@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.
Files changed (46) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +119 -2
  3. package/dist/agent-token-BIboWOU0.js +200 -0
  4. package/dist/client.d.ts +782 -0
  5. package/dist/client.js +7 -0
  6. package/dist/cluster-worker.js +35 -0
  7. package/dist/content-type-C7T28xNb.js +25 -0
  8. package/dist/dataset-BXkus75W.js +1527 -0
  9. package/dist/env-utils-B7SGmoeJ.js +21 -0
  10. package/dist/errors-D4vKuwz8.d.ts +130 -0
  11. package/dist/fake-DUVtKVSE.js +36 -0
  12. package/dist/index-D7mSOFlM.d.ts +69 -0
  13. package/dist/pack.d.ts +192 -0
  14. package/dist/pack.js +5 -0
  15. package/dist/plugin-j1jt1l3n.js +3844 -0
  16. package/dist/plugin-t2g2wX0b.d.ts +1568 -0
  17. package/dist/proposals-bootstrap.js +37 -0
  18. package/dist/proposals.config.schema.json +20 -0
  19. package/dist/proposals.d.ts +118 -0
  20. package/dist/proposals.default-config.json +4 -0
  21. package/dist/proposals.js +4 -0
  22. package/dist/recall-bootstrap.js +451 -0
  23. package/dist/recall.config.schema.json +232 -0
  24. package/dist/recall.d.ts +1981 -0
  25. package/dist/recall.default-config.json +4 -0
  26. package/dist/recall.js +5 -0
  27. package/dist/repl-C52wyfMs.js +2213 -0
  28. package/dist/row-ByLFE2Wx.d.ts +719 -0
  29. package/dist/row-DK7lPZVe.js +732 -0
  30. package/dist/runtime-metrics-DwpDJ8vz.d.ts +159 -0
  31. package/dist/schema-g4FQLr0V.d.ts +433 -0
  32. package/dist/sdk.d.ts +694 -0
  33. package/dist/sdk.js +112 -0
  34. package/dist/src-C4DzaIQZ.js +837 -0
  35. package/dist/src-CrEgiMJQ.js +1015 -0
  36. package/dist/src-CzxvmhFn.js +2327 -0
  37. package/dist/src-D88LvCX8.js +1797 -0
  38. package/dist/src-D91yij6C.js +13523 -0
  39. package/dist/src-DuopV8u7.js +2408 -0
  40. package/dist/substrate-admin.js +808 -0
  41. package/dist/substrate.js +5477 -0
  42. package/dist/testing.d.ts +1240 -0
  43. package/dist/testing.js +702 -0
  44. package/dist/types-8c0gtnd2.d.ts +35 -0
  45. package/dist/ws-C72iVS5T.d.ts +143 -0
  46. 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 };