@mnmal-ai/substrate 1.0.0-alpha.8 → 1.0.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +32 -14
  2. package/dist/boot-store-BMQUbHKv.js +4086 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-DnToJedN.d.ts} +2 -87
  4. package/dist/cli-DModIbnN.js +3390 -0
  5. package/dist/client.browser.js +2507 -0
  6. package/dist/client.d.ts +222 -171
  7. package/dist/client.js +6 -7
  8. package/dist/cluster-worker.js +0 -1
  9. package/dist/{content-type-C7T28xNb.js → content-type-wLljot5M.js} +0 -1
  10. package/dist/{env-utils-CGNazUNt.js → env-utils-s25Z1YSA.js} +0 -1
  11. package/dist/{errors-D4vKuwz8.d.ts → errors-Cmkp1qxf.d.ts} +44 -4
  12. package/dist/{fake-DUVtKVSE.js → fake-DdXtb-m8.js} +0 -1
  13. package/dist/{index-D7mSOFlM.d.ts → index-BI4KqFiR.d.ts} +7 -11
  14. package/dist/msgpackr-Dq18g6Ds.js +16 -0
  15. package/dist/node-version-BtK_Nq6z.js +32 -0
  16. package/dist/pack.d.ts +75 -11
  17. package/dist/pack.js +4 -4
  18. package/dist/{plugin-B3NxUCVn.js → plugin-CEOhrEme.js} +149 -6
  19. package/dist/proposals-bootstrap.js +6 -5
  20. package/dist/proposals.config.schema.json +5 -0
  21. package/dist/proposals.d.ts +17 -5
  22. package/dist/proposals.default-config.json +2 -1
  23. package/dist/proposals.js +2 -3
  24. package/dist/recall-bootstrap.js +5 -4
  25. package/dist/recall.config.schema.json +6 -0
  26. package/dist/recall.d.ts +27 -6
  27. package/dist/recall.js +2 -3
  28. package/dist/{repl-DeKzfvNV.js → repl-BvDZy-Ut.js} +52 -26
  29. package/dist/{row-ByLFE2Wx.d.ts → row-D0If4qif.d.ts} +92 -12
  30. package/dist/run-BT123RV1.js +2443 -0
  31. package/dist/{plugin-t2g2wX0b.d.ts → schema-aIkY8sR3.d.ts} +1293 -63
  32. package/dist/{script-C6DSa_Na.js → script-ByQ9pzhC.js} +54 -26
  33. package/dist/script-runner.js +78 -0
  34. package/dist/sdk.d.ts +236 -38
  35. package/dist/sdk.js +5 -110
  36. package/dist/semver-D_zdq0hi.js +17 -0
  37. package/dist/src-BMD2OE--.js +8289 -0
  38. package/dist/{src-BLgbLq2k.js → src-B_kHkbsr.js} +780 -330
  39. package/dist/{src-DjIuRjzF.js → src-CKSJ13p8.js} +10231 -4237
  40. package/dist/{src-CkZw6xVD.js → src-CW7eRDss.js} +188 -87
  41. package/dist/{row-DZ0Fnpc6.js → src-DmiUWOLp.js} +2 -1
  42. package/dist/{src-DCy7Iy2l.js → src-DmjwFMu8.js} +900 -77
  43. package/dist/{src-DiNTSaFk.js → src-FXO5JPyk.js} +686 -856
  44. package/dist/substrate-admin.js +17 -782
  45. package/dist/substrate.js +4 -5206
  46. package/dist/testing.d.ts +473 -96
  47. package/dist/testing.js +19 -165
  48. package/dist/{ws-C72iVS5T.d.ts → ws-DW8ng02H.d.ts} +4 -5
  49. package/package.json +26 -26
  50. package/dist/dataset-jZS_4ci4.js +0 -1535
  51. package/dist/pg-edges-store-KH_FQCxx.js +0 -381
  52. package/dist/schema-g4FQLr0V.d.ts +0 -433
  53. package/dist/src-BD27zeGF.js +0 -2339
