hashloom

# hashloom

[![CI](https://github.com/davet47/hashloom/actions/workflows/ci.yml/badge.svg)](https://github.com/davet47/hashloom/actions/workflows/ci.yml)

![hashloom regenerating a unit: one ~300-token context packet plus a cached verification, instead of re-reading whole files](https://raw.githubusercontent.com/davet47/hashloom/main/docs/demo.gif)

**Hashloom treats software units as content-addressed contracts rather than files.** An MCP server that makes agent regeneration loops cheap.

Because contracts are content-addressed and dependency-aware, agents reuse verification, compute blast radius precisely, and regenerate code from a few hundred tokens of context instead of re-reading whole files. Build systems ask which files changed. Hashloom asks which software obligations changed.

The name is a coinage that says exactly what it is: a loom keyed by hashes. On a loom, the warp threads are the fixed, durable strands, and the shuttle weaves disposable weft through them. **Contracts are warp. Code is weft.** (Until 0.3.3 this project shipped as `heddle-mcp`; the engine is unchanged.)

## The problem

Agents repeatedly pay to rediscover software structure. Spec-driven development tools made specs the durable artifact and code regenerable, but they run on plain files, so every regeneration loop re-derives what the project already knows:

1. **Context acquisition is expensive.** Regenerating one unit means re-reading whole spec and source files: thousands of tokens to learn what a few hundred convey.
2. **Verification is uncached.** Every regeneration re-runs (and re-reads the output of) the full relevant test surface, even for units whose contracts haven't changed.
3. **Blast radius is by convention, not mechanism.** When a spec changes, nothing tells the agent precisely which dependents are invalidated.

## The model

Hashloom treats each software unit as a content-addressed contract with explicit dependencies, not a file. A contract is a small YAML spec (signature, invariants, examples, dependency names); the implementation behind it is regenerable weft. Because every contract is hashed and its dependencies are named, the structure an agent keeps re-deriving from files becomes something hashloom computes once and serves.

## Outcomes

The model buys three things, all mechanical:

- **Verification caching.** A green test result is keyed on the contract, implementation, and dependency hashes, and served from cache until one of them changes. pytest runs only on a real miss.
- **Mechanical blast radius.** A contract change reports the exact set of invalidated dependents, transitively and by hash, not by convention.
- **Tiny context packets.** An agent regenerating a unit gets the contract, its dependencies' signatures, and its callers as one packet of a few hundred tokens, instead of the whole file closure.

### The number

Same three regeneration tasks on a 20-contract sample project, once with raw file reads, once through hashloom (tiktoken cl100k, reproduce with `uv run python bench/benchmark.py`):

| task                | raw files | hashloom | reduction |
|---------------------|----------:|-------:|----------:|
| revenue_by_region   |     1,925 |    369 |      5.2x |
| top_customers       |     2,137 |    337 |      6.3x |
| revenue_by_category |     1,942 |    396 |      4.9x |
| **total**           | **6,004** | **1,102** | **5.4x** |

Raw mode counts what a file-based agent reads per task: the unit's spec file, every transitive dep's spec file, every source module in the dep closure, the unit's test file, and the output of running the suite. It is deliberately generous to the baseline: it assumes the agent already knows the exact dependency closure, which is precisely the thing hashloom computes for you.

The same methodology sweeps *every* unit of all four example projects —
Python, Go, TypeScript, and Java — via `bench/sweep.py`, and works on any hashloom
project including yours. Full sweeps average lower than the gate (they count
the leaf types that barely benefit); the ratio tracks dependency depth, so
deeper projects score higher. All the numbers, their distributions, and the
honest caveats live in [docs/benchmarks.md](docs/benchmarks.md).

## Quickstart

```bash
pip install hashloom
# or from source: pip install "git+https://github.com/davet47/hashloom"

cd your-project
hashloom init                 # creates .hashloom/ and contracts/
hashloom index                # builds the store from contracts/
```

Point Claude Code at it:

```bash
claude mcp add hashloom -- hashloom serve
```

(Stdio transport; the server resolves the project by walking up from its working directory to the nearest `.hashloom/`.)

New to the workflow? [docs/getting-started.md](docs/getting-started.md) walks through building a package contract-first with an agent — the working rules to give it, the review loop, and the verify gate.

## Contracts

One YAML file per unit in `contracts/`. Minimal, hand-writable, hashable:

```yaml
name: revenue_by_region
signature: "(sales: list[Sale]) -> dict[Region, float]"
deps: [Sale, Region]            # other contract names
invariants:
  - excludes sales where completed is false
  - excludes sales with null amount
examples:
  - in:  "[Sale(region='QLD', amount=10, completed=True)]"
    out: "{'QLD': 10.0}"
tests: [tests/test_revenue.py::test_revenue_by_region]   # pytest node IDs
impl: src/revenue.py::revenue_by_region                  # current woven weft
status: inferred        # reverse-engineered, not yet human-reviewed; omit once confirmed
```

Subdirectories are namespaces: `contracts/billing/invoice.yaml` is the contract
`billing/invoice`, so the same short name can live in different folders. A
contract's `name` must match its path under `contracts/`.

### When to write a contract

A contract belongs on a stable seam: an interface other units depend on and that you expect to outlive its current implementation. The implementation behind it is disposable weft, regenerated freely. Dropping a contract where it does not earn that place is correct use, not a failure. The failure mode is the opposite, over-pinning interiors you would happily rewrite, which turns the durable layer into busywork.

Contracts are reviewed artifacts. Authoring one is cheap and getting cheaper, so the real cost is reviewing it, not writing it. A wrong contract is worse than no contract, because the durable artifact now lies: agents will regenerate code to satisfy a spec that is itself incorrect. Review a contract the way you review an interface, not the way you skim generated code.

A contract an agent reverse-engineers from existing code can declare that it hasn't earned that review yet: `status: inferred`. Tools then flag — by default, never refuse — any blast-radius or verification answer that rests on it (`inferred: true` on dependents, an `inferred` list on verify results, a review queue in `status`). Teams that want unvetted contracts to hard-fail can opt in to strict provenance mode (`.hashloom/config.json` → `{"strict_provenance": true}`): `verify` then refuses such units with a structured `inferred_contract` error — no tests run, no verdict cached — until they're reviewed; reads and writes stay advisory so drafts can still land and be inspected. Absent means `confirmed`, and confirming an inferred contract after review is free: status is provenance, not meaning, so the flip invalidates nothing (under strict mode, a pre-existing green simply revives on confirm).

### Hashing semantics

- **Contract hash**: sha256 over a canonical form: keys sorted, whitespace normalised, comments stripped, example order preserved, dep order ignored. `impl`, `tests`, `invariants`, and `status` are excluded, so **relocating files never invalidates**, rewording an invariant is free, and confirming an inferred contract never invalidates anything. Invariants are documentation, not a machine obligation; the real check is the tests, whose source is in the verification key.
- **Impl hash**: sha256 over the normalised AST of the implementation, so reformatting and comment edits never bust the cache. Docstrings are stripped too.
- **Verification key**: `(contract hash, impl hash, test-source hash, toolchain identity, transitive dep contract hashes)`. Hashloom caches verification results, keyed so that a change to any contract in the closure, to the implementation, to a test's own source, or to the toolchain identity forces a re-run. The identity is the toolchain version (`python 3.11.7`, `go 1.21.5`, `node <v> ts <v>`, `java 21.0.3`, `dotnet 9.0.303`) plus, when the project commits a dependency source at its root (`uv.lock`, `go.sum`, `package-lock.json`, `pom.xml`, ...), a ` deps <file>=<hash>` digest of it — so a green from an environment with a different declared dependency set is never trusted, and a 3.11 pass is never served to 3.13. The grain is the *committed declared* set (never OS/arch — CI greens still serve every platform); a venv that disagrees with its own lockfile is outside the key, which is one of the things shared-cache revocation exists for. Failures are never served from cache. Two caveats. A cached pass assumes deterministic tests, so a green result that depended on wall-clock time, network, or randomness can outlive the condition that made it pass. And the test-source hash covers each test function's own normalised AST, not the conftest fixtures or helpers it calls, so changing only those will not force a re-run yet (see [Roadmap](ROADMAP.md)).

## MCP tools (the entire surface)

| tool | does |
|---|---|
| `get_contract` | the ~300-token context packet: contract + hash + one-line dep signatures + caller list |
| `put_contract` | validate, write `contracts/<name>.yaml`, return new hash, a semantic diff of what changed, and every invalidated dependent |
| `get_dependents` | blast-radius query, direct or transitive, names + hashes; inferred (unreviewed) contracts flagged |
| `verify` | per-unit `cached-pass` / `pa