@mnmal-ai/substrate 0.0.0 → 1.0.0-alpha.0
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/LICENSE +202 -0
- package/README.md +118 -1
- package/dist/agent-token-BIboWOU0.js +200 -0
- package/dist/client.d.ts +782 -0
- package/dist/client.js +7 -0
- package/dist/cluster-worker.js +35 -0
- package/dist/content-type-C7T28xNb.js +25 -0
- package/dist/dataset-BXkus75W.js +1527 -0
- package/dist/env-utils-B7SGmoeJ.js +21 -0
- package/dist/errors-D4vKuwz8.d.ts +130 -0
- package/dist/fake-DUVtKVSE.js +36 -0
- package/dist/index-D7mSOFlM.d.ts +69 -0
- package/dist/pack.d.ts +192 -0
- package/dist/pack.js +5 -0
- package/dist/plugin-j1jt1l3n.js +3844 -0
- package/dist/plugin-t2g2wX0b.d.ts +1568 -0
- package/dist/proposals-bootstrap.js +37 -0
- package/dist/proposals.config.schema.json +20 -0
- package/dist/proposals.d.ts +118 -0
- package/dist/proposals.default-config.json +4 -0
- package/dist/proposals.js +4 -0
- package/dist/recall-bootstrap.js +451 -0
- package/dist/recall.config.schema.json +232 -0
- package/dist/recall.d.ts +1981 -0
- package/dist/recall.default-config.json +4 -0
- package/dist/recall.js +5 -0
- package/dist/repl-C52wyfMs.js +2213 -0
- package/dist/row-ByLFE2Wx.d.ts +719 -0
- package/dist/row-DK7lPZVe.js +732 -0
- package/dist/runtime-metrics-DwpDJ8vz.d.ts +159 -0
- package/dist/schema-g4FQLr0V.d.ts +433 -0
- package/dist/sdk.d.ts +694 -0
- package/dist/sdk.js +112 -0
- package/dist/src-C4DzaIQZ.js +837 -0
- package/dist/src-CrEgiMJQ.js +1015 -0
- package/dist/src-CzxvmhFn.js +2327 -0
- package/dist/src-D88LvCX8.js +1797 -0
- package/dist/src-D91yij6C.js +13523 -0
- package/dist/src-DuopV8u7.js +2408 -0
- package/dist/substrate-admin.js +808 -0
- package/dist/substrate.js +5477 -0
- package/dist/testing.d.ts +1240 -0
- package/dist/testing.js +702 -0
- package/dist/types-8c0gtnd2.d.ts +35 -0
- package/dist/ws-C72iVS5T.d.ts +143 -0
- package/package.json +117 -4
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
import { E as Row, h as EdgeRef, l as PackEnvelope, u as Schema } from "./schema-g4FQLr0V.js";
|
|
2
|
+
//#region ../../packages/substrate-types/src/bridge.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* Per-frame bucket sent to a bridge. Same shape as `QualifiedFrame` in the
|
|
5
|
+
* engine; redeclared here so types has no dependency on core.
|
|
6
|
+
*/
|
|
7
|
+
type BridgeFrame = Record<string, {
|
|
8
|
+
params?: Record<string, unknown>;
|
|
9
|
+
fields?: Record<string, unknown>;
|
|
10
|
+
idempotencyKey?: string;
|
|
11
|
+
}>;
|
|
12
|
+
interface BridgeClient {
|
|
13
|
+
readonly name: string;
|
|
14
|
+
readonly baseUrl: string;
|
|
15
|
+
/** Fetches the remote's federated schema. Throws `BridgeUnreachableError` on network failure. */
|
|
16
|
+
federatedSchema(): Promise<Record<string, Schema>>;
|
|
17
|
+
/** Proxy a query frame to the remote. */
|
|
18
|
+
query(frame: BridgeFrame): Promise<PackEnvelope>;
|
|
19
|
+
/** Proxy a mutate frame to the remote. */
|
|
20
|
+
mutate(frame: BridgeFrame): Promise<PackEnvelope>;
|
|
21
|
+
/**
|
|
22
|
+
* Read a single row by (type, id) from a remote namespace. Used by sweep's
|
|
23
|
+
* resolveTarget to classify EXISTS/DELETED/MISSING for bridged edges.
|
|
24
|
+
* Returns null if the row doesn't exist. Throws `BridgeUnreachableError`
|
|
25
|
+
* when the remote can't be reached at all.
|
|
26
|
+
*/
|
|
27
|
+
readRow(ref: EdgeRef): Promise<Row | null>;
|
|
28
|
+
/**
|
|
29
|
+
* Fast-path health signal. Returns the cached reachability verdict from the
|
|
30
|
+
* last probe — the bridge runs periodic health checks and updates this.
|
|
31
|
+
*/
|
|
32
|
+
isReachable(): boolean;
|
|
33
|
+
/** Release any timers / pending work. Idempotent. */
|
|
34
|
+
dispose(): void;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Credential a bridge presents to its remote. Carries references only — a path
|
|
38
|
+
* to key material and the registered principal — never the key itself, so the
|
|
39
|
+
* shape is safe to hold in config and log-adjacent structures.
|
|
40
|
+
*/
|
|
41
|
+
interface BridgeCredential {
|
|
42
|
+
/** Path to an Ed25519 private key in PEM form. */
|
|
43
|
+
keyPath: string;
|
|
44
|
+
/** Registered kid at the remote — the principal this bridge authenticates as. */
|
|
45
|
+
kid: string;
|
|
46
|
+
/**
|
|
47
|
+
* Expected URL origin of the remote this credential may be presented to,
|
|
48
|
+
* as `scheme://host[:port]` (compare with `new URL(url).origin`, never by
|
|
49
|
+
* raw string — trailing slashes and default ports would produce false
|
|
50
|
+
* mismatches).
|
|
51
|
+
*
|
|
52
|
+
* REQUIRED, with no opt-out. Discovery supplies the bridge URL off the
|
|
53
|
+
* wire, so without an origin binding an injected topology entry naming a
|
|
54
|
+
* provisioned coordinator would redirect a signed bearer token to an
|
|
55
|
+
* attacker-controlled host.
|
|
56
|
+
*/
|
|
57
|
+
origin: string;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Credential lookup, keyed by COORDINATOR name (not namespace) — one
|
|
61
|
+
* coordinator may serve several namespaces under one credential, per §5.8's
|
|
62
|
+
* "one bridge registration, one set of credentials".
|
|
63
|
+
*
|
|
64
|
+
* This is the federation allowlist. A miss means no bridge is formed at all,
|
|
65
|
+
* which is what makes discovery non-authoritative: a topology entry naming an
|
|
66
|
+
* unprovisioned peer cannot cause traffic to flow to it. The credential's
|
|
67
|
+
* `origin` completes that property — a hit still forms no bridge unless the
|
|
68
|
+
* advertised URL matches the origin the credential was provisioned for.
|
|
69
|
+
*/
|
|
70
|
+
interface BridgeCredentialStore {
|
|
71
|
+
get(bridgeName: string): BridgeCredential | undefined;
|
|
72
|
+
}
|
|
73
|
+
//#endregion
|
|
74
|
+
//#region ../../packages/substrate-types/src/runtime-metrics.d.ts
|
|
75
|
+
/** Per-key resolver latency and error counts, as served by GET /substrate/v1/metrics. */
|
|
76
|
+
interface ResolverStat {
|
|
77
|
+
kind: 'query' | 'mutate';
|
|
78
|
+
calls: number;
|
|
79
|
+
errors: number;
|
|
80
|
+
p50Ms: number;
|
|
81
|
+
p99Ms: number;
|
|
82
|
+
maxMs: number;
|
|
83
|
+
lastAt: string;
|
|
84
|
+
}
|
|
85
|
+
interface ProcessStat {
|
|
86
|
+
rssMB: number;
|
|
87
|
+
heapUsedMB: number;
|
|
88
|
+
cpuUserMs: number;
|
|
89
|
+
cpuSystemMs: number;
|
|
90
|
+
eventLoopLagP99Ms: number;
|
|
91
|
+
inFlight: number;
|
|
92
|
+
}
|
|
93
|
+
interface SlowRequest {
|
|
94
|
+
key: string;
|
|
95
|
+
kind: 'query' | 'mutate';
|
|
96
|
+
durationMs: number;
|
|
97
|
+
at: string;
|
|
98
|
+
}
|
|
99
|
+
interface RuntimeErrorEntry {
|
|
100
|
+
at: string;
|
|
101
|
+
op: 'query' | 'mutate';
|
|
102
|
+
key: string;
|
|
103
|
+
code: string;
|
|
104
|
+
message: string;
|
|
105
|
+
/** The verified identity's id, or `'anonymous'`. */
|
|
106
|
+
caller?: string;
|
|
107
|
+
/** Present when consecutive identical `(unknown)` failures were merged into this entry. */
|
|
108
|
+
count?: number;
|
|
109
|
+
}
|
|
110
|
+
interface RuntimeErrors {
|
|
111
|
+
since: string;
|
|
112
|
+
errors: RuntimeErrorEntry[];
|
|
113
|
+
}
|
|
114
|
+
interface ResolveObservation {
|
|
115
|
+
key: string;
|
|
116
|
+
kind: 'query' | 'mutate';
|
|
117
|
+
durationMs: number;
|
|
118
|
+
ok: boolean;
|
|
119
|
+
code?: string;
|
|
120
|
+
message?: string;
|
|
121
|
+
/** The verified identity's id; absent for an anonymous caller. */
|
|
122
|
+
caller?: string;
|
|
123
|
+
}
|
|
124
|
+
/** What GET /substrate/v1/metrics returns. The new fields are optional so an older server still type-checks. */
|
|
125
|
+
interface RuntimeMetrics {
|
|
126
|
+
since: string;
|
|
127
|
+
requests: {
|
|
128
|
+
query: {
|
|
129
|
+
total: number;
|
|
130
|
+
ok: number;
|
|
131
|
+
error: number;
|
|
132
|
+
durationMsSum: number;
|
|
133
|
+
durationMsMax: number;
|
|
134
|
+
};
|
|
135
|
+
mutate: {
|
|
136
|
+
total: number;
|
|
137
|
+
ok: number;
|
|
138
|
+
error: number;
|
|
139
|
+
durationMsSum: number;
|
|
140
|
+
durationMsMax: number;
|
|
141
|
+
};
|
|
142
|
+
};
|
|
143
|
+
subscriptions: {
|
|
144
|
+
active: number;
|
|
145
|
+
maxQueueDepth?: number;
|
|
146
|
+
entries?: {
|
|
147
|
+
id: string;
|
|
148
|
+
ns: string;
|
|
149
|
+
type: string;
|
|
150
|
+
queueLength: number;
|
|
151
|
+
}[];
|
|
152
|
+
};
|
|
153
|
+
events: Record<string, number>;
|
|
154
|
+
resolvers?: Record<string, ResolverStat>;
|
|
155
|
+
process?: ProcessStat;
|
|
156
|
+
slowest?: SlowRequest[];
|
|
157
|
+
}
|
|
158
|
+
//#endregion
|
|
159
|
+
export { RuntimeErrors as a, BridgeClient as c, BridgeFrame as d, RuntimeErrorEntry as i, BridgeCredential as l, ResolveObservation as n, RuntimeMetrics as o, ResolverStat as r, SlowRequest as s, ProcessStat as t, BridgeCredentialStore as u };
|
|
@@ -0,0 +1,433 @@
|
|
|
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
|
+
[field: string]: unknown;
|
|
16
|
+
}
|
|
17
|
+
type IdentityKind = 'agent' | 'user' | 'system';
|
|
18
|
+
/**
|
|
19
|
+
* Row-attribution actor — records who created or last updated a row.
|
|
20
|
+
* Distinct from the auth `Identity` in `policy.ts` (JWT principal).
|
|
21
|
+
*/
|
|
22
|
+
interface ActorIdentity {
|
|
23
|
+
readonly kind: IdentityKind;
|
|
24
|
+
readonly id: string;
|
|
25
|
+
}
|
|
26
|
+
interface RowMetadata {
|
|
27
|
+
readonly createdAt: string | null;
|
|
28
|
+
readonly updatedAt: string | null;
|
|
29
|
+
readonly createdBy: ActorIdentity | null;
|
|
30
|
+
readonly updatedBy: ActorIdentity | null;
|
|
31
|
+
}
|
|
32
|
+
declare const CLIENT_SUPPLIED_SERVER_FIELD: 'client_supplied_server_field';
|
|
33
|
+
type ClientSuppliedServerFieldError = typeof CLIENT_SUPPLIED_SERVER_FIELD;
|
|
34
|
+
declare const ROW_METADATA_FIELDS: readonly ['createdAt', 'updatedAt', 'createdBy', 'updatedBy'];
|
|
35
|
+
type RowMetadataField = (typeof ROW_METADATA_FIELDS)[number];
|
|
36
|
+
//#endregion
|
|
37
|
+
//#region ../../packages/substrate-types/src/edge.d.ts
|
|
38
|
+
type OnDelete = 'set_null' | 'cascade' | 'restrict' | 'orphan';
|
|
39
|
+
type OnMissing = 'reject' | 'allow';
|
|
40
|
+
interface EdgeRef {
|
|
41
|
+
ns: string;
|
|
42
|
+
type: string;
|
|
43
|
+
id: Id;
|
|
44
|
+
bridged?: boolean;
|
|
45
|
+
}
|
|
46
|
+
interface Edge {
|
|
47
|
+
id: string;
|
|
48
|
+
from: EdgeRef;
|
|
49
|
+
to: EdgeRef;
|
|
50
|
+
fieldName: string;
|
|
51
|
+
policy: OnDelete;
|
|
52
|
+
createdAt: Date;
|
|
53
|
+
deletedAt?: Date;
|
|
54
|
+
lastSweptAt?: Date;
|
|
55
|
+
blocked?: boolean;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Narrow patch type for `EdgesStore.update`. Immutable fields (from, to,
|
|
59
|
+
* policy, fieldName, createdAt, id-as-identity) cannot be changed post-write.
|
|
60
|
+
* `deletedAt` is managed exclusively by `tombstone(id)`.
|
|
61
|
+
*/
|
|
62
|
+
type EdgePatch = Pick<Edge, 'id'> & Partial<Pick<Edge, 'lastSweptAt' | 'blocked'>>;
|
|
63
|
+
type EdgeWriteInput = Omit<Edge, 'id' | 'createdAt' | 'lastSweptAt' | 'deletedAt' | 'blocked'>;
|
|
64
|
+
type CanDeleteResult = {
|
|
65
|
+
ok: true;
|
|
66
|
+
} | {
|
|
67
|
+
ok: false;
|
|
68
|
+
blockedBy: Edge[];
|
|
69
|
+
};
|
|
70
|
+
interface EdgesStore {
|
|
71
|
+
/**
|
|
72
|
+
* Stable identifier for the storage substrate this edges store wraps.
|
|
73
|
+
* Parallels `Dataset.txScopeId` (spec §5.3). When an `EdgesStore`
|
|
74
|
+
* and a `Dataset` share a `txScopeId`, the engine enlists edge
|
|
75
|
+
* mutations into the dataset's `withScopedTransaction`, making
|
|
76
|
+
* row-tombstone + edge-tombstone within one frame atomic.
|
|
77
|
+
*
|
|
78
|
+
* Convention:
|
|
79
|
+
* - pg: derived from the `postgres.Sql` pool reference identity. A
|
|
80
|
+
* `PgEdgesStore` constructed against the same `Sql` as a
|
|
81
|
+
* `PgDataset` advertises the same `txScopeId`.
|
|
82
|
+
* - memory: unique per `MemoryEdgesStore` instance. A memory edges
|
|
83
|
+
* store can never coalesce into a dataset's substrate tx; the engine
|
|
84
|
+
* falls back to nested independent transactions for that case.
|
|
85
|
+
*/
|
|
86
|
+
readonly txScopeId: string;
|
|
87
|
+
write(input: EdgeWriteInput): Promise<Edge>;
|
|
88
|
+
tombstone(id: string, at?: Date): Promise<void>;
|
|
89
|
+
update(patch: EdgePatch): Promise<void>;
|
|
90
|
+
readNextBatch(cursorId: string | null, size: number): Promise<{
|
|
91
|
+
edges: Edge[];
|
|
92
|
+
lastId: string | null;
|
|
93
|
+
}>;
|
|
94
|
+
findEdgesTo(ref: EdgeRef): Promise<Edge[]>;
|
|
95
|
+
/**
|
|
96
|
+
* Batched `findEdgesTo`: all live (non-tombstoned) inbound edges whose `to`
|
|
97
|
+
* matches ANY of `refs`, in a single round-trip. Empty `refs` yields an
|
|
98
|
+
* empty result. Callers group the flat result by `edge.to` themselves.
|
|
99
|
+
*/
|
|
100
|
+
findEdgesToMany(refs: readonly EdgeRef[]): Promise<Edge[]>;
|
|
101
|
+
findEdgesFrom(ref: EdgeRef): Promise<Edge[]>;
|
|
102
|
+
canDelete(ref: EdgeRef): Promise<CanDeleteResult>;
|
|
103
|
+
findBlocked(): Promise<Edge[]>;
|
|
104
|
+
/**
|
|
105
|
+
* List live (non-tombstoned) edges where `from_ns === namespace` OR
|
|
106
|
+
* `to_ns === namespace`. Used by drop-namespace to detect dangling refs
|
|
107
|
+
* when `cascade === 'refuse'`. Bounded by `limit` — callers only need
|
|
108
|
+
* enough to decide + surface a sample.
|
|
109
|
+
*/
|
|
110
|
+
findEdgesTouchingNamespace(namespace: string, limit: number): Promise<Edge[]>;
|
|
111
|
+
/**
|
|
112
|
+
* List live (non-tombstoned) edges where either endpoint matches
|
|
113
|
+
* `(namespace, type)`. Used by drop-type for the same cascade-refuse check.
|
|
114
|
+
*/
|
|
115
|
+
findEdgesTouchingType(namespace: string, type: string, limit: number): Promise<Edge[]>;
|
|
116
|
+
/**
|
|
117
|
+
* Distinct namespaces other than `namespace` at the far end of any edge
|
|
118
|
+
* (tombstoned or live) touching `namespace`, or `(namespace, type)` when
|
|
119
|
+
* `type` is given: the namespaces `dropEdgesByNamespace` / `dropEdgesByType`
|
|
120
|
+
* would delete edges from.
|
|
121
|
+
*/
|
|
122
|
+
namespacesLinkedTo(namespace: string, type?: string): Promise<string[]>;
|
|
123
|
+
/**
|
|
124
|
+
* Physically delete every edge (tombstoned or live) where `from_ns === namespace`
|
|
125
|
+
* OR `to_ns === namespace`. Used by drop-namespace when `cascade === 'delete'`.
|
|
126
|
+
* Returns the exact count physically removed.
|
|
127
|
+
*
|
|
128
|
+
* Same atomicity rules as `tombstone` — MUST run inside a caller-supplied
|
|
129
|
+
* `withTransaction` for multi-store atomicity.
|
|
130
|
+
*/
|
|
131
|
+
dropEdgesByNamespace(namespace: string, within?: readonly string[]): Promise<number>;
|
|
132
|
+
/**
|
|
133
|
+
* Physically delete every edge (tombstoned or live) where either endpoint
|
|
134
|
+
* matches `(namespace, type)`. Used by drop-type when `cascade === 'delete'`.
|
|
135
|
+
* `within` restricts both drops to edges whose far end is `namespace` or one
|
|
136
|
+
* of the listed namespaces.
|
|
137
|
+
*/
|
|
138
|
+
dropEdgesByType(namespace: string, type: string, within?: readonly string[]): Promise<number>;
|
|
139
|
+
/**
|
|
140
|
+
* Execute `fn` atomically. All ops performed on the `tx` argument run inside
|
|
141
|
+
* one substrate transaction. On throw, every mutation inside the callback
|
|
142
|
+
* rolls back; on resolve, the transaction commits and the value is returned.
|
|
143
|
+
*
|
|
144
|
+
* Nested calls flatten into the outer tx (savepoints out of scope).
|
|
145
|
+
* Cross-store atomicity with a sibling `Dataset.withTransaction` is the
|
|
146
|
+
* engine's concern; each store manages its own tx independently here.
|
|
147
|
+
* For enlisted cross-store atomicity, see `Dataset.withScopedTransaction`
|
|
148
|
+
* which yields a tx-bound `EdgesStore` alongside the tx-bound datasets.
|
|
149
|
+
*
|
|
150
|
+
* Mirrors `Dataset.withTransaction` (§4.5, G1 §5.3).
|
|
151
|
+
*/
|
|
152
|
+
withTransaction<T>(fn: (tx: EdgesStore) => Promise<T>): Promise<T>;
|
|
153
|
+
}
|
|
154
|
+
//#endregion
|
|
155
|
+
//#region ../../packages/substrate-types/src/schema.d.ts
|
|
156
|
+
interface FieldDefScalar {
|
|
157
|
+
kind: 'scalar';
|
|
158
|
+
/**
|
|
159
|
+
* `'json'` is an opaque body: msgpack-friendly nested object/array, value
|
|
160
|
+
* round-trips unchanged, but no per-leaf filtering or ordering. Use it for
|
|
161
|
+
* freeform payloads (audit details, debug bags). When you need filterable
|
|
162
|
+
* inner keys, use `field.struct` instead.
|
|
163
|
+
*/
|
|
164
|
+
type: 'string' | 'number' | 'boolean' | 'date' | 'json';
|
|
165
|
+
indexed?: boolean;
|
|
166
|
+
/** Metadata: when true, consumers SHOULD expect `null` as a legitimate value. */
|
|
167
|
+
nullable?: boolean;
|
|
168
|
+
/**
|
|
169
|
+
* Metadata: when true, this field is populated by the engine (not the caller)
|
|
170
|
+
* and write attempts that include it MUST be rejected. Used for the
|
|
171
|
+
* auto-injected `shortId` field. Consumers (autoCRUD create, schema
|
|
172
|
+
* publisher, client codegen) rely on this flag as a declarative contract —
|
|
173
|
+
* do not imperatively guard readonly fields without also flipping this.
|
|
174
|
+
*/
|
|
175
|
+
readonly?: boolean;
|
|
176
|
+
/**
|
|
177
|
+
* Server-managed date flag. Clients may not supply the field in the
|
|
178
|
+
* indicated phase(s) — autoCRUD rejects it with `client_supplied_server_field`:
|
|
179
|
+
* - 'create' — on create only
|
|
180
|
+
* - 'update' — on update only
|
|
181
|
+
* - 'both' — on create and update
|
|
182
|
+
* Nothing stamps it automatically: server-side code (a custom resolver or a
|
|
183
|
+
* system writer such as `applyUpdatePatch`) sets it. A non-nullable,
|
|
184
|
+
* non-defaulted field gated on create is refused by autoCRUD at install,
|
|
185
|
+
* since nothing could fill it. Only honoured on `type: 'date'`.
|
|
186
|
+
*/
|
|
187
|
+
serverSet?: 'create' | 'update' | 'both';
|
|
188
|
+
/**
|
|
189
|
+
* Controlled vocabulary. When present, the value MUST be one of these
|
|
190
|
+
* strings. Consumed by autoCRUD write-validation (covers memory + pg
|
|
191
|
+
* uniformly) and surfaced verbatim in the published schema. `type` stays
|
|
192
|
+
* 'string' — an enum is a constrained string, so pack / client decoder /
|
|
193
|
+
* where-validation treat it identically with no new branch.
|
|
194
|
+
*/
|
|
195
|
+
enum?: readonly string[];
|
|
196
|
+
/**
|
|
197
|
+
* Governed vocabulary: alias -> canonical value (each canonical value is in
|
|
198
|
+
* `enum`). autoCRUD stores the canonical value when an alias is written, and
|
|
199
|
+
* `where` filters on the field match it, so synonyms converge instead of
|
|
200
|
+
* sprawling. Matching is case-insensitive. Published in the schema so every
|
|
201
|
+
* client reads the same table.
|
|
202
|
+
*/
|
|
203
|
+
aliases?: Readonly<Record<string, string>>;
|
|
204
|
+
/**
|
|
205
|
+
* `false` admits values outside `enum` (aliases are still normalised): a
|
|
206
|
+
* transition mode for adopting a vocabulary over existing free-string data.
|
|
207
|
+
* Absent means strict.
|
|
208
|
+
*/
|
|
209
|
+
strict?: boolean;
|
|
210
|
+
/**
|
|
211
|
+
* Alias (or canonical value) -> sibling fields it implies, e.g.
|
|
212
|
+
* `done -> { resolution: 'completed' }`. On write the siblings are filled
|
|
213
|
+
* when the caller omits them and a contradicting value is refused; an
|
|
214
|
+
* `eq` filter on the alias also matches the implied siblings. Keys match
|
|
215
|
+
* case-insensitively.
|
|
216
|
+
*/
|
|
217
|
+
implies?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
|
|
218
|
+
/**
|
|
219
|
+
* Default value applied by autoCRUD `create` when the caller omits this
|
|
220
|
+
* field. Two effects: (1) the row is written with the default instead of
|
|
221
|
+
* being absent; (2) it satisfies the non-nullable presence check, so a
|
|
222
|
+
* non-nullable scalar WITHOUT a default that is omitted on create is
|
|
223
|
+
* rejected (`missing_required_field`) — that is how "required" is expressed.
|
|
224
|
+
* Only applied on create (update is a partial patch). The value should match
|
|
225
|
+
* `type` (booleans for boolean, ISO string for date, etc.).
|
|
226
|
+
*/
|
|
227
|
+
default?: string | number | boolean;
|
|
228
|
+
}
|
|
229
|
+
interface FieldDefCrossRef {
|
|
230
|
+
kind: 'crossRef';
|
|
231
|
+
ns: string;
|
|
232
|
+
type: string;
|
|
233
|
+
onDelete: OnDelete;
|
|
234
|
+
/**
|
|
235
|
+
* Write-time existence policy. 'reject' refuses a create/update
|
|
236
|
+
* whose crossRef value points at a non-existent or tombstoned target;
|
|
237
|
+
* 'allow' is the default when absent. Consulted only at write time, never
|
|
238
|
+
* stored on the edge. Enforced only for locally-resolvable
|
|
239
|
+
* target namespaces (compose rejects 'reject' on bridged/unknown targets).
|
|
240
|
+
*/
|
|
241
|
+
onMissing?: OnMissing;
|
|
242
|
+
/**
|
|
243
|
+
* Substrate-level indexing hint for the edge-source column, mirroring
|
|
244
|
+
* `FieldDefScalar.indexed`, so the dataset need not infer it from the
|
|
245
|
+
* presence of the crossRef itself.
|
|
246
|
+
*/
|
|
247
|
+
indexed?: boolean;
|
|
248
|
+
/** Metadata: when true, consumers SHOULD expect `null` as a legitimate value. */
|
|
249
|
+
nullable?: boolean;
|
|
250
|
+
/**
|
|
251
|
+
* Activation-spreading opt-in. When `spread: true`,
|
|
252
|
+
* recall hits on a row touching this crossRef propagate a damped salience
|
|
253
|
+
* boost to the linked row (forward direction, X → row X references) AND to
|
|
254
|
+
* rows whose same field points at the boosted row (backward direction,
|
|
255
|
+
* X ← rows that reference X). Default off — operators opt in per-edge to
|
|
256
|
+
* avoid polluting attention with low-signal edges (e.g. Decision.sessionId).
|
|
257
|
+
*
|
|
258
|
+
* Damping (typically 0.3) + depth bound (1) are configured on the recall
|
|
259
|
+
* substrate, not per-field.
|
|
260
|
+
*/
|
|
261
|
+
spread?: boolean;
|
|
262
|
+
/**
|
|
263
|
+
* Cross-TYPE opt-in for the recall expansion path.
|
|
264
|
+
* Only meaningful when `spread: true` (the SDK `field.crossRef` builder
|
|
265
|
+
* rejects `expandCrossType` without `spread` at registration). When both
|
|
266
|
+
* are set, BACKWARD walks via this edge are allowed to surface neighbours
|
|
267
|
+
* whose type differs from the request's `scope.type` (e.g. a Concept-typed
|
|
268
|
+
* query surfaces Decisions via inbound `Decision.establishesConcept`).
|
|
269
|
+
*
|
|
270
|
+
* Cross-NAMESPACE expansion is always rejected regardless of this flag.
|
|
271
|
+
* Forward walks always honour scope strictly: allowing them lets
|
|
272
|
+
* neighbour-type rows displace the rows that establish them in the ranking.
|
|
273
|
+
* Default false.
|
|
274
|
+
*/
|
|
275
|
+
expandCrossType?: boolean;
|
|
276
|
+
}
|
|
277
|
+
interface FieldDefStruct {
|
|
278
|
+
kind: 'struct';
|
|
279
|
+
fields: Record<string, FieldDef>;
|
|
280
|
+
/** Metadata: when true, consumers SHOULD expect `null` as a legitimate value. */
|
|
281
|
+
nullable?: boolean;
|
|
282
|
+
}
|
|
283
|
+
interface FieldDefList {
|
|
284
|
+
kind: 'list';
|
|
285
|
+
of: FieldDef;
|
|
286
|
+
/**
|
|
287
|
+
* When true, the field is server-side filterable via the `has` (element
|
|
288
|
+
* membership) operator without `_allowTableScan`, and is backed by a GIN
|
|
289
|
+
* index on `(body -> '<field>')`. List fields are stored as native JSONB
|
|
290
|
+
* arrays. Default false — an unindexed list field rejects `has` unless the
|
|
291
|
+
* caller opts into a table scan. The substrate binary derives the matching GIN
|
|
292
|
+
* as an idempotent migration at boot from this flag; no hand-authored
|
|
293
|
+
* migration is needed per field.
|
|
294
|
+
*/
|
|
295
|
+
indexed?: boolean;
|
|
296
|
+
/** Metadata: when true, consumers SHOULD expect `null` as a legitimate value. */
|
|
297
|
+
nullable?: boolean;
|
|
298
|
+
}
|
|
299
|
+
type FieldDef = FieldDefScalar | FieldDefCrossRef | FieldDefStruct | FieldDefList;
|
|
300
|
+
/**
|
|
301
|
+
* Per-type schema entry. Fields may be declared at registration time; MVP emits
|
|
302
|
+
* `fields: {}` for types registered without a field map (e.g. mutations whose
|
|
303
|
+
* shape is inferred from the resolver's return).
|
|
304
|
+
*/
|
|
305
|
+
interface TypeSchema {
|
|
306
|
+
fields: Record<string, FieldDef>;
|
|
307
|
+
}
|
|
308
|
+
/**
|
|
309
|
+
* Per-mutation schema entry. `params` describes the input shape a client
|
|
310
|
+
* sends; `returns` describes the shape a client decodes on success. Both are
|
|
311
|
+
* required — an empty param bag surfaces as `{}`, never as an absent key.
|
|
312
|
+
*
|
|
313
|
+
* `returns` is typically a `FieldDefStruct` describing the row shape the
|
|
314
|
+
* mutation produces (e.g. `create<T>` returns the inserted row; `delete<T>`
|
|
315
|
+
* returns `{ id, deleted }`). `get<T>` and `update<T>` mark the struct
|
|
316
|
+
* `nullable: true` because an id-miss legitimately produces `null`.
|
|
317
|
+
*
|
|
318
|
+
* Mutations registered without explicit `returns` metadata receive a sentinel
|
|
319
|
+
* fallback (`{ kind: 'scalar', type: 'string', nullable: true }`) so substrate-pack
|
|
320
|
+
* can still round-trip the response — clients treating it as "unknown shape"
|
|
321
|
+
* should fall back to JSON passthrough.
|
|
322
|
+
*/
|
|
323
|
+
interface MutationSchema {
|
|
324
|
+
params: Record<string, FieldDef>;
|
|
325
|
+
returns: FieldDef;
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* The published schema shape surfaced at `GET /substrate/v1/schema`. Spec: §4.2, §6.1,
|
|
329
|
+
* §7.1. `schemaVersion` is the 12-char SHA-256 prefix over the canonicalized
|
|
330
|
+
* schema JSON and travels on every response envelope (§7.0) so the client can
|
|
331
|
+
* detect drift.
|
|
332
|
+
*/
|
|
333
|
+
interface Schema {
|
|
334
|
+
schemaVersion: string;
|
|
335
|
+
types: Record<string, TypeSchema>;
|
|
336
|
+
mutations: Record<string, MutationSchema>;
|
|
337
|
+
/** Present (true) on substrate-contributed virtual namespaces: no autoCRUD, no storage, query/mutate one-shot only. */
|
|
338
|
+
virtual?: true;
|
|
339
|
+
/**
|
|
340
|
+
* The namespace's opaque per-consumer metadata (`defineNamespace` option).
|
|
341
|
+
* Not part of `schemaVersion`: an annotations-only change does not move it.
|
|
342
|
+
*/
|
|
343
|
+
annotations?: Readonly<Record<string, unknown>>;
|
|
344
|
+
}
|
|
345
|
+
/**
|
|
346
|
+
* Per-key shape. A single frame resolves to `'single' | 'list'`. A batched
|
|
347
|
+
* mutate op-key (array of frames) resolves to `Array<'single' | 'list'>` —
|
|
348
|
+
* one shape per frame, in frame-array order. The decoder keys off the
|
|
349
|
+
* discriminator: string → single frame; array → batched.
|
|
350
|
+
*/
|
|
351
|
+
type EnvelopeShape = 'single' | 'list' | Array<'single' | 'list'>;
|
|
352
|
+
/**
|
|
353
|
+
* The response envelope. Spec: §7.0.
|
|
354
|
+
*
|
|
355
|
+
* Query data values are positionally encoded using the client-sent `FieldInput`
|
|
356
|
+
* selection; mutation data values are positionally encoded using the declared
|
|
357
|
+
* `MutationSchema.returns` (§4.2) — mutations don't carry a FieldInput
|
|
358
|
+
* since there's no field selection on a return row.
|
|
359
|
+
*/
|
|
360
|
+
interface PackEnvelope {
|
|
361
|
+
schemaVersion: string;
|
|
362
|
+
data: Record<string, unknown>;
|
|
363
|
+
shapes: Record<string, EnvelopeShape>;
|
|
364
|
+
_meta?: Record<string, unknown>;
|
|
365
|
+
_pagination?: Record<string, {
|
|
366
|
+
nextCursor?: string;
|
|
367
|
+
hasMore: boolean;
|
|
368
|
+
}>;
|
|
369
|
+
/**
|
|
370
|
+
* Per-top-level-key completeness. ABSENT MEANS COMPLETE — callers that
|
|
371
|
+
* predate this field stay correct without change.
|
|
372
|
+
*
|
|
373
|
+
* Set when a bridged key could not be fully resolved (§6.5 "reads never
|
|
374
|
+
* fail" means such a read still returns 200 with orphan markers). The
|
|
375
|
+
* per-row `__orphan` marker says a row is missing; this says the RESULT SET
|
|
376
|
+
* is partial, which a consumer cannot otherwise distinguish from an
|
|
377
|
+
* genuinely empty result.
|
|
378
|
+
*/
|
|
379
|
+
_completeness?: Record<string, {
|
|
380
|
+
complete: boolean;
|
|
381
|
+
unreachable?: string[];
|
|
382
|
+
}>;
|
|
383
|
+
/**
|
|
384
|
+
* Non-fatal read diagnostics, keyed by top-level frame key. ABSENT MEANS
|
|
385
|
+
* NOTHING TO REPORT — callers that predate this field stay correct without
|
|
386
|
+
* change, same contract as `_completeness`.
|
|
387
|
+
*
|
|
388
|
+
* Deliberately NOT `errors`: a consumer doing `if (env.errors) throw` would
|
|
389
|
+
* start failing on reads that succeeded.
|
|
390
|
+
*
|
|
391
|
+
* A client that maps rows into declared interfaces MUST surface this (log,
|
|
392
|
+
* attach to the result, or throw in development): an unknown projection key
|
|
393
|
+
* arrives as `null`, satisfies the interface, and the read looks correct.
|
|
394
|
+
*/
|
|
395
|
+
_diagnostics?: Record<string, {
|
|
396
|
+
/**
|
|
397
|
+
* Projection keys the type does not declare. The read still returned
|
|
398
|
+
* every row; each unknown key materialises as `null` on all of them,
|
|
399
|
+
* indistinguishable from a declared field that is null everywhere.
|
|
400
|
+
*/
|
|
401
|
+
unknownProjectionFields?: string[];
|
|
402
|
+
/**
|
|
403
|
+
* The where-clause reached the substrate without being schema-validated,
|
|
404
|
+
* because the type is registered but absent from its namespace's
|
|
405
|
+
* published schema (e.g. runtime-created types). The result is still
|
|
406
|
+
* correct — substrates refuse a predicate they cannot honour — but an
|
|
407
|
+
* unindexed filter scans instead of rejecting.
|
|
408
|
+
*/
|
|
409
|
+
filterValidationSkipped?: string;
|
|
410
|
+
}>;
|
|
411
|
+
errors?: Array<{
|
|
412
|
+
message: string;
|
|
413
|
+
path?: string[];
|
|
414
|
+
code?: string;
|
|
415
|
+
/**
|
|
416
|
+
* Optional structured payload — populated when the underlying error class
|
|
417
|
+
* carries one (e.g. `ResolverFrameError({ field: '...' })`).
|
|
418
|
+
*/
|
|
419
|
+
details?: Record<string, unknown>;
|
|
420
|
+
}>;
|
|
421
|
+
}
|
|
422
|
+
/**
|
|
423
|
+
* Client-sent field selection tree. Defined here rather than in
|
|
424
|
+
* `@mnmal-ai/substrate-pack` so subscription and streaming machinery (§5.4, §5.5)
|
|
425
|
+
* can reference the same shape without adding substrate-pack to their dependency
|
|
426
|
+
* set — substrate-pack already imports from types, so moving the type upward
|
|
427
|
+
* avoids the would-be cycle.
|
|
428
|
+
*/
|
|
429
|
+
type FieldInput = {
|
|
430
|
+
[field: string]: true | FieldInput;
|
|
431
|
+
};
|
|
432
|
+
//#endregion
|
|
433
|
+
export { Id as C, RowMetadata as D, Row as E, RowMetadataField as O, ClientSuppliedServerFieldError as S, ROW_METADATA_FIELDS as T, EdgesStore as _, FieldDefScalar as a, ActorIdentity as b, MutationSchema as c, TypeSchema as d, CanDeleteResult as f, EdgeWriteInput as g, EdgeRef as h, FieldDefList as i, PackEnvelope as l, EdgePatch as m, FieldDef as n, FieldDefStruct as o, Edge as p, FieldDefCrossRef as r, FieldInput as s, EnvelopeShape as t, Schema as u, OnDelete as v, IdentityKind as w, CLIENT_SUPPLIED_SERVER_FIELD as x, OnMissing as y };
|