v6 Stage Resolver — Truth Table¶

Status: Draft (2026-05-12) — Phase 0 companion artifact for docs/specs/conversation-v6-feature.md. Blocks Phase 1 implementation of app/services/stage_resolver.py. DRAFT for SD review before Dr. Naidu clinical review (Phase 2a). Parent spec: docs/specs/conversation-v6-feature.md — §2.5 stage definitions, §2.6 resolver summary. This doc is the full expansion of §2.6. Tracking issue: #836.

This is a spec, not code. Phase 1 reads it and builds stage_resolver.py from the predicates, ordering, and signature below. Every row here becomes a fixture in tests/test_stage_resolver_determinism.py.

1. Function signature¶

def resolve_stage(
    case: Case,                       # Tenant-scoped Case ORM object
    workflow_state: WorkflowState,    # Pydantic view over case.workflow_state JSONB
    layer_state: PatientLayerState,   # Pydantic view over case.layer_state JSONB
    recovery: RecoveryWorkflowState | None,  # case.workflow_state["recovery"] sub-object
    *,
    now: datetime,                    # Injected for determinism — no time.now() inside
    strict: bool = True,              # Mirrors stage_resolver_strict flag (parent §2.6)
) -> StageResolution:
    """Pure function with respect to return value. No I/O, no LLM, no DB writes. Logging is allowed for malformed-input observability — see `stage_resolver.py` lines 146, 158, 168 for the three warn/debug paths.

    Returns the active stage_id plus the reason code that matched.
    On malformed input or no-rule-match, returns stage_id="support"
    with reason="fallback:<cause>". Never raises user-visible errors.
    """

StageResolution is (stage_id: str, reason: str, matched_predicate_index: int). The reason string is what populates Telegram alert + Langfuse trace tags (parent §2.6 PHI-safe schema).

Lockstep guarantee (parent §2.6 "Determinism guarantee"): resolve_stage is a pure function over its arguments. No DB reads, no Redis reads, no datetime.now(), no Flagsmith reads, no exceptions raised. The strict flag changes what the caller does with the result (alert vs no alert) — it does not change the returned StageResolution. CI gate: tests/test_stage_resolver_determinism.py runs Hypothesis property tests asserting resolve_stage(x) == resolve_stage(x) over the full input domain and that mocking time.time(), random, and the DB session produces identical output.

2. Inputs¶

2.1 Case fields read¶

2.2 WorkflowState booleans¶

Read from case.workflow_state JSONB. Each defaults to False if absent (the resolver MUST tolerate missing keys without raising).

2.3 PatientLayerState completions¶

Read from case.layer_state JSONB. Each is {completion: float[0..1], confidence: float[0..1]}; missing keys default to {completion: 0.0, confidence: 0.0}.

The resolver consumes completion only. confidence is reserved for future extractor-quality gating; explicitly not in any v6 predicate.

2.4 Recovery sub-state¶

Read from case.workflow_state["recovery"] via get_recovery_state(case) → RecoveryWorkflowState | None (app/models/recovery_state.py). When None, the recovery sub-flow has not started. When present, state is one of recovery_offered, recovery_accepted, recovery_in_progress, recovery_completed, recovery_declined.

case.recovery_milestones — list of milestone records (presence + ISO date). Empty [] is valid and triggers the transient-state branch in parent §2.6.

2.5 NOT inputs to the resolver¶

Explicitly excluded (reviewers should not propose adding):

• Conversation history / message content / NLU intent classification of latest user turn. Stage is state-driven, not utterance-driven. Conversation intent influences extractor routing in triage_agent, not stage selection.
• prefer_consult_method — recorded on the case but does not branch the stage. Routing between MSO video and async consult is a knowledge-addendum decision, not a stage decision.
• ehr_completeness — a derived metric for matching-engine gates; the resolver uses medical_status.completion instead.
• LLM-emitted conversation_intent classification — would create an LLM round-trip inside the resolver, violating purity.
• Time-of-day / quiet hours — handled by the messaging layer, not stage selection.
• Tenant identity (beyond the assertion that tenant_id is not None). Per-tenant stage customization is out of scope for v6.

3. Stage catalog¶

Twelve stages. Exactly one is active per turn. Order in this list = predicate evaluation order (first match wins; rationale in §5).

3.1 support (fallback / safety net)¶

• Purpose: Catch-all for malformed state or "I don't know what stage." Keeps voice intact, no proactive question, no advancement pressure.
• Predicate: Activates when no other stage's predicate matches OR any malformed-state condition triggers (see §4 fallback cases). Despite being listed first in §3, it is evaluated last (see §5 precedence) — the order in this catalog is logical, not evaluation order.
• Allowed addendums: None. support deliberately runs base-only to minimize footgun surface during incident response.
• Exit conditions: Any other stage's predicate becomes satisfied on the next turn (e.g., state corruption is repaired by a coordinator).

