@botiverse/k-carrier 0.1.0

package/harness/src/targetCheck.ts

@@ -0,0 +1,47 @@
+/**
+ * The missing-target fail-closed check (registered as
+ * blackbox.missing-target-fails): a binary with NO k.target.ts must be a
+ * typed BLACKBOX_TARGET_REQUIRED FAIL — the harness never guesses
+ * commands. `withTarget` simulates the must-red mutation (a target file
+ * exists, so the failure no longer happens) for known-red driving.
+ */
+import assert from "node:assert/strict";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { type ToothContext } from "./teeth/registry.ts";
+import { ArtifactFactory } from "./artifact-factory/factory.ts";
+import { FakeServer } from "./fake-server/server.ts";
+import { runBinMode } from "./blackbox.ts";
+import { TARGET_FILE } from "./target.ts";
+
+export async function checkMissingTargetFails(
+  ctx: ToothContext,
+  opts: { withTarget?: boolean } = {},
+): Promise<void> {
+  const factory = new ArtifactFactory({ cacheDir: path.join(ctx.sandboxDir, "cache") });
+  const server = new FakeServer({ storeDir: path.join(ctx.sandboxDir, "store") });
+  await server.start();
+  try {
+    const rel = await factory.makeRelease({ version: "1.0.0", behavior: "ok", store: server.store });
+    const appDir = path.join(ctx.sandboxDir, "app");
+    await fs.mkdir(appDir, { recursive: true });
+    const binPath = path.join(appDir, "mytool");
+    await fs.writeFile(binPath, rel.artifactBytes, { mode: 0o755 });
+    if (opts.withTarget) {
+      await fs.writeFile(
+        path.join(appDir, TARGET_FILE),
+        `export default { version: ["--version"], selfUpgrade: ["self", "upgrade"] };`,
+      );
+    }
+    const receipt = await runBinMode({ binPath, profile: "swap" });
+    const decl = receipt.checks.find((c) => c.id === "contract.target-declarations");
+    assert.ok(
+      decl?.status === "fail",
+      "a binary without k.target.ts must fail with an actionable typed error (no guessing)",
+    );
+    assert.equal(receipt.result, "fail");
+    assert.match(decl?.error ?? "", /BLACKBOX_TARGET_REQUIRED/);
+  } finally {
+    await server.stop();
+  }
+}

package/harness/src/teeth/artifact.ts

