// Per-repo skill for the Peat mesh networking layer — pluggable transport, peer discovery, topology, routing, optional Automerge/Iroh CRDT sync, optional HTTP/WS broker.
| name | peat-mesh |
| description | Per-repo skill for the Peat mesh networking layer — pluggable transport, peer discovery, topology, routing, optional Automerge/Iroh CRDT sync, optional HTTP/WS broker. |
| when_to_use | Editing files under peat-mesh/, reviewing peat-mesh PRs, debugging peer/discovery/topology/routing/storage/broker issues, or working on ADR slices that touch mesh. |
| verifies_with | cargo fmt --check, cargo clippy -- -D warnings, cargo test, plus feature-flagged builds for any feature whose code paths the change touches. |
peat-mesh SKILLpeat-mesh is the mesh networking layer of the Peat ecosystem. It provides a pluggable Transport abstraction (BLE via peat-btle, lightweight bridge via peat-lite, IP), peer discovery (mDNS, Kubernetes CRD), topology and partition management, routing, an optional Automerge + Iroh + redb CRDT storage backend, and an optional HTTP/WS service broker. It's a Rust library (edition 2021) with an optional peat-mesh-node binary; other peat-* repos depend on it as a building block — peat-mesh does not depend on its consumers.
src/transport/, src/discovery/, src/topology/, src/routing/, src/storage/, src/broker/tests/Cargo.tomlADR-0001 through ADR-0011 in docs/adr/) or any ecosystem ADR that lands here. Recent ecosystem slices touching this repo: ADR-032 (BLE transport), ADR-035 (peat-lite bridge), ADR-042 (transport security), ADR-049 (security primitives), ADR-059 (translator) — these live in the sibling peat/docs/adr/, not in this repo.If you're editing a peat-* sibling repo and only consume peat-mesh as a dependency, this skill probably isn't the one you want.
In scope:
Transport trait surfaceCargo.tomlOut of scope (route elsewhere):
peat-btle/SKILL.mdpeat-lite/SKILL.mdpeat-node/SKILL.mdpeat-atak-plugin/SKILL.mdpeat/ (the ecosystem core crate) insteadNumbered steps. Skipping a step requires explicit user instruction.
peat/SKILL.md (ecosystem) if accessible. Read this file. Read CONTRIBUTING.md for the build matrix. git status, git log -10.docs/adr/) or propose a new one.main per the trunk-based convention. Vertical slices, one concern per commit. Match existing module boundaries — don't bleed transport logic into discovery, etc.main referencing the issue. Single concern per PR — peat-mesh squash-merges, so the PR title becomes the merge commit subject.A session in this repo is not done until each of these produces evidence:
cargo fmt --check exits 0cargo clippy -- -D warnings exits 0cargo test exits 0cargo test --features <flag> for each affected feature (automerge-backend, broker, kubernetes, bluetooth, lite-bridge). Build-only (cargo build --features <flag>) is not sufficient — feature-gated test paths only execute under cargo test --features, and recent ADR-049 / ADR-059 work lives entirely under feature gates.cargo test --features node exercises the combined feature set used by the binary../scripts/install-hooks.sh runs clean (it gates cargo fmt --check and cargo clippy -- -D warnings on every commit)"Seems right" or "the diff looks correct" is never sufficient.
| Excuse | Rebuttal |
|---|---|
| "This change is too small to need a test." | If it's worth changing, it's worth one assertion. Add the test. |
| "I'll fix the clippy warning later." | The CI gate is -D warnings. There is no later. Fix it before commit. |
| "This refactor is right next door — I'll just clean it up." | Out of scope. Open a separate issue if it matters. Squash-merge ≠ kitchen-sink PR. |
| "I only changed library code; the feature builds will pass." | Feature flags interact non-obviously with optional dependencies (especially iroh / ed25519 pinning). Run the affected feature builds locally. |
"I'll just import directly from peat-btle to avoid the Transport trait detour." | peat-mesh depends optionally on peat-btle (gated by bluetooth); the trait abstraction is the whole point. Cross-direction or non-trait imports break the abstraction and the dependency direction. |
| "The transport-level retry can live in the topology manager — same crate." | Transport-specific retry (link-level send/recv, framing) belongs in the transport adapter — topology must not assume any specific transport's retry semantics. Higher-layer retries — partition healing, route re-discovery — legitimately live above the transport seam (see ADR-0003) and are a different concern; do not collapse them into the same row of reasoning. |
| "I'll skip GPG signing this once — it's just a docs change." | Signing is a repo-policy gate, not a quality gate. Don't bypass. Fix the signing config instead. |
"I'll bump iroh to drop the pre-release ed25519/pkcs8 pins — it's cleaner." | Those pins exist because iroh 0.97/0.98 ship pre-release transitives that don't survive their own dep ranges under rustc ≥1.95. Remove only after verifying upstream actually fixed it (see the comment in Cargo.toml). |
discovery, topology, routing, or storage modules. The Transport trait is the seam.peat-mesh consumers (peat-node, peat-btle, peat-lite, etc.) as peat-mesh dependencies. The dependency direction is one-way.--no-verify to skip the pre-commit hook.Add an entry each time a session produces output that needed correction. One line per gotcha plus a Why: line.
AutomergeStore::put is wholesale-byte-replace at the doc-key level; any get→modify→put sequence on the same key must hold store.lock_doc(&key) across the whole sequence.
Why: two concurrent load-modify-write cycles for the same key silently drop one writer (last put wins) regardless of typed-field structure inside the doc — surfaced as 6/8 lost writes in a concurrent-spawn test during the peat#868 substrate fix.AutomergeBackend::start_sync) silently swallows the per-peer error from sync_document_with_all_peers (let _ = e); anything that returns Err from initiate_sync is dropped with no retry.
Why: returning FlowControlError::CooldownActive there meant back-to-back local writes within the 100ms cooldown never reached peers — the root of peat#864's missing-frame symptom. Defer (sleep the remaining cooldown) instead of erroring on that path.FlowController.sync_cooldown is defer-not-drop on the auto-sync path as of rc.10; don't "simplify" initiate_sync back to fast-fail on cooldown.
Why: the regression test pins both the timing (≥80ms wait) and error-shape (no CooldownActive surfaced); a revert silently re-opens peat#864.peat/SKILL.md (sibling repo)CONTRIBUTING.mddocs/adr/ — repo-local ADRs use 4-digit padded form (ADR-0001 through ADR-0011)peat/docs/adr/ (sibling repo) — ecosystem ADRs use 3-digit form (ADR-032, ADR-049, etc.); these are the IDs cited in this repo's Cargo.toml comments and recent commitsiroh / ed25519 / pkcs8 pin rationale: comment block in Cargo.toml around the automerge-backend depsAGENTS.md (do not duplicate skill content there)Last updated: 2026-05-05 Maintained by: Kit Plummer, VP Data and Autonomy, Defense Unicorns