@mnmal-ai/substrate 1.0.0-alpha.1 → 1.0.0-alpha.10

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 (47) hide show
  1. package/README.md +48 -6
  2. package/dist/boot-store-BVqfFxh1.js +4060 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-Cp4PaIYO.d.ts} +2 -87
  4. package/dist/cli-hSCBywhE.js +3126 -0
  5. package/dist/client.d.ts +130 -8
  6. package/dist/client.js +6 -5
  7. package/dist/{plugin-t2g2wX0b.d.ts → dataset-CejF-Fr_.d.ts} +1640 -1320
  8. package/dist/{agent-token-BIboWOU0.js → env-utils-CGNazUNt.js} +31 -2
  9. package/dist/{errors-D4vKuwz8.d.ts → errors-7mycvNGq.d.ts} +1 -1
  10. package/dist/{index-D7mSOFlM.d.ts → index-DgSfwx7M.d.ts} +1 -1
  11. package/dist/node-version-C5FSmwJX.js +26 -0
  12. package/dist/pack.d.ts +2 -2
  13. package/dist/pack.js +1 -1
  14. package/dist/pg-edges-store-Lxsl5ZnK.js +381 -0
  15. package/dist/{plugin-BuQQEzL-.js → plugin-CtwOINCM.js} +171 -18
  16. package/dist/proposals-bootstrap.js +6 -4
  17. package/dist/proposals.config.schema.json +5 -0
  18. package/dist/proposals.d.ts +15 -4
  19. package/dist/proposals.default-config.json +2 -1
  20. package/dist/proposals.js +2 -2
  21. package/dist/recall-bootstrap.js +13 -4
  22. package/dist/recall.config.schema.json +12 -0
  23. package/dist/recall.d.ts +54 -9
  24. package/dist/recall.js +2 -2
  25. package/dist/{repl-C52wyfMs.js → repl-DqfHelK7.js} +62 -29
  26. package/dist/{row-ByLFE2Wx.d.ts → row-BKKCXIG6.d.ts} +5 -3
  27. package/dist/run-B5dTbZ3g.js +1997 -0
  28. package/dist/{schema-g4FQLr0V.d.ts → schema-DoSc-4ig.d.ts} +44 -7
  29. package/dist/script-C6DSa_Na.js +134 -0
  30. package/dist/sdk.d.ts +90 -12
  31. package/dist/sdk.js +5 -110
  32. package/dist/{src-YXlv_RyL.js → src-5SJ5GEIM.js} +1555 -326
  33. package/dist/{src-DuopV8u7.js → src-7CUSMK66.js} +148 -19
  34. package/dist/{src-zcyUofMJ.js → src-Bi849yhn.js} +39 -15
  35. package/dist/{src-5hVbeiAu.js → src-CqT-QWZ_.js} +697 -57
  36. package/dist/src-CyvV7dCK.js +4333 -0
  37. package/dist/{row-DK7lPZVe.js → src-Da0t6si5.js} +11 -11
  38. package/dist/{src-C4DzaIQZ.js → src-hZb8wfvg.js} +12 -1
  39. package/dist/substrate-admin.js +17 -781
  40. package/dist/substrate.js +4 -5476
  41. package/dist/testing.d.ts +557 -8
  42. package/dist/testing.js +39 -3
  43. package/dist/{ws-C72iVS5T.d.ts → ws-ByZyHk7m.d.ts} +3 -3
  44. package/package.json +21 -20
  45. package/dist/dataset-DOXGRz50.js +0 -1535
  46. package/dist/env-utils-B7SGmoeJ.js +0 -21
  47. package/dist/src-CjEwiKXw.js +0 -2327
@@ -1,6 +1,7 @@
1
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-YXlv_RyL.js";
3
- import { s as requireCapability } from "./row-DK7lPZVe.js";
2
+ import { E as RESERVED_AUTOCRUD_FIELD_NAMES, K as publishSchema, O as field, T as RESERVED_AUTOCRUD_FIELDS, V as resolveIdentity, Vt as ResolverFrameError, Xt as canonicalize$1, _ as assertIndexDecl, d as uuidFromName, dt as JSON_HEADERS, f as migrateFieldValues, j as installAutoCrud, k as autoCrudOptionsOf, l as planServesShape, v as assertOrderedBy, y as defineNamespace } from "./src-5SJ5GEIM.js";
3
+ import { s as requireCapability } from "./src-Da0t6si5.js";
4
+ import "./src-hZb8wfvg.js";
4
5
  import { randomUUID } from "node:crypto";
5
6
 
6
7
  //#region ../../plugins/substrate-proposals/src/capability.ts
@@ -8,6 +9,8 @@ import { randomUUID } from "node:crypto";
8
9
  * Substrate.propose capability policy helper.
9
10
  */
10
11
  const DEFAULT_PROPOSE_CAPABILITY = "substrate.propose";
12
+ /** Changes a type's indexes or natural order (`propose_index`); separate from proposing schema. */
13
+ const DEFAULT_INDEX_CAPABILITY = "substrate.index";
11
14
  /**
12
15
  * Create a policy that requires the given capability to be present in the
13
16
  * request identity. Passing an empty string disables the gate entirely
@@ -19,14 +22,40 @@ function makeProposePolicy(capability = DEFAULT_PROPOSE_CAPABILITY) {
19
22
  if (capability === "") return () => ({ allow: true });
20
23
  return requireCapability(capability);
21
24
  }
25
+ /** TypeProposal fields boot replays as indexes and natural order. */
26
+ const INDEX_FIELDS = ["indexesJson", "orderedByJson"];
22
27
  /**
23
28
  * Writes to the proposal record types need the propose capability: boot
24
29
  * replays every row marked applied, so a row written directly would become
25
- * live schema. Reads stay open to anyone the namespace grant admits.
30
+ * live schema. A write that names a type's indexes or natural order (null, which clears
31
+ * them, included) also needs
32
+ * the index capability, which `propose_index` is gated by. Reads stay open to
33
+ * anyone the namespace grant admits.
26
34
  */
