tools/driver-lab/SPEC.md - fuchsia - Git at Google


            
            <!-- Copyright 2026 The Fuchsia Authors. All rights reserved.

            
            Use of this source code is governed by a BSD-style license that can be

            
            found in the LICENSE file. -->


            # driver-lab host tooling specification


            This is the normative specification for the driver-lab host tooling at

            
            //tools/driver-lab. The companion proxy driver specification lives at

            
            //src/devices/driver-lab/SPEC.md.


            Phase 1 -- the unclaimed-node proxy workflow, which requires no Driver Manager

            
            changes -- is delivered first. Phase 2 -- in-situ driver debugging via an

            
            embedded library -- extends host tooling to active, bound drivers without

            
            managed takeover or Driver Manager changes, requiring no major contract change.

            
            Phase 3 -- software state, runtime knobs, and adaptive bug verification --

            
            extends host plans, the Python API, and agent skills to drive single-build

            
            software state and concurrency experiments over `StateBank` resources.


            ## Phase 1: unclaimed-node proxy workflow


            ### Implementation status


            Changeset numbers (CS) are global across this specification and

            
            `//src/devices/driver-lab/SPEC.md`, whose changesets interleave with

            
            these; gaps in the numbering below are proxy driver changesets. Every

            
            changeset marks itself complete in this list when it lands, so at any

            
            commit this list shows which changes precede and which follow that

            
            commit.


            - [x] CS2 `[driver-lab] Host tooling specification` -- this

            
                  document.

            
            - [x] CS4 `[driver-lab] Transport-neutral host tooling core` --

            
                  frozen data models (18), grant resolution with the TOML store

            
                  (10.3-10.5), and plan validation, canonicalization, and digests

            
                  carrying the reserved takeover keys (11).

            
            - [x] CS5 `[driver-lab] Evidence recording + proxy transport

            
                  abstraction` -- hashed manifest-last evidence bundles (16) and

            
                  the wire-contract-shaped transport seam with the fake proxy

            
                  target (12, 20.3).

            
            - [x] CS6 `[driver-lab] Consent resolution and the plan-run API` --

            
                  interactive consent with exact-rule persistence and fail-closed

            
                  unattended behavior (10.2), and `DriverLab.run_plan` composing

            
                  prepare/execute/finalize with mode and guarantee resolution

            
                  before any connection (6.2, 7.3, 14).

            
            - [x] CS7 `[driver-lab] fuchsia-controller FIDL transport adapter`

            
                  -- `ProxyTransport` over the generated bindings, exercised

            
                  through real FIDL encoding on the build host (12, 20.3).

            
            - [x] CS8 `[driver-lab] Add host CLI tools` -- `driver-lab.pyz`

            
                  with run, permissions list/explain/add/revoke, plan

            
                  digest/validate, and spec exit categories (10.5, 12, 13).

            
            - [x] CS10 `[driver-lab] Add live-target conformance runbook` --

            
                  ephemeral registration and test-node activation exercising the

            
                  real driver end to end (14, 20.4), verified on the emulator.

            
            - [x] CS11 `[driver-lab] Host node discovery via fuchsia.driver.development`

            
                  -- typed node enumeration, bound driver inspection, unclaimed-node

            
                  detection over FIDL, and expected_unclaimed plan verification (7.1,

            
                  8.3, 14.2, 15; milestones H0, H1).

            
            - [x] CS12 `[driver-lab] Direct mode client and published-protocol workflow`

            
                  -- direct-mode capability validation, typed protocol discovery,

            
                  protocol transactions, and target audit exclusion (7.1, 8.2, 15;

            
                  milestone H1).

            
            - [x] CS13 `[driver-lab] Target ceiling policy manifests and verification`

            
                  -- immutable target ceiling manifests, canonical JSON and deterministic

            
                  SHA-256 digests, non-widening narrowing validation, and one-shot vs poll

            
                  enforcement (9.2, 9.6, 22, 23.1; milestone P1 remainder).


            Remaining phase 1 work:


            - [x] CS14 `[driver-lab] Bounded sequences and mutation in proxy driver`

            
                  (11.4, 11.5, 12.2-12.4, 13; milestone P3).

            
            - [x] CS15 `[driver-lab] Host tooling support for mutation and sequences`

            
                  (11, 14; milestone P3 / H4).

            
            - [x] CS16 `[driver-lab] Driver-shaped public Python API` -- `connect`/`attach`,

            
                  `HardwareSession`, `MmioRegion`, and representative protocol resources

            
                  (6.1, 9; milestone H4).

            
            - [x] CS17 `[driver-lab] Stop-path hardening and cancellation` (19; milestone P2).

            
            - [x] CS18 `[driver-lab] Host CLI subtool expansion and verified teardown`

            
                  (8.3, 12, 14.2; milestone H3 remainder).

            
            - [x] CS19 `[driver-lab] Protocol resources, typed endpoints, and heterogeneous sequence`

            
                  (8.1, 8.4, 9.5, 11.5, 11.6, 12, 14.2; milestone P4).

            
            - [ ] Engineering assembly inclusion and production-absence verification

            
                  (7.1, 25).

            
            - [x] CS20 `[driver-lab] Interrupt observation and local acknowledgement`

            
                  (11.7, 17; milestone P5).

            
            - [x] CS21 `[driver-lab] Structured configuration and per-class rate limits`

            
                  (in //src/devices/driver-lab/SPEC.md).

            
            - [x] CS22 `[driver-lab] Serial capture and independent recovery integration`

            
                  (3, 14.1; milestone H5).

            
            - [ ] Register-metadata-backed consent expansion (10.2; open decision 8).


            Phase: 1 -- new-driver development. Covers direct mode and proxy access on

            
            unclaimed nodes. In-situ debugging of existing drivers via an embedded library

            
            is specified in the Phase 2 section of this document and in

            
            //src/devices/driver-lab/SPEC.md, and requires no changes to this contract.


            Scope: host Python API, `ffx` integration, operator authorization, orchestration,

            
            and evidence


            Companion specifications: the proxy driver specification at

            
            //src/devices/driver-lab/SPEC.md, and the Phase 2 section of this document


            ### 1. Purpose


            The host tooling provides a single, driver-shaped Python programming model for

            
            interactive hardware exploration and agent-assisted Fuchsia driver

            
            development. The same entry point supports two target access modes:


            1. direct use of protocols already published by a running driver; and

            
            2. private-resource access through an engineering-only proxy driver.


            In phase 1 the proxy binds directly to an otherwise unclaimed development

            
            node. In-situ debugging of existing, active drivers through an embedded

            
            library is specified in phase 2; the wire and transport contracts here

            
            support both deployment paths without breaking changes.


            The tooling also exposes an `ffx` interface, coordinates out-of-band recovery,

            
            enforces operator-consent policy, freezes executable plans, and preserves the

            
            raw evidence needed to reproduce and audit an experiment.


            This specification deliberately does not define how the proxy maps MMIO,

            
            handles interrupts, or enforces its target-side policy. Those requirements are

            
            owned by the proxy driver specification at //src/devices/driver-lab/SPEC.md.


            ### 2. Normative language


            The terms **must**, **must not**, **should**, and **may** describe requirements,

            
            recommendations, and optional behavior respectively.


            The following terms have specific meanings:


            - **Direct mode:** The host connects to a FIDL protocol already published by

            
              the running driver. The driver remains bound and active.

            
            - **Proxy mode:** The host connects to the isolated proxy driver for private,

            
              policy-controlled target resources. In phase 1 the node is an unclaimed

            
              development node.

            
            - **In-situ debugging:** Connecting directly to an active driver's embedded

            
              driver-lab endpoint for live hardware exploration without unbinding or

            
              quiescing device state. Defined in the Phase 2 section of this document and

            
              in //src/devices/driver-lab/SPEC.md.

            
            - **Target ceiling:** Immutable target-side limits on resources and operations.

            
              Host approval can narrow this ceiling but cannot widen it.

            
            - **Read grant:** Operator authorization for a particular class of register

            
              reads.

            
            - **Plan:** Canonical, bounded experiment intent whose digest changes whenever

            
              any executable field changes.

            
            - **Evidence:** Raw requests, responses, target identity, audit records,

            
              transport events, recovery events, and serial output saved before

            
              interpretation.


            ### 3. Goals


            The host tooling must:


            1. Reach a target control plane served by Driver Manager in the bootstrap

            
               realm, with no dependency on a component in the `core` realm for the

            
               target-side endpoint.

            
            2. Be reachable through supported `ffx` target transports without precluding

            
               a serial-capable transport; serial support itself is separate

            
               `ffx`-team-owned work and does not gate phase 1.

            
            3. Present one typed asynchronous Python API across direct and proxy modes.

            
            4. Preserve the production-driver abstractions used for MMIO, GPIO, SPI, I2C,

            
               serial, clock, reset, and interrupt access.

            
            5. Discover target nodes, bound drivers, and published protocols through the

            
               existing `fuchsia.driver.development` surface rather than a parallel

            
               discovery protocol.

            
            6. Make backend capabilities and safety guarantees visible to callers.

            
            7. Never silently replace a policy-controlled operation with a weaker direct

            
               operation.

            
            8. Require operator authorization for previously unapproved register reads.

            
            9. Persist an exact read grant when the operator chooses "always allow."

            
            10. Fail closed in unattended operation when a required grant is absent.

            
            11. Require explicit approval for mutating plans.

            
            12. Remain forward-compatible with phase 2 managed takeover: plan, session,

            
                and evidence schemas reserve the takeover fields so phase 2 requires no

            
                major contract change.

            
            13. Produce complete, hashed evidence for every attempted hardware run.

            
            14. Integrate with Driver Agent without combining proposal, approval,

            
                execution, and interpretation into one opaque step.

            
            15. Keep serial capture, reset, and power recovery independent of the in-band

            
                experiment transport.


            ### 4. Non-goals


            The host tooling must not:


            - expose arbitrary physical addresses;

            
            - claim that devfs or a published service reveals a driver's private MMIO,

            
              interrupt handles, or incoming namespace;

            
            - infer that every offset in an MMIO region is safe to read;

            
            - interpret a persistent host grant as a target security capability;

            
            - silently authorize an offset because a nearby offset was approved;

            
            - silently downgrade a requested access mode or guarantee;

            
            - automatically retry a mutating plan after a disconnect, reboot, or uncertain

            
              partial execution;

            
            - promise that stopping a production driver preserves its live hardware state;

            
            - execute arbitrary Python or shell expressions from a plan;

            
            - coordinate multiple device nodes in one plan or session (single-node only

            
              in V1);

            
            - guarantee sub-millisecond target-local timing precision;

            
            - provide a universal translation from every Python convenience to Rust or

            
              C++; or

            
            - require the embedded proxy library discussed in earlier designs.


            ### 5. Architecture


            ```text

            
            Driver Agent / Python script / human CLI

            
                                |

            
                                v

            
            Driver-shaped Python API and plan/evidence layer

            
                                |

            
                                v

            
            FFX transport adapter

            
              network / USB / serial-capable target transport

            
                                |

            
                                v

            
            Driver Manager control plane

            
              discovery: fuchsia.driver.development

            
              (takeover protocol arrives in phase 2)

            
                      |                           |

            
                      | direct                    | proxy

            
                      v                           v

            
            Published driver protocol       Isolated proxy driver

            
            running driver remains bound    bound to an unclaimed node


            Paniolo or equivalent --- serial / liveness / reset / power recovery

            
            ```


            The Driver Manager integration is a control plane. Hardware operations run in

            
            the production driver in direct mode or in the isolated proxy driver in proxy

            
            mode. Driver Manager must not become a generic MMIO executor.


            #### 5.1 Why there is no core broker


            The target endpoint must remain available on engineering systems whose normal

            
            component topology or networking is unavailable. Discovery and channel routing

            
            therefore belong at the Driver Framework/Driver Manager layer rather than at a

            
            stable moniker under `core`. This placement was suggested by driver-framework

            
            engineering during early design review.


            Two requirements are distinct here. The target-side control plane must not

            
            live under `core`; serving it from Driver Manager in the bootstrap realm

            
            satisfies that. End-to-end operation without `core` additionally requires a

            
            transport that terminates outside `core`; no such `ffx` transport exists

            
            today, so this design must not preclude one, and serial transport is tracked

            
            as separate work with the `ffx` team. The public Python API must not expose

            
            the transport choice.


            #### 5.2 Standalone proxy vs embedded library


            The standalone proxy (`lab_proxy`) is the Phase 1 mechanism for private hardware

            
            access on unclaimed nodes. For nodes with an active, bound driver, Phase 2

            
            introduces the embedded library (`driver_lab_rust` / `driver_lab_cpp`) for

            
            in-situ debugging. Rather than unbinding the driver, the embedded library preserves

            
            live hardware state and solves clock/power gating by running inside the active

            
            driver component, using cooperative quiesce locks and interrupt event taps to

            
            prevent concurrent interference.


            ### 6. Design invariants


            #### 6.1 Programming-model fidelity


            The public Python API must preserve, as closely as practical:


            - resource types;

            
            - production FIDL method boundaries;

            
            - MMIO access width and ordering;

            
            - asynchronous waits;

            
            - error propagation;

            
            - resource acquisition and lifetime;

            
            - explicit resets and state transitions; and

            
            - the distinction between semantic device protocols and raw registers.


            Discovery, transport, consent, target policy, batching, and evidence may be

            
            implemented underneath or alongside this API. They must not flatten every

            
            hardware resource into an unrelated generic remote-control interface.


            For protocol-backed resources, use generated Python FIDL types directly or a

            
            thin shape-preserving adapter. For MMIO, expose a remote `MmioRegion` object

            
            whose scalar operations resemble the MMIO operations used by an on-device

            
            driver. Target-local batches are an explicit timing and safety facility, not

            
            the only programming model.


            #### 6.2 Explicit capability degradation


            The host must report:


            - selected access mode;

            
            - resource-level capabilities;

            
            - target-policy enforcement;

            
            - target audit availability;

            
            - target-local timing availability;

            
            - fault-isolation level;

            
            - whether a production driver remains active; and

            
            - whether restoration will be required (always false until phase 2).


            Unsupported operations fail before hardware access. A direct-mode connection

            
            must not pretend that private MMIO, private interrupts, target audit, or

            
            target-local batch timing is available.


            #### 6.3 Evidence before interpretation


            Raw evidence is finalized before an agent may label an observation verified,

            
            contradicted, or inconclusive. Interpretation is a derived artifact and must

            
            refer back to exact operation results.


            #### 6.4 Independent recovery


            The experiment channel is not the recovery channel. Serial capture, target

            
            liveness, reset, and power control remain usable after loss of the FIDL or

            
            `ffx` path.


            ### 7. Access modes


            #### 7.1 Direct published-protocol mode


            Direct mode connects to a protocol already published by the active driver.

            
            Discovery may use an aggregated service, devfs compatibility path, or another

            
            Driver Manager-provided route, but those details are hidden below the public

            
            API.


            Direct mode is appropriate for:


            - black-box driver testing;

            
            - normal device configuration;

            
            - querying state exposed by the driver;

            
            - standard GPIO, SPI, I2C, serial, clock, or reset protocols;

            
            - an existing `fuchsia.hardware.registers` endpoint; and

            
            - low-risk ad-hoc exploration that does not require private resources.


            Direct mode does not provide private-register reflection. It provides only

            
            what the running driver publishes.


            #### 7.2 Proxy mode


            Proxy mode is appropriate when the caller needs:


            - MMIO owned privately by the production driver;

            
            - target-local polling or timing;

            
            - proxy target policy and audit;

            
            - proxy interrupt observation;

            
            - exclusive experimental ownership; or

            
            - an initialization sequence that precedes the production driver.


            In phase 1 the node must be unclaimed: the proxy binds through engineering-only

            
            node metadata and existing registration and bind mechanisms. If a normal

            
            driver is bound, the node requires managed takeover, which is phase 2 and is

            
            reported as unsupported. Either way the proxy backend must be compatible with

            
            the resources offered by the parent.


            #### 7.3 Selection rules


            The caller may request `direct`, `proxy`, or `auto`. A proxy request may also

            
            require a specific activation policy: `bind-unclaimed` (phase 1) or `takeover`

            
            (reserved; rejected as unsupported until phase 2).


            `auto` may select direct mode only when every plan requirement is satisfied by

            
            direct mode. It must never:


            - unbind a driver (takeover authorization does not exist until phase 2);

            
            - fall back from a required target policy to host-only validation;

            
            - fall back from target-local timing to host round trips;

            
            - convert private-resource intent into a semantically different public

            
              protocol call; or

            
            - downgrade a mutating plan.


            The selected mode and its guarantees are included in the canonical plan and

            
            evidence.


            ### 8. Target control-plane contract


            Discovery reuses the existing `fuchsia.driver.development` and

            
            `fuchsia.driver.registrar` protocols; this specification adds no parallel

            
            discovery surface and phase 1 requires no Driver Manager changes. The

            
            engineering-only takeover protocol is defined in the Phase 2 section of this

            
            document and in //src/devices/driver-lab/SPEC.md.

            
            The exact FIDL syntax is revision-dependent, but the semantics below are

            
            normative.


            #### 8.1 Node discovery


            Discovery uses `fuchsia.driver.development` (`GetNodeInfo`, `GetDriverInfo`,

            
            and related methods). Work package 1 produces a gap matrix mapping each

            
            required field to that surface in the selected revision. Discovery must

            
            provide:


            - stable node identity criteria (moniker and node properties, not per-boot

            
              numeric IDs);

            
            - bound driver URL and driver-host koid, if any; and

            
            - published protocol/service descriptors, composed from devfs or

            
              component-framework queries where `fuchsia.driver.development` does not

            
              report them directly.


            Boot identity, proxy generation, resource descriptions, and their digests are

            
            reported by the bound proxy's `Describe`, not by Driver Manager. Takeover

            
            eligibility, active proxy-access state, and pending restoration failure are

            
            reported by the phase 2 takeover protocol, not by node discovery.


            Physical addresses and raw handles are never returned.


            #### 8.2 Direct connection


            Direct mode connects only to a protocol that discovery reported. Phase 1 uses

            
            existing devfs or aggregated-service routing; the host tooling validates the

            
            typed protocol/service selector itself and never accepts an arbitrary path or

            
            component moniker from plan JSON. A typed Driver Manager route may be added

            
            later if selector validation proves insufficient.


            #### 8.3 Proxy activation on unclaimed nodes


            Phase 1 activates the proxy only on nodes with no bound driver:


            - the proxy is loaded through engineering assembly inclusion or ephemeral

            
              registration (`fuchsia.driver.registrar`);

            
            - eligibility comes from explicit engineering-only node metadata or a

            
              developer-created test node, never from broad bind rules;

            
            - before connecting, the host verifies the node identity criteria and that

            
              the bound driver is the expected proxy at the expected generation;

            
            - the host connects to the proxy's published service through existing devfs

            
              or aggregated-service routing, then correlates the endpoint back to stable

            
              node identity; and

            
            - ending access stops or unbinds the proxy and verifies the node is again

            
              unclaimed.


            The caller cannot select an arbitrary driver package. The managed-takeover

            
            activation path (`BeginProxyAccess`, `EndProxyAccess`, exclusive leases, and

            
            restoration) is specified in phase 2; phase 1 plans, sessions, and evidence

            
            reserve the fields those flows require.


            ### 9. Public Python API


            The illustrative API below fixes responsibilities, not final spelling:


            ```python

            
            class DriverLab:

            
                @classmethod

            
                async def connect(

            
                    cls,

            
                    target: str,

            
                    *,

            
                    transport: str = "auto",

            
                    timeout_s: float = 10.0,

            
                ) -> "DriverLab": ...


                async def list_nodes(self) -> list[NodeSummary]: ...

            
                async def describe_node(self, node_id: str) -> NodeDescription: ...


                async def attach(

            
                    self,

            
                    node_id: str,

            
                    *,

            
                    mode: Literal["auto", "direct", "proxy"],

            
                    requirements: AccessRequirements,

            
                    context: RunContext,

            
                ) -> "HardwareSession": ...


            class HardwareSession:

            
                @property

            
                def capabilities(self) -> SessionCapabilities: ...


                async def mmio(self, resource: str) -> "MmioRegion": ...

            
                async def gpio(self, resource: str) -> "Gpio": ...

            
                async def spi(self, resource: str) -> "Spi": ...

            
                async def i2c(self, resource: str) -> "I2c": ...

            
                async def serial(self, resource: str) -> "Serial": ...

            
                async def clock(self, resource: str) -> "Clock": ...

            
                async def reset(self, resource: str) -> "Reset": ...

            
                async def interrupt(self, resource: str) -> "Interrupt": ...

            
                async def sequence(self, operations: list[Operation]) -> ExecutionReport: ...


            class MmioRegion:

            
                async def read32(self, offset: int) -> int: ...

            
                async def write32(

            
                    self,

            
                    offset: int,

            
                    value: int,

            
                    *,

            
                    mask: int,

            
                    expected_before: int | None = None,

            
                    expected_mask: int | None = None,

            
                    require_readback: bool = True,

            
                ) -> WriteResult: ...


                async def poll32(

            
                    self,

            
                    offset: int,

            
                    *,

            
                    expected: int,

            
                    mask: int,

            
                    interval_s: float,

            
                    timeout_s: float,

            
                ) -> PollResult: ...

            
            ```


            `sequence` is available only when the selected backend can preserve the

            
            requested ordering and timing. Resource-specific methods remain the canonical

            
            programming model.


            #### 9.1 Translation metadata


            Each public hardware method should document:


            - its closest production C++ and Rust analogue;

            
            - whether it is directly translatable;

            
            - differences caused by remote execution;

            
            - whether it depends on target-local timing; and

            
            - whether it is an experiment-only convenience.


            A future translation checker may reject or flag scripts that use

            
            experiment-only facilities. Automatic translation is not required in the

            
            initial implementation.


            #### 9.2 Async behavior


            Use one asyncio event loop per process. All waits have host deadlines. Target

            
            deadlines must expire slightly before host deadlines so a normal target timeout

            
            can be distinguished from transport loss.


            Do not call blocking sleep from asynchronous code. Hold strong references to

            
            serial, health, evidence, and execution tasks until each has completed or been

            
            explicitly canceled and joined.


            ### 10. Operator authorization


            #### 10.1 Two independent layers


            Authorization has two layers:


            1. The target ceiling determines what the target can ever access.

            
            2. Host consent determines what the current operator or agent may request

            
               within that ceiling.


            A host grant never widens the target ceiling. A target accepting a

            
            session-specific allowlist does not prove who approved it; approval provenance

            
            is evidence, not cryptographic authorization.


            #### 10.2 Default read behavior


            An MMIO read that matches neither an active plan approval nor a persistent

            
            grant must pause for operator consent. In unattended operation it fails closed.

            
            For an unknown register, the active plan approval must itself contain an

            
            explicit human read decision; classifying a plan as read-only is not sufficient

            
            authorization.


            The interactive choices are:


            - **Allow once:** authorize the exact access rule for the current canonical

            
              plan or interactive session.

            
            - **Always allow:** persist the exact read rule.

            
            - **Deny once:** reject the request without changing persistent policy.

            
            - **Always deny:** persist a matching denial.


            The UI must warn that reads may clear status, consume FIFO data, acknowledge

            
            events, or fault when hardware dependencies are disabled.


            "Read all registers" is not a primitive permission:


            - when register metadata exists, the host expands the request into the exact

            
              declared readable offsets and resolves consent for each rule;

            
            - when only an MMIO byte range is known, the host must describe the action as a

            
              raw range sweep rather than pretending every aligned word is a register;

            
            - a raw range sweep requires an explicit human-approved plan enumerating every

            
              offset before execution; and

            
            - the initial implementation must not persist an "always allow this entire

            
              MMIO region" grant.


            The UI may approve an exact displayed set in one interaction, but the stored

            
            and target-enforced result remains a set of exact access rules.


            Consent gates register-class access regardless of transport. A direct-mode

            
            read through a published raw-register endpoint such as

            
            `fuchsia.hardware.registers` resolves against the same plan approvals and

            
            persistent grants as a proxy MMIO read. Semantic protocol operations (GPIO,

            
            SPI, I2C, serial, clock, reset) are governed by plan approval and target

            
            policy, not per-offset read consent.


            Register metadata is a first-class deliverable, not an ambient assumption:

            
            its schema, provenance, and review process must be specified before consent

            
            expansion depends on it (see open decisions).


            In V1 the proxy session allowlist is fixed when the session opens. Consent

            
            granted mid-session takes effect by closing the session and reopening it with

            
            the expanded allowlist; a narrowing-only `ExtendAllowlist` operation is a

            
            deferred open decision.


            Permission-resolution evidence records the source of every decision --

            
            persistent rule, allow-once, always-allow, deny-once, always-deny, or

            
            fail-closed -- so a run's authorization basis is auditable. A persistent

            
            deny short-circuits prompting for the rest of the plan.


            #### 10.3 Grant identity


            A persistent read grant must include:


            - grant schema version;

            
            - stable target/product scope;

            
            - stable node identity criteria;

            
            - resource-description digest;

            
            - logical resource name or ID;

            
            - byte offset;

            
            - width;

            
            - access class;

            
            - optional poll limits;

            
            - decision;

            
            - approval timestamp;

            
            - approval source or identity when available; and

            
            - optional rationale/reference.


            It must not match solely by nodename, boot ID, devfs path, or dynamic service

            
            instance.


            The resource-description digest covers the resource kind, logical size,

            
            provider identity, and any stable metadata needed to prevent an old grant from

            
            matching a changed mapping. A boot change alone need not invalidate a

            
            persistent read grant; a resource-description change does.


            #### 10.4 Access classes


            At minimum distinguish:


            - one-shot read;

            
            - bounded snapshot;

            
            - bounded poll;

            
            - write;

            
            - protocol transaction; and

            
            - interrupt wait.


            A one-shot read grant does not implicitly authorize polling. Poll authorization

            
            includes maximum interval frequency and timeout. All target-local execution

            
            remains subject to proxy limits.


            #### 10.5 Persistent configuration


            The persistent store is a checked, human-readable TOML file. For example:


            ```toml

            
            schema_version = 1


            [[read_grants]]

            
            target_scope = "example-engineering-target"

            
            node_id = "example-device"

            
            resource_digest = "sha256:..."

            
            resource = "control"

            
            offset = 0x3c

            
            width = 32

            
            access = "read_once"

            
            decision = "allow"

            
            approved_at = "2026-07-29T23:10:00Z"

            
            reason = "Reviewed against the device register specification"

            
            ```


            Interactive persistence must:


            1. lock against concurrent writers;

            
            2. parse and validate the existing file;

            
            3. reject ambiguous or overlapping entries;

            
            4. write a temporary file;

            
            5. flush and atomically replace the original;

            
            6. preserve a revision/audit record; and

            
            7. print the exact rule that was added.


            The CLI provides list, explain, add, and revoke operations. Manual config edits

            
            are allowed but undergo the same validation on load.


            #### 10.6 Writes


            Persistent read permission never authorizes a write. A mutating plan requires:


            - an explicit target write policy;

            
            - exact value and mask;

            
            - target/device expectations;

            
            - a precondition when semantics permit;

            
            - readback semantics;

            
            - bounded cleanup or recovery;

            
            - canonical plan approval; and

            
            - active recovery monitoring.


            The first implementation should not offer "always allow arbitrary write."


            ### 11. Probe plans


            Plans are data, not executable code. A representative plan is:


            ```json

            
            {

            
              "schema_version": 1,

            
              "run_id": "2026-07-29T23-10-00Z-status-read",

            
              "case_id": "device-status-observation",

            
              "target": {

            
                "selector": "lab-target",

            
                "expected_boot_id": "..."

            
              },

            
              "node": {

            
                "id": "example-device",

            
                "expected_unclaimed": true,

            
                "expected_resource_digest": "..."

            
              },

            
              "access": {

            
                "mode": "proxy",

            
                "activation": "bind-unclaimed",

            
                "requires_target_policy": true,

            
                "requires_target_audit": true,

            
                "requires_target_local_timing": false

            
              },

            
              "operations": [

            
                {

            
                  "kind": "mmio_read32",

            
                  "resource": "control",

            
                  "offset": "0x3c"

            
                }

            
              ]

            
            }

            
            ```


            The plan schema reserves the managed-takeover fields (expected bound driver,

            
            expected topology generation, expected proxy identity, restoration policy)

            
            for phase 2. For mutation the canonical plan records target policy digest,

            
            proxy generation, exact operation fields, and recovery intent.


            Plans must not support:


            - Python expressions;

            
            - shell interpolation;

            
            - arbitrary driver URLs;

            
            - arbitrary component monikers or protocol paths;

            
            - includes outside approved workspace roots; or

            
            - unvalidated plugins.


            Canonicalization normalizes numeric representations, key order, and operation

            
            order before hashing.


            ### 12. FFX tool and transport adapter


            The supported command surface should be available as an `ffx` subtool so that

            
            target discovery and transport selection remain in the Fuchsia tooling layer.

            
            Proposed commands:


            ```text

            
            ffx driver-lab list

            
            ffx driver-lab describe --node <id>

            
            ffx driver-lab direct --node <id> --protocol <typed-selector>

            
            ffx driver-lab bind-proxy --node <id>

            
            ffx driver-lab end-proxy --node <id>

            
            ffx driver-lab run --plan <json> --evidence-dir <dir>

            
            ffx driver-lab permissions list

            
            ffx driver-lab permissions explain --plan <json>

            
            ffx driver-lab permissions revoke --grant <id>

            
            ```


            `ffx driver-lab takeover` arrives in phase 2.


            The Python package links fuchsia-controller in process and uses the

            
            generated `fuchsia.driver.lab` bindings, behind a transport-neutral

            
            `ProxyTransport` interface so tests run against a wire-contract-faithful

            
            fake and future transports slot in without public API changes. Transport

            
            implementation must not leak into hardware scripts.


            Until the `ffx` subtool exists, the same operations ship as a standalone

            
            `driver-lab.pyz` host tool with JSON on stdout, diagnostics on stderr, and

            
            the exit categories below.


            A serial-capable path, once the separately tracked transport work lands, must

            
            be tested without the normal `core` topology before it is considered

            
            supported. It does not gate phase 1.


            ### 13. CLI behavior


            Structured results go to stdout and diagnostics/prompts go to stderr or the

            
            dedicated interactive UI channel.


            Recommended exit categories:


            ```text

            
            0  success

            
            2  local argument, plan, or permission error

            
            3  stale target/node/resource expectation

            
            4  operation failure or partial execution

            
            5  transport/channel failure

            
            6  target reboot or liveness failure

            
            7  evidence persistence failure

            
            8  proxy activation failure

            
            9  restoration failure (reserved; used by phase 2)

            
            10 unsupported capability or unsafe downgrade

            
            ```


            Ctrl-C cancels bounded execution, finalizes available evidence, and ends

            
            proxy access when one is active. A second interrupt may request out-of-band

            
            escalation but must not abandon proxy-access state silently.


            ### 14. Proxy-mode workflow


            The managed-takeover workflow is specified in phase 2. The phase 1

            
            unclaimed-node workflow is:


            #### 14.1 Prepare


            1. Discover the node and verify it is unclaimed.

            
            2. Capture boot, node, and resource identities.

            
            3. Confirm a compatible proxy is available.

            
            4. Resolve plan requirements.

            
            5. Resolve persistent read grants.

            
            6. Prompt for missing read consent.

            
            7. Require explicit mutation approval when applicable.

            
            8. Freeze and hash the canonical plan.

            
            9. Verify independent serial/recovery availability.


            Preparation performs no hardware operations.


            #### 14.2 Execute


            1. Create a non-reused evidence directory.

            
            2. Start serial and liveness capture.

            
            3. Activate the proxy on the unclaimed node with frozen expectations.

            
            4. Describe the bound proxy and verify its policy/resource digest.

            
            5. Open a session with an exact session allowlist.

            
            6. Execute the bounded plan, draining proxy audit after every mutating

            
               operation so the host record never runs more than one write ahead of

            
               drained target audit.

            
            7. Drain remaining proxy audit.

            
            8. Close the proxy session.

            
            9. End proxy access and verify the node is again unclaimed.

            
            10. Stop capture and finalize evidence.


            #### 14.3 Failure behavior


            - A stale expectation fails before activation.

            
            - Channel loss never causes automatic replay.

            
            - If a write may have completed, the result remains partial or unknown.

            
            - A reboot invalidates all boot-scoped expectations.

            
            - Recovery creates a new run context; it does not resume the old mutation.


            ### 15. Direct-mode workflow


            1. Discover a typed published protocol.

            
            2. Record the running driver identity and generation.

            
            3. Confirm the plan requires no private resources or takeover guarantees.

            
            4. Resolve any applicable host consent.

            
            5. Connect through Driver Manager's typed route.

            
            6. Execute production FIDL methods through generated or shape-preserving

            
               Python bindings.

            
            7. Save requests, responses, timing, and transport events.


            Target proxy policy and audit are absent unless the published protocol itself

            
            provides equivalent guarantees.


            ### 16. Evidence


            Each run gets a new directory:


            ```text

            
            evidence/<run_id>/

            
                manifest.json

            
                plan.requested.json

            
                plan.canonical.json

            
                approval.json

            
                permission-resolution.json

            
                target.description.json

            
                node.before.json

            
                access.capabilities.json

            
                proxy-access.jsonl

            
                execution.response.json

            
                operations.jsonl

            
                target-audit.jsonl

            
                node.after.json

            
                restoration.json

            
                serial.log

            
                host-events.jsonl

            
                interpretation.json

            
            ```


            Files that do not apply to a run are marked not applicable in the manifest

            
            rather than fabricated. `restoration.json` and the takeover entries of

            
            `proxy-access.jsonl` are reserved for phase 2 and marked not applicable in

            
            phase 1 runs.


            `manifest.json` contains:


            - evidence schema version;

            
            - run and case IDs;

            
            - canonical plan digest;

            
            - selected access mode and guarantees;

            
            - target boot/build/product identity;

            
            - node, driver, resource, proxy, and policy identities;

            
            - resolved grant IDs and approval source;

            
            - start and end wall-clock timestamps;

            
            - target monotonic range when available;

            
            - proxy-access outcome (takeover/restoration fields reserved for phase 2);

            
            - serial capture metadata;

            
            - terminal exit category;

            
            - audit-gap status; and

            
            - hash and byte length of every evidence file.


            Write each artifact to a unique temporary file, flush, close, atomically rename,

            
            and hash the final bytes. Write the manifest last. A run whose evidence cannot

            
            be finalized is not successful.


            ### 17. Driver Agent integration


            The workflow remains:


            ```text

            
            proposed

            
                -> permissions-resolved

            
                -> approved

            
                -> running

            
                -> observed

            
                -> interpreted

            
                -> verified | contradicted | inconclusive

            
            ```


            Driver Agent:


            1. proposes the smallest plan needed to resolve a claim;

            
            2. requests missing consent rather than broadening the plan;

            
            3. freezes approved intent;

            
            4. invokes the host API;

            
            5. watches execution and recovery;

            
            6. preserves raw evidence;

            
            7. interprets only finalized evidence; and

            
            8. never converts a transport success into semantic verification.


            Agent interpretation cites the operation, resource, offset or protocol method,

            
            raw values, target timestamp, driver/proxy generation, and relevant source.


            ### 18. Host data models


            Use frozen dataclasses or equivalent validated models for:


            - node summaries and descriptions;

            
            - access requirements and capabilities;

            
            - target and resource identity;

            
            - run context;

            
            - read grants and permission decisions;

            
            - plans and approvals;

            
            - operation requests/results;

            
            - proxy-access transitions (takeover/restoration variants reserved for

            
              phase 2);

            
            - audit pages; and

            
            - evidence manifests.


            Conversion among JSON, internal models, generated FIDL, and subprocess messages

            
            occurs only in explicit functions. Do not pass unvalidated dictionaries through

            
            the system.


            ### 19. Security and trust boundaries


            The host consent file protects the workflow from accidental or unapproved

            
            agent behavior. It is not a target security boundary: a malicious host with

            
            engineering access may bypass it.


            The target ceiling must remain safe enough for the intended engineering

            
            environment even if host approval is bypassed. The plan digest proves stable

            
            intent within the workflow; it is not bearer authorization.


            Permission files:


            - contain no secrets;

            
            - use least-specific filesystem permissions appropriate to the environment;

            
            - are never read from unapproved workspace paths;

            
            - have explicit schema and revision history;

            
            - reject duplicate or ambiguous matches; and

            
            - are included by digest in evidence.


            ### 20. Testing


            #### 20.1 Permission tests


            Test:


            - exact grant match;

            
            - offset, width, resource, node, and digest mismatch;

            
            - boot change with stable resource description;

            
            - resource-description change;

            
            - one-shot grant rejected for poll;

            
            - poll limit enforcement;

            
            - persistent deny precedence;

            
            - unattended fail-closed behavior;

            
            - concurrent config writers;

            
            - malformed/ambiguous config;

            
            - atomic persistence; and

            
            - revoke/explain behavior.


            #### 20.2 Plan and evidence tests


            Test:


            - deterministic canonicalization and hashing;

            
            - every executable change invalidates approval;

            
            - selected access mode is frozen;

            
            - unsupported guarantee fails before connection;

            
            - arbitrary path/moniker/driver injection is rejected;

            
            - partial execution classification;

            
            - atomic artifact writes;

            
            - manifest hashes;

            
            - Ctrl-C finalization;

            
            - disk-full failure; and

            
            - no evidence-directory reuse.


            #### 20.3 Transport tests


            Use fake and physical transports to test:


            - normal network connection;

            
            - supported USB connection;

            
            - serial-capable connection without `core` (applicable once the serial

            
              transport lands);

            
            - target discovery;

            
            - target reboot;

            
            - peer closure;

            
            - transport migration without public API change; and

            
            - identical structured output across transports.


            #### 20.4 Proxy-activation tests


            Test:


            - unclaimed-node verification before bind;

            
            - a node with a bound driver is rejected (takeover is phase 2);

            
            - incompatible proxy;

            
            - proxy bind failure;

            
            - host disconnect during activation and execution;

            
            - execution failure;

            
            - proxy stop failure; and

            
            - the node is verified unclaimed after end of access.


            Managed-takeover state-transition tests are specified in phase 2.


            #### 20.5 Direct-mode tests


            Test:


            - typed protocol discovery;

            
            - direct production FIDL call;

            
            - no private MMIO capability;

            
            - no target-audit claim;

            
            - direct-mode evidence;

            
            - refusal of a takeover-only plan; and

            
            - no fallback after direct connection failure.


            #### 20.6 Driver Agent tests


            Test:


            - prepare performs no access;

            
            - missing read grant pauses or fails closed;

            
            - "always allow" persists the exact rule;

            
            - plan mutation invalidates approval;

            
            - target drift fails before proxy activation;

            
            - interpretation cannot precede finalized evidence;

            
            - target loss causes no automatic mutation retry; and

            
            - a failed proxy teardown prevents a verified outcome.


            ### 21. Build and repository placement


            The `ffx` subtool, target bindings, and transport integration belong in the

            
            Fuchsia tree. The Python package is built there, at `tools/driver-lab`,

            
            because it links fuchsia-controller and the generated bindings.


            Driver Agent adapters, workflow approval objects, and repository-specific

            
            orchestration remain in the external Driver Agent repository.


            Every run records exact revisions and dirty-state artifacts for both

            
            repositories. Directory layout is not part of the evidence identity.


            ### 22. Milestones


            #### Milestone H0: transport and control-plane feasibility


            - prove the target control plane is reachable through a supported transport;

            
            - produce the serial-transport discovery report (FDomain byte-stream

            
              connector status, bootstrap-realm host candidates, `ffx` team roadmap);

            
            - enumerate nodes and bound drivers via `fuchsia.driver.development` and

            
              produce the discovery gap matrix;

            
            - validate unclaimed-node proxy binding via existing registration and bind

            
              mechanisms; and

            
            - decide the stable Python-to-`ffx` adapter.


            Exit: no architecture-critical dependency is assumed rather than demonstrated.


            #### Milestone H1: direct mode


            - typed node/protocol discovery;

            
            - one direct published-protocol interaction;

            
            - capability reporting;

            
            - structured CLI output; and

            
            - evidence bundle.


            Exit: direct mode makes no claim to private resources or target audit.


            #### Milestone H2: permissions


            - read-grant model;

            
            - interactive allow-once/always-deny flows;

            
            - atomic persistent config;

            
            - unattended fail-closed behavior; and

            
            - plan permission resolution.


            Exit: an unapproved register read cannot reach the target.


            #### Milestone H3: proxy activation on unclaimed nodes


            - direct proxy bind for an unclaimed synthetic node;

            
            - prepare, activate, execute, and end-access workflow;

            
            - stale-state validation;

            
            - disconnect handling;

            
            - evidence of every transition; and

            
            - failure recovery.


            Exit: the proxy activates, executes, and deactivates on a synthetic unclaimed

            
            node without manual target intervention.


            #### Milestone H4: driver-shaped Python API


            - MMIO and representative protocol-backed resource objects;

            
            - capability-aware operation dispatch;

            
            - translation metadata;

            
            - target-local sequence support; and

            
            - async cancellation tests.


            Exit: the same overlapping Python operations work through direct and proxy

            
            backends without hiding semantic differences.


            #### Milestone H5: Driver Agent and recovery


            - proposal/permission/approval/run/interpret separation;

            
            - paniolo integration;

            
            - panic/reboot handling;

            
            - no automatic mutating retry; and

            
            - evidence-linked conclusions.


            Exit: an agent can complete an approved read-only investigation and safely

            
            stop for missing authority.


            ### 23. Definition of done


            The phase 1 host tooling is ready when:


            - its target control plane has no `core` component dependency;

            
            - supported target transports pass end-to-end tests without precluding a

            
              serial-capable path;

            
            - direct and proxy modes share one typed public API;

            
            - programming-model differences remain visible;

            
            - private resources are never claimed in direct mode;

            
            - unknown reads require exact operator consent;

            
            - persistent grants are stable, auditable, and revocable;

            
            - mutations require target policy and explicit plan approval;

            
            - proxy access on an unclaimed node activates, executes, and tears down

            
              verifiably;

            
            - transport loss never triggers automatic mutation replay;

            
            - every run produces a complete hashed evidence bundle;

            
            - Driver Agent separates observation from interpretation;

            
            - no plan can inject arbitrary target paths, monikers, or driver URLs; and

            
            - plan, session, and evidence schemas carry the reserved takeover fields so

            
              phase 2 requires no major contract change.


            ### 24. Open decisions


            Before implementation, resolve:


            1. (deferred, `ffx`-team-owned) The serial-capable target transport; phase 1

            
               must not preclude it.

            
            2. Resolved: the Python API links fuchsia-controller in process, with the

            
               generated `fuchsia.driver.lab` bindings behind the transport-neutral

            
               `ProxyTransport` seam.

            
            3. Which node/resource descriptors are stable enough for grant matching.

            
            4. The user-level versus workspace-level permission-file location and merge

            
               precedence.

            
            5. Whether persistent read grants may be shared across equivalent physical

            
               targets.

            
            6. The first standard FIDL resources used to validate programming-model

            
               fidelity.

            
            7. Whether a narrowing-only `ExtendAllowlist` session operation replaces V1's

            
               reopen-per-grant behavior.

            
            8. The register-metadata schema, provenance, and review process backing

            
               consent expansion.


            Takeover-related decisions (force-bind, node persistence, restoration policy,

            
            takeover-protocol packaging) live in the Phase 2 section of this document and

            
            in //src/devices/driver-lab/SPEC.md.


            ### 25. Primary references


            - [Fuchsia Controller remote scripting](https://fuchsia.dev/fuchsia-src/development/tools/fuchsia-controller/scripting-remote-actions)

            
            - [Driver communication and services](https://fuchsia.dev/fuchsia-src/concepts/drivers/driver_communication)

            
            - [Fuchsia registers driver](https://fuchsia.dev/fuchsia-src/development/drivers/driver_guides/registers/overview)

            
            - [Driver runner and driver hosts](https://fuchsia.dev/fuchsia-src/concepts/components/v2/driver_runner)

            
            - [FFX overview and target connections](https://fuchsia.dev/fuchsia-src/development/tools/ffx/getting-started)

            
            - [FDomain RFC](https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0228_fdomain)


            ## Phase 2: in-situ driver debugging workflow


            ### Implementation status


            Changesets continue the global numbering:


            - [x] CS24 `[driver-lab] Core library extraction & pre-mapped MMIO adapter`

            
                  (in //src/devices/driver-lab/SPEC.md).

            
            - [x] CS25 `[driver-lab] Embedded Rust driver library with ServiceFs integration`

            
                  (in //src/devices/driver-lab/SPEC.md).

            
            - [x] CS26 `[driver-lab] Cooperative locking, quiesce hooks, and interrupt tap support`

            
                  (in //src/devices/driver-lab/SPEC.md).

            
            - [x] CS27 `[driver-lab] Assembly gating, CML debug shard, and production-absence verification`

            
            - [x] CS28 `[driver-lab] Reference integration: synthetic platform driver in testing/`

            
            - [x] CS29 `[driver-lab] Host tooling discovery of embedded debug endpoints and in-situ session workflow`

            
            - [x] CS30 `[driver-lab] In-situ live-target conformance test suite`

            
            - [x] CS34 `[driver-lab] Expose FIDL and debug shard to Bazel`

            
                  (in //src/devices/driver-lab/SPEC.md).

            
            - [x] CS35 `[driver-lab] Native Bazel build for driver_lab_rust`

            
                  (in //src/devices/driver-lab/SPEC.md).

            
            - [x] CS36 `[driver-lab] Add C FFI staticlib shim (driver_lab_c)`

            
                  (in //src/devices/driver-lab/SPEC.md).

            
            - [x] CS37 `[driver-lab] Add C/C++ wrapper and StateVmoBank`

            
                  (in //src/devices/driver-lab/SPEC.md).

            
            - [x] CS38 `[driver-lab] Add C++ embedded server unit tests`

            
                  (in //src/devices/driver-lab/SPEC.md).


            Phase: 2 -- in-situ driver debugging workflow.

            
            Extends: the Phase 1 section of this document. The wire client, transport adapters,

            
            CLI parsing, and evidence models apply unchanged.


            Companion specification: the proxy driver specification at

            
            `//src/devices/driver-lab/SPEC.md`.


            ### 1. Purpose


            Phase 2 enables host tooling (`ffx driver-lab`, the public Python API, and Driver

            
            Agent) to connect directly to active, bound drivers equipped with the embedded

            
            driver-lab library. This eliminates the need for managed takeover, avoids

            
            disturbing live hardware state, and provides real-time in-situ inspection of

            
            wedged or misbehaving devices.


            ### 2. Workflow differences: standalone proxy vs in-situ library


            | Stage | Phase 1 (Standalone Proxy) | Phase 2 (Embedded In-Situ Library) |

            
            | :--- | :--- | :--- |

            
            | **Node State** | Unclaimed dev-node (no driver bound) | Active driver bound and running |

            
            | **Target Moniker** | `lab_proxy.cm` on synthetic or test node | Bound driver moniker (e.g. `/bootstrap/boot-drivers:sample-driver`) |

            
            | **Transport Connection** | `connect_device_proxy(proxy_moniker, ...)` | `connect_device_proxy(driver_moniker, ...)` |

            
            | **Hardware State** | Freshly initialized / unclaimed | Live in-flight state (preserves bugs) |

            
            | **Teardown / Restore** | Stop `lab_proxy`; discard node | Close session; release mutation lease; driver resumes normal work |


            ### 3. Design invariants


            #### 3.1 No unbind or hardware reset


            In-situ debugging connects to the live driver component. It does not unbind the

            
            driver, does not drop power domains or clock votes, and does not reset hardware

            
            registers.


            #### 3.2 Safe reads by default


            Scalar reads and snapshots default to non-destructive inspection. Known

            
            clear-on-read or FIFO data registers must be marked `hard_denied` in the target

            
            ceiling manifest unless explicitly authorized in an exact session allowlist.


            #### 3.3 Cooperative quiesce during mutation


            Opening a mutating session acquires an exclusive mutation lease. If registered

            
            by the driver, the library invokes an optional driver-registered synchronous

            
            `quiesce_hook(bool paused)` callback to pause driver-side background polling

            
            loops while host mutations and sequences execute. If complex driver dispatchers

            
            require asynchronous coordination in the future, this interface may be extended

            
            to support an async stream/channel notification.


            ### 4. Host discovery additions


            Host discovery via `fuchsia.driver.development.Manager` remains the discovery

            
            mechanism:

            
            1. `ffx driver-lab list --debug-capable`: Queries active drivers on the target and

            
               filters for components exposing `fuchsia.driver.lab.Service`.

            
            2. `ffx driver-lab describe --moniker <driver-moniker>`: Fetches `ProxyDescription`

            
               directly from the live driver's embedded endpoint, inspecting its registered

            
               MMIO banks, protocol resources, and ceiling policy digest.


            ### 5. In-situ experiment workflow


            #### 5.1 Prepare


            1. Query target driver monikers and confirm that `fuchsia.driver.lab.Service`

            
               is exposed.

            
            2. Run `describe` to fetch registered resources, logical sizes, and the target

            
               policy digest.

            
            3. Operator approves exact read allowlists and probe plans.


            #### 5.2 Execute


            1. Create a non-reused evidence directory.

            
            2. Start serial and liveness capture.

            
            3. Open session with exact allowlist and expectations matching live driver state.

            
            4. Execute probe plan (scalar reads, snapshots, timing sequences).

            
            5. If mutating, the driver's internal background loop is paused via the quiesce

            
               interlock while operations execute.

            
            6. Drain audit ring directly from the driver's embedded buffer.

            
            7. Close session channel.


            #### 5.3 Teardown


            1. Closing the session releases the mutation lease and unquiesces the driver.

            
            2. No Driver Manager rebind, node restoration, or reboot is required.

            
            3. Stop capture and finalize evidence with driver moniker and hash verification.


            ### 6. Failure behavior


            - **Target Disconnect**: Dropping the FIDL connection closes the session on the

            
              target; the driver's embedded server immediately clears the mutation lease and

            
              resumes normal operations.

            
            - **Hardware Wedging**: If a mutating register write locks the hardware bus,

            
              out-of-band serial capture and target reboot recovery run as specified in

            
              Phase 1 Milestone H5.


            ### 7. Host surface additions


            - `attach` and `connect` accept a driver component moniker directly without

            
              requiring an unclaimed node.

            
            - The CLI adds `ffx driver-lab inspect --moniker <id>` as the primary entry point

            
              for live driver diagnostics.

            
            - Evidence records the driver component moniker and URL in `manifest.json`.


            ## Phase 3: software state, runtime knobs, and adaptive verification workflow


            ### Implementation status


            Changesets continue the global numbering:


            - [x] CS31 `[driver-lab] Software state banks, runtime knobs, and diagnostic triggers`

            
                  (in //src/devices/driver-lab/SPEC.md).

            
            - [x] CS32 `[driver-lab] Host plan aliases and StateHandle API for state and knob experiments`

            
            - [x] CS33 `[driver-lab] Update driver-lab and autoda-fix skills for Mode A/B/C verification`


            Phase: 3 -- software state, runtime knobs, and adaptive verification workflow.

            
            Extends: Phases 1 and 2 of this document.


            Companion specification: the proxy driver specification at

            
            `//src/devices/driver-lab/SPEC.md`.


            ### 1. Purpose


            Phase 3 enables host probe plans, the asynchronous Python API, and the

            
            `autoda-fix` skill to interact ergonomically with target-side

            
            `StateBank` resources (CS31) for single-build software state and concurrency

            
            experimentation, while selecting the lightest-weight verification mode for any

            
            driver bug.


            ### 2. Host plan operation aliases and `StateHandle` API (CS32)


            #### 2.1 Plan operation aliases (`driver_lab/plans.py`, `api.py`, `cli.py`)


            Probe plans support semantic operation kinds for `StateBank` resources both at

            
            top-level `operations` and inside `sequence.items`:


            1. **`state_read32`**:

            
               - Reads a 32-bit state slot or read probe at `offset`.

            
               - `resource` defaults to `"state0"` when omitted.

            
               - Maps to `AccessClass.READ_ONCE` (or `AccessClass.SEQUENCE` inside a

            
                 sequence) and executes via `session.read32(resource_id, offset)`.

            
            2. **`state_poll32`**:

            
               - Polls a 32-bit state slot until `(value & mask) == (expected & mask)` or

            
                 timeout (`timeout_ns` defaults to `100_000_000` when omitted).

            
               - `resource` defaults to `"state0"` when omitted.

            
               - Maps to `AccessClass.POLL` and executes via `session.poll32(...)`.

            
            3. **`knob_write32`**:

            
               - Writes a 32-bit runtime tuning knob or fix-toggle flag at `offset`.

            
               - `resource` defaults to `"state0"` when omitted; `readback` defaults to

            
                 `True`.

            
               - Marks the plan as mutating (`is_mutating_plan() == True`), maps to

            
                 `AccessClass.WRITE` (requiring one-time operator consent), and executes via

            
                 `session.write32(...)`.

            
            4. **`trigger_write32`**:

            
               - Invokes a deterministic diagnostic trigger callback at `offset`.

            
               - `resource` defaults to `"state0"` when omitted; accepts `arg` or `value`

            
                 (defaulting to `1`); `readback` defaults to `False`.

            
               - Marks the plan as mutating (`is_mutating_plan() == True`), maps to

            
                 `AccessClass.WRITE` (requiring one-time operator consent), and executes via

            
                 `session.write32(...)`.


            Evidence bundles (`operations.jsonl`) preserve the exact semantic operation

            
            `kind` (`"state_read32"`, `"state_poll32"`, `"knob_write32"`,

            
            `"trigger_write32"`) for audit clarity.


            #### 2.2 Asynchronous Python `StateHandle` (`driver_lab/session.py`)


            `HardwareSession.state(name: str = "state0") -> StateHandle` wraps the named

            
            `StateBank` resource with a driver-shaped asynchronous API:

            
            - `await state.read32(offset) -> int`

            
            - `await state.poll32(offset, expected=0, mask=0xFFFF_FFFF, interval_s=0.001, timeout_s=1.0) -> PollOutcome`

            
            - `await state.write_knob(offset, value, ..., require_readback=True) -> WriteOutcome`

            
            - `await state.trigger(offset, arg=1, ..., require_readback=False) -> WriteOutcome`

            
            - `await state.snapshot32(offsets) -> list[int]`


            ### 3. Adaptive Mode A/B/C verification workflow (`autoda-fix`, CS33)


            The `autoda-fix` skill (`//src/devices/skills/autoda-fix`)

            
            and companion `driver-lab` skill (`//src/devices/skills/driver-lab`) classify

            
            driver bugs during Phase 0 reconnaissance into one of three verification modes:


            1. **Mode A: Hardware Register / Interrupt Loop (`in-situ` MMIO/IRQ)**:

            
               - Used for bugs involving hardware register configuration, bitfields, clocks,

            
                 FIFOs, or interrupts.

            
               - Verifies live register values and interrupt delivery via `mmio_read32`,

            
                 `mmio_write32`, `mmio_poll32`, and `wait_for_interrupt` with hashed

            
                 evidence bundles.

            
            2. **Mode B: In-Situ Software State & Knob Loop (`in-situ` `StateBank`)**:

            
               - Used for concurrency/race bugs, state-machine bugs, and retry/timeout

            
                 tuning on live hardware.

            
               - **Phase 1 (Single Instrumentation Build)**: Instruments suspect code paths

            
                 with a `"state0"` `StateBank` (`define_state_slot`, `define_knob` for fault

            
                 and fix toggles, `define_trigger`) and deploys once (preferring

            
                 `ffx driver restart <driver_url>` for reloadable non-bootfs drivers).

            
               - **Phase 2 (Zero-Compile Experimentation Loop)**: Executes a **Repro Plan**

            
                 (`knob_write32` with fix knob = `0`, `trigger_write32`, `state_read32`)

            
                 followed in the same boot by a **Fix Proof Plan** (`knob_write32` with fix

            
                 knob = `1`, `trigger_write32`, `state_read32` / `state_poll32`).

            
               - **Phase 3 (Clean Final Patch)**: Replaces temporary knobs with the clean,

            
                 unconditional production fix and adds a permanent unit/realm regression

            
                 test.

            
            3. **Mode C: Hermetic Test & Log Verification Loop (No `driver-lab` Required)**:

            
               - Used for pure logic, protocol/message parsing, or deterministic lifecycle

            
                 bugs reproducible via `fx test` (unit/realm tests) or `ffx log`.

            
               - Explicitly forbids shoe-horning `driver-lab` into Mode C bugs when a unit

            
                 test or log assertion is faster and more direct.