@mnmal-ai/substrate 0.0.0-stage → 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.
- package/LICENSE +202 -0
- package/README.md +119 -2
- package/dist/agent-token-BIboWOU0.js +200 -0
- package/dist/client.d.ts +782 -0
- package/dist/client.js +7 -0
- package/dist/cluster-worker.js +35 -0
- package/dist/content-type-C7T28xNb.js +25 -0
- package/dist/dataset-BXkus75W.js +1527 -0
- package/dist/env-utils-B7SGmoeJ.js +21 -0
- package/dist/errors-D4vKuwz8.d.ts +130 -0
- package/dist/fake-DUVtKVSE.js +36 -0
- package/dist/index-D7mSOFlM.d.ts +69 -0
- package/dist/pack.d.ts +192 -0
- package/dist/pack.js +5 -0
- package/dist/plugin-j1jt1l3n.js +3844 -0
- package/dist/plugin-t2g2wX0b.d.ts +1568 -0
- package/dist/proposals-bootstrap.js +37 -0
- package/dist/proposals.config.schema.json +20 -0
- package/dist/proposals.d.ts +118 -0
- package/dist/proposals.default-config.json +4 -0
- package/dist/proposals.js +4 -0
- package/dist/recall-bootstrap.js +451 -0
- package/dist/recall.config.schema.json +232 -0
- package/dist/recall.d.ts +1981 -0
- package/dist/recall.default-config.json +4 -0
- package/dist/recall.js +5 -0
- package/dist/repl-C52wyfMs.js +2213 -0
- package/dist/row-ByLFE2Wx.d.ts +719 -0
- package/dist/row-DK7lPZVe.js +732 -0
- package/dist/runtime-metrics-DwpDJ8vz.d.ts +159 -0
- package/dist/schema-g4FQLr0V.d.ts +433 -0
- package/dist/sdk.d.ts +694 -0
- package/dist/sdk.js +112 -0
- package/dist/src-C4DzaIQZ.js +837 -0
- package/dist/src-CrEgiMJQ.js +1015 -0
- package/dist/src-CzxvmhFn.js +2327 -0
- package/dist/src-D88LvCX8.js +1797 -0
- package/dist/src-D91yij6C.js +13523 -0
- package/dist/src-DuopV8u7.js +2408 -0
- package/dist/substrate-admin.js +808 -0
- package/dist/substrate.js +5477 -0
- package/dist/testing.d.ts +1240 -0
- package/dist/testing.js +702 -0
- package/dist/types-8c0gtnd2.d.ts +35 -0
- package/dist/ws-C72iVS5T.d.ts +143 -0
- package/package.json +117 -3
|
@@ -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 };
|