@botiverse/k-carrier 0.1.0

package/harness/src/artifact/m6Mutations.ts

@@ -0,0 +1,136 @@
+/**
+ * M6 mutation journals/summaries — the wrong behaviors each tooth's
+ * negative control must catch (one per conjunct, the AND-gate rule).
+ * Kept separate from m6.ts so both files stay under the line budget.
+ */
+import { promises as fs } from "node:fs";
+import {
+  ProvenanceError,
+  summarizeProvenance,
+  type ProvenanceJournal,
+  type ProvenanceEntry,
+  type ProvenanceRead,
+  type ProvenanceSummary,
+} from "../../../core/src/provenance/journal.ts";
+
+/** Mutation journal: reuses an existing seq (history can be collapsed). */
+export function reuseSeqJournal(): ProvenanceJournal {
+  const entries: ProvenanceEntry[] = [];
+  return {
+    async append(entry, explicitSeq) {
+      const full: ProvenanceEntry = { seq: explicitSeq ?? 0, who: entry.who, carrier: entry.carrier, when: 0, version: entry.version };
+      entries.push(full);
+      return full;
+    },
+    async read() {
+      return { kind: "observed", entries };
+    },
+  };
+}
+
+/** Mutation journal: accepts a duplicate seq (rewrites history). */
+export function acceptingJournal(): ProvenanceJournal {
+  let seq = -1;
+  const entries: ProvenanceEntry[] = [];
+  return {
+    async append(entry, explicitSeq) {
+      const next = explicitSeq ?? seq + 1;
+      seq = Math.max(seq, next);
+      const full: ProvenanceEntry = { seq: next, who: entry.who, carrier: entry.carrier, when: 0, version: entry.version };
+      entries.push(full);
+      return full;
+    },
+    async read() {
+      return { kind: "observed", entries };
+    },
+  };
+}
+
+/** Mutation journal: read keeps a torn (unparsed) final line. */
+export function keepTornJournal(inner: ProvenanceJournal, file: string): ProvenanceJournal {
+  return {
+    append: (e, s) => inner.append(e, s),
+    async read() {
+      const base = await inner.read();
+      if (base.kind !== "observed") return base;
+      const text = await fs.readFile(file, "utf8");
+      const lines = text.split("\n").filter((l) => l.trim());
+      const entries: ProvenanceEntry[] = [];
+      for (const line of lines) {
+        try {
+          entries.push(JSON.parse(line) as ProvenanceEntry);
+        } catch {
+          // mutation: the torn line is KEPT as an entry — history now
+          // contains something that never completed
+          entries.push({ seq: 99, who: "torn", carrier: "torn", when: 0, version: "torn" });
+        }
+      }
+      return { kind: "observed", entries };
+    },
+  };
+}
+
+/** Mutation journal: appends even when the history is unreadable/corrupt —
+ * the wrong behavior the tooth guards against. Delegates to the real
+ * journal until the corruption, then GUESSES the next seq (the
+ * rewrite-under-a-truncated-view attack) instead of refusing. */
+export function appendOnCorruptJournal(file: string, inner: ProvenanceJournal): ProvenanceJournal {
+  return {
+    async append(entry, explicitSeq) {
+      try {
+        return await inner.append(entry, explicitSeq);
+      } catch (err) {
+        if (err instanceof ProvenanceError && err.code === "PROVENANCE_HISTORY_UNREADABLE") {
+          const full: ProvenanceEntry = { seq: explicitSeq ?? 0, who: entry.who, carrier: entry.carrier, when: 0, version: entry.version };
+          await fs.appendFile(file, `${JSON.stringify(full)}\n`);
+          return full;
+        }
+        throw err;
+      }
+    },
+    async read() {
+      return inner.read();
+    },
+  };
+}
+
+/** Mutation journal: reports genesis for an empty-but-present journal. */
+export function emptyAsGenesisJournal(): ProvenanceJournal {
+  return {
+    async append(): Promise<ProvenanceEntry> {
+      throw new Error("unused");
+    },
+    async read() {
+      return { kind: "genesis" };
+    },
+  };
+}
+
+/** Mutation summary: folds the unreadable bucket into notObserved. */
+export function mergeUnreadableSummary(reads: readonly ProvenanceRead[]): ProvenanceSummary {
+  const base = summarizeProvenance(reads);
+  return {
+    recorded: base.recorded,
+    reconciles: base.reconciles,
+    notObserved: base.notObserved + base.unreadable,
+    unreadable: 0,
+  };
+}
+
+/** Mutation journal: entries are only durable AFTER the outcome (not
+ * write-ahead) — the wrong wiring the tooth guards against. */
+export function promoteOnlyJournal(inner: ProvenanceJournal): ProvenanceJournal & { flush(): Promise<void> } {
+  const buffered: Array<{ who: string; carrier: string; version: string }> = [];
+  return {
+    async append(entry) {
+      buffered.push({ ...entry });
+      return { seq: buffered.length - 1, ...entry, when: 0 };
+    },
+    async read() {
+      return { kind: "observed", entries: [] }; // nothing durable until flushed
+    },
+    async flush() {
+      for (const b of buffered) await inner.append(b);
+    },
+  };
+}

