src/devices/driver-lab/SPEC.md

<!-- 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 proxy driver specification

This is the normative specification for the engineering-only driver-lab
proxy driver (`lab_proxy`) at `//src/devices/driver-lab`. The companion
host tooling specification lives at `//tools/driver-lab/SPEC.md`.

The specification is delivered in three phases. Phase 1 -- unclaimed-node
binding through existing Driver Framework mechanisms, with no Driver Manager
changes -- is delivered first. Phase 2 -- in-situ cooperative debugging via an
embedded driver-lab library -- extends the architecture to existing, active drivers
without managed takeover or Driver Manager modifications, allowing live register
inspection while preserving device state. Phase 3 -- software state banks,
runtime knobs, and diagnostic triggers -- extends in-situ debugging beyond
physical hardware registers so host plans can observe internal driver state,
inject bounded race-window delays, toggle candidate fixes at runtime, and trigger
diagnostic actions in a single build.

## Phase 1: unclaimed-node proxy

### Implementation status

Changeset numbers (CS) are global across this specification and
`//tools/driver-lab/SPEC.md`, whose changesets interleave with these;
gaps in the numbering below are driver-lab 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] CS1 `[driver-lab] Proxy driver specification` -- this
      document.
- [x] CS3 `[driver-lab] Phase 1 proxy driver core` -- the
      takeover-ready `fuchsia.driver.lab` wire contract (sections 7.4,
      11) and the host-testable policy core: ceiling and exact
      allowlist enforcement (9, 10), per-boot identity and description
      digests (8.3, 10.2), bounded reads and snapshots (12.1, 12.5),
      session lifecycle and leases (16), and the audit ring (18). Bind
      rules are `false` and no resources are offered.
- [x] CS9 `[driver-lab] Platform resource provider, bind rules,
      realm tests` -- resource acquisition and local MMIO mapping
      (8.4, 15), the `PROXY_TARGET` bind library and property-gated
      binding (7.2, 7.3), driver realm tests (23.3), and the lab_root
      test fixture serving a fake platform device (23.3, and the
      live-activation path documented by CS10).

