CueCruxVaultCrux

Crux Daemon · 3. The crate map

The workspace has 28 members, and three further Rust crates live in-tree outside it. This chapter is reference: the complete inventory, in one place, with the reverse-dependency map and the honest notes about what is orphaned or inert.

Measurements are lines across <crate>/src/**/*.rs, including inline #[cfg(test)] modules, at workspace version 0.5.52.

3.1 The complete inventory

#CrateKindFilesLOCCargo featuresDependents
1corecrux-typeslib42,545-4
2corecrux-framelib2345-6
3corecrux-protolib + build.rs198-3
4corecrux-receiptslib2417,639-4
5corecrux-segmentlib134,182-5
6corecrux-storagelib912,783fuzzing3
7corecrux-projectionslib1712,604-5
8corecrux-indexlib41,108-5
9corecrux-retrievallib + bench62,044-2
10corecrux-memorylib2418,727llm, dense-embed-model5
11crux-synclib51,354-2
12crux-contriblib2165-0, orphan
13crux-integrationslib43,465-3
14crux-observelib92,538-2
15crux-observe-apilib1776-1
16crux-costlib62,156-2
17vaultcrux-locallib3570-2
18crux-config-wizardlib + bin112,579-1
19crux-lens-featureslib3493-2
20crux-mcplib7741,878-1
21crux-sessionlib155,789-6
22rcx-capability-tokenlib13,139-7
23crux-routerlib32,349-2
24crux-enterprise-shimlib1556-1
25corecruxdbin only + build.rs155151,433otel, wasm-extensions, dense-embed-model, hosted-surfaces0
26corecruxctllib + bin + build.rs5246,615-0
27crux-claude-hookslib + 2 bins2710,034-0
28crux-integration-testslib (test harness)1552-0
Total520348,516

corecruxd has no lib.rs; everything is in the binary crate. rcx-capability-token, crux-observe-api, crux-enterprise-shim and crux-integration-tests are each a single file.

Five binaries are produced across four crates:

BinaryCrateManifest
corecruxdcorecruxdimplicit src/main.rs, Cargo.toml:2
corecruxctlcorecruxctlimplicit src/main.rs, Cargo.toml:2
crux-hookcrux-claude-hooksCargo.toml:10-12
crux-llm-shimcrux-claude-hooksCargo.toml:19-21
crux-config-wizardcrux-config-wizardCargo.toml:12-14

3.2 What each crate is for

Purpose is taken from the crate's own module documentation; the link goes to it.