27
- function proposeToWrite(capability = DEFAULT_PROPOSE_CAPABILITY) {
35
+ function proposeToWrite(capability = DEFAULT_PROPOSE_CAPABILITY, indexCapability = DEFAULT_INDEX_CAPABILITY) {
28
36
  const gate = makeProposePolicy(capability);
29
- return (ctx, args) => ctx.operation === "mutate" ? gate(ctx, args) : { allow: true };
37
+ const indexGate = makeProposePolicy(indexCapability);
38
+ return (ctx, args) => {
39
+ if (ctx.operation !== "mutate") return { allow: true };
40
+ const decision = gate(ctx, args);
41
+ const params = args.params ?? {};
42
+ if (!decision.allow || !INDEX_FIELDS.some((f) => f in params)) return decision;
43
+ return indexGate(ctx, args);
44
+ };
45
+ }
46
+ /**
47
+ * `propose_index`'s gate: the index capability in the namespace whose indexes
48
+ * the call changes (`params.namespace`), else in the frame's namespace.
49
+ */
50
+ function makeIndexPolicy(capability = DEFAULT_INDEX_CAPABILITY) {
51
+ const gate = makeProposePolicy(capability);
52
+ return (ctx, args) => {
53
+ const target = args.params?.namespace;
54
+ return gate(typeof target === "string" ? {
55
+ ...ctx,
56
+ namespace: target
57
+ } : ctx, args);
58
+ };
30
59
  }
31
60
 
32
61
  //#endregion
@@ -156,9 +185,9 @@ function parseFieldSpec(json) {
156
185
  if (!SCALAR_TYPES.has(json.type)) throw new Error(`unsupported scalar type: ${String(json.type)}`);
157
186
  const def = {
158
187
  kind: "scalar",
159
- type: json.type,
160
- indexed: json.indexed ?? true
188
+ type: json.type
161
189
  };
190
+ if (json.indexed !== void 0) def.indexed = json.indexed;
162
191
  if (json.nullable !== void 0) def.nullable = json.nullable;
163
192
  if (json.readonly !== void 0) def.readonly = json.readonly;
164
193
  if (json.enum !== void 0) def.enum = json.enum;
@@ -281,7 +310,8 @@ function assertValidFieldSpec(fieldName, spec) {
281
310
  * substrate-proposals namespace definition.
282
311
  *
283
312
  * Defines two types for schema evolution proposals:
284
- * - TypeProposal: proposes a new type (multiple fields at once)
313
+ * - TypeProposal: proposes a new type (multiple fields at once), and holds
314
+ * the indexes and natural order `propose_index` gives it
285
315
  * - FieldProposal: proposes a single field on an existing type
286
316
  *
287
317
  * Both track proposal metadata (proposedBy, proposedAt, reason) and application
@@ -293,8 +323,8 @@ function assertValidFieldSpec(fieldName, spec) {
293
323
  * the propose resolvers, held under a per-name lock (`proposal-lock.ts`), not
294
324
  * by a schema or database constraint.
295
325
  */
296
- function defineProposalTypes(namespace, capability = DEFAULT_PROPOSE_CAPABILITY) {
297
- const policy = proposeToWrite(capability);
326
+ function defineProposalTypes(namespace, capability = DEFAULT_PROPOSE_CAPABILITY, indexCapability = DEFAULT_INDEX_CAPABILITY) {
327
+ const policy = proposeToWrite(capability, indexCapability);
298
328
  return defineNamespace(namespace, {
299
329
  TypeProposal: {
300
330
  policy,
@@ -308,7 +338,22 @@ function defineProposalTypes(namespace, capability = DEFAULT_PROPOSE_CAPABILITY)
308
338
  appliedAt: field.date({ nullable: true }),
309
339
  resultingSchemaVersion: field.string({ nullable: true }),
310
340
  supersededByCode: field.boolean(),
311
- archived: field.boolean()
341
+ archived: field.boolean(),
342
+ /** `IndexDecl[]` as JSON, set by `propose_index add`; null for none. */
343
+ indexesJson: field.string({
344
+ indexed: false,
345
+ nullable: true
346
+ }),
347
+ /** `OrderedBy` as JSON, set by `propose_index orderedBy`; null for the default. */
348
+ orderedByJson: field.string({
349
+ indexed: false,
350
+ nullable: true
351
+ }),
352
+ /** `'small' | 'large'`, the proposer's size hint for the index advisor; null when none. */
353
+ expectedSize: field.enum(["small", "large"], {
354
+ indexed: false,
355
+ nullable: true
356
+ })
312
357
  }
313
358
  },
314
359
  FieldProposal: {
@@ -375,10 +420,13 @@ function assertValidFieldProposal(targetType, fieldName, fieldSpec, ownsTarget)
375
420
  }
376
421
  /** Installs the proposed type's autoCRUD surface into `registry`. */
377
422
  function installProposedType(registry, args) {
423
+ installAutoCrud(registry, args.typeName, args.dataset, args.edges, { fields: proposedFieldDefs(args.fields) });
424
+ }
425
+ /** A proposed type's field specs as FieldDefs, with the engine-reserved fields added. */
426
+ function proposedFieldDefs(fields) {
378
427
  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 });
428
+ for (const [name, spec] of Object.entries(fields)) fieldDefs[name] = parseFieldSpec(spec);
429
+ return Object.assign(fieldDefs, RESERVED_AUTOCRUD_FIELDS);
382
430
  }
383
431
  /**
384
432
  * Every registry key `applyTypeProposal` would register for this proposal —
@@ -405,6 +453,94 @@ function applyTypeProposal(args) {
405
453
  binding.invalidateSchemaCaches?.();
406
454
  }
407
455
  /**
456
+ * Parses a TypeProposal row's `indexesJson` / `orderedByJson` / `expectedSize`
457
+ * (null or absent: none). An `expectedSize` other than `small` or `large` is
458
+ * left out and handed to `onInvalidSize`, so a bad hint never costs the type
459
+ * its indexes or order.
460
+ */
461
+ function typeIndexOptionsOf(row, onInvalidSize) {
462
+ const parse = (v) => typeof v === "string" ? JSON.parse(v) : void 0;
463
+ const indexes = parse(row.indexesJson);
464
+ const orderedBy = parse(row.orderedByJson);
465
+ const size = row.expectedSize ?? void 0;
466
+ const expectedSize = size === "small" || size === "large" ? size : void 0;
467
+ 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`));
468
+ return {
469
+ ...indexes !== void 0 ? { indexes } : {},
470
+ ...orderedBy !== void 0 ? { orderedBy } : {},
471
+ ...expectedSize !== void 0 ? { expectedSize } : {}
472
+ };
473
+ }
474
+ /**
475
+ * Refuse indexes or a natural order `propose_index` would not accept: each
476
+ * index as code may declare it, but never unique and never named (a name
477
+ * adopts whatever index already holds it), so every one is the engine's own,
478
+ * non-unique and generated. Rows are caller-written, so replay checks too.
479
+ *
480
+ * @throws Error naming the first problem
481
+ */
482
+ function assertValidTypeIndexOptions(typeName, fields, opts) {
483
+ if (opts.indexes !== void 0 && !Array.isArray(opts.indexes)) throw new Error(`indexes on ${typeName} must be an array`);
484
+ for (const decl of opts.indexes ?? []) {
485
+ if (typeof decl !== "object" || decl === null) throw new Error(`index on ${typeName}: must be an object`);
486
+ assertIndexDecl(typeName, fields, decl);
487
+ if (decl.unique !== void 0) throw new Error(`index on ${typeName}: a proposed index is never unique`);
488
+ if (decl.name !== void 0) throw new Error(`index on ${typeName}: a proposed index takes a generated name`);
489
+ }
490
+ if (opts.orderedBy !== void 0) assertOrderedBy(typeName, {
491
+ fields,
492
+ orderedBy: opts.orderedBy
493
+ });
494
+ if (opts.expectedSize !== void 0 && opts.expectedSize !== "small" && opts.expectedSize !== "large") throw new Error(`expectedSize on ${typeName} must be 'small' or 'large'`);
495
+ }
496
+ /**
497
+ * Reinstall `typeName`'s autoCRUD surface with `patch` over the options it was
498
+ * installed with (policy, postWrite, purge, indexes, order), swapping every
499
+ * entry through `registry.replace` so DuplicateRegistration is never thrown.
500
+ */
501
+ function reinstallType(registry, typeName, dataset, edges, patch) {
502
+ const existing = registry.get(typeName);
503
+ if (!existing) throw new Error(`type '${typeName}' not registered`);
504
+ const replaceWriter = {
505
+ register: (key, input) => registry.replace(key, input),
506
+ replace: registry.replace.bind(registry)
507
+ };
508
+ const prior = autoCrudOptionsOf(existing.resolver) ?? {
509
+ policy: existing.policy,
510
+ fields: existing.fields
511
+ };
512
+ installAutoCrud(replaceWriter, typeName, dataset, edges, patch(prior));
513
+ }
514
+ /**
515
+ * Give a registered proposed type the indexes and natural order its row
516
+ * stores, validated against the fields it has now (proposed ones included).
517
+ * Storage builds them on the next `ensureTypeStorage`.
518
+ */
519
+ function applyTypeIndexOptions(args) {
520
+ const binding = args.registryStore.getBinding(args.namespace);
521
+ const existing = binding.registry.get(args.typeName);
522
+ if (!existing) throw new Error(`type '${args.typeName}' not registered`);
523
+ assertValidTypeIndexOptions(args.typeName, existing.fields, args);
524
+ reinstallType(binding.registry, args.typeName, args.dataset, args.edges, (prior) => {
525
+ const { indexes: _i, orderedBy: _o, expectedSize: _s, ...rest } = prior;
526
+ return {
527
+ ...rest,
528
+ ...args.indexes !== void 0 ? { indexes: args.indexes } : {},
529
+ ...args.orderedBy !== void 0 ? { orderedBy: args.orderedBy } : {},
530
+ ...args.expectedSize !== void 0 ? { expectedSize: args.expectedSize } : {}
531
+ };
532
+ });
533
+ binding.invalidateSchemaCaches?.();
534
+ }
535
+ /** Whether the type entry already carries exactly these options. */
536
+ function hasTypeIndexOptions(entry, opts) {
537
+ return sameJson(entry.indexes, opts.indexes) && sameJson(entry.orderedBy, opts.orderedBy) && entry.expectedSize === opts.expectedSize;
538
+ }
539
+ /** Deep equality of JSON values, whatever order their keys were written in. */
540
+ function sameJson(a, b) {
541
+ return JSON.stringify(canonicalize$1(a)) === JSON.stringify(canonicalize$1(b));
542
+ }
543
+ /**
408
544
  * Extend an already-registered type with a new field.
409
545
  *
410
546
  * Replaces the type entry + all autoCRUD mutations atomically with versions
@@ -419,36 +555,34 @@ function applyFieldProposal(args) {
419
555
  const store = args.registryStore;
420
556
  assertValidFieldProposal(args.targetType, args.fieldName, args.fieldSpec, (ns) => store.ownsNamespace(ns));
421
557
  const binding = store.getBinding(args.namespace);
422
- const registry = binding.registry;
423
- const existing = registry.get(args.targetType);
558
+ const existing = binding.registry.get(args.targetType);
424
559
  if (!existing) throw new Error(`applyFieldProposal: target type '${args.targetType}' not registered`);
425
560
  const nextFields = {
426
561
  ...existing.fields,
427
562
  [args.fieldName]: parseFieldSpec(args.fieldSpec)
428
563
  };
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, {
564
+ reinstallType(binding.registry, args.targetType, args.dataset, args.edges, (prior) => ({
435
565
  ...prior,
436
566
  fields: nextFields
437
- });
567
+ }));
438
568
  binding.invalidateSchemaCaches?.();
439
569
  }
440
570
 
441
571
  //#endregion
442
572
  //#region ../../plugins/substrate-proposals/src/engine-write.ts
443
573
  /**
574
+ * Shared helpers used by the propose_* resolvers.
575
+ */
576
+ /**
444
577
  * Run the autoCRUD create-or-update `op` registered on `registry` inside the
445
578
  * caller's own transaction (`args.dataset`), and return the resulting row.
446
579
  * A nested `engine.mutate` would open a second transaction, and so take a
447
580
  * second pooled connection, beside the one the proposal already holds.
448
581
  *
449
- * @throws Error when `op` is not registered, its policy denies, or it returns no row
582
+ * @throws ResolverFrameError `policy_denied` when its policy denies
583
+ * @throws Error when `op` is not registered or returns no row
450
584
  */
451
- async function writeInTx(registry, ctx, args, op, params) {
585
+ async function writeInTx(registry, ctx, args, op, params, skipPolicy = false) {
452
586
  const entry = registry.get(op);
453
587
  if (entry === void 0) throw new Error(`'${op}' is not registered`);
454
588
  const opCtx = {
@@ -461,8 +595,8 @@ async function writeInTx(registry, ctx, args, op, params) {
461
595
  params,
462
596
  fields: { id: true }
463
597
  };
464
- const decision = entry.policy?.(opCtx, opArgs);
465
- if (decision !== void 0 && !decision.allow) throw new Error(`'${op}' denied: ${decision.reason ?? "policy denied"}`);
598
+ const decision = skipPolicy ? void 0 : entry.policy?.(opCtx, opArgs);
599
+ if (decision !== void 0 && !decision.allow) throw new ResolverFrameError("policy_denied", `'${op}' denied: ${decision.reason ?? "policy denied"}`);
466
600
  const row = await entry.resolver(opCtx, opArgs);
467
601
  if (row === null || typeof row !== "object" || Array.isArray(row)) throw new Error(`'${op}' returned no row`);
468
602
  return row;
@@ -511,6 +645,46 @@ async function notifyAfterCommit(args, notify) {
511
645
  if (committed) await notify();
512
646
  });
513
647
  }
648
+ const pendingStorage = /* @__PURE__ */ new Set();
649
+ /** Resolves once every storage preparation started so far has settled. */
650
+ async function storageSettled() {
651
+ await Promise.all([...pendingStorage]);
652
+ }
653
+ function prepareStorage(dataset, type, scope) {
654
+ if (scope?.signal.aborted === true) return;
655
+ const work = (async () => {
656
+ try {
657
+ await dataset.ensureTypeStorage?.(type, scope ? { signal: scope.signal } : void 0);
658
+ } catch (err) {
659
+ process.stderr.write(`[substrate-proposals] storage for ${dataset.namespace}/${type} not prepared: ${err instanceof Error ? err.message : String(err)}\n`);
660
+ }
661
+ })();
662
+ pendingStorage.add(work);
663
+ scope?.pending.add(work);
664
+ work.finally(() => {
665
+ pendingStorage.delete(work);
666
+ scope?.pending.delete(work);
667
+ });
668
+ }
669
+ /**
670
+ * Starts preparing `type`'s storage on the namespace's base `dataset` once the
671
+ * caller's transaction has committed (at once when there is none), never
672
+ * inside it: index builds run CONCURRENTLY and would wait forever on it. It
673
+ * runs in the background, because the lock waits and index builds have no
674
+ * bound and must not hold the caller's response; rows written meanwhile land
675
+ * in the DEFAULT partition and are moved. A failure is logged and never
676
+ * undoes the committed proposal; the next boot or proposal retries.
677
+ * {@link storageSettled} awaits it; `scope`'s signal aborts it.
678
+ */
679
+ function ensureStorageAfterCommit(afterTx, dataset, type, scope) {
680
+ if (afterTx === void 0) {
681
+ prepareStorage(dataset, type, scope);
682
+ return;
683
+ }
684
+ afterTx(async ({ committed }) => {
685
+ if (committed) prepareStorage(dataset, type, scope);
686
+ });
687
+ }
514
688
 
515
689
  //#endregion
516
690
  //#region ../../plugins/substrate-proposals/src/proposal-lock.ts
@@ -637,9 +811,7 @@ async function proposeNamespaceLocked(deps, ctx, args, input) {
637
811
  let proposalId;
638
812
  if (prior !== void 0) proposalId = String(prior.id);
639
813
  else {
640
- proposalId = randomUUID();
641
- await writeInTx(controlBinding.registry, ctx, args, "createNamespaceProposal", {
642
- id: proposalId,
814
+ const created = await writeInTx(controlBinding.registry, ctx, args, "createNamespaceProposal", {
643
815
  ns,
644
816
  proposedBy,
645
817
  proposedAt: /* @__PURE__ */ new Date(),
@@ -649,6 +821,7 @@ async function proposeNamespaceLocked(deps, ctx, args, input) {
649
821
  supersededByCode: false,
650
822
  archived: false
651
823
  });
824
+ proposalId = String(created.id);
652
825
  }
653
826
  try {
654
827
  installHotAddedNamespace({
@@ -658,6 +831,7 @@ async function proposeNamespaceLocked(deps, ctx, args, input) {
658
831
  engine: controlEngine,
659
832
  edges: deps.edges,
660
833
  ...deps.proposeCapability !== void 0 && { proposeCapability: deps.proposeCapability },
834
+ ...deps.indexCapability !== void 0 && { indexCapability: deps.indexCapability },
661
835
  ...deps.registerProposalMutations !== void 0 && { registerProposalMutations: deps.registerProposalMutations }
662
836
  });
663
837
  } finally {
@@ -729,17 +903,23 @@ async function applyProposalFromNotification(args) {
729
903
  const typeHit = await binding.dataset.read("TypeProposal", { id: args.proposalId });
730
904
  if (typeHit.rows.length > 0) {
731
905
  const row = typeHit.rows[0];
732
- if (row.applied === true && !binding.registry.get(row.typeName)) {
906
+ if (row.applied !== true) return;
907
+ const typeName = row.typeName;
908
+ let changed = false;
909
+ if (!binding.registry.get(typeName)) {
733
910
  const fields = JSON.parse(row.fieldsJson);
734
911
  applyTypeProposal({
735
912
  namespace: args.namespace,
736
- typeName: row.typeName,
913
+ typeName,
737
914
  fields,
738
915
  registryStore: args.registryStore,
739
916
  dataset: binding.dataset,
740
917
  edges: binding.edges
741
918
  });
919
+ changed = true;
742
920
  }
921
+ changed = replayTypeIndexOptions(args.registryStore, args.namespace, row) || changed;
922
+ if (changed) ensureStorageAfterCommit(void 0, binding.dataset, typeName, args.registryStore.storage);
743
923
  return;
744
924
  }
745
925
  const fieldHit = await binding.dataset.read("FieldProposal", { id: args.proposalId });
@@ -758,11 +938,33 @@ async function applyProposalFromNotification(args) {
758
938
  dataset: binding.dataset,
759
939
  edges: binding.edges
760
940
  });
941
+ ensureStorageAfterCommit(void 0, binding.dataset, row.targetType, args.registryStore.storage);
761
942
  }
762
943
  }
763
944
  }
764
945
  }
765
946
  /**
947
+ * Bring a registered proposed type's indexes and natural order in line with
948
+ * its row. False when they already match (or the type is not registered).
949
+ *
950
+ * @throws when the row's options are malformed or invalid for the type
951
+ */
952
+ function replayTypeIndexOptions(registryStore, namespace, row, onSkip) {
953
+ const binding = registryStore.getBinding(namespace);
954
+ const entry = binding.registry.get(row.typeName);
955
+ const opts = typeIndexOptionsOf(row, (err) => onSkip?.(row, err));
956
+ if (entry === void 0 || hasTypeIndexOptions(entry, opts)) return false;
957
+ applyTypeIndexOptions({
958
+ namespace,
959
+ typeName: row.typeName,
960
+ ...opts,
961
+ registryStore,
962
+ dataset: binding.dataset,
963
+ edges: binding.edges
964
+ });
965
+ return true;
966
+ }
967
+ /**
766
968
  * A field proposal needs replaying when its field is absent, or when it
767
969
  * narrowed an enum: the type was registered with the wider spec, and the
768
970
  * narrowing exists only in the proposal row.
@@ -780,6 +982,7 @@ async function reconcileNamespace(args) {
780
982
  ] },
781
983
  limit: 1e4
782
984
  });
985
+ const prepare = /* @__PURE__ */ new Set();
783
986
  for (const row of typeRows.rows) {
784
987
  if (binding.registry.get(row.typeName)) continue;
785
988
  try {
@@ -794,7 +997,9 @@ async function reconcileNamespace(args) {
794
997
  });
795
998
  } catch (err) {
796
999
  args.onSkip?.(row, err);
1000
+ continue;
797
1001
  }
1002
+ prepare.add(row.typeName);
798
1003
  }
799
1004
  const fieldRows = await binding.dataset.read("FieldProposal", {
800
1005
  where: { AND: [
@@ -821,8 +1026,16 @@ async function reconcileNamespace(args) {
821
1026
  });
822
1027
  } catch (err) {
823
1028
  args.onSkip?.(row, err);
1029
+ continue;
824
1030
  }
1031
+ prepare.add(row.targetType);
1032
+ }
1033
+ for (const row of typeRows.rows) try {
1034
+ if (replayTypeIndexOptions(args.registryStore, args.namespace, row, args.onSkip)) prepare.add(row.typeName);
1035
+ } catch (err) {
1036
+ args.onSkip?.(row, err);
825
1037
  }
1038
+ for (const type of prepare) ensureStorageAfterCommit(void 0, binding.dataset, type, args.registryStore.storage);
826
1039
  }
827
1040
  /**
828
1041
  * Shared install path for a hot-added namespace. Three call sites use this:
@@ -859,7 +1072,7 @@ function installHotAddedNamespace(args) {
859
1072
  args.registryStore.set(args.ns, binding);
860
1073
  }
861
1074
  const registry = skipRegistered(binding.registry);
862
- defineProposalTypes(args.ns, args.proposeCapability).install({
1075
+ defineProposalTypes(args.ns, args.proposeCapability, args.indexCapability).install({
863
1076
  registry,
864
1077
  dataset: binding.dataset,
865
1078
  edges: binding.edges
@@ -927,6 +1140,7 @@ async function setupClusterNamespaceListener(args) {
927
1140
  engine: args.engine,
928
1141
  edges: args.edges,
929
1142
  ...args.proposeCapability !== void 0 && { proposeCapability: args.proposeCapability },
1143
+ ...args.indexCapability !== void 0 && { indexCapability: args.indexCapability },
930
1144
  ...args.registerProposalMutations !== void 0 && { registerProposalMutations: args.registerProposalMutations }
931
1145
  });
932
1146
  } catch (err) {
@@ -973,6 +1187,7 @@ async function reconcileClusterNamespaces(args) {
973
1187
  engine: args.engine,
974
1188
  edges: args.edges,
975
1189
  ...args.proposeCapability !== void 0 && { proposeCapability: args.proposeCapability },
1190
+ ...args.indexCapability !== void 0 && { indexCapability: args.indexCapability },
976
1191
  ...args.registerProposalMutations !== void 0 && { registerProposalMutations: args.registerProposalMutations }
977
1192
  });
978
1193
  } catch (err) {
@@ -1107,7 +1322,10 @@ function buildOnboardBody(ownedNamespaces) {
1107
1322
  params: {
1108
1323
  typeName: "string — PascalCase, unique within the namespace",
1109
1324
  fields: "object — FieldSpecJson map keyed by camelCase field name (see fieldSpecJson below)",
1110
- proposedReason: "string — short human-readable rationale"
1325
+ proposedReason: "string — short human-readable rationale",
1326
+ 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.",
1327
+ 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.",
1328
+ expectedSize: "optional \"small\"|\"large\" — \"large\" gets index advice sooner"
1111
1329
  },
1112
1330
  returns: {
1113
1331
  id: "uuid — the TypeProposal record id",
@@ -1147,7 +1365,7 @@ function buildOnboardBody(ownedNamespaces) {
1147
1365
  variants: {
1148
1366
  scalar: {
1149
1367
  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."
1368
+ 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. 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
1369
  },
1152
1370
  crossRef: {
1153
1371
  shape: "{ kind: \"crossRef\", ns: string, type: string, onDelete?: \"set_null\"|\"cascade\"|\"restrict\"|\"orphan\", indexed?: bool, nullable?: bool }",
@@ -1166,7 +1384,7 @@ function buildOnboardBody(ownedNamespaces) {
1166
1384
  constraints: [
1167
1385
  "AutoCRUD-only: every proposed type gets the standard create/get/update/delete/list surface. No custom resolvers — those require code.",
1168
1386
  "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.",
1387
+ "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
1388
  "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
1389
  `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
1390
  "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."
@@ -1356,9 +1574,7 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1356
1574
  }, suppliedMap, { oldVocabulary: oldEnum });
1357
1575
  }
1358
1576
  const proposedAt = /* @__PURE__ */ new Date();
1359
- const newId = randomUUID();
1360
1577
  const initialParams = {
1361
- id: newId,
1362
1578
  targetType,
1363
1579
  fieldName,
1364
1580
  fieldSpecJson: JSON.stringify(fieldSpec),
@@ -1373,8 +1589,8 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1373
1589
  archived: false
1374
1590
  };
1375
1591
  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]);
1592
+ const newId = engine !== void 0 ? (await writeInTx(binding.registry, ctx, args, "createFieldProposal", initialParams)).id : (await args.dataset.write("FieldProposal", [initialParams])).ids[0];
1593
+ if (newId === void 0) throw new Error("dataset.write did not return an id for FieldProposal");
1378
1594
  try {
1379
1595
  applyUntilRollback(args, binding.registry, () => applyFieldProposal({
1380
1596
  namespace: deps.namespace,
@@ -1410,6 +1626,7 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1410
1626
  await args.dataset.write("FieldProposal", [appliedRow]);
1411
1627
  }
1412
1628
  await notifyAfterCommit(args, () => deps.pubsub.notify(deps.channelFor(deps.namespace), String(newId)));
1629
+ ensureStorageAfterCommit(args.afterTx, deps.dataset, targetType, deps.registryStore.storage);
1413
1630
  if (migration === null) return appliedRow;
1414
1631
  const { ids: _written, ...summary } = migration;
1415
1632
  return {
@@ -1418,6 +1635,338 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1418
1635
  };
1419
1636
  }
1420
1637
 
1638
+ //#endregion
1639
+ //#region ../../plugins/substrate-proposals/src/propose-index-resolver.ts
1640
+ /**
1641
+ * Factory for the `propose_index` mutation resolver: the signed approval of an
1642
+ * index recommendation, or a direct index change, under the index capability.
1643
+ *
1644
+ * - `add` appends a declared index to a proposed type's TypeProposal row and
1645
+ * reinstalls the type; storage builds it in the background after commit.
1646
+ * - `orderedBy` sets a proposed type's natural order the same way, and storage
1647
+ * swaps its derived indexes.
1648
+ * - `remove` drops an engine-owned, non-unique index the engine no longer
1649
+ * wants, on any type (`Dataset.dropEngineIndex`, which re-checks it live).
1650
+ * An index wanted only because a proposed type's `indexesJson` declares it
1651
+ * is retracted first: the declaration leaves the row, peers are told, and
1652
+ * the index is dropped.
1653
+ * - `dismiss` closes a recommendation without acting on it.
1654
+ *
1655
+ * A referenced `_system/IndexRecommendation` must be `open`, and moves to
1656
+ * `accepted` or `dismissed` by a conditional update from `open`, claimed
1657
+ * before the audit event and the effect and given back (to `open`) if the
1658
+ * effect fails, so a caller never learns it was closed after its own effect. Its rows are
1659
+ * writable by any index-capability holder, so nothing in one is trusted: an
1660
+ * `add` must still be unserved by the type's index plan (as the advisor's
1661
+ * supersede pass decides) and its declaration validates as a direct one does;
1662
+ * `remove` is checked against the catalog. When that evidence no longer
1663
+ * holds the call is refused `recommendation_stale` and the row superseded.
1664
+ *
1665
+ * Every write here goes through the namespaces' base datasets, outside the
1666
+ * caller's transaction: a `DROP INDEX CONCURRENTLY` cannot run beside it, and
1667
+ * a superseded mark must outlive the refusal that rolls the transaction back.
1668
+ * Each one is stamped with the caller's identity.
1669
+ *
1670
+ * Audit: every applied call writes one `_system/AuditEvent` (`index_proposed`)
1671
+ * once its checks have passed and before its first effect (for a drop, under
1672
+ * the table lock, just before `DROP INDEX`), so no effect lands unaudited. For
1673
+ * a recommendation the event's id derives from the recommendation's, written
1674
+ * insert-only, so a retry after a partial failure converges without a second
1675
+ * event.
1676
+ */
1677
+ const SYSTEM_NAMESPACE = "_system";
1678
+ const RECOMMENDATION_TYPE = "IndexRecommendation";
1679
+ const ACTIONS = [
1680
+ "add",
1681
+ "remove",
1682
+ "dismiss",
1683
+ "orderedBy"
1684
+ ];
1685
+ /** `dropEngineIndex` refusal codes, passed through as the call's own. */
1686
+ const DROP_REFUSALS = /* @__PURE__ */ new Set([
1687
+ "unknown_index",
1688
+ "not_engine_owned",
1689
+ "unique_index",
1690
+ "still_desired",
1691
+ "index_drop_timeout"
1692
+ ]);
1693
+ /** A read row without the engine fields reads add (`shortId`), for writing back. */
1694
+ function bodyOf(row) {
1695
+ const body = { ...row };
1696
+ for (const name of RESERVED_AUTOCRUD_FIELD_NAMES) delete body[name];
1697
+ return body;
1698
+ }
1699
+ function invalid(param, message) {
1700
+ return new ProposalError("invalid_params", message, { param });
1701
+ }
1702
+ function closed(id, state) {
1703
+ return new ProposalError("recommendation_closed", `index recommendation '${String(id)}' is no longer open${state === void 0 ? "" : ` (${String(state)})`}`, state === void 0 ? {} : { state });
1704
+ }
1705
+ function parseInput$1(params) {
1706
+ for (const key of [
1707
+ "namespace",
1708
+ "type",
1709
+ "reason"
1710
+ ]) if (typeof params[key] !== "string" || key !== "reason" && params[key] === "") throw invalid(key, `'${key}' must be a${key === "reason" ? "" : " non-empty"} string`);
1711
+ if (!ACTIONS.includes(params.action)) throw invalid("action", `'action' must be one of ${ACTIONS.join(", ")}`);
1712
+ for (const key of ["recommendationId", "indexName"]) if (params[key] !== void 0 && typeof params[key] !== "string") throw invalid(key, `'${key}' must be a string`);
1713
+ return params;
1714
+ }
1715
+ function makeProposeIndexResolver(deps) {
1716
+ return async (ctx, args) => {
1717
+ 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 });
1718
+ const input = parseInput$1(args.params ?? {});
1719
+ const lockOn = deps.datasetFor(SYSTEM_NAMESPACE) ?? args.dataset;
1720
+ const run = () => proposeIndex(deps, ctx, args, input);
1721
+ if (lockOn === void 0) return run();
1722
+ return withProposalLock(lockOn, proposalLockKey("index", input.namespace, input.type), run);
1723
+ };
1724
+ }
1725
+ async function proposeIndex(deps, ctx, args, input) {
1726
+ const identity = resolveIdentity(ctx);
1727
+ const system = deps.datasetFor(SYSTEM_NAMESPACE);
1728
+ const now = /* @__PURE__ */ new Date();
1729
+ const rec = input.recommendationId === void 0 ? void 0 : await openRecommendation();
1730
+ async function openRecommendation() {
1731
+ const id = input.recommendationId;
1732
+ const row = system === void 0 ? void 0 : (await system.read(RECOMMENDATION_TYPE, {
1733
+ id,
1734
+ limit: 1
1735
+ })).rows[0];
1736
+ if (row === void 0) throw new ProposalError("unknown_recommendation", `no index recommendation '${id}'`);
1737
+ if (row.state !== "open") throw closed(id, row.state);
1738
+ if (row.namespace !== input.namespace || row.type !== input.type) throw invalid("recommendationId", `recommendation '${id}' is for ${row.namespace}/${row.type}`);
1739
+ if (input.action !== "dismiss" && row.action !== input.action) throw invalid("action", `recommendation '${id}' recommends '${String(row.action)}'`);
1740
+ return row;
1741
+ }
1742
+ const auditId = rec === void 0 ? randomUUID() : uuidFromName(`index_proposed:${String(rec.id)}`);
1743
+ let audited;
1744
+ const audit = async (detail) => {
1745
+ if (audited !== void 0) return;
1746
+ audited = detail;
1747
+ await system?.write("AuditEvent", [{
1748
+ id: auditId,
1749
+ ts: now.toISOString(),
1750
+ actorKid: identity.id,
1751
+ kind: "index_proposed",
1752
+ targetKid: `${input.namespace}/${input.type}`,
1753
+ clientIp: null,
1754
+ details: {
1755
+ action: input.action,
1756
+ reason: input.reason,
1757
+ recommendationId: rec?.id ?? null,
1758
+ ...detail
1759
+ }
1760
+ }], {
1761
+ identity,
1762
+ now,
1763
+ insertOnly: true
1764
+ });
1765
+ };
1766
+ /** Moves the recommendation (if any) from `open` to `state`, atomically. */
1767
+ const close = async (state) => {
1768
+ if (rec === void 0 || system === void 0) return;
1769
+ const { matched } = await system.conditionalUpdate(RECOMMENDATION_TYPE, rec.id, { state: "open" }, { state }, identity, now);
1770
+ if (!matched) throw closed(rec.id);
1771
+ };
1772
+ let claimed;
1773
+ const claim = async (state) => {
1774
+ await close(state);
1775
+ if (rec !== void 0 && system !== void 0) claimed = state;
1776
+ };
1777
+ /** Gives a claim back (claimed → open) when the work behind it failed. */
1778
+ const release = async () => {
1779
+ const state = claimed;
1780
+ if (state === void 0 || rec === void 0 || system === void 0) return;
1781
+ claimed = void 0;
1782
+ const fail = (why) => {
1783
+ process.stderr.write(`[substrate-proposals] index recommendation ${String(rec.id)} stays ${state} after a failed ${input.action}: ${why}\n`);
1784
+ };
1785
+ try {
1786
+ const { matched } = await system.conditionalUpdate(RECOMMENDATION_TYPE, rec.id, { state }, { state: "open" }, identity, now);
1787
+ if (!matched) fail("it was changed meanwhile");
1788
+ } catch (err) {
1789
+ fail(err instanceof Error ? err.message : String(err));
1790
+ }
1791
+ };
1792
+ const stale = async (reason, code) => {
1793
+ await release();
1794
+ await close("superseded");
1795
+ throw new ProposalError("recommendation_stale", `index recommendation '${String(rec?.id)}' no longer holds: ${reason}`, code !== void 0 ? { reason: code } : {});
1796
+ };
1797
+ const call = {
1798
+ deps,
1799
+ args,
1800
+ input,
1801
+ identity,
1802
+ rec,
1803
+ audit,
1804
+ stale,
1805
+ claim,
1806
+ release
1807
+ };
1808
+ try {
1809
+ switch (input.action) {
1810
+ case "dismiss":
1811
+ if (rec === void 0) throw invalid("recommendationId", "'dismiss' needs a recommendationId");
1812
+ await claim("dismissed");
1813
+ await audit({});
1814
+ break;
1815
+ case "remove":
1816
+ await removeIndex(call, system, auditId);
1817
+ break;
1818
+ case "add":
1819
+ case "orderedBy": await changeProposedType(call);
1820
+ }
1821
+ } catch (err) {
1822
+ await release();
1823
+ throw err;
1824
+ }
1825
+ return {
1826
+ id: auditId,
1827
+ action: input.action,
1828
+ namespace: input.namespace,
1829
+ type: input.type,
1830
+ recommendationId: rec?.id ?? null,
1831
+ indexName: audited?.indexName ?? null
1832
+ };
1833
+ }
1834
+ /** The applied, live TypeProposal row of `type`, or undefined (a code-defined type). */
1835
+ async function proposalOf(binding, type) {
1836
+ return (await binding.dataset.read("TypeProposal", {
1837
+ where: { AND: [
1838
+ { typeName: { eq: type } },
1839
+ { applied: { eq: true } },
1840
+ { supersededByCode: { eq: false } },
1841
+ { archived: { eq: false } }
1842
+ ] },
1843
+ limit: 1
1844
+ })).rows[0];
1845
+ }
1846
+ /**
1847
+ * Stores `next` on the proposal row, reinstalls the type with it, and tells
1848
+ * peers once the caller's transaction commits.
1849
+ */
1850
+ async function storeTypeIndexOptions(call, binding, proposal, next) {
1851
+ const { deps, args, input, identity } = call;
1852
+ const { indexes: all, ...rest } = next;
1853
+ const opts = {
1854
+ ...rest,
1855
+ ...all?.length ? { indexes: all } : {}
1856
+ };
1857
+ await binding.dataset.write("TypeProposal", [{
1858
+ ...bodyOf(proposal),
1859
+ indexesJson: opts.indexes !== void 0 ? JSON.stringify(opts.indexes) : null,
1860
+ orderedByJson: opts.orderedBy !== void 0 ? JSON.stringify(opts.orderedBy) : null
1861
+ }], { identity });
1862
+ applyTypeIndexOptions({
1863
+ namespace: input.namespace,
1864
+ typeName: input.type,
1865
+ ...opts,
1866
+ registryStore: deps.registryStore,
1867
+ dataset: binding.dataset,
1868
+ edges: binding.edges
1869
+ });
1870
+ await notifyAfterCommit(args, () => deps.pubsub.notify(deps.channelFor(input.namespace), String(proposal.id)));
1871
+ }
1872
+ /** `remove`: retract a proposed declaration if that is all that wants it, then drop. */
1873
+ async function removeIndex(call, system, auditId) {
1874
+ const { deps, input, rec } = call;
1875
+ const name = input.indexName ?? rec?.indexName ?? void 0;
1876
+ if (name === void 0) throw invalid("indexName", "'remove' needs an indexName");
1877
+ const dataset = deps.datasetFor(input.namespace) ?? system?.forNamespace(input.namespace);
1878
+ await call.claim("accepted");
1879
+ if (rec === void 0 && dataset?.indexDeclarationOf !== void 0) {
1880
+ const binding = deps.registryStore.ownsNamespace(input.namespace) ? deps.registryStore.getBinding(input.namespace) : void 0;
1881
+ const proposal = binding === void 0 ? void 0 : await proposalOf(binding, input.type);
1882
+ const decl = proposal === void 0 ? void 0 : await dataset.indexDeclarationOf(input.type, name);
1883
+ const current = proposal === void 0 ? {} : typeIndexOptionsOf(proposal);
1884
+ const kept = (current.indexes ?? []).filter((d) => !sameJson(d, decl));
1885
+ if (binding !== void 0 && proposal !== void 0 && decl !== void 0 && kept.length < (current.indexes ?? []).length) {
1886
+ await call.audit({
1887
+ indexName: name,
1888
+ retracted: decl
1889
+ });
1890
+ await storeTypeIndexOptions(call, binding, proposal, {
1891
+ ...current,
1892
+ indexes: kept
1893
+ });
1894
+ }
1895
+ }
1896
+ try {
1897
+ if (dataset?.dropEngineIndex === void 0) throw Object.assign(/* @__PURE__ */ new Error(`no index ${name} on ${input.namespace}/${input.type}`), { code: "unknown_index" });
1898
+ await dataset.dropEngineIndex(input.type, name, { beforeDrop: () => call.audit({ indexName: name }) });
1899
+ } catch (err) {
1900
+ const code = err.code;
1901
+ if (typeof code !== "string" || !DROP_REFUSALS.has(code)) throw err;
1902
+ const message = err instanceof Error ? err.message : String(err);
1903
+ if (rec !== void 0 && code !== "index_drop_timeout") {
1904
+ if (code === "unknown_index" && (await system?.read("AuditEvent", {
1905
+ id: auditId,
1906
+ limit: 1
1907
+ }))?.rows[0] !== void 0) return;
1908
+ await call.stale(message, code);
1909
+ }
1910
+ await call.release();
1911
+ throw new ProposalError(code, message, { indexName: name });
1912
+ }
1913
+ }
1914
+ /** `add` or `orderedBy` on a proposed type: update its row, then its registry entry. */
1915
+ async function changeProposedType(call) {
1916
+ const { deps, args, input, rec, stale } = call;
1917
+ const { namespace: ns, type } = input;
1918
+ 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 });
1919
+ if (!deps.registryStore.ownsNamespace(ns)) throw codeDefined();
1920
+ const binding = deps.registryStore.getBinding(ns);
1921
+ const entry = binding.registry.get(type);
1922
+ if (entry?.kind !== "type") throw new ProposalError("unknown_type", `no type '${type}' in namespace '${ns}'`);
1923
+ const proposal = await proposalOf(binding, type);
1924
+ if (proposal === void 0) throw codeDefined();
1925
+ const current = typeIndexOptionsOf(proposal);
1926
+ let next;
1927
+ let detail;
1928
+ if (input.action === "add") {
1929
+ let decl = input.declaration;
1930
+ if (decl === void 0 && rec !== void 0) try {
1931
+ decl = JSON.parse(rec.declarationJson);
1932
+ } catch {
1933
+ return stale("its declaration is not JSON");
1934
+ }
1935
+ if (decl === void 0) throw invalid("declaration", "'add' needs a declaration");
1936
+ const indexes = current.indexes ?? [];
1937
+ const known = indexes.some((d) => sameJson(d, decl));
1938
+ if (rec !== void 0 && !known) {
1939
+ const plan = await binding.dataset.indexPlan?.(type, ns) ?? { indexes: [] };
1940
+ const served = planServesShape(plan, String(rec.shape));
1941
+ if (served === void 0) return stale("its read shape does not parse");
1942
+ if (served) return stale("an index the type already has serves its read shape");
1943
+ }
1944
+ next = {
1945
+ ...current,
1946
+ indexes: known ? indexes : [...indexes, decl]
1947
+ };
1948
+ detail = { declaration: decl };
1949
+ } else {
1950
+ if (input.orderedBy === void 0) throw invalid("orderedBy", "'orderedBy' needs an orderedBy");
1951
+ next = {
1952
+ ...current,
1953
+ orderedBy: input.orderedBy
1954
+ };
1955
+ detail = { orderedBy: input.orderedBy };
1956
+ }
1957
+ try {
1958
+ assertValidTypeIndexOptions(type, entry.fields, next);
1959
+ } catch (err) {
1960
+ const message = err instanceof Error ? err.message : String(err);
1961
+ if (rec !== void 0) return stale(message);
1962
+ throw invalid(input.action === "add" ? "declaration" : "orderedBy", message);
1963
+ }
1964
+ await call.claim("accepted");
1965
+ await call.audit(detail);
1966
+ await storeTypeIndexOptions(call, binding, proposal, next);
1967
+ ensureStorageAfterCommit(args.afterTx, binding.dataset, type, deps.registryStore.storage);
1968
+ }
1969
+
1421
1970
  //#endregion
