@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.
@@ -3,13 +3,54 @@ import { Link } from "../links/Links";
3
3
  import { LinkQuery } from "../perspectives/LinkQuery";
4
4
  import { makeRandomId } from "./util";
5
5
  import { getPropertiesMetadata, getRelationsMetadata, buildConformanceFilter, setPropertyRegistryEntry, setRelationRegistryEntry, Model } from "./decorators";
6
- import { compileWhereClause } from "./query-utils";
7
6
  import { resolveParentPredicate } from "./query-common";
8
7
  import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
9
8
  import { buildSPARQLQuery } from "./query-sparql";
10
9
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
11
10
  import { normalizeValue, } from "./hydration";
12
11
  // ---------------------------------------------------------------------------
12
+ // Default decoder for file-storage (non-literal resolveLanguage) properties
13
+ // ---------------------------------------------------------------------------
14
+ /**
15
+ * When the Rust executor resolves a non-literal expression it may return a
16
+ * `FileData`-shaped object (`{ data_base64, file_type, ... }`) rather than a
17
+ * raw URI string. If the model class has no custom `transform` registered
18
+ * (e.g. it was synthesised from a SHACL shape at runtime) we still want to
19
+ * decode the content rather than passing raw `FileData` to callers.
20
+ *
21
+ * Decoding rules (mirrors the JS `decodeFileAsJson` / `decodeFileAsString` helpers):
22
+ * - `application/json` (default when `file_type` is absent) → JSON.parse
23
+ * - anything else → raw decoded string
24
+ *
25
+ * If `resolved` is not a `FileData` object the value is returned unchanged so
26
+ * that callers can use this as a safe unconditional fallback.
27
+ */
28
+ function defaultFileDecode(resolved) {
29
+ if (resolved !== null &&
30
+ typeof resolved === 'object' &&
31
+ 'data_base64' in resolved) {
32
+ const fd = resolved;
33
+ let raw;
34
+ try {
35
+ raw = atob(fd.data_base64);
36
+ }
37
+ catch {
38
+ return resolved; // malformed base64 — keep as-is
39
+ }
40
+ const isJson = !fd.file_type || fd.file_type === 'application/json';
41
+ if (isJson) {
42
+ try {
43
+ return JSON.parse(raw);
44
+ }
45
+ catch {
46
+ return raw;
47
+ }
48
+ }
49
+ return raw;
50
+ }
51
+ return resolved;
52
+ }
53
+ // ---------------------------------------------------------------------------
13
54
  // Helpers for Rust-side include resolution
14
55
  // ---------------------------------------------------------------------------
