rollbridge 0.1.30 → 0.1.32

package/src/guardian-client.js

@@ -194,6 +194,11 @@ export default class GuardianClient {
     await this.request({command: "commit-owner-replacement", replacementId})
   }
 
+  /** @param {string} replacementId - Same-authority transaction whose incumbent listener is absent. */
+  async commitRetiredOwnerReplacement(replacementId) {
+    await this.request({command: "commit-retired-owner-replacement", replacementId})
+  }
+
   /** @param {string} replacementId - Committed transaction awaiting incumbent retirement. */
   async finalizeOwnerReplacement(replacementId) {
     await this.request({command: "finalize-owner-replacement", replacementId})
@@ -305,7 +310,7 @@ export default class GuardianClient {
 
       this.buffer = this.buffer.slice(newline + 1)
       if (message.event) {
-        if (message.event === "process" || message.event === "status") this.processes.get(message.key)?.onGuardianEvent(message)
+        if (message.event === "process" || message.event === "process-log" || message.event === "status") this.processes.get(message.key)?.onGuardianEvent(message)
         for (const handler of this.eventHandlers.get(message.event) || []) handler(message)
         const waiter = this.events.get(message.event)?.shift()
 
@@ -349,10 +354,15 @@ class GuardianProcess extends ManagedProcess {
     await this.ensureRegistered()
   }
 
-  async start(reason = "deploy") {
+  /**
+   * @param {import("./managed-process.js").ManagedProcessStartReason} [reason] - Start reason.
+   * @param {import("./managed-process.js").LifecycleRole} [lifecycleRole] - Desired role restored before running.
+   */
+  async start(reason = "deploy", lifecycleRole) {
     await this.ensureRegistered()
     await this.pendingUpdate
-    this.cachedStatus = asProcessStatus(await this.client.request({command: "start", key: this.key, reason}))
+    if (lifecycleRole) this.lifecycleRole = lifecycleRole
+    this.cachedStatus = asProcessStatus(await this.client.request({command: "start", key: this.key, lifecycleRole, reason}))
   }
 
   /** @param {import("./managed-process.js").ManagedProcessDefinition} definition - Updated definition. */
@@ -378,6 +388,27 @@ class GuardianProcess extends ManagedProcess {
     await this.quiesce()
   }
 
+  async requiesceStrict() {
+    await this.ensureRegistered()
+    await this.pendingUpdate
+    this.cachedStatus = asProcessStatus(await this.client.request({command: "requiesce", key: this.key}))
+  }
+
+  async activateStrict() {
+    await this.ensureRegistered()
+    await this.pendingUpdate
+    this.cachedStatus = asProcessStatus(await this.client.request({command: "activate", key: this.key}))
+    this.lifecycleRole = "active"
+  }
+
+  /** @param {import("./managed-process.js").LifecycleRole} role - Exact generation role. */
+  async setLifecycleRole(role) {
+    await this.ensureRegistered()
+    await this.pendingUpdate
+    this.cachedStatus = asProcessStatus(await this.client.request({command: "set-lifecycle-role", key: this.key, lifecycleRole: role}))
+    this.lifecycleRole = role
+  }
+
   async stop(options = {}) {
     await this.ensureRegistered()
     await this.pendingUpdate
@@ -391,6 +422,10 @@ class GuardianProcess extends ManagedProcess {
   /** @param {Record<string, import("./json.js").JsonValue>} event - Guardian event. */
   onGuardianEvent(event) {
     if (event.status) this.cachedStatus = asProcessStatus(event.status)
+    if (event.event === "process-log") {
+      this.emit("log", asProcessLog(event.entry))
+      return
+    }
     if (event.message === "process started") this.emit("started")
     if (event.message === "process exited") this.emit("exit", event.data)
     this.logger(typeof event.message === "string" ? event.message : "guardian process status", event.data && typeof event.data === "object" && !Array.isArray(event.data) ? event.data : {})
@@ -425,6 +460,14 @@ function asProcessStatus(value) {
   return JSON.parse(JSON.stringify(value))
 }
 
+/**
+ * @param {import("./json.js").JsonValue} value - Protocol value.
+ * @returns {import("./managed-process.js").ManagedProcessLog} Process output entry.
+ */
+function asProcessLog(value) {
+  return JSON.parse(JSON.stringify(value))
+}
+
 /**
  * @param {Error | string} error - Error-like value.
  * @returns {string} Error message.

package/src/managed-process.js

@@ -4,15 +4,18 @@ import {EventEmitter} from "node:events"
 import {spawn} from "node:child_process"
 import {processGroupHasLiveMembers, processGroupMembers} from "./process-memory.js"
 
+const ACTIVATION_HOOK_TIMEOUT_MS = 30000
+
 /**
  * @typedef {import("./json.js").JsonValue} JsonValue
  * @typedef {"starting" | "running" | "quiesced" | "stopping" | "stopped" | "failed"} ManagedProcessState
  * @typedef {"deploy" | "crash" | "manual" | "memory"} ManagedProcessStartReason
+ * @typedef {"active" | "candidate" | "retired"} LifecycleRole
  * @typedef {import("node:child_process").ChildProcess["signalCode"]} ProcessExitSignal
  * @typedef {{at: string, line: string, stream: "stdout" | "stderr"}} ManagedProcessLog
  * @typedef {import("./config.js").StopTimeoutMs} StopTimeoutMs
  * @typedef {{command: string, cwd: string | undefined, env: Record<string, string | undefined>, lifecycle: import("./config.js").LifecycleConfig, logger: (message: string, data?: Record<string, import("./json.js").JsonValue>) => void, memory: import("./config.js").MemoryConfig | undefined, outputLines: number, restart: import("./config.js").RestartConfig, restartDelayMs: number, shouldRestart: () => boolean, stopSignal: string, stopTimeoutMs: StopTimeoutMs}} ManagedProcessDefinition
- * @typedef {{children: import("./process-memory.js").ProcessGroupMember[], command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, lastMemoryRestartAt: string | undefined, lastStartReason: ManagedProcessStartReason | undefined, logs: ManagedProcessLog[], memoryRestarts: number, pid: number | undefined, restarts: number, rssBytes: number | undefined, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
+ * @typedef {{children: import("./process-memory.js").ProcessGroupMember[], command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, lastMemoryRestartAt: string | undefined, lastStartReason: ManagedProcessStartReason | undefined, lifecycleRole?: LifecycleRole, logs: ManagedProcessLog[], memoryRestarts: number, pid: number | undefined, restarts: number, rssBytes: number | undefined, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
  */
 
 export default class ManagedProcess extends EventEmitter {
@@ -62,6 +65,7 @@ export default class ManagedProcess extends EventEmitter {
     this.memoryWarned = false
     this.startedAtMs = /** @type {number | undefined} */ (undefined)
     this.intentionalStop = false
+    this.lifecycleRole = /** @type {LifecycleRole} */ ("candidate")
     this.intentionalStopSignal = /** @type {ProcessExitSignal | undefined} */ (undefined)
     this.quiescePromise = /** @type {Promise<void> | undefined} */ (undefined)
     this.quiesceError = /** @type {Error | undefined} */ (undefined)
@@ -76,9 +80,11 @@ export default class ManagedProcess extends EventEmitter {
 
   /**
    * @param {ManagedProcessStartReason} [reason] - Why the process is being started (deploy by default; "crash" on auto-restart, "manual" via the restart command).
-   * @returns {Promise<void>} Resolves after spawn.
+   * @param {LifecycleRole} [lifecycleRole] - Exact desired role to restore before reporting the process running.
+   * @returns {Promise<void>} Resolves after spawn and lifecycle-role restoration.
    */
-  async start(reason = "deploy") {
+  async start(reason = "deploy", lifecycleRole) {
+    if (lifecycleRole) this.lifecycleRole = lifecycleRole
     if (this.child) return
 
     this.intentionalStop = false
@@ -109,16 +115,35 @@ export default class ManagedProcess extends EventEmitter {
       })
 
       child.once("spawn", () => {
-        this.state = "running"
-        this.startedAtMs = Date.now()
-        this.lastStartReason = reason
-        this.logger("process started", {command: this.command, id: this.id, pid: child.pid || null, reason})
-        this.startMemoryMonitor()
-        this.emit("started")
-        resolve(undefined)
+        void (async () => {
+          this.startedAtMs = Date.now()
+          this.lastStartReason = reason
+          try {
+            await this.restoreLifecycleRole()
+          } catch (error) {
+            this.state = "failed"
+            this.logger("process lifecycle role restoration failed", {error: error instanceof Error ? error.message : String(error), id: this.id, role: this.lifecycleRole})
+            reject(error)
+            return
+          }
+          if (this.child !== child) {
+            reject(new Error(`Process ${this.id} exited before lifecycle role ${this.lifecycleRole} was restored`))
+            return
+          }
+          this.state = "running"
+          this.logger("process started", {command: this.command, id: this.id, pid: child.pid || null, reason})
+          this.startMemoryMonitor()
+          this.emit("started")
+          resolve(undefined)
+        })()
       })
       child.once("error", (error) => {
         this.state = "failed"
+        if (this.child === child) {
+          this.child = undefined
+          this.pid = undefined
+          this.exitPromise = undefined
+        }
         reject(error)
       })
       child.stdout.setEncoding("utf8")
@@ -157,11 +182,14 @@ export default class ManagedProcess extends EventEmitter {
     for (const line of String(chunk).split(/\r?\n/)) {
       if (!line) continue
 
-      this.logs.push({at: new Date().toISOString(), line, stream})
+      const entry = {at: new Date().toISOString(), line, stream}
+
+      this.logs.push(entry)
 
       if (this.logs.length > this.outputLines) {
         this.logs.splice(0, this.logs.length - this.outputLines)
       }
+      this.emit("log", entry)
     }
   }
 
@@ -321,6 +349,7 @@ export default class ManagedProcess extends EventEmitter {
     if (this.memoryRestarting) return
 
     this.memoryRestarting = true
+    const lifecycleRole = this.lifecycleRole
 
     try {
       await this.stop()
@@ -333,7 +362,7 @@ export default class ManagedProcess extends EventEmitter {
       this.memoryRestarts += 1
       this.lastMemoryRestartAtMs = Date.now()
       this.memoryWarned = false
-      await this.start("memory")
+      await this.start("memory", lifecycleRole)
     } catch (error) {
       this.logger("memory restart failed", {error: error instanceof Error ? error.message : String(error), id: this.id})
     } finally {
@@ -415,11 +444,15 @@ export default class ManagedProcess extends EventEmitter {
       }
       if (!this.child?.pid) {
         this.state = "stopped"
+        if (this.lifecycle.activateCommand) this.lifecycleRole = "retired"
         return
       }
       this.state = "stopping"
       if (this.lifecycle.quietCommand) this.quiesceError = await this.runHook(this.lifecycle.quietCommand, this.hookTimeoutMs(), "quiet command")
-      if (!this.quiesceError) this.state = "quiesced"
+      if (!this.quiesceError) {
+        this.state = "quiesced"
+        if (this.lifecycle.activateCommand) this.lifecycleRole = "retired"
+      }
     })()
     return await this.quiescePromise
   }
@@ -430,6 +463,44 @@ export default class ManagedProcess extends EventEmitter {
     if (this.quiesceError) throw this.quiesceError
   }
 
+  /** Re-runs the idempotent quiet hook for an explicitly resumed durable transition. */
+  async requiesceStrict() {
+    this.quiescePromise = undefined
+    this.quiesceError = undefined
+    await this.quiesceStrict()
+  }
+
+  /** Runs the opt-in generation activation command and rejects on any hook failure. */
+  async activateStrict() {
+    const command = this.lifecycle.activateCommand
+
+    if (!command) return
+    const error = await this.runHook(command, ACTIVATION_HOOK_TIMEOUT_MS, "activate command", this.pid)
+
+    if (error) throw error
+    this.lifecycleRole = "active"
+  }
+
+  /**
+   * Records the durable desired role without firing a lifecycle command.
+   * @param {LifecycleRole} role - Exact role owned by this process generation.
+   */
+  async setLifecycleRole(role) {
+    this.lifecycleRole = role
+  }
+
+  /** Restores an active or retired role after this exact process starts. */
+  async restoreLifecycleRole() {
+    if (!this.lifecycle.activateCommand || this.lifecycleRole === "candidate") return
+    const command = this.lifecycleRole === "active" ? this.lifecycle.activateCommand : this.lifecycle.quietCommand
+
+    if (!command) throw new Error(`Process ${this.id} cannot restore lifecycle role ${this.lifecycleRole} without its paired command`)
+    const timeoutMs = this.lifecycleRole === "active" ? ACTIVATION_HOOK_TIMEOUT_MS : this.hookTimeoutMs()
+    const error = await this.runHook(command, timeoutMs, `${this.lifecycleRole === "active" ? "activate" : "quiet"} command`, this.pid)
+
+    if (error) throw error
+  }
+
   /** @returns {number} Timeout used for lifecycle hooks. */
   hookTimeoutMs() {
     if (this.stopTimeoutMs === "indefinite") return 30000
@@ -642,6 +713,7 @@ export default class ManagedProcess extends EventEmitter {
       id: this.id,
       lastMemoryRestartAt: this.lastMemoryRestartAtMs === undefined ? undefined : new Date(this.lastMemoryRestartAtMs).toISOString(),
       lastStartReason: this.lastStartReason,
+      ...(this.lifecycle.activateCommand ? {lifecycleRole: this.lifecycleRole} : {}),
       logs: this.logs.slice(-this.outputLines),
       memoryRestarts: this.memoryRestarts,
       pid: this.pid,

package/src/process-guardian.js

@@ -24,6 +24,7 @@ import ManagedProcess from "./managed-process.js"
  * @property {import("./json.js").JsonValue} [authority] - Expected current authority.
  * @property {import("./json.js").JsonValue} [nextAuthority] - Requested replacement authority.
  * @property {import("./managed-process.js").ManagedProcessStartReason} [reason] - Start reason.
+ * @property {import("./managed-process.js").LifecycleRole} [lifecycleRole] - Desired generation role restored during start.
  * @property {string} token - Authentication token.
  */
 
@@ -297,6 +298,23 @@ async function execute(request, socket) {
     return {aborted: true}
   }
 
+  if (request.command === "commit-retired-owner-replacement") {
+    requireReplacement(socket, request)
+    if (!replacementOwnerState) throw new Error("Retired owner replacement transaction is not staged")
+    if (!isDeepStrictEqual(ownerAuthority(ownerState), replacementAuthority)) throw new Error("Retired owner replacement requires unchanged owner authority")
+    const controlPath = ownerControlPath(ownerState)
+
+    try {
+      await fs.lstat(controlPath)
+      throw new Error(`Retired owner control socket ${controlPath} still exists`)
+    } catch (error) {
+      if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") throw error
+    }
+    commitReplacement()
+    finalizeReplacementRetirement()
+    return {committed: true}
+  }
+
   if (request.command === "commit-owner-replacement") {
     requireOwner(socket, request.command)
     if (!replacementClient || request.replacementId !== replacementId || !replacementOwnerState) throw new Error("Owner replacement transaction is not the prepared ready candidate")
@@ -379,6 +397,9 @@ async function execute(request, socket) {
       ? legacyGuardian.process(request.key, managedDefinition)
       : new ManagedProcess(managedDefinition)
 
+    managedProcess.on("log", (entry) => {
+      broadcast({entry, event: "process-log", key: request.key, status: managedProcess.status()})
+    })
     if (recoversLegacyProcess && "recover" in managedProcess && typeof managedProcess.recover === "function") await managedProcess.recover()
 
     record.process = managedProcess
@@ -396,10 +417,18 @@ async function execute(request, socket) {
 
   if (request.command === "start") {
     record.desired = true
-    await record.process.start(request.reason)
+    await record.process.start(request.reason, request.lifecycleRole)
+  } else if (request.command === "activate") {
+    await record.process.activateStrict()
   } else if (request.command === "quiesce") {
     record.desired = false
     await record.process.quiesceStrict()
+  } else if (request.command === "requiesce") {
+    record.desired = false
+    await record.process.requiesceStrict()
+  } else if (request.command === "set-lifecycle-role") {
+    if (request.lifecycleRole !== "active" && request.lifecycleRole !== "candidate" && request.lifecycleRole !== "retired") throw new Error("Guardian lifecycle role is invalid")
+    await record.process.setLifecycleRole(request.lifecycleRole)
   } else if (request.command === "stop") {
     record.desired = false
     await record.process.stop(request.options)
@@ -510,6 +539,21 @@ function ownerAuthority(state) {
   return state.authority
 }
 
+/**
+ * @param {import("./json.js").JsonValue | undefined} state - Committed transferable state.
+ * @returns {string} Exact incumbent public control path.
+ */
+function ownerControlPath(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state) || !("snapshot" in state)) throw new Error("Guardian owner state is missing its committed snapshot")
+  const snapshot = state.snapshot
+
+  if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot) || !("control" in snapshot)) throw new Error("Guardian owner snapshot is missing its control identity")
+  const control = snapshot.control
+
+  if (!control || typeof control !== "object" || Array.isArray(control) || !("path" in control) || typeof control.path !== "string") throw new Error("Guardian owner snapshot has an invalid control identity")
+  return control.path
+}
+
 /**
  * Stops accepting connections and closes every authority channel except the response caller.
  * @param {net.Socket} caller - Shutdown requester retained until it receives the response.

package/src/release-group.js

@@ -116,8 +116,9 @@ export default class ReleaseGroup extends EventEmitter {
   /**
    * Reconstructs this release around processes still owned by the durable guardian.
    * @param {ReleaseStatus} snapshot - Persisted release snapshot.
+   * @param {{synchronizeLifecycleRole?: boolean}} [options] - Guardian role synchronization options.
    */
-  async restore(snapshot) {
+  async restore(snapshot, {synchronizeLifecycleRole = true} = {}) {
     if (!snapshot || snapshot.releaseId !== this.releaseId || snapshot.releasePath !== this.releasePath || snapshot.revision !== this.revision) {
       throw new Error(`Persisted release identity mismatch for ${this.releaseId}`)
     }
@@ -175,6 +176,17 @@ export default class ReleaseGroup extends EventEmitter {
       if (processConfig.nonBlockingDrain) this.nonBlockingDrainIds.add(processStatus.id)
       if ("recover" in processInstance && typeof processInstance.recover === "function") await processInstance.recover()
     }
+    if (synchronizeLifecycleRole) await this.synchronizeLifecycleRoles()
+  }
+
+  /** Synchronizes only the activation owner's durable role without firing its hook. */
+  async synchronizeLifecycleRoles() {
+    const processConfig = this.config.processes.find((candidate) => candidate.lifecycle.activateCommand !== undefined)
+
+    if (!processConfig) return
+    const lifecycleRole = this.state === "active" ? "active" : this.state === "draining" ? "retired" : "candidate"
+
+    await Promise.all(this.getProcesses(processConfig.id).map(({process}) => process.setLifecycleRole(lifecycleRole)))
   }
 
   /**
@@ -253,6 +265,17 @@ export default class ReleaseGroup extends EventEmitter {
     this.activatedAt = new Date().toISOString()
   }
 
+  /** Runs the configured release-generation activation acknowledgement, if any. */
+  async activateGeneration() {
+    const processConfig = this.config.processes.find((candidate) => candidate.lifecycle.activateCommand !== undefined)
+
+    if (!processConfig) return
+    const [instance] = this.getProcesses(processConfig.id)
+
+    if (!instance) throw new Error(`Generation activation process ${processConfig.id} is not running for release ${this.releaseId}`)
+    await instance.process.activateStrict()
+  }
+
   /** @returns {Promise<void>} Allocates all configured per-process ports. */
   async allocatePorts() {
     if (this.portsAllocated) return
@@ -295,12 +318,12 @@ export default class ReleaseGroup extends EventEmitter {
   }
 
   /**
-   * Builds a managed process from config.
+   * Builds one rendered managed-process definition without registering ownership.
    * @param {import("./config.js").ProcessConfig} processConfig - Process config.
    * @param {BuildProcessOptions} [options] - Build options.
-   * @returns {ManagedProcess} Managed process.
+   * @returns {ConstructorParameters<typeof ManagedProcess>[0] & import("./managed-process.js").ManagedProcessDefinition} Managed process definition.
    */
-  buildProcess(processConfig, options = {}) {
+  processDefinition(processConfig, options = {}) {
     const index = options.index ?? 0
     const count = options.count ?? 1
     const instanceId = options.instanceId ?? processConfig.id
@@ -311,12 +334,12 @@ export default class ReleaseGroup extends EventEmitter {
       ...renderedEnv
     }
 
-    const definition = /** @type {ConstructorParameters<typeof ManagedProcess>[0]} */ ({
+    return {
       command: renderTemplate(processConfig.command, context),
       cwd: processConfig.cwd ? renderTemplate(processConfig.cwd, context) : this.releasePath,
       env: processEnv,
       id: instanceId,
-      lifecycle: processConfig.lifecycle,
+      lifecycle: processConfig.lifecycle || {drainTimeoutMs: 0},
       logger: (message, data = {}) => this.logger(message, {processId: instanceId, releaseId: this.releaseId, ...data}),
       memory: processConfig.memory,
       outputLines: processConfig.outputLines,
@@ -325,7 +348,18 @@ export default class ReleaseGroup extends EventEmitter {
       shouldRestart: options.shouldRestart || (() => this.state === "active" || this.state === "starting"),
       stopSignal: processConfig.stopSignal,
       stopTimeoutMs: processConfig.gracefulStopMs
-    })
+    }
+  }
+
+  /**
+   * Builds a managed process from config.
+   * @param {import("./config.js").ProcessConfig} processConfig - Process config.
+   * @param {BuildProcessOptions} [options] - Build options.
+   * @returns {ManagedProcess} Managed process.
+   */
+  buildProcess(processConfig, options = {}) {
+    const definition = this.processDefinition(processConfig, options)
+    const instanceId = options.instanceId ?? processConfig.id
 
     return this.processFactory
       ? this.processFactory(options.guardianKey || `release:${this.releaseId}:${instanceId}`, definition)
@@ -347,7 +381,7 @@ export default class ReleaseGroup extends EventEmitter {
 
       for (let index = 0; index < instances.length; index += 1) {
         const instance = instances[index]
-        const nextDefinition = this.buildProcess(processConfig, {
+        const nextDefinition = this.processDefinition(processConfig, {
           count: processConfig.replicas,
           index,
           instanceId: instance.id
@@ -543,21 +577,25 @@ export default class ReleaseGroup extends EventEmitter {
   /**
    * Marks the generation retired and quiesces its jobs-main and non-blocking workers as one unit.
    * @param {import("./config.js").RollbridgeConfig} [config] - Refreshed retirement config.
+   * @param {{retry?: boolean}} [options] - Explicit durable-transition resume options.
    * @returns {Promise<void>} Resolves when retirement quiescence succeeds.
    */
-  async beginRetirement(config = this.config) {
+  async beginRetirement(config = this.config, {retry = false} = {}) {
     if (this.state === "draining") {
-      if (this.retirementError) throw new Error(this.retirementError)
-      return
+      if (!retry) {
+        if (this.retirementError) throw new Error(this.retirementError)
+        return
+      }
+    } else {
+      this.state = "draining"
+      this.drainStartedAt = new Date().toISOString()
     }
 
-    this.state = "draining"
-    this.drainStartedAt = new Date().toISOString()
     this.refreshProcessDefinitions(config)
     const generationIds = new Set([...this.handoffServiceIds, ...this.nonBlockingDrainIds])
     const results = await Promise.allSettled([...this.processes.entries()]
       .filter(([id]) => generationIds.has(id))
-      .map(([, processInstance]) => processInstance.quiesceStrict()))
+      .map(([, processInstance]) => retry ? processInstance.requiesceStrict() : processInstance.quiesceStrict()))
     const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason)
 
     if (errors.length > 0) {
@@ -565,6 +603,7 @@ export default class ReleaseGroup extends EventEmitter {
       this.retirementError = `${failure.message}: ${errors.map((error) => error instanceof Error ? error.message : String(error)).join("; ")}`
       throw failure
     }
+    this.retirementError = undefined
   }
 
   /** @returns {Promise<void>} Stops all release-owned processes. */

package/test/config-validation.test.js

@@ -204,6 +204,50 @@ test("validateConfig defaults lifecycle, accepts hooks, and rejects bad values",
   assert.deepEqual(validateLifecycle({stopCommand: "kill -TERM $ROLLBRIDGE_PID"}).issues, [])
 })
 
+test("validateConfig accepts one durable handoff activation lifecycle and rejects unsafe placements", () => {
+  const base = {
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    ownerRecovery: {reconnectGraceMs: 30000},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}},
+      {
+        command: "run jobs",
+        deployStrategy: "handoff",
+        id: "jobs",
+        lifecycle: {activateCommand: "jobs activate", quietCommand: "jobs retire"},
+        policy: "service",
+        port: {from: 18100, to: 18199}
+      }
+    ],
+    proxy: {host: "127.0.0.1", port: 8182},
+    statePath: "/tmp/demo.state.json"
+  }
+  const valid = validateConfig(base)
+
+  assert.deepEqual(valid.issues, [])
+  assert.equal(valid.config.processes[1].lifecycle.activateCommand, "jobs activate")
+
+  const invalidType = validateConfig({...base, processes: [base.processes[0], {...base.processes[1], lifecycle: {activateCommand: 5, quietCommand: "jobs retire"}}]})
+  assert.ok(invalidType.issues.some((issue) => issue.message === "processes[1].lifecycle.activateCommand must be a string"))
+
+  const missingRetirement = validateConfig({...base, processes: [base.processes[0], {...base.processes[1], lifecycle: {activateCommand: "jobs activate"}}]})
+  assert.ok(missingRetirement.issues.some((issue) => /requires lifecycle\.quietCommand/.test(issue.message)))
+
+  const nonHandoff = validateConfig({...base, processes: [base.processes[0], {...base.processes[1], deployStrategy: "persistent"}]})
+  assert.ok(nonHandoff.issues.some((issue) => /activateCommand.*handoff service/.test(issue.message)))
+
+  const withoutRecovery = validateConfig({...base, ownerRecovery: undefined, statePath: undefined})
+  assert.ok(withoutRecovery.issues.some((issue) => /activateCommand requires ownerRecovery and statePath/.test(issue.message)))
+
+  const duplicate = validateConfig({...base, processes: [
+    base.processes[0],
+    base.processes[1],
+    {...base.processes[1], id: "jobs-secondary", port: {from: 18200, to: 18299}}
+  ]})
+  assert.ok(duplicate.issues.some((issue) => /at most one lifecycle\.activateCommand/.test(issue.message)))
+})
+
 test("validateConfig accepts indefinite graceful stop windows", () => {
   const {config, issues} = validateConfig({
     application: "demo",

package/test/guardian-client.test.js

@@ -2,6 +2,7 @@
 
 import assert from "node:assert/strict"
 import {spawn} from "node:child_process"
+import {once} from "node:events"
 import fs from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
@@ -49,6 +50,44 @@ test("guardian inventory removes only an exact owned provenance", async () => {
   }
 })
 
+test("guardian runs a strict activation lifecycle command for the exact registered process", async () => {
+  const fixture = await createGuardian()
+  const activationPath = path.join(fixture.root, "activated")
+  const processInstance = fixture.client.process("candidate-activation", {
+    ...definition("candidate-activation"),
+    lifecycle: {activateCommand: `printf activated > ${JSON.stringify(activationPath)}`, drainTimeoutMs: 0}
+  })
+
+  try {
+    await processInstance.start()
+    await processInstance.activateStrict()
+    assert.equal(await fs.readFile(activationPath, "utf8"), "activated")
+  } finally {
+    await cleanupGuardian(fixture)
+  }
+})
+
+test("guardian forwards each retained output line to its exact process proxy", async () => {
+  const fixture = await createGuardian()
+  const marker = "guardian-output-ready"
+  const processInstance = fixture.client.process("output", {
+    ...definition("output"),
+    command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify(`console.log(${JSON.stringify(marker)})`)}`
+  })
+  const logged = once(processInstance, "log")
+  const exitedFirst = once(processInstance, "exit").then(() => { throw new Error("Guardian process exited before forwarding retained output") })
+
+  try {
+    await processInstance.start()
+    const [entry] = await Promise.race([logged, exitedFirst])
+
+    assert.equal(entry.line, marker)
+    assert.ok(processInstance.status().logs.some((candidate) => candidate.line === marker))
+  } finally {
+    await cleanupGuardian(fixture)
+  }
+})
+
 test("guardian shutdown reports an exact owned process stop failure", async () => {
   const fixture = await createGuardian()
   const processInstance = fixture.client.process("broken-stop", {...definition("broken-stop"), stopSignal: "NOT_A_SIGNAL"})
@@ -171,6 +210,37 @@ test("replacement staging rejects owner state published after prepare", async ()
   }
 })
 
+test("retired owner replacement requires unchanged authority and the exact control path absent", async () => {
+  const fixture = await createGuardian()
+  const candidate = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})
+  const controlPath = path.join(fixture.root, "rollbridge.sock")
+  const authority = {configDigest: "incumbent", runtime: null}
+  const nextAuthority = {configDigest: "candidate", runtime: null}
+  const snapshot = {activeReleaseId: "v1", control: {path: controlPath}}
+
+  try {
+    await fixture.client.publishOwnerState({authority, snapshot})
+    await candidate.connect()
+    const changed = await candidate.prepareOwnerReplacement(authority, nextAuthority)
+
+    await candidate.stageOwnerReplacement(changed.replacementId, {authority: nextAuthority, snapshot})
+    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(changed.replacementId), /unchanged owner authority/)
+    await candidate.abortOwnerReplacement(changed.replacementId)
+
+    const occupied = await candidate.prepareOwnerReplacement(authority, authority)
+
+    await candidate.stageOwnerReplacement(occupied.replacementId, {authority, snapshot})
+    await fs.writeFile(controlPath, "occupied\n")
+    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(occupied.replacementId), /control socket .* still exists/)
+    await candidate.abortOwnerReplacement(occupied.replacementId)
+    await fixture.client.shutdown()
+    await fixture.client.guardianExit()
+  } finally {
+    candidate.disconnect()
+    await cleanupGuardian(fixture)
+  }
+})
+
 test("first upgrade migrates a real pre-split guardian without replacing its owned process", async () => {
   const fixture = await createLegacyGuardian()
   const processDefinition = definition("legacy-worker")