@coasys/ad4m 0.13.1-staging.2 → 0.13.1-staging.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/lib/index.cjs +584 -203
  2. package/lib/index.js +581 -204
  3. package/lib/src/Ad4mClient.d.ts +7 -0
  4. package/lib/src/Ad4mClient.js +9 -0
  5. package/lib/src/apiClient.d.ts +13 -0
  6. package/lib/src/apiClient.js +67 -12
  7. package/lib/src/generated/api/AuthInfo.d.ts +4 -0
  8. package/lib/src/generated/api/RuntimeInfo.d.ts +5 -0
  9. package/lib/src/index.d.ts +1 -0
  10. package/lib/src/index.js +1 -0
  11. package/lib/src/model/Ad4mModel.js +45 -18
  12. package/lib/src/model/ModelQueryBuilder.d.ts +7 -3
  13. package/lib/src/model/ModelQueryBuilder.js +9 -4
  14. package/lib/src/model/query-common.js +7 -1
  15. package/lib/src/model/types.d.ts +45 -2
  16. package/lib/src/model/types.js +8 -0
  17. package/lib/src/perspectives/Container.d.ts +41 -0
  18. package/lib/src/perspectives/Container.js +62 -0
  19. package/lib/src/perspectives/PerspectiveProxy.d.ts +6 -3
  20. package/lib/src/perspectives/PerspectiveProxy.js +10 -4
  21. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +94 -12
  22. package/lib/src/perspectives/WakerSubscriptionManager.js +273 -72
  23. package/lib/src/runtime/RuntimeTypes.d.ts +2 -0
  24. package/package.json +2 -2
  25. package/src/Ad4mClient.test.ts +1 -1
  26. package/src/Ad4mClient.ts +10 -0
  27. package/src/apiClient.test.ts +128 -2
  28. package/src/apiClient.ts +64 -11
  29. package/src/generated/api/AuthInfo.ts +6 -1
  30. package/src/generated/api/RuntimeInfo.ts +6 -1
  31. package/src/index.ts +1 -0
  32. package/src/model/Ad4mModel.ts +51 -19
  33. package/src/model/ModelQueryBuilder.ts +9 -6
  34. package/src/model/containment-scope.test.ts +104 -0
  35. package/src/model/query-common.ts +10 -1
  36. package/src/model/types.ts +56 -2
  37. package/src/perspectives/Container.test.ts +65 -0
  38. package/src/perspectives/Container.ts +46 -0
  39. package/src/perspectives/PerspectiveProxy.test.ts +11 -0
  40. package/src/perspectives/PerspectiveProxy.ts +10 -4
  41. package/src/perspectives/WakerSubscriptionManager.test.ts +398 -80
  42. package/src/perspectives/WakerSubscriptionManager.ts +318 -82
  43. package/src/runtime/RuntimeTypes.ts +2 -0
@@ -6,6 +6,107 @@
6
6
  * module (`plugins/ad4m/wakerSubscriptionManager.ts`) rather than carrying its
7
7
  * own copy. Any behaviour change belongs here.
8
8
  */
