THREAD

Source Span Verification: Exact character coordinates bound to quotation
Stale Revision Defense: HTTP 409 STALE_REVISION_ERROR on obsolete write

Problem Statement: The Caregiver Coordination Dilemma

Family caregivers bear an immense, uncoordinated burden managing nonclinical transitions of care. Transport to critical follow-up appointments, clinic check-ins, and instructions are routinely scattered across phone calls, text message threads, paper discharge packets, and fragmented patient portals.

In these informal coordination channels, a critical failure mode occurs: silent revision drift.

A clinic issues an updated discharge summary moving an appointment from Thursday at 10:00 to Friday at 14:00.
In traditional shared calendars, spreadsheets, or group chats, a family member who agreed to drive the patient based on the original note continues to operate on stale instructions.
Prior sign-offs appear valid even when the underlying clinical reality has shifted, leading to missed appointments, delayed post-discharge care, and caregiver burnout.

Existing tools either treat care notes as static unstructured text or blindly overwrite prior state without alerting task owners.

Proposed Solution: THREAD

THREAD is a local-first caregiver coordination architecture designed to eliminate silent coordination drift through deterministic revision invalidation.

Rather than relying on informal trust or automated assumptions, THREAD binds actionable transport tasks directly to verified textual citations in source documents, enforcing explicit re-review whenever underlying records change.

The 4-Stage Core Mechanism:

Exact Source Citation & Line Anchoring: Caregivers inspect the raw clinic note. When extracting an appointment, the system captures exact Unicode character offsets and line coordinates (Follow-up appointment: Thursday at 10:00.). Citations represent verifiable textual origin, not inferred authority.
Decoupled Ownership vs. Acknowledgement: Assigning a ride task to a family caregiver (Ownership) and verifying understanding of the exact quoted instructions (Acknowledgement) are treated as distinct, auditable state machine events.
Explicit Claimed Replacement: When an updated note arrives with a new date, it does not silently overwrite the original. The user inspects side-by-side line diffs and records an explicit, claimed replacement relationship between the two document versions.
Authoritative Stale Invalidation (HTTP 409 STALE_REVISION_ERROR): The moment a replacement is established, prior task acknowledgements are marked STALE. Any attempt to execute or acknowledge obsolete instructions is rejected by the authoritative service with a 409 Conflict. The caregiver is guided to re-read the new citation and issue a fresh acknowledgement, while the historical audit trail remains immutable and accessible.

Guardrails & Nonclinical Safety Boundaries

THREAD is deliberately bounded to protect patient safety:

Strictly Nonclinical Scope: Only nonclinical coordination (transportation, office contacts) is actionable.
Medication Text as Read-Only Quotation: Medication and treatment lines are strictly displayed as read-only quotations. THREAD performs zero dosage calculation, prescription generation, administration scheduling, or clinical advice. Any attempt to generate clinical tasks from medication citations is blocked with 422 TASK_NOT_ALLOWED.
Conservative Conflict Handling: When competing, un-reconciled documents exist (e.g., conflicting discharge times), THREAD refuses to guess a winner. Both notes remain visible, tasks are marked BLOCKED, and a neutral clarification question is formatted for the healthcare provider.
Privacy & Local-First: Operates by default with synthetic, fictional cases on localhost without transmitting personal health information (PHI) to cloud servers.

Technical Architecture & Implementation

THREAD is built with an emphasis on transparency, auditable state transitions, and zero unnecessary runtime bloat:

Authoritative Core: Pure Python 3.10+ standard library implementation (http.server, sqlite3, dataclasses, hashlib, urllib). Zero third-party dependencies required for local execution.
Durable Persistence: SQLite backend with Write-Ahead Logging (WAL), foreign key enforcement (ON DELETE CASCADE), and atomic transaction guarantees.
Hosted Cloud Demonstration:
- Serverless API: Deployed on Vercel (api/index.py, vercel.json) with strict Origin and CSRF controls.
- State Store: Supabase PostgreSQL backend (thread_demo_sessions) utilizing atomic Compare-And-Swap (CAS) optimistic concurrency control and session isolation.
Optional AI Source Navigation: Integrated with NVIDIA NIM hosted microservices running nvidia/nemotron-3.5-lightning-30b-a3b.
- Reasoning is disabled for predictable JSON-only line selection.
- Output is strictly bounded to line index extraction; model prose is discarded.
- Spans are deterministically reconstructed against original text. Missing credentials or provider timeouts fail gracefully to manual review.
Frontend: Vanilla ES6 JavaScript, HTML5, and responsive CSS with clean dark/light semantic design tokens, live diff visualization, and complete keyboard/ARIA accessibility primitives.

Verification & Testing Rigor

THREAD has been verified through a comprehensive test harness:

49/49 Python Test Suite Passing: Exhaustive coverage across domain invariants, SQLite storage roundtrips, atomic CAS concurrency, HTTP REST contract compliance, and NVIDIA NIM boundaries.
Zero Resource Warnings: Strict teardown ensuring zero leaked socket descriptors or unclosed HTTP connections under Python 3.14.
Headless UI Flow Verification: Node.js UI-controller test (tests/test_ui_flow.js) driving the live HTTP API through full end-to-end user handoffs, stale write rejections, idempotency retries, and scoped resets.
Live Production Test Suite: tests/test_hosted.py verified against the production deployment on Vercel and Supabase.

How to Try & Inspect

Live Hosted Demo: https://thread-caregiver-demo.vercel.app
GitHub Repository: https://github.com/dumbthing999-ui/thread-caregiver
Video Walkthrough: https://www.youtube.com/watch?v=FiSS4CqtSqo
Local Reproduction: bash git clone https://github.com/dumbthing999-ui/thread-caregiver.git cd thread-caregiver python3 run_app.py --port 8000 Open http://127.0.0.1:8000/ and select Judge demo · scripted example to experience the step-by-step invalidation workflow.

Built With

css3
html5
javascript
nvidia-nim
python
rest-api
sqlite
supabase
vercel