package/harness/src/artifact/m6Status.ts

@@ -0,0 +1,224 @@
+/**
+ * M6 status-report acceptance checks (test-plan M6 rows: the fleet
+ * read-back equals the live sources at the same moment; a machine that has
+ * never observed a promote reports NOT_OBSERVED — never a fabricated pass;
+ * an unreadable report is its own state, never "never observed"; an
+ * observed pass survives a restart).
+ *
+ * These drive createUpgrader in-process: status() is the L5 read-back
+ * surface, and the teeth pin that it is a READ-BACK, not an invention.
+ */
+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 { fileProvenanceJournal } from "../../../core/src/provenance/journal.ts";
+import { systemClock } from "../../../core/src/clock.ts";
+import type { StatusReport, StatusPredicates } from "../../../core/src/status/report.ts";
+import { serveRelease } from "./m1.ts";
+import { stateDir, makeUpgrader } from "./m6.ts";
+
+function reportFile(ctx: ToothContext): string {
+  return path.join(stateDir(ctx), "report.json");
+}
+
+// ---------------------------------------------------------------------------
+// m6.status-report-matches-local
+// ---------------------------------------------------------------------------
+
+/** Mutation: a status report that INVENTED a field (stable says 9.9.9 while
+ * the machine is on 1.0.0) — the read-back violation the tooth guards
+ * against. */
+function inventedStatus(base: StatusReport): StatusReport {
+  return { ...base, stable: "9.9.9" };
+}
+
+/** Mutation: a REAL conclusion pasted onto the WRONG version (the predicates
+ * are 2.0.0's but claim 3.0.0) — worse than a fake, because consumers join
+ * on the stamp. */
+function wrongStamp(base: StatusReport): StatusReport {
+  if (base.predicates.kind !== "observed") return base;
+  return { ...base, predicates: { ...base.predicates, version: "3.0.0" } };
+}
+
+export async function checkM6StatusReportMatchesLocal(
+  ctx: ToothContext,
+  opts: { inventStable?: boolean; wrongVersionStamp?: boolean } = {},
+): Promise<void> {
+  const journal = fileProvenanceJournal(path.join(stateDir(ctx), "provenance"), systemClock);
+  const server = await serveRelease(ctx, { version: "2.0.0", behavior: "ok", name: "target" });
+  try {
+    const upgrader = await makeUpgrader(ctx, server, journal);
+
+    // Fresh machine: the report equals the live sources AT THE SAME MOMENT.
+    const st1 = await upgrader.state();
+    const s1 = opts.inventStable ? inventedStatus(await upgrader.status()) : await upgrader.status();
+    assert.equal(
+      s1.stable,
+      st1.stableVersion,
+      "the report's stable is the machine's stable, never an invention (inventStable => RED)",
+    );
+    assert.equal(s1.experiment, st1.experimentVersion, "the report's experiment is the machine's experiment");
+    assert.equal(s1.phase, st1.phase, "the report's phase is the machine's phase");
+    assert.equal(s1.policy, "auto", "the report's policy is the configured policy");
+    const jr = await journal.read();
+    assert.deepEqual(s1.provenance, jr, "the report's provenance is the journal's read");
+
+    // After a real promote: the predicates are the last REAL report's,
+    // stamped with the version they evaluated.
+    const outcome = await upgrader.upgradeTo("2.0.0", {
+      consented: true,
+      provenance: { who: "fleet-control", carrier: "example-host" },
+    });
+    assert.equal(outcome.result, "promoted", "the reconcile must promote");
+    assert.ok(outcome.report !== null, "a promoted reconcile carries a convergence report");
+    assert.equal(outcome.report!.version, "2.0.0", "the convergence report is stamped with the version it evaluated");
+    const s2 = opts.wrongVersionStamp ? wrongStamp(await upgrader.status()) : await upgrader.status();
+    assert.equal(
+      s2.predicates.kind,
+      "observed",
+      "after a promote the predicates are the real report's (wrongVersionStamp => RED)",
+    );
+    if (s2.predicates.kind !== "observed") return;
+    assert.equal(
+      s2.predicates.version,
+      "2.0.0",
+      "the status passes the evaluated version through verbatim — a real conclusion must never be joined to the wrong version (wrongVersionStamp => RED)",
+    );
+    assert.deepEqual(
+      s2.predicates.binaryAtTarget,
+      outcome.report!.binaryAtTarget,
+      "the report's binaryAtTarget is the last real evaluation",
+    );
+    assert.deepEqual(
+      s2.predicates.hostLifecycleConverged,
+      outcome.report!.hostLifecycleConverged,
+      "the report's lifecycle predicate is the last real evaluation",
+    );
+    const st2 = await upgrader.state();
+    assert.equal(s2.stable, st2.stableVersion, "after promote, the report still reads the live stable");
+  } finally {
+    await server.stop();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// m6.status-report-silence-not-evidence
+// ---------------------------------------------------------------------------
+
+/** Mutation: a PASSING predicate a machine never evaluated (silence spent
+ * as evidence) — the wrong status reports an `observed` shape on a machine
+ * whose predicates are actually genesis. */
+function fabricatedPass(which: "binary" | "lifecycle"): StatusPredicates {
+  const fake = { passed: true, source: "fabricated", observedAtMs: 0, detail: {} };
+  return which === "binary"
+    ? { kind: "observed", version: "2.0.0", binaryAtTarget: fake, hostLifecycleConverged: null }
+    : { kind: "observed", version: "2.0.0", binaryAtTarget: { ...fake, detail: { version: "2.0.0" } }, hostLifecycleConverged: fake };
+}
+
+/** Mutation: the report lives only in memory — a restart erases the
+ * observation ("observed, I restarted" collapses into "never observed"). */
+function forgettingStatus(base: StatusReport): StatusReport {
+  return { ...base, predicates: { kind: "genesis" } };
+}
+
+export async function checkM6StatusReportSilenceNotEvidence(
+  ctx: ToothContext,
+  opts: {
+    fabricateBinaryPassed?: boolean;
+    fabricateConvergedPassed?: boolean;
+    fabricateAfterRollback?: boolean;
+    noPersistence?: boolean;
+    unreadableIsGenesis?: boolean;
+  } = {},
+): Promise<void> {
+  const journal = fileProvenanceJournal(path.join(stateDir(ctx), "provenance"), systemClock);
+  const good = await serveRelease(ctx, { version: "2.0.0", behavior: "ok", name: "good" });
+  const bad = await serveRelease(ctx, { version: "3.0.0", behavior: "ok", name: "bad" });
+  try {
+    const upgrader = await makeUpgrader(ctx, good, journal);
+
+    // A machine that never observed a promote is NOT_OBSERVED — never a
+    // fabricated pass (in either predicate).
+    const fresh = await upgrader.status();
+    const s1 = opts.fabricateBinaryPassed
+      ? { ...fresh, predicates: fabricatedPass("binary") }
+      : opts.fabricateConvergedPassed
+        ? { ...fresh, predicates: fabricatedPass("lifecycle") }
+        : fresh;
+    assert.equal(
+      s1.predicates.kind,
+      "genesis",
+      "never observed => predicates are genesis (NOT_OBSERVED), never a fabricated pass (fabricateBinaryPassed | fabricateConvergedPassed => RED)",
+    );
+
+    // A reconcile that REACHES the machine but FAILS (auto-rollback) does
+    // not become a pass either: the machine observed a failure, and
+    // "observed a failure" is not "evaluated and passed". A second upgrader
+    // on the moved-on source (same machine: stateDir + journal shared) does
+    // the failing attempt; it has never promoted, so its predicates must
+    // still be genesis.
+    const failingUpgrader = await makeUpgrader(ctx, bad, journal);
+    const r = await failingUpgrader.upgradeTo("3.0.0", {
+      consented: true,
+      provenance: { who: "fleet-control", carrier: "example-host" },
+    });
+    assert.equal(r.result, "rolled-back", "the bad reconcile must roll back");
+    const after = await failingUpgrader.status();
+    const s2 = opts.fabricateAfterRollback ? { ...after, predicates: fabricatedPass("lifecycle") } : after;
+    assert.equal(
+      s2.predicates.kind,
+      "genesis",
+      "a rolled-back reconcile observes a failure, never a pass (fabricateAfterRollback => RED)",
+    );
+
+    // A machine that DID converge must not report NOT_OBSERVED after a
+    // restart: "observed, I restarted" is not "never observed". The report
+    // is persisted at promote and loaded by a fresh upgrader on the same
+    // stateDir.
+    const promoted = await upgrader.upgradeTo("2.0.0", {
+      consented: true,
+      provenance: { who: "fleet-control", carrier: "example-host" },
+    });
+    assert.equal(promoted.result, "promoted", "the good reconcile must promote");
+    const restarted = await makeUpgrader(ctx, good, journal); // same stateDir: the daemon restarted
+    const afterRestart = opts.noPersistence
+      ? forgettingStatus(await restarted.status())
+      : await restarted.status();
+    assert.equal(
+      afterRestart.predicates.kind,
+      "observed",
+      "an observed pass survives a restart — the persisted report is loaded, never erased (noPersistence => RED)",
+    );
+    if (afterRestart.predicates.kind !== "observed") return;
+    assert.equal(afterRestart.predicates.version, "2.0.0", "the persisted report keeps its version stamp");
+    assert.equal(
+      afterRestart.predicates.binaryAtTarget.passed,
+      true,
+      "the persisted report carries the real observed result, not a fabrication",
+    );
+
+    // A report that exists but cannot be read is the THIRD state — never
+    // genesis ("I cannot see the data" is not "there is no data"), and
+    // retirement names the true reason instead of the fake "never observed".
+    await fs.writeFile(reportFile(ctx), '{"version": "2.0.0", "binaryAtTarget": BROKEN', "utf8");
+    const afterCorrupt = await makeUpgrader(ctx, good, journal);
+    const s4 = opts.unreadableIsGenesis
+      ? { ...(await afterCorrupt.status()), predicates: { kind: "genesis" as const } }
+      : await afterCorrupt.status();
+    assert.equal(
+      s4.predicates.kind,
+      "unreadable",
+      "an unreadable report is its own state, never genesis (unreadableIsGenesis => RED)",
+    );
+    const retire = await afterCorrupt.retireLegacyManager();
+    assert.notEqual(retire, "retired", "retirement stays fail-closed on an unreadable report");
+    assert.ok(
+      typeof retire === "object" && retire.held.includes("cannot be read"),
+      "the retirement HOLD names the real reason: unreadable, not never-observed",
+    );
+  } finally {
+    await good.stop();
+    await bad.stop();
+  }
+}

package/harness/src/artifact-factory/checks.ts

@@ -0,0 +1,68 @@
+/**
+ * artifact-factory acceptance checks — run bodies of the factory teeth
+ * (registered in teeth/artifactFactory.ts). Each throws on violation.
+ *
+ * The two acceptance claims (harness-design §1.77):
+ *  - determinism: same (version, behavior) builds byte-identical artifacts
+ *    — and since Ed25519 is deterministic, the whole published release
+ *    (artifact + manifest + signatures) reproduces exactly;
+ *  - the ok artifact is a REAL binary: it runs and reports the stamped
+ *    version (this is what makes "升到坏版本→自动回滚" black-box testable).
+ */
+import assert from "node:assert/strict";
+import * as path from "node:path";
+import { type ToothContext } from "../teeth/registry.ts";
+import { ArtifactFactory, type Behavior } from "./factory.ts";
+import { runArtifact } from "./run.ts";
+import { ReleaseStore } from "../fake-server/store.ts";
+import { MANIFEST_FILE } from "../fake-server/manifest.ts";
+
+function storeFor(dir: string, name: string): ReleaseStore {
+  return new ReleaseStore(path.join(dir, name));
+}
+
+/**
+ * Two independent factories (fresh caches) with the same input must produce
+ * byte-identical artifacts and manifests. `secondFactory`
+ * overrides factory B for known-red driving.
+ */
+export async function checkDeterministicBuild(
+  ctx: ToothContext,
+  secondFactory?: ArtifactFactory,
+): Promise<void> {
+  const factoryA = new ArtifactFactory({ cacheDir: path.join(ctx.sandboxDir, "cache-a") });
+  const factoryB = secondFactory ?? new ArtifactFactory({ cacheDir: path.join(ctx.sandboxDir, "cache-b") });
+  const storeA = storeFor(ctx.sandboxDir, "store-a");
+  const storeB = storeFor(ctx.sandboxDir, "store-b");
+  const a = await factoryA.makeRelease({ version: "2.0.0", behavior: "ok", store: storeA });
+  const b = await factoryB.makeRelease({ version: "2.0.0", behavior: "ok", store: storeB });
+  assert.deepEqual(
+    b.artifactBytes,
+    a.artifactBytes,
+    "same version+behavior must stamp byte-identical artifacts",
+  );
+  const manifestA = await storeA.readFile(MANIFEST_FILE);
+  const manifestB = await storeB.readFile(MANIFEST_FILE);
+  assert.deepEqual(manifestB, manifestA, "manifests must be byte-identical");
+}
+
+/**
+ * The ok artifact must be a real executable that runs and reports its
+ * stamped version. `behavior` overrides the build knob for known-red
+ * driving (a broken build behaves exactly like a must-red mutation).
+ */
+export async function checkOkArtifactRuns(ctx: ToothContext, behavior: Behavior = "ok"): Promise<void> {
+  const factory = new ArtifactFactory({ cacheDir: path.join(ctx.sandboxDir, "cache") });
+  const store = storeFor(ctx.sandboxDir, "store");
+  const version = "1.2.3";
+  const rel = await factory.makeRelease({ version, behavior, store });
+  const artifactPath = path.join(ctx.sandboxDir, "store", "releases", version, rel.artifactFile);
+  const r = await runArtifact(artifactPath);
+  assert.equal(r.timedOut, false, "ok artifact must not hang");
+  assert.equal(r.code, 0, "ok artifact must exit 0");
+  assert.equal(
+    r.stdout.trim(),
+    `${version} ready`,
+    "ok artifact must report the stamped version",
+  );
+}

package/harness/src/artifact-factory/demo.ts

@@ -0,0 +1,70 @@
+/**
+ * The artifact-factory's built-in demo source (harness-design §1.77).
+ *
+ * A tiny zero-dependency node script that IS the "demo binary". It
+ * implements the black-box CLI contract (§1.76): `--version` prints the
+ * stamped version, and `self upgrade` performs a cli-profile self-upgrade
+ * (L1': fetch the manifest from K_RELEASE_BASE, verify the artifact's
+ * sha256, atomically swap its own bytes — next run is the new version).
+ * The default run reports its version (the factory teeth's "runs and
+ * reports" claim).
+ *
+ * `__K_VERSION__` / `__K_BEHAVIOR__` are the stamp placeholders; behavior
+ * bakes deliberate breakage into the artifact (fixture source for rollback
+ * teeth, known-red and adversarial samples).
+ *
+ * K_RELEASE_BASE is the config surface for the fake-server URL — a real
+ * app configures its own release source; the harness points it at localhost.
+ */
+export const DEMO_SOURCE = `#!/usr/bin/env node
+// K demo binary — stamped by artifact-factory (harness-design §1.77).
+// Black-box cli contract (§1.76): --version / self upgrade. K_RELEASE_BASE
+// env = this demo app's own release-source config (localhost in harness).
+"use strict";
+const VERSION = "__K_VERSION__";
+const BEHAVIOR = "__K_BEHAVIOR__";
+const RELEASE_BASE = process.env.K_RELEASE_BASE;
+const fs = require("node:fs");
+// Synchronous writes: process.exit()/SIGKILL can truncate buffered pipe
+// writes, and the black-box assertions read stdout as evidence.
+function report(v) { fs.writeSync(1, v + " ready\\n"); }
+function printVersion() { fs.writeSync(1, VERSION + "\\n"); process.exit(0); }
+
+async function selfUpgrade() {
+  if (!RELEASE_BASE) { process.stderr.write("K_RELEASE_BASE not set\\n"); process.exit(2); }
+  const crypto = require("node:crypto");
+  const fs = require("node:fs");
+  const res = await fetch(RELEASE_BASE + "/manifest.json");
+  if (!res.ok) { process.stderr.write("manifest fetch failed: " + res.status + "\\n"); process.exit(3); }
+  const manifest = await res.json();
+  const targetKeys = Object.keys(manifest.targets);
+  const target = manifest.targets[targetKeys[0]];
+  if (!target) { process.stderr.write("manifest has no targets\\n"); process.exit(3); }
+  const art = await fetch(RELEASE_BASE + "/" + target.file);
+  if (!art.ok) { process.stderr.write("artifact fetch failed: " + art.status + "\\n"); process.exit(3); }
+  const bytes = Buffer.from(await art.arrayBuffer());
+  const hash = crypto.createHash("sha256").update(bytes).digest("hex");
+  if (hash !== target.sha256) { process.stderr.write("sha256 mismatch\\n"); process.exit(4); }
+  const selfPath = process.argv[1];
+  const tmp = selfPath + ".tmp";
+  fs.writeFileSync(tmp, bytes, { mode: 0o755 });
+  fs.renameSync(tmp, selfPath); // cli-profile L1': swap bytes, next run is new version
+  fs.writeSync(1, "upgraded to " + manifest.version + "\\n");
+  process.exit(0);
+}
+
+const args = process.argv.slice(2);
+if (args[0] === "self" && args[1] === "upgrade") {
+  selfUpgrade().catch((e) => { process.stderr.write(String(e) + "\\n"); process.exit(5); });
+} else if (args[0] === "--version") {
+  printVersion();
+} else {
+  switch (BEHAVIOR) {
+    case "crash-on-start": report(VERSION); process.exit(1); break;
+    case "wrong-version-probe": report("9.9.9"); process.exit(0); break;
+    case "hang-on-quiesce": report(VERSION); setInterval(() => {}, 2147483647); break;
+    case "ok":
+    default: report(VERSION); process.exit(0); break;
+  }
+}
+`;

package/harness/src/artifact-factory/factory.ts

@@ -0,0 +1,134 @@
+/**
+ * artifact-factory (harness-design §1.77) — build-once, stamp-many release
+ * production for upgrade tests.
+ *
+ * `makeRelease({version, behavior})` stamps the demo source into a REAL
+ * binary (version string injected into the artifact's own bytes — the same
+ * shape as SEA-embedded versions), then publishes it with manifest + full
+ * signature chain into a ReleaseStore (the fake-server's store).
+ *
+ * The `behavior` knob bakes deliberate breakage into "new versions":
+ * crash-on-start / wrong-version-probe / hang-on-quiesce are the fixture
+ * source for rollback teeth and self-verification known-red/adversarial
+ * samples ("升到坏版本→自动回滚→stable 完好" must be black-box reproducible).
+ *
+ * Content-addressed cache (key = source hash × version × behavior) makes
+ * repeated requests cheap and byte-identical across scenarios. Stamping is
+ * fully deterministic — Ed25519 signing is deterministic too, so the whole
+ * published release (artifact + manifest + signatures) is reproducible.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { DEMO_SOURCE } from "./demo.ts";
+import { sha256Hex } from "../fake-server/manifest.ts";
+import { ReleaseStore, type PublishReleaseSpec } from "../fake-server/store.ts";
+
+export const BEHAVIORS = [
+  "ok",
+  "crash-on-start",
+  "wrong-version-probe",
+  "hang-on-quiesce",
+] as const;
+
+export type Behavior = (typeof BEHAVIORS)[number];
+
+export interface MakeReleaseOptions {
+  version: string;
+  behavior: Behavior;
+  /** The release lands here (the fake-server's store). */
+  store: ReleaseStore;
+  /** Manifest platform tag. Default: "current". */
+  platform?: string;
+  /** Track the release is published under (latest | alpha). Optional. */
+}
+
+export interface FactoryRelease {
+  /** Artifact filename inside the release (served at /<file>). */
+  artifactFile: string;
+  artifactBytes: Uint8Array;
+  sha256: string;
+  /** True when the content-addressed cache served this request. */
+  cached: boolean;
+}
+
+interface CacheMeta {
+  version: string;
+  behavior: Behavior;
+  artifactFile: string;
+  sha256: string;
+}
+
+export class ArtifactFactory {
+  private readonly source: string;
+  private readonly sourceHash: string;
+  private readonly cacheDir: string;
+  private buildCount = 0;
+
+  constructor(opts: { demoSource?: string; cacheDir: string }) {
+    this.source = opts.demoSource ?? DEMO_SOURCE;
+    this.sourceHash = sha256Hex(new TextEncoder().encode(this.source));
+    this.cacheDir = opts.cacheDir;
+  }
+
+  /** Number of actual stamps performed (cache hits don't count). */
+  get builds(): number {
+    return this.buildCount;
+  }
+
+  async makeRelease(opts: MakeReleaseOptions): Promise<FactoryRelease> {
+    const key = `${this.sourceHash}:${opts.version}:${opts.behavior}`;
+    const keyHash = sha256Hex(new TextEncoder().encode(key));
+    const binPath = path.join(this.cacheDir, `${keyHash}.bin`);
+    const metaPath = path.join(this.cacheDir, `${keyHash}.json`);
+
+    let meta: CacheMeta;
+    let bytes: Uint8Array;
+    let cached = false;
+    const metaRaw = await fs.readFile(metaPath).catch(() => null);
+    if (metaRaw) {
+      meta = JSON.parse(new TextDecoder().decode(metaRaw)) as CacheMeta;
+      bytes = new Uint8Array(await fs.readFile(binPath));
+      cached = true;
+    } else {
+      await fs.mkdir(this.cacheDir, { recursive: true });
+      bytes = stamp(this.source, opts.version, opts.behavior);
+      meta = {
+        version: opts.version,
+        behavior: opts.behavior,
+        artifactFile: artifactFileName(opts.version),
+        sha256: sha256Hex(bytes),
+      };
+      await fs.writeFile(binPath, bytes, { mode: 0o755 });
+      await fs.writeFile(metaPath, JSON.stringify(meta));
+      this.buildCount += 1;
+    }
+
+    if (!opts.store.has(opts.version)) {
+      const spec: PublishReleaseSpec = {
+        version: opts.version,
+        artifacts: { [meta.artifactFile]: bytes },
+        binary: meta.artifactFile,
+        executable: true,
+      };
+      if (opts.platform !== undefined) spec.platform = opts.platform;
+      await opts.store.publish(spec);
+    }
+
+    return {
+      artifactFile: meta.artifactFile,
+      artifactBytes: bytes,
+      sha256: meta.sha256,
+      cached,
+    };
+  }
+}
+
+export function artifactFileName(version: string): string {
+  return `app-${version}.bin`;
+}
+
+/** Replace the stamp placeholders; the only byte-varying step, fully deterministic. */
+export function stamp(source: string, version: string, behavior: Behavior): Uint8Array {
+  const stamped = source.replaceAll("__K_VERSION__", version).replaceAll("__K_BEHAVIOR__", behavior);
+  return new TextEncoder().encode(stamped);
+}