- [x] CS10 `[driver-lab] Add live-target conformance runbook` (in
      //tools/driver-lab/SPEC.md).
- [x] CS11 `[driver-lab] Host node discovery via fuchsia.driver.development`
      (in //tools/driver-lab/SPEC.md).
- [x] CS12 `[driver-lab] Direct mode client and published-protocol workflow`
      (in //tools/driver-lab/SPEC.md).
- [x] CS13 `[driver-lab] Target ceiling policy manifests and verification`
      (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`
      (in //tools/driver-lab/SPEC.md).
- [x] CS16 `[driver-lab] Driver-shaped public Python API` (in
      //tools/driver-lab/SPEC.md).
- [x] CS17 `[driver-lab] Stop-path hardening and cancellation` (19; milestone P2).
- [x] CS18 `[driver-lab] Host CLI subtool expansion and verified teardown`
      (in //tools/driver-lab/SPEC.md).
- [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`
      (12.1, 22).
- [x] CS22 `[driver-lab] Serial capture and independent recovery integration`
      (in //tools/driver-lab/SPEC.md; milestone H5).

Phase: 1 -- new-driver development. The proxy binds to unclaimed nodes through
existing Driver Framework mechanisms. Existing-driver debugging via an embedded
library is specified in the Phase 2 section of this document.

Scope: standalone proxy driver, target policy, resource execution, audit, and
lifecycle.

Companion specification: host tooling at `//tools/driver-lab/SPEC.md`

### 1. Purpose

The proxy driver provides exclusive, resource-scoped hardware access on a
Fuchsia target for interactive and agent-assisted driver development. It runs
locally on the target, maps only resources offered to its device node, executes
bounded operations, enforces a target ceiling and session allowlist, and
records a target-side audit trail.

The driver-lab capability supports two deployment situations:

1. it is selected as the standalone proxy driver for an unclaimed device node
   during new-driver exploration (phase 1, specified here); or
2. its core functionality is embedded as a library in an existing, active driver
   for in-situ live debugging (phase 2).

The core policy, execution, audit, and wire contracts serve both situations.
Phase 1 specifies the standalone driver; Phase 2 specifies the embedded library.

### 2. Normative language

The terms **must**, **must not**, **should**, and **may** describe requirements,
recommendations, and optional behavior respectively.

The following terms have specific meanings:

- **Proxy:** The standalone DFv2 driver defined here.
- **Target ceiling:** Immutable target policy describing the greatest access
  the proxy may provide for a node/resource class.
- **Session allowlist:** Exact plan-derived permissions supplied when a session
  opens. It may only narrow the target ceiling.
- **Managed takeover:** Driver Manager stops a node's current driver, binds the
  proxy, and later restores the original driver. Defined in the Phase 2
  section of this document.
- **Resource identity:** A stable logical description and digest for an offered
  resource. It never includes a host-provided physical address.
- **Partial completion:** An execution in which at least one operation began
  but the complete plan did not finish successfully.

### 3. Goals

The proxy must:

1. Run in a dedicated driver host.
2. Obtain resources only from the node to which it is bound.
3. Support platform-, PCI-, and other parent-native resource providers through
   narrow backend adapters.
4. Map MMIO locally with device-appropriate cache policy.
5. Retain all objects required for each mapping's lifetime.
6. Represent resources by stable logical IDs and names.
7. Describe resource size, kind, supported operations, target ceiling, and
   identity digest.
8. Enforce both the target ceiling and the exact session allowlist immediately
   before every access.
9. Execute bounded MMIO reads, snapshots, masked writes, polls, delays, and
   barriers.
10. Support resource-specific GPIO, SPI, I2C, serial, clock, reset, and
    interrupt operations without erasing their production semantics.
11. Execute timing-sensitive sequences locally when explicitly requested.
12. Serialize mutation and reject ambiguous concurrent execution.
13. Report explicit per-operation status and partial completion.
14. Record attempted, rejected, successful, failed, and cleanup operations in a
    bounded audit ring.
15. Close or cancel every outstanding request during stop.
16. Contain an experimental driver fault away from Driver Manager and unrelated
    production drivers.
17. Be included only in authorized engineering configurations and remain
    inactive until explicitly bound.

### 4. Non-goals

The proxy must not:

- accept an arbitrary physical address;
- request root resource;
- export MMIO VMOs, interrupt handles, BTIs, IOMMUs, or root-like capabilities
  to the host;
- map resources belonging to another node;
- share ownership with the normal driver for the same node;
- inspect the memory or private state of an active production driver;
- run inside Driver Manager;
- execute arbitrary uploaded code or target-side scripts;
- load a host-provided policy that widens the target ceiling;
- claim transactional rollback for MMIO;
- automatically restore every register from captured "before" values;
- permit unbounded polling, sleeping, snapshots, vectors, or audit output;
- expose DMA programming, arbitrary PCI configuration writes, or SMC calls in
  the initial protocol;
- bind broadly to normal nodes without explicit Driver Manager selection or
  engineering-only bind metadata;
- coordinate operations across multiple device nodes in one session;
- guarantee sub-millisecond timing precision for delays, polls, or
  inter-operation gaps in V1; or
- appear in a production image.

### 5. Architecture

```text
Host tooling
    |
    | ffx target transport
    v
Driver Manager control plane
  discovery: fuchsia.driver.development
    |
    | bind proxy (phase 1) / connect embedded endpoint (phase 2)
    v
Target Component (standalone lab_proxy in phase 1, active driver in phase 2)
    |
    +-- policy and session server
    +-- MMIO executor
    +-- protocol-resource adapters
    +-- interrupt tracker / event tap
    +-- audit ring
    |
    v
Hardware resources mapped to the target driver
```

Driver Manager owns discovery (`fuchsia.driver.development`). The session server
owns the experimental session and bounded hardware execution after connection.

### 6. Design invariants

#### 6.1 Capability confinement

The proxy can access only resources offered to its bound node. It must use the
parent's normal platform, PCI, or bus protocol. It must not obtain a global
resource and reconstruct mappings from host input.

#### 6.2 Hardware safety and concurrency

In phase 1 the standalone proxy binds only to nodes with no bound driver. In
phase 2 the embedded library runs inside the active driver and enforces safety
through cooperative locking, quiesce hooks for mutating sequences, and ceiling
denials on destructive reads.

#### 6.3 Target ceiling is authoritative

The host may provide an exact read consent list and an approved plan, but it
cannot:

- add a resource;
- increase a resource size;
- add an operation width;
- remove a hard deny;
- increase a target deadline;
- enable a disabled resource class; or
- widen a write mask.

#### 6.4 Local execution

MMIO mappings and interrupt objects remain on the target. FIDL carries scalar
operations, protocol transactions, results, descriptions, and audit entries.

#### 6.5 Programming-model fidelity

The target wire contract should preserve the meaning of normal driver
operations:

- protocol-backed resources retain production FIDL request and response
  semantics where possible;
- MMIO remains explicitly width- and offset-based;
- interrupt waiting remains asynchronous;
- reset and clock state changes remain explicit;
- SPI/I2C/serial exchanges do not become generic byte writes; and
- errors are not collapsed into prose.

A generic sequence protocol may coordinate heterogeneous operations locally,
but it must identify the original resource operation precisely. It is an
execution mechanism, not a replacement programming model.

#### 6.6 Bounded execution

Every request has target-enforced bounds. No host field can select an infinite
timeout, unconstrained vector, or blocking dispatcher sleep.

#### 6.7 Explicit partial completion

Writes generally cannot be undone. Execution reports every operation that
began, stops according to declared error rules, and never labels the sequence
atomic.

#### 6.8 Audit is diagnostic, not durable authorization

The proxy audit establishes what it attempted under a run/session context. It
does not prove that the host approval was issued by a particular human.

### 7. Deployment and activation

#### 7.1 Engineering-only packaging

The proxy package should be present by default in the engineering
configurations that support driver-lab workflows. Presence alone grants no
hardware access.

Production images must not offer any of the following, and the build must
verify this:

- the proxy driver package;
- the Driver Manager takeover protocol (phase 2);
- special debug bind metadata;
- target debug policy artifacts; or
- debug capability routes.

The verification mechanism (package absence, a Driver Manager binary variant,
or config gating with capability-route verification) is owned by platform
assembly. This specification requires only that the chosen mechanism be
verifiable at build time.

#### 7.2 Inactive by default

The proxy must not opportunistically claim normal device nodes. In phase 1 it
becomes eligible only through explicit engineering-only node metadata or a
developer-created test node; it may be loaded through engineering assembly
inclusion or ephemeral registration (`fuchsia.driver.registrar`). Plans
cannot supply a driver URL.

In phase 2 a Driver Manager operation may additionally select the fixed proxy
identity for an exclusive managed takeover. That node-scoped force-bind is
new Driver Manager work (the existing `DisableDriver` is global by URL and
unsuitable) and is specified in the Phase 2 section of this document.

#### 7.3 Direct selection during development

For hardware without a normal driver, an engineering product or explicit
developer action selects the proxy at initial bind. This is the phase 1 activation path. It uses the same policy, FIDL,
evidence, and session implementation that the embedded library (phase 2) reuses.

#### 7.4 Embedded library in-situ debugging (phase 2)

In-situ debugging -- embedding the driver-lab server into an active driver,
sharing mapped MMIO via VMO duplication, coordinating concurrency via quiesce
hooks, and tapping interrupts -- is specified in the Phase 2 section of this
document. The phase 1 wire contract serves both standalone and embedded
deployments with no major version change.

### 8. Resource model

#### 8.1 Resource kinds

The extensible resource model begins with:

- MMIO region;
- interrupt;
- GPIO protocol;
- SPI protocol;
- I2C protocol;
- serial protocol;
- clock protocol; and
- reset protocol.

Additional kinds require explicit capability descriptions, bounds, tests, and
threat-model review.

#### 8.2 Resource description

Each resource description contains:

- numeric ID scoped to the proxy instance;
- stable logical name when available;
- resource kind;
- provider identity/type;
- logical size where applicable;
- supported access widths or protocol methods;
- read/write classification;
- target limits;
- stable metadata used to compute a resource-description digest; and
- flags identifying missing or provisional metadata.

Descriptions never expose physical addresses or raw target handles.

#### 8.3 Resource digest

The digest is computed from canonical descriptions including:

- node identity criteria;
- provider kind;
- resource ordinal/name;
- logical size;
- operation widths;
- the immutable target-ceiling entries that apply to this resource, not the
  whole policy manifest; and
- relevant stable parent metadata.

Dynamic handle values, mapping addresses, boot IDs, and service-instance names
are excluded.

The digest allows a persistent host read grant to stop matching when resource
layout or policy changes. Scoping the ceiling input per resource ensures that
a policy change on one resource does not invalidate grants on unrelated
resources.

#### 8.4 Parent adapters

Use an injected `ResourceProvider` interface with implementations appropriate
to the target node:

```text
ResourceProvider
    DescribeResources()
    OpenMmio(id)
    OpenInterrupt(id)
    ConnectProtocol(id, kind)

PlatformResourceProvider
PciResourceProvider
Other reviewed bus-specific providers
FakeResourceProvider
```

Do not place bus-specific address translation in the FIDL server or policy
engine.

If a parent exposes a larger region than the proxy's logical resource, checked
translation must verify both the logical resource and actual backing mapping:

```text
backing_offset = logical_base + request_offset
```

All arithmetic is checked before access.

Resource providers communicate with the parent over zircon channel-transport
FIDL. The isolated driver-host requirement (goal 1) already forces this:
driver-transport (`fdf`) protocols require colocation with the parent.
Parents that offer resources only over driver transport are ineligible for
proxy access in V1; whether a colocated mode is ever introduced is a phase 2
open decision.

### 9. Target policy

#### 9.1 Policy layers

The proxy evaluates:

```text
actual resource bounds
    ∩ immutable target ceiling
    ∩ session allowlist
    ∩ session mode
    ∩ per-operation structural validation
```

Every layer must permit the operation.

#### 9.2 Immutable target ceiling

The ceiling comes from engineering assembly, board/bus metadata, or immutable
package content. Runtime configuration may narrow it but cannot widen it.

It specifies:

- permitted resource providers and resource kinds;
- maximum logical region sizes;
- access widths;
- hard-denied read offsets or ranges;
- whether unknown reads may be enabled by a session grant;
- exact writable offsets and masks;
- precondition/readback requirements;
- permitted protocol methods and maximum transaction sizes;
- interrupt observation permission;
- maximum operations, snapshot items, poll time, delay, and sequence duration;
- audit capacity; and
- cleanup rules.

#### 9.3 Unknown reads

For a resource whose ceiling permits operator-authorized exploration, an
otherwise unclassified aligned read may be allowed only when:

- the offset fits the logical and actual resource;
- it is not hard-denied;
- the exact resource, offset, width, and access class appear in the session
  allowlist; and
- all rate, count, and duration limits are satisfied.

This is an engineering risk decision. The proxy does not claim that an allowed
unknown read is side-effect free.

A session request to sweep a range is expanded into exact offsets before the
session opens. The proxy does not accept a wildcard "all offsets in this
region" allowlist rule.

#### 9.4 Writes

Writes are denied unless the immutable target ceiling contains an exact
writable-register entry. A host/session grant cannot invent a write entry.

Each entry specifies:

- offset and width;
- allowed mask;
- whether read-modify-write is valid;
- allowed precondition mask;
- whether a precondition is required;
- readback mask and semantics;
- barrier requirements;
- failure classification; and
- optional explicitly reviewed cleanup.

Write-one-to-clear, self-clearing, FIFO-like, or destructive-read registers
require a distinct operation semantic. Do not overload ordinary masked writes.

#### 9.5 Protocol-backed resources

For GPIO, SPI, I2C, serial, clock, reset, and future protocols, policy uses
method-specific bounds rather than pretending they are MMIO:

- method allowlist;
- transfer length;
- bus address or chip-select restrictions where applicable;
- configuration ranges;
- timeout/deadline;
- permitted state changes; and
- reset/cleanup behavior.

#### 9.6 Policy generation

When policy is expressed in JSON5 or another checked-in format, generate:

1. a target-native immutable table; and
2. a canonical manifest returned in `Describe`.

Generation rejects duplicate IDs/names, overflow, ambiguous overlap, invalid
masks, unreachable cleanup, nondeterministic ordering, and limits above FIDL
maxima.

Hash the canonical manifest bytes. Evidence records the digest.

### 10. Session allowlist

#### 10.1 Purpose

The session allowlist is derived from the canonical host plan after permission
resolution. It prevents a stale or buggy client from accessing anything beyond
the frozen run, even though it is not cryptographic proof of approval.

#### 10.2 Required identity

Opening a session includes:

- run and case IDs;
- plan digest;
- host tool version;
- expected boot ID;
- expected proxy generation;
- expected resource-description digest;
- expected target-policy digest;
- read-only or mutating mode;
- exact allowed operations or access rules; and
- bounded plan limits.

The proxy rejects a stale identity before access.

#### 10.3 Narrowing validation

Before opening the session, the proxy validates the entire allowlist against
the target ceiling. A rejected allowlist creates no session and performs no
hardware operation.

A read-only session can never issue a write even if a write appears in target
policy. A mutating session additionally requires an exclusive mutation lease.

### 11. Wire contract

The final FIDL syntax must match the selected Fuchsia revision. The semantic
contract below is normative. The V1 contract is implemented as the
`fuchsia.driver.lab` library with the `Proxy` (`Describe`,
`OpenSession`) and `Session` (`Read32`, `Snapshot`, `ReadAudit`) protocols.

#### 11.1 Limits

The protocol declares compile-time bounds for:

- resource names and device IDs;
- resource count;
- operation count;
- snapshot item count;
- protocol transaction size;
- audit page size;
- detail strings;
- session allowlist rules; and
- total encoded response size.

Runtime target limits may be smaller.

#### 11.2 Proxy description

`Describe` returns:

- protocol major/minor;
- proxy implementation version;
- proxy instance/generation;
- boot ID;
- node identity and topology generation;
- takeover identity when applicable (reserved; populated only in phase 2);
- target policy name/digest;
- canonical resource descriptions and digest;
- supported resource and operation kinds;
- runtime limits;
- audit capacity; and
- fault-isolation/session capabilities.

#### 11.3 Session creation

`OpenSession` accepts run context, session mode, identity expectations, and the
exact allowlist. It returns a session channel and session ID.

Read-only sessions may coexist when safe. Exactly one mutating session exists
per proxy instance. Target-local sequences are serialized initially, including
read-only sequences whose interleaving would make evidence ambiguous.

The allowlist is fixed for the session's lifetime in V1. Expanding consent
requires closing the session and reopening it with the expanded allowlist; a
narrowing-only `ExtendAllowlist` operation is a deferred open decision
(section 26).

#### 11.4 MMIO operations

The initial scalar MMIO methods are:

- `Read32(resource_id, offset)`;
- `Write32(resource_id, offset, value, write_mask, precondition, readback)`;
- `Snapshot(items)`; and
- `Poll32(resource_id, offset, expected, mask, interval, timeout)`.

Additional widths require protocol and policy revision. Offsets are bytes from
the start of a logical resource.

#### 11.5 Ordered sequence

`ExecuteSequence` accepts a bounded ordered list containing:

- resource-specific scalar operations;
- delay;
- memory barrier; and
- only those protocol transactions whose exact semantics are represented.

Every entry identifies resource kind, resource ID, and operation-specific
fields. Unknown operations produce `ZX_ERR_NOT_SUPPORTED`.

The sequence is not atomic. Whole-sequence structural/policy validation occurs
before the first hardware operation. Hardware preconditions are evaluated at
execution time.

#### 11.6 Resource-specific endpoints

Where practical, a session should open a typed endpoint for a standard
protocol-backed resource. The endpoint:

- preserves generated FIDL request/response types;
- is bound to the session identity;
- enforces the same target policy and allowlist;
- writes the same audit records; and
- observes the same deadlines and cancellation.

If an exact production protocol cannot represent necessary debug policy or
audit behavior, define a narrowly shaped adapter and document the difference.

#### 11.7 Interrupt observation

`WaitForInterrupt(resource_id, after_sequence, timeout)` is a bounded hanging
request. The proxy retains and acknowledges the interrupt locally.

The report includes:

- interrupt resource ID;
- event sequence;
- total count;
- target timestamp; and
- coalesced/overflow information.

The initial protocol observes interrupts only. It does not let the host change
polarity, routing, or masking.

#### 11.8 Audit

`ReadAudit(cursor, limit)` returns a bounded page and reports the oldest
available sequence so the host can detect gaps.

#### 11.9 Versioning

- Increment minor for optional compatible fields and safely rejectable flexible
  operations.
- Increment major for changed operation meaning, policy guarantees, session
  semantics, or evidence interpretation.
- Never reuse an ordinal with different meaning.
- The host requires an exact major version.
- Golden descriptions and compatibility matrices cover every supported major.

### 12. MMIO semantics

#### 12.1 Read validation

Immediately before every read:

1. verify session and proxy generation;
2. find the resource;
3. require supported width and alignment;
4. check `offset + width` for overflow;
5. require the access within logical size;
6. require the access within actual mapped size;
7. enforce target read ceiling/hard denies;
8. match the exact session allowlist;
9. enforce access-class count/rate/deadline limits; and
10. perform one volatile read.

Rejected accesses are audited without touching hardware.

#### 12.2 Masked writes

For an ordinary 32-bit masked write:

```text
policy_mask = immutable target mask
requested   = request.write_mask

require requested != 0
require (requested & ~policy_mask) == 0

if requested covers the full register width
   and no precondition is configured or requested:
    volatile_write32(request.value)
else:
    require read-modify-write valid for this policy entry
    before = volatile_read32()
    require precondition if configured
    after = (before & ~requested) | (request.value & requested)
    volatile_write32(after)

apply required barrier
read back configured stable bits if required
```

The before-read in the read-modify-write path is itself a hardware read with
potential side effects; it is audited, and it is permitted only where the
policy entry declares read-modify-write valid. Write-only registers must be
declared full-mask, non-read-modify-write, and without preconditions.

Reject rather than silently narrow a requested mask.

#### 12.3 Polls and delays

Polls use asynchronous timers on the driver dispatcher. They never busy-wait
and never block the dispatcher with sleep.

Dispatcher timers provide millisecond-class scheduling precision. V1 makes no
sub-millisecond guarantee for delays, polls, or inter-operation gaps; whether
ceiling-bounded short spin-delays are permitted for microsecond-class
sequencing is an open decision (section 26). Declared timing precision is
part of capability reporting.

The proxy enforces:

- maximum interval frequency;
- maximum timeout;
- maximum iteration count;
- sequence wall-clock deadline; and
- cancellation on session close or stop.

#### 12.4 Barriers

Use the architecture/platform MMIO primitives from the selected Fuchsia tree.
A barrier orders accesses; it does not prove device-internal completion.

#### 12.5 Snapshot

Validate every item before the first read. The snapshot is an ordered series of
reads, not an atomic hardware snapshot. Each value includes an individual
timestamp, status, and audit sequence.

### 13. Execution and dispatcher model

Start with one synchronized dispatcher for:

- FIDL requests;
- session state;
- execution state machines;
- timers;
- interrupt callbacks;
- audit ordering; and
- driver stop.

Use an asynchronous sequence state machine:

```text
ValidateWholeSequence
    |
    v
BeginOperation
    +-- immediate operation -> Record -> next
    +-- delay -> arm timer -> resume -> Record -> next
    +-- poll -> read -> matched/timeout/arm interval
    +-- protocol wait -> async completion -> Record -> next
```

A second target-local sequence receives `ZX_ERR_SHOULD_WAIT` until safe
concurrency semantics are designed.

On failure:

- stop when `stop_on_error` is true;
- continue only for explicitly recoverable errors when it is false;
- never continue after stop, peer closure, invalid backend state, or a
  policy-classified fatal error; and
- initially require `stop_on_error = true` for every mutating sequence.

### 14. Core implementation boundaries

Use narrow testable modules:

```text
ProxyDriver
    lifecycle, outgoing service, instance identity

ResourceProvider
    node/parent-specific acquisition

HardwareBackend
    MMIO, barriers, clock, and injected protocol operations

AccessPolicy
    actual bounds + target ceiling + session allowlist

Executor
    scalar operations and asynchronous sequences

SessionServer
    run context, allowlist, leases, cancellation

ProtocolResourceAdapter
    GPIO/SPI/I2C/serial/clock/reset endpoints

InterruptTracker
    async waits, counters, acknowledgment

AuditRing
    bounded ordered target evidence
```

FIDL conversion stays at service boundaries. Policy and executor tests run
without a component realm: the pure-logic modules form the
`lab_proxy_core` crate, which builds for both the target and the build
host so their tests run without an emulator.

### 15. Driver start

`Start` must:

1. read immutable engineering configuration;
2. load/generate the target ceiling;
3. connect to the node's parent-native resource provider;
4. enumerate offered resources;
5. validate policy against actual resources;
6. map permitted MMIO locally;
7. obtain and register permitted interrupts;
8. connect permitted protocol-backed resources;
9. derive boot/proxy/resource identities and digests;
10. create FIDL binding groups;
11. publish the proxy service through the Driver Framework route expected by
    the Driver Manager control plane; and
12. emit one structured ready event.

Start performs no experimental write. Avoid reads with possible side effects.
An identity read during start is allowed only when explicitly declared safe
and audited.

Start fails if a required resource is absent, undersized, ambiguous, or
incompatible with policy.

### 16. Sessions and leases

A session owns:

- run context;
- exact allowlist;
- read-only/mutating mode;
- session ID;
- pending timers/waits;
- sequence state; and
- audit cursor metadata.

On session channel close:

- cancel timers and waits;
- stop new operations;
- release the mutation lease;
- audit session closure;
- run only explicitly configured fail-safe cleanup; and
- finish within a bounded deadline.

Cleanup is fallible and audited. A resource with unknown safe cleanup has no
automatic cleanup and relies on normal driver rebind, target reset, or
out-of-band recovery.

### 17. Interrupt handling

For every interrupt callback:

1. capture target monotonic time;
2. increment count and sequence;
3. calculate coalescing information where available;
4. satisfy eligible waiters;
5. append an event/audit entry; and
6. acknowledge the interrupt on every path.

Use virtual interrupts in tests. An interrupt storm must not allocate
unbounded memory or starve stop/restoration.

### 18. Audit ring

The fixed-capacity ring assigns monotonically increasing 64-bit sequence
numbers. Wrap overwrites old entries but does not reset sequence.

The ring is in-memory: a driver-host crash loses undrained entries. Host
workflows must therefore drain audit incrementally during mutating plans
rather than only at run end.

Each entry contains:

- target boot and proxy generation;
- session and run context;
- resource identity;
- operation index and normalized operation;
- allowlist match/grant reference when provided;
- target policy decision;
- status;
- applicable before/after/value data;
- start/completion or event timestamp; and
- cleanup/failure classification.

Never audit pointer values, physical addresses, channel handles, or unbounded
caller strings.

The driver layer mirrors each appended entry into system tracing through an
append observer, keeping the core crate free of Fuchsia dependencies. Entries
are written to the `driver_lab` trace category, or `driver_lab:irq` for
interrupt taps, and successful writes also sample a per-resource counter.
Mirroring must be a no-op unless a trace session enables the category, must
not block, and must be disabled for embedded servers in builds without
`enable_driver_lab`. Trace events are best-effort; the audit ring remains the
authoritative record.

### 19. Stop

`PrepareStop` must:

1. reject new sessions;
2. stop accepting operations;
3. cancel sequence timers and protocol waits;
4. cancel interrupt waits;
5. finish in-flight callbacks;
6. close FIDL bindings with an epitaph;
7. run only bounded configured cleanup;
8. stop interrupt handlers;
9. release mappings/resources; and
10. complete stop within the Driver Manager stop deadline.

Every pending call terminates with a result, epitaph, cancellation, or bounded
host timeout.

### 20. Error model

Use typed application errors and Zircon status consistently:

- invalid/misaligned input;
- out of resource bounds;
- target ceiling denial;
- session allowlist denial;
- stale boot/proxy/resource identity;
- failed precondition;
- unsupported resource/method;
- timeout;
- cancellation;
- mutation lease contention;
- partial execution; and
- fatal backend state.

Machine-parsed information must not exist only in a human detail string.

Execution reports contain:

- sequence/batch ID;
- first and last audit sequence;
- result for every operation that began;
- stopped-on-error flag;
- partial-completion classification;
- fatal/nonfatal classification; and
- proxy health after execution.

### 21. Source layout

Exact paths may follow repository conventions:

```text
src/devices/driver-lab/
    BUILD.bazel
    BUILD.gn
    meta/
    fidl/
        BUILD.bazel
        BUILD.gn
        driver_lab.fidl          fuchsia.driver.lab wire contract; moves to
                                 an internal-category SDK library once the
                                 contract stabilizes
    src/
        lib.rs                   driver lifecycle and service publication
        driver_lab_lib.rs        embedded Rust library crate root
        embedded.rs              EmbeddedLabServer and DriverLabBuilder
        c_api.rs                 C FFI staticlib shim (driver_lab_c)
        server.rs                FIDL session server
        trace.rs                 audit-to-trace mirroring (driver_lab categories)
        core.rs                  host-testable core crate root
        access_policy.rs
        audit_ring.rs
        digest.rs
        executor.rs
        hardware_backend.rs
        session.rs
        resource_provider.rs           planned: parent adapters (P0/P1)
        protocol_resource_adapter.rs   planned (P4)
        interrupt_tracker.rs           planned (P5)
    cpp/
        include/lib/driver_lab/
            driver_lab.h         idiomatic C++20 wrapper and StateVmoBank
            driver_lab_c.h       pure C ABI declarations and global state helpers
        driver_lab.cc            C++20 wrapper and StateVmoBank implementation
        tests/
            driver_lab_cpp_test.cc   C++ embedded server and StateVmoBank unit tests
    policy/                            planned: schema and generation
    bind/

src/devices/bin/driver_manager/
    ... engineering takeover integration (phase 2) ...
```

The proxy is implemented in Rust on the DFv2 Rust driver bindings. Where the
Rust driver-framework, MMIO, or interrupt bindings lag their C++ equivalents
in the selected revision, the gap is a feasibility-spike finding to resolve
upstream, not a reason to switch languages. The wire contract and host
programming model remain language-neutral.

### 22. Build and configuration

Create separate targets for:

- FIDL libraries and generated bindings;
- policy schema/generator;
- pure policy/executor library;
- proxy driver/component/package;
- unit and integration tests;
- Driver Manager takeover integration (phase 2);
- host bindings and compatibility goldens;
- engineering assembly inclusion; and
- production-absence verification.

Structured configuration may reduce:

- enabled state;
- audit capacity;
- log verbosity;
- maximum operation count;
- maximum deadlines; and
- automatic restoration timeout (phase 2).

It may not widen resource or write policy.

### 23. Testing

#### 23.1 Policy tests

Cover:

- known/unknown resources;
- logical versus actual sizes;
- digest determinism;
- hard-denied reads;
- unknown read with and without exact allowlist;
- width/alignment;
- overflow;
- one-shot versus poll permission;
- target limit narrowing;
- read-only versus mutating session;
- exact write offset/mask;
- precondition/readback requirements;
- protocol method and transaction limits; and
- cleanup validation.

#### 23.2 Executor tests

Use fake MMIO, fake clocks, fake timers, and fake protocol resources. Cover:

- scalar read;
- snapshot prevalidation;
- masked write calculation;
- rejected mask performs no write;
- failed precondition;
- readback success/mismatch;
- immediate and delayed poll success;
- poll timeout;
- barriers and ordering;
- protocol transaction;
- stop-on-error partial result;
- cancellation;
- audit/result correspondence; and
- concurrent sequence rejection.

#### 23.3 Driver realm tests

Provide fake parent resources and test:

- platform-like and PCI-like providers;
- resource enumeration;
- missing/undersized resources;
- mapping and device cache policy;
- service publication;
- session opening;
- virtual interrupts;
- driver stop;
- pending request cancellation; and
- no resource handles returned to the host.

#### 23.4 Activation integration tests

With a synthetic unclaimed node:

1. register and bind the proxy through existing mechanisms;
2. verify identity, generation, and digest reporting;
3. execute a read-only plan;
4. stop the proxy; and
5. verify the node is again unclaimed.

Inject failure at every transition. Managed-takeover integration tests are
specified in phase 2.

#### 23.5 Interrupt tests

Verify count/sequence, retained events, future waits, timeout, coalescing,
multiple observers, close cancellation, stop cancellation, acknowledgment,
storm bounding, and stop/teardown responsiveness.

#### 23.6 Security-negative tests

Verify rejection of:

- physical address input;
- unknown resource;
- resource size boundary/overflow;
- unsupported width;
- hard-denied read;
- read absent from session allowlist;
- one-shot grant used for poll;
- write absent from immutable target policy;
- excessive write mask;
- missing precondition;
- oversized operation vectors or transactions;
- excessive timeout/delay;
- mutation from read-only session;
- second mutating session;
- stale identity/digest;
- arbitrary driver URL or protocol path;
- concurrent ownership with normal driver; and
- proxy/control artifacts in a production image.

#### 23.7 Fault injection

Cover:

| Fault | Required result |
|---|---|
| Peer closes before operation | no access; transport failure |
| Peer closes after write | partial/unknown result remains visible |
| Stop during delay/poll | bounded cancellation |
| Driver host crashes | proxy generation changes; session becomes stale |
| Target reboot | boot identity changes; no replay |
| Audit wrap | explicit gap reported |
| Interrupt storm | bounded memory and responsive stop |
| Protocol backend hangs | target/host deadline and recovery path |
| Cleanup fails | audited failure; no success claim |

### 24. Milestones

#### Milestone P0: feasibility

- validate proxy bind to an unclaimed node via existing registration and bind
  mechanisms;
- validate Rust DFv2 driver support for MMIO mapping, interrupt handling,
  synchronized-dispatcher timers, and service publication;
- classify candidate parent resource providers as channel-transport or
  driver-transport-only in the selected revision;
- validate the first parent resource provider;
- validate isolated host placement;
- define the engineering/production assembly boundary with platform assembly
  owners; and
- (phase-2 gate) review node-scoped force-bind, node persistence across
  normal-driver unbind, and restoration with the driver-framework team.

#### Milestone P1: read-only proxy

- `Describe`;
- immutable ceiling;
- session allowlist;
- named MMIO mapping;
- `Read32` and snapshot;
- audit; and
- driver realm tests.

Exit: only an exact allowed read inside an offered resource reaches fake MMIO.

#### Milestone P2: activation integration

- proxy registration, bind, and service routing on an unclaimed synthetic
  node;
- generation identity;
- bounded stop; and
- verified teardown back to an unclaimed node.

Exit: synthetic activation and teardown succeed and every injected transition
failure is visible. (Managed-takeover integration is the corresponding
phase 2 milestone.)

#### Milestone P3: bounded sequence and mutation

- delay, poll, and barrier;
- exact masked writes;
- precondition/readback;
- mutation lease;
- cleanup semantics;
- partial completion; and
- expanded fault tests.

Exit: no out-of-policy bit can be written and no failed sequence is called
atomic.

#### Milestone P4: protocol resources

- representative GPIO and SPI or I2C adapters;
- production-shaped typed endpoints;
- method-specific policy and audit;
- heterogeneous target-local sequence; and
- translation-fidelity documentation.

Exit: host Python can perform equivalent resource operations through direct and
proxy modes without flattening their semantics.

#### Milestone P5: interrupts and physical validation

- interrupt observation;
- virtual tests;
- selected hardware-safe read validation;
- selected reviewed mutation;
- driver-host failure drill; and
- out-of-band recovery drill.

Exit: hardware runs preserve evidence and return the target to a known
operational state.

### 25. Definition of done

The phase 1 proxy is ready when:

- production images verifiably do not offer it;
- it is present but inactive in selected engineering images;
- it binds without an arbitrary host-supplied driver URL;
- it binds only to nodes with no bound driver;
- it receives only resources offered to its node;
- no host API accepts a physical address or raw target resource handle;
- actual bounds, target ceiling, and session allowlist are all enforced;
- unknown reads require an exact session grant;
- writes require immutable exact target policy;
- operations and waits are bounded;
- target-local execution never blocks the dispatcher;
- partial completion is represented honestly;
- audit covers attempted and rejected operations;
- driver stop cancels all pending work;
- teardown verifiably returns the node to an unclaimed state;
- synthetic, security-negative, fault-injection, and selected physical tests
  pass;
- the wire contract remains usable from the companion host tooling
  (`//tools/driver-lab/SPEC.md`); and
- the wire contract carries the reserved takeover fields so phase 2 requires
  no major version change.

### 26. Open decisions

Before implementation, resolve:

1. The first parent resource-provider adapter.
2. How generic engineering read ceilings are supplied without unsafe global
   defaults.
3. Which offsets/ranges must be hard-denied even with operator consent.
4. The initial write-policy authoring and review process.
5. Whether standard FIDL protocols can be served unchanged while preserving
   session policy/audit.
6. The Rust driver-framework, MMIO, interrupt, and timer APIs available in
   the selected Fuchsia revision, and any binding gaps requiring upstream
   work.
7. Whether a narrowing-only `ExtendAllowlist` session operation replaces V1's
   reopen-per-grant behavior.
8. Whether ceiling-bounded short spin-delays are permitted for
   microsecond-class sequencing.

Takeover-related decisions (force-bind and restore APIs, node-class
persistence, restoration-state persistence, driver-host restart during
takeover, subtree teardown) live in the Phase 2 section of this document.

### 27. Primary references

- [Driver communication and services](https://fuchsia.dev/fuchsia-src/concepts/drivers/driver_communication)
- [Mapping device memory in a driver](https://fuchsia.dev/fuchsia-src/concepts/drivers/mapping-a-devices-memory-in-a-driver)
- [Using hardware resources in a driver](https://fuchsia.dev/fuchsia-src/development/drivers/tutorials/sdk_build_driver/hardware-resources)
- [Handling interrupts in a driver](https://fuchsia.dev/fuchsia-src/development/drivers/developer_guide/handle-interrupts-in-a-driver)
- [Driver runner and driver hosts](https://fuchsia.dev/fuchsia-src/concepts/components/v2/driver_runner)
- [Fuchsia registers driver](https://fuchsia.dev/fuchsia-src/development/drivers/driver_guides/registers/overview)
- [Structured configuration](https://fuchsia.dev/fuchsia-src/development/components/configuration/structured_config)
- [Build configuration and product assembly](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/build_configuration)

## Phase 2: embedded driver library & in-situ debugging

### Implementation status

Changesets continue the global numbering from Phase 1:

- [x] CS24 `[driver-lab] Core library extraction & pre-mapped MMIO adapter`
- [x] CS25 `[driver-lab] Embedded Rust driver library with ServiceFs integration`
- [x] CS26 `[driver-lab] Cooperative locking, quiesce hooks, and interrupt tap support`
- [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`
      (in //tools/driver-lab/SPEC.md).
- [x] CS30 `[driver-lab] In-situ live-target conformance test suite`
      (in //tools/driver-lab/SPEC.md).
- [x] CS34 `[driver-lab] Expose FIDL and debug shard to Bazel`
- [x] CS35 `[driver-lab] Native Bazel build for driver_lab_rust`
- [x] CS36 `[driver-lab] Add C FFI staticlib shim (driver_lab_c)`
- [x] CS37 `[driver-lab] Add C/C++ wrapper and StateVmoBank`
- [x] CS38 `[driver-lab] Add C++ embedded server unit tests`

Phase: 2 -- existing-driver in-situ inspection and live debugging via embedded library.
Extends: Phase 1 of this document. The wire contract (`fuchsia.driver.lab`), policy
models, audit ring, and bounded executor apply unchanged.

Companion specification: host tooling at `//tools/driver-lab/SPEC.md`.

### 1. Purpose

Phase 2 enables empirical hardware exploration and live debugging of existing,
bound drivers without stopping them or tearing down their child subtrees.

A driver incorporates the `driver_lab` library during compilation (in engineering
and debug builds), shares its mapped hardware resources with the embedded server,
and serves `fuchsia.driver.lab.Service` from its outgoing directory. Host tooling
connects directly to the driver's moniker, enabling register inspection, bounded
probing, and timing-sensitive sequences while the driver remains alive and active.

### 2. Architecture & library model

#### 2.1 Capability sharing via VMO duplication

The embedded library does not request root capabilities or acquire new resources
from the parent node:
- The driver duplicates its existing MMIO VMO handle (`zx::Rights::SAME_RIGHTS`).
- The library creates an independent local mapping (`MappedMmio`) within the same
  driver host process address space.
- The driver's internal data structures, register types, and private memory
  remain unperturbed.

#### 2.2 Concurrency and cooperative interlocking

Because both the driver's normal dispatch loops and the host's probe sequences
have access to hardware registers, unsynchronized mutations must be prevented:
- **Read operations**: Scalar reads and snapshots to known read-safe registers
  are permitted concurrently. Destructive registers (clear-on-read interrupt
  status, FIFO data registers) must be marked `hard_denied` in the target
  ceiling manifest unless explicitly authorized by an exact allowlist.
- **Mutating sequences and quiescing**: Opening a mutating session acquires an
  exclusive mutation lease. The library invokes an optional driver-registered
  synchronous `quiesce_hook(bool paused)` callback, allowing the driver's state
  machine or worker threads to pause background register polling 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.

#### 2.3 Interrupt observation via event tapping

In Zircon, a `zx::interrupt` object can only be bound to a single dispatcher or
thread. The library therefore does not attempt to steal or bind the raw interrupt
handle.
- The driver instruments its existing interrupt service routine to ping the
  library: `lab.notify_interrupt(resource_id)`.
- The library increments the sequence counter, appends to the audit ring, and
  satisfies pending host `WaitForInterrupt` hanging gets.

### 3. Language roadmap

#### 3.1 Phase 2a: Rust driver library (`driver_lab_rust`)

Prioritized for immediate support across Fuchsia's DFv2 Rust driver stack in
both GN and Bazel builds.
- Links directly against `lab_proxy_core`.
- Native integration with `fdf_component::DriverContext`, `ServiceFs`, and
  `fuchsia_async::Scope` (with GN-only driver crates feature-gated under
  `fdf_driver` and a pure-`zx` root VMAR mapping fallback for native Bazel
  compilation).
- First reference integration: synthetic platform driver in `testing/` (CS28).

#### 3.2 Phase 2b: C/C++ embedded driver library (`driver_lab_c` and `driver_lab_cpp`)

Supports DFv2 C++ and hybrid C/C++ drivers across both GN and Bazel builds
by wrapping `driver_lab_rust` in a thin `extern "C"` FFI static library
(`driver_lab_c`, declared in `cpp/include/lib/driver_lab/driver_lab_c.h`) so all
SHA-256 resource/policy digest calculation, session allowlist enforcement, audit
ring buffering, and sequence execution remain single-sourced in Rust:
- `driver_lab_c` exposes opaque `DriverLabBuilderHandle` and
  `DriverLabServerHandle` pointers over a pure C ABI, runs a dedicated
  background `fuchsia_async::LocalExecutor` thread to serve incoming
  `fuchsia.driver.lab.Proxy` channels without blocking the C++ `fdf::Dispatcher`,
  and provides process-wide global state/knob helpers
  (`driver_lab_global_set_state_u32` and `driver_lab_global_get_knob_u32`) for
  legacy `.c` files.
- `driver_lab_cpp` (`cpp/include/lib/driver_lab/driver_lab.h` and
  `cpp/driver_lab.cc`) provides RAII C++20 wrappers in `namespace driver_lab`:
  `StateVmoBank` (shared-memory VMO bank for telemetry/state and host-tunable
  fault-injection knobs), `Builder`, and `EmbeddedServer` (integrating with
  `fdf::OutgoingDirectory` and `component::OutgoingDirectory`).
- Unit tests (`driver_lab_cpp_tests` in `cpp/tests/driver_lab_cpp_test.cc`)
  verify `Describe`, mutating `OpenSession`, `Read32`, `Write32` on
  `StateVmoBank` knobs, global C state/knob visibility, interrupt tapping,
  quiesce hooks, `ReadAudit`, and hard-denied range rejection over FIDL.

### 4. Production absence and security gating

The embedded debug library must never be active in production (`user`) builds:
1. **Compilation gating**: Gated by build argument (`enable_driver_lab = is_debug`).
   In release builds, library types compile to zero-sized no-ops and outgoing
   service handlers are omitted.
2. **Component manifest sharding**: Driver manifests import a common shard
   `//src/devices/driver-lab/meta/debug.shard.cml` (exported to both GN and
   Bazel targets as `//src/devices/driver-lab:meta/debug.shard.cml`) that
   exposes `fuchsia.driver.lab.Service`.
3. **Product assembly verification**: Platform assembly golden checks verify that
   no production package or bootfs driver exposes `fuchsia.driver.lab.Service`.

### 5. Open design decisions resolved

1. *Takeover unbind/force-bind APIs*: Obsoleted. No Driver Manager changes required.
2. *Subtree teardown and power framework*: Obsoleted. Drivers remain bound;
   subtrees and power topologies remain undisturbed.
3. *ARM64 clock/power gating panics*: Resolved. The running driver maintains its
   votes for power domains and clocks throughout the debug session.

## Phase 3: software state banks, runtime knobs, and diagnostic triggers

### Implementation status

Changesets continue the global numbering from Phase 2:

- [x] CS31 `[driver-lab] Software state banks, runtime knobs, and diagnostic triggers`
- [x] CS32 `[driver-lab] Host plan aliases and StateHandle API for state and knob experiments`
      (in //tools/driver-lab/SPEC.md).
- [x] CS33 `[driver-lab] Update driver-lab and autoda-fix skills for Mode A/B/C verification`
      (in //tools/driver-lab/SPEC.md).

Phase: 3 -- single-build in-situ software state observation, runtime knobs, and
diagnostic triggers.
Extends: Phases 1 and 2 of this document. `StateBank` implements `MmioBackend`
and `ResourceBackend`, requiring no breaking changes to `fuchsia.driver.lab`.

Companion specification: host tooling at `//tools/driver-lab/SPEC.md`.

### 1. Purpose

Phase 3 extends embedded in-situ debugging (`driver_lab_rust::embedded`) beyond
physical MMIO registers so developers and agents can reproduce, diagnose,
prototype fixes for, and verify software state-machine and concurrency bugs
without repeated `edit -> build -> flash/OTA -> reboot` cycles.

### 2. `StateBank` architecture and primitives

`lab_proxy_core::state_bank::StateBank` exposes a 32-bit word-addressed virtual
resource backed by 4-byte aligned offsets within a declared `logical_size`:

1. **Observable state slots (`define_state_slot(offset, initial) -> StateSlotHandle`)**:
   - Backed by `Arc<AtomicU32>` (`StateEntry::AtomicSlot`).
   - Read-only to the host by default (`offset` is omitted from
     `writable_offsets`).
   - The driver updates and reads the slot with zero lock contention via
     `StateSlotHandle` (`load`, `store`, `fetch_add`, `fetch_or`, `fetch_and`).
2. **Runtime knobs (`define_knob(offset, initial) -> StateSlotHandle`)**:
   - Backed by `Arc<AtomicU32>` (`StateEntry::AtomicSlot`) with `offset` added
     to `writable_offsets`.
   - Enables fault/race-window injection knobs (e.g., bounded microsecond delay
     at a suspect critical section) and candidate fix-toggle knobs (e.g.,
     enabling a lock or teardown guard at runtime to prove reproduction with
     `knob = 0` and resolution with `knob = 1` in the same boot).
3. **On-demand read probes (`define_read_probe(offset, probe)`)**:
   - Backed by `Arc<dyn Fn() -> Result<u32, BackendError> + Send + Sync>`
     (`StateEntry::ReadProbe`), evaluated synchronously when `read32` is called.
   - Read-only; host writes are rejected.
4. **Diagnostic triggers (`define_trigger(offset, trigger)`)**:
   - Backed by `StateEntry::Trigger { last_result: Arc<AtomicU32>, callback }`
     with `offset` added to `writable_offsets`.
   - Invokes `callback(value)` on `write32(offset, value)` under a mutating
     session lease, stores the returned `u32` status into `last_result` for
     immediate `readback` or subsequent `read32`/`poll32`, and returns
     `Err(BackendError::Fault)` if the callback fails.

### 3. Policy enforcement and wire contract stability

- `StateBank` implements `MmioBackend` (`read32`, `write32`, and `barrier` via
  `std::sync::atomic::fence(Ordering::SeqCst)`) and `ResourceBackend`.
- `LiveBackend::State(StateBank)` integrates with `DriverLabBuilder::with_state_bank(name, bank)`,
  which registers the bank in `ProvidedResources` with a `ResourceCeiling`
  populated from `bank.writable_offsets()`.
- All existing target policy invariants (`writable_registers`, `hard_denied`,
  session allowlist narrowing, mutating session lease, `quiesce_hook`, and
  `target-audit.jsonl` recording) apply automatically without changing
  `driver_lab.fidl`.

### 4. Reference sample driver integration

`lab_sample_driver` (`//src/devices/driver-lab/testing/src/sample_driver.rs`)
registers a `"state0"` `StateBank` alongside `"mmio0"` and `"irq0"`, exposing
`STATE_BUSY_FLAG` (`0x00`), `STATE_INVARIANT_VIOLATIONS` (`0x04`),
`KNOB_RACE_DELAY_US` (`0x08`), `KNOB_FIX_ENABLED` (`0x0C`), and
`TRIGGER_CONCURRENT_OP` (`0x10`), verified in `sample_driver_realm_test`.