@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
@@ -70,6 +70,14 @@ export class Literal {
70
70
  const numberString = body.substring(7);
71
71
  return parseFloat(numberString);
72
72
  }
73
+ if (body.startsWith("boolean:")) {
74
+ const boolString = decodeURIComponent(body.substring(8));
75
+ if (boolString === "true")
76
+ return true;
77
+ if (boolString === "false")
78
+ return false;
79
+ throw new Error(`Can't parse boolean literal: ${boolString}`);
80
+ }
73
81
  if (body.startsWith("json:")) {
74
82
  const json = body.substring(5);
75
83
  return JSON.parse(decodeURIComponent(json));
@@ -16,4 +16,20 @@ export type RunInterpretationRequest = {
16
16
  * `None`/empty selects all subject classes registered in the perspective.
17
17
  */
18
18
  classes: Array<string> | null;
19
+ /**
20
+ * Optional parent-scope filter for the dedup lookup: when set, only
21
+ * existing instances of the target classes that live under this scope
22
+ * are candidates for upsert. `None` = whole-perspective dedup set (the
23
+ * pre-scope default). Same semantics as `AutoProcessorConfig.existingScope`.
24
+ */
25
+ existingScope?: any;
26
+ /**
27
+ * Optional parent-scope target for newly minted instances: when set,
28
+ * every base URI the pass CREATES is additionally linked as a child of
29
+ * `mintScope.id` via the scope's predicate. Upserts of pre-existing
30
+ * instances are NOT linked (would multi-parent unrelated graph state).
31
+ * Must be the `Raw` variant of `Scope` (id + predicate). Same semantics
32
+ * as `AutoProcessorConfig.mintScope`.
33
+ */
34
+ mintScope?: any;
19
35
  };
@@ -2,7 +2,7 @@ import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
2
2
  import type { SHACLShape } from "../shacl/SHACLShape";
3
3
  import type { JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
4
4
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
5
- import type { ParentScope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata, TypedQuery, IncludeExtras, IncludeOf } from "./types";
5
+ import type { Scope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata, TypedQuery, IncludeExtras, IncludeOf } from "./types";
6
6
  /**
7
7
  * Base class for defining data models in AD4M.
8
8
  *
@@ -24,12 +24,28 @@ import type { ParentScope, IncludeMap, Query, GetOptions, ResultsWithTotalCount,
24
24
  * // Define a recipe model
25
25
  * @Model({ name: "Recipe" })
26
26
  * class Recipe extends Ad4mModel {
27
- * // Required property with literal value
27
+ * // Plain property — no `resolveLanguage` → deterministic typed literal
28
+ * // storage (fast POS-index path). This is the perf default.
29
+ * @Property({ through: "recipe://name" })
30
+ * name: string = "";
31
+ *
32
+ * // Property that needs per-value provenance (e.g. a signed message body):
33
+ * // `resolveLanguage: "literal"` routes values through expression_create on
34
+ * // the built-in literal language, producing a signed envelope URI
35
+ * // (author/timestamp/proof) instead of a bare typed literal.
28
36
  * @Property({
29
- * through: "recipe://name",
37
+ * through: "recipe://signed_note",
30
38
  * resolveLanguage: "literal"
31
39
  * })
32
- * name: string = "";
40
+ * signedNote: string = "";
41
+ *
42
+ * // Property resolved through a custom language: values are routed through
43
+ * // expression_create on that language (signed expression URIs).
44
+ * @Optional({
45
+ * through: "recipe://photo",
46
+ * resolveLanguage: "QmFileStorageLanguageAddress..."
47
+ * })
48
+ * photo: string = "";
33
49
  *
34
50
  * // Optional property with custom initial value
35
51
  * @Optional({
@@ -157,7 +173,7 @@ export declare class Ad4mModel {
157
173
  * ```typescript
158
174
  * @Model({ name: "Recipe" })
159
175
  * class Recipe extends Ad4mModel {
160
- * @Property({ through: "recipe://name", resolveLanguage: "literal" })
176
+ * @Property({ through: "recipe://name" })
161
177
  * name: string = "";
162
178
  *
163
179
  * @HasMany({ through: "recipe://ingredient" })
@@ -176,7 +192,9 @@ export declare class Ad4mModel {
176
192
  *
177
193
  * @param perspective - The perspective where this model will be stored
178
194
  * @param baseExpression - Optional expression URI for this instance.
179
- * If omitted, a random Literal URL is generated.
195
+ * If omitted, a random `ad4m://obj/<id>` IRI is generated,
196
+ * independent of any property content — this is what keeps
197
+ * two instances with identical property values distinct.
180
198
  * @param source - Optional source expression this instance is linked to
181
199
  *
182
200
  * @example
@@ -185,7 +203,7 @@ export declare class Ad4mModel {
185
203
  * const recipe = new Recipe(perspective);
186
204
  *
187
205
  * // Create with specific base expression
188
- * const recipe = new Recipe(perspective, "literal:...");
206
+ * const recipe = new Recipe(perspective, "ad4m://obj/existing-id");
189
207
  * ```
190
208
  */
191
209
  constructor(perspective: PerspectiveProxy, baseExpression?: string);
@@ -537,7 +555,7 @@ export declare class Ad4mModel {
537
555
  * @param perspective - The perspective to create the instance in
538
556
  * @param data - Property values to assign before saving
539
557
  * @param options - Optional settings:
540
- * - `parent` — a `ParentScope` (model form or raw form) whose `id` will
558
+ * - `parent` — a `Scope` (model form or raw form) whose `id` will
541
559
  * be used to create an incoming link from the parent to the new instance.
542
560
  * - `batchId` — an existing batch id; when provided the link write and
543
561
  * `save()` are added to the batch instead of committed immediately.
@@ -563,7 +581,7 @@ export declare class Ad4mModel {
563
581
  * ```
564
582
  */
565
583
  static create<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, data?: Record<string, any>, options?: {
566
- parent?: ParentScope;
584
+ parent?: Scope;
567
585
  batchId?: string;
568
586
  }): Promise<T>;
569
587
  /**
@@ -717,8 +735,7 @@ export declare class Ad4mModel {
717
735
  * // With explicit configuration
718
736
  * const PersonClass = Ad4mModel.fromJSONSchema(schema, {
719
737
  * name: "Person",
720
- * namespace: "person://",
721
- * resolveLanguage: "literal"
738
+ * namespace: "person://"
722
739
  * });
723
740
  *
724
741
  * // With property mapping
@@ -1,11 +1,10 @@
1
- import { Literal } from "../Literal";
2
1
  import { Link } from "../links/Links";
3
2
  import { LinkQuery } from "../perspectives/LinkQuery";
4
3
  import { makeRandomId } from "./util";
5
4
  import { getPropertiesMetadata, getRelationsMetadata, setPropertyRegistryEntry, setRelationRegistryEntry, Model } from "./decorators";
6
5
  import { resolveParentPredicate } from "./query-common";
7
6
  import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
8
- import { buildSPARQLQuery } from "./query-sparql";
7
+ import { buildSPARQLQuery, valueToLiteralIri, effectiveLiteralStorage } from "./query-sparql";
9
8
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
10
9
  import { normalizeValue, } from "./hydration";
11
10
  // ---------------------------------------------------------------------------
@@ -108,12 +107,28 @@ function jsonToModelInstance(ModelClass, perspective, json, include, properties)
108
107
  * // Define a recipe model
109
108
  * @Model({ name: "Recipe" })
110
109
  * class Recipe extends Ad4mModel {
111
- * // Required property with literal value
110
+ * // Plain property — no `resolveLanguage` → deterministic typed literal
111
+ * // storage (fast POS-index path). This is the perf default.
112
+ * @Property({ through: "recipe://name" })
113
+ * name: string = "";
114
+ *
115
+ * // Property that needs per-value provenance (e.g. a signed message body):
116
+ * // `resolveLanguage: "literal"` routes values through expression_create on
117
+ * // the built-in literal language, producing a signed envelope URI
118
+ * // (author/timestamp/proof) instead of a bare typed literal.
112
119
  * @Property({
113
- * through: "recipe://name",
120
+ * through: "recipe://signed_note",
114
121
  * resolveLanguage: "literal"
115
122
  * })
116
- * name: string = "";
123
+ * signedNote: string = "";
124
+ *
125
+ * // Property resolved through a custom language: values are routed through
126
+ * // expression_create on that language (signed expression URIs).
127
+ * @Optional({
128
+ * through: "recipe://photo",
129
+ * resolveLanguage: "QmFileStorageLanguageAddress..."
130
+ * })
131
+ * photo: string = "";
117
132
  *
118
133
  * // Optional property with custom initial value
119
134
  * @Optional({
@@ -253,7 +268,7 @@ export class Ad4mModel {
253
268
  * ```typescript
254
269
  * @Model({ name: "Recipe" })
255
270
  * class Recipe extends Ad4mModel {
256
- * @Property({ through: "recipe://name", resolveLanguage: "literal" })
271
+ * @Property({ through: "recipe://name" })
257
272
  * name: string = "";
258
273
  *
259
274
  * @HasMany({ through: "recipe://ingredient" })
@@ -342,7 +357,7 @@ export class Ad4mModel {
342
357
  predicate: predicate,
343
358
  required: isRequired,
344
359
  readOnly: propertySchema["x-ad4m"]?.writable === false,
345
- ...(propertySchema["x-ad4m"]?.resolveLanguage && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
360
+ ...(propertySchema["x-ad4m"]?.resolveLanguage !== undefined && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
346
361
  ...(propertySchema["x-ad4m"]?.initial && { initial: propertySchema["x-ad4m"].initial }),
347
362
  ...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
348
363
  };
@@ -361,7 +376,9 @@ export class Ad4mModel {
361
376
  *
362
377
  * @param perspective - The perspective where this model will be stored
363
378
  * @param baseExpression - Optional expression URI for this instance.
364
- * If omitted, a random Literal URL is generated.
379
+ * If omitted, a random `ad4m://obj/<id>` IRI is generated,
380
+ * independent of any property content — this is what keeps
381
+ * two instances with identical property values distinct.
365
382
  * @param source - Optional source expression this instance is linked to
366
383
  *
367
384
  * @example
@@ -370,12 +387,21 @@ export class Ad4mModel {
370
387
  * const recipe = new Recipe(perspective);
371
388
  *
372
389
  * // Create with specific base expression
373
- * const recipe = new Recipe(perspective, "literal:...");
390
+ * const recipe = new Recipe(perspective, "ad4m://obj/existing-id");
374
391
  * ```
375
392
  */
376
393
  constructor(perspective, baseExpression) {
377
394
  this._snapshot = null;
378
- this._baseExpression = baseExpression ? baseExpression : Literal.from(makeRandomId(24)).toUrl();
395
+ // Use a dedicated `ad4m://obj/<id>` scheme for auto-generated
396
+ // baseExpressions instead of `Literal.from(...).toUrl()`'s
397
+ // `literal:string:<id>`. After typed-literal storage lands, the storage
398
+ // layer translates any `literal:string:X` target into a typed
399
+ // `"X"^^xsd:string` literal — which is correct for property values but
400
+ // wrong for relation targets (which must remain NamedNode IRIs). Using
401
+ // a distinct scheme keeps auto-generated instance IDs unambiguously
402
+ // IRIs, so relation links like `<post> --has_comment--> <comment-id>`
403
+ // round-trip correctly through the SPARQL store.
404
+ this._baseExpression = baseExpression ? baseExpression : `ad4m://obj/${makeRandomId(24)}`;
379
405
  this._perspective = perspective;
380
406
  }
381
407
  /**
@@ -937,14 +963,22 @@ export class Ad4mModel {
937
963
  }
938
964
  // Generate actions from metadata (replaces Prolog query)
939
965
  const actions = this.generatePropertySetterAction(key, metadata);
940
- // Get resolve language from metadata (replaces Prolog query)
941
- let resolveLanguage = metadata.resolveLanguage;
942
966
  // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
943
967
  if (value === undefined || value === null || value === "") {
944
968
  return;
945
969
  }
946
- if (resolveLanguage) {
947
- value = await this._perspective.createExpression(value, resolveLanguage);
970
+ const mode = effectiveLiteralStorage(metadata);
971
+ if (mode.kind === "custom") {
972
+ // Custom language: route through expression_create on that language.
973
+ value = await this._perspective.createExpression(value, mode.language);
974
+ }
975
+ else if (mode.kind === "envelope") {
976
+ // Built-in literal language: signed-envelope expression (provenance).
977
+ value = await this._perspective.createExpression(value, "literal");
978
+ }
979
+ else {
980
+ // Deterministic literal: IRI (POS-index friendly).
981
+ value = valueToLiteralIri(value);
948
982
  }
949
983
  await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value }], batchId);
950
984
  }
@@ -1063,41 +1097,30 @@ export class Ad4mModel {
1063
1097
  // entirely and let innerUpdate write the links directly.
1064
1098
  const metadata = this.constructor.getModelMetadata();
1065
1099
  const hasConstructor = Object.values(metadata.properties).some((p) => p.required || p.flag || p.initial !== undefined);
1066
- // Track properties that have resolveLanguage (non-literal) so they can be
1067
- // set via setProperty after createSubject (which doesn't resolve languages).
1068
- const deferredResolveLanguageProps = [];
1100
+ // Track properties resolved through expression_create — a signed literal
1101
+ // envelope or a custom (non-"literal") resolveLanguage. These may fail
1102
+ // inside a batch context, so defer them to setProperty after createSubject.
1103
+ const deferredExpressionProps = [];
1069
1104
  if (hasConstructor) {
1070
- // First filter out the properties that are not relations (arrays)
1071
1105
  const initialValues = {};
1072
1106
  for (const [key, value] of Object.entries(this)) {
1073
1107
  if (value !== undefined && value !== null && !(Array.isArray(value) && value.length > 0) && !value?.action) {
1074
- // Check if this property requires language resolution (e.g. file storage).
1075
- // If so, resolve the expression *before* passing to createSubject so
1076
- // the constructor receives a valid URI instead of raw data.
1077
1108
  const propMeta = metadata.properties[key];
1078
- if (propMeta?.resolveLanguage && propMeta.resolveLanguage !== 'literal' && typeof value === 'object') {
1079
- // Defer these properties — they need createExpression which may
1080
- // fail inside a batch context on some languages. We'll set them
1081
- // via setProperty after createSubject.
1082
- deferredResolveLanguageProps.push(key);
1109
+ if (propMeta && effectiveLiteralStorage(propMeta).kind !== "deterministic") {
1110
+ deferredExpressionProps.push(key);
1083
1111
  continue;
1084
1112
  }
1085
1113
  initialValues[key] = value;
1086
1114
  }
1087
1115
  }
1088
- // Get the class name instead of passing the instance to avoid Prolog query generation
1089
1116
  const className = await this.perspective.stringOrTemplateObjectToSubjectClassName(this);
1090
- // Create the subject with the initial values
1091
1117
  await this.perspective.createSubject(className, this._baseExpression, initialValues, batchId);
1092
1118
  }
1093
1119
  // Set properties and relations via innerUpdate.
1094
1120
  // When createSubject was skipped (no constructor actions), we must enable
1095
1121
  // property writing so that scalar values are persisted as links.
1096
1122
  await this.innerUpdate(!hasConstructor, batchId);
1097
- // Now handle any deferred resolveLanguage properties that were excluded
1098
- // from initialValues. setProperty will call createExpression to upload
1099
- // the data to the appropriate language and store the resulting URI.
1100
- for (const key of deferredResolveLanguageProps) {
1123
+ for (const key of deferredExpressionProps) {
1101
1124
  const value = this[key];
1102
1125
  if (value !== undefined && value !== null) {
1103
1126
  await this.setProperty(key, value, batchId);
@@ -1392,7 +1415,7 @@ export class Ad4mModel {
1392
1415
  * @param perspective - The perspective to create the instance in
1393
1416
  * @param data - Property values to assign before saving
1394
1417
  * @param options - Optional settings:
1395
- * - `parent` — a `ParentScope` (model form or raw form) whose `id` will
1418
+ * - `parent` — a `Scope` (model form or raw form) whose `id` will
1396
1419
  * be used to create an incoming link from the parent to the new instance.
1397
1420
  * - `batchId` — an existing batch id; when provided the link write and
1398
1421
  * `save()` are added to the batch instead of committed immediately.
@@ -1624,8 +1647,7 @@ export class Ad4mModel {
1624
1647
  * // With explicit configuration
1625
1648
  * const PersonClass = Ad4mModel.fromJSONSchema(schema, {
1626
1649
  * name: "Person",
1627
- * namespace: "person://",
1628
- * resolveLanguage: "literal"
1650
+ * namespace: "person://"
1629
1651
  * });
1630
1652
  *
1631
1653
  * // With property mapping
@@ -169,11 +169,11 @@ export class ModelQueryBuilder {
169
169
  }
170
170
  const field = options?.field;
171
171
  if (typeof modelOrPredicate === 'string') {
172
- // Raw predicate string → raw form of ParentScope
172
+ // Raw predicate string → raw form of Scope
173
173
  this.queryParams.parent = { id, predicate: modelOrPredicate };
174
174
  }
175
175
  else if (typeof modelOrPredicate === 'function') {
176
- // Model class → model form of ParentScope
176
+ // Model class → model form of Scope
177
177
  this.queryParams.parent = { id, model: modelOrPredicate, ...(field && { field }) };
178
178
  }
179
179
  else if (typeof idOrInstance !== 'string') {
@@ -35,6 +35,15 @@ export interface RelationMetadataEntry {
35
35
  * Overrides auto-derived conformance when set.
36
36
  */
37
37
  where?: Where;
38
+ /**
39
+ * SHACL `sh:datatype` for the relation's target values. Set when the
40
+ * relation holds encoded literal values (e.g. `"xsd:string"` for a
41
+ * `HasMany<string>` that stores plain strings). Emitted into SHACL
42
+ * so the executor knows to decode `literal:<type>:<value>` wire form
43
+ * on hydration. Omit for URI relations that point at other model
44
+ * instances — those pass through byte-for-byte.
45
+ */
46
+ datatype?: string;
38
47
  }
39
48
  /**
40
49
  * Retrieve property metadata for a given class constructor.
@@ -127,7 +136,16 @@ export interface PropertyOptions {
127
136
  */
128
137
  readOnly?: boolean;
129
138
  /**
130
- * The language used to store the property. Can be the default `Literal` Language or a custom language address.
139
+ * The language used to resolve/store the property value — and the sole
140
+ * selector of storage mode. Not defaulted:
141
+ * - unset (the default for a plain `@Property()`) → deterministic
142
+ * typed literal storage (`literal:string:` / `:number:` / `:boolean:` /
143
+ * `:json:` IRIs stored as XSD-typed RDF literals; POS-index friendly).
144
+ * - `"literal"` → the built-in literal language: values go through
145
+ * `expression_create`, producing a signed-envelope URI with
146
+ * author/timestamp/proof (per-value provenance, e.g. Flux message
147
+ * bodies).
148
+ * - a custom language address → `expression_create` on that language.
131
149
  */
132
150
  resolveLanguage?: string;
133
151
  /**
@@ -197,6 +215,16 @@ export interface PropertyOptions {
197
215
  * should set this.
198
216
  */
199
217
  identity?: boolean;
218
+ /**
219
+ * Explicit SHACL `sh:datatype` for the property value. When set, this
220
+ * overrides auto-inference and — importantly — lets custom `getter`
221
+ * properties opt into typed-literal decoding. Auto-inference is disabled
222
+ * for properties with a `getter` (see `shacl-gen.ts`) because such
223
+ * getters typically return URIs; setting `datatype` explicitly declares
224
+ * that this getter returns literal values of the given XSD type
225
+ * (e.g. `"xsd://string"`) and enables the hydration decode gate.
226
+ */
227
+ datatype?: string;
200
228
  }
201
229
  /**
202
230
  * Convenience decorator for defining optional (not required) properties.
@@ -205,7 +233,7 @@ export interface PropertyOptions {
205
233
  *
206
234
  * @description
207
235
  * Equivalent to `@Property` but defaults `required` to `false` and does not
208
- * apply `resolveLanguage` or `initial` defaults. Use this when a property
236
+ * apply any `initial` defaults. Use this when a property
209
237
  * may or may not have a value, and you want full control over its configuration.
210
238
  *
211
239
  * @example
@@ -317,8 +345,7 @@ export interface ModelConfig {
317
345
  * @Model({ name: "Recipe" })
318
346
  * class Recipe extends Ad4mModel {
319
347
  * @Property({
320
- * through: "recipe://name",
321
- * resolveLanguage: "literal"
348
+ * through: "recipe://name"
322
349
  * })
323
350
  * name: string = "";
324
351
  *
@@ -363,7 +390,9 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
363
390
  * Smart defaults (all overridable):
364
391
  * - `required` → `false`
365
392
  * - `readOnly` → `false`
366
- * - `resolveLanguage` → `"literal"`
393
+ * - `resolveLanguage` → unset → deterministic typed literal storage
394
+ * (the perf default). Set `resolveLanguage: "literal"` for a signed-envelope
395
+ * value, or a custom language address to resolve through that language.
367
396
  * - `initial` → `undefined` (no link created until a value is explicitly set)
368
397
  *
369
398
  * Properties are optional by default. When a model instance is created without
@@ -396,7 +425,8 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
396
425
  * })
397
426
  * role: string = "";
398
427
  *
399
- * // Optional property with literal resolution
428
+ * // Optional property with signed-envelope literal storage
429
+ * // (per-value provenance)
400
430
  * @Property({
401
431
  * through: "user://bio",
402
432
  * resolveLanguage: "literal"
@@ -409,7 +439,7 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
409
439
  * @param {string} opts.through - The predicate URI for the property
410
440
  * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
411
441
  * @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
412
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
442
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
413
443
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
414
444
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
415
445
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
@@ -466,7 +496,7 @@ export declare function Property(opts: PropertyOptions): <T>(target: T, key: key
466
496
  * @param {PropertyOptions} opts - Property configuration
467
497
  * @param {string} opts.through - The predicate URI for the property
468
498
  * @param {string} [opts.initial] - Initial value (if property should have one)
469
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
499
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
470
500
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
471
501
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
472
502
  */
@@ -523,6 +553,20 @@ export interface RelationOptions {
523
553
  * ```
524
554
  */
525
555
  where?: Where;
556
+ /**
557
+ * SHACL `sh:datatype` for the relation's target values. Set when the
558
+ * relation holds encoded literal values (e.g. `"xsd:string"` for a
559
+ * `HasMany<string>` that stores plain strings). The executor uses
560
+ * this to decode `literal:<type>:<value>` wire form on hydration.
561
+ * Omit for URI relations that point at other model instances.
562
+ *
563
+ * @example
564
+ * ```typescript
565
+ * @HasMany({ through: "run://source", datatype: "xsd:string" })
566
+ * sources: string[] = [];
567
+ * ```
568
+ */
569
+ datatype?: string;
526
570
  }
527
571
  /**
528
572
  * Utility type that describes the auto-generated helper methods for a HasMany
@@ -206,7 +206,7 @@ function applyPropertyMetadata(opts) {
206
206
  *
207
207
  * @description
208
208
  * Equivalent to `@Property` but defaults `required` to `false` and does not
209
- * apply `resolveLanguage` or `initial` defaults. Use this when a property
209
+ * apply any `initial` defaults. Use this when a property
210
210
  * may or may not have a value, and you want full control over its configuration.
211
211
  *
212
212
  * @example
@@ -329,8 +329,7 @@ export function Flag(opts) {
329
329
  * @Model({ name: "Recipe" })
330
330
  * class Recipe extends Ad4mModel {
331
331
  * @Property({
332
- * through: "recipe://name",
333
- * resolveLanguage: "literal"
332
+ * through: "recipe://name"
334
333
  * })
335
334
  * name: string = "";
336
335
  *
@@ -387,7 +386,9 @@ export function Model(opts) {
387
386
  * Smart defaults (all overridable):
388
387
  * - `required` → `false`
389
388
  * - `readOnly` → `false`
390
- * - `resolveLanguage` → `"literal"`
389
+ * - `resolveLanguage` → unset → deterministic typed literal storage
390
+ * (the perf default). Set `resolveLanguage: "literal"` for a signed-envelope
391
+ * value, or a custom language address to resolve through that language.
391
392
  * - `initial` → `undefined` (no link created until a value is explicitly set)
392
393
  *
393
394
  * Properties are optional by default. When a model instance is created without
@@ -420,7 +421,8 @@ export function Model(opts) {
420
421
  * })
421
422
  * role: string = "";
422
423
  *
423
- * // Optional property with literal resolution
424
+ * // Optional property with signed-envelope literal storage
425
+ * // (per-value provenance)
424
426
  * @Property({
425
427
  * through: "user://bio",
426
428
  * resolveLanguage: "literal"
@@ -433,18 +435,22 @@ export function Model(opts) {
433
435
  * @param {string} opts.through - The predicate URI for the property
434
436
  * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
435
437
  * @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
436
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
438
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
437
439
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
438
440
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
439
441
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
440
442
  */
441
443
  export function Property(opts) {
442
444
  const required = opts.required ?? false;
445
+ // `resolveLanguage` is intentionally NOT defaulted here.
446
+ // The effective storage mode is derived from what the user explicitly set:
447
+ // - unset → deterministic typed literal (the perf default)
448
+ // - "literal" → signed literal envelope (per-value provenance)
449
+ // - <custom address> → expression on that custom language
443
450
  return applyPropertyMetadata({
444
451
  ...opts,
445
452
  required,
446
453
  readOnly: opts.readOnly ?? false,
447
- resolveLanguage: opts.resolveLanguage ?? "literal",
448
454
  initial: opts.initial ?? (required ? "literal:string:uninitialized" : undefined),
449
455
  });
450
456
  }
@@ -499,7 +505,7 @@ export function Property(opts) {
499
505
  * @param {PropertyOptions} opts - Property configuration
500
506
  * @param {string} opts.through - The predicate URI for the property
501
507
  * @param {string} [opts.initial] - Initial value (if property should have one)
502
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
508
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
503
509
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
504
510
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
505
511
  */
@@ -567,6 +573,7 @@ export function HasMany(first, second) {
567
573
  ...(opts.getter && { getter: opts.getter }),
568
574
  ...(opts.filter !== undefined && { filter: opts.filter }),
569
575
  ...(opts.where && { where: opts.where }),
576
+ ...(opts.datatype && { datatype: opts.datatype }),
570
577
  };
571
578
  const relKey = key;
572
579
  // Only add mutation methods when a predicate is available
@@ -600,6 +607,7 @@ export function HasOne(first, second) {
600
607
  local: opts.local,
601
608
  ...(opts.filter !== undefined && { filter: opts.filter }),
602
609
  ...(opts.where && { where: opts.where }),
610
+ ...(opts.datatype && { datatype: opts.datatype }),
603
611
  };
604
612
  const relKey = key;
605
613
  if (opts.through) {
@@ -640,6 +648,7 @@ export function BelongsToOne(first, second) {
640
648
  local: opts.local,
641
649
  ...(opts.filter !== undefined && { filter: opts.filter }),
642
650
  ...(opts.where && { where: opts.where }),
651
+ ...(opts.datatype && { datatype: opts.datatype }),
643
652
  };
644
653
  if (opts.through) {
645
654
  // Read-only property (the owning side manages the link)
@@ -669,6 +678,7 @@ export function BelongsToMany(first, second) {
669
678
  ...(opts.getter && { getter: opts.getter }),
670
679
  ...(opts.filter !== undefined && { filter: opts.filter }),
671
680
  ...(opts.where && { where: opts.where }),
681
+ ...(opts.datatype && { datatype: opts.datatype }),
672
682
  };
673
683
  // @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
674
684
  // prototype methods. Mutation must go through the owning side's @HasMany decorator.
@@ -238,13 +238,7 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
238
238
  }
239
239
  else {
240
240
  // Handle regular properties
241
- let resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
242
- // If no specific resolveLanguage for this property, use the global one
243
- if (!resolveLanguage && options.resolveLanguage) {
244
- resolveLanguage = options.resolveLanguage;
245
- }
246
241
  const local = getPropertyOption(propertyName, propertySchema, options, 'local');
247
- // Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
248
242
  let readOnly = getPropertyOption(propertyName, propertySchema, options, 'readOnly');
249
243
  if (readOnly === undefined) {
250
244
  const xWritable = propertySchema["x-ad4m"]?.writable;
@@ -252,22 +246,14 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
252
246
  }
253
247
  const writable = !readOnly;
254
248
  let initial = getPropertyOption(propertyName, propertySchema, options, 'initial');
255
- // Handle nested objects by serializing to JSON
256
- if (isObjectType(propertySchema) && !resolveLanguage) {
257
- resolveLanguage = 'literal';
249
+ // Not defaulted — absence means "deterministic typed literal" (the
250
+ // perf default); an explicit `resolveLanguage: "literal"` selects the
251
+ // signed-envelope path; any other value selects a custom language.
252
+ // See effectiveLiteralStorage().
253
+ const resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
254
+ if (isObjectType(propertySchema)) {
258
255
  console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
259
256
  }
260
- // Ensure numeric properties use literal language for correct typing
261
- if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
262
- resolveLanguage = 'literal';
263
- }
264
- // Default resolveLanguage to 'literal' for all remaining property types,
265
- // matching the @Property decorator behaviour. Without this, string values
266
- // stored as literal: URLs are returned unparsed.
267
- if (resolveLanguage === undefined || resolveLanguage === null) {
268
- resolveLanguage = 'literal';
269
- }
270
- // If property is required, ensure it has an initial value
271
257
  if (isRequired && !initial) {
272
258
  if (isObjectType(propertySchema)) {
273
259
  initial = 'literal:json:{}';
@@ -280,7 +266,7 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
280
266
  through: predicate,
281
267
  required: isRequired,
282
268
  writable: writable,
283
- ...(resolveLanguage && { resolveLanguage }),
269
+ ...(resolveLanguage !== undefined && { resolveLanguage }),
284
270
  ...(local !== undefined && { local }),
285
271
  ...(initial && { initial })
286
272
  };
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Shared query helpers used by both the Prolog and SPARQL query pipelines.
3
3
  */
4
- import type { ParentScope } from "./types";
4
+ import type { Scope } from "./types";
5
5
  /**
6
6
  * Resolves the predicate for a parent query.
7
7
  *
@@ -11,4 +11,4 @@ import type { ParentScope } from "./types";
11
11
  * - With `field`: direct key lookup
12
12
  * - Without `field`: scan for a relation whose `target()` matches `childCtor`
13
13
  */
14
- export declare function resolveParentPredicate(parent: ParentScope, childCtor: Function): string;
14
+ export declare function resolveParentPredicate(parent: Scope, childCtor: Function): string;