Reconciliation Clinical Review Matrix
Last updated: 2026-06-23
Status: clinical/quality review aid; not formal freeze evidence until tied to an implementation SHA, verification run, and RTM evidence promotion.
Purpose
This document translates the fallback basal and issued-dose reconciliation logic into a clinician-readable matrix. It is intended to answer:
- What happened?
- What evidence does the app have?
- What does the app do next?
- What does the user see or need to do?
- What safety control prevents over-delivery, under-accounting, or a stranded user interface?
The matching engineering decision matrix is executable in
BionicLoopCore/Tests/BionicLoopCoreTests/ReconciliationCaseClassifierDecisionMatrixTests.swift.
Plain-Language Terms
| Term | Meaning |
|---|---|
| Issued dose | The app sent, or started sending, an insulin-adding pump command. This can be meal, correction, basal, or mixed automatic insulin. |
| Requested dose | The insulin amount the app asked the pump to deliver. |
| Delivered dose | The insulin amount the pump reports, or the amount the app assumes under a documented safety policy when the old pod cannot be interrogated. |
| Attribution step | The algorithm step where the delivered insulin is entered into primary and secondary algorithm inputs. |
| Replay / backfill | Running missed historical algorithm steps so the algorithms receive the delivered-insulin history. Replay never sends catch-up pump commands. |
| Fallback basal | The programmed pod basal schedule intended to continue basal insulin if the app cannot communicate. |
| 0.00 U/hr mask | A temporary basal command used while the app is connected so the fallback basal schedule does not add insulin on top of app-driven dosing. |
| Confirmed evidence | Same-pod pump evidence, such as pump last-delivery status or a credible same-pod pump-total delta. |
| Corrected evidence | Same-pod pump-total evidence that is credible but differs from modeled fallback exposure; the pump-reported amount is used. |
| Assumed evidence | A clinically approved assumption that insulin was delivered when the old pod cannot provide direct proof. This is never labeled as pump-confirmed. |
| No replay | The app does not backfill fallback insulin because the evidence is missing, stale, not credible, or belongs to a different pod. |
Non-Negotiable Safety Rules
| Rule | Safety purpose |
|---|---|
| Algorithm start, stop, and session reset are explicit user actions only. | Prevent hidden therapy session changes during recovery. |
| Replay never issues pump commands. | Prevent catch-up insulin delivery. Replay only informs the algorithms what was delivered or assumed delivered. |
| Primary and secondary algorithms receive the same reconciled delivered-insulin input. | Keep therapy and safety algorithm views aligned. |
| Same-pod evidence is required to confirm actual pump delivery. | Prevent a replacement pod or unrelated status from proving old-pod insulin delivery. |
| Assumed-delivered evidence is explicitly labeled as assumed, not confirmed. | Preserve clinical traceability and avoid misleading review or user messaging. |
| Replacement-pod delivery evidence is scrubbed for old-pod reconciliation. | Prevent a new pod bolus from being credited to an old pod event. |
| Pending issued-dose state is persisted when the pump command starts. | Survive force-quit/relaunch or communication loss during bolus delivery. |
| If the original pod is still delivering, live advancement waits. | Avoid overlapping or misattributing an active delivery. |
| If the old pod is gone, retired, expired, or replaced, the app must not strand the user. | Allow pod replacement and continued therapy while preserving assumed-delivered evidence. |
| Fallback replay is bounded to planned missed fallback-active rows before the current live step. | Prevent replaying future rows or rows before fallback delivery was active. |
| Fallback delivered units are allocated by the fallback schedule weights for the outage window. | Avoid even-smoothing when the programmed basal rate differed across time windows. |
| Issued-dose insulin is partitioned before fallback residual insulin. | Prevent meal/correction insulin from being counted again as fallback basal. |
| Telemetry and Recent Dose Steps must show request step, delivered amount, evidence source, disposition, and replay status. | Make local and cloud evidence auditable. |
Evidence Labels Clinicians Will See
| Label | Meaning | Clinical interpretation |
|---|---|---|
| Confirmed | Pump evidence from the same pod supports the delivered amount. | Most reliable. |
| Corrected | Same-pod pump total is credible, but differs from modeled fallback delivery; pump-reported residual is used. | Reliable enough to use, with explicit difference recorded. |
| Assumed by policy | Direct proof is unavailable, but clinical policy says to assume delivery for safety accounting. | Conservative insulin accounting; not pump-confirmed. |
| Ambiguous | The app cannot safely decide yet, usually because pump status is unknown, stale, or delivery is still active. | Temporary wait/skip state. |
| No replay | The app will not backfill fallback rows from the available evidence. | Must be obvious in UI/telemetry; no hidden catch-up. |
Human-Readable Behavior Matrix
A. No Pending Recovery Or Future Attribution
| ID | Situation | Evidence available | App behavior | User impact | Safety control |
|---|---|---|---|---|---|
| A-01 | No pending issued dose and no fallback recovery. | Current pump/CGM inputs. | Run the next live algorithm step normally. | No special UI. | Normal dosing gates still apply. |
| A-02 | An issued dose exists, but the current step is before the first step where it should be attributed. | Pending issued-dose record only. | Do not replay the issued dose and do not run a standalone live step before attribution is eligible; independently safe fallback replay may still proceed. | Meal/progress UI may remain active if delivery is still in progress; meal availability is governed by separate UI gates. | Prevents early insulin accounting or live advancement before delivered insulin can be represented. |
B. Issued Dose, Meal Dose, Correction Dose, Or Canceled Partial Dose
| ID | Situation | Evidence available | App behavior | User impact | Safety control |
|---|---|---|---|---|---|
| B-01 | Original pod reports the issued dose is still delivering. | Same pod, delivery state active. | Skip live advancement; keep pending attribution. | User sees delivery/reconnect progress rather than a new completed state. | Avoids overlapping or misattributing an active delivery. |
| B-02 | Pump status is unknown. | No trustworthy current pump state. | Skip live advancement for that reconciliation path. | App waits for a safer status refresh or user escape path. | No guessed delivery from unknown status. |
| B-03 | Pump status is stale compared with the dose request. | Old status timestamp. | Skip live advancement for that reconciliation path. | App waits for fresh status or old-pod-unavailable policy. | No decisions from stale evidence. |
| B-04 | Same pod confirms full delivered dose at the first attribution step. | Pump last-delivery or stored same-pod evidence. | Enter delivered insulin into the live step. | Meal progress can close as confirmed. | Algorithms receive delivered insulin without replay. |
| B-05 | Same pod confirms full delivered dose after one or more attribution steps were missed. | Pump last-delivery or stored same-pod evidence. | Replay missed attribution rows before the next live step. | Recent Dose Steps shows replay/backfill rows. | Replay rows do not dose the pump. |
| B-06 | Meal/correction was canceled or partially delivered. | Same-pod evidence with delivered amount less than requested. | Use the actual partial delivered amount, not the requested amount. | Chart/recent rows should show the partial delivered amount. | Prevents cancelled insulin from being counted as full-dose delivery. |
| B-07 | Same-pod evidence has the wrong request step, wrong amount, or impossible delivered amount. | Evidence exists but does not match the pending request. | Do not treat it as confirmed. If same-pod idle/suspended assumption policy applies, label as assumed by policy. | UI/telemetry must not call this confirmed. | Prevents bad evidence from becoming pump-confirmed proof. |
| B-08 | Original pod identity differs from current pod identity. | New/different pod observed. | Assume the old issued dose was delivered; scrub replacement-pod last-delivery for this attribution. | App continues in same algorithm session. | Prevents blocking therapy on a pod the user cannot interrogate, while avoiding new-pod evidence contamination. |
| B-09 | Old pod is no longer active, retired, expired, service-stopped, or user has chosen replacement escape. | Old pod unavailable. | Assume the issued dose was delivered; clear only meal progress UI; keep algorithm attribution until consumed live or replayed. | User can proceed with pod replacement and future therapy. | Prevents stranded UI and unresolvable dose holds. |
| B-10 | Persisted assumed-delivered evidence exists after relaunch. | Stored assumed evidence plus stored failure reason. | Preserve the original reason, such as different/new pod or old pod unavailable. | UI/telemetry remains consistent after force-quit/relaunch. | Prevents relaunch from turning a known assumption into a generic/ambiguous event. |
| B-11 | A second meal announcement is attempted after a canceled or partial meal dose. | Pending or consumed attribution state. | The previous delivered insulin must be available as input to the next eligible algorithm execution, including a meal-triggered execution. | The app should not show a stale unresolved block if prior evidence was consumed or assumed. | Prevents hidden insulin from being lost when user immediately announces another meal. |
C. Fallback Basal Recovery
| ID | Situation | Evidence available | App behavior | User impact | Safety control |
|---|---|---|---|---|---|
| C-01 | Fallback was armed, but the app reconnects before the 0.00 U/hr mask expires. | Same pod, mask still active. | Restore original schedule; no fallback basal replay is needed. | Recent Dose Steps may show fallback armed/restored with no replay. | Prevents adding fallback insulin that was masked. |
| C-02 | 0.00 U/hr mask expired while disconnected, and same pod has credible pump-total delta. | Same-pod pump total. | Replay bounded fallback-active rows before the current live step. | Recent Dose Steps and telemetry show backfilled fallback rows. | Algorithms receive basal that likely occurred while disconnected. |
| C-03 | Same-pod pump total differs from modeled fallback exposure but remains credible. | Same-pod pump total and modeled fallback schedule. | Use the pump-reported corrected residual amount. | Evidence label is corrected, not simply modeled. | Avoids over-crediting modeled fallback if pump says less was delivered. |
| C-04 | Fallback replay plan has explicit zero-delivery rows. | Bounded replay rows with zero delivered units. | Replay the rows with zero delivered units. | Reviewer can see the missed windows even when dose is 0. | Prevents silent holes in the algorithm history. |
| C-05 | Positive fallback exposure exists, but schedule weights are missing or unusable. | No safe allocation basis. | Do not guess row allocation; clear/suppress replay with no-replay reason. | UI/telemetry should make no-replay obvious. | Prevents fabricated basal distribution. |
| C-06 | Fallback plan is stale, invalid, or no longer matches current due step. | Persisted plan cannot safely map to current step. | Clear or suppress fallback replay. Valid issued-dose evidence must still be preserved separately. | User should not see incorrect backfill rows. | Prevents replay against the wrong step window. |
| C-07 | Fallback recovery sees different/new pod, unknown pod identity, or history discontinuity. | Old-pod continuity not proven. | Suppress pump-counter fallback replay from the new/unknown pod. | Therapy can continue without pretending the new pod proves old-pod basal. | Replacement pod evidence cannot prove old-pod delivery. |
| C-08 | Old pod is unavailable/retired/expired/service-stopped during fallback recovery. | Old pod cannot provide direct evidence. | Use modeled assumed fallback only if that clinical policy is accepted for the case; label as assumed by policy. | User can replace pod; evidence is not marked confirmed. | Avoids unresolvable holds while preserving assumption traceability. |
| C-09 | A fallback replay plan exists, but its latest status is missing, pending, failed, canceled, or resumed without reconciliation. | Replay plan without replayable reconciliation status. | Clear the plan as no-replay instead of treating it as confirmed. | User/reviewer should not see pump-confirmed fallback rows. | Prevents ambiguous or incomplete recovery metadata from authorizing replay. |
D. Issued Dose And Fallback Basal Overlap
| ID | Situation | Evidence available | App behavior | User impact | Safety control |
|---|---|---|---|---|---|
| D-01 | Issued meal/correction dose and fallback basal are both inside the same pump-total delta. | Same-pod pump total plus pending issued dose. | Partition issued-dose insulin first, then allocate only residual fallback basal. | Telemetry should show both pieces separately. | Prevents meal/correction insulin from being counted again as basal. |
| D-02 | Issued-dose resolution reaches into the fallback replay window. | Resolved issued-dose evidence plus fallback replay plan. | Merge the issued-dose delivery into the first appropriate fallback replay row. | One replay sequence explains both events. | Prevents unnecessary pre-fallback replay rows and preserves delivered insulin. |
| D-03 | Issued-dose evidence is valid, but fallback replay metadata is stale or suppressed. | Valid issued-dose evidence plus invalid fallback metadata. | Preserve the issued-dose replay/live attribution; do not let fallback cleanup hide it. | User/reviewer still sees the insulin that was delivered or assumed. | Prevents stale fallback state from dropping issued-dose accounting. |
| D-04 | Original pod still reports active delivery while fallback replay is pending. | Same pod delivering. | Delivery-in-progress skip takes precedence; do not run fallback replay or live step yet. | App waits for a safer pump state. | Prevents replay/live advancement while insulin delivery is unresolved. |
| D-05 | Issued dose is not yet at its attribution step, but fallback replay is due. | Pending future attribution plus executable fallback plan. | If same-pod delivery is still active, wait. If issued-dose evidence is already resolved, merge it into the first fallback replay row. Otherwise execute bounded fallback replay alone and leave the issued dose pending until due. | Backfill can proceed without early meal/correction accounting, but resolved delivered insulin is not dropped. | Keeps independent recovery paths ordered by their own due windows and avoids standalone live advancement before pending insulin can be represented. |
| D-06 | Issued-dose and fallback replay are both due, but the issued-dose evidence is only a direct same-pod idle or old-pod-unavailable assumption. | No stored evidence the fallback path can merge, and not a different/new-pod assumption path. | Replay fallback only; leave issued-dose handling to its own path. | Avoids a combined row that runtime cannot actually reproduce. | Keeps the review matrix aligned with implemented runtime merge capability. |
E. Pod Replacement, Expired Pod, Force-Quit, And UI Escape
| ID | Situation | Evidence available | App behavior | User impact | Safety control |
|---|---|---|---|---|---|
| E-01 | App force-quits or is killed during a meal/correction/automatic bolus. | Pending issued-dose state persisted at command start. | Relaunch restores pending attribution and reconciles on status refresh or next safe work cycle. | Meal progress should recover instead of disappearing permanently. | Protects against losing knowledge of an in-flight bolus. |
| E-02 | User disconnects during meal delivery and reconnects to same pod. | Same-pod status or last-delivery evidence. | Close/resolve progress UI when evidence is available, even before the next scheduled algorithm step; later consume into live/replay input. | Modal should not remain stuck only because the next CGM step has not run. | Separates UI progress closure from algorithm attribution while keeping evidence. |
| E-03 | User cannot reconnect to old pod and needs to replace it. | Old pod unavailable or user replacement escape. | Allow replacement path; assume pending issued dose delivered by policy; do not auto-stop algorithm session. | User can move on to new pod setup. | Prevents unresolvable therapy block. |
| E-04 | New pod is active while old issued dose remains unreconciled. | Different/new pod identity. | Do not block future dosing solely because old pod evidence is unavailable; assume old dose delivered by policy. | User should not be trapped by prior pod evidence loss. | Matches clinical guidance to avoid delivery holds that the user cannot clear. |
| E-05 | Meal progress UI would otherwise be stranded. | Timeout/escape eligibility plus unresolved old-pod state. | Provide explicit escape/replacement path; preserve reconciliation evidence. | User can unblock UI without clearing algorithm history incorrectly. | UI dismissal never erases insulin accounting state by itself. |
F. Telemetry, Recent Dose Steps, And Review Evidence
| ID | Situation | Required evidence fields | App behavior | Reviewer impact | Safety control |
|---|---|---|---|---|---|
| F-01 | Any issued-dose reconciliation. | Requested step, attributed step, requested units, delivered units, source, disposition, failure reason if applicable. | Local and cloud evidence should agree. | Clinicians can tell confirmed vs assumed vs partial. | Prevents ambiguous dose history. |
| F-02 | Any fallback replay. | Fallback status, planned row range, executed row range, delivered units per row, schedule weighting, source/disposition. | Replay rows appear locally and in telemetry when cloud path is available. | Scout/cloud review should match Recent Dose Steps. | Prevents local-only evidence from being mistaken for complete cloud evidence. |
| F-03 | No replay / suppressed replay. | Reason code: different/new pod, unknown identity, history discontinuity, stale plan, invalid plan, no schedule weights, no credible evidence. | UI/telemetry explicitly records no-replay reason. | Reviewer can distinguish "no insulin" from "insulin not backfilled." | Prevents silent evidence gaps. |
| F-04 | Assumed-delivered policy used. | Assumption source, old/new pod identifiers if available, user action if applicable, timestamp. | Evidence label remains assumed by policy. | Clinical review can identify where direct proof was unavailable. | Prevents assumed events from being promoted as confirmed. |
Risk Controls By Hazard
| Hazard | Control in this process |
|---|---|
| Over-delivery from catch-up insulin | Replay never sends pump commands. |
| Over-accounting insulin | Confirmed evidence must match request step, units, pod identity, and time; partition issued-dose insulin before fallback residual. |
| Under-accounting insulin | Confirmed or clinically assumed delivered insulin is replayed or fed into the next eligible live step. |
| Wrong pod used as evidence | Pod identity gates same-pod confirmation; replacement pod evidence is scrubbed for old-pod events. |
| User stranded by old pod that cannot be interrogated | Assumed-delivered policy and replacement escape allow continued therapy without automatic session reset. |
| Hidden session reset or restart | Algorithm start/stop/reset remains explicit user action only. |
| Misleading UI or telemetry | Evidence labels distinguish confirmed, corrected, assumed, ambiguous, and no-replay. |
| Lost in-flight bolus after force-quit | Pending attribution is persisted at command start. |
| Fallback rows applied to wrong time window | Replay is bounded to persisted fallback-active rows before current due step and weighted by schedule. |
| Meal/correction double-counted as fallback basal | Pump-total reconciliation subtracts/partitions issued-dose insulin before fallback residual replay. |
Clinical Review Questions Still Worth Explicit Sign-Off
| Topic | Question |
|---|---|
| Same-pod idle/suspended unresolved issued dose | Should the app assume delivered for all automatic boluses when the same pod is idle/suspended but direct dose evidence is unavailable, or only after old-pod evidence becomes unrecoverable? |
| Assumed meal learning | Should assumed-delivered meal announcements be excluded from meal learning unless delivery is pump-confirmed? |
| Old-pod unavailable fallback | Is modeled assumed fallback acceptable for all durations/rates when an expired/retired/no-active old pod cannot provide pump-total evidence, or should larger exposures require acknowledgment/escalation? |
| UI wording | What exact wording should distinguish pump-confirmed, corrected, assumed by policy, unresolved, and no-replay states? |
| Cloud evidence threshold | Which hardware traces must be visible in Scout/cloud before calling this IDE-baseline ready? |
Review Checklist
Before baseline freeze, confirm:
- Each matrix row has either direct test coverage or a documented verification path.
- Each assumed-delivered path is accepted by clinical/quality stakeholders.
- Recent Dose Steps and cloud telemetry use the same evidence source and disposition labels.
- Replacement-pod and expired-pod recovery cannot strand meal progress UI.
- Replay rows never issue pump commands.
- Replay row times, request steps, delivered units, and fallback schedule weighting are visible in evidence.
- Remaining open clinical questions are either resolved or explicitly deferred.