muse-crew 0.13.3 → 0.14.1

package/lib/classify-publish-absence.js

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+// classify-publish-absence.js — deterministic classifier for publish attempts
+// parked with an UNKNOWN outcome (blocker 15, Phase 1, 2026-09-18).
+//
+// The workflow's fire-and-forget trigger returns no receipt, so a parked
+// unknown means "the edit may or may not have gone through and the build
+// may or may not have run." This unit decides mechanically from durable
+// signals only — never from timing windows or audit-dir counting:
+//
+//   sensor findings (lib/readback-disk.js — the on-disk source read-back)
+//   × manifest (.space-build/manifest.json — built_at + content_sha256)
+//   × repo state (git diff base..commit, HEAD)
+//
+// Decisions (design-room19.md §1.4):
+//   verified            — manifest built_at advanced past the trigger AND
+//                         every discriminating added line PRESENT / removed
+//                         ABSENT (the build landed; route to parent
+//                         verification, which stamps).
+//   provably-dropped    — (a) every discriminating added line ABSENT,
+//                         (b) every discriminating removed line PRESENT,
+//                         (c) manifest built_at NOT advanced past trigger,
+//                         (d) no build in flight (checked twice, bracketing
+//                         the content read), (e) decision time ≥ park +
+//                         quiesce, (f) HEAD == commit. One safe retry.
+//   applied-not-built   — source PRESENT but manifest stale: the platform
+//                         started something but no build completed.
+//                         → ambiguous, park with the diagnosis, NO retry
+//                         (re-applying a possibly mid-apply diff is the
+//                         2026-09-12 hazard in a new coat).
+//   ambiguous           — partial-apply, binary/mode-only/rename diffs,
+//                         unreadable sensor, manifest-advanced-but-mismatched,
+//                         zero discriminating lines. Terminal, no retry.
+//   deferred            — trigger age < quiesce, or build in flight. No
+//                         budget consumed. Still in flight at park+2h → the
+//                         caller treats it as terminal (pathological).
+//   superseded          — HEAD != commit. Terminal, no retry (a retry would
+//                         regress a newer publish).
+//
+// "Discriminating" reuses lib/publish-content.js — the verifier's own
+// collision-exemption logic. Lines already in the old tree are
+// non-discriminating and ignored.
+//
+// Usage:
+//   node classify-publish-absence.js --repo-path <path> --commit <sha>
+//       --base <sha> --slug <slug> --trigger-ts <ISO> --park-ts <ISO>
+//       [--spaces-root <dir>] [--task-id <uuid>]
+//       [--quiesce-mins <n>] [--in-flight-window-mins <n>]
+//
+//   --manifest-before is the workflow's pre-trigger manifest snapshot
+//   (JSON {"built_at":<ISO|null>,"content_sha256":<hex|null>}, design §1.9).
+//   The verified path requires the current manifest's content_sha256 to
+//   differ from the baseline (a new build identity, not a replayed
+//   manifest). When the baseline is unavailable the classifier falls back
+//   to the time-based advance check and notes it; the Step 4.5 verifier
+//   (lib/verify-publish.js) is the strict gate and fails closed without a
+//   baseline before stamping.
+//
+// Exit 0 with the decision JSON on stdout for every decision (a decision
+// is data, not a failure). Exit 2 on usage/validation. Nothing is printed
+// to stdout on failure.
+
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  EMPTY_TREE,
+  parseDiff,
+  parseFindings,
+  makeOldCounter,
+  discriminatingLines,
+} from "./publish-content.js";
+
+function arg(name, required = true, def = null) {
+  const i = process.argv.lastIndexOf(name); // last occurrence wins
+  if (i < 0 || i + 1 >= process.argv.length) {
+    if (required && def === null) fail("usage", `${name} is required.`);
+    return def;
+  }
+  return process.argv[i + 1];
+}
+function fail(code, message) {
+  process.stderr.write(JSON.stringify({ ok: false, error: code, message }) + "\n");
+  process.exit(2);
+}
+
+const repoPath = arg("--repo-path");
+const commit = arg("--commit");
+const base = arg("--base");
+const slug = arg("--slug");
+const triggerTs = arg("--trigger-ts");
+const parkTs = arg("--park-ts");
+const spacesRoot = arg("--spaces-root", false, join(homedir(), "workspace", "ts-spaces"));
+const taskId = arg("--task-id", false, "classify");
+const quiesceMins = parseInt(arg("--quiesce-mins", false, "30"), 10);
+const inFlightWindowMins = parseInt(arg("--in-flight-window-mins", false, "15"), 10);
+// Pre-trigger manifest baseline (design §1.9), JSON-encoded. Optional —
+// the classifier falls back to the time-based check when absent.
+// 2026-09-18, should-fix 1: distinguish absent (legacy, no baseline) from
+// malformed (supplied but invalid) — malformed is ambiguous, not absent.
+// A valid baseline requires a parseable built_at timestamp and a 64-hex
+// content_sha256.
+let manifestBefore = null;
+let manifestBeforeMalformed = false;
+const manifestBeforeRaw = arg("--manifest-before", false, null);
+if (manifestBeforeRaw) {
+  try {
+    const parsed = JSON.parse(manifestBeforeRaw);
+    const builtAt = parsed && typeof parsed.built_at === "string" ? parsed.built_at : null;
+    const sha = parsed && typeof parsed.content_sha256 === "string" ? parsed.content_sha256 : null;
+    const builtAtMs = builtAt ? Date.parse(builtAt) : NaN;
+    const shaOk = sha && /^[0-9a-f]{64}$/.test(sha);
+    if (parsed && typeof parsed === "object" && builtAtMs > 0 && shaOk) {
+      manifestBefore = { built_at: builtAt, content_sha256: sha };
+    } else {
+      // Supplied but invalid: fail closed as ambiguous, not absent.
+      manifestBeforeMalformed = true;
+    }
+  } catch {
+    // Supplied but unparsable: fail closed as ambiguous, not absent.
+    manifestBeforeMalformed = true;
+  }
+}
+
+if (!/^[0-9a-f]{40}$/.test(commit)) fail("usage", "commit must be a 40-char hex sha.");
+if (!/^[0-9a-f]{40}$/.test(base)) fail("usage", "base must be a 40-char hex sha.");
+if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(slug)) fail("usage", "slug is not a safe artifact slug.");
+const triggerMs = Date.parse(triggerTs);
+const parkMs = Date.parse(parkTs);
+if (!(triggerMs > 0)) fail("usage", "trigger-ts is not a valid timestamp.");
+if (!(parkMs > 0)) fail("usage", "park-ts is not a valid timestamp.");
+if (!(quiesceMins > 0)) fail("usage", "quiesce-mins must be positive.");
+if (!(inFlightWindowMins > 0)) fail("usage", "in-flight-window-mins must be positive.");
+
+function decide(decision, reasons, details = {}) {
+  process.stdout.write(JSON.stringify({ ok: true, decision, reasons, details }) + "\n");
+  process.exit(0);
+}
+
+// Resolve the space dir with realpath containment (same rule as
+// readback-disk.js — the slug must not escape the spaces root).
+function resolveSpaceDir() {
+  try {
+    const rootReal = realpathSync(spacesRoot);
+    const candReal = realpathSync(join(spacesRoot, slug));
+    if (candReal !== rootReal && !candReal.startsWith(rootReal + "/")) return null;
+    return statSync(candReal).isDirectory() ? candReal : null;
+  } catch {
+    return null;
+  }
+}
+
+// (d) No build in flight. Signals, both heuristic but conservative:
+//   - manifest built_at within the window: a build just landed, the
+//     deployment may still be propagating;
+//   - any file under .space-build with mtime within the window: the
+//     platform is actively writing build output.
+// A build running longer than the window without touching .space-build is
+// pathological; the caller escalates to terminal at park+2h.
+// (d) Build-in-flight detection: the manifest is the platform's build
+// record. A build is "in flight" for our purposes if the manifest state
+// changes during the content read (a build landed mid-read — the read may
+// be torn) or if the manifest's built_at is within the settle window (a
+// build just completed; the working copy may still be settling). Checked
+// twice bracketing the content read (design §1.4d); the double check
+// bounds the residual window to the local disk-read duration. Directory
+// mtimes are NOT used — they cannot distinguish a running build from a
+// recently completed one, and the manifest is the honest record.
+function manifestState(spaceDir) {
+  const m = readManifest(spaceDir);
+  if (!m) return null;
+  return { built_at: m.built_at, content_sha256: m.content_sha256 };
+}
+function buildInFlight(spaceDir, nowMs, beforeState) {
+  const afterState = manifestState(spaceDir);
+  // State changed during the read → a build landed mid-read.
+  if (beforeState && afterState &&
+      (beforeState.built_at !== afterState.built_at ||
+       beforeState.content_sha256 !== afterState.content_sha256)) {
+    return { inFlight: true, afterState, reason: `manifest changed during the content read (before built_at=${beforeState.built_at}, after built_at=${afterState.built_at}) — the read may be torn` };
+  }
+  // Manifest built very recently → a build just completed; let it settle.
+  // 2026-09-18, should-fix 2: enforce 0 <= age < settleMs. A future built_at
+  // (negative age) is pathological — clock skew or corruption — and must not
+  // defer forever. It is ambiguous, not in-flight.
+  const settleMs = inFlightWindowMins * 60 * 1000;
+  const builtAtMs = afterState && afterState.built_at ? Date.parse(afterState.built_at) : NaN;
+  if (Number.isFinite(builtAtMs)) {
+    const ageMs = nowMs - builtAtMs;
+    if (ageMs < 0) {
+      return { inFlight: false, afterState, pathological: true, reason: `manifest built_at ${afterState.built_at} is in the future (age ${ageMs}ms) — pathological, not in-flight` };
+    }
+    if (ageMs < settleMs) {
+      return { inFlight: true, afterState, reason: `manifest built_at ${afterState.built_at} is within the ${inFlightWindowMins}min settle window — a build just completed` };
+    }
+  }
+  return { inFlight: false, afterState };
+}
+
+function readManifest(spaceDir) {
+  if (!spaceDir) return null;
+  try {
+    const m = JSON.parse(readFileSync(join(spaceDir, ".space-build", "manifest.json"), "utf8"));
+    return {
+      built_at: typeof m.built_at === "string" ? m.built_at : null,
+      content_sha256: typeof m.content_sha256 === "string" ? m.content_sha256 : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+const nowMs = Date.now();
+const spaceDir = resolveSpaceDir();
+
+// (should-fix 1) Malformed supplied baseline → ambiguous, not absent.
+// A supplied --manifest-before that fails validation is evidence corruption,
+// not a legacy absent baseline. Fail closed.
+if (manifestBeforeMalformed) {
+  decide("ambiguous",
+    [`supplied --manifest-before failed validation (must be JSON with a parseable built_at and a 64-hex content_sha256)`],
+    { manifest_before_malformed: true });
+}
+
+// (e) Decision time ≥ park + quiesce. Too young → deferred, no budget
+// consumed, no timer advanced.
+if (nowMs < parkMs + quiesceMins * 60 * 1000) {
+  decide("deferred",
+    [`trigger age below quiesce: park ${parkTs}, quiesce ${quiesceMins}min`],
+    { park_ts: parkTs, quiesce_mins: quiesceMins });
+}
+
+// (d) First in-flight check, before the content read. Captures the
+// manifest state; the second check compares against it.
+const manifestBeforeRead = manifestState(spaceDir);
+let flight = buildInFlight(spaceDir, nowMs, null);
+// Pathological future timestamp → ambiguous, not deferred (should-fix 2).
+if (flight.pathological) {
+  decide("ambiguous",
+    [`manifest built_at is in the future (pathological): ${flight.reason}`],
+    { pathological_future_built_at: true, in_flight_reason: flight.reason });
+}
+if (flight.inFlight) {
+  if (nowMs > parkMs + 2 * 60 * 60 * 1000) {
+    decide("ambiguous",
+      [`build still in flight at park+2h (pathological): ${flight.reason}`],
+      { in_flight_reason: flight.reason });
+  }
+  decide("deferred", [`build in flight (pre-read check): ${flight.reason}`],
+    { in_flight_reason: flight.reason });
+}
+
+// The content read: the deterministic sensor on the platform's working copy.
+const sensorPath = join(new URL(".", import.meta.url).pathname, "readback-disk.js");
+let findingsText;
+try {
+  findingsText = execFileSync("node", [
+    sensorPath,
+    "--repo-path", repoPath,
+    "--commit", commit,
+    "--base", base,
+    "--slug", slug,
+    "--task-id", taskId,
+    "--spaces-root", spacesRoot,
+  ], { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+} catch (e) {
+  decide("ambiguous",
+    [`sensor unreadable: ${(e.stderr || e.message || "").toString().slice(0, 200)}`],
+    { sensor_failed: true });
+}
+
+// (d) Second in-flight check, bracketing the content read. Compares the
+// manifest state against the pre-read baseline; a change means a build
+// landed mid-read (the read may be torn). The double check bounds the
+// residual window to the local disk-read duration.
+flight = buildInFlight(spaceDir, Date.now(), manifestBeforeRead);
+// Pathological future timestamp → ambiguous, not deferred (should-fix 2).
+if (flight.pathological) {
+  decide("ambiguous",
+    [`manifest built_at is in the future (pathological, post-read): ${flight.reason}`],
+    { pathological_future_built_at: true, in_flight_reason: flight.reason });
+}
+if (flight.inFlight) {
+  decide("deferred", [`build in flight (post-read check): ${flight.reason}`],
+    { in_flight_reason: flight.reason });
+}
+
+// 2026-09-18, should-fix 3: use the manifest state already checked by the
+// post-read in-flight check (flight.afterState) — do NOT re-read the manifest
+// here. A third read reopens the TOCTOU window the double-check just closed.
+const manifest = flight.afterState;
+const manifestBuiltAtMs = manifest && manifest.built_at ? Date.parse(manifest.built_at) : NaN;
+const manifestAdvanced = Number.isFinite(manifestBuiltAtMs) && manifestBuiltAtMs > triggerMs;
+
+// The expected change, from git (never from anyone's report).
+if (base !== EMPTY_TREE) {
+  try {
+    execFileSync("git", ["-C", repoPath, "merge-base", "--is-ancestor", base, commit], { stdio: "ignore" });
+  } catch {
+    decide("ambiguous", [`base ${base} is not an ancestor of commit ${commit}`], {});
+  }
+}
+let diff;
+try {
+  diff = execFileSync("git", ["-C", repoPath, "diff", base, commit, "--"], {
+    encoding: "utf8", maxBuffer: 4 * 1024 * 1024,
+  });
+} catch (e) {
+  decide("ambiguous", [`git diff failed: ${e.message.slice(0, 200)}`], {});
+}
+if (!diff.trim()) {
+  decide("ambiguous", ["empty diff for commit — nothing to judge"], {});
+}
+const diffMap = parseDiff(diff);
+const oldCount = makeOldCounter(repoPath, base);
+const disc = discriminatingLines(diffMap, oldCount);
+
+// Files the line-based judge cannot certify at all → ambiguous, never a
+// retry on zero signal.
+for (const [path, d] of disc) {
+  if (d.unjudgeable) {
+    decide("ambiguous",
+      [`unverifiable-content ${path}: ${d.unjudgeable} — the diff carries no discriminating lines for this file`],
+      { file: path, unjudgeable: d.unjudgeable });
+  }
+}
+
+// (f) Supersession re-check: a retry against a moved HEAD would regress a
+// newer publish.
+let head;
+try {
+  head = execFileSync("git", ["-C", repoPath, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+} catch (e) {
+  decide("ambiguous", [`git rev-parse HEAD failed: ${e.message.slice(0, 200)}`], {});
+}
+if (head !== commit) {
+  decide("superseded",
+    [`HEAD is ${head}, not ${commit} — a newer publish supersedes this one; no retry`],
+    { head, commit });
+}
+
+// The findings must cover every discriminating line, or the read is not a
+// read of this diff.
+const { findings, malformed } = parseFindings(findingsText);
+if (malformed) {
+  decide("ambiguous", [`unreadable findings: ${malformed}`], {});
+}
+let totalDisc = 0;
+let addedPresent = 0, addedAbsent = 0, removedPresent = 0, removedAbsent = 0;
+for (const [path, d] of disc) {
+  const found = findings.get(path);
+  if (!found) {
+    decide("ambiguous", [`no findings for changed file ${path}`], { file: path });
+  }
+  for (const line of d.addedDisc) {
+    totalDisc++;
+    const v = found.added.get(line);
+    if (v === undefined) decide("ambiguous", [`no ADDED finding for line in ${path}`], { file: path });
+    if (v === "PRESENT") addedPresent++; else addedAbsent++;
+  }
+  for (const line of d.removedDisc) {
+    totalDisc++;
+    const v = found.removed.get(line);
+    if (v === undefined) decide("ambiguous", [`no REMOVED finding for line in ${path}`], { file: path });
+    if (v === "PRESENT") removedPresent++; else removedAbsent++;
+  }
+}
+if (totalDisc === 0) {
+  decide("ambiguous",
+    ["zero discriminating lines across the diff — no signal to judge; refusing to decide on vacuous truth"],
+    {});
+}
+
+const details = {
+  manifest_built_at: manifest ? manifest.built_at : null,
+  manifest_advanced: manifestAdvanced,
+  head,
+  discriminating_added: addedPresent + addedAbsent,
+  discriminating_removed: removedPresent + removedAbsent,
+  added_present: addedPresent,
+  added_absent: addedAbsent,
+  removed_present: removedPresent,
+  removed_absent: removedAbsent,
+};
+
+// Manifest advanced past the trigger: a build ran for this attempt.
+if (manifestAdvanced) {
+  // Verified ⟺ the source shows the full post-edit state. A side with no
+  // discriminating lines is vacuously satisfied; totalDisc > 0 (checked
+  // above) guarantees at least one side carries signal.
+  const addedOk = addedPresent + addedAbsent === 0 || (addedPresent > 0 && addedAbsent === 0);
+  const removedOk = removedPresent + removedAbsent === 0 || (removedAbsent > 0 && removedPresent === 0);
+  if (addedOk && removedOk) {
+    // Design §1.9: the manifest must be a NEW build identity, not a
+    // replayed manifest with a bumped built_at. When the pre-trigger
+    // baseline is available, require the content_sha256 to differ; when
+    // unavailable, fall back to the time-based advance (noted) — the Step
+    // 4.5 verifier is the strict gate and fails closed without a baseline
+    // before stamping.
+    const beforeHash = manifestBefore ? manifestBefore.content_sha256 : null;
+    const currentHash = manifest ? manifest.content_sha256 : null;
+    if (manifestBefore && beforeHash && currentHash) {
+      if (beforeHash === currentHash) {
+        decide("ambiguous",
+          [`manifest built_at advanced past trigger but content_sha256 is unchanged from the pre-trigger baseline — a replayed manifest, not a new build; refusing to verify`],
+          { ...details, manifest_before: manifestBefore });
+      }
+      decide("verified",
+        [`manifest built_at ${manifest.built_at} advanced past trigger ${triggerTs} with a new content_sha256 (differs from pre-trigger baseline); content matches the diff`],
+        { ...details, manifest_before: manifestBefore });
+    }
+    decide("verified",
+      [`manifest built_at ${manifest.built_at} advanced past trigger ${triggerTs}; content matches the diff (no pre-trigger baseline — freshness by time only; the Step 4.5 verifier fails closed without a baseline)`],
+      { ...details, manifest_before: null, baseline_absent: true });
+  }
+  // A build ran but the content does not match: not ours to claim.
+  decide("ambiguous",
+    [`manifest advanced past trigger but content mismatched (added PRESENT ${addedPresent}/${addedPresent + addedAbsent}, removed ABSENT ${removedAbsent}/${removedPresent + removedAbsent}) — a build ran that is not this diff`],
+    details);
+}
+
+// Manifest stale: no build for this attempt. Judge the source state.
+const addedDropped = addedPresent + addedAbsent === 0 || (addedAbsent > 0 && addedPresent === 0);
+const removedDropped = removedPresent + removedAbsent === 0 || (removedPresent > 0 && removedAbsent === 0);
+const addedApplied = addedPresent + addedAbsent === 0 || (addedPresent > 0 && addedAbsent === 0);
+const removedApplied = removedPresent + removedAbsent === 0 || (removedAbsent > 0 && removedPresent === 0);
+if (addedDropped && removedDropped) {
+  decide("provably-dropped",
+    [
+      "(a) every discriminating added line ABSENT",
+      "(b) every discriminating removed line PRESENT",
+      `(c) manifest built_at ${manifest ? manifest.built_at : "missing"} NOT advanced past trigger ${triggerTs}`,
+      "(d) no build in flight (checked twice, bracketing the read)",
+      `(e) decision time past park+${quiesceMins}min quiesce`,
+      "(f) HEAD == commit",
+    ],
+    details);
+}
+if (addedApplied && removedApplied) {
+  // J1's shape: the platform started something (the phantom) but no build
+  // completed — "platform build-emission failure." No retry: re-applying a
+  // possibly mid-apply diff is the 2026-09-12 hazard in a new coat.
+  decide("applied-not-built",
+    [
+      `source shows the full post-edit state but manifest stale (built_at ${manifest ? manifest.built_at : "missing"}) — platform build-emission failure; no retry`,
+    ],
+    details);
+}
+decide("ambiguous",
+  [`partial-apply or indeterminate (added PRESENT ${addedPresent}/${addedPresent + addedAbsent}, removed PRESENT ${removedPresent}/${removedPresent + removedAbsent}) with a stale manifest`],
+  details);