@botiverse/k-carrier 0.1.0 → 0.1.6

package/README.md

@@ -6,34 +6,12 @@ CLI self-update libraries stop at replacing bytes; fleet updaters assume a machi
 
 **Two process models, defined by how many live incarnations K manages** — `swap` (**0**: K replaces bytes and touches no process; a one-shot CLI and an hours-long agent session are the same case) and `service` (**1**: K stops the old, starts the new, and proves it). OS lifecycle convergence and fleet drive are capabilities you opt into on top, not a third model. Proof is executable: a runnable example per case, and a claim without a green example does not exist.
 
-## Delivery and guarantee are different axes
-
-Most updaters are compared on one vague axis called "complexity". There are
-two, and they are independent:
-
-|                       | delivery — how hard is it to put the bytes in place | guarantee — what is promised afterwards |
-|-----------------------|---------------------------------------|-----------------------------|
-| `rustup self update`  | low: replace one file, exit           | low: none                   |
-| `electron-updater`    | **high**                              | low: none                   |
-| **K**                 | low: one binary                       | **high**: transaction, readback, rollback |
-
-Measured, not asserted: of electron-updater 6.8.9's ~4,200 lines, ~1,170 are
-per-platform installation (Squirrel.Mac, NSIS, deb/rpm/pacman, AppImage),
-~1,200 orchestration and policy, ~960 feed providers, and ~860 differential
-download. Downloading is not the hard part — **installing is, because
-installing is not yours to do**: you hand off to a system component with its
-own rules (Squirrel.Mac accepts only a URL, so the updater serves the file it
-already downloaded back to itself over a local HTTP server; NSIS may need
-elevation; dpkg needs root). Grep that codebase for rollback and you find none,
-and nothing checks health after the install.
-
-K deliberately does not compete on the delivery axis — platform packaging
-belongs to platform tools. It exists on the other one, and specifically for the
-consequence those tools all share and none of them handle: **because something
-else installs your bytes, something else replaces and restarts your process.**
-The process driving the upgrade dies on the *success* path, so the successor
-must be able to tell "the handover worked" from "we crashed" — by evidence,
-never by a flag saying the restart was planned.
+## What K owns
+
+K does not replace platform packaging or artifact delivery. It wraps an
+addressable release in a transaction with rollback and convergence readback.
+Because the process driving an upgrade may die on the success path, the
+successor proves the handoff from live evidence rather than trusting a flag.
 
 ## Start here
 