9
+ /** A letter, combining mark, digit or underscore: what a term must not touch. */
10
+ const WORD_CHAR = "[\\p{L}\\p{M}\\p{N}_]";
11
+ /**
12
+ * The elements a message's HTML is made of. A `<` before any other name is text:
13
+ * We stores plain text, where "<hey Data> can you look" is words.
14
+ */
15
+ const ELEMENT = "a|abbr|b|bdi|bdo|blockquote|br|caption|center|cite|code|col|colgroup|dd|del|details|dfn|div|dl|dt|em|" +
16
+ "figcaption|figure|font|h[1-6]|hr|i|img|ins|kbd|label|li|mark|ol|p|pre|q|s|samp|section|article|small|" +
17
+ "span|strike|strong|sub|summary|sup|table|tbody|td|tfoot|th|thead|time|tr|u|ul|var|wbr|script|style";
18
+ /** An attribute: a name, then optionally `=` and a quoted value (which may hold `>`) or an unquoted one. */
19
+ const ATTRIBUTE = `\\s+[A-Za-z_:][-\\w:.]*(?:\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s"'=<>\`]+))?`;
20
+ /**
21
+ * Markup: a comment, a `<script>`/`<style>` element with its contents, or a tag of
22
+ * a known element whose rest is a valid attribute list. "a < b" and
23
+ * "if a <b then ask Data, else c -> d" are text: the comma is no attribute.
24
+ */
25
+ const TAG = new RegExp(`<!--[\\s\\S]*?-->` +
26
+ `|<(script|style)(?=[\\s/>])(?:${ATTRIBUTE})*\\s*>[\\s\\S]*?<\\/\\1\\s*>` +
27
+ `|<(?:${ELEMENT})(?=[\\s/>])(?:${ATTRIBUTE})*\\s*\\/?>` +
28
+ `|<\\/(?:${ELEMENT})\\s*>`, "gi");
29
+ /** Tags that break a line: replaced by a space, so `<p>hi</p><p>Data</p>` keeps "Data" a word. */
30
+ const BREAKING_TAG = /^<\/?(?:p|div|br|hr|li|ul|ol|h[1-6]|blockquote|pre|tr|td|th|table|section|article)\b/i;
31
+ /**
32
+ * The attributes a mention puts its target's DID in: Flux's `<a data-type="mention"
33
+ * href="did:…">`, older Flux messages' `<span data-id="did:…">`, and We's editor chip
34
+ * `<span class="we-mention" data-did="did:…">`.
35
+ */
36
+ const ATTRIBUTES = new RegExp(ATTRIBUTE, "g");
37
+ const MENTION_TARGET = /^\s+(?:href|data-id|data-did)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))$/i;
38
+ /**
39
+ * How much of a record's text the word check reads. Dropping markup costs time
40
+ * quadratic in a run of unclosed `<script>`, `<style>` or `<!--` openers, so a
41
+ * very long text could hold the event loop for seconds, and a row that holds
42
+ * no term is checked again on every result while it is in the window. A term
43
+ * past this many characters does not wake.
44
+ */
45
+ export const MENTION_TEXT_LIMIT = 16384;
46
+ const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
47
+ function decodeEntities(s) {
48
+ return s.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (whole, ref) => {
49
+ if (ref[0] !== "#")
50
+ return ENTITIES[ref.toLowerCase()] ?? whole;
51
+ const code = ref[1] === "x" || ref[1] === "X" ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
52
+ return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
53
+ });
54
+ }
55
+ /**
56
+ * What a reader sees of `text`, and the DIDs its mentions point at. `text` may be
57
+ * HTML (TextContent allows it): tag names and attributes are markup, not words, so
58
+ * a bot named "Data" must not wake on `data-type="mention"` in a mention of
59
+ * someone else. Plain text passes through unchanged, apart from entities.
60
+ */
61
+ function readableParts(text) {
62
+ const targets = [];
63
+ const visible = text.replace(TAG, (tag, scriptOrStyle) => {
64
+ if (scriptOrStyle)
65
+ return " ";
66
+ if (tag.startsWith("<!--"))
67
+ return "";
68
+ // Parse complete attributes first: a DID-shaped string inside `title`
69
+ // is not a target attribute and must not wake an agent.
70
+ for (const attribute of tag.matchAll(ATTRIBUTES)) {
71
+ const target = MENTION_TARGET.exec(attribute[0]);
72
+ if (target)
73
+ targets.push(decodeEntities(target[1] ?? target[2] ?? target[3]));
74
+ }
75
+ return BREAKING_TAG.test(tag) ? " " : "";
76
+ });
77
+ return { visible: decodeEntities(visible), targets };
78
+ }
79
+ /**
80
+ * Whether `text` holds one of `terms` as a whole word, case-insensitively:
81
+ * "Data" is in "hi Data!", "@data" and "Data's turn", not in "metadata" or
82
+ * "database". A term is matched literally (regex characters, quotes) and must
83
+ * not touch a letter, mark, digit or underscore on either side, so a name
84
+ * that starts or ends with punctuation still matches. Same rule as #1459's
85
+ * SPARQL `(?:^|\W)term(?:\W|$)`.
86
+ *
87
+ * The rule runs on the visible text only: in HTML, tags and attributes are
88
+ * dropped and entities decoded first. A mention's target attribute
89
+ * (`href`, `data-id`, `data-did`) matches an exact, case-sensitive DID term, which
90
+ * is how a mention by DID is found when the DID is not in the visible text.
91
+ *
92
+ * The mention query's `contains` matches substrings (model query has no word
93
+ * match); this is the check that keeps "data" from waking on "metadata".
94
+ * It reads the first {@link MENTION_TEXT_LIMIT} characters only.
95
+ */
96
+ export function holdsAWholeWordTerm(text, terms) {
97
+ const { visible, targets } = readableParts(text.slice(0, MENTION_TEXT_LIMIT));
98
+ return terms.some((term) => {
99
+ if (!term)
100
+ return false;
101
+ if (term.startsWith("did:") && targets.includes(term))
102
+ return true;
103
+ const escaped = term.replace(/[\\^$.*+?()[\]{}|\/]/g, "\\$&");
104
+ return new RegExp(`(?<!${WORD_CHAR})${escaped}(?!${WORD_CHAR})`, "iu").test(visible);
105
+ });
106
+ }
107
+ /** The built-in `Container` (`Container.builtinUri`; not imported, so the
108
+ * plugin bundle does not pull in the model layer). */
109
+ const CONTAINER = "ad4m://Container";
9
110
  /**
10
111
  * Add a short cause hint to known subscription failures.
11
112
  * The executor needs its main key to register a live query; on a restarted
@@ -72,6 +173,20 @@ export class WakerSubscriptionManager {
72
173
  /** Per-subscription set of already-processed message addresses (for mention subs)
73
174
  * or serialized result hash (for channel-messages subs). */
