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.

Canonical "where the ledger lives" (September 2026): LOOP1_COORDINATION_ARCHITECTURE.md is authoritative for org coordination loops (WIN, job_placement, org attestation, enrollment disposition, accountability dashboard). The system of record for org loops is last1.app (Postgres behind the monolith + edge stack on R940). This document remains the gate-mapped spec for LastVet-native ROI/consent proof events and read-surface behavior — do not treat §1 below as the org-loop SoR.

1. THE SPINE — two stores (do not conflate)

1a. Org coordination loop ledger — last1.app (canonical)

Org programs, enrollment lifecycle, attestation, Λ state, accountability metrics, org report aggregates. Implemented per LOOP1_COORDINATION_ARCHITECTURE.md. Agents: default here for coordination, disposition, and org dashboard work.

Gate 0 flows (ROI delivery, provider verify, consent grants) may emit PHI-free proof events from lastvet-api. This is not the org-loop system of record. Schema sketch (Gate 0 / MH referral legacy — extend only where Gate specs explicitly allow):

coordination_loops (LastVet — MH referral spine, optional / Gate 2 MH path)

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. Org-loop aggregates are read from the last1.app ledger (accountability dashboard, org report routes). LastVet may render veteran-facing summaries; last1.app is the system of record, not an independent replicator mirroring LastVet. Two-source outcomes (org attestation + veteran confirmation) are verified on the last1.app engine; LastVet surfaces nudges and veteran confirm where scoped. (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 Gate 2 — on last1.app ledger
Admin portal aggregates (org accountability dashboard, disposition §10.10) Built on last1.app; grow with events

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.