Safety Principles

DiveSuite handles decompression calculations that, if incorrect, can cause serious injury or death. This document defines our non-negotiable safety principles.

Core Principles

1. Deco Engine Isolation

All decompression calculations happen in a single, isolated Rust module:

+-------------------------------------+
|           Application               |
+-------------------------------------+
|         Service Layer               |
+-------------------------------------+
|    +-----------------------+        |
|    |    Deco Engine        | <- Only module that
|    |    (Rust/WASM)        |   touches tissue
|    |                       |   loading calculations
|    |  - Buhlmann ZHL-16C   |
|    |  - NDL calculation    |
|    |  - Gas physics        |
|    +-----------------------+        |
+-------------------------------------+

Rules:

• Only the deco engine performs tissue loading calculations
• The engine has a clean API boundary (Input -> Output)
• No direct manipulation of engine internals from outside
• Engine code requires explicit review before modification

2. AI Never Overrides

AI is strictly advisory. AI cannot:

• Generate decompression schedules
• Modify gradient factors without user confirmation
• Suggest exceeding MOD, NDL, or ppO2 limits
• Override safety warnings
• Bypass the validation layer

Architecture:

User Input -+--------------------------------------> Validation -> Deco Engine -> Plan
            |                                              ^
            +-> AI Service -> Suggestions -> User Review --+
                            (advisory)      (required)

AI output is always treated as unverified user input that must flow through normal validation.

3. Disclaimers Always Visible

Every dive plan output includes a mandatory disclaimer:

Required Disclaimer

This dive plan is for informational and planning purposes only.

• DiveSuite is NOT a dive computer and cannot monitor your actual dive
• Always dive with a functioning dive computer and follow its guidance
• Never exceed your training, certification level, or personal limits
• Verify critical dive plans with multiple independent sources

Implementation:

• Disclaimer component cannot be removed or hidden
• Disclaimer must be visible without scrolling on plan output
• First-launch acceptance recorded with timestamp
• Acceptance stored in database for legal record

4. Validation Required

Before release, the deco engine must be validated:

• Unit tests: 95%+ branch coverage
• Property-based tests: Verify invariants (NDL decreases with depth, etc.)
• Cross-reference: Compare against Subsurface, MultiDeco (same algorithm)
• Documentation: All test vectors documented in deco-validation.md

What we validate against:

Reference	Purpose	Match Type
Subsurface	Same algorithm (Buhlmann ZHL-16C)	Exact match
MultiDeco	Commercial reference	Near match
Published tables	Sanity check	Approximate

What we do NOT claim:

• Equivalence with PADI tables (uses DSAT, not Buhlmann)
• Medical device certification
• Guarantee of diver safety

5. Offline Must Work

Core safety features work without internet:

Feature	Offline	Online Required
Dive planning	Yes	-
Dive logging	Yes	-
Profile visualization	Yes	-
Safety disclaimers	Yes	-
AI suggestions	No	Yes
Cloud sync	No	Yes
Community features	No	Yes

When offline:

• AI features are disabled (not erroring)
• UI clearly indicates offline status
• All local data remains accessible

Safety-Critical Code Paths

Deco Engine

rust-engine/src/lib.rs

pub fn calculate_plan(input: DecoEngineInput) -> Result<DecoEngineOutput, DecoError> {
    // 1. Validate input
    validate_input(&input)?;

    // 2. Calculate tissue loading
    let tissues = calculate_tissue_loading(&input);

    // 3. Calculate NDL or deco schedule
    let plan = if is_ndl_dive(&tissues, &input) {
        calculate_ndl_plan(&tissues, &input)
    } else {
        calculate_deco_plan(&tissues, &input)
    }?;

    // 4. Calculate gas consumption
    let gas = calculate_gas_consumption(&plan, &input)?;

    // 5. Generate warnings
    let warnings = generate_safety_warnings(&plan, &input);

    Ok(DecoEngineOutput {
        plan,
        gas_consumption: gas,
        tissue_loading: tissues,
        warnings,
        // Disclaimer is ALWAYS included
        disclaimer: MANDATORY_DISCLAIMER,
    })
}

AI Safety Layer

src/features/ai/services/safety-validator.ts

export function validateAIOutput(suggestion: AISuggestion, limits: SafetyLimits): ValidationResult {
  const violations: Violation[] = [];

  // Check MOD
  if (suggestion.depth > limits.maxOperatingDepth) {
    violations.push({
      type: 'MOD_EXCEEDED',
      message: `Suggested depth ${suggestion.depth}m exceeds MOD ${limits.maxOperatingDepth}m`,
    });
  }

  // Check ppO2
  if (suggestion.ppO2 > limits.maxPpO2) {
    violations.push({
      type: 'PPO2_EXCEEDED',
      message: `Suggested ppO2 ${suggestion.ppO2} exceeds limit ${limits.maxPpO2}`,
    });
  }

  // Check NDL
  if (suggestion.bottomTime > limits.ndl) {
    violations.push({
      type: 'NDL_EXCEEDED',
      message: `Suggested bottom time exceeds NDL`,
    });
  }

  return {
    valid: violations.length === 0,
    violations,
    // If any violations, AI suggestion is rejected
    suggestion: violations.length === 0 ? suggestion : null,
  };
}

Forbidden Actions

The following actions are explicitly forbidden in DiveSuite code:

Action	Why Forbidden
Disable disclaimer display	Legal and safety requirement
Allow AI to modify deco output	Safety boundary violation
Suppress safety warnings	Could hide critical information
Skip validation in production	Could allow unsafe plans
Use any in deco-related TS	Type safety is critical
Use panic! in deco Rust	Must handle errors gracefully

Incident Response

When a safety issue is discovered:

1. Assess severity — Can this cause injury?
2. Notify users — In-app notification for critical issues
3. Force update — CC-09 mechanism for safety-critical fixes
4. Fix and test — Including regression test
5. Disclose — Document in release notes
6. Post-mortem — How did this pass testing?