@botiverse/k-carrier 0.1.0

package/harness/src/teeth/artifactM6.ts

@@ -0,0 +1,264 @@
+/**
+ * M6 provenance teeth (test-plan M6 rows: provenance journal forward-only;
+ * a genesis machine is NOT_OBSERVED and never counted as "recorded"; an
+ * unreadable/corrupt journal is a THIRD state, never genesis; every
+ * reconcile that reaches the transaction records WHO drove it, write-ahead).
+ * Registration site only — check bodies live in harness/src/artifact/m6.ts.
+ */
+import { registerTooth } from "./registry.ts";
+import {
+  checkM6ProvenanceForwardOnly,
+  checkM6ProvenanceGenesisNotObserved,
+  checkM6ProvenanceRecordsEachReconcile,
+} from "../artifact/m6.ts";
+import {
+  checkM6StatusReportMatchesLocal,
+  checkM6StatusReportSilenceNotEvidence,
+} from "../artifact/m6Status.ts";
+import {
+  checkM6DriveStageThroughPolicy,
+  checkM6DrivePromoteThroughPolicy,
+  checkM6DriveRollbackThroughOwnership,
+  checkM6RollbackSettlesInflightOwnershipFlip,
+  checkM6PushRollbackThroughPolicy,
+  checkM6AutoRollbackNeedsNoConsent,
+} from "../artifact/m6Drive.ts";
+
+registerTooth({
+  id: "m6.provenance-forward-only",
+  profiles: ["service"],
+  layers: ["L5"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "an overwrite of an existing entry is accepted (provenance becomes rewritable)",
+      caughtOnlyBy: "this", // nobody else pins the forward-only journal
+    },
+    {
+      mutate: "a torn final line is kept (history includes an entry that never completed)",
+      caughtOnlyBy: "this",
+    },
+    {
+      mutate: "appends are not unique/ordered (history can be collapsed or reordered)",
+      caughtOnlyBy: "this",
+    },
+    {
+      mutate:
+        "appending on an unreadable/corrupt history is allowed (a truncated view re-issues a seq)",
+      caughtOnlyBy: "this", // the rewrite-under-a-truncated-view attack
+    },
+  ],
+  run: checkM6ProvenanceForwardOnly,
+});
+
+registerTooth({
+  id: "m6.provenance-genesis-not-observed",
+  profiles: ["service"],
+  layers: ["L5"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "genesis machines are counted as recorded (recorded ∪ not-observed collapses into one bucket)",
+      caughtOnlyBy: "this", // "no data" ≠ "no problem": the M6 genesis guard
+    },
+    {
+      mutate:
+        "an empty-but-present journal is reported as genesis (machinery present, misreported as never-had-it)",
+      caughtOnlyBy: "this",
+    },
+    {
+      mutate:
+        "an unreadable journal is reported as genesis (\"I cannot see the data\" becomes \"there is no data\")",
+      caughtOnlyBy: "this", // only this tooth pins the third state
+    },
+    {
+      mutate:
+        "aggregation folds unreadable into notObserved (the 'definitely absent' bucket)",
+      caughtOnlyBy: "this",
+    },
+  ],
+  run: checkM6ProvenanceGenesisNotObserved,
+});
+
+registerTooth({
+  id: "m6.status-report-matches-local",
+  profiles: ["service"],
+  layers: ["L5"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the report invents/fabricates a field (stable says X while the machine is on Y)",
+      caughtOnlyBy: "this", // only this tooth pins the read-back equality
+    },
+    {
+      mutate: "the report's predicates are not the last real evaluation's (a report from a different machine/moment)",
+      caughtOnlyBy: "this",
+    },
+    {
+      mutate:
+        "a real conclusion is attached to the wrong version (no stamp / wrong stamp — consumers cannot join correctly)",
+      caughtOnlyBy: "this", // a true fact pasted on the wrong version reads like a lie
+    },
+  ],
+  run: checkM6StatusReportMatchesLocal,
+});
+
+registerTooth({
+  id: "m6.status-report-silence-not-evidence",
+  profiles: ["service"],
+  layers: ["L5"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "a machine that never observed a promote reports binaryAtTarget: passed:true",
+      caughtOnlyBy: "this", // silence cannot be spent as evidence (M5 rule, fleet surface)
+    },
+    {
+      mutate:
+        "a machine that never observed a promote reports hostLifecycleConverged: passed:true",
+      caughtOnlyBy: "this",
+    },
+    {
+      mutate:
+        "a rolled-back reconcile is reported as an observed pass (failure converted into evidence)",
+      caughtOnlyBy: "this",
+    },
+    {
+      mutate:
+        "a machine that DID converge reports NOT_OBSERVED after a restart (the report is not persisted)",
+      caughtOnlyBy: "this", // "observed, I restarted" is not "never observed"
+    },
+    {
+      mutate:
+        "an unreadable report is read as genesis (\"I cannot see the data\" becomes \"there is no data\" — the report store collapses to two states)",
+      caughtOnlyBy: "this", // same family as the provenance third state, one package
+    },
+  ],
+  run: checkM6StatusReportSilenceNotEvidence,
+});
+
+registerTooth({
+  id: "m6.provenance-records-each-reconcile",
+  profiles: ["service"],
+  layers: ["L5"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "a successful reconcile leaves no provenance entry (the 'who' is lost)",
+      caughtOnlyBy: "this", // only this tooth pins who-drove-it on every reconcile
+    },
+    {
+      mutate:
+        "a failed reconcile (auto-rollback) is not recorded (journaling after the outcome, not write-ahead)",
+      caughtOnlyBy: "this",
+    },
+  ],
+  run: checkM6ProvenanceRecordsEachReconcile,
+});
+
+registerTooth({
+  id: "m6.drive-stage-through-policy",
+  profiles: ["service"],
+  layers: ["L5", "L4"],
+  requiresCapability: "fleet-drive",
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the drive path stages bytes without consent (policy=confirm is not honored)",
+      caughtOnlyBy: "this", // only this tooth pins drive stage through the policy gate
+    },
+    {
+      mutate: "a held drive stage leaves a provenance entry (it never reached the transaction)",
+      caughtOnlyBy: "this", // "reaches the transaction" is the provenance threshold
+    },
+  ],
+  run: checkM6DriveStageThroughPolicy,
+});
+
+registerTooth({
+  id: "m6.drive-promote-through-policy",
+  profiles: ["service"],
+  layers: ["L5", "L4"],
+  requiresCapability: "fleet-drive",
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the drive path promotes without consent",
+      caughtOnlyBy: "this",
+    },
+    {
+      mutate: "the drive installs a different version than the one approved (consent does not bind)",
+      caughtOnlyBy: "this", // consent is to a VERSION, never to "the upgrade"
+    },
+  ],
+  run: checkM6DrivePromoteThroughPolicy,
+});
+
+registerTooth({
+  id: "m6.drive-rollback-through-ownership",
+  profiles: ["service"],
+  layers: ["L5", "L1"],
+  requiresCapability: "fleet-drive",
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "a drive rollback on a managed-elsewhere machine at rest rolls back (someone else's copy modified)",
+      caughtOnlyBy: "this", // only this tooth pins the at-rest ownership gate
+    },
+    {
+      mutate:
+        "a TERMINAL rolled-back state is classified as in-flight (an exclusion-list at-rest check would touch a machine that is not ours)",
+      caughtOnlyBy: "this", // the gate enumerates positively: the next terminal phase cannot silently become "in flight"
+    },
+  ],
+  run: checkM6DriveRollbackThroughOwnership,
+});
+
+registerTooth({
+  id: "m6.rollback-settles-inflight-ownership-flip",
+  profiles: ["service"],
+  layers: ["L1"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "a machine with an in-flight transaction is held from settling when ownership flipped (bricked mid-transaction)",
+      caughtOnlyBy: "this", // the reverse: a held on an opened transaction is a brick
+    },
+  ],
+  run: checkM6RollbackSettlesInflightOwnershipFlip,
+});
+
+registerTooth({
+  id: "m6.push-rollback-through-policy",
+  profiles: ["service"],
+  layers: ["L5", "L4"],
+  requiresCapability: "fleet-drive",
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "a pushed rollback of an ALREADY-PROMOTED version executes without consent (the downgrade attack by another name)",
+      caughtOnlyBy: "this", // safe direction is byte safety, not authority (the ruling)
+    },
+  ],
+  run: checkM6PushRollbackThroughPolicy,
+});
+
+registerTooth({
+  id: "m6.auto-rollback-needs-no-consent",
+  profiles: ["service"],
+  layers: ["L5", "L4"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "the in-transaction auto-rollback waits for consent that never comes (the promise 'you'll always get back' is false)",
+      caughtOnlyBy: "this", // the controlling twin of push-rollback-through-policy
+    },
+  ],
+  run: checkM6AutoRollbackNeedsNoConsent,
+});

