@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
@@ -109,7 +109,18 @@ interface EdgesStore {
109
109
  */
110
110
  readonly txScopeId: string;
111
111
  write(input: EdgeWriteInput): Promise<Edge>;
112
+ /**
113
+ * `write` for many inputs, returned in input order (pg: one multi-row
114
+ * INSERT whatever the count). Empty `inputs` returns `[]` and sends nothing.
115
+ */
116
+ writeMany(inputs: readonly EdgeWriteInput[]): Promise<Edge[]>;
112
117
  tombstone(id: string, at?: Date): Promise<void>;
118
+ /**
119
+ * `tombstone` for many ids with one stamp (pg: one statement). Unknown and
120
+ * already-tombstoned ids are skipped, the latter keeping their first stamp.
121
+ * Empty `ids` does nothing and sends nothing.
122
+ */
123
+ tombstoneMany(ids: readonly string[], at?: Date): Promise<void>;
113
124
  update(patch: EdgePatch): Promise<void>;
114
125
  readNextBatch(cursorId: string | null, size: number): Promise<{
115
126
  edges: Edge[];
@@ -123,6 +134,11 @@ interface EdgesStore {
123
134
  */
124
135
  findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
125
136
  findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
137
+ /**
138
+ * Batched `findEdgesFrom`: all live outbound edges whose `from` matches ANY
139
+ * of `refs`, in a single round-trip, as `findEdgesToMany` does for `to`.
140
+ */
141
+ findEdgesFromMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
126
142
  canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
127
143
  findBlocked(): Promise<Edge[]>;
128
144
  /**
@@ -225,6 +241,18 @@ interface ResolveObservation {
225
241
  message?: string;
226
242
  /** The verified identity's id; absent for an anonymous caller. */
227
243
  caller?: string;
244
+ /**
245
+ * Set when the element ran in a batch resolver call: the number of elements
246
+ * in that call. `durationMs` is then the whole call's time, shared by all of
247
+ * them. Absent for a per-element resolve.
248
+ */
249
+ batchSize?: number;
250
+ /**
251
+ * The element's position (0..batchSize-1) in its batch call; set with
252
+ * `batchSize`. Latency aggregates take a batch once, from index 0, so one
253
+ * call's time is not counted batchSize times. Call counts take every element.
254
+ */
255
+ batchIndex?: number;
228
256
  }
229
257
  /**
230
258
  * One type's table and index statistics, for the index advisor. Counters are
@@ -535,6 +563,33 @@ interface DeleteResult {
535
563
  deleted: number;
536
564
  ids: Id[];
537
565
  }
566
+ /** Options of `Dataset.updateWhere` / `deleteWhere`. */
567
+ interface FilterWriteOptions {
568
+ /** Most rows the filter may match; one more refuses the write with `filter_too_broad`. */
569
+ maxMatch: number;
570
+ /** Stamped as `updatedBy` (update only); the anonymous system actor when absent. */
571
+ actor?: ActorIdentity;
572
+ /** Stamped as `updatedAt` (update only); the clock when absent. */
573
+ now?: Date;
574
+ }
575
+ /**
576
+ * What a by-filter write changed: every changed id, and the changed rows
577
+ * (post-images for an update, pre-images for a delete). Both are bounded by
578
+ * `maxMatch`.
579
+ */
580
+ interface FilterWriteResult {
581
+ count: number;
582
+ ids: Id[];
583
+ rows: Row[];
584
+ }
585
+ /** The caps on `updateMany<T>` / `deleteMany<T>`. */
586
+ interface FilterWriteLimits {
587
+ /** Most rows one filter may match (`SUBSTRATE_FILTER_WRITE_MAX_MATCH`). */
588
+ maxMatch: number;
589
+ /** Most ids one result returns (`SUBSTRATE_FILTER_WRITE_IDS_CAP`). */
590
+ idsCap: number;
591
+ }
592
+ declare const DEFAULT_FILTER_WRITE_LIMITS: Readonly<FilterWriteLimits>;
538
593
  interface DropResult {
539
594
  /** Number of rows physically removed. */
540
595
  rowsDeleted: number;
@@ -625,7 +680,7 @@ interface Dataset {
625
680
  * Physically delete every row AND short-id for `this.namespace`, across
626
681
  * every type. Equivalent to calling `dropType` for each distinct type
627
682
  * seen in storage, but substrate impls SHOULD use a single bulk DELETE
628
- * where available (pg: `DELETE FROM rows WHERE namespace = $1`).
683
+ * where available (pg: one DELETE per type table).
629
684
  *
630
685
  * Same atomicity rules as `dropType`. Same "ignores archived state".
631
686
  */
@@ -639,8 +694,9 @@ interface Dataset {
639
694
  *
640
695
  * Semantics:
641
696
  * - Equality is strict (`===`) for scalars; `Date` compares by
642
- * `.getTime()`; `null` matches only a stored `null` (including
643
- * intentionally-null fields set via `updateField`), never an absent field.
697
+ * `.getTime()`; `null` matches a stored `null` or an absent field, on both
698
+ * datasets. A declared scalar or crossRef set to `null` reads back absent
699
+ * (`isColumnField`), so it matches `null` all the same.
644
700
  * - A missing row fails the match even when `match` is empty — the
645
701
  * operation is "update this existing row if predicate holds".
646
702
  * - `updates` is merged onto the stored row the same way `write()` upserts
@@ -692,12 +748,21 @@ interface Dataset {
692
748
  * rest `pending`, for a later `nonUnique` call to build. `signal` cancels an
693
749
  * in-flight non-unique build, which the next call retries. Default `all`.
694
750
  *
751
+ * On a store keeping each type in a table of its own, also brings that
752
+ * table in line with the type's declared fields: a newly declared field gets
753
+ * its column, or, with `newFields: 'pending'`, is recorded `pending` for a
754
+ * background sweep to add. Resolves with the fields that went `pending` in
755
+ * this call; a store without such tables resolves `{ pending: [] }`.
756
+ *
695
757
  * OPTIONAL. Backends without per-type storage omit it.
696
758
  */
697
759
  ensureTypeStorage?(type: string, opts?: {
698
760
  indexes?: 'all' | 'unique' | 'nonUnique';
699
761
  signal?: AbortSignal;
700
- }): Promise<void>;
762
+ newFields?: 'column' | 'pending';
763
+ }): Promise<{
764
+ pending: string[];
765
+ }>;
701
766
  /**
702
767
  * Where `type`'s rows live and how its declared indexes stand, read from the
703
768
  * catalog without building anything.
@@ -705,13 +770,45 @@ interface Dataset {
705
770
  * OPTIONAL. Backends without per-type storage omit it.
706
771
  */
707
772
  describeStorage?(type: string): Promise<TypeStorageReport>;
773
+ /**
774
+ * Gives each `pending` field of every namespace its column and moves its
775
+ * values out of jsonb, and finishes each `promoting` one, a field at a time.
776
+ * DDL waits at most `lockTimeoutMs` for its table's lock, then that field is
777
+ * `busy` and retried by the next call; `batchRows` rows move per statement.
778
+ * `signal` stops the sweep between steps. Resolves with one event per field
779
+ * it touched. A field that failed on a unique conflict waits for its type's
780
+ * catalog to change, unless `retryConflicts` is set.
781
+ *
782
+ * OPTIONAL. Backends with no per-type tables omit it.
783
+ */
784
+ promotePendingFields?(opts: {
785
+ lockTimeoutMs: number;
786
+ batchRows: number;
787
+ signal?: AbortSignal;
788
+ /** Retries fields a unique conflict holds back until their type's catalog changes: an operator's run after fixing the data. */
789
+ retryConflicts?: boolean;
790
+ /**
791
+ * The store has no other writers (migrate-store's target): a field's move
792
+ * to its column waits for its table lock, so a blocking autovacuum is
793
+ * cancelled, rather than retrying without queueing in front of writers.
794
+ */
795
+ noWriters?: boolean;
796
+ }): Promise<PromotionEvent[]>;
797
+ /**
798
+ * Store-wide counts of the fields an operator should know about: held in
799
+ * jsonb until promoted, whose promotion failed, and no longer declared with
800
+ * their column kept. Counts only, with no namespace, type, field or error
801
+ * text, since `/health` shows it unauthenticated; `storageReport` names them.
802
+ *
803
+ * OPTIONAL. Backends with no per-type tables omit it.
804
+ */
805
+ fieldWarnings?(): Promise<string[]>;
708
806
  /**
709
807
  * The database-wide storage layout and what an operator should look at:
710
- * rows parked in DEFAULT partitions, indexes and CHECK constraints on the
711
- * `rows` parent, indexes this process has yet to build or failed to build,
712
- * and a partition count over `partitionBudget`; and, as `info`, engine
713
- * indexes no longer declared and open index recommendations. Never changes
714
- * anything.
808
+ * indexes this process has yet to build or failed to build, fields whose
809
+ * promotion failed, and a type-table count over `partitionBudget`; and, as
810
+ * `info`, engine indexes no longer declared, pending and orphaned fields,
811
+ * and open index recommendations. Never changes anything.
715
812
  *
716
813
  * OPTIONAL. Backends without per-type storage omit it.
717
814
  */
@@ -855,6 +952,62 @@ interface Dataset {
855
952
  * callers chain their own `read()` after resolution.
856
953
  */
857
954
  resolveShortId(type: string, shortId: number): Promise<string | null>;
955
+ /**
956
+ * `count` fresh short ids for `type`, ascending, in one call (pg: one
957
+ * statement whatever `count`). Like `allocateShortId`, binds nothing.
958
+ * `count` of 0 returns `[]` and sends nothing.
959
+ */
960
+ allocateShortIds(type: string, count: number): Promise<number[]>;
961
+ /**
962
+ * `bindShortId` for many pairs at once (pg: one statement). Idempotent per
963
+ * pair, as `bindShortId` is. An empty `pairs` does nothing and sends nothing.
964
+ */
965
+ bindShortIds(type: string, pairs: ReadonlyArray<{
966
+ shortId: number;
967
+ rowId: string;
968
+ }>): Promise<void>;
969
+ /**
970
+ * Set-wise `resolveShortId` for the LIVE rows among `shortIds` (pg: one
971
+ * statement). A short id with no binding, or whose row is tombstoned or
972
+ * purged, is absent from the map: the answer `resolveShortId` then a live
973
+ * `read` gives, which is how callers resolve today. Repeats in `shortIds`
974
+ * are deduped. An empty `shortIds` returns an empty map and sends nothing.
975
+ */
976
+ resolveShortIds(type: string, shortIds: readonly number[]): Promise<ReadonlyMap<number, string>>;
977
+ /**
978
+ * Multi-row `update`: merges each patch into its LIVE row with today's
979
+ * semantics (a key absent from the patch keeps its value, `null` clears it;
980
+ * `id` and `_deletedAt` keys are ignored), stamps `updatedAt` = `now` and
981
+ * `updatedBy` = `actor` (the anonymous system actor when `null`), as
982
+ * `conditionalUpdate` does. pg runs one statement whatever the batch size.
983
+ *
984
+ * The result has one entry per patch, in order: the merged row, or `null`
985
+ * when `id` is not live. It never revives a tombstoned row or re-creates a
986
+ * purged one.
987
+ *
988
+ * A repeated `id` is allowed: its patches apply in input order (later keys
989
+ * win, as sequential patches would) and every slot for that id holds the
990
+ * final merged row. An empty `patches` returns `[]` and sends nothing.
991
+ */
992
+ patchRows(type: string, patches: ReadonlyArray<{
993
+ id: Id;
994
+ patch: Record<string, unknown>;
995
+ }>, actor: ActorIdentity | null, now: Date): Promise<Array<Row | null>>;
996
+ /**
997
+ * Update every live row of `type` matching `where`: merges `set` into each,
998
+ * as `patchRows` does, and stamps `updatedAt` / `updatedBy`. When more than
999
+ * `opts.maxMatch` rows match it throws `ResolverFrameError('filter_too_broad')`
1000
+ * and changes nothing; zero matches is `{ count: 0 }`. pg runs one
1001
+ * statement, which locks the matched rows and re-tests `where` on each, so
1002
+ * a row a concurrent writer moved out of the filter is not updated.
1003
+ */
1004
+ updateWhere?(type: string, where: WhereClause, set: Record<string, unknown>, opts: FilterWriteOptions): Promise<FilterWriteResult>;
1005
+ /**
1006
+ * Tombstone every live row of `type` matching `where`, under the same cap
1007
+ * and lock as `updateWhere`. `rows` are the pre-images. Checks no edges:
1008
+ * the caller gates `restrict` and rolls back.
1009
+ */
1010
+ deleteWhere?(type: string, where: WhereClause, opts: FilterWriteOptions): Promise<FilterWriteResult>;
858
1011
  /**
859
1012
  * Inverse of `resolveShortId` — look up the short id assigned to a
860
1013
  * given row id. Returns null if no sidecar entry exists (e.g. rows written
@@ -923,15 +1076,35 @@ interface TypeIndexState {
923
1076
  /** Why a `pending` index was not built: the free-disk check refused it. */
924
1077
  reason?: 'insufficient_disk';
925
1078
  }
926
- /** Where a type's rows live: `partition` is set on the partitioned layout once the type has one. */
1079
+ /** Where a type's rows live: `table` is set once the type has its table. */
927
1080
  interface TypeStorageReport {
928
- layout: 'legacy' | 'partitioned';
929
- partition?: string;
1081
+ layout: 'tables';
1082
+ table?: string;
930
1083
  indexes: TypeIndexState[];
1084
+ /** Declared fields whose values live in `extra` until they get a column. */
1085
+ pending?: string[];
1086
+ /** Fields no longer declared whose columns are kept. */
1087
+ orphaned?: string[];
1088
+ }
1089
+ /**
1090
+ * One field's outcome in a promotion sweep (`Dataset.promotePendingFields`):
1091
+ * `promoted` (it has its column and every value moved), `busy` (its table's
1092
+ * lock was held past the timeout; retried next sweep) or `failed` (an error,
1093
+ * or the third busy attempt in a row). `attempts` counts this one. A field
1094
+ * another process is sweeping is `busy` with the error `held by another
1095
+ * process`, and its `attempts` is the recorded count, unchanged.
1096
+ */
1097
+ interface PromotionEvent {
1098
+ kind: 'promoted' | 'busy' | 'failed';
1099
+ namespace: string;
1100
+ type: string;
1101
+ field: string;
1102
+ attempts: number;
1103
+ error?: string;
931
1104
  }
932
1105
  interface StorageReport {
933
1106
  /** `unknown` when the report itself failed. */
934
- layout: 'legacy' | 'partitioned' | 'unknown';
1107
+ layout: 'tables' | 'unknown';
935
1108
  warnings: string[];
936
1109
  /** Worth showing, not a fault: the doctor prints these without failing. */
937
1110
  info?: string[];
@@ -1083,6 +1256,8 @@ interface ResolverArgs {
1083
1256
  * transactions (a concurrent index drop) refuses to share one.
1084
1257
  */
1085
1258
  txEntries?: number;
1259
+ /** Engine-injected on `updateMany<T>` / `deleteMany<T>`: the deployment's caps. */
1260
+ filterWriteLimits?: FilterWriteLimits;
1086
1261
  }
1087
1262
  /**
1088
1263
  * Post-commit write announcement consumed by the engine's subscription bus
@@ -1314,9 +1489,17 @@ type PostWriteHook = (row: Row, ctx: RequestContext) => Promise<void>;
1314
1489
  * want the canonical alias should import `Resolver` from this package.
1315
1490
  */
1316
1491
  type RegistryEntryResolver = (ctx: RequestContext, args: ResolverArgs) => Promise<Row | Row[] | ReadResult | AsyncIterable<Row> | null> | AsyncIterable<Row>;
1492
+ /**
1493
+ * Set-wise resolver for a mutate array: one call for every uncached element,
1494
+ * in order, returning one entry per element. Throw `BatchElementError(i, cause)`
1495
+ * to refuse element `i`; any throw rolls back the whole array.
1496
+ */
1497
+ type BatchResolver = (ctx: RequestContext, args: readonly ResolverArgs[]) => Promise<Array<Row | null>>;
1317
1498
  /** Input shape for `Registry.register` / `Registry.replace`. */
1318
1499
  interface RegistryEntryInput {
1319
1500
  resolver: RegistryEntryResolver;
1501
+ /** When present, a mutate array calls this once instead of `resolver` per element. */
1502
+ batch?: BatchResolver;
1320
1503
  policy?: Policy;
1321
1504
  fields?: Record<string, FieldDef>;
1322
1505
  kind?: RegistryEntryKind;
@@ -1335,6 +1518,11 @@ interface RegistryEntryInput {
1335
1518
  * string matching. Omit for type entries and custom mutations.
1336
1519
  */
1337
1520
  verb?: AutoCrudVerb;
1521
+ /**
1522
+ * The type a by-filter mutation (`updateMany<T>` / `deleteMany<T>`) writes.
1523
+ * The engine validates `params.where` against it as a query's `where`.
1524
+ */
1525
+ filterTarget?: string;
1338
1526
  }
1339
1527
  /**
1340
1528
  * Stored shape returned by `Registry.get` and `Registry.all`. Mirrors the
@@ -1344,6 +1532,8 @@ interface RegistryEntryInput {
1344
1532
  */
1345
1533
  interface RegistryEntry {
1346
1534
  resolver: RegistryEntryResolver;
1535
+ /** Mirrors `RegistryEntryInput.batch`. */
1536
+ batch?: BatchResolver;
1347
1537
  policy: Policy;
1348
1538
  fields: Record<string, FieldDef>;
1349
1539
  kind: RegistryEntryKind;
@@ -1359,6 +1549,8 @@ interface RegistryEntry {
1359
1549
  expectedSize?: 'small' | 'large';
1360
1550
  /** Mirrors `RegistryEntryInput.verb` — present when the registrant stamped one. */
1361
1551
  verb?: AutoCrudVerb;
1552
+ /** Mirrors `RegistryEntryInput.filterTarget`. */
1553
+ filterTarget?: string;
1362
1554
  }
1363
1555
  /**
1364
1556
  * Canonical per-namespace registry surface, implemented by the concrete
@@ -1591,10 +1783,10 @@ interface NamespaceDefinition {
1591
1783
  */
1592
1784
  annotations?: Readonly<Record<string, unknown>>;
1593
1785
  /**
1594
- * Body keys a SQL dataset mirrors into dedicated `rows` columns, so filters
1595
- * and sorts on them hit an index. The declaring plugin creates the columns in
1596
- * its kernel migrations; the engine creates none. `column` is a bare
1597
- * identifier.
1786
+ * @deprecated Ignored. Every declared scalar is a column of its type's
1787
+ * table, so there is nothing left to promote. It was the old layouts' body
1788
+ * keys mirrored into dedicated `rows` columns; it still type-checks, so a
1789
+ * plugin that sets it boots unchanged.
1598
1790
  */
1599
1791
  promotedColumns?: Readonly<Record<string, {
1600
1792
  column: string;
@@ -1700,6 +1892,25 @@ interface NamespaceConfig {
1700
1892
  /** From `NamespaceDefinition.annotations`; surfaced on the schema, never hashed. */
1701
1893
  annotations?: Readonly<Record<string, unknown>>;
1702
1894
  }
1895
+ /**
1896
+ * What a coordinator's `onCommittedWrites` hook is told: one `(namespace, type,
1897
+ * operation)` group of one committed transaction. `ids` keep the order the
1898
+ * writes were emitted in. `actor` is who the request was attributed to, or
1899
+ * null for a request with no recognisable identity.
1900
+ */
1901
+ interface CommittedWriteBatch {
1902
+ namespace: string;
1903
+ type: string;
1904
+ operation: 'create' | 'update' | 'delete';
1905
+ actor: ActorIdentity | null;
1906
+ ids: readonly Id[];
1907
+ }
1908
+ /**
1909
+ * Never awaited by the mutate, so keep its synchronous part cheap. A throw or a
1910
+ * rejection is recorded as a `/health` warning (plugin name and time, not the
1911
+ * message) and does not touch the write.
1912
+ */
1913
+ type CommittedWritesHook = (batch: CommittedWriteBatch) => void | Promise<void>;
1703
1914
  /**
1704
1915
  * Narrow engine handle threaded into scheduled-task / plugin-route contexts.
1705
1916
  * The concrete `Engine` class in `@mnmal-ai/substrate-core` satisfies this
@@ -1709,6 +1920,14 @@ interface NamespaceConfig {
1709
1920
  interface EngineHandle {
1710
1921
  query(input: EngineInput): Promise<PackEnvelope>;
1711
1922
  mutate(input: EngineInput): Promise<PackEnvelope>;
1923
+ /**
1924
+ * Announce writes that were committed outside `mutate`: they reach
1925
+ * subscribers, then every coordinator's `onCommittedWrites`, as a commit
1926
+ * through `mutate` would. This is not a transaction and checks nothing: the
1927
+ * caller guarantees `events` are already committed, since an announced write
1928
+ * that rolls back cannot be taken back.
1929
+ */
1930
+ announceWrites(events: readonly WriteEvent[], actor: ActorIdentity | null): Promise<void>;
1712
1931
  /**
1713
1932
  * Evaluate the read policy for a type entry without dispatching it.
1714
1933
  * Out-of-band read surfaces (kernel routes returning row data
@@ -1872,6 +2091,12 @@ interface CoordinatorPlugin {
1872
2091
  * `NamespaceInstallContext.pluginPolicy`.
1873
2092
  */
1874
2093
  policies?: Policy[];
2094
+ /**
2095
+ * Told what each committed transaction wrote, once per `(namespace, type,
2096
+ * operation)` rather than once per row. Never awaited by the mutate, run in
2097
+ * commit order per plugin; a slow hook delays only this plugin's later calls.
2098
+ */
2099
+ onCommittedWrites?: CommittedWritesHook;
1875
2100
  /**
1876
2101
  * Post-register lifecycle hook. Fires after every plugin's `install()`
1877
2102
  * resolves — use this for resource priming that needs the full namespace
@@ -2030,12 +2255,12 @@ interface KernelMigrationContext {
2030
2255
  */
2031
2256
  sql: unknown | null;
2032
2257
  /**
2033
- * How `rows` is stored: `'partitioned'` (LIST(namespace) then LIST(type)) or
2034
- * `'legacy'` (one plain table). `null` on the in-memory dataset. PG refuses
2035
- * a unique index on a partitioned parent unless it includes every partition
2036
- * key column (`namespace`, `type`), so such DDL on `rows` must branch on this.
2258
+ * How rows are stored: `'tables'`, one table per type and no `rows` table,
2259
+ * the only layout a store boots. `null` on the in-memory dataset. A
2260
+ * migration that still runs DDL on `rows` fails, and the host names its
2261
+ * plugin (`KernelMigrationLayoutError`).
2037
2262
  */
2038
- layout: 'legacy' | 'partitioned' | null;
2263
+ layout: 'tables' | null;
2039
2264
  metric(name: string, payload?: unknown): void;
2040
2265
  }
2041
2266
  /**
@@ -2183,6 +2408,12 @@ interface PlanClause {
2183
2408
  kind: 'hop' | 'filter' | 'order' | 'ref' | 'derive' | 'bucket' | 'agg';
2184
2409
  served: boolean;
2185
2410
  recommend?: IndexDecl;
2411
+ /**
2412
+ * On the hop of a pick or a frame `_agg`: how the store evaluates it.
2413
+ * `per-seed` probes once per seed row; `per-hub` computes a pick once per
2414
+ * hub many seeds share; `group-by` aggregates a window in one pass.
2415
+ */
2416
+ form?: 'per-seed' | 'per-hub' | 'group-by';
2186
2417
  }
2187
2418
  /** Words of a natural-language question the parse did not use, and why. */
2188
2419
  interface Dropped {
@@ -2213,7 +2444,11 @@ interface FieldDefScalar {
2213
2444
  * `false`.
2214
2445
  */
2215
2446
  indexed?: boolean;
2216
- /** Metadata: when true, consumers SHOULD expect `null` as a legitimate value. */
2447
+ /**
2448
+ * Metadata: when true, the value may be unset. A string, number, boolean or
2449
+ * date reads back as an absent key then, never `null` (`isColumnField`); a
2450
+ * `json` field keeps an explicit `null`.
2451
+ */
2217
2452
  nullable?: boolean;
2218
2453
  /**
2219
2454
  * Metadata: when true, this field is populated by the engine (not the caller)
@@ -2295,7 +2530,10 @@ interface FieldDefCrossRef {
2295
2530
  * presence of the crossRef itself.
2296
2531
  */
2297
2532
  indexed?: boolean;
2298
- /** Metadata: when true, consumers SHOULD expect `null` as a legitimate value. */
2533
+ /**
2534
+ * Metadata: when true, the value may be unset. An unset field reads back as an
2535
+ * absent key, never `null` (`isColumnField`).
2536
+ */
2299
2537
  nullable?: boolean;
2300
2538
  /**
2301
2539
  * Activation-spreading opt-in. When `spread: true`,
@@ -2327,7 +2565,7 @@ interface FieldDefCrossRef {
2327
2565
  interface FieldDefStruct {
2328
2566
  kind: 'struct';
2329
2567
  fields: Record<string, FieldDef>;
2330
- /** Metadata: when true, consumers SHOULD expect `null` as a legitimate value. */
2568
+ /** Metadata: when true, the value may be `null` or absent. */
2331
2569
  nullable?: boolean;
2332
2570
  }
2333
2571
  interface FieldDefList {
@@ -2342,10 +2580,17 @@ interface FieldDefList {
2342
2580
  * migration is needed per field.
2343
2581
  */
2344
2582
  indexed?: boolean;
2345
- /** Metadata: when true, consumers SHOULD expect `null` as a legitimate value. */
2583
+ /** Metadata: when true, the value may be `null` or absent. */
2346
2584
  nullable?: boolean;
2347
2585
  }
2348
2586
  type FieldDef = FieldDefScalar | FieldDefCrossRef | FieldDefStruct | FieldDefList;
2587
+ /**
2588
+ * True when the field's value is a typed column: a scalar other than `json` that
2589
+ * the server does not own, or a crossRef. An explicit `null` on such a field
2590
+ * reads back as absent. A json, struct or list field keeps its `null`, and a
2591
+ * readonly scalar such as `shortId` is the server's.
2592
+ */
2593
+ declare function isColumnField(def: FieldDef): boolean;
2349
2594
  /**
2350
2595
  * Per-type schema entry. Fields may be declared at registration time; MVP emits
2351
2596
  * `fields: {}` for types registered without a field map (e.g. mutations whose
@@ -2506,4 +2751,4 @@ type FieldInput = {
2506
2751
  [field: string]: true | FieldInput;
2507
2752
  };
2508
2753
  //#endregion
2509
- export { PluginRouter as $, WriteOptions as $t, KernelPlugin as A, DeriveSpec as At, QualifiedFrame as B, ReadResult as Bt, FilterOperatorDef as C, Row as Cn, WriteEvent as Ct, KernelMigration as D, assertNoRepeatedIds as Dn, Dataset as Dt, KernelLifecycleContext as E, WriteRow as En, ConditionalUpdateResult as Et, NamespaceInstallContext as F, FrameAgg as Ft, RegistryEntryKind as G, TypeStorageReport as Gt, RegistryBase as H, StorageReport as Ht, NamespaceTypeDef as I, IndexPlan as It, ScheduledTaskContext as J, WalkAggOperand as Jt, RegistryEntryResolver as K, UpdateFieldRef as Kt, PluginLifecycleContext as L, NestedSelection as Lt, McpToolRegistration as M, FieldKind as Mt, NamespaceConfig as N, FieldPredicate as Nt, KernelMigrationContext as O, DatasetRegistry as Ot, NamespaceDefinition as P, FilterCapabilities as Pt, HttpMethod as Q, WhereClause as Qt, PluginRouteContext as R, OrderByClause as Rt, EngineInput as S, ROW_METADATA_FIELDS as Sn, TypedResolver as St, IndexDecl as T, RowMetadataField as Tn, BucketSpec as Tt, RegistryEntry as U, TxScopeHandles as Ut, Registry as V, RefOperand as Vt, RegistryEntryInput as W, TypeIndexState as Wt, VirtualTypeDef as X, WalkNode as Xt, VirtualMutationDef as Y, WalkAggPredicate as Yt, HttpHandler as Z, WalkPick as Zt, CoordinatorPlugin as _, ActorIdentity as _n, RequestContext as _t, FieldDefCrossRef as a, RuntimeErrors as an, SubstrateResponse as at, EncodeContext as b, Id as bn, ResolverReturn as bt, FieldDefStruct as c, TypeStats as cn, WsConnection as ct, OrderedBy as d, EdgePatch as dn, AutoCrudVerb as dt, WriteResult as en, RequestObservation as et, PackEnvelope as f, EdgeRef as fn, Identity as ft, naturalOrderOf as g, OnMissing as gn, PolicyProbeContext as gt, TypeSchema as h, OnDelete as hn, PolicyDecision as ht, FieldDef as i, RuntimeErrorEntry as in, SubstrateRequest as it, KernelRouteClaim as j, DropResult as jt, KernelNamespaceContribution as k, DeleteResult as kt, FieldInput as l, CanDeleteResult as ln, WsHandler as lt, Schema as m, EdgesStore as mn, Policy as mt, Dropped as n, ResolveObservation as nn, RuntimeOp as nt, FieldDefList as o, RuntimeMetrics as on, SubstrateServer as ot, PlanClause as p, EdgeWriteInput as pn, Obligation as pt, ScheduledTask as q, WalkAgg as qt, EnvelopeShape as r, ResolverStat as rn, StartOpts as rt, FieldDefScalar as s, SlowRequest as sn, TlsConfig as st, DEFAULT_ORDERED_BY as t, ProcessStat as tn, RequestObserver as tt, MutationSchema as u, Edge as un, AfterTxWork as ut, DropParticipant as v, CLIENT_SUPPLIED_SERVER_FIELD as vn, Resolver as vt, FrameEntry as w, RowMetadata as wn, AggFn as wt, EngineHandle as x, IdentityKind as xn, RowFilterObligation as xt, EmbedSourceContext as y, ClientSuppliedServerFieldError as yn, ResolverArgs as yt, PostWriteHook as z, ReadParams as zt };
2754
+ export { VirtualMutationDef as $, TypeIndexState as $t, KernelLifecycleContext as A, IdentityKind as An, ConditionalUpdateResult as At, NamespaceTypeDef as B, FilterWriteLimits as Bt, EmbedSourceContext as C, EdgesStore as Cn, ResolverArgs as Ct, FilterOperatorDef as D, CLIENT_SUPPLIED_SERVER_FIELD as Dn, WriteEvent as Dt, EngineInput as E, ActorIdentity as En, TypedResolver as Et, KernelRouteClaim as F, WriteRow as Fn, DeriveSpec as Ft, Registry as G, NestedSelection as Gt, PluginRouteContext as H, FilterWriteResult as Ht, McpToolRegistration as I, assertNoRepeatedIds as In, DropResult as It, RegistryEntryInput as J, ReadParams as Jt, RegistryBase as K, OrderByClause as Kt, NamespaceConfig as L, FieldKind as Lt, KernelMigrationContext as M, Row as Mn, Dataset as Mt, KernelNamespaceContribution as N, RowMetadata as Nn, DatasetRegistry as Nt, FrameEntry as O, ClientSuppliedServerFieldError as On, AggFn as Ot, KernelPlugin as P, RowMetadataField as Pn, DeleteResult as Pt, ScheduledTaskContext as Q, TxScopeHandles as Qt, NamespaceDefinition as R, FieldPredicate as Rt, DropParticipant as S, EdgeWriteInput as Sn, Resolver as St, EngineHandle as T, OnMissing as Tn, RowFilterObligation as Tt, PostWriteHook as U, FrameAgg as Ut, PluginLifecycleContext as V, FilterWriteOptions as Vt, QualifiedFrame as W, IndexPlan as Wt, RegistryEntryResolver as X, RefOperand as Xt, RegistryEntryKind as Y, ReadResult as Yt, ScheduledTask as Z, StorageReport as Zt, naturalOrderOf as _, TypeStats as _n, Obligation as _t, FieldDefCrossRef as a, WalkNode as an, RequestObserver as at, CommittedWritesHook as b, EdgePatch as bn, PolicyProbeContext as bt, FieldDefStruct as c, WriteOptions as cn, SubstrateRequest as ct, OrderedBy as d, ResolveObservation as dn, TlsConfig as dt, TypeStorageReport as en, VirtualTypeDef as et, PackEnvelope as f, ResolverStat as fn, WsConnection as ft, isColumnField as g, SlowRequest as gn, Identity as gt, TypeSchema as h, RuntimeMetrics as hn, AutoCrudVerb as ht, FieldDef as i, WalkAggPredicate as in, RequestObservation as it, KernelMigration as j, ROW_METADATA_FIELDS as jn, DEFAULT_FILTER_WRITE_LIMITS as jt, IndexDecl as k, Id as kn, BucketSpec as kt, FieldInput as l, WriteResult as ln, SubstrateResponse as lt, Schema as m, RuntimeErrors as mn, AfterTxWork as mt, Dropped as n, WalkAgg as nn, HttpMethod as nt, FieldDefList as o, WalkPick as on, RuntimeOp as ot, PlanClause as p, RuntimeErrorEntry as pn, WsHandler as pt, RegistryEntry as q, PromotionEvent as qt, EnvelopeShape as r, WalkAggOperand as rn, PluginRouter as rt, FieldDefScalar as s, WhereClause as sn, StartOpts as st, DEFAULT_ORDERED_BY as t, UpdateFieldRef as tn, HttpHandler as tt, MutationSchema as u, ProcessStat as un, SubstrateServer as ut, BatchResolver as v, CanDeleteResult as vn, Policy as vt, EncodeContext as w, OnDelete as wn, ResolverReturn as wt, CoordinatorPlugin as x, EdgeRef as xn, RequestContext as xt, CommittedWriteBatch as y, Edge as yn, PolicyDecision as yt, NamespaceInstallContext as z, FilterCapabilities as zt };