Skip to content

GiveCare SMS Runtime Contract

Type: reference.

This document is the canonical public contract for the SMS runtime. Cross-repo consumers use its exact gc-sms.care care.runtime.project owner projection, pinned to a commit through the root projection-ref command. They do not infer behavior from source files. Editing it does not refresh a consumer's pin.

Code gates. Jev reads. Code acts. Luna answers. Jev checks. The outbox delivers.

Each caregiver is one Pi conversation in one Cloudflare Durable Object. Code owns every effect. Luna (the language model) writes one reply per turn with no tools and never changes the record. Jev (the TypeSafe judge) answers narrow questions about the caregiver's message, catalog candidates and Luna's reply.

Primitives

  1. Conversation. The Pi transcript is the thread; Pi compaction keeps it bounded. An inbound message is admitted once per provider SID.
  2. Record. runtime/records.ts: Caregiver (consent, consent log, last safety concern, latest SID, pending burst), Message (one per SID), Profile (saved facts in the caregiver's words, typed care fields and when each was last asked, the plan step and outcomes, summary lines, the case's focus, what was offered and how it went), OutboxItem and SafetyEvent. Assessment and enrollment have their own documents.
  3. Context. runtime/context.ts renders the record for Luna. A beforeRequest hook adds this turn's brief (help sought, what was saved, the plan change, the one detail Luna may ask for, the tagged passages) to each Luna request without storing it.
  4. Acts. runtime/acts.ts: plain functions code runs on Jev's reading.
  5. Guardrails. Jev's per-turn input reading and the output check.
  6. Gate. channel/gate.ts: STOP, START, PAUSE, consent, exact crisis phrases, identity, assessment commands and menus, before any model.
  7. Outbox. runtime/outbox.ts: one durable task per message.
  8. Clock. Pi tasks sleep until they are due; the object's alarm is Pi's wake (runtime/caregiver.ts). There is no other scheduler.

Layers

Folder is role; .oxlintrc.json fences imports. care/ (pure domain) imports nothing of ours; channel/ imports care/; jev/ imports care/ and channel/; runtime/ imports everything. Nothing imports eval/ or scripts/.

Shared objects (Directory: phone ownership, enrollment and global budgets; EmailContact: email consent, suppression and delivery; EmailList: publication lists and fan-out; UnknownMessage) use native RPC with explicit recovery; their updates are not one global transaction.

Generated inputs (care/knowledge/generated/, care/assessment/generated/) are owner projections from benefits, knowledge and assessment, pinned in .givecare/module.json and synced with a verified owner commit. The catalog has four sources: benefits, resources, strategies and guidance.

Turn

  1. Admit. runtime/twilio.ts verifies the exact signed URL and fields. receive (runtime/admit.ts) runs the gate in the SID-admission commit, so consent changes and a deterministic crisis route are durable before any model runs. Ordinary text joins the pending burst and creates one givecare.turn task.
  2. Gate. STOP/START/PAUSE change consent; carrier keywords get no app reply because the carrier answers them. An exact crisis phrase records a safety event and queues its route line, even under stopped consent (nothing sends). Paused or identity-uncertain text gets only the input guardrail.
  3. Read. Turns read in admission order. A turn a newer message already follows is screened, not answered: Jev's guard reads its own text, and only a route line answers it; with no reading it is flagged for review. The newest turn's assessment command, saved-notes command or tapped menu gets a code reply with no model. Otherwise Jev reads the whole unanswered burst with the recent thread. An urgent or emergency reading commits code's route line and Luna never runs, except a plain clinician concern, which Luna answers under the clinician line. No reading means the bounded fallback ending in the emergency line. Each caregiver may get 20 answered messages per hour; past that, one notice, then silence.
  4. Act. Unless consent is not active, the turn is superseded, or Jev read an instruction override, code acts in the same commit (below).
  5. Answer. Luna writes one reply as the conversation's own generation. Directory caps Luna at 300 replies per hour across caregivers (notice once). At most 2 Luna requests per turn (a reply and one correction), 3,200 output tokens each.
  6. Check. Jev judges the complete reply, each sentence against the passages it cites. A rejected reply gets one correction; a second rejection ends in the fallback. A rejected or superseded reply is edited out of the transcript. Code text (route lines, receipts, choices) is never judged.
  7. Send. The reply and receipts queue one OutboxItem (see Outbox).