CratePurposeModule doc
corecrux-typesFoundational data types shared across every crate: evidence types, control evidence, decision-plane types. Deliberately a leaf with minimal dependencies so nothing introduces a cycle. JSON via serde.lib.rs:6
corecrux-frameCanonical frame encoding for on-disk data. The v1 header layout, hash helpers, and the encoder/decoder used by corecrux-segment and downstream replay. Pure types and bit-level layout, no I/O.lib.rs:6
corecrux-protoA 98-line tonic::include_proto! wrapper with exactly two modules, dataplane_v1 and observe_v1. Proto sources live in proto/.lib.rs:6
corecrux-receiptsReceipts stored as opaque canonical bytes, signature verification, export bundles. Hashing operates over the stored bytes exactly, with no re-serialisation. Ed25519 CROWN receipt signing.lib.rs:8
corecrux-segmentThe sealed segment format. An active segment accepts appended frames; at its size threshold it is sealed, a table of contents is written, a BLAKE3 hash covers the whole file, and the segment becomes immutable. LZ4 frame compression, paired with .ccxi companions.lib.rs:8
corecrux-storageThe append-only shard storage engine. Events are hash-partitioned across shards, written to active segments, sealed when full. Each shard has its own directory, manifest and commit markers for crash recovery. Append with backpressure, deterministic replay, integrity verification, epoch-based shard ownership.lib.rs:6
corecrux-projectionsLiving Objects projections, snapshots and parity harness plumbing. Deliberately deterministic: sorted key orders, integer-only state, stable snapshot encoding.lib.rs:6
corecrux-indexThe .ccxi companion index, a seal-time inverted index built alongside sealed segments. Per-token posting lists (PForDelta compressed), per-document metadata, vocabulary table.lib.rs:6
corecrux-retrievalFused retrieval. Loads .ccxi companions, builds a merged inverted index, and scores queries with BM25 plus graph signals from ProjectionState. Also exposes the pluggable dense lane.lib.rs:6
corecrux-memoryThe fact, session, entity, edge and case stores, plus embeddings. The richest module doc in the workspace. CI enforces a 93% coverage floor.lib.rs:6
crux-syncOutbox sync client. Offline-first: contributions are written to a local outbox, then pushed on connectivity. Handles authentication, retry with exponential backoff and cursor tracking. CI enforces a 98% coverage floor.lib.rs:6
crux-contribContribution manifest builder and envelope signing, content-addressed references with Ed25519 signatures. Linked into nothing. See §3.5.lib.rs:6
crux-integrationsThe manifest contract for integration packs. "Version 1 is intentionally declarative: packs can describe MCP, HTTP, SDK, CLI, file watcher, and webhook recipes, but they do not execute code inside the daemon process." That sentence is the load-bearing security statement of the extension system.lib.rs:6
crux-observeThe self-observation layer. Captures operational events, errors, warnings, metrics, health, and bootstrap documentation as facts in the memory subsystem, so the daemon can reason about its own history. Also owns the log redactor.lib.rs:6
crux-observe-apiShared wire types for the agent audit-chain data contract. A deliberately frozen schema, the agent_trace_node projection, the mutation-step mapping table, and the reasoning-capture policy. The leanest contract crate in the workspace.lib.rs:6
crux-costThe three-step cost model. Zero workspace dependencies and two external ones, the easiest crate for an outside consumer to vendor.lib.rs:8
vaultcrux-localDaemon-local classification and content-loading policy, so transport crates do not duplicate tier-boundary rules. The Local versus HostedGated split is the Community/hosted boundary in the MCP tool surface.lib.rs:6
crux-config-wizardComposes CLAUDE.md and AGENTS.md from versioned profile fragments. Loaded by the crux-hook session-start hook for drift detection, and callable directly for init, regenerate, check, list, add, remove, diff.lib.rs:6
crux-lens-featuresThe canonical statement of what a lens is, and the smallest complete example of the pattern. Coverage reports, gap analysis, promise coverage.lib.rs:6
crux-mcpThe MCP tool surface: the 118-tool catalogue, JSON-RPC dispatch, the axum router and SSE transport, agent-token authentication, the audit envelope, the tool ledger, OAuth resource metadata, and the holdout control arm.lib.rs:8
crux-sessionThe session plane, with four invariants stated verbatim in its module doc. Session registry, capability plans, the sealer, and the install identity.lib.rs:9
rcx-capability-tokenThe RCX capability-token format, with a fail-closed guarantee stated in the module doc. The most-depended-on crate in the workspace.lib.rs:8
crux-routerRCX daemon router primitives. "Deliberately pure for Phase 1": consumes a capability token and returns deterministic routing and refusal decisions. Network refresh and revocation IO land in later phases. See §3.6.lib.rs:8
crux-enterprise-shimEnterprise customer-hosted capability-token validation contract: trust-root selection, airgap enforcement, backend and capability matching, egress refusal reasons. The name says shim; it is a fully implemented pure policy contract.lib.rs:6
corecruxdThe daemon. Bootstrap data, seeded passports, lens-kind registrations, HTTP router, gRPC router, MCP server, optional workspace scan and storyline materialiser. Configuration is environment-variable driven.main.rs:13
corecruxctlThe operator CLI, a clap-based dispatcher routing subcommands to handlers in the corecruxctl library crate. 40 handler modules; 51 subcommand variants.main.rs:9
crux-claude-hooksThe Claude Code hook binaries: session-start banner, pre-compact, context monitor, code context, observe capture, plus the experimental local-LLM shim.lib.rs:11
crux-integration-testsThe integration test harness. Exactly one public type, TestDaemon (lib.rs:208); everything else is private. Produces no library consumed by production code.lib.rs:6

3.3 Who depends on whom

Derived by grepping path = "../<crate>" across all 28 manifests. (dev) marks a dev-dependency edge.

