@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
@@ -0,0 +1,62 @@
1
+ var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
2
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
3
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
4
+ else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
5
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
6
+ };
7
+ var __metadata = (this && this.__metadata) || function (k, v) {
8
+ if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
9
+ };
10
+ import { Ad4mModel } from "../model/Ad4mModel";
11
+ import { HasMany, Model } from "../model/decorators";
12
+ /**
13
+ * The built-in abstract class `Container { children }` (#1446): what holds
14
+ * other records — a channel, a thread, a post, a call, a document, a board.
15
+ *
16
+ * X is contained in P when `P ad4m://has_child X` exists, whatever P is (an
17
+ * instance of any class, or a node no class describes, such as
18
+ * `ad4m://self`), or when P is an instance of a class whose `children`
19
+ * relation (by name, or aliased to `children`) links X:
20
+ *
21
+ * ```typescript
22
+ * @Model({ name: "Block", implements: [Container] })
23
+ * class Block extends Ad4mModel {
24
+ * @HasMany({ through: "we://child", alias: { Container: "children" } })
25
+ * blocks: string[] = [];
26
+ * }
27
+ *
28
+ * // Messages held by P, through has_child or a Block's we://child:
29
+ * await Message.findAll(perspective, { parent: { id: P } });
30
+ * // Everything that holds X:
31
+ * await Container.findAll(perspective, { parent: { ids: [X], direction: "in" } });
32
+ * ```
33
+ *
34
+ * A row's `children` is everything it holds, merged across its classes. A
35
+ * node no class describes is a row of its own when it holds something by
36
+ * `has_child`. Always scope a `Container` query (`where: { id }`, a
37
+ * `children` filter or `parent`): unscoped, it reads every holder in the
38
+ * perspective.
39
+ *
40
+ * Built in: the executor declares it (mirrors
41
+ * `rust-executor/src/perspectives/hardwired_sdna/container.json`) and reads
42
+ * it by its URI, `ad4m://Container`, so a perspective never stores it and an
43
+ * app class named `Container` does not replace it. `register()` on it writes
44
+ * nothing.
45
+ */
46
+ let Container = class Container extends Ad4mModel {
47
+ constructor() {
48
+ super(...arguments);
49
+ /** What it holds, whatever their class. */
50
+ this.children = [];
51
+ }
52
+ };
53
+ /** The URI the executor reads it by. */
54
+ Container.builtinUri = "ad4m://Container";
55
+ __decorate([
56
+ HasMany({ through: "ad4m://has_child" }),
57
+ __metadata("design:type", Array)
58
+ ], Container.prototype, "children", void 0);
59
+ Container = __decorate([
60
+ Model({ name: "Container", abstract: true })
61
+ ], Container);
62
+ export { Container };
@@ -18,7 +18,7 @@ import { SHACLShape } from "../shacl/SHACLShape";
18
18
  import { SHACLFlow } from "../shacl/SHACLFlow";
19
19
  import type { AddAutoProcessorConfig, InterpretationOverlayInfo, RawScope, RunInterpretationObserveOptions } from "./AutoProcessor";
20
20
  type QueryCallback = (result: AllInstancesResult) => void;
21
- /** A live SPARQL query with its latest result.
21
+ /** A live SPARQL or model query with its latest result.
22
22
  *
23
23
  * `subscribe()` opens the query and resolves once the first result is in;
24
24
  * `onResult()` callbacks then get every later result. The executor sends
@@ -33,7 +33,10 @@ type QueryCallback = (result: AllInstancesResult) => void;
33
33
  */
