@coasys/ad4m 0.13.0-test-model-layer → 0.13.0-test-inverse-relations

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 (41) hide show
  1. package/lib/index.cjs +432 -46
  2. package/lib/index.js +430 -47
  3. package/lib/src/ai/AIClient.d.ts +13 -0
  4. package/lib/src/ai/AIClient.js +15 -0
  5. package/lib/src/model/Ad4mModel.js +14 -6
  6. package/lib/src/model/ModelQueryBuilder.js +13 -3
  7. package/lib/src/model/query-common.d.ts +10 -1
  8. package/lib/src/model/query-common.js +16 -0
  9. package/lib/src/model/query-sparql.js +25 -1
  10. package/lib/src/model/shacl-gen.js +12 -0
  11. package/lib/src/model/types.d.ts +91 -1
  12. package/lib/src/model/types.js +9 -0
  13. package/lib/src/perspectives/AutoProcessor.d.ts +8 -0
  14. package/lib/src/perspectives/FlowInstance.d.ts +30 -12
  15. package/lib/src/perspectives/FlowInstance.js +36 -13
  16. package/lib/src/perspectives/FlowModels.d.ts +7 -1
  17. package/lib/src/perspectives/FlowModels.js +8 -2
  18. package/lib/src/perspectives/PerspectiveClient.d.ts +16 -0
  19. package/lib/src/perspectives/PerspectiveClient.js +12 -0
  20. package/lib/src/perspectives/PerspectiveProxy.d.ts +31 -3
  21. package/lib/src/perspectives/PerspectiveProxy.js +78 -2
  22. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +55 -5
  23. package/lib/src/perspectives/WakerSubscriptionManager.js +183 -8
  24. package/package.json +1 -1
  25. package/src/ai/AIClient.ts +16 -0
  26. package/src/model/Ad4mModel.test.ts +79 -0
  27. package/src/model/Ad4mModel.ts +14 -6
  28. package/src/model/ModelQueryBuilder.ts +13 -3
  29. package/src/model/query-common.ts +20 -1
  30. package/src/model/query-sparql.ts +28 -1
  31. package/src/model/shacl-gen.ts +12 -0
  32. package/src/model/shacl-roundtrip.test.ts +71 -0
  33. package/src/model/types.ts +96 -1
  34. package/src/perspectives/AutoProcessor.ts +8 -0
  35. package/src/perspectives/FlowInstance.ts +39 -13
  36. package/src/perspectives/FlowModels.ts +8 -2
  37. package/src/perspectives/PerspectiveClient.ts +28 -0
  38. package/src/perspectives/PerspectiveProxy.test.ts +154 -0
  39. package/src/perspectives/PerspectiveProxy.ts +84 -5
  40. package/src/perspectives/WakerSubscriptionManager.test.ts +199 -0
  41. package/src/perspectives/WakerSubscriptionManager.ts +197 -9
@@ -1,10 +1,10 @@
1
1
  /**
2
2
  * WakerSubscriptionManager — manages live query subscriptions for the waker.
3
3
  *
4
- * Lives in core so it can be imported by both the plugin and integration tests
5
- * without ESM/CJS import issues.
6
- *
7
- * NOTE: keep in sync with plugins/ad4m/wakerSubscriptionManager.ts
4
+ * This is the single implementation: it is exported from `@coasys/ad4m` and
5
+ * used by the integration tests, and the OpenClaw AD4M plugin re-exports this
6
+ * module (`plugins/ad4m/wakerSubscriptionManager.ts`) rather than carrying its
7
+ * own copy. Any behaviour change belongs here.
8
8
  */
9
9
 
