rollbridge 0.1.35 → 0.1.37

package/README.md

@@ -240,9 +240,11 @@ later deploys continue to honor the original drain boundary.
 
 There is one explicit compatibility boundary: the first upgrade from a genuine
 pre-owner-replacement Rollbridge guardian and daemon cannot share its listeners
-on supported Node 20. After authenticating the guardian, exact daemon PID/socket,
-runtime authority, and durable owned-process state, `ensure-daemon` performs a
-one-time **disruptive** bridge. Existing proxy/control connections may close,
+on supported Node 20. The same boundary applies to a retained transition guardian
+that supports prepare/stage but predates the retired-owner commit command. After
+an explicit capability probe and authentication of the guardian, exact daemon
+PID/socket, runtime authority, and durable owned-process state, `ensure-daemon`
+performs a one-time **disruptive** bridge. Existing proxy/control connections may close,
 the retained processes keep their exact PIDs under guardian supervision, and
 `status.ownerTransition` reports `mode: "legacy-first-upgrade"` with
 `disruptive: true`. The bridge requires the existing config identity unchanged;

package/changelog.d/20260830-guardian-retired-replacement-process-key.md

@@ -1,9 +1,16 @@
 ### Fixed
 
 - Select retired-owner commit proof from the guardian-published committed owner
-  snapshot rather than candidate-local process order, and independently require
-  that proof to remain registered while retaining the replacement transaction,
-  authority, and control-path fences.
+  snapshot rather than candidate-local process order, reserve its incumbent-owned
+  registration through commit, then attach it to the committed candidate while
+  retaining the replacement transaction, authority, and control-path fences.
 - Fail closed when an older retained guardian cannot commit that replacement
   atomically after the incumbent control socket disappears, preserving the
   incumbent owner, retained connections, and guardian-managed release processes.
+- Explicitly classify retained guardian replacement capabilities before preparing
+  a transaction. Guardians with prepare/stage support but no retired-owner commit
+  command use the fully attested one-time disruptive legacy upgrade bridge;
+  malformed, stale, or ambiguous protocol responses continue to fail closed. The
+  partial guardian's prepared transaction remains the mutation fence through
+  candidate reconstruction and boundary revalidation, and failed preparation
+  notifies the incumbent to resume paused release drains.

package/docs/cli.md

@@ -103,7 +103,8 @@ the candidate binds and validates its listeners, and an authenticated fenced
 transaction commits guardian authority and the final control socket. A lost
 control response is accepted only when the guardian confirms the exact committed
 transaction id. The first authenticated upgrade from a genuine pre-replacement
-guardian/daemon is the sole exception: `ensure-daemon` preserves its exact
+guardian/daemon, or from a retained prepare/stage guardian that explicitly lacks
+the retired-owner commit capability, is the sole exception: `ensure-daemon` preserves its exact
 guardian-owned processes but deliberately retires the old listeners before the
 Node 20 candidate binds, so existing proxy/control connections may close.
 Successful status JSON records this as `ownerTransition.disruptive: true` and

package/docs/config.md

@@ -151,8 +151,10 @@ config reloads remain unchanged.
 
 The first upgrade from an authenticated pre-replacement Rollbridge guardian and
 daemon uses an explicitly disruptive compatibility bridge because that legacy
