Skip to content

Software Requirements Specification (SRS)

Status: Final draft prepared for handoff (pending review)
Version: 1.11 Owner: BionicLoop engineering
Prepared by: BionicLoop engineering Reviewer: ____
Approver: ____
Decision date: ____
Effective date: ____
Baseline freeze SHA: ____
Scope: Closed-loop investigational runtime, device integration, and safety-critical UI behavior Last updated: 2026-06-18

Revision History

Version Date Author Summary of Changes
0.1 2026-03-25 Engineering Initial controlled draft baseline
0.9 2026-04-06 BionicLoop engineering Added handoff-ready document-control metadata and software-handoff disposition language
0.91 2026-04-08 BionicLoop engineering Added masked offline-fallback maintenance, disarm, and fallback-review-event requirements for the active feasibility branch
0.92 2026-04-08 BionicLoop engineering Clarified 20-minute masked-fallback renewal window, deferred maintenance semantics, and recoverable restore context for the active feasibility branch
0.93 2026-04-14 BionicLoop engineering Added reconciliation-required blocked-state requirements after offline mask expiry for the active masked-fallback feasibility branch
0.94 2026-04-14 BionicLoop engineering Added reconnect recovery requirements for connected restore/disarm retry and explicit fresh re-arm after successful recovery
0.95 2026-04-14 BionicLoop engineering Updated reconnect recovery behavior to auto-arm a fresh session after successful masked-fallback recovery while preserving the fallback review trail
0.96 2026-04-14 BionicLoop engineering Updated masked-fallback feasibility recovery to preserve the existing session/cadence anchor and resume on the current due step without replay when reconnect restore succeeds
0.97 2026-04-14 BionicLoop engineering Clarified state-persistence wording for same-session unreconciled resume after successful masked-fallback reconnect recovery
0.98 2026-04-15 BionicLoop engineering Added pod total-delivery baseline, modeled-vs-pump-reported fallback review, and pre-step missing-fallback arm clarifications for the active feasibility branch
0.99 2026-04-15 BionicLoop engineering Added confirmed/corrected basal-only reconnect replay requirements and clarified ambiguous unreconciled-resume fallback behavior
1.00 2026-04-15 BionicLoop engineering Added dedicated cloud fallback telemetry contract requirements for BionicScout rendering of fallback lifecycle and delivery/replay summary detail
1.01 2026-04-15 BionicLoop engineering Clarified that confirmed/corrected reconnect replay must persist replayed internal steps into local export telemetry as distinct replay-marked rows
1.02 2026-04-27 BionicLoop engineering Clarified that fallback replay must use pump-reported delivered-insulin delta and must not substitute modeled expected delivery when pump reconciliation is unavailable
1.03 2026-05-06 BionicLoop engineering Added safety-track q5 nominal-basal profile persistence, four six-hour fallback-schedule generation, schedule-aware modeled exposure, and fallback profile/schedule cloud telemetry requirements
1.04 2026-06-02 BionicLoop engineering Reframed confirmed/corrected fallback recovery as pump-delta delivery reconciliation into the live resumed step, tightened pump-evidence credibility, aligned six-hour schedule-refresh cadence, and added repeated no-active-pod critical alerting
1.05 2026-06-04 BionicLoop engineering Aligned masked-fallback requirements with the current candidate baseline: confirmed/corrected recovery replays bounded missed primary/secondary algorithm steps with CGM=-1, per-step pump-delivery input, and no catch-up pump commands before the resumed live step
1.06 2026-06-08 BionicLoop engineering Added schedule-weighted allocation of credible same-pod pump-delta replay across missed fallback steps and clarified zero-weight suppression / zero-delta replay behavior
1.07 2026-06-12 BionicLoop engineering Added generalized issued-bolus attribution and no-guess replay/disposition requirements for meal, correction, and basal bolus commands interrupted by pump communication loss
1.08 2026-06-13 BionicLoop engineering Hardened issued-dose reconciliation requirements for non-credible delivered-unit evidence, replacement-pod live-step insulin input, and automatic resume blocking during unresolved holds
1.09 2026-06-15 BionicLoop engineering Updated different/new-pod issued-dose requirement to assumed-delivered replay/live attribution, replacement-pod command allowance, legacy hold nonblocking behavior, and deferred adaptation-forget consideration
1.10 2026-06-17 BionicLoop engineering Added one-step algorithm/runtime cadence reconciliation before meal-step selection so loop executedStep, pump request step, and algorithm stepTime remain aligned when the algorithm bridge has already consumed the due step.
1.11 2026-06-18 BionicLoop engineering Added retired/expired/no-active-pod fallback recovery disposition: modeled fallback exposure may be recorded as assumed delivered and replayed when the original pod can no longer provide connected reconciliation evidence.
1.11 2026-06-17 BionicLoop engineering Added explicit user-confirmed pod-replacement escape for unconfirmed meal delivery progress so the app can record assumed-delivered evidence and open pod setup without leaving the UI trapped.

Requirement Format

Each requirement uses a stable ID and a testable shall statement.

