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.
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¶
- Conversation. The Pi transcript is the thread; Pi compaction keeps it bounded. An inbound message is admitted once per provider SID.
- 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),OutboxItemandSafetyEvent. Assessment and enrollment have their own documents. - Context.
runtime/context.tsrenders the record for Luna. AbeforeRequesthook 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. - Acts.
runtime/acts.ts: plain functions code runs on Jev's reading. - Guardrails. Jev's per-turn input reading and the output check.
- Gate.
channel/gate.ts: STOP, START, PAUSE, consent, exact crisis phrases, identity, assessment commands and menus, before any model. - Outbox.
runtime/outbox.ts: one durable task per message. - 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¶
- Admit.
runtime/twilio.tsverifies 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 onegivecare.turntask. - 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.
- 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.
- Act. Unless consent is not active, the turn is superseded, or Jev read an instruction override, code acts in the same commit (below).
- 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.
- 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.
- 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.