fix(docs): refresh project guidance for TC39 decorators, build configuration, and dependency compatibility

readme.hints.md

@@ -1,113 +1,29 @@
 # Project Memory - Smartdata
 
-## TC39 Decorator Migration (v6.0.0) - ✅ COMPLETED
-
-### Final Status: All Tests Passing (157/157)
-
-Migration successfully completed on 2025-11-17.
-
-### What Changed:
-
-- ✅ Removed `experimentalDecorators` from tsconfig.json
-- ✅ Refactored all 7 decorators to TC39 Stage 3 syntax
-  - 5 property decorators: @globalSvDb, @svDb, @unI, @index, @searchable
-  - 2 class decorators: @Collection, @managed
-- ✅ Implemented context.metadata pattern for shared decorator state
-- ✅ All tests passing across Node.js and Deno runtimes
-
-### Critical Discovery: TC39 Metadata Access Pattern
-
-**THE KEY INSIGHT**: In TC39 decorators, metadata is NOT accessed via `constructor[Symbol.metadata]`. Instead:
+## TC39 Decorator Pattern
 
 - **Field decorators**: Write to `context.metadata`
-- **Class decorators**: Read from `context.metadata` (same shared object!)
-- The `context.metadata` object is shared between all decorators on the same class
-- Attempting to write to `constructor[Symbol.metadata]` throws: "Cannot assign to read only property"
+- **Class decorators**: Read from `context.metadata` (same shared object)
+- `Symbol.metadata` on constructors is read-only (managed by runtime)
+- Field decorators run before class decorators (guaranteed order)
+- `declare` keyword for instance properties accessed via prototype getters (avoids ES2022 shadowing)
 
-### Implementation Pattern:
+### Runtime Compatibility
 
-```typescript
-// Field decorator - stores metadata
-export function svDb() {
-  return (value: undefined, context: ClassFieldDecoratorContext) => {
-    const metadata = context.metadata as ISmartdataDecoratorMetadata;
-    if (!metadata.saveableProperties) {
-      metadata.saveableProperties = [];
-    }
-    metadata.saveableProperties.push(String(context.name));
-  };
-}
+- ✅ Node.js v20+ / v25+: Full TC39 support
+- ✅ Deno v2.x: Full TC39 support
+- ❌ Bun: No TC39 support (uses legacy decorators only)
 
-// Class decorator - reads metadata and initializes prototype
-export function Collection(dbArg: SmartdataDb) {
-  return function(value: Function, context: ClassDecoratorContext) => {
-    const metadata = context.metadata as ISmartdataDecoratorMetadata;
-    if (metadata?.saveableProperties) {
-      decoratedClass.prototype.saveableProperties = [...metadata.saveableProperties];
-    }
-    return decoratedClass;
-  };
-}
-```
+## Build Configuration (v7.1.0+)
 
-### Runtime Compatibility:
+- **Build tool**: `@git.zone/tsbuild` v4 with `tsbuild tsfolders`
+- **tsconfig.json**: Includes `"types": ["node"]` since tsbuild v4 defaults to DOM+ESNext lib only
+- **Strict mode**: tsbuild v4 enables strict checks; properties use `!` definite assignment or `declare`
+- **Test imports**: Use `@git.zone/tstest/tapbundle` (NOT `@push.rocks/tapbundle`)
+- **Config file**: `.smartconfig.json` (renamed from `npmextra.json`)
 
-- ✅ **Node.js v23.8.0**: Full TC39 support
-- ✅ **Deno v2.5.4**: Full TC39 support
-- ❌ **Bun v1.3.0**: No TC39 support (uses legacy decorators only)
-  - Removed "+bun" from test filenames to skip Bun tests
+## Dependencies (v7.1.0+)
 
-### Key Technical Notes:
-
-1. **Metadata Initialization Timing**: Class decorators run AFTER field decorators, allowing them to read accumulated metadata and initialize prototypes before any instances are created
-2. **Prototype vs Instance Properties**: Properties set on prototype are accessible via `this.propertyName` in instances
-3. **TypeScript Lib Support**: TypeScript 5.9.3 includes built-in decorator types (no custom lib configuration needed)
-4. **Interface Naming**: Used `ISmartdataDecoratorMetadata` extending `DecoratorMetadataObject` for type safety
-
-### Files Modified:
-
-- ts/classes.doc.ts (property decorators + metadata interface)
-- ts/classes.collection.ts (class decorators + prototype initialization)
-- tsconfig.json (removed experimentalDecorators flag)
-- test/\*.ts (renamed files to remove "+bun" suffix)
-
-### Test Results:
-
-All 157 tests passing across 10 test files:
-
-- test.cursor.ts: 7/7
-- test.deno.ts: 11/11 (queries working correctly!)
-- test.search.advanced.ts: 41/41
-- test.typescript.ts: 4/4
-- test.watch.ts: 5/5
-- And 5 more test files
-
-### Migration Learnings for Future Reference:
-
-1. `context.metadata` is the ONLY way to share state between decorators
-2. Class decorators must initialize prototypes from metadata immediately
-3. `Symbol.metadata` on constructors is read-only (managed by runtime)
-4. Field decorators run before class decorators (guaranteed order)
-5. TypeScript 5.2+ has built-in TC39 decorator support
-
-## ES2022 Class Fields & Prototype Getters - Fixed in v7.0.15
-
-### Issue
-
-ES2022 class fields (`useDefineForClassFields: true`) create own properties during construction that shadow prototype getters defined by decorators.
-
-### Solution
-
-Use `declare` keyword for instance properties that are accessed via prototype getters:
-
-```typescript
-// In SmartDataDbDoc (ts/classes.doc.ts):
-declare public collection: SmartdataCollection<any>;  // Type-only, no JS emitted
-declare public manager: TManager;  // Type-only, no JS emitted
-```
-
-### Key Insight
-
-- `declare` tells TypeScript this is a type-only declaration
-- No JavaScript code is emitted for `declare` properties
-- Prototype getters defined by `@Collection` and `@managed` decorators are no longer shadowed
+- `@push.rocks/taskbuffer` v8: distributedCoordination API at `taskbuffer.distributedCoordination.*`
+- `@push.rocks/smartmongo` v5: API compatible (`createAndStart`, `getMongoDescriptor`, `stop`, `stopAndDumpToDir`)
+- `mongodb` v7.1: ChangeStream requires `Document` constraint, use `any` for generic watcher