@@ -0,0 +1,215 @@
+/**
+ * M1 artifact teeth (test-plan M1 L0 rows; the package spec):
+ * tampered artifact => refuse install; kill mid-swap => old bytes intact;
+ * source refuses rather than guesses. Registration site only — check bodies
+ * live in harness/src/artifact/checks.ts.
+ */
+import { registerTooth } from "./registry.ts";
+import {
+  checkTamperedArtifactRefused,
+  checkKillMidSwapPreservesOld,
+  checkSourceFailsClosed,
+} from "../artifact/checks.ts";
+import {
+  checkSwapToolUpgradeLoop,
+  checkSwapToolRollback,
+} from "../artifact/m1.ts";
+import {
+  checkM3ServiceUpgrade,
+  checkM3ServiceRollback,
+  checkM3StuckDriverEvidence,
+} from "../artifact/m3.ts";
+import { checkDownloadResumesAfterKill } from "../artifact/m1Resume.ts";
+import {
+  checkM4ConfirmNoConsentZeroSideEffects,
+  checkM4ConsentBindsVersion,
+  checkM4NotifyOnlyReportsInstallableVersion,
+} from "../artifact/m4.ts";
+
+registerTooth({
+  id: "artifact.tamper-refuses-install",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "downloadVerified skips the sha256 verification",
+      caughtOnlyBy: {
+        alsoCaughtBy: "core/src/artifact download unit tests (SHA256_MISMATCH)",
+        whyStillNeeded:
+          "the tooth runs the full black-box plane — fake-server tamper API + factory artifact + real HTTP — which the unit test does not",
+      },
+    },
+  ],
+  run: checkTamperedArtifactRefused,
+});
+
+registerTooth({
+  id: "artifact.atomic-swap-crash-safe",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "atomicWriteFile writes the target in place (no tmp+rename; half-writes visible)",
+      caughtOnlyBy: "this", // only this tooth kills a real process mid-swap
+    },
+  ],
+  run: checkKillMidSwapPreservesOld,
+});
+
+registerTooth({
+  id: "artifact.source-fails-closed",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the release source guesses a target instead of refusing (unknown platform / unservable version)",
+      caughtOnlyBy: {
+        alsoCaughtBy: "core/src/artifact source unit tests",
+        whyStillNeeded:
+          "the tooth pins refusal at the real source boundary (platform + named-version), not just one helper",
+      },
+    },
+  ],
+  run: checkSourceFailsClosed,
+});
+
+registerTooth({
+  id: "m1.swap-tool-upgrade",
+  profiles: ["swap"],
+  layers: ["L0", "L1p"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the upgrade never reaches the stable slot (next run still reports the old version)",
+      caughtOnlyBy: "this", // only this tooth runs the full black-box upgrade through the demo
+    },
+  ],
+  run: checkSwapToolUpgradeLoop,
+});
+
+registerTooth({
+  id: "m1.swap-tool-rollback",
+  profiles: ["swap"],
+  layers: ["L0", "L1p"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "a failing experiment is promoted instead of rolled back",
+      caughtOnlyBy: {
+        alsoCaughtBy: "core txn engine unit tests (rollback symmetry)",
+        whyStillNeeded:
+          "the engine tests use in-memory effects; this tooth drives the real binary + real slots through the demo's own upgrade command",
+      },
+    },
+  ],
+  run: checkSwapToolRollback,
+});
+
+
+
+
+
+registerTooth({
+  id: "m3.service-upgrade",
+  profiles: ["service"],
+  layers: ["L0", "L1", "L2", "L3"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the new service is the SAME process as the old (no fresh incarnation; startId reused)",
+      caughtOnlyBy: "this", // only this tooth checks the running process's fresh startId end to end
+    },
+    {
+      mutate: "stop(slot) sends SIGKILL but never verifies the process is gone",
+      caughtOnlyBy: "this", // signal-sent != dead; only this tooth asserts the old pid is OS-gone
+    },
+  ],
+  run: checkM3ServiceUpgrade,
+});
+
+registerTooth({
+  id: "m3.service-rollback",
+  profiles: ["service"],
+  layers: ["L0", "L1", "L2", "L3"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "rollback reverts the slots but does not pull the old version back up",
+      caughtOnlyBy: "this", // only this tooth asserts the old version is ACTUALLY running after rollback
+    },
+  ],
+  run: checkM3ServiceRollback,
+});
+
+registerTooth({
+  id: "m3.stuck-driver-evidence-recovery",
+  profiles: ["service"],
+  layers: ["L0", "L1", "L2", "L3"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the successor decides the handover by a flag, not by evidence (or never recovers at all)",
+      caughtOnlyBy: "this", // only this tooth wedges the driver and demands evidence-based recovery
+    },
+  ],
+  run: checkM3StuckDriverEvidence,
+});
+
+registerTooth({
+  id: "m1.download-resumes-after-kill",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "an interrupted download restarts from zero (no partial, no Range resume)",
+      caughtOnlyBy: "this", // only this tooth kills a real downloader and demands a Range resume
+    },
+  ],
+  run: checkDownloadResumesAfterKill,
+});
+
+registerTooth({
+  id: "m4.confirm-no-consent-zero-side-effects",
+  profiles: ["service"],
+  layers: ["L0", "L1", "L4"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the confirm gate moves after staging (unapproved bytes reach the disk)",
+      caughtOnlyBy: "this", // only this tooth asserts the stateDir is untouched under unapproved confirm
+    },
+  ],
+  run: checkM4ConfirmNoConsentZeroSideEffects,
+});
+
+registerTooth({
+  id: "m4.consent-binds-version",
+  profiles: ["service"],
+  layers: ["L0", "L1", "L4"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the continuation installs whatever the server serves now, not the approved version",
+      caughtOnlyBy: "this", // only this tooth binds consent to the specific offered version
+    },
+  ],
+  run: checkM4ConsentBindsVersion,
+});
+
+registerTooth({
+  id: "m4.notify-only-reports-installable-version",
+  profiles: ["service"],
+  layers: ["L0", "L1", "L4"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the notification names a version that is not the installable one",
+      caughtOnlyBy: "this", // only this tooth pins the notification to the actual pick
+    },
+  ],
+  run: checkM4NotifyOnlyReportsInstallableVersion,
+});

