@bounded-systems/mint 0.4.3

package/adoption.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// Org-wide mint adoption scanner. Classifies every repo:
+//
+//   ADOPTED      — has a .release/ intent directory (uses mint)
+//   PUBLISHABLE  — package.json with a version, not private — SHOULD adopt, hasn't
+//   N/A          — no versioned package / private (versioning not applicable)
+//
+//   node adoption.mjs            # human report
+//   node adoption.mjs --json     # machine-readable to stdout
+//   node adoption.mjs --write    # open a caller PR for each publishable-not-adopted repo
+//
+// Env: GITHUB_TOKEN (required), ORG (default: bounded-systems), MINT_REF (pin)
+import { writeFileSync } from "node:fs";
+
+const jsonOut = process.argv.includes("--json");
+const write = process.argv.includes("--write");
+const token = process.env.GITHUB_TOKEN;
+if (!token) { console.error("adoption: GITHUB_TOKEN required"); process.exit(1); }
+const org = process.env.ORG ?? "bounded-systems";
+const MINT_REF = process.env.MINT_REF ?? "v0.3.1"; // 6656a2c — first tag with release-provenance.yml
+
+async function ghReq(path, { method = "GET", body } = {}) {
+  const r = await fetch(`https://api.github.com/${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "X-GitHub-Api-Version": "2022-11-28",
+      Accept: "application/vnd.github+json",
+      "User-Agent": "bounded-systems-mint", // GitHub rejects UA-less requests as abuse
+      ...(body ? { "Content-Type": "application/json" } : {}),
+    },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  if (r.status === 404) return null;
+  if (!r.ok) { console.warn(`  gh ${method} ${path} → HTTP ${r.status}: ${(await r.text()).slice(0, 120)}`); return null; }
+  return r.json();
+}
+const gh = (path) => ghReq(path);
+
+// Caller files dropped into each adopting repo.
+const b64 = (s) => Buffer.from(s).toString("base64");
+const VERSION_YML = `name: version
+
+# Versioning via the bounded-systems mint capability. Validates .release/ intents
+# (fails closed on a malformed one) and previews the next version on every PR.
+# Pinned to an immutable mint commit SHA; bump when mint tags.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  version:
+    uses: bounded-systems/mint/.github/workflows/version.yml@${MINT_REF} # mint
+    with:
+      ref: ${MINT_REF}
+`;
+const RELEASE_YML = `name: release
+
+# Release provenance via the bounded-systems mint capability. On a v<version> tag
+# (cut by \`mint release\`), emits the deterministic in-toto release Statement
+# (tag → version plan → commit), keyless-signs it (cosign/OIDC), and attaches it
+# to the GitHub release. Pinned to an immutable mint commit SHA; bump when mint tags.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write   # create / upload to the GitHub release
+  id-token: write   # OIDC — cosign keyless signing
+
+jobs:
+  release:
+    uses: bounded-systems/mint/.github/workflows/release-provenance.yml@${MINT_REF} # mint
+    with:
+      ref: ${MINT_REF}
+`;
+const RELEASE_README = `# Release intents
+
+This repo uses [@bounded-systems/mint](https://github.com/bounded-systems/mint) for
+versioning. Each PR with a user-facing change drops an intent file here; mint
+resolves the strongest bump and cuts the release deterministically.
+
+Format — \`.release/<slug>.md\`:
+
+    ---
+    bump: minor   # patch | minor | major
+    ---
+    short summary of the change (becomes the changelog line)
+
+The \`version\` CI job runs \`mint plan\`, which validates every intent and previews
+the next version.
+`;
+
+async function putFile(repo, path, content, branch, message) {
+  return ghReq(`repos/${org}/${repo}/contents/${path.split("/").map(encodeURIComponent).join("/")}`, {
+    method: "PUT",
+    body: { message, content: b64(content), branch },
+  });
+}
+
+// Open a caller PR adopting mint in one repo. Idempotent-ish: skips if the branch
+// already exists. Returns { repo, pr, url } or null.
+async function openAdoptionPR(repo) {
+  const meta = await gh(`repos/${org}/${repo}`);
+  const base = meta?.default_branch ?? "main";
+  const ref = await gh(`repos/${org}/${repo}/git/ref/heads/${base}`);
+  if (!ref?.object?.sha) { console.warn(`  ${repo}: no ${base} ref`); return null; }
+  const branch = "adopt-mint";
+  const made = await ghReq(`repos/${org}/${repo}/git/refs`, { method: "POST", body: { ref: `refs/heads/${branch}`, sha: ref.object.sha } });
+  if (!made) { console.warn(`  ${repo}: branch exists or create failed — skipping`); return null; }
+  await putFile(repo, ".github/workflows/version.yml", VERSION_YML, branch, "chore: adopt @bounded-systems/mint for versioning");
+  await putFile(repo, ".github/workflows/release.yml", RELEASE_YML, branch, "chore: adopt @bounded-systems/mint release provenance");
+  await putFile(repo, ".release/README.md", RELEASE_README, branch, "chore: add .release intent directory");
+  const pr = await ghReq(`repos/${org}/${repo}/pulls`, {
+    method: "POST",
+    body: { title: "chore: adopt @bounded-systems/mint for versioning", head: branch, base, body: "Adopt [mint](https://github.com/bounded-systems/mint): the reusable version-check (validates `.release/` intents + previews the next bump on every PR) **and** release provenance (on a `v*` tag, emits + keyless-signs the in-toto release Statement and attaches it to the release). Replaces hand-tagging. Org-wide rollout — see bounded-systems/string-audit#43." },
+  });
+  if (!pr?.number) return null;
+  console.log(`  ✓ ${repo.padEnd(24)} PR #${pr.number}`);
+  return { repo, pr: pr.number, url: pr.html_url, branch };
+}
+
+async function fileJson(repo, path) {
+  const d = await gh(`repos/${org}/${repo}/contents/${path.split("/").map(encodeURIComponent).join("/")}`);
+  if (!d?.content) return null;
+  try { return JSON.parse(Buffer.from(d.content, "base64").toString("utf8")); } catch { return null; }
+}
+
+async function probe(repo) {
+  const [release, pkg] = await Promise.all([
+    gh(`repos/${org}/${repo}/contents/.release`), // dir listing or null
+    fileJson(repo, "package.json"),
+  ]);
+  const adopted = Array.isArray(release) && release.some((e) => e.name.endsWith(".md"));
+  const versioned = pkg != null && typeof pkg.version === "string" && pkg.private !== true;
+  if (adopted) return { repo, status: "adopted", version: pkg?.version ?? null };
+  if (versioned) return { repo, status: "publishable", version: pkg.version };
+  return { repo, status: "na", reason: pkg == null ? "no package.json" : pkg.private ? "private" : "no version" };
+}
+
+// Paginate org repos.
+const repos = [];
+for (let page = 1; ; page++) {
+  const batch = await gh(`orgs/${org}/repos?per_page=100&page=${page}&sort=full_name`);
+  if (!batch?.length) break;
+  repos.push(...batch);
+  if (batch.length < 100) break;
+}
+
+// Probe in batches of 8.
+const probed = [];
+for (let i = 0; i < repos.length; i += 8) {
+  probed.push(...await Promise.all(repos.slice(i, i + 8).map((r) => probe(r.name))));
+}
+
+const adopted = probed.filter((r) => r.status === "adopted");
+const publishable = probed.filter((r) => r.status === "publishable");
+const na = probed.filter((r) => r.status === "na");
+const report = { org, scanned: repos.length, adopted, publishable, na };
+
+// --write: open a caller PR for every publishable-not-adopted repo.
+if (write) {
+  console.log(`\n  opening caller PRs for ${publishable.length} publishable repo(s) (mint @ ${MINT_REF.slice(0, 8)})\n`);
+  const opened = [];
+  for (const r of publishable) {
+    const pr = await openAdoptionPR(r.repo);
+    if (pr) opened.push(pr);
+  }
+  report.opened = opened;
+  console.log(`\n  opened ${opened.length}/${publishable.length} PR(s)`);
+}
+
+if (jsonOut) {
+  process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+} else {
+  const denom = adopted.length + publishable.length;
+  const pct = denom ? Math.round((adopted.length / denom) * 100) : 100;
+  console.log(`\n  mint adoption — ${org}: ${repos.length} repos scanned\n  ${"─".repeat(48)}`);
+  console.log(`  ADOPTED      ${adopted.length}`);
+  for (const r of adopted) console.log(`    ✓ ${r.repo}${r.version ? ` (${r.version})` : ""}`);
+  console.log(`\n  PUBLISHABLE — should adopt (${publishable.length})`);
+  for (const r of publishable) console.log(`    · ${r.repo} (${r.version})`);
+  console.log(`\n  N/A — not a versioned package (${na.length})`);
+  console.log(`\n  coverage: ${adopted.length}/${denom} versioned packages (${pct}%)\n`);
+}
+
+writeFileSync("adoption-report.json", JSON.stringify(report, null, 2));

package/intents.mjs

@@ -0,0 +1,52 @@
+// Intent files: `.release/*.md` — one per change, authored in the PR that makes
+// the change. Format is front-matter + summary body:
+//
+//   ---
+//   bump: minor
+//   ---
+//   scan: promote to a verb (CLI + MCP) + shared Zod type contracts
+//
+// Parsed and validated against the Zod `Intent` contract in plan.mjs. No YAML
+// dependency — the front matter is a minimal `key: value` block.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Intent } from "./plan.mjs";
+
+const FRONT_MATTER = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
+
+// Parse one intent file's text → validated { bump, summary }. Throws on a missing
+// front-matter block, unknown bump, or empty summary (fail closed — a malformed
+// intent must never silently drop from a release).
+export function parseIntent(text, label = "intent") {
+  const m = text.match(FRONT_MATTER);
+  if (!m) throw new Error(`${label}: missing front-matter block (--- bump: <kind> ---)`);
+  const fields = {};
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+    if (kv) fields[kv[1]] = kv[2].trim();
+  }
+  const summary = m[2].trim();
+  return Intent.parse({ bump: fields.bump, summary });
+}
+
+// Load every intent in a directory (default `.release/`), skipping README.md and
+// dot/underscore-prefixed templates. Returns [] when the directory is absent.
+export async function loadIntents(dir = ".release") {
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch (e) {
+    if (e.code === "ENOENT") return [];
+    throw e;
+  }
+  const files = names
+    .filter((n) => n.endsWith(".md"))
+    .filter((n) => n !== "README.md" && !n.startsWith("_") && !n.startsWith("."))
+    .sort();
+  const intents = [];
+  for (const f of files) {
+    const text = await readFile(join(dir, f), "utf8");
+    intents.push({ file: join(dir, f), ...parseIntent(text, f) });
+  }
+  return intents;
+}

package/jsr.json

@@ -0,0 +1,21 @@
+{
+  "name": "@bounded-systems/mint",
+  "version": "0.4.3",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "exports": {
+    ".": "./plan.mjs",
+    "./intents": "./intents.mjs",
+    "./release": "./release.mjs"
+  },
+  "publish": {
+    "include": [
+      "plan.mjs",
+      "intents.mjs",
+      "release.mjs",
+      "mint.mjs",
+      "README.md",
+      "CHANGELOG.md",
+      "jsr.json"
+    ]
+  }
+}

package/mint.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// mint — deterministic versioning CLI. Impurity (clock, filesystem, git) lives
+// here at the edge; plan.mjs stays a pure function.
+//
+//   mint plan    [--dir .release] [--date YYYY-MM-DD] [--json]   preview the next release
+//   mint version [--dir .release] [--date YYYY-MM-DD]            apply: bump manifest + CHANGELOG, consume intents
+//   mint release [--dry-run] [--no-push] [--no-attest]           cut the v<version> tag + emit release provenance
+//   mint attest  [--out <path>]                                  (re)emit the in-toto release Statement (CI signs it)
+//
+// A verbspec-typed CLI/MCP surface (mirroring string-audit's audit.mjs/mcp.mjs)
+// is a follow-up; this skeleton wires the verbs directly against the Zod core.
+import { readFile, writeFile, unlink } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { plan, changelogEntry } from "./plan.mjs";
+import { loadIntents } from "./intents.mjs";
+import { releaseStatement, statementDigest } from "./release.mjs";
+
+const git = (...a) => execFileSync("git", a, { encoding: "utf8" }).trim();
+const gitOk = (...a) => { try { execFileSync("git", a, { stdio: "ignore" }); return true; } catch { return false; } };
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const flag = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? (args[i + 1] ?? "") : null;
+};
+const has = (name) => args.includes(name);
+
+const today = () => new Date().toISOString().slice(0, 10); // wall-clock confined to the CLI edge
+const dir = flag("--dir") ?? ".release";
+const date = flag("--date") ?? today();
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function currentVersion() {
+  const pkg = await readJson("package.json");
+  if (!pkg.version) throw new Error("package.json has no version field");
+  return pkg.version;
+}
+
+async function cmdPlan() {
+  const intents = await loadIntents(dir);
+  const p = plan({ currentVersion: await currentVersion(), intents, date });
+  if (has("--json")) {
+    process.stdout.write(JSON.stringify(p, null, 2) + "\n");
+    return;
+  }
+  if (p.bump == null) {
+    console.log(`mint: no intents in ${dir}/ — nothing to release (stays ${p.currentVersion})`);
+    return;
+  }
+  console.log(`mint plan — ${p.currentVersion} → ${p.nextVersion}  (${p.bump}, ${intents.length} intent${intents.length !== 1 ? "s" : ""})\n`);
+  console.log(p.entry);
+}
+
+async function cmdVersion() {
+  const intents = await loadIntents(dir);
+  const p = plan({ currentVersion: await currentVersion(), intents, date });
+  if (p.bump == null) {
+    console.log(`mint: no intents in ${dir}/ — nothing to release`);
+    return;
+  }
+
+  // Bump the manifest (+ lockfile if present), preserving 2-space JSON.
+  const pkg = await readJson("package.json");
+  pkg.version = p.nextVersion;
+  await writeFile("package.json", JSON.stringify(pkg, null, 2) + "\n");
+  try {
+    const lock = await readJson("package-lock.json");
+    lock.version = p.nextVersion;
+    if (lock.packages?.[""]) lock.packages[""].version = p.nextVersion;
+    await writeFile("package-lock.json", JSON.stringify(lock, null, 2) + "\n");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  // Keep jsr.json in lockstep (JSR has its own manifest version).
+  try {
+    const jsr = await readJson("jsr.json");
+    jsr.version = p.nextVersion;
+    await writeFile("jsr.json", JSON.stringify(jsr, null, 2) + "\n");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+
+  // Prepend the entry to CHANGELOG.md (create with a header if absent).
+  let changelog = "";
+  try { changelog = await readFile("CHANGELOG.md", "utf8"); }
+  catch (e) { if (e.code !== "ENOENT") throw e; changelog = "# Changelog\n"; }
+  const head = changelog.startsWith("# ") ? changelog.slice(0, changelog.indexOf("\n") + 1) : "# Changelog\n";
+  const rest = changelog.slice(head.length).replace(/^\n+/, "");
+  await writeFile("CHANGELOG.md", `${head}\n${p.entry}\n${rest}`.replace(/\n{3,}/g, "\n\n"));
+
+  // Consume the intents.
+  for (const i of intents) if (i.file) await unlink(i.file);
+
+  console.log(`mint: ${p.currentVersion} → ${p.nextVersion} (${p.bump}). Updated package.json + CHANGELOG.md, consumed ${intents.length} intent(s).`);
+  console.log(`Next: commit, then \`mint release\` to cut the tag + emit release provenance.`);
+}
+
+// The GitHub Actions OIDC issuer enforced by the bounded-systems keyless flow.
+const OIDC_ISSUER = "https://token.actions.githubusercontent.com";
+
+// The CI signing identity, derived from the GitHub Actions environment. Returns
+// null outside CI (no GITHUB_REPOSITORY) — the statement is then UNSIGNED and the
+// release record carries `builder: null`. Mirrors the sites' provenance builder.
+function ciBuilder() {
+  const repository = process.env.GITHUB_REPOSITORY;
+  if (!repository) return null;
+  return {
+    repository,
+    commit: process.env.GITHUB_SHA ?? "",
+    ref: process.env.GITHUB_REF ?? "",
+    runId: process.env.GITHUB_RUN_ID ?? "",
+    workflowRef: process.env.GITHUB_WORKFLOW_REF ?? "",
+    issuer: OIDC_ISSUER,
+  };
+}
+
+// Assemble the in-toto release Statement from repo state. Impure at the edge
+// (reads package.json + CHANGELOG + git HEAD + CI env); delegates the pure shape
+// to release.mjs. Throws with a CLI-friendly message on a missing changelog entry.
+async function gatherStatement() {
+  const pkg = await readJson("package.json");
+  const version = pkg.version;
+  if (!version) throw new Error("package.json has no version");
+  const tag = `v${version}`;
+
+  let changelog = "";
+  try { changelog = await readFile("CHANGELOG.md", "utf8"); } catch { /* none */ }
+  const entry = changelogEntry(changelog, version);
+  if (!entry) throw new Error(`no CHANGELOG.md entry for ${version} — run \`mint version\` first.`);
+
+  const commit = git("rev-parse", "HEAD");
+  // Producer is mint itself, not the consumer package; pin a ref when CI sets one.
+  const producer = `@bounded-systems/mint${process.env.MINT_REF ? `@${process.env.MINT_REF}` : ""}`;
+  const stmt = releaseStatement({ version, tag, commit, date, changelog: entry, producer, builder: ciBuilder() });
+  return { stmt, tag, entry, version };
+}
+
+// (Re)emit the in-toto release Statement to stdout (or --out <path>). Pure +
+// deterministic for a given repo state; CI keyless-signs the emitted file with
+// cosign. Same record `mint release` writes — exposed on its own so release.yml
+// can regenerate it after the tag push and sign it.
+async function cmdAttest() {
+  const { stmt, tag } = await gatherStatement();
+  const text = JSON.stringify(stmt, null, 2) + "\n";
+  const out = flag("--out");
+  if (out) {
+    await writeFile(out, text);
+    console.error(`mint: wrote release statement for ${tag} → ${out} (${statementDigest(stmt).slice(0, 12)})`);
+  } else {
+    process.stdout.write(text);
+  }
+}
+
+// Cut the release tag AND emit its provenance. Signs the tag when git signing is
+// configured (else an annotated tag with a warning); the annotation is the
+// changelog entry. Alongside the tag it writes the in-toto release Statement
+// (tag → version plan → commit) to `<tag>.intoto.json` — UNSIGNED locally;
+// keyless-signed by release.yml in CI (cosign, OIDC). --dry-run previews without
+// touching git; --remote sets the push target (default origin); --no-push skips
+// pushing; --no-attest skips the provenance file; --attest <path> overrides it.
+async function cmdRelease() {
+  const dryRun = has("--dry-run");
+  const noPush = has("--no-push");
+  const noAttest = has("--no-attest");
+  const remote = flag("--remote") ?? "origin";
+
+  let gathered;
+  try { gathered = await gatherStatement(); }
+  catch (e) { console.error(`mint release: ${e.message}`); process.exit(1); }
+  const { stmt, tag, entry } = gathered;
+  const attestPath = flag("--attest") ?? `${tag}.intoto.json`;
+  const stmtText = JSON.stringify(stmt, null, 2) + "\n";
+  const signedStatement = stmt.predicate.builder != null; // CI ⇒ keyless-signed downstream
+  const signedTag = git("config", "--get", "commit.gpgsign") === "true" || gitOk("config", "--get", "user.signingkey");
+  const tagExists = gitOk("rev-parse", tag);
+  const dirty = git("status", "--porcelain");
+
+  // --dry-run is a pure preview: it never touches git, so the mutation guards
+  // (clean tree, tag absent) are surfaced as warnings instead of hard failures.
+  if (dryRun) {
+    console.log(`mint release (dry run): would create ${signedTag ? "signed" : "annotated"} tag ${tag} and ${noPush ? "skip push" : `push to ${remote}`}.`);
+    if (!noAttest) console.log(`mint release (dry run): would write release provenance → ${attestPath} (${statementDigest(stmt).slice(0, 12)}, ${signedStatement ? "CI keyless-signs it" : "unsigned — signing is CI-only"}).`);
+    if (tagExists) console.log(`mint release (dry run): note — tag ${tag} already exists; a real release would refuse.`);
+    if (dirty) console.log("mint release (dry run): note — working tree not clean; a real release would refuse.");
+    console.log("");
+    console.log(entry.trimEnd());
+    if (!noAttest) { console.log("\n--- in-toto release Statement (preview) ---"); process.stdout.write(stmtText); }
+    return;
+  }
+
+  // Guards for the real path: tag not already present, clean git tree.
+  if (tagExists) { console.error(`mint release: tag ${tag} already exists.`); process.exit(1); }
+  if (dirty) { console.error("mint release: working tree not clean — commit the release first."); process.exit(1); }
+
+  git("tag", signedTag ? "-s" : "-a", tag, "-m", entry);
+  console.log(`mint: created ${signedTag ? "signed" : "annotated (unsigned — no git signing key configured)"} tag ${tag}`);
+  if (!noAttest) {
+    await writeFile(attestPath, stmtText);
+    console.log(`mint: wrote release provenance → ${attestPath}${signedStatement ? "" : " (unsigned — keyless signing runs in CI)"}`);
+  }
+  if (!noPush) { git("push", remote, tag); console.log(`mint: pushed ${tag} to ${remote}`); }
+  console.log(`Next: release.yml keyless-signs the statement (cosign, OIDC) + attaches it to the GitHub release. Verify with \`cosign verify-blob\` / \`gh attestation verify\`.`);
+}
+
+const COMMANDS = { plan: cmdPlan, version: cmdVersion, release: cmdRelease, attest: cmdAttest };
+
+if (!cmd || cmd === "--help" || cmd === "-h" || !COMMANDS[cmd]) {
+  const known = Object.keys(COMMANDS).join(" | ");
+  console.log(`mint — deterministic versioning\n\n  mint <${known}> [--dir .release] [--date YYYY-MM-DD] [--json]\n`);
+  process.exit(cmd && !COMMANDS[cmd] ? 1 : 0);
+}
+
+await COMMANDS[cmd]();

package/mint.test.mjs

@@ -0,0 +1,179 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { plan, resolveBump, renderEntry, changelogEntry } from "./plan.mjs";
+import { parseIntent } from "./intents.mjs";
+import {
+  releaseStatement,
+  canonicalize,
+  dssePAE,
+  statementDigest,
+  STATEMENT_TYPE,
+  RELEASE_PREDICATE_TYPE,
+  DSSE_PAYLOAD_TYPE,
+} from "./release.mjs";
+
+const CHANGELOG = `# Changelog
+
+## 0.2.0 — 2026-06-24
+
+### Minor
+
+- mint release verb + SLSA release workflow
+
+## 0.1.0 — 2026-06-23
+
+### Minor
+
+- initial
+`;
+
+const date = "2026-06-23";
+
+test("bump precedence — the strongest intent wins", () => {
+  assert.equal(resolveBump([{ bump: "patch" }, { bump: "minor" }]), "minor");
+  assert.equal(resolveBump([{ bump: "minor" }, { bump: "major" }, { bump: "patch" }]), "major");
+  assert.equal(resolveBump([{ bump: "patch" }]), "patch");
+  assert.equal(resolveBump([]), null);
+});
+
+test("semver arithmetic is delegated correctly", () => {
+  assert.equal(plan({ currentVersion: "0.6.1", intents: [{ bump: "minor", summary: "x" }], date }).nextVersion, "0.7.0");
+  assert.equal(plan({ currentVersion: "0.6.1", intents: [{ bump: "patch", summary: "x" }], date }).nextVersion, "0.6.2");
+  assert.equal(plan({ currentVersion: "0.6.1", intents: [{ bump: "major", summary: "x" }], date }).nextVersion, "1.0.0");
+});
+
+test("no intents → no release (version unchanged, null bump)", () => {
+  const p = plan({ currentVersion: "1.2.3", intents: [], date });
+  assert.equal(p.bump, null);
+  assert.equal(p.nextVersion, "1.2.3");
+  assert.equal(p.entry, null);
+});
+
+test("plan is deterministic — same inputs, byte-identical output regardless of intent order", () => {
+  const intents = [
+    { bump: "patch", summary: "fix b" },
+    { bump: "minor", summary: "feat z" },
+    { bump: "patch", summary: "fix a" },
+    { bump: "minor", summary: "feat a" },
+  ];
+  const a = plan({ currentVersion: "0.6.1", intents, date });
+  const b = plan({ currentVersion: "0.6.1", intents: [...intents].reverse(), date });
+  assert.deepEqual(a.entry, b.entry);
+  assert.equal(a.nextVersion, b.nextVersion);
+  // grouped by kind (major→minor→patch), sorted within group:
+  assert.match(a.entry, /### Minor\n\n- feat a\n- feat z\n\n### Patch\n\n- fix a\n- fix b/);
+});
+
+test("changelog entry header carries version + injected date", () => {
+  const entry = renderEntry({ nextVersion: "0.7.0", date, intents: [{ bump: "minor", summary: "scan verb" }] });
+  assert.ok(entry.startsWith("## 0.7.0 — 2026-06-23\n"));
+});
+
+test("malformed input fails closed", () => {
+  assert.throws(() => plan({ currentVersion: "not-semver", intents: [], date }));
+  assert.throws(() => plan({ currentVersion: "1.0.0", intents: [{ bump: "huge", summary: "x" }], date }));
+  assert.throws(() => plan({ currentVersion: "1.0.0", intents: [{ bump: "minor", summary: "" }], date }));
+  assert.throws(() => plan({ currentVersion: "1.0.0", intents: [], date: "June 23" }));
+});
+
+test("changelogEntry extracts one version's section, not the next", () => {
+  const e = changelogEntry(CHANGELOG, "0.2.0");
+  assert.ok(e.startsWith("## 0.2.0 — 2026-06-24"));
+  assert.match(e, /mint release verb/);
+  assert.ok(!e.includes("0.1.0"), "must stop before the next heading");
+  const old = changelogEntry(CHANGELOG, "0.1.0");
+  assert.ok(old.startsWith("## 0.1.0"));
+  assert.match(old, /- initial/);
+  assert.equal(changelogEntry(CHANGELOG, "9.9.9"), null);
+});
+
+test("parseIntent reads front matter + summary, validates the contract", () => {
+  const i = parseIntent("---\nbump: minor\n---\nscan: promote to a verb\n");
+  assert.deepEqual(i, { bump: "minor", summary: "scan: promote to a verb" });
+  assert.throws(() => parseIntent("no front matter here"), /missing front-matter/);
+  assert.throws(() => parseIntent("---\nbump: minor\n---\n"), /summary/); // empty body
+});
+
+// ── mint release — provenance core (release.mjs) ────────────────────────────
+
+const REL = {
+  version: "0.3.0",
+  tag: "v0.3.0",
+  commit: "0123456789abcdef0123456789abcdef01234567",
+  date: "2026-06-29",
+  changelog: changelogEntry(CHANGELOG, "0.2.0"),
+  producer: "@bounded-systems/mint",
+};
+
+test("release statement binds tag → version plan → commit (in-toto Statement v1)", () => {
+  const s = releaseStatement(REL);
+  assert.equal(s._type, STATEMENT_TYPE);
+  assert.equal(s._type, "https://in-toto.io/Statement/v1");
+  assert.equal(s.predicateType, RELEASE_PREDICATE_TYPE);
+  // subject IS the tag, anchored to the commit (in-toto gitCommit digest).
+  assert.deepEqual(s.subject, [{ name: "v0.3.0", digest: { gitCommit: REL.commit } }]);
+  assert.equal(s.predicate.version, "0.3.0");
+  assert.equal(s.predicate.tag, "v0.3.0");
+  assert.equal(s.predicate.commit, REL.commit);
+  // the version plan is bound by the byte-exact changelog digest.
+  assert.equal(s.predicate.plan.changelog, REL.changelog);
+  assert.equal(
+    s.predicate.plan.digest.sha256,
+    createHash("sha256").update(REL.changelog, "utf8").digest("hex"),
+  );
+  // no builder ⇒ produced locally + unsigned.
+  assert.equal(s.predicate.builder, null);
+});
+
+test("release statement is deterministic — same inputs, byte-identical record", () => {
+  const a = releaseStatement(REL);
+  const b = releaseStatement({ ...REL });
+  assert.deepEqual(a, b);
+  assert.equal(canonicalize(a), canonicalize(b));
+  assert.equal(statementDigest(a), statementDigest(b));
+});
+
+test("canonicalize is key-order independent (stable digest + DSSE payload)", () => {
+  const a = canonicalize({ b: 1, a: { y: 2, x: 3 } });
+  const b = canonicalize({ a: { x: 3, y: 2 }, b: 1 });
+  assert.equal(a, b);
+  assert.equal(a, '{"a":{"x":3,"y":2},"b":1}');
+});
+
+test("CI builder is carried through (keyless signing identity)", () => {
+  const builder = {
+    repository: "bounded-systems/mint",
+    commit: REL.commit,
+    ref: "refs/tags/v0.3.0",
+    runId: "42",
+    workflowRef: "bounded-systems/mint/.github/workflows/release.yml@refs/tags/v0.3.0",
+    issuer: "https://token.actions.githubusercontent.com",
+  };
+  const s = releaseStatement({ ...REL, builder });
+  assert.deepEqual(s.predicate.builder, builder);
+  // local (null builder) and CI (builder) records differ — signing is recorded.
+  assert.notEqual(statementDigest(s), statementDigest(releaseStatement(REL)));
+});
+
+test("tag format is enforced — only v<semver> is accepted", () => {
+  assert.throws(() => releaseStatement({ ...REL, tag: "0.3.0" }), /tag must be v<semver>/);
+  assert.throws(() => releaseStatement({ ...REL, tag: "release-0.3.0" }), /tag must be v<semver>/);
+  assert.throws(() => releaseStatement({ ...REL, tag: "v0.3" }), /tag must be v<semver>/);
+  // prerelease + build metadata are valid semver tags.
+  assert.equal(releaseStatement({ ...REL, tag: "v0.3.0-rc.1" }).predicate.tag, "v0.3.0-rc.1");
+});
+
+test("release statement fails closed on malformed input", () => {
+  assert.throws(() => releaseStatement({ ...REL, commit: "nothex!" }), /git object id/);
+  assert.throws(() => releaseStatement({ ...REL, date: "June 29" }), /YYYY-MM-DD/);
+  assert.throws(() => releaseStatement({ ...REL, changelog: "" }), /changelog/);
+});
+
+test("DSSE pre-authentication encoding wraps the canonical statement", () => {
+  const s = releaseStatement(REL);
+  const pae = dssePAE(s).toString("utf8");
+  const payload = canonicalize(s);
+  assert.ok(pae.startsWith(`DSSEv1 ${DSSE_PAYLOAD_TYPE.length} ${DSSE_PAYLOAD_TYPE} ${Buffer.byteLength(payload)} `));
+  assert.ok(pae.endsWith(payload));
+});