@mnmal-ai/substrate 1.0.0-alpha.11 → 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 (38) hide show
  1. package/README.md +4 -2
  2. package/dist/{boot-store-C5vNZJ3i.js → boot-store-DHv9H1Gr.js} +165 -69
  3. package/dist/{bridge-COu0Tg_h.d.ts → bridge-DQyQ6Qhn.d.ts} +1 -1
  4. package/dist/{cli-BrwW4tjO.js → cli-_UNdneXr.js} +11 -9
  5. package/dist/client.d.ts +3 -3
  6. package/dist/client.js +3 -3
  7. package/dist/{errors-BOllGhVx.d.ts → errors-xP9Mo7Q1.d.ts} +25 -4
  8. package/dist/{index-Cp74OcmS.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-BLsbcXkk.js → pg-edges-store-B4FSN9yp.js} +72 -9
  12. package/dist/{plugin-DIYm2cZE.js → plugin-BLm5IRdX.js} +2 -2
  13. package/dist/proposals-bootstrap.js +2 -2
  14. package/dist/proposals.d.ts +2 -2
  15. package/dist/proposals.js +1 -1
  16. package/dist/recall-bootstrap.js +2 -2
  17. package/dist/recall.d.ts +10 -10
  18. package/dist/recall.js +2 -2
  19. package/dist/{repl-B8gy0YM7.js → repl-DUJGBwie.js} +25 -25
  20. package/dist/{row-DwaDU4b-.d.ts → row-Cu_iRhcR.d.ts} +2 -2
  21. package/dist/{run-B18qtGKc.js → run-BpsTNvdI.js} +520 -141
  22. package/dist/{schema-CijHRfuk.d.ts → schema-oXfQyo0s.d.ts} +272 -27
  23. package/dist/sdk.d.ts +93 -29
  24. package/dist/sdk.js +4 -4
  25. package/dist/{src-D041j6GS.js → src-Bew_JvTo.js} +32 -16
  26. package/dist/{src-DpPdw2oL.js → src-Bi3NhEsT.js} +1 -1
  27. package/dist/{src-DK7VEQT6.js → src-C4t1Gy-m.js} +2477 -830
  28. package/dist/{src-Br6aDUti.js → src-CHND7-Pm.js} +2 -2
  29. package/dist/src-CSe2tJDf.js +6940 -0
  30. package/dist/{src-DptNGNYQ.js → src-CzhKLsOV.js} +175 -91
  31. package/dist/{src-Dbvuel6w.js → src-DWqzrm3O.js} +18 -1
  32. package/dist/substrate-admin.js +1 -1
  33. package/dist/substrate.js +1 -1
  34. package/dist/testing.d.ts +233 -92
  35. package/dist/testing.js +6 -23
  36. package/dist/{ws-DC8OhMaV.d.ts → ws-Dx3A2B4U.d.ts} +2 -2
  37. package/package.json +19 -20
  38. package/dist/src-gz4I1F29.js +0 -5097
package/dist/testing.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { $ as PluginRouter, $t as WriteOptions, A as KernelPlugin, B as QualifiedFrame, Bt as ReadResult, Cn as Row, Dt as Dataset, En as WriteRow, Et as ConditionalUpdateResult, Gt as TypeStorageReport, H as RegistryBase, Ht as StorageReport, It as IndexPlan, Kt as UpdateFieldRef, N as NamespaceConfig, Ot as DatasetRegistry, Pt as FilterCapabilities, Q as HttpMethod, S as EngineInput, T as IndexDecl, U as RegistryEntry, Ut as TxScopeHandles, V as Registry$1, W as RegistryEntryInput, Z as HttpHandler, _ as CoordinatorPlugin, _n as ActorIdentity, _t as RequestContext, an as RuntimeErrors, at as SubstrateResponse, bn as Id, cn as TypeStats, ct as WsConnection, d as OrderedBy, dn as EdgePatch, en as WriteResult, f as PackEnvelope, fn as EdgeRef, ft as Identity, gt as PolicyProbeContext, ht as PolicyDecision, i as FieldDef, it as SubstrateRequest, jt as DropResult, kt as DeleteResult, ln as CanDeleteResult, lt as WsHandler, m as Schema, mn as EdgesStore, nn as ResolveObservation, nt as RuntimeOp, ot as SubstrateServer, pn as EdgeWriteInput, q as ScheduledTask, rn as ResolverStat, rt as StartOpts, sn as SlowRequest, tn as ProcessStat, tt as RequestObserver, un as Edge, v as DropParticipant, x as EngineHandle, yt as ResolverArgs, zt as ReadParams } from "./schema-CijHRfuk.js";
2
- import { a as WsResponseFrame, f as IdempotencyStore, l as SweepDeps, s as BridgeRegistry, u as SweepState } from "./ws-DC8OhMaV.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";
3
3
  import { t as Embedder } from "./types-8c0gtnd2.js";
