@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
@@ -10,12 +10,22 @@
10
10
  // Forward type-only reference to Ad4mModel (no runtime circular dependency)
11
11
  // ---------------------------------------------------------------------------
12
12
  import type { Ad4mModel } from "./Ad4mModel";
13
+ import type { LinkStatus } from "../perspectives/PerspectiveProxy";
13
14
  import type { NodeExpression } from "../shacl/NodeExpression";
14
15
 
15
16
  // ---------------------------------------------------------------------------
16
17
  // Query DSL types
17
18
  // ---------------------------------------------------------------------------
18
19
 
20
+ /**
21
+ * Who wrote a link: a DID, any of several DIDs, or `{ not }` / `{ contains }`
22
+ * over the author DID.
23
+ */
24
+ export type AuthorCondition =
25
+ | string
26
+ | string[]
27
+ | { not?: string | string[]; contains?: string };
28
+
19
29
  export type WhereOps = {
20
30
  not: string | number | boolean | string[] | number[];
21
31
  between: [number, number];
@@ -24,6 +34,16 @@ export type WhereOps = {
24
34
  gt: number; // greater than
25
35
  gte: number; // greater than or equal to
26
36
  contains: string | number; // substring/element check
37
+ /** Equality as an operator: `{ eq: X }` is the bare value `X` (an array
38
+ * means any of). It lets a value sit beside `author`, and cannot be
39
+ * combined with the other value operators. */
40
+ eq: string | number | boolean | string[] | number[];
41
+ /** Per-link author: the link that satisfies this property's condition was
42
+ * written by this author, e.g. `{ agent: { eq: did, author: admin } }`.
43
+ * Alone, `{ agent: { author: admin } }`: admin wrote some `agent` link.
44
+ * Only on properties and relations stored as links (not getters,
45
+ * `timestamp` or `id`). See "Filtering by Author" in the model-classes guide. */
46
+ author: AuthorCondition;
27
47
  };
28
48
  export type WhereCondition =
29
49
  | string
@@ -42,8 +62,23 @@ export type Where = {
42
62
  AND?: Where[];
43
63
  /** Logical NOT: instance must NOT satisfy the given sub-clause. */
44
64
  NOT?: Where;
65
+ /**
66
+ * Only instances that are valid outputs of a completed run of `flow`
67
+ * (optionally: of a run settled into terminal state `state`).
68
+ *
69
+ * Decided executor-side by cryptographic receipt verification, not by a
70
+ * property: an instance passes only when a verified receipt of the flow
71
+ * names it among the outputs its quorum committed to AND its live content
72
+ * still matches that commitment. Fail-closed — a forged, unverifiable or
73
+ * stale receipt excludes the instance — and applied BEFORE `limit`/
74
+ * `offset`, so a page of N is N valid outputs. Only supported as a
75
+ * top-level key on the queried class; anywhere else the query errors.
76
+ */
77
+ producedByFlow?: ProducedByFlowFilter;
45
78
  [propertyName: string]: WhereCondition | undefined;
46
79
  };
80
+ /** The `where.producedByFlow` filter — see {@link Where.producedByFlow}. */
81
+ export type ProducedByFlowFilter = { flow: string; state?: string };
47
82
  export type Order = { [propertyName: string]: "ASC" | "DESC" };
48
83
 
49
84
  /**
@@ -64,10 +99,137 @@ export type Order = { [propertyName: string]: "ASC" | "DESC" };
64
99
  * predicate to write.
65
100
  *
66
101
  * **Raw form** — explicit predicate string, no metadata lookup.
102
+ *
103
+ * **Traverse form** — bounded traversal from one or more anchors, for reading
104
+ * a tree rather than one node's children. Read-only: AutoProcessor's write
105
+ * scopes reject it, because it names no single parent to write under.
67
106
  */
68
107
  export type Scope =
69
108
  | { model: typeof Ad4mModel; id: string; field?: string }
70
- | { id: string; predicate: string };
109
+ | { id: string; predicate: string }
110
+ | TraverseScope;
111
+
112
+ /**
113
+ * Walk a predicate from several anchors at once, and optionally all the way
114
+ * down.
115
+ *
116
+ * This exists because a tree read one level at a time costs a round trip per
117
+ * level and — under a subscription — one subscription per *parent*. Asking for
118
+ * every anchor in one query makes both proportional to depth instead.
119
+ *
120
+ * The predicate is named the same two ways the other scopes name it: literally,
121
+ * or by the model and relation that own it. See {@link TraverseByPredicate} and
122
+ * {@link TraverseByModel}.
123
+ */
124
+ export type TraverseScope = TraverseByPredicate | TraverseByModel;
125
+
126
+ /** A traversal naming its predicate literally, as the Raw scope does. */
127
+ export interface TraverseByPredicate extends TraverseOptions {
128
+ predicate: string;
129
+ }
130
+
131
+ /**
132
+ * A traversal naming its predicate through the model that declares it, as the
133
+ * Model scope does — `{ model: Post, field: 'comments' }` rather than
134
+ * `'test://has_comment'`.
135
+ *
136
+ * Without `field` the predicate is resolved by scanning for a relation on
137
+ * `model` whose target is the queried class, which is the same rule the Model
138
+ * scope uses and the same reason to pass `field` when a parent has more than
139
+ * one relation to the same child.
140
+ */
141
+ export interface TraverseByModel extends TraverseOptions {
142
+ model: typeof Ad4mModel;
143
+ field?: string;
144
+ }
145
+
146
+ /** Everything a traversal says that is not how it names its predicate. */
147
+ export interface TraverseOptions {
148
+ /** The anchors to walk from. A bare string is the single-anchor spelling. */
149
+ ids: string | string[];
150
+ /**
151
+ * Follow the predicate as far as it goes rather than one step.
152
+ *
153
+ * The result is a flat set of everything reachable, and it does **not**
154
+ * describe the shape it came from: SPARQL property paths bind no intermediate
155
+ * variables, so a row says that it is under the anchor and never where. To
156
+ * rebuild a tree, read the inverse relation (`@BelongsToOne`) alongside it and
157
+ * assemble from the parent each row reports.
158
+ *
159
+ * Excludes every named anchor, not just the one a given row was reached through — a caller
160
+ * naming two anchors where one sits below the other gets neither back, exactly as with `levels`.
161
+ * An anchor is where the read started, not something it found, and that holds in a cycle too.
162
+ *
163
+ * Refused alongside `levels`, which is the bounded form of the same walk.
164
+ */
165
+ transitive?: boolean;
166
+ /**
167
+ * `'out'` (default) matches `anchor --predicate--> result`; `'in'` matches
168
+ * `result --predicate--> anchor`, which is how to *search* among the things
169
+ * pointing at a node — ordered, filtered, limited. A reverse `include`
170
+ * answers the same question for rows already in hand, but cannot narrow them.
171
+ */
172
+ direction?: 'out' | 'in';
173
+ /**
174
+ * Keep at most this many results per anchor — "the top 5 replies under each
175
+ * of these 20 comments" in one query.
176
+ *
177
+ * Applied by the executor between selecting ids and hydrating them, because
178
+ * SPARQL has no per-group limit (no window functions, and sub-SELECTs are
179
+ * uncorrelated). The practical consequence is that the over-fetch is paid in
180
+ * ids, not records: a branch with 3,000 replies costs 3,000 strings and
181
+ * hydrates 5.
182
+ *
183
+ * Pair it with `order` — without one the "top" N is whatever the store
184
+ * happened to return first. A global `limit`/`offset` is applied to the
185
+ * sliced union afterwards, not before it.
186
+ *
187
+ * Refused alongside `levels`, which applies its own per-anchor limit at
188
+ * every depth.
189
+ */
190
+ limitPerAnchor?: number;
191
+ /**
192
+ * Walk the relation level by level, keeping this many results per anchor at each depth —
193
+ * `[10, 5, 3]` is "ten replies, five under each of those, three under each of *those*".
194
+ *
195
+ * The walk happens in the executor, which is the point of it. A caller can drive the same walk by
196
+ * asking for one level and using the ids as the next level's anchors, but each step is then a
197
+ * network round trip, and a UI that draws as each answer lands shows the tree assembling itself a
198
+ * level at a time. Inside the executor the levels are sequential queries against a local store
199
+ * with nothing serialised between them, and the records are hydrated once for the union — so
200
+ * three levels cost one request and one hydration rather than three of each.
201
+ *
202
+ * Results come back flat and breadth-first; read the inverse relation alongside to rebuild the
203
+ * tree, exactly as with `transitive`. The anchors are excluded from their own result, also as
204
+ * with `transitive` — a walk that reaches an anchor again, through a cycle or because one anchor
205
+ * was named below another, reports it at neither place.
206
+ *
207
+ * Each record appears once, under whichever anchor the ordering reaches first — a reply to two
208
+ * of the anchors is one reply, not two. It does not spend a place in the other anchors' breadth
209
+ * either: they fill theirs with replies of their own, so a breadth of five means five distinct
210
+ * records wherever five exist.
211
+ *
212
+ * A global `limit`/`offset` applies to that flat union once, after every level has been cut to
213
+ * its own breadth — not to each level.
214
+ *
215
+ * Combining this with `transitive` or `limitPerAnchor` is an **error**, not a preference the
216
+ * executor resolves: `transitive` is the unbounded form of the same walk, and `limitPerAnchor`
217
+ * has no place to act when the walk sets a per-anchor limit at every depth itself. (It is not a
218
+ * substitute either — with a single anchor at the top there is one group, so it caps the total
219
+ * rather than the breadth at each level.) Put the first level's breadth in `levels[0]`.
220
+ */
221
+ levels?: number[];
222
+ }
223
+
224
+ /**
225
+ * Whether this scope is a traversal rather than a single named parent.
226
+ *
227
+ * The other two forms carry `id`; this one carries `ids` and may name several,
228
+ * so anything reaching for one parent — every write path — has to ask first.
229
+ */
230
+ export function isTraverseScope(scope: Scope): scope is TraverseScope {
231
+ return 'ids' in scope;
232
+ }
71
233
 
72
234
  /**
73
235
  * Describes which relations to eager-load when querying.
@@ -117,6 +279,20 @@ export interface IncludeProjection {
117
279
  from: string;
118
280
  /** When true, attaches an integer count instead of a list. */
119
281
  count?: true;
282
+ /**
283
+ * Project over everything reachable through `from`, not just one step.
284
+ *
285
+ * `{ from: 'comments', count: true, transitive: true }` is the whole
286
+ * conversation under each row rather than its direct replies — which is what
287
+ * a reader takes "42 replies" on a collapsed branch to mean. The projection
288
+ * query is already grouped per parent and already asked of every row at once,
289
+ * so this adds no round trip.
290
+ *
291
+ * Cannot be combined with a filter on the link's author or timestamp: those
292
+ * read the reification of one link, and a path has none. Such a projection is
293
+ * skipped with a warning rather than silently answering a different question.
294
+ */
295
+ transitive?: boolean;
120
296
  /**
121
297
  * Bare class name of the projection target. Set automatically by
122
298
  * `prepareModelQueryParams`; the executor resolves the target's shape
@@ -163,8 +339,110 @@ export type Query = {
163
339
  * queries where getter-backed properties are not needed.
164
340
  */
165
341
  deepQuery?: boolean;
342
+ /**
343
+ * Read instances as they exist in links of one status only.
344
+ *
345
+ * `'shared'` hydrates from Shared links only: every property, relation,
346
+ * `author` and `updatedAt` comes from links that are gossiped to the
347
+ * neighbourhood, and none from this executor's Local links. That is the
348
+ * read to use when showing data to another user (#1024). `'local'` is the
349
+ * converse. Unset or `null` (the default) reads both, and a property
350
+ * declared `local: true` still reads only its Local links.
351
+ *
352
+ * Relations include typed `@HasMany` / `@HasOne` relations, which are filled
353
+ * by the conformance getter the SDK generates: the executor adds the status
354
+ * check to that getter's relation link. A hand-written `getter` is run as
355
+ * written, so it reads links of any status unless it checks
356
+ * `<ad4m://ontology/status>` itself.
357
+ *
358
+ * Included relations and the instances a `$` projection hydrates inherit
359
+ * the setting, unless an include's sub-query sets its own. The `__links`
360
+ * rows (see {@link Query.links}) are restricted the same way.
361
+ *
362
+ * Combines with {@link Query.includeUnverified}: a link must have the
363
+ * requested status **and** pass the signature check, both on the same link.
364
+ * So a Local link whose signature did not verify is withheld under
365
+ * `linkStatus: 'local'` too, and comes back only with
366
+ * `linkStatus: 'local', includeUnverified: true` (or with no `linkStatus`
367
+ * and `includeUnverified: true`).
368
+ *
369
+ * Scope: this restricts the links that hydrate an instance and the links
370
+ * that *select* it (`where`, the class's flags, `count`/`totalCount`, `$`
371
+ * projections, `parent` scopes and the order behind `limit`/`offset`). So an
372
+ * instance is returned under `'local'` only when it is flagged in a Local
373
+ * link, and under `'shared'` only when it is flagged in a Shared one.
374
+ */
375
+ linkStatus?: LinkStatus;
376
+ /**
377
+ * Also hydrate from links whose signature did not verify.
378
+ *
379
+ * By default the executor withholds every link whose stored signature
380
+ * verdict is not valid, so a forged or tampered link never becomes a
381
+ * property value, a relation target, `author` or `updatedAt`. That
382
+ * includes a typed relation's generated conformance getter. A `getter` you
383
+ * write yourself runs as written, so it reads unverified links unless it
384
+ * joins the link's `ad4m://ontology/proofValid` itself. Set this to
385
+ * `true` only to *display* an unverified claim, e.g. a UI that marks a value
386
+ * as unverified. Anything that acts on the data, such as a vote counter or a
387
+ * role check, must leave it off.
388
+ *
389
+ * Included relations inherit the setting unless their sub-query sets its own.
390
+ *
391
+ * The same applies to the rows under `__links` and to what *selects* an
392
+ * instance: `where` (including a per-link `author`), the class's flags,
393
+ * `count`/`totalCount`, the order behind `limit`/`offset`, `parent` scopes
394
+ * and `$` projections, `transitive` ones included. With `true`, selection
395
+ * reads unverified links too.
396
+ */
397
+ includeUnverified?: boolean;
398
+ /**
399
+ * Return the individual links behind each instance, with their own author,
400
+ * timestamp, signature and signature verdict, under `instance.__links`. For
401
+ * a collection this is per-item provenance: who added each member, when, and
402
+ * whether their signature holds.
403
+ *
404
+ * Each entry is a property or relation name the model declares, or an
405
+ * absolute predicate IRI — including one the model does **not** declare
406
+ * (an annotation such as a revocation tombstone). A name wins over the IRI
407
+ * reading. Every requested entry is present on every instance, as `[]` when
408
+ * it has no such link. An entry that is neither a declared name nor an IRI,
409
+ * or that names a reverse relation (`@BelongsToOne` / `@BelongsToMany`),
410
+ * makes the query fail rather than answer `[]`.
411
+ *
412
+ * The rows are read by a second query after the instances are hydrated, so
413
+ * asking for them never changes `createdAt`, `updatedAt` or any property.
414
+ * See {@link LinkRow}.
415
+ */
416
+ links?: string[];
166
417
  };
