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

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-DOXGRz50.js +1535 -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-BuQQEzL-.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-5hVbeiAu.js +1797 -0
  35. package/dist/src-C4DzaIQZ.js +837 -0
  36. package/dist/src-CjEwiKXw.js +2327 -0
  37. package/dist/src-DuopV8u7.js +2408 -0
  38. package/dist/src-YXlv_RyL.js +13524 -0
  39. package/dist/src-zcyUofMJ.js +1015 -0
  40. package/dist/substrate-admin.js +808 -0
  41. package/dist/substrate.js +5482 -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,1240 @@
1
+ import { C as Id, E as Row, _ as EdgesStore, b as ActorIdentity, f as CanDeleteResult, g as EdgeWriteInput, h as EdgeRef, l as PackEnvelope, m as EdgePatch, p as Edge, u as Schema } from "./schema-g4FQLr0V.js";
2
+ import { a as RuntimeErrors, n as ResolveObservation, r as ResolverStat, s as SlowRequest, t as ProcessStat } from "./runtime-metrics-DwpDJ8vz.js";
3
+ import { $ as PolicyProbeContext, A as ScheduledTask, B as StartOpts, C as QualifiedFrame, D as RegistryEntryInput, E as RegistryEntry, F as HttpMethod, G as WsConnection, H as SubstrateResponse, I as PluginRouter, K as WsHandler, P as HttpHandler, Q as PolicyDecision, R as RequestObserver, St as WriteResult, T as RegistryBase, U as SubstrateServer, V as SubstrateRequest, Y as Identity, _t as ReadResult, a as EngineHandle, ct as Dataset, dt as DropResult, et as RequestContext, g as NamespaceConfig, gt as ReadParams, lt as DatasetRegistry, mt as FilterCapabilities, n as DropParticipant, o as EngineInput, p as KernelPlugin, st as ConditionalUpdateResult, t as CoordinatorPlugin, ut as DeleteResult, w as Registry$1, xt as WriteOptions, yt as UpdateFieldRef, z as RuntimeOp } from "./plugin-t2g2wX0b.js";
4
+ import { a as WsResponseFrame, f as IdempotencyStore, l as SweepDeps, s as BridgeRegistry, u as SweepState } from "./ws-C72iVS5T.js";
5
+ import { t as Embedder } from "./types-8c0gtnd2.js";
6
+ //#region ../../packages/substrate-compose/src/auth.d.ts
7
+ type JwtAlg = 'RS256' | 'ES256' | 'HS256' | 'EdDSA';
8
+ interface AuthKey {
9
+ kid?: string;
10
+ alg: JwtAlg;
11
+ /** PEM for RS256/ES256/EdDSA, HMAC secret (utf8) for HS256. */
12
+ publicKey: string;
13
+ /** Provenance: 'agent' attributes writes as kind:'agent'; default 'user'. */
14
+ kind?: 'user' | 'agent';
15
+ }
16
+ interface AuthConfig {
17
+ keys: Array<AuthKey>;
18
+ /** JWT claim value that, when present in `capabilities`, grants admin. */
19
+ adminCapability?: string;
20
+ /**
21
+ * Dataset-backed key registry (§5.12). When set, `verifyBearerToken`
22
+ * consults it after the file-based `keys` array for tokens signed with an
23
+ * asymmetric alg. Rows looked up via the registry also enforce a
24
+ * claim-vs-row intersection on `ns` / `capabilities` — the JWT payload
25
+ * cannot inflate its scope beyond what the Key row authorises.
26
+ * File-based keys trust their token claims verbatim.
27
+ */
28
+ keyRegistry?: KeyRegistry;
29
+ /**
30
+ * `'required'` (default): a missing or invalid token → 401.
31
+ *
32
+ * `'attribute'`: a missing token is admitted to READS — routes gated `read`
33
+ * or gated on nothing — and refused everywhere else. An invalid token is
34
+ * still 401 in BOTH modes. Anonymous writes are refused even against a
35
+ * namespace whose policy declares `writes: 'open'`: writes carry provenance.
36
+ *
37
+ * The two refusals name themselves differently, because they need different
38
+ * fixes: a tokenless caller gets `detail`, a rejected credential gets
39
+ * `reason` where there is a safe signal.
40
+ */
41
+ mode?: 'required' | 'attribute';
42
+ /**
43
+ * Clock-skew tolerance in seconds applied to `exp` / `nbf`.
44
+ * `exp` rejects only when the token is more than `leewaySeconds` past expiry;
45
+ * `nbf` rejects only when it is more than `leewaySeconds` before validity.
46
+ * Absent / `0` is strict.
47
+ */
48
+ leewaySeconds?: number;
49
+ /**
50
+ * Longest a token may still have to run, in seconds: `exp` more than this
51
+ * (plus leeway) in the future is refused, so a stolen token cannot be a
52
+ * permanent credential. Default {@link DEFAULT_MAX_TOKEN_LIFETIME_SECONDS};
53
+ * `0` disables the bound.
54
+ */
55
+ maxTokenLifetimeSeconds?: number;
56
+ /**
57
+ * The origins this server answers as (`SUBSTRATE_PUBLIC_ORIGIN`). When set, a
58
+ * token carrying `aud` must name one of them; a token with no `aud` is still
59
+ * accepted. Absent → `aud` is not checked.
60
+ */
61
+ audiences?: ReadonlyArray<string>;
62
+ /**
63
+ * Where the deployment's agent DIRECTORY lives, so `POST /substrate/v1/_system/keys` can
64
+ * write a credential and its directory row atomically. Absent →
65
+ * the route registers the credential alone and reports `directory.created:
66
+ * false, reason: 'not_configured'` rather than staying quiet about it.
67
+ */
68
+ identityDirectory?: IdentityDirectoryConfig;
69
+ }
70
+ /**
71
+ * Sign an HS256 JWT. Test-only helper — hand-rolling both sides means auth
72
+ * round-trip tests depend on nothing outside node:crypto.
73
+ */
74
+ export declare function signHs256(payload: Record<string, unknown>, secret: string, header?: {
75
+ kid?: string;
76
+ }): string;
77
+ //#endregion
78
+ //#region ../../packages/substrate-compose/src/_system/types.d.ts
79
+ /**
80
+ * Where the operator's agent DIRECTORY lives, so `POST /substrate/v1/_system/keys` can
81
+ * write the credential and the directory row in ONE transaction.
82
+ *
83
+ * A usable identity is two rows: the `_system/Key` credential (what
84
+ * verifies a JWT) and a directory row (what is listed and what mail routes
85
+ * against). The directory type belongs to a plugin (e.g.
86
+ * `acme/AgentIdentity`), so the operator names it here and core stays
87
+ * generic.
88
+ *
89
+ * Unset is supported: the route writes the credential alone and says so in
90
+ * its response (`directory.created: false`, `reason: 'not_configured'`).
91
+ */
92
+ interface IdentityDirectoryConfig {
93
+ /**
94
+ * Qualified TYPE key of the directory, e.g. `'acme/AgentIdentity'`. The
95
+ * autoCRUD create mutation is derived as `create<Type>`. Split rather than
96
+ * taking the mutation name directly because the policy pre-flight
97
+ * (`engine.evaluateWritePolicy`) is asked about a TYPE.
98
+ */
99
+ readonly frame: string;
100
+ /** Directory field carrying the kid. Always forced to the registered kid. Default `'kid'`. */
101
+ readonly kidField?: string;
102
+ /**
103
+ * Directory field carrying the host — everything after the last `@` in the
104
+ * kid. `null` disables the derivation. Default `'host'`, which is
105
+ * non-nullable on `acme/AgentIdentity` and is why deriving it beats
106
+ * making every caller repeat it.
107
+ */
108
+ readonly hostField?: string | null;
109
+ /** Directory field carrying the human-readable name. Default `'displayName'`. */
110
+ readonly displayNameField?: string | null;
111
+ /** Static params merged beneath the derived + caller-supplied ones. */
112
+ readonly defaults?: Readonly<Record<string, unknown>>;
113
+ }
114
+ /** Subset of `JwtAlg` the dataset accepts. HS256 is rejected at write-time. */
115
+ type KeyAlgorithm = 'EdDSA' | 'RS256' | 'ES256';
116
+ //#endregion
117
+ //#region ../../packages/substrate-compose/src/_system/registry.d.ts
118
+ interface KeyRecord {
119
+ kid: string;
120
+ algorithm: KeyAlgorithm;
121
+ /** PEM-encoded public key (SPKI or PKCS#1). */
122
+ publicKey: string;
123
+ namespaces: Array<string>;
124
+ capabilities: Array<string>;
125
+ revokedAt: Date | null;
126
+ }
127
+ interface KeyRegistry {
128
+ /** Synchronous lookup against the in-memory cache. Returns null when not found or revoked. */
129
+ lookup(kid: string): KeyRecord | null;
130
+ /**
131
+ * Install a row the caller already holds. Preferred over `refresh` for any
132
+ * caller that has just written the row: it needs no read, so it cannot be
133
+ * defeated by transaction visibility.
134
+ *
135
+ * Returns false when the row does not project (unknown algorithm, missing
136
+ * key material) — the caller has handed over something unusable and the
137
+ * cache is left untouched rather than being corrupted by a partial write.
138
+ */
139
+ install(row: Row): boolean;
140
+ /**
141
+ * Re-read a single row from the dataset. ONLY sound for callers that are
142
+ * outside the writing transaction — an in-tx caller cannot see its own
143
+ * write and will evict the very key it just created. Such callers want
144
+ * `install` instead.
145
+ */
146
+ refresh(kid: string): Promise<void>;
147
+ /** Remove a kid from the cache (for delete/purge). */
148
+ evict(kid: string): void;
149
+ /** Reload every row — called once at compose-time. */
150
+ primeFromDataset(): Promise<void>;
151
+ /**
152
+ * Stop the optional periodic re-prime timer. No-op when re-prime is
153
+ * disabled. Called on graceful shutdown; the timer is `.unref()`-ed so this
154
+ * is only strictly needed for deterministic test tear-down.
155
+ */
156
+ dispose(): void;
157
+ }
158
+ //#endregion
159
+ //#region ../../packages/substrate-compose/src/_system/rate-limit.d.ts
160
+ /**
161
+ * In-process sliding-window rate limiter (spec §5.12).
162
+ *
163
+ * Used to cap anonymous `/substrate/v1/_system/register` traffic per source IP
164
+ * (default 10 requests / 60s). In-process by design: no external store for a
165
+ * rarely-exercised admin surface.
166
+ *
167
+ * Algorithm: per-key array of request timestamps within the window. On each
168
+ * `check(key)` the limiter prunes stamps older than `windowMs`, compares the
169
+ * remaining length against `maxRequests`, and either records the new stamp
170
+ * (allow) or computes `retryAfterMs` from the oldest surviving stamp (deny).
171
+ *
172
+ * A scavenger interval sweeps empty buckets so a one-off burst from an IP
173
+ * doesn't leak memory. The timer is `.unref()`-ed so it never holds the
174
+ * process open; tests that want to clean up deterministically call `dispose()`.
175
+ */
176
+ interface RateLimitResult {
177
+ allowed: boolean;
178
+ /**
179
+ * Milliseconds the caller should wait before retrying. Present (and positive)
180
+ * only when `allowed === false`; `0` on allow.
181
+ */
182
+ retryAfterMs: number;
183
+ }
184
+ interface RateLimiter {
185
+ check(key: string): RateLimitResult;
186
+ /** Drop the scavenger interval. Tests call this to let the event loop settle. */
187
+ dispose(): void;
188
+ }
189
+ //#endregion
190
+ //#region ../../packages/substrate-core/src/registry.d.ts
191
+ type TypeKey = string | {
192
+ readonly name: string;
193
+ };
194
+ declare class Registry extends RegistryBase implements Registry$1 {
195
+ private readonly entries;
196
+ protected performRegister(key: TypeKey, input: RegistryEntryInput): void;
197
+ /**
198
+ * Replace an existing entry atomically. Throws UnknownType when the entry is
199
+ * not present — callers adding a new type should use register() instead.
200
+ * Mirrors register()'s defaults for policy, kind, fields, params, returns.
201
+ */
202
+ protected performReplace(key: TypeKey, input: RegistryEntryInput): void;
203
+ protected performUnregister(key: TypeKey): void;
204
+ get(key: TypeKey): RegistryEntry | undefined;
205
+ has(key: TypeKey): boolean;
206
+ all(): IterableIterator<[string, RegistryEntry]>;
207
+ }
208
+ //#endregion
209
+ //#region ../../packages/substrate-core/src/engine/internals.d.ts
210
+ type MetricFn = (name: string, payload?: unknown) => void;
211
+ interface EngineOptions {
212
+ namespaces: Map<string, NamespaceConfig>;
213
+ datasets: DatasetRegistry;
214
+ /**
215
+ * Engine-scoped edges store (§4.6). Threaded into every resolver as
216
+ * `args.edges`. Required — every engine has one, even if the only consumer
217
+ * is autoCRUD's edge-aware delete. Edges are inherently cross-namespace
218
+ * (`EdgeRef.ns`), so the store is singular at engine scope, not per-ns.
219
+ */
220
+ edges: EdgesStore;
221
+ metric?: MetricFn;
222
+ /**
223
+ * One observation per key resolved locally: duration and outcome. Called once
224
+ * per query key, once per single-frame mutate key and once per element of a
225
+ * batched array (under its op key). Deliberately NOT observed: bridged keys,
226
+ * the `aborted` / `batched_not_supported` pre-dispatch returns in `query()`,
227
+ * and empty arrays, since keys that never reach a resolver are not resolver
228
+ * latency. Elements of a batched array that succeeded before a
229
+ * `BatchedFrameRefusal` rollback stay observed as `ok`; the rollback itself is
230
+ * visible as the `batched_frame_rolled_back` error. Errors thrown by the hook,
231
+ * and rejections of a returned thenable, are swallowed. When absent, the engine
232
+ * does no timing at all.
233
+ */
234
+ onResolve?: (o: ResolveObservation) => void;
235
+ /**
236
+ * Idempotency dedup (§5.13). Absent → no dedup; `FrameEntry.idempotencyKey`
237
+ * is ignored on mutate (queries ignore it unconditionally). Present → the
238
+ * engine consults `store.get` before dispatch and `store.put` after a
239
+ * successful mutate frame. `defaultTtlMs` defaults to 24h per spec.
240
+ */
241
+ idempotency?: {
242
+ store: IdempotencyStore;
243
+ defaultTtlMs?: number;
244
+ };
245
+ /**
246
+ * Subscription back-pressure (§5.13). Per-subscription pending-frame
247
+ * threshold; when exceeded the engine emits a final `subscription_overloaded`
248
+ * error frame, an `end` frame, and drops the entry from the bus. Default 256.
249
+ */
250
+ subscriptions?: {
251
+ queueLimit?: number;
252
+ /**
253
+ * Most rows a type subscription's snapshot may hold. A snapshot with more
254
+ * is refused with `snapshot_too_large`. Unset reads the snapshot unbounded.
255
+ */
256
+ snapshotLimit?: number;
257
+ };
258
+ /**
259
+ * Sweep-adjacent hooks used by the §6.4 lifecycle subscription, which
260
+ * builds `applyLostNamespace`'s `SweepDeps` from them. `bridges` defaults to
261
+ * a no-op registry (every namespace local and reachable); a non-local
262
+ * namespace present in it is proxied through the bridge (§5.8).
263
+ */
264
+ sweepHooks?: {
265
+ bridges?: BridgeRegistry;
266
+ };
267
+ }
268
+ /**
269
+ * `__brand` is a phantom literal — purely a type-level marker, no runtime
270
+ * presence (constructors don't set it). Distinguishes `SubscriptionHandle`
271
+ * from the structurally-identical `StreamHandle` so a stream handle returned
272
+ * by `engine.stream(...)` isn't silently accepted where a subscription handle
273
+ * is expected (and vice versa). The literal types `'SubscriptionHandle'`
274
+ * vs `'StreamHandle'` are incompatible even when both fields are optional,
275
+ * so TS rejects cross-assignment at every call seam.
276
+ */
277
+ /**
278
+ * Reason for a subscription teardown. Threaded through `SubscriptionHandle.cancel()`
279
+ * so the engine can emit a per-reason metric (`engine_subscription_closed_<reason>`)
280
+ * without the call site knowing which metric string to use.
281
+ *
282
+ * - `'cancel'` — explicit client-driven cancel (op: 'cancel') or direct handle use
283
+ * - `'socket_close'` — underlying WS socket closed (conn.onClose)
284
+ * - `'shutdown'` — server-initiated graceful shutdown (conn.onShutdown)
285
+ */
286
+ type SubscriptionCancelReason = 'cancel' | 'socket_close' | 'shutdown';
287
+ interface SubscriptionHandle {
288
+ readonly __brand?: 'SubscriptionHandle';
289
+ readonly id: string;
290
+ cancel(reason?: SubscriptionCancelReason): void;
291
+ }
292
+ interface SubscribeInput {
293
+ /**
294
+ * Phantom brand, never set at runtime. Without it this is structurally
295
+ * interchangeable with `StreamInput`, so subscribe/stream inputs could be
296
+ * swapped with no type error.
297
+ */
298
+ readonly __brand?: 'SubscribeInput';
299
+ id: string;
300
+ frame: QualifiedFrame;
301
+ ctx: Partial<RequestContext>;
302
+ /**
303
+ * Frame sink. Sync-returning callbacks are still valid; the engine awaits
304
+ * whatever `onFrame` returns so back-pressure-aware transports (e.g. WS
305
+ * send-buffer drain) can resolve asynchronously. The fanout loop tracks
306
+ * pending (unsettled) calls per subscription and tears the entry down when
307
+ * the count exceeds `EngineOptions.subscriptions.queueLimit` (§5.13).
308
+ */
309
+ onFrame: (frame: WsResponseFrame) => void | Promise<void>;
310
+ }
311
+ /**
312
+ * Phantom `__brand` literal — same intent as `SubscriptionHandle.__brand`.
313
+ */
314
+ interface StreamHandle {
315
+ readonly __brand?: 'StreamHandle';
316
+ readonly id: string;
317
+ cancel(): void;
318
+ }
319
+ /**
320
+ * §5.5 stream dispatch input. One qualified key per call — multi-key streams
321
+ * conflate emission orderings, so the engine rejects them with
322
+ * `stream_multi_key`.
323
+ *
324
+ * `onFrame` is async so the transport layer can await send-buffer drains
325
+ * between chunks. The engine awaits it between every chunk emission, which is
326
+ * how back-pressure lives at the route layer without leaking transport
327
+ * details into the engine.
328
+ *
329
+ * `signal` is an optional external abort source (socket close, shutdown).
330
+ * Internally the engine always creates its own `AbortController` so
331
+ * `handle.cancel()` works; the external signal is folded in as a second
332
+ * trigger.
333
+ */
334
+ interface StreamInput {
335
+ /** Phantom brand, never set at runtime. See `SubscribeInput.__brand`. */
336
+ readonly __brand?: 'StreamInput';
337
+ id: string;
338
+ frame: QualifiedFrame;
339
+ ctx: Partial<RequestContext>;
340
+ onFrame: (frame: WsResponseFrame) => void | Promise<void>;
341
+ signal?: AbortSignal;
342
+ }
343
+ /**
344
+ * One live subscription entry keyed by `(ns, type)`. A multi-key subscribe
345
+ * request produces one entry per qualified key; they share the same client-
346
+ * supplied `id` and all tear down together when `SubscriptionHandle.cancel`
347
+ * runs.
348
+ *
349
+ * `currentRowIds` tracks which ids matched the where clause at snapshot time;
350
+ * the fanout path consults it to decide whether a post-commit row that still
351
+ * matches is an `add` (id not previously seen) vs an `update` (id already
352
+ * known).
353
+ */
354
+ interface SubscriptionEntryStat {
355
+ readonly id: string;
356
+ readonly ns: string;
357
+ readonly type: string;
358
+ readonly queueLength: number;
359
+ }
360
+ interface SubscriptionStatsSnapshot {
361
+ /** Total registered entries (same basis as activeSubscriptionCount). */
362
+ readonly count: number;
363
+ /** Largest per-entry queue length at snapshot time; 0 when idle/empty. */
364
+ readonly maxQueueDepth: number;
365
+ readonly entries: readonly SubscriptionEntryStat[];
366
+ }
367
+ //#endregion
368
+ //#region ../../packages/substrate-core/src/engine/engine.d.ts
369
+ declare class Engine {
370
+ #private;
371
+ constructor(opts: EngineOptions);
372
+ /**
373
+ * Best-effort cleanup. Detaches the engine's §6.4 lifecycle subscription
374
+ * from the registry so subsequent registry disposals don't trigger work
375
+ * against this engine. Safe to call more than once.
376
+ *
377
+ * Callers are NOT required to invoke `dispose` — engines over a process-
378
+ * lifetime registry can skip it entirely. Apps that hot-swap engines (tests,
379
+ * SIGHUP reload) should call it to avoid leaked listeners.
380
+ */
381
+ dispose(): void;
382
+ /**
383
+ * Append a new namespace to the engine at runtime, without a restart.
384
+ * Throws on collision or on a tombstoned name; idempotent re-add is the
385
+ * caller's responsibility.
386
+ *
387
+ * Side effect: invalidates federated schema cache so subsequent reads
388
+ * surface the new namespace's types.
389
+ */
390
+ addNamespace(ns: string, config: NamespaceConfig): void;
391
+ /**
392
+ * Mark a namespace as tombstoned. Hides it from `schemaFor` / `federatedSchema`,
393
+ * causes new query / mutate / subscribe ops to fail per-key with
394
+ * `namespace_tombstoned`, and closes any existing live subscriptions on the
395
+ * ns with a `namespace_tombstoned` error frame. Idempotent.
396
+ *
397
+ * The underlying NamespaceConfig stays in `#namespaces` for in-flight safety
398
+ * — concurrent ops that already resolved a config reference run to
399
+ * completion. Full physical reclaim happens at engine restart, gated by
400
+ * whatever persistence layer the host uses to decide which namespaces to
401
+ * re-install at boot.
402
+ */
403
+ tombstoneNamespace(ns: string): void;
404
+ /** See `EngineHandle.addDropParticipant`. */
405
+ addDropParticipant(participant: DropParticipant): () => void;
406
+ dropParticipants(): readonly DropParticipant[];
407
+ /** See `EngineHandle.onNamespaceTombstoned`. */
408
+ onNamespaceTombstoned(listener: (ns: string) => void): () => void;
409
+ /**
410
+ * Take a namespace off the engine and free its name, so `addNamespace` can
411
+ * take it again: live subscriptions on it close, its schema disappears, and
412
+ * new ops answer `unknown_namespace`. Ops that already resolved its config
413
+ * run to completion. Undoes a runtime add (a rolled-back propose_namespace);
414
+ * a namespace a plugin installs at boot comes back on restart. Idempotent.
415
+ */
416
+ removeNamespace(ns: string): void;
417
+ /** Whether `ns` is on the engine, and if so whether it is still served. */
418
+ namespaceState(ns: string): 'absent' | 'live' | 'tombstoned';
419
+ /**
420
+ * Internal accessor for the per-namespace registry. Consumers (notably the
421
+ * substrate binary's mutate route, which needs per-mutation `returns` metadata
422
+ * for positional encoding) should treat this as a package-internal API —
423
+ * application code goes through `query`/`mutate` or `schemaFor`.
424
+ */
425
+ registryFor(ns: string): Registry$1 | undefined;
426
+ /**
427
+ * Factory for a fresh empty Registry instance, so plugins can provision
428
+ * namespaces via addNamespace without a runtime import on this package.
429
+ */
430
+ createRegistry(): Registry;
431
+ /**
432
+ * True iff `name` is a registered substrate-plugin filter operator (e.g.
433
+ * `embeddingSimilar` from substrate-recall). Thin pass-through to the shared
434
+ * `@mnmal-ai/substrate-filter` registry. In-process consumers branch on this
435
+ * instead of catching "unknown operator" errors; HTTP consumers should
436
+ * read the sorted name list from `binary.filterOperators` in
437
+ * `/substrate/v1/onboard` (same registry, exposed at the transport edge).
438
+ */
439
+ hasFilterOperator(name: string): boolean;
440
+ /**
441
+ * Sorted list of registered extension-operator names. Surfaced via
442
+ * `/substrate/v1/onboard.binary.filterOperators` for HTTP consumers.
443
+ */
444
+ listFilterOperators(): ReadonlyArray<string>;
445
+ /**
446
+ * Look up the host-registered dataset for `ns`, or `undefined` if the host
447
+ * has not provisioned one. Pass-through to the engine's `DatasetRegistry`,
448
+ * surfaced on `EngineHandle` for plugins handling runtime-added
449
+ * namespaces.
450
+ */
451
+ datasetFor(ns: string): Dataset | undefined;
452
+ schemaFor(ns: string): Schema;
453
+ federatedSchema(): Record<string, Schema>;
454
+ /**
455
+ * Invalidate the cached federated-schema map and version, plus the per-ns
456
+ * schema cache entry when `ns` is supplied. For external mutators that
457
+ * change a namespace's registered types after construction.
458
+ */
459
+ invalidateSchemaCaches(ns?: string): void;
460
+ /**
461
+ * Evaluate the write policy for a type entry WITHOUT dispatching it, for
462
+ * kernel routes that mutate outside frame dispatch. Same checks as
463
+ * `evaluateReadPolicy`, with `operation: 'mutate'`. Use this, not the read
464
+ * probe, for writes: a namespace may gate writes more strictly than reads.
465
+ */
466
+ evaluateWritePolicy(ns: string, type: string, identity: Identity | null, probe?: PolicyProbeContext): PolicyDecision;
467
+ /**
468
+ * Evaluate the read policy for a type entry WITHOUT dispatching it, so
469
+ * out-of-band read routes are gated by the same composed policy as
470
+ * `engine.query`. Fails closed on a tombstoned or unknown namespace, an
471
+ * unknown type, a non-type entry, or a refused identity grant. Pass the
472
+ * caller's `probe` context so policies reading headers, `clientIp`, `meta`
473
+ * or `authEnabled` decide as they would in dispatch.
474
+ */
475
+ evaluateReadPolicy(ns: string, type: string, identity: Identity | null, probe?: PolicyProbeContext): PolicyDecision;
476
+ /**
477
+ * Refresh the cached schemas for every registered bridge. Callers invoke
478
+ * this at composition-root wire-up time to populate `federatedSchema()`'s
479
+ * bridge merge; subsequent drift (schemaVersion change) triggers an auto-
480
+ * refetch via the envelope decoder (§7.1), not this API.
481
+ *
482
+ * Unreachable bridges are skipped silently — reachability is owed to the
483
+ * per-bridge probe, not this surface.
484
+ */
485
+ refreshBridgeSchemas(): Promise<void>;
486
+ federatedSchemaVersion(): string;
487
+ /**
488
+ * Run a query frame. §5.13: callers control timeout by aborting `input.signal`
489
+ * — the engine ships no server-side timer. Pre-aborted input short-circuits
490
+ * with an `aborted` error per remaining entry; a signal that fires mid-flight
491
+ * causes subsequent entries to be skipped with the same error code.
492
+ *
493
+ * Bridge routing (§5.8): keys whose namespace is not local but IS registered
494
+ * with the bridge registry are proxied to the bridge in parallel with the
495
+ * local path. Unreachable bridges surface `{ __orphan: true, reason:
496
+ * 'bridge_unreachable' }` per-key (§6.5 "Reads never fail").
497
+ */
498
+ query(input: EngineInput): Promise<PackEnvelope>;
499
+ /**
500
+ * Run a mutate frame atomically. §5.13: callers control timeout via
501
+ * `input.signal` (AbortController). Cancellation is cooperative — a resolver
502
+ * that throws on `args.signal.aborted` triggers the enclosing tx's rollback
503
+ * through the existing throw-rolls-back contract. A signal that fires AFTER
504
+ * a resolver returns does NOT undo a committed write.
505
+ *
506
+ * Idempotency (§5.13): when any entry carries `idempotencyKey`, the engine
507
+ * computes a per-frame dedup key and consults the configured store before
508
+ * dispatch. A hit returns the cached envelope verbatim; a miss proceeds
509
+ * normally and caches the envelope on success.
510
+ *
511
+ * Bridge routing (§5.8): keys whose namespace is bridged are proxied to the
512
+ * remote via `BridgeClient.mutate` — one call per bridge, in parallel with
513
+ * the local tx. G1 atomicity (§5.3) does NOT extend across bridges: each
514
+ * bridge commits independently and the local tx commits independently,
515
+ * best-effort with orphan markers on partial failure. Unreachable
516
+ * bridges surface per-key `bridge_unreachable` errors in `envelope.errors`
517
+ * (§6.5 "Deletes never proceed silently across a network").
518
+ */
519
+ mutate(input: EngineInput): Promise<PackEnvelope>;
520
+ /**
521
+ * Register a subscription (§5.4) by delegating to the SubscribeSubsystem.
522
+ * The subsystem owns the bus, the back-pressure queue, and the WriteEvent
523
+ * fanout — see subscribe.ts for the full contract.
524
+ */
525
+ subscribe(input: SubscribeInput): Promise<SubscriptionHandle>;
526
+ /**
527
+ * Live count of active subscription entries. Delegates to the
528
+ * SubscribeSubsystem, which owns the authoritative map.
529
+ */
530
+ activeSubscriptionCount(): number;
531
+ /**
532
+ * Snapshot of per-entry queue depths for the GET /substrate/v1/metrics superset.
533
+ * Delegates to the SubscribeSubsystem, which owns the authoritative map.
534
+ * Returns an idle snapshot ({ count: 0, maxQueueDepth: 0, entries: [] })
535
+ * when no subscriptions are registered.
536
+ */
537
+ subscriptionStats(): SubscriptionStatsSnapshot;
538
+ /**
539
+ * Register a stream dispatch (§5.5) by delegating to the StreamSubsystem —
540
+ * see stream.ts for the full contract. Completion is observed via the
541
+ * terminal `end` / `error` frame on `onFrame`; `cancel` is synchronous.
542
+ */
543
+ stream(input: StreamInput): StreamHandle;
544
+ }
545
+ //#endregion
546
+ //#region ../../packages/substrate-core/src/load-plugins.d.ts
547
+ interface LoadPluginsOptions {
548
+ plugins: CoordinatorPlugin[];
549
+ /** Resolve the dataset to use for a given namespace. Returns undefined if unknown. */
550
+ datasetFor(namespace: string): Dataset | undefined;
551
+ edges: EdgesStore;
552
+ /** Metric sink threaded into every `onStart` hook. No-op when omitted. */
553
+ metric?(name: string, payload?: unknown): void;
554
+ /**
555
+ * Composed substrate plugins. Walked per coordinator namespace at install
556
+ * time — each substrate's `contributePostWrites(nsDef)` is called and
557
+ * merged into the install context's `postWriteContributions` map.
558
+ * Substrates without `contributePostWrites` are skipped.
559
+ */
560
+ kernelPlugins?: KernelPlugin[];
561
+ }
562
+ interface LoadedPluginSchedule {
563
+ pluginName: string;
564
+ tasks: ScheduledTask[];
565
+ }
566
+ interface LoadedPlugins {
567
+ namespaces: Map<string, NamespaceConfig>;
568
+ datasets: Map<string, Dataset>;
569
+ /**
570
+ * Scheduled tasks contributed by plugins. The binary installs these into a
571
+ * `TaskScheduler` and calls `.start()` after the server's `start()` resolves.
572
+ */
573
+ schedule: LoadedPluginSchedule[];
574
+ /**
575
+ * Every plugin in registration order. The composition root uses this to
576
+ * mount plugin-scoped routes — `createPluginRouter({ name: plugin.name })`
577
+ * is invoked per entry when `plugin.routes` is defined.
578
+ */
579
+ plugins: CoordinatorPlugin[];
580
+ /**
581
+ * Run every plugin's `onStart` hook in registration order. Engine is
582
+ * threaded through `PluginLifecycleContext` so plugins that mutate their
583
+ * registry post-construction can invoke `engine.invalidateSchemaCaches(ns)`.
584
+ */
585
+ runOnStart(engine: EngineHandle): Promise<void>;
586
+ /**
587
+ * Run every plugin's `onStop` hook in REVERSE registration order. Errors
588
+ * from one plugin's teardown are logged via the metric sink under
589
+ * `plugin_on_stop_error` and do NOT abort other plugins' teardown. The
590
+ * binary's `compose()` `stop()` invokes this before the server stops
591
+ * accepting connections and before the substrate `closeStore()` runs.
592
+ */
593
+ runOnStop(engine: EngineHandle): Promise<void>;
594
+ }
595
+ export declare function loadPlugins(opts: LoadPluginsOptions): Promise<LoadedPlugins>;
596
+ //#endregion
597
+ //#region ../../packages/substrate-core/src/memory-edges-store.d.ts
598
+ interface MemoryEdgesStoreOptions {
599
+ now: () => Date;
600
+ }
601
+ export declare class MemoryEdgesStore implements EdgesStore {
602
+ #private;
603
+ private edges;
604
+ private readonly now;
605
+ private counter;
606
+ /**
607
+ * Memory-backed edges stores cannot enlist into any dataset's substrate
608
+ * transaction — they own their own single Map with no shared storage
609
+ * identity. Each instance advertises a unique id so the engine can
610
+ * distinguish instances and fall back to its nested-tx path.
611
+ */
612
+ readonly txScopeId: string;
613
+ constructor(options: MemoryEdgesStoreOptions);
614
+ /**
615
+ * Generate a lexicographically-monotonic id. Real deployments use ULIDs; for
616
+ * the reference in-memory store we just need "sortable + monotonic within a
617
+ * process," which `ts-counter` delivers without pulling a dependency.
618
+ */
619
+ private nextId;
620
+ write(input: EdgeWriteInput): Promise<Edge>;
621
+ tombstone(id: string, at?: Date): Promise<void>;
622
+ update(patch: EdgePatch): Promise<void>;
623
+ readNextBatch(cursorId: string | null, size: number): Promise<{
624
+ edges: Edge[];
625
+ lastId: string | null;
626
+ }>;
627
+ findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
628
+ findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
629
+ findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
630
+ canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
631
+ findBlocked(): Promise<Edge[]>;
632
+ findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
633
+ findEdgesTouchingType(namespace: string, type: string, limit: number): Promise<Edge[]>;
634
+ namespacesLinkedTo(namespace: string, type?: string): Promise<string[]>;
635
+ dropEdgesByNamespace(namespace: string, within?: readonly string[]): Promise<number>;
636
+ dropEdgesByType(namespace: string, type: string, within?: readonly string[]): Promise<number>;
637
+ /**
638
+ * Snapshot-and-restore atomicity. Spec §4.6, G1 §5.3.
639
+ *
640
+ * The memory store holds a single `edges` Map; tx routing goes through
641
+ * `this`. On throw, we swap `edges` back to the pre-tx snapshot. The clone
642
+ * depth is one level (map + per-edge `{...}`) so `tombstone` / `update`
643
+ * mutations — which flip fields on the Edge object — are isolated.
644
+ */
645
+ withTransaction<T>(fn: (tx: EdgesStore) => Promise<T>): Promise<T>;
646
+ }
647
+ //#endregion
648
+ //#region ../../packages/substrate-core/src/runtime-stats.d.ts
649
+ interface OpStat {
650
+ /** Requests seen for this op. */
651
+ readonly total: number;
652
+ /** Transport-level successes (HTTP status < 400). */
653
+ readonly ok: number;
654
+ /** Transport-level failures (HTTP status >= 400). */
655
+ readonly error: number;
656
+ /** Summed request duration; consumer derives mean = durationMsSum / total. */
657
+ readonly durationMsSum: number;
658
+ /** Largest single request duration observed. */
659
+ readonly durationMsMax: number;
660
+ }
661
+ interface RuntimeStatsSnapshot {
662
+ /** Wall-clock ISO timestamp when the counter was initialised. */
663
+ readonly since: string;
664
+ readonly requests: {
665
+ readonly query: OpStat;
666
+ readonly mutate: OpStat;
667
+ };
668
+ /** Live gauge, read through the activeSubscriptions callback at snapshot time. */
669
+ readonly subscriptions: {
670
+ readonly active: number;
671
+ /** Present when the subscriptionStats dep is wired and doesn't throw. */
672
+ readonly maxQueueDepth?: number;
673
+ /** Present when the subscriptionStats dep is wired and doesn't throw. */
674
+ readonly entries?: readonly SubscriptionEntryStat[];
675
+ };
676
+ /** Engine MetricFn tallies, keyed by event name. Bounded by emission sites in code. */
677
+ readonly events: Readonly<Record<string, number>>;
678
+ /** Per-key latency/error stats, capped at 512 keys (LRU). */
679
+ readonly resolvers?: Readonly<Record<string, ResolverStat>>;
680
+ /** Present only when the processStats dep is wired and doesn't throw. */
681
+ readonly process?: ProcessStat;
682
+ /** The last ten resolves at or above the running p99, newest first. */
683
+ readonly slowest?: readonly SlowRequest[];
684
+ }
685
+ interface RuntimeStats {
686
+ recordRequest(op: RuntimeOp, ok: boolean, durationMs: number): void;
687
+ recordEvent(name: string): void;
688
+ recordResolve(o: ResolveObservation): void;
689
+ /** Newest-first ring of the last 50 failed resolves; messages truncated, no stacks. */
690
+ errors(): RuntimeErrors;
691
+ snapshot(): RuntimeStatsSnapshot;
692
+ }
693
+ //#endregion
694
+ //#region ../../packages/substrate-core/src/task-scheduler.d.ts
695
+ type SchedulerMetricFn = (name: string, payload?: unknown) => void;
696
+ interface TaskSchedulerOptions {
697
+ engine: EngineHandle;
698
+ metric?: SchedulerMetricFn;
699
+ }
700
+ declare class TaskScheduler {
701
+ #private;
702
+ constructor(opts: TaskSchedulerOptions);
703
+ register(pluginName: string, tasks: ScheduledTask[]): void;
704
+ start(): void;
705
+ stop(): Promise<void>;
706
+ /**
707
+ * Invoke `pluginName/taskName` once. Intended for tests that advance the
708
+ * scheduler without waiting on wall-clock timers. Participates in the
709
+ * reentrancy guard — a parallel `runNow()` while a previous invocation is
710
+ * still running emits `scheduled_task_overlapped` and resolves without
711
+ * firing the handler again.
712
+ */
713
+ runNow(pluginName: string, taskName: string): Promise<void>;
714
+ }
715
+ //#endregion
716
+ //#region ../../packages/substrate-dataset-memory/src/memory-dataset.d.ts
717
+ interface MemoryDatasetOptions {
718
+ namespace: string;
719
+ /**
720
+ * Substrate identity. Each `MemoryDataset` instance owns its own
721
+ * `Map` storage, so by default instances are distinct substrates. Tests
722
+ * that want cross-namespace batched mutates in memory can construct
723
+ * multiple instances with the same explicit `txScopeId`, but must
724
+ * also share the underlying `store` and `shortIds` state themselves —
725
+ * the memory dataset does NOT coordinate storage across instances
726
+ * that happen to share a txScopeId string. This knob exists mainly
727
+ * so the engine can exercise the cross-substrate refusal path in
728
+ * tests without spinning up pg.
729
+ */
730
+ txScopeId?: string;
731
+ }
732
+ export declare class MemoryDataset implements Dataset {
733
+ #private;
734
+ readonly namespace: string;
735
+ readonly txScopeId: string;
736
+ readonly capabilities: FilterCapabilities;
737
+ /** See `Dataset.withAdvisoryLock`. Excludes holders on this instance. */
738
+ withAdvisoryLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
739
+ private store;
740
+ private shortIds;
741
+ constructor(options: MemoryDatasetOptions);
742
+ private bucket;
743
+ read(type: string, params: ReadParams): Promise<ReadResult>;
744
+ write(type: string, rows: Row[], options?: WriteOptions): Promise<WriteResult>;
745
+ tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
746
+ purge(type: string, ids: Id[]): Promise<DeleteResult>;
747
+ dropType(type: string): Promise<DropResult>;
748
+ dropNamespace(): Promise<DropResult>;
749
+ /**
750
+ * Compare-and-update. Spec §5.12 Phase 2 / Dispatch B.
751
+ *
752
+ * The whole method body runs synchronously within a single async microtask —
753
+ * there are no awaited reads against the store — so the check-then-write
754
+ * pair is atomic with respect to every other operation on this dataset
755
+ * instance. This is the mechanism that makes the `_system` invite-consumption
756
+ * flow race-safe even on the in-memory substrate, where `withTransaction`
757
+ * does not serialise concurrent callers.
758
+ */
759
+ conditionalUpdate(type: string, id: Id, match: Record<string, unknown>, updates: Record<string, unknown>, actor?: ActorIdentity, now?: Date): Promise<ConditionalUpdateResult>;
760
+ updateField(ref: UpdateFieldRef, fieldName: string, value: unknown): Promise<void>;
761
+ /**
762
+ * Snapshot-and-restore atomicity. Spec §5.3 / G1.
763
+ *
764
+ * All ops inside `fn` go through `this` — the memory dataset has a single
765
+ * `store` reference, so routing the tx view back to `this` is safe. On throw,
766
+ * we swap `store` back to the pre-tx snapshot.
767
+ *
768
+ * Row clone depth: two levels (buckets, then rows). A row's nested fields
769
+ * (e.g. `row.tags`) are NOT deep-cloned — callers that mutate nested
770
+ * structures inside a tx and then throw will observe stale references after
771
+ * rollback. G1 operates on flat rows.
772
+ */
773
+ withTransaction<T>(fn: (tx: Dataset) => Promise<T>): Promise<T>;
774
+ allocateShortId(type: string): Promise<number>;
775
+ bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
776
+ resolveShortId(type: string, shortId: number): Promise<string | null>;
777
+ getShortIdForRow(type: string, rowId: string): Promise<number | null>;
778
+ forNamespace(namespace: string): Dataset;
779
+ }
780
+ //#endregion
781
+ //#region ../../packages/substrate-dataset-memory/src/memory-registry.d.ts
782
+ type NamespaceLostListener = (ns: string) => void;
783
+ interface MemoryDatasetRegistryOptions {
784
+ /**
785
+ * Optional fallback invoked on `get(ns)` miss. Returning a dataset caches
786
+ * it via `set(ns, dataset)` so the next get is a direct map hit. Returning
787
+ * undefined leaves the registry empty for that ns and is NOT cached — the
788
+ * next get re-invokes the factory (caller may have provisioned the
789
+ * substrate in between).
790
+ */
791
+ factory?: (ns: string) => Dataset | undefined;
792
+ }
793
+ declare class MemoryDatasetRegistry implements DatasetRegistry {
794
+ private readonly datasets;
795
+ private readonly listeners;
796
+ private readonly factory;
797
+ constructor(options?: MemoryDatasetRegistryOptions);
798
+ get(ns: string): Dataset | undefined;
799
+ has(ns: string): boolean;
800
+ set(ns: string, dataset: Dataset): void;
801
+ onNamespaceLost(listener: NamespaceLostListener): () => void;
802
+ dispose(ns: string): void;
803
+ }
804
+ //#endregion
805
+ //#region ../../packages/substrate-compose/src/routes/config-echo.d.ts
806
+ /**
807
+ * Where a knob's effective value came from. `explicit` means the operator set
808
+ * the variable to a non-empty value; everything else — unset, empty string,
809
+ * whitespace-only — is `default`, because that is how the parsers treat it
810
+ * (docker-compose's `${VAR:-}` substitution produces an empty string, and
811
+ * reading that as "operator chose this" is how a knob silently becomes NaN).
812
+ */
813
+ type KnobSource = 'default' | 'explicit';
814
+ interface KnobReport {
815
+ /** The environment variable that sets this knob, e.g. `SUBSTRATE_SWEEP_INTERVAL_MS`. */
816
+ env: string;
817
+ /**
818
+ * The EFFECTIVE value after parsing — not the raw string. `null` means the
819
+ * knob resolves to off/absent, which is a real answer and distinct from the
820
+ * knob being unreported.
821
+ */
822
+ value: string | number | boolean | null;
823
+ source: KnobSource;
824
+ /**
825
+ * Present and `true` only for secret-valued knobs, whose `value` is
826
+ * `'<set>'` or `null` rather than the secret. Flagged rather than omitted so
827
+ * a reader can tell "this is hidden" from "this is genuinely unset".
828
+ */
829
+ redacted?: true;
830
+ }
831
+ /** Keyed by the `ParsedConfig` field name the knob resolves to. */
832
+ type ConfigReport = Record<string, KnobReport>;
833
+ //#endregion
834
+ //#region ../../packages/substrate-compose/src/compose.d.ts
835
+ interface ComposeOpts {
836
+ server: SubstrateServer;
837
+ dataset: Dataset;
838
+ /**
839
+ * Who this deployment writes AS when auth is disabled. Required in that case
840
+ * and refused at boot when absent.
841
+ *
842
+ * With no auth there is no bearer, so nothing identifies a caller; an
843
+ * unauthenticated deployment declares its actor rather than getting a silent
844
+ * default.
845
+ *
846
+ * Ignored when `auth` is set — a real caller's identity is better than a
847
+ * deployment-level stand-in, and using one would mask an auth misconfig.
848
+ */
849
+ systemActor?: string;
850
+ /**
851
+ * EdgesStore instance. Omit to use an in-process `MemoryEdgesStore`. Pg-backed
852
+ * binaries pass a `PgEdgesStore` so edges persist across restarts and
853
+ * participate in the engine's cross-store transaction nesting (§6.2).
854
+ */
855
+ edges?: EdgesStore;
856
+ /**
857
+ * Coordinator plugins (§5.11). When supplied, each plugin's `install()`
858
+ * contributes its own registry and namespace. Absent → the binary still
859
+ * boots (with `_system` admin routes and `/health`), but the `default`
860
+ * namespace is empty — no user types are served. Tests that need a
861
+ * populated namespace pass a coordinator.
862
+ */
863
+ coordinators?: Array<CoordinatorPlugin>;
864
+ /**
865
+ * Composed substrate plugins (§5.11 substrate tier). When supplied AND
866
+ * coordinators are also supplied, each substrate's `contributePostWrites`
867
+ * (if defined) is invoked per coordinator namespace at install time, so
868
+ * substrate-driven postWrite hooks chain into the engine's per-(ns,type)
869
+ * postWrite flow. When absent, no substrate contributions run — the binary
870
+ * still boots, but no embedding side-effects fire.
871
+ */
872
+ kernelPlugins?: Array<KernelPlugin>;
873
+ /**
874
+ * Per-namespace dataset overrides. When `coordinators` claim namespaces
875
+ * other than `'default'`, map them here; `loadPlugins` consults this map
876
+ * first and falls back to `opts.dataset` when a namespace is not listed.
877
+ * Ignored when `coordinators` is omitted.
878
+ */
879
+ datasets?: Record<string, Dataset>;
880
+ /**
881
+ * Bridge registry (§5.8). When supplied, the engine routes frame entries
882
+ * whose namespace is bridged through the bridge's query/mutate surface, and
883
+ * the sweep `resolveTarget` consults bridges for row lookups. When absent,
884
+ * a no-op stub is used — every namespace is treated as local/reachable.
885
+ */
886
+ bridges?: BridgeRegistry;
887
+ /**
888
+ * JWT auth config (§5.12). When supplied, route handlers for
889
+ * `/substrate/v1/query`, `/substrate/v1/mutate`, and the `/substrate/v1/ws` upgrade require a
890
+ * valid `Authorization: Bearer <token>` header; missing / invalid tokens
891
+ * return 401 with `{ code: 'unauthorized' }`. When absent, every request
892
+ * passes through unauthenticated, attributed to `systemActor`.
893
+ *
894
+ * Open routes (no key needed even with auth enabled): `GET /health`,
895
+ * `GET /substrate/v1/whoami` and `POST /substrate/v1/_system/register`. Schema discovery
896
+ * and `/substrate/v1/onboard` sit behind `read` like `/substrate/v1/query`.
897
+ */
898
+ auth?: AuthConfig;
899
+ /**
900
+ * Override for the `/substrate/v1/_system/register` rate limiter.
901
+ * When absent, the composer allocates a limiter with the
902
+ * default 10-requests-per-60s-per-IP cap. Tests supply a spoofable instance
903
+ * (and control the `now` clock) so they can exercise the 429 path
904
+ * deterministically.
905
+ */
906
+ registerRateLimiter?: RateLimiter;
907
+ /**
908
+ * Binary semver — surfaced by `GET /substrate/v1/onboard` so agents know which
909
+ * binary they're talking to. Defaults to `'0.0.0'` when omitted.
910
+ */
911
+ version?: string;
912
+ /**
913
+ * §5.13 idempotency store. When supplied, the engine dedups mutate frames
914
+ * whose `FrameEntry.idempotencyKey` is present — cached envelopes are
915
+ * replayed byte-identically, transparently to callers. Absent → no dedup; the key is silently ignored. `defaultTtlMs` defaults
916
+ * to 24h per spec.
917
+ */
918
+ idempotency?: {
919
+ store: IdempotencyStore;
920
+ defaultTtlMs?: number;
921
+ };
922
+ /**
923
+ * §5.13 subscription back-pressure override. Threads straight into
924
+ * `EngineOptions.subscriptions`. Default (absent): engine default
925
+ * queueLimit of 256. Conformance tests set a tiny limit to trigger the
926
+ * teardown contract deterministically (docs/ws-subscription-contract.md).
927
+ */
928
+ subscriptions?: {
929
+ queueLimit?: number;
930
+ /** Most rows a subscription snapshot may return; defaults to `pageLimits.maxLimit`. */
931
+ snapshotLimit?: number;
932
+ };
933
+ /**
934
+ * Allowlist of peer IPs whose `x-forwarded-for`
935
+ * header is trusted for `/substrate/v1/_system/register` rate-limit bucketing.
936
+ * Exact IP strings only — no CIDR. An empty set (the default) means XFF is
937
+ * always ignored; the route buckets on `req.peerIp` (or `'unknown'`).
938
+ * Callers that need CIDR should terminate XFF parsing at their reverse
939
+ * proxy.
940
+ */
941
+ trustedProxies?: Set<string>;
942
+ /**
943
+ * Page bounds for remote list reads on `/substrate/v1/query`: a type read
944
+ * with no `limit` gets `defaultLimit`, one above `maxLimit` is refused.
945
+ * Defaults to 100 and 1000. In-process callers are not bounded, except that
946
+ * `maxLimit` also caps every subscription snapshot.
947
+ */
948
+ pageLimits?: {
949
+ defaultLimit: number;
950
+ maxLimit: number;
951
+ };
952
+ /**
953
+ * Opt-in periodic re-prime interval (ms) for the
954
+ * `KeyRegistry` public-key cache. Bounds cross-instance revocation
955
+ * staleness: when multiple binaries share one store, a key revoked by one
956
+ * instance is honoured by the others within one tick instead of only after
957
+ * a restart. Only takes effect when auth is enabled (the cache is otherwise
958
+ * never consulted). Omit / non-positive → disabled (the single-instance
959
+ * default; write-through invalidation already keeps one process consistent).
960
+ */
961
+ keyReprimeIntervalMs?: number;
962
+ /**
963
+ * HMAC secret for browser SSE stream tickets. REQUIRED when `auth` is set,
964
+ * and at least `MIN_STREAM_TICKET_SECRET_LEN` characters after trimming —
965
+ * `compose` throws otherwise, because the ungated `GET` stream routes
966
+ * authenticate on this signature alone, the dev default is a published
967
+ * constant, and `''` / `' '` are HMAC keys Node accepts. Omit it only with
968
+ * auth disabled, where `gate` is the identity function and there is nothing
969
+ * to bypass. Trimmed before use.
970
+ */
971
+ streamTicketSecret?: string;
972
+ /**
973
+ * Effective value + provenance for every defaulted knob, as the caller's
974
+ * env parser resolved them. When present, compose mounts
975
+ * `GET /substrate/v1/config` admin-gated to echo it.
976
+ *
977
+ * Passed in rather than derived here: compose does not read the
978
+ * environment, and the echo must report what the parser resolved, not a
979
+ * second reading of the environment. Omitted by programmatic embedders.
980
+ */
981
+ configReport?: ConfigReport;
982
+ }
983
+ interface ComposeResult {
984
+ engine: Engine;
985
+ /**
986
+ * The primed `KeyRegistry` this composition built, or `null` when auth
987
+ * is off.
988
+ *
989
+ * Routes mounted outside compose (e.g. substrate kernel routes) must put
990
+ * this registry in their `AuthConfig`: `opts.auth` alone has none, so
991
+ * agent-key bearers would fail to verify there.
992
+ */
993
+ keyRegistry: KeyRegistry | null;
994
+ registry: Registry$1;
995
+ datasets: MemoryDatasetRegistry;
996
+ edges: EdgesStore;
997
+ sweepDeps: SweepDeps;
998
+ /**
999
+ * Run one sweep cycle from a null cursor. Exposed for tests that need to
1000
+ * drive the reconciler deterministically — production uses the `setInterval`
1001
+ * loop in `main.ts`.
1002
+ */
1003
+ runSweepNow: () => Promise<SweepState>;
1004
+ /**
1005
+ * Non-null when any coordinator plugin contributed a `schedule`. The
1006
+ * composition root constructs the scheduler, registers every plugin's
1007
+ * tasks, and returns it unstarted. `main.ts` calls `scheduler.start()`
1008
+ * after the server's `start()` resolves; `stop()` below awaits its teardown.
1009
+ */
1010
+ scheduler: TaskScheduler | null;
1011
+ /** Live runtime-stats counter. Read via `stats.snapshot()` or via `GET /substrate/v1/metrics`. */
1012
+ stats: RuntimeStats;
1013
+ stop: (opts?: {
1014
+ grace?: number;
1015
+ abortInFlight?: boolean;
1016
+ }) => Promise<void>;
1017
+ }
1018
+ export declare function compose(opts: ComposeOpts): Promise<ComposeResult>;
1019
+ //#endregion
1020
+ //#region ../../packages/substrate-dataset-pg/src/testing.d.ts
1021
+ /**
1022
+ * Safety rails for pg integration tests. Shared by every package whose suites
1023
+ * run destructive setup (TRUNCATE / DELETE / DDL) against whatever database
1024
+ * `POSTGRES_URL` names.
1025
+ *
1026
+ * Imported via the `@mnmal-ai/substrate-dataset-pg/testing` subpath, so every
1027
+ * package shares one tested copy rather than hand-copying it.
1028
+ *
1029
+ * Independent checks:
1030
+ *
1031
+ * 1. `assertTestDatabase` — the database NAME must end `_test` or `_dev`, so a
1032
+ * stray `POSTGRES_URL` cannot point a destructive suite at real data.
1033
+ *
1034
+ * 2. `assertNotSuperuser` — the CREDENTIAL must not be a superuser. The name
1035
+ * check says nothing about what the role can reach, and a superuser
1036
+ * bypasses every grant that would otherwise contain it.
1037
+ *
1038
+ * 3. `assertCannotWriteOutsideTestDatabases` — the credential must not be able
1039
+ * to damage any non-test database. Check 2 implies this only while
1040
+ * production runs as a superuser; this asks postgres directly.
1041
+ */
1042
+ export interface GuardOptions {
1043
+ /** Named in the failure message so a developer knows which suite refused. */
1044
+ packageName: string;
1045
+ }
1046
+ export interface SuperuserGuardOptions extends GuardOptions {
1047
+ /** Injectable for tests, so the suite needs no live postgres. */
1048
+ probe?: (url: string) => Promise<boolean>;
1049
+ }
1050
+ export declare function assertTestDatabase(url: string | undefined, opts: GuardOptions): void;
1051
+ /**
1052
+ * Returns whether the superuser probe's rows say `on`. Throws on a missing
1053
+ * row rather than returning `false`: an unanswered probe is not evidence of
1054
+ * safety.
1055
+ */
1056
+ export declare function interpretSuperuserProbe(rows: Array<{
1057
+ su?: string;
1058
+ }>): boolean;
1059
+ export declare function assertNotSuperuser(url: string | undefined, opts: SuperuserGuardOptions): Promise<void>;
1060
+ /** A database outside the test set that the connecting credential could damage. */
1061
+ export interface ReachFinding {
1062
+ database: string;
1063
+ /** What makes it damageable: owning the database itself, or a relation in it. */
1064
+ via: 'owns-database' | 'writable-relation';
1065
+ /** For `writable-relation`: a sample of `schema.table` names, at most five. */
1066
+ relations?: string[];
1067
+ }
1068
+ export interface ReachGuardOptions extends GuardOptions {
1069
+ /** Injectable for tests, so the suite needs no live postgres. */
1070
+ probe?: (url: string) => Promise<ReachFinding[]>;
1071
+ }
1072
+ /**
1073
+ * Throws if the credential in `url` owns, or can write to, anything in a
1074
+ * database whose name is not a test name. No-op when `url` is unset.
1075
+ *
1076
+ * Deliberately not a CONNECT check: postgres grants CONNECT to PUBLIC, so a
1077
+ * correctly scoped test role can still connect to production.
1078
+ */
1079
+ export declare function assertCannotWriteOutsideTestDatabases(url: string | undefined, opts: ReachGuardOptions): Promise<void>;
1080
+ export declare function reachFailureMessage(findings: readonly ReachFinding[], packageName: string): string | undefined;
1081
+ export interface AnnounceOptions {
1082
+ /** Named in the announcement so a developer knows which suite stood down. */
1083
+ packageName: string;
1084
+ /** Injectable sink; defaults to stderr. */
1085
+ warn?: (message: string) => void;
1086
+ }
1087
+ /**
1088
+ * Writes one stderr line when `url` is unset, saying this package's pg-gated
1089
+ * suites will skip — otherwise a skip looks the same as a pass in the gate.
1090
+ *
1091
+ * Call it from `vitest.config.ts` (evaluated once per run), not `setupFiles`
1092
+ * (once per file). It uses `process.stderr.write` because vitest swallows
1093
+ * `console.warn` when every file skips.
1094
+ */
1095
+ export declare function announcePgGating(url: string | undefined, opts: AnnounceOptions): void;
1096
+ /**
1097
+ * Returns the schema a package's pg-gated suites own.
1098
+ *
1099
+ * Deterministic rather than per-run, so the schema persists between runs and
1100
+ * migrations stay incremental.
1101
+ */
1102
+ export declare function pgTestSchemaName(packageName: string): string;
1103
+ /**
1104
+ * Returns `url` with `search_path` pinned to this package's schema.
1105
+ *
1106
+ * A startup parameter, not `SET search_path`: with a pool, a `SET` reaches
1107
+ * only one connection. `public` stays on the path because the `vector` type
1108
+ * lives there.
1109
+ *
1110
+ * The query string is built by hand because postgres.js needs the space as
1111
+ * `%20`; `URLSearchParams` would emit `+`, which postgres rejects.
1112
+ */
1113
+ export declare function pgTestSchemaUrl(url: string, packageName: string): string;
1114
+ export interface SchemaIsolationOptions extends GuardOptions {
1115
+ /** Injectable for tests, so the suite needs no live postgres. */
1116
+ createSchema?: (url: string, schema: string) => Promise<void>;
1117
+ /** Injectable for tests. Names substrate relations still sitting in `public`. */
1118
+ findPublicLeftovers?: (url: string) => Promise<string[]>;
1119
+ /** Injectable sink; defaults to stderr. */
1120
+ warn?: (message: string) => void;
1121
+ }
1122
+ /**
1123
+ * Returns a warning naming substrate relations left in `public`, or undefined if
1124
+ * there are none.
1125
+ *
1126
+ * With `public` on the search_path, an unqualified name missing from the
1127
+ * package schema resolves to `public`'s copy, so leftovers there are unsafe.
1128
+ * They are named rather than dropped: this code does not own them.
1129
+ */
1130
+ export declare function publicLeftoverWarning(names: readonly string[], packageName: string): string | undefined;
1131
+ /**
1132
+ * Creates this package's test schema and returns the URL that reaches it, or
1133
+ * `undefined` when there is no `POSTGRES_URL`. Warns about leftovers in `public`.
1134
+ *
1135
+ * Packages run concurrently and their suites drop and re-migrate the shared
1136
+ * tables, so each needs its own schema. A schema rather than a database,
1137
+ * because the least-privilege `substrate_test` role has no CREATEDB.
1138
+ *
1139
+ * Call from `globalSetup`, so forked workers inherit the rewritten URL.
1140
+ */
1141
+ export declare function preparePgTestSchema(url: string | undefined, opts: SchemaIsolationOptions): Promise<string | undefined>;
1142
+ //#endregion
1143
+ //#region ../../packages/substrate-embedder/src/fake.d.ts
1144
+ interface FakeEmbedderOptions {
1145
+ /** Output vector dimension. Default: 384 (matches bge-small-en). */
1146
+ dimension?: number;
1147
+ }
1148
+ export declare class FakeEmbedder implements Embedder {
1149
+ readonly modelId: string;
1150
+ readonly dimension: number;
1151
+ constructor(opts?: FakeEmbedderOptions);
1152
+ embed(text: string): Promise<Float32Array>;
1153
+ }
1154
+ //#endregion
1155
+ //#region ../../packages/substrate-server-memory/src/memory-ws-connection.d.ts
1156
+ /**
1157
+ * @internal — thrown when sending on a closed in-memory WS pair. Treat as
1158
+ * package-private.
1159
+ */
1160
+ export declare class WsClosedError extends Error {
1161
+ constructor();
1162
+ }
1163
+ type Frame = Buffer | Uint8Array | string;
1164
+ interface MemoryWsClient {
1165
+ send(frame: Frame): void;
1166
+ onMessage(cb: (frame: Buffer) => void): void;
1167
+ onClose(cb: (code?: number) => void): void;
1168
+ close(code?: number, reason?: string): void;
1169
+ readonly closed: boolean;
1170
+ }
1171
+ /**
1172
+ * @internal — paired in-memory WS endpoints used by `MemorySubstrateServer`
1173
+ * for inject-style WS testing. Treat as package-private.
1174
+ */
1175
+ export declare function createMemoryWsPair(): {
1176
+ server: WsConnection;
1177
+ client: MemoryWsClient;
1178
+ };
1179
+ //#endregion
1180
+ //#region ../../packages/substrate-server-memory/src/memory-server.d.ts
1181
+ type ErrorHook = (err: Error, req?: SubstrateRequest) => void;
1182
+ export declare class UnknownWsPathError extends Error {
1183
+ constructor(path: string);
1184
+ }
1185
+ /**
1186
+ * @internal — thrown when `MemorySubstrateServer.start()` is called twice.
1187
+ * Re-exported from the package index; treat as package-private.
1188
+ */
1189
+ export declare class AlreadyStartedError extends Error {
1190
+ constructor();
1191
+ }
1192
+ export declare class MemorySubstrateServer implements SubstrateServer {
1193
+ #private;
1194
+ route(method: HttpMethod, path: string, handler: HttpHandler): void;
1195
+ websocket(path: string, handler: WsHandler): void;
1196
+ onError(hook: ErrorHook): void;
1197
+ observeRequests(observer: RequestObserver): void;
1198
+ observeInFlight(fn: (op: RuntimeOp, delta: 1 | -1) => void): void;
1199
+ start(_opts?: StartOpts): Promise<{
1200
+ address: string;
1201
+ port: number;
1202
+ }>;
1203
+ stop(opts?: {
1204
+ grace?: number;
1205
+ abortInFlight?: boolean;
1206
+ }): Promise<void>;
1207
+ abortAllRequests(reason?: string): void;
1208
+ onShutdown(cb: (reason: string) => void): void;
1209
+ createPluginRouter(plugin: {
1210
+ name: string;
1211
+ }): PluginRouter;
1212
+ inject(req: Partial<SubstrateRequest>): Promise<SubstrateResponse>;
1213
+ connectWebsocket(path: string, headers?: Record<string, string>): MemoryWsClient;
1214
+ }
1215
+ //#endregion
1216
+ //#region ../../packages/substrate-server-memory/src/route-matcher.d.ts
1217
+ /**
1218
+ * Pure path-pattern matcher used by `MemorySubstrateServer`.
1219
+ *
1220
+ * Supported syntax:
1221
+ * - Literal segments: `/foo/bar`
1222
+ * - Named captures: `/users/:id` → params.id
1223
+ * - Trailing wildcard: `/files/*` → params.rest (captures joined tail, may be empty)
1224
+ *
1225
+ * Design calls:
1226
+ * - Matching is exact on segment count unless the last registered segment is `*`.
1227
+ * - Trailing slash is significant. `/foo` does not match `/foo/`, and vice-versa.
1228
+ * Networked servers normalise this in their own idiomatic way; keeping the
1229
+ * matcher strict makes test assertions unambiguous.
1230
+ * - The matcher does NOT strip or parse querystrings. Callers pre-strip.
1231
+ * - The matcher does NOT decode URI components. Tests that need encoded values
1232
+ * can assert against the raw bytes; decoding is a per-caller policy.
1233
+ */
1234
+ /**
1235
+ * @internal — used by `MemorySubstrateServer.inject` for path-pattern matching.
1236
+ * Treat as package-private.
1237
+ */
1238
+ export declare function matchRoute(registered: string, actual: string): Record<string, string> | null;
1239
+ //#endregion
1240
+ export type { AuthConfig, ComposeResult, MemoryWsClient };