@coasys/ad4m 0.12.0-rc1-dev.2 → 0.12.0-rc1-dev.3
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.
- package/jest.config.js +10 -3
- package/lib/index.cjs +6872 -5886
- package/lib/index.js +6868 -5874
- package/lib/src/Ad4mClient.d.ts +9 -16
- package/lib/src/Ad4mClient.js +46 -25
- package/lib/src/Literal.d.ts +1 -2
- package/lib/src/Literal.js +38 -35
- package/lib/src/SmartLiteral.d.ts +1 -2
- package/lib/src/SmartLiteral.js +30 -15
- package/lib/src/agent/AgentClient.d.ts +1 -4
- package/lib/src/agent/AgentClient.js +79 -99
- package/lib/src/ai/AIClient.d.ts +1 -2
- package/lib/src/ai/AIClient.js +224 -220
- package/lib/src/expression/ExpressionClient.d.ts +1 -1
- package/lib/src/expression/ExpressionClient.js +73 -86
- package/lib/src/index.d.ts +1 -1
- package/lib/src/index.js +1 -1
- package/lib/src/language/LanguageClient.d.ts +1 -1
- package/lib/src/language/LanguageClient.js +52 -52
- package/lib/src/model/Ad4mModel.d.ts +1351 -144
- package/lib/src/model/Ad4mModel.js +3737 -228
- package/lib/src/model/Ad4mModel.test.js +522 -979
- package/lib/src/model/Subject.d.ts +3 -3
- package/lib/src/model/Subject.js +25 -25
- package/lib/src/model/decorators.d.ts +444 -100
- package/lib/src/model/decorators.js +686 -321
- package/lib/src/model/util.d.ts +6 -6
- package/lib/src/model/util.js +24 -24
- package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +1 -5
- package/lib/src/neighbourhood/NeighbourhoodClient.js +179 -242
- package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +1 -2
- package/lib/src/neighbourhood/NeighbourhoodProxy.js +28 -13
- package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +5 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
- package/lib/src/perspectives/PerspectiveClient.js +240 -316
- package/lib/src/perspectives/PerspectiveProxy.d.ts +99 -61
- package/lib/src/perspectives/PerspectiveProxy.js +485 -832
- package/lib/src/runtime/RuntimeClient.d.ts +1 -5
- package/lib/src/runtime/RuntimeClient.js +238 -412
- package/lib/src/shacl/SHACLFlow.test.js +105 -164
- package/lib/src/shacl/SHACLShape.d.ts +12 -17
- package/lib/src/shacl/SHACLShape.js +115 -128
- package/lib/src/shacl/SHACLShape.test.js +176 -244
- package/lib/src/shims/reflect-metadata.d.ts +0 -0
- package/lib/src/shims/type-graphql.d.ts +32 -0
- package/lib/src/src/Ad4mClient.d.ts +28 -0
- package/lib/src/src/Address.d.ts +1 -0
- package/lib/src/src/DID.d.ts +1 -0
- package/lib/src/src/Exception.d.ts +7 -0
- package/lib/src/src/Literal.d.ts +7 -0
- package/lib/src/src/PubSub.d.ts +17 -0
- package/lib/src/src/SmartLiteral.d.ts +12 -0
- package/lib/src/src/agent/Agent.d.ts +110 -0
- package/lib/src/src/agent/AgentClient.d.ts +62 -0
- package/lib/src/src/agent/AgentResolver.d.ts +30 -0
- package/lib/src/src/agent/AgentStatus.d.ts +8 -0
- package/lib/src/src/ai/AIClient.d.ts +32 -0
- package/lib/src/src/ai/AIResolver.d.ts +75 -0
- package/lib/src/src/ai/Tasks.d.ts +37 -0
- package/lib/src/src/buildSchema.d.ts +1 -0
- package/lib/src/src/expression/Expression.d.ts +28 -0
- package/lib/src/src/expression/ExpressionClient.d.ts +13 -0
- package/lib/src/src/expression/ExpressionRef.d.ts +9 -0
- package/lib/src/src/expression/ExpressionResolver.d.ts +10 -0
- package/lib/src/src/index.d.ts +35 -0
- package/lib/src/src/jestSetup.d.ts +1 -0
- package/lib/src/src/language/Icon.d.ts +4 -0
- package/lib/src/src/language/Language.d.ts +206 -0
- package/lib/src/src/language/LanguageClient.d.ts +17 -0
- package/lib/src/src/language/LanguageContext.d.ts +37 -0
- package/lib/src/src/language/LanguageHandle.d.ts +9 -0
- package/lib/src/src/language/LanguageMeta.d.ts +35 -0
- package/lib/src/src/language/LanguageRef.d.ts +6 -0
- package/lib/src/src/language/LanguageResolver.d.ts +19 -0
- package/lib/src/src/links/Links.d.ts +39 -0
- package/lib/src/src/links/Links.test.d.ts +1 -0
- package/lib/src/src/model/Ad4mModel.d.ts +1438 -0
- package/lib/src/src/model/Ad4mModel.test.d.ts +1 -0
- package/lib/src/src/model/Subject.d.ts +25 -0
- package/lib/src/src/model/decorators.d.ts +545 -0
- package/lib/src/src/model/util.d.ts +12 -0
- package/lib/src/src/neighbourhood/Neighbourhood.d.ts +10 -0
- package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +25 -0
- package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +19 -0
- package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
- package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +24 -0
- package/lib/src/src/perspectives/LinkQuery.d.ts +11 -0
- package/lib/src/src/perspectives/Perspective.d.ts +38 -0
- package/lib/src/src/perspectives/Perspective.test.d.ts +1 -0
- package/lib/src/src/perspectives/PerspectiveClient.d.ts +97 -0
- package/lib/src/src/perspectives/PerspectiveDiff.d.ts +9 -0
- package/lib/src/src/perspectives/PerspectiveHandle.d.ts +18 -0
- package/lib/src/src/perspectives/PerspectiveProxy.d.ts +865 -0
- package/lib/src/src/perspectives/PerspectiveResolver.d.ts +57 -0
- package/lib/src/src/runtime/RuntimeClient.d.ts +56 -0
- package/lib/src/src/runtime/RuntimeResolver.d.ts +132 -0
- package/lib/src/src/shacl/SHACLFlow.d.ts +171 -0
- package/lib/src/src/shacl/SHACLFlow.test.d.ts +1 -0
- package/lib/src/src/shacl/SHACLShape.d.ts +117 -0
- package/lib/src/src/shacl/SHACLShape.test.d.ts +1 -0
- package/lib/src/src/typeDefs.d.ts +1 -0
- package/lib/src/src/unwrapApolloResult.d.ts +2 -0
- package/lib/src/src/utils.d.ts +25 -0
- package/lib/src/utils.d.ts +0 -8
- package/lib/src/utils.js +7 -21
- package/package.json +15 -14
- package/src/Ad4mClient.test.ts +1315 -1564
- package/src/Ad4mClient.ts +54 -55
- package/src/Literal.test.ts +26 -45
- package/src/Literal.ts +66 -82
- package/src/SmartLiteral.ts +58 -74
- package/src/agent/AgentClient.ts +99 -144
- package/src/ai/AIClient.ts +359 -409
- package/src/expression/ExpressionClient.ts +96 -142
- package/src/index.ts +1 -1
- package/src/language/LanguageClient.ts +113 -137
- package/src/model/Ad4mModel.test.ts +616 -1114
- package/src/model/Ad4mModel.ts +4361 -451
- package/src/model/Subject.ts +159 -0
- package/src/model/decorators.ts +1168 -667
- package/src/model/util.ts +54 -53
- package/src/neighbourhood/NeighbourhoodClient.ts +266 -392
- package/src/neighbourhood/NeighbourhoodProxy.test.ts +7 -3
- package/src/neighbourhood/NeighbourhoodProxy.ts +40 -58
- package/src/perspectives/PerspectiveClient.ts +540 -779
- package/src/perspectives/PerspectiveProxy.ts +2067 -2860
- package/src/runtime/RuntimeClient.ts +476 -775
- package/src/shacl/SHACLFlow.test.ts +129 -196
- package/src/shacl/SHACLShape.test.ts +190 -284
- package/src/shacl/SHACLShape.ts +200 -224
- package/src/utils.ts +17 -31
- package/tsconfig.json +10 -9
- package/src/model/IMPROVEMENTS.md +0 -482
- package/src/model/PREDICATE_COLLISION_FIX.md +0 -651
- package/src/model/README.md +0 -317
- package/src/model/SHACL_MUTATION_DECOUPLING.md +0 -356
- package/src/model/SUBSCRIPTION_STRATEGY.md +0 -317
- package/src/model/TC39_STAGE_3_DECORATORS.md +0 -609
- package/src/model/mutation.ts +0 -461
- package/src/model/parentUtils.ts +0 -91
- package/src/model/prolog/generatePrologFacts.ts +0 -176
- package/src/model/prolog/index.ts +0 -1
- package/src/model/query/ModelQueryBuilder.ts +0 -173
- package/src/model/query/fetchInstance.ts +0 -181
- package/src/model/query/hydration.ts +0 -273
- package/src/model/query/operations.ts +0 -510
- package/src/model/query/snapshot.ts +0 -126
- package/src/model/query/surrealCompiler.ts +0 -376
- package/src/model/schema/fromJSONSchema.ts +0 -411
- package/src/model/schema/metadata.ts +0 -148
- package/src/model/subscription.ts +0 -307
- package/src/model/transaction.ts +0 -60
- package/src/model/types.ts +0 -207
|
@@ -1,651 +0,0 @@
|
|
|
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.
|