# zc Strategy Memo
Snapshot date: 2026-07-04
This memo reconstructs the current state of the `zc` repository from the repository itself: source code, docs, workflows, changelog, and the active feature branch. It is intentionally conservative. Where the repository does not provide enough evidence, the item is marked as an inference or an open question.
## 1. Executive Summary
`zc` is a Rust command-line broker for the Zakuro ecosystem. Its primary job is to route compute requests, manage billing, discover workers, and expose operational tooling for local meshes and P2P deployments. The repository is already feature-rich: it includes broker routing, mesh orchestration, QUIC and VPN support, diagnostics, hooks for Zakuro Drive, and benchmark tooling.
The current branch, `feat/bench-mesh-warmup`, adds and documents `zc bench mesh`, a mesh warmup / calibration CLI that probes worker URIs and emits a JSON report with per-worker latency and backpressure guidance. The code exists on the branch; the main remaining gap is environment-backed validation because Cargo must fetch private git dependencies and the local toolchain/home layout is constrained.
The largest repository-wide risks are dependency reproducibility and operational drift between documentation, workflows, and live infrastructure. The feature branch is structurally sound, but full validation still needs a Cargo environment that can reach the necessary dependencies or a locally mirrored replacement.
## 2. Original Intent
The repository’s intent is to provide a single operational surface for the Zakuro broker:
- route compute requests to workers;
- manage credit-based billing and worker discovery;
- support local mesh orchestration and P2P networking;
- provide benchmark and diagnostic commands for operators;
- keep the broker usable as both a runtime component and an admin tool.
For `bench mesh` specifically, the intent reconstructed from the issue is narrower:
- expose the warmup / calibration flow as a CLI;
- probe a set of worker URIs from Rust;
- emit a machine-readable JSON report;
- make the output easy to pipe into `jq` or an operator tool.
## 3. Project Evolution
The repository appears to have evolved in stages:
1. **Broker and routing foundation.**
The early code focused on compute routing, billing, and worker management.
2. **Operational surface expansion.**
Mesh orchestration, diagnostics, TUI support, and VPN/P2P tooling were added so operators could control the system from the CLI.
3. **Benchmark and calibration tooling.**
The benchmark path expanded from throughput tests into more specialised mesh work, including the `bench mesh` calibration CLI on the current branch.
4. **Hardening and documentation alignment.**
The repository now carries changelog entries, user-facing docs, and explicit notes about private dependencies and release constraints.
## 4. Completed Work
### Core broker CLI
- **Purpose:** Start the broker, inspect the mesh, manage the runtime, and expose operational commands.
- **Evidence:** `src/main.rs`, `src/broker/*`, `docs/USAGE.md`, `README.md`.
- **Status:** Complete with limitations.
- **Limitations:** Some commands depend on network access, local Docker, or a configured broker environment.
### Mesh orchestration
- **Purpose:** Manage a local Docker compute-node mesh and broker.
- **Evidence:** `src/mesh.rs`, `zc mesh` command wiring, docs and help text.
- **Status:** Complete.
- **Limitations:** Local Docker and image availability remain environmental prerequisites.
### Benchmarking
- **Purpose:** Measure throughput and routing strategies under load.
- **Evidence:** `src/broker/bench.rs`, `docs/USAGE.md`, `README.md`, changelog entries.
- **Status:** Complete with limitations.
- **Limitations:** Benchmark numbers are environment-specific and should not be over-interpreted.
### Mesh warmup / calibration CLI
- **Purpose:** Expose the worker warmup flow as `zc bench mesh`.
- **Evidence:** `src/broker/bench_mesh.rs`, `src/main.rs`, `README.md`, `docs/USAGE.md`, `CHANGELOG.md`.
- **Status:** Implemented on branch and documented.
- **Limitations:** Full validation is blocked by the current Cargo/home/network constraints.
### Governance and baseline hygiene
- **Purpose:** Keep the repository maintainable and legally coherent.
- **Evidence:** Root `LICENSE`, contributor docs, changelog, and workflow hardening from the broader branch history.
- **Status:** Complete with limitations.
- **Limitations:** Private git dependencies still complicate reproducible local builds.
## 5. Current State
| Broker CLI | Complete with limitations | `src/main.rs`, docs, help text | Keep commands and docs aligned | Medium | Review docs whenever new subcommands land |
| Mesh orchestration | Complete | `src/mesh.rs`, `zc mesh` wiring | Maintain Docker/image compatibility | Medium | Validate on the next image or Docker change |
| Benchmarking | Complete with limitations | `src/broker/bench.rs`, docs | Preserve benchmark semantics | Medium | Keep workload descriptions current |
| Mesh warmup CLI | Implemented, awaiting full validation | `src/broker/bench_mesh.rs`, docs, changelog | Validate in an environment with writable Cargo state and reachable deps | High | Run the feature branch in CI or a toolchain-enabled environment |
| Dependency reproducibility | Blocked | Private git deps in `Cargo.toml` | Reduce dependency fetching friction | High | Keep the local/CI setup aligned with the private repo layout |
| Release hygiene | Complete with limitations | Changelog and docs | Keep versioning and release notes in sync | Medium | Update changelog per feature branch |
## 6. Remaining Work
1. **Validate the feature branch fully.**
Why it matters: the code is present, but the branch should not be merged on assumption alone.
Dependencies: a writable Cargo home, a usable Rust toolchain, and dependency resolution for the private git crates.
Risk if omitted: a branch that looks complete but fails under real build conditions.
Recommended next step: rerun the narrow `bench_mesh` test target in CI or in a build environment with the required dependency access.
2. **Keep the docs in step with the command set.**
Why it matters: operators will otherwise miss `zc bench mesh`.
Dependencies: README, `docs/USAGE.md`, changelog.
Risk if omitted: the feature exists but remains undiscoverable.
Recommended next step: update the docs whenever the mesh report schema changes.
3. **Keep private dependency handling explicit.**
Why it matters: this repository depends on private Git sources and that affects local development and CI.
Dependencies: `zakuro` and `zakuro-drive` repositories.
Risk if omitted: repeated “works on one machine” failures.
Recommended next step: preserve the documented dependency story and avoid silently changing it.
## 7. Risks and Open Questions
- Can the current feature branch be built in CI without special environment workarounds?
- Is the JSON report schema stable enough to treat as a user-facing contract?
- Should the bandwidth probe remain HTTP-based v1, or should it eventually be upgraded to the postcard/QUIC path described in the source comments?
- What is the cleanest way to validate the private git dependencies in a reproducible environment?
## 8. Status Matrix
| Broker CLI | Complete with limitations | `src/main.rs`, docs | Keep docs current | Medium | Update user docs when commands change |
| Mesh orchestration | Complete | `src/mesh.rs` | Keep Docker compatibility aligned | Medium | Validate on image changes |
| Benchmarking | Complete with limitations | `src/broker/bench.rs` | Keep benchmark docs honest | Medium | Update examples when output changes |
| Mesh warmup CLI | Implemented, awaiting validation | `src/broker/bench_mesh.rs` | Confirm build/test in CI | High | Run a dependency-capable test environment |
| Private deps | Blocked | `Cargo.toml` git dependencies | Make local/CI resolution reproducible | High | Keep dependency overrides explicit |
| Documentation | In progress | `README.md`, `docs/USAGE.md`, `CHANGELOG.md` | Keep docs aligned with CLI | Low | Revisit docs when the CLI changes |
## 9. Recommended Next Steps
### Immediate
- Keep the current docs changes with the feature branch.
- Validate `bench_mesh` in an environment where Cargo can resolve the private git dependencies.
### Short term
- Review whether the v1 HTTP probe path is sufficient for the current release or whether the QUIC/postcard follow-up should be scheduled.
- Keep the changelog in step with the branch before merge.
### Medium term
- Reduce friction around the private dependency path if the repository is going to stay on this release model.
- Preserve parity between the Rust CLI, the Python warmup flow, and operator docs.
## 10. Final Assessment
`zc` is in good structural shape, and `feat/bench-mesh-warmup` is a credible implementation of the requested CLI. The main gap is not design quality; it is validation under the repository’s real dependency constraints. The right next step is to keep the docs and changelog aligned, then validate in a build environment that can actually resolve the private git sources.