Runtime and Cadence

  • SRS-RUN-001: The runtime shall maintain 5-minute algorithm cadence anchored to first successful step execution time.
  • SRS-RUN-002: The runtime shall compute expected step index from anchored schedule and skip duplicate step execution for the same index. Before resolving ordinary cadence or meal-announce step selection, runtime shall reconcile persisted cadence state with the algorithm-reported next step; if the algorithm has already consumed the current due step while the persisted runtime state lags, runtime shall advance persisted lastExecutedStep to the algorithm-implied last executed step without re-anchoring the schedule, so live executedStep, pump request-step attribution, and algorithm input stepTime remain aligned.
  • SRS-RUN-003: The runtime shall execute loop work only on configured wake causes (current policy: cgmUpdate, bgCheck, mealAnnounce, and guarded pumpReconnect fallback paths).
  • SRS-RUN-004: After the first successful anchored step exists, the runtime shall permit a guarded pump-reconnect fallback wake to execute the current due step when no accepted CGM receipt newer than the approved CGM freshness limit exists and normal execution safety gates pass.
  • SRS-RUN-005: Ordinary guarded pump-reconnect fallback for CGM absence shall not execute step 0, shall not re-anchor cadence, and shall not replay multiple missed slots; each ordinary reconnect-triggered execution may service at most the current due step. This row does not describe masked offline-fallback recovery after a persisted reconciliation-required state.
  • SRS-RUN-006: Masked offline-fallback shall not arm a new fallback schedule or refresh the programmed fallback schedule unless the loop is armed, a current algorithm session identifier exists, and a valid fallback candidate is available from either the current just-computed algorithm step or a prior successful step. When a current step first produces a valid fallback candidate and no fallback is armed, runtime shall attempt the first fallback arm after primary/secondary algorithm calculation and before applying that same step's pump command, so step 0 and other first-candidate steps cannot let a bolus outrun fallback arming. Pre-execution masked-fallback arm, mask-renewal, and schedule-refresh maintenance shall require freshly refreshed idle pump status; unavailable, unknown, delivering, or refresh-failure status shall defer that maintenance and record the defer reason without mutating pump state. An already-masked fallback may renew its existing 0.0 U/hr mask before the next step executes once the runtime is inside the approved renewal window, but only while the current mask remains active and pump maintenance safety gates pass. If runtime later detects offline mask expiry (maskExpiredOffline) or any remask failure leaves the fallback schedule potentially exposed after possible schedule mutation or mask replacement, it shall persist a masked-fallback reconciliation-required recovery state, suppress ordinary loop doWork execution, and keep closed-loop stepping blocked until reconnect recovery either resolves by connected restore/disarm or is otherwise explicitly cleared; it shall not silently auto-resume authoritative closed loop in the same session immediately after detecting that exposure state. For the current feasibility branch, if reconnect restore succeeds while the loop remained armed and basal-only reconnect evidence is confirmed or corrected, runtime shall preserve the existing session/cadence anchor, bound replay to missed steps before the resumed current due step whose delivery interval overlaps confirmed fallback-active time, and replay those primary and secondary/safety algorithm steps with unavailable CGM input (CGM=-1) and per-step pump-delivery input allocated from credible pump-reported delivered insulin using the persisted programmed fallback schedule as the per-step weighting model. Disconnected missed steps before offline fallback activation shall remain missing and shall not be replayed as synthetic 0 U rows. The replayed steps shall not issue pump commands. The resumed live step shall then execute with actual refreshed CGM/pump status and shall not receive a duplicate aggregate recovered-delivery input. If reconnect evidence is ambiguous, runtime may resume the existing session on the current due 5-minute step without fallback delivery reconciliation, but that path shall be marked as an unreconciled resume rather than authoritative reconciliation. If connected restore/disarm cannot complete because the previous pod is known inactive/no-active, retired, or past hard service-stop while masked-fallback recovery remains pending, runtime may clear the recovery state without creating a new algorithm session by recording modeled fallback exposure as assumed_delivered_per_clinical_policy, queueing the same bounded no-command replay plan, and labeling the recovery as assumed rather than pump-confirmed.

Team review notes: - SRS-RUN-003 reflects the currently implemented wake-cause policy. - Guarded reconnect fallback is implemented as a secondary wake path from pump-status recovery, not raw BLE connect. - Current reconnect-fallback gate is accepted CGM receipt age > 5 minutes, matching the present CGM freshness limit for algorithm-use eligibility.

CGM Input Handling

  • SRS-CGM-001: The runtime shall map CGM values outside 39...401 mg/dL to unavailable input (-1) before algorithm invocation.
  • SRS-CGM-002: Step 0 shall require a fresh in-range CGM input.
  • SRS-CGM-003: Step >0 shall be allowed to run with unavailable CGM input (-1) when fresh in-range CGM is not available.
  • SRS-CGM-004: The UI shall show loop reason/state when step execution is blocked for missing fresh CGM at step 0.
  • SRS-CGM-005: When the loop is armed and no successful algorithm step has completed for longer than the approved interruption threshold, the app shall detect that loop stepping is stalled and expose that condition to alert/status logic.

Team review notes: - SRS-CGM-005 is implemented with a 15-minute threshold based on the most recent successful step time; before the first successful step exists, the threshold is measured from session start / first-step wait state. - The interruption condition is recomputed on foreground from persisted runtime/session state and is distinct from the protocol Dexcom Bluetooth interruption alert (> 2 hours).

Fingerstick BG Input Handling

  • SRS-BG-001: The app shall provide a manual BG entry flow with explicit Submit and Cancel actions, enforce accepted input range 20...600 mg/dL, capture a submission timestamp at user confirmation time, and show user-facing guidance that manual BG is used for algorithm dosing decisions and does not calibrate CGM.
  • SRS-BG-002: Manual BG submit shall trigger a dedicated runtime wake cause (bgCheck) with no future-slot borrowing and shall create/update a single pending BG candidate for the next eligible algorithm step.
  • SRS-BG-003: If submit occurs after the current due step has already executed, the pending BG candidate shall roll forward to the immediate next step (not discarded immediately).
  • SRS-BG-004: During bgCheck, manual BG shall map to algorithm BG input (BGval) while CGM input mapping policy remains independent (CGM may be unavailable -1).
  • SRS-BG-005: BG submission shall not override pump command-application safety gates; when pump status is unavailable/unknown, runtime may execute algorithm step but shall block command application.
  • SRS-BG-006: Runtime shall reject stale manual BG submissions using a defined freshness window and provide an explicit user-visible reason.
  • SRS-BG-007: Telemetry shall record BG source (manualBG), submitted value, submit timestamp, and execution result for each bgCheck attempt.
  • SRS-BG-008: Step-0 BG rescue is deferred from the current software handoff baseline. If a future approved baseline enables step 0 BG rescue, it shall permit execution only when fresh in-range CGM is unavailable and a valid fresh manual BG is present.
  • SRS-BG-009: Pending BG candidate shall be valid for one step only and must be discarded if not consumed on that immediate next step.
  • SRS-BG-010: If a new manual BG is submitted while a pending BG candidate exists and has not yet been consumed, the newer submission shall replace the older candidate.
  • SRS-BG-011: Manual BG submit shall not execute bgCheck when loop runtime is disarmed (Algorithm Off state) or when masked-fallback reconciliation is pending.
  • SRS-BG-012: Until step-0 BG rescue is explicitly approved, manual BG submit shall be rejected before the first successful anchored step exists (firstSuccessfulStepAt == nil).

