@coasys/ad4m 0.12.0-rc1-dev.1 → 0.12.0-rc1-dev.3

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 (124) hide show
  1. package/jest.config.js +8 -1
  2. package/lib/index.cjs +13793 -12854
  3. package/lib/index.js +13782 -12851
  4. package/lib/src/Ad4mClient.test.d.ts +1 -0
  5. package/lib/src/Ad4mClient.test.js +1204 -0
  6. package/lib/src/Literal.test.d.ts +1 -0
  7. package/lib/src/Literal.test.js +41 -0
  8. package/lib/src/model/Ad4mModel.d.ts +528 -101
  9. package/lib/src/model/Ad4mModel.js +1670 -748
  10. package/lib/src/model/Ad4mModel.test.js +140 -156
  11. package/lib/src/model/Subject.d.ts +3 -3
  12. package/lib/src/model/Subject.js +25 -25
  13. package/lib/src/model/decorators.d.ts +259 -247
  14. package/lib/src/model/decorators.js +379 -422
  15. package/lib/src/model/mutation.d.ts +81 -0
  16. package/lib/src/model/mutation.js +317 -0
  17. package/lib/src/model/parentUtils.d.ts +32 -0
  18. package/lib/src/model/parentUtils.js +64 -0
  19. package/lib/src/model/prolog/generatePrologFacts.d.ts +36 -0
  20. package/lib/src/model/prolog/generatePrologFacts.js +139 -0
  21. package/lib/src/model/prolog/index.d.ts +1 -0
  22. package/lib/src/model/prolog/index.js +1 -0
  23. package/lib/src/model/query/ModelQueryBuilder.d.ts +82 -0
  24. package/lib/src/model/query/ModelQueryBuilder.js +115 -0
  25. package/lib/src/model/query/QueryBuilder.d.ts +101 -0
  26. package/lib/src/model/query/QueryBuilder.js +193 -0
  27. package/lib/src/model/query/SurrealQueryBuilder.d.ts +48 -0
  28. package/lib/src/model/query/SurrealQueryBuilder.js +371 -0
  29. package/lib/src/model/query/fetchInstance.d.ts +24 -0
  30. package/lib/src/model/query/fetchInstance.js +144 -0
  31. package/lib/src/model/query/hydration.d.ts +54 -0
  32. package/lib/src/model/query/hydration.js +214 -0
  33. package/lib/src/model/query/operations.d.ts +59 -0
  34. package/lib/src/model/query/operations.js +384 -0
  35. package/lib/src/model/query/snapshot.d.ts +59 -0
  36. package/lib/src/model/query/snapshot.js +106 -0
  37. package/lib/src/model/query/surrealCompiler.d.ts +42 -0
  38. package/lib/src/model/query/surrealCompiler.js +304 -0
  39. package/lib/src/model/schema/fromJSONSchema.d.ts +67 -0
  40. package/lib/src/model/schema/fromJSONSchema.js +264 -0
  41. package/lib/src/model/schema/metadata.d.ts +15 -0
  42. package/lib/src/model/schema/metadata.js +112 -0
  43. package/lib/src/model/subscription.d.ts +47 -0
  44. package/lib/src/model/subscription.js +231 -0
  45. package/lib/src/model/transaction.d.ts +27 -0
  46. package/lib/src/model/transaction.js +32 -0
  47. package/lib/src/model/types.d.ts +195 -0
  48. package/lib/src/model/types.js +8 -0
  49. package/lib/src/model/util.d.ts +6 -6
  50. package/lib/src/model/util.js +22 -22
  51. package/lib/src/neighbourhood/NeighbourhoodClient.js +31 -12
  52. package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -9
  53. package/lib/src/perspectives/PerspectiveProxy.js +63 -51
  54. package/lib/src/shacl/SHACLShape.d.ts +9 -0
  55. package/lib/src/shacl/SHACLShape.js +28 -4
  56. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  57. package/lib/src/shims/type-graphql.d.ts +32 -0
  58. package/lib/src/src/Ad4mClient.d.ts +28 -0
  59. package/lib/src/src/Address.d.ts +1 -0
  60. package/lib/src/src/DID.d.ts +1 -0
  61. package/lib/src/src/Exception.d.ts +7 -0
  62. package/lib/src/src/Literal.d.ts +7 -0
  63. package/lib/src/src/PubSub.d.ts +17 -0
  64. package/lib/src/src/SmartLiteral.d.ts +12 -0
  65. package/lib/src/src/agent/Agent.d.ts +110 -0
  66. package/lib/src/src/agent/AgentClient.d.ts +62 -0
  67. package/lib/src/src/agent/AgentResolver.d.ts +30 -0
  68. package/lib/src/src/agent/AgentStatus.d.ts +8 -0
  69. package/lib/src/src/ai/AIClient.d.ts +32 -0
  70. package/lib/src/src/ai/AIResolver.d.ts +75 -0
  71. package/lib/src/src/ai/Tasks.d.ts +37 -0
  72. package/lib/src/src/buildSchema.d.ts +1 -0
  73. package/lib/src/src/expression/Expression.d.ts +28 -0
  74. package/lib/src/src/expression/ExpressionClient.d.ts +13 -0
  75. package/lib/src/src/expression/ExpressionRef.d.ts +9 -0
  76. package/lib/src/src/expression/ExpressionResolver.d.ts +10 -0
  77. package/lib/src/src/index.d.ts +35 -0
  78. package/lib/src/src/jestSetup.d.ts +1 -0
  79. package/lib/src/src/language/Icon.d.ts +4 -0
  80. package/lib/src/src/language/Language.d.ts +206 -0
  81. package/lib/src/src/language/LanguageClient.d.ts +17 -0
  82. package/lib/src/src/language/LanguageContext.d.ts +37 -0
  83. package/lib/src/src/language/LanguageHandle.d.ts +9 -0
  84. package/lib/src/src/language/LanguageMeta.d.ts +35 -0
  85. package/lib/src/src/language/LanguageRef.d.ts +6 -0
  86. package/lib/src/src/language/LanguageResolver.d.ts +19 -0
  87. package/lib/src/src/links/Links.d.ts +39 -0
  88. package/lib/src/src/links/Links.test.d.ts +1 -0
  89. package/lib/src/src/model/Ad4mModel.d.ts +1438 -0
  90. package/lib/src/src/model/Ad4mModel.test.d.ts +1 -0
  91. package/lib/src/src/model/Subject.d.ts +25 -0
  92. package/lib/src/src/model/decorators.d.ts +545 -0
  93. package/lib/src/src/model/util.d.ts +12 -0
  94. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +10 -0
  95. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +25 -0
  96. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +19 -0
  97. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
  98. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +24 -0
  99. package/lib/src/src/perspectives/LinkQuery.d.ts +11 -0
  100. package/lib/src/src/perspectives/Perspective.d.ts +38 -0
  101. package/lib/src/src/perspectives/Perspective.test.d.ts +1 -0
  102. package/lib/src/src/perspectives/PerspectiveClient.d.ts +97 -0
  103. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +9 -0
  104. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +18 -0
  105. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +865 -0
  106. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +57 -0
  107. package/lib/src/src/runtime/RuntimeClient.d.ts +56 -0
  108. package/lib/src/src/runtime/RuntimeResolver.d.ts +132 -0
  109. package/lib/src/src/shacl/SHACLFlow.d.ts +171 -0
  110. package/lib/src/src/shacl/SHACLFlow.test.d.ts +1 -0
  111. package/lib/src/src/shacl/SHACLShape.d.ts +117 -0
  112. package/lib/src/src/shacl/SHACLShape.test.d.ts +1 -0
  113. package/lib/src/src/typeDefs.d.ts +1 -0
  114. package/lib/src/src/unwrapApolloResult.d.ts +2 -0
  115. package/lib/src/src/utils.d.ts +25 -0
  116. package/package.json +20 -24
  117. package/src/model/Ad4mModel.test.ts +132 -149
  118. package/src/model/Ad4mModel.ts +1930 -784
  119. package/src/model/Subject.ts +24 -24
  120. package/src/model/decorators.ts +626 -482
  121. package/src/model/util.ts +22 -22
  122. package/src/neighbourhood/NeighbourhoodClient.ts +32 -16
  123. package/src/perspectives/PerspectiveProxy.ts +69 -55
  124. package/src/shacl/SHACLShape.ts +33 -4
@@ -1,8 +1,9 @@
1
1
  import { Literal } from "../Literal";
2
2
  import { Link } from "../links/Links";
3
+ import { LinkQuery } from "../perspectives/LinkQuery";
3
4
  import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
4
- import { makeRandomPrologAtom, PropertyOptions, CollectionOptions, ModelOptions } from "./decorators";
5
- import { singularToPlural, pluralToSingular, propertyNameToSetterName, collectionToAdderName, collectionToRemoverName, collectionToSetterName } from "./util";
5
+ import { makeRandomId, PropertyOptions, Model, getPropertiesMetadata, getRelationsMetadata, setPropertyRegistryEntry, setRelationRegistryEntry, PropertyMetadataEntry, RelationMetadataEntry } from "./decorators";
6
+ import { singularToPlural, pluralToSingular, propertyNameToSetterName, relationToAdderName, relationToRemoverName, relationToSetterName } from "./util";
6
7
  import { escapeSurrealString } from "../utils";
7
8
 
8
9
  // JSON Schema type definitions
