@coasys/ad4m 0.13.0-test-interpretation → 0.13.0-test-interpretation-2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/lib/index.cjs +451 -149
  2. package/lib/index.js +449 -150
  3. package/lib/src/Literal.js +8 -0
  4. package/lib/src/generated/api/RunInterpretationRequest.d.ts +16 -0
  5. package/lib/src/model/Ad4mModel.d.ts +28 -11
  6. package/lib/src/model/Ad4mModel.js +57 -35
  7. package/lib/src/model/ModelQueryBuilder.js +2 -2
  8. package/lib/src/model/decorators.d.ts +52 -8
  9. package/lib/src/model/decorators.js +18 -8
  10. package/lib/src/model/json-schema.js +7 -21
  11. package/lib/src/model/query-common.d.ts +2 -2
  12. package/lib/src/model/query-sparql.d.ts +62 -0
  13. package/lib/src/model/query-sparql.js +78 -15
  14. package/lib/src/model/query-utils.d.ts +7 -2
  15. package/lib/src/model/query-utils.js +21 -11
  16. package/lib/src/model/shacl-gen.js +44 -15
  17. package/lib/src/model/types.d.ts +23 -8
  18. package/lib/src/perspectives/AutoProcessor.d.ts +132 -2
  19. package/lib/src/perspectives/InterpretationModels.d.ts +51 -3
  20. package/lib/src/perspectives/InterpretationModels.js +64 -26
  21. package/lib/src/perspectives/PerspectiveClient.d.ts +22 -2
  22. package/lib/src/perspectives/PerspectiveClient.js +35 -3
  23. package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -1
  24. package/lib/src/perspectives/PerspectiveProxy.js +24 -14
  25. package/lib/src/perspectives/SparqlBindings.d.ts +24 -3
  26. package/lib/src/perspectives/SparqlBindings.js +57 -6
  27. package/lib/src/shacl/SHACLShape.d.ts +11 -3
  28. package/lib/src/shacl/SHACLShape.js +15 -1
  29. package/lib/src/shacl/index.d.ts +1 -1
  30. package/lib/src/shacl/index.js +1 -1
  31. package/package.json +2 -2
  32. package/src/Literal.ts +7 -0
  33. package/src/generated/api/RunInterpretationRequest.ts +19 -3
  34. package/src/model/Ad4mModel.test.ts +84 -22
  35. package/src/model/Ad4mModel.ts +61 -41
  36. package/src/model/ModelQueryBuilder.ts +2 -2
  37. package/src/model/decorators.ts +62 -9
  38. package/src/model/json-schema.ts +10 -25
  39. package/src/model/query-common.ts +2 -2
  40. package/src/model/query-sparql.test.ts +114 -13
  41. package/src/model/query-sparql.ts +83 -14
  42. package/src/model/query-utils.ts +22 -12
  43. package/src/model/shacl-gen.ts +42 -13
  44. package/src/model/shacl-roundtrip.test.ts +4 -2
  45. package/src/model/types.ts +23 -8
  46. package/src/perspectives/AutoProcessor.ts +133 -1
  47. package/src/perspectives/InterpretationModels.ts +103 -21
  48. package/src/perspectives/PerspectiveClient.ts +50 -4
  49. package/src/perspectives/PerspectiveProxy.ts +37 -21
  50. package/src/perspectives/SparqlBindings.test.ts +134 -0
  51. package/src/perspectives/SparqlBindings.ts +57 -6
  52. package/src/shacl/SHACLShape.test.ts +56 -4
  53. package/src/shacl/SHACLShape.ts +30 -6
  54. package/src/shacl/index.ts +1 -1
