@coasys/ad4m 0.12.0-rc1-dev → 0.12.0-rc1-dev.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/jest.config.js +4 -4
  2. package/lib/index.cjs +5999 -6044
  3. package/lib/index.js +5977 -6038
  4. package/lib/src/Ad4mClient.d.ts +16 -9
  5. package/lib/src/Ad4mClient.js +25 -46
  6. package/lib/src/Ad4mClient.test.d.ts +1 -0
  7. package/lib/src/Ad4mClient.test.js +1204 -0
  8. package/lib/src/Literal.d.ts +2 -1
  9. package/lib/src/Literal.js +35 -38
  10. package/lib/src/Literal.test.d.ts +1 -0
  11. package/lib/src/Literal.test.js +41 -0
  12. package/lib/src/SmartLiteral.d.ts +2 -1
  13. package/lib/src/SmartLiteral.js +15 -30
  14. package/lib/src/agent/AgentClient.d.ts +4 -1
  15. package/lib/src/agent/AgentClient.js +99 -79
  16. package/lib/src/ai/AIClient.d.ts +2 -1
  17. package/lib/src/ai/AIClient.js +220 -224
  18. package/lib/src/expression/ExpressionClient.d.ts +1 -1
  19. package/lib/src/expression/ExpressionClient.js +86 -73
  20. package/lib/src/index.d.ts +1 -1
  21. package/lib/src/index.js +1 -1
  22. package/lib/src/language/LanguageClient.d.ts +1 -1
  23. package/lib/src/language/LanguageClient.js +52 -52
  24. package/lib/src/model/Ad4mModel.d.ts +157 -937
  25. package/lib/src/model/Ad4mModel.js +212 -2797
  26. package/lib/src/model/Ad4mModel.test.js +1002 -561
  27. package/lib/src/model/decorators.d.ts +94 -426
  28. package/lib/src/model/decorators.js +333 -741
  29. package/lib/src/model/mutation.d.ts +81 -0
  30. package/lib/src/model/mutation.js +317 -0
  31. package/lib/src/model/parentUtils.d.ts +32 -0
  32. package/lib/src/model/parentUtils.js +64 -0
  33. package/lib/src/model/prolog/generatePrologFacts.d.ts +36 -0
  34. package/lib/src/model/prolog/generatePrologFacts.js +139 -0
  35. package/lib/src/model/prolog/index.d.ts +1 -0
  36. package/lib/src/model/prolog/index.js +1 -0
  37. package/lib/src/model/query/ModelQueryBuilder.d.ts +82 -0
  38. package/lib/src/model/query/ModelQueryBuilder.js +115 -0
  39. package/lib/src/model/query/QueryBuilder.d.ts +101 -0
  40. package/lib/src/model/query/QueryBuilder.js +193 -0
  41. package/lib/src/model/query/SurrealQueryBuilder.d.ts +48 -0
  42. package/lib/src/model/query/SurrealQueryBuilder.js +371 -0
  43. package/lib/src/model/query/fetchInstance.d.ts +24 -0
  44. package/lib/src/model/query/fetchInstance.js +144 -0
  45. package/lib/src/model/query/hydration.d.ts +54 -0
  46. package/lib/src/model/query/hydration.js +214 -0
  47. package/lib/src/model/query/operations.d.ts +59 -0
  48. package/lib/src/model/query/operations.js +384 -0
  49. package/lib/src/model/query/snapshot.d.ts +59 -0
  50. package/lib/src/model/query/snapshot.js +106 -0
  51. package/lib/src/model/query/surrealCompiler.d.ts +42 -0
  52. package/lib/src/model/query/surrealCompiler.js +304 -0
  53. package/lib/src/model/schema/fromJSONSchema.d.ts +67 -0
  54. package/lib/src/model/schema/fromJSONSchema.js +264 -0
  55. package/lib/src/model/schema/metadata.d.ts +15 -0
  56. package/lib/src/model/schema/metadata.js +112 -0
  57. package/lib/src/model/subscription.d.ts +47 -0
  58. package/lib/src/model/subscription.js +231 -0
  59. package/lib/src/model/transaction.d.ts +27 -0
  60. package/lib/src/model/transaction.js +32 -0
  61. package/lib/src/model/types.d.ts +195 -0
  62. package/lib/src/model/types.js +8 -0
  63. package/lib/src/model/util.js +7 -7
  64. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +5 -1
  65. package/lib/src/neighbourhood/NeighbourhoodClient.js +263 -181
  66. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -1
  67. package/lib/src/neighbourhood/NeighbourhoodProxy.js +13 -28
  68. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +1 -5
  69. package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
  70. package/lib/src/perspectives/PerspectiveClient.js +316 -240
  71. package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -92
  72. package/lib/src/perspectives/PerspectiveProxy.js +803 -444
  73. package/lib/src/runtime/RuntimeClient.d.ts +5 -1
  74. package/lib/src/runtime/RuntimeClient.js +412 -238
  75. package/lib/src/shacl/SHACLFlow.test.js +164 -105
  76. package/lib/src/shacl/SHACLShape.d.ts +17 -3
  77. package/lib/src/shacl/SHACLShape.js +127 -90
  78. package/lib/src/shacl/SHACLShape.test.js +244 -176
  79. package/lib/src/utils.d.ts +8 -0
  80. package/lib/src/utils.js +21 -7
  81. package/package.json +8 -13
  82. package/src/Ad4mClient.test.ts +1564 -1315
  83. package/src/Ad4mClient.ts +55 -54
  84. package/src/Literal.test.ts +45 -26
  85. package/src/Literal.ts +82 -66
  86. package/src/SmartLiteral.ts +74 -58
  87. package/src/agent/AgentClient.ts +144 -99
  88. package/src/ai/AIClient.ts +409 -359
  89. package/src/expression/ExpressionClient.ts +142 -96
  90. package/src/index.ts +1 -1
  91. package/src/language/LanguageClient.ts +137 -113
  92. package/src/model/Ad4mModel.test.ts +1128 -647
  93. package/src/model/Ad4mModel.ts +485 -3247
  94. package/src/model/IMPROVEMENTS.md +482 -0
  95. package/src/model/PREDICATE_COLLISION_FIX.md +651 -0
  96. package/src/model/README.md +317 -0
  97. package/src/model/SHACL_MUTATION_DECOUPLING.md +356 -0
  98. package/src/model/SUBSCRIPTION_STRATEGY.md +317 -0
  99. package/src/model/TC39_STAGE_3_DECORATORS.md +609 -0
  100. package/src/model/decorators.ts +689 -1046
  101. package/src/model/mutation.ts +461 -0
  102. package/src/model/parentUtils.ts +91 -0
  103. package/src/model/prolog/generatePrologFacts.ts +176 -0
  104. package/src/model/prolog/index.ts +1 -0
  105. package/src/model/query/ModelQueryBuilder.ts +173 -0
  106. package/src/model/query/fetchInstance.ts +181 -0
  107. package/src/model/query/hydration.ts +273 -0
  108. package/src/model/query/operations.ts +510 -0
  109. package/src/model/query/snapshot.ts +126 -0
  110. package/src/model/query/surrealCompiler.ts +376 -0
  111. package/src/model/schema/fromJSONSchema.ts +411 -0
  112. package/src/model/schema/metadata.ts +148 -0
  113. package/src/model/subscription.ts +307 -0
  114. package/src/model/transaction.ts +60 -0
  115. package/src/model/types.ts +207 -0
  116. package/src/model/util.ts +47 -48
  117. package/src/neighbourhood/NeighbourhoodClient.ts +393 -251
  118. package/src/neighbourhood/NeighbourhoodProxy.test.ts +3 -7
  119. package/src/neighbourhood/NeighbourhoodProxy.ts +58 -40
  120. package/src/perspectives/PerspectiveClient.ts +779 -540
  121. package/src/perspectives/PerspectiveProxy.ts +2860 -2053
  122. package/src/runtime/RuntimeClient.ts +775 -476
  123. package/src/shacl/SHACLFlow.test.ts +196 -129
  124. package/src/shacl/SHACLShape.test.ts +284 -190
  125. package/src/shacl/SHACLShape.ts +225 -172
  126. package/src/utils.ts +31 -17
  127. package/tsconfig.json +9 -10
  128. package/src/model/Subject.ts +0 -159
