feat: explainable longitudinal pattern summaries with cited records (#34)

The home insight card now reports the confirmed-log count and form
groupings for a window, every line names the exact confirmed records it
was built from, and following a citation opens those records. A window
below the minimum states that it is too sparse instead of describing a
trend, and a window with both firm and loose logs says it is mixed rather
than picking a winner. No line explains a cause, rules on food, or offers
a health verdict.

- src/summary.js: window filtering, insufficient-data guard, per-form
  lines, mixed-pattern line, boundary copy, record citations
- app.js: explainable home card plus a pattern-source sheet listing the
  cited records
- tests/summary.test.js, tests/pattern-summary.acceptance.mjs: unit and
  real-browser coverage, gated in CI and the release builder
- scripts/record_release_demo.mjs: fictional multi-day sample logs,
  citation follow-through, and the sparse-window refusal on camera

.dockerignore

@@ -0,0 +1,12 @@
+# The worker image is built from source; weights, releases, and private data never enter it.
+.git/
+node_modules/
+models/
+*.gguf
+artifacts/
+video/
+research/source-pages/
+__pycache__/
+*.pyc
+.env
+.env.*

.gitea/workflows/quality.yml

@@ -55,6 +55,9 @@ jobs:
           npm run test:manual-fallback
           npm run test:provisional
           npm run test:followup
+          npm run test:vision-refusal
+          npm run test:worker-readiness
+          npm run test:pattern-summary
       - name: Dependency audit
         run: npm audit --audit-level=high
       - name: Syntax checks

README.md

@@ -97,6 +97,7 @@ npm run test:ui       # server required on port 4173
 npm run test:photo    # mocked positive suggestion through the real browser UX
 npm run test:sleek   # simplified 390x844 shell + free-text Hermes chat
 npm run test:manual-fallback  # vision-offline manual path + in-session draft recovery
+npm run test:vision-refusal   # corpus refusals through a real server and a real browser
 npm audit --audit-level=high
 ```
 
@@ -115,8 +116,10 @@ npm audit --audit-level=high
 - Red-flag symptom escalation
 - A short user-reported follow-up after a hard/lumpy (Bristol 1–2) log — difficulty passing, soreness, visible blood, truly black/tarry versus dark brown, and hydration. Mild reports get concise non-diagnostic self-care that never claims a photo ruled out bleeding; a confirmed red flag sets the same deterministic escalation the manual checkboxes use
 - Manual fallback that never depends on AI: when the vision worker is offline or disabled, no AI or consent control is offered and manual Bristol entry stays one action away
+- 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
 - Local browser ledger, calendar, pattern summary, JSON portability, 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
 
 ## What is deliberately not faked

app.js

@@ -4,6 +4,7 @@ import { createDraft, draftNotice, isDraftDirty } from './src/draft.js';
 import { changeVisualField, confirmSuggestion, createSuggestionState, provenanceCopy } from './src/suggestion.js';
 import { HARD_STOOL_QUESTIONS, createFollowUpAnswers, evaluateHardStoolFollowUp, needsHardStoolFollowUp } from './src/followup.js';
 import { visionReadiness } from './src/vision-readiness.js';
+import { buildPatternSummary } from './src/summary.js';
 
 const runtimeConfig = {
   basePath: document.querySelector('meta[name="timmy-base-path"]')?.content || '/',
@@ -96,6 +97,7 @@ function bindGlobal(){
   document.querySelectorAll('[data-view]').forEach(btn=>btn.onclick=()=>{view=btn.dataset.view;render()});
   document.querySelectorAll('[data-log]').forEach(btn=>btn.onclick=openLogger);
   document.querySelectorAll('[data-scan]').forEach(btn=>btn.onclick=openPhotoFirst);
+  document.querySelectorAll('[data-statement-link]').forEach(btn=>btn.onclick=()=>showPatternRecords(btn.dataset.statementLink));
 }
 
 function recentList(limit=5){
@@ -105,9 +107,35 @@ function recentList(limit=5){
 function thisWeek(){const now=Date.now(),week=7*864e5;return entries.filter(e=>now-new Date(e.occurredAt).getTime()<week).length}
 function currentStreak(){const dates=new Set(entries.map(e=>e.occurredAt.slice(0,10)));let n=0,d=new Date();while(dates.has(d.toISOString().slice(0,10))){n++;d.setDate(d.getDate()-1)}return n}
 
+// Issue #34: the home insight card is explainable. Every line says which confirmed records it was
+// built from, following a citation shows exactly those records, and a sparse window says so
+// instead of describing a trend the data cannot support.
+function patternSummaryCard(){
+  const summary=buildPatternSummary(entries);
+  const logs=`${summary.records.length} confirmed log${summary.records.length===1?'':'s'}`;
+  const lines=summary.insufficient
+    ? `<p class="fine" data-summary-insufficient>${esc(summary.copy)}</p>`
+    : `<ul class="pattern-statements">${summary.statements.map(statement=>`<li data-statement="${statement.id}" data-records="${statement.entryIds.length}">${esc(statement.text)} <button class="pattern-link" data-statement-link="${statement.id}">${statement.entryIds.length} record${statement.entryIds.length===1?'':'s'} ›</button></li>`).join('')}</ul>`;
+  return `<section class="section"><div class="insight-card pattern-card" data-pattern-summary role="group" aria-label="Explainable pattern summary"><div class="timmy-orb"><img src="${appPath('assets/timmy.svg')}" alt=""></div><div><span class="eyebrow">Timmy noticed</span><p class="pattern-window" data-summary-window>${esc(summary.window.label)} · ${logs}</p>${lines}<p class="fine pattern-boundary">${esc(summary.boundary)}</p></div></div></section>`;
+}
+function showPatternRecords(statementId){
+  const summary=buildPatternSummary(entries);
+  const statement=summary.statements.find(item=>item.id===statementId);
+  if(!statement)return;
+  const byId=new Map(summary.records.map(record=>[record.id,record]));
+  const rows=statement.entryIds.map(id=>byId.get(id)).filter(Boolean)
+    .map(record=>`<article class="entry" data-summary-record data-entry-id="${esc(record.id)}"><div class="type-dot">T${record.bristolType}</div><div><strong>${formatDate(record.occurredAt)}</strong><span>Type ${record.bristolType} · ${esc(record.bucket)}</span></div></article>`).join('');
+  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="pattern-records-title"><div class="sheet-handle"></div><div class="sheet-header"><div><span class="eyebrow">Pattern source</span><h2 id="pattern-records-title">${esc(statement.text)}</h2></div><button class="icon-btn" id="pattern-records-close" aria-label="Close">×</button></div><div data-summary-records><p class="fine">These are the confirmed logs this line was built from.</p><div class="entries-card">${rows}</div><p class="fine">Window: ${esc(summary.window.label)}. Change or delete any of these logs and this line changes with them.</p></div></section>`;
+  document.body.append(wrap);
+  document.querySelector('#pattern-records-close').onclick=()=>wrap.remove();
+  wrap.onclick=e=>{if(e.target===wrap)wrap.remove()};
+}
+
 function home(){
   const latest=entries.slice().sort((a,b)=>new Date(b.occurredAt)-new Date(a.occurredAt))[0];
-  shell(`<main class="home-main"><section class="hero sleek-hero"><span class="eyebrow">Your intelligent pooping pal</span><h1>Log it.<br>Learn the pattern.</h1><p class="lead">Start with a photo. Timmy suggests visible form and color; you review everything before it is saved.</p><button class="capture-cta btn-primary" data-scan><span class="capture-icon" aria-hidden="true">◉</span><span><strong>Start photo log</strong><small>Private, guided, about 10 seconds</small></span><i aria-hidden="true">→</i></button><button class="text-action" data-log>Log manually instead</button></section><section class="glance" aria-label="Journal at a glance"><div><strong>${thisWeek()}</strong><span>this week</span></div><i></i><div><strong>${currentStreak()}</strong><span>day streak</span></div><i></i><div><strong>${entries.length}</strong><span>all logs</span></div></section><section class="section"><div class="insight-card"><div class="timmy-orb"><img src="${appPath('assets/timmy.svg')}" alt=""></div><div><span class="eyebrow">Timmy noticed</span><p>${esc(buildTimmySummary(entries))}</p></div></div></section><section class="section recent-section"><div class="section-head"><div><span class="eyebrow">Latest</span><h2>${latest?'Recent log':'Ready when you are'}</h2></div>${latest?'<button class="text-action compact" data-view="calendar">View journal</button>':''}</div>${latest?`<div class="latest-card"><div class="type-dot">T${latest.bristolType}</div><div><strong>${formatDate(latest.occurredAt)}</strong><span>${esc(latest.color)} · ${bucketForBristolType(latest.bristolType)}</span></div><span class="chevron">›</span></div>`:'<p class="fine">One quick, confirmed entry is enough to begin seeing your pattern.</p>'}</section></main>`);
+  shell(`<main class="home-main"><section class="hero sleek-hero"><span class="eyebrow">Your intelligent pooping pal</span><h1>Log it.<br>Learn the pattern.</h1><p class="lead">Start with a photo. Timmy suggests visible form and color; you review everything before it is saved.</p><button class="capture-cta btn-primary" data-scan><span class="capture-icon" aria-hidden="true">◉</span><span><strong>Start photo log</strong><small>Private, guided, about 10 seconds</small></span><i aria-hidden="true">→</i></button><button class="text-action" data-log>Log manually instead</button></section><section class="glance" aria-label="Journal at a glance"><div><strong>${thisWeek()}</strong><span>this week</span></div><i></i><div><strong>${currentStreak()}</strong><span>day streak</span></div><i></i><div><strong>${entries.length}</strong><span>all logs</span></div></section>${patternSummaryCard()}<section class="section recent-section"><div class="section-head"><div><span class="eyebrow">Latest</span><h2>${latest?'Recent log':'Ready when you are'}</h2></div>${latest?'<button class="text-action compact" data-view="calendar">View journal</button>':''}</div>${latest?`<div class="latest-card"><div class="type-dot">T${latest.bristolType}</div><div><strong>${formatDate(latest.occurredAt)}</strong><span>${esc(latest.color)} · ${bucketForBristolType(latest.bristolType)}</span></div><span class="chevron">›</span></div>`:'<p class="fine">One quick, confirmed entry is enough to begin seeing your pattern.</p>'}</section></main>`);
 }
 
 function calendar(){
@@ -176,6 +204,9 @@ async function loadVisionStatus(){
 }
 function visionStatusHtml(){
  if(!visionStatus)return '<div class="model-status checking">◌ Checking the vision worker…</div>';
+ // Reachable is not loaded (#15): a worker answering before its pinned model is loaded must not be
+ // shown as ready, because the AI controls are withheld until the model can actually answer.
+ if(visionStatus.providerReady&&visionStatus.modelSeen!==true)return '<div class="model-status loading">◌ Vision worker up · the model is not loaded yet · manual logging is available</div>';
  if(visionStatus.profile==='selfhost'&&visionStatus.providerReady)return `<div class="model-status ready">● Self-hosted model ready · ${esc(visionStatus.model)}</div>`;
  if(visionStatus.providerReady)return `<div class="model-status ready">● Vision provider ready · ${esc(visionStatus.model)}</div>`;
  return '<div class="model-status offline">○ Vision worker offline · manual logging is still available</div>';
@@ -192,7 +223,7 @@ function showPhotoFirst(mode='pick',error=''){
  photoFirstMode=mode;
  document.querySelector('.sheet-backdrop')?.remove();const wrap=document.createElement('div');wrap.className='sheet-backdrop';wrap.innerHTML=`<section class="sheet scan-sheet" role="dialog" aria-modal="true" aria-labelledby="scan-title"><div class="sheet-handle"></div><div class="sheet-header"><div><span class="eyebrow">Photo-first log</span><h2 id="scan-title">${mode==='result'?'Review Timmy’s suggestion':mode==='analyzing'?'Analyzing privately':'Start with the camera'}</h2></div><button class="icon-btn" id="close-sheet" aria-label="Close">×</button></div>${photoFirstBody(mode,error)}</section>`;document.body.append(wrap);document.querySelector('#close-sheet').onclick=()=>wrap.remove();wrap.onclick=e=>{if(e.target===wrap)wrap.remove()};
  document.querySelectorAll('#camera-photo,#gallery-photo').forEach(file=>{file.onchange=handleAiPhoto;file.addEventListener('cancel',()=>showPhotoFirst('pick','Camera or photo picker closed. If permission was denied, allow camera access in browser settings, choose from the gallery, or continue without AI.'))});
- const consent=document.querySelector('#ai-consent'),analyze=document.querySelector('#analyze-photo');if(consent&&analyze)consent.onchange=()=>analyze.disabled=!consent.checked||visionStatus?.providerReady===false;if(analyze)analyze.onclick=runAiAnalysis;
+ const consent=document.querySelector('#ai-consent'),analyze=document.querySelector('#analyze-photo');if(consent&&analyze)consent.onchange=()=>analyze.disabled=!consent.checked||!visionReadiness(visionStatus).ready;if(analyze)analyze.onclick=runAiAnalysis;
  document.querySelector('#retake-photo')?.addEventListener('click',()=>{form.photoDataUrl='';photoHint='';resetSuggestion();showPhotoFirst('pick')});
  document.querySelector('#manual-from-scan')?.addEventListener('click',()=>{resetSuggestion();showLogStep(1)});
  document.querySelector('#use-suggestion')?.addEventListener('click',()=>{suggestionState=confirmSuggestion(suggestionState);form=mergeVisualSuggestion(form,aiSuggestion);form.typeChosen=true;showLogStep(1)});

deploy/worker/Dockerfile

@@ -0,0 +1,67 @@
+# Timmy self-hosted vision worker (issue #15).
+#
+# Reproducible by construction: the llama.cpp revision and both model hashes are pinned here and in
+# deploy/worker/receipts.json, and tests/worker-container.test.js fails if either drifts from
+# scripts/bootstrap_selfhost_smolvlm.sh on the host.
+#
+# The weights are deliberately NOT baked into the image. They are mounted read-only at /models and
+# hash-verified against the pinned receipts by the entrypoint before the server starts.
+
+ARG LLAMA_CPP_COMMIT=6d05498314db1b57f81c271080018aa2d0b89be9
+ARG MODEL_SHA256=0cf76814555b8665149075b74ab6b5c1d428ea1d3d01c1918c12012e8d7c9f58
+ARG MMPROJ_SHA256=ae07ea1facd07dd3230c4483b63e8cda96c6944ad2481f33d531f79e892dd024
+
+# Digest-pinned bases, recorded in deploy/worker/receipts.json. A tag alone can be repointed, so
+# the digest is what makes this build reproducible.
+FROM nvidia/cuda:12.4.1-devel-ubuntu22.04@sha256:da6791294b0b04d7e65d87b7451d6f2390b4d36225ab0701ee7dfec5769829f5 AS build
+
+ARG LLAMA_CPP_COMMIT
+RUN apt-get update \
+ && apt-get install --yes --no-install-recommends git ca-certificates cmake build-essential \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /src
+RUN git init llama.cpp \
+ && cd llama.cpp \
+ && git remote add origin https://github.com/ggml-org/llama.cpp \
+ && git fetch --depth 1 origin "${LLAMA_CPP_COMMIT}" \
+ && git checkout --detach FETCH_HEAD
+RUN cmake -S llama.cpp -B llama.cpp/build -DCMAKE_BUILD_TYPE=Release -DLLAMA_CURL=OFF -DGGML_CUDA=ON \
+ && cmake --build llama.cpp/build --parallel "$(nproc)" --target llama-server
+
+FROM nvidia/cuda:12.4.1-runtime-ubuntu22.04@sha256:517da2300c184c9999ec203c2665244bdebd3578d12fcc7065e83667932643d9 AS runtime
+
+ARG MODEL_SHA256
+ARG MMPROJ_SHA256
+
+RUN apt-get update \
+ && apt-get install --yes --no-install-recommends curl ca-certificates \
+ && rm -rf /var/lib/apt/lists/* \
+ && mkdir -p /models
+
+COPY --from=build /src/llama.cpp/build/bin/ /usr/local/bin/
+COPY deploy/worker/entrypoint.sh /usr/local/bin/timmy-worker-entrypoint
+COPY scripts/worker_ready.sh /usr/local/bin/timmy-worker-ready
+RUN chmod 0755 /usr/local/bin/timmy-worker-entrypoint /usr/local/bin/timmy-worker-ready && ldconfig
+
+# No credential is configured: the worker is a private service the app reaches over host loopback.
+# 0.0.0.0 here is the address inside this container's own network namespace; the run recipe decides
+# exposure and publishes on 127.0.0.1 only.
+ENV TIMMY_MODEL_DIR=/models \
+    TIMMY_MODEL_FILE=/models/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf \
+    TIMMY_MMPROJ_FILE=/models/mmproj-SmolVLM2-2.2B-Instruct-Q8_0.gguf \
+    TIMMY_MODEL_SHA256=${MODEL_SHA256} \
+    TIMMY_MMPROJ_SHA256=${MMPROJ_SHA256} \
+    TIMMY_MODEL_ALIAS=SmolVLM2-2.2B-Instruct \
+    TIMMY_MODEL_HOST=0.0.0.0 \
+    TIMMY_MODEL_PORT=8080
+
+USER 10001:10001
+EXPOSE 8080
+
+# Health is the post-load gate: the worker is not healthy until the pinned model is being served,
+# so an orchestrator cannot route to a worker that cannot answer. start-period covers a cold load.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=600s --retries=3 \
+  CMD ["/usr/local/bin/timmy-worker-ready", "--host", "127.0.0.1", "--port", "8080", "--alias", "SmolVLM2-2.2B-Instruct"]
+
+ENTRYPOINT ["/usr/local/bin/timmy-worker-entrypoint"]

deploy/worker/build_image.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Build the pinned Timmy worker image (issue #15).
+#
+# Every pin is checked before docker is invoked, so an unpinned or floating reference fails here
+# rather than producing an image nobody can reproduce.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+RECEIPTS="$REPO_ROOT/deploy/worker/receipts.json"
+IMAGE="${TIMMY_WORKER_IMAGE:-timmy-vision-worker}"
+TAG="${TIMMY_WORKER_TAG:-$(date -u +%Y%m%d)}"
+PUBLISH_HOST="${TIMMY_WORKER_PUBLISH_HOST:-127.0.0.1}"
+PORT="${TIMMY_MODEL_PORT:-8080}"
+
+receipt_field() {
+  python3 - "$RECEIPTS" "$1" <<'PY'
+import json
+import sys
+document = json.load(open(sys.argv[1]))
+value = document
+for part in sys.argv[2].split('.'):
+    value = value[int(part)] if part.isdigit() else value[part]
+print(value)
+PY
+}
+
+# An explicit value still wins, but an empty one is treated as an invalid pin rather than a default.
+LLAMA_CPP_COMMIT="${TIMMY_LLAMA_CPP_COMMIT-$(receipt_field llamaCpp.commit)}"
+MODEL_SHA256="${TIMMY_MODEL_SHA256-$(receipt_field models.0.sha256)}"
+MMPROJ_SHA256="${TIMMY_MMPROJ_SHA256-$(receipt_field models.1.sha256)}"
+MODEL_FILE="$(receipt_field models.0.file)"
+MMPROJ_FILE="$(receipt_field models.1.file)"
+BUILD_BASE="$(receipt_field baseImages.build.reference)@$(receipt_field baseImages.build.digest)"
+RUNTIME_BASE="$(receipt_field baseImages.runtime.reference)@$(receipt_field baseImages.runtime.digest)"
+
+if [[ ! "$LLAMA_CPP_COMMIT" =~ ^[0-9a-f]{40}$ ]]; then
+  printf 'Refusing to build: the llama.cpp pin must be a 40-hex commit, got %s (floating refs are not reproducible).\n' "${LLAMA_CPP_COMMIT:-<empty>}" >&2
+  exit 64
+fi
+for pin in "$MODEL_SHA256" "$MMPROJ_SHA256"; do
+  if [[ ! "$pin" =~ ^[0-9a-f]{64}$ ]]; then
+    printf 'Refusing to build: every model hash must be a pinned sha256, got %s.\n' "${pin:-<empty>}" >&2
+    exit 64
+  fi
+done
+for base in "$BUILD_BASE" "$RUNTIME_BASE"; do
+  if [[ ! "$base" =~ @sha256:[0-9a-f]{64}$ ]]; then
+    printf 'Refusing to build: base images must be digest-pinned, got %s.\n' "$base" >&2
+    exit 64
+  fi
+done
+
+if [[ ! "$PUBLISH_HOST" =~ ^(127\.0\.0\.1|::1|localhost)$ ]]; then
+  printf 'Refusing to publish the worker outside loopback (127.0.0.1): got %s.\n' "$PUBLISH_HOST" >&2
+  exit 64
+fi
+
+print_plan() {
+  printf 'image: %s:%s\n' "$IMAGE" "$TAG"
+  printf 'llama.cpp commit: %s\n' "$LLAMA_CPP_COMMIT"
+  printf '%s sha256: %s\n' "$MODEL_FILE" "$MODEL_SHA256"
+  printf '%s sha256: %s\n' "$MMPROJ_FILE" "$MMPROJ_SHA256"
+  printf 'base image (build): %s\n' "$BUILD_BASE"
+  printf 'base image (runtime): %s\n' "$RUNTIME_BASE"
+  printf 'bind address: %s:%s\n' "$PUBLISH_HOST" "$PORT"
+  printf 'publish: %s:%s\n' "$PUBLISH_HOST" "$PORT"
+  printf 'docker build --file deploy/worker/Dockerfile --build-arg LLAMA_CPP_COMMIT=%s --build-arg MODEL_SHA256=%s --build-arg MMPROJ_SHA256=%s --tag %s:%s .\n' \
+    "$LLAMA_CPP_COMMIT" "$MODEL_SHA256" "$MMPROJ_SHA256" "$IMAGE" "$TAG"
+}
+
+if [[ "${1:-}" == '--print-plan' ]]; then
+  print_plan
+  exit 0
+fi
+
+print_plan
+cd "$REPO_ROOT"
+docker build \
+  --file deploy/worker/Dockerfile \
+  --build-arg "LLAMA_CPP_COMMIT=$LLAMA_CPP_COMMIT" \
+  --build-arg "MODEL_SHA256=$MODEL_SHA256" \
+  --build-arg "MMPROJ_SHA256=$MMPROJ_SHA256" \
+  --tag "$IMAGE:$TAG" \
+  .
+printf 'Built %s:%s from pinned receipts. Run it with deploy/worker/run_worker_container.sh\n' "$IMAGE" "$TAG"

deploy/worker/entrypoint.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Start the pinned worker after verifying the mounted weights (issue #15).
+#
+# Fails closed before the server is allowed to answer: a missing pin, an unreadable model, or a
+# hash mismatch stops the container instead of serving suggestions from an unknown model.
+set -euo pipefail
+
+MODEL="${TIMMY_MODEL_FILE:-/models/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf}"
+MMPROJ="${TIMMY_MMPROJ_FILE:-/models/mmproj-SmolVLM2-2.2B-Instruct-Q8_0.gguf}"
+MODEL_SHA256="${TIMMY_MODEL_SHA256:-}"
+MMPROJ_SHA256="${TIMMY_MMPROJ_SHA256:-}"
+ALIAS="${TIMMY_MODEL_ALIAS:-SmolVLM2-2.2B-Instruct}"
+HOST="${TIMMY_MODEL_HOST:-0.0.0.0}"
+PORT="${TIMMY_MODEL_PORT:-8080}"
+THREADS="${TIMMY_MODEL_THREADS:-4}"
+
+for pin in "$MODEL_SHA256" "$MMPROJ_SHA256"; do
+  if [[ ! "$pin" =~ ^[0-9a-f]{64}$ ]]; then
+    printf 'Refusing to start: the pinned model hashes are missing or malformed.\n' >&2
+    exit 78
+  fi
+done
+
+for file in "$MODEL" "$MMPROJ"; do
+  if [[ ! -f "$file" ]]; then
+    printf 'Refusing to start: %s is not mounted. Mount the verified model directory read-only at /models.\n' "$file" >&2
+    exit 78
+  fi
+done
+
+printf '%s  %s\n%s  %s\n' "$MODEL_SHA256" "$MODEL" "$MMPROJ_SHA256" "$MMPROJ" | sha256sum --check --status || {
+  printf 'Refusing to start: mounted weights do not match the pinned receipts.\n' >&2
+  exit 78
+}
+
+printf 'Starting %s from pinned weights on %s:%s (private namespace)\n' "$ALIAS" "$HOST" "$PORT"
+exec llama-server \
+  --model "$MODEL" \
+  --mmproj "$MMPROJ" \
+  --alias "$ALIAS" \
+  --host "$HOST" \
+  --port "$PORT" \
+  --ctx-size 4096 \
+  --parallel 1 \
+  --threads "$THREADS" \
+  --no-webui

deploy/worker/receipts.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": 1,
+  "issue": 15,
+  "llamaCpp": {
+    "repository": "https://github.com/ggml-org/llama.cpp",
+    "commit": "6d05498314db1b57f81c271080018aa2d0b89be9"
+  },
+  "baseImages": {
+    "build": {
+      "reference": "nvidia/cuda:12.4.1-devel-ubuntu22.04",
+      "digest": "sha256:da6791294b0b04d7e65d87b7451d6f2390b4d36225ab0701ee7dfec5769829f5"
+    },
+    "runtime": {
+      "reference": "nvidia/cuda:12.4.1-runtime-ubuntu22.04",
+      "digest": "sha256:517da2300c184c9999ec203c2665244bdebd3578d12fcc7065e83667932643d9"
+    }
+  },
+  "models": [
+    {
+      "file": "SmolVLM2-2.2B-Instruct-Q4_K_M.gguf",
+      "sha256": "0cf76814555b8665149075b74ab6b5c1d428ea1d3d01c1918c12012e8d7c9f58",
+      "mount": "/models/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf"
+    },
+    {
+      "file": "mmproj-SmolVLM2-2.2B-Instruct-Q8_0.gguf",
+      "sha256": "ae07ea1facd07dd3230c4483b63e8cda96c6944ad2481f33d531f79e892dd024",
+      "mount": "/models/mmproj-SmolVLM2-2.2B-Instruct-Q8_0.gguf"
+    }
+  ],
+  "alias": "SmolVLM2-2.2B-Instruct",
+  "bind": {
+    "publishHost": "127.0.0.1",
+    "containerPort": 8080
+  },
+  "notes": [
+    "Model weights are never baked into the image; they are mounted read-only and hash-verified at start-up.",
+    "The pins are asserted equal to scripts/bootstrap_selfhost_smolvlm.sh by tests/worker-container.test.js so host and image cannot drift.",
+    "The worker needs no provider credential: it is a private loopback-only service."
+  ]
+}

deploy/worker/run_worker_container.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Run the pinned worker with the least privilege it can work under (issue #15).
+#
+# The worker is a private service. It is published on loopback only, mounts the verified weights
+# read-only, keeps an immutable root filesystem, and holds no credential of any kind.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+RECEIPTS="$REPO_ROOT/deploy/worker/receipts.json"
+IMAGE="${TIMMY_WORKER_IMAGE:-timmy-vision-worker}"
+TAG="${TIMMY_WORKER_TAG:-$(date -u +%Y%m%d)}"
+PORT="${TIMMY_MODEL_PORT:-8080}"
+PUBLISH_HOST="${TIMMY_WORKER_PUBLISH_HOST:-127.0.0.1}"
+MODEL_DIR="${TIMMY_WORKER_MODEL_DIR:-${TIMMY_SELFHOST_ROOT:-$HOME/.local/share/timmy-selfhost}/models}"
+NAME="${TIMMY_WORKER_CONTAINER:-timmy-vision-worker}"
+ALIAS="${TIMMY_MODEL_ALIAS:-SmolVLM2-2.2B-Instruct}"
+
+# Exposure is the one decision this recipe must never get wrong, so a non-loopback publish host is
+# refused rather than warned about.
+if [[ ! "$PUBLISH_HOST" =~ ^(127\.0\.0\.1|::1|localhost)$ ]]; then
+  printf 'Refusing to publish the worker outside loopback (127.0.0.1): got %s.\n' "$PUBLISH_HOST" >&2
+  exit 64
+fi
+
+if [[ ! "$PORT" =~ ^[0-9]{1,5}$ ]] || (( PORT < 1 || PORT > 65535 )); then
+  printf 'Refusing to start: the port must be a number between 1 and 65535, got %s.\n' "$PORT" >&2
+  exit 64
+fi
+
+RUN_ARGS=(
+  run
+  --detach
+  --name "$NAME"
+  --read-only
+  --cap-drop=ALL
+  --security-opt no-new-privileges
+  --tmpfs /tmp:rw,noexec,nosuid,size=64m
+  --volume "$MODEL_DIR:/models:ro"
+  --publish "127.0.0.1:${PORT}:8080"
+  --env "TIMMY_MODEL_PORT=8080"
+  --env "TIMMY_MODEL_THREADS=${TIMMY_MODEL_THREADS:-4}"
+  "$IMAGE:$TAG"
+)
+
+if [[ "${1:-}" == '--print-plan' ]]; then
+  printf 'image: %s:%s\n' "$IMAGE" "$TAG"
+  printf 'model directory (read-only mount): %s\n' "$MODEL_DIR"
+  printf 'bind address: %s:%s\n' "$PUBLISH_HOST" "$PORT"
+  printf 'publish: %s:%s\n' "$PUBLISH_HOST" "$PORT"
+  printf 'health: %s ready (post-load gate)\n' "$ALIAS"
+  printf 'docker %s\n' "${RUN_ARGS[*]}"
+  exit 0
+fi
+
+if [[ ! -d "$MODEL_DIR" ]]; then
+  printf 'Refusing to start: %s is not a directory. Install the pinned weights with scripts/bootstrap_selfhost_smolvlm.sh install.\n' "$MODEL_DIR" >&2
+  exit 78
+fi
+
+docker "${RUN_ARGS[@]}"
+printf 'Worker container %s started on %s:%s. Readiness: docker exec %s timmy-worker-ready\n' "$NAME" "$PUBLISH_HOST" "$PORT" "$NAME"

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",
+    "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",
     "test:ui": "node tests/ui.acceptance.mjs",
     "test:photo": "node tests/photo-first.acceptance.mjs",
     "test:mobile-capture": "node tests/mobile-capture.acceptance.mjs",
@@ -12,10 +12,13 @@
     "test:manual-fallback": "node tests/manual-fallback.acceptance.mjs",
     "test:provisional": "node tests/provisional-suggestion.acceptance.mjs",
     "test:followup": "node tests/followup.acceptance.mjs",
+    "test:vision-refusal": "node tests/vision-refusal.acceptance.mjs",
     "test:staging-smoke": "node tests/staging.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 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 && 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",
+    "test:pattern-summary": "node tests/pattern-summary.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 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 && 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",
     "check:diff": "bash scripts/check_diff.sh",
-    "start": "node server.mjs"
+    "start": "node server.mjs",
+    "test:worker-readiness": "node tests/worker-readiness.acceptance.mjs"
   },
   "devDependencies": {
     "playwright": "^1.62.1"

scripts/bootstrap_selfhost_smolvlm.sh

@@ -137,6 +137,10 @@ case "${1:-}" in
   start)
     start_worker
     ;;
+  ready)
+    # Post-load readiness (issue #15): delegate so the host and the container gate cannot drift.
+    exec "$(dirname "$0")/worker_ready.sh" --host "$HOST" --port "$PORT" --alias SmolVLM2-2.2B-Instruct "${@:2}"
+    ;;
   health)
     health_worker
     ;;
@@ -144,7 +148,7 @@ case "${1:-}" in
     stop_worker
     ;;
   *)
-    printf 'Usage: %s {install|start|health|stop|receipt|verify}\n' "$0" >&2
+    printf 'Usage: %s {install|start|health|ready|stop|receipt|verify}\n' "$0" >&2
     exit 64
     ;;
 esac

scripts/build_release.py

@@ -37,6 +37,11 @@ DEMO_REQUIRED_CAPTIONS = (
     "Delete all local data clears the ledger in this browser; there is no server copy of it to keep",
     "Hermes Agent connected — free-text, contextual, and server-side",
     "Urgent language is intercepted deterministically before Hermes",
+    "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",
+    "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",
 )
 
 
@@ -108,6 +113,8 @@ def main() -> int:
         run(["git", "checkout", "--quiet", commit], tree)
         run(["npm", "ci", "--ignore-scripts"], tree)
         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)
         server_env = dict(os.environ)
         server_env.update({"HOST": "127.0.0.1", "PORT": "4173", "TIMMY_VISION_ENABLED": "false"})
         server_log = (release_dir / "acceptance-server.log").open("w", encoding="utf-8")
@@ -131,6 +138,9 @@ def main() -> int:
             run(["npm", "run", "test:manual-fallback"], tree)
             run(["npm", "run", "test:provisional"], tree)
             run(["npm", "run", "test:followup"], tree)
+            run(["npm", "run", "test:vision-refusal"], tree)
+            run(["npm", "run", "test:worker-readiness"], tree)
+            run(["npm", "run", "test:pattern-summary"], 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)
@@ -172,11 +182,15 @@ 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", "tests/staging.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", "scripts/record_worker_benchmark.mjs", "tests/staging.acceptance.mjs", "tests/vision-refusal.acceptance.mjs", "tests/worker-readiness.acceptance.mjs", "tests/pattern-summary.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)
-        run(["python3", "-m", "py_compile", "scripts/ingest_training_photo.py", "scripts/build_release.py"], tree)
+        run(["bash", "-n", "scripts/worker_ready.sh"], tree)
+        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(["git", "diff", "--check", commit], tree)
 
         names = tracked_files(tree)
@@ -203,6 +217,11 @@ def main() -> int:
             "- Vision profiles: hosted and self-hosted SmolVLM2 bootstrap\n"
             "- AI suggestions stay provisional: suggested, confirmed, and corrected states are distinct and screen-reader described; correcting one clears the AI-confirmed state without losing user context\n"
             "- Hard-stool follow-up: a Bristol 1-2 entry asks user-reported questions (difficulty passing, soreness, visible blood, truly black/tarry versus dark brown, hydration); mild reports get non-diagnostic self-care, and a confirmed red-flag answer lands on the same deterministic escalation path as manual logging\n"
+            "- Vision corpus: a committed CC0 synthetic corpus (stool, non-stool, blur, glare, empty bowl, malformed response) proves every reply is schema-valid or fails closed; a schema-valid reply with unreadable fields abstains instead of erroring, and unparsable or out-of-range replies return plain copy with nothing applied — including a reply that fills in one field and leaves the other blank, where an out-of-range value still fails closed instead of being reported as an unreadable photo (issue #73)\n"
+            "- Self-hosted worker container: a digest-pinned image that builds the pinned llama.cpp revision, mounts hash-verified weights read-only, runs unprivileged with no credential, and is published on loopback only (issue #15)\n"
+            "- Post-load readiness: the app offers AI only once the pinned model is actually loaded, so a reachable-but-unloaded worker falls back to manual logging in one tap instead of failing after the upload (issue #15)\n"
+            "- 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"
             "- Safety: suggestions are observable-field assistance, never diagnosis; user confirmation is required\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"
@@ -248,7 +267,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, offline vision status, and deterministic Hermes chat response",
+            "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, and deterministic Hermes chat response",
         },
         "gates": {
             "unit_security": "passed",
@@ -258,6 +277,10 @@ def main() -> int:
             "manual_fallback_draft_recovery": "passed",
             "provisional_suggestion_state": "passed",
             "hard_stool_followup": "passed",
+            "vision_corpus_refusal": "passed",
+            "worker_container_receipts": "passed",
+            "worker_post_load_readiness": "passed",
+            "longitudinal_pattern_summary": "passed",
             "dependency_audit_high": "passed",
             "syntax": "passed",
             "secret_scan": "passed",

scripts/build_vision_corpus.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Generate the deterministic synthetic vision corpus for issue #18.
+
+Every fixture is drawn from fixed integer math: no camera, no human subject, no
+third-party content, and no randomness. That keeps the corpus redistributable and
+keeps the recorded SHA-256 hashes meaningful as an integrity receipt.
+
+Usage:
+  python3 scripts/build_vision_corpus.py            # (re)write fixtures and manifest.json
+  python3 scripts/build_vision_corpus.py --verify   # verify committed fixtures against the manifest
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+from PIL import Image, ImageDraw, ImageFilter
+
+LICENSE = "CC0-1.0"
+CORPUS_DIR = Path(__file__).resolve().parents[1] / "tests" / "fixtures" / "vision-corpus"
+WIDTH, HEIGHT = 640, 480
+PROVENANCE = "Synthetic fixture drawn deterministically by scripts/build_vision_corpus.py; no camera, no human subject, no third-party content."
+
+OBSERVATION_STRINGS = {
+    "smooth": "Smooth, formed appearance.",
+    "flatware": "Flatware on a tray.",
+    "unclear": "Form is unclear.",
+    "highlight": "Large specular highlight hides the surface.",
+    "container": "Empty container.",
+    "confident": "Confident.",
+    "partial": "Form read, colour not.",
+}
+
+
+def background(color: tuple[int, int, int]) -> Image.Image:
+    """A flat canvas with a coarse, deterministic shade band."""
+    image = Image.new("RGB", (WIDTH, HEIGHT), color)
+    draw = ImageDraw.Draw(image)
+    for index in range(4):
+        shade = tuple(min(255, channel + 6 * index) for channel in color)
+        draw.rectangle([0, index * 120, WIDTH, index * 120 + 119], fill=shade)
+    return image
+
+
+def blob(image: Image.Image, box: tuple[int, int, int, int], tone: tuple[int, int, int]) -> None:
+    draw = ImageDraw.Draw(image)
+    draw.ellipse(box, fill=tone)
+    left, top, right, bottom = box
+    inset = max(4, (right - left) // 6)
+    draw.ellipse([left + inset, top + inset, right - inset, bottom - inset],
+                 fill=tuple(min(255, channel + 10) for channel in tone))
+
+
+def stool_like() -> Image.Image:
+    image = background((226, 222, 212))
+    blob(image, (170, 150, 470, 330), (108, 76, 48))
+    return image
+
+
+def non_stool_scene() -> Image.Image:
+    image = background((198, 202, 208))
+    draw = ImageDraw.Draw(image)
+    draw.ellipse([120, 90, 520, 390], fill=(244, 244, 240))
+    draw.rectangle([60, 200, 300, 224], fill=(120, 126, 134))
+    draw.rectangle([340, 200, 580, 224], fill=(120, 126, 134))
+    return image
+
+
+def blur_low_detail() -> Image.Image:
+    return stool_like().filter(ImageFilter.GaussianBlur(5))
+
+
+def glare_overexposed() -> Image.Image:
+    image = background((222, 218, 208))
+    blob(image, (150, 140, 430, 300), (104, 74, 46))
+    draw = ImageDraw.Draw(image)
+    draw.polygon([(380, 200), (640, 120), (640, 360), (420, 330)], fill=(252, 252, 250))
+    draw.ellipse([470, 210, 620, 320], fill=(255, 255, 255))
+    return image
+
+
+def empty_bowl() -> Image.Image:
+    image = background((214, 210, 202))
+    draw = ImageDraw.Draw(image)
+    draw.ellipse([130, 90, 510, 400], fill=(238, 236, 230))
+    draw.ellipse([175, 130, 465, 360], fill=(206, 204, 198))
+    draw.ellipse([220, 170, 420, 320], fill=(232, 230, 224))
+    return image
+
+
+def unusable_tone() -> Image.Image:
+    image = background((202, 206, 198))
+    blob(image, (190, 160, 450, 320), (128, 118, 92))
+    return image
+
+
+def shaded_tone() -> Image.Image:
+    image = background((216, 214, 206))
+    blob(image, (180, 155, 460, 325), (96, 84, 52))
+    draw = ImageDraw.Draw(image)
+    draw.rectangle([0, 300, WIDTH, 306], fill=(180, 178, 170))
+    return image
+
+
+def half_read_tone() -> Image.Image:
+    """A fixture for the reply shape that fills one field and blanks the other (issue #73)."""
+    image = background((208, 212, 204))
+    blob(image, (175, 150, 455, 322), (112, 96, 66))
+    draw = ImageDraw.Draw(image)
+    draw.rectangle([0, 200, WIDTH // 2, 206], fill=(196, 194, 186))
+    draw.rectangle([WIDTH // 2, 260, WIDTH, 266], fill=(170, 168, 160))
+    return image
+
+
+def content(payload: dict[str, object] | str) -> str:
+    return payload if isinstance(payload, str) else json.dumps(payload, separators=(",", ":"))
+
+
+def cases() -> list[dict[str, Any]]:
+    return [
+        {
+            "id": "stool-like-formed",
+            "caseClass": "stool",
+            "image": stool_like,
+            "expectedOutcome": "suggestion",
+            "expectedReason": "schema_valid_suggestion",
+            "providerContent": content({
+                "isStool": True, "bristolType": 4, "color": "brown", "confidence": 0.83,
+                "imageQuality": "good", "observations": OBSERVATION_STRINGS["smooth"],
+            }),
+        },
+        {
+            "id": "non-stool-scene",
+            "caseClass": "non-stool",
+            "image": non_stool_scene,
+            "expectedOutcome": "abstained",
+            "expectedReason": "not_stool",
+            "providerContent": content({
+                "isStool": False, "bristolType": None, "color": None, "confidence": 0.97,
+                "imageQuality": "good", "observations": OBSERVATION_STRINGS["flatware"],
+            }),
+        },
+        {
+            "id": "blur-low-detail",
+            "caseClass": "blur",
+            "image": blur_low_detail,
+            "expectedOutcome": "abstained",
+            "expectedReason": "low_confidence",
+            "providerContent": content({
+                "isStool": True, "bristolType": 4, "color": "brown", "confidence": 0.41,
+                "imageQuality": "poor", "observations": OBSERVATION_STRINGS["unclear"],
+            }),
+        },
+        {
+            "id": "glare-overexposed",
+            "caseClass": "glare",
+            "image": glare_overexposed,
+            "expectedOutcome": "abstained",
+            "expectedReason": "unusable_visual_fields",
+            "providerContent": content({
+                "isStool": True, "bristolType": None, "color": None, "confidence": 0.66,
+                "imageQuality": "poor", "observations": OBSERVATION_STRINGS["highlight"],
+            }),
+        },
+        {
+            "id": "empty-bowl",
+            "caseClass": "empty-bowl",
+            "image": empty_bowl,
+            "expectedOutcome": "abstained",
+            "expectedReason": "not_stool",
+            "providerContent": content({
+                "isStool": False, "bristolType": None, "color": None, "confidence": 0.93,
+                "imageQuality": "good", "observations": OBSERVATION_STRINGS["container"],
+            }),
+        },
+        {
+            "id": "malformed-response",
+            "caseClass": "malformed-response",
+            "image": unusable_tone,
+            "expectedOutcome": "fail_closed",
+            "expectedReason": "unparsable_content",
+            "providerContent": "Sure! It looks like a Type 4 to me. Hope that helps.",
+        },
+        {
+            "id": "out-of-range-fields",
+            "caseClass": "malformed-response",
+            "image": shaded_tone,
+            "expectedOutcome": "fail_closed",
+            "expectedReason": "out_of_range_or_missing_fields",
+            # Confidence stays inside the contract so this reply reaches the field-range check. At 1.4 it
+            # died at the confidence gate instead, which credited the `out_of_range_or_missing_fields`
+            # label to a guard the case never exercised (issue #73).
+            "providerContent": content({
+                "isStool": True, "bristolType": 9, "color": "purple", "confidence": 0.9,
+                "imageQuality": "excellent", "observations": OBSERVATION_STRINGS["confident"],
+            }),
+        },
+        {
+            "id": "blank-plus-out-of-range",
+            "caseClass": "malformed-response",
+            "image": half_read_tone,
+            "expectedOutcome": "fail_closed",
+            "expectedReason": "out_of_range_or_missing_fields",
+            # The class the blank-first ordering used to let through (issue #73): one field is blank and
+            # the other is a filled-in, impossible value. A filled-in field is a claim, so this must fail
+            # closed rather than abstain as `unusable_visual_fields`.
+            "providerContent": content({
+                "isStool": True, "bristolType": 9, "color": None, "confidence": 0.9,
+                "imageQuality": "good", "observations": OBSERVATION_STRINGS["partial"],
+            }),
+        },
+    ]
+
+
+def write_fixture(definition: dict[str, Any], directory: Path) -> dict[str, Any]:
+    name = f"{definition['id']}.png"
+    target = directory / name
+    factory: Callable[[], Image.Image] = definition["image"]
+    factory().save(target, "PNG", optimize=True)
+    data = target.read_bytes()
+    return {
+        "id": definition["id"],
+        "caseClass": definition["caseClass"],
+        "file": name,
+        "bytes": len(data),
+        "sha256": hashlib.sha256(data).hexdigest(),
+        "width": WIDTH,
+        "height": HEIGHT,
+        "format": "png",
+        "synthetic": True,
+        "license": LICENSE,
+        "provenance": PROVENANCE,
+        "expectedOutcome": definition["expectedOutcome"],
+        "expectedReason": definition["expectedReason"],
+        "providerContent": definition["providerContent"],
+    }
+
+
+def manifest(entries: list[dict[str, object]]) -> dict[str, object]:
+    return {
+        "schemaVersion": 1,
+        "generator": "scripts/build_vision_corpus.py",
+        "license": LICENSE,
+        "note": "Synthetic fixtures only. No real medical imagery, no personal data, and no third-party content.",
+        "cases": entries,
+    }
+
+
+def write(directory: Path) -> int:
+    directory.mkdir(parents=True, exist_ok=True)
+    entries = [write_fixture(definition, directory) for definition in cases()]
+    (directory / "manifest.json").write_text(json.dumps(manifest(entries), indent=2) + "\n", encoding="utf-8")
+    print(f"wrote {len(entries)} fixtures to {directory}")
+    return 0
+
+
+def verify(directory: Path) -> int:
+    manifest_path = directory / "manifest.json"
+    recorded = json.loads(manifest_path.read_text(encoding="utf-8"))
+    problems: list[str] = []
+    for entry in recorded.get("cases", []):
+        path = directory / str(entry.get("file"))
+        if not path.is_file():
+            problems.append(f"{entry.get('id')}: missing fixture {entry.get('file')}")
+            continue
+        data = path.read_bytes()
+        if hashlib.sha256(data).hexdigest() != entry.get("sha256"):
+            problems.append(f"{entry.get('id')}: bytes do not match the recorded sha256")
+        if len(data) != entry.get("bytes"):
+            problems.append(f"{entry.get('id')}: byte length does not match the manifest")
+    if problems:
+        for problem in problems:
+            print(problem, file=sys.stderr)
+        return 1
+    print(f"verified {len(recorded.get('cases', []))} corpus fixtures against manifest.json")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--verify", action="store_true", help="check committed fixtures against the manifest instead of rewriting")
+    parser.add_argument("--directory", default=str(CORPUS_DIR))
+    args = parser.parse_args()
+    directory = Path(args.directory)
+    return verify(directory) if args.verify else write(directory)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/record_release_demo.mjs

@@ -1,6 +1,9 @@
 import { chromium } from 'playwright';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { analyzePhoto, visionFailureResponse } from '../src/vision-service.js';
+import { loadVisionCorpus } from '../src/vision-corpus.js';
 
 const output = path.resolve(process.argv[2] || 'release-demo.webm');
 const version = process.env.TIMMY_RELEASE_VERSION || 'review build';
@@ -13,6 +16,26 @@ const captionsShown = [];
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
 await mkdir(path.dirname(output), { recursive: true });
 
+// The refusal scene replays committed synthetic corpus cases through the real analysis code path,
+// so the recording shows the status and copy the server would actually send rather than copy
+// written for the video. No real photo is used anywhere in the corpus.
+const corpus = await loadVisionCorpus(fileURLToPath(new URL('../tests/fixtures/vision-corpus/', import.meta.url)));
+const corpusCase = id => corpus.cases.find(entry => entry.id === id);
+async function corpusAnalyzeResult(entry) {
+  const fetchImpl = async () => ({ ok: true, json: async () => ({ choices: [{ message: { content: entry.providerContent } }] }) });
+  try {
+    const result = await analyzePhoto({
+      payload: { imageDataUrl: 'data:image/png;base64,YQ==', consent: true },
+      fetchImpl,
+      config: { baseUrl: 'http://127.0.0.1:9/v1', apiKey: 'corpus-replay', model: 'corpus-model' },
+    });
+    return { status: 200, body: result };
+  } catch (error) {
+    const failure = visionFailureResponse(error);
+    return { status: failure.status, body: failure.body };
+  }
+}
+
 const browser = await chromium.launch({ headless: true });
 const context = await browser.newContext({
   viewport: { width: 405, height: 720 },
@@ -26,6 +49,9 @@ const errors = [];
 page.on('console', message => { if (message.type() === 'error') errors.push(message.text()); });
 page.on('pageerror', error => errors.push(error.message));
 let visionOffline = false;
+// Reachable is not loaded: the worker can answer /v1/models before its pinned model is resident,
+// and the recording shows the app withholding AI in exactly that state (issue #15).
+let modelLoaded = true;
 await page.route('**/api/vision-status', route => route.fulfill({
   status: 200,
   contentType: 'application/json',
@@ -36,23 +62,26 @@ await page.route('**/api/vision-status', route => route.fulfill({
     model: 'SmolVLM2-2.2B-Instruct',
     // The second pass flips the app's own readiness contract so no AI control is offered at all.
     providerReady: !visionOffline,
-    modelSeen: !visionOffline,
-  }),
-}));
-await page.route('**/api/analyze', route => route.fulfill({
-  status: 200,
-  contentType: 'application/json',
-  body: JSON.stringify({
-    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.',
+    modelSeen: !visionOffline && modelLoaded,
   }),
 }));
+// The happy path keeps one deterministic suggestion. The refusal scene swaps this for a real
+// corpus replay, so both the usable and the refused answers come from the same code path.
+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.',
+};
+let analyzeOverride = null;
+await page.route('**/api/analyze', route => {
+  const response = analyzeOverride || { status: 200, body: suggestionBody };
+  return route.fulfill({ status: response.status, contentType: 'application/json', body: JSON.stringify(response.body) });
+});
 await page.route('**/api/agent/status', route => route.fulfill({
   status: 200,
   contentType: 'application/json',
@@ -204,6 +233,135 @@ await caption('One tap still reaches manual Bristol entry, and the draft keeps y
 await tap('#discard-draft', 500);
 await caption('Start over clears the kept draft — nothing lingers silently', 1500);
 await tap('#close-sheet', 450);
+
+// Post-load readiness pass (issue #15): the worker answers, but its pinned model is not resident
+// yet. The app must withhold AI instead of offering a control that fails after the upload. Every
+// claim below is asserted in the browser, so the recording cannot show a state the app does not have.
+modelLoaded = false;
+visionOffline = false;
+await caption('Now the same worker while its pinned model is still loading', 1700);
+await tap('[data-scan]', 550);
+await page.getByText(/model is not loaded yet/i).first().waitFor();
+if (await page.getByText(/Self-hosted model ready/i).count() !== 0) {
+  throw new Error('A reachable worker without its loaded model must never be reported ready');
+}
+const loadingAmber = await page.locator('.model-status.loading').first().evaluate(el => getComputedStyle(el).backgroundColor);
+if (loadingAmber !== 'rgb(253, 243, 216)') throw new Error('The not-loaded state must be visually distinct from ready and offline');
+await page.locator('#gallery-photo').setInputFiles('tests/fixtures/synthetic-type4.jpg');
+await page.getByText(/Ready for your review/i).waitFor();
+if (await page.locator('#analyze-photo').count() !== 0) throw new Error('No AI control may exist before the model is loaded');
+if (await page.locator('.consent-card').count() !== 0) throw new Error('No consent may be requested before the model is loaded');
+await caption('Reachable is not loaded: no AI control, no consent, and no upload until the pinned model is resident', 2900);
+await tap('#manual-from-scan', 500);
+await page.getByText('Pick the closest form').waitFor();
+await caption('One tap still reaches manual Bristol entry while the model finishes loading', 2000);
+await tap('#close-sheet', 450);
+modelLoaded = true;
+await caption('Once the pinned model is loaded, the same screen offers the AI analysis again', 2200);
+await tap('[data-scan]', 550);
+await page.getByText(/Self-hosted model ready/i).waitFor();
+await page.locator('#gallery-photo').setInputFiles('tests/fixtures/synthetic-type4.jpg');
+await page.getByText(/Ready for your review/i).waitFor();
+if (await page.locator('.consent-card').isVisible() !== true) throw new Error('The AI path must return once the model is loaded');
+if (await page.locator('#analyze-photo').count() !== 1) throw new Error('The analyze control must return once the model is loaded');
+await tap('#close-sheet', 450);
+
+// Corpus refusal pass (issue #18): the same photo flow, fed the answers Timmy has to refuse.
+visionOffline = false;
+await caption('The corpus also replays the answers Timmy has to refuse', 1700);
+analyzeOverride = await corpusAnalyzeResult(corpusCase('non-stool-scene'));
+await tap('[data-scan]', 500);
+await page.getByText(/Self-hosted model ready/i).waitFor();
+await page.locator('#gallery-photo').setInputFiles('tests/fixtures/vision-corpus/non-stool-scene.png');
+await page.locator('#ai-consent').check();
+await tap('#analyze-photo', 600);
+await page.getByText(/No confident match/i).waitFor();
+await caption('A non-stool photo gets a refusal, never a guess — manual entry stays one tap away', 2600);
+await indicate('.scan-result');
+analyzeOverride = await corpusAnalyzeResult(corpusCase('glare-overexposed'));
+await tap('#retake-photo', 400);
+await page.locator('#gallery-photo').setInputFiles('tests/fixtures/vision-corpus/glare-overexposed.png');
+await page.locator('#ai-consent').check();
+await tap('#analyze-photo', 600);
+await page.getByText(/does not show a form Timmy can read safely/i).waitFor();
+await caption('Unreadable visual fields abstain as well: a valid reply with nothing to prefill is not an error', 2700);
+await indicate('.scan-result');
+analyzeOverride = await corpusAnalyzeResult(corpusCase('out-of-range-fields'));
+await tap('#retake-photo', 400);
+await page.locator('#gallery-photo').setInputFiles('tests/fixtures/vision-corpus/out-of-range-fields.png');
+await page.locator('#ai-consent').check();
+await tap('#analyze-photo', 600);
+await page.getByText(/couldn’t analyze that safely/i).waitFor();
+await caption('An out-of-range answer fails closed: nothing is applied and no provider detail reaches you', 2700);
+await indicate('.scan-result');
+// Issue #73's escape class: one field blank, the other filled in and impossible. The old blank-first
+// ordering abstained here, which told the user the photo was unreadable while the model had returned a
+// value Timmy must never apply. The scene is asserted in the browser, not just captioned.
+analyzeOverride = await corpusAnalyzeResult(corpusCase('blank-plus-out-of-range'));
+await tap('#retake-photo', 400);
+await page.locator('#gallery-photo').setInputFiles('tests/fixtures/vision-corpus/blank-plus-out-of-range.png');
+await page.locator('#ai-consent').check();
+await tap('#analyze-photo', 600);
+await page.getByText(/couldn’t analyze that safely/i).waitFor();
+if (await page.getByText(/No confident match/i).count() !== 0) {
+  throw new Error('A filled-in out-of-range field must not be shown as an unreadable-photo abstention');
+}
+await caption('A filled-in field that is out of range still fails closed, even when the other field came back blank', 2900);
+await indicate('.scan-result');
+await caption('You are no longer told the photo was unreadable when the model returned an impossible value', 2400);
+await indicate('.scan-result');
+await caption('Every refusal replays a committed synthetic fixture — there are no real photos in the corpus', 2500);
+analyzeOverride = null;
+await tap('#close-sheet', 450);
+
+// Explainable pattern summary (issue #34). The recording seeds fictional multi-day sample logs into
+// the app's own local ledger contract, then follows one summary line to the exact records behind it.
+// Every claim below is checked in the browser, and no real health data is involved anywhere.
+const seedSyntheticLedger = async entries => {
+  const key = await page.evaluate(() => `timmy:${document.querySelector('meta[name="timmy-base-path"]')?.content || '/'}:ledger-v1`);
+  await page.evaluate(({ storeKey, list }) => localStorage.setItem(storeKey, JSON.stringify(list)), { storeKey: key, list: entries });
+  await page.reload({ waitUntil: 'networkidle' });
+};
+const sampleDay = (id, daysAgo, bristolType) => ({
+  id,
+  occurredAt: new Date(Date.now() - daysAgo * 86400000).toISOString(),
+  bristolType,
+  color: 'brown',
+  urgency: 1,
+  discomfort: 1,
+  note: '',
+  photoDataUrl: '',
+  symptoms: {},
+});
+await caption('The journal explains its own pattern lines instead of just asserting a trend', 2200);
+await seedSyntheticLedger([
+  sampleDay('demo-firm', 2, 2),
+  sampleDay('demo-typical-1', 5, 3),
+  sampleDay('demo-typical-2', 9, 4),
+  sampleDay('demo-typical-3', 12, 4),
+  sampleDay('demo-old', 40, 6),
+]);
+await caption("Fictional sample logs are seeded into this browser's own storage — no real health data appears here", 2600);
+await page.locator('[data-pattern-summary]').waitFor();
+await indicate('[data-pattern-summary]');
+await caption('The summary says which confirmed logs it read, and a citation opens exactly those records', 2400);
+await indicate('[data-statement="typical"]');
+await tap('[data-statement-link="typical"]', 650);
+const citedRecords = await page.locator('[data-summary-record]').evaluateAll(nodes => nodes.map(node => node.getAttribute('data-entry-id')).sort());
+if (JSON.stringify(citedRecords) !== JSON.stringify(['demo-typical-1', 'demo-typical-2', 'demo-typical-3'])) {
+  throw new Error('A summary citation must list exactly the records it cites');
+}
+await caption('Every pattern line names the confirmed logs behind it, and following one shows exactly those records', 2900);
+await indicate('[data-summary-records]');
+await tap('#pattern-records-close', 450);
+await seedSyntheticLedger([sampleDay('demo-sparse-1', 1, 4), sampleDay('demo-sparse-2', 4, 6)]);
+await page.locator('[data-summary-insufficient]').waitFor();
+await indicate('[data-summary-insufficient]');
+await caption('Two logs is not a pattern: the summary refuses to describe a trend it cannot support', 2900);
+// Restore the empty ledger the earlier scenes started from, so the rest of the recording is unchanged.
+await page.evaluate(() => localStorage.clear());
+await page.reload({ waitUntil: 'networkidle' });
+
 await caption('The threat model documents this surface, so the recording shows it live rather than describing it', 2200);
 await tap('[data-view="calendar"]', 550);
 await page.getByText(/Your private journal/i).waitFor();
@@ -242,7 +400,14 @@ await page.evaluate(() => {
 });
 await sleep(2200);
 
-if (errors.length) throw new Error(`Browser errors: ${errors.join(' | ')}`);
+// The refusal pass deliberately produces two fail-closed 503s (an out-of-range reply, and one blank field
+// beside an out-of-range one), which the browser logs as failed resources. Requiring exactly those two
+// keeps the scene honest: if the boundary stops refusing, this fails instead of quietly recording a happy
+// path, and a dropped scene is caught rather than silently shrinking the evidence.
+const expectedFailClosed = errors.filter(message => /Failed to load resource: the server responded with a status of 503 \(Service Unavailable\)/.test(message));
+if (expectedFailClosed.length !== 2 || errors.length !== expectedFailClosed.length) {
+  throw new Error(`Browser errors: ${errors.join(' | ') || 'unexpected error count'}`);
+}
 // Machine-readable receipt of exactly what was rendered on camera, so the release gate can prove
 // the recorded delta statement reached the screen instead of trusting the script source.
 if (captionsOut) {

scripts/record_worker_benchmark.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// Record the target-GPU cost of the pinned worker (issue #15).
+//
+// This script measures; it never invents. If no GPU can be probed, if the pinned model is not
+// loaded, or if the cold start cannot be observed, it exits non-zero and writes no receipt at all,
+// because a receipt with zeroed or assumed numbers is worse than no receipt.
+import { spawn } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const LOOPBACK = /^(127\.0\.0\.1|localhost|::1)$/;
+
+function parseArgs(argv) {
+  const options = {
+    out: '',
+    host: '127.0.0.1',
+    port: '8080',
+    alias: 'SmolVLM2-2.2B-Instruct',
+    gpuProbe: 'nvidia-smi',
+    warmSamples: 20,
+    startCommand: '',
+    readyTimeoutSeconds: 900,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const [flag, inline] = argv[index].split('=');
+    const value = inline ?? argv[index + 1];
+    const consume = inline === undefined ? 2 : 1;
+    if (flag === '--out') options.out = value;
+    else if (flag === '--host') options.host = value;
+    else if (flag === '--port') options.port = value;
+    else if (flag === '--alias') options.alias = value;
+    else if (flag === '--gpu-probe') options.gpuProbe = value;
+    else if (flag === '--warm-samples') options.warmSamples = Number(value);
+    else if (flag === '--start-command') options.startCommand = value;
+    else if (flag === '--ready-timeout') options.readyTimeoutSeconds = Number(value);
+    else fail(`Unknown argument: ${flag}`);
+    index += consume - 1;
+  }
+  return options;
+}
+
+function fail(message, code = 64) {
+  process.stderr.write(`${message}\n`);
+  process.exit(code);
+}
+
+const reject = message => {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+};
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+async function modelsServed({ host, port, alias }) {
+  try {
+    const response = await fetch(`http://${host}:${port}/v1/models`, { signal: AbortSignal.timeout(3000) });
+    if (!response.ok) return false;
+    const body = await response.json();
+    const ids = Array.isArray(body?.data) ? body.data.map(item => item?.id).filter(Boolean) : [];
+    return ids.some(id => id === alias || id.includes(alias));
+  } catch {
+    return false;
+  }
+}
+
+function runCommand(command, args) {
+  return new Promise(resolve => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.on('error', error => resolve({ code: 127, stdout, stderr: String(error.message) }));
+    child.on('close', code => resolve({ code, stdout, stderr }));
+  });
+}
+
+async function probeGpu(probeCommand) {
+  const result = await runCommand(probeCommand, [
+    '--query-gpu=name,memory.total,memory.used',
+    '--format=csv,noheader,nounits',
+  ]);
+  if (result.code !== 0) {
+    reject(`No GPU could be probed with ${probeCommand}: ${result.stderr.trim() || `exit ${result.code}`}. A benchmark receipt needs a real device, so nothing was written.`);
+  }
+  const [name, total, used] = result.stdout.trim().split('\n')[0].split(',').map(part => part.trim());
+  if (!name || !/^\d+$/.test(total) || !/^\d+$/.test(used)) {
+    reject(`The GPU probe returned unreadable output (${JSON.stringify(result.stdout.trim())}); refusing to record VRAM it cannot read.`);
+  }
+  return { name, vramTotalMiB: Number(total), vramUsedMiB: Number(used) };
+}
+
+function percentile(sorted, fraction) {
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(fraction * sorted.length) - 1));
+  return sorted[index];
+}
+
+const options = parseArgs(process.argv.slice(2));
+if (!options.out) fail('--out is required so the receipt has a destination');
+if (!LOOPBACK.test(options.host)) fail(`The worker is a loopback service; refusing to benchmark ${options.host}.`);
+if (!Number.isInteger(options.warmSamples) || options.warmSamples < 1) fail('--warm-samples must be a positive integer');
+
+const receipts = JSON.parse(await readFile(fileURLToPath(new URL('../deploy/worker/receipts.json', import.meta.url)), 'utf8'));
+
+// The device is probed first: nothing is timed until we know the numbers have somewhere to be real.
+const gpu = await probeGpu(options.gpuProbe);
+
+if (!(await modelsServed(options))) {
+  reject(`${options.alias} is not loaded on ${options.host}:${options.port} yet, so there is no ready worker to time. Start the worker and wait for the post-load gate.`);
+}
+
+let coldStartMs = null;
+if (options.startCommand) {
+  const started = Date.now();
+  const started_process = await runCommand('bash', ['-c', options.startCommand]);
+  if (started_process.code !== 0) {
+    reject(`The cold-start command failed (exit ${started_process.code}): ${started_process.stderr.trim()}`);
+  }
+  const deadline = Date.now() + options.readyTimeoutSeconds * 1000;
+  let ready = false;
+  while (Date.now() < deadline) {
+    if (await modelsServed(options)) { ready = true; break; }
+    await sleep(250);
+  }
+  if (!ready) reject(`The worker did not become ready within ${options.readyTimeoutSeconds}s, so the cold start could not be measured.`);
+  coldStartMs = Date.now() - started;
+}
+
+const samples = [];
+for (let index = 0; index < options.warmSamples; index += 1) {
+  const started = process.hrtime.bigint();
+  const ok = await modelsServed(options);
+  const elapsedMs = Number(process.hrtime.bigint() - started) / 1e6;
+  if (!ok) reject('The worker stopped answering during the warm pass; the receipt would be partial, so nothing was written.');
+  samples.push(Math.round(elapsedMs * 1000) / 1000);
+}
+const sorted = [...samples].sort((left, right) => left - right);
+
+const receipt = {
+  schemaVersion: 1,
+  status: 'measured_on_target_gpu',
+  measuredAt: new Date().toISOString(),
+  gpu,
+  coldStartMs,
+  warmLatencyMs: {
+    samples: sorted.length,
+    min: sorted[0],
+    p50: percentile(sorted, 0.5),
+    p95: percentile(sorted, 0.95),
+    max: sorted[sorted.length - 1],
+  },
+  worker: { baseUrl: `http://${options.host}:${options.port}/v1`, alias: options.alias },
+  pins: {
+    llamaCppCommit: receipts.llamaCpp.commit,
+    modelSha256: receipts.models.map(model => model.sha256),
+  },
+};
+
+await writeFile(path.resolve(options.out), `${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
+process.stdout.write(`${path.resolve(options.out)}\n`);

scripts/worker_ready.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Post-load readiness gate for Timmy's self-hosted vision worker (issue #15).
+#
+# A worker that answers on its port is not necessarily a worker that can answer: llama.cpp opens
+# its HTTP listener before the model finishes loading and returns an error until the weights are
+# resident. Readiness therefore passes only when the pinned model alias is actually served.
+#
+# Exit codes:
+#   0  ready — the pinned model is loaded and being served
+#   2  the worker is not reachable
+#   3  the worker is reachable but the pinned model is not loaded yet
+#  64  usage error (including a non-loopback probe host)
+set -uo pipefail
+
+HOST="${TIMMY_MODEL_HOST:-127.0.0.1}"
+PORT="${TIMMY_MODEL_PORT:-8080}"
+ALIAS="${TIMMY_MODEL_ALIAS:-SmolVLM2-2.2B-Instruct}"
+WAIT=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --host) HOST="${2:-}"; shift 2 ;;
+    --port) PORT="${2:-}"; shift 2 ;;
+    --alias) ALIAS="${2:-}"; shift 2 ;;
+    --wait) WAIT="${2:-}"; shift 2 ;;
+    *)
+      printf 'Usage: %s [--host H] [--port P] [--alias A] [--wait SECONDS]\n' "$0" >&2
+      exit 64
+      ;;
+  esac
+done
+
+# The worker is a private, loopback-only service. Probing anything else would be a mistake about
+# exposure, so refuse rather than answer about a host this gate is not responsible for.
+if [[ ! "$HOST" =~ ^(127\.0\.0\.1|localhost|::1)$ ]]; then
+  printf 'Readiness must be probed on loopback, got %s\n' "$HOST" >&2
+  exit 64
+fi
+
+deadline=$(( $(date +%s) + WAIT ))
+outcome='unreachable'
+while :; do
+  body="$(curl --silent --max-time 3 "http://$HOST:$PORT/v1/models" 2>/dev/null)"
+  if [[ $? -eq 0 && -n "$body" ]]; then
+    if printf '%s' "$body" | grep -q -- "$ALIAS"; then
+      printf 'Worker ready: %s is loaded on http://%s:%s/v1\n' "$ALIAS" "$HOST" "$PORT"
+      exit 0
+    fi
+    outcome='not-loaded'
+    printf 'Worker reachable on http://%s:%s/v1 but %s is not loaded yet.\n' "$HOST" "$PORT" "$ALIAS" >&2
+  else
+    outcome='unreachable'
+    printf 'Worker not reachable on http://%s:%s/v1.\n' "$HOST" "$PORT" >&2
+  fi
+  [[ "$(date +%s)" -ge "$deadline" ]] && break
+  sleep 1
+done
+
+[[ "$outcome" == 'not-loaded' ]] && exit 3
+exit 2

server.mjs

@@ -3,7 +3,7 @@ import { isIP } from 'node:net';
 import { readFile, stat } from 'node:fs/promises';
 import { extname, join, normalize } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { analyzePhoto } from './src/vision-service.js';
+import { analyzePhoto, visionFailureResponse } from './src/vision-service.js';
 import { probeVisionProvider, resolveVisionConfig } from './src/vision-config.js';
 import { AgentGatewayError, createHermesAgentService, resolveHermesAgentConfig } from './src/hermes-agent-service.js';
 
@@ -55,7 +55,7 @@ http.createServer(async(req,res)=>{
    if(!visionConfig.enabled)return sendJson(res,503,{error:'AI analysis is disabled. Continue manually.'});
    const payload=await readJson(req);
    try{return sendJson(res,200,await analyzePhoto({payload,config:visionConfig}))}
-   catch(error){const safe=/consent|JPEG|PNG|WebP|empty|too large/i.test(error.message);return sendJson(res,safe?400:503,{error:error.message})}
+   catch(error){const failure=visionFailureResponse(error);return sendJson(res,failure.status,failure.body)}
   }
   if(appPath==='/api/agent/status'&&req.method==='GET')return sendJson(res,200,agentService.status(cookie(req,'timmy_agent')));
   if(appPath==='/api/agent/unlock'&&req.method==='POST'){

src/analysis.js

@@ -2,32 +2,60 @@ const COLORS = new Set(['brown', 'green', 'yellow', 'pale', 'red', 'black']);
 const QUALITIES = new Set(['good', 'fair', 'poor']);
 const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
 
+// Fail-closed responses carry a code so the server boundary and the corpus can name the failure
+// class without matching on prose.
+export const VISION_FAILURE_CODES = Object.freeze({ invalidJson: 'invalid_json', invalidFields: 'invalid_fields' });
+
+function visionResponseError(code, message) {
+  const error = new Error(message);
+  error.name = 'VisionResponseError';
+  error.code = code;
+  return error;
+}
+
 function asObject(raw) {
   if (raw && typeof raw === 'object' && !Array.isArray(raw)) return raw;
-  if (typeof raw !== 'string') throw new Error('Invalid AI response.');
+  if (typeof raw !== 'string') throw visionResponseError(VISION_FAILURE_CODES.invalidJson, 'Invalid AI response.');
   const cleaned = raw.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
   try {
     const parsed = JSON.parse(cleaned);
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error();
     return parsed;
   } catch {
-    throw new Error('Invalid AI response.');
+    throw visionResponseError(VISION_FAILURE_CODES.invalidJson, 'Invalid AI response.');
   }
 }
 
 export function parseVisionResponse(raw) {
   const value = asObject(raw);
-  if (typeof value.isStool !== 'boolean') throw new Error('Invalid AI response: isStool is required.');
+  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 new Error('Invalid AI response: confidence is required.');
-  if (!value.isStool) return { status: 'needs_user_input', isStool: false, reason: 'The image does not clearly show stool.' };
-  if (confidence < 0.55) return { status: 'needs_user_input', isStool: true, reason: 'The image is too uncertain to prefill safely.' };
-  const bristolType = Number(value.bristolType);
-  const color = String(value.color || '').toLowerCase();
-  const imageQuality = String(value.imageQuality || '').toLowerCase();
-  if (!Number.isInteger(bristolType) || bristolType < 1 || bristolType > 7 || !COLORS.has(color) || !QUALITIES.has(imageQuality)) {
-    throw new Error('Invalid AI response: visual fields are out of range.');
+  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.' };
+  // 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
+  // contract the response fails closed, even when the other field is blank (#73), because a caller
+  // reading `unusable_visual_fields` would be told the photo was unreadable when the model had in
+  // fact returned an impossible value.
+  const blank = input => input === null || input === undefined || (typeof input === 'string' && !input.trim());
+  const bristolType = blank(value.bristolType) ? null : Number(value.bristolType);
+  const color = blank(value.color) ? null : String(value.color).toLowerCase();
+  if ((bristolType !== null && (!Number.isInteger(bristolType) || bristolType < 1 || bristolType > 7))
+    || (color !== null && !COLORS.has(color))) {
+    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.',
+    };
+  }
+  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.');
   return {
     status: 'suggestion',
     isStool: true,

src/summary.js

@@ -0,0 +1,76 @@
+import { bucketForBristolType } from './domain.js';
+
+export const PATTERN_WINDOW_DAYS = 28;
+// Two logs are an anecdote. Below this the summary is required to say so instead of describing a trend.
+export const MIN_WINDOW_LOGS = 3;
+
+const DAY_MS = 86400000;
+
+// The summary may only describe what the user recorded. No cause, no health verdict, no food ruling.
+const BOUNDARY = 'Built only from your own confirmed records in this window. Timmy reports what you logged and when — not why, and never a verdict on your health or your food.';
+
+function inWindowRecords(entries, now, windowDays) {
+  const startedAt = now - windowDays * DAY_MS;
+  return (Array.isArray(entries) ? entries : [])
+    .map(entry => ({ entry, at: new Date(entry?.occurredAt).getTime() }))
+    .filter(({ at }) => Number.isFinite(at) && at <= now && at >= startedAt)
+    .sort((left, right) => left.at - right.at)
+    .map(({ entry, at }) => ({
+      id: String(entry?.id ?? ''),
+      occurredAt: new Date(at).toISOString(),
+      bristolType: Number(entry?.bristolType),
+      bucket: bucketForBristolType(entry?.bristolType),
+    }));
+}
+
+export function buildPatternSummary(entries = [], { now = Date.now(), windowDays = PATTERN_WINDOW_DAYS } = {}) {
+  const records = inWindowRecords(entries, now, windowDays);
+  const window = {
+    days: windowDays,
+    label: `last ${windowDays} days`,
+    start: new Date(now - windowDays * DAY_MS).toISOString(),
+    end: new Date(now).toISOString(),
+  };
+
+  if (records.length < MIN_WINDOW_LOGS) {
+    return {
+      window,
+      records,
+      insufficient: true,
+      statements: [],
+      boundary: BOUNDARY,
+      copy: `Not enough confirmed logs in this window yet — ${records.length} of ${MIN_WINDOW_LOGS} needed before Timmy describes a pattern.`,
+    };
+  }
+
+  const frequency = {
+    id: 'frequency',
+    text: `${records.length} confirmed log${records.length === 1 ? '' : 's'} in the ${window.label}.`,
+    entryIds: records.map(record => record.id),
+  };
+
+  const buckets = new Map();
+  for (const record of records) {
+    if (!buckets.has(record.bucket)) buckets.set(record.bucket, []);
+    buckets.get(record.bucket).push(record.id);
+  }
+  const bucketLine = (bucket, label) => ({
+    id: bucket === 'constipation' ? 'firm' : bucket,
+    text: `${label}: ${buckets.get(bucket).length} of ${records.length} confirmed log${records.length === 1 ? '' : 's'}.`,
+    entryIds: buckets.get(bucket),
+  });
+  const formLines = [
+    ['constipation', 'Firm side (Type 1–2)'],
+    ['typical', 'Typical range (Type 3–4)'],
+    ['loose', 'Loose side (Type 5–7)'],
+  ].filter(([bucket]) => buckets.has(bucket)).map(([bucket, label]) => bucketLine(bucket, label));
+  // Both ends in one window is not a trend, and the summary has to say so out loud rather than
+  // picking whichever side is marginally larger.
+  const mixedLine = buckets.has('constipation') && buckets.has('loose') ? [{
+    id: 'mixed',
+    text: `Firm and loose logs both appear in the ${window.label} (${buckets.get('constipation').length} firm, ${buckets.get('loose').length} loose), which is a mixed pattern and not one trend.`,
+    entryIds: records.filter(record => record.bucket === 'constipation' || record.bucket === 'loose').map(record => record.id),
+  }] : [];
+
+  return { window, records, insufficient: false, statements: [frequency, ...formLines, ...mixedLine], copy: '', boundary: BOUNDARY };
+}

src/vision-corpus.js

@@ -0,0 +1,111 @@
+// Contract for the deterministic vision corpus under tests/fixtures/vision-corpus.
+//
+// The corpus exists to prove one claim continuously: every provider response Timmy
+// receives is either a schema-valid visible-field suggestion or it fails closed.
+// Fixtures are synthetic images generated by scripts/build_vision_corpus.py; no real
+// medical imagery, personal data, or third-party content is redistributable here.
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { parseVisionResponse, VISION_FAILURE_CODES } from './analysis.js';
+
+export const VISION_CORPUS_LICENSE = 'CC0-1.0';
+
+// Case classes the corpus must always cover, from issue #18.
+export const VISION_CORPUS_CLASSES = Object.freeze([
+  'stool',
+  'non-stool',
+  'blur',
+  'glare',
+  'empty-bowl',
+  'malformed-response',
+]);
+
+export const VISION_CORPUS_OUTCOMES = Object.freeze(['suggestion', 'abstained', 'fail_closed']);
+
+const ALLOWED_CLASSES = new Set(VISION_CORPUS_CLASSES);
+
+export function validateCorpusManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object') throw new Error('vision corpus manifest must be an object');
+  if (manifest.schemaVersion !== 1) throw new Error('vision corpus manifest must declare schemaVersion 1');
+  if (manifest.license !== VISION_CORPUS_LICENSE) {
+    throw new Error(`vision corpus must be redistributable under ${VISION_CORPUS_LICENSE}`);
+  }
+  if (!Array.isArray(manifest.cases) || manifest.cases.length === 0) throw new Error('vision corpus must list cases');
+  const ids = new Set();
+  for (const entry of manifest.cases) {
+    if (!entry?.id) throw new Error('every corpus case needs an id');
+    if (ids.has(entry.id)) throw new Error(`duplicate corpus case: ${entry.id}`);
+    ids.add(entry.id);
+    if (!ALLOWED_CLASSES.has(entry.caseClass)) throw new Error(`${entry.id} has an unsupported caseClass: ${entry.caseClass}`);
+    if (entry.synthetic !== true) throw new Error(`${entry.id} must be a synthetic fixture`);
+    if (entry.license !== VISION_CORPUS_LICENSE) throw new Error(`${entry.id} must record its ${VISION_CORPUS_LICENSE} license`);
+    if (typeof entry.provenance !== 'string' || !entry.provenance.trim()) throw new Error(`${entry.id} must record provenance`);
+    if (!/^[a-f0-9]{64}$/.test(String(entry.sha256 || ''))) throw new Error(`${entry.id} must record a sha256`);
+    if (!VISION_CORPUS_OUTCOMES.includes(entry.expectedOutcome)) {
+      throw new Error(`${entry.id} must declare an expectedOutcome from ${VISION_CORPUS_OUTCOMES.join(', ')}`);
+    }
+    if (!('providerContent' in entry)) throw new Error(`${entry.id} must record the provider response it replays`);
+  }
+  for (const required of VISION_CORPUS_CLASSES) {
+    if (!manifest.cases.some(entry => entry.caseClass === required)) {
+      throw new Error(`vision corpus is missing the required ${required} case`);
+    }
+  }
+  return manifest;
+}
+
+export function classifyVisionOutcome(providerContent) {
+  let parsed;
+  try {
+    parsed = parseVisionResponse(providerContent);
+  } catch (error) {
+    const reason = error?.code === VISION_FAILURE_CODES.invalidJson
+      ? 'unparsable_content'
+      : error?.code === VISION_FAILURE_CODES.invalidFields
+        ? 'out_of_range_or_missing_fields'
+        : 'unexpected_error';
+    return { outcome: 'fail_closed', reason, detail: error.message };
+  }
+  if (parsed.status === 'suggestion') {
+    return {
+      outcome: 'suggestion',
+      reason: 'schema_valid_suggestion',
+      bristolType: parsed.bristolType,
+      color: parsed.color,
+      confidence: parsed.confidence,
+    };
+  }
+  if (parsed.status === 'needs_user_input') {
+    return {
+      outcome: 'abstained',
+      reason: parsed.abstainedFor,
+      detail: parsed.reason,
+    };
+  }
+  return { outcome: 'fail_closed', reason: 'unparsable_content', detail: 'The response could not be used.' };
+}
+
+export async function loadVisionCorpus(directory) {
+  const manifestPath = join(directory, 'manifest.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`vision corpus manifest could not be read at ${manifestPath}: ${error.message}`);
+  }
+  validateCorpusManifest(manifest);
+  for (const entry of manifest.cases) {
+    let bytes;
+    try {
+      bytes = await readFile(join(directory, entry.file));
+    } catch {
+      throw new Error(`${entry.id} is missing its fixture ${entry.file}`);
+    }
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    if (digest !== entry.sha256 || bytes.length !== entry.bytes) {
+      throw new Error(`${entry.id} fixture ${entry.file} does not match its recorded sha256; regenerate the corpus instead of editing it`);
+    }
+  }
+  return { ...manifest, directory };
+}

src/vision-readiness.js

@@ -31,5 +31,17 @@ export function visionReadiness(status) {
       message: 'Vision worker offline. Manual logging is still available.',
     };
   }
+  // A worker that answers /v1/models has not necessarily loaded the model yet (#15), so readiness
+  // passes only once the pinned model is confirmed loaded. An unconfirmed model fails closed to the
+  // manual path instead of offering an AI control that fails after the upload.
+  if (status.modelSeen !== true) {
+    return {
+      phase: 'loading',
+      ready: false,
+      manualOnly: true,
+      manualLabel: MANUAL_LABEL,
+      message: 'The vision worker is up but the model is not loaded yet. Manual logging is available.',
+    };
+  }
   return { phase: 'ready', ready: true, manualOnly: false, manualLabel: '', message: '' };
 }

src/vision-service.js

@@ -1,4 +1,17 @@
-import { buildVisionRequest, parseVisionResponse, validatePhotoPayload } from './analysis.js';
+import { buildVisionRequest, parseVisionResponse, validatePhotoPayload, VISION_FAILURE_CODES } from './analysis.js';
+
+// One place decides what a failed analysis request returns, so the browser copy is testable and a
+// provider's own words never reach the user.
+const FAIL_CLOSED_COPY = 'No suggestion was applied. Continue manually, or try a clearer photo.';
+const INPUT_REJECTION = /consent|JPEG|PNG|WebP|empty|too large/i;
+
+export function visionFailureResponse(error) {
+  const message = String(error?.message || '');
+  if (INPUT_REJECTION.test(message)) return { status: 400, body: { error: message } };
+  const schemaFailure = error?.code === VISION_FAILURE_CODES.invalidJson || error?.code === VISION_FAILURE_CODES.invalidFields;
+  if (schemaFailure) return { status: 503, body: { error: FAIL_CLOSED_COPY } };
+  return { status: 503, body: { error: message || 'AI analysis is temporarily unavailable. Continue manually.' } };
+}
 
 function providerEndpoint(baseUrl) {
   let url;

styles.css

@@ -18,7 +18,7 @@ main{display:block}.eyebrow{font-size:11px;font-weight:800;letter-spacing:.1em;t
 .chat-page{display:flex;flex-direction:column;min-height:calc(100vh - 175px)}.chat-title{padding-bottom:8px}.agent-status{display:flex;align-items:center;gap:11px;padding:11px 13px;background:rgba(255,253,250,.7);border:1px solid var(--line);border-radius:17px;margin-bottom:12px}.agent-status>i{width:10px;height:10px;border-radius:50%;background:#a9a39d;box-shadow:0 0 0 5px rgba(169,163,157,.13)}.agent-status.connected>i{background:#209479;box-shadow:0 0 0 5px rgba(32,148,121,.13)}.agent-status.locked>i{background:#d19b27}.agent-status strong,.agent-status small{display:block}.agent-status strong{font-size:13px}.agent-status small{font-size:11px;color:var(--muted);margin-top:2px}.conversation{background:var(--surface);border:1px solid var(--line);border-radius:23px;padding:13px;box-shadow:0 10px 30px rgba(55,40,31,.05)}.chat{display:flex;flex-direction:column;gap:9px;min-height:195px;max-height:42vh;overflow:auto;padding:4px 1px 14px}.bubble{max-width:86%;padding:11px 13px;border-radius:17px;line-height:1.42;font-size:14px;white-space:pre-wrap}.bubble.timmy{align-self:flex-start;background:#efebe4;border-bottom-left-radius:5px}.bubble.user{align-self:flex-end;background:var(--teal);color:white;border-bottom-right-radius:5px}.thinking{display:flex;gap:4px}.thinking span{width:6px;height:6px;border-radius:50%;background:#8b847d;animation:blink 1s infinite}.thinking span:nth-child(2){animation-delay:.15s}.thinking span:nth-child(3){animation-delay:.3s}@keyframes blink{50%{opacity:.25;transform:translateY(-2px)}}.composer{display:grid;grid-template-columns:1fr 45px;gap:8px;align-items:end;background:#f0ece5;border-radius:18px;padding:6px}.composer textarea{border:0;background:transparent;resize:none;min-height:42px;max-height:110px;padding:10px 9px;outline:0;color:var(--ink)}.composer button{width:44px;height:44px;border:0;border-radius:14px;background:var(--ink);color:white;font-size:22px;cursor:pointer}.composer button:disabled{opacity:.4}.composer-note{font-size:10px;color:var(--muted);margin:7px 5px 0;line-height:1.35}.chat-error{font-size:12px;color:var(--red);margin:0 4px 8px}.safety-line{margin:13px 4px 0;color:var(--muted);font-size:11px;line-height:1.45}.safety-line strong{color:var(--ink)}.unlock-card{background:#fff8e6;border:1px solid #ead9a9;border-radius:20px;padding:14px;margin-bottom:12px}.unlock-card>label{display:block;font-size:12px;font-weight:800;margin-bottom:7px}.unlock-row{display:grid;grid-template-columns:1fr auto;gap:8px}.unlock-card .fine{margin:8px 2px 0}
 .sheet-backdrop{position:fixed;inset:0;background:rgba(28,22,18,.42);display:flex;align-items:flex-end;justify-content:center;z-index:50;padding-top:28px;backdrop-filter:blur(5px)}.sheet{width:min(100%,680px);max-height:94vh;overflow:auto;background:var(--surface);border-radius:28px 28px 0 0;padding:9px 18px calc(24px + env(safe-area-inset-bottom));box-shadow:0 -15px 50px rgba(30,22,18,.2)}.sheet-handle{width:38px;height:4px;background:#d8d1c8;border-radius:999px;margin:2px auto 15px}.sheet-header{display:flex;justify-content:space-between;align-items:flex-start;gap:12px}.sheet-header h2{margin-top:4px}.icon-btn{width:44px;height:44px;border:0;border-radius:50%;background:#efebe5;font-size:24px;cursor:pointer}.progress{height:4px;background:#eee8df;border-radius:99px;margin:7px 0 18px;overflow:hidden}.progress i{height:100%;display:block;background:var(--teal)}.progress-step-1{width:33.34%}.progress-step-2{width:66.68%}.progress-step-3{width:100%}
 .draft-resume{display:flex;align-items:center;justify-content:space-between;gap:10px;background:#fdf3d8;border:1px solid #ecd9a3;border-radius:14px;padding:8px 11px;margin:0 0 14px;font-size:12px;line-height:1.35;color:#5d4a12}.draft-resume strong{font-weight:800}
-.scan-hero{text-align:center;padding:3px 15px 12px}.scan-hero img{width:76px}.scan-hero h3{font-size:19px;margin:4px 0 7px}.scan-hero p{font-size:13px;line-height:1.45;color:var(--muted)}.model-status{border-radius:14px;padding:9px 11px;font-size:11px;font-weight:700;margin-bottom:12px}.model-status.ready{background:var(--teal-soft);color:var(--teal)}.model-status.offline{background:var(--red-soft);color:var(--red)}.model-status.checking{background:#f0ece5;color:var(--muted)}.capture-choice-grid{display:grid;grid-template-columns:1fr 1fr;gap:10px}.capture-status{background:var(--red-soft);color:var(--red);border-radius:14px;padding:10px 12px;font-size:12px;line-height:1.4}.photo-capture{display:grid;place-items:center;text-align:center;border:1.5px dashed #b9aea1;border-radius:21px;padding:16px 10px;background:#faf7f1;cursor:pointer}.photo-capture b{font-size:30px}.photo-capture strong{margin:6px 0 2px}.photo-capture span{font-size:11px;color:var(--muted)}.photo-capture input{display:none}.photo-preview{display:block;width:100%;max-height:250px;object-fit:cover;border-radius:18px;margin:10px 0}.quality-note{font-size:12px;color:var(--muted)}.consent-card{background:#f5f1e9;border-radius:18px;padding:12px;margin:12px 0}.check{display:flex;gap:11px;align-items:flex-start;padding:9px 0}.check input{width:20px;height:20px;accent-color:var(--teal);flex:0 0 auto}.check span{font-size:13px;line-height:1.4}.analyzing{text-align:center;padding:33px 10px}.analyzing img{width:86px}.spinner{width:32px;height:32px;border:3px solid var(--soft);border-top-color:var(--teal);border-radius:50%;animation:spin .8s linear infinite;margin:10px auto}@keyframes spin{to{transform:rotate(360deg)}}.analyzing p{font-size:13px;color:var(--muted)}.scan-result{background:var(--teal-soft);border-radius:20px;padding:17px;margin-bottom:13px}.scan-result.needs-input{background:#f2eee7;text-align:center}.scan-result.needs-input>b{font-size:28px}.scan-result p{font-size:13px;line-height:1.45;margin:9px 0 0}.ai-badge{font-size:10px;font-weight:850;letter-spacing:.08em;color:var(--teal)}.suggestion-pair{display:grid;grid-template-columns:1fr 1fr;gap:9px;margin-top:12px}.suggestion-pair>div{background:var(--surface);padding:12px;border-radius:14px}.suggestion-pair small,.suggestion-pair strong{display:block}.suggestion-pair small{font-size:9px;color:var(--muted)}.suggestion-pair strong{font-size:18px;margin-top:2px}.ai-prefill{background:var(--teal-soft);border-radius:16px;padding:11px 13px;margin-bottom:12px}.ai-prefill strong,.ai-prefill small{display:block}.ai-prefill small{color:var(--muted);margin-top:3px}.choice-grid{display:grid;grid-template-columns:1fr 1fr;gap:8px}.bristol{min-height:66px;border:1px solid var(--line);background:#f7f3ed;border-radius:16px;padding:10px;text-align:left;cursor:pointer}.bristol strong,.bristol span{display:block}.bristol span{font-size:11px;color:var(--muted);margin-top:2px}.bristol.selected{background:var(--ink);color:white}.bristol.selected span{color:#ddd}.field{display:block;margin-bottom:15px}.field-label{display:block;font-size:12px;font-weight:800;margin-bottom:6px}.input{width:100%;min-height:48px;border:1px solid var(--line);border-radius:14px;background:#f8f5ef;padding:10px 12px;color:var(--ink)}textarea.input{min-height:85px;resize:vertical}.range-row{display:grid;grid-template-columns:1fr 37px;gap:10px;align-items:center}.range-row input{accent-color:var(--teal)}.range-val{width:37px;height:37px;border-radius:12px;background:var(--soft);display:grid;place-items:center;font-weight:800}.photo-drop{width:100%;background:#f3eee7}.symptoms{display:flex;flex-direction:column}.alert{background:var(--red-soft);border:1px solid #eec1ba;border-radius:16px;padding:13px;color:#75261f}.alert p{margin:5px 0 0;font-size:13px;line-height:1.4}
+.scan-hero{text-align:center;padding:3px 15px 12px}.scan-hero img{width:76px}.scan-hero h3{font-size:19px;margin:4px 0 7px}.scan-hero p{font-size:13px;line-height:1.45;color:var(--muted)}.model-status{border-radius:14px;padding:9px 11px;font-size:11px;font-weight:700;margin-bottom:12px}.model-status.ready{background:var(--teal-soft);color:var(--teal)}.model-status.offline{background:var(--red-soft);color:var(--red)}.model-status.loading{background:#fdf3d8;color:#5d4a12}.capture-choice-grid{display:grid;grid-template-columns:1fr 1fr;gap:10px}.capture-status{background:var(--red-soft);color:var(--red);border-radius:14px;padding:10px 12px;font-size:12px;line-height:1.4}.photo-capture{display:grid;place-items:center;text-align:center;border:1.5px dashed #b9aea1;border-radius:21px;padding:16px 10px;background:#faf7f1;cursor:pointer}.photo-capture b{font-size:30px}.photo-capture strong{margin:6px 0 2px}.photo-capture span{font-size:11px;color:var(--muted)}.photo-capture input{display:none}.photo-preview{display:block;width:100%;max-height:250px;object-fit:cover;border-radius:18px;margin:10px 0}.quality-note{font-size:12px;color:var(--muted)}.consent-card{background:#f5f1e9;border-radius:18px;padding:12px;margin:12px 0}.check{display:flex;gap:11px;align-items:flex-start;padding:9px 0}.check input{width:20px;height:20px;accent-color:var(--teal);flex:0 0 auto}.check span{font-size:13px;line-height:1.4}.analyzing{text-align:center;padding:33px 10px}.analyzing img{width:86px}.spinner{width:32px;height:32px;border:3px solid var(--soft);border-top-color:var(--teal);border-radius:50%;animation:spin .8s linear infinite;margin:10px auto}@keyframes spin{to{transform:rotate(360deg)}}.analyzing p{font-size:13px;color:var(--muted)}.scan-result{background:var(--teal-soft);border-radius:20px;padding:17px;margin-bottom:13px}.scan-result.needs-input{background:#f2eee7;text-align:center}.scan-result.needs-input>b{font-size:28px}.scan-result p{font-size:13px;line-height:1.45;margin:9px 0 0}.ai-badge{font-size:10px;font-weight:850;letter-spacing:.08em;color:var(--teal)}.suggestion-pair{display:grid;grid-template-columns:1fr 1fr;gap:9px;margin-top:12px}.suggestion-pair>div{background:var(--surface);padding:12px;border-radius:14px}.suggestion-pair small,.suggestion-pair strong{display:block}.suggestion-pair small{font-size:9px;color:var(--muted)}.suggestion-pair strong{font-size:18px;margin-top:2px}.ai-prefill{background:var(--teal-soft);border-radius:16px;padding:11px 13px;margin-bottom:12px}.ai-prefill strong,.ai-prefill small{display:block}.ai-prefill small{color:var(--muted);margin-top:3px}.choice-grid{display:grid;grid-template-columns:1fr 1fr;gap:8px}.bristol{min-height:66px;border:1px solid var(--line);background:#f7f3ed;border-radius:16px;padding:10px;text-align:left;cursor:pointer}.bristol strong,.bristol span{display:block}.bristol span{font-size:11px;color:var(--muted);margin-top:2px}.bristol.selected{background:var(--ink);color:white}.bristol.selected span{color:#ddd}.field{display:block;margin-bottom:15px}.field-label{display:block;font-size:12px;font-weight:800;margin-bottom:6px}.input{width:100%;min-height:48px;border:1px solid var(--line);border-radius:14px;background:#f8f5ef;padding:10px 12px;color:var(--ink)}textarea.input{min-height:85px;resize:vertical}.range-row{display:grid;grid-template-columns:1fr 37px;gap:10px;align-items:center}.range-row input{accent-color:var(--teal)}.range-val{width:37px;height:37px;border-radius:12px;background:var(--soft);display:grid;place-items:center;font-weight:800}.photo-drop{width:100%;background:#f3eee7}.symptoms{display:flex;flex-direction:column}.alert{background:var(--red-soft);border:1px solid #eec1ba;border-radius:16px;padding:13px;color:#75261f}.alert p{margin:5px 0 0;font-size:13px;line-height:1.4}
 .privacy-list{display:flex;flex-direction:column;gap:4px}.privacy-item{display:grid;grid-template-columns:40px 1fr;gap:11px;padding:11px 0;border-bottom:1px solid var(--line)}.privacy-item:last-child{border-bottom:0}.privacy-item>b{width:38px;height:38px;border-radius:13px;background:var(--teal-soft);display:grid;place-items:center;color:var(--teal)}.privacy-item h3{margin-bottom:4px}.privacy-item p,.source-list p{font-size:13px;line-height:1.45;color:var(--muted);margin-bottom:5px}.source-list a{color:var(--teal)}.danger-zone{border-color:#e9c4bf}.toast{position:fixed;left:50%;bottom:96px;transform:translateX(-50%);background:var(--ink);color:white;border-radius:999px;padding:11px 16px;font-size:13px;font-weight:700;z-index:100;box-shadow:var(--shadow)}
 .staging-label{margin:8px auto 86px;text-align:center;color:var(--muted);font-size:10px;letter-spacing:.03em;opacity:.72}
 @media(min-width:560px){.app-shell{padding-inline:24px}.sleek-hero{padding-inline:10px}.choice-grid{grid-template-columns:repeat(3,1fr)}}
@@ -46,3 +46,9 @@ main{display:block}.eyebrow{font-size:11px;font-weight:800;letter-spacing:.1em;t
 .followup-guidance .fine{margin:8px 0 0}
 .followup-guidance.escalated{background:var(--red-soft);border-color:#eec1ba}
 .followup-guidance.escalated>strong{color:#75261f}
+.pattern-card{align-items:start}
+.pattern-window{margin:3px 0 6px;font-size:12px;font-weight:800;color:var(--teal);letter-spacing:.02em}
+.pattern-statements{margin:0;padding:0;list-style:none}
+.pattern-statements li{font-size:13.5px;line-height:1.45;margin-bottom:7px;color:#4d453e}
+.pattern-link{display:inline-block;margin-top:3px;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}
+.pattern-boundary{margin:8px 0 0;color:var(--muted)}

tests/analysis.test.js

@@ -37,14 +37,17 @@ test('validates a confident visual suggestion without inventing nonvisual fields
 });
 
 test('fails closed on a non-stool or low-confidence image', () => {
+  // abstainedFor names which abstention happened, so callers never have to parse prose.
   assert.deepEqual(parseVisionResponse({ isStool: false, confidence: 0.9 }), {
     status: 'needs_user_input',
     isStool: false,
+    abstainedFor: 'not_stool',
     reason: 'The image does not clearly show stool.',
   });
   assert.deepEqual(parseVisionResponse({ isStool: true, bristolType: 4, color: 'brown', confidence: 0.31 }), {
     status: 'needs_user_input',
     isStool: true,
+    abstainedFor: 'low_confidence',
     reason: 'The image is too uncertain to prefill safely.',
   });
 });
@@ -78,3 +81,53 @@ test('builds a structured multimodal request that forbids diagnosis and nonvisua
   assert.match(prompt, /not a diagnosis/i);
   assert.equal(body.messages[0].content.find(part => part.type === 'image_url').image_url.url, 'data:image/jpeg;base64,YQ==');
 });
+
+test('fails closed when a field the model did fill in is out of range while another field is blank', () => {
+  // Issue #73: the blank-first ordering let a blank field short-circuit the whole response, so a reply
+  // that carried an impossible value came back as `unusable_visual_fields` — telling the user the photo
+  // was unreadable when the model had in fact returned something Timmy must never apply. A blank field
+  // means "could not read it"; a filled-in field is a claim, and a claim outside the contract fails closed.
+  assert.throws(
+    () => parseVisionResponse({ isStool: true, bristolType: 9, color: null, confidence: 0.9, imageQuality: 'good', observations: 'Form read, colour not.' }),
+    (error) => {
+      assert.equal(error.code, 'invalid_fields', 'an out-of-range form next to a blank colour must fail closed');
+      return true;
+    },
+  );
+  assert.throws(
+    () => parseVisionResponse({ isStool: true, bristolType: null, color: 'purple', confidence: 0.9, imageQuality: 'good', observations: 'Colour read, form not.' }),
+    (error) => {
+      assert.equal(error.code, 'invalid_fields', 'an out-of-range colour next to a blank form must fail closed');
+      return true;
+    },
+  );
+});
+
+test('still abstains when the only filled-in visual field is inside the contract', () => {
+  // The complement of the rule above: a partial read that is entirely valid is an abstention, not a
+  // failure, so the glare path keeps returning 200 with nothing prefilled.
+  assert.deepEqual(parseVisionResponse({ isStool: true, bristolType: 4, color: null, confidence: 0.9, imageQuality: 'good', observations: 'Form read, colour not.' }), {
+    status: 'needs_user_input',
+    isStool: true,
+    abstainedFor: 'unusable_visual_fields',
+    reason: 'The photo does not show a form Timmy can read safely.',
+  });
+});
+
+test('abstains instead of failing when a schema-valid response carries no readable visual fields', () => {
+  // The declared JSON schema allows a null form and color whenever the model cannot read them,
+  // so a schema-valid response must come back as an abstention — never as a provider failure.
+  assert.deepEqual(parseVisionResponse({
+    isStool: true,
+    bristolType: null,
+    color: null,
+    confidence: 0.66,
+    imageQuality: 'poor',
+    observations: 'Large specular highlight hides the surface.',
+  }), {
+    status: 'needs_user_input',
+    isStool: true,
+    abstainedFor: 'unusable_visual_fields',
+    reason: 'The photo does not show a form Timmy can read safely.',
+  });
+});

tests/ci-workflow.test.js

@@ -98,3 +98,66 @@ test('diff hygiene checks only the pull request or latest commit range', async (
   assert.match(script, /HEAD\^\.\.HEAD/);
   assert.doesNotMatch(script, /hash-object -t tree/);
 });
+
+test('the vision corpus and its refusal boundary are unit-, browser-, and release-gated', async () => {
+  const [packageJsonText, workflow, builder] = await Promise.all([
+    readFile(packagePath, 'utf8'),
+    readFile(workflowPath, 'utf8'),
+    readFile(new URL('../scripts/build_release.py', import.meta.url), 'utf8'),
+  ]);
+  const packageJson = JSON.parse(packageJsonText);
+
+  assert.match(packageJson.scripts.test, /tests\/vision-corpus\.test\.js/);
+  assert.match(packageJson.scripts.test, /tests\/vision-boundary\.test\.js/);
+  assert.equal(packageJson.scripts['test:vision-refusal'], 'node tests/vision-refusal.acceptance.mjs');
+  assert.match(packageJson.scripts['check:syntax'], /node --check src\/vision-corpus\.js/);
+  assert.match(packageJson.scripts['check:syntax'], /node --check tests\/vision-refusal\.acceptance\.mjs/);
+  assert.match(packageJson.scripts['check:syntax'], /py_compile[^&]*scripts\/build_vision_corpus\.py/);
+  assert.match(workflow, /npm run test:vision-refusal/);
+  // The release builder must verify the committed corpus hashes and run the refusal suite itself.
+  assert.match(builder, /"test:vision-refusal"/);
+  assert.match(builder, /"vision_corpus_refusal": "passed"/);
+  assert.match(builder, /build_vision_corpus\.py", "--verify"/);
+});
+
+test('the pinned worker container, post-load gate, and GPU benchmark are gated end to end', async () => {
+  const [packageJsonText, workflow, builder] = await Promise.all([
+    readFile(packagePath, 'utf8'),
+    readFile(workflowPath, 'utf8'),
+    readFile(new URL('../scripts/build_release.py', import.meta.url), 'utf8'),
+  ]);
+  const packageJson = JSON.parse(packageJsonText);
+
+  assert.match(packageJson.scripts.test, /tests\/worker-container\.test\.js/);
+  assert.match(packageJson.scripts.test, /tests\/worker-ready\.test\.js/);
+  assert.match(packageJson.scripts.test, /tests\/worker-benchmark\.test\.js/);
+  assert.equal(packageJson.scripts['test:worker-readiness'], 'node tests/worker-readiness.acceptance.mjs');
+  assert.match(packageJson.scripts['check:syntax'], /node --check scripts\/record_worker_benchmark\.mjs/);
+  assert.match(packageJson.scripts['check:syntax'], /node --check tests\/worker-readiness\.acceptance\.mjs/);
+  for (const script of ['scripts/worker_ready.sh', 'deploy/worker/entrypoint.sh', 'deploy/worker/build_image.sh', 'deploy/worker/run_worker_container.sh']) {
+    assert.ok(packageJson.scripts['check:syntax'].includes(`bash -n ${script}`), `${script} must be syntax-gated`);
+  }
+  assert.match(workflow, /npm run test:worker-readiness/);
+  assert.match(builder, /"test:worker-readiness"/);
+  assert.match(builder, /"worker_container_receipts": "passed"/);
+  assert.match(builder, /"worker_post_load_readiness": "passed"/);
+  assert.match(builder, /"scripts\/worker_ready\.sh"/);
+});
+
+test('explainable pattern summaries are a unit-, browser-, and release-gated contract', async () => {
+  const [packageJsonText, workflow, builder] = await Promise.all([
+    readFile(packagePath, 'utf8'),
+    readFile(workflowPath, 'utf8'),
+    readFile(new URL('../scripts/build_release.py', import.meta.url), 'utf8'),
+  ]);
+  const packageJson = JSON.parse(packageJsonText);
+
+  assert.match(packageJson.scripts.test, /tests\/summary\.test\.js/);
+  assert.equal(packageJson.scripts['test:pattern-summary'], 'node tests/pattern-summary.acceptance.mjs');
+  assert.match(packageJson.scripts['check:syntax'], /node --check src\/summary\.js/);
+  assert.match(packageJson.scripts['check:syntax'], /node --check tests\/pattern-summary\.acceptance\.mjs/);
+  assert.match(workflow, /npm run test:pattern-summary/);
+  assert.match(builder, /"test:pattern-summary"/);
+  assert.match(builder, /"longitudinal_pattern_summary": "passed"/);
+  assert.match(builder, /"src\/summary\.js"/);
+});

tests/fixtures/vision-corpus/README.md

@@ -0,0 +1,55 @@
+# Vision corpus (issue #18)
+
+A committed, deterministic corpus that proves one claim on every run: **every reply Timmy receives is
+either a schema-valid visible-field suggestion or it fails closed.** Nothing is guessed, and a
+refusal never carries a form or a colour.
+
+## Licence and provenance
+
+- All fixtures are licensed **CC0-1.0**.
+- Every fixture is a synthetic image drawn from fixed integer math by
+  [`scripts/build_vision_corpus.py`](../../../scripts/build_vision_corpus.py). There is no camera, no
+  human subject, no third-party content, and no real medical imagery anywhere in this directory.
+- `manifest.json` records each fixture's `sha256`, byte length, provenance, licence, case class, the
+  provider reply it replays, and the outcome that reply must produce.
+- The hashes are an integrity receipt: `loadVisionCorpus()` refuses a fixture whose bytes no longer
+  match the manifest, so the corpus cannot be quietly edited into a different test.
+
+## Coverage
+
+| Case | Class | Replayed provider reply | Required outcome |
+|---|---|---|---|
+| `stool-like-formed` | stool | valid suggestion, confidence 0.83 | `suggestion` |
+| `non-stool-scene` | non-stool | `isStool: false` | `abstained` (`not_stool`) |
+| `blur-low-detail` | blur | confidence 0.41 | `abstained` (`low_confidence`) |
+| `glare-overexposed` | glare | schema-valid with null form and colour | `abstained` (`unusable_visual_fields`) |
+| `empty-bowl` | empty-bowl | `isStool: false` | `abstained` (`not_stool`) |
+| `malformed-response` | malformed-response | plain prose, not JSON | `fail_closed` (`unparsable_content`) |
+| `out-of-range-fields` | malformed-response | Bristol 9, colour `purple`, confidence 0.9 | `fail_closed` (`out_of_range_or_missing_fields`) |
+| `blank-plus-out-of-range` | malformed-response | Bristol 9 with a `null` colour, confidence 0.9 | `fail_closed` (`out_of_range_or_missing_fields`) |
+
+Both out-of-range cases keep `confidence` inside the contract on purpose: at `1.4` the reply died at the
+confidence gate, so the `out_of_range_or_missing_fields` label was credited to a guard the case never
+reached. `blank-plus-out-of-range` covers the reply shape that the blank-first ordering used to abstain on
+(issue #73) — a filled-in field is a claim, and a claim outside the contract fails closed even when the
+other field came back blank.
+
+## Where the corpus is enforced
+
+- `tests/vision-corpus.test.js` — corpus contract, hash integrity, and conformance of every reply.
+- `tests/vision-boundary.test.js` — the corpus replayed through the real provider call path and
+  through a running `server.mjs`, asserting status codes and that no image bytes or credentials
+  appear in a fail-closed body.
+- `tests/vision-refusal.acceptance.mjs` — the same refusals in a real browser.
+- `scripts/record_release_demo.mjs` — the release demo replays corpus cases through the real analysis
+  code path, so the video shows the status the server would actually send.
+
+## Regenerating
+
+```bash
+python3 scripts/build_vision_corpus.py            # rewrite fixtures and manifest.json
+python3 scripts/build_vision_corpus.py --verify   # verify committed fixtures against the manifest
+```
+
+The release builder runs `--verify` before anything is packaged. Regenerate deliberately and commit
+the new hashes; never hand-edit a fixture or a recorded reply.

tests/fixtures/vision-corpus/manifest.json

@@ -0,0 +1,136 @@
+{
+  "schemaVersion": 1,
+  "generator": "scripts/build_vision_corpus.py",
+  "license": "CC0-1.0",
+  "note": "Synthetic fixtures only. No real medical imagery, no personal data, and no third-party content.",
+  "cases": [
+    {
+      "id": "stool-like-formed",
+      "caseClass": "stool",
+      "file": "stool-like-formed.png",
+      "bytes": 2414,
+      "sha256": "4bb50ec6fc4ef7e9c83ed3b7ba69cdf5e73ef74b9f05e97898892bc852df970a",
+      "width": 640,
+      "height": 480,
+      "format": "png",
+      "synthetic": true,
+      "license": "CC0-1.0",
+      "provenance": "Synthetic fixture drawn deterministically by scripts/build_vision_corpus.py; no camera, no human subject, no third-party content.",
+      "expectedOutcome": "suggestion",
+      "expectedReason": "schema_valid_suggestion",
+      "providerContent": "{\"isStool\":true,\"bristolType\":4,\"color\":\"brown\",\"confidence\":0.83,\"imageQuality\":\"good\",\"observations\":\"Smooth, formed appearance.\"}"
+    },
+    {
+      "id": "non-stool-scene",
+      "caseClass": "non-stool",
+      "file": "non-stool-scene.png",
+      "bytes": 2406,
+      "sha256": "4d12150073856c1d7dfb9332049182ee0145da6ad50f6964a7273c8c61f21f91",
+      "width": 640,
+      "height": 480,
+      "format": "png",
+      "synthetic": true,
+      "license": "CC0-1.0",
+      "provenance": "Synthetic fixture drawn deterministically by scripts/build_vision_corpus.py; no camera, no human subject, no third-party content.",
+      "expectedOutcome": "abstained",
+      "expectedReason": "not_stool",
+      "providerContent": "{\"isStool\":false,\"bristolType\":null,\"color\":null,\"confidence\":0.97,\"imageQuality\":\"good\",\"observations\":\"Flatware on a tray.\"}"
+    },
+    {
+      "id": "blur-low-detail",
+      "caseClass": "blur",
+      "file": "blur-low-detail.png",
+      "bytes": 21598,
+      "sha256": "17000163662a42fd434bb2b2428d9e5a2156da08cbc82210e41dfc6fa7e24852",
+      "width": 640,
+      "height": 480,
+      "format": "png",
+      "synthetic": true,
+      "license": "CC0-1.0",
+      "provenance": "Synthetic fixture drawn deterministically by scripts/build_vision_corpus.py; no camera, no human subject, no third-party content.",
+      "expectedOutcome": "abstained",
+      "expectedReason": "low_confidence",
+      "providerContent": "{\"isStool\":true,\"bristolType\":4,\"color\":\"brown\",\"confidence\":0.41,\"imageQuality\":\"poor\",\"observations\":\"Form is unclear.\"}"
+    },
+    {
+      "id": "glare-overexposed",
+      "caseClass": "glare",
+      "file": "glare-overexposed.png",
+      "bytes": 3140,
+      "sha256": "1dc87a80951dd244c9831cba8b352e24718cf5f103f4dfd0a30e8c8c1c599f95",
+      "width": 640,
+      "height": 480,
+      "format": "png",
+      "synthetic": true,
+      "license": "CC0-1.0",
+      "provenance": "Synthetic fixture drawn deterministically by scripts/build_vision_corpus.py; no camera, no human subject, no third-party content.",
+      "expectedOutcome": "abstained",
+      "expectedReason": "unusable_visual_fields",
+      "providerContent": "{\"isStool\":true,\"bristolType\":null,\"color\":null,\"confidence\":0.66,\"imageQuality\":\"poor\",\"observations\":\"Large specular highlight hides the surface.\"}"
+    },
+    {
+      "id": "empty-bowl",
+      "caseClass": "empty-bowl",
+      "file": "empty-bowl.png",
+      "bytes": 3479,
+      "sha256": "ab443d1d9d28338e5c9f48054e7989cfce59ae25e2a9008be31cd9223be6abc4",
+      "width": 640,
+      "height": 480,
+      "format": "png",
+      "synthetic": true,
+      "license": "CC0-1.0",
+      "provenance": "Synthetic fixture drawn deterministically by scripts/build_vision_corpus.py; no camera, no human subject, no third-party content.",
+      "expectedOutcome": "abstained",
+      "expectedReason": "not_stool",
+      "providerContent": "{\"isStool\":false,\"bristolType\":null,\"color\":null,\"confidence\":0.93,\"imageQuality\":\"good\",\"observations\":\"Empty container.\"}"
+    },
+    {
+      "id": "malformed-response",
+      "caseClass": "malformed-response",
+      "file": "malformed-response.png",
+      "bytes": 2341,
+      "sha256": "634d16337879783b307d0ecf84348cfdc07950f6893095267901383f2efc83c2",
+      "width": 640,
+      "height": 480,
+      "format": "png",
+      "synthetic": true,
+      "license": "CC0-1.0",
+      "provenance": "Synthetic fixture drawn deterministically by scripts/build_vision_corpus.py; no camera, no human subject, no third-party content.",
+      "expectedOutcome": "fail_closed",
+      "expectedReason": "unparsable_content",
+      "providerContent": "Sure! It looks like a Type 4 to me. Hope that helps."
+    },
+    {
+      "id": "out-of-range-fields",
+      "caseClass": "malformed-response",
+      "file": "out-of-range-fields.png",
+      "bytes": 2375,
+      "sha256": "ac20ca9f3c9cbd118d3a2957110505d049a85861f97d361dcfbc4787960a5f8f",
+      "width": 640,
+      "height": 480,
+      "format": "png",
+      "synthetic": true,
+      "license": "CC0-1.0",
+      "provenance": "Synthetic fixture drawn deterministically by scripts/build_vision_corpus.py; no camera, no human subject, no third-party content.",
+      "expectedOutcome": "fail_closed",
+      "expectedReason": "out_of_range_or_missing_fields",
+      "providerContent": "{\"isStool\":true,\"bristolType\":9,\"color\":\"purple\",\"confidence\":0.9,\"imageQuality\":\"excellent\",\"observations\":\"Confident.\"}"
+    },
+    {
+      "id": "blank-plus-out-of-range",
+      "caseClass": "malformed-response",
+      "file": "blank-plus-out-of-range.png",
+      "bytes": 2403,
+      "sha256": "d45048cd1f5bfb1be1667238c9c21fca0cd1cae8b55e12d4f325203625eeafbd",
+      "width": 640,
+      "height": 480,
+      "format": "png",
+      "synthetic": true,
+      "license": "CC0-1.0",
+      "provenance": "Synthetic fixture drawn deterministically by scripts/build_vision_corpus.py; no camera, no human subject, no third-party content.",
+      "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.\"}"
+    }
+  ]
+}

tests/helpers/vision-harness.mjs

@@ -0,0 +1,80 @@
+// Shared harness for driving the real /api/analyze boundary with recorded corpus responses.
+//
+// Nothing here fakes the application code: the test only decides which recorded provider
+// response a stub OpenAI-compatible worker returns, and then talks to the real server.
+import http from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+export const repoRoot = fileURLToPath(new URL('../..', import.meta.url));
+export const corpusDir = fileURLToPath(new URL('../fixtures/vision-corpus/', import.meta.url));
+export const CORPUS_MODEL = 'corpus-model';
+
+export function caseFor(corpus, id) {
+  const entry = corpus.cases.find(item => item.id === id);
+  if (!entry) throw new Error(`corpus case ${id} is missing`);
+  return entry;
+}
+
+export async function corpusPayload(entry) {
+  const bytes = await readFile(join(corpusDir, entry.file));
+  return { imageDataUrl: `data:image/png;base64,${bytes.toString('base64')}`, consent: true };
+}
+
+/** Stub OpenAI-compatible worker whose answer the test selects per request. */
+export function startProvider() {
+  const state = { content: '', requests: [] };
+  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: CORPUS_MODEL }] }));
+    }
+    let body = '';
+    req.on('data', chunk => { body += chunk; });
+    req.on('end', () => {
+      state.requests.push(body);
+      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)),
+  })));
+}
+
+/** Real server.mjs, vision enabled, pointed at the stub worker. */
+export async function startServer({ providerPort, port = 4199 }) {
+  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: CORPUS_MODEL,
+      TIMMY_VISION_TIMEOUT_MS: '5000',
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  for (let attempt = 0; attempt < 80; attempt += 1) {
+    try {
+      const probe = await fetch(`http://127.0.0.1:${port}/api/healthz`);
+      if (probe.ok) return child;
+    } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  child.kill();
+  throw new Error('acceptance server did not become ready');
+}
+
+export async function stopServer(child) {
+  if (!child || child.exitCode !== null) return;
+  child.kill();
+  await new Promise(resolve => child.once('exit', resolve));
+}

tests/mobile-capture.acceptance.mjs

@@ -18,7 +18,9 @@ for (const viewport of viewports) {
   await page.route('**/api/vision-status', route => route.fulfill({
     status: 200,
     contentType: 'application/json',
-    body: JSON.stringify({ enabled: true, profile: 'selfhost', providerReady: true, model: 'synthetic-test-model' }),
+    // The fixture mirrors the real /api/vision-status contract, which reports whether the pinned
+    // model was actually seen loaded (#15) alongside provider reachability.
+    body: JSON.stringify({ enabled: true, profile: 'selfhost', providerReady: true, modelSeen: true, model: 'synthetic-test-model' }),
   }));
   await page.route('**/api/analyze', route => {
     analysisRequests += 1;

tests/pattern-summary.acceptance.mjs

@@ -0,0 +1,88 @@
+import { chromium } from 'playwright';
+import assert from 'node:assert/strict';
+import { mkdir } from 'node:fs/promises';
+
+// Issue #34: every longitudinal summary line must point at the confirmed records behind it, and a
+// sparse window must say so instead of describing a trend. The records are fictional sample entries
+// written into the app's own local ledger contract; no real health data is involved.
+const DAY = 86400000;
+const sample = (id, daysAgo, bristolType) => ({
+  id,
+  occurredAt: new Date(Date.now() - daysAgo * DAY).toISOString(),
+  bristolType,
+  color: 'brown',
+  urgency: 1,
+  discomfort: 1,
+  note: '',
+  photoDataUrl: '',
+  symptoms: {},
+});
+
+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));
+
+const seed = async entries => page.evaluate(list => {
+  const base = document.querySelector('meta[name="timmy-base-path"]')?.content || '/';
+  localStorage.setItem(`timmy:${base}:ledger-v1`, JSON.stringify(list));
+}, entries);
+
+await page.goto('http://127.0.0.1:4173', { waitUntil: 'networkidle' });
+await page.evaluate(() => localStorage.clear());
+
+// 1. A sparse window refuses to describe a pattern.
+await seed([sample('sparse-a', 1, 4), sample('sparse-b', 4, 6)]);
+await page.reload({ waitUntil: 'networkidle' });
+const sparse = page.locator('[data-summary-insufficient]');
+assert.equal(await sparse.count(), 1, 'a window below the minimum must show honest insufficient-data copy');
+assert.match(await sparse.innerText(), /not enough confirmed logs/i);
+assert.match(await sparse.innerText(), /2 of 3/);
+assert.equal(await page.locator('[data-statement]').count(), 0, 'no pattern line may be claimed from two logs');
+await page.screenshot({ path: 'artifacts/pattern-summary-insufficient-mobile.png' });
+
+// 2. A populated window renders explainable lines, each citing its own records.
+const seeded = [
+  sample('rec-firm', 2, 1),
+  sample('rec-typical-1', 5, 3),
+  sample('rec-typical-2', 9, 4),
+  sample('rec-typical-3', 12, 4),
+  sample('rec-old', 40, 6),
+];
+await seed(seeded);
+await page.reload({ waitUntil: 'networkidle' });
+
+const card = page.locator('[data-pattern-summary]');
+assert.equal(await card.count(), 1, 'the home insight card is the explainable summary');
+assert.match(await page.locator('[data-summary-window]').innerText(), /last 28 days/i);
+assert.match(await page.locator('[data-statement="frequency"]').innerText(), /4 confirmed logs/);
+assert.equal(await page.locator('[data-statement="firm"]').getAttribute('data-records'), '1');
+assert.equal(await page.locator('[data-statement="typical"]').getAttribute('data-records'), '3');
+// The out-of-window log is neither counted nor offered as a citation.
+assert.doesNotMatch(await card.innerText(), /5 confirmed logs/);
+await page.screenshot({ path: 'artifacts/pattern-summary-home-mobile.png' });
+
+// 3. Following a citation shows exactly the contributing confirmed records.
+await page.locator('[data-statement-link="typical"]').click();
+const records = page.locator('[data-summary-records]');
+await records.waitFor();
+assert.equal(await page.locator('[data-summary-record]').count(), 3, 'the citation lists exactly its own records');
+const listed = await page.locator('[data-summary-record]').evaluateAll(nodes => nodes.map(node => node.getAttribute('data-entry-id')));
+assert.deepEqual(listed.sort(), ['rec-typical-1', 'rec-typical-2', 'rec-typical-3']);
+assert.match(await records.innerText(), /Type 3/);
+assert.match(await records.innerText(), /These are the confirmed logs this line was built from/);
+await page.screenshot({ path: 'artifacts/pattern-summary-records-mobile.png' });
+await page.locator('#pattern-records-close').click();
+assert.equal(await page.locator('[data-summary-records]').count(), 0, 'the citation sheet closes cleanly');
+
+// 4. The summary never explains a cause or clears a food.
+const summaryText = await card.innerText();
+assert.doesNotMatch(summaryText, /because|due to|caused|safe to eat|avoid eating|should eat|diagnos/i);
+
+assert.deepEqual(errors, []);
+await context.close();
+await browser.close();
+console.log('PASS longitudinal pattern summaries cite their confirmed records and refuse to describe a sparse window');

tests/release-demo.test.js

@@ -50,6 +50,27 @@ test('release demo shows the provisional, confirmed, and corrected suggestion st
   assert.match(demo, /Type 2/, 'the retained draft in the demo must show the value the user corrected to');
 });
 
+test('release demo shows the explainable pattern summary and follows a citation to its own records', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+
+  // Issue #34: the recording must exercise the summary, its citation sheet, and the sparse case.
+  assert.match(demo, /\[data-pattern-summary\]/);
+  assert.match(demo, /\[data-statement-link="typical"\]/);
+  assert.match(demo, /\[data-summary-record\]/);
+  assert.match(demo, /\[data-summary-insufficient\]/);
+  assert.match(demo, /The summary says which confirmed logs it read, and a citation opens exactly those records/);
+  assert.match(demo, /Every pattern line names the confirmed logs behind it, and following one shows exactly those records/);
+  assert.match(demo, /Fictional sample logs are seeded into this browser's own storage — no real health data appears here/);
+  assert.match(demo, /Two logs is not a pattern: the summary refuses to describe a trend it cannot support/);
+  // The cited records are asserted in the browser, not narrated.
+  assert.match(demo, /must list exactly the records it cites/);
+  // Both captions are required release gates, so a later release cannot drop the scene silently.
+  assert.match(builder, /Every pattern line names the confirmed logs behind it, and following one shows exactly those records/);
+  assert.match(builder, /Two logs is not a pattern: the summary refuses to describe a trend it cannot support/);
+  assert.match(builder, /"longitudinal_pattern_summary": "passed"/);
+});
+
 test('release builder gates the sleek shell, Hermes chat, and bootstrap syntax', async () => {
   const builder = await readFile(builderPath, 'utf8');
   assert.match(builder, /"test:sleek"/);
@@ -148,3 +169,57 @@ test('release demo captions expire and the contact sheet spans the whole recordi
   assert.match(builder, /12 \/ demo_duration/);
   assert.match(builder, /Release demo contact sheet was not produced/);
 });
+
+test('release demo visibly exercises the corpus refusal paths instead of only the happy path', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+
+  // The refusal responses must come from the recorded corpus and the real analysis code path,
+  // never from copy pasted into the recording script.
+  assert.match(demo, /loadVisionCorpus/);
+  assert.match(demo, /visionFailureResponse/);
+  assert.match(demo, /corpusAnalyzeResult/);
+  assert.match(demo, /tests\/fixtures\/vision-corpus\/non-stool-scene\.png/);
+  assert.match(demo, /tests\/fixtures\/vision-corpus\/out-of-range-fields\.png/);
+  assert.match(demo, /getByText\(\/No confident match\/i\)/);
+  assert.match(demo, /couldn’t analyze that safely/i);
+
+  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/);
+  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/);
+});
+
+test('release demo shows a filled-in out-of-range field failing closed even beside a blank one', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+
+  // Issue #73's escape class, replayed on camera from the committed corpus rather than described.
+  assert.match(demo, /corpusCase\('blank-plus-out-of-range'\)/);
+  assert.match(demo, /tests\/fixtures\/vision-corpus\/blank-plus-out-of-range\.png/);
+  assert.match(demo, /A filled-in field that is out of range still fails closed, even when the other field came back blank/);
+  assert.match(demo, /no longer told the photo was unreadable when the model returned an impossible value/);
+  // The extra fail-closed scene is a real 503, so the demo's error budget must count it.
+  assert.match(demo, /expectedFailClosed\.length !== 2/);
+  // The caption is a required gate, so a later release cannot silently drop the scene.
+  assert.match(builder, /A filled-in field that is out of range still fails closed/);
+});
+
+test('release demo shows readiness waiting for the loaded pinned model before AI is offered', async () => {
+  const demo = await readFile(demoPath, 'utf8');
+  const builder = await readFile(builderPath, 'utf8');
+
+  // Issue #15: reachable is not loaded, and the recording must prove the app withholds AI.
+  assert.match(demo, /modelLoaded = false/);
+  assert.match(demo, /getByText\(\/model is not loaded yet\/i\)/);
+  assert.match(demo, /model-status\.loading/);
+  assert.match(demo, /Reachable is not loaded: no AI control, no consent, and no upload until the pinned model is resident/);
+  assert.match(demo, /No AI control may exist before the model is loaded/);
+  assert.match(demo, /Once the pinned model is loaded, the same screen offers the AI analysis again/);
+  // The scene is asserted in the browser, not narrated: the demo throws if the state is wrong.
+  assert.match(demo, /must never be reported ready/);
+  // 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/);
+});