1422
1971
  //#region ../../plugins/substrate-proposals/src/propose-type-resolver.ts
1423
1972
  /**
@@ -1441,6 +1990,8 @@ async function proposeFieldLocked(deps, ctx, args, input) {
1441
1990
  function parseInput(params) {
1442
1991
  const { proposedReason } = params;
1443
1992
  if (proposedReason !== void 0 && typeof proposedReason !== "string") throw new ProposalError("invalid_params", "'proposedReason' must be a string", { param: "proposedReason" });
1993
+ const { expectedSize } = params;
1994
+ if (expectedSize !== void 0 && expectedSize !== "small" && expectedSize !== "large") throw new ProposalError("invalid_params", "'expectedSize' must be 'small' or 'large'", { param: "expectedSize" });
1444
1995
  return {
1445
1996
  ...params,
1446
1997
  proposedReason: proposedReason ?? ""
@@ -1451,6 +2002,11 @@ function makeProposeTypeResolver(deps) {
1451
2002
  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
2003
  const input = parseInput(args.params ?? {});
1453
2004
  assertValidTypeProposal(input.typeName, input.fields, (ns, type) => ns === deps.namespace && type === input.typeName || deps.registryStore.ownsType(ns, type));
2005
+ try {
2006
+ assertValidTypeIndexOptions(input.typeName, proposedFieldDefs(input.fields), indexOptionsOf(input));
2007
+ } catch (cause) {
2008
+ throw new ProposalError("invalid_params", cause instanceof Error ? cause.message : String(cause), {}, { cause });
2009
+ }
1454
2010
  const dataset = args.dataset ?? deps.dataset;
1455
2011
  return withProposalLock(dataset, proposalLockKey("type", deps.namespace, input.typeName), () => proposeTypeLocked(deps, ctx, {
1456
2012
  ...args,
@@ -1458,6 +2014,30 @@ function makeProposeTypeResolver(deps) {
1458
2014
  }, input));
1459
2015
  };
1460
2016
  }
2017
+ function indexOptionsOf(input) {
2018
+ const { indexes, orderedBy, expectedSize } = input;
2019
+ return {
2020
+ ...indexes?.length ? { indexes } : {},
2021
+ ...orderedBy !== void 0 ? { orderedBy } : {},
2022
+ ...expectedSize !== void 0 ? { expectedSize } : {}
2023
+ };
2024
+ }
2025
+ /**
2026
+ * Whether `typeName` has storage already: any TypeProposal row by that name,
2027
+ * or any row of the type, archived and tombstoned ones included, so a
2028
+ * propose-only caller cannot clear the signal by deleting them.
2029
+ */
2030
+ async function hasStorage(dataset, typeName) {
2031
+ if ((await dataset.read("TypeProposal", {
2032
+ where: { typeName: { eq: typeName } },
2033
+ includeDeleted: true,
2034
+ limit: 1
2035
+ })).rows.length > 0) return true;
2036
+ return (await dataset.read(typeName, {
2037
+ includeDeleted: true,
2038
+ limit: 1
2039
+ })).rows.length > 0;
2040
+ }
1461
2041
  /** Steps 2-7, run while holding the proposal lock for this type name. */
