@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
package/src/model/README.md
DELETED
|
@@ -1,317 +0,0 @@
|
|
|
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
|
-
```
|
|
@@ -1,356 +0,0 @@
|
|
|
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.
|