@supersuit/hyperspec 0.1.0 → 0.3.0

package/examples/writing/essay.hyperspec.md

@@ -0,0 +1,217 @@
+---
+hyperspec: "0.1"
+title: Hand your first one-on-one to the person you manage
+kind: essay
+profile: writing
+decisions:
+  - id: kind
+    state: decided
+    value: an essay of 700 to 1,100 words for a newsletter read by people in their first year of managing
+    source: essay/materials/voice-memo.md
+    author: example-author
+    chosen_by: human
+  - id: agenda-card
+    state: decided
+    value: the essay ends on the three questions, written so a reader can copy them onto a card
+    source: essay/materials/voice-memo.md, the three questions
+    author: example-author
+    chosen_by: human
+  - id: publish-venue
+    state: delegated
+    rule: publish where the audience block's reads_on line says the reader already is, and nowhere else
+    source: publishing checklist
+    author: agent:claude
+    chosen_by: agent
+requirements:
+  - id: r1
+    text: the opening line tells the reader who sets the agenda of a first one-on-one
+    fails_when: a reader shown only the first two sentences cannot say who should set the agenda
+    check:
+      rubric: show the simulated reader the first two sentences and ask who sets the agenda; pass only on "the report"
+    source: essay/goldens/opening.md
+    author: example-author
+  - id: r2
+    text: the three questions appear word for word as the voice memo states them
+    fails_when: any of the three questions differs from essay/materials/voice-memo.md by a word
+    check:
+      station: verbatim match of each question against the voice memo
+    source: essay/materials/voice-memo.md
+    author: example-author
+  - id: r3
+    text: every survey figure in the draft matches the verified survey summary
+    fails_when: a figure in the draft has no entry in the claims ledger pointing at essay/materials/team-survey.md, or differs from it
+    check:
+      station: every factual claim in the ledger points at a source span
+    source: sourcing pass
+    author: agent:claude
+  - id: r4
+    text: the draft argues only the four claims in the spine, in order
+    fails_when: a paragraph advances a point that traces to none of c1 to c4, or c3 lands before c2
+    check:
+      rubric: map each paragraph to a spine claim; fail on any paragraph that maps to none or out of order
+    source: spine interview
+    author: example-author
+  - id: r5
+    text: the draft tells the reader what to do with silence in the meeting
+    fails_when: the draft never says to wait after asking a question
+    check:
+      rubric: ask the simulated reader what to do after asking the first question; pass only on "wait"
+    source: essay/materials/interview-notes.md
+    author: example-author
+  - id: r6
+    text: the draft stays inside its length envelope
+    fails_when: the word count is under 700 or over 1,100
+    check:
+      station: word count against form.length
+    source: form decision
+    author: example-author
+rejects:
+  - a list of more than three questions
+  - advice to use the one-on-one for project status
+  - any claim about what most managers do that the survey does not support
+  - the walking one-on-one aside from the voice memo
+examples:
+  - path: essay/goldens/opening.md
+    why: the claim lands in the first sentence, and the second sentence turns it into an instruction
+resume:
+  next_action: mark the three materials into labeled segments, then outline the four spine claims against the form's required parts
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: essay/runs.jsonl
+writing:
+  materials:
+    items:
+      - id: voice-memo
+        path: essay/materials/voice-memo.md
+        produced_by: example-author
+        captured: "2026-09-12"
+        how: voice memo, transcribed
+        trust: raw
+      - id: interview
+        path: essay/materials/interview-notes.md
+        produced_by: example-author
+        captured: "2026-09-15"
+        how: notes taken during a call, reviewed by the person interviewed
+        trust: considered
+      - id: survey
+        path: essay/materials/team-survey.md
+        produced_by: example-author
+        captured: "2026-05-30"
+        how: survey summary, figures checked against the raw export by a second person
+        trust: verified
+    check:
+      station: every segment of every material carries a label from the closed set
+    source: capture step
+    author: agent:claude
+  dna:
+    writer: example-author
+    scope:
+      form: essay
+      audience: new managers
+      purpose: teach
+    rules: style-rules.md
+    goldens:
+      - path: essay/goldens/opening.md
+        why: one plain claim, then a second sentence that turns it into something to do
+      - path: essay/goldens/close.md
+        why: ends on an instruction and gives the reason for it in the same sentence
+    check:
+      rubric: blind lineup within this scope; a judge shown the generated opening beside the two goldens cannot pick it out
+    source: goldens marked on the review page
+    author: example-author
+  persona:
+    identity: self
+    stance: mentor
+    may_assert:
+      - what the author did in their own first one-on-ones and what happened
+      - the three questions the author uses now
+    will_not_say:
+      - a claim about what most managers do, beyond the survey's own figures
+      - the name of anyone on the author's team
+    facts_from: sources
+    check:
+      rubric: persona-consistency judge; the mentor stance holds, and no fact appears that is not in the claims ledger
+    source: persona interview
+    author: example-author
+  audience:
+    who: someone in their first three months of managing, who was promoted from the team they now lead
+    funnel_now: has a first one-on-one with a new report on the calendar this week
+    knows:
+      - one-on-one
+      - report
+      - tracker
+    believes_now: a one-on-one is where a manager catches up on how the work is going
+    wants: a plan for the first meeting that will not waste either person's half hour
+    reads_on: a phone, in the ten minutes before the meeting
+    reader: person
+    check:
+      station: term check against knows; any other term is defined on first use
+      rubric: simulated reader reports where it got lost and where it stopped reading
+    source: audience interview
+    author: example-author
+  goal:
+    from: plans to run the first one-on-one from their own list
+    to: hands the first one-on-one to the report and asks the three questions
+    next_if_worked: copies the three questions into their calendar invite
+    change:
+      kind: action
+      text: the reader asks the three questions in their next one-on-one and waits after each
+    conditions: [r1, r2, r3, r4, r5, r6]
+    check:
+      rubric: the doctor grades the draft against every condition; the simulated reader is asked whether it would copy the questions now
+    source: goal interview
+    author: example-author
+  form:
+    name: essay
+    length:
+      min: 700
+      max: 1100
+      unit: words
+    required_parts:
+      - an opening that states the claim
+      - the story of the author's first one-on-one
+      - the three questions
+      - what to do with the answers
+      - a close the reader can act on
+    stations:
+      - the three questions render as a numbered list
+    check:
+      station: structure and length check against required_parts and length
+    source: form decision
+    author: example-author
+  spine:
+    kind: primer
+    claims:
+      - id: c1
+        text: the first one-on-one is the one meeting where the report should set the agenda
+        materials: [voice-memo, interview]
+      - id: c2
+        text: status belongs in the tracker, and a one-on-one spent on it teaches the manager nothing new
+        materials: [voice-memo, survey]
+      - id: c3
+        text: three questions are enough to hand the meeting over
+        materials: [voice-memo]
+      - id: c4
+        text: the answer worth having comes after a silence the manager does not fill
+        materials: [interview]
+    check:
+      rubric: each claim lands, in order, and the draft argues nothing outside the chain
+    source: spine interview
+    author: example-author
+  sources:
+    ledger: essay/claims.jsonl
+    unsourced_claim: fail
+    check:
+      station: every factual claim in the ledger points at a source span; every quote matches its source verbatim
+    source: sourcing pass
+    author: agent:claude
+fiction: false
+---
+
+# Hand your first one-on-one to the person you manage
+
+A worked example of the writing profile: an essay for new managers, specified before a word of
+it is drafted. Every file this spec names ships beside it. `essay/claims.jsonl` does not exist
+yet, because the claims ledger is written during drafting.