74
175
  this.seenMessages = new Map();
176
+ /**
177
+ * Per mention subscription: the addresses whose wake was delivered, or that were history when
178
+ * the subscription opened. This, not `seenMessages`, is what gets persisted: an address joins
179
+ * `seenMessages` as soon as it is read, while its parents are still resolving and before any
180
+ * wake, so a restart in between must not take it as done.
181
+ */
182
+ this.delivered = new Map();
183
+ /**
184
+ * Per mention subscription: mentions read but whose wake has not been delivered yet, keyed by
185
+ * address. They accumulate across a debounce window, so one wake names all of them.
186
+ */
187
+ this.undelivered = new Map();
188
+ /** Failed wake attempts in a row per subscription, for the retry backoff. */
189
+ this.wakeFailures = new Map();
75
190
  this.perspectiveClient = options.perspectiveClient;
76
191
  this.logger = options.logger;
77
192
  this.debounceMs = options.debounceMs ?? 2000;
@@ -82,6 +197,7 @@ export class WakerSubscriptionManager {
82
197
  this.previousSeenMessages = options.previousSeenMessages ?? {};
83
198
  this.retryPendingMs = options.retryPendingMs ?? 30000;
84
199
  this.subscribeTimeoutMs = options.subscribeTimeoutMs ?? 15000;
200
+ this.retryWakeMs = options.retryWakeMs ?? 5000;
85
201
  }
86
202
  /** A token identifying this attempt at subscribing `id`. */
