@cotal-ai/workspace 0.90.1 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/build/Release/win32-arm64/build.json +1 -1
  2. package/build/Release/win32-x64/build.json +1 -1
  3. package/dist/agent-secrets.d.ts +2 -2
  4. package/dist/agent-secrets.d.ts.map +1 -1
  5. package/dist/agent-secrets.js +2 -2
  6. package/dist/agent-secrets.js.map +1 -1
  7. package/dist/auth-paths.d.ts +8 -2
  8. package/dist/auth-paths.d.ts.map +1 -1
  9. package/dist/auth-paths.js +12 -5
  10. package/dist/auth-paths.js.map +1 -1
  11. package/dist/broker-display.d.ts +4 -0
  12. package/dist/broker-display.d.ts.map +1 -0
  13. package/dist/broker-display.js +29 -0
  14. package/dist/broker-display.js.map +1 -0
  15. package/dist/colors.d.ts +11 -4
  16. package/dist/colors.d.ts.map +1 -1
  17. package/dist/colors.js +36 -9
  18. package/dist/colors.js.map +1 -1
  19. package/dist/connect.d.ts +64 -6
  20. package/dist/connect.d.ts.map +1 -1
  21. package/dist/connect.js +170 -74
  22. package/dist/connect.js.map +1 -1
  23. package/dist/control-target.d.ts +2 -2
  24. package/dist/control-target.js +2 -2
  25. package/dist/credential-actions.d.ts +91 -0
  26. package/dist/credential-actions.d.ts.map +1 -0
  27. package/dist/credential-actions.js +74 -0
  28. package/dist/credential-actions.js.map +1 -0
  29. package/dist/deprecated-daemon-entries.d.ts +30 -0
  30. package/dist/deprecated-daemon-entries.d.ts.map +1 -0
  31. package/dist/deprecated-daemon-entries.js +37 -0
  32. package/dist/deprecated-daemon-entries.js.map +1 -0
  33. package/dist/endpoint-actions.d.ts +31 -0
  34. package/dist/endpoint-actions.d.ts.map +1 -0
  35. package/dist/endpoint-actions.js +2 -0
  36. package/dist/endpoint-actions.js.map +1 -0
  37. package/dist/endpoint-caller.d.ts +74 -0
  38. package/dist/endpoint-caller.d.ts.map +1 -0
  39. package/dist/endpoint-caller.js +118 -0
  40. package/dist/endpoint-caller.js.map +1 -0
  41. package/dist/endpoint-contract.d.ts +32 -0
  42. package/dist/endpoint-contract.d.ts.map +1 -0
  43. package/dist/endpoint-contract.js +92 -0
  44. package/dist/endpoint-contract.js.map +1 -0
  45. package/dist/extension-mutation.d.ts.map +1 -1
  46. package/dist/extension-mutation.js +4 -1
  47. package/dist/extension-mutation.js.map +1 -1
  48. package/dist/extensions.d.ts +28 -8
  49. package/dist/extensions.d.ts.map +1 -1
  50. package/dist/extensions.js +20 -8
  51. package/dist/extensions.js.map +1 -1
  52. package/dist/flags.d.ts +8 -1
  53. package/dist/flags.d.ts.map +1 -1
  54. package/dist/flags.js +9 -7
  55. package/dist/flags.js.map +1 -1
  56. package/dist/index.d.ts +25 -0
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +25 -0
  59. package/dist/index.js.map +1 -1
  60. package/dist/launch-persona.d.ts +10 -0
  61. package/dist/launch-persona.d.ts.map +1 -0
  62. package/dist/launch-persona.js +34 -0
  63. package/dist/launch-persona.js.map +1 -0
  64. package/dist/local-process.d.ts +16 -12
  65. package/dist/local-process.d.ts.map +1 -1
  66. package/dist/local-process.js +7 -2
  67. package/dist/local-process.js.map +1 -1
  68. package/dist/maintenance.d.ts +267 -4
  69. package/dist/maintenance.d.ts.map +1 -1
  70. package/dist/maintenance.js +666 -12
  71. package/dist/maintenance.js.map +1 -1
  72. package/dist/mesh-manifest-schema.d.ts +118 -0
  73. package/dist/mesh-manifest-schema.d.ts.map +1 -0
  74. package/dist/mesh-manifest-schema.js +96 -0
  75. package/dist/mesh-manifest-schema.js.map +1 -0
  76. package/dist/mesh-registry.d.ts +27 -0
  77. package/dist/mesh-registry.d.ts.map +1 -1
  78. package/dist/mesh-registry.js +69 -13
  79. package/dist/mesh-registry.js.map +1 -1
  80. package/dist/mesh-target.d.ts +15 -7
  81. package/dist/mesh-target.d.ts.map +1 -1
  82. package/dist/mesh-target.js +77 -26
  83. package/dist/mesh-target.js.map +1 -1
  84. package/dist/official-connectors.d.ts +13 -0
  85. package/dist/official-connectors.d.ts.map +1 -1
  86. package/dist/official-connectors.js +18 -2
  87. package/dist/official-connectors.js.map +1 -1
  88. package/dist/output.d.ts +147 -0
  89. package/dist/output.d.ts.map +1 -0
  90. package/dist/output.js +186 -0
  91. package/dist/output.js.map +1 -0
  92. package/dist/pid.d.ts +5 -3
  93. package/dist/pid.d.ts.map +1 -1
  94. package/dist/pid.js +25 -13
  95. package/dist/pid.js.map +1 -1
  96. package/dist/preferences.d.ts +93 -0
  97. package/dist/preferences.d.ts.map +1 -0
  98. package/dist/preferences.js +272 -0
  99. package/dist/preferences.js.map +1 -0
  100. package/dist/preflight.d.ts +3 -0
  101. package/dist/preflight.d.ts.map +1 -1
  102. package/dist/preflight.js +6 -3
  103. package/dist/preflight.js.map +1 -1
  104. package/dist/prepared-spaces.d.ts +27 -0
  105. package/dist/prepared-spaces.d.ts.map +1 -0
  106. package/dist/prepared-spaces.js +57 -0
  107. package/dist/prepared-spaces.js.map +1 -0
  108. package/dist/present.d.ts +108 -0
  109. package/dist/present.d.ts.map +1 -0
  110. package/dist/present.js +249 -0
  111. package/dist/present.js.map +1 -0
  112. package/dist/prompt-input.d.ts +12 -0
  113. package/dist/prompt-input.d.ts.map +1 -0
  114. package/dist/prompt-input.js +35 -0
  115. package/dist/prompt-input.js.map +1 -0
  116. package/dist/protected-records.d.ts +102 -0
  117. package/dist/protected-records.d.ts.map +1 -0
  118. package/dist/protected-records.js +465 -0
  119. package/dist/protected-records.js.map +1 -0
  120. package/dist/registration-policy.d.ts +4 -1
  121. package/dist/registration-policy.d.ts.map +1 -1
  122. package/dist/registration-policy.js +4 -3
  123. package/dist/registration-policy.js.map +1 -1
  124. package/dist/render.d.ts +8 -0
  125. package/dist/render.d.ts.map +1 -1
  126. package/dist/render.js +49 -32
  127. package/dist/render.js.map +1 -1
  128. package/dist/service-adapter.d.ts +198 -0
  129. package/dist/service-adapter.d.ts.map +1 -0
  130. package/dist/service-adapter.js +294 -0
  131. package/dist/service-adapter.js.map +1 -0
  132. package/dist/service-custody.d.ts +5 -0
  133. package/dist/service-custody.d.ts.map +1 -0
  134. package/dist/service-custody.js +41 -0
  135. package/dist/service-custody.js.map +1 -0
  136. package/dist/service-definition.d.ts +52 -0
  137. package/dist/service-definition.d.ts.map +1 -0
  138. package/dist/service-definition.js +85 -0
  139. package/dist/service-definition.js.map +1 -0
  140. package/dist/service-definition.schema.json +79 -0
  141. package/dist/service-extension-metadata.d.ts +11 -0
  142. package/dist/service-extension-metadata.d.ts.map +1 -0
  143. package/dist/service-extension-metadata.js +66 -0
  144. package/dist/service-extension-metadata.js.map +1 -0
  145. package/dist/service-identity.d.ts +51 -0
  146. package/dist/service-identity.d.ts.map +1 -0
  147. package/dist/service-identity.js +103 -0
  148. package/dist/service-identity.js.map +1 -0
  149. package/dist/service-observation.d.ts +32 -0
  150. package/dist/service-observation.d.ts.map +1 -0
  151. package/dist/service-observation.js +134 -0
  152. package/dist/service-observation.js.map +1 -0
  153. package/dist/service-preset.d.ts +12 -0
  154. package/dist/service-preset.d.ts.map +1 -0
  155. package/dist/service-preset.js +10 -0
  156. package/dist/service-preset.js.map +1 -0
  157. package/dist/service-startup.d.ts +23 -0
  158. package/dist/service-startup.d.ts.map +1 -0
  159. package/dist/service-startup.js +39 -0
  160. package/dist/service-startup.js.map +1 -0
  161. package/dist/service-stop.d.ts +47 -0
  162. package/dist/service-stop.d.ts.map +1 -0
  163. package/dist/service-stop.js +152 -0
  164. package/dist/service-stop.js.map +1 -0
  165. package/dist/service-target.d.ts +5 -0
  166. package/dist/service-target.d.ts.map +1 -0
  167. package/dist/service-target.js +19 -0
  168. package/dist/service-target.js.map +1 -0
  169. package/dist/signer-export.d.ts +31 -0
  170. package/dist/signer-export.d.ts.map +1 -0
  171. package/dist/signer-export.js +114 -0
  172. package/dist/signer-export.js.map +1 -0
  173. package/dist/space-segmentation.d.ts +13 -2
  174. package/dist/space-segmentation.d.ts.map +1 -1
  175. package/dist/space-segmentation.js +7 -3
  176. package/dist/space-segmentation.js.map +1 -1
  177. package/dist/space.d.ts +5 -5
  178. package/dist/space.d.ts.map +1 -1
  179. package/dist/space.js +8 -6
  180. package/dist/space.js.map +1 -1
  181. package/dist/system-rotation.d.ts +4 -3
  182. package/dist/system-rotation.d.ts.map +1 -1
  183. package/dist/system-rotation.js +16 -6
  184. package/dist/system-rotation.js.map +1 -1
  185. package/dist/web-session.d.ts +7 -0
  186. package/dist/web-session.d.ts.map +1 -1
  187. package/dist/web-session.js +9 -0
  188. package/dist/web-session.js.map +1 -1
  189. package/package.json +6 -2
