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

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 (97) hide show
  1. package/lib/index.cjs +610 -208
  2. package/lib/index.js +607 -209
  3. package/lib/src/Ad4mClient.d.ts +7 -0
  4. package/lib/src/Ad4mClient.js +9 -0
  5. package/lib/src/agent/AgentClient.d.ts +16 -1
  6. package/lib/src/agent/AgentClient.js +21 -2
  7. package/lib/src/ai/AITypes.d.ts +6 -2
  8. package/lib/src/apiClient.d.ts +13 -0
  9. package/lib/src/apiClient.js +67 -12
  10. package/lib/src/generated/api/Apps.d.ts +4 -0
  11. package/lib/src/generated/api/AuthInfo.d.ts +4 -0
  12. package/lib/src/generated/api/Events.d.ts +10 -12
  13. package/lib/src/generated/api/FlowStateChangedEvent.d.ts +3 -2
  14. package/lib/src/generated/api/Model.d.ts +4 -0
  15. package/lib/src/generated/api/ModelApi.d.ts +5 -1
  16. package/lib/src/generated/api/ModelApiInput.d.ts +7 -1
  17. package/lib/src/generated/api/Notification.d.ts +5 -1
  18. package/lib/src/generated/api/NotificationInput.d.ts +4 -0
  19. package/lib/src/generated/api/PerspectiveEvent.d.ts +8 -0
  20. package/lib/src/generated/api/{PerspectiveLinkWithOwner.d.ts → PerspectiveLinkEvent.d.ts} +4 -2
  21. package/lib/src/generated/api/{PerspectiveLinkUpdatedWithOwner.d.ts → PerspectiveLinkUpdatedEvent.d.ts} +4 -2
  22. package/lib/src/generated/api/PerspectiveRemovedEvent.d.ts +7 -0
  23. package/lib/src/generated/api/RequestCapabilityRequest.d.ts +1 -0
  24. package/lib/src/generated/api/RpcMethods.d.ts +10 -1
  25. package/lib/src/generated/api/RuntimeInfo.d.ts +5 -0
  26. package/lib/src/generated/api/RuntimeUpdateNotificationParams.d.ts +6 -1
  27. package/lib/src/generated/api/UsersRevokeAllSessionsParams.d.ts +7 -0
  28. package/{src/generated/api/PerspectiveRemovedWithOwner.ts → lib/src/generated/api/UsersRevokeAllSessionsParams.js} +1 -2
  29. package/lib/src/index.d.ts +1 -0
  30. package/lib/src/index.js +1 -0
  31. package/lib/src/model/Ad4mModel.js +45 -18
  32. package/lib/src/model/ModelQueryBuilder.d.ts +7 -3
  33. package/lib/src/model/ModelQueryBuilder.js +9 -4
  34. package/lib/src/model/query-common.js +7 -1
  35. package/lib/src/model/types.d.ts +45 -2
  36. package/lib/src/model/types.js +8 -0
  37. package/lib/src/perspectives/Container.d.ts +41 -0
  38. package/lib/src/perspectives/Container.js +62 -0
  39. package/lib/src/perspectives/PerspectiveProxy.d.ts +6 -3
  40. package/lib/src/perspectives/PerspectiveProxy.js +10 -4
  41. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +94 -12
  42. package/lib/src/perspectives/WakerSubscriptionManager.js +276 -75
  43. package/lib/src/runtime/RuntimeClient.d.ts +6 -3
  44. package/lib/src/runtime/RuntimeClient.js +2 -0
  45. package/lib/src/runtime/RuntimeTypes.d.ts +7 -1
  46. package/package.json +2 -2
  47. package/src/Ad4mClient.test.ts +54 -19
  48. package/src/Ad4mClient.ts +10 -0
  49. package/src/agent/AgentClient.ts +26 -2
  50. package/src/ai/AITypes.ts +6 -2
  51. package/src/apiClient.test.ts +128 -3
  52. package/src/apiClient.ts +64 -11
  53. package/src/generated/api/Apps.ts +6 -1
  54. package/src/generated/api/AuthInfo.ts +6 -1
  55. package/src/generated/api/Events.ts +10 -12
  56. package/src/generated/api/FlowStateChangedEvent.ts +3 -2
  57. package/src/generated/api/Model.ts +4 -0
  58. package/src/generated/api/ModelApi.ts +5 -1
  59. package/src/generated/api/ModelApiInput.ts +8 -1
  60. package/src/generated/api/Notification.ts +5 -1
  61. package/src/generated/api/NotificationInput.ts +6 -1
  62. package/src/generated/api/PerspectiveEvent.ts +7 -0
  63. package/src/generated/api/{PerspectiveLinkUpdatedWithOwner.ts → PerspectiveLinkEvent.ts} +4 -1
  64. package/src/generated/api/PerspectiveLinkUpdatedEvent.ts +7 -0
  65. package/src/generated/api/PerspectiveRemovedEvent.ts +6 -0
  66. package/src/generated/api/RequestCapabilityRequest.ts +1 -1
  67. package/src/generated/api/RpcMethods.ts +4 -1
  68. package/src/generated/api/RuntimeInfo.ts +6 -1
  69. package/src/generated/api/RuntimeUpdateNotificationParams.ts +7 -1
  70. package/src/generated/api/UsersRevokeAllSessionsParams.ts +8 -0
  71. package/src/index.ts +1 -0
  72. package/src/model/Ad4mModel.ts +51 -19
  73. package/src/model/ModelQueryBuilder.ts +9 -6
  74. package/src/model/containment-scope.test.ts +104 -0
  75. package/src/model/query-common.ts +10 -1
  76. package/src/model/types.ts +56 -2
  77. package/src/perspectives/Container.test.ts +65 -0
  78. package/src/perspectives/Container.ts +46 -0
  79. package/src/perspectives/PerspectiveProxy.test.ts +11 -0
  80. package/src/perspectives/PerspectiveProxy.ts +10 -4
  81. package/src/perspectives/WakerSubscriptionManager.test.ts +400 -82
  82. package/src/perspectives/WakerSubscriptionManager.ts +321 -85
  83. package/src/perspectives/link-updated-type.test.ts +2 -2
  84. package/src/perspectives/listener-leaks.test.ts +3 -3
  85. package/src/runtime/RuntimeClient.ts +6 -3
  86. package/src/runtime/RuntimeTypes.ts +10 -1
  87. package/lib/src/generated/api/MessageReceivedEvent.d.ts +0 -7
  88. package/lib/src/generated/api/PerspectiveRemovedWithOwner.d.ts +0 -5
  89. package/lib/src/generated/api/PerspectiveWithOwner.d.ts +0 -6
  90. package/lib/src/generated/api/PerspectiveWithOwner.js +0 -1
  91. package/src/generated/api/MessageReceivedEvent.ts +0 -7
  92. package/src/generated/api/PerspectiveLinkWithOwner.ts +0 -4
  93. package/src/generated/api/PerspectiveWithOwner.ts +0 -4
  94. /package/lib/src/generated/api/{MessageReceivedEvent.js → PerspectiveEvent.js} +0 -0
  95. /package/lib/src/generated/api/{PerspectiveLinkUpdatedWithOwner.js → PerspectiveLinkEvent.js} +0 -0
  96. /package/lib/src/generated/api/{PerspectiveLinkWithOwner.js → PerspectiveLinkUpdatedEvent.js} +0 -0
  97. /package/lib/src/generated/api/{PerspectiveRemovedWithOwner.js → PerspectiveRemovedEvent.js} +0 -0
