Merge main into the #16 ingress branch and close what the RC gate caught

Brings #82 up to today's `main` (1bbcc10) and resolves the two conflicts as ordered
unions: `package.json` `test`/`check:syntax` and the release builder's syntax allow-list
and evidence keys. Both sides only appended, so nothing was dropped.

Verifying the merge against main's RC attack suite (#40) found two real defects, each
fixed test-first:

- An oversized body destroyed the socket mid-upload, so the caller saw `fetch failed`
  instead of the 413 it had already earned, and `security_attack_suite.mjs` could not
  complete at all. New test in `tests/analyze-ingress.acceptance.test.js` failed with
  `fetch failed` before the fix; `src/http-body.js` now keeps draining without buffering
  and refuses on `end`, so the ceiling still holds and the refusal is readable.
- #16's per-caller budget turned the suite's own load phase into 8/8 429s, which would
  have published refusals as analysis latency. The load phase now runs against a second
  permissive target and the suite refuses to publish a load figure if any sample was
  refused. `buildReport` also publishes `evidenceVerified`, so the verdict is
  re-derivable from the report — asserted by #40's acceptance test, which only trips once
  the verdict is GO.

Evidence on the merged tree: `npm test` 277/277, `test:security-attack` 8/8, the RC attack
suite returns VERDICT: GO with both P0 ingress cases passing (main is BLOCKED on exactly
those two), 14 browser acceptance suites green, and the release demo records end to end
(8:13, 97 captions) including the on-camera refusal scene.

.gitea/workflows/quality.yml

@@ -32,7 +32,12 @@ jobs:
       - name: Unit and security tests
         run: |
           npm test
+          npm run test:security-attack
           python3 tests/staging-deploy.test.py -v
+          python3 tests/corpus-manifest.test.py -v
+          python3 tests/corpus-review.test.py -v
+          python3 tests/dataset-card.test.py -v
+          python3 tests/calibration-harness.test.py -v
       - name: Mobile browser acceptance
         run: |
           npm start > /tmp/timmy-server.log 2>&1 &
@@ -60,6 +65,8 @@ jobs:
           npm run test:worker-readiness
           npm run test:pattern-summary
           npm run test:photo-lifecycle
+          npm run test:training-contribution
+          npm run test:portability
       - name: Dependency audit
         run: npm audit --audit-level=high
       - name: Syntax checks

.gitignore

@@ -5,3 +5,4 @@ __pycache__/
 *.pyc
 .env
 .env.*
+artifacts/security/

README.md

@@ -6,6 +6,7 @@ A working mobile-first bowel diary with an optional **photo-first AI assist**:
 - [Product and safety boundary](PRODUCT.md)
 - [Product boundary and release authority decision](docs/PRODUCT-DECISIONS.md)
 - [Self-hosted stool-vision decision](research/SELF-HOSTED-STOOL-VISION.md)
+- [Production topology, secrets, backup, and rollback runbook](docs/PRODUCTION-RUNBOOK.md)
 
 ## Build a gated review release
 
@@ -28,6 +29,25 @@ sudo python3 scripts/deploy_staging.py rollback --commit PRIOR_FULL_COMMIT
 
 Commands are fixed argv arrays executed with `shell=False`; JSON argv overrides and `--root` exist for rootless fixtures. See [the staging runbook](docs/STAGING-RUNBOOK.md) for host prerequisites, mode-600 environment injection, Caddy validation, smoke credentials, logs, backups, removal, and the explicit no-live-change boundary.
 
+## Back up and restore the records an operator holds
+
+The app keeps the journal in the person's own browser, so the server has no diary to back up. What an
+operator can lose is the corpus: the append-only `manifest.jsonl` with its provenance records and its
+withdrawal tombstones, plus the derived images those records point at.
+
+```bash
+python3 scripts/operator_backup.py backup --source /srv/timmy-corpus --archive /srv/backups/timmy-nightly.tar.gz --label nightly
+python3 scripts/operator_backup.py verify --archive /srv/backups/timmy-nightly.tar.gz --manifest /srv/backups/timmy-nightly.tar.gz.manifest.json
+python3 scripts/operator_backup.py restore --archive /srv/backups/timmy-nightly.tar.gz --manifest /srv/backups/timmy-nightly.tar.gz.manifest.json --target /srv/timmy-corpus.restore-check
+```
+
+Model weights, transient inference images, secrets, logs, and symlinks are refused by name, and every
+skipped path is listed in the manifest with its reason. Each stored member carries a SHA-256, the
+archive is reproducible, and a restore re-verifies every digest and the record counts before it writes
+anything — a tampered archive or a lost tombstone fails loudly instead of restoring quietly. See the
+[production runbook](docs/PRODUCTION-RUNBOOK.md) for topology, network boundaries, secrets, retention,
+and the rollback paths.
+
 ## Run with the self-hosted open-weight path
 
 ```bash
@@ -100,6 +120,9 @@ npm run test:manual-fallback  # vision-offline manual path + in-session draft re
 npm run test:vision-refusal   # corpus refusals through a real server and a real browser
 npm run test:grounded-chat    # chat answers cite the ledger, or refuse to answer
 npm run test:photo-lifecycle  # photo presence, explicit reveal, remove-photo-keeps-log, delete-all
+npm run test:calibration      # the release-gate harness: gates, threshold protocol, refused corpora
+npm run test:review           # blind review queue, held-back model answer, an append-only ledger, withdrawals
+npm run test:security-attack  # hostile synthetic uploads at the real boundary, with a counting worker (#40)
 npm audit --audit-level=high
 ```
 
@@ -109,7 +132,7 @@ npm audit --audit-level=high
 - Client-side image compression before transfer
 - Explicit consent before one-time provider analysis
 - Structured AI suggestions for **visible Bristol form and color only**
-- Confidence display, low-confidence abstention, and user confirmation
+- Confidence display, low-confidence abstention, and user confirmation, governed by one versioned policy: `poor` image quality abstains even at high confidence, and a confident reply is never enough on its own — see [docs/ABSTENTION-POLICY.md](docs/ABSTENTION-POLICY.md)
 - Urgency, discomfort, notes, and symptoms remain strictly user-reported
 - Manual logging that never uploads
 - Sleek three-destination mobile shell with one dominant photo action
@@ -122,7 +145,7 @@ npm audit --audit-level=high
 - A committed CC0 synthetic vision corpus that continuously proves every reply is schema-valid or fails closed. A schema-valid reply with no readable form or colour now **abstains** ("No confident match") instead of surfacing as a worker failure, and unparsable or out-of-range replies return plain copy — "No suggestion was applied. Continue manually, or try a clearer photo." — with no provider text, image bytes, or credentials echoed. See [tests/fixtures/vision-corpus](tests/fixtures/vision-corpus/README.md)
 - Unsaved logging drafts are retained in the session with an explicit start over, and the service worker never caches analysis requests or image bodies
 - Private photo lifecycle: a confirmed log reports a saved photo as a label rather than a thumbnail, showing the image is an explicit request, removing the photo keeps every confirmed field, deleting a log is a separate two-step decision, and delete-all removes the ledger and every stored photo together
-- Local browser ledger, calendar, pattern summary, JSON portability, and delete-all
+- Local browser ledger, calendar, pattern summary, versioned JSON backup (logs, training receipts, and per-log AI provenance) with safe upgrade/refusal on import, and delete-all
 - Explainable pattern summaries: the home insight card reports the confirmed-log count and form groupings for the last 28 days, every line names the exact confirmed records behind it, following a citation opens those records, and a window below the minimum says it is too sparse instead of describing a trend. No line explains a cause, rules on food, or offers a health verdict
 - Installable/offline PWA shell for the manual and saved-ledger paths
 
@@ -132,6 +155,14 @@ The positive photo-prefill interface is covered by a deterministic provider fixt
 
 Timmy does not diagnose disease, identify bleeding, infer pain/urgency, recommend treatment, or clear foods. The selected VLM is a bootstrap worker, not the final classifier. See [research/SELF-HOSTED-STOOL-VISION.md](research/SELF-HOSTED-STOOL-VISION.md) for the measured receipts, hardware gate, consented-data pipeline, specialist-classifier plan, and sources.
 
+The calibration harness ([scripts/calibration_report.py](scripts/calibration_report.py), [contract](docs/EVALUATION-HARNESS.md)) computes the ROADMAP release gates — macro-F1, precision-at-coverage, and calibration error — from prediction files, chooses a threshold on validation only, and refuses a corpus that leaks one contributor across two splits. Its committed fixtures are invented numbers that exercise the arithmetic: **no candidate model has been measured against these gates yet, and the harness itself is not evidence about accuracy.**
+
+The reviewer tool ([scripts/review_corpus.py](scripts/review_corpus.py), [contract](docs/REVIEWER-TOOL.md)) is the labeling control for that corpus, and it is a command-line tool with no screen in the app. The review queue shows the contributor's proposal and withholds every model field, a reveal is refused until a human has committed their own labels, a correction must actually change the proposal, adjudication is appended beside the review it resolves instead of overwriting it, and a withdrawn contribution cannot be queued, reviewed, revealed, adjudicated, or trained on. Unreviewed and excluded samples are never training data. It records decisions; it does not measure a model.
+
+What the corpus is, and what a label may assert, is published rather than implied: [docs/DATASET_CARD.md](docs/DATASET_CARD.md) is generated from the manifest by [scripts/dataset_card.py](scripts/dataset_card.py), so every count on it is read back from real records and every fact the pipeline does not collect (devices, contexts, licenses) is printed as `pending` instead of estimated — a card for a corpus where one contributor straddles two splits is refused, not published. [docs/LABELING_GUIDE.md](docs/LABELING_GUIDE.md) is the reviewer's rulebook: visible form, broad visible color, and photo quality only, visible color is not blood, nothing is diagnosed, and a model suggestion is provisional input to a human decision rather than the label.
+
+The release candidate is attacked before anyone is asked to trust it. [scripts/security_attack_suite.mjs](scripts/security_attack_suite.mjs) drives the real server with synthetic hostile bytes — an oversized body, an HTML polyglot dressed as a JPEG, undecodable bytes, a request without consent, a worker answer that breaks the schema, a byte-identical replay, and a concurrent burst — while a counting stub worker records every call that reaches the model boundary. [docs/RC-SECURITY-EVIDENCE.md](docs/RC-SECURITY-EVIDENCE.md) owns the rule: any failing P0 case blocks RC approval, and a required class with no executable evidence blocks it too. **It currently returns `VERDICT: BLOCKED`** — bytes are still trusted from the data-URL label, so a hostile file reaches the worker before it fails on schema. That is a published finding against [#16](https://forge.alexanderwhitestone.com/git/stackchain/timmy-talking-turd/issues/16), not a passing check.
+
 ## Architecture
 
 ```text

app.js

@@ -1,4 +1,4 @@
-import { bucketForBristolType, detectUrgentFlags, detectUrgentText, exportLedger, hasUrgentLedgerContext, importLedger, photoQualityMessage, sanitizeEntry, urgentChatMessage } from './src/domain.js';
+import { bucketForBristolType, detectUrgentFlags, detectUrgentText, exportLedgerBackup, LEDGER_EXPORT_VERSION, hasUrgentLedgerContext, importLedgerBackup, photoQualityMessage, sanitizeEntry, urgentChatMessage } from './src/domain.js';
 import { mergeVisualSuggestion } from './src/analysis.js';
 import { createDraft, draftNotice, isDraftDirty } from './src/draft.js';
 import { changeVisualField, confirmSuggestion, createSuggestionState, provenanceCopy } from './src/suggestion.js';
@@ -7,6 +7,7 @@ import { visionReadiness } from './src/vision-readiness.js';
 import { buildPatternSummary } from './src/summary.js';
 import { answerFromLedger, buildChatLedger, resolveAgentReply } from './src/grounded-chat.js';
 import { photoState, withoutEntry, withoutPhoto } from './src/photo-lifecycle.js';
+import { addContribution, consentTerms, contributionEligibility, contributionForEntry, receiptPreview, withdrawContribution } from './src/training-contribution.js';
 
 const runtimeConfig = {
   basePath: document.querySelector('meta[name="timmy-base-path"]')?.content || '/',
@@ -16,6 +17,7 @@ const BASE_PATH = runtimeConfig.basePath || '/';
 const APP_ROOT = BASE_PATH === '/' ? '/' : `${BASE_PATH}/`;
 function appPath(path='') { return `${APP_ROOT}${String(path).replace(/^\/+/, '')}`; }
 const STORE = `timmy:${BASE_PATH}:ledger-v1`;
+const TRAINING_STORE = `timmy:${BASE_PATH}:training-contributions-v1`;
 const LEGACY_STORE = 'timmy-ledger-v1';
 if (BASE_PATH === '/') {
   const legacyEntries = localStorage.getItem(LEGACY_STORE);
@@ -28,6 +30,7 @@ if (BASE_PATH === '/') {
 }
 const app = document.querySelector('#app');
 let entries = loadEntries();
+let contributions = loadContributions();
 let view = 'home';
 let photoHint = '';
 let aiSuggestion = null;
@@ -39,6 +42,10 @@ let chatBusy = false;
 let chatError = '';
 let chatMessages = [{ role: 'timmy', text: 'Ask me about your confirmed logs, visible patterns, privacy, or how Timmy works.' }];
 let draftResumed = false;
+// Issue #35 — importing a backup reports which version the file came from and what changed, and a
+// refused file leaves the ledger exactly as it was. The notice is state, not a toast, because a
+// message that disappears in two seconds cannot tell anyone whether their records were replaced.
+let portabilityNotice = null;
 let form = createDraft();
 let followUpAnswers = createFollowUpAnswers();
 
@@ -86,6 +93,10 @@ function refreshFollowUp(){
 function esc(value='') { return String(value).replace(/[&<>'"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;',"'":'&#39;','"':'&quot;'}[c])); }
 function loadEntries() { try { return JSON.parse(localStorage.getItem(STORE) || '[]'); } catch { return []; } }
 function saveEntries() { localStorage.setItem(STORE, JSON.stringify(entries)); }
+// Training contribution receipts are their own store: a journal save never writes here, and a
+// withdrawal keeps a tombstone instead of quietly erasing the audit trail.
+function loadContributions() { try { return JSON.parse(localStorage.getItem(TRAINING_STORE) || '[]'); } catch { return []; } }
+function saveContributions() { localStorage.setItem(TRAINING_STORE, JSON.stringify(contributions)); }
 function formatDate(value) { return new Intl.DateTimeFormat(undefined,{month:'short',day:'numeric',hour:'numeric',minute:'2-digit'}).format(new Date(value)); }
 function toast(message) { const node=document.createElement('div');node.className='toast';node.textContent=message;document.body.append(node);setTimeout(()=>node.remove(),2400); }
 
@@ -101,6 +112,8 @@ function bindGlobal(){
   document.querySelectorAll('[data-scan]').forEach(btn=>btn.onclick=openPhotoFirst);
   document.querySelectorAll('[data-statement-link]').forEach(btn=>btn.onclick=()=>showPatternRecords(btn.dataset.statementLink));
   document.querySelectorAll('[data-entry-open]').forEach(btn=>btn.onclick=()=>showEntrySheet(btn.dataset.entryOpen));
+  document.querySelectorAll('[data-contribute-entry]').forEach(btn=>btn.onclick=()=>showContributionConsent(btn.dataset.contributeEntry));
+  document.querySelectorAll('[data-withdraw]').forEach(btn=>btn.onclick=()=>withdrawTrainingContribution(btn.dataset.withdraw));
 }
 
 function recentList(limit=5){
@@ -122,7 +135,7 @@ function showEntrySheet(id, armed=false){
   const urgent=detectUrgentFlags(entry.symptoms);
   document.querySelector('.sheet-backdrop')?.remove();
   const wrap=document.createElement('div');wrap.className='sheet-backdrop';
-  wrap.innerHTML=`<section class="sheet" role="dialog" aria-modal="true" aria-labelledby="entry-sheet-title"><div class="sheet-handle"></div><div class="sheet-header"><div><span class="eyebrow">Confirmed log</span><h2 id="entry-sheet-title">${formatDate(entry.occurredAt)}</h2></div><button class="icon-btn" id="entry-sheet-close" aria-label="Close">×</button></div><div class="entry-facts"><div><span>Form</span><strong>Type ${entry.bristolType}</strong></div><div><span>Color</span><strong>${esc(entry.color)}</strong></div><div><span>Urgency</span><strong>${entry.urgency}/4</strong></div><div><span>Discomfort</span><strong>${entry.discomfort}/4</strong></div></div>${entry.note?`<p class="fine entry-note">${esc(entry.note)}</p>`:''}${urgent.urgent?alertHtml(urgent.message):''}${photo.hasPhoto?`<section class="photo-lifecycle" data-photo-lifecycle="present"><strong>Photo saved with this log</strong><p class="fine">The image stays in this browser. The journal never shows it as a thumbnail until you ask.</p><div id="entry-photo-slot"></div><div class="row"><button class="btn btn-secondary" id="show-entry-photo">Show photo</button><button class="btn btn-ghost" id="remove-entry-photo">Remove photo, keep log</button></div></section>`:`<section class="photo-lifecycle" data-photo-lifecycle="absent"><strong>No photo saved</strong><p class="fine">This confirmed log is text only. Its record does not depend on an image.</p></section>`}<div class="entry-actions">${armed?`<button class="btn btn-danger btn-wide" id="delete-entry-confirm">Tap again to delete this log and its photo</button><p class="fine">This removes the confirmed log and its saved photo from this browser. It cannot be undone.</p>`:`<button class="btn btn-ghost btn-wide" id="delete-entry">Delete this log and its photo</button>`}</div></section>`;
+  wrap.innerHTML=`<section class="sheet" role="dialog" aria-modal="true" aria-labelledby="entry-sheet-title"><div class="sheet-handle"></div><div class="sheet-header"><div><span class="eyebrow">Confirmed log</span><h2 id="entry-sheet-title">${formatDate(entry.occurredAt)}</h2></div><button class="icon-btn" id="entry-sheet-close" aria-label="Close">×</button></div><div class="entry-facts"><div><span>Form</span><strong>Type ${entry.bristolType}</strong></div><div><span>Color</span><strong>${esc(entry.color)}</strong></div><div><span>Urgency</span><strong>${entry.urgency}/4</strong></div><div><span>Discomfort</span><strong>${entry.discomfort}/4</strong></div></div>${entry.note?`<p class="fine entry-note">${esc(entry.note)}</p>`:''}${entry.provenance?`<p class="fine entry-provenance" data-entry-provenance="${esc(entry.provenance.source)}">${esc(entry.provenance.source==='ai-corrected'?'Saved from an AI suggestion you corrected. Your values are stored, not the model’s.':'Saved from an AI suggestion you confirmed: visible form and color only, never a diagnosis.')}${entry.provenance.model?` Model: ${esc(entry.provenance.model)}.`:''}</p>`:''}${urgent.urgent?alertHtml(urgent.message):''}${photo.hasPhoto?`<section class="photo-lifecycle" data-photo-lifecycle="present"><strong>Photo saved with this log</strong><p class="fine">The image stays in this browser. The journal never shows it as a thumbnail until you ask.</p><div id="entry-photo-slot"></div><div class="row"><button class="btn btn-secondary" id="show-entry-photo">Show photo</button><button class="btn btn-ghost" id="remove-entry-photo">Remove photo, keep log</button></div></section>`:`<section class="photo-lifecycle" data-photo-lifecycle="absent"><strong>No photo saved</strong><p class="fine">This confirmed log is text only. Its record does not depend on an image.</p></section>`}<div class="entry-actions">${armed?`<button class="btn btn-danger btn-wide" id="delete-entry-confirm">Tap again to delete this log and its photo</button><p class="fine">This removes the confirmed log and its saved photo from this browser. It cannot be undone.</p>`:`<button class="btn btn-ghost btn-wide" id="delete-entry">Delete this log and its photo</button>`}</div></section>`;
   document.body.append(wrap);
   if(entrySheetKeyHandler)document.removeEventListener('keydown',entrySheetKeyHandler);
   const close=()=>{wrap.remove();document.removeEventListener('keydown',onKey);if(entrySheetKeyHandler===onKey)entrySheetKeyHandler=null};
@@ -245,13 +258,68 @@ async function sendChat(event){
  finally{chatBusy=false;timmy()}
 }
 
+// Issue #24 — contributing a confirmed photo to training is a second, separate consent. A journal
+// save writes nothing here, the consent version and the receipt are on screen before the confirm
+// control can be pressed, and a withdrawal keeps a tombstone naming every derived artifact by
+// contribution id. Nothing is transmitted in this build: the receipt is queued on the device.
+function newContributionId(){
+  const raw=globalThis.crypto?.randomUUID?.()||`${Date.now().toString(16)}${Math.random().toString(16).slice(2)}`;
+  return `contrib-${String(raw).replace(/[^a-z0-9]/gi,'').slice(0,12)}`;
+}
+function trainingConsentSection(){
+  const terms=consentTerms();
+  const queued=contributions.filter(receipt=>receipt.state!=='withdrawn').length;
+  const active=contributions.filter(receipt=>receipt.state!=='withdrawn').map(receipt=>`<div class="contribution-row" data-contribution-state="${esc(receipt.state)}"><div><strong>Type ${receipt.labels.bristolType} · ${esc(receipt.labels.color)}</strong><span>Receipt ${esc(receipt.contributionId)} · consent ${esc(receipt.consentVersion)}</span></div><button class="btn btn-ghost" data-withdraw="${esc(receipt.contributionId)}">Withdraw</button></div>`);
+  const offerable=entries.filter(entry=>contributionEligibility(entry).eligible&&!contributions.some(receipt=>receipt.entryId===entry.id)).map(entry=>`<div class="contribution-row"><div><strong>${formatDate(entry.occurredAt)}</strong><span>Type ${entry.bristolType} · photo saved</span></div><button class="btn btn-secondary" data-contribute-entry="${esc(entry.id)}">Review opt-in</button></div>`);
+  const tombstones=contributions.filter(receipt=>receipt.state==='withdrawn').map(receipt=>`<div class="contribution-row withdrawn" data-contribution-state="withdrawn"><div><strong>Withdrawn ${esc(formatDate(receipt.withdrawnAt))}</strong><span data-withdrawn-artifacts>raw image, confirmed label · receipt ${esc(receipt.contributionId)}</span></div></div>`);
+  const rows=[...active,...offerable].join('');
+  return `<section class="section card training-consent" data-training-consent><h2>Training contribution</h2><p class="fine">Off by default. Saving a log never contributes it, and nothing is uploaded in this build — a receipt is queued on this device.</p><p class="fine">Consent version <code data-contribution-consent-version>${esc(terms.version)}</code> · <span data-contribution-queued-count>${queued}</span> queued</p>${rows?`<div class="contribution-list">${rows}</div>`:'<p class="fine">No saved photos are available to contribute yet.</p>'}${tombstones.length?`<h3>Withdrawn receipts</h3>${tombstones.join('')}`:''}<p class="fine">Deleting all local data below also clears these receipts.</p></section>`;
+}
+let contributionSheetKeyHandler=null;
+function showContributionConsent(entryId){
+  const entry=entries.find(item=>item.id===entryId);
+  const eligibility=contributionEligibility(entry);
+  if(!eligibility.eligible){toast(eligibility.reason||'This log cannot be contributed.');return}
+  if(contributionForEntry(contributions,entryId)){toast('This log already has an active contribution receipt.');return}
+  const terms=consentTerms();
+  const contributionId=newContributionId();
+  const consentedAt=new Date().toISOString();
+  document.querySelector('.sheet-backdrop')?.remove();
+  const wrap=document.createElement('div');wrap.className='sheet-backdrop';
+  wrap.innerHTML=`<section class="sheet" role="dialog" aria-modal="true" aria-labelledby="contribution-title" data-contribution-sheet><div class="sheet-handle"></div><div class="sheet-header"><div><span class="eyebrow">Separate consent</span><h2 id="contribution-title">Contribute one photo?</h2></div><button class="icon-btn" id="contribution-cancel" aria-label="Close">×</button></div><div class="consent-card"><p class="fine">Consent version <code data-contribution-version>${esc(terms.version)}</code></p><p class="fine">Receipt <code data-receipt-id>${esc(contributionId)}</code> · ${esc(formatDate(consentedAt))}</p><p class="fine"><strong>Included:</strong> ${esc(terms.includes.join('; '))}.</p><p class="fine"><strong>Never included:</strong> ${esc(terms.excludes.join('; '))}.</p><p class="fine">${esc(terms.transport)}</p></div><label class="check"><input id="training-consent-check" type="checkbox"><span>I have read consent ${esc(terms.version)} and want this one log contributed.</span></label><button class="btn btn-primary btn-wide" id="contribute-confirm" disabled>Contribute this photo and label</button><button class="btn btn-ghost btn-wide section" id="contribution-cancel-bottom">Not now</button></section>`;
+  document.body.append(wrap);
+  if(contributionSheetKeyHandler)document.removeEventListener('keydown',contributionSheetKeyHandler);
+  const close=()=>{wrap.remove();document.removeEventListener('keydown',onKey);if(contributionSheetKeyHandler===onKey)contributionSheetKeyHandler=null};
+  const onKey=event=>{if(event.key==='Escape')close()};
+  contributionSheetKeyHandler=onKey;
+  document.addEventListener('keydown',onKey);
+  document.querySelector('#contribution-cancel').onclick=close;
+  document.querySelector('#contribution-cancel-bottom').onclick=close;
+  wrap.onclick=event=>{if(event.target===wrap)close()};
+  const check=document.querySelector('#training-consent-check'),confirm=document.querySelector('#contribute-confirm');
+  check.onchange=()=>{confirm.disabled=!check.checked};
+  confirm.onclick=()=>{
+    try{
+      contributions=addContribution(contributions,receiptPreview(entry,{contributionId,consentedAt}));
+      saveContributions();close();render();toast('Queued on this device. Nothing was uploaded.');
+    }catch(error){toast(error.message||'That receipt could not be recorded.')}
+  };
+}
+function withdrawTrainingContribution(contributionId){
+  const result=withdrawContribution(contributions,contributionId,new Date().toISOString());
+  if(!result.tombstone){toast('That contribution receipt was not found.');return}
+  contributions=result.contributions;saveContributions();render();toast('Contribution withdrawn. The receipt is kept as a tombstone.');
+  return result.tombstone;
+}
+
 function privacy(){
-  shell(`<main><div class="page-title"><span class="eyebrow">Private by design</span><h1>Your poop. Your phone.</h1><p>This prototype has no account, analytics, ad tracker, or server database.</p></div><section class="card privacy-list"><div class="privacy-item"><b>⌂</b><div><h3>Stored locally</h3><p>Saved entries and optional photos live in this browser’s local storage. You can remove one photo without deleting its confirmed log.</p></div></div><div class="privacy-item"><b>⇩</b><div><h3>Portable</h3><p>Export a readable JSON file. Import it in another copy of Timmy.</p></div></div><div class="privacy-item"><b>◎</b><div><h3>AI only when you ask</h3><p>Manual logging never uploads. Analyze a photo sends one compressed copy after consent. Hermes chat may receive up to 20 confirmed text-only entries after you connect; photos and backend credentials never enter chat.</p></div></div></section><section class="section card"><h2>Data controls</h2><div class="row"><button class="btn btn-primary" id="export">Export JSON</button><label class="btn btn-secondary" for="import">Import JSON</label><input class="hidden" type="file" id="import" accept="application/json"></div><p class="fine section">Exports can contain sensitive health notes and photos. Store them somewhere you trust.</p></section><section class="section card source-list"><h2>Health sources</h2><p class="fine">The Bristol groupings and urgent-symptom copy are grounded in public clinical guidance.</p><p><a target="_blank" rel="noreferrer" href="https://www.continence.org.au/about-incontinence/bowel-incontinence/bristol-stool-chart/">Continence Health Australia</a></p><p><a target="_blank" rel="noreferrer" href="https://www.nhs.uk/conditions/bleeding-from-the-bottom-rectal-bleeding/">NHS rectal bleeding guidance</a></p><p><a target="_blank" rel="noreferrer" href="https://www.niddk.nih.gov/health-information/digestive-diseases/constipation/symptoms-causes">NIDDK constipation guidance</a></p></section><section class="section card danger-zone"><h2>Delete everything</h2><p class="fine">Permanently removes Timmy’s local ledger and every saved photo from this browser.</p><button class="btn btn-danger" id="delete-all">Delete all local data</button></section></main>`);
+  shell(`<main><div class="page-title"><span class="eyebrow">Private by design</span><h1>Your poop. Your phone.</h1><p>This prototype has no account, analytics, ad tracker, or server database.</p></div><section class="card privacy-list"><div class="privacy-item"><b>⌂</b><div><h3>Stored locally</h3><p>Saved entries and optional photos live in this browser’s local storage. You can remove one photo without deleting its confirmed log.</p></div></div><div class="privacy-item"><b>⇩</b><div><h3>Portable</h3><p>Export a readable JSON file. Import it in another copy of Timmy.</p></div></div><div class="privacy-item"><b>◎</b><div><h3>AI only when you ask</h3><p>Manual logging never uploads. Analyze a photo sends one compressed copy after consent. Hermes chat may receive up to 20 confirmed text-only entries after you connect; photos and backend credentials never enter chat.</p></div></div></section><section class="section card"><h2>Data controls</h2><div class="row"><button class="btn btn-primary" id="export">Export JSON</button><label class="btn btn-secondary" for="import">Import JSON</label><input class="hidden" type="file" id="import" accept="application/json"></div><p class="fine section">Exports can contain sensitive health notes and photos. Store them somewhere you trust.</p></section>${portabilityNoticeBlock()}${trainingConsentSection()}<section class="section card source-list"><h2>Health sources</h2><p class="fine">The Bristol groupings and urgent-symptom copy are grounded in public clinical guidance.</p><p><a target="_blank" rel="noreferrer" href="https://www.continence.org.au/about-incontinence/bowel-incontinence/bristol-stool-chart/">Continence Health Australia</a></p><p><a target="_blank" rel="noreferrer" href="https://www.nhs.uk/conditions/bleeding-from-the-bottom-rectal-bleeding/">NHS rectal bleeding guidance</a></p><p><a target="_blank" rel="noreferrer" href="https://www.niddk.nih.gov/health-information/digestive-diseases/constipation/symptoms-causes">NIDDK constipation guidance</a></p></section><section class="section card danger-zone"><h2>Delete everything</h2><p class="fine">Permanently removes Timmy’s local ledger and every saved photo from this browser.</p><button class="btn btn-danger" id="delete-all">Delete all local data</button></section></main>`);
   document.querySelector('#export').onclick=exportData;document.querySelector('#import').onchange=importData;document.querySelector('#delete-all').onclick=deleteData;
 }
-function exportData(){const blob=new Blob([exportLedger(entries)],{type:'application/json'}),a=document.createElement('a');a.href=URL.createObjectURL(blob);a.download='timmy-ledger.json';a.click();URL.revokeObjectURL(a.href);toast('Export created');}
-async function importData(e){try{const text=await e.target.files[0].text();entries=importLedger(text);saveEntries();render();toast('Ledger imported')}catch(err){toast(err.message)}}
-function deleteData(){if(confirm('Delete every local Timmy entry and photo? This cannot be undone.')){entries=[];localStorage.removeItem(STORE);localStorage.removeItem(LEGACY_STORE);render();toast('Local ledger and photos deleted')}}
+function exportData(){const blob=new Blob([exportLedgerBackup({entries,contributions})],{type:'application/json'}),a=document.createElement('a');a.href=URL.createObjectURL(blob);a.download=`timmy-backup-v${LEDGER_EXPORT_VERSION}.json`;a.click();URL.revokeObjectURL(a.href);portabilityNotice={kind:'ok',version:LEDGER_EXPORT_VERSION,text:`Backup written as version ${LEDGER_EXPORT_VERSION}: ${entries.length} log${entries.length===1?'':'s'} and ${contributions.length} training receipt${contributions.length===1?'':'s'}.`};render();toast('Backup exported');}
+async function importData(e){const file=e.target.files?.[0];if(!file)return;try{const result=importLedgerBackup(await file.text());entries=result.entries;contributions=result.contributions;saveEntries();saveContributions();portabilityNotice={kind:'ok',version:result.fromVersion,text:[`Restored ${result.entries.length} log${result.entries.length===1?'':'s'} and ${result.contributions.length} training receipt${result.contributions.length===1?'':'s'} from a version ${result.fromVersion} backup.`,...result.notices].join(' ')};e.target.value='';render();toast('Backup imported')}catch(err){portabilityNotice={kind:'error',text:`${err.message||'That backup could not be read.'} Your ledger is unchanged.`};e.target.value='';render();toast('Nothing was imported')}}
+function portabilityNoticeBlock(){if(!portabilityNotice)return '';if(portabilityNotice.kind==='error')return `<p class="portability-notice error" role="alert" data-portability-error>${esc(portabilityNotice.text)}</p>`;return `<p class="portability-notice" role="status" data-portability-notice data-portability-version="${esc(String(portabilityNotice.version))}">${esc(portabilityNotice.text)}</p>`}
+function deleteData(){if(confirm('Delete every local Timmy entry and photo? This cannot be undone.')){entries=[];contributions=[];portabilityNotice=null;localStorage.removeItem(STORE);localStorage.removeItem(LEGACY_STORE);localStorage.removeItem(TRAINING_STORE);render();toast('Local ledger and photos deleted')}}
 
 function openPhotoFirst(){beginDraft();photoHint='';resetSuggestion();visionStatus=null;showPhotoFirst('pick');loadVisionStatus()}
 async function loadVisionStatus(){
@@ -311,7 +379,21 @@ function bindStep(step){
 }
 async function handlePhoto(e){const file=e.target.files[0];if(!file)return;try{const result=await compressPhoto(file);form.photoDataUrl=result.dataUrl;photoHint=photoQualityMessage(result);showLogStep(2)}catch{photoHint='That image could not be read. Try another photo.';showLogStep(2)}}
 function compressPhoto(file){return new Promise((resolve,reject)=>{const img=new Image(),url=URL.createObjectURL(file);img.onload=()=>{const scale=Math.min(1,1200/Math.max(img.width,img.height)),canvas=document.createElement('canvas');canvas.width=Math.round(img.width*scale);canvas.height=Math.round(img.height*scale);const ctx=canvas.getContext('2d');ctx.drawImage(img,0,0,canvas.width,canvas.height);const sample=ctx.getImageData(0,0,Math.min(canvas.width,120),Math.min(canvas.height,120)).data;let total=0;for(let i=0;i<sample.length;i+=4)total+=(sample[i]+sample[i+1]+sample[i+2])/3;URL.revokeObjectURL(url);resolve({dataUrl:canvas.toDataURL('image/jpeg',.7),width:img.width,height:img.height,brightness:total/(sample.length/4)/255})};img.onerror=()=>{URL.revokeObjectURL(url);reject()};img.src=url})}
-function saveLog(){const result=detectUrgentFlags(form.symptoms);const entry=sanitizeEntry({...form});try{entries.push(entry);saveEntries()}catch{entry.photoDataUrl='';entries[entries.length-1]=entry;saveEntries();toast('Log saved, but the photo was too large for browser storage')}clearDraft();document.querySelector('.sheet-backdrop')?.remove();view='home';render();toast(result.urgent?'Saved. Please follow the medical-care alert.':'Private log saved')}
+// Issue #35 — if this log began as an AI suggestion, the saved record says so. The fields are
+// limited to what the app actually knows (which visible fields were suggested, whether they were
+// confirmed or corrected, and which model answered), so a backup cannot be read as a diagnosis or a
+// broader claim than the visual suggestion the person accepted.
+function provenanceForSave(){
+  const status=suggestionState?.status;
+  if(status!=='confirmed'&&status!=='corrected')return null;
+  const suggestion=suggestionState.suggestion;
+  if(!suggestion)return null;
+  const provenance={source:status==='confirmed'?'ai-confirmed':'ai-corrected',suggestedBristolType:suggestion.bristolType,suggestedColor:suggestion.color,confirmedAt:new Date().toISOString()};
+  const model=typeof visionStatus?.model==='string'?visionStatus.model.trim():'';
+  if(model)provenance.model=model.slice(0,80);
+  return provenance;
+}
+function saveLog(){const result=detectUrgentFlags(form.symptoms);const entry=sanitizeEntry({...form,provenance:provenanceForSave()});try{entries.push(entry);saveEntries()}catch{entry.photoDataUrl='';entries[entries.length-1]=entry;saveEntries();toast('Log saved, but the photo was too large for browser storage')}clearDraft();document.querySelector('.sheet-backdrop')?.remove();view='home';render();toast(result.urgent?'Saved. Please follow the medical-care alert.':'Private log saved')}
 function render(){({home,calendar,timmy,privacy}[view]||home)()}
 
 render();

docs/ABSTENTION-POLICY.md

@@ -0,0 +1,98 @@
+# Abstention policy
+
+Issue #32 asks for raw model scores to be turned into a conservative suggestion policy. This is that
+policy. It is the only thing that decides whether Timmy offers a visual prefill, and it answers two
+different questions that are easy to confuse:
+
+1. **Per photo** — is this individual answer good enough to show?
+2. **Per release** — has a candidate model earned the right to prefill at all?
+
+Both are implemented in [`src/abstention-policy.js`](../src/abstention-policy.js). The parser in
+[`src/analysis.js`](../src/analysis.js) reads its limits from that module rather than carrying its own
+copy, so a policy change is one edit, not three.
+
+A suggestion is never a diagnosis, never fills in urgency, discomfort, symptoms, or notes, and is
+never saved until the user confirms it. Abstention is the default; a prefill is the exception.
+
+## Why quality is a gate, not a footnote
+
+`imageQuality` is something the model reports about its own photo. A confident form and colour read
+from a blurry photo is exactly the answer a user is most likely to accept without thinking, so
+confidence alone cannot authorise a prefill. The policy accepts `good` and `fair`; `poor` abstains
+regardless of how confident the reply looked. This is proven end to end by the committed corpus case
+`poor-quality-confident`, which replays a 0.94-confidence answer about the synthetic motion-blur
+fixture and expects an abstention.
+
+## Per-photo gates
+
+Evaluated in this order. The first gate that fails names the refusal, so the user is told the real
+reason rather than a generic one.
+
+| Order | Gate | Refusal (`abstainedFor`) | User-facing copy |
+|---|---|---|---|
+| 1 | Model says the photo is not clearly stool | `not_stool` | The image does not clearly show stool. |
+| 2 | Confidence below `minConfidence` (0.55) | `low_confidence` | The image is too uncertain to prefill safely. |
+| 3 | Form or colour came back blank | `unusable_visual_fields` | The photo does not show a form Timmy can read safely. |
+| 4 | `imageQuality` is below the accepted levels | `low_quality` | The photo is too blurry or poorly lit to suggest a form safely. |
+
+A filled-in field outside the contract (`bristolType` outside 1–7, an unknown `color`, an unknown
+`imageQuality`) is not an abstention — it **fails closed** with no provider detail shown, because a
+caller must never be told "the photo was unreadable" when the model actually returned an impossible
+value. That ordering is covered by the corpus escape cases (`out-of-range-fields`,
+`blank-plus-out-of-range`).
+
+Unknown and out-of-distribution images can only be judged from what the schema lets the model say: it
+must declare `isStool`, a confidence, and a quality. There is no separate OOD channel, and this policy
+does not invent one. A photo the model cannot place therefore lands on `not_stool`, `low_confidence`,
+or `low_quality` — all three abstain.
+
+## Per-release gate
+
+The calibration harness ([`scripts/calibration_report.py`](../scripts/calibration_report.py), issue
+#29) scores candidates on a held-out test split with a threshold selected on validation only. The
+policy turns that report into a single decision with `evaluatePrefillGate(report)`:
+
+| Requirement | Blocked reason if unmet |
+|---|---|
+| Report verdict is `GO` | `calibration-verdict-not-go` |
+| The report names a recommended candidate | `no-recommended-calibration` |
+| That candidate's threshold was selected on `validation` | `threshold-not-selected-on-validation` |
+| That candidate was scored on the held-out `test` split | `gate-not-scored-on-held-out-test` |
+| That candidate passed every release gate | `candidate-failed-release-gates` |
+
+A missing or unreadable report is a block, never a default allow.
+
+Run it as a receipt:
+
+```bash
+python3 scripts/calibration_report.py \
+  --predictions tests/fixtures/calibration/predictions.jsonl \
+  --min-coverage 0.5 --json /tmp/calibration-report.json
+
+node scripts/abstention_policy_receipt.mjs --report /tmp/calibration-report.json
+# exit 0 = prefill authorised, 3 = blocked, 2 = the report could not be read
+```
+
+**Current state:** the committed synthetic predictions produce `BLOCKED`, so the receipt exits 3 and
+names why. No production candidate exists yet — issue #31 (fine-tuned classifier) is the dependency —
+and the policy exists so that candidate is held to one stated contract instead of whatever it happens
+to score. The release builder does not gate on this receipt yet; it records the quality gate on camera
+through the demo instead. Wiring the receipt into `scripts/build_release.py` as a hard prefill gate
+belongs with #31, when there is a candidate to judge.
+
+## Versioning
+
+`ABSTENTION_POLICY.version` is an integer that changes whenever a limit changes. A policy change is a
+behaviour change: the release notes must be able to say which policy produced a suggestion. The
+shipped object is frozen so nothing can tighten or loosen it at runtime; callers that need a
+different policy pass one explicitly (`parseVisionResponse(raw, policy)`), which is how the tests
+prove the parser has no hidden limits of its own.
+
+## What this policy does not do
+
+- It does not decide the Bristol type, the colour, or the quality. It only decides whether to show
+  them.
+- It does not touch deterministic red-flag escalation, which runs independently of model state.
+- It does not read, store, or log an image, and it never inspects inference bodies.
+- It does not set the numeric thresholds from anything but validation data, and it does not convert a
+  `BLOCKED` calibration into a pass.

docs/CORPUS-MANIFEST.md

@@ -0,0 +1,69 @@
+# Corpus manifest contract
+
+The training corpus is described by an **append-only** `manifest.jsonl`. One line is one event;
+nothing is ever rewritten in place, so the trail can be audited after a withdrawal. The
+implementation lives in [`scripts/corpus_manifest.py`](../scripts/corpus_manifest.py) and is
+driven by [`scripts/ingest_training_photo.py`](../scripts/ingest_training_photo.py).
+
+## Sample record (`recordType: "sample"`, schema version 2)
+
+| Field | Meaning |
+|---|---|
+| `contributionId` | Opaque id minted by the app's contribution receipt. The same id addresses every derived artifact and every later tombstone. |
+| `consent.version`, `consent.recordedAt` | The consent version the contributor accepted, and when. Duplicated as `consentVersion` for older readers. |
+| `source.kind`, `source.inputSha256` | How the bytes arrived (`cli-ingest`) and the digest of the caller's input. The caller's path is never recorded. |
+| `hashes.rawInput`, `hashes.derived` | Digest of the supplied bytes and of the re-encoded image that is actually stored. |
+| `derivation` | `format`, `maxDimension`, `metadataStripped`, and the `pipeline` version that produced the derived image. |
+| `review.status`, `review.reviewedAt` | `user-confirmed` or `clinician-reviewed`. A label set is never unlabelled-by-default. |
+| `split` | `train`, `validation`, or `test`, derived from the salted subject key so one contributor never straddles splits. |
+| `subjectKey` | 16-hex pseudonym derived from a salted subject id. Never a name, email, or account. |
+| `lifecycle.state`, `lifecycle.updatedAt` | `active` while the sample is usable for training. |
+| `imageId`, `relativePath` | Derived image digest and its dataset-relative path. |
+
+## Tombstone record (`recordType: "tombstone"`)
+
+A withdrawal never deletes history; it appends a tombstone that:
+
+- keeps `contributionId` and `imageId` so the withdrawal can be matched to the original sample,
+- records `lifecycle.state: "revoked"`, the timestamp, and the reason,
+- lists `deletedArtifacts` — every derived copy it removed, addressed by contribution id with the
+  digest that identifies the bytes,
+- deliberately drops `labels`, `subjectKey`, and `relativePath`: a deletion receipt keeps
+  identifiers and hashes, not the health label or the person.
+
+`revoke()` removes the derived image and any raw pre-derivation copy from the active dataset
+before appending the tombstone, and refuses any path that resolves outside the dataset root.
+
+## Lifecycle rules (all covered by `tests/corpus-manifest.test.py`)
+
+- `active` → `revoked` only, and only with a recorded reason.
+- `revoked` → `active` is refused: a revoked contribution cannot return to the active dataset.
+- Revoking an unknown contribution, or revoking twice, is refused and appends nothing.
+- A contribution id can be ingested once; the same derived image cannot carry two label sets.
+- `active_records()` returns only samples that are still `active` and were never tombstoned, so a
+  trainer that reads through it cannot silently train on withdrawn data.
+
+## Usage
+
+```bash
+export TIMMY_DATASET_SALT=...                       # >= 8 chars, never committed
+python3 scripts/ingest_training_photo.py \
+  --input photo.jpg --output-dir /srv/timmy-corpus \
+  --subject-id subject-123 --consent-version research-v1 \
+  --contribution-id "$CONTRIBUTION_ID" \
+  --bristol-type 4 --color brown --quality good --reviewer user-confirmed
+
+python3 scripts/ingest_training_photo.py --revoke "$CONTRIBUTION_ID" \
+  --output-dir /srv/timmy-corpus --reason "subject withdrawal"
+```
+
+`npm run test:corpus` runs the contract suite. Every fixture is synthetic; no real medical image
+is read, written, or committed.
+
+## Review and adjudication
+
+A manifest says what was ingested and whether the person still allows it. It does not say whether
+the labels are right. That decision lives in a separate append-only ledger,
+`<dataset>/reviews.jsonl`, written by [scripts/review_corpus.py](review_corpus.py) — see
+[REVIEWER-TOOL.md](REVIEWER-TOOL.md). The trainer reads `trainable_records()`, which returns only
+samples that are still active, carry a human decision, and were not excluded.

docs/DATASET_CARD.md

@@ -0,0 +1,104 @@
+# Dataset card — Timmy consented stool-image corpus
+
+Generated by [`scripts/dataset_card.py`](../scripts/dataset_card.py) from the append-only
+corpus manifest. Do not edit this page by hand: regenerate it, or `--check` fails. Every count
+below is read back from `manifest.jsonl`; a fact the pipeline does not collect is printed as
+`pending` rather than estimated, so nothing here is invented.
+
+| Field | Value |
+|---|---|
+| Corpus | `/srv/timmy-corpus` |
+| Corpus present on this machine | no |
+| Last manifest record | pending — no record yet |
+| Active samples | 0 |
+| Contributors | 0 |
+| Withdrawals | 0 |
+| Contexts | pending — not collected by ingest — no setting, time-of-day, or location fields are recorded |
+| Devices | pending — not collected by ingest — no camera, model, or OS fields are recorded |
+| Licenses | pending — no contributor grant is recorded yet, so no license is asserted |
+| Regenerate | `python3 scripts/dataset_card.py --corpus /srv/timmy-corpus` |
+
+## What this corpus is for
+
+Consented photos of stool, labelled by a human reviewer, for research on a stool-form
+classifier. The corpus may not be used to diagnose disease, to identify a person, or to
+train a model that speaks to a patient with clinical authority. A model's output stays
+provisional until the person logging confirms it: see [PRODUCT-DECISIONS.md](PRODUCT-DECISIONS.md).
+
+This corpus holds no consented images yet. Every count of zero below is a real count of
+an empty manifest, not a placeholder, and the pending facts stay pending until the
+pipeline collects them.
+
+## Contributor-level split policy
+
+Splits are derived from the salted pseudonymous subject key, never assigned per photo: the
+first byte of the key decides the split, `< 205` train, `< 230` validation, otherwise test
+(the ingestion rule in `scripts/ingest_training_photo.py`). One contributor's photos all land
+in one split, and this generator refuses a manifest where a subject key appears in two splits
+or where a recorded split is not the one its subject key derives. Both edges are stated here
+so the policy on this page is the policy in the code.
+
+| Split | Contributors | Active samples |
+|---|---:|---:|
+| `train` | 0 | 0 |
+| `validation` | 0 | 0 |
+| `test` | 0 | 0 |
+
+## Class balance (active samples only)
+
+**Type**
+
+| Type | Active samples |
+|---|---:|
+| Type 1 | 0 |
+| Type 2 | 0 |
+| Type 3 | 0 |
+| Type 4 | 0 |
+| Type 5 | 0 |
+| Type 6 | 0 |
+| Type 7 | 0 |
+
+**Color**
+
+| Color | Active samples |
+|---|---:|
+| `brown` | 0 |
+| `green` | 0 |
+| `yellow` | 0 |
+| `pale` | 0 |
+| `red` | 0 |
+| `black` | 0 |
+
+**Quality**
+
+| Quality | Active samples |
+|---|---:|
+| `good` | 0 |
+| `fair` | 0 |
+| `poor` | 0 |
+
+**Review status**
+
+| Review status | Active samples |
+|---|---:|
+| `user-confirmed` | 0 |
+| `clinician-reviewed` | 0 |
+
+A withdrawn sample is excluded from every table above. Labels are what a reviewer saw, not a
+diagnosis: [LABELING_GUIDE.md](LABELING_GUIDE.md) says what a label may and may not assert.
+
+## Exclusions and withdrawals
+
+A withdrawal appends a tombstone, deletes the derived image and any raw copy, and stays in the
+history. Contribution ids and reasons are published here because a deletion receipt is
+checkable; subject keys and labels are never published.
+
+No withdrawals are recorded.
+
+## Limitations
+
+- Composition (devices, contexts, licenses) is pending, so the corpus is not yet a
+  representative sample of anything and must not be described as one.
+- Review status is a human decision, not a clinical gold standard; `user-confirmed` means the
+  person who took the photo agreed with the proposal.
+- A held-out split measures generalization across contributors, not across a population.

docs/EVALUATION-HARNESS.md

@@ -0,0 +1,117 @@
+# Evaluation harness contract
+
+Issue #29 asks for the authoritative comparison and release-gate harness: macro-F1, per-class
+precision/recall, a confusion matrix, calibration error, coverage, and precision-at-coverage, over
+splits that are contributor-held-out and reproducible, comparing candidate models.
+
+The implementation is [`scripts/calibration_report.py`](../scripts/calibration_report.py). It reads
+predictions something else produced, and it refuses to compute gates it cannot honestly compute.
+
+The GO/BLOCKED verdict this report produces is consumed by the production abstention policy in
+[`docs/ABSTENTION-POLICY.md`](ABSTENTION-POLICY.md): a candidate that has not cleared these gates
+cannot authorise a visual prefill.
+
+**This harness does not train, does not diagnose, and never reads an image.** It only sees Bristol
+labels, predictions, and confidences.
+
+## Input
+
+One prediction record per line (JSONL), one file or many:
+
+```json
+{"model":"specialist-candidate","subjectKey":"cd1a2b3c4d5e6f01","split":"validation",
+ "truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.97}}
+```
+
+| Field | Rule |
+|---|---|
+| `model` | Non-empty. Candidates are grouped by this value, so one file may carry several. |
+| `subjectKey` | The 16-hex pseudonymous key from the corpus manifest. Never a name, email, or account. |
+| `split` | `train`, `validation`, or `test`. |
+| `truth.bristolType` | Whole number 1–7. |
+| `prediction` | `{bristolType: 1–7, confidence: 0–1}`, or `null` when the candidate offered nothing. |
+
+A record that breaks any row above is refused (exit 2) rather than scored.
+
+## Splits are contributor-held-out and reproducible
+
+The split rule is the ingestion rule from `scripts/ingest_training_photo.py`: the first byte of the
+subject key picks the bucket — below `205` is `train`, below `230` is `validation`, otherwise `test`.
+Because the rule reads only the pseudonymous key, a split can be re-derived by anyone holding the
+manifest, and a corpus cannot quietly re-label itself.
+
+`assert_contributor_held_out()` refuses:
+
+- a `split` that does not match the one the subject key derives (not reproducible), and
+- one subject key appearing in more than one split (contributor leak) — a held-out score where the
+  model has already seen that person is not held out.
+
+Several photos from one contributor inside one split are fine; that is the normal case.
+
+## Metrics
+
+The harness is a *selective* classifier evaluation. A suggestion is **accepted** when it exists and
+its confidence is at or above the threshold; everything else is an abstention. Two abstention
+reasons are counted separately: `no-suggestion` and `low-confidence`.
+
+| Metric | Definition |
+|---|---|
+| `coverage` | accepted / total in the scored split. |
+| `precisionAtCoverage` | correct / accepted. The gate metric. |
+| `perClass[label]` | `precision`, `recall`, `f1`, `support`, `predicted` over accepted suggestions. |
+| `macroF1` | Mean of `perClass[*].f1` over the classes present in **accepted** truth. A class whose every photo abstained cannot be scored, so it is named in `excludedClasses` instead of being counted as a silent zero. |
+| `confusion` | `"truth->predicted": count` over accepted suggestions. |
+| `ece` | Expected calibration error over accepted suggestions in ten equal-width confidence bins, weighted by each bin's share. |
+
+Calibration is measured on the same accepted set as precision, so a candidate cannot look calibrated
+by abstaining out of its worst bins.
+
+## Threshold protocol
+
+`select_threshold()` takes the coverage floor and returns the threshold with the highest
+precision-at-coverage among the cuts that still clear that floor, breaking ties toward wider coverage.
+It reads the **validation split only** and raises otherwise: choosing a threshold on the data the gate
+is measured on manufactures whatever precision the report needs.
+
+`compare()` therefore fixes one threshold per candidate on validation, scores that candidate on test,
+and never looks back at validation scores.
+
+## Gates
+
+Taken from the ROADMAP release gates. All limits are inclusive — a candidate exactly on the line passes.
+
+| Gate | Limit |
+|---|---|
+| `macroF1` | ≥ 0.80 |
+| `precisionAtCoverage` | ≥ 0.90 |
+| `ece` | ≤ 0.05 |
+
+A candidate must clear all three on its held-out split. `verdict` is `GO` only when at least one
+candidate does; `recommended` is the passing candidate with the highest macro-F1 (then precision).
+Otherwise the verdict is `BLOCKED` and no candidate is recommended.
+
+## Run it
+
+```bash
+python3 scripts/calibration_report.py \
+  --predictions tests/fixtures/calibration/predictions.jsonl \
+  --min-coverage 0.5 --json /tmp/calibration-report.json
+
+npm run test:calibration    # the harness contract suite
+```
+
+| Exit code | Meaning |
+|---|---|
+| 0 | `GO` — a candidate cleared every gate. |
+| 3 | `BLOCKED` — the release gate refuses every candidate. |
+| 2 | Refused — malformed, leaky, or unreproducible input. Nothing was scored or written. |
+
+`--json PATH` writes the full report (per-class rows, confusion matrix, calibration bins, gate detail).
+The report is only written after a successful run.
+
+## Fixtures
+
+[`tests/fixtures/calibration/`](../tests/fixtures/calibration/README.md) holds synthetic predictions
+that exercise `BLOCKED`, `GO`, and the leaked-corpus refusal. They are invented numbers on fabricated
+subject keys: **no model produced them and they say nothing about the real classifier.** Recording a
+video or writing a report from them means saying so.

docs/LABELING_GUIDE.md

@@ -0,0 +1,84 @@
+# Labeling guide — Timmy corpus review
+
+This is the guide a human reviewer follows when labelling a contributed photo in
+[`scripts/review_corpus.py`](../scripts/review_corpus.py). It exists so a label in the corpus means
+the same thing to every reviewer, and so a model trained on those labels cannot quietly inherit a
+clinical claim nobody made. The corpus it describes is summarised, from the manifest and never by
+hand, in [DATASET_CARD.md](DATASET_CARD.md).
+
+A label is an observation. It is **not** a diagnosis, not a severity assessment, and not a statement
+about the person's health.
+
+## What a reviewer may record
+
+Three fields, all of them visible in the photo:
+
+| Field | Vocabulary | Rule |
+|---|---|---|
+| `bristolType` | 1–7 | The Bristol form the sample most resembles, by shape and surface — not by how the person says they feel. |
+| `color` | `brown`, `green`, `yellow`, `pale`, `red`, `black` | The **broad visible color** of the sample in the photo. |
+| `quality` | `good`, `fair`, `poor` | Whether the photo supports a confident form and color call at all. |
+
+`quality` is about the photo, not the person: glare, blur, framing, and distance. A `poor` photo
+belongs in the corpus as a `poor` photo; it is not a reason to guess a higher-quality label, and
+`review_corpus.py` excludes an unclear sample from training instead of filling the gap.
+
+## Color is not blood
+
+The single most damaging mistake available here. Visible color describes what the photo looks like;
+it does not establish that blood is present:
+
+- `red` means **the sample looks reddish in this photo**. It is **not blood**, and it is not
+  "bleeding". A reviewer never writes "blood" into a label, a comment, or an exclusion reason.
+- `black` means **the sample looks black or very dark in this photo**. It is not "melena", not
+  "GI bleed", and not evidence of anything.
+- Neither field may be used to reassure. A `brown` label is **not** a statement that there is no
+  bleeding; a photo cannot rule that out and the app does not claim it can.
+- Blood, black or tarry stool, pain, urgency, fever, or vomiting are **user-reported** facts, asked
+  in words and routed to the deterministic red-flag path. They are never inferred from an image and
+  never stored as a label by this tool.
+
+If the photo genuinely shows something a reviewer believes needs urgent attention, the correct action
+is to stop labelling and escalate to the maintainers — not to encode a clinical judgement in a class.
+
+## Never diagnose
+
+- Do not diagnose, rule out, or name a disease, condition, or cause in any label, comment, or
+  exclusion reason.
+- Do not infer symptoms, pain, urgency, frequency, hydration, diet, medication, or pregnancy.
+- Do not grade severity ("mild", "concerning", "abnormal"). The vocabulary is form, color, and photo
+  quality only.
+- A model suggestion is **provisional input**, never the label. The reviewer's own committed decision
+  is the label; `review_corpus.py` refuses to reveal the model's answer until the reviewer has
+  committed theirs, and records any disagreement beside the proposal rather than averaging it away.
+
+## Exclusions
+
+Exclude a sample when it cannot be labelled honestly:
+
+| Situation | Action |
+|---|---|
+| No stool visible, or the photo is of something else | Exclude: `not-stool`. |
+| Photo too blurred, glared, or distant to judge form | Exclude: `unreadable-photo`. |
+| Two samples in one frame, or ambiguous framing | Exclude: `ambiguous-frame`. |
+| Reviewer believes the image needs urgent clinical attention | **Stop.** Escalate to maintainers; do not label, do not exclude quietly. |
+| Contributor withdrew consent | Not a review decision: the manifest tombstones the contribution and the queue drops it. |
+
+An exclusion is recorded with a reason from the list above. An excluded sample is never training
+data, and re-including it requires a new review, not an edit.
+
+## Splits: one contributor, one split
+
+All of a contributor's photos stay in **one split**, decided by their salted pseudonymous subject key
+(`< 205` train, `< 230` validation, otherwise test — the ingestion rule in
+`scripts/ingest_training_photo.py`). A reviewer never chooses a split, and a reviewer never moves a
+sample between splits to balance a class. If a class is thin, the honest answer is more consented
+contributors, not a leaked one. `scripts/dataset_card.py` refuses to publish a card for a corpus
+where one subject key appears in two splits.
+
+## Reporting a problem with this guide
+
+If a label feels impossible to assign without a clinical judgement, that is a gap in this guide, not
+a licence to improvise. Open an issue against
+[stackchain/timmy-talking-turd](https://forge.alexanderwhitestone.com/git/stackchain/timmy-talking-turd)
+describing the case, without attaching a real medical image.

docs/PRODUCT-DECISIONS.md

@@ -34,6 +34,14 @@ The application’s deterministic urgent-symptom guidance runs before chat and r
 
 Logging must never depend on AI availability. When the vision worker is offline, disabled, or still unknown, the photo-first flow offers no AI action and no analysis-consent prompt, and manual Bristol entry remains one action away from every photo step. A chosen photo and any entered context are retained as an in-session draft with a visible summary and an explicit start over; drafts are deliberately not persisted to storage, so a photo awaiting consent is never written to disk. The service worker never caches analysis requests or image bodies.
 
+### Training contribution consent
+
+Contributing a confirmed photo to training is a second consent, not a side effect of logging. A journal save is never a training contribution; a contribution exists only after the person reads the current consent version and its receipt (contribution id, what is included, what is never included) and accepts it explicitly. The receipt carries the consent version it was accepted under, the confirmed Bristol form and broad color, and no note text, symptom answers, urgency/discomfort ratings, identity, or photo bytes.
+
+Withdrawal is first-class: withdrawal keeps a tombstone naming every derived artifact by contribution id (raw image and confirmed label), so a deletion request can be addressed against the corpus rather than trusted to a promise. Delete-all clears the ledger, saved photos, and contribution receipts together.
+
+This build acknowledges that records the intent and does not transmit a contribution until the corpus pipeline and privacy copy are reviewed in #22 and #25; the section says so in the app rather than implying an upload that does not exist.
+
 ### Release authority
 
 Hermes/Timmy is the release authority for routine engineering, test, build, deployment, and release-candidate preparation. Automated evidence must remain reproducible and must not overstate model accuracy or safety.
@@ -48,6 +56,16 @@ Human gates are limited to:
 
 Routine provisioning, deployment, label sweeps, and release-candidate assembly are not human-operated gates.
 
+### Backup portability and entry provenance
+
+A backup is the person's own record and must keep working as the AI fields evolve.
+
+- Every export stamps a schema version (currently version 2). The same file carries the confirmed logs and the training contribution receipts, including withdrawn tombstones.
+- An older backup is upgraded on import, and the app says which version the file came from. Fields that did not exist when the file was written are left empty rather than invented.
+- A backup from a newer version is refused with an instruction to update Timmy, and a refused import leaves the ledger unchanged.
+- Malformed, oversized, and over-limit files fail before anything is replaced.
+- Provenance is stored on the confirmed log when a saved entry began as a confirmed or corrected AI suggestion: source, suggested visible fields, the model that answered, and when it was confirmed. It never records a diagnosis, a symptom, or provider credentials, and backups are written through an allowlist so unknown keys never leave the device.
+
 ## Consequences
 
 - Model output is assistive and fail-closed, never authoritative.

docs/PRODUCTION-RUNBOOK.md

@@ -0,0 +1,172 @@
+# Production topology, secrets, backup, and rollback
+
+This runbook answers one question for the operator: how do the parts of Timmy run, what may they
+reach, what must never be lost, and how does each part come back? It covers the pieces that exist in
+this tree today — the Node app, the private vision worker, the private staging directory, and the
+consented corpus. It does not describe a training fleet, a cloud account, or a hosted database,
+because this build has none.
+
+Everything below is run by automation or by one operator on the host. Nothing here is performed by a
+participant, and no step needs a public endpoint.
+
+## Topology
+
+| Process | Entry point | Holds | Restart unit |
+|---|---|---|---|
+| App and API | `node server.mjs` on `HOST=127.0.0.1 PORT=4173` | Nothing durable. Serves the PWA, proxies `/api/vision/*`, and gates `/api/agent/*` behind an access code. | `timmy-staging.service` (staging), `node server.mjs` (local) |
+| Vision worker | `deploy/worker/run_worker_container.sh` | The pinned GGUF weights, mounted read-only from the host. | `scripts/run_selfhost_smolvlm.sh start`, container restart policy |
+| Staging releases | `/opt/timmy-staging/releases/<40-character-commit>` with a `current` symlink | Immutable release trees plus the mode-600 environment file. | `timmy-staging.service` |
+| Consented corpus | `/srv/timmy-corpus` | `manifest.jsonl` (append-only provenance and tombstones) and `images/` derived from consented contributions. | none — file data |
+| Caddy | host Caddy | Terminates TLS and routes `/git/` to Gitea and `/timmy-staging/` to the app. | host Caddy |
+
+The app is stateless for a reason: there is **no server-side copy of the journal**. A person's logs
+and photos live in their own browser storage, and they hold the portable JSON backup. The server
+holds no diary, so a lost server loses no one's health record — only the operator records listed
+above can be lost, and only those are backed up here.
+
+Health and readiness are separate, and the probe reports readiness only:
+
+```
+GET /api/healthz  ->  {"ok":true,"release":"<tag>","commit":"<commit>","visionEnabled":<bool>,"agentEnabled":<bool>}
+```
+
+`visionEnabled` and `agentEnabled` say whether the feature is configured, never which key or endpoint
+is configured. The worker answers `/v1/models` before its pinned model is resident, so readiness
+means "served a request from the loaded model", not "the port is open" — `scripts/worker_ready.sh`
+enforces that distinction and the app withholds the AI control until it passes.
+
+## Network boundaries
+
+- The app reads `HOST` and its own default is `0.0.0.0`, which is a local-development convenience and
+  not the deployment. The deployment sets `HOST=127.0.0.1` in the mode-600 environment file
+  (`deploy/timmy-staging.env.example` is the template) and is reachable from outside solely through
+  the Caddy `/timmy-staging/` subpath. A bare `node server.mjs` on a shared host listens on every
+  interface — treat that as a laptop command, never as a production start.
+- The Gitea `/git/` catch-all is declared before the staging route and must stay reachable across
+  every Caddy reload.
+- The vision worker binds `127.0.0.1:8080` and is never published: `deploy/worker/run_worker_container.sh`
+  refuses a non-loopback publish host instead of warning about it, and no route in `server.mjs`
+  forwards arbitrary paths to the worker — the only vision endpoints are `/api/vision-status` and the
+  analysis request.
+- Outbound from the host is limited to the pinned model download during bootstrap, which is refused
+  unless both SHA-256 receipts match. After that the worker needs no egress at all.
+- Inference bodies and image bytes are never logged, and no reverse-proxy access log retains a
+  request body. A backup that contained them would be a second copy of someone's photo, so they are
+  excluded by the tool rather than by the operator remembering.
+- No participant-facing endpoint requires an inbound port, a DNS record, or a cloud credential.
+
+## Secrets
+
+Four secrets exist, and every one of them is injected at runtime:
+
+| Secret | Source | Scope |
+|---|---|---|
+| `TIMMY_DATASET_SALT` | mode-600 environment file on the host | Corpus subject keys and split assignment. Rotating it re-splits future ingests, so it is not rotated casually. |
+| Vision provider key or worker token | mode-600 environment file on the host | Only the app process reads it; the browser never receives it. |
+| Agent access code | mode-600 environment file on the host | Unlocks `/api/agent/unlock`; the cookie it mints is `HttpOnly` and same-origin. |
+| Gitea access token | local operator shell or secret store | Issue and PR automation only. It is never written into a release tree, an archive, or a log. |
+
+Rules:
+
+- Never commit a secret, and never pass one on a command line that lands in shell history. Use the
+  environment file (`chmod 600`, owned by the service user) or the systemd `EnvironmentFile=`.
+- Placeholders in this document are angle-bracketed or environment references, e.g.
+  `TIMMY_DATASET_SALT=<random 32+ characters, never committed>`. A literal value here is a bug.
+- `scripts/build_release.py` scans the cloned tree for private-key blocks and assigned credentials
+  and fails the release if it finds one, so a secret that reaches a commit is caught before it
+  reaches a release.
+- Rotation is: issue the replacement on the host, restart the unit, confirm `/api/healthz` and one
+  real inference request, then revoke the old value in the provider's own UI. Nothing in Git holds a
+  copy that would need rewriting.
+- The backup tool refuses `.env`, `*.env`, `*.key`, `*.pem`, `id_rsa`, `tokens.json`, and
+  `credentials.json` by name, so a backup can be copied off-host without carrying the keys that
+  operate the host.
+
+## Backup
+
+The operator records that cannot be rebuilt are the corpus `manifest.jsonl` and the derived images
+it points at. A tombstone is the only proof that a participant withdrew, so a backup that drops
+tombstone lines silently re-authorises training on withdrawn data. The tool treats that as a
+correctness bug, not a storage detail.
+
+`scripts/operator_backup.py` archives **only** records, and writes one manifest naming every byte it
+stored and every path it refused:
+
+- Stored: `manifest.jsonl`, derived images, and any receipt files under the data root.
+- Excluded, with the reason recorded: **model weights** (`model-weights` — re-downloadable, pinned by
+  hash), **transient inference** directories and uploads (`transient-inference` — a second copy of
+  someone's photo), **secret** files (`secret`), logs (`log`), symlinks (`symlink`), and anything over
+  `--max-bytes` (`oversize`).
+- Every stored member carries a SHA-256, and the archive is reproducible: sorted members, zeroed
+  timestamps and ownership, `gzip` with a fixed mtime. Two backups of unchanged records are
+  byte-identical, so "did anything change?" is answerable by digest.
+
+```bash
+python3 scripts/operator_backup.py backup --source /srv/timmy-corpus --archive /srv/backups/timmy-nightly.tar.gz --label nightly
+python3 scripts/operator_backup.py verify --archive /srv/backups/timmy-nightly.tar.gz --manifest /srv/backups/timmy-nightly.tar.gz.manifest.json
+```
+
+The command writes `<archive>.manifest.json` unless `--manifest` names another path, and prints a
+receipt with the stored file count, archive digest, and record counts (`samples`, `tombstones`,
+`activeSamples`). It refuses a source that is not a directory and refuses to overwrite an existing
+archive, so a nightly run cannot erase the previous night.
+
+Retention: keep fourteen nightlies and the first backup of each month, and copy each archive plus its
+manifest off-host. Also keep a human-readable record of the counts: `verify` compares the archive
+against the manifest, and a restore compares the restored counts against both.
+
+What this backup deliberately does not cover: the browser-held journal (there is no server copy; the
+person's own portable export is the backup), model weights, and anything in the release tree, which
+is rebuilt from a commit by `scripts/build_release.py`.
+
+## Restore
+
+A restore never writes over live data. It verifies first, and it writes into a directory that must
+not exist or must be empty:
+
+```bash
+python3 scripts/operator_backup.py restore --archive /srv/backups/timmy-nightly.tar.gz --manifest /srv/backups/timmy-nightly.tar.gz.manifest.json --target /srv/timmy-corpus.restore-check
+```
+
+In order, before the first byte is written:
+
+1. the manifest is loaded and its `schemaVersion` checked;
+2. every archive member is refused if it is a link, a non-regular file, an absolute path, a traversal
+   path, or a name the manifest never listed;
+3. every member's SHA-256 is recomputed and compared, and a mismatch stops the restore;
+4. a member the manifest lists but the archive lacks stops the restore.
+
+After the extract it recounts `manifest.jsonl` in the target and refuses if the counts differ from
+the backup, so a restore that silently lost a tombstone fails loudly. Then the operator compares the
+restored tree against the live one, and promotes it by moving the directories — the tool does not
+pretend to know which directory is authoritative.
+
+Restoring the person's own logs is a different operation and stays where it belongs: the app's
+import control accepts the JSON file they exported, upgrades an older version and says which version
+it read, and refuses a file from a newer Timmy without touching the ledger it would have replaced.
+
+## Rollback
+
+Two rollbacks exist, and only one of them is a live staging action.
+
+**Release rollback (staging).** Staging keeps one immutable directory per commit and a `current`
+symlink, so a rollback is a repoint, a restart, and a bounded health check that restores and verifies
+the previous release if the new one does not come up:
+
+```bash
+python3 scripts/deploy_staging.py status
+python3 scripts/deploy_staging.py rollback --commit <FULL_COMMIT>
+```
+
+The rollback path is exercised by `tests/staging-deploy.test.py`, which drives the real
+`scripts/deploy_staging.py` code against a rootless fixture (`--root`), including the case where the
+named commit has no immutable release directory, where the restart fails, and where the health probe
+never passes. That is the same code path the host runs; the difference is only the root.
+
+The live drill on the private staging host — promote a build, serve it, roll it back, and confirm the
+participant-facing page again — is a **human gate**, tracked under #53. This loop does not run that
+drill automatically, because a rolled-back staging host is being used for release testing at the time.
+
+**Data rollback (operator records).** The equivalent for the corpus is the restore above: verify,
+restore into a new directory, compare counts, then move it into place. A restore is never attempted in
+place, and a failed verify leaves the live directory untouched.

docs/RC-SECURITY-EVIDENCE.md

@@ -0,0 +1,80 @@
+# RC Security & Abuse Evidence (#40)
+
+The release candidate is attacked before users get to it. This page is the procedure and the rule,
+not a stored result: a pasted-in "all clear" is exactly the kind of evidence that stops being true
+after the next commit.
+
+## Run it
+
+```bash
+node scripts/security_attack_suite.mjs --json artifacts/security/rc-attack-report.json
+```
+
+Exit codes are part of the contract:
+
+| Exit | Meaning |
+|---:|---|
+| `0` | `VERDICT: GO` — every case matched its expectation. |
+| `1` | `VERDICT: BLOCKED` — at least one P0 case failed, or a required category has no executable evidence. |
+| `2` | The suite could not complete (target never became ready, vision disabled, no log captured). |
+
+The suite is a child process of nothing: it starts its own copy of `server.mjs` on a free loopback
+port, points it at a **counting stub worker**, and drives it with synthetic hostile bytes. It never
+contacts a real model provider, never uses a real medical image, and never touches a live user's data.
+
+## What it does and does not prove
+
+- It proves what this HTTP boundary did with the bytes it was handed, and whether the worker behind
+  it was called. The worker is a stub, so "the provider saw it" is a counted fact, not an inference.
+- It does **not** measure model quality, clinical accuracy, or the safety of the medical/non-diagnostic
+  boundary. Those live in the vision, escalation, and clinical-review issues.
+- Latency numbers describe the loopback boundary against a stub. They are not a model benchmark.
+
+## Cases
+
+| Case | Class | Severity | Expectation |
+|---|---|---:|---|
+| `ingress-oversized-body` | oversized | P0 | `413`, worker never called |
+| `ingress-polyglot-html` | polyglot | P0 | `400`, worker never called |
+| `ingress-garbage-bytes` | truncated | P0 | `400`, worker never called |
+| `consent-required` | consent | P0 | `400`, worker never called |
+| `model-output-malformed` | malformed | P0 | `503` neutral copy, provider text never echoed |
+| `replay-duplicate-request` | replay | P2 | identical answer, nothing stored server-side |
+| `flood-concurrency` | flood | P1 | burst meets a bound (`429`/overload), not an open pipe |
+| `log-leak-scan` | log | P0 | captured server log carries no image bytes |
+| `deletion-withdrawal` | deletion | P0 | out of surface — counted only when `tests/training-contribution.test.js` exists |
+
+## The rule
+
+`src/release-security-gate.js` owns the verdict, so it is testable rather than asserted:
+
+- A case passes only when **every** expected field matches the observation. A partial match fails and
+  names the field that broke (`status 400 expected, observed 200`).
+- **Any** failing P0 case blocks RC approval. P1/P2 failures are recorded as holds.
+- A required class with no executable evidence is `unproven` and blocks the release. Coverage may be
+  borrowed from another suite (`out-of-surface` + an evidence path) only after the runner verified
+  that file exists — otherwise it blocks.
+- The report is redacted before it is written, and assembly fails closed if any image bytes survive
+  redaction. Evidence that carries a photo is worse than no evidence.
+
+## Current state (read the run, not this line)
+
+This section used to predict **BLOCKED** until the ingress hardening in
+[#16](https://forge.alexanderwhitestone.com/git/stackchain/timmy-talking-turd/issues/16) landed. With
+that ingress in place the same command returns **GO** on this tree, because the format is decided from
+the bytes rather than the data-URL label: `ingress-polyglot-html` and `ingress-garbage-bytes` are now
+refused with `400` before the worker is called, and an oversized body is refused with a `413` the
+caller can read instead of a dropped connection. Latency for the load phase is measured against a
+second target with the request budget opened up, so those samples are analyses rather than `429`
+refusals. Queue bounding is still [#17](https://forge.alexanderwhitestone.com/git/stackchain/timmy-talking-turd/issues/17)
+and is held here as P1.
+
+Deletion is governed by the contribution ledger, not by this HTTP boundary; the case stays
+`covered-elsewhere` against `tests/training-contribution.test.js` and blocks if that file disappears.
+
+## Evidence hygiene
+
+- The report is written to `artifacts/security/` and must never be committed with a real photo in it.
+- The captured server log is scanned by the same detector (`containsImageBytes`) before it is quoted.
+- Error bodies are recorded as a 120-character snippet; the suite refuses to write a report that
+  still contains a data URI or a long base64 run.

docs/REVIEWER-TOOL.md

@@ -0,0 +1,93 @@
+# Blind review and adjudication tool
+
+Contract for `scripts/review_corpus.py`, the labeling control named in the
+[photo data-flow threat model](PHOTO-DATAFLOW-THREAT-MODEL.md) and the gate in front of the
+[training corpus](CORPUS-MANIFEST.md). Issue [#26](https://forge.alexanderwhitestone.com/git/stackchain/timmy-talking-turd/issues/26).
+
+The tool decides which samples a trainer is allowed to read. It is a command-line tool, not a
+screen in the app: there is no reviewer UI, and nothing here implies one.
+
+## The four invariants
+
+1. **The model answer is withheld until a human commits.** `build_queue()` takes no predictions at
+   all, so the queue cannot leak an answer it never receives. `reveal()` refuses to return anything
+   for a contribution with no committed review.
+2. **History is append-only.** A review is a line in `reviews.jsonl`. An adjudication is another
+   line that names the record it resolves (`resolvesRecord`, `resolves`). The review being
+   overruled is never edited, and no record is deleted.
+3. **A withdrawal beats every other answer.** A revoked contribution cannot be queued, reviewed,
+   revealed, adjudicated, or trained on. The refusal says it was withdrawn — not that it is
+   already reviewed — because the person's withdrawal is the fact that matters.
+4. **Unreviewed and excluded samples are not training data.** `trainable_records()` returns only
+   samples that are still active, carry a human decision, and were not excluded.
+
+## Review ledger records
+
+One JSON object per line in `<dataset>/reviews.jsonl`:
+
+```json
+{"schemaVersion":1,"recordType":"review","contributionId":"...","imageId":"<sha256>","proposed":{"bristolType":4,"color":"brown","quality":"good"},"reviewer":"reviewer-a","decision":"corrected","labels":{"bristolType":5,"color":"green","quality":"fair"},"committedAt":"2026-10-27T09:00:00+00:00"}
+{"schemaVersion":1,"recordType":"adjudication","contributionId":"...","imageId":"<sha256>","resolvesRecord":1,"resolves":{"reviewer":"reviewer-a","decision":"corrected"},"reviewer":"reviewer-b","decision":"upheld","labels":{"bristolType":5,"color":"green","quality":"fair"},"adjudicatedAt":"2026-10-27T10:00:00+00:00"}
+```
+
+- `proposed` copies the labels the reviewer judged, so a later manifest change cannot rewrite what
+  was reviewed.
+- `decision` is `agreed`, `corrected`, or `excluded` for a review, and `upheld`, `corrected`, or
+  `excluded` for an adjudication. An exclusion carries `exclusionReason` and no labels.
+- The ledger never carries `subjectKey`, note text, symptom answers, or image bytes.
+
+## A model answer file
+
+`reveal` reads predictions only to show what the reviewer could not see. A file may be one JSON
+document or one object per line:
+
+```json
+{"model":"<name>","answers":{"<contributionId>":{"bristolType":6,"color":"brown","quality":"good","confidence":0.71}}}
+```
+
+Keys may be contribution ids or derived image digests. `reveal` is a read: it appends nothing.
+When no answer file is supplied, `model` is `null` — the tool does not invent an answer.
+
+## Usage
+
+```bash
+python3 scripts/review_corpus.py queue --dataset /srv/timmy-corpus
+python3 scripts/review_corpus.py review --dataset /srv/timmy-corpus \
+  --contribution "$CONTRIBUTION_ID" --reviewer reviewer-a --bristol 5 --color green --quality fair
+python3 scripts/review_corpus.py reveal --dataset /srv/timmy-corpus \
+  --contribution "$CONTRIBUTION_ID" --predictions answers.json
+python3 scripts/review_corpus.py adjudicate --dataset /srv/timmy-corpus \
+  --contribution "$CONTRIBUTION_ID" --reviewer reviewer-b --upheld
+python3 scripts/review_corpus.py trainable --dataset /srv/timmy-corpus
+```
+
+Every mutating command prints the record it appended. A refusal exits `2` and prints one line of
+plain copy on stderr.
+
+## Refusals (all covered by `tests/corpus-review.test.py`)
+
+| Attempt | Result |
+|---|---|
+| Review or reveal a withdrawn contribution | refused: `was withdrawn and cannot be reviewed, revealed, or trained on` |
+| Reveal before any review is committed | refused: `stays hidden until a review is committed` |
+| Review the same contribution twice | refused; adjudication is the only way to change a decision |
+| Correct a label to the value it already has | refused: a correction must change it |
+| Review with a blank reviewer id | refused |
+| Exclude without a reason | refused |
+| Review a contribution that has no active sample | refused |
+| Queue an active sample whose image is missing | refused: a reviewer cannot judge a file that is not there |
+| Adjudicate your own review | refused: adjudication needs a second reviewer |
+| Adjudicate twice | refused |
+| Adjudicate a contribution with no review | refused |
+
+## Known limits
+
+- One review per contribution, resolved by at most one adjudication. Re-review after an
+  adjudication would need a new record type; it is not implemented.
+- The tool does not measure or validate a model. It records what a human decided and what a model
+  answered, so the disagreement can be counted later.
+- It does not train, split, or export a dataset; `trainable_records()` is the list a trainer may
+  read, not a trainer.
+
+`npm run test:review` runs the contract suite. Every fixture is the committed synthetic image; no
+real medical image is read, written, or committed.

package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "node --test tests/domain.test.js tests/analysis.test.js tests/vision-service.test.js tests/vision-config.test.js tests/draft.test.js tests/suggestion.test.js tests/followup.test.js tests/vision-readiness.test.js tests/hermes-agent-service.test.js tests/agent-gateway.acceptance.test.js tests/staging-health.test.js tests/service-worker-runtime.test.js tests/training-ingest.test.js tests/ci-workflow.test.js tests/product-decisions.test.js tests/release-demo.test.js tests/selfhost-bootstrap.test.js tests/staging-config.test.js tests/threat-model.test.js tests/vision-corpus.test.js tests/vision-boundary.test.js tests/worker-benchmark.test.js tests/worker-ready.test.js tests/worker-container.test.js tests/summary.test.js tests/escalation-regression.test.js tests/grounded-chat.test.js tests/photo-lifecycle.test.js tests/image-ingress.test.js tests/rate-limit.test.js tests/http-body.test.js tests/analyze-ingress.acceptance.test.js",
+    "test": "node --test tests/domain.test.js tests/analysis.test.js tests/vision-service.test.js tests/vision-config.test.js tests/draft.test.js tests/suggestion.test.js tests/followup.test.js tests/vision-readiness.test.js tests/hermes-agent-service.test.js tests/agent-gateway.acceptance.test.js tests/staging-health.test.js tests/service-worker-runtime.test.js tests/training-ingest.test.js tests/ci-workflow.test.js tests/product-decisions.test.js tests/release-demo.test.js tests/selfhost-bootstrap.test.js tests/staging-config.test.js tests/threat-model.test.js tests/vision-corpus.test.js tests/vision-boundary.test.js tests/worker-benchmark.test.js tests/worker-ready.test.js tests/worker-container.test.js tests/summary.test.js tests/escalation-regression.test.js tests/grounded-chat.test.js tests/photo-lifecycle.test.js tests/training-contribution.test.js tests/portability.test.js tests/abstention-policy.test.js tests/release-security-gate.test.js tests/image-ingress.test.js tests/rate-limit.test.js tests/http-body.test.js tests/analyze-ingress.acceptance.test.js",
     "test:ui": "node tests/ui.acceptance.mjs",
     "test:photo": "node tests/photo-first.acceptance.mjs",
     "test:mobile-capture": "node tests/mobile-capture.acceptance.mjs",
@@ -18,10 +18,20 @@
     "test:pattern-summary": "node tests/pattern-summary.acceptance.mjs",
     "test:grounded-chat": "node tests/grounded-chat.acceptance.mjs",
     "test:photo-lifecycle": "node tests/photo-lifecycle.acceptance.mjs",
-    "check:syntax": "node --check app.js && node --check server.mjs && node --check service-worker.js && node --check src/image-ingress.js && node --check src/rate-limit.js && node --check src/http-body.js && node --check src/analysis.js && node --check src/domain.js && node --check src/draft.js && node --check src/suggestion.js && node --check src/followup.js && node --check src/vision-readiness.js && node --check src/hermes-agent-service.js && node --check src/vision-config.js && node --check src/vision-service.js && node --check src/vision-corpus.js && node --check src/summary.js && node --check src/photo-lifecycle.js && node --check src/grounded-chat.js && node --check scripts/record_release_demo.mjs && node --check tests/staging.acceptance.mjs && node --check tests/manual-fallback.acceptance.mjs && node --check tests/provisional-suggestion.acceptance.mjs && node --check tests/followup.acceptance.mjs && node --check tests/vision-refusal.acceptance.mjs && bash -n scripts/bootstrap_selfhost_smolvlm.sh && bash -n scripts/run_selfhost_smolvlm.sh && python3 -m py_compile scripts/ingest_training_photo.py scripts/build_release.py scripts/deploy_staging.py scripts/build_vision_corpus.py && node --check scripts/record_worker_benchmark.mjs && node --check tests/worker-readiness.acceptance.mjs && node --check tests/pattern-summary.acceptance.mjs && node --check tests/photo-lifecycle.acceptance.mjs && node --check tests/grounded-chat.acceptance.mjs && bash -n scripts/worker_ready.sh && bash -n deploy/worker/entrypoint.sh && bash -n deploy/worker/build_image.sh && bash -n deploy/worker/run_worker_container.sh && node --check tests/ingress-capture.acceptance.mjs && node --check tests/analyze-ingress.acceptance.test.js",
+    "test:training-contribution": "node tests/training-contribution.acceptance.mjs",
+    "check:syntax": "node --check app.js && node --check server.mjs && node --check service-worker.js && node --check src/analysis.js && node --check src/domain.js && node --check src/draft.js && node --check src/suggestion.js && node --check src/followup.js && node --check src/vision-readiness.js && node --check src/hermes-agent-service.js && node --check src/vision-config.js && node --check src/vision-service.js && node --check src/vision-corpus.js && node --check src/summary.js && node --check src/photo-lifecycle.js && node --check src/grounded-chat.js && node --check src/training-contribution.js && node --check src/abstention-policy.js && node --check src/release-security-gate.js && node --check scripts/security_attack_suite.mjs && node --check tests/security-attack.acceptance.mjs && node --check scripts/record_release_demo.mjs && node --check tests/staging.acceptance.mjs && node --check tests/manual-fallback.acceptance.mjs && node --check tests/provisional-suggestion.acceptance.mjs && node --check tests/followup.acceptance.mjs && node --check tests/vision-refusal.acceptance.mjs && bash -n scripts/bootstrap_selfhost_smolvlm.sh && bash -n scripts/run_selfhost_smolvlm.sh && python3 -m py_compile scripts/corpus_manifest.py scripts/review_corpus.py scripts/dataset_card.py scripts/ingest_training_photo.py scripts/build_release.py scripts/deploy_staging.py scripts/build_vision_corpus.py scripts/calibration_report.py scripts/operator_backup.py && node --check scripts/record_worker_benchmark.mjs && node --check scripts/abstention_policy_receipt.mjs && node --check tests/worker-readiness.acceptance.mjs && node --check tests/pattern-summary.acceptance.mjs && node --check tests/photo-lifecycle.acceptance.mjs && node --check tests/training-contribution.acceptance.mjs && node --check tests/portability.acceptance.mjs && node --check tests/grounded-chat.acceptance.mjs && bash -n scripts/worker_ready.sh && bash -n deploy/worker/entrypoint.sh && bash -n deploy/worker/build_image.sh && bash -n deploy/worker/run_worker_container.sh && node --check src/image-ingress.js && node --check src/rate-limit.js && node --check src/http-body.js && python3 -m py_compile scripts/ingest_training_photo.py scripts/build_release.py scripts/deploy_staging.py scripts/build_vision_corpus.py && node --check tests/ingress-capture.acceptance.mjs && node --check tests/analyze-ingress.acceptance.test.js",
     "check:diff": "bash scripts/check_diff.sh",
     "start": "node server.mjs",
-    "test:worker-readiness": "node tests/worker-readiness.acceptance.mjs"
+    "test:worker-readiness": "node tests/worker-readiness.acceptance.mjs",
+    "test:portability": "node tests/portability.acceptance.mjs",
+    "test:corpus": "python3 tests/corpus-manifest.test.py",
+    "test:calibration": "python3 tests/calibration-harness.test.py",
+    "test:policy": "node --test tests/abstention-policy.test.js",
+    "test:review": "python3 tests/corpus-review.test.py",
+    "test:dataset-card": "python3 tests/dataset-card.test.py",
+    "test:backup": "python3 tests/backup-restore.test.py",
+    "test:runbook": "python3 tests/production-runbook.test.py",
+    "test:security-attack": "node tests/security-attack.acceptance.mjs"
   },
   "devDependencies": {
     "playwright": "^1.62.1"

scripts/abstention_policy_receipt.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Executable receipt for the production abstention policy (issue #32).
+//
+// The calibration harness decides GO/BLOCKED for a candidate model. This reads that report and
+// answers the only question the app cares about: may a suggestion be shipped at all? It exits 3 when
+// prefill is blocked, so a release step can gate on it instead of reading prose.
+//
+// There is no model candidate yet (#31), so in practice this receipt reports BLOCKED today. That is
+// the honest state: the policy is ready, the evidence is not.
+import { readFile } from 'node:fs/promises';
+import { ABSTENTION_POLICY, evaluatePrefillGate } from '../src/abstention-policy.js';
+
+function parseArgs(argv) {
+  const args = { report: '' };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--report') {
+      args.report = argv[i + 1] || '';
+      i += 1;
+    } else throw new Error(`unknown argument: ${argv[i]}`);
+  }
+  if (!args.report) throw new Error('--report <calibration-report.json> is required');
+  return args;
+}
+
+let args;
+try {
+  args = parseArgs(process.argv.slice(2));
+} catch (error) {
+  console.error(error.message);
+  process.exit(2);
+}
+
+let report;
+try {
+  report = JSON.parse(await readFile(args.report, 'utf8'));
+} catch (error) {
+  console.error(`could not read the calibration report at ${args.report}: ${error.message}`);
+  process.exit(2);
+}
+
+const gate = evaluatePrefillGate(report);
+const policy = ABSTENTION_POLICY;
+console.log('TIMMY ABSTENTION POLICY RECEIPT');
+console.log(`policy: version ${policy.version} · confidence ≥ ${policy.minConfidence.toFixed(2)} · quality ${policy.acceptedImageQuality.join('|')}`);
+console.log(`calibration: verdict ${gate.verdict} · model ${gate.calibrationModel || 'none'}`);
+console.log(gate.prefillAllowed
+  ? `prefill: AUTHORISED for ${gate.calibrationModel}`
+  : `prefill: BLOCKED — ${gate.blockedBy.join(', ')}`);
+process.exit(gate.prefillAllowed ? 0 : 3);

scripts/build_release.py

@@ -9,6 +9,7 @@ import os
 from pathlib import Path
 import re
 import shutil
+import socket
 import subprocess
 import sys
 import tarfile
@@ -45,6 +46,7 @@ DEMO_REQUIRED_CAPTIONS = (
     "A tarry note already saved in the journal escalates the same way, before any provider call",
     "An out-of-range answer fails closed: nothing is applied and no provider detail reaches you",
     "A filled-in field that is out of range still fails closed, even when the other field came back blank",
+    "A confident reply about a blurry photo still abstains — photo quality is part of the policy, not just confidence",
     "Reachable is not loaded: no AI control, no consent, and no upload until the pinned model is resident",
     "Every pattern line names the confirmed logs behind it, and following one shows exactly those records",
     "Two logs is not a pattern: the summary refuses to describe a trend it cannot support",
@@ -52,6 +54,33 @@ DEMO_REQUIRED_CAPTIONS = (
     "The answer states the count and cites the four confirmed logs it counted",
     "Following a citation opens exactly the confirmed log behind that answer",
     "Ask something the journal cannot answer and Timmy refuses instead of reassuring",
+    "Training contribution is off by default: a saved log is never training data",
+    "The consent version and the receipt are on screen before the contribute button works",
+    "Withdrawing keeps a tombstone naming every derived artifact by contribution ID",
+    "The corpus pipeline is a command-line tool, not a screen in the app — this runs the real ingest against the committed synthetic fixture",
+    "Every ingested sample records consent, source digest, both hashes, derivation, review, and lifecycle — the caller file path is never stored",
+    "Withdrawing deletes the derived image and any raw copy, keeps the original record, and appends a tombstone — the trainer sees zero active samples",
+    "Revoking the same contribution twice is refused and appends nothing: the manifest only ever grows",
+    "The calibration harness is a command-line release gate, not a screen in the app — this runs it against committed synthetic predictions",
+    "Every score on this card is invented to exercise the arithmetic: no model produced them and none of them describes the real classifier",
+    "Each candidate is scored on test at a threshold chosen on validation only; picking a threshold on the split you report is refused",
+    "One contributor spread across two splits is refused before anything is scored, and a passing verdict is proven only by a fixture engineered to clear it",
+    "A backup is versioned, and it carries the withdrawn receipt as a tombstone rather than silence",
+    "An older backup is upgraded on import, and the notice says which version the file came from",
+    "A file from a newer Timmy is refused with an instruction, and the ledger it would have replaced is untouched",
+    "A restored log still says it began as an AI suggestion you corrected — provenance is part of the record",
+    "The review tool is a command line, not a screen in the app — this runs it against the committed synthetic sample",
+    "The queue shows the proposal and hides the model answer; revealing it is refused until a reviewer commits",
+    "The model said Type 6 and the reviewer said Type 5: the disagreement is recorded, not smoothed over",
+    "Withdrawing the contribution empties the queue and the training set, and the tool refuses to review it at all",
+    "The dataset card is generated from the corpus manifest, so no count on it is typed by hand",
+    "The operator backup is a command line, not a screen in the app",
+    "Model weights and transient inference images are refused by name, and every skipped path is listed with its reason",
+    "Verify re-hashes every stored member against the manifest, and the restore only starts once that check passes",
+    "A restore returns the same records, including the withdrawal tombstone a trainer must never lose",
+    "One contributor's photos stay in one split: a corpus that leaks a person across splits is refused",
+    "Devices, contexts, and licenses stay pending until the pipeline collects them",
+    "The card is a page, not a screen in the app — it is published with the real generator against synthetic fixtures",
 )
 
 
@@ -70,6 +99,29 @@ def sha256(path: Path) -> str:
     return digest.hexdigest()
 
 
+def assert_port_free(host: str, port: int) -> None:
+    """Fail closed when something is already listening where the acceptance server must bind."""
+    with socket.socket() as sock:
+        sock.settimeout(1.0)
+        if sock.connect_ex((host, port)) == 0:
+            raise SystemExit(
+                f"Port {port} is already served by another process; refusing to gate or record this "
+                "release against a tree that is not the one under test."
+            )
+
+
+def assert_served_tree(tree: Path, host: str, port: int) -> None:
+    """Prove the responding server is the clone under test, not a stale checkout on the same port."""
+    for relative in ("src/domain.js", "app.js"):
+        served = urllib.request.urlopen(f"http://{host}:{port}/{relative}", timeout=5).read()
+        expected = (tree / relative).read_bytes()
+        if hashlib.sha256(served).hexdigest() != hashlib.sha256(expected).hexdigest():
+            raise SystemExit(
+                f"The acceptance server is serving {relative} from a different tree; "
+                "every gate and the demo would describe a release that is not this commit."
+            )
+
+
 def tracked_files(tree: Path) -> list[str]:
     names = run(["git", "ls-files"], tree, capture=True).splitlines()
     return sorted(name for name in names if name and not name.startswith(EXCLUDED_PREFIXES)
@@ -125,8 +177,27 @@ def main() -> int:
         run(["npm", "test"], tree)
         # The committed corpus hashes are an integrity receipt: verify them before anything is built.
         run(["python3", "scripts/build_vision_corpus.py", "--verify"], tree)
+        # Issue #25's corpus pipeline is a CLI, so its own suite is a release gate, not just CI.
+        run(["python3", "tests/corpus-manifest.test.py", "-v"], tree)
+        # Issue #26's review tool decides which samples a trainer may read, so the blindness and
+        # withdrawal rules it enforces are a release gate too.
+        run(["python3", "tests/corpus-review.test.py", "-v"], tree)
+        # Issue #27 publishes a dataset card from the manifest, so the generator that decides what
+        # a stranger reads about the corpus is exercised before this release exists.
+        run(["python3", "tests/dataset-card.test.py", "-v"], tree)
+        # Issue #29's evaluation harness decides GO/BLOCKED for a model, so its refusal and gate
+        # arithmetic are exercised before this release is allowed to exist.
+        run(["python3", "tests/calibration-harness.test.py", "-v"], tree)
+        # Issue #39's operator backup is the only copy of the corpus tombstones, so the tool that
+        # produces it, and the runbook whose commands must stay real, are gated before the release.
+        run(["python3", "tests/backup-restore.test.py", "-v"], tree)
+        run(["python3", "tests/production-runbook.test.py", "-v"], tree)
         server_env = dict(os.environ)
         server_env.update({"HOST": "127.0.0.1", "PORT": "4173", "TIMMY_VISION_ENABLED": "false"})
+        # A leftover server from another checkout answers on this port and the readiness probe cannot
+        # tell it apart from ours, so every gate and the recorded demo would silently describe a
+        # different tree. Refuse to build over a live listener, and verify the served bytes afterwards.
+        assert_port_free("127.0.0.1", 4173)
         server_log = (release_dir / "acceptance-server.log").open("w", encoding="utf-8")
         server = subprocess.Popen(["node", "server.mjs"], cwd=tree, env=server_env,
                                   stdout=server_log, stderr=subprocess.STDOUT, text=True)
@@ -141,6 +212,9 @@ def main() -> int:
                     time.sleep(0.1)
             else:
                 raise SystemExit("Acceptance server did not become ready")
+            if server.poll() is not None:
+                raise SystemExit("Acceptance server exited after reporting ready")
+            assert_served_tree(tree, "127.0.0.1", 4173)
             run(["npm", "run", "test:ui"], tree)
             run(["npm", "run", "test:photo"], tree)
             run(["npm", "run", "test:mobile-capture"], tree)
@@ -154,6 +228,8 @@ def main() -> int:
             run(["npm", "run", "test:pattern-summary"], tree)
             run(["npm", "run", "test:grounded-chat"], tree)
             run(["npm", "run", "test:photo-lifecycle"], tree)
+            run(["npm", "run", "test:training-contribution"], tree)
+            run(["npm", "run", "test:portability"], tree)
             demo_raw = release_dir / f"timmy-talking-turd-{version}-demo.raw.webm"
             caption_receipt = release_dir / f"timmy-talking-turd-{version}-demo-captions.json"
             demo_env = dict(server_env)
@@ -201,7 +277,7 @@ def main() -> int:
         if not contact_sheet.exists() or contact_sheet.stat().st_size == 0:
             raise SystemExit("Release demo contact sheet was not produced")
         run(["npm", "audit", "--audit-level=high"], tree)
-        for file in ("app.js", "server.mjs", "service-worker.js", "src/analysis.js", "src/domain.js", "src/draft.js", "src/suggestion.js", "src/followup.js", "src/vision-readiness.js", "src/hermes-agent-service.js", "src/vision-config.js", "src/vision-service.js", "src/vision-corpus.js", "src/summary.js", "src/photo-lifecycle.js", "src/image-ingress.js", "src/rate-limit.js", "src/http-body.js", "scripts/record_worker_benchmark.mjs", "tests/staging.acceptance.mjs", "tests/vision-refusal.acceptance.mjs", "tests/worker-readiness.acceptance.mjs", "tests/pattern-summary.acceptance.mjs", "tests/photo-lifecycle.acceptance.mjs", "tests/ingress-capture.acceptance.mjs"):
+        for file in ("app.js", "server.mjs", "service-worker.js", "src/analysis.js", "src/domain.js", "src/draft.js", "src/suggestion.js", "src/followup.js", "src/vision-readiness.js", "src/hermes-agent-service.js", "src/vision-config.js", "src/vision-service.js", "src/vision-corpus.js", "src/summary.js", "src/photo-lifecycle.js", "src/training-contribution.js", "scripts/record_worker_benchmark.mjs", "tests/staging.acceptance.mjs", "tests/vision-refusal.acceptance.mjs", "tests/worker-readiness.acceptance.mjs", "tests/pattern-summary.acceptance.mjs", "tests/photo-lifecycle.acceptance.mjs", "tests/training-contribution.acceptance.mjs", "src/image-ingress.js", "src/rate-limit.js", "src/http-body.js", "tests/ingress-capture.acceptance.mjs"):
             run(["node", "--check", file], tree)
         run(["bash", "-n", "scripts/bootstrap_selfhost_smolvlm.sh"], tree)
         run(["bash", "-n", "scripts/run_selfhost_smolvlm.sh"], tree)
@@ -209,7 +285,7 @@ def main() -> int:
         run(["bash", "-n", "deploy/worker/entrypoint.sh"], tree)
         run(["bash", "-n", "deploy/worker/build_image.sh"], tree)
         run(["bash", "-n", "deploy/worker/run_worker_container.sh"], tree)
-        run(["python3", "-m", "py_compile", "scripts/ingest_training_photo.py", "scripts/build_release.py", "scripts/build_vision_corpus.py"], tree)
+        run(["python3", "-m", "py_compile", "scripts/ingest_training_photo.py", "scripts/build_release.py", "scripts/build_vision_corpus.py", "scripts/corpus_manifest.py", "scripts/review_corpus.py", "scripts/dataset_card.py"], tree)
         run(["git", "diff", "--check", commit], tree)
 
         names = tracked_files(tree)
@@ -242,7 +318,14 @@ def main() -> int:
             "- Target-GPU benchmark: scripts/record_worker_benchmark.mjs records cold start, warm latency, and VRAM on the target GPU and refuses to write a receipt it did not measure; no GPU measurement is bundled with this release\n"
             "- Explainable pattern summaries (issue #34): the home insight card reports confirmed-log counts and form groupings per window, every line names the exact confirmed records behind it, following a citation opens those records, and a window below the minimum says it is too sparse instead of describing a trend; no line explains a cause, rules on food, or offers a health verdict\n"
             "- Private photo lifecycle (issue #36): the journal marks a log that holds a saved photo without rendering a thumbnail, showing the image is an explicit request, removing it keeps every confirmed field, deleting a log is a separate two-step decision that takes its photo, and delete-all removes the ledger and every stored photo together\n"
-            "- Safety: suggestions are observable-field assistance, never diagnosis; user confirmation is required\n"
+            "- Training contribution is a separate opt-in (issue #24): a journal save records no contribution, the consent version and the receipt are on screen before the control can be pressed, the receipt is queued on this device only (this build transmits nothing) and carries no note text, symptom answers, or photo bytes, and a withdrawal keeps a tombstone naming every derived artifact by contribution id\n"
+            "- Auditable corpus pipeline (issue #25): every ingested training sample now records its consent version and timestamp, source kind and the raw-input digest (the caller's file path is never stored), both the raw and derived hashes, the derivation pipeline, the human review status, the split, and its lifecycle state in an append-only manifest; withdrawing a contribution deletes the derived image and any raw pre-derivation copy from the active dataset, keeps the original record as its own history, and appends a tombstone that names every removed artifact by contribution id and digest while dropping labels and the subject key; illegal lifecycle moves (re-ingesting a contribution, re-labelling a derived image, revoking twice, revoking an unknown contribution, reviving a revoked one, revoking without a reason) are refused before any byte is written\n"
+            "- Scope note: the corpus pipeline is a command-line tool. There is no corpus screen in the app, and this release does not imply one — the recorded demo runs the real ingest and revoke commands against the committed synthetic fixture and shows their actual output\n"
+            "- Blind reviewer and adjudication tool (issue #26): the review queue shows the proposal and withholds every model field, revealing a model answer is refused until a human has committed their own labels, a correction must actually change the proposal, the ledger is append-only, and a second reader's adjudication is appended beside the review it resolves rather than replacing it; a withdrawn contribution cannot be queued, reviewed, revealed, adjudicated, or trained on, and unreviewed or excluded samples are never training data\n"
+            "- Scope note: the review tool is a command line, not a screen in the app. There is no reviewer screen, and this release does not imply one — the recorded demo runs the real queue, review, reveal, adjudicate, and trainable commands against the committed synthetic sample and shows their actual output, with a synthetic answer file that no model produced\n"
+            "- Published dataset card and labeling guide (issue #27): the card is generated from the corpus manifest by scripts/dataset_card.py, so every count on it is read back from the manifest and every fact the pipeline does not collect (devices, contexts, licenses) is printed as pending instead of estimated; the generator refuses to publish a card for a corpus where one contributor straddles two splits or where a recorded split is not the one the subject key derives, a withdrawn sample contributes no label to the balance tables, and no subject key ever reaches the page\n"
+            "- Contributor-level split policy, published where it is enforced: splits follow the salted subject key (below 205 train, below 230 validation, otherwise test), all of a contributor's photos land in one split, and docs/LABELING_GUIDE.md states that a reviewer records visible form, broad visible color, and photo quality only — visible color is not blood, nothing is diagnosed, and a model suggestion is provisional input to a human decision rather than the label\n"
+            "- Scope note: the dataset card is a generated document, not a screen in the app, and this release does not imply one — the recorded demo builds a throwaway corpus with the real ingest command from synthetic fixtures, publishes the card with the real generator, and shows the refusal a planted contributor earns\n"
             "- Known limitation: open-weight VLM acceptance is proven, Bristol accuracy is not clinically validated\n"
             "- Package excludes model weights, medical-image corpora, raw research pages, generated screenshots, and video production assets\n"
         )
@@ -287,7 +370,7 @@ def main() -> int:
             "codec": "h264",
             "pixel_format": "yuv420p",
             "recorded_from_working_app": True,
-            "fixture_data": "synthetic-Type-4, deterministic vision suggestion reviewed, confirmed, and corrected to Type 2, user-reported hard-stool follow-up with non-diagnostic self-care and a confirmed black/tarry red flag, the CC0 synthetic vision corpus replaying a non-stool refusal, an unreadable-fields abstention, an out-of-range fail-closed reply, and a blank-plus-out-of-range fail-closed reply, offline vision status, fictional multi-day sample logs driving the explainable pattern summary and its citation sheet, a sparse fictional window showing the insufficient-data copy, a grounded local chat answer citing each counted log and opening the cited record, a refusal that borrows no journal evidence, and a deterministic Hermes chat reply whose positional refs render as sources",
+            "fixture_data": "synthetic-Type-4, deterministic vision suggestion reviewed, confirmed, and corrected to Type 2, user-reported hard-stool follow-up with non-diagnostic self-care and a confirmed black/tarry red flag, the CC0 synthetic vision corpus replaying a non-stool refusal, an unreadable-fields abstention, a confident reply about a poor-quality photo abstaining, an out-of-range fail-closed reply, and a blank-plus-out-of-range fail-closed reply, offline vision status, fictional multi-day sample logs driving the explainable pattern summary and its citation sheet, a sparse fictional window showing the insufficient-data copy, a grounded local chat answer citing each counted log and opening the cited record, a refusal that borrows no journal evidence, and a deterministic Hermes chat reply whose positional refs render as sources, plus the opt-in training contribution path where nothing is queued after ordinary saves, the consent version and receipt precede the confirm control, one receipt is queued on the device only, and withdrawal leaves a tombstone naming each derived artifact, plus a versioned backup that carries the logs and the withdrawn receipt, an older version 1 file upgraded with the version named on screen, a file from a newer Timmy refused without changing the ledger, and a restored log still showing it began as a corrected AI suggestion, plus the corpus audit card, where the real ingest and revoke commands run against the committed synthetic fixture and the card shows their actual output: the provenance record with consent, source digest, both hashes, derivation, review and lifecycle; the derived image deleted from disk; the original record kept as history beside a tombstone that drops labels and the subject key; zero active samples for a trainer; and a second revocation refused without appending anything, plus the review ledger card, where the real review commands run against the committed synthetic sample and the card shows their actual output: one pending proposal with the model answer withheld, a refused reveal before commitment, a committed Type 5 correction beside the Type 4 proposal, the revealed synthetic Type 6 answer recorded as a three-field disagreement, a second reader's adjudication pointing at the review it resolved, one trainable sample, and a withdrawal that empties the queue and the training set and makes review refused, plus the operator backup card, where the real backup, verify, and restore commands run against a synthetic corpus built by the real ingest and revoke commands and the card shows their actual output: two samples and one tombstone recorded, a weight shard, a transient inference upload, an operator env file and a log refused by name with the reason listed, the exclusion counts the manifest wrote, one digest for the archive, a verify that re-hashes every stored member, and a restore that returns the manifest byte-for-byte with the tombstone intact",
         },
         "gates": {
             "unit_security": "passed",
@@ -298,10 +381,19 @@ def main() -> int:
             "provisional_suggestion_state": "passed",
             "hard_stool_followup": "passed",
             "vision_corpus_refusal": "passed",
+            "abstention_quality_gate": "passed",
             "worker_container_receipts": "passed",
             "worker_post_load_readiness": "passed",
             "longitudinal_pattern_summary": "passed",
             "grounded_chat_citations": "passed",
+            "training_contribution_consent": "passed",
+            "corpus_manifest_provenance": "passed",
+            "reviewer_adjudication_blind": "passed",
+            "dataset_card_generated": "passed",
+            "calibration_harness_gates": "passed",
+            "production_backup_restore": "passed",
+            "production_runbook_commands": "passed",
+            "portable_backup_restore": "passed",
             "image_ingress_refusal": "passed",
             "dependency_audit_high": "passed",
             "syntax": "passed",

scripts/calibration_report.py

@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+"""Contributor-held-out evaluation harness for the Timmy Bristol classifier.
+
+This is the comparison and release-gate tool for issue #29: it turns candidate predictions into the
+numbers the ROADMAP gates are written in — macro-F1, per-class precision/recall, a confusion matrix,
+calibration error, coverage, and precision-at-coverage — and it refuses a corpus whose splits are
+not contributor-held-out or not reproducible.
+
+Nothing here trains, scores, or diagnoses: it reads predictions that something else produced, and it
+reports what those predictions would have done on held-out contributors. Every fixture used to test
+it is synthetic.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+BRISTOL_CLASSES = tuple(range(1, 8))
+SPLITS = ("train", "validation", "test")
+# The split rule is the ingestion rule (scripts/ingest_training_photo.py): the bucket of the first
+# byte of the pseudonymous subject key. Keeping it here means a split can be re-derived from the
+# key alone, so a corpus cannot quietly re-label its own splits.
+_TRAIN_EDGE = 205
+_VALIDATION_EDGE = 230
+_SHA_LIKE = re.compile(r"^[0-9a-f]{16}$")
+
+# The ROADMAP release gates. A candidate must clear every one on its held-out split; a limit is
+# inclusive, so a model exactly on the line passes.
+RELEASE_GATES = {"macroF1": 0.80, "precisionAtCoverage": 0.90, "ece": 0.05}
+
+
+class EvaluationError(Exception):
+    """The corpus or the caller asked for a comparison that cannot be trusted."""
+
+
+def expected_split(subject_key: str) -> str:
+    """The split a pseudonymous subject key must belong to, by the ingestion rule."""
+    if not isinstance(subject_key, str) or not _SHA_LIKE.match(subject_key):
+        raise EvaluationError("subject key must be the 16-character pseudonymous digest")
+    bucket = int(subject_key[:2], 16)
+    if bucket < _TRAIN_EDGE:
+        return "train"
+    if bucket < _VALIDATION_EDGE:
+        return "validation"
+    return "test"
+
+
+def _calibration_error(accepted: list[tuple[int, int, float]], bins: int = 10) -> tuple[float, list[dict]]:
+    """Expected calibration error over the accepted suggestions, by equal-width confidence bin."""
+    if not accepted:
+        return 0.0, []
+    edges = [index / bins for index in range(bins + 1)]
+    buckets: list[list[tuple[int, int, float]]] = [[] for _ in range(bins)]
+    for truth, predicted, confidence in accepted:
+        index = min(int(confidence * bins), bins - 1)
+        buckets[index].append((truth, predicted, confidence))
+    error = 0.0
+    detail: list[dict] = []
+    for index, bucket in enumerate(buckets):
+        if not bucket:
+            continue
+        accuracy = sum(1 for truth, predicted, _ in bucket if truth == predicted) / len(bucket)
+        mean_confidence = sum(confidence for _, _, confidence in bucket) / len(bucket)
+        share = len(bucket) / len(accepted)
+        error += share * abs(accuracy - mean_confidence)
+        detail.append(
+            {
+                "lower": edges[index],
+                "upper": edges[index + 1],
+                "count": len(bucket),
+                "accuracy": accuracy,
+                "meanConfidence": mean_confidence,
+            }
+        )
+    return error, detail
+
+
+def assert_contributor_held_out(records: list[dict]) -> None:
+    """Refuse a corpus whose splits are not contributor-held-out and reproducible.
+
+    A split must be re-derivable from the pseudonymous subject key alone (the ingestion rule), and
+    one contributor's photos must all land in the same split. Otherwise a held-out score is not
+    held out: the model has already seen that person's body in training.
+    """
+    splits_by_subject: dict[str, set[str]] = {}
+    for entry in records:
+        subject = entry.get("subjectKey")
+        if not isinstance(subject, str) or not subject:
+            raise EvaluationError("every prediction must carry the pseudonymous subject key")
+        split = entry.get("split")
+        if split not in SPLITS:
+            raise EvaluationError(f"split must be one of {', '.join(SPLITS)}: {split!r}")
+        splits_by_subject.setdefault(subject, set()).add(split)
+    for subject, splits in splits_by_subject.items():
+        if len(splits) > 1:
+            raise EvaluationError(
+                f"contributor {subject} leaks across {', '.join(sorted(splits))}: splits must be contributor-held-out"
+            )
+    for entry in records:
+        subject = entry["subjectKey"]
+        required = expected_split(subject)
+        if entry["split"] != required:
+            raise EvaluationError(
+                f"split {entry['split']!r} for contributor {subject} is not reproducible: the subject key derives {required!r}"
+            )
+
+
+def compare(models: dict[str, list[dict]], *, min_coverage: float = 0.5, gates: dict | None = None) -> dict:
+    """Compare candidate models against the release gates.
+
+    Each candidate gets one threshold, chosen on its own validation split, and is then measured on
+    its test split. The gates are the ROADMAP release gates; all limits are inclusive.
+    """
+    limits = dict(gates or RELEASE_GATES)
+    rows: list[dict] = []
+    for model_id in sorted(models):
+        records = models[model_id]
+        assert_contributor_held_out(records)
+        test = [entry for entry in records if entry.get("split") == "test"]
+        validation = [entry for entry in records if entry.get("split") == "validation"]
+        if not test:
+            raise EvaluationError(f"{model_id} has no test-split predictions to measure a release on")
+        if not validation:
+            raise EvaluationError(f"{model_id} has no validation-split predictions to fix a threshold on")
+        selection = select_threshold(validation, min_coverage=min_coverage)
+        scored = evaluate(test, threshold=selection["threshold"])
+        failed = []
+        if scored["macroF1"] < limits["macroF1"]:
+            failed.append("macroF1")
+        if scored["precisionAtCoverage"] < limits["precisionAtCoverage"]:
+            failed.append("precisionAtCoverage")
+        if scored["ece"] > limits["ece"]:
+            failed.append("ece")
+        rows.append(
+            {
+                "model": model_id,
+                **scored,
+                "selectionSplit": "validation",
+                "evaluatedSplit": "test",
+                "minCoverage": min_coverage,
+                "gate": {"passed": not failed, "failed": failed},
+            }
+        )
+    ordered = sorted(
+        rows,
+        key=lambda row: (
+            not row["gate"]["passed"],
+            -row["macroF1"],
+            -row["precisionAtCoverage"],
+            row["model"],
+        ),
+    )
+    passing = [row for row in ordered if row["gate"]["passed"]]
+    return {
+        "gates": limits,
+        "models": ordered,
+        "recommended": passing[0]["model"] if passing else None,
+        "verdict": "GO" if passing else "BLOCKED",
+    }
+
+
+def select_threshold(records: list[dict], *, min_coverage: float = 0.5) -> dict:
+    """Choose the abstention threshold that maximises precision at a required coverage.
+
+    Selection reads the validation split only. Fixing a threshold on the same data the release gate
+    is measured on would manufacture whatever precision the report needs.
+    """
+    if not records:
+        raise EvaluationError("threshold selection needs validation predictions")
+    if not 0.0 <= min_coverage <= 1.0:
+        raise EvaluationError(f"a coverage floor must be between 0 and 1: {min_coverage}")
+    if any(entry.get("split") != "validation" for entry in records):
+        raise EvaluationError("threshold selection must use the validation split only")
+    assert_contributor_held_out(records)
+
+    candidates = {0.0}
+    candidates.update(
+        entry["prediction"]["confidence"] for entry in records if entry["prediction"] is not None
+    )
+    best: dict | None = None
+    for threshold in sorted(candidates):
+        report = evaluate(records, threshold=threshold)
+        # Float comparison: a coverage exactly on the floor must not be lost to rounding.
+        if report["coverage"] + 1e-12 < min_coverage:
+            continue
+        if best is None:
+            best = report
+            continue
+        more_precise = round(report["precisionAtCoverage"], 12) > round(best["precisionAtCoverage"], 12)
+        equally_precise_but_wider = (
+            round(report["precisionAtCoverage"], 12) == round(best["precisionAtCoverage"], 12)
+            and report["coverage"] > best["coverage"]
+        )
+        if more_precise or equally_precise_but_wider:
+            best = report
+    if best is None:
+        raise EvaluationError(f"no threshold reaches the {min_coverage:.0%} coverage floor on validation")
+    return {**best, "selectionSplit": "validation", "minCoverage": min_coverage}
+
+
+def evaluate(records: list[dict], *, threshold: float = 0.0) -> dict:
+    """Score one model's accepted suggestions at a fixed abstention threshold."""
+    accepted: list[tuple[int, int, float]] = []
+    abstentions = {"low-confidence": 0, "no-suggestion": 0}
+    for entry in records:
+        truth = entry["truth"]["bristolType"]
+        prediction = entry["prediction"]
+        if prediction is None:
+            abstentions["no-suggestion"] += 1
+            continue
+        if prediction["confidence"] < threshold:
+            abstentions["low-confidence"] += 1
+            continue
+        accepted.append((truth, prediction["bristolType"], prediction["confidence"]))
+
+    confusion: dict[str, int] = {}
+    for truth, predicted, _ in accepted:
+        key = f"{truth}->{predicted}"
+        confusion[key] = confusion.get(key, 0) + 1
+
+    truth_classes = {truth for truth, _, _ in accepted}
+    per_class: dict[int, dict] = {}
+    for label in sorted(truth_classes):
+        true_positive = sum(1 for truth, predicted, _ in accepted if truth == label and predicted == label)
+        predicted_positive = sum(1 for _, predicted, _ in accepted if predicted == label)
+        actual_positive = sum(1 for truth, _, _ in accepted if truth == label)
+        precision = true_positive / predicted_positive if predicted_positive else 0.0
+        recall = true_positive / actual_positive if actual_positive else 0.0
+        f1 = 2 * precision * recall / (precision + recall) if precision + recall else 0.0
+        per_class[label] = {
+            "precision": precision,
+            "recall": recall,
+            "f1": f1,
+            "support": actual_positive,
+            "predicted": predicted_positive,
+        }
+
+    macro_f1 = sum(row["f1"] for row in per_class.values()) / len(per_class) if per_class else 0.0
+    ece, calibration_bins = _calibration_error(accepted)
+    truth_classes_in_split = {entry["truth"]["bristolType"] for entry in records}
+    return {
+        "threshold": threshold,
+        "counts": {"total": len(records), "accepted": len(accepted), "abstained": len(records) - len(accepted)},
+        "abstentions": abstentions,
+        "coverage": len(accepted) / len(records) if records else 0.0,
+        "precisionAtCoverage": (
+            sum(1 for truth, predicted, _ in accepted if truth == predicted) / len(accepted) if accepted else 0.0
+        ),
+        "perClass": per_class,
+        "excludedClasses": sorted(truth_classes_in_split - set(per_class)),
+        "macroF1": macro_f1,
+        "ece": ece,
+        "calibrationBins": calibration_bins,
+        "confusion": dict(sorted(confusion.items())),
+    }
+
+
+def _validate_prediction(entry: object, where: str) -> dict:
+    """Normalise and bound one prediction record, or refuse it."""
+    if not isinstance(entry, dict):
+        raise EvaluationError(f"{where} is not a prediction object")
+    model = entry.get("model")
+    if not isinstance(model, str) or not model.strip():
+        raise EvaluationError(f"{where} needs the model that produced the prediction")
+    truth = entry.get("truth")
+    if not isinstance(truth, dict) or not isinstance(truth.get("bristolType"), int):
+        raise EvaluationError(f"{where} needs truth.bristolType as a whole number")
+    if truth["bristolType"] not in BRISTOL_CLASSES:
+        raise EvaluationError(f"{where} truth.bristolType {truth['bristolType']} is outside Bristol 1-7")
+    split = entry.get("split")
+    if split not in SPLITS:
+        raise EvaluationError(f"{where} split must be one of {', '.join(SPLITS)}")
+    subject = entry.get("subjectKey")
+    if not isinstance(subject, str) or not _SHA_LIKE.match(subject):
+        raise EvaluationError(f"{where} needs the 16-character pseudonymous subject key")
+    prediction = entry.get("prediction")
+    if prediction is not None:
+        if not isinstance(prediction, dict):
+            raise EvaluationError(f"{where} prediction must be an object or null")
+        if prediction.get("bristolType") not in BRISTOL_CLASSES:
+            raise EvaluationError(f"{where} predicted bristolType must be 1-7")
+        confidence = prediction.get("confidence")
+        if not isinstance(confidence, (int, float)) or isinstance(confidence, bool) or not 0.0 <= confidence <= 1.0:
+            raise EvaluationError(f"{where} confidence must be a number between 0 and 1")
+    return {
+        "model": model.strip(),
+        "subjectKey": subject,
+        "split": split,
+        "truth": {"bristolType": truth["bristolType"]},
+        "prediction": None
+        if prediction is None
+        else {"bristolType": prediction["bristolType"], "confidence": float(prediction["confidence"])},
+    }
+
+
+def load_predictions(paths: list[str]) -> list[dict]:
+    """Read prediction JSONL files, refusing anything the gates could not honestly be computed from."""
+    records: list[dict] = []
+    for raw_path in paths:
+        path = Path(raw_path)
+        if not path.is_file():
+            raise EvaluationError(f"predictions file not found: {path}")
+        for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+            if not line.strip():
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise EvaluationError(f"{path}:{number} is not valid JSON: {exc.msg}") from exc
+            records.append(_validate_prediction(entry, f"{path}:{number}"))
+    if not records:
+        raise EvaluationError("no prediction records were supplied")
+    return records
+
+
+def group_by_model(records: list[dict]) -> dict[str, list[dict]]:
+    models: dict[str, list[dict]] = {}
+    for entry in records:
+        models.setdefault(entry["model"], []).append(
+            {key: value for key, value in entry.items() if key != "model"}
+        )
+    return models
+
+
+def format_report(report: dict, *, source: str) -> str:
+    """Render the comparison as a compact receipt a human can read in a terminal."""
+    lines = [
+        "TIMMY CALIBRATION REPORT",
+        f"source: {source}",
+        f"threshold: chosen on validation only · scored on test · coverage floor {report['models'][0]['minCoverage']:.0%}"
+        if report["models"]
+        else "threshold: nothing to score",
+        "candidates: " + ", ".join(row["model"] for row in report["models"]),
+        "",
+        f"{'model':<26}{'thr':>5}{'macroF1':>9}{'prec@cov':>10}{'coverage':>10}{'ECE':>7}  gate",
+    ]
+    for row in report["models"]:
+        gate = "PASS" if row["gate"]["passed"] else "FAIL: " + ", ".join(row["gate"]["failed"])
+        lines.append(
+            f"{row['model']:<26}{row['threshold']:>5.2f}{row['macroF1']:>9.3f}"
+            f"{row['precisionAtCoverage']:>10.3f}{row['coverage']:>10.2f}{row['ece']:>7.3f}  {gate}"
+        )
+    limits = report["gates"]
+    lines += [
+        "",
+        "verdict: " + report["verdict"] + (f" — recommended {report['recommended']}" if report["recommended"] else ""),
+        f"gates: macroF1 >= {limits['macroF1']:.2f} · precision@coverage >= {limits['precisionAtCoverage']:.2f} · ECE <= {limits['ece']:.2f}",
+    ]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Score Bristol candidates against the release gates.")
+    parser.add_argument("--predictions", action="append", required=True, metavar="PATH", help="prediction JSONL (repeatable)")
+    parser.add_argument("--min-coverage", type=float, default=0.5, help="coverage floor for threshold selection")
+    parser.add_argument("--json", metavar="PATH", help="write the full report as JSON here")
+    parser.add_argument("--source", default=None, help="what the predictions are, recorded in the receipt")
+    args = parser.parse_args(argv)
+
+    try:
+        records = load_predictions(args.predictions)
+        report = compare(group_by_model(records), min_coverage=args.min_coverage)
+    except EvaluationError as exc:
+        print(f"calibration harness refused: {exc}", file=sys.stderr)
+        return 2
+
+    source = args.source or f"{len(records)} prediction records from {len(args.predictions)} file(s)"
+    print(format_report(report, source=source))
+    if args.json:
+        Path(args.json).write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    return 0 if report["verdict"] == "GO" else 3
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/corpus_manifest.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""Immutable, auditable corpus manifest for Timmy training contributions.
+
+Every ingested sample is described by one append-only manifest record: who consented, under
+which consent version, where the bytes came from, the hashes of the raw input and the derived
+image, how the derived image was produced, who reviewed the labels, which split it belongs to,
+and where it sits in its lifecycle. Nothing in this module rewrites history: records are only
+ever appended, and a withdrawal is a tombstone, not a deletion of the trail.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+
+SCHEMA_VERSION = 2
+PIPELINE = "timmy-ingest/2"
+
+SAMPLE = "sample"
+TOMBSTONE = "tombstone"
+RECORD_TYPES = frozenset({SAMPLE, TOMBSTONE})
+
+ACTIVE = "active"
+REVOKED = "revoked"
+STATES = frozenset({ACTIVE, REVOKED})
+
+SPLITS = ("train", "validation", "test")
+REVIEWERS = ("user-confirmed", "clinician-reviewed")
+COLORS = ("brown", "green", "yellow", "pale", "red", "black")
+QUALITIES = ("good", "fair", "poor")
+
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+_CONTRIBUTION_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$")
+
+
+class CorpusError(Exception):
+    """A record cannot be built or written as asked."""
+
+
+class IllegalTransition(CorpusError):
+    """A lifecycle change that must never happen is being attempted."""
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _require_sha256(value: object, field: str) -> str:
+    if not isinstance(value, str) or not _SHA256.match(value):
+        raise CorpusError(f"{field} must be a lowercase hex sha256 digest")
+    return value
+
+
+def _require_iso(value: object, field: str) -> str:
+    if not isinstance(value, str) or not re.match(r"^\d{4}-\d{2}-\d{2}T", value):
+        raise CorpusError(f"{field} must be an ISO-8601 timestamp")
+    return value
+
+
+def build_record(
+    *,
+    contribution_id: str,
+    consent_version: str,
+    subject_key: str,
+    split: str,
+    labels: dict,
+    review_status: str,
+    derived_sha256: str,
+    raw_sha256: str,
+    ingested_at: str,
+    source_kind: str = "cli-ingest",
+) -> dict:
+    """Build one active sample record carrying its full provenance."""
+    if not isinstance(contribution_id, str) or not _CONTRIBUTION_ID.match(contribution_id):
+        raise CorpusError("contribution id is required and must be a stable opaque identifier")
+    if not isinstance(consent_version, str) or not consent_version.strip():
+        raise CorpusError("consent version is required")
+    if not isinstance(subject_key, str) or not re.match(r"^[0-9a-f]{16}$", subject_key):
+        raise CorpusError("subject key must be the 16-character pseudonymous digest")
+    if split not in SPLITS:
+        raise CorpusError(f"split must be one of {', '.join(SPLITS)}")
+    if review_status not in REVIEWERS:
+        raise CorpusError(f"review status must be one of {', '.join(REVIEWERS)}")
+    if not isinstance(source_kind, str) or not source_kind.strip():
+        raise CorpusError("source kind is required")
+    if not isinstance(labels, dict) or set(labels) != {"bristolType", "color", "quality"}:
+        raise CorpusError("labels must carry bristolType, color, and quality")
+    if labels["bristolType"] not in range(1, 8):
+        raise CorpusError("bristolType must be 1-7")
+    if labels["color"] not in COLORS or labels["quality"] not in QUALITIES:
+        raise CorpusError("color and quality must be from the documented vocabularies")
+    derived = _require_sha256(derived_sha256, "derived sha256")
+    raw = _require_sha256(raw_sha256, "raw input sha256")
+    stamped = _require_iso(ingested_at, "ingestedAt")
+
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "recordType": SAMPLE,
+        "contributionId": contribution_id,
+        "imageId": derived,
+        "relativePath": f"images/{derived}.jpg",
+        "subjectKey": subject_key,
+        "split": split,
+        "consentVersion": consent_version.strip(),
+        "consent": {"version": consent_version.strip(), "recordedAt": stamped},
+        "source": {"kind": source_kind, "inputSha256": raw},
+        "hashes": {"rawInput": raw, "derived": derived},
+        "derivation": {
+            "format": "jpeg",
+            "maxDimension": 1200,
+            "metadataStripped": True,
+            "pipeline": PIPELINE,
+        },
+        "labels": {
+            "bristolType": labels["bristolType"],
+            "color": labels["color"],
+            "quality": labels["quality"],
+        },
+        "review": {"status": review_status, "reviewedAt": stamped},
+        "lifecycle": {"state": ACTIVE, "updatedAt": stamped},
+        "ingestedAt": stamped,
+    }
+
+
+def assert_admissible(manifest_path: Path, record: dict) -> None:
+    """Refuse a sample that duplicates a contribution or re-labels the same derived image."""
+    if record.get("recordType", SAMPLE) != SAMPLE:
+        return
+    for prior in load_manifest(manifest_path):
+        if prior.get("recordType", SAMPLE) != SAMPLE:
+            continue
+        if prior.get("contributionId") == record.get("contributionId"):
+            raise IllegalTransition(f"contribution {record['contributionId']} was already ingested")
+        if prior.get("imageId") == record.get("imageId") and prior.get("labels") != record.get("labels"):
+            raise CorpusError("the same derived image cannot carry two different label sets")
+
+
+def append_record(manifest_path: Path, record: dict) -> None:
+    """Append one record to the manifest without touching what is already there."""
+    assert_admissible(manifest_path, record)
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    with manifest_path.open("a", encoding="utf-8") as manifest:
+        manifest.write(json.dumps(record, separators=(",", ":"), sort_keys=False) + "\n")
+
+
+def load_manifest(manifest_path: Path) -> list[dict]:
+    """Read the append-only manifest in order. A missing manifest is an empty corpus."""
+    if not manifest_path.exists():
+        return []
+    with manifest_path.open("r", encoding="utf-8") as manifest:
+        return [json.loads(line) for line in manifest.read().splitlines() if line.strip()]
+
+
+def transition(record: dict, state: str, at: str, reason: str | None = None) -> dict:
+    """Return a copy of the record in the next lifecycle state, or refuse the move."""
+    current = record.get("lifecycle", {}).get("state")
+    if state not in STATES:
+        raise IllegalTransition(f"unknown lifecycle state: {state!r}")
+    if current not in STATES:
+        raise IllegalTransition(f"record carries no legal lifecycle state: {current!r}")
+    if current == state:
+        raise IllegalTransition(f"record is already {state}")
+    if current == REVOKED:
+        raise IllegalTransition("a revoked contribution cannot return to the active dataset")
+    _require_iso(at, "lifecycle timestamp")
+    if state == REVOKED and (not isinstance(reason, str) or not reason.strip()):
+        raise IllegalTransition("revocation needs a recorded reason")
+    updated = {**record, "lifecycle": {"state": state, "updatedAt": at}}
+    if state == REVOKED:
+        updated["lifecycle"]["reason"] = reason.strip()
+    return updated
+
+
+def active_records(records: list[dict]) -> list[dict]:
+    """Samples still usable for training: active, and never revoked afterwards."""
+    revoked = {
+        record.get("contributionId")
+        for record in records
+        if record.get("recordType") == TOMBSTONE or record.get("lifecycle", {}).get("state") == REVOKED
+    }
+    return [
+        record
+        for record in records
+        if record.get("recordType", SAMPLE) == SAMPLE
+        and record.get("lifecycle", {}).get("state") == ACTIVE
+        and record.get("contributionId") not in revoked
+    ]
+
+
+def _safe_dataset_path(dataset_root: Path, relative: str) -> Path:
+    path = (dataset_root / relative).resolve()
+    if not path.is_relative_to(dataset_root.resolve()):
+        raise CorpusError(f"refusing to touch a path outside the dataset: {relative}")
+    return path
+
+
+def revoke(dataset_root: Path, contribution_id: str, at: str, reason: str) -> dict:
+    """Revoke one contribution: append a tombstone and delete its bytes from the dataset."""
+    manifest_path = dataset_root / "manifest.jsonl"
+    records = load_manifest(manifest_path)
+    samples = [
+        record
+        for record in records
+        if record.get("recordType", SAMPLE) == SAMPLE and record.get("contributionId") == contribution_id
+    ]
+    if not isinstance(reason, str) or not reason.strip():
+        raise IllegalTransition("revocation needs a recorded reason")
+    if any(
+        record.get("recordType") == TOMBSTONE and record.get("contributionId") == contribution_id
+        for record in records
+    ):
+        raise IllegalTransition(f"contribution {contribution_id} is already revoked")
+    if not samples:
+        raise IllegalTransition(f"no ingested sample carries contribution {contribution_id}")
+    sample = samples[-1]
+    if sample.get("lifecycle", {}).get("state") != ACTIVE:
+        raise IllegalTransition(f"contribution {contribution_id} is not active")
+
+    deleted = []
+    candidates = [(sample["relativePath"], sample["hashes"]["derived"])]
+    # A raw pre-derivation copy is identified by the raw input digest, never by a user path.
+    for path in sorted((dataset_root / "raw").glob(f"{sample['hashes']['rawInput']}*")):
+        candidates.append((str(path.relative_to(dataset_root)), sample["hashes"]["rawInput"]))
+    for relative, digest in candidates:
+        target = _safe_dataset_path(dataset_root, relative)
+        existed = target.is_file()
+        if existed:
+            target.unlink()
+        deleted.append({"relativePath": relative, "sha256": digest, "deleted": existed})
+
+    tombstone = {
+        "schemaVersion": SCHEMA_VERSION,
+        "recordType": TOMBSTONE,
+        "contributionId": contribution_id,
+        "imageId": sample["imageId"],
+        "deletedArtifacts": deleted,
+        "lifecycle": {"state": REVOKED, "updatedAt": _require_iso(at, "lifecycle timestamp"), "reason": reason.strip()},
+    }
+    append_record(manifest_path, tombstone)
+    return tombstone

scripts/dataset_card.py

@@ -0,0 +1,344 @@
+#!/usr/bin/env python3
+"""Generate the published dataset card from the append-only corpus manifest (issue #27).
+
+A dataset card that is typed by hand drifts from the corpus it describes, and a card that estimates
+its own numbers is worse than no card at all. This generator therefore only reports what the manifest
+actually contains:
+
+- counts of active samples, contributors, and withdrawals,
+- the contributor-level split policy, checked before a single line is rendered,
+- class balance over the active samples only,
+- every fact the pipeline does not collect (devices, contexts, licenses) printed as ``pending``.
+
+Nothing is inferred. A person's pseudonymous subject key never reaches the page, and a withdrawn
+sample contributes no label to the balance tables. The output is a pure function of the manifest, so
+the committed card can be regenerated and compared byte for byte.
+
+Usage:
+    python3 scripts/dataset_card.py --corpus /srv/timmy-corpus
+    python3 scripts/dataset_card.py --corpus /srv/timmy-corpus --out docs/DATASET_CARD.md
+    python3 scripts/dataset_card.py --corpus /srv/timmy-corpus --check docs/DATASET_CARD.md
+    python3 scripts/dataset_card.py --corpus /srv/timmy-corpus --json
+
+Exit codes: 0 the card rendered (and matched, with --check); 1 the card on disk is out of date;
+2 the corpus cannot be described honestly and was refused.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from corpus_manifest import (  # noqa: E402
+    COLORS,
+    QUALITIES,
+    REVIEWERS,
+    SAMPLE,
+    SPLITS,
+    TOMBSTONE,
+    CorpusError,
+    active_records,
+    load_manifest,
+)
+from calibration_report import expected_split  # noqa: E402
+
+# The facts no current pipeline step records. They are reported as pending rather than guessed.
+PENDING_FACTS = ("contexts", "devices", "licenses")
+PENDING_LABELS = {
+    "devices": "Devices",
+    "contexts": "Contexts",
+    "licenses": "Licenses",
+}
+PENDING_REASONS = {
+    "devices": "not collected by ingest — no camera, model, or OS fields are recorded",
+    "contexts": "not collected by ingest — no setting, time-of-day, or location fields are recorded",
+    "licenses": "no contributor grant is recorded yet, so no license is asserted",
+}
+
+
+class CardError(Exception):
+    """The corpus cannot be described as asked."""
+
+
+def assert_contributor_held_out(records: list[dict]) -> None:
+    """Refuse a corpus where one contributor straddles splits or a split cannot be re-derived.
+
+    The rule is the ingestion rule, so a corpus cannot quietly relabel its own splits: a split must
+    follow from the pseudonymous subject key alone, and one person's photos must all land in one
+    split. Otherwise every held-out number downstream is measuring a person the model already met.
+    """
+    splits_by_subject: dict[str, set[str]] = {}
+    for record in records:
+        if record.get("recordType", SAMPLE) != SAMPLE:
+            continue
+        subject = record.get("subjectKey")
+        if not isinstance(subject, str) or not subject:
+            raise CardError("every sample must carry the pseudonymous subject key")
+        split = record.get("split")
+        if split not in SPLITS:
+            raise CardError(f"split must be one of {', '.join(SPLITS)}: {split!r}")
+        splits_by_subject.setdefault(subject, set()).add(split)
+    for subject, splits in sorted(splits_by_subject.items()):
+        if len(splits) > 1:
+            raise CardError(
+                f"contributor {subject} leaks across {', '.join(sorted(splits))}: "
+                "one contributor's photos must stay in one split"
+            )
+    for record in records:
+        if record.get("recordType", SAMPLE) != SAMPLE:
+            continue
+        try:
+            required = expected_split(record["subjectKey"])
+        except Exception as exc:  # noqa: BLE001 - the rule reports its own refusal
+            raise CardError(str(exc)) from exc
+        if record["split"] != required:
+            raise CardError(
+                f"split {record['split']!r} for contributor {record['subjectKey']} is not reproducible: "
+                f"the subject key derives {required!r}"
+            )
+
+
+def summarize(records: list[dict]) -> dict:
+    """Count what the manifest holds. Pure function of the records, in a stable order."""
+    assert_contributor_held_out(records)
+    active = active_records(records)
+
+    # A withdrawal can appear as a tombstone or as a revoked sample record (both are legal history);
+    # it is one withdrawn contribution either way, so count distinct contribution ids.
+    withdrawn: dict[str, dict] = {}
+    for record in records:
+        is_tombstone = record.get("recordType") == TOMBSTONE
+        is_revoked_sample = (
+            record.get("recordType", SAMPLE) == SAMPLE
+            and record.get("lifecycle", {}).get("state") == "revoked"
+        )
+        if not (is_tombstone or is_revoked_sample):
+            continue
+        contribution = record.get("contributionId")
+        if not isinstance(contribution, str) or not contribution:
+            raise CardError("a withdrawn record must carry the contribution id it revokes")
+        lifecycle = record.get("lifecycle", {})
+        entry = withdrawn.setdefault(
+            contribution,
+            {"contributionId": contribution, "withdrawnAt": None, "reason": None, "artifacts": 0},
+        )
+        stamp = lifecycle.get("updatedAt")
+        if stamp and (entry["withdrawnAt"] is None or stamp > entry["withdrawnAt"]):
+            entry["withdrawnAt"] = stamp
+        if lifecycle.get("reason"):
+            entry["reason"] = lifecycle["reason"]
+        if is_tombstone:
+            entry["artifacts"] = len(record.get("deletedArtifacts") or [])
+
+    by_split = {split: {"contributors": set(), "samples": 0} for split in SPLITS}
+    for record in active:
+        by_split[record["split"]]["contributors"].add(record["subjectKey"])
+        by_split[record["split"]]["samples"] += 1
+
+    bristol = {str(day): 0 for day in range(1, 8)}
+    color = {name: 0 for name in COLORS}
+    quality = {name: 0 for name in QUALITIES}
+    review = {name: 0 for name in REVIEWERS}
+    for record in active:
+        labels = record.get("labels", {})
+        bristol[str(labels.get("bristolType"))] = bristol.get(str(labels.get("bristolType")), 0) + 1
+        if labels.get("color") in color:
+            color[labels["color"]] += 1
+        if labels.get("quality") in quality:
+            quality[labels["quality"]] += 1
+        status = record.get("review", {}).get("status")
+        if status in review:
+            review[status] += 1
+
+    stamps = [record.get("ingestedAt") for record in records if record.get("ingestedAt")]
+    stamps += [entry["withdrawnAt"] for entry in withdrawn.values() if entry["withdrawnAt"]]
+
+    withdrawals_detail = [
+        {
+            "contributionId": entry["contributionId"],
+            "withdrawnAt": entry["withdrawnAt"],
+            "reason": entry["reason"],
+            "artifacts": entry["artifacts"],
+        }
+        for entry in withdrawn.values()
+    ]
+
+    return {
+        "activeSamples": len(active),
+        "contributors": len({record["subjectKey"] for record in active}),
+        "withdrawals": len(withdrawn),
+        "bySplit": {split: {"contributors": len(entry["contributors"]), "samples": entry["samples"]} for split, entry in by_split.items()},
+        "bristol": bristol,
+        "colors": color,
+        "qualities": quality,
+        "review": review,
+        "lastRecordAt": max(stamps) if stamps else None,
+        "withdrawalsDetail": sorted(withdrawals_detail, key=lambda entry: (entry["withdrawnAt"] or "", entry["contributionId"] or "")),
+        "pending": sorted(PENDING_FACTS),
+    }
+
+
+def _count_table(title: str, rows: list[tuple[str, int]]) -> list[str]:
+    lines = [f"**{title}**", "", f"| {title} | Active samples |", "|---|---:|"]
+    lines += [f"| {label} | {count} |" for label, count in rows]
+    lines.append("")
+    return lines
+
+
+def render_card(summary: dict, *, corpus: str) -> str:
+    """Render the card. Every value here comes from the manifest, or is marked pending."""
+    present = summary["activeSamples"] > 0 or summary["withdrawals"] > 0
+    lines = [
+        "# Dataset card — Timmy consented stool-image corpus",
+        "",
+        "Generated by [`scripts/dataset_card.py`](../scripts/dataset_card.py) from the append-only",
+        "corpus manifest. Do not edit this page by hand: regenerate it, or `--check` fails. Every count",
+        "below is read back from `manifest.jsonl`; a fact the pipeline does not collect is printed as",
+        "`pending` rather than estimated, so nothing here is invented.",
+        "",
+        "| Field | Value |",
+        "|---|---|",
+        f"| Corpus | `{corpus}` |",
+        f"| Corpus present on this machine | {'yes' if present else 'no'} |",
+        f"| Last manifest record | {summary['lastRecordAt'] or 'pending — no record yet'} |",
+        f"| Active samples | {summary['activeSamples']} |",
+        f"| Contributors | {summary['contributors']} |",
+        f"| Withdrawals | {summary['withdrawals']} |",
+    ]
+    for fact in PENDING_FACTS:
+        lines.append(f"| {PENDING_LABELS[fact]} | pending — {PENDING_REASONS[fact]} |")
+    lines.append(f"| Regenerate | `python3 scripts/dataset_card.py --corpus {corpus}` |")
+    lines += [
+        "",
+        "## What this corpus is for",
+        "",
+        "Consented photos of stool, labelled by a human reviewer, for research on a stool-form",
+        "classifier. The corpus may not be used to diagnose disease, to identify a person, or to",
+        "train a model that speaks to a patient with clinical authority. A model's output stays",
+        "provisional until the person logging confirms it: see [PRODUCT-DECISIONS.md](PRODUCT-DECISIONS.md).",
+        "",
+    ]
+    if summary["activeSamples"] == 0:
+        lines += [
+            "This corpus holds no consented images yet. Every count of zero below is a real count of",
+            "an empty manifest, not a placeholder, and the pending facts stay pending until the",
+            "pipeline collects them.",
+            "",
+        ]
+    lines += [
+        "## Contributor-level split policy",
+        "",
+        "Splits are derived from the salted pseudonymous subject key, never assigned per photo: the",
+        "first byte of the key decides the split, `< 205` train, `< 230` validation, otherwise test",
+        "(the ingestion rule in `scripts/ingest_training_photo.py`). One contributor's photos all land",
+        "in one split, and this generator refuses a manifest where a subject key appears in two splits",
+        "or where a recorded split is not the one its subject key derives. Both edges are stated here",
+        "so the policy on this page is the policy in the code.",
+        "",
+        "| Split | Contributors | Active samples |",
+        "|---|---:|---:|",
+    ]
+    for split in SPLITS:
+        entry = summary["bySplit"][split]
+        lines.append(f"| `{split}` | {entry['contributors']} | {entry['samples']} |")
+    lines += ["", "## Class balance (active samples only)", ""]
+    lines += _count_table("Type", [(f"Type {day}", summary["bristol"][str(day)]) for day in range(1, 8)])
+    lines += _count_table("Color", [(f"`{name}`", count) for name, count in summary["colors"].items()])
+    lines += _count_table("Quality", [(f"`{name}`", count) for name, count in summary["qualities"].items()])
+    lines += _count_table("Review status", [(f"`{name}`", count) for name, count in summary["review"].items()])
+    lines += [
+        "A withdrawn sample is excluded from every table above. Labels are what a reviewer saw, not a",
+        "diagnosis: [LABELING_GUIDE.md](LABELING_GUIDE.md) says what a label may and may not assert.",
+        "",
+        "## Exclusions and withdrawals",
+        "",
+        "A withdrawal appends a tombstone, deletes the derived image and any raw copy, and stays in the",
+        "history. Contribution ids and reasons are published here because a deletion receipt is",
+        "checkable; subject keys and labels are never published.",
+        "",
+    ]
+    if summary["withdrawalsDetail"]:
+        lines += [
+            "| Contribution | Withdrawn at | Reason | Artifacts removed |",
+            "|---|---|---|---:|",
+        ]
+        for entry in summary["withdrawalsDetail"]:
+            lines.append(
+                f"| `{entry['contributionId']}` | {entry['withdrawnAt'] or 'pending'} | "
+                f"{entry['reason'] or 'pending'} | {entry['artifacts']} |"
+            )
+    else:
+        lines.append("No withdrawals are recorded.")
+    lines += [
+        "",
+        "## Limitations",
+        "",
+        "- Composition (devices, contexts, licenses) is pending, so the corpus is not yet a",
+        "  representative sample of anything and must not be described as one.",
+        "- Review status is a human decision, not a clinical gold standard; `user-confirmed` means the",
+        "  person who took the photo agreed with the proposal.",
+        "- A held-out split measures generalization across contributors, not across a population.",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def load_corpus(corpus: Path) -> list[dict]:
+    try:
+        return load_manifest(corpus / "manifest.jsonl")
+    except (CorpusError, json.JSONDecodeError) as exc:
+        raise CardError(f"the manifest at {corpus / 'manifest.jsonl'} cannot be read: {exc}") from exc
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Generate the Timmy dataset card from the corpus manifest.")
+    parser.add_argument("--corpus", required=True, help="dataset root holding manifest.jsonl")
+    parser.add_argument("--out", help="write the card here instead of stdout")
+    parser.add_argument("--check", help="fail if the card at this path is not what would be generated")
+    parser.add_argument("--json", action="store_true", help="print the summary object instead of the card")
+    parser.add_argument("--corpus-label", help="path to name on the card (defaults to --corpus)")
+    args = parser.parse_args(argv)
+
+    corpus = Path(args.corpus)
+    try:
+        records = load_corpus(corpus)
+        summary = summarize(records)
+    except CardError as exc:
+        print(f"refusing to render a dataset card: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps(summary, indent=2, sort_keys=True))
+        return 0
+
+    card = render_card(summary, corpus=args.corpus_label or args.corpus)
+
+    if args.check:
+        target = Path(args.check)
+        existing = target.read_text(encoding="utf-8") if target.exists() else ""
+        if existing != card:
+            print(
+                f"{target} is out of date: regenerate it with "
+                f"`python3 scripts/dataset_card.py --corpus {args.corpus_label or args.corpus} --out {target}`",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"{target} matches the corpus manifest")
+        return 0
+
+    if args.out:
+        target = Path(args.out)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(card, encoding="utf-8")
+        print(f"wrote {target} ({summary['activeSamples']} active samples, {summary['contributors']} contributors)")
+        return 0
+
+    sys.stdout.write(card)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/ingest_training_photo.py

@@ -12,6 +12,8 @@ from pathlib import Path
 
 from PIL import Image, ImageOps
 
+from corpus_manifest import CorpusError, append_record, assert_admissible, build_record, revoke, sha256_hex
+
 COLORS = ("brown", "green", "yellow", "pale", "red", "black")
 QUALITIES = ("good", "fair", "poor")
 REVIEWERS = ("user-confirmed", "clinician-reviewed")
@@ -19,27 +21,62 @@ REVIEWERS = ("user-confirmed", "clinician-reviewed")
 
 def parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser()
-    p.add_argument("--input", required=True)
+    p.add_argument("--input")
     p.add_argument("--output-dir", required=True)
-    p.add_argument("--subject-id", required=True)
-    p.add_argument("--consent-version", required=True)
-    p.add_argument("--bristol-type", required=True, type=int, choices=range(1, 8))
-    p.add_argument("--color", required=True, choices=COLORS)
-    p.add_argument("--quality", required=True, choices=QUALITIES)
-    p.add_argument("--reviewer", required=True, choices=REVIEWERS)
+    p.add_argument("--subject-id")
+    p.add_argument("--consent-version")
+    p.add_argument("--contribution-id")
+    p.add_argument("--bristol-type", type=int, choices=range(1, 8))
+    p.add_argument("--color", choices=COLORS)
+    p.add_argument("--quality", choices=QUALITIES)
+    p.add_argument("--reviewer", choices=REVIEWERS)
+    # Revocation is a corpus operation, not an ingestion: it needs the dataset and a reason.
+    p.add_argument("--revoke", metavar="CONTRIBUTION_ID")
+    p.add_argument("--reason")
     return p
 
 
+def require_ingest_arguments(args: argparse.Namespace) -> None:
+    if not args.consent_version or not args.consent_version.strip():
+        raise SystemExit("consent version is required")
+    if not args.reviewer:
+        raise SystemExit("a human review status is required")
+    missing = [
+        flag
+        for flag, value in (
+            ("--input", args.input),
+            ("--subject-id", args.subject_id),
+            ("--contribution-id", args.contribution_id),
+            ("--bristol-type", args.bristol_type),
+            ("--color", args.color),
+            ("--quality", args.quality),
+        )
+        if value is None or value == ""
+    ]
+    if missing:
+        raise SystemExit(f"ingesting a sample also needs {', '.join(missing)}")
+
+
 def main() -> int:
     args = parser().parse_args()
+    if args.revoke:
+        if not args.reason:
+            raise SystemExit("revoking a contribution needs a recorded reason")
+        try:
+            tombstone = revoke(Path(args.output_dir), args.revoke, datetime.now(timezone.utc).isoformat(), args.reason)
+        except CorpusError as exc:
+            raise SystemExit(str(exc)) from exc
+        print(json.dumps(tombstone))
+        return 0
+
+    require_ingest_arguments(args)
     salt = os.environ.get("TIMMY_DATASET_SALT", "")
     if len(salt) < 8:
         raise SystemExit("TIMMY_DATASET_SALT must contain at least 8 characters")
-    if not args.consent_version.strip():
-        raise SystemExit("consent version is required")
 
     try:
-        with Image.open(args.input) as source:
+        raw_bytes = Path(args.input).read_bytes()
+        with Image.open(io.BytesIO(raw_bytes)) as source:
             image = ImageOps.exif_transpose(source).convert("RGB")
             image.thumbnail((1200, 1200))
             buffer = io.BytesIO()
@@ -55,37 +92,34 @@ def main() -> int:
 
     output = Path(args.output_dir)
     images = output / "images"
-    images.mkdir(parents=True, exist_ok=True)
     relative_path = f"images/{image_id}.jpg"
     target = output / relative_path
-    if not target.exists():
-        target.write_bytes(data)
 
-    record = {
-        "schemaVersion": 1,
-        "imageId": image_id,
-        "relativePath": relative_path,
-        "subjectKey": subject_key,
-        "split": split,
-        "consentVersion": args.consent_version.strip(),
-        "ingestedAt": datetime.now(timezone.utc).isoformat(),
-        "labels": {
-            "bristolType": args.bristol_type,
-            "color": args.color,
-            "quality": args.quality,
-        },
-        "review": {"status": args.reviewer},
-        "derivation": {
-            "format": "jpeg",
-            "maxDimension": 1200,
-            "metadataStripped": True,
-        },
-    }
-    with (output / "manifest.jsonl").open("a", encoding="utf-8") as manifest:
-        manifest.write(json.dumps(record, separators=(",", ":")) + "\n")
+    now = datetime.now(timezone.utc).isoformat()
+    record = build_record(
+        contribution_id=args.contribution_id,
+        consent_version=args.consent_version,
+        subject_key=subject_key,
+        split=split,
+        labels={"bristolType": args.bristol_type, "color": args.color, "quality": args.quality},
+        review_status=args.reviewer,
+        derived_sha256=image_id,
+        raw_sha256=sha256_hex(raw_bytes),
+        ingested_at=now,
+    )
+    try:
+        # Refuse a duplicate contribution before any byte lands in the active dataset.
+        assert_admissible(output / "manifest.jsonl", record)
+        images.mkdir(parents=True, exist_ok=True)
+        if not target.exists():
+            target.write_bytes(data)
+        append_record(output / "manifest.jsonl", record)
+    except CorpusError as exc:
+        raise SystemExit(str(exc)) from exc
     print(json.dumps(record))
     return 0
 
 
+
 if __name__ == "__main__":
     sys.exit(main())

scripts/operator_backup.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""Operator backup and restore for the records Timmy must not lose.
+
+The app keeps the journal in the person's own browser, so the server side of Timmy holds no diary.
+What the operator does hold, and what cannot be rebuilt from anywhere else, is the corpus: the
+append-only ``manifest.jsonl`` with its provenance records and its withdrawal tombstones, plus the
+derived images those records point at. Losing that file loses the proof that a participant
+withdrew, which is the one receipt the project has promised to keep.
+
+This tool therefore:
+
+- archives only records, and names every path it refused to archive with the reason
+  (``model-weights``, ``transient-inference``, ``secret``, ``log``, ``symlink``, ``oversize``), so a
+  missing file is an auditable decision instead of a silent omission;
+- writes one SHA-256 per archived member and a reproducible archive (sorted members, zeroed
+  timestamps and ownership), so two backups of the same records are byte-identical;
+- verifies every digest, member name, and record count before a restore writes anything, and
+  refuses absolute, traversal, link, and unlisted members.
+
+Usage:
+
+    python3 scripts/operator_backup.py backup --source /srv/timmy-corpus --archive /srv/backups/timmy.tar.gz
+    python3 scripts/operator_backup.py verify --archive /srv/backups/timmy.tar.gz --manifest /srv/backups/timmy.tar.gz.manifest.json
+    python3 scripts/operator_backup.py restore --archive ... --manifest ... --target /srv/timmy-corpus.restored
+"""
+from __future__ import annotations
+
+import argparse
+import gzip
+import hashlib
+import io
+import json
+import os
+import sys
+import tarfile
+from datetime import datetime, timezone
+from pathlib import Path, PurePosixPath
+
+SCHEMA_VERSION = 1
+TOOL = "operator_backup.py"
+PAYLOAD_PREFIX = "payload/"
+DEFAULT_MAX_BYTES = 64 * 1024 * 1024
+
+WEIGHT_SUFFIXES = (".gguf", ".safetensors", ".onnx", ".bin", ".pt", ".ckpt", ".pth")
+WEIGHT_DIRS = ("weights", "models")
+TRANSIENT_DIRS = ("transient", "inference-tmp", "inference-tmp-images", "uploads", "tmp", "cache")
+LOG_DIRS = ("logs",)
+LOG_SUFFIXES = (".log",)
+SECRET_NAMES = (".env", "id_rsa", "id_ed25519", "id_ecdsa", "tokens.json", "credentials.json")
+SECRET_SUFFIXES = (".key", ".pem", ".p12", ".pfx", ".env")
+
+
+class BackupError(Exception):
+    """A refusal that is reported on stderr and exits non-zero."""
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def classify(relative: PurePosixPath) -> str | None:
+    """Return the reason a path is not archived, or ``None`` when it is a record."""
+    parts = relative.parts[:-1]
+    name = relative.name
+    lowered = [part.lower() for part in parts]
+    suffix = PurePosixPath(name.lower()).suffix
+
+    if name.lower().startswith(".env") or name.lower() in SECRET_NAMES or suffix in SECRET_SUFFIXES:
+        return "secret"
+    if suffix in WEIGHT_SUFFIXES or any(part in WEIGHT_DIRS for part in lowered):
+        return "model-weights"
+    if any(part in TRANSIENT_DIRS for part in lowered):
+        return "transient-inference"
+    if any(part in LOG_DIRS for part in lowered) or suffix in LOG_SUFFIXES:
+        return "log"
+    return None
+
+
+def record_counts(manifest_path: Path) -> dict[str, int]:
+    """Count the append-only manifest the way a trainer would read it."""
+    counts = {"samples": 0, "tombstones": 0, "activeSamples": 0}
+    if not manifest_path.is_file():
+        return counts
+    revoked: set[str] = set()
+    samples: list[dict] = []
+    for line in manifest_path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError as error:
+            raise BackupError(f"manifest {manifest_path} is not valid JSON Lines: {error}") from error
+        kind = entry.get("recordType")
+        if kind == "sample":
+            samples.append(entry)
+            counts["samples"] += 1
+        elif kind == "tombstone":
+            counts["tombstones"] += 1
+            if entry.get("contributionId"):
+                revoked.add(str(entry["contributionId"]))
+    counts["activeSamples"] = sum(
+        1 for entry in samples
+        if str(entry.get("contributionId")) not in revoked
+        and str((entry.get("lifecycle") or {}).get("state")) == "active"
+    )
+    return counts
+
+
+def collect(source: Path, max_bytes: int) -> tuple[list[tuple[PurePosixPath, Path]], list[dict]]:
+    included: list[tuple[PurePosixPath, Path]] = []
+    excluded: list[dict] = []
+    for dirpath, dirnames, filenames in os.walk(source, followlinks=False):
+        dirnames.sort()
+        base = Path(dirpath)
+        for name in sorted(filenames):
+            path = base / name
+            relative = PurePosixPath(path.relative_to(source).as_posix())
+            if path.is_symlink():
+                excluded.append({"path": str(relative), "reason": "symlink", "bytes": 0})
+                continue
+            reason = classify(relative)
+            if reason:
+                excluded.append({"path": str(relative), "reason": reason, "bytes": _size(path)})
+                continue
+            size = _size(path)
+            if size > max_bytes:
+                excluded.append({"path": str(relative), "reason": "oversize", "bytes": size})
+                continue
+            included.append((relative, path))
+    included.sort(key=lambda item: str(item[0]))
+    excluded.sort(key=lambda entry: entry["path"])
+    return included, excluded
+
+
+def _size(path: Path) -> int:
+    try:
+        return path.stat().st_size
+    except OSError:
+        return 0
+
+
+def backup(*, source: Path, archive: Path, manifest_path: Path, label: str, max_bytes: int) -> dict:
+    if not source.is_dir():
+        raise BackupError(f"source {source} is not a directory")
+    if archive.exists():
+        raise BackupError(f"archive {archive} already exists; move it aside instead of overwriting a backup")
+
+    included, excluded = collect(source, max_bytes)
+    files = [{"path": str(relative), "sha256": sha256_file(path), "bytes": _size(path)} for relative, path in included]
+    counts = record_counts(source / "manifest.jsonl")
+
+    archive.parent.mkdir(parents=True, exist_ok=True)
+    partial = archive.with_name(archive.name + ".partial")
+    with partial.open("wb") as raw:
+        # gzip mtime=0 and zeroed tar metadata keep two backups of the same records identical.
+        with gzip.GzipFile(fileobj=raw, mode="wb", mtime=0) as compressed:
+            with tarfile.open(fileobj=compressed, mode="w", format=tarfile.PAX_FORMAT) as tar:
+                for (relative, path), entry in zip(included, files):
+                    payload = path.read_bytes()
+                    info = tarfile.TarInfo(PAYLOAD_PREFIX + str(relative))
+                    info.size = len(payload)
+                    info.mode = 0o644
+                    info.mtime = 0
+                    info.uid = info.gid = 0
+                    info.uname = info.gname = ""
+                    tar.addfile(info, io.BytesIO(payload))
+                    if hashlib.sha256(payload).hexdigest() != entry["sha256"]:
+                        raise BackupError(f"{relative} changed while it was being archived")
+    os.replace(partial, archive)
+
+    manifest = {
+        "schemaVersion": SCHEMA_VERSION,
+        "tool": TOOL,
+        "createdAt": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "label": label,
+        "sourceLabel": source.name,
+        "archive": {"name": archive.name, "sha256": sha256_file(archive), "bytes": _size(archive)},
+        "records": counts,
+        "files": files,
+        "excluded": excluded,
+    }
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return {
+        "archive": str(archive),
+        "manifest": str(manifest_path),
+        "files": len(files),
+        "bytes": manifest["archive"]["bytes"],
+        "records": counts,
+        "excluded": {entry["reason"]: sum(1 for other in excluded if other["reason"] == entry["reason"]) for entry in excluded},
+    }
+
+
+def load_manifest(manifest_path: Path) -> dict:
+    if not manifest_path.is_file():
+        raise BackupError(f"manifest {manifest_path} does not exist")
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        raise BackupError(f"manifest {manifest_path} is not valid JSON: {error}") from error
+    if manifest.get("schemaVersion") != SCHEMA_VERSION:
+        raise BackupError(f"manifest schemaVersion {manifest.get('schemaVersion')!r} is not {SCHEMA_VERSION}")
+    return manifest
+
+
+def verified_members(archive: Path, manifest: dict) -> list[tuple[str, bytes]]:
+    """Check every member of the archive before anything is written to disk."""
+    if not archive.is_file():
+        raise BackupError(f"archive {archive} does not exist")
+    expected = {entry["path"]: entry for entry in manifest.get("files") or []}
+    extracted: list[tuple[str, bytes]] = []
+    seen: set[str] = set()
+    with tarfile.open(archive, "r:gz") as tar:
+        for info in tar.getmembers():
+            if info.isdir():
+                continue
+            if info.issym() or info.islnk():
+                raise BackupError(f"archive member {info.name!r} is a link, not a regular file")
+            if not info.isfile():
+                raise BackupError(f"archive member {info.name!r} is not a regular file")
+            if os.path.isabs(info.name):
+                raise BackupError(f"archive member {info.name!r} is an absolute path")
+            if not info.name.startswith(PAYLOAD_PREFIX):
+                raise BackupError(f"archive member {info.name!r} is not under {PAYLOAD_PREFIX}")
+            relative = info.name[len(PAYLOAD_PREFIX):]
+            parts = PurePosixPath(relative).parts
+            if not parts or any(part in ("..", ".", "") for part in parts):
+                raise BackupError(f"archive member {info.name!r} resolves outside the restore root")
+            if relative not in expected:
+                raise BackupError(f"archive member {info.name!r} is not listed in the manifest")
+            handle = tar.extractfile(info)
+            if handle is None:
+                raise BackupError(f"archive member {info.name!r} cannot be read")
+            payload = handle.read()
+            if hashlib.sha256(payload).hexdigest() != expected[relative]["sha256"]:
+                raise BackupError(
+                    f"archive member {info.name!r} does not match the manifest digest "
+                    "(the archive changed after it was recorded)"
+                )
+            seen.add(relative)
+            extracted.append((relative, payload))
+    missing = sorted(set(expected) - seen)
+    if missing:
+        raise BackupError(f"archive is missing members the manifest lists: {', '.join(missing)}")
+    return extracted
+
+
+def verify(*, archive: Path, manifest_path: Path) -> dict:
+    manifest = load_manifest(manifest_path)
+    members_list = verified_members(archive, manifest)
+    return {"archive": str(archive), "files": len(members_list), "records": manifest.get("records", {})}
+
+
+def restore(*, archive: Path, manifest_path: Path, target: Path) -> dict:
+    manifest = load_manifest(manifest_path)
+    if target.exists():
+        if not target.is_dir():
+            raise BackupError(f"restore target {target} is not a directory")
+        if any(target.iterdir()):
+            raise BackupError(f"restore target {target} is not empty; restore into a new directory")
+    # Digests and member names are checked before the first byte is written, so a hostile or
+    # tampered archive cannot leave a half-restored record set behind.
+    members_list = verified_members(archive, manifest)
+    target.mkdir(parents=True, exist_ok=True)
+    for relative, payload in members_list:
+        destination = target / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(payload)
+        os.chmod(destination, 0o644)
+
+    counts = record_counts(target / "manifest.jsonl")
+    if manifest.get("records") and counts != manifest["records"]:
+        raise BackupError(
+            f"restored record counts {counts} do not match the backup manifest {manifest['records']}"
+        )
+    return {"target": str(target), "files": len(members_list), "records": counts}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    backup_parser = subparsers.add_parser("backup", help="archive the records and write a manifest")
+    backup_parser.add_argument("--source", required=True, type=Path)
+    backup_parser.add_argument("--archive", required=True, type=Path)
+    backup_parser.add_argument("--manifest", type=Path)
+    backup_parser.add_argument("--label", default="manual")
+    backup_parser.add_argument("--max-bytes", type=int, default=DEFAULT_MAX_BYTES)
+
+    verify_parser = subparsers.add_parser("verify", help="recompute every digest in an archive")
+    verify_parser.add_argument("--archive", required=True, type=Path)
+    verify_parser.add_argument("--manifest", required=True, type=Path)
+
+    restore_parser = subparsers.add_parser("restore", help="verify, then write the records into a new directory")
+    restore_parser.add_argument("--archive", required=True, type=Path)
+    restore_parser.add_argument("--manifest", required=True, type=Path)
+    restore_parser.add_argument("--target", required=True, type=Path)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "backup":
+            manifest_path = args.manifest or args.archive.with_name(args.archive.name + ".manifest.json")
+            receipt = backup(
+                source=args.source, archive=args.archive, manifest_path=manifest_path,
+                label=args.label, max_bytes=args.max_bytes,
+            )
+        elif args.command == "verify":
+            receipt = verify(archive=args.archive, manifest_path=args.manifest)
+        else:
+            receipt = restore(archive=args.archive, manifest_path=args.manifest, target=args.target)
+    except BackupError as error:
+        print(f"refused: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(receipt, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/review_corpus.py

@@ -0,0 +1,461 @@
+#!/usr/bin/env python3
+"""Blind reviewer and adjudication tool for the Timmy training corpus (issue #26).
+
+A reviewer reads one active sample, commits their own label without seeing what the model
+said, and only then can the model answer be revealed. Adjudication is a second reader's
+ruling, appended after the review it resolves; nothing in the review ledger is ever rewritten.
+A withdrawn contribution cannot be queued, reviewed, revealed, adjudicated, or trained on.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# The tool sits beside corpus_manifest.py and is also imported by path from the test suite.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from corpus_manifest import (  # noqa: E402
+    COLORS,
+    QUALITIES,
+    CorpusError,
+    active_records,
+    load_manifest,
+)
+
+SCHEMA_VERSION = 1
+REVIEW = "review"
+ADJUDICATION = "adjudication"
+DECISIONS = ("agreed", "corrected", "excluded")
+ADJUDICATIONS = ("upheld", "corrected", "excluded")
+LABEL_FIELDS = ("bristolType", "color", "quality")
+_TIMESTAMP = re.compile(r"^\d{4}-\d{2}-\d{2}T")
+
+
+class ReviewError(Exception):
+    """A review action that must never happen is being attempted."""
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _manifest_path(dataset_root: Path) -> Path:
+    return Path(dataset_root) / "manifest.jsonl"
+
+
+def review_ledger_path(dataset_root: Path) -> Path:
+    return Path(dataset_root) / "reviews.jsonl"
+
+
+def load_reviews(dataset_root: Path) -> list[dict]:
+    """Read the append-only review ledger in order. A missing ledger is an unreviewed corpus."""
+    path = review_ledger_path(dataset_root)
+    if not path.exists():
+        return []
+    with path.open("r", encoding="utf-8") as ledger:
+        return [json.loads(line) for line in ledger.read().splitlines() if line.strip()]
+
+
+def _history(reviews: list[dict], contribution_id: str) -> list[dict]:
+    return [record for record in reviews if record.get("contributionId") == contribution_id]
+
+
+def _append_review(dataset_root: Path, record: dict) -> dict:
+    path = review_ledger_path(dataset_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as ledger:
+        ledger.write(json.dumps(record, separators=(",", ":"), sort_keys=False) + "\n")
+    return record
+
+
+def _active_sample(dataset_root: Path, contribution_id: str) -> dict:
+    """The one active sample for this contribution, or a refusal that names why there is none."""
+    records = load_manifest(_manifest_path(dataset_root))
+    for sample in active_records(records):
+        if sample.get("contributionId") == contribution_id:
+            return sample
+    if any(record.get("contributionId") == contribution_id for record in records):
+        raise ReviewError(
+            f"contribution {contribution_id} was withdrawn and cannot be reviewed, revealed, or trained on"
+        )
+    raise ReviewError(f"no active sample carries contribution {contribution_id}")
+
+
+def _validate_labels(labels: object) -> dict:
+    if not isinstance(labels, dict) or set(labels) != set(LABEL_FIELDS):
+        raise ReviewError("a decided label must carry bristolType, color, and quality")
+    if labels["bristolType"] not in range(1, 8):
+        raise ReviewError("bristolType must be 1-7")
+    if labels["color"] not in COLORS or labels["quality"] not in QUALITIES:
+        raise ReviewError("color and quality must be from the documented vocabularies")
+    return {field: labels[field] for field in LABEL_FIELDS}
+
+
+def _decide(
+    *,
+    reviewer: str,
+    decision: str,
+    labels,
+    exclusion_reason,
+    proposed: dict,
+    allowed: tuple[str, ...],
+    change_subject: str = "proposed label",
+) -> dict:
+    """Validate one human decision and return the fields it contributes to the ledger."""
+    reviewer_id = reviewer.strip() if isinstance(reviewer, str) else ""
+    if not reviewer_id:
+        raise ReviewError("reviewer is required")
+    if decision not in allowed:
+        raise ReviewError(f"decision must be one of {', '.join(allowed)}")
+    if decision in ("agreed", "upheld"):
+        return {"reviewer": reviewer_id, "decision": decision, "labels": dict(proposed)}
+    if decision == "excluded":
+        if not isinstance(exclusion_reason, str) or not exclusion_reason.strip():
+            raise ReviewError("exclusion needs a recorded reason")
+        return {
+            "reviewer": reviewer_id,
+            "decision": decision,
+            "exclusionReason": exclusion_reason.strip(),
+        }
+    decided = _validate_labels(labels)
+    if decided == proposed:
+        raise ReviewError(f"a corrected decision must change the {change_subject}")
+    return {"reviewer": reviewer_id, "decision": decision, "labels": decided}
+
+
+def commit_review(
+    dataset_root: Path,
+    contribution_id: str,
+    reviewer: str,
+    decision: str,
+    labels: dict | None = None,
+    exclusion_reason: str | None = None,
+    at: str | None = None,
+) -> dict:
+    """Append one human label decision for an active sample, before any model answer is shown."""
+    dataset_root = Path(dataset_root)
+    reviews = load_reviews(dataset_root)
+    # A withdrawal outranks every other refusal: nothing may be reviewed out of a corpus that no
+    # longer holds the sample, and the refusal has to say so.
+    sample = _active_sample(dataset_root, contribution_id)
+    if _history(reviews, contribution_id):
+        raise ReviewError(
+            f"contribution {contribution_id} is already reviewed; "
+            "adjudication is the only way to change a decision"
+        )
+    proposed = dict(sample["labels"])
+    committed = _decide(
+        reviewer=reviewer,
+        decision=decision,
+        labels=labels,
+        exclusion_reason=exclusion_reason,
+        proposed=proposed,
+        allowed=DECISIONS,
+    )
+    stamped = at or _now()
+    if not _TIMESTAMP.match(stamped):
+        raise ReviewError("committed timestamp must be ISO-8601")
+    record = {
+        "schemaVersion": SCHEMA_VERSION,
+        "recordType": REVIEW,
+        "contributionId": contribution_id,
+        "imageId": sample["imageId"],
+        "proposed": proposed,
+        **committed,
+        "committedAt": stamped,
+    }
+    return _append_review(dataset_root, record)
+
+
+def load_predictions(path: Path) -> dict:
+    """Read a model answer file: one JSON document, or one JSON object per line.
+
+    A pretty-printed object is a document, not a set of lines, so it is parsed whole; only a file
+    that is not valid JSON as a document is read line by line.
+    """
+    text = Path(path).read_text(encoding="utf-8")
+    if not text.strip():
+        return {"answers": {}}
+    try:
+        document = json.loads(text)
+    except json.JSONDecodeError:
+        document = None
+    if isinstance(document, dict):
+        if "answers" in document:
+            return document
+        if document and all(isinstance(value, dict) for value in document.values()):
+            return {"answers": document}
+        raise ReviewError("every prediction needs a contributionId or imageId")
+    answers: dict[str, dict] = {}
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        entry = json.loads(line)
+        key = entry.get("contributionId") or entry.get("imageId")
+        if not key:
+            raise ReviewError("every prediction needs a contributionId or imageId")
+        answers[key] = entry
+    return {"answers": answers}
+
+
+def _model_answer(predictions: dict | None, contribution_id: str, image_id: str) -> dict | None:
+    if not isinstance(predictions, dict):
+        return None
+    answers = predictions.get("answers", predictions)
+    for key in (contribution_id, image_id):
+        entry = answers.get(key)
+        if isinstance(entry, dict):
+            labels = {field: entry.get(field) for field in LABEL_FIELDS}
+            if all(value is not None for value in labels.values()):
+                answer = {"labels": labels}
+                if "confidence" in entry:
+                    answer["confidence"] = entry["confidence"]
+                if "model" in predictions:
+                    answer["model"] = predictions["model"]
+                return answer
+    return None
+
+
+def reveal(dataset_root: Path, contribution_id: str, predictions: dict | None = None) -> dict:
+    """Show the model's answer for a sample, but only after a human has committed their own.
+
+    The order is the whole point: the reviewer's label is already fixed in the ledger when this
+    runs, so a model answer can be read for disagreement but cannot steer the human into agreeing.
+    """
+    dataset_root = Path(dataset_root)
+    sample = _active_sample(dataset_root, contribution_id)
+    history = _history(load_reviews(dataset_root), contribution_id)
+    if not history:
+        raise ReviewError(
+            f"the model answer for contribution {contribution_id} stays hidden until a review is committed"
+        )
+    reviewed = history[0]
+    human_labels = dict(reviewed["labels"]) if "labels" in reviewed else None
+    answer = _model_answer(predictions, contribution_id, sample["imageId"])
+    disagree = []
+    if answer and human_labels:
+        disagree = [field for field in LABEL_FIELDS if answer["labels"][field] != human_labels[field]]
+    return {
+        "contributionId": contribution_id,
+        "human": {"reviewer": reviewed["reviewer"], "decision": reviewed["decision"], "labels": human_labels},
+        "model": answer,
+        "disagreeFields": disagree,
+        "disagreement": bool(disagree),
+    }
+
+
+def adjudicate(
+    dataset_root: Path,
+    contribution_id: str,
+    reviewer: str,
+    decision: str,
+    labels: dict | None = None,
+    exclusion_reason: str | None = None,
+    at: str | None = None,
+) -> dict:
+    """Append a second reader's ruling on a review. The review it resolves stays in the ledger."""
+    dataset_root = Path(dataset_root)
+    reviews = load_reviews(dataset_root)
+    sample = _active_sample(dataset_root, contribution_id)
+    history = _history(reviews, contribution_id)
+    if not history:
+        raise ReviewError(f"no review to adjudicate for contribution {contribution_id}")
+    if any(record.get("recordType") == ADJUDICATION for record in history):
+        raise ReviewError(f"contribution {contribution_id} is already adjudicated")
+    reviewed = history[0]
+    if isinstance(reviewer, str) and reviewer.strip() == reviewed["reviewer"]:
+        raise ReviewError("adjudication needs a second reviewer, not the reviewer who decided")
+    reviewed_labels = dict(reviewed.get("labels") or {})
+    ruling = _decide(
+        reviewer=reviewer,
+        decision=decision,
+        labels=labels,
+        exclusion_reason=exclusion_reason,
+        proposed=reviewed_labels,
+        allowed=ADJUDICATIONS,
+        change_subject="reviewed label",
+    )
+    stamped = at or _now()
+    if not _TIMESTAMP.match(stamped):
+        raise ReviewError("committed timestamp must be ISO-8601")
+    record = {
+        "schemaVersion": SCHEMA_VERSION,
+        "recordType": ADJUDICATION,
+        "contributionId": contribution_id,
+        "imageId": sample["imageId"],
+        "resolvesRecord": reviews.index(reviewed) + 1,
+        "resolves": {"reviewer": reviewed["reviewer"], "decision": reviewed["decision"]},
+        **ruling,
+        "adjudicatedAt": stamped,
+    }
+    return _append_review(dataset_root, record)
+
+
+def trainable_records(dataset_root: Path) -> list[dict]:
+    """The training set this corpus is allowed to produce right now.
+
+    A sample is trainable only if it is still active, a human reviewed it, and the final decision
+    was not an exclusion. Unreviewed proposals are never training data, and an adjudication
+    replaces the label it resolved without deleting it.
+    """
+    dataset_root = Path(dataset_root)
+    reviews = load_reviews(dataset_root)
+    trainable = []
+    for sample in active_records(load_manifest(_manifest_path(dataset_root))):
+        history = _history(reviews, sample["contributionId"])
+        if not history:
+            continue
+        final = history[-1]
+        if final["decision"] == "excluded":
+            continue
+        entry = {
+            "contributionId": sample["contributionId"],
+            "imageId": sample["imageId"],
+            "relativePath": sample["relativePath"],
+            "split": sample["split"],
+            "labels": dict(final["labels"]),
+            "reviewedBy": history[0]["reviewer"],
+        }
+        if final.get("recordType") == ADJUDICATION:
+            entry["adjudicatedBy"] = final["reviewer"]
+        trainable.append(entry)
+    return trainable
+
+
+def _decision_from(args: argparse.Namespace, *, uphold: bool) -> tuple[str, dict | None, str | None]:
+    """Translate the flag shape into one decision, refusing a half-specified review."""
+    label_flags = [args.bristol, args.color, args.quality]
+    if args.exclude:
+        if any(flag is not None for flag in label_flags):
+            raise ReviewError("an exclusion cannot carry labels")
+        return "excluded", None, args.exclude
+    if uphold and args.upheld:
+        if any(flag is not None for flag in label_flags):
+            raise ReviewError("an upheld review keeps the reviewed label; pass no labels with it")
+        return "upheld", None, None
+    if not uphold and args.agree:
+        if any(flag is not None for flag in label_flags):
+            raise ReviewError("agreeing keeps the proposed label; pass no labels with it")
+        return "agreed", None, None
+    if all(flag is not None for flag in label_flags):
+        return "corrected", {"bristolType": args.bristol, "color": args.color, "quality": args.quality}, None
+    if any(flag is not None for flag in label_flags):
+        raise ReviewError("a corrected decision needs --bristol, --color, and --quality together")
+    hint = "--upheld, a corrected label, or --exclude" if uphold else "--agree, a corrected label, or --exclude"
+    raise ReviewError(f"a decision is required: pass {hint}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Blind review and adjudication for the Timmy training corpus.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    queue = commands.add_parser("queue", help="list the blind review queue")
+    queue.add_argument("--dataset", required=True)
+    queue.add_argument("--limit", type=int)
+
+    review = commands.add_parser("review", help="commit a human label decision")
+    review.add_argument("--dataset", required=True)
+    review.add_argument("--contribution", required=True)
+    review.add_argument("--reviewer", required=True)
+    review.add_argument("--agree", action="store_true", help="the proposed label is correct")
+    review.add_argument("--bristol", type=int, choices=range(1, 8))
+    review.add_argument("--color", choices=COLORS)
+    review.add_argument("--quality", choices=QUALITIES)
+    review.add_argument("--exclude", metavar="REASON")
+
+    reveal = commands.add_parser("reveal", help="show the model answer after the human commits")
+    reveal.add_argument("--dataset", required=True)
+    reveal.add_argument("--contribution", required=True)
+    reveal.add_argument("--predictions", help="JSON or JSONL of model answers; omit if none exist")
+
+    adjudicate_parser = commands.add_parser("adjudicate", help="append a second reader's ruling")
+    adjudicate_parser.add_argument("--dataset", required=True)
+    adjudicate_parser.add_argument("--contribution", required=True)
+    adjudicate_parser.add_argument("--reviewer", required=True)
+    adjudicate_parser.add_argument("--bristol", type=int, choices=range(1, 8))
+    adjudicate_parser.add_argument("--color", choices=COLORS)
+    adjudicate_parser.add_argument("--quality", choices=QUALITIES)
+    adjudicate_parser.add_argument("--exclude", metavar="REASON")
+    adjudicate_parser.add_argument("--upheld", action="store_true", help="keep the reviewed label")
+
+    trainable = commands.add_parser("trainable", help="list what a trainer is allowed to read")
+    trainable.add_argument("--dataset", required=True)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "queue":
+            items = build_queue(Path(args.dataset), limit=args.limit)
+            print(json.dumps({"count": len(items), "items": items}, indent=2))
+            return 0
+        if args.command == "review":
+            decision, labels, exclusion_reason = _decision_from(args, uphold=False)
+            record = commit_review(
+                Path(args.dataset), args.contribution, args.reviewer,
+                decision, labels, exclusion_reason,
+            )
+            print(json.dumps(record, indent=2))
+            return 0
+        if args.command == "reveal":
+            predictions = load_predictions(args.predictions) if args.predictions else None
+            print(json.dumps(reveal(Path(args.dataset), args.contribution, predictions), indent=2))
+            return 0
+        if args.command == "adjudicate":
+            decision, labels, exclusion_reason = _decision_from(args, uphold=True)
+            record = adjudicate(
+                Path(args.dataset), args.contribution, args.reviewer,
+                decision, labels, exclusion_reason,
+            )
+            print(json.dumps(record, indent=2))
+            return 0
+        if args.command == "trainable":
+            items = trainable_records(Path(args.dataset))
+            print(json.dumps({"count": len(items), "items": items}, indent=2))
+            return 0
+    except (ReviewError, CorpusError) as error:
+        print(str(error), file=sys.stderr)
+        return 2
+    return 0
+
+
+def build_queue(dataset_root: Path, limit: int | None = None) -> list[dict]:
+    """Blind review queue: what a reviewer must judge, and nothing about what a model thinks.
+
+    This function deliberately takes no predictions. Blindness is structural here: the queue
+    cannot leak a model answer because it never receives one.
+    """
+    dataset_root = Path(dataset_root)
+    reviews = load_reviews(dataset_root)
+    reviewed = {record.get("contributionId") for record in reviews}
+    queue: list[dict] = []
+    for sample in active_records(load_manifest(_manifest_path(dataset_root))):
+        contribution_id = sample["contributionId"]
+        if contribution_id in reviewed:
+            continue
+        image = dataset_root / sample["relativePath"]
+        if not image.is_file():
+            raise ReviewError(f"the dataset lists an active sample whose image is missing: {sample['relativePath']}")
+        queue.append({
+            "schemaVersion": SCHEMA_VERSION,
+            "contributionId": contribution_id,
+            "imageId": sample["imageId"],
+            "relativePath": sample["relativePath"],
+            "split": sample["split"],
+            "proposed": dict(sample["labels"]),
+            "blindToModel": True,
+        })
+        if limit is not None and len(queue) >= limit:
+            break
+    return queue
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/security_attack_suite.mjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+// RC attack suite (#40): attack the release candidate before users do.
+//
+// Every case drives the shipping `server.mjs` with synthetic hostile bytes while a stub worker counts
+// the calls that reach it. The suite records what it observed and derives a verdict from the
+// observation; it never asserts a result it did not see. No real medical image, no live user data,
+// no third-party provider is involved, and the provider is a counting stub, so "reached the worker"
+// is provable rather than inferred.
+//
+// Usage: node scripts/security_attack_suite.mjs [--json <path>] [--base-url <url>]
+// Exit: 0 = GO, 1 = BLOCKED (a P0 finding, or a required category with no executable evidence).
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import http from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { buildReport, containsImageBytes, latencyPercentiles } from '../src/release-security-gate.js';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+const argument = (name, fallback) => {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? fallback : process.argv[index + 1];
+};
+const reportPath = argument('--json', join(repoRoot, 'artifacts/security/rc-attack-report.json'));
+const explicitBaseUrl = argument('--base-url', '');
+
+function freePort() {
+  return new Promise(resolve => {
+    const probe = http.createServer();
+    probe.listen(0, '127.0.0.1', () => {
+      const { port } = probe.address();
+      probe.close(() => resolve(port));
+    });
+  });
+}
+
+// A counting OpenAI-compatible worker. `state.content` is the answer the next request receives, and
+// `state.requests` is the evidence that a request crossed the provider boundary at all.
+function startStubWorker() {
+  const state = { content: '', requests: 0 };
+  const server = http.createServer((req, res) => {
+    if (req.url.endsWith('/models')) {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      return res.end(JSON.stringify({ data: [{ id: 'stub-vision-worker' }] }));
+    }
+    req.resume();
+    req.on('end', () => {
+      state.requests += 1;
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ choices: [{ message: { content: state.content } }] }));
+    });
+  });
+  return new Promise(resolve => server.listen(0, '127.0.0.1', () => resolve({
+    state,
+    port: server.address().port,
+    close: () => new Promise(done => server.close(done)),
+  })));
+}
+
+// The real server, with its own stdout/stderr captured from the first byte: the log scan is only
+// worth something if it read a log that actually exists.
+async function startTarget({ providerPort, port, env = {} }) {
+  const child = spawn(process.execPath, ['server.mjs'], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      HOST: '127.0.0.1',
+      PORT: String(port),
+      TIMMY_VISION_ENABLED: 'true',
+      TIMMY_VISION_PROFILE: 'selfhost',
+      TIMMY_VISION_BASE_URL: `http://127.0.0.1:${providerPort}/v1`,
+      TIMMY_VISION_MODEL: 'stub-vision-worker',
+      TIMMY_VISION_TIMEOUT_MS: '5000',
+      ...env,
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const log = [];
+  child.stdout.on('data', chunk => log.push(chunk.toString('utf8')));
+  child.stderr.on('data', chunk => log.push(chunk.toString('utf8')));
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (log.join('').includes('Timmy is listening')) return { child, log };
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/healthz`);
+      if (response.ok) return { child, log };
+    } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  child.kill();
+  throw new Error('attack suite target did not become ready');
+}
+
+const stop = child => new Promise(resolve => {
+  if (!child || child.exitCode !== null) return resolve();
+  child.kill();
+  child.once('exit', resolve);
+});
+
+async function main() {
+  const worker = await startStubWorker();
+  const port = explicitBaseUrl ? null : await freePort();
+  const baseUrl = explicitBaseUrl || `http://127.0.0.1:${port}`;
+  const target = explicitBaseUrl ? null : await startTarget({ providerPort: worker.port, port });
+  const photo = await readFile(join(repoRoot, 'tests/fixtures/synthetic-type4.jpg'));
+  const imageDataUrl = `data:image/jpeg;base64,${photo.toString('base64')}`;
+
+  const post = async (body, targetBase = baseUrl) => {
+    const before = worker.state.requests;
+    const response = await fetch(`${targetBase}/api/analyze`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: typeof body === 'string' ? body : JSON.stringify(body),
+    });
+    const text = await response.text();
+    return { status: response.status, text, providerCalls: worker.state.requests - before };
+  };
+
+  const cases = [];
+  const record = (entry) => { cases.push(entry); return entry; };
+
+  try {
+    const health = await fetch(`${baseUrl}/api/healthz`).then(response => response.json());
+    if (!health.visionEnabled) throw new Error('the attack suite needs vision analysis enabled on the target');
+
+    // 1. An oversized body must die at the request cap, before the photo is parsed or forwarded.
+    const oversized = await post({ consent: true, imageDataUrl: `data:image/jpeg;base64,${'A'.repeat(6.6 * 1024 * 1024)}` });
+    record({
+      id: 'ingress-oversized-body',
+      category: 'oversized',
+      severity: 'P0',
+      requirement: 'A body over the request cap is refused before any provider work.',
+      expected: { status: 413, providerCalls: 0 },
+      observed: { status: oversized.status, providerCalls: oversized.providerCalls },
+      snippet: oversized.text.slice(0, 120),
+    });
+
+    // 2. Bytes decide the format, not the data-URL label: HTML dressed as a JPEG is a polyglot.
+    const html = Buffer.from('<html><body><script>alert(document.cookie)</script></body></html>');
+    const polyglot = await post({ consent: true, imageDataUrl: `data:image/jpeg;base64,${html.toString('base64')}` });
+    record({
+      id: 'ingress-polyglot-html',
+      category: 'polyglot',
+      severity: 'P0',
+      requirement: 'A payload whose bytes are HTML under an image/jpeg label is refused before the provider sees it.',
+      expected: { status: 400, providerCalls: 0 },
+      observed: { status: polyglot.status, providerCalls: polyglot.providerCalls },
+      snippet: polyglot.text.slice(0, 120),
+    });
+
+    // 3. Random bytes under a JPEG label are not an image either.
+    const garbage = await post({ consent: true, imageDataUrl: `data:image/jpeg;base64,${randomBytes(64).toString('base64')}` });
+    record({
+      id: 'ingress-garbage-bytes',
+      category: 'truncated',
+      severity: 'P0',
+      requirement: 'Undecodable bytes are refused rather than forwarded and interpreted.',
+      expected: { status: 400, providerCalls: 0 },
+      observed: { status: garbage.status, providerCalls: garbage.providerCalls },
+      snippet: garbage.text.slice(0, 120),
+    });
+
+    // 4. Consent is a precondition, and it is cheap to prove: no consent, no provider call.
+    const noConsent = await post({ consent: false, imageDataUrl });
+    record({
+      id: 'consent-required',
+      category: 'consent',
+      severity: 'P0',
+      requirement: 'Analysis without explicit consent is refused and never leaves the boundary.',
+      expected: { status: 400, providerCalls: 0 },
+      observed: { status: noConsent.status, providerCalls: noConsent.providerCalls },
+      snippet: noConsent.text.slice(0, 120),
+    });
+
+    // 5. A worker answer outside the schema must fail closed, and the provider's words must not
+    //    reach the user or the evidence file.
+    worker.state.content = 'garbage-completion-token: isStool yes maybe, bristolType ten';
+    const malformed = await post({ consent: true, imageDataUrl });
+    record({
+      id: 'model-output-malformed',
+      category: 'malformed',
+      severity: 'P0',
+      requirement: 'A non-conforming provider answer is replaced by neutral copy and never echoed.',
+      expected: { status: 503, providerTextLeaked: false },
+      observed: { status: malformed.status, providerTextLeaked: /garbage-completion-token/.test(malformed.text) },
+      snippet: malformed.text.slice(0, 120),
+    });
+
+    // 6. Replay: this boundary holds no session state, so a replay is a second request. What must
+    //    hold is that it is answered identically and that nothing accumulates server-side.
+    worker.state.content = JSON.stringify({ isStool: true, bristolType: 4, color: 'brown', confidence: 0.82, imageQuality: 'good', observations: 'Smooth, formed appearance.' });
+    const first = await post({ consent: true, imageDataUrl });
+    const second = await post({ consent: true, imageDataUrl });
+    record({
+      id: 'replay-duplicate-request',
+      category: 'replay',
+      severity: 'P2',
+      requirement: 'A byte-identical replay is answered identically and stores nothing on the server.',
+      expected: { status: 200, providerCalls: 1, repeatedAnswerIdentical: true },
+      observed: { status: second.status, providerCalls: second.providerCalls, repeatedAnswerIdentical: first.text === second.text },
+      snippet: second.text.slice(0, 120),
+    });
+
+    // 7. Flood: concurrent requests must meet a bound instead of all reaching the worker at once.
+    const beforeFlood = worker.state.requests;
+    const flood = await Promise.all(Array.from({ length: 12 }, () => post({ consent: true, imageDataUrl })));
+    record({
+      id: 'flood-concurrency',
+      category: 'flood',
+      severity: 'P1',
+      requirement: 'A burst of concurrent analyses meets a bounded queue or a rate refusal.',
+      expected: { refused: true },
+      observed: { refused: flood.some(item => item.status === 429 || item.status === 503), providerCalls: worker.state.requests - beforeFlood },
+      snippet: `statuses ${[...new Set(flood.map(item => item.status))].sort().join(',')}`,
+    });
+
+    // 8. Log inspection: the operator log is committed evidence, so it must not contain the photo.
+    const capturedLog = (target?.log || []).join('');
+    if (!capturedLog.trim()) throw new Error('no server log was captured, so the log scan would prove nothing');
+    record({
+      id: 'log-leak-scan',
+      category: 'log',
+      severity: 'P0',
+      requirement: 'Server logs contain no image bytes, base64, or note text.',
+      expected: { imageBytesInLog: false },
+      observed: { imageBytesInLog: containsImageBytes(capturedLog) },
+      snippet: `${capturedLog.trim().split('\n').length} log line(s) inspected`,
+    });
+
+    // 9. Deletion is governed by the contribution ledger, not by this HTTP boundary. Covering it
+    //    here means naming the executable test that does it, and only counting it once verified.
+    let evidenceVerified = false;
+    try {
+      await access(join(repoRoot, 'tests/training-contribution.test.js'));
+      evidenceVerified = true;
+    } catch {}
+    record({
+      id: 'deletion-withdrawal',
+      category: 'deletion',
+      severity: 'P0',
+      surface: 'out-of-surface',
+      requirement: 'Withdrawal deletes the contribution and the server holds no copy of the photo.',
+      evidence: 'tests/training-contribution.test.js',
+      evidenceVerified,
+      snippet: evidenceVerified ? 'covered by the contribution ledger suite' : 'named evidence file is missing',
+    });
+
+    // Load: sequential valid analyses, abstaining answers, latency measured with the same boundary.
+    // The abuse cases above spend the ingress request budget, so latency is measured against a second
+    // target that starts with the budget wide open; otherwise these samples would be 429 refusals.
+    const loadPort = explicitBaseUrl ? null : await freePort();
+    const loadTarget = explicitBaseUrl
+      ? null
+      : await startTarget({
+        providerPort: worker.port,
+        port: loadPort,
+        env: { TIMMY_ANALYZE_RATE_LIMIT: '100000', TIMMY_ANALYZE_RATE_WINDOW_MS: '60000' },
+      });
+    const loadBase = explicitBaseUrl || `http://127.0.0.1:${loadPort}`;
+    worker.state.content = JSON.stringify({ isStool: false, confidence: 0.9 });
+    const samples = [];
+    let errors = 0;
+    let abstentions = 0;
+    try {
+      for (let index = 0; index < 8; index += 1) {
+        const started = performance.now();
+        const result = await post({ consent: true, imageDataUrl }, loadBase);
+        samples.push(Math.round(performance.now() - started));
+        if (result.status !== 200) errors += 1;
+        else {
+          try {
+            if (JSON.parse(result.text).status === 'needs_user_input') abstentions += 1;
+          } catch {}
+        }
+      }
+    } finally {
+      await stop(loadTarget?.child);
+    }
+    const percentiles = latencyPercentiles(samples);
+    const load = {
+      requests: samples.length,
+      errors,
+      abstentions,
+      p50: percentiles.p50,
+      p95: percentiles.p95,
+      max: percentiles.max,
+      note: 'Latency measured against a counting stub on loopback; it measures this boundary, not a model.',
+    };
+    // Issue #16 adds a per-caller request budget at the ingress, so a suite that spends its budget on
+    // the abuse cases above would measure 429 refusals here and publish them as analysis latency.
+    // A refusal is not a sample: the load phase runs against its own permissive target instead.
+    if (load.errors > 0) {
+      throw new Error(`the load phase measured ${load.errors}/${load.requests} refusals instead of analyses, so it cannot publish latency`);
+    }
+
+    const report = buildReport({
+      generatedAt: new Date().toISOString(),
+      target: {
+        baseUrl,
+        provider: 'stub counting worker (synthetic answers, no model loaded)',
+        visionProfile: 'selfhost',
+        release: health.release,
+        commit: health.commit,
+      },
+      cases,
+      load,
+    });
+    await mkdir(dirname(reportPath), { recursive: true });
+    await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+
+    const width = Math.max(...cases.map(item => item.id.length));
+    for (const item of report.cases) {
+      const detail = item.status === 'fail' ? ` — ${item.mismatch}` : '';
+      console.log(`${item.id.padEnd(width)}  ${item.severity}  ${item.status}${detail}`);
+    }
+    console.log(`load: ${load.requests} requests · p50 ${load.p50}ms · p95 ${load.p95}ms · errors ${load.errors} · abstentions ${load.abstentions}`);
+    console.log(`report: ${reportPath}`);
+    console.log(`VERDICT: ${report.verdict}`);
+    if (report.verdict === 'BLOCKED') {
+      for (const item of [...report.blocking, ...report.unproven]) console.log(`  blocks RC: ${item.id} (${item.severity}) ${item.reason}`);
+    }
+    return report.verdict === 'GO' ? 0 : 1;
+  } finally {
+    await stop(target?.child);
+    await worker.close();
+  }
+}
+
+main().then(code => { process.exitCode = code; }).catch(error => {
+  console.error(`attack suite could not complete: ${error.message}`);
+  process.exitCode = 2;
+});

service-worker.js

@@ -1,7 +1,7 @@
 const ROOT = new URL(self.registration.scope).pathname;
 const appPath = path => `${ROOT}${String(path).replace(/^\/+/, '')}`;
 const CACHE_NAMESPACE = `timmy-shell:${ROOT}:`;
-const CACHE = `${CACHE_NAMESPACE}v5`;
+const CACHE = `${CACHE_NAMESPACE}v6`;
 const ASSETS = [
   '',
   'index.html',

src/abstention-policy.js

@@ -0,0 +1,69 @@
+// The production abstention policy (issue #32).
+//
+// A suggestion is only ever a visual prefill, and this module is the single place that decides when
+// Timmy is allowed to offer one. Two different questions live here, and they are deliberately
+// separate:
+//
+//   1. Per-photo: is this individual answer good enough to show? Confidence, image quality, and
+//      whether the model actually read a form and a colour.
+//   2. Per-release: has a candidate cleared the calibration gates on a held-out split, with its
+//      threshold chosen on validation only? Until it has, no prefill may be shipped at all.
+//
+// The copy is fixed here so the browser, the corpus, and the server cannot drift into three
+// different explanations of the same refusal.
+export const ABSTENTION_COPY = Object.freeze({
+  not_stool: 'The image does not clearly show stool.',
+  low_confidence: 'The image is too uncertain to prefill safely.',
+  unusable_visual_fields: 'The photo does not show a form Timmy can read safely.',
+  low_quality: 'The photo is too blurry or poorly lit to suggest a form safely.',
+});
+
+// Bump `version` whenever a limit below changes: a policy change is a behaviour change, and the
+// release notes have to be able to name which policy a suggestion was produced under.
+export const ABSTENTION_POLICY = Object.freeze({
+  version: 1,
+  minConfidence: 0.55,
+  // "fair" may prefill; "poor" never does. The model already returns its own quality judgement, so
+  // a confident answer about an unreadable photo is exactly the case this gate exists for.
+  acceptedImageQuality: Object.freeze(['good', 'fair']),
+});
+
+export function abstainFor(reason, isStool = true) {
+  if (!Object.prototype.hasOwnProperty.call(ABSTENTION_COPY, reason)) {
+    throw new Error(`unknown abstention reason: ${reason}`);
+  }
+  return {
+    status: 'needs_user_input',
+    isStool,
+    abstainedFor: reason,
+    reason: ABSTENTION_COPY[reason],
+  };
+}
+
+export function isLowQuality(imageQuality, policy = ABSTENTION_POLICY) {
+  return !policy.acceptedImageQuality.includes(String(imageQuality || '').toLowerCase());
+}
+
+// Release-level gate. The calibration harness already refuses to pick a threshold anywhere but the
+// validation split; this decides whether a report authorises prefill at all, and names every reason
+// it does not. A missing or malformed report is a block, never a default-allow.
+export function evaluatePrefillGate(report) {
+  const blockedBy = [];
+  const verdict = report?.verdict || 'UNKNOWN';
+  if (verdict !== 'GO') blockedBy.push('calibration-verdict-not-go');
+  const models = Array.isArray(report?.models) ? report.models : [];
+  const recommended = models.find(row => row?.model === report?.recommended) || null;
+  if (!recommended) {
+    blockedBy.push('no-recommended-calibration');
+  } else {
+    if (recommended.selectionSplit !== 'validation') blockedBy.push('threshold-not-selected-on-validation');
+    if (recommended.evaluatedSplit !== 'test') blockedBy.push('gate-not-scored-on-held-out-test');
+    if (recommended.gate?.passed !== true) blockedBy.push('candidate-failed-release-gates');
+  }
+  return {
+    prefillAllowed: blockedBy.length === 0,
+    verdict,
+    calibrationModel: recommended?.model || null,
+    blockedBy,
+  };
+}

src/analysis.js

@@ -1,3 +1,5 @@
+import { ABSTENTION_POLICY, abstainFor, isLowQuality } from './abstention-policy.js';
+
 const COLORS = new Set(['brown', 'green', 'yellow', 'pale', 'red', 'black']);
 const QUALITIES = new Set(['good', 'fair', 'poor']);
 const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
@@ -26,13 +28,13 @@ function asObject(raw) {
   }
 }
 
-export function parseVisionResponse(raw) {
+export function parseVisionResponse(raw, policy = ABSTENTION_POLICY) {
   const value = asObject(raw);
   if (typeof value.isStool !== 'boolean') throw visionResponseError(VISION_FAILURE_CODES.invalidFields, 'Invalid AI response: isStool is required.');
   const confidence = Number(value.confidence);
   if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw visionResponseError(VISION_FAILURE_CODES.invalidFields, 'Invalid AI response: confidence is required.');
-  if (!value.isStool) return { status: 'needs_user_input', isStool: false, abstainedFor: 'not_stool', reason: 'The image does not clearly show stool.' };
-  if (confidence < 0.55) return { status: 'needs_user_input', isStool: true, abstainedFor: 'low_confidence', reason: 'The image is too uncertain to prefill safely.' };
+  if (!value.isStool) return abstainFor('not_stool', false);
+  if (confidence < policy.minConfidence) return abstainFor('low_confidence');
   // The request schema lets the model return a null form and color when it cannot read them.
   // A blank field means the model could not read it, so a schema-valid answer with nothing usable
   // abstains and nothing is prefilled. A filled-in field is a claim, though: if it sits outside the
@@ -47,15 +49,12 @@ export function parseVisionResponse(raw) {
     throw visionResponseError(VISION_FAILURE_CODES.invalidFields, 'Invalid AI response: visual fields are out of range.');
   }
   if (bristolType === null || color === null) {
-    return {
-      status: 'needs_user_input',
-      isStool: true,
-      abstainedFor: 'unusable_visual_fields',
-      reason: 'The photo does not show a form Timmy can read safely.',
-    };
+    return abstainFor('unusable_visual_fields');
   }
   const imageQuality = String(value.imageQuality || '').toLowerCase();
   if (!QUALITIES.has(imageQuality)) throw visionResponseError(VISION_FAILURE_CODES.invalidFields, 'Invalid AI response: visual fields are out of range.');
+  // A confident reading of a photo the model itself calls poor is still not a safe prefill.
+  if (isLowQuality(imageQuality, policy)) return abstainFor('low_quality');
   return {
     status: 'suggestion',
     isStool: true,

src/domain.js

@@ -111,9 +111,32 @@ export function sanitizeEntry(input = {}) {
     note: String(input.note || '').trim().slice(0, 500),
     photoDataUrl: typeof input.photoDataUrl === 'string' && input.photoDataUrl.startsWith('data:image/') ? input.photoDataUrl : '',
     symptoms,
+    provenance: sanitizeProvenance(input.provenance),
   };
 }
 
+// Provenance is the only record of whether a confirmed log began as an AI suggestion. It is kept to
+// an allowlist so a backup can never smuggle a credential, a prompt, or a raw model reply out of the
+// device, and it is `null` for logs that never had one — a missing record is not a manual entry.
+const PROVENANCE_SOURCES = Object.freeze(['ai-confirmed', 'ai-corrected']);
+
+function sanitizeProvenance(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (!PROVENANCE_SOURCES.includes(value.source)) return null;
+  const provenance = { source: value.source };
+  if (typeof value.model === 'string' && value.model.trim()) provenance.model = value.model.trim().slice(0, 80);
+  const suggestedType = Number(value.suggestedBristolType);
+  if (Number.isInteger(suggestedType) && suggestedType >= 1 && suggestedType <= 7) {
+    provenance.suggestedBristolType = suggestedType;
+  }
+  if (['brown', 'green', 'yellow', 'pale', 'red', 'black'].includes(value.suggestedColor)) {
+    provenance.suggestedColor = value.suggestedColor;
+  }
+  const confirmedAt = value.confirmedAt ? new Date(value.confirmedAt) : null;
+  if (confirmedAt && !Number.isNaN(confirmedAt.valueOf())) provenance.confirmedAt = confirmedAt.toISOString();
+  return provenance;
+}
+
 export function photoQualityMessage({ width = 0, height = 0, brightness = 0.5 } = {}) {
   if (width < 640 || height < 480) return 'Move a little closer or use a higher-resolution photo. The image stays on this device.';
   if (brightness < 0.12) return 'Add more light before saving. Timmy only checks whether the photo is usable.';
@@ -121,19 +144,120 @@ export function photoQualityMessage({ width = 0, height = 0, brightness = 0.5 }
   return 'Ready for your review. Choose the matching Bristol form yourself; Timmy does not interpret the picture.';
 }
 
+export const LEDGER_EXPORT_VERSION = 2;
+
 export function exportLedger(entries, exportedAt = new Date().toISOString()) {
+  return exportLedgerBackup({ entries, exportedAt });
+}
+
+// A backup is written through an allowlist, so only fields this build understands leave the device.
+// Entries are re-sanitized on the way out as well as in: an unknown key on an entry is not part of
+// the person's record, and a crafted key must never be laundered through a backup.
+export function exportLedgerBackup({ entries = [], contributions = [], exportedAt = new Date().toISOString() } = {}) {
+  const list = Array.isArray(entries) ? entries.map(sanitizeEntry) : [];
+  const receipts = (Array.isArray(contributions) ? contributions : []).map(sanitizeContribution).filter(Boolean);
   return JSON.stringify({
     product: 'Timmy the Talking Turd',
-    schemaVersion: 1,
+    schemaVersion: LEDGER_EXPORT_VERSION,
     exportedAt,
-    entries: Array.isArray(entries) ? entries : [],
+    entries: list,
+    contributions: receipts,
   }, null, 2);
 }
 
+const CONTRIBUTION_STATES = Object.freeze(['queued-local', 'withdrawn']);
+const CONTRIBUTION_ARTIFACTS = Object.freeze(['raw-image', 'confirmed-label']);
+
+function isoOrNull(value) {
+  if (!value) return null;
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.valueOf()) ? null : parsed.toISOString();
+}
+
+export function sanitizeContribution(input = {}) {
+  const contributionId = String(input?.contributionId || '').trim().slice(0, 120);
+  if (!contributionId) return null;
+  const state = CONTRIBUTION_STATES.includes(input.state) ? input.state : 'queued-local';
+  const receipt = {
+    contributionId,
+    entryId: String(input.entryId || '').trim().slice(0, 120),
+    consentVersion: String(input.consentVersion || '').trim().slice(0, 60),
+    consentedAt: isoOrNull(input.consentedAt),
+    labels: {
+      bristolType: Math.min(7, Math.max(1, Number(input.labels?.bristolType) || 4)),
+      color: ['brown', 'green', 'yellow', 'pale', 'red', 'black'].includes(input.labels?.color) ? input.labels.color : 'brown',
+    },
+    state,
+  };
+  const withdrawnAt = isoOrNull(input.withdrawnAt);
+  if (state === 'withdrawn' && withdrawnAt) receipt.withdrawnAt = withdrawnAt;
+  if (state === 'withdrawn') {
+    receipt.artifacts = (Array.isArray(input.artifacts) ? input.artifacts : [])
+      .filter(artifact => CONTRIBUTION_ARTIFACTS.includes(artifact?.artifact))
+      .map(artifact => ({
+        artifact: artifact.artifact,
+        contributionId: String(artifact.contributionId || contributionId).slice(0, 120),
+        state: artifact.state === 'withdrawn' ? 'withdrawn' : 'active',
+      }));
+  }
+  return receipt;
+}
+
 export function importLedger(text) {
-  const parsed = JSON.parse(text);
-  if (parsed?.schemaVersion !== 1 || !Array.isArray(parsed.entries)) throw new Error('This is not a supported Timmy export.');
-  return parsed.entries.map(sanitizeEntry);
+  return importLedgerBackup(text).entries;
+}
+
+// A backup can be older than this build. Version 1 files record no provenance for their entries, so
+// the migration leaves that field empty instead of guessing a source, and the caller is told which
+// version the file came from.
+export const LEDGER_IMPORT_LIMITS = Object.freeze({ maxTextLength: 16 * 1024 * 1024, maxEntries: 5000 });
+
+export function importLedgerBackup(text) {
+  const raw = String(text ?? '');
+  if (raw.length > LEDGER_IMPORT_LIMITS.maxTextLength) {
+    throw new Error('That backup is too large for Timmy to read safely. Nothing was imported.');
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('That file is not readable JSON, so nothing was imported.');
+  }
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.entries)) {
+    throw new Error('This is not a supported Timmy backup.');
+  }
+  const fromVersion = Number(parsed.schemaVersion);
+  if (Number.isInteger(fromVersion) && fromVersion > LEDGER_EXPORT_VERSION) {
+    throw new Error(`This backup was written by a newer version of Timmy (version ${fromVersion}). Update Timmy before importing it; nothing was imported.`);
+  }
+  if (!Number.isInteger(fromVersion) || fromVersion < 1) {
+    throw new Error('This is not a supported Timmy backup.');
+  }
+  if (parsed.entries.length > LEDGER_IMPORT_LIMITS.maxEntries) {
+    throw new Error('That backup holds more logs than Timmy will import at once. Nothing was imported.');
+  }
+  const entries = parsed.entries.map(sanitizeEntry);
+  const rawContributions = Array.isArray(parsed.contributions) ? parsed.contributions : [];
+  const contributions = rawContributions.map(sanitizeContribution).filter(Boolean);
+  const migrated = fromVersion < LEDGER_EXPORT_VERSION;
+  // The caller already says what it restored, so this notice only reports the upgrade. Restating the
+  // restored count here made the on-screen notice read as two stacked sentences saying one thing.
+  const notices = migrated
+    ? [`Upgraded from version ${fromVersion} to version ${LEDGER_EXPORT_VERSION}; fields the old file did not record are left empty.`]
+    : [];
+  // Skipping an unreadable receipt silently would tell someone their opt-in vanished. Say it.
+  const skipped = rawContributions.length - contributions.length;
+  if (skipped > 0) {
+    notices.push(`${skipped} training contribution ${skipped === 1 ? 'receipt' : 'receipts'} could not be read and ${skipped === 1 ? 'was' : 'were'} skipped.`);
+  }
+  return {
+    entries,
+    contributions,
+    fromVersion,
+    migrated,
+    notices,
+    exportedAt: typeof parsed.exportedAt === 'string' ? parsed.exportedAt : null,
+  };
 }
 
 export const urgentSymptomKeys = Object.freeze([...URGENT_KEYS]);

src/http-body.js

@@ -23,6 +23,7 @@ export class BodyError extends Error {
 export function readJsonBody(req, { maxBytes = 6 * 1024 * 1024, timeoutMs = 15_000 } = {}) {
   return new Promise((resolve, reject) => {
     let settled = false;
+    let tooLarge = false;
     let size = 0;
     const chunks = [];
     const finish = callback => {
@@ -45,18 +46,21 @@ export function readJsonBody(req, { maxBytes = 6 * 1024 * 1024, timeoutMs = 15_0
 
     function onData(chunk) {
       if (settled) return;
+      // Past the ceiling the body is already refused: keep draining it without buffering so the
+      // caller can still read the 413. Destroying the socket here would surface as "fetch failed"
+      // and leave the caller with no status to act on.
+      if (tooLarge) return;
       size += chunk.length;
       if (size > maxBytes) {
-        finish(() => {
-          req.destroy?.();
-          reject(new BodyError('too_large'));
-        });
+        tooLarge = true;
+        chunks.length = 0;
         return;
       }
       chunks.push(chunk);
     }
     function onEnd() {
       finish(() => {
+        if (tooLarge) return reject(new BodyError('too_large'));
         try {
           resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
         } catch {

src/release-security-gate.js

@@ -0,0 +1,95 @@
+// Release security gate: the arithmetic and the verdict rule for the RC attack suite (#40).
+//
+// The suite observes the real server; this module only turns observations into a verdict. Keeping
+// the rule here (not in the runner) is what makes "a P0 finding blocks RC approval" testable.
+
+/** Nearest-rank percentile: the returned value is always a sample that was actually measured. */
+export function latencyPercentiles(samples) {
+  const sorted = [...samples].sort((a, b) => a - b);
+  if (!sorted.length) return { count: 0, p50: null, p95: null, max: null };
+  const rank = (p) => sorted[Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1)];
+  return { count: sorted.length, p50: rank(50), p95: rank(95), max: sorted[sorted.length - 1] };
+}
+
+/** One case against one expectation. A partial match is a failure, and it says which field broke. */
+export function evaluateCase(record) {
+  const mismatches = Object.keys(record.expected)
+    .filter(field => record.observed?.[field] !== record.expected[field])
+    .map(field => `${field} ${record.expected[field]} expected, observed ${record.observed?.[field]}`);
+  return { ...record, status: mismatches.length ? 'fail' : 'pass', mismatch: mismatches.join('; ') };
+}
+
+const SEVERITY_BLOCKS = (severity) => severity === 'P0';
+
+/** The RC rule: every P0 failure blocks approval, unproven categories block it too, P1/P2 only hold. */
+export function releaseVerdict({ cases, load = null }) {
+  const evaluated = cases.map(record => (record.surface === 'out-of-surface'
+    ? { ...record, status: record.evidenceVerified ? 'covered-elsewhere' : 'unproven' }
+    : evaluateCase(record)));
+  const blocking = evaluated.filter(item => item.status === 'fail' && SEVERITY_BLOCKS(item.severity))
+    .map(item => ({ id: item.id, severity: item.severity, reason: item.mismatch }));
+  const holds = evaluated.filter(item => item.status === 'fail' && !SEVERITY_BLOCKS(item.severity))
+    .map(item => ({ id: item.id, severity: item.severity, reason: item.mismatch }));
+  const unproven = evaluated.filter(item => item.status === 'unproven')
+    .map(item => ({ id: item.id, severity: item.severity, reason: 'no executable evidence' }));
+  return {
+    verdict: blocking.length || unproven.length ? 'BLOCKED' : 'GO',
+    blocking,
+    holds,
+    unproven,
+    coveredElsewhere: evaluated.filter(item => item.status === 'covered-elsewhere').map(item => item.id),
+    proven: evaluated.filter(item => item.status === 'pass').length,
+    cases: evaluated,
+    load,
+  };
+}
+
+// Evidence hygiene: the report and the captured server log are committed and quoted. A photo that
+// survived into either one is a leak of the exact data this suite exists to protect.
+const IMAGE_DATA_URI = /data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/gi;
+const LONG_BASE64 = /[A-Za-z0-9+/]{200,}={0,2}/;
+
+export function containsImageBytes(text) {
+  const value = String(text ?? '');
+  return new RegExp(IMAGE_DATA_URI.source, 'i').test(value) || LONG_BASE64.test(value);
+}
+
+export function redactImageBytes(text) {
+  return String(text ?? '')
+    .replace(IMAGE_DATA_URI, '[redacted image bytes]')
+    .replace(new RegExp(LONG_BASE64.source, 'g'), '[redacted image bytes]');
+}
+
+/** Fails closed rather than emitting evidence that carries a photo. */
+export function assertNoImageBytes(label, text) {
+  if (containsImageBytes(text)) throw new Error(`${label} contains image bytes; refusing to write release evidence.`);
+  return true;
+}
+
+/**
+ * The receipt the release job quotes. It is redacted after assembly, so a case that captured a
+ * response body still cannot carry a photo in it.
+ */
+export function buildReport({ generatedAt, target, cases, load, suite = 'scripts/security_attack_suite.mjs' }) {
+  const verdict = releaseVerdict({ cases, load });
+  const report = {
+    schema: 'timmy-rc-security-attack/1',
+    issue: 40,
+    generatedAt,
+    suite,
+    target,
+    verdict: verdict.verdict,
+    blocking: verdict.blocking,
+    holds: verdict.holds,
+    unproven: verdict.unproven,
+    coveredElsewhere: verdict.coveredElsewhere,
+    proven: verdict.proven,
+    cases: verdict.cases.map(({ id, category, severity, requirement, expected, observed, status, mismatch, snippet, surface, evidence, evidenceVerified }) =>
+      ({ id, category, severity, requirement, expected, observed, status, mismatch, surface, evidence, evidenceVerified, snippet: snippet ? redactImageBytes(snippet) : undefined })),
+    load,
+    disclaimer: 'Synthetic hostile bytes only. Every case drives the real server against a stub worker; no real medical image and no live user data is involved.',
+  };
+  const clean = JSON.parse(redactImageBytes(JSON.stringify(report)));
+  assertNoImageBytes('security report', JSON.stringify(clean));
+  return clean;
+}

src/training-contribution.js

@@ -0,0 +1,103 @@
+// Issue #24 — contributing a confirmed photo to Timmy's training corpus is a separate decision from
+// saving a log. A journal save records nothing here; a contribution exists only after someone reads
+// the consent terms and accepts them, and it exists as a receipt they can point a withdrawal at.
+// Nothing is transmitted: this build queues the receipt on the device so the corpus pipeline (#25)
+// has something auditable to consume later.
+export const TRAINING_CONSENT_VERSION = 'training-consent-v1';
+
+const IMAGE_DATA_URL = /^data:image\/[a-z0-9.+-]+(?:;base64)?,[A-Za-z0-9+/=%.-]+$/i;
+const CONTRIBUTED_ARTIFACTS = ['raw-image', 'confirmed-label'];
+
+export function consentTerms() {
+  return {
+    version: TRAINING_CONSENT_VERSION,
+    includes: [
+      'The saved photo bytes for this one log',
+      'The confirmed Bristol form, broad color, and image quality',
+    ],
+    excludes: [
+      'Your note text',
+      'Your symptom answers',
+      'Urgency and discomfort ratings',
+      'Anything identifying you or this device',
+    ],
+    transport: 'Queued on this device only — nothing is uploaded in this build.',
+  };
+}
+
+export function defaultContributionState() {
+  return { optedIn: false, receipt: null };
+}
+
+export function contributionEligibility(entry) {
+  if (!entry || !entry.id) return { eligible: false, reason: 'This log has no identifier to attach a receipt to.' };
+  if (!IMAGE_DATA_URL.test(String(entry.photoDataUrl || ''))) {
+    return { eligible: false, reason: 'This log has no saved photo to contribute.' };
+  }
+  if (!Number.isInteger(entry.bristolType) || entry.bristolType < 1 || entry.bristolType > 7) {
+    return { eligible: false, reason: 'This log has no confirmed Bristol form to contribute.' };
+  }
+  if (!entry.color) return { eligible: false, reason: 'This log has no confirmed color to contribute.' };
+  return { eligible: true, reason: '' };
+}
+
+export function receiptPreview(entry, { contributionId, consentedAt } = {}) {
+  if (!contributionId) throw new Error('A contribution receipt needs its own identifier.');
+  if (!consentedAt) throw new Error('A contribution receipt needs the moment of consent.');
+  const eligibility = contributionEligibility(entry);
+  if (!eligibility.eligible) throw new Error(eligibility.reason);
+  return {
+    contributionId,
+    entryId: entry.id,
+    consentVersion: TRAINING_CONSENT_VERSION,
+    consentedAt,
+    labels: { bristolType: entry.bristolType, color: entry.color },
+    state: 'queued-local',
+  };
+}
+
+export function contributionForEntry(contributions, entryId) {
+  if (!Array.isArray(contributions)) return null;
+  return contributions.find(item => item.entryId === entryId && item.state !== 'withdrawn') || null;
+}
+
+export function addContribution(contributions, receipt) {
+  const list = Array.isArray(contributions) ? contributions : [];
+  if (!receipt || receipt.consentVersion !== TRAINING_CONSENT_VERSION) {
+    throw new Error('A contribution needs the current consent version.');
+  }
+  if (contributionForEntry(list, receipt.entryId)) return list;
+  return [...list, receipt];
+}
+
+export function derivedArtifacts(receipt) {
+  const state = receipt?.state === 'withdrawn' ? 'withdrawn' : 'active';
+  return CONTRIBUTED_ARTIFACTS.map(artifact => ({
+    artifact,
+    contributionId: receipt?.contributionId || '',
+    state,
+  }));
+}
+
+export function withdrawContribution(contributions, contributionId, withdrawnAt) {
+  const list = Array.isArray(contributions) ? contributions : [];
+  const receipt = list.find(item => item.contributionId === contributionId);
+  if (!receipt) return { contributions: list, tombstone: null };
+  const withdrawn = {
+    ...receipt,
+    state: 'withdrawn',
+    withdrawnAt,
+    artifacts: derivedArtifacts({ ...receipt, state: 'withdrawn' }),
+  };
+  return {
+    contributions: list.map(item => (item.contributionId === contributionId ? withdrawn : item)),
+    tombstone: {
+      contributionId: receipt.contributionId,
+      entryId: receipt.entryId,
+      consentVersion: receipt.consentVersion,
+      consentedAt: receipt.consentedAt,
+      withdrawnAt,
+      artifacts: withdrawn.artifacts,
+    },
+  };
+}

styles.css

@@ -59,3 +59,19 @@ main{display:block}.eyebrow{font-size:11px;font-weight:800;letter-spacing:.1em;t
 .chat-citation{min-height:32px;padding:5px 10px;border:1px solid #bcdfd4;border-radius:999px;background:var(--surface);color:var(--teal);font-weight:800;font-size:11px;cursor:pointer}
 .chat-citation:active{background:#e9f5f0}
 .chat-unverified{margin:9px 0 0;padding-top:8px;border-top:1px solid rgba(55,40,31,.09);font-size:11px;line-height:1.4;font-weight:700;color:#8a5a12}
+
+/* Issue #24 — an opt-in receipt and its tombstone must read as separate facts, not one run-on line. */
+.contribution-list{display:flex;flex-direction:column;margin-top:10px}
+.training-consent h3{font-size:13px;margin:16px 0 2px}
+.contribution-row{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:11px 0;border-top:1px solid var(--line)}
+.contribution-row:first-child{border-top:0}
+.contribution-row>div{display:flex;flex-direction:column;gap:3px;min-width:0}
+.contribution-row strong{font-size:13px;line-height:1.3}
+.contribution-row span{font-size:11px;line-height:1.4;color:var(--muted);overflow-wrap:anywhere}
+.contribution-row .btn{min-height:40px;padding:0 14px;font-size:12px;flex:0 0 auto}
+.contribution-row.withdrawn strong{color:var(--muted)}
+
+/* Issue #35 — a backup says which version it came from, and a refused file says so in place. */
+.portability-notice{margin:0 0 12px;padding:12px 14px;border-radius:15px;font-size:12.5px;line-height:1.45;font-weight:700;background:var(--teal-soft);color:#155c4f;border:1px solid #bcdfd4}
+.portability-notice.error{background:var(--red-soft);border-color:#eec1ba;color:#75261f}
+.entry-provenance{margin:10px 0 0;padding-top:9px;border-top:1px solid rgba(55,40,31,.09)}

tests/abstention-policy.test.js

@@ -0,0 +1,117 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { ABSTENTION_COPY, ABSTENTION_POLICY, abstainFor, evaluatePrefillGate } from '../src/abstention-policy.js';
+
+test('every abstention reason has one fixed piece of copy the user sees', () => {
+  assert.equal(abstainFor('not_stool').reason, 'The image does not clearly show stool.');
+  assert.equal(abstainFor('low_confidence').reason, 'The image is too uncertain to prefill safely.');
+  assert.equal(abstainFor('unusable_visual_fields').reason, 'The photo does not show a form Timmy can read safely.');
+  assert.equal(abstainFor('low_quality').reason, 'The photo is too blurry or poorly lit to suggest a form safely.');
+  assert.deepEqual(abstainFor('low_quality'), {
+    status: 'needs_user_input',
+    isStool: true,
+    abstainedFor: 'low_quality',
+    reason: ABSTENTION_COPY.low_quality,
+  });
+  assert.equal(abstainFor('not_stool', false).isStool, false);
+  assert.throws(() => abstainFor('looked_wrong'), /unknown abstention reason/);
+});
+
+test('the policy states the confidence floor and the quality levels that may prefill', () => {
+  assert.ok(Number.isInteger(ABSTENTION_POLICY.version));
+  assert.equal(ABSTENTION_POLICY.minConfidence, 0.55);
+  assert.deepEqual([...ABSTENTION_POLICY.acceptedImageQuality], ['good', 'fair']);
+  assert.equal(ABSTENTION_POLICY.acceptedImageQuality.includes('poor'), false);
+  assert.equal(Object.isFrozen(ABSTENTION_POLICY), true, 'the shipped policy must not be mutated at runtime');
+});
+
+test('prefill is authorised only by a GO report whose threshold was selected on validation', () => {
+  const passing = {
+    verdict: 'GO',
+    recommended: 'specialist-candidate',
+    models: [{
+      model: 'specialist-candidate',
+      selectionSplit: 'validation',
+      evaluatedSplit: 'test',
+      gate: { passed: true, failed: [] },
+    }],
+  };
+  assert.deepEqual(evaluatePrefillGate(passing), {
+    prefillAllowed: true,
+    verdict: 'GO',
+    calibrationModel: 'specialist-candidate',
+    blockedBy: [],
+  });
+
+  const blocked = evaluatePrefillGate({
+    verdict: 'BLOCKED',
+    recommended: null,
+    models: [{ model: 'specialist-candidate', selectionSplit: 'validation', evaluatedSplit: 'test', gate: { passed: false, failed: ['precisionAtCoverage'] } }],
+  });
+  assert.equal(blocked.prefillAllowed, false);
+  assert.deepEqual(blocked.blockedBy, ['calibration-verdict-not-go', 'no-recommended-calibration']);
+
+  const selectedOnTest = evaluatePrefillGate({
+    verdict: 'GO',
+    recommended: 'opportunist',
+    models: [{ model: 'opportunist', selectionSplit: 'test', evaluatedSplit: 'test', gate: { passed: true, failed: [] } }],
+  });
+  assert.equal(selectedOnTest.prefillAllowed, false, 'a threshold chosen on the split it is scored on is not evidence');
+  assert.deepEqual(selectedOnTest.blockedBy, ['threshold-not-selected-on-validation']);
+
+  const noReport = evaluatePrefillGate(undefined);
+  assert.equal(noReport.prefillAllowed, false);
+  assert.match(noReport.blockedBy.join(','), /calibration-verdict-not-go/);
+});
+
+const execFileAsync = promisify(execFile);
+const receiptScript = fileURLToPath(new URL('../scripts/abstention_policy_receipt.mjs', import.meta.url));
+
+async function runReceipt(report) {
+  const directory = await mkdtemp(join(tmpdir(), 'timmy-policy-'));
+  const reportPath = join(directory, 'calibration-report.json');
+  await writeFile(reportPath, JSON.stringify(report));
+  try {
+    const { stdout } = await execFileAsync(process.execPath, [receiptScript, '--report', reportPath]);
+    return { code: 0, stdout };
+  } catch (error) {
+    return { code: error.code, stdout: error.stdout || '', stderr: error.stderr || '' };
+  }
+}
+
+test('the receipt refuses to authorise prefill without a passing held-out calibration', async () => {
+  const blocked = await runReceipt({
+    verdict: 'BLOCKED',
+    recommended: null,
+    models: [{ model: 'specialist-candidate', selectionSplit: 'validation', evaluatedSplit: 'test', gate: { passed: false, failed: ['precisionAtCoverage'] } }],
+  });
+  assert.equal(blocked.code, 3, 'a blocked calibration must exit non-zero instead of shipping prefill');
+  assert.match(blocked.stdout, /prefill: BLOCKED/);
+  assert.match(blocked.stdout, /calibration-verdict-not-go/);
+  assert.match(blocked.stdout, /policy: version 1 · confidence ≥ 0\.55 · quality good\|fair/);
+
+  const passing = await runReceipt({
+    verdict: 'GO',
+    recommended: 'specialist-candidate',
+    models: [{ model: 'specialist-candidate', selectionSplit: 'validation', evaluatedSplit: 'test', gate: { passed: true, failed: [] } }],
+  });
+  assert.equal(passing.code, 0);
+  assert.match(passing.stdout, /prefill: AUTHORISED for specialist-candidate/);
+});
+
+test('the receipt treats a missing report as a block and never as a default allow', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'timmy-policy-'));
+  try {
+    await execFileAsync(process.execPath, [receiptScript, '--report', join(directory, 'absent.json')]);
+    assert.fail('a missing calibration report must not exit 0');
+  } catch (error) {
+    assert.equal(error.code, 2);
+    assert.match(String(error.stderr), /could not read|absent/i);
+  }
+});

tests/analysis.test.js

@@ -1,5 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { ABSTENTION_COPY, ABSTENTION_POLICY } from '../src/abstention-policy.js';
 
 import {
   buildVisionRequest,
@@ -131,3 +132,39 @@ test('abstains instead of failing when a schema-valid response carries no readab
     reason: 'The photo does not show a form Timmy can read safely.',
   });
 });
+
+test('a confident answer about a low-quality photo still abstains', () => {
+  // Issue #32: confidence is not the only gate. A blurry or badly lit photo can produce a
+  // confident-looking form and colour, and prefilling it would show the user a claim the photo
+  // cannot support. Quality is part of the policy, so this abstains instead of prefilling.
+  assert.deepEqual(parseVisionResponse({
+    isStool: true,
+    bristolType: 4,
+    color: 'brown',
+    confidence: 0.94,
+    imageQuality: 'poor',
+    observations: 'Form barely visible through motion blur.',
+  }), {
+    status: 'needs_user_input',
+    isStool: true,
+    abstainedFor: 'low_quality',
+    reason: 'The photo is too blurry or poorly lit to suggest a form safely.',
+  });
+});
+
+test('the parse path reads the shipped policy instead of hardcoding its own limits', () => {
+  // Issue #32: policy numbers and copy live in one module. A caller may tighten the policy for a
+  // release without editing the parser, and a photo that the default policy would accept has to
+  // abstain under the stricter one — otherwise the parser is carrying its own hidden policy.
+  const fields = { isStool: true, bristolType: 4, color: 'brown', confidence: 0.8, imageQuality: 'fair', observations: 'Form visible but soft.' };
+  assert.equal(parseVisionResponse(fields).status, 'suggestion', 'fair quality may prefill under the shipped policy');
+  const strict = { ...ABSTENTION_POLICY, minConfidence: 0.9, acceptedImageQuality: ['good'] };
+  assert.equal(parseVisionResponse(fields, strict).abstainedFor, 'low_confidence');
+  assert.equal(parseVisionResponse({ ...fields, confidence: 0.95 }, strict).abstainedFor, 'low_quality');
+  assert.equal(parseVisionResponse({ ...fields, confidence: 0.95, imageQuality: 'good' }, strict).status, 'suggestion');
+  assert.equal(
+    parseVisionResponse({ ...fields, imageQuality: 'poor' }).reason,
+    ABSTENTION_COPY.low_quality,
+    'the refusal copy must come from the policy module, not a second copy in the parser',
+  );
+});

tests/analyze-ingress.acceptance.test.js

@@ -177,6 +177,33 @@ test('the shipping server still analyses a clean re-encoded image', async () =>
   });
 });
 
+test('the shipping server refuses an oversized body with a refusal the caller can read', async () => {
+  // Issue #16 sets a byte ceiling, and issue #40 asks the release candidate to prove that ceiling
+  // behaves like a refusal rather than a dropped connection. Destroying the socket while the caller
+  // is still uploading leaves the caller with "fetch failed" and no status to act on, so the refusal
+  // has to be written and read before the connection goes away.
+  await withServer({}, async ({ base, provider }) => {
+    const oversized = JSON.stringify({
+      consent: true,
+      imageDataUrl: `data:image/jpeg;base64,${'A'.repeat(6.6 * 1024 * 1024)}`,
+    });
+    let response;
+    try {
+      response = await fetch(`${base}/api/analyze`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: oversized,
+      });
+    } catch (error) {
+      assert.fail(`an oversized body must be refused with a readable status, not a dropped connection: ${error.message}`);
+    }
+    const body = await response.json();
+    assert.equal(response.status, 413);
+    assert.match(body.error, /too large/i);
+    assert.equal(provider.state.calls, 0, 'an oversized body must never reach the provider');
+  });
+});
+
 test('the shipping server refuses a flood with 429 and stops calling the provider', async () => {
   await withServer({ TIMMY_ANALYZE_RATE_LIMIT: '2', TIMMY_ANALYZE_RATE_WINDOW_MS: '60000' }, async ({ base, provider }) => {
     const payload = { consent: true, imageDataUrl: dataUrl('image/jpeg', cleanJpeg()) };

tests/backup-restore.test.py

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+"""Tests for the operator backup and restore tool.
+
+Issue #39 asks for a production topology and a backup that a person can trust with the records
+Timmy is not allowed to lose. The corpus manifest is append-only and the tombstones in it are the
+only proof that a withdrawal happened, so a backup that quietly drops them, or a restore that
+rebuilds a training set from withdrawn contributions, is worse than no backup at all.
+
+The rules this suite locks in:
+
+- model weights and transient inference images are never archived, and every excluded path is
+  named in the manifest with the reason it was left out;
+- every archived byte carries a SHA-256 that ``verify`` recomputes before a restore writes
+  anything, so a tampered archive fails closed;
+- hostile members (absolute paths, traversal, links, unlisted extras) are refused instead of
+  extracted;
+- a restore round-trips the append-only manifest byte-for-byte and reports the same record counts,
+  including the tombstones.
+
+Every fixture is synthetic: the "images" are opaque bytes, no real medical image is read or written.
+"""
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+BACKUP = ROOT / "scripts" / "operator_backup.py"
+
+IMAGE_BYTES = b"\xff\xd8\xff\xe0synthetic-jpeg-payload-not-a-real-photo"
+WEIGHT_BYTES = b"GGUF-synthetic-weight-shard-not-a-real-model"
+TRANSIENT_BYTES = b"transient-inference-upload-must-not-be-archived"
+SECRET_BYTES = b"TIMMY_DATASET_SALT=demo\nTIMMY_VISION_TOKEN=do-not-archive-me\n"
+
+
+def digest(payload: bytes) -> str:
+    return hashlib.sha256(payload).hexdigest()
+
+
+def run(args: list[str], env: dict[str, str] | None = None) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, str(BACKUP), *args],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        env={**os.environ, **(env or {})},
+    )
+
+
+def records(*lines: dict) -> str:
+    return "".join(json.dumps(line) + "\n" for line in lines)
+
+
+def sample(contribution_id: str, *, relative_path: str = "images/sample-1.jpg") -> dict:
+    return {
+        "recordType": "sample",
+        "schemaVersion": 2,
+        "contributionId": contribution_id,
+        "relativePath": relative_path,
+        "imageId": digest(IMAGE_BYTES),
+        "lifecycle": {"state": "active", "updatedAt": "2026-08-01T10:00:00+00:00"},
+    }
+
+
+def tombstone(contribution_id: str) -> dict:
+    return {
+        "recordType": "tombstone",
+        "schemaVersion": 2,
+        "contributionId": contribution_id,
+        "lifecycle": {"state": "revoked", "updatedAt": "2026-08-02T10:00:00+00:00"},
+        "reason": "participant withdrew consent",
+        "deletedArtifacts": [{"contributionId": contribution_id, "sha256": digest(IMAGE_BYTES)}],
+    }
+
+
+def build_source(root: Path, *, with_tombstone: bool = False) -> Path:
+    """A synthetic server-side data root: the records that must survive, plus what must not."""
+    source = root / "srv-timmy"
+    (source / "images").mkdir(parents=True)
+    (source / "images" / "sample-1.jpg").write_bytes(IMAGE_BYTES)
+    (source / "manifest.jsonl").write_text(
+        records(sample("contribution-1"), *([tombstone("contribution-2")] if with_tombstone else [])),
+        encoding="utf-8",
+    )
+    # Must never be archived: weights, transient inference bytes, operator secrets, and logs.
+    (source / "weights").mkdir()
+    (source / "weights" / "model.gguf").write_bytes(WEIGHT_BYTES)
+    (source / "transient").mkdir()
+    (source / "transient" / "inference-upload-1.jpg").write_bytes(TRANSIENT_BYTES)
+    (source / "secrets.env").write_bytes(SECRET_BYTES)
+    (source / "operator.log").write_text("GET /api/vision 200\n", encoding="utf-8")
+    return source
+
+
+def members(archive: Path) -> dict[str, bytes]:
+    with tarfile.open(archive, "r:gz") as tar:
+        out = {}
+        for info in tar.getmembers():
+            if not info.isfile():
+                continue
+            handle = tar.extractfile(info)
+            assert handle is not None
+            out[info.name] = handle.read()
+        return out
+
+
+def craft_archive(path: Path, entries: list[tuple[str, bytes]], *, link: str | None = None) -> None:
+    """Build an archive by hand so the hostile cases are hostile on purpose."""
+    with tarfile.open(path, "w:gz") as tar:
+        for name, payload in entries:
+            info = tarfile.TarInfo(name)
+            info.size = len(payload)
+            info.mode = 0o644
+            tar.addfile(info, io.BytesIO(payload))
+        if link:
+            info = tarfile.TarInfo(link)
+            info.type = tarfile.SYMTYPE
+            info.linkname = "/etc/passwd"
+            info.mode = 0o777
+            tar.addfile(info)
+
+
+class BackupContractTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp(prefix="timmy-backup-test-"))
+        self.addCleanup(shutil.rmtree, self.tmp, True)
+        self.archive = self.tmp / "backup.tar.gz"
+        self.manifest = self.tmp / "backup.manifest.json"
+
+    def backup(self, source: Path, *extra: str) -> subprocess.CompletedProcess:
+        return run([
+            "backup", "--source", str(source), "--archive", str(self.archive),
+            "--manifest", str(self.manifest), "--label", "nightly", *extra,
+        ])
+
+    def test_backup_archives_records_and_excludes_weights_transient_images_secrets_and_logs(self) -> None:
+        source = build_source(self.tmp, with_tombstone=True)
+        result = self.backup(source)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        archived = members(self.archive)
+        self.assertEqual(sorted(archived), ["payload/images/sample-1.jpg", "payload/manifest.jsonl"])
+        self.assertEqual(archived["payload/images/sample-1.jpg"], IMAGE_BYTES)
+        self.assertNotIn(WEIGHT_BYTES, b"".join(archived.values()))
+        self.assertNotIn(TRANSIENT_BYTES, b"".join(archived.values()))
+        self.assertNotIn(SECRET_BYTES, b"".join(archived.values()))
+
+        manifest = json.loads(self.manifest.read_text(encoding="utf-8"))
+        excluded = {entry["path"]: entry["reason"] for entry in manifest["excluded"]}
+        self.assertEqual(excluded["weights/model.gguf"], "model-weights")
+        self.assertEqual(excluded["transient/inference-upload-1.jpg"], "transient-inference")
+        self.assertEqual(excluded["secrets.env"], "secret")
+        self.assertEqual(excluded["operator.log"], "log")
+        # Every archived member is listed with the digest of the bytes that were stored.
+        listed = {entry["path"]: entry["sha256"] for entry in manifest["files"]}
+        self.assertEqual(listed, {
+            "images/sample-1.jpg": digest(IMAGE_BYTES),
+            "manifest.jsonl": digest((source / "manifest.jsonl").read_bytes()),
+        })
+
+    def test_backup_reports_record_counts_including_tombstones(self) -> None:
+        source = build_source(self.tmp, with_tombstone=True)
+        result = self.backup(source)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        receipt = json.loads(result.stdout)
+        self.assertEqual(receipt["records"], {"samples": 1, "tombstones": 1, "activeSamples": 1})
+        manifest = json.loads(self.manifest.read_text(encoding="utf-8"))
+        self.assertEqual(manifest["records"], {"samples": 1, "tombstones": 1, "activeSamples": 1})
+        self.assertEqual(manifest["label"], "nightly")
+
+    def test_backup_refuses_to_follow_a_symlink_out_of_the_data_root(self) -> None:
+        source = build_source(self.tmp)
+        (source / "images" / "escape.jpg").symlink_to("/etc/hostname")
+        result = self.backup(source)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertNotIn("payload/images/escape.jpg", members(self.archive))
+        manifest = json.loads(self.manifest.read_text(encoding="utf-8"))
+        excluded = {entry["path"]: entry["reason"] for entry in manifest["excluded"]}
+        self.assertEqual(excluded["images/escape.jpg"], "symlink")
+
+    def test_backup_refuses_missing_source_and_existing_archive(self) -> None:
+        missing = run(["backup", "--source", str(self.tmp / "nope"), "--archive", str(self.archive)])
+        self.assertNotEqual(missing.returncode, 0)
+        self.assertIn("is not a directory", missing.stderr)
+
+        source = build_source(self.tmp)
+        self.assertEqual(self.backup(source).returncode, 0)
+        again = self.backup(source)
+        self.assertNotEqual(again.returncode, 0)
+        self.assertIn("already exists", again.stderr)
+
+    def test_verify_and_restore_round_trip_the_records(self) -> None:
+        source = build_source(self.tmp, with_tombstone=True)
+        self.assertEqual(self.backup(source).returncode, 0)
+        verified = run(["verify", "--archive", str(self.archive), "--manifest", str(self.manifest)])
+        self.assertEqual(verified.returncode, 0, verified.stderr)
+
+        target = self.tmp / "restored"
+        restored = run([
+            "restore", "--archive", str(self.archive), "--manifest", str(self.manifest),
+            "--target", str(target),
+        ])
+        self.assertEqual(restored.returncode, 0, restored.stderr)
+        receipt = json.loads(restored.stdout)
+        self.assertEqual(receipt["records"], {"samples": 1, "tombstones": 1, "activeSamples": 1})
+        self.assertEqual((target / "manifest.jsonl").read_bytes(), (source / "manifest.jsonl").read_bytes())
+        self.assertEqual((target / "images" / "sample-1.jpg").read_bytes(), IMAGE_BYTES)
+        # The manifest is append-only history: the tombstone line survives the round trip verbatim.
+        lines = [json.loads(line) for line in (target / "manifest.jsonl").read_text().splitlines() if line.strip()]
+        self.assertEqual([line["recordType"] for line in lines], ["sample", "tombstone"])
+
+    def test_verify_refuses_tampered_member_before_a_restore_writes_anything(self) -> None:
+        source = build_source(self.tmp)
+        self.assertEqual(self.backup(source).returncode, 0)
+        manifest = json.loads(self.manifest.read_text(encoding="utf-8"))
+        tampered = b"\xff\xd8\xff\xe0synthetic-jpeg-payload-not-a-real-photO"
+        craft_archive(self.archive, [
+            ("payload/images/sample-1.jpg", tampered),
+            ("payload/manifest.jsonl", (source / "manifest.jsonl").read_bytes()),
+        ])
+        verified = run(["verify", "--archive", str(self.archive), "--manifest", str(self.manifest)])
+        self.assertNotEqual(verified.returncode, 0)
+        self.assertIn("does not match", verified.stderr)
+        self.assertEqual(manifest["files"][0]["sha256"], digest(IMAGE_BYTES))
+
+        target = self.tmp / "restored-tampered"
+        restored = run([
+            "restore", "--archive", str(self.archive), "--manifest", str(self.manifest),
+            "--target", str(target),
+        ])
+        self.assertNotEqual(restored.returncode, 0)
+        self.assertFalse(target.exists())
+
+    def test_verify_refuses_a_member_the_manifest_never_listed(self) -> None:
+        source = build_source(self.tmp)
+        self.assertEqual(self.backup(source).returncode, 0)
+        craft_archive(self.archive, [
+            ("payload/images/sample-1.jpg", IMAGE_BYTES),
+            ("payload/manifest.jsonl", (source / "manifest.jsonl").read_bytes()),
+            ("payload/extra.bin", b"unlisted"),
+        ])
+        verified = run(["verify", "--archive", str(self.archive), "--manifest", str(self.manifest)])
+        self.assertNotEqual(verified.returncode, 0)
+        self.assertIn("not listed in the manifest", verified.stderr)
+
+    def test_restore_refuses_traversal_and_absolute_members(self) -> None:
+        for name, needle in (("payload/../../etc/passwd", "outside"), ("/etc/passwd", "absolute")):
+            with self.subTest(member=name):
+                archive = self.tmp / "hostile.tar.gz"
+                manifest_path = self.tmp / "hostile.manifest.json"
+                payload = b"root:x:0:0"
+                craft_archive(archive, [(name, payload)])
+                manifest_path.write_text(json.dumps({
+                    "schemaVersion": 1,
+                    "files": [{"path": "images/sample-1.jpg", "sha256": digest(payload), "bytes": len(payload)}],
+                    "records": {"samples": 0, "tombstones": 0, "activeSamples": 0},
+                }), encoding="utf-8")
+                target = self.tmp / f"hostile-out-{needle}"
+                restored = run([
+                    "restore", "--archive", str(archive), "--manifest", str(manifest_path),
+                    "--target", str(target),
+                ])
+                self.assertNotEqual(restored.returncode, 0)
+                self.assertIn(needle, restored.stderr.lower())
+                self.assertFalse(target.exists())
+
+    def test_restore_refuses_link_members(self) -> None:
+        archive = self.tmp / "link.tar.gz"
+        manifest_path = self.tmp / "link.manifest.json"
+        craft_archive(archive, [("payload/manifest.jsonl", b"{}\n")], link="payload/images/sample-1.jpg")
+        manifest_path.write_text(json.dumps({
+            "schemaVersion": 1,
+            "files": [{"path": "manifest.jsonl", "sha256": digest(b"{}\n"), "bytes": 3}],
+            "records": {"samples": 0, "tombstones": 0, "activeSamples": 0},
+        }), encoding="utf-8")
+        target = self.tmp / "link-out"
+        restored = run([
+            "restore", "--archive", str(archive), "--manifest", str(manifest_path), "--target", str(target),
+        ])
+        self.assertNotEqual(restored.returncode, 0)
+        self.assertIn("link", restored.stderr)
+        self.assertFalse(target.exists())
+
+    def test_restore_refuses_a_non_empty_target(self) -> None:
+        source = build_source(self.tmp)
+        self.assertEqual(self.backup(source).returncode, 0)
+        target = self.tmp / "occupied"
+        target.mkdir()
+        (target / "keep.txt").write_text("operator file that must not be overwritten", encoding="utf-8")
+        restored = run([
+            "restore", "--archive", str(self.archive), "--manifest", str(self.manifest),
+            "--target", str(target),
+        ])
+        self.assertNotEqual(restored.returncode, 0)
+        self.assertIn("not empty", restored.stderr)
+        self.assertEqual((target / "keep.txt").read_text(encoding="utf-8"), "operator file that must not be overwritten")
+
+    def test_backup_is_reproducible_for_the_same_records(self) -> None:
+        source = build_source(self.tmp, with_tombstone=True)
+        self.assertEqual(self.backup(source).returncode, 0)
+        first = json.loads(self.manifest.read_text(encoding="utf-8"))
+        first_digest = hashlib.sha256(self.archive.read_bytes()).hexdigest()
+        self.archive.unlink()
+        self.manifest.unlink()
+        self.assertEqual(self.backup(source).returncode, 0)
+        second = json.loads(self.manifest.read_text(encoding="utf-8"))
+        self.assertEqual(first["files"], second["files"])
+        self.assertEqual(first["excluded"], second["excluded"])
+        self.assertEqual(first_digest, hashlib.sha256(self.archive.read_bytes()).hexdigest())
+        self.assertNotEqual(first["createdAt"], "")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/calibration-harness.test.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""Tests for the contributor-held-out evaluation harness.
+
+Issue #29 asks for the authoritative comparison and release-gate harness: macro-F1, per-class
+precision/recall, a confusion matrix, calibration error, coverage, and precision-at-coverage, over
+splits that are contributor-held-out and reproducible, comparing candidate models.
+
+Every fixture in this file is synthetic: fictional pseudonymous subject keys and invented
+prediction scores. No real photo, label, or patient record is read or written.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+import unittest
+
+ROOT = Path(__file__).resolve().parents[1]
+HARNESS = ROOT / "scripts" / "calibration_report.py"
+
+
+def load_harness():
+    spec = importlib.util.spec_from_file_location("calibration_report", HARNESS)
+    assert spec and spec.loader, "scripts/calibration_report.py must exist"
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+harness = load_harness()
+
+
+def record(subject_key: str, truth: int, predicted: int | None, confidence: float, *, split: str | None = None, model: str = "frozen-encoder") -> dict:
+    return {
+        "model": model,
+        "subjectKey": subject_key,
+        "split": split or harness.expected_split(subject_key),
+        "truth": {"bristolType": truth},
+        "prediction": None if predicted is None else {"bristolType": predicted, "confidence": confidence},
+    }
+
+
+class ComparisonTests(unittest.TestCase):
+    def models(self):
+        return {
+            "specialist-candidate": [
+                record("cd00000000000001", 4, 4, 1.0),
+                record("ce00000000000002", 3, 3, 1.0),
+                record("e600000000000001", 4, 4, 1.0),
+                record("e700000000000002", 6, 6, 1.0),
+            ],
+            "vlm-bootstrap": [
+                record("d000000000000004", 4, 4, 1.0),
+                record("e600000000000003", 4, 2, 1.0),
+                record("e700000000000004", 6, 6, 1.0),
+            ],
+        }
+
+    def test_measures_each_candidate_on_test_at_a_threshold_chosen_on_validation(self):
+        verdict = harness.compare(self.models())
+        self.assertEqual([row["model"] for row in verdict["models"]], ["specialist-candidate", "vlm-bootstrap"])
+        specialist = verdict["models"][0]
+        self.assertEqual(specialist["selectionSplit"], "validation")
+        self.assertEqual(specialist["threshold"], 0.0)
+        self.assertEqual(specialist["evaluatedSplit"], "test")
+        self.assertAlmostEqual(specialist["macroF1"], 1.0, places=6)
+        self.assertTrue(specialist["gate"]["passed"])
+        self.assertEqual(specialist["gate"]["failed"], [])
+        self.assertEqual(verdict["recommended"], "specialist-candidate")
+        self.assertEqual(verdict["verdict"], "GO")
+
+    def test_a_candidate_that_is_only_half_right_fails_the_macro_f1_precision_and_calibration_gates(self):
+        vlm = next(row for row in harness.compare(self.models())["models"] if row["model"] == "vlm-bootstrap")
+        self.assertAlmostEqual(vlm["precisionAtCoverage"], 0.5, places=6)
+        self.assertFalse(vlm["gate"]["passed"])
+        self.assertEqual(vlm["gate"]["failed"], ["macroF1", "precisionAtCoverage", "ece"])
+
+    def test_blocks_the_release_when_no_candidate_clears_every_gate(self):
+        models = {"vlm-bootstrap": self.models()["vlm-bootstrap"]}
+        verdict = harness.compare(models)
+        self.assertEqual(verdict["verdict"], "BLOCKED")
+        self.assertIsNone(verdict["recommended"])
+        self.assertEqual(verdict["gates"], {"macroF1": 0.80, "precisionAtCoverage": 0.90, "ece": 0.05})
+
+    def test_gate_limits_are_inclusive_so_a_candidate_exactly_on_the_line_passes(self):
+        records = [
+            record("cd00000000000001", 4, 4, 0.9),
+            record("e600000000000001", 4, 4, 0.9),
+            record("e700000000000002", 3, 2, 0.9),
+        ]
+        verdict = harness.compare({"frozen-encoder": records}, gates={"macroF1": 0.0, "precisionAtCoverage": 0.5, "ece": 1.0})
+        row = verdict["models"][0]
+        self.assertAlmostEqual(row["precisionAtCoverage"], 0.5, places=6)
+        self.assertTrue(row["gate"]["passed"], row["gate"])
+
+    def test_refuses_a_candidate_with_no_held_out_predictions(self):
+        with self.assertRaisesRegex(harness.EvaluationError, "no test-split predictions"):
+            harness.compare({"frozen-encoder": [record("cd00000000000001", 4, 4, 1.0)]})
+
+
+class CliTests(unittest.TestCase):
+    def write_predictions(self, directory: Path, name: str, rows: list[dict]) -> Path:
+        path = directory / name
+        path.write_text("\n".join(json.dumps(row) for row in rows) + "\n", encoding="utf-8")
+        return path
+
+    def run_cli(self, *args: str) -> subprocess.CompletedProcess:
+        return subprocess.run(
+            [sys.executable, str(HARNESS), *args], cwd=ROOT, capture_output=True, text=True
+        )
+
+    def test_reports_a_go_with_the_candidate_table_and_writes_the_json_report(self):
+        with tempfile.TemporaryDirectory() as raw:
+            directory = Path(raw)
+            predictions = self.write_predictions(directory, "predictions.jsonl", [
+                {**record("cd00000000000001", 4, 4, 1.0), "model": "specialist-candidate"},
+                {**record("e600000000000001", 4, 4, 1.0), "model": "specialist-candidate"},
+                {**record("e700000000000002", 6, 6, 1.0), "model": "specialist-candidate"},
+            ])
+            output = directory / "report.json"
+            run = self.run_cli("--predictions", str(predictions), "--json", str(output), "--min-coverage", "0.5")
+            self.assertEqual(run.returncode, 0, run.stderr)
+            self.assertIn("verdict: GO", run.stdout)
+            self.assertIn("specialist-candidate", run.stdout)
+            self.assertIn("macroF1", run.stdout)
+            report = json.loads(output.read_text(encoding="utf-8"))
+            self.assertEqual(report["verdict"], "GO")
+            self.assertEqual(report["recommended"], "specialist-candidate")
+            self.assertEqual(report["models"][0]["evaluatedSplit"], "test")
+            self.assertEqual(report["models"][0]["selectionSplit"], "validation")
+
+    def test_exits_three_when_the_release_gate_blocks(self):
+        with tempfile.TemporaryDirectory() as raw:
+            directory = Path(raw)
+            predictions = self.write_predictions(directory, "predictions.jsonl", [
+                {**record("cd00000000000001", 4, 3, 1.0), "model": "vlm-bootstrap"},
+                {**record("e600000000000001", 4, 2, 1.0), "model": "vlm-bootstrap"},
+            ])
+            run = self.run_cli("--predictions", str(predictions))
+            self.assertEqual(run.returncode, 3, run.stderr)
+            self.assertIn("verdict: BLOCKED", run.stdout)
+
+
+    def test_refuses_an_out_of_range_label_instead_of_scoring_it(self):
+        with tempfile.TemporaryDirectory() as raw:
+            directory = Path(raw)
+            output = directory / "report.json"
+            bad_truth = self.write_predictions(directory, "truth.jsonl", [
+                {**record("cd00000000000001", 9, 9, 1.0), "model": "frozen-encoder"},
+            ])
+            run = self.run_cli("--predictions", str(bad_truth), "--json", str(output))
+            self.assertEqual(run.returncode, 2)
+            self.assertIn("outside Bristol 1-7", run.stderr)
+            self.assertFalse(output.exists(), "a refused run must not leave a report behind")
+            bad_prediction = self.write_predictions(directory, "prediction.jsonl", [
+                {**record("e600000000000001", 4, 9, 1.0), "model": "frozen-encoder"},
+            ])
+            run = self.run_cli("--predictions", str(bad_prediction))
+            self.assertEqual(run.returncode, 2)
+            self.assertIn("predicted bristolType must be 1-7", run.stderr)
+
+    def test_refuses_a_corpus_that_leaks_a_contributor_across_splits(self):
+        with tempfile.TemporaryDirectory() as raw:
+            directory = Path(raw)
+            predictions = self.write_predictions(directory, "predictions.jsonl", [
+                {**record("cd00000000000001", 4, 4, 1.0, split="train"), "model": "frozen-encoder"},
+                {**record("cd00000000000001", 4, 4, 1.0, split="validation"), "model": "frozen-encoder"},
+                {**record("e600000000000001", 4, 4, 1.0), "model": "frozen-encoder"},
+            ])
+            run = self.run_cli("--predictions", str(predictions))
+            self.assertEqual(run.returncode, 2)
+            self.assertIn("leaks across", run.stderr)
+
+
+class ThresholdSelectionTests(unittest.TestCase):
+    def validation_records(self):
+        # 0xcd–0xe5 bucket to validation under the ingestion rule. Confident answers are right and
+        # the least confident one is wrong, which is what a threshold is supposed to exploit.
+        return [
+            record("cd00000000000001", 4, 4, 0.90),
+            record("ce00000000000002", 4, 4, 0.80),
+            record("cf00000000000003", 3, 3, 0.60),
+            record("d000000000000004", 7, 4, 0.40),
+        ]
+
+    def test_picks_the_most_precise_threshold_that_still_clears_the_coverage_floor(self):
+        records = self.validation_records()
+        # At a 0.5 floor, 0.60 and 0.80 are both perfect; the wider cut wins, so 0.60.
+        floored = harness.select_threshold(records, min_coverage=0.5)
+        self.assertEqual(floored["threshold"], 0.6)
+        self.assertEqual(floored["counts"], {"total": 4, "accepted": 3, "abstained": 1})
+        self.assertAlmostEqual(floored["precisionAtCoverage"], 1.0, places=6)
+        self.assertAlmostEqual(floored["coverage"], 0.75, places=6)
+        self.assertEqual(floored["selectionSplit"], "validation")
+        # A 0.8 floor forbids that cut, so the harness falls back to the widest honest threshold
+        # instead of silently returning a threshold that violates the floor.
+        strict = harness.select_threshold(records, min_coverage=0.8)
+        self.assertEqual(strict["threshold"], 0.0)
+        self.assertAlmostEqual(strict["precisionAtCoverage"], 0.75, places=6)
+
+    def test_refuses_an_unreachable_coverage_floor(self):
+        with self.assertRaisesRegex(harness.EvaluationError, "coverage floor"):
+            harness.select_threshold(self.validation_records(), min_coverage=1.5)
+
+    def test_refuses_to_choose_a_threshold_on_test_or_train_data(self):
+        test_only = [record("e700000000000001", 4, 4, 0.9)]
+        with self.assertRaisesRegex(harness.EvaluationError, "validation split only"):
+            harness.select_threshold(test_only, min_coverage=0.5)
+        train_mixed = [record("aa00000000000001", 4, 4, 0.9), record("cd00000000000001", 3, 3, 0.8)]
+        with self.assertRaisesRegex(harness.EvaluationError, "validation split only"):
+            harness.select_threshold(train_mixed, min_coverage=0.5)
+
+
+class ContributorHeldOutTests(unittest.TestCase):
+    def test_refuses_a_split_that_cannot_be_derived_from_the_subject_key(self):
+        # 0xaa = 170, below the train/validation edge, so this subject can only ever be train.
+        records = [record("aa00000000000001", 4, 4, 0.9, split="test")]
+        with self.assertRaisesRegex(harness.EvaluationError, "not reproducible"):
+            harness.assert_contributor_held_out(records)
+
+
+    def test_refuses_a_contributor_whose_photos_span_two_splits(self):
+        records = [
+            record("aa00000000000001", 4, 4, 0.9, split="train"),
+            record("aa00000000000001", 3, 3, 0.8, split="validation"),
+        ]
+        with self.assertRaisesRegex(harness.EvaluationError, "leaks across"):
+            harness.assert_contributor_held_out(records)
+
+    def test_allows_one_contributor_to_supply_several_photos_in_the_same_split(self):
+        records = [
+            record("aa00000000000001", 4, 4, 0.9),
+            record("aa00000000000001", 3, 3, 0.8),
+        ]
+        harness.assert_contributor_held_out(records)  # several photos, one person, one split: fine
+
+
+class CalibrationTests(unittest.TestCase):
+    def test_calibration_error_weights_each_confidence_bin_by_its_share_of_accepted_suggestions(self):
+        records = [
+            record("aa00000000000001", 4, 4, 0.95),
+            record("ab00000000000002", 4, 4, 0.90),
+            record("ac00000000000003", 3, 3, 0.55),
+            record("ad00000000000004", 7, 7, 0.70),
+        ]
+        # Bins [0.9,1.0) hold both 0.95 and 0.90: mean confidence 0.925, accuracy 1.0, gap 0.075.
+        self.assertAlmostEqual(harness.evaluate(records, threshold=0.0)["ece"], 0.225, places=6)
+        # Raising the threshold to 0.6 drops the 0.55 sample, so it can no longer pull calibration.
+        self.assertAlmostEqual(harness.evaluate(records, threshold=0.6)["ece"], 0.15, places=6)
+
+
+class AbstentionTests(unittest.TestCase):
+    def test_low_confidence_and_explicit_abstentions_shrink_coverage_but_never_count_as_errors(self):
+        records = [
+            record("aa00000000000001", 4, 4, 0.90),
+            record("ab00000000000002", 4, 3, 0.55),
+            record("ac00000000000003", 3, 3, 0.40),
+            record("ad00000000000004", 7, None, 0.0),
+        ]
+        report = harness.evaluate(records, threshold=0.6)
+        self.assertEqual(report["counts"], {"total": 4, "accepted": 1, "abstained": 3})
+        self.assertAlmostEqual(report["coverage"], 0.25, places=6)
+        self.assertAlmostEqual(report["precisionAtCoverage"], 1.0, places=6)
+        # Only the accepted suggestion is scored; the class that abstained away is named, not hidden.
+        self.assertEqual(sorted(report["perClass"]), [4])
+        self.assertAlmostEqual(report["macroF1"], 1.0, places=6)
+        self.assertEqual(report["excludedClasses"], [3, 7])
+        self.assertEqual(report["abstentions"], {"low-confidence": 2, "no-suggestion": 1})
+
+    def test_a_threshold_above_every_confidence_abstains_on_everything_without_crashing(self):
+        records = [
+            record("aa00000000000001", 4, 4, 0.30),
+            record("ab00000000000002", 2, 2, 0.50),
+        ]
+        report = harness.evaluate(records, threshold=0.95)
+        self.assertEqual(report["counts"], {"total": 2, "accepted": 0, "abstained": 2})
+        self.assertAlmostEqual(report["coverage"], 0.0, places=6)
+        self.assertAlmostEqual(report["macroF1"], 0.0, places=6)
+        self.assertEqual(report["perClass"], {})
+
+
+class MacroF1Tests(unittest.TestCase):
+    def test_scores_each_bristol_class_and_averages_only_the_classes_present_in_truth(self):
+        records = [
+            record("aa00000000000001", 4, 4, 0.90),
+            record("ab00000000000002", 4, 3, 0.80),
+            record("ac00000000000003", 3, 3, 0.70),
+            record("ad00000000000004", 7, 7, 0.60),
+        ]
+        report = harness.evaluate(records, threshold=0.0)
+        self.assertEqual(sorted(report["perClass"]), [3, 4, 7])
+        self.assertAlmostEqual(report["perClass"][4]["precision"], 1.0, places=6)
+        self.assertAlmostEqual(report["perClass"][4]["recall"], 0.5, places=6)
+        self.assertAlmostEqual(report["perClass"][4]["f1"], 0.666667, places=6)
+        self.assertAlmostEqual(report["perClass"][3]["precision"], 0.5, places=6)
+        self.assertAlmostEqual(report["perClass"][3]["recall"], 1.0, places=6)
+        self.assertAlmostEqual(report["perClass"][7]["f1"], 1.0, places=6)
+        self.assertAlmostEqual(report["macroF1"], 0.777778, places=6)
+        self.assertEqual(report["confusion"], {"4->4": 1, "4->3": 1, "3->3": 1, "7->7": 1})
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/ci-workflow.test.js

@@ -34,6 +34,17 @@ test('CI pins the Python image dependency required by the full unit suite', asyn
   assert.match(requirements, /^Pillow==12\.3\.0$/m);
 });
 
+test('the dataset card generator and its suite are CI- and release-gated', async () => {
+  const workflow = await readFile(workflowPath, 'utf8');
+  const packageJson = JSON.parse(await readFile(packagePath, 'utf8'));
+
+  // Issue #27 publishes a page a stranger reads about the corpus, so the generator that decides its
+  // numbers runs in CI and is invoked by its own suite, not only by whoever remembers.
+  assert.match(workflow, /python3 tests\/dataset-card\.test\.py -v/);
+  assert.match(packageJson.scripts['test:dataset-card'], /dataset-card\.test\.py/);
+  assert.match(packageJson.scripts['check:syntax'], /py_compile[^&]*scripts\/dataset_card\.py/);
+});
+
 test('default unit suite includes the self-host bootstrap contract', async () => {
   const packageJson = JSON.parse(await readFile(packagePath, 'utf8'));
 
@@ -174,3 +185,31 @@ test('the deterministic symptom escalation regression suite runs in the default
   assert.match(builder, /"src\/domain\.js"/);
   assert.match(builder, /"src\/hermes-agent-service\.js"/);
 });
+
+test('the calibration harness is wired into the unit and syntax gates', async () => {
+  const [packageJsonText, workflow] = await Promise.all([
+    readFile(packagePath, 'utf8'),
+    readFile(workflowPath, 'utf8'),
+  ]);
+  const packageJson = JSON.parse(packageJsonText);
+
+  // Issue #29: a release gate nothing runs is a claim, not a gate.
+  assert.equal(packageJson.scripts['test:calibration'], 'python3 tests/calibration-harness.test.py');
+  assert.match(packageJson.scripts['check:syntax'], /py_compile[^&]*scripts\/calibration_report\.py/);
+  assert.match(workflow, /python3 tests\/calibration-harness\.test\.py -v/);
+  // The release builder has to run it too, or the gate exists only in CI.
+  const builder = await readFile(new URL('../scripts/build_release.py', import.meta.url), 'utf8');
+  assert.match(builder, /tests\/calibration-harness\.test\.py/);
+  assert.match(builder, /"calibration_harness_gates": "passed"/);
+});
+
+test('CI runs the RC attack suite so its evidence is reproducible on every change', async () => {
+  const workflow = await readFile(workflowPath, 'utf8');
+  const packageJson = JSON.parse(await readFile(packagePath, 'utf8'));
+
+  // Issue #40: the attack report is evidence, not a claim. CI has to be able to regenerate it.
+  assert.match(workflow, /npm run test:security-attack/);
+  assert.equal(packageJson.scripts['test:security-attack'], 'node tests/security-attack.acceptance.mjs');
+  assert.match(packageJson.scripts.test, /tests\/release-security-gate\.test\.js/);
+  assert.match(packageJson.scripts['check:syntax'], /node --check src\/release-security-gate\.js/);
+});

tests/corpus-manifest.test.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""Tests for the auditable corpus manifest: provenance, tombstones, and lifecycle rules.
+
+Issue #25 promotes the ingest script into a corpus pipeline with an append-only manifest,
+revocation tombstones, and lifecycle transitions that cannot be walked backwards. Every
+fixture here is synthetic; no real photo bytes are read or written.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+import unittest
+
+from PIL import Image
+
+ROOT = Path(__file__).resolve().parents[1]
+INGEST = ROOT / "scripts" / "ingest_training_photo.py"
+FIXTURE = ROOT / "tests" / "fixtures" / "synthetic-type4.jpg"
+CONTRIBUTION_ID = "6f1d0c9e-2c4a-4f3b-9d1e-8a7b6c5d4e3f"
+ISO_UTC = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?\+00:00$")
+
+
+def load_structures():
+    spec = importlib.util.spec_from_file_location("corpus_manifest", ROOT / "scripts" / "corpus_manifest.py")
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+structures = load_structures()
+
+
+def active_image_paths(out: Path) -> list[str]:
+    return [record["relativePath"] for record in structures.active_records(structures.load_manifest(out / "manifest.jsonl"))]
+
+
+
+def ingest(args: list[str], env: dict[str, str] | None = None) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, str(INGEST), *args],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        env={**os.environ, "TIMMY_DATASET_SALT": "test-only-salt", **(env or {})},
+    )
+
+
+def ingest_default(out: Path, **overrides: str) -> subprocess.CompletedProcess:
+    args = [
+        "--input", str(FIXTURE),
+        "--output-dir", str(out),
+        "--subject-id", "subject-123",
+        "--consent-version", "research-v1",
+        "--contribution-id", CONTRIBUTION_ID,
+        "--bristol-type", "4",
+        "--color", "brown",
+        "--quality", "good",
+        "--reviewer", "user-confirmed",
+    ]
+    for key, value in overrides.items():
+        flag = "--" + key.replace("_", "-")
+        if value is None:
+            index = args.index(flag)
+            del args[index:index + 2]
+            continue
+        args[args.index(flag) + 1] = value
+    return ingest(args)
+
+
+def manifest_lines(out: Path) -> list[dict]:
+    text = (out / "manifest.jsonl").read_text(encoding="utf-8")
+    return [json.loads(line) for line in text.splitlines() if line.strip()]
+
+
+class IngestProvenanceTests(unittest.TestCase):
+    def test_ingest_records_consent_source_hashes_derivation_review_split_and_lifecycle(self):
+        with tempfile.TemporaryDirectory() as raw:
+            out = Path(raw)
+            run = ingest_default(out)
+            self.assertEqual(run.returncode, 0, run.stderr)
+            record = json.loads(run.stdout)
+            raw_bytes = FIXTURE.read_bytes()
+
+            self.assertEqual(record["schemaVersion"], 2)
+            self.assertEqual(record["contributionId"], CONTRIBUTION_ID)
+            self.assertEqual(record["consentVersion"], "research-v1")
+            self.assertEqual(record["consent"], {"version": "research-v1", "recordedAt": record["ingestedAt"]})
+            self.assertRegex(record["consent"]["recordedAt"], ISO_UTC)
+
+            # Source is named, and the raw input only ever appears as a digest.
+            self.assertEqual(record["source"], {
+                "kind": "cli-ingest",
+                "inputSha256": hashlib.sha256(raw_bytes).hexdigest(),
+            })
+            self.assertEqual(record["hashes"]["rawInput"], hashlib.sha256(raw_bytes).hexdigest())
+            self.assertEqual(record["hashes"]["derived"], record["imageId"])
+
+            self.assertEqual(record["derivation"], {
+                "format": "jpeg",
+                "maxDimension": 1200,
+                "metadataStripped": True,
+                "pipeline": "timmy-ingest/2",
+            })
+            self.assertEqual(record["review"], {"status": "user-confirmed", "reviewedAt": record["ingestedAt"]})
+            self.assertIn(record["split"], ("train", "validation", "test"))
+            self.assertEqual(record["lifecycle"], {"state": "active", "updatedAt": record["ingestedAt"]})
+            self.assertEqual(record["recordType"], "sample")
+
+            # Provenance never leaks the caller's path or the source bytes.
+            self.assertNotIn("inputPath", record)
+            on_disk = (out / "manifest.jsonl").read_text(encoding="utf-8")
+            self.assertNotIn(str(FIXTURE), on_disk)
+            self.assertNotIn(str(out), on_disk)
+            self.assertEqual(manifest_lines(out), [record])
+            self.assertTrue((out / record["relativePath"]).is_file())
+
+
+class RevocationTests(unittest.TestCase):
+    def test_revocation_appends_a_tombstone_and_removes_the_bytes_from_active_datasets(self):
+        with tempfile.TemporaryDirectory() as raw:
+            out = Path(raw)
+            self.assertEqual(ingest_default(out).returncode, 0)
+            sample = manifest_lines(out)[0]
+            derived = out / sample["relativePath"]
+            self.assertTrue(derived.is_file())
+            # Some pipelines keep the pre-derivation copy; revocation must clear that too.
+            raw_dir = out / "raw"
+            raw_dir.mkdir()
+            raw_copy = raw_dir / f"{sample['hashes']['rawInput']}.jpg"
+            raw_copy.write_bytes(FIXTURE.read_bytes())
+
+            run = ingest(["--revoke", CONTRIBUTION_ID, "--output-dir", str(out), "--reason", "subject withdrawal"])
+            self.assertEqual(run.returncode, 0, run.stderr)
+            tombstone = json.loads(run.stdout)
+
+            self.assertEqual(tombstone["schemaVersion"], 2)
+            self.assertEqual(tombstone["recordType"], "tombstone")
+            self.assertEqual(tombstone["contributionId"], CONTRIBUTION_ID)
+            self.assertEqual(tombstone["imageId"], sample["imageId"])
+            self.assertEqual(tombstone["lifecycle"]["state"], "revoked")
+            self.assertRegex(tombstone["lifecycle"]["updatedAt"], ISO_UTC)
+            self.assertEqual(tombstone["lifecycle"]["reason"], "subject withdrawal")
+
+            # The tombstone addresses every derived artifact by contribution id, and says what went.
+            self.assertEqual(tombstone["deletedArtifacts"], [
+                {"relativePath": sample["relativePath"], "sha256": sample["hashes"]["derived"], "deleted": True},
+                {"relativePath": f"raw/{sample['hashes']['rawInput']}.jpg", "sha256": sample["hashes"]["rawInput"], "deleted": True},
+            ])
+            self.assertEqual(tombstone["contributionId"], CONTRIBUTION_ID)
+
+            # No byte-bearing copy survives anywhere in the dataset tree.
+            self.assertFalse(derived.exists())
+            self.assertFalse(raw_copy.exists())
+            survivors = []
+            for path in out.rglob("*"):
+                if path.is_file() and path.name != "manifest.jsonl":
+                    survivors.append((str(path.relative_to(out)), hashlib.sha256(path.read_bytes()).hexdigest()))
+            self.assertEqual(survivors, [])
+
+            # History is append-only: the sample record is untouched, the tombstone follows it.
+            history = manifest_lines(out)
+            self.assertEqual(len(history), 2)
+            self.assertEqual(history[0], sample)
+            self.assertEqual(history[1], tombstone)
+
+            # A deletion receipt keeps identifiers and hashes, never the label or subject key.
+            self.assertNotIn("labels", tombstone)
+            self.assertNotIn("subjectKey", tombstone)
+            self.assertNotIn("relativePath", tombstone)
+
+
+class ActiveRecordTests(unittest.TestCase):
+    def test_only_unrevoked_samples_are_active(self):
+        with tempfile.TemporaryDirectory() as raw:
+            out = Path(raw)
+            self.assertEqual(ingest_default(out).returncode, 0)
+            self.assertEqual(active_image_paths(out), [f"images/{manifest_lines(out)[0]['imageId']}.jpg"])
+            self.assertEqual(ingest(["--revoke", CONTRIBUTION_ID, "--output-dir", str(out), "--reason", "gone"]).returncode, 0)
+            self.assertEqual(active_image_paths(out), [])
+
+
+class IllegalTransitionTests(unittest.TestCase):
+    def test_a_second_revocation_is_refused_and_appends_nothing(self):
+        with tempfile.TemporaryDirectory() as raw:
+            out = Path(raw)
+            self.assertEqual(ingest_default(out).returncode, 0)
+            self.assertEqual(ingest(["--revoke", CONTRIBUTION_ID, "--output-dir", str(out), "--reason", "first"]).returncode, 0)
+            history = manifest_lines(out)
+            self.assertEqual(len(history), 2)
+
+            again = ingest(["--revoke", CONTRIBUTION_ID, "--output-dir", str(out), "--reason", "again"])
+            self.assertNotEqual(again.returncode, 0)
+            self.assertRegex(again.stderr, "already revoked")
+            self.assertEqual(manifest_lines(out), history)
+
+    def test_revoking_an_unknown_contribution_is_refused(self):
+        with tempfile.TemporaryDirectory() as raw:
+            out = Path(raw)
+            self.assertEqual(ingest_default(out).returncode, 0)
+            history = manifest_lines(out)
+
+            unknown = ingest(["--revoke", "11111111-2222-3333-4444-555555555555", "--output-dir", str(out), "--reason", "nope"])
+            self.assertNotEqual(unknown.returncode, 0)
+            self.assertRegex(unknown.stderr, "no ingested sample carries contribution")
+            self.assertEqual(manifest_lines(out), history)
+            self.assertTrue((out / history[0]["relativePath"]).is_file())
+
+    def test_a_contribution_cannot_be_ingested_twice(self):
+        with tempfile.TemporaryDirectory() as raw:
+            out = Path(raw)
+            self.assertEqual(ingest_default(out).returncode, 0)
+            history = manifest_lines(out)
+
+            duplicate = ingest_default(out, color="green")
+            self.assertNotEqual(duplicate.returncode, 0)
+            self.assertRegex(duplicate.stderr, "already ingested")
+            self.assertEqual(manifest_lines(out), history)
+
+    def test_a_refused_duplicate_leaves_no_orphan_image_behind(self):
+        with tempfile.TemporaryDirectory() as raw:
+            out = Path(raw)
+            self.assertEqual(ingest_default(out).returncode, 0)
+            history = manifest_lines(out)
+
+            # Same contribution id, different pixels: the derived digest differs, so a guard that
+            # runs after the write would strand a second image in the active dataset.
+            variant = out.parent / "variant-type4.jpg"
+            with Image.open(FIXTURE) as source:
+                changed = source.convert("RGB")
+                changed.putpixel((4, 4), (255, 0, 0))
+                changed.save(variant, "JPEG", quality=95)
+            duplicate = ingest_default(out, input=str(variant))
+            self.assertNotEqual(duplicate.returncode, 0)
+            self.assertRegex(duplicate.stderr, "already ingested")
+
+            self.assertEqual(manifest_lines(out), history)
+            images = sorted(path.name for path in (out / "images").iterdir())
+            self.assertEqual(images, [f"{history[0]['imageId']}.jpg"])
+
+
+    def test_lifecycle_transitions_cannot_walk_backwards(self):
+        with tempfile.TemporaryDirectory() as raw:
+            out = Path(raw)
+            self.assertEqual(ingest_default(out).returncode, 0)
+            sample = manifest_lines(out)[0]
+            at = sample["ingestedAt"]
+
+            revoked = structures.transition(sample, "revoked", at, "withdrawal")
+            self.assertEqual(revoked["lifecycle"]["state"], "revoked")
+            self.assertEqual(revoked["lifecycle"]["reason"], "withdrawal")
+            self.assertEqual(sample["lifecycle"]["state"], "active", "transition must not mutate its input")
+
+            for args, expected in (
+                ((revoked, "active", at), "cannot return to the active dataset"),
+                ((sample, "revoked", at, "   "), "recorded reason"),
+                ((sample, "archived", at), "unknown lifecycle state"),
+                (({**sample, "lifecycle": {"state": "active", "updatedAt": at}}, "active", at), "already active"),
+            ):
+                with self.assertRaises(structures.IllegalTransition) as raised:
+                    structures.transition(*args)
+                self.assertRegex(str(raised.exception), expected)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/corpus-review.test.py

@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+"""Tests for the blind reviewer and adjudication tool (issue #26).
+
+The tool decides what a training sample is allowed to say, so these tests attack the two
+properties that make the labels trustworthy:
+
+* a reviewer never sees the model's answer before committing their own, and
+* a withdrawn contribution can never be shown, reviewed, or trained on.
+
+Every fixture is the committed synthetic image; no real photo bytes are read or written.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+INGEST = ROOT / "scripts" / "ingest_training_photo.py"
+FIXTURE = ROOT / "tests" / "fixtures" / "synthetic-type4.jpg"
+FIRST = "6f1d0c9e-2c4a-4f3b-9d1e-8a7b6c5d4e3f"
+SECOND = "0b9a8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d"
+
+
+def load_tool():
+    spec = importlib.util.spec_from_file_location("review_corpus", ROOT / "scripts" / "review_corpus.py")
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+tool = load_tool()
+
+
+def ingest(dataset: Path, contribution: str, *, bristol: str = "4", color: str = "brown", quality: str = "good") -> dict:
+    done = subprocess.run(
+        [
+            sys.executable, str(INGEST),
+            "--input", str(FIXTURE),
+            "--output-dir", str(dataset),
+            "--subject-id", "subject-123",
+            "--consent-version", "research-v1",
+            "--contribution-id", contribution,
+            "--bristol-type", bristol,
+            "--color", color,
+            "--quality", quality,
+            "--reviewer", "user-confirmed",
+        ],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        env={**os.environ, "TIMMY_DATASET_SALT": "review-test-salt"},
+    )
+    assert done.returncode == 0, done.stderr
+    return json.loads(done.stdout)
+
+
+def revoke(dataset: Path, contribution: str) -> dict:
+    done = subprocess.run(
+        [sys.executable, str(INGEST), "--output-dir", str(dataset), "--revoke", contribution, "--reason", "participant withdrew consent"],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        env={**os.environ, "TIMMY_DATASET_SALT": "review-test-salt"},
+    )
+    assert done.returncode == 0, done.stderr
+    return json.loads(done.stdout)
+
+
+def ledger(dataset: Path) -> list[dict]:
+    path = dataset / "reviews.jsonl"
+    if not path.exists():
+        return []
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+PREDICTIONS = {
+    "version": "synthetic-model-placeholder",
+    "answers": {
+        FIRST: {"bristolType": 6, "color": "brown", "quality": "good", "confidence": 0.71},
+        SECOND: {"bristolType": 4, "color": "brown", "quality": "good", "confidence": 0.9},
+    },
+}
+
+
+class QueueBlindnessTests(unittest.TestCase):
+    def test_the_queue_shows_the_proposal_and_withholds_every_model_field(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            sample = ingest(dataset, FIRST)
+
+            queue = tool.build_queue(dataset)
+
+            self.assertEqual(len(queue), 1)
+            packet = queue[0]
+            self.assertEqual(packet["contributionId"], FIRST)
+            self.assertEqual(packet["imageId"], sample["imageId"])
+            self.assertEqual(packet["relativePath"], sample["relativePath"])
+            self.assertEqual(packet["proposed"], {"bristolType": 4, "color": "brown", "quality": "good"})
+            self.assertTrue(packet["blindToModel"])
+
+            # Not a naming convention: nothing model-shaped and nothing identity-bearing may ride along.
+            text = json.dumps(packet)
+            for forbidden in ("confidence", "modelSuggestion", "prediction", "subjectKey", "data:image", "base64"):
+                self.assertNotIn(forbidden, text)
+
+    def test_resolved_samples_leave_the_queue(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+            self.assertEqual(len(tool.build_queue(dataset)), 1)
+
+            tool.commit_review(dataset, FIRST, "reviewer-a", "agreed")
+
+            self.assertEqual(tool.build_queue(dataset), [])
+
+    def test_the_queue_refuses_an_active_sample_whose_image_is_gone(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            sample = ingest(dataset, FIRST)
+            (dataset / sample["relativePath"]).unlink()
+
+            with self.assertRaises(tool.ReviewError) as raised:
+                tool.build_queue(dataset)
+            self.assertRegex(str(raised.exception), "image is missing")
+
+
+class BlindRevealTests(unittest.TestCase):
+    def test_the_model_answer_stays_hidden_until_a_review_is_committed(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+
+            with self.assertRaises(tool.ReviewError) as raised:
+                tool.reveal(dataset, FIRST, PREDICTIONS)
+            self.assertRegex(str(raised.exception), "hidden until a review is committed")
+
+    def test_reveal_reports_the_disagreement_after_the_human_commits(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+            tool.commit_review(dataset, FIRST, "reviewer-a", "corrected", {"bristolType": 5, "color": "green", "quality": "fair"})
+
+            revealed = tool.reveal(dataset, FIRST, PREDICTIONS)
+
+            self.assertEqual(revealed["human"]["labels"], {"bristolType": 5, "color": "green", "quality": "fair"})
+            self.assertEqual(revealed["model"]["labels"], {"bristolType": 6, "color": "brown", "quality": "good"})
+            self.assertEqual(revealed["disagreeFields"], ["bristolType", "color", "quality"])
+            self.assertTrue(revealed["disagreement"])
+            # Revealing is a read: it must not quietly rewrite the review ledger.
+            self.assertEqual(len(ledger(dataset)), 1)
+
+
+class CommitTests(unittest.TestCase):
+    def test_a_committed_review_keeps_the_proposal_and_the_human_decision(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            sample = ingest(dataset, FIRST)
+
+            record = tool.commit_review(dataset, FIRST, "reviewer-a", "corrected", {"bristolType": 2, "color": "brown", "quality": "poor"}, at="2026-10-27T09:00:00+00:00")
+
+            self.assertEqual(record["recordType"], "review")
+            self.assertEqual(record["contributionId"], FIRST)
+            self.assertEqual(record["imageId"], sample["imageId"])
+            self.assertEqual(record["reviewer"], "reviewer-a")
+            self.assertEqual(record["decision"], "corrected")
+            self.assertEqual(record["labels"], {"bristolType": 2, "color": "brown", "quality": "poor"})
+            self.assertEqual(record["proposed"], {"bristolType": 4, "color": "brown", "quality": "good"})
+            self.assertEqual(record["committedAt"], "2026-10-27T09:00:00+00:00")
+            self.assertEqual(ledger(dataset), [record])
+            self.assertNotIn("subjectKey", json.dumps(record))
+
+    def test_a_contribution_cannot_be_reviewed_twice(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+            tool.commit_review(dataset, FIRST, "reviewer-a", "agreed")
+            history = ledger(dataset)
+
+            with self.assertRaises(tool.ReviewError) as raised:
+                tool.commit_review(dataset, FIRST, "reviewer-b", "corrected", {"bristolType": 2, "color": "black", "quality": "poor"})
+            self.assertRegex(str(raised.exception), "already reviewed")
+            self.assertEqual(ledger(dataset), history)
+
+    def test_a_correction_that_changes_nothing_is_refused(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+
+            with self.assertRaises(tool.ReviewError) as raised:
+                tool.commit_review(dataset, FIRST, "reviewer-a", "corrected", {"bristolType": 4, "color": "brown", "quality": "good"})
+            self.assertRegex(str(raised.exception), "must change the proposed label")
+            self.assertEqual(ledger(dataset), [])
+
+    def test_invalid_labels_and_blank_reviewers_are_refused(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+
+            for decision, labels, reviewer, expected in (
+                ("corrected", {"bristolType": 9, "color": "brown", "quality": "good"}, "reviewer-a", "bristolType must be 1-7"),
+                ("corrected", {"bristolType": 4, "color": "purple", "quality": "good"}, "reviewer-a", "color and quality"),
+                ("agreed", None, "   ", "reviewer is required"),
+                ("excluded", None, "reviewer-a", "exclusion needs a recorded reason"),
+                ("approved", None, "reviewer-a", "decision must be one of"),
+            ):
+                with self.assertRaises(tool.ReviewError) as raised:
+                    tool.commit_review(dataset, FIRST, reviewer, decision, labels)
+                self.assertRegex(str(raised.exception), expected)
+            self.assertEqual(ledger(dataset), [])
+
+    def test_reviewing_an_unknown_contribution_is_refused(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+
+            with self.assertRaises(tool.ReviewError) as raised:
+                tool.commit_review(dataset, SECOND, "reviewer-a", "agreed")
+            self.assertRegex(str(raised.exception), "no active sample carries contribution")
+            self.assertEqual(ledger(dataset), [])
+
+
+class WithdrawnContributionTests(unittest.TestCase):
+    def test_a_withdrawn_contribution_never_reaches_the_queue_review_or_the_trainer(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+            tool.commit_review(dataset, FIRST, "reviewer-a", "corrected", {"bristolType": 5, "color": "brown", "quality": "good"})
+            self.assertEqual(len(tool.trainable_records(dataset)), 1)
+
+            revoke(dataset, FIRST)
+
+            self.assertEqual(tool.build_queue(dataset), [])
+            self.assertEqual(tool.trainable_records(dataset), [])
+            for call in (
+                lambda: tool.commit_review(dataset, FIRST, "reviewer-b", "agreed"),
+                lambda: tool.adjudicate(dataset, FIRST, "reviewer-b", "upheld"),
+                lambda: tool.reveal(dataset, FIRST, PREDICTIONS),
+            ):
+                with self.assertRaises(tool.ReviewError) as raised:
+                    call()
+                self.assertRegex(str(raised.exception), "withdrawn")
+
+
+class AdjudicationTests(unittest.TestCase):
+    def test_adjudication_is_appended_and_the_first_review_is_preserved(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+            first = tool.commit_review(dataset, FIRST, "reviewer-a", "corrected", {"bristolType": 5, "color": "brown", "quality": "good"}, at="2026-10-27T09:00:00+00:00")
+
+            ruling = tool.adjudicate(dataset, FIRST, "reviewer-b", "corrected", {"bristolType": 4, "color": "brown", "quality": "fair"}, at="2026-10-27T10:00:00+00:00")
+
+            self.assertEqual(ruling["recordType"], "adjudication")
+            self.assertEqual(ruling["decision"], "corrected")
+            self.assertEqual(ruling["labels"], {"bristolType": 4, "color": "brown", "quality": "fair"})
+            self.assertEqual(ruling["resolvesRecord"], 1)
+            self.assertEqual(ruling["resolves"], {"reviewer": "reviewer-a", "decision": "corrected"})
+
+            history = ledger(dataset)
+            self.assertEqual(len(history), 2)
+            self.assertEqual(history[0], first, "the review being overruled must survive untouched")
+            self.assertEqual(history[1], ruling)
+
+            # The trainer follows the ruling, not the review it replaced.
+            trainable = tool.trainable_records(dataset)
+            self.assertEqual(len(trainable), 1)
+            self.assertEqual(trainable[0]["labels"], {"bristolType": 4, "color": "brown", "quality": "fair"})
+            self.assertEqual(trainable[0]["adjudicatedBy"], "reviewer-b")
+
+    def test_an_upheld_review_keeps_the_label_and_records_the_second_reader(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+            tool.commit_review(dataset, FIRST, "reviewer-a", "agreed")
+
+            ruling = tool.adjudicate(dataset, FIRST, "reviewer-b", "upheld")
+
+            self.assertEqual(ruling["labels"], {"bristolType": 4, "color": "brown", "quality": "good"})
+            self.assertEqual(ruling["resolves"], {"reviewer": "reviewer-a", "decision": "agreed"})
+
+    def test_a_reviewer_cannot_adjudicate_their_own_review(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+            tool.commit_review(dataset, FIRST, "reviewer-a", "agreed")
+
+            with self.assertRaises(tool.ReviewError) as raised:
+                tool.adjudicate(dataset, FIRST, "reviewer-a", "corrected", {"bristolType": 2, "color": "brown", "quality": "good"})
+            self.assertRegex(str(raised.exception), "second reviewer")
+            self.assertEqual(len(ledger(dataset)), 1)
+
+    def test_a_second_adjudication_is_refused(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+            tool.commit_review(dataset, FIRST, "reviewer-a", "agreed")
+            tool.adjudicate(dataset, FIRST, "reviewer-b", "upheld")
+            history = ledger(dataset)
+
+            with self.assertRaises(tool.ReviewError) as raised:
+                tool.adjudicate(dataset, FIRST, "reviewer-c", "excluded", exclusion_reason="unclear")
+            self.assertRegex(str(raised.exception), "already adjudicated")
+            self.assertEqual(ledger(dataset), history)
+
+    def test_adjudicating_an_unreviewed_contribution_is_refused(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+
+            with self.assertRaises(tool.ReviewError) as raised:
+                tool.adjudicate(dataset, FIRST, "reviewer-b", "upheld")
+            self.assertRegex(str(raised.exception), "no review to adjudicate")
+            self.assertEqual(ledger(dataset), [])
+
+
+class TrainableSetTests(unittest.TestCase):
+    def test_only_human_reviewed_and_unexcluded_samples_reach_the_trainer(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+            ingest(dataset, SECOND)
+
+            # Unreviewed samples are not training data, however confident the proposal is.
+            self.assertEqual(tool.trainable_records(dataset), [])
+
+            tool.commit_review(dataset, FIRST, "reviewer-a", "agreed")
+            tool.commit_review(dataset, SECOND, "reviewer-a", "excluded", exclusion_reason="cannot tell stool from photo edge")
+
+            trainable = tool.trainable_records(dataset)
+            self.assertEqual([item["contributionId"] for item in trainable], [FIRST])
+            self.assertEqual(trainable[0]["labels"], {"bristolType": 4, "color": "brown", "quality": "good"})
+            self.assertEqual(trainable[0]["reviewedBy"], "reviewer-a")
+
+            # Excluded is a labeling judgement, not a withdrawal: the provenance record still exists.
+            history = [json.loads(line) for line in (dataset / "manifest.jsonl").read_text(encoding="utf-8").splitlines() if line.strip()]
+            self.assertEqual(len(history), 2)
+
+
+class PredictionFileTests(unittest.TestCase):
+    def test_a_pretty_printed_answer_file_is_read_whole_not_line_by_line(self):
+        with tempfile.TemporaryDirectory() as raw:
+            path = Path(raw) / "answers.json"
+            path.write_text(json.dumps({"model": "synthetic answer file", "answers": {FIRST: {"bristolType": 6, "color": "brown", "quality": "good"}}}, indent=2), encoding="utf-8")
+
+            loaded = tool.load_predictions(path)
+
+            self.assertEqual(loaded["answers"][FIRST]["bristolType"], 6)
+
+    def test_a_line_delimited_answer_file_is_read_by_contribution(self):
+        with tempfile.TemporaryDirectory() as raw:
+            path = Path(raw) / "answers.jsonl"
+            path.write_text(
+                json.dumps({"contributionId": FIRST, "bristolType": 6, "color": "brown", "quality": "good"}) + "\n"
+                + json.dumps({"contributionId": SECOND, "bristolType": 2, "color": "black", "quality": "poor"}) + "\n",
+                encoding="utf-8",
+            )
+
+            loaded = tool.load_predictions(path)
+
+            self.assertEqual(loaded["answers"][FIRST]["bristolType"], 6)
+            self.assertEqual(loaded["answers"][SECOND]["bristolType"], 2)
+
+    def test_an_answer_without_an_identifier_is_refused(self):
+        with tempfile.TemporaryDirectory() as raw:
+            path = Path(raw) / "answers.jsonl"
+            path.write_text(json.dumps({"bristolType": 6}) + "\n", encoding="utf-8")
+
+            with self.assertRaises(tool.ReviewError) as raised:
+                tool.load_predictions(path)
+            self.assertRegex(str(raised.exception), "contributionId or imageId")
+
+
+class CliTests(unittest.TestCase):
+    def run_cli(self, *args: str) -> subprocess.CompletedProcess:
+        return subprocess.run(
+            [sys.executable, str(ROOT / "scripts" / "review_corpus.py"), *args],
+            cwd=ROOT, capture_output=True, text=True,
+        )
+
+    def test_the_cli_keeps_the_blind_order_and_reports_refusals_non_zero(self):
+        with tempfile.TemporaryDirectory() as raw:
+            dataset = Path(raw)
+            ingest(dataset, FIRST)
+
+            queue = self.run_cli("queue", "--dataset", str(dataset))
+            self.assertEqual(queue.returncode, 0, queue.stderr)
+            packet = json.loads(queue.stdout)
+            self.assertEqual(packet["count"], 1)
+            self.assertNotIn("confidence", queue.stdout)
+
+            early = self.run_cli("reveal", "--dataset", str(dataset), "--contribution", FIRST)
+            self.assertNotEqual(early.returncode, 0)
+            self.assertRegex(early.stderr, "hidden until a review is committed")
+
+            committed = self.run_cli(
+                "review", "--dataset", str(dataset), "--contribution", FIRST,
+                "--reviewer", "reviewer-a", "--bristol", "5", "--color", "green", "--quality", "fair",
+            )
+            self.assertEqual(committed.returncode, 0, committed.stderr)
+            self.assertEqual(json.loads(committed.stdout)["decision"], "corrected")
+
+            reveal = self.run_cli("reveal", "--dataset", str(dataset), "--contribution", FIRST)
+            self.assertEqual(reveal.returncode, 0, reveal.stderr)
+            self.assertEqual(json.loads(reveal.stdout)["model"], None, "no prediction was supplied, so none is invented")
+
+            trainable = self.run_cli("trainable", "--dataset", str(dataset))
+            self.assertEqual(trainable.returncode, 0, trainable.stderr)
+            self.assertEqual(json.loads(trainable.stdout)["count"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/dataset-card.test.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""Tests for the published dataset card and the contributor-level split policy.
+
+Issue #27 asks for three things a stranger can inspect before trusting a model: a dataset card that
+reports who is in the corpus, *the* labeling guide, and a contributor-level split policy that keeps a
+person's photos in exactly one split. The card is generated from the append-only manifest by
+[`scripts/dataset_card.py`](../scripts/dataset_card.py) instead of being written by hand, so a number
+on it is a claim the corpus can be re-checked against and an unknown fact can only appear as
+``pending`` — never as a plausible-looking estimate.
+
+Every fixture here is synthetic: records are built through the real
+[`scripts/corpus_manifest.py`](../scripts/corpus_manifest.py) builder and no image bytes are read or
+written.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+import unittest
+
+ROOT = Path(__file__).resolve().parents[1]
+CARD_SCRIPT = ROOT / "scripts" / "dataset_card.py"
+COMMITTED_CARD = ROOT / "docs" / "DATASET_CARD.md"
+LABELING_GUIDE = ROOT / "docs" / "LABELING_GUIDE.md"
+CANONICAL_CORPUS = "/srv/timmy-corpus"
+
+# Subject keys chosen so the ingestion rule (first byte of the key) puts each contributor in a known
+# split: < 205 train, < 230 validation, otherwise test.
+TRAIN_A = "0a" + "1" * 14
+TRAIN_B = "0b" + "2" * 14
+VALIDATION_C = "d0" + "3" * 14
+TEST_D = "ee" + "4" * 14
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("corpus_manifest", ROOT / "scripts" / "corpus_manifest.py")
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+structures = load_module()
+
+
+def digest(seed: str) -> str:
+    import hashlib
+
+    return hashlib.sha256(seed.encode()).hexdigest()
+
+
+def sample(
+    *,
+    contribution_id: str,
+    subject_key: str,
+    split: str,
+    bristol: int = 4,
+    color: str = "brown",
+    quality: str = "good",
+    reviewer: str = "user-confirmed",
+    at: str = "2026-08-01T10:00:00+00:00",
+) -> dict:
+    return structures.build_record(
+        contribution_id=contribution_id,
+        consent_version="training-consent-v1",
+        subject_key=subject_key,
+        split=split,
+        labels={"bristolType": bristol, "color": color, "quality": quality},
+        review_status=reviewer,
+        derived_sha256=digest(contribution_id + "-derived"),
+        raw_sha256=digest(contribution_id + "-raw"),
+        ingested_at=at,
+    )
+
+
+def write_manifest(dataset: Path, records: list[dict]) -> Path:
+    manifest = dataset / "manifest.jsonl"
+    manifest.parent.mkdir(parents=True, exist_ok=True)
+    with manifest.open("w", encoding="utf-8") as handle:
+        for record in records:
+            handle.write(json.dumps(record, separators=(",", ":")) + "\n")
+    return manifest
+
+
+def run_card(args: list[str]) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, str(CARD_SCRIPT), *args],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        env={**os.environ},
+    )
+
+
+def build_corpus(dataset: Path) -> None:
+    """Four active samples across three contributors, plus one withdrawal."""
+    records = [
+        sample(contribution_id="contrib-train-a1", subject_key=TRAIN_A, split="train", bristol=4),
+        sample(contribution_id="contrib-train-a2", subject_key=TRAIN_A, split="train", bristol=3, color="green"),
+        sample(contribution_id="contrib-train-b1", subject_key=TRAIN_B, split="train", bristol=6, quality="fair"),
+        sample(
+            contribution_id="contrib-validation-c1",
+            subject_key=VALIDATION_C,
+            split="validation",
+            bristol=4,
+            reviewer="clinician-reviewed",
+        ),
+        sample(contribution_id="contrib-test-d1", subject_key=TEST_D, split="test", bristol=1, quality="poor"),
+    ]
+    revoked = structures.transition(
+        sample(contribution_id="contrib-withdrawn-1", subject_key=TEST_D, split="test", bristol=7, color="black"),
+        "revoked",
+        "2026-08-02T09:00:00+00:00",
+        "participant withdrew consent",
+    )
+    write_manifest(dataset, [*records, revoked])
+
+
+class DatasetCardTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = tempfile.TemporaryDirectory()
+        self.dataset = Path(self.tmp.name) / "corpus"
+        self.dataset.mkdir(parents=True, exist_ok=True)
+
+    def tearDown(self) -> None:
+        self.tmp.cleanup()
+
+    def test_card_reports_the_real_corpus_counts_from_the_manifest(self) -> None:
+        build_corpus(self.dataset)
+        result = run_card(["--corpus", str(self.dataset)])
+        self.assertEqual(result.returncode, 0, result.stderr)
+        card = result.stdout
+
+        # Five active samples from four contributors; the withdrawal is reported separately.
+        self.assertIn("| Active samples | 5 |", card)
+        self.assertIn("| Contributors | 4 |", card)
+        self.assertIn("| Withdrawals | 1 |", card)
+        # Contributor-level split policy: the contributor count per split is what a reader needs to
+        # see that one person cannot be in two splits.
+        self.assertIn("| `train` | 2 | 3 |", card)
+        self.assertIn("| `validation` | 1 | 1 |", card)
+        self.assertIn("| `test` | 1 | 1 |", card)
+        # Class balance is counted, not described.
+        self.assertIn("| Type 4 | 2 |", card)
+        self.assertIn("| Type 1 | 1 |", card)
+        self.assertIn("| `black` | 0 |", card, "a withdrawn sample's label must not be counted")
+        self.assertIn("| `clinician-reviewed` | 1 |", card)
+
+    def test_card_marks_uncollected_facts_pending_instead_of_estimating_them(self) -> None:
+        build_corpus(self.dataset)
+        card = run_card(["--corpus", str(self.dataset)]).stdout
+
+        for fact in ("Devices", "Contexts", "Licenses"):
+            line = next((row for row in card.splitlines() if row.startswith(f"| {fact} |")), None)
+            self.assertIsNotNone(line, f"the card must name {fact}")
+            self.assertIn("pending", line.lower(), f"{fact} cannot be reported until it is collected")
+        self.assertIn("rather than estimated", card.lower())
+        self.assertIn("nothing here is invented", card.lower())
+
+    def test_card_names_withdrawals_without_exposing_the_person_or_their_labels(self) -> None:
+        build_corpus(self.dataset)
+        card = run_card(["--corpus", str(self.dataset)]).stdout
+
+        self.assertIn("contrib-withdrawn-1", card)
+        self.assertIn("participant withdrew consent", card)
+        for subject in (TRAIN_A, TRAIN_B, VALIDATION_C, TEST_D):
+            self.assertNotIn(subject, card, "the published card must never carry a subject key")
+        self.assertNotIn(digest("contrib-withdrawn-1" + "-derived"), card)
+
+    def test_card_refuses_a_contributor_spread_across_two_splits(self) -> None:
+        write_manifest(
+            self.dataset,
+            [
+                sample(contribution_id="contrib-leak-1", subject_key=TEST_D, split="test"),
+                # Same person, relabelled into training: the leak the policy exists to stop.
+                sample(contribution_id="contrib-leak-2", subject_key=TEST_D, split="train"),
+            ],
+        )
+        out = Path(self.tmp.name) / "card.md"
+        result = run_card(["--corpus", str(self.dataset), "--out", str(out)])
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertRegex(result.stderr, r"contributor [0-9a-f]{16} (leaks across|is in two splits)")
+        self.assertFalse(out.exists(), "a refused card must not be written")
+
+    def test_card_refuses_a_split_the_subject_key_does_not_derive(self) -> None:
+        write_manifest(
+            self.dataset,
+            [sample(contribution_id="contrib-mislabelled-1", subject_key=TEST_D, split="train")],
+        )
+        result = run_card(["--corpus", str(self.dataset)])
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertRegex(result.stderr, r"not reproducible")
+
+    def test_card_states_the_split_rule_it_applies(self) -> None:
+        build_corpus(self.dataset)
+        card = run_card(["--corpus", str(self.dataset)]).stdout
+
+        # The thresholds are the ingestion rule; a card that states a different rule is a different
+        # policy, so both edges are named on the page.
+        self.assertIn("205", card)
+        self.assertIn("230", card)
+        self.assertRegex(card, r"subject key")
+
+    def test_card_is_byte_identical_between_runs(self) -> None:
+        build_corpus(self.dataset)
+        first = run_card(["--corpus", str(self.dataset)])
+        second = run_card(["--corpus", str(self.dataset)])
+        # A rendered card, not two matching empty strings: the run has to succeed and say something.
+        self.assertEqual(first.returncode, 0, first.stderr)
+        self.assertIn("| Active samples | 5 |", first.stdout)
+        self.assertEqual(first.stdout, second.stdout)
+
+    def test_card_is_honest_when_there_is_no_corpus(self) -> None:
+        missing = Path(self.tmp.name) / "absent"
+        result = run_card(["--corpus", str(missing)])
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("| Active samples | 0 |", result.stdout)
+        self.assertIn("| Contributors | 0 |", result.stdout)
+        self.assertRegex(result.stdout, r"no consented images")
+        self.assertIn("pending", result.stdout.lower(), "an empty corpus reports pending facts, not blanks")
+
+    def test_card_reports_a_withdrawal_count_without_inventing_a_denominator(self) -> None:
+        build_corpus(self.dataset)
+        summary = json.loads(run_card(["--corpus", str(self.dataset), "--json"]).stdout)
+
+        self.assertEqual(summary["activeSamples"], 5)
+        self.assertEqual(summary["contributors"], 4)
+        self.assertEqual(summary["withdrawals"], 1)
+        self.assertEqual(summary["bySplit"]["train"], {"contributors": 2, "samples": 3})
+        self.assertEqual(summary["pending"], ["contexts", "devices", "licenses"])
+        self.assertEqual([entry["contributionId"] for entry in summary["withdrawalsDetail"]], ["contrib-withdrawn-1"])
+        self.assertNotIn("subjectKey", json.dumps(summary))
+
+    def test_committed_card_is_the_generator_output_not_a_hand_written_page(self) -> None:
+        card = COMMITTED_CARD.read_text(encoding="utf-8")
+        result = run_card(["--corpus", CANONICAL_CORPUS])
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(
+            card,
+            result.stdout,
+            "docs/DATASET_CARD.md must be regenerated with scripts/dataset_card.py, never hand-edited",
+        )
+        self.assertIn(f"--corpus {CANONICAL_CORPUS}", card)
+
+    def test_check_mode_refuses_a_hand_edited_card(self) -> None:
+        build_corpus(self.dataset)
+        stale = Path(self.tmp.name) / "stale-card.md"
+        stale.write_text("# Dataset card\n\n| Active samples | 9000 |\n", encoding="utf-8")
+
+        result = run_card(["--corpus", str(self.dataset), "--check", str(stale)])
+        self.assertNotEqual(result.returncode, 0)
+        self.assertRegex(result.stderr, r"out of date|differs")
+
+    def test_labeling_guide_separates_visible_color_from_blood_and_forbids_diagnosis(self) -> None:
+        guide = LABELING_GUIDE.read_text(encoding="utf-8")
+        lowered = guide.lower()
+
+        self.assertIn("color", lowered)
+        # Visible color is not bleeding: the guide has to say so in the reviewer's own vocabulary.
+        self.assertIn("not blood", lowered)
+        for forbidden in ("diagnose", "diagnosis"):
+            self.assertIn(forbidden, lowered, "the guide must name what a label may never assert")
+        self.assertRegex(lowered, r"do not diagnose|never diagnos")
+        # Exclusions and the split policy are part of the guide, not a separate folklore.
+        self.assertIn("exclude", lowered)
+        self.assertRegex(lowered, r"one split|same split")
+        # The card and the guide point at each other, so a reader lands on both.
+        self.assertIn("DATASET_CARD.md", guide)
+        self.assertIn("LABELING_GUIDE.md", COMMITTED_CARD.read_text(encoding="utf-8"))
+
+    def test_labeling_guide_never_claims_a_model_decides_the_label(self) -> None:
+        guide = LABELING_GUIDE.read_text(encoding="utf-8")
+        lowered = guide.lower()
+
+        self.assertRegex(lowered, r"human|reviewer")
+        # A model suggestion is provisional input to a human decision, never the decision.
+        self.assertRegex(lowered, r"provisional|suggestion")
+        self.assertNotRegex(lowered, r"model (decides|determines) the label")
+
+
+    def test_readme_points_a_newcomer_at_the_card_and_the_guide(self) -> None:
+        readme = (ROOT / "README.md").read_text(encoding="utf-8")
+
+        # A published card nobody links to is not published: both pages are reachable from the front page.
+        self.assertIn("docs/DATASET_CARD.md", readme)
+        self.assertIn("docs/LABELING_GUIDE.md", readme)
+        self.assertIn("scripts/dataset_card.py", readme)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/domain.test.js

@@ -8,6 +8,7 @@ import {
   detectUrgentText,
   exportLedger,
   hasUrgentLedgerContext,
+  LEDGER_EXPORT_VERSION,
   photoQualityMessage,
   sanitizeEntry,
 } from '../src/domain.js';
@@ -113,9 +114,10 @@ test('sanitizes a user entry to the MVP data contract', () => {
   });
   assert.deepEqual(Object.keys(entry).sort(), [
     'bristolType', 'color', 'discomfort', 'id', 'note', 'occurredAt',
-    'photoDataUrl', 'symptoms', 'urgency'
+    'photoDataUrl', 'provenance', 'symptoms', 'urgency'
   ].sort());
   assert.equal(entry.unexpected, undefined);
+  assert.equal(entry.provenance, null, 'a manual entry records no AI provenance rather than an invented one');
 });
 
 test('photo quality guidance is deterministic and does not claim visual diagnosis', () => {
@@ -125,10 +127,11 @@ test('photo quality guidance is deterministic and does not claim visual diagnosi
   assert.doesNotMatch(photoQualityMessage({ width: 1200, height: 900, brightness: 0.5 }), /type [1-7]|disease|diagnos/i);
 });
 
-test('export ledger is portable JSON with version and entries', () => {
+test('export ledger is portable JSON with the current version and entries', () => {
   const text = exportLedger([{ id: 'a', bristolType: 4 }], '2026-08-18T00:00:00.000Z');
   const parsed = JSON.parse(text);
-  assert.equal(parsed.schemaVersion, 1);
+  assert.equal(parsed.schemaVersion, LEDGER_EXPORT_VERSION);
+  assert.equal(parsed.schemaVersion, 2);
   assert.equal(parsed.exportedAt, '2026-08-18T00:00:00.000Z');
   assert.equal(parsed.entries.length, 1);
 });

tests/fixtures/calibration/README.md

@@ -0,0 +1,31 @@
+# Synthetic calibration fixtures
+
+These files prove the evaluation harness in `scripts/calibration_report.py` (issue #29) computes the
+release gates correctly. **They are not measurements.** No model produced them, no contributor
+supplied them, and no number here says anything about how well Timmy labels a real photo.
+
+Every row is a promise in the same shape the harness accepts:
+
+```json
+{"model":"…","subjectKey":"<16 hex>","split":"validation","truth":{"bristolType":4},
+ "prediction":{"bristolType":4,"confidence":0.97}}
+```
+
+`subjectKey` values are fictional but obey the ingestion split rule (the first byte of the key picks
+the split), so the harness's contributor-held-out check is exercised for real. `prediction: null`
+means the candidate produced no suggestion at all.
+
+| File | What it is for | Harness outcome |
+|---|---|---|
+| `predictions.jsonl` | Three candidates with invented scores: a bootstrap that calls almost everything Type 4, a frozen encoder that is precise but badly calibrated, and a specialist that looks strong on validation and slips on test. | `BLOCKED` — each candidate fails a different gate. |
+| `predictions-go.jsonl` | One engineered candidate that clears every gate, including a low-confidence mistake on validation that the threshold is supposed to cut away. | `GO` — proves the passing branch and threshold selection, not a result. |
+| `predictions-leaky.jsonl` | One contributor whose photos sit in both `validation` and `test`. | Refused with exit 2 — a leaked corpus is never scored. |
+
+## Regenerating
+
+The numbers are hand-chosen so the expected outcome is obvious by inspection; there is no generator
+to re-run. If you change a row, update the expectation in `tests/calibration-harness.test.py` and the
+caption in `scripts/record_release_demo.mjs` together, and read the harness output back before
+claiming what it says.
+
+No image, no diagnosis, and no patient data lives in this directory.

tests/fixtures/calibration/predictions-go.jsonl

@@ -0,0 +1,14 @@
+{"model":"gate-plumbing-fixture","subjectKey":"cd1a2b3c4d5e6f01","split":"validation","truth":{"bristolType":1},"prediction":{"bristolType":1,"confidence":0.97}}
+{"model":"gate-plumbing-fixture","subjectKey":"ce2b3c4d5e6f7012","split":"validation","truth":{"bristolType":2},"prediction":{"bristolType":2,"confidence":0.97}}
+{"model":"gate-plumbing-fixture","subjectKey":"cf3c4d5e6f701223","split":"validation","truth":{"bristolType":3},"prediction":{"bristolType":3,"confidence":0.98}}
+{"model":"gate-plumbing-fixture","subjectKey":"d04d5e6f70122334","split":"validation","truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.97}}
+{"model":"gate-plumbing-fixture","subjectKey":"d15e6f7012233445","split":"validation","truth":{"bristolType":5},"prediction":{"bristolType":5,"confidence":0.98}}
+{"model":"gate-plumbing-fixture","subjectKey":"d26f701223344556","split":"validation","truth":{"bristolType":6},"prediction":{"bristolType":3,"confidence":0.6}}
+{"model":"gate-plumbing-fixture","subjectKey":"d370122334455667","split":"validation","truth":{"bristolType":7},"prediction":{"bristolType":7,"confidence":0.97}}
+{"model":"gate-plumbing-fixture","subjectKey":"e671223344556677","split":"test","truth":{"bristolType":1},"prediction":{"bristolType":1,"confidence":0.97}}
+{"model":"gate-plumbing-fixture","subjectKey":"e772334455667788","split":"test","truth":{"bristolType":2},"prediction":{"bristolType":2,"confidence":0.98}}
+{"model":"gate-plumbing-fixture","subjectKey":"e883445566778899","split":"test","truth":{"bristolType":3},"prediction":{"bristolType":3,"confidence":0.97}}
+{"model":"gate-plumbing-fixture","subjectKey":"e994556677889900","split":"test","truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.98}}
+{"model":"gate-plumbing-fixture","subjectKey":"eaa5667788990011","split":"test","truth":{"bristolType":5},"prediction":{"bristolType":5,"confidence":0.97}}
+{"model":"gate-plumbing-fixture","subjectKey":"ebb6778899001122","split":"test","truth":{"bristolType":6},"prediction":{"bristolType":6,"confidence":0.97}}
+{"model":"gate-plumbing-fixture","subjectKey":"ecc7889900112233","split":"test","truth":{"bristolType":7},"prediction":{"bristolType":7,"confidence":0.98}}

tests/fixtures/calibration/predictions-leaky.jsonl

@@ -0,0 +1,2 @@
+{"model":"frozen-encoder","subjectKey":"cd1a2b3c4d5e6f01","split":"validation","truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.7}}
+{"model":"frozen-encoder","subjectKey":"cd1a2b3c4d5e6f01","split":"test","truth":{"bristolType":6},"prediction":{"bristolType":6,"confidence":0.7}}

tests/fixtures/calibration/predictions.jsonl

@@ -0,0 +1,42 @@
+{"model":"vlm-bootstrap","subjectKey":"cd1a2b3c4d5e6f01","split":"validation","truth":{"bristolType":1},"prediction":{"bristolType":4,"confidence":0.55}}
+{"model":"vlm-bootstrap","subjectKey":"ce2b3c4d5e6f7012","split":"validation","truth":{"bristolType":2},"prediction":{"bristolType":4,"confidence":0.52}}
+{"model":"vlm-bootstrap","subjectKey":"cf3c4d5e6f701223","split":"validation","truth":{"bristolType":3},"prediction":{"bristolType":4,"confidence":0.61}}
+{"model":"vlm-bootstrap","subjectKey":"d04d5e6f70122334","split":"validation","truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.72}}
+{"model":"vlm-bootstrap","subjectKey":"d15e6f7012233445","split":"validation","truth":{"bristolType":5},"prediction":{"bristolType":4,"confidence":0.64}}
+{"model":"vlm-bootstrap","subjectKey":"d26f701223344556","split":"validation","truth":{"bristolType":6},"prediction":{"bristolType":4,"confidence":0.58}}
+{"model":"vlm-bootstrap","subjectKey":"d370122334455667","split":"validation","truth":{"bristolType":7},"prediction":{"bristolType":4,"confidence":0.53}}
+{"model":"vlm-bootstrap","subjectKey":"e671223344556677","split":"test","truth":{"bristolType":1},"prediction":{"bristolType":4,"confidence":0.57}}
+{"model":"vlm-bootstrap","subjectKey":"e772334455667788","split":"test","truth":{"bristolType":2},"prediction":{"bristolType":4,"confidence":0.54}}
+{"model":"vlm-bootstrap","subjectKey":"e883445566778899","split":"test","truth":{"bristolType":3},"prediction":{"bristolType":4,"confidence":0.63}}
+{"model":"vlm-bootstrap","subjectKey":"e994556677889900","split":"test","truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.7}}
+{"model":"vlm-bootstrap","subjectKey":"eaa5667788990011","split":"test","truth":{"bristolType":5},"prediction":{"bristolType":4,"confidence":0.62}}
+{"model":"vlm-bootstrap","subjectKey":"ebb6778899001122","split":"test","truth":{"bristolType":6},"prediction":{"bristolType":4,"confidence":0.59}}
+{"model":"vlm-bootstrap","subjectKey":"ecc7889900112233","split":"test","truth":{"bristolType":7},"prediction":{"bristolType":4,"confidence":0.51}}
+{"model":"frozen-encoder","subjectKey":"cd1a2b3c4d5e6f01","split":"validation","truth":{"bristolType":1},"prediction":{"bristolType":1,"confidence":0.62}}
+{"model":"frozen-encoder","subjectKey":"ce2b3c4d5e6f7012","split":"validation","truth":{"bristolType":2},"prediction":{"bristolType":2,"confidence":0.58}}
+{"model":"frozen-encoder","subjectKey":"cf3c4d5e6f701223","split":"validation","truth":{"bristolType":3},"prediction":{"bristolType":4,"confidence":0.66}}
+{"model":"frozen-encoder","subjectKey":"d04d5e6f70122334","split":"validation","truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.71}}
+{"model":"frozen-encoder","subjectKey":"d15e6f7012233445","split":"validation","truth":{"bristolType":5},"prediction":{"bristolType":5,"confidence":0.57}}
+{"model":"frozen-encoder","subjectKey":"d26f701223344556","split":"validation","truth":{"bristolType":6},"prediction":{"bristolType":6,"confidence":0.64}}
+{"model":"frozen-encoder","subjectKey":"d370122334455667","split":"validation","truth":{"bristolType":7},"prediction":{"bristolType":6,"confidence":0.55}}
+{"model":"frozen-encoder","subjectKey":"e671223344556677","split":"test","truth":{"bristolType":1},"prediction":{"bristolType":1,"confidence":0.6}}
+{"model":"frozen-encoder","subjectKey":"e772334455667788","split":"test","truth":{"bristolType":2},"prediction":{"bristolType":2,"confidence":0.59}}
+{"model":"frozen-encoder","subjectKey":"e883445566778899","split":"test","truth":{"bristolType":3},"prediction":{"bristolType":3,"confidence":0.63}}
+{"model":"frozen-encoder","subjectKey":"e994556677889900","split":"test","truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.69}}
+{"model":"frozen-encoder","subjectKey":"eaa5667788990011","split":"test","truth":{"bristolType":5},"prediction":{"bristolType":6,"confidence":0.56}}
+{"model":"frozen-encoder","subjectKey":"ebb6778899001122","split":"test","truth":{"bristolType":6},"prediction":{"bristolType":6,"confidence":0.61}}
+{"model":"frozen-encoder","subjectKey":"ecc7889900112233","split":"test","truth":{"bristolType":7},"prediction":{"bristolType":7,"confidence":0.54}}
+{"model":"specialist-candidate","subjectKey":"cd1a2b3c4d5e6f01","split":"validation","truth":{"bristolType":1},"prediction":{"bristolType":1,"confidence":0.88}}
+{"model":"specialist-candidate","subjectKey":"ce2b3c4d5e6f7012","split":"validation","truth":{"bristolType":2},"prediction":{"bristolType":2,"confidence":0.86}}
+{"model":"specialist-candidate","subjectKey":"cf3c4d5e6f701223","split":"validation","truth":{"bristolType":3},"prediction":{"bristolType":3,"confidence":0.9}}
+{"model":"specialist-candidate","subjectKey":"d04d5e6f70122334","split":"validation","truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.94}}
+{"model":"specialist-candidate","subjectKey":"d15e6f7012233445","split":"validation","truth":{"bristolType":5},"prediction":{"bristolType":5,"confidence":0.87}}
+{"model":"specialist-candidate","subjectKey":"d26f701223344556","split":"validation","truth":{"bristolType":6},"prediction":{"bristolType":6,"confidence":0.91}}
+{"model":"specialist-candidate","subjectKey":"d370122334455667","split":"validation","truth":{"bristolType":7},"prediction":{"bristolType":7,"confidence":0.85}}
+{"model":"specialist-candidate","subjectKey":"e671223344556677","split":"test","truth":{"bristolType":1},"prediction":{"bristolType":1,"confidence":0.86}}
+{"model":"specialist-candidate","subjectKey":"e772334455667788","split":"test","truth":{"bristolType":2},"prediction":{"bristolType":2,"confidence":0.84}}
+{"model":"specialist-candidate","subjectKey":"e883445566778899","split":"test","truth":{"bristolType":3},"prediction":{"bristolType":3,"confidence":0.89}}
+{"model":"specialist-candidate","subjectKey":"e994556677889900","split":"test","truth":{"bristolType":4},"prediction":{"bristolType":4,"confidence":0.92}}
+{"model":"specialist-candidate","subjectKey":"eaa5667788990011","split":"test","truth":{"bristolType":5},"prediction":{"bristolType":5,"confidence":0.88}}
+{"model":"specialist-candidate","subjectKey":"ebb6778899001122","split":"test","truth":{"bristolType":6},"prediction":{"bristolType":3,"confidence":0.83}}
+{"model":"specialist-candidate","subjectKey":"ecc7889900112233","split":"test","truth":{"bristolType":7},"prediction":{"bristolType":7,"confidence":0.87}}

tests/fixtures/vision-corpus/manifest.json

@@ -131,6 +131,22 @@
       "expectedOutcome": "fail_closed",
       "expectedReason": "out_of_range_or_missing_fields",
       "providerContent": "{\"isStool\":true,\"bristolType\":9,\"color\":null,\"confidence\":0.9,\"imageQuality\":\"good\",\"observations\":\"Form read, colour not.\"}"
+    },
+    {
+      "id": "poor-quality-confident",
+      "caseClass": "blur",
+      "file": "blur-low-detail.png",
+      "bytes": 21598,
+      "sha256": "17000163662a42fd434bb2b2428d9e5a2156da08cbc82210e41dfc6fa7e24852",
+      "width": 640,
+      "height": 480,
+      "format": "png",
+      "synthetic": true,
+      "license": "CC0-1.0",
+      "provenance": "The same synthetic motion-blur fixture that blur-low-detail replays, replayed again with a confident provider answer; drawn deterministically by scripts/build_vision_corpus.py, no camera, no human subject, no third-party content.",
+      "expectedOutcome": "abstained",
+      "expectedReason": "low_quality",
+      "providerContent": "{\"isStool\":true,\"bristolType\":4,\"color\":\"brown\",\"confidence\":0.94,\"imageQuality\":\"poor\",\"observations\":\"Form barely visible through motion blur.\"}"
     }
   ]
 }

tests/portability.acceptance.mjs

@@ -0,0 +1,131 @@
+import { chromium } from 'playwright';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+
+// Issue #35 — a backup is the person's own record, and it has to keep working as the app's AI
+// provenance fields evolve. This drives the real app in a browser: a version 1 file is upgraded and
+// says so, a file from a newer Timmy is refused without touching the ledger, the export carries the
+// contribution receipts, and a log saved from a confirmed AI suggestion comes back saying that.
+//
+// The image used below is the committed synthetic Type 4 fixture; no real photo is involved.
+const browser = await chromium.launch({ headless: true });
+const context = await browser.newContext({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 2, serviceWorkers: 'block' });
+const page = await context.newPage();
+const errors = [];
+page.on('console', message => { if (message.type() === 'error') errors.push(message.text()); });
+page.on('pageerror', error => errors.push(error.message));
+page.on('dialog', dialog => dialog.accept());
+
+const suggestionBody = {
+  status: 'suggestion', isStool: true, bristolType: 4, color: 'brown', confidence: 0.83,
+  imageQuality: 'good', observations: 'Smooth, formed appearance.',
+  warning: 'Visual suggestion only. Confirm it yourself; this is not a diagnosis.',
+};
+await page.route('**/api/vision-status', route => route.fulfill({
+  status: 200, contentType: 'application/json',
+  body: JSON.stringify({ enabled: true, profile: 'selfhost', processor: 'self-hosted', model: 'SmolVLM2-2.2B-Instruct', providerReady: true, modelSeen: true }),
+}));
+await page.route('**/api/analyze', route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(suggestionBody) }));
+await page.route('**/api/agent/status', route => route.fulfill({
+  status: 200, contentType: 'application/json',
+  body: JSON.stringify({ enabled: true, configured: false, authenticated: false, mode: 'local-fallback' }),
+}));
+
+await page.goto('http://127.0.0.1:4173', { waitUntil: 'networkidle' });
+await page.evaluate(() => localStorage.clear());
+await page.reload({ waitUntil: 'networkidle' });
+
+const basePath = () => page.evaluate(() => document.querySelector('meta[name="timmy-base-path"]')?.content || '/');
+const storeKey = async suffix => `timmy:${await basePath()}:${suffix}`;
+const readStore = async suffix => {
+  const raw = await page.evaluate(key => localStorage.getItem(key), await storeKey(suffix));
+  return raw === null ? null : JSON.parse(raw);
+};
+// The privacy view sits behind the journal's settings row, exactly as a person reaches it.
+const openPrivacy = async () => {
+  await page.locator('[data-view="calendar"]').first().click();
+  await page.locator('.settings-row[data-view="privacy"]').first().click();
+  await page.locator('#export').waitFor();
+};
+const importBackup = async (name, text) => {
+  await page.locator('#import').setInputFiles({ name, mimeType: 'application/json', buffer: Buffer.from(text) });
+  await page.waitForTimeout(350);
+};
+
+const legacyBackup = JSON.stringify({
+  product: 'Timmy the Talking Turd',
+  schemaVersion: 1,
+  exportedAt: '2026-08-01T09:00:00.000Z',
+  entries: [
+    { id: 'legacy-1', occurredAt: '2026-08-01T08:00:00.000Z', bristolType: 3, color: 'brown', urgency: 1, discomfort: 0, note: 'synthetic', photoDataUrl: '', symptoms: {} },
+    { id: 'legacy-2', occurredAt: '2026-08-02T08:00:00.000Z', bristolType: 6, color: 'brown', urgency: 2, discomfort: 1, note: '', photoDataUrl: '', symptoms: {} },
+  ],
+});
+
+// 1. A version 1 backup is imported, upgraded, and says which version it came from.
+await openPrivacy();
+await importBackup('timmy-backup-v1.json', legacyBackup);
+const upgraded = await readStore('ledger-v1');
+assert.equal(upgraded.length, 2, 'the version 1 backup must restore both logs');
+await page.locator('[data-portability-notice]').waitFor();
+const noticeText = (await page.locator('[data-portability-notice]').innerText()).trim();
+assert.match(noticeText, /version 1/i, 'the notice must name the version the file came from');
+assert.match(noticeText, /upgraded/i, 'the notice must say the backup was upgraded');
+assert.equal(await page.locator('[data-portability-notice]').getAttribute('data-portability-version'), '1');
+assert.equal(upgraded[0].provenance, null, 'a pre-provenance backup must not acquire a source it never recorded');
+assert.equal(upgraded[0].bristolType, 3, 'the confirmed form must survive the upgrade');
+
+// 2. A file from a newer Timmy is refused, and the ledger it would have replaced stays exactly as it was.
+const before = JSON.stringify(await readStore('ledger-v1'));
+await importBackup('timmy-backup-v3.json', JSON.stringify({ product: 'Timmy the Talking Turd', schemaVersion: 3, entries: [{ id: 'future', bristolType: 7 }] }));
+await page.locator('[data-portability-error]').waitFor();
+const errorText = (await page.locator('[data-portability-error]').innerText()).trim();
+assert.match(errorText, /newer version of Timmy/i);
+assert.equal(JSON.stringify(await readStore('ledger-v1')), before, 'a refused import must not change the ledger');
+
+// 3. A log saved from a confirmed AI suggestion records that provenance, and the export states it.
+await page.locator('[data-view="home"]').first().click();
+await page.locator('[data-scan]').first().click();
+await page.getByText(/Self-hosted model ready/i).waitFor();
+await page.locator('#gallery-photo').setInputFiles('tests/fixtures/synthetic-type4.jpg');
+await page.locator('#ai-consent').check();
+await page.locator('#analyze-photo').click();
+await page.locator('#use-suggestion').waitFor();
+await page.locator('#use-suggestion').click();
+await page.locator('[data-provenance="confirmed"]').waitFor();
+await page.locator('#next').click();
+await page.locator('#next').click();
+await page.locator('#save').click();
+await page.getByText(/Private log saved|Saved/).waitFor();
+const savedLedger = await readStore('ledger-v1');
+const assisted = savedLedger.find(entry => entry.id !== 'legacy-1' && entry.id !== 'legacy-2');
+assert.ok(assisted, 'the saved log must be in the ledger');
+assert.equal(assisted.provenance?.source, 'ai-confirmed', 'a confirmed AI suggestion must be recorded on the saved log');
+assert.equal(assisted.provenance?.suggestedBristolType, 4);
+assert.equal(assisted.provenance?.model, 'SmolVLM2-2.2B-Instruct');
+
+// 4. Export carries the current version, the entries, and the contribution receipts — and nothing else.
+await openPrivacy();
+const [download] = await Promise.all([page.waitForEvent('download'), page.locator('#export').click()]);
+const exported = JSON.parse(await readFile(await download.path(), 'utf8'));
+assert.equal(exported.schemaVersion, 2);
+assert.equal(exported.entries.length, 3);
+assert.deepEqual(exported.contributions, [], 'nothing was contributed, so no receipt may appear');
+assert.equal(exported.entries.find(entry => entry.id === assisted.id).provenance.source, 'ai-confirmed');
+
+// 5. Round trip: the export restores into a cleared browser with provenance intact.
+const exportedText = JSON.stringify(exported);
+await page.evaluate(() => localStorage.clear());
+await page.reload({ waitUntil: 'networkidle' });
+await openPrivacy();
+await importBackup('timmy-backup-v2.json', exportedText);
+const roundTripped = await readStore('ledger-v1');
+assert.equal(roundTripped.length, 3);
+const restoredAssisted = roundTripped.find(entry => entry.id === assisted.id);
+assert.deepEqual(restoredAssisted.provenance, assisted.provenance, 'provenance must survive a round trip');
+await page.locator('[data-portability-notice]').waitFor();
+assert.match((await page.locator('[data-portability-notice]').innerText()).trim(), /version 2/i);
+
+assert.deepEqual(errors, [], `browser errors: ${errors.join(' | ')}`);
+await browser.close();
+console.log(JSON.stringify({ ok: true, scenes: ['v1-upgrade', 'future-refused', 'provenance-recorded', 'export-v2', 'round-trip'] }));

tests/portability.test.js

@@ -0,0 +1,152 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { LEDGER_EXPORT_VERSION, LEDGER_IMPORT_LIMITS, exportLedger, exportLedgerBackup, importLedger, importLedgerBackup } from '../src/domain.js';
+
+// Issue #35 — a backup is the person's own record. Provenance is part of what they own: a log that
+// was saved from a confirmed or corrected AI suggestion has to come back out of the export saying
+// exactly that, instead of silently reverting to looking like a manual entry.
+const confirmedByUser = {
+  id: 'demo-corrected',
+  occurredAt: '2026-08-18T10:00:00.000Z',
+  bristolType: 2,
+  color: 'brown',
+  urgency: 1,
+  discomfort: 0,
+  note: 'synthetic',
+  photoDataUrl: '',
+  symptoms: {},
+  provenance: {
+    source: 'ai-corrected',
+    model: 'SmolVLM2-2.2B-Instruct',
+    suggestedBristolType: 4,
+    suggestedColor: 'brown',
+    confirmedAt: '2026-08-18T09:59:00.000Z',
+  },
+};
+
+test('an export stamps the current schema version and keeps confirmed AI provenance', () => {
+  const parsed = JSON.parse(exportLedger([confirmedByUser], '2026-08-18T11:00:00.000Z'));
+
+  assert.equal(LEDGER_EXPORT_VERSION, 2);
+  assert.equal(parsed.schemaVersion, 2);
+  assert.equal(parsed.entries.length, 1);
+  assert.deepEqual(parsed.entries[0].provenance, confirmedByUser.provenance);
+  assert.equal(parsed.entries[0].bristolType, 2, 'the corrected value stays the saved value');
+});
+
+// A version 1 file was written before entries recorded provenance. Importing it must restore the
+// confirmed values and say plainly that this backup predates provenance, rather than inventing a
+// source for logs that never had one.
+const legacyBackup = JSON.stringify({
+  product: 'Timmy the Talking Turd',
+  schemaVersion: 1,
+  exportedAt: '2026-08-01T09:00:00.000Z',
+  entries: [
+    {
+      id: 'legacy-entry',
+      occurredAt: '2026-08-01T08:00:00.000Z',
+      bristolType: 4,
+      color: 'brown',
+      urgency: 2,
+      discomfort: 1,
+      note: '',
+      photoDataUrl: '',
+      symptoms: { blood: false },
+    },
+  ],
+});
+
+test('a version 1 backup imports its confirmed values and reports the upgrade', () => {
+  const result = importLedgerBackup(legacyBackup);
+
+  assert.equal(result.fromVersion, 1);
+  assert.equal(result.migrated, true);
+  assert.equal(result.entries.length, 1);
+  assert.equal(result.entries[0].id, 'legacy-entry');
+  assert.equal(result.entries[0].bristolType, 4);
+  assert.equal(result.entries[0].provenance, null, 'a pre-provenance backup must not be given a source it never recorded');
+  assert.match(result.notices.join(' '), /version 1/i);
+  assert.match(result.notices.join(' '), /upgraded/i);
+  // The import screen already reports what was restored; a notice that restates the count renders as
+  // a duplicated sentence on screen, so the upgrade notice must only describe the upgrade.
+  assert.doesNotMatch(result.notices.join(' '), /Restored \d+ logs?/);
+  assert.equal(importLedger(legacyBackup).length, 1, 'the plain entry import still works');
+});
+
+// A training contribution receipt is user-owned data too. A backup that restored the journal but
+// dropped the receipts would tell someone their opt-in never happened, so version 2 carries them —
+// with the withdrawal tombstone intact and nothing else copied out of the device.
+const withdrawnReceipt = {
+  contributionId: 'contrib-1',
+  entryId: 'demo-corrected',
+  consentVersion: 'training-consent-v1',
+  consentedAt: '2026-08-18T10:05:00.000Z',
+  labels: { bristolType: 2, color: 'brown' },
+  state: 'withdrawn',
+  withdrawnAt: '2026-08-18T10:30:00.000Z',
+  artifacts: [
+    { artifact: 'raw-image', contributionId: 'contrib-1', state: 'withdrawn' },
+    { artifact: 'confirmed-label', contributionId: 'contrib-1', state: 'withdrawn' },
+  ],
+  // A crafted file must not be able to hand a credential back to the app.
+  agentAccessCode: 'leak-me-please',
+};
+
+test('a backup carries contribution receipts and their tombstones without copying secrets', () => {
+  const text = exportLedgerBackup({
+    entries: [{ ...confirmedByUser, agentAccessCode: 'leak-me-please' }],
+    contributions: [withdrawnReceipt],
+    exportedAt: '2026-08-18T12:00:00.000Z',
+  });
+  const parsed = JSON.parse(text);
+
+  assert.equal(parsed.schemaVersion, 2);
+  assert.equal(parsed.contributions.length, 1);
+  assert.equal(parsed.contributions[0].state, 'withdrawn');
+  assert.deepEqual(parsed.contributions[0].artifacts, withdrawnReceipt.artifacts);
+  assert.equal(parsed.entries[0].agentAccessCode, undefined);
+  assert.doesNotMatch(text, /leak-me-please/);
+
+  const restored = importLedgerBackup(text);
+  assert.equal(restored.migrated, false);
+  assert.equal(restored.fromVersion, 2);
+  assert.equal(restored.contributions.length, 1);
+  assert.equal(restored.contributions[0].contributionId, 'contrib-1');
+  assert.equal(restored.contributions[0].state, 'withdrawn');
+  assert.deepEqual(restored.contributions[0].artifacts, withdrawnReceipt.artifacts);
+  assert.equal(restored.contributions[0].agentAccessCode, undefined);
+  assert.deepEqual(restored.entries[0].provenance, confirmedByUser.provenance);
+});
+
+test('a backup from a newer Timmy is refused with an instruction instead of a guess', () => {
+  const future = JSON.stringify({ product: 'Timmy the Talking Turd', schemaVersion: 3, entries: [], contributions: [] });
+
+  assert.throws(() => importLedgerBackup(future), /newer version of Timmy/i);
+});
+
+test('a file that is not a readable Timmy backup is refused', () => {
+  assert.throws(() => importLedgerBackup('{not json'), /not readable JSON/i);
+  assert.throws(() => importLedgerBackup(JSON.stringify({ hello: 'world' })), /not a supported Timmy backup/i);
+  assert.throws(() => importLedgerBackup(JSON.stringify({ schemaVersion: 0, entries: [] })), /not a supported Timmy backup/i);
+});
+
+test('an oversized backup or one with too many logs is refused before anything is imported', () => {
+  const huge = `{"schemaVersion":2,"entries":[]}${' '.repeat(LEDGER_IMPORT_LIMITS.maxTextLength)}`;
+  assert.throws(() => importLedgerBackup(huge), /too large/i);
+
+  const many = { schemaVersion: 2, entries: Array.from({ length: LEDGER_IMPORT_LIMITS.maxEntries + 1 }, () => ({ id: 'x', bristolType: 4 })) };
+  assert.throws(() => importLedgerBackup(JSON.stringify(many)), /more logs than Timmy will import/i);
+});
+
+test('an unreadable contribution receipt is skipped and reported, never silently dropped', () => {
+  const text = JSON.stringify({
+    schemaVersion: 2,
+    entries: [{ id: 'kept', bristolType: 4 }],
+    contributions: [{ entryId: 'kept', state: 'queued-local' }],
+  });
+  const result = importLedgerBackup(text);
+
+  assert.equal(result.contributions.length, 0);
+  assert.match(result.notices.join(' '), /could not be read and was skipped/i);
+});

tests/product-decisions.test.js

@@ -21,6 +21,15 @@ test('product decision record fixes the AI boundary and release authority', asyn
   assert.match(decision, /\.\.\/research\/SELF-HOSTED-STOOL-VISION\.md/);
 });
 
+test('the decision record keeps training contribution as its own versioned, withdrawable consent', async () => {
+  const decision = await readFile(decisionPath, 'utf8');
+
+  assert.match(decision, /### Training contribution consent/);
+  assert.match(decision, /never a training contribution/i);
+  assert.match(decision, /withdrawal keeps a tombstone naming every derived artifact by contribution id/i);
+  assert.match(decision, /does not transmit a contribution until the corpus pipeline and privacy copy are reviewed/i);
+});
+
 test('Hermes deployment installs a checked-in non-diagnostic workspace policy', async () => {
   const [policy, readme] = await Promise.all([readFile(policyPath, 'utf8'), readFile(readmePath, 'utf8')]);
   assert.match(policy, /never diagnose/i);
@@ -28,3 +37,16 @@ test('Hermes deployment installs a checked-in non-diagnostic workspace policy',
   assert.match(policy, /explicit user intent and confirmation/i);
   assert.match(readme, /install -m 600 docs\/TIMMY-AGENT-POLICY\.md/);
 });
+
+test('the decision record keeps a backup versioned and refuses files it cannot read', async () => {
+  const decision = await readFile(decisionPath, 'utf8');
+  const readme = await readFile(readmePath, 'utf8');
+
+  assert.match(decision, /### Backup portability and entry provenance/);
+  assert.match(decision, /schema version/i);
+  assert.match(decision, /upgraded on import/i);
+  assert.match(decision, /newer version is refused/i);
+  assert.match(decision, /a refused import leaves the ledger unchanged/i);
+  assert.match(decision, /provenance is stored on the confirmed log/i);
+  assert.match(readme, /versioned JSON backup/i);
+});

tests/production-runbook.test.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Tests for the production topology, secrets, backup, and rollback runbook.
+
+A runbook is only worth reading if its commands are the ones the tools actually accept, so this
+suite parses every documented ``python3 scripts/...`` command out of the markdown and checks each
+flag against the real CLI help. It also fails if the document starts carrying a real secret, or if
+it keeps claiming the server holds no journal after ``server.mjs`` starts writing one.
+"""
+from __future__ import annotations
+
+import re
+import shlex
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+RUNBOOK = ROOT / "docs" / "PRODUCTION-RUNBOOK.md"
+SERVER = ROOT / "server.mjs"
+BACKUP = ROOT / "scripts" / "operator_backup.py"
+
+FENCE = re.compile(r"```bash\n(.*?)```", re.S)
+SECRET_ASSIGNMENT = re.compile(
+    r"(?i)(?:token|secret|password|passwd|api[_-]?key|salt)\s*=\s*(?!<|\$|\"|\'|\.\.\.)[^\s`\"']{6,}"
+)
+
+
+def text() -> str:
+    return RUNBOOK.read_text(encoding="utf-8")
+
+
+def sections() -> dict[str, str]:
+    body = text()
+    headings = list(re.finditer(r"^## (.+)$", body, re.M))
+    out: dict[str, str] = {}
+    for index, match in enumerate(headings):
+        end = headings[index + 1].start() if index + 1 < len(headings) else len(body)
+        out[match.group(1).strip().lower()] = body[match.end():end]
+    return out
+
+
+def documented_commands() -> list[str]:
+    commands: list[str] = []
+    for block in FENCE.findall(text()):
+        for line in block.splitlines():
+            line = line.strip()
+            if line.startswith("python3 scripts/"):
+                commands.append(line)
+    return commands
+
+
+def help_text(script: str, subcommand: str | None) -> str:
+    argv = [sys.executable, script] + ([subcommand] if subcommand else []) + ["--help"]
+    result = subprocess.run(argv, cwd=ROOT, capture_output=True, text=True)
+    assert result.returncode == 0, f"{' '.join(argv)} failed: {result.stderr}"
+    return result.stdout
+
+
+class ProductionRunbookTests(unittest.TestCase):
+    def test_runbook_covers_topology_network_boundaries_secrets_backup_restore_and_rollback(self) -> None:
+        self.assertTrue(RUNBOOK.is_file(), "docs/PRODUCTION-RUNBOOK.md must exist")
+        titles = sections().keys()
+        for required in ("topology", "network boundaries", "secrets", "backup", "restore", "rollback"):
+            self.assertTrue(
+                any(title.startswith(required) for title in titles),
+                f"runbook is missing a '{required}' section; found {sorted(titles)}",
+            )
+
+    def test_backup_section_names_what_is_never_archived_and_why(self) -> None:
+        backup = next(body for title, body in sections().items() if title.startswith("backup"))
+        self.assertIn("scripts/operator_backup.py", backup)
+        for required in ("model weights", "transient inference", "secret", "tombstone"):
+            self.assertIn(required, backup.lower(), f"backup section must name {required}")
+        self.assertRegex(backup, r"manifest\.jsonl")
+
+    def test_every_documented_script_command_is_accepted_by_the_real_cli(self) -> None:
+        commands = documented_commands()
+        self.assertGreaterEqual(len(commands), 4, f"expected documented commands, found {commands}")
+        for command in commands:
+            with self.subTest(command=command):
+                tokens = shlex.split(command)
+                script = tokens[1]
+                rest = tokens[2:]
+                subcommand = rest[0] if rest and not rest[0].startswith("-") else None
+                combined = help_text(script, subcommand) + help_text(script, None)
+                for token in rest:
+                    if token.startswith("--"):
+                        self.assertIn(token, combined, f"{script} does not accept {token}")
+                for token in rest[1:]:
+                    if not token.startswith("--"):
+                        continue
+
+    def test_documented_backup_commands_are_the_ones_the_tool_runs(self) -> None:
+        commands = " ".join(documented_commands())
+        for flag in ("--source", "--archive", "--manifest", "--target"):
+            self.assertIn(flag, commands, f"the runbook must show the real {flag} flag")
+        self.assertIn("verify", commands)
+        self.assertIn("restore", commands)
+
+    def test_rollback_is_documented_as_a_tested_fixture_path_and_a_human_gated_live_drill(self) -> None:
+        rollback = next(body for title, body in sections().items() if title.startswith("rollback"))
+        self.assertIn("scripts/deploy_staging.py rollback", rollback)
+        self.assertRegex(rollback.lower(), r"human[- ]gate")
+        self.assertIn("#53", rollback)
+        self.assertIn("tests/staging-deploy.test.py", rollback)
+        # The live drill must be explicit about not being run by automation (wrapped lines are fine).
+        self.assertRegex(
+            rollback.lower(),
+            r"(?s)not .{0,80}automatically|does not run .{0,80}automatically",
+            "the runbook must say the live drill is not run automatically",
+        )
+
+    def test_network_boundaries_match_how_the_server_and_worker_actually_bind(self) -> None:
+        server = SERVER.read_text(encoding="utf-8")
+        # The app's own default is not loopback, so the runbook must say the deployment sets it.
+        self.assertRegex(server, r"HOST\|\|'0\.0\.0\.0'")
+        staging_env = (ROOT / "deploy" / "timmy-staging.env.example").read_text(encoding="utf-8")
+        self.assertIn("HOST=127.0.0.1", staging_env)
+        worker = (ROOT / "deploy" / "worker" / "run_worker_container.sh").read_text(encoding="utf-8")
+        self.assertIn("Refusing to publish the worker outside loopback", worker)
+
+        boundaries = next(body for title, body in sections().items() if title.startswith("network boundaries"))
+        self.assertIn("0.0.0.0", boundaries, "the runbook must name the app's real default bind address")
+        self.assertIn("HOST=127.0.0.1", boundaries)
+        self.assertIn("deploy/timmy-staging.env.example", boundaries)
+        self.assertIn("loopback", boundaries.lower())
+        self.assertIn("8080", boundaries)
+
+    def test_runbook_carries_no_literal_secret_values(self) -> None:
+        findings = [match.group(0) for match in SECRET_ASSIGNMENT.finditer(text())]
+        self.assertEqual(findings, [], f"runbook looks like it contains a real secret: {findings}")
+        self.assertIn("mode-600", text())
+        self.assertIn("never commit", text().lower())
+
+    def test_runbook_claims_match_a_stateless_server(self) -> None:
+        server = SERVER.read_text(encoding="utf-8")
+        for call in ("writeFile", "appendFile", "createWriteStream", "mkdirSync"):
+            self.assertNotIn(call, server, "server.mjs started persisting data; the runbook's data-lifetime claim must be updated")
+        body = text().lower()
+        self.assertIn("no server-side copy of the journal", body)
+        self.assertIn("/api/healthz", body)
+        # The health probe is allowed to report readiness, never configuration or secrets.
+        health = re.search(r"'/api/healthz'[^\n]*", server)
+        self.assertIsNotNone(health, "server.mjs must serve /api/healthz")
+        health_text = health.group(0) if health else ""
+        for forbidden in ("token", "secret", "env:", "password"):
+            self.assertNotIn(forbidden, health_text.lower())
+        # The response may report readiness only, so a new field is a deliberate decision.
+        for field in ("ok", "release", "commit", "visionEnabled", "agentEnabled"):
+            self.assertIn(field, health_text)
+
+    def test_backup_tool_is_gated_by_its_own_suite(self) -> None:
+        package = (ROOT / "package.json").read_text(encoding="utf-8")
+        self.assertIn("tests/backup-restore.test.py", package)
+        self.assertIn("tests/production-runbook.test.py", package)
+        self.assertTrue(BACKUP.is_file())
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/release-demo.test.js

@@ -289,6 +289,14 @@ test('release demo visibly exercises the corpus refusal paths instead of only th
   assert.match(demo, /A non-stool photo gets a refusal, never a guess/);
   assert.match(demo, /Unreadable visual fields abstain as well/);
   assert.match(demo, /An out-of-range answer fails closed/);
+  // Issue #32's quality gate: a confident answer about a low-quality photo must abstain on camera.
+  assert.match(demo, /corpusCase\('poor-quality-confident'\)/);
+  assert.match(demo, /tests\/fixtures\/vision-corpus\/blur-low-detail\.png/);
+  assert.match(demo, /too blurry or poorly lit/);
+  assert.match(demo, /must not prefill a form, however confident the reply looked/);
+  assert.match(demo, /A confident reply about a blurry photo still abstains/);
+  assert.match(builder, /A confident reply about a blurry photo still abstains — photo quality is part of the policy, not just confidence/);
+  assert.match(builder, /"abstention_quality_gate": "passed"/);
   assert.match(demo, /no real photos in the corpus|no real photos in the recording/);
   // The refusal copy the user sees is gated on camera, so a release cannot drop it silently.
   assert.match(builder, /An out-of-range answer fails closed/);
@@ -325,3 +333,228 @@ test('release demo shows readiness waiting for the loaded pinned model before AI
   // The caption is a required release gate, so the scene cannot be dropped silently.
   assert.match(builder, /Reachable is not loaded: no AI control, no consent, and no upload until the pinned model is resident/);
 });
+
+test('release demo shows the training contribution as a separate opt-in receipt that can be withdrawn', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+  const app = await readFile(new URL('../app.js', import.meta.url), 'utf8');
+
+  // Issue #24: the recording must show the opt-in section, the consent gate, and the withdrawal.
+  assert.match(demo, /\[data-training-consent\]/);
+  assert.match(demo, /\[data-contribute-entry="demo-wipe"\]/);
+  assert.match(demo, /#training-consent-check/);
+  assert.match(demo, /#contribute-confirm/);
+  assert.match(demo, /\[data-contribution-state="queued-local"\]/);
+  assert.match(demo, /data-withdraw=/);
+  assert.match(demo, /\[data-withdrawn-artifacts\]/);
+  assert.match(demo, /training-consent-v1/);
+  // Every claim is measured in the browser before the caption that makes it.
+  assert.match(demo, /a journal save must not queue a training contribution/);
+  assert.match(demo, /the contribute control must stay disabled until the terms are accepted/);
+  assert.match(demo, /no receipt may exist before explicit consent/);
+  assert.match(demo, /a receipt must never copy the photo bytes/);
+  assert.match(demo, /every derived artifact must be addressed by contribution id/);
+  assert.match(demo, /delete-all must clear the contribution receipts as well/);
+  // The controls are the app's own, not demo-only scaffolding.
+  assert.match(app, /data-training-consent/);
+  assert.match(app, /data-contribution-queued-count/);
+  assert.match(app, /id="training-consent-check"/);
+  assert.match(app, /id="contribute-confirm" disabled/);
+  assert.match(app, /data-withdraw=/);
+  // The captions and the gate key are required, so a later release cannot drop the scenes silently.
+  assert.match(builder, /Training contribution is off by default: a saved log is never training data/);
+  assert.match(builder, /The consent version and the receipt are on screen before the contribute button works/);
+  assert.match(builder, /Withdrawing keeps a tombstone naming every derived artifact by contribution ID/);
+  assert.match(builder, /"training_contribution_consent": "passed"/);
+  assert.match(builder, /"test:training-contribution"/);
+});
+
+test('release demo shows a versioned backup, an upgraded older file, and a refused newer one', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+  const app = await readFile(new URL('../app.js', import.meta.url), 'utf8');
+
+  // Issue #35: the recording must export the real file, import an older version, refuse a newer one,
+  // and reopen a restored log so its provenance is on screen — not merely described.
+  assert.match(demo, /waitForEvent\('download'\)/);
+  assert.match(demo, /exportedBackup\.schemaVersion !== 2/);
+  assert.match(demo, /the backup must carry the withdrawn receipt as a tombstone/);
+  assert.match(demo, /\[data-portability-notice\]\[data-portability-version="1"\]/);
+  assert.match(demo, /\[data-portability-error\]/);
+  assert.match(demo, /\[data-entry-provenance="ai-corrected"\]/);
+  // Every claim is measured before the caption that makes it.
+  assert.match(demo, /an older backup must be reported as upgraded/);
+  assert.match(demo, /a refused import must not change the ledger it would have replaced/);
+  assert.match(demo, /a restored log must still show that it began as a corrected AI suggestion/);
+  // The controls belong to the app, and the provenance line is its own rendering.
+  assert.match(app, /id="export"/);
+  assert.match(app, /data-portability-notice/);
+  assert.match(app, /data-entry-provenance=/);
+  // Captions and the gate key are required, so a later release cannot drop the scenes silently.
+  assert.match(builder, /A backup is versioned, and it carries the withdrawn receipt as a tombstone rather than silence/);
+  assert.match(builder, /An older backup is upgraded on import, and the notice says which version the file came from/);
+  assert.match(builder, /A file from a newer Timmy is refused with an instruction, and the ledger it would have replaced is untouched/);
+  assert.match(builder, /A restored log still says it began as an AI suggestion you corrected — provenance is part of the record/);
+  assert.match(builder, /"portable_backup_restore": "passed"/);
+  assert.match(builder, /"test:portability"/);
+});
+
+test('the builder refuses to gate or record a release against a foreign server', async () => {
+  const builder = await readFile(builderPath, 'utf8');
+
+  // A leftover checkout answering on the acceptance port once satisfied every flow and the demo,
+  // so the release described a tree that was not the commit under test. The builder must refuse a
+  // live listener before it starts, then prove the served bytes are this tree's before any gate.
+  assert.match(builder, /def assert_port_free/);
+  assert.match(builder, /assert_port_free\("127\.0\.0\.1", 4173\)/);
+  assert.match(builder, /def assert_served_tree/);
+  assert.match(builder, /assert_served_tree\(tree, "127\.0\.0\.1", 4173\)/);
+  const identityCheck = builder.indexOf('assert_served_tree(tree, "127.0.0.1", 4173)');
+  const firstFlow = builder.indexOf('run(["npm", "run", "test:ui"]');
+  assert.ok(identityCheck > 0, 'the served-tree check must be present');
+  assert.ok(firstFlow > identityCheck, 'the served-tree check must run before the first acceptance flow');
+});
+
+test('release demo replays the calibration harness against synthetic predictions instead of narrating the gates', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+
+  // Issue #29: the gate math is only proven by running the real harness on camera.
+  assert.match(demo, /scripts\/calibration_report\.py/);
+  assert.match(demo, /tests\/fixtures\/calibration\/predictions\.jsonl/);
+  assert.match(demo, /tests\/fixtures\/calibration\/predictions-go\.jsonl/);
+  assert.match(demo, /tests\/fixtures\/calibration\/predictions-leaky\.jsonl/);
+  // All three verdict paths are exercised: blocked, passing, and refused before scoring.
+  assert.match(demo, /the synthetic candidate fixtures must block the release/);
+  assert.match(demo, /the engineered fixture must prove the passing branch/);
+  assert.match(demo, /a leaked corpus must be refused before scoring/);
+  // The card is drawn from the report the run wrote, and gated for readability like the corpus card.
+  assert.match(demo, /id: 'calibration-report'/);
+  assert.match(demo, /Calibration card is not fully readable on screen/);
+  assert.match(demo, /the card must show the macro-F1 the harness measured/);
+  assert.match(demo, /the card must show the refusal the leaked corpus earned/);
+  // The scores are labelled as invented: a synthetic fixture is not a measurement of any model.
+  assert.match(demo, /invented scores, not measurements of any model/);
+  assert.match(demo, /synthetic predictions · no model was measured/);
+  // The scene cannot be dropped silently: its captions are release gates.
+  assert.match(builder, /The calibration harness is a command-line release gate, not a screen in the app/);
+  assert.match(builder, /Every score on this card is invented to exercise the arithmetic/);
+  assert.match(builder, /Each candidate is scored on test at a threshold chosen on validation only/);
+  assert.match(builder, /One contributor spread across two splits is refused before anything is scored/);
+});
+
+test('release demo runs the blind review tool in its enforced order instead of describing it', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+
+  // Issue #26: the review tool is a CLI. The scene runs the real commands and shows their output.
+  assert.match(demo, /scripts\/review_corpus\.py/);
+  assert.match(demo, /tests\/fixtures\/synthetic-type4\.jpg/);
+  // Blindness is proven by the refusal, not by a caption: reveal is attempted before any commit.
+  assert.match(demo, /stays hidden until a review is committed/);
+  // The reviewer's labels are committed before the model answer is shown, and both are recorded.
+  assert.match(demo, /--reviewer'?,? ?'reviewer-a'/);
+  assert.match(demo, /disagreeFields/);
+  // A second reader adjudicates; the review it resolves must still be in the ledger afterwards.
+  assert.match(demo, /'adjudicate'/);
+  assert.match(demo, /resolvesRecord/);
+  // A withdrawn contribution leaves the queue, the training set, and the review path entirely.
+  assert.match(demo, /was withdrawn and cannot be reviewed/);
+  assert.match(demo, /id: 'review-audit'/);
+  assert.match(demo, /Review card is not fully readable on screen/);
+  assert.match(demo, /the card must show the model answer the run revealed/);
+  assert.match(demo, /the card must show the withdrawn refusal the run earned/);
+  // The card must not claim a model measured anything: the answer file is a synthetic fixture.
+  assert.match(demo, /synthetic answer file · no model was measured/);
+
+  // The scene is a release gate, so a later release cannot quietly drop it.
+  assert.match(builder, /tests\/corpus-review\.test\.py/);
+  assert.match(builder, /"reviewer_adjudication_blind": "passed"/);
+  assert.match(builder, /The review tool is a command line, not a screen in the app/);
+  assert.match(builder, /The queue shows the proposal and hides the model answer; revealing it is refused until a reviewer commits/);
+  assert.match(builder, /The model said Type 6 and the reviewer said Type 5: the disagreement is recorded, not smoothed over/);
+  assert.match(builder, /Withdrawing the contribution empties the queue and the training set, and the tool refuses to review it at all/);
+});
+
+test('release demo publishes the dataset card from a manifest it builds on camera', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+
+  // Issue #27: the card is a generated artifact. The scene builds a real corpus with the real ingest
+  // commands, publishes the card, and re-checks the committed page, instead of describing a document.
+  assert.match(demo, /scripts\/dataset_card\.py/);
+  assert.match(demo, /id: 'dataset-card'/);
+  assert.match(demo, /Dataset card is not fully readable on screen/);
+  // The split policy is proven by the refusal, not by a caption: a leaked contributor is attempted.
+  assert.match(demo, /leaks across/);
+  assert.match(demo, /the generator must refuse a corpus that leaks one contributor across splits/);
+  // The pending facts must be visibly pending, and the committed page must be the generator's output.
+  assert.match(demo, /pending/);
+  assert.match(demo, /the committed dataset card must be the generator's own output/);
+  assert.match(demo, /docs\/DATASET_CARD\.md/);
+  // Nothing on the card may claim a model measured or labelled anything here.
+  assert.match(demo, /no model labelled anything here/);
+
+  // The scene and its guide are release gates, so a later release cannot drop them silently.
+  assert.match(builder, /The dataset card is generated from the corpus manifest, so no count on it is typed by hand/);
+  assert.match(builder, /One contributor's photos stay in one split: a corpus that leaks a person across splits is refused/);
+  assert.match(builder, /Devices, contexts, and licenses stay pending until the pipeline collects them/);
+  assert.match(builder, /tests\/dataset-card\.test\.py/);
+  assert.match(builder, /"dataset_card_generated": "passed"/);
+  assert.match(builder, /scripts\/dataset_card\.py/);
+});
+
+test('release demo runs the operator backup and restore on synthetic records instead of describing it', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+
+  // Issue #39: the backup is a CLI, so the recording runs the real tool and shows what it stored,
+  // what it refused, and what the restore returned.
+  assert.match(demo, /scripts\/operator_backup\.py/);
+  assert.match(demo, /'backup', '--source'/);
+  assert.match(demo, /'verify', '--archive'/);
+  assert.match(demo, /'restore', '--archive'/);
+  assert.match(demo, /id: 'production-backup'/);
+  assert.match(demo, /Production backup card is not fully readable on screen/);
+  // The exclusions are proven by the run, not asserted by a caption: the decoys are real files.
+  assert.match(demo, /model-weights/);
+  assert.match(demo, /transient-inference/);
+  assert.match(demo, /must not archive the weight shard or a transient inference upload/);
+  // A restore must return the append-only manifest byte for byte, tombstone included.
+  assert.match(demo, /must return the same records, tombstone included/);
+
+  assert.match(demo, /The operator backup is a command line, not a screen in the app/);
+  assert.match(demo, /Model weights and transient inference images are refused by name, and every skipped path is listed with its reason/);
+  assert.match(demo, /Verify re-hashes every stored member against the manifest, and the restore only starts once that check passes/);
+  assert.match(demo, /A restore returns the same records, including the withdrawal tombstone a trainer must never lose/);
+
+  // The scene is a release gate, and the tool's own suite runs before the release exists.
+  assert.match(demo, /process\.env\.TIMMY_DEMO_URL \|\| 'http:\/\/127\.0\.0\.1:4173'/);
+  assert.match(builder, /tests\/backup-restore\.test\.py/);
+  assert.match(builder, /tests\/production-runbook\.test\.py/);
+  assert.match(builder, /"production_backup_restore": "passed"/);
+  assert.match(builder, /"production_runbook_commands": "passed"/);
+  assert.match(builder, /The operator backup is a command line, not a screen in the app/);
+  assert.match(builder, /A restore returns the same records, including the withdrawal tombstone a trainer must never lose/);
+});
+
+test('release demo runs the RC attack suite on camera and prints the verdict it derived', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+
+  // Issue #40 turns hostile uploads into a release gate. The scene must run the real suite, not
+  // describe it, and the card must show the verdict the suite derived rather than a flattering one.
+  assert.match(demo, /scripts\/security_attack_suite\.mjs', '--json'/);
+  assert.match(demo, /SECURITY ATTACK SUITE/);
+  assert.match(demo, /Every hostile upload on screen went at the real server, and the worker behind it counted every call it received/);
+  assert.match(demo, /A failing case is a finding the release job has to see, so the card prints the verdict the suite derived/);
+  assert.match(demo, /The gate blocks RC approval on any P0 case that reached the worker/);
+  assert.match(demo, /securityReport\.verdict/);
+  assert.match(demo, /securityCardProof/);
+  // The finding must name where the fix lives instead of implying the boundary is already safe.
+  assert.match(demo, /Refusing bytes by their content is the fix in review, not a claim this video makes/);
+  // Each case row prints the fields it actually observed. A guarantee that the card never renders
+  // `http undefined` (a case with no status) or the bare status again (a case with no provider calls).
+  assert.match(demo, /'refused' in observed/);
+  assert.match(demo, /'providerTextLeaked' in observed/);
+  assert.doesNotMatch(demo, /http \$\{observed\.status\} · worker \$\{observed\.providerCalls\}`/);
+});

tests/release-security-gate.test.js

@@ -0,0 +1,104 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { buildReport, containsImageBytes, evaluateCase, latencyPercentiles, redactImageBytes, releaseVerdict } from '../src/release-security-gate.js';
+
+test('latency percentiles use nearest-rank so p95 is an observed sample, not an interpolation', () => {
+  const samples = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
+  assert.deepEqual(latencyPercentiles(samples), { count: 10, p50: 50, p95: 100, max: 100 });
+});
+
+// A case is a promise the suite makes before it runs: this input must land here, and the provider
+// must (or must not) see exactly this many calls. The verdict is derived, never typed.
+const polyglot = {
+  id: 'ingress-polyglot-html',
+  severity: 'P0',
+  expected: { status: 400, providerCalls: 0 },
+  observed: { status: 400, providerCalls: 0 },
+};
+
+test('a case whose observation matches its expectation passes', () => {
+  assert.equal(evaluateCase(polyglot).status, 'pass');
+});
+
+test('a case that reached the provider is a failure that names the field that broke', () => {
+  const result = evaluateCase({ ...polyglot, observed: { status: 200, providerCalls: 1 } });
+  assert.equal(result.status, 'fail');
+  assert.match(result.mismatch, /status 400 expected, observed 200/);
+  assert.match(result.mismatch, /providerCalls 0 expected, observed 1/);
+});
+
+test('a P0 failure blocks the release, and a P1 failure only holds it', () => {
+  const leaked = { ...polyglot, observed: { status: 200, providerCalls: 1 } };
+  const blocked = releaseVerdict({ cases: [leaked, { ...polyglot, id: 'flood', severity: 'P1', observed: { status: 200, providerCalls: 12 } }] });
+  assert.equal(blocked.verdict, 'BLOCKED');
+  assert.deepEqual(blocked.blocking.map(item => item.id), ['ingress-polyglot-html']);
+  assert.deepEqual(blocked.holds.map(item => item.id), ['flood']);
+});
+
+test('a suite with no failures is a GO, and counts say how many cases were proven', () => {
+  const verdict = releaseVerdict({ cases: [polyglot] });
+  assert.equal(verdict.verdict, 'GO');
+  assert.deepEqual(verdict.blocking, []);
+  assert.equal(verdict.proven, 1);
+});
+
+test('a required category that no case exercised blocks the release instead of passing by omission', () => {
+  const deletion = { id: 'deletion-withdrawal', severity: 'P0', surface: 'out-of-surface', evidence: 'tests/training-contribution.test.js', evidenceVerified: false };
+  const verdict = releaseVerdict({ cases: [polyglot, deletion] });
+  assert.equal(verdict.verdict, 'BLOCKED');
+  assert.deepEqual(verdict.unproven.map(item => item.id), ['deletion-withdrawal']);
+});
+
+test('coverage borrowed from another test file only counts once the runner verified that file exists', () => {
+  const verified = { id: 'deletion-withdrawal', severity: 'P0', surface: 'out-of-surface', evidence: 'tests/training-contribution.test.js', evidenceVerified: true };
+  const verdict = releaseVerdict({ cases: [polyglot, verified] });
+  assert.equal(verdict.verdict, 'GO');
+  assert.deepEqual(verdict.coveredElsewhere, ['deletion-withdrawal']);
+});
+
+// The report and the server log are shipped as release evidence. Neither may carry a photo.
+const JPEG_DATA_URI = 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAFQABAQAAAAAAAAAAAAAAAAAAAAn/xAAUEAEAAAAAAAAAAAAAAAAAAAAJ/9oACAEBAAA/AKp//9k=';
+
+test('a data URI or a long base64 run is recognised as image bytes', () => {
+  assert.equal(containsImageBytes(`posted ${JPEG_DATA_URI} to the worker`), true);
+  assert.equal(containsImageBytes('chunk ' + 'A'.repeat(64) + 'yQ'.repeat(200)), true);
+});
+
+test('ordinary log lines, hex digests, and short tokens are not image bytes', () => {
+  assert.equal(containsImageBytes('Timmy is listening on http://127.0.0.1:4173 · vision configured · Hermes locked and ready'), false);
+  assert.equal(containsImageBytes('sha256 ' + 'a1b2c3d4'.repeat(8)), false);
+  assert.equal(containsImageBytes('case ingress-polyglot-html observed status 200'), false);
+});
+
+test('redaction removes the bytes and keeps the sentence around them honest', () => {
+  const redacted = redactImageBytes(`provider received ${JPEG_DATA_URI} at 12:01`);
+  assert.equal(containsImageBytes(redacted), false);
+  assert.match(redacted, /\[redacted image bytes\]/);
+  assert.match(redacted, /^provider received .* at 12:01$/);
+});
+
+test('the report carries the verdict, the target it ran against, and the measured load numbers', () => {
+  const report = buildReport({
+    generatedAt: '2026-10-30T10:48:00.000Z',
+    target: { baseUrl: 'http://127.0.0.1:4173', provider: 'stub counting worker' },
+    cases: [polyglot],
+    load: { requests: 8, errors: 0, abstentions: 8, p50: 12, p95: 40, max: 40 },
+  });
+  assert.equal(report.schema, 'timmy-rc-security-attack/1');
+  assert.equal(report.verdict, 'GO');
+  assert.equal(report.generatedAt, '2026-10-30T10:48:00.000Z');
+  assert.equal(report.target.provider, 'stub counting worker');
+  assert.equal(report.load.p95, 40);
+  assert.equal(containsImageBytes(JSON.stringify(report)), false);
+});
+
+test('a case that quotes a response body cannot smuggle the photo into the report', () => {
+  const report = buildReport({
+    generatedAt: '2026-10-30T10:48:00.000Z',
+    target: { baseUrl: 'http://127.0.0.1:4173', provider: 'stub' },
+    cases: [{ ...polyglot, observed: { status: 400, providerCalls: 0 }, snippet: `refused ${JPEG_DATA_URI}` }],
+    load: null,
+  });
+  assert.equal(containsImageBytes(JSON.stringify(report)), false);
+  assert.match(JSON.stringify(report), /redacted image bytes/);
+});

tests/security-attack.acceptance.mjs

@@ -0,0 +1,89 @@
+// Acceptance: the RC attack suite must drive the real server and then tell the truth about what it
+// saw. Nothing here trusts the runner's own summary line: every case status is re-derived from the
+// recorded observation with the same rule the release gate uses, and the report is scanned for photo
+// bytes. If the suite ever marks a case pass while observing a mismatch, this test fails.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { containsImageBytes, evaluateCase, releaseVerdict } from '../src/release-security-gate.js';
+
+const repoRoot = new URL('..', import.meta.url).pathname;
+
+async function runSuite() {
+  const directory = await mkdtemp(join(tmpdir(), 'timmy-rc-attack-'));
+  const reportPath = join(directory, 'report.json');
+  const run = await new Promise(resolve => {
+    execFile(process.execPath, ['scripts/security_attack_suite.mjs', '--json', reportPath], {
+      cwd: repoRoot,
+      timeout: 180_000,
+    }, (error, stdout, stderr) => resolve({
+      code: error?.code ?? 0,
+      stdout,
+      stderr,
+    }));
+  });
+  const report = JSON.parse(await readFile(reportPath, 'utf8'));
+  await rm(directory, { recursive: true, force: true });
+  return { run, report };
+}
+
+const suite = await runSuite();
+const byId = new Map(suite.report.cases.map(item => [item.id, item]));
+
+test('the suite exits non-zero exactly when its own verdict blocks the release', () => {
+  assert.ok([0, 1].includes(suite.run.code), `unexpected exit ${suite.run.code}: ${suite.run.stderr}`);
+  assert.match(suite.run.stdout, new RegExp(`VERDICT: ${suite.report.verdict}`));
+  assert.equal(suite.run.code, suite.report.verdict === 'BLOCKED' ? 1 : 0);
+});
+
+test('every reported case status is re-derivable from the observation it recorded', () => {
+  for (const item of suite.report.cases.filter(entry => entry.surface !== 'out-of-surface')) {
+    const derived = evaluateCase(item);
+    assert.equal(item.status, derived.status, `${item.id} claims ${item.status} but observed ${JSON.stringify(item.observed)} against ${JSON.stringify(item.expected)}`);
+  }
+  assert.equal(suite.report.verdict, releaseVerdict({ cases: suite.report.cases }).verdict);
+});
+
+test('the suite covers the abuse classes the ticket names, not a convenient subset', () => {
+  const required = ['oversized', 'polyglot', 'malformed', 'flood', 'log', 'deletion', 'replay'];
+  const categories = new Set(suite.report.cases.map(item => item.category));
+  for (const category of required) assert.ok(categories.has(category), `no case covers ${category}`);
+  assert.ok(suite.report.cases.length >= 8, `only ${suite.report.cases.length} cases ran`);
+});
+
+test('a request without consent is refused and the worker is never called', () => {
+  const consent = byId.get('consent-required');
+  assert.equal(consent.observed.status, 400);
+  assert.equal(consent.observed.providerCalls, 0);
+  assert.equal(consent.status, 'pass');
+});
+
+test('an oversized body is refused before any provider work', () => {
+  const oversized = byId.get('ingress-oversized-body');
+  assert.equal(oversized.observed.status, 413);
+  assert.equal(oversized.observed.providerCalls, 0);
+});
+
+test('a provider answer that breaks the schema fails closed without quoting the provider', () => {
+  const malformed = byId.get('model-output-malformed');
+  assert.equal(malformed.observed.status, 503);
+  assert.equal(malformed.observed.providerTextLeaked, false);
+  assert.ok(!JSON.stringify(malformed).includes('garbage-completion-token'), 'the report must not quote the provider');
+});
+
+test('the captured server log and the report itself carry no photo bytes', () => {
+  assert.equal(byId.get('log-leak-scan').observed.imageBytesInLog, false);
+  assert.equal(containsImageBytes(JSON.stringify(suite.report)), false);
+});
+
+test('the load phase recorded percentiles, errors, and abstentions without any image body', () => {
+  const load = suite.report.load;
+  assert.ok(load.requests >= 8, `only ${load.requests} load requests ran`);
+  assert.equal(typeof load.p50, 'number');
+  assert.equal(typeof load.p95, 'number');
+  assert.equal(typeof load.abstentions, 'number');
+  assert.equal(containsImageBytes(JSON.stringify(load)), false);
+});

tests/service-worker-runtime.test.js

@@ -44,11 +44,14 @@ async function dispatchFetch(handler, request) {
 }
 
 test('root activation deletes only its obsolete Timmy caches including the legacy v4 cache', async () => {
+  // The backup/provenance release (issue #35) changes app.js and src/domain.js, so the shell cache
+  // must advance or an installed client keeps serving the old ledger code indefinitely.
   const { listeners, deleted } = loadWorker({
     cacheKeys: [
       'timmy-shell-v4',
       'timmy-shell:/:v4',
       'timmy-shell:/:v5',
+      'timmy-shell:/:v6',
       'timmy-shell:/timmy-staging/:v4',
       'sibling-shared-origin-cache',
     ],
@@ -56,7 +59,7 @@ test('root activation deletes only its obsolete Timmy caches including the legac
 
   await dispatchExtendable(listeners.get('activate'));
 
-  assert.deepEqual(deleted.sort(), ['timmy-shell-v4', 'timmy-shell:/:v4']);
+  assert.deepEqual(deleted.sort(), ['timmy-shell-v4', 'timmy-shell:/:v4', 'timmy-shell:/:v5']);
 });
 
 test('offline shell lookup uses only the current named cache', async () => {

tests/training-contribution.acceptance.mjs

@@ -0,0 +1,120 @@
+import { chromium } from 'playwright';
+import assert from 'node:assert/strict';
+import { mkdir } from 'node:fs/promises';
+
+// Issue #24 — contributing a confirmed photo to training is a separate opt-in. This runs the real
+// app in a browser: a journal save must record nothing, the consent sheet must show the version and
+// the receipt before the button works, and a withdrawal must leave a tombstone naming every derived
+// artifact. The photo is a synthetic 1x1 PNG constant; no real photo is loaded.
+const SYNTHETIC_PHOTO = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+ip1sAAAAASUVORK5CYII=';
+const CONSENT_VERSION = 'training-consent-v1';
+
+await mkdir('artifacts', { recursive: true });
+const browser = await chromium.launch({ headless: true });
+const context = await browser.newContext({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 2, serviceWorkers: 'block' });
+const page = await context.newPage();
+const errors = [];
+page.on('console', message => { if (message.type() === 'error') errors.push(message.text()); });
+page.on('pageerror', error => errors.push(error.message));
+page.on('dialog', dialog => dialog.accept());
+await page.goto('http://127.0.0.1:4173', { waitUntil: 'networkidle' });
+await page.evaluate(() => localStorage.clear());
+await page.reload({ waitUntil: 'networkidle' });
+
+const basePath = () => page.evaluate(() => document.querySelector('meta[name="timmy-base-path"]')?.content || '/');
+const storeKey = async suffix => `timmy:${await basePath()}:${suffix}`;
+const readStore = async suffix => {
+  const key = await storeKey(suffix);
+  const raw = await page.evaluate(storeKeys => localStorage.getItem(storeKeys), key);
+  return raw === null ? null : JSON.parse(raw);
+};
+const writeStore = async (suffix, value) => {
+  const key = await storeKey(suffix);
+  await page.evaluate(({ storeKey: k, payload }) => localStorage.setItem(k, payload), { storeKey: key, payload: JSON.stringify(value) });
+};
+
+// 1. Saving a log through the app's own flow contributes nothing.
+await page.locator('[data-log]').first().click();
+await page.locator('[data-type="4"]').click();
+await page.locator('#next').click();
+await page.locator('#note').fill('Synthetic test entry');
+await page.locator('#next').click();
+await page.locator('#save').click();
+await page.getByText(/Private log saved/).waitFor();
+assert.equal(await readStore('training-contributions-v1'), null, 'a journal save must not record a training contribution');
+
+// 2. Seed one photo-bearing log and one text-only log for the privacy section.
+const seeded = [
+  {
+    id: 'demo-photo', occurredAt: new Date(Date.now() - 86400000).toISOString(), bristolType: 4,
+    color: 'brown', urgency: 1, discomfort: 0, note: 'synthetic', photoDataUrl: SYNTHETIC_PHOTO, symptoms: {},
+  },
+  {
+    id: 'demo-text', occurredAt: new Date(Date.now() - 2 * 86400000).toISOString(), bristolType: 3,
+    color: 'brown', urgency: 2, discomfort: 1, note: 'no photo here', photoDataUrl: '', symptoms: {},
+  },
+];
+await writeStore('ledger-v1', seeded);
+await page.reload({ waitUntil: 'networkidle' });
+await page.locator('[data-view="calendar"]').first().click();
+await page.locator('[data-view="privacy"]').first().click();
+await page.getByText(/Your poop\. Your phone\./i).waitFor();
+
+const section = page.locator('[data-training-consent]');
+assert.equal(await section.count(), 1, 'the privacy page must offer the training contribution section');
+assert.match(await section.innerText(), /off by default/i);
+assert.match(await section.innerText(), /nothing is uploaded/i);
+assert.equal((await page.locator('[data-contribution-consent-version]').innerText()).trim(), CONSENT_VERSION);
+assert.equal((await page.locator('[data-contribution-queued-count]').innerText()).trim(), '0');
+assert.equal(await page.locator('[data-contribute-entry="demo-photo"]').count(), 1, 'a saved photo may be contributed');
+assert.equal(await page.locator('[data-contribute-entry="demo-text"]').count(), 0, 'a log without photo bytes cannot be contributed');
+
+// 3. The receipt and the consent version are on screen before the confirm control works.
+await page.locator('[data-contribute-entry="demo-photo"]').click();
+const sheet = page.locator('[data-contribution-sheet]');
+await sheet.waitFor();
+assert.match(await sheet.innerText(), new RegExp(CONSENT_VERSION));
+const receiptId = (await page.locator('[data-receipt-id]').innerText()).trim();
+assert.ok(receiptId.length > 0, 'the receipt shown before consent must name its own id');
+assert.match(await sheet.innerText(), /photo bytes/i);
+assert.match(await sheet.innerText(), /note text/i);
+assert.equal(await page.locator('#contribute-confirm').isDisabled(), true, 'the contribution button stays disabled until the terms are accepted');
+assert.equal(await readStore('training-contributions-v1'), null, 'no receipt may be written before explicit consent');
+await page.screenshot({ path: 'artifacts/training-contribution-consent-mobile.png' });
+
+// 4. Consent records exactly one queued-on-device receipt.
+await page.locator('#training-consent-check').check();
+await page.locator('#contribute-confirm').click();
+await page.getByText(/Queued on this device/i).first().waitFor();
+const queued = await readStore('training-contributions-v1');
+assert.equal(queued.length, 1);
+assert.equal(queued[0].entryId, 'demo-photo');
+assert.equal(queued[0].consentVersion, CONSENT_VERSION);
+assert.equal(queued[0].contributionId, receiptId);
+assert.equal(queued[0].state, 'queued-local');
+assert.equal(JSON.stringify(queued).includes('data:image'), false, 'the receipt must not copy photo bytes');
+assert.equal(JSON.stringify(queued).includes('synthetic'), false, 'the receipt must not copy note text');
+await page.locator('[data-contribution-state="queued-local"]').waitFor();
+assert.equal((await page.locator('[data-contribution-queued-count]').innerText()).trim(), '1');
+await page.screenshot({ path: 'artifacts/training-contribution-queued-mobile.png' });
+
+// 5. Withdrawal leaves a tombstone that addresses every derived artifact by contribution id.
+await page.locator(`[data-withdraw="${receiptId}"]`).click();
+await page.locator('[data-contribution-state="withdrawn"]').waitFor();
+const withdrawn = await readStore('training-contributions-v1');
+assert.equal(withdrawn.length, 1, 'the withdrawn receipt is kept as a tombstone, not silently erased');
+assert.equal(withdrawn[0].state, 'withdrawn');
+assert.ok(withdrawn[0].withdrawnAt, 'the tombstone records when the withdrawal happened');
+assert.deepEqual(withdrawn[0].artifacts.map(artifact => artifact.artifact).sort(), ['confirmed-label', 'raw-image']);
+for (const artifact of withdrawn[0].artifacts) {
+  assert.equal(artifact.contributionId, receiptId);
+  assert.equal(artifact.state, 'withdrawn');
+}
+assert.match(await page.locator('[data-withdrawn-artifacts]').innerText(), /raw image/i);
+assert.equal((await page.locator('[data-contribution-queued-count]').innerText()).trim(), '0');
+await page.screenshot({ path: 'artifacts/training-contribution-withdrawn-mobile.png' });
+
+assert.deepEqual(errors, []);
+await context.close();
+await browser.close();
+console.log('PASS training contribution stays opt-in, shows its consent version before commit, and withdrawal names every derived artifact');

tests/training-contribution.test.js

@@ -0,0 +1,161 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  TRAINING_CONSENT_VERSION,
+  addContribution,
+  consentTerms,
+  contributionEligibility,
+  contributionForEntry,
+  defaultContributionState,
+  derivedArtifacts,
+  receiptPreview,
+  withdrawContribution,
+} from '../src/training-contribution.js';
+
+// Issue #24 — contributing a photo to Timmy's training corpus is a separate decision from saving
+// a log. Nothing here is transmitted: the receipt is what a person could carry to a corpus pipeline
+// later, and the withdrawal tombstone is what names the artifacts a deletion has to reach.
+
+const PHOTO = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+ip1sAAAAASUVORK5CYII=';
+const entry = (overrides = {}) => ({
+  id: 'log-1',
+  occurredAt: '2026-10-14T07:20:00.000Z',
+  bristolType: 4,
+  color: 'brown',
+  urgency: 1,
+  discomfort: 0,
+  note: 'after lunch',
+  photoDataUrl: PHOTO,
+  symptoms: { blood: false },
+  ...overrides,
+});
+const preview = (target = entry(), id = 'contrib-1') => receiptPreview(target, {
+  contributionId: id,
+  consentedAt: '2026-10-21T10:00:00.000Z',
+});
+
+test('saving a journal entry contributes nothing by default', () => {
+  assert.deepEqual(defaultContributionState(), { optedIn: false, receipt: null });
+});
+
+test('an entry with no saved photo bytes cannot be contributed', () => {
+  const unavailable = contributionEligibility(entry({ photoDataUrl: '' }));
+  assert.equal(unavailable.eligible, false);
+  assert.match(unavailable.reason, /no saved photo/i);
+  assert.equal(contributionEligibility(entry()).eligible, true);
+});
+
+test('the consent terms name the version and what is never shared', () => {
+  const terms = consentTerms();
+
+  assert.equal(terms.version, TRAINING_CONSENT_VERSION);
+  assert.match(terms.version, /^training-consent-/);
+  assert.ok(terms.includes.some(item => /photo/i.test(item)));
+  assert.ok(terms.excludes.some(item => /note/i.test(item)));
+  assert.ok(terms.excludes.some(item => /symptom/i.test(item)));
+  // This build is honest about transport: a receipt is queued on the device, not uploaded.
+  assert.match(terms.transport, /nothing is uploaded/i);
+});
+
+test('the receipt shown before consent carries the version, the id, and no free text from the log', () => {
+  const receipt = preview();
+
+  assert.equal(receipt.contributionId, 'contrib-1');
+  assert.equal(receipt.consentVersion, TRAINING_CONSENT_VERSION);
+  assert.equal(receipt.consentedAt, '2026-10-21T10:00:00.000Z');
+  assert.deepEqual(receipt.labels, { bristolType: 4, color: 'brown' });
+  assert.equal(receipt.state, 'queued-local');
+  // The confirmed note and symptom flags stay in the journal; they are not part of a contribution.
+  const serialized = JSON.stringify(receipt);
+  assert.equal(serialized.includes('after lunch'), false);
+  assert.equal(serialized.includes('"blood"'), false);
+  assert.equal(serialized.includes('data:image'), false);
+});
+
+test('a receipt cannot be recorded without the current consent version', () => {
+  assert.throws(
+    () => addContribution([], { ...preview(), consentVersion: 'training-consent-v0' }),
+    /consent version/i,
+  );
+});
+
+test('recording a contribution returns a new list and leaves the ledger it was given alone', () => {
+  const before = [];
+  const after = addContribution(before, preview());
+
+  assert.equal(before.length, 0);
+  assert.equal(after.length, 1);
+  assert.equal(after[0].contributionId, 'contrib-1');
+  assert.equal(contributionForEntry(after, 'log-1')?.contributionId, 'contrib-1');
+});
+
+test('the same log cannot be contributed twice while its receipt is still active', () => {
+  const first = addContribution([], preview());
+  const second = addContribution(first, preview(entry(), 'contrib-2'));
+
+  assert.equal(second.length, 1);
+  assert.equal(second[0].contributionId, 'contrib-1');
+});
+
+test('withdrawal keeps a tombstone that names every derived artifact by contribution id', () => {
+  const contributions = addContribution([], preview());
+  const artifacts = derivedArtifacts(contributions[0]);
+
+  const { contributions: after, tombstone } = withdrawContribution(
+    contributions, 'contrib-1', '2026-10-21T11:00:00.000Z',
+  );
+
+  assert.equal(after[0].state, 'withdrawn');
+  assert.equal(after[0].withdrawnAt, '2026-10-21T11:00:00.000Z');
+  assert.equal(tombstone.contributionId, 'contrib-1');
+  assert.deepEqual(
+    tombstone.artifacts.map(artifact => artifact.artifact).sort(),
+    artifacts.map(artifact => artifact.artifact).sort(),
+  );
+  for (const artifact of tombstone.artifacts) {
+    assert.equal(artifact.contributionId, 'contrib-1');
+    assert.equal(artifact.state, 'withdrawn');
+  }
+});
+
+test('the derived artifacts are the image bytes and the confirmed label, addressed by contribution id', () => {
+  const artifacts = derivedArtifacts(preview());
+
+  assert.deepEqual(artifacts.map(artifact => artifact.artifact).sort(), ['confirmed-label', 'raw-image']);
+  for (const artifact of artifacts) {
+    assert.equal(artifact.contributionId, 'contrib-1');
+    assert.equal(artifact.state, 'active');
+  }
+});
+
+test('withdrawing one contribution never touches another receipt', () => {
+  const list = [
+    ...addContribution([], preview()),
+    ...addContribution([], preview(entry({ id: 'log-2' }), 'contrib-2')),
+  ];
+
+  const { contributions: after } = withdrawContribution(list, 'contrib-1', '2026-10-21T11:00:00.000Z');
+
+  assert.equal(after.find(item => item.contributionId === 'contrib-1').state, 'withdrawn');
+  assert.equal(after.find(item => item.contributionId === 'contrib-2').state, 'queued-local');
+});
+
+test('withdrawing an unknown contribution id changes nothing and reports no tombstone', () => {
+  const list = addContribution([], preview());
+  const { contributions: after, tombstone } = withdrawContribution(list, 'missing', '2026-10-21T11:00:00.000Z');
+
+  assert.equal(after, list);
+  assert.equal(tombstone, null);
+});
+
+test('a withdrawn log can be contributed again under a fresh receipt', () => {
+  const { contributions: withdrawn } = withdrawContribution(
+    addContribution([], preview()), 'contrib-1', '2026-10-21T11:00:00.000Z',
+  );
+
+  const again = addContribution(withdrawn, preview(entry(), 'contrib-2'));
+
+  assert.equal(again.length, 2);
+  assert.equal(contributionForEntry(again, 'log-1').contributionId, 'contrib-2');
+  assert.equal(contributionForEntry(again, 'log-1').state, 'queued-local');
+});

tests/training-ingest.test.js

@@ -14,6 +14,7 @@ test('training ingest strips metadata, derives a pseudonymous split, and writes
       '--output-dir', out,
       '--subject-id', 'subject-123',
       '--consent-version', 'research-v1',
+      '--contribution-id', '6f1d0c9e-2c4a-4f3b-9d1e-8a7b6c5d4e3f',
       '--bristol-type', '4',
       '--color', 'brown',
       '--quality', 'good',
@@ -45,10 +46,11 @@ test('training ingest rejects records without explicit consent or human review',
     '--input', 'tests/fixtures/synthetic-type4.jpg',
     '--output-dir', '/tmp/should-not-exist-timmy',
     '--subject-id', 'subject-123',
+    '--contribution-id', '6f1d0c9e-2c4a-4f3b-9d1e-8a7b6c5d4e3f',
     '--bristol-type', '4',
     '--color', 'brown',
     '--quality', 'good',
   ], { encoding: 'utf8', env: { ...process.env, TIMMY_DATASET_SALT: 'test-only-salt' } });
   assert.notEqual(run.status, 0);
-  assert.match(run.stderr, /consent|reviewer/i);
+  assert.match(run.stderr, /consent/i);
 });