@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
package/lib/index.cjs CHANGED
@@ -783,6 +783,14 @@ class Literal {
783
783
  const numberString = body.substring(7);
784
784
  return parseFloat(numberString);
785
785
  }
786
+ if (body.startsWith("boolean:")) {
787
+ const boolString = decodeURIComponent(body.substring(8));
788
+ if (boolString === "true")
789
+ return true;
790
+ if (boolString === "false")
791
+ return false;
792
+ throw new Error(`Can't parse boolean literal: ${boolString}`);
793
+ }
786
794
  if (body.startsWith("json:")) {
787
795
  const json = body.substring(5);
788
796
  return JSON.parse(decodeURIComponent(json));
@@ -1193,6 +1201,13 @@ class SHACLShape {
1193
1201
  if (prop.writable !== undefined) {
1194
1202
  turtle += ` ad4m:writable ${prop.writable} ;\n`;
1195
1203
  }
1204
+ // Interpreter dedup key: `toLinks()` and `toJSON()` preserve
1205
+ // `identity`; a Turtle export must too or the round-trip through
1206
+ // Turtle silently drops the interpretation-dedup marker
1207
+ // (CodeRabbit #881 review).
1208
+ if (prop.identity !== undefined) {
1209
+ turtle += ` ad4m:identity ${prop.identity} ;\n`;
1210
+ }
1196
1211
  // Remove trailing semicolon and close bracket
1197
1212
  turtle = turtle.slice(0, -2) + '\n';
1198
1213
  turtle += isLast ? ` ] .\n` : ` ] ;\n`;
@@ -1582,10 +1597,15 @@ class SHACLShape {
1582
1597
  val = val.substring(8);
1583
1598
  prop.writable = val === 'true';
1584
1599
  }
1600
+ // The general language selector (e.g. "literal" or a custom address).
1585
1601
  const resolveLangLink = links.find(l => l.source === propShapeId && l.predicate === "ad4m://resolveLanguage");
1586
1602
  if (resolveLangLink) {
1587
1603
  prop.resolveLanguage = resolveLangLink.target.replace(/^literal:\/\/string:|^literal:string:/, '');
1588
1604
  }
1605
+ // Storage mode is derived from `resolveLanguage` alone:
1606
+ // - unset → deterministic typed literal (fast path)
1607
+ // - "literal" → signed envelope on the built-in literal language
1608
+ // - <address> → expression on that custom language
1589
1609
  // Parse action arrays
1590
1610
  const setterLink = links.find(l => l.source === propShapeId && l.predicate === "ad4m://setter");
1591
1611
  if (setterLink) {
@@ -1752,6 +1772,7 @@ class SHACLShape {
1752
1772
  filter: p.filter,
1753
1773
  transform: p.transform,
1754
1774
  interpretation_hint: p.interpretationHint,
1775
+ identity: p.identity,
1755
1776
  })),
1756
1777
  constructor_actions: this.constructor_actions,
1757
1778
  destructor_actions: this.destructor_actions,
@@ -1783,7 +1804,7 @@ class SHACLShape {
1783
1804
  hasValue: p.has_value,
1784
1805
  local: p.local,
1785
1806
  writable: p.writable,
1786
- resolveLanguage: p.resolve_language,
1807
+ resolveLanguage: p.resolve_language ?? p.resolveLanguage,
1787
1808
  setter: p.setter,
1788
1809
  adder: p.adder,
1789
1810
  remover: p.remover,
@@ -1798,6 +1819,7 @@ class SHACLShape {
1798
1819
  filter: p.filter,
1799
1820
  transform: p.transform,
1800
1821
  interpretationHint: p.interpretation_hint,
1822
+ identity: p.identity,
1801
1823
  });
1802
1824
  }
1803
1825
  if (json.constructor_actions) {
@@ -1922,20 +1944,38 @@ interpretationHint) {
1922
1944
  name: propName,
1923
1945
  path: propMeta.through,
1924
1946
  };