CrateDepended on by
corecrux-framecorecrux-index, corecrux-projections, corecrux-segment (dev), corecrux-storage, corecruxctl, corecruxd
corecrux-indexcorecrux-retrieval, corecrux-storage, corecruxctl, corecruxd (dev), crux-mcp (dev)
corecrux-memorycrux-lens-features, crux-observe, crux-mcp, corecruxctl, corecruxd
corecrux-projectionscorecrux-retrieval, crux-mcp, crux-session (dev), corecruxctl, corecruxd
corecrux-protocrux-integration-tests, corecruxctl, corecruxd
corecrux-receiptscrux-integrations, crux-mcp, corecruxctl, corecruxd
corecrux-retrievalcrux-mcp, corecruxd
corecrux-segmentcorecrux-index, corecrux-projections, corecrux-storage, corecruxctl, corecruxd
corecrux-storagecorecrux-projections, corecruxctl, corecruxd
corecrux-typescorecrux-receipts, crux-mcp, corecruxctl, corecruxd
corecruxctl, (leaf: the CLI)
corecruxd, (leaf: the daemon)
crux-claude-hooks, (leaf: the hook binaries)
crux-config-wizardcrux-claude-hooks
crux-contrib- nothing. Orphan workspace member.
crux-costcorecruxctl, corecruxd
crux-enterprise-shimcorecruxd
crux-integration-tests, (leaf: the test harness)
crux-integrationscrux-mcp, corecruxctl, corecruxd
crux-lens-featurescrux-mcp, corecruxd
crux-mcpcorecruxd
crux-observecrux-mcp, corecruxd
crux-observe-apicorecruxd
crux-routercrux-mcp, corecruxd
crux-sessionrcx-capability-token, crux-sync (dev), crux-claude-hooks, crux-mcp, corecruxctl, corecruxd
crux-synccorecrux-memory, corecruxd
rcx-capability-tokencrux-sync, crux-router, crux-enterprise-shim, crux-integrations, corecrux-memory, crux-mcp, corecruxd
vaultcrux-localcrux-mcp, corecruxd

Most-depended-on: rcx-capability-token (7), then crux-session and corecrux-frame (6 each). Fan-out leaders: corecruxd depends on 23 workspace crates, crux-mcp on 12, corecruxctl on 12.

corecrux-index is not a runtime dependency of corecruxd. It appears only under [dev-dependencies]. Any documentation placing it on the daemon's runtime request path is wrong.

3.4 The three crates the existing docs never mention

Two crates are named in the workspace exclude list, and there is a third that is neither a member nor excluded.

CratePackageVersionLOCIn the root exclude list?Manifest
shells/desktop/lifecyclecrux-shell-lifecycle0.5.34534YesCargo.toml:10
shells/desktop/connectioncrux-shell-connection0.5.344,726No, not listedCargo.toml:4
shells/desktop/appcrux-desktop-shell0.5.34-YesCargo.toml:11

crux-shell-connection carries its own [workspace] table (Cargo.toml:16) and its own Cargo.lock, but is not named in the root exclude. It is reachable only as a path dependency of the excluded app crate. Because the root members list is explicit with no globs, cargo does not error, the crate is simply invisible to the daemon workspace.

Four consequences worth stating:

  • cargo build --workspace and cargo test --workspace cover 28 of the repository's 31 Rust crates. Any statement that --workspace covers everything is wrong.
  • All three shell crates are pinned at 0.5.34 while the workspace is at 0.5.52, 18 patch releases of drift. The version-sync.yml CI gate only checks the workspace version against the release tag, so the shell crates are not covered by it.
  • They share the workspace MSRV and licence but not the workspace lints; each declares its own. crux-shell-connection sets unsafe_code = "forbid" locally (Cargo.toml:22-23).
  • crux-shell-lifecycle is deliberately dependency-free, std only, not even tokio, so it compiles and unit-tests on any host including a webkit-less WSL. crux-shell-connection has exactly two dependencies, both exact-pinned: blake3 = "=1.8.5" and getrandom = "=0.3.4". The app crate exact-pins tauri = "=2.11.5", tauri-build = "=2.6.3" and ureq = "=3.3.0".

They are built by .github/workflows/desktop-shell.yml, the only build path for them. shells/desktop/app/Cargo.toml:5-7 gives the local-validation instruction: validate with cargo metadata --no-deps, not cargo build.

3.5 crux-contrib is a fully orphaned crate