1462
2042
  async function proposeTypeLocked(deps, ctx, args, input) {
1463
2043
  const { typeName, fields, proposedReason } = input;
@@ -1483,12 +2063,9 @@ async function proposeTypeLocked(deps, ctx, args, input) {
1483
2063
  }).find((key) => liveRegistry.has(key));
1484
2064
  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
2065
  const proposedAt = /* @__PURE__ */ new Date();
1486
- const fieldsJson = JSON.stringify(fields);
1487
- const newId = randomUUID();
1488
2066
  const initialParams = {
1489
- id: newId,
1490
2067
  typeName,
1491
- fieldsJson,
2068
+ fieldsJson: JSON.stringify(fields),
1492
2069
  proposedBy,
1493
2070
  proposedAt,
1494
2071
  proposedReason,
@@ -1496,22 +2073,56 @@ async function proposeTypeLocked(deps, ctx, args, input) {
1496
2073
  appliedAt: null,
1497
2074
  resultingSchemaVersion: null,
1498
2075
  supersededByCode: false,
1499
- archived: false
2076
+ archived: false,
2077
+ expectedSize: input.expectedSize ?? null
2078
+ };
2079
+ const indexOpts = indexOptionsOf(input);
2080
+ const indexFields = {
2081
+ indexesJson: indexOpts.indexes ? JSON.stringify(indexOpts.indexes) : null,
2082
+ orderedByJson: indexOpts.orderedBy ? JSON.stringify(indexOpts.orderedBy) : null
1500
2083
  };
1501
2084
  const binding = deps.registryStore.getBinding(deps.namespace);
1502
2085
  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");
2086
+ let newId;
2087
+ if (engine !== void 0) {
2088
+ const declaresIndexes = indexOpts.indexes !== void 0 || indexOpts.orderedBy !== void 0;
2089
+ newId = (await writeInTx(binding.registry, ctx, args, "createTypeProposal", {
2090
+ ...initialParams,
2091
+ ...indexFields
2092
+ }, !(declaresIndexes && await hasStorage(args.dataset, typeName)))).id;
2093
+ } else {
2094
+ const id = (await args.dataset.write("TypeProposal", [{
2095
+ ...initialParams,
2096
+ ...indexFields
2097
+ }])).ids[0];
2098
+ if (id === void 0) throw new Error("dataset.write did not return an id for TypeProposal");
2099
+ newId = id;
2100
+ }
1505
2101
  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?.());
