@mnmal-ai/substrate 0.0.0-stage → 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 +119 -2
- 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 -3
|
@@ -0,0 +1,1797 @@
|
|
|
1
|
+
import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
|
|
2
|
+
import { A as resolveIdentity, F as publishSchema, Z as JSON_HEADERS, _ as field, b as installAutoCrud, h as RESERVED_AUTOCRUD_FIELDS, l as migrateFieldValues, m as defineNamespace, v as autoCrudOptionsOf, wt as ResolverFrameError } from "./src-D91yij6C.js";
|
|
3
|
+
import { s as requireCapability } from "./row-DK7lPZVe.js";
|
|
4
|
+
import { randomUUID } from "node:crypto";
|
|
5
|
+
|
|
6
|
+
//#region ../../plugins/substrate-proposals/src/capability.ts
|
|
7
|
+
/**
|
|
8
|
+
* Substrate.propose capability policy helper.
|
|
9
|
+
*/
|
|
10
|
+
const DEFAULT_PROPOSE_CAPABILITY = "substrate.propose";
|
|
11
|
+
/**
|
|
12
|
+
* Create a policy that requires the given capability to be present in the
|
|
13
|
+
* request identity. Passing an empty string disables the gate entirely
|
|
14
|
+
* (allow-all) — intended for dev / smoke-test deployments where JWT auth
|
|
15
|
+
* isn't configured and every request would otherwise have no identity.
|
|
16
|
+
* Production deployments should always supply a real capability name.
|
|
17
|
+
*/
|
|
18
|
+
function makeProposePolicy(capability = DEFAULT_PROPOSE_CAPABILITY) {
|
|
19
|
+
if (capability === "") return () => ({ allow: true });
|
|
20
|
+
return requireCapability(capability);
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Writes to the proposal record types need the propose capability: boot
|
|
24
|
+
* replays every row marked applied, so a row written directly would become
|
|
25
|
+
* live schema. Reads stay open to anyone the namespace grant admits.
|
|
26
|
+
*/
|
|
27
|
+
function proposeToWrite(capability = DEFAULT_PROPOSE_CAPABILITY) {
|
|
28
|
+
const gate = makeProposePolicy(capability);
|
|
29
|
+
return (ctx, args) => ctx.operation === "mutate" ? gate(ctx, args) : { allow: true };
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
//#endregion
|
|
33
|
+
//#region ../../plugins/substrate-proposals/src/control-plane.ts
|
|
34
|
+
/**
|
|
35
|
+
* Control-plane namespace for substrate-proposals.
|
|
36
|
+
*
|
|
37
|
+
* `_system_proposals` is reserved by the plugin and houses the NamespaceProposal
|
|
38
|
+
* autoCRUD type. It's installed alongside any user-facing ownedNamespaces and
|
|
39
|
+
* cannot be passed in `ownedNamespaces` (the plugin throws on collision at
|
|
40
|
+
* construction). The leading underscore follows the `_system*` system-reserved
|
|
41
|
+
* namespace convention (mirrors `_system` admin namespace).
|
|
42
|
+
*
|
|
43
|
+
* The NamespaceProposal type tracks runtime namespace additions for restart
|
|
44
|
+
* recovery: applied=true rows are replayed by reconcileClusterNamespaces on
|
|
45
|
+
* cold boot, before the per-namespace TypeProposal/FieldProposal reconcile.
|
|
46
|
+
*
|
|
47
|
+
* `supersededByCode` mirrors TypeProposal/FieldProposal — set when a namespace
|
|
48
|
+
* proposed at runtime is later added to static plugin config (`ownedNamespaces`). The proposal row stays for
|
|
49
|
+
* audit/queryability; the static-config path becomes the source of truth.
|
|
50
|
+
*/
|
|
51
|
+
const CONTROL_NAMESPACE = "_system_proposals";
|
|
52
|
+
/** The pattern `defineNamespace` enforces: no '/' (frame keys) and no ':' (grant syntax). */
|
|
53
|
+
const NAMESPACE_NAME = /^[A-Za-z0-9_-]+$/;
|
|
54
|
+
/** A name `propose_namespace` may create, and so the only kind replay may install. */
|
|
55
|
+
function isProposableNamespace(ns) {
|
|
56
|
+
return typeof ns === "string" && NAMESPACE_NAME.test(ns) && ns !== "_system_proposals";
|
|
57
|
+
}
|
|
58
|
+
function defineControlPlaneTypes(capability = DEFAULT_PROPOSE_CAPABILITY) {
|
|
59
|
+
return defineNamespace(CONTROL_NAMESPACE, { NamespaceProposal: {
|
|
60
|
+
policy: proposeToWrite(capability),
|
|
61
|
+
fields: {
|
|
62
|
+
ns: field.string(),
|
|
63
|
+
proposedBy: field.string(),
|
|
64
|
+
proposedAt: field.date(),
|
|
65
|
+
proposedReason: field.string({ indexed: false }),
|
|
66
|
+
applied: field.boolean(),
|
|
67
|
+
appliedAt: field.date({ nullable: true }),
|
|
68
|
+
supersededByCode: field.boolean(),
|
|
69
|
+
archived: field.boolean()
|
|
70
|
+
}
|
|
71
|
+
} });
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
//#endregion
|
|
75
|
+
//#region ../../plugins/substrate-proposals/src/errors.ts
|
|
76
|
+
/**
|
|
77
|
+
* Structured error types for schema proposals.
|
|
78
|
+
*
|
|
79
|
+
* ProposalError carries a stable code string so NL agents and SDK clients can dispatch
|
|
80
|
+
* on error.code without parsing human-readable messages. Details hold context-specific
|
|
81
|
+
* metadata for recovery or logging.
|
|
82
|
+
*/
|
|
83
|
+
/**
|
|
84
|
+
* Structured error for proposal operations with stable error codes.
|
|
85
|
+
*
|
|
86
|
+
* Supports wire serialization via toJSON() for consistent error handling
|
|
87
|
+
* across HTTP boundaries.
|
|
88
|
+
*/
|
|
89
|
+
var ProposalError = class ProposalError extends ResolverFrameError {
|
|
90
|
+
name = "ProposalError";
|
|
91
|
+
code;
|
|
92
|
+
details;
|
|
93
|
+
constructor(code, message, details = {}, options = {}) {
|
|
94
|
+
super(code, message, details);
|
|
95
|
+
this.code = code;
|
|
96
|
+
this.details = details;
|
|
97
|
+
if (options.cause !== void 0) Object.defineProperty(this, "cause", {
|
|
98
|
+
value: options.cause,
|
|
99
|
+
enumerable: false
|
|
100
|
+
});
|
|
101
|
+
Object.setPrototypeOf(this, ProposalError.prototype);
|
|
102
|
+
}
|
|
103
|
+
toJSON() {
|
|
104
|
+
return {
|
|
105
|
+
error: this.code,
|
|
106
|
+
message: this.message,
|
|
107
|
+
details: this.details
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
};
|
|
111
|
+
|
|
112
|
+
//#endregion
|
|
113
|
+
//#region ../../plugins/substrate-proposals/src/field-spec-json.ts
|
|
114
|
+
/**
|
|
115
|
+
* Wire format for proposable field definitions. Mirrors `FieldDef` from
|
|
116
|
+
* `@mnmal-ai/substrate-types` one-for-one, but only covers the subset that
|
|
117
|
+
* autoCRUD can serve. Anything outside this surface cannot be proposed
|
|
118
|
+
* and must land through code.
|
|
119
|
+
*/
|
|
120
|
+
/**
|
|
121
|
+
* Type and field names a proposal may introduce. They become segments of
|
|
122
|
+
* `<ns>/<Type>` frame keys and autoCRUD operation names, so a '/' or an
|
|
123
|
+
* empty name would register something no caller can address.
|
|
124
|
+
*/
|
|
125
|
+
const PROPOSABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
126
|
+
/** @throws ProposalError `invalid_params` when `value` is not a proposable name */
|
|
127
|
+
function assertProposableName(param, value) {
|
|
128
|
+
if (typeof value !== "string" || !PROPOSABLE_NAME.test(value)) throw new ProposalError("invalid_params", `'${param}' must match ${PROPOSABLE_NAME.source}, got ${JSON.stringify(value)}`, { param });
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* Refuse a crossRef, at any depth in `spec`, whose target `ownsType` rejects.
|
|
132
|
+
*
|
|
133
|
+
* @throws ProposalError `invalid_field_spec` naming the field and the target
|
|
134
|
+
*/
|
|
135
|
+
function assertCrossRefsOwned(fieldName, spec, ownsType) {
|
|
136
|
+
for (const ref of crossRefsIn(spec)) if (!ownsType(ref.ns, ref.type)) throw new ProposalError("invalid_field_spec", `Field '${fieldName}' references '${ref.ns}/${ref.type}', which is not a type in a namespace this plugin owns`, { fieldName });
|
|
137
|
+
}
|
|
138
|
+
function crossRefsIn(spec) {
|
|
139
|
+
switch (spec.kind) {
|
|
140
|
+
case "crossRef": return [spec];
|
|
141
|
+
case "list": return crossRefsIn(spec.of);
|
|
142
|
+
case "struct": return Object.values(spec.fields).flatMap(crossRefsIn);
|
|
143
|
+
default: return [];
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
const SCALAR_TYPES = /* @__PURE__ */ new Set([
|
|
147
|
+
"string",
|
|
148
|
+
"number",
|
|
149
|
+
"boolean",
|
|
150
|
+
"date",
|
|
151
|
+
"json"
|
|
152
|
+
]);
|
|
153
|
+
function parseFieldSpec(json) {
|
|
154
|
+
switch (json.kind) {
|
|
155
|
+
case "scalar": {
|
|
156
|
+
if (!SCALAR_TYPES.has(json.type)) throw new Error(`unsupported scalar type: ${String(json.type)}`);
|
|
157
|
+
const def = {
|
|
158
|
+
kind: "scalar",
|
|
159
|
+
type: json.type,
|
|
160
|
+
indexed: json.indexed ?? true
|
|
161
|
+
};
|
|
162
|
+
if (json.nullable !== void 0) def.nullable = json.nullable;
|
|
163
|
+
if (json.readonly !== void 0) def.readonly = json.readonly;
|
|
164
|
+
if (json.enum !== void 0) def.enum = json.enum;
|
|
165
|
+
if (json.aliases !== void 0 || json.strict !== void 0 || json.implies !== void 0) {
|
|
166
|
+
if (json.enum === void 0) throw new Error("aliases, strict and implies need an enum to govern");
|
|
167
|
+
const vocab = field.vocab(json.enum, {
|
|
168
|
+
...json.aliases !== void 0 ? { aliases: json.aliases } : {},
|
|
169
|
+
...json.strict !== void 0 ? { strict: json.strict } : {},
|
|
170
|
+
...json.implies !== void 0 ? { implies: json.implies } : {}
|
|
171
|
+
});
|
|
172
|
+
if (vocab.aliases !== void 0) def.aliases = vocab.aliases;
|
|
173
|
+
if (vocab.strict !== void 0) def.strict = vocab.strict;
|
|
174
|
+
if (vocab.implies !== void 0) def.implies = vocab.implies;
|
|
175
|
+
}
|
|
176
|
+
return def;
|
|
177
|
+
}
|
|
178
|
+
case "crossRef": {
|
|
179
|
+
if ("onMissing" in json && json.onMissing !== void 0) throw new Error("onMissing is not supported via propose_field; declare it in a hand-authored namespace instead");
|
|
180
|
+
const def = {
|
|
181
|
+
kind: "crossRef",
|
|
182
|
+
ns: json.ns,
|
|
183
|
+
type: json.type,
|
|
184
|
+
onDelete: json.onDelete ?? "set_null",
|
|
185
|
+
indexed: json.indexed ?? true
|
|
186
|
+
};
|
|
187
|
+
if (json.nullable !== void 0) def.nullable = json.nullable;
|
|
188
|
+
return def;
|
|
189
|
+
}
|
|
190
|
+
case "struct": {
|
|
191
|
+
const fields = {};
|
|
192
|
+
for (const [name, spec] of Object.entries(json.fields)) {
|
|
193
|
+
if (!PROPOSABLE_NAME.test(name)) throw new Error(`invalid struct field name '${name}'`);
|
|
194
|
+
fields[name] = parseFieldSpec(spec);
|
|
195
|
+
}
|
|
196
|
+
const def = {
|
|
197
|
+
kind: "struct",
|
|
198
|
+
fields
|
|
199
|
+
};
|
|
200
|
+
if (json.nullable !== void 0) def.nullable = json.nullable;
|
|
201
|
+
return def;
|
|
202
|
+
}
|
|
203
|
+
case "list": {
|
|
204
|
+
const def = {
|
|
205
|
+
kind: "list",
|
|
206
|
+
of: parseFieldSpec(json.of)
|
|
207
|
+
};
|
|
208
|
+
if (json.nullable !== void 0) def.nullable = json.nullable;
|
|
209
|
+
return def;
|
|
210
|
+
}
|
|
211
|
+
default: throw new Error(`unknown field spec kind: ${JSON.stringify(json)}`);
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
function stringifyFieldDef(def) {
|
|
215
|
+
switch (def.kind) {
|
|
216
|
+
case "scalar": {
|
|
217
|
+
const out = {
|
|
218
|
+
kind: "scalar",
|
|
219
|
+
type: def.type
|
|
220
|
+
};
|
|
221
|
+
if (def.indexed !== void 0) out.indexed = def.indexed;
|
|
222
|
+
if (def.nullable !== void 0) out.nullable = def.nullable;
|
|
223
|
+
if (def.readonly !== void 0) out.readonly = def.readonly;
|
|
224
|
+
if (def.enum !== void 0) out.enum = def.enum;
|
|
225
|
+
if (def.aliases !== void 0) out.aliases = { ...def.aliases };
|
|
226
|
+
if (def.strict !== void 0) out.strict = def.strict;
|
|
227
|
+
if (def.implies !== void 0) out.implies = { ...def.implies };
|
|
228
|
+
return out;
|
|
229
|
+
}
|
|
230
|
+
case "crossRef": {
|
|
231
|
+
const out = {
|
|
232
|
+
kind: "crossRef",
|
|
233
|
+
ns: def.ns,
|
|
234
|
+
type: def.type
|
|
235
|
+
};
|
|
236
|
+
if (def.onDelete !== void 0) out.onDelete = def.onDelete;
|
|
237
|
+
if (def.indexed === false) out.indexed = false;
|
|
238
|
+
if (def.nullable !== void 0) out.nullable = def.nullable;
|
|
239
|
+
return out;
|
|
240
|
+
}
|
|
241
|
+
case "struct": {
|
|
242
|
+
const fields = {};
|
|
243
|
+
for (const [name, inner] of Object.entries(def.fields)) fields[name] = stringifyFieldDef(inner);
|
|
244
|
+
const out = {
|
|
245
|
+
kind: "struct",
|
|
246
|
+
fields
|
|
247
|
+
};
|
|
248
|
+
if (def.nullable !== void 0) out.nullable = def.nullable;
|
|
249
|
+
return out;
|
|
250
|
+
}
|
|
251
|
+
case "list": {
|
|
252
|
+
const out = {
|
|
253
|
+
kind: "list",
|
|
254
|
+
of: stringifyFieldDef(def.of)
|
|
255
|
+
};
|
|
256
|
+
if (def.nullable !== void 0) out.nullable = def.nullable;
|
|
257
|
+
return out;
|
|
258
|
+
}
|
|
259
|
+
default: throw new Error(`unknown FieldDef kind: ${JSON.stringify(def)}`);
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
/**
|
|
263
|
+
* Check that `spec` parses, so a proposal can be refused before any row is
|
|
264
|
+
* written for it.
|
|
265
|
+
*
|
|
266
|
+
* @throws ProposalError `invalid_field_spec` naming `fieldName` and the parse failure
|
|
267
|
+
*/
|
|
268
|
+
function assertValidFieldSpec(fieldName, spec) {
|
|
269
|
+
assertProposableName("fieldName", fieldName);
|
|
270
|
+
if (typeof spec !== "object" || spec === null) throw new ProposalError("invalid_field_spec", `Spec for field '${fieldName}' must be an object`, { fieldName });
|
|
271
|
+
try {
|
|
272
|
+
parseFieldSpec(spec);
|
|
273
|
+
} catch (cause) {
|
|
274
|
+
throw new ProposalError("invalid_field_spec", `Invalid spec for field '${fieldName}': ${cause instanceof Error ? cause.message : String(cause)}`, { fieldName });
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
//#endregion
|
|
279
|
+
//#region ../../plugins/substrate-proposals/src/namespace.ts
|
|
280
|
+
/**
|
|
281
|
+
* substrate-proposals namespace definition.
|
|
282
|
+
*
|
|
283
|
+
* Defines two types for schema evolution proposals:
|
|
284
|
+
* - TypeProposal: proposes a new type (multiple fields at once)
|
|
285
|
+
* - FieldProposal: proposes a single field on an existing type
|
|
286
|
+
*
|
|
287
|
+
* Both track proposal metadata (proposedBy, proposedAt, reason) and application
|
|
288
|
+
* state (applied, appliedAt). The `supersededByCode` flag indicates that a
|
|
289
|
+
* proposal was made obsolete by unrelated code changes — distinct from an
|
|
290
|
+
* explicit `superseded` status in decision-tracking.
|
|
291
|
+
*
|
|
292
|
+
* First-past-the-post uniqueness is enforced by a read-before-write check in
|
|
293
|
+
* the propose resolvers, held under a per-name lock (`proposal-lock.ts`), not
|
|
294
|
+
* by a schema or database constraint.
|
|
295
|
+
*/
|
|
296
|
+
function defineProposalTypes(namespace, capability = DEFAULT_PROPOSE_CAPABILITY) {
|
|
297
|
+
const policy = proposeToWrite(capability);
|
|
298
|
+
return defineNamespace(namespace, {
|
|
299
|
+
TypeProposal: {
|
|
300
|
+
policy,
|
|
301
|
+
fields: {
|
|
302
|
+
typeName: field.string(),
|
|
303
|
+
fieldsJson: field.string({ indexed: false }),
|
|
304
|
+
proposedBy: field.string(),
|
|
305
|
+
proposedAt: field.date(),
|
|
306
|
+
proposedReason: field.string({ indexed: false }),
|
|
307
|
+
applied: field.boolean(),
|
|
308
|
+
appliedAt: field.date({ nullable: true }),
|
|
309
|
+
resultingSchemaVersion: field.string({ nullable: true }),
|
|
310
|
+
supersededByCode: field.boolean(),
|
|
311
|
+
archived: field.boolean()
|
|
312
|
+
}
|
|
313
|
+
},
|
|
314
|
+
FieldProposal: {
|
|
315
|
+
policy,
|
|
316
|
+
fields: {
|
|
317
|
+
targetType: field.string(),
|
|
318
|
+
fieldName: field.string(),
|
|
319
|
+
fieldSpecJson: field.string({ indexed: false }),
|
|
320
|
+
proposedBy: field.string(),
|
|
321
|
+
proposedAt: field.date(),
|
|
322
|
+
proposedReason: field.string({ indexed: false }),
|
|
323
|
+
valueMapJson: field.string({
|
|
324
|
+
indexed: false,
|
|
325
|
+
nullable: true
|
|
326
|
+
}),
|
|
327
|
+
applied: field.boolean(),
|
|
328
|
+
appliedAt: field.date({ nullable: true }),
|
|
329
|
+
resultingSchemaVersion: field.string({ nullable: true }),
|
|
330
|
+
supersededByCode: field.boolean(),
|
|
331
|
+
archived: field.boolean()
|
|
332
|
+
}
|
|
333
|
+
}
|
|
334
|
+
});
|
|
335
|
+
}
|
|
336
|
+
/** The canonical ordered list of type names registered by this namespace. */
|
|
337
|
+
const PROPOSAL_TYPE_NAMES = ["TypeProposal", "FieldProposal"];
|
|
338
|
+
|
|
339
|
+
//#endregion
|
|
340
|
+
//#region ../../plugins/substrate-proposals/src/apply.ts
|
|
341
|
+
/**
|
|
342
|
+
* Apply proposal helpers — runtime type + field registration.
|
|
343
|
+
*
|
|
344
|
+
* `applyTypeProposal` is the bridge between a stored TypeProposal (field specs
|
|
345
|
+
* on the wire) and the live Registry: it parses each FieldSpecJson → FieldDef,
|
|
346
|
+
* injects the engine-reserved shortId field (mirroring defineNamespace), and
|
|
347
|
+
* delegates to `installAutoCrud` to register the full CRUD surface.
|
|
348
|
+
*
|
|
349
|
+
* `applyFieldProposal` extends an already-registered type with a new field by
|
|
350
|
+
* replacing the type entry + all autoCRUD mutations with versions that include
|
|
351
|
+
* the new field definition. The existing shortId field is preserved via spread.
|
|
352
|
+
*/
|
|
353
|
+
/**
|
|
354
|
+
* Refuse a type proposal no caller could address, or whose crossRefs leave
|
|
355
|
+
* the plugin's namespaces. The resolver passes a check that also requires the
|
|
356
|
+
* target type to exist; replay cannot, as a target in another namespace may
|
|
357
|
+
* not have been replayed yet.
|
|
358
|
+
*
|
|
359
|
+
* @throws ProposalError `invalid_params` / `invalid_field_spec`
|
|
360
|
+
*/
|
|
361
|
+
function assertValidTypeProposal(typeName, fields, ownsTarget) {
|
|
362
|
+
assertProposableName("typeName", typeName);
|
|
363
|
+
if (typeof fields !== "object" || fields === null || Array.isArray(fields) || Object.keys(fields).length === 0) throw new ProposalError("invalid_params", "'fields' must be a non-empty object", { param: "fields" });
|
|
364
|
+
for (const [fieldName, spec] of Object.entries(fields)) {
|
|
365
|
+
assertValidFieldSpec(fieldName, spec);
|
|
366
|
+
assertCrossRefsOwned(fieldName, spec, ownsTarget);
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
/** As `assertValidTypeProposal`, for one field on `targetType`. */
|
|
370
|
+
function assertValidFieldProposal(targetType, fieldName, fieldSpec, ownsTarget) {
|
|
371
|
+
assertProposableName("targetType", targetType);
|
|
372
|
+
if (PROPOSAL_TYPE_NAMES.includes(targetType)) throw new ProposalError("invalid_params", `'${targetType}' is a proposal type and cannot take proposed fields`, { param: "targetType" });
|
|
373
|
+
assertValidFieldSpec(fieldName, fieldSpec);
|
|
374
|
+
assertCrossRefsOwned(fieldName, fieldSpec, ownsTarget);
|
|
375
|
+
}
|
|
376
|
+
/** Installs the proposed type's autoCRUD surface into `registry`. */
|
|
377
|
+
function installProposedType(registry, args) {
|
|
378
|
+
const fieldDefs = {};
|
|
379
|
+
for (const [name, spec] of Object.entries(args.fields)) fieldDefs[name] = parseFieldSpec(spec);
|
|
380
|
+
Object.assign(fieldDefs, RESERVED_AUTOCRUD_FIELDS);
|
|
381
|
+
installAutoCrud(registry, args.typeName, args.dataset, args.edges, { fields: fieldDefs });
|
|
382
|
+
}
|
|
383
|
+
/**
|
|
384
|
+
* Every registry key `applyTypeProposal` would register for this proposal —
|
|
385
|
+
* the type name plus each autoCRUD operation name — without registering any.
|
|
386
|
+
*
|
|
387
|
+
* @returns the keys in registration order
|
|
388
|
+
* @throws whatever `applyTypeProposal` would throw for an invalid field spec
|
|
389
|
+
*/
|
|
390
|
+
function typeProposalRegistryKeys(args) {
|
|
391
|
+
const keys = [];
|
|
392
|
+
installProposedType({ register: (key) => keys.push(key) }, args);
|
|
393
|
+
return keys;
|
|
394
|
+
}
|
|
395
|
+
/**
|
|
396
|
+
* Validates, then installs. Every path that turns a row into schema (the
|
|
397
|
+
* resolver, boot replay, a peer's NOTIFY) passes through here, and a row can
|
|
398
|
+
* be written directly by any holder of the propose capability.
|
|
399
|
+
*/
|
|
400
|
+
function applyTypeProposal(args) {
|
|
401
|
+
const store = args.registryStore;
|
|
402
|
+
assertValidTypeProposal(args.typeName, args.fields, (ns, type) => ns === args.namespace && type === args.typeName || store.ownsNamespace(ns));
|
|
403
|
+
const binding = store.getBinding(args.namespace);
|
|
404
|
+
installProposedType(binding.registry, args);
|
|
405
|
+
binding.invalidateSchemaCaches?.();
|
|
406
|
+
}
|
|
407
|
+
/**
|
|
408
|
+
* Extend an already-registered type with a new field.
|
|
409
|
+
*
|
|
410
|
+
* Replaces the type entry + all autoCRUD mutations atomically with versions
|
|
411
|
+
* that include the new field. Uses a `replaceWriter` that funnels every
|
|
412
|
+
* `register` call from installAutoCrud through `registry.replace()` so
|
|
413
|
+
* DuplicateRegistration is never thrown.
|
|
414
|
+
*
|
|
415
|
+
* The replacement is strictly additive — existing rows without the new field
|
|
416
|
+
* continue to read as field-absent.
|
|
417
|
+
*/
|
|
418
|
+
function applyFieldProposal(args) {
|
|
419
|
+
const store = args.registryStore;
|
|
420
|
+
assertValidFieldProposal(args.targetType, args.fieldName, args.fieldSpec, (ns) => store.ownsNamespace(ns));
|
|
421
|
+
const binding = store.getBinding(args.namespace);
|
|
422
|
+
const registry = binding.registry;
|
|
423
|
+
const existing = registry.get(args.targetType);
|
|
424
|
+
if (!existing) throw new Error(`applyFieldProposal: target type '${args.targetType}' not registered`);
|
|
425
|
+
const nextFields = {
|
|
426
|
+
...existing.fields,
|
|
427
|
+
[args.fieldName]: parseFieldSpec(args.fieldSpec)
|
|
428
|
+
};
|
|
429
|
+
const replaceWriter = {
|
|
430
|
+
register: (key, input) => registry.replace(key, input),
|
|
431
|
+
replace: registry.replace.bind(registry)
|
|
432
|
+
};
|
|
433
|
+
const prior = autoCrudOptionsOf(existing.resolver) ?? { policy: existing.policy };
|
|
434
|
+
installAutoCrud(replaceWriter, args.targetType, args.dataset, args.edges, {
|
|
435
|
+
...prior,
|
|
436
|
+
fields: nextFields
|
|
437
|
+
});
|
|
438
|
+
binding.invalidateSchemaCaches?.();
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
//#endregion
|
|
442
|
+
//#region ../../plugins/substrate-proposals/src/engine-write.ts
|
|
443
|
+
/**
|
|
444
|
+
* Run the autoCRUD create-or-update `op` registered on `registry` inside the
|
|
445
|
+
* caller's own transaction (`args.dataset`), and return the resulting row.
|
|
446
|
+
* A nested `engine.mutate` would open a second transaction, and so take a
|
|
447
|
+
* second pooled connection, beside the one the proposal already holds.
|
|
448
|
+
*
|
|
449
|
+
* @throws Error when `op` is not registered, its policy denies, or it returns no row
|
|
450
|
+
*/
|
|
451
|
+
async function writeInTx(registry, ctx, args, op, params) {
|
|
452
|
+
const entry = registry.get(op);
|
|
453
|
+
if (entry === void 0) throw new Error(`'${op}' is not registered`);
|
|
454
|
+
const opCtx = {
|
|
455
|
+
...ctx,
|
|
456
|
+
entry: op,
|
|
457
|
+
...entry.verb !== void 0 ? { verb: entry.verb } : {}
|
|
458
|
+
};
|
|
459
|
+
const opArgs = {
|
|
460
|
+
...args,
|
|
461
|
+
params,
|
|
462
|
+
fields: { id: true }
|
|
463
|
+
};
|
|
464
|
+
const decision = entry.policy?.(opCtx, opArgs);
|
|
465
|
+
if (decision !== void 0 && !decision.allow) throw new Error(`'${op}' denied: ${decision.reason ?? "policy denied"}`);
|
|
466
|
+
const row = await entry.resolver(opCtx, opArgs);
|
|
467
|
+
if (row === null || typeof row !== "object" || Array.isArray(row)) throw new Error(`'${op}' returned no row`);
|
|
468
|
+
return row;
|
|
469
|
+
}
|
|
470
|
+
/**
|
|
471
|
+
* Run `install` against the live `registry`, and take back every entry it
|
|
472
|
+
* added or replaced if it throws or the caller's transaction rolls back, so
|
|
473
|
+
* the schema never outlives the proposal row that justifies it. An entry
|
|
474
|
+
* something else has replaced since is left alone.
|
|
475
|
+
*/
|
|
476
|
+
function applyUntilRollback(args, registry, install, afterUndo) {
|
|
477
|
+
const before = new Map(registry.all());
|
|
478
|
+
const changedSince = () => [...registry.all()].filter(([key, entry]) => before.get(key) !== entry);
|
|
479
|
+
const undo = (installed) => {
|
|
480
|
+
for (const [key, entry] of installed) {
|
|
481
|
+
if (registry.get(key) !== entry) continue;
|
|
482
|
+
const prior = before.get(key);
|
|
483
|
+
if (prior !== void 0) registry.replace(key, prior);
|
|
484
|
+
else registry.unregister?.(key);
|
|
485
|
+
}
|
|
486
|
+
afterUndo();
|
|
487
|
+
};
|
|
488
|
+
try {
|
|
489
|
+
install();
|
|
490
|
+
} catch (err) {
|
|
491
|
+
undo(changedSince());
|
|
492
|
+
throw err;
|
|
493
|
+
}
|
|
494
|
+
if (args.afterTx === void 0) return;
|
|
495
|
+
const installed = changedSince();
|
|
496
|
+
args.afterTx(async ({ committed }) => {
|
|
497
|
+
if (!committed) undo(installed);
|
|
498
|
+
});
|
|
499
|
+
}
|
|
500
|
+
/**
|
|
501
|
+
* Run `notify` once the caller's transaction commits, so a peer reacting to it
|
|
502
|
+
* reads the committed row, and skip it on a rollback. Outside a transaction
|
|
503
|
+
* (no `afterTx`) it runs at once.
|
|
504
|
+
*/
|
|
505
|
+
async function notifyAfterCommit(args, notify) {
|
|
506
|
+
if (args.afterTx === void 0) {
|
|
507
|
+
await notify();
|
|
508
|
+
return;
|
|
509
|
+
}
|
|
510
|
+
args.afterTx(async ({ committed }) => {
|
|
511
|
+
if (committed) await notify();
|
|
512
|
+
});
|
|
513
|
+
}
|
|
514
|
+
|
|
515
|
+
//#endregion
|
|
516
|
+
//#region ../../plugins/substrate-proposals/src/proposal-lock.ts
|
|
517
|
+
const localTails = /* @__PURE__ */ new Map();
|
|
518
|
+
/** The lock key for one proposal identity: `substrate-proposals:<kind>:<ns>/<name>`. */
|
|
519
|
+
function proposalLockKey(kind, ns, name) {
|
|
520
|
+
return `substrate-proposals:${kind}:${ns}/${name}`;
|
|
521
|
+
}
|
|
522
|
+
/**
|
|
523
|
+
* Run `fn` while holding the lock for `key`. Uses the dataset's
|
|
524
|
+
* `withAdvisoryLock` when it has one (pg: excludes every process on the
|
|
525
|
+
* database); otherwise a process-local mutex, which leaves instances in other
|
|
526
|
+
* processes unserialised.
|
|
527
|
+
*
|
|
528
|
+
* @returns whatever `fn` resolves to
|
|
529
|
+
* @throws whatever `fn` throws, after the lock is released
|
|
530
|
+
*/
|
|
531
|
+
function withProposalLock(dataset, key, fn) {
|
|
532
|
+
if (typeof dataset.withAdvisoryLock === "function") return dataset.withAdvisoryLock(key, fn);
|
|
533
|
+
return withLocalLock(key, fn);
|
|
534
|
+
}
|
|
535
|
+
async function withLocalLock(key, fn) {
|
|
536
|
+
const prior = localTails.get(key) ?? Promise.resolve();
|
|
537
|
+
let release;
|
|
538
|
+
const held = new Promise((resolve) => {
|
|
539
|
+
release = resolve;
|
|
540
|
+
});
|
|
541
|
+
const tail = prior.then(() => held);
|
|
542
|
+
localTails.set(key, tail);
|
|
543
|
+
await prior;
|
|
544
|
+
try {
|
|
545
|
+
return await fn();
|
|
546
|
+
} finally {
|
|
547
|
+
release();
|
|
548
|
+
if (localTails.get(key) === tail) localTails.delete(key);
|
|
549
|
+
}
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
//#endregion
|
|
553
|
+
//#region ../../plugins/substrate-proposals/src/propose-namespace-resolver.ts
|
|
554
|
+
/**
|
|
555
|
+
* propose_namespace — runtime namespace creation.
|
|
556
|
+
*
|
|
557
|
+
* Hot-adds a new namespace to the live engine without a binary restart, e.g.
|
|
558
|
+
* to provision per-user / per-tenant namespaces on demand. Mirrors
|
|
559
|
+
* `propose_type` in shape and first-past-the-post (FPP) collision semantics.
|
|
560
|
+
* Steps 2-9 run under the proposal lock for the ns, so of two racing callers
|
|
561
|
+
* the second reads the first's committed row and throws
|
|
562
|
+
* `namespace_already_proposed` with prior context.
|
|
563
|
+
*
|
|
564
|
+
* Steps:
|
|
565
|
+
* 1. Refuse the control-plane ns + malformed names (`invalid_namespace`).
|
|
566
|
+
* 2. FPP check on the non-archived NamespaceProposal for this ns. A row from
|
|
567
|
+
* another proposer, or an applied one, → `namespace_already_proposed`. An
|
|
568
|
+
* applied=false row from the same signed caller is a stranded earlier attempt
|
|
569
|
+
* and is resumed: steps 5-9 run against it. With no row, an ns installed
|
|
570
|
+
* on this engine other than by an earlier propose_namespace →
|
|
571
|
+
* `invalid_namespace`.
|
|
572
|
+
* 3. Verify dataset for the new ns is provisioned. The host MUST have
|
|
573
|
+
* registered it before calling; missing → `dataset_not_provisioned`.
|
|
574
|
+
* Runs BEFORE the row write so a misconfigured `datasetFor` does not
|
|
575
|
+
* strand an applied=false row.
|
|
576
|
+
* 4. Persist the NamespaceProposal row in the control-plane ns
|
|
577
|
+
* (`applied=false`) through autoCRUD on the caller's transaction, so
|
|
578
|
+
* `_metadata`, `shortId` and the `postWrite` hook apply. Skipped when
|
|
579
|
+
* resuming.
|
|
580
|
+
* 5. `engine.addNamespace(ns, { registry: engine.createRegistry() })`,
|
|
581
|
+
* skipped when a stranded attempt already added it.
|
|
582
|
+
* 6. Install TypeProposal + FieldProposal autoCRUD and the propose_*
|
|
583
|
+
* mutations onto the new ns, skipping entries already registered, and
|
|
584
|
+
* stash the binding in the RegistryStore.
|
|
585
|
+
* 7. Mark the proposal row `applied=true` (autoCRUD-routed update).
|
|
586
|
+
* 8. NOTIFY on the cluster channel `_substrate_proposals_cluster` with the ns
|
|
587
|
+
* name once the caller's transaction commits, so peers can't observe a
|
|
588
|
+
* half-applied state.
|
|
589
|
+
* 9. Return the applied row.
|
|
590
|
+
*
|
|
591
|
+
* The row writes commit with the caller's transaction, so a failure in steps
|
|
592
|
+
* 5-7 rolls the row back and leaves only the install; the same proposer's retry
|
|
593
|
+
* completes it. Reconcile replays only applied=true rows, so until then the ns
|
|
594
|
+
* is not restored on restart.
|
|
595
|
+
*/
|
|
596
|
+
const CLUSTER_CHANNEL = "_substrate_proposals_cluster";
|
|
597
|
+
function makeProposeNamespaceResolver(deps) {
|
|
598
|
+
return async (ctx, args) => {
|
|
599
|
+
const input = args.params ?? {};
|
|
600
|
+
const { ns } = input;
|
|
601
|
+
if (!isProposableNamespace(ns) || ns === deps.controlNamespace) throw new ProposalError("invalid_namespace", `${JSON.stringify(ns)} cannot be proposed (reserved, or not matching [A-Za-z0-9_-]+)`);
|
|
602
|
+
if (input.proposedReason !== void 0 && typeof input.proposedReason !== "string") throw new ProposalError("invalid_params", "'proposedReason' must be a string", { param: "proposedReason" });
|
|
603
|
+
const dataset = args.dataset ?? deps.registryStore.getBinding(deps.controlNamespace).dataset;
|
|
604
|
+
return withProposalLock(dataset, proposalLockKey("namespace", deps.controlNamespace, ns), () => proposeNamespaceLocked(deps, ctx, {
|
|
605
|
+
...args,
|
|
606
|
+
dataset
|
|
607
|
+
}, input));
|
|
608
|
+
};
|
|
609
|
+
}
|
|
610
|
+
/** Steps 2-9, run while holding the proposal lock for this namespace. */
|
|
611
|
+
async function proposeNamespaceLocked(deps, ctx, args, input) {
|
|
612
|
+
const { ns } = input;
|
|
613
|
+
const proposedReason = input.proposedReason ?? "";
|
|
614
|
+
const proposedBy = resolveIdentity(ctx).id;
|
|
615
|
+
const controlBinding = deps.registryStore.getBinding(deps.controlNamespace);
|
|
616
|
+
const controlEngine = controlBinding.engine;
|
|
617
|
+
const existing = await args.dataset.read("NamespaceProposal", {
|
|
618
|
+
where: { AND: [{ ns: { eq: ns } }, { archived: { eq: false } }] },
|
|
619
|
+
limit: 1
|
|
620
|
+
});
|
|
621
|
+
if ((await args.dataset.read("NamespaceProposal", {
|
|
622
|
+
where: { AND: [{ ns: { eq: ns } }, { archived: { eq: true } }] },
|
|
623
|
+
limit: 1
|
|
624
|
+
})).rows.length > 0) throw new ProposalError("namespace_retired", `'${ns}' was dropped and its name is reserved; existing grants may still name it`);
|
|
625
|
+
const prior = existing.rows[0];
|
|
626
|
+
const resuming = prior !== void 0 && prior.applied === false && prior.proposedBy === proposedBy;
|
|
627
|
+
if (prior !== void 0 && !resuming) throw new ProposalError("namespace_already_proposed", `Namespace '${ns}' already proposed (by ${String(prior.proposedBy)})`, {
|
|
628
|
+
by: prior.proposedBy,
|
|
629
|
+
at: prior.proposedAt
|
|
630
|
+
});
|
|
631
|
+
const state = controlEngine?.namespaceState(ns) ?? "absent";
|
|
632
|
+
const held = deps.registryStore.has(ns) ? deps.registryStore.getBinding(ns).hotAdded !== true : state !== "absent";
|
|
633
|
+
if (state === "tombstoned" || !resuming && held) throw new ProposalError("invalid_namespace", `'${ns}' is already installed on this engine and cannot be proposed`);
|
|
634
|
+
const newDataset = deps.datasetFor(ns);
|
|
635
|
+
if (newDataset === void 0) throw new ProposalError("dataset_not_provisioned", `No dataset registered for '${ns}'. Host must register the dataset before propose_namespace.`);
|
|
636
|
+
if (controlEngine === void 0) throw new ProposalError("engine_not_wired", "propose_namespace requires the control-plane engine handle (wired by onStart)");
|
|
637
|
+
let proposalId;
|
|
638
|
+
if (prior !== void 0) proposalId = String(prior.id);
|
|
639
|
+
else {
|
|
640
|
+
proposalId = randomUUID();
|
|
641
|
+
await writeInTx(controlBinding.registry, ctx, args, "createNamespaceProposal", {
|
|
642
|
+
id: proposalId,
|
|
643
|
+
ns,
|
|
644
|
+
proposedBy,
|
|
645
|
+
proposedAt: /* @__PURE__ */ new Date(),
|
|
646
|
+
proposedReason,
|
|
647
|
+
applied: false,
|
|
648
|
+
appliedAt: null,
|
|
649
|
+
supersededByCode: false,
|
|
650
|
+
archived: false
|
|
651
|
+
});
|
|
652
|
+
}
|
|
653
|
+
try {
|
|
654
|
+
installHotAddedNamespace({
|
|
655
|
+
ns,
|
|
656
|
+
dataset: newDataset,
|
|
657
|
+
registryStore: deps.registryStore,
|
|
658
|
+
engine: controlEngine,
|
|
659
|
+
edges: deps.edges,
|
|
660
|
+
...deps.proposeCapability !== void 0 && { proposeCapability: deps.proposeCapability },
|
|
661
|
+
...deps.registerProposalMutations !== void 0 && { registerProposalMutations: deps.registerProposalMutations }
|
|
662
|
+
});
|
|
663
|
+
} finally {
|
|
664
|
+
claimForRollback(deps, ns, controlEngine, args);
|
|
665
|
+
}
|
|
666
|
+
const now = /* @__PURE__ */ new Date();
|
|
667
|
+
await writeInTx(controlBinding.registry, ctx, args, "updateNamespaceProposal", {
|
|
668
|
+
id: proposalId,
|
|
669
|
+
applied: true,
|
|
670
|
+
appliedAt: now
|
|
671
|
+
});
|
|
672
|
+
await notifyAfterCommit(args, () => deps.pubsub.notify(CLUSTER_CHANNEL, ns));
|
|
673
|
+
const rawRow = (await args.dataset.read("NamespaceProposal", { id: proposalId })).rows[0];
|
|
674
|
+
if (!rawRow) throw new Error(`NamespaceProposal row ${proposalId} not found after apply`);
|
|
675
|
+
return {
|
|
676
|
+
...rawRow,
|
|
677
|
+
applied: true,
|
|
678
|
+
appliedAt: now
|
|
679
|
+
};
|
|
680
|
+
}
|
|
681
|
+
/**
|
|
682
|
+
* Take the hot-added `ns` back off the engine if the caller's transaction
|
|
683
|
+
* rolls back, so it cannot stay live and writable with no proposal row (whose
|
|
684
|
+
* writes nothing would replay at boot). Runs only when this attempt holds a
|
|
685
|
+
* hot-added binding, i.e. its `addNamespace` landed or it adopted a stranded
|
|
686
|
+
* one. The claim is a token on the binding: a later attempt that adopts the
|
|
687
|
+
* binding before this undo runs (the proposal lock is gone by then) replaces
|
|
688
|
+
* the token, and this undo then leaves the namespace to it.
|
|
689
|
+
*/
|
|
690
|
+
function claimForRollback(deps, ns, engine, args) {
|
|
691
|
+
if (args.afterTx === void 0 || !deps.registryStore.has(ns)) return;
|
|
692
|
+
const binding = deps.registryStore.getBinding(ns);
|
|
693
|
+
if (binding.hotAdded !== true) return;
|
|
694
|
+
const claim = {};
|
|
695
|
+
binding.claim = claim;
|
|
696
|
+
const control = deps.registryStore.getBinding(deps.controlNamespace).dataset;
|
|
697
|
+
args.afterTx(async ({ committed }) => {
|
|
698
|
+
if (committed || !deps.registryStore.has(ns)) return;
|
|
699
|
+
const current = deps.registryStore.getBinding(ns);
|
|
700
|
+
if (current !== binding || current.claim !== claim) return;
|
|
701
|
+
if (engine.namespaceState(ns) !== "live") return;
|
|
702
|
+
if ((await control.read("NamespaceProposal", {
|
|
703
|
+
where: { AND: [
|
|
704
|
+
{ ns: { eq: ns } },
|
|
705
|
+
{ archived: { eq: false } },
|
|
706
|
+
{ applied: { eq: true } }
|
|
707
|
+
] },
|
|
708
|
+
limit: 1
|
|
709
|
+
})).rows.length > 0) return;
|
|
710
|
+
if (deps.registryStore.getBinding(ns) !== binding || binding.claim !== claim) return;
|
|
711
|
+
engine.removeNamespace(ns);
|
|
712
|
+
deps.registryStore.delete(ns);
|
|
713
|
+
});
|
|
714
|
+
}
|
|
715
|
+
|
|
716
|
+
//#endregion
|
|
717
|
+
//#region ../../plugins/substrate-proposals/src/multi-instance.ts
|
|
718
|
+
async function setupNamespaceListener(args) {
|
|
719
|
+
await args.pubsub.listen(args.channel, async (payload) => {
|
|
720
|
+
await applyProposalFromNotification({
|
|
721
|
+
namespace: args.namespace,
|
|
722
|
+
proposalId: payload,
|
|
723
|
+
registryStore: args.registryStore
|
|
724
|
+
}).catch(() => {});
|
|
725
|
+
});
|
|
726
|
+
}
|
|
727
|
+
async function applyProposalFromNotification(args) {
|
|
728
|
+
const binding = args.registryStore.getBinding(args.namespace);
|
|
729
|
+
const typeHit = await binding.dataset.read("TypeProposal", { id: args.proposalId });
|
|
730
|
+
if (typeHit.rows.length > 0) {
|
|
731
|
+
const row = typeHit.rows[0];
|
|
732
|
+
if (row.applied === true && !binding.registry.get(row.typeName)) {
|
|
733
|
+
const fields = JSON.parse(row.fieldsJson);
|
|
734
|
+
applyTypeProposal({
|
|
735
|
+
namespace: args.namespace,
|
|
736
|
+
typeName: row.typeName,
|
|
737
|
+
fields,
|
|
738
|
+
registryStore: args.registryStore,
|
|
739
|
+
dataset: binding.dataset,
|
|
740
|
+
edges: binding.edges
|
|
741
|
+
});
|
|
742
|
+
}
|
|
743
|
+
return;
|
|
744
|
+
}
|
|
745
|
+
const fieldHit = await binding.dataset.read("FieldProposal", { id: args.proposalId });
|
|
746
|
+
if (fieldHit.rows.length > 0) {
|
|
747
|
+
const row = fieldHit.rows[0];
|
|
748
|
+
if (row.applied === true) {
|
|
749
|
+
const entry = binding.registry.get(row.targetType);
|
|
750
|
+
if (entry && fieldNeedsReplay(entry, row)) {
|
|
751
|
+
const fieldSpec = JSON.parse(row.fieldSpecJson);
|
|
752
|
+
applyFieldProposal({
|
|
753
|
+
namespace: args.namespace,
|
|
754
|
+
targetType: row.targetType,
|
|
755
|
+
fieldName: row.fieldName,
|
|
756
|
+
fieldSpec,
|
|
757
|
+
registryStore: args.registryStore,
|
|
758
|
+
dataset: binding.dataset,
|
|
759
|
+
edges: binding.edges
|
|
760
|
+
});
|
|
761
|
+
}
|
|
762
|
+
}
|
|
763
|
+
}
|
|
764
|
+
}
|
|
765
|
+
/**
|
|
766
|
+
* A field proposal needs replaying when its field is absent, or when it
|
|
767
|
+
* narrowed an enum: the type was registered with the wider spec, and the
|
|
768
|
+
* narrowing exists only in the proposal row.
|
|
769
|
+
*/
|
|
770
|
+
function fieldNeedsReplay(entry, row) {
|
|
771
|
+
return !(row.fieldName in entry.fields) || typeof row.valueMapJson === "string";
|
|
772
|
+
}
|
|
773
|
+
async function reconcileNamespace(args) {
|
|
774
|
+
const binding = args.registryStore.getBinding(args.namespace);
|
|
775
|
+
const typeRows = await binding.dataset.read("TypeProposal", {
|
|
776
|
+
where: { AND: [
|
|
777
|
+
{ applied: { eq: true } },
|
|
778
|
+
{ supersededByCode: { eq: false } },
|
|
779
|
+
{ archived: { eq: false } }
|
|
780
|
+
] },
|
|
781
|
+
limit: 1e4
|
|
782
|
+
});
|
|
783
|
+
for (const row of typeRows.rows) {
|
|
784
|
+
if (binding.registry.get(row.typeName)) continue;
|
|
785
|
+
try {
|
|
786
|
+
const fields = JSON.parse(row.fieldsJson);
|
|
787
|
+
applyTypeProposal({
|
|
788
|
+
namespace: args.namespace,
|
|
789
|
+
typeName: row.typeName,
|
|
790
|
+
fields,
|
|
791
|
+
registryStore: args.registryStore,
|
|
792
|
+
dataset: binding.dataset,
|
|
793
|
+
edges: binding.edges
|
|
794
|
+
});
|
|
795
|
+
} catch (err) {
|
|
796
|
+
args.onSkip?.(row, err);
|
|
797
|
+
}
|
|
798
|
+
}
|
|
799
|
+
const fieldRows = await binding.dataset.read("FieldProposal", {
|
|
800
|
+
where: { AND: [
|
|
801
|
+
{ applied: { eq: true } },
|
|
802
|
+
{ supersededByCode: { eq: false } },
|
|
803
|
+
{ archived: { eq: false } }
|
|
804
|
+
] },
|
|
805
|
+
orderBy: [{ appliedAt: "asc" }],
|
|
806
|
+
limit: 1e4
|
|
807
|
+
});
|
|
808
|
+
for (const row of fieldRows.rows) {
|
|
809
|
+
const entry = binding.registry.get(row.targetType);
|
|
810
|
+
if (!entry || !fieldNeedsReplay(entry, row)) continue;
|
|
811
|
+
try {
|
|
812
|
+
const fieldSpec = JSON.parse(row.fieldSpecJson);
|
|
813
|
+
applyFieldProposal({
|
|
814
|
+
namespace: args.namespace,
|
|
815
|
+
targetType: row.targetType,
|
|
816
|
+
fieldName: row.fieldName,
|
|
817
|
+
fieldSpec,
|
|
818
|
+
registryStore: args.registryStore,
|
|
819
|
+
dataset: binding.dataset,
|
|
820
|
+
edges: binding.edges
|
|
821
|
+
});
|
|
822
|
+
} catch (err) {
|
|
823
|
+
args.onSkip?.(row, err);
|
|
824
|
+
}
|
|
825
|
+
}
|
|
826
|
+
}
|
|
827
|
+
/**
|
|
828
|
+
* Shared install path for a hot-added namespace. Three call sites use this:
|
|
829
|
+
* - `setupClusterNamespaceListener` (NOTIFY-triggered install on a peer)
|
|
830
|
+
* - `reconcileClusterNamespaces` (cold-boot replay of applied=true rows)
|
|
831
|
+
* - `makeProposeNamespaceResolver` (the original propose_namespace mutation)
|
|
832
|
+
*
|
|
833
|
+
* Resumable: when `registryStore` already binds `ns` (an earlier install
|
|
834
|
+
* failed part-way), the engine add is skipped and the existing binding is
|
|
835
|
+
* completed, registering only the entries not yet present. Uses
|
|
836
|
+
* `engine.createRegistry()` so the plugin stays zero-runtime-dep on substrate-core.
|
|
837
|
+
*
|
|
838
|
+
* The listener and reconcile skip a bound ns before calling; the resolver
|
|
839
|
+
* calls through to resume a stranded proposal.
|
|
840
|
+
*
|
|
841
|
+
* @throws Error when `ns` is not a name propose_namespace accepts (a replayed
|
|
842
|
+
* row is caller-written data), from `engine.addNamespace` when the engine
|
|
843
|
+
* already holds an unbound `ns`, or from `registerProposalMutations`
|
|
844
|
+
*/
|
|
845
|
+
function installHotAddedNamespace(args) {
|
|
846
|
+
if (!isProposableNamespace(args.ns)) throw new Error(`refusing to install ${JSON.stringify(args.ns)}: not a proposable namespace`);
|
|
847
|
+
let binding = args.registryStore.has(args.ns) ? args.registryStore.getBinding(args.ns) : void 0;
|
|
848
|
+
if (binding === void 0) {
|
|
849
|
+
const newRegistry = args.engine.createRegistry();
|
|
850
|
+
args.engine.addNamespace(args.ns, { registry: newRegistry });
|
|
851
|
+
binding = {
|
|
852
|
+
registry: newRegistry,
|
|
853
|
+
dataset: args.dataset,
|
|
854
|
+
edges: args.edges,
|
|
855
|
+
engine: args.engine,
|
|
856
|
+
invalidateSchemaCaches: () => args.engine.invalidateSchemaCaches(args.ns),
|
|
857
|
+
hotAdded: true
|
|
858
|
+
};
|
|
859
|
+
args.registryStore.set(args.ns, binding);
|
|
860
|
+
}
|
|
861
|
+
const registry = skipRegistered(binding.registry);
|
|
862
|
+
defineProposalTypes(args.ns, args.proposeCapability).install({
|
|
863
|
+
registry,
|
|
864
|
+
dataset: binding.dataset,
|
|
865
|
+
edges: binding.edges
|
|
866
|
+
});
|
|
867
|
+
if (args.registerProposalMutations !== void 0) args.registerProposalMutations({
|
|
868
|
+
namespace: args.ns,
|
|
869
|
+
dataset: binding.dataset,
|
|
870
|
+
edges: binding.edges,
|
|
871
|
+
registry
|
|
872
|
+
});
|
|
873
|
+
}
|
|
874
|
+
/** A view of `registry` whose `register` is a no-op for names already present. */
|
|
875
|
+
function skipRegistered(registry) {
|
|
876
|
+
return {
|
|
877
|
+
register: (key, input) => {
|
|
878
|
+
if (!registry.has(key)) registry.register(key, input);
|
|
879
|
+
},
|
|
880
|
+
replace: (key, input) => registry.replace(key, input),
|
|
881
|
+
get: (key) => registry.get(key),
|
|
882
|
+
has: (key) => registry.has(key),
|
|
883
|
+
all: () => registry.all(),
|
|
884
|
+
...registry.unregister !== void 0 && { unregister: (key) => registry.unregister?.(key) },
|
|
885
|
+
get epoch() {
|
|
886
|
+
return registry.epoch;
|
|
887
|
+
}
|
|
888
|
+
};
|
|
889
|
+
}
|
|
890
|
+
/**
|
|
891
|
+
* Subscribe to the cluster-wide namespace channel (`_substrate_proposals_cluster`).
|
|
892
|
+
*
|
|
893
|
+
* When a peer instance applies a `propose_namespace` mutation, it fires a
|
|
894
|
+
* NOTIFY with the new ns name. This handler installs the ns into the local
|
|
895
|
+
* engine + registers proposal CRUD types + stashes the binding so subsequent
|
|
896
|
+
* per-ns NOTIFYs (TypeProposal / FieldProposal applies) can find a registry.
|
|
897
|
+
*
|
|
898
|
+
* Idempotency: if `registryStore.has(ns)` is already true, no-op. Covers
|
|
899
|
+
* cold-boot reconcile races and accidental re-broadcasts. The check
|
|
900
|
+
* runs BEFORE `engine.addNamespace`, whose collision semantics would otherwise
|
|
901
|
+
* throw — and throwing in a NOTIFY handler kills the listener.
|
|
902
|
+
*
|
|
903
|
+
* Race-window assumption: NOTIFY delivery is serial per channel — pg LISTEN
|
|
904
|
+
* guarantees this; the test's LoopbackPubSub honors it (synchronous await
|
|
905
|
+
* loop). A future async-fanout PubSub would race the has/set window and
|
|
906
|
+
* need a lock.
|
|
907
|
+
*
|
|
908
|
+
* If the ns is broadcast but the local host hasn't provisioned a dataset for
|
|
909
|
+
* it (hosts diverge on dataset registration), the handler skips and emits
|
|
910
|
+
* `_system_proposals.cluster_skip_no_dataset` via `args.metric`.
|
|
911
|
+
* Throwing in a NOTIFY handler tears down the LISTEN connection, so a metric
|
|
912
|
+
* is the only way to surface this without losing the listener.
|
|
913
|
+
*/
|
|
914
|
+
async function setupClusterNamespaceListener(args) {
|
|
915
|
+
await args.pubsub.listen(CLUSTER_CHANNEL, async (ns) => {
|
|
916
|
+
if (args.registryStore.has(ns)) return;
|
|
917
|
+
const dataset = args.datasetFor(ns);
|
|
918
|
+
if (dataset === void 0) {
|
|
919
|
+
args.metric?.("_system_proposals.cluster_skip_no_dataset", { ns });
|
|
920
|
+
return;
|
|
921
|
+
}
|
|
922
|
+
try {
|
|
923
|
+
installHotAddedNamespace({
|
|
924
|
+
ns,
|
|
925
|
+
dataset,
|
|
926
|
+
registryStore: args.registryStore,
|
|
927
|
+
engine: args.engine,
|
|
928
|
+
edges: args.edges,
|
|
929
|
+
...args.proposeCapability !== void 0 && { proposeCapability: args.proposeCapability },
|
|
930
|
+
...args.registerProposalMutations !== void 0 && { registerProposalMutations: args.registerProposalMutations }
|
|
931
|
+
});
|
|
932
|
+
} catch (err) {
|
|
933
|
+
args.metric?.("_system_proposals.cluster_skip_invalid", {
|
|
934
|
+
ns,
|
|
935
|
+
error: err instanceof Error ? err.message : String(err)
|
|
936
|
+
});
|
|
937
|
+
}
|
|
938
|
+
});
|
|
939
|
+
}
|
|
940
|
+
/**
|
|
941
|
+
* Cold-boot replay of applied=true NamespaceProposal rows from the control-plane
|
|
942
|
+
* dataset. For each row whose ns isn't already in registryStore (idempotent
|
|
943
|
+
* against partial-replay states) and whose dataset is provisioned locally,
|
|
944
|
+
* install it into the engine + register proposal CRUD types + set binding.
|
|
945
|
+
*
|
|
946
|
+
* Returns the list of namespaces actually added so the caller can extend its
|
|
947
|
+
* per-ns reconcile pass to cover them too — TypeProposals proposed for
|
|
948
|
+
* hot-added namespaces before restart need to be replayed alongside the
|
|
949
|
+
* static-ownedNamespace TypeProposals.
|
|
950
|
+
*
|
|
951
|
+
* Mirrors setupClusterNamespaceListener's per-ns install path.
|
|
952
|
+
*
|
|
953
|
+
* Silently skips a row whose dataset the host has not provisioned (the
|
|
954
|
+
* cluster listener's misconfig case): throwing would tear down boot. Unlike
|
|
955
|
+
* the listener, no metric is emitted.
|
|
956
|
+
*/
|
|
957
|
+
async function reconcileClusterNamespaces(args) {
|
|
958
|
+
const rows = await args.registryStore.getBinding(args.controlNamespace).dataset.read("NamespaceProposal", {
|
|
959
|
+
where: { AND: [{ applied: { eq: true } }, { archived: { eq: false } }] },
|
|
960
|
+
limit: 1e4
|
|
961
|
+
});
|
|
962
|
+
const added = [];
|
|
963
|
+
for (const row of rows.rows) {
|
|
964
|
+
const ns = row.ns;
|
|
965
|
+
if (args.registryStore.has(ns)) continue;
|
|
966
|
+
const dataset = args.datasetFor(ns);
|
|
967
|
+
if (dataset === void 0) continue;
|
|
968
|
+
try {
|
|
969
|
+
installHotAddedNamespace({
|
|
970
|
+
ns,
|
|
971
|
+
dataset,
|
|
972
|
+
registryStore: args.registryStore,
|
|
973
|
+
engine: args.engine,
|
|
974
|
+
edges: args.edges,
|
|
975
|
+
...args.proposeCapability !== void 0 && { proposeCapability: args.proposeCapability },
|
|
976
|
+
...args.registerProposalMutations !== void 0 && { registerProposalMutations: args.registerProposalMutations }
|
|
977
|
+
});
|
|
978
|
+
} catch (err) {
|
|
979
|
+
args.onSkip?.(row, err);
|
|
980
|
+
continue;
|
|
981
|
+
}
|
|
982
|
+
added.push(ns);
|
|
983
|
+
}
|
|
984
|
+
return added;
|
|
985
|
+
}
|
|
986
|
+
/** Peers are told on this channel that a hot-added namespace was dropped. */
|
|
987
|
+
const CLUSTER_DROP_CHANNEL = "_substrate_proposals_cluster_drop";
|
|
988
|
+
/** True when `ns` is a namespace this plugin hot-added and still holds. */
|
|
989
|
+
function isHotAdded(registryStore, ns) {
|
|
990
|
+
return registryStore.has(ns) && registryStore.getBinding(ns).hotAdded === true;
|
|
991
|
+
}
|
|
992
|
+
/**
|
|
993
|
+
* Drop participant: inside the drop's own transaction, archive every
|
|
994
|
+
* NamespaceProposal row for the dropped namespace, so boot replay does not
|
|
995
|
+
* reinstall it and the name stays reserved (`namespace_retired`). Decided from
|
|
996
|
+
* the control plane, not this process's bindings: only a proposed namespace
|
|
997
|
+
* has rows. A throw rolls the drop back.
|
|
998
|
+
*/
|
|
999
|
+
function namespaceDropParticipant(controlNamespace) {
|
|
1000
|
+
return {
|
|
1001
|
+
namespaces: [controlNamespace],
|
|
1002
|
+
async onDrop(ns, datasetFor) {
|
|
1003
|
+
const control = datasetFor(controlNamespace);
|
|
1004
|
+
for (;;) {
|
|
1005
|
+
const standing = await control.read("NamespaceProposal", {
|
|
1006
|
+
where: { AND: [{ ns: { eq: ns } }, { archived: { eq: false } }] },
|
|
1007
|
+
limit: 500
|
|
1008
|
+
});
|
|
1009
|
+
if (standing.rows.length === 0) return;
|
|
1010
|
+
await control.write("NamespaceProposal", standing.rows.map((row) => ({
|
|
1011
|
+
...row,
|
|
1012
|
+
archived: true
|
|
1013
|
+
})));
|
|
1014
|
+
}
|
|
1015
|
+
}
|
|
1016
|
+
};
|
|
1017
|
+
}
|
|
1018
|
+
/**
|
|
1019
|
+
* After a drop has committed (its rows archived by the participant above):
|
|
1020
|
+
* take a hot-added namespace off this engine and tell peers to do the same.
|
|
1021
|
+
*/
|
|
1022
|
+
async function retireDroppedNamespace(args) {
|
|
1023
|
+
if (!isHotAdded(args.registryStore, args.ns)) return;
|
|
1024
|
+
args.engine.removeNamespace(args.ns);
|
|
1025
|
+
args.registryStore.delete(args.ns);
|
|
1026
|
+
await args.pubsub.notify(CLUSTER_DROP_CHANNEL, args.ns);
|
|
1027
|
+
}
|
|
1028
|
+
/**
|
|
1029
|
+
* Take a peer-dropped hot-added namespace off this engine too. The message is
|
|
1030
|
+
* only a hint: the namespace is removed only when no live NamespaceProposal
|
|
1031
|
+
* row stands behind it in the shared control plane.
|
|
1032
|
+
*/
|
|
1033
|
+
async function setupClusterDropListener(args) {
|
|
1034
|
+
await args.pubsub.listen(CLUSTER_DROP_CHANNEL, async (ns) => {
|
|
1035
|
+
const { registryStore } = args;
|
|
1036
|
+
if (!isHotAdded(registryStore, ns)) return;
|
|
1037
|
+
try {
|
|
1038
|
+
if ((await registryStore.getBinding(args.controlNamespace).dataset.read("NamespaceProposal", {
|
|
1039
|
+
where: { AND: [
|
|
1040
|
+
{ ns: { eq: ns } },
|
|
1041
|
+
{ archived: { eq: false } },
|
|
1042
|
+
{ applied: { eq: true } }
|
|
1043
|
+
] },
|
|
1044
|
+
limit: 1
|
|
1045
|
+
})).rows.length > 0) {
|
|
1046
|
+
args.metric?.("_system_proposals.cluster_drop_ignored", { ns });
|
|
1047
|
+
return;
|
|
1048
|
+
}
|
|
1049
|
+
args.engine.removeNamespace(ns);
|
|
1050
|
+
registryStore.delete(ns);
|
|
1051
|
+
} catch (err) {
|
|
1052
|
+
args.metric?.("_system_proposals.cluster_drop_failed", {
|
|
1053
|
+
ns,
|
|
1054
|
+
error: err instanceof Error ? err.message : String(err)
|
|
1055
|
+
});
|
|
1056
|
+
}
|
|
1057
|
+
});
|
|
1058
|
+
}
|
|
1059
|
+
|
|
1060
|
+
//#endregion
|
|
1061
|
+
//#region ../../plugins/substrate-proposals/src/onboard.ts
|
|
1062
|
+
/**
|
|
1063
|
+
* Onboard contribution for substrate-proposals. Returned verbatim by the
|
|
1064
|
+
* binary's `GET /substrate/v1/onboard` under
|
|
1065
|
+
* `instructions.plugins["substrate-proposals"]`, and served directly at
|
|
1066
|
+
* `GET /plugins/substrate-proposals/onboard` by `registerOnboardRoute`.
|
|
1067
|
+
*
|
|
1068
|
+
* Target reader: a cold-start agent that can see `propose_namespace`,
|
|
1069
|
+
* `propose_type`, and `propose_field` in the federated schema but doesn't
|
|
1070
|
+
* know when or how to reach for them. This body explains the workflow, the
|
|
1071
|
+
* wire shape, and the guardrails — enough for an LLM to compose a correct
|
|
1072
|
+
* call without reading plugin source.
|
|
1073
|
+
*/
|
|
1074
|
+
function buildOnboardBody(ownedNamespaces) {
|
|
1075
|
+
return {
|
|
1076
|
+
plugin: "substrate-proposals",
|
|
1077
|
+
description: `Lets authorised agents add new namespaces, new types, and new fields at runtime. Proposed namespaces and types become immediately queryable/mutatable via autoCRUD — no restart, no code change. The reserved control-plane namespace \`${CONTROL_NAMESPACE}\` is always installed; it houses the NamespaceProposal autoCRUD type that records every runtime namespace addition for audit + restart recovery. Statically-owned namespaces in this deployment: ` + (ownedNamespaces.length > 0 ? ownedNamespaces.join(", ") : "(none — runtime-only via propose_namespace)"),
|
|
1078
|
+
capability: "Every propose_* call is gated by the `substrate.propose` capability on the caller identity (or the name set by the plugin's `proposeCapability` config). Without the capability, the policy denies with code `policy_denied`.",
|
|
1079
|
+
whenToUse: [
|
|
1080
|
+
"Reach for propose_namespace when you need a brand-new namespace (e.g. per-user / per-tenant partition) that no current ownedNamespace covers. Hot-added namespaces support the same propose_type / propose_field surface as static ownedNamespaces.",
|
|
1081
|
+
"Reach for propose_type when the user describes a concept you don't see in the schema and an owned namespace covers that domain (e.g. user asks you to 'track the books they lend out' and `home` is an owned namespace).",
|
|
1082
|
+
"Reach for propose_field when an existing type needs a new attribute (additive) or a new edge (via a `crossRef` fieldSpec).",
|
|
1083
|
+
"DON'T propose for a one-off container — ask yourself if the concept is durable. A proposal shipped into the typed store is a commitment.",
|
|
1084
|
+
"DON'T propose_type if the namespace is code-declared and outside ownedNamespaces. Propose will reject with `unowned_namespace` — propose_namespace it first if appropriate."
|
|
1085
|
+
],
|
|
1086
|
+
mutations: {
|
|
1087
|
+
propose_namespace: {
|
|
1088
|
+
summary: `Hot-add a new namespace to the live engine without a restart. The new ns becomes immediately addressable by propose_type / propose_field. Recorded as a NamespaceProposal row in the \`${CONTROL_NAMESPACE}\` control-plane ns for audit + restart recovery.`,
|
|
1089
|
+
frameKey: `${CONTROL_NAMESPACE}/propose_namespace`,
|
|
1090
|
+
params: {
|
|
1091
|
+
ns: "string — the new namespace name. Cannot be the reserved control-plane name.",
|
|
1092
|
+
proposedReason: "string — short human-readable rationale"
|
|
1093
|
+
},
|
|
1094
|
+
returns: {
|
|
1095
|
+
id: "uuid — the NamespaceProposal record id",
|
|
1096
|
+
ns: "string",
|
|
1097
|
+
applied: "boolean — true once the namespace is live in the engine",
|
|
1098
|
+
appliedAt: "ISO-8601 datetime",
|
|
1099
|
+
proposedBy: "string — the signed caller id; never taken from params",
|
|
1100
|
+
"proposedAt / proposedReason": "when, and the echoed rationale",
|
|
1101
|
+
supersededByCode: "boolean — true when a later code deploy adds the same ns to static ownedNamespaces"
|
|
1102
|
+
}
|
|
1103
|
+
},
|
|
1104
|
+
propose_type: {
|
|
1105
|
+
summary: "Create a new type + its autoCRUD surface in one atomic write.",
|
|
1106
|
+
frameKey: "<ns>/propose_type where <ns> must be in ownedNamespaces",
|
|
1107
|
+
params: {
|
|
1108
|
+
typeName: "string — PascalCase, unique within the namespace",
|
|
1109
|
+
fields: "object — FieldSpecJson map keyed by camelCase field name (see fieldSpecJson below)",
|
|
1110
|
+
proposedReason: "string — short human-readable rationale"
|
|
1111
|
+
},
|
|
1112
|
+
returns: {
|
|
1113
|
+
id: "uuid — the TypeProposal record id",
|
|
1114
|
+
typeName: "string",
|
|
1115
|
+
applied: "boolean — true once the type is live in the registry",
|
|
1116
|
+
appliedAt: "ISO-8601 datetime",
|
|
1117
|
+
resultingSchemaVersion: "string — schemaVersion hash of the registry AFTER this proposal applied; null until applied",
|
|
1118
|
+
proposedBy: "string — the signed caller id; never taken from params",
|
|
1119
|
+
"proposedAt / proposedReason": "when, and the echoed rationale",
|
|
1120
|
+
supersededByCode: "boolean — true when a later code deploy declared the same name"
|
|
1121
|
+
}
|
|
1122
|
+
},
|
|
1123
|
+
propose_field: {
|
|
1124
|
+
summary: "Add one field to an existing type (code-declared or previously proposed).",
|
|
1125
|
+
frameKey: "<ns>/propose_field where <ns> is the namespace containing targetType",
|
|
1126
|
+
params: {
|
|
1127
|
+
targetType: "string — name of the type to extend",
|
|
1128
|
+
fieldName: "string — new field, camelCase, unique on this type",
|
|
1129
|
+
fieldSpec: "FieldSpecJson — single field; see variants below",
|
|
1130
|
+
proposedReason: "string",
|
|
1131
|
+
valueMap: "optional — stranded source value → target value (null to knowingly strand). Only for enum narrowing: runs migrate-first-then-narrow. Without it, re-proposing an existing field with a different spec is refused."
|
|
1132
|
+
},
|
|
1133
|
+
returns: {
|
|
1134
|
+
id: "uuid — the FieldProposal record id",
|
|
1135
|
+
targetType: "string",
|
|
1136
|
+
fieldName: "string",
|
|
1137
|
+
applied: "boolean",
|
|
1138
|
+
appliedAt: "ISO-8601 datetime",
|
|
1139
|
+
resultingSchemaVersion: "string — schemaVersion hash of the registry AFTER this proposal applied; null until applied",
|
|
1140
|
+
valueMapJson: "the supplied map as JSON, null when none",
|
|
1141
|
+
migration: "present only when the destructive path ran — { migrated, stranded, rowsScanned, truncated }"
|
|
1142
|
+
}
|
|
1143
|
+
}
|
|
1144
|
+
},
|
|
1145
|
+
fieldSpecJson: {
|
|
1146
|
+
description: "Narrow wire format mirroring the autoCRUD-expressible subset of FieldDef. Only these four shapes are accepted. Anything more expressive needs code + PR.",
|
|
1147
|
+
variants: {
|
|
1148
|
+
scalar: {
|
|
1149
|
+
shape: "{ kind: \"scalar\", type: \"string\"|\"number\"|\"boolean\"|\"date\"|\"json\", indexed?: bool, nullable?: bool }",
|
|
1150
|
+
notes: "indexed defaults to true for string/number/boolean/date, and is forced false for json (opaque body — no per-leaf filtering). readonly is reserved for engine-managed fields. Use type:\"json\" for arbitrary nested blobs you do not need to filter on (audit details, free-form metadata). Use kind:\"struct\" instead when you have a known nested shape and want per-field where-clause support."
|
|
1151
|
+
},
|
|
1152
|
+
crossRef: {
|
|
1153
|
+
shape: "{ kind: \"crossRef\", ns: string, type: string, onDelete?: \"set_null\"|\"cascade\"|\"restrict\"|\"orphan\", indexed?: bool, nullable?: bool }",
|
|
1154
|
+
notes: "Use crossRef to declare an edge. Cross-namespace edges work when both ns values are in the plugin's ownedNamespaces. onDelete defaults to \"set_null\". For N:M, propose a join type with two crossRef fields — v2 does not model N:M natively."
|
|
1155
|
+
},
|
|
1156
|
+
struct: {
|
|
1157
|
+
shape: "{ kind: \"struct\", fields: Record<string, FieldSpecJson>, nullable?: bool }",
|
|
1158
|
+
notes: "Nested struct; each inner field is itself a FieldSpecJson."
|
|
1159
|
+
},
|
|
1160
|
+
list: {
|
|
1161
|
+
shape: "{ kind: \"list\", of: FieldSpecJson, nullable?: bool }",
|
|
1162
|
+
notes: "Homogeneous list. For list-of-struct: { kind: \"list\", of: { kind: \"struct\", ... } }."
|
|
1163
|
+
}
|
|
1164
|
+
}
|
|
1165
|
+
},
|
|
1166
|
+
constraints: [
|
|
1167
|
+
"AutoCRUD-only: every proposed type gets the standard create/get/update/delete/list surface. No custom resolvers — those require code.",
|
|
1168
|
+
"Additive, with one exception: propose_type rejects if the name exists; propose_field rejects with `destructive_change_required` if the field exists with a different spec, unless the change narrows an enum and a valueMap is supplied. That path rewrites every stored value the map names before narrowing, so it changes data, not just schema.",
|
|
1169
|
+
"First-past-the-post: concurrent proposes of the same name (namespace, type, or field) are serialised by a lock on that name — a database-wide advisory lock on a pg backend, a process-local lock otherwise. The first to take it wins; the next reads its row and gets `namespace_already_proposed` / `type_already_proposed` with the prior proposedBy/at in details, or, for a field with an identical spec, the prior FieldProposal row.",
|
|
1170
|
+
"Engine-injected fields: every proposed type gets a readonly+indexed `shortId: number` field auto-added by the plugin — callers must NOT declare shortId themselves.",
|
|
1171
|
+
`Proposals are first-class data: every NamespaceProposal / TypeProposal / FieldProposal is queryable as a normal type. NamespaceProposal lives in \`${CONTROL_NAMESPACE}\`; TypeProposal / FieldProposal live in their target namespace.`,
|
|
1172
|
+
"Hot-added namespaces are first-class: a namespace created via propose_namespace supports the same propose_type / propose_field surface as a static ownedNamespace, and survives restarts via NamespaceProposal replay on cold boot."
|
|
1173
|
+
],
|
|
1174
|
+
collisions: {
|
|
1175
|
+
namespace_already_proposed: "A NamespaceProposal with this ns name already exists (non-archived). First-past-the-post — the prior proposer wins. Error details include `{ by, at }` from the prior proposal so the caller can decide whether to retry under a different name or proceed against the existing ns. Exception: if your own earlier propose_namespace for this ns failed part-way (its row is still applied=false), re-sending it under the same identity completes it instead.",
|
|
1176
|
+
namespace_retired: "This ns was proposed and later dropped. Its name stays reserved, because keys and invites grant namespaces by name and would otherwise reach a new namespace under the old one. Pick a different name.",
|
|
1177
|
+
invalid_namespace: `Reserved or malformed ns. The control-plane name (\`${CONTROL_NAMESPACE}\`) cannot be proposed; a name must match [A-Za-z0-9_-]+, and a namespace the host already installed is rejected. Pick a different name.`,
|
|
1178
|
+
dataset_not_provisioned: "The host has not registered a dataset for the requested ns. propose_namespace will not auto-provision storage — backend selection is the host's responsibility. Ensure the binary or embedding host wires `datasetFor(ns)` before calling.",
|
|
1179
|
+
type_already_proposed: "A TypeProposal with this typeName already exists in the namespace. Use propose_field to extend it; do not re-propose.",
|
|
1180
|
+
type_already_exists: "A code-declared type (or a previously-applied proposal) already owns this name. Same resolution path as above.",
|
|
1181
|
+
destructive_change_required: "A field of the same name exists on targetType with a different spec. This is a destructive change. Pick a different fieldName, or accept that evolving the shape needs code.",
|
|
1182
|
+
unknown_type: "targetType is not registered. propose_type it first.",
|
|
1183
|
+
unowned_namespace: "Namespace isn't in this plugin instance's ownedNamespaces and has not been hot-added via propose_namespace. Either propose_namespace it first, or accept that proposals are scoped per-deployment.",
|
|
1184
|
+
invalid_field_spec: "fieldSpec did not match one of the four allowed shapes (scalar / crossRef / struct / list), or a crossRef targets a type outside the namespaces this plugin owns. Check kind, nesting, type spellings and crossRef targets.",
|
|
1185
|
+
invalid_params: "A required param is missing or malformed: typeName / targetType / fieldName must match [A-Za-z_][A-Za-z0-9_]*, fields must be a non-empty object, proposedReason a string."
|
|
1186
|
+
},
|
|
1187
|
+
examples: {
|
|
1188
|
+
addNewNamespace: { mutate: { [`${CONTROL_NAMESPACE}/propose_namespace`]: {
|
|
1189
|
+
params: {
|
|
1190
|
+
ns: "home_user_42",
|
|
1191
|
+
proposedReason: "Provision per-user home namespace on demand — host has dataset wired."
|
|
1192
|
+
},
|
|
1193
|
+
fields: {
|
|
1194
|
+
id: true,
|
|
1195
|
+
ns: true,
|
|
1196
|
+
applied: true,
|
|
1197
|
+
appliedAt: true
|
|
1198
|
+
}
|
|
1199
|
+
} } },
|
|
1200
|
+
addNewType: { mutate: { [`${ownedNamespaces[0] ?? "<ns>"}/propose_type`]: {
|
|
1201
|
+
params: {
|
|
1202
|
+
typeName: "Dress",
|
|
1203
|
+
fields: {
|
|
1204
|
+
name: {
|
|
1205
|
+
kind: "scalar",
|
|
1206
|
+
type: "string"
|
|
1207
|
+
},
|
|
1208
|
+
size: {
|
|
1209
|
+
kind: "scalar",
|
|
1210
|
+
type: "string",
|
|
1211
|
+
nullable: true
|
|
1212
|
+
},
|
|
1213
|
+
color: {
|
|
1214
|
+
kind: "scalar",
|
|
1215
|
+
type: "string",
|
|
1216
|
+
nullable: true
|
|
1217
|
+
}
|
|
1218
|
+
},
|
|
1219
|
+
proposedReason: "User asked to track dresses in their closet."
|
|
1220
|
+
},
|
|
1221
|
+
fields: {
|
|
1222
|
+
id: true,
|
|
1223
|
+
typeName: true,
|
|
1224
|
+
applied: true
|
|
1225
|
+
}
|
|
1226
|
+
} } },
|
|
1227
|
+
addFieldToExistingType: { mutate: { [`${ownedNamespaces[0] ?? "<ns>"}/propose_field`]: {
|
|
1228
|
+
params: {
|
|
1229
|
+
targetType: "Dress",
|
|
1230
|
+
fieldName: "brand",
|
|
1231
|
+
fieldSpec: {
|
|
1232
|
+
kind: "scalar",
|
|
1233
|
+
type: "string",
|
|
1234
|
+
nullable: true
|
|
1235
|
+
},
|
|
1236
|
+
proposedReason: "Extend Dress with brand — user mentioned Reformation."
|
|
1237
|
+
},
|
|
1238
|
+
fields: {
|
|
1239
|
+
id: true,
|
|
1240
|
+
fieldName: true,
|
|
1241
|
+
applied: true
|
|
1242
|
+
}
|
|
1243
|
+
} } },
|
|
1244
|
+
addCrossNamespaceEdge: { mutate: { [`${ownedNamespaces[0] ?? "<ns>"}/propose_field`]: {
|
|
1245
|
+
params: {
|
|
1246
|
+
targetType: "Dress",
|
|
1247
|
+
fieldName: "owner",
|
|
1248
|
+
fieldSpec: {
|
|
1249
|
+
kind: "crossRef",
|
|
1250
|
+
ns: "household",
|
|
1251
|
+
type: "Person",
|
|
1252
|
+
onDelete: "set_null"
|
|
1253
|
+
},
|
|
1254
|
+
proposedReason: "Link each Dress to its household owner."
|
|
1255
|
+
},
|
|
1256
|
+
fields: {
|
|
1257
|
+
id: true,
|
|
1258
|
+
applied: true
|
|
1259
|
+
}
|
|
1260
|
+
} } }
|
|
1261
|
+
}
|
|
1262
|
+
};
|
|
1263
|
+
}
|
|
1264
|
+
function registerOnboardRoute(router, _ctx, ownedNamespaces) {
|
|
1265
|
+
const body = buildOnboardBody(ownedNamespaces);
|
|
1266
|
+
const encoded = JSON.stringify(body);
|
|
1267
|
+
router.get("/onboard", () => ({
|
|
1268
|
+
status: 200,
|
|
1269
|
+
headers: JSON_HEADERS,
|
|
1270
|
+
body: encoded
|
|
1271
|
+
}));
|
|
1272
|
+
}
|
|
1273
|
+
|
|
1274
|
+
//#endregion
|
|
1275
|
+
//#region ../../plugins/substrate-proposals/src/propose-field-resolver.ts
|
|
1276
|
+
/**
|
|
1277
|
+
* Factory for the propose_field mutation resolver.
|
|
1278
|
+
*
|
|
1279
|
+
* Validates ownership, looks up the target type in the live Registry, handles
|
|
1280
|
+
* idempotent re-proposals and destructive-change guards, stores the
|
|
1281
|
+
* FieldProposal row, applies the field to the live Registry, marks the row
|
|
1282
|
+
* applied, and emits a PubSub notification.
|
|
1283
|
+
*
|
|
1284
|
+
* Writes route through the autoCRUD `createFieldProposal` resolver on the
|
|
1285
|
+
* caller's own transaction when the engine handle is wired (production). Raw
|
|
1286
|
+
* `dataset.write` is the fallback for resolver-direct tests that don't boot an
|
|
1287
|
+
* engine (as in propose-type-resolver). The registry apply is taken back if
|
|
1288
|
+
* the caller's transaction rolls back.
|
|
1289
|
+
*/
|
|
1290
|
+
/** Canonical JSON string for a FieldSpecJson — parse then stringify to normalise defaults. */
|
|
1291
|
+
function canonicalize(spec) {
|
|
1292
|
+
return JSON.stringify(stringifyFieldDef(parseFieldSpec(spec)));
|
|
1293
|
+
}
|
|
1294
|
+
function makeProposeFieldResolver(deps) {
|
|
1295
|
+
return async (ctx, args) => {
|
|
1296
|
+
if (!deps.ownedNamespaces.has(deps.namespace) && !deps.registryStore.has(deps.namespace)) throw new ProposalError("unowned_namespace", `Namespace '${deps.namespace}' is not owned by this plugin instance`);
|
|
1297
|
+
const input = args.params ?? {};
|
|
1298
|
+
assertValidFieldProposal(input.targetType, input.fieldName, input.fieldSpec, (ns, type) => deps.registryStore.ownsType(ns, type));
|
|
1299
|
+
if (input.proposedReason !== void 0 && typeof input.proposedReason !== "string") throw new ProposalError("invalid_params", "'proposedReason' must be a string", { param: "proposedReason" });
|
|
1300
|
+
const dataset = args.dataset ?? deps.dataset;
|
|
1301
|
+
return withProposalLock(dataset, proposalLockKey("field", deps.namespace, `${input.targetType}.${input.fieldName}`), () => proposeFieldLocked(deps, ctx, {
|
|
1302
|
+
...args,
|
|
1303
|
+
dataset
|
|
1304
|
+
}, input));
|
|
1305
|
+
};
|
|
1306
|
+
}
|
|
1307
|
+
/** Steps 2-8, run while holding the proposal lock for this field. */
|
|
1308
|
+
async function proposeFieldLocked(deps, ctx, args, input) {
|
|
1309
|
+
const { targetType, fieldName, fieldSpec } = input;
|
|
1310
|
+
const proposedReason = input.proposedReason ?? "";
|
|
1311
|
+
const proposedBy = resolveIdentity(ctx).id;
|
|
1312
|
+
const suppliedMap = input.valueMap ?? null;
|
|
1313
|
+
const binding = deps.registryStore.getBinding(deps.namespace);
|
|
1314
|
+
const entry = binding.registry.get(targetType);
|
|
1315
|
+
if (!entry) throw new ProposalError("unknown_type", `Target type '${targetType}' is not registered in namespace '${deps.namespace}'`, { targetType });
|
|
1316
|
+
const existingFieldDef = entry.fields[fieldName];
|
|
1317
|
+
let migration = null;
|
|
1318
|
+
if (existingFieldDef !== void 0) {
|
|
1319
|
+
const incomingCanonical = canonicalize(fieldSpec);
|
|
1320
|
+
if (incomingCanonical === JSON.stringify(stringifyFieldDef(existingFieldDef))) {
|
|
1321
|
+
const priorResult = await args.dataset.read("FieldProposal", {
|
|
1322
|
+
where: { AND: [
|
|
1323
|
+
{ targetType: { eq: targetType } },
|
|
1324
|
+
{ fieldName: { eq: fieldName } },
|
|
1325
|
+
{ archived: { eq: false } }
|
|
1326
|
+
] },
|
|
1327
|
+
limit: 1
|
|
1328
|
+
});
|
|
1329
|
+
if (priorResult.rows.length > 0) return priorResult.rows[0];
|
|
1330
|
+
return {
|
|
1331
|
+
id: `code-declared:${targetType}.${fieldName}`,
|
|
1332
|
+
targetType,
|
|
1333
|
+
fieldName,
|
|
1334
|
+
fieldSpecJson: incomingCanonical,
|
|
1335
|
+
applied: true,
|
|
1336
|
+
proposedBy: "code",
|
|
1337
|
+
proposedReason: "code-declared"
|
|
1338
|
+
};
|
|
1339
|
+
}
|
|
1340
|
+
if (suppliedMap === null) throw new ProposalError("destructive_change_required", `Field '${fieldName}' on '${targetType}' already exists with a different spec. Pass a valueMap (stranded source value → target value, null to knowingly strand) to migrate stored rows first, then narrow.`, {
|
|
1341
|
+
existing: JSON.stringify(stringifyFieldDef(existingFieldDef)),
|
|
1342
|
+
proposed: canonicalize(fieldSpec)
|
|
1343
|
+
});
|
|
1344
|
+
const newEnum = fieldSpec.kind === "scalar" ? fieldSpec.enum ?? null : null;
|
|
1345
|
+
if (newEnum === null) throw new ProposalError("destructive_change_required", `Field '${fieldName}' on '${targetType}' already exists with a different spec, and the supplied valueMap only applies to enum narrowing — the proposed spec declares no vocabulary.`, {
|
|
1346
|
+
existing: JSON.stringify(stringifyFieldDef(existingFieldDef)),
|
|
1347
|
+
proposed: canonicalize(fieldSpec)
|
|
1348
|
+
});
|
|
1349
|
+
const oldEnum = existingFieldDef.kind === "scalar" ? existingFieldDef.enum ?? null : null;
|
|
1350
|
+
migration = await migrateFieldValues({
|
|
1351
|
+
dataset: args.dataset,
|
|
1352
|
+
namespace: deps.namespace,
|
|
1353
|
+
type: targetType,
|
|
1354
|
+
field: fieldName,
|
|
1355
|
+
vocabulary: newEnum
|
|
1356
|
+
}, suppliedMap, { oldVocabulary: oldEnum });
|
|
1357
|
+
}
|
|
1358
|
+
const proposedAt = /* @__PURE__ */ new Date();
|
|
1359
|
+
const newId = randomUUID();
|
|
1360
|
+
const initialParams = {
|
|
1361
|
+
id: newId,
|
|
1362
|
+
targetType,
|
|
1363
|
+
fieldName,
|
|
1364
|
+
fieldSpecJson: JSON.stringify(fieldSpec),
|
|
1365
|
+
proposedBy,
|
|
1366
|
+
proposedAt,
|
|
1367
|
+
proposedReason,
|
|
1368
|
+
valueMapJson: suppliedMap === null ? null : JSON.stringify(suppliedMap),
|
|
1369
|
+
applied: false,
|
|
1370
|
+
appliedAt: null,
|
|
1371
|
+
resultingSchemaVersion: null,
|
|
1372
|
+
supersededByCode: false,
|
|
1373
|
+
archived: false
|
|
1374
|
+
};
|
|
1375
|
+
const engine = binding.engine;
|
|
1376
|
+
if (engine !== void 0) await writeInTx(binding.registry, ctx, args, "createFieldProposal", initialParams);
|
|
1377
|
+
else await args.dataset.write("FieldProposal", [initialParams]);
|
|
1378
|
+
try {
|
|
1379
|
+
applyUntilRollback(args, binding.registry, () => applyFieldProposal({
|
|
1380
|
+
namespace: deps.namespace,
|
|
1381
|
+
targetType,
|
|
1382
|
+
fieldName,
|
|
1383
|
+
fieldSpec,
|
|
1384
|
+
registryStore: deps.registryStore,
|
|
1385
|
+
dataset: deps.dataset,
|
|
1386
|
+
edges: deps.edges
|
|
1387
|
+
}), () => binding.invalidateSchemaCaches?.());
|
|
1388
|
+
} catch (cause) {
|
|
1389
|
+
throw new ProposalError("field_already_exists", `Could not apply field '${fieldName}' to '${targetType}': ${cause instanceof Error ? cause.message : String(cause)}`, {}, { cause });
|
|
1390
|
+
}
|
|
1391
|
+
const now = /* @__PURE__ */ new Date();
|
|
1392
|
+
const resultingSchemaVersion = publishSchema(binding.registry).schemaVersion;
|
|
1393
|
+
if (engine !== void 0) await writeInTx(binding.registry, ctx, args, "updateFieldProposal", {
|
|
1394
|
+
id: newId,
|
|
1395
|
+
applied: true,
|
|
1396
|
+
appliedAt: now,
|
|
1397
|
+
resultingSchemaVersion
|
|
1398
|
+
});
|
|
1399
|
+
const rawRow = (await args.dataset.read("FieldProposal", { id: newId })).rows[0];
|
|
1400
|
+
if (!rawRow) throw new Error(`FieldProposal row ${newId} not found after write`);
|
|
1401
|
+
let appliedRow;
|
|
1402
|
+
if (engine !== void 0) appliedRow = rawRow;
|
|
1403
|
+
else {
|
|
1404
|
+
appliedRow = {
|
|
1405
|
+
...rawRow,
|
|
1406
|
+
applied: true,
|
|
1407
|
+
appliedAt: now,
|
|
1408
|
+
resultingSchemaVersion
|
|
1409
|
+
};
|
|
1410
|
+
await args.dataset.write("FieldProposal", [appliedRow]);
|
|
1411
|
+
}
|
|
1412
|
+
await notifyAfterCommit(args, () => deps.pubsub.notify(deps.channelFor(deps.namespace), String(newId)));
|
|
1413
|
+
if (migration === null) return appliedRow;
|
|
1414
|
+
const { ids: _written, ...summary } = migration;
|
|
1415
|
+
return {
|
|
1416
|
+
...appliedRow,
|
|
1417
|
+
migration: summary
|
|
1418
|
+
};
|
|
1419
|
+
}
|
|
1420
|
+
|
|
1421
|
+
//#endregion
|
|
1422
|
+
//#region ../../plugins/substrate-proposals/src/propose-type-resolver.ts
|
|
1423
|
+
/**
|
|
1424
|
+
* Factory for the propose_type mutation resolver.
|
|
1425
|
+
*
|
|
1426
|
+
* Validates ownership, deduplicates pending proposals, stores the TypeProposal
|
|
1427
|
+
* row, applies the type to the live Registry via applyTypeProposal, marks the
|
|
1428
|
+
* row applied, and emits a PubSub notification.
|
|
1429
|
+
*
|
|
1430
|
+
* Writes route through the autoCRUD `createTypeProposal` resolver on the
|
|
1431
|
+
* caller's own transaction when the engine handle is wired (production:
|
|
1432
|
+
* onStart wires it), which populates `_metadata`, allocates `shortId`, and
|
|
1433
|
+
* fires the `postWrite` hook. When the engine is unwired (resolver-direct test
|
|
1434
|
+
* harnesses that don't boot an engine), the resolver falls back to raw
|
|
1435
|
+
* `dataset.write` — the writes happen but autoCRUD's surrounding effects do
|
|
1436
|
+
* not.
|
|
1437
|
+
*
|
|
1438
|
+
* The registry apply is taken back if the caller's transaction rolls back
|
|
1439
|
+
* (`applyUntilRollback`), so the type never outlives its row.
|
|
1440
|
+
*/
|
|
1441
|
+
function parseInput(params) {
|
|
1442
|
+
const { proposedReason } = params;
|
|
1443
|
+
if (proposedReason !== void 0 && typeof proposedReason !== "string") throw new ProposalError("invalid_params", "'proposedReason' must be a string", { param: "proposedReason" });
|
|
1444
|
+
return {
|
|
1445
|
+
...params,
|
|
1446
|
+
proposedReason: proposedReason ?? ""
|
|
1447
|
+
};
|
|
1448
|
+
}
|
|
1449
|
+
function makeProposeTypeResolver(deps) {
|
|
1450
|
+
return async (ctx, args) => {
|
|
1451
|
+
if (!deps.ownedNamespaces.has(deps.namespace) && !deps.registryStore.has(deps.namespace)) throw new ProposalError("unowned_namespace", `Namespace '${deps.namespace}' is not owned by this plugin instance`);
|
|
1452
|
+
const input = parseInput(args.params ?? {});
|
|
1453
|
+
assertValidTypeProposal(input.typeName, input.fields, (ns, type) => ns === deps.namespace && type === input.typeName || deps.registryStore.ownsType(ns, type));
|
|
1454
|
+
const dataset = args.dataset ?? deps.dataset;
|
|
1455
|
+
return withProposalLock(dataset, proposalLockKey("type", deps.namespace, input.typeName), () => proposeTypeLocked(deps, ctx, {
|
|
1456
|
+
...args,
|
|
1457
|
+
dataset
|
|
1458
|
+
}, input));
|
|
1459
|
+
};
|
|
1460
|
+
}
|
|
1461
|
+
/** Steps 2-7, run while holding the proposal lock for this type name. */
|
|
1462
|
+
async function proposeTypeLocked(deps, ctx, args, input) {
|
|
1463
|
+
const { typeName, fields, proposedReason } = input;
|
|
1464
|
+
const proposedBy = resolveIdentity(ctx).id;
|
|
1465
|
+
const existing = await args.dataset.read("TypeProposal", {
|
|
1466
|
+
where: { AND: [{ typeName: { eq: typeName } }, { archived: { eq: false } }] },
|
|
1467
|
+
limit: 1
|
|
1468
|
+
});
|
|
1469
|
+
if (existing.rows.length > 0) {
|
|
1470
|
+
const prior = existing.rows[0];
|
|
1471
|
+
throw new ProposalError("type_already_proposed", `TypeProposal for '${typeName}' already exists (proposed by ${String(prior.proposedBy)})`, {
|
|
1472
|
+
by: prior.proposedBy,
|
|
1473
|
+
at: prior.proposedAt
|
|
1474
|
+
});
|
|
1475
|
+
}
|
|
1476
|
+
const liveRegistry = deps.registryStore.getBinding(deps.namespace).registry;
|
|
1477
|
+
if (liveRegistry.has(typeName)) throw new ProposalError("type_already_exists", `Type '${typeName}' is already registered in namespace '${deps.namespace}'`);
|
|
1478
|
+
const takenKey = typeProposalRegistryKeys({
|
|
1479
|
+
typeName,
|
|
1480
|
+
fields,
|
|
1481
|
+
dataset: deps.dataset,
|
|
1482
|
+
edges: deps.edges
|
|
1483
|
+
}).find((key) => liveRegistry.has(key));
|
|
1484
|
+
if (takenKey !== void 0) throw new ProposalError("type_already_exists", `Type '${typeName}' would register operation '${takenKey}', which is already registered in namespace '${deps.namespace}'`);
|
|
1485
|
+
const proposedAt = /* @__PURE__ */ new Date();
|
|
1486
|
+
const fieldsJson = JSON.stringify(fields);
|
|
1487
|
+
const newId = randomUUID();
|
|
1488
|
+
const initialParams = {
|
|
1489
|
+
id: newId,
|
|
1490
|
+
typeName,
|
|
1491
|
+
fieldsJson,
|
|
1492
|
+
proposedBy,
|
|
1493
|
+
proposedAt,
|
|
1494
|
+
proposedReason,
|
|
1495
|
+
applied: false,
|
|
1496
|
+
appliedAt: null,
|
|
1497
|
+
resultingSchemaVersion: null,
|
|
1498
|
+
supersededByCode: false,
|
|
1499
|
+
archived: false
|
|
1500
|
+
};
|
|
1501
|
+
const binding = deps.registryStore.getBinding(deps.namespace);
|
|
1502
|
+
const engine = binding.engine;
|
|
1503
|
+
if (engine !== void 0) await writeInTx(binding.registry, ctx, args, "createTypeProposal", initialParams);
|
|
1504
|
+
else if (!(await args.dataset.write("TypeProposal", [initialParams])).ids[0]) throw new Error("dataset.write did not return an id for TypeProposal");
|
|
1505
|
+
try {
|
|
1506
|
+
applyUntilRollback(args, binding.registry, () => applyTypeProposal({
|
|
1507
|
+
namespace: deps.namespace,
|
|
1508
|
+
typeName,
|
|
1509
|
+
fields,
|
|
1510
|
+
registryStore: deps.registryStore,
|
|
1511
|
+
dataset: deps.dataset,
|
|
1512
|
+
edges: deps.edges
|
|
1513
|
+
}), () => binding.invalidateSchemaCaches?.());
|
|
1514
|
+
} catch (cause) {
|
|
1515
|
+
throw new ProposalError("type_already_exists", `Could not apply type '${typeName}': ${cause instanceof Error ? cause.message : String(cause)}`, {}, { cause });
|
|
1516
|
+
}
|
|
1517
|
+
const now = /* @__PURE__ */ new Date();
|
|
1518
|
+
const resultingSchemaVersion = publishSchema(binding.registry).schemaVersion;
|
|
1519
|
+
let appliedRow;
|
|
1520
|
+
if (engine !== void 0) {
|
|
1521
|
+
appliedRow = await writeInTx(binding.registry, ctx, args, "updateTypeProposal", {
|
|
1522
|
+
id: newId,
|
|
1523
|
+
applied: true,
|
|
1524
|
+
appliedAt: now,
|
|
1525
|
+
resultingSchemaVersion
|
|
1526
|
+
});
|
|
1527
|
+
const rawRow = (await args.dataset.read("TypeProposal", { id: newId })).rows[0];
|
|
1528
|
+
if (!rawRow) throw new Error(`TypeProposal row ${newId} not found after engine update`);
|
|
1529
|
+
appliedRow = rawRow;
|
|
1530
|
+
} else {
|
|
1531
|
+
const rawRow = (await args.dataset.read("TypeProposal", { id: newId })).rows[0];
|
|
1532
|
+
if (!rawRow) throw new Error(`TypeProposal row ${newId} not found after write`);
|
|
1533
|
+
appliedRow = {
|
|
1534
|
+
...rawRow,
|
|
1535
|
+
applied: true,
|
|
1536
|
+
appliedAt: now,
|
|
1537
|
+
resultingSchemaVersion
|
|
1538
|
+
};
|
|
1539
|
+
await args.dataset.write("TypeProposal", [appliedRow]);
|
|
1540
|
+
}
|
|
1541
|
+
await notifyAfterCommit(args, () => deps.pubsub.notify(deps.channelFor(deps.namespace), String(newId)));
|
|
1542
|
+
return appliedRow;
|
|
1543
|
+
}
|
|
1544
|
+
|
|
1545
|
+
//#endregion
|
|
1546
|
+
//#region ../../plugins/substrate-proposals/src/registry-store.ts
|
|
1547
|
+
/**
|
|
1548
|
+
* Holds a namespace → NamespaceBinding map, bridging compose-time type
|
|
1549
|
+
* registration (install()) and runtime apply-proposal + multi-instance
|
|
1550
|
+
* reconcile code paths.
|
|
1551
|
+
*
|
|
1552
|
+
* The plugin stashes each namespace's binding (registry + dataset + edges) at
|
|
1553
|
+
* install so mutation resolvers, onStart and reconcile can reach it later.
|
|
1554
|
+
*/
|
|
1555
|
+
var RegistryStore = class {
|
|
1556
|
+
bindings = /* @__PURE__ */ new Map();
|
|
1557
|
+
/**
|
|
1558
|
+
* Register a full NamespaceBinding for the given namespace.
|
|
1559
|
+
*
|
|
1560
|
+
* @throws Error if the namespace already has a binding (duplicate is a bug)
|
|
1561
|
+
*/
|
|
1562
|
+
set(namespace, binding) {
|
|
1563
|
+
if (this.bindings.has(namespace)) throw new Error(`RegistryStore: duplicate binding for namespace '${namespace}'`);
|
|
1564
|
+
this.bindings.set(namespace, binding);
|
|
1565
|
+
}
|
|
1566
|
+
/**
|
|
1567
|
+
* Retrieve the full NamespaceBinding for the given namespace.
|
|
1568
|
+
*
|
|
1569
|
+
* @throws Error if the namespace has no binding (lookup is a contract violation)
|
|
1570
|
+
*/
|
|
1571
|
+
getBinding(namespace) {
|
|
1572
|
+
const b = this.bindings.get(namespace);
|
|
1573
|
+
if (!b) throw new Error(`RegistryStore: no binding for namespace '${namespace}'`);
|
|
1574
|
+
return b;
|
|
1575
|
+
}
|
|
1576
|
+
/**
|
|
1577
|
+
* Back-compat: returns just the registry handle.
|
|
1578
|
+
*/
|
|
1579
|
+
get(namespace) {
|
|
1580
|
+
return this.getBinding(namespace).registry;
|
|
1581
|
+
}
|
|
1582
|
+
/** Forget a namespace's binding (its runtime install was taken back). */
|
|
1583
|
+
delete(namespace) {
|
|
1584
|
+
this.bindings.delete(namespace);
|
|
1585
|
+
}
|
|
1586
|
+
/**
|
|
1587
|
+
* Safe presence check for a namespace in the store.
|
|
1588
|
+
*/
|
|
1589
|
+
has(namespace) {
|
|
1590
|
+
return this.bindings.has(namespace);
|
|
1591
|
+
}
|
|
1592
|
+
/**
|
|
1593
|
+
* True when `type` is a type registered in a namespace this plugin owns, so
|
|
1594
|
+
* a proposed crossRef cannot point into a namespace it does not manage or at
|
|
1595
|
+
* a type that does not exist. The control plane is the plugin's own, not a
|
|
1596
|
+
* user namespace.
|
|
1597
|
+
*/
|
|
1598
|
+
ownsType(namespace, type) {
|
|
1599
|
+
return this.ownsNamespace(namespace) && this.getBinding(namespace).registry.get(type)?.kind === "type";
|
|
1600
|
+
}
|
|
1601
|
+
/** True when `namespace` is a user namespace this plugin owns or hot-added. */
|
|
1602
|
+
ownsNamespace(namespace) {
|
|
1603
|
+
return namespace !== "_system_proposals" && this.bindings.has(namespace);
|
|
1604
|
+
}
|
|
1605
|
+
/**
|
|
1606
|
+
* Wire the post-replace schema-cache invalidator for a namespace. Called
|
|
1607
|
+
* from the plugin's `onStart` once the engine handle is available. No-op if the namespace has no binding — the binding is
|
|
1608
|
+
* registered at install time and onStart runs strictly after install.
|
|
1609
|
+
*/
|
|
1610
|
+
setInvalidator(namespace, fn) {
|
|
1611
|
+
const b = this.bindings.get(namespace);
|
|
1612
|
+
if (b !== void 0) b.invalidateSchemaCaches = fn;
|
|
1613
|
+
}
|
|
1614
|
+
/**
|
|
1615
|
+
* Wire the engine handle so propose_type / propose_field resolvers can route
|
|
1616
|
+
* TypeProposal / FieldProposal writes through autoCRUD. Called from
|
|
1617
|
+
* the plugin's `onStart` alongside `setInvalidator`. Same lifecycle: no-op
|
|
1618
|
+
* for unregistered namespaces; binding always pre-exists after install.
|
|
1619
|
+
*/
|
|
1620
|
+
setEngine(namespace, engine) {
|
|
1621
|
+
const b = this.bindings.get(namespace);
|
|
1622
|
+
if (b !== void 0) b.engine = engine;
|
|
1623
|
+
}
|
|
1624
|
+
};
|
|
1625
|
+
|
|
1626
|
+
//#endregion
|
|
1627
|
+
//#region ../../plugins/substrate-proposals/src/config.ts
|
|
1628
|
+
/**
|
|
1629
|
+
* Convenience stub for tests and single-instance deployments where multi-
|
|
1630
|
+
* instance invalidation is not needed.
|
|
1631
|
+
*/
|
|
1632
|
+
function createNoopPubSub() {
|
|
1633
|
+
return {
|
|
1634
|
+
async listen() {},
|
|
1635
|
+
async notify() {}
|
|
1636
|
+
};
|
|
1637
|
+
}
|
|
1638
|
+
|
|
1639
|
+
//#endregion
|
|
1640
|
+
//#region ../../plugins/substrate-proposals/src/index.ts
|
|
1641
|
+
function createProposalsPlugin(config) {
|
|
1642
|
+
if (config.ownedNamespaces.includes("_system_proposals")) throw new Error(`'${CONTROL_NAMESPACE}' is the reserved control-plane namespace and cannot appear in ownedNamespaces — remove it from your ownedNamespaces config`);
|
|
1643
|
+
const ownedNamespaces = new Set(config.ownedNamespaces);
|
|
1644
|
+
const registryStore = new RegistryStore();
|
|
1645
|
+
const capability = config.proposeCapability ?? "substrate.propose";
|
|
1646
|
+
const policy = makeProposePolicy(capability);
|
|
1647
|
+
let lookupDataset = config.datasetFor ?? (() => void 0);
|
|
1648
|
+
/**
|
|
1649
|
+
* Shared resolver-registration helper. Used at static-ns install time AND
|
|
1650
|
+
* at hot-add time (from propose_namespace + cluster listener + cold-boot
|
|
1651
|
+
* reconcile via the `registerProposalMutations` seam in multi-instance.ts).
|
|
1652
|
+
* Single-source because divergence makes propose_type silently unreachable
|
|
1653
|
+
* on hot-added namespaces.
|
|
1654
|
+
*/
|
|
1655
|
+
const registerProposalMutations = (registerArgs) => {
|
|
1656
|
+
const deps = {
|
|
1657
|
+
namespace: registerArgs.namespace,
|
|
1658
|
+
ownedNamespaces,
|
|
1659
|
+
registryStore,
|
|
1660
|
+
dataset: registerArgs.dataset,
|
|
1661
|
+
edges: registerArgs.edges,
|
|
1662
|
+
pubsub: config.pubsub,
|
|
1663
|
+
channelFor: (n) => `_substrate_proposals_${n}`
|
|
1664
|
+
};
|
|
1665
|
+
registerArgs.registry.register("propose_type", {
|
|
1666
|
+
kind: "mutation",
|
|
1667
|
+
resolver: makeProposeTypeResolver(deps),
|
|
1668
|
+
policy
|
|
1669
|
+
});
|
|
1670
|
+
registerArgs.registry.register("propose_field", {
|
|
1671
|
+
kind: "mutation",
|
|
1672
|
+
resolver: makeProposeFieldResolver(deps),
|
|
1673
|
+
policy
|
|
1674
|
+
});
|
|
1675
|
+
};
|
|
1676
|
+
return {
|
|
1677
|
+
name: "substrate-proposals",
|
|
1678
|
+
contractVersion: ">=1.0.0-alpha.0 <2.0.0",
|
|
1679
|
+
namespaces: [{
|
|
1680
|
+
namespace: CONTROL_NAMESPACE,
|
|
1681
|
+
install(ctx) {
|
|
1682
|
+
registryStore.set(CONTROL_NAMESPACE, {
|
|
1683
|
+
registry: ctx.registry,
|
|
1684
|
+
dataset: ctx.dataset,
|
|
1685
|
+
edges: ctx.edges
|
|
1686
|
+
});
|
|
1687
|
+
defineControlPlaneTypes(capability).install(ctx);
|
|
1688
|
+
ctx.registry.register("propose_namespace", {
|
|
1689
|
+
kind: "mutation",
|
|
1690
|
+
resolver: makeProposeNamespaceResolver({
|
|
1691
|
+
controlNamespace: CONTROL_NAMESPACE,
|
|
1692
|
+
registryStore,
|
|
1693
|
+
datasetFor: (ns) => lookupDataset(ns),
|
|
1694
|
+
edges: ctx.edges,
|
|
1695
|
+
pubsub: config.pubsub,
|
|
1696
|
+
proposeCapability: capability,
|
|
1697
|
+
registerProposalMutations
|
|
1698
|
+
}),
|
|
1699
|
+
policy
|
|
1700
|
+
});
|
|
1701
|
+
}
|
|
1702
|
+
}, ...config.ownedNamespaces.map((ns) => ({
|
|
1703
|
+
namespace: ns,
|
|
1704
|
+
install(ctx) {
|
|
1705
|
+
registryStore.set(ns, {
|
|
1706
|
+
registry: ctx.registry,
|
|
1707
|
+
dataset: ctx.dataset,
|
|
1708
|
+
edges: ctx.edges
|
|
1709
|
+
});
|
|
1710
|
+
defineProposalTypes(ns, capability).install(ctx);
|
|
1711
|
+
registerProposalMutations({
|
|
1712
|
+
namespace: ns,
|
|
1713
|
+
dataset: ctx.dataset,
|
|
1714
|
+
edges: ctx.edges,
|
|
1715
|
+
registry: ctx.registry
|
|
1716
|
+
});
|
|
1717
|
+
}
|
|
1718
|
+
}))],
|
|
1719
|
+
onboardInstructions: buildOnboardBody(config.ownedNamespaces),
|
|
1720
|
+
routes: (router, ctx) => {
|
|
1721
|
+
registerOnboardRoute(router, ctx, config.ownedNamespaces);
|
|
1722
|
+
},
|
|
1723
|
+
async onStart(ctx) {
|
|
1724
|
+
registryStore.setInvalidator(CONTROL_NAMESPACE, () => ctx.engine.invalidateSchemaCaches(CONTROL_NAMESPACE));
|
|
1725
|
+
registryStore.setEngine(CONTROL_NAMESPACE, ctx.engine);
|
|
1726
|
+
if (config.datasetFor === void 0) lookupDataset = (ns) => ctx.engine.datasetFor(ns);
|
|
1727
|
+
const controlBinding = registryStore.getBinding(CONTROL_NAMESPACE);
|
|
1728
|
+
const hotAddedNamespaces = await reconcileClusterNamespaces({
|
|
1729
|
+
controlNamespace: CONTROL_NAMESPACE,
|
|
1730
|
+
registryStore,
|
|
1731
|
+
engine: ctx.engine,
|
|
1732
|
+
datasetFor: lookupDataset,
|
|
1733
|
+
edges: controlBinding.edges,
|
|
1734
|
+
proposeCapability: capability,
|
|
1735
|
+
registerProposalMutations,
|
|
1736
|
+
onSkip: (row, err) => ctx.metric("_system_proposals.replay_skipped", {
|
|
1737
|
+
namespace: CONTROL_NAMESPACE,
|
|
1738
|
+
id: row.id,
|
|
1739
|
+
error: err instanceof Error ? err.message : String(err)
|
|
1740
|
+
})
|
|
1741
|
+
});
|
|
1742
|
+
const allNs = [...config.ownedNamespaces, ...hotAddedNamespaces];
|
|
1743
|
+
for (const ns of allNs) {
|
|
1744
|
+
registryStore.setInvalidator(ns, () => ctx.engine.invalidateSchemaCaches(ns));
|
|
1745
|
+
registryStore.setEngine(ns, ctx.engine);
|
|
1746
|
+
await reconcileNamespace({
|
|
1747
|
+
namespace: ns,
|
|
1748
|
+
registryStore,
|
|
1749
|
+
onSkip: (row, err) => ctx.metric("_system_proposals.replay_skipped", {
|
|
1750
|
+
namespace: ns,
|
|
1751
|
+
id: row.id,
|
|
1752
|
+
error: err instanceof Error ? err.message : String(err)
|
|
1753
|
+
})
|
|
1754
|
+
});
|
|
1755
|
+
await setupNamespaceListener({
|
|
1756
|
+
namespace: ns,
|
|
1757
|
+
channel: `_substrate_proposals_${ns}`,
|
|
1758
|
+
pubsub: config.pubsub,
|
|
1759
|
+
registryStore
|
|
1760
|
+
});
|
|
1761
|
+
ctx.metric("_system_proposals.namespace_ready", { namespace: ns });
|
|
1762
|
+
}
|
|
1763
|
+
ctx.engine.addDropParticipant(namespaceDropParticipant(CONTROL_NAMESPACE));
|
|
1764
|
+
ctx.engine.onNamespaceTombstoned((ns) => {
|
|
1765
|
+
retireDroppedNamespace({
|
|
1766
|
+
ns,
|
|
1767
|
+
registryStore,
|
|
1768
|
+
engine: ctx.engine,
|
|
1769
|
+
pubsub: config.pubsub
|
|
1770
|
+
}).catch((err) => ctx.metric("_system_proposals.retire_failed", {
|
|
1771
|
+
ns,
|
|
1772
|
+
error: err instanceof Error ? err.message : String(err)
|
|
1773
|
+
}));
|
|
1774
|
+
});
|
|
1775
|
+
await setupClusterDropListener({
|
|
1776
|
+
controlNamespace: CONTROL_NAMESPACE,
|
|
1777
|
+
registryStore,
|
|
1778
|
+
engine: ctx.engine,
|
|
1779
|
+
pubsub: config.pubsub,
|
|
1780
|
+
metric: ctx.metric
|
|
1781
|
+
});
|
|
1782
|
+
await setupClusterNamespaceListener({
|
|
1783
|
+
pubsub: config.pubsub,
|
|
1784
|
+
registryStore,
|
|
1785
|
+
engine: ctx.engine,
|
|
1786
|
+
datasetFor: lookupDataset,
|
|
1787
|
+
edges: controlBinding.edges,
|
|
1788
|
+
metric: ctx.metric,
|
|
1789
|
+
proposeCapability: capability,
|
|
1790
|
+
registerProposalMutations
|
|
1791
|
+
});
|
|
1792
|
+
}
|
|
1793
|
+
};
|
|
1794
|
+
}
|
|
1795
|
+
|
|
1796
|
+
//#endregion
|
|
1797
|
+
export { createNoopPubSub as n, ProposalError as r, createProposalsPlugin as t };
|