Team review notes: - SRS-BG-008 is deferred from the current software handoff baseline; current accepted behavior remains CGM-only at step 0 via SRS-BG-012. - Manual BG accepted range is currently set to 20...600 mg/dL. - Manual BG freshness duration remains a required configuration value that must be explicitly approved and versioned. - SRS-BG-011 is implemented in app runtime to prevent loop-off execution from manual BG UI. - SRS-BG-012 is currently enforced in runtime; step-0 BG rescue remains disabled by default.

Pump Handling

  • SRS-PUMP-001: On pump-status refresh failure or unknown state, runtime shall continue algorithm execution with unavailable pump input fields and block command application.
  • SRS-PUMP-002: In closed-loop mode, manual bolus command paths shall not be exposed.
  • SRS-PUMP-003: Dosing command handling shall respect DASH delivery constraints (including minimum practical delivery quantum).
  • SRS-PUMP-004: Home pod status tile shall update to reflect actual connect/disconnect state transitions without requiring user entry into pump settings.
  • SRS-PUMP-005: While pump delivery is in progress, Home and meal-availability pump state shall auto-refresh without requiring navigation into pump settings.
  • SRS-PUMP-006: For the masked offline-fallback feasibility path, the app shall maintain a connected 0.0 U/hr / 30 minute temp-basal mask over the programmed fallback basal schedule while communications remain healthy. The programmed fallback schedule shall be derived from the secondary/safety algorithm track's persisted q5 nominal-basal profile when available by averaging four local-time six-hour blocks (00:00-06:00, 06:00-12:00, 12:00-18:00, 18:00-24:00) and rounding each block to a supported DASH basal rate; if no profile can be generated yet, runtime may fall back to the latest rounded scalar safety-track nominal-basal candidate. Existing masked fallback shall enter renewal once the active mask reaches its final 20 minutes; pre-execution renewal and schedule refresh shall first verify fresh idle pump status, and if renewal is temporarily blocked but the current mask remains active, runtime shall defer maintenance and record the defer reason rather than treating the attempt as an immediate hard failure. Programmed fallback schedule refresh shall use the IDE baseline cadence of no more often than every 6 hours unless explicitly overridden for controlled hardware validation. If successful step execution stalls or deferred maintenance continues long enough for the active mask to expire, the pod may autonomously resume the programmed fallback schedule and runtime shall record that transition for later reconciliation rather than continuing ordinary authoritative loop stepping.
  • SRS-PUMP-007: Masked fallback schedule arm, refresh, and disarm shall be treated as disruptive programmed-basal replacements and shall be blocked unless pump delivery state is known and safe for maintenance (no active bolus, no unknown basal-delivery state, and no nonzero temp basal).
  • SRS-PUMP-008: If an active algorithm session has no currently armed masked fallback and a valid rounded nominal fallback candidate is available from the current or most recent successful step, runtime shall program the fallback schedule before any later same-step pump command when the candidate was just computed, or in the next safe pre-execution maintenance pass with fresh idle pump status when the candidate was already persisted, and shall apply the connected 0.0 U/hr mask in the same maintenance sequence. The pre-pump-command first-arm attempt shall run only with refreshed pump status that is not unavailable and not unknown; otherwise runtime shall leave first-arm maintenance for a later safe wake and allow the current step's normal pump command path to classify the unavailable or unknown pump state under its own safety rules. The programmed schedule shall prefer the secondary/safety q5 nominal-basal profile-derived four-block schedule over the scalar candidate once at least one valid q5 profile observation exists. If that first arm attempt is cleanly blocked before any schedule mutation, runtime shall leave fallback explicitly unarmed and record the blocked arm as a failure requiring retry, not as ordinary deferred masked maintenance, while the current step's normal pump command may still be attempted under its own safety gates; runtime shall not immediately retry that first arm again in the same cycle after emitting a pre-command fallback event. If schedule programming may have succeeded but the immediate 0.0 U/hr mask fails, is blocked, or is uncertain, runtime shall persist reconciliation-required masked-fallback recovery context and block the current step's normal pump command.
  • SRS-PUMP-009: Session reset/disarm after masked fallback has been armed shall attempt to restore the original programmed basal schedule and shall record restore success or failure for operator review. If restore fails, the app shall preserve recoverable restore context and block the next algorithm start until masked-fallback recovery is resolved. When masked-fallback recovery remains pending across reconnect, app start, or foreground, the app may retry connected restore/disarm of the original programmed schedule; if that retry succeeds after offline mask expiry or any remask failure that may have left the fallback schedule exposed while the loop remained armed and basal-only reconnect evidence is confirmed or corrected, it shall preserve the existing session/cadence anchor, clear the blocked recovery state, queue pump-delta fallback delivery reconciliation, and then permit same-session recovery. Reconciliation shall use pump-reported delivered-insulin delta only when same physical pod continuity is proven and the connected delivery-counter baseline credibly spans the exposure window; modeled fallback exposure is retained for operator review/logging only and shall not fill delivery accounting when pump-reported delivery evidence is unavailable, not credible, from a different/new pod, or from unknown pod identity. Historical CGM is not required to authorize fallback delivery reconciliation; instead, confirmed/corrected recovery shall replay only the bounded missed primary and secondary/safety algorithm steps whose delivery interval overlaps the confirmed fallback-active interval, with CGM=-1, per-step pump-delivery input allocated from the credible same-pod pump-reported delta in proportion to the persisted programmed fallback schedule rate active during each replayed step, explicit 0 U input for fallback-active replayed steps with no pump allocation, and no catch-up pump commands before resuming the current due step. Pre-activation disconnected missed steps shall not be replayed. The pump-reported delta shall remain the authoritative total; schedule-derived exposure shall be used only as the deterministic weighting model, including actual overlap duration when replay slots cross fallback-schedule boundaries or midnight. If the persisted schedule is unavailable or the schedule weights sum to zero while the pump-reported delta is positive, replay shall be suppressed rather than guessed; if the authoritative pump-reported delta is 0 U, replay may still backfill the fallback-active missed step range with explicit 0 U inputs. If reconnect evidence is ambiguous, from a different/new pod, from unknown pod identity, or has a delivery-counter/history discontinuity, the app may instead permit same-session resume on the current due 5-minute slot without fallback delivery reconciliation, but it shall record that outcome as an unreconciled resume for operator review. Successful reconnect recovery shall also retain modeled fallback exposure and, when compatible same-pod pump-evidence baseline data are available, the pump-reported delivered-insulin delta for operator review. If the operator explicitly reset or turned the loop off before recovery completes, the successful restore shall keep the loop off. Exception: when the original pod is known inactive/no-active, retired, or past hard service-stop and connected pump-reported evidence is therefore unavailable, the app may use the persisted fallback schedule to record modeled fallback exposure as assumed delivered per clinical policy, replay the bounded fallback-active missed steps without pump commands, retain the assumed-vs-confirmed distinction in UI/telemetry, and preserve the existing algorithm session.
  • SRS-PUMP-010: For any automatic algorithm-issued bolus command (including meal, correction, mixed, or basal micro-dose commands), runtime shall persist issued-dose attribution when the command is applied or its delivery outcome is uncertain. The attribution shall include request step, first eligible attribution step, requested units, request time, expected physical completion time, component split when available, flow ID when applicable, and pod identity when available. If the next due step arrives while that dose is still delivering, runtime shall skip the algorithm step rather than advancing with provisional delivery evidence. If communication resumes after one or more missed steps and pump evidence matches the same request step, requested units within supported rounding tolerance, proven same pod identity, and delivered units within the credible range of 0...requested units (within tolerance), runtime shall replay the missed primary and secondary/safety algorithm steps before the live resumed step, inject the reconciled delivered amount only at the first missed step after the request step, use unavailable CGM input (CGM=-1) for synthetic missed steps, and issue no catch-up pump commands. If persisted matching evidence exists and the live due step is exactly the first eligible attribution step, runtime shall feed that evidence into the live step without creating synthetic replay rows. If fallback-basal replay is also pending and reconnect recovery has a same-pod cumulative pump-delivered insulin delta that includes both the pending issued dose and fallback basal exposure, runtime shall first partition the known pending issued-dose requested amount from the pump total, persist that partition as issued-dose reconciliation evidence, use only the residual pump delta for fallback-basal credibility and replay allocation, and retain the raw pump total separately for telemetry/operator review. If the pump total cannot cover the pending issued dose, the pending dose cannot be matched to the same pod/request, or the residual does not credibly match modeled fallback exposure, runtime shall not guess the split, shall not store or display the raw pump total as actual fallback-basal delivery, and shall suppress replay under ambiguous/unresolved reconciliation. If fallback-basal replay is also pending, issued-dose replay shall be monotonic and non-duplicating with fallback replay. If matching evidence is unavailable, mismatched, non-credible, missing pod identity, or still unresolved while the original pod has not been proven replaced and no SRS-MEAL-012 user-confirmed escape has occurred, runtime shall not guess delivered insulin and shall skip live advancement while the attribution remains pending. If a different/new pod is observed before reconciliation, runtime shall record different_or_new_pod, preserve the current algorithm session, assume the issued dose was delivered, feed the assumed delivered amount into the first eligible attribution step by replay or live-step input, clear the old-pod pending attribution after that consumption, scrub unrelated replacement-pod lastDelivery from the resumed live algorithm input, and shall not block later insulin-adding automatic commands solely because the original pod cannot be reconciled. For the SRS-MEAL-012 user-confirmed unavailable-pod escape, runtime may consume assumed-delivered clinical-policy evidence without pod identity only when request step, requested units, delivered-unit bounds, and non-active pump status match. Legacy persisted different_or_new_pod_unresolved holds shall be treated as nonblocking under this policy.