2102
+ applyUntilRollback(args, binding.registry, () => {
2103
+ applyTypeProposal({
2104
+ namespace: deps.namespace,
2105
+ typeName,
2106
+ fields,
2107
+ registryStore: deps.registryStore,
2108
+ dataset: deps.dataset,
2109
+ edges: deps.edges
2110
+ });
2111
+ if (Object.keys(indexOpts).length > 0) try {
2112
+ applyTypeIndexOptions({
2113
+ namespace: deps.namespace,
2114
+ typeName,
2115
+ ...indexOpts,
2116
+ registryStore: deps.registryStore,
2117
+ dataset: deps.dataset,
2118
+ edges: deps.edges
2119
+ });
2120
+ } catch (cause) {
2121
+ throw new ProposalError("invalid_params", cause instanceof Error ? cause.message : String(cause), {}, { cause });
2122
+ }
2123
+ }, () => binding.invalidateSchemaCaches?.());
1514
2124
  } catch (cause) {
2125
+ if (cause instanceof ProposalError) throw cause;
1515
2126
  throw new ProposalError("type_already_exists", `Could not apply type '${typeName}': ${cause instanceof Error ? cause.message : String(cause)}`, {}, { cause });
1516
2127
  }
1517
2128
  const now = /* @__PURE__ */ new Date();
