timmy
2094a07d9f
A backup is the person's own record and has to keep working as the AI fields evolve. - Export stamps schema version 2 and carries the confirmed logs plus the training contribution receipts, including withdrawn tombstones; both are written through an allowlist so unknown keys and credentials never leave the device. - Import accepts version 1 and 2. A version 1 file is upgraded, the notice names the version it came from, and entries that predate provenance stay null instead of being given a source they never recorded. - A file from a newer Timmy is refused with an update instruction, malformed, oversized and over-limit files fail closed, and a refused import leaves the ledger unchanged. - A log saved from a confirmed or corrected AI suggestion records its provenance (source, suggested visible fields, model, confirmedAt) and the entry sheet states it. - Service worker shell cache v5 -> v6 so installed clients actually receive the change. Evidence: tests/portability.test.js (7 unit cases), tests/portability.acceptance.mjs (real browser: v1 upgrade, future refusal with unchanged ledger, provenance recorded, export v2, round trip), release demo scenes with on-camera caption proof, and the release builder gate portable_backup_restore. Refs #35
5.8 KiB
Product Boundary and Release Authority Decision
- Status: Accepted
- Date: 2026-08-20
- Scope: Photo-assisted bowel logging and release governance
Context
Timmy can make a conservative visual suggestion from a user-selected image, but the available general-purpose model is not clinically validated. The product must preserve manual logging, deterministic red-flag escalation, and user control regardless of model availability or output.
Decision
Observable AI fields
AI may suggest only:
- visible Bristol form (Types 1–7);
- broad color;
- image quality.
Every suggestion is provisional, may abstain, and requires user review or correction before it can enter the journal. Symptoms remain user-entered, and journal saving is separate from training contribution consent.
Prohibited inferences
AI must not infer or claim disease, bleeding, pain, urgency, fever, vomiting, treatment, causation, or whether a food is safe. It must not replace professional care, suppress deterministic red-flag escalation, or present a suggestion as a diagnosis.
Conversational Hermes boundary
Timmy may expose a smart free-text conversation backed by a fully tool-capable Hermes Agent, but only through an authenticated, same-origin, server-side gateway. The browser never receives provider credentials or Hermes session IDs and cannot select the model, provider, tool policy, work directory, or internal session. Browser sessions use opaque HttpOnly cookies, bounded message and ledger sizes, single-flight turns, fixed time/rate/session limits, and sanitized output. Photos are excluded from chat context.
The application’s deterministic urgent-symptom guidance runs before chat and remains authoritative when Hermes is offline, slow, malformed, or conversationally mistaken. Hermes must not diagnose, invent symptoms, override escalation, or take external/destructive actions without explicit user intent and confirmation.
Availability and draft retention
Logging must never depend on AI availability. When the vision worker is offline, disabled, or still unknown, the photo-first flow offers no AI action and no analysis-consent prompt, and manual Bristol entry remains one action away from every photo step. A chosen photo and any entered context are retained as an in-session draft with a visible summary and an explicit start over; drafts are deliberately not persisted to storage, so a photo awaiting consent is never written to disk. The service worker never caches analysis requests or image bodies.
Training contribution consent
Contributing a confirmed photo to training is a second consent, not a side effect of logging. A journal save is never a training contribution; a contribution exists only after the person reads the current consent version and its receipt (contribution id, what is included, what is never included) and accepts it explicitly. The receipt carries the consent version it was accepted under, the confirmed Bristol form and broad color, and no note text, symptom answers, urgency/discomfort ratings, identity, or photo bytes.
Withdrawal is first-class: withdrawal keeps a tombstone naming every derived artifact by contribution id (raw image and confirmed label), so a deletion request can be addressed against the corpus rather than trusted to a promise. Delete-all clears the ledger, saved photos, and contribution receipts together.
This build acknowledges that records the intent and does not transmit a contribution until the corpus pipeline and privacy copy are reviewed in #22 and #25; the section says so in the app rather than implying an upload that does not exist.
Release authority
Hermes/Timmy is the release authority for routine engineering, test, build, deployment, and release-candidate preparation. Automated evidence must remain reproducible and must not overstate model accuracy or safety.
Human gates
Human gates are limited to:
- clinical and privacy review when language or policy crosses those boundaries;
- beta consent before participation;
- RC approval before shipping a release candidate.
Routine provisioning, deployment, label sweeps, and release-candidate assembly are not human-operated gates.
Backup portability and entry provenance
A backup is the person's own record and must keep working as the AI fields evolve.
- Every export stamps a schema version (currently version 2). The same file carries the confirmed logs and the training contribution receipts, including withdrawn tombstones.
- An older backup is upgraded on import, and the app says which version the file came from. Fields that did not exist when the file was written are left empty rather than invented.
- A backup from a newer version is refused with an instruction to update Timmy, and a refused import leaves the ledger unchanged.
- Malformed, oversized, and over-limit files fail before anything is replaced.
- Provenance is stored on the confirmed log when a saved entry began as a confirmed or corrected AI suggestion: source, suggested visible fields, the model that answered, and when it was confirmed. It never records a diagnosis, a symptom, or provider credentials, and backups are written through an allowlist so unknown keys never leave the device.
Consequences
- Model output is assistive and fail-closed, never authoritative.
- A generic open-weight VLM can support bootstrap experiments but cannot become the production Bristol classifier without the documented calibration and evaluation evidence.
- Release evidence and demonstrations must use fictional or synthetic data and state the non-diagnostic boundary honestly.