package/harness/src/teeth/artifactDownload.ts

@@ -0,0 +1,136 @@
+/**
+ * M1 download-hole teeth (the 8 L0 fixes, one tooth per hole:
+ * deadline raced not signalled, Rosetta arch lie, progress without
+ * resumeDir, empty body named, stall bounds silence, error classification,
+ * stall phase honesty). Registration site only — check bodies live in
+ * harness/src/artifact/downloadHoles.ts.
+ */
+import { registerTooth } from "./registry.ts";
+import {
+  checkDownloadTimeoutEnforced,
+  checkPlatformKeyNativeArch,
+  checkDownloadProgressWithoutResumeDir,
+  checkDownloadEmptyBodyNamed,
+  checkDownloadStallBoundsSilence,
+  checkDownloadErrorsClassified,
+  checkDownloadStallPhaseHonest,
+} from "../artifact/downloadHoles.ts";
+
+registerTooth({
+  id: "m1.download-timeout-enforced",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "the deadline is only signalled, never raced — a fetch that ignores AbortSignal outlives every timeout (all timeouts silently inert)",
+      caughtOnlyBy: "this", // fetchImpl is an adopter-supplied seam; its regression looks exactly like a working download
+    },
+  ],
+  run: checkDownloadTimeoutEnforced,
+});
+
+registerTooth({
+  id: "m1.platform-key-native-arch",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "the platform key trusts process.arch — under Rosetta the machine is pinned to the x64 build forever, with nothing looking wrong",
+      caughtOnlyBy: "this", // the wrong package is still a fully legal package: no error, just the wrong hardware served
+    },
+    {
+      mutate:
+        "the hardware probe is consulted outside darwin+x64 (shelling out on every platform lookup)",
+      caughtOnlyBy: "this",
+    },
+  ],
+  run: checkPlatformKeyNativeArch,
+});
+
+registerTooth({
+  id: "m1.download-progress-without-resumedir",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "byte progress never fires without a resumeDir (a configured-looking sink that never moves)",
+      caughtOnlyBy: "this", // "slow" vs "hung" must stay distinguishable even with no partial to resume
+    },
+  ],
+  run: checkDownloadProgressWithoutResumeDir,
+});
+
+registerTooth({
+  id: "m1.download-empty-body-named",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "a no-body response returns zero bytes — the only symptom is a sha256 mismatch against the empty string, hiding the cause",
+      caughtOnlyBy: "this", // the failure path must not produce the empty success value
+    },
+    {
+      mutate:
+        "the RESUME path treats a no-body response as an empty prefix to continue from (the cause hides behind a sha256 mismatch there too)",
+      caughtOnlyBy: "this", // discovered while writing these teeth: the twin path had no pre-existing mutation to copy
+    },
+  ],
+  run: checkDownloadEmptyBodyNamed,
+});
+
+registerTooth({
+  id: "m1.download-stall-bounds-silence",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "the stall budget is a total timeout — a slow-but-progressing download is killed (silence and duration conflated)",
+      caughtOnlyBy: "this", // bounding SILENCE follows liveness; a total budget encodes a guess about size/bandwidth
+    },
+    {
+      mutate: "there is no stall budget at all — a wedged connection holds until the total timeout and never names the stall",
+      caughtOnlyBy: "this",
+    },
+  ],
+  run: checkDownloadStallBoundsSilence,
+});
+
+registerTooth({
+  id: "m1.download-errors-classified",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "an in-memory download error is reported bare — an abort we caused ourselves is indistinguishable from the network breaking",
+      caughtOnlyBy: "this", // "we gave up on purpose" must be tellable from "the network died"
+    },
+  ],
+  run: checkDownloadErrorsClassified,
+});
+
+registerTooth({
+  id: "m1.download-stall-phase-honest",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate:
+        "a stall that happened mid-body is reported as 'awaiting response' — the reader looks at the wrong end of the transfer",
+      caughtOnlyBy: "this",
+    },
+  ],
+  run: checkDownloadStallPhaseHonest,
+});

