beadcyte 0.4.0

package/src/serve.mjs

@@ -0,0 +1,411 @@
+// beadcyte serve — local Vue dev server + companion /api/beads endpoint.
+//
+// Boots Vite programmatically on the beadcyte web root (`src/web/`) and
+// attaches a `/api/beads` middleware that shells `bd list --all --limit 0
+// --json` from the CWD, cached ~30s. Same port for both, so the browser fetches
+// the API from its own origin and CORS never comes up.
+//
+// Localhost-only. No auth. This is a dev tool, not a service — same posture as
+// bv, and same threat model.
+
+import { execFile } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { createServer as createViteServer } from "vite";
+import vuePlugin from "@vitejs/plugin-vue";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createAllowlist, inspectProject } from "./projects.mjs";
+import { resolveRosterPath, ROSTER_CANDIDATES } from "./roster-path.mjs";
+import { clearState, writeState } from "./server-state.mjs";
+import { createHistoryWalker } from "./history-walk.mjs";
+import { mergeHistory } from "./review-hours.mjs";
+import { validateMutation, bdArgsFor, describeMutation, createdIdFrom } from "./mutate.mjs";
+
+const execFileAsync = promisify(execFile);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const webRoot = join(__dirname, "web");
+
+// ── args ──────────────────────────────────────────────────────────────────
+const args = parseArgs(process.argv.slice(2));
+if (args.help || args.h) {
+  printHelp();
+  process.exit(0);
+}
+const port = parseInt(args.port ?? "4173", 10);
+// Undefined means "use the convention", which now spans two directory
+// names — see roster-path.mjs.
+const rosterPath = args.roster;
+const cacheTtlMs = parseInt(args["cache-ttl"] ?? "30000", 10);
+const cwd = process.cwd();
+// Set by `beadcyte start`: where to record the port once we are listening, so
+// `beadcyte stop` can find this process. Unset when run in the foreground.
+const stateFile = process.env.BEADCYTE_STATE_FILE;
+
+// ── projects ──────────────────────────────────────────────────────────────
+// The launch directory is seeded so a first run is never empty; everything
+// else has to be registered by the client before it can be read.
+const allowlist = createAllowlist([cwd]);
+
+// ── beads cache ───────────────────────────────────────────────────────────
+// The shell-out to `bd` is the one non-trivial cost. Cached per project —
+// a single global would serve one project's beads for another for up to the
+// TTL after a switch, or force a refetch on every toggle.
+//
+// `lastMs` is retained per project so the client's load meter can fill
+// against a real prior measurement instead of a fabricated percentage; the
+// subprocess is ~90% of load time and reports no progress of its own.
+const caches = new Map(); // project -> { generated_at, payload, ts, lastMs }
+
+// ── history walk (bp-67g.57) ─────────────────────────────────────────────
+// hours_in_review lives only in `bd history`, one shell-out per bead (~0.4s,
+// ~0.4MB each on this repo), so it is walked in the background and cached;
+// the request path only merges what the walk already knows. When a walk
+// changes something, the cached payload is re-merged and re-stamped so the
+// next poll picks it up without another `bd list`.
+//
+// bd serialises its calls, so the walk keeps out of the request path's way:
+// it waits for any `bd list` in flight before each history call, and it does
+// not start until WALK_START_DELAY_MS after a load, so the boot-time prefetch
+// below and the first real request are both answered first. Measured before
+// this: a first request racing the walk took 4.9–7.4s instead of 1.0s.
+const WALK_START_DELAY_MS = 5_000;
+let listInFlight = null; // Promise while a `bd list` runs, else null
+const historyWalker = createHistoryWalker({
+  log: (msg) => console.error(`[beadcyte serve] ${msg}`),
+  beforeEach: () => listInFlight ?? Promise.resolve(),
+});
+const walkTimers = new Map(); // project -> timeout
+function scheduleWalk(project, beads) {
+  clearTimeout(walkTimers.get(project));
+  walkTimers.set(
+    project,
+    setTimeout(() => {
+      walkTimers.delete(project);
+      void historyWalker.refresh(project, beads);
+    }, WALK_START_DELAY_MS),
+  );
+}
+const historyListeners = new Set();
+function watchHistory(project) {
+  if (historyListeners.has(project)) return;
+  historyListeners.add(project);
+  historyWalker.onChange(project, () => {
+    const hit = caches.get(project);
+    if (!hit?.payload) return;
+    mergeHistory(hit.payload.beads, historyWalker.cache(project));
+    const generated_at = new Date().toISOString();
+    hit.generated_at = generated_at;
+    hit.payload.generated_at = generated_at;
+  });
+}
+
+async function loadBeads(project) {
+  const now = Date.now();
+  const hit = caches.get(project);
+  if (hit?.payload && now - hit.ts < cacheTtlMs) return hit;
+
+  const started = Date.now();
+  const listing = execFileAsync(
+    "bd",
+    ["list", "--all", "--limit", "0", "--json"],
+    { cwd: project, maxBuffer: 256 * 1024 * 1024 },
+  );
+  // Held for the history walk to yield to; cleared however the list ends.
+  listInFlight = listing.then(
+    () => {
+      listInFlight = null;
+    },
+    () => {
+      listInFlight = null;
+    },
+  );
+  const { stdout } = await listing;
+  const beads = JSON.parse(stdout);
+  mergeHistory(beads, historyWalker.cache(project));
+  watchHistory(project);
+  scheduleWalk(project, beads);
+  const roster = loadRoster(beads, project);
+  const took_ms = Date.now() - started;
+  const generated_at = new Date().toISOString();
+  const entry = {
+    generated_at,
+    payload: { generated_at, beads, roster, project, took_ms },
+    ts: now,
+    lastMs: took_ms,
+  };
+  caches.set(project, entry);
+  return entry;
+}
+
+function loadRoster(beads, project) {
+  const found = resolveRosterPath(project, rosterPath);
+  if (found) {
+    try {
+      return JSON.parse(readFileSync(found.path, "utf8"));
+    } catch (e) {
+      console.error(`[beadcyte serve] roster ${found.path} failed to parse: ${e.message}`);
+    }
+  }
+  if (rosterPath) {
+    console.error(
+      `[beadcyte serve] --roster ${rosterPath} does not exist; deriving from beads`,
+    );
+  }
+  const seen = new Set();
+  for (const b of beads) if (b.assignee) seen.add(b.assignee);
+  return {
+    cap: 5,
+    humans: [...seen].map((handle) => ({ handle })),
+    _derived: true,
+  };
+}
+
+// ── vite server ───────────────────────────────────────────────────────────
+// The /api/beads route must be registered BEFORE Vite's own middlewares
+// (transformIndexHtml SPA fallback), otherwise every request returns
+// index.html. `configureServer` without a returned function runs pre-internal.
+/**
+ * Live data must never be reused from a cache we don't control.
+ *
+ * These responses carried no Cache-Control at all — just a Date — and with
+ * no directives and no validators a browser applies heuristic freshness and
+ * may serve a stored copy without revalidating. That quietly defeats the
+ * whole point of polling: the client asks again and the browser answers
+ * from its own store. `no-store` rather than `no-cache` because there is no
+ * value in keeping a copy of a snapshot at all.
+ */
+function noStore(res) {
+  res.setHeader("Cache-Control", "no-store, max-age=0");
+}
+
+/** Collect a request body. Small by construction — one JSON path. */
+function readBody(req, limit = 64 * 1024) {
+  return new Promise((resolve, reject) => {
+    let out = "";
+    req.on("data", (chunk) => {
+      out += chunk;
+      if (out.length > limit) reject(new Error("body too large"));
+    });
+    req.on("end", () => resolve(out));
+    req.on("error", reject);
+  });
+}
+
+const beadsApiPlugin = {
+  name: "bp-beads-api",
+  configureServer(server) {
+    // Registration: validate a path and admit it. This is the ONLY way a
+    // directory becomes readable, which is what keeps /api/beads from
+    // doubling as a filesystem probe for any page that can reach localhost.
+    server.middlewares.use("/api/projects", async (req, res) => {
+      const json = (code, body) => {
+        res.statusCode = code;
+        res.setHeader("Content-Type", "application/json");
+        noStore(res);
+        res.end(JSON.stringify(body));
+      };
+      if (req.method === "GET") {
+        // What this server already trusts, so a client with a stale
+        // registry can tell what it still has access to.
+        return json(200, { launch: cwd, projects: allowlist.list() });
+      }
+      if (req.method !== "POST") return json(405, { error: "use GET or POST" });
+      try {
+        const raw = await readBody(req);
+        const { path } = raw ? JSON.parse(raw) : {};
+        const seen = allowlist.register(path);
+        if (!seen.ok) return json(400, { ok: false, reason: seen.reason });
+        return json(200, { ok: true, path: seen.path, label: seen.label });
+      } catch (e) {
+        return json(400, { ok: false, error: String(e.message ?? e) });
+      }
+    });
+
+    // Writes (bp-ocs): one bead, one whitelisted action, one bd command,
+    // argv not shell. The project must be registered, exactly like reads;
+    // the list cache for it is dropped so the next poll shows the change;
+    // the fresh bead comes back so the client can replace its optimistic
+    // guess with what bd actually did.
+    server.middlewares.use("/api/mutate", async (req, res) => {
+      const json = (code, body) => {
+        res.statusCode = code;
+        res.setHeader("Content-Type", "application/json");
+        noStore(res);
+        res.end(JSON.stringify(body));
+      };
+      if (req.method !== "POST") return json(405, { error: "use POST" });
+      let m;
+      let project;
+      try {
+        const raw = await readBody(req);
+        const body = raw ? JSON.parse(raw) : {};
+        project = typeof body.project === "string" && body.project ? body.project : cwd;
+        if (!allowlist.allows(project)) return json(403, { error: "project not registered for this session", project });
+        m = validateMutation(body);
+      } catch (e) {
+        return json(400, { error: String(e.message ?? e) });
+      }
+      const command = describeMutation(m);
+      try {
+        const ran = await execFileAsync("bd", bdArgsFor(m), { cwd: project, maxBuffer: 8 * 1024 * 1024 });
+        caches.delete(project);
+        // create has no id until bd names one (bp-2fq).
+        const id = m.action === "create" ? createdIdFrom(ran.stdout) : m.id;
+        if (!id) return json(200, { ok: true, command, bead: null });
+        const { stdout } = await execFileAsync("bd", ["show", id, "--json"], { cwd: project, maxBuffer: 8 * 1024 * 1024 });
+        const shown = JSON.parse(stdout);
+        const bead = Array.isArray(shown) ? shown[0] ?? null : shown;
+        console.error(`[beadcyte serve] mutate: ${command}`);
+        return json(200, { ok: true, command, bead });
+      } catch (e) {
+        const detail = String(e?.stderr || e?.message || e).trim().split("\n").slice(-3).join(" ");
+        console.error(`[beadcyte serve] mutate failed: ${command}: ${detail}`);
+        return json(500, { ok: false, command, error: detail });
+      }
+    });
+
+    server.middlewares.use("/api/beads", async (req, res) => {
+      try {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const since = url.searchParams.get("since");
+        // Absent `project` means the launch directory, so an old client and
+        // a plain curl both keep working.
+        const project = url.searchParams.get("project") ?? cwd;
+        if (!allowlist.allows(project)) {
+          // Refused on the allowlist alone — no stat, no realpath, nothing
+          // that could reveal whether the path exists.
+          res.statusCode = 403;
+          res.setHeader("Content-Type", "application/json");
+          noStore(res);
+          res.end(
+            JSON.stringify({
+              error: "project not registered for this session",
+              project,
+            }),
+          );
+          return;
+        }
+        const data = await loadBeads(project);
+        // Short-circuit for polling: if `since` matches current generated_at,
+        // return an empty body with 304-style semantics (via a `stale=false`
+        // flag so the client doesn't need to interpret the status code).
+        if (since && since === data.generated_at) {
+          res.setHeader("Content-Type", "application/json");
+          noStore(res);
+          res.end(
+            JSON.stringify({
+              stale: false,
+              generated_at: data.generated_at,
+              project,
+              last_ms: data.lastMs ?? null,
+            }),
+          );
+          return;
+        }
+        res.setHeader("Content-Type", "application/json");
+        noStore(res);
+        res.end(JSON.stringify({ stale: true, ...data.payload }));
+      } catch (e) {
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "application/json");
+        noStore(res);
+        res.end(JSON.stringify({ error: String(e.message ?? e) }));
+      }
+    });
+  },
+};
+
+// Expose the package version to the app as `import.meta.env.VITE_BEADCYTE_VERSION`.
+const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"));
+process.env.VITE_BEADCYTE_VERSION = packageJson.version;
+// The in-app changelog's link out (bp-67g.46). Deployment-specific — a
+// private group's repo is not something to hardcode — so it is an env var,
+// and the link is absent when unset.
+if (process.env.BEADCYTE_CHANGELOG_URL) {
+  process.env.VITE_BEADCYTE_CHANGELOG_URL = process.env.BEADCYTE_CHANGELOG_URL;
+}
+
+const vite = await createViteServer({
+  root: webRoot,
+  server: {
+    port,
+    strictPort: false,
+    host: "127.0.0.1",
+  },
+  plugins: [beadsApiPlugin, vuePlugin()],
+  clearScreen: false,
+});
+
+await vite.listen(port);
+
+const info = vite.config.server;
+const actualPort = vite.httpServer?.address()?.port ?? info.port ?? port;
+console.log(`\n  beadcyte serve — http://127.0.0.1:${actualPort}/`);
+console.log(`  data at   http://127.0.0.1:${actualPort}/api/beads`);
+console.log(`  cwd       ${cwd}`);
+// Nothing is loaded at boot, so the banner states the path rather than
+// reporting on a cache entry that cannot exist yet.
+console.log(
+  `  roster    ${rosterPath ?? ROSTER_CANDIDATES.join(" or ")} (per project; derived from beads when absent)`,
+);
+console.log(`  projects  registered on demand — ${cwd} seeded`);
+console.log(stateFile ? `  stop with beadcyte stop\n` : `  Ctrl-C to stop\n`);
+
+if (stateFile) {
+  // Written after the banner so `start` can print the banner from the log.
+  writeState(stateFile, {
+    pid: process.pid,
+    port: actualPort,
+    url: `http://127.0.0.1:${actualPort}/`,
+    cwd,
+    startedAt: new Date().toISOString(),
+    log: process.env.BEADCYTE_LOG_FILE ?? null,
+  });
+  for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.on(sig, () => {
+      clearState(stateFile);
+      vite.close().finally(() => process.exit(0));
+    });
+  }
+}
+
+// Warm the cache so the first browser request is instant.
+// Warm the launch project only. Other projects load when first selected —
+// prefetching a registry the browser holds isn't possible at boot anyway.
+loadBeads(cwd).catch((e) =>
+  console.error(`[beadcyte serve] initial bd load failed: ${e.message}`),
+);
+
+// ── helpers ───────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const k = a.slice(2);
+    const v = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+    out[k] = v;
+  }
+  return out;
+}
+
+function printHelp() {
+  console.log(`beadcyte serve — the interactive app, in the foreground (Ctrl-C to stop)
+
+Usage:
+  beadcyte serve [--port N] [--roster PATH] [--cache-ttl MS]
+  beadcyte start [same flags]     the same server in the background; returns
+  beadcyte stop                   end a background server for this directory
+
+Boots a Vite dev server for the interactive Gantt at 127.0.0.1:<port>. Same
+port serves /api/beads which shells 'bd list --all --limit 0 --json' from the
+CURRENT WORKING DIRECTORY, cached for --cache-ttl ms (default 30000).
+
+Flags:
+  --port N          Listen port (default: 4173; falls through if taken)
+  --roster PATH     Roster JSON path (default: .beadcyte/roster.json)
+  --cache-ttl MS    Beads cache TTL in ms (default: 30000)
+  -h, --help        This message
+`);
+}

