@coasys/ad4m 0.13.1-staging.13 → 0.13.1-staging.15

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 (75) hide show
  1. package/lib/index.cjs +571 -480
  2. package/lib/index.js +571 -476
  3. package/lib/src/agent/AgentClient.d.ts +9 -8
  4. package/lib/src/agent/AgentClient.js +46 -67
  5. package/lib/src/cache/KeyedCache.d.ts +51 -0
  6. package/lib/src/cache/KeyedCache.js +142 -0
  7. package/lib/src/expression/ExpressionClient.d.ts +14 -3
  8. package/lib/src/expression/ExpressionClient.js +49 -111
  9. package/lib/src/generated/api/ExpressionLookupError.d.ts +7 -0
  10. package/lib/src/generated/api/ExpressionLookupError.js +2 -0
  11. package/lib/src/generated/api/ExpressionManyEntry.d.ts +6 -0
  12. package/lib/src/generated/api/ExpressionManyEntry.js +1 -0
  13. package/lib/src/generated/api/FlowFiredEntry.d.ts +11 -0
  14. package/lib/src/generated/api/FlowFiredEntry.js +2 -0
  15. package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +3 -3
  16. package/lib/src/generated/api/RpcMethods.d.ts +4 -2
  17. package/lib/src/model/Ad4mModel.d.ts +26 -2
  18. package/lib/src/model/Ad4mModel.js +127 -83
  19. package/lib/src/model/ModelQueryBuilder.d.ts +3 -0
  20. package/lib/src/model/ModelQueryBuilder.js +42 -14
  21. package/lib/src/model/index.d.ts +0 -1
  22. package/lib/src/model/index.js +0 -1
  23. package/lib/src/model/query-common.d.ts +8 -0
  24. package/lib/src/model/query-common.js +12 -0
  25. package/lib/src/model/shacl-gen.js +2 -0
  26. package/lib/src/model/types.d.ts +12 -3
  27. package/lib/src/neighbourhood/SfuManager.d.ts +8 -1
  28. package/lib/src/neighbourhood/SfuManager.js +9 -2
  29. package/lib/src/perspectives/FlowModels.js +1 -1
  30. package/lib/src/perspectives/LiveQuery.d.ts +1 -1
  31. package/lib/src/perspectives/PerspectiveClient.d.ts +17 -6
  32. package/lib/src/perspectives/PerspectiveClient.js +83 -44
  33. package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -10
  34. package/lib/src/perspectives/PerspectiveProxy.js +31 -69
  35. package/lib/src/shacl/SHACLShape.d.ts +4 -0
  36. package/lib/src/shacl/SHACLShape.js +10 -0
  37. package/package.json +2 -2
  38. package/src/Ad4mClient.test.ts +17 -6
  39. package/src/agent/AgentClient.ts +46 -74
  40. package/src/cache/KeyedCache.test.ts +162 -0
  41. package/src/cache/KeyedCache.ts +179 -0
  42. package/src/cache/cache.test.ts +294 -71
  43. package/src/expression/ExpressionClient.ts +46 -131
  44. package/src/generated/api/ExpressionLookupError.ts +6 -0
  45. package/src/generated/api/ExpressionManyEntry.ts +8 -0
  46. package/src/generated/api/FlowFiredEntry.ts +11 -0
  47. package/src/generated/api/PerspectiveFlowFiredParams.ts +3 -3
  48. package/src/generated/api/RpcMethods.ts +4 -2
  49. package/src/model/Ad4mModel.test.ts +237 -43
  50. package/src/model/Ad4mModel.ts +134 -99
  51. package/src/model/ModelQueryBuilder.ts +41 -15
  52. package/src/model/count-result-type.test.ts +72 -0
  53. package/src/model/index.ts +0 -1
  54. package/src/model/query-common.ts +13 -0
  55. package/src/model/relation-filtering.test.ts +3 -5
  56. package/src/model/shacl-gen.ts +1 -0
  57. package/src/model/shacl-roundtrip.test.ts +28 -0
  58. package/src/model/types.ts +9 -3
  59. package/src/model/write-round-trips.test.ts +30 -6
  60. package/src/neighbourhood/SfuManager.test.ts +57 -5
  61. package/src/neighbourhood/SfuManager.ts +10 -2
  62. package/src/perspectives/FlowModels.ts +1 -1
  63. package/src/perspectives/LiveQuery.ts +1 -1
  64. package/src/perspectives/PerspectiveClient.test.ts +287 -0
  65. package/src/perspectives/PerspectiveClient.ts +101 -66
  66. package/src/perspectives/PerspectiveProxy.test.ts +6 -14
  67. package/src/perspectives/PerspectiveProxy.ts +33 -67
  68. package/src/perspectives/TextContent.test.ts +0 -16
  69. package/src/perspectives/shacl-rpc.test.ts +1 -1
  70. package/src/shacl/SHACLShape.test.ts +21 -0
  71. package/src/shacl/SHACLShape.ts +16 -0
  72. package/lib/src/model/query-cache.d.ts +0 -30
  73. package/lib/src/model/query-cache.js +0 -66
  74. package/src/model/query-cache.test.ts +0 -54
  75. package/src/model/query-cache.ts +0 -79
