@coasys/ad4m 0.12.0-rc1-dev.1 → 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 -6046
  3. package/lib/index.js +5977 -6040
  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 -2799
  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 -3249
  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,651 @@
1
+ # Fix Predicate Collision: Type-Safe Relation Hydration
2
+
3
+ > **Status:** Agreed — implementing Path 3 (Hybrid)
4
+ > **Created:** 2026-02-28
5
+ > **Priority:** High — this is the root cause of the channel pinning duplication bug
6
+
7
+ ---
8
+
9
+ ## Table of Contents
10
+
11
+ 1. [The Bug](#the-bug)
12
+ 2. [Root Cause](#root-cause)
13
+ 3. [Why This Happens](#why-this-happens)
14
+ 4. [The Deeper Problem](#the-deeper-problem)
15
+ 5. [Solution Options](#solution-options)
16
+ 6. [Recommendation](#recommendation)
17
+ 7. [Implementation Plan](#implementation-plan)
18
+ 8. [Migration Strategy](#migration-strategy)
19
+
20
+ ---
21
+
22
+ ## The Bug
23
+
24
+ When a user pins a channel in Flux, all conversations inside that channel get
25
+ duplicated. The channel ends up with two copies of every conversation link.
26
+
27
+ ### Reproduction
28
+
29
+ 1. Create a channel with 3 conversations
30
+ 2. Pin the channel (toggle `isPinned`)
31
+ 3. Observe: the channel now has 6 conversations (3 originals + 3 duplicates)
32
+
33
+ ### Immediate cause
34
+
35
+ `Channel.findOne()` hydrates the full channel, including all relations. When
36
+ `save()` is called to persist the `isPinned` change, it re-writes **all**
37
+ relation links — including `conversations` — creating duplicates.
38
+
39
+ This was partially fixed by the **dirty tracking** system (see `snapshot.ts`),
40
+ which detects unchanged relations and skips them during `save()`. But the dirty
41
+ tracking fix treats the symptom. The underlying predicate collision problem
42
+ remains.
43
+
44
+ ---
45
+
46
+ ## Root Cause
47
+
48
+ The `Channel` model has two different relations that use the **same predicate**:
49
+
50
+ ```ts
51
+ @Model("Channel")
52
+ class Channel extends Ad4mModel {
53
+ @HasMany({ type: "Conversation", through: "ad4m://has_child" })
54
+ conversations: Conversation[] = [];
55
+
56
+ @HasMany({ type: "Channel", through: "ad4m://has_child" })
57
+ childChannels: Channel[] = [];
58
+ }
59
+ ```
60
+
61
+ Both `conversations` and `childChannels` use `"ad4m://has_child"` as their
62
+ predicate. In the link store, a channel's children look like:
63
+
64
+ ```
65
+ channel-1 --ad4m://has_child--> conversation-A
66
+ channel-1 --ad4m://has_child--> conversation-B
67
+ channel-1 --ad4m://has_child--> child-channel-X
68
+ ```
69
+
70
+ When the ORM hydrates `conversations`, it queries:
71
+
72
+ ```sql
73
+ SELECT * FROM links WHERE source = 'channel-1' AND predicate = 'ad4m://has_child'
74
+ ```
75
+
76
+ This returns **all three links** — including the child channel link. The ORM
77
+ then tries to instantiate all of them as `Conversation` objects. The child
78
+ channel link either:
79
+
80
+ 1. Gets silently instantiated as a malformed `Conversation` (wrong type), or
81
+ 2. Gets filtered out during hydration because it doesn't have the right SHACL
82
+ type marker
83
+
84
+ In practice, the ORM relies on SurrealDB's subject-class index to filter by
85
+ type, so the hydration usually works correctly for **reading**. But when `save()`
86
+ re-writes the relation links, it doesn't know which links in the store are
87
+ "conversations" and which are "child channels" — they all have the same
88
+ predicate.
89
+
90
+ ---
91
+
92
+ ## Why This Happens
93
+
94
+ ### RDF predicates are untyped
95
+
96
+ In RDF, a triple `(subject, predicate, object)` says nothing about the **type**
97
+ of the object. The predicate `ad4m://has_child` means "this thing has a child"
98
+ but doesn't say whether the child is a Conversation, a Channel, or a Cat.
99
+
100
+ This is by design in RDF — predicates are intentionally generic to enable
101
+ schema-free linking. But the ORM pretends predicates carry type information. When
102
+ it sees `@HasMany({ type: "Conversation", through: "ad4m://has_child" })`, it
103
+ assumes all `has_child` links from a Channel point to Conversations.
104
+
105
+ ### The ORM reads correctly but writes naively
106
+
107
+ **Reading** works because the ORM doesn't just query by predicate — it also
108
+ checks the subject class (via SurrealDB's SHACL index). So when hydrating
109
+ `conversations`, it effectively does:
110
+
111
+ ```
112
+ WHERE predicate = 'ad4m://has_child' AND target.type = 'Conversation'
113
+ ```
114
+
115
+ **Writing** is where things break. When `save()` re-writes `conversations`, it:
116
+
117
+ 1. Removes all links with predicate `ad4m://has_child` from the source
118
+ 2. Re-adds links for each item in the `conversations` array
119
+
120
+ Step 1 also removes the `childChannels` links (same predicate). Step 2 doesn't
121
+ add them back because they weren't in the `conversations` array.
122
+
123
+ With dirty tracking, `save()` now skips unchanged relations entirely. But if
124
+ `conversations` **is** changed (say, a new conversation is added), the
125
+ re-write in step 1 still blows away the child channel links.
126
+
127
+ ---
128
+
129
+ ## The Deeper Problem
130
+
131
+ This isn't specific to Channel. **Any model that reuses a predicate across
132
+ multiple relations** will have the same issue. And it's not obvious to the
133
+ developer that they're creating a collision — `has_child` is a perfectly natural
134
+ predicate for both "a channel's conversations" and "a channel's sub-channels".
135
+
136
+ ### Examples of potential collisions
137
+
138
+ ```ts
139
+ // Collision: same predicate for different target types
140
+ @HasMany({ type: "Message", through: "ad4m://has_item" })
141
+ messages: Message[];
142
+
143
+ @HasMany({ type: "Attachment", through: "ad4m://has_item" })
144
+ attachments: Attachment[];
145
+
146
+ // Collision: @HasMany and @HasOne with same predicate
147
+ @HasMany({ type: "Tag", through: "ad4m://tagged_with" })
148
+ tags: Tag[];
149
+
150
+ @HasOne({ type: "Tag", through: "ad4m://tagged_with" })
151
+ primaryTag: Tag;
152
+ ```
153
+
154
+ ---
155
+
156
+ ## Solution Options
157
+
158
+ ### Option A: Enforce Unique Predicates (Recommended First Step)
159
+
160
+ **Rule:** Within a single `@Model`, every `through` predicate must be unique
161
+ across all `@HasMany`, `@HasOne`, `@BelongsToOne`, and `@BelongsToMany`
162
+ decorators.
163
+
164
+ **Implementation:**
165
+
166
+ ```ts
167
+ // In the @Model decorator:
168
+ function Model(name: string) {
169
+ return function (constructor: Function) {
170
+ const relations = relationRegistry.get(constructor) ?? [];
171
+ const predicates = new Map<string, string>(); // predicate → field name
172
+
173
+ for (const rel of relations) {
174
+ const existing = predicates.get(rel.through);
175
+ if (existing) {
176
+ throw new Error(
177
+ `@Model("${name}"): predicate "${rel.through}" is used by both ` +
178
+ `"${existing}" and "${rel.key}". Each relation must use a unique ` +
179
+ `predicate. Use "ad4m://has_conversation" and ` +
180
+ `"ad4m://has_child_channel" instead of reusing "ad4m://has_child".`,
181
+ );
182
+ }
183
+ predicates.set(rel.through, rel.key);
184
+ }
185
+
186
+ // ... rest of @Model logic
187
+ };
188
+ }
189
+ ```
190
+
191
+ **Migration for Channel:**
192
+
193
+ ```ts
194
+ // Before (collision):
195
+ @HasMany({ type: "Conversation", through: "ad4m://has_child" })
196
+ conversations: Conversation[] = [];
197
+
198
+ @HasMany({ type: "Channel", through: "ad4m://has_child" })
199
+ childChannels: Channel[] = [];
200
+
201
+ // After (unique predicates):
202
+ @HasMany({ type: "Conversation", through: "ad4m://has_conversation" })
203
+ conversations: Conversation[] = [];
204
+
205
+ @HasMany({ type: "Channel", through: "ad4m://has_child_channel" })
206
+ childChannels: Channel[] = [];
207
+ ```
208
+
209
+ **Pros:**
210
+
211
+ - Simple to implement (~20 lines)
212
+ - Catches the bug at definition time (loud error, not silent data corruption)
213
+ - No changes to the query/mutation pipeline
214
+ - Aligns with how the ORM actually uses predicates (as typed foreign keys)
215
+
216
+ **Cons:**
217
+
218
+ - Loses some RDF generality (predicates become model-specific keys)
219
+ - Doesn't solve the case where two different models use the same predicate
220
+ pointing at the same target type (but that's not a real problem in practice)
221
+
222
+ ---
223
+
224
+ ### Option B: Type-Filtered Hydration and Mutation
225
+
226
+ **Rule:** The ORM always considers the target type when reading and writing
227
+ relation links. A relation `@HasMany({ type: "Conversation", through: "ad4m://has_child" })`
228
+ only reads/writes links where the target is a `Conversation`.
229
+
230
+ **Reading (already works):**
231
+ SurrealDB's subject-class index already filters by type during hydration.
232
+
233
+ **Writing (needs change):**
234
+
235
+ ```ts
236
+ // In mutation.ts, when updating a HasMany relation:
237
+ async function updateRelation(ctx, key, relMeta) {
238
+ const currentLinks = await ctx.perspective.get(
239
+ new LinkQuery({
240
+ source: ctx.id,
241
+ predicate: relMeta.through,
242
+ }),
243
+ );
244
+
245
+ // Only touch links whose targets are of the correct type
246
+ const relevantLinks = currentLinks.filter((link) =>
247
+ isOfType(link.target, relMeta.type),
248
+ );
249
+
250
+ const desiredIds = new Set(ctx.instance[key].map((v) => v.id));
251
+ const currentIds = new Set(relevantLinks.map((l) => l.data.target));
252
+
253
+ // Remove links that are no longer in the array
254
+ for (const link of relevantLinks) {
255
+ if (!desiredIds.has(link.data.target)) {
256
+ await ctx.perspective.remove(link);
257
+ }
258
+ }
259
+
260
+ // Add links for new items
261
+ for (const id of desiredIds) {
262
+ if (!currentIds.has(id)) {
263
+ await ctx.perspective.add(
264
+ new Link({
265
+ source: ctx.id,
266
+ predicate: relMeta.through,
267
+ target: id,
268
+ }),
269
+ );
270
+ }
271
+ }
272
+ }
273
+ ```
274
+
275
+ The key change is `isOfType()` — checking whether a target has the expected
276
+ subject-class marker before touching its link.
277
+
278
+ **Pros:**
279
+
280
+ - No breaking changes to existing predicates
281
+ - Preserves RDF generality (same predicate, different types, handled correctly)
282
+ - More aligned with how RDF actually works
283
+
284
+ **Cons:**
285
+
286
+ - **Mutation cost:** `isOfType()` requires querying each target's type
287
+ (additional DB lookups). For a `HasMany` with N items, that's up to N extra
288
+ SurrealDB queries per `save()`. These could be batched into a single
289
+ `WHERE id IN [...]` query, but the round-trip still exists.
290
+ - **Query cost: none.** The read path already uses SurrealDB's subject-class
291
+ index to filter by type — this is how hydration works today regardless of
292
+ which option you choose. Option B doesn't change the query path at all.
293
+ The cost is purely on the write side.
294
+ - Adds complexity to the mutation path (harder to debug)
295
+ - Still doesn't prevent the developer from accidentally creating ambiguous
296
+ schemas — the ORM silently handles it, so the developer may never realise
297
+ two relations share a predicate
298
+
299
+ ---
300
+
301
+ ### Option C: Compound Predicates
302
+
303
+ **Rule:** The ORM automatically generates unique predicates by combining the
304
+ user-specified predicate with the target type.
305
+
306
+ ```ts
307
+ @HasMany({ type: "Conversation", through: "ad4m://has_child" })
308
+ conversations: Conversation[] = [];
309
+
310
+ // Internally becomes: predicate = "ad4m://has_child#Conversation"
311
+
312
+ @HasMany({ type: "Channel", through: "ad4m://has_child" })
313
+ childChannels: Channel[] = [];
314
+
315
+ // Internally becomes: predicate = "ad4m://has_child#Channel"
316
+ ```
317
+
318
+ **Pros:**
319
+
320
+ - No breaking API changes for the developer
321
+ - Unique predicates without manual naming
322
+ - Query and mutation just work
323
+
324
+ **Cons:**
325
+
326
+ - Breaks RDF interop (non-standard predicate URIs)
327
+ - Existing data uses un-suffixed predicates — needs migration
328
+ - Hides what's actually happening (developer sees `has_child`, store has `has_child#Conversation`)
329
+ - Fragile if model names change
330
+
331
+ ---
332
+
333
+ ## Recommendation
334
+
335
+ ### These are alternative strategies, not sequential steps
336
+
337
+ **Important:** Options A and B are mutually exclusive philosophies. If Option B
338
+ is implemented (the ORM correctly handles shared predicates via type filtering),
339
+ then Option A's hard error is wrong — it forbids something the ORM now handles
340
+ correctly. You can't enforce "predicates must be unique" and then build a system
341
+ that correctly handles non-unique predicates. Pick one:
342
+
343
+ ### Path 1: Option A alone — Enforce Unique Predicates
344
+
345
+ Choose this if you believe:
346
+
347
+ - The ORM should treat predicates as typed foreign keys (one predicate = one relation)
348
+ - RDF generality within a single model isn't needed
349
+ - Developers should be explicit about their link semantics
350
+
351
+ **What you get:**
352
+
353
+ - ~20 lines of code in `@Model`
354
+ - Zero changes to query or mutation logic
355
+ - Bugs caught at definition time with a clear error message
356
+ - Self-documenting schemas (`ad4m://has_conversation` is clearer than `ad4m://has_child`)
357
+
358
+ **What you give up:**
359
+
360
+ - Developers can't reuse a predicate across relations within a model
361
+ - Existing data with shared predicates needs migration (rename links)
362
+
363
+ **This is the simpler path.** No new runtime complexity. The fix is in the
364
+ schema, not the engine.
365
+
366
+ ### Path 2: Option B alone — Type-Filtered Mutation
367
+
368
+ Choose this if you believe:
369
+
370
+ - Shared predicates are a valid RDF pattern the ORM should support
371
+ - The ORM should be smart enough to handle them correctly
372
+ - Forcing predicate renaming across existing data is too costly
373
+
374
+ **What you get:**
375
+
376
+ - Correct read and write behaviour even with shared predicates
377
+ - No breaking changes to existing models or data
378
+ - Better RDF alignment
379
+
380
+ **What you give up:**
381
+
382
+ - Extra `isOfType()` lookups during mutation (write-side cost only — the read
383
+ path already uses SurrealDB's type index and is unaffected)
384
+ - More complex mutation logic (harder to debug)
385
+ - Developers still won't get a warning when they create an ambiguous schema —
386
+ the ORM silently handles it, which means the developer may not even realise
387
+ two relations share a predicate until they inspect the link store
388
+
389
+ ### Path 3: Option A as warning + Option B as fix (Hybrid)
390
+
391
+ There is one valid combination: use Option A as a **warning** (not error) and
392
+ Option B as the actual correctness mechanism:
393
+
394
+ ```ts
395
+ // In @Model:
396
+ if (predicateCollision) {
397
+ console.warn(
398
+ `[AD4M ORM] Model "${name}": predicate "${rel.through}" is shared by ` +
399
+ `"${existing}" and "${rel.key}". The ORM handles this correctly via ` +
400
+ `type-filtered mutation, but consider using unique predicates for clarity.`,
401
+ );
402
+ }
403
+ ```
404
+
405
+ This gives developers visibility ("hey, you're sharing predicates") without
406
+ breaking their code, while the type-filtering ensures correctness regardless.
407
+
408
+ **This is the recommended path.** It fixes the bug at the engine level,
409
+ gives developers visibility without breaking changes, and leaves predicate
410
+ renaming as an optional clean-up rather than a hard prerequisite.
411
+
412
+ ### Our recommendation: Path 3 (Hybrid — Warning + Type-Filtered Mutation)
413
+
414
+ After further discussion, Path 3 is the optimal route. Here's why:
415
+
416
+ 1. **Correctness by default.** Type-filtered mutation (Option B) means the ORM
417
+ handles shared predicates correctly regardless of whether the developer
418
+ notices the collision. Silent data corruption is eliminated at the engine
419
+ level, not just at the schema level.
420
+
421
+ 2. **The warning is still valuable.** Shared predicates are almost always a
422
+ modelling mistake. The `console.warn` in `@Model` gives developers immediate
423
+ visibility without breaking existing code or requiring a forced migration.
424
+ It's a nudge, not a blocker.
425
+
426
+ 3. **Write-side cost is acceptable.** The `isOfType()` lookups during mutation
427
+ can be batched into a single `WHERE id IN [...]` query per relation, keeping
428
+ the extra round-trip to one per dirty relation per `save()`. For the typical
429
+ model this is negligible, and the correctness guarantee outweighs it.
430
+
431
+ 4. **No forced migration.** Path 1 requires renaming all colliding predicates
432
+ and writing a data migration before shipping. Path 3 fixes the bug
433
+ immediately in the engine, then lets predicate renaming happen at a more
434
+ comfortable pace — or not at all, if developers prefer to leave their schemas
435
+ as-is.
436
+
437
+ 5. **Future-proof.** If RDF interop with external agents becomes a requirement,
438
+ shared predicates are already handled correctly. Nothing needs to be
439
+ re-architected later.
440
+
441
+ ---
442
+
443
+ ## Implementation Plan
444
+
445
+ ### Phase 1: Audit All Models
446
+
447
+ Search all model files across Flux and We for predicate collisions:
448
+
449
+ ```bash
450
+ # Find all @HasMany/@HasOne/@BelongsTo* decorators and their predicates
451
+ grep -rn '@Has\|@BelongsTo' --include='*.ts' | grep 'through:' | \
452
+ sed 's/.*through:\s*["'\'']\([^"'\'']*\)["'\''].*/\1/' | \
453
+ sort | uniq -c | sort -rn
454
+ ```
455
+
456
+ Confirm the Channel collision is the only one, or identify others.
457
+
458
+ ### Phase 2: Implement Type-Filtered Mutation (Option B — the core fix)
459
+
460
+ Update `mutation.ts` so that when re-writing a relation, the ORM only touches
461
+ links whose targets are of the correct type. This eliminates the data corruption
462
+ regardless of whether predicates are shared.
463
+
464
+ ```ts
465
+ // In mutation.ts, when updating a HasMany relation:
466
+ async function updateRelation(ctx, key, relMeta) {
467
+ const currentLinks = await ctx.perspective.get(
468
+ new LinkQuery({
469
+ source: ctx.id,
470
+ predicate: relMeta.through,
471
+ }),
472
+ );
473
+
474
+ // Only touch links whose targets are of the correct type — this ensures
475
+ // shared predicates across different relation fields don't clobber each other.
476
+ const relevantLinks = await filterByType(currentLinks, relMeta.type);
477
+
478
+ const desiredIds = new Set(ctx.instance[key].map((v) => v.id));
479
+ const currentIds = new Set(relevantLinks.map((l) => l.data.target));
480
+
481
+ for (const link of relevantLinks) {
482
+ if (!desiredIds.has(link.data.target)) {
483
+ await ctx.perspective.remove(link);
484
+ }
485
+ }
486
+
487
+ for (const id of desiredIds) {
488
+ if (!currentIds.has(id)) {
489
+ await ctx.perspective.add(
490
+ new Link({ source: ctx.id, predicate: relMeta.through, target: id }),
491
+ );
492
+ }
493
+ }
494
+ }
495
+ ```
496
+
497
+ `filterByType` should batch the type lookups into a single `WHERE id IN [...]`
498
+ query to keep the extra round-trip to one per dirty relation per `save()`.
499
+
500
+ ### Phase 3: Add @Model Collision Warning (Option A as warning)
501
+
502
+ Add the duplicate-predicate check in the `@Model` decorator, emitting a
503
+ **warning** (not an error) so developers are alerted without breaking existing
504
+ code:
505
+
506
+ ```ts
507
+ // In the @Model decorator:
508
+ const relations = relationRegistry.get(constructor) ?? [];
509
+ const predicates = new Map<string, string>();
510
+
511
+ for (const rel of relations) {
512
+ const existing = predicates.get(rel.through);
513
+ if (existing) {
514
+ console.warn(
515
+ `[AD4M ORM] Model "${name}": predicate "${rel.through}" is shared by ` +
516
+ `"${existing}" and "${rel.key}". The ORM handles this correctly via ` +
517
+ `type-filtered mutation, but consider using unique predicates for clarity.`,
518
+ );
519
+ }
520
+ predicates.set(rel.through, rel.key);
521
+ }
522
+ ```
523
+
524
+ ### Phase 4: (Optional) Rename Colliding Predicates
525
+
526
+ With Phases 2 and 3 in place the bug is already fixed. Renaming predicates is
527
+ now a clean-up exercise, not a hard requirement. Do it when convenient:
528
+
529
+ ```ts
530
+ // Before:
531
+ @HasMany({ type: "Conversation", through: "ad4m://has_child" })
532
+ conversations: Conversation[] = [];
533
+
534
+ @HasMany({ type: "Channel", through: "ad4m://has_child" })
535
+ childChannels: Channel[] = [];
536
+
537
+ // After:
538
+ @HasMany({ type: "Conversation", through: "ad4m://has_conversation" })
539
+ conversations: Conversation[] = [];
540
+
541
+ @HasMany({ type: "Channel", through: "ad4m://has_child_channel" })
542
+ childChannels: Channel[] = [];
543
+ ```
544
+
545
+ If predicates are renamed, ship a one-time data migration run on app startup
546
+ (gated by a version flag) to rewrite existing links:
547
+
548
+ ```ts
549
+ async function migrateChannelPredicates(perspective: PerspectiveProxy) {
550
+ const links = await perspective.get(
551
+ new LinkQuery({ predicate: "ad4m://has_child" }),
552
+ );
553
+ for (const link of links) {
554
+ const targetType = await getSubjectClass(link.data.target);
555
+ let newPredicate: string;
556
+ if (targetType === "Conversation") {
557
+ newPredicate = "ad4m://has_conversation";
558
+ } else if (targetType === "Channel") {
559
+ newPredicate = "ad4m://has_child_channel";
560
+ } else {
561
+ continue; // leave non-Channel/Conversation has_child links untouched
562
+ }
563
+ await perspective.remove(link);
564
+ await perspective.add(new Link({ ...link.data, predicate: newPredicate }));
565
+ }
566
+ }
567
+ ```
568
+
569
+ ### Phase 5: Verify
570
+
571
+ - All existing tests pass
572
+ - Channel pinning no longer duplicates conversations
573
+ - New conversations appear correctly
574
+ - Child channels appear correctly
575
+ - Shared-predicate warning fires in dev console for any colliding models
576
+
577
+ ---
578
+
579
+ ## Migration Strategy
580
+
581
+ ### Identifying Collisions
582
+
583
+ Run this audit across all model files:
584
+
585
+ ```bash
586
+ # Find all @HasMany/@HasOne/@BelongsTo* decorators and their predicates
587
+ grep -rn '@Has\|@BelongsTo' --include='*.ts' | grep 'through:' | \
588
+ sed 's/.*through:\s*["'\'']\([^"'\'']*\)["'\''].*/\1/' | \
589
+ sort | uniq -c | sort -rn
590
+ ```
591
+
592
+ ### Known Collisions (from Flux audit)
593
+
594
+ | Model | Field 1 | Field 2 | Shared Predicate |
595
+ | ------- | --------------- | --------------- | ------------------ |
596
+ | Channel | `conversations` | `childChannels` | `ad4m://has_child` |
597
+
598
+ > **Note:** This list should be expanded with a full audit of all models in
599
+ > Flux (~22 models) and We (~10 models).
600
+
601
+ ### Renaming Convention
602
+
603
+ When splitting a shared predicate, use descriptive relation-specific names:
604
+
605
+ | Before | After |
606
+ | --------------------------------------- | -------------------------- |
607
+ | `ad4m://has_child` (for conversations) | `ad4m://has_conversation` |
608
+ | `ad4m://has_child` (for child channels) | `ad4m://has_child_channel` |
609
+ | `ad4m://has_item` (for messages) | `ad4m://has_message` |
610
+ | `ad4m://has_item` (for attachments) | `ad4m://has_attachment` |
611
+
612
+ The pattern is: `ad4m://has_<singular_relation_name>`.
613
+
614
+ ### Data Migration Considerations
615
+
616
+ 1. **Local-first:** Each user's local perspective needs migration. Ship the
617
+ migration as part of the app update — run it once on startup if a version
618
+ flag isn't set.
619
+
620
+ 2. **Shared neighbourhoods:** Other agents may still create links with the old
621
+ predicate. The ORM should accept both old and new predicates during a
622
+ transition period, but only write new predicates.
623
+
624
+ 3. **Ordering:** Migrate reads first (accept both predicates), then writes (use
625
+ new predicate), then drop old-predicate support.
626
+
627
+ ### Transition Period Query
628
+
629
+ During migration, the ORM can query both predicates:
630
+
631
+ ```ts
632
+ // In operations.ts, during include hydration:
633
+ const predicates = relMeta.legacyPredicates
634
+ ? [relMeta.through, ...relMeta.legacyPredicates]
635
+ : [relMeta.through];
636
+
637
+ // Query each predicate and merge results
638
+ ```
639
+
640
+ This could be supported via a decorator option:
641
+
642
+ ```ts
643
+ @HasMany({
644
+ type: "Conversation",
645
+ through: "ad4m://has_conversation",
646
+ legacyPredicates: ["ad4m://has_child"], // also read from old predicate
647
+ })
648
+ conversations: Conversation[] = [];
649
+ ```
650
+
651
+ Once all data is migrated, remove the `legacyPredicates` option.