@botiverse/k-carrier 0.1.0 → 0.1.5

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

@@ -27,6 +27,7 @@ import { finishUpgradeOutcome } from "./upgrade/outcome.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";
 
 export interface CreateUpgraderOptions extends UpgraderConfig {
   clock?: Clock;
@@ -65,7 +66,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;
@@ -150,7 +150,6 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
     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;
@@ -170,7 +169,6 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
         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` };
@@ -231,6 +229,8 @@ export function createUpgrader(opts: CreateUpgraderOptions): Upgrader {
   }
 
   return {
+    recover: () => recoverUpgrade(opts.stateDir, clock, engine),
+
     async check(): Promise<{ current: string; target: string | null }> {
       const current = (await readState()).stableVersion;
       const release = await opts.source.checkForUpdate({

package/core/src/index.ts

@@ -6,10 +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";
 
+// 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/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/recover.ts

@@ -0,0 +1,17 @@
+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,
+): Promise<void> {
+  const lock = await acquireUpgradeLock(stateDir, clock.nowMs());
+  try {
+    await engine.recover();
+  } finally {
+    await lock.release();
+  }
+}

package/core/src/upgrader.ts

@@ -24,6 +24,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.

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/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@botiverse/k-carrier",
-  "version": "0.1.0",
+  "version": "0.1.5",
+  "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.