@mnmal-ai/substrate 1.0.0-alpha.8 → 1.0.0-beta.1
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 +32 -14
- package/dist/boot-store-BMQUbHKv.js +4086 -0
- package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-DnToJedN.d.ts} +2 -87
- package/dist/cli-DModIbnN.js +3390 -0
- package/dist/client.browser.js +2507 -0
- package/dist/client.d.ts +222 -171
- package/dist/client.js +6 -7
- package/dist/cluster-worker.js +0 -1
- package/dist/{content-type-C7T28xNb.js → content-type-wLljot5M.js} +0 -1
- package/dist/{env-utils-CGNazUNt.js → env-utils-s25Z1YSA.js} +0 -1
- package/dist/{errors-D4vKuwz8.d.ts → errors-Cmkp1qxf.d.ts} +44 -4
- package/dist/{fake-DUVtKVSE.js → fake-DdXtb-m8.js} +0 -1
- package/dist/{index-D7mSOFlM.d.ts → index-BI4KqFiR.d.ts} +7 -11
- package/dist/msgpackr-Dq18g6Ds.js +16 -0
- package/dist/node-version-BtK_Nq6z.js +32 -0
- package/dist/pack.d.ts +75 -11
- package/dist/pack.js +4 -4
- package/dist/{plugin-B3NxUCVn.js → plugin-CEOhrEme.js} +149 -6
- package/dist/proposals-bootstrap.js +6 -5
- package/dist/proposals.config.schema.json +5 -0
- package/dist/proposals.d.ts +17 -5
- package/dist/proposals.default-config.json +2 -1
- package/dist/proposals.js +2 -3
- package/dist/recall-bootstrap.js +5 -4
- package/dist/recall.config.schema.json +6 -0
- package/dist/recall.d.ts +27 -6
- package/dist/recall.js +2 -3
- package/dist/{repl-DeKzfvNV.js → repl-BvDZy-Ut.js} +52 -26
- package/dist/{row-ByLFE2Wx.d.ts → row-D0If4qif.d.ts} +92 -12
- package/dist/run-BT123RV1.js +2443 -0
- package/dist/{plugin-t2g2wX0b.d.ts → schema-aIkY8sR3.d.ts} +1293 -63
- package/dist/{script-C6DSa_Na.js → script-ByQ9pzhC.js} +54 -26
- package/dist/script-runner.js +78 -0
- package/dist/sdk.d.ts +236 -38
- package/dist/sdk.js +5 -110
- package/dist/semver-D_zdq0hi.js +17 -0
- package/dist/src-BMD2OE--.js +8289 -0
- package/dist/{src-BLgbLq2k.js → src-B_kHkbsr.js} +780 -330
- package/dist/{src-DjIuRjzF.js → src-CKSJ13p8.js} +10231 -4237
- package/dist/{src-CkZw6xVD.js → src-CW7eRDss.js} +188 -87
- package/dist/{row-DZ0Fnpc6.js → src-DmiUWOLp.js} +2 -1
- package/dist/{src-DCy7Iy2l.js → src-DmjwFMu8.js} +900 -77
- package/dist/{src-DiNTSaFk.js → src-FXO5JPyk.js} +686 -856
- package/dist/substrate-admin.js +17 -782
- package/dist/substrate.js +4 -5206
- package/dist/testing.d.ts +473 -96
- package/dist/testing.js +19 -165
- package/dist/{ws-C72iVS5T.d.ts → ws-DW8ng02H.d.ts} +4 -5
- package/package.json +26 -26
- package/dist/dataset-jZS_4ci4.js +0 -1535
- package/dist/pg-edges-store-KH_FQCxx.js +0 -381
- package/dist/schema-g4FQLr0V.d.ts +0 -433
- package/dist/src-BD27zeGF.js +0 -2339
|
@@ -1,4 +1,359 @@
|
|
|
1
|
-
|
|
1
|
+
//#region ../../packages/substrate-types/src/core.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Core substrate-neutral types. Spec: §4.5 Dataset, §4.6 Edge.
|
|
4
|
+
*/
|
|
5
|
+
type Id = string | number;
|
|
6
|
+
interface Row {
|
|
7
|
+
id: Id;
|
|
8
|
+
_deletedAt?: Date | null;
|
|
9
|
+
/**
|
|
10
|
+
* Server-managed row-lifecycle metadata, set by autoCRUD on create/update
|
|
11
|
+
* and projected on every read alongside `id`. Each dataset stores it in
|
|
12
|
+
* its own way.
|
|
13
|
+
*/
|
|
14
|
+
_metadata?: RowMetadata;
|
|
15
|
+
/** Per-row walk aggregates (`params.agg`). */
|
|
16
|
+
_agg?: Record<string, unknown>;
|
|
17
|
+
/** Nested selections whose cap was hit, by name. */
|
|
18
|
+
_truncated?: Record<string, true>;
|
|
19
|
+
[field: string]: unknown;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* A row as passed to `Dataset.write`. `id` may be omitted: the dataset then
|
|
23
|
+
* assigns a version-7 UUID and returns it in `WriteResult.ids`.
|
|
24
|
+
*/
|
|
25
|
+
interface WriteRow {
|
|
26
|
+
id?: Id;
|
|
27
|
+
_deletedAt?: Date | null;
|
|
28
|
+
_metadata?: RowMetadata;
|
|
29
|
+
[field: string]: unknown;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Refuse an upsert batch that names one id twice: the datasets would
|
|
33
|
+
* otherwise disagree (pg cannot update a row twice in one statement).
|
|
34
|
+
*/
|
|
35
|
+
declare function assertNoRepeatedIds(type: string, rows: readonly WriteRow[]): void;
|
|
36
|
+
type IdentityKind = 'agent' | 'user' | 'system';
|
|
37
|
+
/**
|
|
38
|
+
* Row-attribution actor — records who created or last updated a row.
|
|
39
|
+
* Distinct from the auth `Identity` in `policy.ts` (JWT principal).
|
|
40
|
+
*/
|
|
41
|
+
interface ActorIdentity {
|
|
42
|
+
readonly kind: IdentityKind;
|
|
43
|
+
readonly id: string;
|
|
44
|
+
}
|
|
45
|
+
interface RowMetadata {
|
|
46
|
+
readonly createdAt: string | null;
|
|
47
|
+
readonly updatedAt: string | null;
|
|
48
|
+
readonly createdBy: ActorIdentity | null;
|
|
49
|
+
readonly updatedBy: ActorIdentity | null;
|
|
50
|
+
/**
|
|
51
|
+
* The row's place in its type's commit order, on a type declared
|
|
52
|
+
* `ordering: 'visible'`; absent on every other type. Assigned on insert only.
|
|
53
|
+
*/
|
|
54
|
+
readonly seq?: number;
|
|
55
|
+
}
|
|
56
|
+
declare const CLIENT_SUPPLIED_SERVER_FIELD: 'client_supplied_server_field';
|
|
57
|
+
type ClientSuppliedServerFieldError = typeof CLIENT_SUPPLIED_SERVER_FIELD;
|
|
58
|
+
declare const ROW_METADATA_FIELDS: readonly ['createdAt', 'updatedAt', 'createdBy', 'updatedBy'];
|
|
59
|
+
type RowMetadataField = (typeof ROW_METADATA_FIELDS)[number];
|
|
60
|
+
//#endregion
|
|
61
|
+
//#region ../../packages/substrate-types/src/edge.d.ts
|
|
62
|
+
type OnDelete = 'set_null' | 'cascade' | 'restrict' | 'orphan';
|
|
63
|
+
type OnMissing = 'reject' | 'allow';
|
|
64
|
+
interface EdgeRef {
|
|
65
|
+
ns: string;
|
|
66
|
+
type: string;
|
|
67
|
+
id: Id;
|
|
68
|
+
bridged?: boolean;
|
|
69
|
+
}
|
|
70
|
+
interface Edge {
|
|
71
|
+
id: string;
|
|
72
|
+
from: EdgeRef;
|
|
73
|
+
to: EdgeRef;
|
|
74
|
+
fieldName: string;
|
|
75
|
+
policy: OnDelete;
|
|
76
|
+
createdAt: Date;
|
|
77
|
+
deletedAt?: Date;
|
|
78
|
+
lastSweptAt?: Date;
|
|
79
|
+
blocked?: boolean;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Narrow patch type for `EdgesStore.update`. Immutable fields (from, to,
|
|
83
|
+
* policy, fieldName, createdAt, id-as-identity) cannot be changed post-write.
|
|
84
|
+
* `deletedAt` is managed exclusively by `tombstone(id)`.
|
|
85
|
+
*/
|
|
86
|
+
type EdgePatch = Pick<Edge, 'id'> & Partial<Pick<Edge, 'lastSweptAt' | 'blocked'>>;
|
|
87
|
+
type EdgeWriteInput = Omit<Edge, 'id' | 'createdAt' | 'lastSweptAt' | 'deletedAt' | 'blocked'>;
|
|
88
|
+
type CanDeleteResult = {
|
|
89
|
+
ok: true;
|
|
90
|
+
} | {
|
|
91
|
+
ok: false;
|
|
92
|
+
blockedBy: Edge[];
|
|
93
|
+
};
|
|
94
|
+
interface EdgesStore {
|
|
95
|
+
/**
|
|
96
|
+
* Stable identifier for the storage substrate this edges store wraps.
|
|
97
|
+
* Parallels `Dataset.txScopeId` (spec §5.3). When an `EdgesStore`
|
|
98
|
+
* and a `Dataset` share a `txScopeId`, the engine enlists edge
|
|
99
|
+
* mutations into the dataset's `withScopedTransaction`, making
|
|
100
|
+
* row-tombstone + edge-tombstone within one frame atomic.
|
|
101
|
+
*
|
|
102
|
+
* Convention:
|
|
103
|
+
* - pg: derived from the `postgres.Sql` pool reference identity. A
|
|
104
|
+
* `PgEdgesStore` constructed against the same `Sql` as a
|
|
105
|
+
* `PgDataset` advertises the same `txScopeId`.
|
|
106
|
+
* - memory: unique per `MemoryEdgesStore` instance. A memory edges
|
|
107
|
+
* store can never coalesce into a dataset's substrate tx; the engine
|
|
108
|
+
* falls back to nested independent transactions for that case.
|
|
109
|
+
*/
|
|
110
|
+
readonly txScopeId: string;
|
|
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[]>;
|
|
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>;
|
|
124
|
+
update(patch: EdgePatch): Promise<void>;
|
|
125
|
+
readNextBatch(cursorId: string | null, size: number): Promise<{
|
|
126
|
+
edges: Edge[];
|
|
127
|
+
lastId: string | null;
|
|
128
|
+
}>;
|
|
129
|
+
findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
|
|
130
|
+
/**
|
|
131
|
+
* Batched `findEdgesTo`: all live (non-tombstoned) inbound edges whose `to`
|
|
132
|
+
* matches ANY of `refs`, in a single round-trip. Empty `refs` yields an
|
|
133
|
+
* empty result. Callers group the flat result by `edge.to` themselves.
|
|
134
|
+
*/
|
|
135
|
+
findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
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[]>;
|
|
142
|
+
canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
|
|
143
|
+
findBlocked(): Promise<Edge[]>;
|
|
144
|
+
/**
|
|
145
|
+
* List live (non-tombstoned) edges where `from_ns === namespace` OR
|
|
146
|
+
* `to_ns === namespace`. Used by drop-namespace to detect dangling refs
|
|
147
|
+
* when `cascade === 'refuse'`. Bounded by `limit` — callers only need
|
|
148
|
+
* enough to decide + surface a sample.
|
|
149
|
+
*/
|
|
150
|
+
findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
|
|
151
|
+
/**
|
|
152
|
+
* List live (non-tombstoned) edges where either endpoint matches
|
|
153
|
+
* `(namespace, type)`. Used by drop-type for the same cascade-refuse check.
|
|
154
|
+
*/
|
|
155
|
+
findEdgesTouchingType(namespace: string, type: string, limit: number): Promise<Edge[]>;
|
|
156
|
+
/**
|
|
157
|
+
* Distinct namespaces other than `namespace` at the far end of any edge
|
|
158
|
+
* (tombstoned or live) touching `namespace`, or `(namespace, type)` when
|
|
159
|
+
* `type` is given: the namespaces `dropEdgesByNamespace` / `dropEdgesByType`
|
|
160
|
+
* would delete edges from.
|
|
161
|
+
*/
|
|
162
|
+
namespacesLinkedTo(namespace: string, type?: string): Promise<string[]>;
|
|
163
|
+
/**
|
|
164
|
+
* Physically delete every edge (tombstoned or live) where `from_ns === namespace`
|
|
165
|
+
* OR `to_ns === namespace`. Used by drop-namespace when `cascade === 'delete'`.
|
|
166
|
+
* Returns the exact count physically removed.
|
|
167
|
+
*
|
|
168
|
+
* Same atomicity rules as `tombstone` — MUST run inside a caller-supplied
|
|
169
|
+
* `withTransaction` for multi-store atomicity.
|
|
170
|
+
*/
|
|
171
|
+
dropEdgesByNamespace(namespace: string, within?: readonly string[]): Promise<number>;
|
|
172
|
+
/**
|
|
173
|
+
* Physically delete every edge (tombstoned or live) where either endpoint
|
|
174
|
+
* matches `(namespace, type)`. Used by drop-type when `cascade === 'delete'`.
|
|
175
|
+
* `within` restricts both drops to edges whose far end is `namespace` or one
|
|
176
|
+
* of the listed namespaces.
|
|
177
|
+
*/
|
|
178
|
+
dropEdgesByType(namespace: string, type: string, within?: readonly string[]): Promise<number>;
|
|
179
|
+
/**
|
|
180
|
+
* Execute `fn` atomically. All ops performed on the `tx` argument run inside
|
|
181
|
+
* one substrate transaction. On throw, every mutation inside the callback
|
|
182
|
+
* rolls back; on resolve, the transaction commits and the value is returned.
|
|
183
|
+
*
|
|
184
|
+
* Nested calls flatten into the outer tx (savepoints out of scope).
|
|
185
|
+
* Cross-store atomicity with a sibling `Dataset.withTransaction` is the
|
|
186
|
+
* engine's concern; each store manages its own tx independently here.
|
|
187
|
+
* For enlisted cross-store atomicity, see `Dataset.withScopedTransaction`
|
|
188
|
+
* which yields a tx-bound `EdgesStore` alongside the tx-bound datasets.
|
|
189
|
+
*
|
|
190
|
+
* Mirrors `Dataset.withTransaction` (§4.5, G1 §5.3).
|
|
191
|
+
*/
|
|
192
|
+
withTransaction<T>(fn: (tx: EdgesStore) => Promise<T>): Promise<T>;
|
|
193
|
+
}
|
|
194
|
+
//#endregion
|
|
195
|
+
//#region ../../packages/substrate-types/src/expression.d.ts
|
|
196
|
+
/**
|
|
197
|
+
* Typed expressions for the read grammar: the JSON form, the type lattice, the
|
|
198
|
+
* curated function catalogue and the size limits.
|
|
199
|
+
*
|
|
200
|
+
* An expression is a bare string (a field, or `_agg.<name>`), a number, boolean
|
|
201
|
+
* or `null` literal, `{ lit: "text" }` (string literal), `{ int64: "<decimal>" }`
|
|
202
|
+
* (exact int64 constant) or `{ <fn>: [args...] }` (a call, one key).
|
|
203
|
+
*/
|
|
204
|
+
type Expr = string | number | boolean | null | {
|
|
205
|
+
lit: string;
|
|
206
|
+
} | {
|
|
207
|
+
int64: string;
|
|
208
|
+
} | {
|
|
209
|
+
[fn: string]: Expr[];
|
|
210
|
+
};
|
|
211
|
+
type ExprType = 'number' | 'int64' | 'string' | 'boolean' | 'date';
|
|
212
|
+
/**
|
|
213
|
+
* An argument slot. `'any'` slots unify to one type (int64 and number compare
|
|
214
|
+
* as number); `'unit'` is a `{ lit }` date unit, `'pattern'` a `{ lit }`
|
|
215
|
+
* regex and `'likePattern'` a `{ lit }` LIKE pattern, all literal-only.
|
|
216
|
+
*/
|
|
217
|
+
type ArgType = ExprType | 'any' | 'unit' | 'pattern' | 'likePattern';
|
|
218
|
+
interface FunctionSig {
|
|
219
|
+
name: string;
|
|
220
|
+
/** Fixed argument slots, or `'variadic'` when the checker applies the function's own rules. */
|
|
221
|
+
args: ArgType[] | 'variadic';
|
|
222
|
+
/** `'any'` is the unified type of the `'any'` (and, for arithmetic, `'number'`) arguments. */
|
|
223
|
+
returns: ExprType | 'any';
|
|
224
|
+
description: string;
|
|
225
|
+
}
|
|
226
|
+
declare const EXPR_FUNCTIONS: readonly FunctionSig[];
|
|
227
|
+
declare const EXPR_LIMITS: {
|
|
228
|
+
maxDepth: number;
|
|
229
|
+
maxNodesPerExpr: number;
|
|
230
|
+
maxNodesPerFrame: number;
|
|
231
|
+
};
|
|
232
|
+
/** The aggregate names `_agg`, `having` and grouped reads accept. */
|
|
233
|
+
declare const EXPR_AGGREGATES: readonly ['count', 'countDistinct', 'sum', 'avg', 'min', 'max'];
|
|
234
|
+
declare const DATE_UNITS: readonly ['second', 'minute', 'hour', 'day', 'week', 'month', 'year'];
|
|
235
|
+
//#endregion
|
|
236
|
+
//#region ../../packages/substrate-types/src/runtime-metrics.d.ts
|
|
237
|
+
/** Per-key resolver latency and error counts, as served by GET /substrate/v1/metrics. */
|
|
238
|
+
interface ResolverStat {
|
|
239
|
+
kind: 'query' | 'mutate';
|
|
240
|
+
calls: number;
|
|
241
|
+
errors: number;
|
|
242
|
+
p50Ms: number;
|
|
243
|
+
p99Ms: number;
|
|
244
|
+
maxMs: number;
|
|
245
|
+
lastAt: string;
|
|
246
|
+
}
|
|
247
|
+
interface ProcessStat {
|
|
248
|
+
rssMB: number;
|
|
249
|
+
heapUsedMB: number;
|
|
250
|
+
cpuUserMs: number;
|
|
251
|
+
cpuSystemMs: number;
|
|
252
|
+
eventLoopLagP99Ms: number;
|
|
253
|
+
inFlight: number;
|
|
254
|
+
}
|
|
255
|
+
interface SlowRequest {
|
|
256
|
+
key: string;
|
|
257
|
+
kind: 'query' | 'mutate';
|
|
258
|
+
durationMs: number;
|
|
259
|
+
at: string;
|
|
260
|
+
}
|
|
261
|
+
interface RuntimeErrorEntry {
|
|
262
|
+
at: string;
|
|
263
|
+
op: 'query' | 'mutate';
|
|
264
|
+
key: string;
|
|
265
|
+
code: string;
|
|
266
|
+
message: string;
|
|
267
|
+
/** The verified identity's id, or `'anonymous'`. */
|
|
268
|
+
caller?: string;
|
|
269
|
+
/** Present when consecutive identical `(unknown)` failures were merged into this entry. */
|
|
270
|
+
count?: number;
|
|
271
|
+
}
|
|
272
|
+
interface RuntimeErrors {
|
|
273
|
+
since: string;
|
|
274
|
+
errors: RuntimeErrorEntry[];
|
|
275
|
+
}
|
|
276
|
+
interface ResolveObservation {
|
|
277
|
+
key: string;
|
|
278
|
+
kind: 'query' | 'mutate';
|
|
279
|
+
durationMs: number;
|
|
280
|
+
ok: boolean;
|
|
281
|
+
code?: string;
|
|
282
|
+
message?: string;
|
|
283
|
+
/** The verified identity's id; absent for an anonymous caller. */
|
|
284
|
+
caller?: string;
|
|
285
|
+
/**
|
|
286
|
+
* Set when the element ran in a batch resolver call: the number of elements
|
|
287
|
+
* in that call. `durationMs` is then the whole call's time, shared by all of
|
|
288
|
+
* them. Absent for a per-element resolve.
|
|
289
|
+
*/
|
|
290
|
+
batchSize?: number;
|
|
291
|
+
/**
|
|
292
|
+
* The element's position (0..batchSize-1) in its batch call; set with
|
|
293
|
+
* `batchSize`. Latency aggregates take a batch once, from index 0, so one
|
|
294
|
+
* call's time is not counted batchSize times. Call counts take every element.
|
|
295
|
+
*/
|
|
296
|
+
batchIndex?: number;
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* One type's table and index statistics, for the index advisor. Counters are
|
|
300
|
+
* cumulative since the server's statistics were last reset. Row counts are
|
|
301
|
+
* estimates. A type ABSENT from a `typeStats()` result is unknown, not empty:
|
|
302
|
+
* never read its absence as 0 rows (a sampled store can miss a small type).
|
|
303
|
+
*/
|
|
304
|
+
interface TypeStats {
|
|
305
|
+
namespace: string;
|
|
306
|
+
type: string;
|
|
307
|
+
liveRows: number;
|
|
308
|
+
insertsTotal: number;
|
|
309
|
+
updatesTotal: number;
|
|
310
|
+
deletesTotal: number;
|
|
311
|
+
indexes: Array<{
|
|
312
|
+
name: string;
|
|
313
|
+
scans: number;
|
|
314
|
+
/** The last scan (ISO), or null when none since the statistics were last reset. */
|
|
315
|
+
lastScanAt: string | null;
|
|
316
|
+
sizeBytes: number;
|
|
317
|
+
unique: boolean;
|
|
318
|
+
/** Built or adopted by the engine's index reconciler for this type. */
|
|
319
|
+
engineOwned: boolean;
|
|
320
|
+
}>;
|
|
321
|
+
}
|
|
322
|
+
/** What GET /substrate/v1/metrics returns. The new fields are optional so an older server still type-checks. */
|
|
323
|
+
interface RuntimeMetrics {
|
|
324
|
+
since: string;
|
|
325
|
+
requests: {
|
|
326
|
+
query: {
|
|
327
|
+
total: number;
|
|
328
|
+
ok: number;
|
|
329
|
+
error: number;
|
|
330
|
+
durationMsSum: number;
|
|
331
|
+
durationMsMax: number;
|
|
332
|
+
};
|
|
333
|
+
mutate: {
|
|
334
|
+
total: number;
|
|
335
|
+
ok: number;
|
|
336
|
+
error: number;
|
|
337
|
+
durationMsSum: number;
|
|
338
|
+
durationMsMax: number;
|
|
339
|
+
};
|
|
340
|
+
};
|
|
341
|
+
subscriptions: {
|
|
342
|
+
active: number;
|
|
343
|
+
maxQueueDepth?: number;
|
|
344
|
+
entries?: {
|
|
345
|
+
id: string;
|
|
346
|
+
ns: string;
|
|
347
|
+
type: string;
|
|
348
|
+
queueLength: number;
|
|
349
|
+
}[];
|
|
350
|
+
};
|
|
351
|
+
events: Record<string, number>;
|
|
352
|
+
resolvers?: Record<string, ResolverStat>;
|
|
353
|
+
process?: ProcessStat;
|
|
354
|
+
slowest?: SlowRequest[];
|
|
355
|
+
}
|
|
356
|
+
//#endregion
|
|
2
357
|
//#region ../../packages/substrate-types/src/dataset.d.ts
|
|
3
358
|
/**
|
|
4
359
|
* Handles yielded by `Dataset.withScopedTransaction`. Contains the
|
|
@@ -21,12 +376,12 @@ interface TxScopeHandles {
|
|
|
21
376
|
* substrate layer — the validator enforces `null` only on those two operators.
|
|
22
377
|
*/
|
|
23
378
|
interface FieldPredicate {
|
|
24
|
-
eq?: number | string | boolean | Date | null;
|
|
25
|
-
neq?: number | string | boolean | Date | null;
|
|
26
|
-
gt?: number | string | Date;
|
|
27
|
-
gte?: number | string | Date;
|
|
28
|
-
lt?: number | string | Date;
|
|
29
|
-
lte?: number | string | Date;
|
|
379
|
+
eq?: number | string | boolean | Date | null | RefOperand;
|
|
380
|
+
neq?: number | string | boolean | Date | null | RefOperand;
|
|
381
|
+
gt?: number | string | Date | RefOperand;
|
|
382
|
+
gte?: number | string | Date | RefOperand;
|
|
383
|
+
lt?: number | string | Date | RefOperand;
|
|
384
|
+
lte?: number | string | Date | RefOperand;
|
|
30
385
|
between?: [number | string | Date, number | string | Date];
|
|
31
386
|
in?: Array<number | string | boolean | Date>;
|
|
32
387
|
nin?: Array<number | string | boolean | Date>;
|
|
@@ -49,8 +404,105 @@ type WhereClause = {
|
|
|
49
404
|
} | {
|
|
50
405
|
NOT: WhereClause;
|
|
51
406
|
} | {
|
|
407
|
+
_walk: WalkNode;
|
|
408
|
+
} | WalkAggPredicate | {
|
|
409
|
+
_walk?: never;
|
|
410
|
+
_agg?: never;
|
|
52
411
|
[field: string]: FieldPredicate | WhereClause | unknown;
|
|
53
412
|
};
|
|
413
|
+
type WalkPick = {
|
|
414
|
+
latest: string;
|
|
415
|
+
} | {
|
|
416
|
+
max: string;
|
|
417
|
+
} | {
|
|
418
|
+
min: string;
|
|
419
|
+
};
|
|
420
|
+
interface WalkNode {
|
|
421
|
+
as?: string;
|
|
422
|
+
/** `'<ns>/<Type>.<field>'`: inbound edge. */
|
|
423
|
+
in?: string;
|
|
424
|
+
/** `'<field>'`: outbound edge. */
|
|
425
|
+
out?: string;
|
|
426
|
+
where?: WhereClause;
|
|
427
|
+
quantifier?: 'any' | 'none' | 'all';
|
|
428
|
+
pick?: WalkPick;
|
|
429
|
+
/**
|
|
430
|
+
* Pick walks only: the neighbours the pick chooses among. `where` then
|
|
431
|
+
* judges the picked row, so "the latest non-skipped run" is
|
|
432
|
+
* `{ pick: { latest: 'at' }, among: { NOT: { status: { eq: 'skipped' } } } }` (#1810).
|
|
433
|
+
*/
|
|
434
|
+
among?: WhereClause;
|
|
435
|
+
}
|
|
436
|
+
/** `'$.f'` | `'<as>.f'` | `'_agg.<name>'` */
|
|
437
|
+
interface RefOperand {
|
|
438
|
+
$ref: string;
|
|
439
|
+
times?: number;
|
|
440
|
+
plus?: number;
|
|
441
|
+
}
|
|
442
|
+
type AggFn = {
|
|
443
|
+
count: true;
|
|
444
|
+
} | {
|
|
445
|
+
avg: string;
|
|
446
|
+
} | {
|
|
447
|
+
sum: string;
|
|
448
|
+
} | {
|
|
449
|
+
min: string;
|
|
450
|
+
} | {
|
|
451
|
+
max: string;
|
|
452
|
+
} | {
|
|
453
|
+
latest: {
|
|
454
|
+
by: string;
|
|
455
|
+
value: string;
|
|
456
|
+
};
|
|
457
|
+
};
|
|
458
|
+
type WalkAgg = {
|
|
459
|
+
in?: string;
|
|
460
|
+
out?: string;
|
|
461
|
+
where?: WhereClause;
|
|
462
|
+
} & AggFn;
|
|
463
|
+
/** A frame aggregate: `count: true` counts rows; every other argument is an expression. */
|
|
464
|
+
type FrameAgg = {
|
|
465
|
+
count: Expr;
|
|
466
|
+
} | {
|
|
467
|
+
countDistinct: Expr;
|
|
468
|
+
} | {
|
|
469
|
+
avg: Expr;
|
|
470
|
+
} | {
|
|
471
|
+
sum: Expr;
|
|
472
|
+
} | {
|
|
473
|
+
min: Expr;
|
|
474
|
+
} | {
|
|
475
|
+
max: Expr;
|
|
476
|
+
};
|
|
477
|
+
interface NestedSelection {
|
|
478
|
+
_walk: {
|
|
479
|
+
in?: string;
|
|
480
|
+
out?: string;
|
|
481
|
+
where?: WhereClause;
|
|
482
|
+
};
|
|
483
|
+
fields: Record<string, unknown>;
|
|
484
|
+
where?: WhereClause;
|
|
485
|
+
orderBy?: OrderByClause[];
|
|
486
|
+
limit?: number;
|
|
487
|
+
}
|
|
488
|
+
/** An `_agg` comparison operand: a number, a date or string (by the aggregate's kind), or a `$ref`. */
|
|
489
|
+
type WalkAggOperand = number | string | RefOperand;
|
|
490
|
+
/** `{ _agg: <walk aggregate>, <cmp>: <operand> }` */
|
|
491
|
+
type WalkAggPredicate = {
|
|
492
|
+
_agg: WalkAgg;
|
|
493
|
+
} & ({
|
|
494
|
+
eq: WalkAggOperand;
|
|
495
|
+
} | {
|
|
496
|
+
neq: WalkAggOperand;
|
|
497
|
+
} | {
|
|
498
|
+
gt: WalkAggOperand;
|
|
499
|
+
} | {
|
|
500
|
+
gte: WalkAggOperand;
|
|
501
|
+
} | {
|
|
502
|
+
lt: WalkAggOperand;
|
|
503
|
+
} | {
|
|
504
|
+
lte: WalkAggOperand;
|
|
505
|
+
});
|
|
54
506
|
/**
|
|
55
507
|
* OrderBy clause. One entry per field, direction per field. Engine appends an
|
|
56
508
|
* implicit `{ id: 'asc' }` when callers omit `id` as the final tie-breaker — a
|
|
@@ -60,23 +512,34 @@ interface OrderByClause {
|
|
|
60
512
|
[field: string]: 'asc' | 'desc';
|
|
61
513
|
}
|
|
62
514
|
interface ReadParams {
|
|
515
|
+
/** Aborts the read. Substrates that can (PgDataset) cancel the in-flight statement; others MAY ignore it. */
|
|
516
|
+
signal?: AbortSignal;
|
|
63
517
|
id?: Id;
|
|
64
518
|
ids?: Id[];
|
|
65
519
|
includeDeleted?: boolean;
|
|
66
520
|
where?: WhereClause;
|
|
67
521
|
orderBy?: OrderByClause[];
|
|
68
522
|
limit?: number;
|
|
523
|
+
/** Return a match count (`ReadResult.count`). */
|
|
524
|
+
count?: boolean;
|
|
525
|
+
aggregate?: Record<string, FrameAgg>;
|
|
526
|
+
/** Group keys by output name; with `aggregate`, the read returns one group per distinct key tuple. */
|
|
527
|
+
groupBy?: Record<string, Expr>;
|
|
528
|
+
/** A boolean expression over group keys and aggregate names, applied before order and limit. */
|
|
529
|
+
having?: Expr;
|
|
530
|
+
/** Groups to skip, on a grouped read. */
|
|
531
|
+
offset?: number;
|
|
532
|
+
/** Computed per-row values by output name: each row gains one key per entry, which `orderBy` may use. */
|
|
533
|
+
select?: Record<string, Expr>;
|
|
534
|
+
/** Per-row walk aggregates, lifted out of `fields` by the list resolver. */
|
|
535
|
+
agg?: Record<string, WalkAgg>;
|
|
536
|
+
/** Per-row nested selections, lifted out of `fields` by the list resolver. */
|
|
537
|
+
nested?: Record<string, NestedSelection>;
|
|
69
538
|
/**
|
|
70
539
|
* Opaque cursor produced by a prior `read()` call. Base64url-encoded JSON
|
|
71
540
|
* (server-built, server-consumed). Callers should treat it as a black box.
|
|
72
541
|
*/
|
|
73
542
|
cursor?: string;
|
|
74
|
-
/**
|
|
75
|
-
* Admin-gated escape hatch for filtering on unindexed fields. Absent → the
|
|
76
|
-
* validator rejects filters on any `indexed: false` field. Policies can pin
|
|
77
|
-
* this to admin identities.
|
|
78
|
-
*/
|
|
79
|
-
_allowTableScan?: boolean;
|
|
80
543
|
/**
|
|
81
544
|
* Optional caller-supplied projection hint. Substrates MAY use this to
|
|
82
545
|
* narrow the body keys they materialise from storage — e.g. PgDataset
|
|
@@ -109,9 +572,16 @@ interface ReadResult {
|
|
|
109
572
|
rows: Row[];
|
|
110
573
|
nextCursor?: string;
|
|
111
574
|
hasMore: boolean;
|
|
575
|
+
count?: number;
|
|
576
|
+
groups?: Array<Record<string, unknown>>;
|
|
577
|
+
truncated?: boolean;
|
|
112
578
|
}
|
|
113
579
|
interface WriteResult {
|
|
114
580
|
written: number;
|
|
581
|
+
/**
|
|
582
|
+
* One per written row, in input order: a supplied id verbatim, otherwise
|
|
583
|
+
* the id the dataset assigned. Under `insertOnly`, skipped rows are absent.
|
|
584
|
+
*/
|
|
115
585
|
ids: Id[];
|
|
116
586
|
/**
|
|
117
587
|
* Merged rows after upsert — substrates populate this with the post-merge
|
|
@@ -147,6 +617,33 @@ interface DeleteResult {
|
|
|
147
617
|
deleted: number;
|
|
148
618
|
ids: Id[];
|
|
149
619
|
}
|
|
620
|
+
/** Options of `Dataset.updateWhere` / `deleteWhere`. */
|
|
621
|
+
interface FilterWriteOptions {
|
|
622
|
+
/** Most rows the filter may match; one more refuses the write with `filter_too_broad`. */
|
|
623
|
+
maxMatch: number;
|
|
624
|
+
/** Stamped as `updatedBy` (update only); the anonymous system actor when absent. */
|
|
625
|
+
actor?: ActorIdentity;
|
|
626
|
+
/** Stamped as `updatedAt` (update only); the clock when absent. */
|
|
627
|
+
now?: Date;
|
|
628
|
+
}
|
|
629
|
+
/**
|
|
630
|
+
* What a by-filter write changed: every changed id, and the changed rows
|
|
631
|
+
* (post-images for an update, pre-images for a delete). Both are bounded by
|
|
632
|
+
* `maxMatch`.
|
|
633
|
+
*/
|
|
634
|
+
interface FilterWriteResult {
|
|
635
|
+
count: number;
|
|
636
|
+
ids: Id[];
|
|
637
|
+
rows: Row[];
|
|
638
|
+
}
|
|
639
|
+
/** The caps on `updateMany<T>` / `deleteMany<T>`. */
|
|
640
|
+
interface FilterWriteLimits {
|
|
641
|
+
/** Most rows one filter may match (`SUBSTRATE_FILTER_WRITE_MAX_MATCH`). */
|
|
642
|
+
maxMatch: number;
|
|
643
|
+
/** Most ids one result returns (`SUBSTRATE_FILTER_WRITE_IDS_CAP`). */
|
|
644
|
+
idsCap: number;
|
|
645
|
+
}
|
|
646
|
+
declare const DEFAULT_FILTER_WRITE_LIMITS: Readonly<FilterWriteLimits>;
|
|
150
647
|
interface DropResult {
|
|
151
648
|
/** Number of rows physically removed. */
|
|
152
649
|
rowsDeleted: number;
|
|
@@ -158,13 +655,18 @@ interface DropResult {
|
|
|
158
655
|
* validates every where-clause leaf against `operators[fieldKind]` and rejects
|
|
159
656
|
* ops the dataset can't execute rather than returning a silently wrong result.
|
|
160
657
|
*/
|
|
161
|
-
type FieldKind = 'scalar.number' | 'scalar.string' | 'scalar.boolean' | 'scalar.date' | 'scalar.json' | 'crossRef' | 'list';
|
|
658
|
+
type FieldKind = 'scalar.number' | 'scalar.int16' | 'scalar.int32' | 'scalar.int64' | 'scalar.string' | 'scalar.boolean' | 'scalar.date' | 'scalar.json' | 'crossRef' | 'list';
|
|
162
659
|
interface FilterCapabilities {
|
|
163
660
|
operators: Record<FieldKind, string[]>;
|
|
164
661
|
/** Does the dataset honour `orderBy`? */
|
|
165
662
|
orderBy: boolean;
|
|
166
663
|
/** Does the dataset honour cursor-based pagination? */
|
|
167
664
|
cursor: boolean;
|
|
665
|
+
/**
|
|
666
|
+
* Does the dataset answer the typed-edge-walk grammar? The engine refuses a
|
|
667
|
+
* walk frame on a dataset without it (`walks_unsupported_store`).
|
|
668
|
+
*/
|
|
669
|
+
walks?: boolean;
|
|
168
670
|
}
|
|
169
671
|
interface UpdateFieldRef {
|
|
170
672
|
ns?: string;
|
|
@@ -207,7 +709,7 @@ interface Dataset {
|
|
|
207
709
|
*/
|
|
208
710
|
readonly txScopeId: string;
|
|
209
711
|
read(type: string, params: ReadParams): Promise<ReadResult>;
|
|
210
|
-
write(type: string, rows:
|
|
712
|
+
write(type: string, rows: WriteRow[], options?: WriteOptions): Promise<WriteResult>;
|
|
211
713
|
tombstone(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
212
714
|
purge(type: string, ids: Id[]): Promise<DeleteResult>;
|
|
213
715
|
/**
|
|
@@ -232,7 +734,7 @@ interface Dataset {
|
|
|
232
734
|
* Physically delete every row AND short-id for `this.namespace`, across
|
|
233
735
|
* every type. Equivalent to calling `dropType` for each distinct type
|
|
234
736
|
* seen in storage, but substrate impls SHOULD use a single bulk DELETE
|
|
235
|
-
* where available (pg:
|
|
737
|
+
* where available (pg: one DELETE per type table).
|
|
236
738
|
*
|
|
237
739
|
* Same atomicity rules as `dropType`. Same "ignores archived state".
|
|
238
740
|
*/
|
|
@@ -246,8 +748,9 @@ interface Dataset {
|
|
|
246
748
|
*
|
|
247
749
|
* Semantics:
|
|
248
750
|
* - Equality is strict (`===`) for scalars; `Date` compares by
|
|
249
|
-
* `.getTime()`; `null` matches
|
|
250
|
-
*
|
|
751
|
+
* `.getTime()`; `null` matches a stored `null` or an absent field, on both
|
|
752
|
+
* datasets. A declared scalar or crossRef set to `null` reads back absent
|
|
753
|
+
* (`isColumnField`), so it matches `null` all the same.
|
|
251
754
|
* - A missing row fails the match even when `match` is empty — the
|
|
252
755
|
* operation is "update this existing row if predicate holds".
|
|
253
756
|
* - `updates` is merged onto the stored row the same way `write()` upserts
|
|
@@ -275,7 +778,7 @@ interface Dataset {
|
|
|
275
778
|
* Run `fn` while holding a mutual-exclusion lock named `key`, waiting until
|
|
276
779
|
* it is free. Excludes every other holder of the same key on this substrate:
|
|
277
780
|
* pg holds a session advisory lock, so the exclusion spans processes sharing
|
|
278
|
-
* the database; memory excludes holders on this dataset instance only.
|
|
781
|
+
* the store's database schema; memory excludes holders on this dataset instance only.
|
|
279
782
|
* Released when `fn` settles, whether it resolves or throws, except on a
|
|
280
783
|
* pg tx-bound dataset, where it is held until the transaction ends so the
|
|
281
784
|
* next holder sees what this one committed. Not re-entrant:
|
|
@@ -287,6 +790,152 @@ interface Dataset {
|
|
|
287
790
|
* @throws whatever `fn` throws, after the lock is released
|
|
288
791
|
*/
|
|
289
792
|
withAdvisoryLock?<T>(key: string, fn: () => Promise<T>): Promise<T>;
|
|
793
|
+
/**
|
|
794
|
+
* Prepare dedicated storage for `type` in this namespace, moving any rows
|
|
795
|
+
* already written for it there. Idempotent, and safe beside concurrent
|
|
796
|
+
* reads and writes: no row is lost, duplicated or seen twice. That holds for
|
|
797
|
+
* READ COMMITTED readers; a REPEATABLE READ snapshot taken before the move
|
|
798
|
+
* can miss the moved rows. Also builds the type's indexes, including its
|
|
799
|
+
* declared `indexes`, and throws when a unique one cannot be built.
|
|
800
|
+
*
|
|
801
|
+
* `indexes` picks which: `unique` builds only the unique ones and leaves the
|
|
802
|
+
* rest `pending`, for a later `nonUnique` call to build. `signal` cancels an
|
|
803
|
+
* in-flight non-unique build, which the next call retries. Default `all`.
|
|
804
|
+
*
|
|
805
|
+
* On a store keeping each type in a table of its own, also brings that
|
|
806
|
+
* table in line with the type's declared fields: a newly declared field gets
|
|
807
|
+
* its column, or, with `newFields: 'pending'`, is recorded `pending` for a
|
|
808
|
+
* background sweep to add. Resolves with the fields that went `pending` in
|
|
809
|
+
* this call; a store without such tables resolves `{ pending: [] }`.
|
|
810
|
+
*
|
|
811
|
+
* OPTIONAL. Backends without per-type storage omit it.
|
|
812
|
+
*/
|
|
813
|
+
ensureTypeStorage?(type: string, opts?: {
|
|
814
|
+
indexes?: 'all' | 'unique' | 'nonUnique';
|
|
815
|
+
signal?: AbortSignal;
|
|
816
|
+
newFields?: 'column' | 'pending';
|
|
817
|
+
}): Promise<{
|
|
818
|
+
pending: string[];
|
|
819
|
+
}>;
|
|
820
|
+
/**
|
|
821
|
+
* Where `type`'s rows live and how its declared indexes stand, read from the
|
|
822
|
+
* catalog without building anything.
|
|
823
|
+
*
|
|
824
|
+
* OPTIONAL. Backends without per-type storage omit it.
|
|
825
|
+
*/
|
|
826
|
+
describeStorage?(type: string): Promise<TypeStorageReport>;
|
|
827
|
+
/**
|
|
828
|
+
* Gives each `pending` field of every namespace its column and moves its
|
|
829
|
+
* values out of jsonb, and finishes each `promoting` one, a field at a time.
|
|
830
|
+
* DDL waits at most `lockTimeoutMs` for its table's lock, then that field is
|
|
831
|
+
* `busy` and retried by the next call; `batchRows` rows move per statement.
|
|
832
|
+
* `signal` stops the sweep between steps. Resolves with one event per field
|
|
833
|
+
* it touched. A field that failed on a unique conflict waits for its type's
|
|
834
|
+
* catalog to change, unless `retryConflicts` is set.
|
|
835
|
+
*
|
|
836
|
+
* OPTIONAL. Backends with no per-type tables omit it.
|
|
837
|
+
*/
|
|
838
|
+
promotePendingFields?(opts: {
|
|
839
|
+
lockTimeoutMs: number;
|
|
840
|
+
batchRows: number;
|
|
841
|
+
signal?: AbortSignal;
|
|
842
|
+
/** Retries fields a unique conflict holds back until their type's catalog changes: an operator's run after fixing the data. */
|
|
843
|
+
retryConflicts?: boolean;
|
|
844
|
+
/**
|
|
845
|
+
* The store has no other writers (migrate-store's target): a field's move
|
|
846
|
+
* to its column waits for its table lock, so a blocking autovacuum is
|
|
847
|
+
* cancelled, rather than retrying without queueing in front of writers.
|
|
848
|
+
*/
|
|
849
|
+
noWriters?: boolean;
|
|
850
|
+
}): Promise<PromotionEvent[]>;
|
|
851
|
+
/**
|
|
852
|
+
* Store-wide counts of the fields an operator should know about: held in
|
|
853
|
+
* jsonb until promoted, whose promotion failed, and no longer declared with
|
|
854
|
+
* their column kept; and of misfits, values kept under `$raw`. Counts only, with no namespace, type, field or error
|
|
855
|
+
* text, since `/health` shows it unauthenticated; `storageReport` names them.
|
|
856
|
+
*
|
|
857
|
+
* OPTIONAL. Backends with no per-type tables omit it.
|
|
858
|
+
*/
|
|
859
|
+
fieldWarnings?(): Promise<string[]>;
|
|
860
|
+
/**
|
|
861
|
+
* The connection pool right now: connections open, opening, idle and leased,
|
|
862
|
+
* and requests waiting for one. Counts only; `/health` shows it unauthenticated.
|
|
863
|
+
*
|
|
864
|
+
* OPTIONAL. Backends with no connection pool omit it.
|
|
865
|
+
*/
|
|
866
|
+
poolStats?(): PoolStats;
|
|
867
|
+
/**
|
|
868
|
+
* The database-wide storage layout and what an operator should look at:
|
|
869
|
+
* indexes this process has yet to build or failed to build, fields whose
|
|
870
|
+
* promotion failed, and a type-table count over `partitionBudget`; and, as
|
|
871
|
+
* `info`, engine indexes no longer declared, pending and orphaned fields,
|
|
872
|
+
* misfits per type and field, and open index recommendations. Never changes anything.
|
|
873
|
+
*
|
|
874
|
+
* OPTIONAL. Backends without per-type storage omit it.
|
|
875
|
+
*/
|
|
876
|
+
storageReport?(opts: {
|
|
877
|
+
partitionBudget: number;
|
|
878
|
+
}): Promise<StorageReport>;
|
|
879
|
+
/**
|
|
880
|
+
* Table and index statistics for every type the store holds, every
|
|
881
|
+
* namespace, read from the database's own statistics. Estimates, never a
|
|
882
|
+
* count. Never changes anything.
|
|
883
|
+
*
|
|
884
|
+
* OPTIONAL. Backends without such statistics omit it.
|
|
885
|
+
*/
|
|
886
|
+
typeStats?(): Promise<TypeStats[]>;
|
|
887
|
+
/**
|
|
888
|
+
* The indexes the engine wants for `namespace`/`type` (any namespace, not
|
|
889
|
+
* only this one), with each one's leading keys, and the type's size hint.
|
|
890
|
+
* Undefined when the type is unknown. Never changes anything.
|
|
891
|
+
*
|
|
892
|
+
* OPTIONAL. Backends that build no indexes omit it.
|
|
893
|
+
*/
|
|
894
|
+
indexPlan?(type: string, namespace: string): Promise<IndexPlan | undefined>;
|
|
895
|
+
/**
|
|
896
|
+
* Drop index `name` of this namespace's `type`, a signed `propose_index`
|
|
897
|
+
* remove. Only an engine-owned, non-unique index the engine no longer wants
|
|
898
|
+
* (a leftover or a retracted declaration) is dropped; anything else is
|
|
899
|
+
* refused with an error whose `code` is `unknown_index`, `not_engine_owned`,
|
|
900
|
+
* `unique_index` or `still_desired`, and nothing is dropped. A drop that
|
|
901
|
+
* waits longer than `lockTimeoutMs` on another transaction is abandoned with
|
|
902
|
+
* `index_drop_timeout`; the index may then be left invalid, and a retry drops it.
|
|
903
|
+
*
|
|
904
|
+
* OPTIONAL. Backends that build no indexes omit it (the memory dataset):
|
|
905
|
+
* there, `propose_index remove` has no index to find, so it is refused
|
|
906
|
+
* `unknown_index`, and a remove recommendation it names is superseded.
|
|
907
|
+
*/
|
|
908
|
+
dropEngineIndex?(type: string, name: string, opts?: {
|
|
909
|
+
/** Runs once every check has passed, just before the drop; a throw drops nothing. */
|
|
910
|
+
beforeDrop?: () => Promise<void>;
|
|
911
|
+
/** The drop's bound on each lock wait, in ms. Defaults to the backend's own. */
|
|
912
|
+
lockTimeoutMs?: number;
|
|
913
|
+
}): Promise<void>;
|
|
914
|
+
/**
|
|
915
|
+
* Drop the engine-owned indexes of this namespace, after a namespace drop
|
|
916
|
+
* has committed: its types leave the engine, so nothing would remove them.
|
|
917
|
+
* Non-unique ones only, unless `unique`, which the caller passes only when
|
|
918
|
+
* the namespace is declared nowhere (in no code and no live proposal): a
|
|
919
|
+
* declared namespace's types come back, and until the reconciler rebuilds a
|
|
920
|
+
* unique index, writes would not be held to it. Returns the names dropped.
|
|
921
|
+
* Never inside a transaction; a tx-bound instance throws. A lock wait that
|
|
922
|
+
* times out throws `index_drop_timeout`, leaving the rest for
|
|
923
|
+
* `storageReport` to list as orphaned.
|
|
924
|
+
*
|
|
925
|
+
* OPTIONAL. Backends that build no indexes omit it.
|
|
926
|
+
*/
|
|
927
|
+
dropNamespaceIndexes?(opts?: {
|
|
928
|
+
unique?: boolean;
|
|
929
|
+
}): Promise<string[]>;
|
|
930
|
+
/**
|
|
931
|
+
* The entry of this namespace's `type`'s declared `indexes` whose index is
|
|
932
|
+
* named `name`, or undefined when no declaration builds it (a derived or
|
|
933
|
+
* engine index, or none). `propose_index remove` retracts it when it is a
|
|
934
|
+
* proposed type's. Never changes anything.
|
|
935
|
+
*
|
|
936
|
+
* OPTIONAL. Backends that build no indexes omit it.
|
|
937
|
+
*/
|
|
938
|
+
indexDeclarationOf?(type: string, name: string): Promise<IndexDecl | undefined>;
|
|
290
939
|
/**
|
|
291
940
|
* Execute `fn` atomically. All ops performed on the `tx` argument run inside
|
|
292
941
|
* one substrate transaction. If `fn` throws or returns a rejected promise,
|
|
@@ -364,6 +1013,62 @@ interface Dataset {
|
|
|
364
1013
|
* callers chain their own `read()` after resolution.
|
|
365
1014
|
*/
|
|
366
1015
|
resolveShortId(type: string, shortId: number): Promise<string | null>;
|
|
1016
|
+
/**
|
|
1017
|
+
* `count` fresh short ids for `type`, ascending, in one call (pg: one
|
|
1018
|
+
* statement whatever `count`). Like `allocateShortId`, binds nothing.
|
|
1019
|
+
* `count` of 0 returns `[]` and sends nothing.
|
|
1020
|
+
*/
|
|
1021
|
+
allocateShortIds(type: string, count: number): Promise<number[]>;
|
|
1022
|
+
/**
|
|
1023
|
+
* `bindShortId` for many pairs at once (pg: one statement). Idempotent per
|
|
1024
|
+
* pair, as `bindShortId` is. An empty `pairs` does nothing and sends nothing.
|
|
1025
|
+
*/
|
|
1026
|
+
bindShortIds(type: string, pairs: ReadonlyArray<{
|
|
1027
|
+
shortId: number;
|
|
1028
|
+
rowId: string;
|
|
1029
|
+
}>): Promise<void>;
|
|
1030
|
+
/**
|
|
1031
|
+
* Set-wise `resolveShortId` for the LIVE rows among `shortIds` (pg: one
|
|
1032
|
+
* statement). A short id with no binding, or whose row is tombstoned or
|
|
1033
|
+
* purged, is absent from the map: the answer `resolveShortId` then a live
|
|
1034
|
+
* `read` gives, which is how callers resolve today. Repeats in `shortIds`
|
|
1035
|
+
* are deduped. An empty `shortIds` returns an empty map and sends nothing.
|
|
1036
|
+
*/
|
|
1037
|
+
resolveShortIds(type: string, shortIds: readonly number[]): Promise<ReadonlyMap<number, string>>;
|
|
1038
|
+
/**
|
|
1039
|
+
* Multi-row `update`: merges each patch into its LIVE row with today's
|
|
1040
|
+
* semantics (a key absent from the patch keeps its value, `null` clears it;
|
|
1041
|
+
* `id` and `_deletedAt` keys are ignored), stamps `updatedAt` = `now` and
|
|
1042
|
+
* `updatedBy` = `actor` (the anonymous system actor when `null`), as
|
|
1043
|
+
* `conditionalUpdate` does. pg runs one statement whatever the batch size.
|
|
1044
|
+
*
|
|
1045
|
+
* The result has one entry per patch, in order: the merged row, or `null`
|
|
1046
|
+
* when `id` is not live. It never revives a tombstoned row or re-creates a
|
|
1047
|
+
* purged one.
|
|
1048
|
+
*
|
|
1049
|
+
* A repeated `id` is allowed: its patches apply in input order (later keys
|
|
1050
|
+
* win, as sequential patches would) and every slot for that id holds the
|
|
1051
|
+
* final merged row. An empty `patches` returns `[]` and sends nothing.
|
|
1052
|
+
*/
|
|
1053
|
+
patchRows(type: string, patches: ReadonlyArray<{
|
|
1054
|
+
id: Id;
|
|
1055
|
+
patch: Record<string, unknown>;
|
|
1056
|
+
}>, actor: ActorIdentity | null, now: Date): Promise<Array<Row | null>>;
|
|
1057
|
+
/**
|
|
1058
|
+
* Update every live row of `type` matching `where`: merges `set` into each,
|
|
1059
|
+
* as `patchRows` does, and stamps `updatedAt` / `updatedBy`. When more than
|
|
1060
|
+
* `opts.maxMatch` rows match it throws `ResolverFrameError('filter_too_broad')`
|
|
1061
|
+
* and changes nothing; zero matches is `{ count: 0 }`. pg runs one
|
|
1062
|
+
* statement, which locks the matched rows and re-tests `where` on each, so
|
|
1063
|
+
* a row a concurrent writer moved out of the filter is not updated.
|
|
1064
|
+
*/
|
|
1065
|
+
updateWhere?(type: string, where: WhereClause, set: Record<string, unknown>, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
1066
|
+
/**
|
|
1067
|
+
* Tombstone every live row of `type` matching `where`, under the same cap
|
|
1068
|
+
* and lock as `updateWhere`. `rows` are the pre-images. Checks no edges:
|
|
1069
|
+
* the caller gates `restrict` and rolls back.
|
|
1070
|
+
*/
|
|
1071
|
+
deleteWhere?(type: string, where: WhereClause, opts: FilterWriteOptions): Promise<FilterWriteResult>;
|
|
367
1072
|
/**
|
|
368
1073
|
* Inverse of `resolveShortId` — look up the short id assigned to a
|
|
369
1074
|
* given row id. Returns null if no sidecar entry exists (e.g. rows written
|
|
@@ -416,6 +1121,75 @@ interface DatasetRegistry {
|
|
|
416
1121
|
*/
|
|
417
1122
|
dispose?(ns: string): void;
|
|
418
1123
|
}
|
|
1124
|
+
/**
|
|
1125
|
+
* One declared index of a type and its state: as the catalog holds it, or,
|
|
1126
|
+
* while this process defers or runs its build, `pending`, `building` or
|
|
1127
|
+
* `failed`. Filters on an index that is not `valid` scan.
|
|
1128
|
+
*/
|
|
1129
|
+
interface TypeIndexState {
|
|
1130
|
+
name: string;
|
|
1131
|
+
fields: string[];
|
|
1132
|
+
unique: boolean;
|
|
1133
|
+
state: 'valid' | 'building' | 'pending' | 'invalid' | 'failed';
|
|
1134
|
+
outcome: 'created' | 'adopted' | 'swapped' | 'unchanged';
|
|
1135
|
+
/** Why a `failed` index failed: an error code, then a short reason. */
|
|
1136
|
+
error?: string;
|
|
1137
|
+
/** Why a `pending` index was not built: the free-disk check refused it. */
|
|
1138
|
+
reason?: 'insufficient_disk';
|
|
1139
|
+
}
|
|
1140
|
+
/** Where a type's rows live: `table` is set once the type has its table. */
|
|
1141
|
+
interface TypeStorageReport {
|
|
1142
|
+
layout: 'tables';
|
|
1143
|
+
table?: string;
|
|
1144
|
+
indexes: TypeIndexState[];
|
|
1145
|
+
/** Declared fields whose values live in `extra` until they get a column. */
|
|
1146
|
+
pending?: string[];
|
|
1147
|
+
/** Fields no longer declared whose columns are kept. */
|
|
1148
|
+
orphaned?: string[];
|
|
1149
|
+
}
|
|
1150
|
+
/**
|
|
1151
|
+
* One field's outcome in a promotion sweep (`Dataset.promotePendingFields`):
|
|
1152
|
+
* `promoted` (it has its column and every value moved), `busy` (its table's
|
|
1153
|
+
* lock was held past the timeout; retried next sweep) or `failed` (an error,
|
|
1154
|
+
* or the third busy attempt in a row). `attempts` counts this one. A field
|
|
1155
|
+
* another process is sweeping is `busy` with the error `held by another
|
|
1156
|
+
* process`, and its `attempts` is the recorded count, unchanged.
|
|
1157
|
+
*/
|
|
1158
|
+
interface PromotionEvent {
|
|
1159
|
+
kind: 'promoted' | 'busy' | 'failed';
|
|
1160
|
+
namespace: string;
|
|
1161
|
+
type: string;
|
|
1162
|
+
field: string;
|
|
1163
|
+
attempts: number;
|
|
1164
|
+
error?: string;
|
|
1165
|
+
}
|
|
1166
|
+
interface StorageReport {
|
|
1167
|
+
/** `unknown` when the report itself failed. */
|
|
1168
|
+
layout: 'tables' | 'unknown';
|
|
1169
|
+
warnings: string[];
|
|
1170
|
+
/** Worth showing, not a fault: the doctor prints these without failing. */
|
|
1171
|
+
info?: string[];
|
|
1172
|
+
}
|
|
1173
|
+
/** See `Dataset.indexPlan`. */
|
|
1174
|
+
interface IndexPlan {
|
|
1175
|
+
/** Each desired index, its keys in order: a derived index ends with the type's natural order. */
|
|
1176
|
+
indexes: Array<{
|
|
1177
|
+
name: string;
|
|
1178
|
+
keys: Array<[string, 'asc' | 'desc']>;
|
|
1179
|
+
unique: boolean;
|
|
1180
|
+
/** A partial index's predicate beyond `live`: it serves only reads that `eq` each field to its value. */
|
|
1181
|
+
only?: Record<string, boolean | null>;
|
|
1182
|
+
}>;
|
|
1183
|
+
expectedSize?: 'small' | 'large';
|
|
1184
|
+
}
|
|
1185
|
+
/** A connection pool's counts, as `Dataset.poolStats` reports them. */
|
|
1186
|
+
interface PoolStats {
|
|
1187
|
+
connections: number;
|
|
1188
|
+
opening: number;
|
|
1189
|
+
idle: number;
|
|
1190
|
+
leased: number;
|
|
1191
|
+
waiting: number;
|
|
1192
|
+
}
|
|
419
1193
|
//#endregion
|
|
420
1194
|
//#region ../../packages/substrate-types/src/policy.d.ts
|
|
421
1195
|
interface Identity {
|
|
@@ -427,8 +1201,8 @@ interface Identity {
|
|
|
427
1201
|
* tasks: ['read','mutate'] }`; `'*'` is a legal key. Read it through the
|
|
428
1202
|
* `identity-grant.ts` helpers.
|
|
429
1203
|
*
|
|
430
|
-
* A plain object rather than a Map: `Identity` is JSON-serialised
|
|
431
|
-
*
|
|
1204
|
+
* A plain object rather than a Map: `Identity` is JSON-serialised, and a
|
|
1205
|
+
* Map would arrive as `{}` on the far side.
|
|
432
1206
|
*
|
|
433
1207
|
* A bare `{ id }` with no grant (direct-call tests, system actors) is the
|
|
434
1208
|
* no-claim case: `grantOf` resolves it to `null`, and the engine's grant
|
|
@@ -456,7 +1230,7 @@ interface RequestContext {
|
|
|
456
1230
|
* `peerIp` + the operator-configured trusted-proxy allowlist. When the peer
|
|
457
1231
|
* is in the allowlist, this is the leftmost `x-forwarded-for` entry; when
|
|
458
1232
|
* untrusted, this is the peer IP itself. Undefined when the transport doesn't
|
|
459
|
-
* expose peerIp (direct engine unit tests,
|
|
1233
|
+
* expose peerIp (direct engine unit tests, paths without a peer).
|
|
460
1234
|
*/
|
|
461
1235
|
clientIp?: string;
|
|
462
1236
|
/**
|
|
@@ -545,6 +1319,14 @@ interface ResolverArgs {
|
|
|
545
1319
|
* the tx-scoped `dataset` handle instead. Absent on the query/subscribe path.
|
|
546
1320
|
*/
|
|
547
1321
|
resolveDataset?: (ns: string) => Dataset | undefined;
|
|
1322
|
+
/**
|
|
1323
|
+
* Engine-injected on mutate: how many frame entries share this call's
|
|
1324
|
+
* transaction, itself included. A resolver whose effect waits on other
|
|
1325
|
+
* transactions (a concurrent index drop) refuses to share one.
|
|
1326
|
+
*/
|
|
1327
|
+
txEntries?: number;
|
|
1328
|
+
/** Engine-injected on `updateMany<T>` / `deleteMany<T>`: the deployment's caps. */
|
|
1329
|
+
filterWriteLimits?: FilterWriteLimits;
|
|
548
1330
|
}
|
|
549
1331
|
/**
|
|
550
1332
|
* Post-commit write announcement consumed by the engine's subscription bus
|
|
@@ -664,33 +1446,6 @@ interface RequestObservation {
|
|
|
664
1446
|
readonly durationMs: number;
|
|
665
1447
|
}
|
|
666
1448
|
type RequestObserver = (o: RequestObservation) => void;
|
|
667
|
-
interface WsConnection {
|
|
668
|
-
readonly id: string;
|
|
669
|
-
send(frame: Buffer | Uint8Array | string): void;
|
|
670
|
-
/**
|
|
671
|
-
* Transport-level back-pressure seam. Resolves once the
|
|
672
|
-
* socket's write buffer is below its high-water mark — immediately when it
|
|
673
|
-
* already is. The stream route awaits this between chunks so a fast producer
|
|
674
|
-
* paces to a slow consumer instead of growing the send buffer unbounded.
|
|
675
|
-
* Optional: transports without buffer introspection (memory tests) omit it,
|
|
676
|
-
* and the route treats a missing hook as "always drained".
|
|
677
|
-
*/
|
|
678
|
-
drain?(): Promise<void>;
|
|
679
|
-
onMessage(cb: (frame: Buffer) => void): void;
|
|
680
|
-
onClose(cb: (code?: number) => void): void;
|
|
681
|
-
close(code?: number, reason?: string): void;
|
|
682
|
-
/**
|
|
683
|
-
* Register a callback invoked synchronously during graceful server shutdown,
|
|
684
|
-
* BEFORE the underlying socket is closed. Higher layers use this to flush
|
|
685
|
-
* structured frames (e.g. `{ kind: 'end', reason: 'server_restart' }` per
|
|
686
|
-
* active subscription) so clients can short-circuit reconnect backoff
|
|
687
|
-
* instead of seeing an abrupt 1006 drop. Optional — transports without a
|
|
688
|
-
* pre-close hook (memory tests) may omit it; the route layer should
|
|
689
|
-
* tolerate undefined.
|
|
690
|
-
*/
|
|
691
|
-
onShutdown?(cb: (reason: string) => void): void;
|
|
692
|
-
}
|
|
693
|
-
type WsHandler = (req: SubstrateRequest, conn: WsConnection) => void | Promise<void>;
|
|
694
1449
|
interface TlsConfig {
|
|
695
1450
|
cert: string | Buffer;
|
|
696
1451
|
key: string | Buffer;
|
|
@@ -707,7 +1462,6 @@ interface PluginRouter {
|
|
|
707
1462
|
put(path: string, handler: HttpHandler): void;
|
|
708
1463
|
delete(path: string, handler: HttpHandler): void;
|
|
709
1464
|
patch(path: string, handler: HttpHandler): void;
|
|
710
|
-
websocket(path: string, handler: WsHandler): void;
|
|
711
1465
|
}
|
|
712
1466
|
interface SubstrateServer {
|
|
713
1467
|
start(opts?: StartOpts): Promise<{
|
|
@@ -719,7 +1473,6 @@ interface SubstrateServer {
|
|
|
719
1473
|
abortInFlight?: boolean;
|
|
720
1474
|
}): Promise<void>;
|
|
721
1475
|
route(method: HttpMethod, path: string, handler: HttpHandler): void;
|
|
722
|
-
websocket(path: string, handler: WsHandler): void;
|
|
723
1476
|
onError?(hook: (err: Error, req?: SubstrateRequest) => void): void;
|
|
724
1477
|
createPluginRouter(plugin: {
|
|
725
1478
|
name: string;
|
|
@@ -727,17 +1480,16 @@ interface SubstrateServer {
|
|
|
727
1480
|
/**
|
|
728
1481
|
* Abort every in-flight HTTP request's `req.signal` so resolvers cooperatively
|
|
729
1482
|
* bail. Used during graceful shutdown to give the engine a chance to roll
|
|
730
|
-
* back mutations before fastify's drain timeout fires.
|
|
731
|
-
* not affected by this call; their teardown rides on socket close.
|
|
1483
|
+
* back mutations before fastify's drain timeout fires.
|
|
732
1484
|
*/
|
|
733
1485
|
abortAllRequests(reason?: string): void;
|
|
734
1486
|
/**
|
|
735
1487
|
* Register a callback invoked synchronously at the START of `stop()` —
|
|
736
1488
|
* before in-flight requests are aborted and before the transport drains.
|
|
737
1489
|
*
|
|
738
|
-
*
|
|
739
|
-
* a
|
|
740
|
-
*
|
|
1490
|
+
* For routes that hold a response open indefinitely (streams): handlers
|
|
1491
|
+
* flush a terminal frame and end their response, or the drain would wait
|
|
1492
|
+
* forever.
|
|
741
1493
|
*
|
|
742
1494
|
* Additive, not last-one-wins (unlike `onError`): a dropped registration is
|
|
743
1495
|
* a leaked stream. Optional — transports with no graceful phase may omit it,
|
|
@@ -776,14 +1528,28 @@ type PostWriteHook = (row: Row, ctx: RequestContext) => Promise<void>;
|
|
|
776
1528
|
* want the canonical alias should import `Resolver` from this package.
|
|
777
1529
|
*/
|
|
778
1530
|
type RegistryEntryResolver = (ctx: RequestContext, args: ResolverArgs) => Promise<Row | Row[] | ReadResult | AsyncIterable<Row> | null> | AsyncIterable<Row>;
|
|
1531
|
+
/**
|
|
1532
|
+
* Set-wise resolver for a mutate array: one call for every uncached element,
|
|
1533
|
+
* in order, returning one entry per element. Throw `BatchElementError(i, cause)`
|
|
1534
|
+
* to refuse element `i`; any throw rolls back the whole array.
|
|
1535
|
+
*/
|
|
1536
|
+
type BatchResolver = (ctx: RequestContext, args: readonly ResolverArgs[]) => Promise<Array<Row | null>>;
|
|
779
1537
|
/** Input shape for `Registry.register` / `Registry.replace`. */
|
|
780
1538
|
interface RegistryEntryInput {
|
|
781
1539
|
resolver: RegistryEntryResolver;
|
|
1540
|
+
/** When present, a mutate array calls this once instead of `resolver` per element. */
|
|
1541
|
+
batch?: BatchResolver;
|
|
782
1542
|
policy?: Policy;
|
|
783
1543
|
fields?: Record<string, FieldDef>;
|
|
784
1544
|
kind?: RegistryEntryKind;
|
|
785
1545
|
params?: Record<string, FieldDef>;
|
|
786
1546
|
returns?: FieldDef;
|
|
1547
|
+
/** Natural order of a `kind: 'type'` entry; published on its `TypeSchema`. */
|
|
1548
|
+
orderedBy?: OrderedBy;
|
|
1549
|
+
/** Declared indexes of a `kind: 'type'` entry installed at runtime (a proposed type). */
|
|
1550
|
+
indexes?: IndexDecl[];
|
|
1551
|
+
/** A proposed type's size hint; `large` lowers the index advisor's row minimum. */
|
|
1552
|
+
expectedSize?: 'small' | 'large';
|
|
787
1553
|
/**
|
|
788
1554
|
* Semantic verb for autoCRUD-registered mutations. The engine
|
|
789
1555
|
* threads this into `RequestContext.verb` at dispatch so type-/plugin-level
|
|
@@ -791,6 +1557,11 @@ interface RegistryEntryInput {
|
|
|
791
1557
|
* string matching. Omit for type entries and custom mutations.
|
|
792
1558
|
*/
|
|
793
1559
|
verb?: AutoCrudVerb;
|
|
1560
|
+
/**
|
|
1561
|
+
* The type a by-filter mutation (`updateMany<T>` / `deleteMany<T>`) writes.
|
|
1562
|
+
* The engine validates `params.where` against it as a query's `where`.
|
|
1563
|
+
*/
|
|
1564
|
+
filterTarget?: string;
|
|
794
1565
|
}
|
|
795
1566
|
/**
|
|
796
1567
|
* Stored shape returned by `Registry.get` and `Registry.all`. Mirrors the
|
|
@@ -800,6 +1571,8 @@ interface RegistryEntryInput {
|
|
|
800
1571
|
*/
|
|
801
1572
|
interface RegistryEntry {
|
|
802
1573
|
resolver: RegistryEntryResolver;
|
|
1574
|
+
/** Mirrors `RegistryEntryInput.batch`. */
|
|
1575
|
+
batch?: BatchResolver;
|
|
803
1576
|
policy: Policy;
|
|
804
1577
|
fields: Record<string, FieldDef>;
|
|
805
1578
|
kind: RegistryEntryKind;
|
|
@@ -807,8 +1580,16 @@ interface RegistryEntry {
|
|
|
807
1580
|
params: Record<string, FieldDef>;
|
|
808
1581
|
/** Present only for `kind: 'mutation'` entries that declared a return shape. */
|
|
809
1582
|
returns?: FieldDef;
|
|
1583
|
+
/** Mirrors `RegistryEntryInput.orderedBy`. */
|
|
1584
|
+
orderedBy?: OrderedBy;
|
|
1585
|
+
/** Mirrors `RegistryEntryInput.indexes`. */
|
|
1586
|
+
indexes?: IndexDecl[];
|
|
1587
|
+
/** Mirrors `RegistryEntryInput.expectedSize`. */
|
|
1588
|
+
expectedSize?: 'small' | 'large';
|
|
810
1589
|
/** Mirrors `RegistryEntryInput.verb` — present when the registrant stamped one. */
|
|
811
1590
|
verb?: AutoCrudVerb;
|
|
1591
|
+
/** Mirrors `RegistryEntryInput.filterTarget`. */
|
|
1592
|
+
filterTarget?: string;
|
|
812
1593
|
}
|
|
813
1594
|
/**
|
|
814
1595
|
* Canonical per-namespace registry surface, implemented by the concrete
|
|
@@ -943,6 +1724,29 @@ interface EmbedSourceContext {
|
|
|
943
1724
|
id: string;
|
|
944
1725
|
}) => Promise<Row | null>;
|
|
945
1726
|
}
|
|
1727
|
+
/**
|
|
1728
|
+
* A declared index over a type's scalar or crossRef fields, built by the
|
|
1729
|
+
* engine with the same expressions the filter compiler emits.
|
|
1730
|
+
*
|
|
1731
|
+
* - `fields`: key columns in order; `dir` defaults to `asc`. Both directions
|
|
1732
|
+
* sort NULLs last, as `orderBy` does.
|
|
1733
|
+
* - `unique`: refused at build time while duplicate live values exist.
|
|
1734
|
+
* - `where`: always ANDed with "not deleted". `'live'` adds nothing more; a
|
|
1735
|
+
* record adds equality to a boolean (or IS NULL for `null`) on the type's
|
|
1736
|
+
* own fields. Only those operands compile to literals, which a generic plan
|
|
1737
|
+
* needs to match the index predicate.
|
|
1738
|
+
* - `name`: the pg index name to own or adopt; generated when omitted. It may
|
|
1739
|
+
* not end in `__swap`, the reconciler's temporary suffix.
|
|
1740
|
+
*/
|
|
1741
|
+
interface IndexDecl {
|
|
1742
|
+
fields: Array<string | {
|
|
1743
|
+
field: string;
|
|
1744
|
+
dir: 'asc' | 'desc';
|
|
1745
|
+
}>;
|
|
1746
|
+
unique?: boolean;
|
|
1747
|
+
where?: 'live' | Record<string, boolean | null>;
|
|
1748
|
+
name?: string;
|
|
1749
|
+
}
|
|
946
1750
|
/**
|
|
947
1751
|
* Structural shape of a type definition, mirroring `TypeInput` from
|
|
948
1752
|
* @mnmal-ai/substrate-sdk (redeclared to avoid a substrate-types → substrate-sdk import
|
|
@@ -991,6 +1795,14 @@ interface NamespaceTypeDef {
|
|
|
991
1795
|
lexical?: {
|
|
992
1796
|
source: (row: Row) => string | null | undefined | Promise<string | null | undefined>;
|
|
993
1797
|
};
|
|
1798
|
+
/** Composite and unique indexes the engine builds for this type. See {@link IndexDecl}. */
|
|
1799
|
+
indexes?: IndexDecl[];
|
|
1800
|
+
/** The type's natural order, the default read order. See {@link OrderedBy}. */
|
|
1801
|
+
orderedBy?: OrderedBy;
|
|
1802
|
+
/** See the SDK's `TypeInput.ordering`. */
|
|
1803
|
+
ordering?: 'visible';
|
|
1804
|
+
/** Size hint: `large` lowers the index advisor's row minimum for this type. */
|
|
1805
|
+
expectedSize?: 'small' | 'large';
|
|
994
1806
|
[key: string]: unknown;
|
|
995
1807
|
}
|
|
996
1808
|
interface NamespaceDefinition {
|
|
@@ -1010,10 +1822,10 @@ interface NamespaceDefinition {
|
|
|
1010
1822
|
*/
|
|
1011
1823
|
annotations?: Readonly<Record<string, unknown>>;
|
|
1012
1824
|
/**
|
|
1013
|
-
*
|
|
1014
|
-
*
|
|
1015
|
-
*
|
|
1016
|
-
*
|
|
1825
|
+
* @deprecated Ignored. Every declared scalar is a column of its type's
|
|
1826
|
+
* table, so there is nothing left to promote. It was the old layouts' body
|
|
1827
|
+
* keys mirrored into dedicated `rows` columns; it still type-checks, so a
|
|
1828
|
+
* plugin that sets it boots unchanged.
|
|
1017
1829
|
*/
|
|
1018
1830
|
promotedColumns?: Readonly<Record<string, {
|
|
1019
1831
|
column: string;
|
|
@@ -1119,6 +1931,25 @@ interface NamespaceConfig {
|
|
|
1119
1931
|
/** From `NamespaceDefinition.annotations`; surfaced on the schema, never hashed. */
|
|
1120
1932
|
annotations?: Readonly<Record<string, unknown>>;
|
|
1121
1933
|
}
|
|
1934
|
+
/**
|
|
1935
|
+
* What a coordinator's `onCommittedWrites` hook is told: one `(namespace, type,
|
|
1936
|
+
* operation)` group of one committed transaction. `ids` keep the order the
|
|
1937
|
+
* writes were emitted in. `actor` is who the request was attributed to, or
|
|
1938
|
+
* null for a request with no recognisable identity.
|
|
1939
|
+
*/
|
|
1940
|
+
interface CommittedWriteBatch {
|
|
1941
|
+
namespace: string;
|
|
1942
|
+
type: string;
|
|
1943
|
+
operation: 'create' | 'update' | 'delete';
|
|
1944
|
+
actor: ActorIdentity | null;
|
|
1945
|
+
ids: readonly Id[];
|
|
1946
|
+
}
|
|
1947
|
+
/**
|
|
1948
|
+
* Never awaited by the mutate, so keep its synchronous part cheap. A throw or a
|
|
1949
|
+
* rejection is recorded as a `/health` warning (plugin name and time, not the
|
|
1950
|
+
* message) and does not touch the write.
|
|
1951
|
+
*/
|
|
1952
|
+
type CommittedWritesHook = (batch: CommittedWriteBatch) => void | Promise<void>;
|
|
1122
1953
|
/**
|
|
1123
1954
|
* Narrow engine handle threaded into scheduled-task / plugin-route contexts.
|
|
1124
1955
|
* The concrete `Engine` class in `@mnmal-ai/substrate-core` satisfies this
|
|
@@ -1128,6 +1959,14 @@ interface NamespaceConfig {
|
|
|
1128
1959
|
interface EngineHandle {
|
|
1129
1960
|
query(input: EngineInput): Promise<PackEnvelope>;
|
|
1130
1961
|
mutate(input: EngineInput): Promise<PackEnvelope>;
|
|
1962
|
+
/**
|
|
1963
|
+
* Announce writes that were committed outside `mutate`: they reach
|
|
1964
|
+
* subscribers, then every coordinator's `onCommittedWrites`, as a commit
|
|
1965
|
+
* through `mutate` would. This is not a transaction and checks nothing: the
|
|
1966
|
+
* caller guarantees `events` are already committed, since an announced write
|
|
1967
|
+
* that rolls back cannot be taken back.
|
|
1968
|
+
*/
|
|
1969
|
+
announceWrites(events: readonly WriteEvent[], actor: ActorIdentity | null): Promise<void>;
|
|
1131
1970
|
/**
|
|
1132
1971
|
* Evaluate the read policy for a type entry without dispatching it.
|
|
1133
1972
|
* Out-of-band read surfaces (kernel routes returning row data
|
|
@@ -1291,6 +2130,12 @@ interface CoordinatorPlugin {
|
|
|
1291
2130
|
* `NamespaceInstallContext.pluginPolicy`.
|
|
1292
2131
|
*/
|
|
1293
2132
|
policies?: Policy[];
|
|
2133
|
+
/**
|
|
2134
|
+
* Told what each committed transaction wrote, once per `(namespace, type,
|
|
2135
|
+
* operation)` rather than once per row. Never awaited by the mutate, run in
|
|
2136
|
+
* commit order per plugin; a slow hook delays only this plugin's later calls.
|
|
2137
|
+
*/
|
|
2138
|
+
onCommittedWrites?: CommittedWritesHook;
|
|
1294
2139
|
/**
|
|
1295
2140
|
* Post-register lifecycle hook. Fires after every plugin's `install()`
|
|
1296
2141
|
* resolves — use this for resource priming that needs the full namespace
|
|
@@ -1309,7 +2154,7 @@ interface CoordinatorPlugin {
|
|
|
1309
2154
|
* - subprocess children that should receive SIGTERM cleanly
|
|
1310
2155
|
* - long-lived `setInterval` timers (`.unref()` keeps them from
|
|
1311
2156
|
* blocking exit, but explicit teardown is still cleaner for tests)
|
|
1312
|
-
* -
|
|
2157
|
+
* - open subscriptions / outbound connections that should close
|
|
1313
2158
|
* cooperatively rather than dropping mid-request
|
|
1314
2159
|
*
|
|
1315
2160
|
* Errors are caught + logged via the lifecycle metric sink under
|
|
@@ -1329,7 +2174,7 @@ interface CoordinatorPlugin {
|
|
|
1329
2174
|
*/
|
|
1330
2175
|
schedule?: ScheduledTask[];
|
|
1331
2176
|
/**
|
|
1332
|
-
* Mount plugin-scoped HTTP
|
|
2177
|
+
* Mount plugin-scoped HTTP routes. Called once at compose-time with a
|
|
1333
2178
|
* `PluginRouter` pre-prefixed `/substrate/v1/plugins/<name>` by the server impl. The
|
|
1334
2179
|
* router surface matches `PluginRouter` in `./server.ts`.
|
|
1335
2180
|
*
|
|
@@ -1376,6 +2221,12 @@ interface KernelPlugin {
|
|
|
1376
2221
|
* to populate this slot).
|
|
1377
2222
|
*/
|
|
1378
2223
|
migrations?: KernelMigration[];
|
|
2224
|
+
/**
|
|
2225
|
+
* Names of the tables (in the store's schema) this plugin keeps data in.
|
|
2226
|
+
* `substrate-admin migrate-store` copies them alongside the engine's own
|
|
2227
|
+
* tables and refuses a source table that nothing declares.
|
|
2228
|
+
*/
|
|
2229
|
+
storeTables?: readonly string[];
|
|
1379
2230
|
/**
|
|
1380
2231
|
* Filter operators contributed to the where-clause grammar. Each entry
|
|
1381
2232
|
* registers a custom operator (e.g. `embeddingSimilar`) the engine's
|
|
@@ -1406,6 +2257,11 @@ interface KernelPlugin {
|
|
|
1406
2257
|
* coordinators arrive.
|
|
1407
2258
|
*/
|
|
1408
2259
|
onKernelReady?(ctx: KernelLifecycleContext): void | Promise<void>;
|
|
2260
|
+
/**
|
|
2261
|
+
* Stops whatever `onKernelReady` started (timers, workers). The host calls
|
|
2262
|
+
* it before it closes the store, and may call it more than once.
|
|
2263
|
+
*/
|
|
2264
|
+
onKernelStop?(): void | Promise<void>;
|
|
1409
2265
|
/**
|
|
1410
2266
|
* Contribute postWrite hooks for a coordinator namespace at install time.
|
|
1411
2267
|
* Called by the engine ONCE per registered coordinator namespace, AFTER
|
|
@@ -1437,6 +2293,13 @@ interface KernelMigrationContext {
|
|
|
1437
2293
|
* binary is running against the in-memory dataset.
|
|
1438
2294
|
*/
|
|
1439
2295
|
sql: unknown | null;
|
|
2296
|
+
/**
|
|
2297
|
+
* How rows are stored: `'tables'`, one table per type and no `rows` table,
|
|
2298
|
+
* the only layout a store boots. `null` on the in-memory dataset. A
|
|
2299
|
+
* migration that still runs DDL on `rows` fails, and the host names its
|
|
2300
|
+
* plugin (`KernelMigrationLayoutError`).
|
|
2301
|
+
*/
|
|
2302
|
+
layout: 'tables' | null;
|
|
1440
2303
|
metric(name: string, payload?: unknown): void;
|
|
1441
2304
|
}
|
|
1442
2305
|
/**
|
|
@@ -1562,7 +2425,374 @@ interface KernelLifecycleContext {
|
|
|
1562
2425
|
plugin: string;
|
|
1563
2426
|
namespace: string;
|
|
1564
2427
|
}[];
|
|
2428
|
+
/**
|
|
2429
|
+
* Whether this boot may start background work (timers, backfills). False
|
|
2430
|
+
* when the host boots the store only to prepare or copy into it, as
|
|
2431
|
+
* `substrate-admin migrate-store` does: do convergent reconciliation, start
|
|
2432
|
+
* nothing that writes later.
|
|
2433
|
+
*/
|
|
2434
|
+
background: boolean;
|
|
1565
2435
|
metric(name: string, payload?: unknown): void;
|
|
1566
2436
|
}
|
|
1567
2437
|
//#endregion
|
|
1568
|
-
|
|
2438
|
+
//#region ../../packages/substrate-types/src/schema.d.ts
|
|
2439
|
+
/**
|
|
2440
|
+
* One clause of a walk-grammar read, marked index-served or not (typed edge
|
|
2441
|
+
* walks, goal 7). `path` is inside the frame entry, e.g. `['where', '_walk']`.
|
|
2442
|
+
* An unserved clause names the index that would serve it in `recommend`, when
|
|
2443
|
+
* one can be declared.
|
|
2444
|
+
*/
|
|
2445
|
+
interface PlanClause {
|
|
2446
|
+
path: string[];
|
|
2447
|
+
kind: 'hop' | 'filter' | 'order' | 'ref' | 'select' | 'group' | 'agg';
|
|
2448
|
+
served: boolean;
|
|
2449
|
+
recommend?: IndexDecl;
|
|
2450
|
+
/**
|
|
2451
|
+
* On the hop of a pick or a frame `_agg`: how the store evaluates it.
|
|
2452
|
+
* `per-seed` probes once per seed row; `per-hub` computes a pick once per
|
|
2453
|
+
* hub many seeds share; `group-by` aggregates a window in one pass.
|
|
2454
|
+
*/
|
|
2455
|
+
form?: 'per-seed' | 'per-hub' | 'group-by';
|
|
2456
|
+
}
|
|
2457
|
+
/** Words of a natural-language question the parse did not use, and why. */
|
|
2458
|
+
interface Dropped {
|
|
2459
|
+
span: string;
|
|
2460
|
+
reason: string;
|
|
2461
|
+
/**
|
|
2462
|
+
* What the loss changes. `filter`: which rows match (a filter, comparison,
|
|
2463
|
+
* walk, time window or connective), so a count, aggregate, `$ref` or pick
|
|
2464
|
+
* reading that lost it is `unknown`. `order`: an ordering, limit or
|
|
2465
|
+
* projection; the matched rows are the same and the answer stands.
|
|
2466
|
+
*/
|
|
2467
|
+
kind: 'filter' | 'order';
|
|
2468
|
+
}
|
|
2469
|
+
interface FieldDefScalar {
|
|
2470
|
+
kind: 'scalar';
|
|
2471
|
+
/**
|
|
2472
|
+
* `'json'` is an opaque body: msgpack-friendly nested object/array, value
|
|
2473
|
+
* round-trips unchanged, but no per-leaf filtering or ordering. Use it for
|
|
2474
|
+
* freeform payloads (audit details, debug bags). When you need filterable
|
|
2475
|
+
* inner keys, use `field.struct` instead.
|
|
2476
|
+
*/
|
|
2477
|
+
type: 'string' | 'number' | 'int16' | 'int32' | 'int64' | 'boolean' | 'date' | 'json';
|
|
2478
|
+
/**
|
|
2479
|
+
* Tri-state. `true` builds an index (a btree; a GIN for json). Unset means
|
|
2480
|
+
* no index. `false` means no index AND not a search handle: long-form
|
|
2481
|
+
* prose that NL and similar consumers leave out. The field filters either
|
|
2482
|
+
* way. Physical consumers test `=== true`, so never normalise unset to
|
|
2483
|
+
* `false`.
|
|
2484
|
+
*/
|
|
2485
|
+
indexed?: boolean;
|
|
2486
|
+
/**
|
|
2487
|
+
* Metadata: when true, the value may be unset. A string, number, boolean or
|
|
2488
|
+
* date reads back as an absent key then, never `null` (`isColumnField`); a
|
|
2489
|
+
* `json` field keeps an explicit `null`.
|
|
2490
|
+
*/
|
|
2491
|
+
nullable?: boolean;
|
|
2492
|
+
/**
|
|
2493
|
+
* Metadata: when true, this field is populated by the engine (not the caller)
|
|
2494
|
+
* and write attempts that include it MUST be rejected. Used for the
|
|
2495
|
+
* auto-injected `shortId` field. Consumers (autoCRUD create, schema
|
|
2496
|
+
* publisher, client codegen) rely on this flag as a declarative contract —
|
|
2497
|
+
* do not imperatively guard readonly fields without also flipping this.
|
|
2498
|
+
*/
|
|
2499
|
+
readonly?: boolean;
|
|
2500
|
+
/**
|
|
2501
|
+
* Server-managed date flag. Clients may not supply the field in the
|
|
2502
|
+
* indicated phase(s) — autoCRUD rejects it with `client_supplied_server_field`:
|
|
2503
|
+
* - 'create' — on create only
|
|
2504
|
+
* - 'update' — on update only
|
|
2505
|
+
* - 'both' — on create and update
|
|
2506
|
+
* Nothing stamps it automatically: server-side code (a custom resolver or a
|
|
2507
|
+
* system writer such as `applyUpdatePatch`) sets it. A non-nullable,
|
|
2508
|
+
* non-defaulted field gated on create is refused by autoCRUD at install,
|
|
2509
|
+
* since nothing could fill it. Only honoured on `type: 'date'`.
|
|
2510
|
+
*/
|
|
2511
|
+
serverSet?: 'create' | 'update' | 'both';
|
|
2512
|
+
/**
|
|
2513
|
+
* Controlled vocabulary. When present, the value MUST be one of these
|
|
2514
|
+
* strings. Consumed by autoCRUD write-validation (covers memory + pg
|
|
2515
|
+
* uniformly) and surfaced verbatim in the published schema. `type` stays
|
|
2516
|
+
* 'string' — an enum is a constrained string, so pack / client decoder /
|
|
2517
|
+
* where-validation treat it identically with no new branch.
|
|
2518
|
+
*/
|
|
2519
|
+
enum?: readonly string[];
|
|
2520
|
+
/**
|
|
2521
|
+
* Governed vocabulary: alias -> canonical value (each canonical value is in
|
|
2522
|
+
* `enum`). autoCRUD stores the canonical value when an alias is written, and
|
|
2523
|
+
* `where` filters on the field match it, so synonyms converge instead of
|
|
2524
|
+
* sprawling. Matching is case-insensitive. Published in the schema so every
|
|
2525
|
+
* client reads the same table.
|
|
2526
|
+
*/
|
|
2527
|
+
aliases?: Readonly<Record<string, string>>;
|
|
2528
|
+
/**
|
|
2529
|
+
* `false` admits values outside `enum` (aliases are still normalised): a
|
|
2530
|
+
* transition mode for adopting a vocabulary over existing free-string data.
|
|
2531
|
+
* Absent means strict.
|
|
2532
|
+
*/
|
|
2533
|
+
strict?: boolean;
|
|
2534
|
+
/**
|
|
2535
|
+
* Alias (or canonical value) -> sibling fields it implies, e.g.
|
|
2536
|
+
* `done -> { resolution: 'completed' }`. On write the siblings are filled
|
|
2537
|
+
* when the caller omits them and a contradicting value is refused; an
|
|
2538
|
+
* `eq` filter on the alias also matches the implied siblings. Keys match
|
|
2539
|
+
* case-insensitively.
|
|
2540
|
+
*/
|
|
2541
|
+
implies?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
|
|
2542
|
+
/**
|
|
2543
|
+
* Default value applied by autoCRUD `create` when the caller omits this
|
|
2544
|
+
* field. Two effects: (1) the row is written with the default instead of
|
|
2545
|
+
* being absent; (2) it satisfies the non-nullable presence check, so a
|
|
2546
|
+
* non-nullable scalar WITHOUT a default that is omitted on create is
|
|
2547
|
+
* rejected (`missing_required_field`) — that is how "required" is expressed.
|
|
2548
|
+
* Only applied on create (update is a partial patch). The value should match
|
|
2549
|
+
* `type` (booleans for boolean, ISO string for date, etc.).
|
|
2550
|
+
*/
|
|
2551
|
+
default?: string | number | boolean;
|
|
2552
|
+
}
|
|
2553
|
+
interface FieldDefCrossRef {
|
|
2554
|
+
kind: 'crossRef';
|
|
2555
|
+
ns: string;
|
|
2556
|
+
type: string;
|
|
2557
|
+
onDelete: OnDelete;
|
|
2558
|
+
/**
|
|
2559
|
+
* Write-time existence policy. 'reject' refuses a create/update
|
|
2560
|
+
* whose crossRef value points at a non-existent or tombstoned target;
|
|
2561
|
+
* 'allow' is the default when absent. Consulted only at write time, never
|
|
2562
|
+
* stored on the edge. Enforced only for locally-resolvable
|
|
2563
|
+
* target namespaces (compose rejects 'reject' on bridged/unknown targets).
|
|
2564
|
+
*/
|
|
2565
|
+
onMissing?: OnMissing;
|
|
2566
|
+
/**
|
|
2567
|
+
* Substrate-level indexing hint for the edge-source column, mirroring
|
|
2568
|
+
* `FieldDefScalar.indexed`, so the dataset need not infer it from the
|
|
2569
|
+
* presence of the crossRef itself.
|
|
2570
|
+
*/
|
|
2571
|
+
indexed?: boolean;
|
|
2572
|
+
/**
|
|
2573
|
+
* Metadata: when true, the value may be unset. An unset field reads back as an
|
|
2574
|
+
* absent key, never `null` (`isColumnField`).
|
|
2575
|
+
*/
|
|
2576
|
+
nullable?: boolean;
|
|
2577
|
+
/**
|
|
2578
|
+
* Activation-spreading opt-in. When `spread: true`,
|
|
2579
|
+
* recall hits on a row touching this crossRef propagate a damped salience
|
|
2580
|
+
* boost to the linked row (forward direction, X → row X references) AND to
|
|
2581
|
+
* rows whose same field points at the boosted row (backward direction,
|
|
2582
|
+
* X ← rows that reference X). Default off — operators opt in per-edge to
|
|
2583
|
+
* avoid polluting attention with low-signal edges (e.g. Decision.sessionId).
|
|
2584
|
+
*
|
|
2585
|
+
* Damping (typically 0.3) + depth bound (1) are configured on the recall
|
|
2586
|
+
* substrate, not per-field.
|
|
2587
|
+
*/
|
|
2588
|
+
spread?: boolean;
|
|
2589
|
+
/**
|
|
2590
|
+
* Cross-TYPE opt-in for the recall expansion path.
|
|
2591
|
+
* Only meaningful when `spread: true` (the SDK `field.crossRef` builder
|
|
2592
|
+
* rejects `expandCrossType` without `spread` at registration). When both
|
|
2593
|
+
* are set, BACKWARD walks via this edge are allowed to surface neighbours
|
|
2594
|
+
* whose type differs from the request's `scope.type` (e.g. a Concept-typed
|
|
2595
|
+
* query surfaces Decisions via inbound `Decision.establishesConcept`).
|
|
2596
|
+
*
|
|
2597
|
+
* Cross-NAMESPACE expansion is always rejected regardless of this flag.
|
|
2598
|
+
* Forward walks always honour scope strictly: allowing them lets
|
|
2599
|
+
* neighbour-type rows displace the rows that establish them in the ranking.
|
|
2600
|
+
* Default false.
|
|
2601
|
+
*/
|
|
2602
|
+
expandCrossType?: boolean;
|
|
2603
|
+
}
|
|
2604
|
+
interface FieldDefStruct {
|
|
2605
|
+
kind: 'struct';
|
|
2606
|
+
fields: Record<string, FieldDef>;
|
|
2607
|
+
/** Metadata: when true, the value may be `null` or absent. */
|
|
2608
|
+
nullable?: boolean;
|
|
2609
|
+
}
|
|
2610
|
+
interface FieldDefList {
|
|
2611
|
+
kind: 'list';
|
|
2612
|
+
of: FieldDef;
|
|
2613
|
+
/**
|
|
2614
|
+
* When true, the `has` (element membership) operator is backed by a GIN
|
|
2615
|
+
* index on `(body -> '<field>')`. List fields are stored as native JSONB
|
|
2616
|
+
* arrays. Default false — `has` on an unindexed list still works, by
|
|
2617
|
+
* scanning the type's rows. The substrate binary derives the matching GIN
|
|
2618
|
+
* as an idempotent migration at boot from this flag; no hand-authored
|
|
2619
|
+
* migration is needed per field.
|
|
2620
|
+
*/
|
|
2621
|
+
indexed?: boolean;
|
|
2622
|
+
/** Metadata: when true, the value may be `null` or absent. */
|
|
2623
|
+
nullable?: boolean;
|
|
2624
|
+
}
|
|
2625
|
+
type FieldDef = FieldDefScalar | FieldDefCrossRef | FieldDefStruct | FieldDefList;
|
|
2626
|
+
/**
|
|
2627
|
+
* True when the field's value is a typed column: a scalar other than `json` that
|
|
2628
|
+
* the server does not own, or a crossRef. An explicit `null` on such a field
|
|
2629
|
+
* reads back as absent. A json, struct or list field keeps its `null`, and a
|
|
2630
|
+
* readonly scalar such as `shortId` is the server's.
|
|
2631
|
+
*/
|
|
2632
|
+
declare function isColumnField(def: FieldDef): boolean;
|
|
2633
|
+
/**
|
|
2634
|
+
* Per-type schema entry. Fields may be declared at registration time; MVP emits
|
|
2635
|
+
* `fields: {}` for types registered without a field map (e.g. mutations whose
|
|
2636
|
+
* shape is inferred from the resolver's return).
|
|
2637
|
+
*/
|
|
2638
|
+
interface TypeSchema {
|
|
2639
|
+
fields: Record<string, FieldDef>;
|
|
2640
|
+
/** The type's natural order; absent means {@link DEFAULT_ORDERED_BY}. */
|
|
2641
|
+
orderedBy?: OrderedBy;
|
|
2642
|
+
/**
|
|
2643
|
+
* Same-namespace crossRefs that point at this type: `field` on `type`.
|
|
2644
|
+
* Where a walk can come from. Absent when none.
|
|
2645
|
+
*/
|
|
2646
|
+
inboundRefs?: Array<{
|
|
2647
|
+
type: string;
|
|
2648
|
+
field: string;
|
|
2649
|
+
}>;
|
|
2650
|
+
}
|
|
2651
|
+
/**
|
|
2652
|
+
* A type's natural order: exactly one `{ field: direction }` key, the order a
|
|
2653
|
+
* read with no `orderBy` returns. The datasets still append `id` as the tie-break.
|
|
2654
|
+
*/
|
|
2655
|
+
type OrderedBy = Record<string, 'asc' | 'desc'>;
|
|
2656
|
+
/** Natural order of a type that declares none: newest first. */
|
|
2657
|
+
declare const DEFAULT_ORDERED_BY: OrderedBy;
|
|
2658
|
+
/** The declared natural order, or {@link DEFAULT_ORDERED_BY}. */
|
|
2659
|
+
declare function naturalOrderOf(schema: Pick<TypeSchema, 'orderedBy'>): OrderedBy;
|
|
2660
|
+
/**
|
|
2661
|
+
* Per-mutation schema entry. `params` describes the input shape a client
|
|
2662
|
+
* sends; `returns` describes the shape a client decodes on success. Both are
|
|
2663
|
+
* required — an empty param bag surfaces as `{}`, never as an absent key.
|
|
2664
|
+
*
|
|
2665
|
+
* `returns` is typically a `FieldDefStruct` describing the row shape the
|
|
2666
|
+
* mutation produces (e.g. `create<T>` returns the inserted row; `delete<T>`
|
|
2667
|
+
* returns `{ id, deleted }`). `get<T>` and `update<T>` mark the struct
|
|
2668
|
+
* `nullable: true` because an id-miss legitimately produces `null`.
|
|
2669
|
+
*
|
|
2670
|
+
* Mutations registered without explicit `returns` metadata receive a sentinel
|
|
2671
|
+
* fallback (`{ kind: 'scalar', type: 'string', nullable: true }`) so substrate-pack
|
|
2672
|
+
* can still round-trip the response — clients treating it as "unknown shape"
|
|
2673
|
+
* should fall back to JSON passthrough.
|
|
2674
|
+
*/
|
|
2675
|
+
interface MutationSchema {
|
|
2676
|
+
params: Record<string, FieldDef>;
|
|
2677
|
+
returns: FieldDef;
|
|
2678
|
+
/**
|
|
2679
|
+
* Present when the mutation writes rows of its namespace's type (an autoCRUD
|
|
2680
|
+
* create or update): with no `fields`, its result is `{ id, shortId }`.
|
|
2681
|
+
*/
|
|
2682
|
+
writesRows?: true;
|
|
2683
|
+
}
|
|
2684
|
+
/**
|
|
2685
|
+
* The published schema shape surfaced at `GET /substrate/v1/schema`. Spec: §4.2, §6.1,
|
|
2686
|
+
* §7.1. `schemaVersion` is the 12-char SHA-256 prefix over the canonicalized
|
|
2687
|
+
* schema JSON and travels on every response envelope (§7.0) so the client can
|
|
2688
|
+
* detect drift.
|
|
2689
|
+
*/
|
|
2690
|
+
interface Schema {
|
|
2691
|
+
schemaVersion: string;
|
|
2692
|
+
types: Record<string, TypeSchema>;
|
|
2693
|
+
mutations: Record<string, MutationSchema>;
|
|
2694
|
+
/** Present (true) on substrate-contributed virtual namespaces: no autoCRUD, no storage, query/mutate one-shot only. */
|
|
2695
|
+
virtual?: true;
|
|
2696
|
+
/**
|
|
2697
|
+
* The namespace's opaque per-consumer metadata (`defineNamespace` option).
|
|
2698
|
+
* Not part of `schemaVersion`: an annotations-only change does not move it.
|
|
2699
|
+
*/
|
|
2700
|
+
annotations?: Readonly<Record<string, unknown>>;
|
|
2701
|
+
}
|
|
2702
|
+
/**
|
|
2703
|
+
* Per-key shape. A single frame resolves to `'single' | 'list'`, or for a
|
|
2704
|
+
* walk read to `'count'` (`data[key]` is `{ count }`) or `'groups'`
|
|
2705
|
+
* (`data[key]` is `{ groups, truncated? }`). A batched mutate op-key (array
|
|
2706
|
+
* of frames) resolves to `Array<'single' | 'list'>` — one shape per frame, in
|
|
2707
|
+
* frame-array order. The decoder keys off the discriminator: string → single
|
|
2708
|
+
* frame; array → batched.
|
|
2709
|
+
*/
|
|
2710
|
+
type EnvelopeShape = 'single' | 'list' | 'count' | 'groups' | Array<'single' | 'list'>;
|
|
2711
|
+
/**
|
|
2712
|
+
* The response envelope. Spec: §7.0.
|
|
2713
|
+
*
|
|
2714
|
+
* Query data values are positionally encoded using the client-sent `FieldInput`
|
|
2715
|
+
* selection; mutation data values are positionally encoded using the declared
|
|
2716
|
+
* `MutationSchema.returns` (§4.2) — mutations don't carry a FieldInput
|
|
2717
|
+
* since there's no field selection on a return row.
|
|
2718
|
+
*/
|
|
2719
|
+
interface PackEnvelope {
|
|
2720
|
+
schemaVersion: string;
|
|
2721
|
+
data: Record<string, unknown>;
|
|
2722
|
+
shapes: Record<string, EnvelopeShape>;
|
|
2723
|
+
_meta?: Record<string, unknown>;
|
|
2724
|
+
_pagination?: Record<string, {
|
|
2725
|
+
nextCursor?: string;
|
|
2726
|
+
hasMore: boolean;
|
|
2727
|
+
}>;
|
|
2728
|
+
/**
|
|
2729
|
+
* Per-top-level-key completeness. ABSENT MEANS COMPLETE — callers that
|
|
2730
|
+
* predate this field stay correct without change.
|
|
2731
|
+
*
|
|
2732
|
+
* Set when a bridged key could not be fully resolved (§6.5 "reads never
|
|
2733
|
+
* fail" means such a read still returns 200 with orphan markers). The
|
|
2734
|
+
* per-row `__orphan` marker says a row is missing; this says the RESULT SET
|
|
2735
|
+
* is partial, which a consumer cannot otherwise distinguish from an
|
|
2736
|
+
* genuinely empty result.
|
|
2737
|
+
*/
|
|
2738
|
+
_completeness?: Record<string, {
|
|
2739
|
+
complete: boolean;
|
|
2740
|
+
unreachable?: string[];
|
|
2741
|
+
}>;
|
|
2742
|
+
/**
|
|
2743
|
+
* Non-fatal read diagnostics, keyed by top-level frame key. ABSENT MEANS
|
|
2744
|
+
* NOTHING TO REPORT — callers that predate this field stay correct without
|
|
2745
|
+
* change, same contract as `_completeness`.
|
|
2746
|
+
*
|
|
2747
|
+
* Deliberately NOT `errors`: a consumer doing `if (env.errors) throw` would
|
|
2748
|
+
* start failing on reads that succeeded.
|
|
2749
|
+
*
|
|
2750
|
+
* A client that maps rows into declared interfaces MUST surface this (log,
|
|
2751
|
+
* attach to the result, or throw in development): an unknown projection key
|
|
2752
|
+
* arrives as `null`, satisfies the interface, and the read looks correct.
|
|
2753
|
+
*/
|
|
2754
|
+
_diagnostics?: Record<string, {
|
|
2755
|
+
/**
|
|
2756
|
+
* Projection keys the type does not declare. The read still returned
|
|
2757
|
+
* every row; each unknown key materialises as `null` on all of them,
|
|
2758
|
+
* indistinguishable from a declared field that is null everywhere.
|
|
2759
|
+
*/
|
|
2760
|
+
unknownProjectionFields?: string[];
|
|
2761
|
+
/**
|
|
2762
|
+
* The where-clause reached the substrate without being schema-validated,
|
|
2763
|
+
* because the type is registered but absent from its namespace's
|
|
2764
|
+
* published schema (e.g. runtime-created types). The result is still
|
|
2765
|
+
* correct — substrates refuse a predicate they cannot honour — but the
|
|
2766
|
+
* engine's operator and operand check did not run.
|
|
2767
|
+
*/
|
|
2768
|
+
filterValidationSkipped?: string;
|
|
2769
|
+
/**
|
|
2770
|
+
* A walk-grammar read's clauses, each marked index-served or not
|
|
2771
|
+
* (typed edge walks, goal 7). Annotation only: nothing is refused on
|
|
2772
|
+
* it. Absent on ordinary reads, and when the store has no index plan.
|
|
2773
|
+
*/
|
|
2774
|
+
plan?: PlanClause[];
|
|
2775
|
+
}>;
|
|
2776
|
+
errors?: Array<{
|
|
2777
|
+
message: string;
|
|
2778
|
+
path?: string[];
|
|
2779
|
+
code?: string;
|
|
2780
|
+
/**
|
|
2781
|
+
* Optional structured payload — populated when the underlying error class
|
|
2782
|
+
* carries one (e.g. `ResolverFrameError({ field: '...' })`).
|
|
2783
|
+
*/
|
|
2784
|
+
details?: Record<string, unknown>;
|
|
2785
|
+
}>;
|
|
2786
|
+
}
|
|
2787
|
+
/**
|
|
2788
|
+
* Client-sent field selection tree. Defined here rather than in
|
|
2789
|
+
* `@mnmal-ai/substrate-pack` so subscription and streaming machinery (§5.4, §5.5)
|
|
2790
|
+
* can reference the same shape without adding substrate-pack to their dependency
|
|
2791
|
+
* set — substrate-pack already imports from types, so moving the type upward
|
|
2792
|
+
* avoids the would-be cycle.
|
|
2793
|
+
*/
|
|
2794
|
+
type FieldInput = {
|
|
2795
|
+
[field: string]: true | FieldInput;
|
|
2796
|
+
};
|
|
2797
|
+
//#endregion
|
|
2798
|
+
export { VirtualMutationDef as $, WalkAgg as $t, KernelLifecycleContext as A, OnMissing as An, DatasetRegistry as At, NamespaceTypeDef as B, WriteRow as Bn, IndexPlan as Bt, EmbedSourceContext as C, CanDeleteResult as Cn, RowFilterObligation as Ct, FilterOperatorDef as D, EdgeWriteInput as Dn, ConditionalUpdateResult as Dt, EngineInput as E, EdgeRef as En, AggFn as Et, KernelRouteClaim as F, IdentityKind as Fn, FilterCapabilities as Ft, Registry as G, ReadParams as Gt, PluginRouteContext as H, OrderByClause as Ht, McpToolRegistration as I, ROW_METADATA_FIELDS as In, FilterWriteLimits as It, RegistryEntryInput as J, StorageReport as Jt, RegistryBase as K, ReadResult as Kt, NamespaceConfig as L, Row as Ln, FilterWriteOptions as Lt, KernelMigrationContext as M, CLIENT_SUPPLIED_SERVER_FIELD as Mn, DropResult as Mt, KernelNamespaceContribution as N, ClientSuppliedServerFieldError as Nn, FieldKind as Nt, FrameEntry as O, EdgesStore as On, DEFAULT_FILTER_WRITE_LIMITS as Ot, KernelPlugin as P, Id as Pn, FieldPredicate as Pt, ScheduledTaskContext as Q, UpdateFieldRef as Qt, NamespaceDefinition as R, RowMetadata as Rn, FilterWriteResult as Rt, DropParticipant as S, FunctionSig as Sn, ResolverReturn as St, EngineHandle as T, EdgePatch as Tn, WriteEvent as Tt, PostWriteHook as U, PoolStats as Ut, PluginLifecycleContext as V, assertNoRepeatedIds as Vn, NestedSelection as Vt, QualifiedFrame as W, PromotionEvent as Wt, RegistryEntryResolver as X, TypeIndexState as Xt, RegistryEntryKind as Y, TxScopeHandles as Yt, ScheduledTask as Z, TypeStorageReport as Zt, naturalOrderOf as _, EXPR_AGGREGATES as _n, PolicyDecision as _t, FieldDefCrossRef as a, WriteOptions as an, RequestObserver as at, CommittedWritesHook as b, Expr as bn, Resolver as bt, FieldDefStruct as c, ResolveObservation as cn, SubstrateRequest as ct, OrderedBy as d, RuntimeErrors as dn, TlsConfig as dt, WalkAggOperand as en, VirtualTypeDef as et, PackEnvelope as f, RuntimeMetrics as fn, AfterTxWork as ft, isColumnField as g, DATE_UNITS as gn, Policy as gt, TypeSchema as h, ArgType as hn, Obligation as ht, FieldDef as i, WhereClause as in, RequestObservation as it, KernelMigration as j, ActorIdentity as jn, DeleteResult as jt, IndexDecl as k, OnDelete as kn, Dataset as kt, FieldInput as l, ResolverStat as ln, SubstrateResponse as lt, Schema as m, TypeStats as mn, Identity as mt, Dropped as n, WalkNode as nn, HttpMethod as nt, FieldDefList as o, WriteResult as on, RuntimeOp as ot, PlanClause as p, SlowRequest as pn, AutoCrudVerb as pt, RegistryEntry as q, RefOperand as qt, EnvelopeShape as r, WalkPick as rn, PluginRouter as rt, FieldDefScalar as s, ProcessStat as sn, StartOpts as st, DEFAULT_ORDERED_BY as t, WalkAggPredicate as tn, HttpHandler as tt, MutationSchema as u, RuntimeErrorEntry as un, SubstrateServer as ut, BatchResolver as v, EXPR_FUNCTIONS as vn, PolicyProbeContext as vt, EncodeContext as w, Edge as wn, TypedResolver as wt, CoordinatorPlugin as x, ExprType as xn, ResolverArgs as xt, CommittedWriteBatch as y, EXPR_LIMITS as yn, RequestContext as yt, NamespaceInstallContext as z, RowMetadataField as zn, FrameAgg as zt };
|