@mnmal-ai/substrate 0.0.0 → 1.0.0-alpha.0

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 (46) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +118 -1
  3. package/dist/agent-token-BIboWOU0.js +200 -0
  4. package/dist/client.d.ts +782 -0
  5. package/dist/client.js +7 -0
  6. package/dist/cluster-worker.js +35 -0
  7. package/dist/content-type-C7T28xNb.js +25 -0
  8. package/dist/dataset-BXkus75W.js +1527 -0
  9. package/dist/env-utils-B7SGmoeJ.js +21 -0
  10. package/dist/errors-D4vKuwz8.d.ts +130 -0
  11. package/dist/fake-DUVtKVSE.js +36 -0
  12. package/dist/index-D7mSOFlM.d.ts +69 -0
  13. package/dist/pack.d.ts +192 -0
  14. package/dist/pack.js +5 -0
  15. package/dist/plugin-j1jt1l3n.js +3844 -0
  16. package/dist/plugin-t2g2wX0b.d.ts +1568 -0
  17. package/dist/proposals-bootstrap.js +37 -0
  18. package/dist/proposals.config.schema.json +20 -0
  19. package/dist/proposals.d.ts +118 -0
  20. package/dist/proposals.default-config.json +4 -0
  21. package/dist/proposals.js +4 -0
  22. package/dist/recall-bootstrap.js +451 -0
  23. package/dist/recall.config.schema.json +232 -0
  24. package/dist/recall.d.ts +1981 -0
  25. package/dist/recall.default-config.json +4 -0
  26. package/dist/recall.js +5 -0
  27. package/dist/repl-C52wyfMs.js +2213 -0
  28. package/dist/row-ByLFE2Wx.d.ts +719 -0
  29. package/dist/row-DK7lPZVe.js +732 -0
  30. package/dist/runtime-metrics-DwpDJ8vz.d.ts +159 -0
  31. package/dist/schema-g4FQLr0V.d.ts +433 -0
  32. package/dist/sdk.d.ts +694 -0
  33. package/dist/sdk.js +112 -0
  34. package/dist/src-C4DzaIQZ.js +837 -0
  35. package/dist/src-CrEgiMJQ.js +1015 -0
  36. package/dist/src-CzxvmhFn.js +2327 -0
  37. package/dist/src-D88LvCX8.js +1797 -0
  38. package/dist/src-D91yij6C.js +13523 -0
  39. package/dist/src-DuopV8u7.js +2408 -0
  40. package/dist/substrate-admin.js +808 -0
  41. package/dist/substrate.js +5477 -0
  42. package/dist/testing.d.ts +1240 -0
  43. package/dist/testing.js +702 -0
  44. package/dist/types-8c0gtnd2.d.ts +35 -0
  45. package/dist/ws-C72iVS5T.d.ts +143 -0
  46. package/package.json +117 -4
