@botiverse/k-carrier 0.1.0

package/harness/src/fixtures/service-adapter.ts

@@ -0,0 +1,187 @@
+/**
+ * Service-tier adopter adapter fixture — a STANDALONE implementation of
+ * the five HostAdapter responsibilities with REAL process semantics, used
+ * to exercise `k-harness --adapter` against the service-profile teeth
+ * (upgrade / rollback / lifecycle-converged).
+ *
+ * It is intentionally NOT the demo's host: a real adopter brings its own
+ * host semantics. This one models the computer-shaped host:
+ *  - quiesce()/resume(): no-op (computer does not preserve sessions);
+ *  - stop(): SIGKILL the running successor child and VERIFY it is gone
+ *    (signal-sent ≠ dead);
+ *  - start(): spawn the slot artifact as a real child process and wait
+ *    for its ready line — the EVIDENCE. Only healthProbe() can say the
+ *    successor is running;
+ *  - healthProbe(): ask the LIVE process (the child's own ready/evidence
+ *    line protocol) — never reads files, never computes its own version;
+ *  - lifecycle surface: start() registers the OS auto-start entry
+ *    (the app's SSOT) which the ReadbackSurface reads back.
+ *
+ * Default export contract: `(stateDir: string) => HostDriver`; the
+ * lifecycle surfaces come from the same factory's `lifecycleSurfaces`.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import type { HostAdapter, ProcessEvidence, Slot } from "../../../core/src/lifecycle/hostAdapter.ts";
+import type { ReadbackSurface } from "../../../core/src/converge/predicates.ts";
+import type { HostDriver, LedgerState } from "../fake-host/inproc.ts";
+import { slotArtifactPath } from "../../../core/src/txn/fileEffects.ts";
+
+interface Successor {
+  child: ChildProcess;
+  version: string;
+  pid: number;
+  startId: string;
+}
+
+function readLine(child: ChildProcess, prefix: string, timeoutMs: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error(`timed out waiting for "${prefix}" from successor`));
+    }, timeoutMs);
+    const onData = (chunk: Buffer): void => {
+      buffer += chunk.toString("utf8");
+      // Only COMPLETE lines (newline-terminated) are protocol messages.
+      for (;;) {
+        const nl = buffer.indexOf("\n");
+        if (nl === -1) break;
+        const line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        if (line.startsWith(`${prefix} `)) {
+          cleanup();
+          resolve(line.slice(prefix.length + 1));
+          return;
+        }
+      }
+    };
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      child.stdout?.off("data", onData);
+    };
+    child.stdout?.on("data", onData);
+  });
+}
+
+async function tryReady(child: ChildProcess, timeoutMs: number): Promise<Successor | null> {
+  try {
+    const line = await readLine(child, "ready", timeoutMs);
+    const info = JSON.parse(line) as { version: string; pid: number; startId: string };
+    return { child, ...info };
+  } catch {
+    return null;
+  }
+}
+
+export function createServiceAdapter(stateDir: string): HostDriver & {
+  lifecycleSurfaces(): ReadbackSurface[];
+} {
+  let successor: Successor | null = null;
+  let runningSlot: Slot | null = null;
+
+  const autostartPath = path.join(stateDir, "lifecycle", "autostart.json");
+  const writeAutostart = async (slot: Slot): Promise<void> => {
+    await fs.mkdir(path.dirname(autostartPath), { recursive: true });
+    await fs.writeFile(
+      autostartPath,
+      JSON.stringify({ enabled: true, target: slotArtifactPath(stateDir, slot) }),
+    );
+  };
+
+  const host: HostAdapter = {
+    async quiesce() {
+      // computer does not preserve sessions: nothing to park
+    },
+    async stop() {
+      runningSlot = null;
+      const cur = successor;
+      successor = null;
+      if (cur) {
+        try {
+          process.kill(cur.pid, "SIGKILL");
+        } catch {
+          // already gone
+        }
+        const deadline = Date.now() + 5000;
+        while (processAlive(cur.pid)) {
+          if (Date.now() > deadline) throw new Error(`pid ${cur.pid} still alive`);
+          await new Promise((r) => {
+            setTimeout(r, 10);
+          });
+        }
+      }
+    },
+    async start(slot: Slot) {
+      runningSlot = slot;
+      const artifact = slotArtifactPath(stateDir, slot);
+      const child = spawn(process.execPath, [artifact], {
+        env: { ...process.env, K_STATE_DIR: stateDir },
+        stdio: ["pipe", "pipe", "ignore"],
+      });
+      const info = await tryReady(child, 5000);
+      successor = info;
+      if (info !== null) await writeAutostart(slot);
+    },
+    async healthProbe(): Promise<ProcessEvidence> {
+      const cur = successor;
+      if (!cur || cur.child.exitCode !== null) throw new Error("no live successor to probe");
+      cur.child.stdin?.write("probe\n");
+      const line = await readLine(cur.child, "evidence", 5000);
+      return JSON.parse(line) as ProcessEvidence;
+    },
+    async resume() {
+      // nothing parked in quiesce
+    },
+  };
+
+  return {
+    ...host,
+    get running(): Slot | null {
+      return runningSlot;
+    },
+    get parked(): boolean {
+      return false;
+    },
+    get startId(): string | null {
+      return successor?.startId ?? null;
+    },
+    async ledger(): Promise<Uint8Array> {
+      throw new Error("service adapter has no workload ledger");
+    },
+    async ledgerState(): Promise<LedgerState> {
+      throw new Error("service adapter has no workload ledger");
+    },
+    lifecycleSurfaces(): ReadbackSurface[] {
+      return [
+        {
+          id: "adapter.autostart",
+          read: async () => {
+            try {
+              const raw = await fs.readFile(autostartPath, "utf8");
+              const parsed = JSON.parse(raw) as { enabled: boolean; target: string };
+              return {
+                value: parsed.enabled ? parsed.target : "",
+                source: "adapter.autostart",
+              };
+            } catch {
+              return { value: "", source: "adapter.autostart" };
+            }
+          },
+        },
+      ];
+    },
+  };
+}
+
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export default createServiceAdapter;

package/harness/src/index.ts

@@ -0,0 +1,11 @@
+// Public API of @botiverse/k-carrier/harness — the acceptance harness.
+//
+// This barrel is the single supported entry point for the harness; deep
+// imports into ./harness/src/** are internal and not part of the public API.
+// The harness is also runnable as the `k-harness` bin.
+
+// The black-box target contract an adopter ships (k.target.ts) and its loader.
+export * from "./target.ts";
+
+// The in-process fake host used to exercise an adapter deterministically.
+export * from "./fake-host/inproc.ts";

package/harness/src/receipt.ts

@@ -0,0 +1,83 @@
+/**
+ * Structured receipt — the k-harness output contract (harness-design §1.3:
+ * "跑完输出结构化 receipt（给 CI 和人两用）"). Human-readable lines on
+ * stdout, full JSON on request (`--json`); exit code = 0 iff result pass.
+ */
+import type { Profile } from "./teeth/registry.ts";
+
+export type CheckStatus = "pass" | "fail" | "na";
+
+export interface CheckResult {
+  id: string;
+  status: CheckStatus;
+  /** Typed failure (`CODE: message`) or null on pass/na. */
+  error: string | null;
+  durationMs: number;
+}
+
+export type Mode = "profile" | "bin" | "adapter";
+
+export interface Receipt {
+  mode: Mode;
+  profile: Profile;
+  /** The binary/adapter under test, or null for profile mode. */
+  target: string | null;
+  startedAtMs: number;
+  durationMs: number;
+  checks: CheckResult[];
+  summary: { pass: number; fail: number; na: number; total: number };
+  result: "pass" | "fail";
+}
+
+export function buildReceipt(opts: {
+  mode: Mode;
+  profile: Profile;
+  target: string | null;
+  checks: CheckResult[];
+  startedAtMs?: number;
+  durationMs?: number;
+}): Receipt {
+  const pass = opts.checks.filter((c) => c.status === "pass").length;
+  const fail = opts.checks.filter((c) => c.status === "fail").length;
+  const na = opts.checks.filter((c) => c.status === "na").length;
+  // Fail-closed on BOTH shapes of nothing:
+  //   - an empty check list ("0 checks" ≠ "all passed"), and
+  //   - a list where nothing actually executed. A receipt of all-`na` used to
+  //     report pass, which is the empty suite wearing a non-empty list: the
+  //     count looks healthy and not one thing was verified.
+  // A green therefore requires at least one check that genuinely passed.
+  const result: "pass" | "fail" =
+    fail > 0 || opts.checks.length === 0 || pass === 0 ? "fail" : "pass";
+  return {
+    mode: opts.mode,
+    profile: opts.profile,
+    target: opts.target,
+    startedAtMs: opts.startedAtMs ?? Date.now(),
+    durationMs: opts.durationMs ?? 0,
+    checks: opts.checks,
+    summary: { pass, fail, na, total: opts.checks.length },
+    result,
+  };
+}
+
+const MARK: Record<CheckStatus, string> = { pass: "✔", fail: "✖", na: "–" };
+
+/** Human-readable lines (also on --json, so the receipt is never silent). */
+export function printReceiptLines(r: Receipt, out: (line: string) => void): void {
+  out(`k-harness ${r.mode} (profile ${r.profile}${r.target ? `, target ${r.target}` : ""})`);
+  for (const c of r.checks) {
+    const detail = c.status === "fail" ? ` — ${c.error}` : "";
+    out(`  ${MARK[c.status]} ${c.id} (${c.durationMs}ms)${detail}`);
+  }
+  out(
+    `result: ${r.result} — ${r.summary.pass} pass, ${r.summary.fail} fail, ${r.summary.na} na (${r.summary.total} checks, ${r.durationMs}ms)`,
+  );
+}
+
+export function printReceipt(r: Receipt, json: boolean, out: (line: string) => void = console.log): void {
+  if (json) {
+    out(JSON.stringify(r, null, 2));
+    return;
+  }
+  printReceiptLines(r, out);
+}

