@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,482 @@
1
+ # Ad4mModel — Improvement Backlog
2
+
3
+ Identified gaps and improvement areas for future PRs.
4
+
5
+ ---
6
+
7
+ ## 1. Dirty Tracking (Unit of Work)
8
+
9
+ **Problem:** Every `save()` writes all properties unconditionally. If a model has 20 properties and only one changes, all 20 setter actions are executed, creating unnecessary link churn and network noise.
10
+
11
+ **Solution:** Maintain a `#dirtyFields: Set<string>` on each instance. Intercept property assignments (via `Proxy` or setter generation in `Property()`) to mark fields dirty. `save()` only writes dirty fields; after commit the set is cleared.
12
+
13
+ **Prior art:** TypeORM Unit of Work, MikroORM identity map.
14
+
15
+ ---
16
+
17
+ ## 2. SurrealDB-Side Range Filter Push-Down
18
+
19
+ **Problem:** Comparison operators (`gt`, `lt`, `gte`, `lte`, `between`, `contains`) on scalar properties fall through to post-query JavaScript filtering. Because scalar values are stored as `literal://` URIs, SurrealDB cannot index them for range comparisons without `fn::parse_literal()` unwrapping. This means `findAll(p, { where: { rating: { gt: 4 } } })` fetches **all** instances and filters in JS — a full table scan at scale.
20
+
21
+ **Options:**
22
+
23
+ - Store numeric/boolean values in a SurrealDB-native way (separate `value` field alongside the `literal://` URI) so the DB can index them directly.
24
+ - Define SurrealDB computed fields that cache the unwrapped scalar value, then filter against the computed field.
25
+ - Use `fn::parse_literal(out.uri)` inside the graph traversal WHERE clause directly (requires SurrealDB to evaluate the function per-link, no index — but still better than JS filtering).
26
+
27
+ ---
28
+
29
+ ## 3. N+1 Prevention for Typed Relation Hydration
30
+
31
+ **Problem:** When `relatedModel` is set on a `@HasMany`, hydrating relations calls `_findAllInternal` once per parent instance. 10 posts × 5 comments each = 10 separate `findAll()` queries. No batching exists.
32
+
33
+ **Solution:** In `hydrateInstanceFromLinks` (or a post-hydration pass in `operations.ts`), collect all relation IDs across the entire result set, then run a single batched `findAll({ where: { base: [...ids] } })` for each related model type. Equivalent to a DataLoader / SQL `IN (...)` pattern.
34
+
35
+ ---
36
+
37
+ ## 4. Runtime Validation
38
+
39
+ **Problem:** There is no validation layer. Setting `recipe.rating = "not a number"` silently persists a type-incorrect value. Errors surface only later (if at all) during hydration.
40
+
41
+ **Solution:** Add an optional `validate` option to `@Property` accepting a predicate function or a class-validator-style decorator. Add a `validate()` method to `Ad4mModel` that checks all properties before `save()`. Optionally throw by default or expose errors as a return value.
42
+
43
+ ```typescript
44
+ @Property({ through: "recipe://rating", validate: (v) => typeof v === "number" && v >= 0 })
45
+ rating: number = 0;
46
+ ```
47
+
48
+ ---
49
+
50
+ ## 5. TypeScript Type Inference for `fromJSONSchema`
51
+
52
+ **Problem:** `fromJSONSchema` returns `typeof Ad4mModel` — TypeScript has no knowledge of the generated class's property types. Autocomplete and type-checking are completely lost for dynamically generated models.
53
+
54
+ **Options:**
55
+
56
+ - A type-level schema builder (fluent API returning typed class) that preserves inference without codegen:
57
+ ```typescript
58
+ const Recipe = Ad4mModel.define({
59
+ name: field<string>({ through: "recipe://name" }),
60
+ rating: field<number>({ through: "recipe://rating" }),
61
+ });
62
+ // Recipe is typed: { name: string; rating: number }
63
+ ```
64
+ - Code generation from JSON Schema (Prisma-style): a CLI command that produces a `.ts` file with a properly typed class from a `.json` schema file.
65
+
66
+ ---
67
+
68
+ ## 6. Robust Create-vs-Update Detection
69
+
70
+ **Problem:** `#savedOnce` tracks whether `save()` was called on the current JS instance. Constructing a model wrapper around a known existing ID (`new Recipe(perspective, existingId)`) starts with `#savedOnce = false`, so the first `save()` runs the create path (calling `createSubject`), which may conflict with the already-existing subject.
71
+
72
+ **Solution:** Before the first `save()` on an instance constructed with an explicit `id`, check the perspective for the subject's actual existence (e.g. `isSubjectInstance`). Cache the result so subsequent saves don't pay the round-trip cost.
73
+
74
+ ---
75
+
76
+ ## 7. Stage 3 Decorator Migration
77
+
78
+ **Problem:** The decorator system uses TypeScript's legacy `experimentalDecorators` (Stage 2) format. TypeScript 5.x introduced Stage 3 decorators with different metadata semantics (`context` object instead of `target`/`key`). The current code will need migration when Stage 3 becomes the ecosystem default.
79
+
80
+ **Action:** Track TC39 Stage 3 stabilisation. When `reflect-metadata` is no longer required by major libraries, plan a migration. The `WeakMap`-keyed registry (`propertyRegistry`, `relationRegistry`) already decouples metadata storage from the decorator protocol, so migration should be largely mechanical — change decorator signatures, keep the registry logic intact.
81
+
82
+ ---
83
+
84
+ ## 8. `getter` Option — N+1 Footgun
85
+
86
+ **Problem:** `@Property({ getter: "..." })` and `@HasMany({ getter: "..." })` allow arbitrary SurrealQL expressions to be evaluated per-instance after the main link fetch. This fires one additional `querySurrealDB` call _per instance_ in `evaluateCustomGetters()` — a guaranteed N+1 on every `findAll`.
87
+
88
+ **Distinction from `transform`:** `transform` operates on a value already resolved from a link triple (sync, no extra query). `getter` is for properties with **no backing link triple** — values computed entirely from other nodes' data (e.g. `array::len(string::split(...))` aggregations). It covers ground `transform` cannot, so it cannot simply be removed.
89
+
90
+ **Additional limitations:**
91
+
92
+ - `getter` properties are invisible to `where` clauses (skipped in `hydrateInstanceFromLinks`) — `findAll(p, { where: { wordCount: { gt: 100 } } })` silently ignores the filter.
93
+ - Not subscribed correctly — every subscription re-query re-fires all getter calls.
94
+ - Not represented in the SHACL shape — the Rust executor has no knowledge of it.
95
+
96
+ **Proper fix:** Emit getter expressions as SurrealDB computed fields in the SHACL shape (see item #2), so they are evaluated server-side inside the bulk query rather than in a separate per-instance round-trip. Until that exists, `getter` is a necessary escape hatch but should be used only for single-instance `.find()` calls, never in `findAll`.
97
+
98
+ **Action:** Add a dev-time `console.warn` when `getter` is present without `readOnly: true`, reinforcing that it is not a writable/filterable property. Document the N+1 caveat clearly.
99
+
100
+ ---
101
+
102
+ ## 9. Abort / Rollback for Transactions
103
+
104
+ **Problem:** `runTransaction` catches errors and logs a debug message, but there is no explicit `abortBatch()` on `PerspectiveProxy`. The uncommitted batch is silently discarded by the runtime GC. This is invisible to the caller and relies on runtime-level cleanup.
105
+
106
+ **Solution:** If `PerspectiveProxy` exposes an `abortBatch(id)` call (or can be extended to), call it explicitly in the `catch` block of `runTransaction` for predictable, immediate cleanup rather than relying on GC timing.
107
+
108
+ ---
109
+
110
+ ## 10. tests/js Integration Test Migration
111
+
112
+ **Background:** The `ad4m/tests/js` Mocha suite is the correct long-term home for all `Ad4mModel` integration tests. The target file is `tests/js/tests/model-decorator-api.test.ts`. Currently scenario 08 (14 tests) lives in the `we` playground. The `tests/js` suite imports deprecated symbols and needs a cleanup pass before new tests can land cleanly.
113
+
114
+ **Action:**
115
+
116
+ 1. Fix deprecated imports in `prolog-and-literals.test.ts` and `multi-user-simple.test.ts`
117
+ 2. Establish consistent port allocation and setup pattern across the suite
118
+ 3. Port scenario 08 models + all current tests into `model-decorator-api.test.ts`
119
+ 4. Add subscription lifecycle tests (Phase 3d coverage at executor level)
120
+ 5. Write remaining scenarios (01–07, 09–10) directly in `tests/js`
121
+
122
+ **Priority:** Post-merge. Blocking a dedicated follow-up PR.
123
+
124
+ ---
125
+
126
+ ## 11. CRDT Ordering (Phase 5)
127
+
128
+ **Background:** Concurrent link writes from multiple agents can produce non-deterministic ordering — last-writer-wins SurrealDB timestamp semantics may not match causal intent in a distributed graph.
129
+
130
+ **Goals:**
131
+
132
+ - Make P2P-safe ordering the default, not an afterthought
133
+ - Eliminate boilerplate across all future list-based plugins
134
+ - Provide clear migration path as algorithms improve
135
+ - Enable A/B testing of different strategies
136
+
137
+ ---
138
+
139
+ ### Developer-Facing API
140
+
141
+ ```typescript
142
+ @HasMany(() => Task, {
143
+ through: 'ad4m://has_child',
144
+ ordering: {
145
+ strategy: 'linkedList', // 'linkedList' | 'fractionalIndex' | 'timestamp' | 'manual'
146
+ sortBy: 'taskName', // Fallback for ties (optional)
147
+ }
148
+ })
149
+ orderedTasks: Task[] = [];
150
+ ```
151
+
152
+ Developers use normal array operations — the framework generates CRDT links:
153
+
154
+ ```typescript
155
+ column.orderedTasks.push(newTask); // Append
156
+ column.orderedTasks.splice(2, 0, task); // Insert at index 2
157
+ column.orderedTasks.splice(1, 1); // Remove at index 1
158
+ await column.update(); // Framework generates CRDT links
159
+ ```
160
+
161
+ ---
162
+
163
+ ### Architecture
164
+
165
+ **Layer 1 — Model Decorator (API Surface)**
166
+
167
+ ```typescript
168
+ interface OrderingConfig {
169
+ strategy: "linkedList" | "fractionalIndex" | "timestamp" | "manual";
170
+ sortBy?: string; // Property name for tiebreaker
171
+ conflictResolution?: "lww" | "merge"; // Last-write-wins or merge
172
+ }
173
+ ```
174
+
175
+ **Layer 2 — Ordering Strategy Interface**
176
+
177
+ ```typescript
178
+ interface OrderingStrategy {
179
+ reconstruct(items: Ad4mModel[], links: Link[]): Ad4mModel[];
180
+ generateLinks(
181
+ items: Ad4mModel[],
182
+ operation: Operation,
183
+ context: OperationContext,
184
+ ): Link[];
185
+ garbageCollect?(links: Link[], cutoffDate: Date): Link[];
186
+ }
187
+
188
+ interface Operation {
189
+ type: "insert" | "delete" | "move" | "reorder";
190
+ index: number;
191
+ item?: Ad4mModel;
192
+ targetIndex?: number; // For moves
193
+ }
194
+
195
+ interface OperationContext {
196
+ agentDID: string;
197
+ timestamp: number;
198
+ collectionId: string;
199
+ }
200
+ ```
201
+
202
+ **Layer 3 — Concrete Strategies**
203
+
204
+ LinkedList Strategy (RGA-based) uses predicates `ad4m://ordered_after`, `ad4m://position_id`, `ad4m://position_deleted`. Reconstructs by building an `afterMap` from links, sorting same-position items by `${timestamp}_${agentDID}` positionId, then traversing the linked list from `null` head.
205
+
206
+ Fractional Index Strategy uses predicates `ad4m://fractional_position`, `ad4m://position_id`. Reconstructs by sorting items lexicographically by their stored position string with positionId as tiebreaker. Generates new positions as the midpoint between neighbours.
207
+
208
+ Strategy Factory:
209
+
210
+ ```typescript
211
+ class OrderingStrategyFactory {
212
+ static create(config?: OrderingConfig): OrderingStrategy {
213
+ switch (config?.strategy) {
214
+ case "linkedList":
215
+ return new LinkedListStrategy();
216
+ case "fractionalIndex":
217
+ return new FractionalIndexStrategy();
218
+ case "timestamp":
219
+ return new TimestampStrategy();
220
+ default:
221
+ return new ManualStrategy(); // current behaviour
222
+ }
223
+ }
224
+ }
225
+ ```
226
+
227
+ Custom strategies are supported: `ordering: { strategy: new MyCustomStrategy() }`.
228
+
229
+ **Layer 4 — Array Proxy**
230
+
231
+ `wrapCollectionWithOrdering()` on `Ad4mModel` returns a `Proxy` that intercepts `push`, `unshift`, `splice` and records a pending `Operation`. On `update()`, pending operations are passed to the strategy's `generateLinks()` and the resulting links are batched into the perspective write.
232
+
233
+ ---
234
+
235
+ ### Migration Strategy
236
+
237
+ Old string-array properties still work. Migration helper:
238
+
239
+ ```typescript
240
+ async migrateToOrderedCollection() {
241
+ const oldIds = JSON.parse(this.orderedTaskIds);
242
+ const batchId = await this.perspective.createBatch();
243
+ let previousId = null;
244
+ for (const taskId of oldIds) {
245
+ await this.perspective.addLink({ source: taskId, predicate: 'ad4m://ordered_after', target: previousId || 'null' }, batchId);
246
+ await this.perspective.addLink({ source: taskId, predicate: 'ad4m://position_id', target: `literal://string:${Date.now()}_migration` }, batchId);
247
+ previousId = taskId;
248
+ }
249
+ await this.perspective.commitBatch(batchId);
250
+ this.orderedTaskIds = '[]';
251
+ await this.update();
252
+ }
253
+ ```
254
+
255
+ ---
256
+
257
+ ### Strategy Comparison
258
+
259
+ | | RGA (LinkedList) | YATA | Fractional Index |
260
+ | ----------------------- | ---------------- | --------- | ---------------- |
261
+ | **Insert** | O(n) | O(1)\* | O(1) |
262
+ | **Delete** | O(n) | O(1) | O(n) |
263
+ | **Move** | O(n)×2 | O(1)×2 | O(1) |
264
+ | **Memory/item** | ~64 bytes | ~96 bytes | ~64 bytes |
265
+ | **Links/item** | 2 | 5 | 2 |
266
+ | **Conflict resolution** | Good | Excellent | Good |
267
+
268
+ \*Amortized
269
+
270
+ **RGA/LinkedList** — recommended default. Simple, debuggable, natural for AD4M's triple store. Best for lists < 50 items.
271
+
272
+ **Fractional Index** — simpler to understand, good for deterministic ordering, lists that don't change structure often. Position strings can grow over time and need occasional rebalancing.
273
+
274
+ **YATA** — future option. 3× storage but O(1) amortised ops and best-in-class conflict semantics. Only worth it for heavy concurrent editing (document editors, etc.).
275
+
276
+ ---
277
+
278
+ ### Open Questions
279
+
280
+ 1. **Bulk replace** (`tasks = newArray`) — treat as diff of old vs new, generate appropriate insert/delete operations.
281
+ 2. **Custom strategies** — supported via plugin: `ordering: { strategy: new MyCustomStrategy() }`.
282
+ 3. **Conflict visualisation** — AD4M inspector extension showing link graph.
283
+ 4. **Garbage collection cadence** — run on perspective sync, configurable tombstone threshold (e.g. 30 days).
284
+ 5. **Lazy vs eager reconstruction** — lazy on read, cache result, invalidate on link change.
285
+
286
+ ---
287
+
288
+ ### Implementation Phases
289
+
290
+ - [ ] Add `OrderingStrategy` interface + `LinkedListStrategy` (RGA)
291
+ - [ ] Add `ordering` option to `@HasMany` decorator options type
292
+ - [ ] Create Array Proxy layer in `Ad4mModel`
293
+ - [ ] Update `update()` to flush pending ordering operations
294
+ - [ ] Unit tests for each strategy in isolation
295
+ - [ ] `FractionalIndexStrategy` + `TimestampStrategy`
296
+ - [ ] Garbage collection
297
+ - [ ] Migration helper utility
298
+ - [ ] Integration tests (scenario 10 in playground)
299
+ - [ ] Debugging tools / inspector
300
+
301
+ ---
302
+
303
+ ### References
304
+
305
+ - [Figma's Fractional Indexing](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/)
306
+ - [CRDT Survey Paper](https://hal.inria.fr/hal-00932836/document)
307
+ - [RGA Algorithm](https://pages.lip6.fr/Marc.Shapiro/papers/RGA-TPDS-2011.pdf)
308
+ - [Yjs Documentation](https://docs.yjs.dev/)
309
+ - [Automerge CRDT](https://automerge.org/)
310
+
311
+ ---
312
+
313
+ **Scope:** Changes to `hydration.ts`, `SurrealQueryBuilder.ts`, `@HasMany` decorator options, possibly SHACL-level ordering predicates, and the Rust executor's link ordering. Fills in scenario 10 of the playground test harness.
314
+
315
+ **Priority:** Post-merge. High impact for multi-user apps.
316
+
317
+ ---
318
+
319
+ ## 12. External Consumer Migration — SubjectRepository (Phase G)
320
+
321
+ **Background:** `flux/packages/api/src/factory/SubjectRepository` and `ad4m-hooks/helpers/src/factory/SubjectRepository` still use Prolog `infer()` + the Subject proxy (`subject.init()`, async getters) for all model queries. They have no knowledge of `Ad4mModel`.
322
+
323
+ **Migration path:**
324
+
325
+ - Replace `getAll()` + `getSubjectData()` with `Ad4mModel.findAll()`
326
+ - Replace paginated `getAll()` with `Ad4mModel.findPage()`
327
+ - Replace Subject proxy getters with `Ad4mModel.getData()`
328
+ - Wire `useSubjects`/`useSubject` hooks to `Ad4mModel.subscribe()` for live updates
329
+
330
+ **Removals after migration:**
331
+
332
+ - `PerspectiveProxy.getSubjectData()` + `getSubjectProxy()`
333
+ - `PerspectiveClient.getSubjectData()`
334
+ - Rust `get_subject_data()` + GQL resolver (currently fires 5 Prolog queries per call)
335
+ - Both `SubjectRepository` classes
336
+
337
+ **Prerequisite:** Flux Phase F (decorator rename) must complete first.
338
+
339
+ **Priority:** Post-merge. Gated on Flux and hooks teams.
340
+
341
+ ---
342
+
343
+ ## 13. sh:inversePath — Rust/Prolog Side
344
+
345
+ **Background:** `@BelongsToOne`/`@BelongsToMany` set `inversePath: true` on the SHACL shape. The TypeScript SurrealDB hydration path works correctly (reverse `WHERE out.uri = ...` query). However `shacl_parser.rs` has zero handling of `sh:inversePath` — it never emits reverse Prolog predicates, so any Prolog-side lookup for a reverse relation silently returns nothing. `generatePrologFacts.ts` likewise has no reverse-predicate clause.
346
+
347
+ **Action:**
348
+
349
+ - `shacl_parser.rs`: detect `sh:inversePath`, emit reverse Prolog clauses (e.g. `channel_of(X, Y) :- triple(Y, 'predicate', X).`)
350
+ - `generatePrologFacts.ts`: handle `inversePath: true` shapes, emit reverse predicate clause
351
+
352
+ **Priority:** Low — only matters if a consumer writes explicit Prolog queries against reverse relations. The SurrealDB path (the common case) already works.
353
+
354
+ ---
355
+
356
+ ## 14. Parameterised SurrealQL Queries
357
+
358
+ **Problem:** `SurrealQueryBuilder.ts` and `getData()` still use string interpolation with `formatSurrealValue()` to prevent injection. SurrealDB supports parameterized queries via `querySurrealDB(query, bindings)` which are safe by construction.
359
+
360
+ ```typescript
361
+ // Current:
362
+ `SELECT ... FROM link WHERE in.uri = ${formatSurrealValue(base)}`;
363
+
364
+ // Target:
365
+ perspective.querySurrealDB("SELECT ... FROM link WHERE in.uri = $base", {
366
+ base,
367
+ });
368
+ ```
369
+
370
+ **Scope:** `queryToSurrealQL`, `getData()`, `fetchInstance.ts`, all raw SurrealQL construction throughout the query layer.
371
+
372
+ **Priority:** Medium. Not a regression (`formatSurrealValue` prevents injection today) but parameterized queries are the industry standard and eliminate an entire class of potential escaping bugs.
373
+
374
+ ---
375
+
376
+ ## 15. SDNA Wire Protocol Rename (`collection*` → `relation*`)
377
+
378
+ **Background:** The SDNA wire protocol still uses `collection`-prefixed predicate names: `collection/2`, `collection_getter/4`, `collection_adder/3`, `collection_remover/3`, `collection_setter/3`. These appear in 78+ locations across bootstrap languages and are queried by name throughout the Rust executor.
379
+
380
+ **Why deferred:** Renaming is a breaking change to the SDNA wire protocol — any live perspective with existing SDNA would stop working. Requires a versioned format, compatibility shim, or coordinated breaking release.
381
+
382
+ **Scope:**
383
+
384
+ 1. Choose new names (`relation/2`, `relation_getter/4`, etc.)
385
+ 2. Update all Rust executor references (`engine_pool.rs`, `sdna.rs`, `perspective_instance.rs`)
386
+ 3. Update all 78+ bootstrap language `.pl` files
387
+ 4. Update `tests/js/sdna/subject.pl`
388
+ 5. Write migration strategy
389
+
390
+ **Priority:** Major version / coordinated release item. Not before Phase G is complete.
391
+
392
+ ---
393
+
394
+ ## 16. Relation Action Duplication — TypeScript vs Rust SHACL
395
+
396
+ **Problem:** Relation adder/remover/setter mutations call `executeAction` with a TypeScript-generated action array. The Rust executor has `get_collection_adder_actions()` that derives the same structure from SHACL. Two implementations of the same logic that must stay in sync manually.
397
+
398
+ **Solution:** Have relation mutations fetch SHACL-derived actions from the executor (the same way `createSubject` does for property setters) rather than generating them independently in TypeScript.
399
+
400
+ **Priority:** Low. The implementations are simple and unlikely to diverge in practice, but the duplication is a maintenance risk for anyone modifying SHACL action formats.
401
+
402
+ ---
403
+
404
+ ## 17. Lifecycle Hooks
405
+
406
+ **Problem:** No mechanism to run logic before/after model persistence operations. Common patterns (validation before save, cascading deletes, post-load transforms) require subclass overrides with manual `super` calls.
407
+
408
+ **Proposed API:** Override async methods on the model class:
409
+
410
+ ```typescript
411
+ @ModelOptions({ name: "Recipe" })
412
+ class Recipe extends Ad4mModel {
413
+ async beforeSave() {
414
+ if (!this.name) throw new Error("Name required");
415
+ }
416
+
417
+ async afterLoad() {
418
+ // post-process after loading from perspective
419
+ }
420
+
421
+ async beforeDelete() {
422
+ // cascade deletes, cleanup, etc.
423
+ await Promise.all(this.ingredients.map((i) => i.delete()));
424
+ }
425
+ }
426
+ ```
427
+
428
+ **Scope:** `Ad4mModel.ts` — add protected no-op stub methods; call them at the appropriate points in `save()`, `getData()`/`findAll()`, and `delete()`. Hooks should be `async` and awaited so they can perform perspective operations.
429
+
430
+ **Priority:** Medium. Low effort, high ergonomics win.
431
+
432
+ ---
433
+
434
+ ## 18. Auto-Inverse Relations
435
+
436
+ **Problem:** Defining both sides of a bidirectional relationship is repetitive and error-prone. If the predicates or models diverge the relationship silently breaks.
437
+
438
+ **Proposed API:** An `inverse` option on `@BelongsToOne` / `@BelongsToMany` that auto-registers the forward `@HasMany` on the related class:
439
+
440
+ ```typescript
441
+ @ModelOptions({ name: "Message" })
442
+ class Message extends Ad4mModel {
443
+ @BelongsToOne(() => Channel, {
444
+ through: "ad4m://has_child",
445
+ inverse: "messages", // auto-registers @HasMany on Channel
446
+ })
447
+ channel: Channel;
448
+ }
449
+
450
+ // Channel no longer needs to manually declare:
451
+ // @HasMany(() => Message, { through: 'ad4m://has_child' })
452
+ // messages: Message[] = [];
453
+ ```
454
+
455
+ **Scope:** Decorator registration in `decorators.ts` — after `@BelongsToOne`/`@BelongsToMany` registers its own metadata, if `inverse` is set, call `registerRelation` on the related class's prototype for the forward side. Requires deferred resolution (the related class may not be fully defined yet) — use a post-decoration pass or lazy initialisation at first metadata read.
456
+
457
+ **Priority:** Low-medium. Reduces boilerplate in bidirectional models but the manual two-sided declaration is clear and explicit.
458
+
459
+ ---
460
+
461
+ ## Priority Order (suggested)
462
+
463
+ | # | Item | Impact | Effort |
464
+ | --- | ----------------------------- | ------ | ------ |
465
+ | 2 | Range filter push-down | High | Medium |
466
+ | 1 | Dirty tracking | High | Medium |
467
+ | 3 | N+1 batching | High | Medium |
468
+ | 8 | `getter` N+1 / push-down | High | Medium |
469
+ | 11 | CRDT ordering | High | High |
470
+ | 4 | Runtime validation | Medium | Low |
471
+ | 6 | Create-vs-update detection | Medium | Low |
472
+ | 14 | Parameterised SurrealQL | Medium | Medium |
473
+ | 10 | tests/js migration | Medium | Medium |
474
+ | 12 | External consumer migration | Medium | High |
475
+ | 5 | fromJSONSchema type inference | Medium | High |
476
+ | 13 | sh:inversePath Rust side | Low | Low |
477
+ | 16 | Relation action duplication | Low | Medium |
478
+ | 9 | Transaction abort | Low | Low |
479
+ | 15 | SDNA wire rename | Low | High |
480
+ | 17 | Lifecycle hooks | Medium | Low |
481
+ | 18 | Auto-inverse relations | Low | Medium |
482
+ | 7 | Stage 3 decorators | Low | High |