15
56
  /**
@@ -761,7 +802,11 @@ export class Ad4mModel {
761
802
  const allRelMeta = getRelationsMetadata(this);
762
803
  enrichShapeForIncludes(metadata, query.include, allRelMeta);
763
804
  }
764
- // Pre-compute conformance getters (with where-clause support)
805
+ // Pre-compute conformance getters for Rust-side evaluation.
806
+ // Where clauses are NOT compiled into getter SPARQL because stored
807
+ // property values are signed expression envelopes (literal:json:...),
808
+ // not simple literal:string:X values. Instead, where clauses are
809
+ // attached as metadata for Rust-side post-evaluation filtering.
765
810
  {
766
811
  const allRelMeta = getRelationsMetadata(this);
767
812
  for (const [relName, relMeta] of Object.entries(metadata.relations)) {
@@ -774,43 +819,31 @@ export class Ad4mModel {
774
819
  try {
775
820
  const TargetClass = meta.target();
776
821
  const filter = buildConformanceFilter(meta.predicate, TargetClass);
777
- // Compile where clauses to SPARQL when all target properties use
778
- // literal encoding (literal:string:X etc.) which is SPARQL-matchable.
779
- // Properties with a non-literal resolveLanguage store expression hashes
780
- // that can't be matched by value in SPARQL.
781
- let whereConditions = [];
822
+ if (filter) {
823
+ rel.getter = filter.getter;
824
+ }
825
+ // Attach where-clause metadata for Rust-side post-getter filtering
782
826
  if (rel.where) {
783
827
  try {
784
828
  const targetMetadata = TargetClass.getModelMetadata?.() ?? null;
785
- let allSparqlFilterable = true;
786
829
  if (targetMetadata) {
830
+ const predicates = {};
787
831
  for (const propName of Object.keys(rel.where)) {
788
832
  if (['id', 'author', 'timestamp'].includes(propName))
789
833
  continue;
790
834
  const propMeta = targetMetadata.properties[propName];
791
- if (propMeta?.resolveLanguage && propMeta.resolveLanguage !== 'literal') {
792
- allSparqlFilterable = false;
793
- break;
835
+ if (propMeta?.predicate) {
836
+ predicates[propName] = propMeta.predicate;
794
837
  }
795
838
  }
796
- }
797
- if (allSparqlFilterable) {
798
- whereConditions = compileWhereClause(rel.where, targetMetadata);
839
+ if (Object.keys(predicates).length > 0) {
840
+ rel.whereFilter = rel.where;
841
+ rel.wherePredicates = predicates;
842
+ }
799
843
  }
800
844
  }
801
845
  catch (_) { }
802
846
  }
803
- if (filter) {
804
- let getter = filter.getter;
805
- if (whereConditions.length > 0) {
806
- getter = getter.replace(/ \}$/, ` ${whereConditions.join(' ')} }`);
807
- }
808
- rel.getter = getter;
809
- }
810
- else if (whereConditions.length > 0) {
811
- const escapedPred = meta.predicate.replace(/[<>"{}|\\^`\u0000-\u0020]/g, '');
812
- rel.getter = `SELECT ?target WHERE { <Base> <${escapedPred}> ?target . ${whereConditions.join(' ')} }`;
813
- }
814
847
  }
815
848
  catch (_) { }
816
849
  }
@@ -833,6 +866,55 @@ export class Ad4mModel {
833
866
  return [];
834
867
  return arr.map((json) => jsonToModelInstance(this, perspective, json, include, properties));
835
868
  }
869
+ /**
870
+ * Resolve non-literal (file-language) properties on an array of already-constructed
871
+ * model instances. Handles two cases:
872
+ *
873
+ * 1. The Rust executor returned a raw URI string → fetch via `getExpression` then apply transform.
874
+ * 2. The Rust executor already resolved the expression and returned a `FileData` object
875
+ * (happens when the perspective backend eagerly fetches file content) → apply transform
876
+ * (or `defaultFileDecode` if no transform is registered on the class, e.g. for SHACL-
877
+ * synthesised model classes).
878
+ *
879
+ * Extracted as a public static so `ModelQueryBuilder.subscribe()` can reuse it without
880
+ * duplicating logic or introducing a circular dependency.
881
+ * @internal
882
+ */
883
+ static async resolveNonLiteralProps(perspective, instances) {
884
+ const propsMeta = getPropertiesMetadata(this);
885
+ const resolveProps = Object.entries(propsMeta).filter(([, opts]) => opts.resolveLanguage != null &&
886
+ opts.resolveLanguage !== 'literal');
887
+ if (resolveProps.length === 0)
888
+ return;
889
+ await Promise.all(instances.map(async (inst) => {
890
+ for (const [propName, opts] of resolveProps) {
891
+ const val = inst[propName];
892
+ const transform = opts.transform;
893
+ const applyTransform = (resolved) => typeof transform === 'function' ? transform(resolved) : defaultFileDecode(resolved);
894
+ if (typeof val === 'string' && val && !val.startsWith('literal:')) {
895
+ // Case 1: raw URI — fetch from language runtime
896
+ try {
897
+ const expression = await perspective.getExpression(val);
898
+ if (expression) {
899
+ let resolved;
900
+ try {
901
+ resolved = JSON.parse(expression.data);
902
+ }
903
+ catch {
904
+ resolved = expression.data;
905
+ }
906
+ inst[propName] = applyTransform(resolved);
907
+ }
908
+ }
909
+ catch (_) { /* resolution failed — keep raw value */ }
910
+ }
911
+ else if (val !== null && val !== undefined && typeof val === 'object') {
912
+ // Case 2: already resolved by Rust — apply transform / default decode
913
+ inst[propName] = applyTransform(val);
914
+ }
915
+ }
916
+ }));
917
+ }
836
918
  // instancesFromQueryResult — removed (superseded by Rust executeModelQuery pipeline)
