# One contract from command to computation

Unify the developer interfaces without putting all responsibilities into one module or global cache.

Status: Local candidate · in review. Prelaunch; not a live service guarantee.
Native toolkit 0.1.0 is an unmerged review candidate, locally qualified on Linux x64. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

Reviewed: 2026-10-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/developer-architecture

> Centralize shared definitions. Keep effects and mutable data at explicit boundaries.

## The same operation has one owner

1. **One command contract** — CLI options, help, and the explicit MCP subset come from one typed Rust catalog. A new CLI command is not automatically an agent tool.

2. **One application read path** — The CLI and MCP share query handlers for local configuration, diagnostics, replay, and Atlas. Only their transport envelopes differ.

3. **One bounded operation context** — Each operation shares captured immutable file buffers and a normalized View index. The next request gets a fresh capture, not a global customer-state cache.

4. **Read-only dependency injection** — Read handlers receive a bounded ProjectReader with no writer, credential, shell, or network capability. The real Rust engine remains the decision owner.

5. **Protected generation** — Writes require --write. Planning and commit share conflict rules; changed configuration or managed guidance aborts the old plan.

6. **Two independent artifacts** — The service and native toolkit are packaged separately and tested without source or network. Local evidence is not a production release or live service guarantee.

## Borrow one View; capture one operation

A ProjectSnapshot keeps one normalized manifest and an ID-to-position index beside its ordered View payloads. Handlers borrow the selected View rather than copying it into another state store.

Each ReadSession shares immutable file buffers, misses, and errors within one operation. The limits are 128 file/presence observations, 2 MiB total captured content, and 300 KiB per file. Every subsequent MCP call gets a fresh capture.

This is not an atomic cross-file snapshot, a global tenant cache, a database migration, or a constant-time historical reconstruction guarantee. Only immutable embedded SDK/OpenAPI assets are shared process-wide.

## Inject reads, not permission to do everything

ProjectReader exposes bounded reads and presence checks. It has no writer, credential, shell, or network operation. Tests inject in-memory readers with counters and failures; production uses a checked filesystem adapter.

The canonical hashes and History/State engine are not replaceable through that interface. Local writes retain their source observations, acquire a cooperating-writer lock, recheck inputs, and re-plan against current target bytes. Changed config or guidance aborts a stale plan.

These controls protect cooperating local workflows. They do not claim an atomic multi-file transaction or a sandbox against a malicious filesystem owner.