@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
@@ -0,0 +1,134 @@
1
+ import { Literal } from '../Literal';
2
+ import { parseLit, parseLitNumber, parseLitBoolean, parseSparqlCount } from './SparqlBindings';
3
+
4
+ describe('parseLit', () => {
5
+ it('returns empty string for undefined/null/empty', () => {
6
+ expect(parseLit(undefined)).toBe('');
7
+ expect(parseLit(null)).toBe('');
8
+ expect(parseLit('')).toBe('');
9
+ });
10
+
11
+ it('returns the raw value unchanged when Literal.fromUrl throws (non-literal URI)', () => {
12
+ expect(parseLit('just a string')).toBe('just a string');
13
+ expect(parseLit('http://example.com/resource')).toBe('http://example.com/resource');
14
+ });
15
+
16
+ it('decodes literal:string: primitives', () => {
17
+ expect(parseLit(Literal.from('hello').toUrl())).toBe('hello');
18
+ expect(parseLit(Literal.from('hello world').toUrl())).toBe('hello world');
19
+ });
20
+
21
+ it('decodes literal:number: and literal:boolean: primitives to their string form', () => {
22
+ expect(parseLit(Literal.from(42).toUrl())).toBe('42');
23
+ expect(parseLit(Literal.from(true).toUrl())).toBe('true');
24
+ expect(parseLit(Literal.from(false).toUrl())).toBe('false');
25
+ });
26
+
27
+ // Signed-envelope literals are produced by the `literal` language on write
28
+ // for any property declared with `resolveLanguage: 'literal'` — see
29
+ // rust-executor/src/languages/mod.rs (`expression_create` literal branch,
30
+ // which calls `create_signed_expression` before `literal_encode`).
31
+ // Consumers expect `.data` on read, not the envelope JSON.
32
+ it("extracts `.data` from signed-envelope literals (resolveLanguage: 'literal')", () => {
33
+ const envelope = {
34
+ author: 'did:key:z6MkTest',
35
+ timestamp: '2026-08-19T14:00:00.000Z',
36
+ data: '<p>hello</p>',
37
+ proof: { key: 'did:key:z6MkTest#z6MkTest', signature: 'deadbeef' },
38
+ };
39
+ expect(parseLit(Literal.from(envelope).toUrl())).toBe('<p>hello</p>');
40
+ });
41
+
42
+ it('extracts `.data` when the envelope only carries a `data` field', () => {
43
+ expect(parseLit(Literal.from({ data: 'extracted' }).toUrl())).toBe('extracted');
44
+ });
45
+
46
+ it('falls back to JSON.stringify for objects without a string `.data`', () => {
47
+ expect(parseLit(Literal.from({ foo: 'bar' }).toUrl())).toBe(JSON.stringify({ foo: 'bar' }));
48
+ });
49
+
50
+ it('falls back to JSON.stringify when `.data` is a non-string value', () => {
51
+ const payload = { data: { nested: 'object' } };
52
+ expect(parseLit(Literal.from(payload).toUrl())).toBe(JSON.stringify(payload));
53
+ });
54
+
55
+ // Some storage backends / query paths surface signed envelopes for
56
+ // `resolveLanguage: 'literal'` properties as a bare JSON string rather
57
+ // than a `literal:json:*` URL — the Flux Synergy view hit this when
58
+ // Message.body arrived as `{"author":..,"timestamp":..,"data":"hi","proof":..}`
59
+ // straight out of a SPARQL binding. parseLit must still unwrap `.data`
60
+ // in that shape or the raw envelope leaks into the chat UI.
61
+ it('extracts .data from a plain-JSON signed envelope (no literal: URL wrapper)', () => {
62
+ const envelope = JSON.stringify({
63
+ author: 'did:key:z6MkTest',
64
+ timestamp: '2026-08-19T14:00:00.000Z',
65
+ data: '<p>hello</p>',
66
+ proof: { key: 'did:key:z6MkTest#z6MkTest', signature: 'deadbeef' },
67
+ });
68
+ expect(parseLit(envelope)).toBe('<p>hello</p>');
69
+ });
70
+
71
+ it('leaves plain-JSON objects without a string .data unchanged', () => {
72
+ // Not an envelope — preserve original JSON so downstream code sees
73
+ // exactly what was stored.
74
+ const raw = JSON.stringify({ foo: 'bar' });
75
+ expect(parseLit(raw)).toBe(raw);
76
+ });
77
+
78
+ it('leaves plain text values that happen to start with `{` unchanged', () => {
79
+ expect(parseLit('{ not really json')).toBe('{ not really json');
80
+ });
81
+ });
82
+
83
+ describe('parseLitNumber', () => {
84
+ it('returns 0 for empty input', () => {
85
+ expect(parseLitNumber(undefined)).toBe(0);
86
+ expect(parseLitNumber(null)).toBe(0);
87
+ expect(parseLitNumber('')).toBe(0);
88
+ });
89
+
90
+ it('decodes literal:number: bindings', () => {
91
+ expect(parseLitNumber(Literal.from(42).toUrl())).toBe(42);
92
+ expect(parseLitNumber(Literal.from(3.14).toUrl())).toBe(3.14);
93
+ });
94
+
95
+ it('returns 0 for non-numeric decoded values', () => {
96
+ expect(parseLitNumber(Literal.from('not a number').toUrl())).toBe(0);
97
+ });
98
+ });
99
+
100
+ describe('parseLitBoolean', () => {
101
+ it('returns false for empty input', () => {
102
+ expect(parseLitBoolean(undefined)).toBe(false);
103
+ expect(parseLitBoolean(null)).toBe(false);
104
+ expect(parseLitBoolean('')).toBe(false);
105
+ });
106
+
107
+ it('decodes literal:boolean: bindings', () => {
108
+ expect(parseLitBoolean(Literal.from(true).toUrl())).toBe(true);
109
+ expect(parseLitBoolean(Literal.from(false).toUrl())).toBe(false);
110
+ });
111
+
112
+ it('returns false for any non-"true" decoded value', () => {
113
+ expect(parseLitBoolean(Literal.from('yes').toUrl())).toBe(false);
114
+ expect(parseLitBoolean(Literal.from(1).toUrl())).toBe(false);
115
+ });
116
+ });
117
+
118
+ describe('parseSparqlCount', () => {
119
+ it('returns 0 for undefined/null/empty result arrays', () => {
120
+ expect(parseSparqlCount(undefined)).toBe(0);
121
+ expect(parseSparqlCount(null)).toBe(0);
122
+ expect(parseSparqlCount([])).toBe(0);
123
+ });
124
+
125
+ it('parses the first row `count` value', () => {
126
+ expect(parseSparqlCount([{ count: '5' }])).toBe(5);
127
+ expect(parseSparqlCount([{ count: '0' }])).toBe(0);
128
+ expect(parseSparqlCount([{ count: '123' }, { count: '999' }])).toBe(123);
129
+ });
130
+
131
+ it('returns 0 for non-integer count values', () => {
132
+ expect(parseSparqlCount([{ count: 'not-a-number' }])).toBe(0);
133
+ });
134
+ });
@@ -47,21 +47,72 @@ export function parseSparqlCount(result: CountBinding[] | undefined | null): num
47
47
  /**
48
48
  * Decode a `Literal`-encoded SPARQL binding back to a plain string.
49
49
  *
50
- * Mirrors Flux's local `parseLit` helper. Returns `''` for `undefined`/empty
51
- * input. Falls through to the raw value if decoding fails (defensive — the
52
- * binding may already be a plain string for unwrapped properties).
50
+ * Returns `''` for `undefined`/empty input. Falls through to the raw value
51
+ * if decoding fails — bindings against properties resolved through a custom
52
+ * language are already raw URIs and should pass through unchanged.
53
+ *
54
+ * Signed-envelope literals
55
+ * ------------------------
56
+ * Properties declared with `resolveLanguage: 'literal'` are written through
57
+ * the built-in `literal` language, which wraps the value in a signed
58
+ * expression envelope (`{ author, timestamp, data, proof }`) and encodes
59
+ * the whole envelope as a `literal:json:` URL — see
60
+ * `rust-executor/src/languages/mod.rs::expression_create` (literal branch).
61
+ * On read, `parseLit` unwraps `.data` from that envelope so callers get the
62
+ * original scalar value instead of the envelope JSON.
63
+ *
64
+ * The Channel V refactor moved most scalar properties to deterministic
65
+ * typed XSD literals which no longer round-trip through this envelope — for
66
+ * those properties the SPARQL binding is already the lexical form and this
67
+ * helper decodes to the primitive. Signed-envelope literals still exist
68
+ * for any property that opts back into `resolveLanguage: 'literal'` (e.g.
69
+ * per-message provenance for chat bodies), which is why the `.data` unwrap
70
+ * is preserved here.
71
+ *
72
+ * Non-envelope JSON objects (`literal:json:` payloads that are not signed
73
+ * envelopes) are JSON-stringified for display.
53
74
  */