Meal Announce

  • SRS-MEAL-001: Meal announce shall only use borrow execution when request time is before the next scheduled slot and within borrow window (<= 2 future 5-minute slots).
  • SRS-MEAL-002: Meal announce shall be blocked unless an active pod is present, pump status is known, and pump is not delivering. Unavailable-reason precedence shall report noPump when no active pod is present, and reserve signalLoss for active-pod unknown-status conditions.
  • SRS-MEAL-003: Meal announce UI shall provide explicit unavailable reason and next retry time when applicable, including reconnect/recovery-required guidance when masked fallback may have become active.
  • SRS-MEAL-004: If meal announce is requested after the next scheduled slot is already due/missed, runtime shall execute meal input on the current due step (expectedStep) instead of rejecting solely due to late borrow timing.
  • SRS-MEAL-005: Meal announce shall be blocked until the loop establishes the first successful anchored step (firstSuccessfulStepAt), even when pump and CGM are otherwise available.
  • SRS-MEAL-006: If the meal announce composer remains visible while runtime availability changes, the app shall revalidate meal availability on foreground refresh and immediately before submit; unavailable state shall block dispatch and present current blocked messaging instead of using stale availability.
  • SRS-MEAL-007: Meal announce submit shall not be presented or logged as success until runtime/coordinator result is known. Executed success shall only be shown after runtime completion, and blocked/rejected outcomes shall produce explicit user-visible result messaging. Uncertain command outcomes shall produce explicit blocked guidance rather than optimistic success.
  • SRS-MEAL-008: Once a meal announce request is accepted for execution, the app shall persist pending meal-request state across relaunch until the request is explicitly cleared, reconciled against executed step history, or reset by session reset/disarm. Persisted state shall include the concrete target step accepted by runtime and the correlated meal flow identifier needed for lifecycle telemetry closure.
  • SRS-MEAL-009: While a persisted prior meal request remains pending, additional meal announces shall be blocked after relaunch and the user shall be informed that a meal request is already in progress. If the prior request has an uncertain command outcome, duplicate meal entry shall remain blocked until reconciliation or session reset/disarm, and the user shall be informed that the prior meal delivery outcome is uncertain.
  • SRS-MEAL-010: If a competing trigger or slot conflict prevents meal execution on the originally observed slot, runtime shall not silently lose or reinterpret the meal request. The app shall block the submit with explicit slot-conflict/retry guidance rather than silently reassigning the meal to a different borrowed step.
  • SRS-MEAL-011: If meal announce is requested while pump bolus delivery is already in progress, the app shall present a destructive cancel-delivery path on Home that can cancel the current bolus, report the actual insulin delivered before cancellation in Home's standard alert-summary region, and preserve that delivered amount for subsequent algorithm-step accounting when the operator later reopens meal announce.
  • SRS-MEAL-012: If a meal-announcement delivery-progress modal remains unresolved because the original pod cannot be confirmed, the app shall provide an explicit user-confirmed pod-replacement escape only for the matching meal-linked issued-dose attribution. The escape shall become available when the original pod is known unavailable, past hard service-stop, known different/replaced, or when the expected physical completion time has elapsed by at least 2 minutes without matching evidence. On confirmation, runtime shall record assumed-delivered issued-dose evidence using the original requested units and pod identity when available, record an auditable user_abandoned_unavailable_pod disposition, clear only the meal-progress UI fields, preserve the issued-dose attribution for replay/live-step insulin accounting, and route the operator to pod setup. The escape shall not resolve correction-only or basal-only pending issued-dose attributions.

