@coasys/ad4m 0.13.0-test-5 → 0.13.0-test-7

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.
@@ -2,16 +2,36 @@ import { ApiClient } from "../apiClient";
2
2
  import { InteractionCall, InteractionMeta } from "../language/Language";
3
3
  import { ExpressionRendered } from "./Expression";
4
4
  import { Literal } from "../Literal";
5
+ import { PersistentCache, createPersistentCache } from "../cache/PersistentCache";
5
6
  import type { CreateExpressionRequest, ExpressionManyRequest } from "../generated/api";
6
7
 
8
+ interface CachedExpression {
9
+ data: ExpressionRendered;
10
+ size: number;
11
+ }
12
+
7
13
  export class ExpressionClient {
8
14
  #apiClient: ApiClient
9
15
 
16
+ // L1: in-memory LRU cache (hot path, sub-ms)
17
+ #memCache = new Map<string, CachedExpression>();
18
+ #inflight = new Map<string, Promise<ExpressionRendered>>();
19
+ /** Maximum number of entries in the L1 memory cache. */
20
+ static MAX_MEM_ENTRIES = 200;
21
+ /** Maximum total size (in bytes) of L1 memory cache values. */
22
+ static MAX_MEM_BYTES = 5 * 1024 * 1024; // 5 MB
23
+ #totalMemBytes = 0;
24
+
25
+ // L2: persistent cache (IndexedDB in browser, NullCache in Node)
26
+ #persistent: PersistentCache<ExpressionRendered>;
27
+
10
28
  constructor(baseUrl: string, token?: string, sharedApiClient?: ApiClient) {
11
29
  this.#apiClient = sharedApiClient || new ApiClient(baseUrl, token)
30
+ this.#persistent = createPersistentCache<ExpressionRendered>('ad4m-expression-cache', 'expressions');
12
31
  }
13
32
 
14
33
  async get(url: string, alwaysGet: boolean = false): Promise<ExpressionRendered> {
34
+ // Existing literal fast-path
15
35
  if(!alwaysGet){
16
36
  try {
17
37
  let literalValue = Literal.fromUrl(url).get();
@@ -23,11 +43,120 @@ export class ExpressionClient {
23
43
  } catch(e) {}
24
44
  }
25
45
 
26
- return this.#apiClient.call<ExpressionRendered>('expression.get', { url })
46
+ // L1: memory hit
47
+ if (!alwaysGet) {
48
+ const memHit = this.#memCache.get(url);
49
+ if (memHit) return memHit.data;
50
+ }
51
+
52
+ // Deduplicate in-flight requests
53
+ if (!alwaysGet) {
54
+ const existing = this.#inflight.get(url);
55
+ if (existing) return existing;
56
+ }
57
+
58
+ // L2 check + L3 network
59
+ const promise = (async () => {
60
+ if (!alwaysGet) {
61
+ const persisted = await this.#persistent.get(url);
62
+ if (persisted) {
63
+ this.#memCacheResult(url, persisted); // promote to L1
64
+ return persisted;
65
+ }
66
+ }
67
+
68
+ // L3: network fetch
69
+ const result = await this.#apiClient.call<ExpressionRendered>('expression.get', { url });
70
+ this.#memCacheResult(url, result);
71
+ this.#persistent.put(url, result); // fire-and-forget write to L2
72
+ return result;
73
+ })();
74
+
75
+ this.#inflight.set(url, promise);
76
+
77
+ try {
78
+ return await promise;
79
+ } finally {
80
+ this.#inflight.delete(url);
81
+ }
27
82
  }
28
83
 
29
84
  async getMany(urls: string[]): Promise<ExpressionRendered[]> {
30
- return this.#apiClient.call<ExpressionRendered[]>('expression.getMany', { urls })
85
+ // Check L1 first
86
+ const results: (ExpressionRendered | null)[] = urls.map(
87
+ u => this.#memCache.get(u)?.data ?? null
88
+ );
89
+ let uncachedIndices = results
90
+ .map((r, i) => r === null ? i : -1)
91
+ .filter(i => i >= 0);
92
+
93
+ if (uncachedIndices.length === 0) return results as ExpressionRendered[];
94
+
95
+ // Check L2 for remaining misses
96
+ const l2Results = await Promise.all(
97
+ uncachedIndices.map(i => this.#persistent.get(urls[i]))
98
+ );
99
+ const stillMissing: number[] = [];
100
+ for (let j = 0; j < uncachedIndices.length; j++) {
101
+ const idx = uncachedIndices[j];
102
+ if (l2Results[j]) {
103
+ results[idx] = l2Results[j]!;
104
+ this.#memCacheResult(urls[idx], l2Results[j]!); // promote to L1
105
+ } else {
106
+ stillMissing.push(idx);
107
+ }
108
+ }
109
+
110
+ if (stillMissing.length === 0) return results as ExpressionRendered[];
111
+
112
+ // L3: fetch only truly uncached URLs
113
+ const uncachedUrls = stillMissing.map(i => urls[i]);
114
+ const fetched = await this.#apiClient.call<ExpressionRendered[]>(
115
+ 'expression.getMany', { urls: uncachedUrls }
116
+ );
117
+
118
+ for (let i = 0; i < stillMissing.length; i++) {
119
+ const idx = stillMissing[i];
120
+ results[idx] = fetched[i];
121
+ if (fetched[i]) {
122
+ this.#memCacheResult(uncachedUrls[i], fetched[i]);
123
+ this.#persistent.put(uncachedUrls[i], fetched[i]); // fire-and-forget
124
+ }
125
+ }
126
+
127
+ return results as ExpressionRendered[];
128
+ }
129
+
130
+ /**
131
+ * Insert a result into L1 memory cache with LRU eviction.
132
+ */
133
+ #memCacheResult(url: string, data: ExpressionRendered): void {
134
+ const size = JSON.stringify(data).length;
135
+
136
+ // Evict oldest entries if we'd exceed limits
137
+ while (
138
+ this.#memCache.size >= ExpressionClient.MAX_MEM_ENTRIES ||
139
+ this.#totalMemBytes + size > ExpressionClient.MAX_MEM_BYTES
140
+ ) {
141
+ const oldest = this.#memCache.keys().next().value;
142
+ if (!oldest) break;
143
+ const entry = this.#memCache.get(oldest)!;
144
+ this.#totalMemBytes -= entry.size;
145
+ this.#memCache.delete(oldest);
146
+ }
147
+
148
+ this.#memCache.set(url, { data, size });
149
+ this.#totalMemBytes += size;
150
+ }
151
+
152
+ /**
153
+ * Clear both L1 (memory) and L2 (persistent) expression caches.
154
+ */
155
+ clearCache(): void {
156
+ this.#memCache.clear();
157
+ this.#inflight.clear();
158
+ this.#totalMemBytes = 0;
159
+ this.#persistent.clear(); // fire-and-forget
31
160
  }
32
161
 
33
162
  async getRaw(url: string): Promise<string> {
@@ -44,6 +173,11 @@ export class ExpressionClient {
44
173
  }
45
174
 
46
175
  async interact(url: string, interactionCall: InteractionCall): Promise<string|null> {
47
- return this.#apiClient.call<string|null>('expression.interact', { url, interactionCall })
176
+ const result = await this.#apiClient.call<string|null>('expression.interact', { url, interactionCall });
177
+ // Interactions can mutate the expression — invalidate cache so next get() fetches fresh
178
+ this.#memCache.delete(url);
179
+ this.#inflight.delete(url);
180
+ this.#persistent.delete(url); // fire-and-forget
181
+ return result;
48
182
  }
49
183
  }
package/src/index.ts CHANGED
@@ -2,6 +2,7 @@ export * from "./Ad4mClient"
2
2
  export * from "./Address";
3
3
  export * from "./agent/Agent";
4
4
  export * from "./agent/AgentStatus";
5
+ export * from "./cache/PersistentCache";
5
6
  export * from "./Exception";
6
7
  export * from "./expression/Expression";
7
8
  export * from "./expression/ExpressionRef";
@@ -1424,66 +1424,6 @@ describe("ModelQueryBuilder paginateSubscribe", () => {
1424
1424
  expect(queryJson.offset).toBe(0);
1425
1425
  });
1426
1426
 
1427
- it("paginateSubscribe should skip isInit messages from subscription", async () => {
1428
- const mockSubscriptionId = "paginate-init-sub";
1429
- let capturedCallback: ((result: any) => void) | null = null;
1430
-
1431
- const mockClient = {
1432
- modelSubscribe: jest.fn().mockResolvedValue({
1433
- subscriptionId: mockSubscriptionId,
1434
- result: { instances: [], totalCount: 0 },
1435
- }),
1436
- subscribeToQueryUpdates: jest.fn().mockImplementation((_id: string, cb: any) => {
1437
- capturedCallback = cb;
1438
- return () => {};
1439
- }),
1440
- keepAliveQuery: jest.fn().mockResolvedValue(true),
1441
- disposeQuerySubscription: jest.fn().mockResolvedValue(true),
1442
- };
1443
-
1444
- let modelQueryCallCount = 0;
1445
- const mockPerspective = {
1446
- uuid: "test-uuid",
1447
- client: mockClient,
1448
- modelSubscribe: jest.fn().mockImplementation(async (className: string, queryJson: string, shapeJson?: string) => {
1449
- return mockClient.modelSubscribe("test-uuid", className, queryJson, shapeJson);
1450
- }),
1451
- modelQuery: jest.fn().mockImplementation(async () => {
1452
- modelQueryCallCount++;
1453
- return { instances: [], totalCount: 0 };
1454
- }),
1455
- } as any;
1456
-
1457
- const { Ad4mModel, Model, Flag, Property } = require("./index");
1458
-
1459
- @Model({ name: "InitGuardTest" })
1460
- class InitGuardTest extends Ad4mModel {
1461
- @Flag({ through: "test://type", value: "test://init" })
1462
- type: string = "test://init";
1463
- @Property({ through: "test://name" })
1464
- name: string = "";
1465
- }
1466
-
1467
- const userCallback = jest.fn();
1468
- const builder = InitGuardTest.query(mockPerspective);
1469
- await builder.paginateSubscribe(10, 1, userCallback);
1470
-
1471
- // Reset the count after initial fetch
1472
- const initialCallCount = modelQueryCallCount;
1473
-
1474
- // Simulate an isInit message from subscription
1475
- expect(capturedCallback).not.toBeNull();
1476
- capturedCallback!({ isInit: true });
1477
-
1478
- // Wait for any async processing
1479
- await new Promise(r => setTimeout(r, 50));
1480
-
1481
- // modelQuery should NOT have been called again (isInit was filtered)
1482
- expect(modelQueryCallCount).toBe(initialCallCount);
1483
- // User callback should NOT have been invoked by isInit
1484
- expect(userCallback).not.toHaveBeenCalled();
1485
- });
1486
-
1487
1427
  it("paginateSubscribe should re-fetch on real subscription updates", async () => {
1488
1428
  const mockSubscriptionId = "paginate-update-sub";
1489
1429
  let capturedCallback: ((result: any) => void) | null = null;
@@ -1530,7 +1470,7 @@ describe("ModelQueryBuilder paginateSubscribe", () => {
1530
1470
 
1531
1471
  const initialCallCount = modelQueryCallCount;
1532
1472
 
1533
- // Simulate a real subscription update (not isInit)
1473
+ // Simulate a subscription update
1534
1474
  capturedCallback!({ instances: [{ id: "new-item" }], totalCount: 1 });
1535
1475
 
1536
1476
  // Wait for async processing
@@ -24,6 +24,46 @@ import type {
24
24
  } from "./types";
25
25
 
26
26
 
27
+ // ---------------------------------------------------------------------------
28
+ // Default decoder for file-storage (non-literal resolveLanguage) properties
29
+ // ---------------------------------------------------------------------------
30
+
31
+ /**
32
+ * When the Rust executor resolves a non-literal expression it may return a
33
+ * `FileData`-shaped object (`{ data_base64, file_type, ... }`) rather than a
34
+ * raw URI string. If the model class has no custom `transform` registered
35
+ * (e.g. it was synthesised from a SHACL shape at runtime) we still want to
36
+ * decode the content rather than passing raw `FileData` to callers.
37
+ *
38
+ * Decoding rules (mirrors the JS `decodeFileAsJson` / `decodeFileAsString` helpers):
39
+ * - `application/json` (default when `file_type` is absent) → JSON.parse
40
+ * - anything else → raw decoded string
41
+ *
42
+ * If `resolved` is not a `FileData` object the value is returned unchanged so
43
+ * that callers can use this as a safe unconditional fallback.
44
+ */
45
+ function defaultFileDecode(resolved: unknown): unknown {
46
+ if (
47
+ resolved !== null &&
48
+ typeof resolved === 'object' &&
49
+ 'data_base64' in (resolved as object)
50
+ ) {
51
+ const fd = resolved as { data_base64: string; file_type?: string };
52
+ let raw: string;
53
+ try {
54
+ raw = atob(fd.data_base64);
55
+ } catch {
56
+ return resolved; // malformed base64 — keep as-is
57
+ }
58
+ const isJson = !fd.file_type || fd.file_type === 'application/json';
59
+ if (isJson) {
60
+ try { return JSON.parse(raw); } catch { return raw; }
61
+ }
62
+ return raw;
63
+ }
64
+ return resolved;
65
+ }
66
+
27
67
  // ---------------------------------------------------------------------------
28
68
  // Helpers for Rust-side include resolution
29
69
  // ---------------------------------------------------------------------------
@@ -857,7 +897,11 @@ export class Ad4mModel {
857
897
  enrichShapeForIncludes(metadata, query.include, allRelMeta);
858
898
  }
859
899
 
860
- // Pre-compute conformance getters (with where-clause support)
900
+ // Pre-compute conformance getters for Rust-side evaluation.
901
+ // Where clauses are NOT compiled into getter SPARQL because stored
902
+ // property values are signed expression envelopes (literal:json:...),
903
+ // not simple literal:string:X values. Instead, where clauses are
904
+ // attached as metadata for Rust-side post-evaluation filtering.
861
905
  {
862
906
  const allRelMeta = getRelationsMetadata(this as any);
863
907
  for (const [relName, relMeta] of Object.entries(metadata.relations)) {
@@ -869,41 +913,30 @@ export class Ad4mModel {
869
913
  const TargetClass = meta.target();
870
914
  const filter = buildConformanceFilter(meta.predicate, TargetClass);
871
915
 
872
- // Compile where clauses to SPARQL when all target properties use
873
- // literal encoding (literal:string:X etc.) which is SPARQL-matchable.
874
- // Properties with a non-literal resolveLanguage store expression hashes
875
- // that can't be matched by value in SPARQL.
876
- let whereConditions: string[] = [];
916
+ if (filter) {
917
+ rel.getter = filter.getter;
918
+ }
919
+
920
+ // Attach where-clause metadata for Rust-side post-getter filtering
877
921
  if (rel.where) {
878
922
  try {
879
923
  const targetMetadata = (TargetClass as any).getModelMetadata?.() ?? null;
880
- let allSparqlFilterable = true;
881
924
  if (targetMetadata) {
925
+ const predicates: Record<string, string> = {};
882
926
  for (const propName of Object.keys(rel.where)) {
883
927
  if (['id', 'author', 'timestamp'].includes(propName)) continue;
884
928
  const propMeta = targetMetadata.properties[propName];
885
- if (propMeta?.resolveLanguage && propMeta.resolveLanguage !== 'literal') {
886
- allSparqlFilterable = false;
887
- break;
929
+ if (propMeta?.predicate) {
930
+ predicates[propName] = propMeta.predicate;
888
931
  }
889
932
  }
890
- }
891
- if (allSparqlFilterable) {
892
- whereConditions = compileWhereClause(rel.where, targetMetadata);
933
+ if (Object.keys(predicates).length > 0) {
934
+ rel.whereFilter = rel.where;
935
+ rel.wherePredicates = predicates;
936
+ }
893
937
  }
894
938
  } catch (_) {}
895
939
  }
896
-
897
- if (filter) {
898
- let getter = filter.getter;
899
- if (whereConditions.length > 0) {
900
- getter = getter.replace(/ \}$/, ` ${whereConditions.join(' ')} }`);
901
- }
902
- rel.getter = getter;
903
- } else if (whereConditions.length > 0) {
904
- const escapedPred = meta.predicate.replace(/[<>"{}|\\^`\u0000-\u0020]/g, '');
905
- rel.getter = `SELECT ?target WHERE { <Base> <${escapedPred}> ?target . ${whereConditions.join(' ')} }`;
906
- }
907
940
  } catch (_) {}
908
941
  }
909
942
  }
@@ -933,6 +966,60 @@ export class Ad4mModel {
933
966
  return arr.map((json: any) => jsonToModelInstance(this, perspective, json, include, properties));
934
967
  }
935
968
 
969
+ /**
970
+ * Resolve non-literal (file-language) properties on an array of already-constructed
971
+ * model instances. Handles two cases:
972
+ *
973
+ * 1. The Rust executor returned a raw URI string → fetch via `getExpression` then apply transform.
974
+ * 2. The Rust executor already resolved the expression and returned a `FileData` object
975
+ * (happens when the perspective backend eagerly fetches file content) → apply transform
976
+ * (or `defaultFileDecode` if no transform is registered on the class, e.g. for SHACL-
977
+ * synthesised model classes).
978
+ *
979
+ * Extracted as a public static so `ModelQueryBuilder.subscribe()` can reuse it without
980
+ * duplicating logic or introducing a circular dependency.
981
+ * @internal
982
+ */
983
+ static async resolveNonLiteralProps<T extends Ad4mModel>(
984
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
985
+ perspective: PerspectiveProxy,
986
+ instances: T[],
987
+ ): Promise<void> {
988
+ const propsMeta = getPropertiesMetadata(this as any);
989
+ const resolveProps = Object.entries(propsMeta).filter(
990
+ ([, opts]: [string, any]) =>
991
+ opts.resolveLanguage != null &&
992
+ opts.resolveLanguage !== 'literal',
993
+ );
994
+ if (resolveProps.length === 0) return;
995
+
996
+ await Promise.all(
997
+ instances.map(async (inst: any) => {
998
+ for (const [propName, opts] of resolveProps) {
999
+ const val = inst[propName];
1000
+ const transform = (opts as any).transform;
1001
+ const applyTransform = (resolved: unknown) =>
1002
+ typeof transform === 'function' ? transform(resolved) : defaultFileDecode(resolved);
1003
+
1004
+ if (typeof val === 'string' && val && !val.startsWith('literal:')) {
1005
+ // Case 1: raw URI — fetch from language runtime
1006
+ try {
1007
+ const expression = await perspective.getExpression(val);
1008
+ if (expression) {
1009
+ let resolved: any;
1010
+ try { resolved = JSON.parse(expression.data); } catch { resolved = expression.data; }
1011
+ inst[propName] = applyTransform(resolved);
1012
+ }
1013
+ } catch (_) { /* resolution failed — keep raw value */ }
1014
+ } else if (val !== null && val !== undefined && typeof val === 'object') {
1015
+ // Case 2: already resolved by Rust — apply transform / default decode
1016
+ inst[propName] = applyTransform(val);
1017
+ }
1018
+ }
1019
+ }),
1020
+ );
1021
+ }
1022
+
936
1023
  // instancesFromQueryResult — removed (superseded by Rust executeModelQuery pipeline)
937
1024
 
938
1025
  /**
@@ -1044,43 +1131,32 @@ export class Ad4mModel {
1044
1131
  const TargetClass = meta.target();
1045
1132
  const filter = buildConformanceFilter(meta.predicate, TargetClass);
1046
1133
 
1047
- // Compile where clauses to SPARQL when all target properties use
1048
- // literal encoding (literal:string:X etc.) which is SPARQL-matchable.
1049
- // Properties with a non-literal resolveLanguage store expression hashes
1050
- // that can't be matched by value in SPARQL.
1051
- let whereConditions: string[] = [];
1134
+ if (filter) {
1135
+ rel.getter = filter.getter;
1136
+ }
1137
+
1138
+ // Attach where-clause metadata for Rust-side post-getter filtering.
1139
+ // Property values are signed expression envelopes (literal:json:...)
1140
+ // and cannot be matched by SPARQL FILTER on the raw IRI.
1052
1141
  if (rel.where) {
1053
1142
  try {
1054
1143
  const targetMetadata = (TargetClass as any).getModelMetadata?.() ?? null;
1055
- let allSparqlFilterable = true;
1056
1144
  if (targetMetadata) {
1145
+ const predicates: Record<string, string> = {};
1057
1146
  for (const propName of Object.keys(rel.where)) {
1058
1147
  if (['id', 'author', 'timestamp'].includes(propName)) continue;
1059
1148
  const propMeta = targetMetadata.properties[propName];
1060
- if (propMeta?.resolveLanguage && propMeta.resolveLanguage !== 'literal') {
1061
- allSparqlFilterable = false;
1062
- break;
1149
+ if (propMeta?.predicate) {
1150
+ predicates[propName] = propMeta.predicate;
1063
1151
  }
1064
1152
  }
1065
- }
1066
- if (allSparqlFilterable) {
1067
- whereConditions = compileWhereClause(rel.where, targetMetadata);
1153
+ if (Object.keys(predicates).length > 0) {
1154
+ rel.whereFilter = rel.where;
1155
+ rel.wherePredicates = predicates;
1156
+ }
1068
1157
  }
1069
1158
  } catch (_) { /* target metadata unavailable */ }
1070
1159
  }
1071
-
1072
- if (filter) {
1073
- let getter = filter.getter;
1074
- if (whereConditions.length > 0) {
1075
- // Append where conditions before the closing }
1076
- getter = getter.replace(/ \}$/, ` ${whereConditions.join(' ')} }`);
1077
- }
1078
- rel.getter = getter;
1079
- } else if (whereConditions.length > 0) {
1080
- // No conformance filter but where clause exists — build getter from where alone
1081
- const escapedPred = meta.predicate.replace(/[<>"{}|\\^`\u0000-\u0020]/g, '');
1082
- rel.getter = `SELECT ?target WHERE { <Base> <${escapedPred}> ?target . ${whereConditions.join(' ')} }`;
1083
- }
1084
1160
  } catch (e) {
1085
1161
  // Target class may not be available; skip silently
1086
1162
  }
@@ -1093,14 +1169,6 @@ export class Ad4mModel {
1093
1169
  const shapeJson = JSON.stringify(metadata);
1094
1170
  const queryJson = JSON.stringify(queryInput);
1095
1171
 
1096
- // TEMP DEBUG: Log getters with where-clause filters to diagnose CI failure
1097
- for (const [relName, relMeta] of Object.entries(metadata.relations)) {
1098
- const rel = relMeta as any;
1099
- if (rel.where) {
1100
- console.log(`[MODEL_QUERY_DEBUG] relation="${relName}" getter=${rel.getter ?? 'NONE'} where=${JSON.stringify(rel.where)}`);
1101
- }
1102
- }
1103
-
1104
1172
  const result = await perspective.modelQuery(className, queryJson, shapeJson);
1105
1173
 
1106
1174
  // Convert JSON instances to model class instances, recursively constructing
@@ -1111,32 +1179,9 @@ export class Ad4mModel {
1111
1179
 
1112
1180
  // Resolve non-literal expressions (e.g. file languages where the stored
1113
1181
  // value is a content-addressed hash that must be fetched from the language
1114
- // runtime). The Rust endpoint returns raw target URIs; we resolve them here.
1115
- const propsMeta = getPropertiesMetadata(this as any);
1116
- const resolveProps = Object.entries(propsMeta).filter(
1117
- ([, opts]: [string, any]) =>
1118
- opts.resolveLanguage != null &&
1119
- opts.resolveLanguage !== 'literal',
1120
- );
1121
- if (resolveProps.length > 0) {
1122
- await Promise.all(
1123
- instances.map(async (inst: any) => {
1124
- for (const [propName, opts] of resolveProps) {
1125
- const val = inst[propName];
1126
- if (typeof val !== 'string' || !val || val.startsWith('literal:')) continue;
1127
- try {
1128
- const expression = await perspective.getExpression(val);
1129
- if (expression) {
1130
- let resolved: any;
1131
- try { resolved = JSON.parse(expression.data); } catch { resolved = expression.data; }
1132
- const transform = (opts as any).transform;
1133
- inst[propName] = typeof transform === 'function' ? transform(resolved) : resolved;
1134
- }
1135
- } catch (_) { /* resolution failed — keep raw value */ }
1136
- }
1137
- }),
1138
- );
1139
- }
1182
+ // runtime). The Rust endpoint may return either a raw target URI (string)
1183
+ // or an already-resolved FileData object — both cases are handled here.
1184
+ await (this as any).resolveNonLiteralProps(perspective, instances);
1140
1185
 
1141
1186
  // Take snapshots for dirty tracking
1142
1187
  const snapshotRelations = queryInput.include;
@@ -391,8 +391,15 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
391
391
  return (ctor as any).parseModelResult(this.perspective, raw, this.queryParams.include, this.queryParams.properties);
392
392
  };
393
393
 
394
- // Parse initial results
395
- const initialResults = parseResults(initialModelResult);
394
+ // Resolve non-literal (file-language) properties — handles both raw URI strings
395
+ // and already-resolved FileData objects returned by the Rust executor.
396
+ const resolveAndReturn = async (instances: T[]): Promise<T[]> => {
397
+ await (ctor as any).resolveNonLiteralProps(this.perspective, instances);
398
+ return instances;
399
+ };
400
+
401
+ // Parse initial results (with non-literal resolution)
402
+ const initialResults = await resolveAndReturn(parseResults(initialModelResult));
396
403
 
397
404
  // Track last emitted result fingerprint to suppress duplicate callbacks
398
405
  let lastResultFingerprint: string | null = null;
@@ -409,16 +416,15 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
409
416
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(
410
417
  subscriptionId,
411
418
  (rawResult: any) => {
412
- // Skip delayed #init# messages — initial data was already returned
413
- // synchronously from modelSubscribe(). Late init messages contain stale
414
- // data that would overwrite real subscription updates.
415
- if (rawResult && rawResult.isInit) return;
416
419
  try {
417
- const results = parseResults(rawResult);
418
- const fp = buildFingerprint(results);
419
- if (fp === lastResultFingerprint) return;
420
- lastResultFingerprint = fp;
421
- callback(results);
420
+ resolveAndReturn(parseResults(rawResult)).then((results) => {
421
+ const fp = buildFingerprint(results);
422
+ if (fp === lastResultFingerprint) return;
423
+ lastResultFingerprint = fp;
424
+ callback(results);
425
+ }).catch((e) => {
426
+ console.error('Model subscription update resolve error:', e);
427
+ });
422
428
  } catch (e) {
423
429
  console.error('Model subscription update parse error:', e);
424
430
  }
@@ -537,7 +543,6 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
537
543
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(
538
544
  subscriptionId,
539
545
  (rawResult: any) => {
540
- if (rawResult && rawResult.isInit) return;
541
546
  try {
542
547
  callback(parseCount(rawResult));
543
548
  } catch (e) {
@@ -674,7 +679,6 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
674
679
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(
675
680
  subscriptionId,
676
681
  (rawResult: any) => {
677
- if (rawResult && rawResult.isInit) return;
678
682
  processResults().catch(e => console.error('Paginate subscription error:', e));
679
683
  },
680
684
  );
@@ -160,7 +160,7 @@ export type GetOptions = Pick<Query, 'include' | 'properties'>;
160
160
  // Result types
161
161
  // ---------------------------------------------------------------------------
162
162
 
163
- export type AllInstancesResult = { AllInstances: Ad4mModel[]; TotalCount?: number; isInit?: boolean };
163
+ export type AllInstancesResult = { AllInstances: Ad4mModel[]; TotalCount?: number };
164
164
  export type ResultsWithTotalCount<T> = { results: T[]; totalCount?: number };
165
165
  export type PaginationResult<T> = { results: T[]; totalCount?: number; pageSize: number; pageNumber: number };
166
166
 
@@ -16,14 +16,8 @@ export type UuidCallback = (uuid: string) => null
16
16
  export type LinkCallback = (link: LinkExpression) => null
17
17
  export type SyncStateChangeCallback = (state: PerspectiveState) => null
18
18
 
19
- function normalizeQueryResult(raw: unknown, errorContext: string): { result: AllInstancesResult; isInit: boolean } {
19
+ function normalizeQueryResult(raw: unknown, errorContext: string): AllInstancesResult {
20
20
  let finalResult: unknown = raw
21
- let isInit = false
22
-
23
- if (typeof finalResult === 'string' && finalResult.startsWith('#init#')) {
24
- finalResult = finalResult.substring(6)
25
- isInit = true
26
- }
27
21
 
28
22
  if (typeof finalResult === 'string') {
29
23
  try {
@@ -33,11 +27,7 @@ function normalizeQueryResult(raw: unknown, errorContext: string): { result: All
33
27
  }
34
28
  }
35
29
 
36
- if (isInit && typeof finalResult === 'object' && finalResult !== null) {
37
- (finalResult as Record<string, unknown>).isInit = true
38
- }
39
-
40
- return { result: finalResult as AllInstancesResult, isInit }
30
+ return finalResult as AllInstancesResult
41
31
  }
42
32
 
43
33
  export class PerspectiveClient {
@@ -131,13 +121,13 @@ export class PerspectiveClient {
131
121
  return JSON.parse(result)
132
122
  }
133
123
 
134
- async subscribeQuery(uuid: string, query: string): Promise<{ subscriptionId: string, result: AllInstancesResult, isInit?: boolean }> {
124
+ async subscribeQuery(uuid: string, query: string): Promise<{ subscriptionId: string, result: AllInstancesResult }> {
135
125
  const response = await this.#apiClient.call<{ subscriptionId: string, result: unknown }>(
136
126
  'perspective.subscribeQuery', { uuid, query }
137
127
  )
138
128
  const { subscriptionId, result } = response
139
- const normalized = normalizeQueryResult(result, 'Error parsing subscribeQuery result:')
140
- return { subscriptionId, result: normalized.result, isInit: normalized.isInit }
129
+ const parsed = normalizeQueryResult(result, 'Error parsing subscribeQuery result:')
130
+ return { subscriptionId, result: parsed }
141
131
  }
142
132
 
143
133
  async perspectiveKeepAliveQuery(uuid: string, subscriptionId: string): Promise<boolean> {
@@ -161,8 +151,8 @@ export class PerspectiveClient {
161
151
  const eventSubscriptionId = event.subscriptionId || event.subscription_id
162
152
  if (eventSubscriptionId !== subscriptionId) return
163
153
 
164
- const normalized = normalizeQueryResult(event.result, 'Error parsing query subscription:')
165
- onData(normalized.result)
154
+ const parsed = normalizeQueryResult(event.result, 'Error parsing query subscription:')
155
+ onData(parsed)
166
156
  }
167
157
  )
168
158
  this.#querySubscriptionUnsubscribers.set(subscriptionId, unsub)