hashloom 0.4.0__tar.gz

hashloom-0.4.0/.dockerignore

@@ -0,0 +1,6 @@
+.git
+.venv
+.hashloom
+node_modules
+dist
+__pycache__

hashloom-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Something doesn't work as documented
+title: ""
+labels: bug
+---
+
+**What happened**
+<!-- The behaviour you saw. -->
+
+**What you expected**
+
+**Repro**
+<!-- Minimal steps. A small contract YAML plus the command or MCP call is ideal. -->
+
+**Environment**
+- hashloom version (`hashloom --version`):
+- Python version:
+- OS:
+
+**Anything else**
+<!-- status / verify output, the structured error code and message if there is
+one (hashloom never leaks a stack trace over MCP). -->

hashloom-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Propose a change or addition
+title: ""
+labels: enhancement
+---
+
+**The problem**
+<!-- What are you trying to do that hashloom makes hard today? -->
+
+**Proposed direction**
+
+**Does it fit the surface?**
+<!-- hashloom is deliberately small: 5 MCP tools, 5 CLI commands, and the README
+documents the entire surface. If this adds to that surface, say why it earns a
+place (the failure mode we guard against is "scope creep toward Loom"). Where the
+project is already headed lives in ROADMAP.md. -->

hashloom-0.4.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What and why
+
+<!-- What does this change do, and why? Link any issue it closes. -->
+
+## Checklist
+
+- [ ] `uv run pytest` passes (full suite).
+- [ ] Touches `contract.py` or `implhash.py`? The hash-stability tests
+      (`tests/test_contract_hash.py`, `tests/test_implhash.py`) still pass, and
+      any change to what busts a hash is intentional.
+- [ ] Touches the context packets or hashing? `uv run python bench/benchmark.py`
+      still reports >5x.
+- [ ] Scope: this does not expand the 5-MCP-tool / 5-CLI-command surface, or it
+      was discussed in an issue first.
+- [ ] Tool errors stay structured (`HashloomError`); no stack traces over MCP.

hashloom-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+# cancel superseded runs on the same ref (e.g. rapid pushes)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - uses: actions/setup-go@v5      # for the Go adapter tests (else they skip)
+        with:
+          go-version: 'stable'
+      - uses: actions/setup-node@v4    # for the TypeScript adapter tests (else they skip)
+        with:
+          node-version: '22'           # >= 22.6 for .ts type-stripping in node:test
+      - uses: actions/setup-java@v4    # for the Java adapter tests (else they skip; mvn ships on the runner)
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+      - name: Install the TypeScript toolchain
+        run: npm ci                    # provides the `typescript` the tshash helper resolves
+      - name: Sync deps
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+      - name: Run tests
+        # hash-stability suites are load-bearing; e2e spawns the real stdio server
+        run: uv run --python ${{ matrix.python-version }} pytest -q
+
+  benchmark:
+    name: benchmark (>5x DoD guard)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Token-reduction benchmark
+        # exits nonzero below the 5x definition-of-done line
+        run: uv run python bench/benchmark.py

hashloom-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+# Publish to PyPI via Trusted Publishing (OIDC) when a version tag is pushed.
+# No API token is stored: the publish job mints a short-lived OIDC token that
+# PyPI trusts because this repo + workflow + environment are registered there.
+#
+# The published version comes from src/hashloom/__init__.py (hatchling reads it
+# as the dynamic version); the tag is only the trigger, so keep the tag and
+# __version__ in sync, e.g. __version__ = "0.1.0" published by tag v0.1.0.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check the tag matches __version__
+        # The whole chain assumes it: PyPI publishes __version__ (hatchling
+        # dynamic version) while the mcp-registry job stamps server.json from
+        # the tag. Fail fast instead of publishing two different versions.
+        run: |
+          TAG=${GITHUB_REF#refs/tags/v}
+          PKG=$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' src/hashloom/__init__.py)
+          [ "$TAG" = "$PKG" ] || { echo "tag v$TAG != __version__ $PKG" >&2; exit 1; }
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Store the distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # `name` must match the environment in the PyPI pending-publisher form.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hashloom
+    permissions:
+      id-token: write  # required for Trusted Publishing; no stored secret
+    steps:
+      - name: Download the distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  mcp-registry:
+    name: Publish to MCP Registry
+    # needs the PyPI publish: the registry validates that the listed version
+    # exists on PyPI and that its README carries the mcp-name marker.
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # GitHub OIDC is the registry login; no stored secret
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Sync server.json versions to the tag
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          jq --arg v "$VERSION" '.version = $v | .packages[].version = $v' server.json > server.tmp && mv server.tmp server.json
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login github-oidc
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish

hashloom-0.4.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.hashloom/
+.pytest_cache/
+node_modules/
+target/

hashloom-0.4.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "hashloom": {
+      "command": "uv",
+      "args": ["run", "hashloom", "serve"]
+    }
+  }
+}