Team review note: - SRS-MEAL-004 is accepted for the current software handoff baseline as the implemented late-submit meal behavior. - Meal tooLate retry messaging shall point to the immediate next due-step time boundary (not an added fixed 5-minute delay). - SRS-MEAL-007 through SRS-MEAL-012 are now implemented in the app baseline through runtime-result-gated meal success handling, blocked/rejected submit messaging, persisted pending meal-request state + flow correlation, uncertain-outcome duplicate blocking, relaunch reconciliation against executed-step/pump-delivery evidence, explicit slot-conflict blocking when another step advances after the meal flow was opened, a destructive cancel-delivery flow when meal entry is attempted during active bolus delivery, user-confirmed pod replacement for unconfirmed old-pod meal delivery, and correlated accepted/resolved lifecycle telemetry closure.

State Persistence and Recovery

  • SRS-STATE-001: The app shall persist algorithm state and runtime cadence state across relaunch.
  • SRS-STATE-002: Reset Algo shall clear persisted algorithm state, persisted cadence state, and step timeline/session history to start a fresh session.
  • SRS-STATE-003: Pump and CGM manager state shall persist across relaunch to avoid forced re-pairing.
  • SRS-STATE-004: When masked fallback is armed, runtime persistence shall retain the original programmed basal schedule, the currently programmed fallback schedule/rate, safety target, last known pod identity, last known pod total-delivery baseline/timestamp, last mask-renewal / schedule-refresh timestamps and outcomes, any restore-pending, restore-failed, or reconciliation-required recovery context needed for safe connected maintenance and later disarm/restore, and any pending pump-delta reconciliation state needed for reconnect recovery after offline mask expiry, confirmed/corrected missed-step algorithm replay, or explicit ambiguous unreconciled resume. Runtime persistence shall also retain separate primary and secondary/safety q5 nominal-basal profiles, with local-time slot observations, so fallback schedule generation is traceable to the safety-track nominal basal values rather than the primary dosing track. Runtime persistence shall retain pending issued-dose attribution, active issued-dose reconciliation holds, and the most recent issued-dose reconciliation failure disposition needed to avoid guessing delivered insulin across relaunch or pod replacement.
  • SRS-STATE-005: Algorithm start, stop, reset, and replacement algorithm-session creation shall occur only in response to an explicit operator action. Runtime recovery, pump reconnect, pod replacement, CGM recovery, fallback reconciliation failure, app launch, app foreground, scheduler wake, telemetry replay, or cloud/auth state shall not independently stop the algorithm, start the algorithm, reset the active algorithm session, or create a replacement session. Recovery logic may block command application, suppress replay, mark missed steps as unreconciled, and continue the existing session at the current cadence slot.