@@ -58,10 +59,47 @@ type WhereCondition = string | number | boolean | string[] | number[] | { [K in
58
59
  type Where = { [propertyName: string]: WhereCondition };
59
60
  type Order = { [propertyName: string]: "ASC" | "DESC" };
60
61
 
62
+ /**
63
+ * Discriminated union for parent-scoped queries.
64
+ *
65
+ * **Model form** (preferred) — predicate auto-resolved from the parent model's
66
+ * relation metadata. Use `field` to disambiguate when the parent has multiple
67
+ * relations targeting the same child class.
68
+ *
69
+ * **Raw form** — explicit predicate string, no metadata lookup.
70
+ */
71
+ export type ParentScope =
72
+ | { model: typeof Ad4mModel; id: string; field?: string }
73
+ | { id: string; predicate: string };
74
+
75
+ /**
76
+ * Describes which relations to eager-load when querying.
77
+ *
78
+ * Each value is either:
79
+ * - `true` — hydrate the relation one level deep
80
+ * - A `RelationSubQuery` — scoped sub-query (filter / sort / paginate / nested include)
81
+ *
82
+ * @example
83
+ * ```typescript
84
+ * // One level deep
85
+ * { comments: true }
86
+ *
87
+ * // Sub-query: only the 5 most-recent comments
88
+ * { comments: { order: { createdAt: 'DESC' }, limit: 5 } }
89
+ *
90
+ * // Nested eager-load
91
+ * { comments: { include: { author: true } } }
92
+ * ```
93
+ */
94
+ export interface IncludeMap {
95
+ [relation: string]: boolean | RelationSubQuery;
96
+ }
97
+
61
98
  export type Query = {
62
- source?: string;
99
+ /** Filter to instances that are the target of a link from a given parent. */
100
+ parent?: ParentScope;
63
101
  properties?: string[];
64
- collections?: string[]; // replace with include: Query[]
102
+ include?: IncludeMap;
65
103
  where?: Where;
66
104
  order?: Order;
67
105
  offset?: number;
@@ -69,6 +107,26 @@ export type Query = {
69
107
  count?: boolean;
70
108
  };
71
109
 
110
+ /**
111
+ * Sub-query options for a specific relation inside an `IncludeMap`.
112
+ *
113
+ * Equivalent to `Query` without top-level scoping (`parent`) or `count`,
114
+ * since the result set is already constrained to the linked relation.
115
+ *
116
+ * @example
117
+ * ```typescript
118
+ * await post.get({ include: { comments: { order: { createdAt: 'DESC' }, limit: 5 } } });
119
+ * ```
120
+ */
121
+ export type RelationSubQuery = Omit<Query, 'parent' | 'count'>;
122
+
123
+ /**
124
+ * Options accepted by the instance `get()` method.
125
+ *
126
+ * A subset of `Query` — only hydration controls apply to a single known instance.
127
+ */
128
+ export type GetOptions = Pick<Query, 'include' | 'properties'>;
129
+
72
130
  export type AllInstancesResult = { AllInstances: Ad4mModel[]; TotalCount?: number; isInit?: boolean };
73
131
  export type ResultsWithTotalCount<T> = { results: T[]; totalCount?: number };
74
132
  export type PaginationResult<T> = { results: T[]; totalCount?: number; pageSize: number; pageNumber: number };
@@ -83,8 +141,8 @@ export interface PropertyMetadata {
83
141
  predicate: string;
84
142
  /** Whether the property is required */
85
143
  required: boolean;
86
- /** Whether the property is writable */
87
- writable: boolean;
144
+ /** Whether the property is read-only */
145
+ readOnly: boolean;
88
146
  /** Initial value if specified */
89
147
  initial?: string;
90
148
  /** Language for resolution (e.g., "literal") */
@@ -104,41 +162,87 @@ export interface PropertyMetadata {
104
162
  }
105
163
 
106
164
  /**
107
- * Metadata for a single collection extracted from decorators.
165
+ * Metadata for a single relation extracted from decorators.
108
166
  */
109
- export interface CollectionMetadata {
110
- /** The collection name */
167
+ export interface RelationMetadata {
168
+ /** The relation name */
111
169
  name: string;
112
170
  /** The predicate URI (through value) */
113
171
  predicate: string;
114
- /** Filter conditions */
115
- where?: { isInstance?: any; prologCondition?: string; condition?: string };
116
172
  /** Custom SurrealQL getter code */
117
173
  getter?: string;
118
174
  /** Whether stored locally only */
119
175
  local?: boolean;
176
+ /** Link direction: 'forward' for HasMany/HasOne, 'reverse' for BelongsToMany/BelongsToOne */
177
+ direction?: 'forward' | 'reverse';
120
178
  }
121
179
 
180
+
181
+
122
182
  /**
123
183
  * Complete model metadata extracted from decorators.
124
184
  */
125
185
  export interface ModelMetadata {
126
- /** The model class name from @ModelOptions */
186
+ /** The model class name from @Model */
127
187
  className: string;
128
188
  /** Map of property name to metadata */
129
189
  properties: Record<string, PropertyMetadata>;
130
- /** Map of collection name to metadata */
131
- collections: Record<string, CollectionMetadata>;
190
+ /** Map of relation name to metadata */
191
+ relations: Record<string, RelationMetadata>;
132
192
  }
133
193
 
134
194
  function capitalize(word: string): string {
135
195
  return word.charAt(0).toUpperCase() + word.slice(1);
136
196
  }
137
197
 
138
- function buildSourceQuery(source?: string): string {
139
- // Constrains the query to instances that have the provided source
140
- if (!source) return "";
141
- return `triple("${source}", "ad4m://has_child", Base)`;
198
+ /**
199
+ * Resolves the predicate for a parent query.
200
+ *
201
+ * Uses TS discriminated union narrowing:
202
+ * - Raw form (`{ id, predicate }`) → predicate used as-is
203
+ * - Model form (`{ model, id, field? }`) → lookup from relation metadata
204
+ * - With `field`: direct key lookup
205
+ * - Without `field`: scan for a relation whose `target()` matches `childCtor`
206
+ */
207
+ function resolveParentPredicate(
208
+ parent: ParentScope,
209
+ childCtor: Function,
210
+ ): string {
211
+ // Raw form — explicit predicate
212
+ if ('predicate' in parent) return parent.predicate;
213
+
214
+ // Model form — resolve from relation metadata
215
+ const { model } = parent;
216
+ const relMeta = getRelationsMetadata(model);
217
+
218
+ // Direct lookup by field name when provided
219
+ if (parent.field) {
220
+ const entry = relMeta[parent.field];
221
+ if (!entry) {
222
+ throw new Error(
223
+ `parent(): field "${parent.field}" is not a registered relation on ${model.name}`,
224
+ );
225
+ }
226
+ return entry.predicate;
227
+ }
228
+
229
+ // Fallback: scan for a relation whose target matches the child class
230
+ for (const [, entry] of Object.entries(relMeta)) {
231
+ if (entry.target && entry.target() === childCtor) {
232
+ return entry.predicate;
233
+ }
234
+ }
235
+ throw new Error(
236
+ `parent(): could not resolve predicate — no relation on ${model.name} targets ${(childCtor as any).name || 'the queried class'}`,
237
+ );
238
+ }
239
+
240
+ function buildParentQuery(
241
+ parent: ParentScope | undefined,
242
+ resolvedPredicate?: string,
243
+ ): string {
244
+ if (!parent || !resolvedPredicate) return '';
245
+ return `triple("${parent.id}", "${resolvedPredicate}", Base)`;
142
246
  }
143
247
 
144
248
  // todo: only return Timestamp & Author from query (Base, AllLinks, and SortLinks not required)
@@ -169,22 +273,9 @@ function buildPropertiesQuery(properties?: string[]): string {
169
273
  `;
170
274
  }
171
275
 
172
- function buildCollectionsQuery(collections?: string[]): string {
173
- // Gets the name and array of values for all (or some) collections on a Ad4mModel instance
174
- // If no collections are provided, all are included
175
- return `
176
- findall([CollectionName, CollectionValues], (
177
- % Constrain to specified collections if provided
178
- ${collections ? `member(CollectionName, [${collections.map((name) => `"${name}"`).join(", ")}]),` : ""}
179
-
180
- collection(SubjectClass, CollectionName),
181
- collection_getter(SubjectClass, Base, CollectionName, CollectionValues)
182
- ), Collections)
183
- `;
184
- }
185
-
186
276
  function buildWhereQuery(where: Where = {}): string {
187
277
  // Constrains the query to instances that match the provided where conditions
278
+ // 'id' maps to the Prolog 'Base' variable (the base expression of the instance).
188
279
 
189
280
  function formatValue(value) {
190
281
  // Wrap strings in quotes
@@ -193,10 +284,10 @@ function buildWhereQuery(where: Where = {}): string {
193
284
 
194
285
  return (Object.entries(where) as [string, WhereCondition][])
195
286
  .map(([key, value]) => {
196
- const isSpecial = ["base", "author", "timestamp"].includes(key);
287
+ const isSpecial = ["id", "author", "timestamp"].includes(key);
197
288
  const getter = `resolve_property(SubjectClass, Base, "${key}", Value${key}, _)`;
198
- // const getter = `property_getter(SubjectClass, Base, "${key}", URI), literal_from_url(URI, V, _)`;
199
- const field = capitalize(key);
289
+ // For 'id' the Prolog variable is always 'Base'
290
+ const field = key === "id" ? "Base" : capitalize(key);
200
291
 
201
292
  // Handle direct array values (for IN conditions)
202
293
  if (Array.isArray(value)) {
@@ -256,8 +347,22 @@ function buildCountQuery(count?: boolean): string {
256
347
 
257
348
  function buildOrderQuery(order?: Order): string {
258
349
  if (!order) return "SortedInstances = UnsortedInstances";
259
- const [propertyName, direction] = Object.entries(order)[0];
260
- return `sort_instances(UnsortedInstances, "${propertyName}", "${direction}", SortedInstances)`;
350
+ const entries = Object.entries(order);
351
+ if (entries.length === 1) {
352
+ const [propertyName, direction] = entries[0];
353
+ return `sort_instances(UnsortedInstances, "${propertyName}", "${direction}", SortedInstances)`;
354
+ }
355
+ // Multi-field sort: sort from least-significant to most-significant key
356
+ // so that the final (primary) sort preserves secondary-key ordering for equal values.
357
+ // The merge_sort implementation is stable (equal elements keep original order).
358
+ const clauses: string[] = [];
359
+ for (let i = entries.length - 1; i >= 0; i--) {
360
+ const [propertyName, direction] = entries[i];
361
+ const inputVar = i === entries.length - 1 ? "UnsortedInstances" : `MultiSortIntermediate${i + 1}`;
362
+ const outputVar = i === 0 ? "SortedInstances" : `MultiSortIntermediate${i}`;
363
+ clauses.push(`sort_instances(${inputVar}, "${propertyName}", "${direction}", ${outputVar})`);
364
+ }
365
+ return clauses.join(",\n ");
261
366
  }
262
367
 
263
368
  function buildOffsetQuery(offset?: number): string {
@@ -313,21 +418,21 @@ function isNumericType(schema: JSONSchemaProperty): boolean {
313
418
  *
314
419
  * @description
315
420
  * Ad4mModel provides the foundation for creating data models that are stored in AD4M perspectives.
316
- * Each model instance is represented as a subgraph in the perspective, with properties and collections
421
+ * Each model instance is represented as a subgraph in the perspective, with properties and relations
317
422
  * mapped to links in that graph. The class uses Prolog-based queries to efficiently search and filter
318
423
  * instances based on their properties and relationships.
319
424
  *
320
425
  * Key concepts:
321
426
  * - Each model instance has a unique base expression that serves as its identifier
322
427
  * - Properties are stored as links with predicates defined by the `through` option
323
- * - Collections represent one-to-many relationships as sets of links
428
+ * - Relations represent one-to-many relationships as sets of links
324
429
  * - Queries are translated to Prolog for efficient graph pattern matching
325
430
  * - Changes are tracked through the perspective's subscription system
326
431
  *
327
432
  * @example
328
433
  * ```typescript
329
434
  * // Define a recipe model
330
- * @ModelOptions({ name: "Recipe" })
435
+ * @Model({ name: "Recipe" })
331
436
  * class Recipe extends Ad4mModel {
332
437
  * // Required property with literal value
333
438
  * @Property({
@@ -355,15 +460,12 @@ function isNumericType(schema: JSONSchemaProperty): boolean {
355
460
  * })
356
461
  * averageRating: number = 0;
357
462
  *
358
- * // Collection of ingredients
359
- * @Collection({ through: "recipe://ingredient" })
360
- * ingredients: string[] = [];
463
+ * // Relation of ingredients
464
+ * @HasMany({ through: "recipe://ingredient" })
465
+ * ingredients: string[] = [];
361
466
  *
362
- * // Collection of comments that are instances of another model
363
- * @Collection({
364
- * through: "recipe://comment",
365
- * where: { isInstance: Comment }
366
- * })
467
+ * // Relation of comments linked to another model
468
+ * @HasMany(() => Comment, { through: "recipe://comment" })
367
469
  * comments: Comment[] = [];
368
470
  * }
369
471
  *
@@ -408,16 +510,35 @@ function isNumericType(schema: JSONSchemaProperty): boolean {
408
510
  * ```
409
511
  */
410
512
  export class Ad4mModel {
411
- #baseExpression: string;
412
- #subjectClassName: string;
413
- #source: string;
414
- #perspective: PerspectiveProxy;
513
+ private _baseExpression: string;
514
+ private _subjectClassName: string;
515
+ private _perspective: PerspectiveProxy;
516
+ private _snapshot: Record<string, any> | null = null;
415
517
  author: string;
416
518
  createdAt: any;
417
519
  updatedAt: any;
418
520
 
419
521
  private static classNamesByClass = new WeakMap<typeof Ad4mModel, { [perspectiveId: string]: string }>();
420
522
 
523
+ /**
524
+ * Generates the SDNA (Subject DNA) Prolog rules for this model class.
525
+ * Injected at class-definition time by the `@Model` decorator.
526
+ * Returns a default value on un-decorated base classes.
527
+ */
528
+ static generateSDNA(): { sdna: string; name: string } {
529
+ return { sdna: '', name: '' };
530
+ }
531
+
532
+ /**
533
+ * Generates the SHACL shape graph for this model class.
534
+ * Injected at class-definition time by the `@Model` decorator.
535
+ * Returns `{ shape: null, name: '' }` on un-decorated base classes —
536
+ * the decorator's `parentSHACL?.shape?.nodeShapeUri` check handles this.
537
+ */
538
+ static generateSHACL(): { shape: any; name: string } {
539
+ return { shape: null, name: '' };
540
+ }
541
+
421
542
  static async getClassName(perspective: PerspectiveProxy) {
422
543
  // Check if this is the Ad4mModel class itself or a subclass
423
544
  const isBaseClass = this === Ad4mModel;
@@ -455,64 +576,64 @@ export class Ad4mModel {
455
576
  * Extracts metadata from decorators for query building.
456
577
  *
457
578
  * @description
458
- * This method reads the metadata stored by decorators (@Property, @Collection, etc.)
579
+ * This method reads the metadata stored by decorators (@Property, @HasMany, etc.)
459
580
  * and returns it in a structured format that's easier to work with for query builders
460
581
  * and other systems that need to introspect model structure.
461
582
  *
462
583
  * The metadata includes:
463
- * - Class name from @ModelOptions
584
+ * - Class name from @Model
464
585
  * - Property metadata (predicates, types, constraints, etc.)
465
- * - Collection metadata (predicates, filters, etc.)
586
+ * - Relation metadata (predicates, filters, etc.)
466
587
  *
467
588
  * For models created via `fromJSONSchema()`, this method will derive metadata from
468
- * the stored `__properties` and `__collections` structures that were populated during
469
- * the dynamic class creation. If these structures are empty but a JSON schema was
470
- * attached to the class, it can fall back to deriving metadata from that schema.
589
+ * the WeakMap registries that were populated during the dynamic class creation.
590
+ * If these structures are empty but a JSON schema was attached to the class,
591
+ * it can fall back to deriving metadata from that schema.
471
592
  *
472
- * @returns Structured metadata object containing className, properties, and collections
473
- * @throws Error if the class doesn't have @ModelOptions decorator
593
+ * @returns Structured metadata object containing className, properties, and relations
594
+ * @throws Error if the class doesn't have @Model decorator
474
595
  *
475
596
  * @example
476
597
  * ```typescript
477
- * @ModelOptions({ name: "Recipe" })
598
+ * @Model({ name: "Recipe" })
478
599
  * class Recipe extends Ad4mModel {
479
600
  * @Property({ through: "recipe://name", resolveLanguage: "literal" })
480
601
  * name: string = "";
481
602
  *
482
- * @Collection({ through: "recipe://ingredient" })
603
+ * @HasMany({ through: "recipe://ingredient" })
483
604
  * ingredients: string[] = [];
484
605
  * }
485
606
  *
486
607
  * const metadata = Recipe.getModelMetadata();
487
608
  * console.log(metadata.className); // "Recipe"
488
609
  * console.log(metadata.properties.name.predicate); // "recipe://name"
489
- * console.log(metadata.collections.ingredients.predicate); // "recipe://ingredient"
610
+ * console.log(metadata.relations.ingredients.predicate); // "recipe://ingredient"
490
611
  * ```
491
612
  */
492
613
  public static getModelMetadata(): ModelMetadata {
493
614
  // Access the prototype with any type to access decorator-added properties
494
615
  const prototype = this.prototype as any;
495
616
 
496
- // Validate that the class has @ModelOptions decorator
617
+ // Validate that the class has @Model decorator
497
618
  // The decorator sets prototype.className, so we check for its existence
498
619
  if (!prototype.className || prototype.className === 'Ad4mModel') {
499
- throw new Error("Model class must be decorated with @ModelOptions");
620
+ throw new Error("Model class must be decorated with @Model");
500
621
  }
501
622
 
502
623
  // Extract className
503
624
  const className = prototype.className;
504
625
 
505
- // Extract properties from prototype.__properties
626
+ // Extract properties from WeakMap registry
506
627
  const propertiesMetadata: Record<string, PropertyMetadata> = {};
507
- const prototypeProperties = prototype.__properties || {};
628
+ const prototypeProperties = getPropertiesMetadata(this);
508
629
 
509
630
  for (const [propertyName, opts] of Object.entries(prototypeProperties)) {
510
- const options = opts as PropertyOptions & { required?: boolean; flag?: boolean };
631
+ const options = opts as PropertyOptions & { required?: boolean; flag?: boolean; writable?: boolean };
511
632
  propertiesMetadata[propertyName] = {
512
633
  name: propertyName,
513
634
  predicate: options.through || "",
514
635
  required: options.required || false,
515
- writable: options.writable || false,
636
+ readOnly: !(options.writable ?? false),
516
637
  ...(options.initial !== undefined && { initial: options.initial }),
517
638
  ...(options.resolveLanguage !== undefined && { resolveLanguage: options.resolveLanguage }),
518
639
  ...(options.prologGetter !== undefined && { prologGetter: options.prologGetter }),
@@ -524,26 +645,29 @@ export class Ad4mModel {
524
645
  };
525
646
  }
526
647
 
527
- // Extract collections from prototype.__collections
528
- const collectionsMetadata: Record<string, CollectionMetadata> = {};
529
- const prototypeCollections = prototype.__collections || {};
648
+ // Extract relations (relations) from WeakMap registry
649
+ const relationsMetadata: Record<string, RelationMetadata> = {};
650
+ const allRelationsMeta = getRelationsMetadata(this as any);
651
+ const prototypeRelations = Object.fromEntries(
652
+ Object.entries(allRelationsMeta).filter(([, r]) => r.kind === 'hasMany' || r.kind === 'belongsToMany')
653
+ );
530
654
 
531
- for (const [collectionName, opts] of Object.entries(prototypeCollections)) {
532
- const options = opts as CollectionOptions;
533
- collectionsMetadata[collectionName] = {
534
- name: collectionName,
535
- predicate: options.through || "",
536
- ...(options.where !== undefined && { where: options.where }),
655
+ for (const [relationName, opts] of Object.entries(prototypeRelations)) {
656
+ const options = opts as RelationMetadataEntry;
657
+ relationsMetadata[relationName] = {
658
+ name: relationName,
659
+ predicate: options.predicate || "",
537
660
  ...(options.local !== undefined && { local: options.local }),
538
- ...(options.getter !== undefined && { getter: options.getter })
661
+ ...(options.getter !== undefined && { getter: options.getter }),
662
+ direction: (options.kind === 'belongsToMany' || options.kind === 'belongsToOne') ? 'reverse' : 'forward',
539
663
  };
540
664
  }
541
665
 
542
666
  // Fallback: If both structures are empty but a JSON schema is attached, derive from it
543
667
  // This handles edge cases where fromJSONSchema() was called but metadata wasn't properly populated
544
668
  const hasProperties = Object.keys(propertiesMetadata).length > 0;
545
- const hasCollections = Object.keys(collectionsMetadata).length > 0;
546
- const hasMetadata = hasProperties || hasCollections;
669
+ const hasRelations = Object.keys(relationsMetadata).length > 0;
670
+ const hasMetadata = hasProperties || hasRelations;
547
671
 
548
672
  if (!hasMetadata && prototype.__jsonSchema) {
549
673
  // Derive metadata from the attached JSON schema
@@ -562,7 +686,7 @@ export class Ad4mModel {
562
686
  );
563
687
 
564
688
  if (isArray) {
565
- collectionsMetadata[propertyName] = {
689
+ relationsMetadata[propertyName] = {
566
690
  name: propertyName,
567
691
  predicate: predicate,
568
692
  ...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
@@ -573,7 +697,7 @@ export class Ad4mModel {
573
697
  name: propertyName,
574
698
  predicate: predicate,
575
699
  required: isRequired,
576
- writable: propertySchema["x-ad4m"]?.writable !== false,
700
+ readOnly: propertySchema["x-ad4m"]?.writable === false,
577
701
  ...(propertySchema["x-ad4m"]?.resolveLanguage && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
578
702
  ...(propertySchema["x-ad4m"]?.initial && { initial: propertySchema["x-ad4m"].initial }),
579
703
  ...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
@@ -586,7 +710,7 @@ export class Ad4mModel {
586
710
  return {
587
711
  className,
588
712
  properties: propertiesMetadata,
589
- collections: collectionsMetadata
713
+ relations: relationsMetadata,
590
714
  };
591
715
  }
592
716
 
@@ -594,7 +718,8 @@ export class Ad4mModel {
594
718
  * Constructs a new model instance.
595
719
  *
596
720
  * @param perspective - The perspective where this model will be stored
597
- * @param baseExpression - Optional unique identifier for this instance
721
+ * @param baseExpression - Optional expression URI for this instance.
722
+ * If omitted, a random Literal URL is generated.
598
723
  * @param source - Optional source expression this instance is linked to
599
724
  *
600
725
  * @example
@@ -603,23 +728,26 @@ export class Ad4mModel {
603
728
  * const recipe = new Recipe(perspective);
604
729
  *
605
730
  * // Create with specific base expression
606
- * const recipe = new Recipe(perspective, "recipe://chocolate-cake");
607
- *
608
- * // Create with source link
609
- * const recipe = new Recipe(perspective, undefined, "cookbook://desserts");
731
+ * const recipe = new Recipe(perspective, "literal://...");
610
732
  * ```
611
733
  */
612
- constructor(perspective: PerspectiveProxy, baseExpression?: string, source?: string) {
613
- this.#baseExpression = baseExpression ? baseExpression : Literal.from(makeRandomPrologAtom(24)).toUrl();
614
- this.#perspective = perspective;
615
- this.#source = source || "ad4m://self";
734
+ constructor(perspective: PerspectiveProxy, baseExpression?: string) {
735
+ this._baseExpression = baseExpression ? baseExpression : Literal.from(makeRandomId(24)).toUrl();
736
+ this._perspective = perspective;
737
+ }
738
+
739
+ /**
740
+ * The unique identifier (expression URI) of this model instance.
741
+ */
742
+ get id(): string {
743
+ return this._baseExpression;
616
744
  }
617
745
 
618
746
  /**
619
- * Gets the base expression of the subject.
747
+ * @deprecated Use `.id` instead. Will be removed in a future version.
620
748
  */
621
- get baseExpression() {
622
- return this.#baseExpression;
749
+ get baseExpression(): string {
750
+ return this._baseExpression;
623
751
  }
624
752
 
625
753
  /**
@@ -627,25 +755,27 @@ export class Ad4mModel {
627
755
  * Allows subclasses to access the perspective while keeping it private from external code.
628
756
  */
629
757
  protected get perspective(): PerspectiveProxy {
630
- return this.#perspective;
758
+ return this._perspective;
631
759
  }
632
760
 
633
761
  /**
634
762
  * Get property metadata from decorator (Phase 1: Prolog-free refactor)
635
763
  * @private
636
764
  */
637
- private getPropertyMetadata(key: string): PropertyOptions | undefined {
638
- const proto = Object.getPrototypeOf(this);
639
- return proto.__properties?.[key];
765
+ private getPropertyMetadata(key: string): PropertyMetadataEntry | undefined {
766
+ const ctor = this.constructor;
767
+ const props = getPropertiesMetadata(ctor);
768
+ return props[key];
640
769
  }
641
770
 
642
771
  /**
643
- * Get collection metadata from decorator (Phase 1: Prolog-free refactor)
772
+ * Get relation options from decorator
644
773
  * @private
645
774
  */
646
- private getCollectionMetadata(key: string): CollectionOptions | undefined {
647
- const proto = Object.getPrototypeOf(this);
648
- return proto.__collections?.[key];
775
+ private getRelationOptions(key: string): RelationMetadataEntry | undefined {
776
+ const ctor = this.constructor;
777
+ const rels = getRelationsMetadata(ctor);
778
+ return rels[key];
649
779
  }
650
780
 
651
781
  /**
@@ -653,9 +783,17 @@ export class Ad4mModel {
653
783
  * Replaces Prolog query: property_setter(C, key, Setter)
654
784
  * @private
655
785
  */
656
- private generatePropertySetterAction(key: string, metadata: PropertyOptions): any[] {
786
+ private generatePropertySetterAction(key: string, metadata: PropertyMetadataEntry): any[] {
787
+ // Flags are always immutable — throw a clear error
788
+ if (metadata.flag) {
789
+ throw new Error(
790
+ `Property "${key}" is a @Flag and cannot be written. ` +
791
+ `Flags are immutable type markers set at creation time.`
792
+ );
793
+ }
794
+
657
795
  // Check if property is read-only
658
- if (metadata.writable === false) {
796
+ if (metadata.readOnly) {
659
797
  throw new Error(`Property "${key}" is read-only and cannot be written`);
660
798
  }
661
799
 
@@ -681,18 +819,18 @@ export class Ad4mModel {
681
819
  }
682
820
 
683
821
  /**
684
- * Generate collection action from metadata (Phase 1: Prolog-free refactor)
822
+ * Generate relation action from metadata (Phase 1: Prolog-free refactor)
685
823
  * Replaces Prolog queries: collection_adder, collection_remover, collection_setter
686
824
  * @private
687
825
  */
688
- private generateCollectionAction(key: string, actionType: 'adder' | 'remover' | 'setter'): any[] {
689
- const metadata = this.getCollectionMetadata(key);
826
+ private generateRelationAction(key: string, actionType: 'adder' | 'remover' | 'setter'): any[] {
827
+ const metadata = this.getRelationOptions(key);
690
828
  if (!metadata) {
691
- throw new Error(`Collection "${key}" has no metadata defined`);
829
+ throw new Error(`Relation "${key}" has no metadata defined`);
692
830
  }
693
831
 
694
- if (!metadata.through) {
695
- throw new Error(`Collection "${key}" has no 'through' predicate defined`);
832
+ if (!metadata.predicate) {
833
+ throw new Error(`Relation "${key}" has no predicate defined`);
696
834
  }
697
835
 
698
836
  const actionMap = {
@@ -704,12 +842,229 @@ export class Ad4mModel {
704
842
  return [{
705
843
  action: actionMap[actionType],
706
844
  source: "this",
707
- predicate: metadata.through,
845
+ predicate: metadata.predicate,
708
846
  target: "value",
709
847
  ...(metadata.local && { local: true })
710
848
  }];
711
849
  }
712
850
 
851
+ // ──────────────────────────────────────────────────────────
852
+ // Unified hydration helpers
853
+ // ──────────────────────────────────────────────────────────
854
+
855
+ /**
856
+ * Resolves a raw link target value into a hydrated property value.
857
+ *
858
+ * Handles, in order:
859
+ * 1. Non-literal expression resolution (`perspective.getExpression`)
860
+ * 2. Literal URI parsing (`Literal.fromUrl(…).get()`)
861
+ * 3. Primitive type coercion (string → number / boolean)
862
+ * 4. Transform function application
863
+ *
864
+ * @param target - The raw target string from the link
865
+ * @param propMeta - Property metadata from the decorator registry
866
+ * @param perspective - The perspective for expression resolution
867
+ * @param expectedType - Optional JS typeof hint for coercion (e.g. 'number')
868
+ * @returns The resolved value
869
+ * @private
870
+ */
871
+ private static async hydratePropertyValue(
872
+ target: string,
873
+ propMeta: PropertyMetadata,
874
+ perspective: PerspectiveProxy,
875
+ expectedType?: string,
876
+ ): Promise<any> {
877
+ let value: any = target;
878
+
879
+ if (target !== undefined && target !== null && target !== '') {
880
+ // Non-literal expression resolution
881
+ if (
882
+ propMeta.resolveLanguage != null &&
883
+ propMeta.resolveLanguage !== 'literal' &&
884
+ typeof target === 'string' &&
885
+ !target.startsWith('literal://')
886
+ ) {
887
+ try {
888
+ const expression = await perspective.getExpression(target);
889
+ if (expression) {
890
+ try { value = JSON.parse(expression.data); } catch { value = expression.data; }
891
+ }
892
+ } catch (e) {
893
+ console.warn(`hydratePropertyValue: failed to resolve expression for "${propMeta.name}":`, e);
894
+ }
895
+ }
896
+ // Literal URI parsing
897
+ else if (
898
+ propMeta.resolveLanguage === 'literal' &&
899
+ typeof target === 'string' &&
900
+ target.startsWith('literal://')
901
+ ) {
902
+ try {
903
+ const parsed = Literal.fromUrl(target).get();
904
+ value = parsed.data !== undefined ? parsed.data : parsed;
905
+ } catch {
906
+ // Keep raw value
907
+ }
908
+ }
909
+ // Primitive type coercion
910
+ else if (typeof target === 'string' && expectedType) {
911
+ if (expectedType === 'number') value = Number(target);
912
+ else if (expectedType === 'boolean') value = target === 'true' || target === '1';
913
+ }
914
+ }
915
+
916
+ // Transform function
917
+ if (propMeta.transform && typeof propMeta.transform === 'function') {
918
+ value = propMeta.transform(value);
919
+ }
920
+
921
+ return value;
922
+ }
923
+
924
+ /**
925
+ * Link shape accepted by `hydrateFromLinks`.
926
+ * Both `getData()` and `instancesFromSurrealResult()` produce this shape.
927
+ */
928
+ private static readonly _linkShape: undefined; // type-only marker
929
+
930
+ /**
931
+ * Hydrates an instance from an array of raw links.
932
+ *
933
+ * Processes properties (latest-wins semantics), relations
934
+ * (chronological accumulation), and timestamps/author in a single
935
+ * pass over the links array.
936
+ *
937
+ * @param instance - The blank model instance to populate
938
+ * @param links - Array of link objects (predicate, target, author?, timestamp?)
939
+ * @param metadata - Model metadata from `getModelMetadata()`
940
+ * @param perspective - The perspective for expression resolution
941
+ * @param requestedProperties - Optional sparse fieldset; when provided, only these
942
+ * property names are hydrated (relations are unaffected).
943
+ * Omit or pass `undefined` to hydrate all properties.
944
+ * @private
945
+ */
946
+ private static async hydrateFromLinks(
947
+ instance: any,
948
+ links: Array<{ predicate: string; target: string; author?: string; timestamp?: string | number }>,
949
+ metadata: ModelMetadata,
950
+ perspective: PerspectiveProxy,
951
+ requestedProperties?: string[],
952
+ ): Promise<void> {
953
+ if (!links || links.length === 0) return;
954
+
955
+ let minTimestamp: string | number | null = null;
956
+ let maxTimestamp: string | number | null = null;
957
+ let originalAuthor: string | null = null;
958
+ let latestAuthor: string | null = null;
959
+
960
+ // Build predicate→propName and predicate→relName lookup maps for O(1) matching
961
+ // When requestedProperties is provided, only include those properties in the map
962
+ const propFilter = requestedProperties && requestedProperties.length > 0
963
+ ? new Set(requestedProperties)
964
+ : null;
965
+
966
+ const predToProperty = new Map<string, [string, PropertyMetadata]>();
967
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
968
+ if (propMeta.getter) continue; // Handled via custom getter evaluation
969
+ if (propFilter && !propFilter.has(propName)) continue; // Skip unrequested properties
970
+ predToProperty.set(propMeta.predicate, [propName, propMeta]);
971
+ }
972
+
973
+ const predToRelation = new Map<string, [string, RelationMetadata]>();
974
+ for (const [relName, relMeta] of Object.entries(metadata.relations)) {
975
+ if (relMeta.getter) continue;
976
+ predToRelation.set(relMeta.predicate, [relName, relMeta]);
977
+ }
978
+
979
+ // Per-property accumulator: track all matching targets so we can pick the last (latest-wins)
980
+ const propertyLatest = new Map<string, { target: string; timestamp?: string | number }>();
981
+
982
+ // Per-relation accumulator: ordered targets with metadata for sorting
983
+ const relationAccum = new Map<string, Array<{ target: string; timestamp: string | number; index: number }>>();
984
+
985
+ // Single pass over all links
986
+ for (let i = 0; i < links.length; i++) {
987
+ const link = links[i];
988
+ const { predicate, target, author, timestamp } = link;
989
+ if (target === 'None' || target === undefined || target === null) continue;
990
+
991
+ // Track timestamps/authors
992
+ if (timestamp != null) {
993
+ if (minTimestamp == null || timestamp < minTimestamp) {
994
+ minTimestamp = timestamp;
995
+ originalAuthor = author ?? null;
996
+ }
997
+ if (maxTimestamp == null || timestamp > maxTimestamp) {
998
+ maxTimestamp = timestamp;
999
+ latestAuthor = author ?? null;
1000
+ }
1001
+ }
1002
+
1003
+ // Property match — accumulate for latest-wins
1004
+ const propEntry = predToProperty.get(predicate);
1005
+ if (propEntry) {
1006
+ const existing = propertyLatest.get(propEntry[0]);
1007
+ // Latest-wins: always overwrite (links are ordered ASC so last = latest)
1008
+ propertyLatest.set(propEntry[0], { target, timestamp });
1009
+ continue;
1010
+ }
1011
+
1012
+ // Relation match — accumulate all
1013
+ const relEntry = predToRelation.get(predicate);
1014
+ if (relEntry) {
1015
+ const [relName] = relEntry;
1016
+ let arr = relationAccum.get(relName);
1017
+ if (!arr) {
1018
+ arr = [];
1019
+ relationAccum.set(relName, arr);
1020
+ }
1021
+ arr.push({ target, timestamp: timestamp ?? '', index: i });
1022
+ }
1023
+ }
1024
+
1025
+ // Resolve properties
1026
+ for (const [propName, { target }] of propertyLatest) {
1027
+ const [, propMeta] = predToProperty.get(
1028
+ metadata.properties[propName].predicate
1029
+ )!;
1030
+ const expectedType = typeof instance[propName];
1031
+ instance[propName] = await this.hydratePropertyValue(
1032
+ target,
1033
+ propMeta,
1034
+ perspective,
1035
+ expectedType !== 'undefined' ? expectedType : undefined,
1036
+ );
1037
+ }
1038
+
1039
+ // Resolve relations: sort by timestamp (stable via index tiebreaker), filter empties
1040
+ for (const [relName, items] of relationAccum) {
1041
+ items.sort((a, b) => {
1042
+ const cmp = String(a.timestamp).localeCompare(String(b.timestamp));
1043
+ return cmp !== 0 ? cmp : a.index - b.index;
1044
+ });
1045
+ instance[relName] = items
1046
+ .map(i => i.target)
1047
+ .filter((v: any) => v !== undefined && v !== null && v !== '' && v !== 'None');
1048
+ }
1049
+
1050
+ // Assign author / timestamps
1051
+ if (originalAuthor) instance.author = originalAuthor;
1052
+ if (minTimestamp != null) {
1053
+ instance.createdAt = typeof minTimestamp === 'string' && minTimestamp.includes('T')
1054
+ ? new Date(minTimestamp).getTime()
1055
+ : typeof minTimestamp === 'string'
1056
+ ? (isNaN(parseInt(minTimestamp, 10)) ? minTimestamp : parseInt(minTimestamp, 10))
1057
+ : minTimestamp;
1058
+ }
1059
+ if (maxTimestamp != null) {
1060
+ instance.updatedAt = typeof maxTimestamp === 'string' && maxTimestamp.includes('T')
1061
+ ? new Date(maxTimestamp).getTime()
1062
+ : typeof maxTimestamp === 'string'
1063
+ ? (isNaN(parseInt(maxTimestamp, 10)) ? maxTimestamp : parseInt(maxTimestamp, 10))
1064
+ : maxTimestamp;
1065
+ }
1066
+ }
1067
+
713
1068
  public static async assignValuesToInstance(perspective: PerspectiveProxy, instance: Ad4mModel, values: ValueTuple[]) {
714
1069
  // Map properties to object
715
1070
  const propsObject = Object.fromEntries(
@@ -750,7 +1105,8 @@ export class Ad4mModel {
750
1105
  }
751
1106
  }
752
1107
  // Apply transform function if it exists
753
- const transform = instance["__properties"]?.[name]?.transform;
1108
+ const propsMeta = getPropertiesMetadata(instance.constructor);
1109
+ const transform = propsMeta[name]?.transform;
754
1110
  if (transform && typeof transform === "function") {
755
1111
  finalValue = transform(finalValue);
756
1112
  }
@@ -781,203 +1137,230 @@ export class Ad4mModel {
781
1137
  Object.assign(instance, writableProps);
782
1138
  }
783
1139
 
784
- private async getData() {
785
- // Builds an object with the author, timestamp, all properties, & all collections on the Ad4mModel and saves it to the instance
1140
+ // ──────────────────────────────────────────────────────────
1141
+ // Snapshot / dirty tracking
1142
+ // ──────────────────────────────────────────────────────────
1143
+
1144
+ /**
1145
+ * Captures a shallow snapshot of the instance's current property and
1146
+ * relation values. Called automatically after hydration (`get()`,
1147
+ * query results). The snapshot is used by `isDirty()`,
1148
+ * `changedFields()`, and by `update()` to skip unchanged fields.
1149
+ * @private
1150
+ */
1151
+ /**
1152
+ * Normalize a value for snapshot storage.
1153
+ * Arrays of model instances are reduced to their `.id` strings so that
1154
+ * dirty-tracking compares stable identifiers instead of object references.
1155
+ */
1156
+ private static normalizeValue(value: any): any {
1157
+ if (Array.isArray(value)) {
1158
+ return value.map((v: any) =>
1159
+ v && typeof v === 'object' && typeof v.id === 'string' ? v.id : v,
1160
+ );
1161
+ }
1162
+ return value;
1163
+ }
1164
+
1165
+ /**
1166
+ * @param includedRelations Controls which relation fields are recorded
1167
+ * in the snapshot for dirty-tracking:
1168
+ * • `undefined` (default) — snapshot ALL relations (used by `.get()`,
1169
+ * `.create()`, `.save()` etc. where full hydration has occurred).
1170
+ * • `IncludeMap` object (e.g. `{ views: true }`) — only snapshot the
1171
+ * relations named in the map. Fields not listed are omitted from
1172
+ * the snapshot so that `changedFields()` ignores them.
1173
+ * • `null` / empty object — skip ALL relations (used by bare
1174
+ * subscriptions that don't eagerly load relations).
1175
+ */
1176
+ private takeSnapshot(includedRelations?: Record<string, any> | null): void {
1177
+ const ctor = this.constructor as typeof Ad4mModel;
1178
+ const metadata = ctor.getModelMetadata();
1179
+ const snap: Record<string, any> = {};
1180
+
1181
+ // Always snapshot properties
1182
+ for (const propName of Object.keys(metadata.properties)) {
1183
+ const val = (this as any)[propName];
1184
+ snap[propName] = Ad4mModel.normalizeValue(
1185
+ Array.isArray(val) ? [...val] : val,
1186
+ );
1187
+ }
1188
+
1189
+ // Snapshot relations only when appropriate:
1190
+ // undefined → all relations (backward compat)
1191
+ // IncludeMap → only the keys present in the map
1192
+ // null / {} → none
1193
+ if (includedRelations === undefined) {
1194
+ // Full snapshot — e.g. after getData() / create()
1195
+ for (const relName of Object.keys(metadata.relations)) {
1196
+ const val = (this as any)[relName];
1197
+ snap[relName] = Ad4mModel.normalizeValue(
1198
+ Array.isArray(val) ? [...val] : val,
1199
+ );
1200
+ }
1201
+ } else if (includedRelations && Object.keys(includedRelations).length > 0) {
1202
+ // Partial snapshot — only the explicitly included relations
1203
+ for (const relName of Object.keys(includedRelations)) {
1204
+ if (relName in metadata.relations) {
1205
+ const val = (this as any)[relName];
1206
+ snap[relName] = Ad4mModel.normalizeValue(
1207
+ Array.isArray(val) ? [...val] : val,
1208
+ );
1209
+ }
1210
+ }
1211
+ }
1212
+ // else: null or empty object → skip all relations
1213
+
1214
+ this._snapshot = snap;
1215
+ }
1216
+
1217
+ /**
1218
+ * Returns `true` if any tracked property or relation has changed
1219
+ * since the last hydration (or since `takeSnapshot()` was last called).
1220
+ *
1221
+ * Always returns `true` if no snapshot exists (e.g. a freshly
1222
+ * constructed instance that hasn't been fetched yet).
1223
+ *
1224
+ * @example
1225
+ * ```typescript
1226
+ * const recipe = await Recipe.create(perspective, { name: "Pasta" });
1227
+ * recipe.isDirty(); // false — just hydrated
1228
+ * recipe.name = "Risotto";
1229
+ * recipe.isDirty(); // true
1230
+ * ```
1231
+ */
1232
+ isDirty(): boolean {
1233
+ if (!this._snapshot) return true;
1234
+ return this.changedFields().length > 0;
1235
+ }
1236
+
1237
+ /**
1238
+ * Returns the names of properties/relations that differ from the
1239
+ * snapshot taken at the last hydration.
1240
+ *
1241
+ * Returns **all** field names if no snapshot exists.
1242
+ *
1243
+ * @example
1244
+ * ```typescript
1245
+ * recipe.name = "New Name";
1246
+ * recipe.changedFields(); // ["name"]
1247
+ * ```
1248
+ */
1249
+ changedFields(): string[] {
1250
+ const ctor = this.constructor as typeof Ad4mModel;
1251
+ const metadata = ctor.getModelMetadata();
1252
+
1253
+ if (!this._snapshot) {
1254
+ return [
1255
+ ...Object.keys(metadata.properties),
1256
+ ...Object.keys(metadata.relations),
1257
+ ];
1258
+ }
1259
+
1260
+ const changed: string[] = [];
1261
+ const allFields = [
1262
+ ...Object.keys(metadata.properties),
1263
+ ...Object.keys(metadata.relations),
1264
+ ];
1265
+
1266
+ for (const field of allFields) {
1267
+ // Skip fields that were not recorded in the snapshot (e.g. relation
1268
+ // fields omitted because the originating query had no `include`).
1269
+ // Without this guard, a relation populated by hydrateFromLinks with
1270
+ // raw string IDs would appear "dirty" against a missing snapshot
1271
+ // entry and trigger an unnecessary (and potentially destructive)
1272
+ // setRelationValues call during innerUpdate.
1273
+ if (!(field in this._snapshot)) continue;
1274
+
1275
+ const current = Ad4mModel.normalizeValue((this as any)[field]);
1276
+ const original = this._snapshot[field];
1277
+
1278
+ if (Array.isArray(current) || Array.isArray(original)) {
1279
+ // Order-insensitive comparison (sorted) so reordering alone
1280
+ // doesn't mark a relation as dirty.
1281
+ const a = Array.isArray(current) ? [...current].sort() : [];
1282
+ const b = Array.isArray(original) ? [...original].sort() : [];
1283
+ if (a.length !== b.length || a.some((v: any, i: number) => v !== b[i])) {
1284
+ changed.push(field);
1285
+ }
1286
+ } else if (current !== original) {
1287
+ changed.push(field);
1288
+ }
1289
+ }
1290
+ return changed;
1291
+ }
1292
+
1293
+ private async getData(opts?: GetOptions) {
1294
+ // Builds an object with the author, timestamp, all properties, & all relations on the Ad4mModel and saves it to the instance
786
1295
  // Use SurrealDB for data queries
787
1296
  try {
788
1297
  const ctor = this.constructor as typeof Ad4mModel;
789
1298
  const metadata = ctor.getModelMetadata();
790
1299
 
791
1300
  // Query for all links from this specific node (base expression)
792
- // Using formatSurrealValue to prevent SQL injection by properly escaping the value
793
- const safeBaseExpression = ctor.formatSurrealValue(this.#baseExpression);
794
- // Note: We use ORDER BY timestamp ASC because:
795
- // - For collections: we want chronological order (oldest to newest)
796
- // - For properties: we select the LAST element to get "latest wins" semantics
1301
+ const safeBaseExpression = ctor.formatSurrealValue(this._baseExpression);
797
1302
  const linksQuery = `
798
1303
  SELECT id, predicate, out.uri AS target, author, timestamp
799
1304
  FROM link
800
1305
  WHERE in.uri = ${safeBaseExpression}
801
1306
  ORDER BY timestamp ASC
802
1307
  `;
803
- const links = await this.#perspective.querySurrealDB(linksQuery);
1308
+ const links = await this._perspective.querySurrealDB(linksQuery);
804
1309
 
805
1310
  if (links && links.length > 0) {
806
- let minTimestamp = null;
807
- let maxTimestamp = null;
808
- let latestAuthor = null;
809
- let originalAuthor = null;
810
-
811
- // Process properties (skip those with custom getter)
812
- for (const [propName, propMeta] of Object.entries(metadata.properties)) {
813
- if (propMeta.getter) continue; // Handle via custom getter evaluation
814
- const matching = links.filter((l: any) => l.predicate === propMeta.predicate);
815
- if (matching.length > 0) {
816
- // "Latest wins" semantics: select the last element since links are ordered ASC.
817
- // The last element has the most recent timestamp and represents the current property value.
818
- const link = matching[matching.length - 1];
819
- let value = link.target;
820
-
821
- // Track timestamps/authors for createdAt and updatedAt
822
- if (link.timestamp) {
823
- if (!minTimestamp || link.timestamp < minTimestamp) {
824
- minTimestamp = link.timestamp;
825
- originalAuthor = link.author;
826
- }
827
- if (!maxTimestamp || link.timestamp > maxTimestamp) {
828
- maxTimestamp = link.timestamp;
829
- latestAuthor = link.author;
830
- }
831
- }
832
-
833
- // Handle resolveLanguage
834
- if (propMeta.resolveLanguage && propMeta.resolveLanguage !== 'literal') {
835
- try {
836
- const expression = await this.#perspective.getExpression(value);
837
- if (expression) {
838
- try {
839
- value = JSON.parse(expression.data);
840
- } catch {
841
- value = expression.data;
842
- }
843
- }
844
- } catch (e) {
845
- console.warn(`Failed to resolve expression for ${propName}:`, e);
846
- }
847
- } else if (propMeta.resolveLanguage === 'literal' && typeof value === 'string' && value.startsWith('literal://')) {
848
- // Only parse literal URIs when resolveLanguage is explicitly 'literal'.
849
- // Without this guard, properties pointing to baseExpressions of other models
850
- // (which may be literal:// strings) would get unwrapped, breaking link URI validation.
851
- try {
852
- const parsed = Literal.fromUrl(value).get();
853
- value = parsed.data !== undefined ? parsed.data : parsed;
854
- } catch (e) {
855
- // Keep original value
856
- }
857
- }
858
-
859
- // Apply transform if exists
860
- if (propMeta.transform && typeof propMeta.transform === 'function') {
861
- value = propMeta.transform(value);
862
- }
863
-
864
- (this as any)[propName] = value;
865
- }
866
- }
867
-
868
- // Process collections (skip those with custom getter)
869
- for (const [collName, collMeta] of Object.entries(metadata.collections)) {
870
- if (collMeta.getter) continue; // Handle via custom getter evaluation
871
- const matching = links.filter((l: any) => l.predicate === collMeta.predicate);
872
- // Collections preserve chronological order: links are sorted ASC by timestamp,
873
- // so the collection reflects the order in which items were added (oldest to newest).
874
- let values = matching.map((l: any) => l.target);
875
-
876
- // Apply where.condition filtering if present
877
- if (collMeta.where?.condition && values.length > 0) {
878
- try {
879
- // Filter values by evaluating condition for each value
880
- const filteredValues: string[] = [];
881
-
882
- for (const value of values) {
883
- let condition = collMeta.where.condition
884
- .replace(/\$perspective/g, `'${this.#perspective.uuid}'`)
885
- .replace(/\$base/g, `'${this.#baseExpression}'`)
886
- .replace(/Target/g, `'${value.replace(/'/g, "\\'")}'`);
887
-
888
- // If condition starts with WHERE, wrap it in array length check pattern
889
- // Using array::len() to properly count matching links
890
- if (condition.trim().startsWith('WHERE')) {
891
- condition = `array::len(SELECT * FROM link ${condition}) > 0`;
892
- }
893
-
894
- const filterQuery = `RETURN ${condition}`;
895
- const result = await this.#perspective.querySurrealDB(filterQuery);
896
-
897
- // RETURN can return the value directly or in an array
898
- const isTrue = result === true || (Array.isArray(result) && result.length > 0 && result[0] === true);
899
- if (isTrue) {
900
- filteredValues.push(value);
901
- }
902
- }
903
-
904
- values = filteredValues;
905
- } catch (error) {
906
- console.warn(`Failed to apply condition filter for ${collName}:`, error);
907
- // Keep unfiltered values on error
908
- }
909
- }
910
-
911
- // Apply where.isInstance filtering if present
912
- if (collMeta.where?.isInstance && values.length > 0) {
913
- try {
914
- const className = typeof collMeta.where.isInstance === 'string'
915
- ? collMeta.where.isInstance
916
- : collMeta.where.isInstance.name;
917
-
918
- const filterMetadata = await this.#perspective.getSubjectClassMetadataFromSDNA(className);
919
- if (filterMetadata) {
920
- values = await this.#perspective.batchCheckSubjectInstances(values, filterMetadata);
921
- }
922
- } catch (error) {
923
- // Keep unfiltered values on error
924
- }
925
- }
926
-
927
- (this as any)[collName] = values;
928
- }
1311
+ // Core hydration: properties (latest-wins), relations, timestamps/author
1312
+ const requestedProperties = opts?.properties && opts.properties.length > 0 ? opts.properties : undefined;
1313
+ await ctor.hydrateFromLinks(this, links, metadata, this._perspective, requestedProperties);
1314
+ }
929
1315
 
930
- // Set author and timestamps
931
- if (originalAuthor) {
932
- (this as any).author = originalAuthor;
933
- }
934
- if (minTimestamp) {
935
- (this as any).createdAt = minTimestamp;
936
- }
937
- if (maxTimestamp) {
938
- (this as any).updatedAt = maxTimestamp;
1316
+ // Populate reverse relation fields (belongsToOne / belongsToMany) as string IDs.
1317
+ const allRelsMeta = getRelationsMetadata(ctor as any);
1318
+ const requestedProps = opts?.properties && opts.properties.length > 0 ? new Set(opts.properties) : null;
1319
+ for (const [relName, relMeta] of Object.entries(allRelsMeta)) {
1320
+ if (relMeta.kind !== 'belongsToOne' && relMeta.kind !== 'belongsToMany') continue;
1321
+ if (requestedProps && !requestedProps.has(relName)) continue;
1322
+ const reverseLinks = await this._perspective.get(
1323
+ new LinkQuery({ predicate: relMeta.predicate, target: this._baseExpression })
1324
+ );
1325
+ const sourceIds = reverseLinks
1326
+ .filter((l) => l.data.target === this._baseExpression)
1327
+ .map((l) => l.data.source);
1328
+ if (relMeta.kind === 'belongsToOne') {
1329
+ (this as any)[relName] = sourceIds.length > 0 ? sourceIds[sourceIds.length - 1] : null;
1330
+ } else {
1331
+ (this as any)[relName] = sourceIds;
939
1332
  }
940
1333
  }
941
1334
 
942
1335
  // Evaluate SurrealQL getters
943
- await ctor.evaluateCustomGettersForInstance(this, this.#perspective, metadata);
944
-
945
- // Apply where.isInstance filtering to getter collections
946
- // (non-getter collections were already filtered above)
947
- for (const [collName, collMeta] of Object.entries(metadata.collections)) {
948
- if (collMeta.getter && collMeta.where?.isInstance && (this as any)[collName]?.length > 0) {
949
- try {
950
- const className = typeof collMeta.where.isInstance === 'string'
951
- ? collMeta.where.isInstance
952
- : collMeta.where.isInstance.name;
953
-
954
- const filterMetadata = await this.#perspective.getSubjectClassMetadataFromSDNA(className);
955
- if (filterMetadata) {
956
- const filtered = await this.#perspective.batchCheckSubjectInstances((this as any)[collName], filterMetadata);
957
- (this as any)[collName] = filtered;
958
- }
959
- } catch (error) {
960
- // Keep unfiltered values on error
961
- }
962
- }
1336
+ await ctor.evaluateCustomGettersForInstance(this, this._perspective, metadata);
1337
+
1338
+ // Eager-load relations if requested
1339
+ if (opts?.include) {
1340
+ await ctor.hydrateRelations([this], this._perspective, opts.include);
963
1341
  }
964
1342
  } catch (e) {
965
- console.error(`SurrealDB getData also failed for ${this.#baseExpression}:`, e);
1343
+ console.error(`SurrealDB getData also failed for ${this._baseExpression}:`, e);
966
1344
  }
967
1345
 
1346
+ this.takeSnapshot();
968
1347
  return this;
969
1348
  }
970
1349
 
971
1350
  // Todo: Only return AllInstances (InstancesWithOffset, SortedInstances, & UnsortedInstances not required)
972
1351
  public static async queryToProlog(perspective: PerspectiveProxy, query: Query, modelClassName?: string | null) {
973
- const { source, properties, collections, where, order, offset, limit, count } = query;
1352
+ const { properties, where, order, offset, limit, count } = query;
974
1353
  const className = modelClassName || (await this.getClassName(perspective));
975
1354
 
1355
+ // Resolve parent predicate from model metadata if needed
1356
+ const resolvedParentPredicate = query.parent
1357
+ ? resolveParentPredicate(query.parent, this)
1358
+ : undefined;
1359
+
976
1360
  const instanceQueries = [
977
1361
  buildAuthorAndTimestampQuery(),
978
- buildSourceQuery(source),
1362
+ buildParentQuery(query.parent, resolvedParentPredicate),
979
1363
  buildPropertiesQuery(properties),
980
- buildCollectionsQuery(collections),
981
1364
  buildWhereQuery(where),
982
1365
  ];
983
1366
 
@@ -996,7 +1379,7 @@ export class Ad4mModel {
996
1379
  }
997
1380
 
998
1381
  /**
999
- * Evaluates custom SurrealQL getters for properties and collections on a specific instance.
1382
+ * Evaluates custom SurrealQL getters for properties and relations on a specific instance.
1000
1383
  * @private
1001
1384
  */
1002
1385
  private static async evaluateCustomGettersForInstance(
@@ -1004,7 +1387,7 @@ export class Ad4mModel {
1004
1387
  perspective: PerspectiveProxy,
1005
1388
  metadata: any
1006
1389
  ) {
1007
- const safeBaseExpression = this.formatSurrealValue(instance.baseExpression);
1390
+ const safeBaseExpression = this.formatSurrealValue(instance.id);
1008
1391
 
1009
1392
  // Evaluate property getters
1010
1393
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
@@ -1025,27 +1408,273 @@ export class Ad4mModel {
1025
1408
  }
1026
1409
  }
1027
1410
 
1028
- // Evaluate collection getters
1029
- for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1030
- if ((collMeta as any).getter) {
1411
+ // Evaluate relation getters
1412
+ for (const [relName, relMeta] of Object.entries(metadata.relations)) {
1413
+ if ((relMeta as any).getter) {
1031
1414
  try {
1032
1415
  // Replace 'Base' placeholder with actual base expression
1033
- const query = (collMeta as any).getter.replace(/Base/g, safeBaseExpression);
1416
+ const query = (relMeta as any).getter.replace(/Base/g, safeBaseExpression);
1034
1417
  // Query from node table to have graph traversal context
1035
1418
  const result = await perspective.querySurrealDB(
1036
1419
  `SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`
1037
1420
  );
1038
1421
  if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
1039
- // Filter out 'None' from collection results
1422
+ // Filter out 'None' from relation results
1040
1423
  const value = result[0].value;
1041
- instance[collName] = Array.isArray(value)
1424
+ instance[relName] = Array.isArray(value)
1042
1425
  ? value.filter((v: any) => v !== undefined && v !== null && v !== '' && v !== 'None')
1043
1426
  : value;
1044
1427
  }
1045
1428
  } catch (error) {
1046
- console.warn(`Failed to evaluate getter for ${collName}:`, error);
1429
+ console.warn(`Failed to evaluate getter for ${relName}:`, error);
1430
+ }
1431
+ }
1432
+ }
1433
+ }
1434
+
1435
+ /**
1436
+ * Hydrates relation fields on instances according to the provided IncludeMap.
1437
+ *
1438
+ * For each relation listed in `includeMap`, the raw expression-URI strings
1439
+ * stored on the instance are replaced with fully-hydrated model instances
1440
+ * (fetched via the relation's `target()` class). Nested IncludeMaps are
1441
+ * supported for multi-level eager loading.
1442
+ *
1443
+ * @param instances - The instances whose relations should be hydrated
1444
+ * @param perspective - The perspective to fetch related instances from
1445
+ * @param includeMap - Describes which relations to hydrate
1446
+ * @private
1447
+ */
1448
+ private static async hydrateRelations<T extends Ad4mModel>(
1449
+ instances: T[],
1450
+ perspective: PerspectiveProxy,
1451
+ includeMap: IncludeMap | undefined,
1452
+ ): Promise<void> {
1453
+ if (!includeMap || Object.keys(includeMap).length === 0) return;
1454
+
1455
+ const relMeta = getRelationsMetadata(this);
1456
+
1457
+ for (const [relName, includeValue] of Object.entries(includeMap)) {
1458
+ const meta: RelationMetadataEntry | undefined = relMeta[relName];
1459
+ if (!meta) {
1460
+ console.warn(`include: relation "${relName}" not found in metadata, skipping`);
1461
+ continue;
1462
+ }
1463
+
1464
+ const TargetClass = meta.target() as unknown as typeof Ad4mModel;
1465
+
1466
+ // Determine if a RelationSubQuery was supplied (object) vs a plain `true`
1467
+ const subQuery: RelationSubQuery | undefined =
1468
+ typeof includeValue === 'object' && includeValue !== null
1469
+ ? (includeValue as RelationSubQuery)
1470
+ : undefined;
1471
+ const nestedInclude: IncludeMap | undefined = subQuery?.include;
1472
+
1473
+ // ── Reverse relations (belongsToOne / belongsToMany) ──────────────────
1474
+ // The link goes target→instance, so we query backwards:
1475
+ // predicate = meta.predicate, target = inst.id → source is the related id
1476
+ if (meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') {
1477
+ // Per-instance reverse lookup (can't batch easily across instances)
1478
+ for (const inst of instances) {
1479
+ const reverseLinks = await perspective.get(
1480
+ new LinkQuery({ predicate: meta.predicate, target: inst.id })
1481
+ );
1482
+ // Defensive filter: perspective.get may return extra results; ensure
1483
+ // we only use links that genuinely point to this instance.
1484
+ const sourceIds = reverseLinks
1485
+ .filter(l => l.data.target === inst.id)
1486
+ .map(l => l.data.source);
1487
+
1488
+ if (meta.kind === 'belongsToOne') {
1489
+ if (sourceIds.length === 0) {
1490
+ (inst as any)[relName] = null;
1491
+ continue;
1492
+ }
1493
+ const sourceId = sourceIds[sourceIds.length - 1]; // latest-wins
1494
+ try {
1495
+ const related = new TargetClass(perspective, sourceId);
1496
+ await related.get();
1497
+ (inst as any)[relName] = related;
1498
+ } catch {
1499
+ (inst as any)[relName] = null;
1500
+ }
1501
+ } else {
1502
+ // belongsToMany — return array of hydrated instances
1503
+ let hydrated: Ad4mModel[] = [];
1504
+
1505
+ // If there's a where/order sub-query, delegate to findAll for filtering
1506
+ if (subQuery && (subQuery.where || subQuery.order || subQuery.properties)) {
1507
+ const whereWithIds: Record<string, any> = {
1508
+ id: sourceIds,
1509
+ ...(subQuery.where ?? {}),
1510
+ };
1511
+ hydrated = await TargetClass.findAll(perspective, {
1512
+ where: whereWithIds as any,
1513
+ ...(subQuery.order && { order: subQuery.order as any }),
1514
+ ...(subQuery.properties && { properties: subQuery.properties }),
1515
+ });
1516
+ } else {
1517
+ await Promise.all(sourceIds.map(async (sid) => {
1518
+ try {
1519
+ const related = new TargetClass(perspective, sid);
1520
+ await related.get(
1521
+ subQuery?.properties ? { properties: subQuery.properties } : undefined
1522
+ );
1523
+ hydrated.push(related);
1524
+ } catch { /* skip */ }
1525
+ }));
1526
+ }
1527
+
1528
+ // Apply order (client-side, if not already handled by findAll above)
1529
+ if (subQuery?.order && !(subQuery.where || subQuery.properties)) {
1530
+ const orderEntries = Object.entries(subQuery.order);
1531
+ hydrated = hydrated.sort((a, b) => {
1532
+ for (const [field, dir] of orderEntries) {
1533
+ const av = String((a as any)[field] ?? '');
1534
+ const bv = String((b as any)[field] ?? '');
1535
+ const diff = av.localeCompare(bv);
1536
+ if (diff !== 0) return dir === 'DESC' ? -diff : diff;
1537
+ }
1538
+ return 0;
1539
+ });
1540
+ }
1541
+
1542
+ // Apply offset and limit
1543
+ if (subQuery?.offset != null || subQuery?.limit != null) {
1544
+ const start = subQuery.offset ?? 0;
1545
+ const end = subQuery.limit != null ? start + subQuery.limit : undefined;
1546
+ hydrated = hydrated.slice(start, end);
1547
+ }
1548
+
1549
+ (inst as any)[relName] = hydrated;
1550
+
1551
+ // Recurse for nested includes
1552
+ if (nestedInclude && hydrated.length > 0) {
1553
+ await TargetClass.hydrateRelations(hydrated, perspective, nestedInclude);
1554
+ }
1555
+ }
1556
+ }
1557
+ continue; // skip the forward-relation path below
1558
+ }
1559
+
1560
+ // ── Forward relations (hasMany / hasOne) ──────────────────────────────
1561
+ // Collect all unique URIs across all instances for batch-friendly lookup.
1562
+ // IMPORTANT: We cache each instance's raw value NOW (before the async
1563
+ // findAll) so that concurrent getData() calls on the same instance can't
1564
+ // overwrite the relation field between the uriSet relation and the
1565
+ // post-await assignment loop. Without this cache, a concurrent call
1566
+ // can replace the raw URI strings with hydrated model objects, causing
1567
+ // the `typeof v === 'string'` check to fail and the array to end up empty.
1568
+ const uriSet = new Set<string>();
1569
+ const rawCache = new Map<T, any>();
1570
+ for (const inst of instances) {
1571
+ const raw = (inst as any)[relName];
1572
+ rawCache.set(inst, Array.isArray(raw) ? [...raw] : raw);
1573
+ if (raw == null) continue;
1574
+ if (Array.isArray(raw)) {
1575
+ for (const v of raw) {
1576
+ if (typeof v === 'string') uriSet.add(v);
1577
+ // Handle already-hydrated instances (from a concurrent call)
1578
+ else if (v && typeof v === 'object' && typeof v.id === 'string') uriSet.add(v.id);
1579
+ }
1580
+ } else if (typeof raw === 'string') {
1581
+ uriSet.add(raw);
1582
+ } else if (raw && typeof raw === 'object' && typeof raw.id === 'string') {
1583
+ uriSet.add(raw.id);
1584
+ }
1585
+ }
1586
+
1587
+ if (uriSet.size === 0) continue;
1588
+
1589
+ // Hydrate related instances using findAll to ensure conformance checking.
1590
+ // findAll validates model membership via graph traversal (required predicates / flags),
1591
+ // so non-conforming linked URIs are silently dropped — matching the documented behaviour.
1592
+ const hydrated = new Map<string, Ad4mModel>();
1593
+
1594
+ const whereWithIds: Record<string, any> = {
1595
+ id: Array.from(uriSet),
1596
+ ...(subQuery?.where ?? {}),
1597
+ };
1598
+ const fetchQuery: any = {
1599
+ where: whereWithIds,
1600
+ ...(subQuery?.order && { order: subQuery.order }),
1601
+ ...(subQuery?.properties && { properties: subQuery.properties }),
1602
+ };
1603
+ const results = await TargetClass.findAll(perspective, fetchQuery);
1604
+ for (const result of results) {
1605
+ hydrated.set(result.id, result);
1606
+ }
1607
+
1608
+ // Replace raw URIs with hydrated instances on each parent instance.
1609
+ // Use the cached raw values captured BEFORE the async findAll to avoid
1610
+ // the race condition where a concurrent getData() already replaced the
1611
+ // strings with hydrated objects.
1612
+ for (const inst of instances) {
1613
+ const raw = rawCache.get(inst);
1614
+ if (raw == null) continue;
1615
+ if (Array.isArray(raw)) {
1616
+ // Map URIs → instances; handle both raw strings and already-hydrated objects
1617
+ let resolved: Ad4mModel[] = raw
1618
+ .map((v: any) => {
1619
+ if (typeof v === 'string') {
1620
+ return hydrated.has(v) ? hydrated.get(v)! : null;
1621
+ }
1622
+ // Already a hydrated model instance (from a concurrent call)
1623
+ if (v && typeof v === 'object' && typeof v.id === 'string') {
1624
+ return hydrated.has(v.id) ? hydrated.get(v.id)! : v;
1625
+ }
1626
+ return null;
1627
+ })
1628
+ .filter((v): v is Ad4mModel => v !== null);
1629
+
1630
+ // Per-instance sort (client-side, after filtering)
1631
+ if (subQuery?.order) {
1632
+ const orderEntries = Object.entries(subQuery.order);
1633
+ resolved = resolved.sort((a, b) => {
1634
+ for (const [field, dir] of orderEntries) {
1635
+ const av = String((a as any)[field] ?? '');
1636
+ const bv = String((b as any)[field] ?? '');
1637
+ const diff = av.localeCompare(bv);
1638
+ if (diff !== 0) return dir === 'DESC' ? -diff : diff;
1639
+ }
1640
+ return 0;
1641
+ });
1642
+ }
1643
+
1644
+ // Per-instance limit / offset
1645
+ if (subQuery?.offset != null || subQuery?.limit != null) {
1646
+ const start = subQuery.offset ?? 0;
1647
+ const end =
1648
+ subQuery.limit != null ? start + subQuery.limit : undefined;
1649
+ resolved = resolved.slice(start, end);
1650
+ }
1651
+
1652
+ // Enforce maxCount guard — single-valued relations keep only the last item
1653
+ if (meta.maxCount === 1) {
1654
+ if (resolved.length > 1) {
1655
+ console.warn(
1656
+ `include: relation "${relName}" has maxCount 1 but ${resolved.length} values found; keeping the last`,
1657
+ );
1658
+ }
1659
+ (inst as any)[relName] = resolved.length > 0
1660
+ ? resolved[resolved.length - 1]
1661
+ : null;
1662
+ } else {
1663
+ (inst as any)[relName] = resolved;
1664
+ }
1665
+ } else if (typeof raw === 'string' && hydrated.has(raw)) {
1666
+ (inst as any)[relName] = hydrated.get(raw);
1667
+ } else if (raw && typeof raw === 'object' && typeof raw.id === 'string') {
1668
+ // Already-hydrated object — look up refreshed version or keep as-is
1669
+ (inst as any)[relName] = hydrated.has(raw.id) ? hydrated.get(raw.id) : raw;
1047
1670
  }
1048
1671
  }
1672
+
1673
+ // Recurse for nested includes
1674
+ if (nestedInclude) {
1675
+ const hydratedInstances = Array.from(hydrated.values());
1676
+ await TargetClass.hydrateRelations(hydratedInstances, perspective, nestedInclude);
1677
+ }
1049
1678
  }
1050
1679
  }
1051
1680
 
@@ -1060,18 +1689,18 @@ export class Ad4mModel {
1060
1689
  *
1061
1690
  * The generated query uses a CTE (Common Table Expression) pattern:
1062
1691
  * 1. First, identify candidate base expressions by filtering links based on where conditions
1063
- * 2. Then, for each candidate base, resolve properties and collections via subqueries
1692
+ * 2. Then, for each candidate base, resolve properties and relations via subqueries
1064
1693
  * 3. Finally, apply ordering, pagination (LIMIT/START) at the SQL level
1065
1694
  *
1066
1695
  * Key architectural notes:
1067
1696
  * - SurrealDB stores only raw links (source, predicate, target, author, timestamp)
1068
1697
  * - No SDNA knowledge at the database level
1069
1698
  * - Properties are resolved via subqueries that look for links with specific predicates
1070
- * - Collections are similar but return multiple values instead of one
1699
+ * - Relations are similar but return multiple values instead of one
1071
1700
  * - Special fields (base, author, timestamp) are accessed directly, not via subqueries
1072
1701
  *
1073
1702
  * @param perspective - The perspective to query (used for metadata extraction)
1074
- * @param query - Query parameters (where, order, limit, offset, properties, collections)
1703
+ * @param query - Query parameters (where, order, limit, offset, properties, relations)
1075
1704
  * @returns Complete SurrealQL query string ready for execution
1076
1705
  *
1077
1706
  * @example
@@ -1087,54 +1716,82 @@ export class Ad4mModel {
1087
1716
  */
1088
1717
  public static async queryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
1089
1718
  const metadata = this.getModelMetadata();
1090
- const { source, where, order, offset, limit } = query;
1719
+ const { where, order, offset, limit } = query;
1091
1720
 
1092
1721
  // Build list of graph traversal filters for required predicates
1093
1722
  const graphTraversalFilters: string[] = [];
1094
1723
 
1095
- // Add source filter if specified (filter to nodes that are children of this source)
1096
- // Source filter means: find targets of 'ad4m://has_child' links from the specified source
1097
- if (source) {
1098
- // Use graph traversal: node must be target of has_child link from source
1724
+ // Add parent filter if specified (filter to nodes linked from a parent via a specific predicate)
1725
+ if (query.parent) {
1726
+ const parentPredicate = resolveParentPredicate(query.parent, this);
1099
1727
  graphTraversalFilters.push(
1100
- `count(<-link[WHERE perspective = $perspective AND in.uri = ${this.formatSurrealValue(source)} AND predicate = 'ad4m://has_child']) > 0`
1728
+ `count(<-link[WHERE in.uri = ${this.formatSurrealValue(query.parent.id)} AND predicate = '${escapeSurrealString(parentPredicate)}']) > 0`
1101
1729
  );
1102
1730
  }
1103
1731
 
1104
1732
  // Add filters for required properties
1105
1733
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1106
1734
  if (propMeta.required) {
1735
+ // Skip properties with a getter — they are computed dynamically
1736
+ // and may not have a stored link with their predicate, so requiring their
1737
+ // presence would wrongly exclude valid model instances.
1738
+ if (propMeta.getter) continue;
1739
+
1107
1740
  // For flag properties, also filter by the target value
1108
1741
  if (propMeta.flag && propMeta.initial) {
1109
1742
  graphTraversalFilters.push(
1110
- `count(->link[WHERE perspective = $perspective AND predicate = '${escapeSurrealString(propMeta.predicate)}' AND out.uri = '${escapeSurrealString(propMeta.initial)}']) > 0`
1743
+ `count(->link[WHERE predicate = '${escapeSurrealString(propMeta.predicate)}' AND out.uri = '${escapeSurrealString(propMeta.initial)}']) > 0`
1111
1744
  );
1112
1745
  } else {
1113
1746
  graphTraversalFilters.push(
1114
- `count(->link[WHERE perspective = $perspective AND predicate = '${escapeSurrealString(propMeta.predicate)}']) > 0`
1747
+ `count(->link[WHERE predicate = '${escapeSurrealString(propMeta.predicate)}']) > 0`
1115
1748
  );
1116
1749
  }
1117
1750
  }
1118
1751
  }
1119
1752
 
1120
- // If no required properties, we need at least one property to define the model
1121
- // Use any property with an initial value as the defining characteristic
1753
+ // If no required properties produced filters, try properties with initial
1754
+ // values (e.g. @Flag or @Property with an explicit initial).
1122
1755
  if (graphTraversalFilters.length === 0) {
1123
1756
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1124
1757
  if (propMeta.initial) {
1125
- // For flag properties, also filter by the target value
1126
1758
  if (propMeta.flag) {
1127
1759
  graphTraversalFilters.push(
1128
- `count(->link[WHERE perspective = $perspective AND predicate = '${escapeSurrealString(propMeta.predicate)}' AND out.uri = '${escapeSurrealString(propMeta.initial)}']) > 0`
1760
+ `count(->link[WHERE predicate = '${escapeSurrealString(propMeta.predicate)}' AND out.uri = '${escapeSurrealString(propMeta.initial)}']) > 0`
1129
1761
  );
1130
1762
  } else {
1131
1763
  graphTraversalFilters.push(
1132
- `count(->link[WHERE perspective = $perspective AND predicate = '${escapeSurrealString(propMeta.predicate)}']) > 0`
1764
+ `count(->link[WHERE predicate = '${escapeSurrealString(propMeta.predicate)}']) > 0`
1133
1765
  );
1134
1766
  }
1135
- break; // Just need one defining property
1767
+ break;
1768
+ }
1769
+ }
1770
+ }
1771
+
1772
+ // Still no filters → open-world structural matching.
1773
+ // Require the node to have at least one link whose predicate is declared
1774
+ // by this model (property OR relation). This prevents the query from
1775
+ // matching every node in the perspective.
1776
+ if (graphTraversalFilters.length === 0) {
1777
+ const structuralPredicates: string[] = [];
1778
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
1779
+ if (propMeta.predicate) {
1780
+ structuralPredicates.push(`predicate = '${escapeSurrealString(propMeta.predicate)}'`);
1781
+ }
1782
+ }
1783
+ if (metadata.relations) {
1784
+ for (const [, relMeta] of Object.entries(metadata.relations)) {
1785
+ if (relMeta.predicate) {
1786
+ structuralPredicates.push(`predicate = '${escapeSurrealString(relMeta.predicate)}'`);
1787
+ }
1136
1788
  }
1137
1789
  }
1790
+ if (structuralPredicates.length > 0) {
1791
+ graphTraversalFilters.push(
1792
+ `count(->link[WHERE (${structuralPredicates.join(' OR ')})]) > 0`
1793
+ );
1794
+ }
1138
1795
  }
1139
1796
 
1140
1797
  // Build user WHERE clause filters using graph traversal
@@ -1151,18 +1808,21 @@ export class Ad4mModel {
1151
1808
  whereConditions.push(userWhereClause);
1152
1809
  }
1153
1810
 
1154
- // Always ensure node has at least one link in this perspective
1155
- whereConditions.push(`count(->link[WHERE perspective = $perspective]) > 0`);
1811
+ // Always ensure node has at least one link (each perspective has its own isolated DB)
1812
+ whereConditions.push(`count(->link) > 0`);
1156
1813
 
1157
1814
  // Build the query FROM node using direct graph traversal in WHERE
1158
1815
  // This avoids slow subqueries and uses graph indexes for fast traversal
1816
+ // FETCH links expands the link record IDs into full record objects
1817
+ // (without FETCH, ->link returns only IDs like "link:abc123")
1159
1818
  const fullQuery = `
1160
1819
  SELECT
1161
1820
  id AS source,
1162
1821
  uri AS source_uri,
1163
- ->link[WHERE perspective = $perspective] AS links
1822
+ ->link AS links
1164
1823
  FROM node
1165
1824
  WHERE ${whereConditions.join(' AND ')}
1825
+ FETCH links
1166
1826
  `.trim();
1167
1827
 
1168
1828
  return fullQuery;
@@ -1194,18 +1854,18 @@ WHERE ${whereConditions.join(' AND ')}
1194
1854
  const conditions: string[] = [];
1195
1855
 
1196
1856
  for (const [propertyName, condition] of Object.entries(where)) {
1197
- // Check if this is a special field (base, author, timestamp)
1857
+ // Check if this is a special field (id, author, timestamp)
1198
1858
  // Note: author and timestamp filtering is done in JavaScript after query
1199
- const isSpecial = ['base', 'author', 'timestamp'].includes(propertyName);
1859
+ const isSpecial = ['id', 'author', 'timestamp'].includes(propertyName);
1200
1860
 
1201
1861
  if (isSpecial) {
1202
1862
  // Skip author and timestamp - they'll be filtered in JavaScript
1203
- // Only handle 'base' (which maps to 'uri') here
1863
+ // Only handle 'id' (which maps to 'uri') here
1204
1864
  if (propertyName === 'author' || propertyName === 'timestamp') {
1205
1865
  continue; // Skip - will be filtered post-query
1206
1866
  }
1207
1867
 
1208
- const columnName = 'uri'; // base maps to uri in node table
1868
+ const columnName = 'uri'; // id maps to uri in node table
1209
1869
 
1210
1870
  // Handle base/uri field directly
1211
1871
  if (Array.isArray(condition)) {
@@ -1246,7 +1906,54 @@ WHERE ${whereConditions.join(' AND ')}
1246
1906
  conditions.push(`${columnName} = ${this.formatSurrealValue(condition)}`);
1247
1907
  }
1248
1908
  } else {
1249
- // Handle regular properties via graph traversal
1909
+ // Handle regular properties via graph traversal.
1910
+ // IMPORTANT: Check relation metadata first — @BelongsToOne / @BelongsToMany
1911
+ // also write into propertyRegistry, but the link direction is inverted.
1912
+ // If we matched the property path they would get a forward ->link filter
1913
+ // which is wrong for belongs-to relations.
1914
+ const allRelations = getRelationsMetadata(this);
1915
+ const relMeta = allRelations[propertyName];
1916
+ const isBelongs = relMeta?.kind === 'belongsToOne' || relMeta?.kind === 'belongsToMany';
1917
+
1918
+ if (relMeta) {
1919
+ const predicate = escapeSurrealString(relMeta.predicate);
1920
+
1921
+ if (Array.isArray(condition)) {
1922
+ const formattedValues = condition.map(v => this.formatSurrealValue(v)).join(', ');
1923
+ if (isBelongs) {
1924
+ conditions.push(`count(<-link[WHERE predicate = '${predicate}' AND in.uri IN [${formattedValues}]]) > 0`);
1925
+ } else {
1926
+ conditions.push(`count(->link[WHERE predicate = '${predicate}' AND out.uri IN [${formattedValues}]]) > 0`);
1927
+ }
1928
+ } else if (typeof condition === 'object' && condition !== null) {
1929
+ const ops = condition as any;
1930
+ if (ops.not !== undefined) {
1931
+ if (Array.isArray(ops.not)) {
1932
+ const formattedValues = ops.not.map(v => this.formatSurrealValue(v)).join(', ');
1933
+ if (isBelongs) {
1934
+ conditions.push(`count(<-link[WHERE predicate = '${predicate}' AND in.uri IN [${formattedValues}]]) = 0`);
1935
+ } else {
1936
+ conditions.push(`count(->link[WHERE predicate = '${predicate}' AND out.uri IN [${formattedValues}]]) = 0`);
1937
+ }
1938
+ } else {
1939
+ if (isBelongs) {
1940
+ conditions.push(`count(<-link[WHERE predicate = '${predicate}' AND in.uri = ${this.formatSurrealValue(ops.not)}]) = 0`);
1941
+ } else {
1942
+ conditions.push(`count(->link[WHERE predicate = '${predicate}' AND out.uri = ${this.formatSurrealValue(ops.not)}]) = 0`);
1943
+ }
1944
+ }
1945
+ }
1946
+ } else {
1947
+ // Simple equality
1948
+ if (isBelongs) {
1949
+ conditions.push(`count(<-link[WHERE predicate = '${predicate}' AND in.uri = ${this.formatSurrealValue(condition)}]) > 0`);
1950
+ } else {
1951
+ conditions.push(`count(->link[WHERE predicate = '${predicate}' AND out.uri = ${this.formatSurrealValue(condition)}]) > 0`);
1952
+ }
1953
+ }
1954
+ continue;
1955
+ }
1956
+
1250
1957
  const propMeta = metadata.properties[propertyName];
1251
1958
  if (!propMeta) continue; // Skip if property not found in metadata
1252
1959
 
@@ -1257,7 +1964,7 @@ WHERE ${whereConditions.join(' AND ')}
1257
1964
  if (Array.isArray(condition)) {
1258
1965
  // Array values (IN clause)
1259
1966
  const formattedValues = condition.map(v => this.formatSurrealValue(v)).join(', ');
1260
- conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}' AND ${targetField} IN [${formattedValues}]]) > 0`);
1967
+ conditions.push(`count(->link[WHERE predicate = '${predicate}' AND ${targetField} IN [${formattedValues}]]) > 0`);
1261
1968
  } else if (typeof condition === 'object' && condition !== null) {
1262
1969
  // Operator object
1263
1970
  const ops = condition as any;
@@ -1265,10 +1972,10 @@ WHERE ${whereConditions.join(' AND ')}
1265
1972
  if (Array.isArray(ops.not)) {
1266
1973
  // For NOT IN with array: must NOT have a link with value in the array
1267
1974
  const formattedValues = ops.not.map(v => this.formatSurrealValue(v)).join(', ');
1268
- conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}' AND ${targetField} IN [${formattedValues}]]) = 0`);
1975
+ conditions.push(`count(->link[WHERE predicate = '${predicate}' AND ${targetField} IN [${formattedValues}]]) = 0`);
1269
1976
  } else {
1270
1977
  // For NOT with single value: must NOT have this value
1271
- conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(ops.not)}]) = 0`);
1978
+ conditions.push(`count(->link[WHERE predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(ops.not)}]) = 0`);
1272
1979
  }
1273
1980
  }
1274
1981
  // Note: gt, gte, lt, lte, between, contains operators are filtered in JavaScript
@@ -1281,11 +1988,11 @@ WHERE ${whereConditions.join(' AND ')}
1281
1988
  ops.between !== undefined || ops.contains !== undefined;
1282
1989
  if (hasComparisonOps) {
1283
1990
  // Ensure we only get nodes that have this property
1284
- conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}']) > 0`);
1991
+ conditions.push(`count(->link[WHERE predicate = '${predicate}']) > 0`);
1285
1992
  }
1286
1993
  } else {
1287
1994
  // Simple equality
1288
- conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(condition)}]) > 0`);
1995
+ conditions.push(`count(->link[WHERE predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(condition)}]) > 0`);
1289
1996
  }
1290
1997
  }
1291
1998
  }
@@ -1325,19 +2032,19 @@ WHERE ${whereConditions.join(' AND ')}
1325
2032
  const conditions: string[] = [];
1326
2033
 
1327
2034
  for (const [propertyName, condition] of Object.entries(where)) {
1328
- // Check if this is a special field (base, author, timestamp)
2035
+ // Check if this is a special field (id, author, timestamp)
1329
2036
  // Note: author and timestamp filtering is done in JavaScript after GROUP BY
1330
2037
  // because they need to be computed from the grouped links first
1331
- const isSpecial = ['base', 'author', 'timestamp'].includes(propertyName);
2038
+ const isSpecial = ['id', 'author', 'timestamp'].includes(propertyName);
1332
2039
 
1333
2040
  if (isSpecial) {
1334
2041
  // Skip author and timestamp - they'll be filtered in JavaScript
1335
- // Only handle 'base' (which maps to 'source') here
2042
+ // Only handle 'id' (which maps to 'source') here
1336
2043
  if (propertyName === 'author' || propertyName === 'timestamp') {
1337
2044
  continue; // Skip - will be filtered post-query
1338
2045
  }
1339
2046
 
1340
- const columnName = 'source'; // base maps to source
2047
+ const columnName = 'source'; // id maps to source
1341
2048
 
1342
2049
  // Handle base/source field directly
1343
2050
  if (Array.isArray(condition)) {
@@ -1429,26 +2136,26 @@ WHERE ${whereConditions.join(' AND ')}
1429
2136
  * Builds the SELECT fields for SurrealQL queries.
1430
2137
  *
1431
2138
  * @description
1432
- * Generates the field list for the SELECT clause, resolving properties and collections
2139
+ * Generates the field list for the SELECT clause, resolving properties and relations
1433
2140
  * via subqueries. Each property is fetched with a subquery that finds the link with the
1434
- * appropriate predicate and returns its target. Collections are similar but don't use LIMIT 1.
2141
+ * appropriate predicate and returns its target. Relations are similar but don't use LIMIT 1.
1435
2142
  *
1436
2143
  * Field types:
1437
2144
  * - Properties: `(SELECT VALUE target FROM link WHERE source = $parent.base AND predicate = 'X' LIMIT 1) AS propName`
1438
- * - Collections: `(SELECT VALUE target FROM link WHERE source = $parent.base AND predicate = 'X') AS collName`
2145
+ * - Relations: `(SELECT VALUE target FROM link WHERE source = $parent.base AND predicate = 'X') AS relName`
1439
2146
  * - Author/Timestamp: Always included to provide metadata about each instance
1440
2147
  *
1441
- * If properties or collections arrays are provided, only those fields are included.
1442
- * Otherwise, all properties/collections from metadata are included.
2148
+ * If properties or relations arrays are provided, only those fields are included.
2149
+ * Otherwise, all properties/relations from metadata are included.
1443
2150
  *
1444
- * @param metadata - Model metadata containing property and collection predicates
2151
+ * @param metadata - Model metadata containing property and relation predicates
1445
2152
  * @param properties - Optional array of property names to include (default: all)
1446
- * @param collections - Optional array of collection names to include (default: all)
2153
+ * @param relations - Optional array of relation names to include (default: all)
1447
2154
  * @returns Comma-separated SELECT field list
1448
2155
  *
1449
2156
  * @private
1450
2157
  */
1451
- private static buildSurrealSelectFields(metadata: ModelMetadata, properties?: string[], collections?: string[]): string {
2158
+ private static buildSurrealSelectFields(metadata: ModelMetadata, properties?: string[], relations?: string[]): string {
1452
2159
  const fields: string[] = [];
1453
2160
 
1454
2161
  // Determine properties to fetch
@@ -1462,15 +2169,15 @@ WHERE ${whereConditions.join(' AND ')}
1462
2169
  fields.push(`(SELECT VALUE target FROM link WHERE source = source AND predicate = '${escapedPredicate}' LIMIT 1) AS ${propName}`);
1463
2170
  }
1464
2171
 
1465
- // Determine collections to fetch
1466
- const collsToFetch = collections || Object.keys(metadata.collections);
1467
- for (const collName of collsToFetch) {
1468
- const collMeta = metadata.collections[collName];
1469
- if (!collMeta) continue; // Skip if not found
2172
+ // Determine relations to fetch
2173
+ const relsToFetch = relations || Object.keys(metadata.relations);
2174
+ for (const relName of relsToFetch) {
2175
+ const relMeta = metadata.relations[relName];
2176
+ if (!relMeta) continue; // Skip if not found
1470
2177
 
1471
2178
  // Reference source directly since we're selecting from link table
1472
- const escapedPredicate = escapeSurrealString(collMeta.predicate);
1473
- fields.push(`(SELECT VALUE target FROM link WHERE source = source AND predicate = '${escapedPredicate}') AS ${collName}`);
2179
+ const escapedPredicate = escapeSurrealString(relMeta.predicate);
2180
+ fields.push(`(SELECT VALUE target FROM link WHERE source = source AND predicate = '${escapedPredicate}') AS ${relName}`);
1474
2181
  }
1475
2182
 
1476
2183
  // Always add author and timestamp fields
@@ -1487,7 +2194,7 @@ WHERE ${whereConditions.join(' AND ')}
1487
2194
  *
1488
2195
  * @private
1489
2196
  */
1490
- private static buildSurrealSelectFieldsWithAggregation(metadata: ModelMetadata, properties?: string[], collections?: string[]): string {
2197
+ private static buildSurrealSelectFieldsWithAggregation(metadata: ModelMetadata, properties?: string[], relations?: string[]): string {
1491
2198
  const fields: string[] = [];
1492
2199
 
1493
2200
  // Determine properties to fetch
@@ -1501,15 +2208,15 @@ WHERE ${whereConditions.join(' AND ')}
1501
2208
  fields.push(`array::first(target[WHERE predicate = '${escapedPredicate}']) AS ${propName}`);
1502
2209
  }
1503
2210
 
1504
- // Determine collections to fetch
1505
- const collsToFetch = collections || Object.keys(metadata.collections);
1506
- for (const collName of collsToFetch) {
1507
- const collMeta = metadata.collections[collName];
1508
- if (!collMeta) continue; // Skip if not found
2211
+ // Determine relations to fetch
2212
+ const relsToFetch = relations || Object.keys(metadata.relations);
2213
+ for (const relName of relsToFetch) {
2214
+ const relMeta = metadata.relations[relName];
2215
+ if (!relMeta) continue; // Skip if not found
1509
2216
 
1510
2217
  // Use array filtering to get all target values for this predicate
1511
- const escapedPredicate = escapeSurrealString(collMeta.predicate);
1512
- fields.push(`target[WHERE predicate = '${escapedPredicate}'] AS ${collName}`);
2218
+ const escapedPredicate = escapeSurrealString(relMeta.predicate);
2219
+ fields.push(`target[WHERE predicate = '${escapedPredicate}'] AS ${relName}`);
1513
2220
  }
1514
2221
 
1515
2222
  // Always add author and timestamp fields
@@ -1563,15 +2270,15 @@ WHERE ${whereConditions.join(' AND ')}
1563
2270
  ): Promise<ResultsWithTotalCount<T>> {
1564
2271
  if (!result?.[0]?.AllInstances) return { results: [], totalCount: 0 };
1565
2272
  // Map results to instances
1566
- const requestedAttribtes = [...(query?.properties || []), ...(query?.collections || [])];
2273
+ const requestedProperties = query?.properties || [];
1567
2274
  const allInstances = await Promise.all(
1568
2275
  result[0].AllInstances.map(async ([Base, Properties, Collections, Timestamp, Author]) => {
1569
2276
  try {
1570
2277
  const instance = new this(perspective, Base) as any;
1571
2278
  // Remove unrequested attributes from instance
1572
- if (requestedAttribtes.length) {
2279
+ if (requestedProperties.length) {
1573
2280
  Object.keys(instance).forEach((key) => {
1574
- if (!requestedAttribtes.includes(key)) delete instance[key];
2281
+ if (!requestedProperties.includes(key) && key !== 'createdAt' && key !== 'updatedAt' && key !== 'author' && key !== 'id' && key !== 'baseExpression') delete instance[key];
1575
2282
  });
1576
2283
  }
1577
2284
  // Collect values to assign to instance
@@ -1586,7 +2293,24 @@ WHERE ${whereConditions.join(' AND ')}
1586
2293
  }
1587
2294
  })
1588
2295
  );
1589
- return { results: allInstances.filter((instance) => instance !== null), totalCount: result[0].TotalCount };
2296
+ const instances = allInstances.filter((instance) => instance !== null) as T[];
2297
+
2298
+ // Eager-load relations if requested (BEFORE snapshot so dirty tracking is accurate)
2299
+ if (query.include && instances.length > 0) {
2300
+ await this.hydrateRelations(instances, perspective, query.include);
2301
+ }
2302
+
2303
+ // Take snapshots for dirty tracking after ALL hydration is complete
2304
+ // (including eager-loaded relations).
2305
+ // When `include` is specified, only snapshot those relations.
2306
+ // Otherwise snapshot ALL fields (properties + relations) since
2307
+ // hydrateFromLinks populates relations with stable raw IDs.
2308
+ const snapshotRelations = query.include;
2309
+ for (const inst of instances) {
2310
+ (inst as Ad4mModel).takeSnapshot(snapshotRelations);
2311
+ }
2312
+
2313
+ return { results: instances, totalCount: result[0].TotalCount };
1590
2314
  }
1591
2315
 
1592
2316
  /**
@@ -1609,7 +2333,6 @@ WHERE ${whereConditions.join(' AND ')}
1609
2333
 
1610
2334
  const metadata = this.getModelMetadata();
1611
2335
  const requestedProperties = query?.properties || [];
1612
- const requestedCollections = query?.collections || [];
1613
2336
 
1614
2337
  // The query used GROUP BY with graph traversal, so each row has:
1615
2338
  // - source: the node ID (e.g., "node:abc123")
@@ -1631,254 +2354,73 @@ WHERE ${whereConditions.join(' AND ')}
1631
2354
  const links = row.links || [];
1632
2355
 
1633
2356
  const instance = new this(perspective, base) as any;
2357
+
2358
+ // Core hydration via unified helper (pass requestedProperties for sparse fieldset)
2359
+ await this.hydrateFromLinks(instance, links, metadata, perspective, requestedProperties.length > 0 ? requestedProperties : undefined);
1634
2360
 
1635
- // Track both earliest (createdAt) and most recent (updatedAt) timestamps
1636
- let minTimestamp = null;
1637
- let maxTimestamp = null;
1638
- let originalAuthor = null;
1639
- let latestAuthor = null;
1640
-
1641
- // Process each link (track index for collection ordering)
1642
- for (let linkIndex = 0; linkIndex < links.length; linkIndex++) {
1643
- const link = links[linkIndex];
1644
- const predicate = link.predicate;
1645
- const target = link.target;
1646
-
1647
- // Skip 'None' values
1648
- if (target === 'None') continue;
1649
-
1650
- // Track both earliest (createdAt) and latest (updatedAt) timestamps with their authors
1651
- if (link.timestamp) {
1652
- if (!minTimestamp || link.timestamp < minTimestamp) {
1653
- minTimestamp = link.timestamp;
1654
- originalAuthor = link.author;
1655
- }
1656
- if (!maxTimestamp || link.timestamp > maxTimestamp) {
1657
- maxTimestamp = link.timestamp;
1658
- latestAuthor = link.author;
2361
+ // When specific properties are requested, delete unrequested properties
2362
+ // so they return undefined instead of their constructor defaults (e.g. 0, [])
2363
+ if (requestedProperties.length > 0) {
2364
+ const requested = new Set(requestedProperties);
2365
+ for (const propName of Object.keys(metadata.properties)) {
2366
+ if (!requested.has(propName)) {
2367
+ delete instance[propName];
1659
2368
  }
1660
2369
  }
1661
-
1662
- // Find matching property (skip those with getter)
1663
- let foundProperty = false;
1664
- for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1665
- if (propMeta.getter) continue; // Handle via getter evaluation
1666
- if (propMeta.predicate === predicate) {
1667
- // For properties, take the first value (or we could use timestamp to get latest)
1668
- // Note: Empty objects {} are truthy, so we need to check for them explicitly
1669
- const currentValue = instance[propName];
1670
- const isEmptyObject = typeof currentValue === 'object' && currentValue !== null && !Array.isArray(currentValue) && Object.keys(currentValue).length === 0;
1671
- if (!currentValue || currentValue === "" || currentValue === 0 || isEmptyObject) {
1672
- let convertedValue = target;
1673
-
1674
- // Only process if target has a value
1675
- if (target !== undefined && target !== null && target !== '') {
1676
- // Check if we need to resolve a non-literal language expression.
1677
- // resolveLanguage must be defined and not 'literal' to trigger expression resolution.
1678
- // Also skip if the target itself is a literal:// URI — those are handled by the
1679
- // literal-parsing branch below (avoids calling getExpression on empty literals like
1680
- // "literal://string:" which would cause a deserialization error).
1681
- if (propMeta.resolveLanguage != undefined && propMeta.resolveLanguage !== 'literal' && typeof target === 'string' && !target.startsWith('literal://')) {
1682
- // For non-literal languages, resolve the expression via perspective.getExpression()
1683
- // Note: Literals are already parsed by SurrealDB's fn::parse_literal()
1684
- try {
1685
- const expression = await perspective.getExpression(target);
1686
- if (expression) {
1687
- // Parse the expression data if it's a JSON string
1688
- try {
1689
- convertedValue = JSON.parse(expression.data);
1690
- } catch {
1691
- // If parsing fails, use the data as-is
1692
- convertedValue = expression.data;
1693
- }
1694
- }
1695
- } catch (e) {
1696
- console.warn(`Failed to resolve expression for ${propName} with target "${target}":`, e);
1697
- console.warn("Falling back to raw value");
1698
- convertedValue = target; // Fall back to raw value
1699
- }
1700
- } else if (propMeta.resolveLanguage === 'literal' && typeof target === 'string' && target.startsWith('literal://')) {
1701
- // Only parse literal URIs when resolveLanguage is explicitly set to 'literal'.
1702
- // Without this check, properties pointing to baseExpressions of other models
1703
- // (which may be literal:// strings) would get unwrapped, breaking link URI validation.
1704
- try {
1705
- const parsed = Literal.fromUrl(target).get();
1706
- if(parsed.data !== undefined) {
1707
- convertedValue = parsed.data;
1708
- } else {
1709
- convertedValue = parsed;
1710
- }
1711
- } catch (e) {
1712
- // If literal parsing fails, just use the value as-is (don't bail)
1713
- convertedValue = target;
1714
- }
1715
- } else if (typeof target === 'string') {
1716
- // Type conversion: check the instance property's current type
1717
- const expectedType = typeof instance[propName];
1718
- if (expectedType === 'number') {
1719
- convertedValue = Number(target);
1720
- } else if (expectedType === 'boolean') {
1721
- convertedValue = target === 'true' || target === '1';
1722
- }
1723
- }
1724
- }
1725
-
1726
- // Apply transform function if it exists
1727
- if (propMeta.transform && typeof propMeta.transform === 'function') {
1728
- convertedValue = propMeta.transform(convertedValue);
1729
- }
1730
-
1731
- instance[propName] = convertedValue;
1732
- }
1733
- foundProperty = true;
1734
- break;
2370
+ for (const relName of Object.keys(metadata.relations)) {
2371
+ if (!requested.has(relName) && !(query.include && relName in query.include)) {
2372
+ delete instance[relName];
1735
2373
  }
1736
2374
  }
1737
-
1738
- // If not a property, check if it's a collection (skip those with getter)
1739
- if (!foundProperty) {
1740
- for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1741
- if (collMeta.getter) continue; // Handle via getter evaluation
1742
- if (collMeta.predicate === predicate) {
1743
- // For collections, accumulate all values with their timestamps and indices for sorting
1744
- if (!instance[collName]) {
1745
- instance[collName] = [];
1746
- }
1747
- // Initialize timestamp tracking array if not already done
1748
- const timestampsKey = `__${collName}_timestamps`;
1749
- const indicesKey = `__${collName}_indices`;
1750
- if (!instance[timestampsKey]) {
1751
- instance[timestampsKey] = [];
1752
- }
1753
- if (!instance[indicesKey]) {
1754
- instance[indicesKey] = [];
1755
- }
1756
- if (!instance[collName].includes(target)) {
1757
- instance[collName].push(target);
1758
- instance[timestampsKey].push(link.timestamp || '');
1759
- // Track original position in the links array for stable sorting
1760
- instance[indicesKey].push(linkIndex);
1761
- }
1762
- break;
1763
- }
2375
+ // Also strip metadata fields unless explicitly requested
2376
+ for (const metaField of ['author', 'createdAt', 'updatedAt'] as const) {
2377
+ if (!requested.has(metaField)) {
2378
+ delete instance[metaField];
1764
2379
  }
1765
2380
  }
1766
2381
  }
1767
-
1768
- // Set author and timestamps
1769
- if (originalAuthor) {
1770
- instance.author = originalAuthor;
1771
- }
1772
-
1773
- // Set createdAt from earliest timestamp
1774
- if (minTimestamp) {
1775
- if (typeof minTimestamp === 'string' && minTimestamp.includes('T')) {
1776
- instance.createdAt = new Date(minTimestamp).getTime();
1777
- } else if (typeof minTimestamp === 'string') {
1778
- const parsed = parseInt(minTimestamp, 10);
1779
- instance.createdAt = isNaN(parsed) ? minTimestamp : parsed;
1780
- } else {
1781
- instance.createdAt = minTimestamp;
1782
- }
1783
- }
1784
-
1785
- // Set updatedAt from most recent timestamp
1786
- if (maxTimestamp) {
1787
- if (typeof maxTimestamp === 'string' && maxTimestamp.includes('T')) {
1788
- instance.updatedAt = new Date(maxTimestamp).getTime();
1789
- } else if (typeof maxTimestamp === 'string') {
1790
- const parsed = parseInt(maxTimestamp, 10);
1791
- instance.updatedAt = isNaN(parsed) ? maxTimestamp : parsed;
1792
- } else {
1793
- instance.updatedAt = maxTimestamp;
1794
- }
1795
- }
1796
-
1797
- // Sort collections by timestamp to maintain insertion order
1798
- for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1799
- const timestampsKey = `__${collName}_timestamps`;
1800
- const indicesKey = `__${collName}_indices`;
1801
- if (instance[collName] && instance[timestampsKey]) {
1802
- // Create array of [value, timestamp, index] tuples
1803
- const pairs = instance[collName].map((value: any, index: number) => ({
1804
- value,
1805
- timestamp: instance[timestampsKey][index] || '',
1806
- originalIndex: instance[indicesKey]?.[index] ?? index
1807
- }));
1808
- // Sort by timestamp first, then by original index for stable sorting
1809
- pairs.sort((a, b) => {
1810
- const tsA = String(a.timestamp || '');
1811
- const tsB = String(b.timestamp || '');
1812
- const tsCompare = tsA.localeCompare(tsB);
1813
- if (tsCompare !== 0) return tsCompare;
1814
- // Use original index as tiebreaker for stable sorting
1815
- return a.originalIndex - b.originalIndex;
1816
- });
1817
- // Replace collection with sorted values, filtering out empty strings and None
1818
- instance[collName] = pairs
1819
- .map(p => p.value)
1820
- .filter((v: any) => v !== undefined && v !== null && v !== '' && v !== 'None');
1821
- // Clean up temporary arrays
1822
- delete instance[timestampsKey];
1823
- delete instance[indicesKey];
1824
- }
1825
- }
1826
-
1827
- // Filter by requested attributes if specified
1828
- if (requestedProperties.length > 0 || requestedCollections.length > 0) {
1829
- const requestedAttributes = [...requestedProperties, ...requestedCollections];
1830
- Object.keys(instance).forEach((key) => {
1831
- // Keep only requested attributes, plus always keep createdAt, updatedAt, author, and baseExpression
1832
- // Note: timestamp is a getter alias for createdAt, so we preserve createdAt instead
1833
- if (!requestedAttributes.includes(key) && key !== 'createdAt' && key !== 'updatedAt' && key !== 'author' && key !== 'baseExpression') {
1834
- delete instance[key];
1835
- }
1836
- });
1837
- }
1838
-
2382
+
1839
2383
  instances.push(instance);
1840
2384
  } catch (error) {
1841
2385
  console.error(`Failed to process SurrealDB instance ${base}:`, error);
1842
2386
  }
1843
2387
  }
1844
-
2388
+
2389
+ // Populate reverse relation fields (belongsToOne / belongsToMany) as string IDs.
2390
+ // These relations point FROM other nodes TO this instance, so they cannot be resolved
2391
+ // from the node's own outgoing links fetched above. We do a reverse-link lookup here
2392
+ // so that these fields are populated as IDs even without an explicit include.
2393
+ const allRelsMeta = getRelationsMetadata(this as any);
2394
+ const reverseRelEntries = Object.entries(allRelsMeta).filter(
2395
+ ([relName, meta]) =>
2396
+ (meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') &&
2397
+ (requestedProperties.length === 0 || requestedProperties.includes(relName))
2398
+ );
2399
+ if (reverseRelEntries.length > 0 && instances.length > 0) {
2400
+ await Promise.all(
2401
+ instances.map(async (inst) => {
2402
+ for (const [relName, relMeta] of reverseRelEntries) {
2403
+ const reverseLinks = await perspective.get(
2404
+ new LinkQuery({ predicate: relMeta.predicate, target: inst.id })
2405
+ );
2406
+ const sourceIds = reverseLinks
2407
+ .filter((l) => l.data.target === inst.id)
2408
+ .map((l) => l.data.source);
2409
+ if (relMeta.kind === 'belongsToOne') {
2410
+ (inst as any)[relName] = sourceIds.length > 0 ? sourceIds[sourceIds.length - 1] : null;
2411
+ } else {
2412
+ (inst as any)[relName] = sourceIds;
2413
+ }
2414
+ }
2415
+ })
2416
+ );
2417
+ }
2418
+
1845
2419
  // Evaluate custom getters for all instances (single pass)
1846
- // This populates collection values needed for where.isInstance filtering
1847
2420
  for (const instance of instances) {
1848
2421
  await this.evaluateCustomGettersForInstance(instance, perspective, metadata);
1849
2422
  }
1850
2423
 
1851
- // Filter collections by where.isInstance if specified
1852
- // Do this after initial evaluation so collection values exist for filtering
1853
- for (const instance of instances) {
1854
- for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1855
- if (collMeta.where?.isInstance && instance[collName]?.length > 0) {
1856
- try {
1857
- const targetClass = collMeta.where.isInstance;
1858
- const subjects = instance[collName];
1859
-
1860
- // Get the class metadata from SDNA to pass to batchCheckSubjectInstances
1861
- const targetClassName = typeof targetClass === 'string'
1862
- ? targetClass
1863
- : (targetClass as any).prototype?.className || targetClass.name;
1864
- const classMetadata = await perspective.getSubjectClassMetadataFromSDNA(targetClassName);
1865
-
1866
- if (!classMetadata) {
1867
- continue;
1868
- }
1869
-
1870
- // Check which subjects are instances of the target class
1871
- const validSubjects = await perspective.batchCheckSubjectInstances(subjects, classMetadata);
1872
-
1873
- // Update the collection with filtered instances
1874
- instance[collName] = validSubjects;
1875
- } catch (error) {
1876
- // On error, leave the collection unfiltered rather than breaking everything
1877
- }
1878
- }
1879
- }
1880
- }
1881
-
1882
2424
  // Filter by where conditions that couldn't be filtered in SQL
1883
2425
  // This includes:
1884
2426
  // - author/timestamp (computed from grouped links)
@@ -1925,30 +2467,34 @@ WHERE ${whereConditions.join(' AND ')}
1925
2467
  (query.limit !== undefined || query.offset !== undefined ? { timestamp: 'ASC' as 'ASC' } : null);
1926
2468
 
1927
2469
  if (effectiveOrder) {
1928
- const orderPropName = Object.keys(effectiveOrder)[0];
1929
- const orderDirection = Object.values(effectiveOrder)[0];
2470
+ const orderEntries = Object.entries(effectiveOrder);
1930
2471
 
1931
2472
  filteredInstances.sort((a: any, b: any) => {
1932
- let aVal = a[orderPropName];
1933
- let bVal = b[orderPropName];
1934
-
1935
- // Handle undefined values - push them to the end
1936
- if (aVal === undefined && bVal === undefined) return 0;
1937
- if (aVal === undefined) return orderDirection === 'ASC' ? 1 : -1;
1938
- if (bVal === undefined) return orderDirection === 'ASC' ? -1 : 1;
1939
-
1940
- // Compare values
1941
- let comparison = 0;
1942
- if (typeof aVal === 'number' && typeof bVal === 'number') {
1943
- comparison = aVal - bVal;
1944
- } else if (typeof aVal === 'string' && typeof bVal === 'string') {
1945
- comparison = aVal.localeCompare(bVal);
1946
- } else {
1947
- // Convert to strings for comparison
1948
- comparison = String(aVal).localeCompare(String(bVal));
1949
- }
2473
+ for (const [orderPropName, orderDirection] of orderEntries) {
2474
+ let aVal = a[orderPropName];
2475
+ let bVal = b[orderPropName];
2476
+
2477
+ // Handle undefined values - push them to the end
2478
+ if (aVal === undefined && bVal === undefined) continue;
2479
+ if (aVal === undefined) return orderDirection === 'ASC' ? 1 : -1;
2480
+ if (bVal === undefined) return orderDirection === 'ASC' ? -1 : 1;
2481
+
2482
+ // Compare values
2483
+ let comparison = 0;
2484
+ if (typeof aVal === 'number' && typeof bVal === 'number') {
2485
+ comparison = aVal - bVal;
2486
+ } else if (typeof aVal === 'string' && typeof bVal === 'string') {
2487
+ comparison = aVal.localeCompare(bVal);
2488
+ } else {
2489
+ comparison = String(aVal).localeCompare(String(bVal));
2490
+ }
1950
2491
 
1951
- return orderDirection === 'DESC' ? -comparison : comparison;
2492
+ if (comparison !== 0) {
2493
+ return orderDirection === 'DESC' ? -comparison : comparison;
2494
+ }
2495
+ // comparison === 0: continue to next sort field
2496
+ }
2497
+ return 0;
1952
2498
  });
1953
2499
  }
1954
2500
 
@@ -1963,6 +2509,22 @@ WHERE ${whereConditions.join(' AND ')}
1963
2509
  paginatedInstances = filteredInstances.slice(start, end);
1964
2510
  }
1965
2511
 
2512
+ // Eager-load relations if requested (BEFORE snapshot so dirty tracking is accurate)
2513
+ if (query.include && paginatedInstances.length > 0) {
2514
+ await this.hydrateRelations(paginatedInstances, perspective, query.include);
2515
+ }
2516
+
2517
+ // Take snapshots for dirty tracking after ALL hydration is complete
2518
+ // (including eager-loaded relations).
2519
+ // When `include` is specified, only snapshot those relations.
2520
+ // Otherwise snapshot ALL fields (properties + relations) since
2521
+ // hydrateFromLinks populates relations with stable raw IDs —
2522
+ // this ensures push-to-array + save() correctly detects dirty relations.
2523
+ const snapshotRelations = query.include;
2524
+ for (const inst of paginatedInstances) {
2525
+ (inst as Ad4mModel).takeSnapshot(snapshotRelations);
2526
+ }
2527
+
1966
2528
  return {
1967
2529
  results: paginatedInstances,
1968
2530
  totalCount
@@ -2067,6 +2629,9 @@ WHERE ${whereConditions.join(' AND ')}
2067
2629
  query: Query = {},
2068
2630
  useSurrealDB: boolean = true
2069
2631
  ): Promise<T[]> {
2632
+ if (query.properties && query.properties.length === 0) {
2633
+ throw new Error("properties[] must not be empty — omit the field to return all properties, or specify at least one field name");
2634
+ }
2070
2635
  if (useSurrealDB) {
2071
2636
  const surrealQuery = await this.queryToSurrealQL(perspective, query);
2072
2637
  const result = await perspective.querySurrealDB(surrealQuery);
@@ -2080,6 +2645,37 @@ WHERE ${whereConditions.join(' AND ')}
2080
2645
  }
2081
2646
  }
2082
2647
 
2648
+ /**
2649
+ * Finds the first instance matching the query, or `null` if none exists.
2650
+ *
2651
+ * Equivalent to `findAll` with `limit: 1` — only one instance is hydrated.
2652
+ *
2653
+ * @param perspective - The perspective to search in
2654
+ * @param query - Optional query parameters to filter results
2655
+ * @param useSurrealDB - Whether to use SurrealDB (default: true) or Prolog (legacy)
2656
+ * @returns The first matching instance, or `null`
2657
+ *
2658
+ * @example
2659
+ * ```typescript
2660
+ * const recipe = await Recipe.findOne(perspective, {
2661
+ * where: { name: "Pasta" }
2662
+ * });
2663
+ * if (recipe) {
2664
+ * console.log(recipe.name);
2665
+ * }
2666
+ * ```
2667
+ */
2668
+ static async findOne<T extends Ad4mModel>(
2669
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
2670
+ perspective: PerspectiveProxy,
2671
+ query: Query = {},
2672
+ useSurrealDB: boolean = true,
2673
+ ): Promise<T | null> {
2674
+ const limitedQuery = { ...query, limit: 1 };
2675
+ const results = await this.findAll(perspective, limitedQuery, useSurrealDB);
2676
+ return results[0] ?? null;
2677
+ }
2678
+
2083
2679
  /**
2084
2680
  * Gets all instances with count of total matches without offset & limit applied.
2085
2681
  *
@@ -2161,9 +2757,12 @@ WHERE ${whereConditions.join(' AND ')}
2161
2757
  }
2162
2758
 
2163
2759
  static async countQueryToProlog(perspective: PerspectiveProxy, query: Query = {}, modelClassName?: string | null) {
2164
- const { source, where } = query;
2760
+ const { where } = query;
2165
2761
  const className = modelClassName || (await this.getClassName(perspective));
2166
- const instanceQueries = [buildAuthorAndTimestampQuery(), buildSourceQuery(source), buildWhereQuery(where)];
2762
+ const resolvedParentPredicate = query.parent
2763
+ ? resolveParentPredicate(query.parent, this)
2764
+ : undefined;
2765
+ const instanceQueries = [buildAuthorAndTimestampQuery(), buildParentQuery(query.parent, resolvedParentPredicate), buildWhereQuery(where)];
2167
2766
  const resultSetQueries = [buildCountQuery(true), buildOrderQuery(), buildOffsetQuery(), buildLimitQuery()];
2168
2767
 
2169
2768
  const fullQuery = `
@@ -2250,109 +2849,135 @@ WHERE ${whereConditions.join(' AND ')}
2250
2849
  }
2251
2850
 
2252
2851
  if (resolveLanguage) {
2253
- value = await this.#perspective.createExpression(value, resolveLanguage);
2852
+ value = await this._perspective.createExpression(value, resolveLanguage);
2254
2853
  }
2255
2854
 
2256
- await this.#perspective.executeAction(actions, this.#baseExpression, [{ name: "value", value }], batchId);
2855
+ await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value }], batchId);
2856
+ }
2857
+
2858
+ /** Resolve a relation argument to a plain string ID. Accepts either a raw
2859
+ * string ID or an Ad4mModel instance (in which case `.id` is used). */
2860
+ private resolveRelationId(value: any): string {
2861
+ if (typeof value === 'string') return value;
2862
+ if (value && typeof value === 'object' && typeof value.id === 'string') return value.id;
2863
+ return String(value);
2257
2864
  }
2258
2865
 
2259
- private async setCollectionSetter(key: string, value: any, batchId?: string) {
2866
+ private async setRelationValues(key: string, value: any, batchId?: string) {
2260
2867
  // Phase 1: Use metadata instead of Prolog queries
2261
- const metadata = this.getCollectionMetadata(key);
2868
+ const metadata = this.getRelationOptions(key);
2262
2869
  if (!metadata) {
2263
- console.warn(`Collection "${key}" has no metadata, skipping`);
2870
+ console.warn(`Relation "${key}" has no metadata, skipping`);
2264
2871
  return;
2265
2872
  }
2266
2873
 
2267
2874
  // Generate actions from metadata (replaces Prolog query)
2268
- const actions = this.generateCollectionAction(key, 'setter');
2875
+ const actions = this.generateRelationAction(key, 'setter');
2269
2876
 
2270
2877
  if (value != null) {
2271
2878
  if (Array.isArray(value)) {
2272
- await this.#perspective.executeAction(
2879
+ await this._perspective.executeAction(
2273
2880
  actions,
2274
- this.#baseExpression,
2275
- value.map((v) => ({ name: "value", value: v })),
2881
+ this._baseExpression,
2882
+ value.map((v) => ({ name: "value", value: this.resolveRelationId(v) })),
2276
2883
  batchId
2277
2884
  );
2278
2885
  } else {
2279
- await this.#perspective.executeAction(actions, this.#baseExpression, [{ name: "value", value }], batchId);
2886
+ await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(value) }], batchId);
2280
2887
  }
2281
2888
  }
2282
2889
  }
2283
2890
 
2284
- private async setCollectionAdder(key: string, value: any, batchId?: string) {
2891
+ private async addRelationValue(key: string, value: any, batchId?: string) {
2285
2892
  // Phase 1: Use metadata instead of Prolog queries
2286
- const metadata = this.getCollectionMetadata(key);
2893
+ const metadata = this.getRelationOptions(key);
2287
2894
  if (!metadata) {
2288
- console.warn(`Collection "${key}" has no metadata, skipping`);
2895
+ console.warn(`Relation "${key}" has no metadata, skipping`);
2289
2896
  return;
2290
2897
  }
2291
2898
 
2292
2899
  // Generate actions from metadata (replaces Prolog query)
2293
- const actions = this.generateCollectionAction(key, 'adder');
2900
+ const actions = this.generateRelationAction(key, 'adder');
2294
2901
 
2295
2902
  if (value != null) {
2296
2903
  if (Array.isArray(value)) {
2297
2904
  await Promise.all(
2298
2905
  value.map((v) =>
2299
- this.#perspective.executeAction(actions, this.#baseExpression, [{ name: "value", value: v }], batchId)
2906
+ this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(v) }], batchId)
2300
2907
  )
2301
2908
  );
2302
2909
  } else {
2303
- await this.#perspective.executeAction(actions, this.#baseExpression, [{ name: "value", value }], batchId);
2910
+ await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(value) }], batchId);
2304
2911
  }
2305
2912
  }
2306
2913
  }
2307
2914
 
2308
- private async setCollectionRemover(key: string, value: any, batchId?: string) {
2915
+ private async removeRelationValue(key: string, value: any, batchId?: string) {
2309
2916
  // Phase 1: Use metadata instead of Prolog queries
2310
- const metadata = this.getCollectionMetadata(key);
2917
+ const metadata = this.getRelationOptions(key);
2311
2918
  if (!metadata) {
2312
- console.warn(`Collection "${key}" has no metadata, skipping`);
2919
+ console.warn(`Relation "${key}" has no metadata, skipping`);
2313
2920
  return;
2314
2921
  }
2315
2922
 
2316
2923
  // Generate actions from metadata (replaces Prolog query)
2317
- const actions = this.generateCollectionAction(key, 'remover');
2924
+ const actions = this.generateRelationAction(key, 'remover');
2318
2925
 
2319
2926
  if (value != null) {
2320
2927
  if (Array.isArray(value)) {
2321
2928
  await Promise.all(
2322
2929
  value.map((v) =>
2323
- this.#perspective.executeAction(actions, this.#baseExpression, [{ name: "value", value: v }], batchId)
2930
+ this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(v) }], batchId)
2324
2931
  )
2325
2932
  );
2326
2933
  } else {
2327
- await this.#perspective.executeAction(actions, this.#baseExpression, [{ name: "value", value }], batchId);
2934
+ await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(value) }], batchId);
2328
2935
  }
2329
2936
  }
2330
2937
  }
2331
2938
 
2332
2939
  /**
2333
2940
  * Saves the model instance to the perspective.
2334
- * Creates a new instance with the base expression and links it to the source.
2941
+ *
2942
+ * **New instances** (no snapshot yet): creates the subject via
2943
+ * `createSubject` with initial scalar values, then sets relations
2944
+ * via `innerUpdate`.
2945
+ *
2946
+ * **Existing instances** (snapshot present, i.e. fetched via `get()`
2947
+ * or a query): updates only dirty fields via `innerUpdate`, then
2948
+ * refreshes from the perspective.
2335
2949
  *
2336
2950
  * @param batchId - Optional batch ID for batch operations
2337
2951
  * @throws Will throw if instance creation, linking, or updating fails
2338
2952
  *
2339
2953
  * @example
2340
2954
  * ```typescript
2955
+ * // Create
2341
2956
  * const recipe = new Recipe(perspective);
2342
2957
  * recipe.name = "Spaghetti";
2343
- * recipe.ingredients = ["pasta", "tomato sauce"];
2344
2958
  * await recipe.save();
2345
2959
  *
2346
- * // Or with batch operations:
2347
- * const batchId = await perspective.createBatch();
2348
- * await recipe.save(batchId);
2349
- * await perspective.commitBatch(batchId);
2960
+ * // Update
2961
+ * recipe.rating = 10;
2962
+ * await recipe.save();
2350
2963
  * ```
2351
2964
  */
2352
2965
  async save(batchId?: string) {
2353
- // We use createSubject's initialValues to set properties (but not collections)
2354
- // We then later use innerUpdate to set collections
2966
+ // Existing instance → update path (has been fetched / hydrated before)
2967
+ if (this._snapshot) {
2968
+ await this.innerUpdate(true, batchId);
2969
+ if (batchId) {
2970
+ // Batch hasn't been committed yet — getData() would fetch stale data
2971
+ // and overwrite in-memory values. Just refresh the snapshot so further
2972
+ // saves within the same batch diff correctly.
2973
+ this.takeSnapshot();
2974
+ } else {
2975
+ await this.getData();
2976
+ }
2977
+ return;
2978
+ }
2355
2979
 
2980
+ // New instance → create path
2356
2981
  let batchCreatedHere = false;
2357
2982
  if(!batchId) {
2358
2983
  batchId = await this.perspective.createBatch()
@@ -2360,48 +2985,72 @@ WHERE ${whereConditions.join(' AND ')}
2360
2985
  }
2361
2986
 
2362
2987
 
2363
- // First filter out the properties that are not collections (arrays)
2364
- const initialValues = {};
2365
- for (const [key, value] of Object.entries(this)) {
2366
- if (value !== undefined && value !== null && !(Array.isArray(value) && value.length > 0) && !value?.action) {
2367
- initialValues[key] = value;
2368
- }
2369
- }
2988
+ // Check if the model has any constructor actions (required properties,
2989
+ // flags, or properties with initial values). Models whose properties are
2990
+ // all optional, have no @Flag, and have no initial values produce an empty
2991
+ // SHACL constructor, so calling createSubject would fail on the Rust side
2992
+ // ("No SHACL constructor found"). In that case we skip createSubject
2993
+ // entirely and let innerUpdate write the links directly.
2994
+ const metadata = (this.constructor as typeof Ad4mModel).getModelMetadata();
2995
+ const hasConstructor = Object.values(metadata.properties).some(
2996
+ (p) => p.required || p.flag || p.initial !== undefined
2997
+ );
2370
2998
 
2371
- // Get the class name instead of passing the instance to avoid Prolog query generation
2372
- const className = await this.perspective.stringOrTemplateObjectToSubjectClassName(this);
2999
+ if (hasConstructor) {
3000
+ // First filter out the properties that are not relations (arrays)
3001
+ const initialValues = {};
3002
+ for (const [key, value] of Object.entries(this)) {
3003
+ if (value !== undefined && value !== null && !(Array.isArray(value) && value.length > 0) && !value?.action) {
3004
+ initialValues[key] = value;
3005
+ }
3006
+ }
2373
3007
 
2374
- // Create the subject with the initial values
2375
- await this.perspective.createSubject(
2376
- className,
2377
- this.#baseExpression,
2378
- initialValues,
2379
- batchId
2380
- );
3008
+ // Get the class name instead of passing the instance to avoid Prolog query generation
3009
+ const className = await this.perspective.stringOrTemplateObjectToSubjectClassName(this);
2381
3010
 
2382
- // Link the subject to the source
2383
- await this.#perspective.add(
2384
- new Link({ source: this.#source, predicate: "ad4m://has_child", target: this.baseExpression }),
2385
- 'shared',
2386
- batchId
2387
- );
3011
+ // Create the subject with the initial values
3012
+ await this.perspective.createSubject(
3013
+ className,
3014
+ this._baseExpression,
3015
+ initialValues,
3016
+ batchId
3017
+ );
3018
+ }
2388
3019
 
2389
- // Set collections
2390
- await this.innerUpdate(false, batchId)
3020
+ // Set properties and relations via innerUpdate.
3021
+ // When createSubject was skipped (no constructor actions), we must enable
3022
+ // property writing so that scalar values are persisted as links.
3023
+ await this.innerUpdate(!hasConstructor, batchId)
2391
3024
 
2392
3025
  // If we got a batchId passed in, we let the caller decide when to commit.
2393
- // But then we can call getData() since the instance won't exist in the perspective
2394
- // until the bacht is committedl
3026
+ // We can't call getData() since the instance won't exist in the perspective
3027
+ // until the batch is committed.
2395
3028
  if (batchCreatedHere) {
2396
3029
  await this.perspective.commitBatch(batchId)
2397
3030
  await this.getData();
3031
+ } else {
3032
+ // Take a snapshot so that a subsequent save() within the same batch
3033
+ // routes through the UPDATE path instead of CREATE, avoiding duplicate
3034
+ // links (e.g. two competing "title" values).
3035
+ this.takeSnapshot();
2398
3036
  }
2399
3037
  }
2400
3038
 
2401
3039
  private cleanCopy() {
2402
- const cleanCopy = {};
2403
- const props = Object.entries(this);
2404
- for (const [key, value] of props) {
3040
+ const ctor = this.constructor as typeof Ad4mModel;
3041
+ const metadata = ctor.getModelMetadata();
3042
+ const cleanCopy: Record<string, any> = {};
3043
+
3044
+ // Only include schema-declared fields (properties + relations),
3045
+ // preserving internal ORM machinery (_id, _perspective, generated
3046
+ // addX/removeX/setX methods, _snapshot, etc.)
3047
+ const schemaFields = new Set([
3048
+ ...Object.keys(metadata.properties),
3049
+ ...Object.keys(metadata.relations),
3050
+ ]);
3051
+
3052
+ for (const key of schemaFields) {
3053
+ const value = (this as any)[key];
2405
3054
  if (value !== undefined && value !== null && key !== "author" && key !== "timestamp") {
2406
3055
  cleanCopy[key] = value;
2407
3056
  }
@@ -2410,37 +3059,60 @@ WHERE ${whereConditions.join(' AND ')}
2410
3059
  }
2411
3060
 
2412
3061
  private async innerUpdate(setProperties: boolean = true, batchId?: string) {
2413
- this.#subjectClassName = await this.#perspective.stringOrTemplateObjectToSubjectClassName(this.cleanCopy());
3062
+ const ctor = this.constructor as typeof Ad4mModel;
3063
+ this._subjectClassName = await this._perspective.stringOrTemplateObjectToSubjectClassName(this.cleanCopy());
3064
+
3065
+ // Determine which fields actually changed (skip unchanged when snapshot exists)
3066
+ const dirty = this._snapshot ? new Set(this.changedFields()) : null;
3067
+
3068
+ // Only iterate schema-declared fields, not internal ORM properties
3069
+ const metadata = ctor.getModelMetadata();
3070
+ const schemaFields = new Set([
3071
+ ...Object.keys(metadata.properties),
3072
+ ...Object.keys(metadata.relations),
3073
+ ]);
2414
3074
 
2415
3075
  const entries = Object.entries(this);
2416
3076
  for (const [key, value] of entries) {
3077
+ // Only process schema-declared fields
3078
+ if (!schemaFields.has(key)) continue;
3079
+ // Skip unchanged fields when a snapshot is available
3080
+ if (dirty && !dirty.has(key)) continue;
3081
+
2417
3082
  if (value !== undefined && value !== null) {
2418
3083
  if (value?.action) {
2419
3084
  switch (value.action) {
2420
3085
  case "setter":
2421
- await this.setCollectionSetter(key, value.value, batchId);
3086
+ await this.setRelationValues(key, value.value, batchId);
2422
3087
  break;
2423
3088
  case "adder":
2424
- await this.setCollectionAdder(key, value.value, batchId);
3089
+ await this.addRelationValue(key, value.value, batchId);
2425
3090
  break;
2426
3091
  case "remover":
2427
- await this.setCollectionRemover(key, value.value, batchId);
3092
+ await this.removeRelationValue(key, value.value, batchId);
2428
3093
  break;
2429
3094
  default:
2430
- await this.setCollectionSetter(key, value.value, batchId);
3095
+ await this.setRelationValues(key, value.value, batchId);
2431
3096
  break;
2432
3097
  }
2433
3098
  } else if (Array.isArray(value)) {
2434
- // Handle all arrays as collections, including empty ones (which clears the collection)
2435
- await this.setCollectionSetter(key, value, batchId);
3099
+ // Handle all arrays as relations, including empty ones (which clears the relation)
3100
+ await this.setRelationValues(key, value, batchId);
2436
3101
  } else if (value !== undefined && value !== null && value !== "") {
2437
3102
  if (setProperties) {
2438
- // Check if this is a collection property (has collection metadata)
2439
- const collMetadata = this.getCollectionMetadata(key);
2440
- if (collMetadata) {
2441
- // Skip - it's a collection, not a regular property
3103
+ // Check if this is a relation property (has relation metadata)
3104
+ const relationMeta = this.getRelationOptions(key);
3105
+ if (relationMeta) {
3106
+ // Skip - it's a relation, not a regular property
2442
3107
  continue;
2443
3108
  }
3109
+
3110
+ // Skip flag properties — they are immutable after creation
3111
+ const propMeta = this.getPropertyMetadata(key);
3112
+ if (propMeta?.flag) {
3113
+ continue;
3114
+ }
3115
+
2444
3116
  await this.setProperty(key, value, batchId);
2445
3117
  }
2446
3118
  }
@@ -2449,46 +3121,42 @@ WHERE ${whereConditions.join(' AND ')}
2449
3121
  }
2450
3122
 
2451
3123
  /**
2452
- * Updates the model instance's properties and collections.
2453
- *
2454
- * @param batchId - Optional batch ID for batch operations
2455
- * @throws Will throw if property setting or collection updates fail
2456
- *
2457
- * @example
2458
- * ```typescript
2459
- * const recipe = await Recipe.findAll(perspective)[0];
2460
- * recipe.rating = 5;
2461
- * recipe.ingredients.push("garlic");
2462
- * await recipe.update();
2463
- *
2464
- * // Or with batch operations:
2465
- * const batchId = await perspective.createBatch();
2466
- * await recipe.update(batchId);
2467
- * await perspective.commitBatch(batchId);
2468
- * ```
2469
- */
2470
- async update(batchId?: string) {
2471
- await this.innerUpdate(true, batchId);
2472
- await this.getData();
2473
- }
2474
-
2475
- /**
2476
- * Gets the model instance with all properties and collections populated.
2477
- *
3124
+ * Gets the model instance with all properties and relations populated.
3125
+ *
3126
+ * @param optsOrInclude - Optional hydration options. Accepts two forms:
3127
+ * - `GetOptions` wrapper: `{ include: { comments: true }, properties: ['title'] }`
3128
+ * - `IncludeMap` shorthand: `{ comments: true }` (equivalent to `{ include: { comments: true } }`)
2478
3129
  * @returns The populated model instance
2479
3130
  * @throws Will throw if data retrieval fails
2480
- *
3131
+ *
2481
3132
  * @example
2482
3133
  * ```typescript
2483
3134
  * const recipe = new Recipe(perspective, existingId);
2484
3135
  * await recipe.get();
2485
3136
  * console.log(recipe.name, recipe.ingredients);
3137
+ *
3138
+ * // Shorthand — pass IncludeMap directly:
3139
+ * await recipe.get({ ingredients: true });
3140
+ *
3141
+ * // Full options — includes sparse fieldset:
3142
+ * await recipe.get({ include: { ingredients: true }, properties: ['name'] });
2486
3143
  * ```
2487
3144
  */
2488
- async get() {
2489
- this.#subjectClassName = await this.#perspective.stringOrTemplateObjectToSubjectClassName(this.cleanCopy());
3145
+ async get(optsOrInclude?: GetOptions | IncludeMap) {
3146
+ // Normalise: if the caller passed a plain IncludeMap shorthand (no `include`
3147
+ // or `properties` key at the top level) wrap it in GetOptions automatically.
3148
+ let opts: GetOptions | undefined;
3149
+ if (!optsOrInclude) {
3150
+ opts = undefined;
3151
+ } else if ('include' in optsOrInclude || 'properties' in optsOrInclude) {
3152
+ opts = optsOrInclude as GetOptions;
3153
+ } else {
3154
+ opts = { include: optsOrInclude as IncludeMap };
3155
+ }
3156
+
3157
+ this._subjectClassName = await this._perspective.stringOrTemplateObjectToSubjectClassName(this.cleanCopy());
2490
3158
 
2491
- return await this.getData();
3159
+ return await this.getData(opts);
2492
3160
  }
2493
3161
 
2494
3162
  /**
@@ -2509,7 +3177,262 @@ WHERE ${whereConditions.join(' AND ')}
2509
3177
  * ```
2510
3178
  */
2511
3179
  async delete(batchId?: string) {
2512
- await this.#perspective.removeSubject(this, this.#baseExpression, batchId);
3180
+ // Check if the model has a destructor (required properties, flags, or
3181
+ // properties with initial values). Models whose properties are all
3182
+ // optional, have no @Flag, and have no initial values produce an empty
3183
+ // SHACL destructor, so calling removeSubject would fail. In that case
3184
+ // we skip the destructor and just remove all outgoing links directly.
3185
+ const metadata = (this.constructor as typeof Ad4mModel).getModelMetadata();
3186
+ const hasDestructor = Object.values(metadata.properties).some(
3187
+ (p) => p.required || p.flag || p.initial !== undefined
3188
+ );
3189
+
3190
+ if (hasDestructor) {
3191
+ // Remove the subject itself (destructor actions)
3192
+ await this._perspective.removeSubject(this, this._baseExpression, batchId);
3193
+ } else {
3194
+ // No destructor — manually remove all outgoing links from this node
3195
+ try {
3196
+ const outgoingLinks = await this._perspective.get(new LinkQuery({ source: this._baseExpression }));
3197
+ if (outgoingLinks.length > 0) {
3198
+ await this._perspective.removeLinks(outgoingLinks, batchId);
3199
+ }
3200
+ } catch (e) {
3201
+ console.warn(`delete(): failed to remove outgoing links for ${this._baseExpression}:`, e);
3202
+ }
3203
+ }
3204
+
3205
+ // Clean up incoming links — remove any links that point **to** this instance
3206
+ try {
3207
+ const incomingLinks = await this._perspective.get(new LinkQuery({ target: this._baseExpression }));
3208
+ if (incomingLinks.length > 0) {
3209
+ await this._perspective.removeLinks(incomingLinks, batchId);
3210
+ }
3211
+ } catch (e) {
3212
+ // Non-fatal: the subject was already deleted; incoming link cleanup is best-effort
3213
+ console.warn(`delete(): failed to clean up incoming links for ${this._baseExpression}:`, e);
3214
+ }
3215
+ }
3216
+
3217
+ // ──────────────────────────────────────────────────────────
3218
+ // Static convenience methods
3219
+ // ──────────────────────────────────────────────────────────
3220
+
3221
+ /**
3222
+ * Options for `Ad4mModel.create()`.
3223
+ */
3224
+ static readonly CreateOptions: undefined; // type-only anchor for JSDoc
3225
+
3226
+ /**
3227
+ * Creates and saves a new model instance in one step.
3228
+ *
3229
+ * @param perspective - The perspective to create the instance in
3230
+ * @param data - Property values to assign before saving
3231
+ * @param options - Optional settings:
3232
+ * - `parent` — a `ParentScope` (model form or raw form) whose `id` will
3233
+ * be used to create an incoming link from the parent to the new instance.
3234
+ * - `batchId` — an existing batch id; when provided the link write and
3235
+ * `save()` are added to the batch instead of committed immediately.
3236
+ * @returns The saved model instance
3237
+ *
3238
+ * @example
3239
+ * ```typescript
3240
+ * // Simple create
3241
+ * const recipe = await Recipe.create(perspective, {
3242
+ * name: "Spaghetti",
3243
+ * rating: 5,
3244
+ * });
3245
+ *
3246
+ * // Create under a parent (link auto-created)
3247
+ * const comment = await Comment.create(perspective, { text: "Great!" }, {
3248
+ * parent: { model: Post, id: postId },
3249
+ * });
3250
+ *
3251
+ * // Create inside a transaction
3252
+ * await Ad4mModel.transaction(perspective, async (tx) => {
3253
+ * await Recipe.create(perspective, { name: "Pasta" }, { batchId: tx.batchId });
3254
+ * });
3255
+ * ```
3256
+ */
3257
+ static async create<T extends Ad4mModel>(
3258
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
3259
+ perspective: PerspectiveProxy,
3260
+ data: Record<string, any> = {},
3261
+ options?: { parent?: ParentScope; batchId?: string },
3262
+ ): Promise<T> {
3263
+ const instance = new this(perspective) as T;
3264
+ Object.assign(instance, data);
3265
+
3266
+ // When a parent scope is provided without a caller-supplied batch, open a
3267
+ // new batch ourselves so that the instance creation and the parent→child
3268
+ // link are committed atomically. If either step throws, commitBatch is
3269
+ // never reached and the batch is implicitly abandoned (rollback).
3270
+ if (options?.parent && !options?.batchId) {
3271
+ const batchId = await perspective.createBatch();
3272
+ await instance.save(batchId);
3273
+ const predicate = resolveParentPredicate(options.parent, this);
3274
+ const link = new Link({
3275
+ source: options.parent.id,
3276
+ predicate,
3277
+ target: instance.id,
3278
+ });
3279
+ await perspective.add(link, 'shared', batchId);
3280
+ await perspective.commitBatch(batchId);
3281
+ // Hydrate the instance now that the batch has been committed (mirrors the
3282
+ // behaviour of save() when it manages its own batch).
3283
+ await instance.get();
3284
+ return instance;
3285
+ }
3286
+
3287
+ await instance.save(options?.batchId);
3288
+
3289
+ // Create parent → child link if a parent scope was provided
3290
+ if (options?.parent) {
3291
+ const predicate = resolveParentPredicate(options.parent, this);
3292
+ const link = new Link({
3293
+ source: options.parent.id,
3294
+ predicate,
3295
+ target: instance.id,
3296
+ });
3297
+ await perspective.add(link, 'shared', options?.batchId);
3298
+ }
3299
+
3300
+ return instance;
3301
+ }
3302
+
3303
+ /**
3304
+ * Updates an existing model instance identified by `id`.
3305
+ *
3306
+ * Fetches the instance, applies the provided changes, calls `save()`,
3307
+ * and returns the refreshed instance.
3308
+ *
3309
+ * @param perspective - The perspective containing the instance
3310
+ * @param id - The expression URI of the instance to update
3311
+ * @param data - Property values to merge before saving
3312
+ * @returns The updated model instance
3313
+ *
3314
+ * @example
3315
+ * ```typescript
3316
+ * const recipe = await Recipe.update(perspective, recipeId, {
3317
+ * rating: 10,
3318
+ * });
3319
+ * ```
3320
+ */
3321
+ static async update<T extends Ad4mModel>(
3322
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
3323
+ perspective: PerspectiveProxy,
3324
+ id: string,
3325
+ data: Record<string, any>,
3326
+ ): Promise<T> {
3327
+ const instance = new this(perspective, id) as T;
3328
+ await instance.get();
3329
+ Object.assign(instance, data);
3330
+ await instance.save();
3331
+ return instance;
3332
+ }
3333
+
3334
+ /**
3335
+ * Deletes an existing model instance identified by `id`.
3336
+ *
3337
+ * Also cleans up any incoming links that point to this instance.
3338
+ *
3339
+ * @param perspective - The perspective containing the instance
3340
+ * @param id - The expression URI of the instance to delete
3341
+ *
3342
+ * @example
3343
+ * ```typescript
3344
+ * await Recipe.delete(perspective, recipeId);
3345
+ * ```
3346
+ *
3347
+ * @deprecated Use the name `delete` — `remove` is preserved as an alias.
3348
+ */
3349
+ static async remove(
3350
+ this: typeof Ad4mModel & (new (...args: any[]) => Ad4mModel),
3351
+ perspective: PerspectiveProxy,
3352
+ id: string,
3353
+ ): Promise<void> {
3354
+ return this.delete(perspective, id);
3355
+ }
3356
+
3357
+ /**
3358
+ * Deletes an existing model instance identified by `id`.
3359
+ *
3360
+ * Also cleans up any incoming links that point to this instance.
3361
+ *
3362
+ * @param perspective - The perspective containing the instance
3363
+ * @param id - The expression URI of the instance to delete
3364
+ *
3365
+ * @example
3366
+ * ```typescript
3367
+ * await Recipe.delete(perspective, recipeId);
3368
+ * ```
3369
+ */
3370
+ static async delete(
3371
+ this: typeof Ad4mModel & (new (...args: any[]) => Ad4mModel),
3372
+ perspective: PerspectiveProxy,
3373
+ id: string,
3374
+ ): Promise<void> {
3375
+ const instance = new this(perspective, id);
3376
+ await instance.delete();
3377
+ }
3378
+
3379
+ /**
3380
+ * Registers this model's SHACL schema on the given perspective.
3381
+ *
3382
+ * This ensures the perspective knows about the model's shape
3383
+ * (properties, relations, constraints) so instances can be
3384
+ * created, queried, and validated.
3385
+ *
3386
+ * @param perspective - The perspective to register the model on
3387
+ *
3388
+ * @example
3389
+ * ```typescript
3390
+ * await Recipe.register(perspective);
3391
+ * // Now you can create / query Recipe instances on this perspective
3392
+ * ```
3393
+ */
3394
+ static async register(
3395
+ this: typeof Ad4mModel,
3396
+ perspective: PerspectiveProxy,
3397
+ ): Promise<void> {
3398
+ await perspective.ensureSDNASubjectClass(this);
3399
+ }
3400
+
3401
+ /**
3402
+ * Executes a set of model operations inside a single batch (transaction).
3403
+ *
3404
+ * All `save`, `update`, and `delete` calls made via the provided `batchId`
3405
+ * are buffered and flushed atomically when the callback completes.
3406
+ * If the callback throws, the batch is **not** committed, preventing
3407
+ * partial writes.
3408
+ *
3409
+ * @param perspective - The perspective to operate on
3410
+ * @param fn - Async callback that receives a `TransactionContext` object.
3411
+ * Pass `tx.batchId` to `save(tx.batchId)`, `update(tx.batchId)`,
3412
+ * `delete(tx.batchId)`, etc.
3413
+ * @returns The value returned by `fn`
3414
+ *
3415
+ * @example
3416
+ * ```typescript
3417
+ * await Ad4mModel.transaction(perspective, async (tx) => {
3418
+ * const recipe = new Recipe(perspective);
3419
+ * recipe.name = "Spaghetti";
3420
+ * await recipe.save(tx.batchId);
3421
+ *
3422
+ * const old = await Recipe.query(perspective).where({ name: "Stale" }).run();
3423
+ * for (const r of old) await r.delete(tx.batchId);
3424
+ * });
3425
+ * // All changes committed atomically here
3426
+ * ```
3427
+ */
3428
+ static async transaction<R = void>(
3429
+ perspective: PerspectiveProxy,
3430
+ fn: (tx: { batchId: string }) => Promise<R>,
3431
+ ): Promise<R> {
3432
+ const batchId = await perspective.createBatch();
3433
+ const result = await fn({ batchId });
3434
+ await perspective.commitBatch(batchId);
3435
+ return result;
2513
3436
  }
2514
3437
 
2515
3438
  /**
@@ -2615,9 +3538,9 @@ WHERE ${whereConditions.join(' AND ')}
2615
3538
  (DynamicModelClass as any).className = options.name;
2616
3539
  (DynamicModelClass.prototype as any).className = options.name;
2617
3540
 
2618
- // Generate properties and collections metadata
3541
+ // Generate properties and relations metadata
2619
3542
  const properties: any = {};
2620
- const collections: any = {};
3543
+ const relations: any = {};
2621
3544
 
2622
3545
  if (schema.properties) {
2623
3546
  for (const [propertyName, propertySchema] of Object.entries(schema.properties)) {
@@ -2627,9 +3550,9 @@ WHERE ${whereConditions.join(' AND ')}
2627
3550
  const isArray = isArrayType(propertySchema);
2628
3551
 
2629
3552
  if (isArray) {
2630
- // Handle arrays as collections
2631
- // Store the singular form as the collection key since SDNA generation expects singular
2632
- collections[propertyName] = {
3553
+ // Handle arrays as relations
3554
+ // Store the singular form as the relation key since SDNA generation expects singular
3555
+ relations[propertyName] = {
2633
3556
  through: predicate,
2634
3557
  local: this.getPropertyOption(propertyName, propertySchema, options, 'local')
2635
3558
  };
@@ -2641,10 +3564,10 @@ WHERE ${whereConditions.join(' AND ')}
2641
3564
  value: []
2642
3565
  });
2643
3566
 
2644
- // Add collection methods
3567
+ // Add relation methods
2645
3568
  const adderName = `add${capitalize(propertyName)}`;
2646
3569
  const removerName = `remove${capitalize(propertyName)}`;
2647
- const setterName = `setCollection${capitalize(propertyName)}`;
3570
+ const setterName = `set${capitalize(propertyName)}`;
2648
3571
 
2649
3572
  (DynamicModelClass.prototype as any)[adderName] = function() {
2650
3573
  // Placeholder function for SDNA generation
@@ -2664,7 +3587,13 @@ WHERE ${whereConditions.join(' AND ')}
2664
3587
  resolveLanguage = options.resolveLanguage;
2665
3588
  }
2666
3589
  const local = this.getPropertyOption(propertyName, propertySchema, options, 'local');
2667
- const writable = this.getPropertyOption(propertyName, propertySchema, options, 'writable', true);
3590
+ // Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
3591
+ let readOnly = this.getPropertyOption(propertyName, propertySchema, options, 'readOnly');
3592
+ if (readOnly === undefined) {
3593
+ const xWritable = propertySchema["x-ad4m"]?.writable;
3594
+ readOnly = xWritable !== undefined ? !xWritable : false;
3595
+ }
3596
+ const writable = !readOnly;
2668
3597
  let initial = this.getPropertyOption(propertyName, propertySchema, options, 'initial');
2669
3598
 
2670
3599
  // Handle nested objects by serializing to JSON
@@ -2677,6 +3606,13 @@ WHERE ${whereConditions.join(' AND ')}
2677
3606
  if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
2678
3607
  resolveLanguage = 'literal';
2679
3608
  }
3609
+
3610
+ // Default resolveLanguage to 'literal' for all remaining property types,
3611
+ // matching the @Property decorator behaviour. Without this, string values
3612
+ // stored as literal:// URLs are returned unparsed.
3613
+ if (resolveLanguage === undefined || resolveLanguage === null) {
3614
+ resolveLanguage = 'literal';
3615
+ }
2680
3616
 
2681
3617
  // If property is required, ensure it has an initial value
2682
3618
  if (isRequired && !initial) {
@@ -2715,56 +3651,30 @@ WHERE ${whereConditions.join(' AND ')}
2715
3651
  }
2716
3652
  }
2717
3653
 
2718
- // Validate that at least one property has an initial value (needed for valid SDNA constructor)
2719
- // Collections don't create constructor actions, only properties with initial values do
2720
- const hasPropertyWithInitial = Object.values(properties).some((prop: any) => prop.initial);
3654
+ // No auto-flag generation — models with all-optional properties use
3655
+ // open-world structural matching. Consumers who need type discrimination
3656
+ // should add an explicit @Flag to their model definition.
2721
3657
 
2722
- if (!hasPropertyWithInitial) {
2723
- // If no properties have initial values, add a type identifier automatically
2724
- const typeProperty = `ad4m://type`;
2725
- let typeValue: string;
2726
- if (namespace.includes('://')) {
2727
- const [scheme, rest] = namespace.split('://');
2728
- const path = (rest || '').replace(/\/+$/,'');
2729
- if (path) {
2730
- typeValue = `${scheme}://${path}/instance`;
2731
- } else {
2732
- typeValue = `${scheme}://instance`;
2733
- }
2734
- } else {
2735
- const path = namespace.replace(/\/+$/,'');
2736
- typeValue = `${path}/instance`;
2737
- }
2738
-
2739
- properties['__ad4m_type'] = {
2740
- through: typeProperty,
2741
- required: true,
2742
- writable: false,
2743
- initial: typeValue,
2744
- flag: true
2745
- };
2746
-
2747
- // Add the type property to the prototype
2748
- Object.defineProperty(DynamicModelClass.prototype, '__ad4m_type', {
2749
- configurable: true,
2750
- writable: false,
2751
- value: typeValue
3658
+ // Attach metadata to WeakMap registries
3659
+ for (const [propName, propMeta] of Object.entries(properties)) {
3660
+ setPropertyRegistryEntry(DynamicModelClass, propName, propMeta as any);
3661
+ }
3662
+ for (const [relName, relMeta] of Object.entries(relations)) {
3663
+ setRelationRegistryEntry(DynamicModelClass, relName, {
3664
+ predicate: (relMeta as any).through || "",
3665
+ kind: 'hasMany',
3666
+ ...(( relMeta as any).getter !== undefined && { getter: (relMeta as any).getter }),
3667
+ ...(( relMeta as any).local !== undefined && { local: (relMeta as any).local }),
2752
3668
  });
2753
-
2754
- console.warn(`No properties with initial values found. Added automatic type flag: ${typeProperty} = ${typeValue}`);
2755
3669
  }
2756
3670
 
2757
- // Attach metadata to prototype
2758
- (DynamicModelClass.prototype as any).__properties = properties;
2759
- (DynamicModelClass.prototype as any).__collections = collections;
2760
-
2761
3671
  // Store the JSON schema and options on the prototype for potential fallback use by getModelMetadata()
2762
3672
  (DynamicModelClass.prototype as any).__jsonSchema = schema;
2763
3673
  (DynamicModelClass.prototype as any).__jsonSchemaOptions = options;
2764
3674
 
2765
- // Apply the ModelOptions decorator to set up the generateSDNA method
2766
- const ModelOptionsDecorator = ModelOptions({ name: options.name });
2767
- ModelOptionsDecorator(DynamicModelClass);
3675
+ // Apply the Model decorator to set up the generateSDNA method
3676
+ const ModelDecorator = Model({ name: options.name });
3677
+ ModelDecorator(DynamicModelClass);
2768
3678
 
2769
3679
  return DynamicModelClass as typeof Ad4mModel;
2770
3680
  }
@@ -3029,18 +3939,76 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
3029
3939
  }
3030
3940
 
3031
3941
  /**
3032
- * Sets the source filter for the query.
3033
- *
3034
- * @param source - The source to filter by
3942
+ * Scopes the query to instances linked from a parent.
3943
+ *
3944
+ * The predicate is resolved in order of precedence:
3945
+ * 1. **Instance only** — the parent's constructor is used as the model
3946
+ * class; its relation metadata is scanned for a relation whose
3947
+ * `target()` matches the queried model class.
3948
+ * 2. **Instance + options with `field`** — direct field-name lookup on
3949
+ * the parent model's relation metadata (disambiguates when a parent
3950
+ * has multiple relations targeting the same child class).
3951
+ * 3. **String id + model class** — same metadata scan (or field lookup if
3952
+ * options include `field`).
3953
+ * 4. **String id + string predicate** — raw escape hatch, no metadata lookup.
3954
+ *
3955
+ * Passing a plain string id with no second argument throws because the
3956
+ * predicate cannot be resolved without a model class.
3957
+ *
3958
+ * @param idOrInstance - The parent's expression URI **or** an Ad4mModel instance
3959
+ * @param modelOrPredicate - A model class (predicate auto-resolved) **or** a raw predicate string
3960
+ * @param options - Optional settings: `field` for direct relation-name lookup
3035
3961
  * @returns The query builder for chaining
3036
- *
3962
+ *
3037
3963
  * @example
3038
3964
  * ```typescript
3039
- * .source("ad4m://self")
3965
+ * // Instance — predicate auto-resolved from Cookbook's @HasMany(() => Recipe)
3966
+ * Recipe.query(perspective).parent(cookbook).get();
3967
+ *
3968
+ * // Instance + field — disambiguate when parent has multiple relations to same child
3969
+ * Recipe.query(perspective).parent(cookbook, { field: "recipes" }).get();
3970
+ *
3971
+ * // String id + model class
3972
+ * Recipe.query(perspective).parent(cookbookId, Cookbook).get();
3973
+ *
3974
+ * // String id + model class + field
3975
+ * Recipe.query(perspective).parent(cookbookId, Cookbook, { field: "recipes" }).get();
3976
+ *
3977
+ * // String id + raw predicate (escape hatch)
3978
+ * Recipe.query(perspective).parent(cookbookId, "cookbook://recipe").get();
3040
3979
  * ```
3041
3980
  */
3042
- source(source: string): ModelQueryBuilder<T> {
3043
- this.queryParams.source = source;
3981
+ parent(idOrInstance: string | Ad4mModel, modelOrPredicate?: typeof Ad4mModel | string | { field: string }, options?: { field?: string }): ModelQueryBuilder<T> {
3982
+ const id = typeof idOrInstance === 'string' ? idOrInstance : idOrInstance.id;
3983
+
3984
+ // Handle options-object as second arg: parent(instance, { field: "recipes" })
3985
+ if (typeof modelOrPredicate === 'object' && modelOrPredicate !== null && !('prototype' in modelOrPredicate)) {
3986
+ if (typeof idOrInstance === 'string') {
3987
+ throw new Error(
3988
+ 'parent() called with a string id and options object requires a model class as second argument',
3989
+ );
3990
+ }
3991
+ const model = idOrInstance.constructor as typeof Ad4mModel;
3992
+ this.queryParams.parent = { id, model, field: (modelOrPredicate as { field: string }).field };
3993
+ return this;
3994
+ }
3995
+
3996
+ const field = options?.field;
3997
+
3998
+ if (typeof modelOrPredicate === 'string') {
3999
+ // Raw predicate string → raw form of ParentScope
4000
+ this.queryParams.parent = { id, predicate: modelOrPredicate };
4001
+ } else if (typeof modelOrPredicate === 'function') {
4002
+ // Model class → model form of ParentScope
4003
+ this.queryParams.parent = { id, model: modelOrPredicate, ...(field && { field }) };
4004
+ } else if (typeof idOrInstance !== 'string') {
4005
+ // Ad4mModel instance — derive model class from constructor
4006
+ this.queryParams.parent = { id, model: idOrInstance.constructor as typeof Ad4mModel, ...(field && { field }) };
4007
+ } else {
4008
+ throw new Error(
4009
+ 'parent() called with a string id requires a second argument: either a model class or a predicate string',
4010
+ );
4011
+ }
3044
4012
  return this;
3045
4013
  }
3046
4014
 
@@ -3061,18 +4029,33 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
3061
4029
  }
3062
4030
 
3063
4031
  /**
3064
- * Specifies which collections to include in the results.
3065
- *
3066
- * @param collections - Array of collection names to include
4032
+ * Specifies which relations to eager-load (hydrate into model instances).
4033
+ *
4034
+ * Without `include`, relation fields contain raw expression URIs (strings).
4035
+ * With `include`, the URIs are resolved into fully-hydrated model instances
4036
+ * using the `target` class declared in the relation decorator.
4037
+ *
4038
+ * Supports nested includes for multi-level eager loading.
4039
+ *
4040
+ * @param map - An IncludeMap describing which relations to hydrate
3067
4041
  * @returns The query builder for chaining
3068
- *
4042
+ *
3069
4043
  * @example
3070
4044
  * ```typescript
3071
- * .collections(["ingredients", "steps"])
4045
+ * // Hydrate comments one level deep
4046
+ * const recipes = await Recipe.query(perspective)
4047
+ * .include({ comments: true })
4048
+ * .run();
4049
+ * // recipe.comments is now Comment[] (model instances), not string[]
4050
+ *
4051
+ * // Nested: hydrate comments AND each comment's author
4052
+ * const recipes = await Recipe.query(perspective)
4053
+ * .include({ comments: { author: true } })
4054
+ * .run();
3072
4055
  * ```
3073
4056
  */
3074
- collections(collections: string[]): ModelQueryBuilder<T> {
3075
- this.queryParams.collections = collections;
4057
+ include(map: IncludeMap): ModelQueryBuilder<T> {
4058
+ this.queryParams.include = map;
3076
4059
  return this;
3077
4060
  }
3078
4061
 
@@ -3124,17 +4107,38 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
3124
4107
  * ```
3125
4108
  */
3126
4109
  async get(): Promise<T[]> {
4110
+ let results: T[];
3127
4111
  if (this.useSurrealDBFlag) {
3128
4112
  const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
3129
4113
  const result = await this.perspective.querySurrealDB(surrealQuery);
3130
- const { results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
3131
- return results as T[];
4114
+ ({ results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result) as { results: T[] });
3132
4115
  } else {
3133
4116
  const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
3134
4117
  const result = await this.perspective.infer(query);
3135
- const { results } = await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, result);
3136
- return results as T[];
4118
+ ({ results } = await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, result) as { results: T[] });
3137
4119
  }
4120
+
4121
+ return results;
4122
+ }
4123
+
4124
+ /**
4125
+ * Returns the first matching instance, or `null` if none match.
4126
+ *
4127
+ * Internally sets `limit: 1` and delegates to `get()`.
4128
+ *
4129
+ * @returns The first matching instance, or `null`
4130
+ *
4131
+ * @example
4132
+ * ```typescript
4133
+ * const recipe = await Recipe.query(perspective)
4134
+ * .where({ name: "Pasta" })
4135
+ * .first();
4136
+ * ```
4137
+ */
4138
+ async first(): Promise<T | null> {
4139
+ this.queryParams.limit = 1;
4140
+ const results = await this.get();
4141
+ return results[0] ?? null;
3138
4142
  }
3139
4143
 
3140
4144
  /**
@@ -3172,43 +4176,45 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
3172
4176
  // Clean up any existing subscription
3173
4177
  this.dispose();
3174
4178
 
4179
+ const ctor = this.ctor;
4180
+
3175
4181
  if (this.useSurrealDBFlag) {
3176
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
4182
+ const surrealQuery = await ctor.queryToSurrealQL(this.perspective, this.queryParams);
3177
4183
  this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
3178
4184
 
3179
4185
  const processResults = async (result: any) => {
3180
- // The result from live query subscription update (handled in PerspectiveInstance listener)
3181
- // is the new full set of results (because we re-query in Rust).
3182
- // So we just need to map it to instances.
3183
- const { results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
4186
+ const { results } = await ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
3184
4187
  callback(results as T[]);
3185
4188
  };
3186
4189
 
3187
4190
  this.currentSubscription.onResult(processResults);
3188
4191
 
3189
4192
  // Process initial result
3190
- const { results } = await this.ctor.instancesFromSurrealResult(
4193
+ const { results } = await ctor.instancesFromSurrealResult(
3191
4194
  this.perspective,
3192
4195
  this.queryParams,
3193
4196
  this.currentSubscription.result
3194
4197
  );
4198
+ // Also invoke callback with initial results so subscribers see them
4199
+ callback(results as T[]);
3195
4200
  return results as T[];
3196
4201
  } else {
3197
- // Note: Subscriptions currently only work with Prolog
3198
- const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
4202
+ const query = await ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
3199
4203
  this.currentSubscription = await this.perspective.subscribeInfer(query);
3200
4204
 
3201
4205
  const processResults = async (result: AllInstancesResult) => {
3202
- const { results } = await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, result);
4206
+ const { results } = await ctor.instancesFromPrologResult(this.perspective, this.queryParams, result);
3203
4207
  callback(results as T[]);
3204
4208
  };
3205
4209
 
3206
4210
  this.currentSubscription.onResult(processResults);
3207
- const { results } = await this.ctor.instancesFromPrologResult(
4211
+ const { results } = await ctor.instancesFromPrologResult(
3208
4212
  this.perspective,
3209
4213
  this.queryParams,
3210
4214
  this.currentSubscription.result
3211
4215
  );
4216
+ // Also invoke callback with initial results so subscribers see them
4217
+ callback(results as T[]);
3212
4218
  return results as T[];
3213
4219
  }
3214
4220
  }
@@ -3291,6 +4297,7 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
3291
4297
  this.queryParams,
3292
4298
  this.currentSubscription.result
3293
4299
  );
4300
+ callback(totalCount);
3294
4301
  return totalCount;
3295
4302
  } else {
3296
4303
  const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -3302,7 +4309,9 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
3302
4309
  };
3303
4310
 
3304
4311
  this.currentSubscription.onResult(processResults);
3305
- return this.currentSubscription.result?.[0]?.TotalCount || 0;
4312
+ const initialCount = this.currentSubscription.result?.[0]?.TotalCount || 0;
4313
+ callback(initialCount);
4314
+ return initialCount;
3306
4315
  }
3307
4316
  }
3308
4317
 
@@ -3390,7 +4399,9 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
3390
4399
 
3391
4400
  this.currentSubscription.onResult(processResults);
3392
4401
  const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, this.currentSubscription.result)) as ResultsWithTotalCount<T>;
3393
- return { results, totalCount, pageSize, pageNumber };
4402
+ const initialPage = { results, totalCount, pageSize, pageNumber };
4403
+ callback(initialPage);
4404
+ return initialPage;
3394
4405
  } else {
3395
4406
  const prologQuery = await this.ctor.queryToProlog(this.perspective, paginationQuery, this.modelClassName);
3396
4407
  this.currentSubscription = await this.perspective.subscribeInfer(prologQuery);
@@ -3402,7 +4413,142 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
3402
4413
 
3403
4414
  this.currentSubscription.onResult(processResults);
3404
4415
  const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, this.currentSubscription.result)) as ResultsWithTotalCount<T>;
3405
- return { results, totalCount, pageSize, pageNumber };
4416
+ const initialPrologPage = { results, totalCount, pageSize, pageNumber };
4417
+ callback(initialPrologPage);
4418
+ return initialPrologPage;
4419
+ }
4420
+ }
4421
+ }
4422
+
4423
+ // ── Standalone Prolog fact generator ──────────────────────────────────────────
4424
+
4425
+ /**
4426
+ * Convert a camelCase or PascalCase identifier to snake_case.
4427
+ * Examples: "TestPost" -> "test_post", "createdAt" -> "created_at"
4428
+ */
4429
+ function toSnakeCase(str: string): string {
4430
+ return str
4431
+ .replace(/([A-Z])/g, "_$1")
4432
+ .toLowerCase()
4433
+ .replace(/^_/, "");
4434
+ }
4435
+
4436
+ function buildInstanceClause(predicateName: string, metadata: ModelMetadata): string | null {
4437
+ const props = metadata.properties;
4438
+ // Collect flags first — these are the strongest recognizers
4439
+ const flags = Object.values(props).filter((p) => p.flag && p.predicate && p.initial);
4440
+ if (flags.length > 0) {
4441
+ const conditions = flags
4442
+ .map((p) => `triple(X, '${p.predicate}', '${p.initial}')`)
4443
+ .join(",\n ");
4444
+ return `${predicateName}(X) :-\n ${conditions}.`;
4445
+ }
4446
+ // Fallback: required non-flag properties
4447
+ const required = Object.values(props).filter((p) => p.required && p.predicate && !p.flag);
4448
+ if (required.length > 0) {
4449
+ const conditions = required
4450
+ .map((p) => `triple(X, '${p.predicate}', _)`)
4451
+ .join(",\n ");
4452
+ return `${predicateName}(X) :-\n ${conditions}.`;
4453
+ }
4454
+ // Open-world structural fallback: match nodes that have at least one of the
4455
+ // model's declared property predicates. Uses disjunction (;) so any single
4456
+ // predicate is enough.
4457
+ const allPredicates = Object.values(props)
4458
+ .filter((p) => p.predicate)
4459
+ .map((p) => p.predicate!);
4460
+ if (metadata.relations) {
4461
+ for (const rel of Object.values(metadata.relations)) {
4462
+ if (rel.predicate) allPredicates.push(rel.predicate);
3406
4463
  }
3407
4464
  }
4465
+ if (allPredicates.length > 0) {
4466
+ const disjunction = allPredicates
4467
+ .map((pred) => `triple(X, '${pred}', _)`)
4468
+ .join(" ;\n ");
4469
+ return `${predicateName}(X) :-\n (${disjunction}).`;
4470
+ }
4471
+ return null;
4472
+ }
4473
+
4474
+ function buildPropertyClause(modelPredicateName: string, prop: PropertyMetadata): string | null {
4475
+ if (prop.flag) return null;
4476
+ if (!prop.predicate) return null;
4477
+ const clauseName = `${modelPredicateName}_${toSnakeCase(prop.name)}`;
4478
+ return `${clauseName}(X, Value) :- triple(X, '${prop.predicate}', Value).`;
4479
+ }
4480
+
4481
+ function buildRelationClause(modelPredicateName: string, relation: RelationMetadata): string | null {
4482
+ if (!relation.predicate) return null;
4483
+ const clauseName = `${modelPredicateName}_${toSnakeCase(relation.name)}`;
4484
+ if (relation.direction === "reverse") {
4485
+ return `${clauseName}(X, Values) :- findall(V, triple(V, '${relation.predicate}', X), Values).`;
4486
+ }
4487
+ return `${clauseName}(X, Values) :- findall(V, triple(X, '${relation.predicate}', V), Values).`;
4488
+ }
4489
+
4490
+ /**
4491
+ * Generate Prolog predicate facts from a model class's decorator metadata.
4492
+ *
4493
+ * Given a model class decorated with `@Model` (and its `@Flag`, `@Property`,
4494
+ * `@HasMany`, `@BelongsToMany` decorators), this function emits a string of
4495
+ * Prolog clauses that can be prepended to any `perspective.infer()` call.
4496
+ *
4497
+ * The generated predicates are:
4498
+ * - **Instance recognizer** — `modelName(X)` — matches instances of the model
4499
+ * - **Property getters** — `modelName_propName(X, Value)` — one per property
4500
+ * - **Relation getters** — `modelName_relName(X, Values)` — one per relation
4501
+ *
4502
+ * @example
4503
+ * ```typescript
4504
+ * import { generatePrologFacts } from '@coasys/ad4m';
4505
+ *
4506
+ * const facts = generatePrologFacts(Poll);
4507
+ * const result = await perspective.infer(\`
4508
+ * \${facts}
4509
+ * recent_popular_poll(X) :-
4510
+ * poll(X),
4511
+ * poll_vote_count(X, N), N > 10.
4512
+ * \`);
4513
+ * ```
4514
+ *
4515
+ * @param ModelClass - A class decorated with `@Model` that extends `Ad4mModel`
4516
+ * @returns A multi-line Prolog string ready for use with `perspective.infer()`
4517
+ */
4518
+ export function generatePrologFacts(ModelClass: typeof Ad4mModel): string {
4519
+ const metadata = ModelClass.getModelMetadata();
4520
+ const predicateName = toSnakeCase(metadata.className);
4521
+ const lines: string[] = [];
4522
+
4523
+ lines.push(`% ${metadata.className} — generated Prolog facts`);
4524
+
4525
+ // Instance recognizer
4526
+ const instanceClause = buildInstanceClause(predicateName, metadata);
4527
+ if (instanceClause) {
4528
+ lines.push("");
4529
+ lines.push(`% Instance recognizer`);
4530
+ lines.push(instanceClause);
4531
+ }
4532
+
4533
+ // Property getters
4534
+ const propClauses = Object.values(metadata.properties)
4535
+ .map((p) => buildPropertyClause(predicateName, p))
4536
+ .filter((c): c is string => c !== null);
4537
+ if (propClauses.length > 0) {
4538
+ lines.push("");
4539
+ lines.push(`% Field getters`);
4540
+ lines.push(...propClauses);
4541
+ }
4542
+
4543
+ // Relation getters
4544
+ const relClauses = Object.values(metadata.relations)
4545
+ .map((c) => buildRelationClause(predicateName, c))
4546
+ .filter((c): c is string => c !== null);
4547
+ if (relClauses.length > 0) {
4548
+ lines.push("");
4549
+ lines.push(`% Relation getters`);
4550
+ lines.push(...relClauses);
4551
+ }
4552
+
4553
+ return lines.join("\n");
3408
4554
  }