hashloom-0.4.0/CHANGELOG.md

@@ -0,0 +1,245 @@
+# Changelog
+
+All notable changes are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-07-09
+
+**Renamed: heddle → hashloom.** Two unrelated "heddle" MCP servers already
+existed (one predating this project by three months), and the bare PyPI name
+was squatted — the loom-part namespace turned out to be crowded ground. The
+coinage `hashloom` says what the tool is (a loom keyed by hashes), is
+unclaimed everywhere, and takes the *bare* PyPI name: `pip install hashloom`.
+
+### Changed
+- Distribution `heddle-mcp` → `hashloom`; import and CLI `heddle` → `hashloom`;
+  MCP registry id `io.github.davet47/heddle` → `io.github.davet47/hashloom`
+  (registry launches now use `uvx hashloom serve` via `packageArguments`);
+  error class `HeddleError` → `HashloomError`; cache-server token env var
+  `HEDDLE_CACHE_TOKEN` → `HASHLOOM_CACHE_TOKEN`; project marker directory
+  `.heddle/` → `.hashloom/`.
+- **Migration** (pre-0.4.0 projects): the store is derived — run
+  `hashloom init && hashloom index` in each project, move any
+  `.heddle/config.json` to `.hashloom/config.json` by hand, and delete the old
+  `.heddle/` directory. Contract files are untouched.
+- The roadmap's hosted-store theme renumbers v0.4 → v0.5 (this release took
+  the 0.4.0 slot).
+- The engine is otherwise unchanged; `heddle-mcp` 0.3.3 is the tombstone.
+
+## [0.3.3] - 2026-07-09
+
+The tombstone release: **the project has been renamed to `hashloom`** (the
+loom-part namespace turned out to be crowded — two unrelated "heddle" MCP
+servers already exist). This is the final release as `heddle-mcp`; the engine
+continues unchanged as [`hashloom`](https://pypi.org/project/hashloom/) from
+0.4.0 on. No code changes.
+
+## [0.3.2] - 2026-07-09
+
+Theme: Java, end to end — a fourth language adapter, its reference example,
+and the adapter seam itself brought under contract. Plus run instructions for
+every example, and the repo dogfooding its own MCP server.
+
+### Added
+- **Java adapter** — a `.java` impl routes to Java: hashing via a single-file
+  `javac`-tree helper (`langs/javahash/JavaHash.java`, JDK-only, zero
+  dependencies) so formatting, comments, and javadoc never bust the cache;
+  tests via the project's own Maven or Gradle, auto-detected from the build
+  manifest (`pom.xml` → `mvn`, `build.gradle` → `gradle`, committed
+  `mvnw`/`gradlew` wrappers preferred); toolchain from `.heddle/config.json`
+  (`{"java": "..."}`), else `java` on PATH. Needs a JDK >= 11. The contract
+  syntax and the 5-tool / 5-CLI surface are unchanged.
+- **The adapter seam under contract** — `contracts/LanguageAdapter.yaml`
+  (status: inferred, pending review) covers the six-method per-language
+  Protocol and `adapter_for` routing, with toolchain-free seam tests in
+  `tests/test_langs_seam.py`. Heddle-on-heddle: the seam that gained a fourth
+  implementation is now itself a contracted unit.
+- **`examples/java-payroll`** — the Java counterpart example: 11 contracts over
+  a weekly payroll run (types → pay/tax arithmetic → payslip rendering, three
+  layers deep), the shape of a Spring service layer with zero framework
+  dependencies (JUnit 5 only, via Maven). Exercises records, `Class.method`
+  quals, a parameterized bracket table, and a `@Nested` test class with dotted
+  node ids. `bench/sweep.py` learns the `.java` suite runner, and the
+  [benchmark scorecard](docs/benchmarks.md) gains the measured row (3.2× over
+  all 11 units, the most conservative baseline of the four).
+- **Per-example run instructions** — each of the four example projects ships
+  its own README: prerequisites, running the tests directly, the heddle loop,
+  and a blast-radius walkthrough whose radius sizes and re-run sets were
+  executed and measured before landing, not asserted.
+- **Dogfood config** — `.mcp.json` registers the repo's own MCP server at
+  project scope, and CLAUDE.md now directs agents to prefer `get_contract`
+  packets over reading contracted seams' source files.
+- **Glama listing** — a claim file plus an introspectable Dockerfile, the next
+  step in the post-registry discoverability sequence (#64).
+
+## [0.3.1] - 2026-07-05
+
+Theme: discoverability. An official MCP Registry listing, and the CI that
+keeps it from going stale. No engine changes.
+
+### Added
+- An MCP Registry listing, `io.github.davet47/heddle`: `server.json` at the
+  repo root describes the server, the README carries the `mcp-name`
+  ownership marker (the registry verifies PyPI packages by finding it in
+  the package description), and a `heddle-mcp` console script boots the
+  stdio server directly — the registry's launch convention is
+  `uvx <distribution>`, and uvx runs the script named after the
+  distribution. A launch shim for `heddle serve`, not a sixth CLI command.
+- Registry publishing in CI: an `mcp-registry` job in the release workflow
+  authenticates with GitHub OIDC (no stored secret), syncs the versions in
+  `server.json` from the tag, and publishes to
+  registry.modelcontextprotocol.io after the PyPI publish succeeds — every
+  tagged release updates the listing.
+- A benchmark scorecard, `docs/benchmarks.md`, and a full-sweep benchmark,
+  `bench/sweep.py`: the scorecard holds every published token-reduction
+  number — the sales DoD gate (5.4×) plus full sweeps of all three example
+  projects (sales 4.1×, go-ledger 3.0×, ts-cart 3.1× — sweeps count the leaf
+  units the gate doesn't, so they average lower by construction), the
+  dogfood store's cache counters, and the concessions any public claim
+  should carry (closure knowledge granted free to the baseline;
+  first-try-green assumed for heddle; per-change estimate, not a session
+  total; initial build costs more). `sweep.py` runs the same accounting over
+  every verifiable unit of any heddle project, language-aware only in the
+  suite runner (pytest / `go test` / `node --test`). Every scorecard row is
+  reproducible from this repo alone; ratios are deterministic tiktoken
+  counts and independent of what drives the session. The README's "The
+  number" section links to it.
+
+## [0.3.0] - 2026-07-04
+
+Theme: adoption. Everything a first-time visitor needs that the engine
+releases didn't ship: a getting-started walkthrough for the contract-first
+agent workflow, sample projects in all three supported languages, and the
+strongest possible existence proof — heddle developing heddle, its own stable
+seams under contract (written `inferred` by the agent, since reviewed and
+explicitly confirmed by a human, at zero re-verification cost). No code
+changes: the engine is 0.2.0's; the 5 MCP tools / 5 CLI commands surface and
+all response shapes are unchanged.
+
+### Added
+- Heddle develops on heddle: the repo is now itself a heddle project —
+  `contracts/` holds 12 contracts over the stable seams (the five `api.py`
+  tool functions, the hashing trio, `impl_hash`, `verification_key`,
+  `HeddleError`, the `Store` Protocol), bound to the existing test suite and
+  born `status: inferred` pending human review. `heddle verify --radius` is
+  the inner-loop gate for changes to contracted seams; the full pytest suite
+  and the benchmark remain the definition of done.
+- A getting-started walkthrough, `docs/getting-started.md`: how a human and an
+  agent build a package contract-first — setup, the CLAUDE.md working rules to
+  give the agent, the inferred→confirmed review loop, and the `verify --radius`
+  gate as the definition of done.
+- A TypeScript sample project, `examples/ts-cart`: 8 contracts over a shopping
+  cart (interface/type-alias contracts included), exercising the TypeScript
+  adapter end to end — canonical-AST impl hashing via the project's own
+  `typescript`, `node:test` verification under type stripping, and the
+  `verify --radius` gate.
+- A Go sample project, `examples/go-ledger`: 8 contracts over a small
+  double-entry ledger (struct/type contracts included), exercising the Go
+  adapter end to end — AST-stable impl hashing, `go test -json` verification,
+  and the `verify --radius` gate.
+
+## [0.2.0] - 2026-07-04
+
+Theme: solo → team. A team can now share verification greens — one teammate or
+CI verifies a unit once and everyone gets `cached-pass` — soundly, keyed by
+toolchain. Plus two new language adapters, contract provenance, and a
+CI-gateable verify. Everything is additive: the 5 MCP tools / 5 CLI commands
+surface and the contract format are unchanged, and 0.1.0 projects work as-is.
+One-time cost on upgrade: existing cached greens re-verify once (the
+verification key now includes the toolchain).
+
+### Added
+- Gate-shaped verification: `verify` responses carry a top-level `ok` — true iff
+  every unit is `pass`/`cached-pass` (failures, unknown names, and unverifiable
+  units all gate) — and a `radius` option (`heddle verify --radius NAME`, MCP
+  `verify(names, radius=true)`) widens each name to itself plus every transitive
+  dependent, spec-only units dropped. One call = a hard pass/fail for a change's
+  whole blast radius; the CLI exit code mirrors `ok`, so a CI step or agent loop
+  can block on it. No new tools/commands.
+- Contract provenance: an optional `status: inferred | confirmed` field on
+  contracts. `inferred` marks a contract reverse-engineered from code and not
+  yet human-reviewed; tools warn — never refuse — when a decision rests on one
+  (`inferred: true` on `get_dependents`/`get_contract` dep entries, `inferred`
+  and `invalidated_inferred` on `put_contract`, an `inferred` list on `verify`
+  results, and a review-queue list in `status`). Absent = `confirmed`, so
+  existing contracts are unaffected, and the field is excluded from the contract
+  hash, so confirming an inferred contract after review invalidates nothing and
+  busts no cached green. The 5-tool / 5-CLI surface is unchanged; every new
+  response key appears only when an inferred contract is actually involved.
+- Remote shared verification cache (transport): a `RemoteStore` client and a
+  stdlib `python -m heddle.cache_server` (a bearer-token JSON HTTP service over a
+  `SqliteStore`) let a team share verdicts and impl blobs across machines —
+  configured per project via `.heddle/config.json` `{"shared": {"url","token"}}`,
+  with **no change to the 5 MCP tools / 5 CLI commands** (the cache server is an
+  operational process, not a subcommand). A shared-store outage degrades silently
+  to local verify. Cross-machine greens are made sound by the toolchain-in-key
+  change below.
+- Toolchain in the verification key: the key now folds in a per-language toolchain
+  identity (`python 3.11.7` / `go 1.21.5` / `node <v> ts <v>`), so a shared or
+  cross-machine green is trusted only when the toolchain version matches —
+  otherwise it re-runs. Version-only (no OS/arch), so a CI(Linux) green still
+  serves a Mac/Windows dev. One-time: existing greens re-verify once on upgrade.
+- Semantic diff in `put_contract`: the response carries a `diff` of what changed
+  versus the prior contract (signature, deps, invariants, examples, impl/tests).
+- Test source in the verification key (#18): editing a test's body now forces a
+  re-run; reformatting, comments, and docstrings in a test stay cached. Conftest
+  fixtures and helpers a test calls are not yet covered.
+- Content-addressed impl-source store: `heddle index` stores each impl file's
+  source as a deduped blob, so the store can serve weft, not only verdicts.
+- A backend-agnostic `Store` interface (a Protocol) with `SqliteStore` as the
+  local implementation: the seam for a shared/remote cache.
+- Shared verification cache MVP (`LayeredStore`): a local store fronted by a
+  shared one (read-through, write-through for greens), so one client's verified
+  green serves another. Design for the hosted service in docs/hosted-store.md.
+- Multi-language adapters: contracts whose `impl` is a `.go` file verify with a
+  Go adapter (a stdlib `go/ast` hash helper plus `go test -json`), chosen by the
+  impl's extension. Python is unchanged and the default; the contract syntax and
+  the 5-tool / 5-CLI surface are unchanged.
+- TypeScript adapter: contracts whose `impl` is a `.ts`/`.tsx`/`.mts`/`.cts` file
+  verify with a TypeScript adapter — a hand-written canonical AST hash via the TS
+  Compiler API (resolved from the project's own `typescript`, since TS has no
+  `ast.dump`), plus an auto-detected test runner (vitest / jest if declared in
+  `package.json`, else Node's built-in `node:test`). Needs Node (>= 22.6 for `.ts`
+  type-stripping under `node:test`). Python and Go are unchanged; the contract
+  syntax and the 5-tool / 5-CLI surface are unchanged.
+- A `rechecks` block in `status` (#20): re-verifications triggered by a contract
+  change, and how many changed no verdict (`wasted_rate`).
+- Invariants out of the contract hash (#19): rewording or reordering an invariant
+  no longer changes the hash or cascades a re-verify. Invariants are documentation;
+  the machine check is the tests (their source is in the key via #18). One-time:
+  contracts with invariants re-hash once on upgrade.
+
+## [0.1.0] - 2026-06-23
+
+First public release, published to PyPI as `heddle-mcp` (the import name and CLI
+stay `heddle`).
+
+### Added
+- Content-addressed contracts: one hashable YAML file per software unit
+  (signature, invariants, examples, dependencies), with subdirectory namespaces.
+- Hash-keyed verification cache: a green test result keyed on the contract,
+  implementation, and transitive dependency hashes. pytest runs only on a miss;
+  failures are never served from cache.
+- Mechanical blast radius: `get_dependents` reports the exact set of invalidated
+  dependents, direct or transitive, by hash.
+- Five MCP tools (`get_contract`, `put_contract`, `get_dependents`, `verify`,
+  `status`) and five CLI commands (`init`, `index`, `serve`, `status`, `verify`).
+- Configurable verify interpreter and timeout via `heddle serve --python`,
+  `.heddle/config.json`, or an auto-detected project `.venv`.
+- `--no-pycache-trust` / `pycache_trust` to clear stale `__pycache__` before a
+  verify run.
+- Structured errors over MCP (no stack traces).
+- CI (tests on Python 3.10 through 3.13 plus the >5x benchmark guard) and PyPI
+  Trusted Publishing on version tags.
+
+[Unreleased]: https://github.com/davet47/hashloom/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/davet47/hashloom/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/davet47/hashloom/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/davet47/hashloom/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/davet47/hashloom/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/davet47/hashloom/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/davet47/hashloom/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/davet47/hashloom/releases/tag/v0.1.0

hashloom-0.4.0/CLAUDE.md

@@ -0,0 +1,116 @@
+# Working rules for hashloom
+
+Hashloom is a hash-keyed verification cache + content-addressed contract store,
+exposed over MCP. Contracts are warp (durable), code is weft (regenerable). These
+rules override default behavior — follow them.
+
+## Git is the user's
+
+**Commit and push only when the user explicitly asks** — never on your own, and
+write **no `Co-Authored-By` trailer** when you do. The user owns the PR/merge flow
+and brings local back to a clean, synced `main` before each new piece of work.
+
+**A fresh branch per change.** The first action on any new feature/change is
+`git switch -c <scoped-name>` off `main` — never commit to `main`, and never reuse
+a previous feature branch for new work. One piece = one branch = one PR.
+
+**Never git worktrees** — too much machinery for this project; the user dislikes
+them. Don't reach for worktree isolation.
+
+## Scope discipline
+
+Anything not on the current milestone is an entry in [ISSUES.md](ISSUES.md) — file
+it there, don't write the code. The named failure mode is "scope creep toward
+Loom." Keep the surface minimal: **5 MCP tools, 5 CLI commands.** The README
+documents "the entire surface"; if a change would add to it, stop and confirm.
+(The shared-cache backend `python -m hashloom.cache_server` is a deliberate
+*operational* process, not a 6th CLI command — the client surface stays 5/5.)
+
+## Hashloom develops on hashloom
+
+The repo is itself a hashloom project: `contracts/` holds contracts for the
+stable seams (the five `api.py` functions, the `contract.py` hashing trio,
+`impl_hash`, `verification_key`, `HashloomError`, the `Store` Protocol). The
+workflow from [docs/getting-started.md](docs/getting-started.md) applies here:
+
+- **The hashloom MCP server is project-configured** in [.mcp.json](.mcp.json)
+  (`uv run hashloom serve`). When its tools are present, **prefer `get_contract`
+  packets and `get_dependents` over reading a contracted seam's source file** —
+  the ~300-token packet is the token-frugal path this project exists to prove;
+  fall back to file reads only for uncontracted code.
+- **Before changing a contracted seam**, check the blast radius (the
+  `get_dependents` MCP tool when connected — it is not a CLI command);
+  **after touching one**, `uv run hashloom verify --radius <name>` must return
+  `ok: true` — that is the inner-loop gate.
+- **A new stable seam gets a contract before its implementation.** If you (the
+  agent) derived the contract rather than the user specifying it, mark it
+  `status: inferred`; the user flips it to `confirmed` on review. `hashloom
+  status` lists the review queue.
+- **Do not contract churning interiors.** `remote.py`, `cache_server.py`, and
+  `shared.py` are deliberately uncontracted while the v0.3 hosted-store work
+  reshapes them; helpers (`tokens.py`, `project.py`) are weft. Pinning
+  interiors is the failure mode the README warns about.
+- **The hashloom gate layers on the DoD — it never replaces it.** Full
+  `uv run pytest` and the benchmark below remain the definition of done;
+  hashloom's cached verify must not be the only thing vouching for hashloom.
+
+## Definition of done: >5x token reduction
+
+`bench/benchmark.py` is the DoD guard — it exits nonzero below 5x (currently
+5x+). Run it for anything that could touch the context packets or hashing.
+**Never regress it.**
+
+## Hash stability is load-bearing
+
+`tests/test_contract_hash.py` and `tests/test_implhash.py` are the spec. Cosmetic
+input changes — whitespace, key order, comments, docstrings, file relocation —
+must never change a hash; meaning changes (signature, invariant/example order)
+must. If you touch `contract.py` or `implhash.py`, these tests are the contract.
+Run `uv run pytest` (full suite) before declaring anything done.
+
+## The store is derived
+
+`.hashloom/store.db` is rebuildable from `contracts/` via `hashloom index` — never
+hand-edit it. `contracts/*.yaml` is the source of truth.
+
+## Errors are structured
+
+Nothing leaks a stack trace over MCP. `_respond` in
+[server.py](src/hashloom/server.py) wraps every tool; raise `HashloomError(code,
+message)` for anything an agent should see. Keep it that way.
+
+## The verify interpreter
+
+`verify` shells pytest out to a resolved interpreter (see
+[config.py](src/hashloom/config.py)), in precedence order:
+
+1. `hashloom serve --python PATH`
+2. `.hashloom/config.json` → `{"python": "..."}`
+3. auto-detected project venv (`<root>/.venv/bin/python`, …)
+4. `sys.executable`
+
+So hashloom can verify a target project against *its own* venv without being
+installed into it. `hashloom status` reports the resolved interpreter.
+
+Non-Python impls resolve their own toolchain by the same precedence, keyed by the
+impl extension: a `.go` impl uses `go` (`.hashloom/config.json` → `"go"`); a
+`.ts`/`.tsx` impl uses `node` (→ `"node"`) plus the project's *own* `typescript`,
+and auto-detects the test runner (vitest / jest, else Node's `node:test`); a
+`.java` impl uses `java` (→ `"java"`, JDK >= 11) and auto-detects the runner from
+the build manifest (`pom.xml` → Maven, `build.gradle` → Gradle, committed
+`mvnw`/`gradlew` wrappers preferred).
+
+## How to run
+
+```bash
+uv run pytest                       # full suite — hash stability is load-bearing
+uv run python bench/benchmark.py    # the DoD number
+```
+
+CI (`.github/workflows/ci.yml`) runs both on every push and PR, so the DoD and
+hash-stability rules are enforced, not just documented. Keep it green.
+
+Python >=3.10. Deps: mcp, pyyaml, tiktoken, pytest. TypeScript contracts also
+need Node >=22.6 and the project's own `typescript` (CI installs a repo-local one
+via `npm ci`; `node_modules/` is gitignored). Java contracts need a JDK >=11 plus
+Maven or Gradle (CI installs Temurin; Maven ships on the runner).

hashloom-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to hashloom
+
+Thanks for your interest. hashloom is a hash-keyed verification cache and a
+content-addressed contract store, exposed over MCP. Contracts are the durable
+warp; code is the regenerable weft. A few rules keep it that way.
+
+## Scope: the surface is fixed on purpose
+
+hashloom is deliberately small: **5 MCP tools and 5 CLI commands**, and the README
+documents the entire surface. The named failure mode is "scope creep toward
+Loom." Bug fixes and docs are welcome any time. A change that would add to that
+surface needs a conversation first, so please open an issue before writing it.
+
+## Development
+
+Requires Python >= 3.10 and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run pytest                       # full suite
+uv run python bench/benchmark.py    # the definition-of-done number
+```
+
+## Two things are load-bearing
+
+1. **Hash stability.** `tests/test_contract_hash.py` and `tests/test_implhash.py`
+   are the spec. Cosmetic input changes (whitespace, key order, comments,
+   docstrings, file relocation) must never change a hash; meaning changes
+   (signature, invariant or example order) must. If you touch `contract.py` or
+   `implhash.py`, those tests are the contract.
+2. **The >5x token reduction.** `bench/benchmark.py` is the definition-of-done
+   guard and exits nonzero below 5x. Run it for anything that could touch the
+   context packets or hashing, and never regress it.
+
+Two more invariants worth knowing: nothing leaks a stack trace over MCP (tool
+errors are structured `HashloomError(code, message)` values, see `server.py`), and
+`.hashloom/store.db` is derived state rebuildable from `contracts/` via `hashloom
+index`, so never hand-edit it. `contracts/*.yaml` is the source of truth.
+
+## Pull requests
+
+- Branch off `main`, one focused change per branch.
+- `main` is protected: every PR must pass CI (pytest on Python 3.10 through 3.13,
+  plus the benchmark guard) before it can merge. Run both locally first.
+- Keep the diff scoped to one thing. If you spot an unrelated issue, file it.
+- Match the surrounding code: its naming, comment density, and idioms.
+
+Where the project is headed lives in [ROADMAP.md](ROADMAP.md); deferred non-goals
+are in [ISSUES.md](ISSUES.md).
+
+## Releases
+
+Maintainer-only, via PyPI Trusted Publishing on a version tag. See
+[RELEASING.md](RELEASING.md).

hashloom-0.4.0/Dockerfile

@@ -0,0 +1,8 @@
+# Runs the MCP server against a baked-in empty project so directory sandboxes
+# (e.g. Glama) can start it and introspect the tools. To serve a real project,
+# mount it over /app: docker run -i --rm -v "$PWD":/app <image>
+FROM python:3.13-slim
+WORKDIR /app
+COPY . /src
+RUN pip install --no-cache-dir /src && hashloom init
+ENTRYPOINT ["hashloom-mcp"]