@mnmal-ai/substrate 1.0.0-alpha.9 → 1.0.0-beta.2

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 (52) hide show
  1. package/README.md +32 -14
  2. package/dist/boot-store-DpnnxRpR.js +4086 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-DnToJedN.d.ts} +2 -87
  4. package/dist/cli-COS16L1Z.js +3449 -0
  5. package/dist/client.browser.js +2507 -0
  6. package/dist/client.d.ts +222 -171
  7. package/dist/client.js +6 -7
  8. package/dist/cluster-worker.js +0 -1
  9. package/dist/{content-type-C7T28xNb.js → content-type-wLljot5M.js} +0 -1
  10. package/dist/{env-utils-CGNazUNt.js → env-utils-s25Z1YSA.js} +0 -1
  11. package/dist/{errors-D4vKuwz8.d.ts → errors-CuCMwPpb.d.ts} +46 -4
  12. package/dist/{fake-DUVtKVSE.js → fake-DdXtb-m8.js} +0 -1
  13. package/dist/{index-D7mSOFlM.d.ts → index-BI4KqFiR.d.ts} +7 -11
  14. package/dist/msgpackr-Dq18g6Ds.js +16 -0
  15. package/dist/node-version-BtK_Nq6z.js +32 -0
  16. package/dist/pack.d.ts +75 -11
  17. package/dist/pack.js +4 -4
  18. package/dist/{plugin-DpncES1p.js → plugin-DWagHKxm.js} +78 -8
  19. package/dist/proposals-bootstrap.js +6 -5
  20. package/dist/proposals.config.schema.json +5 -0
  21. package/dist/proposals.d.ts +17 -5
  22. package/dist/proposals.default-config.json +2 -1
  23. package/dist/proposals.js +2 -3
  24. package/dist/recall-bootstrap.js +3 -4
  25. package/dist/recall.d.ts +11 -12
  26. package/dist/recall.js +2 -3
  27. package/dist/{repl-DeKzfvNV.js → repl-C8ZgDrQ7.js} +52 -26
  28. package/dist/{row-SRhura12.d.ts → row-D0If4qif.d.ts} +91 -13
  29. package/dist/run-D-4sXpTu.js +2443 -0
  30. package/dist/{plugin-t2g2wX0b.d.ts → schema-aIkY8sR3.d.ts} +1293 -63
  31. package/dist/{script-C6DSa_Na.js → script-ByQ9pzhC.js} +54 -26
  32. package/dist/script-runner.js +78 -0
  33. package/dist/sdk.d.ts +236 -38
  34. package/dist/sdk.js +5 -110
  35. package/dist/semver-D_zdq0hi.js +17 -0
  36. package/dist/{src-BLgbLq2k.js → src-B_kHkbsr.js} +780 -330
  37. package/dist/{src-DjIuRjzF.js → src-C0ylwQFC.js} +10243 -4238
  38. package/dist/{src-C12EA0w9.js → src-D1PgjgUg.js} +179 -96
  39. package/dist/{src-DCy7Iy2l.js → src-Db3XI_pn.js} +900 -77
  40. package/dist/{row-DZ0Fnpc6.js → src-DmiUWOLp.js} +2 -1
  41. package/dist/src-DxD3iktO.js +8307 -0
  42. package/dist/{src-DiNTSaFk.js → src-FXO5JPyk.js} +686 -856
  43. package/dist/substrate-admin.js +17 -782
  44. package/dist/substrate.js +4 -5302
  45. package/dist/testing.d.ts +473 -96
  46. package/dist/testing.js +19 -165
  47. package/dist/{ws-C72iVS5T.d.ts → ws-DW8ng02H.d.ts} +4 -5
  48. package/package.json +26 -26
  49. package/dist/dataset-CqrqTYPz.js +0 -1535
  50. package/dist/pg-edges-store-KH_FQCxx.js +0 -381
  51. package/dist/schema-g4FQLr0V.d.ts +0 -433
  52. package/dist/src-BD27zeGF.js +0 -2339
@@ -1,6 +1,6 @@
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-DjIuRjzF.js";
3
- import { s as requireCapability } from "./row-DZ0Fnpc6.js";
1
+ import { $ as publishSchema, D as RESERVED_AUTOCRUD_FIELDS, Gn as canonicalize$1, I as installAutoCrud, J as resolveIdentity, Lt as JSON_HEADERS, M as field, O as RESERVED_AUTOCRUD_FIELD_NAMES, P as autoCrudOptionsOf, b as assertOrderedBy, d as uuidFromName, f as emitFieldEvents, j as reservedMetadataFieldMessage, l as planServesShape, p as migrateFieldValues, wn as ResolverFrameError, x as defineNamespace, y as assertIndexDecl } from "./src-C0ylwQFC.js";
2
+ import { s as requireCapability } from "./src-DmiUWOLp.js";
3
+ import "./src-B_kHkbsr.js";
4
4
  import { randomUUID } from "node:crypto";
5
5
 
6
6
  //#region ../../plugins/substrate-proposals/src/capability.ts
@@ -8,6 +8,10 @@ import { randomUUID } from "node:crypto";
8
8
  * Substrate.propose capability policy helper.
9
9
  */
10
10
  const DEFAULT_PROPOSE_CAPABILITY = "substrate.propose";
11
+ /** Changes a type's indexes or natural order (`propose_index`); separate from proposing schema. */
12
+ const DEFAULT_INDEX_CAPABILITY = "substrate.index";
13
+ /** What `drop_type` / `drop_namespace` require in the target namespace (the compose default). */
14
+ const DEFAULT_DROP_CAPABILITY = "admin";
11
15
  /**
12
16
  * Create a policy that requires the given capability to be present in the
13
17
  * request identity. Passing an empty string disables the gate entirely
@@ -19,14 +23,137 @@ function makeProposePolicy(capability = DEFAULT_PROPOSE_CAPABILITY) {
19
23
  if (capability === "") return () => ({ allow: true });
20
24
  return requireCapability(capability);
21
25
  }
26
+ /** TypeProposal fields boot replays as indexes and natural order. */
27
+ const INDEX_FIELDS = ["indexesJson", "orderedByJson"];
22
28
  /**
23
29
  * Writes to the proposal record types need the propose capability: boot
24
30
  * replays every row marked applied, so a row written directly would become
25
- * live schema. Reads stay open to anyone the namespace grant admits.
31
+ * live schema. A write that names a type's indexes or natural order (null, which clears
32
+ * them, included) also needs
33
+ * the index capability, which `propose_index` is gated by. Reads stay open to
34
+ * anyone the namespace grant admits.
26
35
  */