54
75
  export function parseLit(val: string | undefined | null): string {
55
76
  if (val === undefined || val === null || val === '') return '';
77
+
78
+ // Fast-path 1: `literal:*` URLs from properties written through the built-in
79
+ // `literal` language. On Channel V typed-XSD-literal properties, these
80
+ // decode straight to a primitive; on `resolveLanguage: 'literal'` properties
81
+ // (per-message provenance in chat/synergy) they decode to a signed-envelope
82
+ // object we unwrap via `.data`.
56
83
  try {
57
84
  const result = Literal.fromUrl(val).get();
58
- if (result && typeof result === 'object') {
59
- return (result as { data?: string }).data ?? JSON.stringify(result);
85
+ if (typeof result === 'object' && result !== null) {
86
+ const data = (result as { data?: unknown }).data;
87
+ if (typeof data === 'string') return data;
88
+ return JSON.stringify(result);
60
89
  }
61
90
  return String(result);
62
91
  } catch {
63
- return val;
92
+ // fall through to plain-JSON envelope detection
64
93
  }
94
+
95
+ // Fast-path 2: envelope stored/returned as a bare JSON string rather than a
96
+ // `literal:json:*` URL. Depending on the storage backend and query path,
97
+ // SPARQL bindings for `resolveLanguage: 'literal'` properties can surface
98
+ // the envelope object directly as its JSON serialisation (Oxigraph typed
99
+ // xsd:string of the JSON, or a Channel V pass-through) instead of the URL
100
+ // form. Detect that shape by parsing the string and unwrapping `.data`
101
+ // when it looks like a signed envelope; anything else passes through
102
+ // unchanged so plain text (e.g. "just a string") is not corrupted.
103
+ if (val.length >= 2 && val.charCodeAt(0) === 0x7b /* '{' */) {
104
+ try {
105
+ const parsed = JSON.parse(val);
106
+ if (parsed && typeof parsed === 'object') {
107
+ const data = (parsed as { data?: unknown }).data;
108
+ if (typeof data === 'string') return data;
109
+ }
110
+ } catch {
111
+ // not JSON — fall through and return the raw value
112
+ }
113
+ }
114
+
115
+ return val;
65
116
  }
66
117
 
67
118
  /** Decode a `Literal`-encoded binding to a number. Returns 0 on empty/invalid input. */
@@ -191,7 +191,7 @@ describe('SHACLShape', () => {
191
191
  minInclusive: 10,
192
192
  maxInclusive: 100,
193
193
  hasValue: 'expectedValue',
194
- resolveLanguage: 'test://language',
194
+ resolveLanguage: 'literal',
195
195
  local: true,
196
196
  writable: true,
197
197
  setter: [{ action: 'addLink', source: 'this', predicate: 'test://field', target: 'value' }],
@@ -212,7 +212,7 @@ describe('SHACLShape', () => {
212
212
  expect(prop.minInclusive).toBe(10);
213
213
  expect(prop.maxInclusive).toBe(100);
214
214
  expect(prop.hasValue).toBe('expectedValue');
215
- expect(prop.resolveLanguage).toBe('test://language');
215
+ expect(prop.resolveLanguage).toBe('literal');
216
216
  expect(prop.local).toBe(true);
217
217
  expect(prop.writable).toBe(true);
218
218
  expect(prop.setter).toBeDefined();
@@ -330,15 +330,41 @@ describe('SHACLShape', () => {
330
330
  original.addProperty({
331
331
  name: 'content',
332
332
  path: 'test://content',
333
- resolveLanguage: 'literal',
333
+ resolveLanguage: 'lang://custom',
334
334
  });
335
335
 
336
336
  const json = original.toJSON();
337
337
  const reconstructed = SHACLShape.fromJSON(json);
338
338
 
339
+ expect(reconstructed.properties[0].resolveLanguage).toBe('lang://custom');
340
+ });
341
+
342
+ it('preserves resolveLanguage:"literal" (envelope opt-in)', () => {
343
+ const original = new SHACLShape('test://Model');
344
+ original.addProperty({
345
+ name: 'content',
346
+ path: 'test://content',
347
+ resolveLanguage: 'literal',
348
+ });
349
+
350
+ const reconstructed = SHACLShape.fromJSON(original.toJSON());
339
351
  expect(reconstructed.properties[0].resolveLanguage).toBe('literal');
340
352
  });
341
353
 
354
+ it('round-trips resolveLanguage through toLinks/fromLinks', () => {
355
+ const original = new SHACLShape('test://Model');
356
+ original.addProperty({
357
+ name: 'content',
358
+ path: 'test://content',
359
+ resolveLanguage: 'lang://custom',
360
+ });
361
+
362
+ const links = original.toLinks();
363
+ const reconstructed = SHACLShape.fromLinks(links, 'test://ModelShape');
364
+ const prop = reconstructed.properties.find(p => p.name === 'content');
365
+ expect(prop?.resolveLanguage).toBe('lang://custom');
366
+ });
367
+
342
368
  it('preserves constructor and destructor actions', () => {
343
369
  const original = new SHACLShape('test://Model');
344
370
  original.constructor_actions = [
@@ -636,7 +662,7 @@ describe('SHACLShape', () => {
636
662
  name: 'image',
637
663
  path: 'image://data',
638
664
  datatype: 'xsd://string',
639
- resolveLanguage: '',
665
+ resolveLanguage: 'literal',
640
666
  transform: concat(literal('data:image/png;base64,'), focus()),
641
667
  });
642
668
 
@@ -151,7 +151,13 @@ export interface SHACLPropertyShape {
151
151
  /** AD4M-specific: Writable property */
152
152
  writable?: boolean;
153
153
 
154
- /** AD4M-specific: Language to resolve property values through */
154
+ /** AD4M-specific: sole selector of storage mode:
155
+ * - unset → deterministic typed literal (fast POS-index
156
+ * path, the default for a plain `@Property()`).
157
+ * - `"literal"` → signed envelope on the built-in literal
158
+ * language (per-value provenance, e.g. Flux
159
+ * message bodies).
160
+ * - `<custom address>` → `expression_create` on that custom language. */
155
161
  resolveLanguage?: string;
156
162
 
157
163
  /** AD4M-specific: Setter action for this property */
@@ -206,8 +212,10 @@ export interface SHACLPropertyShape {
206
212
  filter?: boolean;
207
213
 
208
214
  /** AD4M-specific: Transform expression (SHACL-AF Node Expression).
209
- * Applied to resolved property values in the Rust model query engine.
210
- * Only used for properties with resolveLanguage set. */
215
+ * Applied to a property's resolved value in the Rust model query engine —
216
+ * for values resolved through a `resolveLanguage` (`"literal"` for a signed
217
+ * envelope, or a custom language) and for any property that declares a
218
+ * transform. */
211
219
  transform?: NodeExpression;
212
220
 
213
221
  /** AD4M-specific: Natural-language hint that steers the generic LLM
@@ -372,11 +380,19 @@ export class SHACLShape {
372
380
  if (prop.local !== undefined) {
373
381
  turtle += ` ad4m:local ${prop.local} ;\n`;
374
382
  }
375
-
383
+
376
384
  if (prop.writable !== undefined) {
377
385
  turtle += ` ad4m:writable ${prop.writable} ;\n`;
378
386
  }
379
-
387
+
388
+ // Interpreter dedup key: `toLinks()` and `toJSON()` preserve
389
+ // `identity`; a Turtle export must too or the round-trip through
390
+ // Turtle silently drops the interpretation-dedup marker
391
+ // (CodeRabbit #881 review).
392
+ if (prop.identity !== undefined) {
393
+ turtle += ` ad4m:identity ${prop.identity} ;\n`;
394
+ }
395
+
380
396
  // Remove trailing semicolon and close bracket
381
397
  turtle = turtle.slice(0, -2) + '\n';
382
398
  turtle += isLast ? ` ] .\n` : ` ] ;\n`;
@@ -849,6 +865,7 @@ export class SHACLShape {
849
865
  prop.writable = val === 'true';
850
866
  }
851
867
 
868
+ // The general language selector (e.g. "literal" or a custom address).
852
869
  const resolveLangLink = links.find(l =>
853
870
  l.source === propShapeId && l.predicate === "ad4m://resolveLanguage"
854
871
  );
@@ -856,6 +873,11 @@ export class SHACLShape {
856
873
  prop.resolveLanguage = resolveLangLink.target.replace(/^literal:\/\/string:|^literal:string:/, '');
857
874
  }
858
875
 
876
+ // Storage mode is derived from `resolveLanguage` alone:
877
+ // - unset → deterministic typed literal (fast path)
878
+ // - "literal" → signed envelope on the built-in literal language
879
+ // - <address> → expression on that custom language
880
+
859
881
  // Parse action arrays
860
882
  const setterLink = links.find(l =>
861
883
  l.source === propShapeId && l.predicate === "ad4m://setter"
@@ -1105,7 +1127,7 @@ export class SHACLShape {
1105
1127
  hasValue: p.has_value,
1106
1128
  local: p.local,
1107
1129
  writable: p.writable,
1108
- resolveLanguage: p.resolve_language,
1130
+ resolveLanguage: p.resolve_language ?? (p as any).resolveLanguage,
1109
1131
  setter: p.setter,
1110
1132
  adder: p.adder,
1111
1133
  remover: p.remover,
@@ -43,7 +43,7 @@ export {
43
43
  * ```typescript
44
44
  * @Property({
45
45
  * through: 'we://image',
46
- * resolveLanguage: FILE_STORAGE_LANGUAGE,
46
+ * resolveLanguage: 'literal',
47
47
  * transform: fileToDataUri,
48
48
  * })
49
49
  * avatar?: string;