TinyChannels is a Rust 2024 library crate rooted at Cargo.toml. Public API
exports live in src/lib.rs, with the crate-wide error type in src/error.rs.
The initial scaffold reserves two top-level module directories: src/channel/
for channel-side messaging abstractions and src/harness/ for harness-facing
communication boundaries.
Prefer small, focused modules that do one thing clearly. New feature areas
should live in module directories instead of accumulating broad multi-purpose
files. Within each module directory, keep shared type definitions in a
dedicated types.rs file and keep module-local unit tests in a dedicated
test.rs file. The module root should wire the pieces together and expose the
smallest useful API.
Integration tests belong in tests/ once behavior exists. Design notes and
module-level specifications live in docs/, with docs/spec/README.md as the
top-level architecture reference.
cargo fmt --check: verify Rust formatting without changing files.cargo fmt: format the crate before committing.cargo clippy --all-targets -- -D warnings: run lint checks for the library and tests, treating warnings as failures.cargo build --all-targets: compile all crate targets.cargo test: run the full test suite.
Run commands from the repository root unless a future workspace layout changes the crate location.
Use standard rustfmt output and Rust 2024 idioms. Module and file names should
be snake_case; public types and traits should be PascalCase; functions,
methods, fields, and local variables should be snake_case. Prefer small typed
APIs with Result<T> using the crate error type exported from src/error.rs.
Keep public exports centralized in src/lib.rs so downstream users have a
predictable surface.
Place integration tests in tests/ and use descriptive test names such as
serializes_channel_message. Add focused tests when changing serialization,
routing, transport adapters, lifecycle events, or public request/response
shapes.
Add or update tests with every behavior change, and document any intentionally untested edge case in the PR description.
Write documentation for public APIs, architecture decisions, examples, and
non-obvious behavior. Keep README.md, docs/spec/README.md, and module docs
aligned with code changes.
Keep every Markdown file, including AGENTS.md, at 500 lines or fewer. When a
topic grows past that limit, split it into focused files and link them from the
module's README.md. Complex modules should include a module-level README.md
that explains the design, public surface, and important operational
constraints.
Keep commit subjects concise and imperative. The first line should be specific to the change and avoid bundling unrelated work.
Pull requests should include a short summary, the commands run locally, and any API or behavior changes. Link related issues when available. Include updated examples or docs when public APIs, architecture, or expected usage changes.
Always make small, focused commits. Each commit should cover one logical change, build independently, and avoid mixing formatting, refactors, and behavior changes unless they are inseparable.