837
919
  /**
838
920
  * Execute a model query via the executor-side endpoint.
@@ -943,45 +1025,33 @@ export class Ad4mModel {
943
1025
  try {
944
1026
  const TargetClass = meta.target();
945
1027
  const filter = buildConformanceFilter(meta.predicate, TargetClass);
946
- // Compile where clauses to SPARQL when all target properties use
947
- // literal encoding (literal:string:X etc.) which is SPARQL-matchable.
948
- // Properties with a non-literal resolveLanguage store expression hashes
949
- // that can't be matched by value in SPARQL.
950
- let whereConditions = [];
1028
+ if (filter) {
1029
+ rel.getter = filter.getter;
1030
+ }
1031
+ // Attach where-clause metadata for Rust-side post-getter filtering.
1032
+ // Property values are signed expression envelopes (literal:json:...)
1033
+ // and cannot be matched by SPARQL FILTER on the raw IRI.
951
1034
  if (rel.where) {
952
1035
  try {
953
1036
  const targetMetadata = TargetClass.getModelMetadata?.() ?? null;
954
- let allSparqlFilterable = true;
955
1037
  if (targetMetadata) {
1038
+ const predicates = {};
956
1039
  for (const propName of Object.keys(rel.where)) {
957
1040
  if (['id', 'author', 'timestamp'].includes(propName))
958
1041
  continue;
959
1042
  const propMeta = targetMetadata.properties[propName];
960
- if (propMeta?.resolveLanguage && propMeta.resolveLanguage !== 'literal') {
961
- allSparqlFilterable = false;
962
- break;
1043
+ if (propMeta?.predicate) {
1044
+ predicates[propName] = propMeta.predicate;
963
1045
  }
964
1046
  }
965
- }
966
- if (allSparqlFilterable) {
967
- whereConditions = compileWhereClause(rel.where, targetMetadata);
1047
+ if (Object.keys(predicates).length > 0) {
1048
+ rel.whereFilter = rel.where;
1049
+ rel.wherePredicates = predicates;
1050
+ }
968
1051
  }
969
1052
  }
970
1053
  catch (_) { /* target metadata unavailable */ }
971
1054
  }
