@ricsam/r5d-worker 0.0.136 → 0.0.138

package/dist/mjs/runtime/releases/manager.mjs

@@ -0,0 +1,541 @@
+import { Database } from "bun:sqlite";
+import { chmodSync, closeSync, constants, existsSync, fsyncSync, lstatSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import { canonicalJson, negotiateProtocol, OwnershipFence, RuntimeHello, RuntimeId } from "@ricsam/r5d-api/runtime-protocol";
+import { HostExecutorClient } from "../client.mjs";
+import { AdapterConfig, AdapterGrant, ExecutorCommand, ExecutorError, EXECUTOR_CAPABILITY } from "../protocol.mjs";
+import { privateDirectory, readPrivateJson } from "../storage.mjs";
+import { AdapterManifest, bytesHash, canonicalDirectory, ImmutableAdapterArtifacts, outsideWorkspaces } from "./artifacts.mjs";
+import { digest } from "./grants.mjs";
+import { AdapterChild } from "./process.mjs";
+import { AdapterRetirementCompletion } from "./retirement.mjs";
+const ReleaseManagerConfig = z.object({
+  installationId: RuntimeId,
+  workerId: RuntimeId,
+  stateDir: z.string().startsWith("/"),
+  artifactsDir: z.string().startsWith("/"),
+  workspaceRoots: z.array(z.string().startsWith("/")).min(1),
+  runtimePath: z.string().startsWith("/"),
+  runtimeSha256: z.string().regex(/^[a-f0-9]{64}$/),
+  controller: AdapterConfig
+}).strict();
+function callDigest(command) {
+  const parsed = ExecutorCommand.parse(command);
+  if (parsed.method === "start") return digest({ ...parsed, operation: { ...parsed.operation, fence: null } });
+  if ("run" in parsed) return digest({ ...parsed, run: { ...parsed.run, fence: null } });
+  return digest(parsed);
+}
+function privateSqlitePath(path) {
+  if (!existsSync(path)) return;
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.uid !== process.getuid?.() || stat.mode & 63)
+    throw new ExecutorError("insecure_release_state");
+}
+class WorkerAdapterReleases {
+  invocation = randomUUID();
+  config;
+  artifacts;
+  controller;
+  db;
+  lock;
+  ackKey;
+  children = /* @__PURE__ */ new Map();
+  deliveries = /* @__PURE__ */ new Map();
+  probes = 0;
+  retiring = /* @__PURE__ */ new Set();
+  serial = Promise.resolve();
+  closing = false;
+  closed;
+  constructor(input) {
+    this.config = ReleaseManagerConfig.parse(input);
+    const config = this.config;
+    if (config.controller.hello.installationId !== config.installationId || config.controller.hello.role !== "scheduler")
+      throw new ExecutorError("wrong_controller");
+    privateDirectory(config.stateDir);
+    outsideWorkspaces(config.stateDir, config.workspaceRoots);
+    this.verifyRuntime();
+    this.artifacts = new ImmutableAdapterArtifacts(config.artifactsDir, config.installationId, config.workerId, config.workspaceRoots);
+    this.controller = new HostExecutorClient(config.controller);
+    for (const file of ["manager.lock.sqlite", "releases.sqlite", "releases.sqlite-wal", "releases.sqlite-shm"])
+      privateSqlitePath(join(config.stateDir, file));
+    this.lock = new Database(join(config.stateDir, "manager.lock.sqlite"), { create: true });
+    chmodSync(join(config.stateDir, "manager.lock.sqlite"), 384);
+    try {
+      this.lock.exec("PRAGMA busy_timeout=0; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS singleton (id INTEGER)");
+    } catch {
+      this.lock.close();
+      throw new ExecutorError("release_manager_already_running");
+    }
+    let opened;
+    try {
+      this.db = opened = new Database(join(config.stateDir, "releases.sqlite"), { create: true });
+      chmodSync(join(config.stateDir, "releases.sqlite"), 384);
+      this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+        CREATE TABLE IF NOT EXISTS identity (id INTEGER PRIMARY KEY CHECK(id=1), digest TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS releases (id TEXT PRIMARY KEY, record TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS calls (id TEXT PRIMARY KEY, principal TEXT NOT NULL, hash TEXT NOT NULL,
+          state TEXT NOT NULL, acknowledged INTEGER NOT NULL DEFAULT 0);
+        CREATE TABLE IF NOT EXISTS transitions (id INTEGER PRIMARY KEY AUTOINCREMENT, kind TEXT NOT NULL, body TEXT NOT NULL, state TEXT NOT NULL)`);
+      const binding = digest({
+        installationId: config.installationId,
+        workerId: config.workerId,
+        artifactsDir: config.artifactsDir,
+        socketPath: config.controller.socketPath,
+        controllerId: config.controller.principalId
+      });
+      const prior = this.db.query("SELECT digest FROM identity WHERE id=1").get();
+      if (prior && prior.digest !== binding) throw new ExecutorError("wrong_store_identity");
+      if (!prior) this.db.query("INSERT INTO identity VALUES (1,?)").run(binding);
+      this.db.exec("UPDATE calls SET state='unknown' WHERE state='pending'; UPDATE transitions SET state='unknown' WHERE state='pending'");
+      this.db.exec(`CREATE TABLE IF NOT EXISTS deliveries (id TEXT PRIMARY KEY, receipt TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS rpc_identity (id INTEGER PRIMARY KEY CHECK(id=1), digest TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS observation_sequence (id INTEGER PRIMARY KEY CHECK(id=1), seq INTEGER NOT NULL, ack_key TEXT NOT NULL)`);
+      this.db.query("INSERT OR IGNORE INTO observation_sequence VALUES(1,0,?)").run(randomBytes(32).toString("hex"));
+      this.ackKey = this.db.query("SELECT ack_key FROM observation_sequence WHERE id=1").get().ack_key;
+      for (const row of this.db.query("SELECT id,receipt FROM deliveries").all()) {
+        const receipt = JSON.parse(row.receipt);
+        if (receipt.state === "pending") this.saveDelivery({ ...receipt, state: "unknown", outcome: null });
+      }
+      privateDirectory(join(config.stateDir, "configs"));
+    } catch (error) {
+      opened?.close();
+      this.lock.close();
+      throw error;
+    }
+  }
+  verifyRuntime() {
+    const config = this.config;
+    canonicalDirectory(config.runtimePath.slice(0, config.runtimePath.lastIndexOf("/")) || "/");
+    const runtime = lstatSync(config.runtimePath);
+    if (!runtime.isFile() || runtime.isSymbolicLink() || runtime.mode & 18 || bytesHash(readFileSync(config.runtimePath)) !== config.runtimeSha256)
+      throw new ExecutorError("unapproved_runtime");
+  }
+  exclusive(fn) {
+    const result = this.serial.then(() => {
+      if (this.closing) throw new ExecutorError("release_manager_closed");
+      return fn();
+    });
+    this.serial = result.catch(() => {
+    });
+    return result;
+  }
+  list() {
+    return this.db.query("SELECT record FROM releases ORDER BY id").all().map((row) => JSON.parse(row.record));
+  }
+  calls() {
+    return this.db.query("SELECT * FROM calls ORDER BY id").all();
+  }
+  transitions() {
+    return this.db.query("SELECT * FROM transitions ORDER BY id").all();
+  }
+  get(id) {
+    const record = this.list().find((record2) => record2.principalId === id);
+    if (!record) throw new ExecutorError("adapter_not_found");
+    return record;
+  }
+  put(record) {
+    this.db.query("INSERT INTO releases VALUES (?,?) ON CONFLICT(id) DO UPDATE SET record=excluded.record").run(record.principalId, canonicalJson(record));
+  }
+  configPath(id) {
+    return join(this.config.stateDir, "configs", `${digest(id)}.json`);
+  }
+  async keeper() {
+    const status = await this.controller.status();
+    if (status.hello.installationId !== this.config.installationId || status.workerId !== this.config.workerId)
+      throw new ExecutorError("wrong_resource");
+    return status;
+  }
+  /** Approval digest must come from the authenticated release ledger, not the source directory itself. */
+  stage(input) {
+    return this.exclusive(async () => {
+      const manifest = AdapterManifest.parse(input.manifest), grant = AdapterGrant.parse(input.grant), adapter = AdapterConfig.parse(input.adapter);
+      if (digest(manifest.hello) !== digest(grant.hello) || digest(adapter.hello) !== digest(grant.hello) || grant.artifactDigest !== input.approvalDigest || grant.installationId !== manifest.installationId || grant.workerId !== manifest.workerId || adapter.principalId !== grant.principal.id || adapter.socketPath !== this.config.controller.socketPath || bytesHash(Buffer.from(adapter.token)) !== grant.principal.tokenHash)
+        throw new ExecutorError("artifact_grant_mismatch");
+      const prior = this.list().find((row) => row.principalId === grant.principal.id);
+      if (prior && (digest(prior.grant) !== digest(grant) || prior.artifactDigest !== input.approvalDigest))
+        throw new ExecutorError("grant_identity_conflict");
+      if (prior?.phase === "retired") throw new ExecutorError("adapter_retired");
+      if (!prior && this.list().filter((row) => row.phase !== "retired").length >= 2) throw new ExecutorError("adapter_retention_blocked");
+      const keeper = await this.keeper();
+      negotiateProtocol(manifest.hello, keeper.hello, manifest.hello.capabilities);
+      this.artifacts.stage(input.source, manifest, input.approvalDigest);
+      const path = this.configPath(adapter.principalId);
+      if (existsSync(path)) {
+        if (digest(AdapterConfig.parse(readPrivateJson(path))) !== digest(adapter)) throw new ExecutorError("adapter_config_conflict");
+      } else {
+        const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 384);
+        try {
+          writeFileSync(fd, JSON.stringify(adapter));
+          fsyncSync(fd);
+        } finally {
+          closeSync(fd);
+        }
+        const directory = openSync(join(this.config.stateDir, "configs"), constants.O_RDONLY | constants.O_DIRECTORY);
+        try {
+          fsyncSync(directory);
+        } finally {
+          closeSync(directory);
+        }
+      }
+      const record = prior ?? {
+        principalId: adapter.principalId,
+        manifest,
+        artifactDigest: input.approvalDigest,
+        grant,
+        phase: "staged"
+      };
+      this.put(record);
+      await this.controller.registerAdapter(grant);
+      return record;
+    });
+  }
+  launch(id) {
+    return this.exclusive(async () => {
+      const record = this.get(id);
+      if (record.phase === "retired") throw new ExecutorError("adapter_retired");
+      await this.controller.registerAdapter(record.grant);
+      const directory = this.artifacts.verify(record.manifest, record.artifactDigest);
+      let child = this.children.get(id);
+      if (!child?.alive) {
+        this.verifyRuntime();
+        const adapter = AdapterConfig.parse(readPrivateJson(this.configPath(id)));
+        if (digest(adapter.hello) !== digest(record.grant.hello) || adapter.principalId !== id || adapter.socketPath !== this.config.controller.socketPath || bytesHash(Buffer.from(adapter.token)) !== record.grant.principal.tokenHash)
+          throw new ExecutorError("adapter_config_conflict");
+        child = new AdapterChild(
+          this.config.runtimePath,
+          join(directory, record.manifest.entrypoint),
+          this.configPath(id),
+          this.config.stateDir,
+          adapter.timeoutMs
+        );
+        this.children.set(id, child);
+      }
+      try {
+        const status = await child.request({ method: "status" });
+        if (status.workerId !== this.config.workerId || status.degraded) throw new ExecutorError("candidate_not_ready");
+        negotiateProtocol(record.manifest.hello, status.hello, [EXECUTOR_CAPABILITY, ...record.manifest.hello.capabilities]);
+        if (record.phase === "staged") {
+          record.phase = "ready";
+          this.put(record);
+        }
+        return { pid: child.process.pid };
+      } catch (error) {
+        await child.close();
+        this.children.delete(id);
+        throw error;
+      }
+    });
+  }
+  /** Fence/lease are the committed DB grant from the separately authenticated controller, not a locally invented epoch. */
+  promote(id, inputFence, validUntil) {
+    return this.exclusive(async () => {
+      const record = this.get(id), fence = OwnershipFence.parse(inputFence);
+      if (record.phase === "staged" || record.phase === "retired" || !this.children.get(id)?.alive)
+        throw new ExecutorError("candidate_not_ready");
+      if (fence.installationId !== this.config.installationId || fence.resourceId !== this.config.workerId || fence.resourceType !== "worker" || fence.ownerId !== record.grant.principal.ownerId)
+        throw new ExecutorError("wrong_resource");
+      this.artifacts.verify(record.manifest, record.artifactDigest);
+      const readiness = await this.children.get(id).request({ method: "status" });
+      if (readiness.workerId !== this.config.workerId || readiness.degraded) throw new ExecutorError("candidate_not_ready");
+      negotiateProtocol(record.manifest.hello, readiness.hello, record.manifest.hello.capabilities);
+      const transition = this.db.query("INSERT INTO transitions(kind,body,state) VALUES ('promote',?,'pending') RETURNING id").get(canonicalJson({ principalId: id, fence, validUntil }));
+      try {
+        await this.controller.setAuthority(fence, validUntil);
+        this.recordAuthority(id);
+        this.db.query("UPDATE transitions SET state='completed' WHERE id=?").run(transition.id);
+      } catch (error) {
+        this.db.query("UPDATE transitions SET state='unknown' WHERE id=?").run(transition.id);
+        throw error;
+      }
+    });
+  }
+  recordAuthority(id) {
+    this.db.transaction(() => {
+      for (const record of this.list()) {
+        if (record.principalId === id) {
+          record.phase = "active";
+          this.put(record);
+        } else if (record.phase === "active") {
+          record.phase = "retained";
+          this.put(record);
+        }
+      }
+    })();
+  }
+  /** Recovery reads the keeper, never replays a promotion or kills a remembered PID. */
+  reconcile() {
+    return this.exclusive(async () => {
+      const status = await this.keeper(), owner = status.authority?.fence.ownerId;
+      const record = this.list().find((row) => row.grant.principal.ownerId === owner);
+      if (record && record.phase !== "retired") this.recordAuthority(record.principalId);
+      for (const row of this.list()) {
+        if (status.adapters.some((grant) => grant.principalId === row.principalId && grant.state === "retired")) {
+          row.phase = "retired";
+          this.put(row);
+          await this.children.get(row.principalId)?.close();
+          this.children.delete(row.principalId);
+        }
+      }
+      return status;
+    });
+  }
+  bindRpcPrincipals(principals) {
+    const hash = digest(principals);
+    const old = this.db.query("SELECT digest FROM rpc_identity WHERE id=1").get();
+    if (old && old.digest !== hash) throw new ExecutorError("rpc_identity_conflict");
+    if (!old) this.db.query("INSERT INTO rpc_identity VALUES(1,?)").run(hash);
+  }
+  /** Actual child request, independent of the delivery/admin queues; never substitutes direct executor status. */
+  async probe(id, hello) {
+    const record = this.get(id), child = this.children.get(id);
+    if (this.closing || this.retiring.has(id) || record.phase === "retired" || !child?.alive || digest(hello) !== digest(record.grant.hello))
+      throw new ExecutorError("candidate_not_ready");
+    if (this.probes >= 8) throw new ExecutorError("manager_probe_busy");
+    this.probes++;
+    try {
+      const status = await child.request({ method: "status" });
+      if (!child.alive || this.retiring.has(id) || this.children.get(id) !== child || status.workerId !== this.config.workerId || status.degraded)
+        throw new ExecutorError("candidate_not_ready");
+      negotiateProtocol(hello, status.hello, hello.capabilities);
+      return { ...status, adapterPid: child.process.pid };
+    } finally {
+      this.probes--;
+    }
+  }
+  delivery(callId) {
+    const row = this.db.query("SELECT receipt FROM deliveries WHERE id=?").get(callId);
+    if (!row) return null;
+    const receipt = JSON.parse(row.receipt);
+    if (receipt.responseDigest !== digest({ callId: receipt.callId, commandDigest: receipt.commandDigest, state: receipt.state, outcome: receipt.outcome }))
+      throw new ExecutorError("delivery_corrupt");
+    return receipt;
+  }
+  ackToken(callId, responseDigest, requesterId, deliveryKind) {
+    return createHmac("sha256", this.ackKey).update(canonicalJson({ callId, responseDigest, requesterId, deliveryKind })).digest("hex");
+  }
+  saveDelivery(receipt) {
+    const value = {
+      ...receipt,
+      responseDigest: digest({
+        callId: receipt.callId,
+        commandDigest: receipt.commandDigest,
+        state: receipt.state,
+        outcome: receipt.outcome
+      })
+    };
+    value.ackToken = this.ackToken(value.callId, value.responseDigest, value.requesterId, value.deliveryKind);
+    const serialized = canonicalJson(value);
+    if (Buffer.byteLength(serialized) > 1024 * 1024 - 4096) throw new ExecutorError("delivery_result_too_large");
+    this.db.query("INSERT INTO deliveries VALUES (?,?) ON CONFLICT(id) DO UPDATE SET receipt=excluded.receipt").run(value.callId, serialized);
+    return value;
+  }
+  /** Stable transport ID: persisted completed outcomes replay exactly; unknown never redispatches. */
+  deliver(callId, id, hello, requesterId, command) {
+    if (callId.startsWith("observation-")) return Promise.reject(new ExecutorError("reserved_delivery_id"));
+    if (command.method === "poll") return Promise.reject(new ExecutorError("observation_required"));
+    return this.dispatchDelivery(callId, id, hello, requesterId, command, "mutation");
+  }
+  observe(id, hello, requesterId, command) {
+    if (command.method !== "poll") return Promise.reject(new ExecutorError("forbidden"));
+    const seq = this.db.query("UPDATE observation_sequence SET seq=seq+1 WHERE id=1 AND seq<9007199254740990 RETURNING seq").get();
+    if (!seq) return Promise.reject(new ExecutorError("observation_sequence_exhausted"));
+    return this.dispatchDelivery(`observation-${seq.seq}`, id, hello, requesterId, command, "observation");
+  }
+  dispatchDelivery(callId, id, hello, requesterId, command, deliveryKind) {
+    const notAdmitted = (code) => new ExecutorError(code, code, command.method === "start");
+    if (this.closing) return Promise.reject(notAdmitted("release_manager_closed"));
+    RuntimeId.parse(callId);
+    RuntimeId.parse(requesterId);
+    const parsed = ExecutorCommand.parse(command);
+    if (!["start", "poll", "write", "resize", "cancel"].includes(parsed.method)) return Promise.reject(new ExecutorError("forbidden"));
+    const identity = parsed.method === "start" ? parsed.operation : "run" in parsed ? parsed.run : null;
+    if (!identity?.sessionId) return Promise.reject(new ExecutorError("forbidden"));
+    const hash = digest(parsed), prior = this.delivery(callId);
+    if (prior) {
+      if (prior.adapterId !== id || digest(this.get(id).grant.hello) !== digest(hello) || prior.commandDigest !== hash || prior.requesterId !== requesterId || prior.userId !== identity.userId || prior.sessionId !== identity.sessionId)
+        return Promise.reject(new ExecutorError("call_payload_mismatch"));
+      if (prior.state === "completed" && prior.outcome === null) return Promise.reject(new ExecutorError("delivery_payload_missing"));
+      return this.deliveries.get(callId) ?? Promise.resolve(prior);
+    }
+    const record = this.get(id), child = this.children.get(id);
+    if (this.retiring.has(id) || record.phase === "retired" || digest(record.grant.hello) !== digest(hello) || !child?.alive)
+      return Promise.reject(notAdmitted("candidate_not_ready"));
+    if (this.deliveries.size >= (parsed.method === "cancel" ? 32 : 28)) return Promise.reject(notAdmitted("manager_delivery_busy"));
+    const size = this.db.query(
+      "SELECT count(*) AS count, coalesce(sum(length(CAST(receipt AS BLOB))),0) AS bytes FROM deliveries WHERE json_extract(receipt,'$.deliveryKind')=?"
+    ).get(deliveryKind);
+    const countLimit = deliveryKind === "observation" ? 256 : parsed.method === "start" ? 2048 : parsed.method === "cancel" ? 4096 : 3072;
+    const byteLimit = (deliveryKind === "observation" ? 8 : parsed.method === "start" ? 16 : parsed.method === "cancel" ? 32 : 24) * 1024 * 1024;
+    if (size.count >= countLimit || size.bytes + (this.deliveries.size + 1) * 1024 * 1024 > byteLimit)
+      return Promise.reject(notAdmitted("delivery_retention_full"));
+    const receipt = this.saveDelivery({
+      callId,
+      deliveryKind,
+      installationId: this.config.installationId,
+      workerId: this.config.workerId,
+      adapterId: id,
+      requesterId,
+      userId: identity.userId,
+      sessionId: identity.sessionId,
+      operationId: identity.operationId,
+      commandDigest: hash,
+      state: "pending",
+      outcome: null,
+      acknowledged: false
+    });
+    const task = (async () => {
+      try {
+        const result = await child.request(parsed);
+        if (result && typeof result === "object" && (result.state === "unknown" || result.receipt?.state === "unknown"))
+          return this.saveDelivery({ ...receipt, state: "unknown", outcome: null });
+        return this.saveDelivery({ ...receipt, state: "completed", outcome: { ok: true, result } });
+      } catch (error) {
+        const known = error instanceof ExecutorError && !error.code.endsWith("_unknown") && !["invalid_response", "delivery_result_too_large", "process_cleanup_uncertain"].includes(error.code);
+        const outcome = known ? { ok: false, error: { code: error.code, rejectedBeforeAdmission: error.rejectedBeforeAdmission } } : null;
+        return this.saveDelivery({ ...receipt, state: known ? "completed" : "unknown", outcome });
+      } finally {
+        this.deliveries.delete(callId);
+      }
+    })();
+    this.deliveries.set(callId, task);
+    return task;
+  }
+  acknowledgeDelivery(callId, responseDigest, ackToken, requesterId) {
+    const receipt = this.delivery(callId);
+    const kind = callId.startsWith("observation-") ? "observation" : "mutation";
+    const expected = this.ackToken(callId, responseDigest, requesterId, kind);
+    if (!/^[a-f0-9]{64}$/.test(ackToken) || !timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(ackToken, "hex")))
+      throw new ExecutorError("delivery_ack_mismatch");
+    if (!receipt) {
+      const match = /^observation-([1-9][0-9]*)$/.exec(callId), seq = Number(match?.[1]);
+      const highwater = this.db.query("SELECT seq FROM observation_sequence WHERE id=1").get().seq;
+      if (!match || !Number.isSafeInteger(seq) || seq > highwater) throw new ExecutorError("delivery_ack_mismatch");
+    } else {
+      if (receipt.requesterId !== requesterId || receipt.responseDigest !== responseDigest)
+        throw new ExecutorError("delivery_ack_mismatch");
+      if (receipt.state !== "completed" || receipt.outcome === null) throw new ExecutorError("delivery_reconciliation_required");
+      if (receipt.deliveryKind === "observation") this.db.query("DELETE FROM deliveries WHERE id=?").run(callId);
+      else this.saveDelivery({ ...receipt, acknowledged: true });
+    }
+    return { callId, responseDigest, acknowledged: true };
+  }
+  /** Admin-only attestation to independently durable reconciliation. Never replays or changes the unknown outcome. */
+  settleUnknownDelivery(callId, evidenceDigest) {
+    z.string().regex(/^[a-f0-9]{64}$/).parse(evidenceDigest);
+    const receipt = this.delivery(callId);
+    if (!receipt || receipt.state !== "unknown") throw new ExecutorError("delivery_not_unknown");
+    return this.db.transaction(() => {
+      this.db.query("INSERT INTO transitions(kind,body,state) VALUES ('settle-unknown',?,'completed')").run(canonicalJson({ callId, responseDigest: receipt.responseDigest, evidenceDigest }));
+      return this.saveDelivery({ ...receipt, acknowledged: true });
+    })();
+  }
+  deliveryDrain(id) {
+    const rows = this.db.query("SELECT receipt FROM deliveries").all();
+    const receipts = rows.map((row) => JSON.parse(row.receipt)).filter((receipt) => receipt.adapterId === id && !receipt.acknowledged);
+    return { unsettled: receipts.length, unknown: receipts.filter((receipt) => receipt.state === "unknown").length };
+  }
+  /** Stable callId journals delivery; reusing it never dispatches twice. Explicit retry uses reconcileCall. */
+  request(callId, id, command) {
+    return this.exclusive(() => this.dispatch(callId, id, command, false));
+  }
+  reconcileCall(callId, id, command) {
+    return this.exclusive(() => this.dispatch(callId, id, command, true));
+  }
+  async dispatch(callId, id, command, explicitRetry) {
+    RuntimeId.parse(callId);
+    if (!["start", "poll", "write", "resize", "cancel"].includes(command.method)) throw new ExecutorError("forbidden");
+    const hash = callDigest(command), prior = this.calls().find((call) => call.id === callId);
+    if (prior && prior.hash !== hash) throw new ExecutorError("call_payload_mismatch");
+    if (prior && !explicitRetry)
+      throw new ExecutorError(prior.state === "completed" ? "call_already_delivered" : "adapter_outcome_unknown");
+    if (!prior && explicitRetry) throw new ExecutorError("call_not_found");
+    if (!this.children.get(id)?.alive) throw new ExecutorError("candidate_not_ready");
+    if (!prior) this.db.query("INSERT INTO calls VALUES (?,?,?,'pending',0)").run(callId, id, hash);
+    try {
+      const result = await this.children.get(id).request(command);
+      this.db.query("UPDATE calls SET state='completed' WHERE id=?").run(callId);
+      return result;
+    } catch (error) {
+      this.db.query("UPDATE calls SET state='unknown' WHERE id=?").run(callId);
+      throw error;
+    }
+  }
+  /** Called only after the controller's durable inbox/outbox has recorded the result OR explicit unknown reconciliation. */
+  acknowledge(callId) {
+    return this.exclusive(async () => {
+      const call = this.calls().find((row) => row.id === callId);
+      if (!call || call.state === "pending") throw new ExecutorError("call_not_settled");
+      this.db.query("UPDATE calls SET acknowledged=1 WHERE id=?").run(callId);
+    });
+  }
+  retire(id, retirementIntentDigest) {
+    return this.exclusive(async () => {
+      const record = this.get(id);
+      if (retirementIntentDigest !== void 0 && !/^[a-f0-9]{64}$/.test(retirementIntentDigest))
+        throw new ExecutorError("invalid_retirement_intent");
+      if (record.phase === "retired") {
+        const completion = record.retirementCompletion;
+        if (!completion || retirementIntentDigest && completion.retirementIntentDigest !== retirementIntentDigest)
+          throw new ExecutorError("adapter_retirement_unknown");
+        AdapterRetirementCompletion.parse(completion);
+        if (completion.installationId !== this.config.installationId || completion.workerId !== this.config.workerId || completion.adapterId !== id || completion.manifestDigest !== digest(record.manifest) || completion.grantDigest !== digest(record.grant))
+          throw new ExecutorError("adapter_retirement_unknown");
+        if (this.calls().some((call) => call.principal === id && !call.acknowledged) || this.deliveryDrain(id).unsettled)
+          throw new ExecutorError("adapter_drain_blocked");
+        return;
+      }
+      const child = this.children.get(id);
+      if (this.calls().some((call) => call.principal === id && !call.acknowledged) || this.deliveryDrain(id).unsettled)
+        throw new ExecutorError("adapter_drain_blocked");
+      this.retiring.add(id);
+      try {
+        await this.controller.retireAdapter(id);
+      } catch (error) {
+        this.retiring.delete(id);
+        throw error;
+      }
+      record.phase = "retired";
+      this.put(record);
+      await child?.close();
+      this.children.delete(id);
+      if (child && child.process.pid && retirementIntentDigest && (child.process.exitCode !== null || child.process.signalCode !== null)) {
+        record.retirementCompletion = AdapterRetirementCompletion.parse({
+          format: 1,
+          installationId: this.config.installationId,
+          workerId: this.config.workerId,
+          adapterId: id,
+          manifestDigest: digest(record.manifest),
+          grantDigest: digest(record.grant),
+          retirementIntentDigest,
+          managerInvocation: this.invocation,
+          childPid: child.process.pid,
+          completionId: randomUUID()
+        });
+        this.put(record);
+      }
+    });
+  }
+  stopAdapter(id) {
+    return this.exclusive(async () => {
+      await this.children.get(id)?.close();
+      this.children.delete(id);
+    });
+  }
+  close() {
+    return this.closed ??= (async () => {
+      this.closing = true;
+      await this.serial;
+      await Promise.allSettled([...this.deliveries.values()]);
+      for (const child of this.children.values()) await child.close();
+      this.children.clear();
+      this.db.close();
+      this.lock.close();
+    })();
+  }
+}
+export {
+  ReleaseManagerConfig,
+  WorkerAdapterReleases
+};

package/dist/mjs/runtime/releases/process.mjs

@@ -0,0 +1,88 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { ExecutorError, isStartNonAdmissionCode, MAX_FRAME_BYTES } from "../protocol.mjs";
+class AdapterChild {
+  constructor(runtimePath, entrypoint, configPath, home, timeoutMs = 1e4) {
+    this.timeoutMs = timeoutMs;
+    this.process = spawn(runtimePath, [entrypoint, configPath], {
+      cwd: home,
+      env: { PATH: "/usr/local/bin:/usr/bin:/bin", HOME: home, LANG: "C.UTF-8" },
+      stdio: "pipe"
+    });
+    let buffer = Buffer.alloc(0);
+    this.process.stdout.on("data", (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      if (buffer.length > MAX_FRAME_BYTES) {
+        this.fail();
+        this.process.kill();
+        return;
+      }
+      while (buffer.includes(10)) {
+        const end = buffer.indexOf(10), line = buffer.subarray(0, end);
+        buffer = buffer.subarray(end + 1);
+        try {
+          const message = JSON.parse(line.toString("utf8"));
+          const pending = this.pending.get(message.id);
+          if (!pending) continue;
+          this.pending.delete(message.id);
+          clearTimeout(pending.timer);
+          if (message.ok === true) pending.resolve(message.result);
+          else
+            pending.reject(
+              new ExecutorError(
+                message.error?.code ?? "adapter_outcome_unknown",
+                void 0,
+                message.ok === false && pending.method === "start" && isStartNonAdmissionCode(message.error?.code) && message.error?.rejectedBeforeAdmission === true
+              )
+            );
+        } catch {
+          this.fail();
+          this.process.kill();
+        }
+      }
+    });
+    this.process.stderr.resume();
+    this.process.stdin.on("error", () => this.fail());
+    this.process.once("error", () => this.fail());
+    this.process.once("exit", () => this.fail());
+  }
+  timeoutMs;
+  process;
+  pending = /* @__PURE__ */ new Map();
+  gone = false;
+  fail() {
+    this.gone = true;
+    for (const call of this.pending.values()) {
+      clearTimeout(call.timer);
+      call.reject(new ExecutorError("adapter_outcome_unknown"));
+    }
+    this.pending.clear();
+  }
+  get alive() {
+    return !this.gone && this.process.exitCode === null && this.process.signalCode === null;
+  }
+  request(command) {
+    if (!this.alive) return Promise.reject(new ExecutorError("adapter_outcome_unknown"));
+    const id = randomUUID(), frame = JSON.stringify({ id, command }) + "\n";
+    if (Buffer.byteLength(frame) > MAX_FRAME_BYTES) return Promise.reject(new ExecutorError("request_too_large"));
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new ExecutorError("adapter_outcome_unknown"));
+      }, this.timeoutMs);
+      this.pending.set(id, { resolve: (result) => resolve(result), reject, timer, method: command.method });
+      this.process.stdin.write(frame);
+    });
+  }
+  async close() {
+    if (this.process.exitCode !== null || this.process.signalCode !== null) return;
+    const stopped = new Promise((resolve) => this.process.once("close", () => resolve()));
+    this.process.kill("SIGTERM");
+    const timer = setTimeout(() => this.process.kill("SIGKILL"), 2e3);
+    await stopped;
+    clearTimeout(timer);
+  }
+}
+export {
+  AdapterChild
+};

package/dist/mjs/runtime/releases/retirement.mjs

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { RuntimeId } from "@ricsam/r5d-api/runtime-protocol";
+const Digest = z.string().regex(/^[a-f0-9]{64}$/);
+const AdapterRetirementCompletion = z.object({
+  format: z.literal(1),
+  installationId: RuntimeId,
+  workerId: RuntimeId,
+  adapterId: RuntimeId,
+  manifestDigest: Digest,
+  grantDigest: Digest,
+  retirementIntentDigest: Digest,
+  managerInvocation: z.string().uuid(),
+  childPid: z.number().int().positive(),
+  completionId: z.string().uuid()
+}).strict();
+export {
+  AdapterRetirementCompletion
+};