package/src/server-state.mjs

@@ -0,0 +1,105 @@
+// server-state.mjs — where `beadcyte start` records the background server.
+//
+// `beadcyte start` launches `beadcyte serve` detached and returns the shell to
+// the user; `beadcyte stop` has to find that process again later, from the same
+// project directory, possibly from a different terminal. The record that joins
+// the two is a small JSON file keyed on the project directory.
+//
+// It lives under the OS temp dir, not inside the project, for two reasons: a
+// user's repository should not need a .gitignore entry to use a viewer, and a
+// leftover record after a crash then costs nothing but a stale file in /tmp.
+// The server's log sits beside it under the same key, so `start` can print
+// where the output went.
+//
+// Pure in the sense this repo means it: nothing runs on import, and every
+// function takes the paths it touches as arguments (with a tmpdir default) so
+// a test can point the whole thing at a scratch directory.
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** Directory that holds every project's record and log. */
+export function stateDir(base = tmpdir()) {
+  return join(base, "beadcyte");
+}
+
+/**
+ * Stable key for a project directory: a prefix of the sha1 of its absolute
+ * path. Two terminals in the same directory agree; two projects never collide
+ * in practice.
+ */
+export function projectKey(projectDir) {
+  return createHash("sha1").update(resolve(projectDir)).digest("hex").slice(0, 16);
+}
+
+/** Path of the JSON record for a project. */
+export function stateFileFor(projectDir, base = tmpdir()) {
+  return join(stateDir(base), `${projectKey(projectDir)}.json`);
+}
+
+/** Path of the server log for a project — beside its record. */
+export function logFileFor(projectDir, base = tmpdir()) {
+  return join(stateDir(base), `${projectKey(projectDir)}.log`);
+}
+
+/**
+ * Read a record. Returns null when the file is missing or unparsable — a
+ * corrupt record is treated as "not running" rather than as an error, because
+ * the only recovery either way is to start again.
+ *
+ * @returns {{ pid: number, port: number, url: string, cwd: string, startedAt: string, log: string|null } | null}
+ */
+export function readState(file) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof parsed?.pid !== "number") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Write a record, creating the directory on first use. */
+export function writeState(file, state) {
+  mkdirSync(join(file, ".."), { recursive: true });
+  writeFileSync(file, JSON.stringify(state, null, 2) + "\n");
+}
+
+/** Remove a record if present. Missing is not an error. */
+export function clearState(file) {
+  if (existsSync(file)) unlinkSync(file);
+}
+
+/**
+ * Is there a process with this pid? Signal 0 probes without delivering.
+ * EPERM means it exists but belongs to someone else, which still counts as
+ * alive: `stop` will then fail loudly on the real signal instead of quietly
+ * deleting a record for a server it cannot reach.
+ */
+export function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code === "EPERM";
+  }
+}
+
+/** The lines `start` prints once the server is up. */
+export function describeRunning(state) {
+  return [
+    `beadcyte is running for ${state.cwd}`,
+    `  ${state.url}  (pid ${state.pid})`,
+    ...(state.log ? [`  log       ${state.log}`] : []),
+    `  stop with: beadcyte stop`,
+  ].join("\n");
+}