package/harness/src/teeth/blackbox.ts

@@ -0,0 +1,22 @@
+/**
+ * Black-box contract teeth — registration site for the --bin mode's
+ * fail-closed discipline (harness-design §1.76, ruling: no
+ * zero-config defaults, no convention probing — the target MUST be
+ * declared). Check bodies live in blackbox.ts.
+ */
+import { registerTooth } from "./registry.ts";
+import { checkMissingTargetFails } from "../targetCheck.ts";
+
+registerTooth({
+  id: "blackbox.missing-target-fails",
+  profiles: ["swap", "service"],
+  layers: ["L0", "L1p"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the harness guesses commands (probes --version / self upgrade) when no target file exists",
+      caughtOnlyBy: "this", // only this tooth pins that a missing target is a typed FAIL, never a guess
+    },
+  ],
+  run: checkMissingTargetFails,
+});

package/harness/src/teeth/checks.ts

@@ -0,0 +1,278 @@
+/**
+ * M0 acceptance checks — the run bodies of the fake-server + sandbox teeth
+ * (registered in m0.ts).
+ *
+ * Each check throws on violation (a tooth goes red by throwing). The checks
+ * are exported separately so the self-verification tests can drive
+ * known-red by running a check against a mutated world (a no-op tamper, a
+ * shared dir) — the tooth must throw then, exactly like the mutation-runner
+ * will demand.
+ *
+ * The oracle is sha256: K verifies integrity, not authenticity (design-v1
+ * §L0.5), so every tamper op here is judged by "do the served bytes still
+ * hash to what the manifest promises". Signature-chain checks lived here
+ * until 2026-08-06 and were removed with the feature -- a tooth for a
+ * guarantee the product does not make is worse than no tooth.
+ */
+import assert from "node:assert/strict";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { type ToothContext } from "./registry.ts";
+import { FakeServer, type PublishedRelease } from "../fake-server/server.ts";
+import {
+  MANIFEST_FILE,
+  compareVersions,
+  sha256Hex,
+  type Manifest,
+} from "../fake-server/manifest.ts";
+import { createSandbox } from "../scenario/sandbox.ts";
+
+export const M0_ARTIFACT = "app-1.0.0.bin";
+export const M0_ARTIFACT_B = "app-1.0.0-extra.bin";
+const PAYLOAD = "K fake-server payload";
+const PAYLOAD_V2 = "K fake-server payload v2";
+
+export interface ReleaseFixture {
+  server: FakeServer;
+  artifact: string;
+  artifactBytes: Uint8Array;
+  manifest: Manifest;
+}
+
+/** Start a fake-server with one published release inside the tooth sandbox. */
+export async function setupRelease(
+  ctx: ToothContext,
+  opts: {
+    artifacts?: Record<string, string>;
+    version?: string;
+    platform?: string;
+    binary?: string;
+  } = {},
+): Promise<ReleaseFixture> {
+  const server = new FakeServer({ storeDir: path.join(ctx.sandboxDir, "store") });
+  await server.start();
+  const artifacts = opts.artifacts ?? { [M0_ARTIFACT]: PAYLOAD };
+  const names = Object.keys(artifacts);
+  const artifact = opts.binary ?? (names.length === 1 ? names[0] : undefined);
+  if (!artifact) throw new Error("setupRelease: no artifact selected");
+  const content = artifacts[artifact];
+  if (content === undefined) throw new Error(`setupRelease: artifact ${artifact} has no content`);
+  const released: PublishedRelease = await server.publishRelease({
+    version: opts.version ?? "1.0.0",
+    artifacts,
+    platform: opts.platform ?? "darwin-arm64",
+    binary: artifact,
+  });
+  return {
+    server,
+    artifact,
+    artifactBytes: new TextEncoder().encode(content),
+    manifest: released.manifest,
+  };
+}
+
+export async function fetchBytes(
+  server: FakeServer,
+  file: string,
+): Promise<{ status: number; body: Uint8Array }> {
+  const res = await fetch(`${server.url}/${file}`);
+  return { status: res.status, body: new Uint8Array(await res.arrayBuffer()) };
+}
+
+/**
+ * Does the file the server currently serves still hash to `expected`?
+ *
+ * Fetch failures return false rather than throwing: for these checks a file
+ * that cannot be fetched is as much a mismatch as wrong bytes, and both are
+ * reported by the caller's own assertion message.
+ */
+export async function servedHashMatches(
+  server: FakeServer,
+  file: string,
+  expected: string,
+): Promise<boolean> {
+  const res = await fetchBytes(server, file);
+  if (res.status !== 200) return false;
+  return sha256Hex(res.body) === expected;
+}
+
+// ---------------------------------------------------------------------------
+// Checks (exported for known-red driving). Each throws on violation.
+// ---------------------------------------------------------------------------
+
+export async function checkServesConsistentRelease(
+  ctx: ToothContext,
+  mutate?: (server: FakeServer, fx: ReleaseFixture) => Promise<void>,
+): Promise<void> {
+  const fx = await setupRelease(ctx);
+  try {
+    if (mutate) await mutate(fx.server, fx);
+    const m = await fetchBytes(fx.server, MANIFEST_FILE);
+    assert.equal(m.status, 200, "manifest must be served");
+    const manifest = JSON.parse(new TextDecoder().decode(m.body)) as Manifest;
+    assert.equal(manifest.version, "1.0.0");
+    const target = manifest.targets["darwin-arm64"];
+    assert.ok(target, "manifest must carry the published platform target");
+    assert.equal(target.file, fx.artifact);
+    assert.equal(target.sha256, sha256Hex(fx.artifactBytes));
+    assert.equal(target.size, fx.artifactBytes.length);
+
+    const art = await fetchBytes(fx.server, fx.artifact);
+    assert.equal(art.status, 200, "artifact must be served");
+    // sha256, not deepEqual: a byte-equality assertion here would fire FIRST
+    // and report "bytes differ" for a corruption whose tested property is
+    // manifest/bytes disagreement -- an unrelated earlier reason masking the
+    // one under test.
+    assert.equal(sha256Hex(art.body), target.sha256, "served bytes must match manifest sha256");
+
+  } finally {
+    await fx.server.stop();
+  }
+}
+
+export async function checkCorruptByteRejects(
+  ctx: ToothContext,
+  mutate?: (server: FakeServer) => Promise<void>,
+): Promise<void> {
+  const fx = await setupRelease(ctx);
+  try {
+    if (mutate) await mutate(fx.server);
+    else await fx.server.corruptByte(fx.artifact, 0);
+    const published = sha256Hex(fx.artifactBytes);
+    assert.equal(
+      await servedHashMatches(fx.server, fx.artifact, published),
+      false,
+      "corrupted artifact must no longer hash to the published digest",
+    );
+    // isolation: untouched files must still be intact
+    const m = await fetchBytes(fx.server, MANIFEST_FILE);
+    assert.equal(m.status, 200, "untampered manifest must still be served");
+    const manifest = JSON.parse(new TextDecoder().decode(m.body)) as Manifest;
+    assert.equal(
+      manifest.targets["darwin-arm64"]?.sha256,
+      published,
+      "tampering the artifact must not have rewritten the manifest",
+    );
+  } finally {
+    await fx.server.stop();
+  }
+}
+
+export async function checkSwapArtifactsRejects(
+  ctx: ToothContext,
+  mutate?: (server: FakeServer) => Promise<void>,
+): Promise<void> {
+  const bytesB = "K fake-server payload B";
+  const fx = await setupRelease(ctx, {
+    artifacts: { [M0_ARTIFACT]: PAYLOAD, [M0_ARTIFACT_B]: bytesB },
+    binary: M0_ARTIFACT,
+  });
+  const expected = new Map([
+    [M0_ARTIFACT, sha256Hex(fx.artifactBytes)],
+    [M0_ARTIFACT_B, sha256Hex(new TextEncoder().encode(bytesB))],
+  ]);
+  try {
+    if (mutate) await mutate(fx.server);
+    else await fx.server.swapFiles(M0_ARTIFACT, M0_ARTIFACT_B);
+    // Both names must be wrong, not just one: a swap that moved a single file
+    // would leave the other intact, and a check that only looked at the binary
+    // would call that a detected swap.
+    for (const [name, digest] of expected) {
+      assert.equal(
+        await servedHashMatches(fx.server, name, digest),
+        false,
+        `swapped artifact ${name} must no longer hash to its published digest`,
+      );
+    }
+  } finally {
+    await fx.server.stop();
+  }
+}
+
+export async function checkServeOlderVersion(
+  ctx: ToothContext,
+  mutate?: (server: FakeServer) => Promise<string>,
+): Promise<void> {
+  const server = new FakeServer({ storeDir: path.join(ctx.sandboxDir, "store") });
+  await server.start();
+  try {
+    await server.publishRelease({
+      version: "1.0.0",
+      artifacts: { "app-1.0.0.bin": PAYLOAD },
+      platform: "darwin-arm64",
+    });
+    await server.publishRelease({
+      version: "2.0.0",
+      artifacts: { "app-2.0.0.bin": PAYLOAD_V2 },
+      platform: "darwin-arm64",
+    });
+    const older = mutate ? await mutate(server) : await server.serveOlderVersion();
+    assert.equal(older, "1.0.0", "serveOlderVersion must switch to the older release");
+    const m = await fetchBytes(server, MANIFEST_FILE);
+    const manifest = JSON.parse(new TextDecoder().decode(m.body)) as Manifest;
+    assert.equal(
+      compareVersions(manifest.version, "2.0.0"),
+      -1,
+      "served manifest version must be strictly older than the previously active one",
+    );
+    const oldArt = await fetchBytes(server, "app-1.0.0.bin");
+    assert.equal(oldArt.status, 200, "older release's artifacts must be served");
+  } finally {
+    await server.stop();
+  }
+}
+
+export async function checkDropFileRemoves(
+  ctx: ToothContext,
+  mutate?: (server: FakeServer) => Promise<void>,
+): Promise<void> {
+  const fx = await setupRelease(ctx);
+  try {
+    if (mutate) await mutate(fx.server);
+    else await fx.server.dropFile(fx.artifact);
+    const art = await fetchBytes(fx.server, fx.artifact);
+    assert.equal(art.status, 404, "dropped file must no longer be served");
+    const m = await fetchBytes(fx.server, MANIFEST_FILE);
+    assert.equal(m.status, 200, "remaining files must still be served");
+  } finally {
+    await fx.server.stop();
+  }
+}
+
+/** The distinctness assertions of the sandbox tooth, standalone for known-red. */
+export function assertSandboxDistinct(
+  a: { dir: string; port: number },
+  b: { dir: string; port: number },
+): void {
+  assert.notEqual(a.dir, b.dir, "two live sandboxes must have distinct dirs");
+  assert.notEqual(a.port, b.port, "two live sandboxes must have distinct ports");
+}
+
+export async function assertDirGone(dir: string): Promise<void> {
+  await assert.rejects(fs.access(dir), "teardown must remove the sandbox dir");
+}
+
+export async function checkSandboxIsolation(ctx: ToothContext): Promise<void> {
+  const a = await createSandbox({ prefix: "iso-a", baseDir: ctx.sandboxDir });
+  const b = await createSandbox({ prefix: "iso-b", baseDir: ctx.sandboxDir });
+  try {
+    assertSandboxDistinct(a, b);
+    await assertDirGone(path.join(a.dir, "does-not-exist")); // sanity: helper works
+  } finally {
+    await a.teardown();
+    await b.teardown();
+  }
+  await assertDirGone(a.dir);
+  await assertDirGone(b.dir);
+}
+
+/**
+ * Sandbox verify-dead check lives with the sandbox module (its domain):
+ * re-exported here so the M0 teeth and tests import from one place.
+ */
+export { checkSandboxVerifyDead } from "../scenario/sandbox.ts";
+
+// ---------------------------------------------------------------------------
+// Registered teeth (must-red answered per "who else would catch this?").
+// ---------------------------------------------------------------------------
+