package/dist/testing.d.ts CHANGED
@@ -1,7 +1,5 @@
1
- import { C as Id, E as Row, _ as EdgesStore, b as ActorIdentity, f as CanDeleteResult, g as EdgeWriteInput, h as EdgeRef, l as PackEnvelope, m as EdgePatch, n as FieldDef, p as Edge, u as Schema } from "./schema-g4FQLr0V.js";
2
- import { a as RuntimeErrors, n as ResolveObservation, r as ResolverStat, s as SlowRequest, t as ProcessStat } from "./runtime-metrics-DwpDJ8vz.js";
3
- import { $ as PolicyProbeContext, A as ScheduledTask, B as StartOpts, C as QualifiedFrame, D as RegistryEntryInput, E as RegistryEntry, F as HttpMethod, G as WsConnection, H as SubstrateResponse, I as PluginRouter, K as WsHandler, P as HttpHandler, Q as PolicyDecision, R as RequestObserver, St as WriteResult, T as RegistryBase, U as SubstrateServer, V as SubstrateRequest, Y as Identity, _t as ReadResult, a as EngineHandle, ct as Dataset, dt as DropResult, et as RequestContext, g as NamespaceConfig, gt as ReadParams, lt as DatasetRegistry, mt as FilterCapabilities, n as DropParticipant, o as EngineInput, p as KernelPlugin, st as ConditionalUpdateResult, t as CoordinatorPlugin, ut as DeleteResult, 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
- * - `'socket_close'` — underlying WS socket closed (conn.onClose)
339
+ * - `'client_disconnect'` — client disconnected (response closed)
285
340
  * - `'shutdown'` — server-initiated graceful shutdown (conn.onShutdown)
286
341
  */
287
- type SubscriptionCancelReason = 'cancel' | 'socket_close' | 'shutdown';
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. WS
306
- * send-buffer drain) can resolve asynchronously. The fanout loop tracks
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
- write(type: string, rows: Row[], options?: WriteOptions): Promise<WriteResult>;
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 the `/substrate/v1/ws` upgrade require a
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/ws-subscription-contract.md).
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
- * HMAC secret for browser SSE stream tickets. REQUIRED when `auth` is set,
970
- * and at least `MIN_STREAM_TICKET_SECRET_LEN` characters after trimming —
971
- * `compose` throws otherwise, because the ungated `GET` stream routes
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
- streamTicketSecret?: string;
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. The version key uses the raw ns/type/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, derived: ReadonlyArray<MigrationInput>): Promise<void>;
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
- * Body keys mirrored into dedicated columns on `rows`, so filters and
1214
- * sorts on them use an index instead of extracting from JSONB.
1215
- *
1216
- * None by default. A namespace declares its own (`NamespaceDefinition`'s
1217
- * `promotedColumns`), and the plugin that declares them adds the columns in
1218
- * its kernel migrations: the engine creates none. Three things that bite:
1219
- *
1220
- * - Filters and sorts route to the column and ONLY the column, so a column
1221
- * added over existing rows must be backfilled from the body first, or
1222
- * those rows miss every filter. Reads return the body.
1223
- * - `column` is a BARE name (`'severity'`, not `'r.severity'`) and is
1224
- * validated as an identifier at construction, because it is interpolated
1225
- * into SQL as an identifier.
1226
- * - Text columns sort and range-compare `COLLATE "C"`, so an index meant
1227
- * to serve those must be built `COLLATE "C"` too.
1228
- */
1229
- promotedColumns?: PromotedBodyColumnMap;
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
- /** See `PgDatasetOptions.promotedColumns`. */
1243
- promotedColumns?: PromotedBodyColumnMap;
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
- * Body values extract as text and are cast for comparison only; the filter
1256
- * validator has already rejected type mismatches.
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
- write(type: string, rows: Row[], options?: WriteOptions): Promise<WriteResult>;
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
- * Short-id mappings are left in place, as in `purge()`: a row id can
1268
- * reappear after a tombstone + rewrite.
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
- * database, across processes. On a tx-bound instance the lock is
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, MemoryWsClient, PgDatasetOptions, PgEdgesStoreOptions };
1932
+ export type { AuthConfig, ComposeResult, FieldDefLookup, IndexedListField, PgDatasetOptions, PgEdgesStoreOptions };