@@ -17,22 +17,41 @@ const MOCK_RESPONSES: Record<string, RpcHandler> = {
17
17
  'agent.get': { did: 'did:test:123', perspective: new Perspective(), directMessageLanguage: 'lang://dm' },
18
18
  'events.watch': true,
19
19
  'agent.status': { did: 'did:test:123', didDocument: 'doc', isInitialized: true, isUnlocked: true },
20
- 'agent.byDid': (p: Record<string, unknown>) => ({ did: p.did, perspective: new Perspective() }),
21
- 'expression.get': (p: Record<string, unknown>) => ({
22
- author: 'did:test:123', timestamp: '2024-01-01', data: `{"url":"${p.url}"}`,
23
- language: { address: 'lang://test' }, proof: { valid: true },
24
- }),
25
- 'expression.getMany': (p: Record<string, unknown>) => {
26
- const urls = (p.urls || []) as string[];
27
- return urls.map((url: string) => ({
20
+ // Like the executor: `did:test:missing` is unknown (null), `did:test:broken`
21
+ // fails, and one failing DID fails the whole `agent.byDIDs` call (#1213).
22
+ 'agent.byDid': (p: Record<string, unknown>) => {
23
+ if (p.did === 'did:test:missing') return null;
24
+ if (p.did === 'did:test:broken') throw { code: 500, message: `Failed to get agent ${p.did}: language failed` };
25
+ return { did: p.did, perspective: new Perspective() };
26
+ },
27
+ 'agent.byDIDs': (p: Record<string, unknown>) =>
28
+ (p.dids as string[]).map(did => (MOCK_RESPONSES['agent.byDid'] as (p: Record<string, unknown>) => unknown)({ did })),
29
+ // Like the executor: `.../missing` is unknown (null), `.../broken` fails, and
30
+ // `getMany` answers per URL what `get` does (a failure as `{ code, message }`).
31
+ 'expression.get': (p: Record<string, unknown>) => {
32
+ const url = p.url as string;
33
+ if (url.endsWith('/missing')) return null;
34
+ if (url.endsWith('/broken')) throw { code: 500, message: `Failed to get expression ${url}: language failed` };
35
+ return {
28
36
  author: 'did:test:123', timestamp: '2024-01-01', data: `{"url":"${url}"}`,
29
37
  language: { address: 'lang://test' }, proof: { valid: true },
30
- }));
38
+ };
31
39
  },
40
+ 'expression.getMany': (p: Record<string, unknown>) =>
41
+ ((p.urls || []) as string[]).map(url => {
42
+ try {
43
+ return (MOCK_RESPONSES['expression.get'] as (p: Record<string, unknown>) => unknown)({ url });
44
+ } catch (failure) {
45
+ return failure;
46
+ }
47
+ }),
32
48
  'expression.interact': () => 'ok',
33
49
  'expression.create': (p: Record<string, unknown>) => `lang://test/Qm-created-${Date.now()}`,
34
50
  };
35
51
 
52
+ /** How long the mock executor takes to answer a call; reset to 0 before each test. */
53
+ let replyDelayMs: (type: string, params: Record<string, unknown>) => number = () => 0;
54
+
36
55
  // ===================== MOCK WEBSOCKET =====================
37
56
 
38
57
  class MockWebSocket {
@@ -83,13 +102,18 @@ class MockWebSocket {
83
102
  return;
84
103
  }
85
104
 
86
- const result = typeof handler === 'function'
87
- ? (handler as (p: Record<string, unknown>) => unknown)(params)
88
- : handler;
105
+ let reply: Record<string, unknown>;
106
+ try {
107
+ reply = { id, result: typeof handler === 'function'
108
+ ? (handler as (p: Record<string, unknown>) => unknown)(params)
109
+ : handler };
110
+ } catch (error) {
111
+ reply = { id, error }; // a handler throws `{ code, message }` to fail the call
112
+ }
89
113
 
90
114
  setTimeout(() => {
91
- this.onmessage?.({ data: JSON.stringify({ id, result }) });
92
- }, 0);
115
+ this.onmessage?.({ data: JSON.stringify(reply) });
116
+ }, replyDelayMs(msgType, params));
93
117
  } catch { /* malformed JSON */ }
94
118
  }
95
119
 