@@ -1539,6 +2150,7 @@ async function proposeTypeLocked(deps, ctx, args, input) {
1539
2150
  await args.dataset.write("TypeProposal", [appliedRow]);
1540
2151
  }
1541
2152
  await notifyAfterCommit(args, () => deps.pubsub.notify(deps.channelFor(deps.namespace), String(newId)));
2153
+ ensureStorageAfterCommit(args.afterTx, deps.dataset, typeName, deps.registryStore.storage);
1542
2154
  return appliedRow;
1543
2155
  }
1544
2156
 
@@ -1554,6 +2166,17 @@ async function proposeTypeLocked(deps, ctx, args, input) {
1554
2166
  */
1555
2167
  var RegistryStore = class {
1556
2168
  bindings = /* @__PURE__ */ new Map();
2169
+ #storageAbort = new AbortController();
2170
+ /** This plugin instance's background storage work. */
2171
+ storage = {
2172
+ signal: this.#storageAbort.signal,
2173
+ pending: /* @__PURE__ */ new Set()
2174
+ };
2175
+ /** Aborts the background storage work (an interrupted build is left INVALID for the next reconcile) and awaits it. */
2176
+ async stopStorage() {
2177
+ this.#storageAbort.abort();
2178
+ await Promise.all([...this.storage.pending]);
2179
+ }
1557
2180
  /**
1558
2181
  * Register a full NamespaceBinding for the given namespace.
1559
2182
  *
@@ -1644,6 +2267,7 @@ function createProposalsPlugin(config) {
1644
2267
  const registryStore = new RegistryStore();
1645
2268
  const capability = config.proposeCapability ?? "substrate.propose";
1646
2269
  const policy = makeProposePolicy(capability);
2270
+ const indexCapability = config.indexCapability ?? "substrate.index";
1647
2271
  let lookupDataset = config.datasetFor ?? (() => void 0);
1648
2272
  /**
1649
2273
  * Shared resolver-registration helper. Used at static-ns install time AND
@@ -1694,10 +2318,21 @@ function createProposalsPlugin(config) {
1694
2318
  edges: ctx.edges,
1695
2319
  pubsub: config.pubsub,
1696
2320
  proposeCapability: capability,
2321
+ indexCapability,
1697
2322
  registerProposalMutations
1698
2323
  }),
1699
2324
  policy
1700
2325
  });
2326
+ ctx.registry.register("propose_index", {
2327
+ kind: "mutation",
2328
+ resolver: makeProposeIndexResolver({
2329
+ registryStore,
2330
+ datasetFor: (ns) => lookupDataset(ns),
2331
+ pubsub: config.pubsub,
2332
+ channelFor: (n) => `_substrate_proposals_${n}`
2333
+ }),
2334
+ policy: makeIndexPolicy(indexCapability)
2335
+ });
1701
2336
  }
1702
2337
  }, ...config.ownedNamespaces.map((ns) => ({
1703
2338
  namespace: ns,
@@ -1707,7 +2342,7 @@ function createProposalsPlugin(config) {
1707
2342
  dataset: ctx.dataset,
1708
2343
  edges: ctx.edges
1709
2344
  });
1710
- defineProposalTypes(ns, capability).install(ctx);
2345
+ defineProposalTypes(ns, capability, indexCapability).install(ctx);
1711
2346
  registerProposalMutations({
1712
2347
  namespace: ns,
1713
2348
  dataset: ctx.dataset,
@@ -1732,6 +2367,7 @@ function createProposalsPlugin(config) {
1732
2367
  datasetFor: lookupDataset,
1733
2368
  edges: controlBinding.edges,
1734
2369
  proposeCapability: capability,
2370
+ indexCapability,
1735
2371
  registerProposalMutations,
1736
2372
  onSkip: (row, err) => ctx.metric("_system_proposals.replay_skipped", {
1737
2373
  namespace: CONTROL_NAMESPACE,
@@ -1787,11 +2423,15 @@ function createProposalsPlugin(config) {
1787
2423
  edges: controlBinding.edges,
1788
2424
  metric: ctx.metric,
1789
2425
  proposeCapability: capability,
2426
+ indexCapability,
1790
2427
  registerProposalMutations
1791
2428
  });
2429
+ },
2430
+ async onStop() {
2431
+ await registryStore.stopStorage();
1792
2432
  }
1793
2433
  };
1794
2434
  }
1795
2435
 
1796
2436
  //#endregion
1797
- export { createNoopPubSub as n, ProposalError as r, createProposalsPlugin as t };
2437
+ export { ProposalError as i, createNoopPubSub as n, storageSettled as r, createProposalsPlugin as t };