@botiverse/k-carrier 0.1.0

package/harness/src/artifact/m4.ts

@@ -0,0 +1,201 @@
+/**
+ * M4 consent & notification acceptance checks (the M4 spec).
+ *
+ *  - confirm without approval: policy=confirm holds BEFORE any disk side
+ *    effect — nothing is staged, not just nothing promoted.
+ *  - consent binds a SPECIFIC version: the continuation after approval
+ *    installs exactly the version that was offered; if the publisher moved
+ *    on, the continuation refuses instead of installing whatever is
+ *    current now. Consent is to a version, never to "the upgrade".
+ *  - notify-only: the notification carries the version that is ACTUALLY
+ *    installable, and nothing is staged.
+ */
+import assert from "node:assert/strict";
+import * as path from "node:path";
+import { promises as fs } from "node:fs";
+import { type ToothContext } from "../teeth/registry.ts";
+import { FakeServer } from "../fake-server/server.ts";
+import { runCommand } from "../artifact-factory/run.ts";
+import { buildSwapTool, coreUpgraderUrl, readState, serveRelease } from "./m1.ts";
+import { CLI_TOOL_SOURCE } from "../../../examples/swap-tool/source.ts";
+import { ArtifactFactory } from "../artifact-factory/factory.ts";
+import { currentPlatformKey } from "../../../core/src/artifact/staticManifestSource.ts";
+
+function swapEnv(ctx: ToothContext, baseUrl: string, servers: FakeServer[], extra: Record<string, string> = {}): Record<string, string> {
+  return {
+    K_RELEASE_BASE: baseUrl,
+    K_STATE_DIR: path.join(ctx.sandboxDir, "state"),
+    K_CORE_UPGRADER: coreUpgraderUrl(),
+    ...extra,
+  };
+}
+
+/** Assert the stateDir has NO transaction side effects at all (not staged). */
+async function assertZeroDiskSideEffects(ctx: ToothContext): Promise<void> {
+  const dir = path.join(ctx.sandboxDir, "state");
+  let exists = true;
+  try {
+    await fs.access(dir);
+  } catch {
+    exists = false;
+  }
+  if (!exists) return;
+  await assert.rejects(fs.access(path.join(dir, "journal.jsonl")), "journal must not exist");
+  await assert.rejects(fs.access(path.join(dir, "slots")), "slots must not exist");
+  await assert.rejects(fs.access(path.join(dir, "incoming")), "incoming must not exist");
+}
+
+// ---------------------------------------------------------------------------
+// m4.confirm-no-consent-zero-side-effects
+// ---------------------------------------------------------------------------
+
+export async function checkM4ConfirmNoConsentZeroSideEffects(
+  ctx: ToothContext,
+  opts: { policy?: "confirm" | "auto" } = {},
+): Promise<void> {
+  const binPath = await buildSwapTool(ctx);
+  const target = await serveRelease(ctx, {
+    version: "2.0.0",
+    behavior: "ok",
+    name: "target",
+    source: CLI_TOOL_SOURCE,
+  });
+  try {
+    const env = swapEnv(ctx, target.url, [target], { K_POLICY: opts.policy ?? "confirm" });
+    const up = await runCommand(binPath, ["self", "upgrade"], { env, timeoutMs: 30000 });
+    assert.equal(
+      up.code,
+      0,
+      `confirm-held must exit 0 (${up.stderr.trim()}; auto mutation => RED)`,
+    );
+    assert.match(up.stdout, /held: policy requires confirmation/, "confirm must hold, not install");
+    assert.match(
+      up.stderr,
+      /notify confirm-request v2\.0\.0/,
+      "a confirm-request must name the offered version",
+    );
+    // the whole point: nothing was staged, not just nothing promoted
+    await assertZeroDiskSideEffects(ctx);
+  } finally {
+    await target.stop();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// m4.consent-binds-version
+// ---------------------------------------------------------------------------
+
+export async function checkM4ConsentBindsVersion(
+  ctx: ToothContext,
+  opts: { serverSwitched?: boolean; expectInstalled?: boolean } = {},
+): Promise<void> {
+  const binPath = await buildSwapTool(ctx);
+  const target = await serveRelease(ctx, {
+    version: "2.0.0",
+    behavior: "ok",
+    name: "target",
+    source: CLI_TOOL_SOURCE,
+  });
+  try {
+    const env = swapEnv(ctx, target.url, [target], { K_POLICY: "confirm" });
+
+    // 1) offer: confirm-request names 2.0.0
+    const offer = await runCommand(binPath, ["self", "upgrade"], { env, timeoutMs: 30000 });
+    assert.equal(offer.code, 0, `offer must hold (${offer.stderr.trim()})`);
+    assert.match(offer.stdout, /held: policy requires confirmation/);
+    assert.match(offer.stderr, /notify confirm-request v2\.0\.0/);
+
+    // 2) the publisher moves on (or not) before the user answers
+    if (opts.serverSwitched) {
+      // the SAME server now serves 3.0.0 — the continuation must refuse the
+      // approved 2.0.0, not silently install whatever is current
+      // 3.0.0 must be a REAL, RUNNABLE release. Publishing garbage bytes here
+      // made this tooth pass for the wrong reason: with version binding
+      // removed, the continuation DID fetch 3.0.0 -- it just could not run, so
+      // the probe failed and nothing was installed, which is exactly what the
+      // oracle checks. The tooth then proves "the payload was unrunnable", not
+      // "consent is bound to a version". (Found in review by removing the
+      // binding and watching this stay green.)
+      const switchedFactory = new ArtifactFactory({
+        cacheDir: path.join(ctx.sandboxDir, "cache-switched"),
+        demoSource: CLI_TOOL_SOURCE,
+      });
+      await switchedFactory.makeRelease({
+        version: "3.0.0",
+        behavior: "ok",
+        store: target.store,
+        platform: currentPlatformKey(),
+      });
+      try {
+        const continueRun = await runCommand(binPath, ["confirm", "upgrade", "2.0.0"], {
+          env,
+          timeoutMs: 30000,
+        });
+        const v = await versionOf(binPath);
+        const st = await readState(env);
+        const nothingInstalled = v === "1.0.0" && st.stableVersion === "0.0.0";
+        if (opts.expectInstalled === true) {
+          // mutation expectation: the binding was lost and the continuation
+          // installed something — the zero-install assertion must go RED
+          assert.ok(!nothingInstalled, "the binding must have installed the offered version (expectInstalled => RED)");
+        } else {
+          assert.ok(nothingInstalled, "the continuation must refuse when the approved version is no longer served");
+          assert.match(continueRun.stdout, /held/, "the refusal must be a typed held, not a silent install");
+          assert.match(continueRun.stdout, /no longer served|nothing was installed/);
+        }
+        return;
+      } finally {
+        // nothing extra to stop: the switched release lives on `target`
+      }
+    }
+
+    // 3) green: the continuation installs EXACTLY the offered version
+    const cont = await runCommand(binPath, ["confirm", "upgrade", "2.0.0"], {
+      env,
+      timeoutMs: 30000,
+    });
+    assert.equal(cont.code, 0, `continuation must exit 0 (${cont.stderr.trim()})`);
+    assert.match(cont.stdout, /upgraded to 2\.0\.0/);
+    assert.equal(await versionOf(binPath), "2.0.0", "the continuation must install the OFFERED version");
+    const st = await readState(env);
+    assert.equal(st.stableVersion, "2.0.0", "stable must hold the approved version");
+    assert.equal(st.phase, "promoted");
+  } finally {
+    await target.stop();
+  }
+}
+
+async function versionOf(binPath: string): Promise<string> {
+  const v = await runCommand(binPath, ["--version"], { timeoutMs: 30000 });
+  assert.equal(v.code, 0, `version command failed (${v.stderr.trim()})`);
+  return v.stdout.trim();
+}
+
+// ---------------------------------------------------------------------------
+// m4.notify-only-reports-installable-version
+// ---------------------------------------------------------------------------
+
+export async function checkM4NotifyOnlyReportsInstallableVersion(
+  ctx: ToothContext,
+  opts: { policy?: "notify-only" | "confirm" } = {},
+): Promise<void> {
+  const binPath = await buildSwapTool(ctx);
+  const target = await serveRelease(ctx, {
+    version: "2.0.0",
+    behavior: "ok",
+    name: "target",
+    source: CLI_TOOL_SOURCE,
+  });
+  try {
+    const env = swapEnv(ctx, target.url, [target], { K_POLICY: opts.policy ?? "notify-only" });
+    const up = await runCommand(binPath, ["self", "upgrade"], { env, timeoutMs: 30000 });
+    assert.equal(up.code, 0, `notify-only must exit 0 (${up.stderr.trim()}; confirm mutation => RED)`);
+    assert.match(up.stdout, /held: policy is notify-only/, "notify-only must hold, not install");
+    // the notification must name the version that is ACTUALLY installable
+    assert.match(up.stderr, /notify held v2\.0\.0: notify-only/);
+    await assertZeroDiskSideEffects(ctx);
+  } finally {
+    await target.stop();
+  }
+}
+

package/harness/src/artifact/m5.ts

@@ -0,0 +1,239 @@
+/**
+ * M5 platform-surface / lifecycle-convergence acceptance checks
+ * (test-plan M5 rows: 点名面读回一致；面在 allowlist 才可作证；未注册面被引用
+ * ⇒ 拒; fail-closed 退役序; 禁投影).
+ *
+ * These drive createUpgrader in-process (the library plane — the converge
+ * machinery is exactly the kind of internal tooth the black-box plane
+ * cannot reach).
+ */
+import assert from "node:assert/strict";
+import * as path from "node:path";
+import { type ToothContext } from "../teeth/registry.ts";
+import { createUpgrader, type CreateUpgraderOptions } from "../../../core/src/createUpgrader.ts";
+import { staticManifestSource } from "../../../core/src/artifact/staticManifestSource.ts";
+import {
+  buildSurfaceAllowlist,
+  readAllowlisted,
+  evaluateLifecycleConvergence,
+} from "../../../core/src/converge/lifecycle.ts";
+import type { ReadbackSurface } from "../../../core/src/converge/predicates.ts";
+import type { HostAdapter, ProcessEvidence, Slot } from "../../../core/src/lifecycle/hostAdapter.ts";
+import { slotArtifactPath } from "../../../core/src/txn/fileEffects.ts";
+import { FakeServer } from "../fake-server/server.ts";
+import { ArtifactFactory } from "../artifact-factory/factory.ts";
+
+function stateDir(ctx: ToothContext): string {
+  return path.join(ctx.sandboxDir, "state");
+}
+
+/** A host whose probe reports the started slot's version (swap-like). */
+function simpleHost(): HostAdapter {
+  let version = "0.0.0";
+  let startId = "init";
+  return {
+    async quiesce() {},
+    async stop() {},
+    async start(slot: Slot) {
+      version = slot === "experiment" ? "2.0.0" : "1.0.0";
+      startId = `${slot}-${Math.random().toString(36).slice(2)}`;
+    },
+    async healthProbe(): Promise<ProcessEvidence> {
+      return { version, pid: process.pid, startId };
+    },
+    async resume() {},
+  };
+}
+
+function makeSurface(id: string, value: () => Promise<string>): ReadbackSurface {
+  return { id, read: async () => ({ value: await value(), source: id }) };
+}
+
+async function serveTarget(ctx: ToothContext): Promise<FakeServer> {
+  const server = new FakeServer({ storeDir: path.join(ctx.sandboxDir, "store") });
+  await server.start();
+  const factory = new ArtifactFactory({ cacheDir: path.join(ctx.sandboxDir, "cache") });
+  await factory.makeRelease({
+    version: "2.0.0",
+    behavior: "ok",
+    store: server.store,
+    platform: (await import("../../../core/src/artifact/staticManifestSource.ts")).currentPlatformKey(),
+  });
+  return server;
+}
+
+function makeUpgrader(
+  ctx: ToothContext,
+  server: FakeServer,
+  surfaces: ReadbackSurface[],
+): ReturnType<typeof createUpgrader> {
+  const opts: CreateUpgraderOptions = {
+    host: simpleHost(),
+    source: staticManifestSource({ baseUrl: server.url }),
+    policy: "auto",
+    notificationSink: async () => {},
+    stateDir: stateDir(ctx),
+    lifecycleSurfaces: surfaces,
+  };
+  return createUpgrader(opts);
+}
+
+// ---------------------------------------------------------------------------
+// m5.lifecycle-surface-allowlist
+// ---------------------------------------------------------------------------
+
+export async function checkM5LifecycleSurfaceAllowlist(
+  ctx: ToothContext,
+  opts: { acceptUnknown?: boolean } = {},
+): Promise<void> {
+  const allowlist = buildSurfaceAllowlist([
+    { surface: makeSurface("test.autostart", async () => "registered-path"), expectedTarget: "registered-path" },
+  ]);
+  if (opts.acceptUnknown) {
+    // mutation: an unknown surface id is accepted as evidence — the
+    // refusal assertion must go RED
+    assert.ok(
+      (await readAllowlisted(allowlist, "not-declared")).value.length >= 0,
+      "unregistered surface must be refused (acceptUnknown => RED)",
+    );
+    return;
+  }
+  // an id not on the allowlist is a typed refusal (未注册面被引用 ⇒ 拒)
+  await assert.rejects(readAllowlisted(allowlist, "not-declared"), /UNREGISTERED_SURFACE/);
+
+  // and the evaluator refuses when a declared surface cannot be read
+  const broken = await evaluateLifecycleConvergence(
+    buildSurfaceAllowlist([
+      {
+        surface: makeSurface("broken.autostart", async () => {
+          throw new Error("surface cannot be read on this machine");
+        }),
+        expectedTarget: "x",
+      },
+    ]),
+    0,
+  );
+  assert.equal(broken.passed, false, "an unreadable surface cannot vouch for convergence");
+  assert.match(broken.source, /broken\.autostart/);
+}
+
+// ---------------------------------------------------------------------------
+// m5.lifecycle-converged-promotes
+// ---------------------------------------------------------------------------
+
+export async function checkM5LifecycleConvergedPromotes(
+  ctx: ToothContext,
+  opts: { staleSurface?: boolean } = {},
+): Promise<void> {
+  const server = await serveTarget(ctx);
+  try {
+    const dir = stateDir(ctx);
+    const target = slotArtifactPath(dir, "experiment");
+    const stale = path.join(dir, "slots", "stable", "artifact.bin");
+    const surface = opts.staleSurface
+      ? { id: "test.autostart", read: async () => ({ value: stale, source: "test.autostart" }) }
+      : { id: "test.autostart", read: async () => ({ value: target, source: "test.autostart" }) };
+    const upgrader = makeUpgrader(ctx, server, [surface]);
+    const outcome = await upgrader.upgrade();
+    if (opts.staleSurface) {
+      // mutation: the surface reads back the OLD path — the predicate must
+      // refuse, so the promote assertion goes RED
+      assert.equal(
+        outcome.result,
+        "promoted",
+        "convergence requires the surface to read back the new artifact (staleSurface => RED)",
+      );
+      return;
+    }
+    assert.equal(outcome.result, "promoted", "a converged surface must allow the promote");
+    const lifecycle = outcome.report?.hostLifecycleConverged ?? null;
+    assert.ok(lifecycle, "this app DID declare a surface, so the report must carry a verdict");
+    assert.equal(lifecycle.passed, true, "the report must carry the real converged predicate");
+    assert.equal(lifecycle.source, "test.autostart");
+    assert.equal(outcome.report?.binaryAtTarget.passed, true);
+  } finally {
+    await server.stop();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// m5.lifecycle-projection-ban
+// ---------------------------------------------------------------------------
+
+export async function checkM5LifecycleProjectionBan(
+  ctx: ToothContext,
+  opts: { acceptProjection?: boolean } = {},
+): Promise<void> {
+  // projection: the surface value is the VERSION string (metadata), not the
+  // artifact path — it must never satisfy host_lifecycle_converged
+  const projection = makeSurface("test.autostart", async () => "2.0.0");
+  const result = await evaluateLifecycleConvergence(
+    buildSurfaceAllowlist([
+      { surface: projection, expectedTarget: slotArtifactPath(stateDir(ctx), "experiment") },
+    ]),
+    0,
+  );
+  if (opts.acceptProjection) {
+    // mutation expectation: the projection IS accepted as convergence — the
+    // real evaluator refuses it, so this assertion must go RED
+    assert.equal(result.passed, true, "metadata must not green the predicate (acceptProjection => RED)");
+    return;
+  }
+  assert.equal(result.passed, false, "a version string is not lifecycle evidence (projection ban)");
+  assert.match(JSON.stringify(result.detail), /does not reference the installed artifact path/);
+
+  // end to end: the upgrade with a projecting surface refuses to promote
+  const server = await serveTarget(ctx);
+  try {
+    const upgrader = makeUpgrader(ctx, server, [projection]);
+    const outcome = await upgrader.upgrade();
+    assert.notEqual(outcome.result, "promoted", "a projecting surface must block the promote");
+  } finally {
+    await server.stop();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// m5.lifecycle-fail-closed-retirement
+// ---------------------------------------------------------------------------
+
+export async function checkM5LifecycleFailClosedRetirement(
+  ctx: ToothContext,
+  opts: { retireUnconditionally?: boolean } = {},
+): Promise<void> {
+  const server = await serveTarget(ctx);
+  try {
+    // the surface reads back the OLD path: convergence fails
+    const stale = path.join(stateDir(ctx), "slots", "stable", "artifact.bin");
+    const surface = { id: "test.autostart", read: async () => ({ value: stale, source: "test.autostart" }) };
+    const upgrader = makeUpgrader(ctx, server, [surface]);
+    const outcome = await upgrader.upgrade();
+    assert.notEqual(outcome.result, "promoted", "the non-converged upgrade must not promote");
+
+    const retire = await upgrader.retireLegacyManager();
+    if (opts.retireUnconditionally) {
+      // mutation: retirement ignores convergence — the HOLD assertion goes RED
+      assert.equal(retire, "retired", "retirement before convergence must be a HOLD (unconditional => RED)");
+      return;
+    }
+    assert.notEqual(retire, "retired", "retirement before convergence is a typed HOLD");
+    assert.match((retire as { held: string }).held, /before host_lifecycle_converged passed/);
+
+    // after a CONVERGED promote, retirement is allowed
+    const goodServer = await serveTarget(ctx);
+    try {
+      const dir = stateDir(ctx);
+      const target = slotArtifactPath(dir, "experiment");
+      const goodSurface = { id: "test.autostart", read: async () => ({ value: target, source: "test.autostart" }) };
+      const up2 = makeUpgrader(ctx, goodServer, [goodSurface]);
+      const good = await up2.upgrade();
+      assert.equal(good.result, "promoted");
+      assert.equal(await up2.retireLegacyManager(), "retired", "post-convergence retirement is allowed");
+    } finally {
+      await goodServer.stop();
+    }
+  } finally {
+    await server.stop();
+  }
+}
+