@mnmal-ai/substrate 1.0.0-alpha.11 → 1.0.0-alpha.13
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.
- package/README.md +12 -5
- package/dist/{boot-store-C5vNZJ3i.js → boot-store-0BPtJ8ne.js} +167 -71
- package/dist/{bridge-COu0Tg_h.d.ts → bridge-DQyQ6Qhn.d.ts} +1 -1
- package/dist/{cli-BrwW4tjO.js → cli-BvQqNFVn.js} +14 -11
- package/dist/client.d.ts +3 -3
- package/dist/client.js +3 -3
- package/dist/{errors-BOllGhVx.d.ts → errors-xP9Mo7Q1.d.ts} +25 -4
- package/dist/{index-Cp74OcmS.d.ts → index-baF5A5jU.d.ts} +1 -1
- package/dist/pack.d.ts +2 -2
- package/dist/pack.js +1 -1
- package/dist/{pg-edges-store-BLsbcXkk.js → pg-edges-store-B4FSN9yp.js} +72 -9
- package/dist/{plugin-DIYm2cZE.js → plugin-BLm5IRdX.js} +2 -2
- package/dist/proposals-bootstrap.js +2 -2
- package/dist/proposals.d.ts +2 -2
- package/dist/proposals.js +1 -1
- package/dist/recall-bootstrap.js +2 -2
- package/dist/recall.d.ts +10 -10
- package/dist/recall.js +2 -2
- package/dist/{repl-B8gy0YM7.js → repl-Dw2Fb7C1.js} +25 -25
- package/dist/{row-DwaDU4b-.d.ts → row-Dtj3KrPH.d.ts} +9 -2
- package/dist/{run-B18qtGKc.js → run-CgDw2c3X.js} +520 -141
- package/dist/{schema-CijHRfuk.d.ts → schema-oXfQyo0s.d.ts} +272 -27
- package/dist/sdk.d.ts +93 -29
- package/dist/sdk.js +4 -4
- package/dist/{src-D041j6GS.js → src-Bew_JvTo.js} +32 -16
- package/dist/{src-DpPdw2oL.js → src-Bi3NhEsT.js} +1 -1
- package/dist/{src-DptNGNYQ.js → src-BjWVYYoo.js} +175 -91
- package/dist/{src-DK7VEQT6.js → src-C4t1Gy-m.js} +2477 -830
- package/dist/{src-Br6aDUti.js → src-CHND7-Pm.js} +2 -2
- package/dist/src-CSe2tJDf.js +6940 -0
- package/dist/{src-Dbvuel6w.js → src-DWqzrm3O.js} +18 -1
- package/dist/substrate-admin.js +1 -1
- package/dist/substrate.js +1 -1
- package/dist/testing.d.ts +233 -92
- package/dist/testing.js +6 -23
- package/dist/{ws-DC8OhMaV.d.ts → ws-Dx3A2B4U.d.ts} +2 -2
- package/package.json +19 -20
- 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:
|
|
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
|
|
643
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
711
|
-
*
|
|
712
|
-
*
|
|
713
|
-
*
|
|
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: `
|
|
1079
|
+
/** Where a type's rows live: `table` is set once the type has its table. */
|
|
927
1080
|
interface TypeStorageReport {
|
|
928
|
-
layout: '
|
|
929
|
-
|
|
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: '
|
|
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
|
-
*
|
|
1595
|
-
*
|
|
1596
|
-
*
|
|
1597
|
-
*
|
|
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
|
|
2034
|
-
*
|
|
2035
|
-
*
|
|
2036
|
-
*
|
|
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: '
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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,
|
|
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,
|
|
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 {
|
|
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 };
|