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.

crates/format

Pure byte-level storage format helpers: compression and delta encoding. No I/O, no policy; just the wire-and-disk byte shapes that objects and the storage backends serialize through.

crates/schema

Pure persisted schema models and codecs shared across the workspace: the OpRecord shape, ref models, and their encode/decode. Kept dependency-light so anything that reads or writes on-disk records can pull just the schema.

Coordinator

crates/core (published as heddle-core)

The embeddable Heddle facade: the ExecutionContext that carries verbosity and progress/warning sinks, plus the repo-level fsck and query surfaces. This is the entry point an embedder reaches for when driving Heddle in-process rather than through the CLI.

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/wire (published as heddle-wire)

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. (Renamed from proto/heddle-proto in v0.4.0.)

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, ProjFS on Windows, all behind a trait so the core stays pure Rust. Surfaces threads as a directory tree without checking them out. Off by default; enable fuse, fskit, or projfs 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 reflogs; converts each into a Heddle state with agent attribution and reasoning annotations. Drives the heddle-ingest binary and the bridge git import path; the ingest Cargo feature (on by default) also gates heddle bridge git reason, which mines local AI-coding-agent sessions for reasoning notecards.

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.