@coasys/ad4m 0.13.0-test-interpretation-1 → 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 +449 -149
  2. package/lib/index.js +447 -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 +13 -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 +30 -4
  53. package/src/shacl/SHACLShape.ts +28 -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) {
@@ -1784,7 +1804,7 @@ class SHACLShape {
1784
1804
  hasValue: p.has_value,
1785
1805
  local: p.local,
1786
1806
  writable: p.writable,
1787
- resolveLanguage: p.resolve_language,
1807
+ resolveLanguage: p.resolve_language ?? p.resolveLanguage,
1788
1808
  setter: p.setter,
1789
1809
  adder: p.adder,
1790
1810
  remover: p.remover,
@@ -1924,20 +1944,38 @@ interpretationHint) {
1924
1944
  name: propName,
1925
1945
  path: propMeta.through,
1926
1946
  };
1927
- // Determine datatype from initial value or resolveLanguage
1928
- if (propMeta.resolveLanguage === "literal") {
1929
- 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;
1930
1965
  }
1931
- else if (propMeta.initial) {
1932
- const initialType = typeof obj[propName];
1933
- if (initialType === "number") {
1934
- propShape.datatype = "xsd://integer";
1935
- }
1936
- else if (initialType === "boolean") {
1937
- propShape.datatype = "xsd://boolean";
1938
- }
1939
- else if (initialType === "string") {
1940
- 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
+ }
1941
1979
  }
1942
1980
  }
1943
1981
  // Cardinality constraints
@@ -2039,8 +2077,19 @@ interpretationHint) {
2039
2077
  name: relName,
2040
2078
  path: synthesizedPath,
2041
2079
  };
2042
- // Relations typically contain IRIs
2043
- 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
+ }
2044
2093
  // Encode relation kind so the executor can derive direction and
2045
2094
  // scalar-vs-collection rendering without consulting the JS class.
2046
2095
  relShape.relationKind = relMeta.kind;
