@coasys/ad4m 0.13.0-test-model-layer → 0.13.0-test-flows-1

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 (55) hide show
  1. package/lib/index.cjs +817 -65
  2. package/lib/index.js +814 -66
  3. package/lib/src/ai/AIClient.d.ts +13 -0
  4. package/lib/src/ai/AIClient.js +15 -0
  5. package/lib/src/ai/AITypes.d.ts +5 -0
  6. package/lib/src/index.js +2 -0
  7. package/lib/src/model/Ad4mModel.d.ts +6 -1
  8. package/lib/src/model/Ad4mModel.js +41 -6
  9. package/lib/src/model/ModelQueryBuilder.d.ts +47 -3
  10. package/lib/src/model/ModelQueryBuilder.js +97 -6
  11. package/lib/src/model/query-common.d.ts +10 -1
  12. package/lib/src/model/query-common.js +16 -0
  13. package/lib/src/model/query-sparql.d.ts +11 -0
  14. package/lib/src/model/query-sparql.js +93 -1
  15. package/lib/src/model/query-utils.js +16 -0
  16. package/lib/src/model/shacl-gen.js +12 -0
  17. package/lib/src/model/types.d.ts +320 -3
  18. package/lib/src/model/types.js +9 -0
  19. package/lib/src/perspectives/AutoProcessor.d.ts +8 -0
  20. package/lib/src/perspectives/FlowInstance.d.ts +176 -12
  21. package/lib/src/perspectives/FlowInstance.js +77 -13
  22. package/lib/src/perspectives/FlowModels.d.ts +40 -9
  23. package/lib/src/perspectives/FlowModels.js +59 -13
  24. package/lib/src/perspectives/PerspectiveClient.d.ts +18 -0
  25. package/lib/src/perspectives/PerspectiveClient.js +30 -0
  26. package/lib/src/perspectives/PerspectiveProxy.d.ts +69 -2
  27. package/lib/src/perspectives/PerspectiveProxy.js +157 -7
  28. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +55 -5
  29. package/lib/src/perspectives/WakerSubscriptionManager.js +183 -8
  30. package/lib/src/shacl/SHACLFlow.d.ts +43 -0
  31. package/package.json +1 -1
  32. package/src/ai/AIClient.ts +16 -0
  33. package/src/ai/AITypes.ts +5 -0
  34. package/src/index.ts +2 -0
  35. package/src/model/Ad4mModel.test.ts +442 -0
  36. package/src/model/Ad4mModel.ts +39 -7
  37. package/src/model/ModelQueryBuilder.ts +101 -10
  38. package/src/model/query-common.ts +20 -1
  39. package/src/model/query-sparql.test.ts +115 -0
  40. package/src/model/query-sparql.ts +97 -1
  41. package/src/model/query-utils.ts +18 -0
  42. package/src/model/relation-filtering.test.ts +7 -0
  43. package/src/model/shacl-gen.ts +12 -0
  44. package/src/model/shacl-roundtrip.test.ts +71 -0
  45. package/src/model/types-typed-query.test.ts +42 -0
  46. package/src/model/types.ts +316 -6
  47. package/src/perspectives/AutoProcessor.ts +8 -0
  48. package/src/perspectives/FlowInstance.ts +194 -13
  49. package/src/perspectives/FlowModels.ts +53 -13
  50. package/src/perspectives/PerspectiveClient.ts +62 -0
  51. package/src/perspectives/PerspectiveProxy.test.ts +272 -0
  52. package/src/perspectives/PerspectiveProxy.ts +163 -7
  53. package/src/perspectives/WakerSubscriptionManager.test.ts +199 -0
  54. package/src/perspectives/WakerSubscriptionManager.ts +197 -9
  55. package/src/shacl/SHACLFlow.ts +44 -0
@@ -6,7 +6,16 @@
6
6
  * creating circular runtime dependencies on `Ad4mModel.ts`.
7
7
  */
8
8
  import type { Ad4mModel } from "./Ad4mModel";
9
+ import type { LinkStatus } from "../perspectives/PerspectiveProxy";
9
10
  import type { NodeExpression } from "../shacl/NodeExpression";