-owner cannot transfer listeners on Node 20. Rollbridge attests the exact guardian
-and daemon processes, sockets, runtime/config authority, and durable process
+owner cannot transfer listeners on Node 20. A retained guardian that supports
+replacement prepare/stage but lacks the retired-owner commit command is explicitly
+classified and uses the same bridge. Rollbridge attests the exact guardian and
+daemon processes, sockets, runtime/config authority, and durable process
 registrations before retiring the legacy listeners. Managed process PIDs and
 release state remain supervised, but live proxy/control connections may close.
 The resulting status includes `ownerTransition: {disruptive: true, mode:

package/docs/troubleshooting.md

@@ -11,6 +11,9 @@ cannot authenticate and attest an allowed owner transition.
 
 **Fix.** With `ownerRecovery`, a genuine pre-owner-replacement Rollbridge daemon
 and guardian can cross the documented one-time disruptive bridge automatically.
+A retained guardian that implements replacement prepare/stage but lacks the
+retired-owner commit capability uses that same bridge only after the exact
+non-mutating capability signature and legacy process dispatch are confirmed.
 Its existing proxy/control connections may close; successful status reports
 `ownerTransition.mode: "legacy-first-upgrade"`. Keep the incumbent config
 identity unchanged for that first invocation, then apply config/socket changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rollbridge",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
   "keywords": [
     "deploy",

package/src/daemon.js

@@ -29,7 +29,7 @@ const STATE_PERSIST_INTERVAL_MS = 5000
  * @typedef {{configDigest: string, format: number, guardian: {pid?: number, socketPath: string, token: string}, reconnectGraceMs: number}} OwnerRecoveryMetadata
  * @typedef {DaemonStatus & {recovery: OwnerRecoveryMetadata, singletonReleaseIds?: Record<string, string>}} OwnerRecoverySnapshot
  * @typedef {{authority: JsonValue, config: import("./config.js").RollbridgeConfig, releaseConfigs?: Record<string, import("./config.js").RollbridgeConfig>, singletonReleaseIds?: Record<string, string>, snapshot: OwnerRecoverySnapshot}} PrivateOwnerState
- * @typedef {{boundaryCrossed: boolean, incumbentControl: Awaited<ReturnType<typeof openControlSession>>, incumbentStartTime: string, prepared: {ownerState: JsonValue, replacementId: string}, recoverySnapshot: OwnerRecoverySnapshot}} LegacyOwnerBridge
+ * @typedef {{boundaryCrossed: boolean, incumbentControl?: Awaited<ReturnType<typeof openControlSession>>, incumbentStartTime: string, legacyGuardian: GuardianClient, legacyInventory: {key: string, provenance: string}[], legacyPrepared?: {ownerState: JsonValue, replacementId: string}, legacySnapshot: OwnerRecoverySnapshot, prepared: {ownerState: JsonValue, replacementId: string}, recoverySnapshot: OwnerRecoverySnapshot}} LegacyOwnerBridge
  */
 
 export default class RollbridgeDaemon {
@@ -325,24 +325,38 @@ export default class RollbridgeDaemon {
       configDigest: persisted.recovery.configDigest,
       runtime: persisted.daemonRuntime ? {...persisted.daemonRuntime} : null
     }
-    let legacyBridge
-    let prepared
+    const replacementProtocol = await this.guardian.ownerReplacementProtocol()
+    const legacyBridge = replacementProtocol === "legacy"
+      ? await this.prepareLegacyOwnerReplacement({persisted, persistedAuthority})
+      : undefined
+    const prepared = legacyBridge?.prepared ?? await this.guardian.prepareOwnerReplacement(persistedAuthority, this.ownerAuthority())
+    let preparedStatus
+    let reservedProcessKey
+    let transfer
 
     try {
-      prepared = await this.guardian.prepareOwnerReplacement(persistedAuthority, this.ownerAuthority())
+      preparedStatus = await this.guardian.replacementStatus()
+      transfer = /** @type {PrivateOwnerState} */ (prepared.ownerState)
+      if (!transfer?.config || !transfer.snapshot) throw new Error("Committed owner published incomplete replacement state")
+      const registeredProcesses = new Map((await this.guardian.inventory()).map(({key, provenance}) => [key, provenance]))
+
+      reservedProcessKey = legacyBridge ? undefined : ownerSnapshotProcessKeys(transfer.snapshot, transfer.singletonReleaseIds)
+        .find((key) => registeredProcesses.has(key))
+      if (reservedProcessKey) this.guardian.reserveProcessRecovery(reservedProcessKey, /** @type {string} */ (registeredProcesses.get(reservedProcessKey)))
+      await this.restoreOwnerState(transfer.snapshot, {config: transfer.config, releaseConfigs: transfer.releaseConfigs, resumeDrains: false, singletonReleaseIds: transfer.singletonReleaseIds, synchronizeLifecycleRoles: false})
     } catch (error) {
-      legacyBridge = await this.prepareLegacyOwnerReplacement({
-        error: error instanceof Error ? error : String(error),
-        persisted,
-        persistedAuthority
-      })
-      prepared = legacyBridge.prepared
+      legacyBridge?.incumbentControl?.close()
+      if (legacyBridge) {
+        try {
+          await this.abandonLegacyOwnerBridge(legacyBridge)
+        } catch (cleanupError) {
+          throw new AggregateError([error, cleanupError], "Legacy owner replacement reconstruction failed and its upgrade coordinator could not be abandoned", {cause: cleanupError})
+        }
+      } else {
+        this.guardian.disconnect()
+      }
+      throw error
     }
-    const preparedStatus = await this.guardian.replacementStatus()
-    const transfer = /** @type {PrivateOwnerState} */ (prepared.ownerState)
-
-    if (!transfer?.config || !transfer.snapshot) throw new Error("Committed owner published incomplete replacement state")
-    await this.restoreOwnerState(transfer.snapshot, {config: transfer.config, releaseConfigs: transfer.releaseConfigs, resumeDrains: false, singletonReleaseIds: transfer.singletonReleaseIds, synchronizeLifecycleRoles: false})
     for (const release of this.releases.values()) release.preserveConfigOnRetirement = true
     this.logger("owner replacement candidate prepared", {activeReleaseId: this.activeRelease?.releaseId ?? null, replacementId: prepared.replacementId})
 
@@ -386,6 +400,7 @@ export default class RollbridgeDaemon {
         if (incumbentControl) {
           const listenerSession = incumbentControl
 
+          if (reservedProcessKey) await this.guardian.recoverReservedProcess(reservedProcessKey)
           incumbentControl.onEvent((event) => this.handleIncumbentListenerEvent(event, listenerSession))
           await incumbentControl.request({
             command: "yield-owner-listeners",
@@ -414,15 +429,20 @@ export default class RollbridgeDaemon {
         snapshot: this.status()
       })
 
+      if (staged.committed && reservedProcessKey) {
+        committedAuthority = true
+        await this.guardian.recoverReservedProcess(reservedProcessKey)
+      }
+
       if (!staged.committed) {
         if (retiredIncumbentControl) {
-          const recoveredProcesses = this.guardian.processes
-          const processKey = ownerSnapshotProcessKeys(transfer.snapshot, transfer.singletonReleaseIds)
-            .find((key) => recoveredProcesses.has(key))
+          const processKey = reservedProcessKey
 
-          if (!processKey) throw new Error("Retired owner replacement requires an exact recovered process from committed owner state")
+          if (!processKey || !this.guardian.processes.has(processKey)) throw new Error("Retired owner replacement requires an exact reserved process from committed owner state")
           try {
             await this.guardian.commitRetiredOwnerReplacement(prepared.replacementId, processKey)
+            committedAuthority = true
+            await this.guardian.recoverReservedProcess(processKey)
           } catch (error) {
             if (!(error instanceof Error) || error.message !== "Guardian commit-retired-owner-replacement requires the committed owner") throw error
             throw new Error(
@@ -484,12 +504,13 @@ export default class RollbridgeDaemon {
       }
       if (legacyBridge && !legacyBridge.boundaryCrossed) {
         try {
-          await this.guardian.abandonLegacyUpgrade()
+          await this.abandonLegacyOwnerBridge(legacyBridge)
         } catch (failure) {
           abortError = failure instanceof Error ? failure : new Error(String(failure))
         }
       } else {
         this.guardian.disconnect()
+        legacyBridge?.legacyGuardian.disconnect()
       }
       if (committed) {
         const commitmentError = await committed
@@ -540,56 +561,74 @@ export default class RollbridgeDaemon {
   }
 
   /**
-   * Authenticates and prepares the one-time disruptive bridge for a genuine pre-split guardian.
-   * @param {{error: Error | string, persisted: OwnerRecoverySnapshot, persistedAuthority: {configDigest: string, runtime: import("./daemon-runtime.js").DaemonRuntimeIdentity | null}}} options - Legacy evidence.
+   * Authenticates and prepares the one-time disruptive bridge for an exact legacy guardian protocol.
+   * @param {{persisted: OwnerRecoverySnapshot, persistedAuthority: {configDigest: string, runtime: import("./daemon-runtime.js").DaemonRuntimeIdentity | null}}} options - Legacy evidence.
    * @returns {Promise<LegacyOwnerBridge>} Prepared bridge.
    */
-  async prepareLegacyOwnerReplacement({error, persisted, persistedAuthority}) {
-    const diagnostic = error instanceof Error ? error.message : String(error)
+  async prepareLegacyOwnerReplacement({persisted, persistedAuthority}) {
     const legacyProcessKey = ownerSnapshotProcessKeys(persisted, persisted.singletonReleaseIds)[0]
+    const legacyGuardian = this.guardian
+    let legacyPrepared
+
+    if (!legacyProcessKey) throw new Error("Legacy disruptive owner replacement requires an exact guardian-owned process registration in durable state")
+    if (!legacyGuardian) throw new Error("Legacy disruptive replacement is missing its authenticated guardian connection")
+    try {
+      legacyPrepared = await legacyGuardian.prepareOwnerReplacement(persistedAuthority, this.ownerAuthority())
+    } catch (error) {
+      const diagnostic = error instanceof Error ? error.message : String(error)
+
+      if (!isLegacyGuardianPrepareDiagnostic(diagnostic)) throw error
+      let probeAccepted = false
 
-    if (!isLegacyGuardianPrepareDiagnostic(diagnostic)) throw error
-    if (!legacyProcessKey) throw new Error("Legacy disruptive owner replacement requires an exact guardian-owned process registration in durable state", {cause: error})
-    if (diagnostic !== "Unknown guardian command: prepare-owner-replacement") {
       try {
-        await this.guardian?.request({
+        await legacyGuardian.request({
           authority: persistedAuthority,
           command: "prepare-owner-replacement",
           key: legacyProcessKey,
           nextAuthority: this.ownerAuthority()
         })
-        throw new Error("Legacy guardian protocol probe unexpectedly accepted owner replacement")
+        probeAccepted = true
       } catch (probeError) {
         if (!(probeError instanceof Error) || probeError.message !== "Unknown guardian command: prepare-owner-replacement") {
           throw new Error("Guardian does not match the authenticated pre-split replacement protocol signature", {cause: probeError})
         }
       }
+      if (probeAccepted) throw new Error("Legacy guardian protocol probe unexpectedly accepted owner replacement", {cause: error})
     }
-    if (persisted.recovery.configDigest !== this.ownerRecoveryConfigDigest()) {
-      throw new Error("The one-time legacy guardian bridge requires the incumbent config identity unchanged; retry the config change after the bridge establishes split-3 authority")
-    }
-    if (!this.legacyIncumbentPid) throw new Error("The authenticated pre-split guardian requires an exact incumbent PID from ensure-daemon for the disruptive bridge")
-    if (!this.guardianIdentity?.pid) throw new Error("The authenticated pre-split guardian state is missing its exact guardian PID")
-    const legacyGuardian = this.guardian
-
-    if (!legacyGuardian) throw new Error("Legacy disruptive replacement is missing its authenticated guardian connection")
-
-    await verifyLegacyGuardianProcess(this.guardianIdentity.pid, this.guardianIdentity.socketPath)
-    const incumbentStartTime = await verifyLegacyDaemonProcess(this.legacyIncumbentPid, this.configPath, persisted.control.path)
-    const incumbentControl = await openControlSession(persisted.control.path)
+    let incumbentControl
     let upgraded
 
     try {
-      const incumbentStatus = await incumbentControl.request({command: "status"})
+      if (persisted.recovery.configDigest !== this.ownerRecoveryConfigDigest()) {
+        throw new Error("The one-time legacy guardian bridge requires the incumbent config identity unchanged; retry the config change after the bridge establishes split-3 authority")
+      }
+      if (!this.legacyIncumbentPid) throw new Error("The authenticated legacy guardian requires an exact incumbent PID from ensure-daemon for the disruptive bridge")
+      if (!this.guardianIdentity?.pid) throw new Error("The authenticated legacy guardian state is missing its exact guardian PID")
+      await verifyLegacyGuardianProcess(this.guardianIdentity.pid, this.guardianIdentity.socketPath)
+      const incumbentStartTime = await verifyLegacyDaemonProcess(this.legacyIncumbentPid, this.configPath, persisted.control.path)
+      if (legacyPrepared) assertLegacyPrivateOwnerState(legacyPrepared.ownerState, persisted, persistedAuthority)
+      try {
+        incumbentControl = await openControlSession(persisted.control.path)
+      } catch (error) {
+        if (!legacyPrepared || !error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") throw error
+      }
+      if (incumbentControl) {
+        const incumbentStatus = await incumbentControl.request({command: "status"})
 
-      assertLegacyIncumbentStatus(incumbentStatus, persisted)
-      const ownerState = {
-        authority: persistedAuthority,
-        config: this.config,
-        releaseConfigs: Object.fromEntries(persisted.releases.map((release) => [release.releaseId, this.config])),
-        singletonReleaseIds: Object.fromEntries(persisted.singletons.map((singleton) => [singleton.id, persisted.activeReleaseId]).filter((entry) => entry[1] !== null)),
-        snapshot: persisted
+        assertLegacyIncumbentStatus(incumbentStatus, persisted)
       }
+      const ownerState = legacyPrepared
+        ? legacyPrepared.ownerState
+        : {
+            authority: persistedAuthority,
+            config: this.config,
+            releaseConfigs: Object.fromEntries(persisted.releases.map((release) => [release.releaseId, this.config])),
+            singletonReleaseIds: Object.fromEntries(persisted.singletons.map((singleton) => [singleton.id, persisted.activeReleaseId]).filter((entry) => entry[1] !== null)),
+            snapshot: persisted
+          }
+      const legacyInventory = normalizeLegacyGuardianInventory(await legacyGuardian.inventory())
+
+      assertLegacyGuardianInventoryMembership(legacyInventory, /** @type {PrivateOwnerState} */ (ownerState))
       const upgradedIdentity = /** @type {{pid?: number, socketPath: string, token: string}} */ ({
         socketPath: `${this.statePath}.split3-guardian.sock`,
         token: crypto.randomBytes(32).toString("hex")
@@ -598,7 +637,6 @@ export default class RollbridgeDaemon {
       await assertPathAbsent(upgradedIdentity.socketPath, "Legacy upgrade guardian socket")
       upgraded = await legacyGuardian.upgradeLegacyGuardian({ownerState, ...upgradedIdentity})
       upgradedIdentity.pid = upgraded.pid
-      legacyGuardian.disconnect()
       this.guardian = upgraded
       this.guardianIdentity = upgradedIdentity
       const prepared = await upgraded.prepareOwnerReplacement(persistedAuthority, this.ownerAuthority())
@@ -612,36 +650,102 @@ export default class RollbridgeDaemon {
         incumbentPid: this.legacyIncumbentPid,
         replacementId: prepared.replacementId
       })
-      return {boundaryCrossed: false, incumbentControl, incumbentStartTime, prepared, recoverySnapshot}
+      return {boundaryCrossed: false, incumbentControl, incumbentStartTime, legacyGuardian, legacyInventory, legacyPrepared, legacySnapshot: persisted, prepared, recoverySnapshot}
     } catch (upgradeError) {
-      incumbentControl.close()
-      if (upgraded) await upgraded.abandonLegacyUpgrade()
+      incumbentControl?.close()
+      let cleanupError
+
+      if (upgraded) {
+        try {
+          await upgraded.abandonLegacyUpgrade()
+        } catch (error) {
+          cleanupError = error instanceof Error ? error : new Error(String(error))
+        }
+      }
+      legacyGuardian.disconnect()
+      if (cleanupError) {
+        throw new AggregateError([upgradeError, cleanupError], "Legacy owner replacement validation failed and its upgrade coordinator could not be abandoned", {cause: upgradeError})
+      }
       throw upgradeError
     }
   }
 
+  /**
+   * Abandons the uncommitted coordinator before releasing the incumbent guardian transaction.
+   * @param {LegacyOwnerBridge} bridge - Prepared bridge.
+   */
+  async abandonLegacyOwnerBridge(bridge) {
+    let cleanupError
+
+    try {
+      await this.guardian?.abandonLegacyUpgrade()
+    } catch (error) {
+      cleanupError = error instanceof Error ? error : new Error(String(error))
+    }
+    bridge.legacyGuardian.disconnect()
+    if (cleanupError) throw cleanupError
+  }
+
   /**
    * Crosses the explicitly disruptive legacy-only boundary after candidate reconstruction.
    * @param {LegacyOwnerBridge} bridge - Prepared bridge.
    */
   async crossLegacyDisruptiveBoundary(bridge) {
     if (!this.legacyIncumbentPid || !this.statePath) throw new Error("Legacy disruptive boundary is missing its exact incumbent identity")
+    if (!this.guardian) throw new Error("Legacy disruptive boundary is missing its authenticated upgraded guardian")
+    if (!bridge.legacyGuardian.pid) throw new Error("Legacy disruptive boundary is missing its authenticated retained guardian PID")
+    await verifyLegacyGuardianProcess(bridge.legacyGuardian.pid, bridge.legacyGuardian.socketPath)
     const currentStartTime = await verifyLegacyDaemonProcess(this.legacyIncumbentPid, this.configPath, bridge.recoverySnapshot.control.path)
 
     if (currentStartTime !== bridge.incumbentStartTime) throw new Error("Legacy incumbent PID identity changed before the disruptive boundary")
+    if (!isDeepStrictEqual(await readState(this.statePath), bridge.legacySnapshot)) {
+      throw new Error("Legacy owner recovery state changed before the disruptive boundary")
+    }
+    if (bridge.incumbentControl) {
+      assertLegacyIncumbentStatus(await bridge.incumbentControl.request({command: "status"}), bridge.legacySnapshot)
+    }
+    const currentInventory = normalizeLegacyGuardianInventory(await bridge.legacyGuardian.inventory())
+
+    if (!isDeepStrictEqual(currentInventory, bridge.legacyInventory)) {
+      throw new Error("Legacy guardian process inventory changed before the disruptive boundary")
+    }
+    const candidateOwnerState = {
+      authority: this.ownerAuthority(),
+      config: this.config,
+      releaseConfigs: Object.fromEntries([...this.releases].map(([releaseId, release]) => [releaseId, release.config])),
+      singletonReleaseIds: Object.fromEntries(this.singletonReleaseIds),
+      snapshot: this.status()
+    }
+
+    assertLegacyGuardianInventoryMembership(currentInventory, candidateOwnerState)
+    let legacyCommitted
+
+    if (bridge.legacyPrepared) {
+      const status = await bridge.legacyGuardian.replacementStatus()
+
+      if (!status.ownerClaimed) throw new Error("Legacy guardian incumbent ownership changed before the disruptive boundary")
+      legacyCommitted = bridge.legacyGuardian.waitForEvent("replacement-committed")
+      const staged = await bridge.legacyGuardian.stageOwnerReplacement(bridge.legacyPrepared.replacementId, candidateOwnerState)
+
+      if (staged.committed) throw new Error("Legacy guardian committed replacement before the authenticated disruptive boundary")
+    }
     this.logger("legacy owner replacement disruptive boundary", {
       disruptive: true,
       incumbentPid: this.legacyIncumbentPid,
-      reason: "pre-split guardian and daemon lacked atomic replacement protocol"
+      reason: "retained guardian and daemon lacked atomic replacement protocol"
     })
+    await this.guardian.beginLegacyOwnerClaim(bridge.prepared.replacementId, bridge.recoverySnapshot.recovery.reconnectGraceMs)
     process.kill(this.legacyIncumbentPid, "SIGKILL")
     bridge.boundaryCrossed = true
-    await bridge.incumbentControl.closed()
+    await bridge.incumbentControl?.closed()
+    if (legacyCommitted) await legacyCommitted
+    bridge.legacyGuardian.disconnect()
+    await this.guardian.completeLegacyOwnerClaim(bridge.prepared.replacementId)
     await writeState(this.statePath, bridge.recoverySnapshot)
     this.ownerTransition = /** @type {OwnerTransition} */ ({
       disruptive: true,
       mode: "legacy-first-upgrade",
-      reason: "pre-split guardian and daemon lacked atomic replacement protocol"
+      reason: "retained guardian and daemon lacked atomic replacement protocol"
     })
   }
 
@@ -1998,7 +2102,7 @@ export function isLegacyGuardianPrepareDiagnostic(diagnostic) {
 }
 
 /**
- * @param {OwnerRecoverySnapshot} snapshot - Durable committed owner snapshot.
+ * @param {DaemonStatus} snapshot - Serialized owner process snapshot.
  * @param {Record<string, string>} [singletonReleaseIds] - Exact singleton owner releases.
  * @returns {string[]} Exact guardian registration keys present in the snapshot.
  */
@@ -2017,6 +2121,40 @@ function ownerSnapshotProcessKeys(snapshot, singletonReleaseIds = {}) {
   return keys
 }
 
+/**
+ * Canonicalizes the authenticated guardian inventory without relying on map insertion order.
+ * @param {{key: string, provenance: string}[]} inventory - Guardian inventory response.
+ * @returns {{key: string, provenance: string}[]} Exact key/provenance fence.
+ */
+function normalizeLegacyGuardianInventory(inventory) {
+  const normalized = inventory.map((entry) => {
+    if (!entry || typeof entry.key !== "string" || !entry.key || typeof entry.provenance !== "string" || !entry.provenance) {
+      throw new Error("Legacy guardian returned an invalid process inventory")
+    }
+    return {key: entry.key, provenance: entry.provenance}
+  }).sort((left, right) => left.key.localeCompare(right.key))
+
+  if (new Set(normalized.map(({key}) => key)).size !== normalized.length) {
+    throw new Error("Legacy guardian returned duplicate process registrations")
+  }
+  return normalized
+}
+
+/**
+ * Requires every and only the process registrations serialized by committed private owner state.
+ * @param {{key: string, provenance: string}[]} inventory - Canonical guardian inventory.
+ * @param {{snapshot: DaemonStatus, singletonReleaseIds?: Record<string, string>}} ownerState - Authenticated owner process snapshot.
+ */
+function assertLegacyGuardianInventoryMembership(inventory, ownerState) {
+  if (!ownerState?.snapshot) throw new Error("Legacy guardian owner state is missing its committed process snapshot")
+  const inventoryKeys = inventory.map(({key}) => key)
+  const snapshotKeys = ownerSnapshotProcessKeys(ownerState.snapshot, ownerState.singletonReleaseIds).sort((left, right) => left.localeCompare(right))
+
+  if (!isDeepStrictEqual(inventoryKeys, snapshotKeys)) {
+    throw new Error("Legacy guardian process inventory does not match committed owner state")
+  }
+}
+
 /**
  * Verifies the exact authenticated guardian process and socket without scanning other PIDs.
  * @param {number} pid - Persisted guardian PID.
@@ -2026,7 +2164,7 @@ async function verifyLegacyGuardianProcess(pid, socketPath) {
   const args = await processArguments(pid, "legacy guardian")
   const script = args.find((argument) => argument.endsWith("process-guardian.js"))
 
-  if (!script || !args.includes(socketPath)) throw new Error(`Persisted guardian PID ${pid} does not match the pre-split guardian command and socket`)
+  if (!script || !args.includes(socketPath)) throw new Error(`Persisted guardian PID ${pid} does not match the retained guardian command and socket`)
   await verifyProcessUser(pid, "legacy guardian")
   await verifyUnixSocketOwner(pid, socketPath, "legacy guardian")
 }
@@ -2045,7 +2183,7 @@ async function verifyLegacyDaemonProcess(pid, configPath, socketPath) {
   const configIndex = args.indexOf("--config")
 
   if (daemonIndex < 0 || configIndex < 0 || args[configIndex + 1] !== configPath) {
-    throw new Error(`Daemon PID ${pid} does not match the exact pre-split daemon config command`)
+    throw new Error(`Daemon PID ${pid} does not match the exact retained daemon config command`)
   }
   await verifyProcessUser(pid, "legacy daemon")
   await verifyUnixSocketOwner(pid, socketPath, "legacy daemon")
@@ -2121,10 +2259,38 @@ function assertLegacyIncumbentStatus(status, persisted) {
   if (status.application !== persisted.application || !control || typeof control !== "object" || Array.isArray(control) || control.path !== persisted.control.path ||
     !runtime || typeof runtime !== "object" || Array.isArray(runtime) || runtime.digest !== persisted.daemonRuntime?.digest ||
     !ownerRecovery || typeof ownerRecovery !== "object" || Array.isArray(ownerRecovery) || ownerRecovery.configDigest !== persisted.recovery.configDigest) {
-    throw new Error("Responsive incumbent does not match the exact persisted pre-split daemon authority")
+    throw new Error("Responsive incumbent does not match the exact persisted retained-daemon authority")
   }
 }
 
+/**
+ * Validates private committed state returned by a partial transaction guardian.
+ * @param {JsonValue} value - Authenticated guardian owner state.
+ * @param {OwnerRecoverySnapshot} persisted - Durable expected identity.
+ * @param {{configDigest: string, runtime: import("./daemon-runtime.js").DaemonRuntimeIdentity | null}} persistedAuthority - Exact committed authority.
+ */
+function assertLegacyPrivateOwnerState(value, persisted, persistedAuthority) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Partial legacy guardian returned invalid committed owner state")
+  const state = /** @type {Record<string, JsonValue>} */ (value)
+  const config = state.config
+  const snapshot = state.snapshot
+
+  if (!isDeepStrictEqual(state.authority, persistedAuthority) || !config || typeof config !== "object" || Array.isArray(config) ||
+    ownerConfigDigest(/** @type {import("./config.js").RollbridgeConfig} */ (config)) !== persistedAuthority.configDigest ||
+    !snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) {
+    throw new Error("Partial legacy guardian committed owner state does not match the persisted authority")
+  }
+  const privateSnapshot = /** @type {OwnerRecoverySnapshot} */ (snapshot)
+
+  assertLegacyIncumbentStatus(/** @type {Record<string, JsonValue>} */ (snapshot), persisted)
+  if (!isDeepStrictEqual(
+    ownerSnapshotProcessKeys(privateSnapshot, state.singletonReleaseIds && typeof state.singletonReleaseIds === "object" && !Array.isArray(state.singletonReleaseIds)
+      ? /** @type {Record<string, string>} */ (state.singletonReleaseIds)
+      : {}).sort(),
+    ownerSnapshotProcessKeys(persisted, persisted.singletonReleaseIds).sort()
+  )) throw new Error("Partial legacy guardian committed process membership does not match durable recovery state")
+}
+
 /**
  * @param {string} candidatePath - Path that must not preexist.
  * @param {string} label - Diagnostic label.