@supersuit/hyperspec 0.1.0 → 0.2.0

package/bin/hyperspec.mjs

@@ -4,6 +4,11 @@ import { loadSpec } from "../src/load.mjs";
 import { lintSpec } from "../src/rules.mjs";
 import { score, exitCode } from "../src/score.mjs";
 import { template } from "../src/template.mjs";
+import { readRecipe, checkRecipe } from "../src/recipe.mjs";
+import { approve } from "../src/writer.mjs";
+import { reproduce } from "../src/reproduce.mjs";
+import { regenerate } from "../src/regenerate.mjs";
+import { compare } from "../src/compare.mjs";
 
 const HELP = `hyperspec <command> [options]
 
@@ -11,6 +16,29 @@ const HELP = `hyperspec <command> [options]
                                exit 0 pass, 1 a test fails, 3 blocked on an open decision, 2 usage
   init <file> [--title T] [--kind K]   write a new hyperspec skeleton (refuses to overwrite)
 
+  recipe check <output-or-recipe> [--json]
+                               check a recipe's completeness (a path not ending .recipe.json
+                               means <path>.recipe.json)
+                               exit 0 ok (warns only), 1 no recipe found or a check failed,
+                               2 unreadable/invalid recipe JSON
+  recipe approve <recipe> --by <slug> [--json]
+                               set the recipe's approver, print remaining findings
+                               exit 0 once --by and the recipe are valid, 2 missing --by or
+                               unreadable recipe
+  reproduce <recipe> [--restore] [--store d] [--json]
+                               replay a recipe's hash checks against the blob store; never
+                               runs a model
+                               exit 0 reproduces cleanly, 1 a check failed, 2 unreadable recipe
+  regenerate <recipe> --out <path> --clicker <slug>
+             (--add-input n=p [--reads id]... | --swap-input n=p | --factory-version v)
+             [--run cmd] [--change text] [--store d] [--json]
+                               make a child recipe from a parent plus exactly one change
+                               exit 0 ok, 1 a stage failed or the child has failing verdicts,
+                               2 usage, 3 pending a runner
+  compare <child-recipe> --doctor cmd [--parent r] [--spec s] [--json]
+                               grade a child and its parent through one doctor against one spec
+                               exit 0 not regressed, 1 regressed, 2 usage or unreadable input
+
 Spec: SPEC.md`;
 
 const argv = process.argv.slice(2);
@@ -57,5 +85,254 @@ if (cmd === "lint") {
   process.exit(worst);
 }
 
+// Generic flag/positional parser for the recipe verbs below. A value-taking flag (valueFlags,
+// repeatableFlags) never swallows a following --flag as its value (missing value is an error, not
+// a silent grab); a bool flag never eats the next token as a positional; any --flag not declared
+// for this verb is an error. This is the same discipline lint's own hand-rolled parser follows
+// above (a stray flag never swallows a file), generalized once repeated-flag verbs (regenerate's
+// --reads) and value flags (--out, --by, --doctor, ...) showed up.
+function parseArgs(args, { valueFlags = [], boolFlags = [], repeatableFlags = [] } = {}) {
+  const positionals = [];
+  const values = {};
+  for (const f of boolFlags) values[f] = false;
+  for (const f of repeatableFlags) values[f] = [];
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      if (repeatableFlags.includes(a)) {
+        const v = args[i + 1];
+        if (v === undefined || v.startsWith("--")) return { error: `${a} needs a value` };
+        values[a].push(v);
+        i += 2;
+        continue;
+      }
+      if (valueFlags.includes(a)) {
+        const v = args[i + 1];
+        if (v === undefined || v.startsWith("--")) return { error: `${a} needs a value` };
+        values[a] = v;
+        i += 2;
+        continue;
+      }
+      if (boolFlags.includes(a)) { values[a] = true; i += 1; continue; }
+      return { error: `unknown flag: ${a}` };
+    }
+    positionals.push(a);
+    i += 1;
+  }
+  return { positionals, values };
+}
+
+// name=path, split on the FIRST =, so a path that itself contains = survives intact. A value with
+// no = is a usage error (exit 2).
+function namePath(flagName, raw) {
+  const eq = raw.indexOf("=");
+  if (eq === -1) { console.error(`${flagName} needs name=path`); process.exit(2); }
+  return { name: raw.slice(0, eq), path: raw.slice(eq + 1) };
+}
+
+function printFindings(findings) {
+  if (!findings.length) { console.log("ok"); return; }
+  for (const f of findings) console.log(`${f.severity === "fail" ? "fail" : "warn"} [${f.field}] ${f.message}`);
+}
+
+function printPlan(plan) {
+  for (const p of plan ?? []) console.log(`  ${p.id}: ${p.action}${p.reason ? ` (${p.reason})` : ""}`);
+}
+
+if (cmd === "recipe") {
+  const sub = argv[1];
+
+  if (sub === "check") {
+    const parsed = parseArgs(argv.slice(2), { boolFlags: ["--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [target] = parsed.positionals;
+    const json = parsed.values["--json"];
+    if (!target) { console.error("recipe check needs a recipe or output path"); process.exit(2); }
+    const recipePath = target.endsWith(".recipe.json") ? target : `${target}.recipe.json`;
+
+    if (!existsSync(recipePath)) {
+      const msg = `no recipe beside ${target}`;
+      if (json) console.log(JSON.stringify({ recipe: recipePath, error: msg }, null, 2));
+      else console.error(msg);
+      process.exit(1);
+    }
+
+    const loaded = readRecipe(recipePath);
+    if (loaded.error) {
+      if (json) console.log(JSON.stringify({ recipe: recipePath, error: loaded.error }, null, 2));
+      else console.error(loaded.error);
+      process.exit(2);
+    }
+
+    const findings = checkRecipe(loaded.data);
+    const hasFail = findings.some((f) => f.severity === "fail");
+    if (json) console.log(JSON.stringify({ recipe: recipePath, findings }, null, 2));
+    else { console.log(`${recipePath}:`); printFindings(findings); }
+    process.exit(hasFail ? 1 : 0);
+  }
+
+  if (sub === "approve") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--by"], boolFlags: ["--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [recipePath] = parsed.positionals;
+    const json = parsed.values["--json"];
+    if (!recipePath) { console.error("recipe approve needs a recipe path"); process.exit(2); }
+    if (!parsed.values["--by"]) { console.error("recipe approve needs --by <slug>"); process.exit(2); }
+
+    let findings;
+    try {
+      findings = approve(recipePath, parsed.values["--by"]);
+    } catch (e) {
+      if (json) console.log(JSON.stringify({ recipe: recipePath, error: e.message }, null, 2));
+      else console.error(e.message);
+      process.exit(2);
+    }
+
+    if (json) console.log(JSON.stringify({ recipe: recipePath, approver: parsed.values["--by"], findings }, null, 2));
+    else { console.log(`${recipePath}: approver set to ${parsed.values["--by"]}`); printFindings(findings); }
+    process.exit(0);
+  }
+
+  console.error(`unknown recipe subcommand: ${sub}\n\n${HELP}`);
+  process.exit(2);
+}
+
+if (cmd === "reproduce") {
+  const parsed = parseArgs(argv.slice(1), { valueFlags: ["--store"], boolFlags: ["--restore", "--json"] });
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [recipePath] = parsed.positionals;
+  const json = parsed.values["--json"];
+  if (!recipePath) { console.error("reproduce needs a recipe path"); process.exit(2); }
+
+  const result = reproduce(recipePath, { store: parsed.values["--store"], restore: parsed.values["--restore"] });
+  if (json) console.log(JSON.stringify(result, null, 2));
+
+  if (result.error) {
+    if (!json) console.error(result.error);
+    process.exit(2);
+  }
+  if (!result.ok) {
+    if (!json) {
+      console.error(`first mismatch: ${result.firstMismatch}`);
+      for (const step of result.steps) console.log(`  ${step.ok ? "ok  " : "FAIL"} ${step.ref}${step.why ? `: ${step.why}` : ""}`);
+      if (result.restored) console.log("restored the output file from its blob");
+    }
+    process.exit(1);
+  }
+  if (!json) {
+    for (const step of result.steps) console.log(`  ok   ${step.ref}`);
+    if (result.restored) console.log("restored the output file from its blob");
+    console.log("reproduces cleanly");
+  }
+  process.exit(0);
+}
+
+if (cmd === "regenerate") {
+  const parsed = parseArgs(argv.slice(1), {
+    valueFlags: ["--out", "--clicker", "--add-input", "--swap-input", "--factory-version", "--run", "--change", "--store"],
+    boolFlags: ["--json"],
+    repeatableFlags: ["--reads"],
+  });
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [recipePath] = parsed.positionals;
+  const json = parsed.values["--json"];
+  if (!recipePath) { console.error("regenerate needs a parent recipe path"); process.exit(2); }
+  if (parsed.values["--reads"].length && parsed.values["--add-input"] === undefined) {
+    console.error("--reads is only valid with --add-input");
+    process.exit(2);
+  }
+
+  const change = {};
+  if (parsed.values["--add-input"] !== undefined) {
+    const pair = namePath("--add-input", parsed.values["--add-input"]);
+    change.addInput = { ...pair, reads: parsed.values["--reads"] };
+  }
+  if (parsed.values["--swap-input"] !== undefined) {
+    change.swapInput = namePath("--swap-input", parsed.values["--swap-input"]);
+  }
+  if (parsed.values["--factory-version"] !== undefined) change.factoryVersion = parsed.values["--factory-version"];
+
+  const result = regenerate(recipePath, {
+    out: parsed.values["--out"],
+    clicker: parsed.values["--clicker"],
+    change,
+    run: parsed.values["--run"],
+    changeText: parsed.values["--change"],
+    store: parsed.values["--store"],
+  });
+  if (json) console.log(JSON.stringify(result, null, 2));
+
+  if (result.usage) {
+    if (!json) console.error(result.error);
+    process.exit(2);
+  }
+  if (!result.ok) {
+    if (!json) {
+      console.error(result.failedStage ? `stage ${result.failedStage} failed: ${result.error}` : result.error);
+      if (result.plan?.length) printPlan(result.plan);
+    }
+    process.exit(1);
+  }
+  if (result.pending) {
+    if (!json) {
+      const waiting = result.plan.filter((p) => p.action === "rerun").map((p) => p.id);
+      console.log(`pending; stages waiting for a runner: ${waiting.join(", ") || "(none)"}`);
+      printPlan(result.plan);
+      console.log(`child recipe: ${result.childRecipe}`);
+      console.log("a pending child cannot be finished in place yet; to produce the output, rerun regenerate on the parent with --run <command> and a new --out");
+    }
+    process.exit(3);
+  }
+  if (result.failedVerdicts?.length) {
+    if (!json) {
+      console.log(`child written despite failing verdict(s): ${result.failedVerdicts.join(", ")}`);
+      printPlan(result.plan);
+      console.log(`child recipe: ${result.childRecipe}`);
+      console.log(`output: ${result.output}`);
+    }
+    process.exit(1);
+  }
+  if (!json) {
+    printPlan(result.plan);
+    console.log(`child recipe: ${result.childRecipe}`);
+    console.log(`output: ${result.output}`);
+  }
+  process.exit(0);
+}
+
+if (cmd === "compare") {
+  const parsed = parseArgs(argv.slice(1), { valueFlags: ["--doctor", "--parent", "--spec"], boolFlags: ["--json"] });
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [childRecipePath] = parsed.positionals;
+  const json = parsed.values["--json"];
+  if (!childRecipePath) { console.error("compare needs a child recipe path"); process.exit(2); }
+
+  const result = compare(childRecipePath, {
+    doctor: parsed.values["--doctor"],
+    parent: parsed.values["--parent"],
+    spec: parsed.values["--spec"],
+  });
+  if (json) console.log(JSON.stringify(result, null, 2));
+
+  // Both a usage error and a check-failed error (missing output, escaping path, ...) map to
+  // 2 here — compare's own ok:false without a usage flag is still "could not grade", i.e. an
+  // unreadable-input class failure, not a graded-but-worse-1 class one.
+  if (!result.ok) {
+    if (!json) console.error(result.error);
+    process.exit(2);
+  }
+  if (!json) {
+    for (const w of result.warnings) console.log(`warn: ${w}`);
+    if (result.ledger) console.log(`ledger: ${result.ledger}`);
+  }
+  if (result.regressed) {
+    if (!json) console.log(`regression: child scored ${result.child.score} vs parent ${result.parent.score}; suspect: ${result.suspect ?? "unknown"}`);
+    process.exit(1);
+  }
+  if (!json) console.log(`child scored ${result.child.score} vs parent ${result.parent.score} (delta ${result.delta})`);
+  process.exit(0);
+}
+
 console.error(`unknown command: ${cmd}\n\n${HELP}`);
 process.exit(2);

package/examples/recipe/doctor.mjs

@@ -0,0 +1,11 @@
+// The doctor `hyperspec compare --doctor "node doctor.mjs"` runs once on the parent's output and
+// once on the child's, with the same spec. stdin: { output, spec }, both absolute paths. The last
+// stdout line is { "score": <number>, "notes": "..." }. This one scores an essay by how many
+// claims it carries.
+import { readFileSync } from "node:fs";
+
+const { output } = JSON.parse(readFileSync(0, "utf8"));
+const essay = readFileSync(output, "utf8");
+const section = essay.split("## Claims")[1]?.split("## ")[0] ?? "";
+const score = section.split("\n").filter((line) => line.startsWith("- ")).length;
+console.log(JSON.stringify({ score, notes: `${score} claims` }));

package/examples/recipe/essay.hyperspec.md

@@ -0,0 +1,50 @@
+---
+hyperspec: "0.1"
+title: What a recipe is for
+kind: essay
+decisions:
+  - id: audience
+    state: decided
+    value: someone who has never rerun a piece of work from its inputs
+    source: materials/notes.md
+    author: example-author
+    chosen_by: human
+  - id: shape
+    state: decided
+    value: the claims from the calls first, then the terms they lean on
+    source: stages.mjs
+    author: example-author
+    chosen_by: human
+requirements:
+  - id: every-claim-spoken
+    text: every claim is a line someone said on a call
+    fails_when: the essay carries a claim that no call transcript contains
+    check:
+      station: stages.mjs claims() copies lines from the calls and never writes one
+    source: materials/call.md
+    author: example-author
+  - id: more-claims-score-higher
+    text: an essay built from more calls carries more claims
+    fails_when: compare scores an essay with an added call no higher than its parent
+    check:
+      rubric: doctor.mjs counts the bullets under the Claims heading
+    source: doctor.mjs
+    author: example-author
+rejects:
+  - a claim nobody said on a call
+examples:
+  - path: materials/call.md
+    why: the raw call every claim is copied from, word for word
+resume:
+  next_action: add the next call with hyperspec regenerate --add-input, then compare the two essays
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: runs.jsonl
+---
+
+# What a recipe is for
+
+The example spec for `examples/recipe/`. The factory builds a short essay from call transcripts
+and a set of notes, and writes a recipe beside it.

package/examples/recipe/factory.mjs

@@ -0,0 +1,29 @@
+// The example factory: two inputs, three stages, and a recipe written beside the output.
+// Run it with `node factory.mjs`. It writes essay.md and essay.md.recipe.json next to itself.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { startRecipe } from "@supersuit/hyperspec/recipe";
+import { claims, draft, terms, verdict } from "./stages.mjs";
+
+const here = (p) => fileURLToPath(new URL(p, import.meta.url));
+const read = (p) => readFileSync(here(p), "utf8");
+
+const recipe = startRecipe({
+  output: here("essay.md"),
+  factory: { name: "example-essay", version: "1.0.0" },
+  spec: here("essay.hyperspec.md"),
+  clicker: "you",
+});
+recipe.input("call", here("materials/call.md"));
+recipe.input("notes", here("materials/notes.md"));
+
+const c = claims([read("materials/call.md")]);
+recipe.stage({ id: "claims", reads: ["input:call"], output: c, verdict: verdict("claims", c) });
+const t = terms([read("materials/notes.md")]);
+recipe.stage({ id: "terms", reads: ["input:notes"], output: t, verdict: verdict("terms", t) });
+const d = draft(c, t);
+recipe.stage({ id: "draft", reads: ["stage:claims", "stage:terms"], output: d, verdict: verdict("draft", d) });
+
+const { findings } = recipe.finish();
+console.log("wrote essay.md and essay.md.recipe.json");
+for (const f of findings) console.log(`${f.severity} [${f.field}] ${f.message}`);

package/examples/recipe/materials/call-2.md

@@ -0,0 +1,2 @@
+Ana: A recipe you cannot rerun is a receipt.
+Sam: So the second call goes in as one more input, and only the claims change.

package/examples/recipe/materials/call.md

@@ -0,0 +1,3 @@
+Maya: The recipe is the part people skip.
+Sam: Because writing it down feels like overhead.
+Maya: It stops being overhead the day you have to redo the work.

package/examples/recipe/materials/notes.md

@@ -0,0 +1,3 @@
+stage: one step of a factory, keyed by everything it read
+blob: the exact bytes of an input, stored by their hash
+recipe: the record of what made an output, from what, and who approved it

package/examples/recipe/runner.mjs

@@ -0,0 +1,20 @@
+// The runner `hyperspec regenerate --run "node runner.mjs"` calls once per stage it must rerun.
+// stdin: { stage, reads: [{ ref, sha256, path }], model }. Each read is a temp file holding the
+// exact bytes that ref resolved to. stdout: the stage's output, byte for byte. The last stderr
+// line starting "VERDICT " is the stage's verdict. A runner that prints none fails the stage:
+// silence is not a verdict.
+import { readFileSync } from "node:fs";
+import { claims, draft, terms, verdict } from "./stages.mjs";
+
+const job = JSON.parse(readFileSync(0, "utf8"));
+const text = (ref) => readFileSync(job.reads.find((r) => r.ref === ref).path, "utf8");
+const inputs = () => job.reads.filter((r) => r.ref.startsWith("input:")).map((r) => readFileSync(r.path, "utf8"));
+
+let output;
+if (job.stage === "claims") output = claims(inputs());
+else if (job.stage === "terms") output = terms(inputs());
+else if (job.stage === "draft") output = draft(text("stage:claims"), text("stage:terms"));
+else { console.error(`runner.mjs does not know stage ${job.stage}`); process.exit(2); }
+
+process.stdout.write(output);
+console.error(`VERDICT ${JSON.stringify(verdict(job.stage, output))}`);

package/examples/recipe/stages.mjs

@@ -0,0 +1,31 @@
+// The three stages of the example factory. Each is a plain text transform with no model in it,
+// so the same inputs always give the same bytes. factory.mjs runs them the first time;
+// runner.mjs runs them again when `hyperspec regenerate --run` asks for a stage.
+
+// claims: every line spoken on a call, without the speaker's name, as a bullet.
+export function claims(calls) {
+  const lines = calls.flatMap((text) => text.split("\n"))
+    .map((line) => line.replace(/^[^:]+:\s*/, "").trim())
+    .filter(Boolean);
+  return lines.map((line) => `- ${line}`).join("\n") + "\n";
+}
+
+// terms: every "term: definition" line in the notes, sorted by term.
+export function terms(notes) {
+  const lines = notes.flatMap((text) => text.split("\n")).filter((line) => line.includes(":"));
+  return lines
+    .map((line) => { const i = line.indexOf(":"); return [line.slice(0, i).trim(), line.slice(i + 1).trim()]; })
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([term, meaning]) => `- **${term}**: ${meaning}`)
+    .join("\n") + "\n";
+}
+
+// draft: the essay, built from the two earlier stages.
+export function draft(claimsText, termsText) {
+  return `# What a recipe is for\n\n## Claims\n\n${claimsText}\n## Terms\n\n${termsText}`;
+}
+
+// The verdict each stage reports: a stage that produced nothing fails.
+export function verdict(stage, output) {
+  return { station: `${stage}-not-empty`, pass: output.trim().length > 0, note: "" };
+}

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "@supersuit/hyperspec",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A hyperspec is a spec written for an agent: every decision accounted for, every requirement failable and checked, every field traced. The standard and its linter.",
   "type": "module",
   "bin": {
     "hyperspec": "bin/hyperspec.mjs"
   },
