@coasys/ad4m 0.13.0-test-interpretation → 0.13.0-test-interpretation-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 (54) hide show
  1. package/lib/index.cjs +451 -149
  2. package/lib/index.js +449 -150
  3. package/lib/src/Literal.js +8 -0
  4. package/lib/src/generated/api/RunInterpretationRequest.d.ts +16 -0
  5. package/lib/src/model/Ad4mModel.d.ts +28 -11
  6. package/lib/src/model/Ad4mModel.js +57 -35
  7. package/lib/src/model/ModelQueryBuilder.js +2 -2
  8. package/lib/src/model/decorators.d.ts +52 -8
  9. package/lib/src/model/decorators.js +18 -8
  10. package/lib/src/model/json-schema.js +7 -21
  11. package/lib/src/model/query-common.d.ts +2 -2
  12. package/lib/src/model/query-sparql.d.ts +62 -0
  13. package/lib/src/model/query-sparql.js +78 -15
  14. package/lib/src/model/query-utils.d.ts +7 -2
  15. package/lib/src/model/query-utils.js +21 -11
  16. package/lib/src/model/shacl-gen.js +44 -15
  17. package/lib/src/model/types.d.ts +23 -8
  18. package/lib/src/perspectives/AutoProcessor.d.ts +132 -2
  19. package/lib/src/perspectives/InterpretationModels.d.ts +51 -3
  20. package/lib/src/perspectives/InterpretationModels.js +64 -26
  21. package/lib/src/perspectives/PerspectiveClient.d.ts +22 -2
  22. package/lib/src/perspectives/PerspectiveClient.js +35 -3
  23. package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -1
  24. package/lib/src/perspectives/PerspectiveProxy.js +24 -14
  25. package/lib/src/perspectives/SparqlBindings.d.ts +24 -3
  26. package/lib/src/perspectives/SparqlBindings.js +57 -6
  27. package/lib/src/shacl/SHACLShape.d.ts +11 -3
  28. package/lib/src/shacl/SHACLShape.js +15 -1
  29. package/lib/src/shacl/index.d.ts +1 -1
  30. package/lib/src/shacl/index.js +1 -1
  31. package/package.json +2 -2
  32. package/src/Literal.ts +7 -0
  33. package/src/generated/api/RunInterpretationRequest.ts +19 -3
  34. package/src/model/Ad4mModel.test.ts +84 -22
  35. package/src/model/Ad4mModel.ts +61 -41
  36. package/src/model/ModelQueryBuilder.ts +2 -2
  37. package/src/model/decorators.ts +62 -9
  38. package/src/model/json-schema.ts +10 -25
  39. package/src/model/query-common.ts +2 -2
  40. package/src/model/query-sparql.test.ts +114 -13
  41. package/src/model/query-sparql.ts +83 -14
  42. package/src/model/query-utils.ts +22 -12
  43. package/src/model/shacl-gen.ts +42 -13
  44. package/src/model/shacl-roundtrip.test.ts +4 -2
  45. package/src/model/types.ts +23 -8
  46. package/src/perspectives/AutoProcessor.ts +133 -1
  47. package/src/perspectives/InterpretationModels.ts +103 -21
  48. package/src/perspectives/PerspectiveClient.ts +50 -4
  49. package/src/perspectives/PerspectiveProxy.ts +37 -21
  50. package/src/perspectives/SparqlBindings.test.ts +134 -0
  51. package/src/perspectives/SparqlBindings.ts +57 -6
  52. package/src/shacl/SHACLShape.test.ts +56 -4
  53. package/src/shacl/SHACLShape.ts +30 -6
  54. package/src/shacl/index.ts +1 -1
@@ -27,6 +27,68 @@ import type { Where, Query, ModelMetadata } from "./types";
27
27
  * potentially discarding matches beyond the LIMIT.
28
28
  */
29
29
  export declare function hasJsOnlyWhereFilters(metadata: ModelMetadata, allRelationsMetadata: Record<string, RelationMetadataEntry>, where?: Where): boolean;
