@mnmal-ai/substrate 1.0.0-alpha.10 → 1.0.0-alpha.12
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.
- package/README.md +4 -2
- package/dist/{boot-store-BVqfFxh1.js → boot-store-DHv9H1Gr.js} +170 -69
- package/dist/{bridge-Cp4PaIYO.d.ts → bridge-DQyQ6Qhn.d.ts} +1 -1
- package/dist/{cli-hSCBywhE.js → cli-_UNdneXr.js} +44 -24
- package/dist/client.d.ts +3 -4
- package/dist/client.js +3 -3
- package/dist/{errors-7mycvNGq.d.ts → errors-xP9Mo7Q1.d.ts} +38 -4
- package/dist/{index-DgSfwx7M.d.ts → index-baF5A5jU.d.ts} +1 -1
- package/dist/pack.d.ts +2 -2
- package/dist/pack.js +1 -1
- package/dist/{pg-edges-store-Lxsl5ZnK.js → pg-edges-store-B4FSN9yp.js} +72 -9
- package/dist/{plugin-CtwOINCM.js → plugin-BLm5IRdX.js} +2 -2
- package/dist/proposals-bootstrap.js +2 -2
- package/dist/proposals.d.ts +2 -3
- package/dist/proposals.js +1 -1
- package/dist/recall-bootstrap.js +2 -2
- package/dist/recall.d.ts +10 -11
- package/dist/recall.js +2 -2
- package/dist/{repl-DqfHelK7.js → repl-DUJGBwie.js} +25 -25
- package/dist/{row-BKKCXIG6.d.ts → row-Cu_iRhcR.d.ts} +57 -10
- package/dist/{run-B5dTbZ3g.js → run-BpsTNvdI.js} +539 -145
- package/dist/{dataset-CejF-Fr_.d.ts → schema-oXfQyo0s.d.ts} +2455 -1589
- package/dist/sdk.d.ts +108 -34
- package/dist/sdk.js +4 -4
- package/dist/{src-CqT-QWZ_.js → src-Bew_JvTo.js} +32 -16
- package/dist/{src-Da0t6si5.js → src-Bi3NhEsT.js} +1 -1
- package/dist/{src-5SJ5GEIM.js → src-C4t1Gy-m.js} +4844 -1367
- package/dist/{src-7CUSMK66.js → src-CHND7-Pm.js} +7 -3
- package/dist/src-CSe2tJDf.js +6940 -0
- package/dist/{src-Bi849yhn.js → src-CzhKLsOV.js} +175 -91
- package/dist/{src-hZb8wfvg.js → src-DWqzrm3O.js} +400 -284
- package/dist/substrate-admin.js +1 -1
- package/dist/substrate.js +1 -1
- package/dist/testing.d.ts +255 -90
- package/dist/testing.js +6 -23
- package/dist/{ws-ByZyHk7m.d.ts → ws-Dx3A2B4U.d.ts} +2 -3
- package/package.json +20 -20
- package/dist/schema-DoSc-4ig.d.ts +0 -470
- package/dist/src-CyvV7dCK.js +0 -4333
|
@@ -1,1888 +1,2754 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
1
|
+
//#region ../../packages/substrate-types/src/core.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Core substrate-neutral types. Spec: §4.5 Dataset, §4.6 Edge.
|
|
4
|
+
*/
|
|
5
|
+
type Id = string | number;
|
|
6
|
+
interface Row {
|
|
7
|
+
id: Id;
|
|
8
|
+
_deletedAt?: Date | null;
|
|
7
9
|
/**
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
* A plain object rather than a Map: `Identity` is JSON-serialised into the
|
|
13
|
-
* SSE stream ticket, and a Map would arrive as `{}` on the far side.
|
|
14
|
-
*
|
|
15
|
-
* A bare `{ id }` with no grant (direct-call tests, system actors) is the
|
|
16
|
-
* no-claim case: `grantOf` resolves it to `null`, and the engine's grant
|
|
17
|
-
* gate then admits every namespace. An authenticator for remote callers
|
|
18
|
-
* must therefore always set `grants`, `{}` for none.
|
|
10
|
+
* Server-managed row-lifecycle metadata, set by autoCRUD on create/update
|
|
11
|
+
* and projected on every read alongside `id`. Each dataset stores it in
|
|
12
|
+
* its own way.
|
|
19
13
|
*/
|
|
20
|
-
|
|
21
|
-
|
|
14
|
+
_metadata?: RowMetadata;
|
|
15
|
+
/** Per-row walk aggregates (`params.agg`). */
|
|
16
|
+
_agg?: Record<string, unknown>;
|
|
17
|
+
/** Nested selections whose cap was hit, by name. */
|
|
18
|
+
_truncated?: Record<string, true>;
|
|
19
|
+
[field: string]: unknown;
|
|
22
20
|
}
|
|
23
21
|
/**
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
* `RequestContext.entry` / `operation` instead.
|
|
22
|
+
* A row as passed to `Dataset.write`. `id` may be omitted: the dataset then
|
|
23
|
+
* assigns a version-7 UUID and returns it in `WriteResult.ids`.
|
|
27
24
|
*/
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
25
|
+
interface WriteRow {
|
|
26
|
+
id?: Id;
|
|
27
|
+
_deletedAt?: Date | null;
|
|
28
|
+
_metadata?: RowMetadata;
|
|
29
|
+
[field: string]: unknown;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Refuse an upsert batch that names one id twice: the datasets would
|
|
33
|
+
* otherwise disagree (pg cannot update a row twice in one statement).
|
|
34
|
+
*/
|
|
35
|
+
declare function assertNoRepeatedIds(type: string, rows: readonly WriteRow[]): void;
|
|
36
|
+
type IdentityKind = 'agent' | 'user' | 'system';
|
|
37
|
+
/**
|
|
38
|
+
* Row-attribution actor — records who created or last updated a row.
|
|
39
|
+
* Distinct from the auth `Identity` in `policy.ts` (JWT principal).
|
|
40
|
+
*/
|
|
41
|
+
interface ActorIdentity {
|
|
42
|
+
readonly kind: IdentityKind;
|
|
43
|
+
readonly id: string;
|
|
44
|
+
}
|
|
45
|
+
interface RowMetadata {
|
|
46
|
+
readonly createdAt: string | null;
|
|
47
|
+
readonly updatedAt: string | null;
|
|
48
|
+
readonly createdBy: ActorIdentity | null;
|
|
49
|
+
readonly updatedBy: ActorIdentity | null;
|
|
36
50
|
/**
|
|
37
|
-
*
|
|
38
|
-
* `
|
|
39
|
-
* is in the allowlist, this is the leftmost `x-forwarded-for` entry; when
|
|
40
|
-
* untrusted, this is the peer IP itself. Undefined when the transport doesn't
|
|
41
|
-
* expose peerIp (direct engine unit tests, pre-upgrade WS paths).
|
|
51
|
+
* The row's place in its type's commit order, on a type declared
|
|
52
|
+
* `ordering: 'visible'`; absent on every other type. Assigned on insert only.
|
|
42
53
|
*/
|
|
43
|
-
|
|
54
|
+
readonly seq?: number;
|
|
55
|
+
}
|
|
56
|
+
declare const CLIENT_SUPPLIED_SERVER_FIELD: 'client_supplied_server_field';
|
|
57
|
+
type ClientSuppliedServerFieldError = typeof CLIENT_SUPPLIED_SERVER_FIELD;
|
|
58
|
+
declare const ROW_METADATA_FIELDS: readonly ['createdAt', 'updatedAt', 'createdBy', 'updatedBy'];
|
|
59
|
+
type RowMetadataField = (typeof ROW_METADATA_FIELDS)[number];
|
|
60
|
+
//#endregion
|
|
61
|
+
//#region ../../packages/substrate-types/src/edge.d.ts
|
|
62
|
+
type OnDelete = 'set_null' | 'cascade' | 'restrict' | 'orphan';
|
|
63
|
+
type OnMissing = 'reject' | 'allow';
|
|
64
|
+
interface EdgeRef {
|
|
65
|
+
ns: string;
|
|
66
|
+
type: string;
|
|
67
|
+
id: Id;
|
|
68
|
+
bridged?: boolean;
|
|
69
|
+
}
|
|
70
|
+
interface Edge {
|
|
71
|
+
id: string;
|
|
72
|
+
from: EdgeRef;
|
|
73
|
+
to: EdgeRef;
|
|
74
|
+
fieldName: string;
|
|
75
|
+
policy: OnDelete;
|
|
76
|
+
createdAt: Date;
|
|
77
|
+
deletedAt?: Date;
|
|
78
|
+
lastSweptAt?: Date;
|
|
79
|
+
blocked?: boolean;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Narrow patch type for `EdgesStore.update`. Immutable fields (from, to,
|
|
83
|
+
* policy, fieldName, createdAt, id-as-identity) cannot be changed post-write.
|
|
84
|
+
* `deletedAt` is managed exclusively by `tombstone(id)`.
|
|
85
|
+
*/
|
|
86
|
+
type EdgePatch = Pick<Edge, 'id'> & Partial<Pick<Edge, 'lastSweptAt' | 'blocked'>>;
|
|
87
|
+
type EdgeWriteInput = Omit<Edge, 'id' | 'createdAt' | 'lastSweptAt' | 'deletedAt' | 'blocked'>;
|
|
88
|
+
type CanDeleteResult = {
|
|
89
|
+
ok: true;
|
|
90
|
+
} | {
|
|
91
|
+
ok: false;
|
|
92
|
+
blockedBy: Edge[];
|
|
93
|
+
};
|
|
94
|
+
interface EdgesStore {
|
|
44
95
|
/**
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
96
|
+
* Stable identifier for the storage substrate this edges store wraps.
|
|
97
|
+
* Parallels `Dataset.txScopeId` (spec §5.3). When an `EdgesStore`
|
|
98
|
+
* and a `Dataset` share a `txScopeId`, the engine enlists edge
|
|
99
|
+
* mutations into the dataset's `withScopedTransaction`, making
|
|
100
|
+
* row-tombstone + edge-tombstone within one frame atomic.
|
|
48
101
|
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
102
|
+
* Convention:
|
|
103
|
+
* - pg: derived from the `postgres.Sql` pool reference identity. A
|
|
104
|
+
* `PgEdgesStore` constructed against the same `Sql` as a
|
|
105
|
+
* `PgDataset` advertises the same `txScopeId`.
|
|
106
|
+
* - memory: unique per `MemoryEdgesStore` instance. A memory edges
|
|
107
|
+
* store can never coalesce into a dataset's substrate tx; the engine
|
|
108
|
+
* falls back to nested independent transactions for that case.
|
|
51
109
|
*/
|
|
52
|
-
|
|
110
|
+
readonly txScopeId: string;
|
|
111
|
+
write(input: EdgeWriteInput): Promise<Edge>;
|
|
53
112
|
/**
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
* at every dispatch site (query/mutate/stream/subscribe) so type- and
|
|
57
|
-
* plugin-level policies can discriminate between resolvers that otherwise
|
|
58
|
-
* present identically (`get<T>` and `delete<T>` both arrive as
|
|
59
|
-
* operation:'mutate' with id-only params). Undefined only in direct-call
|
|
60
|
-
* unit tests that construct a bare ctx.
|
|
113
|
+
* `write` for many inputs, returned in input order (pg: one multi-row
|
|
114
|
+
* INSERT whatever the count). Empty `inputs` returns `[]` and sends nothing.
|
|
61
115
|
*/
|
|
62
|
-
|
|
116
|
+
writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
|
|
117
|
+
tombstone(id: string, at?: Date): Promise<void>;
|
|
63
118
|
/**
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
* and custom mutations.
|
|
119
|
+
* `tombstone` for many ids with one stamp (pg: one statement). Unknown and
|
|
120
|
+
* already-tombstoned ids are skipped, the latter keeping their first stamp.
|
|
121
|
+
* Empty `ids` does nothing and sends nothing.
|
|
68
122
|
*/
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
rows?: Row[];
|
|
123
|
+
tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
|
|
124
|
+
update(patch: EdgePatch): Promise<void>;
|
|
125
|
+
readNextBatch(cursorId: string | null, size: number): Promise<{
|
|
126
|
+
edges: Edge[];
|
|
127
|
+
lastId: string | null;
|
|
128
|
+
}>;
|
|
129
|
+
findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
|
|
77
130
|
/**
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
* — using a dataset captured at registration time bypasses the active
|
|
82
|
-
* transaction and breaks atomicity. Optional purely to keep direct-resolver
|
|
83
|
-
* unit tests concise; the engine always supplies it.
|
|
131
|
+
* Batched `findEdgesTo`: all live (non-tombstoned) inbound edges whose `to`
|
|
132
|
+
* matches ANY of `refs`, in a single round-trip. Empty `refs` yields an
|
|
133
|
+
* empty result. Callers group the flat result by `edge.to` themselves.
|
|
84
134
|
*/
|
|
85
|
-
|
|
135
|
+
findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
136
|
+
findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
|
|
86
137
|
/**
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
* fallback for direct-call tests. Unlike `dataset`, this is not namespace-
|
|
90
|
-
* scoped — edges are inherently cross-namespace, and a single engine-scoped
|
|
91
|
-
* `EdgesStore` is threaded through every call.
|
|
138
|
+
* Batched `findEdgesFrom`: all live outbound edges whose `from` matches ANY
|
|
139
|
+
* of `refs`, in a single round-trip, as `findEdgesToMany` does for `to`.
|
|
92
140
|
*/
|
|
93
|
-
|
|
141
|
+
findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
142
|
+
canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
|
|
143
|
+
findBlocked(): Promise<Edge[]>;
|
|
94
144
|
/**
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
* subscription bus only after the enclosing `withTransaction` commits — a
|
|
100
|
-
* rolled-back tx emits nothing. Direct-call unit tests may pass `onWrite` to
|
|
101
|
-
* observe resolver output without spinning up an engine.
|
|
145
|
+
* List live (non-tombstoned) edges where `from_ns === namespace` OR
|
|
146
|
+
* `to_ns === namespace`. Used by drop-namespace to detect dangling refs
|
|
147
|
+
* when `cascade === 'refuse'`. Bounded by `limit` — callers only need
|
|
148
|
+
* enough to decide + surface a sample.
|
|
102
149
|
*/
|
|
103
|
-
|
|
150
|
+
findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
|
|
104
151
|
/**
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
* an audit row for the refusal that caused it. The work is told which
|
|
108
|
-
* (`committed`), so post-commit work can skip a rollback. Absent outside a
|
|
109
|
-
* transaction, where the caller can simply do the work.
|
|
152
|
+
* List live (non-tombstoned) edges where either endpoint matches
|
|
153
|
+
* `(namespace, type)`. Used by drop-type for the same cascade-refuse check.
|
|
110
154
|
*/
|
|
111
|
-
|
|
155
|
+
findEdgesTouchingType(namespace: string, type: string, limit: number): Promise<Edge[]>;
|
|
112
156
|
/**
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
* `abort` to release cursors / close descriptors in their `finally` block.
|
|
118
|
-
* The engine cannot force-stop a generator; cooperation is the contract.
|
|
119
|
-
* Absent on query/mutate dispatch — non-streaming resolvers should not see a
|
|
120
|
-
* signal they have no way to honour.
|
|
157
|
+
* Distinct namespaces other than `namespace` at the far end of any edge
|
|
158
|
+
* (tombstoned or live) touching `namespace`, or `(namespace, type)` when
|
|
159
|
+
* `type` is given: the namespaces `dropEdgesByNamespace` / `dropEdgesByType`
|
|
160
|
+
* would delete edges from.
|
|
121
161
|
*/
|
|
122
|
-
|
|
162
|
+
namespacesLinkedTo(namespace: string, type?: string): Promise<string[]>;
|
|
123
163
|
/**
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
164
|
+
* Physically delete every edge (tombstoned or live) where `from_ns === namespace`
|
|
165
|
+
* OR `to_ns === namespace`. Used by drop-namespace when `cascade === 'delete'`.
|
|
166
|
+
* Returns the exact count physically removed.
|
|
167
|
+
*
|
|
168
|
+
* Same atomicity rules as `tombstone` — MUST run inside a caller-supplied
|
|
169
|
+
* `withTransaction` for multi-store atomicity.
|
|
128
170
|
*/
|
|
129
|
-
|
|
171
|
+
dropEdgesByNamespace(namespace: string, within?: readonly string[]): Promise<number>;
|
|
130
172
|
/**
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
*
|
|
173
|
+
* Physically delete every edge (tombstoned or live) where either endpoint
|
|
174
|
+
* matches `(namespace, type)`. Used by drop-type when `cascade === 'delete'`.
|
|
175
|
+
* `within` restricts both drops to edges whose far end is `namespace` or one
|
|
176
|
+
* of the listed namespaces.
|
|
134
177
|
*/
|
|
135
|
-
|
|
178
|
+
dropEdgesByType(namespace: string, type: string, within?: readonly string[]): Promise<number>;
|
|
179
|
+
/**
|
|
180
|
+
* Execute `fn` atomically. All ops performed on the `tx` argument run inside
|
|
181
|
+
* one substrate transaction. On throw, every mutation inside the callback
|
|
182
|
+
* rolls back; on resolve, the transaction commits and the value is returned.
|
|
183
|
+
*
|
|
184
|
+
* Nested calls flatten into the outer tx (savepoints out of scope).
|
|
185
|
+
* Cross-store atomicity with a sibling `Dataset.withTransaction` is the
|
|
186
|
+
* engine's concern; each store manages its own tx independently here.
|
|
187
|
+
* For enlisted cross-store atomicity, see `Dataset.withScopedTransaction`
|
|
188
|
+
* which yields a tx-bound `EdgesStore` alongside the tx-bound datasets.
|
|
189
|
+
*
|
|
190
|
+
* Mirrors `Dataset.withTransaction` (§4.5, G1 §5.3).
|
|
191
|
+
*/
|
|
192
|
+
withTransaction<T>(fn: (tx: EdgesStore) => Promise<T>): Promise<T>;
|
|
136
193
|
}
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
type: string;
|
|
149
|
-
id: Row['id'];
|
|
150
|
-
operation: 'create' | 'update' | 'delete';
|
|
151
|
-
row?: Row;
|
|
194
|
+
//#endregion
|
|
195
|
+
//#region ../../packages/substrate-types/src/runtime-metrics.d.ts
|
|
196
|
+
/** Per-key resolver latency and error counts, as served by GET /substrate/v1/metrics. */
|
|
197
|
+
interface ResolverStat {
|
|
198
|
+
kind: 'query' | 'mutate';
|
|
199
|
+
calls: number;
|
|
200
|
+
errors: number;
|
|
201
|
+
p50Ms: number;
|
|
202
|
+
p99Ms: number;
|
|
203
|
+
maxMs: number;
|
|
204
|
+
lastAt: string;
|
|
152
205
|
}
|
|
153
|
-
interface
|
|
154
|
-
|
|
155
|
-
|
|
206
|
+
interface ProcessStat {
|
|
207
|
+
rssMB: number;
|
|
208
|
+
heapUsedMB: number;
|
|
209
|
+
cpuUserMs: number;
|
|
210
|
+
cpuSystemMs: number;
|
|
211
|
+
eventLoopLagP99Ms: number;
|
|
212
|
+
inFlight: number;
|
|
156
213
|
}
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
interface RowFilterObligation<T = unknown> extends Obligation {
|
|
163
|
-
kind: 'row-filter';
|
|
164
|
-
predicate: (ctx: RequestContext, row: T) => boolean;
|
|
214
|
+
interface SlowRequest {
|
|
215
|
+
key: string;
|
|
216
|
+
kind: 'query' | 'mutate';
|
|
217
|
+
durationMs: number;
|
|
218
|
+
at: string;
|
|
165
219
|
}
|
|
166
|
-
interface
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
220
|
+
interface RuntimeErrorEntry {
|
|
221
|
+
at: string;
|
|
222
|
+
op: 'query' | 'mutate';
|
|
223
|
+
key: string;
|
|
224
|
+
code: string;
|
|
225
|
+
message: string;
|
|
226
|
+
/** The verified identity's id, or `'anonymous'`. */
|
|
227
|
+
caller?: string;
|
|
228
|
+
/** Present when consecutive identical `(unknown)` failures were merged into this entry. */
|
|
229
|
+
count?: number;
|
|
230
|
+
}
|
|
231
|
+
interface RuntimeErrors {
|
|
232
|
+
since: string;
|
|
233
|
+
errors: RuntimeErrorEntry[];
|
|
234
|
+
}
|
|
235
|
+
interface ResolveObservation {
|
|
236
|
+
key: string;
|
|
237
|
+
kind: 'query' | 'mutate';
|
|
238
|
+
durationMs: number;
|
|
239
|
+
ok: boolean;
|
|
240
|
+
code?: string;
|
|
241
|
+
message?: string;
|
|
242
|
+
/** The verified identity's id; absent for an anonymous caller. */
|
|
243
|
+
caller?: string;
|
|
244
|
+
/**
|
|
245
|
+
* Set when the element ran in a batch resolver call: the number of elements
|
|
246
|
+
* in that call. `durationMs` is then the whole call's time, shared by all of
|
|
247
|
+
* them. Absent for a per-element resolve.
|
|
248
|
+
*/
|
|
249
|
+
batchSize?: number;
|
|
250
|
+
/**
|
|
251
|
+
* The element's position (0..batchSize-1) in its batch call; set with
|
|
252
|
+
* `batchSize`. Latency aggregates take a batch once, from index 0, so one
|
|
253
|
+
* call's time is not counted batchSize times. Call counts take every element.
|
|
254
|
+
*/
|
|
255
|
+
batchIndex?: number;
|
|
170
256
|
}
|
|
171
|
-
type Policy = (ctx: RequestContext, args: ResolverArgs) => PolicyDecision;
|
|
172
|
-
/**
|
|
173
|
-
* Engine-facing resolver shape. Spec: §4.3, §5.2, §5.5.
|
|
174
|
-
*
|
|
175
|
-
* The engine treats any resolver's return as opaque rows. A `ReadResult` return
|
|
176
|
-
* signals a paged list; the engine unpacks `rows` into the envelope and copies
|
|
177
|
-
* `nextCursor`/`hasMore` into `_pagination[key]`. An `AsyncIterable<Row>`
|
|
178
|
-
* return is the §5.5 stream-dispatch shape (duck-typed via
|
|
179
|
-
* `Symbol.asyncIterator` so it can't collide with `Row[]`).
|
|
180
|
-
*
|
|
181
|
-
* This is what the registry stores and what the engine dispatches to. Plugin
|
|
182
|
-
* authors declaring custom resolvers use the typed-authoring form
|
|
183
|
-
* `TypedResolver<T>` below; the engine erases to `Resolver` at registration
|
|
184
|
-
* time.
|
|
185
|
-
*/
|
|
186
|
-
type Resolver = (ctx: RequestContext, args: ResolverArgs) => Promise<Row | Row[] | ReadResult | AsyncIterable<Row> | null> | AsyncIterable<Row>;
|
|
187
|
-
/**
|
|
188
|
-
* Typed-authoring resolver shape. Used by autoCRUD and hand-authored resolvers
|
|
189
|
-
* that want to preserve the concrete return type before erasing to `Resolver`
|
|
190
|
-
* at registration. `T` is unconstrained at the type level — the engine
|
|
191
|
-
* discriminates on the runtime value shape regardless of static type.
|
|
192
|
-
*/
|
|
193
|
-
type TypedResolver<T> = (ctx: RequestContext, args: ResolverArgs) => Promise<T>;
|
|
194
257
|
/**
|
|
195
|
-
*
|
|
196
|
-
*
|
|
197
|
-
*
|
|
258
|
+
* One type's table and index statistics, for the index advisor. Counters are
|
|
259
|
+
* cumulative since the server's statistics were last reset. Row counts are
|
|
260
|
+
* estimates. A type ABSENT from a `typeStats()` result is unknown, not empty:
|
|
261
|
+
* never read its absence as 0 rows (a sampled store can miss a small type).
|
|
198
262
|
*/
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
type
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
263
|
+
interface TypeStats {
|
|
264
|
+
namespace: string;
|
|
265
|
+
type: string;
|
|
266
|
+
liveRows: number;
|
|
267
|
+
insertsTotal: number;
|
|
268
|
+
updatesTotal: number;
|
|
269
|
+
deletesTotal: number;
|
|
270
|
+
indexes: Array<{
|
|
271
|
+
name: string;
|
|
272
|
+
scans: number;
|
|
273
|
+
/** The last scan (ISO), or null when none since the statistics were last reset. */
|
|
274
|
+
lastScanAt: string | null;
|
|
275
|
+
sizeBytes: number;
|
|
276
|
+
unique: boolean;
|
|
277
|
+
/** Built or adopted by the engine's index reconciler for this type. */
|
|
278
|
+
engineOwned: boolean;
|
|
279
|
+
}>;
|
|
280
|
+
}
|
|
281
|
+
/** What GET /substrate/v1/metrics returns. The new fields are optional so an older server still type-checks. */
|
|
282
|
+
interface RuntimeMetrics {
|
|
283
|
+
since: string;
|
|
284
|
+
requests: {
|
|
285
|
+
query: {
|
|
286
|
+
total: number;
|
|
287
|
+
ok: number;
|
|
288
|
+
error: number;
|
|
289
|
+
durationMsSum: number;
|
|
290
|
+
durationMsMax: number;
|
|
291
|
+
};
|
|
292
|
+
mutate: {
|
|
293
|
+
total: number;
|
|
294
|
+
ok: number;
|
|
295
|
+
error: number;
|
|
296
|
+
durationMsSum: number;
|
|
297
|
+
durationMsMax: number;
|
|
298
|
+
};
|
|
299
|
+
};
|
|
300
|
+
subscriptions: {
|
|
301
|
+
active: number;
|
|
302
|
+
maxQueueDepth?: number;
|
|
303
|
+
entries?: {
|
|
304
|
+
id: string;
|
|
305
|
+
ns: string;
|
|
306
|
+
type: string;
|
|
307
|
+
queueLength: number;
|
|
308
|
+
}[];
|
|
309
|
+
};
|
|
310
|
+
events: Record<string, number>;
|
|
311
|
+
resolvers?: Record<string, ResolverStat>;
|
|
312
|
+
process?: ProcessStat;
|
|
313
|
+
slowest?: SlowRequest[];
|
|
314
|
+
}
|
|
315
|
+
//#endregion
|
|
316
|
+
//#region ../../packages/substrate-types/src/dataset.d.ts
|
|
317
|
+
/**
|
|
318
|
+
* Handles yielded by `Dataset.withScopedTransaction`. Contains the
|
|
319
|
+
* tx-bound dataset for every requested namespace plus (optionally) a
|
|
320
|
+
* tx-bound edges store enlisted into the same substrate transaction.
|
|
321
|
+
* See `withScopedTransaction` JSDoc for the `edges` contract.
|
|
322
|
+
*/
|
|
323
|
+
interface TxScopeHandles {
|
|
324
|
+
datasets: Map<string, Dataset>;
|
|
325
|
+
edges: EdgesStore | null;
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* A leaf predicate on a single field. At most one operator per call-site is
|
|
329
|
+
* used in practice (e.g. `{ age: { gt: 18 } }`), but the shape admits several
|
|
330
|
+
* operators so `{ age: { gte: 10, lt: 100 } }` can express a half-open range
|
|
331
|
+
* without the caller reaching for an explicit `AND`. Semantics: the leaf
|
|
332
|
+
* matches when EVERY specified operator matches (implicit AND within a leaf).
|
|
333
|
+
*
|
|
334
|
+
* `eq`/`neq` accept `null` to address IS NULL / IS NOT NULL semantics at the
|
|
335
|
+
* substrate layer — the validator enforces `null` only on those two operators.
|
|
336
|
+
*/
|
|
337
|
+
interface FieldPredicate {
|
|
338
|
+
eq?: number | string | boolean | Date | null | RefOperand;
|
|
339
|
+
neq?: number | string | boolean | Date | null | RefOperand;
|
|
340
|
+
gt?: number | string | Date | RefOperand;
|
|
341
|
+
gte?: number | string | Date | RefOperand;
|
|
342
|
+
lt?: number | string | Date | RefOperand;
|
|
343
|
+
lte?: number | string | Date | RefOperand;
|
|
344
|
+
between?: [number | string | Date, number | string | Date];
|
|
345
|
+
in?: Array<number | string | boolean | Date>;
|
|
346
|
+
nin?: Array<number | string | boolean | Date>;
|
|
347
|
+
contains?: string;
|
|
348
|
+
startsWith?: string;
|
|
349
|
+
endsWith?: string;
|
|
350
|
+
has?: number | string | boolean | Date | null;
|
|
351
|
+
path?: string[];
|
|
352
|
+
}
|
|
353
|
+
/**
|
|
354
|
+
* A where clause is either a logical combinator OR a map of field names to
|
|
355
|
+
* predicates / nested where clauses (for struct fields). Field names and the
|
|
356
|
+
* three combinator keys (AND/OR/NOT) share a namespace — `AND`/`OR`/`NOT` are
|
|
357
|
+
* reserved and must not collide with field names declared in any type.
|
|
358
|
+
*/
|
|
359
|
+
type WhereClause = {
|
|
360
|
+
AND: WhereClause[];
|
|
361
|
+
} | {
|
|
362
|
+
OR: WhereClause[];
|
|
363
|
+
} | {
|
|
364
|
+
NOT: WhereClause;
|
|
365
|
+
} | {
|
|
366
|
+
_walk: WalkNode;
|
|
367
|
+
} | WalkAggPredicate | {
|
|
368
|
+
_walk?: never;
|
|
369
|
+
_agg?: never;
|
|
370
|
+
[field: string]: FieldPredicate | WhereClause | unknown;
|
|
371
|
+
};
|
|
372
|
+
type WalkPick = {
|
|
373
|
+
latest: string;
|
|
374
|
+
} | {
|
|
375
|
+
max: string;
|
|
376
|
+
} | {
|
|
377
|
+
min: string;
|
|
378
|
+
};
|
|
379
|
+
interface WalkNode {
|
|
380
|
+
as?: string;
|
|
381
|
+
/** `'<ns>/<Type>.<field>'`: inbound edge. */
|
|
382
|
+
in?: string;
|
|
383
|
+
/** `'<field>'`: outbound edge. */
|
|
384
|
+
out?: string;
|
|
385
|
+
where?: WhereClause;
|
|
386
|
+
quantifier?: 'any' | 'none' | 'all';
|
|
387
|
+
pick?: WalkPick;
|
|
388
|
+
}
|
|
389
|
+
/** `'$.f'` | `'<as>.f'` | `'_agg.<name>'` */
|
|
390
|
+
interface RefOperand {
|
|
391
|
+
$ref: string;
|
|
392
|
+
times?: number;
|
|
393
|
+
plus?: number;
|
|
394
|
+
}
|
|
395
|
+
type AggFn = {
|
|
396
|
+
count: true;
|
|
397
|
+
} | {
|
|
398
|
+
avg: string;
|
|
399
|
+
} | {
|
|
400
|
+
sum: string;
|
|
401
|
+
} | {
|
|
402
|
+
min: string;
|
|
403
|
+
} | {
|
|
404
|
+
max: string;
|
|
405
|
+
} | {
|
|
406
|
+
latest: {
|
|
407
|
+
by: string;
|
|
408
|
+
value: string;
|
|
409
|
+
};
|
|
410
|
+
};
|
|
411
|
+
type WalkAgg = {
|
|
412
|
+
in?: string;
|
|
413
|
+
out?: string;
|
|
414
|
+
where?: WhereClause;
|
|
415
|
+
} & AggFn;
|
|
416
|
+
type FrameAgg = Exclude<AggFn, {
|
|
417
|
+
latest: unknown;
|
|
418
|
+
}>;
|
|
419
|
+
interface BucketSpec {
|
|
420
|
+
field: string;
|
|
421
|
+
by: 'day' | 'hour';
|
|
422
|
+
}
|
|
423
|
+
type DeriveSpec = {
|
|
424
|
+
diff: [string, string];
|
|
425
|
+
} | {
|
|
426
|
+
ratio: [string, string];
|
|
427
|
+
};
|
|
428
|
+
interface NestedSelection {
|
|
429
|
+
_walk: {
|
|
430
|
+
in?: string;
|
|
431
|
+
out?: string;
|
|
432
|
+
where?: WhereClause;
|
|
433
|
+
};
|
|
434
|
+
fields: Record<string, unknown>;
|
|
435
|
+
where?: WhereClause;
|
|
436
|
+
orderBy?: OrderByClause[];
|
|
437
|
+
limit?: number;
|
|
438
|
+
}
|
|
439
|
+
/** An `_agg` comparison operand: a number, a date or string (by the aggregate's kind), or a `$ref`. */
|
|
440
|
+
type WalkAggOperand = number | string | RefOperand;
|
|
441
|
+
/** `{ _agg: <walk aggregate>, <cmp>: <operand> }` */
|
|
442
|
+
type WalkAggPredicate = {
|
|
443
|
+
_agg: WalkAgg;
|
|
444
|
+
} & ({
|
|
445
|
+
eq: WalkAggOperand;
|
|
446
|
+
} | {
|
|
447
|
+
neq: WalkAggOperand;
|
|
448
|
+
} | {
|
|
449
|
+
gt: WalkAggOperand;
|
|
450
|
+
} | {
|
|
451
|
+
gte: WalkAggOperand;
|
|
452
|
+
} | {
|
|
453
|
+
lt: WalkAggOperand;
|
|
454
|
+
} | {
|
|
455
|
+
lte: WalkAggOperand;
|
|
456
|
+
});
|
|
457
|
+
/**
|
|
458
|
+
* OrderBy clause. One entry per field, direction per field. Engine appends an
|
|
459
|
+
* implicit `{ id: 'asc' }` when callers omit `id` as the final tie-breaker — a
|
|
460
|
+
* deterministic tie-break is what makes cursor pagination stable across pages.
|
|
461
|
+
*/
|
|
462
|
+
interface OrderByClause {
|
|
463
|
+
/** A `$`-prefixed key orders by a `params.derive` entry. */
|
|
464
|
+
[field: string]: 'asc' | 'desc';
|
|
465
|
+
}
|
|
466
|
+
interface ReadParams {
|
|
467
|
+
/** Aborts the read. Substrates that can (PgDataset) cancel the in-flight statement; others MAY ignore it. */
|
|
468
|
+
signal?: AbortSignal;
|
|
469
|
+
id?: Id;
|
|
470
|
+
ids?: Id[];
|
|
471
|
+
includeDeleted?: boolean;
|
|
472
|
+
where?: WhereClause;
|
|
473
|
+
orderBy?: OrderByClause[];
|
|
474
|
+
limit?: number;
|
|
475
|
+
/** Return a match count (`ReadResult.count`). */
|
|
476
|
+
count?: boolean;
|
|
477
|
+
aggregate?: Record<string, FrameAgg>;
|
|
478
|
+
bucket?: BucketSpec;
|
|
479
|
+
derive?: Record<string, DeriveSpec>;
|
|
480
|
+
/** Per-row walk aggregates, lifted out of `fields` by the list resolver. */
|
|
481
|
+
agg?: Record<string, WalkAgg>;
|
|
482
|
+
/** Per-row nested selections, lifted out of `fields` by the list resolver. */
|
|
483
|
+
nested?: Record<string, NestedSelection>;
|
|
222
484
|
/**
|
|
223
|
-
*
|
|
224
|
-
*
|
|
485
|
+
* Opaque cursor produced by a prior `read()` call. Base64url-encoded JSON
|
|
486
|
+
* (server-built, server-consumed). Callers should treat it as a black box.
|
|
225
487
|
*/
|
|
226
|
-
|
|
227
|
-
/** Whether the deployment verifies credentials, stamped with `clientIp`. */
|
|
228
|
-
authEnabled?: boolean;
|
|
488
|
+
cursor?: string;
|
|
229
489
|
/**
|
|
230
|
-
*
|
|
231
|
-
*
|
|
232
|
-
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
490
|
+
* Optional caller-supplied projection hint. Substrates MAY use this to
|
|
491
|
+
* narrow the body keys they materialise from storage — e.g. PgDataset
|
|
492
|
+
* builds a `jsonb_build_object(...)` projection over only the requested
|
|
493
|
+
* top-level body keys, saving wire + parse bandwidth.
|
|
494
|
+
*
|
|
495
|
+
* When present, ONLY top-level entries are honoured (the value can be `true`
|
|
496
|
+
* or a nested FieldInput-shaped object — the substrate treats both as
|
|
497
|
+
* "include this key"). Nested projection inside JSONB sub-trees is intentionally
|
|
498
|
+
* out of scope; the pack codec already prunes deeper. Row-metadata-style keys
|
|
499
|
+
* (`_metadata`, `shortId`, `_deletedAt`, `id`) are populated from dedicated
|
|
500
|
+
* columns regardless of `fields` and never need to be included here.
|
|
501
|
+
*
|
|
502
|
+
* When absent, substrates return the full body, for raw `dataset.read()`
|
|
503
|
+
* callers (sweep, compose registry, migration scripts) that don't know which
|
|
504
|
+
* body keys they'll need downstream.
|
|
505
|
+
*
|
|
506
|
+
* Substrates MAY ignore this hint — it's a perf optimisation, not a contract.
|
|
507
|
+
* Memory dataset, for instance, has no wire to save and ignores it.
|
|
235
508
|
*/
|
|
236
|
-
|
|
509
|
+
fields?: {
|
|
510
|
+
[field: string]: true | unknown;
|
|
511
|
+
};
|
|
237
512
|
}
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
513
|
+
/**
|
|
514
|
+
* Paged result of a `read()` call. `rows` is always present; `nextCursor` is
|
|
515
|
+
* present iff `hasMore` is `true` and the current page is non-empty.
|
|
516
|
+
*/
|
|
517
|
+
interface ReadResult {
|
|
518
|
+
rows: Row[];
|
|
519
|
+
nextCursor?: string;
|
|
520
|
+
hasMore: boolean;
|
|
521
|
+
count?: number;
|
|
522
|
+
groups?: Array<Record<string, unknown>>;
|
|
523
|
+
truncated?: boolean;
|
|
242
524
|
}
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
525
|
+
interface WriteResult {
|
|
526
|
+
written: number;
|
|
527
|
+
/**
|
|
528
|
+
* One per written row, in input order: a supplied id verbatim, otherwise
|
|
529
|
+
* the id the dataset assigned. Under `insertOnly`, skipped rows are absent.
|
|
530
|
+
*/
|
|
531
|
+
ids: Id[];
|
|
532
|
+
/**
|
|
533
|
+
* Merged rows after upsert — substrates populate this with the post-merge
|
|
534
|
+
* row state so autoCRUD update can skip its post-read. Order
|
|
535
|
+
* matches `ids` (one entry per input row). Substrates that can't compute
|
|
536
|
+
* the merged shape cheaply may emit input rows verbatim; consumers must
|
|
537
|
+
* not rely on body keys absent from the input being filled in.
|
|
538
|
+
*/
|
|
539
|
+
rows: Row[];
|
|
253
540
|
}
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
541
|
+
/**
|
|
542
|
+
* Optional 3rd-arg to `dataset.write` / `tx.write`. When the incoming row's
|
|
543
|
+
* `_metadata` is absent, the substrate auto-fills it from these hints:
|
|
544
|
+
* - `now` → both `createdAt` and `updatedAt` (defaults to `new Date()`)
|
|
545
|
+
* - `identity` → both `createdBy` and `updatedBy` (defaults to `null`)
|
|
546
|
+
*
|
|
547
|
+
* On upsert collision, `created_*` columns preserve existing values (immutability);
|
|
548
|
+
* `updated_*` columns adopt the new values (bump intent). Engine path
|
|
549
|
+
* (`autocrud-create`/`autocrud-update`) constructs full `_metadata` itself —
|
|
550
|
+
* this auto-fill is purely a safety net for raw-write bypass paths.
|
|
551
|
+
*/
|
|
552
|
+
interface WriteOptions {
|
|
553
|
+
readonly identity?: ActorIdentity;
|
|
554
|
+
readonly now?: Date;
|
|
258
555
|
/**
|
|
259
|
-
*
|
|
260
|
-
*
|
|
261
|
-
*
|
|
262
|
-
* paces to a slow consumer instead of growing the send buffer unbounded.
|
|
263
|
-
* Optional: transports without buffer introspection (memory tests) omit it,
|
|
264
|
-
* and the route treats a missing hook as "always drained".
|
|
556
|
+
* Insert only: a row whose id already exists (live or tombstoned) is left
|
|
557
|
+
* untouched and omitted from the result's `ids` and `rows`. The existence
|
|
558
|
+
* check and the insert are one atomic step.
|
|
265
559
|
*/
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
560
|
+
readonly insertOnly?: boolean;
|
|
561
|
+
}
|
|
562
|
+
interface DeleteResult {
|
|
563
|
+
deleted: number;
|
|
564
|
+
ids: Id[];
|
|
565
|
+
}
|
|
566
|
+
/** Options of `Dataset.updateWhere` / `deleteWhere`. */
|
|
567
|
+
interface FilterWriteOptions {
|
|
568
|
+
/** Most rows the filter may match; one more refuses the write with `filter_too_broad`. */
|
|
569
|
+
maxMatch: number;
|
|
570
|
+
/** Stamped as `updatedBy` (update only); the anonymous system actor when absent. */
|
|
571
|
+
actor?: ActorIdentity;
|
|
572
|
+
/** Stamped as `updatedAt` (update only); the clock when absent. */
|
|
573
|
+
now?: Date;
|
|
574
|
+
}
|
|
575
|
+
/**
|
|
576
|
+
* What a by-filter write changed: every changed id, and the changed rows
|
|
577
|
+
* (post-images for an update, pre-images for a delete). Both are bounded by
|
|
578
|
+
* `maxMatch`.
|
|
579
|
+
*/
|
|
580
|
+
interface FilterWriteResult {
|
|
581
|
+
count: number;
|
|
582
|
+
ids: Id[];
|
|
583
|
+
rows: Row[];
|
|
584
|
+
}
|
|
585
|
+
/** The caps on `updateMany<T>` / `deleteMany<T>`. */
|
|
586
|
+
interface FilterWriteLimits {
|
|
587
|
+
/** Most rows one filter may match (`SUBSTRATE_FILTER_WRITE_MAX_MATCH`). */
|
|
588
|
+
maxMatch: number;
|
|
589
|
+
/** Most ids one result returns (`SUBSTRATE_FILTER_WRITE_IDS_CAP`). */
|
|
590
|
+
idsCap: number;
|
|
591
|
+
}
|
|
592
|
+
declare const DEFAULT_FILTER_WRITE_LIMITS: Readonly<FilterWriteLimits>;
|
|
593
|
+
interface DropResult {
|
|
594
|
+
/** Number of rows physically removed. */
|
|
595
|
+
rowsDeleted: number;
|
|
596
|
+
/** Number of short-id allocations physically removed. */
|
|
597
|
+
shortIdsDeleted: number;
|
|
598
|
+
}
|
|
599
|
+
/**
|
|
600
|
+
* Dataset-declared filter capabilities. §5.2 capability negotiation: the engine
|
|
601
|
+
* validates every where-clause leaf against `operators[fieldKind]` and rejects
|
|
602
|
+
* ops the dataset can't execute rather than returning a silently wrong result.
|
|
603
|
+
*/
|
|
604
|
+
type FieldKind = 'scalar.number' | 'scalar.string' | 'scalar.boolean' | 'scalar.date' | 'scalar.json' | 'crossRef' | 'list';
|
|
605
|
+
interface FilterCapabilities {
|
|
606
|
+
operators: Record<FieldKind, string[]>;
|
|
607
|
+
/** Does the dataset honour `orderBy`? */
|
|
608
|
+
orderBy: boolean;
|
|
609
|
+
/** Does the dataset honour cursor-based pagination? */
|
|
610
|
+
cursor: boolean;
|
|
270
611
|
/**
|
|
271
|
-
*
|
|
272
|
-
*
|
|
273
|
-
* structured frames (e.g. `{ kind: 'end', reason: 'server_restart' }` per
|
|
274
|
-
* active subscription) so clients can short-circuit reconnect backoff
|
|
275
|
-
* instead of seeing an abrupt 1006 drop. Optional — transports without a
|
|
276
|
-
* pre-close hook (memory tests) may omit it; the route layer should
|
|
277
|
-
* tolerate undefined.
|
|
612
|
+
* Does the dataset answer the typed-edge-walk grammar? The engine refuses a
|
|
613
|
+
* walk frame on a dataset without it (`walks_unsupported_store`).
|
|
278
614
|
*/
|
|
279
|
-
|
|
280
|
-
}
|
|
281
|
-
type WsHandler = (req: SubstrateRequest, conn: WsConnection) => void | Promise<void>;
|
|
282
|
-
interface TlsConfig {
|
|
283
|
-
cert: string | Buffer;
|
|
284
|
-
key: string | Buffer;
|
|
285
|
-
ca?: string | Buffer;
|
|
615
|
+
walks?: boolean;
|
|
286
616
|
}
|
|
287
|
-
interface
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
617
|
+
interface UpdateFieldRef {
|
|
618
|
+
ns?: string;
|
|
619
|
+
type: string;
|
|
620
|
+
id: Id;
|
|
291
621
|
}
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
622
|
+
/**
|
|
623
|
+
* Outcome of a `conditionalUpdate` call (spec §5.12 Phase 2 / Dispatch B).
|
|
624
|
+
*
|
|
625
|
+
* `matched: true` when the row existed AND every key in `match` equalled the
|
|
626
|
+
* row's stored value at the moment of the update — the substrate applied
|
|
627
|
+
* `updates` and returned the merged row. `matched: false` when the row was
|
|
628
|
+
* missing or at least one match condition failed; in both cases no write landed
|
|
629
|
+
* and `row` is `null`.
|
|
630
|
+
*/
|
|
631
|
+
interface ConditionalUpdateResult {
|
|
632
|
+
matched: boolean;
|
|
633
|
+
row: Row | null;
|
|
299
634
|
}
|
|
300
|
-
interface
|
|
301
|
-
|
|
302
|
-
address: string;
|
|
303
|
-
port: number;
|
|
304
|
-
}>;
|
|
305
|
-
stop(opts?: {
|
|
306
|
-
grace?: number;
|
|
307
|
-
abortInFlight?: boolean;
|
|
308
|
-
}): Promise<void>;
|
|
309
|
-
route(method: HttpMethod, path: string, handler: HttpHandler): void;
|
|
310
|
-
websocket(path: string, handler: WsHandler): void;
|
|
311
|
-
onError?(hook: (err: Error, req?: SubstrateRequest) => void): void;
|
|
312
|
-
createPluginRouter(plugin: {
|
|
313
|
-
name: string;
|
|
314
|
-
}): PluginRouter;
|
|
635
|
+
interface Dataset {
|
|
636
|
+
readonly namespace: string;
|
|
315
637
|
/**
|
|
316
|
-
*
|
|
317
|
-
*
|
|
318
|
-
*
|
|
319
|
-
*
|
|
638
|
+
* Stable identifier for the storage substrate this dataset wraps. Two
|
|
639
|
+
* datasets share a substrate when their `txScopeId` values are `===`
|
|
640
|
+
* — they can participate in a single transaction via the engine's
|
|
641
|
+
* substrate-coalescing path (spec §5.3, enabling cross-namespace G1
|
|
642
|
+
* batched mutations when all frames target the same substrate).
|
|
643
|
+
*
|
|
644
|
+
* Convention:
|
|
645
|
+
* - pg: derived from the `postgres.Sql` pool reference identity. All
|
|
646
|
+
* `PgDataset` instances constructed against the same `sql`
|
|
647
|
+
* handle share one `txScopeId`.
|
|
648
|
+
* - memory: unique per `MemoryDataset` instance by default (each
|
|
649
|
+
* instance owns its own `Map`). Test harnesses that want shared-
|
|
650
|
+
* memory semantics can opt in via an explicit constructor option.
|
|
651
|
+
*
|
|
652
|
+
* Datasets with different `txScopeId` values CANNOT participate in a
|
|
653
|
+
* single transaction — the engine refuses mixed-substrate batched
|
|
654
|
+
* mutates with `cross_tx_scope_refused`.
|
|
320
655
|
*/
|
|
321
|
-
|
|
656
|
+
readonly txScopeId: string;
|
|
657
|
+
read(type: string, params: ReadParams): Promise<ReadResult>;
|
|
658
|
+
write(type: string, rows: WriteRow[], options?: WriteOptions): Promise<WriteResult>;
|
|
659
|
+
tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
660
|
+
purge(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
322
661
|
/**
|
|
323
|
-
*
|
|
324
|
-
*
|
|
662
|
+
* Physically delete every row of `type` within this dataset's namespace,
|
|
663
|
+
* plus every short-id allocation for that type. Ignores `_deletedAt` /
|
|
664
|
+
* `archived` state — drop is hard-delete regardless of row status.
|
|
325
665
|
*
|
|
326
|
-
*
|
|
327
|
-
*
|
|
328
|
-
*
|
|
666
|
+
* MUST run inside a caller-supplied `withTransaction` if atomicity with
|
|
667
|
+
* edge cleanup / audit emission is required. When called standalone,
|
|
668
|
+
* implementations MUST still execute the row-delete + short-id-delete as
|
|
669
|
+
* a single atomic step against the substrate.
|
|
329
670
|
*
|
|
330
|
-
*
|
|
331
|
-
*
|
|
332
|
-
*
|
|
671
|
+
* Returns the exact counts physically removed. If the type has no rows,
|
|
672
|
+
* returns zeros without error.
|
|
673
|
+
*
|
|
674
|
+
* Storage-level primitive: operates on any (namespace, type) rows present
|
|
675
|
+
* in storage regardless of whether the type is currently known to the
|
|
676
|
+
* engine's registry.
|
|
333
677
|
*/
|
|
334
|
-
|
|
678
|
+
dropType(type: string): Promise<DropResult>;
|
|
335
679
|
/**
|
|
336
|
-
*
|
|
337
|
-
*
|
|
680
|
+
* Physically delete every row AND short-id for `this.namespace`, across
|
|
681
|
+
* every type. Equivalent to calling `dropType` for each distinct type
|
|
682
|
+
* seen in storage, but substrate impls SHOULD use a single bulk DELETE
|
|
683
|
+
* where available (pg: one DELETE per type table).
|
|
684
|
+
*
|
|
685
|
+
* Same atomicity rules as `dropType`. Same "ignores archived state".
|
|
338
686
|
*/
|
|
339
|
-
|
|
687
|
+
dropNamespace(): Promise<DropResult>;
|
|
688
|
+
updateField(ref: UpdateFieldRef, fieldName: string, value: unknown): Promise<void>;
|
|
340
689
|
/**
|
|
341
|
-
*
|
|
342
|
-
*
|
|
343
|
-
*
|
|
344
|
-
*
|
|
690
|
+
* Atomic compare-and-update by PK. If the row `(type, id)` exists AND every
|
|
691
|
+
* `(field, value)` pair in `match` equals the stored row's field, apply the
|
|
692
|
+
* `updates` map and return `{ matched: true, row: mergedRow }`. Otherwise
|
|
693
|
+
* write nothing and return `{ matched: false, row: null }`.
|
|
694
|
+
*
|
|
695
|
+
* Semantics:
|
|
696
|
+
* - Equality is strict (`===`) for scalars; `Date` compares by
|
|
697
|
+
* `.getTime()`; `null` matches a stored `null` or an absent field, on both
|
|
698
|
+
* datasets. A declared scalar or crossRef set to `null` reads back absent
|
|
699
|
+
* (`isColumnField`), so it matches `null` all the same.
|
|
700
|
+
* - A missing row fails the match even when `match` is empty — the
|
|
701
|
+
* operation is "update this existing row if predicate holds".
|
|
702
|
+
* - `updates` is merged onto the stored row the same way `write()` upserts
|
|
703
|
+
* merge: each key overwrites; omitted keys are preserved. `_deletedAt`
|
|
704
|
+
* is reserved and silently skipped (matches `write()`'s sanitisation).
|
|
705
|
+
* - The whole check+write is atomic against other dataset operations.
|
|
706
|
+
* Implementations MUST NOT yield between the predicate test and the
|
|
707
|
+
* write. Pg uses `UPDATE ... WHERE <match> RETURNING *` inside the
|
|
708
|
+
* caller's enclosing `withTransaction`; memory runs the whole body
|
|
709
|
+
* synchronously within the `async` microtask.
|
|
710
|
+
*
|
|
711
|
+
* Motivating use case: the `_system` register route consumes a one-shot
|
|
712
|
+
* invite — the invite row's `consumedAt` must transition from `null` to a
|
|
713
|
+
* timestamp exactly once, even under concurrent registrations.
|
|
714
|
+
*
|
|
715
|
+
* Metadata: a successful match unconditionally bumps `updatedAt` to `now`
|
|
716
|
+
* (a server-set `now()` when omitted) and stamps `updatedBy` with the supplied `actor` (or
|
|
717
|
+
* a `{ kind: 'system', id: 'anonymous' }` sentinel when omitted) — same
|
|
718
|
+
* semantics as `write()`'s upsert path, so recency-ranked recall sees the
|
|
719
|
+
* change. `createdAt` / `createdBy` are preserved.
|
|
345
720
|
*/
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
observeInFlight?(fn: (op: RuntimeOp, delta: 1 | -1) => void): void;
|
|
349
|
-
}
|
|
350
|
-
//#endregion
|
|
351
|
-
//#region ../../packages/substrate-types/src/plugin.d.ts
|
|
352
|
-
/** Whether a registry entry is a top-level addressable type or a mutation. */
|
|
353
|
-
type RegistryEntryKind = 'type' | 'mutation';
|
|
354
|
-
/**
|
|
355
|
-
* postWrite hook signature. Receives the written row and request context;
|
|
356
|
-
* may perform side-effects (e.g. embedding, index updates). Returned promise
|
|
357
|
-
* is awaited before the engine acks the write to the caller.
|
|
358
|
-
*/
|
|
359
|
-
type PostWriteHook = (row: Row, ctx: RequestContext) => Promise<void>;
|
|
360
|
-
/**
|
|
361
|
-
* Resolver signature stored in a `RegistryEntry`. Identical to the canonical
|
|
362
|
-
* engine-facing `Resolver` in `./policy.ts`; redeclared inline here to keep
|
|
363
|
-
* the registry surface self-describing for the types package. Importers that
|
|
364
|
-
* want the canonical alias should import `Resolver` from this package.
|
|
365
|
-
*/
|
|
366
|
-
type RegistryEntryResolver = (ctx: RequestContext, args: ResolverArgs) => Promise<Row | Row[] | ReadResult | AsyncIterable<Row> | null> | AsyncIterable<Row>;
|
|
367
|
-
/** Input shape for `Registry.register` / `Registry.replace`. */
|
|
368
|
-
interface RegistryEntryInput {
|
|
369
|
-
resolver: RegistryEntryResolver;
|
|
370
|
-
policy?: Policy;
|
|
371
|
-
fields?: Record<string, FieldDef>;
|
|
372
|
-
kind?: RegistryEntryKind;
|
|
373
|
-
params?: Record<string, FieldDef>;
|
|
374
|
-
returns?: FieldDef;
|
|
375
|
-
/** Natural order of a `kind: 'type'` entry; published on its `TypeSchema`. */
|
|
376
|
-
orderedBy?: OrderedBy;
|
|
377
|
-
/** Declared indexes of a `kind: 'type'` entry installed at runtime (a proposed type). */
|
|
378
|
-
indexes?: IndexDecl[];
|
|
379
|
-
/** A proposed type's size hint; `large` lowers the index advisor's row minimum. */
|
|
380
|
-
expectedSize?: 'small' | 'large';
|
|
721
|
+
conditionalUpdate(type: string, id: Id, match: Record<string, unknown>, updates: Record<string, unknown>, actor?: ActorIdentity, now?: Date): Promise<ConditionalUpdateResult>;
|
|
722
|
+
readonly capabilities: FilterCapabilities;
|
|
381
723
|
/**
|
|
382
|
-
*
|
|
383
|
-
*
|
|
384
|
-
*
|
|
385
|
-
*
|
|
724
|
+
* Run `fn` while holding a mutual-exclusion lock named `key`, waiting until
|
|
725
|
+
* it is free. Excludes every other holder of the same key on this substrate:
|
|
726
|
+
* pg holds a session advisory lock, so the exclusion spans processes sharing
|
|
727
|
+
* the store's database schema; memory excludes holders on this dataset instance only.
|
|
728
|
+
* Released when `fn` settles, whether it resolves or throws, except on a
|
|
729
|
+
* pg tx-bound dataset, where it is held until the transaction ends so the
|
|
730
|
+
* next holder sees what this one committed. Not re-entrant:
|
|
731
|
+
* re-acquiring a held key inside `fn` waits forever.
|
|
732
|
+
*
|
|
733
|
+
* OPTIONAL. Callers feature-detect and fall back to a process-local lock.
|
|
734
|
+
*
|
|
735
|
+
* @returns whatever `fn` resolves to
|
|
736
|
+
* @throws whatever `fn` throws, after the lock is released
|
|
386
737
|
*/
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
}
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
readonly name: string;
|
|
423
|
-
}, input: RegistryEntryInput): void;
|
|
738
|
+
withAdvisoryLock?<T>(key: string, fn: () => Promise<T>): Promise<T>;
|
|
739
|
+
/**
|
|
740
|
+
* Prepare dedicated storage for `type` in this namespace, moving any rows
|
|
741
|
+
* already written for it there. Idempotent, and safe beside concurrent
|
|
742
|
+
* reads and writes: no row is lost, duplicated or seen twice. That holds for
|
|
743
|
+
* READ COMMITTED readers; a REPEATABLE READ snapshot taken before the move
|
|
744
|
+
* can miss the moved rows. Also builds the type's indexes, including its
|
|
745
|
+
* declared `indexes`, and throws when a unique one cannot be built.
|
|
746
|
+
*
|
|
747
|
+
* `indexes` picks which: `unique` builds only the unique ones and leaves the
|
|
748
|
+
* rest `pending`, for a later `nonUnique` call to build. `signal` cancels an
|
|
749
|
+
* in-flight non-unique build, which the next call retries. Default `all`.
|
|
750
|
+
*
|
|
751
|
+
* On a store keeping each type in a table of its own, also brings that
|
|
752
|
+
* table in line with the type's declared fields: a newly declared field gets
|
|
753
|
+
* its column, or, with `newFields: 'pending'`, is recorded `pending` for a
|
|
754
|
+
* background sweep to add. Resolves with the fields that went `pending` in
|
|
755
|
+
* this call; a store without such tables resolves `{ pending: [] }`.
|
|
756
|
+
*
|
|
757
|
+
* OPTIONAL. Backends without per-type storage omit it.
|
|
758
|
+
*/
|
|
759
|
+
ensureTypeStorage?(type: string, opts?: {
|
|
760
|
+
indexes?: 'all' | 'unique' | 'nonUnique';
|
|
761
|
+
signal?: AbortSignal;
|
|
762
|
+
newFields?: 'column' | 'pending';
|
|
763
|
+
}): Promise<{
|
|
764
|
+
pending: string[];
|
|
765
|
+
}>;
|
|
766
|
+
/**
|
|
767
|
+
* Where `type`'s rows live and how its declared indexes stand, read from the
|
|
768
|
+
* catalog without building anything.
|
|
769
|
+
*
|
|
770
|
+
* OPTIONAL. Backends without per-type storage omit it.
|
|
771
|
+
*/
|
|
772
|
+
describeStorage?(type: string): Promise<TypeStorageReport>;
|
|
424
773
|
/**
|
|
425
|
-
*
|
|
426
|
-
*
|
|
427
|
-
*
|
|
774
|
+
* Gives each `pending` field of every namespace its column and moves its
|
|
775
|
+
* values out of jsonb, and finishes each `promoting` one, a field at a time.
|
|
776
|
+
* DDL waits at most `lockTimeoutMs` for its table's lock, then that field is
|
|
777
|
+
* `busy` and retried by the next call; `batchRows` rows move per statement.
|
|
778
|
+
* `signal` stops the sweep between steps. Resolves with one event per field
|
|
779
|
+
* it touched. A field that failed on a unique conflict waits for its type's
|
|
780
|
+
* catalog to change, unless `retryConflicts` is set.
|
|
781
|
+
*
|
|
782
|
+
* OPTIONAL. Backends with no per-type tables omit it.
|
|
428
783
|
*/
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
784
|
+
promotePendingFields?(opts: {
|
|
785
|
+
lockTimeoutMs: number;
|
|
786
|
+
batchRows: number;
|
|
787
|
+
signal?: AbortSignal;
|
|
788
|
+
/** Retries fields a unique conflict holds back until their type's catalog changes: an operator's run after fixing the data. */
|
|
789
|
+
retryConflicts?: boolean;
|
|
790
|
+
/**
|
|
791
|
+
* The store has no other writers (migrate-store's target): a field's move
|
|
792
|
+
* to its column waits for its table lock, so a blocking autovacuum is
|
|
793
|
+
* cancelled, rather than retrying without queueing in front of writers.
|
|
794
|
+
*/
|
|
795
|
+
noWriters?: boolean;
|
|
796
|
+
}): Promise<PromotionEvent[]>;
|
|
438
797
|
/**
|
|
439
|
-
*
|
|
440
|
-
*
|
|
798
|
+
* Store-wide counts of the fields an operator should know about: held in
|
|
799
|
+
* jsonb until promoted, whose promotion failed, and no longer declared with
|
|
800
|
+
* their column kept. Counts only, with no namespace, type, field or error
|
|
801
|
+
* text, since `/health` shows it unauthenticated; `storageReport` names them.
|
|
802
|
+
*
|
|
803
|
+
* OPTIONAL. Backends with no per-type tables omit it.
|
|
441
804
|
*/
|
|
442
|
-
|
|
443
|
-
readonly name: string;
|
|
444
|
-
}): void;
|
|
805
|
+
fieldWarnings?(): Promise<string[]>;
|
|
445
806
|
/**
|
|
446
|
-
*
|
|
447
|
-
*
|
|
448
|
-
*
|
|
449
|
-
*
|
|
807
|
+
* The database-wide storage layout and what an operator should look at:
|
|
808
|
+
* indexes this process has yet to build or failed to build, fields whose
|
|
809
|
+
* promotion failed, and a type-table count over `partitionBudget`; and, as
|
|
810
|
+
* `info`, engine indexes no longer declared, pending and orphaned fields,
|
|
811
|
+
* and open index recommendations. Never changes anything.
|
|
450
812
|
*
|
|
451
|
-
*
|
|
452
|
-
* fall back to callback-driven invalidation when it is absent.
|
|
813
|
+
* OPTIONAL. Backends without per-type storage omit it.
|
|
453
814
|
*/
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
* Base class binding the `epoch` bookkeeping so an implementation cannot forget
|
|
458
|
-
* it. Subclasses supply storage via `performRegister` / `performReplace` and
|
|
459
|
-
* never implement `register` / `replace` themselves, so the counter is advanced
|
|
460
|
-
* by construction rather than by discipline.
|
|
461
|
-
*
|
|
462
|
-
* A throw from `performRegister` leaves the epoch untouched, which is correct:
|
|
463
|
-
* a rejected registration changed nothing.
|
|
464
|
-
*
|
|
465
|
-
* Decorators cannot extend this — they wrap an instance rather than subclass it
|
|
466
|
-
* — so a wrapping registry must forward `epoch` from the wrapped instance. See
|
|
467
|
-
* `substrate-compose`'s `_system` install for the worked example.
|
|
468
|
-
*/
|
|
469
|
-
declare abstract class RegistryBase implements Registry {
|
|
470
|
-
#private;
|
|
471
|
-
get epoch(): number;
|
|
472
|
-
register(key: string | {
|
|
473
|
-
readonly name: string;
|
|
474
|
-
}, input: RegistryEntryInput): void;
|
|
475
|
-
replace(key: string | {
|
|
476
|
-
readonly name: string;
|
|
477
|
-
}, input: RegistryEntryInput): void;
|
|
478
|
-
unregister(key: string | {
|
|
479
|
-
readonly name: string;
|
|
480
|
-
}): void;
|
|
481
|
-
/** Store a new entry. Throw to reject; the epoch will not advance. */
|
|
482
|
-
protected abstract performRegister(key: string | {
|
|
483
|
-
readonly name: string;
|
|
484
|
-
}, input: RegistryEntryInput): void;
|
|
485
|
-
/** Overwrite an existing entry. Throw to reject; the epoch will not advance. */
|
|
486
|
-
protected abstract performReplace(key: string | {
|
|
487
|
-
readonly name: string;
|
|
488
|
-
}, input: RegistryEntryInput): void;
|
|
489
|
-
/** Remove an entry. Not abstract, so existing subclasses stay valid; they refuse. */
|
|
490
|
-
protected performUnregister(key: string | {
|
|
491
|
-
readonly name: string;
|
|
492
|
-
}): void;
|
|
493
|
-
abstract get(key: string | {
|
|
494
|
-
readonly name: string;
|
|
495
|
-
}): RegistryEntry | undefined;
|
|
496
|
-
abstract has(key: string | {
|
|
497
|
-
readonly name: string;
|
|
498
|
-
}): boolean;
|
|
499
|
-
abstract all(): IterableIterator<[string, RegistryEntry]>;
|
|
500
|
-
}
|
|
501
|
-
/** See `EngineHandle.addDropParticipant`. */
|
|
502
|
-
interface DropParticipant {
|
|
503
|
-
/** Namespaces whose datasets `onDrop` writes, opened in the drop's transaction. */
|
|
504
|
-
readonly namespaces: readonly string[];
|
|
505
|
-
/** `datasetFor` returns the transaction-bound dataset of one of `namespaces`. */
|
|
506
|
-
onDrop(ns: string, datasetFor: (ns: string) => Dataset): Promise<void>;
|
|
507
|
-
}
|
|
508
|
-
interface NamespaceInstallContext {
|
|
509
|
-
registry: Registry;
|
|
510
|
-
dataset: Dataset;
|
|
511
|
-
edges: EdgesStore;
|
|
815
|
+
storageReport?(opts: {
|
|
816
|
+
partitionBudget: number;
|
|
817
|
+
}): Promise<StorageReport>;
|
|
512
818
|
/**
|
|
513
|
-
*
|
|
514
|
-
*
|
|
515
|
-
*
|
|
516
|
-
*
|
|
517
|
-
*
|
|
518
|
-
* `@mnmal-ai/substrate-sdk` does this automatically.
|
|
819
|
+
* Table and index statistics for every type the store holds, every
|
|
820
|
+
* namespace, read from the database's own statistics. Estimates, never a
|
|
821
|
+
* count. Never changes anything.
|
|
822
|
+
*
|
|
823
|
+
* OPTIONAL. Backends without such statistics omit it.
|
|
519
824
|
*/
|
|
520
|
-
|
|
825
|
+
typeStats?(): Promise<TypeStats[]>;
|
|
521
826
|
/**
|
|
522
|
-
*
|
|
523
|
-
*
|
|
524
|
-
*
|
|
525
|
-
*
|
|
526
|
-
*
|
|
827
|
+
* The indexes the engine wants for `namespace`/`type` (any namespace, not
|
|
828
|
+
* only this one), with each one's leading keys, and the type's size hint.
|
|
829
|
+
* Undefined when the type is unknown. Never changes anything.
|
|
830
|
+
*
|
|
831
|
+
* OPTIONAL. Backends that build no indexes omit it.
|
|
527
832
|
*/
|
|
528
|
-
|
|
529
|
-
}
|
|
530
|
-
/**
|
|
531
|
-
* Read-side context passed to `NamespaceTypeDef.embed.source` when the
|
|
532
|
-
* substrate composing the embedding (e.g. substrate-recall) has a dataset
|
|
533
|
-
* resolver wired. Lets the source function pull related-entity context
|
|
534
|
-
* via crossRefs (e.g. inline a linked Concept's name into the embedded
|
|
535
|
-
* text so semantic recall surfaces relevant rows).
|
|
536
|
-
*
|
|
537
|
-
* Minimal by design — `read` is the only method, and it returns the
|
|
538
|
-
* first matching row or `null`. Source functions that don't need
|
|
539
|
-
* crossRef enrichment ignore the parameter.
|
|
540
|
-
*/
|
|
541
|
-
interface EmbedSourceContext {
|
|
542
|
-
read: (namespace: string, type: string, params: {
|
|
543
|
-
id: string;
|
|
544
|
-
}) => Promise<Row | null>;
|
|
545
|
-
}
|
|
546
|
-
/**
|
|
547
|
-
* A declared index over a type's scalar or crossRef fields, built by the
|
|
548
|
-
* engine with the same expressions the filter compiler emits.
|
|
549
|
-
*
|
|
550
|
-
* - `fields`: key columns in order; `dir` defaults to `asc`. Both directions
|
|
551
|
-
* sort NULLs last, as `orderBy` does.
|
|
552
|
-
* - `unique`: refused at build time while duplicate live values exist.
|
|
553
|
-
* - `where`: always ANDed with "not deleted". `'live'` adds nothing more; a
|
|
554
|
-
* record adds equality to a boolean (or IS NULL for `null`) on the type's
|
|
555
|
-
* own fields. Only those operands compile to literals, which a generic plan
|
|
556
|
-
* needs to match the index predicate.
|
|
557
|
-
* - `name`: the pg index name to own or adopt; generated when omitted. It may
|
|
558
|
-
* not end in `__swap`, the reconciler's temporary suffix.
|
|
559
|
-
*/
|
|
560
|
-
interface IndexDecl {
|
|
561
|
-
fields: Array<string | {
|
|
562
|
-
field: string;
|
|
563
|
-
dir: 'asc' | 'desc';
|
|
564
|
-
}>;
|
|
565
|
-
unique?: boolean;
|
|
566
|
-
where?: 'live' | Record<string, boolean | null>;
|
|
567
|
-
name?: string;
|
|
568
|
-
}
|
|
569
|
-
/**
|
|
570
|
-
* Structural shape of a type definition, mirroring `TypeInput` from
|
|
571
|
-
* @mnmal-ai/substrate-sdk (redeclared to avoid a substrate-types → substrate-sdk import
|
|
572
|
-
* cycle). Substrate plugins read it structurally; slots not named here pass
|
|
573
|
-
* through opaquely.
|
|
574
|
-
*/
|
|
575
|
-
interface NamespaceTypeDef {
|
|
576
|
-
fields: Record<string, FieldDef>;
|
|
577
|
-
postWrite?: (row: Row, ctx: RequestContext) => Promise<void>;
|
|
578
|
-
embed?: {
|
|
579
|
-
/**
|
|
580
|
-
* Produce the source text fed to the embedder for this row, or `null` /
|
|
581
|
-
* `undefined` to declare the row un-indexable.
|
|
582
|
-
*
|
|
583
|
-
* The null sentinel is a RETRIEVAL POLICY, not an absence of text: it
|
|
584
|
-
* means "this row exists and must be referenceable, but must never enter
|
|
585
|
-
* the recall candidate set". The composing substrate both declines to
|
|
586
|
-
* index the row AND removes any embedding it already has, so a row that
|
|
587
|
-
* flips to un-indexable after being written stops being recallable
|
|
588
|
-
* without being deleted.
|
|
589
|
-
*
|
|
590
|
-
* `''` is NOT the sentinel — an empty string embeds normally. Returning
|
|
591
|
-
* `''` to mean "skip" indexes every such row at the same point in the
|
|
592
|
-
* vector space.
|
|
593
|
-
*
|
|
594
|
-
* `ctx` is optional — when the composing substrate has a dataset
|
|
595
|
-
* resolver wired, source functions may call `ctx.read(ns, type,
|
|
596
|
-
* { id })` to inline related-entity context. When `ctx` is undefined,
|
|
597
|
-
* the source must work from `row` alone. Async return is supported
|
|
598
|
-
* so source functions can await crossRef reads.
|
|
599
|
-
*/
|
|
600
|
-
source: (row: Row, ctx?: EmbedSourceContext) => string | null | undefined | Promise<string | null | undefined>;
|
|
601
|
-
};
|
|
833
|
+
indexPlan?(type: string, namespace: string): Promise<IndexPlan | undefined>;
|
|
602
834
|
/**
|
|
603
|
-
*
|
|
604
|
-
*
|
|
835
|
+
* Drop index `name` of this namespace's `type`, a signed `propose_index`
|
|
836
|
+
* remove. Only an engine-owned, non-unique index the engine no longer wants
|
|
837
|
+
* (a leftover or a retracted declaration) is dropped; anything else is
|
|
838
|
+
* refused with an error whose `code` is `unknown_index`, `not_engine_owned`,
|
|
839
|
+
* `unique_index` or `still_desired`, and nothing is dropped. A drop that
|
|
840
|
+
* waits longer than `lockTimeoutMs` on another transaction is abandoned with
|
|
841
|
+
* `index_drop_timeout`; the index may then be left invalid, and a retry drops it.
|
|
842
|
+
*
|
|
843
|
+
* OPTIONAL. Backends that build no indexes omit it (the memory dataset):
|
|
844
|
+
* there, `propose_index remove` has no index to find, so it is refused
|
|
845
|
+
* `unknown_index`, and a remove recommendation it names is superseded.
|
|
846
|
+
*/
|
|
847
|
+
dropEngineIndex?(type: string, name: string, opts?: {
|
|
848
|
+
/** Runs once every check has passed, just before the drop; a throw drops nothing. */
|
|
849
|
+
beforeDrop?: () => Promise<void>;
|
|
850
|
+
/** The drop's bound on each lock wait, in ms. Defaults to the backend's own. */
|
|
851
|
+
lockTimeoutMs?: number;
|
|
852
|
+
}): Promise<void>;
|
|
853
|
+
/**
|
|
854
|
+
* Drop the engine-owned indexes of this namespace, after a namespace drop
|
|
855
|
+
* has committed: its types leave the engine, so nothing would remove them.
|
|
856
|
+
* Non-unique ones only, unless `unique`, which the caller passes only when
|
|
857
|
+
* the namespace is declared nowhere (in no code and no live proposal): a
|
|
858
|
+
* declared namespace's types come back, and until the reconciler rebuilds a
|
|
859
|
+
* unique index, writes would not be held to it. Returns the names dropped.
|
|
860
|
+
* Never inside a transaction; a tx-bound instance throws. A lock wait that
|
|
861
|
+
* times out throws `index_drop_timeout`, leaving the rest for
|
|
862
|
+
* `storageReport` to list as orphaned.
|
|
863
|
+
*
|
|
864
|
+
* OPTIONAL. Backends that build no indexes omit it.
|
|
865
|
+
*/
|
|
866
|
+
dropNamespaceIndexes?(opts?: {
|
|
867
|
+
unique?: boolean;
|
|
868
|
+
}): Promise<string[]>;
|
|
869
|
+
/**
|
|
870
|
+
* The entry of this namespace's `type`'s declared `indexes` whose index is
|
|
871
|
+
* named `name`, or undefined when no declaration builds it (a derived or
|
|
872
|
+
* engine index, or none). `propose_index remove` retracts it when it is a
|
|
873
|
+
* proposed type's. Never changes anything.
|
|
874
|
+
*
|
|
875
|
+
* OPTIONAL. Backends that build no indexes omit it.
|
|
876
|
+
*/
|
|
877
|
+
indexDeclarationOf?(type: string, name: string): Promise<IndexDecl | undefined>;
|
|
878
|
+
/**
|
|
879
|
+
* Execute `fn` atomically. All ops performed on the `tx` argument run inside
|
|
880
|
+
* one substrate transaction. If `fn` throws or returns a rejected promise,
|
|
881
|
+
* every mutation inside the callback rolls back. If `fn` resolves, the
|
|
882
|
+
* transaction commits and the resolved value is returned.
|
|
883
|
+
*
|
|
884
|
+
* Scope rules:
|
|
885
|
+
* - `tx.namespace === this.namespace`
|
|
886
|
+
* - Calls on the outer dataset (`this`) inside `fn` bypass the transaction
|
|
887
|
+
* and are NOT rolled back on failure — this is a caller bug; implementations
|
|
888
|
+
* MUST NOT attempt to guard against it. All ops inside `fn` MUST go through
|
|
889
|
+
* `tx`.
|
|
890
|
+
* - Nested `tx.withTransaction(...)` is implementation-defined. The reference
|
|
891
|
+
* impls (memory, pg) flatten nested calls into the outermost transaction
|
|
892
|
+
* (no savepoints).
|
|
893
|
+
*/
|
|
894
|
+
withTransaction<T>(fn: (tx: Dataset) => Promise<T>): Promise<T>;
|
|
895
|
+
/**
|
|
896
|
+
* Engine-only. Open a substrate-level transaction spanning multiple
|
|
897
|
+
* namespaces on the same substrate, and invoke `fn` with a handles object
|
|
898
|
+
* containing tx-bound datasets + (optionally) a tx-bound `EdgesStore`.
|
|
899
|
+
* Called by the engine's mutate path (spec §5.3) for both single-ns and
|
|
900
|
+
* cross-ns frames — the engine calls with `[ns]` for the single-ns case.
|
|
605
901
|
*
|
|
606
|
-
*
|
|
607
|
-
*
|
|
608
|
-
*
|
|
609
|
-
*
|
|
902
|
+
* `namespaces` is the full set of namespaces the engine will dispatch
|
|
903
|
+
* frames to inside the tx. Implementations MUST return a tx-bound
|
|
904
|
+
* dataset for every requested namespace in `handles.datasets`; missing
|
|
905
|
+
* entries are a programming error on the caller side.
|
|
610
906
|
*
|
|
611
|
-
*
|
|
612
|
-
*
|
|
907
|
+
* `handles.edges` contract:
|
|
908
|
+
* - `non-null` when the implementation can enlist a shared `EdgesStore`
|
|
909
|
+
* into the same substrate tx (e.g. pg where the `PgEdgesStore` is wired
|
|
910
|
+
* in via constructor and shares the `Sql`). The engine routes edge
|
|
911
|
+
* mutations through this handle — true cross-store atomicity for
|
|
912
|
+
* row + edge within one frame.
|
|
913
|
+
* - `null` when the implementation can't enlist (e.g. memory datasets
|
|
914
|
+
* where edges live in a separate Map). The engine falls back to
|
|
915
|
+
* running edge ops in a nested independent tx and accepts the
|
|
916
|
+
* visibility-ordering quirk documented in `autocrud-delete.ts`.
|
|
917
|
+
*
|
|
918
|
+
* Scope rules mirror `withTransaction`:
|
|
919
|
+
* - All ops on values from `handles.datasets.get(ns)` and `handles.edges`
|
|
920
|
+
* run in the same tx.
|
|
921
|
+
* - Ops on the outer dataset (`this`) inside `fn` bypass the tx — caller
|
|
922
|
+
* bug; implementations do not guard.
|
|
923
|
+
* - A throw or rejection inside `fn` rolls back every mutation across
|
|
924
|
+
* every namespace + edges in the tx.
|
|
925
|
+
*
|
|
926
|
+
* OPTIONAL. Implementations that can't coalesce cross-namespace writes
|
|
927
|
+
* into one substrate transaction omit this method — the engine falls
|
|
928
|
+
* back to refusing cross-namespace batches with `cross_tx_scope_refused`
|
|
929
|
+
* (and loses edge-enlist for single-ns).
|
|
613
930
|
*/
|
|
614
|
-
|
|
615
|
-
source: (row: Row) => string | null | undefined | Promise<string | null | undefined>;
|
|
616
|
-
};
|
|
617
|
-
/** Composite and unique indexes the engine builds for this type. See {@link IndexDecl}. */
|
|
618
|
-
indexes?: IndexDecl[];
|
|
619
|
-
/** The type's natural order, the default read order. See {@link OrderedBy}. */
|
|
620
|
-
orderedBy?: OrderedBy;
|
|
621
|
-
/** See the SDK's `TypeInput.ordering`. */
|
|
622
|
-
ordering?: 'visible';
|
|
623
|
-
/** Size hint: `large` lowers the index advisor's row minimum for this type. */
|
|
624
|
-
expectedSize?: 'small' | 'large';
|
|
625
|
-
[key: string]: unknown;
|
|
626
|
-
}
|
|
627
|
-
interface NamespaceDefinition {
|
|
628
|
-
namespace: string;
|
|
931
|
+
withScopedTransaction?<T>(namespaces: ReadonlyArray<string>, fn: (handles: TxScopeHandles) => Promise<T>): Promise<T>;
|
|
629
932
|
/**
|
|
630
|
-
*
|
|
631
|
-
*
|
|
632
|
-
*
|
|
633
|
-
*
|
|
634
|
-
*
|
|
635
|
-
*
|
|
933
|
+
* Allocate the next short id for the given type within this dataset's
|
|
934
|
+
* namespace. Monotonic per (namespace, type). Does NOT record any
|
|
935
|
+
* row-id mapping — call `bindShortId` after the row is written.
|
|
936
|
+
*
|
|
937
|
+
* The implementation may use the dataset's current tx handle so the
|
|
938
|
+
* sequence advance rolls back on tx rollback (postgres sequences
|
|
939
|
+
* actually never roll back, but the surrounding tx semantics match
|
|
940
|
+
* what callers expect).
|
|
636
941
|
*/
|
|
637
|
-
|
|
942
|
+
allocateShortId(type: string): Promise<number>;
|
|
638
943
|
/**
|
|
639
|
-
*
|
|
640
|
-
*
|
|
944
|
+
* Record the (shortId → rowId) pairing after the row is written.
|
|
945
|
+
* Called by autoCRUD create immediately after the dataset write()
|
|
946
|
+
* returns the new row id. Safe to call within the enclosing tx.
|
|
641
947
|
*/
|
|
642
|
-
|
|
948
|
+
bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
|
|
643
949
|
/**
|
|
644
|
-
*
|
|
645
|
-
*
|
|
646
|
-
*
|
|
647
|
-
* identifier.
|
|
950
|
+
* Resolve a short id to the underlying row id, or null if no such short
|
|
951
|
+
* id exists for this (namespace, type). Does not join `rows` —
|
|
952
|
+
* callers chain their own `read()` after resolution.
|
|
648
953
|
*/
|
|
649
|
-
|
|
650
|
-
column: string;
|
|
651
|
-
kind: 'boolean' | 'text';
|
|
652
|
-
}>>;
|
|
954
|
+
resolveShortId(type: string, shortId: number): Promise<string | null>;
|
|
653
955
|
/**
|
|
654
|
-
*
|
|
655
|
-
*
|
|
656
|
-
*
|
|
657
|
-
* engine's `DatasetRegistry` is the app composition root's job.
|
|
956
|
+
* `count` fresh short ids for `type`, ascending, in one call (pg: one
|
|
957
|
+
* statement whatever `count`). Like `allocateShortId`, binds nothing.
|
|
958
|
+
* `count` of 0 returns `[]` and sends nothing.
|
|
658
959
|
*/
|
|
659
|
-
|
|
660
|
-
}
|
|
661
|
-
interface PluginLifecycleContext {
|
|
960
|
+
allocateShortIds(type: string, count: number): Promise<number[]>;
|
|
662
961
|
/**
|
|
663
|
-
*
|
|
664
|
-
*
|
|
665
|
-
* `onStart` handler is type-incompatible with a substrate's
|
|
666
|
-
* `onKernelReady` handler — the composition root sets this, and plugins
|
|
667
|
-
* can also branch on it at runtime if a single helper handles both
|
|
668
|
-
* lifecycle stages.
|
|
962
|
+
* `bindShortId` for many pairs at once (pg: one statement). Idempotent per
|
|
963
|
+
* pair, as `bindShortId` is. An empty `pairs` does nothing and sends nothing.
|
|
669
964
|
*/
|
|
670
|
-
|
|
965
|
+
bindShortIds(type: string, pairs: ReadonlyArray<{
|
|
966
|
+
shortId: number;
|
|
967
|
+
rowId: string;
|
|
968
|
+
}>): Promise<void>;
|
|
671
969
|
/**
|
|
672
|
-
*
|
|
673
|
-
*
|
|
674
|
-
*
|
|
675
|
-
*
|
|
970
|
+
* Set-wise `resolveShortId` for the LIVE rows among `shortIds` (pg: one
|
|
971
|
+
* statement). A short id with no binding, or whose row is tombstoned or
|
|
972
|
+
* purged, is absent from the map: the answer `resolveShortId` then a live
|
|
973
|
+
* `read` gives, which is how callers resolve today. Repeats in `shortIds`
|
|
974
|
+
* are deduped. An empty `shortIds` returns an empty map and sends nothing.
|
|
676
975
|
*/
|
|
677
|
-
|
|
976
|
+
resolveShortIds(type: string, shortIds: readonly number[]): Promise<ReadonlyMap<number, string>>;
|
|
678
977
|
/**
|
|
679
|
-
*
|
|
680
|
-
*
|
|
681
|
-
*
|
|
682
|
-
*
|
|
683
|
-
*
|
|
978
|
+
* Multi-row `update`: merges each patch into its LIVE row with today's
|
|
979
|
+
* semantics (a key absent from the patch keeps its value, `null` clears it;
|
|
980
|
+
* `id` and `_deletedAt` keys are ignored), stamps `updatedAt` = `now` and
|
|
981
|
+
* `updatedBy` = `actor` (the anonymous system actor when `null`), as
|
|
982
|
+
* `conditionalUpdate` does. pg runs one statement whatever the batch size.
|
|
983
|
+
*
|
|
984
|
+
* The result has one entry per patch, in order: the merged row, or `null`
|
|
985
|
+
* when `id` is not live. It never revives a tombstoned row or re-creates a
|
|
986
|
+
* purged one.
|
|
987
|
+
*
|
|
988
|
+
* A repeated `id` is allowed: its patches apply in input order (later keys
|
|
989
|
+
* win, as sequential patches would) and every slot for that id holds the
|
|
990
|
+
* final merged row. An empty `patches` returns `[]` and sends nothing.
|
|
684
991
|
*/
|
|
685
|
-
|
|
992
|
+
patchRows(type: string, patches: ReadonlyArray<{
|
|
993
|
+
id: Id;
|
|
994
|
+
patch: Record<string, unknown>;
|
|
995
|
+
}>, actor: ActorIdentity | null, now: Date): Promise<Array<Row | null>>;
|
|
996
|
+
/**
|
|
997
|
+
* Update every live row of `type` matching `where`: merges `set` into each,
|
|
998
|
+
* as `patchRows` does, and stamps `updatedAt` / `updatedBy`. When more than
|
|
999
|
+
* `opts.maxMatch` rows match it throws `ResolverFrameError('filter_too_broad')`
|
|
1000
|
+
* and changes nothing; zero matches is `{ count: 0 }`. pg runs one
|
|
1001
|
+
* statement, which locks the matched rows and re-tests `where` on each, so
|
|
1002
|
+
* a row a concurrent writer moved out of the filter is not updated.
|
|
1003
|
+
*/
|
|
1004
|
+
updateWhere?(type: string, where: WhereClause, set: Record<string, unknown>, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
1005
|
+
/**
|
|
1006
|
+
* Tombstone every live row of `type` matching `where`, under the same cap
|
|
1007
|
+
* and lock as `updateWhere`. `rows` are the pre-images. Checks no edges:
|
|
1008
|
+
* the caller gates `restrict` and rolls back.
|
|
1009
|
+
*/
|
|
1010
|
+
deleteWhere?(type: string, where: WhereClause, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
1011
|
+
/**
|
|
1012
|
+
* Inverse of `resolveShortId` — look up the short id assigned to a
|
|
1013
|
+
* given row id. Returns null if no sidecar entry exists (e.g. rows written
|
|
1014
|
+
* before short ids were allocated).
|
|
1015
|
+
*/
|
|
1016
|
+
getShortIdForRow(type: string, rowId: string): Promise<number | null>;
|
|
1017
|
+
/**
|
|
1018
|
+
* Spawn a sibling dataset bound to the same backing store but scoped to
|
|
1019
|
+
* a different namespace. Used by `compose()` to auto-allocate per-namespace
|
|
1020
|
+
* datasets when a coordinator plugin claims a namespace the operator hasn't
|
|
1021
|
+
* mapped explicitly.
|
|
1022
|
+
*
|
|
1023
|
+
* Substrate semantics:
|
|
1024
|
+
* - Pg: returns a new `PgDataset` sharing this dataset's `sql` pool +
|
|
1025
|
+
* `edgesStore`. The returned dataset has the SAME `txScopeId` (so it
|
|
1026
|
+
* can participate in cross-namespace batched mutations on the shared pool).
|
|
1027
|
+
* - Memory: returns a new `MemoryDataset` with its own backing `Map`
|
|
1028
|
+
* per the default convention (each instance owns its own substrate). The
|
|
1029
|
+
* returned dataset has a NEW `txScopeId` — it cannot share a transaction
|
|
1030
|
+
* with the caller. Test harnesses that need shared-memory semantics across
|
|
1031
|
+
* namespaces should construct each `MemoryDataset` explicitly with
|
|
1032
|
+
* the relevant constructor option.
|
|
1033
|
+
*
|
|
1034
|
+
* Idempotency note: callers SHOULD NOT call `forNamespace(this.namespace)`;
|
|
1035
|
+
* the resulting object's identity is implementation-defined. Use this only
|
|
1036
|
+
* to derive datasets for *different* namespaces.
|
|
1037
|
+
*/
|
|
1038
|
+
forNamespace(namespace: string): Dataset;
|
|
1039
|
+
}
|
|
1040
|
+
interface DatasetRegistry {
|
|
1041
|
+
get(ns: string): Dataset | undefined;
|
|
1042
|
+
has(ns: string): boolean;
|
|
1043
|
+
set(ns: string, dataset: Dataset): void;
|
|
1044
|
+
/**
|
|
1045
|
+
* Observe namespace lifecycle events (§6.4). Fires when a namespace is
|
|
1046
|
+
* disposed — explicit unregister or substrate-signalled loss (memory-backed
|
|
1047
|
+
* restart). Returns a disposer that unsubscribes when invoked.
|
|
1048
|
+
*
|
|
1049
|
+
* Optional: registries over persistent substrates (pg) never lose namespaces
|
|
1050
|
+
* at runtime and can omit this surface entirely. Consumers MUST feature-
|
|
1051
|
+
* detect before subscribing.
|
|
1052
|
+
*/
|
|
1053
|
+
onNamespaceLost?(listener: (ns: string) => void): () => void;
|
|
1054
|
+
/**
|
|
1055
|
+
* Explicitly drop `ns` from the registry and fire `onNamespaceLost`
|
|
1056
|
+
* listeners synchronously. Disposing an unregistered namespace is a silent
|
|
1057
|
+
* no-op — keeps graceful-shutdown replays idempotent.
|
|
1058
|
+
*
|
|
1059
|
+
* Optional: same rationale as `onNamespaceLost`.
|
|
1060
|
+
*/
|
|
1061
|
+
dispose?(ns: string): void;
|
|
686
1062
|
}
|
|
687
1063
|
/**
|
|
688
|
-
*
|
|
689
|
-
*
|
|
690
|
-
*
|
|
691
|
-
* substrate-types stays zero-runtime.
|
|
1064
|
+
* One declared index of a type and its state: as the catalog holds it, or,
|
|
1065
|
+
* while this process defers or runs its build, `pending`, `building` or
|
|
1066
|
+
* `failed`. Filters on an index that is not `valid` scan.
|
|
692
1067
|
*/
|
|
693
|
-
interface
|
|
694
|
-
|
|
695
|
-
fields
|
|
1068
|
+
interface TypeIndexState {
|
|
1069
|
+
name: string;
|
|
1070
|
+
fields: string[];
|
|
1071
|
+
unique: boolean;
|
|
1072
|
+
state: 'valid' | 'building' | 'pending' | 'invalid' | 'failed';
|
|
1073
|
+
outcome: 'created' | 'adopted' | 'swapped' | 'unchanged';
|
|
1074
|
+
/** Why a `failed` index failed: an error code, then a short reason. */
|
|
1075
|
+
error?: string;
|
|
1076
|
+
/** Why a `pending` index was not built: the free-disk check refused it. */
|
|
1077
|
+
reason?: 'insufficient_disk';
|
|
1078
|
+
}
|
|
1079
|
+
/** Where a type's rows live: `table` is set once the type has its table. */
|
|
1080
|
+
interface TypeStorageReport {
|
|
1081
|
+
layout: 'tables';
|
|
1082
|
+
table?: string;
|
|
1083
|
+
indexes: TypeIndexState[];
|
|
1084
|
+
/** Declared fields whose values live in `extra` until they get a column. */
|
|
1085
|
+
pending?: string[];
|
|
1086
|
+
/** Fields no longer declared whose columns are kept. */
|
|
1087
|
+
orphaned?: string[];
|
|
1088
|
+
}
|
|
1089
|
+
/**
|
|
1090
|
+
* One field's outcome in a promotion sweep (`Dataset.promotePendingFields`):
|
|
1091
|
+
* `promoted` (it has its column and every value moved), `busy` (its table's
|
|
1092
|
+
* lock was held past the timeout; retried next sweep) or `failed` (an error,
|
|
1093
|
+
* or the third busy attempt in a row). `attempts` counts this one. A field
|
|
1094
|
+
* another process is sweeping is `busy` with the error `held by another
|
|
1095
|
+
* process`, and its `attempts` is the recorded count, unchanged.
|
|
1096
|
+
*/
|
|
1097
|
+
interface PromotionEvent {
|
|
1098
|
+
kind: 'promoted' | 'busy' | 'failed';
|
|
1099
|
+
namespace: string;
|
|
1100
|
+
type: string;
|
|
1101
|
+
field: string;
|
|
1102
|
+
attempts: number;
|
|
1103
|
+
error?: string;
|
|
1104
|
+
}
|
|
1105
|
+
interface StorageReport {
|
|
1106
|
+
/** `unknown` when the report itself failed. */
|
|
1107
|
+
layout: 'tables' | 'unknown';
|
|
1108
|
+
warnings: string[];
|
|
1109
|
+
/** Worth showing, not a fault: the doctor prints these without failing. */
|
|
1110
|
+
info?: string[];
|
|
1111
|
+
}
|
|
1112
|
+
/** See `Dataset.indexPlan`. */
|
|
1113
|
+
interface IndexPlan {
|
|
1114
|
+
/** Each desired index, its keys in order: a derived index ends with the type's natural order. */
|
|
1115
|
+
indexes: Array<{
|
|
1116
|
+
name: string;
|
|
1117
|
+
keys: Array<[string, 'asc' | 'desc']>;
|
|
1118
|
+
unique: boolean;
|
|
1119
|
+
/** A partial index's predicate beyond `live`: it serves only reads that `eq` each field to its value. */
|
|
1120
|
+
only?: Record<string, boolean | null>;
|
|
1121
|
+
}>;
|
|
1122
|
+
expectedSize?: 'small' | 'large';
|
|
1123
|
+
}
|
|
1124
|
+
//#endregion
|
|
1125
|
+
//#region ../../packages/substrate-types/src/policy.d.ts
|
|
1126
|
+
interface Identity {
|
|
1127
|
+
id: string;
|
|
1128
|
+
roles?: string[];
|
|
1129
|
+
scopes?: string[];
|
|
696
1130
|
/**
|
|
697
|
-
*
|
|
698
|
-
*
|
|
699
|
-
*
|
|
1131
|
+
* Per-namespace capabilities — the only grant surface. `{ notes: ['read'],
|
|
1132
|
+
* tasks: ['read','mutate'] }`; `'*'` is a legal key. Read it through the
|
|
1133
|
+
* `identity-grant.ts` helpers.
|
|
1134
|
+
*
|
|
1135
|
+
* A plain object rather than a Map: `Identity` is JSON-serialised into the
|
|
1136
|
+
* SSE stream ticket, and a Map would arrive as `{}` on the far side.
|
|
1137
|
+
*
|
|
1138
|
+
* A bare `{ id }` with no grant (direct-call tests, system actors) is the
|
|
1139
|
+
* no-claim case: `grantOf` resolves it to `null`, and the engine's grant
|
|
1140
|
+
* gate then admits every namespace. An authenticator for remote callers
|
|
1141
|
+
* must therefore always set `grants`, `{}` for none.
|
|
700
1142
|
*/
|
|
701
|
-
|
|
1143
|
+
grants: Record<string, string[]>;
|
|
1144
|
+
[k: string]: unknown;
|
|
702
1145
|
}
|
|
703
1146
|
/**
|
|
704
|
-
*
|
|
705
|
-
*
|
|
706
|
-
*
|
|
707
|
-
* Batched mutate (§5.13): a mutate op-key MAY carry an array of `FrameEntry`
|
|
708
|
-
* values. All frames under one op-key run serially inside the SAME
|
|
709
|
-
* transaction — all-or-nothing per op-key, committed independently of other
|
|
710
|
-
* op-keys. Single-frame op-keys share one transaction when they share a
|
|
711
|
-
* substrate and are refused (`cross_tx_scope_refused`) when they do not.
|
|
712
|
-
* Query / subscribe / stream op-keys reject array values.
|
|
1147
|
+
* Semantic verb stamped on autoCRUD-registered mutation entries.
|
|
1148
|
+
* Absent on type entries and custom mutations — policies needing those use
|
|
1149
|
+
* `RequestContext.entry` / `operation` instead.
|
|
713
1150
|
*/
|
|
714
|
-
type
|
|
715
|
-
interface
|
|
716
|
-
|
|
717
|
-
|
|
1151
|
+
type AutoCrudVerb = 'get' | 'create' | 'update' | 'delete';
|
|
1152
|
+
interface RequestContext {
|
|
1153
|
+
identity: Identity | null;
|
|
1154
|
+
namespace: string;
|
|
1155
|
+
operation: 'query' | 'mutate' | 'subscribe' | 'stream';
|
|
1156
|
+
now: Date;
|
|
1157
|
+
headers: Record<string, string>;
|
|
1158
|
+
meta: Record<string, unknown>;
|
|
718
1159
|
/**
|
|
719
|
-
*
|
|
720
|
-
*
|
|
721
|
-
* `
|
|
1160
|
+
* Trust-gated client IP computed by the HTTP route handler from the request's
|
|
1161
|
+
* `peerIp` + the operator-configured trusted-proxy allowlist. When the peer
|
|
1162
|
+
* is in the allowlist, this is the leftmost `x-forwarded-for` entry; when
|
|
1163
|
+
* untrusted, this is the peer IP itself. Undefined when the transport doesn't
|
|
1164
|
+
* expose peerIp (direct engine unit tests, pre-upgrade WS paths).
|
|
722
1165
|
*/
|
|
723
|
-
|
|
1166
|
+
clientIp?: string;
|
|
724
1167
|
/**
|
|
725
|
-
*
|
|
726
|
-
* a
|
|
727
|
-
*
|
|
1168
|
+
* Whether the deployment verifies credentials at all, as the transport knows
|
|
1169
|
+
* it, so a refusal for want of an identity can say whether auth is off
|
|
1170
|
+
* rather than implying the caller's key is wrong.
|
|
1171
|
+
*
|
|
1172
|
+
* `undefined` means the transport did not say (direct engine unit tests,
|
|
1173
|
+
* routes with no auth config in scope). Treat it as unknown, never as `false`.
|
|
728
1174
|
*/
|
|
729
|
-
|
|
730
|
-
readonly defaultLimit: number;
|
|
731
|
-
readonly maxLimit: number;
|
|
732
|
-
};
|
|
733
|
-
}
|
|
734
|
-
/**
|
|
735
|
-
* Per-namespace engine configuration. substrate-core imports this type rather
|
|
736
|
-
* than redeclaring it.
|
|
737
|
-
*/
|
|
738
|
-
interface NamespaceConfig {
|
|
739
|
-
registry: Registry;
|
|
1175
|
+
authEnabled?: boolean;
|
|
740
1176
|
/**
|
|
741
|
-
*
|
|
742
|
-
*
|
|
743
|
-
*
|
|
744
|
-
*
|
|
745
|
-
*
|
|
746
|
-
*
|
|
747
|
-
*
|
|
1177
|
+
* The registry entry name this dispatch targets — the `<name>` half of the
|
|
1178
|
+
* qualified frame key (e.g. `deleteTodo`, `Todo`). Threaded by the engine
|
|
1179
|
+
* at every dispatch site (query/mutate/stream/subscribe) so type- and
|
|
1180
|
+
* plugin-level policies can discriminate between resolvers that otherwise
|
|
1181
|
+
* present identically (`get<T>` and `delete<T>` both arrive as
|
|
1182
|
+
* operation:'mutate' with id-only params). Undefined only in direct-call
|
|
1183
|
+
* unit tests that construct a bare ctx.
|
|
748
1184
|
*/
|
|
749
|
-
|
|
750
|
-
/**
|
|
751
|
-
|
|
1185
|
+
entry?: string;
|
|
1186
|
+
/**
|
|
1187
|
+
* Semantic verb of the targeted entry when autoCRUD registered it.
|
|
1188
|
+
* Prefer this over `entry`-name matching for intent-level policies
|
|
1189
|
+
* ("deny deletes") — it survives entry renames. Absent for type entries
|
|
1190
|
+
* and custom mutations.
|
|
1191
|
+
*/
|
|
1192
|
+
verb?: AutoCrudVerb;
|
|
752
1193
|
}
|
|
753
|
-
/**
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
interface EngineHandle {
|
|
760
|
-
query(input: EngineInput): Promise<PackEnvelope>;
|
|
761
|
-
mutate(input: EngineInput): Promise<PackEnvelope>;
|
|
1194
|
+
/** The caller's request context for a policy check made outside dispatch. */
|
|
1195
|
+
type PolicyProbeContext = Partial<Pick<RequestContext, 'now' | 'headers' | 'meta' | 'clientIp' | 'authEnabled'>>;
|
|
1196
|
+
interface ResolverArgs {
|
|
1197
|
+
params?: Record<string, unknown>;
|
|
1198
|
+
fields?: Record<string, unknown>;
|
|
1199
|
+
rows?: Row[];
|
|
762
1200
|
/**
|
|
763
|
-
*
|
|
764
|
-
*
|
|
765
|
-
*
|
|
766
|
-
*
|
|
767
|
-
*
|
|
1201
|
+
* Engine-injected per-call dataset handle. On `engine.mutate`, this is the
|
|
1202
|
+
* transaction-scoped `tx` view (spec §5.3, G1); on `engine.query` it's the
|
|
1203
|
+
* plain namespace dataset. Resolvers that perform I/O MUST use this handle
|
|
1204
|
+
* — using a dataset captured at registration time bypasses the active
|
|
1205
|
+
* transaction and breaks atomicity. Optional purely to keep direct-resolver
|
|
1206
|
+
* unit tests concise; the engine always supplies it.
|
|
768
1207
|
*/
|
|
769
|
-
|
|
1208
|
+
dataset?: Dataset;
|
|
770
1209
|
/**
|
|
771
|
-
*
|
|
772
|
-
*
|
|
773
|
-
*
|
|
774
|
-
*
|
|
775
|
-
*
|
|
1210
|
+
* Engine-injected per-call edges store (§4.6). Resolvers that touch edges
|
|
1211
|
+
* MUST use this handle; the closed-over store from registration is a
|
|
1212
|
+
* fallback for direct-call tests. Unlike `dataset`, this is not namespace-
|
|
1213
|
+
* scoped — edges are inherently cross-namespace, and a single engine-scoped
|
|
1214
|
+
* `EdgesStore` is threaded through every call.
|
|
776
1215
|
*/
|
|
777
|
-
|
|
1216
|
+
edges?: EdgesStore;
|
|
778
1217
|
/**
|
|
779
|
-
*
|
|
780
|
-
*
|
|
781
|
-
*
|
|
782
|
-
*
|
|
783
|
-
*
|
|
1218
|
+
* Engine-injected post-commit write hook (§5.4). Write-path resolvers
|
|
1219
|
+
* (autoCRUD create/update/delete, or custom mutation resolvers) call this
|
|
1220
|
+
* AFTER their substrate write lands to announce the change. The engine
|
|
1221
|
+
* collects calls into a per-transaction batch and fans them out to the
|
|
1222
|
+
* subscription bus only after the enclosing `withTransaction` commits — a
|
|
1223
|
+
* rolled-back tx emits nothing. Direct-call unit tests may pass `onWrite` to
|
|
1224
|
+
* observe resolver output without spinning up an engine.
|
|
784
1225
|
*/
|
|
785
|
-
|
|
1226
|
+
onWrite?: (event: WriteEvent) => void;
|
|
786
1227
|
/**
|
|
787
|
-
*
|
|
788
|
-
*
|
|
789
|
-
*
|
|
790
|
-
*
|
|
791
|
-
*
|
|
792
|
-
* - existing live subscriptions on the ns are closed with a
|
|
793
|
-
* `namespace_tombstoned` error frame
|
|
794
|
-
*
|
|
795
|
-
* Idempotent. The underlying NamespaceConfig stays in `#namespaces` for
|
|
796
|
-
* concurrency safety (in-flight ops keep their references) — full physical
|
|
797
|
-
* reclaim happens at engine restart, gated by whatever persistence layer
|
|
798
|
-
* the host uses to decide which namespaces to re-install at boot. Tombstone
|
|
799
|
-
* state itself is in-memory; restart wipes it.
|
|
1228
|
+
* Queue work to run once the surrounding transaction has settled, whether it
|
|
1229
|
+
* committed or rolled back: a record that must outlive a rollback, such as
|
|
1230
|
+
* an audit row for the refusal that caused it. The work is told which
|
|
1231
|
+
* (`committed`), so post-commit work can skip a rollback. Absent outside a
|
|
1232
|
+
* transaction, where the caller can simply do the work.
|
|
800
1233
|
*/
|
|
801
|
-
|
|
1234
|
+
afterTx?: (fn: AfterTxWork) => void;
|
|
802
1235
|
/**
|
|
803
|
-
*
|
|
804
|
-
*
|
|
805
|
-
*
|
|
1236
|
+
* Engine-injected cancellation signal (§5.5). Supplied on `stream` dispatch
|
|
1237
|
+
* so generator resolvers can abort mid-iteration when the client cancels or
|
|
1238
|
+
* the socket closes. Streaming resolvers SHOULD observe this signal — either
|
|
1239
|
+
* by calling `signal.throwIfAborted()` at yield points, or by listening for
|
|
1240
|
+
* `abort` to release cursors / close descriptors in their `finally` block.
|
|
1241
|
+
* The engine cannot force-stop a generator; cooperation is the contract.
|
|
1242
|
+
* Absent on query/mutate dispatch — non-streaming resolvers should not see a
|
|
1243
|
+
* signal they have no way to honour.
|
|
806
1244
|
*/
|
|
807
|
-
|
|
1245
|
+
signal?: AbortSignal;
|
|
808
1246
|
/**
|
|
809
|
-
*
|
|
810
|
-
*
|
|
811
|
-
*
|
|
812
|
-
*
|
|
1247
|
+
* Engine-injected cross-namespace dataset resolver (committed, non-tx view).
|
|
1248
|
+
* Write-path resolvers use it to verify crossRef referents that live in a
|
|
1249
|
+
* DIFFERENT namespace (onMissing:'reject'). Same-namespace targets should use
|
|
1250
|
+
* the tx-scoped `dataset` handle instead. Absent on the query/subscribe path.
|
|
813
1251
|
*/
|
|
814
|
-
|
|
815
|
-
/** The participants `addDropParticipant` registered, for the drop route. */
|
|
816
|
-
dropParticipants(): readonly DropParticipant[];
|
|
1252
|
+
resolveDataset?: (ns: string) => Dataset | undefined;
|
|
817
1253
|
/**
|
|
818
|
-
*
|
|
819
|
-
*
|
|
820
|
-
*
|
|
821
|
-
* runtime add, e.g. a rolled-back propose_namespace. Idempotent.
|
|
1254
|
+
* Engine-injected on mutate: how many frame entries share this call's
|
|
1255
|
+
* transaction, itself included. A resolver whose effect waits on other
|
|
1256
|
+
* transactions (a concurrent index drop) refuses to share one.
|
|
822
1257
|
*/
|
|
823
|
-
|
|
824
|
-
/**
|
|
825
|
-
|
|
1258
|
+
txEntries?: number;
|
|
1259
|
+
/** Engine-injected on `updateMany<T>` / `deleteMany<T>`: the deployment's caps. */
|
|
1260
|
+
filterWriteLimits?: FilterWriteLimits;
|
|
1261
|
+
}
|
|
1262
|
+
/**
|
|
1263
|
+
* Post-commit write announcement consumed by the engine's subscription bus
|
|
1264
|
+
* (§5.4). Emitted by write-path resolvers after the substrate operation
|
|
1265
|
+
* commits inside the current transaction. `row` is the post-commit canonical
|
|
1266
|
+
* row for creates and updates; for deletes it's the pre-tombstone snapshot
|
|
1267
|
+
* (absent if the resolver couldn't read the row before deleting). The engine
|
|
1268
|
+
* filters matching subscriptions by `(ns, type)`, tests the `row` against each
|
|
1269
|
+
* subscription's `where` predicate, and emits `add` / `update` / `remove`.
|
|
1270
|
+
*/
|
|
1271
|
+
interface WriteEvent {
|
|
1272
|
+
ns: string;
|
|
1273
|
+
type: string;
|
|
1274
|
+
id: Row['id'];
|
|
1275
|
+
operation: 'create' | 'update' | 'delete';
|
|
1276
|
+
row?: Row;
|
|
1277
|
+
}
|
|
1278
|
+
interface Obligation {
|
|
1279
|
+
kind: string;
|
|
1280
|
+
[k: string]: unknown;
|
|
1281
|
+
}
|
|
1282
|
+
/**
|
|
1283
|
+
* Row-filter obligation: emitted by `row<T>(predicate)` policies. The engine
|
|
1284
|
+
* scans accumulated obligations after resolver execution and applies each
|
|
1285
|
+
* predicate as a silent filter.
|
|
1286
|
+
*/
|
|
1287
|
+
interface RowFilterObligation<T = unknown> extends Obligation {
|
|
1288
|
+
kind: 'row-filter';
|
|
1289
|
+
predicate: (ctx: RequestContext, row: T) => boolean;
|
|
1290
|
+
}
|
|
1291
|
+
interface PolicyDecision {
|
|
1292
|
+
allow: boolean;
|
|
1293
|
+
reason?: string;
|
|
1294
|
+
obligations?: Obligation[];
|
|
1295
|
+
}
|
|
1296
|
+
type Policy = (ctx: RequestContext, args: ResolverArgs) => PolicyDecision;
|
|
1297
|
+
/**
|
|
1298
|
+
* Engine-facing resolver shape. Spec: §4.3, §5.2, §5.5.
|
|
1299
|
+
*
|
|
1300
|
+
* The engine treats any resolver's return as opaque rows. A `ReadResult` return
|
|
1301
|
+
* signals a paged list; the engine unpacks `rows` into the envelope and copies
|
|
1302
|
+
* `nextCursor`/`hasMore` into `_pagination[key]`. An `AsyncIterable<Row>`
|
|
1303
|
+
* return is the §5.5 stream-dispatch shape (duck-typed via
|
|
1304
|
+
* `Symbol.asyncIterator` so it can't collide with `Row[]`).
|
|
1305
|
+
*
|
|
1306
|
+
* This is what the registry stores and what the engine dispatches to. Plugin
|
|
1307
|
+
* authors declaring custom resolvers use the typed-authoring form
|
|
1308
|
+
* `TypedResolver<T>` below; the engine erases to `Resolver` at registration
|
|
1309
|
+
* time.
|
|
1310
|
+
*/
|
|
1311
|
+
type Resolver = (ctx: RequestContext, args: ResolverArgs) => Promise<Row | Row[] | ReadResult | AsyncIterable<Row> | null> | AsyncIterable<Row>;
|
|
1312
|
+
/**
|
|
1313
|
+
* Typed-authoring resolver shape. Used by autoCRUD and hand-authored resolvers
|
|
1314
|
+
* that want to preserve the concrete return type before erasing to `Resolver`
|
|
1315
|
+
* at registration. `T` is unconstrained at the type level — the engine
|
|
1316
|
+
* discriminates on the runtime value shape regardless of static type.
|
|
1317
|
+
*/
|
|
1318
|
+
type TypedResolver<T> = (ctx: RequestContext, args: ResolverArgs) => Promise<T>;
|
|
1319
|
+
/**
|
|
1320
|
+
* Engine-visible return shape for a resolver. `ReadResult` means "paged list";
|
|
1321
|
+
* `Row[]` means "full list, no pagination"; `Row` means "single"; `null` means
|
|
1322
|
+
* "single, not found". The engine discriminates at runtime.
|
|
1323
|
+
*/
|
|
1324
|
+
type ResolverReturn = Row | Row[] | ReadResult | null;
|
|
1325
|
+
/** Work queued through `ResolverArgs.afterTx`, told whether the transaction committed. */
|
|
1326
|
+
type AfterTxWork = (outcome: {
|
|
1327
|
+
committed: boolean;
|
|
1328
|
+
}) => Promise<void>;
|
|
1329
|
+
//#endregion
|
|
1330
|
+
//#region ../../packages/substrate-types/src/server.d.ts
|
|
1331
|
+
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
|
|
1332
|
+
interface SubstrateRequest {
|
|
1333
|
+
method: HttpMethod;
|
|
1334
|
+
path: string;
|
|
1335
|
+
headers: Record<string, string>;
|
|
1336
|
+
query: Record<string, string>;
|
|
1337
|
+
params: Record<string, string>;
|
|
1338
|
+
body: Buffer | null;
|
|
1339
|
+
identity?: Identity;
|
|
1340
|
+
/**
|
|
1341
|
+
* Remote peer IP observed at the transport layer. Populated by adapters
|
|
1342
|
+
* (Fastify: `request.ip`; memory: caller supplies via `inject({ peerIp })`).
|
|
1343
|
+
* Absent when transport doesn't expose it. Consumers that gate on peer IP
|
|
1344
|
+
* (e.g. `x-forwarded-for` trust) treat `undefined` as "untrusted peer".
|
|
1345
|
+
*/
|
|
1346
|
+
peerIp?: string;
|
|
826
1347
|
/**
|
|
827
|
-
*
|
|
828
|
-
*
|
|
829
|
-
* without taking a runtime dep on the concrete Registry class in substrate-core.
|
|
1348
|
+
* Client IP after the trusted-proxy check, stamped by the host before plugin
|
|
1349
|
+
* and kernel route handlers run. Never read from the client.
|
|
830
1350
|
*/
|
|
831
|
-
|
|
1351
|
+
clientIp?: string;
|
|
1352
|
+
/** Whether the deployment verifies credentials, stamped with `clientIp`. */
|
|
1353
|
+
authEnabled?: boolean;
|
|
832
1354
|
/**
|
|
833
|
-
*
|
|
834
|
-
*
|
|
835
|
-
*
|
|
836
|
-
*
|
|
837
|
-
*
|
|
838
|
-
*
|
|
839
|
-
* Substrate selection remains the host's responsibility — this method only
|
|
840
|
-
* exposes the lookup. Plugins that hot-add namespaces (substrate-proposals'
|
|
841
|
-
* `propose_namespace`) MUST require the host to register the dataset before
|
|
842
|
-
* the call; this method returns `undefined` for unregistered namespaces.
|
|
1355
|
+
* Per-request abort signal. Production transports (Fastify) wire it to fire
|
|
1356
|
+
* on socket close (client disconnect) and on `abortAllRequests()` during
|
|
1357
|
+
* graceful shutdown. Route handlers thread it into `engine.query/mutate`
|
|
1358
|
+
* via `signal:` so resolvers can cooperatively bail. Optional because
|
|
1359
|
+
* test fixtures and embedded `inject()` callers may not need cancellation.
|
|
843
1360
|
*/
|
|
844
|
-
|
|
1361
|
+
signal?: AbortSignal;
|
|
845
1362
|
}
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
*/
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
1363
|
+
interface SubstrateResponse {
|
|
1364
|
+
status: number;
|
|
1365
|
+
headers?: Record<string, string>;
|
|
1366
|
+
body?: Buffer | Uint8Array | string | ReadableStream;
|
|
1367
|
+
}
|
|
1368
|
+
type HttpHandler = (req: SubstrateRequest) => SubstrateResponse | Promise<SubstrateResponse>;
|
|
1369
|
+
/** Request op classes counted by the runtime-metrics surface (§ engine-metrics spec). */
|
|
1370
|
+
type RuntimeOp = 'query' | 'mutate';
|
|
1371
|
+
/** One observed HTTP request at the transport seam. */
|
|
1372
|
+
interface RequestObservation {
|
|
1373
|
+
readonly op: RuntimeOp;
|
|
1374
|
+
/** Transport-level success — HTTP status < 400. Frame-level envelope errors still count ok. */
|
|
1375
|
+
readonly ok: boolean;
|
|
1376
|
+
/** Wall-clock elapsed from handler entry to response, measured via Date.now(). Always >= 0. */
|
|
1377
|
+
readonly durationMs: number;
|
|
1378
|
+
}
|
|
1379
|
+
type RequestObserver = (o: RequestObservation) => void;
|
|
1380
|
+
interface WsConnection {
|
|
1381
|
+
readonly id: string;
|
|
1382
|
+
send(frame: Buffer | Uint8Array | string): void;
|
|
856
1383
|
/**
|
|
857
|
-
*
|
|
858
|
-
*
|
|
859
|
-
*
|
|
1384
|
+
* Transport-level back-pressure seam. Resolves once the
|
|
1385
|
+
* socket's write buffer is below its high-water mark — immediately when it
|
|
1386
|
+
* already is. The stream route awaits this between chunks so a fast producer
|
|
1387
|
+
* paces to a slow consumer instead of growing the send buffer unbounded.
|
|
1388
|
+
* Optional: transports without buffer introspection (memory tests) omit it,
|
|
1389
|
+
* and the route treats a missing hook as "always drained".
|
|
860
1390
|
*/
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
1391
|
+
drain?(): Promise<void>;
|
|
1392
|
+
onMessage(cb: (frame: Buffer) => void): void;
|
|
1393
|
+
onClose(cb: (code?: number) => void): void;
|
|
1394
|
+
close(code?: number, reason?: string): void;
|
|
1395
|
+
/**
|
|
1396
|
+
* Register a callback invoked synchronously during graceful server shutdown,
|
|
1397
|
+
* BEFORE the underlying socket is closed. Higher layers use this to flush
|
|
1398
|
+
* structured frames (e.g. `{ kind: 'end', reason: 'server_restart' }` per
|
|
1399
|
+
* active subscription) so clients can short-circuit reconnect backoff
|
|
1400
|
+
* instead of seeing an abrupt 1006 drop. Optional — transports without a
|
|
1401
|
+
* pre-close hook (memory tests) may omit it; the route layer should
|
|
1402
|
+
* tolerate undefined.
|
|
1403
|
+
*/
|
|
1404
|
+
onShutdown?(cb: (reason: string) => void): void;
|
|
866
1405
|
}
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
pluginName: string;
|
|
873
|
-
/** Engine handle for read/write work performed by the task. */
|
|
874
|
-
engine: EngineHandle;
|
|
875
|
-
/** Structured metric sink — fire-and-forget. */
|
|
876
|
-
metric(name: string, payload?: unknown): void;
|
|
1406
|
+
type WsHandler = (req: SubstrateRequest, conn: WsConnection) => void | Promise<void>;
|
|
1407
|
+
interface TlsConfig {
|
|
1408
|
+
cert: string | Buffer;
|
|
1409
|
+
key: string | Buffer;
|
|
1410
|
+
ca?: string | Buffer;
|
|
877
1411
|
}
|
|
878
|
-
interface
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
intervalMs: number;
|
|
883
|
-
/** Fire once at registration in addition to the interval ticks. Default false. */
|
|
884
|
-
runOnStart?: boolean;
|
|
885
|
-
/** Handler — receives a context with engine access for read/write work. */
|
|
886
|
-
handler(ctx: ScheduledTaskContext): void | Promise<void>;
|
|
1412
|
+
interface StartOpts {
|
|
1413
|
+
host?: string;
|
|
1414
|
+
port?: number;
|
|
1415
|
+
tls?: TlsConfig;
|
|
887
1416
|
}
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
engine: EngineHandle;
|
|
896
|
-
/** Structured metric sink — fire-and-forget. */
|
|
897
|
-
metric(name: string, payload?: unknown): void;
|
|
1417
|
+
interface PluginRouter {
|
|
1418
|
+
get(path: string, handler: HttpHandler): void;
|
|
1419
|
+
post(path: string, handler: HttpHandler): void;
|
|
1420
|
+
put(path: string, handler: HttpHandler): void;
|
|
1421
|
+
delete(path: string, handler: HttpHandler): void;
|
|
1422
|
+
patch(path: string, handler: HttpHandler): void;
|
|
1423
|
+
websocket(path: string, handler: WsHandler): void;
|
|
898
1424
|
}
|
|
899
|
-
interface
|
|
900
|
-
|
|
901
|
-
|
|
1425
|
+
interface SubstrateServer {
|
|
1426
|
+
start(opts?: StartOpts): Promise<{
|
|
1427
|
+
address: string;
|
|
1428
|
+
port: number;
|
|
1429
|
+
}>;
|
|
1430
|
+
stop(opts?: {
|
|
1431
|
+
grace?: number;
|
|
1432
|
+
abortInFlight?: boolean;
|
|
1433
|
+
}): Promise<void>;
|
|
1434
|
+
route(method: HttpMethod, path: string, handler: HttpHandler): void;
|
|
1435
|
+
websocket(path: string, handler: WsHandler): void;
|
|
1436
|
+
onError?(hook: (err: Error, req?: SubstrateRequest) => void): void;
|
|
1437
|
+
createPluginRouter(plugin: {
|
|
1438
|
+
name: string;
|
|
1439
|
+
}): PluginRouter;
|
|
902
1440
|
/**
|
|
903
|
-
*
|
|
904
|
-
*
|
|
1441
|
+
* Abort every in-flight HTTP request's `req.signal` so resolvers cooperatively
|
|
1442
|
+
* bail. Used during graceful shutdown to give the engine a chance to roll
|
|
1443
|
+
* back mutations before fastify's drain timeout fires. WS connections are
|
|
1444
|
+
* not affected by this call; their teardown rides on socket close.
|
|
1445
|
+
*/
|
|
1446
|
+
abortAllRequests(reason?: string): void;
|
|
1447
|
+
/**
|
|
1448
|
+
* Register a callback invoked synchronously at the START of `stop()` —
|
|
1449
|
+
* before in-flight requests are aborted and before the transport drains.
|
|
905
1450
|
*
|
|
906
|
-
* The
|
|
907
|
-
*
|
|
908
|
-
*
|
|
909
|
-
* silently — if you cannot say whether the last major broke the plugin
|
|
910
|
-
* interface, do not widen it.
|
|
1451
|
+
* The HTTP analogue of `WsConnection.onShutdown`, for routes that hold
|
|
1452
|
+
* a response open indefinitely (SSE): handlers flush a terminal frame and end
|
|
1453
|
+
* their response, or the drain would wait forever.
|
|
911
1454
|
*
|
|
912
|
-
*
|
|
913
|
-
*
|
|
1455
|
+
* Additive, not last-one-wins (unlike `onError`): a dropped registration is
|
|
1456
|
+
* a leaked stream. Optional — transports with no graceful phase may omit it,
|
|
1457
|
+
* and callers must tolerate undefined.
|
|
914
1458
|
*/
|
|
915
|
-
|
|
1459
|
+
onShutdown?(cb: (reason: string) => void): void;
|
|
916
1460
|
/**
|
|
917
|
-
*
|
|
918
|
-
*
|
|
919
|
-
* policy must allow. Useful for cross-cutting concerns (audit logging,
|
|
920
|
-
* rate limits, identity enrichment) that span multiple namespaces in the
|
|
921
|
-
* same plugin. The composed result is surfaced through
|
|
922
|
-
* `NamespaceInstallContext.pluginPolicy`.
|
|
1461
|
+
* Test-only: invoke the server's handler pipeline without opening a socket.
|
|
1462
|
+
* Networked implementations may leave this undefined.
|
|
923
1463
|
*/
|
|
924
|
-
|
|
1464
|
+
inject?(req: Partial<SubstrateRequest>): Promise<SubstrateResponse>;
|
|
925
1465
|
/**
|
|
926
|
-
*
|
|
927
|
-
*
|
|
928
|
-
*
|
|
1466
|
+
* Register a per-request observer for op throughput + latency. Optional —
|
|
1467
|
+
* transports without instrumentation may omit it. At most one observer; a
|
|
1468
|
+
* second call replaces the first. The transport invokes it only for the
|
|
1469
|
+
* `/substrate/v1/query` and `/substrate/v1/mutate` routes.
|
|
929
1470
|
*/
|
|
930
|
-
|
|
1471
|
+
observeRequests?(observer: RequestObserver): void;
|
|
1472
|
+
/** Optional: told when a query/mutate HTTP request starts (+1) and ends (-1), including when it throws. */
|
|
1473
|
+
observeInFlight?(fn: (op: RuntimeOp, delta: 1 | -1) => void): void;
|
|
1474
|
+
}
|
|
1475
|
+
//#endregion
|
|
1476
|
+
//#region ../../packages/substrate-types/src/plugin.d.ts
|
|
1477
|
+
/** Whether a registry entry is a top-level addressable type or a mutation. */
|
|
1478
|
+
type RegistryEntryKind = 'type' | 'mutation';
|
|
1479
|
+
/**
|
|
1480
|
+
* postWrite hook signature. Receives the written row and request context;
|
|
1481
|
+
* may perform side-effects (e.g. embedding, index updates). Returned promise
|
|
1482
|
+
* is awaited before the engine acks the write to the caller.
|
|
1483
|
+
*/
|
|
1484
|
+
type PostWriteHook = (row: Row, ctx: RequestContext) => Promise<void>;
|
|
1485
|
+
/**
|
|
1486
|
+
* Resolver signature stored in a `RegistryEntry`. Identical to the canonical
|
|
1487
|
+
* engine-facing `Resolver` in `./policy.ts`; redeclared inline here to keep
|
|
1488
|
+
* the registry surface self-describing for the types package. Importers that
|
|
1489
|
+
* want the canonical alias should import `Resolver` from this package.
|
|
1490
|
+
*/
|
|
1491
|
+
type RegistryEntryResolver = (ctx: RequestContext, args: ResolverArgs) => Promise<Row | Row[] | ReadResult | AsyncIterable<Row> | null> | AsyncIterable<Row>;
|
|
1492
|
+
/**
|
|
1493
|
+
* Set-wise resolver for a mutate array: one call for every uncached element,
|
|
1494
|
+
* in order, returning one entry per element. Throw `BatchElementError(i, cause)`
|
|
1495
|
+
* to refuse element `i`; any throw rolls back the whole array.
|
|
1496
|
+
*/
|
|
1497
|
+
type BatchResolver = (ctx: RequestContext, args: readonly ResolverArgs[]) => Promise<Array<Row | null>>;
|
|
1498
|
+
/** Input shape for `Registry.register` / `Registry.replace`. */
|
|
1499
|
+
interface RegistryEntryInput {
|
|
1500
|
+
resolver: RegistryEntryResolver;
|
|
1501
|
+
/** When present, a mutate array calls this once instead of `resolver` per element. */
|
|
1502
|
+
batch?: BatchResolver;
|
|
1503
|
+
policy?: Policy;
|
|
1504
|
+
fields?: Record<string, FieldDef>;
|
|
1505
|
+
kind?: RegistryEntryKind;
|
|
1506
|
+
params?: Record<string, FieldDef>;
|
|
1507
|
+
returns?: FieldDef;
|
|
1508
|
+
/** Natural order of a `kind: 'type'` entry; published on its `TypeSchema`. */
|
|
1509
|
+
orderedBy?: OrderedBy;
|
|
1510
|
+
/** Declared indexes of a `kind: 'type'` entry installed at runtime (a proposed type). */
|
|
1511
|
+
indexes?: IndexDecl[];
|
|
1512
|
+
/** A proposed type's size hint; `large` lowers the index advisor's row minimum. */
|
|
1513
|
+
expectedSize?: 'small' | 'large';
|
|
931
1514
|
/**
|
|
932
|
-
*
|
|
933
|
-
*
|
|
934
|
-
*
|
|
935
|
-
*
|
|
936
|
-
* they came up — late-loading plugins that depended on earlier ones get
|
|
937
|
-
* to release their handles first.
|
|
938
|
-
*
|
|
939
|
-
* Use for resources the OS won't reap on process exit:
|
|
940
|
-
* - subprocess children that should receive SIGTERM cleanly
|
|
941
|
-
* - long-lived `setInterval` timers (`.unref()` keeps them from
|
|
942
|
-
* blocking exit, but explicit teardown is still cleaner for tests)
|
|
943
|
-
* - WebSocket subscriptions / outbound connections that should close
|
|
944
|
-
* cooperatively rather than dropping mid-request
|
|
945
|
-
*
|
|
946
|
-
* Errors are caught + logged via the lifecycle metric sink under
|
|
947
|
-
* `plugin_on_stop_error` — one plugin's failed teardown does NOT abort
|
|
948
|
-
* other plugins' teardown. The engine + pg pool are still live during
|
|
949
|
-
* onStop calls, so plugins can do final writes (e.g. an audit row
|
|
950
|
-
* recording the shutdown). After all onStop hooks resolve, the server
|
|
951
|
-
* stops accepting connections and the substrate's `closeStore()` runs.
|
|
952
|
-
*
|
|
953
|
-
* Symmetric to `onStart`. Skipped (no-op) when omitted.
|
|
1515
|
+
* Semantic verb for autoCRUD-registered mutations. The engine
|
|
1516
|
+
* threads this into `RequestContext.verb` at dispatch so type-/plugin-level
|
|
1517
|
+
* policies can discriminate get/create/update/delete without entry-name
|
|
1518
|
+
* string matching. Omit for type entries and custom mutations.
|
|
954
1519
|
*/
|
|
955
|
-
|
|
1520
|
+
verb?: AutoCrudVerb;
|
|
956
1521
|
/**
|
|
957
|
-
*
|
|
958
|
-
*
|
|
959
|
-
* after the server's `start()` resolves.
|
|
1522
|
+
* The type a by-filter mutation (`updateMany<T>` / `deleteMany<T>`) writes.
|
|
1523
|
+
* The engine validates `params.where` against it as a query's `where`.
|
|
960
1524
|
*/
|
|
961
|
-
|
|
1525
|
+
filterTarget?: string;
|
|
1526
|
+
}
|
|
1527
|
+
/**
|
|
1528
|
+
* Stored shape returned by `Registry.get` and `Registry.all`. Mirrors the
|
|
1529
|
+
* concrete `RegistryEntry` in `@mnmal-ai/substrate-core` — the engine reads
|
|
1530
|
+
* `policy`, `kind`, `resolver`, `fields`, `params`, and `returns` off this
|
|
1531
|
+
* shape on every dispatch.
|
|
1532
|
+
*/
|
|
1533
|
+
interface RegistryEntry {
|
|
1534
|
+
resolver: RegistryEntryResolver;
|
|
1535
|
+
/** Mirrors `RegistryEntryInput.batch`. */
|
|
1536
|
+
batch?: BatchResolver;
|
|
1537
|
+
policy: Policy;
|
|
1538
|
+
fields: Record<string, FieldDef>;
|
|
1539
|
+
kind: RegistryEntryKind;
|
|
1540
|
+
/** Always present — `{}` for `kind: 'type'` entries where the concept doesn't apply. */
|
|
1541
|
+
params: Record<string, FieldDef>;
|
|
1542
|
+
/** Present only for `kind: 'mutation'` entries that declared a return shape. */
|
|
1543
|
+
returns?: FieldDef;
|
|
1544
|
+
/** Mirrors `RegistryEntryInput.orderedBy`. */
|
|
1545
|
+
orderedBy?: OrderedBy;
|
|
1546
|
+
/** Mirrors `RegistryEntryInput.indexes`. */
|
|
1547
|
+
indexes?: IndexDecl[];
|
|
1548
|
+
/** Mirrors `RegistryEntryInput.expectedSize`. */
|
|
1549
|
+
expectedSize?: 'small' | 'large';
|
|
1550
|
+
/** Mirrors `RegistryEntryInput.verb` — present when the registrant stamped one. */
|
|
1551
|
+
verb?: AutoCrudVerb;
|
|
1552
|
+
/** Mirrors `RegistryEntryInput.filterTarget`. */
|
|
1553
|
+
filterTarget?: string;
|
|
1554
|
+
}
|
|
1555
|
+
/**
|
|
1556
|
+
* Canonical per-namespace registry surface, implemented by the concrete
|
|
1557
|
+
* `Registry` class in `@mnmal-ai/substrate-core`.
|
|
1558
|
+
*/
|
|
1559
|
+
interface Registry {
|
|
1560
|
+
register(key: string | {
|
|
1561
|
+
readonly name: string;
|
|
1562
|
+
}, input: RegistryEntryInput): void;
|
|
1563
|
+
replace(key: string | {
|
|
1564
|
+
readonly name: string;
|
|
1565
|
+
}, input: RegistryEntryInput): void;
|
|
962
1566
|
/**
|
|
963
|
-
*
|
|
964
|
-
* `
|
|
965
|
-
*
|
|
966
|
-
*
|
|
967
|
-
* With auth on, HTTP routes require `read` for GET and `mutate` otherwise,
|
|
968
|
-
* granted in one of this plugin's `namespaces`; a plugin with no namespaces
|
|
969
|
-
* accepts the capability granted in any namespace.
|
|
1567
|
+
* Read back a registered entry. Returns undefined when the entry is absent.
|
|
1568
|
+
* The full `RegistryEntry` shape (resolver, policy, kind, fields, params,
|
|
1569
|
+
* returns) is exposed because the engine reads every field on dispatch.
|
|
970
1570
|
*/
|
|
971
|
-
|
|
1571
|
+
get(key: string | {
|
|
1572
|
+
readonly name: string;
|
|
1573
|
+
}): RegistryEntry | undefined;
|
|
1574
|
+
/** Presence check. Returns true iff `key` is registered. */
|
|
1575
|
+
has(key: string | {
|
|
1576
|
+
readonly name: string;
|
|
1577
|
+
}): boolean;
|
|
1578
|
+
/** Iterate every `[name, entry]` pair. Used by the schema publisher. */
|
|
1579
|
+
all(): IterableIterator<[string, RegistryEntry]>;
|
|
972
1580
|
/**
|
|
973
|
-
*
|
|
974
|
-
*
|
|
975
|
-
* `instructions.plugins.<name>` and enumerates the plugin's conventional
|
|
976
|
-
* `/substrate/v1/plugins/<name>/onboard` route under `instructions.pluginRoutes`. Use
|
|
977
|
-
* this to teach agents about the plugin's types, write flows, or any
|
|
978
|
-
* plugin-specific grammar a cold-start agent would otherwise have to
|
|
979
|
-
* discover per endpoint. The shape is free-form — the binary round-trips
|
|
980
|
-
* it verbatim.
|
|
1581
|
+
* Remove an entry. Optional: only a registry that can take back a live
|
|
1582
|
+
* apply (a schema proposal rolled back with its transaction) offers it.
|
|
981
1583
|
*/
|
|
982
|
-
|
|
1584
|
+
unregister?(key: string | {
|
|
1585
|
+
readonly name: string;
|
|
1586
|
+
}): void;
|
|
1587
|
+
/**
|
|
1588
|
+
* Monotonic mutation counter — incremented by every `register` / `replace` / `unregister`.
|
|
1589
|
+
* Lets a consumer cache anything derived from the registry (the published
|
|
1590
|
+
* schema, above all) and detect staleness from the data, without relying on
|
|
1591
|
+
* every registrant remembering to call `engine.invalidateSchemaCaches`.
|
|
1592
|
+
*
|
|
1593
|
+
* Optional so third-party `Registry` implementations remain valid; consumers
|
|
1594
|
+
* fall back to callback-driven invalidation when it is absent.
|
|
1595
|
+
*/
|
|
1596
|
+
readonly epoch?: number | undefined;
|
|
983
1597
|
}
|
|
984
1598
|
/**
|
|
985
|
-
*
|
|
986
|
-
*
|
|
987
|
-
*
|
|
1599
|
+
* Base class binding the `epoch` bookkeeping so an implementation cannot forget
|
|
1600
|
+
* it. Subclasses supply storage via `performRegister` / `performReplace` and
|
|
1601
|
+
* never implement `register` / `replace` themselves, so the counter is advanced
|
|
1602
|
+
* by construction rather than by discipline.
|
|
988
1603
|
*
|
|
989
|
-
*
|
|
990
|
-
*
|
|
1604
|
+
* A throw from `performRegister` leaves the epoch untouched, which is correct:
|
|
1605
|
+
* a rejected registration changed nothing.
|
|
1606
|
+
*
|
|
1607
|
+
* Decorators cannot extend this — they wrap an instance rather than subclass it
|
|
1608
|
+
* — so a wrapping registry must forward `epoch` from the wrapped instance. See
|
|
1609
|
+
* `substrate-compose`'s `_system` install for the worked example.
|
|
991
1610
|
*/
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
1611
|
+
declare abstract class RegistryBase implements Registry {
|
|
1612
|
+
#private;
|
|
1613
|
+
get epoch(): number;
|
|
1614
|
+
register(key: string | {
|
|
1615
|
+
readonly name: string;
|
|
1616
|
+
}, input: RegistryEntryInput): void;
|
|
1617
|
+
replace(key: string | {
|
|
1618
|
+
readonly name: string;
|
|
1619
|
+
}, input: RegistryEntryInput): void;
|
|
1620
|
+
unregister(key: string | {
|
|
1621
|
+
readonly name: string;
|
|
1622
|
+
}): void;
|
|
1623
|
+
/** Store a new entry. Throw to reject; the epoch will not advance. */
|
|
1624
|
+
protected abstract performRegister(key: string | {
|
|
1625
|
+
readonly name: string;
|
|
1626
|
+
}, input: RegistryEntryInput): void;
|
|
1627
|
+
/** Overwrite an existing entry. Throw to reject; the epoch will not advance. */
|
|
1628
|
+
protected abstract performReplace(key: string | {
|
|
1629
|
+
readonly name: string;
|
|
1630
|
+
}, input: RegistryEntryInput): void;
|
|
1631
|
+
/** Remove an entry. Not abstract, so existing subclasses stay valid; they refuse. */
|
|
1632
|
+
protected performUnregister(key: string | {
|
|
1633
|
+
readonly name: string;
|
|
1634
|
+
}): void;
|
|
1635
|
+
abstract get(key: string | {
|
|
1636
|
+
readonly name: string;
|
|
1637
|
+
}): RegistryEntry | undefined;
|
|
1638
|
+
abstract has(key: string | {
|
|
1639
|
+
readonly name: string;
|
|
1640
|
+
}): boolean;
|
|
1641
|
+
abstract all(): IterableIterator<[string, RegistryEntry]>;
|
|
1642
|
+
}
|
|
1643
|
+
/** See `EngineHandle.addDropParticipant`. */
|
|
1644
|
+
interface DropParticipant {
|
|
1645
|
+
/** Namespaces whose datasets `onDrop` writes, opened in the drop's transaction. */
|
|
1646
|
+
readonly namespaces: readonly string[];
|
|
1647
|
+
/** `datasetFor` returns the transaction-bound dataset of one of `namespaces`. */
|
|
1648
|
+
onDrop(ns: string, datasetFor: (ns: string) => Dataset): Promise<void>;
|
|
1649
|
+
}
|
|
1650
|
+
interface NamespaceInstallContext {
|
|
1651
|
+
registry: Registry;
|
|
1652
|
+
dataset: Dataset;
|
|
1653
|
+
edges: EdgesStore;
|
|
995
1654
|
/**
|
|
996
|
-
* Plugin
|
|
997
|
-
*
|
|
998
|
-
*
|
|
999
|
-
*
|
|
1000
|
-
*
|
|
1655
|
+
* Plugin-global policy composed from the owning plugin's `policies` array
|
|
1656
|
+
* (undefined when the plugin declares none). Namespace install
|
|
1657
|
+
* implementations SHOULD compose this with any namespace-scoped or per-type
|
|
1658
|
+
* policies via `and()` so plugin-level invariants apply across every
|
|
1659
|
+
* resolver the namespace contributes. `defineNamespace` in
|
|
1660
|
+
* `@mnmal-ai/substrate-sdk` does this automatically.
|
|
1001
1661
|
*/
|
|
1002
|
-
|
|
1662
|
+
pluginPolicy?: Policy;
|
|
1003
1663
|
/**
|
|
1004
|
-
*
|
|
1005
|
-
*
|
|
1006
|
-
*
|
|
1007
|
-
*
|
|
1664
|
+
* Substrate-plugin contributions to per-type postWrite chains. Map
|
|
1665
|
+
* `typeName → PostWriteHook[]`. Engine populates by walking each
|
|
1666
|
+
* composed substrate plugin's `contributePostWrites(namespace)` and
|
|
1667
|
+
* merging results. Hooks run AFTER the type's inline postWrite in
|
|
1668
|
+
* declaration order. Empty map / undefined = no contributions.
|
|
1008
1669
|
*/
|
|
1009
|
-
|
|
1670
|
+
postWriteContributions?: Record<string, PostWriteHook[]>;
|
|
1671
|
+
}
|
|
1672
|
+
/**
|
|
1673
|
+
* Read-side context passed to `NamespaceTypeDef.embed.source` when the
|
|
1674
|
+
* substrate composing the embedding (e.g. substrate-recall) has a dataset
|
|
1675
|
+
* resolver wired. Lets the source function pull related-entity context
|
|
1676
|
+
* via crossRefs (e.g. inline a linked Concept's name into the embedded
|
|
1677
|
+
* text so semantic recall surfaces relevant rows).
|
|
1678
|
+
*
|
|
1679
|
+
* Minimal by design — `read` is the only method, and it returns the
|
|
1680
|
+
* first matching row or `null`. Source functions that don't need
|
|
1681
|
+
* crossRef enrichment ignore the parameter.
|
|
1682
|
+
*/
|
|
1683
|
+
interface EmbedSourceContext {
|
|
1684
|
+
read: (namespace: string, type: string, params: {
|
|
1685
|
+
id: string;
|
|
1686
|
+
}) => Promise<Row | null>;
|
|
1687
|
+
}
|
|
1688
|
+
/**
|
|
1689
|
+
* A declared index over a type's scalar or crossRef fields, built by the
|
|
1690
|
+
* engine with the same expressions the filter compiler emits.
|
|
1691
|
+
*
|
|
1692
|
+
* - `fields`: key columns in order; `dir` defaults to `asc`. Both directions
|
|
1693
|
+
* sort NULLs last, as `orderBy` does.
|
|
1694
|
+
* - `unique`: refused at build time while duplicate live values exist.
|
|
1695
|
+
* - `where`: always ANDed with "not deleted". `'live'` adds nothing more; a
|
|
1696
|
+
* record adds equality to a boolean (or IS NULL for `null`) on the type's
|
|
1697
|
+
* own fields. Only those operands compile to literals, which a generic plan
|
|
1698
|
+
* needs to match the index predicate.
|
|
1699
|
+
* - `name`: the pg index name to own or adopt; generated when omitted. It may
|
|
1700
|
+
* not end in `__swap`, the reconciler's temporary suffix.
|
|
1701
|
+
*/
|
|
1702
|
+
interface IndexDecl {
|
|
1703
|
+
fields: Array<string | {
|
|
1704
|
+
field: string;
|
|
1705
|
+
dir: 'asc' | 'desc';
|
|
1706
|
+
}>;
|
|
1707
|
+
unique?: boolean;
|
|
1708
|
+
where?: 'live' | Record<string, boolean | null>;
|
|
1709
|
+
name?: string;
|
|
1710
|
+
}
|
|
1711
|
+
/**
|
|
1712
|
+
* Structural shape of a type definition, mirroring `TypeInput` from
|
|
1713
|
+
* @mnmal-ai/substrate-sdk (redeclared to avoid a substrate-types → substrate-sdk import
|
|
1714
|
+
* cycle). Substrate plugins read it structurally; slots not named here pass
|
|
1715
|
+
* through opaquely.
|
|
1716
|
+
*/
|
|
1717
|
+
interface NamespaceTypeDef {
|
|
1718
|
+
fields: Record<string, FieldDef>;
|
|
1719
|
+
postWrite?: (row: Row, ctx: RequestContext) => Promise<void>;
|
|
1720
|
+
embed?: {
|
|
1721
|
+
/**
|
|
1722
|
+
* Produce the source text fed to the embedder for this row, or `null` /
|
|
1723
|
+
* `undefined` to declare the row un-indexable.
|
|
1724
|
+
*
|
|
1725
|
+
* The null sentinel is a RETRIEVAL POLICY, not an absence of text: it
|
|
1726
|
+
* means "this row exists and must be referenceable, but must never enter
|
|
1727
|
+
* the recall candidate set". The composing substrate both declines to
|
|
1728
|
+
* index the row AND removes any embedding it already has, so a row that
|
|
1729
|
+
* flips to un-indexable after being written stops being recallable
|
|
1730
|
+
* without being deleted.
|
|
1731
|
+
*
|
|
1732
|
+
* `''` is NOT the sentinel — an empty string embeds normally. Returning
|
|
1733
|
+
* `''` to mean "skip" indexes every such row at the same point in the
|
|
1734
|
+
* vector space.
|
|
1735
|
+
*
|
|
1736
|
+
* `ctx` is optional — when the composing substrate has a dataset
|
|
1737
|
+
* resolver wired, source functions may call `ctx.read(ns, type,
|
|
1738
|
+
* { id })` to inline related-entity context. When `ctx` is undefined,
|
|
1739
|
+
* the source must work from `row` alone. Async return is supported
|
|
1740
|
+
* so source functions can await crossRef reads.
|
|
1741
|
+
*/
|
|
1742
|
+
source: (row: Row, ctx?: EmbedSourceContext) => string | null | undefined | Promise<string | null | undefined>;
|
|
1743
|
+
};
|
|
1010
1744
|
/**
|
|
1011
|
-
*
|
|
1012
|
-
*
|
|
1013
|
-
*
|
|
1745
|
+
* Produce the text fed to the LEXICAL (keyword) index for this row, with the
|
|
1746
|
+
* same `null` / `undefined` un-indexable sentinel as `embed.source`.
|
|
1747
|
+
*
|
|
1748
|
+
* A sibling of `embed` rather than a flag on it, because the two indexes
|
|
1749
|
+
* want different text: `embed.source` conventionally takes a short handle
|
|
1750
|
+
* (`synopsis || body`), which drops proper nouns a keyword index needs.
|
|
1751
|
+
* `lexical.source` is where the long form goes.
|
|
1752
|
+
*
|
|
1753
|
+
* A type may declare either, both, or neither. Both is the expected shape for
|
|
1754
|
+
* a store whose handle is shorter than its content.
|
|
1014
1755
|
*/
|
|
1015
|
-
|
|
1756
|
+
lexical?: {
|
|
1757
|
+
source: (row: Row) => string | null | undefined | Promise<string | null | undefined>;
|
|
1758
|
+
};
|
|
1759
|
+
/** Composite and unique indexes the engine builds for this type. See {@link IndexDecl}. */
|
|
1760
|
+
indexes?: IndexDecl[];
|
|
1761
|
+
/** The type's natural order, the default read order. See {@link OrderedBy}. */
|
|
1762
|
+
orderedBy?: OrderedBy;
|
|
1763
|
+
/** See the SDK's `TypeInput.ordering`. */
|
|
1764
|
+
ordering?: 'visible';
|
|
1765
|
+
/** Size hint: `large` lowers the index advisor's row minimum for this type. */
|
|
1766
|
+
expectedSize?: 'small' | 'large';
|
|
1767
|
+
[key: string]: unknown;
|
|
1768
|
+
}
|
|
1769
|
+
interface NamespaceDefinition {
|
|
1770
|
+
namespace: string;
|
|
1016
1771
|
/**
|
|
1017
|
-
*
|
|
1018
|
-
*
|
|
1019
|
-
*
|
|
1772
|
+
* Type definitions registered under this namespace, keyed by type name.
|
|
1773
|
+
* Read-only metadata exposed for substrate plugins that need to walk
|
|
1774
|
+
* the type surface at coordinator-namespace install time (e.g.
|
|
1775
|
+
* substrate-recall reads `types[T].embed?.source` to contribute embedding
|
|
1776
|
+
* postWrite hooks). Populated by `defineNamespace`; absent on hand-crafted
|
|
1777
|
+
* `NamespaceDefinition` objects that bypass the SDK helper.
|
|
1020
1778
|
*/
|
|
1021
|
-
|
|
1779
|
+
types?: Readonly<Record<string, NamespaceTypeDef>>;
|
|
1022
1780
|
/**
|
|
1023
|
-
*
|
|
1024
|
-
*
|
|
1781
|
+
* Opaque per-consumer metadata, keyed by consumer (e.g. `nl`). Core never
|
|
1782
|
+
* interprets it; it is passed through to the namespace schema unchanged.
|
|
1025
1783
|
*/
|
|
1026
|
-
|
|
1784
|
+
annotations?: Readonly<Record<string, unknown>>;
|
|
1027
1785
|
/**
|
|
1028
|
-
*
|
|
1029
|
-
*
|
|
1786
|
+
* @deprecated Ignored. Every declared scalar is a column of its type's
|
|
1787
|
+
* table, so there is nothing left to promote. It was the old layouts' body
|
|
1788
|
+
* keys mirrored into dedicated `rows` columns; it still type-checks, so a
|
|
1789
|
+
* plugin that sets it boots unchanged.
|
|
1030
1790
|
*/
|
|
1031
|
-
|
|
1791
|
+
promotedColumns?: Readonly<Record<string, {
|
|
1792
|
+
column: string;
|
|
1793
|
+
kind: 'boolean' | 'text';
|
|
1794
|
+
}>>;
|
|
1032
1795
|
/**
|
|
1033
|
-
*
|
|
1034
|
-
*
|
|
1035
|
-
*
|
|
1036
|
-
* the
|
|
1796
|
+
* Install types + mutations + policies into the registry. Invoked once at
|
|
1797
|
+
* registration time, BEFORE the engine is constructed. The plugin owns the
|
|
1798
|
+
* dataset handle it uses for resolver closures; wiring datasets into the
|
|
1799
|
+
* engine's `DatasetRegistry` is the app composition root's job.
|
|
1037
1800
|
*/
|
|
1038
|
-
|
|
1801
|
+
install(ctx: NamespaceInstallContext): void | Promise<void>;
|
|
1802
|
+
}
|
|
1803
|
+
interface PluginLifecycleContext {
|
|
1039
1804
|
/**
|
|
1040
|
-
*
|
|
1041
|
-
*
|
|
1042
|
-
*
|
|
1043
|
-
*
|
|
1805
|
+
* Tagged-union discriminant. Differentiates this context from
|
|
1806
|
+
* the structurally-similar `KernelLifecycleContext` so a coordinator's
|
|
1807
|
+
* `onStart` handler is type-incompatible with a substrate's
|
|
1808
|
+
* `onKernelReady` handler — the composition root sets this, and plugins
|
|
1809
|
+
* can also branch on it at runtime if a single helper handles both
|
|
1810
|
+
* lifecycle stages.
|
|
1044
1811
|
*/
|
|
1045
|
-
|
|
1812
|
+
readonly lifecycle: 'coordinator';
|
|
1046
1813
|
/**
|
|
1047
|
-
*
|
|
1048
|
-
*
|
|
1814
|
+
* Structured metric/log sink — the hosting binary picks the concrete surface
|
|
1815
|
+
* (stdout JSON, Prometheus counter, OpenTelemetry span, …). Plugins MUST NOT
|
|
1816
|
+
* assume the sink is synchronous or observable; the contract is fire-and-
|
|
1817
|
+
* forget per call.
|
|
1049
1818
|
*/
|
|
1050
|
-
|
|
1819
|
+
metric(name: string, payload?: unknown): void;
|
|
1051
1820
|
/**
|
|
1052
|
-
*
|
|
1053
|
-
*
|
|
1054
|
-
*
|
|
1055
|
-
*
|
|
1056
|
-
*
|
|
1057
|
-
* inline hook in chain order.
|
|
1058
|
-
*
|
|
1059
|
-
* Use this to inspect `namespace.types[T].embed` and emit embedding
|
|
1060
|
-
* hooks per type without coupling the binary to plugin internals.
|
|
1061
|
-
*
|
|
1062
|
-
* Returns: a record mapping type names to PostWriteHook contributions.
|
|
1063
|
-
* Type names not in the record receive no contribution.
|
|
1821
|
+
* Engine handle threaded into `onStart` so plugins that mutate their
|
|
1822
|
+
* registry post-construction (e.g. substrate-proposals' applyType /
|
|
1823
|
+
* applyField paths) can wire `engine.invalidateSchemaCaches(ns)` into
|
|
1824
|
+
* their replace flow. Engine construction completes before `onStart`
|
|
1825
|
+
* fires, so the handle is always live here.
|
|
1064
1826
|
*/
|
|
1065
|
-
|
|
1066
|
-
}
|
|
1067
|
-
/** Single migration unit. */
|
|
1068
|
-
interface KernelMigration {
|
|
1069
|
-
/** Unique id within the plugin. Stored in migrations tracking table. */
|
|
1070
|
-
id: string;
|
|
1071
|
-
/** Apply migration. Called only when this migration's id is absent from the migrations table. */
|
|
1072
|
-
apply(ctx: KernelMigrationContext): Promise<void>;
|
|
1073
|
-
/** Inverse — drops what apply created. */
|
|
1074
|
-
rollback?(ctx: KernelMigrationContext): Promise<void>;
|
|
1827
|
+
engine: EngineHandle;
|
|
1075
1828
|
}
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1829
|
+
/**
|
|
1830
|
+
* Engine-facing input shape for `query` / `mutate` / `subscribe` / `stream`.
|
|
1831
|
+
* Declared here (rather than in substrate-core) so plugin surfaces can reference
|
|
1832
|
+
* the engine's call shape as a type without importing the engine package —
|
|
1833
|
+
* substrate-types stays zero-runtime.
|
|
1834
|
+
*/
|
|
1835
|
+
interface FrameEntry {
|
|
1836
|
+
params?: Record<string, unknown>;
|
|
1837
|
+
fields?: Record<string, unknown>;
|
|
1082
1838
|
/**
|
|
1083
|
-
*
|
|
1084
|
-
*
|
|
1085
|
-
*
|
|
1086
|
-
* key column (`namespace`, `type`), so such DDL on `rows` must branch on this.
|
|
1839
|
+
* §5.13 dedup key. Present on a mutate frame entry opts the whole frame
|
|
1840
|
+
* into the engine's idempotency store; a repeat call with the same key
|
|
1841
|
+
* inside the TTL returns the cached envelope verbatim.
|
|
1087
1842
|
*/
|
|
1088
|
-
|
|
1089
|
-
metric(name: string, payload?: unknown): void;
|
|
1843
|
+
idempotencyKey?: string;
|
|
1090
1844
|
}
|
|
1091
1845
|
/**
|
|
1092
|
-
*
|
|
1093
|
-
*
|
|
1094
|
-
* The operator's name is the Record key it's registered under in
|
|
1095
|
-
* `KernelPlugin.filterOperators`.
|
|
1846
|
+
* Qualified frame (§4.7). Keys are `<ns>/<name>`. `<name>` is the type entry
|
|
1847
|
+
* name for query, or the mutation name for mutate.
|
|
1096
1848
|
*
|
|
1097
|
-
*
|
|
1098
|
-
*
|
|
1099
|
-
*
|
|
1100
|
-
*
|
|
1101
|
-
*
|
|
1102
|
-
*
|
|
1849
|
+
* Batched mutate (§5.13): a mutate op-key MAY carry an array of `FrameEntry`
|
|
1850
|
+
* values. All frames under one op-key run serially inside the SAME
|
|
1851
|
+
* transaction — all-or-nothing per op-key, committed independently of other
|
|
1852
|
+
* op-keys. Single-frame op-keys share one transaction when they share a
|
|
1853
|
+
* substrate and are refused (`cross_tx_scope_refused`) when they do not.
|
|
1854
|
+
* Query / subscribe / stream op-keys reject array values.
|
|
1103
1855
|
*/
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
} | {
|
|
1109
|
-
ok: false;
|
|
1110
|
-
reason: string;
|
|
1111
|
-
};
|
|
1112
|
-
execute(value: unknown, context: unknown): Promise<unknown>;
|
|
1856
|
+
type QualifiedFrame = Record<string, FrameEntry | Array<FrameEntry>>;
|
|
1857
|
+
interface EngineInput {
|
|
1858
|
+
frame: QualifiedFrame;
|
|
1859
|
+
ctx: Partial<RequestContext>;
|
|
1113
1860
|
/**
|
|
1114
|
-
*
|
|
1115
|
-
*
|
|
1116
|
-
*
|
|
1861
|
+
* §5.13 cancellation. Threaded into each resolver via `args.signal` so
|
|
1862
|
+
* resolvers observe cancel by polling `signal.aborted` or registering an
|
|
1863
|
+
* `abort` listener.
|
|
1117
1864
|
*/
|
|
1118
|
-
|
|
1865
|
+
signal?: AbortSignal;
|
|
1866
|
+
/**
|
|
1867
|
+
* Page bounds for list reads, set by a transport serving remote callers:
|
|
1868
|
+
* a type read with no `limit` gets `defaultLimit`, one above `maxLimit` is
|
|
1869
|
+
* refused. Absent for in-process callers, which read what they ask for.
|
|
1870
|
+
*/
|
|
1871
|
+
pageLimits?: {
|
|
1872
|
+
readonly defaultLimit: number;
|
|
1873
|
+
readonly maxLimit: number;
|
|
1874
|
+
};
|
|
1119
1875
|
}
|
|
1120
1876
|
/**
|
|
1121
|
-
*
|
|
1122
|
-
*
|
|
1123
|
-
* work unchanged. The resolver receives the standard (ctx, args) pair; the
|
|
1124
|
-
* engine leaves `args.dataset` undefined for virtual namespaces — resolvers
|
|
1125
|
-
* compute from `params`/`fields` and MUST NOT reach for a dataset handle.
|
|
1877
|
+
* Per-namespace engine configuration. substrate-core imports this type rather
|
|
1878
|
+
* than redeclaring it.
|
|
1126
1879
|
*/
|
|
1127
|
-
interface
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1880
|
+
interface NamespaceConfig {
|
|
1881
|
+
registry: Registry;
|
|
1882
|
+
/**
|
|
1883
|
+
* Marks a substrate-contributed namespace. Virtual namespaces
|
|
1884
|
+
* have NO dataset: the engine skips the dataset-presence check on
|
|
1885
|
+
* dispatch and leaves `args.dataset` undefined — resolvers compute from
|
|
1886
|
+
* `params`/`fields` and MUST NOT reach for a dataset handle. They are
|
|
1887
|
+
* structurally incapable of autoCRUD/storage — coordinators own data,
|
|
1888
|
+
* substrate surfaces own computation. Subscribe refuses these namespaces
|
|
1889
|
+
* with `subscription_unsupported_frame`.
|
|
1890
|
+
*/
|
|
1891
|
+
virtual?: boolean;
|
|
1892
|
+
/** From `NamespaceDefinition.annotations`; surfaced on the schema, never hashed. */
|
|
1893
|
+
annotations?: Readonly<Record<string, unknown>>;
|
|
1136
1894
|
}
|
|
1137
1895
|
/**
|
|
1138
|
-
*
|
|
1139
|
-
*
|
|
1140
|
-
*
|
|
1896
|
+
* What a coordinator's `onCommittedWrites` hook is told: one `(namespace, type,
|
|
1897
|
+
* operation)` group of one committed transaction. `ids` keep the order the
|
|
1898
|
+
* writes were emitted in. `actor` is who the request was attributed to, or
|
|
1899
|
+
* null for a request with no recognisable identity.
|
|
1141
1900
|
*/
|
|
1142
|
-
interface
|
|
1901
|
+
interface CommittedWriteBatch {
|
|
1143
1902
|
namespace: string;
|
|
1144
|
-
|
|
1145
|
-
|
|
1903
|
+
type: string;
|
|
1904
|
+
operation: 'create' | 'update' | 'delete';
|
|
1905
|
+
actor: ActorIdentity | null;
|
|
1906
|
+
ids: readonly Id[];
|
|
1146
1907
|
}
|
|
1147
|
-
/**
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1908
|
+
/**
|
|
1909
|
+
* Never awaited by the mutate, so keep its synchronous part cheap. A throw or a
|
|
1910
|
+
* rejection is recorded as a `/health` warning (plugin name and time, not the
|
|
1911
|
+
* message) and does not touch the write.
|
|
1912
|
+
*/
|
|
1913
|
+
type CommittedWritesHook = (batch: CommittedWriteBatch) => void | Promise<void>;
|
|
1914
|
+
/**
|
|
1915
|
+
* Narrow engine handle threaded into scheduled-task / plugin-route contexts.
|
|
1916
|
+
* The concrete `Engine` class in `@mnmal-ai/substrate-core` satisfies this
|
|
1917
|
+
* structurally; plugin code binds against this handle without importing the
|
|
1918
|
+
* engine package.
|
|
1919
|
+
*/
|
|
1920
|
+
interface EngineHandle {
|
|
1921
|
+
query(input: EngineInput): Promise<PackEnvelope>;
|
|
1922
|
+
mutate(input: EngineInput): Promise<PackEnvelope>;
|
|
1152
1923
|
/**
|
|
1153
|
-
*
|
|
1154
|
-
*
|
|
1155
|
-
*
|
|
1924
|
+
* Announce writes that were committed outside `mutate`: they reach
|
|
1925
|
+
* subscribers, then every coordinator's `onCommittedWrites`, as a commit
|
|
1926
|
+
* through `mutate` would. This is not a transaction and checks nothing: the
|
|
1927
|
+
* caller guarantees `events` are already committed, since an announced write
|
|
1928
|
+
* that rolls back cannot be taken back.
|
|
1929
|
+
*/
|
|
1930
|
+
announceWrites(events: readonly WriteEvent[], actor: ActorIdentity | null): Promise<void>;
|
|
1931
|
+
/**
|
|
1932
|
+
* Evaluate the read policy for a type entry without dispatching it.
|
|
1933
|
+
* Out-of-band read surfaces (kernel routes returning row data
|
|
1934
|
+
* outside frame dispatch — e.g. /substrate/v1/recall) call this so the same
|
|
1935
|
+
* composed policies that gate `query` gate them too. Fails closed on
|
|
1936
|
+
* unknown namespace/type and tombstoned namespaces.
|
|
1937
|
+
*/
|
|
1938
|
+
evaluateReadPolicy(ns: string, type: string, identity: Identity | null, probe?: PolicyProbeContext): PolicyDecision;
|
|
1939
|
+
/**
|
|
1940
|
+
* Invalidate cached schema outputs after an out-of-band registry mutation
|
|
1941
|
+
* (e.g. `applyTypeProposal` / `applyFieldProposal` calling
|
|
1942
|
+
* `Registry.replace`). Without this hook, `federatedSchema()` and
|
|
1943
|
+
* `schemaFor(ns)` keep returning pre-mutation views. Optional `ns` argument also drops the per-namespace `schemaFor` cache;
|
|
1944
|
+
* omit to invalidate only the federated outputs.
|
|
1945
|
+
*/
|
|
1946
|
+
invalidateSchemaCaches(ns?: string): void;
|
|
1947
|
+
/**
|
|
1948
|
+
* Register a new namespace at runtime. Throws on collision or on a
|
|
1949
|
+
* tombstoned name. Used by substrate-proposals' propose_namespace verb to provision
|
|
1950
|
+
* per-user / per-tenant namespaces without binary restart. Caller (typically
|
|
1951
|
+
* the resolver) is responsible for FPP semantics; this method is the
|
|
1952
|
+
* mechanical primitive.
|
|
1953
|
+
*/
|
|
1954
|
+
addNamespace(ns: string, config: NamespaceConfig): void;
|
|
1955
|
+
/**
|
|
1956
|
+
* Mark a namespace as tombstoned. After this call:
|
|
1957
|
+
* - schemaFor(ns) throws `unknown namespace`
|
|
1958
|
+
* - federatedSchema() omits the ns
|
|
1959
|
+
* - query / mutate / subscribe against the ns return a per-key
|
|
1960
|
+
* `namespace_tombstoned` error
|
|
1961
|
+
* - existing live subscriptions on the ns are closed with a
|
|
1962
|
+
* `namespace_tombstoned` error frame
|
|
1156
1963
|
*
|
|
1157
|
-
*
|
|
1158
|
-
*
|
|
1159
|
-
*
|
|
1964
|
+
* Idempotent. The underlying NamespaceConfig stays in `#namespaces` for
|
|
1965
|
+
* concurrency safety (in-flight ops keep their references) — full physical
|
|
1966
|
+
* reclaim happens at engine restart, gated by whatever persistence layer
|
|
1967
|
+
* the host uses to decide which namespaces to re-install at boot. Tombstone
|
|
1968
|
+
* state itself is in-memory; restart wipes it.
|
|
1160
1969
|
*/
|
|
1161
|
-
|
|
1162
|
-
}
|
|
1163
|
-
/** Top-level MCP tool registration. */
|
|
1164
|
-
interface McpToolRegistration {
|
|
1165
|
-
name: string;
|
|
1166
|
-
description: string;
|
|
1167
|
-
inputSchema: unknown;
|
|
1168
|
-
handler(input: unknown): Promise<unknown>;
|
|
1169
|
-
}
|
|
1170
|
-
interface KernelLifecycleContext {
|
|
1970
|
+
tombstoneNamespace(ns: string): void;
|
|
1171
1971
|
/**
|
|
1172
|
-
*
|
|
1173
|
-
*
|
|
1174
|
-
*
|
|
1972
|
+
* Be told, after the fact, each time a namespace is tombstoned (a drop), so
|
|
1973
|
+
* a plugin that installed it can retire what it owns. A listener's throw is
|
|
1974
|
+
* reported as a metric and does not reach the dropper. Returns a disposer.
|
|
1175
1975
|
*/
|
|
1176
|
-
|
|
1976
|
+
onNamespaceTombstoned(listener: (ns: string) => void): () => void;
|
|
1177
1977
|
/**
|
|
1178
|
-
*
|
|
1179
|
-
*
|
|
1180
|
-
*
|
|
1181
|
-
*
|
|
1182
|
-
* For convergent, run-every-boot reconciliation: a migration runs only once
|
|
1183
|
-
* per `id`, so it cannot re-scope objects it already created.
|
|
1978
|
+
* Take part in every namespace drop's transaction: the drop route opens
|
|
1979
|
+
* `participant.namespaces` in its transaction too and runs `onDrop` after
|
|
1980
|
+
* the rows are gone and before it commits, so a throw rolls the drop back.
|
|
1981
|
+
* Returns a disposer.
|
|
1184
1982
|
*/
|
|
1185
|
-
|
|
1983
|
+
addDropParticipant(participant: DropParticipant): () => void;
|
|
1984
|
+
/** The participants `addDropParticipant` registered, for the drop route. */
|
|
1985
|
+
dropParticipants(): readonly DropParticipant[];
|
|
1186
1986
|
/**
|
|
1187
|
-
*
|
|
1188
|
-
*
|
|
1189
|
-
*
|
|
1190
|
-
*
|
|
1191
|
-
* engine has not yet registered them.
|
|
1192
|
-
*
|
|
1193
|
-
* Read these rather than adding a namespace knob to substrate config, which
|
|
1194
|
-
* could silently disagree with what the coordinator uses.
|
|
1987
|
+
* Take a namespace off the engine and free its name for `addNamespace`.
|
|
1988
|
+
* Subscriptions on it close, its schema disappears, new ops answer
|
|
1989
|
+
* `unknown_namespace`; in-flight ops keep their resolved config. Undoes a
|
|
1990
|
+
* runtime add, e.g. a rolled-back propose_namespace. Idempotent.
|
|
1195
1991
|
*/
|
|
1196
|
-
|
|
1992
|
+
removeNamespace(ns: string): void;
|
|
1993
|
+
/** Whether `ns` is on the engine, and if so whether it is still served. */
|
|
1994
|
+
namespaceState(ns: string): 'absent' | 'live' | 'tombstoned';
|
|
1197
1995
|
/**
|
|
1198
|
-
*
|
|
1199
|
-
*
|
|
1200
|
-
*
|
|
1201
|
-
* The two absent cases differ and consumers must branch on them:
|
|
1202
|
-
* - `undefined` — this host does not supply attribution (e.g. an older
|
|
1203
|
-
* binary); do not treat it as an empty list
|
|
1204
|
-
* - `[]` — attribution supplied, and there are no coordinators
|
|
1205
|
-
*
|
|
1206
|
-
* Filtering on `plugin === 'some-name'` makes the coordinator's `name` a
|
|
1207
|
-
* contract term: hold it in one constant shared with the coordinator and pin
|
|
1208
|
-
* it with a test, or a rename makes the filter silently match nothing.
|
|
1996
|
+
* Construct a fresh empty Registry that the engine can accept via
|
|
1997
|
+
* `addNamespace`. Plugins call this to provision new namespaces at runtime
|
|
1998
|
+
* without taking a runtime dep on the concrete Registry class in substrate-core.
|
|
1209
1999
|
*/
|
|
1210
|
-
|
|
1211
|
-
plugin: string;
|
|
1212
|
-
namespace: string;
|
|
1213
|
-
}[];
|
|
2000
|
+
createRegistry(): Registry;
|
|
1214
2001
|
/**
|
|
1215
|
-
*
|
|
1216
|
-
*
|
|
1217
|
-
* `
|
|
1218
|
-
*
|
|
2002
|
+
* Look up the host-registered dataset for a namespace, or `undefined` if the
|
|
2003
|
+
* host has not provisioned one. Thin pass-through to the engine's
|
|
2004
|
+
* `DatasetRegistry.get`, surfaced on the handle so plugins running on
|
|
2005
|
+
* dynamically-added namespaces can resolve datasets without the host having
|
|
2006
|
+
* to plumb a `datasetFor` lookup through plugin config.
|
|
2007
|
+
*
|
|
2008
|
+
* Substrate selection remains the host's responsibility — this method only
|
|
2009
|
+
* exposes the lookup. Plugins that hot-add namespaces (substrate-proposals'
|
|
2010
|
+
* `propose_namespace`) MUST require the host to register the dataset before
|
|
2011
|
+
* the call; this method returns `undefined` for unregistered namespaces.
|
|
1219
2012
|
*/
|
|
1220
|
-
|
|
1221
|
-
metric(name: string, payload?: unknown): void;
|
|
1222
|
-
}
|
|
1223
|
-
//#endregion
|
|
1224
|
-
//#region ../../packages/substrate-types/src/runtime-metrics.d.ts
|
|
1225
|
-
/** Per-key resolver latency and error counts, as served by GET /substrate/v1/metrics. */
|
|
1226
|
-
interface ResolverStat {
|
|
1227
|
-
kind: 'query' | 'mutate';
|
|
1228
|
-
calls: number;
|
|
1229
|
-
errors: number;
|
|
1230
|
-
p50Ms: number;
|
|
1231
|
-
p99Ms: number;
|
|
1232
|
-
maxMs: number;
|
|
1233
|
-
lastAt: string;
|
|
1234
|
-
}
|
|
1235
|
-
interface ProcessStat {
|
|
1236
|
-
rssMB: number;
|
|
1237
|
-
heapUsedMB: number;
|
|
1238
|
-
cpuUserMs: number;
|
|
1239
|
-
cpuSystemMs: number;
|
|
1240
|
-
eventLoopLagP99Ms: number;
|
|
1241
|
-
inFlight: number;
|
|
1242
|
-
}
|
|
1243
|
-
interface SlowRequest {
|
|
1244
|
-
key: string;
|
|
1245
|
-
kind: 'query' | 'mutate';
|
|
1246
|
-
durationMs: number;
|
|
1247
|
-
at: string;
|
|
1248
|
-
}
|
|
1249
|
-
interface RuntimeErrorEntry {
|
|
1250
|
-
at: string;
|
|
1251
|
-
op: 'query' | 'mutate';
|
|
1252
|
-
key: string;
|
|
1253
|
-
code: string;
|
|
1254
|
-
message: string;
|
|
1255
|
-
/** The verified identity's id, or `'anonymous'`. */
|
|
1256
|
-
caller?: string;
|
|
1257
|
-
/** Present when consecutive identical `(unknown)` failures were merged into this entry. */
|
|
1258
|
-
count?: number;
|
|
1259
|
-
}
|
|
1260
|
-
interface RuntimeErrors {
|
|
1261
|
-
since: string;
|
|
1262
|
-
errors: RuntimeErrorEntry[];
|
|
1263
|
-
}
|
|
1264
|
-
interface ResolveObservation {
|
|
1265
|
-
key: string;
|
|
1266
|
-
kind: 'query' | 'mutate';
|
|
1267
|
-
durationMs: number;
|
|
1268
|
-
ok: boolean;
|
|
1269
|
-
code?: string;
|
|
1270
|
-
message?: string;
|
|
1271
|
-
/** The verified identity's id; absent for an anonymous caller. */
|
|
1272
|
-
caller?: string;
|
|
1273
|
-
}
|
|
1274
|
-
/**
|
|
1275
|
-
* One type's table and index statistics, for the index advisor. Counters are
|
|
1276
|
-
* cumulative since the server's statistics were last reset. Row counts are
|
|
1277
|
-
* estimates. A type ABSENT from a `typeStats()` result is unknown, not empty:
|
|
1278
|
-
* never read its absence as 0 rows (a sampled store can miss a small type).
|
|
1279
|
-
*/
|
|
1280
|
-
interface TypeStats {
|
|
1281
|
-
namespace: string;
|
|
1282
|
-
type: string;
|
|
1283
|
-
liveRows: number;
|
|
1284
|
-
insertsTotal: number;
|
|
1285
|
-
updatesTotal: number;
|
|
1286
|
-
deletesTotal: number;
|
|
1287
|
-
indexes: Array<{
|
|
1288
|
-
name: string;
|
|
1289
|
-
scans: number;
|
|
1290
|
-
/** The last scan (ISO), or null when none since the statistics were last reset. */
|
|
1291
|
-
lastScanAt: string | null;
|
|
1292
|
-
sizeBytes: number;
|
|
1293
|
-
unique: boolean;
|
|
1294
|
-
/** Built or adopted by the engine's index reconciler for this type. */
|
|
1295
|
-
engineOwned: boolean;
|
|
1296
|
-
}>;
|
|
1297
|
-
}
|
|
1298
|
-
/** What GET /substrate/v1/metrics returns. The new fields are optional so an older server still type-checks. */
|
|
1299
|
-
interface RuntimeMetrics {
|
|
1300
|
-
since: string;
|
|
1301
|
-
requests: {
|
|
1302
|
-
query: {
|
|
1303
|
-
total: number;
|
|
1304
|
-
ok: number;
|
|
1305
|
-
error: number;
|
|
1306
|
-
durationMsSum: number;
|
|
1307
|
-
durationMsMax: number;
|
|
1308
|
-
};
|
|
1309
|
-
mutate: {
|
|
1310
|
-
total: number;
|
|
1311
|
-
ok: number;
|
|
1312
|
-
error: number;
|
|
1313
|
-
durationMsSum: number;
|
|
1314
|
-
durationMsMax: number;
|
|
1315
|
-
};
|
|
1316
|
-
};
|
|
1317
|
-
subscriptions: {
|
|
1318
|
-
active: number;
|
|
1319
|
-
maxQueueDepth?: number;
|
|
1320
|
-
entries?: {
|
|
1321
|
-
id: string;
|
|
1322
|
-
ns: string;
|
|
1323
|
-
type: string;
|
|
1324
|
-
queueLength: number;
|
|
1325
|
-
}[];
|
|
1326
|
-
};
|
|
1327
|
-
events: Record<string, number>;
|
|
1328
|
-
resolvers?: Record<string, ResolverStat>;
|
|
1329
|
-
process?: ProcessStat;
|
|
1330
|
-
slowest?: SlowRequest[];
|
|
2013
|
+
datasetFor(namespace: string): Dataset | undefined;
|
|
1331
2014
|
}
|
|
1332
|
-
//#endregion
|
|
1333
|
-
//#region ../../packages/substrate-types/src/dataset.d.ts
|
|
1334
2015
|
/**
|
|
1335
|
-
*
|
|
1336
|
-
*
|
|
1337
|
-
*
|
|
1338
|
-
*
|
|
2016
|
+
* Engine surface needed by substrate-pack-aware route helpers — extends the
|
|
2017
|
+
* dispatch handle with the two methods compose's `serializeEnvelope` /
|
|
2018
|
+
* `mutateRoute` need to drive positional encoding. The concrete
|
|
2019
|
+
* `Engine` class satisfies this structurally; tests + alt
|
|
2020
|
+
* implementations can satisfy it without depending on the engine package.
|
|
1339
2021
|
*/
|
|
1340
|
-
interface
|
|
1341
|
-
|
|
1342
|
-
|
|
2022
|
+
interface EncodeContext extends EngineHandle {
|
|
2023
|
+
/** Federated schema map (per-namespace Schema) for substrate-pack encoding. */
|
|
2024
|
+
federatedSchema(): Record<string, Schema>;
|
|
2025
|
+
/**
|
|
2026
|
+
* Look up a namespace's mutation-return registry view. Returns undefined
|
|
2027
|
+
* when the namespace isn't registered. The mutate route uses this to
|
|
2028
|
+
* resolve each frame key's `returns` FieldDef for positional encoding.
|
|
2029
|
+
*/
|
|
2030
|
+
registryFor(namespace: string): {
|
|
2031
|
+
get(name: string): {
|
|
2032
|
+
returns?: FieldDef;
|
|
2033
|
+
} | undefined;
|
|
2034
|
+
} | undefined;
|
|
1343
2035
|
}
|
|
1344
2036
|
/**
|
|
1345
|
-
*
|
|
1346
|
-
* used in practice (e.g. `{ age: { gt: 18 } }`), but the shape admits several
|
|
1347
|
-
* operators so `{ age: { gte: 10, lt: 100 } }` can express a half-open range
|
|
1348
|
-
* without the caller reaching for an explicit `AND`. Semantics: the leaf
|
|
1349
|
-
* matches when EVERY specified operator matches (implicit AND within a leaf).
|
|
1350
|
-
*
|
|
1351
|
-
* `eq`/`neq` accept `null` to address IS NULL / IS NOT NULL semantics at the
|
|
1352
|
-
* substrate layer — the validator enforces `null` only on those two operators.
|
|
2037
|
+
* Context threaded into every `ScheduledTask.handler` call.
|
|
1353
2038
|
*/
|
|
1354
|
-
interface
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1362
|
-
|
|
1363
|
-
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
|
|
1367
|
-
|
|
1368
|
-
|
|
2039
|
+
interface ScheduledTaskContext {
|
|
2040
|
+
/** The owning plugin's `name`. */
|
|
2041
|
+
pluginName: string;
|
|
2042
|
+
/** Engine handle for read/write work performed by the task. */
|
|
2043
|
+
engine: EngineHandle;
|
|
2044
|
+
/** Structured metric sink — fire-and-forget. */
|
|
2045
|
+
metric(name: string, payload?: unknown): void;
|
|
2046
|
+
}
|
|
2047
|
+
interface ScheduledTask {
|
|
2048
|
+
/** Unique identifier within the plugin. Used in metric labels. */
|
|
2049
|
+
name: string;
|
|
2050
|
+
/** Fire interval in milliseconds. Minimum 100ms — smaller throws at register. */
|
|
2051
|
+
intervalMs: number;
|
|
2052
|
+
/** Fire once at registration in addition to the interval ticks. Default false. */
|
|
2053
|
+
runOnStart?: boolean;
|
|
2054
|
+
/** Handler — receives a context with engine access for read/write work. */
|
|
2055
|
+
handler(ctx: ScheduledTaskContext): void | Promise<void>;
|
|
1369
2056
|
}
|
|
1370
2057
|
/**
|
|
1371
|
-
*
|
|
1372
|
-
* predicates / nested where clauses (for struct fields). Field names and the
|
|
1373
|
-
* three combinator keys (AND/OR/NOT) share a namespace — `AND`/`OR`/`NOT` are
|
|
1374
|
-
* reserved and must not collide with field names declared in any type.
|
|
1375
|
-
*/
|
|
1376
|
-
type WhereClause = {
|
|
1377
|
-
AND: WhereClause[];
|
|
1378
|
-
} | {
|
|
1379
|
-
OR: WhereClause[];
|
|
1380
|
-
} | {
|
|
1381
|
-
NOT: WhereClause;
|
|
1382
|
-
} | {
|
|
1383
|
-
[field: string]: FieldPredicate | WhereClause | unknown;
|
|
1384
|
-
};
|
|
1385
|
-
/**
|
|
1386
|
-
* OrderBy clause. One entry per field, direction per field. Engine appends an
|
|
1387
|
-
* implicit `{ id: 'asc' }` when callers omit `id` as the final tie-breaker — a
|
|
1388
|
-
* deterministic tie-break is what makes cursor pagination stable across pages.
|
|
2058
|
+
* Context threaded into `CoordinatorPlugin.routes()` calls.
|
|
1389
2059
|
*/
|
|
1390
|
-
interface
|
|
1391
|
-
|
|
2060
|
+
interface PluginRouteContext {
|
|
2061
|
+
/** The owning plugin's `name`. */
|
|
2062
|
+
pluginName: string;
|
|
2063
|
+
/** Engine handle for plugin-scoped routes that need to dispatch back through the engine. */
|
|
2064
|
+
engine: EngineHandle;
|
|
2065
|
+
/** Structured metric sink — fire-and-forget. */
|
|
2066
|
+
metric(name: string, payload?: unknown): void;
|
|
1392
2067
|
}
|
|
1393
|
-
interface
|
|
1394
|
-
|
|
1395
|
-
|
|
1396
|
-
includeDeleted?: boolean;
|
|
1397
|
-
where?: WhereClause;
|
|
1398
|
-
orderBy?: OrderByClause[];
|
|
1399
|
-
limit?: number;
|
|
2068
|
+
interface CoordinatorPlugin {
|
|
2069
|
+
name: string;
|
|
2070
|
+
namespaces: NamespaceDefinition[];
|
|
1400
2071
|
/**
|
|
1401
|
-
*
|
|
1402
|
-
*
|
|
2072
|
+
* Plugin's bound contract version: a semver RANGE over the binary version,
|
|
2073
|
+
* e.g. `'>=4.1.0 <6.0.0'`.
|
|
2074
|
+
*
|
|
2075
|
+
* The ceiling tracks actual compatibility, not the next major: it moves
|
|
2076
|
+
* only when a major genuinely breaks the plugin-facing interface. A ceiling
|
|
2077
|
+
* that admits a major which did break lets the plugin load and misbehave
|
|
2078
|
+
* silently — if you cannot say whether the last major broke the plugin
|
|
2079
|
+
* interface, do not widen it.
|
|
2080
|
+
*
|
|
2081
|
+
* Enforced at boot: a plugin whose range excludes the running binary is
|
|
2082
|
+
* refused.
|
|
1403
2083
|
*/
|
|
1404
|
-
|
|
2084
|
+
contractVersion: string;
|
|
1405
2085
|
/**
|
|
1406
|
-
*
|
|
1407
|
-
*
|
|
1408
|
-
*
|
|
1409
|
-
*
|
|
2086
|
+
* Plugin-global policies applied to every resolver in every namespace the
|
|
2087
|
+
* plugin contributes. Composed by the loader via `and(...)` — the combined
|
|
2088
|
+
* policy must allow. Useful for cross-cutting concerns (audit logging,
|
|
2089
|
+
* rate limits, identity enrichment) that span multiple namespaces in the
|
|
2090
|
+
* same plugin. The composed result is surfaced through
|
|
2091
|
+
* `NamespaceInstallContext.pluginPolicy`.
|
|
2092
|
+
*/
|
|
2093
|
+
policies?: Policy[];
|
|
2094
|
+
/**
|
|
2095
|
+
* Told what each committed transaction wrote, once per `(namespace, type,
|
|
2096
|
+
* operation)` rather than once per row. Never awaited by the mutate, run in
|
|
2097
|
+
* commit order per plugin; a slow hook delays only this plugin's later calls.
|
|
2098
|
+
*/
|
|
2099
|
+
onCommittedWrites?: CommittedWritesHook;
|
|
2100
|
+
/**
|
|
2101
|
+
* Post-register lifecycle hook. Fires after every plugin's `install()`
|
|
2102
|
+
* resolves — use this for resource priming that needs the full namespace
|
|
2103
|
+
* map (e.g. cross-plugin edge warmup).
|
|
2104
|
+
*/
|
|
2105
|
+
onStart?(ctx: PluginLifecycleContext): void | Promise<void>;
|
|
2106
|
+
/**
|
|
2107
|
+
* Pre-shutdown lifecycle hook. Fires when the host calls `compose()`'s
|
|
2108
|
+
* returned `stop()` (which the binary's SIGTERM handler invokes inside
|
|
2109
|
+
* the `SUBSTRATE_SHUTDOWN_GRACE_MS` window). Hooks run in REVERSE
|
|
2110
|
+
* registration order so plugins tear down in the inverse of the order
|
|
2111
|
+
* they came up — late-loading plugins that depended on earlier ones get
|
|
2112
|
+
* to release their handles first.
|
|
1410
2113
|
*
|
|
1411
|
-
*
|
|
1412
|
-
*
|
|
1413
|
-
*
|
|
1414
|
-
*
|
|
1415
|
-
*
|
|
1416
|
-
*
|
|
2114
|
+
* Use for resources the OS won't reap on process exit:
|
|
2115
|
+
* - subprocess children that should receive SIGTERM cleanly
|
|
2116
|
+
* - long-lived `setInterval` timers (`.unref()` keeps them from
|
|
2117
|
+
* blocking exit, but explicit teardown is still cleaner for tests)
|
|
2118
|
+
* - WebSocket subscriptions / outbound connections that should close
|
|
2119
|
+
* cooperatively rather than dropping mid-request
|
|
1417
2120
|
*
|
|
1418
|
-
*
|
|
1419
|
-
*
|
|
1420
|
-
*
|
|
2121
|
+
* Errors are caught + logged via the lifecycle metric sink under
|
|
2122
|
+
* `plugin_on_stop_error` — one plugin's failed teardown does NOT abort
|
|
2123
|
+
* other plugins' teardown. The engine + pg pool are still live during
|
|
2124
|
+
* onStop calls, so plugins can do final writes (e.g. an audit row
|
|
2125
|
+
* recording the shutdown). After all onStop hooks resolve, the server
|
|
2126
|
+
* stops accepting connections and the substrate's `closeStore()` runs.
|
|
1421
2127
|
*
|
|
1422
|
-
*
|
|
1423
|
-
* Memory dataset, for instance, has no wire to save and ignores it.
|
|
2128
|
+
* Symmetric to `onStart`. Skipped (no-op) when omitted.
|
|
1424
2129
|
*/
|
|
1425
|
-
|
|
1426
|
-
|
|
1427
|
-
|
|
2130
|
+
onStop?(ctx: PluginLifecycleContext): void | Promise<void>;
|
|
2131
|
+
/**
|
|
2132
|
+
* Scheduled tasks — the binary ticks these on `.unref()`'d intervals.
|
|
2133
|
+
* Registered with the shared `TaskScheduler` at compose time and started
|
|
2134
|
+
* after the server's `start()` resolves.
|
|
2135
|
+
*/
|
|
2136
|
+
schedule?: ScheduledTask[];
|
|
2137
|
+
/**
|
|
2138
|
+
* Mount plugin-scoped HTTP/WS routes. Called once at compose-time with a
|
|
2139
|
+
* `PluginRouter` pre-prefixed `/substrate/v1/plugins/<name>` by the server impl. The
|
|
2140
|
+
* router surface matches `PluginRouter` in `./server.ts`.
|
|
2141
|
+
*
|
|
2142
|
+
* With auth on, HTTP routes require `read` for GET and `mutate` otherwise,
|
|
2143
|
+
* granted in one of this plugin's `namespaces`; a plugin with no namespaces
|
|
2144
|
+
* accepts the capability granted in any namespace.
|
|
2145
|
+
*/
|
|
2146
|
+
routes?(router: PluginRouter, ctx: PluginRouteContext): void | Promise<void>;
|
|
2147
|
+
/**
|
|
2148
|
+
* Optional onboarding contribution. When set, the hosting binary's
|
|
2149
|
+
* `GET /substrate/v1/onboard` aggregates this record under
|
|
2150
|
+
* `instructions.plugins.<name>` and enumerates the plugin's conventional
|
|
2151
|
+
* `/substrate/v1/plugins/<name>/onboard` route under `instructions.pluginRoutes`. Use
|
|
2152
|
+
* this to teach agents about the plugin's types, write flows, or any
|
|
2153
|
+
* plugin-specific grammar a cold-start agent would otherwise have to
|
|
2154
|
+
* discover per endpoint. The shape is free-form — the binary round-trips
|
|
2155
|
+
* it verbatim.
|
|
2156
|
+
*/
|
|
2157
|
+
onboardInstructions?: Record<string, unknown>;
|
|
1428
2158
|
}
|
|
1429
2159
|
/**
|
|
1430
|
-
*
|
|
1431
|
-
*
|
|
2160
|
+
* Substrate-tier plugin. Augments the kernel rather than the agent-facing
|
|
2161
|
+
* surface. Composes BEFORE coordinator plugins so coordinators can rely on
|
|
2162
|
+
* substrate registrations being live.
|
|
2163
|
+
*
|
|
2164
|
+
* SubstratePlugins do NOT own data namespaces — that's a CoordinatorPlugin
|
|
2165
|
+
* concern (a substrate may claim a virtual `kernelNamespace`).
|
|
1432
2166
|
*/
|
|
1433
|
-
interface
|
|
1434
|
-
|
|
1435
|
-
|
|
1436
|
-
hasMore: boolean;
|
|
1437
|
-
}
|
|
1438
|
-
interface WriteResult {
|
|
1439
|
-
written: number;
|
|
2167
|
+
interface KernelPlugin {
|
|
2168
|
+
/** Unique plugin name. Used in metric labels + collision detection. */
|
|
2169
|
+
name: string;
|
|
1440
2170
|
/**
|
|
1441
|
-
*
|
|
1442
|
-
*
|
|
2171
|
+
* Plugin's bound contract version: a semver RANGE over the binary version,
|
|
2172
|
+
* e.g. `'>=4.1.0 <6.0.0'`. Required on substrate plugins. Checked by
|
|
2173
|
+
* `composeFromManifests` and REFUSED at boot on mismatch; the
|
|
2174
|
+
* ceiling tracks actual compatibility rather than the next major boundary.
|
|
2175
|
+
* See the note on `CoordinatorPlugin.contractVersion` for both.
|
|
1443
2176
|
*/
|
|
1444
|
-
|
|
2177
|
+
contractVersion: string;
|
|
1445
2178
|
/**
|
|
1446
|
-
*
|
|
1447
|
-
*
|
|
1448
|
-
*
|
|
1449
|
-
*
|
|
1450
|
-
|
|
2179
|
+
* Schema migrations the plugin contributes. Applied in declared order
|
|
2180
|
+
* on first install AND on every binary boot (idempotently, gated by
|
|
2181
|
+
* the migrations tracking table seeded by the first KernelPlugin
|
|
2182
|
+
* to populate this slot).
|
|
2183
|
+
*/
|
|
2184
|
+
migrations?: KernelMigration[];
|
|
2185
|
+
/**
|
|
2186
|
+
* Names of the tables (in the store's schema) this plugin keeps data in.
|
|
2187
|
+
* `substrate-admin migrate-store` copies them alongside the engine's own
|
|
2188
|
+
* tables and refuses a source table that nothing declares.
|
|
2189
|
+
*/
|
|
2190
|
+
storeTables?: readonly string[];
|
|
2191
|
+
/**
|
|
2192
|
+
* Filter operators contributed to the where-clause grammar. Each entry
|
|
2193
|
+
* registers a custom operator (e.g. `embeddingSimilar`) the engine's
|
|
2194
|
+
* query validator + substrate executor can dispatch to.
|
|
2195
|
+
*/
|
|
2196
|
+
filterOperators?: Record<string, FilterOperatorDef>;
|
|
2197
|
+
/**
|
|
2198
|
+
* Top-level kernel route claims. Plugin reserves a path under /substrate/v1/.
|
|
2199
|
+
* First-claim wins; collision = boot refusal with actionable error.
|
|
2200
|
+
*/
|
|
2201
|
+
kernelRoutes?: KernelRouteClaim[];
|
|
2202
|
+
/**
|
|
2203
|
+
* Top-level MCP tool registrations. Tool name registers globally with
|
|
2204
|
+
* the MCP server (no /plugins/ prefix on MCP — tools are flat).
|
|
2205
|
+
*/
|
|
2206
|
+
mcpTools?: McpToolRegistration[];
|
|
2207
|
+
/**
|
|
2208
|
+
* Frame-surface contribution. Claims one namespace in the engine registry
|
|
2209
|
+
* carrying resolver-backed query types + mutations — no dataset, no
|
|
2210
|
+
* autoCRUD. Dispatch/policy/idempotency/pack/schema/NL/MCP all inherit from
|
|
2211
|
+
* the normal frame path.
|
|
2212
|
+
*/
|
|
2213
|
+
kernelNamespace?: KernelNamespaceContribution;
|
|
2214
|
+
/**
|
|
2215
|
+
* Post-register lifecycle hook. Fires after every KernelPlugin's
|
|
2216
|
+
* migrations + registrations resolve, BEFORE any coordinator plugin
|
|
2217
|
+
* composes. Use for resource priming the kernel needs before
|
|
2218
|
+
* coordinators arrive.
|
|
2219
|
+
*/
|
|
2220
|
+
onKernelReady?(ctx: KernelLifecycleContext): void | Promise<void>;
|
|
2221
|
+
/**
|
|
2222
|
+
* Stops whatever `onKernelReady` started (timers, workers). The host calls
|
|
2223
|
+
* it before it closes the store, and may call it more than once.
|
|
2224
|
+
*/
|
|
2225
|
+
onKernelStop?(): void | Promise<void>;
|
|
2226
|
+
/**
|
|
2227
|
+
* Contribute postWrite hooks for a coordinator namespace at install time.
|
|
2228
|
+
* Called by the engine ONCE per registered coordinator namespace, AFTER
|
|
2229
|
+
* substrate composition completes. Returned hooks are merged into the
|
|
2230
|
+
* type's effective postWrite chain alongside the type's own inline
|
|
2231
|
+
* `postWrite` (if any). Substrate-supplied hooks run AFTER the type's
|
|
2232
|
+
* inline hook in chain order.
|
|
2233
|
+
*
|
|
2234
|
+
* Use this to inspect `namespace.types[T].embed` and emit embedding
|
|
2235
|
+
* hooks per type without coupling the binary to plugin internals.
|
|
2236
|
+
*
|
|
2237
|
+
* Returns: a record mapping type names to PostWriteHook contributions.
|
|
2238
|
+
* Type names not in the record receive no contribution.
|
|
2239
|
+
*/
|
|
2240
|
+
contributePostWrites?: (namespace: NamespaceDefinition) => Record<string, PostWriteHook>;
|
|
2241
|
+
}
|
|
2242
|
+
/** Single migration unit. */
|
|
2243
|
+
interface KernelMigration {
|
|
2244
|
+
/** Unique id within the plugin. Stored in migrations tracking table. */
|
|
2245
|
+
id: string;
|
|
2246
|
+
/** Apply migration. Called only when this migration's id is absent from the migrations table. */
|
|
2247
|
+
apply(ctx: KernelMigrationContext): Promise<void>;
|
|
2248
|
+
/** Inverse — drops what apply created. */
|
|
2249
|
+
rollback?(ctx: KernelMigrationContext): Promise<void>;
|
|
2250
|
+
}
|
|
2251
|
+
interface KernelMigrationContext {
|
|
2252
|
+
/**
|
|
2253
|
+
* Direct SQL handle for postgres-backed deployments; null when the
|
|
2254
|
+
* binary is running against the in-memory dataset.
|
|
2255
|
+
*/
|
|
2256
|
+
sql: unknown | null;
|
|
2257
|
+
/**
|
|
2258
|
+
* How rows are stored: `'tables'`, one table per type and no `rows` table,
|
|
2259
|
+
* the only layout a store boots. `null` on the in-memory dataset. A
|
|
2260
|
+
* migration that still runs DDL on `rows` fails, and the host names its
|
|
2261
|
+
* plugin (`KernelMigrationLayoutError`).
|
|
1451
2262
|
*/
|
|
1452
|
-
|
|
2263
|
+
layout: 'tables' | null;
|
|
2264
|
+
metric(name: string, payload?: unknown): void;
|
|
1453
2265
|
}
|
|
1454
2266
|
/**
|
|
1455
|
-
*
|
|
1456
|
-
* `_metadata` is absent, the substrate auto-fills it from these hints:
|
|
1457
|
-
* - `now` → both `createdAt` and `updatedAt` (defaults to `new Date()`)
|
|
1458
|
-
* - `identity` → both `createdBy` and `updatedBy` (defaults to `null`)
|
|
2267
|
+
* Where-clause operator extension.
|
|
1459
2268
|
*
|
|
1460
|
-
*
|
|
1461
|
-
* `
|
|
1462
|
-
*
|
|
1463
|
-
*
|
|
2269
|
+
* The operator's name is the Record key it's registered under in
|
|
2270
|
+
* `KernelPlugin.filterOperators`.
|
|
2271
|
+
*
|
|
2272
|
+
* `execute` is awaited by the pre-resolve pass (`@mnmal-ai/substrate-filter`'s
|
|
2273
|
+
* `preResolveExtensionOperatorsDetailed`) and must resolve to an ordered,
|
|
2274
|
+
* scored `{ hits: [{ id: string; score: number; vector?: number[] }, ...] }`
|
|
2275
|
+
* envelope; any other shape throws `ExtensionOperatorResultError`. Relevance
|
|
2276
|
+
* order is preserved in the rewritten `id IN`, and score/vector are surfaced
|
|
2277
|
+
* via the pre-pass meta side-channel for the datasets to stitch onto rows.
|
|
1464
2278
|
*/
|
|
1465
|
-
interface
|
|
1466
|
-
|
|
1467
|
-
|
|
2279
|
+
interface FilterOperatorDef {
|
|
2280
|
+
validate(value: unknown): {
|
|
2281
|
+
ok: true;
|
|
2282
|
+
value: unknown;
|
|
2283
|
+
} | {
|
|
2284
|
+
ok: false;
|
|
2285
|
+
reason: string;
|
|
2286
|
+
};
|
|
2287
|
+
execute(value: unknown, context: unknown): Promise<unknown>;
|
|
1468
2288
|
/**
|
|
1469
|
-
*
|
|
1470
|
-
*
|
|
1471
|
-
*
|
|
2289
|
+
* Computed projection field names the operator contributes per hit (e.g.
|
|
2290
|
+
* `['_score', '_vector']`). The engine refuses a projection of one of these
|
|
2291
|
+
* fields unless its operator is in the where-clause.
|
|
1472
2292
|
*/
|
|
1473
|
-
|
|
1474
|
-
}
|
|
1475
|
-
interface DeleteResult {
|
|
1476
|
-
deleted: number;
|
|
1477
|
-
ids: Id[];
|
|
1478
|
-
}
|
|
1479
|
-
interface DropResult {
|
|
1480
|
-
/** Number of rows physically removed. */
|
|
1481
|
-
rowsDeleted: number;
|
|
1482
|
-
/** Number of short-id allocations physically removed. */
|
|
1483
|
-
shortIdsDeleted: number;
|
|
2293
|
+
computedFields?: string[];
|
|
1484
2294
|
}
|
|
1485
2295
|
/**
|
|
1486
|
-
*
|
|
1487
|
-
*
|
|
1488
|
-
*
|
|
2296
|
+
* Query-only virtual type contributed by a substrate plugin.
|
|
2297
|
+
* `fields` reuses the FieldDef DSL so schema publication + client typing
|
|
2298
|
+
* work unchanged. The resolver receives the standard (ctx, args) pair; the
|
|
2299
|
+
* engine leaves `args.dataset` undefined for virtual namespaces — resolvers
|
|
2300
|
+
* compute from `params`/`fields` and MUST NOT reach for a dataset handle.
|
|
1489
2301
|
*/
|
|
1490
|
-
|
|
1491
|
-
|
|
1492
|
-
|
|
1493
|
-
/** Does the dataset honour `orderBy`? */
|
|
1494
|
-
orderBy: boolean;
|
|
1495
|
-
/** Does the dataset honour cursor-based pagination? */
|
|
1496
|
-
cursor: boolean;
|
|
2302
|
+
interface VirtualTypeDef {
|
|
2303
|
+
fields: Record<string, FieldDef>;
|
|
2304
|
+
resolver: RegistryEntryResolver;
|
|
1497
2305
|
}
|
|
1498
|
-
|
|
1499
|
-
|
|
1500
|
-
|
|
1501
|
-
|
|
2306
|
+
/** Mutation contributed by a substrate plugin under its virtual namespace. */
|
|
2307
|
+
interface VirtualMutationDef {
|
|
2308
|
+
resolver: RegistryEntryResolver;
|
|
2309
|
+
/** Optional params schema published into the namespace schema. */
|
|
2310
|
+
params?: Record<string, FieldDef>;
|
|
1502
2311
|
}
|
|
1503
2312
|
/**
|
|
1504
|
-
*
|
|
1505
|
-
*
|
|
1506
|
-
*
|
|
1507
|
-
* row's stored value at the moment of the update — the substrate applied
|
|
1508
|
-
* `updates` and returned the merged row. `matched: false` when the row was
|
|
1509
|
-
* missing or at least one match condition failed; in both cases no write landed
|
|
1510
|
-
* and `row` is `null`.
|
|
2313
|
+
* A substrate plugin's claimed frame surface.
|
|
2314
|
+
* Registered into the engine's namespaces map as `{ registry, virtual: true }`.
|
|
2315
|
+
* Collision posture mirrors KernelRouteClaim: second claim = boot refusal.
|
|
1511
2316
|
*/
|
|
1512
|
-
interface
|
|
1513
|
-
|
|
1514
|
-
|
|
2317
|
+
interface KernelNamespaceContribution {
|
|
2318
|
+
namespace: string;
|
|
2319
|
+
types?: Record<string, VirtualTypeDef>;
|
|
2320
|
+
mutations?: Record<string, VirtualMutationDef>;
|
|
1515
2321
|
}
|
|
1516
|
-
|
|
1517
|
-
|
|
2322
|
+
/** Top-level kernel route reservation. */
|
|
2323
|
+
interface KernelRouteClaim {
|
|
2324
|
+
path: string;
|
|
2325
|
+
method: HttpMethod;
|
|
2326
|
+
handler: HttpHandler;
|
|
1518
2327
|
/**
|
|
1519
|
-
*
|
|
1520
|
-
*
|
|
1521
|
-
*
|
|
1522
|
-
* substrate-coalescing path (spec §5.3, enabling cross-namespace G1
|
|
1523
|
-
* batched mutations when all frames target the same substrate).
|
|
1524
|
-
*
|
|
1525
|
-
* Convention:
|
|
1526
|
-
* - pg: derived from the `postgres.Sql` pool reference identity. All
|
|
1527
|
-
* `PgDataset` instances constructed against the same `sql`
|
|
1528
|
-
* handle share one `txScopeId`.
|
|
1529
|
-
* - memory: unique per `MemoryDataset` instance by default (each
|
|
1530
|
-
* instance owns its own `Map`). Test harnesses that want shared-
|
|
1531
|
-
* memory semantics can opt in via an explicit constructor option.
|
|
2328
|
+
* Capability the host must check before dispatching, when auth is enabled.
|
|
2329
|
+
* REQUIRED — `'public'` is how a route opts out, so opting out is a
|
|
2330
|
+
* declaration rather than an omission.
|
|
1532
2331
|
*
|
|
1533
|
-
*
|
|
1534
|
-
*
|
|
1535
|
-
*
|
|
2332
|
+
* Do not make this optional: kernel routes mount via the host's raw
|
|
2333
|
+
* `server.route`, which applies no gate of its own, so a route with no
|
|
2334
|
+
* capability would get no auth wrapper at all.
|
|
1536
2335
|
*/
|
|
1537
|
-
|
|
1538
|
-
|
|
1539
|
-
|
|
1540
|
-
|
|
1541
|
-
|
|
2336
|
+
capability: 'read' | 'mutate' | 'admin' | 'public';
|
|
2337
|
+
}
|
|
2338
|
+
/** Top-level MCP tool registration. */
|
|
2339
|
+
interface McpToolRegistration {
|
|
2340
|
+
name: string;
|
|
2341
|
+
description: string;
|
|
2342
|
+
inputSchema: unknown;
|
|
2343
|
+
handler(input: unknown): Promise<unknown>;
|
|
2344
|
+
}
|
|
2345
|
+
interface KernelLifecycleContext {
|
|
1542
2346
|
/**
|
|
1543
|
-
*
|
|
1544
|
-
*
|
|
1545
|
-
*
|
|
1546
|
-
*
|
|
1547
|
-
* MUST run inside a caller-supplied `withTransaction` if atomicity with
|
|
1548
|
-
* edge cleanup / audit emission is required. When called standalone,
|
|
1549
|
-
* implementations MUST still execute the row-delete + short-id-delete as
|
|
1550
|
-
* a single atomic step against the substrate.
|
|
1551
|
-
*
|
|
1552
|
-
* Returns the exact counts physically removed. If the type has no rows,
|
|
1553
|
-
* returns zeros without error.
|
|
1554
|
-
*
|
|
1555
|
-
* Storage-level primitive: operates on any (namespace, type) rows present
|
|
1556
|
-
* in storage regardless of whether the type is currently known to the
|
|
1557
|
-
* engine's registry.
|
|
2347
|
+
* Tagged-union discriminant. Differentiates this context from the
|
|
2348
|
+
* structurally-similar `PluginLifecycleContext`, which would otherwise be
|
|
2349
|
+
* interchangeable under structural typing.
|
|
1558
2350
|
*/
|
|
1559
|
-
|
|
2351
|
+
readonly lifecycle: 'kernel';
|
|
1560
2352
|
/**
|
|
1561
|
-
*
|
|
1562
|
-
*
|
|
1563
|
-
*
|
|
1564
|
-
* where available (pg: `DELETE FROM rows WHERE namespace = $1`).
|
|
2353
|
+
* Direct SQL handle; null when the binary runs against the in-memory
|
|
2354
|
+
* dataset. Same shape and same null semantics as
|
|
2355
|
+
* `KernelMigrationContext.sql`.
|
|
1565
2356
|
*
|
|
1566
|
-
*
|
|
2357
|
+
* For convergent, run-every-boot reconciliation: a migration runs only once
|
|
2358
|
+
* per `id`, so it cannot re-scope objects it already created.
|
|
1567
2359
|
*/
|
|
1568
|
-
|
|
1569
|
-
updateField(ref: UpdateFieldRef, fieldName: string, value: unknown): Promise<void>;
|
|
2360
|
+
sql: unknown | null;
|
|
1570
2361
|
/**
|
|
1571
|
-
*
|
|
1572
|
-
*
|
|
1573
|
-
* `updates` map and return `{ matched: true, row: mergedRow }`. Otherwise
|
|
1574
|
-
* write nothing and return `{ matched: false, row: null }`.
|
|
1575
|
-
*
|
|
1576
|
-
* Semantics:
|
|
1577
|
-
* - Equality is strict (`===`) for scalars; `Date` compares by
|
|
1578
|
-
* `.getTime()`; `null` matches only a stored `null` (including
|
|
1579
|
-
* intentionally-null fields set via `updateField`), never an absent field.
|
|
1580
|
-
* - A missing row fails the match even when `match` is empty — the
|
|
1581
|
-
* operation is "update this existing row if predicate holds".
|
|
1582
|
-
* - `updates` is merged onto the stored row the same way `write()` upserts
|
|
1583
|
-
* merge: each key overwrites; omitted keys are preserved. `_deletedAt`
|
|
1584
|
-
* is reserved and silently skipped (matches `write()`'s sanitisation).
|
|
1585
|
-
* - The whole check+write is atomic against other dataset operations.
|
|
1586
|
-
* Implementations MUST NOT yield between the predicate test and the
|
|
1587
|
-
* write. Pg uses `UPDATE ... WHERE <match> RETURNING *` inside the
|
|
1588
|
-
* caller's enclosing `withTransaction`; memory runs the whole body
|
|
1589
|
-
* synchronously within the `async` microtask.
|
|
2362
|
+
* Namespaces DECLARED by the coordinator plugins this binary loaded, in
|
|
2363
|
+
* load order. Empty when none are configured.
|
|
1590
2364
|
*
|
|
1591
|
-
*
|
|
1592
|
-
*
|
|
1593
|
-
* timestamp exactly once, even under concurrent registrations.
|
|
2365
|
+
* Declared, not installed: coordinators compose AFTER substrate, so the
|
|
2366
|
+
* engine has not yet registered them.
|
|
1594
2367
|
*
|
|
1595
|
-
*
|
|
1596
|
-
*
|
|
1597
|
-
* a `{ kind: 'system', id: 'anonymous' }` sentinel when omitted) — same
|
|
1598
|
-
* semantics as `write()`'s upsert path, so recency-ranked recall sees the
|
|
1599
|
-
* change. `createdAt` / `createdBy` are preserved.
|
|
2368
|
+
* Read these rather than adding a namespace knob to substrate config, which
|
|
2369
|
+
* could silently disagree with what the coordinator uses.
|
|
1600
2370
|
*/
|
|
1601
|
-
|
|
1602
|
-
readonly capabilities: FilterCapabilities;
|
|
2371
|
+
coordinatorNamespaces: readonly string[];
|
|
1603
2372
|
/**
|
|
1604
|
-
*
|
|
1605
|
-
*
|
|
1606
|
-
* pg holds a session advisory lock, so the exclusion spans processes sharing
|
|
1607
|
-
* the store's database schema; memory excludes holders on this dataset instance only.
|
|
1608
|
-
* Released when `fn` settles, whether it resolves or throws, except on a
|
|
1609
|
-
* pg tx-bound dataset, where it is held until the transaction ends so the
|
|
1610
|
-
* next holder sees what this one committed. Not re-entrant:
|
|
1611
|
-
* re-acquiring a held key inside `fn` waits forever.
|
|
2373
|
+
* The same namespaces, attributed to the coordinator that declared each.
|
|
2374
|
+
* Declaration order preserved within a plugin.
|
|
1612
2375
|
*
|
|
1613
|
-
*
|
|
2376
|
+
* The two absent cases differ and consumers must branch on them:
|
|
2377
|
+
* - `undefined` — this host does not supply attribution (e.g. an older
|
|
2378
|
+
* binary); do not treat it as an empty list
|
|
2379
|
+
* - `[]` — attribution supplied, and there are no coordinators
|
|
1614
2380
|
*
|
|
1615
|
-
*
|
|
1616
|
-
*
|
|
2381
|
+
* Filtering on `plugin === 'some-name'` makes the coordinator's `name` a
|
|
2382
|
+
* contract term: hold it in one constant shared with the coordinator and pin
|
|
2383
|
+
* it with a test, or a rename makes the filter silently match nothing.
|
|
1617
2384
|
*/
|
|
1618
|
-
|
|
2385
|
+
coordinatorNamespacesByPlugin?: readonly {
|
|
2386
|
+
plugin: string;
|
|
2387
|
+
namespace: string;
|
|
2388
|
+
}[];
|
|
1619
2389
|
/**
|
|
1620
|
-
*
|
|
1621
|
-
*
|
|
1622
|
-
*
|
|
1623
|
-
*
|
|
1624
|
-
|
|
1625
|
-
|
|
1626
|
-
|
|
1627
|
-
|
|
1628
|
-
|
|
1629
|
-
|
|
1630
|
-
|
|
1631
|
-
|
|
2390
|
+
* Whether this boot may start background work (timers, backfills). False
|
|
2391
|
+
* when the host boots the store only to prepare or copy into it, as
|
|
2392
|
+
* `substrate-admin migrate-store` does: do convergent reconciliation, start
|
|
2393
|
+
* nothing that writes later.
|
|
2394
|
+
*/
|
|
2395
|
+
background: boolean;
|
|
2396
|
+
metric(name: string, payload?: unknown): void;
|
|
2397
|
+
}
|
|
2398
|
+
//#endregion
|
|
2399
|
+
//#region ../../packages/substrate-types/src/schema.d.ts
|
|
2400
|
+
/**
|
|
2401
|
+
* One clause of a walk-grammar read, marked index-served or not (typed edge
|
|
2402
|
+
* walks, goal 7). `path` is inside the frame entry, e.g. `['where', '_walk']`.
|
|
2403
|
+
* An unserved clause names the index that would serve it in `recommend`, when
|
|
2404
|
+
* one can be declared.
|
|
2405
|
+
*/
|
|
2406
|
+
interface PlanClause {
|
|
2407
|
+
path: string[];
|
|
2408
|
+
kind: 'hop' | 'filter' | 'order' | 'ref' | 'derive' | 'bucket' | 'agg';
|
|
2409
|
+
served: boolean;
|
|
2410
|
+
recommend?: IndexDecl;
|
|
2411
|
+
/**
|
|
2412
|
+
* On the hop of a pick or a frame `_agg`: how the store evaluates it.
|
|
2413
|
+
* `per-seed` probes once per seed row; `per-hub` computes a pick once per
|
|
2414
|
+
* hub many seeds share; `group-by` aggregates a window in one pass.
|
|
2415
|
+
*/
|
|
2416
|
+
form?: 'per-seed' | 'per-hub' | 'group-by';
|
|
2417
|
+
}
|
|
2418
|
+
/** Words of a natural-language question the parse did not use, and why. */
|
|
2419
|
+
interface Dropped {
|
|
2420
|
+
span: string;
|
|
2421
|
+
reason: string;
|
|
2422
|
+
/**
|
|
2423
|
+
* What the loss changes. `filter`: which rows match (a filter, comparison,
|
|
2424
|
+
* walk, time window or connective), so a count, aggregate, `$ref` or pick
|
|
2425
|
+
* reading that lost it is `unknown`. `order`: an ordering, limit or
|
|
2426
|
+
* projection; the matched rows are the same and the answer stands.
|
|
1632
2427
|
*/
|
|
1633
|
-
|
|
1634
|
-
|
|
1635
|
-
|
|
1636
|
-
|
|
2428
|
+
kind: 'filter' | 'order';
|
|
2429
|
+
}
|
|
2430
|
+
interface FieldDefScalar {
|
|
2431
|
+
kind: 'scalar';
|
|
1637
2432
|
/**
|
|
1638
|
-
*
|
|
1639
|
-
*
|
|
1640
|
-
*
|
|
1641
|
-
*
|
|
2433
|
+
* `'json'` is an opaque body: msgpack-friendly nested object/array, value
|
|
2434
|
+
* round-trips unchanged, but no per-leaf filtering or ordering. Use it for
|
|
2435
|
+
* freeform payloads (audit details, debug bags). When you need filterable
|
|
2436
|
+
* inner keys, use `field.struct` instead.
|
|
1642
2437
|
*/
|
|
1643
|
-
|
|
2438
|
+
type: 'string' | 'number' | 'boolean' | 'date' | 'json';
|
|
1644
2439
|
/**
|
|
1645
|
-
*
|
|
1646
|
-
*
|
|
1647
|
-
*
|
|
1648
|
-
*
|
|
1649
|
-
*
|
|
1650
|
-
* anything.
|
|
1651
|
-
*
|
|
1652
|
-
* OPTIONAL. Backends without per-type storage omit it.
|
|
2440
|
+
* Tri-state. `true` builds an index (a btree; a GIN for json). Unset means
|
|
2441
|
+
* no index. `false` means no index AND not a search handle: long-form
|
|
2442
|
+
* prose that NL and similar consumers leave out. The field filters either
|
|
2443
|
+
* way. Physical consumers test `=== true`, so never normalise unset to
|
|
2444
|
+
* `false`.
|
|
1653
2445
|
*/
|
|
1654
|
-
|
|
1655
|
-
partitionBudget: number;
|
|
1656
|
-
}): Promise<StorageReport>;
|
|
2446
|
+
indexed?: boolean;
|
|
1657
2447
|
/**
|
|
1658
|
-
*
|
|
1659
|
-
*
|
|
1660
|
-
*
|
|
1661
|
-
*
|
|
1662
|
-
* OPTIONAL. Backends without such statistics omit it.
|
|
2448
|
+
* Metadata: when true, the value may be unset. A string, number, boolean or
|
|
2449
|
+
* date reads back as an absent key then, never `null` (`isColumnField`); a
|
|
2450
|
+
* `json` field keeps an explicit `null`.
|
|
1663
2451
|
*/
|
|
1664
|
-
|
|
2452
|
+
nullable?: boolean;
|
|
1665
2453
|
/**
|
|
1666
|
-
*
|
|
1667
|
-
*
|
|
1668
|
-
*
|
|
1669
|
-
*
|
|
1670
|
-
*
|
|
2454
|
+
* Metadata: when true, this field is populated by the engine (not the caller)
|
|
2455
|
+
* and write attempts that include it MUST be rejected. Used for the
|
|
2456
|
+
* auto-injected `shortId` field. Consumers (autoCRUD create, schema
|
|
2457
|
+
* publisher, client codegen) rely on this flag as a declarative contract —
|
|
2458
|
+
* do not imperatively guard readonly fields without also flipping this.
|
|
1671
2459
|
*/
|
|
1672
|
-
|
|
2460
|
+
readonly?: boolean;
|
|
1673
2461
|
/**
|
|
1674
|
-
*
|
|
1675
|
-
*
|
|
1676
|
-
*
|
|
1677
|
-
*
|
|
1678
|
-
*
|
|
1679
|
-
*
|
|
1680
|
-
*
|
|
1681
|
-
*
|
|
1682
|
-
*
|
|
1683
|
-
* there, `propose_index remove` has no index to find, so it is refused
|
|
1684
|
-
* `unknown_index`, and a remove recommendation it names is superseded.
|
|
2462
|
+
* Server-managed date flag. Clients may not supply the field in the
|
|
2463
|
+
* indicated phase(s) — autoCRUD rejects it with `client_supplied_server_field`:
|
|
2464
|
+
* - 'create' — on create only
|
|
2465
|
+
* - 'update' — on update only
|
|
2466
|
+
* - 'both' — on create and update
|
|
2467
|
+
* Nothing stamps it automatically: server-side code (a custom resolver or a
|
|
2468
|
+
* system writer such as `applyUpdatePatch`) sets it. A non-nullable,
|
|
2469
|
+
* non-defaulted field gated on create is refused by autoCRUD at install,
|
|
2470
|
+
* since nothing could fill it. Only honoured on `type: 'date'`.
|
|
1685
2471
|
*/
|
|
1686
|
-
|
|
1687
|
-
/** Runs once every check has passed, just before the drop; a throw drops nothing. */
|
|
1688
|
-
beforeDrop?: () => Promise<void>;
|
|
1689
|
-
/** The drop's bound on each lock wait, in ms. Defaults to the backend's own. */
|
|
1690
|
-
lockTimeoutMs?: number;
|
|
1691
|
-
}): Promise<void>;
|
|
2472
|
+
serverSet?: 'create' | 'update' | 'both';
|
|
1692
2473
|
/**
|
|
1693
|
-
*
|
|
1694
|
-
*
|
|
1695
|
-
*
|
|
1696
|
-
*
|
|
1697
|
-
*
|
|
1698
|
-
* unique index, writes would not be held to it. Returns the names dropped.
|
|
1699
|
-
* Never inside a transaction; a tx-bound instance throws. A lock wait that
|
|
1700
|
-
* times out throws `index_drop_timeout`, leaving the rest for
|
|
1701
|
-
* `storageReport` to list as orphaned.
|
|
1702
|
-
*
|
|
1703
|
-
* OPTIONAL. Backends that build no indexes omit it.
|
|
2474
|
+
* Controlled vocabulary. When present, the value MUST be one of these
|
|
2475
|
+
* strings. Consumed by autoCRUD write-validation (covers memory + pg
|
|
2476
|
+
* uniformly) and surfaced verbatim in the published schema. `type` stays
|
|
2477
|
+
* 'string' — an enum is a constrained string, so pack / client decoder /
|
|
2478
|
+
* where-validation treat it identically with no new branch.
|
|
1704
2479
|
*/
|
|
1705
|
-
|
|
1706
|
-
unique?: boolean;
|
|
1707
|
-
}): Promise<string[]>;
|
|
2480
|
+
enum?: readonly string[];
|
|
1708
2481
|
/**
|
|
1709
|
-
*
|
|
1710
|
-
*
|
|
1711
|
-
*
|
|
1712
|
-
*
|
|
1713
|
-
*
|
|
1714
|
-
* OPTIONAL. Backends that build no indexes omit it.
|
|
2482
|
+
* Governed vocabulary: alias -> canonical value (each canonical value is in
|
|
2483
|
+
* `enum`). autoCRUD stores the canonical value when an alias is written, and
|
|
2484
|
+
* `where` filters on the field match it, so synonyms converge instead of
|
|
2485
|
+
* sprawling. Matching is case-insensitive. Published in the schema so every
|
|
2486
|
+
* client reads the same table.
|
|
1715
2487
|
*/
|
|
1716
|
-
|
|
2488
|
+
aliases?: Readonly<Record<string, string>>;
|
|
1717
2489
|
/**
|
|
1718
|
-
*
|
|
1719
|
-
*
|
|
1720
|
-
*
|
|
1721
|
-
* transaction commits and the resolved value is returned.
|
|
1722
|
-
*
|
|
1723
|
-
* Scope rules:
|
|
1724
|
-
* - `tx.namespace === this.namespace`
|
|
1725
|
-
* - Calls on the outer dataset (`this`) inside `fn` bypass the transaction
|
|
1726
|
-
* and are NOT rolled back on failure — this is a caller bug; implementations
|
|
1727
|
-
* MUST NOT attempt to guard against it. All ops inside `fn` MUST go through
|
|
1728
|
-
* `tx`.
|
|
1729
|
-
* - Nested `tx.withTransaction(...)` is implementation-defined. The reference
|
|
1730
|
-
* impls (memory, pg) flatten nested calls into the outermost transaction
|
|
1731
|
-
* (no savepoints).
|
|
2490
|
+
* `false` admits values outside `enum` (aliases are still normalised): a
|
|
2491
|
+
* transition mode for adopting a vocabulary over existing free-string data.
|
|
2492
|
+
* Absent means strict.
|
|
1732
2493
|
*/
|
|
1733
|
-
|
|
2494
|
+
strict?: boolean;
|
|
1734
2495
|
/**
|
|
1735
|
-
*
|
|
1736
|
-
*
|
|
1737
|
-
*
|
|
1738
|
-
*
|
|
1739
|
-
*
|
|
1740
|
-
*
|
|
1741
|
-
* `namespaces` is the full set of namespaces the engine will dispatch
|
|
1742
|
-
* frames to inside the tx. Implementations MUST return a tx-bound
|
|
1743
|
-
* dataset for every requested namespace in `handles.datasets`; missing
|
|
1744
|
-
* entries are a programming error on the caller side.
|
|
1745
|
-
*
|
|
1746
|
-
* `handles.edges` contract:
|
|
1747
|
-
* - `non-null` when the implementation can enlist a shared `EdgesStore`
|
|
1748
|
-
* into the same substrate tx (e.g. pg where the `PgEdgesStore` is wired
|
|
1749
|
-
* in via constructor and shares the `Sql`). The engine routes edge
|
|
1750
|
-
* mutations through this handle — true cross-store atomicity for
|
|
1751
|
-
* row + edge within one frame.
|
|
1752
|
-
* - `null` when the implementation can't enlist (e.g. memory datasets
|
|
1753
|
-
* where edges live in a separate Map). The engine falls back to
|
|
1754
|
-
* running edge ops in a nested independent tx and accepts the
|
|
1755
|
-
* visibility-ordering quirk documented in `autocrud-delete.ts`.
|
|
1756
|
-
*
|
|
1757
|
-
* Scope rules mirror `withTransaction`:
|
|
1758
|
-
* - All ops on values from `handles.datasets.get(ns)` and `handles.edges`
|
|
1759
|
-
* run in the same tx.
|
|
1760
|
-
* - Ops on the outer dataset (`this`) inside `fn` bypass the tx — caller
|
|
1761
|
-
* bug; implementations do not guard.
|
|
1762
|
-
* - A throw or rejection inside `fn` rolls back every mutation across
|
|
1763
|
-
* every namespace + edges in the tx.
|
|
1764
|
-
*
|
|
1765
|
-
* OPTIONAL. Implementations that can't coalesce cross-namespace writes
|
|
1766
|
-
* into one substrate transaction omit this method — the engine falls
|
|
1767
|
-
* back to refusing cross-namespace batches with `cross_tx_scope_refused`
|
|
1768
|
-
* (and loses edge-enlist for single-ns).
|
|
2496
|
+
* Alias (or canonical value) -> sibling fields it implies, e.g.
|
|
2497
|
+
* `done -> { resolution: 'completed' }`. On write the siblings are filled
|
|
2498
|
+
* when the caller omits them and a contradicting value is refused; an
|
|
2499
|
+
* `eq` filter on the alias also matches the implied siblings. Keys match
|
|
2500
|
+
* case-insensitively.
|
|
1769
2501
|
*/
|
|
1770
|
-
|
|
2502
|
+
implies?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
|
|
1771
2503
|
/**
|
|
1772
|
-
*
|
|
1773
|
-
*
|
|
1774
|
-
*
|
|
1775
|
-
*
|
|
1776
|
-
*
|
|
1777
|
-
*
|
|
1778
|
-
*
|
|
1779
|
-
* what callers expect).
|
|
2504
|
+
* Default value applied by autoCRUD `create` when the caller omits this
|
|
2505
|
+
* field. Two effects: (1) the row is written with the default instead of
|
|
2506
|
+
* being absent; (2) it satisfies the non-nullable presence check, so a
|
|
2507
|
+
* non-nullable scalar WITHOUT a default that is omitted on create is
|
|
2508
|
+
* rejected (`missing_required_field`) — that is how "required" is expressed.
|
|
2509
|
+
* Only applied on create (update is a partial patch). The value should match
|
|
2510
|
+
* `type` (booleans for boolean, ISO string for date, etc.).
|
|
1780
2511
|
*/
|
|
1781
|
-
|
|
2512
|
+
default?: string | number | boolean;
|
|
2513
|
+
}
|
|
2514
|
+
interface FieldDefCrossRef {
|
|
2515
|
+
kind: 'crossRef';
|
|
2516
|
+
ns: string;
|
|
2517
|
+
type: string;
|
|
2518
|
+
onDelete: OnDelete;
|
|
1782
2519
|
/**
|
|
1783
|
-
*
|
|
1784
|
-
*
|
|
1785
|
-
*
|
|
2520
|
+
* Write-time existence policy. 'reject' refuses a create/update
|
|
2521
|
+
* whose crossRef value points at a non-existent or tombstoned target;
|
|
2522
|
+
* 'allow' is the default when absent. Consulted only at write time, never
|
|
2523
|
+
* stored on the edge. Enforced only for locally-resolvable
|
|
2524
|
+
* target namespaces (compose rejects 'reject' on bridged/unknown targets).
|
|
1786
2525
|
*/
|
|
1787
|
-
|
|
2526
|
+
onMissing?: OnMissing;
|
|
1788
2527
|
/**
|
|
1789
|
-
*
|
|
1790
|
-
*
|
|
1791
|
-
*
|
|
2528
|
+
* Substrate-level indexing hint for the edge-source column, mirroring
|
|
2529
|
+
* `FieldDefScalar.indexed`, so the dataset need not infer it from the
|
|
2530
|
+
* presence of the crossRef itself.
|
|
1792
2531
|
*/
|
|
1793
|
-
|
|
2532
|
+
indexed?: boolean;
|
|
1794
2533
|
/**
|
|
1795
|
-
*
|
|
1796
|
-
*
|
|
1797
|
-
* before short ids were allocated).
|
|
2534
|
+
* Metadata: when true, the value may be unset. An unset field reads back as an
|
|
2535
|
+
* absent key, never `null` (`isColumnField`).
|
|
1798
2536
|
*/
|
|
1799
|
-
|
|
2537
|
+
nullable?: boolean;
|
|
1800
2538
|
/**
|
|
1801
|
-
*
|
|
1802
|
-
* a
|
|
1803
|
-
*
|
|
1804
|
-
*
|
|
1805
|
-
*
|
|
1806
|
-
*
|
|
1807
|
-
* - Pg: returns a new `PgDataset` sharing this dataset's `sql` pool +
|
|
1808
|
-
* `edgesStore`. The returned dataset has the SAME `txScopeId` (so it
|
|
1809
|
-
* can participate in cross-namespace batched mutations on the shared pool).
|
|
1810
|
-
* - Memory: returns a new `MemoryDataset` with its own backing `Map`
|
|
1811
|
-
* per the default convention (each instance owns its own substrate). The
|
|
1812
|
-
* returned dataset has a NEW `txScopeId` — it cannot share a transaction
|
|
1813
|
-
* with the caller. Test harnesses that need shared-memory semantics across
|
|
1814
|
-
* namespaces should construct each `MemoryDataset` explicitly with
|
|
1815
|
-
* the relevant constructor option.
|
|
2539
|
+
* Activation-spreading opt-in. When `spread: true`,
|
|
2540
|
+
* recall hits on a row touching this crossRef propagate a damped salience
|
|
2541
|
+
* boost to the linked row (forward direction, X → row X references) AND to
|
|
2542
|
+
* rows whose same field points at the boosted row (backward direction,
|
|
2543
|
+
* X ← rows that reference X). Default off — operators opt in per-edge to
|
|
2544
|
+
* avoid polluting attention with low-signal edges (e.g. Decision.sessionId).
|
|
1816
2545
|
*
|
|
1817
|
-
*
|
|
1818
|
-
*
|
|
1819
|
-
* to derive datasets for *different* namespaces.
|
|
2546
|
+
* Damping (typically 0.3) + depth bound (1) are configured on the recall
|
|
2547
|
+
* substrate, not per-field.
|
|
1820
2548
|
*/
|
|
1821
|
-
|
|
1822
|
-
}
|
|
1823
|
-
interface DatasetRegistry {
|
|
1824
|
-
get(ns: string): Dataset | undefined;
|
|
1825
|
-
has(ns: string): boolean;
|
|
1826
|
-
set(ns: string, dataset: Dataset): void;
|
|
2549
|
+
spread?: boolean;
|
|
1827
2550
|
/**
|
|
1828
|
-
*
|
|
1829
|
-
*
|
|
1830
|
-
*
|
|
2551
|
+
* Cross-TYPE opt-in for the recall expansion path.
|
|
2552
|
+
* Only meaningful when `spread: true` (the SDK `field.crossRef` builder
|
|
2553
|
+
* rejects `expandCrossType` without `spread` at registration). When both
|
|
2554
|
+
* are set, BACKWARD walks via this edge are allowed to surface neighbours
|
|
2555
|
+
* whose type differs from the request's `scope.type` (e.g. a Concept-typed
|
|
2556
|
+
* query surfaces Decisions via inbound `Decision.establishesConcept`).
|
|
1831
2557
|
*
|
|
1832
|
-
*
|
|
1833
|
-
*
|
|
1834
|
-
*
|
|
2558
|
+
* Cross-NAMESPACE expansion is always rejected regardless of this flag.
|
|
2559
|
+
* Forward walks always honour scope strictly: allowing them lets
|
|
2560
|
+
* neighbour-type rows displace the rows that establish them in the ranking.
|
|
2561
|
+
* Default false.
|
|
1835
2562
|
*/
|
|
1836
|
-
|
|
2563
|
+
expandCrossType?: boolean;
|
|
2564
|
+
}
|
|
2565
|
+
interface FieldDefStruct {
|
|
2566
|
+
kind: 'struct';
|
|
2567
|
+
fields: Record<string, FieldDef>;
|
|
2568
|
+
/** Metadata: when true, the value may be `null` or absent. */
|
|
2569
|
+
nullable?: boolean;
|
|
2570
|
+
}
|
|
2571
|
+
interface FieldDefList {
|
|
2572
|
+
kind: 'list';
|
|
2573
|
+
of: FieldDef;
|
|
1837
2574
|
/**
|
|
1838
|
-
*
|
|
1839
|
-
*
|
|
1840
|
-
*
|
|
1841
|
-
*
|
|
1842
|
-
*
|
|
2575
|
+
* When true, the `has` (element membership) operator is backed by a GIN
|
|
2576
|
+
* index on `(body -> '<field>')`. List fields are stored as native JSONB
|
|
2577
|
+
* arrays. Default false — `has` on an unindexed list still works, by
|
|
2578
|
+
* scanning the type's rows. The substrate binary derives the matching GIN
|
|
2579
|
+
* as an idempotent migration at boot from this flag; no hand-authored
|
|
2580
|
+
* migration is needed per field.
|
|
1843
2581
|
*/
|
|
1844
|
-
|
|
2582
|
+
indexed?: boolean;
|
|
2583
|
+
/** Metadata: when true, the value may be `null` or absent. */
|
|
2584
|
+
nullable?: boolean;
|
|
1845
2585
|
}
|
|
2586
|
+
type FieldDef = FieldDefScalar | FieldDefCrossRef | FieldDefStruct | FieldDefList;
|
|
1846
2587
|
/**
|
|
1847
|
-
*
|
|
1848
|
-
*
|
|
1849
|
-
*
|
|
2588
|
+
* True when the field's value is a typed column: a scalar other than `json` that
|
|
2589
|
+
* the server does not own, or a crossRef. An explicit `null` on such a field
|
|
2590
|
+
* reads back as absent. A json, struct or list field keeps its `null`, and a
|
|
2591
|
+
* readonly scalar such as `shortId` is the server's.
|
|
1850
2592
|
*/
|
|
1851
|
-
|
|
1852
|
-
|
|
1853
|
-
|
|
1854
|
-
|
|
1855
|
-
|
|
1856
|
-
|
|
1857
|
-
|
|
1858
|
-
|
|
1859
|
-
/**
|
|
1860
|
-
|
|
2593
|
+
declare function isColumnField(def: FieldDef): boolean;
|
|
2594
|
+
/**
|
|
2595
|
+
* Per-type schema entry. Fields may be declared at registration time; MVP emits
|
|
2596
|
+
* `fields: {}` for types registered without a field map (e.g. mutations whose
|
|
2597
|
+
* shape is inferred from the resolver's return).
|
|
2598
|
+
*/
|
|
2599
|
+
interface TypeSchema {
|
|
2600
|
+
fields: Record<string, FieldDef>;
|
|
2601
|
+
/** The type's natural order; absent means {@link DEFAULT_ORDERED_BY}. */
|
|
2602
|
+
orderedBy?: OrderedBy;
|
|
2603
|
+
/**
|
|
2604
|
+
* Same-namespace crossRefs that point at this type: `field` on `type`.
|
|
2605
|
+
* Where a walk can come from. Absent when none.
|
|
2606
|
+
*/
|
|
2607
|
+
inboundRefs?: Array<{
|
|
2608
|
+
type: string;
|
|
2609
|
+
field: string;
|
|
2610
|
+
}>;
|
|
1861
2611
|
}
|
|
1862
|
-
/**
|
|
1863
|
-
|
|
1864
|
-
|
|
1865
|
-
|
|
1866
|
-
|
|
2612
|
+
/**
|
|
2613
|
+
* A type's natural order: exactly one `{ field: direction }` key, the order a
|
|
2614
|
+
* read with no `orderBy` returns. The datasets still append `id` as the tie-break.
|
|
2615
|
+
*/
|
|
2616
|
+
type OrderedBy = Record<string, 'asc' | 'desc'>;
|
|
2617
|
+
/** Natural order of a type that declares none: newest first. */
|
|
2618
|
+
declare const DEFAULT_ORDERED_BY: OrderedBy;
|
|
2619
|
+
/** The declared natural order, or {@link DEFAULT_ORDERED_BY}. */
|
|
2620
|
+
declare function naturalOrderOf(schema: Pick<TypeSchema, 'orderedBy'>): OrderedBy;
|
|
2621
|
+
/**
|
|
2622
|
+
* Per-mutation schema entry. `params` describes the input shape a client
|
|
2623
|
+
* sends; `returns` describes the shape a client decodes on success. Both are
|
|
2624
|
+
* required — an empty param bag surfaces as `{}`, never as an absent key.
|
|
2625
|
+
*
|
|
2626
|
+
* `returns` is typically a `FieldDefStruct` describing the row shape the
|
|
2627
|
+
* mutation produces (e.g. `create<T>` returns the inserted row; `delete<T>`
|
|
2628
|
+
* returns `{ id, deleted }`). `get<T>` and `update<T>` mark the struct
|
|
2629
|
+
* `nullable: true` because an id-miss legitimately produces `null`.
|
|
2630
|
+
*
|
|
2631
|
+
* Mutations registered without explicit `returns` metadata receive a sentinel
|
|
2632
|
+
* fallback (`{ kind: 'scalar', type: 'string', nullable: true }`) so substrate-pack
|
|
2633
|
+
* can still round-trip the response — clients treating it as "unknown shape"
|
|
2634
|
+
* should fall back to JSON passthrough.
|
|
2635
|
+
*/
|
|
2636
|
+
interface MutationSchema {
|
|
2637
|
+
params: Record<string, FieldDef>;
|
|
2638
|
+
returns: FieldDef;
|
|
1867
2639
|
}
|
|
1868
|
-
|
|
1869
|
-
|
|
1870
|
-
|
|
1871
|
-
|
|
1872
|
-
|
|
1873
|
-
|
|
2640
|
+
/**
|
|
2641
|
+
* The published schema shape surfaced at `GET /substrate/v1/schema`. Spec: §4.2, §6.1,
|
|
2642
|
+
* §7.1. `schemaVersion` is the 12-char SHA-256 prefix over the canonicalized
|
|
2643
|
+
* schema JSON and travels on every response envelope (§7.0) so the client can
|
|
2644
|
+
* detect drift.
|
|
2645
|
+
*/
|
|
2646
|
+
interface Schema {
|
|
2647
|
+
schemaVersion: string;
|
|
2648
|
+
types: Record<string, TypeSchema>;
|
|
2649
|
+
mutations: Record<string, MutationSchema>;
|
|
2650
|
+
/** Present (true) on substrate-contributed virtual namespaces: no autoCRUD, no storage, query/mutate one-shot only. */
|
|
2651
|
+
virtual?: true;
|
|
2652
|
+
/**
|
|
2653
|
+
* The namespace's opaque per-consumer metadata (`defineNamespace` option).
|
|
2654
|
+
* Not part of `schemaVersion`: an annotations-only change does not move it.
|
|
2655
|
+
*/
|
|
2656
|
+
annotations?: Readonly<Record<string, unknown>>;
|
|
1874
2657
|
}
|
|
1875
|
-
/**
|
|
1876
|
-
|
|
1877
|
-
|
|
1878
|
-
|
|
1879
|
-
|
|
1880
|
-
|
|
1881
|
-
|
|
1882
|
-
|
|
1883
|
-
|
|
2658
|
+
/**
|
|
2659
|
+
* Per-key shape. A single frame resolves to `'single' | 'list'`, or for a
|
|
2660
|
+
* walk read to `'count'` (`data[key]` is `{ count }`) or `'groups'`
|
|
2661
|
+
* (`data[key]` is `{ groups, truncated? }`). A batched mutate op-key (array
|
|
2662
|
+
* of frames) resolves to `Array<'single' | 'list'>` — one shape per frame, in
|
|
2663
|
+
* frame-array order. The decoder keys off the discriminator: string → single
|
|
2664
|
+
* frame; array → batched.
|
|
2665
|
+
*/
|
|
2666
|
+
type EnvelopeShape = 'single' | 'list' | 'count' | 'groups' | Array<'single' | 'list'>;
|
|
2667
|
+
/**
|
|
2668
|
+
* The response envelope. Spec: §7.0.
|
|
2669
|
+
*
|
|
2670
|
+
* Query data values are positionally encoded using the client-sent `FieldInput`
|
|
2671
|
+
* selection; mutation data values are positionally encoded using the declared
|
|
2672
|
+
* `MutationSchema.returns` (§4.2) — mutations don't carry a FieldInput
|
|
2673
|
+
* since there's no field selection on a return row.
|
|
2674
|
+
*/
|
|
2675
|
+
interface PackEnvelope {
|
|
2676
|
+
schemaVersion: string;
|
|
2677
|
+
data: Record<string, unknown>;
|
|
2678
|
+
shapes: Record<string, EnvelopeShape>;
|
|
2679
|
+
_meta?: Record<string, unknown>;
|
|
2680
|
+
_pagination?: Record<string, {
|
|
2681
|
+
nextCursor?: string;
|
|
2682
|
+
hasMore: boolean;
|
|
2683
|
+
}>;
|
|
2684
|
+
/**
|
|
2685
|
+
* Per-top-level-key completeness. ABSENT MEANS COMPLETE — callers that
|
|
2686
|
+
* predate this field stay correct without change.
|
|
2687
|
+
*
|
|
2688
|
+
* Set when a bridged key could not be fully resolved (§6.5 "reads never
|
|
2689
|
+
* fail" means such a read still returns 200 with orphan markers). The
|
|
2690
|
+
* per-row `__orphan` marker says a row is missing; this says the RESULT SET
|
|
2691
|
+
* is partial, which a consumer cannot otherwise distinguish from an
|
|
2692
|
+
* genuinely empty result.
|
|
2693
|
+
*/
|
|
2694
|
+
_completeness?: Record<string, {
|
|
2695
|
+
complete: boolean;
|
|
2696
|
+
unreachable?: string[];
|
|
2697
|
+
}>;
|
|
2698
|
+
/**
|
|
2699
|
+
* Non-fatal read diagnostics, keyed by top-level frame key. ABSENT MEANS
|
|
2700
|
+
* NOTHING TO REPORT — callers that predate this field stay correct without
|
|
2701
|
+
* change, same contract as `_completeness`.
|
|
2702
|
+
*
|
|
2703
|
+
* Deliberately NOT `errors`: a consumer doing `if (env.errors) throw` would
|
|
2704
|
+
* start failing on reads that succeeded.
|
|
2705
|
+
*
|
|
2706
|
+
* A client that maps rows into declared interfaces MUST surface this (log,
|
|
2707
|
+
* attach to the result, or throw in development): an unknown projection key
|
|
2708
|
+
* arrives as `null`, satisfies the interface, and the read looks correct.
|
|
2709
|
+
*/
|
|
2710
|
+
_diagnostics?: Record<string, {
|
|
2711
|
+
/**
|
|
2712
|
+
* Projection keys the type does not declare. The read still returned
|
|
2713
|
+
* every row; each unknown key materialises as `null` on all of them,
|
|
2714
|
+
* indistinguishable from a declared field that is null everywhere.
|
|
2715
|
+
*/
|
|
2716
|
+
unknownProjectionFields?: string[];
|
|
2717
|
+
/**
|
|
2718
|
+
* The where-clause reached the substrate without being schema-validated,
|
|
2719
|
+
* because the type is registered but absent from its namespace's
|
|
2720
|
+
* published schema (e.g. runtime-created types). The result is still
|
|
2721
|
+
* correct — substrates refuse a predicate they cannot honour — but the
|
|
2722
|
+
* engine's operator and operand check did not run.
|
|
2723
|
+
*/
|
|
2724
|
+
filterValidationSkipped?: string;
|
|
2725
|
+
/**
|
|
2726
|
+
* A walk-grammar read's clauses, each marked index-served or not
|
|
2727
|
+
* (typed edge walks, goal 7). Annotation only: nothing is refused on
|
|
2728
|
+
* it. Absent on ordinary reads, and when the store has no index plan.
|
|
2729
|
+
*/
|
|
2730
|
+
plan?: PlanClause[];
|
|
2731
|
+
}>;
|
|
2732
|
+
errors?: Array<{
|
|
2733
|
+
message: string;
|
|
2734
|
+
path?: string[];
|
|
2735
|
+
code?: string;
|
|
2736
|
+
/**
|
|
2737
|
+
* Optional structured payload — populated when the underlying error class
|
|
2738
|
+
* carries one (e.g. `ResolverFrameError({ field: '...' })`).
|
|
2739
|
+
*/
|
|
2740
|
+
details?: Record<string, unknown>;
|
|
1884
2741
|
}>;
|
|
1885
|
-
expectedSize?: 'small' | 'large';
|
|
1886
2742
|
}
|
|
2743
|
+
/**
|
|
2744
|
+
* Client-sent field selection tree. Defined here rather than in
|
|
2745
|
+
* `@mnmal-ai/substrate-pack` so subscription and streaming machinery (§5.4, §5.5)
|
|
2746
|
+
* can reference the same shape without adding substrate-pack to their dependency
|
|
2747
|
+
* set — substrate-pack already imports from types, so moving the type upward
|
|
2748
|
+
* avoids the would-be cycle.
|
|
2749
|
+
*/
|
|
2750
|
+
type FieldInput = {
|
|
2751
|
+
[field: string]: true | FieldInput;
|
|
2752
|
+
};
|
|
1887
2753
|
//#endregion
|
|
1888
|
-
export {
|
|
2754
|
+
export { VirtualMutationDef as $, TypeIndexState as $t, KernelLifecycleContext as A, IdentityKind as An, ConditionalUpdateResult as At, NamespaceTypeDef as B, FilterWriteLimits as Bt, EmbedSourceContext as C, EdgesStore as Cn, ResolverArgs as Ct, FilterOperatorDef as D, CLIENT_SUPPLIED_SERVER_FIELD as Dn, WriteEvent as Dt, EngineInput as E, ActorIdentity as En, TypedResolver as Et, KernelRouteClaim as F, WriteRow as Fn, DeriveSpec as Ft, Registry as G, NestedSelection as Gt, PluginRouteContext as H, FilterWriteResult as Ht, McpToolRegistration as I, assertNoRepeatedIds as In, DropResult as It, RegistryEntryInput as J, ReadParams as Jt, RegistryBase as K, OrderByClause as Kt, NamespaceConfig as L, FieldKind as Lt, KernelMigrationContext as M, Row as Mn, Dataset as Mt, KernelNamespaceContribution as N, RowMetadata as Nn, DatasetRegistry as Nt, FrameEntry as O, ClientSuppliedServerFieldError as On, AggFn as Ot, KernelPlugin as P, RowMetadataField as Pn, DeleteResult as Pt, ScheduledTaskContext as Q, TxScopeHandles as Qt, NamespaceDefinition as R, FieldPredicate as Rt, DropParticipant as S, EdgeWriteInput as Sn, Resolver as St, EngineHandle as T, OnMissing as Tn, RowFilterObligation as Tt, PostWriteHook as U, FrameAgg as Ut, PluginLifecycleContext as V, FilterWriteOptions as Vt, QualifiedFrame as W, IndexPlan as Wt, RegistryEntryResolver as X, RefOperand as Xt, RegistryEntryKind as Y, ReadResult as Yt, ScheduledTask as Z, StorageReport as Zt, naturalOrderOf as _, TypeStats as _n, Obligation as _t, FieldDefCrossRef as a, WalkNode as an, RequestObserver as at, CommittedWritesHook as b, EdgePatch as bn, PolicyProbeContext as bt, FieldDefStruct as c, WriteOptions as cn, SubstrateRequest as ct, OrderedBy as d, ResolveObservation as dn, TlsConfig as dt, TypeStorageReport as en, VirtualTypeDef as et, PackEnvelope as f, ResolverStat as fn, WsConnection as ft, isColumnField as g, SlowRequest as gn, Identity as gt, TypeSchema as h, RuntimeMetrics as hn, AutoCrudVerb as ht, FieldDef as i, WalkAggPredicate as in, RequestObservation as it, KernelMigration as j, ROW_METADATA_FIELDS as jn, DEFAULT_FILTER_WRITE_LIMITS as jt, IndexDecl as k, Id as kn, BucketSpec as kt, FieldInput as l, WriteResult as ln, SubstrateResponse as lt, Schema as m, RuntimeErrors as mn, AfterTxWork as mt, Dropped as n, WalkAgg as nn, HttpMethod as nt, FieldDefList as o, WalkPick as on, RuntimeOp as ot, PlanClause as p, RuntimeErrorEntry as pn, WsHandler as pt, RegistryEntry as q, PromotionEvent as qt, EnvelopeShape as r, WalkAggOperand as rn, PluginRouter as rt, FieldDefScalar as s, WhereClause as sn, StartOpts as st, DEFAULT_ORDERED_BY as t, UpdateFieldRef as tn, HttpHandler as tt, MutationSchema as u, ProcessStat as un, SubstrateServer as ut, BatchResolver as v, CanDeleteResult as vn, Policy as vt, EncodeContext as w, OnDelete as wn, ResolverReturn as wt, CoordinatorPlugin as x, EdgeRef as xn, RequestContext as xt, CommittedWriteBatch as y, Edge as yn, PolicyDecision as yt, NamespaceInstallContext as z, FilterCapabilities as zt };
|