Crate cargoless_proto 

cargoless-proto — the cross-crate contract for cargoless.

This crate is the seam the daemon (watcher/analyzer/model), the build pipeline + CAS (build/cargoless-cas), the dev server (server), the CLI, and future remote backends communicate through. Cross-boundary data flows as these types; nobody reaches across a module boundary with a direct call. Authoring this jointly and freezing it early is the whole point of Plane CWDL-19 (D8) — the two-engineer split silently diverges otherwise.

Why dependency-free and serde-free in v0 (decision of record)

v0 is single-machine, single-process: every consumer of these types links cargoless-proto directly and passes them in-memory (channels / function args). Nothing crosses a process or network boundary, so nothing needs to be serialized. Adding serde now would (a) put a non-trivial dependency in the crate every other crate depends on, slowing the cold build that AC#1/#2 are measured against, and (b) freeze a wire format we have no v0 consumer for.

When a boundary genuinely needs serialization (the dev-server↔browser reload channel speaks WebSocket — decision D3 — and remote CAS is a v1 want), the owning crate adds serde here behind an off-by-default serde feature and derives it on exactly the types that cross that boundary. The contract shapes below are designed so that bolt-on is additive, never a reshape.

The data-flow at a glance

  watcher → analyzer → model ──StateEvent──▶ everyone (verdict stream)
                         │
                         └─on BecameGreen──▶ BuildTrigger ─▶ build/CAS
                                                                 │
                         server ◀──BuildResult── build/CAS ◀─────┘

The model is the single source of truth for “what works”; the build/CAS layer is the single source of truth for “is this exact input already built”. Everything else subscribes.

Structs

ArtifactMeta

Metadata persisted alongside every cached artifact in the CAS, and the payload the dev server consumes to decide whether to hot-reload the browser.

BuildIdentity

The complete set of inputs whose identity determines a build artifact.

BuildResult

Returned by the build/CAS layer for each BuildTrigger; consumed by the daemon (logging/state) and the dev server (reload decision — decisions D3 WebSocket signaling and D5 full-reload-not-hot-swap govern how the browser is told, not this contract).

BuildTrigger

Sent by the daemon to the build/CAS layer to request that a green input set be made servable. The only legitimate cause of a BuildTrigger is a StateEvent::BecameGreen — red inputs are never built (AC#4).

CheckResult

The rich one-shot check verdict: the existing boolean TreeState paired with the full diagnostic list a user needs to fix a red tree. Returned by the adjacent cargoless_core::model::check_once_with_diagnostics; existing callers of TreeState-returning APIs (check_once, frozen for cli-ux and the bench harness) are byte-unaffected.

ContentHash

An opaque content hash, rendered as a hex string.

Diagnostic

One actionable diagnostic, surfaced by the LSP layer and aggregated by the daemon model. Carries the absolute file path, 1-based (file:line:col) position, severity, optional compiler/lint code, the human message, and the diagnostic source string verbatim ("rustc" for cargo-check authoritative, "rust-analyzer" for native advisory, anything else for future tiers) so the CLI can both show provenance and the model can keep classifying authoritative-vs-advisory off the same value.

InputHash

The CAS key: the single digest derived from a BuildIdentity.

PointerFormatError

Returned by PublishedArtifact::parse when the pointer file is not the expected cargoless-latest-green/v1 shape. Dependency-free (no thiserror); a corrupt pointer is treated as “no green yet”, never half-decoded into a wrong artifact.

PublishedArtifact

The latest-green publisher record (decision D-A1; AC#4 “never publish red”). The build/CAS layer writes this beside the canonical pointer file .cargoless/latest-green on every servable green build; the CLI status reads it back. This is the only additive v0 contract surface — it does not touch the four frozen seams (StateEvent / BuildTrigger / BuildResult / ArtifactMeta) and adds no dependency: the on-disk form is a hand-rolled, versioned text codec (render / parse).

TargetTriple

The target triple a build is produced for (e.g. wasm32-unknown-unknown).

UnixSeconds

Wall-clock seconds since the Unix epoch (UTC). A newtype so a timestamp cannot be transposed with any other u64 at a call site. cargoless-proto is deliberately dependency-free, so there is no chrono/time here: the producer (cargoless-core::build) fills this from std::time::SystemTime; this crate only carries the value.

Enums

BuildOutcome

What the build/CAS layer did with a BuildTrigger.

FileState

Per-file compile verdict.

Profile

Cargo build profile. v0 inner-loop builds are always Profile::Dev (workspace [profile.dev] pins opt-level = 0, no wasm-opt, per the AC#3 latency constraint); Profile::Release exists in the contract so the identity is honest and a release build can never alias a dev artifact.

Severity

Diagnostic severity, derived from the LSP DiagnosticSeverity integers (1=Error, 2=Warning, 3=Information, 4=Hint). A typed enum so the CLI renders error/warning/info/hint headers without re-deriving from raw numbers, and so a future consumer can pattern-match exhaustively.

StateEvent

The event stream emitted by the daemon’s green/red model. Every other subsystem subscribes to this; nothing calls the model directly.

TreeState

Aggregate verdict for the whole watched tree.