Skip to content

SAFETY_MODEL.md

Latest commit

 

History

History
116 lines (84 loc) · 5.64 KB

SAFETY_MODEL.md

File metadata and controls

116 lines (84 loc) · 5.64 KB

Safety Model

The Bao1702 Desktop CPS implements a multi-layer safety system designed to prevent accidental corruption of the radio's codeplug or firmware. Writing incorrect data to a radio can render it inoperable ("bricked"), so every write path enforces strict preconditions.

Design Principles

  1. Reads are safe; writes are dangerous — any radio can be read without preconditions.
  2. Backup before write is mandatory — no codeplug write proceeds unless a backup of the target radio already exists in the catalog.
  3. Unknown radios are read-only by default — the compatibility matrix must recognize the radio family before writes are allowed.
  4. Unsafe paths require explicit acknowledgement — the CLI force-write command demands the literal string I_ACCEPT_THE_RISK_OF_BRICKING_THE_RADIO.
  5. Clean-write architecture — the codeplug model is the sole source of truth. Dm1702NativeImageBuilder.Build() generates every byte from modeled fields or known OEM constants. There is no preserved-image overlay. Un-modeled image regions are set to validated OEM defaults (source: cross-capture byte-level comparison of 8 .data files; Ghidra CPS decompilation for offset validation).

Safety Components

SafetyPolicyEngine

The central policy enforcer (Bao1702.Protocol.Safety.SafetyPolicyEngine) evaluates every write request against the current policy options:

SafetyPolicyOptions
├── RequireBackupBeforeWrite: bool (default: true)
├── AllowUnknownTargetRead: bool (default: true)
├── AllowUnknownTargetWrite: bool (default: false)
└── ForceUnsafe: bool (default: false)

The engine returns a SafetyVerdict (Allowed, Blocked, or Warning) with a human-readable reason.

WriteIntentValidator

Before any write operation, WriteIntentValidator checks:

  • The image size matches the expected 245,760 bytes.
  • The codeplug passes structural validation (CodeplugWriteValidator).
  • The target radio identity is recognized in the compatibility matrix.
  • A codeplug backup exists for the target radio.

Validation failures produce WriteIntentValidationRequest results with categorized issues.

BackupLedger

BackupLedger (Bao1702.Protocol.Safety.BackupLedger) manages the on-disk backup catalog:

  • Codeplug backups — stored as raw 245,760-byte images with a JSON manifest containing SHA-256 hash, timestamp, and radio identity.
  • Firmware backups — stored with the same manifest pattern.
  • Integrity verification — SHA-256 is computed at backup time and verified at restore time.
  • Catalog queries — HasCodeplugBackup(radioIdentity) and HasFirmwareBackup(radioIdentity) support policy checks.

CompatibilityMatrix

CompatibilityMatrix maps radio families to capability levels:

Radio Family Read Write Notes
Bao1702 ✅ Confirmed ✅ Confirmed Validated against 8 captures
Unknown ✅ Allowed ❌ Blocked Read-only until identified

Each CompatibilityRule specifies the ProtocolKnowledgeLevel for read and write operations (Confirmed, Inferred, Unknown, or RequiresHardwareVerification).

CodeplugWriteValidator

CodeplugWriteValidator (Bao1702.Codeplug.Validation) performs structural checks before image generation:

  • Image size must equal Dm1702NativeImageAssumptions.ImageLength (245,760 bytes).
  • No duplicate channel names.
  • All zone/scan list/RX group member references resolve to valid entities.
  • Group list contact references are valid.
  • Validation issues are categorized by severity: Info, Warning, Error.

Write Flow

User clicks "Write to Radio"
        │
        ▼
Auto-connect (scan USB printer-class, VID 0483 / PID 5780)
        │ no radio? → display error and abort
        ▼
CodeplugWriteValidator.Validate()
        │ errors? → display and abort
        ▼
SafetyPolicyEngine.Evaluate(writeIntent)
        │ blocked? → display reason and abort
        ▼
BackupLedger.HasCodeplugBackup(radioIdentity)?
        │ no? → block with "read from radio first"
        ▼
Dm1702NativeImageBuilder.Build(model)
        │  (model is sole source of truth — no preserved-image overlay)
        ▼
StockCpsSession.WriteFullCodeplugAsync(image)
        ▼
Success — operation log updated

CLI Force-Write

The CLI unsafe force-write command bypasses all safety checks. It requires:

  1. The --ack flag with the exact string I_ACCEPT_THE_RISK_OF_BRICKING_THE_RADIO.
  2. The ForceUnsafe policy option is set to true internally for the duration of the operation.
  3. A warning is printed to stderr before the write proceeds.

This path exists solely for recovery scenarios where the normal safety chain cannot be satisfied (e.g., restoring a bricked radio from a known-good backup).

Field Validation Classification

Every decoded field in the native image serializers is classified by validation level (source: NativeCoverageAudit.md):

Level Meaning Evidence
Semantically validated Field offset, encoding, and meaning confirmed against OEM behavior Cross-capture binary diffs, Ghidra CPS decompilation
Structurally generated Layout extrapolated from validated patterns; not confirmed against OEM behavior for all values Pattern extension from page 0 to pages 1–2
Unknown Bytes present but semantic meaning not fully confirmed Listed in NativeCoverageAudit.md § Unknowns

This classification is documented per field in NativeCoverageAudit.md and enforced in the serializer source comments. A feature is NOT considered complete unless its native semantics are known, implemented, and validated against OEM behavior.
⚡