167
418
 
419
+ /**
420
+ * One stored link as returned under `__links` — the same shape as the
421
+ * `LinkExpression` `perspective.get()` returns, including the signature
422
+ * verdict the executor recorded when the link was stored.
423
+ *
424
+ * `proof.valid` is `true` only when the signature verifies against `author`.
425
+ * A link stored without a proof arrives with `key` and `signature` set to
426
+ * `""` and `valid: false`; that is an unverifiable link, not a valid unsigned
427
+ * one. Anything that acts on a row (counting a vote, granting a role) should
428
+ * require `proof.valid`.
429
+ *
430
+ * `valid` is never `null` here and `invalid` is always `!valid`, the same
431
+ * convention as `perspective.get()`. So `invalid: true` does not by itself mean
432
+ * a signature failed: it also covers a link with no proof, or with no recorded
433
+ * verdict. To tell an unsigned link from a failed signature, check whether
434
+ * `proof.signature` is `""`.
435
+ */
436
+ export interface LinkRow {
437
+ author: string;
438
+ timestamp: string;
439
+ data: { source: string; predicate: string; target: string };
440
+ proof: { key: string; signature: string; valid: boolean; invalid: boolean };
441
+ }
442
+
443
+ /** `instance.__links`: requested entry (spelled as requested) → its rows, oldest first. */
444
+ export type LinksMap = Record<string, LinkRow[]>;
445
+
168
446
  /**
169
447
  * Sub-query options for a specific relation inside an `IncludeMap`.
170
448
  *
@@ -244,6 +522,10 @@ type HasNoTypedFields<T extends Ad4mModel> =
244
522
  export type StringWhereOps = {
245
523
  not?: string | string[];
246
524
  contains?: string;
525
+ /** See {@link WhereOps.eq}. */
526
+ eq?: string | string[];
527
+ /** See {@link WhereOps.author}. */
528
+ author?: AuthorCondition;
247
529
  };