3.2 discovery¶

• Purpose: Open conversation — find out what procedure, why now, where they're starting from. Frictionless records-first pitch.
• Predicate: workflow_state.procedure_identified == False
• Allowed addendums: financial_options (if financial_readiness.completion == 0.0 AND patient asked about cost).
• Exit conditions: Intent extractor flips procedure_identified=True → next turn resolves to procedure_identification or records_collection per their predicates.

3.3 procedure_identification¶

• Purpose: Confirm specific procedure, laterality, anatomy, mechanism. Tighten intent before pushing for records.
• Predicate: workflow_state.procedure_identified == True AND layer_state.intent_capture.completion < 1.0
• Allowed addendums: procedure_clinical_facts/{procedure_slug} once case.procedure_code is set.
• Exit conditions: intent_capture.completion == 1.0 → resolves to records_collection (typical) or onward.

3.4 records_collection¶

• Purpose: Get medical records uploaded for clinical context. Re-offer records upload on cadence (parent §4 Rule 2.4).
• Predicate: workflow_state.procedure_identified == True AND workflow_state.documents_uploaded == False AND layer_state.medical_status.completion < 0.7
• Allowed addendums: procedure_clinical_facts/{procedure_slug} (so the agent knows which records matter for this procedure).
• Exit conditions: documents_uploaded=True OR medical_status.completion >= 0.7 → next stage per remaining predicates.

3.5 match_review¶

• Purpose: Patient reviews matched providers, asks questions, picks a subset.
• Predicate: workflow_state.match_results_shown == True AND workflow_state.provider_selected == False
• Allowed addendums: financial_options (cost questions are frequent here); insurance_handling if patient mentioned insurance.
• Exit conditions: provider_selected=True → consent_capture. Backward to procedure_identification if patient pivots (parent §2.6 backward-move table).

3.6 consent_capture¶

• Purpose: Capture HIPAA/GDPR/DPDP consent for record forwarding to selected providers.
• Predicate: workflow_state.provider_selected == True AND workflow_state.consent_given == False
• Allowed addendums: None (consent text is base-prompt verbatim per ADR-0018 mandatory clinical text; addendums would dilute compliance-critical wording).
• Exit conditions: consent_given=True → mso_offer. Patient revoke or decline → re-resolves on next turn.

3.7 mso_offer¶

• Purpose: Offer Medical Second Opinion video consult before booking (Flagsmith mso_patient_offer_enabled gates whether the offer fires at all).
• Predicate: workflow_state.consent_given == True AND workflow_state.mso_offered == False
• Allowed addendums: mso_second_opinion (migrated from conversation_v4.yaml:mso_offer_addendum per parent §3.5.1 item 9).
• Exit conditions: mso_offered=True → scheduling (only if also mso_accepted=True per parent §2.6 transient-state branch 2).

3.8 scheduling¶

• Purpose: Pick MSO video slot / book consultation.
• Predicate: workflow_state.mso_offered == True AND workflow_state.mso_accepted == True AND workflow_state.consultation_scheduled == False
• Allowed addendums: None.
• Exit conditions: consultation_scheduled=True → either stays here through reschedules or, once consultation_completed=True, advances to pre_travel.

3.9 pre_travel¶

• Purpose: Logistics, visas, passport, travel readiness.
• Predicate: workflow_state.consultation_completed == True AND workflow_state.treatment_started == False AND layer_state.logistics.completion < 1.0
• Allowed addendums: post_travel_logistics (gates on patient passport status per parent §2.3).
• Exit conditions: treatment_started=True → in_treatment.

3.10 in_treatment¶

• Purpose: During-stay support. Coordinator handles most of this; the agent is light-touch.
• Predicate: workflow_state.treatment_started == True AND workflow_state.treatment_completed == False
• Allowed addendums: None.
• Exit conditions: treatment_completed=True → recovery_offer.

3.11 recovery_offer¶

• Purpose: Post-op recovery facility offer (ADR-0018 §K).
• Predicate: workflow_state.treatment_completed == True AND workflow_state.recovery_offered == False
• Allowed addendums: None — recovery offer text is ADR-0018 §K mandatory clinical text in base.
• Exit conditions: recovery_offered=True AND recovery_accepted=True → recovery_followup. Decline → terminal (resolver falls through to support with reason recovery_declined_no_next_stage, which is acceptable terminal state).

3.12 recovery_followup¶