30
+ /**
31
+ * Check whether a string value is a well-formed absolute IRI that can be
32
+ * stored verbatim as a link target (raw `NamedNode`) instead of being
33
+ * wrapped in a `literal:string:*` URI.
34
+ *
35
+ * This mirrors the Rust `is_safe_iri_target` /
36
+ * `looks_like_absolute_iri` predicate in
37
+ * `rust-executor/src/perspectives/model_query/utils.rs` and is
38
+ * **load-bearing**: a value that returns `true` here MUST also be safely
39
+ * queryable on the Rust side (`validate_iri` gate on the SPARQL
40
+ * `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
41
+ * such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
42
+ * through the write regex, is stored as an invalid `NamedNode`, and
43
+ * becomes a silent no-match on read.
44
+ *
45
+ * Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
46
+ * same rejection set the Rust `validate_iri` applies: any Unicode
47
+ * whitespace, C0/C1 control chars, and the SPARQL-breaking characters
48
+ * `< > { } "`.
49
+ */
50
+ export declare function looksLikeUri(value: string): boolean;
51
+ /**
52
+ * Convert a JS value to its literal: IRI form, matching how the Rust executor
53
+ * stores property values in the default deterministic-literal path
54
+ * (`resolveLanguage` unset). Strings that already look like URIs are returned
55
+ * as-is.
56
+ *
57
+ * Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
58
+ * resolve path) can keep their on-disk form aligned with what
59
+ * `queryToSPARQL()` filters against — otherwise the same value can be
60
+ * stored as `<literal:string:https%3A...>` from one path while WHERE
61
+ * builders probe `<https://example.com>` from the other.
62
+ *
63
+ * The object/array arm mirrors Rust's `Literal::from_json` in
64
+ * `perspective_instance.rs::resolve_property_value` (which routes
65
+ * `Value::Object | Value::Array` through JSON encoding). Without it, JS
66
+ * would fall through to `String(value)` and turn `{a: 1}` into
67
+ * `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
68
+ */
69
+ export declare function valueToLiteralIri(value: any): string;
70
+ /** How a property's value is stored / resolved. */
71
+ export type LiteralStorageMode = {
72
+ kind: "deterministic";
73
+ } | {
74
+ kind: "envelope";
75
+ } | {
76
+ kind: "custom";
77
+ language: string;
78
+ };
79
+ /**
80
+ * Derive the effective storage mode from a property's explicit options.
81
+ * `resolveLanguage` is the sole selector and is NOT defaulted at the
82
+ * decorator level:
83
+ * - unset → deterministic typed literal (the perf default
84
+ * for a plain `@Property()`)
85
+ * - `"literal"` → signed envelope on the built-in literal language
86
+ * (per-value provenance, e.g. Flux message bodies)
87
+ * - `<custom address>` → signed expression on that custom language
88
+ */
89
+ export declare function effectiveLiteralStorage(meta: {
90
+ resolveLanguage?: string;
91
+ }): LiteralStorageMode;
30
92
  /**
31
93
  * Format a value as a SPARQL string literal (double-quoted).
32
94
  */
@@ -70,17 +70,54 @@ export function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
70
70
  return false;
71
71
  }
72
72
  /**
73
- * Check if a string value looks like a URI (has a scheme).
73
+ * Check whether a string value is a well-formed absolute IRI that can be
74
+ * stored verbatim as a link target (raw `NamedNode`) instead of being
75
+ * wrapped in a `literal:string:*` URI.
76
+ *
77
+ * This mirrors the Rust `is_safe_iri_target` /
78
+ * `looks_like_absolute_iri` predicate in
79
+ * `rust-executor/src/perspectives/model_query/utils.rs` and is
80
+ * **load-bearing**: a value that returns `true` here MUST also be safely
81
+ * queryable on the Rust side (`validate_iri` gate on the SPARQL
82
+ * `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
83
+ * such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
84
+ * through the write regex, is stored as an invalid `NamedNode`, and
85
+ * becomes a silent no-match on read.
86
+ *
87
+ * Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
88
+ * same rejection set the Rust `validate_iri` applies: any Unicode
89
+ * whitespace, C0/C1 control chars, and the SPARQL-breaking characters
90
+ * `< > { } "`.
74
91
  */
