rusty-can — Clean-Room Specification Set

This repository contains a clean-room functional specification for an open-source J1939 CAN bus toolkit. It exists so that a fresh implementation can be built from these documents alone, with no reference to any prior source code, producing a codebase whose expression is independently authored while its behavior matches the documented contract.

What this is (and is not)

• It is a behavior-and-interface specification: what each component does, the wire/file/CLI formats it honors, and the algorithms (as processes) it must implement. Everything here is traceable to either observed behavior or a public standard.
• It is not a copy, paraphrase, or transcription of any existing source code. No source text, comments, file organization, or other copyrightable expression from any prior project appears in these documents. Under U.S. copyright law (17 U.S.C. § 102(b)), ideas, procedures, processes, methods of operation, and facts are not protectable; expression is. This spec captures only the former.

The two-role firewall

A clean-room effort separates two roles that must not be the same person at the same time, and whose artifacts flow in one direction only:

   ┌─────────────────┐    specs (this repo)    ┌──────────────────┐
   │  SPEC AUTHORS    │ ──────────────────────► │  IMPLEMENTERS     │
   │ (may read prior  │   behavior + interface  │ (NEVER read prior │
   │  source/docs)    │   + standards only      │  source or docs)  │
   └─────────────────┘                          └──────────────────┘

• Spec authors may study prior implementations to discover behavior, but record only function, interface, and method — never expression.
• Implementers build solely from this repository plus the cited public standards. They must never have access to the prior source.

See spec/00-clean-room-protocol.md for the binding rules, evidence conventions, and sign-off log.

Layout

rusty-can/
├── README.md                  ← you are here
└── spec/
    ├── 00-clean-room-protocol.md           governance, firewall, evidence rules
    ├── 01-glossary-and-normative-references.md   terms + public standards
    ├── 02-system-overview.md               functional component model
    ├── 03-licensing-provenance-and-shippability.md  DBC IP rule, prior-source firewall, what ships
    ├── 1x-*.md                             core library (CAN, codegen, J1939, codec)
    ├── 2x-*.md                             CLI binaries
    ├── 4x/5x/6x-*.md                       simulator, websocket protocol, config
    └── 7x-*.md                             build, packaging, acceptance suite

The reimplementation lives in impl/, alongside spec/: because the spec layer is expression-free, the implementer works in the same repo without contamination. The prior source stays out of this repo entirely.

impl/
├── Cargo.toml              ← workspace (edition 2024, resolver 2)
├── rust-toolchain.toml     ← pinned toolchain / MSRV
├── crates/
│   ├── rcan-core/          ← core library (frame model; codec/J1939 land per roadmap)
│   ├── rcan-can/           ← SocketCAN transport layer (open/send/recv; Linux-only OS surface)
│   ├── rcan-dbc/           ← DBC input layer (clean-room parser → typed model; maintainer-side, not shipped)
│   └── acceptance/         ← spec/72 acceptance suite harness (G1–G8)
└── docs/
    ├── binary-names.md         rcan-* binary-name contract
    ├── transport-conformance.md   P1.2 CAN transport conformance choices (spec/10)
    └── clean-room-attestation.md   firewall attestation scaffold (G8)

Status

Specification set complete — all 29 documents authored and reviewed for firewall compliance (see spec/00 §7 for the document map). rusty-can is a clean-room successor to two off-limits prior codebases — proteus-rs (the authored original, with licensed-IP device support) and cando-rs (a disputed J1939-only derivative); see spec/03 for provenance, the licensed-DBC rule, and what may ship. Scope is J1939 device support only; the licensed proprietary DBCs are used solely as codec/codegen test inputs, never shipped.

The set covers governance, the full J1939/CAN core (codec, addressing, diagnostics, codegen), all 10 CLI binaries, the simulator and its WebSocket protocol, configuration, build/cross-compilation, packaging, and the acceptance/equivalence suite that defines "done" (spec/72).

Implementation has begun under impl/, following the bottom-up build roadmap. A clean-room engineer builds from spec/ + the cited public standards (never the prior source) and proves correctness against spec/72. The current phase is E1 / P1.1 — Skeleton & harness: a workspace that compiles green plus an empty spec/72 acceptance harness, with the clean-room/licensing firewall wired in.

Building

The implementation is a Rust workspace in impl/:

cd impl
cargo build --workspace        # build everything
cargo test --workspace         # unit + integration tests
cargo run -p acceptance        # spec/72 acceptance suite (G1–G8 status)

The toolchain is pinned via impl/rust-toolchain.toml (edition 2024). The build requires no DBC files: the generated message code is committed as a build object (the "C compiler model", spec/12 §1). DBC inputs are needed only by a maintainer regenerating code, resolved from the private CAN_DBC_DIR directory (spec/03 §4). CI runs the Tier-1 gate — build, zero-warning clippy, tests, and the acceptance suite.

License

Licensed under either of Apache License 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion shall be dual licensed as above, without any additional terms or conditions.