@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.
Files changed (39) hide show
  1. package/README.md +4 -2
  2. package/dist/{boot-store-BVqfFxh1.js → boot-store-DHv9H1Gr.js} +170 -69
  3. package/dist/{bridge-Cp4PaIYO.d.ts → bridge-DQyQ6Qhn.d.ts} +1 -1
  4. package/dist/{cli-hSCBywhE.js → cli-_UNdneXr.js} +44 -24
  5. package/dist/client.d.ts +3 -4
  6. package/dist/client.js +3 -3
  7. package/dist/{errors-7mycvNGq.d.ts → errors-xP9Mo7Q1.d.ts} +38 -4
  8. package/dist/{index-DgSfwx7M.d.ts → index-baF5A5jU.d.ts} +1 -1
  9. package/dist/pack.d.ts +2 -2
  10. package/dist/pack.js +1 -1
  11. package/dist/{pg-edges-store-Lxsl5ZnK.js → pg-edges-store-B4FSN9yp.js} +72 -9
  12. package/dist/{plugin-CtwOINCM.js → plugin-BLm5IRdX.js} +2 -2
  13. package/dist/proposals-bootstrap.js +2 -2
  14. package/dist/proposals.d.ts +2 -3
  15. package/dist/proposals.js +1 -1
  16. package/dist/recall-bootstrap.js +2 -2
  17. package/dist/recall.d.ts +10 -11
  18. package/dist/recall.js +2 -2
  19. package/dist/{repl-DqfHelK7.js → repl-DUJGBwie.js} +25 -25
  20. package/dist/{row-BKKCXIG6.d.ts → row-Cu_iRhcR.d.ts} +57 -10
  21. package/dist/{run-B5dTbZ3g.js → run-BpsTNvdI.js} +539 -145
  22. package/dist/{dataset-CejF-Fr_.d.ts → schema-oXfQyo0s.d.ts} +2455 -1589
  23. package/dist/sdk.d.ts +108 -34
  24. package/dist/sdk.js +4 -4
  25. package/dist/{src-CqT-QWZ_.js → src-Bew_JvTo.js} +32 -16
  26. package/dist/{src-Da0t6si5.js → src-Bi3NhEsT.js} +1 -1
  27. package/dist/{src-5SJ5GEIM.js → src-C4t1Gy-m.js} +4844 -1367
  28. package/dist/{src-7CUSMK66.js → src-CHND7-Pm.js} +7 -3
  29. package/dist/src-CSe2tJDf.js +6940 -0
  30. package/dist/{src-Bi849yhn.js → src-CzhKLsOV.js} +175 -91
  31. package/dist/{src-hZb8wfvg.js → src-DWqzrm3O.js} +400 -284
  32. package/dist/substrate-admin.js +1 -1
  33. package/dist/substrate.js +1 -1
  34. package/dist/testing.d.ts +255 -90
  35. package/dist/testing.js +6 -23
  36. package/dist/{ws-ByZyHk7m.d.ts → ws-Dx3A2B4U.d.ts} +2 -3
  37. package/package.json +20 -20
  38. package/dist/schema-DoSc-4ig.d.ts +0 -470
  39. package/dist/src-CyvV7dCK.js +0 -4333
