# __PROJECT__
A runnable Pipecircuit counter program. Add positive integers, then read the
final count:
```sh
cargo run -- 3 4
# count: 3 (was 0)
# count: 7 (was 3)
# snapshot: 7
cargo run -- 18446744073709551615 1
# Overflow is a semantic refusal; the count stays unchanged.
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
```
With no arguments, the program reads zero. Invalid arguments are refused before
starting work. The native application requires an OS supported by Mio; the core
and program libraries remain `no_std`. Framework dependencies use pinned registry releases by default.
`pipec new --framework-path` explicitly selects a local framework checkout.
## What you author
| Domain facts | `core/src/domain_primitives` | Positive `Amount`, arbitrary `Count` |
| Temporal authority | `core/src/state_machines` | `Counter`, exact `Add` and `Read` steps |
| Addressable contracts | `programs/src/pipes` | `Client` and `Counting`, independent input/output families |
| Semantic routing | `programs/src/switchboard` | `CounterProgram` routes each output to its destination |
| Physical installation | `src/wiring` | Named transports, bounds, admission, disconnect policy |
| Foreign peer | `src/client.rs` | CLI requests and display, ordinary Rust with no switchboard |
| Process lifecycle | `src/main.rs` | Argument validation, worker ownership, conduct, teardown and join |
Dependencies point inward: application → program → core. `app_core` and
`app_program` are Cargo dependency aliases, so directory/project renaming does
not change source imports. Both libraries share the same strict lint policy.
The complete circulation is:
```text
CLI thread → owned queue → client.Out
↓
CounterProgram
↓
counter.In
↓
inline CounterAuthority
↓
counter.Out
↓
CounterProgram
↓
CLI thread ← owned queue ← client.In
```
The switchboard names the obligations. `InstalledPipes` fills that exact roster;
its generated conduction dispatch does not repeat semantic route choices.
`MioHost::prepare(...)` opens the reactor for transport construction.
`host.install_program(...)` reserves source storage from the finished fixed
registration inventory and validates physical registrations, then
`pipecircuit.conduct()` owns circulation. The factory's `impl MioConductor<...>`
names the physical turn contract and exact outcomes; the installed closure
implements it automatically. It adds no trait implementation for the app author
and requires no box or `'static` state. Source-turn policy reserves room for
one reply before taking a request. That is justified by this installed inline
route's one-request/one-reply behavior, **not** a universal promise of a pipe.
## Change behavior first
For a new invariant, begin in the core machine and test its exact outcome. For
a new intent, begin with the pipe request family and follow what it requires
inward. For example, a reset operation needs a core transition, an exposed
request/reply, and a client display decision. Exhaustive matches identify the
places requiring a decision. The switchboard deliberately forwards the whole
request family here; it needs no new route when the same authority handles it.
`architecture.rs` derives the counter's shape from Rust source and checks it
against a readable expectation. Machine tests verify preservation on overflow;
CLI tests verify the installed program. Run `pipec diagram Counter --crate core`
for the current shape. These diagrams describe declarations, not runtime traces.
The empty `proofs.rs` and fuzz target directory are extension points, not claims
that proofs or fuzzing have been performed.
## Change placement separately
The client already runs on another thread without becoming a Pipecircuit.
To move the counter authority, keep the core, pipe contracts, and routes. Replace
its inline installation with an owned transport, give the peer authority an
owner, and handle its readiness, bounded admission, failure and shutdown. The
new source appears in source-turn dispatch. The compiler checks message and
nominal-pipe compatibility; tests must still check behavior across the new
asynchronous boundary. A thread alone needs no codec. A socket/foreign process
needs explicit framing, representation and compatibility policy.
This is a walkthrough of the obligations, not a promise of a completed thread
migration example. No new runtime abstraction is required by this starter.
## Bounds and lifecycle
Host poll capacity and dispatch quantum are explicit. Pending source capacity is
derived at installation: the client queue contributes one fixed wake claim and
the inline counter contributes none. Moving the counter to another queue adds its
own slot, even when both queues share the same OS wake. Socket registration
ranges instead require an explicit source-capacity budget; address-space width
is not connection capacity.
Queue and retained-reply capacities are explicitly one. The client allows one
outstanding request, while the installed route also gates admission against
retained-reply capacity. Fixed-size retention charges the owned enum's inline
size; it does not measure referenced heap storage. Changing the protocol to
heap-owning messages requires an explicit accounting policy.
The peer waits on actual reactor wakes. There are no cooldown sleeps or polling
delays. Queues and retention are allocated at setup; CLI arguments and output
formatting are application work. This starter is not a throughput benchmark and
makes no whole-process zero-allocation claim.
After consuming every reply, the client explicitly closes. Disconnect completes
conduction; it alone does not prove delivery. The client result establishes
whether the exchanges succeeded. Teardown reports abandoned retained replies,
closes the local endpoint, and joins the worker, including on conduction failure.
Managed completion notification wakes the host after a worker unwind. Process
abort, a blocked OS output sink, or a broken wake mechanism are outside the
starter's orderly-shutdown guarantee; there is no forced thread termination or
supervision deadline hidden in this example.