rollbridge 0.1.35 → 0.1.37

package/src/guardian-client.js

@@ -21,6 +21,8 @@ export default class GuardianClient {
     this.idleWaiters = /** @type {(() => void)[]} */ ([])
     this.guardianExitPromise = /** @type {Promise<void> | undefined} */ (undefined)
     this.processes = /** @type {Map<string, GuardianProcess>} */ (new Map())
+    this.reservedProcessKey = /** @type {string | undefined} */ (undefined)
+    this.reservedProcessProvenance = /** @type {string | undefined} */ (undefined)
     this.events = /** @type {Map<string, {reject: (error: Error) => void, resolve: (value: Record<string, import("./json.js").JsonValue>) => void}[]>} */ (new Map())
     this.eventHandlers = /** @type {Map<string, ((event: Record<string, import("./json.js").JsonValue>) => void)[]>} */ (new Map())
   }
@@ -52,7 +54,7 @@ export default class GuardianClient {
   }
 
   /**
-   * Starts a current transaction guardian in front of this authenticated pre-split guardian.
+   * Starts a current transaction guardian in front of this authenticated legacy guardian.
    * @param {{ownerState: import("./json.js").JsonValue, socketPath: string, token: string}} options - Upgrade identity and exact committed state.
    * @returns {Promise<GuardianClient>} Current guardian client backed by the legacy supervisor.
    */
@@ -111,6 +113,27 @@ export default class GuardianClient {
     return processInstance
   }
 
