@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,317 @@
1
+ # Ad4mModel — ORM layer for AD4M perspectives
2
+
3
+ `Ad4mModel` is a class-based ORM that maps TypeScript objects to subgraphs inside an
4
+ AD4M [`PerspectiveProxy`](../perspectives/PerspectiveProxy.ts). Each instance is a
5
+ cluster of RDF-style link triples sharing a common **base URI** (the instance `id`).
6
+
7
+ ---
8
+
9
+ ## Quick start
10
+
11
+ ```typescript
12
+ import { Ad4mModel, Model, Property, Flag, HasMany } from "@coasys/ad4m";
13
+
14
+ @Model({ name: "Recipe" })
15
+ export class Recipe extends Ad4mModel {
16
+ @Flag({ through: "recipe://type", value: "recipe://Recipe" })
17
+ type: string = "";
18
+
19
+ @Property({ through: "recipe://title", resolveLanguage: "literal" })
20
+ title: string = "";
21
+
22
+ @Property({ through: "recipe://status", initial: "recipe://draft" })
23
+ status: string = "";
24
+
25
+ @HasMany({ through: "recipe://ingredient" })
26
+ ingredients: string[] = [];
27
+ }
28
+
29
+ // Install the SHACL/SDNA subject class once (idempotent):
30
+ await Recipe.register(perspective);
31
+
32
+ // Create
33
+ const r = await Recipe.create(perspective, { title: "Pasta" });
34
+
35
+ // Read
36
+ const loaded = new Recipe(perspective, r.id);
37
+ await loaded.get();
38
+ console.log(loaded.title); // "Pasta"
39
+
40
+ // Update
41
+ loaded.title = "Pasta al Pomodoro";
42
+ await loaded.save();
43
+
44
+ // Delete
45
+ await loaded.delete();
46
+ ```
47
+
48
+ ---
49
+
50
+ ## Architecture
51
+
52
+ ```
53
+ PerspectiveProxy (graph store)
54
+ └── "subject" node ←→ Ad4mModel instance
55
+ ├── ad4m://type → "recipe://Recipe" (@Flag)
56
+ ├── recipe://title → Literal("Pasta") (@Property)
57
+ └── recipe://ingredient → <uri>… (@HasMany)
58
+ ```
59
+
60
+ - **`id`** — the base URI of the instance subgraph (auto-generated from a random
61
+ 24-char literal if not supplied to the constructor).
62
+ - **Properties** — single-valued link triples `(id, predicate, value)` described by
63
+ `@Property` or `@Flag`.
64
+ - **Relations** — multi-valued link sets described by `@HasMany`, `@HasOne`,
65
+ `@BelongsToOne`, `@BelongsToMany`; each generates `add*`, `remove*`, `set*` methods.
66
+ - **Queries** — `findAll`, `findOne`, `query()` builder, `paginate`, `count` — all
67
+ compiled to SurrealQL and executed against the perspective's local graph engine.
68
+ - **Subscriptions** — `subscribe()` / `query().live()` re-run the query on each
69
+ relevant link change and deliver fresh results via callback.
70
+
71
+ > **Layer boundary**: `PerspectiveProxy` still uses `baseExpression` in its
72
+ > protocol-level Subject API. `Ad4mModel` exposes `id` as its ORM abstraction —
73
+ > the two refer to the same URI.
74
+
75
+ ---
76
+
77
+ ## Decorator reference
78
+
79
+ ### `@Model({ name })`
80
+
81
+ **Required** on every class extending `Ad4mModel`. Registers the SDNA subject class
82
+ name used by the perspective's Prolog engine and enables all static query methods.
83
+
84
+ ```typescript
85
+ @Model({ name: "Comment" })
86
+ class Comment extends Ad4mModel { ... }
87
+ ```
88
+
89
+ ---
90
+
91
+ ### `@Property(opts)`
92
+
93
+ Single-valued property backed by one link triple.
94
+
95
+ | Option | Description |
96
+ | ----------------- | --------------------------------------------------------------------- |
97
+ | `through` | Predicate URI **(required)** |
98
+ | `initial` | Default value added by the constructor action |
99
+ | `required` | Adds `sh:minCount 1` |
100
+ | `writable` | Generates a setter action (default `true` when `through` is set) |
101
+ | `resolveLanguage` | `"literal"` to store/retrieve via the Literal language |
102
+ | `local` | Store only in the local perspective (not synced to the network) |
103
+ | `getter` | Custom SurrealQL expression; used for computed / read-only properties |
104
+ | `transform` | Post-fetch `(rawValue) => transformedValue` function |
105
+
106
+ ```typescript
107
+ @Property({ through: "post://title", resolveLanguage: "literal" })
108
+ title: string = "";
109
+
110
+ // Read-only computed value
111
+ @Property({
112
+ through: "post://wordCount",
113
+ writable: false,
114
+ getter: `array::len(string::split((<-link[WHERE predicate='post://body'].in.uri)[0], ' '))`,
115
+ })
116
+ wordCount: number = 0;
117
+ ```
118
+
119
+ ---
120
+
121
+ ### `@Flag({ through, value })`
122
+
123
+ Immutable type-marker: a `@Property` whose value is fixed at creation and never
124
+ changed. Useful for type discrimination.
125
+
126
+ ```typescript
127
+ @Flag({ through: "ad4m://type", value: "flux://Message" })
128
+ type: string = "";
129
+ ```
130
+
131
+ ---
132
+
133
+ ### `@HasMany(opts)` / `@HasOne(opts)`
134
+
135
+ Forward relation: generates `add*`, `remove*`, and `set*` instance methods.
136
+
137
+ ```typescript
138
+ @HasMany({ through: "post://tag" })
139
+ tags: string[] = [];
140
+
141
+ // Typed — only returns URIs that are instances of the related model
142
+ @HasMany(() => Comment, { through: "post://comment" })
143
+ comments: Comment[] = [];
144
+ export interface Post extends HasManyMethods<"tags" | "comments"> {}
145
+ ```
146
+
147
+ `@HasOne` is the same but limits the collection to a single value (`sh:maxCount 1`).
148
+
149
+ ---
150
+
151
+ ### `@BelongsToOne(relatedModel, opts)` / `@BelongsToMany(relatedModel, opts)`
152
+
153
+ Reverse relation: traverses links **owned by the other side** — read-only, no mutator
154
+ methods generated.
155
+
156
+ ```typescript
157
+ @BelongsToOne(() => Post, { through: "post://comment" })
158
+ post: string = "";
159
+ ```
160
+
161
+ ---
162
+
163
+ ## Querying
164
+
165
+ ### Static helpers
166
+
167
+ ```typescript
168
+ // All instances
169
+ const all = await Recipe.findAll(perspective);
170
+
171
+ // Filtered
172
+ const hot = await Recipe.findAll(perspective, {
173
+ where: { status: "recipe://published", rating: { gt: 4 } },
174
+ order: { createdAt: "DESC" },
175
+ limit: 20,
176
+ offset: 0,
177
+ });
178
+
179
+ // Count
180
+ const n = await Recipe.count(perspective, {
181
+ where: { status: "recipe://draft" },
182
+ });
183
+
184
+ // With total (for pagination UI)
185
+ const { results, totalCount } = await Recipe.findAllAndCount(perspective, {
186
+ limit: 10,
187
+ });
188
+
189
+ // Explicit page
190
+ const page = await Recipe.paginate(perspective, 10, 2);
191
+ ```
192
+
193
+ ### Fluent query builder
194
+
195
+ ```typescript
196
+ const results = await Recipe.query(perspective)
197
+ .where({ status: "recipe://published" })
198
+ .order({ createdAt: "DESC" })
199
+ .limit(10)
200
+ .get();
201
+
202
+ // First match
203
+ const one = await Recipe.query(perspective).where({ title: "Pasta" }).first();
204
+
205
+ // Count matching records
206
+ const n = await Recipe.query(perspective)
207
+ .where({ status: "recipe://draft" })
208
+ .count();
209
+ ```
210
+
211
+ ### Subscriptions
212
+
213
+ ```typescript
214
+ const sub = Recipe.subscribe(
215
+ perspective,
216
+ { where: { status: "recipe://cooking" }, debounce: 300 },
217
+ (recipes) => setRecipes(recipes),
218
+ );
219
+
220
+ // Or via the builder:
221
+ const sub2 = Recipe.query(perspective)
222
+ .where({ status: "recipe://cooking" })
223
+ .live((recipes) => setRecipes(recipes));
224
+
225
+ // Always clean up:
226
+ sub.unsubscribe();
227
+ sub2.unsubscribe();
228
+ ```
229
+
230
+ ---
231
+
232
+ ## Transactions (batch operations)
233
+
234
+ ```typescript
235
+ await Ad4mModel.transaction(perspective, async (tx) => {
236
+ const post = new Post(perspective);
237
+ post.title = "Hello world";
238
+ await post.save(tx.batchId);
239
+
240
+ const comment = new Comment(perspective);
241
+ comment.body = "First!";
242
+ await comment.save(tx.batchId);
243
+ });
244
+ // Commits atomically; any throw aborts the batch
245
+ ```
246
+
247
+ ---
248
+
249
+ ## `fromJSONSchema` — dynamic model generation
250
+
251
+ Build an `Ad4mModel` subclass from a JSON Schema at runtime (useful for generic tooling
252
+ or schema-driven UIs):
253
+
254
+ ```typescript
255
+ const schema = {
256
+ title: "Person",
257
+ type: "object",
258
+ properties: {
259
+ name: { type: "string" },
260
+ email: { type: "string" },
261
+ },
262
+ };
263
+
264
+ // Option 1 — explicit namespace
265
+ const PersonClass = Ad4mModel.fromJSONSchema(schema, {
266
+ name: "Person",
267
+ namespace: "person://",
268
+ resolveLanguage: "literal",
269
+ });
270
+
271
+ // Option 2 — property-level predicate override
272
+ const ContactClass = Ad4mModel.fromJSONSchema(schema, {
273
+ name: "Contact",
274
+ namespace: "contact://",
275
+ propertyMapping: {
276
+ name: "foaf://name",
277
+ email: "foaf://mbox",
278
+ },
279
+ });
280
+
281
+ // Option 3 — embed predicates in the schema itself
282
+ const schemaWithMeta = {
283
+ title: "Product",
284
+ "x-ad4m": { namespace: "product://" },
285
+ properties: {
286
+ name: { type: "string", "x-ad4m": { through: "product://title" } },
287
+ },
288
+ };
289
+ const ProductClass = Ad4mModel.fromJSONSchema(schemaWithMeta, {
290
+ name: "Product",
291
+ });
292
+
293
+ await ProductClass.register(perspective);
294
+ const p = await ProductClass.create(perspective, { name: "Widget" });
295
+ ```
296
+
297
+ ---
298
+
299
+ ## Inheritance
300
+
301
+ Use `@Model` on the parent **and** the child. The SHACL generator emits `sh:node` to
302
+ reference the parent shape instead of duplicating its properties:
303
+
304
+ ```typescript
305
+ @Model({ name: "BaseBlock" })
306
+ class BaseBlock extends Ad4mModel {
307
+ @Property({ through: "block://createdBy" })
308
+ createdBy: string = "";
309
+ }
310
+
311
+ @Model({ name: "PollBlock" })
312
+ class PollBlock extends BaseBlock {
313
+ @Property({ through: "poll://question" })
314
+ question: string = "";
315
+ }
316
+ // PollBlock SHACL shape: sh:node <block://BaseBlockShape> + own poll:// properties only
317
+ ```
@@ -0,0 +1,356 @@
1
+ # Decouple SHACL from the Mutation Hot Path
2
+
3
+ > **Status:** Planning
4
+ > **Created:** 2026-02-28
5
+ > **Priority:** High — removes a class of bugs and simplifies the mutation path
6
+
7
+ ---
8
+
9
+ ## Table of Contents
10
+
11
+ 1. [Problem](#problem)
12
+ 2. [Current Mutation Flow](#current-mutation-flow)
13
+ 3. [What's Wrong With This](#whats-wrong-with-this)
14
+ 4. [Proposed Architecture](#proposed-architecture)
15
+ 5. [What SHACL Should Still Be Used For](#what-shacl-should-still-be-used-for)
16
+ 6. [Implementation Plan](#implementation-plan)
17
+ 7. [Risks and Considerations](#risks-and-considerations)
18
+
19
+ ---
20
+
21
+ ## Problem
22
+
23
+ SHACL shapes are currently used as an **instruction set** for mutations. The Rust
24
+ executor reads constructor/setter/adder/remover actions from the SHACL shape and
25
+ interprets them to create and update links. This means the ORM's decorator
26
+ metadata is serialised into SHACL, transmitted to Rust, parsed back into action
27
+ lists, and then executed as link operations — a round-trip through a
28
+ serialisation format when the ORM already has all the information it needs to
29
+ create links directly.
30
+
31
+ ---
32
+
33
+ ## Current Mutation Flow
34
+
35
+ ### Create path (first `save()`)
36
+
37
+ ```
38
+ ORM: instance.save() [TypeScript]
39
+ → perspective.createSubject(instance, id)
40
+ → Rust executor reads SHACL shape
41
+ → interprets ad4m://constructorActions
42
+ → executes addLink() for each constructor action
43
+ → reads initialValues from instance
44
+ → calls setter actions to overwrite constructor placeholders
45
+ → returns to TypeScript
46
+ ```
47
+
48
+ The create path goes through:
49
+
50
+ 1. TypeScript decorator metadata → SHACL Turtle serialisation
51
+ 2. Turtle → Rust SHACL parser
52
+ 3. Parser → constructor action list
53
+ 4. Action list → link operations
54
+ 5. Then separately: initial values → setter action list → more link operations
55
+
56
+ ### Update path (`save()` on existing instance)
57
+
58
+ ```
59
+ ORM: instance.save() [TypeScript]
60
+ → mutation.innerUpdate()
61
+ → for each dirty property: setProperty() → addLink() directly
62
+ → for each dirty relation: setRelationSetter() → addLink()/removeLink() directly
63
+ ```
64
+
65
+ The update path **already skips SHACL entirely**. It reads decorator metadata
66
+ (predicate URIs, relation types) from the registry and creates/removes links
67
+ directly via the perspective API. This is simpler, faster, and easier to debug.
68
+
69
+ ### The asymmetry
70
+
71
+ | | Create | Update |
72
+ | ----------------------- | ---------------------------------- | -------------------------- |
73
+ | **Reads metadata from** | SHACL shape (via Rust) | Decorator registry (JS) |
74
+ | **Mutation logic in** | Rust SHACL interpreter | TypeScript `mutation.ts` |
75
+ | **Debuggable in** | Rust (requires executor source) | TypeScript (same codebase) |
76
+ | **Latency** | SHACL parse + interpret + link ops | Direct link ops |
77
+
78
+ The update path is the correct architecture. The create path should work the same way.
79
+
80
+ ---
81
+
82
+ ## What's Wrong With This
83
+
84
+ ### 1. SHACL action generation and ORM mutation logic can disagree
85
+
86
+ The SHACL shape is generated from decorator metadata by `generateSHACL()` in
87
+ `decorators.ts`. The mutation logic in `mutation.ts` also reads from decorator
88
+ metadata. These are **two independent code paths** that must stay in sync:
89
+
90
+ - If a decorator option is added (e.g. `local: true`), it must be handled in
91
+ both `generateSHACL()` (for the constructor action) and `mutation.ts` (for
92
+ updates). If one is missed, creates and updates behave differently.
93
+
94
+ - The `createSubject` call in Rust has its own logic for "initial values" that
95
+ overwrite constructor placeholders. This mechanism is invisible from
96
+ TypeScript — if it fails silently, the ORM has no way to detect or recover.
97
+
98
+ ### 2. The Rust round-trip adds latency
99
+
100
+ Every first `save()` goes: JS → Rust SHACL parser → action interpreter → link
101
+ API → SurrealDB reindex → back to JS. The update path skips the SHACL
102
+ parser/interpreter entirely. Moving creates to the same path removes a
103
+ serialisation boundary.
104
+
105
+ ### 3. Debugging mutations requires tracing into Rust
106
+
107
+ When a `save()` produces unexpected links (wrong predicate, missing property,
108
+ duplicate link), debugging the create path requires reading the Rust executor's
109
+ SHACL interpreter. The update path is debuggable entirely in TypeScript — you
110
+ can set breakpoints in `mutation.ts` and inspect every link operation.
111
+
112
+ ### 4. The SHACL "constructor placeholder" pattern is fragile
113
+
114
+ The current SHACL constructor emits placeholder links like:
115
+
116
+ ```turtle
117
+ ad4m://constructorActions → addLink(this, "test://title", "literal://string:")
118
+ ```
119
+
120
+ Then `createSubject` calls setter actions to overwrite the placeholder with the
121
+ real value. This means every property is written **twice** on creation — once as
122
+ a placeholder, once as the real value. If the setter action fails, the
123
+ placeholder persists as stale data.
124
+
125
+ ---
126
+
127
+ ## Proposed Architecture
128
+
129
+ ### Create path (proposed)
130
+
131
+ ```
132
+ ORM: instance.save() [TypeScript]
133
+ → mutation.innerCreate() [new function]
134
+ → for each @Flag: addLink(id, predicate, flagValue)
135
+ → for each @Property: addLink(id, predicate, literal://value)
136
+ → for each @HasMany: links already exist (added via addX())
137
+ → captureSnapshot(instance)
138
+ → done
139
+ ```
140
+
141
+ This mirrors the update path. The ORM reads decorator metadata directly and
142
+ creates links without going through SHACL. Each property is written **once**
143
+ with the correct value — no placeholder/overwrite dance.
144
+
145
+ ### What `innerCreate()` would look like
146
+
147
+ ```ts
148
+ async function innerCreate(ctx: MutationContext): Promise<void> {
149
+ const metadata = getModelMetadata(ctx.instance.constructor);
150
+
151
+ // 1. Write flag links (type markers)
152
+ for (const [key, propMeta] of Object.entries(metadata.properties)) {
153
+ if (propMeta.flag) {
154
+ await ctx.perspective.add(
155
+ new Link({
156
+ source: ctx.id,
157
+ predicate: propMeta.through,
158
+ target: propMeta.initial, // flag value
159
+ }),
160
+ );
161
+ }
162
+ }
163
+
164
+ // 2. Write scalar property links
165
+ for (const [key, propMeta] of Object.entries(metadata.properties)) {
166
+ if (propMeta.flag || propMeta.readOnly) continue;
167
+ const value = ctx.instance[key];
168
+ if (value === undefined || value === null) continue;
169
+
170
+ const target = encodeAsLiteral(value, propMeta);
171
+ await ctx.perspective.add(
172
+ new Link({
173
+ source: ctx.id,
174
+ predicate: propMeta.through,
175
+ target,
176
+ ...(propMeta.local ? { local: true } : {}),
177
+ }),
178
+ );
179
+ }
180
+
181
+ // 3. Write forward-relation links
182
+ // (Relations added via addX() before save() already have links —
183
+ // but relations set as initial data in create() need links too)
184
+ for (const [key, relMeta] of Object.entries(metadata.relations)) {
185
+ if (relMeta.direction === "reverse") continue;
186
+ const value = ctx.instance[key];
187
+ if (!value) continue;
188
+
189
+ const ids = Array.isArray(value)
190
+ ? value.map((v) => (typeof v === "string" ? v : v.id))
191
+ : [typeof value === "string" ? value : value.id];
192
+
193
+ for (const targetId of ids) {
194
+ await ctx.perspective.add(
195
+ new Link({
196
+ source: ctx.id,
197
+ predicate: relMeta.through,
198
+ target: targetId,
199
+ ...(relMeta.local ? { local: true } : {}),
200
+ }),
201
+ );
202
+ }
203
+ }
204
+ }
205
+ ```
206
+
207
+ ### What `save()` becomes
208
+
209
+ ```ts
210
+ async save(batchId?: string) {
211
+ if (this._savedOnce) {
212
+ await mutation.innerUpdate(this._mutationContext(), batchId);
213
+ } else {
214
+ await mutation.innerCreate(this._mutationContext(), batchId);
215
+ }
216
+ this._savedOnce = true;
217
+ }
218
+ ```
219
+
220
+ This is **much simpler** than the current flow which goes through
221
+ `createSubject` → SHACL → Rust.
222
+
223
+ ---
224
+
225
+ ## What SHACL Should Still Be Used For
226
+
227
+ SHACL shapes are valuable. They should stay — just not in the mutation path.
228
+
229
+ ### 1. Validation
230
+
231
+ "Does this subgraph conform to the Channel shape?" SHACL was literally designed
232
+ for this. After creating/updating an instance, the runtime could optionally
233
+ validate the resulting subgraph against its shape.
234
+
235
+ ### 2. Interop / Schema Discovery
236
+
237
+ Other agents or tools can read a perspective's SHACL shapes to understand what
238
+ data structures exist. "What does a Message look like in this neighbourhood?"
239
+ → read the Message SHACL shape.
240
+
241
+ ### 3. `ensureSDNASubjectClass` / SurrealDB Indexing
242
+
243
+ The Rust executor uses SHACL shapes to configure SurrealDB's indexing — which
244
+ predicates to index, what the expected cardinality is, etc. This is the right
245
+ use of SHACL and should continue unchanged.
246
+
247
+ ### 4. Documentation
248
+
249
+ SHACL shapes are human-readable (in Turtle format) and describe the schema in a
250
+ standards-compliant way. They serve as living documentation of the data model.
251
+
252
+ ### Summary
253
+
254
+ | Use case | Keep SHACL? | On critical path? |
255
+ | ----------------------------- | ----------------------------------- | ------------------------------------- |
256
+ | Creating instances | **No** → ORM creates links directly | Was on path, move off |
257
+ | Updating instances | Already not used | Already off path |
258
+ | Validation | **Yes** | Optional / background |
259
+ | Schema discovery / interop | **Yes** | Not on mutation path |
260
+ | SurrealDB index configuration | **Yes** | On init path (once), not per-mutation |
261
+ | Documentation | **Yes** | Not on any runtime path |
262
+
263
+ ---
264
+
265
+ ## Implementation Plan
266
+
267
+ ### Step 1: Implement `innerCreate()` in `mutation.ts`
268
+
269
+ Write the direct-link-creation function as shown above. It reads from the
270
+ decorator metadata registry (same source as `innerUpdate()`) and creates links
271
+ via the perspective API.
272
+
273
+ **Prerequisite:** Understand how `encodeAsLiteral()` should work — the current
274
+ SHACL path uses `resolveLanguage` to determine how to encode values. The new
275
+ path needs the same logic. This likely already exists somewhere in the codebase
276
+ (check how `setProperty` in `mutation.ts` encodes values for updates).
277
+
278
+ ### Step 2: Add a feature flag
279
+
280
+ ```ts
281
+ const USE_DIRECT_CREATE = true; // flip to false to revert
282
+ ```
283
+
284
+ In `save()`, when `!this._savedOnce`:
285
+
286
+ - If flag is on: call `innerCreate()` directly
287
+ - If flag is off: call `createSubject()` (current SHACL path)
288
+
289
+ This allows A/B testing and safe rollback.
290
+
291
+ ### Step 3: Ensure `ensureSDNASubjectClass` still works
292
+
293
+ The SHACL shape must still be generated and registered with the perspective so
294
+ SurrealDB knows how to index the model. This is the `ensureSDNASubjectClass` /
295
+ `register()` call that happens at app startup — it's separate from per-instance
296
+ mutation and should continue unchanged.
297
+
298
+ Verify that SurrealDB correctly indexes instances created via direct links
299
+ (without going through `createSubject`). The index should be based on link
300
+ patterns matching the SHACL shape, not on how the links were created.
301
+
302
+ ### Step 4: Run full test suite
303
+
304
+ - All `model-query.test.ts` tests
305
+ - All `model-transactions.test.ts` tests
306
+ - Flux app smoke test (create channel, send message, pin channel)
307
+ - Verify SHACL shapes are still generated correctly (`generateSHACL()` is unchanged)
308
+
309
+ ### Step 5: Remove the SHACL mutation code path
310
+
311
+ Once validated, remove `createSubject()` from the ORM's save path. Keep:
312
+
313
+ - `generateSHACL()` for shape generation
314
+ - `ensureSDNASubjectClass()` for registration
315
+ - The Rust SHACL parser for index configuration
316
+
317
+ Remove:
318
+
319
+ - The `constructorActions` / `setterActions` interpretation in Rust (or leave it
320
+ for backward compatibility with older clients, but the ORM no longer uses it)
321
+ - The `initialValues` mechanism in `createSubject`
322
+
323
+ ---
324
+
325
+ ## Risks and Considerations
326
+
327
+ ### 1. `createSubject` may do more than just create links
328
+
329
+ The Rust `createSubject` implementation may have side effects beyond link
330
+ creation — e.g. notifying neighbourhood sync, triggering specific SurrealDB
331
+ operations, or updating internal state. These would need to be replicated or
332
+ triggered separately in the direct-create path.
333
+
334
+ **Mitigation:** Audit the Rust `createSubject` implementation before starting.
335
+ If it does more than link creation, those side effects need to be available via
336
+ a separate API call.
337
+
338
+ ### 2. Batch operations
339
+
340
+ The current `save(batchId)` pattern passes a batch ID to `createSubject`. The
341
+ direct-create path needs to pass the same batch ID to each `addLink()` call so
342
+ they're grouped in the same transaction.
343
+
344
+ ### 3. Backward compatibility
345
+
346
+ Older versions of the Rust executor expect `createSubject` calls. If the
347
+ TypeScript ORM starts creating links directly, it must still work with both old
348
+ and new executor versions during the transition period.
349
+
350
+ **Mitigation:** The feature flag (Step 2) allows reverting per-deployment.
351
+
352
+ ### 4. Neighbourhood sync
353
+
354
+ When an instance is created via `createSubject`, the executor may signal
355
+ neighbourhood peers differently than when individual links are added. Verify
356
+ that direct link creation triggers the same sync behaviour.