@mnmal-ai/substrate 1.0.0-alpha.2 → 1.0.0-alpha.20

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