11
+ /**
12
+ * Who wrote a link: a DID, any of several DIDs, or `{ not }` / `{ contains }`
13
+ * over the author DID.
14
+ */
15
+ export type AuthorCondition = string | string[] | {
16
+ not?: string | string[];
17
+ contains?: string;
18
+ };
10
19
  export type WhereOps = {
11
20
  not: string | number | boolean | string[] | number[];
12
21
  between: [number, number];
@@ -15,6 +24,16 @@ export type WhereOps = {
15
24
  gt: number;
16
25
  gte: number;
17
26
  contains: string | number;
27
+ /** Equality as an operator: `{ eq: X }` is the bare value `X` (an array
28
+ * means any of). It lets a value sit beside `author`, and cannot be
29
+ * combined with the other value operators. */
30
+ eq: string | number | boolean | string[] | number[];
31
+ /** Per-link author: the link that satisfies this property's condition was
32
+ * written by this author, e.g. `{ agent: { eq: did, author: admin } }`.
33
+ * Alone, `{ agent: { author: admin } }`: admin wrote some `agent` link.
34
+ * Only on properties and relations stored as links (not getters,
35
+ * `timestamp` or `id`). See "Filtering by Author" in the model-classes guide. */
36
+ author: AuthorCondition;
18
37
  };
19
38
  export type WhereCondition = string | number | boolean | string[] | number[] | {
20
39
  [K in keyof WhereOps]?: WhereOps[K];
@@ -26,8 +45,26 @@ export type Where = {
26
45
  AND?: Where[];
27
46
  /** Logical NOT: instance must NOT satisfy the given sub-clause. */
28
47
  NOT?: Where;
48
+ /**
49
+ * Only instances that are valid outputs of a completed run of `flow`
50
+ * (optionally: of a run settled into terminal state `state`).
51
+ *
52
+ * Decided executor-side by cryptographic receipt verification, not by a
53
+ * property: an instance passes only when a verified receipt of the flow
54
+ * names it among the outputs its quorum committed to AND its live content
55
+ * still matches that commitment. Fail-closed — a forged, unverifiable or
56
+ * stale receipt excludes the instance — and applied BEFORE `limit`/
57
+ * `offset`, so a page of N is N valid outputs. Only supported as a
58
+ * top-level key on the queried class; anywhere else the query errors.
59
+ */
60
+ producedByFlow?: ProducedByFlowFilter;
29
61
  [propertyName: string]: WhereCondition | undefined;
30
62
  };
63
+ /** The `where.producedByFlow` filter — see {@link Where.producedByFlow}. */
64
+ export type ProducedByFlowFilter = {
65
+ flow: string;
66
+ state?: string;
67
+ };
31
68
  export type Order = {
32
69
  [propertyName: string]: "ASC" | "DESC";
33
70
  };
@@ -49,6 +86,10 @@ export type Order = {
49
86
  * predicate to write.
50
87
  *
51
88
  * **Raw form** — explicit predicate string, no metadata lookup.
89
+ *
90
+ * **Traverse form** — bounded traversal from one or more anchors, for reading
91
+ * a tree rather than one node's children. Read-only: AutoProcessor's write
92
+ * scopes reject it, because it names no single parent to write under.
52
93
  */
53
94
  export type Scope = {
54
95
  model: typeof Ad4mModel;
@@ -57,7 +98,122 @@ export type Scope = {
57
98
  } | {
58
99
  id: string;
59
100
  predicate: string;
60
- };
101
+ } | TraverseScope;
102
+ /**
103
+ * Walk a predicate from several anchors at once, and optionally all the way
104
+ * down.
105
+ *
106
+ * This exists because a tree read one level at a time costs a round trip per
107
+ * level and — under a subscription — one subscription per *parent*. Asking for
108
+ * every anchor in one query makes both proportional to depth instead.
109
+ *
110
+ * The predicate is named the same two ways the other scopes name it: literally,
111
+ * or by the model and relation that own it. See {@link TraverseByPredicate} and
112
+ * {@link TraverseByModel}.
113
+ */
114
+ export type TraverseScope = TraverseByPredicate | TraverseByModel;
115
+ /** A traversal naming its predicate literally, as the Raw scope does. */
116
+ export interface TraverseByPredicate extends TraverseOptions {
117
+ predicate: string;
118
+ }
119
+ /**
120
+ * A traversal naming its predicate through the model that declares it, as the
121
+ * Model scope does — `{ model: Post, field: 'comments' }` rather than
122
+ * `'test://has_comment'`.
123
+ *
124
+ * Without `field` the predicate is resolved by scanning for a relation on
125
+ * `model` whose target is the queried class, which is the same rule the Model
126
+ * scope uses and the same reason to pass `field` when a parent has more than
127
+ * one relation to the same child.
128
+ */
129
+ export interface TraverseByModel extends TraverseOptions {
130
+ model: typeof Ad4mModel;
131
+ field?: string;
132
+ }
133
+ /** Everything a traversal says that is not how it names its predicate. */
134
+ export interface TraverseOptions {
135
+ /** The anchors to walk from. A bare string is the single-anchor spelling. */
136
+ ids: string | string[];
137
+ /**
138
+ * Follow the predicate as far as it goes rather than one step.
139
+ *
140
+ * The result is a flat set of everything reachable, and it does **not**
141
+ * describe the shape it came from: SPARQL property paths bind no intermediate
142
+ * variables, so a row says that it is under the anchor and never where. To
143
+ * rebuild a tree, read the inverse relation (`@BelongsToOne`) alongside it and
144
+ * assemble from the parent each row reports.
145
+ *
146
+ * Excludes every named anchor, not just the one a given row was reached through — a caller
147
+ * naming two anchors where one sits below the other gets neither back, exactly as with `levels`.
148
+ * An anchor is where the read started, not something it found, and that holds in a cycle too.
149
+ *
150
+ * Refused alongside `levels`, which is the bounded form of the same walk.
151
+ */
152
+ transitive?: boolean;
153
+ /**
154
+ * `'out'` (default) matches `anchor --predicate--> result`; `'in'` matches
155
+ * `result --predicate--> anchor`, which is how to *search* among the things
156
+ * pointing at a node — ordered, filtered, limited. A reverse `include`
157
+ * answers the same question for rows already in hand, but cannot narrow them.
158
+ */
159
+ direction?: 'out' | 'in';
160
+ /**
161
+ * Keep at most this many results per anchor — "the top 5 replies under each
162
+ * of these 20 comments" in one query.
163
+ *
164
+ * Applied by the executor between selecting ids and hydrating them, because
165
+ * SPARQL has no per-group limit (no window functions, and sub-SELECTs are
166
+ * uncorrelated). The practical consequence is that the over-fetch is paid in
167
+ * ids, not records: a branch with 3,000 replies costs 3,000 strings and
168
+ * hydrates 5.
169
+ *
170
+ * Pair it with `order` — without one the "top" N is whatever the store
171
+ * happened to return first. A global `limit`/`offset` is applied to the
172
+ * sliced union afterwards, not before it.
173
+ *
174
+ * Refused alongside `levels`, which applies its own per-anchor limit at
175
+ * every depth.
176
+ */
177
+ limitPerAnchor?: number;
178
+ /**
179
+ * Walk the relation level by level, keeping this many results per anchor at each depth —
180
+ * `[10, 5, 3]` is "ten replies, five under each of those, three under each of *those*".
181
+ *
182
+ * The walk happens in the executor, which is the point of it. A caller can drive the same walk by
183
+ * asking for one level and using the ids as the next level's anchors, but each step is then a
184
+ * network round trip, and a UI that draws as each answer lands shows the tree assembling itself a
185
+ * level at a time. Inside the executor the levels are sequential queries against a local store
186
+ * with nothing serialised between them, and the records are hydrated once for the union — so
187
+ * three levels cost one request and one hydration rather than three of each.
188
+ *
189
+ * Results come back flat and breadth-first; read the inverse relation alongside to rebuild the
190
+ * tree, exactly as with `transitive`. The anchors are excluded from their own result, also as
191
+ * with `transitive` — a walk that reaches an anchor again, through a cycle or because one anchor
192
+ * was named below another, reports it at neither place.
193
+ *
194
+ * Each record appears once, under whichever anchor the ordering reaches first — a reply to two
195
+ * of the anchors is one reply, not two. It does not spend a place in the other anchors' breadth
196
+ * either: they fill theirs with replies of their own, so a breadth of five means five distinct
197
+ * records wherever five exist.
198
+ *
199
+ * A global `limit`/`offset` applies to that flat union once, after every level has been cut to
200
+ * its own breadth — not to each level.
201
+ *
202
+ * Combining this with `transitive` or `limitPerAnchor` is an **error**, not a preference the
203
+ * executor resolves: `transitive` is the unbounded form of the same walk, and `limitPerAnchor`
204
+ * has no place to act when the walk sets a per-anchor limit at every depth itself. (It is not a
205
+ * substitute either — with a single anchor at the top there is one group, so it caps the total
206
+ * rather than the breadth at each level.) Put the first level's breadth in `levels[0]`.
207
+ */
208
+ levels?: number[];
209
+ }
210
+ /**
211
+ * Whether this scope is a traversal rather than a single named parent.
212
+ *
213
+ * The other two forms carry `id`; this one carries `ids` and may name several,
214
+ * so anything reaching for one parent — every write path — has to ask first.
215
+ */
216
+ export declare function isTraverseScope(scope: Scope): scope is TraverseScope;
61
217
  /**
62
218
  * Describes which relations to eager-load when querying.
63
219
  *
@@ -105,6 +261,20 @@ export interface IncludeProjection {
105
261
  from: string;
106
262
  /** When true, attaches an integer count instead of a list. */
107
263
  count?: true;
264
+ /**
265
+ * Project over everything reachable through `from`, not just one step.
266
+ *
267
+ * `{ from: 'comments', count: true, transitive: true }` is the whole
268
+ * conversation under each row rather than its direct replies — which is what
269
+ * a reader takes "42 replies" on a collapsed branch to mean. The projection
270
+ * query is already grouped per parent and already asked of every row at once,
271
+ * so this adds no round trip.
272
+ *
273
+ * Cannot be combined with a filter on the link's author or timestamp: those
274
+ * read the reification of one link, and a path has none. Such a projection is
275
+ * skipped with a warning rather than silently answering a different question.
276
+ */
277
+ transitive?: boolean;
108
278
  /**
109
279
  * Bare class name of the projection target. Set automatically by
110
280
  * `prepareModelQueryParams`; the executor resolves the target's shape
@@ -147,7 +317,116 @@ export type Query = {
147
317
  * queries where getter-backed properties are not needed.
148
318
  */
149
319
  deepQuery?: boolean;
320
+ /**
321
+ * Read instances as they exist in links of one status only.
322
+ *
323
+ * `'shared'` hydrates from Shared links only: every property, relation,
324
+ * `author` and `updatedAt` comes from links that are gossiped to the
325
+ * neighbourhood, and none from this executor's Local links. That is the
326
+ * read to use when showing data to another user (#1024). `'local'` is the
327
+ * converse. Unset or `null` (the default) reads both, and a property
328
+ * declared `local: true` still reads only its Local links.
329
+ *
330
+ * Relations include typed `@HasMany` / `@HasOne` relations, which are filled
331
+ * by the conformance getter the SDK generates: the executor adds the status
332
+ * check to that getter's relation link. A hand-written `getter` is run as
333
+ * written, so it reads links of any status unless it checks
334
+ * `<ad4m://ontology/status>` itself.
335
+ *
336
+ * Included relations and the instances a `$` projection hydrates inherit
337
+ * the setting, unless an include's sub-query sets its own. The `__links`
338
+ * rows (see {@link Query.links}) are restricted the same way.
339
+ *
340
+ * Combines with {@link Query.includeUnverified}: a link must have the
341
+ * requested status **and** pass the signature check, both on the same link.
342
+ * So a Local link whose signature did not verify is withheld under
343
+ * `linkStatus: 'local'` too, and comes back only with
344
+ * `linkStatus: 'local', includeUnverified: true` (or with no `linkStatus`
345
+ * and `includeUnverified: true`).
346
+ *
347
+ * Scope: this restricts the links that hydrate an instance and the links
348
+ * that *select* it (`where`, the class's flags, `count`/`totalCount`, `$`
349
+ * projections, `parent` scopes and the order behind `limit`/`offset`). So an
350
+ * instance is returned under `'local'` only when it is flagged in a Local
351
+ * link, and under `'shared'` only when it is flagged in a Shared one.
352
+ */
353
+ linkStatus?: LinkStatus;
354
+ /**
355
+ * Also hydrate from links whose signature did not verify.
356
+ *
357
+ * By default the executor withholds every link whose stored signature
358
+ * verdict is not valid, so a forged or tampered link never becomes a
359
+ * property value, a relation target, `author` or `updatedAt`. That
360
+ * includes a typed relation's generated conformance getter. A `getter` you
361
+ * write yourself runs as written, so it reads unverified links unless it
362
+ * joins the link's `ad4m://ontology/proofValid` itself. Set this to
363
+ * `true` only to *display* an unverified claim, e.g. a UI that marks a value
364
+ * as unverified. Anything that acts on the data, such as a vote counter or a
365
+ * role check, must leave it off.
366
+ *
367
+ * Included relations inherit the setting unless their sub-query sets its own.
368
+ *
369
+ * The same applies to the rows under `__links` and to what *selects* an
370
+ * instance: `where` (including a per-link `author`), the class's flags,
371
+ * `count`/`totalCount`, the order behind `limit`/`offset`, `parent` scopes
372
+ * and `$` projections, `transitive` ones included. With `true`, selection
373
+ * reads unverified links too.
374
+ */
375
+ includeUnverified?: boolean;
376
+ /**
377
+ * Return the individual links behind each instance, with their own author,
378
+ * timestamp, signature and signature verdict, under `instance.__links`. For
379
+ * a collection this is per-item provenance: who added each member, when, and
380
+ * whether their signature holds.
381
+ *
382
+ * Each entry is a property or relation name the model declares, or an
383
+ * absolute predicate IRI — including one the model does **not** declare
384
+ * (an annotation such as a revocation tombstone). A name wins over the IRI
385
+ * reading. Every requested entry is present on every instance, as `[]` when
386
+ * it has no such link. An entry that is neither a declared name nor an IRI,
387
+ * or that names a reverse relation (`@BelongsToOne` / `@BelongsToMany`),
388
+ * makes the query fail rather than answer `[]`.
389
+ *
390
+ * The rows are read by a second query after the instances are hydrated, so
391
+ * asking for them never changes `createdAt`, `updatedAt` or any property.
392
+ * See {@link LinkRow}.
393
+ */
394
+ links?: string[];
150
395
  };
396
+ /**
397
+ * One stored link as returned under `__links` — the same shape as the
398
+ * `LinkExpression` `perspective.get()` returns, including the signature
399
+ * verdict the executor recorded when the link was stored.
400
+ *
401
+ * `proof.valid` is `true` only when the signature verifies against `author`.
402
+ * A link stored without a proof arrives with `key` and `signature` set to
403
+ * `""` and `valid: false`; that is an unverifiable link, not a valid unsigned
404
+ * one. Anything that acts on a row (counting a vote, granting a role) should
405
+ * require `proof.valid`.
406
+ *
407
+ * `valid` is never `null` here and `invalid` is always `!valid`, the same
408
+ * convention as `perspective.get()`. So `invalid: true` does not by itself mean
409
+ * a signature failed: it also covers a link with no proof, or with no recorded
410
+ * verdict. To tell an unsigned link from a failed signature, check whether
411
+ * `proof.signature` is `""`.
412
+ */
413
+ export interface LinkRow {
414
+ author: string;
415
+ timestamp: string;
416
+ data: {
417
+ source: string;
418
+ predicate: string;
419
+ target: string;
420
+ };
421
+ proof: {
422
+ key: string;
423
+ signature: string;
424
+ valid: boolean;
425
+ invalid: boolean;
426
+ };
427
+ }
428
+ /** `instance.__links`: requested entry (spelled as requested) → its rows, oldest first. */
429
+ export type LinksMap = Record<string, LinkRow[]>;
151
430
  /**
152
431
  * Sub-query options for a specific relation inside an `IncludeMap`.
153
432
  *
@@ -194,6 +473,10 @@ type HasNoTypedFields<T extends Ad4mModel> = [
194
473
  export type StringWhereOps = {
195
474
  not?: string | string[];
196
475
  contains?: string;
476
+ /** See {@link WhereOps.eq}. */
477
+ eq?: string | string[];
478
+ /** See {@link WhereOps.author}. */
479
+ author?: AuthorCondition;
197
480
  };
198
481
  export type NumericWhereOps = {
199
482
  not?: number | number[];
@@ -202,8 +485,15 @@ export type NumericWhereOps = {
202
485
  gt?: number;
203
486
  gte?: number;
204
487
  between?: [number, number];
488
+ /** See {@link WhereOps.eq}. */
489
+ eq?: number | number[];
490
+ /** See {@link WhereOps.author}. */
491
+ author?: AuthorCondition;
205
492
  };
206
- export type TypedWhereCondition<V> = V extends string ? string | string[] | StringWhereOps : V extends number ? number | number[] | NumericWhereOps : V extends boolean ? boolean : V extends Array<infer U> ? U extends string ? string | string[] | StringWhereOps : U extends number ? number | number[] | NumericWhereOps : WhereCondition : WhereCondition;
493
+ export type TypedWhereCondition<V> = V extends string ? string | string[] | StringWhereOps : V extends number ? number | number[] | NumericWhereOps : V extends boolean ? boolean | {
494
+ eq?: boolean;
495
+ author?: AuthorCondition;
496
+ } : V extends Array<infer U> ? U extends string ? string | string[] | StringWhereOps : U extends number ? number | number[] | NumericWhereOps : WhereCondition : WhereCondition;
207
497
  /** Strict Where: keys constrained to T's properties, plus the well-known
208
498
  * link-metadata fields (`id`/`author`/`timestamp`) and logical combinators. */
209
499
  type StrictTypedWhere<T extends Ad4mModel> = {
@@ -211,6 +501,13 @@ type StrictTypedWhere<T extends Ad4mModel> = {
211
501
  } & {
212
502
  base?: string | string[];
213
503
  id?: string | string[];
504
+ /** Alone: the instance's `.author`, i.e. its earliest link's author.
505
+ * Beside property/relation conditions in the same object: that, AND
506
+ * each of those conditions is satisfied by a link this author wrote.
507
+ * For "this author wrote the `agent` link" alone, nest it:
508
+ * `{ agent: { eq: did, author } }`. It does not reach into
509
+ * `OR`/`AND`/`NOT` sub-clauses. See "Filtering by Author" in the
510
+ * model-classes guide. */
214
511
  author?: WhereCondition;
215
512
  timestamp?: WhereCondition;
216
513
  OR?: StrictTypedWhere<T>[];
@@ -220,6 +517,13 @@ type StrictTypedWhere<T extends Ad4mModel> = {
220
517
  /** Public typed `where` for a model class. Falls back to the loose `Where`
221
518
  * shape when T has no declared fields (e.g. fromSHACL-derived classes). */
222
519
  export type TypedWhere<T extends Ad4mModel> = HasNoTypedFields<T> extends true ? Where : StrictTypedWhere<T>;
520
+ /** Top-level typed `where` of a query on T: {@link TypedWhere} plus
521
+ * `producedByFlow`. Kept out of `TypedWhere` itself because that shape is
522
+ * reused under `OR`/`AND`/`NOT` and in include sub-queries, where the
523
+ * executor rejects `producedByFlow` (see {@link Where.producedByFlow}). */
524
+ export type TypedQueryWhere<T extends Ad4mModel> = TypedWhere<T> & {
525
+ producedByFlow?: ProducedByFlowFilter;
526
+ };
223
527
  type StrictTypedOrder<T extends Ad4mModel> = {
224
528
  [K in PropertyKeysOf<T> | 'timestamp' | 'author' | 'createdAt' | 'updatedAt']?: 'ASC' | 'DESC';
225
529
  } & {
@@ -233,6 +537,11 @@ export type TypedRelationSubQuery<U extends Ad4mModel> = {
233
537
  include?: TypedIncludeMap<U>;
234
538
  limit?: number;
235
539
  offset?: number;
540
+ /** See {@link Query.linkStatus}. Inherited from the parent query when unset. */
541
+ linkStatus?: LinkStatus;
542
+ /** See {@link Query.includeUnverified}. Inherited from the parent query when unset. */
543
+ includeUnverified?: boolean;
544
+ links?: string[];
236
545
  };
237
546
  /** Projection — `from` must be a real relation on T; `where`/`order` constrained to that target.
238
547
  * Modelled as a discriminated union so the literal `count: true` and `limit: 1`
@@ -241,14 +550,17 @@ export type TypedIncludeProjection<T extends Ad4mModel> = {
241
550
  [K in RelationKeysOf<T>]: {
242
551
  from: K;
243
552
  count: true;
553
+ transitive?: boolean;
244
554
  } | {
245
555
  from: K;
246
556
  limit: 1;
557
+ transitive?: boolean;
247
558
  where?: TypedWhere<RelatedModel<T, K>>;
248
559
  order?: TypedOrder<RelatedModel<T, K>>;
249
560
  } | {
250
561
  from: K;
251
562
  limit?: number;
563
+ transitive?: boolean;
252
564
  where?: TypedWhere<RelatedModel<T, K>>;
253
565
  order?: TypedOrder<RelatedModel<T, K>>;
254
566
  };
@@ -286,12 +598,17 @@ type StrictTypedQuery<T extends Ad4mModel> = {
286
598
  properties?: PropertyKeysOf<T>[];
287
599
  include?: TypedIncludeMap<T>;
288
600
  includeAll?: boolean;
289
- where?: TypedWhere<T>;
601
+ where?: TypedQueryWhere<T>;
290
602
  order?: TypedOrder<T>;
291
603
  offset?: number;
292
604
  limit?: number;
293
605
  count?: boolean;
294
606
  deepQuery?: boolean;
607
+ /** See {@link Query.linkStatus}. */
608
+ linkStatus?: LinkStatus;
609
+ /** See {@link Query.includeUnverified}. */
610
+ includeUnverified?: boolean;
611
+ links?: string[];
295
612
  };
296
613
  export type TypedQuery<T extends Ad4mModel> = HasNoTypedFields<T> extends true ? Query : StrictTypedQuery<T>;
297
614
  /** Helper that extracts the `include` literal from a TypedQuery for use with IncludeExtras. */
@@ -5,6 +5,15 @@
5
5
  * (`query-utils.ts`, `decorators.ts`, etc.) can import types without
6
6
  * creating circular runtime dependencies on `Ad4mModel.ts`.
7
7
  */
8
+ /**
9
+ * Whether this scope is a traversal rather than a single named parent.
10
+ *
11
+ * The other two forms carry `id`; this one carries `ids` and may name several,
12
+ * so anything reaching for one parent — every write path — has to ask first.
13
+ */
14
+ export function isTraverseScope(scope) {
15
+ return 'ids' in scope;
16
+ }
8
17
  /** Type guard for IncludeProjection objects. */
9
18
  export function isIncludeProjection(val) {
10
19
  return typeof val === 'object' && val !== null && 'from' in val;
@@ -221,6 +221,14 @@ export interface AddAutoProcessorConfig {
221
221
  basePrefix?: string;
222
222
  /** Class URIs (SHACL `target_class`) to materialize each pass. */
223
223
  interpretationClasses: string[];
224
+ /**
225
+ * Canonical flow URIs (`SHACLFlow` `{namespace}{name}Flow`) this processor
226
+ * is flow-aware of. Flow features — the flow-aware prompt, the
227
+ * transition-proposal pass, and auto-spawn on freshly created items — run
228
+ * only on the flows listed here, mirroring the class selection above.
229
+ * Omit (or pass `[]`) for no flow processing.
230
+ */
231
+ flows?: string[];
224
232
  /** Quiet-window (ms) after the last new item before a pass runs. */
225
233
  debounceMs: number;
226
234
  /** Minimum items before a pass runs (Flux "wait for N inputs"). Default 1. */