crux-contrib has zero reverse dependencies. A grep for crux-contrib across every Cargo.toml in the repository returns exactly two hits: its own [package] name, and the workspace members entry at Cargo.toml:14. Nothing links it.

It is nonetheless compiled on every workspace build, tested in CI, and carries a 99% coverage floor (.github/workflows/ci.yml:446), the highest floor in the workspace, on 165 lines of code that no shipped artefact executes.

docs/architecture.md:123 describes it as a live component. It is not on any code path.

3.6 crux-router never checks revocation, and says so

CruxModeStamp.revocation_checked (lib.rs:126), the field on the stamp a RouterDecision carries, not a field on RouterDecision itself, has this doc comment verbatim (lib.rs:120-125):

"Whether the router consulted token revocation state (CRL / push channel) before authorising. Currently always false: revocation is modelled on the token (crl_url, push_channel) but decide() does not yet consult it, so a revoked-but-unexpired token is still authorised. Surfaced here so downstream auditors do not read an authorised decision as implying the token was checked for revocation."

State it plainly when you build on this: RCX capability-token revocation is not enforced at the router. Revoke by expiry, or by MCP-plane passport revocation, which is enforced and defaults on. The two postures must not be conflated, see chapter 14 and chapter 16 defect B6.

3.7 Cargo features, complete

Only 3 of 28 crates declare any features. Every optional feature is off by default.

