Skip to content

ADR 002: LastVet-First Patient Sharing, Civilian Sharing Tabled

Status

Accepted

Date

2026-05-20

Context

After the original generic provider-network design was reviewed, two product calls were made:

  1. First (and only) integration target: LastVet. Veterans on Onset will push their protocol and adherence to LastVet. LastVet then handles provider sharing through its existing provider portal, consent grants, NPI verification, audit trail, and 42 CFR Part 2 redaction. We are not building any of that on Onset.
  2. Civilian patient sharing is tabled until there's a need. A civilian patient who wants their primary-care provider to see their Onset protocol is, for now, served by their provider creating a free practitioner account on clinic.theonset.app. That gives the provider read access to that patient's adherence via the existing clinic channel. No new Onset-side surface for civilian sharing in v1.

This is a deliberate scope reduction from the earlier design. The earlier design assumed Onset would stand up a SMART-on-FHIR-style provider authorization server, publish a scope catalog, and accept inbound provider OAuth clients. None of that is needed for the actual partner.

Decision

v1 patient sharing scope

  • One direction: Onset → LastVet, push only.
  • One target: LastVet API (/api/v1/me/sync and friends — see ONSET_TO_LASTVET_SYNC_CONTRACT.md).
  • One audience: veterans who use both Onset and LastVet.
  • One consent surface: Onset Settings → "Connected health records" → "Connect to LastVet".

What LastVet-side already exists

LastVet already has the things the earlier design assumed Onset had to build: - A provider portal (provider.last.vet) with NPI-verified provider accounts and subscription tiers. - A consent_grants table with per-category, per-grantee, revocable, expiring grants. - A connection_requests veteran↔provider acceptance flow. - A health_record_items table with a source column for multi-source aggregation (today: va, lastvet, provider). - A /me/sync ingest endpoint that already accepts categorized health items from a patient app — currently hard-coded to source: "va" for VA Lighthouse imports. - 42 CFR Part 2 substance-use redaction in the consent engine. - Append-only audit log.

Onset just needs to be a new source in that ecosystem.

What Onset will not build in v1

  • An inbound OAuth authorization server.
  • A SMART-on-FHIR scope catalog or FHIR projection endpoints.
  • A provider-facing read API or portal.
  • Provider account management, NPI verification, or subscription billing for providers.
  • A non-LastVet aggregator client.
  • A snapshot-share / PDF / signed-URL non-veteran path.

If any of those become necessary later, they will be additive and self-contained, not refactors of what we ship for LastVet.

Civilians in v1

Onset Settings on iOS will: - Show the "Connect to LastVet" card to all users under a "Veteran tools" subheader. We do not gate the card on a self-attested is_veteran flag — see LASTVET_IDENTITY_BRIDGE.md for the rationale. Successful OAuth into LastVet is the verification. Civilians who tap Connect simply can't authenticate at LastVet's end and the connection fails. - Add a one-line non-veteran note alongside the card: "Not a veteran? Ask your provider to sign up at clinic.theonset.app to see your protocol there." Static text, no separate flow.

This is intentional. We do not have, and will not add, an Onset-side veteran self-identification question. Such a question is unverified by definition; relying on it would create a soft fiction. LastVet runs the actual VA Lighthouse verification work — we trust their answer.

Why this scoping

  • LastVet is built. The earlier design described a system Onset doesn't have to build because the partner already has it.
  • Building a generic OAuth server is months of work and has zero adoption until somebody asks for it. We know one partner asked: LastVet. So we ship LastVet.
  • Routing civilians through clinic.theonset.app re-uses the existing practitioner-patient channel, including the adherence sharing the practitioner already has access to. No new code, no new audit surface, no new compliance review.
  • A snapshot-share for civilians is a real product — but it's a different product (PDF rendering, signed URLs, expiry, optional revocation, possibly e-signature). It belongs in its own roadmap slot, not bolted onto the LastVet pilot.

Consequences

Positive

  • ~80% of the original docs become unnecessary.
  • Onset's compliance posture for v1 is unchanged: we're a patient-controlled outbound integration, not a covered third-party provider.
  • LastVet's existing partner reviews, BAAs, and Part 2 work get reused, not duplicated.
  • We can ship the integration in weeks, not quarters.

Tradeoffs

  • Civilian patients who want their PCP to see their protocol have a worse experience: their PCP has to sign up on clinic.theonset.app, which is positioned as a clinic tool. Acceptable for v1 — we don't yet have a single civilian customer asking for this.
  • We are coupled to LastVet for the patient-sharing story. If LastVet's API changes, we follow. Acceptable because we own LastVet.
  • The earlier "generic provider network" framing is gone. If we ever want to integrate with Apple Health Records, MyChart, or another aggregator, we'll write a new doc and likely a new client per aggregator. We'll cross that bridge when one shows up.

Implementation outline

See: - ONSET_TO_LASTVET_SYNC_CONTRACT.md — the wire-level contract. - LASTVET_API_CHANGES_REQUIRED.md — the small set of changes on the LastVet side. - LASTVET_CONNECT_AND_REVOKE.md — the patient-facing connect/revoke flow. - LASTVET_INTEGRATION_PLAN.md — phased rollout.

What this replaces

  • The earlier PROVIDER_LAST_VET_PILOT_ROLLOUT.md (a generic-provider rollout that happened to mention LastVet) is rewritten under the same filename to be the LastVet implementation plan.
  • PROVIDER_AUTH_SMART_FHIR.md and PROVIDER_DATA_ACCESS_CONTRACT.md are deleted; their content was generic-provider machinery Onset is not building.
  • PROVIDER_CONSENT_MODEL.md is rewritten to cover only the patient↔aggregator connection (see LASTVET_CONNECT_AND_REVOKE.md); the per-scope provider-grant catalog is gone because it lives in LastVet, not in Onset.