Read and answer phases each have a 55-second deadline. Pi retries a failed provider request with backoff; task checkpoints carry progress across eviction.

Failure

Recovery sends one fixed reply and keeps the Message in review with its reasons; no staffed queue exists, so no reply promises follow-up. If the input reading crossed a safety floor, the reply is that floor's route line instead. If Jev never read the message, the fallback ends with the emergency line, sets no route and records no concern. A retry never lowers an observed floor.

Safety routes

channel/safetyCopy.ts holds the approved lines; jev/safetyFloor.ts chooses one from the reading's probability mass (not Choice confidence), so an unsure judge still floors:

Reading Reply
Emergency with a confident 911 or 988 and the other below the cutoff That referral's line and route
Emergency without that specificity The combined 911/988 line, route 911
Urgent with protective_services The protective-services line
Other urgent The urgent line; a plain clinician concern gets the clinician line above Mira's answer

A safety record is evidence, not a channel state: it pauses nothing, and the next message is screened again. Luna sees the concern for 14 days.

Acts

An act takes only the caregiver's exact words, refuses words not in the burst or holding a private identifier, commits its effect and leaves a code receipt. Luna is told not to claim a change herself.

Act Writes Rule
saveFacts The caregiver's sentences, with whom each is about Only a confident retain with a confident subject. A confident supersedes marks the named fact replaced; replaced facts never reach Luna.
movePlan One current step, its last five outcomes With no step, only an explicit commitment sets one. A stated replacement closes the step as replaced and sets the caregiver's words as the next one. Uncertain, paused or unrelated readings change nothing. Rechecks the step is still the one read.
saveCare Typed care fields (state, county, ZIP, stage, capacity, support, relationship, condition, living arrangement, work, hardest area, yes/no and number facts) Read from the message alone with not_stated first; code finds the numbers and a ZIP, Jev only names their field or confirms the ZIP. A county is stored only when New York is the state, stated in the same message or already saved.
allowAsk The one missing field Luna may ask for this turn; once the reply commits, when it was asked Code offers only unknown fields the case graph opens (UNLOCKS in care/profile.ts), none asked in the past week, within 2 asks a day and 6 a week in the first week, 3 after; none within a day of a safety concern or at low capacity. When the state is offered, a separate Noul asks whether the next useful step depends on it, and a yes asks for the ZIP when the Choice leans to it over the state, else the state. Otherwise Jev picks one or none; Luna words it.
lookup The message's tagged passages Only when Jev read a help request, an open practical problem, or an answer to the question Mira asked to find that help. A need the message names decides it; a request that names none takes the case's focus from the newest evidence (a hardest area stated since the last check, else that check's pressured areas, worsening first and improving last), across knowledge, services and, for money or services strain, benefits, judged against that focus; with no focus, no lookup. Every need tag Jev reads; one nearby search, for the first resource need it serves, near the ZIP the caregiver wrote this turn, else the stored ZIP (where the care recipient lives, as Jev read it). A claim bound to states is kept only when one of them is the case's state.
scheduleCheckBack One follow-up delivery Only for a check-in the caregiver asked for; code derives the time from day and daypart in their timezone or refuses with a receipt.

recordSafety and assessment answers are code's own writes. Thresholds live in JUDGMENT_THRESHOLDS (care/judgment.ts); they are operating cutoffs, not calibrated accuracy.

Forgetting. "What you remember" lists saved notes by number. Whole-message FORGET <number> or FORGET ALL removes them and their words in the plan; FORGET ALL also clears the care fields. The turn waits for older care tasks, places a native Pi context reset, then confirms. Later model requests never see the earlier thread, summaries included. Stored message history remains; account deletion clears the object.

Retention (owner decision 2026-10-31, not yet enforced): messages 12 months; saved facts, scores and plan while active then 12 months; safety events 24 months; consent and deletion receipts 7 years. FORGET and deletion override.

Reply contract

A reply is Luna's plain text or a code text. Passage tags (p<turn-task-id>-<n>) resolve only against this turn's passages; code strips them and binds the cited passages to each sentence. Limits: 640 characters, four SMS segments, not empty. The reply check (jev/reply.ts) rejects the whole draft for any of: benefits certainty, clinical or legal authority, unsafe assistance, Mira claiming an outside action or presence, a claimed durable write, more than one question or a question for a detail the turn did not allow (an optional reading: no answer rejects nothing), an external claim without supporting cited text (or the caregiver's own words: this turn and their saved notes), a URL, phone, form number, dollar figure or percentage the passages lack, or a missing or mismatched judgment receipt. Freshness is a hard cutoff: a stale catalog item is a missing one.

Code owns the whole reply for STOP/START/PAUSE/HELP, crisis phrases, safety routes, block explanations, assessment questions and readbacks, menus, the check-in text, the rate-limit notice and the fallback.

Assessments

CHECK, MORE and CHECK-IN start assessments; nothing starts from a timer. Code adds one invitation to an ordinary reply when a six-area check is due and nothing is pressing, at most weekly. Code asks each question and records only answers bound to the delivered question; scoring belongs to assessment. CHANGE 3 corrects the last readback. A plain number goes to the current delivered question (owner decision 2026-09-06). Runs silent for 7 days expire when next read.

Outbox

Every queued message gets one durable send task. The task sleeps until the message may send, then rechecks consent, quiet hours and ordering in the claim commit; a follow-up outside the daytime window sleeps to its opening. Directory caps sends at 25 per minute; a denied send sleeps a minute. The budget is asked only after policy settles, and a crisis line bypasses it. An unavailable Directory allows the send.

The claim is durable before Twilio is called. Unknown acceptance becomes ambiguous and is never resent. A crisis reply gets up to three attempts with backoff, ended by a delivery callback or a permanent rejection. Signed callbacks reconcile status, including one that arrives before the SID is attached.

Signup and web

POST /api/signup validates a US phone, name, email and explicit SMS consent; publication consent is a separate opt-in. Directory admits one enrollment per phone; repeated signup never reactivates stopped consent. The welcome is code's and introduces Mira as AI. A silent signup gets one consented, quiet-hours-bound follow-up. An assessment handoff must be unexpired, unused and bound to the signup email. STOP covers texts and every email the signup triggers. If texts are stopped before signup's email admission runs, admission is withheld: nothing is queued, so no receipt, no Weekly subscription and no confirmation. An assessment the caregiver brought still imports, because that is their data, not an outbound send. A Weekly subscription made on its own (/api/subscribe) belongs to the email contact and keeps its own unsubscribe, so STOP leaves it. Email routes and operator reads are in mira's docs/operations.md.

Principles

Care for both people, and keep their needs and danger distinct. Ground concern in evidence. Respond proportionately with the smallest useful step. Preserve the caregiver's agency: Mira prepares, people act, and code owns consent, privacy and every effect. Ask only what unlocks the next useful help, within the budget. When principles conflict, consent, privacy and authority boundaries hold, and the least restrictive adequate response wins.

Deliberate exclusions: no journey router or second policy engine, no form-like intake, no reminders or assessment timers, no parallel steps, no eligibility, clinical, legal or emergency-monitoring claims, and no live self-modification.

Gaps

Local proof is mechanical. Live replay, independent Jev calibration, real-phone SMS/RCS, workload latency and restore rehearsal remain unproven, and operator administration is not implemented.