package/src/ship.mjs

@@ -0,0 +1,178 @@
+// ship.mjs — the one place that answers "did this close actually ship?"
+//
+// Three models hang off that answer: velocity (and therefore every
+// calibrated WIP cap), the estimator's duration and lead-time samples, and
+// the ships-per-week trend. The Gantt also draws `shipped` vs `closedNoShip`
+// from it. Until this module existed the rule was written out five times —
+// `!!b.metadata?.ship?.mr_url` in the estimator (twice), velocity, the SVG
+// CLI and the web view-model — which is precisely how two of them end up
+// disagreeing about what a ship is a year from now.
+//
+// ## Why a commit counts
+//
+// `mr_url` was the only accepted evidence, which quietly restricted the tool
+// to teams working through merge requests. beadcyte's own repo is the case in
+// point: real work, 41 closed beads, commits that name the bead they close,
+// and a velocity of zero — not because nothing shipped but because the
+// evidence took a form the tool refused to read.
+//
+// ## Evidence, not a checkbox
+//
+// docs/economics.md argues that `mr_url` is trustworthy downstream precisely
+// because the close command *refuses to close without it*. Widening the
+// accepted forms must not widen that gate, so:
+//
+//   - `ship: {}` is not evidence. Neither is `ship: { mr_url: "" }`.
+//   - a commit must look like a commit. "TODO", "yes" and "see MR" are not
+//     SHAs, and accepting them would let a placeholder manufacture a ship —
+//     the one failure mode that would make every number downstream worse
+//     rather than merely absent.
+//
+// A rejected-but-present record is reported rather than silently treated as
+// absent, because "you wrote something and it didn't count" needs to be
+// visible or it will be written wrong forever.
+//
+// ## SHAs are trusted, not verified
+//
+// beadcyte never assumes the beads DB and the code live in the same place: it
+// reads `bd list --json`, `beadcyte serve` is normally a global install pointed at
+// some other directory, and beads sync over `refs/dolt/data` independent of
+// any working tree. So there is frequently no repo at hand to check against,
+// and where there is, a SHA that fails to resolve is far more likely to mean
+// a shallow clone, an unfetched branch or a monorepo split than a fabricated
+// record. Verification would also cost one `git cat-file` per closed bead
+// inside a request path that is already cached because a single `bd list` is
+// slow. So the shape is checked and the value is taken on trust.
+
+import { readProvenance, RECORDED } from "./provenance.mjs";
+
+/**
+ * Abbreviated-to-full git object names: 7–40 hex for SHA-1, up to 64 for the
+ * SHA-256 transition. Deliberately not anchored at 40 — plenty of workflows
+ * record `git rev-parse --short HEAD`, and refusing those would push people
+ * back to having no recordable evidence at all.
+ */
+const SHA_RE = /^[0-9a-f]{7,64}$/i;
+
+/** How many characters of a SHA to show when a UI wants a compact one. */
+const SHORT_SHA_LEN = 8;
+
+function trimmed(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+
+/**
+ * The ship block, or a reason it is unreadable.
+ *
+ * The string case is not hypothetical: `bd update --set-metadata
+ * ship={"commit":"..."}` stores the value as a JSON *string*, so a record
+ * that reads correctly in `bd show` is not an object at all and counts for
+ * nothing. Naming that beats treating it as absent — it is a typo in the
+ * command, and nothing else in the UI would ever hint at it.
+ *
+ * @param {{ metadata?: unknown }} bead
+ * @returns {{ ship: Record<string, unknown> } | { malformed: string | null }}
+ */
+function readShip(bead) {
+  const md = /** @type {{ ship?: unknown } | null | undefined} */ (bead?.metadata);
+  const ship = md?.ship;
+  if (ship === undefined || ship === null) return { malformed: null };
+  if (typeof ship !== "object" || Array.isArray(ship)) {
+    return {
+      malformed:
+        `ship record is a ${Array.isArray(ship) ? "list" : typeof ship}, not an object` +
+        // Plain prose: this string is printed straight into the drawer and
+        // the tooltip, neither of which renders markdown.
+        (typeof ship === "string"
+          ? " — bd update --set-metadata stores JSON as a string; use --metadata"
+          : ""),
+    };
+  }
+  return { ship: /** @type {Record<string, unknown>} */ (ship) };
+}
+
+/**
+ * @typedef {Object} ShipEvidence
+ * @property {string[]} forms  which kinds of evidence were found, in
+ *   precedence order: "mr" before "commit". Never empty.
+ * @property {string | null} mrUrl
+ * @property {string | null} commit       full value as recorded
+ * @property {string | null} shortCommit  first 8 chars, for display
+ * @property {string | null} rejected     a present-but-unusable field, if any
+ *   accompanied a usable one (e.g. a valid MR URL and a junk commit)
+ * @property {import("./provenance.mjs").Provenance} provenance
+ *   how the evidence was obtained. A SHA recovered from a `Closes <id>`
+ *   trailer is a fact; the claim that it is THE closing commit is an
+ *   inference, and this is what separates the two. Reads the form that
+ *   carried the evidence — MR first, since it is the stronger record.
+ */
+
+/**
+ * The ship evidence on a bead, or null if it has none that counts.
+ *
+ * Says nothing about `status` — a bead can carry a ship record before its
+ * close lands, and callers that mean "shipped and closed" already test the
+ * status themselves. Keeping the two apart is what lets the drawer show the
+ * evidence on an in-review bead.
+ *
+ * @param {{ metadata?: unknown }} bead  a bd list --json bead
+ * @returns {ShipEvidence | null}
+ */
+export function shipEvidence(bead) {
+  const { ship } = readShip(bead);
+  if (!ship) return null;
+
+  const mrUrl = trimmed(ship.mr_url);
+  const rawCommit = trimmed(ship.commit);
+  const commit = rawCommit && SHA_RE.test(rawCommit) ? rawCommit : null;
+
+  const forms = [];
+  if (mrUrl) forms.push("mr");
+  if (commit) forms.push("commit");
+  if (forms.length === 0) return null;
+
+  return {
+    forms,
+    mrUrl,
+    commit,
+    shortCommit: commit ? commit.slice(0, SHORT_SHA_LEN) : null,
+    rejected: rawCommit && !commit ? `commit is not a SHA: ${rawCommit}` : null,
+    provenance:
+      readProvenance(ship.provenance, forms[0] === "mr" ? "mr_url" : "commit") ??
+      RECORDED,
+  };
+}
+
+/**
+ * Did this bead ship? The predicate every model should use.
+ *
+ * @param {{ metadata?: unknown }} bead
+ * @returns {boolean}
+ */
+export function isShipped(bead) {
+  return shipEvidence(bead) !== null;
+}
+
+/**
+ * Why a bead that looks like it tried to record a ship doesn't count, or null
+ * when there is nothing to explain — no record at all, or a valid one.
+ *
+ * Three distinguishable states, and a UI that collapses them is lying about
+ * one of them: nothing recorded, something recorded that isn't evidence, and
+ * evidence.
+ *
+ * @param {{ metadata?: unknown }} bead
+ * @returns {string | null}
+ */
+export function shipRecordProblem(bead) {
+  const { ship, malformed } = readShip(bead);
+  if (!ship) return malformed ?? null;
+
+  const evidence = shipEvidence(bead);
+  if (evidence) return evidence.rejected;
+
+  const rawCommit = trimmed(ship.commit);
+  if (rawCommit) return `commit is not a SHA: ${rawCommit}`;
+  if (Object.keys(ship).length === 0) return "ship record is empty";
+  return "ship record carries no mr_url and no commit";
+}