27
- function proposeToWrite(capability = DEFAULT_PROPOSE_CAPABILITY) {
36
+ function proposeToWrite(capability = DEFAULT_PROPOSE_CAPABILITY, indexCapability = DEFAULT_INDEX_CAPABILITY) {
28
37
  const gate = makeProposePolicy(capability);
29
- return (ctx, args) => ctx.operation === "mutate" ? gate(ctx, args) : { allow: true };
38
+ const indexGate = makeProposePolicy(indexCapability);
39
+ return (ctx, args) => {
40
+ if (ctx.operation !== "mutate") return { allow: true };
41
+ const decision = gate(ctx, args);
42
+ const params = args.params ?? {};
43
+ if (!decision.allow || !INDEX_FIELDS.some((f) => f in params)) return decision;
44
+ return indexGate(ctx, args);
45
+ };
46
+ }
47
+ /**
48
+ * `propose_index`'s gate: the index capability in the namespace whose indexes
49
+ * the call changes (`params.namespace`), else in the frame's namespace.
50
+ */
51
+ function makeIndexPolicy(capability = DEFAULT_INDEX_CAPABILITY) {
52
+ const gate = makeProposePolicy(capability);
53
+ return (ctx, args) => {
54
+ const target = args.params?.namespace;
55
+ return gate(typeof target === "string" ? {
56
+ ...ctx,
57
+ namespace: target
58
+ } : ctx, args);
59
+ };
60
+ }
61
+ /** Whether `typeName` has rows, archived and tombstoned ones included (purged ones are gone). */
62
+ async function typeHasRows(dataset, typeName) {
63
+ return (await dataset.read(typeName, {
64
+ includeDeleted: true,
65
+ limit: 1
66
+ })).rows.length > 0;
67
+ }
68
+ /**
69
+ * TypeProposal fields boot replay never reads: an update that touches only
70
+ * these leaves the replayed type as it was. Anything else, a field added
71
+ * later included, counts as a removal.
72
+ */
73
+ const BENIGN_PROPOSAL_FIELDS = /* @__PURE__ */ new Set([
74
+ "id",
75
+ "proposedReason",
76
+ "proposedBy",
77
+ "proposedAt",
78
+ "resultingSchemaVersion"
79
+ ]);
80
+ /**
81
+ * Deleting a TypeProposal, or any update that changes what boot replays
82
+ * (archiving, `applied`, renaming `typeName`, `fieldsJson`, ...), drops or
83
+ * redefines its type at the next boot. For a type with storage that needs the
84
+ * drop capability, as `drop_type` does; a proposal for a type with no rows
85
+ * stays the propose capability's alone (#1792, #1954). Storage is checked
86
+ * under the proposal's stored `typeName`, read before the write, so a rename
87
+ * cannot point the check at an empty name, and a removal with no string `id`
88
+ * or no dataset to check is refused. The guarded entries lose `batch`, so a
89
+ * mutate array runs per element through the guard, and `updateMany` /
90
+ * `deleteMany` refuse once their single-row entry is replaced. An empty
91
+ * capability opts out.
92
+ */
93
+ /**
94
+ * Marks a write the plugin makes on its own behalf after it has authorised the
95
+ * whole operation (propose_type's step 5). A symbol, so no wire frame can set it.
96
+ */
97
+ /**
98
+ * Why `typeName` is already defined, or undefined when it is free: it has
99
+ * stored rows, or another live (applied, not archived) proposal defines it.
100
+ * A second live definition would make boot replay choose between them.
101
+ */
102
+ async function defined(dataset, typeName, exceptId) {
103
+ if (await typeHasRows(dataset, typeName)) return "has stored rows";
104
+ return (await dataset.read("TypeProposal", {
105
+ where: { AND: [
106
+ { typeName: { eq: typeName } },
107
+ { applied: { eq: true } },
108
+ { archived: { eq: false } }
109
+ ] },
110
+ limit: 2
111
+ })).rows.some((r) => r.id !== exceptId) ? "already has an applied proposal" : void 0;
112
+ }
113
+ const TRUSTED_WRITE = Symbol("substrate-proposals.trustedWrite");
114
+ function gateTypeProposalRemoval(registry, dropCapability = DEFAULT_DROP_CAPABILITY) {
115
+ if (dropCapability === "") return;
116
+ const gate = makeProposePolicy(dropCapability);
117
+ const removes = {
118
+ deleteTypeProposal: () => true,
119
+ updateTypeProposal: (params) => Object.keys(params).some((k) => !BENIGN_PROPOSAL_FIELDS.has(k)),
120
+ createTypeProposal: (params) => params.applied === true
121
+ };
122
+ for (const [key, isRemoval] of Object.entries(removes)) {
123
+ const entry = registry.get(key);
124
+ if (entry === void 0) continue;
125
+ const { batch: _batch, resolver, ...rest } = entry;
126
+ const deny = (ctx, why) => new ResolverFrameError("policy_denied", `${key}: ${why}`, { required: `${ctx.namespace}:${dropCapability}` });
127
+ registry.replace(key, {
128
+ ...rest,
129
+ resolver: async (ctx, args) => {
130
+ const params = args.params ?? {};
131
+ if (!(args[TRUSTED_WRITE] === true) && isRemoval(params) && !gate(ctx, args).allow) {
132
+ if (key === "createTypeProposal") {
133
+ const name = params.typeName;
134
+ if (args.dataset === void 0) throw deny(ctx, `cannot check '${String(name)}' for stored rows; needs '${dropCapability}'`);
135
+ const why = typeof name === "string" ? await defined(args.dataset, name) : void 0;
136
+ if (why !== void 0) throw deny(ctx, `'${String(name)}' ${why}; an applied proposal for it redefines the type, which needs '${dropCapability}' as drop_type does`);
137
+ return resolver(ctx, args);
138
+ }
139
+ const id = params.id;
140
+ if (typeof id !== "string" || args.dataset === void 0) throw deny(ctx, `cannot check the proposal's type for stored rows without an id and a dataset; needs '${dropCapability}'`);
141
+ const { rows } = await args.dataset.read("TypeProposal", {
142
+ id,
143
+ limit: 1
144
+ });
145
+ const stored = rows[0]?.typeName;
146
+ if (typeof stored === "string" && await typeHasRows(args.dataset, stored)) throw deny(ctx, `'${stored}' has stored rows; this change to its proposal drops or redefines the type, which needs '${dropCapability}' as drop_type does`);
147
+ const name = typeof params.typeName === "string" ? params.typeName : stored;
148
+ if ((params.applied ?? rows[0]?.applied) === true && (params.archived ?? rows[0]?.archived) !== true && typeof name === "string") {
149
+ const why = await defined(args.dataset, name, id);
150
+ if (why !== void 0) throw deny(ctx, `'${name}' ${why}; this change makes a second live definition of it, which needs '${dropCapability}' as drop_type does`);
151
+ }
152
+ }
153
+ return resolver(ctx, args);
154
+ }
155
+ });
156
+ }
30
157
  }
31
158
 
32
159
  //#endregion
@@ -146,6 +273,9 @@ function crossRefsIn(spec) {
146
273
  const SCALAR_TYPES = /* @__PURE__ */ new Set([
147
274
  "string",
148
275
  "number",
276
+ "int16",
277
+ "int32",
278
+ "int64",
149
279
  "boolean",
150
280
  "date",
151
281
  "json"
@@ -156,9 +286,9 @@ function parseFieldSpec(json) {
156
286
  if (!SCALAR_TYPES.has(json.type)) throw new Error(`unsupported scalar type: ${String(json.type)}`);
157
287
  const def = {
158
288
  kind: "scalar",
159
- type: json.type,
160
- indexed: json.indexed ?? true
289
+ type: json.type
161
290
  };
291
+ if (json.indexed !== void 0) def.indexed = json.indexed;
162
292
  if (json.nullable !== void 0) def.nullable = json.nullable;
163
293
  if (json.readonly !== void 0) def.readonly = json.readonly;
164
294
  if (json.enum !== void 0) def.enum = json.enum;
@@ -260,6 +390,18 @@ function stringifyFieldDef(def) {
260
390
  }
261
391
  }
262
392
  /**
393
+ * Refuse a proposed field the engine injects (`shortId`), which apply would overwrite.
394
+ * The resolvers call it, not apply: a stored proposal that names one still replays.
395
+ *
396
+ * @throws ProposalError `invalid_params` naming `fieldName`
397
+ */
398
+ function assertNotEngineInjected(fieldName) {
399
+ if (RESERVED_AUTOCRUD_FIELD_NAMES.includes(fieldName)) throw new ProposalError("invalid_params", `\`${fieldName}\` is a reserved field name, auto-injected by the engine`, {
400
+ param: "fieldName",
401
+ fieldName
402
+ });
403
+ }
404
+ /**
263
405
  * Check that `spec` parses, so a proposal can be refused before any row is
264
406
  * written for it.
265
407
  *
@@ -267,6 +409,11 @@ function stringifyFieldDef(def) {
267
409
  */
268
410
  function assertValidFieldSpec(fieldName, spec) {
269
411
  assertProposableName("fieldName", fieldName);
412
+ const reserved = reservedMetadataFieldMessage(fieldName);
413
+ if (reserved !== void 0) throw new ProposalError("invalid_params", reserved, {
414
+ param: "fieldName",
415
+ fieldName
416
+ });
270
417
  if (typeof spec !== "object" || spec === null) throw new ProposalError("invalid_field_spec", `Spec for field '${fieldName}' must be an object`, { fieldName });
271
418
  try {
272
419
  parseFieldSpec(spec);
@@ -281,7 +428,8 @@ function assertValidFieldSpec(fieldName, spec) {
281
428
  * substrate-proposals namespace definition.
282
429
  *
283
430
  * Defines two types for schema evolution proposals:
284
- * - TypeProposal: proposes a new type (multiple fields at once)
431
+ * - TypeProposal: proposes a new type (multiple fields at once), and holds
432
+ * the indexes and natural order `propose_index` gives it
285
433
  * - FieldProposal: proposes a single field on an existing type
286
434
  *
287
435
  * Both track proposal metadata (proposedBy, proposedAt, reason) and application
@@ -293,9 +441,9 @@ function assertValidFieldSpec(fieldName, spec) {
293
441
  * the propose resolvers, held under a per-name lock (`proposal-lock.ts`), not
294
442
  * by a schema or database constraint.
295
443
  */
296
- function defineProposalTypes(namespace, capability = DEFAULT_PROPOSE_CAPABILITY) {
297
- const policy = proposeToWrite(capability);
298
- return defineNamespace(namespace, {
444
+ function defineProposalTypes(namespace, capability = DEFAULT_PROPOSE_CAPABILITY, indexCapability = DEFAULT_INDEX_CAPABILITY, dropCapability = capability === "" ? "" : DEFAULT_DROP_CAPABILITY) {
445
+ const policy = proposeToWrite(capability, indexCapability);
446
+ const def = defineNamespace(namespace, {
299
447
  TypeProposal: {
300
448
  policy,
301
449
  fields: {
@@ -308,7 +456,22 @@ function defineProposalTypes(namespace, capability = DEFAULT_PROPOSE_CAPABILITY)
308
456
  appliedAt: field.date({ nullable: true }),
309
457
  resultingSchemaVersion: field.string({ nullable: true }),
310
458
  supersededByCode: field.boolean(),
311
- archived: field.boolean()
459
+ archived: field.boolean(),
460
+ /** `IndexDecl[]` as JSON, set by `propose_index add`; null for none. */
461
+ indexesJson: field.string({
462
+ indexed: false,
463
+ nullable: true
464
+ }),
465
+ /** `OrderedBy` as JSON, set by `propose_index orderedBy`; null for the default. */
466
+ orderedByJson: field.string({
467
+ indexed: false,
468
+ nullable: true
469
+ }),
470
+ /** `'small' | 'large'`, the proposer's size hint for the index advisor; null when none. */
471
+ expectedSize: field.enum(["small", "large"], {
472
+ indexed: false,
473
+ nullable: true
474
+ })
312
475
  }
313
476
  },
314
477
  FieldProposal: {
@@ -332,6 +495,13 @@ function defineProposalTypes(namespace, capability = DEFAULT_PROPOSE_CAPABILITY)
332
495
  }
333
496
  }
334
497
  });
498
+ return {
499
+ ...def,
500
+ install(ctx) {
501
+ def.install(ctx);
502
+ gateTypeProposalRemoval(ctx.registry, dropCapability);
503
+ }
504
+ };
335
505
  }
336
506
  /** The canonical ordered list of type names registered by this namespace. */
337
507
  const PROPOSAL_TYPE_NAMES = ["TypeProposal", "FieldProposal"];
@@ -375,10 +545,13 @@ function assertValidFieldProposal(targetType, fieldName, fieldSpec, ownsTarget)
375
545
  }
376
546
  /** Installs the proposed type's autoCRUD surface into `registry`. */
377
547
  function installProposedType(registry, args) {
548
+ installAutoCrud(registry, args.typeName, args.dataset, args.edges, { fields: proposedFieldDefs(args.fields) });
549
+ }
550
+ /** A proposed type's field specs as FieldDefs, with the engine-reserved fields added. */
551
+ function proposedFieldDefs(fields) {
378
552
  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 });
553
+ for (const [name, spec] of Object.entries(fields)) fieldDefs[name] = parseFieldSpec(spec);
554
+ return Object.assign(fieldDefs, RESERVED_AUTOCRUD_FIELDS);
382
555
  }
383
556
  /**
384
557
  * Every registry key `applyTypeProposal` would register for this proposal —
@@ -405,6 +578,95 @@ function applyTypeProposal(args) {
405
578
  binding.invalidateSchemaCaches?.();
406
579
  }
407
580
  /**
581
+ * Parses a TypeProposal row's `indexesJson` / `orderedByJson` / `expectedSize`
582
+ * (null or absent: none). An `expectedSize` other than `small` or `large` is
583
+ * left out and handed to `onInvalidSize`, so a bad hint never costs the type
584
+ * its indexes or order.
585
+ */
586
+ function typeIndexOptionsOf(row, onInvalidSize) {
587
+ const parse = (v) => typeof v === "string" ? JSON.parse(v) : void 0;
588
+ const indexes = parse(row.indexesJson);
589
+ const orderedBy = parse(row.orderedByJson);
590
+ const size = row.expectedSize ?? void 0;
591
+ const expectedSize = size === "small" || size === "large" ? size : void 0;
592
+ if (size !== void 0 && expectedSize === void 0) onInvalidSize?.(/* @__PURE__ */ new Error(`expectedSize on ${String(row.typeName)} must be 'small' or 'large', got '${String(size)}'; ignored`));
593
+ return {
594
+ ...indexes !== void 0 ? { indexes } : {},
595
+ ...orderedBy !== void 0 ? { orderedBy } : {},
596
+ ...expectedSize !== void 0 ? { expectedSize } : {}
597
+ };
598
+ }
599
+ /**
600
+ * Refuse indexes or a natural order `propose_index` would not accept: each
601
+ * index as code may declare it, but never unique and never named (a name
602
+ * adopts whatever index already holds it), so every one is the engine's own,
603
+ * non-unique and generated. Rows are caller-written, so replay checks too.
604
+ *
605
+ * @throws Error naming the first problem
606
+ */
607
+ function assertValidTypeIndexOptions(typeName, fields, opts) {
608
+ if (opts.indexes !== void 0 && !Array.isArray(opts.indexes)) throw new Error(`indexes on ${typeName} must be an array`);
609
+ for (const decl of opts.indexes ?? []) {
610
+ if (typeof decl !== "object" || decl === null) throw new Error(`index on ${typeName}: must be an object`);
611
+ assertIndexDecl(typeName, fields, decl);
612
+ if (decl.unique !== void 0) throw new Error(`index on ${typeName}: a proposed index is never unique`);
613
+ if (decl.name !== void 0) throw new Error(`index on ${typeName}: a proposed index takes a generated name`);
614
+ }
615
+ if (opts.orderedBy !== void 0) assertOrderedBy(typeName, {
616
+ fields,
617
+ orderedBy: opts.orderedBy
618
+ });
619
+ if (opts.expectedSize !== void 0 && opts.expectedSize !== "small" && opts.expectedSize !== "large") throw new Error(`expectedSize on ${typeName} must be 'small' or 'large'`);
620
+ }
621
+ /**
622
+ * Reinstall `typeName`'s autoCRUD surface with `patch` over the options it was
623
+ * installed with (policy, postWrite, purge, indexes, order), swapping every
624
+ * entry through `registry.replace` so DuplicateRegistration is never thrown.
625
+ */
626
+ function reinstallType(registry, typeName, dataset, edges, patch) {
627
+ const existing = registry.get(typeName);
628
+ if (!existing) throw new Error(`type '${typeName}' not registered`);
629
+ const replaceWriter = {
630
+ register: (key, input) => registry.replace(key, input),
631
+ replace: registry.replace.bind(registry),
632
+ get: registry.get.bind(registry)
633
+ };
634
+ const prior = autoCrudOptionsOf(existing.resolver) ?? {
635
+ policy: existing.policy,
636
+ fields: existing.fields
637
+ };
638
+ installAutoCrud(replaceWriter, typeName, dataset, edges, patch(prior));
639
+ }
640
+ /**
641
+ * Give a registered proposed type the indexes and natural order its row
642
+ * stores, validated against the fields it has now (proposed ones included).
643
+ * Storage builds them on the next `ensureTypeStorage`.
644
+ */
645
+ function applyTypeIndexOptions(args) {
646
+ const binding = args.registryStore.getBinding(args.namespace);
647
+ const existing = binding.registry.get(args.typeName);
648
+ if (!existing) throw new Error(`type '${args.typeName}' not registered`);
649
+ assertValidTypeIndexOptions(args.typeName, existing.fields, args);
650
+ reinstallType(binding.registry, args.typeName, args.dataset, args.edges, (prior) => {
651
+ const { indexes: _i, orderedBy: _o, expectedSize: _s, ...rest } = prior;
652
+ return {
653
+ ...rest,
654
+ ...args.indexes !== void 0 ? { indexes: args.indexes } : {},
655
+ ...args.orderedBy !== void 0 ? { orderedBy: args.orderedBy } : {},
656
+ ...args.expectedSize !== void 0 ? { expectedSize: args.expectedSize } : {}
657
+ };
658
+ });
659
+ binding.invalidateSchemaCaches?.();
660
+ }
661
+ /** Whether the type entry already carries exactly these options. */
662
+ function hasTypeIndexOptions(entry, opts) {
663
+ return sameJson(entry.indexes, opts.indexes) && sameJson(entry.orderedBy, opts.orderedBy) && entry.expectedSize === opts.expectedSize;
664
+ }
665
+ /** Deep equality of JSON values, whatever order their keys were written in. */
666
+ function sameJson(a, b) {
667
+ return JSON.stringify(canonicalize$1(a)) === JSON.stringify(canonicalize$1(b));
668
+ }
669
+ /**
408
670
  * Extend an already-registered type with a new field.
409
671
  *
410
672
  * Replaces the type entry + all autoCRUD mutations atomically with versions
@@ -419,36 +681,34 @@ function applyFieldProposal(args) {
419
681
  const store = args.registryStore;
420
682
  assertValidFieldProposal(args.targetType, args.fieldName, args.fieldSpec, (ns) => store.ownsNamespace(ns));
421
683
  const binding = store.getBinding(args.namespace);
422
- const registry = binding.registry;
423
- const existing = registry.get(args.targetType);
684
+ const existing = binding.registry.get(args.targetType);
424
685
  if (!existing) throw new Error(`applyFieldProposal: target type '${args.targetType}' not registered`);
425
686
  const nextFields = {
426
687
  ...existing.fields,
427
688
  [args.fieldName]: parseFieldSpec(args.fieldSpec)
428
689
  };
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, {
690
+ reinstallType(binding.registry, args.targetType, args.dataset, args.edges, (prior) => ({
435
691
  ...prior,
436
692
  fields: nextFields
437
- });
693
+ }));
438
694
  binding.invalidateSchemaCaches?.();
439
695
  }
440
696
 
441
697
  //#endregion
442
698
  //#region ../../plugins/substrate-proposals/src/engine-write.ts
443
699
  /**
700
+ * Shared helpers used by the propose_* resolvers.
701
+ */
702
+ /**
444
703
  * Run the autoCRUD create-or-update `op` registered on `registry` inside the
445
704
  * caller's own transaction (`args.dataset`), and return the resulting row.
446
705
  * A nested `engine.mutate` would open a second transaction, and so take a
447
706
  * second pooled connection, beside the one the proposal already holds.
448
707
  *
449
- * @throws Error when `op` is not registered, its policy denies, or it returns no row
708
+ * @throws ResolverFrameError `policy_denied` when its policy denies
709
+ * @throws Error when `op` is not registered or returns no row
450
710
  */
451
- async function writeInTx(registry, ctx, args, op, params) {
711
+ async function writeInTx(registry, ctx, args, op, params, skipPolicy = false, trusted = false) {
452
712
  const entry = registry.get(op);
453
713
  if (entry === void 0) throw new Error(`'${op}' is not registered`);
454
714
  const opCtx = {
@@ -461,8 +721,9 @@ async function writeInTx(registry, ctx, args, op, params) {
461
721
  params,
462
722
  fields: { id: true }
463
723
  };
464
- const decision = entry.policy?.(opCtx, opArgs);
465
- if (decision !== void 0 && !decision.allow) throw new Error(`'${op}' denied: ${decision.reason ?? "policy denied"}`);
724
+ if (trusted) opArgs[TRUSTED_WRITE] = true;
725
+ const decision = skipPolicy ? void 0 : entry.policy?.(opCtx, opArgs);
726
+ if (decision !== void 0 && !decision.allow) throw new ResolverFrameError("policy_denied", `'${op}' denied: ${decision.reason ?? "policy denied"}`);
466
727
  const row = await entry.resolver(opCtx, opArgs);
467
728
  if (row === null || typeof row !== "object" || Array.isArray(row)) throw new Error(`'${op}' returned no row`);
468
729
  return row;
@@ -511,6 +772,61 @@ async function notifyAfterCommit(args, notify) {
511
772
  if (committed) await notify();
512
773
  });
513
774
  }
775
+ const pendingStorage = /* @__PURE__ */ new Set();
776
+ /** Resolves once every storage preparation started so far has settled. */
777
+ async function storageSettled() {
778
+ await Promise.all([...pendingStorage]);
779
+ }
780
+ function prepareStorage(dataset, type, handle, scope) {
781
+ if (scope?.signal.aborted === true) return;
782
+ const work = (async () => {
783
+ try {
784
+ const pending = (await dataset.ensureTypeStorage?.(type, {
785
+ newFields: "pending",
786
+ ...scope ? { signal: scope.signal } : {}
787
+ }))?.pending ?? [];
788
+ if (handle !== void 0 && pending.length > 0) await emitFieldEvents(handle, pending.map((field) => ({
789
+ kind: "field_pending",
790
+ namespace: dataset.namespace,
791
+ type,
792
+ field,
793
+ attempts: 0
794
+ }))).catch((err) => {
795
+ process.stderr.write(`[substrate-proposals] field_pending for ${dataset.namespace}/${type} not audited: ${err instanceof Error ? err.message : String(err)}\n`);
796
+ });
797
+ } catch (err) {
798
+ process.stderr.write(`[substrate-proposals] storage for ${dataset.namespace}/${type} not prepared: ${err instanceof Error ? err.message : String(err)}\n`);
799
+ }
800
+ })();
801
+ pendingStorage.add(work);
802
+ scope?.pending.add(work);
803
+ work.finally(() => {
804
+ pendingStorage.delete(work);
805
+ scope?.pending.delete(work);
806
+ });
807
+ }
808
+ /**
809
+ * Starts preparing `type`'s storage on the namespace's base `dataset` once the
810
+ * caller's transaction has committed (at once when there is none), never
811
+ * inside it: index builds run CONCURRENTLY and would wait forever on it. It
812
+ * runs in the background, because the lock waits and index builds have no
813
+ * bound and must not hold the caller's response; rows written meanwhile land
814
+ * in the DEFAULT partition and are moved. A failure is logged and never
815
+ * undoes the committed proposal; the next boot or proposal retries.
816
+ * A field added to a type that already has a table is recorded `pending`, and
817
+ * one `field_pending` `_system/AuditEvent` per such field is written and
818
+ * announced through `handle` (F11, F12). {@link storageSettled} awaits it;
819
+ * `scope`'s signal aborts it.
820
+ */
821
+ function ensureStorageAfterCommit(afterTx, dataset, type, handle, scope) {
822
+ if (afterTx === void 0) {
823
+ prepareStorage(dataset, type, handle, scope);
824
+ return;
825
+ }
826
+ afterTx(async ({ committed }) => {
827
+ if (committed) prepareStorage(dataset, type, handle, scope);
828
+ });
829
+ }
514
830
 
515
831
  //#endregion
516
832
  //#region ../../plugins/substrate-proposals/src/proposal-lock.ts
@@ -637,9 +953,7 @@ async function proposeNamespaceLocked(deps, ctx, args, input) {
637
953
  let proposalId;
638
954
  if (prior !== void 0) proposalId = String(prior.id);
639
955
  else {
640
- proposalId = randomUUID();
641
- await writeInTx(controlBinding.registry, ctx, args, "createNamespaceProposal", {
642
- id: proposalId,
956
+ const created = await writeInTx(controlBinding.registry, ctx, args, "createNamespaceProposal", {
643
957
  ns,
644
958
  proposedBy,
645
959
  proposedAt: /* @__PURE__ */ new Date(),
@@ -649,6 +963,7 @@ async function proposeNamespaceLocked(deps, ctx, args, input) {
649
963
  supersededByCode: false,
650
964
  archived: false
651
965
  });
966
+ proposalId = String(created.id);
652
967
  }
653
968
  try {
654
969
  installHotAddedNamespace({
@@ -658,6 +973,7 @@ async function proposeNamespaceLocked(deps, ctx, args, input) {
658
973
  engine: controlEngine,
659
974
  edges: deps.edges,
660
975
  ...deps.proposeCapability !== void 0 && { proposeCapability: deps.proposeCapability },
976
+ ...deps.indexCapability !== void 0 && { indexCapability: deps.indexCapability },
661
977
  ...deps.registerProposalMutations !== void 0 && { registerProposalMutations: deps.registerProposalMutations }
662
978
  });
663
979
  } finally {
@@ -715,12 +1031,32 @@ function claimForRollback(deps, ns, engine, args) {
715
1031
 
716
1032
  //#endregion
717
1033
  //#region ../../plugins/substrate-proposals/src/multi-instance.ts
1034
+ /** Why a stored field proposal is skipped when replay skipped its type. */
1035
+ function typeSkipped(row) {
1036
+ const type = String(row.targetType);
1037
+ const field = String(row.fieldName);
1038
+ return new ProposalError("unknown_type", `type '${type}' was skipped at replay, so its field '${field}' is not added`, {
1039
+ typeName: type,
1040
+ fieldName: field,
1041
+ typeSkipped: true
1042
+ });
1043
+ }
1044
+ /**
1045
+ * The warning line for a stored proposal skipped because it names a field reserved for
1046
+ * server metadata, or because its type was skipped; undefined for any other reason.
1047
+ */
1048
+ function reservedSkipLine(namespace, row, err) {
1049
+ if (err instanceof ProposalError && err.details.typeSkipped === true) return `substrate-proposals: ${namespace}/${String(row.targetType)}: field '${String(row.fieldName)}' is not added, because its type was skipped`;
1050
+ if (!(err instanceof ProposalError) || !err.message.includes("reserved for server metadata")) return;
1051
+ return `substrate-proposals: ${namespace}/${String(row.typeName ?? row.targetType)}: field '${String(err.details.fieldName ?? row.fieldName)}' is reserved for server metadata; ${row.typeName !== void 0 ? "the type is not registered" : "the field is not added"}`;
1052
+ }
718
1053
  async function setupNamespaceListener(args) {
719
1054
  await args.pubsub.listen(args.channel, async (payload) => {
720
1055
  await applyProposalFromNotification({
721
1056
  namespace: args.namespace,
722
1057
  proposalId: payload,
723
- registryStore: args.registryStore
1058
+ registryStore: args.registryStore,
1059
+ ...args.onSkip !== void 0 ? { onSkip: args.onSkip } : {}
724
1060
  }).catch(() => {});
725
1061
  });
726
1062
  }
@@ -729,23 +1065,33 @@ async function applyProposalFromNotification(args) {
729
1065
  const typeHit = await binding.dataset.read("TypeProposal", { id: args.proposalId });
730
1066
  if (typeHit.rows.length > 0) {
731
1067
  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
- });
1068
+ if (row.applied !== true) return;
1069
+ try {
1070
+ const typeName = row.typeName;
1071
+ let changed = false;
1072
+ if (!binding.registry.get(typeName)) {
1073
+ const fields = JSON.parse(row.fieldsJson);
1074
+ applyTypeProposal({
1075
+ namespace: args.namespace,
1076
+ typeName,
1077
+ fields,
1078
+ registryStore: args.registryStore,
1079
+ dataset: binding.dataset,
1080
+ edges: binding.edges
1081
+ });
1082
+ changed = true;
1083
+ }
1084
+ changed = replayTypeIndexOptions(args.registryStore, args.namespace, row) || changed;
1085
+ if (changed) ensureStorageAfterCommit(void 0, binding.dataset, typeName, binding.engine, args.registryStore.storage);
1086
+ } catch (err) {
1087
+ args.onSkip?.(row, err);
742
1088
  }
743
1089
  return;
744
1090
  }
745
1091
  const fieldHit = await binding.dataset.read("FieldProposal", { id: args.proposalId });
746
1092
  if (fieldHit.rows.length > 0) {
747
1093
  const row = fieldHit.rows[0];
748
- if (row.applied === true) {
1094
+ if (row.applied === true) try {
749
1095
  const entry = binding.registry.get(row.targetType);
750
1096
  if (entry && fieldNeedsReplay(entry, row)) {
751
1097
  const fieldSpec = JSON.parse(row.fieldSpecJson);
@@ -758,11 +1104,35 @@ async function applyProposalFromNotification(args) {
758
1104
  dataset: binding.dataset,
759
1105
  edges: binding.edges
760
1106
  });
1107
+ ensureStorageAfterCommit(void 0, binding.dataset, row.targetType, binding.engine, args.registryStore.storage);
761
1108
  }
1109
+ } catch (err) {
1110
+ args.onSkip?.(row, err);
762
1111
  }
763
1112
  }
764
1113
  }
765
1114
  /**
1115
+ * Bring a registered proposed type's indexes and natural order in line with
1116
+ * its row. False when they already match (or the type is not registered).
1117
+ *
1118
+ * @throws when the row's options are malformed or invalid for the type
1119
+ */
1120
+ function replayTypeIndexOptions(registryStore, namespace, row, onSkip) {
1121
+ const binding = registryStore.getBinding(namespace);
1122
+ const entry = binding.registry.get(row.typeName);
1123
+ const opts = typeIndexOptionsOf(row, (err) => onSkip?.(row, err));
1124
+ if (entry === void 0 || hasTypeIndexOptions(entry, opts)) return false;
1125
+ applyTypeIndexOptions({
1126
+ namespace,
1127
+ typeName: row.typeName,
1128
+ ...opts,
1129
+ registryStore,
1130
+ dataset: binding.dataset,
1131
+ edges: binding.edges
1132
+ });
1133
+ return true;
1134
+ }
1135
+ /**
766
1136
  * A field proposal needs replaying when its field is absent, or when it
767
1137
  * narrowed an enum: the type was registered with the wider spec, and the
768
1138
  * narrowing exists only in the proposal row.
@@ -778,8 +1148,11 @@ async function reconcileNamespace(args) {
778
1148
  { supersededByCode: { eq: false } },
779
1149
  { archived: { eq: false } }
780
1150
  ] },
1151
+ orderBy: [{ createdAt: "asc" }],
781
1152
  limit: 1e4
782
1153
  });
1154
+ const prepare = /* @__PURE__ */ new Set();
1155
+ const skippedTypes = /* @__PURE__ */ new Set();
783
1156
  for (const row of typeRows.rows) {
784
1157
  if (binding.registry.get(row.typeName)) continue;
785
1158
  try {
@@ -794,7 +1167,10 @@ async function reconcileNamespace(args) {
794
1167
  });
795
1168
  } catch (err) {
796
1169
  args.onSkip?.(row, err);
1170
+ skippedTypes.add(row.typeName);
1171
+ continue;
797
1172
  }
1173
+ prepare.add(row.typeName);
798
1174
  }
799
1175
  const fieldRows = await binding.dataset.read("FieldProposal", {
800
1176
  where: { AND: [
@@ -807,6 +1183,10 @@ async function reconcileNamespace(args) {
807
1183
  });
808
1184
  for (const row of fieldRows.rows) {
809
1185
  const entry = binding.registry.get(row.targetType);
1186
+ if (!entry && skippedTypes.has(row.targetType)) {
1187
+ args.onSkip?.(row, typeSkipped(row));
1188
+ continue;
1189
+ }
810
1190
  if (!entry || !fieldNeedsReplay(entry, row)) continue;
811
1191
  try {
812
1192
  const fieldSpec = JSON.parse(row.fieldSpecJson);
@@ -821,8 +1201,16 @@ async function reconcileNamespace(args) {
821
1201
  });
822
1202
  } catch (err) {
823
1203
  args.onSkip?.(row, err);
1204
+ continue;
824
1205
  }
1206
+ prepare.add(row.targetType);
825
1207
  }
1208
+ for (const row of typeRows.rows) try {
1209
+ if (replayTypeIndexOptions(args.registryStore, args.namespace, row, args.onSkip)) prepare.add(row.typeName);
1210
+ } catch (err) {
1211
+ args.onSkip?.(row, err);
1212
+ }
1213
+ for (const type of prepare) ensureStorageAfterCommit(void 0, binding.dataset, type, binding.engine, args.registryStore.storage);
826
1214
  }
827
1215
  /**
828
1216
  * Shared install path for a hot-added namespace. Three call sites use this:
@@ -859,7 +1247,7 @@ function installHotAddedNamespace(args) {
859
1247
  args.registryStore.set(args.ns, binding);
860
1248
  }
861
1249
  const registry = skipRegistered(binding.registry);
862
- defineProposalTypes(args.ns, args.proposeCapability).install({
1250
+ defineProposalTypes(args.ns, args.proposeCapability, args.indexCapability).install({
863
1251
  registry,
864
1252
  dataset: binding.dataset,
865
1253
  edges: binding.edges
@@ -927,6 +1315,7 @@ async function setupClusterNamespaceListener(args) {
927
1315
  engine: args.engine,
928
1316
  edges: args.edges,
929
1317
  ...args.proposeCapability !== void 0 && { proposeCapability: args.proposeCapability },
1318
+ ...args.indexCapability !== void 0 && { indexCapability: args.indexCapability },
930
1319
  ...args.registerProposalMutations !== void 0 && { registerProposalMutations: args.registerProposalMutations }
931
1320
  });
932
1321
  } catch (err) {
@@ -973,6 +1362,7 @@ async function reconcileClusterNamespaces(args) {
973
1362
  engine: args.engine,
974
1363
  edges: args.edges,
975
1364
  ...args.proposeCapability !== void 0 && { proposeCapability: args.proposeCapability },
1365
+ ...args.indexCapability !== void 0 && { indexCapability: args.indexCapability },
976
1366
  ...args.registerProposalMutations !== void 0 && { registerProposalMutations: args.registerProposalMutations }
977
1367
  });
978
1368
  } catch (err) {
@@ -1107,7 +1497,10 @@ function buildOnboardBody(ownedNamespaces) {
1107
1497
  params: {
1108
1498
  typeName: "string — PascalCase, unique within the namespace",
1109
1499
  fields: "object — FieldSpecJson map keyed by camelCase field name (see fieldSpecJson below)",
1110
- proposedReason: "string — short human-readable rationale"
1500
+ proposedReason: "string — short human-readable rationale",
1501
+ orderedBy: "optional { \"<field>\": \"asc\"|\"desc\" } — ask yourself what order this is usually read in. A date or number field, or createdAt / updatedAt. Defaults to createdAt desc.",
1502
+ indexes: "optional [{ fields: [...] }] — indexes the usual reads need. Never unique or named. Needs no extra capability on a new type; changing them later needs substrate.index.",
1503
+ expectedSize: "optional \"small\"|\"large\" — \"large\" gets index advice sooner"
1111
1504
  },
1112
1505
  returns: {
1113
1506
  id: "uuid — the TypeProposal record id",
@@ -1146,8 +1539,8 @@ function buildOnboardBody(ownedNamespaces) {
1146
1539
  description: "Narrow wire format mirroring the autoCRUD-expressible subset of FieldDef. Only these four shapes are accepted. Anything more expressive needs code + PR.",
1147
1540
  variants: {
1148
1541
  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."
1542
+ shape: "{ kind: \"scalar\", type: \"string\"|\"number\"|\"int16\"|\"int32\"|\"int64\"|\"boolean\"|\"date\"|\"json\", indexed?: bool, nullable?: bool }",
1543
+ notes: "indexed is unset by default (no index; crossRef defaults to indexed: true). No field needs an index to filter, and non-json scalars sort without one, so set indexed: true only where a read needs the speed. indexed: false also marks a field as not a search handle (long-form prose). json filters by path only and never sorts. readonly is reserved for engine-managed fields. Integers: pick the narrowest of int16 (-32768..32767), int32 (about ±2.1e9) or int64 (about ±9.2e18; a decimal string on the wire past 2^53) that holds every value the field will ever take, since a field's type cannot change once it has rows; when unsure, go one wider. Use number for fractional values. 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
1544
  },
1152
1545
  crossRef: {
1153
1546
  shape: "{ kind: \"crossRef\", ns: string, type: string, onDelete?: \"set_null\"|\"cascade\"|\"restrict\"|\"orphan\", indexed?: bool, nullable?: bool }",
@@ -1166,7 +1559,7 @@ function buildOnboardBody(ownedNamespaces) {
1166
1559
  constraints: [
1167
1560
  "AutoCRUD-only: every proposed type gets the standard create/get/update/delete/list surface. No custom resolvers — those require code.",
1168
1561
  "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.",
1562
+ "First-past-the-post: concurrent proposes of the same name (namespace, type, or field) are serialised by a lock on that name — a schema-scoped 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
1563
  "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
1564
  `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
1565
  "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."
@@ -1296,6 +1689,7 @@ function makeProposeFieldResolver(deps) {
1296
1689
  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
1690
  const input = args.params ?? {};
1298
1691
  assertValidFieldProposal(input.targetType, input.fieldName, input.fieldSpec, (ns, type) => deps.registryStore.ownsType(ns, type));
1692
+ assertNotEngineInjected(input.fieldName);
1299
1693
  if (input.proposedReason !== void 0 && typeof input.proposedReason !== "string") throw new ProposalError("invalid_params", "'proposedReason' must be a string", { param: "proposedReason" });
1300
1694
  const dataset = args.dataset ?? deps.dataset;
1301
1695
  return withProposalLock(dataset, proposalLockKey("field", deps.namespace, `${input.targetType}.${input.fieldName}`), () => proposeFieldLocked(deps, ctx, {
@@ -1356,9 +1750,7 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1356
1750
  }, suppliedMap, { oldVocabulary: oldEnum });
1357
1751
  }
1358
1752
  const proposedAt = /* @__PURE__ */ new Date();
1359
- const newId = randomUUID();
1360
1753
  const initialParams = {
1361
- id: newId,
1362
1754
  targetType,
1363
1755
  fieldName,
1364
1756
  fieldSpecJson: JSON.stringify(fieldSpec),
@@ -1373,8 +1765,8 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1373
1765
  archived: false
1374
1766
  };
1375
1767
  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]);
1768
+ const newId = engine !== void 0 ? (await writeInTx(binding.registry, ctx, args, "createFieldProposal", initialParams)).id : (await args.dataset.write("FieldProposal", [initialParams])).ids[0];
1769
+ if (newId === void 0) throw new Error("dataset.write did not return an id for FieldProposal");
1378
1770
  try {
1379
1771
  applyUntilRollback(args, binding.registry, () => applyFieldProposal({
1380
1772
  namespace: deps.namespace,
@@ -1410,6 +1802,7 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1410
1802
  await args.dataset.write("FieldProposal", [appliedRow]);
1411
1803
  }
1412
1804
  await notifyAfterCommit(args, () => deps.pubsub.notify(deps.channelFor(deps.namespace), String(newId)));
1805
+ ensureStorageAfterCommit(args.afterTx, deps.dataset, targetType, engine, deps.registryStore.storage);
1413
1806
  if (migration === null) return appliedRow;
1414
1807
  const { ids: _written, ...summary } = migration;
1415
1808
  return {
@@ -1418,6 +1811,338 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1418
1811
  };
1419
1812
  }
1420
1813
 
1814
+ //#endregion
1815
+ //#region ../../plugins/substrate-proposals/src/propose-index-resolver.ts
1816
+ /**
1817
+ * Factory for the `propose_index` mutation resolver: the signed approval of an
1818
+ * index recommendation, or a direct index change, under the index capability.
1819
+ *
1820
+ * - `add` appends a declared index to a proposed type's TypeProposal row and
1821
+ * reinstalls the type; storage builds it in the background after commit.
1822
+ * - `orderedBy` sets a proposed type's natural order the same way, and storage
1823
+ * swaps its derived indexes.
1824
+ * - `remove` drops an engine-owned, non-unique index the engine no longer
1825
+ * wants, on any type (`Dataset.dropEngineIndex`, which re-checks it live).
1826
+ * An index wanted only because a proposed type's `indexesJson` declares it
1827
+ * is retracted first: the declaration leaves the row, peers are told, and
1828
+ * the index is dropped.
1829
+ * - `dismiss` closes a recommendation without acting on it.
1830
+ *
1831
+ * A referenced `_system/IndexRecommendation` must be `open`, and moves to
1832
+ * `accepted` or `dismissed` by a conditional update from `open`, claimed
1833
+ * before the audit event and the effect and given back (to `open`) if the
1834
+ * effect fails, so a caller never learns it was closed after its own effect. Its rows are
1835
+ * writable by any index-capability holder, so nothing in one is trusted: an
1836
+ * `add` must still be unserved by the type's index plan (as the advisor's
1837
+ * supersede pass decides) and its declaration validates as a direct one does;
1838
+ * `remove` is checked against the catalog. When that evidence no longer
1839
+ * holds the call is refused `recommendation_stale` and the row superseded.
1840
+ *
1841
+ * Every write here goes through the namespaces' base datasets, outside the
1842
+ * caller's transaction: a `DROP INDEX CONCURRENTLY` cannot run beside it, and
1843
+ * a superseded mark must outlive the refusal that rolls the transaction back.
1844
+ * Each one is stamped with the caller's identity.
1845
+ *
1846
+ * Audit: every applied call writes one `_system/AuditEvent` (`index_proposed`)
1847
+ * once its checks have passed and before its first effect (for a drop, under
1848
+ * the table lock, just before `DROP INDEX`), so no effect lands unaudited. For
1849
+ * a recommendation the event's id derives from the recommendation's, written
1850
+ * insert-only, so a retry after a partial failure converges without a second
1851
+ * event.
1852
+ */
1853
+ const SYSTEM_NAMESPACE = "_system";
1854
+ const RECOMMENDATION_TYPE = "IndexRecommendation";
1855
+ const ACTIONS = [
1856
+ "add",
1857
+ "remove",
1858
+ "dismiss",
1859
+ "orderedBy"
1860
+ ];
1861
+ /** `dropEngineIndex` refusal codes, passed through as the call's own. */
1862
+ const DROP_REFUSALS = /* @__PURE__ */ new Set([
1863
+ "unknown_index",
1864
+ "not_engine_owned",
1865
+ "unique_index",
1866
+ "still_desired",
1867
+ "index_drop_timeout"
1868
+ ]);
1869
+ /** A read row without the engine fields reads add (`shortId`), for writing back. */
1870
+ function bodyOf(row) {
1871
+ const body = { ...row };
1872
+ for (const name of RESERVED_AUTOCRUD_FIELD_NAMES) delete body[name];
1873
+ return body;
1874
+ }
1875
+ function invalid(param, message) {
1876
+ return new ProposalError("invalid_params", message, { param });
1877
+ }
1878
+ function closed(id, state) {
1879
+ return new ProposalError("recommendation_closed", `index recommendation '${String(id)}' is no longer open${state === void 0 ? "" : ` (${String(state)})`}`, state === void 0 ? {} : { state });
1880
+ }
1881
+ function parseInput$1(params) {
1882
+ for (const key of [
1883
+ "namespace",
1884
+ "type",
1885
+ "reason"
1886
+ ]) if (typeof params[key] !== "string" || key !== "reason" && params[key] === "") throw invalid(key, `'${key}' must be a${key === "reason" ? "" : " non-empty"} string`);
1887
+ if (!ACTIONS.includes(params.action)) throw invalid("action", `'action' must be one of ${ACTIONS.join(", ")}`);
1888
+ for (const key of ["recommendationId", "indexName"]) if (params[key] !== void 0 && typeof params[key] !== "string") throw invalid(key, `'${key}' must be a string`);
1889
+ return params;
1890
+ }
1891
+ function makeProposeIndexResolver(deps) {
1892
+ return async (ctx, args) => {
1893
+ if ((args.txEntries ?? 1) > 1) throw new ProposalError("propose_index_not_alone", "propose_index must be the only entry in its mutate request; send it on its own", { entries: args.txEntries });
1894
+ const input = parseInput$1(args.params ?? {});
1895
+ const lockOn = deps.datasetFor(SYSTEM_NAMESPACE) ?? args.dataset;
1896
+ const run = () => proposeIndex(deps, ctx, args, input);
1897
+ if (lockOn === void 0) return run();
1898
+ return withProposalLock(lockOn, proposalLockKey("index", input.namespace, input.type), run);
1899
+ };
1900
+ }
1901
+ async function proposeIndex(deps, ctx, args, input) {
1902
+ const identity = resolveIdentity(ctx);
1903
+ const system = deps.datasetFor(SYSTEM_NAMESPACE);
1904
+ const now = /* @__PURE__ */ new Date();
1905
+ const rec = input.recommendationId === void 0 ? void 0 : await openRecommendation();
1906
+ async function openRecommendation() {
1907
+ const id = input.recommendationId;
1908
+ const row = system === void 0 ? void 0 : (await system.read(RECOMMENDATION_TYPE, {
1909
+ id,
1910
+ limit: 1
1911
+ })).rows[0];
1912
+ if (row === void 0) throw new ProposalError("unknown_recommendation", `no index recommendation '${id}'`);
1913
+ if (row.state !== "open") throw closed(id, row.state);
1914
+ if (row.namespace !== input.namespace || row.type !== input.type) throw invalid("recommendationId", `recommendation '${id}' is for ${row.namespace}/${row.type}`);
1915
+ if (input.action !== "dismiss" && row.action !== input.action) throw invalid("action", `recommendation '${id}' recommends '${String(row.action)}'`);
1916
+ return row;
1917
+ }
1918
+ const auditId = rec === void 0 ? randomUUID() : uuidFromName(`index_proposed:${String(rec.id)}`);
1919
+ let audited;
1920
+ const audit = async (detail) => {
1921
+ if (audited !== void 0) return;
1922
+ audited = detail;
1923
+ await system?.write("AuditEvent", [{
1924
+ id: auditId,
1925
+ ts: now.toISOString(),
1926
+ actorKid: identity.id,
1927
+ kind: "index_proposed",
1928
+ targetKid: `${input.namespace}/${input.type}`,
1929
+ clientIp: null,
1930
+ details: {
1931
+ action: input.action,
1932
+ reason: input.reason,
1933
+ recommendationId: rec?.id ?? null,
1934
+ ...detail
1935
+ }
1936
+ }], {
1937
+ identity,
1938
+ now,
1939
+ insertOnly: true
1940
+ });
1941
+ };
1942
+ /** Moves the recommendation (if any) from `open` to `state`, atomically. */
1943
+ const close = async (state) => {
1944
+ if (rec === void 0 || system === void 0) return;
1945
+ const { matched } = await system.conditionalUpdate(RECOMMENDATION_TYPE, rec.id, { state: "open" }, { state }, identity, now);
1946
+ if (!matched) throw closed(rec.id);
1947
+ };
1948
+ let claimed;
1949
+ const claim = async (state) => {
1950
+ await close(state);
1951
+ if (rec !== void 0 && system !== void 0) claimed = state;
1952
+ };
1953
+ /** Gives a claim back (claimed → open) when the work behind it failed. */
1954
+ const release = async () => {
1955
+ const state = claimed;
1956
+ if (state === void 0 || rec === void 0 || system === void 0) return;
1957
+ claimed = void 0;
1958
+ const fail = (why) => {
1959
+ process.stderr.write(`[substrate-proposals] index recommendation ${String(rec.id)} stays ${state} after a failed ${input.action}: ${why}\n`);
1960
+ };
1961
+ try {
1962
+ const { matched } = await system.conditionalUpdate(RECOMMENDATION_TYPE, rec.id, { state }, { state: "open" }, identity, now);
1963
+ if (!matched) fail("it was changed meanwhile");
1964
+ } catch (err) {
1965
+ fail(err instanceof Error ? err.message : String(err));
1966
+ }
1967
+ };
1968
+ const stale = async (reason, code) => {
1969
+ await release();
1970
+ await close("superseded");
1971
+ throw new ProposalError("recommendation_stale", `index recommendation '${String(rec?.id)}' no longer holds: ${reason}`, code !== void 0 ? { reason: code } : {});
1972
+ };
1973
+ const call = {
1974
+ deps,
1975
+ args,
1976
+ input,
1977
+ identity,
1978
+ rec,
1979
+ audit,
1980
+ stale,
1981
+ claim,
1982
+ release
1983
+ };
1984
+ try {
1985
+ switch (input.action) {
1986
+ case "dismiss":
1987
+ if (rec === void 0) throw invalid("recommendationId", "'dismiss' needs a recommendationId");
1988
+ await claim("dismissed");
1989
+ await audit({});
1990
+ break;
1991
+ case "remove":
1992
+ await removeIndex(call, system, auditId);
1993
+ break;
1994
+ case "add":
1995
+ case "orderedBy": await changeProposedType(call);
1996
+ }
1997
+ } catch (err) {
1998
+ await release();
1999
+ throw err;
2000
+ }
2001
+ return {
2002
+ id: auditId,
2003
+ action: input.action,
2004
+ namespace: input.namespace,
2005
+ type: input.type,
2006
+ recommendationId: rec?.id ?? null,
2007
+ indexName: audited?.indexName ?? null
2008
+ };
2009
+ }
2010
+ /** The applied, live TypeProposal row of `type`, or undefined (a code-defined type). */
2011
+ async function proposalOf(binding, type) {
2012
+ return (await binding.dataset.read("TypeProposal", {
2013
+ where: { AND: [
2014
+ { typeName: { eq: type } },
2015
+ { applied: { eq: true } },
2016
+ { supersededByCode: { eq: false } },
2017
+ { archived: { eq: false } }
2018
+ ] },
2019
+ limit: 1
2020
+ })).rows[0];
2021
+ }
2022
+ /**
2023
+ * Stores `next` on the proposal row, reinstalls the type with it, and tells
2024
+ * peers once the caller's transaction commits.
2025
+ */
2026
+ async function storeTypeIndexOptions(call, binding, proposal, next) {
2027
+ const { deps, args, input, identity } = call;
2028
+ const { indexes: all, ...rest } = next;
2029
+ const opts = {
2030
+ ...rest,
2031
+ ...all?.length ? { indexes: all } : {}
2032
+ };
2033
+ await binding.dataset.write("TypeProposal", [{
2034
+ ...bodyOf(proposal),
2035
+ indexesJson: opts.indexes !== void 0 ? JSON.stringify(opts.indexes) : null,
2036
+ orderedByJson: opts.orderedBy !== void 0 ? JSON.stringify(opts.orderedBy) : null
2037
+ }], { identity });
2038
+ applyTypeIndexOptions({
2039
+ namespace: input.namespace,
2040
+ typeName: input.type,
2041
+ ...opts,
2042
+ registryStore: deps.registryStore,
2043
+ dataset: binding.dataset,
2044
+ edges: binding.edges
2045
+ });
2046
+ await notifyAfterCommit(args, () => deps.pubsub.notify(deps.channelFor(input.namespace), String(proposal.id)));
2047
+ }
2048
+ /** `remove`: retract a proposed declaration if that is all that wants it, then drop. */
2049
+ async function removeIndex(call, system, auditId) {
2050
+ const { deps, input, rec } = call;
2051
+ const name = input.indexName ?? rec?.indexName ?? void 0;
2052
+ if (name === void 0) throw invalid("indexName", "'remove' needs an indexName");
2053
+ const dataset = deps.datasetFor(input.namespace) ?? system?.forNamespace(input.namespace);
2054
+ await call.claim("accepted");
2055
+ if (rec === void 0 && dataset?.indexDeclarationOf !== void 0) {
2056
+ const binding = deps.registryStore.ownsNamespace(input.namespace) ? deps.registryStore.getBinding(input.namespace) : void 0;
2057
+ const proposal = binding === void 0 ? void 0 : await proposalOf(binding, input.type);
2058
+ const decl = proposal === void 0 ? void 0 : await dataset.indexDeclarationOf(input.type, name);
2059
+ const current = proposal === void 0 ? {} : typeIndexOptionsOf(proposal);
2060
+ const kept = (current.indexes ?? []).filter((d) => !sameJson(d, decl));
2061
+ if (binding !== void 0 && proposal !== void 0 && decl !== void 0 && kept.length < (current.indexes ?? []).length) {
2062
+ await call.audit({
2063
+ indexName: name,
2064
+ retracted: decl
2065
+ });
2066
+ await storeTypeIndexOptions(call, binding, proposal, {
2067
+ ...current,
2068
+ indexes: kept
2069
+ });
2070
+ }
2071
+ }
2072
+ try {
2073
+ if (dataset?.dropEngineIndex === void 0) throw Object.assign(/* @__PURE__ */ new Error(`no index ${name} on ${input.namespace}/${input.type}`), { code: "unknown_index" });
2074
+ await dataset.dropEngineIndex(input.type, name, { beforeDrop: () => call.audit({ indexName: name }) });
2075
+ } catch (err) {
2076
+ const code = err.code;
2077
+ if (typeof code !== "string" || !DROP_REFUSALS.has(code)) throw err;
2078
+ const message = err instanceof Error ? err.message : String(err);
2079
+ if (rec !== void 0 && code !== "index_drop_timeout") {
2080
+ if (code === "unknown_index" && (await system?.read("AuditEvent", {
2081
+ id: auditId,
2082
+ limit: 1
2083
+ }))?.rows[0] !== void 0) return;
2084
+ await call.stale(message, code);
2085
+ }
2086
+ await call.release();
2087
+ throw new ProposalError(code, message, { indexName: name });
2088
+ }
2089
+ }
2090
+ /** `add` or `orderedBy` on a proposed type: update its row, then its registry entry. */
2091
+ async function changeProposedType(call) {
2092
+ const { deps, args, input, rec, stale } = call;
2093
+ const { namespace: ns, type } = input;
2094
+ const codeDefined = () => new ProposalError("index_on_code_defined_type", `${ns}/${type} is defined in code by the plugin that owns namespace '${ns}'; declare its ${input.action === "add" ? "index" : "orderedBy"} there`, { namespace: ns });
2095
+ if (!deps.registryStore.ownsNamespace(ns)) throw codeDefined();
2096
+ const binding = deps.registryStore.getBinding(ns);
2097
+ const entry = binding.registry.get(type);
2098
+ if (entry?.kind !== "type") throw new ProposalError("unknown_type", `no type '${type}' in namespace '${ns}'`);
2099
+ const proposal = await proposalOf(binding, type);
2100
+ if (proposal === void 0) throw codeDefined();
2101
+ const current = typeIndexOptionsOf(proposal);
2102
+ let next;
2103
+ let detail;
2104
+ if (input.action === "add") {
2105
+ let decl = input.declaration;
2106
+ if (decl === void 0 && rec !== void 0) try {
2107
+ decl = JSON.parse(rec.declarationJson);
2108
+ } catch {
2109
+ return stale("its declaration is not JSON");
2110
+ }
2111
+ if (decl === void 0) throw invalid("declaration", "'add' needs a declaration");
2112
+ const indexes = current.indexes ?? [];
2113
+ const known = indexes.some((d) => sameJson(d, decl));
2114
+ if (rec !== void 0 && !known) {
2115
+ const plan = await binding.dataset.indexPlan?.(type, ns) ?? { indexes: [] };
2116
+ const served = planServesShape(plan, String(rec.shape));
2117
+ if (served === void 0) return stale("its read shape does not parse");
2118
+ if (served) return stale("an index the type already has serves its read shape");
2119
+ }
2120
+ next = {
2121
+ ...current,
2122
+ indexes: known ? indexes : [...indexes, decl]
2123
+ };
2124
+ detail = { declaration: decl };
2125
+ } else {
2126
+ if (input.orderedBy === void 0) throw invalid("orderedBy", "'orderedBy' needs an orderedBy");
2127
+ next = {
2128
+ ...current,
2129
+ orderedBy: input.orderedBy
2130
+ };
2131
+ detail = { orderedBy: input.orderedBy };
2132
+ }
2133
+ try {
2134
+ assertValidTypeIndexOptions(type, entry.fields, next);
2135
+ } catch (err) {
2136
+ const message = err instanceof Error ? err.message : String(err);
2137
+ if (rec !== void 0) return stale(message);
2138
+ throw invalid(input.action === "add" ? "declaration" : "orderedBy", message);
2139
+ }
2140
+ await call.claim("accepted");
2141
+ await call.audit(detail);
2142
+ await storeTypeIndexOptions(call, binding, proposal, next);
2143
+ ensureStorageAfterCommit(args.afterTx, binding.dataset, type, binding.engine, deps.registryStore.storage);
2144
+ }
2145
+
1421
2146
  //#endregion
1422
2147
  //#region ../../plugins/substrate-proposals/src/propose-type-resolver.ts
1423
2148
  /**
@@ -1441,6 +2166,8 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1441
2166
  function parseInput(params) {
1442
2167
  const { proposedReason } = params;
1443
2168
  if (proposedReason !== void 0 && typeof proposedReason !== "string") throw new ProposalError("invalid_params", "'proposedReason' must be a string", { param: "proposedReason" });
2169
+ const { expectedSize } = params;
2170
+ if (expectedSize !== void 0 && expectedSize !== "small" && expectedSize !== "large") throw new ProposalError("invalid_params", "'expectedSize' must be 'small' or 'large'", { param: "expectedSize" });
1444
2171
  return {
1445
2172
  ...params,
1446
2173
  proposedReason: proposedReason ?? ""
@@ -1451,6 +2178,12 @@ function makeProposeTypeResolver(deps) {
1451
2178
  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
2179
  const input = parseInput(args.params ?? {});
1453
2180
  assertValidTypeProposal(input.typeName, input.fields, (ns, type) => ns === deps.namespace && type === input.typeName || deps.registryStore.ownsType(ns, type));
2181
+ for (const name of Object.keys(input.fields)) assertNotEngineInjected(name);
2182
+ try {
2183
+ assertValidTypeIndexOptions(input.typeName, proposedFieldDefs(input.fields), indexOptionsOf(input));
2184
+ } catch (cause) {
2185
+ throw new ProposalError("invalid_params", cause instanceof Error ? cause.message : String(cause), {}, { cause });
2186
+ }
1454
2187
  const dataset = args.dataset ?? deps.dataset;
1455
2188
  return withProposalLock(dataset, proposalLockKey("type", deps.namespace, input.typeName), () => proposeTypeLocked(deps, ctx, {
1456
2189
  ...args,
@@ -1458,6 +2191,27 @@ function makeProposeTypeResolver(deps) {
1458
2191
  }, input));
1459
2192
  };
1460
2193
  }
2194
+ function indexOptionsOf(input) {
2195
+ const { indexes, orderedBy, expectedSize } = input;
2196
+ return {
2197
+ ...indexes?.length ? { indexes } : {},
2198
+ ...orderedBy !== void 0 ? { orderedBy } : {},
2199
+ ...expectedSize !== void 0 ? { expectedSize } : {}
2200
+ };
2201
+ }
2202
+ /**
2203
+ * Whether `typeName` has storage already: any TypeProposal row by that name,
2204
+ * or any row of the type, archived and tombstoned ones included, so a
2205
+ * propose-only caller cannot clear the signal by deleting them.
2206
+ */
2207
+ async function hasStorage(dataset, typeName) {
2208
+ if ((await dataset.read("TypeProposal", {
2209
+ where: { typeName: { eq: typeName } },
2210
+ includeDeleted: true,
2211
+ limit: 1
2212
+ })).rows.length > 0) return true;
2213
+ return typeHasRows(dataset, typeName);
2214
+ }
1461
2215
  /** Steps 2-7, run while holding the proposal lock for this type name. */
1462
2216
  async function proposeTypeLocked(deps, ctx, args, input) {
1463
2217
  const { typeName, fields, proposedReason } = input;
@@ -1483,12 +2237,9 @@ async function proposeTypeLocked(deps, ctx, args, input) {
1483
2237
  }).find((key) => liveRegistry.has(key));
1484
2238
  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
2239
  const proposedAt = /* @__PURE__ */ new Date();
1486
- const fieldsJson = JSON.stringify(fields);
1487
- const newId = randomUUID();
1488
2240
  const initialParams = {
1489
- id: newId,
1490
2241
  typeName,
1491
- fieldsJson,
2242
+ fieldsJson: JSON.stringify(fields),
1492
2243
  proposedBy,
1493
2244
  proposedAt,
1494
2245
  proposedReason,
@@ -1496,22 +2247,56 @@ async function proposeTypeLocked(deps, ctx, args, input) {
1496
2247
  appliedAt: null,
1497
2248
  resultingSchemaVersion: null,
1498
2249
  supersededByCode: false,
1499
- archived: false
2250
+ archived: false,
2251
+ expectedSize: input.expectedSize ?? null
2252
+ };
2253
+ const indexOpts = indexOptionsOf(input);
2254
+ const indexFields = {
2255
+ indexesJson: indexOpts.indexes ? JSON.stringify(indexOpts.indexes) : null,
2256
+ orderedByJson: indexOpts.orderedBy ? JSON.stringify(indexOpts.orderedBy) : null
1500
2257
  };
1501
2258
  const binding = deps.registryStore.getBinding(deps.namespace);
1502
2259
  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");
2260
+ let newId;
2261
+ if (engine !== void 0) {
2262
+ const declaresIndexes = indexOpts.indexes !== void 0 || indexOpts.orderedBy !== void 0;
2263
+ newId = (await writeInTx(binding.registry, ctx, args, "createTypeProposal", {
2264
+ ...initialParams,
2265
+ ...indexFields
2266
+ }, !(declaresIndexes && await hasStorage(args.dataset, typeName)))).id;
2267
+ } else {
2268
+ const id = (await args.dataset.write("TypeProposal", [{
2269
+ ...initialParams,
2270
+ ...indexFields
2271
+ }])).ids[0];
2272
+ if (id === void 0) throw new Error("dataset.write did not return an id for TypeProposal");
2273
+ newId = id;
2274
+ }
1505
2275
  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?.());
2276
+ applyUntilRollback(args, binding.registry, () => {
2277
+ applyTypeProposal({
2278
+ namespace: deps.namespace,
2279
+ typeName,
2280
+ fields,
2281
+ registryStore: deps.registryStore,
2282
+ dataset: deps.dataset,
2283
+ edges: deps.edges
2284
+ });
2285
+ if (Object.keys(indexOpts).length > 0) try {
2286
+ applyTypeIndexOptions({
2287
+ namespace: deps.namespace,
2288
+ typeName,
2289
+ ...indexOpts,
2290
+ registryStore: deps.registryStore,
2291
+ dataset: deps.dataset,
2292
+ edges: deps.edges
2293
+ });
2294
+ } catch (cause) {
2295
+ throw new ProposalError("invalid_params", cause instanceof Error ? cause.message : String(cause), {}, { cause });
2296
+ }
2297
+ }, () => binding.invalidateSchemaCaches?.());
1514
2298
  } catch (cause) {
2299
+ if (cause instanceof ProposalError) throw cause;
1515
2300
  throw new ProposalError("type_already_exists", `Could not apply type '${typeName}': ${cause instanceof Error ? cause.message : String(cause)}`, {}, { cause });
1516
2301
  }
1517
2302
  const now = /* @__PURE__ */ new Date();
@@ -1523,7 +2308,7 @@ async function proposeTypeLocked(deps, ctx, args, input) {
1523
2308
  applied: true,
1524
2309
  appliedAt: now,
1525
2310
  resultingSchemaVersion
1526
- });
2311
+ }, false, true);
1527
2312
  const rawRow = (await args.dataset.read("TypeProposal", { id: newId })).rows[0];
1528
2313
  if (!rawRow) throw new Error(`TypeProposal row ${newId} not found after engine update`);
1529
2314
  appliedRow = rawRow;
@@ -1539,6 +2324,7 @@ async function proposeTypeLocked(deps, ctx, args, input) {
1539
2324
  await args.dataset.write("TypeProposal", [appliedRow]);
1540
2325
  }
1541
2326
  await notifyAfterCommit(args, () => deps.pubsub.notify(deps.channelFor(deps.namespace), String(newId)));
2327
+ ensureStorageAfterCommit(args.afterTx, deps.dataset, typeName, engine, deps.registryStore.storage);
1542
2328
  return appliedRow;
1543
2329
  }
1544
2330
 
@@ -1554,6 +2340,17 @@ async function proposeTypeLocked(deps, ctx, args, input) {
1554
2340
  */
1555
2341
  var RegistryStore = class {
1556
2342
  bindings = /* @__PURE__ */ new Map();
2343
+ #storageAbort = new AbortController();
2344
+ /** This plugin instance's background storage work. */
2345
+ storage = {
2346
+ signal: this.#storageAbort.signal,
2347
+ pending: /* @__PURE__ */ new Set()
2348
+ };
2349
+ /** Aborts the background storage work (an interrupted build is left INVALID for the next reconcile) and awaits it. */
2350
+ async stopStorage() {
2351
+ this.#storageAbort.abort();
2352
+ await Promise.all([...this.storage.pending]);
2353
+ }
1557
2354
  /**
1558
2355
  * Register a full NamespaceBinding for the given namespace.
1559
2356
  *
@@ -1644,6 +2441,7 @@ function createProposalsPlugin(config) {
1644
2441
  const registryStore = new RegistryStore();
1645
2442
  const capability = config.proposeCapability ?? "substrate.propose";
1646
2443
  const policy = makeProposePolicy(capability);
2444
+ const indexCapability = config.indexCapability ?? "substrate.index";
1647
2445
  let lookupDataset = config.datasetFor ?? (() => void 0);
1648
2446
  /**
1649
2447
  * Shared resolver-registration helper. Used at static-ns install time AND
@@ -1694,10 +2492,21 @@ function createProposalsPlugin(config) {
1694
2492
  edges: ctx.edges,
1695
2493
  pubsub: config.pubsub,
1696
2494
  proposeCapability: capability,
2495
+ indexCapability,
1697
2496
  registerProposalMutations
1698
2497
  }),
1699
2498
  policy
1700
2499
  });
2500
+ ctx.registry.register("propose_index", {
2501
+ kind: "mutation",
2502
+ resolver: makeProposeIndexResolver({
2503
+ registryStore,
2504
+ datasetFor: (ns) => lookupDataset(ns),
2505
+ pubsub: config.pubsub,
2506
+ channelFor: (n) => `_substrate_proposals_${n}`
2507
+ }),
2508
+ policy: makeIndexPolicy(indexCapability)
2509
+ });
1701
2510
  }
1702
2511
  }, ...config.ownedNamespaces.map((ns) => ({
1703
2512
  namespace: ns,
@@ -1707,7 +2516,7 @@ function createProposalsPlugin(config) {
1707
2516
  dataset: ctx.dataset,
1708
2517
  edges: ctx.edges
1709
2518
  });
1710
- defineProposalTypes(ns, capability).install(ctx);
2519
+ defineProposalTypes(ns, capability, indexCapability).install(ctx);
1711
2520
  registerProposalMutations({
1712
2521
  namespace: ns,
1713
2522
  dataset: ctx.dataset,
@@ -1724,6 +2533,18 @@ function createProposalsPlugin(config) {
1724
2533
  registryStore.setInvalidator(CONTROL_NAMESPACE, () => ctx.engine.invalidateSchemaCaches(CONTROL_NAMESPACE));
1725
2534
  registryStore.setEngine(CONTROL_NAMESPACE, ctx.engine);
1726
2535
  if (config.datasetFor === void 0) lookupDataset = (ns) => ctx.engine.datasetFor(ns);
2536
+ const log = config.log ?? ((line) => console.warn(line));
2537
+ const skipped = (ns, row, err) => {
2538
+ ctx.metric("_system_proposals.replay_skipped", {
2539
+ namespace: ns,
2540
+ id: row.id,
2541
+ type: row.typeName ?? row.targetType,
2542
+ field: row.fieldName ?? null,
2543
+ error: err instanceof Error ? err.message : String(err)
2544
+ });
2545
+ const line = reservedSkipLine(ns, row, err);
2546
+ if (line !== void 0) log(line);
2547
+ };
1727
2548
  const controlBinding = registryStore.getBinding(CONTROL_NAMESPACE);
1728
2549
  const hotAddedNamespaces = await reconcileClusterNamespaces({
1729
2550
  controlNamespace: CONTROL_NAMESPACE,
@@ -1732,6 +2553,7 @@ function createProposalsPlugin(config) {
1732
2553
  datasetFor: lookupDataset,
1733
2554
  edges: controlBinding.edges,
1734
2555
  proposeCapability: capability,
2556
+ indexCapability,
1735
2557
  registerProposalMutations,
1736
2558
  onSkip: (row, err) => ctx.metric("_system_proposals.replay_skipped", {
1737
2559
  namespace: CONTROL_NAMESPACE,
@@ -1746,17 +2568,14 @@ function createProposalsPlugin(config) {
1746
2568
  await reconcileNamespace({
1747
2569
  namespace: ns,
1748
2570
  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
- })
2571
+ onSkip: (row, err) => skipped(ns, row, err)
1754
2572
  });
1755
2573
  await setupNamespaceListener({
1756
2574
  namespace: ns,
1757
2575
  channel: `_substrate_proposals_${ns}`,
1758
2576
  pubsub: config.pubsub,
1759
- registryStore
2577
+ registryStore,
2578
+ onSkip: (row, err) => skipped(ns, row, err)
1760
2579
  });
1761
2580
  ctx.metric("_system_proposals.namespace_ready", { namespace: ns });
1762
2581
  }
@@ -1787,11 +2606,15 @@ function createProposalsPlugin(config) {
1787
2606
  edges: controlBinding.edges,
1788
2607
  metric: ctx.metric,
1789
2608
  proposeCapability: capability,
2609
+ indexCapability,
1790
2610
  registerProposalMutations
1791
2611
  });
2612
+ },
2613
+ async onStop() {
2614
+ await registryStore.stopStorage();
1792
2615
  }
1793
2616
  };
1794
2617
  }
1795
2618
 
1796
2619
  //#endregion
1797
- export { createNoopPubSub as n, ProposalError as r, createProposalsPlugin as t };
2620
+ export { ProposalError as i, createNoopPubSub as n, storageSettled as r, createProposalsPlugin as t };