@@ -0,0 +1,609 @@
1
+ # TC39 Stage 3 Decorator Migration Plan
2
+
3
+ > **Status:** Planning
4
+ > **Created:** 2026-02-28
5
+ > **Estimated effort:** ~7–9 days
6
+
7
+ ---
8
+
9
+ ## Table of Contents
10
+
11
+ 1. [Problem Statement](#problem-statement)
12
+ 2. [Why TC39 Decorators](#why-tc39-decorators)
13
+ 3. [Current Architecture (Legacy Decorators)](#current-architecture-legacy-decorators)
14
+ 4. [Target Architecture (TC39 Decorators)](#target-architecture-tc39-decorators)
15
+ 5. [Implementation Roadmap](#implementation-roadmap)
16
+ - [Phase 1: Upgrade TypeScript](#phase-1-upgrade-typescript)
17
+ - [Phase 2: Add `declare` to Flux Model Fields](#phase-2-add-declare-to-flux-model-fields)
18
+ - [Phase 3: Rewrite Decorators to TC39 Spec](#phase-3-rewrite-decorators-to-tc39-spec)
19
+ - [Phase 4: Update Ad4mModel Constructor](#phase-4-update-ad4mmodel-constructor)
20
+ - [Phase 5: Fix Projection (Remove Hacks)](#phase-5-fix-projection-remove-hacks)
21
+ - [Phase 6: Update All Consumer tsconfigs](#phase-6-update-all-consumer-tsconfigs)
22
+ - [Phase 7: Integration Testing](#phase-7-integration-testing)
23
+ 6. [Effort Estimate](#effort-estimate)
24
+ 7. [What You Get](#what-you-get)
25
+ 8. [Gotchas & Risks](#gotchas--risks)
26
+ 9. [Appendix: Current State Audit](#appendix-current-state-audit)
27
+
28
+ ---
29
+
30
+ ## Problem Statement
31
+
32
+ Ad4m's model system needs to:
33
+
34
+ 1. **Map class fields ↔ link-triple predicates** (`title` ↔ `"test://title"`)
35
+ 2. **Generate SHACL shapes** (W3C standard) from the schema for `ensureSDNASubjectClass`
36
+ 3. **Hydrate instances** from SurrealDB query results
37
+ 4. **Persist via link mutations** (add/remove/set links)
38
+ 5. **Provide instance methods** (`save()`, `addComments()`, `get()`, `delete()`)
39
+ 6. **Support inheritance** (`TestDerivedModel extends TestBaseModel`)
40
+ 7. **Work with Vue/React reactivity** (no `#private` fields)
41
+
42
+ The current system uses **legacy TypeScript experimental decorators** (`experimentalDecorators: true`). These decorators receive `target` = the **class prototype**, and every decorator writes to it:
43
+
44
+ ```ts
45
+ // decorators.ts — current @Property implementation
46
+ Object.defineProperty(target, key, { configurable: true, writable: true });
47
+ ```
48
+
49
+ This creates properties like `TestPost.prototype.body = undefined`, `TestPost.prototype.title = undefined`, etc. on the **prototype**, not the instance.
50
+
51
+ ### Concrete bugs caused by this
52
+
53
+ - **`delete instance.body` doesn't fully work** — removes the own property, but `'body' in instance` still returns `true` because `TestPost.prototype.body` exists. This broke our `properties` field projection feature.
54
+ - **Setter stubs on the prototype** — `target[setTitle] = () => {}` puts empty functions on the prototype that could mask real setter wiring if the constructor fails.
55
+ - **`Object.keys(instance)` includes hydrated data but not prototype-shadow fields** — leading to asymmetric behaviour depending on whether a field was hydrated or not.
56
+
57
+ ---
58
+
59
+ ## Why TC39 Decorators
60
+
61
+ | Aspect | Legacy (`experimentalDecorators`) | TC39 Stage 3 (TS ≥ 5.0) |
62
+ | --------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
63
+ | **Spec status** | Deprecated direction; based on an abandoned proposal | JavaScript standard (Stage 3, shipping in engines) |
64
+ | **`target` parameter** | The **prototype** | N/A — field decorators receive `undefined` + a `context` object |
65
+ | **Per-instance init** | Not available — must write to prototype | `context.addInitializer()` runs code in the constructor |
66
+ | **Metadata sharing** | Manual WeakMaps keyed on constructor | `context.metadata` — TC39-standard shared object per class |
67
+ | **`emitDecoratorMetadata`** | Supported (Reflect.getMetadata) | Not supported — use `context.metadata` instead |
68
+ | **Prototype pollution** | Inherent to the pattern | Impossible — field decorators don't receive the prototype |
69
+
70
+ The public API stays **identical** — `@Property({ through: "test://title" })` looks exactly the same to consumers.
71
+
72
+ ---
73
+
74
+ ## Current Architecture (Legacy Decorators)
75
+
76
+ ### How `@Property` works today
77
+
78
+ ```ts
79
+ // core/src/model/decorators.ts (current)
80
+ export function Property(opts: PropertyOptions) {
81
+ return function <T>(target: T, key: keyof T) {
82
+ // 1. Register metadata in WeakMap keyed on constructor
83
+ const existing = propertyRegistry.get((target as any).constructor) ?? {};
84
+ propertyRegistry.set((target as any).constructor, {
85
+ ...existing,
86
+ [key as string]: { ...existing[key as string], ...opts },
87
+ });
88
+
89
+ // 2. Place setter stub on PROTOTYPE (pollution)
90
+ if (!opts.readOnly) {
91
+ target[`set${capitalize(key as string)}`] = () => {};
92
+ }
93
+
94
+ // 3. Place field descriptor on PROTOTYPE (pollution)
95
+ Object.defineProperty(target, key, { configurable: true, writable: true });
96
+ };
97
+ }
98
+ ```
99
+
100
+ **Steps 2 and 3 write to the prototype**, which is the root cause of all the issues.
101
+
102
+ ### How `@HasMany` / `@HasOne` work today
103
+
104
+ Same pattern — register metadata, place `addX`/`removeX`/`setX` stubs on the prototype, call `Object.defineProperty` on the prototype.
105
+
106
+ ### How `@Model` works today
107
+
108
+ Class decorator. Sets `target.prototype.className`, generates SHACL via `target.generateSHACL = function() { ... }`. This part is fine — class decorators always receive the constructor, not the prototype.
109
+
110
+ ### tsconfig settings
111
+
112
+ | Project | `experimentalDecorators` | `emitDecoratorMetadata` | `target` | `useDefineForClassFields` | TypeScript version |
113
+ | ------------------- | ------------------------ | ----------------------- | -------- | ------------------------------------- | ------------------ |
114
+ | `ad4m/core` | `true` | `true` | `ES2020` | not set (default: `false` for ES2020) | `^4.6.2` |
115
+ | `flux/packages/api` | `true` | not set | `ES6` | not set (default: `false` for ES6) | inherited |
116
+ | `we` playground | `true` | `true` | `ES2022` | **`false`** (explicit) | inherited |
117
+
118
+ ### Field declaration patterns
119
+
120
+ | Project | Pattern | Example | Count |
121
+ | -------------- | ------------------------------------- | --------------------- | --------------------------- |
122
+ | **Flux** | Bare type annotation (no initializer) | `body: string;` | ~60 fields across 22 models |
123
+ | **Flux** | With initializer (arrays) | `views: App[] = [];` | ~20 fields |
124
+ | **We** | Always has initializer | `body: string = "";` | ~30 fields across 10 models |
125
+ | **ad4m tests** | Always has initializer | `title: string = "";` | ~15 fields across 6 models |
126
+
127
+ ---
128
+
129
+ ## Target Architecture (TC39 Decorators)
130
+
131
+ ### Core idea: field decorators only store metadata, class decorator collects and registers
132
+
133
+ ```
134
+ ┌─────────────────────────────────────────────────────────────┐
135
+ │ @Property / @HasMany / @Flag (field decorators) │
136
+ │ → write to context.metadata.__ad4m_properties / _relations │
137
+ │ → NO writes to prototype │
138
+ │ → return initializer function (pass-through or flag value) │
139
+ └──────────────────────┬──────────────────────────────────────┘
140
+ │ context.metadata is shared
141
+ ▼
142
+ ┌─────────────────────────────────────────────────────────────┐
143
+ │ @Model (class decorator) │
144
+ │ → reads context.metadata to get all field/relation info │
145
+ │ → registers in propertyRegistry / relationRegistry WeakMap │
146
+ │ → attaches className, generateSHACL │
147
+ └─────────────────────────────────────────────────────────────┘
148
+ ```
149
+
150
+ ### `@Property` — TC39 version
151
+
152
+ ```ts
153
+ function Property(opts: PropertyOptions) {
154
+ return function (
155
+ _value: undefined, // field decorators receive undefined
156
+ context: ClassFieldDecoratorContext, // TC39 context object
157
+ ) {
158
+ const key = String(context.name);
159
+
160
+ // Store metadata in the shared context.metadata object.
161
+ // All field decorators on the same class share this object.
162
+ const meta = context.metadata as any;
163
+ meta.__ad4m_properties ??= {};
164
+ meta.__ad4m_properties[key] = {
165
+ ...(meta.__ad4m_properties[key] ?? {}),
166
+ ...opts,
167
+ };
168
+
169
+ // Return an initializer function that runs when the field is assigned.
170
+ // For most fields this is a pass-through — the class field initializer
171
+ // (e.g. `body: string = ""`) provides the default value.
172
+ return (initialValue: any) => initialValue;
173
+
174
+ // NO Object.defineProperty on prototype
175
+ // NO setter stubs on prototype
176
+ };
177
+ }
178
+ ```
179
+
180
+ ### `@Flag` — TC39 version
181
+
182
+ ```ts
183
+ function Flag(opts: FlagOptions) {
184
+ return function (_value: undefined, context: ClassFieldDecoratorContext) {
185
+ const key = String(context.name);
186
+
187
+ const meta = context.metadata as any;
188
+ meta.__ad4m_properties ??= {};
189
+ meta.__ad4m_properties[key] = {
190
+ through: opts.through,
191
+ initial: opts.value,
192
+ flag: true,
193
+ readOnly: true,
194
+ required: true,
195
+ };
196
+
197
+ // Return initializer that sets the flag value — regardless of
198
+ // what the class field initializer says, flags always equal opts.value
199
+ return () => opts.value;
200
+ };
201
+ }
202
+ ```
203
+
204
+ ### `@HasMany` — TC39 version
205
+
206
+ ```ts
207
+ function HasMany(
208
+ relatedModelOrOpts: (() => any) | RelationOptions,
209
+ opts?: RelationOptions,
210
+ ) {
211
+ const resolvedOpts =
212
+ typeof relatedModelOrOpts === "function" ? opts! : relatedModelOrOpts;
213
+ const relatedModel =
214
+ typeof relatedModelOrOpts === "function" ? relatedModelOrOpts : undefined;
215
+
216
+ return function (_value: undefined, context: ClassFieldDecoratorContext) {
217
+ const key = String(context.name);
218
+
219
+ const meta = context.metadata as any;
220
+ meta.__ad4m_relations ??= {};
221
+ meta.__ad4m_relations[key] = {
222
+ ...resolvedOpts,
223
+ direction: "forward" as const,
224
+ ...(relatedModel ? { relatedModel } : {}),
225
+ };
226
+
227
+ // Pass through the initializer (typically `= []`)
228
+ return (initialValue: any) => initialValue;
229
+
230
+ // NO addX/removeX/setX stubs on prototype —
231
+ // these are wired in the Ad4mModel constructor already
232
+ };
233
+ }
234
+ ```
235
+
236
+ ### `@HasOne`, `@BelongsToOne`, `@BelongsToMany` — same pattern
237
+
238
+ Each stores its metadata in `context.metadata.__ad4m_relations` with the appropriate `direction` and `maxCount` values. No prototype writes.
239
+
240
+ ### `@Model` — TC39 version
241
+
242
+ ```ts
243
+ function Model(opts: ModelConfig) {
244
+ return function <T extends new (...args: any[]) => any>(
245
+ target: T,
246
+ context: ClassDecoratorContext,
247
+ ) {
248
+ // At this point, ALL field decorators have already run and populated
249
+ // context.metadata with __ad4m_properties and __ad4m_relations.
250
+ const meta = context.metadata as any;
251
+ const properties = meta.__ad4m_properties ?? {};
252
+ const relations = meta.__ad4m_relations ?? {};
253
+
254
+ // Register in WeakMaps (same as today, but populated cleanly)
255
+ propertyRegistry.set(target, properties);
256
+ relationRegistry.set(target, relations);
257
+
258
+ // Attach className (same as today)
259
+ target.prototype.className = opts.name;
260
+ target.className = opts.name;
261
+
262
+ // Attach generateSHACL (same logic as today — reads from registries)
263
+ target.generateSHACL = function () {
264
+ // ... identical SHACL generation code ...
265
+ };
266
+
267
+ return target;
268
+ };
269
+ }
270
+ ```
271
+
272
+ ### Inheritance support
273
+
274
+ TC39 `context.metadata` uses prototype-based inheritance automatically:
275
+
276
+ ```ts
277
+ @Model({ name: "Base" })
278
+ class Base extends Ad4mModel {
279
+ @Property({ through: "base://content" })
280
+ content: string = "";
281
+ }
282
+
283
+ @Model({ name: "Derived" })
284
+ class Derived extends Base {
285
+ @Property({ through: "derived://extra" })
286
+ extra: string = "";
287
+ }
288
+ // Derived[Symbol.metadata].__ad4m_properties inherits Base's via prototype chain
289
+ // getPropertiesMetadata(Derived) returns { content: {...}, extra: {...} }
290
+ ```
291
+
292
+ The existing `getPropertiesMetadata()` / `getRelationsMetadata()` functions that walk the constructor prototype chain continue to work unchanged.
293
+
294
+ ---
295
+
296
+ ## Implementation Roadmap
297
+
298
+ ### Phase 1: Upgrade TypeScript
299
+
300
+ **Files:** root `package.json`, `core/package.json`, all `tsconfig.json` files
301
+ **Effort:** 1–2 days
302
+ **Risk:** High (touches all projects)
303
+
304
+ 1. Bump TypeScript to `^5.4` (or latest stable 5.x) in:
305
+ - `ad4m/core/package.json` (currently `^4.6.2`)
306
+ - Any other packages that pin their own TS version
307
+ 2. In every `tsconfig.json`:
308
+ - Remove `"experimentalDecorators": true`
309
+ - Remove `"emitDecoratorMetadata": true`
310
+ - Set `"target": "ES2022"` or higher
311
+ - Set `"useDefineForClassFields": true` (explicit, even though it's the default for ES2022+)
312
+ 3. Fix any type errors from the TS version bump (likely minimal)
313
+ 4. Validate builds pass: `pnpm build` in ad4m root, `yarn build` in flux
314
+
315
+ > **Note:** Do this on a dedicated branch. The tsconfig changes alone will break decorators until Phase 3 is complete, so Phases 1–3 should land together.
316
+
317
+ ### Phase 2: Add `declare` to Flux Model Fields
318
+
319
+ **Files:** All ~22 model files in `flux/packages/api/src/`
320
+ **Effort:** 1 day
321
+ **Risk:** Low (mechanical transformation)
322
+
323
+ With `useDefineForClassFields: true`, a bare field like:
324
+
325
+ ```ts
326
+ @Property({ through: BODY })
327
+ body: string;
328
+ ```
329
+
330
+ would emit `this.body = undefined` in the constructor, clobbering whatever the hydration pipeline sets. The fix:
331
+
332
+ ```ts
333
+ @Property({ through: BODY })
334
+ declare body: string;
335
+ ```
336
+
337
+ `declare` tells TypeScript "this field exists for type-checking but don't emit any runtime code." The decorator and hydration pipeline handle the actual value.
338
+
339
+ **Rules:**
340
+
341
+ | Field pattern | Action needed |
342
+ | --------------------------------------------- | ------------------------------------------------------------------------- |
343
+ | `body: string;` (no initializer) | Add `declare` → `declare body: string;` |
344
+ | `body: string = "";` (with initializer) | No change — initializer runs in constructor, creates own property |
345
+ | `views: App[] = [];` (array with initializer) | No change |
346
+ | `@Flag type: string;` | Add `declare` → `declare type: string;` (Flag initializer sets the value) |
347
+
348
+ **We models** already use initializers on all fields, so they need **no changes** for this phase.
349
+
350
+ **Ad4m test models** already use initializers on all fields, so they need **no changes** for this phase.
351
+
352
+ ### Phase 3: Rewrite Decorators to TC39 Spec
353
+
354
+ **Files:** `core/src/model/decorators.ts`
355
+ **Effort:** 2–3 days
356
+ **Risk:** Medium (core logic unchanged, just new signatures)
357
+
358
+ This is the core of the migration. Each decorator changes its function signature but keeps the same metadata-registration logic. See the [Target Architecture](#target-architecture-tc39-decorators) section above for the full new implementations.
359
+
360
+ **Summary of changes per decorator:**
361
+
362
+ | Decorator | What changes | What stays the same |
363
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
364
+ | `@Property` | Signature → `(undefined, ClassFieldDecoratorContext)`. No `Object.defineProperty`. No setter stubs. Stores in `context.metadata`. | PropertyOptions interface. Metadata shape. |
365
+ | `@Flag` | Same as Property. Returns `() => opts.value` as initializer. | FlagOptions interface. |
366
+ | `@HasMany` | Signature → `(undefined, ClassFieldDecoratorContext)`. No `Object.defineProperty`. No add/remove/set stubs. Stores in `context.metadata.__ad4m_relations`. | RelationOptions interface. relatedModel factory. |
367
+ | `@HasOne` | Same as HasMany but adds `maxCount: 1`. | |
368
+ | `@BelongsToOne` | Same pattern, `direction: "reverse"`, `maxCount: 1`. | |
369
+ | `@BelongsToMany` | Same pattern, `direction: "reverse"`. | |
370
+ | `@Model` | Signature → `(target, ClassDecoratorContext)`. Reads `context.metadata` instead of WeakMaps directly. Registers in WeakMaps. SHACL generation unchanged. | ModelConfig interface. All SHACL logic. |
371
+
372
+ **What's deleted:**
373
+
374
+ - Every `Object.defineProperty(target, key, { configurable: true, writable: true })` line
375
+ - Every `target[setterName] = () => {}` line (setter stubs on prototype)
376
+ - Every `target[adderName] = () => {}` / `target[removerName] = () => {}` line
377
+
378
+ **`Symbol.metadata` polyfill** — TC39 `context.metadata` requires `Symbol.metadata` to exist. TypeScript 5.2+ emits the polyfill automatically. For older environments, add at the top of `decorators.ts`:
379
+
380
+ ```ts
381
+ Symbol.metadata ??= Symbol("Symbol.metadata");
382
+ ```
383
+
384
+ ### Phase 4: Update Ad4mModel Constructor
385
+
386
+ **File:** `core/src/model/Ad4mModel.ts`
387
+ **Effort:** 0.5 day
388
+ **Risk:** Low
389
+
390
+ The constructor already wires `addX`/`removeX`/`setX` methods from the relation registry:
391
+
392
+ ```ts
393
+ constructor(perspective: PerspectiveProxy, id?: string) {
394
+ this._id = id ? id : Literal.from(makeRandomId(24)).toUrl();
395
+ this._perspective = perspective;
396
+
397
+ // Wire up real relation mutator methods (already exists, no change needed)
398
+ const relations = getRelationsMetadata(proto.constructor);
399
+ for (const key of Object.keys(relations)) {
400
+ if (relations[key].direction === "reverse") continue;
401
+ const cap = capitalize(key);
402
+ this[`add${cap}`] = (value, batchId?) => mutation.setRelationAdder(...);
403
+ this[`remove${cap}`] = (value, batchId?) => mutation.setRelationRemover(...);
404
+ this[`set${cap}`] = (value, batchId?) => mutation.setRelationSetter(...);
405
+ }
406
+ }
407
+ ```
408
+
409
+ This **doesn't need to change** — it reads from `relationRegistry` which is populated by `@Model` in Phase 3. The setter stubs that were previously on the prototype are no longer needed because the constructor was already overwriting them with real implementations.
410
+
411
+ **Optional enhancement:** add a `getModelMetadata()` path that can read from `Symbol.metadata` on the constructor as a fallback:
412
+
413
+ ```ts
414
+ static getModelMetadata(): ModelMetadata {
415
+ // Primary: WeakMap (populated by @Model)
416
+ const fromRegistry = _getModelMetadata(this);
417
+ if (fromRegistry) return fromRegistry;
418
+
419
+ // Fallback: Symbol.metadata (TC39 standard)
420
+ const meta = (this as any)[Symbol.metadata];
421
+ if (meta) {
422
+ return {
423
+ className: this.prototype.className,
424
+ properties: meta.__ad4m_properties ?? {},
425
+ relations: meta.__ad4m_relations ?? {},
426
+ };
427
+ }
428
+
429
+ throw new Error("Model metadata not found — is @Model applied?");
430
+ }
431
+ ```
432
+
433
+ ### Phase 5: Fix Projection (Remove Hacks)
434
+
435
+ **Files:**
436
+
437
+ - `core/src/model/query/operations.ts`
438
+ - `tests/js/tests/model/model-query.test.ts`
439
+
440
+ **Effort:** 0.5 day
441
+ **Risk:** Low
442
+
443
+ With no prototype-shadow properties, `delete instance.body` will make `'body' in instance` return `false` correctly.
444
+
445
+ **Revert test assertions** from:
446
+
447
+ ```ts
448
+ expect(r).to.not.have.own.property("body"); // current hack
449
+ ```
450
+
451
+ back to:
452
+
453
+ ```ts
454
+ expect(r).to.not.have.property("body"); // clean assertion
455
+ ```
456
+
457
+ The projection code in `operations.ts` (`delete instance[key]`) works correctly with zero workarounds.
458
+
459
+ ### Phase 6: Update All Consumer tsconfigs
460
+
461
+ **Files:** Every `tsconfig.json` across `ad4m`, `flux`, `we`
462
+ **Effort:** 0.5 day
463
+ **Risk:** Low
464
+
465
+ Ensure all projects have:
466
+
467
+ ```jsonc
468
+ {
469
+ "compilerOptions": {
470
+ // Remove these:
471
+ // "experimentalDecorators": true,
472
+ // "emitDecoratorMetadata": true,
473
+
474
+ // Add/ensure these:
475
+ "target": "ES2022",
476
+ "useDefineForClassFields": true,
477
+ },
478
+ }
479
+ ```
480
+
481
+ **Affected tsconfig counts:**
482
+
483
+ - Flux: ~20 tsconfig files with `experimentalDecorators: true`
484
+ - We: ~4 tsconfig files
485
+ - Ad4m: core + test-runner configs
486
+
487
+ ### Phase 7: Integration Testing
488
+
489
+ **Effort:** 1–2 days
490
+ **Risk:** Medium
491
+
492
+ 1. **Ad4m model tests:** `cd tests/js && pnpm test-model` — all query, transaction, and dirty-tracking tests
493
+ 2. **SHACL validation:** Compare generated Turtle output before/after migration — must be byte-identical
494
+ 3. **Flux build + dev:** `cd flux && yarn build && yarn dev` — ensure all 22 models hydrate correctly
495
+ 4. **We playground:** Build and run the ad4m-model-testing playground
496
+ 5. **Flux channel pinning:** The original bug that triggered this whole investigation — verify pinning a channel no longer duplicates conversations
497
+
498
+ ---
499
+
500
+ ## Effort Estimate
501
+
502
+ | Phase | Effort | Risk |
503
+ | -------------------------------- | ------------- | --------------------------------------------- |
504
+ | 1. Upgrade TypeScript | 1–2 days | High — touches all projects |
505
+ | 2. Add `declare` to Flux models | 1 day | Low — mechanical |
506
+ | 3. Rewrite decorators | 2–3 days | Medium — core logic unchanged, new signatures |
507
+ | 4. Update Ad4mModel constructor | 0.5 day | Low |
508
+ | 5. Fix projection (remove hacks) | 0.5 day | Low |
509
+ | 6. Update tsconfigs | 0.5 day | Low |
510
+ | 7. Integration testing | 1–2 days | Medium |
511
+ | **Total** | **~7–9 days** | |
512
+
513
+ > **Phases 1–3 must land together** on a single branch. The tsconfig changes break legacy decorators, and the new decorators require the tsconfig changes.
514
+
515
+ ---
516
+
517
+ ## What You Get
518
+
519
+ - **Zero prototype pollution** — decorators never write to the prototype
520
+ - **`delete instance.field` works correctly** — no phantom properties from prototype chain
521
+ - **Future-proof** — using the JavaScript standard, not a deprecated TS experiment
522
+ - **Cleaner separation of concerns** — field decorators only store metadata, class decorator collects and registers
523
+ - **`context.metadata`** — the TC39-standard way to share data between decorators, replacing manual WeakMap coordination
524
+ - **Same public API** — `@Property({ through: "..." })`, `@HasMany(...)`, etc. look identical to consumers
525
+ - **Same SHACL output** — the generated shapes are unchanged
526
+ - **Dirty tracking just works** — no prototype shadows to confuse snapshot comparisons
527
+ - **Projection just works** — `delete` fully removes properties, no `.own.property` hacks needed
528
+
529
+ ---
530
+
531
+ ## Gotchas & Risks
532
+
533
+ ### 1. `emitDecoratorMetadata` is not supported by TC39 decorators
534
+
535
+ If anything relies on `Reflect.getMetadata()` at runtime, it needs to be replaced with `context.metadata`. The Ad4m codebase **does not appear to use** `Reflect.getMetadata()`, so this should be fine. Verify with:
536
+
537
+ ```bash
538
+ grep -r "Reflect.getMetadata\|Reflect.defineMetadata\|reflect-metadata" --include="*.ts" core/src/
539
+ ```
540
+
541
+ ### 2. Decorator execution order changes slightly
542
+
543
+ In legacy decorators, field decorators run when the class is defined (at class parse time). In TC39, field decorator **initializers** run in the constructor. However, the metadata-via-`context.metadata` approach avoids timing issues because:
544
+
545
+ - Field decorators populate `context.metadata` at class definition time (the decorator function itself runs at definition time — only the _initializer_ it returns runs per-instance)
546
+ - The `@Model` class decorator runs at class definition time and reads the already-populated `context.metadata`
547
+
548
+ ### 3. `Symbol.metadata` polyfill
549
+
550
+ TC39 `context.metadata` requires `Symbol.metadata` to exist. TypeScript 5.2+ emits the polyfill automatically. For older environments or bundlers that strip it, add at the top of `decorators.ts`:
551
+
552
+ ```ts
553
+ Symbol.metadata ??= Symbol("Symbol.metadata");
554
+ ```
555
+
556
+ ### 4. Flux models without initializers need `declare`
557
+
558
+ With `useDefineForClassFields: true`, a bare `body: string;` emits `this.body = undefined` in the constructor. This would clobber hydrated values. The fix is `declare body: string;`.
559
+
560
+ **Enforcement:** Add an ESLint rule or a custom lint check that flags model fields (decorated with `@Property`, `@HasMany`, etc.) that lack either `declare` or an initializer.
561
+
562
+ ### 5. Third-party decorator libraries
563
+
564
+ Check if any dependencies use `experimentalDecorators` in their published types. Most libraries ship plain `.d.ts` files that don't depend on decorator mode, but verify.
565
+
566
+ ### 6. Vue reactivity
567
+
568
+ Vue 3's reactivity system uses Proxy-based tracking. `declare` fields that are later set by hydration will still be reactive — Vue tracks property access/mutation on the proxy, regardless of whether the property was declared with `declare` or an initializer. The `#private` concern (which breaks Vue proxies) is unrelated and already avoided in Ad4mModel.
569
+
570
+ ---
571
+
572
+ ## Appendix: Current State Audit
573
+
574
+ ### Model count across projects
575
+
576
+ | Project | Model classes | Fields without initializer | Uses `declare` |
577
+ | ---------- | ------------- | -------------------------------------------- | -------------- |
578
+ | Flux | 22 | ~60 fields (all `@Property`/`@Flag` scalars) | No |
579
+ | We | 10 | 0 (all have initializers) | No |
580
+ | Ad4m tests | 6 | 0 (all have initializers) | No |
581
+
582
+ ### Prototype properties created by current decorators
583
+
584
+ For a model like `TestPost` with `@Property title`, `@Property body`, `@Property viewCount`, `@HasMany tags`, `@HasMany comments`, `@HasOne pinnedComment`:
585
+
586
+ ```
587
+ TestPost.prototype own keys:
588
+ constructor, type, setTitle, title, setBody, body,
589
+ setViewCount, viewCount, addTags, removeTags, setTags, tags,
590
+ addComments, removeComments, setComments, comments,
591
+ addPinnedComment, removePinnedComment, setPinnedComment, pinnedComment, className
592
+ ```
593
+
594
+ Every `@Property` creates 2 prototype entries (field + setter stub).
595
+ Every `@HasMany`/`@HasOne` creates 4 prototype entries (field + add + remove + set stubs).
596
+
597
+ **After TC39 migration:** `TestPost.prototype` will only have `constructor` and `className`. Everything else is either an own property (from class field initializers) or wired in the `Ad4mModel` constructor (mutator methods).
598
+
599
+ ### Files to modify
600
+
601
+ | File | Phase | Change |
602
+ | ----------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------ |
603
+ | `ad4m/core/package.json` | 1 | Bump `typescript` to `^5.4` |
604
+ | All `tsconfig.json` (~24 files) | 1, 6 | Remove `experimentalDecorators`/`emitDecoratorMetadata`, set `target: ES2022`, add `useDefineForClassFields: true` |
605
+ | `flux/packages/api/src/**/*.ts` (~22 files) | 2 | Add `declare` to ~60 bare-typed fields |
606
+ | `ad4m/core/src/model/decorators.ts` | 3 | Full decorator rewrite |
607
+ | `ad4m/core/src/model/Ad4mModel.ts` | 4 | Optional: add `Symbol.metadata` fallback in `getModelMetadata()` |
608
+ | `ad4m/core/src/model/query/operations.ts` | 5 | No code change needed — `delete` just works now |
609
+ | `ad4m/tests/js/tests/model/model-query.test.ts` | 5 | Revert `.own.property` → `.have.property` |