+  /**
+   * @param {string} key - Exact committed-owner registration reserved until replacement commit.
+   * @param {string} provenance - Guardian-inventoried definition fence.
+   */
+  reserveProcessRecovery(key, provenance) {
+    if (this.reservedProcessKey) throw new Error(`Guardian process recovery ${this.reservedProcessKey} is already reserved`)
+    this.reservedProcessKey = key
+    this.reservedProcessProvenance = provenance
+  }
+
+  /** @param {string} key - Exact reserved registration to attach after authority commits. */
+  async recoverReservedProcess(key) {
+    if (this.reservedProcessKey !== key) throw new Error(`Guardian process recovery ${key} is not reserved`)
+    const processInstance = this.processes.get(key)
+
+    if (!processInstance) throw new Error(`Reserved guardian process ${key} was not reconstructed`)
+    await processInstance.attachReserved()
+    this.reservedProcessKey = undefined
+    this.reservedProcessProvenance = undefined
+  }
+
   /**
    * @param {Record<string, import("./json.js").JsonValue>} command - Command.
    * @returns {Promise<import("./json.js").JsonValue>} Guardian response.
@@ -166,6 +189,32 @@ export default class GuardianClient {
     await this.request({command: "publish-owner-state", ownerState})
   }
 
+  /**
+   * Classifies the authenticated guardian's owner-replacement protocol without preparing a transaction.
+   * @returns {Promise<"atomic" | "legacy">} Compatible replacement route.
+   */
+  async ownerReplacementProtocol() {
+    try {
+      const response = await this.request({command: "owner-replacement-capabilities"})
+
+      if (!isOwnerReplacementCapabilities(response)) throw new Error("Guardian returned an invalid owner-replacement capability response")
+      return "atomic"
+    } catch (error) {
+      if (!(error instanceof Error) || !isLegacyCapabilityDispatchDiagnostic(error.message)) throw error
+    }
+
+    try {
+      await this.request({command: "commit-retired-owner-replacement", replacementId: "owner-replacement-capability-probe"})
+      throw new Error("Guardian unexpectedly accepted the retired-owner capability probe")
+    } catch (error) {
+      if (!(error instanceof Error)) throw error
+      if (error.message === "Owner replacement transaction is not the prepared candidate") return "atomic"
+      if (error.message === "Guardian commit-retired-owner-replacement requires a process key" ||
+        error.message === "Unknown guardian command: commit-retired-owner-replacement") return "legacy"
+      throw new Error("Guardian returned an ambiguous retired-owner capability response", {cause: error})
+    }
+  }
+
   /**
    * @param {import("./json.js").JsonValue} authority - Persisted current authority.
    * @param {import("./json.js").JsonValue} nextAuthority - Requested authority.
@@ -202,6 +251,23 @@ export default class GuardianClient {
     await this.request({command: "commit-retired-owner-replacement", key, replacementId})
   }
 
+  /**
+   * Begins acquiring the authenticated legacy backend owner channel at the disruptive boundary.
+   * @param {string} replacementId - Exact prepared candidate transaction.
+   * @param {number} graceMs - Event-driven incumbent disconnect grace.
+   */
+  async beginLegacyOwnerClaim(replacementId, graceMs) {
+    await this.request({command: "begin-legacy-owner-claim", graceMs, replacementId})
+  }
+
+  /**
+   * Waits until the upgraded guardian owns its authenticated legacy backend.
+   * @param {string} replacementId - Exact prepared candidate transaction.
+   */
+  async completeLegacyOwnerClaim(replacementId) {
+    await this.request({command: "complete-legacy-owner-claim", replacementId})
+  }
+
   /** @param {string} replacementId - Committed transaction awaiting incumbent retirement. */
   async finalizeOwnerReplacement(replacementId) {
     await this.request({command: "finalize-owner-replacement", replacementId})
@@ -354,6 +420,16 @@ class GuardianProcess extends ManagedProcess {
 
   /** Reconnects to an already registered guardian process without changing its desired state. */
   async recover() {
+    if (this.client.reservedProcessKey === this.key) {
+      if (this.client.reservedProcessProvenance !== this.provenance) throw new Error(`Guardian provenance mismatch for reserved process ${this.key}`)
+      this.cachedStatus = asProcessStatus(await this.client.request({command: "status", key: this.key}))
+      return
+    }
+    await this.ensureRegistered()
+  }
+
+  /** Attaches a reconstructed process whose incumbent-owned registration was reserved through commit. */
+  async attachReserved() {
     await this.ensureRegistered()
   }
 
@@ -463,6 +539,28 @@ function asProcessStatus(value) {
   return JSON.parse(JSON.stringify(value))
 }
 
+/**
+ * @param {import("./json.js").JsonValue} value - Capability response.
+ * @returns {boolean} Whether the response explicitly guarantees retired-owner commit support.
+ */
+function isOwnerReplacementCapabilities(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false
+  const response = /** @type {Record<string, import("./json.js").JsonValue>} */ (value)
+
+  return response.protocol === "owner-replacement" && Number.isInteger(response.version) && Number(response.version) >= 1 &&
+    Array.isArray(response.commands) && response.commands.every((command) => typeof command === "string") &&
+    response.commands.includes("commit-retired-owner-replacement")
+}
+
+/**
+ * @param {string} diagnostic - Exact old generic-dispatch response.
+ * @returns {boolean} Whether this is the narrow old unknown-command dispatch signature.
+ */
+function isLegacyCapabilityDispatchDiagnostic(diagnostic) {
+  return diagnostic === "Guardian owner-replacement-capabilities requires a process key" ||
+    diagnostic === "Unknown guardian command: owner-replacement-capabilities"
+}
+
 /**
  * @param {import("./json.js").JsonValue} value - Protocol value.
  * @returns {import("./managed-process.js").ManagedProcessLog} Process output entry.

package/src/process-guardian.js

@@ -77,6 +77,8 @@ let ownerMutationId
 let retiringClient
 /** @type {string | undefined} */
 let retiringReplacementId
+/** @type {Promise<Error | undefined> | undefined} */
+let legacyOwnerClaim
 let shuttingDown = false
 /** @type {net.Socket | undefined} */
 let shutdownClient
@@ -117,11 +119,7 @@ const server = net.createServer((socket) => {
     }
     if (retiringClient === socket) finalizeReplacementRetirement()
     if (replacementClient === socket) {
-      replacementClient = undefined
-      replacementId = undefined
-      replacementAuthority = undefined
-      replacementOwnerState = undefined
-      if (ownerClient && !ownerClient.destroyed) ownerClient.write(`${JSON.stringify({event: "replacement-aborted"})}\n`)
+      abortReplacement("Replacement candidate disconnected before commit")
     }
     if (shutdownClient === socket) void finishShutdown()
   })
@@ -180,6 +178,10 @@ async function handleLine(socket, line) {
 async function execute(request, socket) {
   if (shuttingDown) throw new Error("Process guardian is shutting down")
 
+  if (request.command === "owner-replacement-capabilities") {
+    return {commands: ["commit-retired-owner-replacement"], protocol: "owner-replacement", version: 1}
+  }
+
   if (request.command === "claim-owner") {
     if (!ownerClient) {
       if (ownerState !== undefined && !isDeepStrictEqual(request.authority, ownerAuthority(ownerState))) {
@@ -225,6 +227,26 @@ async function execute(request, socket) {
     return {abandoned: true}
   }
 
+  if (request.command === "begin-legacy-owner-claim") {
+    if (!legacyGuardian) throw new Error("Guardian is not a legacy upgrade coordinator")
+    requireReplacement(socket, request)
+    if (legacyOwnerClaim) throw new Error("Legacy guardian owner claim is already pending")
+    legacyOwnerClaim = legacyGuardian.claimOwner(request.graceMs ?? 30000, ownerAuthority(ownerState)).then(
+      () => undefined,
+      (error) => error instanceof Error ? error : new Error(String(error))
+    )
+    return {prepared: true}
+  }
+
+  if (request.command === "complete-legacy-owner-claim") {
+    if (!legacyGuardian || !legacyOwnerClaim) throw new Error("Legacy guardian owner claim was not prepared")
+    requireReplacement(socket, request)
+    const claimError = await legacyOwnerClaim
+
+    if (claimError) throw claimError
+    return {claimed: true}
+  }
+
   if (request.command === "publish-owner-state") {
     requireOwner(socket, request.command)
     if (request.ownerState === undefined) throw new Error("Guardian owner publication requires ownerState")
@@ -470,7 +492,10 @@ function requireOwner(socket, command) {
 
 /** @param {string} reason - Abort diagnostic. */
 function abortReplacement(reason) {
-  if (replacementClient && !replacementClient.destroyed) replacementClient.write(`${JSON.stringify({event: "replacement-aborted", reason})}\n`)
+  const event = `${JSON.stringify({event: "replacement-aborted", reason})}\n`
+
+  if (replacementClient && !replacementClient.destroyed) replacementClient.write(event)
+  if (ownerClient && !ownerClient.destroyed) ownerClient.write(event)
   replacementClient = undefined
   replacementId = undefined
   replacementAuthority = undefined

package/test/fixtures/partial-owner-replacement-process-guardian.js

@@ -0,0 +1,106 @@
+// @ts-check
+
+import fs from "node:fs/promises"
+import net from "node:net"
+
+const [socketPath, backendPath, mode = "partial"] = process.argv.slice(2)
+
+if (!socketPath || !backendPath || !process.send) throw new Error("partial process-guardian requires frontend and backend sockets plus a private bootstrap channel")
+
+const token = await new Promise((resolve, reject) => {
+  process.once("disconnect", () => reject(new Error("Partial guardian bootstrap channel closed before authentication capability arrived")))
+  process.once("message", (message) => {
+    if (!message || typeof message !== "object" || !("token" in message) || typeof message.token !== "string" || !message.token) {
+      reject(new Error("Partial guardian bootstrap authentication capability is invalid"))
+      return
+    }
+    resolve(message.token)
+  })
+})
+
+const clients = new Set()
+const server = net.createServer((frontend) => {
+  const backend = net.createConnection(backendPath)
+  let frontendBuffer = ""
+  let backendBuffer = ""
+
+  clients.add(frontend)
+  frontend.setEncoding("utf8")
+  backend.setEncoding("utf8")
+  frontend.on("error", () => frontend.destroy())
+  backend.on("error", () => backend.destroy())
+  frontend.once("close", () => {
+    clients.delete(frontend)
+    backend.destroy()
+  })
+  backend.once("close", () => frontend.destroy())
+  frontend.on("data", (chunk) => {
+    frontendBuffer += chunk
+    let newline = frontendBuffer.indexOf("\n")
+
+    while (newline >= 0) {
+      const line = frontendBuffer.slice(0, newline)
+      const request = JSON.parse(line)
+
+      frontendBuffer = frontendBuffer.slice(newline + 1)
+      if (request.token !== token) {
+        frontend.write(`${JSON.stringify({error: "Guardian authentication failed", id: request.id})}\n`)
+      } else if (request.command === "owner-replacement-capabilities") {
+        const result = mode === "malformed-capability"
+          ? {protocol: "owner-replacement", version: 1}
+          : undefined
+
+        frontend.write(`${JSON.stringify(result
+          ? {id: request.id, result}
+          : {error: "Guardian owner-replacement-capabilities requires a process key", id: request.id})}\n`)
+      } else if (request.command === "commit-retired-owner-replacement") {
+        frontend.write(`${JSON.stringify({
+          error: request.key
+            ? "Guardian commit-retired-owner-replacement requires the committed owner"
+            : "Guardian commit-retired-owner-replacement requires a process key",
+          id: request.id
+        })}\n`)
+      } else {
+        if (mode === "wrong-provenance" && request.command === "register") {
+          request.provenance = `${request.provenance}-tampered`
+          backend.write(`${JSON.stringify(request)}\n`)
+        } else {
+          backend.write(`${line}\n`)
+        }
+      }
+      newline = frontendBuffer.indexOf("\n")
+    }
+  })
+  backend.on("data", (chunk) => {
+    backendBuffer += chunk
+    let newline = backendBuffer.indexOf("\n")
+
+    while (newline >= 0) {
+      const line = backendBuffer.slice(0, newline)
+
+      backendBuffer = backendBuffer.slice(newline + 1)
+      frontend.write(`${line}\n`)
+      newline = backendBuffer.indexOf("\n")
+    }
+  })
+})
+
+server.on("error", (error) => {
+  if (process.send) process.send({error: error.message})
+  else throw error
+})
+server.listen(socketPath, async () => {
+  await fs.chmod(socketPath, 0o600)
+  process.send?.({ready: true})
+  process.disconnect?.()
+})
+
+const shutdown = () => {
+  for (const client of clients) client.destroy()
+  server.close(() => {
+    void fs.rm(socketPath, {force: true}).finally(() => process.exit(0))
+  })
+}
+
+process.once("SIGINT", shutdown)
+process.once("SIGTERM", shutdown)

package/test/guardian-client.test.js

@@ -210,6 +210,32 @@ test("replacement staging rejects owner state published after prepare", async ()
   }
 })
 
+test("replacement abort notifies both the candidate and committed owner", async () => {
+  const fixture = await createGuardian()
+  const candidate = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})
+  const authority = {configDigest: "incumbent", runtime: null}
+  const nextAuthority = {configDigest: "candidate", runtime: null}
+
+  try {
+    await fixture.client.publishOwnerState({authority, snapshot: {activeReleaseId: "v1"}})
+    await candidate.connect()
+    const prepared = await candidate.prepareOwnerReplacement(authority, nextAuthority)
+    const incumbentAborted = fixture.client.waitForEvent("replacement-aborted")
+    const candidateAborted = candidate.waitForEvent("replacement-aborted")
+
+    await candidate.abortOwnerReplacement(prepared.replacementId)
+    assert.deepEqual(await Promise.all([incumbentAborted, candidateAborted]), [
+      {event: "replacement-aborted", reason: "Replacement candidate aborted the prepared transaction"},
+      {event: "replacement-aborted", reason: "Replacement candidate aborted the prepared transaction"}
+    ])
+    await fixture.client.shutdown()
+    await fixture.client.guardianExit()
+  } finally {
+    candidate.disconnect()
+    await cleanupGuardian(fixture)
+  }
+})
+
 test("retired owner replacement commit carries its exact recovered process key", async () => {
   const client = new GuardianClient({socketPath: "/unused", token: "authenticated-capability"})
   const replacementId = "prepared-replacement"
@@ -224,6 +250,77 @@ test("retired owner replacement commit carries its exact recovered process key",
   await client.commitRetiredOwnerReplacement(replacementId, processKey)
 })
 
+test("guardian owner-replacement capability classification is explicit and fail closed", async () => {
+  const current = new GuardianClient({socketPath: "/unused", token: "authenticated-capability"})
+
+  current.request = async (request) => {
+    assert.deepEqual(request, {command: "owner-replacement-capabilities"})
+    return {
+      commands: ["commit-retired-owner-replacement", "future-command"],
+      futureField: {supported: true},
+      protocol: "owner-replacement",
+      version: 2
+    }
+  }
+  assert.equal(await current.ownerReplacementProtocol(), "atomic")
+
+  for (const [commitDiagnostic, expected] of [
+    ["Owner replacement transaction is not the prepared candidate", "atomic"],
+    ["Guardian commit-retired-owner-replacement requires a process key", "legacy"],
+    ["Unknown guardian command: commit-retired-owner-replacement", "legacy"]
+  ]) {
+    const older = new GuardianClient({socketPath: "/unused", token: "authenticated-capability"})
+    const requests = /** @type {Record<string, import("../src/json.js").JsonValue>[]} */ ([])
+
+    older.request = async (request) => {
+      requests.push(request)
+      if (request.command === "owner-replacement-capabilities") throw new Error("Guardian owner-replacement-capabilities requires a process key")
+      throw new Error(commitDiagnostic)
+    }
+    assert.equal(await older.ownerReplacementProtocol(), expected)
+    assert.deepEqual(requests, [
+      {command: "owner-replacement-capabilities"},
+      {command: "commit-retired-owner-replacement", replacementId: "owner-replacement-capability-probe"}
+    ])
+  }
+
+  for (const fixture of [
+    async () => ({commands: [], protocol: "owner-replacement", version: 1}),
+    async (/** @type {Record<string, import("../src/json.js").JsonValue>} */ request) => {
+      if (request.command === "owner-replacement-capabilities") throw new Error("Guardian owner-replacement-capabilities requires a process key")
+      throw new Error("Guardian commit-retired-owner-replacement requires the committed owner")
+    }
+  ]) {
+    const ambiguous = new GuardianClient({socketPath: "/unused", token: "authenticated-capability"})
+
+    ambiguous.request = fixture
+    await assert.rejects(() => ambiguous.ownerReplacementProtocol(), /invalid owner-replacement capability response|ambiguous retired-owner capability response/)
+  }
+})
+
+test("reserved process recovery rejects a reconstructed definition with different provenance", async () => {
+  const fixture = await createGuardian()
+  const candidate = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})
+  const processKey = "release:v1:worker"
+
+  try {
+    await fixture.client.process(processKey, definition("worker")).recover()
+    const [registration] = await fixture.client.inventory()
+
+    assert.ok(registration)
+    await candidate.connect()
+    candidate.reserveProcessRecovery(processKey, registration.provenance)
+    await assert.rejects(
+      () => candidate.process(processKey, definition("different-worker")).recover(),
+      /provenance mismatch for reserved process/
+    )
+    assert.deepEqual((await fixture.client.inventory()).map(({key}) => key), [processKey])
+  } finally {
+    candidate.disconnect()
+    await cleanupGuardian(fixture)
+  }
+})
+
 test("retired owner replacement rejects a registered process absent from committed owner state", async () => {
   const fixture = await createGuardian()
   const candidate = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})