CrateFeatureIn default?GatesManifest
corecrux-storagefuzzingno (no default key)fuzz_scan_frames_v1_block_bytesCargo.toml:9
corecrux-memorydefault = []-nothingCargo.toml:9
corecrux-memoryllmnonothing, a dead flagCargo.toml:10
corecrux-memorydense-embed-modelnodep:fastembed (ONNX Runtime)Cargo.toml:16
corecruxddefault = []-nothingCargo.toml:10
corecruxdotelnoOpenTelemetry OTLP exportCargo.toml:11-16
corecruxdwasm-extensionsnothe wasmtime host for kind: wasm extensionsCargo.toml:21
corecruxddense-embed-modelnoforwards to corecrux-memory/dense-embed-modelCargo.toml:25
corecruxdhosted-surfacesno/v1/gpu1/* and GET /v1/cloud/access-contractCargo.toml:31
corecruxctldefault = []-no optional featuresCargo.toml:57-58

corecrux-memory's llm feature is declared with no dep: entries, and no cfg(feature = "llm") exists anywhere in the workspace; it gates nothing.

3.8 What is a stub, and what only sounds like one

Three module comments state the Community/proprietary boundary explicitly:

LocationWhat it says
dataplane_store.rs:6"Crux Daemon stub, the data-plane store requires the proprietary edition. Only type definitions needed by other modules are retained here."
pool.rs:6"Crux Daemon stub, the data-plane pool requires the proprietary edition."
main.rs:45-48"gRPC service stubs: dataplane-enabled distributions implement full RPCs; Crux Daemon keeps the server skeleton."

Staged but not yet wired, with real code behind them:

LocationNote
main.rs:51-54 (candidate_links)"Candidate proposers are staged behind the identity-candidates rollout path; tests exercise creation/proposal before daemon startup wires automatic proposer runs."
main.rs:38-41 (credit_meter)"Default-off, append-only comped-wallet meter."
passports.rs:572Wired by a later milestone (per-session passport binding)
corecrux-receipts/src/lib.rs:163Agent-observation stream constants declared for a future deployment tier; "only chained-JSONL writes are wired in the community edition"
corecruxctl/src/ops.rs:6444 lines documenting a corecruxctl ops append command that has no CLI subcommand; it is a gRPC client for the unimplemented AppendBatch

There are zero production todo!() / unimplemented!() call sites outside the deliberate gRPC Status::unimplemented returns. Workspace clippy denies both macros (Cargo.toml:132-133). The occurrences that do exist are the stub classifier in the workspace scanner, and one test-only trait impl.

Three names mislead in the opposite direction; these are not stubs:

  • crux-enterprise-shim, a fully implemented pure policy contract. It is startup-fatal on an invalid trust root (main.rs:422). Call it a policy contract.
  • crux-llm-shim, a real, working local-LLM context-injection proxy, default-off behind CRUX_LLM_SHIM=1, with a localhost/RFC1918-only upstream allowlist.
  • crates/corecruxd/src/http/openai_shim.rs, a working OpenAI-compatible HTTP surface over the MCP tool catalogue.

3.9 Lint posture, which is a genuine trust asset

Set at the workspace root and inherited by every member (Cargo.toml):

  • unsafe_code = "forbid" (Cargo.toml:115); there is no unsafe Rust anywhere in the workspace, enforced by the compiler rather than by review.
  • todo and unimplemented are deny (Cargo.toml:132-133).
  • unused_imports, unused_variables, unused_mut, unreachable_code, unreachable_patterns are all deny.
  • clippy correctness and suspicious are deny; style, complexity, perf, pedantic are warn.
  • unwrap_used, expect_used, panic, print_stdout, print_stderr are warn at workspace level, because extracted monorepo code contains hundreds of legitimate uses.

The corecruxd binary escalates the last group to deny for itself (main.rs:9-11), with the rationale stated in the source: "The daemon must never panic on untrusted input." Individual call sites may #[allow] with a // SAFETY: justification. Two module-level exemptions exist: mod metrics (the Prometheus register!() macros panic only on duplicate registration) and corecruxctl's print_stdout / print_stderr, because it is a CLI.

Release profile: opt-level = 3, lto = "thin", codegen-units = 1, strip = "symbols". Production binaries carry no symbols, relevant if you are reading a core dump or a profiler trace from a release build.

3.10 Documentation drift inside the crates

Eight module-doc claims do not match their own code. They are listed here so a reader of the source is not misled by the comment above it.

#Claim in the sourceReality
D1corecrux-storage's module doc names key types ShardStore, Shard, CommitMarker (lib.rs:12)None exist. The real type is ShardStorage (lib.rs:1306)
D2corecrux-segment's module doc names ActiveSegment, SealedSegment, SegmentManifest (lib.rs:17)None exist. The real exported types are at lib.rs:113-116
D3corecrux-index says "GPU-native retrieval", index "loaded to GPU device memory at query time" (lib.rs:6)This repository is CPU-only; no GPU path exists. The crate is also a dev-dependency only of corecruxd
D4crux-claude-hooks says "three subcommands" (lib.rs:11)The binary exposes seven (main.rs:32-56)
D5corecruxd advertises "the gRPC API on port 4007 (tonic)" without qualification (main.rs:15)All 10 registered RPCs return unimplemented, AppendBatch included
D6crux-mcp's lib doc lists 5–7 "tools exposed" (lib.rs:13)crates/crux-mcp/src/tools/ holds 52 files and the catalogue is 118 tools
D7corecrux-memory declares a llm cargo feature (Cargo.toml:10)It gates nothing anywhere
D8corecruxctl/src/ops.rs documents a corecruxctl ops append command (ops.rs:6)No such subcommand exists; the module is unreferenced by main.rs

corecrux-proto's doc comment describes dataplane_v1 as "the primary data plane used by corecruxd for high-throughput event ingestion" (lib.rs:13). In this edition the dataplane pool is None and the module is a #[allow(dead_code)] skeleton.

3.11 Notes for a reader of the source

  • Every crate has an AGENTS.md, 28 of 28. Only crux-claude-hooks has a README.md.
  • Four crates have zero or near-zero external dependencies and are the easiest to read standalone or vendor: crux-observe-api (serde only), crux-cost (serde + serde_json), crux-enterprise-shim (one workspace dep, no external deps), crux-router (one workspace dep plus ed25519-dalek).
  • Eleven tree-sitter grammars are compiled unconditionally into the daemon, TypeScript, Python, Go, Java, C, C++, C#, Ruby, Swift, PHP and the core. Six are exact-pinned, so a grammar upgrade is a deliberate act. They back workspace_scan_polyglot.rs (7,962 LOC) and workspace_scan_ast.rs (1,401 LOC).
  • p256 is a second signature algorithm alongside Ed25519, because Sigstore Rekor's hashedrekord verification requires ECDSA P-256 while the daemon seal key is Ed25519.
  • ed25519-dalek is pinned with features = ["zeroize"] explicitly, even though zeroize is a default feature, so the signing-key zeroize-on-drop guarantee survives any future default-features = false on a consumer.

Sources