• Purpose: Post-op milestone check-ins (ADR-0018 §K).
• Predicate: workflow_state.recovery_accepted == True (milestone presence intentionally NOT required — see parent §2.6 transient-state branch 1)
• Allowed addendums: None.
• Exit conditions: Recovery sub-flow ends. No further stage; case status moves to closed.

4. Truth table¶

Columns:

• case.status — informational, not a predicate input
• proc_id = procedure_identified, docs = documents_uploaded, match = match_results_shown, sel = provider_selected, consent = consent_given, mso_off = mso_offered, mso_acc = mso_accepted, sched = consultation_scheduled, cons_done = consultation_completed, tx_start = treatment_started, tx_done = treatment_completed, rec_off = recovery_offered, rec_acc = recovery_accepted
• IC, MS, LOG = intent_capture.completion, medical_status.completion, logistics.completion
• → stage = resolver output

Rows are grouped by happy-path → branching → edge → fallback. Every row is a fixture seed.

4.1 Happy path (intake → records → consult prep → match → consent → routing → recovery)¶

4.2 Branching — caregiver vs self, fast-track vs full discovery, MSO-declined¶

Per §2.1: case_role is intentionally NOT a predicate input. Caregiver vs self rows produce IDENTICAL resolver output; the difference is in stage guidance (companion-aware language injected from stages.yaml), not stage choice. Listed here so reviewers can verify the identity.

4.3 Edge cases¶

4.4 Caregiver-axis tertiary check¶

These rows exist so the property test can assert resolve_stage is invariant under case_role swaps.

4.5 Fallback / error rows¶

5. Precedence¶

Predicates are evaluated in this exact order. First match wins. support is the catch-all; it does not appear in the ordered list because it has no positive predicate — it returns when nothing else matches OR when a malformed-state condition fires.

1. malformed-state checks (returns support immediately, alerts per F1-F7)
2. recovery_followup        (rec_acc=T)
3. recovery_offer            (tx_done=T AND rec_off=F)
4. in_treatment              (tx_start=T AND tx_done=F)
5. pre_travel                (cons_done=T AND tx_start=F AND LOG<1.0)
6. scheduling                (mso_off=T AND mso_acc=T AND sched=F)
   — note: requires mso_acc=T per parent §2.6 transient-state branch 2
7. mso_offer                 (consent=T AND mso_off=F)
8. consent_capture           (sel=T AND consent=F)
9. match_review              (match=T AND sel=F)
10. procedure_identification (proc_id=T AND IC<1.0)
11. records_collection       (proc_id=T AND docs=F AND MS<0.7)
12. discovery                (proc_id=F)
13. support                  (no rule matched)

Why this order (clinical justification per parent §2.6 rule-order):

• Late-stage states first. Once a patient is in treatment or recovery, no earlier predicate should reclaim them. Evaluating recovery_followup and in_treatment first guarantees this.
• Procedure_identification before records_collection. When proc_id=T AND docs=F AND IC<1.0, both #10 and #11 could match. Clinical rationale (parent §2.6): establish why before pushing for documents. Dr. Naidu re-confirms this ordering in Phase 2a.
• discovery last among positive predicates. It's the broadest predicate (proc_id=F); placing it last ensures more-specific late-stage states are checked first even if proc_id somehow remained False due to a flag-flip race.

Determinism corollary: No two predicates can simultaneously match for the same input with this ordering, because the first-match rule collapses any overlap into a single deterministic outcome. The property test (tests/test_stage_resolver_determinism.py) verifies the implication: for every input in a Hypothesis-generated sample of ~10k cases, resolve_stage(x) == resolve_stage(x) and the matched predicate index is stable across runs.

6. Open questions for Dr. Naidu (Phase 2a clinical review)¶

These shape the predicates but are not decisions this doc makes. Phase 1 implements the spec as written; Phase 2a clinical review may flip any of these, in which case the change happens in one place (this table + the resolver function) with no downstream ripple.

7. CI gates this doc requires¶

8. Relationship to parent spec¶

This doc EXPANDS conversation-v6-feature.md §2.6. Shared definitions:

• Stage list, predicate summary table → parent §2.6
• Tenant-scoping rule → parent §2.6 ("Tenant scoping")
• Telegram alert PHI-safe schema → parent §2.6 ("Telegram alert payload — strict PHI-safe schema")
• Transient-state handling rationale → parent §2.6 ("Transient-state handling")
• Backward stage moves → parent §2.6 ("Backward stage moves")
• Flag dependency matrix governing whether v6 runs at all → parent §3.5.1 item 4

This doc adds: full enumerated truth table, function signature, per-stage exit conditions, allowed-addendum-per-stage map, fallback-row alert wiring, and the open-question list for Phase 2a.