package/harness/src/teeth/examples.ts

@@ -0,0 +1,57 @@
+/**
+ * Examples teeth — each demo is the credential for its profile's support
+ * claim (examples/README.md). Registration site only; check bodies live in
+ * harness/src/examples/checks.ts.
+ */
+import { registerTooth } from "./registry.ts";
+import {
+  checkCliToolBlackbox,
+  checkPlainDaemonContract,
+  checkManagedHostAdapter,
+} from "../examples/checks.ts";
+
+registerTooth({
+  id: "examples.swap-tool-blackbox",
+  profiles: ["swap"],
+  layers: ["L0", "L1p"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "self upgrade swaps no bytes (serves the current version's artifact)",
+      caughtOnlyBy: {
+        alsoCaughtBy: "k-harness --bin contract.self-upgrade (CONTRACT_UPGRADE_SELF_UNCHANGED)",
+        whyStillNeeded:
+          "this tooth makes the swap-tool demo's claim a CI-enforced registered tooth in the cli tier, not just an ad-hoc CLI invocation",
+      },
+    },
+  ],
+  run: checkCliToolBlackbox,
+});
+
+registerTooth({
+  id: "examples.service-daemon-contract",
+  profiles: ["service"],
+  layers: ["L0", "L2", "L3"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the daemon crashes on start (or never answers the probe)",
+      caughtOnlyBy: "this", // only this tooth exercises the daemon demo in process reality
+    },
+  ],
+  run: checkPlainDaemonContract,
+});
+
+registerTooth({
+  id: "examples.hosted-service-adapter",
+  profiles: ["service"],
+  layers: ["L2", "L3"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the managed host loses the session ledger on resume",
+      caughtOnlyBy: "this", // only this tooth pins the managed demo's session preservation
+    },
+  ],
+  run: checkManagedHostAdapter,
+});