1925
- // Determine datatype from initial value or resolveLanguage
1926
- if (propMeta.resolveLanguage === "literal") {
1927
- propShape.datatype = "xsd://string";
1947
+ // Determine datatype from JS field value type; the resolve* options
1948
+ // control storage mode (deterministic vs envelope), not scalar type.
1949
+ // A value stored on the literal language (deterministic or envelope,
1950
+ // i.e. resolveLanguage unset or "literal") gets a string datatype when
1951
+ // no initial value pins a more specific type. A custom resolveLanguage
1952
+ // yields an expression URI, not a literal.
1953
+ //
1954
+ // Skip auto-datatype for properties with a custom `getter` — those
1955
+ // typically return URIs (e.g. `@Optional({ getter: "SELECT ?target ..." })`
1956
+ // that hops through a link to another instance's URI). Autosetting
1957
+ // `sh:datatype xsd:string` there would trip the hydration decode gate
1958
+ // and silently transform `literal:string:<hex>` URIs into their inner
1959
+ // plain-string form on read. Users who want a getter to return literal
1960
+ // values can opt in explicitly by setting `datatype` on the property
1961
+ // options (handled below).
1962
+ if (propMeta.datatype) {
1963
+ // Explicit opt-in from PropertyOptions always wins over inference.
1964
+ propShape.datatype = propMeta.datatype;
1928
1965
  }
1929
- else if (propMeta.initial) {
1930
- const initialType = typeof obj[propName];
1931
- if (initialType === "number") {
1932
- propShape.datatype = "xsd://integer";
1933
- }
1934
- else if (initialType === "boolean") {
1935
- propShape.datatype = "xsd://boolean";
1936
- }
1937
- else if (initialType === "string") {
1938
- propShape.datatype = "xsd://string";
1966
+ else {
1967
+ const isLiteral = propMeta.resolveLanguage === undefined || propMeta.resolveLanguage === "literal";
1968
+ if ((propMeta.initial !== undefined || isLiteral) && !propMeta.getter) {
1969
+ const initialType = typeof obj[propName];
1970
+ if (initialType === "number") {
1971
+ propShape.datatype = "xsd://integer";
1972
+ }
1973
+ else if (initialType === "boolean") {
1974
+ propShape.datatype = "xsd://boolean";
1975
+ }
1976
+ else if (initialType === "string" || isLiteral) {
1977
+ propShape.datatype = "xsd://string";
1978
+ }
1939
1979
  }
1940
1980
  }
1941
1981
  // Cardinality constraints
@@ -2037,8 +2077,19 @@ interpretationHint) {
2037
2077
  name: relName,
2038
2078
  path: synthesizedPath,
2039
2079
  };
2040
- // Relations typically contain IRIs
2041
- relShape.nodeKind = 'IRI';
2080
+ // A relation with a declared `datatype` holds encoded literal
2081
+ // values (e.g. `HasMany<string>` with `datatype: "xsd:string"`).
2082
+ // Everything else is a URI relation pointing at another
2083
+ // instance. The executor uses `sh:datatype` on hydration to
2084
+ // decide whether to decode `literal:<type>:<value>` wire form
2085
+ // (yes for literals, no for URIs).
2086
+ if (relMeta.datatype) {
2087
+ relShape.datatype = relMeta.datatype;
2088
+ relShape.nodeKind = 'Literal';
2089
+ }
2090
+ else {
2091
+ relShape.nodeKind = 'IRI';
2092
+ }
2042
2093
  // Encode relation kind so the executor can derive direction and
2043
2094
  // scalar-vs-collection rendering without consulting the JS class.
2044
2095
  relShape.relationKind = relMeta.kind;
@@ -2462,7 +2513,7 @@ function applyPropertyMetadata(opts) {
2462
2513
  *
2463
2514
  * @description
2464
2515
  * Equivalent to `@Property` but defaults `required` to `false` and does not
2465
- * apply `resolveLanguage` or `initial` defaults. Use this when a property
2516
+ * apply any `initial` defaults. Use this when a property
2466
2517
  * may or may not have a value, and you want full control over its configuration.
2467
2518
  *
2468
2519
  * @example
@@ -2585,8 +2636,7 @@ function Flag(opts) {
2585
2636
  * @Model({ name: "Recipe" })
2586
2637
  * class Recipe extends Ad4mModel {
2587
2638
  * @Property({
2588
- * through: "recipe://name",
2589
- * resolveLanguage: "literal"
2639
+ * through: "recipe://name"
2590
2640
  * })
2591
2641
  * name: string = "";
2592
2642
  *
@@ -2643,7 +2693,9 @@ function Model$1(opts) {
2643
2693
  * Smart defaults (all overridable):
2644
2694
  * - `required` → `false`
2645
2695
  * - `readOnly` → `false`
2646
- * - `resolveLanguage` → `"literal"`
2696
+ * - `resolveLanguage` → unset → deterministic typed literal storage
2697
+ * (the perf default). Set `resolveLanguage: "literal"` for a signed-envelope
2698
+ * value, or a custom language address to resolve through that language.
2647
2699
  * - `initial` → `undefined` (no link created until a value is explicitly set)
2648
2700
  *
2649
2701
  * Properties are optional by default. When a model instance is created without
@@ -2676,7 +2728,8 @@ function Model$1(opts) {
2676
2728
  * })
2677
2729
  * role: string = "";
2678
2730
  *
2679
- * // Optional property with literal resolution
2731
+ * // Optional property with signed-envelope literal storage
2732
+ * // (per-value provenance)
2680
2733
  * @Property({
2681
2734
  * through: "user://bio",
2682
2735
  * resolveLanguage: "literal"
@@ -2689,18 +2742,22 @@ function Model$1(opts) {
2689
2742
  * @param {string} opts.through - The predicate URI for the property
2690
2743
  * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
2691
2744
  * @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
2692
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
2745
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
2693
2746
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
2694
2747
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
2695
2748
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
2696
2749
  */
2697
2750
  function Property(opts) {
2698
2751
  const required = opts.required ?? false;
2752
+ // `resolveLanguage` is intentionally NOT defaulted here.
2753
+ // The effective storage mode is derived from what the user explicitly set:
2754
+ // - unset → deterministic typed literal (the perf default)
2755
+ // - "literal" → signed literal envelope (per-value provenance)
2756
+ // - <custom address> → expression on that custom language
2699
2757
  return applyPropertyMetadata({
2700
2758
  ...opts,
2701
2759
  required,
2702
2760
  readOnly: opts.readOnly ?? false,
2703
- resolveLanguage: opts.resolveLanguage ?? "literal",
2704
2761
  initial: opts.initial ?? (required ? "literal:string:uninitialized" : undefined),
2705
2762
  });
2706
2763
  }
@@ -2755,7 +2812,7 @@ function Property(opts) {
2755
2812
  * @param {PropertyOptions} opts - Property configuration
2756
2813
  * @param {string} opts.through - The predicate URI for the property
2757
2814
  * @param {string} [opts.initial] - Initial value (if property should have one)
2758
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
2815
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
2759
2816
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
2760
2817
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
2761
2818
  */
@@ -2823,6 +2880,7 @@ function HasMany(first, second) {
2823
2880
  ...(opts.getter && { getter: opts.getter }),
2824
2881
  ...(opts.filter !== undefined && { filter: opts.filter }),
2825
2882
  ...(opts.where && { where: opts.where }),
2883
+ ...(opts.datatype && { datatype: opts.datatype }),
2826
2884
  };
2827
2885
  const relKey = key;
2828
2886
  // Only add mutation methods when a predicate is available
@@ -2856,6 +2914,7 @@ function HasOne(first, second) {
2856
2914
  local: opts.local,
2857
2915
  ...(opts.filter !== undefined && { filter: opts.filter }),
2858
2916
  ...(opts.where && { where: opts.where }),
2917
+ ...(opts.datatype && { datatype: opts.datatype }),
2859
2918
  };
2860
2919
  const relKey = key;
2861
2920
  if (opts.through) {
@@ -2896,6 +2955,7 @@ function BelongsToOne(first, second) {
2896
2955
  local: opts.local,
2897
2956
  ...(opts.filter !== undefined && { filter: opts.filter }),
2898
2957
  ...(opts.where && { where: opts.where }),
2958
+ ...(opts.datatype && { datatype: opts.datatype }),
2899
2959
  };
2900
2960
  if (opts.through) {
2901
2961
  // Read-only property (the owning side manages the link)
@@ -2925,6 +2985,7 @@ function BelongsToMany(first, second) {
2925
2985
  ...(opts.getter && { getter: opts.getter }),
2926
2986
  ...(opts.filter !== undefined && { filter: opts.filter }),
2927
2987
  ...(opts.where && { where: opts.where }),
2988
+ ...(opts.datatype && { datatype: opts.datatype }),
2928
2989
  };
2929
2990
  // @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
2930
2991
  // prototype methods. Mutation must go through the owning side's @HasMany decorator.
@@ -3904,6 +3965,16 @@ class PerspectiveProxy {
3904
3965
  async addAutoProcessorEventListener(cb) {
3905
3966
  return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").addAutoProcessorEventListener(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, cb);
3906
3967
  }
3968
+ /**
3969
+ * Subscribe to this perspective's auto-processor neighbourhood-state
3970
+ * events — fires when this executor claims / finishes / abandons a
3971
+ * batch. Perspective-scoped, so a UI can render "someone is
3972
+ * auto-processing this" without receiving the batch payload. See
3973
+ * `AutoProcessorNeighbourhoodStateEvent`.
3974
+ */
3975
+ async addAutoProcessorNeighbourhoodStateListener(cb) {
3976
+ return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").addAutoProcessorNeighbourhoodStateListener(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, cb);
3977
+ }
3907
3978
  /**
3908
3979
  * Executes a Prolog query against the perspective's knowledge base.
3909
3980
  * This is a powerful way to find complex patterns in the graph.
@@ -4776,20 +4847,20 @@ class PerspectiveProxy {
4776
4847
  return null;
4777
4848
  }
4778
4849
  const flowUri = flowUriLinks[0].data.target;
4779
- // Compute alternate prefix for state/transition URIs
4780
- const alternatePrefix = flowUri.endsWith('Flow')
4781
- ? flowUri.slice(0, -4) + '.'
4782
- : flowUri + '.';
4783
- // Fetch flow links using SPARQL to match flowUri source OR alternatePrefix sources
4784
- const sparqlQuery = `SELECT ?s ?p ?o WHERE {
4785
- ?s ?p ?o .
4786
- FILTER(?s = <${flowUri}> || STRSTARTS(STR(?s), "${alternatePrefix}"))
4787
- }`;
4788
- const sparqlResult = await this.querySparql(sparqlQuery);
4789
- const flowLinks = (sparqlResult || []).map((r) => ({
4790
- source: r.s,
4791
- predicate: r.p,
4792
- target: r.o
4850
+ // Fetch flow-level links (hasState, hasTransition, flowable, startAction)
4851
+ const flowLevelLinks = await this.get(new LinkQuery({ source: flowUri }));
4852
+ // Collect state and transition URIs, then fetch their child links
4853
+ const childUris = flowLevelLinks
4854
+ .filter(l => l.data.predicate === "ad4m://hasState"
4855
+ || l.data.predicate === "ad4m://hasTransition")
4856
+ .map(l => l.data.target);
4857
+ const childResults = await Promise.all(childUris.map(uri => this.get(new LinkQuery({ source: uri }))));
4858
+ // Flatten into the {source, predicate, target} shape fromLinks expects
4859
+ const allExprs = [...flowLevelLinks, ...childResults.flat()];
4860
+ const flowLinks = allExprs.map(l => ({
4861
+ source: l.data.source,
4862
+ predicate: l.data.predicate,
4863
+ target: l.data.target
4793
4864
  }));
4794
4865
  return SHACLFlow.fromLinks(flowLinks, flowUri);
4795
4866
  }
@@ -5744,10 +5815,16 @@ class PerspectiveClient {
5744
5815
  * retries on parse failure), so it can legitimately take minutes on slower
5745
5816
  * or CPU-only models. We raise the default 30s RPC timeout here to 20 min
5746
5817
  * (matches the CI `--timeout 1200000` for the interpretation tests).
5818
+ *
5819
+ * `existingScope` and `mintScope` match the AutoProcessor semantics:
5820
+ * `existingScope` constrains the dedup lookup to instances under a
5821
+ * subtree; `mintScope` links every FRESHLY-created base as a child of
5822
+ * `mintScope.id` via its predicate (upserts of pre-existing instances
5823
+ * are NOT re-parented — same rule as the watcher).
5747
5824
  */
5748
- async runInterpretation(uuid, transcript, basePrefix, classes) {
5825
+ async runInterpretation(uuid, transcript, basePrefix, classes, existingScope, mintScope) {
5749
5826
  const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000;
5750
- return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretation', { uuid, transcript, basePrefix, classes }, RUN_INTERPRETATION_TIMEOUT_MS);
5827
+ return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretation', { uuid, transcript, basePrefix, classes, existingScope, mintScope }, RUN_INTERPRETATION_TIMEOUT_MS);
5751
5828
  }
5752
5829
  /**
5753
5830
  * Register a neighbourhood auto-processor on this perspective. The executor's
@@ -5778,6 +5855,11 @@ class PerspectiveClient {
5778
5855
  * Subscribe to auto-processor step signals. `cb` fires for every
5779
5856
  * `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
5780
5857
  * Processed), letting a UI show progress and await the next batch.
5858
+ *
5859
+ * Registered on the per-uuid `#linkUnsubscribers` map so
5860
+ * `PerspectiveProxy.dispose()` → `removeAllListeners(uuid)` cleans the
5861
+ * subscription up; using the global `#unsubscribers` array would leak
5862
+ * callbacks across repeated view lifecycles (CodeRabbit #881 review).
5781
5863
  */
5782
5864
  async addAutoProcessorEventListener(uuid, cb) {
5783
5865
  const unsub = __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").subscribe((data) => {
@@ -5785,7 +5867,28 @@ class PerspectiveClient {
5785
5867
  cb(data);
5786
5868
  }
5787
5869
  });
5788
- __classPrivateFieldGet$9(this, _PerspectiveClient_unsubscribers, "f").push(unsub);
5870
+ let existing = __classPrivateFieldGet$9(this, _PerspectiveClient_linkUnsubscribers, "f").get(uuid) || [];
5871
+ existing.push(unsub);
5872
+ __classPrivateFieldGet$9(this, _PerspectiveClient_linkUnsubscribers, "f").set(uuid, existing);
5873
+ await __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").waitForSubscription();
5874
+ }
5875
+ /**
5876
+ * Subscribe to neighbourhood-state events on a perspective. `cb` fires
5877
+ * when THIS executor claims / finishes / abandons a batch for any
5878
+ * processor on `uuid` — perspective-scoped observability so a UI can
5879
+ * render "someone is auto-processing this" without receiving the batch
5880
+ * payload or LLM I/O. Registered on the per-uuid `#linkUnsubscribers`
5881
+ * map so `PerspectiveProxy.dispose()` sweeps it up.
5882
+ */
5883
+ async addAutoProcessorNeighbourhoodStateListener(uuid, cb) {
5884
+ const unsub = __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").subscribe((data) => {
5885
+ if (data.type === 'auto-processor-neighbourhood-state' && data.perspectiveUuid === uuid) {
5886
+ cb(data);
5887
+ }
5888
+ });
5889
+ let existing = __classPrivateFieldGet$9(this, _PerspectiveClient_linkUnsubscribers, "f").get(uuid) || [];
5890
+ existing.push(unsub);
5891
+ __classPrivateFieldGet$9(this, _PerspectiveClient_linkUnsubscribers, "f").set(uuid, existing);
5789
5892
  await __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").waitForSubscription();
5790
5893
  }
5791
5894
  async addLinkExpression(uuid, link, status = 'shared', batchId) {
@@ -14451,13 +14554,7 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
14451
14554
  }
14452
14555
  else {
14453
14556
  // Handle regular properties
14454
- let resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
14455
- // If no specific resolveLanguage for this property, use the global one
14456
- if (!resolveLanguage && options.resolveLanguage) {
14457
- resolveLanguage = options.resolveLanguage;
14458
- }
14459
14557
  const local = getPropertyOption(propertyName, propertySchema, options, 'local');
14460
- // Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
14461
14558
  let readOnly = getPropertyOption(propertyName, propertySchema, options, 'readOnly');
14462
14559
  if (readOnly === undefined) {
14463
14560
  const xWritable = propertySchema["x-ad4m"]?.writable;
@@ -14465,22 +14562,14 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
14465
14562
  }
14466
14563
  const writable = !readOnly;
14467
14564
  let initial = getPropertyOption(propertyName, propertySchema, options, 'initial');
14468
- // Handle nested objects by serializing to JSON
14469
- if (isObjectType(propertySchema) && !resolveLanguage) {
14470
- resolveLanguage = 'literal';
14565
+ // Not defaulted — absence means "deterministic typed literal" (the
14566
+ // perf default); an explicit `resolveLanguage: "literal"` selects the
14567
+ // signed-envelope path; any other value selects a custom language.
14568
+ // See effectiveLiteralStorage().
14569
+ const resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
14570
+ if (isObjectType(propertySchema)) {
14471
14571
  console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
14472
14572
  }
14473
- // Ensure numeric properties use literal language for correct typing
14474
- if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
14475
- resolveLanguage = 'literal';
14476
- }
14477
- // Default resolveLanguage to 'literal' for all remaining property types,
14478
- // matching the @Property decorator behaviour. Without this, string values
14479
- // stored as literal: URLs are returned unparsed.
14480
- if (resolveLanguage === undefined || resolveLanguage === null) {
14481
- resolveLanguage = 'literal';
14482
- }
14483
- // If property is required, ensure it has an initial value
14484
14573
  if (isRequired && !initial) {
14485
14574
  if (isObjectType(propertySchema)) {
14486
14575
  initial = 'literal:json:{}';
@@ -14493,7 +14582,7 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
14493
14582
  through: predicate,
14494
14583
  required: isRequired,
14495
14584
  writable: writable,
14496
- ...(resolveLanguage && { resolveLanguage }),
14585
+ ...(resolveLanguage !== undefined && { resolveLanguage }),
14497
14586
  ...(local !== undefined && { local }),
14498
14587
  ...(initial && { initial })
14499
14588
  };
@@ -14608,20 +14697,108 @@ function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
14608
14697
  return false;
14609
14698
  }
14610
14699
  /**
14611
- * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
14612
- * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
14613
- * both store values as literal: URIs. Only properties with a non-literal resolveLanguage
14614
- * (e.g. file storage) or flag properties store raw URIs.
14700
+ * Check whether a string value is a well-formed absolute IRI that can be
14701
+ * stored verbatim as a link target (raw `NamedNode`) instead of being
14702
+ * wrapped in a `literal:string:*` URI.
14703
+ *
14704
+ * This mirrors the Rust `is_safe_iri_target` /
14705
+ * `looks_like_absolute_iri` predicate in
14706
+ * `rust-executor/src/perspectives/model_query/utils.rs` and is
14707
+ * **load-bearing**: a value that returns `true` here MUST also be safely
14708
+ * queryable on the Rust side (`validate_iri` gate on the SPARQL
14709
+ * `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
14710
+ * such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
14711
+ * through the write regex, is stored as an invalid `NamedNode`, and
14712
+ * becomes a silent no-match on read.
14713
+ *
14714
+ * Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
14715
+ * same rejection set the Rust `validate_iri` applies: any Unicode
14716
+ * whitespace, C0/C1 control chars, and the SPARQL-breaking characters
14717
+ * `< > { } "`.
14615
14718
  */
14616
- function isLiteralStoredProperty(propMeta) {
14617
- if (propMeta.flag)
14719
+ function looksLikeUri(value) {
14720
+ if (!/^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value))
14618
14721
  return false;
14619
- // If resolveLanguage is set to something other than "literal", it's a language expression URI
14620
- if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal")
14722
+ // Reject anything the Rust-side `validate_iri` rejects so the two
14723
+ // predicates stay in sync. `\s` covers ASCII whitespace *and*
14724
+ // U+00A0/other Unicode whitespace under the default JS regex semantics.
14725
+ if (/[\s<>{}"\u0000-\u001F\u007F-\u009F]/.test(value))
14621
14726
  return false;
14622
- // Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
14623
14727
  return true;
14624
14728
  }
14729
+ /**
14730
+ * Convert a JS value to its literal: IRI form, matching how the Rust executor
14731
+ * stores property values in the default deterministic-literal path
14732
+ * (`resolveLanguage` unset). Strings that already look like URIs are returned
14733
+ * as-is.
14734
+ *
14735
+ * Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
14736
+ * resolve path) can keep their on-disk form aligned with what
14737
+ * `queryToSPARQL()` filters against — otherwise the same value can be
14738
+ * stored as `<literal:string:https%3A...>` from one path while WHERE
14739
+ * builders probe `<https://example.com>` from the other.
14740
+ *
14741
+ * The object/array arm mirrors Rust's `Literal::from_json` in
14742
+ * `perspective_instance.rs::resolve_property_value` (which routes
14743
+ * `Value::Object | Value::Array` through JSON encoding). Without it, JS
14744
+ * would fall through to `String(value)` and turn `{a: 1}` into
14745
+ * `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
14746
+ */
14747
+ function valueToLiteralIri(value) {
14748
+ if (typeof value === 'string') {
14749
+ if (looksLikeUri(value))
14750
+ return value;
14751
+ return Literal.from(value).toUrl();
14752
+ }
14753
+ if (typeof value === 'number') {
14754
+ return Literal.from(value).toUrl();
14755
+ }
14756
+ if (typeof value === 'boolean') {
14757
+ return Literal.from(value).toUrl();
14758
+ }
14759
+ // Objects and arrays: route through Literal.from so we emit
14760
+ // `literal:json:*` (mirrors Rust `Literal::from_json`). Without this
14761
+ // arm we fall through to `String(value)` which turns objects into
14762
+ // `"[object Object]"` and arrays into `"1,2"` — silently storing the
14763
+ // wrong shape and breaking equality filters (`findAll({ where:
14764
+ // { config: {...} } })` would match against `"[object Object]"`).
14765
+ // The `value !== null` guard preserves the historical fallthrough for
14766
+ // `null` (→ `literal:string:null`), since `Literal.from(null).toUrl()`
14767
+ // throws on the empty-literal check.
14768
+ if (value !== null && typeof value === 'object') {
14769
+ return Literal.from(value).toUrl();
14770
+ }
14771
+ return Literal.from(String(value)).toUrl();
14772
+ }
14773
+ /**
14774
+ * Derive the effective storage mode from a property's explicit options.
14775
+ * `resolveLanguage` is the sole selector and is NOT defaulted at the
14776
+ * decorator level:
14777
+ * - unset → deterministic typed literal (the perf default
14778
+ * for a plain `@Property()`)
14779
+ * - `"literal"` → signed envelope on the built-in literal language
14780
+ * (per-value provenance, e.g. Flux message bodies)
14781
+ * - `<custom address>` → signed expression on that custom language
14782
+ */
14783
+ function effectiveLiteralStorage(meta) {
14784
+ const lang = meta.resolveLanguage;
14785
+ if (lang === undefined)
14786
+ return { kind: "deterministic" };
14787
+ if (lang === "literal")
14788
+ return { kind: "envelope" };
14789
+ return { kind: "custom", language: lang };
14790
+ }
14791
+ /**
14792
+ * Determine if a property stores values as deterministic literal: IRIs (so WHERE
14793
+ * filters can match typed literals directly). Envelope / custom-language
14794
+ * properties resolve through expressions, and flag properties store raw URIs —
14795
+ * none is a deterministic literal.
14796
+ */
14797
+ function isLiteralStoredProperty(propMeta) {
14798
+ if (propMeta.flag)
14799
+ return false;
14800
+ return effectiveLiteralStorage(propMeta).kind === "deterministic";
14801
+ }
14625
14802
  /**
14626
14803
  * Escape a string for use as a SPARQL string literal.
14627
14804
  */
@@ -15162,11 +15339,11 @@ class ModelQueryBuilder {
15162
15339
  }
15163
15340
  const field = options?.field;
15164
15341
  if (typeof modelOrPredicate === 'string') {
15165
- // Raw predicate string → raw form of ParentScope
15342
+ // Raw predicate string → raw form of Scope
15166
15343
  this.queryParams.parent = { id, predicate: modelOrPredicate };
15167
15344
  }
15168
15345
  else if (typeof modelOrPredicate === 'function') {
15169
- // Model class → model form of ParentScope
15346
+ // Model class → model form of Scope
15170
15347
  this.queryParams.parent = { id, model: modelOrPredicate, ...(field && { field }) };
15171
15348
  }
15172
15349
  else if (typeof idOrInstance !== 'string') {
@@ -15818,12 +15995,28 @@ function jsonToModelInstance(ModelClass, perspective, json, include, properties)
15818
15995
  * // Define a recipe model
15819
15996
  * @Model({ name: "Recipe" })
15820
15997
  * class Recipe extends Ad4mModel {
15821
- * // Required property with literal value
15998
+ * // Plain property — no `resolveLanguage` → deterministic typed literal
15999
+ * // storage (fast POS-index path). This is the perf default.
16000
+ * @Property({ through: "recipe://name" })
16001
+ * name: string = "";
16002
+ *
16003
+ * // Property that needs per-value provenance (e.g. a signed message body):
16004
+ * // `resolveLanguage: "literal"` routes values through expression_create on
16005
+ * // the built-in literal language, producing a signed envelope URI
16006
+ * // (author/timestamp/proof) instead of a bare typed literal.
15822
16007
  * @Property({
15823
- * through: "recipe://name",
16008
+ * through: "recipe://signed_note",
15824
16009
  * resolveLanguage: "literal"
15825
16010
  * })
15826
- * name: string = "";
16011
+ * signedNote: string = "";
16012
+ *
16013
+ * // Property resolved through a custom language: values are routed through
16014
+ * // expression_create on that language (signed expression URIs).
16015
+ * @Optional({
16016
+ * through: "recipe://photo",
16017
+ * resolveLanguage: "QmFileStorageLanguageAddress..."
16018
+ * })
16019
+ * photo: string = "";
15827
16020
  *
15828
16021
  * // Optional property with custom initial value
15829
16022
  * @Optional({
@@ -15963,7 +16156,7 @@ class Ad4mModel {
15963
16156
  * ```typescript
15964
16157
  * @Model({ name: "Recipe" })
15965
16158
  * class Recipe extends Ad4mModel {
15966
- * @Property({ through: "recipe://name", resolveLanguage: "literal" })
16159
+ * @Property({ through: "recipe://name" })
15967
16160
  * name: string = "";
15968
16161
  *
15969
16162
  * @HasMany({ through: "recipe://ingredient" })
@@ -16052,7 +16245,7 @@ class Ad4mModel {
16052
16245
  predicate: predicate,
16053
16246
  required: isRequired,
16054
16247
  readOnly: propertySchema["x-ad4m"]?.writable === false,
16055
- ...(propertySchema["x-ad4m"]?.resolveLanguage && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
16248
+ ...(propertySchema["x-ad4m"]?.resolveLanguage !== undefined && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
16056
16249
  ...(propertySchema["x-ad4m"]?.initial && { initial: propertySchema["x-ad4m"].initial }),
16057
16250
  ...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
16058
16251
  };
@@ -16071,7 +16264,9 @@ class Ad4mModel {
16071
16264
  *
16072
16265
  * @param perspective - The perspective where this model will be stored
16073
16266
  * @param baseExpression - Optional expression URI for this instance.
16074
- * If omitted, a random Literal URL is generated.
16267
+ * If omitted, a random `ad4m://obj/<id>` IRI is generated,
16268
+ * independent of any property content — this is what keeps
16269
+ * two instances with identical property values distinct.
16075
16270
  * @param source - Optional source expression this instance is linked to
16076
16271
  *
16077
16272
  * @example
@@ -16080,12 +16275,21 @@ class Ad4mModel {
16080
16275
  * const recipe = new Recipe(perspective);
16081
16276
  *
16082
16277
  * // Create with specific base expression
16083
- * const recipe = new Recipe(perspective, "literal:...");
16278
+ * const recipe = new Recipe(perspective, "ad4m://obj/existing-id");
16084
16279
  * ```
16085
16280
  */
16086
16281
  constructor(perspective, baseExpression) {
16087
16282
  this._snapshot = null;
16088
- this._baseExpression = baseExpression ? baseExpression : Literal.from(makeRandomId(24)).toUrl();
16283
+ // Use a dedicated `ad4m://obj/<id>` scheme for auto-generated
16284
+ // baseExpressions instead of `Literal.from(...).toUrl()`'s
16285
+ // `literal:string:<id>`. After typed-literal storage lands, the storage
16286
+ // layer translates any `literal:string:X` target into a typed
16287
+ // `"X"^^xsd:string` literal — which is correct for property values but
16288
+ // wrong for relation targets (which must remain NamedNode IRIs). Using
16289
+ // a distinct scheme keeps auto-generated instance IDs unambiguously
16290
+ // IRIs, so relation links like `<post> --has_comment--> <comment-id>`
16291
+ // round-trip correctly through the SPARQL store.
16292
+ this._baseExpression = baseExpression ? baseExpression : `ad4m://obj/${makeRandomId(24)}`;
16089
16293
  this._perspective = perspective;
16090
16294
  }
16091
16295
  /**
@@ -16647,14 +16851,22 @@ class Ad4mModel {
16647
16851
  }
16648
16852
  // Generate actions from metadata (replaces Prolog query)
16649
16853
  const actions = this.generatePropertySetterAction(key, metadata);
16650
- // Get resolve language from metadata (replaces Prolog query)
16651
- let resolveLanguage = metadata.resolveLanguage;
16652
16854
  // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
16653
16855
  if (value === undefined || value === null || value === "") {
16654
16856
  return;
16655
16857
  }
16656
- if (resolveLanguage) {
16657
- value = await this._perspective.createExpression(value, resolveLanguage);
16858
+ const mode = effectiveLiteralStorage(metadata);
16859
+ if (mode.kind === "custom") {
16860
+ // Custom language: route through expression_create on that language.
16861
+ value = await this._perspective.createExpression(value, mode.language);
16862
+ }
16863
+ else if (mode.kind === "envelope") {
16864
+ // Built-in literal language: signed-envelope expression (provenance).
16865
+ value = await this._perspective.createExpression(value, "literal");
16866
+ }
16867
+ else {
16868
+ // Deterministic literal: IRI (POS-index friendly).
16869
+ value = valueToLiteralIri(value);
16658
16870
  }
16659
16871
  await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value }], batchId);
16660
16872
  }
@@ -16773,41 +16985,30 @@ class Ad4mModel {
16773
16985
  // entirely and let innerUpdate write the links directly.
16774
16986
  const metadata = this.constructor.getModelMetadata();
16775
16987
  const hasConstructor = Object.values(metadata.properties).some((p) => p.required || p.flag || p.initial !== undefined);
16776
- // Track properties that have resolveLanguage (non-literal) so they can be
16777
- // set via setProperty after createSubject (which doesn't resolve languages).
16778
- const deferredResolveLanguageProps = [];
16988
+ // Track properties resolved through expression_create — a signed literal
16989
+ // envelope or a custom (non-"literal") resolveLanguage. These may fail
16990
+ // inside a batch context, so defer them to setProperty after createSubject.
16991
+ const deferredExpressionProps = [];
16779
16992
  if (hasConstructor) {
16780
- // First filter out the properties that are not relations (arrays)
16781
16993
  const initialValues = {};
16782
16994
  for (const [key, value] of Object.entries(this)) {
16783
16995
  if (value !== undefined && value !== null && !(Array.isArray(value) && value.length > 0) && !value?.action) {
16784
- // Check if this property requires language resolution (e.g. file storage).
16785
- // If so, resolve the expression *before* passing to createSubject so
16786
- // the constructor receives a valid URI instead of raw data.
16787
16996
  const propMeta = metadata.properties[key];
16788
- if (propMeta?.resolveLanguage && propMeta.resolveLanguage !== 'literal' && typeof value === 'object') {
16789
- // Defer these properties — they need createExpression which may
16790
- // fail inside a batch context on some languages. We'll set them
16791
- // via setProperty after createSubject.
16792
- deferredResolveLanguageProps.push(key);
16997
+ if (propMeta && effectiveLiteralStorage(propMeta).kind !== "deterministic") {
16998
+ deferredExpressionProps.push(key);
16793
16999
  continue;
16794
17000
  }
16795
17001
  initialValues[key] = value;
16796
17002
  }
16797
17003
  }
16798
- // Get the class name instead of passing the instance to avoid Prolog query generation
16799
17004
  const className = await this.perspective.stringOrTemplateObjectToSubjectClassName(this);
16800
- // Create the subject with the initial values
16801
17005
  await this.perspective.createSubject(className, this._baseExpression, initialValues, batchId);
16802
17006
  }
16803
17007
  // Set properties and relations via innerUpdate.
16804
17008
  // When createSubject was skipped (no constructor actions), we must enable
16805
17009
  // property writing so that scalar values are persisted as links.
16806
17010
  await this.innerUpdate(!hasConstructor, batchId);
16807
- // Now handle any deferred resolveLanguage properties that were excluded
16808
- // from initialValues. setProperty will call createExpression to upload
16809
- // the data to the appropriate language and store the resulting URI.
16810
- for (const key of deferredResolveLanguageProps) {
17011
+ for (const key of deferredExpressionProps) {
16811
17012
  const value = this[key];
16812
17013
  if (value !== undefined && value !== null) {
16813
17014
  await this.setProperty(key, value, batchId);
@@ -17102,7 +17303,7 @@ class Ad4mModel {
17102
17303
  * @param perspective - The perspective to create the instance in
17103
17304
  * @param data - Property values to assign before saving
17104
17305
  * @param options - Optional settings:
17105
- * - `parent` — a `ParentScope` (model form or raw form) whose `id` will
17306
+ * - `parent` — a `Scope` (model form or raw form) whose `id` will
17106
17307
  * be used to create an incoming link from the parent to the new instance.
17107
17308
  * - `batchId` — an existing batch id; when provided the link write and
17108
17309
  * `save()` are added to the batch instead of committed immediately.
@@ -17334,8 +17535,7 @@ class Ad4mModel {
17334
17535
  * // With explicit configuration
17335
17536
  * const PersonClass = Ad4mModel.fromJSONSchema(schema, {
17336
17537
  * name: "Person",
17337
- * namespace: "person://",
17338
- * resolveLanguage: "literal"
17538
+ * namespace: "person://"
17339
17539
  * });
17340
17540
  *
17341
17541
  * // With property mapping
@@ -17752,11 +17952,20 @@ var __metadata = (undefined && undefined.__metadata) || function (k, v) {
17752
17952
  // Mirrors the Rust `auto_processor::config::AutoProcessorConfig` SDNA.
17753
17953
  // One node per registered processor; the node URI is
17754
17954
  // `ad4m://autoprocessor/<processorId>`.
17955
+ // Model name = "AutoProcessor" (NOT "AutoProcessorConfig") to match the Rust
17956
+ // hardwired subject class in `perspectives/auto_processor/config.rs` — that
17957
+ // alignment is what the SDNA parity test in
17958
+ // `tests/js/tests/model/interpretation-models.test.ts` guards. The TS class
17959
+ // symbol keeps the `Config` suffix for readability (`AutoProcessorConfig` reads
17960
+ // better than a bare `AutoProcessor` for an "instances of the config record"
17961
+ // query), but the on-graph subject class it registers is `AutoProcessor`.
17755
17962
  exports.AutoProcessorConfig = class AutoProcessorConfig extends Ad4mModel {
17756
17963
  constructor() {
17757
17964
  super(...arguments);
17758
- this.type = "ad4m://AutoProcessor";
17759
17965
  /** Unique processor id — the dedup key for auto-processor instances. */
17966
+ // First-declared property: `buildSHACL` derives the shape namespace from
17967
+ // its `through` prefix, so `ad4m://processor_id` → `ad4m://` → target_class
17968
+ // `ad4m://AutoProcessor` (matches Rust `AUTO_PROCESSOR_TARGET_CLASS`).
17760
17969
  this.processorId = "";
17761
17970
  /** SPARQL SELECT that gathers source items each pass. */
17762
17971
  this.sourceScopeQuery = "";
@@ -17768,12 +17977,13 @@ exports.AutoProcessorConfig = class AutoProcessorConfig extends Ad4mModel {
17768
17977
  this.batchMax = "32";
17769
17978
  /** How long a won claim is authoritative before peers may re-claim (ms). */
17770
17979
  this.claimTtlMs = "60000";
17980
+ // No `@Flag` type discriminator (Nico 2026-08-19: "type flags are an
17981
+ // anti-pattern for subject classes; match over all the properties
17982
+ // instead"). Conformance is by the presence of `processorId` +
17983
+ // `sourceScopeQuery` + `interpretationClasses` + `debounceMs` +
17984
+ // `batchMax` + `claimTtlMs` — the Rust SDNA takes the same shape.
17771
17985
  }
17772
17986
  };
17773
- __decorate([
17774
- Flag({ through: "rdf://type", value: "ad4m://AutoProcessor" }),
17775
- __metadata("design:type", String)
17776
- ], exports.AutoProcessorConfig.prototype, "type", void 0);
17777
17987
  __decorate([
17778
17988
  Property({ through: "ad4m://processor_id", required: true, identity: true }),
17779
17989
  __metadata("design:type", String)
@@ -17783,11 +17993,11 @@ __decorate([
17783
17993
  __metadata("design:type", String)
17784
17994
  ], exports.AutoProcessorConfig.prototype, "sourceScopeQuery", void 0);
17785
17995
  __decorate([
17786
- Optional({ through: "ad4m://base_prefix", resolveLanguage: "literal" }),
17996
+ Optional({ through: "ad4m://base_prefix" }),
17787
17997
  __metadata("design:type", String)
17788
17998
  ], exports.AutoProcessorConfig.prototype, "basePrefix", void 0);
17789
17999
  __decorate([
17790
- HasMany({ through: "ad4m://interpretation_class" }),
18000
+ HasMany({ through: "ad4m://interpretation_class", datatype: "xsd:string" }),
17791
18001
  __metadata("design:type", Array)
17792
18002
  ], exports.AutoProcessorConfig.prototype, "interpretationClasses", void 0);
17793
18003
  __decorate([
@@ -17795,7 +18005,7 @@ __decorate([
17795
18005
  __metadata("design:type", String)
17796
18006
  ], exports.AutoProcessorConfig.prototype, "debounceMs", void 0);
17797
18007
  __decorate([
17798
- Optional({ through: "ad4m://batch_min", resolveLanguage: "literal" }),
18008
+ Optional({ through: "ad4m://batch_min" }),
17799
18009
  __metadata("design:type", String)
17800
18010
  ], exports.AutoProcessorConfig.prototype, "batchMin", void 0);
17801
18011
  __decorate([
@@ -17803,7 +18013,7 @@ __decorate([
17803
18013
  __metadata("design:type", String)
17804
18014
  ], exports.AutoProcessorConfig.prototype, "batchMax", void 0);
17805
18015
  __decorate([
17806
- Optional({ through: "ad4m://max_wait_ms", resolveLanguage: "literal" }),
18016
+ Optional({ through: "ad4m://max_wait_ms" }),
17807
18017
  __metadata("design:type", String)
17808
18018
  ], exports.AutoProcessorConfig.prototype, "maxWaitMs", void 0);
17809
18019
  __decorate([
@@ -17811,61 +18021,89 @@ __decorate([
17811
18021
  __metadata("design:type", String)
17812
18022
  ], exports.AutoProcessorConfig.prototype, "claimTtlMs", void 0);
17813
18023
  __decorate([
17814
- Optional({ through: "ad4m://source_window_ms", resolveLanguage: "literal" }),
18024
+ Optional({ through: "ad4m://source_window_ms" }),
17815
18025
  __metadata("design:type", String)
17816
18026
  ], exports.AutoProcessorConfig.prototype, "sourceWindowMs", void 0);
17817
18027
  __decorate([
17818
- Optional({ through: "ad4m://dedup_strategy", resolveLanguage: "literal" }),
18028
+ Optional({ through: "ad4m://dedup_strategy" }),
17819
18029
  __metadata("design:type", String)
17820
18030
  ], exports.AutoProcessorConfig.prototype, "dedupStrategy", void 0);
18031
+ __decorate([
18032
+ Optional({ through: "ad4m://existing_scope" }),
18033
+ __metadata("design:type", String)
18034
+ ], exports.AutoProcessorConfig.prototype, "existingScope", void 0);
18035
+ __decorate([
18036
+ Optional({ through: "ad4m://mint_scope" }),
18037
+ __metadata("design:type", String)
18038
+ ], exports.AutoProcessorConfig.prototype, "mintScope", void 0);
18039
+ __decorate([
18040
+ Optional({ through: "ad4m://debug_mode", resolveLanguage: "literal" }),
18041
+ __metadata("design:type", String)
18042
+ ], exports.AutoProcessorConfig.prototype, "debugMode", void 0);
18043
+ __decorate([
18044
+ Optional({ through: "ad4m://persist_debug", resolveLanguage: "literal" }),
18045
+ __metadata("design:type", String)
18046
+ ], exports.AutoProcessorConfig.prototype, "persistDebug", void 0);
18047
+ __decorate([
18048
+ Optional({ through: "ad4m://emit_debug_events", resolveLanguage: "literal" }),
18049
+ __metadata("design:type", String)
18050
+ ], exports.AutoProcessorConfig.prototype, "emitDebugEvents", void 0);
17821
18051
  exports.AutoProcessorConfig = __decorate([
17822
- Model$1({ name: "AutoProcessorConfig" })
18052
+ Model$1({ name: "AutoProcessor" })
17823
18053
  ], exports.AutoProcessorConfig);
17824
18054
  // ── InterpretationRun ───────────────────────────────────────────────────────
17825
18055
  // Mirrors the Rust `interpretation::overlay::InterpretationRun` SDNA.
17826
18056
  // One node per completed pass; the node URI is `ad4m://interp/run/<runId>`.
17827
18057
  exports.InterpretationRun = class InterpretationRun extends Ad4mModel {
17828
18058
  constructor() {
18059
+ // No `@Flag` type discriminator — Rust SDNA drops `ad4m://type` too.
18060
+ // Conformance is by `runId` (identity) — same pattern
18061
+ // `InterpretationOverlay` already uses (`kind` is its discriminator).
17829
18062
  super(...arguments);
17830
- this.type = "ad4m://interpretation-run";
17831
18063
  /** UUID for this run — the dedup key across run nodes. */
17832
18064
  this.runId = "";
17833
18065
  /**
17834
18066
  * Source item IDs consumed by this pass.
17835
18067
  * Stored as multiple links with the same predicate; the processed-turn
17836
- * cursor uses these to avoid re-interpreting a turn.
18068
+ * cursor uses these to avoid re-interpreting a turn. Values are plain
18069
+ * strings (turn hex), so the property opts into `sh:datatype`-gated
18070
+ * literal decoding on hydration.
17837
18071
  */
17838
18072
  this.sources = [];
17839
18073
  }
17840
18074
  };
17841
- __decorate([
17842
- Flag({ through: "ad4m://type", value: "ad4m://interpretation-run" }),
17843
- __metadata("design:type", String)
17844
- ], exports.InterpretationRun.prototype, "type", void 0);
17845
18075
  __decorate([
17846
18076
  Property({ through: "ad4m://interp/run_id", required: true, identity: true }),
17847
18077
  __metadata("design:type", String)
17848
18078
  ], exports.InterpretationRun.prototype, "runId", void 0);
17849
18079
  __decorate([
17850
- Optional({ through: "ad4m://interp/model", resolveLanguage: "literal" }),
18080
+ Optional({ through: "ad4m://interp/model" }),
17851
18081
  __metadata("design:type", String)
17852
18082
  ], exports.InterpretationRun.prototype, "model", void 0);
17853
18083
  __decorate([
17854
- Optional({ through: "ad4m://interp/prompt_version", resolveLanguage: "literal" }),
18084
+ Optional({ through: "ad4m://interp/prompt_version" }),
17855
18085
  __metadata("design:type", String)
17856
18086
  ], exports.InterpretationRun.prototype, "promptVersion", void 0);
17857
18087
  __decorate([
17858
- Optional({ through: "ad4m://interp/ran_at", resolveLanguage: "literal" }),
18088
+ Optional({ through: "ad4m://interp/ran_at" }),
17859
18089
  __metadata("design:type", String)
17860
18090
  ], exports.InterpretationRun.prototype, "ranAt", void 0);
17861
18091
  __decorate([
17862
- Optional({ through: "ad4m://interp/processor", resolveLanguage: "literal" }),
18092
+ Optional({ through: "ad4m://interp/processor" }),
17863
18093
  __metadata("design:type", String)
17864
18094
  ], exports.InterpretationRun.prototype, "processor", void 0);
17865
18095
  __decorate([
17866
- HasMany({ through: "ad4m://interp/sources" }),
18096
+ HasMany({ through: "ad4m://interp/sources", datatype: "xsd:string" }),
17867
18097
  __metadata("design:type", Array)
17868
18098
  ], exports.InterpretationRun.prototype, "sources", void 0);
18099
+ __decorate([
18100
+ Optional({ through: "ad4m://interp/debug_prompt", resolveLanguage: "literal" }),
18101
+ __metadata("design:type", String)
18102
+ ], exports.InterpretationRun.prototype, "debugPrompt", void 0);
18103
+ __decorate([
18104
+ Optional({ through: "ad4m://interp/debug_response", resolveLanguage: "literal" }),
18105
+ __metadata("design:type", String)
18106
+ ], exports.InterpretationRun.prototype, "debugResponse", void 0);
17869
18107
  exports.InterpretationRun = __decorate([
17870
18108
  Model$1({ name: "InterpretationRun" })
17871
18109
  ], exports.InterpretationRun);
@@ -17897,11 +18135,11 @@ exports.InterpretationOverlay = class InterpretationOverlay extends Ad4mModel {
17897
18135
  }
17898
18136
  };
17899
18137
  __decorate([
17900
- Property({ through: "ad4m://interp/kind", required: true, resolveLanguage: "literal" }),
18138
+ Property({ through: "ad4m://interp/kind", required: true }),
17901
18139
  __metadata("design:type", String)
17902
18140
  ], exports.InterpretationOverlay.prototype, "kind", void 0);
17903
18141
  __decorate([
17904
- Optional({ through: "ad4m://interp/run", resolveLanguage: "literal" }),
18142
+ Optional({ through: "ad4m://interp/run" }),
17905
18143
  __metadata("design:type", String)
17906
18144
  ], exports.InterpretationOverlay.prototype, "run", void 0);
17907
18145
  exports.InterpretationOverlay = __decorate([
@@ -17940,23 +18178,74 @@ function parseSparqlCount(result) {
17940
18178
  /**
17941
18179
  * Decode a `Literal`-encoded SPARQL binding back to a plain string.
17942
18180
  *
17943
- * Mirrors Flux's local `parseLit` helper. Returns `''` for `undefined`/empty
17944
- * input. Falls through to the raw value if decoding fails (defensive — the
17945
- * binding may already be a plain string for unwrapped properties).
18181
+ * Returns `''` for `undefined`/empty input. Falls through to the raw value
18182
+ * if decoding fails — bindings against properties resolved through a custom
18183
+ * language are already raw URIs and should pass through unchanged.
18184
+ *
18185
+ * Signed-envelope literals
18186
+ * ------------------------
18187
+ * Properties declared with `resolveLanguage: 'literal'` are written through
18188
+ * the built-in `literal` language, which wraps the value in a signed
18189
+ * expression envelope (`{ author, timestamp, data, proof }`) and encodes
18190
+ * the whole envelope as a `literal:json:` URL — see
18191
+ * `rust-executor/src/languages/mod.rs::expression_create` (literal branch).
18192
+ * On read, `parseLit` unwraps `.data` from that envelope so callers get the
18193
+ * original scalar value instead of the envelope JSON.
18194
+ *
18195
+ * The Channel V refactor moved most scalar properties to deterministic
18196
+ * typed XSD literals which no longer round-trip through this envelope — for
18197
+ * those properties the SPARQL binding is already the lexical form and this
18198
+ * helper decodes to the primitive. Signed-envelope literals still exist
18199
+ * for any property that opts back into `resolveLanguage: 'literal'` (e.g.
18200
+ * per-message provenance for chat bodies), which is why the `.data` unwrap
18201
+ * is preserved here.
18202
+ *
18203
+ * Non-envelope JSON objects (`literal:json:` payloads that are not signed
18204
+ * envelopes) are JSON-stringified for display.
17946
18205
  */
17947
18206
  function parseLit(val) {
17948
18207
  if (val === undefined || val === null || val === '')
17949
18208
  return '';
18209
+ // Fast-path 1: `literal:*` URLs from properties written through the built-in
18210
+ // `literal` language. On Channel V typed-XSD-literal properties, these
18211
+ // decode straight to a primitive; on `resolveLanguage: 'literal'` properties
18212
+ // (per-message provenance in chat/synergy) they decode to a signed-envelope
18213
+ // object we unwrap via `.data`.
17950
18214
  try {
17951
18215
  const result = Literal.fromUrl(val).get();
17952
- if (result && typeof result === 'object') {
17953
- return result.data ?? JSON.stringify(result);
18216
+ if (typeof result === 'object' && result !== null) {
18217
+ const data = result.data;
18218
+ if (typeof data === 'string')
18219
+ return data;
18220
+ return JSON.stringify(result);
17954
18221
  }
17955
18222
  return String(result);
17956
18223
  }
17957
18224
  catch {
17958
- return val;
18225
+ // fall through to plain-JSON envelope detection
18226
+ }
18227
+ // Fast-path 2: envelope stored/returned as a bare JSON string rather than a
18228
+ // `literal:json:*` URL. Depending on the storage backend and query path,
18229
+ // SPARQL bindings for `resolveLanguage: 'literal'` properties can surface
18230
+ // the envelope object directly as its JSON serialisation (Oxigraph typed
18231
+ // xsd:string of the JSON, or a Channel V pass-through) instead of the URL
18232
+ // form. Detect that shape by parsing the string and unwrapping `.data`
18233
+ // when it looks like a signed envelope; anything else passes through
18234
+ // unchanged so plain text (e.g. "just a string") is not corrupted.
18235
+ if (val.length >= 2 && val.charCodeAt(0) === 0x7b /* '{' */) {
18236
+ try {
18237
+ const parsed = JSON.parse(val);
18238
+ if (parsed && typeof parsed === 'object') {
18239
+ const data = parsed.data;
18240
+ if (typeof data === 'string')
18241
+ return data;
18242
+ }
18243
+ }
18244
+ catch {
18245
+ // not JSON — fall through and return the raw value
18246
+ }
17959
18247
  }
18248
+ return val;
17960
18249
  }
17961
18250
  /** Decode a `Literal`-encoded binding to a number. Returns 0 on empty/invalid input. */
17962
18251
  function parseLitNumber(val) {
@@ -18306,16 +18595,21 @@ function formatQueryValue(value) {
18306
18595
  *
18307
18596
  * @param predicate - The predicate URI for the property
18308
18597
  * @param condition - The Where condition value
18309
- * @param opts - Optional settings (e.g. `resolveLanguage`)
18598
+ * @param opts - Optional settings. `isDeterministicLiteral` (default
18599
+ * `true`) selects the direct typed-literal WHERE path.
18600
+ * Set to `false` when the property stores a signed
18601
+ * envelope (`resolveLanguage: "literal"`) or a
18602
+ * custom-language expression — the envelope path unwraps
18603
+ * with `parse_literal` before comparing.
18310
18604
  * @returns A single SPARQL condition string
18311
18605
  */
18312
18606
  function buildWhereCondition(predicate, condition, opts) {
18313
18607
  const escapedPredicate = escapeQueryString(predicate);
18314
- // For literal-resolved properties, we match against the raw IRI (which is a literal: URI)
18315
- // For language-resolved properties, we match against the plain URI
18316
- // For literal-resolved properties, values are stored as IRIs like <literal:string:VALUE>
18317
- // For language-resolved properties, values are plain URIs
18318
- const isLiteral = !opts?.resolveLanguage || opts.resolveLanguage === 'literal';
18608
+ // For deterministic-literal properties, values are stored as typed
18609
+ // literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
18610
+ // IRI form). For envelope / custom-language properties the target is a
18611
+ // signed expression URI; comparisons need to unwrap via `parse_literal`.
18612
+ const isLiteral = opts?.isDeterministicLiteral !== false;
18319
18613
  const varSuffix = opts?.varIndex ?? 0;
18320
18614
  function formatValue(v) {
18321
18615
  if (typeof v === 'string') {
@@ -18424,23 +18718,28 @@ function compileWhereClause(where, metadata) {
18424
18718
  if (['id', 'author', 'timestamp'].includes(propertyName))
18425
18719
  continue;
18426
18720
  let predicate;
18427
- let resolveLanguage;
18721
+ // Storage mode is derived from `resolveLanguage` alone:
18722
+ // - undefined → deterministic typed literal (fast POS-index path)
18723
+ // - "literal" → signed envelope on the literal language
18724
+ // - custom address → expression on that custom language
18725
+ // Envelope and custom-language properties both need the `parse_literal`
18726
+ // unwrap path, so we treat any `resolveLanguage`-carrying property as
18727
+ // non-deterministic here.
18728
+ let isDeterministicLiteral;
18428
18729
  if (metadata) {
18429
18730
  const propMeta = metadata.properties[propertyName];
18430
18731
  if (propMeta) {
18431
18732
  predicate = propMeta.predicate;
18432
- resolveLanguage = propMeta.resolveLanguage;
18733
+ isDeterministicLiteral = propMeta.resolveLanguage === undefined;
18433
18734
  }
18434
18735
  else {
18435
- // Property not found in metadata — treat name as raw predicate URI
18436
18736
  predicate = propertyName;
18437
18737
  }
18438
18738
  }
18439
18739
  else {
18440
- // No metadata — treat name as raw predicate URI
18441
18740
  predicate = propertyName;
18442
18741
  }
18443
- const cond = buildWhereCondition(predicate, condition, { resolveLanguage, varIndex: conditions.length });
18742
+ const cond = buildWhereCondition(predicate, condition, { isDeterministicLiteral, varIndex: conditions.length });
18444
18743
  if (cond) {
18445
18744
  conditions.push(cond);
18446
18745
  }
@@ -18576,7 +18875,7 @@ function fn(iri, args = []) {
18576
18875
  * ```typescript
18577
18876
  * @Property({
18578
18877
  * through: 'we://image',
18579
- * resolveLanguage: FILE_STORAGE_LANGUAGE,
18878
+ * resolveLanguage: 'literal',
18580
18879
  * transform: fileToDataUri,
18581
18880
  * })
18582
18881
  * avatar?: string;
@@ -18705,6 +19004,7 @@ exports.concat = concat;
18705
19004
  exports.createPersistentCache = createPersistentCache;
18706
19005
  exports.determineNamespace = determineNamespace;
18707
19006
  exports.determinePredicate = determinePredicate;
19007
+ exports.effectiveLiteralStorage = effectiveLiteralStorage;
18708
19008
  exports.escapeQueryString = escapeQueryString;
18709
19009
  exports.exists = exists;
18710
19010
  exports.exprRef2String = exprRef2String;
@@ -18733,6 +19033,7 @@ exports.isObjectType = isObjectType;
18733
19033
  exports.isSchemaType = isSchemaType;
18734
19034
  exports.linkEqual = linkEqual;
18735
19035
  exports.literal = literal;
19036
+ exports.looksLikeUri = looksLikeUri;
18736
19037
  exports.normalizeNamespaceString = normalizeNamespaceString;
18737
19038
  exports.normalizeSchemaType = normalizeSchemaType;
18738
19039
  exports.normalizeValue = normalizeValue;
@@ -18748,3 +19049,4 @@ exports.setCachedResult = setCachedResult;
18748
19049
  exports.setPropertyRegistryEntry = setPropertyRegistryEntry;
18749
19050
  exports.setRelationRegistryEntry = setRelationRegistryEntry;
18750
19051
  exports.typeDefsString = typeDefsString;
19052
+ exports.valueToLiteralIri = valueToLiteralIri;