@mnmal-ai/substrate 1.0.0-alpha.2 → 1.0.0-alpha.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +64 -14
- package/dist/boot-store-BaDqbBS-.js +4062 -0
- package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-BhiJKwfF.d.ts} +2 -87
- package/dist/cli-RRFphMtQ.js +3366 -0
- package/dist/client.browser.js +2485 -0
- package/dist/client.d.ts +273 -135
- package/dist/client.js +6 -6
- package/dist/cluster-worker.js +0 -1
- package/dist/{content-type-C7T28xNb.js → content-type-wLljot5M.js} +0 -1
- package/dist/{env-utils-CGNazUNt.js → env-utils-s25Z1YSA.js} +0 -1
- package/dist/{errors-D4vKuwz8.d.ts → errors-CYOaWZ8l.d.ts} +44 -4
- package/dist/{fake-DUVtKVSE.js → fake-DdXtb-m8.js} +0 -1
- package/dist/{index-D7mSOFlM.d.ts → index-ZKeYFHDD.d.ts} +7 -11
- package/dist/msgpackr-Dq18g6Ds.js +16 -0
- package/dist/node-version-BtK_Nq6z.js +32 -0
- package/dist/pack.d.ts +75 -11
- package/dist/pack.js +4 -4
- package/dist/pg-edges-store-C-IRv-O9.js +443 -0
- package/dist/{plugin-QuJN9pG_.js → plugin-MSbSZ6Al.js} +132 -8
- package/dist/proposals-bootstrap.js +6 -5
- package/dist/proposals.config.schema.json +5 -0
- package/dist/proposals.d.ts +17 -5
- package/dist/proposals.default-config.json +2 -1
- package/dist/proposals.js +2 -3
- package/dist/recall-bootstrap.js +5 -4
- package/dist/recall.config.schema.json +6 -0
- package/dist/recall.d.ts +35 -6
- package/dist/recall.js +2 -3
- package/dist/{repl-C52wyfMs.js → repl-Ob5OyQqj.js} +65 -33
- package/dist/{row-ByLFE2Wx.d.ts → row-CfsHSEfB.d.ts} +92 -12
- package/dist/run-B438GGJK.js +2435 -0
- package/dist/{plugin-t2g2wX0b.d.ts → schema-laGLMvMC.d.ts} +1287 -63
- package/dist/script-A9dxMRZA.js +143 -0
- package/dist/script-runner.js +77 -0
- package/dist/sdk.d.ts +227 -38
- package/dist/sdk.js +5 -110
- package/dist/semver-D_zdq0hi.js +17 -0
- package/dist/{src-DMzc3HfW.js → src-BNdhH_Hx.js} +745 -851
- package/dist/{src-CG7giuHr.js → src-BSL2yyVy.js} +779 -75
- package/dist/{src-BLgbLq2k.js → src-B_kHkbsr.js} +780 -330
- package/dist/{src-DWm0iA88.js → src-De9j33jv.js} +188 -87
- package/dist/src-DkxrpQOz.js +7709 -0
- package/dist/{row-DZ0Fnpc6.js → src-DmiUWOLp.js} +2 -1
- package/dist/{src-CHp3QyqB.js → src-S84ef4e3.js} +9177 -3377
- package/dist/substrate-admin.js +17 -782
- package/dist/substrate.js +4 -5487
- package/dist/testing.d.ts +730 -53
- package/dist/testing.js +20 -163
- package/dist/{ws-C72iVS5T.d.ts → ws-BT8kL1IF.d.ts} +4 -5
- package/package.json +26 -26
- package/dist/dataset-BQ8egGl5.js +0 -1535
- package/dist/schema-g4FQLr0V.d.ts +0 -433
- package/dist/src-CXKnqeTW.js +0 -2339
package/dist/testing.d.ts
CHANGED
|
@@ -1,8 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { a as
|
|
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";
|
|
1
|
+
import { At as DatasetRegistry, Bn as WriteRow, Bt as IndexPlan, Cn as CanDeleteResult, Dn as EdgeWriteInput, Dt as ConditionalUpdateResult, E as EngineInput, En as EdgeRef, Ft as FilterCapabilities, G as Registry$1, Gt as ReadParams, It as FilterWriteLimits, J as RegistryEntryInput, Jt as StorageReport, K as RegistryBase, Kt as ReadResult, L as NamespaceConfig, Ln as Row, Lt as FilterWriteOptions, Mt as DropResult, On as EdgesStore, P as KernelPlugin, Pn as Id, Qt as UpdateFieldRef, Rt as FilterWriteResult, S as DropParticipant, T as EngineHandle, Tn as EdgePatch, Tt as WriteEvent, Ut as PoolStats, W as QualifiedFrame, Wt as PromotionEvent, Yt as TxScopeHandles, Z as ScheduledTask, Zt as TypeStorageReport, _t as PolicyDecision, an as WriteOptions, at as RequestObserver, b as CommittedWritesHook, cn as ResolveObservation, ct as SubstrateRequest, d as OrderedBy, dn as RuntimeErrors, f as PackEnvelope, i as FieldDef, in as WhereClause, jn as ActorIdentity, jt as DeleteResult, k as IndexDecl, kt as Dataset, ln as ResolverStat, lt as SubstrateResponse, m as Schema, mn as TypeStats, mt as Identity, nt as HttpMethod, on as WriteResult, ot as RuntimeOp, pn as SlowRequest, q as RegistryEntry, rt as PluginRouter, sn as ProcessStat, st as StartOpts, tt as HttpHandler, ut as SubstrateServer, vt as PolicyProbeContext, wn as Edge, x as CoordinatorPlugin, xt as ResolverArgs, yt as RequestContext } from "./schema-laGLMvMC.js";
|
|
2
|
+
import { a as WsResponseFrame, f as IdempotencyStore, l as SweepDeps, s as BridgeRegistry, u as SweepState } from "./ws-BT8kL1IF.js";
|
|
5
3
|
import { t as Embedder } from "./types-8c0gtnd2.js";
|
|
4
|
+
import { Sql, TransactionSql } from "postgres";
|
|
6
5
|
//#region ../../packages/substrate-compose/src/auth.d.ts
|
|
7
6
|
type JwtAlg = 'RS256' | 'ES256' | 'HS256' | 'EdDSA';
|
|
8
7
|
interface AuthKey {
|
|
@@ -55,8 +54,8 @@ interface AuthConfig {
|
|
|
55
54
|
maxTokenLifetimeSeconds?: number;
|
|
56
55
|
/**
|
|
57
56
|
* The origins this server answers as (`SUBSTRATE_PUBLIC_ORIGIN`). When set, a
|
|
58
|
-
* token
|
|
59
|
-
*
|
|
57
|
+
* token must carry `aud` naming one of them, or it is refused. Absent → `aud`
|
|
58
|
+
* is not checked.
|
|
60
59
|
*/
|
|
61
60
|
audiences?: ReadonlyArray<string>;
|
|
62
61
|
/**
|
|
@@ -75,6 +74,13 @@ export declare function signHs256(payload: Record<string, unknown>, secret: stri
|
|
|
75
74
|
kid?: string;
|
|
76
75
|
}): string;
|
|
77
76
|
//#endregion
|
|
77
|
+
//#region ../../packages/substrate-compose/src/advisor/profiles.d.ts
|
|
78
|
+
/**
|
|
79
|
+
* Sizing profiles: how sensitive the index advisor is. A profile only tunes
|
|
80
|
+
* when a recommendation is written; nothing is ever built without approval.
|
|
81
|
+
*/
|
|
82
|
+
type StoreProfileName = 'personal' | 'growth' | 'scale';
|
|
83
|
+
//#endregion
|
|
78
84
|
//#region ../../packages/substrate-compose/src/_system/types.d.ts
|
|
79
85
|
/**
|
|
80
86
|
* Where the operator's agent DIRECTORY lives, so `POST /substrate/v1/_system/keys` can
|
|
@@ -187,6 +193,38 @@ interface RateLimiter {
|
|
|
187
193
|
dispose(): void;
|
|
188
194
|
}
|
|
189
195
|
//#endregion
|
|
196
|
+
//#region ../../packages/substrate-core/src/advisor/shape-recorder.d.ts
|
|
197
|
+
interface ReadShape {
|
|
198
|
+
namespace: string;
|
|
199
|
+
type: string;
|
|
200
|
+
filters: Array<{
|
|
201
|
+
field: string;
|
|
202
|
+
op: string;
|
|
203
|
+
}>;
|
|
204
|
+
orderBy: Array<[string, 'asc' | 'desc']>;
|
|
205
|
+
/** An OR or a NOT somewhere in the filter: no composite index serves it as a conjunction. */
|
|
206
|
+
disjunctive?: true;
|
|
207
|
+
/**
|
|
208
|
+
* The boolean or null operand of each top-level (or AND-ed) `eq`, the only
|
|
209
|
+
* operand values kept: they decide whether a partial index's predicate
|
|
210
|
+
* holds, and have three possible values.
|
|
211
|
+
*/
|
|
212
|
+
literals?: Record<string, boolean | null>;
|
|
213
|
+
}
|
|
214
|
+
declare class ShapeRecorder {
|
|
215
|
+
#private;
|
|
216
|
+
/** When this recorder was created or last drained: the start of what `drain` returns. */
|
|
217
|
+
since: number;
|
|
218
|
+
constructor(now?: () => number);
|
|
219
|
+
observe(shape: ReadShape, durationMs: number): void;
|
|
220
|
+
/** Every shape seen since the last drain, with its count and p95; then forgets them. */
|
|
221
|
+
drain(): Array<{
|
|
222
|
+
shape: ReadShape;
|
|
223
|
+
count: number;
|
|
224
|
+
p95Ms: number;
|
|
225
|
+
}>;
|
|
226
|
+
}
|
|
227
|
+
//#endregion
|
|
190
228
|
//#region ../../packages/substrate-core/src/registry.d.ts
|
|
191
229
|
type TypeKey = string | {
|
|
192
230
|
readonly name: string;
|
|
@@ -232,6 +270,24 @@ interface EngineOptions {
|
|
|
232
270
|
* does no timing at all.
|
|
233
271
|
*/
|
|
234
272
|
onResolve?: (o: ResolveObservation) => void;
|
|
273
|
+
/**
|
|
274
|
+
* Observes each successful local read of a type: its shape (filtered fields
|
|
275
|
+
* and operators, the effective order including the natural one) and how long
|
|
276
|
+
* the resolver took. For the index advisor; absent means no recording.
|
|
277
|
+
*/
|
|
278
|
+
shapeRecorder?: Pick<ShapeRecorder, 'observe'>;
|
|
279
|
+
/**
|
|
280
|
+
* Coordinators' `onCommittedWrites` hooks, in registration order. Called
|
|
281
|
+
* once per `(namespace, type, operation)` per committed transaction, as
|
|
282
|
+
* that transaction commits and never awaited by the mutate; a failure is a
|
|
283
|
+
* `/health` warning.
|
|
284
|
+
*/
|
|
285
|
+
committedWritesHooks?: ReadonlyArray<{
|
|
286
|
+
plugin: string;
|
|
287
|
+
hook: CommittedWritesHook;
|
|
288
|
+
}>;
|
|
289
|
+
/** Caps on `updateMany<T>` / `deleteMany<T>`; `DEFAULT_FILTER_WRITE_LIMITS` when absent. */
|
|
290
|
+
filterWriteLimits?: FilterWriteLimits;
|
|
235
291
|
/**
|
|
236
292
|
* Idempotency dedup (§5.13). Absent → no dedup; `FrameEntry.idempotencyKey`
|
|
237
293
|
* is ignored on mutate (queries ignore it unconditionally). Present → the
|
|
@@ -280,10 +336,10 @@ interface EngineOptions {
|
|
|
280
336
|
* without the call site knowing which metric string to use.
|
|
281
337
|
*
|
|
282
338
|
* - `'cancel'` — explicit client-driven cancel (op: 'cancel') or direct handle use
|
|
283
|
-
* - `'
|
|
339
|
+
* - `'client_disconnect'` — client disconnected (response closed)
|
|
284
340
|
* - `'shutdown'` — server-initiated graceful shutdown (conn.onShutdown)
|
|
285
341
|
*/
|
|
286
|
-
type SubscriptionCancelReason = 'cancel' | '
|
|
342
|
+
type SubscriptionCancelReason = 'cancel' | 'client_disconnect' | 'shutdown';
|
|
287
343
|
interface SubscriptionHandle {
|
|
288
344
|
readonly __brand?: 'SubscriptionHandle';
|
|
289
345
|
readonly id: string;
|
|
@@ -301,8 +357,8 @@ interface SubscribeInput {
|
|
|
301
357
|
ctx: Partial<RequestContext>;
|
|
302
358
|
/**
|
|
303
359
|
* Frame sink. Sync-returning callbacks are still valid; the engine awaits
|
|
304
|
-
* whatever `onFrame` returns so back-pressure-aware transports (e.g.
|
|
305
|
-
*
|
|
360
|
+
* whatever `onFrame` returns so back-pressure-aware transports (e.g. a frame
|
|
361
|
+
* stream's write drain) can resolve asynchronously. The fanout loop tracks
|
|
306
362
|
* pending (unsettled) calls per subscription and tears the entry down when
|
|
307
363
|
* the count exceeds `EngineOptions.subscriptions.queueLimit` (§5.13).
|
|
308
364
|
*/
|
|
@@ -472,7 +528,7 @@ declare class Engine {
|
|
|
472
528
|
* caller's `probe` context so policies reading headers, `clientIp`, `meta`
|
|
473
529
|
* or `authEnabled` decide as they would in dispatch.
|
|
474
530
|
*/
|
|
475
|
-
evaluateReadPolicy(ns: string, type: string, identity: Identity | null, probe?: PolicyProbeContext): PolicyDecision;
|
|
531
|
+
evaluateReadPolicy(ns: string, type: string, identity: Identity | null, probe?: PolicyProbeContext, args?: ResolverArgs): PolicyDecision;
|
|
476
532
|
/**
|
|
477
533
|
* Refresh the cached schemas for every registered bridge. Callers invoke
|
|
478
534
|
* this at composition-root wire-up time to populate `federatedSchema()`'s
|
|
@@ -523,6 +579,17 @@ declare class Engine {
|
|
|
523
579
|
* fanout — see subscribe.ts for the full contract.
|
|
524
580
|
*/
|
|
525
581
|
subscribe(input: SubscribeInput): Promise<SubscriptionHandle>;
|
|
582
|
+
/**
|
|
583
|
+
* Announce writes committed outside `mutate` (a server-internal writer): they
|
|
584
|
+
* reach subscribers, then the coordinators' `onCommittedWrites` hooks, as a
|
|
585
|
+
* commit through `mutate` would. This is not a transaction and checks
|
|
586
|
+
* nothing: the caller guarantees `events` are already committed.
|
|
587
|
+
*/
|
|
588
|
+
announceWrites(events: readonly WriteEvent[], actor: ActorIdentity | null): Promise<void>;
|
|
589
|
+
/** Resolves once every post-write hook call queued so far has finished. */
|
|
590
|
+
hooksSettled(): Promise<void>;
|
|
591
|
+
/** The last failure per plugin whose post-write hook has not succeeded since. */
|
|
592
|
+
postWriteWarnings(): string[];
|
|
526
593
|
/**
|
|
527
594
|
* Live count of active subscription entries. Delegates to the
|
|
528
595
|
* SubscribeSubsystem, which owns the authoritative map.
|
|
@@ -618,6 +685,8 @@ export declare class MemoryEdgesStore implements EdgesStore {
|
|
|
618
685
|
*/
|
|
619
686
|
private nextId;
|
|
620
687
|
write(input: EdgeWriteInput): Promise<Edge>;
|
|
688
|
+
writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
|
|
689
|
+
tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
|
|
621
690
|
tombstone(id: string, at?: Date): Promise<void>;
|
|
622
691
|
update(patch: EdgePatch): Promise<void>;
|
|
623
692
|
readNextBatch(cursorId: string | null, size: number): Promise<{
|
|
@@ -627,6 +696,7 @@ export declare class MemoryEdgesStore implements EdgesStore {
|
|
|
627
696
|
findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
|
|
628
697
|
findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
629
698
|
findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
|
|
699
|
+
findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
630
700
|
canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
|
|
631
701
|
findBlocked(): Promise<Edge[]>;
|
|
632
702
|
findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
|
|
@@ -733,11 +803,36 @@ interface MemoryDatasetOptions {
|
|
|
733
803
|
* instants, as the pg dataset's lookup does; without it they compare as text.
|
|
734
804
|
*/
|
|
735
805
|
fieldDefLookup?: (type: string, field: string) => FieldDef | undefined;
|
|
806
|
+
/**
|
|
807
|
+
* The namespace's type definitions; a type declared `ordering: 'visible'`
|
|
808
|
+
* gets `_metadata.seq` on insert, as the pg dataset's lookup does. Its
|
|
809
|
+
* `fields` say which keys read back absent when null (`isColumnField`).
|
|
810
|
+
*/
|
|
811
|
+
typeDefLookup?: (type: string, namespace: string) => {
|
|
812
|
+
ordering?: 'visible';
|
|
813
|
+
fields?: Record<string, FieldDef>;
|
|
814
|
+
} | undefined;
|
|
815
|
+
/**
|
|
816
|
+
* Internal: binding assignments one read's walks may try before refusing
|
|
817
|
+
* `walk_budget_exceeded`. Defaults to `WALK_EVALUATION_BUDGET`; tests lower it.
|
|
818
|
+
*/
|
|
819
|
+
walkBudget?: number;
|
|
820
|
+
/**
|
|
821
|
+
* Test-only: declare and answer the typed-edge-walk grammar. The memory
|
|
822
|
+
* dataset is the parity reference for the pg walk compiler, not a walk
|
|
823
|
+
* store; without this the engine refuses walks on it (`walks_unsupported_store`).
|
|
824
|
+
*/
|
|
825
|
+
walkReference?: boolean;
|
|
736
826
|
}
|
|
737
827
|
export declare class MemoryDataset implements Dataset {
|
|
738
828
|
#private;
|
|
739
829
|
readonly namespace: string;
|
|
740
830
|
readonly txScopeId: string;
|
|
831
|
+
private readonly typeDefLookup;
|
|
832
|
+
private readonly walkBudget;
|
|
833
|
+
private readonly walkReference;
|
|
834
|
+
/** Last seq assigned per visible-order type; never decreases, as pg's `visible_seqs`. */
|
|
835
|
+
private seqs;
|
|
741
836
|
readonly capabilities: FilterCapabilities;
|
|
742
837
|
/** See `Dataset.withAdvisoryLock`. Excludes holders on this instance. */
|
|
743
838
|
withAdvisoryLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
|
|
@@ -746,7 +841,15 @@ export declare class MemoryDataset implements Dataset {
|
|
|
746
841
|
constructor(options: MemoryDatasetOptions);
|
|
747
842
|
private bucket;
|
|
748
843
|
read(type: string, params: ReadParams): Promise<ReadResult>;
|
|
749
|
-
|
|
844
|
+
/**
|
|
845
|
+
* Walks over this namespace's live rows, for one read. Neighbours follow the
|
|
846
|
+
* row body's crossRef value (spec 2026-10-24-typed-edge-walks §1), indexed
|
|
847
|
+
* per (type, field) on first use.
|
|
848
|
+
*/
|
|
849
|
+
private walkContext;
|
|
850
|
+
write(type: string, rows: WriteRow[], options?: WriteOptions): Promise<WriteResult>;
|
|
851
|
+
/** The type's column fields, looked up once per call rather than per row. */
|
|
852
|
+
private columnFieldNames;
|
|
750
853
|
tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
751
854
|
purge(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
752
855
|
dropType(type: string): Promise<DropResult>;
|
|
@@ -779,6 +882,18 @@ export declare class MemoryDataset implements Dataset {
|
|
|
779
882
|
allocateShortId(type: string): Promise<number>;
|
|
780
883
|
bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
|
|
781
884
|
resolveShortId(type: string, shortId: number): Promise<string | null>;
|
|
885
|
+
allocateShortIds(type: string, count: number): Promise<number[]>;
|
|
886
|
+
bindShortIds(type: string, pairs: ReadonlyArray<{
|
|
887
|
+
shortId: number;
|
|
888
|
+
rowId: string;
|
|
889
|
+
}>): Promise<void>;
|
|
890
|
+
resolveShortIds(type: string, shortIds: readonly number[]): Promise<ReadonlyMap<number, string>>;
|
|
891
|
+
patchRows(type: string, patches: ReadonlyArray<{
|
|
892
|
+
id: Id;
|
|
893
|
+
patch: Record<string, unknown>;
|
|
894
|
+
}>, actor: ActorIdentity | null, now: Date): Promise<Array<Row | null>>;
|
|
895
|
+
updateWhere(type: string, where: WhereClause, set: Record<string, unknown>, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
896
|
+
deleteWhere(type: string, where: WhereClause, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
782
897
|
getShortIdForRow(type: string, rowId: string): Promise<number | null>;
|
|
783
898
|
forNamespace(namespace: string): Dataset;
|
|
784
899
|
}
|
|
@@ -891,7 +1006,7 @@ interface ComposeOpts {
|
|
|
891
1006
|
bridges?: BridgeRegistry;
|
|
892
1007
|
/**
|
|
893
1008
|
* JWT auth config (§5.12). When supplied, route handlers for
|
|
894
|
-
* `/substrate/v1/query`, `/substrate/v1/mutate`, and
|
|
1009
|
+
* `/substrate/v1/query`, `/substrate/v1/mutate`, `/substrate/v1/subscribe` and `/substrate/v1/stream` require a
|
|
895
1010
|
* valid `Authorization: Bearer <token>` header; missing / invalid tokens
|
|
896
1011
|
* return 401 with `{ code: 'unauthorized' }`. When absent, every request
|
|
897
1012
|
* passes through unauthenticated, attributed to `systemActor`.
|
|
@@ -928,7 +1043,7 @@ interface ComposeOpts {
|
|
|
928
1043
|
* §5.13 subscription back-pressure override. Threads straight into
|
|
929
1044
|
* `EngineOptions.subscriptions`. Default (absent): engine default
|
|
930
1045
|
* queueLimit of 256. Conformance tests set a tiny limit to trigger the
|
|
931
|
-
* teardown contract deterministically (docs/
|
|
1046
|
+
* teardown contract deterministically (docs/stream-contract.md).
|
|
932
1047
|
*/
|
|
933
1048
|
subscriptions?: {
|
|
934
1049
|
queueLimit?: number;
|
|
@@ -954,6 +1069,12 @@ interface ComposeOpts {
|
|
|
954
1069
|
defaultLimit: number;
|
|
955
1070
|
maxLimit: number;
|
|
956
1071
|
};
|
|
1072
|
+
/**
|
|
1073
|
+
* Caps on `updateMany<T>` / `deleteMany<T>`: the most rows one filter may
|
|
1074
|
+
* match (more is refused `filter_too_broad`), and the most ids a result
|
|
1075
|
+
* returns. Defaults to 10000 and 1000.
|
|
1076
|
+
*/
|
|
1077
|
+
filterWriteLimits?: FilterWriteLimits;
|
|
957
1078
|
/**
|
|
958
1079
|
* Opt-in periodic re-prime interval (ms) for the
|
|
959
1080
|
* `KeyRegistry` public-key cache. Bounds cross-instance revocation
|
|
@@ -965,15 +1086,11 @@ interface ComposeOpts {
|
|
|
965
1086
|
*/
|
|
966
1087
|
keyReprimeIntervalMs?: number;
|
|
967
1088
|
/**
|
|
968
|
-
*
|
|
969
|
-
*
|
|
970
|
-
*
|
|
971
|
-
* authenticate on this signature alone, the dev default is a published
|
|
972
|
-
* constant, and `''` / `' '` are HMAC keys Node accepts. Omit it only with
|
|
973
|
-
* auth disabled, where `gate` is the identity function and there is nothing
|
|
974
|
-
* to bypass. Trimmed before use.
|
|
1089
|
+
* Seals pagination cursors under a row-filter policy. Every process sharing
|
|
1090
|
+
* it opens the same cursors; without it the key is per process, so a sealed
|
|
1091
|
+
* cursor stops opening after a restart or on another replica. Trimmed.
|
|
975
1092
|
*/
|
|
976
|
-
|
|
1093
|
+
cursorSealSecret?: string;
|
|
977
1094
|
/**
|
|
978
1095
|
* Effective value + provenance for every defaulted knob, as the caller's
|
|
979
1096
|
* env parser resolved them. When present, compose mounts
|
|
@@ -984,6 +1101,28 @@ interface ComposeOpts {
|
|
|
984
1101
|
* second reading of the environment. Omitted by programmatic embedders.
|
|
985
1102
|
*/
|
|
986
1103
|
configReport?: ConfigReport;
|
|
1104
|
+
/** Reported beside `configReport`; ignored without it. */
|
|
1105
|
+
storageReport?: () => Promise<StorageReport>;
|
|
1106
|
+
/**
|
|
1107
|
+
* The index advisor. Every `intervalMs` (`SUBSTRATE_ADVISOR_INTERVAL_MS`)
|
|
1108
|
+
* it turns the reads the engine recorded and the store's statistics into
|
|
1109
|
+
* `_system/IndexRecommendation` rows. Omitted or `intervalMs: 0`: off, and
|
|
1110
|
+
* no read is recorded. `storeProfile` seeds `_system/StoreProfile` when it
|
|
1111
|
+
* has no row yet.
|
|
1112
|
+
*/
|
|
1113
|
+
advisor?: {
|
|
1114
|
+
intervalMs: number;
|
|
1115
|
+
storeProfile?: StoreProfileName;
|
|
1116
|
+
writeHeavy?: boolean;
|
|
1117
|
+
};
|
|
1118
|
+
/**
|
|
1119
|
+
* The promotion sweep, every `intervalMs` (`SUBSTRATE_PROMOTE_INTERVAL_MS`),
|
|
1120
|
+
* over `dataset`'s pending fields. Omitted or `intervalMs: 0`: no timer;
|
|
1121
|
+
* `POST /substrate/v1/_system/promote-fields` runs it either way.
|
|
1122
|
+
*/
|
|
1123
|
+
promoteFields?: {
|
|
1124
|
+
intervalMs: number;
|
|
1125
|
+
};
|
|
987
1126
|
}
|
|
988
1127
|
interface ComposeResult {
|
|
989
1128
|
engine: Engine;
|
|
@@ -1006,6 +1145,12 @@ interface ComposeResult {
|
|
|
1006
1145
|
* loop in `main.ts`.
|
|
1007
1146
|
*/
|
|
1008
1147
|
runSweepNow: () => Promise<SweepState>;
|
|
1148
|
+
/** Run one index-advisor pass now, for tests; null while the advisor is off. */
|
|
1149
|
+
runAdvisorNow: (() => Promise<{
|
|
1150
|
+
upserted: number;
|
|
1151
|
+
}>) | null;
|
|
1152
|
+
/** Run one promotion sweep now, as the admin route does. */
|
|
1153
|
+
runPromoteFieldsNow: () => Promise<PromotionEvent[]>;
|
|
1009
1154
|
/**
|
|
1010
1155
|
* Non-null when any coordinator plugin contributed a `schedule`. The
|
|
1011
1156
|
* composition root constructs the scheduler, registers every plugin's
|
|
@@ -1022,6 +1167,563 @@ interface ComposeResult {
|
|
|
1022
1167
|
}
|
|
1023
1168
|
export declare function compose(opts: ComposeOpts): Promise<ComposeResult>;
|
|
1024
1169
|
//#endregion
|
|
1170
|
+
//#region ../../packages/substrate-dataset-pg/src/tx-scope.d.ts
|
|
1171
|
+
type PgHandle = Sql | TransactionSql;
|
|
1172
|
+
//#endregion
|
|
1173
|
+
//#region ../../packages/substrate-dataset-pg/src/type-table.d.ts
|
|
1174
|
+
type ColumnKind = 'text' | 'enum' | 'number' | 'int16' | 'int32' | 'int64' | 'date' | 'boolean' | 'crossRef';
|
|
1175
|
+
interface TypedColumn {
|
|
1176
|
+
field: string;
|
|
1177
|
+
column: string;
|
|
1178
|
+
kind: ColumnKind;
|
|
1179
|
+
state: 'column' | 'promoting' | 'orphaned';
|
|
1180
|
+
vocab?: readonly string[];
|
|
1181
|
+
}
|
|
1182
|
+
interface TypeTable {
|
|
1183
|
+
namespace: string;
|
|
1184
|
+
type: string;
|
|
1185
|
+
/** The table, as a quoted identifier. */
|
|
1186
|
+
from: string;
|
|
1187
|
+
/** The jsonb column holding every field without a column of its own. */
|
|
1188
|
+
jsonb: 'extra';
|
|
1189
|
+
column(field: string): TypedColumn | undefined;
|
|
1190
|
+
columns(): readonly TypedColumn[];
|
|
1191
|
+
/** Declared fields whose values live in `extra` until they get a column. */
|
|
1192
|
+
pending: readonly string[];
|
|
1193
|
+
orphaned: readonly string[];
|
|
1194
|
+
/**
|
|
1195
|
+
* The catalog version this descriptor was loaded at (bigint text). Every
|
|
1196
|
+
* write checks it in its own statement (`guardCte`), so one built from a
|
|
1197
|
+
* stale descriptor writes nothing and is rebuilt.
|
|
1198
|
+
*/
|
|
1199
|
+
version: string;
|
|
1200
|
+
}
|
|
1201
|
+
/**
|
|
1202
|
+
* A pool's type-table descriptors. A
|
|
1203
|
+
* `substrate_catalog` notification (sent by `ensureTypeTable` on any change,
|
|
1204
|
+
* delivered at commit) drops its type's entry, and a (re)connect of the
|
|
1205
|
+
* listener drops them all, since notifications may have been missed.
|
|
1206
|
+
*/
|
|
1207
|
+
interface TableCache {
|
|
1208
|
+
/** The pool, which LISTENs on a connection of its own. */
|
|
1209
|
+
sql: PgHandle;
|
|
1210
|
+
/** `null` is a cached miss: the type has no table yet. */
|
|
1211
|
+
tables: Map<string, TypeTable | null>;
|
|
1212
|
+
/** Bumped on each drop; a load notes it at its start (see {@link mayCache}). */
|
|
1213
|
+
gen: number;
|
|
1214
|
+
/** Each key's last drop's `gen`, so a load is refused only for a drop of its own key. */
|
|
1215
|
+
dropped: Map<string, number>;
|
|
1216
|
+
/** The last full clear's `gen`. */
|
|
1217
|
+
cleared: number;
|
|
1218
|
+
/** True once listening; false when LISTEN failed, and then nothing is cached. */
|
|
1219
|
+
listening?: Promise<boolean>;
|
|
1220
|
+
/** After a failed LISTEN, when the next call may try again. */
|
|
1221
|
+
listenRetryAt?: number;
|
|
1222
|
+
/** Only `true` is kept: the migration can be applied while this process runs, never unapplied. */
|
|
1223
|
+
uuidCheck?: true;
|
|
1224
|
+
}
|
|
1225
|
+
//#endregion
|
|
1226
|
+
//#region ../../packages/substrate-dataset-pg/src/disk-guard.d.ts
|
|
1227
|
+
/**
|
|
1228
|
+
* Refuses a background index build that would leave less than a margin of
|
|
1229
|
+
* free space on the database volume. Postgres cannot report filesystem space,
|
|
1230
|
+
* so the volume is a local path the operator names; with none, every build is
|
|
1231
|
+
* allowed and `path` is undefined so the storage report can say checks are off.
|
|
1232
|
+
*/
|
|
1233
|
+
interface DiskGuard {
|
|
1234
|
+
readonly path: string | undefined;
|
|
1235
|
+
check(estimateBytes: number): Promise<{
|
|
1236
|
+
ok: true;
|
|
1237
|
+
} | {
|
|
1238
|
+
ok: false;
|
|
1239
|
+
freeBytes: number;
|
|
1240
|
+
needBytes: number;
|
|
1241
|
+
}>;
|
|
1242
|
+
}
|
|
1243
|
+
//#endregion
|
|
1244
|
+
//#region ../../packages/substrate-dataset-pg/src/layout.d.ts
|
|
1245
|
+
type StorageLayout = 'tables';
|
|
1246
|
+
//#endregion
|
|
1247
|
+
//#region ../../packages/substrate-dataset-pg/src/migrate.d.ts
|
|
1248
|
+
/**
|
|
1249
|
+
* Public migration shape accepted by the runner. Either supply both
|
|
1250
|
+
* `txStatements` + (optional) `concurrentStatements`, OR a legacy
|
|
1251
|
+
* `statements` bucket — the runner treats `statements` as `txStatements`
|
|
1252
|
+
* with no concurrent statements. Mixing `statements` and `txStatements`
|
|
1253
|
+
* is a configuration error.
|
|
1254
|
+
*/
|
|
1255
|
+
type MigrationInput = {
|
|
1256
|
+
readonly version: string;
|
|
1257
|
+
readonly txStatements: ReadonlyArray<string>;
|
|
1258
|
+
readonly concurrentStatements?: ReadonlyArray<string>;
|
|
1259
|
+
readonly statements?: never;
|
|
1260
|
+
} | {
|
|
1261
|
+
readonly version: string;
|
|
1262
|
+
readonly statements: ReadonlyArray<string>;
|
|
1263
|
+
readonly txStatements?: never;
|
|
1264
|
+
readonly concurrentStatements?: never;
|
|
1265
|
+
};
|
|
1266
|
+
interface RunMigrationsOptions {
|
|
1267
|
+
/**
|
|
1268
|
+
* When true, drop the `migrations` tracking table before running.
|
|
1269
|
+
* Forces every migration to re-apply on this call. Intended for tests
|
|
1270
|
+
* that DROP schema objects between runs and need the framework to
|
|
1271
|
+
* recreate them; production paths should never set this.
|
|
1272
|
+
*/
|
|
1273
|
+
force?: boolean;
|
|
1274
|
+
/**
|
|
1275
|
+
* Override the `SUBSTRATE_ENFORCE_UUID_CHECK=true` env-var gate for the gated
|
|
1276
|
+
* UUID-format CHECK constraint migration (0002). Defaults to whatever the
|
|
1277
|
+
* env says. Tests that need to exercise the constrained path explicitly
|
|
1278
|
+
* pass `true`; tests that need to opt out of an env-set gate pass `false`.
|
|
1279
|
+
* Production bootstraps shouldn't pass this — let the env decide.
|
|
1280
|
+
*/
|
|
1281
|
+
enforceUuidCheck?: boolean;
|
|
1282
|
+
}
|
|
1283
|
+
export declare function runMigrations(sql: Sql, opts?: RunMigrationsOptions): Promise<void>;
|
|
1284
|
+
/**
|
|
1285
|
+
* One `field.list({ indexed: true })` or `field.json({ indexed: true })` field
|
|
1286
|
+
* that should be backed by a GIN over `(body -> field)`.
|
|
1287
|
+
*/
|
|
1288
|
+
interface IndexedListField {
|
|
1289
|
+
readonly namespace: string;
|
|
1290
|
+
readonly type: string;
|
|
1291
|
+
readonly field: string;
|
|
1292
|
+
}
|
|
1293
|
+
/**
|
|
1294
|
+
* Derives the tracked, idempotent CONCURRENTLY GIN migration for one indexed
|
|
1295
|
+
* field, as the legacy layout built it on `rows`. The version key uses the raw
|
|
1296
|
+
* ns/type/field. `runDerivedMigrations` skips these: each type table's GIN
|
|
1297
|
+
* indexes are its own, built by `reconcileTypeIndexes`.
|
|
1298
|
+
*/
|
|
1299
|
+
export declare function deriveListIndexMigration(f: IndexedListField): MigrationInput;
|
|
1300
|
+
/**
|
|
1301
|
+
* Applies migrations derived from field definitions through the same tracked,
|
|
1302
|
+
* advisory-locked machinery as the static list. Called after plugins load,
|
|
1303
|
+
* since `runMigrations` has no field-def knowledge. Idempotent: applied
|
|
1304
|
+
* versions are skipped.
|
|
1305
|
+
*
|
|
1306
|
+
* The list/json GIN migrations are skipped: there is no `rows` to aim them
|
|
1307
|
+
* at, and each type table's indexes are its own (`reconcileTypeIndexes`).
|
|
1308
|
+
*/
|
|
1309
|
+
export declare function runDerivedMigrations(sql: Sql, all: ReadonlyArray<MigrationInput>): Promise<void>;
|
|
1310
|
+
//#endregion
|
|
1311
|
+
//#region ../../packages/substrate-dataset-pg/src/pg-edges-store.d.ts
|
|
1312
|
+
interface PgEdgesStoreOptions {
|
|
1313
|
+
sql: Sql;
|
|
1314
|
+
/** Injected clock for tests. Defaults to `() => new Date()`. */
|
|
1315
|
+
now?: () => Date;
|
|
1316
|
+
/**
|
|
1317
|
+
* Per-statement batch size for chunked admin deletes. Defaults to
|
|
1318
|
+
* {@link DEFAULT_DROP_BATCH_SIZE}.
|
|
1319
|
+
*/
|
|
1320
|
+
dropBatchSize?: number;
|
|
1321
|
+
}
|
|
1322
|
+
interface InternalPgEdgesStoreOptions {
|
|
1323
|
+
sql: PgHandle;
|
|
1324
|
+
now: () => Date;
|
|
1325
|
+
inTx: boolean;
|
|
1326
|
+
/**
|
|
1327
|
+
* Tx-bound instances inherit their parent's txScopeId. The public
|
|
1328
|
+
* constructor derives it from the Sql reference.
|
|
1329
|
+
*/
|
|
1330
|
+
txScopeId?: string;
|
|
1331
|
+
dropBatchSize?: number;
|
|
1332
|
+
}
|
|
1333
|
+
export declare class PgEdgesStore implements EdgesStore {
|
|
1334
|
+
#private;
|
|
1335
|
+
readonly txScopeId: string;
|
|
1336
|
+
constructor(options: PgEdgesStoreOptions | InternalPgEdgesStoreOptions);
|
|
1337
|
+
write(input: EdgeWriteInput): Promise<Edge>;
|
|
1338
|
+
writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
|
|
1339
|
+
tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
|
|
1340
|
+
tombstone(id: string, at?: Date): Promise<void>;
|
|
1341
|
+
/**
|
|
1342
|
+
* Hard-deletes tombstoned edges whose `deleted_at` is older than
|
|
1343
|
+
* `olderThan`. Called by the sweep loop. Returns the number deleted.
|
|
1344
|
+
*/
|
|
1345
|
+
purgeTombstonedEdges(opts: {
|
|
1346
|
+
olderThan: Date;
|
|
1347
|
+
}): Promise<{
|
|
1348
|
+
deleted: number;
|
|
1349
|
+
}>;
|
|
1350
|
+
update(patch: EdgePatch): Promise<void>;
|
|
1351
|
+
readNextBatch(cursorId: string | null, size: number): Promise<{
|
|
1352
|
+
edges: Edge[];
|
|
1353
|
+
lastId: string | null;
|
|
1354
|
+
}>;
|
|
1355
|
+
findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
|
|
1356
|
+
findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
1357
|
+
findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
1358
|
+
findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
|
|
1359
|
+
findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
|
|
1360
|
+
findEdgesTouchingType(namespace: string, type: string, limit: number): Promise<Edge[]>;
|
|
1361
|
+
namespacesLinkedTo(namespace: string, type?: string): Promise<string[]>;
|
|
1362
|
+
/**
|
|
1363
|
+
* Chunked physical delete of every edge touching `namespace`, at most
|
|
1364
|
+
* `dropBatchSize` rows per statement, so a large delete does not hold every
|
|
1365
|
+
* row lock at once. Returns the number deleted.
|
|
1366
|
+
*
|
|
1367
|
+
* Outside a tx each batch auto-commits. Inside a caller's tx the batches
|
|
1368
|
+
* stay in it, so a throw still rolls back the whole drop.
|
|
1369
|
+
*/
|
|
1370
|
+
dropEdgesByNamespace(namespace: string, within?: readonly string[]): Promise<number>;
|
|
1371
|
+
/**
|
|
1372
|
+
* Chunked physical delete of every edge touching `(namespace, type)`.
|
|
1373
|
+
* See {@link dropEdgesByNamespace} for the lock-hold + tx semantics.
|
|
1374
|
+
*/
|
|
1375
|
+
dropEdgesByType(namespace: string, type: string, within?: readonly string[]): Promise<number>;
|
|
1376
|
+
canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
|
|
1377
|
+
findBlocked(): Promise<Edge[]>;
|
|
1378
|
+
/**
|
|
1379
|
+
* `sql.begin`-backed atomicity. Same flattening pattern as PgDataset —
|
|
1380
|
+
* nested re-entry skips the inner begin and runs on the existing tx handle
|
|
1381
|
+
* so an inner throw propagates to the outer `sql.begin` for rollback.
|
|
1382
|
+
*/
|
|
1383
|
+
withTransaction<T>(fn: (tx: EdgesStore) => Promise<T>): Promise<T>;
|
|
1384
|
+
/**
|
|
1385
|
+
* Engine-only. Returns a tx-bound clone on the supplied `TransactionSql`,
|
|
1386
|
+
* for `PgDataset.withScopedTransaction`. The caller has verified
|
|
1387
|
+
* the txScopeIds match.
|
|
1388
|
+
*/
|
|
1389
|
+
_enlistInTx(txSql: PgHandle): PgEdgesStore;
|
|
1390
|
+
}
|
|
1391
|
+
//#endregion
|
|
1392
|
+
//#region ../../packages/substrate-dataset-pg/src/pg-dataset.d.ts
|
|
1393
|
+
/**
|
|
1394
|
+
* Returns the declared FieldDef for a type's field, or undefined when unknown
|
|
1395
|
+
* (body-key sorts then fall back to text compare). Lets the SQL builders cast
|
|
1396
|
+
* body values by declared kind, so `count` sorts 2 before 10 — see
|
|
1397
|
+
* `resolveBodyOrderByCast`.
|
|
1398
|
+
*/
|
|
1399
|
+
type FieldDefLookup = (type: string, field: string) => FieldDef | undefined;
|
|
1400
|
+
/**
|
|
1401
|
+
* A type's declared fields and indexes, or undefined when the type is unknown.
|
|
1402
|
+
* Called with the asking dataset's namespace, so a `forNamespace` clone that
|
|
1403
|
+
* inherits the lookup resolves its own types.
|
|
1404
|
+
*/
|
|
1405
|
+
type TypeDefLookup = (type: string, namespace: string) => {
|
|
1406
|
+
fields: Record<string, FieldDef>;
|
|
1407
|
+
indexes?: IndexDecl[];
|
|
1408
|
+
orderedBy?: OrderedBy;
|
|
1409
|
+
ordering?: 'visible';
|
|
1410
|
+
expectedSize?: 'small' | 'large';
|
|
1411
|
+
} | undefined;
|
|
1412
|
+
interface PgDatasetOptions {
|
|
1413
|
+
namespace: string;
|
|
1414
|
+
sql: Sql;
|
|
1415
|
+
/**
|
|
1416
|
+
* Optional sibling `PgEdgesStore` to enlist into this dataset's substrate
|
|
1417
|
+
* transactions. When supplied, MUST share the same `Sql` pool (verified
|
|
1418
|
+
* via `txScopeId === txScopeIdFor(sql)`); the dataset throws on
|
|
1419
|
+
* construction otherwise.
|
|
1420
|
+
*
|
|
1421
|
+
* When supplied, `withScopedTransaction` yields a tx-bound edges store
|
|
1422
|
+
* on the same `TransactionSql` as the tx-bound datasets. When omitted, it
|
|
1423
|
+
* yields `edges: null` and the engine runs edge ops in a separate tx.
|
|
1424
|
+
*/
|
|
1425
|
+
edgesStore?: PgEdgesStore;
|
|
1426
|
+
/**
|
|
1427
|
+
* Optional field-def lookup so orderBy + cursor compares on body fields can
|
|
1428
|
+
* cast to the declared scalar pg type (numeric / timestamptz / boolean)
|
|
1429
|
+
* instead of falling back to lexicographic text compare. When omitted, every
|
|
1430
|
+
* body-key orderBy compares as text.
|
|
1431
|
+
*
|
|
1432
|
+
* A cast sort cannot use an index on the uncast `(body ->> 'field')`
|
|
1433
|
+
* expression; it needs a matching cast expression index.
|
|
1434
|
+
*/
|
|
1435
|
+
fieldDefLookup?: FieldDefLookup;
|
|
1436
|
+
/**
|
|
1437
|
+
* The namespace's type definitions, which `ensureTypeStorage` builds the
|
|
1438
|
+
* type's indexes from. Without it only the engine's own indexes are built.
|
|
1439
|
+
*/
|
|
1440
|
+
typeDefLookup?: TypeDefLookup;
|
|
1441
|
+
/**
|
|
1442
|
+
* Checked before each non-unique index build `ensureTypeStorage` runs; a
|
|
1443
|
+
* refused build stays `pending` (`insufficient_disk`) until a later pass.
|
|
1444
|
+
* Without one nothing is checked. With one that has no path, nothing is
|
|
1445
|
+
* checked either, and `storageReport` says so.
|
|
1446
|
+
*/
|
|
1447
|
+
diskGuard?: DiskGuard;
|
|
1448
|
+
/**
|
|
1449
|
+
* The statement timeout a walk read runs under, in ms (default
|
|
1450
|
+
* `WALK_STATEMENT_TIMEOUT_MS`). A read it cancels is refused as
|
|
1451
|
+
* `query_timeout`.
|
|
1452
|
+
*/
|
|
1453
|
+
statementTimeoutMs?: number;
|
|
1454
|
+
}
|
|
1455
|
+
interface InternalPgSubstrateDatasetOptions {
|
|
1456
|
+
namespace: string;
|
|
1457
|
+
sql: PgHandle;
|
|
1458
|
+
inTx: boolean;
|
|
1459
|
+
/**
|
|
1460
|
+
* Tx-bound instances reuse the root's txScopeId so one substrate never
|
|
1461
|
+
* advertises two ids. The public constructor derives it from the Sql.
|
|
1462
|
+
*/
|
|
1463
|
+
txScopeId?: string;
|
|
1464
|
+
edgesStore?: PgEdgesStore;
|
|
1465
|
+
fieldDefLookup?: FieldDefLookup;
|
|
1466
|
+
/** Shared with the instance this one was derived from. */
|
|
1467
|
+
layoutCache?: LayoutCache;
|
|
1468
|
+
typeDefLookup?: TypeDefLookup;
|
|
1469
|
+
diskGuard?: DiskGuard;
|
|
1470
|
+
statementTimeoutMs?: number;
|
|
1471
|
+
/** The pool's type-table cache, shared with the instance this one was derived from. */
|
|
1472
|
+
tableCache?: TableCache;
|
|
1473
|
+
/** The enclosing transaction's tables, which enter `tableCache` on commit only. */
|
|
1474
|
+
txTables?: TxTables;
|
|
1475
|
+
}
|
|
1476
|
+
/**
|
|
1477
|
+
* The tables a transaction loaded or created, each with the cache generation
|
|
1478
|
+
* it was loaded at. They enter the pool's cache when the transaction commits,
|
|
1479
|
+
* so a rolled-back CREATE or ALTER is never cached (F18).
|
|
1480
|
+
*/
|
|
1481
|
+
/**
|
|
1482
|
+
* A transaction's descriptors. `snapshot`: loaded for a non-READ COMMITTED
|
|
1483
|
+
* transaction's own snapshot (`null`: no table there), which never reaches
|
|
1484
|
+
* the pool's cache.
|
|
1485
|
+
*/
|
|
1486
|
+
type TxTables = Map<string, {
|
|
1487
|
+
table: TypeTable | null;
|
|
1488
|
+
gen: number;
|
|
1489
|
+
snapshot?: true;
|
|
1490
|
+
}>;
|
|
1491
|
+
/** The store's layout once migrated, shared by an instance and every clone of it. */
|
|
1492
|
+
interface LayoutCache {
|
|
1493
|
+
layout?: StorageLayout;
|
|
1494
|
+
}
|
|
1495
|
+
export declare class PgDataset implements Dataset {
|
|
1496
|
+
#private;
|
|
1497
|
+
readonly namespace: string;
|
|
1498
|
+
readonly capabilities: FilterCapabilities;
|
|
1499
|
+
readonly txScopeId: string;
|
|
1500
|
+
constructor(options: PgDatasetOptions | InternalPgSubstrateDatasetOptions);
|
|
1501
|
+
/**
|
|
1502
|
+
* Reads rows of `type` per the §5.2 filter contract (where / orderBy /
|
|
1503
|
+
* cursor / limit). Every value is bound through a parameterised slot.
|
|
1504
|
+
*
|
|
1505
|
+
* The walk grammar (spec 2026-10-24-typed-edge-walks §3) runs in a
|
|
1506
|
+
* transaction under a `SET LOCAL` statement timeout, since pg has no walk
|
|
1507
|
+
* evaluation budget. Other reads are unchanged.
|
|
1508
|
+
*/
|
|
1509
|
+
read(type: string, params: ReadParams): Promise<ReadResult>;
|
|
1510
|
+
/**
|
|
1511
|
+
* Upsert `rows`. A row without an `id` gets one from the database's
|
|
1512
|
+
* `uuidv7()`, returned in `ids` in input order. Limits of a v7 id: it is
|
|
1513
|
+
* never a happened-before signal; ids sort in creation order only within one
|
|
1514
|
+
* connection (across connections within a millisecond, and for
|
|
1515
|
+
* client-supplied ids, order is arbitrary); it reveals its creation time;
|
|
1516
|
+
* and deciding who won (last-writer-wins, `conditionalUpdate`) uses the
|
|
1517
|
+
* database's transaction time or a per-row version, never the id.
|
|
1518
|
+
*
|
|
1519
|
+
* A supplied id repeated in one batch: under `insertOnly` the first
|
|
1520
|
+
* occurrence lands and the rest are skipped; otherwise the batch is refused.
|
|
1521
|
+
*
|
|
1522
|
+
* On an `ordering: 'visible'` type each inserted row gets the next `seq`,
|
|
1523
|
+
* consecutive in input order, under a per-type transaction lock held until
|
|
1524
|
+
* commit, so seq order is commit order. A row that already exists keeps its
|
|
1525
|
+
* seq, and one `insertOnly` skips gets none.
|
|
1526
|
+
*/
|
|
1527
|
+
write(type: string, rows: WriteRow[], options?: WriteOptions): Promise<WriteResult>;
|
|
1528
|
+
tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
1529
|
+
/** On a type table, `deleted` also leaves `row_ids`, and `short_ids` cascade from there. */
|
|
1530
|
+
purge(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
1531
|
+
/**
|
|
1532
|
+
* Hard-deletes tombstoned rows whose `deleted_at` is older than `olderThan`,
|
|
1533
|
+
* across ALL namespaces (the table is substrate-shared). Called by the sweep
|
|
1534
|
+
* loop. Returns the number of rows deleted.
|
|
1535
|
+
*
|
|
1536
|
+
* Each type table is swept in one pass, a window of {@link purgeBatch} ids
|
|
1537
|
+
* per statement in id order, and a swept row leaves `row_ids` in the same
|
|
1538
|
+
* statement, its short id cascading.
|
|
1539
|
+
*/
|
|
1540
|
+
purgeTombstonedRows(opts: {
|
|
1541
|
+
olderThan: Date;
|
|
1542
|
+
}): Promise<{
|
|
1543
|
+
deleted: number;
|
|
1544
|
+
}>;
|
|
1545
|
+
/**
|
|
1546
|
+
* Hard-delete every row for `type` in this namespace, including tombstoned
|
|
1547
|
+
* rows (`deleted_at IS NOT NULL`). Short-id mappings for that type are
|
|
1548
|
+
* removed in the same logical operation. Both deletes run through `this.#sql`
|
|
1549
|
+
* so they participate in any surrounding `withTransaction` boundary. A type
|
|
1550
|
+
* table is emptied, not dropped.
|
|
1551
|
+
*/
|
|
1552
|
+
dropType(type: string): Promise<DropResult>;
|
|
1553
|
+
/**
|
|
1554
|
+
* Hard-delete every row across all types in this namespace, including
|
|
1555
|
+
* tombstoned rows. Short-id mappings for all types are removed too.
|
|
1556
|
+
*/
|
|
1557
|
+
dropNamespace(): Promise<DropResult>;
|
|
1558
|
+
/**
|
|
1559
|
+
* Compare-and-update (spec §5.12): merges `updates` into the live row only
|
|
1560
|
+
* if every `match` field equals its expected value. Returns `matched` and
|
|
1561
|
+
* the updated row.
|
|
1562
|
+
*
|
|
1563
|
+
* One `UPDATE ... WHERE <pk> AND <match>`, so the row lock makes exactly one
|
|
1564
|
+
* of N concurrent callers match. `_deletedAt` and `id` are dropped from
|
|
1565
|
+
* `updates`.
|
|
1566
|
+
*/
|
|
1567
|
+
conditionalUpdate(type: string, id: Id, match: Record<string, unknown>, updates: Record<string, unknown>, actor?: ActorIdentity, now?: Date): Promise<ConditionalUpdateResult>;
|
|
1568
|
+
updateField(ref: UpdateFieldRef, fieldName: string, value: unknown): Promise<void>;
|
|
1569
|
+
/**
|
|
1570
|
+
* `sql.begin`-backed atomicity. Spec §5.3 / G1.
|
|
1571
|
+
*
|
|
1572
|
+
* Nested calls flatten: postgres.js's `begin` inside a `begin` would create
|
|
1573
|
+
* a savepoint (inner rolls back independently of outer), which is stricter
|
|
1574
|
+
* than the G1 contract promises. To match the memory impl — where an inner
|
|
1575
|
+
* throw tears down outer writes too — we detect the re-entry via `#inTx`
|
|
1576
|
+
* and skip the nested begin entirely. The inner throw then propagates to
|
|
1577
|
+
* the outer `sql.begin`, which rolls back the whole thing.
|
|
1578
|
+
*/
|
|
1579
|
+
withTransaction<T>(fn: (tx: Dataset) => Promise<T>): Promise<T>;
|
|
1580
|
+
/**
|
|
1581
|
+
* Runs `fn` in one pg transaction with a tx-bound dataset per requested
|
|
1582
|
+
* namespace (and the edges store, when wired), all on one `TransactionSql`.
|
|
1583
|
+
* A throw rolls back every namespace. Spec §5.3.
|
|
1584
|
+
*
|
|
1585
|
+
* Nested calls flatten onto the current transaction rather than opening a
|
|
1586
|
+
* savepoint.
|
|
1587
|
+
*/
|
|
1588
|
+
withScopedTransaction<T>(namespaces: ReadonlyArray<string>, fn: (handles: TxScopeHandles) => Promise<T>): Promise<T>;
|
|
1589
|
+
/**
|
|
1590
|
+
* See `Dataset.withAdvisoryLock`. Excludes every session on the
|
|
1591
|
+
* same schema, across processes. On a tx-bound instance the lock is
|
|
1592
|
+
* `pg_advisory_xact_lock` on the transaction's own connection, held until
|
|
1593
|
+
* it commits or rolls back: a session lock would need a second connection
|
|
1594
|
+
* beside the open transaction.
|
|
1595
|
+
*/
|
|
1596
|
+
withAdvisoryLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
|
|
1597
|
+
allocateShortId(type: string): Promise<number>;
|
|
1598
|
+
bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
|
|
1599
|
+
resolveShortId(type: string, shortId: number): Promise<string | null>;
|
|
1600
|
+
allocateShortIds(type: string, count: number): Promise<number[]>;
|
|
1601
|
+
bindShortIds(type: string, pairs: ReadonlyArray<{
|
|
1602
|
+
shortId: number;
|
|
1603
|
+
rowId: string;
|
|
1604
|
+
}>): Promise<void>;
|
|
1605
|
+
resolveShortIds(type: string, shortIds: readonly number[]): Promise<ReadonlyMap<number, string>>;
|
|
1606
|
+
patchRows(type: string, patches: ReadonlyArray<{
|
|
1607
|
+
id: Id;
|
|
1608
|
+
patch: Record<string, unknown>;
|
|
1609
|
+
}>, actor: ActorIdentity | null, now: Date): Promise<Array<Row | null>>;
|
|
1610
|
+
updateWhere(type: string, where: WhereClause, set: Record<string, unknown>, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
1611
|
+
deleteWhere(type: string, where: WhereClause, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
1612
|
+
getShortIdForRow(type: string, rowId: string): Promise<number | null>;
|
|
1613
|
+
forNamespace(namespace: string): Dataset;
|
|
1614
|
+
/**
|
|
1615
|
+
* See `Dataset.ensureTypeStorage`. Brings the type's table in line with its
|
|
1616
|
+
* declared fields (`ensureTypeTable`; a new field gets its column, or
|
|
1617
|
+
* `pending` under `newFields: 'pending'`), then reconciles its indexes on
|
|
1618
|
+
* it, and returns the fields that went `pending` in this call (F12). An
|
|
1619
|
+
* index reading a pending field's column waits, `pending`, until the column
|
|
1620
|
+
* exists. Index builds run CONCURRENTLY, outside any transaction, so a
|
|
1621
|
+
* tx-bound instance refuses. Logs each index it created, adopted or
|
|
1622
|
+
* swapped, and records each one left pending, building or failed for
|
|
1623
|
+
* `describeStorage` and `storageReport`.
|
|
1624
|
+
*/
|
|
1625
|
+
ensureTypeStorage(type: string, opts?: {
|
|
1626
|
+
indexes?: 'all' | 'unique' | 'nonUnique';
|
|
1627
|
+
signal?: AbortSignal;
|
|
1628
|
+
newFields?: 'column' | 'pending';
|
|
1629
|
+
}): Promise<{
|
|
1630
|
+
pending: string[];
|
|
1631
|
+
}>;
|
|
1632
|
+
/**
|
|
1633
|
+
* See `Dataset.promotePendingFields`. Store-wide; `[]` before the store is
|
|
1634
|
+
* migrated. Each field's
|
|
1635
|
+
* indexes are reconciled through its namespace's view of this dataset, so a
|
|
1636
|
+
* declared index waiting on the new column is built.
|
|
1637
|
+
*/
|
|
1638
|
+
promotePendingFields(opts: {
|
|
1639
|
+
lockTimeoutMs: number;
|
|
1640
|
+
batchRows: number;
|
|
1641
|
+
signal?: AbortSignal;
|
|
1642
|
+
/** Only this namespace's fields. */
|
|
1643
|
+
namespace?: string;
|
|
1644
|
+
retryConflicts?: boolean;
|
|
1645
|
+
noWriters?: boolean;
|
|
1646
|
+
}): Promise<PromotionEvent[]>;
|
|
1647
|
+
/** See `Dataset.poolStats`. Read on the root dataset; outside a transaction `#sql` is the pool. */
|
|
1648
|
+
poolStats(): PoolStats;
|
|
1649
|
+
/**
|
|
1650
|
+
* See `Dataset.fieldWarnings`. Store-wide; none before the store is migrated. Counts
|
|
1651
|
+
* only, since `/health` shows it unauthenticated: the named lines are in
|
|
1652
|
+
* `storageReport`, which is admin-gated.
|
|
1653
|
+
*/
|
|
1654
|
+
fieldWarnings(): Promise<string[]>;
|
|
1655
|
+
/**
|
|
1656
|
+
* The type's non-unique indexes the next build pass would build or swap,
|
|
1657
|
+
* each with the disk guard's estimate. Empty when the store or the type's
|
|
1658
|
+
* storage does not exist yet. Changes nothing.
|
|
1659
|
+
*/
|
|
1660
|
+
pendingIndexBuilds(type: string): Promise<Array<{
|
|
1661
|
+
name: string;
|
|
1662
|
+
estimateBytes: number;
|
|
1663
|
+
}>>;
|
|
1664
|
+
/**
|
|
1665
|
+
* See `Dataset.describeStorage`. Reads the catalog only, in a fixed number of
|
|
1666
|
+
* queries: the type's table, its indexes, and its `pending` and `orphaned`
|
|
1667
|
+
* fields, as the catalog records them.
|
|
1668
|
+
*/
|
|
1669
|
+
describeStorage(type: string): Promise<TypeStorageReport>;
|
|
1670
|
+
/**
|
|
1671
|
+
* See `Dataset.storageReport`. Spans every namespace of the database. Reads
|
|
1672
|
+
* the type tables and every index on them in one query each, so its cost
|
|
1673
|
+
* does not grow with the number of types.
|
|
1674
|
+
*/
|
|
1675
|
+
storageReport(opts: {
|
|
1676
|
+
partitionBudget: number;
|
|
1677
|
+
}): Promise<StorageReport>;
|
|
1678
|
+
/** See `Dataset.indexPlan`. */
|
|
1679
|
+
indexPlan(type: string, namespace: string): Promise<IndexPlan | undefined>;
|
|
1680
|
+
/**
|
|
1681
|
+
* See `Dataset.dropEngineIndex`. Checks and drops under the table's index
|
|
1682
|
+
* build lock, so a reconcile cannot rebuild or swap the index in between.
|
|
1683
|
+
* Ownership is the reconciler's marker and generated name on an index of
|
|
1684
|
+
* this type (`typeIndexesOf`); the wanted set is the reconciler's own
|
|
1685
|
+
* (`desiredIndexKeys`), so only a leftover or a retracted declaration goes.
|
|
1686
|
+
* Refuses with `IndexDropRefusedError`.
|
|
1687
|
+
*
|
|
1688
|
+
* The drop waits for every transaction holding a lock on the table, and pg
|
|
1689
|
+
* cannot see a cycle through a caller that waits on this call, so each wait
|
|
1690
|
+
* is bounded by `lockTimeoutMs` (default `DROP_LOCK_TIMEOUT_MS`).
|
|
1691
|
+
*/
|
|
1692
|
+
dropEngineIndex(type: string, name: string, opts?: {
|
|
1693
|
+
beforeDrop?: () => Promise<void>;
|
|
1694
|
+
lockTimeoutMs?: number;
|
|
1695
|
+
}): Promise<void>;
|
|
1696
|
+
/**
|
|
1697
|
+
* See `Dataset.dropNamespaceIndexes`. The engine-owned indexes on this
|
|
1698
|
+
* namespace's type tables, which a namespace drop empties but keeps. Unique
|
|
1699
|
+
* ones only when `opts.unique`.
|
|
1700
|
+
* Each table's under its index-build lock, CONCURRENTLY; the wait for that
|
|
1701
|
+
* lock and each lock wait of a drop are bounded by `lockTimeoutMs` (default
|
|
1702
|
+
* `DROP_LOCK_TIMEOUT_MS`), past which it throws `index_drop_timeout`.
|
|
1703
|
+
*/
|
|
1704
|
+
dropNamespaceIndexes(opts?: {
|
|
1705
|
+
unique?: boolean;
|
|
1706
|
+
lockTimeoutMs?: number;
|
|
1707
|
+
}): Promise<string[]>;
|
|
1708
|
+
/** See `Dataset.indexDeclarationOf`. */
|
|
1709
|
+
indexDeclarationOf(type: string, name: string): Promise<IndexDecl | undefined>;
|
|
1710
|
+
/**
|
|
1711
|
+
* See `Dataset.typeStats`. Spans every namespace of the database, in a fixed
|
|
1712
|
+
* number of queries: each type table's own statistics; `liveRows` is
|
|
1713
|
+
* `reltuples` (or `n_live_tup` before the first ANALYZE) and counts
|
|
1714
|
+
* tombstoned rows too.
|
|
1715
|
+
*/
|
|
1716
|
+
typeStats(): Promise<TypeStats[]>;
|
|
1717
|
+
/**
|
|
1718
|
+
* `fields` is the type's, which the caller looks up once however many rows it
|
|
1719
|
+
* builds. The row is decoded first; `requested`, a read's `fields`, then
|
|
1720
|
+
* trims the `$raw` entries `decodeRow` overlays, since the projection keeps
|
|
1721
|
+
* `$raw` whole.
|
|
1722
|
+
*/
|
|
1723
|
+
private materialize;
|
|
1724
|
+
private extractOriginalId;
|
|
1725
|
+
}
|
|
1726
|
+
//#endregion
|
|
1025
1727
|
//#region ../../packages/substrate-dataset-pg/src/testing.d.ts
|
|
1026
1728
|
/**
|
|
1027
1729
|
* Safety rails for pg integration tests. Shared by every package whose suites
|
|
@@ -1144,6 +1846,11 @@ export declare function publicLeftoverWarning(names: readonly string[], packageN
|
|
|
1144
1846
|
* Call from `globalSetup`, so forked workers inherit the rewritten URL.
|
|
1145
1847
|
*/
|
|
1146
1848
|
export declare function preparePgTestSchema(url: string | undefined, opts: SchemaIsolationOptions): Promise<string | undefined>;
|
|
1849
|
+
/**
|
|
1850
|
+
* A `createSchema` for `preparePgTestSchema` that drops and recreates the
|
|
1851
|
+
* schema, so every run builds its store from an empty database.
|
|
1852
|
+
*/
|
|
1853
|
+
export declare function recreatePgTestSchema(url: string, schema: string): Promise<void>;
|
|
1147
1854
|
//#endregion
|
|
1148
1855
|
//#region ../../packages/substrate-embedder/src/fake.d.ts
|
|
1149
1856
|
interface FakeEmbedderOptions {
|
|
@@ -1157,36 +1864,8 @@ export declare class FakeEmbedder implements Embedder {
|
|
|
1157
1864
|
embed(text: string): Promise<Float32Array>;
|
|
1158
1865
|
}
|
|
1159
1866
|
//#endregion
|
|
1160
|
-
//#region ../../packages/substrate-server-memory/src/memory-ws-connection.d.ts
|
|
1161
|
-
/**
|
|
1162
|
-
* @internal — thrown when sending on a closed in-memory WS pair. Treat as
|
|
1163
|
-
* package-private.
|
|
1164
|
-
*/
|
|
1165
|
-
export declare class WsClosedError extends Error {
|
|
1166
|
-
constructor();
|
|
1167
|
-
}
|
|
1168
|
-
type Frame = Buffer | Uint8Array | string;
|
|
1169
|
-
interface MemoryWsClient {
|
|
1170
|
-
send(frame: Frame): void;
|
|
1171
|
-
onMessage(cb: (frame: Buffer) => void): void;
|
|
1172
|
-
onClose(cb: (code?: number) => void): void;
|
|
1173
|
-
close(code?: number, reason?: string): void;
|
|
1174
|
-
readonly closed: boolean;
|
|
1175
|
-
}
|
|
1176
|
-
/**
|
|
1177
|
-
* @internal — paired in-memory WS endpoints used by `MemorySubstrateServer`
|
|
1178
|
-
* for inject-style WS testing. Treat as package-private.
|
|
1179
|
-
*/
|
|
1180
|
-
export declare function createMemoryWsPair(): {
|
|
1181
|
-
server: WsConnection;
|
|
1182
|
-
client: MemoryWsClient;
|
|
1183
|
-
};
|
|
1184
|
-
//#endregion
|
|
1185
1867
|
//#region ../../packages/substrate-server-memory/src/memory-server.d.ts
|
|
1186
1868
|
type ErrorHook = (err: Error, req?: SubstrateRequest) => void;
|
|
1187
|
-
export declare class UnknownWsPathError extends Error {
|
|
1188
|
-
constructor(path: string);
|
|
1189
|
-
}
|
|
1190
1869
|
/**
|
|
1191
1870
|
* @internal — thrown when `MemorySubstrateServer.start()` is called twice.
|
|
1192
1871
|
* Re-exported from the package index; treat as package-private.
|
|
@@ -1197,7 +1876,6 @@ export declare class AlreadyStartedError extends Error {
|
|
|
1197
1876
|
export declare class MemorySubstrateServer implements SubstrateServer {
|
|
1198
1877
|
#private;
|
|
1199
1878
|
route(method: HttpMethod, path: string, handler: HttpHandler): void;
|
|
1200
|
-
websocket(path: string, handler: WsHandler): void;
|
|
1201
1879
|
onError(hook: ErrorHook): void;
|
|
1202
1880
|
observeRequests(observer: RequestObserver): void;
|
|
1203
1881
|
observeInFlight(fn: (op: RuntimeOp, delta: 1 | -1) => void): void;
|
|
@@ -1215,7 +1893,6 @@ export declare class MemorySubstrateServer implements SubstrateServer {
|
|
|
1215
1893
|
name: string;
|
|
1216
1894
|
}): PluginRouter;
|
|
1217
1895
|
inject(req: Partial<SubstrateRequest>): Promise<SubstrateResponse>;
|
|
1218
|
-
connectWebsocket(path: string, headers?: Record<string, string>): MemoryWsClient;
|
|
1219
1896
|
}
|
|
1220
1897
|
//#endregion
|
|
1221
1898
|
//#region ../../packages/substrate-server-memory/src/route-matcher.d.ts
|
|
@@ -1242,4 +1919,4 @@ export declare class MemorySubstrateServer implements SubstrateServer {
|
|
|
1242
1919
|
*/
|
|
1243
1920
|
export declare function matchRoute(registered: string, actual: string): Record<string, string> | null;
|
|
1244
1921
|
//#endregion
|
|
1245
|
-
export type { AuthConfig, ComposeResult,
|
|
1922
|
+
export type { AuthConfig, ComposeResult, FieldDefLookup, IndexedListField, PgDatasetOptions, PgEdgesStoreOptions };
|