@@ -53,10 +31,8 @@ examples/   one runnable demo per profile (swap-tool / service-daemon / hosted-s
 docs/       guides + design + test plan + prior art
 ```
 
-**Platform support today:** Linux and macOS are implemented and gate CI.
-Windows platform operations (replacing a *running* .exe, process liveness) are
-deliberately unimplemented — they throw a typed `PLATFORM_UNSUPPORTED` rather
-than approximating POSIX behaviour and corrupting an install. The Windows CI
-job runs and reports, but does not gate, until those land.
+**Platform support today:** Linux and macOS gate CI. Windows platform
+operations are implemented; its acceptance harness and CI gate are still in
+progress.
 
 Status: incubating. TypeScript first. License: **Apache-2.0**.

package/core/src/bootstrap.ts

@@ -0,0 +1,168 @@
+/**
+ * First-adoption bootstrap for an already-running service.
+ *
+ * K normally owns both slots from the first install. An existing application
+ * adopting K has a different starting world: trusted bytes are running, but
+ * `slots/stable` does not exist yet. Starting the first transaction in that
+ * world would make a failed experiment roll back to an empty slot.
+ *
+ * `bootstrapStable` closes that one-time gap. It copies the application's
+ * current trusted executable into K's stable slot before any transaction can
+ * start. The publication is atomic and shares K's upgrade lock, so a crash
+ * leaves either no stable slot or one complete stable slot, never half of one.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { platformOpsFor } from "./platform/index.ts";
+import { acquireUpgradeLock } from "./txn/lock.ts";
+import { slotArtifactPath } from "./txn/fileEffects.ts";
+
+const VERSION_FILE = "VERSION";
+
+export type BootstrapStableResult = "bootstrapped" | "already-initialized";
+
+export type BootstrapErrorCode =
+  | "BOOTSTRAP_VERSION_INVALID"
+  | "BOOTSTRAP_STATE_CONFLICT"
+  | "BOOTSTRAP_SOURCE_UNREADABLE"
+  | "BOOTSTRAP_WRITE_FAILED";
+
+export class BootstrapError extends Error {
+  readonly code: BootstrapErrorCode;
+
+  constructor(code: BootstrapErrorCode, message: string, options?: { cause?: unknown }) {
+    super(`[${code}] ${message}`, options);
+    this.name = "BootstrapError";
+    this.code = code;
+  }
+}
+
+export interface BootstrapStableOptions {
+  /** Directory K owns for its journal, slots, and staging area. */
+  stateDir: string;
+  /** Version of the trusted executable that is running before K adoption. */
+  version: string;
+  /** Path to those exact trusted executable bytes. */
+  artifactPath: string;
+  /** Clock seam used only for the shared upgrade-lock receipt. */
+  nowMs?: () => number;
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function readInitializedStable(stateDir: string): Promise<string | null> {
+  const stableDir = path.join(stateDir, "slots", "stable");
+  if (!(await pathExists(stableDir))) return null;
+
+  let version: string;
+  try {
+    version = (await fs.readFile(path.join(stableDir, VERSION_FILE), "utf8")).trim();
+    await fs.stat(slotArtifactPath(stateDir, "stable"));
+  } catch (error) {
+    throw new BootstrapError(
+      "BOOTSTRAP_STATE_CONFLICT",
+      "the stable slot exists but is incomplete; refusing to overwrite recovery evidence",
+      { cause: error },
+    );
+  }
+  if (version.length === 0) {
+    throw new BootstrapError(
+      "BOOTSTRAP_STATE_CONFLICT",
+      "the stable slot has an empty version; refusing to overwrite recovery evidence",
+    );
+  }
+  return version;
+}
+
+async function assertPristineTransactionState(stateDir: string): Promise<void> {
+  const conflicting = [
+    path.join(stateDir, "journal.jsonl"),
+    path.join(stateDir, "slots", "experiment"),
+  ];
+  for (const candidate of conflicting) {
+    if (await pathExists(candidate)) {
+      throw new BootstrapError(
+        "BOOTSTRAP_STATE_CONFLICT",
+        `transaction state already exists at ${candidate}; refusing to invent an initial stable slot`,
+      );
+    }
+  }
+}
+
+/**
+ * Seed K's stable slot exactly once from an application's current trusted
+ * executable. A complete existing stable slot means K is already initialized
+ * (possibly at a newer version), so the caller's old carrier bytes are ignored.
+ */
+export async function bootstrapStable(opts: BootstrapStableOptions): Promise<BootstrapStableResult> {
+  const version = opts.version.trim();
+  if (version.length === 0) {
+    throw new BootstrapError("BOOTSTRAP_VERSION_INVALID", "version must be non-empty");
+  }
+
+  const lock = await acquireUpgradeLock(opts.stateDir, (opts.nowMs ?? Date.now)());
+  try {
+    if ((await readInitializedStable(opts.stateDir)) !== null) return "already-initialized";
+    await assertPristineTransactionState(opts.stateDir);
+
+    try {
+      const source = await fs.stat(opts.artifactPath);
+      if (!source.isFile()) throw new Error("bootstrap source is not a regular file");
+    } catch (error) {
+      throw new BootstrapError(
+        "BOOTSTRAP_SOURCE_UNREADABLE",
+        `trusted bootstrap artifact is not readable at ${opts.artifactPath}`,
+        { cause: error },
+      );
+    }
+
+    const slotsDir = path.join(opts.stateDir, "slots");
+    const stableDir = path.join(slotsDir, "stable");
+    const stagingDir = `${stableDir}.bootstrap`;
+    const stagingArtifact = path.join(stagingDir, "artifact.bin");
+    try {
+      await fs.rm(stagingDir, { recursive: true, force: true });
+      await fs.mkdir(stagingDir, { recursive: true });
+      await fs.copyFile(opts.artifactPath, stagingArtifact);
+      const artifactHandle = await fs.open(stagingArtifact, "r+");
+      try {
+        await artifactHandle.sync();
+      } finally {
+        await artifactHandle.close();
+      }
+      await platformOpsFor().makeExecutable(stagingArtifact);
+
+      const versionHandle = await fs.open(path.join(stagingDir, VERSION_FILE), "w");
+      try {
+        await versionHandle.writeFile(version);
+        await versionHandle.sync();
+      } finally {
+        await versionHandle.close();
+      }
+      await fs.mkdir(slotsDir, { recursive: true });
+      await platformOpsFor().renamePath(stagingDir, stableDir);
+      return "bootstrapped";
+    } catch (error) {
+      await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => {});
+      if (error instanceof BootstrapError) throw error;
+      throw new BootstrapError(
+        "BOOTSTRAP_WRITE_FAILED",
+        "could not atomically publish the initial stable slot",
+        { cause: error },
+      );
+    }
+  } finally {
+    await lock.release();
+  }
+}
+
+/** Public slot resolver used by host adapters; layout remains K-owned. */
+export { slotArtifactPath } from "./txn/fileEffects.ts";

package/core/src/createUpgrader.ts

@@ -8,25 +8,24 @@
  */
 import type { Upgrader, UpgraderConfig, UpgradeOutcome, ProvenanceIdentity } from "./upgrader.ts";
 import { phaseAtRest, type TxnState } from "./txn/state.ts";
-import type { Release } from "./artifact/source.ts";
 import type { ProcessEvidence } from "./lifecycle/hostAdapter.ts";
 import { UpgradeEngine } from "./txn/engine.ts";
-import { fileEffects, materializeArtifact } from "./txn/fileEffects.ts";
+import { fileEffects } from "./txn/fileEffects.ts";
 import { acquireUpgradeLock } from "./txn/lock.ts";
-import { downloadVerified } from "./artifact/download.ts";
-import { ArtifactError } from "./artifact/errors.ts";
-import * as path from "node:path";
 import { systemClock, type Clock } from "./clock.ts";
 import { buildSurfaceAllowlist, evaluateLifecycleConvergence } from "./converge/lifecycle.ts";
 import type { ReadbackSurface, PredicateResult } from "./converge/predicates.ts";
 import { platformOpsFor } from "./platform/index.ts";
 import type { UpgradeProgress } from "./progress.ts";
 import { slotArtifactPath } from "./txn/fileEffects.ts";
-import { recordReconcile, type ProvenanceJournal } from "./provenance/journal.ts";
-import { finishUpgradeOutcome } from "./upgrade/outcome.ts";
+import type { ProvenanceJournal } from "./provenance/journal.ts";
 import { retireReason } from "./upgrade/retire.ts";
 import { buildStatusReport, type StatusReport } from "./status/report.ts";
 import { persistReport, loadLastReport, type ReportRead } from "./status/reportStore.ts";
+import { recoverUpgrade } from "./upgrade/recover.ts";
+import type { OperationDescriptor } from "./operation.ts";
+import { createOperationLifecycle } from "./operationLifecycle.ts";
+import { driveUpgrade } from "./upgrade/drive.ts";
 
 export interface CreateUpgraderOptions extends UpgraderConfig {
   clock?: Clock;
@@ -65,7 +64,6 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
   const clock = opts.clock ?? systemClock;
   const effects = fileEffects(opts.stateDir);
   const ownership = opts.installOwnership ?? ((): "self" => "self");
-
   // The last predicate evidence, captured for the promote report (the
   // engine only carries pass/fail; the report needs the real results).
   let lastEvidence: ProcessEvidence | null = null;
@@ -121,116 +119,37 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
     };
   }
 
-  /** Report a stage. Observational only: a broken sink cannot break upgrades. */
-  function reportStage(progress: UpgradeProgress): void {
-    try {
-      opts.onProgress?.(progress);
-    } catch {
-      // a host's progress bar must never be able to fail an upgrade
-    }
-  }
-
-  async function notify(kind: Parameters<UpgraderConfig["notificationSink"]>[0]["kind"], detail: Record<string, string>): Promise<void> {
-    await opts.notificationSink({ kind, detail });
-  }
-
-  /** Gates 1-7. `consented` = the user approved THIS version (the confirm was
-   * shown and answered) — the policy gate is skipped, everything else stands. */
-  async function run(
-    pick: (current: string) => Promise<Release | null>,
-    consented = false,
-    provenance: ProvenanceIdentity | null = null,
-  ): Promise<UpgradeOutcome> {
-    const owner = ownership();
-    if (owner === "managed-elsewhere") {
-      await notify("held", { reason: "managed-elsewhere" });
-      return { result: "held", reason: "this install is managed by another manager; it does not upgrade itself" };
-    }
-
-    const lock = await acquireUpgradeLock(opts.stateDir, clock.nowMs());
-    try {
-      await engine.recover(); // finish or undo anything a previous crash left
-
-      const current = (await readState()).stableVersion;
-      reportStage({ stage: "checking" });
-      let release: Release | null;
-      try {
-        release = await pick(current);
-      } catch (err) {
-        // Consent is to a SPECIFIC version: if the source can no longer
-        // serve it (the publisher moved on), the approval is void — a typed
-        // refusal, never a silent switch to whatever is current now.
-        if (consented && err instanceof ArtifactError && err.code === "PINNED_VERSION_MISMATCH") {
-          await notify("held", { reason: "consented-version-unavailable", version: current });
-          return {
-            result: "held",
-            reason: `the approved version is no longer served; nothing was installed`,
-          };
-        }
-        throw err;
-      }
-      if (release === null) return { result: "up-to-date" };
-
-      if (!consented && opts.policy === "notify-only") {
-        await notify("held", { reason: "notify-only", version: release.version });
-        return { result: "held", reason: `policy is notify-only; ${release.version} is available` };
-      }
-      if (!consented && opts.policy === "confirm") {
-        await notify("confirm-request", { version: release.version, current });
-        return { result: "held", reason: `policy requires confirmation before upgrading to ${release.version}` };
-      }
-
-      if (opts.checkCompatibility) {
-        const refusal = await opts.checkCompatibility(current, release.version);
-        if (refusal !== null) {
-          await notify("held", { reason: "incompatible", detail: refusal });
-          return { result: "held", reason: `incompatible: ${refusal}` };
-        }
-      }
-
-      // Resume support: an interrupted download (process death
-      // mid-fetch) leaves its prefix in stateDir/incoming and the next
-      // attempt continues via Range instead of restarting from zero.
-      reportStage({ stage: "downloading", version: release.version });
-      const bytes = await downloadVerified(release, {
-        clock,
-        resumeDir: path.join(opts.stateDir, "incoming"),
-        onProgress: (downloaded, total) =>
-          reportStage({ stage: "downloading", version: release.version, downloaded, total }),
-      });
-      reportStage({ stage: "verifying", version: release.version });
-
-      reportStage({ stage: "staging", version: release.version });
-      const bytesRef = await materializeArtifact(opts.stateDir, bytes);
-
-      // M6 provenance: record WHO drove this reconcile, write-ahead of the txn.
-      if (opts.provenance) {
-        await recordReconcile(opts.provenance, provenance ?? opts.provenanceIdentity, release.version);
-      }
-
-      reportStage({ stage: "handing-over", version: release.version });
-      const outcome = await engine.upgrade({ version: release.version, bytesRef });
-      const finished = await finishUpgradeOutcome(outcome, {
-        notify,
-        reportStage,
-        targetVersion: release.version,
-        declaredSurfaces: (opts.lifecycleSurfaces ?? []).length,
-        nowMs: clock.nowMs(),
-        evidence: lastEvidence,
-        lifecycle: lastLifecycle,
-      });
-      if (finished.report !== null) {
-        lastReport = { kind: "observed", report: finished.report };
+  const operationLifecycle = createOperationLifecycle(opts.stateDir, clock, readState);
+  const drive = (request: Parameters<typeof driveUpgrade>[1]): Promise<UpgradeOutcome> =>
+    driveUpgrade({
+      stateDir: opts.stateDir,
+      clock,
+      engine,
+      operation: operationLifecycle,
+      ownership,
+      readStableVersion: async () => (await readState()).stableVersion,
+      policy: opts.policy,
+      notificationSink: opts.notificationSink,
+      ...(opts.onProgress ? { onProgress: opts.onProgress } : {}),
+      ...(opts.checkCompatibility ? { checkCompatibility: opts.checkCompatibility } : {}),
+      lifecycleSurfaceCount: (opts.lifecycleSurfaces ?? []).length,
+      evidence: () => lastEvidence,
+      lifecycle: () => lastLifecycle,
+      persistConvergenceReport: async (report) => {
+        lastReport = { kind: "observed", report };
         reportLoaded = true;
-        await persistReport(opts.stateDir, finished.report);
-      }
-      return finished.outcome;
-    } finally {
-      await lock.release();
-    }
-  }
+        await persistReport(opts.stateDir, report);
+      },
+      ...(opts.provenance ? { provenanceJournal: opts.provenance } : {}),
+      ...(opts.provenanceIdentity ? { provenanceIdentity: opts.provenanceIdentity } : {}),
+    }, request);
 
   return {
+    recover: async () => {
+      operationLifecycle.reset();
+      await recoverUpgrade(opts.stateDir, clock, engine, operationLifecycle.settleRecovery);
+    },
+
     async check(): Promise<{ current: string; target: string | null }> {
       const current = (await readState()).stableVersion;
       const release = await opts.source.checkForUpdate({
@@ -241,21 +160,29 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
     },
 
     async upgrade(): Promise<UpgradeOutcome> {
-      return run(async (current) =>
-        opts.source.checkForUpdate({ currentVersion: current, platformKey: platformOpsFor().platformKey() }),
-      );
+      return drive({
+        pick: async (current) => opts.source.checkForUpdate({
+          currentVersion: current,
+          platformKey: platformOpsFor().platformKey(),
+        }),
+      });
     },
 
-    async upgradeTo(version: string, opts2?: { consented?: boolean; provenance?: ProvenanceIdentity }): Promise<UpgradeOutcome> {
-      return run(
-        async (current) =>
-          opts.source.fetchRelease(version, {
+    async upgradeTo(version: string, opts2?: {
+      consented?: boolean;
+      provenance?: ProvenanceIdentity;
+      operation?: OperationDescriptor;
+    }): Promise<UpgradeOutcome> {
+      return drive({
+        pick: async (current) => opts.source.fetchRelease(version, {
             currentVersion: current,
             platformKey: platformOpsFor().platformKey(),
-          }),
-        opts2?.consented === true,
-        opts2?.provenance ?? null,
-      );
+        }),
+        consented: opts2?.consented === true,
+        ...(opts2?.provenance ? { provenance: opts2.provenance } : {}),
+        ...(opts2?.operation ? { operation: opts2.operation } : {}),
+        targetVersionHint: version,
+      });
     },
 
     async retireLegacyManager(): Promise<"retired" | { held: string }> {
@@ -272,12 +199,12 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
         const last = (await effects.journal.readAll()).at(-1)?.intent;
         const inFlight = last !== undefined && !phaseAtRest(last);
         if (!inFlight && ownership() === "managed-elsewhere") {
-          await notify("held", { reason: "managed-elsewhere" });
+          await opts.notificationSink({ kind: "held", detail: { reason: "managed-elsewhere" } });
           return { held: "this install is managed by another manager; it does not roll itself back" };
         }
         await engine.recover();
         await effects.slots.clearExperiment();
-        await notify("rolled-back", { reason });
+        await opts.notificationSink({ kind: "rolled-back", detail: { reason } });
         return "rolled-back";
       } finally {
         await lock.release();
@@ -296,5 +223,16 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
         provenance: opts.provenance ? await opts.provenance.read() : null,
       });
     },
+
+    operation: operationLifecycle.read,
+
+    async acknowledgeOperation(operationId) {
+      const lock = await acquireUpgradeLock(opts.stateDir, clock.nowMs());
+      try {
+        return await operationLifecycle.acknowledge(operationId);
+      } finally {
+        await lock.release();
+      }
+    },
   };
 }

package/core/src/index.ts

@@ -6,9 +6,19 @@
 // The upgrader factory and its configuration.
 export * from "./createUpgrader.ts";
 
+// One-time adoption of an already-running trusted binary into K's stable
+// slot, plus the K-owned slot resolver host adapters use to launch it.
+export * from "./bootstrap.ts";
+
 // Core types: Upgrader, UpgraderConfig, UpgradeOutcome, ProvenanceIdentity,
 // NotificationEvent.
 export * from "./upgrader.ts";
+export * from "./operation.ts";
+
+// The release-source boundary applications implement and the durable
+// provenance journal they wire into createUpgrader.
+export * from "./artifact/source.ts";
+export * from "./provenance/journal.ts";
 
 // The host boundary an adopter implements: HostAdapter, Slot, ProcessEvidence.
 export * from "./lifecycle/hostAdapter.ts";

package/core/src/operation.ts

@@ -0,0 +1,179 @@
+/**
+ * K-owned durable operation receipt.
+ *
+ * Hosts may project this record into their own UI or transport, but they do
+ * not maintain a second upgrade state machine. The operation receipt is the
+ * single durable answer to: what is running, which version was requested,
+ * what stable version can be restored, and whether the terminal receipt has
+ * already been acknowledged by the host transport.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { platformOpsFor } from "./platform/index.ts";
+import type { ProvenanceIdentity } from "./upgrader.ts";
+
+const OPERATION_FILE = "operation.json";
+export const OPERATION_FORMAT_VERSION = 1;
+
+export type OperationPhase =
+  | "checking"
+  | "downloading"
+  | "verifying"
+  | "staging"
+  | "handing-over"
+  | "probing"
+  | "recovering"
+  | "promoted"
+  | "rolled-back"
+  | "held"
+  | "up-to-date"
+  | "failed";
+
+export type OperationOutcome = "promoted" | "rolled-back" | "held" | "up-to-date" | "failed";
+
+const OPERATION_PHASES = new Set<OperationPhase>([
+  "checking",
+  "downloading",
+  "verifying",
+  "staging",
+  "handing-over",
+  "probing",
+  "recovering",
+  "promoted",
+  "rolled-back",
+  "held",
+  "up-to-date",
+  "failed",
+]);
+const OPERATION_OUTCOMES = new Set<OperationOutcome>([
+  "promoted",
+  "rolled-back",
+  "held",
+  "up-to-date",
+  "failed",
+]);
+
+export interface OperationDescriptor {
+  id: string;
+  startedAtMs: number;
+  provenance?: ProvenanceIdentity;
+  /** Opaque non-secret host correlation fields (for example server/request ids). */
+  metadata?: Record<string, string>;
+}
+
+export interface OperationRecord {
+  formatVersion: typeof OPERATION_FORMAT_VERSION;
+  id: string;
+  startedAtMs: number;
+  updatedAtMs: number;
+  fromVersion: string;
+  targetVersion: string;
+  /** The stable version that was current when this operation began. */
+  previousStableVersion: string;
+  phase: OperationPhase;
+  outcome: OperationOutcome | null;
+  reason: string | null;
+  provenance: ProvenanceIdentity | null;
+  metadata: Record<string, string>;
+  /** Host transport receipt, not a second transaction outcome. */
+  acknowledgedAtMs: number | null;
+}
+
+export type OperationRead =
+  | { kind: "genesis" }
+  | { kind: "observed"; operation: OperationRecord }
+  | { kind: "unreadable"; reason: string };
+
+function operationPath(stateDir: string): string {
+  return path.join(stateDir, OPERATION_FILE);
+}
+
+function validIdentity(value: unknown): value is ProvenanceIdentity {
+  return Boolean(
+    value
+    && typeof value === "object"
+    && typeof (value as ProvenanceIdentity).who === "string"
+    && typeof (value as ProvenanceIdentity).carrier === "string",
+  );
+}
+
+function parseOperation(text: string): OperationRecord {
+  const parsed = JSON.parse(text) as Partial<OperationRecord>;
+  if (
+    parsed.formatVersion !== OPERATION_FORMAT_VERSION
+    || typeof parsed.id !== "string"
+    || parsed.id.length === 0
+    || typeof parsed.startedAtMs !== "number"
+    || !Number.isFinite(parsed.startedAtMs)
+    || typeof parsed.updatedAtMs !== "number"
+    || !Number.isFinite(parsed.updatedAtMs)
+    || typeof parsed.fromVersion !== "string"
+    || typeof parsed.targetVersion !== "string"
+    || typeof parsed.previousStableVersion !== "string"
+    || typeof parsed.phase !== "string"
+    || !OPERATION_PHASES.has(parsed.phase as OperationPhase)
+    || !(parsed.outcome === null || (
+      typeof parsed.outcome === "string"
+      && OPERATION_OUTCOMES.has(parsed.outcome as OperationOutcome)
+    ))
+    || !(parsed.reason === null || typeof parsed.reason === "string")
+    || !(parsed.provenance === null || validIdentity(parsed.provenance))
+    || typeof parsed.metadata !== "object"
+    || parsed.metadata === null
+    || Array.isArray(parsed.metadata)
+    || Object.values(parsed.metadata).some((value) => typeof value !== "string")
+    || !(parsed.acknowledgedAtMs === null || typeof parsed.acknowledgedAtMs === "number")
+  ) {
+    throw new Error("operation record has an invalid shape");
+  }
+  return parsed as OperationRecord;
+}
+
+/** Atomic and durable replacement. K's upgrade lock serializes writers. */
+export async function persistOperation(stateDir: string, operation: OperationRecord): Promise<void> {
+  await fs.mkdir(stateDir, { recursive: true });
+  const target = operationPath(stateDir);
+  const tmp = `${target}.tmp`;
+  const fh = await fs.open(tmp, "w");
+  try {
+    await fh.writeFile(JSON.stringify(operation));
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await platformOpsFor().renamePath(tmp, target);
+}
+
+export async function loadOperation(stateDir: string): Promise<OperationRead> {
+  let text: string;
+  try {
+    text = await fs.readFile(operationPath(stateDir), "utf8");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { kind: "genesis" };
+    return { kind: "unreadable", reason: `cannot read ${OPERATION_FILE} (${code ?? (error as Error).message})` };
+  }
+  try {
+    return { kind: "observed", operation: parseOperation(text) };
+  } catch (error) {
+    return { kind: "unreadable", reason: `corrupt ${OPERATION_FILE}: ${(error as Error).message}` };
+  }
+}
+
+export async function acknowledgeOperation(
+  stateDir: string,
+  operationId: string,
+  acknowledgedAtMs: number,
+): Promise<"acknowledged" | "not-terminal" | "not-found" | "changed"> {
+  const current = await loadOperation(stateDir);
+  if (current.kind === "genesis") return "not-found";
+  if (current.kind === "unreadable") throw new Error(current.reason);
+  if (current.operation.id !== operationId) return "changed";
+  if (current.operation.outcome === null) return "not-terminal";
+  await persistOperation(stateDir, {
+    ...current.operation,
+    updatedAtMs: acknowledgedAtMs,
+    acknowledgedAtMs,
+  });
+  return "acknowledged";
+}

package/core/src/operationLifecycle.ts

@@ -0,0 +1,113 @@
+import type { Clock } from "./clock.ts";
+import { phaseAtRest, type TxnState } from "./txn/state.ts";
+import type { ProvenanceIdentity } from "./upgrader.ts";
+import {
+  acknowledgeOperation,
+  loadOperation,
+  persistOperation,
+  type OperationDescriptor,
+  type OperationOutcome,
+  type OperationPhase,
+  type OperationRead,
+  type OperationRecord,
+} from "./operation.ts";
+
+export interface OperationLifecycle {
+  begin(
+    descriptor: OperationDescriptor | null,
+    fromVersion: string,
+    targetVersion: string,
+    provenance: ProvenanceIdentity | null,
+  ): Promise<void>;
+  transition(input: {
+    phase: OperationPhase;
+    outcome?: OperationOutcome | null;
+    reason?: string | null;
+  }): Promise<void>;
+  settleRecovery(): Promise<void>;
+  reset(): void;
+  read(): Promise<OperationRead>;
+  acknowledge(operationId: string): Promise<"acknowledged" | "not-terminal" | "not-found" | "changed">;
+}
+
+export function createOperationLifecycle(
+  stateDir: string,
+  clock: Clock,
+  readState: () => Promise<TxnState>,
+): OperationLifecycle {
+  let record: OperationRecord | null = null;
+
+  const transition: OperationLifecycle["transition"] = async (input) => {
+    if (record === null) return;
+    record = {
+      ...record,
+      updatedAtMs: clock.nowMs(),
+      phase: input.phase,
+      outcome: input.outcome === undefined ? record.outcome : input.outcome,
+      reason: input.reason === undefined ? record.reason : input.reason,
+    };
+    await persistOperation(stateDir, record);
+  };
+
+  return {
+    async begin(descriptor, fromVersion, targetVersion, provenance) {
+      if (descriptor === null) return;
+      const existing = await loadOperation(stateDir);
+      if (existing.kind === "unreadable") throw new Error(existing.reason);
+      if (existing.kind === "observed" && existing.operation.id !== descriptor.id) {
+        if (existing.operation.outcome === null) {
+          throw new Error(`OPERATION_IN_PROGRESS: ${existing.operation.id}`);
+        }
+        if (existing.operation.acknowledgedAtMs === null) {
+          throw new Error(`OPERATION_RECEIPT_PENDING: ${existing.operation.id}`);
+        }
+      }
+      if (existing.kind === "observed" && existing.operation.id === descriptor.id) {
+        record = existing.operation;
+        return;
+      }
+      record = {
+        formatVersion: 1,
+        id: descriptor.id,
+        startedAtMs: descriptor.startedAtMs,
+        updatedAtMs: clock.nowMs(),
+        fromVersion,
+        targetVersion,
+        previousStableVersion: fromVersion,
+        phase: "checking",
+        outcome: null,
+        reason: null,
+        provenance: descriptor.provenance ?? provenance,
+        metadata: { ...descriptor.metadata },
+        acknowledgedAtMs: null,
+      };
+      await persistOperation(stateDir, record);
+    },
+
+    transition,
+
+    async settleRecovery() {
+      const observed = await loadOperation(stateDir);
+      if (observed.kind !== "observed" || observed.operation.outcome !== null) return;
+      record = observed.operation;
+      const state = await readState();
+      if (state.phase === "promoted" && state.stableVersion === record.targetVersion) {
+        await transition({ phase: "promoted", outcome: "promoted" });
+      } else if (phaseAtRest(state.phase)) {
+        await transition({
+          phase: "rolled-back",
+          outcome: "rolled-back",
+          reason: state.rollbackReason ?? `recovery settled at ${state.phase} with stable ${state.stableVersion}`,
+        });
+      }
+    },
+
+    reset() {
+      record = null;
+    },
+
+    read: () => loadOperation(stateDir),
+
+    acknowledge: (operationId) => acknowledgeOperation(stateDir, operationId, clock.nowMs()),
+  };
+}

package/core/src/provenance/journal.ts

@@ -23,7 +23,7 @@
  */
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import type { Clock } from "../clock.ts";
+import { systemClock, type Clock } from "../clock.ts";
 
 const PROVENANCE_FILE = "provenance.jsonl";
 
@@ -84,7 +84,7 @@ export interface ProvenanceJournal {
   read(): Promise<ProvenanceRead>;
 }
 
-export function fileProvenanceJournal(stateDir: string, clock: Clock): ProvenanceJournal {
+export function fileProvenanceJournal(stateDir: string, clock: Clock = systemClock): ProvenanceJournal {
   const filePath = path.join(stateDir, PROVENANCE_FILE);
 
   /** Read the raw file. Throws ProvenanceHistoryUnreadableError when the

package/core/src/upgrade/drive.ts

@@ -0,0 +1,177 @@
+import * as path from "node:path";
+import type { Release } from "../artifact/source.ts";
+import { downloadVerified } from "../artifact/download.ts";
+import { ArtifactError } from "../artifact/errors.ts";
+import { materializeArtifact } from "../txn/fileEffects.ts";
+import { acquireUpgradeLock } from "../txn/lock.ts";
+import type { UpgradeEngine, EngineOutcome } from "../txn/engine.ts";
+import type { Clock } from "../clock.ts";
+import type { UpgradeProgress } from "../progress.ts";
+import type { ProcessEvidence } from "../lifecycle/hostAdapter.ts";
+import type { PredicateResult, ConvergenceReport } from "../converge/predicates.ts";
+import type { OperationDescriptor } from "../operation.ts";
+import type { OperationLifecycle } from "../operationLifecycle.ts";
+import type {
+  NotificationEvent,
+  ProvenanceIdentity,
+  UpgradeOutcome,
+} from "../upgrader.ts";
+import type { ProvenanceJournal } from "../provenance/journal.ts";
+import { recordReconcile } from "../provenance/journal.ts";
+import { finishUpgradeOutcome } from "./outcome.ts";
+
+export interface UpgradeDriveDeps {
+  stateDir: string;
+  clock: Clock;
+  engine: UpgradeEngine;
+  operation: OperationLifecycle;
+  ownership: () => "self" | "managed-elsewhere";
+  readStableVersion: () => Promise<string>;
+  policy: "auto" | "confirm" | "notify-only";
+  notificationSink: (event: NotificationEvent) => Promise<void>;
+  onProgress?: (progress: UpgradeProgress) => void;
+  checkCompatibility?: (from: string, to: string) => Promise<string | null>;
+  lifecycleSurfaceCount: number;
+  evidence: () => ProcessEvidence | null;
+  lifecycle: () => PredicateResult | null;
+  persistConvergenceReport: (report: ConvergenceReport) => Promise<void>;
+  provenanceJournal?: ProvenanceJournal;
+  provenanceIdentity?: ProvenanceIdentity;
+}
+
+export interface UpgradeDriveRequest {
+  pick: (current: string) => Promise<Release | null>;
+  consented?: boolean;
+  provenance?: ProvenanceIdentity;
+  operation?: OperationDescriptor;
+  targetVersionHint?: string;
+}
+
+export async function driveUpgrade(
+  deps: UpgradeDriveDeps,
+  request: UpgradeDriveRequest,
+): Promise<UpgradeOutcome> {
+  const notify = (kind: NotificationEvent["kind"], detail: Record<string, string>) =>
+    deps.notificationSink({ kind, detail });
+  const progress = (value: UpgradeProgress): void => {
+    try { deps.onProgress?.(value); } catch { /* observation cannot fail an upgrade */ }
+  };
+  if (deps.ownership() === "managed-elsewhere") {
+    await notify("held", { reason: "managed-elsewhere" });
+    return { result: "held", reason: "this install is managed by another manager; it does not upgrade itself" };
+  }
+
+  const lock = await acquireUpgradeLock(deps.stateDir, deps.clock.nowMs());
+  try {
+    await deps.engine.recover();
+    await deps.operation.settleRecovery();
+    const current = await deps.readStableVersion();
+    await deps.operation.begin(
+      request.operation ?? null,
+      current,
+      request.targetVersionHint ?? current,
+      request.provenance ?? null,
+    );
+    progress({ stage: "checking" });
+
+    let release: Release | null;
+    try {
+      release = await request.pick(current);
+    } catch (error) {
+      if (request.consented && error instanceof ArtifactError && error.code === "PINNED_VERSION_MISMATCH") {
+        await deps.operation.transition({ phase: "held", outcome: "held", reason: "consented-version-unavailable" });
+        await notify("held", { reason: "consented-version-unavailable", version: current });
+        return { result: "held", reason: "the approved version is no longer served; nothing was installed" };
+      }
+      await deps.operation.transition({
+        phase: "failed",
+        outcome: "failed",
+        reason: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+    if (release === null) {
+      await deps.operation.transition({ phase: "up-to-date", outcome: "up-to-date" });
+      return { result: "up-to-date" };
+    }
+    if (!request.consented && deps.policy === "notify-only") {
+      await deps.operation.transition({ phase: "held", outcome: "held", reason: "notify-only" });
+      await notify("held", { reason: "notify-only", version: release.version });
+      return { result: "held", reason: `policy is notify-only; ${release.version} is available` };
+    }
+    if (!request.consented && deps.policy === "confirm") {
+      await deps.operation.transition({ phase: "held", outcome: "held", reason: "confirmation-required" });
+      await notify("confirm-request", { version: release.version, current });
+      return { result: "held", reason: `policy requires confirmation before upgrading to ${release.version}` };
+    }
+    const refusal = deps.checkCompatibility
+      ? await deps.checkCompatibility(current, release.version)
+      : null;
+    if (refusal !== null) {
+      await deps.operation.transition({ phase: "held", outcome: "held", reason: refusal });
+      await notify("held", { reason: "incompatible", detail: refusal });
+      return { result: "held", reason: `incompatible: ${refusal}` };
+    }
+
+    await deps.operation.transition({ phase: "downloading" });
+    progress({ stage: "downloading", version: release.version });
+    const bytes = await downloadVerified(release, {
+      clock: deps.clock,
+      resumeDir: path.join(deps.stateDir, "incoming"),
+      onProgress: (downloaded, total) =>
+        progress({ stage: "downloading", version: release.version, downloaded, total }),
+    });
+    await deps.operation.transition({ phase: "verifying" });
+    progress({ stage: "verifying", version: release.version });
+    await deps.operation.transition({ phase: "staging" });
+    progress({ stage: "staging", version: release.version });
+    const bytesRef = await materializeArtifact(deps.stateDir, bytes);
+    if (deps.provenanceJournal) {
+      await recordReconcile(
+        deps.provenanceJournal,
+        request.provenance ?? deps.provenanceIdentity,
+        release.version,
+      );
+    }
+
+    await deps.operation.transition({ phase: "handing-over" });
+    progress({ stage: "handing-over", version: release.version });
+    let engineOutcome: EngineOutcome;
+    try {
+      engineOutcome = await deps.engine.upgrade({ version: release.version, bytesRef });
+    } catch (error) {
+      await deps.operation.transition({
+        phase: "recovering",
+        reason: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+    const finished = await finishUpgradeOutcome(engineOutcome, {
+      notify,
+      reportStage: progress,
+      targetVersion: release.version,
+      declaredSurfaces: deps.lifecycleSurfaceCount,
+      nowMs: deps.clock.nowMs(),
+      evidence: deps.evidence(),
+      lifecycle: deps.lifecycle(),
+    });
+    if (finished.report !== null) await deps.persistConvergenceReport(finished.report);
+    switch (finished.outcome.result) {
+      case "promoted":
+        await deps.operation.transition({ phase: "promoted", outcome: "promoted" });
+        break;
+      case "rolled-back":
+        await deps.operation.transition({ phase: "rolled-back", outcome: "rolled-back", reason: finished.outcome.reason });
+        break;
+      case "held":
+        await deps.operation.transition({ phase: "held", outcome: "held", reason: finished.outcome.reason });
+        break;
+      case "up-to-date":
+        await deps.operation.transition({ phase: "up-to-date", outcome: "up-to-date" });
+        break;
+    }
+    return finished.outcome;
+  } finally {
+    await lock.release();
+  }
+}

package/core/src/upgrade/recover.ts

@@ -0,0 +1,19 @@
+import type { Clock } from "../clock.ts";
+import type { UpgradeEngine } from "../txn/engine.ts";
+import { acquireUpgradeLock } from "../txn/lock.ts";
+
+/** Settle an existing transaction under the same lock as every other drive. */
+export async function recoverUpgrade(
+  stateDir: string,
+  clock: Clock,
+  engine: UpgradeEngine,
+  afterRecover?: () => Promise<void>,
+): Promise<void> {
+  const lock = await acquireUpgradeLock(stateDir, clock.nowMs());
+  try {
+    await engine.recover();
+    await afterRecover?.();
+  } finally {
+    await lock.release();
+  }
+}

package/core/src/upgrader.ts

@@ -3,6 +3,7 @@ import type { TxnState } from "./txn/state.js";
 import type { ConvergenceReport } from "./converge/predicates.js";
 import type { StatusReport } from "./status/report.js";
 import type { ReleaseSource } from "./artifact/source.js";
+import type { OperationDescriptor, OperationRead } from "./operation.js";
 
 /**
  * Who drove a reconcile, recorded in the provenance journal (M6, L5).
@@ -24,6 +25,17 @@ export interface ProvenanceIdentity {
  * convergence" (the class of bug this framework exists to kill).
  */
 export interface Upgrader {
+  /**
+   * Settle any transaction a previous coordinator left in flight.
+   *
+   * Recovery uses the same durable journal, host adapter, predicates and
+   * upgrade lock as ordinary upgrades. It never consults the release source
+   * or begins a new transaction; it only replays or rolls back work already
+   * recorded by K. Hosts should run this from a coordinator that survives
+   * service replacement, because recovery may stop and restart the service.
+   */
+  recover(): Promise<void>;
+
   /**
    * Ask the release source whether this install should move, without moving
    * it. `target: null` means nothing to do.
@@ -51,7 +63,11 @@ export interface Upgrader {
    * silently installing whatever is current now. Consent is to a SPECIFIC
    * version, never to "the upgrade" as an event.
    */
-  upgradeTo(version: string, opts?: { consented?: boolean; provenance?: ProvenanceIdentity }): Promise<UpgradeOutcome>;
+  upgradeTo(version: string, opts?: {
+    consented?: boolean;
+    provenance?: ProvenanceIdentity;
+    operation?: OperationDescriptor;
+  }): Promise<UpgradeOutcome>;
 
   /**
    * Explicit rollback while an experiment is live (pre-promote).
@@ -84,6 +100,12 @@ export interface Upgrader {
    * are null (NOT_OBSERVED), never a fabricated pass.
    */
   status(): Promise<StatusReport>;
+
+  /** K's single durable operation receipt; hosts project it, never mirror it. */
+  operation(): Promise<OperationRead>;
+
+  /** Mark one exact terminal operation delivered by the host transport. */
+  acknowledgeOperation(operationId: string): Promise<"acknowledged" | "not-terminal" | "not-found" | "changed">;
 }
 
 export type UpgradeOutcome =

package/docs/design-v1.md

@@ -239,7 +239,7 @@ K                   交付低 / 保证高    单二进制；事务 + 回读 +
 3. 本仓库 = 原"release/publish 侧 spec"的上位替代；接入方视角见 `docs/integration.md`。
 
 ## 6. 决定记录（原开放问题，已拍部分）
-1. **名字/仓库 ✅（08-05）**：公开名 **k-carrier**（`github.com/botiverse/k-carrier`，private 孵化），口头名 **K**。理由：单字母不可检索 + kframework/k 撞名；k-carrier 自解释。
+1. **名字/仓库 ✅（08-05）**：公开名 **k-carrier**（`github.com/botiverse/k-carrier`），口头名 **K**。理由：单字母不可检索 + kframework/k 撞名；k-carrier 自解释。
 2. **core 语言 = TS 起步 ✅（默认成立，未被否）**：与 daemon 同栈、宿主壳复用最快、测试教义全在 TS 生态；留 FFI/重写门。
 3. **并行方式 = 1.0.16 先行 ✅（默认成立）**：按本仓库接口形状写，core 骨架随后收编。
 4. **drive 协议（仍开放）**：对齐现有远程配置生态 vs 自定义最小集 —— 到 L5 动工时拍。

package/docs/integration.md

@@ -241,6 +241,35 @@ The stages are not a parallel state machine: they are derived from the L1
 transaction phases (`stageForPhase`), so a progress display can never show a
 state the transaction does not have.
 
+## 4.6 One durable operation receipt
+
+When a host detaches the transaction driver from the service it replaces,
+pass an exact operation descriptor to `upgradeTo`. K then owns the only
+durable operation state, including the previous stable version and terminal
+outcome:
+
+```ts
+await upgrader.upgradeTo("2.0.0", {
+  consented: true,
+  operation: {
+    id: requestId,
+    startedAtMs: Date.now(),
+    metadata: { originServerId }, // non-secret host correlation only
+  },
+});
+
+const receipt = await upgrader.operation();
+if (receipt.kind === "observed" && receipt.operation.outcome !== null) {
+  await deliver(receipt.operation);
+  await upgrader.acknowledgeOperation(receipt.operation.id);
+}
+```
+
+The host may project this receipt into UI or transport, but must not maintain
+a second pending/status/previous-version state machine. `recover()` settles an
+active receipt under K's upgrade lock before the host reads it again. A corrupt
+or future-version receipt is `unreadable`, never treated as genesis or success.
+
 ## 5. Publishing releases
 
 If you use the built-in `staticManifestSource`, its layout is:

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@botiverse/k-carrier",
-  "version": "0.1.0",
+  "version": "0.1.6",
+  "packageManager": "pnpm@11.18.0",
   "description": "A fail-closed upgrade carrier for long-running managed services: two-slot upgrade transactions (promote/rollback), host-driven quiesce/resume handoff, and post-upgrade convergence read-back.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/botiverse/k-carrier"
+  },
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -12,7 +17,7 @@
     "./harness": "./harness/src/index.ts"
   },
   "bin": {
-    "k-harness": "./harness/src/cli.ts"
+    "k-harness": "harness/src/cli.ts"
   },
   "files": [
     "core/src/**/*.ts",

package/core/src/artifact/README.md

@@ -1 +0,0 @@
-# artifact — see docs/design-v1.md for this layer's spec. Interfaces land here next.

package/core/src/drive/README.md

@@ -1 +0,0 @@
-# drive — see docs/design-v1.md for this layer's spec. Interfaces land here next.

package/core/src/platform/README.md

@@ -1 +0,0 @@
-# platform — see docs/design-v1.md for this layer's spec. Interfaces land here next.

package/core/src/policy/README.md

@@ -1 +0,0 @@
-# policy — see docs/design-v1.md for this layer's spec. Interfaces land here next.

package/harness/README.md

@@ -1,20 +0,0 @@
-# K harness
-
-The generic acceptance bed runs the same registered teeth against K, a real
-binary, or an adopter's HostAdapter. It also owns K's deterministic simulator.
-
-```sh
-k-harness --list
-k-harness --profile service
-k-harness sim                          # fixed PR smoke corpus
-k-harness sim --seed 3737844653 --json # exact replay
-k-harness sim --start-seed 1 --seeds 50000
-```
-
-Simulation uses the real `UpgradeEngine` over an in-memory `TxnEffects` and
-HostAdapter. Every journal, slot, host and predicate effect is a seeded fault
-point. A failure prints its exact replay command and is atomically merged into
-`.k-harness/sim-failures.json`; the nightly workflow uploads that corpus.
-
-The simulator covers transaction/convergence logic. It does not replace the
-real-process crash matrix or real-OS test beds.