@@ -0,0 +1,1568 @@
1
+ import { C as Id, E as Row, _ as EdgesStore, b as ActorIdentity, l as PackEnvelope, n as FieldDef, u as Schema } from "./schema-g4FQLr0V.js";
2
+ //#region ../../packages/substrate-types/src/dataset.d.ts
3
+ /**
4
+ * Handles yielded by `Dataset.withScopedTransaction`. Contains the
5
+ * tx-bound dataset for every requested namespace plus (optionally) a
6
+ * tx-bound edges store enlisted into the same substrate transaction.
7
+ * See `withScopedTransaction` JSDoc for the `edges` contract.
8
+ */
9
+ interface TxScopeHandles {
10
+ datasets: Map<string, Dataset>;
11
+ edges: EdgesStore | null;
12
+ }
13
+ /**
14
+ * A leaf predicate on a single field. At most one operator per call-site is
15
+ * used in practice (e.g. `{ age: { gt: 18 } }`), but the shape admits several
16
+ * operators so `{ age: { gte: 10, lt: 100 } }` can express a half-open range
17
+ * without the caller reaching for an explicit `AND`. Semantics: the leaf
18
+ * matches when EVERY specified operator matches (implicit AND within a leaf).
19
+ *
20
+ * `eq`/`neq` accept `null` to address IS NULL / IS NOT NULL semantics at the
21
+ * substrate layer — the validator enforces `null` only on those two operators.
22
+ */
23
+ interface FieldPredicate {
24
+ eq?: number | string | boolean | Date | null;
25
+ neq?: number | string | boolean | Date | null;
26
+ gt?: number | string | Date;
27
+ gte?: number | string | Date;
28
+ lt?: number | string | Date;
29
+ lte?: number | string | Date;
30
+ between?: [number | string | Date, number | string | Date];
31
+ in?: Array<number | string | boolean | Date>;
32
+ nin?: Array<number | string | boolean | Date>;
33
+ contains?: string;
34
+ startsWith?: string;
35
+ endsWith?: string;
36
+ has?: number | string | boolean | Date | null;
37
+ path?: string[];
38
+ }
39
+ /**
40
+ * A where clause is either a logical combinator OR a map of field names to
41
+ * predicates / nested where clauses (for struct fields). Field names and the
42
+ * three combinator keys (AND/OR/NOT) share a namespace — `AND`/`OR`/`NOT` are
43
+ * reserved and must not collide with field names declared in any type.
44
+ */
45
+ type WhereClause = {
46
+ AND: WhereClause[];
47
+ } | {
48
+ OR: WhereClause[];
49
+ } | {
50
+ NOT: WhereClause;
51
+ } | {
52
+ [field: string]: FieldPredicate | WhereClause | unknown;
53
+ };
54
+ /**
55
+ * OrderBy clause. One entry per field, direction per field. Engine appends an
56
+ * implicit `{ id: 'asc' }` when callers omit `id` as the final tie-breaker — a
57
+ * deterministic tie-break is what makes cursor pagination stable across pages.
58
+ */
59
+ interface OrderByClause {
60
+ [field: string]: 'asc' | 'desc';
61
+ }
62
+ interface ReadParams {
63
+ id?: Id;
64
+ ids?: Id[];
65
+ includeDeleted?: boolean;
66
+ where?: WhereClause;
67
+ orderBy?: OrderByClause[];
68
+ limit?: number;
69
+ /**
70
+ * Opaque cursor produced by a prior `read()` call. Base64url-encoded JSON
71
+ * (server-built, server-consumed). Callers should treat it as a black box.
72
+ */
73
+ cursor?: string;
74
+ /**
75
+ * Admin-gated escape hatch for filtering on unindexed fields. Absent → the
76
+ * validator rejects filters on any `indexed: false` field. Policies can pin
77
+ * this to admin identities.
78
+ */
79
+ _allowTableScan?: boolean;
80
+ /**
81
+ * Optional caller-supplied projection hint. Substrates MAY use this to
82
+ * narrow the body keys they materialise from storage — e.g. PgDataset
83
+ * builds a `jsonb_build_object(...)` projection over only the requested
84
+ * top-level body keys, saving wire + parse bandwidth.
85
+ *
86
+ * When present, ONLY top-level entries are honoured (the value can be `true`
87
+ * or a nested FieldInput-shaped object — the substrate treats both as
88
+ * "include this key"). Nested projection inside JSONB sub-trees is intentionally
89
+ * out of scope; the pack codec already prunes deeper. Row-metadata-style keys
90
+ * (`_metadata`, `shortId`, `_deletedAt`, `id`) are populated from dedicated
91
+ * columns regardless of `fields` and never need to be included here.
92
+ *
93
+ * When absent, substrates return the full body, for raw `dataset.read()`
94
+ * callers (sweep, compose registry, migration scripts) that don't know which
95
+ * body keys they'll need downstream.
96
+ *
97
+ * Substrates MAY ignore this hint — it's a perf optimisation, not a contract.
98
+ * Memory dataset, for instance, has no wire to save and ignores it.
99
+ */
100
+ fields?: {
101
+ [field: string]: true | unknown;
102
+ };
103
+ }
104
+ /**
105
+ * Paged result of a `read()` call. `rows` is always present; `nextCursor` is
106
+ * present iff `hasMore` is `true` and the current page is non-empty.
107
+ */
108
+ interface ReadResult {
109
+ rows: Row[];
110
+ nextCursor?: string;
111
+ hasMore: boolean;
112
+ }
113
+ interface WriteResult {
114
+ written: number;
115
+ ids: Id[];
116
+ /**
117
+ * Merged rows after upsert — substrates populate this with the post-merge
118
+ * row state so autoCRUD update can skip its post-read. Order
119
+ * matches `ids` (one entry per input row). Substrates that can't compute
120
+ * the merged shape cheaply may emit input rows verbatim; consumers must
121
+ * not rely on body keys absent from the input being filled in.
122
+ */
123
+ rows: Row[];
124
+ }
125
+ /**
126
+ * Optional 3rd-arg to `dataset.write` / `tx.write`. When the incoming row's
127
+ * `_metadata` is absent, the substrate auto-fills it from these hints:
128
+ * - `now` → both `createdAt` and `updatedAt` (defaults to `new Date()`)
129
+ * - `identity` → both `createdBy` and `updatedBy` (defaults to `null`)
130
+ *
131
+ * On upsert collision, `created_*` columns preserve existing values (immutability);
132
+ * `updated_*` columns adopt the new values (bump intent). Engine path
133
+ * (`autocrud-create`/`autocrud-update`) constructs full `_metadata` itself —
134
+ * this auto-fill is purely a safety net for raw-write bypass paths.
135
+ */
136
+ interface WriteOptions {
137
+ readonly identity?: ActorIdentity;
138
+ readonly now?: Date;
139
+ /**
140
+ * Insert only: a row whose id already exists (live or tombstoned) is left
141
+ * untouched and omitted from the result's `ids` and `rows`. The existence
142
+ * check and the insert are one atomic step.
143
+ */
144
+ readonly insertOnly?: boolean;
145
+ }
146
+ interface DeleteResult {
147
+ deleted: number;
148
+ ids: Id[];
149
+ }
150
+ interface DropResult {
151
+ /** Number of rows physically removed. */
152
+ rowsDeleted: number;
153
+ /** Number of short-id allocations physically removed. */
154
+ shortIdsDeleted: number;
155
+ }
156
+ /**
157
+ * Dataset-declared filter capabilities. §5.2 capability negotiation: the engine
158
+ * validates every where-clause leaf against `operators[fieldKind]` and rejects
159
+ * ops the dataset can't execute rather than returning a silently wrong result.
160
+ */
161
+ type FieldKind = 'scalar.number' | 'scalar.string' | 'scalar.boolean' | 'scalar.date' | 'scalar.json' | 'crossRef' | 'list';
162
+ interface FilterCapabilities {
163
+ operators: Record<FieldKind, string[]>;
164
+ /** Does the dataset honour `orderBy`? */
165
+ orderBy: boolean;
166
+ /** Does the dataset honour cursor-based pagination? */
167
+ cursor: boolean;
168
+ }
169
+ interface UpdateFieldRef {
170
+ ns?: string;
171
+ type: string;
172
+ id: Id;
173
+ }
174
+ /**
175
+ * Outcome of a `conditionalUpdate` call (spec §5.12 Phase 2 / Dispatch B).
176
+ *
177
+ * `matched: true` when the row existed AND every key in `match` equalled the
178
+ * row's stored value at the moment of the update — the substrate applied
179
+ * `updates` and returned the merged row. `matched: false` when the row was
180
+ * missing or at least one match condition failed; in both cases no write landed
181
+ * and `row` is `null`.
182
+ */
183
+ interface ConditionalUpdateResult {
184
+ matched: boolean;
185
+ row: Row | null;
186
+ }
187
+ interface Dataset {
188
+ readonly namespace: string;
189
+ /**
190
+ * Stable identifier for the storage substrate this dataset wraps. Two
191
+ * datasets share a substrate when their `txScopeId` values are `===`
192
+ * — they can participate in a single transaction via the engine's
193
+ * substrate-coalescing path (spec §5.3, enabling cross-namespace G1
194
+ * batched mutations when all frames target the same substrate).
195
+ *
196
+ * Convention:
197
+ * - pg: derived from the `postgres.Sql` pool reference identity. All
198
+ * `PgDataset` instances constructed against the same `sql`
199
+ * handle share one `txScopeId`.
200
+ * - memory: unique per `MemoryDataset` instance by default (each
201
+ * instance owns its own `Map`). Test harnesses that want shared-
202
+ * memory semantics can opt in via an explicit constructor option.
203
+ *
204
+ * Datasets with different `txScopeId` values CANNOT participate in a
205
+ * single transaction — the engine refuses mixed-substrate batched
206
+ * mutates with `cross_tx_scope_refused`.
207
+ */
208
+ readonly txScopeId: string;
209
+ read(type: string, params: ReadParams): Promise<ReadResult>;
210
+ write(type: string, rows: Row[], options?: WriteOptions): Promise<WriteResult>;
211
+ tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
212
+ purge(type: string, ids: Id[]): Promise<DeleteResult>;
213
+ /**
214
+ * Physically delete every row of `type` within this dataset's namespace,
215
+ * plus every short-id allocation for that type. Ignores `_deletedAt` /
216
+ * `archived` state — drop is hard-delete regardless of row status.
217
+ *
218
+ * MUST run inside a caller-supplied `withTransaction` if atomicity with
219
+ * edge cleanup / audit emission is required. When called standalone,
220
+ * implementations MUST still execute the row-delete + short-id-delete as
221
+ * a single atomic step against the substrate.
222
+ *
223
+ * Returns the exact counts physically removed. If the type has no rows,
224
+ * returns zeros without error.
225
+ *
226
+ * Storage-level primitive: operates on any (namespace, type) rows present
227
+ * in storage regardless of whether the type is currently known to the
228
+ * engine's registry.
229
+ */
230
+ dropType(type: string): Promise<DropResult>;
231
+ /**
232
+ * Physically delete every row AND short-id for `this.namespace`, across
233
+ * every type. Equivalent to calling `dropType` for each distinct type
234
+ * seen in storage, but substrate impls SHOULD use a single bulk DELETE
235
+ * where available (pg: `DELETE FROM rows WHERE namespace = $1`).
236
+ *
237
+ * Same atomicity rules as `dropType`. Same "ignores archived state".
238
+ */
239
+ dropNamespace(): Promise<DropResult>;
240
+ updateField(ref: UpdateFieldRef, fieldName: string, value: unknown): Promise<void>;
241
+ /**
242
+ * Atomic compare-and-update by PK. If the row `(type, id)` exists AND every
243
+ * `(field, value)` pair in `match` equals the stored row's field, apply the
244
+ * `updates` map and return `{ matched: true, row: mergedRow }`. Otherwise
245
+ * write nothing and return `{ matched: false, row: null }`.
246
+ *
247
+ * Semantics:
248
+ * - Equality is strict (`===`) for scalars; `Date` compares by
249
+ * `.getTime()`; `null` matches only a stored `null` (including
250
+ * intentionally-null fields set via `updateField`), never an absent field.
251
+ * - A missing row fails the match even when `match` is empty — the
252
+ * operation is "update this existing row if predicate holds".
253
+ * - `updates` is merged onto the stored row the same way `write()` upserts
254
+ * merge: each key overwrites; omitted keys are preserved. `_deletedAt`
255
+ * is reserved and silently skipped (matches `write()`'s sanitisation).
256
+ * - The whole check+write is atomic against other dataset operations.
257
+ * Implementations MUST NOT yield between the predicate test and the
258
+ * write. Pg uses `UPDATE ... WHERE <match> RETURNING *` inside the
259
+ * caller's enclosing `withTransaction`; memory runs the whole body
260
+ * synchronously within the `async` microtask.
261
+ *
262
+ * Motivating use case: the `_system` register route consumes a one-shot
263
+ * invite — the invite row's `consumedAt` must transition from `null` to a
264
+ * timestamp exactly once, even under concurrent registrations.
265
+ *
266
+ * Metadata: a successful match unconditionally bumps `updatedAt` to `now`
267
+ * (a server-set `now()` when omitted) and stamps `updatedBy` with the supplied `actor` (or
268
+ * a `{ kind: 'system', id: 'anonymous' }` sentinel when omitted) — same
269
+ * semantics as `write()`'s upsert path, so recency-ranked recall sees the
270
+ * change. `createdAt` / `createdBy` are preserved.
271
+ */
272
+ conditionalUpdate(type: string, id: Id, match: Record<string, unknown>, updates: Record<string, unknown>, actor?: ActorIdentity, now?: Date): Promise<ConditionalUpdateResult>;
273
+ readonly capabilities: FilterCapabilities;
274
+ /**
275
+ * Run `fn` while holding a mutual-exclusion lock named `key`, waiting until
276
+ * it is free. Excludes every other holder of the same key on this substrate:
277
+ * pg holds a session advisory lock, so the exclusion spans processes sharing
278
+ * the database; memory excludes holders on this dataset instance only.
279
+ * Released when `fn` settles, whether it resolves or throws, except on a
280
+ * pg tx-bound dataset, where it is held until the transaction ends so the
281
+ * next holder sees what this one committed. Not re-entrant:
282
+ * re-acquiring a held key inside `fn` waits forever.
283
+ *
284
+ * OPTIONAL. Callers feature-detect and fall back to a process-local lock.
285
+ *
286
+ * @returns whatever `fn` resolves to
287
+ * @throws whatever `fn` throws, after the lock is released
288
+ */
289
+ withAdvisoryLock?<T>(key: string, fn: () => Promise<T>): Promise<T>;
290
+ /**
291
+ * Execute `fn` atomically. All ops performed on the `tx` argument run inside
292
+ * one substrate transaction. If `fn` throws or returns a rejected promise,
293
+ * every mutation inside the callback rolls back. If `fn` resolves, the
294
+ * transaction commits and the resolved value is returned.
295
+ *
296
+ * Scope rules:
297
+ * - `tx.namespace === this.namespace`
298
+ * - Calls on the outer dataset (`this`) inside `fn` bypass the transaction
299
+ * and are NOT rolled back on failure — this is a caller bug; implementations
300
+ * MUST NOT attempt to guard against it. All ops inside `fn` MUST go through
301
+ * `tx`.
302
+ * - Nested `tx.withTransaction(...)` is implementation-defined. The reference
303
+ * impls (memory, pg) flatten nested calls into the outermost transaction
304
+ * (no savepoints).
305
+ */
306
+ withTransaction<T>(fn: (tx: Dataset) => Promise<T>): Promise<T>;
307
+ /**
308
+ * Engine-only. Open a substrate-level transaction spanning multiple
309
+ * namespaces on the same substrate, and invoke `fn` with a handles object
310
+ * containing tx-bound datasets + (optionally) a tx-bound `EdgesStore`.
311
+ * Called by the engine's mutate path (spec §5.3) for both single-ns and
312
+ * cross-ns frames — the engine calls with `[ns]` for the single-ns case.
313
+ *
314
+ * `namespaces` is the full set of namespaces the engine will dispatch
315
+ * frames to inside the tx. Implementations MUST return a tx-bound
316
+ * dataset for every requested namespace in `handles.datasets`; missing
317
+ * entries are a programming error on the caller side.
318
+ *
319
+ * `handles.edges` contract:
320
+ * - `non-null` when the implementation can enlist a shared `EdgesStore`
321
+ * into the same substrate tx (e.g. pg where the `PgEdgesStore` is wired
322
+ * in via constructor and shares the `Sql`). The engine routes edge
323
+ * mutations through this handle — true cross-store atomicity for
324
+ * row + edge within one frame.
325
+ * - `null` when the implementation can't enlist (e.g. memory datasets
326
+ * where edges live in a separate Map). The engine falls back to
327
+ * running edge ops in a nested independent tx and accepts the
328
+ * visibility-ordering quirk documented in `autocrud-delete.ts`.
329
+ *
330
+ * Scope rules mirror `withTransaction`:
331
+ * - All ops on values from `handles.datasets.get(ns)` and `handles.edges`
332
+ * run in the same tx.
333
+ * - Ops on the outer dataset (`this`) inside `fn` bypass the tx — caller
334
+ * bug; implementations do not guard.
335
+ * - A throw or rejection inside `fn` rolls back every mutation across
336
+ * every namespace + edges in the tx.
337
+ *
338
+ * OPTIONAL. Implementations that can't coalesce cross-namespace writes
339
+ * into one substrate transaction omit this method — the engine falls
340
+ * back to refusing cross-namespace batches with `cross_tx_scope_refused`
341
+ * (and loses edge-enlist for single-ns).
342
+ */
343
+ withScopedTransaction?<T>(namespaces: ReadonlyArray<string>, fn: (handles: TxScopeHandles) => Promise<T>): Promise<T>;
344
+ /**
345
+ * Allocate the next short id for the given type within this dataset's
346
+ * namespace. Monotonic per (namespace, type). Does NOT record any
347
+ * row-id mapping — call `bindShortId` after the row is written.
348
+ *
349
+ * The implementation may use the dataset's current tx handle so the
350
+ * sequence advance rolls back on tx rollback (postgres sequences
351
+ * actually never roll back, but the surrounding tx semantics match
352
+ * what callers expect).
353
+ */
354
+ allocateShortId(type: string): Promise<number>;
355
+ /**
356
+ * Record the (shortId → rowId) pairing after the row is written.
357
+ * Called by autoCRUD create immediately after the dataset write()
358
+ * returns the new row id. Safe to call within the enclosing tx.
359
+ */
360
+ bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
361
+ /**
362
+ * Resolve a short id to the underlying row id, or null if no such short
363
+ * id exists for this (namespace, type). Does not join `rows` —
364
+ * callers chain their own `read()` after resolution.
365
+ */
366
+ resolveShortId(type: string, shortId: number): Promise<string | null>;
367
+ /**
368
+ * Inverse of `resolveShortId` — look up the short id assigned to a
369
+ * given row id. Returns null if no sidecar entry exists (e.g. rows written
370
+ * before short ids were allocated).
371
+ */
372
+ getShortIdForRow(type: string, rowId: string): Promise<number | null>;
373
+ /**
374
+ * Spawn a sibling dataset bound to the same backing store but scoped to
375
+ * a different namespace. Used by `compose()` to auto-allocate per-namespace
376
+ * datasets when a coordinator plugin claims a namespace the operator hasn't
377
+ * mapped explicitly.
378
+ *
379
+ * Substrate semantics:
380
+ * - Pg: returns a new `PgDataset` sharing this dataset's `sql` pool +
381
+ * `edgesStore`. The returned dataset has the SAME `txScopeId` (so it
382
+ * can participate in cross-namespace batched mutations on the shared pool).
383
+ * - Memory: returns a new `MemoryDataset` with its own backing `Map`
384
+ * per the default convention (each instance owns its own substrate). The
385
+ * returned dataset has a NEW `txScopeId` — it cannot share a transaction
386
+ * with the caller. Test harnesses that need shared-memory semantics across
387
+ * namespaces should construct each `MemoryDataset` explicitly with
388
+ * the relevant constructor option.
389
+ *
390
+ * Idempotency note: callers SHOULD NOT call `forNamespace(this.namespace)`;
391
+ * the resulting object's identity is implementation-defined. Use this only
392
+ * to derive datasets for *different* namespaces.
393
+ */
394
+ forNamespace(namespace: string): Dataset;
395
+ }
396
+ interface DatasetRegistry {
397
+ get(ns: string): Dataset | undefined;
398
+ has(ns: string): boolean;
399
+ set(ns: string, dataset: Dataset): void;
400
+ /**
401
+ * Observe namespace lifecycle events (§6.4). Fires when a namespace is
402
+ * disposed — explicit unregister or substrate-signalled loss (memory-backed
403
+ * restart). Returns a disposer that unsubscribes when invoked.
404
+ *
405
+ * Optional: registries over persistent substrates (pg) never lose namespaces
406
+ * at runtime and can omit this surface entirely. Consumers MUST feature-
407
+ * detect before subscribing.
408
+ */
409
+ onNamespaceLost?(listener: (ns: string) => void): () => void;
410
+ /**
411
+ * Explicitly drop `ns` from the registry and fire `onNamespaceLost`
412
+ * listeners synchronously. Disposing an unregistered namespace is a silent
413
+ * no-op — keeps graceful-shutdown replays idempotent.
414
+ *
415
+ * Optional: same rationale as `onNamespaceLost`.
416
+ */
417
+ dispose?(ns: string): void;
418
+ }
419
+ //#endregion
420
+ //#region ../../packages/substrate-types/src/policy.d.ts
421
+ interface Identity {
422
+ id: string;
423
+ roles?: string[];
424
+ scopes?: string[];
425
+ /**
426
+ * Per-namespace capabilities — the only grant surface. `{ notes: ['read'],
427
+ * tasks: ['read','mutate'] }`; `'*'` is a legal key. Read it through the
428
+ * `identity-grant.ts` helpers.
429
+ *
430
+ * A plain object rather than a Map: `Identity` is JSON-serialised into the
431
+ * SSE stream ticket, and a Map would arrive as `{}` on the far side.
432
+ *
433
+ * A bare `{ id }` with no grant (direct-call tests, system actors) is the
434
+ * no-claim case: `grantOf` resolves it to `null`, and the engine's grant
435
+ * gate then admits every namespace. An authenticator for remote callers
436
+ * must therefore always set `grants`, `{}` for none.
437
+ */
438
+ grants: Record<string, string[]>;
439
+ [k: string]: unknown;
440
+ }
441
+ /**
442
+ * Semantic verb stamped on autoCRUD-registered mutation entries.
443
+ * Absent on type entries and custom mutations — policies needing those use
444
+ * `RequestContext.entry` / `operation` instead.
445
+ */
446
+ type AutoCrudVerb = 'get' | 'create' | 'update' | 'delete';
447
+ interface RequestContext {
448
+ identity: Identity | null;
449
+ namespace: string;
450
+ operation: 'query' | 'mutate' | 'subscribe' | 'stream';
451
+ now: Date;
452
+ headers: Record<string, string>;
453
+ meta: Record<string, unknown>;
454
+ /**
455
+ * Trust-gated client IP computed by the HTTP route handler from the request's
456
+ * `peerIp` + the operator-configured trusted-proxy allowlist. When the peer
457
+ * is in the allowlist, this is the leftmost `x-forwarded-for` entry; when
458
+ * untrusted, this is the peer IP itself. Undefined when the transport doesn't
459
+ * expose peerIp (direct engine unit tests, pre-upgrade WS paths).
460
+ */
461
+ clientIp?: string;
462
+ /**
463
+ * Whether the deployment verifies credentials at all, as the transport knows
464
+ * it, so a refusal for want of an identity can say whether auth is off
465
+ * rather than implying the caller's key is wrong.
466
+ *
467
+ * `undefined` means the transport did not say (direct engine unit tests,
468
+ * routes with no auth config in scope). Treat it as unknown, never as `false`.
469
+ */
470
+ authEnabled?: boolean;
471
+ /**
472
+ * The registry entry name this dispatch targets — the `<name>` half of the
473
+ * qualified frame key (e.g. `deleteTodo`, `Todo`). Threaded by the engine
474
+ * at every dispatch site (query/mutate/stream/subscribe) so type- and
475
+ * plugin-level policies can discriminate between resolvers that otherwise
476
+ * present identically (`get<T>` and `delete<T>` both arrive as
477
+ * operation:'mutate' with id-only params). Undefined only in direct-call
478
+ * unit tests that construct a bare ctx.
479
+ */
480
+ entry?: string;
481
+ /**
482
+ * Semantic verb of the targeted entry when autoCRUD registered it.
483
+ * Prefer this over `entry`-name matching for intent-level policies
484
+ * ("deny deletes") — it survives entry renames. Absent for type entries
485
+ * and custom mutations.
486
+ */
487
+ verb?: AutoCrudVerb;
488
+ }
489
+ /** The caller's request context for a policy check made outside dispatch. */
490
+ type PolicyProbeContext = Partial<Pick<RequestContext, 'now' | 'headers' | 'meta' | 'clientIp' | 'authEnabled'>>;
491
+ interface ResolverArgs {
492
+ params?: Record<string, unknown>;
493
+ fields?: Record<string, unknown>;
494
+ rows?: Row[];
495
+ /**
496
+ * Engine-injected per-call dataset handle. On `engine.mutate`, this is the
497
+ * transaction-scoped `tx` view (spec §5.3, G1); on `engine.query` it's the
498
+ * plain namespace dataset. Resolvers that perform I/O MUST use this handle
499
+ * — using a dataset captured at registration time bypasses the active
500
+ * transaction and breaks atomicity. Optional purely to keep direct-resolver
501
+ * unit tests concise; the engine always supplies it.
502
+ */
503
+ dataset?: Dataset;
504
+ /**
505
+ * Engine-injected per-call edges store (§4.6). Resolvers that touch edges
506
+ * MUST use this handle; the closed-over store from registration is a
507
+ * fallback for direct-call tests. Unlike `dataset`, this is not namespace-
508
+ * scoped — edges are inherently cross-namespace, and a single engine-scoped
509
+ * `EdgesStore` is threaded through every call.
510
+ */
511
+ edges?: EdgesStore;
512
+ /**
513
+ * Engine-injected post-commit write hook (§5.4). Write-path resolvers
514
+ * (autoCRUD create/update/delete, or custom mutation resolvers) call this
515
+ * AFTER their substrate write lands to announce the change. The engine
516
+ * collects calls into a per-transaction batch and fans them out to the
517
+ * subscription bus only after the enclosing `withTransaction` commits — a
518
+ * rolled-back tx emits nothing. Direct-call unit tests may pass `onWrite` to
519
+ * observe resolver output without spinning up an engine.
520
+ */
521
+ onWrite?: (event: WriteEvent) => void;
522
+ /**
523
+ * Queue work to run once the surrounding transaction has settled, whether it
524
+ * committed or rolled back: a record that must outlive a rollback, such as
525
+ * an audit row for the refusal that caused it. The work is told which
526
+ * (`committed`), so post-commit work can skip a rollback. Absent outside a
527
+ * transaction, where the caller can simply do the work.
528
+ */
529
+ afterTx?: (fn: AfterTxWork) => void;
530
+ /**
531
+ * Engine-injected cancellation signal (§5.5). Supplied on `stream` dispatch
532
+ * so generator resolvers can abort mid-iteration when the client cancels or
533
+ * the socket closes. Streaming resolvers SHOULD observe this signal — either
534
+ * by calling `signal.throwIfAborted()` at yield points, or by listening for
535
+ * `abort` to release cursors / close descriptors in their `finally` block.
536
+ * The engine cannot force-stop a generator; cooperation is the contract.
537
+ * Absent on query/mutate dispatch — non-streaming resolvers should not see a
538
+ * signal they have no way to honour.
539
+ */
540
+ signal?: AbortSignal;
541
+ /**
542
+ * Engine-injected cross-namespace dataset resolver (committed, non-tx view).
543
+ * Write-path resolvers use it to verify crossRef referents that live in a
544
+ * DIFFERENT namespace (onMissing:'reject'). Same-namespace targets should use
545
+ * the tx-scoped `dataset` handle instead. Absent on the query/subscribe path.
546
+ */
547
+ resolveDataset?: (ns: string) => Dataset | undefined;
548
+ }
549
+ /**
550
+ * Post-commit write announcement consumed by the engine's subscription bus
551
+ * (§5.4). Emitted by write-path resolvers after the substrate operation
552
+ * commits inside the current transaction. `row` is the post-commit canonical
553
+ * row for creates and updates; for deletes it's the pre-tombstone snapshot
554
+ * (absent if the resolver couldn't read the row before deleting). The engine
555
+ * filters matching subscriptions by `(ns, type)`, tests the `row` against each
556
+ * subscription's `where` predicate, and emits `add` / `update` / `remove`.
557
+ */
558
+ interface WriteEvent {
559
+ ns: string;
560
+ type: string;
561
+ id: Row['id'];
562
+ operation: 'create' | 'update' | 'delete';
563
+ row?: Row;
564
+ }
565
+ interface Obligation {
566
+ kind: string;
567
+ [k: string]: unknown;
568
+ }
569
+ /**
570
+ * Row-filter obligation: emitted by `row<T>(predicate)` policies. The engine
571
+ * scans accumulated obligations after resolver execution and applies each
572
+ * predicate as a silent filter.
573
+ */
574
+ interface RowFilterObligation<T = unknown> extends Obligation {
575
+ kind: 'row-filter';
576
+ predicate: (ctx: RequestContext, row: T) => boolean;
577
+ }
578
+ interface PolicyDecision {
579
+ allow: boolean;
580
+ reason?: string;
581
+ obligations?: Obligation[];
582
+ }
583
+ type Policy = (ctx: RequestContext, args: ResolverArgs) => PolicyDecision;
584
+ /**
585
+ * Engine-facing resolver shape. Spec: §4.3, §5.2, §5.5.
586
+ *
587
+ * The engine treats any resolver's return as opaque rows. A `ReadResult` return
588
+ * signals a paged list; the engine unpacks `rows` into the envelope and copies
589
+ * `nextCursor`/`hasMore` into `_pagination[key]`. An `AsyncIterable<Row>`
590
+ * return is the §5.5 stream-dispatch shape (duck-typed via
591
+ * `Symbol.asyncIterator` so it can't collide with `Row[]`).
592
+ *
593
+ * This is what the registry stores and what the engine dispatches to. Plugin
594
+ * authors declaring custom resolvers use the typed-authoring form
595
+ * `TypedResolver<T>` below; the engine erases to `Resolver` at registration
596
+ * time.
597
+ */
598
+ type Resolver = (ctx: RequestContext, args: ResolverArgs) => Promise<Row | Row[] | ReadResult | AsyncIterable<Row> | null> | AsyncIterable<Row>;
599
+ /**
600
+ * Typed-authoring resolver shape. Used by autoCRUD and hand-authored resolvers
601
+ * that want to preserve the concrete return type before erasing to `Resolver`
602
+ * at registration. `T` is unconstrained at the type level — the engine
603
+ * discriminates on the runtime value shape regardless of static type.
604
+ */
605
+ type TypedResolver<T> = (ctx: RequestContext, args: ResolverArgs) => Promise<T>;
606
+ /**
607
+ * Engine-visible return shape for a resolver. `ReadResult` means "paged list";
608
+ * `Row[]` means "full list, no pagination"; `Row` means "single"; `null` means
609
+ * "single, not found". The engine discriminates at runtime.
610
+ */
611
+ type ResolverReturn = Row | Row[] | ReadResult | null;
612
+ /** Work queued through `ResolverArgs.afterTx`, told whether the transaction committed. */
613
+ type AfterTxWork = (outcome: {
614
+ committed: boolean;
615
+ }) => Promise<void>;
616
+ //#endregion
617
+ //#region ../../packages/substrate-types/src/server.d.ts
618
+ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
619
+ interface SubstrateRequest {
620
+ method: HttpMethod;
621
+ path: string;
622
+ headers: Record<string, string>;
623
+ query: Record<string, string>;
624
+ params: Record<string, string>;
625
+ body: Buffer | null;
626
+ identity?: Identity;
627
+ /**
628
+ * Remote peer IP observed at the transport layer. Populated by adapters
629
+ * (Fastify: `request.ip`; memory: caller supplies via `inject({ peerIp })`).
630
+ * Absent when transport doesn't expose it. Consumers that gate on peer IP
631
+ * (e.g. `x-forwarded-for` trust) treat `undefined` as "untrusted peer".
632
+ */
633
+ peerIp?: string;
634
+ /**
635
+ * Client IP after the trusted-proxy check, stamped by the host before plugin
636
+ * and kernel route handlers run. Never read from the client.
637
+ */
638
+ clientIp?: string;
639
+ /** Whether the deployment verifies credentials, stamped with `clientIp`. */
640
+ authEnabled?: boolean;
641
+ /**
642
+ * Per-request abort signal. Production transports (Fastify) wire it to fire
643
+ * on socket close (client disconnect) and on `abortAllRequests()` during
644
+ * graceful shutdown. Route handlers thread it into `engine.query/mutate`
645
+ * via `signal:` so resolvers can cooperatively bail. Optional because
646
+ * test fixtures and embedded `inject()` callers may not need cancellation.
647
+ */
648
+ signal?: AbortSignal;
649
+ }
650
+ interface SubstrateResponse {
651
+ status: number;
652
+ headers?: Record<string, string>;
653
+ body?: Buffer | Uint8Array | string | ReadableStream;
654
+ }
655
+ type HttpHandler = (req: SubstrateRequest) => SubstrateResponse | Promise<SubstrateResponse>;
656
+ /** Request op classes counted by the runtime-metrics surface (§ engine-metrics spec). */
657
+ type RuntimeOp = 'query' | 'mutate';
658
+ /** One observed HTTP request at the transport seam. */
659
+ interface RequestObservation {
660
+ readonly op: RuntimeOp;
661
+ /** Transport-level success — HTTP status < 400. Frame-level envelope errors still count ok. */
662
+ readonly ok: boolean;
663
+ /** Wall-clock elapsed from handler entry to response, measured via Date.now(). Always >= 0. */
664
+ readonly durationMs: number;
665
+ }
666
+ type RequestObserver = (o: RequestObservation) => void;
667
+ interface WsConnection {
668
+ readonly id: string;
669
+ send(frame: Buffer | Uint8Array | string): void;
670
+ /**
671
+ * Transport-level back-pressure seam. Resolves once the
672
+ * socket's write buffer is below its high-water mark — immediately when it
673
+ * already is. The stream route awaits this between chunks so a fast producer
674
+ * paces to a slow consumer instead of growing the send buffer unbounded.
675
+ * Optional: transports without buffer introspection (memory tests) omit it,
676
+ * and the route treats a missing hook as "always drained".
677
+ */
678
+ drain?(): Promise<void>;
679
+ onMessage(cb: (frame: Buffer) => void): void;
680
+ onClose(cb: (code?: number) => void): void;
681
+ close(code?: number, reason?: string): void;
682
+ /**
683
+ * Register a callback invoked synchronously during graceful server shutdown,
684
+ * BEFORE the underlying socket is closed. Higher layers use this to flush
685
+ * structured frames (e.g. `{ kind: 'end', reason: 'server_restart' }` per
686
+ * active subscription) so clients can short-circuit reconnect backoff
687
+ * instead of seeing an abrupt 1006 drop. Optional — transports without a
688
+ * pre-close hook (memory tests) may omit it; the route layer should
689
+ * tolerate undefined.
690
+ */
691
+ onShutdown?(cb: (reason: string) => void): void;
692
+ }
693
+ type WsHandler = (req: SubstrateRequest, conn: WsConnection) => void | Promise<void>;
694
+ interface TlsConfig {
695
+ cert: string | Buffer;
696
+ key: string | Buffer;
697
+ ca?: string | Buffer;
698
+ }
699
+ interface StartOpts {
700
+ host?: string;
701
+ port?: number;
702
+ tls?: TlsConfig;
703
+ }
704
+ interface PluginRouter {
705
+ get(path: string, handler: HttpHandler): void;
706
+ post(path: string, handler: HttpHandler): void;
707
+ put(path: string, handler: HttpHandler): void;
708
+ delete(path: string, handler: HttpHandler): void;
709
+ patch(path: string, handler: HttpHandler): void;
710
+ websocket(path: string, handler: WsHandler): void;
711
+ }
712
+ interface SubstrateServer {
713
+ start(opts?: StartOpts): Promise<{
714
+ address: string;
715
+ port: number;
716
+ }>;
717
+ stop(opts?: {
718
+ grace?: number;
719
+ abortInFlight?: boolean;
720
+ }): Promise<void>;
721
+ route(method: HttpMethod, path: string, handler: HttpHandler): void;
722
+ websocket(path: string, handler: WsHandler): void;
723
+ onError?(hook: (err: Error, req?: SubstrateRequest) => void): void;
724
+ createPluginRouter(plugin: {
725
+ name: string;
726
+ }): PluginRouter;
727
+ /**
728
+ * Abort every in-flight HTTP request's `req.signal` so resolvers cooperatively
729
+ * bail. Used during graceful shutdown to give the engine a chance to roll
730
+ * back mutations before fastify's drain timeout fires. WS connections are
731
+ * not affected by this call; their teardown rides on socket close.
732
+ */
733
+ abortAllRequests(reason?: string): void;
734
+ /**
735
+ * Register a callback invoked synchronously at the START of `stop()` —
736
+ * before in-flight requests are aborted and before the transport drains.
737
+ *
738
+ * The HTTP analogue of `WsConnection.onShutdown`, for routes that hold
739
+ * a response open indefinitely (SSE): handlers flush a terminal frame and end
740
+ * their response, or the drain would wait forever.
741
+ *
742
+ * Additive, not last-one-wins (unlike `onError`): a dropped registration is
743
+ * a leaked stream. Optional — transports with no graceful phase may omit it,
744
+ * and callers must tolerate undefined.
745
+ */
746
+ onShutdown?(cb: (reason: string) => void): void;
747
+ /**
748
+ * Test-only: invoke the server's handler pipeline without opening a socket.
749
+ * Networked implementations may leave this undefined.
750
+ */
751
+ inject?(req: Partial<SubstrateRequest>): Promise<SubstrateResponse>;
752
+ /**
753
+ * Register a per-request observer for op throughput + latency. Optional —
754
+ * transports without instrumentation may omit it. At most one observer; a
755
+ * second call replaces the first. The transport invokes it only for the
756
+ * `/substrate/v1/query` and `/substrate/v1/mutate` routes.
757
+ */
758
+ observeRequests?(observer: RequestObserver): void;
759
+ /** Optional: told when a query/mutate HTTP request starts (+1) and ends (-1), including when it throws. */
760
+ observeInFlight?(fn: (op: RuntimeOp, delta: 1 | -1) => void): void;
761
+ }
762
+ //#endregion
763
+ //#region ../../packages/substrate-types/src/plugin.d.ts
764
+ /** Whether a registry entry is a top-level addressable type or a mutation. */
765
+ type RegistryEntryKind = 'type' | 'mutation';
766
+ /**
767
+ * postWrite hook signature. Receives the written row and request context;
768
+ * may perform side-effects (e.g. embedding, index updates). Returned promise
769
+ * is awaited before the engine acks the write to the caller.
770
+ */
771
+ type PostWriteHook = (row: Row, ctx: RequestContext) => Promise<void>;
772
+ /**
773
+ * Resolver signature stored in a `RegistryEntry`. Identical to the canonical
774
+ * engine-facing `Resolver` in `./policy.ts`; redeclared inline here to keep
775
+ * the registry surface self-describing for the types package. Importers that
776
+ * want the canonical alias should import `Resolver` from this package.
777
+ */
778
+ type RegistryEntryResolver = (ctx: RequestContext, args: ResolverArgs) => Promise<Row | Row[] | ReadResult | AsyncIterable<Row> | null> | AsyncIterable<Row>;
779
+ /** Input shape for `Registry.register` / `Registry.replace`. */
780
+ interface RegistryEntryInput {
781
+ resolver: RegistryEntryResolver;
782
+ policy?: Policy;
783
+ fields?: Record<string, FieldDef>;
784
+ kind?: RegistryEntryKind;
785
+ params?: Record<string, FieldDef>;
786
+ returns?: FieldDef;
787
+ /**
788
+ * Semantic verb for autoCRUD-registered mutations. The engine
789
+ * threads this into `RequestContext.verb` at dispatch so type-/plugin-level
790
+ * policies can discriminate get/create/update/delete without entry-name
791
+ * string matching. Omit for type entries and custom mutations.
792
+ */
793
+ verb?: AutoCrudVerb;
794
+ }
795
+ /**
796
+ * Stored shape returned by `Registry.get` and `Registry.all`. Mirrors the
797
+ * concrete `RegistryEntry` in `@mnmal-ai/substrate-core` — the engine reads
798
+ * `policy`, `kind`, `resolver`, `fields`, `params`, and `returns` off this
799
+ * shape on every dispatch.
800
+ */
801
+ interface RegistryEntry {
802
+ resolver: RegistryEntryResolver;
803
+ policy: Policy;
804
+ fields: Record<string, FieldDef>;
805
+ kind: RegistryEntryKind;
806
+ /** Always present — `{}` for `kind: 'type'` entries where the concept doesn't apply. */
807
+ params: Record<string, FieldDef>;
808
+ /** Present only for `kind: 'mutation'` entries that declared a return shape. */
809
+ returns?: FieldDef;
810
+ /** Mirrors `RegistryEntryInput.verb` — present when the registrant stamped one. */
811
+ verb?: AutoCrudVerb;
812
+ }
813
+ /**
814
+ * Canonical per-namespace registry surface, implemented by the concrete
815
+ * `Registry` class in `@mnmal-ai/substrate-core`.
816
+ */
817
+ interface Registry {
818
+ register(key: string | {
819
+ readonly name: string;
820
+ }, input: RegistryEntryInput): void;
821
+ replace(key: string | {
822
+ readonly name: string;
823
+ }, input: RegistryEntryInput): void;
824
+ /**
825
+ * Read back a registered entry. Returns undefined when the entry is absent.
826
+ * The full `RegistryEntry` shape (resolver, policy, kind, fields, params,
827
+ * returns) is exposed because the engine reads every field on dispatch.
828
+ */
829
+ get(key: string | {
830
+ readonly name: string;
831
+ }): RegistryEntry | undefined;
832
+ /** Presence check. Returns true iff `key` is registered. */
833
+ has(key: string | {
834
+ readonly name: string;
835
+ }): boolean;
836
+ /** Iterate every `[name, entry]` pair. Used by the schema publisher. */
837
+ all(): IterableIterator<[string, RegistryEntry]>;
838
+ /**
839
+ * Remove an entry. Optional: only a registry that can take back a live
840
+ * apply (a schema proposal rolled back with its transaction) offers it.
841
+ */
842
+ unregister?(key: string | {
843
+ readonly name: string;
844
+ }): void;
845
+ /**
846
+ * Monotonic mutation counter — incremented by every `register` / `replace` / `unregister`.
847
+ * Lets a consumer cache anything derived from the registry (the published
848
+ * schema, above all) and detect staleness from the data, without relying on
849
+ * every registrant remembering to call `engine.invalidateSchemaCaches`.
850
+ *
851
+ * Optional so third-party `Registry` implementations remain valid; consumers
852
+ * fall back to callback-driven invalidation when it is absent.
853
+ */
854
+ readonly epoch?: number | undefined;
855
+ }
856
+ /**
857
+ * Base class binding the `epoch` bookkeeping so an implementation cannot forget
858
+ * it. Subclasses supply storage via `performRegister` / `performReplace` and
859
+ * never implement `register` / `replace` themselves, so the counter is advanced
860
+ * by construction rather than by discipline.
861
+ *
862
+ * A throw from `performRegister` leaves the epoch untouched, which is correct:
863
+ * a rejected registration changed nothing.
864
+ *
865
+ * Decorators cannot extend this — they wrap an instance rather than subclass it
866
+ * — so a wrapping registry must forward `epoch` from the wrapped instance. See
867
+ * `substrate-compose`'s `_system` install for the worked example.
868
+ */
869
+ declare abstract class RegistryBase implements Registry {
870
+ #private;
871
+ get epoch(): number;
872
+ register(key: string | {
873
+ readonly name: string;
874
+ }, input: RegistryEntryInput): void;
875
+ replace(key: string | {
876
+ readonly name: string;
877
+ }, input: RegistryEntryInput): void;
878
+ unregister(key: string | {
879
+ readonly name: string;
880
+ }): void;
881
+ /** Store a new entry. Throw to reject; the epoch will not advance. */
882
+ protected abstract performRegister(key: string | {
883
+ readonly name: string;
884
+ }, input: RegistryEntryInput): void;
885
+ /** Overwrite an existing entry. Throw to reject; the epoch will not advance. */
886
+ protected abstract performReplace(key: string | {
887
+ readonly name: string;
888
+ }, input: RegistryEntryInput): void;
889
+ /** Remove an entry. Not abstract, so existing subclasses stay valid; they refuse. */
890
+ protected performUnregister(key: string | {
891
+ readonly name: string;
892
+ }): void;
893
+ abstract get(key: string | {
894
+ readonly name: string;
895
+ }): RegistryEntry | undefined;
896
+ abstract has(key: string | {
897
+ readonly name: string;
898
+ }): boolean;
899
+ abstract all(): IterableIterator<[string, RegistryEntry]>;
900
+ }
901
+ /** See `EngineHandle.addDropParticipant`. */
902
+ interface DropParticipant {
903
+ /** Namespaces whose datasets `onDrop` writes, opened in the drop's transaction. */
904
+ readonly namespaces: readonly string[];
905
+ /** `datasetFor` returns the transaction-bound dataset of one of `namespaces`. */
906
+ onDrop(ns: string, datasetFor: (ns: string) => Dataset): Promise<void>;
907
+ }
908
+ interface NamespaceInstallContext {
909
+ registry: Registry;
910
+ dataset: Dataset;
911
+ edges: EdgesStore;
912
+ /**
913
+ * Plugin-global policy composed from the owning plugin's `policies` array
914
+ * (undefined when the plugin declares none). Namespace install
915
+ * implementations SHOULD compose this with any namespace-scoped or per-type
916
+ * policies via `and()` so plugin-level invariants apply across every
917
+ * resolver the namespace contributes. `defineNamespace` in
918
+ * `@mnmal-ai/substrate-sdk` does this automatically.
919
+ */
920
+ pluginPolicy?: Policy;
921
+ /**
922
+ * Substrate-plugin contributions to per-type postWrite chains. Map
923
+ * `typeName → PostWriteHook[]`. Engine populates by walking each
924
+ * composed substrate plugin's `contributePostWrites(namespace)` and
925
+ * merging results. Hooks run AFTER the type's inline postWrite in
926
+ * declaration order. Empty map / undefined = no contributions.
927
+ */
928
+ postWriteContributions?: Record<string, PostWriteHook[]>;
929
+ }
930
+ /**
931
+ * Read-side context passed to `NamespaceTypeDef.embed.source` when the
932
+ * substrate composing the embedding (e.g. substrate-recall) has a dataset
933
+ * resolver wired. Lets the source function pull related-entity context
934
+ * via crossRefs (e.g. inline a linked Concept's name into the embedded
935
+ * text so semantic recall surfaces relevant rows).
936
+ *
937
+ * Minimal by design — `read` is the only method, and it returns the
938
+ * first matching row or `null`. Source functions that don't need
939
+ * crossRef enrichment ignore the parameter.
940
+ */
941
+ interface EmbedSourceContext {
942
+ read: (namespace: string, type: string, params: {
943
+ id: string;
944
+ }) => Promise<Row | null>;
945
+ }
946
+ /**
947
+ * Structural shape of a type definition, mirroring `TypeInput` from
948
+ * @mnmal-ai/substrate-sdk (redeclared to avoid a substrate-types → substrate-sdk import
949
+ * cycle). Substrate plugins read it structurally; slots not named here pass
950
+ * through opaquely.
951
+ */
952
+ interface NamespaceTypeDef {
953
+ fields: Record<string, FieldDef>;
954
+ postWrite?: (row: Row, ctx: RequestContext) => Promise<void>;
955
+ embed?: {
956
+ /**
957
+ * Produce the source text fed to the embedder for this row, or `null` /
958
+ * `undefined` to declare the row un-indexable.
959
+ *
960
+ * The null sentinel is a RETRIEVAL POLICY, not an absence of text: it
961
+ * means "this row exists and must be referenceable, but must never enter
962
+ * the recall candidate set". The composing substrate both declines to
963
+ * index the row AND removes any embedding it already has, so a row that
964
+ * flips to un-indexable after being written stops being recallable
965
+ * without being deleted.
966
+ *
967
+ * `''` is NOT the sentinel — an empty string embeds normally. Returning
968
+ * `''` to mean "skip" indexes every such row at the same point in the
969
+ * vector space.
970
+ *
971
+ * `ctx` is optional — when the composing substrate has a dataset
972
+ * resolver wired, source functions may call `ctx.read(ns, type,
973
+ * { id })` to inline related-entity context. When `ctx` is undefined,
974
+ * the source must work from `row` alone. Async return is supported
975
+ * so source functions can await crossRef reads.
976
+ */
977
+ source: (row: Row, ctx?: EmbedSourceContext) => string | null | undefined | Promise<string | null | undefined>;
978
+ };
979
+ /**
980
+ * Produce the text fed to the LEXICAL (keyword) index for this row, with the
981
+ * same `null` / `undefined` un-indexable sentinel as `embed.source`.
982
+ *
983
+ * A sibling of `embed` rather than a flag on it, because the two indexes
984
+ * want different text: `embed.source` conventionally takes a short handle
985
+ * (`synopsis || body`), which drops proper nouns a keyword index needs.
986
+ * `lexical.source` is where the long form goes.
987
+ *
988
+ * A type may declare either, both, or neither. Both is the expected shape for
989
+ * a store whose handle is shorter than its content.
990
+ */
991
+ lexical?: {
992
+ source: (row: Row) => string | null | undefined | Promise<string | null | undefined>;
993
+ };
994
+ [key: string]: unknown;
995
+ }
996
+ interface NamespaceDefinition {
997
+ namespace: string;
998
+ /**
999
+ * Type definitions registered under this namespace, keyed by type name.
1000
+ * Read-only metadata exposed for substrate plugins that need to walk
1001
+ * the type surface at coordinator-namespace install time (e.g.
1002
+ * substrate-recall reads `types[T].embed?.source` to contribute embedding
1003
+ * postWrite hooks). Populated by `defineNamespace`; absent on hand-crafted
1004
+ * `NamespaceDefinition` objects that bypass the SDK helper.
1005
+ */
1006
+ types?: Readonly<Record<string, NamespaceTypeDef>>;
1007
+ /**
1008
+ * Opaque per-consumer metadata, keyed by consumer (e.g. `nl`). Core never
1009
+ * interprets it; it is passed through to the namespace schema unchanged.
1010
+ */
1011
+ annotations?: Readonly<Record<string, unknown>>;
1012
+ /**
1013
+ * Body keys a SQL dataset mirrors into dedicated `rows` columns, so filters
1014
+ * and sorts on them hit an index. The declaring plugin creates the columns in
1015
+ * its kernel migrations; the engine creates none. `column` is a bare
1016
+ * identifier.
1017
+ */
1018
+ promotedColumns?: Readonly<Record<string, {
1019
+ column: string;
1020
+ kind: 'boolean' | 'text';
1021
+ }>>;
1022
+ /**
1023
+ * Install types + mutations + policies into the registry. Invoked once at
1024
+ * registration time, BEFORE the engine is constructed. The plugin owns the
1025
+ * dataset handle it uses for resolver closures; wiring datasets into the
1026
+ * engine's `DatasetRegistry` is the app composition root's job.
1027
+ */
1028
+ install(ctx: NamespaceInstallContext): void | Promise<void>;
1029
+ }
1030
+ interface PluginLifecycleContext {
1031
+ /**
1032
+ * Tagged-union discriminant. Differentiates this context from
1033
+ * the structurally-similar `KernelLifecycleContext` so a coordinator's
1034
+ * `onStart` handler is type-incompatible with a substrate's
1035
+ * `onKernelReady` handler — the composition root sets this, and plugins
1036
+ * can also branch on it at runtime if a single helper handles both
1037
+ * lifecycle stages.
1038
+ */
1039
+ readonly lifecycle: 'coordinator';
1040
+ /**
1041
+ * Structured metric/log sink — the hosting binary picks the concrete surface
1042
+ * (stdout JSON, Prometheus counter, OpenTelemetry span, …). Plugins MUST NOT
1043
+ * assume the sink is synchronous or observable; the contract is fire-and-
1044
+ * forget per call.
1045
+ */
1046
+ metric(name: string, payload?: unknown): void;
1047
+ /**
1048
+ * Engine handle threaded into `onStart` so plugins that mutate their
1049
+ * registry post-construction (e.g. substrate-proposals' applyType /
1050
+ * applyField paths) can wire `engine.invalidateSchemaCaches(ns)` into
1051
+ * their replace flow. Engine construction completes before `onStart`
1052
+ * fires, so the handle is always live here.
1053
+ */
1054
+ engine: EngineHandle;
1055
+ }
1056
+ /**
1057
+ * Engine-facing input shape for `query` / `mutate` / `subscribe` / `stream`.
1058
+ * Declared here (rather than in substrate-core) so plugin surfaces can reference
1059
+ * the engine's call shape as a type without importing the engine package —
1060
+ * substrate-types stays zero-runtime.
1061
+ */
1062
+ interface FrameEntry {
1063
+ params?: Record<string, unknown>;
1064
+ fields?: Record<string, unknown>;
1065
+ /**
1066
+ * §5.13 dedup key. Present on a mutate frame entry opts the whole frame
1067
+ * into the engine's idempotency store; a repeat call with the same key
1068
+ * inside the TTL returns the cached envelope verbatim.
1069
+ */
1070
+ idempotencyKey?: string;
1071
+ }
1072
+ /**
1073
+ * Qualified frame (§4.7). Keys are `<ns>/<name>`. `<name>` is the type entry
1074
+ * name for query, or the mutation name for mutate.
1075
+ *
1076
+ * Batched mutate (§5.13): a mutate op-key MAY carry an array of `FrameEntry`
1077
+ * values. All frames under one op-key run serially inside the SAME
1078
+ * transaction — all-or-nothing per op-key, committed independently of other
1079
+ * op-keys. Single-frame op-keys share one transaction when they share a
1080
+ * substrate and are refused (`cross_tx_scope_refused`) when they do not.
1081
+ * Query / subscribe / stream op-keys reject array values.
1082
+ */
1083
+ type QualifiedFrame = Record<string, FrameEntry | Array<FrameEntry>>;
1084
+ interface EngineInput {
1085
+ frame: QualifiedFrame;
1086
+ ctx: Partial<RequestContext>;
1087
+ /**
1088
+ * §5.13 cancellation. Threaded into each resolver via `args.signal` so
1089
+ * resolvers observe cancel by polling `signal.aborted` or registering an
1090
+ * `abort` listener.
1091
+ */
1092
+ signal?: AbortSignal;
1093
+ /**
1094
+ * Page bounds for list reads, set by a transport serving remote callers:
1095
+ * a type read with no `limit` gets `defaultLimit`, one above `maxLimit` is
1096
+ * refused. Absent for in-process callers, which read what they ask for.
1097
+ */
1098
+ pageLimits?: {
1099
+ readonly defaultLimit: number;
1100
+ readonly maxLimit: number;
1101
+ };
1102
+ }
1103
+ /**
1104
+ * Per-namespace engine configuration. substrate-core imports this type rather
1105
+ * than redeclaring it.
1106
+ */
1107
+ interface NamespaceConfig {
1108
+ registry: Registry;
1109
+ /**
1110
+ * Marks a substrate-contributed namespace. Virtual namespaces
1111
+ * have NO dataset: the engine skips the dataset-presence check on
1112
+ * dispatch and leaves `args.dataset` undefined — resolvers compute from
1113
+ * `params`/`fields` and MUST NOT reach for a dataset handle. They are
1114
+ * structurally incapable of autoCRUD/storage — coordinators own data,
1115
+ * substrate surfaces own computation. Subscribe refuses these namespaces
1116
+ * with `subscription_unsupported_frame`.
1117
+ */
1118
+ virtual?: boolean;
1119
+ /** From `NamespaceDefinition.annotations`; surfaced on the schema, never hashed. */
1120
+ annotations?: Readonly<Record<string, unknown>>;
1121
+ }
1122
+ /**
1123
+ * Narrow engine handle threaded into scheduled-task / plugin-route contexts.
1124
+ * The concrete `Engine` class in `@mnmal-ai/substrate-core` satisfies this
1125
+ * structurally; plugin code binds against this handle without importing the
1126
+ * engine package.
1127
+ */
1128
+ interface EngineHandle {
1129
+ query(input: EngineInput): Promise<PackEnvelope>;
1130
+ mutate(input: EngineInput): Promise<PackEnvelope>;
1131
+ /**
1132
+ * Evaluate the read policy for a type entry without dispatching it.
1133
+ * Out-of-band read surfaces (kernel routes returning row data
1134
+ * outside frame dispatch — e.g. /substrate/v1/recall) call this so the same
1135
+ * composed policies that gate `query` gate them too. Fails closed on
1136
+ * unknown namespace/type and tombstoned namespaces.
1137
+ */
1138
+ evaluateReadPolicy(ns: string, type: string, identity: Identity | null, probe?: PolicyProbeContext): PolicyDecision;
1139
+ /**
1140
+ * Invalidate cached schema outputs after an out-of-band registry mutation
1141
+ * (e.g. `applyTypeProposal` / `applyFieldProposal` calling
1142
+ * `Registry.replace`). Without this hook, `federatedSchema()` and
1143
+ * `schemaFor(ns)` keep returning pre-mutation views. Optional `ns` argument also drops the per-namespace `schemaFor` cache;
1144
+ * omit to invalidate only the federated outputs.
1145
+ */
1146
+ invalidateSchemaCaches(ns?: string): void;
1147
+ /**
1148
+ * Register a new namespace at runtime. Throws on collision or on a
1149
+ * tombstoned name. Used by substrate-proposals' propose_namespace verb to provision
1150
+ * per-user / per-tenant namespaces without binary restart. Caller (typically
1151
+ * the resolver) is responsible for FPP semantics; this method is the
1152
+ * mechanical primitive.
1153
+ */
1154
+ addNamespace(ns: string, config: NamespaceConfig): void;
1155
+ /**
1156
+ * Mark a namespace as tombstoned. After this call:
1157
+ * - schemaFor(ns) throws `unknown namespace`
1158
+ * - federatedSchema() omits the ns
1159
+ * - query / mutate / subscribe against the ns return a per-key
1160
+ * `namespace_tombstoned` error
1161
+ * - existing live subscriptions on the ns are closed with a
1162
+ * `namespace_tombstoned` error frame
1163
+ *
1164
+ * Idempotent. The underlying NamespaceConfig stays in `#namespaces` for
1165
+ * concurrency safety (in-flight ops keep their references) — full physical
1166
+ * reclaim happens at engine restart, gated by whatever persistence layer
1167
+ * the host uses to decide which namespaces to re-install at boot. Tombstone
1168
+ * state itself is in-memory; restart wipes it.
1169
+ */
1170
+ tombstoneNamespace(ns: string): void;
1171
+ /**
1172
+ * Be told, after the fact, each time a namespace is tombstoned (a drop), so
1173
+ * a plugin that installed it can retire what it owns. A listener's throw is
1174
+ * reported as a metric and does not reach the dropper. Returns a disposer.
1175
+ */
1176
+ onNamespaceTombstoned(listener: (ns: string) => void): () => void;
1177
+ /**
1178
+ * Take part in every namespace drop's transaction: the drop route opens
1179
+ * `participant.namespaces` in its transaction too and runs `onDrop` after
1180
+ * the rows are gone and before it commits, so a throw rolls the drop back.
1181
+ * Returns a disposer.
1182
+ */
1183
+ addDropParticipant(participant: DropParticipant): () => void;
1184
+ /** The participants `addDropParticipant` registered, for the drop route. */
1185
+ dropParticipants(): readonly DropParticipant[];
1186
+ /**
1187
+ * Take a namespace off the engine and free its name for `addNamespace`.
1188
+ * Subscriptions on it close, its schema disappears, new ops answer
1189
+ * `unknown_namespace`; in-flight ops keep their resolved config. Undoes a
1190
+ * runtime add, e.g. a rolled-back propose_namespace. Idempotent.
1191
+ */
1192
+ removeNamespace(ns: string): void;
1193
+ /** Whether `ns` is on the engine, and if so whether it is still served. */
1194
+ namespaceState(ns: string): 'absent' | 'live' | 'tombstoned';
1195
+ /**
1196
+ * Construct a fresh empty Registry that the engine can accept via
1197
+ * `addNamespace`. Plugins call this to provision new namespaces at runtime
1198
+ * without taking a runtime dep on the concrete Registry class in substrate-core.
1199
+ */
1200
+ createRegistry(): Registry;
1201
+ /**
1202
+ * Look up the host-registered dataset for a namespace, or `undefined` if the
1203
+ * host has not provisioned one. Thin pass-through to the engine's
1204
+ * `DatasetRegistry.get`, surfaced on the handle so plugins running on
1205
+ * dynamically-added namespaces can resolve datasets without the host having
1206
+ * to plumb a `datasetFor` lookup through plugin config.
1207
+ *
1208
+ * Substrate selection remains the host's responsibility — this method only
1209
+ * exposes the lookup. Plugins that hot-add namespaces (substrate-proposals'
1210
+ * `propose_namespace`) MUST require the host to register the dataset before
1211
+ * the call; this method returns `undefined` for unregistered namespaces.
1212
+ */
1213
+ datasetFor(namespace: string): Dataset | undefined;
1214
+ }
1215
+ /**
1216
+ * Engine surface needed by substrate-pack-aware route helpers — extends the
1217
+ * dispatch handle with the two methods compose's `serializeEnvelope` /
1218
+ * `mutateRoute` need to drive positional encoding. The concrete
1219
+ * `Engine` class satisfies this structurally; tests + alt
1220
+ * implementations can satisfy it without depending on the engine package.
1221
+ */
1222
+ interface EncodeContext extends EngineHandle {
1223
+ /** Federated schema map (per-namespace Schema) for substrate-pack encoding. */
1224
+ federatedSchema(): Record<string, Schema>;
1225
+ /**
1226
+ * Look up a namespace's mutation-return registry view. Returns undefined
1227
+ * when the namespace isn't registered. The mutate route uses this to
1228
+ * resolve each frame key's `returns` FieldDef for positional encoding.
1229
+ */
1230
+ registryFor(namespace: string): {
1231
+ get(name: string): {
1232
+ returns?: FieldDef;
1233
+ } | undefined;
1234
+ } | undefined;
1235
+ }
1236
+ /**
1237
+ * Context threaded into every `ScheduledTask.handler` call.
1238
+ */
1239
+ interface ScheduledTaskContext {
1240
+ /** The owning plugin's `name`. */
1241
+ pluginName: string;
1242
+ /** Engine handle for read/write work performed by the task. */
1243
+ engine: EngineHandle;
1244
+ /** Structured metric sink — fire-and-forget. */
1245
+ metric(name: string, payload?: unknown): void;
1246
+ }
1247
+ interface ScheduledTask {
1248
+ /** Unique identifier within the plugin. Used in metric labels. */
1249
+ name: string;
1250
+ /** Fire interval in milliseconds. Minimum 100ms — smaller throws at register. */
1251
+ intervalMs: number;
1252
+ /** Fire once at registration in addition to the interval ticks. Default false. */
1253
+ runOnStart?: boolean;
1254
+ /** Handler — receives a context with engine access for read/write work. */
1255
+ handler(ctx: ScheduledTaskContext): void | Promise<void>;
1256
+ }
1257
+ /**
1258
+ * Context threaded into `CoordinatorPlugin.routes()` calls.
1259
+ */
1260
+ interface PluginRouteContext {
1261
+ /** The owning plugin's `name`. */
1262
+ pluginName: string;
1263
+ /** Engine handle for plugin-scoped routes that need to dispatch back through the engine. */
1264
+ engine: EngineHandle;
1265
+ /** Structured metric sink — fire-and-forget. */
1266
+ metric(name: string, payload?: unknown): void;
1267
+ }
1268
+ interface CoordinatorPlugin {
1269
+ name: string;
1270
+ namespaces: NamespaceDefinition[];
1271
+ /**
1272
+ * Plugin's bound contract version: a semver RANGE over the binary version,
1273
+ * e.g. `'>=4.1.0 <6.0.0'`.
1274
+ *
1275
+ * The ceiling tracks actual compatibility, not the next major: it moves
1276
+ * only when a major genuinely breaks the plugin-facing interface. A ceiling
1277
+ * that admits a major which did break lets the plugin load and misbehave
1278
+ * silently — if you cannot say whether the last major broke the plugin
1279
+ * interface, do not widen it.
1280
+ *
1281
+ * Enforced at boot: a plugin whose range excludes the running binary is
1282
+ * refused.
1283
+ */
1284
+ contractVersion: string;
1285
+ /**
1286
+ * Plugin-global policies applied to every resolver in every namespace the
1287
+ * plugin contributes. Composed by the loader via `and(...)` — the combined
1288
+ * policy must allow. Useful for cross-cutting concerns (audit logging,
1289
+ * rate limits, identity enrichment) that span multiple namespaces in the
1290
+ * same plugin. The composed result is surfaced through
1291
+ * `NamespaceInstallContext.pluginPolicy`.
1292
+ */
1293
+ policies?: Policy[];
1294
+ /**
1295
+ * Post-register lifecycle hook. Fires after every plugin's `install()`
1296
+ * resolves — use this for resource priming that needs the full namespace
1297
+ * map (e.g. cross-plugin edge warmup).
1298
+ */
1299
+ onStart?(ctx: PluginLifecycleContext): void | Promise<void>;
1300
+ /**
1301
+ * Pre-shutdown lifecycle hook. Fires when the host calls `compose()`'s
1302
+ * returned `stop()` (which the binary's SIGTERM handler invokes inside
1303
+ * the `SUBSTRATE_SHUTDOWN_GRACE_MS` window). Hooks run in REVERSE
1304
+ * registration order so plugins tear down in the inverse of the order
1305
+ * they came up — late-loading plugins that depended on earlier ones get
1306
+ * to release their handles first.
1307
+ *
1308
+ * Use for resources the OS won't reap on process exit:
1309
+ * - subprocess children that should receive SIGTERM cleanly
1310
+ * - long-lived `setInterval` timers (`.unref()` keeps them from
1311
+ * blocking exit, but explicit teardown is still cleaner for tests)
1312
+ * - WebSocket subscriptions / outbound connections that should close
1313
+ * cooperatively rather than dropping mid-request
1314
+ *
1315
+ * Errors are caught + logged via the lifecycle metric sink under
1316
+ * `plugin_on_stop_error` — one plugin's failed teardown does NOT abort
1317
+ * other plugins' teardown. The engine + pg pool are still live during
1318
+ * onStop calls, so plugins can do final writes (e.g. an audit row
1319
+ * recording the shutdown). After all onStop hooks resolve, the server
1320
+ * stops accepting connections and the substrate's `closeStore()` runs.
1321
+ *
1322
+ * Symmetric to `onStart`. Skipped (no-op) when omitted.
1323
+ */
1324
+ onStop?(ctx: PluginLifecycleContext): void | Promise<void>;
1325
+ /**
1326
+ * Scheduled tasks — the binary ticks these on `.unref()`'d intervals.
1327
+ * Registered with the shared `TaskScheduler` at compose time and started
1328
+ * after the server's `start()` resolves.
1329
+ */
1330
+ schedule?: ScheduledTask[];
1331
+ /**
1332
+ * Mount plugin-scoped HTTP/WS routes. Called once at compose-time with a
1333
+ * `PluginRouter` pre-prefixed `/substrate/v1/plugins/<name>` by the server impl. The
1334
+ * router surface matches `PluginRouter` in `./server.ts`.
1335
+ *
1336
+ * With auth on, HTTP routes require `read` for GET and `mutate` otherwise,
1337
+ * granted in one of this plugin's `namespaces`; a plugin with no namespaces
1338
+ * accepts the capability granted in any namespace.
1339
+ */
1340
+ routes?(router: PluginRouter, ctx: PluginRouteContext): void | Promise<void>;
1341
+ /**
1342
+ * Optional onboarding contribution. When set, the hosting binary's
1343
+ * `GET /substrate/v1/onboard` aggregates this record under
1344
+ * `instructions.plugins.<name>` and enumerates the plugin's conventional
1345
+ * `/substrate/v1/plugins/<name>/onboard` route under `instructions.pluginRoutes`. Use
1346
+ * this to teach agents about the plugin's types, write flows, or any
1347
+ * plugin-specific grammar a cold-start agent would otherwise have to
1348
+ * discover per endpoint. The shape is free-form — the binary round-trips
1349
+ * it verbatim.
1350
+ */
1351
+ onboardInstructions?: Record<string, unknown>;
1352
+ }
1353
+ /**
1354
+ * Substrate-tier plugin. Augments the kernel rather than the agent-facing
1355
+ * surface. Composes BEFORE coordinator plugins so coordinators can rely on
1356
+ * substrate registrations being live.
1357
+ *
1358
+ * SubstratePlugins do NOT own data namespaces — that's a CoordinatorPlugin
1359
+ * concern (a substrate may claim a virtual `kernelNamespace`).
1360
+ */
1361
+ interface KernelPlugin {
1362
+ /** Unique plugin name. Used in metric labels + collision detection. */
1363
+ name: string;
1364
+ /**
1365
+ * Plugin's bound contract version: a semver RANGE over the binary version,
1366
+ * e.g. `'>=4.1.0 <6.0.0'`. Required on substrate plugins. Checked by
1367
+ * `composeFromManifests` and REFUSED at boot on mismatch; the
1368
+ * ceiling tracks actual compatibility rather than the next major boundary.
1369
+ * See the note on `CoordinatorPlugin.contractVersion` for both.
1370
+ */
1371
+ contractVersion: string;
1372
+ /**
1373
+ * Schema migrations the plugin contributes. Applied in declared order
1374
+ * on first install AND on every binary boot (idempotently, gated by
1375
+ * the migrations tracking table seeded by the first KernelPlugin
1376
+ * to populate this slot).
1377
+ */
1378
+ migrations?: KernelMigration[];
1379
+ /**
1380
+ * Filter operators contributed to the where-clause grammar. Each entry
1381
+ * registers a custom operator (e.g. `embeddingSimilar`) the engine's
1382
+ * query validator + substrate executor can dispatch to.
1383
+ */
1384
+ filterOperators?: Record<string, FilterOperatorDef>;
1385
+ /**
1386
+ * Top-level kernel route claims. Plugin reserves a path under /substrate/v1/.
1387
+ * First-claim wins; collision = boot refusal with actionable error.
1388
+ */
1389
+ kernelRoutes?: KernelRouteClaim[];
1390
+ /**
1391
+ * Top-level MCP tool registrations. Tool name registers globally with
1392
+ * the MCP server (no /plugins/ prefix on MCP — tools are flat).
1393
+ */
1394
+ mcpTools?: McpToolRegistration[];
1395
+ /**
1396
+ * Frame-surface contribution. Claims one namespace in the engine registry
1397
+ * carrying resolver-backed query types + mutations — no dataset, no
1398
+ * autoCRUD. Dispatch/policy/idempotency/pack/schema/NL/MCP all inherit from
1399
+ * the normal frame path.
1400
+ */
1401
+ kernelNamespace?: KernelNamespaceContribution;
1402
+ /**
1403
+ * Post-register lifecycle hook. Fires after every KernelPlugin's
1404
+ * migrations + registrations resolve, BEFORE any coordinator plugin
1405
+ * composes. Use for resource priming the kernel needs before
1406
+ * coordinators arrive.
1407
+ */
1408
+ onKernelReady?(ctx: KernelLifecycleContext): void | Promise<void>;
1409
+ /**
1410
+ * Contribute postWrite hooks for a coordinator namespace at install time.
1411
+ * Called by the engine ONCE per registered coordinator namespace, AFTER
1412
+ * substrate composition completes. Returned hooks are merged into the
1413
+ * type's effective postWrite chain alongside the type's own inline
1414
+ * `postWrite` (if any). Substrate-supplied hooks run AFTER the type's
1415
+ * inline hook in chain order.
1416
+ *
1417
+ * Use this to inspect `namespace.types[T].embed` and emit embedding
1418
+ * hooks per type without coupling the binary to plugin internals.
1419
+ *
1420
+ * Returns: a record mapping type names to PostWriteHook contributions.
1421
+ * Type names not in the record receive no contribution.
1422
+ */
1423
+ contributePostWrites?: (namespace: NamespaceDefinition) => Record<string, PostWriteHook>;
1424
+ }
1425
+ /** Single migration unit. */
1426
+ interface KernelMigration {
1427
+ /** Unique id within the plugin. Stored in migrations tracking table. */
1428
+ id: string;
1429
+ /** Apply migration. Called only when this migration's id is absent from the migrations table. */
1430
+ apply(ctx: KernelMigrationContext): Promise<void>;
1431
+ /** Inverse — drops what apply created. */
1432
+ rollback?(ctx: KernelMigrationContext): Promise<void>;
1433
+ }
1434
+ interface KernelMigrationContext {
1435
+ /**
1436
+ * Direct SQL handle for postgres-backed deployments; null when the
1437
+ * binary is running against the in-memory dataset.
1438
+ */
1439
+ sql: unknown | null;
1440
+ metric(name: string, payload?: unknown): void;
1441
+ }
1442
+ /**
1443
+ * Where-clause operator extension.
1444
+ *
1445
+ * The operator's name is the Record key it's registered under in
1446
+ * `KernelPlugin.filterOperators`.
1447
+ *
1448
+ * `execute` is awaited by the pre-resolve pass (`@mnmal-ai/substrate-filter`'s
1449
+ * `preResolveExtensionOperatorsDetailed`) and must resolve to an ordered,
1450
+ * scored `{ hits: [{ id: string; score: number; vector?: number[] }, ...] }`
1451
+ * envelope; any other shape throws `ExtensionOperatorResultError`. Relevance
1452
+ * order is preserved in the rewritten `id IN`, and score/vector are surfaced
1453
+ * via the pre-pass meta side-channel for the datasets to stitch onto rows.
1454
+ */
1455
+ interface FilterOperatorDef {
1456
+ validate(value: unknown): {
1457
+ ok: true;
1458
+ value: unknown;
1459
+ } | {
1460
+ ok: false;
1461
+ reason: string;
1462
+ };
1463
+ execute(value: unknown, context: unknown): Promise<unknown>;
1464
+ /**
1465
+ * Computed projection field names the operator contributes per hit (e.g.
1466
+ * `['_score', '_vector']`). The engine refuses a projection of one of these
1467
+ * fields unless its operator is in the where-clause.
1468
+ */
1469
+ computedFields?: string[];
1470
+ }
1471
+ /**
1472
+ * Query-only virtual type contributed by a substrate plugin.
1473
+ * `fields` reuses the FieldDef DSL so schema publication + client typing
1474
+ * work unchanged. The resolver receives the standard (ctx, args) pair; the
1475
+ * engine leaves `args.dataset` undefined for virtual namespaces — resolvers
1476
+ * compute from `params`/`fields` and MUST NOT reach for a dataset handle.
1477
+ */
1478
+ interface VirtualTypeDef {
1479
+ fields: Record<string, FieldDef>;
1480
+ resolver: RegistryEntryResolver;
1481
+ }
1482
+ /** Mutation contributed by a substrate plugin under its virtual namespace. */
1483
+ interface VirtualMutationDef {
1484
+ resolver: RegistryEntryResolver;
1485
+ /** Optional params schema published into the namespace schema. */
1486
+ params?: Record<string, FieldDef>;
1487
+ }
1488
+ /**
1489
+ * A substrate plugin's claimed frame surface.
1490
+ * Registered into the engine's namespaces map as `{ registry, virtual: true }`.
1491
+ * Collision posture mirrors KernelRouteClaim: second claim = boot refusal.
1492
+ */
1493
+ interface KernelNamespaceContribution {
1494
+ namespace: string;
1495
+ types?: Record<string, VirtualTypeDef>;
1496
+ mutations?: Record<string, VirtualMutationDef>;
1497
+ }
1498
+ /** Top-level kernel route reservation. */
1499
+ interface KernelRouteClaim {
1500
+ path: string;
1501
+ method: HttpMethod;
1502
+ handler: HttpHandler;
1503
+ /**
1504
+ * Capability the host must check before dispatching, when auth is enabled.
1505
+ * REQUIRED — `'public'` is how a route opts out, so opting out is a
1506
+ * declaration rather than an omission.
1507
+ *
1508
+ * Do not make this optional: kernel routes mount via the host's raw
1509
+ * `server.route`, which applies no gate of its own, so a route with no
1510
+ * capability would get no auth wrapper at all.
1511
+ */
1512
+ capability: 'read' | 'mutate' | 'admin' | 'public';
1513
+ }
1514
+ /** Top-level MCP tool registration. */
1515
+ interface McpToolRegistration {
1516
+ name: string;
1517
+ description: string;
1518
+ inputSchema: unknown;
1519
+ handler(input: unknown): Promise<unknown>;
1520
+ }
1521
+ interface KernelLifecycleContext {
1522
+ /**
1523
+ * Tagged-union discriminant. Differentiates this context from the
1524
+ * structurally-similar `PluginLifecycleContext`, which would otherwise be
1525
+ * interchangeable under structural typing.
1526
+ */
1527
+ readonly lifecycle: 'kernel';
1528
+ /**
1529
+ * Direct SQL handle; null when the binary runs against the in-memory
1530
+ * dataset. Same shape and same null semantics as
1531
+ * `KernelMigrationContext.sql`.
1532
+ *
1533
+ * For convergent, run-every-boot reconciliation: a migration runs only once
1534
+ * per `id`, so it cannot re-scope objects it already created.
1535
+ */
1536
+ sql: unknown | null;
1537
+ /**
1538
+ * Namespaces DECLARED by the coordinator plugins this binary loaded, in
1539
+ * load order. Empty when none are configured.
1540
+ *
1541
+ * Declared, not installed: coordinators compose AFTER substrate, so the
1542
+ * engine has not yet registered them.
1543
+ *
1544
+ * Read these rather than adding a namespace knob to substrate config, which
1545
+ * could silently disagree with what the coordinator uses.
1546
+ */
1547
+ coordinatorNamespaces: readonly string[];
1548
+ /**
1549
+ * The same namespaces, attributed to the coordinator that declared each.
1550
+ * Declaration order preserved within a plugin.
1551
+ *
1552
+ * The two absent cases differ and consumers must branch on them:
1553
+ * - `undefined` — this host does not supply attribution (e.g. an older
1554
+ * binary); do not treat it as an empty list
1555
+ * - `[]` — attribution supplied, and there are no coordinators
1556
+ *
1557
+ * Filtering on `plugin === 'some-name'` makes the coordinator's `name` a
1558
+ * contract term: hold it in one constant shared with the coordinator and pin
1559
+ * it with a test, or a rename makes the filter silently match nothing.
1560
+ */
1561
+ coordinatorNamespacesByPlugin?: readonly {
1562
+ plugin: string;
1563
+ namespace: string;
1564
+ }[];
1565
+ metric(name: string, payload?: unknown): void;
1566
+ }
1567
+ //#endregion
1568
+ export { PolicyProbeContext as $, ScheduledTask as A, StartOpts as B, QualifiedFrame as C, RegistryEntryInput as D, RegistryEntry as E, HttpMethod as F, WsConnection as G, SubstrateResponse as H, PluginRouter as I, AutoCrudVerb as J, WsHandler as K, RequestObservation as L, VirtualMutationDef as M, VirtualTypeDef as N, RegistryEntryKind as O, HttpHandler as P, PolicyDecision as Q, RequestObserver as R, PostWriteHook as S, WriteResult as St, RegistryBase as T, SubstrateServer as U, SubstrateRequest as V, TlsConfig as W, Obligation as X, Identity as Y, Policy as Z, NamespaceDefinition as _, ReadResult as _t, EngineHandle as a, TypedResolver as at, PluginLifecycleContext as b, WhereClause as bt, FrameEntry as c, Dataset as ct, KernelMigrationContext as d, DropResult as dt, RequestContext as et, KernelNamespaceContribution as f, FieldKind as ft, NamespaceConfig as g, ReadParams as gt, McpToolRegistration as h, OrderByClause as ht, EncodeContext as i, RowFilterObligation as it, ScheduledTaskContext as j, RegistryEntryResolver as k, KernelLifecycleContext as l, DatasetRegistry as lt, KernelRouteClaim as m, FilterCapabilities as mt, DropParticipant as n, ResolverArgs as nt, EngineInput as o, WriteEvent as ot, KernelPlugin as p, FieldPredicate as pt, AfterTxWork as q, EmbedSourceContext as r, ResolverReturn as rt, FilterOperatorDef as s, ConditionalUpdateResult as st, CoordinatorPlugin as t, Resolver as tt, KernelMigration as u, DeleteResult as ut, NamespaceInstallContext as v, TxScopeHandles as vt, Registry as w, PluginRouteContext as x, WriteOptions as xt, NamespaceTypeDef as y, UpdateFieldRef as yt, RuntimeOp as z };