10
10
  export interface WakerSubscription {
@@ -47,6 +47,61 @@ export interface WakerSubscriptionManagerOptions {
47
47
  previousSeenMessages?: Record<string, string[]>;
48
48
  /** Optional: provide QuerySubscriptionProxy class directly (avoids require("@coasys/ad4m") at runtime). */
49
49
  QuerySubscriptionProxy?: any;
50
+ /** How long to wait before re-attempting a subscription the executor rejected
51
+ * (default 30000). 0 disables re-attempts. */
52
+ retryPendingMs?: number;
53
+ /**
54
+ * How long the executor gets to answer the subscribe handshake before the
55
+ * attempt is abandoned and queued for re-attempt (default 15000). 0 removes
56
+ * the bound. Covers both `proxy.subscribe()` and `proxy.initialized`: when
57
+ * the executor accepts the socket but never answers, neither settles, and
58
+ * without a deadline the subscription ended up neither active nor pending,
59
+ * so the re-attempt cycle never saw it (#1016).
60
+ */
61
+ subscribeTimeoutMs?: number;
62
+ }
63
+
64
+ /**
65
+ * Add a short cause hint to known subscription failures.
66
+ * The executor needs its main key to register a live query; on a restarted
67
+ * executor whose wallet was never unlocked this surfaces as a bare 403.
68
+ */
69
+ export function hintFor(msg: string): string {
70
+ // "Executor is locked" is the current executor's message; "main key not
71
+ // found" is what older executors (and unrelated key lookups) say for the
72
+ // same locked state. Either way the caller cannot fix it themselves: keys
73
+ // live in memory only, so every restart locks the node again and only its
74
+ // operator can unlock it.
75
+ if (/executor is locked/i.test(msg) || /main key not found/i.test(msg)) {
76
+ return " — the executor is locked (its keys live in memory only, so every restart locks it again). Only the node's operator can unlock it: contact them and ask for unlockAgent, then subscribe again — a pending subscription re-attempts on its own once the node is unlocked";
77
+ }
78
+ if (/timed out after \d+ms/i.test(msg)) {
79
+ return " — the executor accepted the waker's connection but never answered; check that the waker is pointed at the right executor host and API port (executorUrl in the plugin config) and that the node is unlocked";
80
+ }
81
+ return "";
82
+ }
83
+
84
+ /**
85
+ * Reject `promise` after `ms` instead of waiting forever.
86
+ *
87
+ * The pending set only catches rejections. A handshake that hangs — the
88
+ * executor accepted the socket but never answers — settles nothing, so the
89
+ * subscription was recorded nowhere and the caller's tool invocation died at
90
+ * the harness timeout instead (#1016). The underlying promise is left as is:
91
+ * the caller disposes the proxy, so a late answer backs out on its own.
92
+ */
93
+ async function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
94
+ let timer: ReturnType<typeof setTimeout> | undefined;
95
+ try {
96
+ return await Promise.race([
97
+ promise,
98
+ new Promise<never>((_resolve, reject) => {
99
+ timer = setTimeout(() => reject(new Error(message)), ms);
100
+ }),
101
+ ]);
102
+ } finally {
103
+ if (timer) clearTimeout(timer);
104
+ }
50
105
  }
51
106
 