@@ -133,6 +157,7 @@ afterAll(() => {
133
157
 
134
158
  beforeEach(() => {
135
159
  rpcCallLog = [];
160
+ replyDelayMs = () => 0;
136
161
  MockWebSocket.instances = [];
137
162
  // Fresh client per test to avoid cache leakage
138
163
  ad4m = new Ad4mClient('http://127.0.0.1:12000', 'test-token');
@@ -179,7 +204,7 @@ describe('AgentClient Cache', () => {
179
204
  expect(a3.did).toBe('did:test:dedup');
180
205
 
181
206
  // Only 1 RPC was actually made
182
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
207
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
183
208
  expect(byDidCalls).toHaveLength(1);
184
209
  });
185
210
 
@@ -191,7 +216,7 @@ describe('AgentClient Cache', () => {
191
216
  expect(a2.did).toBe('did:test:cached');
192
217
 
193
218
  // Only 1 RPC
194
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
219
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
195
220
  expect(byDidCalls).toHaveLength(1);
196
221
  });
197
222
 
@@ -199,10 +224,10 @@ describe('AgentClient Cache', () => {
199
224
  await ad4m.agent.byDID('did:test:one');
200
225
  await ad4m.agent.byDID('did:test:two');
201
226
 
202
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
227
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
203
228
  expect(byDidCalls).toHaveLength(2);
204
- expect(byDidCalls[0].params.did).toBe('did:test:one');
205
- expect(byDidCalls[1].params.did).toBe('did:test:two');
229
+ expect(byDidCalls[0].params.dids).toEqual(['did:test:one']);
230
+ expect(byDidCalls[1].params.dids).toEqual(['did:test:two']);
206
231
  });
207
232
 
208
233
  test('agent-updated event updates L1 cache', async () => {
@@ -227,7 +252,7 @@ describe('AgentClient Cache', () => {
227
252
  expect(a2.directMessageLanguage).toBe('lang://updated');
228
253
 
229
254
  // Should still be just 1 RPC (the second call was served from event-updated cache)
230
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
255
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
231
256
  expect(byDidCalls).toHaveLength(1);
232
257
  });
233
258
 
@@ -245,34 +270,66 @@ describe('AgentClient Cache', () => {
245
270
  await ad4m.agent.byDID('did:test:ttl');
246
271
 
247
272
  // Should have made 2 RPCs (first + re-fetch after TTL)
248
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
273
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
249
274
  expect(byDidCalls).toHaveLength(2);
250
275
  } finally {
251
276
  AgentClient.REMOTE_AGENT_TTL_MS = originalTTL;
252
277
  }
253
278
  });
254
279
 
255
- test('self-DID never expires from TTL', async () => {
280
+ test('the own DID expires after the TTL too', async () => {
281
+ // agent-updated only comes from this executor, so a profile changed
282
+ // through another executor of the same agent needs the TTL: every
283
+ // cached profile expires, the own one included.
256
284
  const originalTTL = AgentClient.REMOTE_AGENT_TTL_MS;
257
285
  AgentClient.REMOTE_AGENT_TTL_MS = 1; // 1ms
258
286
 
259
287
  try {
260
- ad4m.agent.setSelfDid('did:test:self');
261
- await ad4m.agent.byDID('did:test:self');
288
+ const own = (await ad4m.agent.status()).did!;
289
+ await ad4m.agent.byDID(own);
262
290
 
263
291
  // Wait longer than TTL
264
292
  await new Promise(r => setTimeout(r, 10));
265
293
 
266
- await ad4m.agent.byDID('did:test:self');
294
+ await ad4m.agent.byDID(own);
267
295
 
268
- // Should still be 1 RPC — self-DID is event-invalidated, not TTL-invalidated
269
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
270
- expect(byDidCalls).toHaveLength(1);
296
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
297
+ expect(byDidCalls).toHaveLength(2);
271
298
  } finally {
272
299
  AgentClient.REMOTE_AGENT_TTL_MS = originalTTL;
273
300
  }
274
301
  });
275
302
 
303
+ test('byDID() — one failing DID rejects only its own callers', async () => {
304
+ // What a lone byDID gives for each DID.
305
+ const lone = {
306
+ ok: await ad4m.agent.byDID('did:test:lone-ok'),
307
+ missing: await ad4m.agent.byDID('did:test:missing'),
308
+ broken: await ad4m.agent.byDID('did:test:broken').then(() => null, (e) => e),
309
+ };
310
+ expect(lone.ok.did).toBe('did:test:lone-ok');
311
+ expect(lone.missing).toBeNull();
312
+ expect(lone.broken).toMatchObject({ status: 500 });
313
+ rpcCallLog = [];
314
+
315
+ const [ok, missing, broken] = await Promise.allSettled([
316
+ ad4m.agent.byDID('did:test:batch-ok'),
317
+ ad4m.agent.byDID('did:test:missing'),
318
+ ad4m.agent.byDID('did:test:broken'),
319
+ ]);
320
+ expect(ok).toMatchObject({ status: 'fulfilled', value: { did: 'did:test:batch-ok' } });
321
+ expect(missing).toEqual({ status: 'fulfilled', value: null });
322
+ expect(broken).toMatchObject({ status: 'rejected', reason: { status: lone.broken.status, message: lone.broken.message } });
323
+
324
+ // One batch, then each DID of the failed batch alone.
325
+ expect(rpcCallLog.filter(c => c.type.startsWith('agent.by')).map(c => [c.type, c.params.dids ?? c.params.did])).toEqual([
326
+ ['agent.byDIDs', ['did:test:batch-ok', 'did:test:missing', 'did:test:broken']],
327
+ ['agent.byDid', 'did:test:batch-ok'],
328
+ ['agent.byDid', 'did:test:missing'],
329
+ ['agent.byDid', 'did:test:broken'],
330
+ ]);
331
+ });
332
+
276
333
  test('invalidateByDid() clears cache and forces re-fetch', async () => {
277
334
  await ad4m.agent.byDID('did:test:invalidate');
278
335
 
@@ -282,21 +339,21 @@ describe('AgentClient Cache', () => {
282
339
  // Next call should make a new RPC
283
340
  await ad4m.agent.byDID('did:test:invalidate');
284
341
 
285
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
342
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
286
343
  expect(byDidCalls).toHaveLength(2);
287
344
  });
288
345
 
289
346
  test('clearByDidCache() clears all L1 entries', async () => {
290
347
  await ad4m.agent.byDID('did:test:clear1');
291
348
  await ad4m.agent.byDID('did:test:clear2');
292
- expect(rpcCallLog.filter(c => c.type === 'agent.byDid')).toHaveLength(2);
349
+ expect(rpcCallLog.filter(c => c.type === 'agent.byDIDs')).toHaveLength(2);
293
350
 
294
351
  ad4m.agent.clearByDidCache();
295
352
 
296
353
  // Both should re-fetch
297
354
  await ad4m.agent.byDID('did:test:clear1');
298
355
  await ad4m.agent.byDID('did:test:clear2');
299
- expect(rpcCallLog.filter(c => c.type === 'agent.byDid')).toHaveLength(4);
356
+ expect(rpcCallLog.filter(c => c.type === 'agent.byDIDs')).toHaveLength(4);
300
357
  });
301
358
 
302
359
  test('byDID() RPC failure cleans up cache entry for retry', async () => {
@@ -325,7 +382,7 @@ describe('AgentClient Cache', () => {
325
382
  const agent = await ad4m.agent.byDID('did:test:fail');
326
383
  expect(agent.did).toBe('did:test:fail');
327
384
 
328
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
385
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
329
386
  expect(byDidCalls).toHaveLength(2);
330
387
  } finally {
331
388
  MOCK_RESPONSES['agent.byDid'] = origHandler;
@@ -333,8 +390,146 @@ describe('AgentClient Cache', () => {
333
390
  });
334
391
  });
335
392
 
393
+ // ===================== BATCHED LOOKUPS =====================
394
+
395
+ describe('Profile and expression lookups batch concurrent misses', () => {
396
+ const calls = (type: string) => rpcCallLog.filter(c => c.type === type);
397
+
398
+ test('20 concurrent byDID() calls for 5 DIDs make 1 RPC, with the results a single lookup gives', async () => {
399
+ const dids = ['did:test:b1', 'did:test:b2', 'did:test:b3', 'did:test:b4', 'did:test:b5'];
400
+ const requested = Array.from({ length: 20 }, (_, i) => dids[i % 5]);
401
+
402
+ const agents = await Promise.all(requested.map(did => ad4m.agent.byDID(did)));
403
+
404
+ expect(calls('agent.byDIDs')).toHaveLength(1);
405
+ expect(calls('agent.byDid')).toHaveLength(0);
406
+ expect([...(calls('agent.byDIDs')[0].params.dids as string[])].sort()).toEqual(dids);
407
+ // Golden: each result equals what one `agent.byDid` lookup of that DID returns.
408
+ const single = new Ad4mClient('http://127.0.0.1:12001', 'test-token');
409
+ for (let i = 0; i < requested.length; i++) {
410
+ const alone = await single.agent.byDID(requested[i]);
411
+ expect(JSON.stringify(agents[i])).toEqual(JSON.stringify(alone));
412
+ }
413
+ });
414
+
415
+ test('an unknown DID resolves to null for its caller only', async () => {
416
+ const orig = MOCK_RESPONSES['agent.byDid'];
417
+ MOCK_RESPONSES['agent.byDid'] = (p: Record<string, unknown>) =>
418
+ p.did === 'did:test:nobody' ? null : { did: p.did, perspective: new Perspective() };
419
+ try {
420
+ const [known, unknown] = await Promise.all([
421
+ ad4m.agent.byDID('did:test:somebody'),
422
+ ad4m.agent.byDID('did:test:nobody'),
423
+ ]);
424
+ expect(known.did).toBe('did:test:somebody');
425
+ expect(unknown).toBeNull();
426
+ expect(calls('agent.byDIDs')).toHaveLength(1);
427
+ } finally {
428
+ MOCK_RESPONSES['agent.byDid'] = orig;
429
+ }
430
+ });
431
+
432
+ test('more than 200 concurrent DIDs go out in calls of at most 200', async () => {
433
+ const dids = Array.from({ length: 250 }, (_, i) => `did:test:many-${i}`);
434
+ const agents = await Promise.all(dids.map(did => ad4m.agent.byDID(did)));
435
+ expect(agents.map(a => a.did)).toEqual(dids);
436
+ expect(calls('agent.byDIDs').map(c => (c.params.dids as string[]).length)).toEqual([200, 50]);
437
+ });
438
+
439
+ test('a failed batch rejects every waiting caller, and the next call retries', async () => {
440
+ const orig = MOCK_RESPONSES['agent.byDIDs'];
441
+ delete MOCK_RESPONSES['agent.byDIDs']; // the mock answers an unknown method with an error
442
+ let results: PromiseSettledResult<unknown>[];
443
+ try {
444
+ results = await Promise.allSettled([ad4m.agent.byDID('did:test:f1'), ad4m.agent.byDID('did:test:f2')]);
445
+ } finally {
446
+ MOCK_RESPONSES['agent.byDIDs'] = orig;
447
+ }
448
+ expect(results.map(r => r.status)).toEqual(['rejected', 'rejected']);
449
+ expect((await ad4m.agent.byDID('did:test:f1')).did).toBe('did:test:f1');
450
+ expect(calls('agent.byDIDs')).toHaveLength(2);
451
+ });
452
+
453
+ test('concurrent getMany() calls share one expression.getMany, each URL fetched once', async () => {
454
+ const [first, second] = await Promise.all([
455
+ ad4m.expression.getMany(['lang://test/Qm-s1', 'lang://test/Qm-s2']),
456
+ ad4m.expression.getMany(['lang://test/Qm-s2', 'lang://test/Qm-s3']),
457
+ ]);
458
+ expect(calls('expression.getMany')).toHaveLength(1);
459
+ expect(calls('expression.getMany')[0].params.urls).toEqual(['lang://test/Qm-s1', 'lang://test/Qm-s2', 'lang://test/Qm-s3']);
460
+ expect(first.map(e => JSON.parse(e.data).url)).toEqual(['lang://test/Qm-s1', 'lang://test/Qm-s2']);
461
+ expect(second.map(e => JSON.parse(e.data).url)).toEqual(['lang://test/Qm-s2', 'lang://test/Qm-s3']);
462
+ });
463
+
464
+ test('a fast get() settles without waiting for a slow get() of the same tick', async () => {
465
+ // Like a language that answers one URL in 5 ms and another in 300 ms.
466
+ const delay = (url: string) => url.endsWith('/Qm-slow') ? 300 : 5;
467
+ replyDelayMs = (type, params) => type === 'expression.get' ? delay(params.url as string)
468
+ : type === 'expression.getMany' ? Math.max(0, ...(params.urls as string[]).map(delay)) : 0;
469
+ await ad4m.agent.status(); // connect first, so the timing is the call's own
470
+ rpcCallLog = [];
471
+
472
+ const started = Date.now();
473
+ const fast = ad4m.expression.get('lang://test/Qm-fast').then(() => Date.now() - started);
474
+ const slow = ad4m.expression.get('lang://test/Qm-slow').then(() => Date.now() - started);
475
+ expect(await fast).toBeLessThan(150);
476
+ expect(await slow).toBeGreaterThanOrEqual(290);
477
+ expect(calls('expression.get').map(c => c.params.url)).toEqual(['lang://test/Qm-fast', 'lang://test/Qm-slow']);
478
+ expect(calls('expression.getMany')).toHaveLength(0);
479
+ });
480
+
481
+ test('a get() in flight serves a concurrent getMany() of the same URL', async () => {
482
+ const [one, many] = await Promise.all([
483
+ ad4m.expression.get('lang://test/Qm-shared'),
484
+ ad4m.expression.getMany(['lang://test/Qm-shared', 'lang://test/Qm-own']),
485
+ ]);
486
+ expect(calls('expression.get').map(c => c.params.url)).toEqual(['lang://test/Qm-shared']);
487
+ expect(calls('expression.getMany').map(c => c.params.urls)).toEqual([['lang://test/Qm-own']]);
488
+ expect(JSON.stringify(many[0])).toEqual(JSON.stringify(one));
489
+ });
490
+
491
+ test('concurrent get() calls make one expression.get per URL', async () => {
492
+ const urls = ['lang://test/Qm-g1', 'lang://test/Qm-g2', 'lang://test/Qm-g1'];
493
+ await Promise.all(urls.map(url => ad4m.expression.get(url)));
494
+ expect(calls('expression.get').map(c => c.params.url)).toEqual(['lang://test/Qm-g1', 'lang://test/Qm-g2']);
495
+ expect(calls('expression.getMany')).toHaveLength(0);
496
+ });
497
+
498
+ test('concurrent getMany() reads make one expression.getMany, each URL settling as a lone get() does', async () => {
499
+ const urls = ['lang://test/Qm-g1', 'lang://test/Qm-g2', 'lang://test/missing', 'lang://test/broken', 'lang://test/Qm-g1'];
500
+ const batched = await Promise.allSettled(urls.map(url => ad4m.expression.getMany([url]).then(([expression]) => expression)));
501
+ expect(calls('expression.getMany')).toHaveLength(1);
502
+ expect(calls('expression.get')).toHaveLength(0);
503
+
504
+ // Golden: each outcome equals what one `expression.get` call gives.
505
+ const alone = await Promise.allSettled(urls.map(url => new Ad4mClient('http://127.0.0.1:12002', 'test-token').expression.get(url, true)));
506
+ expect(calls('expression.get')).toHaveLength(urls.length);
507
+ const outcome = (r: PromiseSettledResult<unknown>) => r.status === 'fulfilled'
508
+ ? { value: JSON.stringify(r.value) }
509
+ : { error: (r.reason as Error).constructor.name, message: (r.reason as Error).message, status: (r.reason as { status?: number }).status };
510
+ expect(batched.map(outcome)).toEqual(alone.map(outcome));
511
+ expect(batched[2]).toEqual({ status: 'fulfilled', value: null });
512
+ expect(batched[3]).toMatchObject({ status: 'rejected', reason: { name: 'RpcError', status: 500 } });
513
+ });
514
+
515
+ test('a failed URL rejects only its own get(), and is read again next time', async () => {
516
+ const [good, bad] = await Promise.allSettled([
517
+ ad4m.expression.get('lang://test/Qm-ok'),
518
+ ad4m.expression.get('lang://test/broken'),
519
+ ]);
520
+ expect(good.status).toBe('fulfilled');
521
+ expect(bad.status).toBe('rejected');
522
+ await expect(ad4m.expression.getMany(['lang://test/Qm-ok', 'lang://test/broken'])).rejects.toMatchObject({ status: 500 });
523
+ expect(calls('expression.get').map(c => c.params.url)).toEqual(['lang://test/Qm-ok', 'lang://test/broken']);
524
+ expect(calls('expression.getMany').map(c => c.params.urls)).toEqual([['lang://test/broken']]);
525
+ });
526
+ });
527
+
336
528
  // ===================== EXPRESSION CACHE TESTS =====================
337
529
 
530
+ /** RPCs that read expressions: `expression.get` (a `get` miss) or a batch of `getMany` misses. */
531
+ const expressionReads = () => rpcCallLog.filter(c => c.type === 'expression.get' || c.type === 'expression.getMany');
532
+
338
533
  describe('ExpressionClient Cache', () => {
339
534
  test('get() deduplication — 3 concurrent calls = 1 RPC', async () => {
340
535
  const [e1, e2, e3] = await Promise.all([
@@ -347,7 +542,7 @@ describe('ExpressionClient Cache', () => {
347
542
  expect(e2.author).toBe('did:test:123');
348
543
  expect(e3.author).toBe('did:test:123');
349
544
 
350
- const getCalls = rpcCallLog.filter(c => c.type === 'expression.get');
545
+ const getCalls = expressionReads();
351
546
  expect(getCalls).toHaveLength(1);
352
547
  });
353
548
 
@@ -355,7 +550,7 @@ describe('ExpressionClient Cache', () => {
355
550
  await ad4m.expression.get('lang://test/Qm-l1hit');
356
551
  await ad4m.expression.get('lang://test/Qm-l1hit');
357
552
 
358
- const getCalls = rpcCallLog.filter(c => c.type === 'expression.get');
553
+ const getCalls = expressionReads();
359
554
  expect(getCalls).toHaveLength(1);
360
555
  });
361
556
 
@@ -363,15 +558,22 @@ describe('ExpressionClient Cache', () => {
363
558
  await ad4m.expression.get('lang://test/Qm-always');
364
559
  await ad4m.expression.get('lang://test/Qm-always', true);
365
560
 
366
- const getCalls = rpcCallLog.filter(c => c.type === 'expression.get');
561
+ const getCalls = expressionReads();
367
562
  expect(getCalls).toHaveLength(2);
368
563
  });
369
564
 
565
+ test('get() alwaysGet stores what it read for the next get()', async () => {
566
+ await ad4m.expression.get('lang://test/Qm-always-fills', true);
567
+ await ad4m.expression.get('lang://test/Qm-always-fills');
568
+
569
+ expect(expressionReads()).toHaveLength(1);
570
+ });
571
+
370
572
  test('get() different URLs make separate RPCs', async () => {
371
573
  await ad4m.expression.get('lang://test/Qm-a');
372
574
  await ad4m.expression.get('lang://test/Qm-b');
373
575
 
374
- const getCalls = rpcCallLog.filter(c => c.type === 'expression.get');
576
+ const getCalls = expressionReads();
375
577
  expect(getCalls).toHaveLength(2);
376
578
  });
377
579
 
@@ -384,19 +586,19 @@ describe('ExpressionClient Cache', () => {
384
586
  await ad4m.expression.get('lang://test/Qm-lru-1');
385
587
  await ad4m.expression.get('lang://test/Qm-lru-2');
386
588
  await ad4m.expression.get('lang://test/Qm-lru-3');
387
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(3);
589
+ expect(expressionReads()).toHaveLength(3);
388
590
 
389
591
  // Add 4th — should evict Qm-lru-1
390
592
  await ad4m.expression.get('lang://test/Qm-lru-4');
391
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(4);
593
+ expect(expressionReads()).toHaveLength(4);
392
594
 
393
595
  // Qm-lru-2 should still be cached (no new RPC)
394
596
  await ad4m.expression.get('lang://test/Qm-lru-2');
395
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(4);
597
+ expect(expressionReads()).toHaveLength(4);
396
598
 
397
599
  // Qm-lru-1 was evicted — should need a new RPC
398
600
  await ad4m.expression.get('lang://test/Qm-lru-1');
399
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(5);
601
+ expect(expressionReads()).toHaveLength(5);
400
602
  } finally {
401
603
  ExpressionClient.MAX_MEM_ENTRIES = originalMax;
402
604
  }
@@ -405,7 +607,7 @@ describe('ExpressionClient Cache', () => {
405
607
  test('getMany() partial cache hits — only fetches uncached URLs', async () => {
406
608
  // Pre-populate Qm-1 in cache
407
609
  await ad4m.expression.get('lang://test/Qm-1');
408
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(1);
610
+ expect(expressionReads()).toHaveLength(1);
409
611
 
410
612
  // getMany with Qm-1 (cached) + Qm-2 (not cached)
411
613
  const results = await ad4m.expression.getMany([
@@ -438,27 +640,47 @@ describe('ExpressionClient Cache', () => {
438
640
  expect(rpcCallLog).toHaveLength(0); // no RPCs at all
439
641
  });
440
642
 
643
+ test('get() TTL expiry triggers re-fetch', async () => {
644
+ // A language may change what a URL returns and no event tells the
645
+ // client, so a cached expression expires instead of staying fresh.
646
+ const originalTTL = ExpressionClient.EXPRESSION_TTL_MS;
647
+ ExpressionClient.EXPRESSION_TTL_MS = 1; // 1ms
648
+
649
+ try {
650
+ await ad4m.expression.get('lang://test/Qm-ttl');
651
+ expect(expressionReads()).toHaveLength(1);
652
+
653
+ // Wait longer than TTL
654
+ await new Promise(r => setTimeout(r, 10));
655
+
656
+ await ad4m.expression.get('lang://test/Qm-ttl');
657
+ expect(expressionReads()).toHaveLength(2);
658
+ } finally {
659
+ ExpressionClient.EXPRESSION_TTL_MS = originalTTL;
660
+ }
661
+ });
662
+
441
663
  test('clearCache() forces re-fetch', async () => {
442
664
  await ad4m.expression.get('lang://test/Qm-clear');
443
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(1);
665
+ expect(expressionReads()).toHaveLength(1);
444
666
 
445
667
  ad4m.expression.clearCache();
446
668
 
447
669
  await ad4m.expression.get('lang://test/Qm-clear');
448
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(2);
670
+ expect(expressionReads()).toHaveLength(2);
449
671
  });
450
672
 
451
673
  test('interact() invalidates cache for that URL', async () => {
452
674
  const url = 'lang://test/Qm-interact';
453
675
  await ad4m.expression.get(url);
454
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(1);
676
+ expect(expressionReads()).toHaveLength(1);
455
677
 
456
678
  // interact should invalidate cache
457
679
  await ad4m.expression.interact(url, { interactionName: 'modify', parameters: {} } as any);
458
680
 
459
681
  // Next get should hit network again (cache invalidated)
460
682
  await ad4m.expression.get(url);
461
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(2);
683
+ expect(expressionReads()).toHaveLength(2);
462
684
  });
463
685
  });
464
686
 
@@ -468,17 +690,17 @@ describe('ExpressionClient Cache — mutation & edge cases', () => {
468
690
  test('interact() only invalidates the targeted URL, not others', async () => {
469
691
  await ad4m.expression.get('lang://test/Qm-keep');
470
692
  await ad4m.expression.get('lang://test/Qm-invalidate');
471
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(2);
693
+ expect(expressionReads()).toHaveLength(2);
472
694
 
473
695
  await ad4m.expression.interact('lang://test/Qm-invalidate', { interactionName: 'modify', parameters: {} } as any);
474
696
 
475
697
  // Qm-keep should still be cached
476
698
  await ad4m.expression.get('lang://test/Qm-keep');
477
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(2); // no new RPC
699
+ expect(expressionReads()).toHaveLength(2); // no new RPC
478
700
 
479
701
  // Qm-invalidate was invalidated — needs re-fetch
480
702
  await ad4m.expression.get('lang://test/Qm-invalidate');
481
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(3);
703
+ expect(expressionReads()).toHaveLength(3);
482
704
  });
483
705
 
484
706
  test('create() does not pollute cache — fresh get() fetches from network', async () => {
@@ -486,7 +708,7 @@ describe('ExpressionClient Cache — mutation & edge cases', () => {
486
708
  // create returns an address string, not an ExpressionRendered
487
709
  // Cache should not have this address yet
488
710
  await ad4m.expression.get(addr);
489
- const getCalls = rpcCallLog.filter(c => c.type === 'expression.get');
711
+ const getCalls = expressionReads();
490
712
  expect(getCalls).toHaveLength(1); // went to network
491
713
  });
492
714
 
@@ -554,12 +776,12 @@ describe('ExpressionClient Cache — mutation & edge cases', () => {
554
776
  await ad4m.expression.get('lang://test/Qm-cross1');
555
777
  await ad4m.expression.get('lang://test/Qm-cross2');
556
778
 
557
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(0); // no individual RPCs
779
+ expect(expressionReads()).toHaveLength(1); // no RPC after the getMany
558
780
  });
559
781
 
560
782
  test('get() populates cache for subsequent getMany()', async () => {
561
783
  await ad4m.expression.get('lang://test/Qm-pre');
562
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(1);
784
+ expect(expressionReads()).toHaveLength(1);
563
785
 
564
786
  rpcCallLog = [];
565
787
 
@@ -585,15 +807,15 @@ describe('ExpressionClient Cache — mutation & edge cases', () => {
585
807
  try {
586
808
  await ad4m.expression.get('lang://test/Qm-bytes-1');
587
809
  await ad4m.expression.get('lang://test/Qm-bytes-2');
588
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(2);
810
+ expect(expressionReads()).toHaveLength(2);
589
811
 
590
812
  // Adding 3rd should evict 1st (oldest)
591
813
  await ad4m.expression.get('lang://test/Qm-bytes-3');
592
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(3);
814
+ expect(expressionReads()).toHaveLength(3);
593
815
 
594
816
  // Qm-bytes-1 was evicted — needs re-fetch
595
817
  await ad4m.expression.get('lang://test/Qm-bytes-1');
596
- expect(rpcCallLog.filter(c => c.type === 'expression.get')).toHaveLength(4);
818
+ expect(expressionReads()).toHaveLength(4);
597
819
  } finally {
598
820
  ExpressionClient.MAX_MEM_ENTRIES = origMaxEntries;
599
821
  ExpressionClient.MAX_MEM_BYTES = origMaxBytes;
@@ -624,7 +846,7 @@ describe('AgentClient Cache — additional edge cases', () => {
624
846
  expect(agent.did).toBe('did:test:preload');
625
847
  expect(agent.directMessageLanguage).toBe('lang://pre');
626
848
 
627
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid' && c.params.did === 'did:test:preload');
849
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs' && (c.params.dids as string[]).includes('did:test:preload'));
628
850
  expect(byDidCalls).toHaveLength(0);
629
851
  });
630
852
 
@@ -632,18 +854,18 @@ describe('AgentClient Cache — additional edge cases', () => {
632
854
  expect(() => ad4m.agent.invalidateByDid('did:test:nonexistent')).not.toThrow();
633
855
  });
634
856
 
635
- test('setSelfDid() then invalidateByDid() allows re-fetch of self', async () => {
636
- ad4m.agent.setSelfDid('did:test:self-inv');
637
- await ad4m.agent.byDID('did:test:self-inv');
638
- expect(rpcCallLog.filter(c => c.type === 'agent.byDid')).toHaveLength(1);
857
+ test('invalidateByDid() on the own DID forces a re-fetch', async () => {
858
+ const own = (await ad4m.agent.status()).did!;
859
+ await ad4m.agent.byDID(own);
860
+ expect(rpcCallLog.filter(c => c.type === 'agent.byDIDs')).toHaveLength(1);
639
861
 
640
- ad4m.agent.invalidateByDid('did:test:self-inv');
862
+ ad4m.agent.invalidateByDid(own);
641
863
 
642
- await ad4m.agent.byDID('did:test:self-inv');
643
- expect(rpcCallLog.filter(c => c.type === 'agent.byDid')).toHaveLength(2);
864
+ await ad4m.agent.byDID(own);
865
+ expect(rpcCallLog.filter(c => c.type === 'agent.byDIDs')).toHaveLength(2);
644
866
  });
645
867
 
646
- test('concurrent byDID() for different DIDs makes parallel RPCs', async () => {
868
+ test('concurrent byDID() for different DIDs makes one RPC', async () => {
647
869
  const [a1, a2, a3] = await Promise.all([
648
870
  ad4m.agent.byDID('did:test:par-1'),
649
871
  ad4m.agent.byDID('did:test:par-2'),
@@ -654,19 +876,20 @@ describe('AgentClient Cache — additional edge cases', () => {
654
876
  expect(a2.did).toBe('did:test:par-2');
655
877
  expect(a3.did).toBe('did:test:par-3');
656
878
 
657
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
658
- expect(byDidCalls).toHaveLength(3); // all different DIDs
879
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
880
+ expect(byDidCalls).toHaveLength(1);
881
+ expect(byDidCalls[0].params.dids).toEqual(['did:test:par-1', 'did:test:par-2', 'did:test:par-3']);
659
882
  });
660
883
 
661
884
  test('updatePublicPerspective() does not interact with byDID cache', async () => {
662
885
  // updatePublicPerspective uses agent.updateProfile RPC, not agent.byDid
663
886
  // Verify cache is unaffected
664
887
  await ad4m.agent.byDID('did:test:update-profile');
665
- expect(rpcCallLog.filter(c => c.type === 'agent.byDid')).toHaveLength(1);
888
+ expect(rpcCallLog.filter(c => c.type === 'agent.byDIDs')).toHaveLength(1);
666
889
 
667
890
  // byDID should still be cached
668
891
  await ad4m.agent.byDID('did:test:update-profile');
669
- expect(rpcCallLog.filter(c => c.type === 'agent.byDid')).toHaveLength(1);
892
+ expect(rpcCallLog.filter(c => c.type === 'agent.byDIDs')).toHaveLength(1);
670
893
  });
671
894
  });
672
895
 
@@ -684,9 +907,9 @@ describe('Cache isolation between clients', () => {
684
907
  await client2.expression.get('lang://test/Qm-isolated');
685
908
 
686
909
  // 2 RPCs for each — both clients went to network independently
687
- const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDid');
910
+ const byDidCalls = rpcCallLog.filter(c => c.type === 'agent.byDIDs');
688
911
  expect(byDidCalls).toHaveLength(2);
689
- const getCalls = rpcCallLog.filter(c => c.type === 'expression.get');
912
+ const getCalls = expressionReads();
690
913
  expect(getCalls).toHaveLength(2);
691
914
  });
692
915
  });
@@ -696,7 +919,7 @@ describe('Cache isolation between clients', () => {
696
919
  describe('Ad4mClient cache integration', () => {
697
920
  test('close() clears agent L1 cache', async () => {
698
921
  await ad4m.agent.byDID('did:test:close');
699
- expect(rpcCallLog.filter(c => c.type === 'agent.byDid')).toHaveLength(1);
922
+ expect(rpcCallLog.filter(c => c.type === 'agent.byDIDs')).toHaveLength(1);
700
923
 
701
924
  ad4m.close();
702
925
 
@@ -707,6 +930,6 @@ describe('Ad4mClient cache integration', () => {
707
930
  const fresh = new Ad4mClient('http://127.0.0.1:12000', 'test-token');
708
931
  await fresh.agent.byDID('did:test:close');
709
932
  // New client should make its own RPC (separate cache)
710
- expect(rpcCallLog.filter(c => c.type === 'agent.byDid')).toHaveLength(2);
933
+ expect(rpcCallLog.filter(c => c.type === 'agent.byDIDs')).toHaveLength(2);
711
934
  });
712
935
  });