@@ -2464,7 +2513,7 @@ function applyPropertyMetadata(opts) {
2464
2513
  *
2465
2514
  * @description
2466
2515
  * Equivalent to `@Property` but defaults `required` to `false` and does not
2467
- * apply `resolveLanguage` or `initial` defaults. Use this when a property
2516
+ * apply any `initial` defaults. Use this when a property
2468
2517
  * may or may not have a value, and you want full control over its configuration.
2469
2518
  *
2470
2519
  * @example
@@ -2587,8 +2636,7 @@ function Flag(opts) {
2587
2636
  * @Model({ name: "Recipe" })
2588
2637
  * class Recipe extends Ad4mModel {
2589
2638
  * @Property({
2590
- * through: "recipe://name",
2591
- * resolveLanguage: "literal"
2639
+ * through: "recipe://name"
2592
2640
  * })
2593
2641
  * name: string = "";
2594
2642
  *
@@ -2645,7 +2693,9 @@ function Model$1(opts) {
2645
2693
  * Smart defaults (all overridable):
2646
2694
  * - `required` → `false`
2647
2695
  * - `readOnly` → `false`
2648
- * - `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.
2649
2699
  * - `initial` → `undefined` (no link created until a value is explicitly set)
2650
2700
  *
2651
2701
  * Properties are optional by default. When a model instance is created without
@@ -2678,7 +2728,8 @@ function Model$1(opts) {
2678
2728
  * })
2679
2729
  * role: string = "";
2680
2730
  *
2681
- * // Optional property with literal resolution
2731
+ * // Optional property with signed-envelope literal storage
2732
+ * // (per-value provenance)
2682
2733
  * @Property({
2683
2734
  * through: "user://bio",
2684
2735
  * resolveLanguage: "literal"
@@ -2691,18 +2742,22 @@ function Model$1(opts) {
2691
2742
  * @param {string} opts.through - The predicate URI for the property
2692
2743
  * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
2693
2744
  * @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
2694
- * @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
2695
2746
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
2696
2747
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
2697
2748
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
2698
2749
  */
2699
2750
  function Property(opts) {
2700
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
2701
2757
  return applyPropertyMetadata({
2702
2758
  ...opts,
2703
2759
  required,
2704
2760
  readOnly: opts.readOnly ?? false,
2705
- resolveLanguage: opts.resolveLanguage ?? "literal",
2706
2761
  initial: opts.initial ?? (required ? "literal:string:uninitialized" : undefined),
2707
2762
  });
2708
2763
  }
@@ -2757,7 +2812,7 @@ function Property(opts) {
2757
2812
  * @param {PropertyOptions} opts - Property configuration
2758
2813
  * @param {string} opts.through - The predicate URI for the property
2759
2814
  * @param {string} [opts.initial] - Initial value (if property should have one)
2760
- * @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
2761
2816
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
2762
2817
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
2763
2818
  */
@@ -2825,6 +2880,7 @@ function HasMany(first, second) {
2825
2880
  ...(opts.getter && { getter: opts.getter }),
2826
2881
  ...(opts.filter !== undefined && { filter: opts.filter }),
2827
2882
  ...(opts.where && { where: opts.where }),
2883
+ ...(opts.datatype && { datatype: opts.datatype }),
2828
2884
  };
2829
2885
  const relKey = key;
2830
2886
  // Only add mutation methods when a predicate is available
@@ -2858,6 +2914,7 @@ function HasOne(first, second) {
2858
2914
  local: opts.local,
2859
2915
  ...(opts.filter !== undefined && { filter: opts.filter }),
2860
2916
  ...(opts.where && { where: opts.where }),
2917
+ ...(opts.datatype && { datatype: opts.datatype }),
2861
2918
  };
2862
2919
  const relKey = key;
2863
2920
  if (opts.through) {
@@ -2898,6 +2955,7 @@ function BelongsToOne(first, second) {
2898
2955
  local: opts.local,
2899
2956
  ...(opts.filter !== undefined && { filter: opts.filter }),
2900
2957
  ...(opts.where && { where: opts.where }),
2958
+ ...(opts.datatype && { datatype: opts.datatype }),
2901
2959
  };
2902
2960
  if (opts.through) {
2903
2961
  // Read-only property (the owning side manages the link)
@@ -2927,6 +2985,7 @@ function BelongsToMany(first, second) {
2927
2985
  ...(opts.getter && { getter: opts.getter }),
2928
2986
  ...(opts.filter !== undefined && { filter: opts.filter }),
2929
2987
  ...(opts.where && { where: opts.where }),
2988
+ ...(opts.datatype && { datatype: opts.datatype }),
2930
2989
  };
2931
2990
  // @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
2932
2991
  // prototype methods. Mutation must go through the owning side's @HasMany decorator.
@@ -3906,6 +3965,16 @@ class PerspectiveProxy {
3906
3965
  async addAutoProcessorEventListener(cb) {
3907
3966
  return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").addAutoProcessorEventListener(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, cb);
3908
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
+ }
3909
3978
  /**
3910
3979
  * Executes a Prolog query against the perspective's knowledge base.
3911
3980
  * This is a powerful way to find complex patterns in the graph.
@@ -4778,20 +4847,20 @@ class PerspectiveProxy {
4778
4847
  return null;
4779
4848
  }
4780
4849
  const flowUri = flowUriLinks[0].data.target;
4781
- // Compute alternate prefix for state/transition URIs
4782
- const alternatePrefix = flowUri.endsWith('Flow')
4783
- ? flowUri.slice(0, -4) + '.'
4784
- : flowUri + '.';
4785
- // Fetch flow links using SPARQL to match flowUri source OR alternatePrefix sources
4786
- const sparqlQuery = `SELECT ?s ?p ?o WHERE {
4787
- ?s ?p ?o .
4788
- FILTER(?s = <${flowUri}> || STRSTARTS(STR(?s), "${alternatePrefix}"))
4789
- }`;
4790
- const sparqlResult = await this.querySparql(sparqlQuery);
4791
- const flowLinks = (sparqlResult || []).map((r) => ({
4792
- source: r.s,
4793
- predicate: r.p,
4794
- 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
4795
4864
  }));
4796
4865
  return SHACLFlow.fromLinks(flowLinks, flowUri);
4797
4866
  }
@@ -5746,10 +5815,16 @@ class PerspectiveClient {
5746
5815
  * retries on parse failure), so it can legitimately take minutes on slower
5747
5816
  * or CPU-only models. We raise the default 30s RPC timeout here to 20 min
5748
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).
5749
5824
  */
5750
- async runInterpretation(uuid, transcript, basePrefix, classes) {
5825
+ async runInterpretation(uuid, transcript, basePrefix, classes, existingScope, mintScope) {
5751
5826
  const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000;
5752
- 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);
5753
5828
  }
5754
5829
  /**
5755
5830
  * Register a neighbourhood auto-processor on this perspective. The executor's
@@ -5780,6 +5855,11 @@ class PerspectiveClient {
5780
5855
  * Subscribe to auto-processor step signals. `cb` fires for every
5781
5856
  * `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
5782
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).
5783
5863
  */
5784
5864
  async addAutoProcessorEventListener(uuid, cb) {
5785
5865
  const unsub = __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").subscribe((data) => {
@@ -5787,7 +5867,28 @@ class PerspectiveClient {
5787
5867
  cb(data);
5788
5868
  }
5789
5869
  });
5790
- __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);
5791
5892
  await __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").waitForSubscription();
5792
5893
  }