248
530
 
249
531
  export type NumericWhereOps = {
@@ -253,12 +535,16 @@ export type NumericWhereOps = {
253
535
  gt?: number;
254
536
  gte?: number;
255
537
  between?: [number, number];
538
+ /** See {@link WhereOps.eq}. */
539
+ eq?: number | number[];
540
+ /** See {@link WhereOps.author}. */
541
+ author?: AuthorCondition;
256
542
  };
257
543
 
258
544
  export type TypedWhereCondition<V> =
259
545
  V extends string ? string | string[] | StringWhereOps
260
546
  : V extends number ? number | number[] | NumericWhereOps
261
- : V extends boolean ? boolean
547
+ : V extends boolean ? boolean | { eq?: boolean; author?: AuthorCondition }
262
548
  : V extends Array<infer U>
263
549
  ? U extends string ? string | string[] | StringWhereOps
264
550
  : U extends number ? number | number[] | NumericWhereOps
@@ -272,6 +558,13 @@ type StrictTypedWhere<T extends Ad4mModel> =
272
558
  & {
273
559
  base?: string | string[];
274
560
  id?: string | string[];
561
+ /** Alone: the instance's `.author`, i.e. its earliest link's author.
562
+ * Beside property/relation conditions in the same object: that, AND
563
+ * each of those conditions is satisfied by a link this author wrote.
564
+ * For "this author wrote the `agent` link" alone, nest it:
565
+ * `{ agent: { eq: did, author } }`. It does not reach into
566
+ * `OR`/`AND`/`NOT` sub-clauses. See "Filtering by Author" in the
567
+ * model-classes guide. */
275
568
  author?: WhereCondition;
276
569
  timestamp?: WhereCondition;
277
570
  OR?: StrictTypedWhere<T>[];
@@ -284,6 +577,13 @@ type StrictTypedWhere<T extends Ad4mModel> =
284
577
  export type TypedWhere<T extends Ad4mModel> =
285
578
  HasNoTypedFields<T> extends true ? Where : StrictTypedWhere<T>;
286
579
 
580
+ /** Top-level typed `where` of a query on T: {@link TypedWhere} plus
581
+ * `producedByFlow`. Kept out of `TypedWhere` itself because that shape is
582
+ * reused under `OR`/`AND`/`NOT` and in include sub-queries, where the
583
+ * executor rejects `producedByFlow` (see {@link Where.producedByFlow}). */
584
+ export type TypedQueryWhere<T extends Ad4mModel> =
585
+ TypedWhere<T> & { producedByFlow?: ProducedByFlowFilter };
586
+
287
587
  // ---- Typed order -------------------------------------------------------------
288
588
 
289
589
  type StrictTypedOrder<T extends Ad4mModel> =
@@ -304,6 +604,11 @@ export type TypedRelationSubQuery<U extends Ad4mModel> = {
304
604
  include?: TypedIncludeMap<U>;
305
605
  limit?: number;
306
606
  offset?: number;
607
+ /** See {@link Query.linkStatus}. Inherited from the parent query when unset. */
608
+ linkStatus?: LinkStatus;
609
+ /** See {@link Query.includeUnverified}. Inherited from the parent query when unset. */
610
+ includeUnverified?: boolean;
611
+ links?: string[];
307
612
  };
308
613
 
309
614
  /** Projection — `from` must be a real relation on T; `where`/`order` constrained to that target.
@@ -311,9 +616,9 @@ export type TypedRelationSubQuery<U extends Ad4mModel> = {
311
616
  * variants narrow inference into `IncludeExtras` (count → number, limit-1 → scalar). */
312
617
  export type TypedIncludeProjection<T extends Ad4mModel> = {
313
618
  [K in RelationKeysOf<T>]:
314
- | { from: K; count: true }
315
- | { from: K; limit: 1; where?: TypedWhere<RelatedModel<T, K>>; order?: TypedOrder<RelatedModel<T, K>> }
316
- | { from: K; limit?: number; where?: TypedWhere<RelatedModel<T, K>>; order?: TypedOrder<RelatedModel<T, K>> };
619
+ | { from: K; count: true; transitive?: boolean }
620
+ | { from: K; limit: 1; transitive?: boolean; where?: TypedWhere<RelatedModel<T, K>>; order?: TypedOrder<RelatedModel<T, K>> }
621
+ | { from: K; limit?: number; transitive?: boolean; where?: TypedWhere<RelatedModel<T, K>>; order?: TypedOrder<RelatedModel<T, K>> };
317
622
  }[RelationKeysOf<T>];
318
623
 
319
624
  type StrictTypedIncludeMap<T extends Ad4mModel> =
@@ -359,12 +664,17 @@ type StrictTypedQuery<T extends Ad4mModel> = {
359
664
  properties?: PropertyKeysOf<T>[];
360
665
  include?: TypedIncludeMap<T>;
361
666
  includeAll?: boolean;
362
- where?: TypedWhere<T>;
667
+ where?: TypedQueryWhere<T>;
363
668
  order?: TypedOrder<T>;
364
669
  offset?: number;
365
670
  limit?: number;
366
671
  count?: boolean;
367
672
  deepQuery?: boolean;
673
+ /** See {@link Query.linkStatus}. */
674
+ linkStatus?: LinkStatus;
675
+ /** See {@link Query.includeUnverified}. */
676
+ includeUnverified?: boolean;
677
+ links?: string[];
368
678
  };
369
679
 
370
680
  export type TypedQuery<T extends Ad4mModel> =
@@ -244,6 +244,14 @@ export interface AddAutoProcessorConfig {
244
244
  basePrefix?: string;
245
245
  /** Class URIs (SHACL `target_class`) to materialize each pass. */
246
246
  interpretationClasses: string[];
247
+ /**
248
+ * Canonical flow URIs (`SHACLFlow` `{namespace}{name}Flow`) this processor
249
+ * is flow-aware of. Flow features — the flow-aware prompt, the
250
+ * transition-proposal pass, and auto-spawn on freshly created items — run
251
+ * only on the flows listed here, mirroring the class selection above.
252
+ * Omit (or pass `[]`) for no flow processing.
253
+ */
254
+ flows?: string[];
247
255
  /** Quiet-window (ms) after the last new item before a pass runs. */
248
256
  debounceMs: number;
249
257
  /** Minimum items before a pass runs (Flux "wait for N inputs"). Default 1. */