Skip to content

LOOP LEDGER + PROOF MACHINE — BUILD SPEC

Audience: the Cursor agent (and Ryan). Read alongside AGENTS.md, the current gate spec, and PARKED.md. Principle: ONE spine, THREE read surfaces. The ledger records the loop; the veteran surface (return path), the org report, and the admin portal all read it. Nothing renders what the ledger didn't record.

1. THE SPINE (lives in last.vet-api Postgres)

coordination_loops

One row per veteran→org care loop. - id, veteran_id, org_id (nullable until Gate 2 orgs exist), need_category (Phase 1: mental_health only) - consent_ref (FK to the signed ROI / grant that scopes the loop) - state — enum: consent_granted → referral_made → referral_accepted → care_delivered → outcome_logged (+ revoked, expired) - created_at, closed_at

loop_events (append-only — the proof stream)

  • id, loop_id, event_type, occurred_at, actor_type (veteran | org | system), actor_ref
  • payload — PHI-FREE. Statuses, timestamps, category codes, measure deltas. Never names, DOB, SSN, diagnoses, note text.
  • No UPDATE, no DELETE. Corrections are new events.

Outcome payload (Phase 1 — deliberately minimal)

  • disposition (service-specific resolved/unresolved — incumbent parity)
  • measure: ONE instrument only — { instrument: "PHQ-9" | "GAD-7", baseline, closing, delta } — or a single veteran-reported item where no instrument exists
  • veteran_confirmed: boolean + timestamp

Heritage: this is last1ProofEvents.ts (the existing PHI-free proof outbox) grown into the system of record. Extend that pattern; do not build a parallel one.

2. HOW DATA ENTERS (no new mechanisms)

  • Org attestation — the closure link. When a loop reaches care_delivered, the org contact receives a link built on the SAME opaque, expiring, verify-gated secure-link mechanism as ROI delivery and provider invites (this is that mechanism's third use — do NOT build a second token system). It opens a token-scoped form: disposition + the one measure. Submit → outcome_logged event. No org account, no portal required pre-Gate 2.
  • Veteran confirmation — rides the Radio Check cadence. At the veteran's next check-in after care_delivered: "Did you get seen?" + the single measure item. Never a separate notification schedule — the system has one clock.
  • System events (consent granted/revoked, ROI delivered, referral state changes) are emitted by the existing flows as they execute.

Two-source outcomes (org-attested + veteran-confirmed) are the credibility feature. Both nullable — a loop can close org-only or veteran-only; the portal reports confirmation rate honestly.

3. READ SURFACE A — the veteran (the return path; see THE_RETURN_PATH.md)

"Your Loops" — a Home surface, Gate 1+. Rendered from the ledger + the existing consent access-event history: - Live referral state ("accepted in 2 days") - Closures ("care delivered — you confirmed") - The veteran's own measure trend (the veteran sees it FIRST) - Consent receipts ("viewed by Dr. Y on Tuesday — under the grant you control") - Gate 2 adds the donated-care meter No new data collection. The invention is pointing the rendering at the veteran first.

4. READ SURFACE B — the org report

Per-org aggregate over that org's loops: referrals received, acceptance time, closure rate, outcome deltas, confirmation rate. This IS the funder-ready report. LastVet's loop ledger is the native model of record for its own outcomes. The two-source outcome (org attestation + veteran confirmation) is verified and held natively in LastVet, anchored to an external measure or authority where one exists. last1.app does NOT hold the outcome as its record of truth — it is an INDEPENDENT REPLICATOR: it validates the LastVet outcome against the same external anchor and certifies it against the last1.org verified-outcome standard. Two independent systems agreeing — ideally both pointing at an external anchor, not at each other — is what makes the double-validation real rather than a mirror. One model of record per outcome (LastVet); one independent certifier (last1.app); neither is the other's source of truth. [Replication MECHANISM = Gate 2. The model-of-record PRINCIPLE holds from Gate 1, because D11's "verified outcome" unit depends on it.] (RealOutcomes is NOT in this path).

5. READ SURFACE C — the admin portal (the proof machine)

Read-only dashboards over the event stream — de-identified aggregates only, by construction (it reads proof events, never the record store; two-data-plane extended to analytics): - Active veterans · waitlist count · consent grants/revocations - Loops by state · time-to-acceptance · time-to-care · closure rate - Outcome-delta distribution · veteran-confirmation rate - Radio Check response rate · Part 2 consent-flow abandonment (first-class pilot metric) - CSV export The one button that matters — "Generate proof one-pager": an auto-rendered, timestamped page/PDF:

N closed veteran MH loops · median time-to-care X days · median measure delta Y · Z% veteran-confirmed That artifact is the Gate 2 deliverable, the investor slide, and the org leave-behind. Generated, never hand-written.

6. GATE MAPPING (do not pull forward)

Piece Gate
Ledger schema + system events from existing flows (consent, ROI delivery) Lands with the ROI API slice (Gate 0's api work) — smallest schema, events only from flows that exist
"Your Loops" veteran surface + veteran confirmation via Radio Check Gate 1 (with OS activation)
Closure link (org attestation) + full loop states + org report + last1.app sync Gate 2
Admin portal aggregates Grow with whatever events exist; proof one-pager button by Gate 2

7. GUARDRAILS

  • No PHI in loop_events, ever. If a metric needs PHI, the metric is wrong.
  • One secure-link mechanism. ROI delivery, provider invite, closure link = same token/verify/revoke core.
  • One clock. Nothing veteran-facing notifies outside the Radio Check cadence.
  • One measure. Phase 1 does not grow an instrument library.
  • Smallest schema that records the loop. This spec is a ceiling, not a floor to build past.

8. HORIZON — EXTERNAL-AUTHORITY OUTCOME ANCHOR (design case: VetClaims / VA rating delta)

PRINCIPLE: the strongest verified outcome is anchored to an authority OUTSIDE both LastVet and last1.app. Where such an anchor exists, outcome verification references it directly and both systems point at it independently.

DESIGN CASE — VA disability rating delta: a veteran's rating moves X% -> Y%. Quantified, VA-authoritative, real-world consequence. The platonic verified outcome — a real external improvement in a veteran's life, not an activity metric.

ELEGANT CLOSURE — the anchor is already in-surface: the VA Service History & Eligibility API returns the disability rating (confirmed in HORIZON_CROSS_ECOSYSTEM_VERIFICATION.md). So LastVet verifies the rating delta NATIVELY against the VA — the outcome does not depend on VetClaims' or anyone's self-report. An external party (VetClaims, a VSO, or the veteran) helps CAUSE the delta; the VA ASSIGNS it; LastVet READS it; last1.app CERTIFIES it.

TWO DISTINCT RISK SURFACES — do not conflate: 1. Claim-BUILDING input (health record -> claim evidence): PHI flow. BAA + consent-engine + 42 CFR Part 2 territory + counsel. This is partnership "Shape 2" and is gated. 2. Outcome VERIFICATION (reading before/after rating): lower risk — benefits data already in LastVet's API scope, not a health-record export. The clean core.

GUARDRAILS: HORIZON, post-Gate 2. Any VetClaims data integration routes through counsel (claims-adjacency to an unaccredited-claims-consultant space under active regulatory scrutiny, plus PHI). The rating-delta verification is the clean core; the record-sharing input is the gated part. Cross-ref: VetClaims partnership item (Outreach board); partnership Shapes 1/2/3.