package/harness/src/teeth/artifactFactory.ts

@@ -0,0 +1,41 @@
+/**
+ * artifact-factory teeth (harness-design §1.77; the package spec:
+ * determinism + the ok artifact really runs and reports its version).
+ *
+ * Registration site only — check bodies live in
+ * artifact-factory/checks.ts; importing this module registers the teeth.
+ */
+import { registerTooth } from "./registry.ts";
+import { checkDeterministicBuild, checkOkArtifactRuns } from "../artifact-factory/checks.ts";
+
+registerTooth({
+  id: "artifact-factory.deterministic-build",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "stamp embeds a time-varying byte (e.g. a build timestamp)",
+      caughtOnlyBy: "this", // only this tooth compares two fresh builds byte-for-byte
+    },
+  ],
+  run: checkDeterministicBuild,
+});
+
+registerTooth({
+  id: "artifact-factory.ok-artifact-runs",
+  profiles: ["swap", "service"],
+  layers: ["L0"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "stamp embeds the wrong version string",
+      caughtOnlyBy: "this", // determinism tooth still passes (wrong is consistent); only a real run exposes it
+    },
+    {
+      mutate: "the ok artifact exits non-zero on start",
+      caughtOnlyBy: "this", // only this tooth executes the built binary
+    },
+  ],
+  run: checkOkArtifactRuns,
+});

package/harness/src/teeth/artifactM5.ts

@@ -0,0 +1,68 @@
+/**
+ * M5 platform-surface / lifecycle-convergence teeth (test-plan M5 rows).
+ * Registration site only — check bodies live in harness/src/artifact/m5.ts.
+ */
+import { registerTooth } from "./registry.ts";
+import {
+  checkM5LifecycleSurfaceAllowlist,
+  checkM5LifecycleConvergedPromotes,
+  checkM5LifecycleProjectionBan,
+  checkM5LifecycleFailClosedRetirement,
+} from "../artifact/m5.ts";
+
+registerTooth({
+  id: "m5.lifecycle-surface-allowlist",
+  profiles: ["service"],
+  layers: ["L3"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "an unregistered (or unreadable) surface vouches for convergence",
+      caughtOnlyBy: "this", // only this tooth pins the allowlist trust boundary
+    },
+  ],
+  run: checkM5LifecycleSurfaceAllowlist,
+});
+
+registerTooth({
+  id: "m5.lifecycle-converged-promotes",
+  profiles: ["service"],
+  layers: ["L3"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "a stale surface read-back still allows the promote",
+      caughtOnlyBy: "this", // only this tooth pins convergence before promote
+    },
+  ],
+  run: checkM5LifecycleConvergedPromotes,
+});
+
+registerTooth({
+  id: "m5.lifecycle-projection-ban",
+  profiles: ["service"],
+  layers: ["L3"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "a version/metadata string satisfies host_lifecycle_converged",
+      caughtOnlyBy: "this", // only this tooth pins the projection ban
+    },
+  ],
+  run: checkM5LifecycleProjectionBan,
+});
+
+registerTooth({
+  id: "m5.lifecycle-fail-closed-retirement",
+  profiles: ["service"],
+  layers: ["L3"],
+  kind: { kind: "invariant" },
+  mustRed: [
+    {
+      mutate: "the legacy lifecycle manager is retired before convergence passed",
+      caughtOnlyBy: "this", // only this tooth pins the retirement order
+    },
+  ],
+  run: checkM5LifecycleFailClosedRetirement,
+});
+