@@ -7,7 +7,7 @@ import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSON
7
7
  import { buildSPARQLQuery, valueToLiteralIri, effectiveLiteralStorage } from "./query-sparql";
8
8
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
9
9
  import { normalizeValue, } from "./hydration";
10
- import { isTraverseScope } from "./types";
10
+ import { isContainedScope, isContainmentTraversal, isTraverseScope } from "./types";
11
11
  // ---------------------------------------------------------------------------
12
12
  // Helpers for Rust-side include resolution
13
13
  // ---------------------------------------------------------------------------
@@ -348,6 +348,24 @@ function jsonToModelInstance(ModelClass, perspective, json, include, properties)
348
348
  }
349
349
  return instance;
350
350
  }
351
+ /**
352
+ * Put `childId` under `parent`. A containment scope `{ id }` writes through the
353
+ * built-in `Container` (#1446): the executor runs the adder of the parent's own
354
+ * `children` relation when its class has one (a block's `we://child`), else
355
+ * writes `ad4m://has_child`. The other forms write their one predicate.
356
+ */
357
+ async function linkToParent(perspective, parent, childCtor, childId, batchId) {
358
+ if (isContainedScope(parent)) {
359
+ await perspective.updateSubject("ad4m://Container", parent.id, { children: { action: "adder", value: [childId] } }, batchId);
360
+ return;
361
+ }
362
+ const link = new Link({
363
+ source: parent.id,
364
+ predicate: resolveParentPredicate(parent, childCtor),
365
+ target: childId,
366
+ });
367
+ await perspective.add(link, 'shared', batchId);
368
+ }
351
369
  /**
352
370
  * Base class for defining data models in AD4M.
353
371
  *
@@ -1005,7 +1023,28 @@ export class Ad4mModel {
1005
1023
  query = { ...query, include: { ...expanded, ...query.include } };
1006
1024
  }
1007
1025
  const queryInput = {};
1008
- if (query.parent) {
1026
+ if (query.parent && isContainedScope(query.parent)) {
1027
+ // Containment: the executor resolves the predicates from the installed
1028
+ // classes, so only the id travels.
1029
+ queryInput.parent = { id: query.parent.id };
1030
+ }
1031
+ else if (query.parent && isContainmentTraversal(query.parent)) {
1032
+ // A traversal over containment: no predicate travels either.
1033
+ const t = query.parent;
1034
+ const traverse = { ids: t.ids };
1035
+ if (t.transitive !== undefined)
1036
+ traverse.transitive = t.transitive;
1037
+ if (t.direction !== undefined)
1038
+ traverse.direction = t.direction;
1039
+ if (t.limitPerAnchor !== undefined)
1040
+ traverse.limitPerAnchor = t.limitPerAnchor;
1041
+ if (t.levels !== undefined)
1042
+ traverse.levels = t.levels;
1043
+ if (t.maxDepth !== undefined)
1044
+ traverse.maxDepth = t.maxDepth;
1045
+ queryInput.parent = traverse;
1046
+ }
1047
+ else if (query.parent) {
1009
1048
  const parentPredicate = resolveParentPredicate(query.parent, this);
1010
1049
  // A traversal keeps its own shape on the wire: the executor reads `ids`,
1011
1050
  // and flattening it to one `id` here is how a request for a whole level
@@ -1029,6 +1068,8 @@ export class Ad4mModel {
1029
1068
  traverse.limitPerAnchor = t.limitPerAnchor;
1030
1069
  if (t.levels !== undefined)
1031
1070
  traverse.levels = t.levels;
1071
+ if (t.maxDepth !== undefined)
1072
+ traverse.maxDepth = t.maxDepth;
1032
1073
  queryInput.parent = traverse;
1033
1074
  }
1034
1075
  else {
@@ -1993,14 +2034,7 @@ export class Ad4mModel {
1993
2034
  if (options?.parent && !options?.batchId) {
1994
2035
  const batchId = await perspective.createBatch();
1995
2036
  await instance.save(batchId);
1996
- const parent = requireSingleParent(options.parent);
1997
- const predicate = resolveParentPredicate(parent, this);
1998
- const link = new Link({
1999
- source: parent.id,
2000
- predicate,
2001
- target: instance.id,
2002
- });
2003
- await perspective.add(link, 'shared', batchId);
2037
+ await linkToParent(perspective, requireSingleParent(options.parent), this, instance.id, batchId);
2004
2038
  await perspective.commitBatch(batchId);
2005
2039
  // Hydrate the instance now that the batch has been committed (mirrors the
2006
2040
  // behaviour of save() when it manages its own batch).
@@ -2010,14 +2044,7 @@ export class Ad4mModel {
2010
2044
  await instance.save(options?.batchId);
2011
2045
  // Create parent → child link if a parent scope was provided
2012
2046
  if (options?.parent) {
2013
- const parent = requireSingleParent(options.parent);
2014
- const predicate = resolveParentPredicate(parent, this);
2015
- const link = new Link({
2016
- source: parent.id,
2017
- predicate,
2018
- target: instance.id,
2019
- });
2020
- await perspective.add(link, 'shared', options?.batchId);
2047
+ await linkToParent(perspective, requireSingleParent(options.parent), this, instance.id, options?.batchId);
2021
2048
  }
2022
2049
  return instance;
2023
2050
  }
@@ -115,9 +115,10 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
115
115
  * 3. **String id + model class** — same metadata scan (or field lookup if
116
116
  * options include `field`).
117
117
  * 4. **String id + string predicate** — raw escape hatch, no metadata lookup.
118
- *
119
- * Passing a plain string id with no second argument throws because the
120
- * predicate cannot be resolved without a model class.
118
+ * 5. **String id alone** — containment through the built-in `Container`:
119
+ * the id's `ad4m://has_child` targets, and the targets of the `children`
120
+ * relation of every class the id is an instance of. The executor
121
+ * resolves the predicates; nothing is looked up here.
121
122
  *
122
123
  * @param idOrInstance - The parent's expression URI **or** an Ad4mModel instance
123
124
  * @param modelOrPredicate - A model class (predicate auto-resolved) **or** a raw predicate string
@@ -140,6 +141,9 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
140
141
  *
141
142
  * // String id + raw predicate (escape hatch)
142
143
  * Recipe.query(perspective).parent(cookbookId, "cookbook://recipe").get();
144
+ *
145
+ * // String id alone: whatever cookbookId contains
146
+ * Recipe.query(perspective).parent(cookbookId).get();
143
147
  * ```
144
148
  */
