Crate tour

Core object model

crates/objects

The object model — blobs, trees, states, actions — and the storage abstraction (ObjectStore trait). Everything content-addressed; everything immutable. If you need to add a new object kind, you add it here first; the rest of the workspace consumes from this crate.

crates/refs

Thread, marker, and HEAD reference management. Supports packed-refs for repos with thousands of refs (the same optimisation Git uses). Locking lives here too: ref updates take a per-ref lock to avoid concurrent-write collisions.

crates/oplog

The append-only operation log. Every state-changing action writes an OpRecord; the chain is checksum-linked so corruption is detectable. Undo / redo logic lives here — scoped by checkout's HEAD-path so multi-agent undo doesn't trample independent work. See the oplog concept for the user-facing framing.

crates/crypto

State signature signing and verification. Three algorithms ship: Ed25519 (default), RSA, P-256. The Signer trait is the integration seam — any key source that implements it works, including hardware tokens and external KMS.

Coordinator

crates/repo

The Repository type that coordinates between objects, refs, oplog, worktree, hooks, and merge operations. Most CLI commands take a Repository handle and operate through it. Two execution models live behind one type: standard repos with heddle_dir == root/.heddle and agent checkouts with shared-store pointers.

Entry points

crates/cli (published as heddle-cli)

The local CLI entry point — argument parsing, command dispatch, harness integration. Args are defined in cli/cli_args/commands_<name>.rs; implementations in cli/commands/<name>.rs. Hosted-only commands (auth, support, presence) are gated behind the client Cargo feature and dispatch through the WeftExtensions trait surface. The CLI reference is grounded against these files (after a brutal lesson on fabrication).

crates/daemon (published as heddle-daemon)

The local-mode gRPC daemon. Hosts the in-process service impls that heddle agent serve exposes over a Unix socket. Carved out of the original server crate at the OSS split so the local agent path doesn't pull in any hosted dependencies.

crates/cli-shared (published as heddle-cli-shared)

The small set of CLI-side types shared between OSS heddle-cli and the closed weft-client: UserConfig, ClientConfig, RemoteTarget. Pulled out so neither side directly depends on the other.

crates/grpc (published as heddle-grpc)

Generated gRPC surface — proto definitions and service bindings. The local daemon speaks this over a Unix socket; the hosted server (in HeddleCo/weft) speaks it over TLS. The proto source ships inside the crate so consumers don't need a workspace-root proto/ directory.

crates/proto (published as heddle-proto)

Shared protocol and auth transport types — message definitions that both client and server side import. Smaller than grpc: this is the data shape, not the transport.

The OSS / closed seam

crates/weft-client-shim (published as weft-client-shim)

The public trait surface between the OSS CLI and the hosted client — defines WeftExtensions and CliContext, plus a NoopWeftExtensions that builds without the client feature use to return "Hosted features not enabled" errors. Lives in the OSS workspace so any future hosted implementation can target a stable public contract.

crates/client (published as heddle-client)

The hosted-backend gRPC client and its command implementations — auth (device-flow login), support (time-bounded grants), presence (publisher), and the credential store. Provides the real implementations of the WeftExtensions trait surface declared in weft-client-shim. The CLI links it optionally via the client Cargo feature; OSS-only builds skip it entirely.

The hosted server itself lives in a separate closed workspace and isn't part of this docs surface. The OSS CLI links into it at build time via the client feature when a hosted-enabled binary is being produced.

Platform-specific subsystems

crates/mount

The filesystem virtualization layer. FUSE on Linux, FSKit on macOS — both behind a trait so the core stays pure Rust. Surfaces threads as a directory tree without checking them out. Off by default; enable fuse or fskit features explicitly. macOS FSKit is scaffolded but kernel registration is stubbed; FUSE shell is production-ready.

crates/ingest

Git history importer. Walks a Git repo's commits, refs, and reflog; converts each into a Heddle state with agent attribution. Powers the feature-gated heddle bridge git ingest subcommand — distinct from bridge git import, which is a lighter local-branch import.

crates/semantic

Code-aware diff and structural inspection. Symbol extraction, function/file change detection, the building blocks of "diff that knows what moved." Powers heddle blame and the semantic-compare flag on heddle diff.

crates/merge

Native hunk-level three-way text merge. The line-based engine the semantic merger and other tooling fall through to when path- or symbol-level reconciliation declines. Identifies disjoint hunks via diff3-style alignment and emits per-hunk conflict markers — matching git's baseline competence. Kept separate from semantic so non-semantic CLI builds retain text-level auto-merge.

Review subsystem

crates/review

The review-analysis domain and the GitHub-backed pipeline that computes review payloads on incoming PRs. Risk-signal computation is delegated to state_review for purity / testability.

crates/state_review

Pure functions that compute the in-budget review signals: novelty, test reachability, pattern deviation, invariant adjacency, self-flagged uncertainty. Same surface that heddle review show renders; same surface heddle review health aggregates across a window of states.

Utilities

crates/devtools

Developer utilities — protocol audit, idempotency checkers, fixtures. Not shipped as part of the user-facing CLI; used by tests and by maintainers when diagnosing protocol drift.

crates/runtime-bridge

The sync→async runtime bridge. A worker thread owns a private current-thread Tokio runtime; synchronous code hands futures over an mpsc channel and blocks on a reply. Used by storage backends whose trait surface is sync but whose underlying I/O is async (aws-sdk-s3, sqlx). Sidesteps the three failure modes of naive bridges — nested-runtime panics, current-thread block_in_place panics, and the non-Tokio caller case.

Next

• Architecture overview — the higher-level concepts that span crates.
• Operating principles — the CLI's behaviour contract.