87
203
  beginAttempt(id) {
@@ -94,7 +210,7 @@ export class WakerSubscriptionManager {
94
210
  return token.epoch !== this.epoch || this.generations.get(id) !== token.gen;
95
211
  }
96
212
  /**
97
- * Create a live SPARQL subscription.
213
+ * Create a live subscription: SPARQL, or a model query when `sub.className` is set.
98
214
  * If a subscription with the same id already exists, it is disposed first.
99
215
  */
100
216
  async subscribe(sub) {
@@ -105,9 +221,16 @@ export class WakerSubscriptionManager {
105
221
  throw new Error("WakerSubscriptionManager: QuerySubscriptionProxy must be provided via constructor options");
106
222
  }
107
223
  const QuerySubscriptionProxy = this.QuerySubscriptionProxyCtor;
224
+ if (sub.type === "mention" && sub.className && !sub.terms?.length) {
225
+ // Without terms the whole-word check cannot run, and every substring
226
+ // ("metadata" for "data") would wake the agent.
227
+ throw new Error(`Waker subscription ${sub.id}: a mention subscription needs its terms (get_mention_waker_config returns them)`);
228
+ }
108
229
  this.logger.info(`[waker] ${sub.id}: creating subscription (perspective=${sub.perspective}, type=${sub.type})`);
109
- this.logger.info(`[waker] ${sub.id}: SPARQL query:\n${sub.query}`);
110
- const proxy = new QuerySubscriptionProxy(sub.perspective, sub.query, this.perspectiveClient);
230
+ this.logger.info(`[waker] ${sub.id}: ${sub.className ? `model query over ${sub.className}` : "SPARQL query"}:\n${sub.query}`);
231
+ const proxy = sub.className
232
+ ? new QuerySubscriptionProxy(sub.perspective, sub.query, this.perspectiveClient, sub.className)
233
+ : new QuerySubscriptionProxy(sub.perspective, sub.query, this.perspectiveClient);
111
234
  // Suppress unhandled rejection from proxy.initialized — QuerySubscriptionProxy
112
235
  // rejects this promise internally when subscribe() fails, and if nobody catches
113
236
  // it before the next microtask it crashes the process.
@@ -148,6 +271,7 @@ export class WakerSubscriptionManager {
148
271
  // reported as active or persisted as if it were.
149
272
  this.activeSubscriptions.delete(sub.id);
150
273
  this.seenMessages.delete(sub.id);
274
+ this.delivered.delete(sub.id);
151
275
  this.persist();
152
276
  // Keep it pending and re-attempt: the usual cause (locked wallet, executor
153
277
  // mid-restart, a handshake the executor never answered) clears on its
@@ -172,33 +296,62 @@ export class WakerSubscriptionManager {
172
296
  this.pendingSubscriptions.delete(sub.id);
173
297
  this.logger.info(`[waker] ${sub.id}: subscription initialized successfully`);
174
298
  // Seed from persisted seen messages so we don't re-wake after restart
299
+ const restored = Object.prototype.hasOwnProperty.call(this.previousSeenMessages, sub.id);
175
300
  const seen = new Set(this.previousSeenMessages[sub.id] ?? []);
176
301
  this.seenMessages.set(sub.id, seen);
302
+ this.delivered.set(sub.id, new Set(seen));
177
303
  if (seen.size > 0) {
178
304
  this.logger.info(`[waker] ${sub.id}: seeded ${seen.size} seen message(s) from persisted state`);
179
305
  }
180
- proxy.onResult(async (result) => {
181
- this.logger.info(`[waker] ${sub.id}: onResult fired — type=${typeof result}, isArray=${Array.isArray(result)}, value=${String(JSON.stringify(result)).substring(0, 500)}`);
182
- // Query engine can deliver non-array values (e.g. false) on disconnect/reconnect — ignore them
183
- if (!Array.isArray(result)) {
184
- this.logger.warn(`[waker] ${sub.id}: ignoring non-array result: ${JSON.stringify(result)}`);
306
+ // `opening` is the result the subscription holds when it opens (`proxy.result`): `onResult`
307
+ // only reports later changes, so this is the one chance to see what was written meanwhile.
308
+ const handleResult = async (result, opening = false) => {
309
+ this.logger.info(`[waker] ${sub.id}: ${opening ? "opening result" : "onResult fired"} — type=${typeof result}, isArray=${Array.isArray(result)}, value=${String(JSON.stringify(result)).substring(0, 500)}`);
310
+ // A model subscription delivers `{ instances }`, SPARQL an array of
311
+ // rows. Anything else (e.g. `false` on a disconnect/reconnect) is
312
+ // ignored.
313
+ const rows = sub.className ? result?.instances : result;
314
+ if (!Array.isArray(rows)) {
315
+ this.logger.warn(`[waker] ${sub.id}: ignoring result without ${sub.className ? "instances" : "rows"}: ${JSON.stringify(result)}`);
185
316
  return;
186
317
  }
187
318
  if (sub.type === "mention") {
188
- // For mention subscriptions: track seen message addresses.
189
- // Only wake for messages we haven't seen before.
319
+ // For mention subscriptions: track seen record ids.
320
+ // Only wake for records we haven't seen before.
190
321
  const currentSeen = this.seenMessages.get(sub.id) ?? new Set();
191
322
  const newMessages = [];
192
- for (const item of result) {
193
- if (item && item.source && !currentSeen.has(item.source)) {
194
- newMessages.push(item.source);
323
+ const terms = sub.terms ?? [];
324
+ for (const item of rows) {
325
+ // A SPARQL row names the record as `source`, a model row as `id`.
326
+ const address = sub.className ? item?.id : item?.source;
327
+ if (typeof address !== "string" || !address || currentSeen.has(address))
328
+ continue;
329
+ if (terms.length) {
330
+ // The mention query matched a substring; wake only on a whole word.
331
+ const text = Array.isArray(item.text) ? item.text.join(" ") : item.text;
332
+ if (typeof text !== "string" || !holdsAWholeWordTerm(text, terms)) {
333
+ this.logger.debug(`[waker] ${sub.id}: ${address} holds no term as a whole word, skipping`);
334
+ continue;
335
+ }
195
336
  }
337
+ currentSeen.add(address);
338
+ newMessages.push(address);
196
339
  }
197
340
  if (newMessages.length === 0) {
198
- this.logger.info(`[waker] ${sub.id}: all ${result.length} items already seen, skipping`);
341
+ this.logger.info(`[waker] ${sub.id}: no new mention among ${rows.length} items, skipping`);
342
+ return;
343
+ }
344
+ if (opening && !restored) {
345
+ // A new subscription: what it opens on is history, readable on demand, not news.
346
+ this.seenMessages.set(sub.id, currentSeen);
347
+ const done = this.delivered.get(sub.id) ?? new Set();
348
+ for (const address of newMessages)
349
+ done.add(address);
350
+ this.delivered.set(sub.id, done);
351
+ this.logger.info(`[waker] ${sub.id}: ${newMessages.length} existing mention(s) taken as history, not woken`);
199
352
  return;
200
353
  }
201
- this.logger.info(`[waker] ${sub.id}: ${newMessages.length} new message(s) out of ${result.length} total`);
354
+ this.logger.info(`[waker] ${sub.id}: ${newMessages.length} new message(s) out of ${rows.length} total`);
202
355
  // Resolve parents, and the chain above them, per new message
203
356
  const mentions = [];
204
357
  for (const msgAddr of newMessages) {
@@ -209,25 +362,20 @@ export class WakerSubscriptionManager {
209
362
  (ancestors.length ? `; ancestors: ${ancestors.join(", ")}` : ""));
210
363
  mentions.push({ address: msgAddr, parents, ancestors });
211
364
  }
212
- // Mark all new messages as seen
213
- for (const addr of newMessages) {
214
- currentSeen.add(addr);
215
- }
216
365
  this.seenMessages.set(sub.id, currentSeen);
217
- // Debounce the wake callback
218
- const existing = this.debounceTimers.get(sub.id);
219
- if (existing)
220
- clearTimeout(existing);
221
- this.debounceTimers.set(sub.id, setTimeout(() => {
222
- this.onWake(sub, result, mentions);
223
- this.debounceTimers.delete(sub.id);
224
- this.persist();
225
- }, this.debounceMs));
366
+ const pending = this.undelivered.get(sub.id) ?? new Map();
367
+ for (const mention of mentions)
368
+ pending.set(mention.address, mention);
369
+ this.undelivered.set(sub.id, pending);
370
+ this.scheduleMentionWake(sub, result, this.debounceMs);
226
371
  }
227
372
  else {
373
+ // A container's contents when the subscription opens are not an update.
374
+ if (opening)
375
+ return;
228
376
  // For channel-messages: always notify the agent on every subscription push.
229
377
  // No deduplication — the agent reads recent messages itself.
230
- this.logger.info(`[waker] ${sub.id}: channel update (${result.length} items)`);
378
+ this.logger.info(`[waker] ${sub.id}: channel update (${rows.length} items)`);
231
379
  const existing = this.debounceTimers.get(sub.id);
232
380
  if (existing)
233
381
  clearTimeout(existing);
@@ -236,7 +384,8 @@ export class WakerSubscriptionManager {
236
384
  this.debounceTimers.delete(sub.id);
237
385
  }, this.debounceMs));
238
386
  }
239
- });
387
+ };
388
+ proxy.onResult((result) => handleResult(result));
240
389
  if (this.isStale(sub.id, token)) {
241
390
  try {
242
391
  proxy.dispose();
@@ -246,6 +395,16 @@ export class WakerSubscriptionManager {
246
395
  }
247
396
  this.proxies.set(sub.id, proxy);
248
397
  this.activeSubscriptions.set(sub.id, sub);
398
+ // After a restart this wakes on mentions written while the waker was down; on a new
399
+ // subscription it records the existing ones as history.
400
+ if (proxy.result !== undefined) {
401
+ try {
402
+ await handleResult(proxy.result, true);
403
+ }
404
+ catch (e) {
405
+ this.logger.warn(`[waker] ${sub.id}: reading the opening result failed: ${e?.message ?? e}`);
406
+ }
407
+ }
249
408
  this.persist();
250
409
  this.logger.info(`[waker] Subscription ${sub.id} active (type=${sub.type}, perspective=${sub.perspective})`);
251
410
  }
@@ -321,9 +480,61 @@ export class WakerSubscriptionManager {
321
480
  this.activeSubscriptions.delete(id);
322
481
  this.pendingSubscriptions.delete(id);
323
482
  this.seenMessages.delete(id);
483
+ this.delivered.delete(id);
484
+ this.undelivered.delete(id);
485
+ this.wakeFailures.delete(id);
324
486
  if (persist)
325
487
  this.persist();
326
488
  }
489
+ /** (Re)start the timer that offers `sub`'s undelivered mentions to `onWake` after `delayMs`. */
490
+ scheduleMentionWake(sub, result, delayMs) {
491
+ const existing = this.debounceTimers.get(sub.id);
492
+ if (existing)
493
+ clearTimeout(existing);
494
+ this.debounceTimers.set(sub.id, setTimeout(() => {
495
+ this.debounceTimers.delete(sub.id);
496
+ void this.deliverMentions(sub, result);
497
+ }, delayMs));
498
+ }
499
+ /**
500
+ * Offer every undelivered mention of `sub` in one wake. On delivery they join the persisted
501
+ * seen set; on failure they stay undelivered and are offered again with backoff.
502
+ */
503
+ async deliverMentions(sub, result) {
504
+ const pending = this.undelivered.get(sub.id);
505
+ if (!pending?.size || !this.activeSubscriptions.has(sub.id))
506
+ return;
507
+ const mentions = Array.from(pending.values());
508
+ let delivered;
509
+ try {
510
+ delivered = (await this.onWake(sub, result, mentions)) !== false;
511
+ }
512
+ catch (e) {
513
+ this.logger.warn(`[waker] ${sub.id}: wake callback threw: ${e?.message ?? e}`);
514
+ delivered = false;
515
+ }
516
+ // Disposed while the wake was in flight: nothing left to retry or persist.
517
+ if (this.undelivered.get(sub.id) !== pending)
518
+ return;
519
+ if (!delivered) {
520
+ const failures = (this.wakeFailures.get(sub.id) ?? 0) + 1;
521
+ this.wakeFailures.set(sub.id, failures);
522
+ const delay = Math.min(this.retryWakeMs * 2 ** (failures - 1), 60000);
523
+ this.logger.warn(`[waker] ${sub.id}: wake for ${mentions.length} mention(s) not delivered, offering again in ${delay}ms`);
524
+ // A newer result arriving meanwhile restarts the timer and joins this wake.
525
+ if (!this.debounceTimers.has(sub.id))
526
+ this.scheduleMentionWake(sub, result, delay);
527
+ return;
528
+ }
529
+ this.wakeFailures.delete(sub.id);
530
+ const done = this.delivered.get(sub.id) ?? new Set();
531
+ for (const mention of mentions) {
532
+ pending.delete(mention.address);
533
+ done.add(mention.address);
534
+ }
535
+ this.delivered.set(sub.id, done);
536
+ this.persist();
537
+ }
327
538
  /** Dispose all active subscriptions and drop anything still pending. */
328
539
  disposeAll() {
329
540
  // Bump the epoch first: in-flight subscribe() calls have no proxy in the
@@ -346,60 +557,50 @@ export class WakerSubscriptionManager {
346
557
  has(id) {
347
558
  return this.activeSubscriptions.has(id);
348
559
  }
349
- /** Resolve one containment level in one query; skip unsafe IRI tokens and treat failures as none. */
560
+ /**
561
+ * Everything holding any of `addresses`, in one model query: a `Container`
562
+ * step in (#1446). The executor follows `ad4m://has_child` on any node and
563
+ * each class's own `children` relation on its instances, so the waker
564
+ * looks up no predicate. Failures count as none.
565
+ */
350
566
  async parentsOf(sub, addresses) {
351
- const safe = [...new Set(addresses)].filter((address) => {
352
- if (/[<>"{}|^`\\\s\x00-\x20]/.test(address)) {
353
- this.logger.warn(`[waker] ${sub.id}: skipping parent lookup for unsafe address ${JSON.stringify(address)}`);
354
- return false;
355
- }
356
- return true;
357
- });
358
- if (!safe.length)
567
+ if (!addresses.length)
359
568
  return [];
360
- try {
361
- const query = safe.length === 1
362
- ? `SELECT ?source WHERE { ?source <ad4m://has_child> <${safe[0]}> . }`
363
- : `SELECT ?source WHERE { VALUES ?child { ${safe.map((address) => `<${address}>`).join(" ")} } ?source <ad4m://has_child> ?child . }`;
364
- const rows = await this.perspectiveClient.querySparql(sub.perspective, query);
365
- if (!Array.isArray(rows))
366
- return [];
367
- // A row omits a variable left unbound in its solution.
368
- return rows.map((row) => row?.source).filter((source) => typeof source === "string");
369
- }
370
- catch (err) {
371
- this.logger.warn(`[waker] ${sub.id}: parent resolution failed for ${JSON.stringify(safe)} — ${err?.message ?? err}`);
372
- return [];
373
- }
569
+ return this.containers(sub, { ids: [...new Set(addresses)], direction: "in" }, addresses);
374
570
  }
375
571
  /**
376
- * The chain above an item's parents, a level at a time, nearest first, up to `ancestorDepth`.
377
- *
378
- * Breadth-first with a visited set: containment is a graph, not a tree — an item can sit in two
379
- * places, and nothing stops a cycle — so each address is reported once and the walk always ends.
380
- * Each level uses one batched parent lookup, bounded by the depth.
572
+ * The chain above an item's parents, nearest first, up to `ancestorDepth` levels: one
573
+ * transitive `Container` walk in from the parents, bounded by `maxDepth`. The executor walks
574
+ * containment as a graph, so each address comes once however many paths reach it, and a
575
+ * cycle ends. The item and its parents are never reported as ancestors.
381
576
  */
382
577
  async ancestorsOf(sub, address, parents) {
578
+ if (!parents.length || this.ancestorDepth <= 0)
579
+ return [];
580
+ const scope = { ids: parents, direction: "in", transitive: true, maxDepth: this.ancestorDepth };
383
581
  const seen = new Set([address, ...parents]);
384
- const ancestors = [];
385
- let level = parents;
386
- for (let depth = 0; depth < this.ancestorDepth && level.length; depth++) {
387
- const next = [];
388
- for (const parent of await this.parentsOf(sub, level)) {
389
- if (seen.has(parent))
390
- continue;
391
- seen.add(parent);
392
- next.push(parent);
393
- }
394
- ancestors.push(...next);
395
- level = next;
582
+ return (await this.containers(sub, scope, parents)).filter((id) => !seen.has(id));
583
+ }
584
+ /** The ids of the `Container` rows `parent` scopes to, in the executor's order. */
585
+ async containers(sub, parent, from) {
586
+ try {
587
+ const query = JSON.stringify({ parent, properties: [] });
588
+ const result = await this.perspectiveClient.modelQuery(sub.perspective, CONTAINER, query);
589
+ const instances = result?.instances;
590
+ if (!Array.isArray(instances))
591
+ return [];
592
+ return instances.map((row) => row?.id).filter((id) => typeof id === "string");
593
+ }
594
+ catch (err) {
595
+ this.logger.warn(`[waker] ${sub.id}: containment lookup failed for ${JSON.stringify(from)} — ${err?.message ?? err}`);
596
+ return [];
396
597
  }
397
- return ancestors;
398
598
  }
399
599
  persist() {
400
600
  if (this.onPersist) {
401
601
  const seen = {};
402
- for (const [id, set] of this.seenMessages) {
602
+ // Only what was delivered: anything else must wake again after a restart.
603
+ for (const [id, set] of this.delivered) {
403
604
  seen[id] = Array.from(set);
404
605
  }
405
606
  this.onPersist(this.getActive(), seen);
@@ -6,6 +6,8 @@ export declare class SentMessage {
6
6
  }
7
7
  export declare class RuntimeInfo {
8
8
  ad4mExecutorVersion: string;
9
+ /** The commit the executor was built from, or null when the build could not tell. */
10
+ ad4mExecutorCommit: string | null;
9
11
  isInitialized: Boolean;
10
12
  isUnlocked: Boolean;
11
13
  }
package/package.json CHANGED
@@ -53,8 +53,8 @@
53
53
  "ws": "8.13.0"
54
54
  },
55
55
  "patchedDependencies": {},
56
- "version": "0.13.1-staging.2",
57
- "gitHead": "ac74cdc648b6db62da5a1eb18d58782b63df11a0",
56
+ "version": "0.13.1-staging.3",
57
+ "gitHead": "67bac5964aafa5476808f9ee146ac0212daac086",
58
58
  "scripts": {
59
59
  "build": "patch-package && tsc && pnpm run bundle",
60
60
  "bundle": "rollup -c rollup.config.js",
@@ -174,7 +174,7 @@ const MOCK_RESPONSES: Record<string, RpcHandler> = {
174
174
  'expression.interact': 'interaction-result',
175
175
 
176
176
  // ── Runtime ──
177
- 'runtime.info': { ad4mExecutorVersion: '0.1.0', isUnlocked: true, isInitialized: true },
177
+ 'runtime.info': { ad4mExecutorVersion: '0.1.0', ad4mExecutorCommit: null, isUnlocked: true, isInitialized: true },
178
178
  'runtime.tlsDomain': 'test.domain.com',
179
179
  'runtime.quit': true,
180
180
  'runtime.openLink': true,
package/src/Ad4mClient.ts CHANGED
@@ -99,6 +99,16 @@ export class Ad4mClient {
99
99
  return this.#apiClient.on(type, handler, filter)
100
100
  }
101
101
 
102
+ /**
103
+ * Call `callback` once when the executor refuses this client's token
104
+ * (expired, revoked, or no session). Every call then fails with a 401
105
+ * `RpcError` and the client stops reconnecting: log in again and build a
106
+ * new client. Returns a function that removes the callback.
107
+ */
108
+ onAuthFailed(callback: (reason: string) => void): () => void {
109
+ return this.#apiClient.onAuthFailed(callback)
110
+ }
111
+
102
112
  /** Close all event connections and clear in-memory caches */
103
113
  close(): void {
104
114
  this.#agentClient.clearByDidCache()