package/examples/writing/story/goldens/dialogue.md

@@ -0,0 +1,3 @@
+"You're late," she said. I wasn't. She knew I wasn't.
+"The bus," I said anyway, because that is how we start.
+"Flour first. Then you can talk."

package/examples/writing/story/goldens/opening.md

@@ -0,0 +1,3 @@
+The alarm at the bakery goes at 3:20, but Ines is always there first, so I have never once
+heard it. What I hear is the mixer. It has a knock in it, a slow one, like it is trying to
+remember something.

package/examples/writing/story/materials/bakery-visit.md

@@ -0,0 +1,8 @@
+Notes from a morning spent at a working bakery, 3:30 to 7:30, with the owner's permission.
+Considered: the owner read these notes and corrected the proofing times.
+
+- First mix at 3:45. Rye sourdough proofs about three hours at room temperature in winter.
+- Trays are turned halfway through the bake because the back left of a deck oven runs hot.
+- The doors open to customers at 7:00. The first person in is usually a regular.
+- The owner does not talk while shaping. Talking happens at the mixer and at the till.
+- Flour is weighed, never scooped. Water temperature is checked every batch.

package/examples/writing/story/materials/notes.md

@@ -0,0 +1,14 @@
+Author's notes for the story, typed over two evenings. Raw thinking.
+
+A bakery on its last morning before the sale closes. Two people: the owner, who has run it for
+thirty-one years, and the apprentice she took on at sixteen, now nineteen. She has not told him
+it is sold. He has not told her he got into a baking school in another city and leaves in the
+autumn. Each thinks they are protecting the other.
+
+The story is four scenes, one morning, 3:40 to 7:00. The oven has a noise. The rye is the thing
+she has never let him do alone.
+
+What it is about, I think: a craft outlives the room it was practiced in. And: people who love
+each other in a work setting say it through the work.
+
+The last line should be about bread, never about feelings.