+  "exports": {
+    "./recipe": "./src/writer.mjs",
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin/",
     "src/",
     "examples/",
     "SPEC.md",
+    "runs.jsonl",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/src/blobs.mjs

@@ -0,0 +1,77 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { sha256 } from "./hash.mjs";
+
+// Resolve the store root: the --store flag, then HYPERSPEC_STORE, then the
+// nearest ancestor of `from` holding .hyperspec/ or .git, else from's own
+// directory. `from` is normally the recipe's directory, but a file path
+// works too (we walk up from its dirname).
+export function storeRoot({ from, store } = {}) {
+  if (store) return resolve(store);
+  if (process.env.HYPERSPEC_STORE) return resolve(process.env.HYPERSPEC_STORE);
+  let dir = resolve(from);
+  try { if (statSync(dir).isFile()) dir = dirname(dir); } catch { /* from may not exist yet; treat it as a directory */ }
+  let cur = dir;
+  while (true) {
+    if (existsSync(join(cur, ".hyperspec")) || existsSync(join(cur, ".git"))) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) return dir; // hit the filesystem root: fall back to the starting directory
+    cur = parent;
+  }
+}
+
+// A hash read from a recipe is a claim, and it becomes part of a filesystem path here. Anything
+// but exactly 64 lowercase hex characters is refused before it touches the disk, so a crafted
+// recipe cannot point a read at `../../somewhere`, a device, or a pipe that never closes.
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+export function isSha256(hex) {
+  return typeof hex === "string" && SHA256_HEX.test(hex);
+}
+
+export function blobPath(root, hex) {
+  if (!isSha256(hex)) {
+    const shown = typeof hex === "string" ? JSON.stringify(hex.length > 80 ? `${hex.slice(0, 80)}...` : hex) : String(hex);
+    throw new Error(`not a SHA-256 hash (64 lowercase hex characters): ${shown}`);
+  }
+  return join(root, ".hyperspec", "blobs", hex.slice(0, 2), hex);
+}
+
+// Writes only if the blob is absent; an existing blob is left untouched (never rewritten).
+// Atomic: bytes land in a temp file in the same directory first, then a single renameSync
+// (atomic on one filesystem) puts them at the final path. A process killed mid-write leaves
+// only the orphaned temp file, never a partially-written file sitting at the content-addressed
+// path — the failure mode a plain writeFileSync(path, bytes) would otherwise leave behind, and
+// which nothing short of an explicit verifyBlob would ever catch afterward.
+export function putBlob(root, bytes) {
+  const hex = sha256(bytes);
+  const path = blobPath(root, hex);
+  if (existsSync(path)) return hex;
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+  try {
+    writeFileSync(tmp, bytes);
+    if (existsSync(path)) { unlinkSync(tmp); return hex; } // another writer won the race; keep theirs
+    renameSync(tmp, path);
+  } catch (e) {
+    try { unlinkSync(tmp); } catch { /* nothing to clean up */ }
+    throw e;
+  }
+  return hex;
+}
+
+// A malformed hash names no blob, so hasBlob, getBlob and verifyBlob treat it as missing.
+export function hasBlob(root, hex) {
+  return isSha256(hex) && existsSync(blobPath(root, hex));
+}
+
+export function getBlob(root, hex) {
+  if (!isSha256(hex)) return null;
+  try { return readFileSync(blobPath(root, hex)); } catch { return null; }
+}
+
+// True when the blob exists and its bytes re-hash to hex (catches tampering).
+export function verifyBlob(root, hex) {
+  const bytes = getBlob(root, hex);
+  return bytes !== null && sha256(bytes) === hex;
+}