package/harness/src/runner.ts

@@ -0,0 +1,268 @@
+/**
+ * k-harness runner — executes the two non-bin modes:
+ *
+ *  - `--profile <cli|daemon|managed>`: runs the tier-filtered tooth set
+ *    (teethFor(profile), harness-design §1.5 分档执行), one fresh sandbox
+ *    per tooth, into a structured receipt.
+ *
+ *  - `--adapter <path>`: runs the adopter contract subset (§1.7: no
+ *    fault-switch teeth) against an external HostAdapter driver. The
+ *    module's default export must be a factory `(stateDir: string) =>
+ *    HostDriver`. Ledger checks are marked na when the adapter has no
+ *    workload driver; probe contract checks always run.
+ */
+import { pathToFileURL } from "node:url";
+import { teethFor, ALL_CAPABILITIES, type Profile, type ToothContext } from "./teeth/registry.ts";
+import { checkAdapterReleaseKnob } from "./adapter/releaseKnob.ts";
+import { checkAdapterProbeBindsLiveProcess } from "./adapter/probeChecks.ts";
+import { createSandbox } from "./scenario/sandbox.ts";
+import { buildReceipt, type CheckResult, type Receipt } from "./receipt.ts";
+import {
+  checkLedgerEquivalence,
+  checkLedgerEquivalenceAfterRollback,
+  checkProbeVersionMatchesSlot,
+  checkProbeBindsCurrentIncarnation,
+  hasWorkloadDriver,
+} from "./fake-host/checks.ts";
+import type { HostDriver } from "./fake-host/inproc.ts";
+import {
+  checkAdapterServiceUpgrade,
+  checkAdapterServiceRollback,
+  checkAdapterLifecycleConverged,
+  type ServiceAdapterFactory,
+} from "./adapter/serviceChecks.ts";
+
+/** Adapter contract subset: quiesce↔resume equivalence + probe 活性 (§1.7). */
+const ADAPTER_CHECKS: Array<{ id: string; run: (ctx: ToothContext, host: HostDriver) => Promise<void> }> = [
+  {
+    id: "adapter.ledger-equivalence",
+    run: (ctx, host) => checkLedgerEquivalence(ctx, { host }),
+  },
+  {
+    id: "adapter.ledger-equivalence-after-rollback",
+    run: (ctx, host) => checkLedgerEquivalenceAfterRollback(ctx, { host }),
+  },
+  {
+    id: "adapter.probe-version-matches-slot",
+    run: (ctx, host) => checkProbeVersionMatchesSlot(ctx, { host }),
+  },
+  {
+    id: "adapter.probe-binds-current-incarnation",
+    run: (ctx, host) => checkProbeBindsCurrentIncarnation(ctx, { host }),
+  },
+];
+
+async function runCheck(
+  id: string,
+  body: () => Promise<{ skipped: boolean }>,
+): Promise<CheckResult> {
+  const startedAtMs = Date.now();
+  try {
+    const { skipped } = await body();
+    return {
+      id,
+      status: skipped ? "na" : "pass",
+      error: null,
+      durationMs: Date.now() - startedAtMs,
+    };
+  } catch (err) {
+    return {
+      id,
+      status: "fail",
+      error: (err as Error).message,
+      durationMs: Date.now() - startedAtMs,
+    };
+  }
+}
+
+export async function runProfile(profile: Profile): Promise<Receipt> {
+  const startedAtMs = Date.now();
+  const teeth = teethFor(profile, ALL_CAPABILITIES);
+  // Fail-closed: an empty selection must never render as "all green"
+  // (zero teeth and all-passed are indistinguishable to CI otherwise).
+  if (teeth.length === 0) {
+    return buildReceipt({
+      mode: "profile",
+      profile,
+      target: null,
+      checks: [
+        {
+          id: "harness.empty-selection",
+          status: "fail",
+          error: `HARNESS_EMPTY_SELECTION: profile ${profile} selected 0 teeth`,
+          durationMs: 0,
+        },
+      ],
+      startedAtMs,
+      durationMs: Date.now() - startedAtMs,
+    });
+  }
+  const checks: CheckResult[] = [];
+  for (const tooth of teeth) {
+    checks.push(
+      await runCheck(tooth.id, async () => {
+        const sb = await createSandbox({ prefix: tooth.id.replaceAll(".", "-") });
+        try {
+          await tooth.run({ profile, sandboxDir: sb.dir });
+        } finally {
+          await sb.teardown();
+        }
+        return { skipped: false };
+      }),
+    );
+  }
+  return buildReceipt({
+    mode: "profile",
+    profile,
+    target: null,
+    checks,
+    startedAtMs,
+    durationMs: Date.now() - startedAtMs,
+  });
+}
+
+/** Load an adapter module: default export must be `(stateDir) => HostDriver`. */
+export async function loadAdapter(adapterPath: string): Promise<ServiceAdapterFactory> {
+  const mod = (await import(pathToFileURL(adapterPath).href)) as { default?: unknown };
+  const factory = mod.default;
+  if (typeof factory !== "function") {
+    throw new TypeError(
+      `adapter ${adapterPath}: default export must be a factory function (stateDir) => HostDriver`,
+    );
+  }
+  return factory as ServiceAdapterFactory;
+}
+
+export async function runAdapter(profile: Profile, adapterPath: string): Promise<Receipt> {
+  const startedAtMs = Date.now();
+  const factory = await loadAdapter(adapterPath);
+  // Fail-closed: an empty contract-check list must never render green.
+  if (ADAPTER_CHECKS.length === 0) {
+    return buildReceipt({
+      mode: "adapter",
+      profile,
+      target: adapterPath,
+      checks: [
+        {
+          id: "harness.empty-selection",
+          status: "fail",
+          error: `HARNESS_EMPTY_SELECTION: adapter contract subset selected 0 checks`,
+          durationMs: 0,
+        },
+      ],
+      startedAtMs,
+      durationMs: Date.now() - startedAtMs,
+    });
+  }
+  const checks: CheckResult[] = [];
+  // Shape probe: the inproc-driver marker (doWork/ledger) selects the
+  // contract subset; the lifecycleSurfaces marker selects the service-tier
+  // checks. An adapter with NEITHER implements no recognizable contract.
+  const inprocDriver = await (async () => {
+    const sb = await createSandbox({ prefix: "adapter-probe-driver" });
+    try {
+      return hasWorkloadDriver(factory(sb.dir));
+    } finally {
+      await sb.teardown();
+    }
+  })();
+  const serviceTier = await (async () => {
+    const sb = await createSandbox({ prefix: "adapter-probe-service" });
+    try {
+      const host = factory(sb.dir);
+      return typeof (host as { lifecycleSurfaces?: unknown }).lifecycleSurfaces === "function";
+    } finally {
+      await sb.teardown();
+    }
+  })();
+  if (!inprocDriver && !serviceTier) {
+    checks.push({
+      id: "adapter.must-declare-a-contract",
+      status: "fail",
+      error:
+        "HARNESS_ADAPTER_SHAPE: the adapter implements neither the inproc workload driver (doWork/ledger) nor the service-tier lifecycle surfaces — nothing is testable without a backdoor",
+      durationMs: 0,
+    });
+  }
+
+  for (const { id, run } of ADAPTER_CHECKS) {
+    checks.push(
+      await runCheck(id, async () => {
+        const sb = await createSandbox({ prefix: id.replaceAll(".", "-") });
+        try {
+          if (!inprocDriver) return { skipped: true };
+          const host = factory(sb.dir);
+          await run({ profile, sandboxDir: sb.dir }, host);
+        } finally {
+          await sb.teardown();
+        }
+        return { skipped: false };
+      }),
+    );
+  }
+
+  // Service-tier adapter acceptance: the SAME assertions as the service
+  // teeth (upgrade / rollback / lifecycle-converged), host swapped for the
+  // external adapter (same teeth, a different host implementation). Gated on the
+  // adapter declaring lifecycle surfaces — the service-tier marker; an
+  // adapter without them is a contract-subset-only host and the checks are
+  // skipped (like the ledger checks' driver skip).
+  if (profile === "service") {
+    const serviceChecks: Array<{
+      id: string;
+      needsSurfaces?: boolean;
+      run: (ctx: ToothContext, f: ServiceAdapterFactory) => Promise<void>;
+    }> = [
+      // First: every check below has a negative control that works by serving
+      // a crash-on-start release. If the adopter's source ignores the knob,
+      // those controls are no-ops and the passes below mean nothing -- so this
+      // is reported before them, not after.
+      { id: "adapter.service-release-knob-bites", run: (ctx, f) => checkAdapterReleaseKnob(ctx, f) },
+      {
+        id: "adapter.service-probe-binds-live-process",
+        run: (ctx, f) => checkAdapterProbeBindsLiveProcess(ctx, f),
+      },
+      { id: "adapter.service-upgrade", run: (ctx, f) => checkAdapterServiceUpgrade(ctx, f) },
+      { id: "adapter.service-rollback", run: (ctx, f) => checkAdapterServiceRollback(ctx, f) },
+      {
+        id: "adapter.lifecycle-converged",
+        // Lifecycle convergence is an opt-in CAPABILITY, not part of being a
+        // service. An adopter that drives no OS-lifecycle surface (a plain
+        // detached owner, say) has nothing to converge, and failing it for
+        // that would push adopters toward declaring a surface they do not
+        // actually read -- the projection L3 bans, invited by the harness.
+        //
+        // It reports `na`, never `pass`: exactly what core does with
+        // `hostLifecycleConverged: null`. Silence keeps its own value here too,
+        // so a receipt can never be read as "convergence checked".
+        needsSurfaces: true,
+        run: (ctx, f) => checkAdapterLifecycleConverged(ctx, f),
+      },
+    ];
+    for (const { id, needsSurfaces, run } of serviceChecks) {
+      checks.push(
+        await runCheck(id, async () => {
+          const sb = await createSandbox({ prefix: id.replaceAll(".", "-") });
+          try {
+            if (!serviceTier) return { skipped: true };
+            if (needsSurfaces === true && (factory(sb.dir).lifecycleSurfaces?.() ?? []).length === 0) {
+              return { skipped: true };
+            }
+            await run({ profile, sandboxDir: sb.dir }, factory);
+          } finally {
+            await sb.teardown();
+          }
+          return { skipped: false };
+        }),
+      );
+    }
+  }
+  return buildReceipt({
+    mode: "adapter",
+    profile,
+    target: adapterPath,
+    checks,
+    startedAtMs,
+    durationMs: Date.now() - startedAtMs,
+  });
+}

