@mnmal-ai/substrate 1.0.0-alpha.10 → 1.0.0-alpha.12

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 (39) hide show
  1. package/README.md +4 -2
  2. package/dist/{boot-store-BVqfFxh1.js → boot-store-DHv9H1Gr.js} +170 -69
  3. package/dist/{bridge-Cp4PaIYO.d.ts → bridge-DQyQ6Qhn.d.ts} +1 -1
  4. package/dist/{cli-hSCBywhE.js → cli-_UNdneXr.js} +44 -24
  5. package/dist/client.d.ts +3 -4
  6. package/dist/client.js +3 -3
  7. package/dist/{errors-7mycvNGq.d.ts → errors-xP9Mo7Q1.d.ts} +38 -4
  8. package/dist/{index-DgSfwx7M.d.ts → index-baF5A5jU.d.ts} +1 -1
  9. package/dist/pack.d.ts +2 -2
  10. package/dist/pack.js +1 -1
  11. package/dist/{pg-edges-store-Lxsl5ZnK.js → pg-edges-store-B4FSN9yp.js} +72 -9
  12. package/dist/{plugin-CtwOINCM.js → plugin-BLm5IRdX.js} +2 -2
  13. package/dist/proposals-bootstrap.js +2 -2
  14. package/dist/proposals.d.ts +2 -3
  15. package/dist/proposals.js +1 -1
  16. package/dist/recall-bootstrap.js +2 -2
  17. package/dist/recall.d.ts +10 -11
  18. package/dist/recall.js +2 -2
  19. package/dist/{repl-DqfHelK7.js → repl-DUJGBwie.js} +25 -25
  20. package/dist/{row-BKKCXIG6.d.ts → row-Cu_iRhcR.d.ts} +57 -10
  21. package/dist/{run-B5dTbZ3g.js → run-BpsTNvdI.js} +539 -145
  22. package/dist/{dataset-CejF-Fr_.d.ts → schema-oXfQyo0s.d.ts} +2455 -1589
  23. package/dist/sdk.d.ts +108 -34
  24. package/dist/sdk.js +4 -4
  25. package/dist/{src-CqT-QWZ_.js → src-Bew_JvTo.js} +32 -16
  26. package/dist/{src-Da0t6si5.js → src-Bi3NhEsT.js} +1 -1
  27. package/dist/{src-5SJ5GEIM.js → src-C4t1Gy-m.js} +4844 -1367
  28. package/dist/{src-7CUSMK66.js → src-CHND7-Pm.js} +7 -3
  29. package/dist/src-CSe2tJDf.js +6940 -0
  30. package/dist/{src-Bi849yhn.js → src-CzhKLsOV.js} +175 -91
  31. package/dist/{src-hZb8wfvg.js → src-DWqzrm3O.js} +400 -284
  32. package/dist/substrate-admin.js +1 -1
  33. package/dist/substrate.js +1 -1
  34. package/dist/testing.d.ts +255 -90
  35. package/dist/testing.js +6 -23
  36. package/dist/{ws-ByZyHk7m.d.ts → ws-Dx3A2B4U.d.ts} +2 -3
  37. package/package.json +20 -20
  38. package/dist/schema-DoSc-4ig.d.ts +0 -470
  39. package/dist/src-CyvV7dCK.js +0 -4333
