# The crates, explained like you're five
One analogy carries the whole workspace: **a weavers' guild**.
Every workshop weaves cloth (writes code). Helpers — tireless, very fast,
not always wise — now do much of the weaving (agents). Each workshop keeps a
card box of pattern cards saying *why* the cloth is woven the way it is
(decisions). A helper may punch a draft card, but only a weaver who has run
their fingers over the actual cloth may sign it (attestation). The
doorkeeper will not let a bolt leave the workshop while any card that shaped
it is unsigned (the gate). And in the guild hall hangs a corkboard of tiny
swatches (the registry): you can tell from two swatches that two workshops
are weaving similar cloth, but you could never rebuild a tapestry from one.
## jac-core — the guild's dictionary (neutral)
The words everyone uses and nobody can smuggle cloth inside. Ink-stamp
serial numbers for people, helpers, and workshops (`HumanId`, `AgentId`,
`OrgId`); wax-seal impressions that uniquely fingerprint an object
(`Digest`, and the typed ids like `SnapshotId`); a clock that is always
handed to you, never read off the wall (`Clock`), so any story can be
replayed; the guild's register of *whose hands made it* (`Provenance` —
weaver, helper, or both). And one special rubber stamp, `DigestSafe`,
applied only to things shaped like seals — never to things shaped like
cloth. Only stamped things may travel to the guild hall.
**How it fits:** every other crate speaks this vocabulary; none of it can
carry content bigger than a seal.
## jac-sketch — the swatch cutter (neutral)
A little machine: feed cloth in one side, get a one-inch swatch card out the
other — 64 numbers, nothing more (`MinHashSketch`). Two swatches from
similar bolts look similar (`Similarity`); a swatch from an unrelated bolt
looks nothing alike. The machine has no reverse gear: there is no method
that gives the cloth back, because the cloth was never kept.
**How it fits:** swatches are the only thing the guild-hall corkboard ever
holds, and they carry the `DigestSafe` stamp.
## jac-object — the bolt room (content)
Where cloth actually lives. A `Blob` is fabric; a `Tree` is a shelf with
labelled pigeonholes, always alphabetised so the same shelf always gets the
same seal; a `Snapshot` is a finished bolt with a tag woven into the selvage
listing what it holds, who made it, and — inseparably — *whose hands* made
it. Because the hands are woven into the tag, re-labelling a helper's bolt
as hand-made produces a visibly different bolt. The shelf clerk
(`MemoryObjectStore`) re-checks every seal on the way out, and `diff_trees`
tells you exactly which pigeonholes changed between two shelves.
**How it fits:** the DAG everything else points into; provenance-is-identity
lives here.
## jac-decision — the card box (content)
Pattern cards (`Decision`): why the cloth is cut this way, what was tried
and rejected, what was knowingly skipped (the `RationaleFamily` families a
helpful interviewer asks about). A helper may draft a card, and the card
says so honestly. Next to it, the signature slip (`Attestation`): a few
sentences in the weaver's own hand, and the pen physically does not fit a
helper's grip — `Attestation::new` takes a human and nothing else. A card is
`Unsettled` until signed and `Settled` after, and "after" is a different
*type*, reachable only through the signing motion (`attest`). There is no
door into the settled room except that one.
**How it fits:** the two compiler-proven invariants of the whole system live
in this crate.
## jac-gate — the doorkeeper (content)
Asks one question of every bolt at the door: *which cards shaped this cloth,
and are they all signed?* Unsigned card → the bolt waits inside (`Blocked`),
with the card's name pinned to it so the right weaver can be found. All
signed → out it goes (`Admitted`), with an honest count — including the
honest zero when no cards claimed the cloth at all. The doorkeeper's default
answer, before anyone asks, is *no*: `Verdict::default()` blocks. Nobody is
fined for a wait; the bolt is parked, never burned.
**How it fits:** the enforcement point that makes decision cards
load-bearing instead of decorative.
## jac-git — the export crate (content)
Other towns speak git. The packing bench (`GitInterop`) flattens a bolt into
the shape their wagons carry, and writes everything git has no field for
onto luggage tags in git's own tag format (`Jacquard-Provenance`,
`Jacquard-Author`, …). The test that matters: pack a bolt, unpack it, and
the seal matches exactly — nothing fell off in the wagon. Tamper with a tag
in transit and the unpacked bolt visibly carries a different seal.
**How it fits:** jacquard repos stay ordinary git repos, and every card and
tag is ordinary repo content any librarian can index.
## jac-repo — the workshop floor (content)
Where it all runs: `commit` weaves, `branch` starts a new loom from an
existing bolt, `propose_decision` drafts a card, `attest` signs one,
`promote` walks a bolt to the doorkeeper and moves the shelf pointer only on
a literal *yes*, and `sketch_snapshot` / `sketch_decision` run cloth through
the swatch cutter — the one sanctioned way anything derived from cloth heads
toward the guild hall.
**How it fits:** the engine every surface (CLI, server, demo) will drive.
## jac-rendezvous — the guild hall corkboard (rendezvous)
The corkboard holds swatches, workshop names, and dates. That is the whole
inventory, and it could not be otherwise: this crate's imports are the
dictionary and the swatch cutter — it has never heard of cloth, shelves, or
cards, and the build proves it stays that way. When two swatches match, the
hall does exactly one thing: hands both workshops the same introduction
token and steps aside. The weavers talk; the hall never does.
**How it fits:** duplicated work becomes a conversation between people
instead of two parallel years of it.
## jac-demo — the guided tour (content)
Walks a visitor through one full story — weave, draft, block, sign, admit,
swatch, rendezvous, export — narrating which mechanism proves each step and,
just as loudly, what is *not* proven yet.
## xtask — the building inspector (neutral)
Checks the walls, not the paint: no `mod.rs` anywhere (`lint-layout`), and
the corkboard room has no corridor to the bolt room (`boundary`). `ci` runs
every check in order. Everything here is a control, not a convenience.