# jacquard
The Jacquard loom took the most skilled work a human could do with thread and
made it programmable: punched cards told the loom what to weave. What it did
not do was remove the weaver. Someone still chose the pattern, punched the
cards, ran their fingers over the cloth, and signed the bolt. And because the
cards were physical, portable things, patterns travelled — weavers learned
what other weavers were making, and the good patterns spread instead of being
reinvented in every workshop.
Version control is having its Jacquard moment. Agents write more of the code
every month, and the systems we record that code in — git and the platforms
over it — capture *what* changed and *who* pushed it, but almost none of
*why*, and no trace of whose hands actually made it. Blame answers "who
touched this line," not "what was this person thinking, and what did they
knowingly trade away." Meanwhile every company quietly builds the same retry
layer, the same pagination, the same auth shim, because nobody can see that
the team two floors up already settled those questions.
jacquard is a Rust replacement for git's core backend, built around three
ideas:
**Design decisions are objects in the version graph.** Not markdown files by
convention — content-addressed objects in the same DAG as the code, with
scopes naming what they govern. Agents may draft and propose them (an AI
interviewer that asks the author "what did you consider and reject?" is the
intended source), but a proposed decision is only *unsettled*. A human
settles it with an **attestation**: a few sentences in their own words that
only understanding can produce. The machine's synthesis and the human's
verbatim account are separate objects with separate provenance, never
conflated. A fail-closed gate blocks promoting work whose blast radius
touches unsettled decisions — the work parks, the decision surfaces, and
attestation (recognised, never policed) reopens the way.
**Provenance is identity.** Every snapshot records whose hands made it —
human, agent, or mixed — *inside its content address*. The same tree
relabelled from `agent` to `human` is a different snapshot with a different
id, visible to everything holding the old one. Honest scope: this makes
provenance unforgeable after the fact, not verified at creation; signing is a
named unblock condition, not a solved problem.
**Rendezvous instead of rework.** Repositories publish MinHash sketches — 64
integers — of their content and decisions to a shared registry. When two
organisations' sketches resemble each other, the registry brokers an
introduction: a token, two names, nothing else. Privacy is structural twice
over: the registry crate cannot *name* content types (the dependency graph
never reaches them, proven by `cargo xtask boundary`), and its API only
accepts types marked `DigestSafe` (proven by the compiler).
jacquard is a sibling of [phantom-thread](../phantom-thread), and built on
its discipline: invariants are facts the build re-proves, not conventions.
An agent cannot attest because no constructor accepts one — checked by a
`compile_fail` doctest. `Settled` is reachable only through `attest()`. The
gate's `Default` verdict is `Blocked`, because unproven is not passed.
## See it run
```bash
cargo run -p jac-demo
```
A narrated end-to-end walkthrough against in-memory adapters: an agent's
commit carries its provenance in its id, a proposed decision blocks a
promotion, a human's attestation admits it, a second organisation's similar
decision surfaces through the registry and an introduction is brokered, and
the whole history round-trips to plain git with provenance riding in
ordinary commit trailers. No network, no persistence, no real git.
Because decisions and attestations are repo content, anything that already
indexes the repository — enterprise search, blame tooling, a future AI
reviewer citing prior decisions — ingests them for free. That is deliberate:
the substrate keeps all durable state in the repo, so every platform choice
above it stays open.
## Going deeper
- [Architecture](docs/design/ARCHITECTURE.md) — trust planes, the crate map,
failure scenarios, acceptance claims, and the unblock conditions.
- [Development](docs/DEVELOPMENT.md) — the invariants the compiler enforces,
workspace layout, and the CI checks.
- [The crates, explained like you're five](docs/ELI5.md) — the weavers' guild
analogy that makes the system legible without reading Rust.
- [Adversarial review](docs/adversarial-review/reviews/TLDR.md) — the design
debates, including the weak points already on the target list.