# M1 implementation plan: workspace, `proto`, gate

> **For the implementing model:** do not work from this file. The owner gives you one task file at
> a time (`01-…` to `09-…`). This file is the index for the owner and the reviewer.

**Goal:** A Cargo workspace whose gate passes, with the real shared types in `proto` and a
`Decision` type in `brokerd` that code outside its policy module cannot construct.

**Architecture:** Seven crates under `crates/`. `proto` holds data types and the frame codec and
depends on no workspace crate. Every role crate is a library with a thin `main.rs` and depends only
on `proto`. Behaviour is pinned by test files and byte-exact fixtures that the design model wrote
and verified against a private reference implementation; the implementer writes the code.

**Tech stack:** Rust stable (edition 2024, `rust-version = "1.95"`), `serde` 1.0.229,
`serde_json` 1.0.151, `humantime` 2.4.0, `toml` 1.1.6 (tests only), `cargo-deny` 0.20.2, POSIX `sh`.

**Spec:** `docs/specs/2026-09-17-pre-m1-design.md`, sections 4, 5 and 8. Brief: `docs/design.md`.

## Global constraints

- No `unsafe` (`unsafe_code = "forbid"` as a workspace lint). No async runtime.
- No source file over 500 lines. No role crate depends on another role crate.
- Every external dependency is in `[workspace.dependencies]` and has a row in
  `docs/dependencies.md`. Crates are `publish = false`.
- Unknown fields are rejected everywhere. Field order is the wire format.
- `make gate` runs offline and must print `gate: ok` at the end of every task.
- Branch `m1`. One task, one fresh OpenCode session, one commit. Review happened once, after task
  07; tasks 08 and 09 are its follow-ups.

## Tasks

| # | File | Delivers | Tests that define it |
|---|---|---|---|
| 01 | `01-workspace-and-gate.md` | Workspace, seven crates, `Makefile`, `deny.toml`, three gate scripts, `docs/dependencies.md`, `docs/egress.md` | `scripts/test-gate-scripts.sh` |
| 02 | `02-proto-values.md` | `SessionId`, `Epoch`, `CallId`, `Hash32`, `Timestamp`, `ValueError`, `DataClass` | `tests/ids.rs` |
| 03 | `03-proto-wire.md` | `Envelope`, `Message`, `ToolRequest`, `ToolResponse`, `WireError`, `ErrorCode`, `DenyReason` | `tests/wire.rs`, `fixtures/wire/` |
| 04 | `04-proto-frame.md` | `read_frame`, `write_frame`, `FrameError`, `MAX_FRAME` | `tests/frame.rs`, `fixtures/frame/` |
| 05 | `05-proto-grant.md` | `Grant`, `Mode`, `Constraints` | `tests/grant.rs`, `fixtures/grant/` |
| 06 | `06-proto-records.md` | `DecisionRecord`, `AuditRecord`, `ToolCall`, `LogRecord` | `tests/records.rs`, `fixtures/records/` |
| 07 | `07-brokerd-decision.md` | `brokerd::policy::Decision`, `decide`, `brokerd::runner::run` | doctests and unit tests in `policy.rs` |
| 08 | `08-proto-strictness.md` | Review follow-up: unknown fields rejected in every struct; `Timestamp` bounded at year 9999 | `tests/strict.rs`, updated `tests/ids.rs` |
| 09 | `09-gate-scripts-table-form.md` | Review follow-up: gate scripts see table-form and dotted dependencies, and fail closed | updated `scripts/test-gate-scripts.sh` |

`files/` holds everything the tasks copy into place. Tests for a later task do not compile until
that task's types exist, which is why they are copied task by task and not all at once.

## For the owner: running a task

In `~/src/boxmaker`, start a fresh OpenCode session with Laguna S 2.1 and send:

> Read `docs/plans/M1/01-workspace-and-gate.md` and do exactly that task.

Then the next file in a new session, and so on. If a session ends with a `stopped` row in
`docs/implementer-log.md`, do not start the next task.

## For the reviewer: after task 07

1. `git log --oneline master..m1` shows seven commits (plus any `stopped` rows), each with the
   `Implemented-By` trailer.
2. Copied files are unchanged:
   `for f in $(cd docs/plans/M1/files && find . -type f); do cmp "docs/plans/M1/files/$f" "$f"; done`
3. `git diff master..m1 --stat -- docs/design.md docs/specs docs/plans AGENTS.md CLAUDE.md` is empty.
4. `make gate` prints `gate: ok`. `make audit` passes.
5. Read every non-test source file against its task: field order, no panics in library code, no
   `#[allow]`, no dependency the tasks did not name, error types as specified.
6. Write findings under "Reviews" in `docs/implementer-log.md`.