Algorithm Verification Controls

  • SRS-ALG-001: The Algo2015 implementation and bridge path shall maintain a deterministic golden-vector regression suite with fixed inputs and expected outputs under version control.
  • SRS-ALG-002: Algo2015 verification shall include structural coverage reporting for C bridge and C++ algorithm sources, with predefined coverage targets and documented rationale for uncovered regions.
  • SRS-ALG-003: Bridge contract behavior for null inputs, state reset edge conditions, sentinel mappings, and subject-id boundary handling shall be explicitly verified.
  • SRS-ALG-004: Algorithm state continuity shall be verified across multi-step execution, persistence/reload, and reset-to-fresh session boundaries.
  • SRS-ALG-005: Any change to pregnancy configuration inputs (target, meal upfront, TMAX) shall include differential algorithm-output evidence against baseline replay vectors.
  • SRS-ALG-006: Formal Algo2015 verification runs shall include a static-analysis lane for algorithm/bridge sources with logged findings status and run linkage metadata.
  • SRS-ALG-007: MISRA assessment for the host-side investigational Algo2015 lane shall be risk-based and conditional: each formal run shall include either linked MISRA evidence with signed deviation handling (if applicable) or an explicit not-applicable decision rationale with compensating controls.

Telemetry and Traceability

  • SRS-LOG-001: For each executed step, telemetry shall include an explicit step execution timestamp (step_executed_at), algorithm input snapshot, output snapshot, and pump command result.
  • SRS-LOG-002: Telemetry storage shall support export with stable column definitions.
  • SRS-LOG-003: Telemetry persistence shall not block UI responsiveness (no heavy synchronous file generation on main actor).
  • SRS-LOG-004: Debug builds shall provide a local cloud-log upload threshold control with levels Error, Warning, Info, Debug; default threshold shall remain Error, and threshold evaluation shall be inclusive (selected level and higher severities).
  • SRS-LOG-005: Clinical settings save flow shall emit ui.critical telemetry for state_viewed, submit, cancel, and blocked outcomes with stable screen_id/element_id values and old/new field details for changed clinical parameters.
  • SRS-LOG-006: app.lifecycle.launched and app.lifecycle.foregrounded telemetry payloads shall include timezone and clock-check context fields: device_timezone_id, device_utc_offset_seconds, clock_check_result, and when available clock_check_skew_seconds, clock_check_rtt_ms, clock_check_at_utc.
  • SRS-LOG-007: Meal-announce telemetry shall expose a correlated request lifecycle so cloud reconstruction does not rely on optimistic submit success alone. Implemented baseline includes submitted, accepted, success, blocked, uncertain, and resolved transitions keyed by meal flow_id, with replay state persisted until emission so accepted and resolved are not lost across terminate/relaunch windows; resolved is emitted for immediate completion, relaunch/pump-evidence reconciliation after uncertainty, or session-reset clear. Loop command telemetry shall preserve command outcome semantics, including uncertain delivery, rather than collapsing all non-success outcomes into generic blocked state.
  • SRS-LOG-008: Target-selection telemetry shall capture clinician-controlled regular-settings target profile changes and participant target-change approval-capture events with stable ui.critical event identifiers and required detail fields (target_range_profile, requested/applied target, approval metadata, and blocked/cancelled reasons where applicable).
  • SRS-LOG-009: Masked fallback review telemetry shall capture fallback arm, maintenance deferred, mask renewal, schedule-refresh unchanged checks, schedule refresh, offline mask expiry, and restore success/failure with selected fallback rate, source, safety target, duration, reconciliation status, pod-continuity result, and failure detail sufficient for Home Recent Dose Steps review. Resolved reconnect-recovery events shall also retain modeled fallback delivery and, when available from proven same-pod continuity, pump-reported delivered insulin since the last connected fallback baseline. Per-step local review telemetry shall also retain the executed primary and secondary algorithm step summaries needed to display each track's step count, suggested dose, nominal basal, and instant basal in Recent Dose Steps. When confirmed/corrected same-session fallback delivery reconciliation occurs, local review/export shall include only fallback-active missed-step primary/secondary algorithm replay rows allocated from the credible same-pod pump-reported delivered-insulin delta using the persisted programmed fallback schedule as the weighting model; each replay step shall use unavailable CGM input (-1), that step's delivered-insulin allocation including explicit 0 U input when no pump allocation belongs to that fallback-active step, and no pump command application. Pre-activation disconnected missed steps shall remain absent from replay telemetry rather than appearing as synthetic 0 U rows. The resumed live step shall use actual refreshed pump status and shall not receive a duplicate aggregate recovered-delivery input. Cloud telemetry shall additionally emit a dedicated loop.fallback.event family with a stable fallback_event_id, lifecycle kind, structured delivery/reconciliation summary fields including pod_continuity, and explicit occurrence timestamps so BionicScout can render fallback-related events separately from ordinary loop-step telemetry and distinguish modeled fallback delivery, pump-reported delivered insulin, and reconciled delivery when available. Fallback arm and schedule-refresh cloud events shall include the programmed four-entry schedule, safety q5 profile source/kind metadata, observed/imputed slot counts, profile timezone metadata, and the 288 q5 profile rates used for that specific schedule-programming operation; routine mask renewals shall not upload the 288-rate array.