tests/sleek-chat.acceptance.mjs

@@ -14,7 +14,7 @@ page.on('console', message => { if (message.type() === 'error') errors.push(mess
 page.on('pageerror', error => errors.push(error.message));
 page.on('request', request => { if (new URL(request.url()).pathname.includes('/api/')) apiRequests.push(new URL(request.url()).pathname); });
 
-await page.route('**/api/vision-status', route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ enabled: true, profile: 'selfhost', providerReady: true, model: 'SmolVLM2-2.2B-Instruct' }) }));
+await page.route('**/api/vision-status', route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ enabled: true, profile: 'selfhost', providerReady: true, modelSeen: true, model: 'SmolVLM2-2.2B-Instruct' }) }));
 await page.route('**/api/agent/status', route => route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ enabled: true, configured: true, authenticated: true, mode: 'hermes-agent' }) }));
 let chatRequest;
 await page.route('**/api/agent/chat', async route => {

tests/summary.test.js

@@ -0,0 +1,100 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildPatternSummary } from '../src/summary.js';
+
+const DAY = 86400000;
+const NOW = Date.parse('2026-09-20T12:00:00.000Z');
+const entry = (id, daysAgo, bristolType) => ({
+  id,
+  occurredAt: new Date(NOW - daysAgo * DAY).toISOString(),
+  bristolType,
+  color: 'brown',
+  urgency: 0,
+  discomfort: 0,
+  note: '',
+  symptoms: {},
+});
+
+test('every summary statement cites the confirmed records it was built from', () => {
+  const summary = buildPatternSummary([entry('a', 1, 4), entry('b', 3, 3), entry('c', 5, 6)], { now: NOW });
+
+  assert.equal(summary.insufficient, false);
+  assert.equal(summary.window.label, 'last 28 days');
+
+  const frequency = summary.statements.find(statement => statement.id === 'frequency');
+  assert.ok(frequency, 'the window needs a frequency line');
+  assert.match(frequency.text, /3 confirmed logs/);
+  assert.match(frequency.text, /last 28 days/);
+  assert.deepEqual(frequency.entryIds, ['c', 'b', 'a']);
+
+  // No statement may cite an id the summary cannot point at a real record for.
+  const known = new Set(summary.records.map(record => record.id));
+  for (const statement of summary.statements) {
+    assert.ok(statement.entryIds.length > 0, `${statement.id} must cite its contributing records`);
+    for (const id of statement.entryIds) assert.ok(known.has(id), `${statement.id} cited an unknown record ${id}`);
+  }
+});
+
+test('each form line cites only the records in that form bucket', () => {
+  const summary = buildPatternSummary([entry('a', 1, 2), entry('b', 3, 4), entry('c', 5, 4), entry('d', 6, 4)], { now: NOW });
+
+  const firm = summary.statements.find(statement => statement.id === 'firm');
+  assert.ok(firm, 'a firm-side line is needed when firm logs exist');
+  assert.match(firm.text, /Type 1–2/);
+  assert.match(firm.text, /1 of 4/);
+  assert.deepEqual(firm.entryIds, ['a']);
+
+  const typical = summary.statements.find(statement => statement.id === 'typical');
+  assert.match(typical.text, /3 of 4/);
+  assert.deepEqual(typical.entryIds, ['d', 'c', 'b']);
+  assert.equal(summary.statements.some(statement => statement.id === 'loose'), false);
+});
+
+test('a contradictory window is reported as a mixed pattern instead of one trend', () => {
+  const summary = buildPatternSummary([entry('a', 1, 1), entry('b', 2, 1), entry('c', 3, 6), entry('d', 4, 7)], { now: NOW });
+
+  const mixed = summary.statements.find(statement => statement.id === 'mixed');
+  assert.ok(mixed, 'a window with both firm and loose logs needs an explicit mixed line');
+  assert.match(mixed.text, /firm and loose logs both appear/i);
+  assert.match(mixed.text, /not one trend/i);
+  assert.deepEqual(mixed.entryIds, ['d', 'c', 'b', 'a']);
+});
+
+test('logs outside the window are neither counted nor cited', () => {
+  const summary = buildPatternSummary([entry('old', 40, 1), entry('a', 1, 4), entry('b', 3, 3), entry('c', 5, 4)], { now: NOW });
+
+  assert.deepEqual(summary.records.map(record => record.id), ['c', 'b', 'a']);
+  assert.equal(summary.statements.some(statement => statement.entryIds.includes('old')), false);
+  assert.match(summary.statements.find(statement => statement.id === 'frequency').text, /3 confirmed logs/);
+
+  const weekly = buildPatternSummary([entry('old', 40, 1), entry('a', 1, 4), entry('b', 2, 4), entry('c', 3, 4)], { now: NOW, windowDays: 7 });
+  assert.equal(weekly.window.label, 'last 7 days');
+  assert.equal(weekly.window.days, 7);
+  assert.deepEqual(weekly.records.map(record => record.id), ['c', 'b', 'a']);
+});
+
+test('the summary states its boundary and never explains a cause or clears a food', () => {
+  const summary = buildPatternSummary([entry('a', 1, 4), entry('b', 3, 3), entry('c', 5, 6)], { now: NOW });
+  assert.match(summary.boundary, /your own confirmed records/i);
+
+  const forbidden = /because|due to|caused|triggered|safe to eat|avoid eating|should eat|clears|diagnos|treat/i;
+  for (const text of [summary.boundary, summary.copy, ...summary.statements.map(statement => statement.text)]) {
+    assert.doesNotMatch(text, forbidden, text);
+  }
+  const sparse = buildPatternSummary([entry('a', 1, 4)], { now: NOW });
+  for (const text of [sparse.boundary, sparse.copy]) {
+    assert.doesNotMatch(text, forbidden, text);
+  }
+});
+
+test('refuses to describe a pattern from too few confirmed logs', () => {
+  const summary = buildPatternSummary([entry('a', 1, 4), entry('b', 3, 3)], { now: NOW });
+
+  assert.equal(summary.insufficient, true);
+  assert.deepEqual(summary.statements, []);
+  assert.match(summary.copy, /not enough confirmed logs/i);
+  assert.match(summary.copy, /2 of 3/);
+  // The summary still lists exactly what it did read, in the order it happened.
+  assert.deepEqual(summary.records.map(record => record.id), ['b', 'a']);
+});

tests/vision-boundary.test.js

@@ -0,0 +1,110 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { analyzePhoto, visionFailureResponse } from '../src/vision-service.js';
+import { loadVisionCorpus } from '../src/vision-corpus.js';
+import { CORPUS_MODEL, caseFor, corpusDir, corpusPayload, startProvider, startServer, stopServer } from './helpers/vision-harness.mjs';
+
+const FAIL_CLOSED_COPY = /no suggestion was applied/i;
+
+test('a malformed provider response fails closed with user-safe copy instead of echoing provider detail', () => {
+  const failure = visionFailureResponse(Object.assign(new Error('Invalid AI response: visual fields are out of range.'), { code: 'invalid_fields' }));
+
+  assert.equal(failure.status, 503);
+  assert.match(failure.body.error, FAIL_CLOSED_COPY);
+  assert.doesNotMatch(failure.body.error, /invalid ai response|out of range/i);
+
+  const consent = visionFailureResponse(new Error('Explicit consent is required before AI analysis.'));
+  assert.equal(consent.status, 400);
+  assert.match(consent.body.error, /consent/i);
+
+  const offline = visionFailureResponse(new Error('AI analysis is temporarily unavailable. Continue manually.'));
+  assert.equal(offline.status, 503);
+  assert.match(offline.body.error, /temporarily unavailable/i);
+});
+
+test('the corpus replays through the real provider call path without inventing a suggestion', async () => {
+  const corpus = await loadVisionCorpus(corpusDir);
+  for (const entry of corpus.cases) {
+    const fetchImpl = async () => ({ ok: true, json: async () => ({ choices: [{ message: { content: entry.providerContent } }] }) });
+    const options = {
+      payload: { imageDataUrl: 'data:image/png;base64,YQ==', consent: true },
+      fetchImpl,
+      config: { baseUrl: 'http://127.0.0.1:9/v1', apiKey: 'corpus-key', model: CORPUS_MODEL },
+    };
+    if (entry.expectedOutcome === 'suggestion') {
+      const result = await analyzePhoto(options);
+      assert.equal(result.status, 'suggestion', `${entry.id} must return a suggestion`);
+      assert.equal(result.imageQuality, 'good');
+    } else if (entry.expectedOutcome === 'abstained') {
+      const result = await analyzePhoto(options);
+      assert.equal(result.status, 'needs_user_input', `${entry.id} must abstain`);
+      assert.equal(result.abstainedFor, entry.expectedReason, `${entry.id} must name its abstention`);
+      assert.equal('bristolType' in result, false, `${entry.id} must not prefill a form`);
+    } else {
+      await assert.rejects(() => analyzePhoto(options), (error) => {
+        assert.equal(visionFailureResponse(error).status, 503, `${entry.id} must fail closed`);
+        return true;
+      });
+    }
+  }
+});
+
+test('the running server answers every corpus case with a fail-closed status and no leaked image bytes', async () => {
+  const corpus = await loadVisionCorpus(corpusDir);
+  const provider = await startProvider();
+  const server = await startServer({ providerPort: provider.port });
+  const postAnalyze = async (payload) => {
+    const response = await fetch('http://127.0.0.1:4199/api/analyze', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    return { status: response.status, body: await response.json() };
+  };
+  try {
+    const suggestion = caseFor(corpus, 'stool-like-formed');
+    provider.state.content = suggestion.providerContent;
+    const payload = await corpusPayload(suggestion);
+    const ok = await postAnalyze(payload);
+    assert.equal(ok.status, 200, 'a schema-valid suggestion is the only case that returns 200 with fields');
+    assert.equal(ok.body.bristolType, 4);
+
+    const glare = caseFor(corpus, 'glare-overexposed');
+    provider.state.content = glare.providerContent;
+    const abstained = await postAnalyze(await corpusPayload(glare));
+    assert.equal(abstained.status, 200, 'a schema-valid response with unreadable fields abstains, it is not a server failure');
+    assert.equal(abstained.body.status, 'needs_user_input');
+    assert.equal(abstained.body.abstainedFor, 'unusable_visual_fields');
+    assert.equal('bristolType' in abstained.body, false);
+
+    const malformed = caseFor(corpus, 'malformed-response');
+    provider.state.content = malformed.providerContent;
+    const unparsable = await postAnalyze(await corpusPayload(malformed));
+    assert.equal(unparsable.status, 503, 'unparsable provider content must not be served as a suggestion');
+    assert.match(unparsable.body.error, FAIL_CLOSED_COPY);
+    assert.doesNotMatch(JSON.stringify(unparsable.body), /base64|data:image|corpus-key|Bearer/i);
+
+    const outOfRangeCase = caseFor(corpus, 'out-of-range-fields');
+    provider.state.content = outOfRangeCase.providerContent;
+    const outOfRange = await postAnalyze(await corpusPayload(outOfRangeCase));
+    assert.equal(outOfRange.status, 503, 'out-of-range fields must not be served as a suggestion');
+    assert.match(outOfRange.body.error, FAIL_CLOSED_COPY);
+
+    // Issue #73: a filled-in field that is out of range fails closed even when the other field is blank,
+    // so the user is never told the photo was unreadable when the model returned an impossible value.
+    const blankAndOutOfRange = caseFor(corpus, 'blank-plus-out-of-range');
+    provider.state.content = blankAndOutOfRange.providerContent;
+    const blankOutOfRange = await postAnalyze(await corpusPayload(blankAndOutOfRange));
+    assert.equal(blankOutOfRange.status, 503, 'a filled-in out-of-range field must not be served as an abstention');
+    assert.match(blankOutOfRange.body.error, FAIL_CLOSED_COPY);
+    assert.equal('abstainedFor' in blankOutOfRange.body, false, 'a contract breach must not be reported as an abstention');
+    assert.doesNotMatch(JSON.stringify(blankOutOfRange.body), /base64|data:image|corpus-key|Bearer/i);
+
+    const noConsent = await postAnalyze({ imageDataUrl: payload.imageDataUrl, consent: false });
+    assert.equal(noConsent.status, 400, 'analysis without explicit consent is a client error');
+    assert.doesNotMatch(JSON.stringify(noConsent.body), /base64|data:image/i);
+  } finally {
+    await stopServer(server);
+    await provider.close();
+  }
+});

tests/vision-corpus.test.js

@@ -0,0 +1,110 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { classifyVisionOutcome, loadVisionCorpus, VISION_CORPUS_CLASSES, VISION_CORPUS_LICENSE, VISION_CORPUS_OUTCOMES } from '../src/vision-corpus.js';
+
+const corpusDir = fileURLToPath(new URL('./fixtures/vision-corpus/', import.meta.url));
+// The colour contract `src/analysis.js` enforces, restated here so the corpus can be checked against it.
+const COLORS_IN_CONTRACT = ['brown', 'green', 'yellow', 'pale', 'red', 'black'];
+
+async function scratchCorpus() {
+  const directory = await mkdtemp(join(tmpdir(), 'timmy-corpus-'));
+  await cp(corpusDir, directory, { recursive: true });
+  return directory;
+}
+
+test('vision corpus ships licensed synthetic fixtures covering every required visual case class', async () => {
+  const corpus = await loadVisionCorpus(corpusDir);
+
+  assert.equal(corpus.license, VISION_CORPUS_LICENSE);
+  const classes = new Set(corpus.cases.map(entry => entry.caseClass));
+  for (const required of VISION_CORPUS_CLASSES) {
+    assert.ok(classes.has(required), `corpus must cover the ${required} case`);
+  }
+  for (const entry of corpus.cases) {
+    assert.equal(entry.synthetic, true, `${entry.id} must be synthetic; no real medical image is redistributable`);
+    assert.equal(entry.license, VISION_CORPUS_LICENSE);
+    assert.match(entry.provenance, /\S/, `${entry.id} must record where it came from`);
+    assert.match(entry.sha256, /^[a-f0-9]{64}$/, `${entry.id} must record its content hash`);
+  }
+});
+
+test('vision corpus rejects fixtures whose bytes no longer match the recorded hash', async () => {
+  const directory = await scratchCorpus();
+  try {
+    const manifest = JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8'));
+    const target = join(directory, manifest.cases[0].file);
+    const bytes = await readFile(target);
+    await writeFile(target, Buffer.concat([bytes, Buffer.from([0])]));
+
+    await assert.rejects(() => loadVisionCorpus(directory), new RegExp(manifest.cases[0].id));
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test('vision corpus rejects an unlicensed, non-synthetic, or incomplete manifest', async () => {
+  const directory = await scratchCorpus();
+  try {
+    const manifestPath = join(directory, 'manifest.json');
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+
+    manifest.cases[0].synthetic = false;
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+    await assert.rejects(() => loadVisionCorpus(directory), /synthetic/i);
+
+    manifest.cases[0].synthetic = true;
+    manifest.cases = manifest.cases.filter(entry => entry.caseClass !== 'non-stool');
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+    await assert.rejects(() => loadVisionCorpus(directory), /non-stool/);
+
+    manifest.cases[0].license = 'all-rights-reserved';
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+    await assert.rejects(() => loadVisionCorpus(directory), /CC0-1\.0/);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test('the corpus earns its out-of-range label and covers the blank-plus-out-of-range class', async () => {
+  const corpus = await loadVisionCorpus(corpusDir);
+  const outOfRange = corpus.cases.filter(entry => entry.expectedReason === 'out_of_range_or_missing_fields');
+  assert.ok(outOfRange.length > 0, 'the corpus must cover the out-of-range failure class');
+
+  // Issue #73: a case whose confidence breaks the gate never reaches the field-range check, so its
+  // `out_of_range_or_missing_fields` label would be attributed to a guard it never exercised.
+  const reachesRangeCheck = outOfRange.filter(entry => Number(JSON.parse(entry.providerContent).confidence) <= 1);
+  assert.ok(reachesRangeCheck.length > 0, 'at least one out-of-range case must clear the confidence gate to exercise the range check');
+
+  // Issue #73's escape class: a blank field next to a non-blank, out-of-range field. This is the exact
+  // reply shape that used to abstain as `unusable_visual_fields` instead of failing closed.
+  const blank = value => value === null || value === undefined || (typeof value === 'string' && !value.trim());
+  const colourInContract = value => COLORS_IN_CONTRACT.includes(String(value).toLowerCase());
+  const formInContract = value => Number.isInteger(Number(value)) && Number(value) >= 1 && Number(value) <= 7;
+  const escapeCases = outOfRange.filter(entry => {
+    const value = JSON.parse(entry.providerContent);
+    const fields = [value.bristolType, value.color];
+    return fields.some(blank) && fields.some(field => !blank(field) && !(colourInContract(field) || formInContract(field)));
+  });
+  assert.ok(escapeCases.length > 0, 'the corpus must carry a blank-plus-out-of-range case so the fail-closed label is really earned');
+});
+
+test('every recorded corpus response is schema-valid or fails closed, exactly as declared', async () => {
+  const corpus = await loadVisionCorpus(corpusDir);
+
+  for (const entry of corpus.cases) {
+    const result = classifyVisionOutcome(entry.providerContent);
+    assert.ok(VISION_CORPUS_OUTCOMES.includes(result.outcome), `${entry.id} produced an unknown outcome ${result.outcome}`);
+    assert.equal(result.outcome, entry.expectedOutcome, `${entry.id} must resolve to ${entry.expectedOutcome}`);
+    assert.equal(result.reason, entry.expectedReason, `${entry.id} must report ${entry.expectedReason}`);
+    // A response may never smuggle a visual claim out of a non-suggestion outcome.
+    if (result.outcome !== 'suggestion') {
+      assert.equal('bristolType' in result, false, `${entry.id} must not carry a suggested form`);
+      assert.equal('color' in result, false, `${entry.id} must not carry a suggested color`);
+    }
+    assert.doesNotMatch(JSON.stringify(result), /base64|data:image|Bear\s?er|api[_-]?key/i, `${entry.id} must not echo image bytes or credentials`);
+  }
+});

tests/vision-readiness.test.js

@@ -16,18 +16,48 @@ test('reports distinct phases so the UI never claims a worker is ready when it i
   assert.equal(visionReadiness(null).phase, 'checking');
   assert.equal(visionReadiness({ enabled: false }).phase, 'disabled');
   assert.equal(visionReadiness({ enabled: true, providerReady: false }).phase, 'offline');
-  assert.equal(visionReadiness({ enabled: true, providerReady: true }).phase, 'ready');
+  // The readiness contract widened in #15: answering the provider probe is no longer enough.
+  assert.equal(visionReadiness({ enabled: true, providerReady: true }).phase, 'loading');
+  assert.equal(visionReadiness({ enabled: true, providerReady: true, modelSeen: false }).phase, 'loading');
+  assert.equal(visionReadiness({ enabled: true, providerReady: true, modelSeen: true }).phase, 'ready');
 });
 
-test('a ready provider keeps AI analysis available and does not force the manual path', () => {
-  const readiness = visionReadiness({ enabled: true, providerReady: true, model: 'SmolVLM2-2.2B-Instruct' });
+test('readiness waits for the pinned model to load before promising AI', () => {
+  // Issue #15: a worker that answers /v1/models has not necessarily loaded the model yet.
+  // Readiness must pass only after the pinned model is loaded, or the user is offered an
+  // AI control that fails after the upload.
+  const notLoaded = visionReadiness({
+    enabled: true,
+    profile: 'selfhost',
+    providerReady: true,
+    modelSeen: false,
+    model: 'SmolVLM2-2.2B-Instruct',
+  });
+  assert.equal(notLoaded.phase, 'loading');
+  assert.equal(notLoaded.ready, false);
+  assert.equal(notLoaded.manualOnly, true);
+  assert.match(notLoaded.message, /model/i);
+  assert.match(notLoaded.manualLabel, /manual|without AI/i);
+
+  const unverified = visionReadiness({ enabled: true, profile: 'selfhost', providerReady: true });
+  assert.equal(unverified.ready, false, 'an unconfirmed model must never be treated as loaded');
+});
+
+test('a loaded pinned model keeps AI analysis available and does not force the manual path', () => {
+  const readiness = visionReadiness({ enabled: true, providerReady: true, modelSeen: true, model: 'SmolVLM2-2.2B-Instruct' });
   assert.equal(readiness.ready, true);
   assert.equal(readiness.manualOnly, false);
   assert.equal(readiness.manualLabel, '');
 });
 
 test('readiness never promises a symptom or diagnosis capability', () => {
-  for (const status of [null, { enabled: false }, { enabled: true, providerReady: false }, { enabled: true, providerReady: true }]) {
+  for (const status of [
+    null,
+    { enabled: false },
+    { enabled: true, providerReady: false },
+    { enabled: true, providerReady: true, modelSeen: true },
+    { enabled: true, providerReady: true, modelSeen: false },
+  ]) {
     const readiness = visionReadiness(status);
     const copy = `${readiness.manualLabel} ${readiness.message}`;
     assert.doesNotMatch(copy, /diagnos|bleeding|cancer|symptom/i);

tests/vision-refusal.acceptance.mjs

@@ -0,0 +1,104 @@
+// Browser acceptance for issue #18: the refusal paths the corpus proves must be visible in the app,
+// not just in unit tests. The app talks to a real server.mjs with vision enabled, and the only thing
+// the harness chooses is which recorded corpus response the stub worker returns.
+import { chromium } from 'playwright';
+import assert from 'node:assert/strict';
+import { mkdir } from 'node:fs/promises';
+import { loadVisionCorpus } from '../src/vision-corpus.js';
+import { caseFor, corpusDir, startProvider, startServer, stopServer } from './helpers/vision-harness.mjs';
+
+await mkdir('artifacts', { recursive: true });
+const corpus = await loadVisionCorpus(corpusDir);
+const provider = await startProvider();
+const server = await startServer({ providerPort: provider.port, port: 4199 });
+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));
+// A fail-closed 503 is the intended boundary response, so the browser logs it as a failed resource.
+// It is expected exactly once; anything else is a real page error.
+const EXPECTED_FAIL_CLOSED_LOG = /Failed to load resource: the server responded with a status of 503 \(Service Unavailable\)/;
+
+async function closeSheet() {
+  await page.locator('#close-sheet').click();
+  await page.locator('.scan-sheet').waitFor({ state: 'detached' });
+}
+
+async function analyzeCorpusCase(entry) {
+  provider.state.content = entry.providerContent;
+  await page.locator('[data-scan]').click();
+  await page.getByText(/Self-hosted model ready/i).waitFor();
+  await page.locator('#gallery-photo').setInputFiles(`tests/fixtures/vision-corpus/${entry.file}`);
+  await page.locator('#ai-consent').check();
+  await page.locator('#analyze-photo').click();
+  await page.locator('.scan-result').first().waitFor();
+}
+
+try {
+  await page.goto('http://127.0.0.1:4199', { waitUntil: 'networkidle' });
+  await page.evaluate(() => localStorage.clear());
+  await page.reload({ waitUntil: 'networkidle' });
+
+  // 1. Non-stool photo: no prefill, a plain refusal, and manual entry still one action away.
+  await analyzeCorpusCase(caseFor(corpus, 'non-stool-scene'));
+  assert.equal(await page.getByText(/No confident match/i).isVisible(), true, 'a non-stool photo must refuse');
+  assert.equal(await page.locator('.ai-badge').count(), 0, 'a refusal must not carry an AI suggestion badge');
+  assert.equal(await page.getByText('Type 4', { exact: true }).count(), 0, 'a refusal must not prefill a form');
+  assert.match(await page.locator('.scan-result').innerText(), /does not clearly show stool/i);
+  const manual = page.locator('#manual-from-scan');
+  assert.match(await manual.innerText(), /Choose the form yourself/i);
+  await page.screenshot({ path: 'artifacts/vision-refusal-non-stool-mobile.png' });
+  await manual.click();
+  await page.getByText('Pick the closest form').waitFor();
+  assert.equal(await page.locator('.ai-prefill').count(), 0, 'refused analysis must not leave AI provenance in the log form');
+  await closeSheet();
+
+  // 2. Glare with unreadable visual fields: schema-valid, so it abstains calmly instead of erroring.
+  await analyzeCorpusCase(caseFor(corpus, 'glare-overexposed'));
+  assert.equal(await page.getByText(/No confident match/i).isVisible(), true);
+  assert.match(await page.locator('.scan-result').innerText(), /does not show a form Timmy can read safely/i);
+  assert.equal(await page.getByText(/couldn’t analyze that safely/i).count(), 0, 'a schema-valid abstention is not a failure');
+  await page.screenshot({ path: 'artifacts/vision-refusal-unreadable-fields-mobile.png' });
+  await closeSheet();
+
+  // 3. Out-of-range model output: fails closed, and the copy says plainly that nothing was applied.
+  await analyzeCorpusCase(caseFor(corpus, 'out-of-range-fields'));
+  await page.getByText(/couldn’t analyze that safely/i).waitFor();
+  assert.match(await page.locator('.scan-result').innerText(), /No suggestion was applied/i);
+  assert.doesNotMatch(await page.locator('.scan-result').innerText(), /out of range|Invalid AI response/i, 'provider detail must not reach the user');
+  assert.equal(await page.locator('.ai-badge').count(), 0);
+  await page.screenshot({ path: 'artifacts/vision-refusal-fail-closed-mobile.png' });
+  await closeSheet();
+
+  // 4. Issue #73: a filled-in field that is out of range fails closed even when the other field is blank.
+  // The old blank-first ordering abstained here, so the user was told the photo was unreadable while the
+  // model had actually returned an impossible value. The abstention copy must not appear on this path.
+  await analyzeCorpusCase(caseFor(corpus, 'blank-plus-out-of-range'));
+  await page.getByText(/couldn’t analyze that safely/i).waitFor();
+  assert.match(await page.locator('.scan-result').innerText(), /No suggestion was applied/i);
+  assert.equal(await page.getByText(/No confident match/i).count(), 0, 'a contract breach must not be shown as an abstention');
+  assert.equal(await page.locator('.ai-badge').count(), 0);
+  assert.doesNotMatch(await page.locator('.scan-result').innerText(), /out of range|Invalid AI response/i, 'provider detail must not reach the user');
+  await page.screenshot({ path: 'artifacts/vision-refusal-blank-plus-out-of-range-mobile.png' });
+  await closeSheet();
+
+  // 5. Positive control: the same corpus still yields a real suggestion when the response is usable.
+  await analyzeCorpusCase(caseFor(corpus, 'stool-like-formed'));
+  await page.getByText(/83% confidence/i).waitFor();
+  assert.equal(await page.getByText('Type 4', { exact: true }).isVisible(), true);
+  await page.screenshot({ path: 'artifacts/vision-corpus-suggestion-mobile.png' });
+
+  // Two fail-closed scenes reach the browser as real 503s; the count is asserted so a scene cannot be
+  // dropped silently, and any other console error still fails the run.
+  const failClosedLogs = errors.filter(message => EXPECTED_FAIL_CLOSED_LOG.test(message));
+  assert.equal(failClosedLogs.length, 2, 'each fail-closed response must reach the browser as a 503');
+  assert.deepEqual(errors.filter(message => !EXPECTED_FAIL_CLOSED_LOG.test(message)), []);
+  console.log('PASS vision corpus refusal: non-stool, unreadable fields, out-of-range, and blank-plus-out-of-range replies never prefill; the usable reply still suggests');
+} finally {
+  await context.close();
+  await browser.close();
+  await stopServer(server);
+  await provider.close();
+}

tests/worker-benchmark.test.js

@@ -0,0 +1,132 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync, spawn } from 'node:child_process';
+import { chmod, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const benchmark = new URL('../scripts/record_worker_benchmark.mjs', import.meta.url).pathname;
+const receiptsPath = new URL('../deploy/worker/receipts.json', import.meta.url);
+const ALIAS = 'SmolVLM2-2.2B-Instruct';
+
+const FAKE_WORKER = `#!/usr/bin/env python3
+import json, os
+from http.server import BaseHTTPRequestHandler, HTTPServer
+loaded = os.environ['WORKER_MODE'] == 'loaded'
+class Handler(BaseHTTPRequestHandler):
+    def do_GET(self):
+        body = json.dumps({'data': [{'id': os.environ['WORKER_ALIAS']}] if loaded else []}).encode()
+        self.send_response(200)
+        self.send_header('Content-Type', 'application/json')
+        self.end_headers()
+        self.wfile.write(body)
+    def log_message(self, *_):
+        pass
+HTTPServer(('127.0.0.1', int(os.environ['WORKER_PORT'])), Handler).serve_forever()
+`;
+
+async function sandbox() {
+  const dir = await mkdtemp(join(tmpdir(), 'timmy-bench-'));
+  const gpuProbe = join(dir, 'nvidia-smi-stub');
+  await writeFile(gpuProbe, '#!/bin/sh\nprintf "NVIDIA A40, 46068, 1234\\n"\n');
+  await chmod(gpuProbe, 0o755);
+  const worker = join(dir, 'worker.py');
+  await writeFile(worker, FAKE_WORKER);
+  return { dir, gpuProbe, worker, out: join(dir, 'worker-benchmark.json') };
+}
+
+async function startWorker(box, mode) {
+  const port = String(30000 + (process.pid % 2000));
+  const proc = spawn('python3', [box.worker], {
+    env: { ...process.env, WORKER_MODE: mode, WORKER_PORT: port, WORKER_ALIAS: ALIAS },
+    stdio: 'ignore',
+  });
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    const probe = spawnSync('bash', ['-c', `curl --silent --output /dev/null --max-time 1 http://127.0.0.1:${port}/v1/models`], { encoding: 'utf8' });
+    if (probe.status === 0) break;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  return { proc, port };
+}
+
+function run(box, port, extra = []) {
+  return spawnSync('node', [benchmark, '--out', box.out, '--port', port, '--alias', ALIAS, '--gpu-probe', box.gpuProbe, ...extra], { encoding: 'utf8' });
+}
+
+test('a benchmark refuses to record numbers it did not measure on a GPU', async () => {
+  const box = await sandbox();
+  const { proc, port } = await startWorker(box, 'loaded');
+  try {
+    const result = spawnSync('node', [benchmark, '--out', box.out, '--port', port, '--alias', ALIAS, '--gpu-probe', join(box.dir, 'missing-smi')], { encoding: 'utf8' });
+    assert.notEqual(result.status, 0, 'measuring without a GPU probe must fail, not record zeros');
+    assert.match(result.stderr, /GPU|probe|VRAM/i);
+    assert.equal(existsSync(box.out), false, 'no receipt may be written from an unmeasured run');
+  } finally {
+    proc.kill('SIGKILL');
+  }
+});
+
+test('a benchmark refuses to time a model that is not loaded', async () => {
+  const box = await sandbox();
+  const { proc, port } = await startWorker(box, 'unloaded');
+  try {
+    const result = run(box, port);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /not loaded|ready/i);
+    assert.equal(existsSync(box.out), false, 'an unloaded model must not produce a latency receipt');
+  } finally {
+    proc.kill('SIGKILL');
+  }
+});
+
+test('a benchmark records cold start, warm latency, VRAM, and the pins it measured', async () => {
+  const box = await sandbox();
+  const { proc, port } = await startWorker(box, 'loaded');
+  try {
+    const result = run(box, port, ['--warm-samples', '5', '--start-command', 'bash -c "sleep 0.3"']);
+    assert.equal(result.status, 0, result.stderr);
+    const receipt = JSON.parse(await readFile(box.out, 'utf8'));
+    assert.equal(receipt.status, 'measured_on_target_gpu');
+    assert.equal(receipt.worker.alias, ALIAS);
+    assert.match(receipt.worker.baseUrl, new RegExp(`^http://127\\.0\\.0\\.1:${port}/v1$`));
+    assert.match(receipt.gpu.name, /NVIDIA A40/);
+    assert.equal(receipt.gpu.vramUsedMiB, 1234);
+    assert.equal(receipt.gpu.vramTotalMiB, 46068);
+    assert.ok(receipt.coldStartMs >= 300, 'cold start is measured, not asserted');
+    assert.equal(receipt.warmLatencyMs.samples, 5);
+    assert.ok(receipt.warmLatencyMs.p50 >= 0 && receipt.warmLatencyMs.p95 >= receipt.warmLatencyMs.p50);
+
+    const receipts = JSON.parse(await readFile(receiptsPath, 'utf8'));
+    assert.equal(receipt.pins.llamaCppCommit, receipts.llamaCpp.commit);
+    assert.deepEqual(receipt.pins.modelSha256, receipts.models.map(model => model.sha256));
+  } finally {
+    proc.kill('SIGKILL');
+  }
+});
+
+test('a benchmark receipt carries no notes, image bytes, or user data', async () => {
+  const box = await sandbox();
+  const { proc, port } = await startWorker(box, 'loaded');
+  try {
+    const result = run(box, port, ['--warm-samples', '3']);
+    assert.equal(result.status, 0, result.stderr);
+    const raw = await readFile(box.out, 'utf8');
+    const receipt = JSON.parse(raw);
+    assert.deepEqual(Object.keys(receipt).sort(), [
+      'coldStartMs',
+      'gpu',
+      'measuredAt',
+      'pins',
+      'schemaVersion',
+      'status',
+      'warmLatencyMs',
+      'worker',
+    ]);
+    assert.doesNotMatch(raw, /data:image|base64|note|observations|symptom/i);
+    // Cold start that was not measured is recorded as unmeasured, never as zero.
+    assert.equal(receipt.coldStartMs, null);
+  } finally {
+    proc.kill('SIGKILL');
+  }
+});

tests/worker-container.test.js

@@ -0,0 +1,151 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+
+const dockerfilePath = new URL('../deploy/worker/Dockerfile', import.meta.url);
+const receiptsPath = new URL('../deploy/worker/receipts.json', import.meta.url);
+const buildScriptPath = new URL('../deploy/worker/build_image.sh', import.meta.url);
+const runScriptPath = new URL('../deploy/worker/run_worker_container.sh', import.meta.url);
+const dockerignorePath = new URL('../.dockerignore', import.meta.url);
+const bootstrapPath = new URL('../scripts/bootstrap_selfhost_smolvlm.sh', import.meta.url);
+
+async function recipe() {
+  const [dockerfile, receipts, buildScript, runScript, dockerignore, bootstrap] = await Promise.all([
+    readFile(dockerfilePath, 'utf8'),
+    readFile(receiptsPath, 'utf8').then(JSON.parse),
+    readFile(buildScriptPath, 'utf8'),
+    readFile(runScriptPath, 'utf8'),
+    readFile(dockerignorePath, 'utf8'),
+    readFile(bootstrapPath, 'utf8'),
+  ]);
+  return { dockerfile, receipts, buildScript, runScript, dockerignore, bootstrap };
+}
+
+function bootstrapDefault(script, name) {
+  const match = new RegExp(`^${name}="\\$\\{[A-Z0-9_]*:-([^}]+)\\}"$`, 'm').exec(script);
+  assert.ok(match, `bootstrap script must declare a default for ${name}`);
+  return match[1];
+}
+
+test('the worker image pins llama.cpp and both model hashes to the bootstrap receipts', async () => {
+  const { dockerfile, receipts, bootstrap } = await recipe();
+  const commit = bootstrapDefault(bootstrap, 'LLAMA_CPP_COMMIT');
+  const modelSha = bootstrapDefault(bootstrap, 'MODEL_SHA256');
+  const mmprojSha = bootstrapDefault(bootstrap, 'MMPROJ_SHA256');
+
+  // Receipts are the runtime/CI source of truth and must not drift from the host bootstrap.
+  assert.equal(receipts.llamaCpp.commit, commit);
+  assert.equal(receipts.llamaCpp.repository, 'https://github.com/ggml-org/llama.cpp');
+  assert.deepEqual(receipts.models.map(model => model.sha256), [modelSha, mmprojSha]);
+  assert.deepEqual(receipts.models.map(model => model.file), [
+    'SmolVLM2-2.2B-Instruct-Q4_K_M.gguf',
+    'mmproj-SmolVLM2-2.2B-Instruct-Q8_0.gguf',
+  ]);
+  assert.match(receipts.llamaCpp.commit, /^[0-9a-f]{40}$/);
+  for (const model of receipts.models) assert.match(model.sha256, /^[0-9a-f]{64}$/);
+
+  // The image builds the same pinned revision: the build args default to the receipts.
+  assert.match(dockerfile, new RegExp(`^ARG LLAMA_CPP_COMMIT=${commit}$`, 'm'));
+  assert.match(dockerfile, new RegExp(`^ARG MODEL_SHA256=${modelSha}$`, 'm'));
+  assert.match(dockerfile, new RegExp(`^ARG MMPROJ_SHA256=${mmprojSha}$`, 'm'));
+  assert.match(dockerfile, /git fetch --depth 1 origin "\$\{LLAMA_CPP_COMMIT\}"/);
+  assert.match(dockerfile, /git checkout --detach FETCH_HEAD/);
+});
+
+test('the worker image uses digest-pinned bases and refuses floating model sources', async () => {
+  const { dockerfile, receipts } = await recipe();
+
+  const froms = dockerfile.split('\n').filter(line => line.startsWith('FROM '));
+  assert.equal(froms.length, 2, 'the recipe is a build stage and a runtime stage');
+  for (const line of froms) assert.match(line, /@sha256:[0-9a-f]{64}/, `base must be digest-pinned: ${line}`);
+  // The recorded receipts and the recipe must name the same immutable bases.
+  const digests = froms.map(line => /@(sha256:[0-9a-f]{64})/.exec(line)[1]);
+  assert.deepEqual(digests, [receipts.baseImages.build.digest, receipts.baseImages.runtime.digest]);
+  assert.equal(receipts.baseImages.build.reference, 'nvidia/cuda:12.4.1-devel-ubuntu22.04');
+  assert.equal(receipts.baseImages.runtime.reference, 'nvidia/cuda:12.4.1-runtime-ubuntu22.04');
+  assert.doesNotMatch(dockerfile, /:latest|ggml-org\/llama\.cpp@?main|refs\/heads\/(?:main|master)/);
+  // Weights are never baked in; the model arrives as a read-only mount.
+  assert.doesNotMatch(dockerfile, /^COPY .*\.gguf/m);
+  assert.doesNotMatch(dockerfile, /^ADD /m);
+  assert.match(dockerfile, /\/models/);
+});
+
+test('the worker image runs unprivileged with no default credentials and a post-load healthcheck', async () => {
+  const { dockerfile } = await recipe();
+  // Directives may be wrapped with a line continuation; assert on the joined directive text.
+  const directives = dockerfile.replace(/\\\n\s*/g, ' ');
+
+  const user = /^USER (?!root)(\S+)$/m.exec(dockerfile);
+  assert.ok(user, 'the runtime stage must drop to an unprivileged user');
+  assert.match(user[1], /^\d+:\d+$/, 'use a numeric uid:gid so the image needs no passwd entry');
+  assert.doesNotMatch(dockerfile, /^ENV .*(?:API_KEY|TOKEN|PASSWORD|SECRET)[ =]/im);
+  // Health must gate on the loaded model, so the container is not "healthy" while it cannot answer.
+  assert.match(directives, /^HEALTHCHECK .*timmy-worker-ready/m);
+  assert.match(directives, /--start-period=\d+s/);
+  assert.match(directives, /--host", "127\.0\.0\.1"/, 'the health probe runs on the container loopback');
+  // The container listens inside its own network namespace; the run recipe, not the image, decides
+  // exposure and publishes on loopback only (asserted separately).
+  assert.match(dockerfile, /--host 0\.0\.0\.0|TIMMY_MODEL_HOST=0\.0\.0\.0/);
+});
+
+test('the build refuses a floating or missing pin before it reaches docker', async () => {
+  const floating = spawnSync('bash', [buildScriptPath.pathname, '--print-plan'], {
+    encoding: 'utf8',
+    env: { ...process.env, TIMMY_LLAMA_CPP_COMMIT: 'latest' },
+  });
+  assert.notEqual(floating.status, 0, 'a floating llama.cpp ref must be rejected');
+  assert.match(floating.stderr, /pin|40-hex|floating/i);
+
+  const missingSha = spawnSync('bash', [buildScriptPath.pathname, '--print-plan'], {
+    encoding: 'utf8',
+    env: { ...process.env, TIMMY_MODEL_SHA256: '' },
+  });
+  assert.notEqual(missingSha.status, 0, 'a missing model hash must be rejected');
+
+  const plan = spawnSync('bash', [buildScriptPath.pathname, '--print-plan'], { encoding: 'utf8' });
+  assert.equal(plan.status, 0, plan.stderr);
+  assert.match(plan.stdout, /llama\.cpp commit: [0-9a-f]{40}/);
+  assert.match(plan.stdout, /SmolVLM2-2\.2B-Instruct-Q4_K_M\.gguf sha256: [0-9a-f]{64}/);
+  assert.match(plan.stdout, /bind address: 127\.0\.0\.1:8080/);
+  assert.match(plan.stdout, /publish: 127\.0\.0\.1:8080/);
+});
+
+test('the run recipe publishes on loopback only and drops every privilege it can', async () => {
+  const { runScript } = await recipe();
+
+  assert.match(runScript, /127\.0\.0\.1:\$\{?PORT/);
+  assert.match(runScript, /--read-only/);
+  assert.match(runScript, /--cap-drop[= ]ALL/);
+  assert.match(runScript, /no-new-privileges/);
+  assert.match(runScript, /--security-opt/);
+  assert.doesNotMatch(runScript, /--privileged/);
+  assert.doesNotMatch(runScript, /-p "\$PORT:/);
+  assert.doesNotMatch(runScript, /\b0\.0\.0\.0\b/);
+  // The model mount is read-only, and no credential has a default value.
+  assert.match(runScript, /:ro\b/);
+  assert.doesNotMatch(runScript, /(?:API_KEY|TOKEN|PASSWORD)=[^\s"']/);
+});
+
+test('the run recipe refuses to publish the worker anywhere but loopback', async () => {
+  const hostile = spawnSync('bash', [runScriptPath.pathname, '--print-plan'], {
+    encoding: 'utf8',
+    env: { ...process.env, TIMMY_WORKER_PUBLISH_HOST: '0.0.0.0' },
+  });
+  assert.notEqual(hostile.status, 0, 'a non-loopback publish must be refused');
+  assert.match(hostile.stderr, /loopback|127\.0\.0\.1/i);
+
+  const plan = spawnSync('bash', [runScriptPath.pathname, '--print-plan'], { encoding: 'utf8' });
+  assert.equal(plan.status, 0, plan.stderr);
+  assert.match(plan.stdout, /publish: 127\.0\.0\.1:\d+/);
+});
+
+test('the build context excludes weights, user images, releases, and secrets', async () => {
+  const { dockerignore } = await recipe();
+
+  for (const pattern of ['*.gguf', 'artifacts/', 'video/', 'models/', '.git/', 'node_modules/', '.env', '.env.*']) {
+    assert.ok(dockerignore.split('\n').includes(pattern), `dockerignore must exclude ${pattern}`);
+  }
+  // Committed synthetic fixtures are fine, but a real medical corpus directory is never buildable.
+  assert.doesNotMatch(dockerignore, /^!.*\.gguf$/m);
+});

tests/worker-readiness.acceptance.mjs

@@ -0,0 +1,91 @@
+import { chromium } from 'playwright';
+import assert from 'node:assert/strict';
+import { mkdir } from 'node:fs/promises';
+
+// Issue #15: readiness must pass only after the pinned model is loaded. A worker that answers
+// /v1/models is reachable, but reachable is not loaded — the app must not offer an AI control
+// that fails after the upload.
+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));
+let modelLoaded = false;
+let analysisRequests = 0;
+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: modelLoaded,
+  }),
+}));
+await page.route('**/api/analyze', route => {
+  analysisRequests += 1;
+  return route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      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.goto('http://127.0.0.1:4173', { waitUntil: 'networkidle' });
+await page.evaluate(() => localStorage.clear());
+await page.reload({ waitUntil: 'networkidle' });
+
+// 1. Worker reachable, pinned model not loaded: no AI promise, no dead control, one action to manual.
+await page.locator('[data-scan]').click();
+await page.getByText(/model is not loaded/i).waitFor();
+// Visual acceptance: the not-loaded state must be visually distinct from the ready and offline
+// states, not an unstyled div that reads like either one of them.
+const loadingStatus = page.locator('.model-status.loading');
+assert.equal(await loadingStatus.count(), 1, 'the not-loaded state needs its own status treatment');
+assert.equal(await loadingStatus.evaluate(el => getComputedStyle(el).backgroundColor), 'rgb(253, 243, 216)');
+assert.equal(await page.getByText(/Self-hosted model ready/i).count(), 0, 'an unloaded model must never be reported ready');
+assert.equal(await page.locator('#analyze-photo').count(), 0, 'no analyze control before the model is loaded');
+await page.locator('#gallery-photo').setInputFiles('tests/fixtures/synthetic-type4.jpg');
+await page.getByText(/Ready for your review/i).waitFor();
+assert.equal(await page.getByText(/model is not loaded/i).count() > 0, true, 'the ready step still states why AI is unavailable');
+assert.equal(await page.locator('.consent-card').count(), 0, 'no consent is requested while the model is not loaded');
+assert.equal(await page.locator('#analyze-photo').count(), 0, 'no dead analyze control on the ready step');
+const fallback = page.locator('#manual-from-scan');
+assert.equal(await fallback.isVisible(), true);
+assert.match(await fallback.innerText(), /without AI|manual/i);
+await fallback.click();
+assert.equal(await page.getByText('Pick the closest form').isVisible(), true, 'one action reaches manual Bristol entry');
+assert.equal(analysisRequests, 0, 'nothing is uploaded before the pinned model is loaded');
+await page.screenshot({ path: 'artifacts/worker-model-loading-mobile.png' });
+await page.locator('#close-sheet').click();
+
+// 2. The pinned model loads: the same flow now offers consent and analysis, and analysis works.
+modelLoaded = true;
+await page.locator('[data-scan]').click();
+await page.getByText(/Self-hosted model ready/i).waitFor();
+await page.locator('#gallery-photo').setInputFiles('tests/fixtures/synthetic-type4.jpg');
+await page.getByText(/Ready for your review/i).waitFor();
+assert.equal(await page.locator('.consent-card').isVisible(), true, 'consent returns once the model is loaded');
+await page.locator('#ai-consent').check();
+await page.locator('#analyze-photo').click();
+await page.getByText(/83% confidence/i).waitFor();
+assert.equal(analysisRequests, 1, 'analysis is offered exactly when the model is loaded');
+await page.screenshot({ path: 'artifacts/worker-model-loaded-mobile.png' });
+
+assert.deepEqual(errors, []);
+await context.close();
+await browser.close();
+console.log('PASS readiness waits for the loaded pinned model: no AI control before load, full AI path after load');

tests/worker-ready.test.js

@@ -0,0 +1,107 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const gate = new URL('../scripts/worker_ready.sh', import.meta.url).pathname;
+const bootstrap = new URL('../scripts/bootstrap_selfhost_smolvlm.sh', import.meta.url);
+const ALIAS = 'SmolVLM2-2.2B-Instruct';
+
+const FAKE_SERVER = `#!/usr/bin/env python3
+import json, os, sys
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+mode = os.environ['WORKER_MODE']
+counter_path = os.environ['WORKER_COUNTER']
+count = int(open(counter_path).read() or '0') if os.path.exists(counter_path) else 0
+
+class Handler(BaseHTTPRequestHandler):
+    def do_GET(self):
+        global count
+        count += 1
+        open(counter_path, 'w').write(str(count))
+        loaded = mode == 'loaded' or (mode == 'flip' and count > 2)
+        body = json.dumps({'data': [{'id': os.environ['WORKER_ALIAS']}] if loaded else []}).encode()
+        self.send_response(200)
+        self.send_header('Content-Type', 'application/json')
+        self.end_headers()
+        self.wfile.write(body)
+    def log_message(self, *_):
+        pass
+
+HTTPServer(('127.0.0.1', int(os.environ['WORKER_PORT'])), Handler).serve_forever()
+`;
+
+async function withWorker(mode, run) {
+  const sandbox = await mkdtemp(join(tmpdir(), 'timmy-worker-ready-'));
+  const counter = join(sandbox, 'count.txt');
+  await writeFile(counter, '0');
+  const server = join(sandbox, 'server.py');
+  await writeFile(server, FAKE_SERVER);
+  const port = String(20000 + (process.pid % 4000));
+  const { spawn } = await import('node:child_process');
+  const proc = spawn('python3', [server], {
+    env: { ...process.env, WORKER_MODE: mode, WORKER_COUNTER: counter, WORKER_PORT: port, WORKER_ALIAS: ALIAS },
+    stdio: 'ignore',
+  });
+  // Wait for the socket to accept connections before probing.
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    const probe = spawnSync('bash', ['-c', `curl --silent --output /dev/null --max-time 1 http://127.0.0.1:${port}/v1/models`], { encoding: 'utf8' });
+    if (probe.status === 0) break;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  try {
+    return await run(port);
+  } finally {
+    proc.kill('SIGKILL');
+  }
+}
+
+function gateRun(port, extra = []) {
+  return spawnSync('bash', [gate, '--port', port, '--alias', ALIAS, ...extra], { encoding: 'utf8' });
+}
+
+test('readiness passes once the pinned model is actually served', async () => {
+  await withWorker('loaded', async port => {
+    const result = gateRun(port);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, new RegExp(`${ALIAS} is loaded`));
+  });
+});
+
+test('a reachable worker with the model still loading is not ready', async () => {
+  await withWorker('unloaded', async port => {
+    const result = gateRun(port);
+    assert.equal(result.status, 3, 'reachable-but-unloaded must be its own failure, not a network error');
+    assert.match(result.stderr, /not loaded yet/i);
+  });
+});
+
+test('an unreachable worker is reported as unreachable', async () => {
+  const result = spawnSync('bash', [gate, '--port', '9', '--alias', ALIAS], { encoding: 'utf8' });
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /not reachable/i);
+});
+
+test('readiness never probes anything but loopback', () => {
+  const result = spawnSync('bash', [gate, '--host', '10.0.0.5', '--port', '8080'], { encoding: 'utf8' });
+  assert.equal(result.status, 64);
+  assert.match(result.stderr, /loopback/i);
+});
+
+test('readiness can wait for the model load it is gating', async () => {
+  await withWorker('flip', async port => {
+    const started = Date.now();
+    const result = gateRun(port, ['--wait', '15']);
+    assert.equal(result.status, 0, result.stderr);
+    assert.ok(Date.now() - started >= 300, 'the gate must actually wait rather than pass on the first probe');
+  });
+});
+
+test('the bootstrap exposes the same post-load gate instead of duplicating it', async () => {
+  const script = await readFile(bootstrap, 'utf8');
+  assert.match(script, /worker_ready\.sh/);
+  assert.match(script, /^  ready\)$/m);
+});