34
34
  export declare class QuerySubscriptionProxy {
35
35
  #private;
36
- constructor(uuid: string, query: string, client: PerspectiveClient);
36
+ /** With `className`, `query` is a model query (JSON) over that class or
37
+ * union of classes, opened with `modelSubscribe`; results are
38
+ * `{ instances, totalCount }`. Without it, `query` is SPARQL. */
39
+ constructor(uuid: string, query: string, client: PerspectiveClient, className?: string | string[]);
37
40
  /** Open the query; resolves with the first result delivered. */
38
41
  subscribe(): Promise<void>;
39
42
  /** The executor's id for this subscription. */
@@ -336,7 +339,7 @@ export declare class PerspectiveProxy {
336
339
  *
337
340
  * The state is not stored on the graph: the engine derives it from the
338
341
  * signed proposals and keeps what it derived per agent, outside the
339
- * perspective. So no other agent — a co-owner on the same node included —
342
+ * perspective. So no other agent — a co-owner on the same executor included —
340
343
  * can read or write your entries, and a link query never sees them.
341
344
  * `FlowInstance.findAll` / `start` call this for you.
342
345
  */
@@ -31,7 +31,7 @@ function extractNamespaceFromUri(uri) {
31
31
  return uri.substring(0, colonIdx + 1);
32
32
  return uri;
33
33
  }
34
- /** A live SPARQL query with its latest result.
34
+ /** A live SPARQL or model query with its latest result.
35
35
  *
36
36
  * `subscribe()` opens the query and resolves once the first result is in;
37
37
  * `onResult()` callbacks then get every later result. The executor sends
@@ -45,14 +45,20 @@ function extractNamespaceFromUri(uri) {
45
45
  * ```
46
46
  */
47
47
  export class QuerySubscriptionProxy {
48
- constructor(uuid, query, client) {
48
+ /** With `className`, `query` is a model query (JSON) over that class or
49
+ * union of classes, opened with `modelSubscribe`; results are
50
+ * `{ instances, totalCount }`. Without it, `query` is SPARQL. */
51
+ constructor(uuid, query, client, className) {
49
52
  _QuerySubscriptionProxy_instances.add(this);
50
53
  _QuerySubscriptionProxy_live.set(this, void 0);
51
54
  _QuerySubscriptionProxy_callbacks.set(this, new Set());
52
55
  _QuerySubscriptionProxy_initialized.set(this, void 0);
53
56
  _QuerySubscriptionProxy_initResolve.set(this, void 0);
54
57
  _QuerySubscriptionProxy_initReject.set(this, void 0);
55
- __classPrivateFieldSet(this, _QuerySubscriptionProxy_live, new LiveQuery(client, uuid, () => client.subscribeQuery(uuid, query), result => __classPrivateFieldGet(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_deliver).call(this, result)), "f");
58
+ const open = className === undefined
59
+ ? () => client.subscribeQuery(uuid, query)
60
+ : () => client.modelSubscribe(uuid, className, query);
61
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_live, new LiveQuery(client, uuid, open, result => __classPrivateFieldGet(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_deliver).call(this, result)), "f");
56
62
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_initialized, new Promise((resolve, reject) => {
57
63
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_initResolve, resolve, "f");
58
64
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_initReject, reject, "f");
@@ -474,7 +480,7 @@ export class PerspectiveProxy {
474
480
  *
475
481
  * The state is not stored on the graph: the engine derives it from the
476
482
  * signed proposals and keeps what it derived per agent, outside the
477
- * perspective. So no other agent — a co-owner on the same node included —
483
+ * perspective. So no other agent — a co-owner on the same executor included —
478
484
  * can read or write your entries, and a link query never sees them.
479
485
  * `FlowInstance.findAll` / `start` call this for you.
480
486
  */
@@ -11,14 +11,61 @@ export interface WakerSubscription {
11
11
  type: "mention" | "channel-messages";
12
12
  perspective: string;
13
13
  channel: string;
14
+ /** SPARQL, or with `className` a model query (JSON) over that class. */
14
15
  query: string;
16
+ /**
17
+ * The class `query` reads, as a model query. A mention subscription has
18
+ * one, from the executor's `get_mention_waker_config`: the built-in
19
+ * `ad4m://TextContent`; a children subscription has the built-in
20
+ * `ad4m://Container`, from `generate_waker_query` (#1446). Without it
21
+ * `query` is SPARQL.
22
+ */
23
+ className?: string;
24
+ /**
25
+ * A mention subscription's terms (profile names and the DID), from
26
+ * `get_mention_waker_config`. The query matches substrings, so a record
27
+ * wakes only when its text holds one of these as a whole word
28
+ * ({@link holdsAWholeWordTerm}); without them a mention subscription is
29
+ * refused.
30
+ */
31
+ terms?: string[];
15
32
  neighbourhood?: string;
16
33
  }
34
+ /**
35
+ * How much of a record's text the word check reads. Dropping markup costs time
36
+ * quadratic in a run of unclosed `<script>`, `<style>` or `<!--` openers, so a
37
+ * very long text could hold the event loop for seconds, and a row that holds
38
+ * no term is checked again on every result while it is in the window. A term
39
+ * past this many characters does not wake.
40
+ */
41
+ export declare const MENTION_TEXT_LIMIT = 16384;
42
+ /**
43
+ * Whether `text` holds one of `terms` as a whole word, case-insensitively:
44
+ * "Data" is in "hi Data!", "@data" and "Data's turn", not in "metadata" or
45
+ * "database". A term is matched literally (regex characters, quotes) and must
46
+ * not touch a letter, mark, digit or underscore on either side, so a name
47
+ * that starts or ends with punctuation still matches. Same rule as #1459's
48
+ * SPARQL `(?:^|\W)term(?:\W|$)`.
49
+ *
50
+ * The rule runs on the visible text only: in HTML, tags and attributes are
51
+ * dropped and entities decoded first. A mention's target attribute
52
+ * (`href`, `data-id`, `data-did`) matches an exact, case-sensitive DID term, which
53
+ * is how a mention by DID is found when the DID is not in the visible text.
54
+ *
55
+ * The mention query's `contains` matches substrings (model query has no word
56
+ * match); this is the check that keeps "data" from waking on "metadata".
57
+ * It reads the first {@link MENTION_TEXT_LIMIT} characters only.
58
+ */
59
+ export declare function holdsAWholeWordTerm(text: string, terms: string[]): boolean;
17
60
  /** Per-message parent resolution result for mention subscriptions. */
18
61
  export interface MentionMessage {
19
- /** The message's expression address (source of the body link). */
62
+ /** The mentioned record's id. */
20
63
  address: string;
21
- /** All parent addresses this message belongs to (channels, conversations, etc.). */
64
+ /**
65
+ * Every container holding it (channels, threads, calls, blocks): whatever
66
+ * links it with `ad4m://has_child`, and every instance of a class whose
67
+ * `children` relation links it. A record can sit in several.
68
+ */
22
69
  parents: string[];
23
70
  /**
24
71
  * Everything above the parents, nearest first: their parents, theirs, and so on up to the
@@ -46,9 +93,13 @@ export interface WakerSubscriptionManagerOptions {
46
93
  * what the levels hold. 0 reports parents only.
47
94
  */
48
95
  ancestorDepth?: number;
49
- /** Called when a subscription fires (after debounce). Return value is ignored.
50
- * For mention subs, `mentions` contains per-message parent info. */
51
- onWake: (sub: WakerSubscription, result: any, mentions?: MentionMessage[]) => void;
96
+ /**
97
+ * Called when a subscription fires (after debounce). For mention subs, `mentions` holds every
98
+ * mention not yet delivered, with its parent info. Resolve `false` (or reject) when the wake did
99
+ * not reach the agent: those mentions stay out of the persisted seen set and are offered again
100
+ * after `retryWakeMs`, so a wake lost to a restarting gateway is not lost for good.
101
+ */
102
+ onWake: (sub: WakerSubscription, result: any, mentions?: MentionMessage[]) => void | boolean | Promise<void | boolean>;
52
103
  /** Called when the active subscription list changes (for persistence). */
53
104
  onPersist?: (subscriptions: WakerSubscription[], seenMessages: Record<string, string[]>) => void;
54
105
  /** Previously persisted seen message IDs per subscription. Seeds seenMessages on resubscribe to avoid duplicate wakes. */
@@ -67,6 +118,9 @@ export interface WakerSubscriptionManagerOptions {
67
118
  * so the re-attempt cycle never saw it (#1016).
68
119
  */
69
120
  subscribeTimeoutMs?: number;
121
+ /** First delay before offering an undelivered mention wake again (default 5000); doubles per
122
+ * failed attempt, up to 60000. */
123
+ retryWakeMs?: number;
70
124
  }
71
125
  /**
72
126
  * Add a short cause hint to known subscription failures.
@@ -85,6 +139,7 @@ export declare class WakerSubscriptionManager {
85
139
  private previousSeenMessages;
86
140
  private retryPendingMs;
87
141
  private subscribeTimeoutMs;
142
+ private retryWakeMs;
88
143
  private proxies;
89
144
  private activeSubscriptions;
90
145
  /** Subscriptions the executor rejected, waiting to be re-attempted. */
@@ -106,13 +161,27 @@ export declare class WakerSubscriptionManager {
106
161
  /** Per-subscription set of already-processed message addresses (for mention subs)
107
162
  * or serialized result hash (for channel-messages subs). */
108
163
  private seenMessages;
164
+ /**
165
+ * Per mention subscription: the addresses whose wake was delivered, or that were history when
166
+ * the subscription opened. This, not `seenMessages`, is what gets persisted: an address joins
167
+ * `seenMessages` as soon as it is read, while its parents are still resolving and before any
168
+ * wake, so a restart in between must not take it as done.
169
+ */
170
+ private delivered;
171
+ /**
172
+ * Per mention subscription: mentions read but whose wake has not been delivered yet, keyed by
173
+ * address. They accumulate across a debounce window, so one wake names all of them.
174
+ */
175
+ private undelivered;
176
+ /** Failed wake attempts in a row per subscription, for the retry backoff. */
177
+ private wakeFailures;
109
178
  constructor(options: WakerSubscriptionManagerOptions);
110
179
  /** A token identifying this attempt at subscribing `id`. */
111
180
  private beginAttempt;
112
181
  /** Whether this attempt has been superseded by a dispose or a newer one. */
113
182
  private isStale;
114
183
  /**
115
- * Create a live SPARQL subscription.
184
+ * Create a live subscription: SPARQL, or a model query when `sub.className` is set.
116
185
  * If a subscription with the same id already exists, it is disposed first.
117
186
  */
118
187
  subscribe(sub: WakerSubscription): Promise<void>;
@@ -132,21 +201,34 @@ export declare class WakerSubscriptionManager {
132
201
  * @param persist — if false, skip calling onPersist (used during batch cleanup).
133
202
  */
134
203
  dispose(id: string, persist?: boolean): void;
204
+ /** (Re)start the timer that offers `sub`'s undelivered mentions to `onWake` after `delayMs`. */
205
+ private scheduleMentionWake;
206
+ /**
207
+ * Offer every undelivered mention of `sub` in one wake. On delivery they join the persisted
208
+ * seen set; on failure they stay undelivered and are offered again with backoff.
209
+ */
210
+ private deliverMentions;
135
211
  /** Dispose all active subscriptions and drop anything still pending. */
136
212
  disposeAll(): void;
137
213
  /** Get all active subscriptions. */
138
214
  getActive(): WakerSubscription[];
139
215
  /** Check if a subscription exists. */
140
216
  has(id: string): boolean;
141
- /** Resolve one containment level in one query; skip unsafe IRI tokens and treat failures as none. */
217
+ /**
218
+ * Everything holding any of `addresses`, in one model query: a `Container`
219
+ * step in (#1446). The executor follows `ad4m://has_child` on any node and
220
+ * each class's own `children` relation on its instances, so the waker
221
+ * looks up no predicate. Failures count as none.
222
+ */
142
223
  private parentsOf;
143
224
  /**
144
- * The chain above an item's parents, a level at a time, nearest first, up to `ancestorDepth`.
145
- *
146
- * Breadth-first with a visited set: containment is a graph, not a tree — an item can sit in two
147
- * places, and nothing stops a cycle — so each address is reported once and the walk always ends.
148
- * Each level uses one batched parent lookup, bounded by the depth.
225
+ * The chain above an item's parents, nearest first, up to `ancestorDepth` levels: one
226
+ * transitive `Container` walk in from the parents, bounded by `maxDepth`. The executor walks
227
+ * containment as a graph, so each address comes once however many paths reach it, and a
228
+ * cycle ends. The item and its parents are never reported as ancestors.
149
229
  */
150
230
  private ancestorsOf;
231
+ /** The ids of the `Container` rows `parent` scopes to, in the executor's order. */
232
+ private containers;
151
233
  private persist;
152
234
  }