UI Safety and Status

  • SRS-UI-001: Home loop-status card shall use deterministic state precedence: No Session > No Pod > No CGM > Ready > age-based states, where age-based states are derived from cadence due-time (firstSuccessfulStepAt + (lastExecutedStep + 1) * 300s) rather than raw lastSuccessfulRunAt.
  • SRS-UI-002: Home availability and status messaging shall align with runtime behavior (no false available state for blocked actions).
  • SRS-UI-003: Initial CGM and Pod startup/setup modals shall provide an explicit Cancel action that dismisses the modal without forcing entry into settings.
  • SRS-UI-004: If the meal announcement composer is visible and the app transitions to background, the composer shall auto-dismiss/cancel so meal intent does not persist across lifecycle interruption.
  • SRS-UI-005: If the latest CGM reading is older than 11 minutes, or if the latest CGM reading is present but not reliable (hasReliableGlucose == false), CGM display surfaces shall mask the reading as -- and shall not display a trend arrow.
  • SRS-UI-006: The app shall perform UTC drift checks on launch, on timezone/significant-time-change events, and on foreground when the last successful check is older than 24 hours. If absolute clock skew exceeds 600 seconds, the app shall present a non-blocking actionable warning no more than once per 24 hours; unavailable UTC checks shall not show warning spam.
  • SRS-UI-007: CGM display surfaces shall render boundary readings as textual values LOW (<=39 mg/dL) and HIGH (>=401 mg/dL) instead of numeric mg/dL values.
  • SRS-UI-008: Home CGM chart y-axis scaling shall use bounded stepped maxima (300, 350, 400 mg/dL) based on displayed data peak, and chart/scrub rendering shall keep boundary-value interpretation consistent with SRS-UI-007.

Clinical Settings and Pregnancy Configuration

  • SRS-CLIN-001: The app shall provide a dedicated Clinical Settings area for clinician-only configuration and control actions.
  • SRS-CLIN-002: Entry to Clinical Settings shall be gated by a subject-scoped offline clinical unlock verifier. The app shall provide a secure local material-installation path for provisioned verifier material; installation shall validate the subject/material match, persist verifier material in local secure storage, preserve the last locally accepted counter across material refresh, clear any active unlock expiration on material refresh, and reset local failed-attempt/lockout state. After verifier material is provisioned into local secure storage, code verification shall not require internet access. The verifier shall normalize grouped ASCII numeric code input, search only counters greater than the last locally accepted counter through the provisioned offline lookahead limit, compute the HMAC code using the provisioned current/supported secret version, persist the matched counter before opening clinician controls, set a local unlock expiration timestamp for the provisioned unlock duration, and reject malformed codes, non-ASCII digits, same/lower counters, wrong-subject codes, counters beyond lookahead, and unsupported secret versions. Manual lock shall persist unlock expiration clearing; if that persistence fails, the app shall keep clinician controls visibly unlocked and show a storage-failure message rather than falsely presenting a locked state. The app shall provide an operator-facing provisioning entry (visible while clinician controls are locked) that accepts the subject ID and the BionicScout-issued one-time provisioning code (30-byte payload, Crockford base32 with format version, subject binding check, and checksum), decodes it offline, and installs the resulting verifier material through the same validated installation path; decoding shall reject malformed/truncated codes, checksum failures, unsupported format versions, and subject mismatches. Installed verifier material shall contain only the per-subject derived device secret; the issuing master secret shall never be provisioned to or stored on the device. The app shall additionally support fetching the provisioning code over the authenticated BionicScout session (subject-device token; the backend releases material only for the subject claimed by that account) and shall validate and install the fetched code through the same decode/installation path as typed input, including rejecting responses whose subject does not match the requested subject. Production master secrets shall not be hardcoded in app source.
  • SRS-CLIN-003: Subject ID, Weight, Start Algo, and Reset Algo controls shall be hosted in Clinical Settings and not exposed in non-clinician settings sections.
  • SRS-CLIN-004: Target selection shall support 90, 100, 110, 120, and 130 mg/dL only.
  • SRS-CLIN-005: Meal upfront percentage selection shall support exactly 75% and 90%.
  • SRS-CLIN-006: TMAX selection shall support 40...70 minutes inclusive, in increments of 5.
  • SRS-CLIN-007: Clinical settings values shall be persisted with versioned defaults/migration so runtime behavior is deterministic across relaunch and app update.
  • SRS-CLIN-008: Relocating Start Algo and Reset Algo into Clinical Settings shall not change their runtime behavior semantics.
  • SRS-CLIN-009: Clinical Settings shall provide a clinician-controlled target-access profile for participant-facing settings with exactly two values: Pregnancy and Standard.
  • SRS-CLIN-010: Participant-facing settings and the clinician target selector shall expose only the target options enabled by the current target-access profile: Pregnancy -> 90, 100, 110 mg/dL; Standard -> 110, 120, 130 mg/dL.
  • SRS-CLIN-011: Participant target changes in regular settings shall require approval capture before apply. The app shall block the change unless the operator records the approving clinical staff member name and an approximate approval time.
  • SRS-CLIN-012: If the clinician changes the target-access profile while the draft target is outside the newly selected profile subset, the app shall normalize the draft target to the nearest allowed value before save rather than preserving an out-of-profile target.
  • SRS-VAL-001: Weight entry shall be pounds on UI, integer-only, stored as kilograms for runtime/algorithm use; in current UX scope this entry is clinician-gated.

Team review notes: - SRS-CLIN-002 is accepted for the current software handoff baseline as an investigational single-device clinical unlock control. Broader production authorization/role-based access remains outside this IDE baseline unless explicitly pulled into scope. - Pregnancy configuration control set is sourced from Docs/Requirements/AlgorithmChanges_PregnancyConfig.md. - Implemented baseline now includes a clinician-controlled participant target-access profile (Pregnancy / Standard), participant target-change approval capture in regular settings, and a clinician target selector that is constrained to the currently selected profile subset.