52
107
  export class WakerSubscriptionManager {
@@ -57,9 +112,26 @@ export class WakerSubscriptionManager {
57
112
  private onPersist?: (subscriptions: WakerSubscription[], seenMessages: Record<string, string[]>) => void;
58
113
  private QuerySubscriptionProxyCtor: any;
59
114
  private previousSeenMessages: Record<string, string[]>;
115
+ private retryPendingMs: number;
116
+ private subscribeTimeoutMs: number;
60
117
 
61
118
  private proxies = new Map<string, any>();
62
119
  private activeSubscriptions = new Map<string, WakerSubscription>();
120
+ /** Subscriptions the executor rejected, waiting to be re-attempted. */
121
+ private pendingSubscriptions = new Map<string, WakerSubscription>();
122
+ private retryTimer: ReturnType<typeof setTimeout> | null = null;
123
+ /**
124
+ * Cancellation tokens for in-flight `subscribe()` calls.
125
+ *
126
+ * `subscribe()` awaits `proxy.subscribe()` and `proxy.initialized`; a
127
+ * `dispose()` / `disposeAll()` landing during either await used to leave a
128
+ * live subscription behind, because nothing stopped the resumed call from
129
+ * registering the proxy in `proxies` / `activeSubscriptions` afterwards.
130
+ * `epoch` is bumped by `disposeAll()` (which cannot enumerate in-flight
131
+ * ids), `generations` per id by `dispose()` and by each new `subscribe()`.
132
+ */
133
+ private epoch = 0;
134
+ private generations = new Map<string, number>();
63
135
  private debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
64
136
  /** Per-subscription set of already-processed message addresses (for mention subs)
65
137
  * or serialized result hash (for channel-messages subs). */
@@ -73,6 +145,20 @@ export class WakerSubscriptionManager {
73
145
  this.onPersist = options.onPersist;
74
146
  this.QuerySubscriptionProxyCtor = options.QuerySubscriptionProxy ?? null;
75
147
  this.previousSeenMessages = options.previousSeenMessages ?? {};
148
+ this.retryPendingMs = options.retryPendingMs ?? 30000;
149
+ this.subscribeTimeoutMs = options.subscribeTimeoutMs ?? 15000;
150
+ }
151
+
152
+ /** A token identifying this attempt at subscribing `id`. */
153
+ private beginAttempt(id: string): { epoch: number; gen: number } {
154
+ const gen = (this.generations.get(id) ?? 0) + 1;
155
+ this.generations.set(id, gen);
156
+ return { epoch: this.epoch, gen };
157
+ }
158
+
159
+ /** Whether this attempt has been superseded by a dispose or a newer one. */
160
+ private isStale(id: string, token: { epoch: number; gen: number }): boolean {
161
+ return token.epoch !== this.epoch || this.generations.get(id) !== token.gen;
76
162
  }
77
163
 
78
164
  /**
@@ -82,6 +168,7 @@ export class WakerSubscriptionManager {
82
168
  async subscribe(sub: WakerSubscription): Promise<void> {
83
169
  // Dispose existing subscription with same id if any
84
170
  this.dispose(sub.id, false);
171
+ const token = this.beginAttempt(sub.id);
85
172
 
86
173
  if (!this.QuerySubscriptionProxyCtor) {
87
174
  throw new Error("WakerSubscriptionManager: QuerySubscriptionProxy must be provided via constructor options");
@@ -105,21 +192,60 @@ export class WakerSubscriptionManager {
105
192
  if (proxy.initialized && typeof proxy.initialized.catch === "function") {
106
193
  proxy.initialized.catch(() => {});
107
194
  }
195
+ // One deadline for the whole handshake: `proxy.subscribe()` and the
196
+ // `initialized` promise it resolves share the budget, so a hang in either
197
+ // surfaces as the same loud-but-recoverable failure a rejection does.
198
+ const budgetMs = this.subscribeTimeoutMs;
199
+ const startedAt = Date.now();
200
+ const bounded = <T>(step: Promise<T>, what: string): Promise<T> =>
201
+ budgetMs > 0
202
+ ? withTimeout(
203
+ step,
204
+ Math.max(0, budgetMs - (Date.now() - startedAt)),
205
+ `${what} timed out after ${budgetMs}ms`,
206
+ )
207
+ : step;
108
208
  try {
109
- await proxy.subscribe();
110
- await proxy.initialized;
209
+ await bounded(proxy.subscribe(), "subscribe handshake");
210
+ if (this.isStale(sub.id, token)) {
211
+ try { proxy.dispose(); } catch {}
212
+ return;
213
+ }
214
+ await bounded(proxy.initialized, "subscription initialization");
111
215
  } catch (err: any) {
112
216
  const msg = err?.message ?? String(err);
113
217
  this.logger.warn(
114
218
  `[waker] ${sub.id}: subscription failed — ${msg}`,
115
219
  );
116
220
  try { proxy.dispose(); } catch {}
117
- // Remove from active state so it doesn't get persisted/retried
221
+ // A dispose that landed mid-attempt wins: don't re-queue something the
222
+ // caller has since asked us to forget.
223
+ if (this.isStale(sub.id, token)) return;
224
+ // Remove from active state — it is not listening, so it must not be
225
+ // reported as active or persisted as if it were.
118
226
  this.activeSubscriptions.delete(sub.id);
119
227
  this.seenMessages.delete(sub.id);
120
228
  this.persist();
121
- return; // Don't throw — caller should not crash
229
+ // Keep it pending and re-attempt: the usual cause (locked wallet, executor
230
+ // mid-restart, a handshake the executor never answered) clears on its
231
+ // own, and the caller asked to be enrolled.
232
+ this.pendingSubscriptions.set(sub.id, sub);
233
+ this.scheduleRetry();
234
+ // Throw so callers can report the real outcome. Background callers
235
+ // (auto-subscribe, restore-on-start) catch and log; the subscribe tools
236
+ // turn this into an error result instead of a false "Subscribed" reply.
237
+ throw new Error(
238
+ `Waker subscription ${sub.id} failed: ${msg}${hintFor(msg)}` +
239
+ (this.retryPendingMs > 0
240
+ ? `. Not listening yet — re-attempting every ${Math.round(this.retryPendingMs / 1000)}s; check ad4m_list_waker_subscriptions.`
241
+ : ""),
242
+ );
243
+ }
244
+ if (this.isStale(sub.id, token)) {
245
+ try { proxy.dispose(); } catch {}
246
+ return;
122
247
  }
248
+ this.pendingSubscriptions.delete(sub.id);
123
249
  this.logger.info(`[waker] ${sub.id}: subscription initialized successfully`);
124
250
 
125
251
  // Seed from persisted seen messages so we don't re-wake after restart
@@ -230,6 +356,10 @@ export class WakerSubscriptionManager {
230
356
  }
231
357
  });
232
358
 
359
+ if (this.isStale(sub.id, token)) {
360
+ try { proxy.dispose(); } catch {}
361
+ return;
362
+ }
233
363
  this.proxies.set(sub.id, proxy);
234
364
  this.activeSubscriptions.set(sub.id, sub);
235
365
  this.persist();
@@ -239,11 +369,60 @@ export class WakerSubscriptionManager {
239
369
  );
240
370
  }
241
371
 
372
+ /** Arm the re-attempt timer if pending subscriptions are waiting. */
373
+ private scheduleRetry(): void {
374
+ if (this.retryPendingMs <= 0) return;
375
+ if (this.retryTimer || this.pendingSubscriptions.size === 0) return;
376
+ this.retryTimer = setTimeout(() => {
377
+ this.retryTimer = null;
378
+ void this.retryPending();
379
+ }, this.retryPendingMs);
380
+ if (typeof this.retryTimer.unref === "function") this.retryTimer.unref();
381
+ }
382
+
383
+ /**
384
+ * Re-attempt every subscription the executor rejected.
385
+ * Each attempt that fails puts itself back into the pending set and re-arms
386
+ * the timer, so an agent that asked to be subscribed ends up enrolled once
387
+ * the executor can accept the query.
388
+ */
389
+ async retryPending(): Promise<void> {
390
+ const waiting = Array.from(this.pendingSubscriptions.values());
391
+ if (waiting.length === 0) return;
392
+ this.logger.info(
393
+ `[waker] re-attempting ${waiting.length} pending subscription(s)`,
394
+ );
395
+ const epoch = this.epoch;
396
+ for (const sub of waiting) {
397
+ // A disposeAll() between two awaits must stop the whole sweep, and a
398
+ // dispose() of this id must skip just it.
399
+ if (epoch !== this.epoch) return;
400
+ if (!this.pendingSubscriptions.has(sub.id)) continue;
401
+ this.pendingSubscriptions.delete(sub.id);
402
+ try {
403
+ await this.subscribe(sub);
404
+ this.logger.info(`[waker] ${sub.id}: enrolled on re-attempt`);
405
+ } catch (err: any) {
406
+ // subscribe() already logged, re-queued and re-armed the timer.
407
+ this.logger.debug(
408
+ `[waker] ${sub.id}: still pending — ${err?.message ?? err}`,
409
+ );
410
+ }
411
+ }
412
+ }
413
+
414
+ /** Subscriptions that were rejected and are waiting to be re-attempted. */
415
+ getPending(): WakerSubscription[] {
416
+ return Array.from(this.pendingSubscriptions.values());
417
+ }
418
+
242
419
  /**
243
420
  * Dispose a single subscription.
244
421
  * @param persist — if false, skip calling onPersist (used during batch cleanup).
245
422
  */
246
423
  dispose(id: string, persist = true): void {
424
+ // Invalidate any subscribe() for this id that is still awaiting.
425
+ this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
247
426
  const proxy = this.proxies.get(id);
248
427
  if (proxy) {
249
428
  try {
@@ -259,15 +438,24 @@ export class WakerSubscriptionManager {
259
438
  this.debounceTimers.delete(id);
260
439
  }
261
440
  this.activeSubscriptions.delete(id);
441
+ this.pendingSubscriptions.delete(id);
262
442
  this.seenMessages.delete(id);
263
443
  if (persist) this.persist();
264
444
  }
265
445
 
266
- /** Dispose all active subscriptions. */
446
+ /** Dispose all active subscriptions and drop anything still pending. */
267
447
  disposeAll(): void {
448
+ // Bump the epoch first: in-flight subscribe() calls have no proxy in the
449
+ // map yet, so per-id invalidation alone cannot reach them.
450
+ this.epoch++;
268
451
  for (const [id] of this.proxies) {
269
452
  this.dispose(id, false);
270
453
  }
454
+ this.pendingSubscriptions.clear();
455
+ if (this.retryTimer) {
456
+ clearTimeout(this.retryTimer);
457
+ this.retryTimer = null;
458
+ }
271
459
  }
272
460
 
273
461
  /** Get all active subscriptions. */