@@ -1,1888 +1,2754 @@
1
- import { C as ActorIdentity, E as Id, M as WriteRow, b as EdgesStore, d as PackEnvelope, f as Schema, k as Row, r as FieldDef, u as OrderedBy } from "./schema-DoSc-4ig.js";
2
- //#region ../../packages/substrate-types/src/policy.d.ts
3
- interface Identity {
4
- id: string;
5
- roles?: string[];
6
- scopes?: string[];
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
- * Per-namespace capabilities — the only grant surface. `{ notes: ['read'],
9
- * tasks: ['read','mutate'] }`; `'*'` is a legal key. Read it through the
10
- * `identity-grant.ts` helpers.
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
- grants: Record<string, string[]>;
21
- [k: string]: unknown;
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
- * Semantic verb stamped on autoCRUD-registered mutation entries.
25
- * Absent on type entries and custom mutations — policies needing those use
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
- type AutoCrudVerb = 'get' | 'create' | 'update' | 'delete';
29
- interface RequestContext {
30
- identity: Identity | null;
31
- namespace: string;
32
- operation: 'query' | 'mutate' | 'subscribe' | 'stream';
33
- now: Date;
34
- headers: Record<string, string>;
35
- meta: Record<string, unknown>;
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
- * Trust-gated client IP computed by the HTTP route handler from the request's
38
- * `peerIp` + the operator-configured trusted-proxy allowlist. When the peer
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
- clientIp?: string;
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
- * Whether the deployment verifies credentials at all, as the transport knows
46
- * it, so a refusal for want of an identity can say whether auth is off
47
- * rather than implying the caller's key is wrong.
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
- * `undefined` means the transport did not say (direct engine unit tests,
50
- * routes with no auth config in scope). Treat it as unknown, never as `false`.
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
- authEnabled?: boolean;
110
+ readonly txScopeId: string;
111
+ write(input: EdgeWriteInput): Promise<Edge>;
53
112
  /**
54
- * The registry entry name this dispatch targets — the `<name>` half of the
55
- * qualified frame key (e.g. `deleteTodo`, `Todo`). Threaded by the engine
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
- entry?: string;
116
+ writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
117
+ tombstone(id: string, at?: Date): Promise<void>;
63
118
  /**
64
- * Semantic verb of the targeted entry when autoCRUD registered it.
65
- * Prefer this over `entry`-name matching for intent-level policies
66
- * ("deny deletes") — it survives entry renames. Absent for type entries
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
- verb?: AutoCrudVerb;
70
- }
71
- /** The caller's request context for a policy check made outside dispatch. */
72
- type PolicyProbeContext = Partial<Pick<RequestContext, 'now' | 'headers' | 'meta' | 'clientIp' | 'authEnabled'>>;
73
- interface ResolverArgs {
74
- params?: Record<string, unknown>;
75
- fields?: Record<string, unknown>;
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
- * Engine-injected per-call dataset handle. On `engine.mutate`, this is the
79
- * transaction-scoped `tx` view (spec §5.3, G1); on `engine.query` it's the
80
- * plain namespace dataset. Resolvers that perform I/O MUST use this handle
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
- dataset?: Dataset;
135
+ findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
136
+ findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
86
137
  /**
87
- * Engine-injected per-call edges store (§4.6). Resolvers that touch edges
88
- * MUST use this handle; the closed-over store from registration is a
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
- edges?: EdgesStore;
141
+ findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
142
+ canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
143
+ findBlocked(): Promise<Edge[]>;
94
144
  /**
95
- * Engine-injected post-commit write hook (§5.4). Write-path resolvers
96
- * (autoCRUD create/update/delete, or custom mutation resolvers) call this
97
- * AFTER their substrate write lands to announce the change. The engine
98
- * collects calls into a per-transaction batch and fans them out to the
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
- onWrite?: (event: WriteEvent) => void;
150
+ findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
104
151
  /**
105
- * Queue work to run once the surrounding transaction has settled, whether it
106
- * committed or rolled back: a record that must outlive a rollback, such as
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
- afterTx?: (fn: AfterTxWork) => void;
155
+ findEdgesTouchingType(namespace: string, type: string, limit: number): Promise<Edge[]>;
112
156
  /**
113
- * Engine-injected cancellation signal (§5.5). Supplied on `stream` dispatch
114
- * so generator resolvers can abort mid-iteration when the client cancels or
115
- * the socket closes. Streaming resolvers SHOULD observe this signal — either
116
- * by calling `signal.throwIfAborted()` at yield points, or by listening for
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
- signal?: AbortSignal;
162
+ namespacesLinkedTo(namespace: string, type?: string): Promise<string[]>;
123
163
  /**
124
- * Engine-injected cross-namespace dataset resolver (committed, non-tx view).
125
- * Write-path resolvers use it to verify crossRef referents that live in a
126
- * DIFFERENT namespace (onMissing:'reject'). Same-namespace targets should use
127
- * the tx-scoped `dataset` handle instead. Absent on the query/subscribe path.
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
- resolveDataset?: (ns: string) => Dataset | undefined;
171
+ dropEdgesByNamespace(namespace: string, within?: readonly string[]): Promise<number>;
130
172
  /**
131
- * Engine-injected on mutate: how many frame entries share this call's
132
- * transaction, itself included. A resolver whose effect waits on other
133
- * transactions (a concurrent index drop) refuses to share one.
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
- txEntries?: number;
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
- * Post-commit write announcement consumed by the engine's subscription bus
139
- * (§5.4). Emitted by write-path resolvers after the substrate operation
140
- * commits inside the current transaction. `row` is the post-commit canonical
141
- * row for creates and updates; for deletes it's the pre-tombstone snapshot
142
- * (absent if the resolver couldn't read the row before deleting). The engine
143
- * filters matching subscriptions by `(ns, type)`, tests the `row` against each
144
- * subscription's `where` predicate, and emits `add` / `update` / `remove`.
145
- */
146
- interface WriteEvent {
147
- ns: string;
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 Obligation {
154
- kind: string;
155
- [k: string]: unknown;
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
- * Row-filter obligation: emitted by `row<T>(predicate)` policies. The engine
159
- * scans accumulated obligations after resolver execution and applies each
160
- * predicate as a silent filter.
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 PolicyDecision {
167
- allow: boolean;
168
- reason?: string;
169
- obligations?: Obligation[];
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
- * Engine-visible return shape for a resolver. `ReadResult` means "paged list";
196
- * `Row[]` means "full list, no pagination"; `Row` means "single"; `null` means
197
- * "single, not found". The engine discriminates at runtime.
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
- type ResolverReturn = Row | Row[] | ReadResult | null;
200
- /** Work queued through `ResolverArgs.afterTx`, told whether the transaction committed. */
201
- type AfterTxWork = (outcome: {
202
- committed: boolean;
203
- }) => Promise<void>;
204
- //#endregion
205
- //#region ../../packages/substrate-types/src/server.d.ts
206
- type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
207
- interface SubstrateRequest {
208
- method: HttpMethod;
209
- path: string;
210
- headers: Record<string, string>;
211
- query: Record<string, string>;
212
- params: Record<string, string>;
213
- body: Buffer | null;
214
- identity?: Identity;
215
- /**
216
- * Remote peer IP observed at the transport layer. Populated by adapters
217
- * (Fastify: `request.ip`; memory: caller supplies via `inject({ peerIp })`).
218
- * Absent when transport doesn't expose it. Consumers that gate on peer IP
219
- * (e.g. `x-forwarded-for` trust) treat `undefined` as "untrusted peer".
220
- */
221
- peerIp?: string;
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
- * Client IP after the trusted-proxy check, stamped by the host before plugin
224
- * and kernel route handlers run. Never read from the client.
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
- clientIp?: string;
227
- /** Whether the deployment verifies credentials, stamped with `clientIp`. */
228
- authEnabled?: boolean;
488
+ cursor?: string;
229
489
  /**
230
- * Per-request abort signal. Production transports (Fastify) wire it to fire
231
- * on socket close (client disconnect) and on `abortAllRequests()` during
232
- * graceful shutdown. Route handlers thread it into `engine.query/mutate`
233
- * via `signal:` so resolvers can cooperatively bail. Optional because
234
- * test fixtures and embedded `inject()` callers may not need cancellation.
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
- signal?: AbortSignal;
509
+ fields?: {
510
+ [field: string]: true | unknown;
511
+ };
237
512
  }
238
- interface SubstrateResponse {
239
- status: number;
240
- headers?: Record<string, string>;
241
- body?: Buffer | Uint8Array | string | ReadableStream;
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
- type HttpHandler = (req: SubstrateRequest) => SubstrateResponse | Promise<SubstrateResponse>;
244
- /** Request op classes counted by the runtime-metrics surface (§ engine-metrics spec). */
245
- type RuntimeOp = 'query' | 'mutate';
246
- /** One observed HTTP request at the transport seam. */
247
- interface RequestObservation {
248
- readonly op: RuntimeOp;
249
- /** Transport-level success — HTTP status < 400. Frame-level envelope errors still count ok. */
250
- readonly ok: boolean;
251
- /** Wall-clock elapsed from handler entry to response, measured via Date.now(). Always >= 0. */
252
- readonly durationMs: number;
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
- type RequestObserver = (o: RequestObservation) => void;
255
- interface WsConnection {
256
- readonly id: string;
257
- send(frame: Buffer | Uint8Array | string): void;
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
- * Transport-level back-pressure seam. Resolves once the
260
- * socket's write buffer is below its high-water mark — immediately when it
261
- * already is. The stream route awaits this between chunks so a fast producer
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
- drain?(): Promise<void>;
267
- onMessage(cb: (frame: Buffer) => void): void;
268
- onClose(cb: (code?: number) => void): void;
269
- close(code?: number, reason?: string): void;
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
- * Register a callback invoked synchronously during graceful server shutdown,
272
- * BEFORE the underlying socket is closed. Higher layers use this to flush
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
- onShutdown?(cb: (reason: string) => void): void;
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 StartOpts {
288
- host?: string;
289
- port?: number;
290
- tls?: TlsConfig;
617
+ interface UpdateFieldRef {
618
+ ns?: string;
619
+ type: string;
620
+ id: Id;
291
621
  }
292
- interface PluginRouter {
293
- get(path: string, handler: HttpHandler): void;
294
- post(path: string, handler: HttpHandler): void;
295
- put(path: string, handler: HttpHandler): void;
296
- delete(path: string, handler: HttpHandler): void;
297
- patch(path: string, handler: HttpHandler): void;
298
- websocket(path: string, handler: WsHandler): void;
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 SubstrateServer {
301
- start(opts?: StartOpts): Promise<{
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
- * Abort every in-flight HTTP request's `req.signal` so resolvers cooperatively
317
- * bail. Used during graceful shutdown to give the engine a chance to roll
318
- * back mutations before fastify's drain timeout fires. WS connections are
319
- * not affected by this call; their teardown rides on socket close.
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
- abortAllRequests(reason?: string): void;
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
- * Register a callback invoked synchronously at the START of `stop()` —
324
- * before in-flight requests are aborted and before the transport drains.
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
- * The HTTP analogue of `WsConnection.onShutdown`, for routes that hold
327
- * a response open indefinitely (SSE): handlers flush a terminal frame and end
328
- * their response, or the drain would wait forever.
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
- * Additive, not last-one-wins (unlike `onError`): a dropped registration is
331
- * a leaked stream. Optional — transports with no graceful phase may omit it,
332
- * and callers must tolerate undefined.
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
- onShutdown?(cb: (reason: string) => void): void;
678
+ dropType(type: string): Promise<DropResult>;
335
679
  /**
336
- * Test-only: invoke the server's handler pipeline without opening a socket.
337
- * Networked implementations may leave this undefined.
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
- inject?(req: Partial<SubstrateRequest>): Promise<SubstrateResponse>;
687
+ dropNamespace(): Promise<DropResult>;
688
+ updateField(ref: UpdateFieldRef, fieldName: string, value: unknown): Promise<void>;
340
689
  /**
341
- * Register a per-request observer for op throughput + latency. Optional —
342
- * transports without instrumentation may omit it. At most one observer; a
343
- * second call replaces the first. The transport invokes it only for the
344
- * `/substrate/v1/query` and `/substrate/v1/mutate` routes.
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
- observeRequests?(observer: RequestObserver): void;
347
- /** Optional: told when a query/mutate HTTP request starts (+1) and ends (-1), including when it throws. */
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
- * Semantic verb for autoCRUD-registered mutations. The engine
383
- * threads this into `RequestContext.verb` at dispatch so type-/plugin-level
384
- * policies can discriminate get/create/update/delete without entry-name
385
- * string matching. Omit for type entries and custom mutations.
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
- verb?: AutoCrudVerb;
388
- }
389
- /**
390
- * Stored shape returned by `Registry.get` and `Registry.all`. Mirrors the
391
- * concrete `RegistryEntry` in `@mnmal-ai/substrate-core` — the engine reads
392
- * `policy`, `kind`, `resolver`, `fields`, `params`, and `returns` off this
393
- * shape on every dispatch.
394
- */
395
- interface RegistryEntry {
396
- resolver: RegistryEntryResolver;
397
- policy: Policy;
398
- fields: Record<string, FieldDef>;
399
- kind: RegistryEntryKind;
400
- /** Always present — `{}` for `kind: 'type'` entries where the concept doesn't apply. */
401
- params: Record<string, FieldDef>;
402
- /** Present only for `kind: 'mutation'` entries that declared a return shape. */
403
- returns?: FieldDef;
404
- /** Mirrors `RegistryEntryInput.orderedBy`. */
405
- orderedBy?: OrderedBy;
406
- /** Mirrors `RegistryEntryInput.indexes`. */
407
- indexes?: IndexDecl[];
408
- /** Mirrors `RegistryEntryInput.expectedSize`. */
409
- expectedSize?: 'small' | 'large';
410
- /** Mirrors `RegistryEntryInput.verb` — present when the registrant stamped one. */
411
- verb?: AutoCrudVerb;
412
- }
413
- /**
414
- * Canonical per-namespace registry surface, implemented by the concrete
415
- * `Registry` class in `@mnmal-ai/substrate-core`.
416
- */
417
- interface Registry {
418
- register(key: string | {
419
- readonly name: string;
420
- }, input: RegistryEntryInput): void;
421
- replace(key: string | {
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
- * Read back a registered entry. Returns undefined when the entry is absent.
426
- * The full `RegistryEntry` shape (resolver, policy, kind, fields, params,
427
- * returns) is exposed because the engine reads every field on dispatch.
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
- get(key: string | {
430
- readonly name: string;
431
- }): RegistryEntry | undefined;
432
- /** Presence check. Returns true iff `key` is registered. */
433
- has(key: string | {
434
- readonly name: string;
435
- }): boolean;
436
- /** Iterate every `[name, entry]` pair. Used by the schema publisher. */
437
- all(): IterableIterator<[string, RegistryEntry]>;
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
- * Remove an entry. Optional: only a registry that can take back a live
440
- * apply (a schema proposal rolled back with its transaction) offers it.
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
- unregister?(key: string | {
443
- readonly name: string;
444
- }): void;
805
+ fieldWarnings?(): Promise<string[]>;
445
806
  /**
446
- * Monotonic mutation counter — incremented by every `register` / `replace` / `unregister`.
447
- * Lets a consumer cache anything derived from the registry (the published
448
- * schema, above all) and detect staleness from the data, without relying on
449
- * every registrant remembering to call `engine.invalidateSchemaCaches`.
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
- * Optional so third-party `Registry` implementations remain valid; consumers
452
- * fall back to callback-driven invalidation when it is absent.
813
+ * OPTIONAL. Backends without per-type storage omit it.
453
814
  */
454
- readonly epoch?: number | undefined;
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
- * Plugin-global policy composed from the owning plugin's `policies` array
514
- * (undefined when the plugin declares none). Namespace install
515
- * implementations SHOULD compose this with any namespace-scoped or per-type
516
- * policies via `and()` so plugin-level invariants apply across every
517
- * resolver the namespace contributes. `defineNamespace` in
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
- pluginPolicy?: Policy;
825
+ typeStats?(): Promise<TypeStats[]>;
521
826
  /**
522
- * Substrate-plugin contributions to per-type postWrite chains. Map
523
- * `typeName → PostWriteHook[]`. Engine populates by walking each
524
- * composed substrate plugin's `contributePostWrites(namespace)` and
525
- * merging results. Hooks run AFTER the type's inline postWrite in
526
- * declaration order. Empty map / undefined = no contributions.
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
- postWriteContributions?: Record<string, PostWriteHook[]>;
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
- * Produce the text fed to the LEXICAL (keyword) index for this row, with the
604
- * same `null` / `undefined` un-indexable sentinel as `embed.source`.
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
- * A sibling of `embed` rather than a flag on it, because the two indexes
607
- * want different text: `embed.source` conventionally takes a short handle
608
- * (`synopsis || body`), which drops proper nouns a keyword index needs.
609
- * `lexical.source` is where the long form goes.
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
- * A type may declare either, both, or neither. Both is the expected shape for
612
- * a store whose handle is shorter than its content.
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
- lexical?: {
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
- * Type definitions registered under this namespace, keyed by type name.
631
- * Read-only metadata exposed for substrate plugins that need to walk
632
- * the type surface at coordinator-namespace install time (e.g.
633
- * substrate-recall reads `types[T].embed?.source` to contribute embedding
634
- * postWrite hooks). Populated by `defineNamespace`; absent on hand-crafted
635
- * `NamespaceDefinition` objects that bypass the SDK helper.
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
- types?: Readonly<Record<string, NamespaceTypeDef>>;
942
+ allocateShortId(type: string): Promise<number>;
638
943
  /**
639
- * Opaque per-consumer metadata, keyed by consumer (e.g. `nl`). Core never
640
- * interprets it; it is passed through to the namespace schema unchanged.
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
- annotations?: Readonly<Record<string, unknown>>;
948
+ bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
643
949
  /**
644
- * Body keys a SQL dataset mirrors into dedicated `rows` columns, so filters
645
- * and sorts on them hit an index. The declaring plugin creates the columns in
646
- * its kernel migrations; the engine creates none. `column` is a bare
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
- promotedColumns?: Readonly<Record<string, {
650
- column: string;
651
- kind: 'boolean' | 'text';
652
- }>>;
954
+ resolveShortId(type: string, shortId: number): Promise<string | null>;
653
955
  /**
654
- * Install types + mutations + policies into the registry. Invoked once at
655
- * registration time, BEFORE the engine is constructed. The plugin owns the
656
- * dataset handle it uses for resolver closures; wiring datasets into the
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
- install(ctx: NamespaceInstallContext): void | Promise<void>;
660
- }
661
- interface PluginLifecycleContext {
960
+ allocateShortIds(type: string, count: number): Promise<number[]>;
662
961
  /**
663
- * Tagged-union discriminant. Differentiates this context from
664
- * the structurally-similar `KernelLifecycleContext` so a coordinator's
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
- readonly lifecycle: 'coordinator';
965
+ bindShortIds(type: string, pairs: ReadonlyArray<{
966
+ shortId: number;
967
+ rowId: string;
968
+ }>): Promise<void>;
671
969
  /**
672
- * Structured metric/log sink — the hosting binary picks the concrete surface
673
- * (stdout JSON, Prometheus counter, OpenTelemetry span, …). Plugins MUST NOT
674
- * assume the sink is synchronous or observable; the contract is fire-and-
675
- * forget per call.
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
- metric(name: string, payload?: unknown): void;
976
+ resolveShortIds(type: string, shortIds: readonly number[]): Promise<ReadonlyMap<number, string>>;
678
977
  /**
679
- * Engine handle threaded into `onStart` so plugins that mutate their
680
- * registry post-construction (e.g. substrate-proposals' applyType /
681
- * applyField paths) can wire `engine.invalidateSchemaCaches(ns)` into
682
- * their replace flow. Engine construction completes before `onStart`
683
- * fires, so the handle is always live here.
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
- engine: EngineHandle;
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
- * Engine-facing input shape for `query` / `mutate` / `subscribe` / `stream`.
689
- * Declared here (rather than in substrate-core) so plugin surfaces can reference
690
- * the engine's call shape as a type without importing the engine package —
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 FrameEntry {
694
- params?: Record<string, unknown>;
695
- fields?: Record<string, unknown>;
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
- * §5.13 dedup key. Present on a mutate frame entry opts the whole frame
698
- * into the engine's idempotency store; a repeat call with the same key
699
- * inside the TTL returns the cached envelope verbatim.
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
- idempotencyKey?: string;
1143
+ grants: Record<string, string[]>;
1144
+ [k: string]: unknown;
702
1145
  }
703
1146
  /**
704
- * Qualified frame (§4.7). Keys are `<ns>/<name>`. `<name>` is the type entry
705
- * name for query, or the mutation name for mutate.
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 QualifiedFrame = Record<string, FrameEntry | Array<FrameEntry>>;
715
- interface EngineInput {
716
- frame: QualifiedFrame;
717
- ctx: Partial<RequestContext>;
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
- * §5.13 cancellation. Threaded into each resolver via `args.signal` so
720
- * resolvers observe cancel by polling `signal.aborted` or registering an
721
- * `abort` listener.
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
- signal?: AbortSignal;
1166
+ clientIp?: string;
724
1167
  /**
725
- * Page bounds for list reads, set by a transport serving remote callers:
726
- * a type read with no `limit` gets `defaultLimit`, one above `maxLimit` is
727
- * refused. Absent for in-process callers, which read what they ask for.
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
- pageLimits?: {
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
- * Marks a substrate-contributed namespace. Virtual namespaces
742
- * have NO dataset: the engine skips the dataset-presence check on
743
- * dispatch and leaves `args.dataset` undefined — resolvers compute from
744
- * `params`/`fields` and MUST NOT reach for a dataset handle. They are
745
- * structurally incapable of autoCRUD/storage — coordinators own data,
746
- * substrate surfaces own computation. Subscribe refuses these namespaces
747
- * with `subscription_unsupported_frame`.
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
- virtual?: boolean;
750
- /** From `NamespaceDefinition.annotations`; surfaced on the schema, never hashed. */
751
- annotations?: Readonly<Record<string, unknown>>;
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
- * Narrow engine handle threaded into scheduled-task / plugin-route contexts.
755
- * The concrete `Engine` class in `@mnmal-ai/substrate-core` satisfies this
756
- * structurally; plugin code binds against this handle without importing the
757
- * engine package.
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
- * Evaluate the read policy for a type entry without dispatching it.
764
- * Out-of-band read surfaces (kernel routes returning row data
765
- * outside frame dispatch — e.g. /substrate/v1/recall) call this so the same
766
- * composed policies that gate `query` gate them too. Fails closed on
767
- * unknown namespace/type and tombstoned namespaces.
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
- evaluateReadPolicy(ns: string, type: string, identity: Identity | null, probe?: PolicyProbeContext): PolicyDecision;
1208
+ dataset?: Dataset;
770
1209
  /**
771
- * Invalidate cached schema outputs after an out-of-band registry mutation
772
- * (e.g. `applyTypeProposal` / `applyFieldProposal` calling
773
- * `Registry.replace`). Without this hook, `federatedSchema()` and
774
- * `schemaFor(ns)` keep returning pre-mutation views. Optional `ns` argument also drops the per-namespace `schemaFor` cache;
775
- * omit to invalidate only the federated outputs.
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
- invalidateSchemaCaches(ns?: string): void;
1216
+ edges?: EdgesStore;
778
1217
  /**
779
- * Register a new namespace at runtime. Throws on collision or on a
780
- * tombstoned name. Used by substrate-proposals' propose_namespace verb to provision
781
- * per-user / per-tenant namespaces without binary restart. Caller (typically
782
- * the resolver) is responsible for FPP semantics; this method is the
783
- * mechanical primitive.
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
- addNamespace(ns: string, config: NamespaceConfig): void;
1226
+ onWrite?: (event: WriteEvent) => void;
786
1227
  /**
787
- * Mark a namespace as tombstoned. After this call:
788
- * - schemaFor(ns) throws `unknown namespace`
789
- * - federatedSchema() omits the ns
790
- * - query / mutate / subscribe against the ns return a per-key
791
- * `namespace_tombstoned` error
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
- tombstoneNamespace(ns: string): void;
1234
+ afterTx?: (fn: AfterTxWork) => void;
802
1235
  /**
803
- * Be told, after the fact, each time a namespace is tombstoned (a drop), so
804
- * a plugin that installed it can retire what it owns. A listener's throw is
805
- * reported as a metric and does not reach the dropper. Returns a disposer.
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
- onNamespaceTombstoned(listener: (ns: string) => void): () => void;
1245
+ signal?: AbortSignal;
808
1246
  /**
809
- * Take part in every namespace drop's transaction: the drop route opens
810
- * `participant.namespaces` in its transaction too and runs `onDrop` after
811
- * the rows are gone and before it commits, so a throw rolls the drop back.
812
- * Returns a disposer.
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
- addDropParticipant(participant: DropParticipant): () => void;
815
- /** The participants `addDropParticipant` registered, for the drop route. */
816
- dropParticipants(): readonly DropParticipant[];
1252
+ resolveDataset?: (ns: string) => Dataset | undefined;
817
1253
  /**
818
- * Take a namespace off the engine and free its name for `addNamespace`.
819
- * Subscriptions on it close, its schema disappears, new ops answer
820
- * `unknown_namespace`; in-flight ops keep their resolved config. Undoes a
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
- removeNamespace(ns: string): void;
824
- /** Whether `ns` is on the engine, and if so whether it is still served. */
825
- namespaceState(ns: string): 'absent' | 'live' | 'tombstoned';
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
- * Construct a fresh empty Registry that the engine can accept via
828
- * `addNamespace`. Plugins call this to provision new namespaces at runtime
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
- createRegistry(): Registry;
1351
+ clientIp?: string;
1352
+ /** Whether the deployment verifies credentials, stamped with `clientIp`. */
1353
+ authEnabled?: boolean;
832
1354
  /**
833
- * Look up the host-registered dataset for a namespace, or `undefined` if the
834
- * host has not provisioned one. Thin pass-through to the engine's
835
- * `DatasetRegistry.get`, surfaced on the handle so plugins running on
836
- * dynamically-added namespaces can resolve datasets without the host having
837
- * to plumb a `datasetFor` lookup through plugin config.
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
- datasetFor(namespace: string): Dataset | undefined;
1361
+ signal?: AbortSignal;
845
1362
  }
846
- /**
847
- * Engine surface needed by substrate-pack-aware route helpers — extends the
848
- * dispatch handle with the two methods compose's `serializeEnvelope` /
849
- * `mutateRoute` need to drive positional encoding. The concrete
850
- * `Engine` class satisfies this structurally; tests + alt
851
- * implementations can satisfy it without depending on the engine package.
852
- */
853
- interface EncodeContext extends EngineHandle {
854
- /** Federated schema map (per-namespace Schema) for substrate-pack encoding. */
855
- federatedSchema(): Record<string, Schema>;
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
- * Look up a namespace's mutation-return registry view. Returns undefined
858
- * when the namespace isn't registered. The mutate route uses this to
859
- * resolve each frame key's `returns` FieldDef for positional encoding.
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
- registryFor(namespace: string): {
862
- get(name: string): {
863
- returns?: FieldDef;
864
- } | undefined;
865
- } | undefined;
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
- * Context threaded into every `ScheduledTask.handler` call.
869
- */
870
- interface ScheduledTaskContext {
871
- /** The owning plugin's `name`. */
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 ScheduledTask {
879
- /** Unique identifier within the plugin. Used in metric labels. */
880
- name: string;
881
- /** Fire interval in milliseconds. Minimum 100ms — smaller throws at register. */
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
- * Context threaded into `CoordinatorPlugin.routes()` calls.
890
- */
891
- interface PluginRouteContext {
892
- /** The owning plugin's `name`. */
893
- pluginName: string;
894
- /** Engine handle for plugin-scoped routes that need to dispatch back through the engine. */
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 CoordinatorPlugin {
900
- name: string;
901
- namespaces: NamespaceDefinition[];
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
- * Plugin's bound contract version: a semver RANGE over the binary version,
904
- * e.g. `'>=4.1.0 <6.0.0'`.
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 ceiling tracks actual compatibility, not the next major: it moves
907
- * only when a major genuinely breaks the plugin-facing interface. A ceiling
908
- * that admits a major which did break lets the plugin load and misbehave
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
- * Enforced at boot: a plugin whose range excludes the running binary is
913
- * refused.
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
- contractVersion: string;
1459
+ onShutdown?(cb: (reason: string) => void): void;
916
1460
  /**
917
- * Plugin-global policies applied to every resolver in every namespace the
918
- * plugin contributes. Composed by the loader via `and(...)` — the combined
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
- policies?: Policy[];
1464
+ inject?(req: Partial<SubstrateRequest>): Promise<SubstrateResponse>;
925
1465
  /**
926
- * Post-register lifecycle hook. Fires after every plugin's `install()`
927
- * resolves — use this for resource priming that needs the full namespace
928
- * map (e.g. cross-plugin edge warmup).
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
- onStart?(ctx: PluginLifecycleContext): void | Promise<void>;
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
- * Pre-shutdown lifecycle hook. Fires when the host calls `compose()`'s
933
- * returned `stop()` (which the binary's SIGTERM handler invokes inside
934
- * the `SUBSTRATE_SHUTDOWN_GRACE_MS` window). Hooks run in REVERSE
935
- * registration order so plugins tear down in the inverse of the order
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
- onStop?(ctx: PluginLifecycleContext): void | Promise<void>;
1520
+ verb?: AutoCrudVerb;
956
1521
  /**
957
- * Scheduled tasks — the binary ticks these on `.unref()`'d intervals.
958
- * Registered with the shared `TaskScheduler` at compose time and started
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
- schedule?: ScheduledTask[];
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
- * Mount plugin-scoped HTTP/WS routes. Called once at compose-time with a
964
- * `PluginRouter` pre-prefixed `/substrate/v1/plugins/<name>` by the server impl. The
965
- * router surface matches `PluginRouter` in `./server.ts`.
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
- routes?(router: PluginRouter, ctx: PluginRouteContext): void | Promise<void>;
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
- * Optional onboarding contribution. When set, the hosting binary's
974
- * `GET /substrate/v1/onboard` aggregates this record under
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
- onboardInstructions?: Record<string, unknown>;
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
- * Substrate-tier plugin. Augments the kernel rather than the agent-facing
986
- * surface. Composes BEFORE coordinator plugins so coordinators can rely on
987
- * substrate registrations being live.
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
- * SubstratePlugins do NOT own data namespaces — that's a CoordinatorPlugin
990
- * concern (a substrate may claim a virtual `kernelNamespace`).
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
- interface KernelPlugin {
993
- /** Unique plugin name. Used in metric labels + collision detection. */
994
- name: string;
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's bound contract version: a semver RANGE over the binary version,
997
- * e.g. `'>=4.1.0 <6.0.0'`. Required on substrate plugins. Checked by
998
- * `composeFromManifests` and REFUSED at boot on mismatch; the
999
- * ceiling tracks actual compatibility rather than the next major boundary.
1000
- * See the note on `CoordinatorPlugin.contractVersion` for both.
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
- contractVersion: string;
1662
+ pluginPolicy?: Policy;
1003
1663
  /**
1004
- * Schema migrations the plugin contributes. Applied in declared order
1005
- * on first install AND on every binary boot (idempotently, gated by
1006
- * the migrations tracking table seeded by the first KernelPlugin
1007
- * to populate this slot).
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
- migrations?: KernelMigration[];
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
- * Names of the tables (in the store's schema) this plugin keeps data in.
1012
- * `substrate-admin migrate-store` copies them alongside the engine's own
1013
- * tables and refuses a source table that nothing declares.
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
- storeTables?: readonly string[];
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
- * Filter operators contributed to the where-clause grammar. Each entry
1018
- * registers a custom operator (e.g. `embeddingSimilar`) the engine's
1019
- * query validator + substrate executor can dispatch to.
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
- filterOperators?: Record<string, FilterOperatorDef>;
1779
+ types?: Readonly<Record<string, NamespaceTypeDef>>;
1022
1780
  /**
1023
- * Top-level kernel route claims. Plugin reserves a path under /substrate/v1/.
1024
- * First-claim wins; collision = boot refusal with actionable error.
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
- kernelRoutes?: KernelRouteClaim[];
1784
+ annotations?: Readonly<Record<string, unknown>>;
1027
1785
  /**
1028
- * Top-level MCP tool registrations. Tool name registers globally with
1029
- * the MCP server (no /plugins/ prefix on MCP — tools are flat).
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
- mcpTools?: McpToolRegistration[];
1791
+ promotedColumns?: Readonly<Record<string, {
1792
+ column: string;
1793
+ kind: 'boolean' | 'text';
1794
+ }>>;
1032
1795
  /**
1033
- * Frame-surface contribution. Claims one namespace in the engine registry
1034
- * carrying resolver-backed query types + mutations — no dataset, no
1035
- * autoCRUD. Dispatch/policy/idempotency/pack/schema/NL/MCP all inherit from
1036
- * the normal frame path.
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
- kernelNamespace?: KernelNamespaceContribution;
1801
+ install(ctx: NamespaceInstallContext): void | Promise<void>;
1802
+ }
1803
+ interface PluginLifecycleContext {
1039
1804
  /**
1040
- * Post-register lifecycle hook. Fires after every KernelPlugin's
1041
- * migrations + registrations resolve, BEFORE any coordinator plugin
1042
- * composes. Use for resource priming the kernel needs before
1043
- * coordinators arrive.
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
- onKernelReady?(ctx: KernelLifecycleContext): void | Promise<void>;
1812
+ readonly lifecycle: 'coordinator';
1046
1813
  /**
1047
- * Stops whatever `onKernelReady` started (timers, workers). The host calls
1048
- * it before it closes the store, and may call it more than once.
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
- onKernelStop?(): void | Promise<void>;
1819
+ metric(name: string, payload?: unknown): void;
1051
1820
  /**
1052
- * Contribute postWrite hooks for a coordinator namespace at install time.
1053
- * Called by the engine ONCE per registered coordinator namespace, AFTER
1054
- * substrate composition completes. Returned hooks are merged into the
1055
- * type's effective postWrite chain alongside the type's own inline
1056
- * `postWrite` (if any). Substrate-supplied hooks run AFTER the type's
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
- contributePostWrites?: (namespace: NamespaceDefinition) => Record<string, PostWriteHook>;
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
- interface KernelMigrationContext {
1077
- /**
1078
- * Direct SQL handle for postgres-backed deployments; null when the
1079
- * binary is running against the in-memory dataset.
1080
- */
1081
- sql: unknown | null;
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
- * How `rows` is stored: `'partitioned'` (LIST(namespace) then LIST(type)) or
1084
- * `'legacy'` (one plain table). `null` on the in-memory dataset. PG refuses
1085
- * a unique index on a partitioned parent unless it includes every partition
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
- layout: 'legacy' | 'partitioned' | null;
1089
- metric(name: string, payload?: unknown): void;
1843
+ idempotencyKey?: string;
1090
1844
  }
1091
1845
  /**
1092
- * Where-clause operator extension.
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
- * `execute` is awaited by the pre-resolve pass (`@mnmal-ai/substrate-filter`'s
1098
- * `preResolveExtensionOperatorsDetailed`) and must resolve to an ordered,
1099
- * scored `{ hits: [{ id: string; score: number; vector?: number[] }, ...] }`
1100
- * envelope; any other shape throws `ExtensionOperatorResultError`. Relevance
1101
- * order is preserved in the rewritten `id IN`, and score/vector are surfaced
1102
- * via the pre-pass meta side-channel for the datasets to stitch onto rows.
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
- interface FilterOperatorDef {
1105
- validate(value: unknown): {
1106
- ok: true;
1107
- value: unknown;
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
- * Computed projection field names the operator contributes per hit (e.g.
1115
- * `['_score', '_vector']`). The engine refuses a projection of one of these
1116
- * fields unless its operator is in the where-clause.
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
- computedFields?: string[];
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
- * Query-only virtual type contributed by a substrate plugin.
1122
- * `fields` reuses the FieldDef DSL so schema publication + client typing
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 VirtualTypeDef {
1128
- fields: Record<string, FieldDef>;
1129
- resolver: RegistryEntryResolver;
1130
- }
1131
- /** Mutation contributed by a substrate plugin under its virtual namespace. */
1132
- interface VirtualMutationDef {
1133
- resolver: RegistryEntryResolver;
1134
- /** Optional params schema published into the namespace schema. */
1135
- params?: Record<string, FieldDef>;
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
- * A substrate plugin's claimed frame surface.
1139
- * Registered into the engine's namespaces map as `{ registry, virtual: true }`.
1140
- * Collision posture mirrors KernelRouteClaim: second claim = boot refusal.
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 KernelNamespaceContribution {
1901
+ interface CommittedWriteBatch {
1143
1902
  namespace: string;
1144
- types?: Record<string, VirtualTypeDef>;
1145
- mutations?: Record<string, VirtualMutationDef>;
1903
+ type: string;
1904
+ operation: 'create' | 'update' | 'delete';
1905
+ actor: ActorIdentity | null;
1906
+ ids: readonly Id[];
1146
1907
  }
1147
- /** Top-level kernel route reservation. */
1148
- interface KernelRouteClaim {
1149
- path: string;
1150
- method: HttpMethod;
1151
- handler: HttpHandler;
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
- * Capability the host must check before dispatching, when auth is enabled.
1154
- * REQUIRED — `'public'` is how a route opts out, so opting out is a
1155
- * declaration rather than an omission.
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
- * Do not make this optional: kernel routes mount via the host's raw
1158
- * `server.route`, which applies no gate of its own, so a route with no
1159
- * capability would get no auth wrapper at all.
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
- capability: 'read' | 'mutate' | 'admin' | 'public';
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
- * Tagged-union discriminant. Differentiates this context from the
1173
- * structurally-similar `PluginLifecycleContext`, which would otherwise be
1174
- * interchangeable under structural typing.
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
- readonly lifecycle: 'kernel';
1976
+ onNamespaceTombstoned(listener: (ns: string) => void): () => void;
1177
1977
  /**
1178
- * Direct SQL handle; null when the binary runs against the in-memory
1179
- * dataset. Same shape and same null semantics as
1180
- * `KernelMigrationContext.sql`.
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
- sql: unknown | null;
1983
+ addDropParticipant(participant: DropParticipant): () => void;
1984
+ /** The participants `addDropParticipant` registered, for the drop route. */
1985
+ dropParticipants(): readonly DropParticipant[];
1186
1986
  /**
1187
- * Namespaces DECLARED by the coordinator plugins this binary loaded, in
1188
- * load order. Empty when none are configured.
1189
- *
1190
- * Declared, not installed: coordinators compose AFTER substrate, so the
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
- coordinatorNamespaces: readonly string[];
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
- * The same namespaces, attributed to the coordinator that declared each.
1199
- * Declaration order preserved within a plugin.
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
- coordinatorNamespacesByPlugin?: readonly {
1211
- plugin: string;
1212
- namespace: string;
1213
- }[];
2000
+ createRegistry(): Registry;
1214
2001
  /**
1215
- * Whether this boot may start background work (timers, backfills). False
1216
- * when the host boots the store only to prepare or copy into it, as
1217
- * `substrate-admin migrate-store` does: do convergent reconciliation, start
1218
- * nothing that writes later.
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
- background: boolean;
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
- * Handles yielded by `Dataset.withScopedTransaction`. Contains the
1336
- * tx-bound dataset for every requested namespace plus (optionally) a
1337
- * tx-bound edges store enlisted into the same substrate transaction.
1338
- * See `withScopedTransaction` JSDoc for the `edges` contract.
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 TxScopeHandles {
1341
- datasets: Map<string, Dataset>;
1342
- edges: EdgesStore | null;
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
- * A leaf predicate on a single field. At most one operator per call-site is
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 FieldPredicate {
1355
- eq?: number | string | boolean | Date | null;
1356
- neq?: number | string | boolean | Date | null;
1357
- gt?: number | string | Date;
1358
- gte?: number | string | Date;
1359
- lt?: number | string | Date;
1360
- lte?: number | string | Date;
1361
- between?: [number | string | Date, number | string | Date];
1362
- in?: Array<number | string | boolean | Date>;
1363
- nin?: Array<number | string | boolean | Date>;
1364
- contains?: string;
1365
- startsWith?: string;
1366
- endsWith?: string;
1367
- has?: number | string | boolean | Date | null;
1368
- path?: string[];
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
- * A where clause is either a logical combinator OR a map of field names to
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 OrderByClause {
1391
- [field: string]: 'asc' | 'desc';
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 ReadParams {
1394
- id?: Id;
1395
- ids?: Id[];
1396
- includeDeleted?: boolean;
1397
- where?: WhereClause;
1398
- orderBy?: OrderByClause[];
1399
- limit?: number;
2068
+ interface CoordinatorPlugin {
2069
+ name: string;
2070
+ namespaces: NamespaceDefinition[];
1400
2071
  /**
1401
- * Opaque cursor produced by a prior `read()` call. Base64url-encoded JSON
1402
- * (server-built, server-consumed). Callers should treat it as a black box.
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
- cursor?: string;
2084
+ contractVersion: string;
1405
2085
  /**
1406
- * Optional caller-supplied projection hint. Substrates MAY use this to
1407
- * narrow the body keys they materialise from storage — e.g. PgDataset
1408
- * builds a `jsonb_build_object(...)` projection over only the requested
1409
- * top-level body keys, saving wire + parse bandwidth.
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
- * When present, ONLY top-level entries are honoured (the value can be `true`
1412
- * or a nested FieldInput-shaped object — the substrate treats both as
1413
- * "include this key"). Nested projection inside JSONB sub-trees is intentionally
1414
- * out of scope; the pack codec already prunes deeper. Row-metadata-style keys
1415
- * (`_metadata`, `shortId`, `_deletedAt`, `id`) are populated from dedicated
1416
- * columns regardless of `fields` and never need to be included here.
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
- * When absent, substrates return the full body, for raw `dataset.read()`
1419
- * callers (sweep, compose registry, migration scripts) that don't know which
1420
- * body keys they'll need downstream.
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
- * Substrates MAY ignore this hint — it's a perf optimisation, not a contract.
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
- fields?: {
1426
- [field: string]: true | unknown;
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
- * Paged result of a `read()` call. `rows` is always present; `nextCursor` is
1431
- * present iff `hasMore` is `true` and the current page is non-empty.
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 ReadResult {
1434
- rows: Row[];
1435
- nextCursor?: string;
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
- * One per written row, in input order: a supplied id verbatim, otherwise
1442
- * the id the dataset assigned. Under `insertOnly`, skipped rows are absent.
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
- ids: Id[];
2177
+ contractVersion: string;
1445
2178
  /**
1446
- * Merged rows after upsert — substrates populate this with the post-merge
1447
- * row state so autoCRUD update can skip its post-read. Order
1448
- * matches `ids` (one entry per input row). Substrates that can't compute
1449
- * the merged shape cheaply may emit input rows verbatim; consumers must
1450
- * not rely on body keys absent from the input being filled in.
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
- rows: Row[];
2263
+ layout: 'tables' | null;
2264
+ metric(name: string, payload?: unknown): void;
1453
2265
  }
1454
2266
  /**
1455
- * Optional 3rd-arg to `dataset.write` / `tx.write`. When the incoming row's
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
- * On upsert collision, `created_*` columns preserve existing values (immutability);
1461
- * `updated_*` columns adopt the new values (bump intent). Engine path
1462
- * (`autocrud-create`/`autocrud-update`) constructs full `_metadata` itself —
1463
- * this auto-fill is purely a safety net for raw-write bypass paths.
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 WriteOptions {
1466
- readonly identity?: ActorIdentity;
1467
- readonly now?: Date;
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
- * Insert only: a row whose id already exists (live or tombstoned) is left
1470
- * untouched and omitted from the result's `ids` and `rows`. The existence
1471
- * check and the insert are one atomic step.
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
- readonly insertOnly?: boolean;
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
- * Dataset-declared filter capabilities. §5.2 capability negotiation: the engine
1487
- * validates every where-clause leaf against `operators[fieldKind]` and rejects
1488
- * ops the dataset can't execute rather than returning a silently wrong result.
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
- type FieldKind = 'scalar.number' | 'scalar.string' | 'scalar.boolean' | 'scalar.date' | 'scalar.json' | 'crossRef' | 'list';
1491
- interface FilterCapabilities {
1492
- operators: Record<FieldKind, string[]>;
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
- interface UpdateFieldRef {
1499
- ns?: string;
1500
- type: string;
1501
- id: Id;
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
- * Outcome of a `conditionalUpdate` call (spec §5.12 Phase 2 / Dispatch B).
1505
- *
1506
- * `matched: true` when the row existed AND every key in `match` equalled the
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 ConditionalUpdateResult {
1513
- matched: boolean;
1514
- row: Row | null;
2317
+ interface KernelNamespaceContribution {
2318
+ namespace: string;
2319
+ types?: Record<string, VirtualTypeDef>;
2320
+ mutations?: Record<string, VirtualMutationDef>;
1515
2321
  }
1516
- interface Dataset {
1517
- readonly namespace: string;
2322
+ /** Top-level kernel route reservation. */
2323
+ interface KernelRouteClaim {
2324
+ path: string;
2325
+ method: HttpMethod;
2326
+ handler: HttpHandler;
1518
2327
  /**
1519
- * Stable identifier for the storage substrate this dataset wraps. Two
1520
- * datasets share a substrate when their `txScopeId` values are `===`
1521
- * — they can participate in a single transaction via the engine's
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
- * Datasets with different `txScopeId` values CANNOT participate in a
1534
- * single transaction — the engine refuses mixed-substrate batched
1535
- * mutates with `cross_tx_scope_refused`.
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
- readonly txScopeId: string;
1538
- read(type: string, params: ReadParams): Promise<ReadResult>;
1539
- write(type: string, rows: WriteRow[], options?: WriteOptions): Promise<WriteResult>;
1540
- tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
1541
- purge(type: string, ids: Id[]): Promise<DeleteResult>;
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
- * Physically delete every row of `type` within this dataset's namespace,
1544
- * plus every short-id allocation for that type. Ignores `_deletedAt` /
1545
- * `archived` state — drop is hard-delete regardless of row status.
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
- dropType(type: string): Promise<DropResult>;
2351
+ readonly lifecycle: 'kernel';
1560
2352
  /**
1561
- * Physically delete every row AND short-id for `this.namespace`, across
1562
- * every type. Equivalent to calling `dropType` for each distinct type
1563
- * seen in storage, but substrate impls SHOULD use a single bulk DELETE
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
- * Same atomicity rules as `dropType`. Same "ignores archived state".
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
- dropNamespace(): Promise<DropResult>;
1569
- updateField(ref: UpdateFieldRef, fieldName: string, value: unknown): Promise<void>;
2360
+ sql: unknown | null;
1570
2361
  /**
1571
- * Atomic compare-and-update by PK. If the row `(type, id)` exists AND every
1572
- * `(field, value)` pair in `match` equals the stored row's field, apply the
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
- * Motivating use case: the `_system` register route consumes a one-shot
1592
- * invite — the invite row's `consumedAt` must transition from `null` to a
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
- * Metadata: a successful match unconditionally bumps `updatedAt` to `now`
1596
- * (a server-set `now()` when omitted) and stamps `updatedBy` with the supplied `actor` (or
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
- conditionalUpdate(type: string, id: Id, match: Record<string, unknown>, updates: Record<string, unknown>, actor?: ActorIdentity, now?: Date): Promise<ConditionalUpdateResult>;
1602
- readonly capabilities: FilterCapabilities;
2371
+ coordinatorNamespaces: readonly string[];
1603
2372
  /**
1604
- * Run `fn` while holding a mutual-exclusion lock named `key`, waiting until
1605
- * it is free. Excludes every other holder of the same key on this substrate:
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
- * OPTIONAL. Callers feature-detect and fall back to a process-local lock.
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
- * @returns whatever `fn` resolves to
1616
- * @throws whatever `fn` throws, after the lock is released
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
- withAdvisoryLock?<T>(key: string, fn: () => Promise<T>): Promise<T>;
2385
+ coordinatorNamespacesByPlugin?: readonly {
2386
+ plugin: string;
2387
+ namespace: string;
2388
+ }[];
1619
2389
  /**
1620
- * Prepare dedicated storage for `type` in this namespace, moving any rows
1621
- * already written for it there. Idempotent, and safe beside concurrent
1622
- * reads and writes: no row is lost, duplicated or seen twice. That holds for
1623
- * READ COMMITTED readers; a REPEATABLE READ snapshot taken before the move
1624
- * can miss the moved rows. Also builds the type's indexes, including its
1625
- * declared `indexes`, and throws when a unique one cannot be built.
1626
- *
1627
- * `indexes` picks which: `unique` builds only the unique ones and leaves the
1628
- * rest `pending`, for a later `nonUnique` call to build. `signal` cancels an
1629
- * in-flight non-unique build, which the next call retries. Default `all`.
1630
- *
1631
- * OPTIONAL. Backends without per-type storage omit it.
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
- ensureTypeStorage?(type: string, opts?: {
1634
- indexes?: 'all' | 'unique' | 'nonUnique';
1635
- signal?: AbortSignal;
1636
- }): Promise<void>;
2428
+ kind: 'filter' | 'order';
2429
+ }
2430
+ interface FieldDefScalar {
2431
+ kind: 'scalar';
1637
2432
  /**
1638
- * Where `type`'s rows live and how its declared indexes stand, read from the
1639
- * catalog without building anything.
1640
- *
1641
- * OPTIONAL. Backends without per-type storage omit it.
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
- describeStorage?(type: string): Promise<TypeStorageReport>;
2438
+ type: 'string' | 'number' | 'boolean' | 'date' | 'json';
1644
2439
  /**
1645
- * The database-wide storage layout and what an operator should look at:
1646
- * rows parked in DEFAULT partitions, indexes and CHECK constraints on the
1647
- * `rows` parent, indexes this process has yet to build or failed to build,
1648
- * and a partition count over `partitionBudget`; and, as `info`, engine
1649
- * indexes no longer declared and open index recommendations. Never changes
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
- storageReport?(opts: {
1655
- partitionBudget: number;
1656
- }): Promise<StorageReport>;
2446
+ indexed?: boolean;
1657
2447
  /**
1658
- * Table and index statistics for every type the store holds, every
1659
- * namespace, read from the database's own statistics. Estimates, never a
1660
- * count. Never changes anything.
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
- typeStats?(): Promise<TypeStats[]>;
2452
+ nullable?: boolean;
1665
2453
  /**
1666
- * The indexes the engine wants for `namespace`/`type` (any namespace, not
1667
- * only this one), with each one's leading keys, and the type's size hint.
1668
- * Undefined when the type is unknown. Never changes anything.
1669
- *
1670
- * OPTIONAL. Backends that build no indexes omit it.
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
- indexPlan?(type: string, namespace: string): Promise<IndexPlan | undefined>;
2460
+ readonly?: boolean;
1673
2461
  /**
1674
- * Drop index `name` of this namespace's `type`, a signed `propose_index`
1675
- * remove. Only an engine-owned, non-unique index the engine no longer wants
1676
- * (a leftover or a retracted declaration) is dropped; anything else is
1677
- * refused with an error whose `code` is `unknown_index`, `not_engine_owned`,
1678
- * `unique_index` or `still_desired`, and nothing is dropped. A drop that
1679
- * waits longer than `lockTimeoutMs` on another transaction is abandoned with
1680
- * `index_drop_timeout`; the index may then be left invalid, and a retry drops it.
1681
- *
1682
- * OPTIONAL. Backends that build no indexes omit it (the memory dataset):
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
- dropEngineIndex?(type: string, name: string, opts?: {
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
- * Drop the engine-owned indexes of this namespace, after a namespace drop
1694
- * has committed: its types leave the engine, so nothing would remove them.
1695
- * Non-unique ones only, unless `unique`, which the caller passes only when
1696
- * the namespace is declared nowhere (in no code and no live proposal): a
1697
- * declared namespace's types come back, and until the reconciler rebuilds a
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
- dropNamespaceIndexes?(opts?: {
1706
- unique?: boolean;
1707
- }): Promise<string[]>;
2480
+ enum?: readonly string[];
1708
2481
  /**
1709
- * The entry of this namespace's `type`'s declared `indexes` whose index is
1710
- * named `name`, or undefined when no declaration builds it (a derived or
1711
- * engine index, or none). `propose_index remove` retracts it when it is a
1712
- * proposed type's. Never changes anything.
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
- indexDeclarationOf?(type: string, name: string): Promise<IndexDecl | undefined>;
2488
+ aliases?: Readonly<Record<string, string>>;
1717
2489
  /**
1718
- * Execute `fn` atomically. All ops performed on the `tx` argument run inside
1719
- * one substrate transaction. If `fn` throws or returns a rejected promise,
1720
- * every mutation inside the callback rolls back. If `fn` resolves, the
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
- withTransaction<T>(fn: (tx: Dataset) => Promise<T>): Promise<T>;
2494
+ strict?: boolean;
1734
2495
  /**
1735
- * Engine-only. Open a substrate-level transaction spanning multiple
1736
- * namespaces on the same substrate, and invoke `fn` with a handles object
1737
- * containing tx-bound datasets + (optionally) a tx-bound `EdgesStore`.
1738
- * Called by the engine's mutate path (spec §5.3) for both single-ns and
1739
- * cross-ns frames — the engine calls with `[ns]` for the single-ns case.
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
- withScopedTransaction?<T>(namespaces: ReadonlyArray<string>, fn: (handles: TxScopeHandles) => Promise<T>): Promise<T>;
2502
+ implies?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
1771
2503
  /**
1772
- * Allocate the next short id for the given type within this dataset's
1773
- * namespace. Monotonic per (namespace, type). Does NOT record any
1774
- * row-id mapping — call `bindShortId` after the row is written.
1775
- *
1776
- * The implementation may use the dataset's current tx handle so the
1777
- * sequence advance rolls back on tx rollback (postgres sequences
1778
- * actually never roll back, but the surrounding tx semantics match
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
- allocateShortId(type: string): Promise<number>;
2512
+ default?: string | number | boolean;
2513
+ }
2514
+ interface FieldDefCrossRef {
2515
+ kind: 'crossRef';
2516
+ ns: string;
2517
+ type: string;
2518
+ onDelete: OnDelete;
1782
2519
  /**
1783
- * Record the (shortId → rowId) pairing after the row is written.
1784
- * Called by autoCRUD create immediately after the dataset write()
1785
- * returns the new row id. Safe to call within the enclosing tx.
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
- bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
2526
+ onMissing?: OnMissing;
1788
2527
  /**
1789
- * Resolve a short id to the underlying row id, or null if no such short
1790
- * id exists for this (namespace, type). Does not join `rows` —
1791
- * callers chain their own `read()` after resolution.
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
- resolveShortId(type: string, shortId: number): Promise<string | null>;
2532
+ indexed?: boolean;
1794
2533
  /**
1795
- * Inverse of `resolveShortId` — look up the short id assigned to a
1796
- * given row id. Returns null if no sidecar entry exists (e.g. rows written
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
- getShortIdForRow(type: string, rowId: string): Promise<number | null>;
2537
+ nullable?: boolean;
1800
2538
  /**
1801
- * Spawn a sibling dataset bound to the same backing store but scoped to
1802
- * a different namespace. Used by `compose()` to auto-allocate per-namespace
1803
- * datasets when a coordinator plugin claims a namespace the operator hasn't
1804
- * mapped explicitly.
1805
- *
1806
- * Substrate semantics:
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
- * Idempotency note: callers SHOULD NOT call `forNamespace(this.namespace)`;
1818
- * the resulting object's identity is implementation-defined. Use this only
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
- forNamespace(namespace: string): Dataset;
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
- * Observe namespace lifecycle events (§6.4). Fires when a namespace is
1829
- * disposed — explicit unregister or substrate-signalled loss (memory-backed
1830
- * restart). Returns a disposer that unsubscribes when invoked.
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
- * Optional: registries over persistent substrates (pg) never lose namespaces
1833
- * at runtime and can omit this surface entirely. Consumers MUST feature-
1834
- * detect before subscribing.
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
- onNamespaceLost?(listener: (ns: string) => void): () => void;
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
- * Explicitly drop `ns` from the registry and fire `onNamespaceLost`
1839
- * listeners synchronously. Disposing an unregistered namespace is a silent
1840
- * no-op — keeps graceful-shutdown replays idempotent.
1841
- *
1842
- * Optional: same rationale as `onNamespaceLost`.
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
- dispose?(ns: string): void;
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
- * One declared index of a type and its state: as the catalog holds it, or,
1848
- * while this process defers or runs its build, `pending`, `building` or
1849
- * `failed`. Filters on an index that is not `valid` scan.
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
- interface TypeIndexState {
1852
- name: string;
1853
- fields: string[];
1854
- unique: boolean;
1855
- state: 'valid' | 'building' | 'pending' | 'invalid' | 'failed';
1856
- outcome: 'created' | 'adopted' | 'swapped' | 'unchanged';
1857
- /** Why a `failed` index failed: an error code, then a short reason. */
1858
- error?: string;
1859
- /** Why a `pending` index was not built: the free-disk check refused it. */
1860
- reason?: 'insufficient_disk';
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
- /** Where a type's rows live: `partition` is set on the partitioned layout once the type has one. */
1863
- interface TypeStorageReport {
1864
- layout: 'legacy' | 'partitioned';
1865
- partition?: string;
1866
- indexes: TypeIndexState[];
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
- interface StorageReport {
1869
- /** `unknown` when the report itself failed. */
1870
- layout: 'legacy' | 'partitioned' | 'unknown';
1871
- warnings: string[];
1872
- /** Worth showing, not a fault: the doctor prints these without failing. */
1873
- info?: string[];
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
- /** See `Dataset.indexPlan`. */
1876
- interface IndexPlan {
1877
- /** Each desired index, its keys in order: a derived index ends with the type's natural order. */
1878
- indexes: Array<{
1879
- name: string;
1880
- keys: Array<[string, 'asc' | 'desc']>;
1881
- unique: boolean;
1882
- /** A partial index's predicate beyond `live`: it serves only reads that `eq` each field to its value. */
1883
- only?: Record<string, boolean | null>;
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 { Registry as $, DropParticipant as A, Resolver as At, KernelMigrationContext as B, ResolverStat as C, AutoCrudVerb as Ct, SlowRequest as D, PolicyDecision as Dt, RuntimeMetrics as E, Policy as Et, FilterOperatorDef as F, WriteEvent as Ft, NamespaceConfig as G, KernelPlugin as H, FrameEntry as I, NamespaceTypeDef as J, NamespaceDefinition as K, IndexDecl as L, EncodeContext as M, ResolverReturn as Mt, EngineHandle as N, RowFilterObligation as Nt, TypeStats as O, PolicyProbeContext as Ot, EngineInput as P, TypedResolver as Pt, QualifiedFrame as Q, KernelLifecycleContext as R, ResolveObservation as S, AfterTxWork as St, RuntimeErrors as T, Obligation as Tt, KernelRouteClaim as U, KernelNamespaceContribution as V, McpToolRegistration as W, PluginRouteContext as X, PluginLifecycleContext as Y, PostWriteHook as Z, UpdateFieldRef as _, SubstrateResponse as _t, DropResult as a, ScheduledTask as at, WriteResult as b, WsConnection as bt, FilterCapabilities as c, VirtualTypeDef as ct, ReadParams as d, PluginRouter as dt, RegistryBase as et, ReadResult as f, RequestObservation as ft, TypeStorageReport as g, SubstrateRequest as gt, TypeIndexState as h, StartOpts as ht, DeleteResult as i, RegistryEntryResolver as it, EmbedSourceContext as j, ResolverArgs as jt, CoordinatorPlugin as k, RequestContext as kt, IndexPlan as l, HttpHandler as lt, TxScopeHandles as m, RuntimeOp as mt, Dataset as n, RegistryEntryInput as nt, FieldKind as o, ScheduledTaskContext as ot, StorageReport as p, RequestObserver as pt, NamespaceInstallContext as q, DatasetRegistry as r, RegistryEntryKind as rt, FieldPredicate as s, VirtualMutationDef as st, ConditionalUpdateResult as t, RegistryEntry as tt, OrderByClause as u, HttpMethod as ut, WhereClause as v, SubstrateServer as vt, RuntimeErrorEntry as w, Identity as wt, ProcessStat as x, WsHandler as xt, WriteOptions as y, TlsConfig as yt, KernelMigration as z };
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 };