5793
5894
  async addLinkExpression(uuid, link, status = 'shared', batchId) {
@@ -14453,13 +14554,7 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
14453
14554
  }
14454
14555
  else {
14455
14556
  // Handle regular properties
14456
- let resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
14457
- // If no specific resolveLanguage for this property, use the global one
14458
- if (!resolveLanguage && options.resolveLanguage) {
14459
- resolveLanguage = options.resolveLanguage;
14460
- }
14461
14557
  const local = getPropertyOption(propertyName, propertySchema, options, 'local');
14462
- // Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
14463
14558
  let readOnly = getPropertyOption(propertyName, propertySchema, options, 'readOnly');
14464
14559
  if (readOnly === undefined) {
14465
14560
  const xWritable = propertySchema["x-ad4m"]?.writable;
@@ -14467,22 +14562,14 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
14467
14562
  }
14468
14563
  const writable = !readOnly;
14469
14564
  let initial = getPropertyOption(propertyName, propertySchema, options, 'initial');
14470
- // Handle nested objects by serializing to JSON
14471
- if (isObjectType(propertySchema) && !resolveLanguage) {
14472
- 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)) {
14473
14571
  console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
14474
14572
  }
14475
- // Ensure numeric properties use literal language for correct typing
14476
- if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
14477
- resolveLanguage = 'literal';
14478
- }
14479
- // Default resolveLanguage to 'literal' for all remaining property types,
14480
- // matching the @Property decorator behaviour. Without this, string values
14481
- // stored as literal: URLs are returned unparsed.
14482
- if (resolveLanguage === undefined || resolveLanguage === null) {
14483
- resolveLanguage = 'literal';
14484
- }
14485
- // If property is required, ensure it has an initial value
14486
14573
  if (isRequired && !initial) {
14487
14574
  if (isObjectType(propertySchema)) {
14488
14575
  initial = 'literal:json:{}';
@@ -14495,7 +14582,7 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
14495
14582
  through: predicate,
14496
14583
  required: isRequired,
14497
14584
  writable: writable,
14498
- ...(resolveLanguage && { resolveLanguage }),
14585
+ ...(resolveLanguage !== undefined && { resolveLanguage }),
14499
14586
  ...(local !== undefined && { local }),
14500
14587
  ...(initial && { initial })
14501
14588
  };
@@ -14610,20 +14697,108 @@ function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
14610
14697
  return false;
14611
14698
  }
14612
14699
  /**
14613
- * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
14614
- * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
14615
- * both store values as literal: URIs. Only properties with a non-literal resolveLanguage
14616
- * (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
+ * `< > { } "`.
14617
14718
  */
14618
- function isLiteralStoredProperty(propMeta) {
14619
- if (propMeta.flag)
14719
+ function looksLikeUri(value) {
14720
+ if (!/^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value))
14620
14721
  return false;
14621
- // If resolveLanguage is set to something other than "literal", it's a language expression URI
14622
- 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))
14623
14726
  return false;
14624
- // Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
14625
14727
  return true;
14626
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
+ }
14627
14802
  /**
14628
14803
  * Escape a string for use as a SPARQL string literal.
14629
14804
  */
@@ -15164,11 +15339,11 @@ class ModelQueryBuilder {
15164
15339
  }
15165
15340
  const field = options?.field;
15166
15341
  if (typeof modelOrPredicate === 'string') {
15167
- // Raw predicate string → raw form of ParentScope
15342
+ // Raw predicate string → raw form of Scope
15168
15343
  this.queryParams.parent = { id, predicate: modelOrPredicate };
15169
15344
  }