package/harness/src/scenario/processScan.ts

@@ -0,0 +1,55 @@
+/**
+ * Out-of-band process scan by marker token (the verify-dead primitive).
+ * Split from sandbox.ts, which owns the marker CONVENTION (see MARKER_ENV
+ * there: one literal token `NAME=value`, carried on BOTH env and argv).
+ */
+import { execFileSync } from "node:child_process";
+
+/**
+ * All pids observably carrying the marker token `NAME=value` — the
+ * sandbox-marker scan behind verify-dead.
+ *
+ * POSIX reads `ps eaxo pid=,command=`: the `e` flag appends each process's
+ * environment to its command line, so BOTH marker channels (env + argv) land
+ * in the same scanned text, and the marker survives the parent dying
+ * (orphans/zombies the host no longer tracks).
+ *
+ * Windows enumerates `Win32_Process` via PowerShell/CIM: only `CommandLine`
+ * is public there, so the ARGV channel is what makes a process claimable —
+ * which is exactly why the marker rides two channels.
+ */
+export function findPidsByMarkerToken(name: string, value: string): number[] {
+  const token = `${name}=${value}`;
+  if (process.platform === "win32") {
+    const out = execFileSync(
+      "powershell.exe",
+      [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress -Depth 1",
+      ],
+      { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
+    );
+    const parsed: unknown = JSON.parse(out);
+    const rows = Array.isArray(parsed) ? parsed : [parsed]; // ConvertTo-Json unwraps single rows
+    const pids: number[] = [];
+    for (const row of rows) {
+      if (typeof row !== "object" || row === null) continue;
+      const pid = (row as { ProcessId?: unknown }).ProcessId;
+      const commandLine = (row as { CommandLine?: unknown }).CommandLine;
+      if (typeof pid !== "number" || typeof commandLine !== "string") continue;
+      if (commandLine.includes(token)) pids.push(pid);
+    }
+    return pids;
+  }
+  const out = execFileSync("ps", ["eaxo", "pid=,command="], { encoding: "utf8" });
+  const pids: number[] = [];
+  for (const line of out.split("\n")) {
+    if (!line.includes(token)) continue;
+    const m = /^\s*(\d+)/.exec(line);
+    const pid = m?.[1];
+    if (pid) pids.push(Number(pid));
+  }
+  return pids;
+}