services/i2c/docs/i2c-client-api-implementation-plan.md - third_party/github/OpenPRoT/openprot - Git at Google

 # I2C Client API Implementation Plan

 **Version:** 0.1.0
 **Date:** February 15, 2026
 **Status:** Planning

 ---

 ## Overview

 This document outlines the implementation plan for the I2C Client API as specified
 in [i2c-client-api.md](./i2c-client-api.md).

 ---

 ## Phase 1: Foundation Types

 **Files:** `services/i2c/api/src/address.rs`, `services/i2c/api/src/error.rs`

 ### 1.1 AddressError enum

 ```rust
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AddressError {
     OutOfRange(u8),
     Reserved(u8),
 }
 ```

 - `Display` impl for error messages
 - `Debug`, `Clone`, `Copy`, `PartialEq`, `Eq` derives

 ### 1.2 I2cAddress newtype

 ```rust
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct I2cAddress(u8);
 ```

 Methods:
 - `new(addr: u8) -> Result<Self, AddressError>` — validate 0x08-0x77
 - `new_unchecked(addr: u8) -> Self` — for reserved addresses
 - `value(self) -> u8` — raw accessor
 - `write_address(self) -> u8` — `(addr << 1) | 0`
 - `read_address(self) -> u8` — `(addr << 1) | 1`
 - `TryFrom<u8>` impl

 Unit tests:
 - Valid range acceptance
 - Reserved range rejection (0x00-0x07, 0x78-0x7F)
 - Out of range rejection (> 0x7F)
 - Unchecked escape hatch

 ### 1.3 I2cError struct

 ```rust
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct I2cError {
     pub code: ResponseCode,
     pub kind: Option<I2cErrorKind>,
 }
 ```

 - `impl embedded_hal::i2c::Error` with `kind()` mapping
 - `impl Display` for human-readable messages
 - Helper constructors: `from_code()`, `from_kind()`

 ### 1.4 ResponseCode enum

 ```rust
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(u8)]
 pub enum ResponseCode {
     Success = 0,
     NoDevice = 1,
     NackData = 2,
     ArbitrationLost = 3,
     BusStuck = 4,
     Timeout = 5,
     InvalidBus = 6,
     InvalidAddress = 7,
     BufferTooSmall = 8,
     BufferTooLarge = 9,
     NotInitialized = 10,
     Busy = 11,
     Unauthorized = 12,
     IoError = 13,
     ServerError = 14,
 }
 ```

 - `from_u8(u8) -> Option<Self>` for wire decoding

 ### 1.5 I2cErrorKind enum

 ```rust
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum I2cErrorKind {
     Bus,
     ArbitrationLoss,
     NoAcknowledge(NoAcknowledgeSource),
     Overrun,
     Other,
 }
 ```

 - Re-export `embedded_hal::i2c::NoAcknowledgeSource`

 ---

 ## Phase 2: Core Traits

 **Files:** `services/i2c/api/src/client.rs`, `services/i2c/api/src/operation.rs`

 ### 2.1 BusIndex newtype

 ```rust
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct BusIndex(u8);
 ```

 - `new(index: u8) -> Self`
 - `value(self) -> u8`
 - Constants: `BUS_0`, `BUS_1`, `BUS_2`

 ### 2.2 Operation enum

 ```rust
 #[derive(Debug)]
 pub enum Operation<'a> {
     Write(&'a [u8]),
     Read(&'a mut [u8]),
 }
 ```

 ### 2.3 I2cClient trait

 ```rust
 use embedded_hal::i2c::ErrorType;

 pub trait I2cClient: ErrorType {
     fn write_read(
         &mut self,
         bus: BusIndex,
         address: I2cAddress,
         write: &[u8],
         read: &mut [u8],
     ) -> Result<usize, Self::Error>;

     fn transaction(
         &mut self,
         bus: BusIndex,
         address: I2cAddress,
         operations: &mut [Operation<'_>],
     ) -> Result<(), Self::Error>;
 }
 ```

 ### 2.4 I2cClientBlocking trait

 ```rust
 pub trait I2cClientBlocking: I2cClient {
     fn write(...) -> Result<(), Self::Error>;
     fn read(...) -> Result<usize, Self::Error>;
     fn read_register(register: u8, buffer: &mut [u8]) -> Result<usize, Self::Error>;
     fn write_register(register: u8, value: &[u8]) -> Result<(), Self::Error>;
     fn probe(...) -> Result<bool, Self::Error>;
 }

 impl<T: I2cClient> I2cClientBlocking for T {}
 ```

 **Note:** `write_register` concatenates register + value into single contiguous write.

 ---

 ## Phase 3: Target Mode

 **File:** `services/i2c/api/src/target.rs`

 ### 3.1 TargetMessage struct

 ```rust
 #[derive(Debug, Clone)]
 pub struct TargetMessage {
     pub source_address: I2cAddress,
     data: [u8; 255],
     len: u8,
 }
 ```

 Methods:
 - `data() -> &[u8]`
 - `len() -> usize`
 - `is_empty() -> bool`
 - `Default` impl

 ### 3.2 I2cTargetClient trait

 ```rust
 use embedded_hal::i2c::ErrorType;

 pub trait I2cTargetClient: ErrorType {
     fn configure_target_address(
         &mut self,
         bus: BusIndex,
         address: I2cAddress,
     ) -> Result<(), Self::Error>;

     fn enable_receive(&mut self, bus: BusIndex) -> Result<(), Self::Error>;

     fn disable_receive(&mut self, bus: BusIndex) -> Result<(), Self::Error>;

     fn wait_for_messages(
         &mut self,
         bus: BusIndex,
         messages: &mut [TargetMessage],
         timeout: Option<Duration>,
     ) -> Result<usize, Self::Error>;

     fn register_notification(
         &mut self,
         bus: BusIndex,
         notification_mask: u32,
     ) -> Result<(), Self::Error>;

     fn get_pending_messages(
         &mut self,
         bus: BusIndex,
         messages: &mut [TargetMessage],
     ) -> Result<usize, Self::Error>;
 }
 ```

 ---

 ## Phase 4: Crate Structure

 **Files:** `services/i2c/api/src/lib.rs`, `services/i2c/api/Cargo.toml`

 ### 4.1 lib.rs

 ```rust
 #![no_std]

 mod address;
 mod client;
 mod error;
 mod operation;
 mod target;

 pub use address::{AddressError, I2cAddress};
 pub use client::{BusIndex, I2cClient, I2cClientBlocking};
 pub use error::{I2cError, I2cErrorKind, ResponseCode};
 pub use operation::Operation;
 pub use target::{I2cTargetClient, TargetMessage};

 // Re-export for convenience
 pub use embedded_hal::i2c::{ErrorType, NoAcknowledgeSource};
 ```

 ### 4.2 Cargo.toml

 ```toml
 [package]
 name = "i2c-api"
 version = "0.1.0"
 edition = "2021"
 license = "Apache-2.0"
 description = "I2C client API traits for OpenPRoT"

 [dependencies]
 embedded-hal = "1.0"

 [features]
 default = []
 std = []
 mock = ["std"]

 [dev-dependencies]
 ```

 ---

 ## Phase 5: Build Configuration

 **File:** `services/i2c/api/BUILD.bazel`

 ```python
 load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

 rust_library(
     name = "i2c_api",
     srcs = glob(["src/**/*.rs"]),
     crate_name = "i2c_api",
     deps = [
         "@crates//:embedded-hal",
     ],
     visibility = ["//visibility:public"],
 )

 rust_test(
     name = "i2c_api_test",
     crate = ":i2c_api",
 )
 ```

 ---

 ## Phase 6: Mock Client (Testing Support)

 **File:** `services/i2c/api/src/mock.rs` (feature-gated with `mock`)

 ### 6.1 ExpectedCall struct

 ```rust
 pub struct ExpectedCall {
     pub bus: BusIndex,
     pub address: I2cAddress,
     pub write_data: Vec<u8>,
     pub response: Vec<u8>,
     pub result: Result<usize, I2cError>,
 }
 ```

 ### 6.2 MockI2cClient

 ```rust
 pub struct MockI2cClient {
     expected_calls: Vec<ExpectedCall>,
     call_index: usize,
 }

 impl embedded_hal::i2c::ErrorType for MockI2cClient {
     type Error = I2cError;
 }

 impl I2cClient for MockI2cClient {
     // Verify calls match expectations
 }
 ```

 Builder API:
 - `new() -> Self`
 - `expect_write_read(...) -> &mut Self`
 - `expect_transaction(...) -> &mut Self`
 - `verify(&self)` — assert all expected calls were made

 ---

 ## Phase 7: IPC Client Stub

 **Directory:** `services/i2c/client/`

 ### 7.1 Structure

 ```
 services/i2c/client/
 ├── Cargo.toml
 ├── BUILD.bazel
 └── src/
     └── lib.rs
 ```

 ### 7.2 I2cChannelClient

 ```rust
 pub struct I2cChannelClient {
     server_channel: pw_channel::Channel,
 }

 impl embedded_hal::i2c::ErrorType for I2cChannelClient {
     type Error = I2cError;
 }

 impl I2cClient for I2cChannelClient {
     // Wire protocol implementation
 }
 ```

 Wire protocol:
 - Request: `[op, bus, addr, write_len, write_data..., read_len]`
 - Response: `[status, data...]`

 **Dependencies:**
 - `i2c-api` crate
 - `pw_channel` (when available)

 ---

 ## Task Checklist

 | # | Task | File | Est. | Status |
 |---|------|------|------|--------|
 | 1 | Create `address.rs` with `AddressError`, `I2cAddress` | `src/address.rs` | 1h | ☐ |
 | 2 | Create `error.rs` with `I2cError`, `ResponseCode`, `I2cErrorKind` | `src/error.rs` | 1h | ☐ |
 | 3 | Create `operation.rs` with `Operation` enum | `src/operation.rs` | 15m | ☐ |
 | 4 | Create `client.rs` with `BusIndex`, `I2cClient`, `I2cClientBlocking` | `src/client.rs` | 2h | ☐ |
 | 5 | Create `target.rs` with `TargetMessage`, `I2cTargetClient` | `src/target.rs` | 1.5h | ☐ |
 | 6 | Create `lib.rs` with re-exports | `src/lib.rs` | 15m | ☐ |
 | 7 | Create `Cargo.toml` | `Cargo.toml` | 15m | ☐ |
 | 8 | Create `BUILD.bazel` | `BUILD.bazel` | 30m | ☐ |
 | 9 | Add unit tests for address validation | `src/address.rs` | 30m | ☐ |
 | 10 | Add unit tests for error conversions | `src/error.rs` | 30m | ☐ |
 | 11 | Create `mock.rs` with `MockI2cClient` | `src/mock.rs` | 1h | ☐ |
 | 12 | Create IPC client crate stub | `services/i2c/client/` | 1h | ☐ |

 **Total estimate:** ~9 hours

 ---

 ## Dependency Graph

 ```
 embedded-hal (external)
         │
         ▼
    ┌─────────┐
    │ i2c-api │  ◄── Phases 1-6
    └─────────┘
         │
         ▼
 ┌──────────────┐
 │ i2c-client   │  ◄── Phase 7 (IPC implementation)
 │ (pw_channel) │
 └──────────────┘
         │
         ▼
 ┌──────────────┐
 │ Application  │  (sensor drivers, MCTP, etc.)
 └──────────────┘
 ```

 ---

 ## Validation Criteria

 - [ ] `cargo build --no-default-features` succeeds (`no_std`)
 - [ ] `cargo test` passes all unit tests
 - [ ] `bazel build //services/i2c/api:i2c_api` succeeds
 - [ ] `I2cError` implements `embedded_hal::i2c::Error`
 - [ ] `I2cClient` uses `embedded_hal::i2c::ErrorType` as supertrait
 - [ ] `write_register` sends single contiguous wire write (verified by mock)
 - [ ] No `Vec`, `String`, or heap allocation in core crate (except `mock` feature)

 ---

 ## Risk Mitigation

 | Risk | Mitigation |
 |------|------------|
 | `pw_channel` API not finalized | Abstract behind trait; stub implementation |
 | `embedded-hal` 1.x breaking changes | Pin version in `Cargo.toml`, test on update |
 | Target mode notification design | Align with existing `hal/blocking` patterns |
 | IPC buffer size limits | Document 255-byte limit; provide direct `write`/`transaction` for larger |

 ---

 ## References

 - [I2C Client API Design](./i2c-client-api.md)
 - [Hubris I2C Architecture Review](./hubris-i2c-architecture-review.md)
 - [embedded-hal I2C traits](https://docs.rs/embedded-hal/latest/embedded_hal/i2c/)
 - [hal/blocking/src/i2c_device.rs](../../../hal/blocking/src/i2c_device.rs)
 - [hal/blocking/src/i2c_hardware.rs](../../../hal/blocking/src/i2c_hardware.rs)
	# I2C Client API Implementation Plan

	Version: 0.1.0
	Date: February 15, 2026
	Status: Planning

	---

	## Overview

	This document outlines the implementation plan for the I2C Client API as specified
	in [i2c-client-api.md](./i2c-client-api.md).

	---

	## Phase 1: Foundation Types

	Files: `services/i2c/api/src/address.rs`, `services/i2c/api/src/error.rs`

	### 1.1 AddressError enum

	```rust
	#[derive(Debug, Clone, Copy, PartialEq, Eq)]
	pub enum AddressError {
	OutOfRange(u8),
	Reserved(u8),
	}
	```

	- `Display` impl for error messages
	- `Debug`, `Clone`, `Copy`, `PartialEq`, `Eq` derives

	### 1.2 I2cAddress newtype

	```rust
	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
	pub struct I2cAddress(u8);
	```

	Methods:
	- `new(addr: u8) -> Result<Self, AddressError>` — validate 0x08-0x77
	- `new_unchecked(addr: u8) -> Self` — for reserved addresses
	- `value(self) -> u8` — raw accessor
	- `write_address(self) -> u8` — `(addr << 1) \| 0`
	- `read_address(self) -> u8` — `(addr << 1) \| 1`
	- `TryFrom<u8>` impl

	Unit tests:
	- Valid range acceptance
	- Reserved range rejection (0x00-0x07, 0x78-0x7F)
	- Out of range rejection (> 0x7F)
	- Unchecked escape hatch

	### 1.3 I2cError struct

	```rust
	#[derive(Debug, Clone, Copy, PartialEq, Eq)]
	pub struct I2cError {
	pub code: ResponseCode,
	pub kind: Option<I2cErrorKind>,
	}
	```

	- `impl embedded_hal::i2c::Error` with `kind()` mapping
	- `impl Display` for human-readable messages
	- Helper constructors: `from_code()`, `from_kind()`

	### 1.4 ResponseCode enum

	```rust
	#[derive(Debug, Clone, Copy, PartialEq, Eq)]
	#[repr(u8)]
	pub enum ResponseCode {
	Success = 0,
	NoDevice = 1,
	NackData = 2,
	ArbitrationLost = 3,
	BusStuck = 4,
	Timeout = 5,
	InvalidBus = 6,
	InvalidAddress = 7,
	BufferTooSmall = 8,
	BufferTooLarge = 9,
	NotInitialized = 10,
	Busy = 11,
	Unauthorized = 12,
	IoError = 13,
	ServerError = 14,
	}
	```

	- `from_u8(u8) -> Option<Self>` for wire decoding

	### 1.5 I2cErrorKind enum

	```rust
	#[derive(Debug, Clone, Copy, PartialEq, Eq)]
	pub enum I2cErrorKind {
	Bus,
	ArbitrationLoss,
	NoAcknowledge(NoAcknowledgeSource),
	Overrun,
	Other,
	}
	```

	- Re-export `embedded_hal::i2c::NoAcknowledgeSource`

	---

	## Phase 2: Core Traits

	Files: `services/i2c/api/src/client.rs`, `services/i2c/api/src/operation.rs`

	### 2.1 BusIndex newtype

	```rust
	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
	pub struct BusIndex(u8);
	```

	- `new(index: u8) -> Self`
	- `value(self) -> u8`
	- Constants: `BUS_0`, `BUS_1`, `BUS_2`

	### 2.2 Operation enum

	```rust
	#[derive(Debug)]
	pub enum Operation<'a> {
	Write(&'a [u8]),
	Read(&'a mut [u8]),
	}
	```

	### 2.3 I2cClient trait

	```rust
	use embedded_hal::i2c::ErrorType;

	pub trait I2cClient: ErrorType {
	fn write_read(
	&mut self,
	bus: BusIndex,
	address: I2cAddress,
	write: &[u8],
	read: &mut [u8],
	) -> Result<usize, Self::Error>;

	fn transaction(
	&mut self,
	bus: BusIndex,
	address: I2cAddress,
	operations: &mut [Operation<'_>],
	) -> Result<(), Self::Error>;
	}
	```

	### 2.4 I2cClientBlocking trait

	```rust
	pub trait I2cClientBlocking: I2cClient {
	fn write(...) -> Result<(), Self::Error>;
	fn read(...) -> Result<usize, Self::Error>;
	fn read_register(register: u8, buffer: &mut [u8]) -> Result<usize, Self::Error>;
	fn write_register(register: u8, value: &[u8]) -> Result<(), Self::Error>;
	fn probe(...) -> Result<bool, Self::Error>;
	}

	impl<T: I2cClient> I2cClientBlocking for T {}
	```

	Note: `write_register` concatenates register + value into single contiguous write.

	---

	## Phase 3: Target Mode

	File: `services/i2c/api/src/target.rs`

	### 3.1 TargetMessage struct

	```rust
	#[derive(Debug, Clone)]
	pub struct TargetMessage {
	pub source_address: I2cAddress,
	data: [u8; 255],
	len: u8,
	}
	```

	Methods:
	- `data() -> &[u8]`
	- `len() -> usize`
	- `is_empty() -> bool`
	- `Default` impl

	### 3.2 I2cTargetClient trait

	```rust
	use embedded_hal::i2c::ErrorType;

	pub trait I2cTargetClient: ErrorType {
	fn configure_target_address(
	&mut self,
	bus: BusIndex,
	address: I2cAddress,
	) -> Result<(), Self::Error>;

	fn enable_receive(&mut self, bus: BusIndex) -> Result<(), Self::Error>;

	fn disable_receive(&mut self, bus: BusIndex) -> Result<(), Self::Error>;

	fn wait_for_messages(
	&mut self,
	bus: BusIndex,
	messages: &mut [TargetMessage],
	timeout: Option<Duration>,
	) -> Result<usize, Self::Error>;

	fn register_notification(
	&mut self,
	bus: BusIndex,
	notification_mask: u32,
	) -> Result<(), Self::Error>;

	fn get_pending_messages(
	&mut self,
	bus: BusIndex,
	messages: &mut [TargetMessage],
	) -> Result<usize, Self::Error>;
	}
	```

	---

	## Phase 4: Crate Structure

	Files: `services/i2c/api/src/lib.rs`, `services/i2c/api/Cargo.toml`

	### 4.1 lib.rs

	```rust
	#![no_std]

	mod address;
	mod client;
	mod error;
	mod operation;
	mod target;

	pub use address::{AddressError, I2cAddress};
	pub use client::{BusIndex, I2cClient, I2cClientBlocking};
	pub use error::{I2cError, I2cErrorKind, ResponseCode};
	pub use operation::Operation;
	pub use target::{I2cTargetClient, TargetMessage};

	// Re-export for convenience
	pub use embedded_hal::i2c::{ErrorType, NoAcknowledgeSource};
	```

	### 4.2 Cargo.toml

	```toml
	[package]
	name = "i2c-api"
	version = "0.1.0"
	edition = "2021"
	license = "Apache-2.0"
	description = "I2C client API traits for OpenPRoT"

	[dependencies]
	embedded-hal = "1.0"

	[features]
	default = []
	std = []
	mock = ["std"]

	[dev-dependencies]
	```

	---

	## Phase 5: Build Configuration

	File: `services/i2c/api/BUILD.bazel`

	```python
	load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

	rust_library(
	name = "i2c_api",
	srcs = glob(["src/*/.rs"]),
	crate_name = "i2c_api",
	deps = [
	"@crates//:embedded-hal",
	],
	visibility = ["//visibility:public"],
	)

	rust_test(
	name = "i2c_api_test",
	crate = ":i2c_api",
	)
	```

	---

	## Phase 6: Mock Client (Testing Support)

	File: `services/i2c/api/src/mock.rs` (feature-gated with `mock`)

	### 6.1 ExpectedCall struct

	```rust
	pub struct ExpectedCall {
	pub bus: BusIndex,
	pub address: I2cAddress,
	pub write_data: Vec<u8>,
	pub response: Vec<u8>,
	pub result: Result<usize, I2cError>,
	}
	```

	### 6.2 MockI2cClient

	```rust
	pub struct MockI2cClient {
	expected_calls: Vec<ExpectedCall>,
	call_index: usize,
	}

	impl embedded_hal::i2c::ErrorType for MockI2cClient {
	type Error = I2cError;
	}

	impl I2cClient for MockI2cClient {
	// Verify calls match expectations
	}
	```

	Builder API:
	- `new() -> Self`
	- `expect_write_read(...) -> &mut Self`
	- `expect_transaction(...) -> &mut Self`
	- `verify(&self)` — assert all expected calls were made

	---

	## Phase 7: IPC Client Stub

	Directory: `services/i2c/client/`

	### 7.1 Structure

	```
	services/i2c/client/
	├── Cargo.toml
	├── BUILD.bazel
	└── src/
	└── lib.rs
	```

	### 7.2 I2cChannelClient

	```rust
	pub struct I2cChannelClient {
	server_channel: pw_channel::Channel,
	}

	impl embedded_hal::i2c::ErrorType for I2cChannelClient {
	type Error = I2cError;
	}

	impl I2cClient for I2cChannelClient {
	// Wire protocol implementation
	}
	```

	Wire protocol:
	- Request: `[op, bus, addr, write_len, write_data..., read_len]`
	- Response: `[status, data...]`

	Dependencies:
	- `i2c-api` crate
	- `pw_channel` (when available)

	---

	## Task Checklist

	\| # \| Task \| File \| Est. \| Status \|
	\|---\|------\|------\|------\|--------\|
	\| 1 \| Create `address.rs` with `AddressError`, `I2cAddress` \| `src/address.rs` \| 1h \| ☐ \|
	\| 2 \| Create `error.rs` with `I2cError`, `ResponseCode`, `I2cErrorKind` \| `src/error.rs` \| 1h \| ☐ \|
	\| 3 \| Create `operation.rs` with `Operation` enum \| `src/operation.rs` \| 15m \| ☐ \|
	\| 4 \| Create `client.rs` with `BusIndex`, `I2cClient`, `I2cClientBlocking` \| `src/client.rs` \| 2h \| ☐ \|
	\| 5 \| Create `target.rs` with `TargetMessage`, `I2cTargetClient` \| `src/target.rs` \| 1.5h \| ☐ \|
	\| 6 \| Create `lib.rs` with re-exports \| `src/lib.rs` \| 15m \| ☐ \|
	\| 7 \| Create `Cargo.toml` \| `Cargo.toml` \| 15m \| ☐ \|
	\| 8 \| Create `BUILD.bazel` \| `BUILD.bazel` \| 30m \| ☐ \|
	\| 9 \| Add unit tests for address validation \| `src/address.rs` \| 30m \| ☐ \|
	\| 10 \| Add unit tests for error conversions \| `src/error.rs` \| 30m \| ☐ \|
	\| 11 \| Create `mock.rs` with `MockI2cClient` \| `src/mock.rs` \| 1h \| ☐ \|
	\| 12 \| Create IPC client crate stub \| `services/i2c/client/` \| 1h \| ☐ \|

	Total estimate: ~9 hours

	---

	## Dependency Graph

	```
	embedded-hal (external)
	│
	▼
	┌─────────┐
	│ i2c-api │ ◄── Phases 1-6
	└─────────┘
	│
	▼
	┌──────────────┐
	│ i2c-client │ ◄── Phase 7 (IPC implementation)
	│ (pw_channel) │
	└──────────────┘
	│
	▼
	┌──────────────┐
	│ Application │ (sensor drivers, MCTP, etc.)
	└──────────────┘
	```

	---

	## Validation Criteria

	- [ ] `cargo build --no-default-features` succeeds (`no_std`)
	- [ ] `cargo test` passes all unit tests
	- [ ] `bazel build //services/i2c/api:i2c_api` succeeds
	- [ ] `I2cError` implements `embedded_hal::i2c::Error`
	- [ ] `I2cClient` uses `embedded_hal::i2c::ErrorType` as supertrait
	- [ ] `write_register` sends single contiguous wire write (verified by mock)
	- [ ] No `Vec`, `String`, or heap allocation in core crate (except `mock` feature)

	---

	## Risk Mitigation

	\| Risk \| Mitigation \|
	\|------\|------------\|
	\| `pw_channel` API not finalized \| Abstract behind trait; stub implementation \|
	\| `embedded-hal` 1.x breaking changes \| Pin version in `Cargo.toml`, test on update \|
	\| Target mode notification design \| Align with existing `hal/blocking` patterns \|
	\| IPC buffer size limits \| Document 255-byte limit; provide direct `write`/`transaction` for larger \|

	---

	## References

	- [I2C Client API Design](./i2c-client-api.md)
	- [Hubris I2C Architecture Review](./hubris-i2c-architecture-review.md)
	- [embedded-hal I2C traits](https://docs.rs/embedded-hal/latest/embedded_hal/i2c/)
	- [hal/blocking/src/i2c_device.rs](../../../hal/blocking/src/i2c_device.rs)
	- [hal/blocking/src/i2c_hardware.rs](../../../hal/blocking/src/i2c_hardware.rs)