@@ -325,13 +325,7 @@ export function buildModelFromJSONSchema(
325
325
 
326
326
  } else {
327
327
  // Handle regular properties
328
- let resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
329
- // If no specific resolveLanguage for this property, use the global one
330
- if (!resolveLanguage && options.resolveLanguage) {
331
- resolveLanguage = options.resolveLanguage;
332
- }
333
328
  const local = getPropertyOption(propertyName, propertySchema, options, 'local');
334
- // Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
335
329
  let readOnly = getPropertyOption(propertyName, propertySchema, options, 'readOnly');
336
330
  if (readOnly === undefined) {
337
331
  const xWritable = propertySchema["x-ad4m"]?.writable;
@@ -339,26 +333,17 @@ export function buildModelFromJSONSchema(
339
333
  }
340
334
  const writable = !readOnly;
341
335
  let initial = getPropertyOption(propertyName, propertySchema, options, 'initial');
342
-
343
- // Handle nested objects by serializing to JSON
344
- if (isObjectType(propertySchema) && !resolveLanguage) {
345
- resolveLanguage = 'literal';
346
- console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
347
- }
348
336
 
349
- // Ensure numeric properties use literal language for correct typing
350
- if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
351
- resolveLanguage = 'literal';
352
- }
337
+ // Not defaulted — absence means "deterministic typed literal" (the
338
+ // perf default); an explicit `resolveLanguage: "literal"` selects the
339
+ // signed-envelope path; any other value selects a custom language.
340
+ // See effectiveLiteralStorage().
341
+ const resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
353
342
 
354
- // Default resolveLanguage to 'literal' for all remaining property types,
355
- // matching the @Property decorator behaviour. Without this, string values
356
- // stored as literal: URLs are returned unparsed.
357
- if (resolveLanguage === undefined || resolveLanguage === null) {
358
- resolveLanguage = 'literal';
343
+ if (isObjectType(propertySchema)) {
344
+ console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
359
345
  }
360
-
361
- // If property is required, ensure it has an initial value
346
+
362
347
  if (isRequired && !initial) {
363
348
  if (isObjectType(propertySchema)) {
364
349
  initial = 'literal:json:{}';
@@ -366,12 +351,12 @@ export function buildModelFromJSONSchema(
366
351
  initial = "ad4m://undefined";
367
352
  }
368
353
  }
369
-
354
+
370
355
  properties[propertyName] = {
371
356
  through: predicate,
372
357
  required: isRequired,
373
358
  writable: writable,
374
- ...(resolveLanguage && { resolveLanguage }),
359
+ ...(resolveLanguage !== undefined && { resolveLanguage }),
375
360
  ...(local !== undefined && { local }),
376
361
  ...(initial && { initial })
377
362
  };
@@ -2,7 +2,7 @@
2
2
  * Shared query helpers used by both the Prolog and SPARQL query pipelines.
3
3
  */
4
4
 
5
- import type { ParentScope } from "./types";
5
+ import type { Scope } from "./types";
6
6
  import { getRelationsMetadata } from "./decorators";
7
7
 
8
8
  /**
@@ -15,7 +15,7 @@ import { getRelationsMetadata } from "./decorators";
15
15
  * - Without `field`: scan for a relation whose `target()` matches `childCtor`
16
16
  */
17
17
  export function resolveParentPredicate(
18
- parent: ParentScope,
18
+ parent: Scope,
19
19
  childCtor: Function,
20
20
  ): string {
21
21
  // Raw form — explicit predicate
@@ -1,28 +1,29 @@
1
- import { buildSPARQLQuery, buildPaginationSubquery, hasJsOnlyWhereFilters } from './query-sparql';
1
+ import { buildSPARQLQuery, buildPaginationSubquery, hasJsOnlyWhereFilters, looksLikeUri, valueToLiteralIri } from './query-sparql';
2
+ import { Literal } from '../Literal';
2
3
 
3
4
  // Minimal stubs for ModelMetadata
4
5
  const emptyMetadata: any = { properties: {}, relations: {} };
5
6
 
6
- // Metadata with a required (non-literal) property and a literal-stored property
7
+ // Metadata with a deterministic-literal property (`name`), a signed-envelope
8
+ // property (`category`, `resolveLanguage: "literal"`), and another
9
+ // deterministic-literal property with an initial value (`description`).
7
10
  const richMetadata: any = {
8
11
  properties: {
9
12
  name: {
10
13
  name: 'name',
11
14
  predicate: 'flux://name',
12
15
  required: true,
13
- resolveLanguage: 'literal',
14
16
  },
15
17
  category: {
16
18
  name: 'category',
17
19
  predicate: 'flux://category',
18
20
  required: true,
19
- resolveLanguage: 'did:lang:abc', // non-literal → URI stored
21
+ resolveLanguage: 'literal', // envelope → expression URI stored
20
22
  },
21
23
  description: {
22
24
  name: 'description',
23
25
  predicate: 'flux://description',
24
26
  initial: 'literal://string:empty',
25
- resolveLanguage: 'literal',
26
27
  },
27
28
  },
28
29
  relations: {},
@@ -41,7 +42,7 @@ describe('hasJsOnlyWhereFilters', () => {
41
42
 
42
43
  it('returns true when where has literal-stored property with comparison operator', () => {
43
44
  // gt/lt/gte/lte/between/contains remain JS-only
44
- const meta: any = { properties: { rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' } }, relations: {} };
45
+ const meta: any = { properties: { rating: { name: 'rating', predicate: 'flux://rating', required: true } }, relations: {} };
45
46
  expect(hasJsOnlyWhereFilters(meta, emptyRelations, { rating: { gt: 5 } })).toBe(true);
46
47
  });
47
48
 
@@ -113,7 +114,7 @@ describe('buildSPARQLQuery — parse_literal push-down filters', () => {
113
114
  it('does NOT use parse_literal for comparison operators (gt/lt)', () => {
114
115
  const meta: any = {
115
116
  properties: {
116
- rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
117
+ rating: { name: 'rating', predicate: 'flux://rating', required: true },
117
118
  },
118
119
  relations: {},
119
120
  };
@@ -204,8 +205,8 @@ describe('buildSPARQLQuery — mixed push-down + JS-only', () => {
204
205
  const modelClass: any = {};
205
206
  const mixedMeta: any = {
206
207
  properties: {
207
- name: { name: 'name', predicate: 'flux://name', required: true, resolveLanguage: 'literal' },
208
- rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
208
+ name: { name: 'name', predicate: 'flux://name', required: true },
209
+ rating: { name: 'rating', predicate: 'flux://rating', required: true },
209
210
  },
210
211
  relations: {},
211
212
  };
@@ -224,10 +225,14 @@ describe('buildSPARQLQuery — mixed push-down + JS-only', () => {
224
225
  describe('buildSPARQLQuery — non-literal and flag properties', () => {
225
226
  const modelClass: any = {};
226
227
 
227
- it('does NOT use parse_literal for non-literal (resolveLanguage) properties', () => {
228
+ it('does NOT use parse_literal for envelope (resolveLanguage: "literal") properties', () => {
229
+ // Envelope properties store signed expression URIs in the target position,
230
+ // not raw literals — the value comparison happens on the unwrapped inner
231
+ // data via a different code path (Rust `parse_literal_fn`), not by the JS
232
+ // WHERE builder emitting a `<ad4m://fn/parse_literal>` filter here.
228
233
  const meta: any = {
229
234
  properties: {
230
- avatar: { name: 'avatar', predicate: 'flux://avatar', required: true, resolveLanguage: 'did:lang:some-language' },
235
+ avatar: { name: 'avatar', predicate: 'flux://avatar', required: true, resolveLanguage: 'literal' },
231
236
  },
232
237
  relations: {},
233
238
  };
@@ -312,7 +317,7 @@ describe('SPARQL-level pagination', () => {
312
317
  it('does NOT push pagination to SPARQL when JS-only where filters exist (gt operator)', () => {
313
318
  const meta: any = {
314
319
  properties: {
315
- rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
320
+ rating: { name: 'rating', predicate: 'flux://rating', required: true },
316
321
  },
317
322
  relations: {},
318
323
  };
@@ -340,7 +345,7 @@ describe('buildSPARQLQuery — set-difference patterns', () => {
340
345
  it('generates global EXISTS without parent scoping when no parent filter', () => {
341
346
  const meta: any = {
342
347
  properties: {
343
- status: { name: 'status', predicate: 'flux://status', required: true, resolveLanguage: 'literal' },
348
+ status: { name: 'status', predicate: 'flux://status', required: true },
344
349
  },
345
350
  relations: {},
346
351
  };
@@ -522,3 +527,99 @@ describe('buildSPARQLQuery — OR/AND/NOT not emitted as SPARQL (handled Rust-si
522
527
  expect(sparql).not.toContain('LIMIT');
523
528
  });
524
529
  });
530
+
531
+ // ──────────────────────────────────────────────────────────
532
+ // valueToLiteralIri — object/array encoding parity with Rust
533
+ // ──────────────────────────────────────────────────────────
534
+
535
+ describe('valueToLiteralIri', () => {
536
+ it('encodes plain objects as literal:json:* and round-trips', () => {
537
+ const url = valueToLiteralIri({ a: 1 });
538
+ expect(url.startsWith('literal:json:')).toBe(true);
539
+ // Regression: previously fell through to String(value) → "[object Object]"
540
+ expect(url).not.toContain('object%20Object');
541
+ expect(Literal.fromUrl(url).get()).toEqual({ a: 1 });
542
+ });
543
+
544
+ it('encodes arrays as literal:json:* and round-trips', () => {
545
+ const url = valueToLiteralIri([1, 2, 3]);
546
+ expect(url.startsWith('literal:json:')).toBe(true);
547
+ // Regression: previously stringified to "1,2,3"
548
+ expect(url).not.toBe('literal:string:1%2C2%2C3');
549
+ expect(Literal.fromUrl(url).get()).toEqual([1, 2, 3]);
550
+ });
551
+
552
+ it('encodes nested objects and round-trips', () => {
553
+ const url = valueToLiteralIri({ nested: { b: 2 } });
554
+ expect(url.startsWith('literal:json:')).toBe(true);
555
+ expect(Literal.fromUrl(url).get()).toEqual({ nested: { b: 2 } });
556
+ });
557
+
558
+ it('preserves string encoding (non-URI)', () => {
559
+ const url = valueToLiteralIri('hello world');
560
+ expect(url).toBe('literal:string:hello%20world');
561
+ expect(Literal.fromUrl(url).get()).toBe('hello world');
562
+ });
563
+
564
+ it('returns URI-like strings unchanged', () => {
565
+ expect(valueToLiteralIri('https://example.com/thing')).toBe('https://example.com/thing');
566
+ });
567
+
568
+ it('encodes numbers as literal:number:*', () => {
569
+ const url = valueToLiteralIri(42);
570
+ expect(url).toBe('literal:number:42');
571
+ expect(Literal.fromUrl(url).get()).toBe(42);
572
+ });
573
+
574
+ it('encodes booleans as literal:boolean:*', () => {
575
+ const url = valueToLiteralIri(true);
576
+ expect(url).toBe('literal:boolean:true');
577
+ expect(Literal.fromUrl(url).get()).toBe(true);
578
+ });
579
+
580
+ it('encodes null via the String() fallthrough as literal:string:null', () => {
581
+ // `null` is `typeof 'object'` in JS, but `Literal.from(null).toUrl()`
582
+ // throws on the empty-literal check, so the `value !== null` guard
583
+ // deliberately keeps `null` on the historical fallthrough path.
584
+ const url = valueToLiteralIri(null);
585
+ expect(url).toBe('literal:string:null');
586
+ expect(Literal.fromUrl(url).get()).toBe('null');
587
+ });
588
+ });
589
+
590
+
591
+ // ---------------------------------------------------------------------------
592
+ // looksLikeUri — shared write-side predicate that MUST agree with the
593
+ // Rust-side `is_safe_iri_target` / `looks_like_absolute_iri`. See the
594
+ // doc comment on `looksLikeUri` for why drift produces silent no-match
595
+ // reads (PR #874).
596
+ // ---------------------------------------------------------------------------
597
+ describe('looksLikeUri', () => {
598
+ it('accepts well-formed absolute IRIs', () => {
599
+ expect(looksLikeUri('did:key:z6Mk123')).toBe(true);
600
+ expect(looksLikeUri('literal:string:hello')).toBe(true);
601
+ expect(looksLikeUri('http://example.com/foo')).toBe(true);
602
+ });
603
+
604
+ it('rejects scheme-lookalike prose that would fail Rust validate_iri', () => {
605
+ expect(looksLikeUri('Note: buy milk')).toBe(false);
606
+ expect(looksLikeUri('Re: standup')).toBe(false);
607
+ expect(looksLikeUri('TODO: fix this')).toBe(false);
608
+ });
609
+
610
+ it('rejects control chars, whitespace, and SPARQL-breaking chars', () => {
611
+ expect(looksLikeUri('tag:2025:new\nline')).toBe(false);
612
+ expect(looksLikeUri('tag:2025:tab\there')).toBe(false);
613
+ expect(looksLikeUri('http://example.com/foo bar')).toBe(false);
614
+ expect(looksLikeUri('foo:<bar>')).toBe(false);
615
+ expect(looksLikeUri('foo:{bar}')).toBe(false);
616
+ expect(looksLikeUri('foo:"quoted')).toBe(false);
617
+ });
618
+
619
+ it('rejects non-IRI shapes', () => {
620
+ expect(looksLikeUri('just plain text')).toBe(false);
621
+ expect(looksLikeUri('42')).toBe(false);
622
+ expect(looksLikeUri(':no-scheme')).toBe(false);
623
+ expect(looksLikeUri('1abc:foo')).toBe(false);
624
+ });
625
+ });
@@ -81,18 +81,53 @@ export function hasJsOnlyWhereFilters(
81
81
  }
82
82
 
83
83
  /**
84
- * Check if a string value looks like a URI (has a scheme).
84
+ * Check whether a string value is a well-formed absolute IRI that can be
85
+ * stored verbatim as a link target (raw `NamedNode`) instead of being
86
+ * wrapped in a `literal:string:*` URI.
87
+ *
88
+ * This mirrors the Rust `is_safe_iri_target` /
89
+ * `looks_like_absolute_iri` predicate in
90
+ * `rust-executor/src/perspectives/model_query/utils.rs` and is
91
+ * **load-bearing**: a value that returns `true` here MUST also be safely
92
+ * queryable on the Rust side (`validate_iri` gate on the SPARQL
93
+ * `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
94
+ * such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
95
+ * through the write regex, is stored as an invalid `NamedNode`, and
96
+ * becomes a silent no-match on read.
97
+ *
98
+ * Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
99
+ * same rejection set the Rust `validate_iri` applies: any Unicode
100
+ * whitespace, C0/C1 control chars, and the SPARQL-breaking characters
101
+ * `< > { } "`.
85
102
  */
86
- function looksLikeUri(value: string): boolean {
87
- return /^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value);
103
+ export function looksLikeUri(value: string): boolean {
104
+ if (!/^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value)) return false;
105
+ // Reject anything the Rust-side `validate_iri` rejects so the two
106
+ // predicates stay in sync. `\s` covers ASCII whitespace *and*
107
+ // U+00A0/other Unicode whitespace under the default JS regex semantics.
108
+ if (/[\s<>{}"\u0000-\u001F\u007F-\u009F]/.test(value)) return false;
109
+ return true;
88
110
  }
89
111
 
90
112
  /**
91
113
  * Convert a JS value to its literal: IRI form, matching how the Rust executor
92
- * stores property values that don't have a resolveLanguage set.
93
- * Strings that already look like URIs are returned as-is.
114
+ * stores property values in the default deterministic-literal path
115
+ * (`resolveLanguage` unset). Strings that already look like URIs are returned
116
+ * as-is.
117
+ *
118
+ * Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
119
+ * resolve path) can keep their on-disk form aligned with what
120
+ * `queryToSPARQL()` filters against — otherwise the same value can be
121
+ * stored as `<literal:string:https%3A...>` from one path while WHERE
122
+ * builders probe `<https://example.com>` from the other.
123
+ *
124
+ * The object/array arm mirrors Rust's `Literal::from_json` in
125
+ * `perspective_instance.rs::resolve_property_value` (which routes
126
+ * `Value::Object | Value::Array` through JSON encoding). Without it, JS
127
+ * would fall through to `String(value)` and turn `{a: 1}` into
128
+ * `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
94
129
  */
95
- function valueToLiteralIri(value: any): string {
130
+ export function valueToLiteralIri(value: any): string {
96
131
  if (typeof value === 'string') {
97
132
  if (looksLikeUri(value)) return value;
98
133
  return Literal.from(value).toUrl();
@@ -103,21 +138,55 @@ function valueToLiteralIri(value: any): string {
103
138
  if (typeof value === 'boolean') {
104
139
  return Literal.from(value).toUrl();
105
140
  }
141
+ // Objects and arrays: route through Literal.from so we emit
142
+ // `literal:json:*` (mirrors Rust `Literal::from_json`). Without this
143
+ // arm we fall through to `String(value)` which turns objects into
144
+ // `"[object Object]"` and arrays into `"1,2"` — silently storing the
145
+ // wrong shape and breaking equality filters (`findAll({ where:
146
+ // { config: {...} } })` would match against `"[object Object]"`).
147
+ // The `value !== null` guard preserves the historical fallthrough for
148
+ // `null` (→ `literal:string:null`), since `Literal.from(null).toUrl()`
149
+ // throws on the empty-literal check.
150
+ if (value !== null && typeof value === 'object') {
151
+ return Literal.from(value).toUrl();
152
+ }
106
153
  return Literal.from(String(value)).toUrl();
107
154
  }
108
155
 
156
+ /** How a property's value is stored / resolved. */
157
+ export type LiteralStorageMode =
158
+ | { kind: "deterministic" } // deterministic literal: IRI (POS-index friendly, no signature)
159
+ | { kind: "envelope" } // signed expression on the built-in literal language
160
+ | { kind: "custom"; language: string }; // signed expression on a custom language
161
+
162
+ /**
163
+ * Derive the effective storage mode from a property's explicit options.
164
+ * `resolveLanguage` is the sole selector and is NOT defaulted at the
165
+ * decorator level:
166
+ * - unset → deterministic typed literal (the perf default
167
+ * for a plain `@Property()`)
168
+ * - `"literal"` → signed envelope on the built-in literal language
169
+ * (per-value provenance, e.g. Flux message bodies)
170
+ * - `<custom address>` → signed expression on that custom language
171
+ */
172
+ export function effectiveLiteralStorage(meta: {
173
+ resolveLanguage?: string;
174
+ }): LiteralStorageMode {
175
+ const lang = meta.resolveLanguage;
176
+ if (lang === undefined) return { kind: "deterministic" };
177
+ if (lang === "literal") return { kind: "envelope" };
178
+ return { kind: "custom", language: lang };
179
+ }
180
+
109
181
  /**
110
- * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
111
- * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
112
- * both store values as literal: URIs. Only properties with a non-literal resolveLanguage
113
- * (e.g. file storage) or flag properties store raw URIs.
182
+ * Determine if a property stores values as deterministic literal: IRIs (so WHERE
183
+ * filters can match typed literals directly). Envelope / custom-language
184
+ * properties resolve through expressions, and flag properties store raw URIs —
185
+ * none is a deterministic literal.
114
186
  */
115
187
  function isLiteralStoredProperty(propMeta: PropertyMetadata): boolean {
116
188
  if (propMeta.flag) return false;
117
- // If resolveLanguage is set to something other than "literal", it's a language expression URI
118
- if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal") return false;
119
- // Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
120
- return true;
189
+ return effectiveLiteralStorage(propMeta).kind === "deterministic";
121
190
  }
122
191
 
123
192
  /**
@@ -47,20 +47,25 @@ export function formatQueryValue(value: any): string {
47
47
  *
48
48
  * @param predicate - The predicate URI for the property
49
49
  * @param condition - The Where condition value
50
- * @param opts - Optional settings (e.g. `resolveLanguage`)
50
+ * @param opts - Optional settings. `isDeterministicLiteral` (default
51
+ * `true`) selects the direct typed-literal WHERE path.
52
+ * Set to `false` when the property stores a signed
53
+ * envelope (`resolveLanguage: "literal"`) or a
54
+ * custom-language expression — the envelope path unwraps
55
+ * with `parse_literal` before comparing.
51
56
  * @returns A single SPARQL condition string
52
57
  */
53
58
  export function buildWhereCondition(
54
59
  predicate: string,
55
60
  condition: WhereCondition,
56
- opts?: { resolveLanguage?: string; varIndex?: number },
61
+ opts?: { isDeterministicLiteral?: boolean; varIndex?: number },
57
62
  ): string {
58
63
  const escapedPredicate = escapeQueryString(predicate);
59
- // For literal-resolved properties, we match against the raw IRI (which is a literal: URI)
60
- // For language-resolved properties, we match against the plain URI
61
- // For literal-resolved properties, values are stored as IRIs like <literal:string:VALUE>
62
- // For language-resolved properties, values are plain URIs
63
- const isLiteral = !opts?.resolveLanguage || opts.resolveLanguage === 'literal';
64
+ // For deterministic-literal properties, values are stored as typed
65
+ // literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
66
+ // IRI form). For envelope / custom-language properties the target is a
67
+ // signed expression URI; comparisons need to unwrap via `parse_literal`.
68
+ const isLiteral = opts?.isDeterministicLiteral !== false;
64
69
 
65
70
  const varSuffix = opts?.varIndex ?? 0;
66
71
 
@@ -183,23 +188,28 @@ export function compileWhereClause(
183
188
  if (['id', 'author', 'timestamp'].includes(propertyName)) continue;
184
189
 
185
190
  let predicate: string;
186
- let resolveLanguage: string | undefined;
191
+ // Storage mode is derived from `resolveLanguage` alone:
192
+ // - undefined → deterministic typed literal (fast POS-index path)
193
+ // - "literal" → signed envelope on the literal language
194
+ // - custom address → expression on that custom language
195
+ // Envelope and custom-language properties both need the `parse_literal`
196
+ // unwrap path, so we treat any `resolveLanguage`-carrying property as
197
+ // non-deterministic here.
198
+ let isDeterministicLiteral: boolean | undefined;
187
199
 
188
200
  if (metadata) {
189
201
  const propMeta = metadata.properties[propertyName];
190
202
  if (propMeta) {
191
203
  predicate = propMeta.predicate;
192
- resolveLanguage = propMeta.resolveLanguage;
204
+ isDeterministicLiteral = propMeta.resolveLanguage === undefined;
193
205
  } else {
194
- // Property not found in metadata — treat name as raw predicate URI
195
206
  predicate = propertyName;
196
207
  }
197
208
  } else {
198
- // No metadata — treat name as raw predicate URI
199
209
  predicate = propertyName;
200
210
  }
201
211
 
202
- const cond = buildWhereCondition(predicate, condition, { resolveLanguage, varIndex: conditions.length });
212
+ const cond = buildWhereCondition(predicate, condition, { isDeterministicLiteral, varIndex: conditions.length });
203
213
  if (cond) {
204
214
  conditions.push(cond);
205
215
  }
@@ -129,17 +129,36 @@ export function buildSHACL(
129
129
  path: propMeta.through,
130
130
  };
131
131
 
132
- // Determine datatype from initial value or resolveLanguage
133
- if (propMeta.resolveLanguage === "literal") {
134
- propShape.datatype = "xsd://string";
135
- } else if (propMeta.initial) {
136
- const initialType = typeof obj[propName];
137
- if (initialType === "number") {
138
- propShape.datatype = "xsd://integer";
139
- } else if (initialType === "boolean") {
140
- propShape.datatype = "xsd://boolean";
141
- } else if (initialType === "string") {
142
- propShape.datatype = "xsd://string";
132
+ // Determine datatype from JS field value type; the resolve* options
133
+ // control storage mode (deterministic vs envelope), not scalar type.
134
+ // A value stored on the literal language (deterministic or envelope,
135
+ // i.e. resolveLanguage unset or "literal") gets a string datatype when
136
+ // no initial value pins a more specific type. A custom resolveLanguage
137
+ // yields an expression URI, not a literal.
138
+ //
139
+ // Skip auto-datatype for properties with a custom `getter` — those
140
+ // typically return URIs (e.g. `@Optional({ getter: "SELECT ?target ..." })`
141
+ // that hops through a link to another instance's URI). Autosetting
142
+ // `sh:datatype xsd:string` there would trip the hydration decode gate
143
+ // and silently transform `literal:string:<hex>` URIs into their inner
144
+ // plain-string form on read. Users who want a getter to return literal
145
+ // values can opt in explicitly by setting `datatype` on the property
146
+ // options (handled below).
147
+ if (propMeta.datatype) {
148
+ // Explicit opt-in from PropertyOptions always wins over inference.
149
+ propShape.datatype = propMeta.datatype;
150
+ } else {
151
+ const isLiteral =
152
+ propMeta.resolveLanguage === undefined || propMeta.resolveLanguage === "literal";
153
+ if ((propMeta.initial !== undefined || isLiteral) && !propMeta.getter) {
154
+ const initialType = typeof obj[propName];
155
+ if (initialType === "number") {
156
+ propShape.datatype = "xsd://integer";
157
+ } else if (initialType === "boolean") {
158
+ propShape.datatype = "xsd://boolean";
159
+ } else if (initialType === "string" || isLiteral) {
160
+ propShape.datatype = "xsd://string";
161
+ }
143
162
  }
144
163
  }
145
164
 
@@ -261,8 +280,18 @@ export function buildSHACL(
261
280
  path: synthesizedPath,
262
281
  };
263
282
 
264
- // Relations typically contain IRIs
265
- relShape.nodeKind = 'IRI';
283
+ // A relation with a declared `datatype` holds encoded literal
284
+ // values (e.g. `HasMany<string>` with `datatype: "xsd:string"`).
285
+ // Everything else is a URI relation pointing at another
286
+ // instance. The executor uses `sh:datatype` on hydration to
287
+ // decide whether to decode `literal:<type>:<value>` wire form
288
+ // (yes for literals, no for URIs).
289
+ if (relMeta.datatype) {
290
+ relShape.datatype = relMeta.datatype;
291
+ relShape.nodeKind = 'Literal';
292
+ } else {
293
+ relShape.nodeKind = 'IRI';
294
+ }
266
295
 
267
296
  // Encode relation kind so the executor can derive direction and
268
297
  // scalar-vs-collection rendering without consulting the JS class.
@@ -180,7 +180,7 @@ describe("Decorators → SHACL writer round-trip", () => {
180
180
  it("emits scalar property predicates", () => {
181
181
  @Model({ name: "Profile" })
182
182
  class Profile extends Ad4mModel {
183
- @Property({ through: "ns://name", resolveLanguage: "literal" })
183
+ @Property({ through: "ns://name" })
184
184
  name: string = "";
185
185
  }
186
186
 
@@ -190,9 +190,11 @@ describe("Decorators → SHACL writer round-trip", () => {
190
190
  expect(findLinkTarget(links, "ns://Profile.name", "sh://path")).toBe(
191
191
  "ns://name",
192
192
  );
193
+ // A bare @Property is deterministic-literal by default — no
194
+ // resolveLanguage link is emitted.
193
195
  expect(
194
196
  findLinkTarget(links, "ns://Profile.name", "ad4m://resolveLanguage"),
195
- ).toBe("literal:string:literal");
197
+ ).toBeUndefined();
196
198
  });
197
199
 
198
200
  it("emits ad4m://interpretation_hint on the class shape and per property", () => {
@@ -47,15 +47,25 @@ export type Where = {
47
47
  export type Order = { [propertyName: string]: "ASC" | "DESC" };
48
48
 
49
49
  /**
50
- * Discriminated union for parent-scoped queries.
50
+ * A named subgraph scope: a parent node + linking predicate.
51
51
  *
52
- * **Model form** (preferred) — predicate auto-resolved from the parent model's
53
- * relation metadata. Use `field` to disambiguate when the parent has multiple
54
- * relations targeting the same child class.
52
+ * Reusable across contexts that need to identify "the subtree under node X
53
+ * linked via predicate P": query-time filtering as a `parent` filter on a
54
+ * `ModelQuery` (the "all Messages belonging to Channel X" case) AND
55
+ * AutoProcessor's `existingScope` / `mintScope` fields — the former
56
+ * constrains dedup lookups; the latter turns each new mint into a child
57
+ * link under the given node.
58
+ *
59
+ * **Model form** (preferred for parent-filter queries) — predicate
60
+ * auto-resolved from the parent model's relation metadata. Use `field` to
61
+ * disambiguate when the parent has multiple relations targeting the same
62
+ * child class. AutoProcessor `mintScope` requires the **Raw form** because
63
+ * only Raw carries an explicit linking predicate; `Model` scopes have no
64
+ * predicate to write.
55
65
  *
56
66
  * **Raw form** — explicit predicate string, no metadata lookup.
57
67
  */
58
- export type ParentScope =
68
+ export type Scope =
59
69
  | { model: typeof Ad4mModel; id: string; field?: string }
60
70
  | { id: string; predicate: string };
61
71
 
@@ -129,7 +139,7 @@ export function isIncludeProjection(val: unknown): val is IncludeProjection {
129
139
 
130
140
  export type Query = {
131
141
  /** Filter to instances that are the target of a link from a given parent. */
132
- parent?: ParentScope;
142
+ parent?: Scope;
133
143
  properties?: string[];
134
144
  include?: IncludeMap;
135
145
  /**
@@ -345,7 +355,7 @@ export type IncludeExtras<T extends Ad4mModel, I> =
345
355
  // ---- Typed Query -------------------------------------------------------------
346
356
 
347
357
  type StrictTypedQuery<T extends Ad4mModel> = {
348
- parent?: ParentScope;
358
+ parent?: Scope;
349
359
  properties?: PropertyKeysOf<T>[];
350
360
  include?: TypedIncludeMap<T>;
351
361
  includeAll?: boolean;
@@ -402,7 +412,12 @@ export interface PropertyMetadata {
402
412
  readOnly: boolean;
403
413
  /** Initial value if specified */
404
414
  initial?: string;
405
- /** Language for resolution (e.g., "literal") */
415
+ /** Sole selector of storage mode:
416
+ * - unset → deterministic typed literal (fast POS-index
417
+ * path, the default for a plain `@Property()`)
418
+ * - `"literal"` → signed envelope on the built-in literal language
419
+ * - `<custom address>` → expression on that custom language
420
+ */
406
421
  resolveLanguage?: string;
407
422
  /** Custom Prolog getter code */
408
423
  prologGetter?: string;