@@ -67,6 +67,7 @@ export function maintenancePaths(root) {
67
67
  commitIntent: join(versionDir, "commit-intent.json"),
68
68
  lock: join(maintenanceDir, "lock.json"),
69
69
  reaper: join(maintenanceDir, "lock-reaper.json"),
70
+ handoff: join(versionDir, "handoff"),
70
71
  };
71
72
  }
72
73
  function fsyncDirectory(path) {
@@ -512,15 +513,37 @@ function validProofIdentity(value) {
512
513
  return Boolean(value && typeof value === "object" &&
513
514
  exactObjectKeys(value, ["path", "dev", "ino", "generation"]) && validIdentity(value));
514
515
  }
516
+ const LISTENER_PROOF_KEYS = ["attemptId", "serverName", "serverNonce", "processOwner", "serverEndpoint", "target"];
517
+ /** The service layer's full assigned id (`serviceOperationId`), repeated here because this module
518
+ * reports through its own maintenance error and must not import the adapter layer. */
519
+ const SERVICE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
520
+ function validControllerListenerInstance(value, owner) {
521
+ const instance = value;
522
+ const pinned = instance?.process;
523
+ // The creation token is opaque (pid.ts): a macOS token carries spaces, so only its frame is checked.
524
+ return Boolean(instance && typeof instance === "object" &&
525
+ exactObjectKeys(instance, ["instanceId", "launchRequestId", "process"]) &&
526
+ typeof instance.instanceId === "string" && SERVICE_ID.test(instance.instanceId) &&
527
+ typeof instance.launchRequestId === "string" && SERVICE_ID.test(instance.launchRequestId) &&
528
+ pinned && typeof pinned === "object" && exactObjectKeys(pinned, ["pid", "token"]) &&
529
+ Number.isInteger(pinned.pid) && Number(pinned.pid) > 0 &&
530
+ typeof pinned.token === "string" && pinned.token !== "" && pinned.token.trim() === pinned.token &&
531
+ pinned.token.length <= 256 && !/[\u0000-\u001f\u007f]/u.test(pinned.token) &&
532
+ owner.pid === pinned.pid && owner.id === `controller-broker-${instance.launchRequestId}`);
533
+ }
515
534
  function validListenerProof(value) {
516
535
  const proof = value;
536
+ const controller = Boolean(proof && typeof proof === "object" && proof.kind !== undefined);
517
537
  return Boolean(proof && typeof proof === "object" &&
518
- exactObjectKeys(proof, ["attemptId", "serverName", "serverNonce", "processOwner", "serverEndpoint", "target"]) &&
538
+ (controller
539
+ ? exactObjectKeys(proof, ["kind", ...LISTENER_PROOF_KEYS, "instance"]) && proof.kind === "controller"
540
+ : exactObjectKeys(proof, LISTENER_PROOF_KEYS)) &&
519
541
  typeof proof.attemptId === "string" && ATTEMPT_ID.test(proof.attemptId) &&
520
542
  typeof proof.serverName === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(proof.serverName) &&
521
543
  typeof proof.serverNonce === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(proof.serverNonce) &&
522
544
  validProofOwner(proof.processOwner) && typeof proof.serverEndpoint === "string" &&
523
545
  canonicalListenerEndpoint(proof.serverEndpoint) === proof.serverEndpoint && validProofIdentity(proof.target) &&
546
+ (!controller || validControllerListenerInstance(proof.instance, proof.processOwner)) &&
524
547
  Buffer.byteLength(JSON.stringify(proof)) <= 16 * 1024);
525
548
  }
526
549
  function validTimestamp(value) {
@@ -597,12 +620,235 @@ function validCutContext(value) {
597
620
  return Boolean(cut && typeof cut === "object" && exactObjectKeys(cut, ["attemptId", "intentAt", "launch"]) &&
598
621
  typeof cut.attemptId === "string" && ATTEMPT_ID.test(cut.attemptId) && validTimestamp(cut.intentAt) &&
599
622
  validJsonObject(cut.launch) && typeof cut.launch.server === "string" &&
600
- canonicalListenerEndpoint(cut.launch.server) === cut.launch.server);
623
+ canonicalListenerEndpoint(cut.launch.server) === cut.launch.server &&
624
+ (cut.launch.custody === undefined ? cut.launch.controller === undefined
625
+ : cut.launch.custody === "legacy" ? cut.launch.controller === undefined
626
+ : cut.launch.custody === "controller" && validControllerCutBinding(cut.launch.controller)));
627
+ }
628
+ const CONTROLLER_ROLES = ["broker", "auth", "delivery", "manager"];
629
+ const SHA256_HEX = /^[0-9a-f]{64}$/;
630
+ /** A protected local record revision (protected-records.ts mints a UUID; older records are text). */
631
+ const DEFINITION_REVISION = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
632
+ const DEFINITION_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
633
+ function validPinnedProcess(value) {
634
+ const pinned = value;
635
+ return Boolean(pinned && typeof pinned === "object" && exactObjectKeys(pinned, ["pid", "token"]) &&
636
+ Number.isInteger(pinned.pid) && Number(pinned.pid) > 0 &&
637
+ typeof pinned.token === "string" && pinned.token !== "" && pinned.token.trim() === pinned.token &&
638
+ pinned.token.length <= 256 && !/[\u0000-\u001f\u007f]/u.test(pinned.token));
639
+ }
640
+ function validControllerMember(value) {
641
+ const member = value;
642
+ return Boolean(member && typeof member === "object" &&
643
+ exactObjectKeys(member, ["role", "definition", "definitionRevision", "instanceId", "launchRequestId", "process"]) &&
644
+ CONTROLLER_ROLES.includes(member.role) &&
645
+ typeof member.definition === "string" && DEFINITION_NAME.test(member.definition) &&
646
+ typeof member.definitionRevision === "string" && DEFINITION_REVISION.test(member.definitionRevision) &&
647
+ typeof member.instanceId === "string" && SERVICE_ID.test(member.instanceId) &&
648
+ typeof member.launchRequestId === "string" && SERVICE_ID.test(member.launchRequestId) &&
649
+ validPinnedProcess(member.process));
650
+ }
651
+ /** Members are unique by role and instance, and always include the broker and the manager. The
652
+ * broker member keeps its cut-time revision; only `brokerDefinitionRevision` is rebound by a
653
+ * restore rollback, so the two are not compared here. */
654
+ function validControllerCutBinding(value) {
655
+ const binding = value;
656
+ const manager = binding?.manager;
657
+ if (!binding || typeof binding !== "object" ||
658
+ !exactObjectKeys(binding, ["stackOperationId", "brokerDefinitionRevision", "members", "manager"]) ||
659
+ typeof binding.stackOperationId !== "string" || !SERVICE_ID.test(binding.stackOperationId) ||
660
+ typeof binding.brokerDefinitionRevision !== "string" || !DEFINITION_REVISION.test(binding.brokerDefinitionRevision) ||
661
+ !Array.isArray(binding.members) || binding.members.length < 2 || binding.members.length > CONTROLLER_ROLES.length ||
662
+ !binding.members.every(validControllerMember) ||
663
+ !manager || typeof manager !== "object" || !exactObjectKeys(manager, ["instanceId", "epoch", "lifecycleUid"]) ||
664
+ typeof manager.instanceId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(manager.instanceId) ||
665
+ !Number.isSafeInteger(manager.epoch) || Number(manager.epoch) < 0 ||
666
+ typeof manager.lifecycleUid !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(manager.lifecycleUid))
667
+ return false;
668
+ const roles = binding.members.map((member) => member.role);
669
+ const broker = binding.members.find((member) => member.role === "broker");
670
+ return new Set(roles).size === roles.length && roles.includes("manager") && Boolean(broker) &&
671
+ new Set(binding.members.map((member) => member.instanceId)).size === binding.members.length;
672
+ }
673
+ /** The cut's controller binding, or undefined for a legacy cut. The journal reader has validated it. */
674
+ export function cutController(cut) {
675
+ return cut.launch.custody === "controller" ? cut.launch.controller : undefined;
676
+ }
677
+ function validControllerStop(value, members) {
678
+ const stop = value;
679
+ if (!stop || typeof stop !== "object" || !exactObjectKeys(stop, ["role", "instanceId", "launchRequestId", "receipt"]))
680
+ return false;
681
+ const member = members.find((row) => row.role === stop.role);
682
+ if (!member || member.instanceId !== stop.instanceId || member.launchRequestId !== stop.launchRequestId)
683
+ return false;
684
+ const receipt = stop.receipt;
685
+ const kind = stop.role === "manager" ? "preserved-exit" : stop.role === "broker" ? "kernel-exit" : "process-exit";
686
+ const scoped = kind !== "process-exit";
687
+ return Boolean(receipt && typeof receipt === "object" &&
688
+ exactObjectKeys(receipt, scoped ? ["kind", "requestId", "scopeSha256", "observedAt"] : ["kind", "requestId", "observedAt"]) &&
689
+ receipt.kind === kind && typeof receipt.requestId === "string" && SERVICE_ID.test(receipt.requestId) &&
690
+ (!scoped || typeof receipt.scopeSha256 === "string" && SHA256_HEX.test(receipt.scopeSha256)) &&
691
+ validTimestamp(receipt.observedAt));
692
+ }
693
+ /** One row per cut member, in any order, with the receipt kind its role requires. */
694
+ function validControllerStops(value, binding) {
695
+ return Array.isArray(value) && value.length === binding.members.length &&
696
+ value.every((stop) => validControllerStop(stop, binding.members)) &&
697
+ new Set(value.map((stop) => stop.role)).size === value.length;
698
+ }
699
+ function validPreservedStop(value, cut, binding) {
700
+ const stop = value;
701
+ const manager = binding.members.find((member) => member.role === "manager");
702
+ if (!stop || typeof stop !== "object" || !exactObjectKeys(stop, ["instanceId", "launchRequestId", "attempts"]) ||
703
+ stop.instanceId !== manager.instanceId || stop.launchRequestId !== manager.launchRequestId ||
704
+ !Array.isArray(stop.attempts) || stop.attempts.length < 1 || stop.attempts.length > 16)
705
+ return false;
706
+ // An unpublished attempt at any position is prepublication history.
707
+ return stop.attempts.every((attempt) => {
708
+ const row = attempt;
709
+ const published = exactObjectKeys(row, ["requestId", "target", "stopper", "withAgents", "scopeSha256", "preserved", "recordedAt", "published"]);
710
+ return Boolean((published || exactObjectKeys(row, ["requestId", "target", "stopper", "withAgents", "scopeSha256", "preserved", "recordedAt"])) &&
711
+ (!published || row.published === true) &&
712
+ typeof row.requestId === "string" && SERVICE_ID.test(row.requestId) &&
713
+ validPinnedProcess(row.target) && row.target.pid === manager.process.pid && row.target.token === manager.process.token &&
714
+ validPinnedProcess(row.stopper) && row.withAgents === false &&
715
+ typeof row.scopeSha256 === "string" && SHA256_HEX.test(row.scopeSha256) &&
716
+ row.preserved && typeof row.preserved === "object" && exactObjectKeys(row.preserved, ["attemptId", "inventorySha256"]) &&
717
+ row.preserved.attemptId === cut.attemptId &&
718
+ typeof row.preserved.inventorySha256 === "string" && SHA256_HEX.test(row.preserved.inventorySha256) &&
719
+ validTimestamp(row.recordedAt));
720
+ }) && new Set(stop.attempts.map((attempt) => attempt.requestId)).size === stop.attempts.length;
721
+ }
722
+ /** A rollback rebound the broker revision away from the one the cut's broker record runs at, so that
723
+ * record can never start again (`startProcessService` refuses a revision mismatch). */
724
+ function cutBrokerRetired(cut) {
725
+ return cut.members.find((member) => member.role === "broker").definitionRevision !== cut.brokerDefinitionRevision;
726
+ }
727
+ function validAttemptBroker(value, cut) {
728
+ const broker = value;
729
+ return Boolean(broker && typeof broker === "object" && exactObjectKeys(broker, ["instanceId", "launchRequestId"]) &&
730
+ typeof broker.instanceId === "string" && SERVICE_ID.test(broker.instanceId) &&
731
+ typeof broker.launchRequestId === "string" && SERVICE_ID.test(broker.launchRequestId) &&
732
+ broker.instanceId !== cut.members.find((member) => member.role === "broker").instanceId);
733
+ }
734
+ function validControllerResumeBinding(value, cut) {
735
+ const binding = value;
736
+ if (!binding || typeof binding !== "object" ||
737
+ !exactObjectKeys(binding, binding.broker === undefined ? ["stackOperationId", "started"] : ["stackOperationId", "started", "broker"]) ||
738
+ binding.broker !== undefined && (!cutBrokerRetired(cut) || !validAttemptBroker(binding.broker, cut)) ||
739
+ typeof binding.stackOperationId !== "string" || !SERVICE_ID.test(binding.stackOperationId) ||
740
+ binding.stackOperationId === cut.stackOperationId ||
741
+ !Array.isArray(binding.started) || binding.started.length > 64)
742
+ return false;
743
+ return binding.started.every((value) => {
744
+ const row = value;
745
+ const keys = ["role", "instanceId", "priorLaunchRequestId", "state"];
746
+ const settled = row?.launchRequestId !== undefined || row?.outcome !== undefined;
747
+ return Boolean(row && typeof row === "object" &&
748
+ exactObjectKeys(row, settled ? [...keys, "launchRequestId", "outcome"] : keys) &&
749
+ CONTROLLER_ROLES.includes(row.role) && row.state === "requested" &&
750
+ typeof row.instanceId === "string" && SERVICE_ID.test(row.instanceId) &&
751
+ typeof row.priorLaunchRequestId === "string" && SERVICE_ID.test(row.priorLaunchRequestId) &&
752
+ (!settled || typeof row.launchRequestId === "string" && SERVICE_ID.test(row.launchRequestId) &&
753
+ row.launchRequestId !== row.priorLaunchRequestId &&
754
+ ["running", "refused-before-spawn", "unknown"].includes(String(row.outcome))));
755
+ });
756
+ }
757
+ /** The resume's controller binding, or undefined for a legacy resume. The journal reader has validated it. */
758
+ export function ordinaryResumeController(context) {
759
+ return context.launch.custody === "controller" ? context.launch.controller : undefined;
760
+ }
761
+ function validTokenHandoff(value, handoffDir, attemptId) {
762
+ const handoff = value;
763
+ if (!handoff || typeof handoff !== "object")
764
+ return false;
765
+ const pinned = handoff.dev !== undefined || handoff.ino !== undefined || handoff.sha256 !== undefined;
766
+ if (!exactObjectKeys(handoff, pinned ? ["path", "state", "dev", "ino", "sha256"] : ["path", "state"]))
767
+ return false;
768
+ if (typeof handoff.path !== "string" || dirname(handoff.path) !== handoffDir ||
769
+ !new RegExp(`^resume-commit\\.${attemptId}\\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`).test(basename(handoff.path)))
770
+ return false;
771
+ // `intended` never has an inode; `written` always has one; consumed or swept keep it when it was written.
772
+ if (handoff.state === "intended")
773
+ return !pinned;
774
+ if (!["written", "consumed", "swept"].includes(handoff.state))
775
+ return false;
776
+ if (handoff.state === "written" && !pinned)
777
+ return false;
778
+ return !pinned || (typeof handoff.dev === "string" && /^\d+$/.test(handoff.dev) &&
779
+ typeof handoff.ino === "string" && /^\d+$/.test(handoff.ino) &&
780
+ typeof handoff.sha256 === "string" && SHA256_HEX.test(handoff.sha256));
781
+ }
782
+ function validControllerReconfiguration(value, restore, binding) {
783
+ const reconfiguration = value;
784
+ if (!reconfiguration || typeof reconfiguration !== "object")
785
+ return false;
786
+ const keys = ["fromRevision", "fromOptionsSha256", "fromConfigPath", "fromConfigSha256", "toConfigPath", "toConfigSha256", "toStoreIdentity", "phase"];
787
+ const phase = reconfiguration.phase;
788
+ const expected = phase === "rendered" ? keys
789
+ : phase === "definition-committed" || phase === "rolling-back" ? [...keys, "toRevision"]
790
+ : phase === "rolled-back" ? [...keys, "toRevision", "rollbackRevision"] : undefined;
791
+ return Boolean(expected && exactObjectKeys(reconfiguration, expected) &&
792
+ typeof reconfiguration.fromRevision === "string" && DEFINITION_REVISION.test(reconfiguration.fromRevision) &&
793
+ typeof reconfiguration.fromOptionsSha256 === "string" && SHA256_HEX.test(reconfiguration.fromOptionsSha256) &&
794
+ typeof reconfiguration.fromConfigPath === "string" && isAbsolute(reconfiguration.fromConfigPath) &&
795
+ reconfiguration.fromConfigPath !== reconfiguration.toConfigPath &&
796
+ typeof reconfiguration.fromConfigSha256 === "string" && SHA256_HEX.test(reconfiguration.fromConfigSha256) &&
797
+ typeof reconfiguration.toConfigPath === "string" && isAbsolute(reconfiguration.toConfigPath) &&
798
+ restore.ownedPaths?.some((owned) => owned.label === "config" && owned.path === reconfiguration.toConfigPath) &&
799
+ typeof reconfiguration.toConfigSha256 === "string" && SHA256_HEX.test(reconfiguration.toConfigSha256) &&
800
+ validIdentity(reconfiguration.toStoreIdentity) && reconfiguration.toStoreIdentity.path === restore.targetPath &&
801
+ (restore.target === undefined || sameStoreIdentity(reconfiguration.toStoreIdentity, restore.target)) &&
802
+ (reconfiguration.toRevision === undefined ||
803
+ typeof reconfiguration.toRevision === "string" && DEFINITION_REVISION.test(reconfiguration.toRevision) &&
804
+ reconfiguration.toRevision !== reconfiguration.fromRevision) &&
805
+ (reconfiguration.rollbackRevision === undefined ||
806
+ typeof reconfiguration.rollbackRevision === "string" && DEFINITION_REVISION.test(reconfiguration.rollbackRevision) &&
807
+ reconfiguration.rollbackRevision !== reconfiguration.fromRevision && reconfiguration.rollbackRevision !== reconfiguration.toRevision &&
808
+ reconfiguration.rollbackRevision === binding.brokerDefinitionRevision) &&
809
+ // Before a rollback the cut still expects the revision the rewrite started from.
810
+ (phase === "rolled-back" || reconfiguration.fromRevision === binding.brokerDefinitionRevision));
811
+ }
812
+ /** A restore's proof scope: its context and the attempt broker its launch binding names. */
813
+ function restoreProofScope(record) {
814
+ const broker = record.launch.controller?.broker;
815
+ return { restore: record.restore, ...(broker ? { broker } : {}) };
816
+ }
817
+ /** A controller listener proof fits the journal's own record of which broker it may name. A
818
+ * resume names a settled `started` broker row. A restore names `reconfiguredBroker` or its
819
+ * binding's attempt broker when present, otherwise the cut's broker instance at a new launch
820
+ * request. An attempt broker of a resume must be that exact pair too. The caller still checks
821
+ * that the instance record is running at that launch request with that process. */
822
+ function controllerProofFits(proof, cut, scope) {
823
+ const instance = proof.instance;
824
+ if (proof.kind !== "controller" || !instance)
825
+ return false;
826
+ const exact = (pair) => pair.instanceId === instance.instanceId && pair.launchRequestId === instance.launchRequestId;
827
+ if ("resume" in scope)
828
+ return (!scope.resume.broker || exact(scope.resume.broker)) &&
829
+ scope.resume.started.some((row) => row.role === "broker" && row.instanceId === instance.instanceId &&
830
+ row.launchRequestId === instance.launchRequestId);
831
+ const attempt = scope.restore.reconfiguredBroker ?? scope.broker;
832
+ if (attempt)
833
+ return exact(attempt);
834
+ const broker = cut.members.find((member) => member.role === "broker");
835
+ return broker.instanceId === instance.instanceId && broker.launchRequestId !== instance.launchRequestId;
836
+ }
837
+ /** The proof variant follows the cut's custody, and a controller proof fits its scope. */
838
+ function listenerProofFitsCustody(proof, cut, scope) {
839
+ const controller = cutController(cut);
840
+ if (!controller)
841
+ return proof.kind === undefined;
842
+ return scope !== undefined && controllerProofFits(proof, controller, scope);
601
843
  }
602
844
  function validCutCompletionEvidence(value, cut) {
603
845
  const evidence = value;
846
+ const controller = cutController(cut);
604
847
  return Boolean(evidence && typeof evidence === "object" &&
605
- exactObjectKeys(evidence, ["attemptId", "observedAt", "managerCommit", "stopped", "listener"]) &&
848
+ exactObjectKeys(evidence, controller
849
+ ? ["attemptId", "observedAt", "managerCommit", "stopped", "listener", "controllerStops"]
850
+ : ["attemptId", "observedAt", "managerCommit", "stopped", "listener"]) &&
851
+ (!controller || validControllerStops(evidence.controllerStops, controller)) &&
606
852
  evidence.attemptId === cut.attemptId && validTimestamp(evidence.observedAt) &&
607
853
  evidence.managerCommit && typeof evidence.managerCommit === "object" &&
608
854
  exactObjectKeys(evidence.managerCommit, ["operation", "attemptId", "state"]) &&
@@ -635,19 +881,43 @@ function normalizedListenerProof(value) {
635
881
  ino: value.target.ino,
636
882
  generation: value.target.generation,
637
883
  },
884
+ ...(value.kind === "controller" && value.instance ? {
885
+ kind: "controller",
886
+ instance: {
887
+ instanceId: value.instance.instanceId,
888
+ launchRequestId: value.instance.launchRequestId,
889
+ process: { pid: value.instance.process.pid, token: value.instance.process.token },
890
+ },
891
+ } : {}),
638
892
  };
639
893
  }
640
894
  function sameProcessOwner(a, b) {
641
895
  return a.pid === b.pid && a.host === b.host && a.startedAt === b.startedAt && a.id === b.id;
642
896
  }
897
+ /** The proof variant must match the cut's custody, and a controller proof must fit the journal's
898
+ * recorded broker. The workspace cannot read service instance records, so the caller passes the
899
+ * live check that the named instance is running at that launch request with that process. A
900
+ * controller proof without that check refuses. */
901
+ function requireCustodyProof(proof, cut, scope, running, root, attemptId) {
902
+ if (!listenerProofFitsCustody(proof, cut, scope))
903
+ maintenanceError("listener-proof-mismatch", proof.kind === "controller"
904
+ ? "the controller listener proof does not name this attempt's recorded broker instance"
905
+ : "a legacy listener proof cannot bind a controller-custody attempt", { root, attemptId });
906
+ if (proof.kind === "controller" && (!running || !running(proof.instance)))
907
+ maintenanceError("listener-proof-mismatch", "the controller listener's broker instance is not proven running at that launch request and process", { root, attemptId });
908
+ }
643
909
  function sameListenerProof(a, b) {
644
- return a.attemptId === b.attemptId && a.serverName === b.serverName &&
910
+ return a.kind === b.kind && a.attemptId === b.attemptId && a.serverName === b.serverName &&
645
911
  a.serverNonce === b.serverNonce && sameProcessOwner(a.processOwner, b.processOwner) &&
646
- a.serverEndpoint === b.serverEndpoint && sameStoreIdentity(a.target, b.target);
912
+ a.serverEndpoint === b.serverEndpoint && sameStoreIdentity(a.target, b.target) &&
913
+ (a.kind !== "controller" || Boolean(a.instance && b.instance &&
914
+ a.instance.instanceId === b.instance.instanceId && a.instance.launchRequestId === b.instance.launchRequestId &&
915
+ a.instance.process.pid === b.instance.process.pid && a.instance.process.token === b.instance.process.token));
647
916
  }
648
917
  function reusesListenerIdentity(a, b) {
649
918
  return a.serverName === b.serverName || a.serverNonce === b.serverNonce ||
650
- sameProcessOwner(a.processOwner, b.processOwner);
919
+ sameProcessOwner(a.processOwner, b.processOwner) ||
920
+ Boolean(a.instance && b.instance && a.instance.launchRequestId === b.instance.launchRequestId);
651
921
  }
652
922
  function validListenerReplacements(value) {
653
923
  if (!Array.isArray(value) || value.length === 0 || value.length > 1024)
@@ -961,6 +1231,26 @@ function validateRestoreContext(record, path) {
961
1231
  }
962
1232
  if (restore.ownedPaths !== undefined && !validOwnedPaths(restore.ownedPaths))
963
1233
  maintenanceError("journal-corrupt", "restore attempt-owned paths are invalid", { paths: [path] });
1234
+ const controller = cutController(record.cut);
1235
+ if (restore.controllerReconfiguration !== undefined &&
1236
+ (!controller || restore.method !== "alternate" ||
1237
+ !validControllerReconfiguration(restore.controllerReconfiguration, restore, controller)))
1238
+ maintenanceError("journal-corrupt", "restore broker reconfiguration is invalid or outside a controller alternate restore", { paths: [path] });
1239
+ const reconfiguredBroker = restore.reconfiguredBroker;
1240
+ if (reconfiguredBroker !== undefined) {
1241
+ const broker = controller?.members.find((member) => member.role === "broker");
1242
+ if (!broker || restore.controllerReconfiguration?.phase !== "definition-committed" ||
1243
+ !reconfiguredBroker || typeof reconfiguredBroker !== "object" ||
1244
+ !exactObjectKeys(reconfiguredBroker, ["instanceId", "launchRequestId"]) ||
1245
+ typeof reconfiguredBroker.instanceId !== "string" || !SERVICE_ID.test(reconfiguredBroker.instanceId) ||
1246
+ typeof reconfiguredBroker.launchRequestId !== "string" || !SERVICE_ID.test(reconfiguredBroker.launchRequestId) ||
1247
+ reconfiguredBroker.instanceId === broker.instanceId)
1248
+ maintenanceError("journal-corrupt", "reconfigured broker instance is invalid", { paths: [path] });
1249
+ }
1250
+ const handoff = record.tokenHandoff;
1251
+ if (handoff !== undefined &&
1252
+ !validTokenHandoff(handoff, join(dirname(path), "handoff"), restore.attemptId))
1253
+ maintenanceError("journal-corrupt", "restore commit-token handoff record is invalid", { paths: [path] });
964
1254
  if (restore.cleanup) {
965
1255
  const cleanup = restore.cleanup;
966
1256
  if (!["attempt-target", "previous-source"].includes(cleanup.kind) ||
@@ -978,8 +1268,18 @@ function validateOrdinaryResume(record, path) {
978
1268
  !ATTEMPT_ID.test(context.attemptId) || typeof context.intentAt !== "string" ||
979
1269
  !Number.isFinite(Date.parse(context.intentAt)) || !validJsonObject(context.launch))
980
1270
  maintenanceError("journal-corrupt", "ordinary resume intent is invalid", { paths: [path] });
1271
+ const cut = cutController(record.cut);
1272
+ const custody = context.launch.custody;
1273
+ if (cut ? custody !== "controller" || !validControllerResumeBinding(context.launch.controller, cut)
1274
+ : custody !== undefined || context.launch.controller !== undefined)
1275
+ maintenanceError("journal-corrupt", "ordinary resume custody does not match the cut", { paths: [path] });
1276
+ const resumeScope = cut ? { resume: ordinaryResumeController(context) } : undefined;
1277
+ if (record.tokenHandoff !== undefined &&
1278
+ !validTokenHandoff(record.tokenHandoff, join(dirname(path), "handoff"), context.attemptId))
1279
+ maintenanceError("journal-corrupt", "resume commit-token handoff record is invalid", { paths: [path] });
981
1280
  if (record.listenerProof !== undefined &&
982
1281
  (!validListenerProof(record.listenerProof) ||
1282
+ !listenerProofFitsCustody(record.listenerProof, record.cut, resumeScope) ||
983
1283
  record.listenerProof.attemptId !== context.attemptId ||
984
1284
  !sameStoreIdentity(record.listenerProof.target, record.source) ||
985
1285
  typeof context.launch.server !== "string" ||
@@ -987,7 +1287,8 @@ function validateOrdinaryResume(record, path) {
987
1287
  maintenanceError("journal-corrupt", "resume listener proof is invalid or belongs to another attempt", { paths: [path] });
988
1288
  if (record.listenerReplacements !== undefined &&
989
1289
  (!validListenerReplacements(record.listenerReplacements) ||
990
- record.listenerReplacements.some((replacement) => replacement.proof.attemptId !== context.attemptId ||
1290
+ record.listenerReplacements.some((replacement) => !listenerProofFitsCustody(replacement.proof, record.cut, resumeScope) ||
1291
+ replacement.proof.attemptId !== context.attemptId ||
991
1292
  !sameStoreIdentity(replacement.proof.target, record.source) ||
992
1293
  typeof context.launch.server !== "string" ||
993
1294
  canonicalListenerEndpoint(context.launch.server) !== replacement.proof.serverEndpoint)))
@@ -1072,7 +1373,17 @@ function validateJournal(value, path) {
1072
1373
  committed.managerCommit.attemptId !== record.cut.attemptId ||
1073
1374
  committed.managerCommit.state !== "preserved")
1074
1375
  maintenanceError("journal-corrupt", "cut-committed manager evidence is invalid", { paths: [path] });
1376
+ const controller = cutController(record.cut);
1377
+ if (committed.preservedStop !== undefined &&
1378
+ (!controller || !validPreservedStop(committed.preservedStop, record.cut, controller)))
1379
+ maintenanceError("journal-corrupt", "cut-committed preserved stop attempts are invalid", { paths: [path] });
1075
1380
  }
1381
+ else if (record.preservedStop !== undefined) {
1382
+ maintenanceError("journal-corrupt", "only a cut-committed journal can record preserved stop attempts", { paths: [path] });
1383
+ }
1384
+ if (record.tokenHandoff !== undefined &&
1385
+ !["manager-committed", "active", "degraded", "resume-committed", "resume-degraded", "resume-retired"].includes(record.state))
1386
+ maintenanceError("journal-corrupt", "this maintenance state cannot record a commit-token handoff", { paths: [path] });
1076
1387
  if (record.state === "claimed") {
1077
1388
  const claim = record.claim;
1078
1389
  if (!claim || typeof claim.attemptId !== "string" || !ATTEMPT_ID.test(claim.attemptId) ||
@@ -1097,8 +1408,19 @@ function validateJournal(value, path) {
1097
1408
  if (restoreRecord.state !== "restore-ready" &&
1098
1409
  !validJsonObject(restoreRecord.launch))
1099
1410
  maintenanceError("journal-corrupt", "restore launch metadata is invalid", { paths: [path] });
1411
+ // A controller restore journals its member starts in the launch, as a controller resume does.
1412
+ if (restoreRecord.state !== "restore-ready") {
1413
+ const launch = restoreRecord.launch;
1414
+ const controller = cutController(record.cut);
1415
+ if (controller ? launch.custody !== "controller" || !validControllerResumeBinding(launch.controller, controller) ||
1416
+ // A rewritten broker definition names its new broker in reconfiguredBroker, never here.
1417
+ launch.controller.broker !== undefined && restoreRecord.restore.controllerReconfiguration !== undefined
1418
+ : launch.custody !== undefined || launch.controller !== undefined)
1419
+ maintenanceError("journal-corrupt", "restore launch custody does not match the cut", { paths: [path] });
1420
+ }
1100
1421
  if (restoreRecord.state !== "restore-ready" && restoreRecord.listenerProof !== undefined &&
1101
1422
  (!validListenerProof(restoreRecord.listenerProof) ||
1423
+ !listenerProofFitsCustody(restoreRecord.listenerProof, record.cut, restoreProofScope(restoreRecord)) ||
1102
1424
  restoreRecord.listenerProof.attemptId !== restoreRecord.restore.attemptId ||
1103
1425
  !sameStoreIdentity(restoreRecord.listenerProof.target, restoreRecord.restore.target) ||
1104
1426
  typeof restoreRecord.launch.server !== "string" ||
@@ -1108,7 +1430,8 @@ function validateJournal(value, path) {
1108
1430
  const committed = restoreRecord;
1109
1431
  if (committed.listenerReplacements !== undefined &&
1110
1432
  (!validListenerReplacements(committed.listenerReplacements) ||
1111
- committed.listenerReplacements.some((replacement) => replacement.proof.attemptId !== committed.restore.attemptId ||
1433
+ committed.listenerReplacements.some((replacement) => !listenerProofFitsCustody(replacement.proof, record.cut, restoreProofScope(committed)) ||
1434
+ replacement.proof.attemptId !== committed.restore.attemptId ||
1112
1435
  !sameStoreIdentity(replacement.proof.target, committed.restore.target) ||
1113
1436
  typeof committed.launch.server !== "string" ||
1114
1437
  canonicalListenerEndpoint(committed.launch.server) !== replacement.proof.serverEndpoint)))
@@ -1206,10 +1529,24 @@ function readyFrom(record) {
1206
1529
  cut: record.cut, cutCompletion: record.cutCompletion,
1207
1530
  };
1208
1531
  }
1532
+ function validCapability(value) {
1533
+ const capability = value;
1534
+ const text = (field) => typeof field === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(field);
1535
+ return Boolean(capability && typeof capability === "object" &&
1536
+ exactObjectKeys(capability, ["instanceId", "epoch", "owner", "uid", "clusterDigest", "statusOutputDigest"]) &&
1537
+ text(capability.instanceId) && Number.isSafeInteger(capability.epoch) && capability.epoch >= 0 &&
1538
+ text(capability.owner) && text(capability.uid) &&
1539
+ typeof capability.clusterDigest === "string" && /^sha256:[0-9a-f]{64}$/.test(capability.clusterDigest) &&
1540
+ typeof capability.statusOutputDigest === "string" && /^sha256:[0-9a-f]{64}$/.test(capability.statusOutputDigest));
1541
+ }
1209
1542
  function validPrepareIntent(value) {
1210
1543
  const intent = value;
1544
+ const controller = Boolean(intent && typeof intent === "object" && (intent.custody !== undefined || intent.capability !== undefined));
1211
1545
  return Boolean(intent && typeof intent === "object" &&
1212
- exactObjectKeys(intent, ["attemptId", "space", "mode", "server", "storeDir"]) &&
1546
+ exactObjectKeys(intent, controller
1547
+ ? ["attemptId", "space", "mode", "server", "storeDir", "custody", "capability"]
1548
+ : ["attemptId", "space", "mode", "server", "storeDir"]) &&
1549
+ (!controller || intent.custody === "controller" && validCapability(intent.capability)) &&
1213
1550
  typeof intent.attemptId === "string" && ATTEMPT_ID.test(intent.attemptId) &&
1214
1551
  typeof intent.space === "string" && intent.space &&
1215
1552
  ["auth", "open", "user"].includes(intent.mode) &&
@@ -1403,6 +1740,51 @@ export function recordPreservationManagerCommit(lock, managerCommit) {
1403
1740
  managerCommittedAt: new Date().toISOString(), managerCommit,
1404
1741
  });
1405
1742
  }
1743
+ function controllerCutCommitted(lock) {
1744
+ const record = currentJournal(lock);
1745
+ const controller = cutController(record.cut);
1746
+ if (record.state !== "cut-committed" || !controller)
1747
+ maintenanceError("invalid-transition", "a preserved-exit stop attempt needs a controller cut-committed journal", { root: lock.root });
1748
+ assertStoreIdentity(record.source);
1749
+ return { record: record, controller: controller };
1750
+ }
1751
+ /** Journal one preserved-exit stop attempt BEFORE its request can be published. The caller has
1752
+ * already proved the handoff empty under this lock. An attempt is never
1753
+ * rewritten or removed; at most 16 are kept. */
1754
+ export function appendPreservedStopAttempt(lock, attempt) {
1755
+ const { record, controller } = controllerCutCommitted(lock);
1756
+ const manager = controller.members.find((member) => member.role === "manager");
1757
+ const previous = record.preservedStop?.attempts ?? [];
1758
+ if (previous.some((row) => row.requestId === attempt.requestId))
1759
+ maintenanceError("invalid-transition", "this preserved-exit stop attempt is already journaled", { root: lock.root, attemptId: record.cut.attemptId });
1760
+ const row = {
1761
+ requestId: attempt.requestId, target: { pid: attempt.target.pid, token: attempt.target.token },
1762
+ stopper: { pid: attempt.stopper.pid, token: attempt.stopper.token }, withAgents: false,
1763
+ scopeSha256: attempt.scopeSha256,
1764
+ preserved: { attemptId: attempt.preserved.attemptId, inventorySha256: attempt.preserved.inventorySha256 },
1765
+ recordedAt: new Date().toISOString(),
1766
+ };
1767
+ return writeJournal(lock, record, {
1768
+ state: "cut-committed", space: record.space, mode: record.mode, source: record.source,
1769
+ resume: record.resume, cut: record.cut, managerCommittedAt: record.managerCommittedAt, managerCommit: record.managerCommit,
1770
+ preservedStop: { instanceId: manager.instanceId, launchRequestId: manager.launchRequestId, attempts: [...previous, row] },
1771
+ });
1772
+ }
1773
+ /** Mark the attempt published only after its request file was written. */
1774
+ export function markPreservedStopPublished(lock, requestId) {
1775
+ const { record } = controllerCutCommitted(lock);
1776
+ const stop = record.preservedStop;
1777
+ const index = stop?.attempts.findIndex((row) => row.requestId === requestId) ?? -1;
1778
+ if (!stop || index < 0)
1779
+ maintenanceError("invalid-transition", "the published preserved-exit stop attempt is not journaled", { root: lock.root, attemptId: record.cut.attemptId });
1780
+ if (stop.attempts[index].published)
1781
+ return record;
1782
+ return writeJournal(lock, record, {
1783
+ state: "cut-committed", space: record.space, mode: record.mode, source: record.source,
1784
+ resume: record.resume, cut: record.cut, managerCommittedAt: record.managerCommittedAt, managerCommit: record.managerCommit,
1785
+ preservedStop: { ...stop, attempts: stop.attempts.map((row, at) => at === index ? { ...row, published: true } : row) },
1786
+ });
1787
+ }
1406
1788
  /** Promote only the exact durable cut after all stopped/unreachable evidence has been supplied. */
1407
1789
  export function completeMaintenanceCut(lock, evidence) {
1408
1790
  const record = currentJournal(lock);
@@ -1607,11 +1989,256 @@ function ordinaryListenerState(record) {
1607
1989
  return {
1608
1990
  ...(record.listenerProof ? { listenerProof: record.listenerProof } : {}),
1609
1991
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
1992
+ ...carriedTokenHandoff(record),
1610
1993
  };
1611
1994
  }
1995
+ /** Every transition that rebuilds a resume or committed-restore record keeps its handoff record,
1996
+ * so a later run can still sweep or settle the exact recorded file. */
1997
+ function carriedTokenHandoff(record) {
1998
+ return record.tokenHandoff ? { tokenHandoff: record.tokenHandoff } : {};
1999
+ }
2000
+ /** The start rows of a controller resume or a controller restore, or undefined for any other record. */
2001
+ export function controllerAttemptBinding(record) {
2002
+ if (!cutController(record.cut))
2003
+ return undefined;
2004
+ if ("ordinaryResume" in record)
2005
+ return ordinaryResumeController(record.ordinaryResume);
2006
+ if ("restore" in record && "launch" in record && record.launch.custody === "controller")
2007
+ return record.launch.controller;
2008
+ return undefined;
2009
+ }
2010
+ /** Mirroring legacy bare down, a validated `active` controller restore of
2011
+ * this space no longer fences the controller stack it restored. That stack's journal must name the
2012
+ * restore's address and restored store, and must have settled the restore's own operation. Every
2013
+ * other state and journal kind still fences. This only reads: the journal is never consumed,
2014
+ * rewritten or deleted. */
2015
+ export function admittedControllerRestore(root, stack) {
2016
+ const record = readMaintenanceJournal(root);
2017
+ const binding = record ? controllerAttemptBinding(record) : undefined;
2018
+ if (!record || record.state !== "active" || !binding || record.space !== stack.space || record.launch.server !== stack.server ||
2019
+ record.restore.target.path !== stack.storeDir || stack.operation.id === binding.stackOperationId && stack.operation.phase !== "completed")
2020
+ return undefined;
2021
+ return record;
2022
+ }
2023
+ /** Whether stack work that carries no maintenance attempt may go ahead at this root: the root holds
2024
+ * no maintenance journal, or its journal is a settled active controller restore of the stack these
2025
+ * facts describe, at this space and address. The broker and manager adapters and a service restart
2026
+ * all decide through it. This only reads. */
2027
+ export function maintenanceAdmitsStackWork(root, space, server, stack) {
2028
+ if (!readMaintenanceJournal(root))
2029
+ return true;
2030
+ return Boolean(stack && stack.space === space && stack.server === server && admittedControllerRestore(root, stack));
2031
+ }
2032
+ /** The record a controller start may change. Before manager commitment any member may start. After
2033
+ * it, only the manager may be relaunched. The
2034
+ * custody and attempt are read from the journal, never from a caller. */
2035
+ function controllerAttemptRecord(lock, role) {
2036
+ const record = currentJournal(lock);
2037
+ const binding = controllerAttemptBinding(record);
2038
+ const committed = record.state === "resume-committed" || record.state === "manager-committed";
2039
+ if (!binding || !committed && record.state !== "resume-intent" && record.state !== "commit-intent")
2040
+ return maintenanceError("invalid-transition", `controller member starts are recorded only in a controller resume or restore before activation, not from ${record.state}`, { root: lock.root });
2041
+ if (committed && role !== "manager")
2042
+ maintenanceError("invalid-transition", "after manager commitment only the manager may be relaunched", { root: lock.root });
2043
+ return { record: record, binding, committed };
2044
+ }
2045
+ /** A commit token exists only after manager commitment, so a handoff belongs to a committed resume
2046
+ * or restore, in any custody (every new launcher passes it as a file). */
2047
+ function handoffRecord(lock) {
2048
+ const record = currentJournal(lock);
2049
+ if ((record.state === "resume-committed" || record.state === "resume-degraded") && record.managerCommit)
2050
+ return { record, attemptId: record.ordinaryResume.attemptId };
2051
+ if ((record.state === "manager-committed" || record.state === "degraded") && record.managerCommit)
2052
+ return { record, attemptId: record.restore.attemptId };
2053
+ return maintenanceError("invalid-transition", `a commit-token handoff needs a manager-committed resume or restore, not ${record.state}`, { root: lock.root });
2054
+ }
2055
+ /** Rewrite only the handoff record; every other field is carried unchanged and revalidated. */
2056
+ function rewriteHandoff(lock, record, tokenHandoff) {
2057
+ return writeJournal(lock, record, { ...record, tokenHandoff });
2058
+ }
2059
+ /** Rewrite only the attempt binding; every other field is carried unchanged and revalidated. */
2060
+ function rewriteControllerAttempt(lock, record, binding, started) {
2061
+ const controller = { stackOperationId: binding.stackOperationId, started: started.map((row) => ({ ...row })), ...(binding.broker ? { broker: { ...binding.broker } } : {}) };
2062
+ const next = "ordinaryResume" in record
2063
+ ? { ...record, ordinaryResume: { ...record.ordinaryResume, launch: { ...record.ordinaryResume.launch, controller } } }
2064
+ : { ...record, launch: { ...record.launch, controller } };
2065
+ return writeJournal(lock, record, next);
2066
+ }
2067
+ /** Journal one member start as `requested` BEFORE `startProcessService` is called. A later run
2068
+ * reads this row with the instance record to decide retry, adopt or hold.
2069
+ * After manager commitment the row may name only the manager, its newest row must have run, and
2070
+ * the caller must prove that exact recorded process gone. */
2071
+ export function requestControllerMemberStart(lock, row, options = {}) {
2072
+ const { record, binding, committed } = controllerAttemptRecord(lock, row.role);
2073
+ if (committed) {
2074
+ const prior = [...binding.started].reverse().find((entry) => entry.role === "manager");
2075
+ if (!prior || prior.outcome !== "running" || !options.priorManagerGone?.(prior))
2076
+ maintenanceError("invalid-transition", "a committed attempt relaunches its manager only after its last recorded start ran and that exact process is proven gone", { root: lock.root });
2077
+ }
2078
+ return rewriteControllerAttempt(lock, record, binding, [...binding.started, { role: row.role, instanceId: row.instanceId, priorLaunchRequestId: row.priorLaunchRequestId, state: "requested" }]);
2079
+ }
2080
+ /** Settle the newest `requested` row for this role with the launch request and its outcome. */
2081
+ export function settleControllerMemberStart(lock, role, launchRequestId, outcome) {
2082
+ const { record, binding } = controllerAttemptRecord(lock, role);
2083
+ let index = -1;
2084
+ binding.started.forEach((row, at) => { if (row.role === role)
2085
+ index = at; });
2086
+ if (index < 0 || binding.started[index].outcome !== undefined)
2087
+ maintenanceError("invalid-transition", "no unsettled member start row matches this role", { root: lock.root });
2088
+ return rewriteControllerAttempt(lock, record, binding, binding.started.map((row, at) => at === index ? { ...row, launchRequestId, outcome } : row));
2089
+ }
2090
+ /** The new broker instance this attempt must start, when the cut's broker record is retired for it:
2091
+ * an alternate restore whose broker definition was rewritten (`reconfiguredBroker`), or any attempt
2092
+ * after a rollback rebound the broker revision (the binding's `broker`). */
2093
+ export function controllerAttemptBroker(record) {
2094
+ const cut = cutController(record.cut);
2095
+ if (!cut)
2096
+ return { required: false };
2097
+ if ("restore" in record && record.restore.controllerReconfiguration?.phase === "definition-committed")
2098
+ return { required: true, ...(record.restore.reconfiguredBroker ? { instance: record.restore.reconfiguredBroker } : {}) };
2099
+ if (!cutBrokerRetired(cut))
2100
+ return { required: false };
2101
+ const broker = controllerAttemptBinding(record)?.broker;
2102
+ return { required: true, ...(broker ? { instance: broker } : {}) };
2103
+ }
2104
+ /** Journal the attempt's new broker instance before its start. Only an
2105
+ * uncommitted controller resume, or a restore at commit intent, records one, and only once. */
2106
+ export function recordControllerAttemptBroker(lock, instance) {
2107
+ const record = currentJournal(lock);
2108
+ const cut = cutController(record.cut);
2109
+ const needed = controllerAttemptBroker(record);
2110
+ if (!cut || !needed.required || record.state !== "resume-intent" && record.state !== "commit-intent")
2111
+ return maintenanceError("invalid-transition", "only a controller attempt whose cut broker is retired records a new broker instance, before manager commitment", { root: lock.root });
2112
+ if (needed.instance) {
2113
+ if (needed.instance.instanceId !== instance.instanceId || needed.instance.launchRequestId !== instance.launchRequestId)
2114
+ maintenanceError("invalid-transition", "this attempt already records another broker instance; it was not replaced", { root: lock.root });
2115
+ return record;
2116
+ }
2117
+ if (!validAttemptBroker(instance, cut))
2118
+ maintenanceError("invalid-transition", "the new broker instance IDs are invalid", { root: lock.root });
2119
+ if (record.state === "commit-intent" && record.restore.controllerReconfiguration?.phase === "definition-committed")
2120
+ return writeJournal(lock, record, { ...record, restore: { ...record.restore, reconfiguredBroker: { instanceId: instance.instanceId, launchRequestId: instance.launchRequestId } } });
2121
+ const binding = controllerAttemptBinding(record);
2122
+ return rewriteControllerAttempt(lock, record, { ...binding, broker: { instanceId: instance.instanceId, launchRequestId: instance.launchRequestId } }, binding.started);
2123
+ }
2124
+ const RECONFIGURATION_FIXED = ["fromRevision", "fromOptionsSha256", "fromConfigPath", "fromConfigSha256", "toConfigPath", "toConfigSha256"];
2125
+ /** Journal one step of an alternate restore's broker definition rewrite, each before the definition
2126
+ * write it names: `rendered` with its attempt-owned
2127
+ * config file, then `definition-committed`, `rolling-back`, and `rolled-back`, which rebinds the
2128
+ * cut's broker revision in the same write. Pre-commit controller alternate restores only. */
2129
+ export function recordRestoreReconfiguration(lock, next, owned) {
2130
+ const record = requireRestoreReady(lock);
2131
+ const cut = cutController(record.cut);
2132
+ const prior = record.restore.controllerReconfiguration;
2133
+ const allowed = prior === undefined
2134
+ ? next.phase === "rendered" && owned?.label === "config" && owned.path === next.toConfigPath && owned.dev !== undefined
2135
+ : prior.phase === "rendered" ? next.phase === "definition-committed"
2136
+ : prior.phase === "definition-committed" ? next.phase === "rolling-back" && next.toRevision === prior.toRevision
2137
+ : prior.phase === "rolling-back" && next.phase === "rolled-back" && next.toRevision === prior.toRevision;
2138
+ const same = prior === undefined || RECONFIGURATION_FIXED.every((key) => prior[key] === next[key]) && sameStoreIdentity(prior.toStoreIdentity, next.toStoreIdentity);
2139
+ if (!cut || record.restore.method !== "alternate" || !allowed || !same || (prior === undefined) !== (owned !== undefined))
2140
+ maintenanceError("invalid-transition", `a controller broker reconfiguration cannot move from ${prior?.phase ?? "none"} to ${next.phase}`, { root: lock.root, attemptId: record.restore.attemptId });
2141
+ const ownedPaths = owned ? [...(record.restore.ownedPaths ?? []).filter((entry) => entry.path !== owned.path), owned] : record.restore.ownedPaths;
2142
+ const restore = { ...record.restore, ...(ownedPaths ? { ownedPaths } : {}), controllerReconfiguration: next };
2143
+ const rebound = next.phase === "rolled-back"
2144
+ ? { ...record.cut, launch: { ...record.cut.launch, controller: { ...cut, brokerDefinitionRevision: next.rollbackRevision } } }
2145
+ : record.cut;
2146
+ return writeJournal(lock, record, { ...readyFrom(record), cut: rebound, state: "restore-ready", phase: record.phase, restore, claim: record.claim });
2147
+ }
2148
+ const HANDOFF_ENTRY = /^resume-commit\./u;
2149
+ /** Create or check the 0700 handoff directory. An existing directory is never chmodded or adopted:
2150
+ * it must be ours, not a link, and closed to group and other. */
2151
+ function handoffDirectory(root) {
2152
+ const paths = maintenancePaths(root);
2153
+ ensureLayout(paths);
2154
+ try {
2155
+ mkdirSync(paths.handoff, { mode: 0o700 });
2156
+ fsyncDirectory(paths.versionDir);
2157
+ }
2158
+ catch (error) {
2159
+ if (errno(error) !== "EEXIST")
2160
+ throw error;
2161
+ }
2162
+ const stat = lstatSync(paths.handoff);
2163
+ if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0)
2164
+ maintenanceError("ambiguous-filesystem-state", "the commit-token handoff directory is not an owned private directory; it was not adopted", { root, paths: [paths.handoff] });
2165
+ return paths.handoff;
2166
+ }
2167
+ /** Settle an earlier handoff of this attempt before a new one, and hold on
2168
+ * any entry the journal does not record: an inode with no recorded identity is never deleted. */
2169
+ export function sweepTokenHandoff(lock) {
2170
+ const { record } = handoffRecord(lock);
2171
+ const directory = handoffDirectory(lock.root);
2172
+ const recorded = record.tokenHandoff;
2173
+ const unknown = readdirSync(directory).filter((name) => HANDOFF_ENTRY.test(name) && join(directory, name) !== recorded?.path);
2174
+ if (unknown.length)
2175
+ maintenanceError("ambiguous-filesystem-state", "the handoff directory holds a commit-token file this attempt did not record; it was not removed", { root: lock.root, paths: unknown.map((name) => join(directory, name)) });
2176
+ if (!recorded || recorded.state === "consumed" || recorded.state === "swept")
2177
+ return record;
2178
+ const stat = lstatSync(recorded.path, { throwIfNoEntry: false });
2179
+ if (!stat)
2180
+ return rewriteHandoff(lock, record, { ...recorded, state: "swept" });
2181
+ if (recorded.state === "intended" || !stat.isFile() || stat.isSymbolicLink() || String(stat.dev) !== recorded.dev || String(stat.ino) !== recorded.ino || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || stat.nlink !== 1)
2182
+ maintenanceError("ambiguous-filesystem-state", "a recorded commit-token handoff path holds an unrecorded or changed file; it was not removed", { root: lock.root, paths: [recorded.path] });
2183
+ unlinkSync(recorded.path);
2184
+ fsyncDirectory(directory);
2185
+ return rewriteHandoff(lock, record, { ...recorded, state: "swept" });
2186
+ }
2187
+ /** Steps 2 and 3: journal the path, write the journal's own token create-only at 0600, then journal
2188
+ * its exact inode and digest, all before the child starts. The token is read from the durable
2189
+ * manager commit evidence, never from a caller. Returns only the path and digest for argv. */
2190
+ export function writeTokenHandoff(lock) {
2191
+ const { record, attemptId } = handoffRecord(lock);
2192
+ const token = record.managerCommit.durableCommitToken;
2193
+ if (record.tokenHandoff && record.tokenHandoff.state !== "consumed" && record.tokenHandoff.state !== "swept")
2194
+ maintenanceError("invalid-transition", "an earlier commit-token handoff is not settled; sweep it first", { root: lock.root, attemptId });
2195
+ const directory = handoffDirectory(lock.root);
2196
+ const path = join(directory, `resume-commit.${attemptId}.${randomUUID()}`);
2197
+ const intended = rewriteHandoff(lock, record, { path, state: "intended" });
2198
+ const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
2199
+ try {
2200
+ writeFileSync(fd, token);
2201
+ fsyncSync(fd);
2202
+ }
2203
+ finally {
2204
+ closeSync(fd);
2205
+ }
2206
+ fsyncDirectory(directory);
2207
+ const stat = lstatSync(path);
2208
+ const sha256 = createHash("sha256").update(token).digest("hex");
2209
+ rewriteHandoff(lock, intended, { path, state: "written", dev: String(stat.dev), ino: String(stat.ino), sha256 });
2210
+ return { path, sha256 };
2211
+ }
2212
+ /** Step 6, after manager readiness: an absent file was consumed by the child; the same inode is
2213
+ * removed here; any other file at the path holds. */
2214
+ export function settleTokenHandoff(lock) {
2215
+ const record = currentJournal(lock);
2216
+ const recorded = record.tokenHandoff;
2217
+ if (!recorded || recorded.state === "consumed" || recorded.state === "swept")
2218
+ return;
2219
+ if (recorded.state !== "written")
2220
+ maintenanceError("ambiguous-filesystem-state", "the commit-token handoff never recorded its written file; it was not settled", { root: lock.root, paths: [recorded.path] });
2221
+ const stat = lstatSync(recorded.path, { throwIfNoEntry: false });
2222
+ let next;
2223
+ if (!stat)
2224
+ next = { ...recorded, state: "consumed" };
2225
+ else if (stat.isFile() && !stat.isSymbolicLink() && String(stat.dev) === recorded.dev && String(stat.ino) === recorded.ino) {
2226
+ unlinkSync(recorded.path);
2227
+ fsyncDirectory(dirname(recorded.path));
2228
+ next = { ...recorded, state: "swept" };
2229
+ }
2230
+ else
2231
+ return maintenanceError("ambiguous-filesystem-state", "the commit-token handoff path holds another file; it was not removed", { root: lock.root, paths: [recorded.path] });
2232
+ rewriteHandoff(lock, record, next);
2233
+ }
2234
+ /** Step 7: retirement or restore activation requires a settled handoff when one was made. */
2235
+ function requireSettledTokenHandoff(record, root) {
2236
+ if (record.tokenHandoff && record.tokenHandoff.state !== "consumed" && record.tokenHandoff.state !== "swept")
2237
+ maintenanceError("invalid-transition", "the commit-token handoff is not settled; activation cannot retire it", { root, paths: [record.tokenHandoff.path] });
2238
+ }
1612
2239
  /** Fsync the exact ordinary-resume listener identity after spawn and before activation. The
1613
2240
  * proof's target is the preserved SOURCE store. */
1614
- export function bindOrdinaryResumeListener(lock, proof) {
2241
+ export function bindOrdinaryResumeListener(lock, proof, options = {}) {
1615
2242
  const record = currentJournal(lock);
1616
2243
  if (record.state !== "resume-intent" &&
1617
2244
  (record.state !== "resume-degraded" || record.managerCommit !== undefined))
@@ -1619,6 +2246,8 @@ export function bindOrdinaryResumeListener(lock, proof) {
1619
2246
  root: lock.root,
1620
2247
  });
1621
2248
  const normalized = normalizedListenerProof(proof);
2249
+ const resumeController = ordinaryResumeController(record.ordinaryResume);
2250
+ requireCustodyProof(normalized, record.cut, resumeController ? { resume: resumeController } : undefined, options.controllerInstanceRunning, lock.root, record.ordinaryResume.attemptId);
1622
2251
  if (normalized.attemptId !== record.ordinaryResume.attemptId ||
1623
2252
  !sameStoreIdentity(normalized.target, record.source))
1624
2253
  maintenanceError("listener-proof-mismatch", "resume listener proof does not match the attempt and preserved source", {
@@ -1648,6 +2277,7 @@ export function bindOrdinaryResumeListener(lock, proof) {
1648
2277
  ...readyFrom(record), state: "resume-intent", ordinaryResume: record.ordinaryResume,
1649
2278
  listenerProof: normalized,
1650
2279
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
2280
+ ...carriedTokenHandoff(record),
1651
2281
  });
1652
2282
  return writeJournal(lock, record, {
1653
2283
  ...readyFrom(record), state: "resume-degraded", ordinaryResume: record.ordinaryResume,
@@ -1655,6 +2285,7 @@ export function bindOrdinaryResumeListener(lock, proof) {
1655
2285
  degradedAt: record.degradedAt, reason: record.reason, recourse: record.recourse,
1656
2286
  listenerProof: normalized,
1657
2287
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
2288
+ ...carriedTokenHandoff(record),
1658
2289
  });
1659
2290
  }
1660
2291
  /** Retire one exactly bound, provably dead resume listener before a fresh proof may be bound. A
@@ -1696,6 +2327,7 @@ export function replaceDeadOrdinaryResumeListener(lock, proof, options = {}) {
1696
2327
  const base = {
1697
2328
  ...readyFrom(record), ordinaryResume: record.ordinaryResume,
1698
2329
  listenerReplacements: [...history, replacement],
2330
+ ...carriedTokenHandoff(record),
1699
2331
  };
1700
2332
  if (record.state === "resume-intent")
1701
2333
  return writeJournal(lock, record, { ...base, state: "resume-intent" });
@@ -1796,6 +2428,7 @@ export function retireOrdinaryResume(lock, retirement) {
1796
2428
  paths: [record.source.path],
1797
2429
  });
1798
2430
  assertStoreIdentity(record.source);
2431
+ requireSettledTokenHandoff(record, lock.root);
1799
2432
  if (!validManagerFinalizeEvidence(retirement, record.ordinaryResume.attemptId, record.managerCommit.durableCommitToken))
1800
2433
  maintenanceError("activation-evidence-invalid", "ordinary resume retirement requires exact manager finalize evidence", {
1801
2434
  root: lock.root, attemptId: record.ordinaryResume.attemptId, paths: [record.source.path],
@@ -2061,13 +2694,14 @@ export function writeRestoreCommitIntent(lock, launch) {
2061
2694
  });
2062
2695
  }
2063
2696
  /** Fsync the exact normal listener identity after spawn and before activation is published. */
2064
- export function bindRestoreListener(lock, proof) {
2697
+ export function bindRestoreListener(lock, proof, options = {}) {
2065
2698
  const record = currentJournal(lock);
2066
2699
  if (record.state !== "commit-intent")
2067
2700
  maintenanceError("invalid-transition", "restore listener can be bound only from commit intent", {
2068
2701
  root: lock.root,
2069
2702
  });
2070
2703
  const normalized = normalizedListenerProof(proof);
2704
+ requireCustodyProof(normalized, record.cut, restoreProofScope(record), options.controllerInstanceRunning, lock.root, record.restore.attemptId);
2071
2705
  if (normalized.attemptId !== record.restore.attemptId ||
2072
2706
  !sameStoreIdentity(normalized.target, record.restore.target))
2073
2707
  maintenanceError("listener-proof-mismatch", "restore listener proof does not match the committed attempt and target", {
@@ -2096,6 +2730,7 @@ export function bindRestoreListener(lock, proof) {
2096
2730
  ...readyFrom(record), state: "commit-intent", restore: record.restore,
2097
2731
  launch: record.launch, listenerProof: normalized,
2098
2732
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
2733
+ ...carriedTokenHandoff(record),
2099
2734
  });
2100
2735
  }
2101
2736
  /**
@@ -2144,6 +2779,7 @@ export function replaceDeadRestoreListener(lock, proof, options = {}) {
2144
2779
  return writeJournal(lock, record, {
2145
2780
  ...readyFrom(record), state: "commit-intent", restore: record.restore, launch: record.launch,
2146
2781
  listenerReplacements: [...history, replacement],
2782
+ ...carriedTokenHandoff(record),
2147
2783
  });
2148
2784
  }
2149
2785
  /** Fsync the manager's suppression-retaining commit token before requesting finalization. */
@@ -2191,6 +2827,7 @@ export function recordRestoreManagerCommit(lock, proof, evidence) {
2191
2827
  ...readyFrom(record), state: "manager-committed", restore: record.restore,
2192
2828
  launch: record.launch, listenerProof: record.listenerProof,
2193
2829
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
2830
+ ...carriedTokenHandoff(record),
2194
2831
  managerCommittedAt: new Date().toISOString(), managerCommit: evidence,
2195
2832
  });
2196
2833
  }
@@ -2221,6 +2858,7 @@ export function markRestoreActive(lock, proof, evidence) {
2221
2858
  });
2222
2859
  assertStoreIdentity(record.restore.target);
2223
2860
  assertListenerOwnerAlive(record.listenerProof);
2861
+ requireSettledTokenHandoff(record, lock.root);
2224
2862
  const details = {
2225
2863
  attemptId: record.restore.attemptId,
2226
2864
  listenerReady: true,
@@ -2232,6 +2870,7 @@ export function markRestoreActive(lock, proof, evidence) {
2232
2870
  ...readyFrom(record), state: "active", restore: record.restore,
2233
2871
  launch: record.launch, listenerProof: record.listenerProof,
2234
2872
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
2873
+ ...carriedTokenHandoff(record),
2235
2874
  managerCommittedAt: record.managerCommittedAt, managerCommit: record.managerCommit,
2236
2875
  activeAt: new Date().toISOString(), details,
2237
2876
  });
@@ -2246,6 +2885,7 @@ export function markRestoreDegraded(lock, reason, recourse) {
2246
2885
  ...readyFrom(record), state: "degraded", restore: record.restore,
2247
2886
  launch: record.launch, ...(record.listenerProof ? { listenerProof: record.listenerProof } : {}),
2248
2887
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
2888
+ ...carriedTokenHandoff(record),
2249
2889
  ...(record.state === "manager-committed"
2250
2890
  ? { managerCommittedAt: record.managerCommittedAt, managerCommit: record.managerCommit }
2251
2891
  : {}),
@@ -2281,6 +2921,7 @@ export function repairRestoreDegradedToActive(lock, proof, evidence) {
2281
2921
  });
2282
2922
  assertStoreIdentity(record.restore.target);
2283
2923
  assertListenerOwnerAlive(record.listenerProof);
2924
+ requireSettledTokenHandoff(record, lock.root);
2284
2925
  if (!record.managerCommit || !record.managerCommittedAt)
2285
2926
  maintenanceError("invalid-transition", "uncommitted degraded restore must record manager commitment before finalization", {
2286
2927
  root: lock.root, attemptId: record.restore.attemptId, paths: [record.restore.target.path],
@@ -2302,6 +2943,7 @@ export function repairRestoreDegradedToActive(lock, proof, evidence) {
2302
2943
  managerCommittedAt: record.managerCommittedAt, managerCommit: record.managerCommit,
2303
2944
  activeAt: new Date().toISOString(), details,
2304
2945
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
2946
+ ...carriedTokenHandoff(record),
2305
2947
  });
2306
2948
  }
2307
2949
  function cleanupTomb(record, kind, identity) {
@@ -2319,6 +2961,7 @@ function startCleanup(lock, record, kind, identity) {
2319
2961
  ...readyFrom(record), state: "active", restore: restore,
2320
2962
  launch: record.launch, ...(record.listenerProof ? { listenerProof: record.listenerProof } : {}),
2321
2963
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
2964
+ ...carriedTokenHandoff(record),
2322
2965
  managerCommittedAt: record.managerCommittedAt, managerCommit: record.managerCommit,
2323
2966
  activeAt: record.activeAt, details: record.details,
2324
2967
  });
@@ -2377,6 +3020,7 @@ function continueCleanup(lock, record) {
2377
3020
  ...readyFrom(record), state: "active", restore: restore,
2378
3021
  launch: record.launch, ...(record.listenerProof ? { listenerProof: record.listenerProof } : {}),
2379
3022
  ...(record.listenerReplacements ? { listenerReplacements: record.listenerReplacements } : {}),
3023
+ ...carriedTokenHandoff(record),
2380
3024
  managerCommittedAt: record.managerCommittedAt, managerCommit: record.managerCommit,
2381
3025
  activeAt: record.activeAt, details: record.details,
2382
3026
  });
@@ -2396,7 +3040,7 @@ function cleanupAttemptTarget(lock, record) {
2396
3040
  }
2397
3041
  /** Refuse to touch a LIVE restore attempt: only the exact recorded coordinator, or a caller that
2398
3042
  * proves the attempt stale (deadline elapsed + every owner dead), may roll it back. */
2399
- function assertRestoreClaimRollbackable(lock, record, options) {
3043
+ export function assertRestoreClaimRollbackable(lock, record, options) {
2400
3044
  if (options.asCoordinator) {
2401
3045
  if (!sameProcessOwner(options.asCoordinator, record.claim.coordinator))
2402
3046
  maintenanceError("claim-live", "rollback caller is not the recorded restore coordinator", {
@@ -2432,6 +3076,16 @@ export function rollbackRestore(lock, options = {}) {
2432
3076
  if (initial.state !== "restore-ready")
2433
3077
  maintenanceError("invalid-transition", "no pre-commit restore is available to roll back", { root: lock.root });
2434
3078
  assertRestoreClaimRollbackable(lock, initial, options);
3079
+ // The attempt-owned config is deleted below only once no live broker definition names it: either
3080
+ // the forward rewrite never landed, or the definition rollback already recorded its revision.
3081
+ const reconfiguration = initial.restore.controllerReconfiguration;
3082
+ const live = options.controllerDefinition?.liveRevision;
3083
+ if (reconfiguration && !(reconfiguration.phase === "rendered" && live === reconfiguration.fromRevision) &&
3084
+ !(reconfiguration.phase === "rolled-back" && live === reconfiguration.rollbackRevision))
3085
+ maintenanceError("rollback-forbidden", "the controller broker definition is not back at the cut's revision; its definition rollback must run first", {
3086
+ root: lock.root, attemptId: initial.restore.attemptId,
3087
+ recourse: [{ action: "inspect", description: "Run the controller restore recovery, which rolls the broker definition back before the store." }],
3088
+ });
2435
3089
  if (!initial.restore.target && pathExistsStrict(initial.restore.targetPath) &&
2436
3090
  !(initial.restore.method === "same-path" && initial.phase === "move-pending" &&
2437
3091
  sameStoreIdentity(initial.source, readStoreIdentity(initial.restore.targetPath)))) {