4
4
  import { Sql, TransactionSql } from "postgres";
5
5
  //#region ../../packages/substrate-compose/src/auth.d.ts
@@ -276,6 +276,18 @@ interface EngineOptions {
276
276
  * the resolver took. For the index advisor; absent means no recording.
277
277
  */
278
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;
279
291
  /**
280
292
  * Idempotency dedup (§5.13). Absent → no dedup; `FrameEntry.idempotencyKey`
281
293
  * is ignored on mutate (queries ignore it unconditionally). Present → the
@@ -567,6 +579,17 @@ declare class Engine {
567
579
  * fanout — see subscribe.ts for the full contract.
568
580
  */
569
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[];
570
593
  /**
571
594
  * Live count of active subscription entries. Delegates to the
572
595
  * SubscribeSubsystem, which owns the authoritative map.
@@ -662,6 +685,8 @@ export declare class MemoryEdgesStore implements EdgesStore {
662
685
  */
663
686
  private nextId;
664
687
  write(input: EdgeWriteInput): Promise<Edge>;
688
+ writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
689
+ tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
665
690
  tombstone(id: string, at?: Date): Promise<void>;
666
691
  update(patch: EdgePatch): Promise<void>;
667
692
  readNextBatch(cursorId: string | null, size: number): Promise<{
@@ -671,6 +696,7 @@ export declare class MemoryEdgesStore implements EdgesStore {
671
696
  findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
672
697
  findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
673
698
  findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
699
+ findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
674
700
  canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
675
701
  findBlocked(): Promise<Edge[]>;
676
702
  findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
@@ -779,10 +805,12 @@ interface MemoryDatasetOptions {
779
805
  fieldDefLookup?: (type: string, field: string) => FieldDef | undefined;
780
806
  /**
781
807
  * The namespace's type definitions; a type declared `ordering: 'visible'`
782
- * 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`).
783
810
  */
784
811
  typeDefLookup?: (type: string, namespace: string) => {
785
812
  ordering?: 'visible';
813
+ fields?: Record<string, FieldDef>;
786
814
  } | undefined;
787
815
  /**
788
816
  * Internal: binding assignments one read's walks may try before refusing
@@ -820,6 +848,8 @@ export declare class MemoryDataset implements Dataset {
820
848
  */
821
849
  private walkContext;
822
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;
823
853
  tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
824
854
  purge(type: string, ids: Id[]): Promise<DeleteResult>;
825
855
  dropType(type: string): Promise<DropResult>;
@@ -852,6 +882,18 @@ export declare class MemoryDataset implements Dataset {
852
882
  allocateShortId(type: string): Promise<number>;
853
883
  bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
854
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>;
855
897
  getShortIdForRow(type: string, rowId: string): Promise<number | null>;
856
898
  forNamespace(namespace: string): Dataset;
857
899
  }
@@ -1027,6 +1069,12 @@ interface ComposeOpts {
1027
1069
  defaultLimit: number;
1028
1070
  maxLimit: number;
1029
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;
1030
1078
  /**
1031
1079
  * Opt-in periodic re-prime interval (ms) for the
1032
1080
  * `KeyRegistry` public-key cache. Bounds cross-instance revocation
@@ -1071,6 +1119,14 @@ interface ComposeOpts {
1071
1119
  storeProfile?: StoreProfileName;
1072
1120
  writeHeavy?: boolean;
1073
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
+ };
1074
1130
  }
1075
1131
  interface ComposeResult {
1076
1132
  engine: Engine;
@@ -1097,6 +1153,8 @@ interface ComposeResult {
1097
1153
  runAdvisorNow: (() => Promise<{
1098
1154
  upserted: number;
1099
1155
  }>) | null;
1156
+ /** Run one promotion sweep now, as the admin route does. */
1157
+ runPromoteFieldsNow: () => Promise<PromotionEvent[]>;
1100
1158
  /**
1101
1159
  * Non-null when any coordinator plugin contributed a `schedule`. The
1102
1160
  * composition root constructs the scheduler, registers every plugin's
@@ -1113,6 +1171,62 @@ interface ComposeResult {
1113
1171
  }
1114
1172
  export declare function compose(opts: ComposeOpts): Promise<ComposeResult>;
1115
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
1116
1230
  //#region ../../packages/substrate-dataset-pg/src/disk-guard.d.ts
1117
1231
  /**
1118
1232
  * Refuses a background index build that would leave less than a margin of
@@ -1132,21 +1246,7 @@ interface DiskGuard {
1132
1246
  }
1133
1247
  //#endregion
1134
1248
  //#region ../../packages/substrate-dataset-pg/src/layout.d.ts
1135
- type StorageLayout = 'legacy' | 'partitioned';
1136
- //#endregion
1137
- //#region ../../packages/substrate-dataset-pg/src/pg-sql/primitives.d.ts
1138
- /**
1139
- * A body key mirrored into a dedicated column on `rows`, so filters and
1140
- * sorts on it hit an index instead of extracting from JSONB.
1141
- *
1142
- * `column` is a BARE column name, not a qualified `r.<col>` fragment: taking a
1143
- * fragment from a caller would put caller text into `sql.unsafe`.
1144
- */
1145
- interface PromotedBodyColumn {
1146
- column: string;
1147
- kind: 'boolean' | 'text';
1148
- }
1149
- type PromotedBodyColumnMap = Readonly<Record<string, PromotedBodyColumn>>;
1249
+ type StorageLayout = 'tables';
1150
1250
  //#endregion
1151
1251
  //#region ../../packages/substrate-dataset-pg/src/migrate.d.ts
1152
1252
  /**
@@ -1183,12 +1283,6 @@ interface RunMigrationsOptions {
1183
1283
  * Production bootstraps shouldn't pass this — let the env decide.
1184
1284
  */
1185
1285
  enforceUuidCheck?: boolean;
1186
- /**
1187
- * The layout for a database with no `rows` yet. Ignored once `rows` exists,
1188
- * since a database keeps its layout. Defaults to `SUBSTRATE_STORAGE_LAYOUT`,
1189
- * then `partitioned`.
1190
- */
1191
- layout?: StorageLayout;
1192
1286
  }
1193
1287
  export declare function runMigrations(sql: Sql, opts?: RunMigrationsOptions): Promise<void>;
1194
1288
  /**
@@ -1202,7 +1296,9 @@ interface IndexedListField {
1202
1296
  }
1203
1297
  /**
1204
1298
  * Derives the tracked, idempotent CONCURRENTLY GIN migration for one indexed
1205
- * 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`.
1206
1302
  */
1207
1303
  export declare function deriveListIndexMigration(f: IndexedListField): MigrationInput;
1208
1304
  /**
@@ -1211,15 +1307,11 @@ export declare function deriveListIndexMigration(f: IndexedListField): Migration
1211
1307
  * since `runMigrations` has no field-def knowledge. Idempotent: applied
1212
1308
  * versions are skipped.
1213
1309
  *
1214
- * On the partitioned layout the list/json GIN migrations are skipped: those
1215
- * indexes live on each type's partition, built by `reconcileTypeIndexes`, and
1216
- * 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`).
1217
1312
  */
1218
1313
  export declare function runDerivedMigrations(sql: Sql, all: ReadonlyArray<MigrationInput>): Promise<void>;
1219
1314
  //#endregion
1220
- //#region ../../packages/substrate-dataset-pg/src/tx-scope.d.ts
1221
- type PgHandle = Sql | TransactionSql;
1222
- //#endregion
1223
1315
  //#region ../../packages/substrate-dataset-pg/src/pg-edges-store.d.ts
1224
1316
  interface PgEdgesStoreOptions {
1225
1317
  sql: Sql;
@@ -1247,6 +1339,8 @@ export declare class PgEdgesStore implements EdgesStore {
1247
1339
  readonly txScopeId: string;
1248
1340
  constructor(options: PgEdgesStoreOptions | InternalPgEdgesStoreOptions);
1249
1341
  write(input: EdgeWriteInput): Promise<Edge>;
1342
+ writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
1343
+ tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
1250
1344
  tombstone(id: string, at?: Date): Promise<void>;
1251
1345
  /**
1252
1346
  * Hard-deletes tombstoned edges whose `deleted_at` is older than
@@ -1264,6 +1358,7 @@ export declare class PgEdgesStore implements EdgesStore {
1264
1358
  }>;
1265
1359
  findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
1266
1360
  findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
1361
+ findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
1267
1362
  findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
1268
1363
  findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
1269
1364
  findEdgesTouchingType(namespace: string, type: string, limit: number): Promise<Edge[]>;
@@ -1342,25 +1437,6 @@ interface PgDatasetOptions {
1342
1437
  * expression; it needs a matching cast expression index.
1343
1438
  */
1344
1439
  fieldDefLookup?: FieldDefLookup;
1345
- /**
1346
- * Body keys mirrored into dedicated columns on `rows`, so filters and
1347
- * sorts on them use an index instead of extracting from JSONB.
1348
- *
1349
- * None by default. A namespace declares its own (`NamespaceDefinition`'s
1350
- * `promotedColumns`), and the plugin that declares them adds the columns in
1351
- * its kernel migrations: the engine creates none. Three things that bite:
1352
- *
1353
- * - Filters and sorts route to the column and ONLY the column, so a column
1354
- * added over existing rows must be backfilled from the body first, or
1355
- * those rows miss every filter. Reads return the body.
1356
- * - `column` is a BARE name (`'severity'`, not `'r.severity'`) and is
1357
- * validated as an identifier at construction, because it is interpolated
1358
- * into SQL as an identifier.
1359
- * - Text columns compare `COLLATE "C"` in every operator, eq included,
1360
- * so an index meant to serve them must key `(column COLLATE "C")`, as
1361
- * declared `indexes` do.
1362
- */
1363
- promotedColumns?: PromotedBodyColumnMap;
1364
1440
  /**
1365
1441
  * The namespace's type definitions, which `ensureTypeStorage` builds the
1366
1442
  * type's indexes from. Without it only the engine's own indexes are built.
@@ -1373,6 +1449,12 @@ interface PgDatasetOptions {
1373
1449
  * checked either, and `storageReport` says so.
1374
1450
  */
1375
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;
1376
1458
  }
1377
1459
  interface InternalPgSubstrateDatasetOptions {
1378
1460
  namespace: string;
@@ -1385,14 +1467,32 @@ interface InternalPgSubstrateDatasetOptions {
1385
1467
  txScopeId?: string;
1386
1468
  edgesStore?: PgEdgesStore;
1387
1469
  fieldDefLookup?: FieldDefLookup;
1388
- /** See `PgDatasetOptions.promotedColumns`. */
1389
- promotedColumns?: PromotedBodyColumnMap;
1390
1470
  /** Shared with the instance this one was derived from. */
1391
1471
  layoutCache?: LayoutCache;
1392
1472
  typeDefLookup?: TypeDefLookup;
1393
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;
1394
1479
  }
1395
- /** 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. */
1396
1496
  interface LayoutCache {
1397
1497
  layout?: StorageLayout;
1398
1498
  }
@@ -1403,10 +1503,12 @@ export declare class PgDataset implements Dataset {
1403
1503
  readonly txScopeId: string;
1404
1504
  constructor(options: PgDatasetOptions | InternalPgSubstrateDatasetOptions);
1405
1505
  /**
1406
- * The walk grammar (spec 2026-10-24-typed-edge-walks §3) runs on the
1407
- * partitioned layout only, and in a transaction under a `SET LOCAL`
1408
- * statement timeout, since pg has no walk evaluation budget. Other reads
1409
- * are unchanged.
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.
1410
1512
  */
1411
1513
  read(type: string, params: ReadParams): Promise<ReadResult>;
1412
1514
  /**
@@ -1428,14 +1530,16 @@ export declare class PgDataset implements Dataset {
1428
1530
  */
1429
1531
  write(type: string, rows: WriteRow[], options?: WriteOptions): Promise<WriteResult>;
1430
1532
  tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
1533
+ /** On a type table, `deleted` also leaves `row_ids`, and `short_ids` cascade from there. */
1431
1534
  purge(type: string, ids: Id[]): Promise<DeleteResult>;
1432
1535
  /**
1433
1536
  * Hard-deletes tombstoned rows whose `deleted_at` is older than `olderThan`,
1434
1537
  * across ALL namespaces (the table is substrate-shared). Called by the sweep
1435
1538
  * loop. Returns the number of rows deleted.
1436
1539
  *
1437
- * Short-id mappings are left in place, as in `purge()`: a row id can
1438
- * 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.
1439
1543
  */
1440
1544
  purgeTombstonedRows(opts: {
1441
1545
  olderThan: Date;
@@ -1446,7 +1550,8 @@ export declare class PgDataset implements Dataset {
1446
1550
  * Hard-delete every row for `type` in this namespace, including tombstoned
1447
1551
  * rows (`deleted_at IS NOT NULL`). Short-id mappings for that type are
1448
1552
  * removed in the same logical operation. Both deletes run through `this.#sql`
1449
- * 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.
1450
1555
  */
1451
1556
  dropType(type: string): Promise<DropResult>;
1452
1557
  /**
@@ -1496,20 +1601,59 @@ export declare class PgDataset implements Dataset {
1496
1601
  allocateShortId(type: string): Promise<number>;
1497
1602
  bindShortId(type: string, shortId: number, rowId: string): Promise<void>;
1498
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>;
1499
1616
  getShortIdForRow(type: string, rowId: string): Promise<number | null>;
1500
1617
  forNamespace(namespace: string): Dataset;
1501
1618
  /**
1502
- * See `Dataset.ensureTypeStorage`. On the partitioned layout, creates this
1503
- * namespace's partition and the type's, then reconciles the type's indexes
1504
- * on it; on legacy, reconciles only its declared `indexes`. Index builds
1505
- * run CONCURRENTLY, outside any transaction, so a tx-bound instance refuses.
1506
- * Logs each index it created, adopted or swapped, and records each one
1507
- * 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`.
1508
1628
  */
1509
1629
  ensureTypeStorage(type: string, opts?: {
1510
1630
  indexes?: 'all' | 'unique' | 'nonUnique';
1511
1631
  signal?: AbortSignal;
1512
- }): 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[]>;
1513
1657
  /**
1514
1658
  * The type's non-unique indexes the next build pass would build or swap,
1515
1659
  * each with the disk guard's estimate. Empty when the store or the type's
@@ -1519,12 +1663,16 @@ export declare class PgDataset implements Dataset {
1519
1663
  name: string;
1520
1664
  estimateBytes: number;
1521
1665
  }>>;
1522
- /** 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
+ */
1523
1671
  describeStorage(type: string): Promise<TypeStorageReport>;
1524
1672
  /**
1525
1673
  * See `Dataset.storageReport`. Spans every namespace of the database. Reads
1526
- * the partition tree and every index on it in one query each, so its cost
1527
- * 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.
1528
1676
  */
1529
1677
  storageReport(opts: {
1530
1678
  partitionBudget: number;
@@ -1548,12 +1696,11 @@ export declare class PgDataset implements Dataset {
1548
1696
  lockTimeoutMs?: number;
1549
1697
  }): Promise<void>;
1550
1698
  /**
1551
- * See `Dataset.dropNamespaceIndexes`. On legacy, the engine-owned partial
1552
- * indexes on `rows` scoped to this namespace; on partitioned, the
1553
- * engine-owned indexes on its type partitions, which a namespace drop
1554
- * empties but keeps. Unique ones only when `opts.unique`. Each table's under
1555
- * its index-build lock, CONCURRENTLY; the wait for that lock and each lock
1556
- * 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
1557
1704
  * `DROP_LOCK_TIMEOUT_MS`), past which it throws `index_drop_timeout`.
1558
1705
  */
1559
1706
  dropNamespaceIndexes(opts?: {
@@ -1564,11 +1711,17 @@ export declare class PgDataset implements Dataset {
1564
1711
  indexDeclarationOf(type: string, name: string): Promise<IndexDecl | undefined>;
1565
1712
  /**
1566
1713
  * See `Dataset.typeStats`. Spans every namespace of the database, in a fixed
1567
- * number of queries. Partitioned: each type partition's own statistics;
1568
- * `liveRows` is `reltuples` (or `n_live_tup` before the first ANALYZE) and
1569
- * 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.
1570
1717
  */
1571
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
+ */
1572
1725
  private materialize;
1573
1726
  private extractOriginalId;
1574
1727
  }
@@ -1695,21 +1848,9 @@ export declare function publicLeftoverWarning(names: readonly string[], packageN
1695
1848
  * Call from `globalSetup`, so forked workers inherit the rewritten URL.
1696
1849
  */
1697
1850
  export declare function preparePgTestSchema(url: string | undefined, opts: SchemaIsolationOptions): Promise<string | undefined>;
1698
- /**
1699
- * The storage layout this run's pg suites build, from `SUBSTRATE_TEST_LAYOUT`
1700
- * (default `legacy`). Copies it into `SUBSTRATE_STORAGE_LAYOUT`, which
1701
- * `runMigrations` reads on a fresh database, and returns the package name to
1702
- * isolate under, so each layout gets a schema of its own.
1703
- *
1704
- * Call from `globalSetup`, before `preparePgTestSchema`.
1705
- */
1706
- export declare function selectPgTestLayout(packageName: string): {
1707
- layout: 'legacy' | 'partitioned';
1708
- packageName: string;
1709
- };
1710
1851
  /**
1711
1852
  * A `createSchema` for `preparePgTestSchema` that drops and recreates the
1712
- * schema, so every run builds its layout from an empty database.
1853
+ * schema, so every run builds its store from an empty database.
1713
1854
  */
1714
1855
  export declare function recreatePgTestSchema(url: string, schema: string): Promise<void>;
1715
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 { Ct as signHs256, G as loadPlugins, Tt as WS_REASON_SERVER_RESTART, W as MemoryEdgesStore, c as MemoryDataset, s as compose } from "./src-DK7VEQT6.js";
3
- import "./src-Dbvuel6w.js";
4
- import { l as deriveListIndexMigration, m as runMigrations, p as runDerivedMigrations, t as PgDataset } from "./src-gz4I1F29.js";
5
- import { t as PgEdgesStore } from "./pg-edges-store-BLsbcXkk.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 };
@@ -1,5 +1,5 @@
1
- import { Ot as DatasetRegistry, bn as Id, f as PackEnvelope, fn as EdgeRef, l as FieldInput, mn as EdgesStore } from "./schema-CijHRfuk.js";
2
- import { t as BridgeClient } from "./bridge-COu0Tg_h.js";
1
+ import { Cn as EdgesStore, Nt as DatasetRegistry, f as PackEnvelope, kn as Id, l as FieldInput, xn as EdgeRef } from "./schema-oXfQyo0s.js";
2
+ import { t as BridgeClient } from "./bridge-DQyQ6Qhn.js";
3
3
  //#region ../../packages/substrate-types/src/idempotency.d.ts
4
4
  interface IdempotencyStore {
5
5
  /**