bybrooklyn/openbitdo
1
0
Fork 0
mirror of https://github.com/bybrooklyn/openbitdo.git synced 2026-03-19 04:12:56 -04:00
Code Issues Packages Projects Releases Wiki Activity

release: prepare v0.0.1-rc.4

Browse Source
This commit is contained in:
Brooklyn Halmstad
2026-03-07 15:51:21 -05:00
parent 86875075fc
commit da09094d3e
52 changed files with 1076 additions and 1234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
process/add_device_guide.md
View File

@@ -1,68 +1,37 @@
# Add Device Support (Hardcoded Path)
# Add Device Support
This guide keeps device support simple and explicit: everything is added directly in Rust code.
This guide describes the clean-room path for adding or promoting a device.
## 1) Add/verify PID in hardcoded registry
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/pid_registry_table.rs`
## Update The Runtime Catalog
Add a `PidRegistryRow` with:
- `name`
- `pid`
- `support_level`
- `support_tier`
- `protocol_family`
1. Add or verify the PID row in `sdk/crates/bitdo_proto/src/pid_registry_table.rs`.
2. Update capability defaults and support-tier policy in `sdk/crates/bitdo_proto/src/registry.rs`.
3. Add or verify command rows in `sdk/crates/bitdo_proto/src/command_registry_table.rs`.
4. Update candidate-readonly gating in `sdk/crates/bitdo_proto/src/session.rs` when the new PID needs safe-read diagnostics.
## 2) Update capability policy
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/registry.rs`
## Update The Sanitized Evidence
Update `default_capability_for(...)` and support-tier PID lists so capability flags match evidence.
Keep the spec and evidence artifacts aligned:
## 3) Add/verify command declarations
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/command_registry_table.rs`
- `spec/device_name_catalog.md`
- `spec/protocol_spec.md`
- `process/device_name_sources.md`
- dossier and matrix artifacts where applicable
Add/verify command rows:
- `id`
- `safety_class`
- `confidence`
- `experimental_default`
- `report_id`
- `request`
- `expected_response`
- `applies_to`
- `operation_group`
## Update Tests
## 4) Confirm runtime policy
Runtime policy is derived in code (not scripts):
- `confirmed` -> enabled by default
- inferred `SafeRead` -> experimental-gated
- inferred `SafeWrite`/unsafe -> blocked until confirmed
At minimum, touch the tests that prove:
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/registry.rs`
- support-tier gating is correct
- command/runtime policy is correct
- diagnostics or mapping behavior is correct for the new device family
## 5) Update candidate gating allowlists
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/session.rs`
## Validation
Update `is_command_allowed_for_candidate_pid(...)` so detect/diag behavior for the new PID is explicit.
From `cleanroom/sdk`:
## 6) Keep spec artifacts in sync
Files:
- `/Users/brooklyn/data/8bitdo/cleanroom/spec/pid_matrix.csv`
- `/Users/brooklyn/data/8bitdo/cleanroom/spec/command_matrix.csv`
- `/Users/brooklyn/data/8bitdo/cleanroom/spec/evidence_index.csv`
- `/Users/brooklyn/data/8bitdo/cleanroom/spec/dossiers/...`
## 7) Add tests
- Extend candidate gating tests:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/tests/candidate_readonly_gating.rs`
- Extend runtime policy tests:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/tests/runtime_policy.rs`
## 8) Validation
From `/Users/brooklyn/data/8bitdo/cleanroom/sdk`:
- `cargo test --workspace --all-targets`
- `./scripts/cleanroom_guard.sh`
```bash
./scripts/cleanroom_guard.sh
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --all-targets
```

57
process/aur_publish_troubleshooting.md
View File

@@ -1,14 +1,15 @@
# AUR Publish SSH Troubleshooting
# AUR Publish Troubleshooting
This runbook focuses on resolving AUR publish failures such as `Permission denied (publickey)` in release workflows.
Use this runbook when the AUR release path fails, especially on SSH authentication.
## Preconditions
- `AUR_USERNAME` secret exists.
- `AUR_SSH_PRIVATE_KEY` secret exists and contains the full private key block.
- Runner can reach `aur.archlinux.org:22`.
## Typical Failure Signatures
## 1) Key format and permissions checks
Run on a secure local shell before updating secrets:
- `Permission denied (publickey)`
- `Host key verification failed`
- missing `AUR_USERNAME`
- missing `AUR_SSH_PRIVATE_KEY`
## Local SSH Sanity Check
```bash
mkdir -p /tmp/aur-debug && cd /tmp/aur-debug
@@ -20,10 +21,11 @@ ssh-keygen -y -f aur_key >/tmp/aur_key.pub
```
Expected:
- `ssh-keygen -y` succeeds.
- no passphrase prompt for CI use.
## 2) Known hosts and host verification
- the key parses successfully
- no CI-incompatible passphrase prompt
## Known Hosts Check
```bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
@@ -31,40 +33,27 @@ ssh-keyscan -H aur.archlinux.org >> ~/.ssh/known_hosts
chmod 600 ~/.ssh/known_hosts
```
Expected:
- `aur.archlinux.org` host key is present in `known_hosts`.
## 3) SSH dry-run authentication
## Remote Auth Check
```bash
ssh -i /tmp/aur-debug/aur_key \
-o IdentitiesOnly=yes \
-o StrictHostKeyChecking=yes \
${AUR_USERNAME}@aur.archlinux.org
"${AUR_USERNAME}@aur.archlinux.org"
```
Expected success signature:
- authentication accepted (AUR may close session after auth; that still proves key acceptance).
An immediate disconnect after auth is still acceptable. It proves the key is valid.
Expected failure signatures:
- `Permission denied (publickey)` means wrong key/user pairing.
- `Host key verification failed` means known_hosts mismatch/missing.
## 4) Repo-level publish dry run
For package repo:
## Repo Check
```bash
git ls-remote ssh://${AUR_USERNAME}@aur.archlinux.org/openbitdo-bin.git
git ls-remote "ssh://${AUR_USERNAME}@aur.archlinux.org/openbitdo-bin.git"
```
Expected:
- command returns refs without auth failures.
If this fails, the AUR account or key pairing is still wrong.
## 5) CI secret update checklist
- Store private key in `AUR_SSH_PRIVATE_KEY` exactly as multiline PEM/OpenSSH block.
- Store account name in `AUR_USERNAME`.
- Re-run release workflow preflight job.
## After The Fix
## 6) Post-fix validation
- Confirm release preflight no longer fails on SSH auth.
- Confirm `publish-aur` job pushes `openbitdo-bin` metadata repo.
- rerun the release workflow
- confirm `publish-aur` succeeds
- confirm `openbitdo-bin` points at the new release tag

26
process/branch_policy.md
View File

@@ -1,16 +1,20 @@
# Branch and Merge Policy
# Branch Policy
Because this workspace currently has no active Git repository metadata, this policy is documented for use when repository control is re-enabled.
## Defaults
## Branches
- `codex/dirtyroom-spec`: sanitize findings into `cleanroom/spec` and `cleanroom/process`
- `codex/cleanroom-sdk`: implement SDK and CLI from sanitized artifacts only
- default branch: `main`
- automation/worktree branches: `codex/*`
- release tags: `v*`
## Merge Strategy
- Cherry-pick sanitized spec commits from dirtyroom branch into cleanroom branch.
- Never merge dirty-room evidence paths into cleanroom implementation branch.
## Merge Expectations
- clean-room implementation stays in `cleanroom/`
- dirty-room or decompiler material never lands in runtime, tests, docs, or workflows inside this tree
- release tags are created from commits that are already on `main`
## Review Checklist
- Guard script passes.
- No forbidden path references in code/tests.
- Requirement IDs are traceable from implementation and tests.
- clean-room guard passes
- no forbidden path references were introduced
- docs and release metadata are consistent with the current RC
- required CI checks stay green

33
process/cleanroom_rules.md
View File

@@ -1,23 +1,24 @@
# Clean-Room Rules
## Allowed Inputs During Clean Implementation
- `cleanroom/spec/**`
- `cleanroom/process/cleanroom_rules.md`
- `cleanroom/harness/golden/**`
## Allowed Inputs
## Forbidden Inputs During Clean Implementation
- `decompiled/**`
- `decompiled_*/*`
- `bundle_extract/**`
- `extracted/**`
- `extracted_net/**`
- `session-ses_35e4.md`
- `cleanroom/spec/**`
- `cleanroom/process/**`
- approved harness fixtures and generated release artifacts
## Forbidden Inputs
- decompiled vendor code
- copied proprietary snippets
- direct references to dirty-room paths from clean implementation or user-facing docs
## Enforcement
- `cleanroom/sdk/scripts/cleanroom_guard.sh` checks for forbidden path and token references.
- CI runs the guard before test jobs.
- `cleanroom/sdk/scripts/cleanroom_guard.sh` scans for forbidden references
- CI runs the guard before packaging and test jobs
## Commit Hygiene
- No copied decompiled code snippets.
- No direct references to dirty-room files in SDK implementation/tests.
- Any new protocol fact must be added to sanitized spec artifacts first.
- no copied decompiled code
- no raw vendor-source excerpts
- new protocol facts must arrive through sanitized spec or evidence updates first

29
process/commenting_standard.md
View File

@@ -1,17 +1,20 @@
# OpenBitdo Commenting Standard
# Commenting Standard
This project prefers concise, high-context comments.
OpenBitdo prefers sparse, high-value comments.
## Required Comment Zones
- Command gating order and rationale (`bitdo_proto::session`).
- Support-tier decisions and promotion boundaries (`candidate-readonly` vs `full`).
- Unsafe/firmware blocking rules and brick-risk protections.
- Retry/fallback behavior where multiple command paths exist.
- State-machine transitions in TUI/app-core flows when transitions are non-obvious.
## Add Comments When
## Avoid
- Trivial comments that restate code syntax.
- Comment blocks that drift from behavior and are not maintained.
- safety or brick-risk behavior is non-obvious
- support-tier gating would be easy to misread
- retries, fallbacks, or validator behavior need rationale
- a state transition matters more than the literal code line
## Rule of Thumb
If someone adding a new device could misread a policy or safety boundary, comment it.
## Avoid Comments When
- the code already says the same thing clearly
- the comment would become stale as soon as names or branches change
- the comment explains syntax instead of intent
## Rule Of Thumb
If a future contributor could accidentally weaken a safety boundary, the surrounding code deserves a short comment.

41
process/community_evidence_intake.md
View File

@@ -1,30 +1,25 @@
# Community Evidence Intake
## Purpose
Collect hardware and protocol evidence from the community in a clean-room-safe format.
This process collects safe, sanitized device evidence from users and testers.
## Submission Requirements
Every report must include:
- Device name
- VID/PID (`0xVVVV:0xPPPP`)
- Firmware version shown by official software/device
- Operation attempted
- Sanitized request/response shape description
- Reproducibility notes (steps, OS, transport mode)
## Required Submission Data
- device name
- VID/PID in `0xVVVV:0xPPPP` form
- firmware version
- operation attempted
- sanitized request or response description
- OS, transport mode, and reproducibility notes
## Prohibited Content
- Raw copied decompiled code.
- Vendor source snippets.
- Binary dumps with proprietary content not required for protocol structure.
## Acceptance Levels
- `intake`: report received, unverified.
- `triaged`: mapped to a PID/operation group and requirement IDs.
- `accepted`: converted into sanitized dossier/spec updates.
- raw decompiled code
- copied vendor source snippets
- proprietary dumps that are not sanitized into structure-level notes
## Maintainer Processing
1. Validate report format.
2. Cross-reference PID with `spec/pid_matrix.csv`.
3. Create/update `spec/dossiers/<pid_hex>/*.toml`.
4. Update `spec/evidence_index.csv` and command/pid matrices.
5. Keep device as `candidate-readonly` until full 3-signal promotion gate is met.
## Maintainer Flow
1. validate the report format
2. map it to a known PID or create a new sanitized record
3. update the relevant spec or dossier artifacts
4. keep the device read-only until runtime and hardware confirmation justify promotion

59
process/device_name_sources.md
View File

@@ -1,33 +1,38 @@
# Device Name Sources
This index lists sanitized naming sources used to build `/Users/brooklyn/data/8bitdo/cleanroom/spec/device_name_catalog.md`.
This index explains where canonical device names came from and how confident the project is in them.
## Primary dirty-room references
- `DR-1`: Decompiled PID constants table (`VIDPID`) in `/Users/brooklyn/data/8bitdo/decompiled_dll/8BitDo_Ultimate_Software_V2.decompiled.cs` around line 194289.
- `DR-2`: Decompiled device name resolver (`getName()`) in `/Users/brooklyn/data/8bitdo/decompiled_dll/8BitDo_Ultimate_Software_V2.decompiled.cs` around line 12249.
- `DR-3`: Decompiled language map (`LanguageTools`) in `/Users/brooklyn/data/8bitdo/decompiled_dll/8BitDo_Ultimate_Software_V2.decompiled.cs` around line 206277.
## Source Classes
## Official 8BitDo web cross-check references
- `WEB-1`: [8BitDo product catalog](https://www.8bitdo.com/#Products)
- `WEB-2`: [Ultimate 2 Wireless Controller](https://www.8bitdo.com/ultimate-2-wireless-controller/)
- `WEB-3`: [Ultimate 2 Bluetooth Controller](https://www.8bitdo.com/ultimate-2-bluetooth-controller/)
- `WEB-4`: [Ultimate 2C Wireless Controller](https://www.8bitdo.com/ultimate-2c-wireless-controller/)
- `WEB-5`: [Ultimate 2C Bluetooth Controller](https://www.8bitdo.com/ultimate-2c-bluetooth-controller/)
- `WEB-6`: [Pro 2 Bluetooth Controller](https://www.8bitdo.com/pro2/)
- `WEB-7`: [Retro 108 Mechanical Keyboard](https://www.8bitdo.com/retro-108-mechanical-keyboard/)
- `WEB-8`: [Retro 87 Mechanical Keyboard - Xbox Edition](https://www.8bitdo.com/retro-87-mechanical-keyboard-xbox/)
- `WEB-9`: [Retro R8 Mouse - Xbox Edition](https://www.8bitdo.com/retro-r8-mouse-xbox/)
- `WEB-10`: [Arcade Controller](https://www.8bitdo.com/arcade-controller/)
- `WEB-11`: [64 Bluetooth Controller](https://www.8bitdo.com/64-controller/)
- `WEB-12`: [Retro Mechanical Keyboard N Edition](https://www.8bitdo.com/retro-mechanical-keyboard/)
- sanitized dirty-room references from internal naming tables
- official 8BitDo product pages
- project-maintained fallback names when neither source is strong enough for a public label
## Confidence policy
- `high`: direct match in `DR-2/DR-3` and/or product page exact-name match.
- `medium`: strong inferred match from product family naming with at least one source anchor.
- `low`: internal fallback name because no confident public marketing name was found.
## Confidence Policy
## Low-confidence naming convention
- Canonical wording for low-confidence rows is:
- `Unconfirmed Internal Device (PID_*)`
- `Unconfirmed Variant Name (PID_*)`
- `Unconfirmed Interface Name (PID_*)`
- `high`: exact or near-exact public confirmation
- `medium`: strong inferred match from family and naming context
- `low`: fallback wording kept intentionally conservative
## Low-Confidence Naming Convention
Use conservative labels such as:
- `Unconfirmed Internal Device (...)`
- `Unconfirmed Variant Name (...)`
- `Unconfirmed Interface Name (...)`
## Current Official Cross-Checks
- [8BitDo product catalog](https://www.8bitdo.com/#Products)
- [Ultimate 2 Wireless Controller](https://www.8bitdo.com/ultimate-2-wireless-controller/)
- [Ultimate 2 Bluetooth Controller](https://www.8bitdo.com/ultimate-2-bluetooth-controller/)
- [Ultimate 2C Wireless Controller](https://www.8bitdo.com/ultimate-2c-wireless-controller/)
- [Ultimate 2C Bluetooth Controller](https://www.8bitdo.com/ultimate-2c-bluetooth-controller/)
- [Pro 2 Bluetooth Controller](https://www.8bitdo.com/pro2/)
- [Retro 108 Mechanical Keyboard](https://www.8bitdo.com/retro-108-mechanical-keyboard/)
- [Retro 87 Mechanical Keyboard - Xbox Edition](https://www.8bitdo.com/retro-87-mechanical-keyboard-xbox/)
- [Retro R8 Mouse - Xbox Edition](https://www.8bitdo.com/retro-r8-mouse-xbox/)
- [Arcade Controller](https://www.8bitdo.com/arcade-controller/)
- [64 Bluetooth Controller](https://www.8bitdo.com/64-controller/)
- [Retro Mechanical Keyboard N Edition](https://www.8bitdo.com/retro-mechanical-keyboard/)

78
process/dirtyroom_collection_playbook.md
View File

@@ -1,60 +1,40 @@
# Dirty-Room Collection Playbook (Decompiler-First Expansion)
# Dirty-Room Collection Playbook
This playbook describes how dirty-room evidence is gathered and sanitized before the clean-room implementation consumes it.
## Goal
Create sanitized, requirement-linked evidence that expands device detect/diagnostics support without contaminating clean-room implementation.
## Scope of This Wave
- Evidence source: decompiler/static-only.
- Target: Wave 2 +12 popularity cohort (plus previously tracked candidate-readonly set).
- Promotion policy: no new `full` promotions in this wave.
- Output artifacts: `spec/dossiers/**`, `spec/evidence_index.csv`, updated `spec/*.csv`, updated `requirements.yaml`.
Produce sanitized, requirement-linked evidence that can expand detect, diagnostics, mapping, or firmware understanding without copying vendor material into the runtime.
## Allowed Dirty-Room Inputs
- `/Users/brooklyn/data/8bitdo/decompiled_dll/8BitDo_Ultimate_Software_V2.decompiled.cs`
- `/Users/brooklyn/data/8bitdo/decompiled/*.cs`
- `/Users/brooklyn/data/8bitdo/decompiled_autoupdate/*.cs`
- Existing dirty-room transcript files under `/Users/brooklyn/data/8bitdo/`
## Allowed Inputs
## Required Sanitization Rules
- Do not copy raw vendor/decompiled code snippets into clean artifacts.
- Record only sanitized structure-level findings:
- command intent
- request/response byte-shape
- validator expectations
- gating/policy notes
- Use requirement IDs only (`REQ-DR-*`, `REQ-PROM-*`, `REQ-COMM-*`, `REQ-GH-*`).
- approved decompiler outputs and existing dirty-room transcripts
- official public web pages used for naming or marketing confirmation
## Required Sanitization
Record only structure-level findings:
- command intent
- request and response shape
- validator expectations
- retry or failure behavior
- promotion or safety notes
Do not copy vendor code or raw proprietary snippets.
## Dossier Workflow
1. Pick PID and operation group.
2. Collect static evidence anchors (class/function names and behavior summaries).
3. Derive sanitized command mapping and validation expectations.
4. Write TOML dossier in `spec/dossiers/<pid_hex>/<operation_group>.toml`.
5. Link dossier ID into `spec/command_matrix.csv` (`dossier_id` column).
6. Update `spec/evidence_index.csv`.
7. Ensure each Wave 2 PID has all three required dossier files:
- `core_diag.toml`
- `mode_or_profile_read.toml`
- `firmware_preflight.toml`
## Authoring Approach (No Helper Scripts)
- Dossiers and matrix updates are maintained directly in repository source files.
- `spec/evidence_index.csv` is updated manually with deterministic ordering.
- Validation is performed through normal repository review plus workspace tests.
1. choose a PID and operation group
2. collect anchors and summarize them
3. create or update the sanitized dossier
4. link the dossier from the relevant matrix rows
5. update evidence indexes and notes
## Confidence Rules
- `confirmed`: requires static + runtime + hardware confirmation (not achievable in this wave).
- `inferred`: static-only or partial confidence.
- For this wave, new entries should remain `inferred` unless already confirmed historically.
## Promotion Rule
## Promotion Gate
A device can move from `candidate-readonly` to `full` only when all three are true:
1. static evidence complete
2. runtime trace evidence complete
3. hardware read/write/readback complete
Moving from `read-only candidate` to `supported` requires:
## Review Checklist
- Dossier contains required fields from schema.
- Requirement linkage is explicit.
- No raw decompiled text/snippets are present.
- `support_tier` remains `candidate-readonly` for new no-hardware devices.
- Runtime and hardware placeholders are populated with concrete promotion evidence tasks.
1. static evidence
2. runtime traces
3. hardware confirmation

68
process/dirtyroom_dossier_schema.md
View File

@@ -1,56 +1,30 @@
# Dirty-Room Dossier Schema
Each dossier file is TOML and must include these fields.
Each dossier is a TOML file that captures sanitized protocol evidence for one PID and one operation group.
## Required Fields
- `dossier_id`: stable identifier, e.g. `DOS-5200-CORE`.
- `pid_hex`: target PID in hex (`0xNNNN`).
- `operation_group`: logical grouping (`CoreDiag`, `ModeProfileRead`, `FirmwarePreflight`, etc).
- `command_id`: array of command IDs scoped by this dossier.
- `request_shape`: sanitized request structure summary.
- `response_shape`: sanitized response structure summary.
- `validator_rules`: array of response validation constraints.
- `retry_behavior`: retry and timeout behavior summary.
- `failure_signatures`: array of known failure signatures.
- `evidence_source`: `static` for this wave.
- `confidence`: `inferred` or `confirmed`.
- `requirement_ids`: array of linked requirement IDs.
- `state_machine`: table with `pre_state`, `action`, `post_state`, and `invalid_transitions`.
- `runtime_placeholder`: table with `required` and `evidence_needed`.
- `hardware_placeholder`: table with `required` and `evidence_needed`.
- `dossier_id`
- `pid_hex`
- `operation_group`
- `command_id`
- `request_shape`
- `response_shape`
- `validator_rules`
- `retry_behavior`
- `failure_signatures`
- `evidence_source`
- `confidence`
- `requirement_ids`
- `state_machine`
- `runtime_placeholder`
- `hardware_placeholder`
## Optional Fields
- `class_family`: static class-family grouping hints.
- `notes`: additional sanitized context.
## Example
```toml
dossier_id = "DOS-5200-CORE"
pid_hex = "0x5200"
operation_group = "CoreDiag"
command_id = ["GetPid", "GetReportRevision", "GetControllerVersion", "Version", "Idle"]
request_shape = "64-byte HID report, command byte in report[1], PID-specific gating outside payload"
response_shape = "short status header plus optional payload bytes"
validator_rules = ["byte0 == 0x02", "response length >= 4"]
retry_behavior = "retry up to configured max attempts on timeout/malformed response"
failure_signatures = ["timeout", "malformed response", "unsupported command for pid"]
evidence_source = "static"
confidence = "inferred"
requirement_ids = ["REQ-DR-001", "REQ-PROM-001", "REQ-PID-002"]
class_family = "JP/Handshake path"
notes = "candidate-readonly in this wave"
- `class_family`
- `notes`
[state_machine]
pre_state = "DeviceConnected"
action = "Run core diagnostics reads"
post_state = "DeviceIdentified"
invalid_transitions = ["NoDevice", "TransportClosed", "BootloaderOnly"]
## Authoring Rule
[runtime_placeholder]
required = true
evidence_needed = ["runtime request/response captures", "error signature examples"]
[hardware_placeholder]
required = true
evidence_needed = ["physical read validation", "repeatability checks"]
```
Prefer short, structure-level descriptions over long prose. The dossier should be good enough to guide clean implementation and testing without embedding dirty-room source text.

56
process/dirtyroom_evidence_backlog.md
View File

@@ -1,50 +1,18 @@
# Dirty-Room Evidence Backlog
## Purpose
This backlog tracks the next protocol-evidence areas that would most improve runtime confidence.
Track future dirty-room evidence work for protocol expansion in a structured way, so new functionality can be translated into sanitized clean-room specs without contaminating implementation code.
## Priority Areas
## Clean-Room Boundaries
1. read-only candidate expansion for additional controller families
2. deeper JP108 mapping confirmation
3. deeper Ultimate 2 profile and slot behavior confirmation
4. firmware trace and recovery evidence across supported devices
5. runtime and hardware evidence needed to promote candidate devices
- Dirty-room analysis may use approved evidence sources.
- Clean implementation must consume only sanitized artifacts in `spec/` and approved harness data.
- No raw dirty-room snippets, copied code, or direct decompiled fragments may be carried into clean implementation files.
## Expected Outputs
## Prioritized Backlog
1. Wave-2 candidate-readonly expansion (decompiler-first):
- Popularity +12 PIDs:
- `0x3100`, `0x3105`, `0x2100`, `0x2101`, `0x901a`, `0x6006`
- `0x5203`, `0x5204`, `0x301a`, `0x9028`, `0x3026`, `0x3027`
- Deliverable posture: detect/diag-only (`candidate-readonly`), no firmware transfer/write promotion.
2. Wave-1 candidate-readonly follow-through:
- Primary 14 PIDs:
- `0x6002`, `0x6003`, `0x3010`, `0x3011`, `0x3012`, `0x3013`
- `0x5200`, `0x5201`, `0x203a`, `0x2049`, `0x2028`, `0x202e`
- `0x3004`, `0x3019`
- Stretch PIDs:
- `0x3021`, `0x2039`, `0x2056`, `0x5205`, `0x5206`
- Deliverable posture: stay candidate-readonly until runtime and hardware evidence is accepted.
3. JP108 deeper mapping coverage:
- Expand dedicated key mapping confirmation beyond the current A/B/K1-K8 baseline.
- Confirm feature and voice command behavior with stronger request/response confidence.
4. Ultimate2 advanced paths:
- Expand confidence for advanced slot/config interactions and additional profile behaviors.
- Confirm edge cases for mode transitions and per-slot persistence.
5. Firmware trace confidence:
- Increase confidence for bootloader enter/chunk/commit/exit behavior across supported target variants.
- Capture and sanitize additional failure and recovery traces.
## Required Sanitized Outputs
- Update `spec/protocol_spec.md` for any newly confirmed operation groups or behavior rules.
- Update `spec/requirements.yaml` with new stable requirement IDs.
- Update `spec/command_matrix.csv` and `spec/pid_matrix.csv` as evidence confidence changes.
- Add or refresh sanitized harness fixtures under `harness/golden/` for replay and regression tests.
## Review Checklist Before Clean Implementation
- Sanitized evidence is traceable to requirement IDs.
- Command confidence levels are explicit (`confirmed` vs `inferred`).
- PID capability changes are reflected in matrices.
- No raw-source text is present in clean implementation artifacts.
- updated spec and requirement references
- refreshed command and PID matrices
- sanitized dossier updates
- optional harness fixtures where they improve regression coverage

26
process/wave1_baseline.md
View File

@@ -1,23 +1,15 @@
# Wave 1 Baseline Snapshot
Generated: 2026-02-28
Generated on 2026-02-28.
## Hardware Access Baseline
- Available hardware lines: JP108 + Ultimate2.
- Exact attached PID variants: pending local identify run on connected hardware.
- Temporary lab fixture defaults remain:
- JP108: `0x5209`
- Ultimate2: `0x6012`
## Baseline
## Required Next Verification Step
Run identify flow with connected hardware and confirm fixture PIDs:
1. `cargo test --workspace --test hardware_smoke -- --ignored --exact hardware_smoke_detect_devices`
2. `./scripts/run_hardware_smoke.sh` with `BITDO_REQUIRED_SUITE=108jp`
3. `./scripts/run_hardware_smoke.sh` with `BITDO_REQUIRED_SUITE=ultimate2`
- owned fixture families: JP108 and Ultimate 2
- existing supported paths were limited to hardware-confirmed devices
- newly expanded devices were intentionally kept read-only
If detected variants differ, update `harness/lab/device_lab.yaml` fixture PIDs immediately.
## Expected Follow-Up
## Support Baseline
- Existing `full` paths: JP108/Ultimate2 and previously confirmed families.
- New expansion wave devices remain `candidate-readonly` (detect/diag only).
- No new firmware/write enablement for no-hardware targets.
- capture runtime traces
- confirm real hardware behavior
- promote devices only after static, runtime, and hardware evidence align

26
process/wave1_results.md
View File

@@ -1,23 +1,9 @@
# Wave 1 Results (Template)
# Wave 1 Results
Generated: 2026-02-28
Generated on 2026-02-28.
## Summary
- Primary target PIDs processed: 14
- Stretch target PIDs processed: TBD
- New `full` promotions: 0 (expected in decompiler-only wave)
## Outcome
## Deliverables
- Dossiers created: `spec/dossiers/**`
- Evidence index updated: `spec/evidence_index.csv`
- Matrices updated: `spec/pid_matrix.csv`, `spec/command_matrix.csv`
- Requirements updated: `spec/requirements.yaml`
## Validation
- `cargo test --workspace --all-targets`: pending
- `./scripts/cleanroom_guard.sh`: pending
- Detect/diag targeted tests: pending
## Follow-Up
- Collect runtime traces for candidate-readonly devices.
- Run hardware confirmation on each candidate before promotion to `full`.
- Wave 1 produced sanitized evidence and candidate-readonly expansion work.
- No new device families were promoted directly to full support.
- Follow-up work remained runtime traces and hardware confirmation.

39
process/wave2_baseline.md
View File

@@ -1,32 +1,17 @@
# Wave 2 Baseline (Frozen)
# Wave 2 Baseline
## Snapshot Date
- 2026-03-01
Snapshot date: 2026-03-01.
## Pre-Wave Counts (Frozen)
- `spec/pid_matrix.csv` rows: 59
- Support tier counts (pre-wave):
- `full`: 14
- `candidate-readonly`: 15
- `detect-only`: 30
- `spec/command_matrix.csv` rows (pre-wave): 37
## Baseline Assumptions
## Hardware Reality (Current)
- Available fixtures: JP108 line and Ultimate2 line only.
- Non-owned devices must remain `candidate-readonly` until strict promotion signals are complete.
## Required Checks Baseline
Branch protection for `main` must require:
- `guard`
- `aur-validate`
- `tui-smoke-test`
- `build-macos-arm64`
- `test`
- `hardware-108jp`
- `hardware-ultimate2`
- hardware ownership still covered only the JP108 and Ultimate 2 lines
- newly researched PIDs had to remain read-only until confirmation improved
- release gates stayed anchored on `guard`, `aur-validate`, `tui-smoke-test`, `build-macos-arm64`, and `test`
## Promotion Policy
Promotion from `candidate-readonly` to `full` requires all 3 signals:
1. static dossier evidence,
2. runtime sanitized traces,
3. hardware read/write/readback confirmation.
Promotion from `read-only candidate` to `supported` requires:
1. static evidence
2. runtime evidence
3. hardware evidence

35
process/wave2_pid_scorecard.md
View File

@@ -1,22 +1,23 @@
# Wave 2 PID Scorecard
Legend:
- Static: dossier + matrix linkage complete.
- Runtime: sanitized runtime traces accepted.
- Hardware: read/write/readback confirmed on owned fixture.
- Gate: promotion blocker status.
- `Static`: dossier and matrix linkage complete
- `Runtime`: sanitized runtime traces accepted
- `Hardware`: real-device confirmation accepted
- `Gate`: reason promotion remains blocked
| PID | Device | Tier | Static | Runtime | Hardware | Gate |
|---|---|---|---|---|---|---|
| `0x3100` | PID_USB_Ultimate | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x3105` | PID_USB_Ultimate2 | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x2100` | PID_Xcloud | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x2101` | PID_Xcloud2 | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x901a` | PID_ArcadeStick | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x6006` | PID_Pro2_CY | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x5203` | PID_NUMPAD | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x5204` | PID_NUMPADRR | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x301a` | PID_UltimateBT2C | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x9028` | PID_N64RR | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x3026` | PID_XBOXUK | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x3027` | PID_XBOXUKUSB | candidate-readonly | yes | no | no | blocked/no_runtime |
| --- | --- | --- | --- | --- | --- | --- |
| `0x3100` | `PID_USB_Ultimate` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x3105` | `PID_USB_Ultimate2` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x2100` | `PID_Xcloud` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x2101` | `PID_Xcloud2` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x901a` | `PID_ArcadeStick` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x6006` | `PID_Pro2_CY` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x5203` | `PID_NUMPAD` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x5204` | `PID_NUMPADRR` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x301a` | `PID_UltimateBT2C` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x9028` | `PID_N64RR` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x3026` | `PID_XBOXUK` | read-only candidate | yes | no | no | blocked/no_runtime |
| `0x3027` | `PID_XBOXUKUSB` | read-only candidate | yes | no | no | blocked/no_runtime |

32
process/wave2_results.md
View File

@@ -1,23 +1,19 @@
# Wave 2 Results
## Scope
- Expansion cohort: 12 additional popularity-first PIDs.
- Evidence mode: static/decompiler-only.
- Support result: all 12 moved to `candidate-readonly` with detect/diag-only behavior.
## Outcome
## Delivered
1. Manual, source-controlled dossier and matrix updates (no script-generated artifacts).
2. Wave 2 dossier set (`core_diag`, `mode_or_profile_read`, `firmware_preflight`) for each of 12 PIDs.
3. `pid_matrix.csv` updated with Wave 2 candidate-readonly tiering.
4. `command_matrix.csv` updated with Wave 2 dossier-linked rows and explicit promotion gates.
5. `evidence_index.csv` updated from current candidate-readonly set.
6. Governance verification completed for variables, labels, and required checks.
- twelve additional PIDs were expanded through sanitized static evidence
- all twelve remained read-only candidates
- no new family was promoted without runtime and hardware confirmation
## Deferred
- Runtime trace evidence for Wave 2 cohort.
- Hardware read/write/readback confirmation for Wave 2 cohort.
- Any promotion to `full` for Wave 2 cohort.
## Deliverables
## Exit Status
- Wave 2 static-only deliverables: complete.
- Promotion status: blocked pending runtime + hardware signals.
- updated dossiers and matrices
- refreshed evidence index
- governance and release-gate verification
## Deferred Work
- runtime traces
- hardware confirmation
- any promotion to full support

46
process/wave2_runtime_intake.md
View File

@@ -1,38 +1,22 @@
# Wave 2 Runtime/Hardware Intake (Prepared, Deferred)
# Wave 2 Runtime Intake
## Purpose
Define exactly what sanitized runtime/hardware evidence is needed to move Wave 2 devices beyond static-only dossiers.
This note describes the evidence still needed to move Wave 2 devices beyond static-only confidence.
## Required Submission Data
Every submission must include:
1. VID/PID in hex.
2. Firmware version.
3. Operation attempted.
4. Sanitized request structure.
5. Sanitized response structure.
6. Reproducibility notes (OS, transport, retries, success/failure rate).
## Sanitization Rules
Allowed content:
- byte-layout summaries,
- command/response shape descriptions,
- validation predicates,
- timing/retry observations.
1. VID/PID
2. firmware version
3. operation attempted
4. sanitized request structure
5. sanitized response structure
6. reproducibility notes
Forbidden content:
- raw decompiled code snippets,
- copied vendor constants blocks,
- copied source fragments from official binaries/tools.
## Acceptance Rules
## Evidence Acceptance Checklist
1. VID/PID and firmware fields are present.
2. Request/response structure is sanitized and technically complete.
3. Failure signatures are mapped to stable categories (`timeout`, `malformed`, `unsupported`, `invalid_signature`).
4. Repro steps are clear enough for independent rerun.
5. No forbidden raw-source content appears.
- no copied vendor code or decompiled snippets
- failure signatures must map to stable categories
- the report must be repeatable enough for an independent rerun
## Promotion Readiness Mapping
A PID is promotion-eligible only when all are true:
1. Static dossiers complete.
2. Runtime traces accepted from at least 2 independent runs.
3. Hardware read/write/readback validation passes on owned fixture(s).
## Promotion Readiness
A PID is promotion-ready only when static, runtime, and hardware evidence all exist together.