@mnmal-ai/substrate 1.0.0-alpha.9 → 1.0.0-beta.2
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 +32 -14
- package/dist/boot-store-DpnnxRpR.js +4086 -0
- package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-DnToJedN.d.ts} +2 -87
- package/dist/cli-COS16L1Z.js +3449 -0
- package/dist/client.browser.js +2507 -0
- package/dist/client.d.ts +222 -171
- package/dist/client.js +6 -7
- 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-CuCMwPpb.d.ts} +46 -4
- package/dist/{fake-DUVtKVSE.js → fake-DdXtb-m8.js} +0 -1
- package/dist/{index-D7mSOFlM.d.ts → index-BI4KqFiR.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/{plugin-DpncES1p.js → plugin-DWagHKxm.js} +78 -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 +3 -4
- package/dist/recall.d.ts +11 -12
- package/dist/recall.js +2 -3
- package/dist/{repl-DeKzfvNV.js → repl-C8ZgDrQ7.js} +52 -26
- package/dist/{row-SRhura12.d.ts → row-D0If4qif.d.ts} +91 -13
- package/dist/run-D-4sXpTu.js +2443 -0
- package/dist/{plugin-t2g2wX0b.d.ts → schema-aIkY8sR3.d.ts} +1293 -63
- package/dist/{script-C6DSa_Na.js → script-ByQ9pzhC.js} +54 -26
- package/dist/script-runner.js +78 -0
- package/dist/sdk.d.ts +236 -38
- package/dist/sdk.js +5 -110
- package/dist/semver-D_zdq0hi.js +17 -0
- package/dist/{src-BLgbLq2k.js → src-B_kHkbsr.js} +780 -330
- package/dist/{src-DjIuRjzF.js → src-C0ylwQFC.js} +10243 -4238
- package/dist/{src-C12EA0w9.js → src-D1PgjgUg.js} +179 -96
- package/dist/{src-DCy7Iy2l.js → src-Db3XI_pn.js} +900 -77
- package/dist/{row-DZ0Fnpc6.js → src-DmiUWOLp.js} +2 -1
- package/dist/src-DxD3iktO.js +8307 -0
- package/dist/{src-DiNTSaFk.js → src-FXO5JPyk.js} +686 -856
- package/dist/substrate-admin.js +17 -782
- package/dist/substrate.js +4 -5302
- package/dist/testing.d.ts +473 -96
- package/dist/testing.js +19 -165
- package/dist/{ws-C72iVS5T.d.ts → ws-DW8ng02H.d.ts} +4 -5
- package/package.json +26 -26
- package/dist/dataset-CqrqTYPz.js +0 -1535
- package/dist/pg-edges-store-KH_FQCxx.js +0 -381
- package/dist/schema-g4FQLr0V.d.ts +0 -433
- package/dist/src-BD27zeGF.js +0 -2339
package/dist/testing.d.ts
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
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, vt as TxScopeHandles, 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-aIkY8sR3.js";
|
|
2
|
+
import { a as WsResponseFrame, f as IdempotencyStore, l as SweepDeps, s as BridgeRegistry, u as SweepState } from "./ws-DW8ng02H.js";
|
|
5
3
|
import { t as Embedder } from "./types-8c0gtnd2.js";
|
|
6
4
|
import { Sql, TransactionSql } from "postgres";
|
|
7
5
|
//#region ../../packages/substrate-compose/src/auth.d.ts
|
|
@@ -76,6 +74,13 @@ export declare function signHs256(payload: Record<string, unknown>, secret: stri
|
|
|
76
74
|
kid?: string;
|
|
77
75
|
}): string;
|
|
78
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
|
|
79
84
|
//#region ../../packages/substrate-compose/src/_system/types.d.ts
|
|
80
85
|
/**
|
|
81
86
|
* Where the operator's agent DIRECTORY lives, so `POST /substrate/v1/_system/keys` can
|
|
@@ -188,6 +193,38 @@ interface RateLimiter {
|
|
|
188
193
|
dispose(): void;
|
|
189
194
|
}
|
|
190
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
|
|
191
228
|
//#region ../../packages/substrate-core/src/registry.d.ts
|
|
192
229
|
type TypeKey = string | {
|
|
193
230
|
readonly name: string;
|
|
@@ -233,6 +270,24 @@ interface EngineOptions {
|
|
|
233
270
|
* does no timing at all.
|
|
234
271
|
*/
|
|
235
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;
|
|
236
291
|
/**
|
|
237
292
|
* Idempotency dedup (§5.13). Absent → no dedup; `FrameEntry.idempotencyKey`
|
|
238
293
|
* is ignored on mutate (queries ignore it unconditionally). Present → the
|
|
@@ -281,10 +336,10 @@ interface EngineOptions {
|
|
|
281
336
|
* without the call site knowing which metric string to use.
|
|
282
337
|
*
|
|
283
338
|
* - `'cancel'` — explicit client-driven cancel (op: 'cancel') or direct handle use
|
|
284
|
-
* - `'
|
|
339
|
+
* - `'client_disconnect'` — client disconnected (response closed)
|
|
285
340
|
* - `'shutdown'` — server-initiated graceful shutdown (conn.onShutdown)
|
|
286
341
|
*/
|
|
287
|
-
type SubscriptionCancelReason = 'cancel' | '
|
|
342
|
+
type SubscriptionCancelReason = 'cancel' | 'client_disconnect' | 'shutdown';
|
|
288
343
|
interface SubscriptionHandle {
|
|
289
344
|
readonly __brand?: 'SubscriptionHandle';
|
|
290
345
|
readonly id: string;
|
|
@@ -302,8 +357,8 @@ interface SubscribeInput {
|
|
|
302
357
|
ctx: Partial<RequestContext>;
|
|
303
358
|
/**
|
|
304
359
|
* Frame sink. Sync-returning callbacks are still valid; the engine awaits
|
|
305
|
-
* whatever `onFrame` returns so back-pressure-aware transports (e.g.
|
|
306
|
-
*
|
|
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
|
|
307
362
|
* pending (unsettled) calls per subscription and tears the entry down when
|
|
308
363
|
* the count exceeds `EngineOptions.subscriptions.queueLimit` (§5.13).
|
|
309
364
|
*/
|
|
@@ -473,7 +528,7 @@ declare class Engine {
|
|
|
473
528
|
* caller's `probe` context so policies reading headers, `clientIp`, `meta`
|
|
474
529
|
* or `authEnabled` decide as they would in dispatch.
|
|
475
530
|
*/
|
|
476
|
-
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;
|
|
477
532
|
/**
|
|
478
533
|
* Refresh the cached schemas for every registered bridge. Callers invoke
|
|
479
534
|
* this at composition-root wire-up time to populate `federatedSchema()`'s
|
|
@@ -524,6 +579,17 @@ declare class Engine {
|
|
|
524
579
|
* fanout — see subscribe.ts for the full contract.
|
|
525
580
|
*/
|
|
526
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[];
|
|
527
593
|
/**
|
|
528
594
|
* Live count of active subscription entries. Delegates to the
|
|
529
595
|
* SubscribeSubsystem, which owns the authoritative map.
|
|
@@ -619,6 +685,8 @@ export declare class MemoryEdgesStore implements EdgesStore {
|
|
|
619
685
|
*/
|
|
620
686
|
private nextId;
|
|
621
687
|
write(input: EdgeWriteInput): Promise<Edge>;
|
|
688
|
+
writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
|
|
689
|
+
tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
|
|
622
690
|
tombstone(id: string, at?: Date): Promise<void>;
|
|
623
691
|
update(patch: EdgePatch): Promise<void>;
|
|
624
692
|
readNextBatch(cursorId: string | null, size: number): Promise<{
|
|
@@ -628,6 +696,7 @@ export declare class MemoryEdgesStore implements EdgesStore {
|
|
|
628
696
|
findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
|
|
629
697
|
findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
630
698
|
findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
|
|
699
|
+
findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
631
700
|
canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
|
|
632
701
|
findBlocked(): Promise<Edge[]>;
|
|
633
702
|
findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
|
|
@@ -734,11 +803,38 @@ interface MemoryDatasetOptions {
|
|
|
734
803
|
* instants, as the pg dataset's lookup does; without it they compare as text.
|
|
735
804
|
*/
|
|
736
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`), and
|
|
810
|
+
* its unique `indexes` refuse a colliding write with `unique_violation`.
|
|
811
|
+
*/
|
|
812
|
+
typeDefLookup?: (type: string, namespace: string) => {
|
|
813
|
+
ordering?: 'visible';
|
|
814
|
+
fields?: Record<string, FieldDef>;
|
|
815
|
+
indexes?: IndexDecl[];
|
|
816
|
+
} | undefined;
|
|
817
|
+
/**
|
|
818
|
+
* Internal: binding assignments one read's walks may try before refusing
|
|
819
|
+
* `walk_budget_exceeded`. Defaults to `WALK_EVALUATION_BUDGET`; tests lower it.
|
|
820
|
+
*/
|
|
821
|
+
walkBudget?: number;
|
|
822
|
+
/**
|
|
823
|
+
* Test-only: declare and answer the typed-edge-walk grammar. The memory
|
|
824
|
+
* dataset is the parity reference for the pg walk compiler, not a walk
|
|
825
|
+
* store; without this the engine refuses walks on it (`walks_unsupported_store`).
|
|
826
|
+
*/
|
|
827
|
+
walkReference?: boolean;
|
|
737
828
|
}
|
|
738
829
|
export declare class MemoryDataset implements Dataset {
|
|
739
830
|
#private;
|
|
740
831
|
readonly namespace: string;
|
|
741
832
|
readonly txScopeId: string;
|
|
833
|
+
private readonly typeDefLookup;
|
|
834
|
+
private readonly walkBudget;
|
|
835
|
+
private readonly walkReference;
|
|
836
|
+
/** Last seq assigned per visible-order type; never decreases, as pg's `visible_seqs`. */
|
|
837
|
+
private seqs;
|
|
742
838
|
readonly capabilities: FilterCapabilities;
|
|
743
839
|
/** See `Dataset.withAdvisoryLock`. Excludes holders on this instance. */
|
|
744
840
|
withAdvisoryLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
|
|
@@ -747,7 +843,23 @@ export declare class MemoryDataset implements Dataset {
|
|
|
747
843
|
constructor(options: MemoryDatasetOptions);
|
|
748
844
|
private bucket;
|
|
749
845
|
read(type: string, params: ReadParams): Promise<ReadResult>;
|
|
750
|
-
|
|
846
|
+
/**
|
|
847
|
+
* Walks over this namespace's live rows, for one read. Neighbours follow the
|
|
848
|
+
* row body's crossRef value (spec 2026-10-24-typed-edge-walks §1), indexed
|
|
849
|
+
* per (type, field) on first use.
|
|
850
|
+
*/
|
|
851
|
+
private walkContext;
|
|
852
|
+
write(type: string, rows: WriteRow[], options?: WriteOptions): Promise<WriteResult>;
|
|
853
|
+
/**
|
|
854
|
+
* Refuses `changed` (rows by id, as they would land) when it collides with
|
|
855
|
+
* another live row on a declared unique index, as pg's partial unique btree
|
|
856
|
+
* does: same `unique_violation`, index name and fields. A null or absent key
|
|
857
|
+
* value never collides (pg's NULLs are distinct; no index is NULLS NOT DISTINCT).
|
|
858
|
+
*/
|
|
859
|
+
private assertUnique;
|
|
860
|
+
private uniqueViolation;
|
|
861
|
+
/** The type's column fields, looked up once per call rather than per row. */
|
|
862
|
+
private columnFieldNames;
|
|
751
863
|
tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
752
864
|
purge(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
753
865
|
dropType(type: string): Promise<DropResult>;
|
|
@@ -780,6 +892,18 @@ export declare class MemoryDataset implements Dataset {
|
|
|
780
892
|
allocateShortId(type: string): Promise<number>;
|
|
781
893
|
bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
|
|
782
894
|
resolveShortId(type: string, shortId: number): Promise<string | null>;
|
|
895
|
+
allocateShortIds(type: string, count: number): Promise<number[]>;
|
|
896
|
+
bindShortIds(type: string, pairs: ReadonlyArray<{
|
|
897
|
+
shortId: number;
|
|
898
|
+
rowId: string;
|
|
899
|
+
}>): Promise<void>;
|
|
900
|
+
resolveShortIds(type: string, shortIds: readonly number[]): Promise<ReadonlyMap<number, string>>;
|
|
901
|
+
patchRows(type: string, patches: ReadonlyArray<{
|
|
902
|
+
id: Id;
|
|
903
|
+
patch: Record<string, unknown>;
|
|
904
|
+
}>, actor: ActorIdentity | null, now: Date): Promise<Array<Row | null>>;
|
|
905
|
+
updateWhere(type: string, where: WhereClause, set: Record<string, unknown>, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
906
|
+
deleteWhere(type: string, where: WhereClause, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
783
907
|
getShortIdForRow(type: string, rowId: string): Promise<number | null>;
|
|
784
908
|
forNamespace(namespace: string): Dataset;
|
|
785
909
|
}
|
|
@@ -892,7 +1016,7 @@ interface ComposeOpts {
|
|
|
892
1016
|
bridges?: BridgeRegistry;
|
|
893
1017
|
/**
|
|
894
1018
|
* JWT auth config (§5.12). When supplied, route handlers for
|
|
895
|
-
* `/substrate/v1/query`, `/substrate/v1/mutate`, and
|
|
1019
|
+
* `/substrate/v1/query`, `/substrate/v1/mutate`, `/substrate/v1/subscribe` and `/substrate/v1/stream` require a
|
|
896
1020
|
* valid `Authorization: Bearer <token>` header; missing / invalid tokens
|
|
897
1021
|
* return 401 with `{ code: 'unauthorized' }`. When absent, every request
|
|
898
1022
|
* passes through unauthenticated, attributed to `systemActor`.
|
|
@@ -929,7 +1053,7 @@ interface ComposeOpts {
|
|
|
929
1053
|
* §5.13 subscription back-pressure override. Threads straight into
|
|
930
1054
|
* `EngineOptions.subscriptions`. Default (absent): engine default
|
|
931
1055
|
* queueLimit of 256. Conformance tests set a tiny limit to trigger the
|
|
932
|
-
* teardown contract deterministically (docs/
|
|
1056
|
+
* teardown contract deterministically (docs/stream-contract.md).
|
|
933
1057
|
*/
|
|
934
1058
|
subscriptions?: {
|
|
935
1059
|
queueLimit?: number;
|
|
@@ -955,6 +1079,12 @@ interface ComposeOpts {
|
|
|
955
1079
|
defaultLimit: number;
|
|
956
1080
|
maxLimit: number;
|
|
957
1081
|
};
|
|
1082
|
+
/**
|
|
1083
|
+
* Caps on `updateMany<T>` / `deleteMany<T>`: the most rows one filter may
|
|
1084
|
+
* match (more is refused `filter_too_broad`), and the most ids a result
|
|
1085
|
+
* returns. Defaults to 10000 and 1000.
|
|
1086
|
+
*/
|
|
1087
|
+
filterWriteLimits?: FilterWriteLimits;
|
|
958
1088
|
/**
|
|
959
1089
|
* Opt-in periodic re-prime interval (ms) for the
|
|
960
1090
|
* `KeyRegistry` public-key cache. Bounds cross-instance revocation
|
|
@@ -966,15 +1096,11 @@ interface ComposeOpts {
|
|
|
966
1096
|
*/
|
|
967
1097
|
keyReprimeIntervalMs?: number;
|
|
968
1098
|
/**
|
|
969
|
-
*
|
|
970
|
-
*
|
|
971
|
-
*
|
|
972
|
-
* authenticate on this signature alone, the dev default is a published
|
|
973
|
-
* constant, and `''` / `' '` are HMAC keys Node accepts. Omit it only with
|
|
974
|
-
* auth disabled, where `gate` is the identity function and there is nothing
|
|
975
|
-
* to bypass. Trimmed before use.
|
|
1099
|
+
* Seals pagination cursors under a row-filter policy. Every process sharing
|
|
1100
|
+
* it opens the same cursors; without it the key is per process, so a sealed
|
|
1101
|
+
* cursor stops opening after a restart or on another replica. Trimmed.
|
|
976
1102
|
*/
|
|
977
|
-
|
|
1103
|
+
cursorSealSecret?: string;
|
|
978
1104
|
/**
|
|
979
1105
|
* Effective value + provenance for every defaulted knob, as the caller's
|
|
980
1106
|
* env parser resolved them. When present, compose mounts
|
|
@@ -985,6 +1111,28 @@ interface ComposeOpts {
|
|
|
985
1111
|
* second reading of the environment. Omitted by programmatic embedders.
|
|
986
1112
|
*/
|
|
987
1113
|
configReport?: ConfigReport;
|
|
1114
|
+
/** Reported beside `configReport`; ignored without it. */
|
|
1115
|
+
storageReport?: () => Promise<StorageReport>;
|
|
1116
|
+
/**
|
|
1117
|
+
* The index advisor. Every `intervalMs` (`SUBSTRATE_ADVISOR_INTERVAL_MS`)
|
|
1118
|
+
* it turns the reads the engine recorded and the store's statistics into
|
|
1119
|
+
* `_system/IndexRecommendation` rows. Omitted or `intervalMs: 0`: off, and
|
|
1120
|
+
* no read is recorded. `storeProfile` seeds `_system/StoreProfile` when it
|
|
1121
|
+
* has no row yet.
|
|
1122
|
+
*/
|
|
1123
|
+
advisor?: {
|
|
1124
|
+
intervalMs: number;
|
|
1125
|
+
storeProfile?: StoreProfileName;
|
|
1126
|
+
writeHeavy?: boolean;
|
|
1127
|
+
};
|
|
1128
|
+
/**
|
|
1129
|
+
* The promotion sweep, every `intervalMs` (`SUBSTRATE_PROMOTE_INTERVAL_MS`),
|
|
1130
|
+
* over `dataset`'s pending fields. Omitted or `intervalMs: 0`: no timer;
|
|
1131
|
+
* `POST /substrate/v1/_system/promote-fields` runs it either way.
|
|
1132
|
+
*/
|
|
1133
|
+
promoteFields?: {
|
|
1134
|
+
intervalMs: number;
|
|
1135
|
+
};
|
|
988
1136
|
}
|
|
989
1137
|
interface ComposeResult {
|
|
990
1138
|
engine: Engine;
|
|
@@ -1007,6 +1155,12 @@ interface ComposeResult {
|
|
|
1007
1155
|
* loop in `main.ts`.
|
|
1008
1156
|
*/
|
|
1009
1157
|
runSweepNow: () => Promise<SweepState>;
|
|
1158
|
+
/** Run one index-advisor pass now, for tests; null while the advisor is off. */
|
|
1159
|
+
runAdvisorNow: (() => Promise<{
|
|
1160
|
+
upserted: number;
|
|
1161
|
+
}>) | null;
|
|
1162
|
+
/** Run one promotion sweep now, as the admin route does. */
|
|
1163
|
+
runPromoteFieldsNow: () => Promise<PromotionEvent[]>;
|
|
1010
1164
|
/**
|
|
1011
1165
|
* Non-null when any coordinator plugin contributed a `schedule`. The
|
|
1012
1166
|
* composition root constructs the scheduler, registers every plugin's
|
|
@@ -1023,6 +1177,83 @@ interface ComposeResult {
|
|
|
1023
1177
|
}
|
|
1024
1178
|
export declare function compose(opts: ComposeOpts): Promise<ComposeResult>;
|
|
1025
1179
|
//#endregion
|
|
1180
|
+
//#region ../../packages/substrate-dataset-pg/src/tx-scope.d.ts
|
|
1181
|
+
type PgHandle = Sql | TransactionSql;
|
|
1182
|
+
//#endregion
|
|
1183
|
+
//#region ../../packages/substrate-dataset-pg/src/type-table.d.ts
|
|
1184
|
+
type ColumnKind = 'text' | 'enum' | 'number' | 'int16' | 'int32' | 'int64' | 'date' | 'boolean' | 'crossRef';
|
|
1185
|
+
interface TypedColumn {
|
|
1186
|
+
field: string;
|
|
1187
|
+
column: string;
|
|
1188
|
+
kind: ColumnKind;
|
|
1189
|
+
state: 'column' | 'promoting' | 'orphaned';
|
|
1190
|
+
vocab?: readonly string[];
|
|
1191
|
+
}
|
|
1192
|
+
interface TypeTable {
|
|
1193
|
+
namespace: string;
|
|
1194
|
+
type: string;
|
|
1195
|
+
/** The table, as a quoted identifier. */
|
|
1196
|
+
from: string;
|
|
1197
|
+
/** The jsonb column holding every field without a column of its own. */
|
|
1198
|
+
jsonb: 'extra';
|
|
1199
|
+
column(field: string): TypedColumn | undefined;
|
|
1200
|
+
columns(): readonly TypedColumn[];
|
|
1201
|
+
/** Declared fields whose values live in `extra` until they get a column. */
|
|
1202
|
+
pending: readonly string[];
|
|
1203
|
+
orphaned: readonly string[];
|
|
1204
|
+
/**
|
|
1205
|
+
* The catalog version this descriptor was loaded at (bigint text). Every
|
|
1206
|
+
* write checks it in its own statement (`guardCte`), so one built from a
|
|
1207
|
+
* stale descriptor writes nothing and is rebuilt.
|
|
1208
|
+
*/
|
|
1209
|
+
version: string;
|
|
1210
|
+
}
|
|
1211
|
+
/**
|
|
1212
|
+
* A pool's type-table descriptors. A
|
|
1213
|
+
* `substrate_catalog` notification (sent by `ensureTypeTable` on any change,
|
|
1214
|
+
* delivered at commit) drops its type's entry, and a (re)connect of the
|
|
1215
|
+
* listener drops them all, since notifications may have been missed.
|
|
1216
|
+
*/
|
|
1217
|
+
interface TableCache {
|
|
1218
|
+
/** The pool, which LISTENs on a connection of its own. */
|
|
1219
|
+
sql: PgHandle;
|
|
1220
|
+
/** `null` is a cached miss: the type has no table yet. */
|
|
1221
|
+
tables: Map<string, TypeTable | null>;
|
|
1222
|
+
/** Bumped on each drop; a load notes it at its start (see {@link mayCache}). */
|
|
1223
|
+
gen: number;
|
|
1224
|
+
/** Each key's last drop's `gen`, so a load is refused only for a drop of its own key. */
|
|
1225
|
+
dropped: Map<string, number>;
|
|
1226
|
+
/** The last full clear's `gen`. */
|
|
1227
|
+
cleared: number;
|
|
1228
|
+
/** True once listening; false when LISTEN failed, and then nothing is cached. */
|
|
1229
|
+
listening?: Promise<boolean>;
|
|
1230
|
+
/** After a failed LISTEN, when the next call may try again. */
|
|
1231
|
+
listenRetryAt?: number;
|
|
1232
|
+
/** Only `true` is kept: the migration can be applied while this process runs, never unapplied. */
|
|
1233
|
+
uuidCheck?: true;
|
|
1234
|
+
}
|
|
1235
|
+
//#endregion
|
|
1236
|
+
//#region ../../packages/substrate-dataset-pg/src/disk-guard.d.ts
|
|
1237
|
+
/**
|
|
1238
|
+
* Refuses a background index build that would leave less than a margin of
|
|
1239
|
+
* free space on the database volume. Postgres cannot report filesystem space,
|
|
1240
|
+
* so the volume is a local path the operator names; with none, every build is
|
|
1241
|
+
* allowed and `path` is undefined so the storage report can say checks are off.
|
|
1242
|
+
*/
|
|
1243
|
+
interface DiskGuard {
|
|
1244
|
+
readonly path: string | undefined;
|
|
1245
|
+
check(estimateBytes: number): Promise<{
|
|
1246
|
+
ok: true;
|
|
1247
|
+
} | {
|
|
1248
|
+
ok: false;
|
|
1249
|
+
freeBytes: number;
|
|
1250
|
+
needBytes: number;
|
|
1251
|
+
}>;
|
|
1252
|
+
}
|
|
1253
|
+
//#endregion
|
|
1254
|
+
//#region ../../packages/substrate-dataset-pg/src/layout.d.ts
|
|
1255
|
+
type StorageLayout = 'tables';
|
|
1256
|
+
//#endregion
|
|
1026
1257
|
//#region ../../packages/substrate-dataset-pg/src/migrate.d.ts
|
|
1027
1258
|
/**
|
|
1028
1259
|
* Public migration shape accepted by the runner. Either supply both
|
|
@@ -1071,7 +1302,9 @@ interface IndexedListField {
|
|
|
1071
1302
|
}
|
|
1072
1303
|
/**
|
|
1073
1304
|
* Derives the tracked, idempotent CONCURRENTLY GIN migration for one indexed
|
|
1074
|
-
* field
|
|
1305
|
+
* field, as the legacy layout built it on `rows`. The version key uses the raw
|
|
1306
|
+
* ns/type/field. `runDerivedMigrations` skips these: each type table's GIN
|
|
1307
|
+
* indexes are its own, built by `reconcileTypeIndexes`.
|
|
1075
1308
|
*/
|
|
1076
1309
|
export declare function deriveListIndexMigration(f: IndexedListField): MigrationInput;
|
|
1077
1310
|
/**
|
|
@@ -1079,11 +1312,11 @@ export declare function deriveListIndexMigration(f: IndexedListField): Migration
|
|
|
1079
1312
|
* advisory-locked machinery as the static list. Called after plugins load,
|
|
1080
1313
|
* since `runMigrations` has no field-def knowledge. Idempotent: applied
|
|
1081
1314
|
* versions are skipped.
|
|
1315
|
+
*
|
|
1316
|
+
* The list/json GIN migrations are skipped: there is no `rows` to aim them
|
|
1317
|
+
* at, and each type table's indexes are its own (`reconcileTypeIndexes`).
|
|
1082
1318
|
*/
|
|
1083
|
-
export declare function runDerivedMigrations(sql: Sql,
|
|
1084
|
-
//#endregion
|
|
1085
|
-
//#region ../../packages/substrate-dataset-pg/src/tx-scope.d.ts
|
|
1086
|
-
type PgHandle = Sql | TransactionSql;
|
|
1319
|
+
export declare function runDerivedMigrations(sql: Sql, all: ReadonlyArray<MigrationInput>): Promise<void>;
|
|
1087
1320
|
//#endregion
|
|
1088
1321
|
//#region ../../packages/substrate-dataset-pg/src/pg-edges-store.d.ts
|
|
1089
1322
|
interface PgEdgesStoreOptions {
|
|
@@ -1112,6 +1345,8 @@ export declare class PgEdgesStore implements EdgesStore {
|
|
|
1112
1345
|
readonly txScopeId: string;
|
|
1113
1346
|
constructor(options: PgEdgesStoreOptions | InternalPgEdgesStoreOptions);
|
|
1114
1347
|
write(input: EdgeWriteInput): Promise<Edge>;
|
|
1348
|
+
writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
|
|
1349
|
+
tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
|
|
1115
1350
|
tombstone(id: string, at?: Date): Promise<void>;
|
|
1116
1351
|
/**
|
|
1117
1352
|
* Hard-deletes tombstoned edges whose `deleted_at` is older than
|
|
@@ -1129,6 +1364,7 @@ export declare class PgEdgesStore implements EdgesStore {
|
|
|
1129
1364
|
}>;
|
|
1130
1365
|
findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
|
|
1131
1366
|
findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
1367
|
+
findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
1132
1368
|
findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
|
|
1133
1369
|
findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
|
|
1134
1370
|
findEdgesTouchingType(namespace: string, type: string, limit: number): Promise<Edge[]>;
|
|
@@ -1163,20 +1399,6 @@ export declare class PgEdgesStore implements EdgesStore {
|
|
|
1163
1399
|
_enlistInTx(txSql: PgHandle): PgEdgesStore;
|
|
1164
1400
|
}
|
|
1165
1401
|
//#endregion
|
|
1166
|
-
//#region ../../packages/substrate-dataset-pg/src/pg-sql/primitives.d.ts
|
|
1167
|
-
/**
|
|
1168
|
-
* A body key mirrored into a dedicated column on `rows`, so filters and
|
|
1169
|
-
* sorts on it hit an index instead of extracting from JSONB.
|
|
1170
|
-
*
|
|
1171
|
-
* `column` is a BARE column name, not a qualified `r.<col>` fragment: taking a
|
|
1172
|
-
* fragment from a caller would put caller text into `sql.unsafe`.
|
|
1173
|
-
*/
|
|
1174
|
-
interface PromotedBodyColumn {
|
|
1175
|
-
column: string;
|
|
1176
|
-
kind: 'boolean' | 'text';
|
|
1177
|
-
}
|
|
1178
|
-
type PromotedBodyColumnMap = Readonly<Record<string, PromotedBodyColumn>>;
|
|
1179
|
-
//#endregion
|
|
1180
1402
|
//#region ../../packages/substrate-dataset-pg/src/pg-dataset.d.ts
|
|
1181
1403
|
/**
|
|
1182
1404
|
* Returns the declared FieldDef for a type's field, or undefined when unknown
|
|
@@ -1185,6 +1407,18 @@ type PromotedBodyColumnMap = Readonly<Record<string, PromotedBodyColumn>>;
|
|
|
1185
1407
|
* `resolveBodyOrderByCast`.
|
|
1186
1408
|
*/
|
|
1187
1409
|
type FieldDefLookup = (type: string, field: string) => FieldDef | undefined;
|
|
1410
|
+
/**
|
|
1411
|
+
* A type's declared fields and indexes, or undefined when the type is unknown.
|
|
1412
|
+
* Called with the asking dataset's namespace, so a `forNamespace` clone that
|
|
1413
|
+
* inherits the lookup resolves its own types.
|
|
1414
|
+
*/
|
|
1415
|
+
type TypeDefLookup = (type: string, namespace: string) => {
|
|
1416
|
+
fields: Record<string, FieldDef>;
|
|
1417
|
+
indexes?: IndexDecl[];
|
|
1418
|
+
orderedBy?: OrderedBy;
|
|
1419
|
+
ordering?: 'visible';
|
|
1420
|
+
expectedSize?: 'small' | 'large';
|
|
1421
|
+
} | undefined;
|
|
1188
1422
|
interface PgDatasetOptions {
|
|
1189
1423
|
namespace: string;
|
|
1190
1424
|
sql: Sql;
|
|
@@ -1210,23 +1444,23 @@ interface PgDatasetOptions {
|
|
|
1210
1444
|
*/
|
|
1211
1445
|
fieldDefLookup?: FieldDefLookup;
|
|
1212
1446
|
/**
|
|
1213
|
-
*
|
|
1214
|
-
*
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
*
|
|
1219
|
-
*
|
|
1220
|
-
*
|
|
1221
|
-
*
|
|
1222
|
-
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
*
|
|
1226
|
-
*
|
|
1227
|
-
*
|
|
1228
|
-
*/
|
|
1229
|
-
|
|
1447
|
+
* The namespace's type definitions, which `ensureTypeStorage` builds the
|
|
1448
|
+
* type's indexes from. Without it only the engine's own indexes are built.
|
|
1449
|
+
*/
|
|
1450
|
+
typeDefLookup?: TypeDefLookup;
|
|
1451
|
+
/**
|
|
1452
|
+
* Checked before each non-unique index build `ensureTypeStorage` runs; a
|
|
1453
|
+
* refused build stays `pending` (`insufficient_disk`) until a later pass.
|
|
1454
|
+
* Without one nothing is checked. With one that has no path, nothing is
|
|
1455
|
+
* checked either, and `storageReport` says so.
|
|
1456
|
+
*/
|
|
1457
|
+
diskGuard?: DiskGuard;
|
|
1458
|
+
/**
|
|
1459
|
+
* The statement timeout a walk read runs under, in ms (default
|
|
1460
|
+
* `WALK_STATEMENT_TIMEOUT_MS`). A read it cancels is refused as
|
|
1461
|
+
* `query_timeout`.
|
|
1462
|
+
*/
|
|
1463
|
+
statementTimeoutMs?: number;
|
|
1230
1464
|
}
|
|
1231
1465
|
interface InternalPgSubstrateDatasetOptions {
|
|
1232
1466
|
namespace: string;
|
|
@@ -1239,8 +1473,34 @@ interface InternalPgSubstrateDatasetOptions {
|
|
|
1239
1473
|
txScopeId?: string;
|
|
1240
1474
|
edgesStore?: PgEdgesStore;
|
|
1241
1475
|
fieldDefLookup?: FieldDefLookup;
|
|
1242
|
-
/**
|
|
1243
|
-
|
|
1476
|
+
/** Shared with the instance this one was derived from. */
|
|
1477
|
+
layoutCache?: LayoutCache;
|
|
1478
|
+
typeDefLookup?: TypeDefLookup;
|
|
1479
|
+
diskGuard?: DiskGuard;
|
|
1480
|
+
statementTimeoutMs?: number;
|
|
1481
|
+
/** The pool's type-table cache, shared with the instance this one was derived from. */
|
|
1482
|
+
tableCache?: TableCache;
|
|
1483
|
+
/** The enclosing transaction's tables, which enter `tableCache` on commit only. */
|
|
1484
|
+
txTables?: TxTables;
|
|
1485
|
+
}
|
|
1486
|
+
/**
|
|
1487
|
+
* The tables a transaction loaded or created, each with the cache generation
|
|
1488
|
+
* it was loaded at. They enter the pool's cache when the transaction commits,
|
|
1489
|
+
* so a rolled-back CREATE or ALTER is never cached (F18).
|
|
1490
|
+
*/
|
|
1491
|
+
/**
|
|
1492
|
+
* A transaction's descriptors. `snapshot`: loaded for a non-READ COMMITTED
|
|
1493
|
+
* transaction's own snapshot (`null`: no table there), which never reaches
|
|
1494
|
+
* the pool's cache.
|
|
1495
|
+
*/
|
|
1496
|
+
type TxTables = Map<string, {
|
|
1497
|
+
table: TypeTable | null;
|
|
1498
|
+
gen: number;
|
|
1499
|
+
snapshot?: true;
|
|
1500
|
+
}>;
|
|
1501
|
+
/** The store's layout once migrated, shared by an instance and every clone of it. */
|
|
1502
|
+
interface LayoutCache {
|
|
1503
|
+
layout?: StorageLayout;
|
|
1244
1504
|
}
|
|
1245
1505
|
export declare class PgDataset implements Dataset {
|
|
1246
1506
|
#private;
|
|
@@ -1252,20 +1512,40 @@ export declare class PgDataset implements Dataset {
|
|
|
1252
1512
|
* Reads rows of `type` per the §5.2 filter contract (where / orderBy /
|
|
1253
1513
|
* cursor / limit). Every value is bound through a parameterised slot.
|
|
1254
1514
|
*
|
|
1255
|
-
*
|
|
1256
|
-
*
|
|
1515
|
+
* The walk grammar (spec 2026-10-24-typed-edge-walks §3) runs in a
|
|
1516
|
+
* transaction under a `SET LOCAL` statement timeout, since pg has no walk
|
|
1517
|
+
* evaluation budget. Other reads are unchanged.
|
|
1257
1518
|
*/
|
|
1258
1519
|
read(type: string, params: ReadParams): Promise<ReadResult>;
|
|
1259
|
-
|
|
1520
|
+
/**
|
|
1521
|
+
* Upsert `rows`. A row without an `id` gets one from the database's
|
|
1522
|
+
* `uuidv7()`, returned in `ids` in input order. Limits of a v7 id: it is
|
|
1523
|
+
* never a happened-before signal; ids sort in creation order only within one
|
|
1524
|
+
* connection (across connections within a millisecond, and for
|
|
1525
|
+
* client-supplied ids, order is arbitrary); it reveals its creation time;
|
|
1526
|
+
* and deciding who won (last-writer-wins, `conditionalUpdate`) uses the
|
|
1527
|
+
* database's transaction time or a per-row version, never the id.
|
|
1528
|
+
*
|
|
1529
|
+
* A supplied id repeated in one batch: under `insertOnly` the first
|
|
1530
|
+
* occurrence lands and the rest are skipped; otherwise the batch is refused.
|
|
1531
|
+
*
|
|
1532
|
+
* On an `ordering: 'visible'` type each inserted row gets the next `seq`,
|
|
1533
|
+
* consecutive in input order, under a per-type transaction lock held until
|
|
1534
|
+
* commit, so seq order is commit order. A row that already exists keeps its
|
|
1535
|
+
* seq, and one `insertOnly` skips gets none.
|
|
1536
|
+
*/
|
|
1537
|
+
write(type: string, rows: WriteRow[], options?: WriteOptions): Promise<WriteResult>;
|
|
1260
1538
|
tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
1539
|
+
/** On a type table, `deleted` also leaves `row_ids`, and `short_ids` cascade from there. */
|
|
1261
1540
|
purge(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
1262
1541
|
/**
|
|
1263
1542
|
* Hard-deletes tombstoned rows whose `deleted_at` is older than `olderThan`,
|
|
1264
1543
|
* across ALL namespaces (the table is substrate-shared). Called by the sweep
|
|
1265
1544
|
* loop. Returns the number of rows deleted.
|
|
1266
1545
|
*
|
|
1267
|
-
*
|
|
1268
|
-
*
|
|
1546
|
+
* Each type table is swept in one pass, a window of {@link purgeBatch} ids
|
|
1547
|
+
* per statement in id order, and a swept row leaves `row_ids` in the same
|
|
1548
|
+
* statement, its short id cascading.
|
|
1269
1549
|
*/
|
|
1270
1550
|
purgeTombstonedRows(opts: {
|
|
1271
1551
|
olderThan: Date;
|
|
@@ -1276,7 +1556,8 @@ export declare class PgDataset implements Dataset {
|
|
|
1276
1556
|
* Hard-delete every row for `type` in this namespace, including tombstoned
|
|
1277
1557
|
* rows (`deleted_at IS NOT NULL`). Short-id mappings for that type are
|
|
1278
1558
|
* removed in the same logical operation. Both deletes run through `this.#sql`
|
|
1279
|
-
* so they participate in any surrounding `withTransaction` boundary.
|
|
1559
|
+
* so they participate in any surrounding `withTransaction` boundary. A type
|
|
1560
|
+
* table is emptied, not dropped.
|
|
1280
1561
|
*/
|
|
1281
1562
|
dropType(type: string): Promise<DropResult>;
|
|
1282
1563
|
/**
|
|
@@ -1317,7 +1598,7 @@ export declare class PgDataset implements Dataset {
|
|
|
1317
1598
|
withScopedTransaction<T>(namespaces: ReadonlyArray<string>, fn: (handles: TxScopeHandles) => Promise<T>): Promise<T>;
|
|
1318
1599
|
/**
|
|
1319
1600
|
* See `Dataset.withAdvisoryLock`. Excludes every session on the
|
|
1320
|
-
*
|
|
1601
|
+
* same schema, across processes. On a tx-bound instance the lock is
|
|
1321
1602
|
* `pg_advisory_xact_lock` on the transaction's own connection, held until
|
|
1322
1603
|
* it commits or rolls back: a session lock would need a second connection
|
|
1323
1604
|
* beside the open transaction.
|
|
@@ -1326,8 +1607,129 @@ export declare class PgDataset implements Dataset {
|
|
|
1326
1607
|
allocateShortId(type: string): Promise<number>;
|
|
1327
1608
|
bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
|
|
1328
1609
|
resolveShortId(type: string, shortId: number): Promise<string | null>;
|
|
1610
|
+
allocateShortIds(type: string, count: number): Promise<number[]>;
|
|
1611
|
+
bindShortIds(type: string, pairs: ReadonlyArray<{
|
|
1612
|
+
shortId: number;
|
|
1613
|
+
rowId: string;
|
|
1614
|
+
}>): Promise<void>;
|
|
1615
|
+
resolveShortIds(type: string, shortIds: readonly number[]): Promise<ReadonlyMap<number, string>>;
|
|
1616
|
+
patchRows(type: string, patches: ReadonlyArray<{
|
|
1617
|
+
id: Id;
|
|
1618
|
+
patch: Record<string, unknown>;
|
|
1619
|
+
}>, actor: ActorIdentity | null, now: Date): Promise<Array<Row | null>>;
|
|
1620
|
+
updateWhere(type: string, where: WhereClause, set: Record<string, unknown>, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
1621
|
+
deleteWhere(type: string, where: WhereClause, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
1329
1622
|
getShortIdForRow(type: string, rowId: string): Promise<number | null>;
|
|
1330
1623
|
forNamespace(namespace: string): Dataset;
|
|
1624
|
+
/**
|
|
1625
|
+
* See `Dataset.ensureTypeStorage`. Brings the type's table in line with its
|
|
1626
|
+
* declared fields (`ensureTypeTable`; a new field gets its column, or
|
|
1627
|
+
* `pending` under `newFields: 'pending'`), then reconciles its indexes on
|
|
1628
|
+
* it, and returns the fields that went `pending` in this call (F12). An
|
|
1629
|
+
* index reading a pending field's column waits, `pending`, until the column
|
|
1630
|
+
* exists. Index builds run CONCURRENTLY, outside any transaction, so a
|
|
1631
|
+
* tx-bound instance refuses. Logs each index it created, adopted or
|
|
1632
|
+
* swapped, and records each one left pending, building or failed for
|
|
1633
|
+
* `describeStorage` and `storageReport`.
|
|
1634
|
+
*/
|
|
1635
|
+
ensureTypeStorage(type: string, opts?: {
|
|
1636
|
+
indexes?: 'all' | 'unique' | 'nonUnique';
|
|
1637
|
+
signal?: AbortSignal;
|
|
1638
|
+
newFields?: 'column' | 'pending';
|
|
1639
|
+
}): Promise<{
|
|
1640
|
+
pending: string[];
|
|
1641
|
+
}>;
|
|
1642
|
+
/**
|
|
1643
|
+
* See `Dataset.promotePendingFields`. Store-wide; `[]` before the store is
|
|
1644
|
+
* migrated. Each field's
|
|
1645
|
+
* indexes are reconciled through its namespace's view of this dataset, so a
|
|
1646
|
+
* declared index waiting on the new column is built.
|
|
1647
|
+
*/
|
|
1648
|
+
promotePendingFields(opts: {
|
|
1649
|
+
lockTimeoutMs: number;
|
|
1650
|
+
batchRows: number;
|
|
1651
|
+
signal?: AbortSignal;
|
|
1652
|
+
/** Only this namespace's fields. */
|
|
1653
|
+
namespace?: string;
|
|
1654
|
+
retryConflicts?: boolean;
|
|
1655
|
+
noWriters?: boolean;
|
|
1656
|
+
}): Promise<PromotionEvent[]>;
|
|
1657
|
+
/** See `Dataset.poolStats`. Read on the root dataset; outside a transaction `#sql` is the pool. */
|
|
1658
|
+
poolStats(): PoolStats;
|
|
1659
|
+
/**
|
|
1660
|
+
* See `Dataset.fieldWarnings`. Store-wide; none before the store is migrated. Counts
|
|
1661
|
+
* only, since `/health` shows it unauthenticated: the named lines are in
|
|
1662
|
+
* `storageReport`, which is admin-gated.
|
|
1663
|
+
*/
|
|
1664
|
+
fieldWarnings(): Promise<string[]>;
|
|
1665
|
+
/**
|
|
1666
|
+
* The type's non-unique indexes the next build pass would build or swap,
|
|
1667
|
+
* each with the disk guard's estimate. Empty when the store or the type's
|
|
1668
|
+
* storage does not exist yet. Changes nothing.
|
|
1669
|
+
*/
|
|
1670
|
+
pendingIndexBuilds(type: string): Promise<Array<{
|
|
1671
|
+
name: string;
|
|
1672
|
+
estimateBytes: number;
|
|
1673
|
+
}>>;
|
|
1674
|
+
/**
|
|
1675
|
+
* See `Dataset.describeStorage`. Reads the catalog only, in a fixed number of
|
|
1676
|
+
* queries: the type's table, its indexes, and its `pending` and `orphaned`
|
|
1677
|
+
* fields, as the catalog records them.
|
|
1678
|
+
*/
|
|
1679
|
+
describeStorage(type: string): Promise<TypeStorageReport>;
|
|
1680
|
+
/**
|
|
1681
|
+
* See `Dataset.storageReport`. Spans every namespace of the database. Reads
|
|
1682
|
+
* the type tables and every index on them in one query each, so its cost
|
|
1683
|
+
* does not grow with the number of types.
|
|
1684
|
+
*/
|
|
1685
|
+
storageReport(opts: {
|
|
1686
|
+
partitionBudget: number;
|
|
1687
|
+
}): Promise<StorageReport>;
|
|
1688
|
+
/** See `Dataset.indexPlan`. */
|
|
1689
|
+
indexPlan(type: string, namespace: string): Promise<IndexPlan | undefined>;
|
|
1690
|
+
/**
|
|
1691
|
+
* See `Dataset.dropEngineIndex`. Checks and drops under the table's index
|
|
1692
|
+
* build lock, so a reconcile cannot rebuild or swap the index in between.
|
|
1693
|
+
* Ownership is the reconciler's marker and generated name on an index of
|
|
1694
|
+
* this type (`typeIndexesOf`); the wanted set is the reconciler's own
|
|
1695
|
+
* (`desiredIndexKeys`), so only a leftover or a retracted declaration goes.
|
|
1696
|
+
* Refuses with `IndexDropRefusedError`.
|
|
1697
|
+
*
|
|
1698
|
+
* The drop waits for every transaction holding a lock on the table, and pg
|
|
1699
|
+
* cannot see a cycle through a caller that waits on this call, so each wait
|
|
1700
|
+
* is bounded by `lockTimeoutMs` (default `DROP_LOCK_TIMEOUT_MS`).
|
|
1701
|
+
*/
|
|
1702
|
+
dropEngineIndex(type: string, name: string, opts?: {
|
|
1703
|
+
beforeDrop?: () => Promise<void>;
|
|
1704
|
+
lockTimeoutMs?: number;
|
|
1705
|
+
}): Promise<void>;
|
|
1706
|
+
/**
|
|
1707
|
+
* See `Dataset.dropNamespaceIndexes`. The engine-owned indexes on this
|
|
1708
|
+
* namespace's type tables, which a namespace drop empties but keeps. Unique
|
|
1709
|
+
* ones only when `opts.unique`.
|
|
1710
|
+
* Each table's under its index-build lock, CONCURRENTLY; the wait for that
|
|
1711
|
+
* lock and each lock wait of a drop are bounded by `lockTimeoutMs` (default
|
|
1712
|
+
* `DROP_LOCK_TIMEOUT_MS`), past which it throws `index_drop_timeout`.
|
|
1713
|
+
*/
|
|
1714
|
+
dropNamespaceIndexes(opts?: {
|
|
1715
|
+
unique?: boolean;
|
|
1716
|
+
lockTimeoutMs?: number;
|
|
1717
|
+
}): Promise<string[]>;
|
|
1718
|
+
/** See `Dataset.indexDeclarationOf`. */
|
|
1719
|
+
indexDeclarationOf(type: string, name: string): Promise<IndexDecl | undefined>;
|
|
1720
|
+
/**
|
|
1721
|
+
* See `Dataset.typeStats`. Spans every namespace of the database, in a fixed
|
|
1722
|
+
* number of queries: each type table's own statistics; `liveRows` is
|
|
1723
|
+
* `reltuples` (or `n_live_tup` before the first ANALYZE) and counts
|
|
1724
|
+
* tombstoned rows too.
|
|
1725
|
+
*/
|
|
1726
|
+
typeStats(): Promise<TypeStats[]>;
|
|
1727
|
+
/**
|
|
1728
|
+
* `fields` is the type's, which the caller looks up once however many rows it
|
|
1729
|
+
* builds. The row is decoded first; `requested`, a read's `fields`, then
|
|
1730
|
+
* trims the `$raw` entries `decodeRow` overlays, since the projection keeps
|
|
1731
|
+
* `$raw` whole.
|
|
1732
|
+
*/
|
|
1331
1733
|
private materialize;
|
|
1332
1734
|
private extractOriginalId;
|
|
1333
1735
|
}
|
|
@@ -1454,6 +1856,11 @@ export declare function publicLeftoverWarning(names: readonly string[], packageN
|
|
|
1454
1856
|
* Call from `globalSetup`, so forked workers inherit the rewritten URL.
|
|
1455
1857
|
*/
|
|
1456
1858
|
export declare function preparePgTestSchema(url: string | undefined, opts: SchemaIsolationOptions): Promise<string | undefined>;
|
|
1859
|
+
/**
|
|
1860
|
+
* A `createSchema` for `preparePgTestSchema` that drops and recreates the
|
|
1861
|
+
* schema, so every run builds its store from an empty database.
|
|
1862
|
+
*/
|
|
1863
|
+
export declare function recreatePgTestSchema(url: string, schema: string): Promise<void>;
|
|
1457
1864
|
//#endregion
|
|
1458
1865
|
//#region ../../packages/substrate-embedder/src/fake.d.ts
|
|
1459
1866
|
interface FakeEmbedderOptions {
|
|
@@ -1467,36 +1874,8 @@ export declare class FakeEmbedder implements Embedder {
|
|
|
1467
1874
|
embed(text: string): Promise<Float32Array>;
|
|
1468
1875
|
}
|
|
1469
1876
|
//#endregion
|
|
1470
|
-
//#region ../../packages/substrate-server-memory/src/memory-ws-connection.d.ts
|
|
1471
|
-
/**
|
|
1472
|
-
* @internal — thrown when sending on a closed in-memory WS pair. Treat as
|
|
1473
|
-
* package-private.
|
|
1474
|
-
*/
|
|
1475
|
-
export declare class WsClosedError extends Error {
|
|
1476
|
-
constructor();
|
|
1477
|
-
}
|
|
1478
|
-
type Frame = Buffer | Uint8Array | string;
|
|
1479
|
-
interface MemoryWsClient {
|
|
1480
|
-
send(frame: Frame): void;
|
|
1481
|
-
onMessage(cb: (frame: Buffer) => void): void;
|
|
1482
|
-
onClose(cb: (code?: number) => void): void;
|
|
1483
|
-
close(code?: number, reason?: string): void;
|
|
1484
|
-
readonly closed: boolean;
|
|
1485
|
-
}
|
|
1486
|
-
/**
|
|
1487
|
-
* @internal — paired in-memory WS endpoints used by `MemorySubstrateServer`
|
|
1488
|
-
* for inject-style WS testing. Treat as package-private.
|
|
1489
|
-
*/
|
|
1490
|
-
export declare function createMemoryWsPair(): {
|
|
1491
|
-
server: WsConnection;
|
|
1492
|
-
client: MemoryWsClient;
|
|
1493
|
-
};
|
|
1494
|
-
//#endregion
|
|
1495
1877
|
//#region ../../packages/substrate-server-memory/src/memory-server.d.ts
|
|
1496
1878
|
type ErrorHook = (err: Error, req?: SubstrateRequest) => void;
|
|
1497
|
-
export declare class UnknownWsPathError extends Error {
|
|
1498
|
-
constructor(path: string);
|
|
1499
|
-
}
|
|
1500
1879
|
/**
|
|
1501
1880
|
* @internal — thrown when `MemorySubstrateServer.start()` is called twice.
|
|
1502
1881
|
* Re-exported from the package index; treat as package-private.
|
|
@@ -1507,7 +1886,6 @@ export declare class AlreadyStartedError extends Error {
|
|
|
1507
1886
|
export declare class MemorySubstrateServer implements SubstrateServer {
|
|
1508
1887
|
#private;
|
|
1509
1888
|
route(method: HttpMethod, path: string, handler: HttpHandler): void;
|
|
1510
|
-
websocket(path: string, handler: WsHandler): void;
|
|
1511
1889
|
onError(hook: ErrorHook): void;
|
|
1512
1890
|
observeRequests(observer: RequestObserver): void;
|
|
1513
1891
|
observeInFlight(fn: (op: RuntimeOp, delta: 1 | -1) => void): void;
|
|
@@ -1525,7 +1903,6 @@ export declare class MemorySubstrateServer implements SubstrateServer {
|
|
|
1525
1903
|
name: string;
|
|
1526
1904
|
}): PluginRouter;
|
|
1527
1905
|
inject(req: Partial<SubstrateRequest>): Promise<SubstrateResponse>;
|
|
1528
|
-
connectWebsocket(path: string, headers?: Record<string, string>): MemoryWsClient;
|
|
1529
1906
|
}
|
|
1530
1907
|
//#endregion
|
|
1531
1908
|
//#region ../../packages/substrate-server-memory/src/route-matcher.d.ts
|
|
@@ -1552,4 +1929,4 @@ export declare class MemorySubstrateServer implements SubstrateServer {
|
|
|
1552
1929
|
*/
|
|
1553
1930
|
export declare function matchRoute(registered: string, actual: string): Record<string, string> | null;
|
|
1554
1931
|
//#endregion
|
|
1555
|
-
export type { AuthConfig, ComposeResult, FieldDefLookup, IndexedListField,
|
|
1932
|
+
export type { AuthConfig, ComposeResult, FieldDefLookup, IndexedListField, PgDatasetOptions, PgEdgesStoreOptions };
|