User Alerts and Escalation

  • SRS-ALERT-001: The app shall normalize alerts from pump (OmniBLE), CGM (G7SensorKit), algorithm/runtime, and app safety policies into a single alert domain model.
  • SRS-ALERT-002: Each alert shall include source, severity, timestamp, user-facing message, and recommended action metadata.
  • SRS-ALERT-003: Alert presentation shall apply severity-based channels and deterministic precedence so critical alerts are never hidden by lower-severity alerts.
  • SRS-ALERT-004: The app shall debounce or coalesce transient reconnect/noise events to reduce false-alarm UX while preserving true fault visibility.
  • SRS-ALERT-005: Alert life-cycle behavior shall define clear/acknowledge rules per alert type (auto-clear vs explicit acknowledge).
  • SRS-ALERT-006: Protocol-required alert conditions and response wording shall be represented in app behavior and traceable to verification evidence.
  • SRS-ALERT-007: For high-priority non-CGM alerts (actionable/safetyCritical), the app shall issue background local notifications with de-duplication and per-severity cooldown to avoid alert spam.
  • SRS-ALERT-008: The app shall provide an in-app Alert Center showing both active alerts and recently cleared alerts.
  • SRS-ALERT-009: Pump and CGM alert issue/retract lifecycle state shall persist across app relaunch, including lookup of unretracted alerts and restoration of active alert visibility.
  • SRS-ALERT-010: Alerts with time-sensitive countdown wording shall refresh displayed remaining time at least once per minute while active so user-facing timing remains current.
  • SRS-ALERT-011: Home shall present active alerts as a prioritized vertical carousel (severity first, then recency) with explicit multiplicity indication when more than one alert is active.
  • SRS-ALERT-012: Safety-critical pump alerts (ALERT-PUMP-FAULT, ALERT-PUMP-INCOMPATIBLE) shall not auto-clear solely due to hasActivePod == false; they shall clear only on explicit lifecycle retraction/recovery or explicit acknowledge workflow.
  • SRS-ALERT-013: When armed-loop execution is stalled beyond the approved interruption threshold, the app shall issue an actionable interruption alert distinct from G7 unavailable/failed/expired alerts and clear it once successful step execution resumes or the loop is disarmed.
  • SRS-ALERT-014: The interruption alert shall use broader Algorithm Stepping Interrupted semantics, triggered when the armed loop has not achieved a successful algorithm step for longer than the approved interruption threshold, regardless of whether the immediate blocker is missing CGM, missing pod, pump signal loss, or another runtime execution gate.
  • SRS-ALERT-015: BionicLoop CGM availability/failure alerts shall be in-app informational status only on Home / Alert Center, shall not require explicit acknowledge, and shall not schedule background local notifications. The FDA-cleared Dexcom application shall be treated as the source of truth for CGM alarming and shall be configured accordingly in study use.
  • SRS-ALERT-016: When a trustworthy G7 reading is <55 mg/dL, the app shall issue an in-app-only urgent-low review alert on Home / Alert Center, shall allow clinician acknowledge/review capture, shall not schedule background local notifications, and shall auto-clear the active alert state on a later trustworthy G7 reading >=55 mg/dL. This alert shall be app-derived from CGM data and shall not claim Dexcom-app acknowledgement.
  • SRS-ALERT-017: Any no-active-pod condition shall raise a safety-critical pump alert after the approved debounce and shall repeat background local notification attempts at least every 30 minutes while the no-active-pod condition remains true, until active pod state is restored or another approved exit condition clears the alert.

Alert evolution notes: - Current implemented baseline is ALERT-ALGORITHM-STEPPING-INTERRUPTED. - The alert triggers on absent successful step execution rather than CGM-specific receipt loss alone. - Algorithm Stepping Interrupted preserves root-cause visibility so stronger underlying pump alerts remain available and prioritized while CGM state remains visible as separate informational context.

Alert source inventory and normalized mapping baseline: - Alert Inventory and Mapping

Security and Privacy

  • SRS-SEC-001: Long-term telemetry architecture shall support secure cloud upload as primary transport, with local CSV retained only as a development-only path.
  • SRS-SEC-002: Telemetry export and storage paths shall be controlled to minimize PHI/PII exposure.
  • SRS-SEC-003: Protected cloud API access is deferred from the current software handoff package. If cloud-backed protected APIs are included in a future accepted baseline, they shall require authenticated user identity managed by Cognito before access is granted.
  • SRS-SEC-004: Multi-provider onboarding policy is deferred from the current software handoff package. If included in a future accepted baseline, onboarding shall define the allowed Sign in with Apple, Google, and Email paths explicitly.
  • SRS-SEC-005: Cloud authorization-role enforcement is deferred from the current software handoff package. If included in a future accepted baseline, authorization shall enforce least-privilege role and scope checks for telemetry and dashboard access.
  • SRS-SEC-006: Protected-cloud authentication failure handling is deferred from the current software handoff package. If included in a future accepted baseline, authentication and session failures shall fail closed for protected cloud operations while preserving safe local app behavior.
  • SRS-SEC-007: Cognito password-recovery workflow is deferred from the current software handoff package. If included in a future accepted baseline, email/password onboarding shall provide reset-code request and confirmation with explicit success/failure feedback.
  • SRS-SEC-008: Launch session-restore behavior is deferred from the current software handoff package. If included in a future accepted baseline, authenticated persisted sessions shall attempt secure restore/refresh without unnecessary manual re-login when restore succeeds.
  • SRS-SEC-009: Auth-failure Home-bypass continuity behavior is deferred from the current software handoff package. If included in a future accepted baseline, the app shall support explicit local Home bypass with persistent remote-monitoring login-recovery messaging when unauthenticated local loop state remains active.

Team review notes: - SRS-SEC-003..009 are deferred from the current software handoff package and require explicit scope re-entry before closure is claimed. - Existing development implementation may cover portions of SRS-SEC-007..009, but that implementation is not being claimed as closed software-handoff scope in this package. - Role model (clinical/engineering/admin) and token lifecycle policy are pending.

Traceability Source Mapping

Primary upstream references:

  • Docs/Requirements/Requirements.md
  • Docs/Requirements/RiskAnalysis.md
  • Docs/Analysis/Marjorie_AlgorithmIO_GapAnalysis.md
  • Docs/Architecture/Architecture.md
  • Docs/Requirements/AlgorithmChanges_PregnancyConfig.md