15170
15345
  else if (typeof modelOrPredicate === 'function') {
15171
- // Model class → model form of ParentScope
15346
+ // Model class → model form of Scope
15172
15347
  this.queryParams.parent = { id, model: modelOrPredicate, ...(field && { field }) };
15173
15348
  }
15174
15349
  else if (typeof idOrInstance !== 'string') {
@@ -15820,12 +15995,28 @@ function jsonToModelInstance(ModelClass, perspective, json, include, properties)
15820
15995
  * // Define a recipe model
15821
15996
  * @Model({ name: "Recipe" })
15822
15997
  * class Recipe extends Ad4mModel {
15823
- * // 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.
15824
16007
  * @Property({
15825
- * through: "recipe://name",
16008
+ * through: "recipe://signed_note",
15826
16009
  * resolveLanguage: "literal"
15827
16010
  * })
15828
- * 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 = "";
15829
16020
  *
15830
16021
  * // Optional property with custom initial value
15831
16022
  * @Optional({
@@ -15965,7 +16156,7 @@ class Ad4mModel {
15965
16156
  * ```typescript
15966
16157
  * @Model({ name: "Recipe" })
15967
16158
  * class Recipe extends Ad4mModel {
15968
- * @Property({ through: "recipe://name", resolveLanguage: "literal" })
16159
+ * @Property({ through: "recipe://name" })
15969
16160
  * name: string = "";
15970
16161
  *
15971
16162
  * @HasMany({ through: "recipe://ingredient" })
@@ -16054,7 +16245,7 @@ class Ad4mModel {
16054
16245
  predicate: predicate,
16055
16246
  required: isRequired,
16056
16247
  readOnly: propertySchema["x-ad4m"]?.writable === false,
16057
- ...(propertySchema["x-ad4m"]?.resolveLanguage && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
16248
+ ...(propertySchema["x-ad4m"]?.resolveLanguage !== undefined && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
16058
16249
  ...(propertySchema["x-ad4m"]?.initial && { initial: propertySchema["x-ad4m"].initial }),
16059
16250
  ...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
16060
16251
  };
@@ -16073,7 +16264,9 @@ class Ad4mModel {
16073
16264
  *
16074
16265
  * @param perspective - The perspective where this model will be stored
16075
16266
  * @param baseExpression - Optional expression URI for this instance.
16076
- * 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.
16077
16270
  * @param source - Optional source expression this instance is linked to
16078
16271
  *
16079
16272
  * @example
@@ -16082,12 +16275,21 @@ class Ad4mModel {
16082
16275
  * const recipe = new Recipe(perspective);
16083
16276
  *
16084
16277
  * // Create with specific base expression
16085
- * const recipe = new Recipe(perspective, "literal:...");
16278
+ * const recipe = new Recipe(perspective, "ad4m://obj/existing-id");
16086
16279
  * ```
16087
16280
  */
16088
16281
  constructor(perspective, baseExpression) {
16089
16282
  this._snapshot = null;
16090
- 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)}`;
16091
16293
  this._perspective = perspective;
16092
16294
  }
16093
16295
  /**
@@ -16649,14 +16851,22 @@ class Ad4mModel {
16649
16851
  }
16650
16852
  // Generate actions from metadata (replaces Prolog query)
16651
16853
  const actions = this.generatePropertySetterAction(key, metadata);
16652
- // Get resolve language from metadata (replaces Prolog query)
16653
- let resolveLanguage = metadata.resolveLanguage;
16654
16854
  // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
16655
16855
  if (value === undefined || value === null || value === "") {
16656
16856
  return;
16657
16857
  }
16658
- if (resolveLanguage) {
16659
- 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);
16660
16870
  }
16661
16871
  await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value }], batchId);
16662
16872
  }
@@ -16775,41 +16985,30 @@ class Ad4mModel {
16775
16985
  // entirely and let innerUpdate write the links directly.
16776
16986
  const metadata = this.constructor.getModelMetadata();
16777
16987
  const hasConstructor = Object.values(metadata.properties).some((p) => p.required || p.flag || p.initial !== undefined);
16778
- // Track properties that have resolveLanguage (non-literal) so they can be
16779
- // set via setProperty after createSubject (which doesn't resolve languages).
16780
- 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 = [];
16781
16992
  if (hasConstructor) {
16782
- // First filter out the properties that are not relations (arrays)
16783
16993
  const initialValues = {};
16784
16994
  for (const [key, value] of Object.entries(this)) {
16785
16995
  if (value !== undefined && value !== null && !(Array.isArray(value) && value.length > 0) && !value?.action) {
16786
- // Check if this property requires language resolution (e.g. file storage).
16787
- // If so, resolve the expression *before* passing to createSubject so
16788
- // the constructor receives a valid URI instead of raw data.
16789
16996
  const propMeta = metadata.properties[key];
16790
- if (propMeta?.resolveLanguage && propMeta.resolveLanguage !== 'literal' && typeof value === 'object') {
16791
- // Defer these properties — they need createExpression which may
16792
- // fail inside a batch context on some languages. We'll set them
16793
- // via setProperty after createSubject.
16794
- deferredResolveLanguageProps.push(key);
16997
+ if (propMeta && effectiveLiteralStorage(propMeta).kind !== "deterministic") {
16998
+ deferredExpressionProps.push(key);
16795
16999
  continue;
16796
17000
  }
16797
17001
  initialValues[key] = value;
16798
17002
  }
16799
17003
  }
16800
- // Get the class name instead of passing the instance to avoid Prolog query generation
16801
17004
  const className = await this.perspective.stringOrTemplateObjectToSubjectClassName(this);
16802
- // Create the subject with the initial values
16803
17005
  await this.perspective.createSubject(className, this._baseExpression, initialValues, batchId);
16804
17006
  }
16805
17007
  // Set properties and relations via innerUpdate.
16806
17008
  // When createSubject was skipped (no constructor actions), we must enable
16807
17009
  // property writing so that scalar values are persisted as links.
16808
17010
  await this.innerUpdate(!hasConstructor, batchId);
16809
- // Now handle any deferred resolveLanguage properties that were excluded
16810
- // from initialValues. setProperty will call createExpression to upload
16811
- // the data to the appropriate language and store the resulting URI.
16812
- for (const key of deferredResolveLanguageProps) {
17011
+ for (const key of deferredExpressionProps) {
16813
17012
  const value = this[key];
16814
17013
  if (value !== undefined && value !== null) {
16815
17014
  await this.setProperty(key, value, batchId);
@@ -17104,7 +17303,7 @@ class Ad4mModel {
17104
17303
  * @param perspective - The perspective to create the instance in
17105
17304
  * @param data - Property values to assign before saving
17106
17305
  * @param options - Optional settings:
17107
- * - `parent` — a `ParentScope` (model form or raw form) whose `id` will
17306
+ * - `parent` — a `Scope` (model form or raw form) whose `id` will
17108
17307
  * be used to create an incoming link from the parent to the new instance.
17109
17308
  * - `batchId` — an existing batch id; when provided the link write and
17110
17309
  * `save()` are added to the batch instead of committed immediately.
@@ -17336,8 +17535,7 @@ class Ad4mModel {
17336
17535
  * // With explicit configuration
17337
17536
  * const PersonClass = Ad4mModel.fromJSONSchema(schema, {
17338
17537
  * name: "Person",
17339
- * namespace: "person://",
17340
- * resolveLanguage: "literal"
17538
+ * namespace: "person://"
17341
17539
  * });
17342
17540
  *
17343
17541
  * // With property mapping
@@ -17754,11 +17952,20 @@ var __metadata = (undefined && undefined.__metadata) || function (k, v) {
17754
17952
  // Mirrors the Rust `auto_processor::config::AutoProcessorConfig` SDNA.
17755
17953
  // One node per registered processor; the node URI is
17756
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`.
17757
17962
  exports.AutoProcessorConfig = class AutoProcessorConfig extends Ad4mModel {
17758
17963
  constructor() {
17759
17964
  super(...arguments);
17760
- this.type = "ad4m://AutoProcessor";
17761
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`).
17762
17969
  this.processorId = "";
17763
17970
  /** SPARQL SELECT that gathers source items each pass. */
17764
17971
  this.sourceScopeQuery = "";
@@ -17770,12 +17977,13 @@ exports.AutoProcessorConfig = class AutoProcessorConfig extends Ad4mModel {
17770
17977
  this.batchMax = "32";
17771
17978
  /** How long a won claim is authoritative before peers may re-claim (ms). */
17772
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.
17773
17985
  }
17774
17986
  };
17775
- __decorate([
17776
- Flag({ through: "rdf://type", value: "ad4m://AutoProcessor" }),
17777
- __metadata("design:type", String)
17778
- ], exports.AutoProcessorConfig.prototype, "type", void 0);
17779
17987
  __decorate([
17780
17988
  Property({ through: "ad4m://processor_id", required: true, identity: true }),
17781
17989
  __metadata("design:type", String)
@@ -17785,11 +17993,11 @@ __decorate([
17785
17993
  __metadata("design:type", String)
17786
17994
  ], exports.AutoProcessorConfig.prototype, "sourceScopeQuery", void 0);
17787
17995
  __decorate([
17788
- Optional({ through: "ad4m://base_prefix", resolveLanguage: "literal" }),
17996
+ Optional({ through: "ad4m://base_prefix" }),
17789
17997
  __metadata("design:type", String)
17790
17998
  ], exports.AutoProcessorConfig.prototype, "basePrefix", void 0);
17791
17999
  __decorate([
17792
- HasMany({ through: "ad4m://interpretation_class" }),
18000
+ HasMany({ through: "ad4m://interpretation_class", datatype: "xsd:string" }),
17793
18001
  __metadata("design:type", Array)
17794
18002
  ], exports.AutoProcessorConfig.prototype, "interpretationClasses", void 0);
17795
18003
  __decorate([
@@ -17797,7 +18005,7 @@ __decorate([
17797
18005
  __metadata("design:type", String)
17798
18006
  ], exports.AutoProcessorConfig.prototype, "debounceMs", void 0);
17799
18007
  __decorate([
17800
- Optional({ through: "ad4m://batch_min", resolveLanguage: "literal" }),
18008
+ Optional({ through: "ad4m://batch_min" }),
17801
18009
  __metadata("design:type", String)
17802
18010
  ], exports.AutoProcessorConfig.prototype, "batchMin", void 0);
17803
18011
  __decorate([
@@ -17805,7 +18013,7 @@ __decorate([
17805
18013
  __metadata("design:type", String)
17806
18014
  ], exports.AutoProcessorConfig.prototype, "batchMax", void 0);
17807
18015
  __decorate([
17808
- Optional({ through: "ad4m://max_wait_ms", resolveLanguage: "literal" }),
18016
+ Optional({ through: "ad4m://max_wait_ms" }),
17809
18017
  __metadata("design:type", String)
17810
18018
  ], exports.AutoProcessorConfig.prototype, "maxWaitMs", void 0);
17811
18019
  __decorate([
@@ -17813,61 +18021,89 @@ __decorate([
17813
18021
  __metadata("design:type", String)
17814
18022
  ], exports.AutoProcessorConfig.prototype, "claimTtlMs", void 0);
17815
18023
  __decorate([
17816
- Optional({ through: "ad4m://source_window_ms", resolveLanguage: "literal" }),
18024
+ Optional({ through: "ad4m://source_window_ms" }),
17817
18025
  __metadata("design:type", String)
17818
18026
  ], exports.AutoProcessorConfig.prototype, "sourceWindowMs", void 0);
17819
18027
  __decorate([
17820
- Optional({ through: "ad4m://dedup_strategy", resolveLanguage: "literal" }),
18028
+ Optional({ through: "ad4m://dedup_strategy" }),
17821
18029
  __metadata("design:type", String)
17822
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);
17823
18051
  exports.AutoProcessorConfig = __decorate([
17824
- Model$1({ name: "AutoProcessorConfig" })
18052
+ Model$1({ name: "AutoProcessor" })
17825
18053
  ], exports.AutoProcessorConfig);
17826
18054
  // ── InterpretationRun ───────────────────────────────────────────────────────
17827
18055
  // Mirrors the Rust `interpretation::overlay::InterpretationRun` SDNA.
17828
18056
  // One node per completed pass; the node URI is `ad4m://interp/run/<runId>`.
17829
18057
  exports.InterpretationRun = class InterpretationRun extends Ad4mModel {
17830
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).
17831
18062
  super(...arguments);
17832
- this.type = "ad4m://interpretation-run";
17833
18063
  /** UUID for this run — the dedup key across run nodes. */
17834
18064
  this.runId = "";
17835
18065
  /**
17836
18066
  * Source item IDs consumed by this pass.
17837
18067
  * Stored as multiple links with the same predicate; the processed-turn
17838
- * 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.
17839
18071
  */
17840
18072
  this.sources = [];
17841
18073
  }
17842
18074
  };
17843
- __decorate([
17844
- Flag({ through: "ad4m://type", value: "ad4m://interpretation-run" }),
17845
- __metadata("design:type", String)
17846
- ], exports.InterpretationRun.prototype, "type", void 0);
17847
18075
  __decorate([
17848
18076
  Property({ through: "ad4m://interp/run_id", required: true, identity: true }),
17849
18077
  __metadata("design:type", String)
17850
18078
  ], exports.InterpretationRun.prototype, "runId", void 0);
17851
18079
  __decorate([
17852
- Optional({ through: "ad4m://interp/model", resolveLanguage: "literal" }),
18080
+ Optional({ through: "ad4m://interp/model" }),
17853
18081
  __metadata("design:type", String)
17854
18082
  ], exports.InterpretationRun.prototype, "model", void 0);
17855
18083
  __decorate([
17856
- Optional({ through: "ad4m://interp/prompt_version", resolveLanguage: "literal" }),
18084
+ Optional({ through: "ad4m://interp/prompt_version" }),
17857
18085
  __metadata("design:type", String)
17858
18086
  ], exports.InterpretationRun.prototype, "promptVersion", void 0);
17859
18087
  __decorate([
17860
- Optional({ through: "ad4m://interp/ran_at", resolveLanguage: "literal" }),
18088
+ Optional({ through: "ad4m://interp/ran_at" }),
17861
18089
  __metadata("design:type", String)
17862
18090
  ], exports.InterpretationRun.prototype, "ranAt", void 0);
17863
18091
  __decorate([
17864
- Optional({ through: "ad4m://interp/processor", resolveLanguage: "literal" }),
18092
+ Optional({ through: "ad4m://interp/processor" }),
17865
18093
  __metadata("design:type", String)
17866
18094
  ], exports.InterpretationRun.prototype, "processor", void 0);
17867
18095
  __decorate([
17868
- HasMany({ through: "ad4m://interp/sources" }),
18096
+ HasMany({ through: "ad4m://interp/sources", datatype: "xsd:string" }),
17869
18097
  __metadata("design:type", Array)
17870
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);
17871
18107
  exports.InterpretationRun = __decorate([
17872
18108
  Model$1({ name: "InterpretationRun" })
17873
18109
  ], exports.InterpretationRun);
@@ -17899,11 +18135,11 @@ exports.InterpretationOverlay = class InterpretationOverlay extends Ad4mModel {
17899
18135
  }
17900
18136
  };
17901
18137
  __decorate([
17902
- Property({ through: "ad4m://interp/kind", required: true, resolveLanguage: "literal" }),
18138
+ Property({ through: "ad4m://interp/kind", required: true }),
17903
18139
  __metadata("design:type", String)
17904
18140
  ], exports.InterpretationOverlay.prototype, "kind", void 0);
17905
18141
  __decorate([
17906
- Optional({ through: "ad4m://interp/run", resolveLanguage: "literal" }),
18142
+ Optional({ through: "ad4m://interp/run" }),
17907
18143
  __metadata("design:type", String)
17908
18144
  ], exports.InterpretationOverlay.prototype, "run", void 0);
17909
18145
  exports.InterpretationOverlay = __decorate([
@@ -17942,23 +18178,74 @@ function parseSparqlCount(result) {
17942
18178
  /**
17943
18179
  * Decode a `Literal`-encoded SPARQL binding back to a plain string.
17944
18180
  *
17945
- * Mirrors Flux's local `parseLit` helper. Returns `''` for `undefined`/empty
17946
- * input. Falls through to the raw value if decoding fails (defensive — the
17947
- * 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.
17948
18205
  */
17949
18206
  function parseLit(val) {
17950
18207
  if (val === undefined || val === null || val === '')
17951
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`.
17952
18214
  try {
17953
18215
  const result = Literal.fromUrl(val).get();
17954
- if (result && typeof result === 'object') {
17955
- 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);
17956
18221
  }
17957
18222
  return String(result);
17958
18223
  }
17959
18224
  catch {
17960
- 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
+ }
17961
18247
  }
18248
+ return val;
17962
18249
  }
17963
18250
  /** Decode a `Literal`-encoded binding to a number. Returns 0 on empty/invalid input. */
17964
18251
  function parseLitNumber(val) {
@@ -18308,16 +18595,21 @@ function formatQueryValue(value) {
18308
18595
  *
18309
18596
  * @param predicate - The predicate URI for the property
18310
18597
  * @param condition - The Where condition value
18311
- * @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.
18312
18604
  * @returns A single SPARQL condition string
18313
18605
  */
18314
18606
  function buildWhereCondition(predicate, condition, opts) {
18315
18607
  const escapedPredicate = escapeQueryString(predicate);
18316
- // For literal-resolved properties, we match against the raw IRI (which is a literal: URI)
18317
- // For language-resolved properties, we match against the plain URI
18318
- // For literal-resolved properties, values are stored as IRIs like <literal:string:VALUE>
18319
- // For language-resolved properties, values are plain URIs
18320
- 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;
18321
18613
  const varSuffix = opts?.varIndex ?? 0;
18322
18614
  function formatValue(v) {
18323
18615
  if (typeof v === 'string') {
@@ -18426,23 +18718,28 @@ function compileWhereClause(where, metadata) {
18426
18718
  if (['id', 'author', 'timestamp'].includes(propertyName))
18427
18719
  continue;
18428
18720
  let predicate;
18429
- 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;
18430
18729
  if (metadata) {
18431
18730
  const propMeta = metadata.properties[propertyName];
18432
18731
  if (propMeta) {
18433
18732
  predicate = propMeta.predicate;
18434
- resolveLanguage = propMeta.resolveLanguage;
18733
+ isDeterministicLiteral = propMeta.resolveLanguage === undefined;
18435
18734
  }
18436
18735
  else {
18437
- // Property not found in metadata — treat name as raw predicate URI
18438
18736
  predicate = propertyName;
18439
18737
  }
18440
18738
  }
18441
18739
  else {
18442
- // No metadata — treat name as raw predicate URI
18443
18740
  predicate = propertyName;
18444
18741
  }
18445
- const cond = buildWhereCondition(predicate, condition, { resolveLanguage, varIndex: conditions.length });
18742
+ const cond = buildWhereCondition(predicate, condition, { isDeterministicLiteral, varIndex: conditions.length });
18446
18743
  if (cond) {
18447
18744
  conditions.push(cond);
18448
18745
  }
@@ -18578,7 +18875,7 @@ function fn(iri, args = []) {
18578
18875
  * ```typescript
18579
18876
  * @Property({
18580
18877
  * through: 'we://image',
18581
- * resolveLanguage: FILE_STORAGE_LANGUAGE,
18878
+ * resolveLanguage: 'literal',
18582
18879
  * transform: fileToDataUri,
18583
18880
  * })
18584
18881
  * avatar?: string;
@@ -18707,6 +19004,7 @@ exports.concat = concat;
18707
19004
  exports.createPersistentCache = createPersistentCache;
18708
19005
  exports.determineNamespace = determineNamespace;
18709
19006
  exports.determinePredicate = determinePredicate;
19007
+ exports.effectiveLiteralStorage = effectiveLiteralStorage;
18710
19008
  exports.escapeQueryString = escapeQueryString;
18711
19009
  exports.exists = exists;
18712
19010
  exports.exprRef2String = exprRef2String;
@@ -18735,6 +19033,7 @@ exports.isObjectType = isObjectType;
18735
19033
  exports.isSchemaType = isSchemaType;
18736
19034
  exports.linkEqual = linkEqual;
18737
19035
  exports.literal = literal;
19036
+ exports.looksLikeUri = looksLikeUri;
18738
19037
  exports.normalizeNamespaceString = normalizeNamespaceString;
18739
19038
  exports.normalizeSchemaType = normalizeSchemaType;
18740
19039
  exports.normalizeValue = normalizeValue;
@@ -18750,3 +19049,4 @@ exports.setCachedResult = setCachedResult;
18750
19049
  exports.setPropertyRegistryEntry = setPropertyRegistryEntry;
18751
19050
  exports.setRelationRegistryEntry = setRelationRegistryEntry;
18752
19051
  exports.typeDefsString = typeDefsString;
19052
+ exports.valueToLiteralIri = valueToLiteralIri;