release: prepare v0.0.1-rc.4

spec/protocol_spec.md

@@ -1,98 +1,93 @@
-# 8BitDo Clean-Room Protocol Specification (Sanitized)
+# OpenBitdo Protocol Overview
 
-## Scope
-This document defines a sanitized command and transport contract for a clean-room Rust implementation.
-It is intentionally independent from reverse-engineered source code details and uses stable requirement IDs.
+This document summarizes the sanitized protocol model used by the clean-room runtime.
 
 ## Wire Model
-- Transport: HID-like reports
-- Primary report width: 64 bytes (`Standard64`, `DInput`, `JpHandshake` families)
-- Variable-length reports: allowed for boot/firmware phases
-- Byte order: little-endian for multi-byte numeric fields
+
+- HID-like command transport
+- primary 64-byte reports for `Standard64`, `DInput`, and `JpHandshake`
+- variable-length reports only where firmware or boot phases require them
+- little-endian multi-byte numbers
 
 ## Protocol Families
-- `Standard64`: standard 64-byte command and response flow
-- `JpHandshake`: alternate handshake and version probing workflow
-- `DInput`: command family used for mode and runtime profile operations
-- `DS4Boot`: reserved boot mode for DS4-style update path
-- `Unknown`: fallback for unknown devices
+
+- `Standard64`
+- `JpHandshake`
+- `DInput`
+- `DS4Boot`
+- `Unknown`
 
 ## Safety Classes
-- `SafeRead`: read-only operations
-- `SafeWrite`: runtime settings/profile writes
-- `UnsafeBoot`: bootloader transitions with brick risk
-- `UnsafeFirmware`: firmware transfer/commit operations with brick risk
 
-## Response Validation Contract
-- Responses are validated per command against byte-pattern expectations from `command_matrix.csv`
-- Validation outcomes: `Ok`, `Invalid`, `Malformed`
-- Retry policy applies on `Malformed` or timeout responses
+- `SafeRead`: diagnostics and metadata reads
+- `SafeWrite`: profile, setting, or mapping writes
+- `UnsafeBoot`: bootloader transitions
+- `UnsafeFirmware`: firmware transfer and commit operations
+
+## Response Validation
+
+- every command validates against the registry table
+- outcomes are `Ok`, `Invalid`, or `Malformed`
+- retry logic applies on timeout or malformed data according to session policy
 
 ## Operation Groups
-- `Core`: generic identify/mode/profile/boot/fallback commands
-- `JP108Dedicated`: 108-key dedicated-button mapping + feature/voice operations
-- `Ultimate2Core`: Ultimate2 mode/slot/core-map operations
-- `Firmware`: device-scoped firmware enter/chunk/commit/exit operations
-- `CoreDiag`: decompiler-first detect/diagnostic command subset for candidate-readonly PIDs
-- `ModeProfileRead`: decompiler-first read-only mode/profile snapshot group for candidate-readonly PIDs
-- `FirmwarePreflight`: decompiler-first firmware readiness metadata reads (no transfer enablement)
 
-## JP108 Dedicated Support
-- Supported targets: `0x5209` (`PID_108JP`), `0x520a` (`PID_108JPUSB`)
-- First milestone mapping scope: `A`, `B`, `K1`-`K8`
-- Additional controls in this group:
-  - feature flags read/write
-  - voice setting read/write
-- Full 111-key matrix remap is explicitly out of scope for this milestone.
+- `Core`
+- `JP108Dedicated`
+- `Ultimate2Core`
+- `Firmware`
+- `CoreDiag`
+- `ModeProfileRead`
+- `FirmwarePreflight`
 
-## Ultimate2 Core Support
-- Supported targets: `0x6012` (`PID_Ultimate2`), `0x6013` (`PID_Ultimate2RR`)
-- First milestone editable scope:
-  - current mode read/set
-  - current slot read
-  - slot config read/write
-  - core button map read/write
-- Advanced subsystems (theme/sixaxis/deep macro editing) are intentionally hidden in this milestone.
+## Support Model
 
-## PID-Aware Command Gating
-- Command availability is gated by:
-  1. safety class and runtime unsafe acknowledgements
-  2. capability flags
-  3. explicit PID allowlist from `command_matrix.csv:applies_to`
-- `applies_to="*"` means globally available within existing safety/capability constraints.
+### Support Levels
 
-## Device Support Levels
-- `full`: command execution permitted for safe and unsafe operations (with user gates)
-- `detect-only`: identification allowed; unsupported operations return `UnsupportedForPid`
+- `full`
+- `detect-only`
 
-## Support Tiers
-- `full`: read/write/unsafe operations available according to existing safety gates.
-- `candidate-readonly`: detect/diag safe reads are allowed per PID allowlist; safe writes and unsafe flows are blocked.
-- `detect-only`: identify-only posture for unsupported or unknown PIDs.
+### Support Tiers
 
-## Candidate Read-Only Wave Policy
-- Wave-1 and Wave-2 expansion PIDs are classified as `candidate-readonly`.
-- Command policy for this tier:
-  - allow: detect/diag safe-read subset.
-  - allow: read-only mode/profile snapshot reads when family-appropriate.
-  - allow: firmware metadata/preflight reads only.
-  - deny: all safe-write operations.
-  - deny: all unsafe boot/firmware operations.
-- Promotion from `candidate-readonly` to `full` requires 3-signal evidence:
-  1. static dossier coverage
-  2. runtime trace evidence
-  3. hardware read/write/readback confirmation
+- `full`: normal read, write, and gated unsafe paths
+- `candidate-readonly`: safe-read diagnostics only
+- `detect-only`: identify-only posture
 
-## Dossier Linkage
-- Per-PID operation evidence is tracked in `spec/dossiers/**`.
-- `command_matrix.csv:dossier_id` links command rows to sanitized dossier artifacts.
-- `evidence_index.csv` maps PID to class-family anchors and operation groups.
+## Candidate Read-Only Policy
 
-## Required Runtime Gating
-Unsafe commands execute only when both conditions are true:
-1. `--unsafe`
-2. `--i-understand-brick-risk`
+Read-only candidates may:
 
-## Clean-Room Requirements Linkage
-Implementation and tests must trace to IDs in `requirements.yaml`.
-All public APIs and behavior are governed by `REQ-PROT-*`, `REQ-PID-*`, `REQ-SAFE-*`, and `REQ-TEST-*` IDs.
+- identify themselves
+- run allowed safe-read diagnostics
+- perform family-appropriate read-only metadata checks
+
+Read-only candidates may not:
+
+- write mappings or profiles
+- enter unsafe boot paths
+- transfer firmware
+
+Promotion to full support requires:
+
+1. static evidence
+2. runtime evidence
+3. hardware evidence
+
+## Feature Scopes
+
+### JP108
+
+- supported targets: `0x5209`, `0x520a`
+- current mapping scope: `A`, `B`, `K1`-`K8`
+
+### Ultimate 2
+
+- supported targets: `0x6012`, `0x6013`
+- current scope: mode, slot, slot config, core button map, and required analog handling
+
+## Runtime Safety Rule
+
+Unsafe commands are only allowed when the runtime has both:
+
+1. unsafe mode enabled
+2. explicit brick-risk acknowledgment