Skip to content

Software Requirements Specification (SRS)

Status: Final draft prepared for handoff (pending review)
Version: 0.9
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-04-06 15:05 EDT

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

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.
  • 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: Pump-reconnect fallback shall not execute step 0, shall not re-anchor cadence, and shall not replay multiple missed slots; each reconnect-triggered execution may service at most the current due step.

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, and capture a submission timestamp at user confirmation time.
  • 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).
  • 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.

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.
  • 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.

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-011 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, 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.

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).

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 an investigational passcode control. The current software handoff baseline uses configured passcode value 020508; production release requires replacement with authenticated role-based access.
  • 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 control and must be replaced by authenticated, role-based gating before production release. - 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.

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