@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.js CHANGED
@@ -779,6 +779,14 @@ class Literal {
779
779
  const numberString = body.substring(7);
780
780
  return parseFloat(numberString);
781
781
  }
782
+ if (body.startsWith("boolean:")) {
783
+ const boolString = decodeURIComponent(body.substring(8));
784
+ if (boolString === "true")
785
+ return true;
786
+ if (boolString === "false")
787
+ return false;
788
+ throw new Error(`Can't parse boolean literal: ${boolString}`);
789
+ }
782
790
  if (body.startsWith("json:")) {
783
791
  const json = body.substring(5);
784
792
  return JSON.parse(decodeURIComponent(json));
@@ -1189,6 +1197,13 @@ class SHACLShape {
1189
1197
  if (prop.writable !== undefined) {
1190
1198
  turtle += ` ad4m:writable ${prop.writable} ;\n`;
1191
1199
  }
1200
+ // Interpreter dedup key: `toLinks()` and `toJSON()` preserve
1201
+ // `identity`; a Turtle export must too or the round-trip through
1202
+ // Turtle silently drops the interpretation-dedup marker
1203
+ // (CodeRabbit #881 review).
1204
+ if (prop.identity !== undefined) {
1205
+ turtle += ` ad4m:identity ${prop.identity} ;\n`;
1206
+ }
1192
1207
  // Remove trailing semicolon and close bracket
1193
1208
  turtle = turtle.slice(0, -2) + '\n';
1194
1209
  turtle += isLast ? ` ] .\n` : ` ] ;\n`;
@@ -1578,10 +1593,15 @@ class SHACLShape {
1578
1593
  val = val.substring(8);
1579
1594
  prop.writable = val === 'true';
1580
1595
  }
1596
+ // The general language selector (e.g. "literal" or a custom address).
1581
1597
  const resolveLangLink = links.find(l => l.source === propShapeId && l.predicate === "ad4m://resolveLanguage");
1582
1598
  if (resolveLangLink) {
1583
1599
  prop.resolveLanguage = resolveLangLink.target.replace(/^literal:\/\/string:|^literal:string:/, '');
1584
1600
  }
1601
+ // Storage mode is derived from `resolveLanguage` alone:
1602
+ // - unset → deterministic typed literal (fast path)
1603
+ // - "literal" → signed envelope on the built-in literal language
1604
+ // - <address> → expression on that custom language
1585
1605
  // Parse action arrays
1586
1606
  const setterLink = links.find(l => l.source === propShapeId && l.predicate === "ad4m://setter");
1587
1607
  if (setterLink) {
@@ -1780,7 +1800,7 @@ class SHACLShape {
1780
1800
  hasValue: p.has_value,
1781
1801
  local: p.local,
1782
1802
  writable: p.writable,
1783
- resolveLanguage: p.resolve_language,
1803
+ resolveLanguage: p.resolve_language ?? p.resolveLanguage,
1784
1804
  setter: p.setter,
1785
1805
  adder: p.adder,
1786
1806
  remover: p.remover,
@@ -1920,20 +1940,38 @@ interpretationHint) {
1920
1940
  name: propName,
1921
1941
  path: propMeta.through,
1922
1942
  };
1923
- // Determine datatype from initial value or resolveLanguage
1924
- if (propMeta.resolveLanguage === "literal") {
1925
- propShape.datatype = "xsd://string";
1943
+ // Determine datatype from JS field value type; the resolve* options
1944
+ // control storage mode (deterministic vs envelope), not scalar type.
1945
+ // A value stored on the literal language (deterministic or envelope,
1946
+ // i.e. resolveLanguage unset or "literal") gets a string datatype when
1947
+ // no initial value pins a more specific type. A custom resolveLanguage
1948
+ // yields an expression URI, not a literal.
1949
+ //
1950
+ // Skip auto-datatype for properties with a custom `getter` — those
1951
+ // typically return URIs (e.g. `@Optional({ getter: "SELECT ?target ..." })`
1952
+ // that hops through a link to another instance's URI). Autosetting
1953
+ // `sh:datatype xsd:string` there would trip the hydration decode gate
1954
+ // and silently transform `literal:string:<hex>` URIs into their inner
1955
+ // plain-string form on read. Users who want a getter to return literal
1956
+ // values can opt in explicitly by setting `datatype` on the property
1957
+ // options (handled below).
1958
+ if (propMeta.datatype) {
1959
+ // Explicit opt-in from PropertyOptions always wins over inference.
1960
+ propShape.datatype = propMeta.datatype;
1926
1961
  }
1927
- else if (propMeta.initial) {
1928
- const initialType = typeof obj[propName];
1929
- if (initialType === "number") {
1930
- propShape.datatype = "xsd://integer";
1931
- }
1932
- else if (initialType === "boolean") {
1933
- propShape.datatype = "xsd://boolean";
1934
- }
1935
- else if (initialType === "string") {
1936
- propShape.datatype = "xsd://string";
1962
+ else {
1963
+ const isLiteral = propMeta.resolveLanguage === undefined || propMeta.resolveLanguage === "literal";
1964
+ if ((propMeta.initial !== undefined || isLiteral) && !propMeta.getter) {
1965
+ const initialType = typeof obj[propName];
1966
+ if (initialType === "number") {
1967
+ propShape.datatype = "xsd://integer";
1968
+ }
1969
+ else if (initialType === "boolean") {
1970
+ propShape.datatype = "xsd://boolean";
1971
+ }
1972
+ else if (initialType === "string" || isLiteral) {
1973
+ propShape.datatype = "xsd://string";
1974
+ }
1937
1975
  }
1938
1976
  }
1939
1977
  // Cardinality constraints
@@ -2035,8 +2073,19 @@ interpretationHint) {
2035
2073
  name: relName,
2036
2074
  path: synthesizedPath,
2037
2075
  };
2038
- // Relations typically contain IRIs
2039
- relShape.nodeKind = 'IRI';
2076
+ // A relation with a declared `datatype` holds encoded literal
2077
+ // values (e.g. `HasMany<string>` with `datatype: "xsd:string"`).
2078
+ // Everything else is a URI relation pointing at another
2079
+ // instance. The executor uses `sh:datatype` on hydration to
2080
+ // decide whether to decode `literal:<type>:<value>` wire form
2081
+ // (yes for literals, no for URIs).
2082
+ if (relMeta.datatype) {
2083
+ relShape.datatype = relMeta.datatype;
2084
+ relShape.nodeKind = 'Literal';
2085
+ }
2086
+ else {
2087
+ relShape.nodeKind = 'IRI';
2088
+ }
2040
2089
  // Encode relation kind so the executor can derive direction and
2041
2090
  // scalar-vs-collection rendering without consulting the JS class.
2042
2091
  relShape.relationKind = relMeta.kind;
@@ -2460,7 +2509,7 @@ function applyPropertyMetadata(opts) {
2460
2509
  *
2461
2510
  * @description
2462
2511
  * Equivalent to `@Property` but defaults `required` to `false` and does not
2463
- * apply `resolveLanguage` or `initial` defaults. Use this when a property
2512
+ * apply any `initial` defaults. Use this when a property
2464
2513
  * may or may not have a value, and you want full control over its configuration.
2465
2514
  *
2466
2515
  * @example
@@ -2583,8 +2632,7 @@ function Flag(opts) {
2583
2632
  * @Model({ name: "Recipe" })
2584
2633
  * class Recipe extends Ad4mModel {
2585
2634
  * @Property({
2586
- * through: "recipe://name",
2587
- * resolveLanguage: "literal"
2635
+ * through: "recipe://name"
2588
2636
  * })
2589
2637
  * name: string = "";
2590
2638
  *
@@ -2641,7 +2689,9 @@ function Model$1(opts) {
2641
2689
  * Smart defaults (all overridable):
2642
2690
  * - `required` → `false`
2643
2691
  * - `readOnly` → `false`
2644
- * - `resolveLanguage` → `"literal"`
2692
+ * - `resolveLanguage` → unset → deterministic typed literal storage
2693
+ * (the perf default). Set `resolveLanguage: "literal"` for a signed-envelope
2694
+ * value, or a custom language address to resolve through that language.
2645
2695
  * - `initial` → `undefined` (no link created until a value is explicitly set)
2646
2696
  *
2647
2697
  * Properties are optional by default. When a model instance is created without
@@ -2674,7 +2724,8 @@ function Model$1(opts) {
2674
2724
  * })
2675
2725
  * role: string = "";
2676
2726
  *
2677
- * // Optional property with literal resolution
2727
+ * // Optional property with signed-envelope literal storage
2728
+ * // (per-value provenance)
2678
2729
  * @Property({
2679
2730
  * through: "user://bio",
2680
2731
  * resolveLanguage: "literal"
@@ -2687,18 +2738,22 @@ function Model$1(opts) {
2687
2738
  * @param {string} opts.through - The predicate URI for the property
2688
2739
  * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
2689
2740
  * @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
2690
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
2741
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
2691
2742
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
2692
2743
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
2693
2744
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
2694
2745
  */
2695
2746
  function Property(opts) {
2696
2747
  const required = opts.required ?? false;
2748
+ // `resolveLanguage` is intentionally NOT defaulted here.
2749
+ // The effective storage mode is derived from what the user explicitly set:
2750
+ // - unset → deterministic typed literal (the perf default)
2751
+ // - "literal" → signed literal envelope (per-value provenance)
2752
+ // - <custom address> → expression on that custom language
2697
2753
  return applyPropertyMetadata({
2698
2754
  ...opts,
2699
2755
  required,
2700
2756
  readOnly: opts.readOnly ?? false,
2701
- resolveLanguage: opts.resolveLanguage ?? "literal",
2702
2757
  initial: opts.initial ?? (required ? "literal:string:uninitialized" : undefined),
2703
2758
  });
2704
2759
  }
@@ -2753,7 +2808,7 @@ function Property(opts) {
2753
2808
  * @param {PropertyOptions} opts - Property configuration
2754
2809
  * @param {string} opts.through - The predicate URI for the property
2755
2810
  * @param {string} [opts.initial] - Initial value (if property should have one)
2756
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
2811
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
2757
2812
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
2758
2813
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
2759
2814
  */
@@ -2821,6 +2876,7 @@ function HasMany(first, second) {
2821
2876
  ...(opts.getter && { getter: opts.getter }),
2822
2877
  ...(opts.filter !== undefined && { filter: opts.filter }),
2823
2878
  ...(opts.where && { where: opts.where }),
2879
+ ...(opts.datatype && { datatype: opts.datatype }),
2824
2880
  };
2825
2881
  const relKey = key;
2826
2882
  // Only add mutation methods when a predicate is available
@@ -2854,6 +2910,7 @@ function HasOne(first, second) {
2854
2910
  local: opts.local,
2855
2911
  ...(opts.filter !== undefined && { filter: opts.filter }),
2856
2912
  ...(opts.where && { where: opts.where }),
2913
+ ...(opts.datatype && { datatype: opts.datatype }),
2857
2914
  };
2858
2915
  const relKey = key;
2859
2916
  if (opts.through) {
@@ -2894,6 +2951,7 @@ function BelongsToOne(first, second) {
2894
2951
  local: opts.local,
2895
2952
  ...(opts.filter !== undefined && { filter: opts.filter }),
2896
2953
  ...(opts.where && { where: opts.where }),
2954
+ ...(opts.datatype && { datatype: opts.datatype }),
2897
2955
  };
2898
2956
  if (opts.through) {
2899
2957
  // Read-only property (the owning side manages the link)
@@ -2923,6 +2981,7 @@ function BelongsToMany(first, second) {
2923
2981
  ...(opts.getter && { getter: opts.getter }),
2924
2982
  ...(opts.filter !== undefined && { filter: opts.filter }),
2925
2983
  ...(opts.where && { where: opts.where }),
2984
+ ...(opts.datatype && { datatype: opts.datatype }),
2926
2985
  };
2927
2986
  // @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
2928
2987
  // prototype methods. Mutation must go through the owning side's @HasMany decorator.
@@ -3902,6 +3961,16 @@ class PerspectiveProxy {
3902
3961
  async addAutoProcessorEventListener(cb) {
3903
3962
  return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").addAutoProcessorEventListener(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, cb);
3904
3963
  }
3964
+ /**
3965
+ * Subscribe to this perspective's auto-processor neighbourhood-state
3966
+ * events — fires when this executor claims / finishes / abandons a
3967
+ * batch. Perspective-scoped, so a UI can render "someone is
3968
+ * auto-processing this" without receiving the batch payload. See
3969
+ * `AutoProcessorNeighbourhoodStateEvent`.
3970
+ */
3971
+ async addAutoProcessorNeighbourhoodStateListener(cb) {
3972
+ return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").addAutoProcessorNeighbourhoodStateListener(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, cb);
3973
+ }
3905
3974
  /**
3906
3975
  * Executes a Prolog query against the perspective's knowledge base.
3907
3976
  * This is a powerful way to find complex patterns in the graph.
@@ -4774,20 +4843,20 @@ class PerspectiveProxy {
4774
4843
  return null;
4775
4844
  }
4776
4845
  const flowUri = flowUriLinks[0].data.target;
4777
- // Compute alternate prefix for state/transition URIs
4778
- const alternatePrefix = flowUri.endsWith('Flow')
4779
- ? flowUri.slice(0, -4) + '.'
4780
- : flowUri + '.';
4781
- // Fetch flow links using SPARQL to match flowUri source OR alternatePrefix sources
4782
- const sparqlQuery = `SELECT ?s ?p ?o WHERE {
4783
- ?s ?p ?o .
4784
- FILTER(?s = <${flowUri}> || STRSTARTS(STR(?s), "${alternatePrefix}"))
4785
- }`;
4786
- const sparqlResult = await this.querySparql(sparqlQuery);
4787
- const flowLinks = (sparqlResult || []).map((r) => ({
4788
- source: r.s,
4789
- predicate: r.p,
4790
- target: r.o
4846
+ // Fetch flow-level links (hasState, hasTransition, flowable, startAction)
4847
+ const flowLevelLinks = await this.get(new LinkQuery({ source: flowUri }));
4848
+ // Collect state and transition URIs, then fetch their child links
4849
+ const childUris = flowLevelLinks
4850
+ .filter(l => l.data.predicate === "ad4m://hasState"
4851
+ || l.data.predicate === "ad4m://hasTransition")
4852
+ .map(l => l.data.target);
4853
+ const childResults = await Promise.all(childUris.map(uri => this.get(new LinkQuery({ source: uri }))));
4854
+ // Flatten into the {source, predicate, target} shape fromLinks expects
4855
+ const allExprs = [...flowLevelLinks, ...childResults.flat()];
4856
+ const flowLinks = allExprs.map(l => ({
4857
+ source: l.data.source,
4858
+ predicate: l.data.predicate,
4859
+ target: l.data.target
4791
4860
  }));
4792
4861
  return SHACLFlow.fromLinks(flowLinks, flowUri);
4793
4862
  }
@@ -5742,10 +5811,16 @@ class PerspectiveClient {
5742
5811
  * retries on parse failure), so it can legitimately take minutes on slower
5743
5812
  * or CPU-only models. We raise the default 30s RPC timeout here to 20 min
5744
5813
  * (matches the CI `--timeout 1200000` for the interpretation tests).
5814
+ *
5815
+ * `existingScope` and `mintScope` match the AutoProcessor semantics:
5816
+ * `existingScope` constrains the dedup lookup to instances under a
5817
+ * subtree; `mintScope` links every FRESHLY-created base as a child of
5818
+ * `mintScope.id` via its predicate (upserts of pre-existing instances
5819
+ * are NOT re-parented — same rule as the watcher).
5745
5820
  */
5746
- async runInterpretation(uuid, transcript, basePrefix, classes) {
5821
+ async runInterpretation(uuid, transcript, basePrefix, classes, existingScope, mintScope) {
5747
5822
  const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000;
5748
- return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretation', { uuid, transcript, basePrefix, classes }, RUN_INTERPRETATION_TIMEOUT_MS);
5823
+ return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretation', { uuid, transcript, basePrefix, classes, existingScope, mintScope }, RUN_INTERPRETATION_TIMEOUT_MS);
5749
5824
  }
5750
5825
  /**
5751
5826
  * Register a neighbourhood auto-processor on this perspective. The executor's
@@ -5776,6 +5851,11 @@ class PerspectiveClient {
5776
5851
  * Subscribe to auto-processor step signals. `cb` fires for every
5777
5852
  * `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
5778
5853
  * Processed), letting a UI show progress and await the next batch.
5854
+ *
5855
+ * Registered on the per-uuid `#linkUnsubscribers` map so
5856
+ * `PerspectiveProxy.dispose()` → `removeAllListeners(uuid)` cleans the
5857
+ * subscription up; using the global `#unsubscribers` array would leak
5858
+ * callbacks across repeated view lifecycles (CodeRabbit #881 review).
5779
5859
  */
5780
5860
  async addAutoProcessorEventListener(uuid, cb) {
5781
5861
  const unsub = __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").subscribe((data) => {
@@ -5783,7 +5863,28 @@ class PerspectiveClient {
5783
5863
  cb(data);
5784
5864
  }
5785
5865
  });
5786
- __classPrivateFieldGet$9(this, _PerspectiveClient_unsubscribers, "f").push(unsub);
5866
+ let existing = __classPrivateFieldGet$9(this, _PerspectiveClient_linkUnsubscribers, "f").get(uuid) || [];
5867
+ existing.push(unsub);
5868
+ __classPrivateFieldGet$9(this, _PerspectiveClient_linkUnsubscribers, "f").set(uuid, existing);
5869
+ await __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").waitForSubscription();
5870
+ }
5871
+ /**
5872
+ * Subscribe to neighbourhood-state events on a perspective. `cb` fires
5873
+ * when THIS executor claims / finishes / abandons a batch for any
5874
+ * processor on `uuid` — perspective-scoped observability so a UI can
5875
+ * render "someone is auto-processing this" without receiving the batch
5876
+ * payload or LLM I/O. Registered on the per-uuid `#linkUnsubscribers`
5877
+ * map so `PerspectiveProxy.dispose()` sweeps it up.
5878
+ */
5879
+ async addAutoProcessorNeighbourhoodStateListener(uuid, cb) {
5880
+ const unsub = __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").subscribe((data) => {
5881
+ if (data.type === 'auto-processor-neighbourhood-state' && data.perspectiveUuid === uuid) {
5882
+ cb(data);
5883
+ }
5884
+ });
5885
+ let existing = __classPrivateFieldGet$9(this, _PerspectiveClient_linkUnsubscribers, "f").get(uuid) || [];
5886
+ existing.push(unsub);
5887
+ __classPrivateFieldGet$9(this, _PerspectiveClient_linkUnsubscribers, "f").set(uuid, existing);
5787
5888
  await __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").waitForSubscription();
5788
5889
  }
5789
5890
  async addLinkExpression(uuid, link, status = 'shared', batchId) {
@@ -14449,13 +14550,7 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
14449
14550
  }
14450
14551
  else {
14451
14552
  // Handle regular properties
14452
- let resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
14453
- // If no specific resolveLanguage for this property, use the global one
14454
- if (!resolveLanguage && options.resolveLanguage) {
14455
- resolveLanguage = options.resolveLanguage;
14456
- }
14457
14553
  const local = getPropertyOption(propertyName, propertySchema, options, 'local');
14458
- // Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
14459
14554
  let readOnly = getPropertyOption(propertyName, propertySchema, options, 'readOnly');
14460
14555
  if (readOnly === undefined) {
14461
14556
  const xWritable = propertySchema["x-ad4m"]?.writable;
@@ -14463,22 +14558,14 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
14463
14558
  }
14464
14559
  const writable = !readOnly;
14465
14560
  let initial = getPropertyOption(propertyName, propertySchema, options, 'initial');
14466
- // Handle nested objects by serializing to JSON
14467
- if (isObjectType(propertySchema) && !resolveLanguage) {
14468
- resolveLanguage = 'literal';
14561
+ // Not defaulted — absence means "deterministic typed literal" (the
14562
+ // perf default); an explicit `resolveLanguage: "literal"` selects the
14563
+ // signed-envelope path; any other value selects a custom language.
14564
+ // See effectiveLiteralStorage().
14565
+ const resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
14566
+ if (isObjectType(propertySchema)) {
14469
14567
  console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
14470
14568
  }
14471
- // Ensure numeric properties use literal language for correct typing
14472
- if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
14473
- resolveLanguage = 'literal';
14474
- }
14475
- // Default resolveLanguage to 'literal' for all remaining property types,
14476
- // matching the @Property decorator behaviour. Without this, string values
14477
- // stored as literal: URLs are returned unparsed.
14478
- if (resolveLanguage === undefined || resolveLanguage === null) {
14479
- resolveLanguage = 'literal';
14480
- }
14481
- // If property is required, ensure it has an initial value
14482
14569
  if (isRequired && !initial) {
14483
14570
  if (isObjectType(propertySchema)) {
14484
14571
  initial = 'literal:json:{}';
@@ -14491,7 +14578,7 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
14491
14578
  through: predicate,
14492
14579
  required: isRequired,
14493
14580
  writable: writable,
14494
- ...(resolveLanguage && { resolveLanguage }),
14581
+ ...(resolveLanguage !== undefined && { resolveLanguage }),
14495
14582
  ...(local !== undefined && { local }),
14496
14583
  ...(initial && { initial })
14497
14584
  };
@@ -14606,20 +14693,108 @@ function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
14606
14693
  return false;
14607
14694
  }
14608
14695
  /**
14609
- * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
14610
- * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
14611
- * both store values as literal: URIs. Only properties with a non-literal resolveLanguage
14612
- * (e.g. file storage) or flag properties store raw URIs.
14696
+ * Check whether a string value is a well-formed absolute IRI that can be
14697
+ * stored verbatim as a link target (raw `NamedNode`) instead of being
14698
+ * wrapped in a `literal:string:*` URI.
14699
+ *
14700
+ * This mirrors the Rust `is_safe_iri_target` /
14701
+ * `looks_like_absolute_iri` predicate in
14702
+ * `rust-executor/src/perspectives/model_query/utils.rs` and is
14703
+ * **load-bearing**: a value that returns `true` here MUST also be safely
14704
+ * queryable on the Rust side (`validate_iri` gate on the SPARQL
14705
+ * `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
14706
+ * such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
14707
+ * through the write regex, is stored as an invalid `NamedNode`, and
14708
+ * becomes a silent no-match on read.
14709
+ *
14710
+ * Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
14711
+ * same rejection set the Rust `validate_iri` applies: any Unicode
14712
+ * whitespace, C0/C1 control chars, and the SPARQL-breaking characters
14713
+ * `< > { } "`.
14613
14714
  */
14614
- function isLiteralStoredProperty(propMeta) {
14615
- if (propMeta.flag)
14715
+ function looksLikeUri(value) {
14716
+ if (!/^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value))
14616
14717
  return false;
14617
- // If resolveLanguage is set to something other than "literal", it's a language expression URI
14618
- if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal")
14718
+ // Reject anything the Rust-side `validate_iri` rejects so the two
14719
+ // predicates stay in sync. `\s` covers ASCII whitespace *and*
14720
+ // U+00A0/other Unicode whitespace under the default JS regex semantics.
14721
+ if (/[\s<>{}"\u0000-\u001F\u007F-\u009F]/.test(value))
14619
14722
  return false;
14620
- // Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
14621
14723
  return true;
14622
14724
  }
14725
+ /**
14726
+ * Convert a JS value to its literal: IRI form, matching how the Rust executor
14727
+ * stores property values in the default deterministic-literal path
14728
+ * (`resolveLanguage` unset). Strings that already look like URIs are returned
14729
+ * as-is.
14730
+ *
14731
+ * Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
14732
+ * resolve path) can keep their on-disk form aligned with what
14733
+ * `queryToSPARQL()` filters against — otherwise the same value can be
14734
+ * stored as `<literal:string:https%3A...>` from one path while WHERE
14735
+ * builders probe `<https://example.com>` from the other.
14736
+ *
14737
+ * The object/array arm mirrors Rust's `Literal::from_json` in
14738
+ * `perspective_instance.rs::resolve_property_value` (which routes
14739
+ * `Value::Object | Value::Array` through JSON encoding). Without it, JS
14740
+ * would fall through to `String(value)` and turn `{a: 1}` into
14741
+ * `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
14742
+ */
14743
+ function valueToLiteralIri(value) {
14744
+ if (typeof value === 'string') {
14745
+ if (looksLikeUri(value))
14746
+ return value;
14747
+ return Literal.from(value).toUrl();
14748
+ }
14749
+ if (typeof value === 'number') {
14750
+ return Literal.from(value).toUrl();
14751
+ }
14752
+ if (typeof value === 'boolean') {
14753
+ return Literal.from(value).toUrl();
14754
+ }
14755
+ // Objects and arrays: route through Literal.from so we emit
14756
+ // `literal:json:*` (mirrors Rust `Literal::from_json`). Without this
14757
+ // arm we fall through to `String(value)` which turns objects into
14758
+ // `"[object Object]"` and arrays into `"1,2"` — silently storing the
14759
+ // wrong shape and breaking equality filters (`findAll({ where:
14760
+ // { config: {...} } })` would match against `"[object Object]"`).
14761
+ // The `value !== null` guard preserves the historical fallthrough for
14762
+ // `null` (→ `literal:string:null`), since `Literal.from(null).toUrl()`
14763
+ // throws on the empty-literal check.
14764
+ if (value !== null && typeof value === 'object') {
14765
+ return Literal.from(value).toUrl();
14766
+ }
14767
+ return Literal.from(String(value)).toUrl();
14768
+ }
14769
+ /**
14770
+ * Derive the effective storage mode from a property's explicit options.
14771
+ * `resolveLanguage` is the sole selector and is NOT defaulted at the
14772
+ * decorator level:
14773
+ * - unset → deterministic typed literal (the perf default
14774
+ * for a plain `@Property()`)
14775
+ * - `"literal"` → signed envelope on the built-in literal language
14776
+ * (per-value provenance, e.g. Flux message bodies)
14777
+ * - `<custom address>` → signed expression on that custom language
14778
+ */
14779
+ function effectiveLiteralStorage(meta) {
14780
+ const lang = meta.resolveLanguage;
14781
+ if (lang === undefined)
14782
+ return { kind: "deterministic" };
14783
+ if (lang === "literal")
14784
+ return { kind: "envelope" };
14785
+ return { kind: "custom", language: lang };
14786
+ }
14787
+ /**
14788
+ * Determine if a property stores values as deterministic literal: IRIs (so WHERE
14789
+ * filters can match typed literals directly). Envelope / custom-language
14790
+ * properties resolve through expressions, and flag properties store raw URIs —
14791
+ * none is a deterministic literal.
14792
+ */
14793
+ function isLiteralStoredProperty(propMeta) {
14794
+ if (propMeta.flag)
14795
+ return false;
14796
+ return effectiveLiteralStorage(propMeta).kind === "deterministic";
14797
+ }
14623
14798
  /**
14624
14799
  * Escape a string for use as a SPARQL string literal.
14625
14800
  */
@@ -15160,11 +15335,11 @@ class ModelQueryBuilder {
15160
15335
  }
15161
15336
  const field = options?.field;
15162
15337
  if (typeof modelOrPredicate === 'string') {
15163
- // Raw predicate string → raw form of ParentScope
15338
+ // Raw predicate string → raw form of Scope
15164
15339
  this.queryParams.parent = { id, predicate: modelOrPredicate };
15165
15340
  }
15166
15341
  else if (typeof modelOrPredicate === 'function') {
15167
- // Model class → model form of ParentScope
15342
+ // Model class → model form of Scope
15168
15343
  this.queryParams.parent = { id, model: modelOrPredicate, ...(field && { field }) };
15169
15344
  }
15170
15345
  else if (typeof idOrInstance !== 'string') {
@@ -15816,12 +15991,28 @@ function jsonToModelInstance(ModelClass, perspective, json, include, properties)
15816
15991
  * // Define a recipe model
15817
15992
  * @Model({ name: "Recipe" })
15818
15993
  * class Recipe extends Ad4mModel {
15819
- * // Required property with literal value
15994
+ * // Plain property — no `resolveLanguage` → deterministic typed literal
15995
+ * // storage (fast POS-index path). This is the perf default.
15996
+ * @Property({ through: "recipe://name" })
15997
+ * name: string = "";
15998
+ *
15999
+ * // Property that needs per-value provenance (e.g. a signed message body):
16000
+ * // `resolveLanguage: "literal"` routes values through expression_create on
16001
+ * // the built-in literal language, producing a signed envelope URI
16002
+ * // (author/timestamp/proof) instead of a bare typed literal.
15820
16003
  * @Property({
15821
- * through: "recipe://name",
16004
+ * through: "recipe://signed_note",
15822
16005
  * resolveLanguage: "literal"
15823
16006
  * })
15824
- * name: string = "";
16007
+ * signedNote: string = "";
16008
+ *
16009
+ * // Property resolved through a custom language: values are routed through
16010
+ * // expression_create on that language (signed expression URIs).
16011
+ * @Optional({
16012
+ * through: "recipe://photo",
16013
+ * resolveLanguage: "QmFileStorageLanguageAddress..."
16014
+ * })
16015
+ * photo: string = "";
15825
16016
  *
15826
16017
  * // Optional property with custom initial value
15827
16018
  * @Optional({
@@ -15961,7 +16152,7 @@ class Ad4mModel {
15961
16152
  * ```typescript
15962
16153
  * @Model({ name: "Recipe" })
15963
16154
  * class Recipe extends Ad4mModel {
15964
- * @Property({ through: "recipe://name", resolveLanguage: "literal" })
16155
+ * @Property({ through: "recipe://name" })
15965
16156
  * name: string = "";
15966
16157
  *
15967
16158
  * @HasMany({ through: "recipe://ingredient" })
@@ -16050,7 +16241,7 @@ class Ad4mModel {
16050
16241
  predicate: predicate,
16051
16242
  required: isRequired,
16052
16243
  readOnly: propertySchema["x-ad4m"]?.writable === false,
16053
- ...(propertySchema["x-ad4m"]?.resolveLanguage && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
16244
+ ...(propertySchema["x-ad4m"]?.resolveLanguage !== undefined && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
16054
16245
  ...(propertySchema["x-ad4m"]?.initial && { initial: propertySchema["x-ad4m"].initial }),
16055
16246
  ...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
16056
16247
  };
@@ -16069,7 +16260,9 @@ class Ad4mModel {
16069
16260
  *
16070
16261
  * @param perspective - The perspective where this model will be stored
16071
16262
  * @param baseExpression - Optional expression URI for this instance.
16072
- * If omitted, a random Literal URL is generated.
16263
+ * If omitted, a random `ad4m://obj/<id>` IRI is generated,
16264
+ * independent of any property content — this is what keeps
16265
+ * two instances with identical property values distinct.
16073
16266
  * @param source - Optional source expression this instance is linked to
16074
16267
  *
16075
16268
  * @example
@@ -16078,12 +16271,21 @@ class Ad4mModel {
16078
16271
  * const recipe = new Recipe(perspective);
16079
16272
  *
16080
16273
  * // Create with specific base expression
16081
- * const recipe = new Recipe(perspective, "literal:...");
16274
+ * const recipe = new Recipe(perspective, "ad4m://obj/existing-id");
16082
16275
  * ```
16083
16276
  */
16084
16277
  constructor(perspective, baseExpression) {
16085
16278
  this._snapshot = null;
16086
- this._baseExpression = baseExpression ? baseExpression : Literal.from(makeRandomId(24)).toUrl();
16279
+ // Use a dedicated `ad4m://obj/<id>` scheme for auto-generated
16280
+ // baseExpressions instead of `Literal.from(...).toUrl()`'s
16281
+ // `literal:string:<id>`. After typed-literal storage lands, the storage
16282
+ // layer translates any `literal:string:X` target into a typed
16283
+ // `"X"^^xsd:string` literal — which is correct for property values but
16284
+ // wrong for relation targets (which must remain NamedNode IRIs). Using
16285
+ // a distinct scheme keeps auto-generated instance IDs unambiguously
16286
+ // IRIs, so relation links like `<post> --has_comment--> <comment-id>`
16287
+ // round-trip correctly through the SPARQL store.
16288
+ this._baseExpression = baseExpression ? baseExpression : `ad4m://obj/${makeRandomId(24)}`;
16087
16289
  this._perspective = perspective;
16088
16290
  }
16089
16291
  /**
@@ -16645,14 +16847,22 @@ class Ad4mModel {
16645
16847
  }
16646
16848
  // Generate actions from metadata (replaces Prolog query)
16647
16849
  const actions = this.generatePropertySetterAction(key, metadata);
16648
- // Get resolve language from metadata (replaces Prolog query)
16649
- let resolveLanguage = metadata.resolveLanguage;
16650
16850
  // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
16651
16851
  if (value === undefined || value === null || value === "") {
16652
16852
  return;
16653
16853
  }
16654
- if (resolveLanguage) {
16655
- value = await this._perspective.createExpression(value, resolveLanguage);
16854
+ const mode = effectiveLiteralStorage(metadata);
16855
+ if (mode.kind === "custom") {
16856
+ // Custom language: route through expression_create on that language.
16857
+ value = await this._perspective.createExpression(value, mode.language);
16858
+ }
16859
+ else if (mode.kind === "envelope") {
16860
+ // Built-in literal language: signed-envelope expression (provenance).
16861
+ value = await this._perspective.createExpression(value, "literal");
16862
+ }
16863
+ else {
16864
+ // Deterministic literal: IRI (POS-index friendly).
16865
+ value = valueToLiteralIri(value);
16656
16866
  }
16657
16867
  await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value }], batchId);
16658
16868
  }
@@ -16771,41 +16981,30 @@ class Ad4mModel {
16771
16981
  // entirely and let innerUpdate write the links directly.
16772
16982
  const metadata = this.constructor.getModelMetadata();
16773
16983
  const hasConstructor = Object.values(metadata.properties).some((p) => p.required || p.flag || p.initial !== undefined);
16774
- // Track properties that have resolveLanguage (non-literal) so they can be
16775
- // set via setProperty after createSubject (which doesn't resolve languages).
16776
- const deferredResolveLanguageProps = [];
16984
+ // Track properties resolved through expression_create — a signed literal
16985
+ // envelope or a custom (non-"literal") resolveLanguage. These may fail
16986
+ // inside a batch context, so defer them to setProperty after createSubject.
16987
+ const deferredExpressionProps = [];
16777
16988
  if (hasConstructor) {
16778
- // First filter out the properties that are not relations (arrays)
16779
16989
  const initialValues = {};
16780
16990
  for (const [key, value] of Object.entries(this)) {
16781
16991
  if (value !== undefined && value !== null && !(Array.isArray(value) && value.length > 0) && !value?.action) {
16782
- // Check if this property requires language resolution (e.g. file storage).
16783
- // If so, resolve the expression *before* passing to createSubject so
16784
- // the constructor receives a valid URI instead of raw data.
16785
16992
  const propMeta = metadata.properties[key];
16786
- if (propMeta?.resolveLanguage && propMeta.resolveLanguage !== 'literal' && typeof value === 'object') {
16787
- // Defer these properties — they need createExpression which may
16788
- // fail inside a batch context on some languages. We'll set them
16789
- // via setProperty after createSubject.
16790
- deferredResolveLanguageProps.push(key);
16993
+ if (propMeta && effectiveLiteralStorage(propMeta).kind !== "deterministic") {
16994
+ deferredExpressionProps.push(key);
16791
16995
  continue;
16792
16996
  }
16793
16997
  initialValues[key] = value;
16794
16998
  }
16795
16999
  }
16796
- // Get the class name instead of passing the instance to avoid Prolog query generation
16797
17000
  const className = await this.perspective.stringOrTemplateObjectToSubjectClassName(this);
16798
- // Create the subject with the initial values
16799
17001
  await this.perspective.createSubject(className, this._baseExpression, initialValues, batchId);
16800
17002
  }
16801
17003
  // Set properties and relations via innerUpdate.
16802
17004
  // When createSubject was skipped (no constructor actions), we must enable
16803
17005
  // property writing so that scalar values are persisted as links.
16804
17006
  await this.innerUpdate(!hasConstructor, batchId);
16805
- // Now handle any deferred resolveLanguage properties that were excluded
16806
- // from initialValues. setProperty will call createExpression to upload
16807
- // the data to the appropriate language and store the resulting URI.
16808
- for (const key of deferredResolveLanguageProps) {
17007
+ for (const key of deferredExpressionProps) {
16809
17008
  const value = this[key];
16810
17009
  if (value !== undefined && value !== null) {
16811
17010
  await this.setProperty(key, value, batchId);
@@ -17100,7 +17299,7 @@ class Ad4mModel {
17100
17299
  * @param perspective - The perspective to create the instance in
17101
17300
  * @param data - Property values to assign before saving
17102
17301
  * @param options - Optional settings:
17103
- * - `parent` — a `ParentScope` (model form or raw form) whose `id` will
17302
+ * - `parent` — a `Scope` (model form or raw form) whose `id` will
17104
17303
  * be used to create an incoming link from the parent to the new instance.
17105
17304
  * - `batchId` — an existing batch id; when provided the link write and
17106
17305
  * `save()` are added to the batch instead of committed immediately.
@@ -17332,8 +17531,7 @@ class Ad4mModel {
17332
17531
  * // With explicit configuration
17333
17532
  * const PersonClass = Ad4mModel.fromJSONSchema(schema, {
17334
17533
  * name: "Person",
17335
- * namespace: "person://",
17336
- * resolveLanguage: "literal"
17534
+ * namespace: "person://"
17337
17535
  * });
17338
17536
  *
17339
17537
  * // With property mapping
@@ -17750,11 +17948,20 @@ var __metadata = (undefined && undefined.__metadata) || function (k, v) {
17750
17948
  // Mirrors the Rust `auto_processor::config::AutoProcessorConfig` SDNA.
17751
17949
  // One node per registered processor; the node URI is
17752
17950
  // `ad4m://autoprocessor/<processorId>`.
17951
+ // Model name = "AutoProcessor" (NOT "AutoProcessorConfig") to match the Rust
17952
+ // hardwired subject class in `perspectives/auto_processor/config.rs` — that
17953
+ // alignment is what the SDNA parity test in
17954
+ // `tests/js/tests/model/interpretation-models.test.ts` guards. The TS class
17955
+ // symbol keeps the `Config` suffix for readability (`AutoProcessorConfig` reads
17956
+ // better than a bare `AutoProcessor` for an "instances of the config record"
17957
+ // query), but the on-graph subject class it registers is `AutoProcessor`.
17753
17958
  let AutoProcessorConfig = class AutoProcessorConfig extends Ad4mModel {
17754
17959
  constructor() {
17755
17960
  super(...arguments);
17756
- this.type = "ad4m://AutoProcessor";
17757
17961
  /** Unique processor id — the dedup key for auto-processor instances. */
17962
+ // First-declared property: `buildSHACL` derives the shape namespace from
17963
+ // its `through` prefix, so `ad4m://processor_id` → `ad4m://` → target_class
17964
+ // `ad4m://AutoProcessor` (matches Rust `AUTO_PROCESSOR_TARGET_CLASS`).
17758
17965
  this.processorId = "";
17759
17966
  /** SPARQL SELECT that gathers source items each pass. */
17760
17967
  this.sourceScopeQuery = "";
@@ -17766,12 +17973,13 @@ let AutoProcessorConfig = class AutoProcessorConfig extends Ad4mModel {
17766
17973
  this.batchMax = "32";
17767
17974
  /** How long a won claim is authoritative before peers may re-claim (ms). */
17768
17975
  this.claimTtlMs = "60000";
17976
+ // No `@Flag` type discriminator (Nico 2026-08-19: "type flags are an
17977
+ // anti-pattern for subject classes; match over all the properties
17978
+ // instead"). Conformance is by the presence of `processorId` +
17979
+ // `sourceScopeQuery` + `interpretationClasses` + `debounceMs` +
17980
+ // `batchMax` + `claimTtlMs` — the Rust SDNA takes the same shape.
17769
17981
  }
17770
17982
  };
17771
- __decorate([
17772
- Flag({ through: "rdf://type", value: "ad4m://AutoProcessor" }),
17773
- __metadata("design:type", String)
17774
- ], AutoProcessorConfig.prototype, "type", void 0);
17775
17983
  __decorate([
17776
17984
  Property({ through: "ad4m://processor_id", required: true, identity: true }),
17777
17985
  __metadata("design:type", String)
@@ -17781,11 +17989,11 @@ __decorate([
17781
17989
  __metadata("design:type", String)
17782
17990
  ], AutoProcessorConfig.prototype, "sourceScopeQuery", void 0);
17783
17991
  __decorate([
17784
- Optional({ through: "ad4m://base_prefix", resolveLanguage: "literal" }),
17992
+ Optional({ through: "ad4m://base_prefix" }),
17785
17993
  __metadata("design:type", String)
17786
17994
  ], AutoProcessorConfig.prototype, "basePrefix", void 0);
17787
17995
  __decorate([
17788
- HasMany({ through: "ad4m://interpretation_class" }),
17996
+ HasMany({ through: "ad4m://interpretation_class", datatype: "xsd:string" }),
17789
17997
  __metadata("design:type", Array)
17790
17998
  ], AutoProcessorConfig.prototype, "interpretationClasses", void 0);
17791
17999
  __decorate([
@@ -17793,7 +18001,7 @@ __decorate([
17793
18001
  __metadata("design:type", String)
17794
18002
  ], AutoProcessorConfig.prototype, "debounceMs", void 0);
17795
18003
  __decorate([
17796
- Optional({ through: "ad4m://batch_min", resolveLanguage: "literal" }),
18004
+ Optional({ through: "ad4m://batch_min" }),
17797
18005
  __metadata("design:type", String)
17798
18006
  ], AutoProcessorConfig.prototype, "batchMin", void 0);
17799
18007
  __decorate([
@@ -17801,7 +18009,7 @@ __decorate([
17801
18009
  __metadata("design:type", String)
17802
18010
  ], AutoProcessorConfig.prototype, "batchMax", void 0);
17803
18011
  __decorate([
17804
- Optional({ through: "ad4m://max_wait_ms", resolveLanguage: "literal" }),
18012
+ Optional({ through: "ad4m://max_wait_ms" }),
17805
18013
  __metadata("design:type", String)
17806
18014
  ], AutoProcessorConfig.prototype, "maxWaitMs", void 0);
17807
18015
  __decorate([
@@ -17809,61 +18017,89 @@ __decorate([
17809
18017
  __metadata("design:type", String)
17810
18018
  ], AutoProcessorConfig.prototype, "claimTtlMs", void 0);
17811
18019
  __decorate([
17812
- Optional({ through: "ad4m://source_window_ms", resolveLanguage: "literal" }),
18020
+ Optional({ through: "ad4m://source_window_ms" }),
17813
18021
  __metadata("design:type", String)
17814
18022
  ], AutoProcessorConfig.prototype, "sourceWindowMs", void 0);
17815
18023
  __decorate([
17816
- Optional({ through: "ad4m://dedup_strategy", resolveLanguage: "literal" }),
18024
+ Optional({ through: "ad4m://dedup_strategy" }),
17817
18025
  __metadata("design:type", String)
17818
18026
  ], AutoProcessorConfig.prototype, "dedupStrategy", void 0);
18027
+ __decorate([
18028
+ Optional({ through: "ad4m://existing_scope" }),
18029
+ __metadata("design:type", String)
18030
+ ], AutoProcessorConfig.prototype, "existingScope", void 0);
18031
+ __decorate([
18032
+ Optional({ through: "ad4m://mint_scope" }),
18033
+ __metadata("design:type", String)
18034
+ ], AutoProcessorConfig.prototype, "mintScope", void 0);
18035
+ __decorate([
18036
+ Optional({ through: "ad4m://debug_mode", resolveLanguage: "literal" }),
18037
+ __metadata("design:type", String)
18038
+ ], AutoProcessorConfig.prototype, "debugMode", void 0);
18039
+ __decorate([
18040
+ Optional({ through: "ad4m://persist_debug", resolveLanguage: "literal" }),
18041
+ __metadata("design:type", String)
18042
+ ], AutoProcessorConfig.prototype, "persistDebug", void 0);
18043
+ __decorate([
18044
+ Optional({ through: "ad4m://emit_debug_events", resolveLanguage: "literal" }),
18045
+ __metadata("design:type", String)
18046
+ ], AutoProcessorConfig.prototype, "emitDebugEvents", void 0);
17819
18047
  AutoProcessorConfig = __decorate([
17820
- Model$1({ name: "AutoProcessorConfig" })
18048
+ Model$1({ name: "AutoProcessor" })
17821
18049
  ], AutoProcessorConfig);
17822
18050
  // ── InterpretationRun ───────────────────────────────────────────────────────
17823
18051
  // Mirrors the Rust `interpretation::overlay::InterpretationRun` SDNA.
17824
18052
  // One node per completed pass; the node URI is `ad4m://interp/run/<runId>`.
17825
18053
  let InterpretationRun = class InterpretationRun extends Ad4mModel {
17826
18054
  constructor() {
18055
+ // No `@Flag` type discriminator — Rust SDNA drops `ad4m://type` too.
18056
+ // Conformance is by `runId` (identity) — same pattern
18057
+ // `InterpretationOverlay` already uses (`kind` is its discriminator).
17827
18058
  super(...arguments);
17828
- this.type = "ad4m://interpretation-run";
17829
18059
  /** UUID for this run — the dedup key across run nodes. */
17830
18060
  this.runId = "";
17831
18061
  /**
17832
18062
  * Source item IDs consumed by this pass.
17833
18063
  * Stored as multiple links with the same predicate; the processed-turn
17834
- * cursor uses these to avoid re-interpreting a turn.
18064
+ * cursor uses these to avoid re-interpreting a turn. Values are plain
18065
+ * strings (turn hex), so the property opts into `sh:datatype`-gated
18066
+ * literal decoding on hydration.
17835
18067
  */
17836
18068
  this.sources = [];
17837
18069
  }
17838
18070
  };
17839
- __decorate([
17840
- Flag({ through: "ad4m://type", value: "ad4m://interpretation-run" }),
17841
- __metadata("design:type", String)
17842
- ], InterpretationRun.prototype, "type", void 0);
17843
18071
  __decorate([
17844
18072
  Property({ through: "ad4m://interp/run_id", required: true, identity: true }),
17845
18073
  __metadata("design:type", String)
17846
18074
  ], InterpretationRun.prototype, "runId", void 0);
17847
18075
  __decorate([
17848
- Optional({ through: "ad4m://interp/model", resolveLanguage: "literal" }),
18076
+ Optional({ through: "ad4m://interp/model" }),
17849
18077
  __metadata("design:type", String)
17850
18078
  ], InterpretationRun.prototype, "model", void 0);
17851
18079
  __decorate([
17852
- Optional({ through: "ad4m://interp/prompt_version", resolveLanguage: "literal" }),
18080
+ Optional({ through: "ad4m://interp/prompt_version" }),
17853
18081
  __metadata("design:type", String)
17854
18082
  ], InterpretationRun.prototype, "promptVersion", void 0);
17855
18083
  __decorate([
17856
- Optional({ through: "ad4m://interp/ran_at", resolveLanguage: "literal" }),
18084
+ Optional({ through: "ad4m://interp/ran_at" }),
17857
18085
  __metadata("design:type", String)
17858
18086
  ], InterpretationRun.prototype, "ranAt", void 0);
17859
18087
  __decorate([
17860
- Optional({ through: "ad4m://interp/processor", resolveLanguage: "literal" }),
18088
+ Optional({ through: "ad4m://interp/processor" }),
17861
18089
  __metadata("design:type", String)
17862
18090
  ], InterpretationRun.prototype, "processor", void 0);
17863
18091
  __decorate([
17864
- HasMany({ through: "ad4m://interp/sources" }),
18092
+ HasMany({ through: "ad4m://interp/sources", datatype: "xsd:string" }),
17865
18093
  __metadata("design:type", Array)
17866
18094
  ], InterpretationRun.prototype, "sources", void 0);
18095
+ __decorate([
18096
+ Optional({ through: "ad4m://interp/debug_prompt", resolveLanguage: "literal" }),
18097
+ __metadata("design:type", String)
18098
+ ], InterpretationRun.prototype, "debugPrompt", void 0);
18099
+ __decorate([
18100
+ Optional({ through: "ad4m://interp/debug_response", resolveLanguage: "literal" }),
18101
+ __metadata("design:type", String)
18102
+ ], InterpretationRun.prototype, "debugResponse", void 0);
17867
18103
  InterpretationRun = __decorate([
17868
18104
  Model$1({ name: "InterpretationRun" })
17869
18105
  ], InterpretationRun);
@@ -17895,11 +18131,11 @@ let InterpretationOverlay = class InterpretationOverlay extends Ad4mModel {
17895
18131
  }
17896
18132
  };
17897
18133
  __decorate([
17898
- Property({ through: "ad4m://interp/kind", required: true, resolveLanguage: "literal" }),
18134
+ Property({ through: "ad4m://interp/kind", required: true }),
17899
18135
  __metadata("design:type", String)
17900
18136
  ], InterpretationOverlay.prototype, "kind", void 0);
17901
18137
  __decorate([
17902
- Optional({ through: "ad4m://interp/run", resolveLanguage: "literal" }),
18138
+ Optional({ through: "ad4m://interp/run" }),
17903
18139
  __metadata("design:type", String)
17904
18140
  ], InterpretationOverlay.prototype, "run", void 0);
17905
18141
  InterpretationOverlay = __decorate([
@@ -17938,23 +18174,74 @@ function parseSparqlCount(result) {
17938
18174
  /**
17939
18175
  * Decode a `Literal`-encoded SPARQL binding back to a plain string.
17940
18176
  *
17941
- * Mirrors Flux's local `parseLit` helper. Returns `''` for `undefined`/empty
17942
- * input. Falls through to the raw value if decoding fails (defensive — the
17943
- * binding may already be a plain string for unwrapped properties).
18177
+ * Returns `''` for `undefined`/empty input. Falls through to the raw value
18178
+ * if decoding fails — bindings against properties resolved through a custom
18179
+ * language are already raw URIs and should pass through unchanged.
18180
+ *
18181
+ * Signed-envelope literals
18182
+ * ------------------------
18183
+ * Properties declared with `resolveLanguage: 'literal'` are written through
18184
+ * the built-in `literal` language, which wraps the value in a signed
18185
+ * expression envelope (`{ author, timestamp, data, proof }`) and encodes
18186
+ * the whole envelope as a `literal:json:` URL — see
18187
+ * `rust-executor/src/languages/mod.rs::expression_create` (literal branch).
18188
+ * On read, `parseLit` unwraps `.data` from that envelope so callers get the
18189
+ * original scalar value instead of the envelope JSON.
18190
+ *
18191
+ * The Channel V refactor moved most scalar properties to deterministic
18192
+ * typed XSD literals which no longer round-trip through this envelope — for
18193
+ * those properties the SPARQL binding is already the lexical form and this
18194
+ * helper decodes to the primitive. Signed-envelope literals still exist
18195
+ * for any property that opts back into `resolveLanguage: 'literal'` (e.g.
18196
+ * per-message provenance for chat bodies), which is why the `.data` unwrap
18197
+ * is preserved here.
18198
+ *
18199
+ * Non-envelope JSON objects (`literal:json:` payloads that are not signed
18200
+ * envelopes) are JSON-stringified for display.
17944
18201
  */
17945
18202
  function parseLit(val) {
17946
18203
  if (val === undefined || val === null || val === '')
17947
18204
  return '';
18205
+ // Fast-path 1: `literal:*` URLs from properties written through the built-in
18206
+ // `literal` language. On Channel V typed-XSD-literal properties, these
18207
+ // decode straight to a primitive; on `resolveLanguage: 'literal'` properties
18208
+ // (per-message provenance in chat/synergy) they decode to a signed-envelope
18209
+ // object we unwrap via `.data`.
17948
18210
  try {
17949
18211
  const result = Literal.fromUrl(val).get();
17950
- if (result && typeof result === 'object') {
17951
- return result.data ?? JSON.stringify(result);
18212
+ if (typeof result === 'object' && result !== null) {
18213
+ const data = result.data;
18214
+ if (typeof data === 'string')
18215
+ return data;
18216
+ return JSON.stringify(result);
17952
18217
  }
17953
18218
  return String(result);
17954
18219
  }
17955
18220
  catch {
17956
- return val;
18221
+ // fall through to plain-JSON envelope detection
18222
+ }
18223
+ // Fast-path 2: envelope stored/returned as a bare JSON string rather than a
18224
+ // `literal:json:*` URL. Depending on the storage backend and query path,
18225
+ // SPARQL bindings for `resolveLanguage: 'literal'` properties can surface
18226
+ // the envelope object directly as its JSON serialisation (Oxigraph typed
18227
+ // xsd:string of the JSON, or a Channel V pass-through) instead of the URL
18228
+ // form. Detect that shape by parsing the string and unwrapping `.data`
18229
+ // when it looks like a signed envelope; anything else passes through
18230
+ // unchanged so plain text (e.g. "just a string") is not corrupted.
18231
+ if (val.length >= 2 && val.charCodeAt(0) === 0x7b /* '{' */) {
18232
+ try {
18233
+ const parsed = JSON.parse(val);
18234
+ if (parsed && typeof parsed === 'object') {
18235
+ const data = parsed.data;
18236
+ if (typeof data === 'string')
18237
+ return data;
18238
+ }
18239
+ }
18240
+ catch {
18241
+ // not JSON — fall through and return the raw value
18242
+ }
17957
18243
  }
18244
+ return val;
17958
18245
  }
17959
18246
  /** Decode a `Literal`-encoded binding to a number. Returns 0 on empty/invalid input. */
17960
18247
  function parseLitNumber(val) {
@@ -18304,16 +18591,21 @@ function formatQueryValue(value) {
18304
18591
  *
18305
18592
  * @param predicate - The predicate URI for the property
18306
18593
  * @param condition - The Where condition value
18307
- * @param opts - Optional settings (e.g. `resolveLanguage`)
18594
+ * @param opts - Optional settings. `isDeterministicLiteral` (default
18595
+ * `true`) selects the direct typed-literal WHERE path.
18596
+ * Set to `false` when the property stores a signed
18597
+ * envelope (`resolveLanguage: "literal"`) or a
18598
+ * custom-language expression — the envelope path unwraps
18599
+ * with `parse_literal` before comparing.
18308
18600
  * @returns A single SPARQL condition string
18309
18601
  */
18310
18602
  function buildWhereCondition(predicate, condition, opts) {
18311
18603
  const escapedPredicate = escapeQueryString(predicate);
18312
- // For literal-resolved properties, we match against the raw IRI (which is a literal: URI)
18313
- // For language-resolved properties, we match against the plain URI
18314
- // For literal-resolved properties, values are stored as IRIs like <literal:string:VALUE>
18315
- // For language-resolved properties, values are plain URIs
18316
- const isLiteral = !opts?.resolveLanguage || opts.resolveLanguage === 'literal';
18604
+ // For deterministic-literal properties, values are stored as typed
18605
+ // literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
18606
+ // IRI form). For envelope / custom-language properties the target is a
18607
+ // signed expression URI; comparisons need to unwrap via `parse_literal`.
18608
+ const isLiteral = opts?.isDeterministicLiteral !== false;
18317
18609
  const varSuffix = opts?.varIndex ?? 0;
18318
18610
  function formatValue(v) {
18319
18611
  if (typeof v === 'string') {
@@ -18422,23 +18714,28 @@ function compileWhereClause(where, metadata) {
18422
18714
  if (['id', 'author', 'timestamp'].includes(propertyName))
18423
18715
  continue;
18424
18716
  let predicate;
18425
- let resolveLanguage;
18717
+ // Storage mode is derived from `resolveLanguage` alone:
18718
+ // - undefined → deterministic typed literal (fast POS-index path)
18719
+ // - "literal" → signed envelope on the literal language
18720
+ // - custom address → expression on that custom language
18721
+ // Envelope and custom-language properties both need the `parse_literal`
18722
+ // unwrap path, so we treat any `resolveLanguage`-carrying property as
18723
+ // non-deterministic here.
18724
+ let isDeterministicLiteral;
18426
18725
  if (metadata) {
18427
18726
  const propMeta = metadata.properties[propertyName];
18428
18727
  if (propMeta) {
18429
18728
  predicate = propMeta.predicate;
18430
- resolveLanguage = propMeta.resolveLanguage;
18729
+ isDeterministicLiteral = propMeta.resolveLanguage === undefined;
18431
18730
  }
18432
18731
  else {
18433
- // Property not found in metadata — treat name as raw predicate URI
18434
18732
  predicate = propertyName;
18435
18733
  }
18436
18734
  }
18437
18735
  else {
18438
- // No metadata — treat name as raw predicate URI
18439
18736
  predicate = propertyName;
18440
18737
  }
18441
- const cond = buildWhereCondition(predicate, condition, { resolveLanguage, varIndex: conditions.length });
18738
+ const cond = buildWhereCondition(predicate, condition, { isDeterministicLiteral, varIndex: conditions.length });
18442
18739
  if (cond) {
18443
18740
  conditions.push(cond);
18444
18741
  }
@@ -18574,7 +18871,7 @@ function fn(iri, args = []) {
18574
18871
  * ```typescript
18575
18872
  * @Property({
18576
18873
  * through: 'we://image',
18577
- * resolveLanguage: FILE_STORAGE_LANGUAGE,
18874
+ * resolveLanguage: 'literal',
18578
18875
  * transform: fileToDataUri,
18579
18876
  * })
18580
18877
  * avatar?: string;
@@ -18584,4 +18881,4 @@ const fileToDataUri = ifExpr(exists(path('file_storage://data_base64')))
18584
18881
  .then(concat(literal('data:'), coalesce(path('file_storage://file_type'), literal('image/png')), literal(';base64,'), path('file_storage://data_base64')))
18585
18882
  .else(focus());
18586
18883
 
18587
- export { AIClient, Model as AIModel, AIModelLoadingStatus, AIPromptExamples, AIPromptExamplesInput, AITask, AITaskInput, Ad4mClient, Ad4mModel, Agent, AgentClient, AgentExpression, AgentSignature, AgentStatus, Apps, AuthInfo, AuthInfoInput, AutoProcessorConfig, BelongsToMany, BelongsToOne, Capability, CapabilityInput, ComputeLogEntry, EntanglementProof, EntanglementProofInput, ExceptionInfo, ExceptionType, Expression, ExpressionGeneric, ExpressionGenericInput, ExpressionProof, ExpressionProofInput, ExpressionRef, ExpressionRendered, Flag, HasMany, HasOne, HostingUserInfo, IDBCache, Icon, ImportResult, ImportStats, InteractionCall, InteractionMeta, InteractionParameter, InterpretationOverlay, InterpretationRun, LanguageExpression, LanguageHandle, LanguageLanguageInput, LanguageMeta, LanguageMetaInput, LanguageMetaInternal, LanguageRef, Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkExpressionUpdated, LinkInput, LinkMutations, LinkQuery, Literal, LocalModel, LocalModelInput, Model$1 as Model, ModelApi, ModelApiInput, ModelInput, ModelQueryBuilder, Neighbourhood, NeighbourhoodExpression, NeighbourhoodProxy, Notification, NotificationInput, NullCache, OnlineAgent, Optional, PaymentRequestResult, Perspective, PerspectiveDiff, PerspectiveDiffExpression, PerspectiveExpression, PerspectiveHandle, PerspectiveInput, PerspectiveProxy, PerspectiveState, PerspectiveUnsignedInput, Property, QuerySubscriptionProxy, ReadOnly, Resource, ResourceInput, RpcError as RestError, RpcError, RuntimeInfo, SHACLFlow, SHACLShape, SMART_LITERAL_CONTENT_PREDICATE, SentMessage, SmartLiteral, TokenizerSource, TokenizerSourceInput, TriggeredNotification, UserCreationResult, UserStatistics, VerificationRequestResult, VoiceActivityParamsInput, WakerSubscriptionManager, buildConformanceFilter, buildModelFromJSONSchema, buildPaginationSubquery, buildSDNA, buildSHACL, buildSPARQLQuery, buildWhereCondition, capSentence, clearQueryCache, coalesce, compileWhereClause, concat, createPersistentCache, determineNamespace, determinePredicate, escapeQueryString, exists, exprRef2String, fileToDataUri, fn, focus, formatList, formatQueryValue, formatSPARQLValue, getCachedResult, getDefaultValueForType, getMemoizedSHACL, getPropertiesMetadata, getPropertyOption, getRelationsMetadata, hasJsOnlyWhereFilters, ifExpr, invalidatePerspectiveCache, isArrayType, isExpression, isIncludeProjection, isLink, isNodeExpression, isNumericType, isObjectType, isSchemaType, linkEqual, literal, normalizeNamespaceString, normalizeSchemaType, normalizeValue, parseExprUrl, parseLit, parseLitBoolean, parseLitNumber, parseSparqlCount, path, queryCacheSize, resolveParentPredicate, setCachedResult, setPropertyRegistryEntry, setRelationRegistryEntry, typeDefsString };
18884
+ export { AIClient, Model as AIModel, AIModelLoadingStatus, AIPromptExamples, AIPromptExamplesInput, AITask, AITaskInput, Ad4mClient, Ad4mModel, Agent, AgentClient, AgentExpression, AgentSignature, AgentStatus, Apps, AuthInfo, AuthInfoInput, AutoProcessorConfig, BelongsToMany, BelongsToOne, Capability, CapabilityInput, ComputeLogEntry, EntanglementProof, EntanglementProofInput, ExceptionInfo, ExceptionType, Expression, ExpressionGeneric, ExpressionGenericInput, ExpressionProof, ExpressionProofInput, ExpressionRef, ExpressionRendered, Flag, HasMany, HasOne, HostingUserInfo, IDBCache, Icon, ImportResult, ImportStats, InteractionCall, InteractionMeta, InteractionParameter, InterpretationOverlay, InterpretationRun, LanguageExpression, LanguageHandle, LanguageLanguageInput, LanguageMeta, LanguageMetaInput, LanguageMetaInternal, LanguageRef, Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkExpressionUpdated, LinkInput, LinkMutations, LinkQuery, Literal, LocalModel, LocalModelInput, Model$1 as Model, ModelApi, ModelApiInput, ModelInput, ModelQueryBuilder, Neighbourhood, NeighbourhoodExpression, NeighbourhoodProxy, Notification, NotificationInput, NullCache, OnlineAgent, Optional, PaymentRequestResult, Perspective, PerspectiveDiff, PerspectiveDiffExpression, PerspectiveExpression, PerspectiveHandle, PerspectiveInput, PerspectiveProxy, PerspectiveState, PerspectiveUnsignedInput, Property, QuerySubscriptionProxy, ReadOnly, Resource, ResourceInput, RpcError as RestError, RpcError, RuntimeInfo, SHACLFlow, SHACLShape, SMART_LITERAL_CONTENT_PREDICATE, SentMessage, SmartLiteral, TokenizerSource, TokenizerSourceInput, TriggeredNotification, UserCreationResult, UserStatistics, VerificationRequestResult, VoiceActivityParamsInput, WakerSubscriptionManager, buildConformanceFilter, buildModelFromJSONSchema, buildPaginationSubquery, buildSDNA, buildSHACL, buildSPARQLQuery, buildWhereCondition, capSentence, clearQueryCache, coalesce, compileWhereClause, concat, createPersistentCache, determineNamespace, determinePredicate, effectiveLiteralStorage, escapeQueryString, exists, exprRef2String, fileToDataUri, fn, focus, formatList, formatQueryValue, formatSPARQLValue, getCachedResult, getDefaultValueForType, getMemoizedSHACL, getPropertiesMetadata, getPropertyOption, getRelationsMetadata, hasJsOnlyWhereFilters, ifExpr, invalidatePerspectiveCache, isArrayType, isExpression, isIncludeProjection, isLink, isNodeExpression, isNumericType, isObjectType, isSchemaType, linkEqual, literal, looksLikeUri, normalizeNamespaceString, normalizeSchemaType, normalizeValue, parseExprUrl, parseLit, parseLitBoolean, parseLitNumber, parseSparqlCount, path, queryCacheSize, resolveParentPredicate, setCachedResult, setPropertyRegistryEntry, setRelationRegistryEntry, typeDefsString, valueToLiteralIri };