@@ -37,7 +37,7 @@ function isEntrypointPath(moduleUrl, argv1) {
37
37
  */
38
38
  if (isEntrypointPath(import.meta.url, process.argv[1])) {
39
39
  assertNodeVersion();
40
- import("./run-B5dTbZ3g.js").then(({ runAdminCli }) => runAdminCli());
40
+ import("./run-BpsTNvdI.js").then(({ runAdminCli }) => runAdminCli());
41
41
  }
42
42
 
43
43
  //#endregion
package/dist/substrate.js CHANGED
@@ -4,7 +4,7 @@ import { t as assertNodeVersion } from "./node-version-C5FSmwJX.js";
4
4
 
5
5
  //#region src/bin/substrate.ts
6
6
  assertNodeVersion();
7
- import("./cli-hSCBywhE.js").then(({ runCli }) => runCli(process.argv.slice(2))).then((code) => process.exit(code));
7
+ import("./cli-_UNdneXr.js").then(({ runCli }) => runCli(process.argv.slice(2))).then((code) => process.exit(code));
8
8
 
9
9
  //#endregion
10
10
  export { };
package/dist/testing.d.ts CHANGED
@@ -1,6 +1,5 @@
1
- import { C as ActorIdentity, E as Id, M as WriteRow, _ as EdgePatch, b as EdgesStore, d as PackEnvelope, f as Schema, g as Edge, h as CanDeleteResult, k as Row, r as FieldDef, u as OrderedBy, v as EdgeRef, y as EdgeWriteInput } from "./schema-DoSc-4ig.js";
2
- import { $ as Registry$1, A as DropParticipant, C as ResolverStat, D as SlowRequest, Dt as PolicyDecision, G as NamespaceConfig, H as KernelPlugin, L as IndexDecl, N as EngineHandle, O as TypeStats, Ot as PolicyProbeContext, P as EngineInput, Q as QualifiedFrame, S as ResolveObservation, T as RuntimeErrors, _ as UpdateFieldRef, _t as SubstrateResponse, a as DropResult, at as ScheduledTask, b as WriteResult, bt as WsConnection, c as FilterCapabilities, d as ReadParams, dt as PluginRouter, et as RegistryBase, f as ReadResult, g as TypeStorageReport, gt as SubstrateRequest, ht as StartOpts, i as DeleteResult, k as CoordinatorPlugin, kt as RequestContext, l as IndexPlan, lt as HttpHandler, m as TxScopeHandles, mt as RuntimeOp, n as Dataset, nt as RegistryEntryInput, p as StorageReport, pt as RequestObserver, r as DatasetRegistry, t as ConditionalUpdateResult, tt as RegistryEntry, ut as HttpMethod, vt as SubstrateServer, wt as Identity, x as ProcessStat, xt as WsHandler, y as WriteOptions } from "./dataset-CejF-Fr_.js";
3
- import { a as WsResponseFrame, f as IdempotencyStore, l as SweepDeps, s as BridgeRegistry, u as SweepState } from "./ws-ByZyHk7m.js";
1
+ import { At as ConditionalUpdateResult, Bt as FilterWriteLimits, Cn as EdgesStore, Ct as ResolverArgs, Dt as WriteEvent, E as EngineInput, En as ActorIdentity, Fn as WriteRow, G as Registry$1, Ht as FilterWriteResult, It as DropResult, J as RegistryEntryInput, Jt as ReadParams, K as RegistryBase, L as NamespaceConfig, Mn as Row, Mt as Dataset, Nt as DatasetRegistry, P as KernelPlugin, Pt as DeleteResult, Qt as TxScopeHandles, S as DropParticipant, Sn as EdgeWriteInput, T as EngineHandle, Vt as FilterWriteOptions, W as QualifiedFrame, Wt as IndexPlan, Yt as ReadResult, Z as ScheduledTask, Zt as StorageReport, _n as TypeStats, at as RequestObserver, b as CommittedWritesHook, bn as EdgePatch, bt as PolicyProbeContext, cn as WriteOptions, ct as SubstrateRequest, d as OrderedBy, dn as ResolveObservation, en as TypeStorageReport, f as PackEnvelope, fn as ResolverStat, ft as WsConnection, gn as SlowRequest, gt as Identity, i as FieldDef, k as IndexDecl, kn as Id, ln as WriteResult, lt as SubstrateResponse, m as Schema, mn as RuntimeErrors, nt as HttpMethod, ot as RuntimeOp, pt as WsHandler, q as RegistryEntry, qt as PromotionEvent, rt as PluginRouter, sn as WhereClause, st as StartOpts, tn as UpdateFieldRef, tt as HttpHandler, un as ProcessStat, ut as SubstrateServer, vn as CanDeleteResult, x as CoordinatorPlugin, xn as EdgeRef, xt as RequestContext, yn as Edge, yt as PolicyDecision, zt as FilterCapabilities } from "./schema-oXfQyo0s.js";
2
+ import { a as WsResponseFrame, f as IdempotencyStore, l as SweepDeps, s as BridgeRegistry, u as SweepState } from "./ws-Dx3A2B4U.js";
4
3
  import { t as Embedder } from "./types-8c0gtnd2.js";
5
4
  import { Sql, TransactionSql } from "postgres";
6
5
  //#region ../../packages/substrate-compose/src/auth.d.ts
@@ -277,6 +276,18 @@ interface EngineOptions {
277
276
  * the resolver took. For the index advisor; absent means no recording.
278
277
  */
279
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;
280
291
  /**
281
292
  * Idempotency dedup (§5.13). Absent → no dedup; `FrameEntry.idempotencyKey`
282
293
  * is ignored on mutate (queries ignore it unconditionally). Present → the
@@ -517,7 +528,7 @@ declare class Engine {
517
528
  * caller's `probe` context so policies reading headers, `clientIp`, `meta`
518
529
  * or `authEnabled` decide as they would in dispatch.
519
530
  */
520
- 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;
521
532
  /**
522
533
  * Refresh the cached schemas for every registered bridge. Callers invoke
523
534
  * this at composition-root wire-up time to populate `federatedSchema()`'s
@@ -568,6 +579,17 @@ declare class Engine {
568
579
  * fanout — see subscribe.ts for the full contract.
569
580
  */
570
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[];
571
593
  /**
572
594
  * Live count of active subscription entries. Delegates to the
573
595
  * SubscribeSubsystem, which owns the authoritative map.
@@ -663,6 +685,8 @@ export declare class MemoryEdgesStore implements EdgesStore {
663
685
  */
664
686
  private nextId;
665
687
  write(input: EdgeWriteInput): Promise<Edge>;
688
+ writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
689
+ tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
666
690
  tombstone(id: string, at?: Date): Promise<void>;
667
691
  update(patch: EdgePatch): Promise<void>;
668
692
  readNextBatch(cursorId: string | null, size: number): Promise<{
@@ -672,6 +696,7 @@ export declare class MemoryEdgesStore implements EdgesStore {
672
696
  findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
673
697
  findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
674
698
  findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
699
+ findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
675
700
  canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
676
701
  findBlocked(): Promise<Edge[]>;
677
702
  findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
@@ -780,17 +805,32 @@ interface MemoryDatasetOptions {
780
805
  fieldDefLookup?: (type: string, field: string) => FieldDef | undefined;
781
806
  /**
782
807
  * The namespace's type definitions; a type declared `ordering: 'visible'`
783
- * gets `_metadata.seq` on insert, as the pg dataset's lookup does.
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`).
784
810
  */
785
811
  typeDefLookup?: (type: string, namespace: string) => {
786
812
  ordering?: 'visible';
813
+ fields?: Record<string, FieldDef>;
787
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;
788
826
  }
789
827
  export declare class MemoryDataset implements Dataset {
790
828
  #private;
791
829
  readonly namespace: string;
792
830
  readonly txScopeId: string;
793
831
  private readonly typeDefLookup;
832
+ private readonly walkBudget;
833
+ private readonly walkReference;
794
834
  /** Last seq assigned per visible-order type; never decreases, as pg's `visible_seqs`. */
795
835
  private seqs;
796
836
  readonly capabilities: FilterCapabilities;
@@ -801,7 +841,15 @@ export declare class MemoryDataset implements Dataset {
801
841
  constructor(options: MemoryDatasetOptions);
802
842
  private bucket;
803
843
  read(type: string, params: ReadParams): Promise<ReadResult>;
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;
804
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;
805
853
  tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
806
854
  purge(type: string, ids: Id[]): Promise<DeleteResult>;
807
855
  dropType(type: string): Promise<DropResult>;
@@ -834,6 +882,18 @@ export declare class MemoryDataset implements Dataset {
834
882
  allocateShortId(type: string): Promise<number>;
835
883
  bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
836
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>;
837
897
  getShortIdForRow(type: string, rowId: string): Promise<number | null>;
838
898
  forNamespace(namespace: string): Dataset;
839
899
  }
@@ -1009,6 +1069,12 @@ interface ComposeOpts {
1009
1069
  defaultLimit: number;
1010
1070
  maxLimit: number;
1011
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;
1012
1078
  /**
1013
1079
  * Opt-in periodic re-prime interval (ms) for the
1014
1080
  * `KeyRegistry` public-key cache. Bounds cross-instance revocation
@@ -1053,6 +1119,14 @@ interface ComposeOpts {
1053
1119
  storeProfile?: StoreProfileName;
1054
1120
  writeHeavy?: boolean;
1055
1121
  };
1122
+ /**
1123
+ * The promotion sweep, every `intervalMs` (`SUBSTRATE_PROMOTE_INTERVAL_MS`),
1124
+ * over `dataset`'s pending fields. Omitted or `intervalMs: 0`: no timer;
1125
+ * `POST /substrate/v1/_system/promote-fields` runs it either way.
1126
+ */
1127
+ promoteFields?: {
1128
+ intervalMs: number;
1129
+ };
1056
1130
  }
1057
1131
  interface ComposeResult {
1058
1132
  engine: Engine;
@@ -1079,6 +1153,8 @@ interface ComposeResult {
1079
1153
  runAdvisorNow: (() => Promise<{
1080
1154
  upserted: number;
1081
1155
  }>) | null;
1156
+ /** Run one promotion sweep now, as the admin route does. */
1157
+ runPromoteFieldsNow: () => Promise<PromotionEvent[]>;
1082
1158
  /**
1083
1159
  * Non-null when any coordinator plugin contributed a `schedule`. The
1084
1160
  * composition root constructs the scheduler, registers every plugin's
@@ -1095,6 +1171,62 @@ interface ComposeResult {
1095
1171
  }
1096
1172
  export declare function compose(opts: ComposeOpts): Promise<ComposeResult>;
1097
1173
  //#endregion
1174
+ //#region ../../packages/substrate-dataset-pg/src/tx-scope.d.ts
1175
+ type PgHandle = Sql | TransactionSql;
1176
+ //#endregion
1177
+ //#region ../../packages/substrate-dataset-pg/src/type-table.d.ts
1178
+ type ColumnKind = 'text' | 'enum' | 'number' | 'date' | 'boolean' | 'crossRef';
1179
+ interface TypedColumn {
1180
+ field: string;
1181
+ column: string;
1182
+ kind: ColumnKind;
1183
+ state: 'column' | 'promoting' | 'orphaned';
1184
+ vocab?: readonly string[];
1185
+ }
1186
+ interface TypeTable {
1187
+ namespace: string;
1188
+ type: string;
1189
+ /** The table, as a quoted identifier. */
1190
+ from: string;
1191
+ /** The jsonb column holding every field without a column of its own. */
1192
+ jsonb: 'extra';
1193
+ column(field: string): TypedColumn | undefined;
1194
+ columns(): readonly TypedColumn[];
1195
+ /** Declared fields whose values live in `extra` until they get a column. */
1196
+ pending: readonly string[];
1197
+ orphaned: readonly string[];
1198
+ /**
1199
+ * The catalog version this descriptor was loaded at (bigint text). Every
1200
+ * write checks it in its own statement (`guardCte`), so one built from a
1201
+ * stale descriptor writes nothing and is rebuilt.
1202
+ */
1203
+ version: string;
1204
+ }
1205
+ /**
1206
+ * A pool's type-table descriptors. A
1207
+ * `substrate_catalog` notification (sent by `ensureTypeTable` on any change,
1208
+ * delivered at commit) drops its type's entry, and a (re)connect of the
1209
+ * listener drops them all, since notifications may have been missed.
1210
+ */
1211
+ interface TableCache {
1212
+ /** The pool, which LISTENs on a connection of its own. */
1213
+ sql: PgHandle;
1214
+ /** `null` is a cached miss: the type has no table yet. */
1215
+ tables: Map<string, TypeTable | null>;
1216
+ /** Bumped on each drop; a load notes it at its start (see {@link mayCache}). */
1217
+ gen: number;
1218
+ /** Each key's last drop's `gen`, so a load is refused only for a drop of its own key. */
1219
+ dropped: Map<string, number>;
1220
+ /** The last full clear's `gen`. */
1221
+ cleared: number;
1222
+ /** True once listening; false when LISTEN failed, and then nothing is cached. */
1223
+ listening?: Promise<boolean>;
1224
+ /** After a failed LISTEN, when the next call may try again. */
1225
+ listenRetryAt?: number;
1226
+ /** Only `true` is kept: the migration can be applied while this process runs, never unapplied. */
1227
+ uuidCheck?: true;
1228
+ }
1229
+ //#endregion
1098
1230
  //#region ../../packages/substrate-dataset-pg/src/disk-guard.d.ts
1099
1231
  /**
1100
1232
  * Refuses a background index build that would leave less than a margin of
@@ -1114,21 +1246,7 @@ interface DiskGuard {
1114
1246
  }
1115
1247
  //#endregion
1116
1248
  //#region ../../packages/substrate-dataset-pg/src/layout.d.ts
1117
- type StorageLayout = 'legacy' | 'partitioned';
1118
- //#endregion
1119
- //#region ../../packages/substrate-dataset-pg/src/pg-sql/primitives.d.ts
1120
- /**
1121
- * A body key mirrored into a dedicated column on `rows`, so filters and
1122
- * sorts on it hit an index instead of extracting from JSONB.
1123
- *
1124
- * `column` is a BARE column name, not a qualified `r.<col>` fragment: taking a
1125
- * fragment from a caller would put caller text into `sql.unsafe`.
1126
- */
1127
- interface PromotedBodyColumn {
1128
- column: string;
1129
- kind: 'boolean' | 'text';
1130
- }
1131
- type PromotedBodyColumnMap = Readonly<Record<string, PromotedBodyColumn>>;
1249
+ type StorageLayout = 'tables';
1132
1250
  //#endregion
1133
1251
  //#region ../../packages/substrate-dataset-pg/src/migrate.d.ts
1134
1252
  /**
@@ -1165,12 +1283,6 @@ interface RunMigrationsOptions {
1165
1283
  * Production bootstraps shouldn't pass this — let the env decide.
1166
1284
  */
1167
1285
  enforceUuidCheck?: boolean;
1168
- /**
1169
- * The layout for a database with no `rows` yet. Ignored once `rows` exists,
1170
- * since a database keeps its layout. Defaults to `SUBSTRATE_STORAGE_LAYOUT`,
1171
- * then `partitioned`.
1172
- */
1173
- layout?: StorageLayout;
1174
1286
  }
1175
1287
  export declare function runMigrations(sql: Sql, opts?: RunMigrationsOptions): Promise<void>;
1176
1288
  /**
@@ -1184,7 +1296,9 @@ interface IndexedListField {
1184
1296
  }
1185
1297
  /**
1186
1298
  * Derives the tracked, idempotent CONCURRENTLY GIN migration for one indexed
1187
- * field. The version key uses the raw ns/type/field.
1299
+ * field, as the legacy layout built it on `rows`. The version key uses the raw
1300
+ * ns/type/field. `runDerivedMigrations` skips these: each type table's GIN
1301
+ * indexes are its own, built by `reconcileTypeIndexes`.
1188
1302
  */
1189
1303
  export declare function deriveListIndexMigration(f: IndexedListField): MigrationInput;
1190
1304
  /**
@@ -1193,15 +1307,11 @@ export declare function deriveListIndexMigration(f: IndexedListField): Migration
1193
1307
  * since `runMigrations` has no field-def knowledge. Idempotent: applied
1194
1308
  * versions are skipped.
1195
1309
  *
1196
- * On the partitioned layout the list/json GIN migrations are skipped: those
1197
- * indexes live on each type's partition, built by `reconcileTypeIndexes`, and
1198
- * Postgres cannot build one CONCURRENTLY on the partitioned parent.
1310
+ * The list/json GIN migrations are skipped: there is no `rows` to aim them
1311
+ * at, and each type table's indexes are its own (`reconcileTypeIndexes`).
1199
1312
  */
1200
1313
  export declare function runDerivedMigrations(sql: Sql, all: ReadonlyArray<MigrationInput>): Promise<void>;
1201
1314
  //#endregion
1202
- //#region ../../packages/substrate-dataset-pg/src/tx-scope.d.ts
1203
- type PgHandle = Sql | TransactionSql;
1204
- //#endregion
1205
1315
  //#region ../../packages/substrate-dataset-pg/src/pg-edges-store.d.ts
1206
1316
  interface PgEdgesStoreOptions {
1207
1317
  sql: Sql;
@@ -1229,6 +1339,8 @@ export declare class PgEdgesStore implements EdgesStore {
1229
1339
  readonly txScopeId: string;
1230
1340
  constructor(options: PgEdgesStoreOptions | InternalPgEdgesStoreOptions);
1231
1341
  write(input: EdgeWriteInput): Promise<Edge>;
1342
+ writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
1343
+ tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
1232
1344
  tombstone(id: string, at?: Date): Promise<void>;
1233
1345
  /**
1234
1346
  * Hard-deletes tombstoned edges whose `deleted_at` is older than
@@ -1246,6 +1358,7 @@ export declare class PgEdgesStore implements EdgesStore {
1246
1358
  }>;
1247
1359
  findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
1248
1360
  findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
1361
+ findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
1249
1362
  findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
1250
1363
  findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
1251
1364
  findEdgesTouchingType(namespace: string, type: string, limit: number): Promise<Edge[]>;
@@ -1324,25 +1437,6 @@ interface PgDatasetOptions {
1324
1437
  * expression; it needs a matching cast expression index.
1325
1438
  */
1326
1439
  fieldDefLookup?: FieldDefLookup;
1327
- /**
1328
- * Body keys mirrored into dedicated columns on `rows`, so filters and
1329
- * sorts on them use an index instead of extracting from JSONB.
1330
- *
1331
- * None by default. A namespace declares its own (`NamespaceDefinition`'s
1332
- * `promotedColumns`), and the plugin that declares them adds the columns in
1333
- * its kernel migrations: the engine creates none. Three things that bite:
1334
- *
1335
- * - Filters and sorts route to the column and ONLY the column, so a column
1336
- * added over existing rows must be backfilled from the body first, or
1337
- * those rows miss every filter. Reads return the body.
1338
- * - `column` is a BARE name (`'severity'`, not `'r.severity'`) and is
1339
- * validated as an identifier at construction, because it is interpolated
1340
- * into SQL as an identifier.
1341
- * - Text columns compare `COLLATE "C"` in every operator, eq included,
1342
- * so an index meant to serve them must key `(column COLLATE "C")`, as
1343
- * declared `indexes` do.
1344
- */
1345
- promotedColumns?: PromotedBodyColumnMap;
1346
1440
  /**
1347
1441
  * The namespace's type definitions, which `ensureTypeStorage` builds the
1348
1442
  * type's indexes from. Without it only the engine's own indexes are built.
@@ -1355,6 +1449,12 @@ interface PgDatasetOptions {
1355
1449
  * checked either, and `storageReport` says so.
1356
1450
  */
1357
1451
  diskGuard?: DiskGuard;
1452
+ /**
1453
+ * The statement timeout a walk read runs under, in ms (default
1454
+ * `WALK_STATEMENT_TIMEOUT_MS`). A read it cancels is refused as
1455
+ * `query_timeout`.
1456
+ */
1457
+ statementTimeoutMs?: number;
1358
1458
  }
1359
1459
  interface InternalPgSubstrateDatasetOptions {
1360
1460
  namespace: string;
@@ -1367,14 +1467,32 @@ interface InternalPgSubstrateDatasetOptions {
1367
1467
  txScopeId?: string;
1368
1468
  edgesStore?: PgEdgesStore;
1369
1469
  fieldDefLookup?: FieldDefLookup;
1370
- /** See `PgDatasetOptions.promotedColumns`. */
1371
- promotedColumns?: PromotedBodyColumnMap;
1372
1470
  /** Shared with the instance this one was derived from. */
1373
1471
  layoutCache?: LayoutCache;
1374
1472
  typeDefLookup?: TypeDefLookup;
1375
1473
  diskGuard?: DiskGuard;
1474
+ statementTimeoutMs?: number;
1475
+ /** The pool's type-table cache, shared with the instance this one was derived from. */
1476
+ tableCache?: TableCache;
1477
+ /** The enclosing transaction's tables, which enter `tableCache` on commit only. */
1478
+ txTables?: TxTables;
1376
1479
  }
1377
- /** The detected layout, shared by an instance and every clone of it. */
1480
+ /**
1481
+ * The tables a transaction loaded or created, each with the cache generation
1482
+ * it was loaded at. They enter the pool's cache when the transaction commits,
1483
+ * so a rolled-back CREATE or ALTER is never cached (F18).
1484
+ */
1485
+ /**
1486
+ * A transaction's descriptors. `snapshot`: loaded for a non-READ COMMITTED
1487
+ * transaction's own snapshot (`null`: no table there), which never reaches
1488
+ * the pool's cache.
1489
+ */
1490
+ type TxTables = Map<string, {
1491
+ table: TypeTable | null;
1492
+ gen: number;
1493
+ snapshot?: true;
1494
+ }>;
1495
+ /** The store's layout once migrated, shared by an instance and every clone of it. */
1378
1496
  interface LayoutCache {
1379
1497
  layout?: StorageLayout;
1380
1498
  }
@@ -1384,6 +1502,14 @@ export declare class PgDataset implements Dataset {
1384
1502
  readonly capabilities: FilterCapabilities;
1385
1503
  readonly txScopeId: string;
1386
1504
  constructor(options: PgDatasetOptions | InternalPgSubstrateDatasetOptions);
1505
+ /**
1506
+ * Reads rows of `type` per the §5.2 filter contract (where / orderBy /
1507
+ * cursor / limit). Every value is bound through a parameterised slot.
1508
+ *
1509
+ * The walk grammar (spec 2026-10-24-typed-edge-walks §3) runs in a
1510
+ * transaction under a `SET LOCAL` statement timeout, since pg has no walk
1511
+ * evaluation budget. Other reads are unchanged.
1512
+ */
1387
1513
  read(type: string, params: ReadParams): Promise<ReadResult>;
1388
1514
  /**
1389
1515
  * Upsert `rows`. A row without an `id` gets one from the database's
@@ -1404,14 +1530,16 @@ export declare class PgDataset implements Dataset {
1404
1530
  */
1405
1531
  write(type: string, rows: WriteRow[], options?: WriteOptions): Promise<WriteResult>;
1406
1532
  tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
1533
+ /** On a type table, `deleted` also leaves `row_ids`, and `short_ids` cascade from there. */
1407
1534
  purge(type: string, ids: Id[]): Promise<DeleteResult>;
1408
1535
  /**
1409
1536
  * Hard-deletes tombstoned rows whose `deleted_at` is older than `olderThan`,
1410
1537
  * across ALL namespaces (the table is substrate-shared). Called by the sweep
1411
1538
  * loop. Returns the number of rows deleted.
1412
1539
  *
1413
- * Short-id mappings are left in place, as in `purge()`: a row id can
1414
- * reappear after a tombstone + rewrite.
1540
+ * Each type table is swept in one pass, a window of {@link purgeBatch} ids
1541
+ * per statement in id order, and a swept row leaves `row_ids` in the same
1542
+ * statement, its short id cascading.
1415
1543
  */
1416
1544
  purgeTombstonedRows(opts: {
1417
1545
  olderThan: Date;
@@ -1422,7 +1550,8 @@ export declare class PgDataset implements Dataset {
1422
1550
  * Hard-delete every row for `type` in this namespace, including tombstoned
1423
1551
  * rows (`deleted_at IS NOT NULL`). Short-id mappings for that type are
1424
1552
  * removed in the same logical operation. Both deletes run through `this.#sql`
1425
- * so they participate in any surrounding `withTransaction` boundary.
1553
+ * so they participate in any surrounding `withTransaction` boundary. A type
1554
+ * table is emptied, not dropped.
1426
1555
  */
1427
1556
  dropType(type: string): Promise<DropResult>;
1428
1557
  /**
@@ -1472,20 +1601,59 @@ export declare class PgDataset implements Dataset {
1472
1601
  allocateShortId(type: string): Promise<number>;
1473
1602
  bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
1474
1603
  resolveShortId(type: string, shortId: number): Promise<string | null>;
1604
+ allocateShortIds(type: string, count: number): Promise<number[]>;
1605
+ bindShortIds(type: string, pairs: ReadonlyArray<{
1606
+ shortId: number;
1607
+ rowId: string;
1608
+ }>): Promise<void>;
1609
+ resolveShortIds(type: string, shortIds: readonly number[]): Promise<ReadonlyMap<number, string>>;
1610
+ patchRows(type: string, patches: ReadonlyArray<{
1611
+ id: Id;
1612
+ patch: Record<string, unknown>;
1613
+ }>, actor: ActorIdentity | null, now: Date): Promise<Array<Row | null>>;
1614
+ updateWhere(type: string, where: WhereClause, set: Record<string, unknown>, opts: FilterWriteOptions): Promise<FilterWriteResult>;
1615
+ deleteWhere(type: string, where: WhereClause, opts: FilterWriteOptions): Promise<FilterWriteResult>;
1475
1616
  getShortIdForRow(type: string, rowId: string): Promise<number | null>;
1476
1617
  forNamespace(namespace: string): Dataset;
1477
1618
  /**
1478
- * See `Dataset.ensureTypeStorage`. On the partitioned layout, creates this
1479
- * namespace's partition and the type's, then reconciles the type's indexes
1480
- * on it; on legacy, reconciles only its declared `indexes`. Index builds
1481
- * run CONCURRENTLY, outside any transaction, so a tx-bound instance refuses.
1482
- * Logs each index it created, adopted or swapped, and records each one
1483
- * left pending, building or failed for `describeStorage` and `storageReport`.
1619
+ * See `Dataset.ensureTypeStorage`. Brings the type's table in line with its
1620
+ * declared fields (`ensureTypeTable`; a new field gets its column, or
1621
+ * `pending` under `newFields: 'pending'`), then reconciles its indexes on
1622
+ * it, and returns the fields that went `pending` in this call (F12). An
1623
+ * index reading a pending field's column waits, `pending`, until the column
1624
+ * exists. Index builds run CONCURRENTLY, outside any transaction, so a
1625
+ * tx-bound instance refuses. Logs each index it created, adopted or
1626
+ * swapped, and records each one left pending, building or failed for
1627
+ * `describeStorage` and `storageReport`.
1484
1628
  */
1485
1629
  ensureTypeStorage(type: string, opts?: {
1486
1630
  indexes?: 'all' | 'unique' | 'nonUnique';
1487
1631
  signal?: AbortSignal;
1488
- }): Promise<void>;
1632
+ newFields?: 'column' | 'pending';
1633
+ }): Promise<{
1634
+ pending: string[];
1635
+ }>;
1636
+ /**
1637
+ * See `Dataset.promotePendingFields`. Store-wide; `[]` before the store is
1638
+ * migrated. Each field's
1639
+ * indexes are reconciled through its namespace's view of this dataset, so a
1640
+ * declared index waiting on the new column is built.
1641
+ */
1642
+ promotePendingFields(opts: {
1643
+ lockTimeoutMs: number;
1644
+ batchRows: number;
1645
+ signal?: AbortSignal;
1646
+ /** Only this namespace's fields. */
1647
+ namespace?: string;
1648
+ retryConflicts?: boolean;
1649
+ noWriters?: boolean;
1650
+ }): Promise<PromotionEvent[]>;
1651
+ /**
1652
+ * See `Dataset.fieldWarnings`. Store-wide; none before the store is migrated. Counts
1653
+ * only, since `/health` shows it unauthenticated: the named lines are in
1654
+ * `storageReport`, which is admin-gated.
1655
+ */
1656
+ fieldWarnings(): Promise<string[]>;
1489
1657
  /**
1490
1658
  * The type's non-unique indexes the next build pass would build or swap,
1491
1659
  * each with the disk guard's estimate. Empty when the store or the type's
@@ -1495,12 +1663,16 @@ export declare class PgDataset implements Dataset {
1495
1663
  name: string;
1496
1664
  estimateBytes: number;
1497
1665
  }>>;
1498
- /** See `Dataset.describeStorage`. Reads the catalog only, in a fixed number of queries. */
1666
+ /**
1667
+ * See `Dataset.describeStorage`. Reads the catalog only, in a fixed number of
1668
+ * queries: the type's table, its indexes, and its `pending` and `orphaned`
1669
+ * fields, as the catalog records them.
1670
+ */
1499
1671
  describeStorage(type: string): Promise<TypeStorageReport>;
1500
1672
  /**
1501
1673
  * See `Dataset.storageReport`. Spans every namespace of the database. Reads
1502
- * the partition tree and every index on it in one query each, so its cost
1503
- * does not grow with the number of partitions.
1674
+ * the type tables and every index on them in one query each, so its cost
1675
+ * does not grow with the number of types.
1504
1676
  */
1505
1677
  storageReport(opts: {
1506
1678
  partitionBudget: number;
@@ -1524,12 +1696,11 @@ export declare class PgDataset implements Dataset {
1524
1696
  lockTimeoutMs?: number;
1525
1697
  }): Promise<void>;
1526
1698
  /**
1527
- * See `Dataset.dropNamespaceIndexes`. On legacy, the engine-owned partial
1528
- * indexes on `rows` scoped to this namespace; on partitioned, the
1529
- * engine-owned indexes on its type partitions, which a namespace drop
1530
- * empties but keeps. Unique ones only when `opts.unique`. Each table's under
1531
- * its index-build lock, CONCURRENTLY; the wait for that lock and each lock
1532
- * wait of a drop are bounded by `lockTimeoutMs` (default
1699
+ * See `Dataset.dropNamespaceIndexes`. The engine-owned indexes on this
1700
+ * namespace's type tables, which a namespace drop empties but keeps. Unique
1701
+ * ones only when `opts.unique`.
1702
+ * Each table's under its index-build lock, CONCURRENTLY; the wait for that
1703
+ * lock and each lock wait of a drop are bounded by `lockTimeoutMs` (default
1533
1704
  * `DROP_LOCK_TIMEOUT_MS`), past which it throws `index_drop_timeout`.
1534
1705
  */
1535
1706
  dropNamespaceIndexes(opts?: {
@@ -1540,11 +1711,17 @@ export declare class PgDataset implements Dataset {
1540
1711
  indexDeclarationOf(type: string, name: string): Promise<IndexDecl | undefined>;
1541
1712
  /**
1542
1713
  * See `Dataset.typeStats`. Spans every namespace of the database, in a fixed
1543
- * number of queries. Partitioned: each type partition's own statistics;
1544
- * `liveRows` is `reltuples` (or `n_live_tup` before the first ANALYZE) and
1545
- * counts tombstoned rows too. Legacy: see the shortcut below.
1714
+ * number of queries: each type table's own statistics; `liveRows` is
1715
+ * `reltuples` (or `n_live_tup` before the first ANALYZE) and counts
1716
+ * tombstoned rows too.
1546
1717
  */
1547
1718
  typeStats(): Promise<TypeStats[]>;
1719
+ /**
1720
+ * `fields` is the type's, which the caller looks up once however many rows it
1721
+ * builds. The row is decoded first; `requested`, a read's `fields`, then
1722
+ * trims the `$raw` entries `decodeRow` overlays, since the projection keeps
1723
+ * `$raw` whole.
1724
+ */
1548
1725
  private materialize;
1549
1726
  private extractOriginalId;
1550
1727
  }
@@ -1671,21 +1848,9 @@ export declare function publicLeftoverWarning(names: readonly string[], packageN
1671
1848
  * Call from `globalSetup`, so forked workers inherit the rewritten URL.
1672
1849
  */
1673
1850
  export declare function preparePgTestSchema(url: string | undefined, opts: SchemaIsolationOptions): Promise<string | undefined>;
1674
- /**
1675
- * The storage layout this run's pg suites build, from `SUBSTRATE_TEST_LAYOUT`
1676
- * (default `legacy`). Copies it into `SUBSTRATE_STORAGE_LAYOUT`, which
1677
- * `runMigrations` reads on a fresh database, and returns the package name to
1678
- * isolate under, so each layout gets a schema of its own.
1679
- *
1680
- * Call from `globalSetup`, before `preparePgTestSchema`.
1681
- */
1682
- export declare function selectPgTestLayout(packageName: string): {
1683
- layout: 'legacy' | 'partitioned';
1684
- packageName: string;
1685
- };
1686
1851
  /**
1687
1852
  * A `createSchema` for `preparePgTestSchema` that drops and recreates the
1688
- * schema, so every run builds its layout from an empty database.
1853
+ * schema, so every run builds its store from an empty database.
1689
1854
  */
1690
1855
  export declare function recreatePgTestSchema(url: string, schema: string): Promise<void>;
1691
1856
  //#endregion
package/dist/testing.js CHANGED
@@ -1,8 +1,8 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { G as loadPlugins, W as MemoryEdgesStore, _t as signHs256, c as MemoryDataset, s as compose, yt as WS_REASON_SERVER_RESTART } from "./src-5SJ5GEIM.js";
3
- import "./src-hZb8wfvg.js";
4
- import { l as deriveListIndexMigration, m as runMigrations, p as runDerivedMigrations, t as PgDataset } from "./src-CyvV7dCK.js";
5
- import { t as PgEdgesStore } from "./pg-edges-store-Lxsl5ZnK.js";
2
+ import { Mt as signHs256, Pt as WS_REASON_SERVER_RESTART, X as loadPlugins, Y as MemoryEdgesStore, c as MemoryDataset, s as compose } from "./src-C4t1Gy-m.js";
3
+ import "./src-DWqzrm3O.js";
4
+ import { _ as runDerivedMigrations, m as deriveListIndexMigration, t as PgDataset, v as runMigrations } from "./src-CSe2tJDf.js";
5
+ import { t as PgEdgesStore } from "./pg-edges-store-B4FSN9yp.js";
6
6
  import { t as FakeEmbedder } from "./fake-DUVtKVSE.js";
7
7
  import { randomUUID } from "node:crypto";
8
8
  import postgres from "postgres";
@@ -267,25 +267,8 @@ async function preparePgTestSchema(url, opts) {
267
267
  return pgTestSchemaUrl(url, opts.packageName);
268
268
  }
269
269
  /**
270
- * The storage layout this run's pg suites build, from `SUBSTRATE_TEST_LAYOUT`
271
- * (default `legacy`). Copies it into `SUBSTRATE_STORAGE_LAYOUT`, which
272
- * `runMigrations` reads on a fresh database, and returns the package name to
273
- * isolate under, so each layout gets a schema of its own.
274
- *
275
- * Call from `globalSetup`, before `preparePgTestSchema`.
276
- */
277
- function selectPgTestLayout(packageName) {
278
- const layout = process.env.SUBSTRATE_TEST_LAYOUT ?? "legacy";
279
- if (layout !== "legacy" && layout !== "partitioned") throw new Error(`SUBSTRATE_TEST_LAYOUT must be 'legacy' or 'partitioned', got '${layout}'`);
280
- process.env.SUBSTRATE_STORAGE_LAYOUT = layout;
281
- return {
282
- layout,
283
- packageName: `${packageName}-${layout}`
284
- };
285
- }
286
- /**
287
270
  * A `createSchema` for `preparePgTestSchema` that drops and recreates the
288
- * schema, so every run builds its layout from an empty database.
271
+ * schema, so every run builds its store from an empty database.
289
272
  */
290
273
  async function recreatePgTestSchema(url, schema) {
291
274
  const sql = postgres(url, {
@@ -735,4 +718,4 @@ var MemorySubstrateServer = class {
735
718
  };
736
719
 
737
720
  //#endregion
738
- export { AlreadyStartedError, FakeEmbedder, MemoryDataset, MemoryEdgesStore, MemorySubstrateServer, PgDataset, PgEdgesStore, UnknownWsPathError, WsClosedError, announcePgGating, assertCannotWriteOutsideTestDatabases, assertNotSuperuser, assertTestDatabase, compose, createMemoryWsPair, deriveListIndexMigration, interpretSuperuserProbe, loadPlugins, matchRoute, pgTestSchemaName, pgTestSchemaUrl, preparePgTestSchema, publicLeftoverWarning, reachFailureMessage, recreatePgTestSchema, runDerivedMigrations, runMigrations, selectPgTestLayout, signHs256 };
721
+ export { AlreadyStartedError, FakeEmbedder, MemoryDataset, MemoryEdgesStore, MemorySubstrateServer, PgDataset, PgEdgesStore, UnknownWsPathError, WsClosedError, announcePgGating, assertCannotWriteOutsideTestDatabases, assertNotSuperuser, assertTestDatabase, compose, createMemoryWsPair, deriveListIndexMigration, interpretSuperuserProbe, loadPlugins, matchRoute, pgTestSchemaName, pgTestSchemaUrl, preparePgTestSchema, publicLeftoverWarning, reachFailureMessage, recreatePgTestSchema, runDerivedMigrations, runMigrations, signHs256 };