package/examples/writing/story/materials/scene-list.md

@@ -0,0 +1,7 @@
+Scene list, agreed with the editor before drafting. Considered.
+
+- scene-1, 3:40: Theo arrives. Ines is already mixing. The oven noise. No one says anything real.
+- scene-2, 4:30: shaping. Ines lets Theo shape the rye for the first time, and does not say why.
+- scene-3, 5:50: the bake. Ines tells Theo the bakery is sold, while turning a tray.
+- scene-4, 6:55: before the doors open. Theo tells Ines about the school. She hands him the
+  starter jar.

package/examples/writing/story.hyperspec.md

@@ -0,0 +1,285 @@
+---
+hyperspec: "0.1"
+title: The Rye
+kind: short story
+profile: writing
+decisions:
+  - id: point-of-view
+    state: decided
+    value: first person, told by Theo, in the past tense
+    source: story/materials/notes.md
+    author: example-author
+    chosen_by: human
+  - id: time-span
+    state: decided
+    value: one morning, 3:40 to 7:00, in the four scenes of the scene list and in that order
+    source: story/materials/scene-list.md
+    author: example-author
+    chosen_by: human
+  - id: bakery-name
+    state: delegated
+    rule: the bakery is never named; it is always "the bakery" or "Ines's"
+    source: editor's note on the scene list
+    author: agent:claude
+    chosen_by: agent
+requirements:
+  - id: r1
+    text: the two voices cannot be confused
+    fails_when: a judge shown ten lines of dialogue with the speaker hidden names the wrong speaker for more than one of them
+    check:
+      rubric: blind attribution test across both characters, ten lines drawn at random from the draft
+    source: story/materials/notes.md
+    author: example-author
+  - id: r2
+    text: no one says what they could not know yet
+    fails_when: Theo mentions the sale before scene-3, or Ines mentions the school before scene-4
+    check:
+      station: knowledge-leak check of every line against each character's knowledge timeline
+    source: story/materials/scene-list.md
+    author: example-author
+  - id: r3
+    text: the bakery's process matches a real working morning
+    fails_when: a proofing time, the tray turn, or the opening time differs from story/materials/bakery-visit.md
+    check:
+      station: every process detail in the claims ledger points at a span of the bakery visit notes
+    source: story/materials/bakery-visit.md
+    author: agent:claude
+  - id: r4
+    text: the story is the four scenes of the scene list, in order
+    fails_when: the draft has more or fewer than four scenes, or they run out of the scene list's order
+    check:
+      station: structure check against story/materials/scene-list.md
+    source: story/materials/scene-list.md
+    author: example-author
+  - id: r5
+    text: the last line is about bread
+    fails_when: the final sentence names a feeling, or does not mention bread, dough, flour or the starter
+    check:
+      rubric: read the final sentence; fail if it names an emotion or mentions none of bread, dough, flour or the starter
+    source: story/materials/notes.md
+    author: example-author
+  - id: r6
+    text: the story stays inside its length envelope
+    fails_when: the word count is under 2,500 or over 4,000
+    check:
+      station: word count against form.length
+    source: editor's brief
+    author: example-author
+rejects:
+  - either character saying out loud that they love or will miss the other
+  - a flashback outside the one morning
+  - a scene where the oven noise is explained
+  - an ending that tells the reader what the starter jar means
+examples:
+  - path: story/goldens/dialogue.md
+    why: three short lines carry a ritual both characters know, without either of them naming it
+resume:
+  next_action: mark the three materials into labeled segments, then draft scene-1 from the scene list with Theo's knowledge as of scene-1
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: story/runs.jsonl
+writing:
+  materials:
+    items:
+      - id: notes
+        path: story/materials/notes.md
+        produced_by: example-author
+        captured: "2026-08-20"
+        how: typed notes
+        trust: raw
+      - id: bakery-visit
+        path: story/materials/bakery-visit.md
+        produced_by: example-author
+        captured: "2026-08-28"
+        how: notes taken on site, corrected by the bakery owner afterwards
+        trust: considered
+      - id: scene-list
+        path: story/materials/scene-list.md
+        produced_by: example-author
+        captured: "2026-09-02"
+        how: scene list agreed with the editor
+        trust: considered
+    check:
+      station: every segment of every material carries a label from the closed set
+    source: capture step
+    author: agent:claude
+  dna:
+    writer: example-author
+    scope:
+      form: short story
+      audience: literary magazine readers
+      purpose: move
+    rules: style-rules.md
+    goldens:
+      - path: story/goldens/opening.md
+        why: the narrator's voice arrives through one concrete sound, and the sentence about the mixer tells you how he sees the world
+      - path: story/goldens/dialogue.md
+        why: the narration between lines says only what Theo notices, never what Ines feels
+    check:
+      rubric: blind lineup within this scope; a judge shown a generated passage beside the two goldens cannot pick it out
+    source: goldens marked on the review page
+    author: example-author
+  persona:
+    identity: character:theo
+    stance: witness
+    may_assert:
+      - what Theo sees, hears and does in the bakery that morning
+      - what Theo knows as of the current scene, per his knowledge timeline
+    will_not_say:
+      - what Ines is thinking or feeling
+      - anything Theo does not know yet at that point in the morning
+    facts_from: sources
+    check:
+      rubric: persona-consistency judge; Theo's narration stays a witness's, and no process detail appears that is not in the claims ledger
+    source: persona interview
+    author: example-author
+  audience:
+    who: readers of a quarterly literary magazine who read short fiction in print
+    funnel_now: has turned to the story in the magazine without knowing the author
+    knows:
+      - bakery
+      - apprentice
+      - sourdough
+    believes_now: nothing yet about this author or these two people
+    wants: a story they can finish in one sitting and keep thinking about
+    reads_on: print, in one sitting of about fifteen minutes
+    reader: person
+    check:
+      station: term check against knows; proof, starter and deck oven are made plain by context on first use
+      rubric: simulated reader reports where it got lost and where it stopped reading
+    source: editor's brief
+    author: example-author
+  goal:
+    from: has never read the author
+    to: finishes the story and remembers the starter jar
+    next_if_worked: looks for the author's other stories
+    change:
+      kind: feeling
+      text: the reader feels the handover of the starter jar as the moment the two say what neither says aloud
+    conditions: [r1, r2, r3, r4, r5, r6]
+    check:
+      rubric: the doctor grades the draft against every condition; the simulated reader is asked what the starter jar meant and whether it would look for the author's next story
+    source: goal interview
+    author: example-author
+  form:
+    name: short story
+    length:
+      min: 2500
+      max: 4000
+      unit: words
+    required_parts:
+      - four scenes, in the scene list's order
+      - a last line about bread
+    stations:
+      - continuity against the scene list
+      - knowledge-leak check, per character, per scene
+    check:
+      station: structure and length check against required_parts and length
+    source: editor's brief
+    author: example-author
+  spine:
+    kind: story
+    claims:
+      - id: c1
+        text: each of them hides their news to protect the other, and the hiding is the thing they share
+        materials: [notes, scene-list]
+      - id: c2
+        text: people who love each other at work say it through the work
+        materials: [notes, bakery-visit]
+      - id: c3
+        text: a craft outlives the room it was practiced in
+        materials: [notes, scene-list]
+    check:
+      rubric: each claim lands, in order, through what the characters do, and the story argues nothing outside the chain
+    source: spine interview
+    author: example-author
+  sources:
+    ledger: story/claims.jsonl
+    unsourced_claim: fail
+    check:
+      station: every process detail in the ledger points at a source span; every quote matches its source verbatim
+    source: sourcing pass
+    author: agent:claude
+  characters:
+    - id: ines
+      speech:
+        uses:
+          - instructions in the imperative
+          - numbers, weights and times
+          - first names, for customers
+        never:
+          - an apology in words
+          - a sentence about her own feelings
+          - a question she does not need answered
+        rhythm: short, flat sentences, often without a subject; silence where another person would reassure
+      wants: to leave the bakery in hands she trusts, without having to say that she is leaving it
+      fears: that Theo will stay in a trade with no bakery to do it in, because of her
+      hides: that she sold the bakery two weeks ago
+      knowledge:
+        - by: scene-1
+          knows: the sale closes on Friday, and the new owners will not keep it a bakery
+        - by: scene-4
+          knows: Theo has a place at a baking school in another city and leaves in the autumn
+      relationships:
+        - to: theo
+          how: gives him instructions where another person would give praise
+        - to: customers
+          how: warm and unhurried, asks after their families by name
+      arc_state: has let go of the bakery, and has not yet let go of Theo
+      golden_lines:
+        - Flour first. Then you can talk.
+        - Left side runs hot. Turn them at eight minutes.
+        - Sold means sold. Shape the rye.
+      rejected_lines:
+        - I'm so sorry I didn't tell you sooner, Theo.
+        - This place has been my whole life, you know?
+        - Would you like to try the rye today?
+      check:
+        rubric: blind attribution test, knowledge-leak check against the timeline, consistency against golden and rejected lines
+      source: story/materials/notes.md
+      author: example-author
+    - id: theo
+      speech:
+        uses:
+          - questions he already knows the answer to
+          - hedges such as "I mean" and "kind of"
+          - a joke when he is nervous
+        never:
+          - a flat instruction
+          - a word of baking jargon he has not heard Ines use first
+        rhythm: long sentences that double back on themselves and end in a question
+      wants: Ines to tell him he is ready, in words, once
+      fears: that leaving for school is a betrayal of the person who taught him
+      hides: that he has a place at a baking school in another city and leaves in the autumn
+      knowledge:
+        - by: scene-1
+          knows: the oven has made the noise since March, and he leaves for school in the autumn
+        - by: scene-3
+          knows: the bakery is sold, and the new owners will not keep it a bakery
+      relationships:
+        - to: ines
+          how: asks questions to keep her talking, and never interrupts her while she shapes
+      arc_state: still acting the apprentice while privately already leaving
+      golden_lines:
+        - Okay but like, if the oven's made that noise since March, is it a noise, or is that just how the oven talks now?
+        - I can do the rye. I mean, I think I can do the rye. I did it Tuesday, kind of.
+        - So is that a yes, or is that the face you make when it's a yes?
+      rejected_lines:
+        - Shape the rye.
+        - I have been accepted to a culinary program and will be leaving in the autumn.
+        - Left side runs hot, turn them early.
+      check:
+        rubric: blind attribution test, knowledge-leak check against the timeline, consistency against golden and rejected lines
+      source: story/materials/notes.md
+      author: example-author
+fiction: true
+---
+
+# The Rye
+
+A worked example of the writing profile for fiction: a short story with two characters, each
+specified well enough that an agent can write their dialogue and a judge can tell them apart.
+Every file this spec names ships beside it. `story/claims.jsonl` does not exist yet, because the
+claims ledger is written during drafting.

package/examples/writing/style-rules.md

@@ -0,0 +1,19 @@
+# Style rules
+
+The always-on layer. These apply to everything this writer publishes, whatever the form, the
+audience or the purpose. Goldens change with the scope; these do not.
+
+## Never
+
+- No em dashes. Use a comma, a colon, or a new sentence.
+- No sentence that sets up a claim only to knock down a weaker one first. State the claim.
+- No adjective standing in for evidence. If a sentence says a thing is important, it shows why.
+- No filler openers ("In today's world", "It goes without saying").
+- No exclamation marks outside quoted dialogue.
+
+## Always
+
+- The first line of a piece states what it is about.
+- A number carries its source, or it does not go in.
+- A quotation is word for word, or it is not in quotation marks.
+- One idea per paragraph. A paragraph that needs a second idea is two paragraphs.

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "@supersuit/hyperspec",
-  "version": "0.1.0",
+  "version": "0.3.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",
+    "WRITING.md",
+    "runs.jsonl",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -34,6 +40,6 @@
     "outcome-factory"
   ],
   "dependencies": {
-    "@supersuit/superskill": "^0.2.1"
+    "@supersuit/superskill": "^0.2.2"
   }
 }

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;
+}