972
- if (filter) {
973
- let getter = filter.getter;
974
- if (whereConditions.length > 0) {
975
- // Append where conditions before the closing }
976
- getter = getter.replace(/ \}$/, ` ${whereConditions.join(' ')} }`);
977
- }
978
- rel.getter = getter;
979
- }
980
- else if (whereConditions.length > 0) {
981
- // No conformance filter but where clause exists — build getter from where alone
982
- const escapedPred = meta.predicate.replace(/[<>"{}|\\^`\u0000-\u0020]/g, '');
983
- rel.getter = `SELECT ?target WHERE { <Base> <${escapedPred}> ?target . ${whereConditions.join(' ')} }`;
984
- }
985
1055
  }
986
1056
  catch (e) {
987
1057
  // Target class may not be available; skip silently
@@ -993,13 +1063,6 @@ export class Ad4mModel {
993
1063
  // the TS decorators are the definitive source of truth.
994
1064
  const shapeJson = JSON.stringify(metadata);
995
1065
  const queryJson = JSON.stringify(queryInput);
996
- // TEMP DEBUG: Log getters with where-clause filters to diagnose CI failure
997
- for (const [relName, relMeta] of Object.entries(metadata.relations)) {
998
- const rel = relMeta;
999
- if (rel.where) {
1000
- console.log(`[MODEL_QUERY_DEBUG] relation="${relName}" getter=${rel.getter ?? 'NONE'} where=${JSON.stringify(rel.where)}`);
1001
- }
1002
- }
1003
1066
  const result = await perspective.modelQuery(className, queryJson, shapeJson);
1004
1067
  // Convert JSON instances to model class instances, recursively constructing
1005
1068
  // class instances for any included relations resolved by Rust.
@@ -1008,34 +1071,9 @@ export class Ad4mModel {
1008
1071
  });
1009
1072
  // Resolve non-literal expressions (e.g. file languages where the stored
1010
1073
  // value is a content-addressed hash that must be fetched from the language
1011
- // runtime). The Rust endpoint returns raw target URIs; we resolve them here.
1012
- const propsMeta = getPropertiesMetadata(this);
1013
- const resolveProps = Object.entries(propsMeta).filter(([, opts]) => opts.resolveLanguage != null &&
1014
- opts.resolveLanguage !== 'literal');
1015
- if (resolveProps.length > 0) {
1016
- await Promise.all(instances.map(async (inst) => {
1017
- for (const [propName, opts] of resolveProps) {
1018
- const val = inst[propName];
1019
- if (typeof val !== 'string' || !val || val.startsWith('literal:'))
1020
- continue;
1021
- try {
1022
- const expression = await perspective.getExpression(val);
1023
- if (expression) {
1024
- let resolved;
1025
- try {
1026
- resolved = JSON.parse(expression.data);
1027
- }
1028
- catch {
1029
- resolved = expression.data;
1030
- }
1031
- const transform = opts.transform;
1032
- inst[propName] = typeof transform === 'function' ? transform(resolved) : resolved;
1033
- }
1034
- }
1035
- catch (_) { /* resolution failed — keep raw value */ }
1036
- }
1037
- }));
1038
- }
1074
+ // runtime). The Rust endpoint may return either a raw target URI (string)
1075
+ // or an already-resolved FileData object — both cases are handled here.
1076
+ await this.resolveNonLiteralProps(perspective, instances);
1039
1077
  // Take snapshots for dirty tracking
1040
1078
  const snapshotRelations = queryInput.include;
1041
1079
  for (const inst of instances) {
@@ -351,8 +351,14 @@ export class ModelQueryBuilder {
351
351
  const parseResults = (raw) => {
352
352
  return ctor.parseModelResult(this.perspective, raw, this.queryParams.include, this.queryParams.properties);
353
353
  };
354
- // Parse initial results
355
- const initialResults = parseResults(initialModelResult);
354
+ // Resolve non-literal (file-language) properties — handles both raw URI strings
355
+ // and already-resolved FileData objects returned by the Rust executor.
356
+ const resolveAndReturn = async (instances) => {
357
+ await ctor.resolveNonLiteralProps(this.perspective, instances);
358
+ return instances;
359
+ };
360
+ // Parse initial results (with non-literal resolution)
361
+ const initialResults = await resolveAndReturn(parseResults(initialModelResult));
356
362
  // Track last emitted result fingerprint to suppress duplicate callbacks
357
363
  let lastResultFingerprint = null;
358
364
  const buildFingerprint = (results) => {
@@ -364,18 +370,16 @@ export class ModelQueryBuilder {
364
370
  // Listen for subscription updates via the same GraphQL subscription channel.
365
371
  // When Rust re-runs the model query and finds changed results, it pushes them.
366
372
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(subscriptionId, (rawResult) => {
367
- // Skip delayed #init# messages — initial data was already returned
368
- // synchronously from modelSubscribe(). Late init messages contain stale
369
- // data that would overwrite real subscription updates.
370
- if (rawResult && rawResult.isInit)
371
- return;
372
373
  try {
373
- const results = parseResults(rawResult);
374
- const fp = buildFingerprint(results);
375
- if (fp === lastResultFingerprint)
376
- return;
377
- lastResultFingerprint = fp;
378
- callback(results);
374
+ resolveAndReturn(parseResults(rawResult)).then((results) => {
375
+ const fp = buildFingerprint(results);
376
+ if (fp === lastResultFingerprint)
377
+ return;
378
+ lastResultFingerprint = fp;
379
+ callback(results);
380
+ }).catch((e) => {
381
+ console.error('Model subscription update resolve error:', e);
382
+ });
379
383
  }
380
384
  catch (e) {
381
385
  console.error('Model subscription update parse error:', e);
@@ -475,8 +479,6 @@ export class ModelQueryBuilder {
475
479
  };
476
480
  const initialCount = parseCount(initialModelResult);
477
481
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(subscriptionId, (rawResult) => {
478
- if (rawResult && rawResult.isInit)
479
- return;
480
482
  try {
481
483
  callback(parseCount(rawResult));
482
484
  }
@@ -590,8 +592,6 @@ export class ModelQueryBuilder {
590
592
  callback({ results, totalCount, pageSize, pageNumber });
591
593
  };
592
594
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(subscriptionId, (rawResult) => {
593
- if (rawResult && rawResult.isInit)
594
- return;
595
595
  processResults().catch(e => console.error('Paginate subscription error:', e));
596
596
  });
597
597
  let keepaliveFailures = 0;
@@ -151,7 +151,6 @@ export type GetOptions = Pick<Query, 'include' | 'properties'>;
151
151
  export type AllInstancesResult = {
152
152
  AllInstances: Ad4mModel[];
153
153
  TotalCount?: number;
154
- isInit?: boolean;
155
154
  };
156
155
  export type ResultsWithTotalCount<T> = {
157
156
  results: T[];
@@ -31,7 +31,6 @@ export declare class PerspectiveClient {
31
31
  subscribeQuery(uuid: string, query: string): Promise<{
32
32
  subscriptionId: string;
33
33
  result: AllInstancesResult;
34
- isInit?: boolean;
35
34
  }>;
36
35
  perspectiveKeepAliveQuery(uuid: string, subscriptionId: string): Promise<boolean>;
37
36
  perspectiveDisposeQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean>;
@@ -15,11 +15,6 @@ import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
15
15
  import { PerspectiveProxy } from './PerspectiveProxy';
16
16
  function normalizeQueryResult(raw, errorContext) {
17
17
  let finalResult = raw;
18
- let isInit = false;
19
- if (typeof finalResult === 'string' && finalResult.startsWith('#init#')) {
20
- finalResult = finalResult.substring(6);
21
- isInit = true;
22
- }
23
18
  if (typeof finalResult === 'string') {
24
19
  try {
25
20
  finalResult = JSON.parse(finalResult);
@@ -28,10 +23,7 @@ function normalizeQueryResult(raw, errorContext) {
28
23
  console.error(errorContext, e);
29
24
  }
30
25
  }
31
- if (isInit && typeof finalResult === 'object' && finalResult !== null) {
32
- finalResult.isInit = true;
33
- }
34
- return { result: finalResult, isInit };
26
+ return finalResult;
35
27
  }
36
28
  export class PerspectiveClient {
37
29
  constructor(baseUrl, token, subscribe = true, sharedApiClient) {
@@ -122,8 +114,8 @@ export class PerspectiveClient {
122
114
  async subscribeQuery(uuid, query) {
123
115
  const response = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.subscribeQuery', { uuid, query });
124
116
  const { subscriptionId, result } = response;
125
- const normalized = normalizeQueryResult(result, 'Error parsing subscribeQuery result:');
126
- return { subscriptionId, result: normalized.result, isInit: normalized.isInit };
117
+ const parsed = normalizeQueryResult(result, 'Error parsing subscribeQuery result:');
118
+ return { subscriptionId, result: parsed };
127
119
  }
128
120
  async perspectiveKeepAliveQuery(uuid, subscriptionId) {
129
121
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.keepAliveQuery', { uuid, subscriptionId });
@@ -139,8 +131,8 @@ export class PerspectiveClient {
139
131
  const eventSubscriptionId = event.subscriptionId || event.subscription_id;
140
132
  if (eventSubscriptionId !== subscriptionId)
141
133
  return;
142
- const normalized = normalizeQueryResult(event.result, 'Error parsing query subscription:');
143
- onData(normalized.result);
134
+ const parsed = normalizeQueryResult(event.result, 'Error parsing query subscription:');
135
+ onData(parsed);
144
136
  });
145
137
  __classPrivateFieldGet(this, _PerspectiveClient_querySubscriptionUnsubscribers, "f").set(subscriptionId, unsub);
146
138
  return unsub;
@@ -154,9 +154,6 @@ export class QuerySubscriptionProxy {
154
154
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_initResolve, undefined, "f"); // Prevent double-resolve
155
155
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_initReject, undefined, "f");
156
156
  }
157
- // Skip duplicate init messages
158
- if (updateResult.isInit && __classPrivateFieldGet(this, _QuerySubscriptionProxy_latestResult, "f"))
159
- return;
160
157
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_latestResult, updateResult, "f");
161
158
  __classPrivateFieldGet(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_notifyCallbacks).call(this, updateResult);
162
159
  }), "f");
package/package.json CHANGED
@@ -5,12 +5,6 @@
5
5
  "module": "lib/index.js",
6
6
  "types": "lib/src/index.d.ts",
7
7
  "type": "module",
8
- "scripts": {
9
- "build": "patch-package && tsc && pnpm run bundle",
10
- "bundle": "rollup -c rollup.config.js",
11
- "test": "jest --forceExit",
12
- "generate:api-types": "cd ../rust-executor && TS_RS_EXPORT_DIR=../core/src/generated/api/ cargo test --lib 2>/dev/null && echo \"API types generated to core/src/generated/api/\""
13
- },
14
8
  "repository": {
15
9
  "type": "git",
16
10
  "url": "git+https://github.com/coasys/ad4m.git"
@@ -54,8 +48,11 @@
54
48
  "ws": "8.13.0"
55
49
  },
56
50
  "patchedDependencies": {},
57
- "pnpm": {
58
- "patchedDependencies": {}
59
- },
60
- "version": "0.13.0-test-5"
61
- }
51
+ "version": "0.13.0-test-7",
52
+ "scripts": {
53
+ "build": "patch-package && tsc && pnpm run bundle",
54
+ "bundle": "rollup -c rollup.config.js",
55
+ "test": "jest --forceExit",
56
+ "generate:api-types": "cd ../rust-executor && TS_RS_EXPORT_DIR=../core/src/generated/api/ cargo test --lib 2>/dev/null && echo \"API types generated to core/src/generated/api/\""
57
+ }
58
+ }
@@ -148,9 +148,14 @@ const MOCK_RESPONSES: Record<string, RpcHandler> = {
148
148
  language: { address: 'lang://test' }, proof: { valid: true },
149
149
  };
150
150
  },
151
- 'expression.getMany': [
152
- { author: 'did:test:1', timestamp: '2023-01-01', data: { type: 'test' }, language: { address: 'lang://test' }, proof: { valid: true } },
153
- ],
151
+ 'expression.getMany': (p: Record<string, unknown>) => {
152
+ // Return one result per URL (aligned by index), matching real API behavior
153
+ const urls = (p.urls || []) as string[];
154
+ return urls.map((url: string) => ({
155
+ author: 'did:test:1', timestamp: '2023-01-01', data: { type: 'test' },
156
+ language: { address: 'lang://test' }, proof: { valid: true },
157
+ }));
158
+ },
154
159
  'expression.create': 'Qm-expression-hash',
155
160
  'expression.interactions': [{ label: 'interact1', name: 'doSomething', parameters: [] }],
156
161
  'expression.interact': 'interaction-result',
@@ -348,6 +353,9 @@ afterAll(() => {
348
353
  beforeEach(() => {
349
354
  lastRpcCall = null;
350
355
  MockWebSocket.instances = [];
356
+ // Clear caches to prevent cross-test interference
357
+ ad4m.agent.clearByDidCache();
358
+ ad4m.expression.clearCache();
351
359
  });
352
360
 
353
361
  // ===================== AGENT TESTS =====================
@@ -857,7 +865,9 @@ describe('ExpressionClient', () => {
857
865
 
858
866
  test('getMany() returns multiple expressions', async () => {
859
867
  const exprs = await ad4m.expression.getMany(['url1', 'url2']);
860
- expect(exprs).toHaveLength(1);
868
+ expect(exprs).toHaveLength(2);
869
+ expect(exprs[0].author).toBe('did:test:1');
870
+ expect(exprs[1].author).toBe('did:test:1');
861
871
  });
862
872
 
863
873
  test('getRaw() returns raw expression', async () => {
package/src/Ad4mClient.ts CHANGED
@@ -90,8 +90,9 @@ export class Ad4mClient {
90
90
  this.#agentClient.subscribeAppsChanged()
91
91
  }
92
92
 
93
- /** Close all event connections */
93
+ /** Close all event connections and clear in-memory caches */
94
94
  close(): void {
95
+ this.#agentClient.clearByDidCache()
95
96
  this.#apiClient.closeAll()
96
97
  }
97
98
  }
@@ -14,6 +14,7 @@ import { AgentStatus } from "./AgentStatus";
14
14
  import { LinkMutations, LinkExpression } from "../links/Links";
15
15
  import { PerspectiveClient } from "../perspectives/PerspectiveClient";
16
16
  import { VerificationRequestResult } from "../runtime/RuntimeTypes";
17
+ import { PersistentCache, createPersistentCache } from "../cache/PersistentCache";
17
18
  import type {
18
19
  GenerateAgentRequest,
19
20
  ImportAgentRequest,
@@ -48,6 +49,16 @@ export class AgentClient {
48
49
  #computeLogUpdatedCallbacks: ComputeLogUpdatedCallback[];
49
50
  #unsubscribers: (() => void)[];
50
51
 
52
+ // ── byDID cache ────────────────────────────────────────────────────
53
+ // L1: in-memory promise cache with timestamps for TTL
54
+ #memCache = new Map<string, { promise: Promise<Agent>; ts: number }>();
55
+ // L2: persistent cache (IndexedDB in browser, NullCache in Node)
56
+ #persistent: PersistentCache<Agent>;
57
+ // Self-DID for event-driven invalidation (no TTL for own profile)
58
+ #selfDid: string | null = null;
59
+ /** TTL for remote (non-self) agent profiles in L1 cache (ms). */
60
+ static REMOTE_AGENT_TTL_MS = 5 * 60_000; // 5 minutes
61
+
51
62
  constructor(baseUrl: string, token?: string, subscribe: boolean = true, sharedApiClient?: ApiClient) {
52
63
  this.#baseUrl = baseUrl;
53
64
  this.#token = token;
@@ -58,6 +69,7 @@ export class AgentClient {
58
69
  this.#hostingUserInfoChangedCallbacks = [];
59
70
  this.#computeLogUpdatedCallbacks = [];
60
71
  this.#unsubscribers = [];
72
+ this.#persistent = createPersistentCache<Agent>('ad4m-agent-cache', 'agents');
61
73
 
62
74
  if (subscribe) {
63
75
  this.subscribeAgentUpdated();
@@ -99,7 +111,66 @@ export class AgentClient {
99
111
  }
100
112
 
101
113
  async byDID(did: string): Promise<Agent> {
102
- return this.#apiClient.call<Agent>('agent.byDid', { did });
114
+ const now = Date.now();
115
+ const cached = this.#memCache.get(did);
116
+
117
+ if (cached) {
118
+ const isSelf = did === this.#selfDid;
119
+ // Self-DID: L1 always valid (event-driven invalidation)
120
+ // Remote DID: L1 valid within TTL
121
+ if (isSelf || (now - cached.ts) < AgentClient.REMOTE_AGENT_TTL_MS) {
122
+ return cached.promise;
123
+ }
124
+ }
125
+
126
+ // Deduplicate: store the promise immediately so concurrent calls share one RPC
127
+ const promise = (async () => {
128
+ // L2: check persistent cache before network
129
+ const persisted = await this.#persistent.get(did);
130
+ if (persisted) {
131
+ return persisted;
132
+ }
133
+
134
+ // L3: network fetch
135
+ const result = await this.#apiClient.call<Agent>('agent.byDid', { did });
136
+ this.#persistent.put(did, result); // fire-and-forget write to L2
137
+ return result;
138
+ })();
139
+
140
+ this.#memCache.set(did, { promise, ts: now });
141
+
142
+ // Clean up on failure so next call retries
143
+ promise.catch(() => {
144
+ if (this.#memCache.get(did)?.promise === promise) {
145
+ this.#memCache.delete(did);
146
+ }
147
+ });
148
+
149
+ return promise;
150
+ }
151
+
152
+ /**
153
+ * Set the current agent's own DID.
154
+ * The self-DID receives event-driven invalidation and is never TTL-expired.
155
+ */
156
+ setSelfDid(did: string): void {
157
+ this.#selfDid = did;
158
+ }
159
+
160
+ /**
161
+ * Invalidate a specific DID's cache entry in both L1 and L2.
162
+ */
163
+ invalidateByDid(did: string): void {
164
+ this.#memCache.delete(did);
165
+ this.#persistent.delete(did); // fire-and-forget
166
+ }
167
+
168
+ /**
169
+ * Clear the entire L1 (memory) byDID cache.
170
+ * L2 (IndexedDB) is preserved — agent data remains valid across sessions.
171
+ */
172
+ clearByDidCache(): void {
173
+ this.#memCache.clear();
103
174
  }
104
175
 
105
176
  async updatePublicPerspective(perspective: PerspectiveInput): Promise<Agent> {
@@ -175,7 +246,18 @@ export class AgentClient {
175
246
  subscribeAgentUpdated() {
176
247
  const unsub = this.#apiClient.subscribe((data) => {
177
248
  if (data.type === 'agent-updated') {
178
- this.#updatedCallbacks.forEach((cb) => cb((data.agent || data) as Agent));
249
+ const agent = (data.agent || data) as Agent;
250
+
251
+ // Update L1 and L2 cache from the event payload
252
+ if (agent.did) {
253
+ this.#memCache.set(agent.did, {
254
+ promise: Promise.resolve(agent),
255
+ ts: Date.now(),
256
+ });
257
+ this.#persistent.put(agent.did, agent); // fire-and-forget
258
+ }
259
+
260
+ this.#updatedCallbacks.forEach((cb) => cb(agent));
179
261
  }
180
262
  });
181
263
  this.#unsubscribers.push(unsub);