145
149
  parent(idOrInstance: string | Ad4mModel, modelOrPredicate?: typeof Ad4mModel | string | {
@@ -162,9 +162,10 @@ export class ModelQueryBuilder {
162
162
  * 3. **String id + model class** — same metadata scan (or field lookup if
163
163
  * options include `field`).
164
164
  * 4. **String id + string predicate** — raw escape hatch, no metadata lookup.
165
- *
166
- * Passing a plain string id with no second argument throws because the
167
- * predicate cannot be resolved without a model class.
165
+ * 5. **String id alone** — containment through the built-in `Container`:
166
+ * the id's `ad4m://has_child` targets, and the targets of the `children`
167
+ * relation of every class the id is an instance of. The executor
168
+ * resolves the predicates; nothing is looked up here.
168
169
  *
169
170
  * @param idOrInstance - The parent's expression URI **or** an Ad4mModel instance
170
171
  * @param modelOrPredicate - A model class (predicate auto-resolved) **or** a raw predicate string
@@ -187,6 +188,9 @@ export class ModelQueryBuilder {
187
188
  *
188
189
  * // String id + raw predicate (escape hatch)
189
190
  * Recipe.query(perspective).parent(cookbookId, "cookbook://recipe").get();
191
+ *
192
+ * // String id alone: whatever cookbookId contains
193
+ * Recipe.query(perspective).parent(cookbookId).get();
190
194
  * ```
191
195
  */
192
196
  parent(idOrInstance, modelOrPredicate, options) {
@@ -214,7 +218,8 @@ export class ModelQueryBuilder {
214
218
  this.queryParams.parent = { id, model: idOrInstance.constructor, ...(field && { field }) };
215
219
  }
216
220
  else {
217
- throw new Error('parent() called with a string id requires a second argument: either a model class or a predicate string');
221
+ // String id alone → containment form of Scope
222
+ this.queryParams.parent = { id };
218
223
  }
219
224
  return this;
220
225
  }
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Shared query helpers used by both the Prolog and SPARQL query pipelines.
3
3
  */
4
- import { isTraverseScope } from "./types";
4
+ import { isContainedScope, isContainmentTraversal, isTraverseScope } from "./types";
5
5
  import { getRelationsMetadata } from "./decorators";
6
6
  /**
7
7
  * Resolves the predicate for a parent query.
@@ -31,6 +31,12 @@ export function resolveParentPredicate(parent, childCtor) {
31
31
  // Raw form — explicit predicate
32
32
  if ('predicate' in parent)
33
33
  return parent.predicate;
34
+ // Containment form — one predicate per containment edge, resolved by the
35
+ // executor from the installed classes. There is no single one to return.
36
+ if (isContainedScope(parent) || isContainmentTraversal(parent)) {
37
+ throw new Error('parent(): a containment scope { id } names no single predicate; the executor resolves ' +
38
+ 'it. Use the model query path (findAll / query / subscribe) to read it.');
39
+ }
34
40
  // Model form — resolve from relation metadata
35
41
  const { model } = parent;
36
42
  const relMeta = getRelationsMetadata(model);
@@ -90,6 +90,13 @@ export type Order = {
90
90
  * **Traverse form** — bounded traversal from one or more anchors, for reading
91
91
  * a tree rather than one node's children. Read-only: AutoProcessor's write
92
92
  * scopes reject it, because it names no single parent to write under.
93
+ *
94
+ * **Containment form** — `{ id }` alone: everything contained in `id`, through
95
+ * the built-in `Container`. That is the targets of `id`'s `ad4m://has_child`
96
+ * links, whatever `id` is, and the targets of the `children` relation (by name,
97
+ * or aliased to `children`) of every class `id` is an instance of. The caller
98
+ * names no class and no predicate; the executor resolves them from the
99
+ * installed classes. See {@link ContainedScope}.
93
100
  */
94
101
  export type Scope = {
95
102
  model: typeof Ad4mModel;
@@ -98,7 +105,22 @@ export type Scope = {
98
105
  } | {
99
106
  id: string;
100
107
  predicate: string;
101
- } | TraverseScope;
108
+ } | TraverseScope | ContainedScope;
109
+ /**
110
+ * Contained in `id`, through `Container`: `{ id }` and nothing else. A
111
+ * misspelt extra field (`{ id, predicat }`) is an error in the executor,
112
+ * never a containment read.
113
+ */
114
+ export interface ContainedScope {
115
+ id: string;
116
+ predicate?: never;
117
+ model?: never;
118
+ field?: never;
119
+ }
120
+ /** Whether this traversal follows containment rather than a named predicate. */
121
+ export declare function isContainmentTraversal(scope: Scope): scope is TraverseByContainment;
122
+ /** Whether this scope is the containment form, `{ id }` alone. */
123
+ export declare function isContainedScope(scope: Scope): scope is ContainedScope;
102
124
  /**
103
125
  * Walk a predicate from several anchors at once, and optionally all the way
104
126
  * down.
@@ -111,7 +133,23 @@ export type Scope = {
111
133
  * or by the model and relation that own it. See {@link TraverseByPredicate} and
112
134
  * {@link TraverseByModel}.
113
135
  */
114
- export type TraverseScope = TraverseByPredicate | TraverseByModel;
136
+ export type TraverseScope = TraverseByPredicate | TraverseByModel | TraverseByContainment;
137
+ /**
138
+ * A traversal over containment, through the built-in `Container`: it names no
139
+ * predicate, and follows every edge the executor resolves from the installed
140
+ * classes — `ad4m://has_child` on any node, and each class's own `children`
141
+ * relation on its instances. `direction: 'in'` from a record reaches whatever
142
+ * holds it: `Container.findAll(p, { parent: { ids: [x], direction: 'in' } })`.
143
+ *
144
+ * The rows are the queried class; the nodes a transitive walk passes through
145
+ * are any container. With no `order`, a transitive walk's rows come nearest
146
+ * first. `levels` is refused on it, and so is `limitPerAnchor` on a
147
+ * transitive one; bound it with `maxDepth`.
148
+ */
149
+ export interface TraverseByContainment extends TraverseOptions {
150
+ predicate?: never;
151
+ model?: never;
152
+ }
115
153
  /** A traversal naming its predicate literally, as the Raw scope does. */
116
154
  export interface TraverseByPredicate extends TraverseOptions {
117
155
  predicate: string;
@@ -181,6 +219,11 @@ export interface TraverseOptions {
181
219
  * every depth.
182
220
  */
183
221
  limitPerAnchor?: number;
222
+ /**
223
+ * With `transitive`, stop the walk after this many hops (`1` is the direct
224
+ * neighbours). Refused without `transitive` and alongside `levels`.
225
+ */
226
+ maxDepth?: number;
184
227
  /**
185
228
  * Walk the relation level by level, keeping this many results per anchor at each depth —
186
229
  * `[10, 5, 3]` is "ten replies, five under each of those, three under each of *those*".
@@ -5,6 +5,14 @@
5
5
  * (`query-utils.ts`, `decorators.ts`, etc.) can import types without
6
6
  * creating circular runtime dependencies on `Ad4mModel.ts`.
7
7
  */
8
+ /** Whether this traversal follows containment rather than a named predicate. */
9
+ export function isContainmentTraversal(scope) {
10
+ return isTraverseScope(scope) && !('predicate' in scope && scope.predicate) && !('model' in scope && scope.model);
11
+ }
12
+ /** Whether this scope is the containment form, `{ id }` alone. */
13
+ export function isContainedScope(scope) {
14
+ return !isTraverseScope(scope) && !('predicate' in scope) && !('model' in scope);
15
+ }
8
16
  /**
9
17
  * Whether this scope is a traversal rather than a single named parent.
10
18
  *
@@ -0,0 +1,41 @@
1
+ import { Ad4mModel } from "../model/Ad4mModel";
2
+ /**
3
+ * The built-in abstract class `Container { children }` (#1446): what holds
4
+ * other records — a channel, a thread, a post, a call, a document, a board.
5
+ *
6
+ * X is contained in P when `P ad4m://has_child X` exists, whatever P is (an
7
+ * instance of any class, or a node no class describes, such as
8
+ * `ad4m://self`), or when P is an instance of a class whose `children`
9
+ * relation (by name, or aliased to `children`) links X:
10
+ *
11
+ * ```typescript
12
+ * @Model({ name: "Block", implements: [Container] })
13
+ * class Block extends Ad4mModel {
14
+ * @HasMany({ through: "we://child", alias: { Container: "children" } })
15
+ * blocks: string[] = [];
16
+ * }
17
+ *
18
+ * // Messages held by P, through has_child or a Block's we://child:
19
+ * await Message.findAll(perspective, { parent: { id: P } });
20
+ * // Everything that holds X:
21
+ * await Container.findAll(perspective, { parent: { ids: [X], direction: "in" } });
22
+ * ```
23
+ *
24
+ * A row's `children` is everything it holds, merged across its classes. A
25
+ * node no class describes is a row of its own when it holds something by
26
+ * `has_child`. Always scope a `Container` query (`where: { id }`, a
27
+ * `children` filter or `parent`): unscoped, it reads every holder in the
28
+ * perspective.
29
+ *
30
+ * Built in: the executor declares it (mirrors
31
+ * `rust-executor/src/perspectives/hardwired_sdna/container.json`) and reads
32
+ * it by its URI, `ad4m://Container`, so a perspective never stores it and an
33
+ * app class named `Container` does not replace it. `register()` on it writes
34
+ * nothing.
35
+ */
36
+ export declare class Container extends Ad4mModel {
37
+ /** The URI the executor reads it by. */
38
+ static readonly builtinUri = "ad4m://Container";
39
+ /** What it holds, whatever their class. */
40
+ children: string[];
41
+ }
@@ -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
  }