75
- function looksLikeUri(value) {
76
- return /^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value);
92
+ export function looksLikeUri(value) {
93
+ if (!/^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value))
94
+ return false;
95
+ // Reject anything the Rust-side `validate_iri` rejects so the two
96
+ // predicates stay in sync. `\s` covers ASCII whitespace *and*
97
+ // U+00A0/other Unicode whitespace under the default JS regex semantics.
98
+ if (/[\s<>{}"\u0000-\u001F\u007F-\u009F]/.test(value))
99
+ return false;
100
+ return true;
77
101
  }
78
102
  /**
79
103
  * Convert a JS value to its literal: IRI form, matching how the Rust executor
80
- * stores property values that don't have a resolveLanguage set.
81
- * Strings that already look like URIs are returned as-is.
104
+ * stores property values in the default deterministic-literal path
105
+ * (`resolveLanguage` unset). Strings that already look like URIs are returned
106
+ * as-is.
107
+ *
108
+ * Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
109
+ * resolve path) can keep their on-disk form aligned with what
110
+ * `queryToSPARQL()` filters against — otherwise the same value can be
111
+ * stored as `<literal:string:https%3A...>` from one path while WHERE
112
+ * builders probe `<https://example.com>` from the other.
113
+ *
114
+ * The object/array arm mirrors Rust's `Literal::from_json` in
115
+ * `perspective_instance.rs::resolve_property_value` (which routes
116
+ * `Value::Object | Value::Array` through JSON encoding). Without it, JS
117
+ * would fall through to `String(value)` and turn `{a: 1}` into
118
+ * `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
82
119
  */
83
- function valueToLiteralIri(value) {
120
+ export function valueToLiteralIri(value) {
84
121
  if (typeof value === 'string') {
85
122
  if (looksLikeUri(value))
86
123
  return value;
@@ -92,22 +129,48 @@ function valueToLiteralIri(value) {
92
129
  if (typeof value === 'boolean') {
93
130
  return Literal.from(value).toUrl();
94
131
  }
132
+ // Objects and arrays: route through Literal.from so we emit
133
+ // `literal:json:*` (mirrors Rust `Literal::from_json`). Without this
134
+ // arm we fall through to `String(value)` which turns objects into
135
+ // `"[object Object]"` and arrays into `"1,2"` — silently storing the
136
+ // wrong shape and breaking equality filters (`findAll({ where:
137
+ // { config: {...} } })` would match against `"[object Object]"`).
138
+ // The `value !== null` guard preserves the historical fallthrough for
139
+ // `null` (→ `literal:string:null`), since `Literal.from(null).toUrl()`
140
+ // throws on the empty-literal check.
141
+ if (value !== null && typeof value === 'object') {
142
+ return Literal.from(value).toUrl();
143
+ }
95
144
  return Literal.from(String(value)).toUrl();
96
145
  }
97
146
  /**
98
- * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
99
- * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
100
- * both store values as literal: URIs. Only properties with a non-literal resolveLanguage
101
- * (e.g. file storage) or flag properties store raw URIs.
147
+ * Derive the effective storage mode from a property's explicit options.
148
+ * `resolveLanguage` is the sole selector and is NOT defaulted at the
149
+ * decorator level:
150
+ * - unset → deterministic typed literal (the perf default
151
+ * for a plain `@Property()`)
152
+ * - `"literal"` → signed envelope on the built-in literal language
153
+ * (per-value provenance, e.g. Flux message bodies)
154
+ * - `<custom address>` → signed expression on that custom language
155
+ */
156
+ export function effectiveLiteralStorage(meta) {
157
+ const lang = meta.resolveLanguage;
158
+ if (lang === undefined)
159
+ return { kind: "deterministic" };
160
+ if (lang === "literal")
161
+ return { kind: "envelope" };
162
+ return { kind: "custom", language: lang };
163
+ }
164
+ /**
165
+ * Determine if a property stores values as deterministic literal: IRIs (so WHERE
166
+ * filters can match typed literals directly). Envelope / custom-language
167
+ * properties resolve through expressions, and flag properties store raw URIs —
168
+ * none is a deterministic literal.
102
169
  */
103
170
  function isLiteralStoredProperty(propMeta) {
104
171
  if (propMeta.flag)
105
172
  return false;
106
- // If resolveLanguage is set to something other than "literal", it's a language expression URI
107
- if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal")
108
- return false;
109
- // Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
110
- return true;
173
+ return effectiveLiteralStorage(propMeta).kind === "deterministic";
111
174
  }
112
175
  /**
113
176
  * Escape a string for use as a SPARQL string literal.
@@ -25,11 +25,16 @@ export declare function formatQueryValue(value: any): string;
25
25
  *
26
26
  * @param predicate - The predicate URI for the property
27
27
  * @param condition - The Where condition value
28
- * @param opts - Optional settings (e.g. `resolveLanguage`)
28
+ * @param opts - Optional settings. `isDeterministicLiteral` (default
29
+ * `true`) selects the direct typed-literal WHERE path.
30
+ * Set to `false` when the property stores a signed
31
+ * envelope (`resolveLanguage: "literal"`) or a
32
+ * custom-language expression — the envelope path unwraps
33
+ * with `parse_literal` before comparing.
29
34
  * @returns A single SPARQL condition string
30
35
  */
31
36
  export declare function buildWhereCondition(predicate: string, condition: WhereCondition, opts?: {
32
- resolveLanguage?: string;
37
+ isDeterministicLiteral?: boolean;
33
38
  varIndex?: number;
34
39
  }): string;
35
40
  /**
@@ -46,16 +46,21 @@ export function formatQueryValue(value) {
46
46
  *
47
47
  * @param predicate - The predicate URI for the property
48
48
  * @param condition - The Where condition value
49
- * @param opts - Optional settings (e.g. `resolveLanguage`)
49
+ * @param opts - Optional settings. `isDeterministicLiteral` (default
50
+ * `true`) selects the direct typed-literal WHERE path.
51
+ * Set to `false` when the property stores a signed
52
+ * envelope (`resolveLanguage: "literal"`) or a
53
+ * custom-language expression — the envelope path unwraps
54
+ * with `parse_literal` before comparing.
50
55
  * @returns A single SPARQL condition string
51
56
  */
52
57
  export function buildWhereCondition(predicate, condition, opts) {
53
58
  const escapedPredicate = escapeQueryString(predicate);
54
- // For literal-resolved properties, we match against the raw IRI (which is a literal: URI)
55
- // For language-resolved properties, we match against the plain URI
56
- // For literal-resolved properties, values are stored as IRIs like <literal:string:VALUE>
57
- // For language-resolved properties, values are plain URIs
58
- const isLiteral = !opts?.resolveLanguage || opts.resolveLanguage === 'literal';
59
+ // For deterministic-literal properties, values are stored as typed
60
+ // literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
61
+ // IRI form). For envelope / custom-language properties the target is a
62
+ // signed expression URI; comparisons need to unwrap via `parse_literal`.
63
+ const isLiteral = opts?.isDeterministicLiteral !== false;
59
64
  const varSuffix = opts?.varIndex ?? 0;
60
65
  function formatValue(v) {
61
66
  if (typeof v === 'string') {
@@ -164,23 +169,28 @@ export function compileWhereClause(where, metadata) {
164
169
  if (['id', 'author', 'timestamp'].includes(propertyName))
165
170
  continue;
166
171
  let predicate;
167
- let resolveLanguage;
172
+ // Storage mode is derived from `resolveLanguage` alone:
173
+ // - undefined → deterministic typed literal (fast POS-index path)
174
+ // - "literal" → signed envelope on the literal language
175
+ // - custom address → expression on that custom language
176
+ // Envelope and custom-language properties both need the `parse_literal`
177
+ // unwrap path, so we treat any `resolveLanguage`-carrying property as
178
+ // non-deterministic here.
179
+ let isDeterministicLiteral;
168
180
  if (metadata) {
169
181
  const propMeta = metadata.properties[propertyName];
170
182
  if (propMeta) {
171
183
  predicate = propMeta.predicate;
172
- resolveLanguage = propMeta.resolveLanguage;
184
+ isDeterministicLiteral = propMeta.resolveLanguage === undefined;
173
185
  }
174
186
  else {
175
- // Property not found in metadata — treat name as raw predicate URI
176
187
  predicate = propertyName;
177
188
  }
178
189
  }
179
190
  else {
180
- // No metadata — treat name as raw predicate URI
181
191
  predicate = propertyName;
182
192
  }
183
- const cond = buildWhereCondition(predicate, condition, { resolveLanguage, varIndex: conditions.length });
193
+ const cond = buildWhereCondition(predicate, condition, { isDeterministicLiteral, varIndex: conditions.length });
184
194
  if (cond) {
185
195
  conditions.push(cond);
186
196
  }
@@ -104,20 +104,38 @@ interpretationHint) {
104
104
  name: propName,
105
105
  path: propMeta.through,
106
106
  };
107
- // Determine datatype from initial value or resolveLanguage
108
- if (propMeta.resolveLanguage === "literal") {
109
- propShape.datatype = "xsd://string";
107
+ // Determine datatype from JS field value type; the resolve* options
108
+ // control storage mode (deterministic vs envelope), not scalar type.
109
+ // A value stored on the literal language (deterministic or envelope,
110
+ // i.e. resolveLanguage unset or "literal") gets a string datatype when
111
+ // no initial value pins a more specific type. A custom resolveLanguage
112
+ // yields an expression URI, not a literal.
113
+ //
114
+ // Skip auto-datatype for properties with a custom `getter` — those
115
+ // typically return URIs (e.g. `@Optional({ getter: "SELECT ?target ..." })`
116
+ // that hops through a link to another instance's URI). Autosetting
117
+ // `sh:datatype xsd:string` there would trip the hydration decode gate
118
+ // and silently transform `literal:string:<hex>` URIs into their inner
119
+ // plain-string form on read. Users who want a getter to return literal
120
+ // values can opt in explicitly by setting `datatype` on the property
121
+ // options (handled below).
122
+ if (propMeta.datatype) {
123
+ // Explicit opt-in from PropertyOptions always wins over inference.
124
+ propShape.datatype = propMeta.datatype;
110
125
  }
111
- else if (propMeta.initial) {
112
- const initialType = typeof obj[propName];
113
- if (initialType === "number") {
114
- propShape.datatype = "xsd://integer";
115
- }
116
- else if (initialType === "boolean") {
117
- propShape.datatype = "xsd://boolean";
118
- }
119
- else if (initialType === "string") {
120
- propShape.datatype = "xsd://string";
126
+ else {
127
+ const isLiteral = propMeta.resolveLanguage === undefined || propMeta.resolveLanguage === "literal";
128
+ if ((propMeta.initial !== undefined || isLiteral) && !propMeta.getter) {
129
+ const initialType = typeof obj[propName];
130
+ if (initialType === "number") {
131
+ propShape.datatype = "xsd://integer";
132
+ }
133
+ else if (initialType === "boolean") {
134
+ propShape.datatype = "xsd://boolean";
135
+ }
136
+ else if (initialType === "string" || isLiteral) {
137
+ propShape.datatype = "xsd://string";
138
+ }
121
139
  }
122
140
  }
123
141
  // Cardinality constraints
@@ -219,8 +237,19 @@ interpretationHint) {
219
237
  name: relName,
220
238
  path: synthesizedPath,
221
239
  };
222
- // Relations typically contain IRIs
223
- relShape.nodeKind = 'IRI';
240
+ // A relation with a declared `datatype` holds encoded literal
241
+ // values (e.g. `HasMany<string>` with `datatype: "xsd:string"`).
242
+ // Everything else is a URI relation pointing at another
243
+ // instance. The executor uses `sh:datatype` on hydration to
244
+ // decide whether to decode `literal:<type>:<value>` wire form
245
+ // (yes for literals, no for URIs).
246
+ if (relMeta.datatype) {
247
+ relShape.datatype = relMeta.datatype;
248
+ relShape.nodeKind = 'Literal';
249
+ }
250
+ else {
251
+ relShape.nodeKind = 'IRI';
252
+ }
224
253
  // Encode relation kind so the executor can derive direction and
225
254
  // scalar-vs-collection rendering without consulting the JS class.
226
255
  relShape.relationKind = relMeta.kind;
@@ -32,15 +32,25 @@ export type Order = {
32
32
  [propertyName: string]: "ASC" | "DESC";
33
33
  };
34
34
  /**
35
- * Discriminated union for parent-scoped queries.
35
+ * A named subgraph scope: a parent node + linking predicate.
36
36
  *
37
- * **Model form** (preferred) — predicate auto-resolved from the parent model's
38
- * relation metadata. Use `field` to disambiguate when the parent has multiple
39
- * relations targeting the same child class.
37
+ * Reusable across contexts that need to identify "the subtree under node X
38
+ * linked via predicate P": query-time filtering as a `parent` filter on a
39
+ * `ModelQuery` (the "all Messages belonging to Channel X" case) AND
40
+ * AutoProcessor's `existingScope` / `mintScope` fields — the former
41
+ * constrains dedup lookups; the latter turns each new mint into a child
42
+ * link under the given node.
43
+ *
44
+ * **Model form** (preferred for parent-filter queries) — predicate
45
+ * auto-resolved from the parent model's relation metadata. Use `field` to
46
+ * disambiguate when the parent has multiple relations targeting the same
47
+ * child class. AutoProcessor `mintScope` requires the **Raw form** because
48
+ * only Raw carries an explicit linking predicate; `Model` scopes have no
49
+ * predicate to write.
40
50
  *
41
51
  * **Raw form** — explicit predicate string, no metadata lookup.
42
52
  */
43
- export type ParentScope = {
53
+ export type Scope = {
44
54
  model: typeof Ad4mModel;
45
55
  id: string;
46
56
  field?: string;
@@ -113,7 +123,7 @@ export interface IncludeProjection {
113
123
  export declare function isIncludeProjection(val: unknown): val is IncludeProjection;
114
124
  export type Query = {
115
125
  /** Filter to instances that are the target of a link from a given parent. */
116
- parent?: ParentScope;
126
+ parent?: Scope;
117
127
  properties?: string[];
118
128
  include?: IncludeMap;
119
129
  /**
@@ -272,7 +282,7 @@ export type IncludeExtras<T extends Ad4mModel, I> = I extends Record<string, any
272
282
  } ? (R extends RelationKeysOf<T> ? RelatedModel<T, R>[] : never) : unknown;
273
283
  } : unknown;
274
284
  type StrictTypedQuery<T extends Ad4mModel> = {
275
- parent?: ParentScope;
285
+ parent?: Scope;
276
286
  properties?: PropertyKeysOf<T>[];
277
287
  include?: TypedIncludeMap<T>;
278
288
  includeAll?: boolean;
@@ -323,7 +333,12 @@ export interface PropertyMetadata {
323
333
  readOnly: boolean;
324
334
  /** Initial value if specified */
325
335
  initial?: string;
326
- /** Language for resolution (e.g., "literal") */
336
+ /** Sole selector of storage mode:
337
+ * - unset → deterministic typed literal (fast POS-index
338
+ * path, the default for a plain `@Property()`)
339
+ * - `"literal"` → signed envelope on the built-in literal language
340
+ * - `<custom address>` → expression on that custom language
341
+ */
327
342
  resolveLanguage?: string;
328
343
  /** Custom Prolog getter code */
329
344
  prologGetter?: string;
@@ -1,5 +1,55 @@
1
- /** One step in an auto-processor pass (serde camelCase of the Rust enum). */
2
- export type AutoProcessorStep = "batchReady" | "claimed" | "backedOff" | "awaitingAuthor" | "notCandidate" | "gatheringTranscript" | "runningInterpretation" | "processed" | "shapesMissing" | "emptyTranscript";
1
+ /**
2
+ * Raw form of `Scope` (parent node + linking predicate) — the only variant
3
+ * the WebSocket auto-processor config accepts. `Scope`'s model form
4
+ * (`{ model: typeof Ad4mModel, id, field? }`) references a JS class
5
+ * constructor, which JSON.stringify silently drops, so the executor would
6
+ * receive `{ id }` and the scope would be unresolvable. Client callers who
7
+ * hold a model class should resolve its predicate via
8
+ * `ModelQueryBuilder.buildParentScope()` first and pass the result here.
9
+ */
10
+ export type RawScope = {
11
+ id: string;
12
+ predicate: string;
13
+ };
14
+ /**
15
+ * One step in an auto-processor pass (serde camelCase of the Rust enum).
16
+ *
17
+ * ## Lifecycle (winning peer, emitDebugEvents: true)
18
+ *
19
+ * A pass on the winning executor emits, in order:
20
+ *
21
+ * 1. `batchReady` — debounced batch reached threshold, pass starting
22
+ * 2. `claimed` — this executor won the `try_claim`
23
+ * 3. `gatheringTranscript` — pulling the batch's transcript turns
24
+ * 4. `runningInterpretation` — about to invoke the LLM
25
+ * 5. `llmRequestSent` — prompt built + dispatched; carries `llmInput`
26
+ * (only when `emitDebugEvents: true`)
27
+ * 6. `llmResponseReceived` — LLM response arrived; carries `llmOutput`
28
+ * (only when `emitDebugEvents: true`) — the UI
29
+ * can render "waiting on LLM" between steps 5-6
30
+ * 7. `processed` — pass complete; carries `bases[]` (new/updated
31
+ * instance URIs)
32
+ *
33
+ * ## Lifecycle (losing peer, or short-circuit)
34
+ *
35
+ * - `batchReady` → `backedOff` — another peer claimed the batch first
36
+ * - `batchReady` → `awaitingAuthor` — no author of the batch is online
37
+ * - `batchReady` → `notCandidate` — this peer stood down for an earlier author
38
+ * - `claimed` → `shapesMissing` — a configured class shape hasn't synced
39
+ * - `claimed` → `emptyTranscript` — the batch drained empty
40
+ *
41
+ * ## Payload fields per step
42
+ *
43
+ * All steps carry `perspectiveUuid`, `processorId`, `agentDid`, `itemIds[]`.
44
+ * Additional payload:
45
+ *
46
+ * - `backedOff`, `notCandidate` → `detail` = holder / elected-author DID
47
+ * - `shapesMissing` → `detail` = comma-joined missing class URIs
48
+ * - `llmRequestSent` → `llmInput` = raw prompt
49
+ * - `llmResponseReceived` → `llmOutput` = raw LLM response
50
+ * - `processed` → `bases[]` = new/updated instance URIs
51
+ */
52
+ export type AutoProcessorStep = "batchReady" | "claimed" | "backedOff" | "awaitingAuthor" | "notCandidate" | "gatheringTranscript" | "runningInterpretation" | "llmRequestSent" | "llmResponseReceived" | "processed" | "shapesMissing" | "emptyTranscript";
3
53
  /** A single step-signal from one auto-processor pass on one perspective. */
4
54
  export interface AutoProcessorEvent {
5
55
  type: "auto-processor-event";
@@ -14,6 +64,44 @@ export interface AutoProcessorEvent {
14
64
  bases: string[];
15
65
  /** Free-form context for the step (a holder/elected DID, an error, …). */
16
66
  detail?: string;
67
+ /** Raw LLM prompt this pass fed the model. Present ONLY on
68
+ * `llmRequestSent` events, and only when the processor was configured
69
+ * with `emitDebugEvents: true`. Never carried on `processed`. */
70
+ llmInput?: string;
71
+ /** Raw LLM response this pass received. Present ONLY on
72
+ * `llmResponseReceived` events, and only when the processor was
73
+ * configured with `emitDebugEvents: true`. Never carried on `processed`. */
74
+ llmOutput?: string;
75
+ }
76
+ /**
77
+ * Coarse-grained phase of a neighbourhood-state event.
78
+ *
79
+ * `claimed` — this executor just started a pass.
80
+ * `finished` — the pass completed successfully.
81
+ * `abandoned` — the pass short-circuited (missing shape / empty batch /
82
+ * error); the claim will TTL-expire.
83
+ */
84
+ export type NeighbourhoodPhase = "claimed" | "finished" | "abandoned";
85
+ /**
86
+ * `auto-processor-neighbourhood-state` — perspective-scoped observability
87
+ * event. Fires when THIS executor claims, finishes, or abandons a batch.
88
+ * Anyone with perspective read access sees it, so a UI can render "someone
89
+ * is auto-processing this" without receiving the batch payload or LLM I/O.
90
+ *
91
+ * Cross-executor visibility (peer's claim reaching us via Holochain sync) is
92
+ * NOT covered here; consumers who need that subscribe to `link-added` and
93
+ * filter for the `has_claim` predicate on the shared perspective.
94
+ */
95
+ export interface AutoProcessorNeighbourhoodStateEvent {
96
+ type: "auto-processor-neighbourhood-state";
97
+ perspectiveUuid: string;
98
+ processorId: string;
99
+ /** DID that claimed the batch — the pass owner's DID. */
100
+ claimantDid: string;
101
+ /** SHA-256 hex of the batch's item-id set — merge `claimed` + `finished`
102
+ * for the same key to render a single row in a UI. */
103
+ batchKey: string;
104
+ phase: NeighbourhoodPhase;
17
105
  }
18
106
  /** Configuration for `perspective.addAutoProcessor` (everything but `uuid`). */
19
107
  export interface AddAutoProcessorConfig {
@@ -69,6 +157,48 @@ export interface AddAutoProcessorConfig {
69
157
  * runs.
70
158
  */
71
159
  sourceWindowMs?: number;
160
+ /**
161
+ * Optional parent-scope filter for the dedup lookup: when set, only
162
+ * existing instances of the interpretation classes that live under this
163
+ * scope are candidates for upsert. Omit for the whole-perspective dedup
164
+ * set (pre-scope behaviour). Raw form only — see `RawScope`.
165
+ */
166
+ existingScope?: RawScope;
167
+ /**
168
+ * Optional parent-scope target for newly minted instances: when set,
169
+ * every base URI the pass CREATES is additionally linked as a child of
170
+ * `mintScope.id` via the scope's predicate — turning the SoA-tree
171
+ * "children live under this node" pattern from a URI-prefix convention
172
+ * into an actual graph edge. Upserts of pre-existing instances are NOT
173
+ * linked (would multi-parent unrelated graph state). Raw form only —
174
+ * see `RawScope`; the Rust watcher rejects `Model` scopes at runtime.
175
+ */
176
+ mintScope?: RawScope;
177
+ /**
178
+ * Persist the raw LLM prompt + response on the pass's `InterpretationRun`
179
+ * (`debugPrompt` / `debugResponse`) so a UI can look them up post-hoc.
180
+ * Independent of `emitDebugEvents` — Nico's PR #903 split so a caller
181
+ * can persist without emitting mid-pass events (retrospective inspection
182
+ * only) or emit without persisting (live observability, no graph-sync
183
+ * payload). Default `false` — LLM I/O is 10s of KB per pass and every
184
+ * enabled peer syncs it.
185
+ */
186
+ persistDebug?: boolean;
187
+ /**
188
+ * Emit `LlmRequestSent` and `LlmResponseReceived` `auto-processor-event`s
189
+ * mid-pass, so a subscribed UI can render "waiting on LLM" between
190
+ * prompt-send and response-receive. See `persistDebug` for the split
191
+ * rationale. Default `false`.
192
+ */
193
+ emitDebugEvents?: boolean;
194
+ /**
195
+ * Legacy backwards-compat alias — pre-split callers set `debugMode` as a
196
+ * single coupled flag. When present and both `persistDebug` +
197
+ * `emitDebugEvents` are absent, its value is expanded to both. The two
198
+ * specific fields take precedence when present. Prefer the split fields;
199
+ * this alias is retained so pre-split clients still work.
200
+ */
201
+ debugMode?: boolean;
72
202
  }
73
203
  /**
74
204
  * Raw REST-API response shape for a pending interpretation overlay.
@@ -16,7 +16,6 @@
16
16
  */
17
17
  import { Ad4mModel } from "../model/Ad4mModel";
18
18
  export declare class AutoProcessorConfig extends Ad4mModel {
19
- type: string;
20
19
  /** Unique processor id — the dedup key for auto-processor instances. */
21
20
  processorId: string;
22
21
  /** SPARQL SELECT that gathers source items each pass. */
@@ -39,9 +38,50 @@ export declare class AutoProcessorConfig extends Ad4mModel {
39
38
  sourceWindowMs?: string;
40
39
  /** Serialised `DedupStrategy` JSON (absent = NormalizedString). */
41
40
  dedupStrategy?: string;
41
+ /**
42
+ * Serialised `Scope` JSON (absent = whole-perspective dedup set).
43
+ * Constrains the existing-instance lookup to the subtree rooted at
44
+ * `Scope.id` linked via `Scope.predicate` — the SoA-tree "existing items
45
+ * live under THIS project node" pattern. Stored as an opaque JSON blob
46
+ * because SHACL properties carry no rich-object type-check; the Rust
47
+ * watcher parses it back into `Scope`.
48
+ */
49
+ existingScope?: string;
50
+ /**
51
+ * Serialised `Scope` JSON (absent = mint sites are unlinked). When set,
52
+ * every freshly created base URI gets an additional `Scope.id
53
+ * --Scope.predicate--> new-uri` link written into the perspective, so
54
+ * mints become first-class children of the target scope. Must be the
55
+ * `Raw` form of `Scope`; `Model` scopes carry no linking predicate.
56
+ */
57
+ mintScope?: string;
58
+ /**
59
+ * Legacy coupled debug knob (`"true"` / `"false"` string). Reserved as a
60
+ * backwards-compat scalar: pre-split writes used it as the single flag
61
+ * for both LLM I/O persistence AND mid-pass event emission. The Rust
62
+ * loader still reads it as a fallback when the specific `persistDebug`
63
+ * / `emitDebugEvents` fields are absent. New writes SHOULD prefer the
64
+ * split fields (below); this alias is retained so a pre-split peer's
65
+ * config still loads with the coupled behaviour it originally requested.
66
+ */
67
+ debugMode?: string;
68
+ /**
69
+ * Persist the raw LLM prompt + response on the pass's `InterpretationRun`
70
+ * (`debugPrompt` / `debugResponse`). Independent of `emitDebugEvents`
71
+ * — Nico's PR #903 split. Absent = fall back to legacy `debugMode` (see
72
+ * above); when both are absent, defaults to `"false"`.
73
+ */
74
+ persistDebug?: string;
75
+ /**
76
+ * Emit `LlmRequestSent` and `LlmResponseReceived` auto-processor events
77
+ * mid-pass, so a subscribed UI can render "waiting on LLM" between
78
+ * prompt-send and response-receive. Independent of `persistDebug`.
79
+ * Absent = fall back to legacy `debugMode`; when both are absent,
80
+ * defaults to `"false"`.
81
+ */
82
+ emitDebugEvents?: string;
42
83
  }
43
84
  export declare class InterpretationRun extends Ad4mModel {
44
- type: string;
45
85
  /** UUID for this run — the dedup key across run nodes. */
46
86
  runId: string;
47
87
  /** LLM model id used for this run. */
@@ -55,9 +95,17 @@ export declare class InterpretationRun extends Ad4mModel {
55
95
  /**
56
96
  * Source item IDs consumed by this pass.
57
97
  * Stored as multiple links with the same predicate; the processed-turn
58
- * cursor uses these to avoid re-interpreting a turn.
98
+ * cursor uses these to avoid re-interpreting a turn. Values are plain
99
+ * strings (turn hex), so the property opts into `sh:datatype`-gated
100
+ * literal decoding on hydration.
59
101
  */
60
102
  sources: string[];
103
+ /** Raw LLM prompt this pass fed the model. Present only when the pass's
104
+ * AutoProcessor had `persistDebug: true` (or the legacy `debugMode: true`
105
+ * fallback). Absent by default. */
106
+ debugPrompt?: string;
107
+ /** Raw LLM response this pass received. Same rules as `debugPrompt`. */
108
+ debugResponse?: string;
61
109
  }
62
110
  export declare class InterpretationOverlay extends Ad4mModel {
63
111
  /**