verify: strict provenance mode — refuse, not warn, on inferred contracts (#49) (#87)

Opt-in .hashloom/config.json {"strict_provenance": true}: verify refuses
any unit whose dependency closure contains a status: inferred contract —
a structured inferred_contract error naming the unvetted contracts, ok
false, CLI exit 1. The refusal fires before verify_one, so no tests run
and no cache entry is written; a pre-existing green revives when the
contract is confirmed (the flip stays free). Reads and writes keep their
advisory flags so machine-drafted batches still land and get reviewed.
Config-only: resolved inside api.verify, so no contracted signature
changed (verify.yaml's invariant reword is hash-free) and no new flags,
tools, or commands — the 5/5 surface is unchanged.

Co-authored-by: dt <david@e3.com.au>

Author: davet47

CHANGELOG.md

@@ -7,6 +7,15 @@ follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ### Added
+- Strict provenance mode (#49): opt-in `.hashloom/config.json`
+  `{"strict_provenance": true}`. `verify` refuses any unit whose dependency
+  closure contains a `status: inferred` contract — a structured
+  `inferred_contract` error per unit (`ok: false`, CLI exit 1), with the
+  unvetted names listed. The refusal runs no tests and writes no cache
+  entry, so a pre-existing green revives when the contract is confirmed
+  (the flip stays free). Reads (`get_contract`, `get_dependents`, `status`)
+  and writes keep their advisory flags so machine-drafted batches can still
+  land and be reviewed. Config-only: no new flags, tools, or commands.
 - `integrations/speckit-hashloom/` (#75): a [GitHub
   spec-kit](https://github.com/github/spec-kit) extension — the greenfield
   counterpart to the graphify importer. `/speckit.hashloom.seams` drafts

README.md

@@ -100,7 +100,7 @@ A contract belongs on a stable seam: an interface other units depend on and that
 
 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 — 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`). Absent means `confirmed`, and confirming an inferred contract after review is free: status is provenance, not meaning, so the flip invalidates nothing.
+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
 
@@ -115,7 +115,7 @@ A contract an agent reverse-engineers from existing code can declare that it has
 | `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` / `pass` / `fail` plus a top-level `ok` gate bit; `radius=true` widens each name to its full blast radius; runs tests only on cache misses; failures come back as a ≤40-token assertion summary, never a traceback; inferred contracts in the closure flagged |
+| `verify` | per-unit `cached-pass` / `pass` / `fail` plus a top-level `ok` gate bit; `radius=true` widens each name to its full blast radius; runs tests only on cache misses; failures come back as a ≤40-token assertion summary, never a traceback; inferred contracts in the closure flagged (refused under strict provenance mode) |
 | `status` | dirty contracts, stale verifications, cache hit-rate, resolved verify interpreter, cumulative token counters |
 
 Every tool returns structured errors — `{"error": {"code": "unknown_dep", "message": "'Regoin' not found — nearest: 'Region'"}}` — never a stack trace.
@@ -129,10 +129,11 @@ globally-installed hashloom can verify a project against its own virtualenv with
 being installed into it; `hashloom status` shows which interpreter it resolved.
 
 `.hashloom/config.json` also takes `verify_timeout` (seconds per pytest run,
-default 300) for suites that need longer than the default, and `pycache_trust`
+default 300) for suites that need longer than the default, `pycache_trust`
 (default `true`); set `pycache_trust: false` — or pass `--no-pycache-trust` — to
 clear the project's `__pycache__` before each verify run, so a stale `.pyc` can
-never shadow the current source.
+never shadow the current source, and `strict_provenance` (default `false`) to
+make `verify` refuse units whose closure contains inferred contracts.
 
 ### Beyond Python
 

ROADMAP.md

@@ -67,9 +67,10 @@ remaining hard parts from [docs/hosted-store.md](docs/hosted-store.md):
   honestly; shrinking it (flakiness detection, an optional re-verify TTL, or
   marking tests untrusted-for-caching) is open design work, not yet scheduled.
 - **Strict provenance mode** ([#49](https://github.com/davet47/hashloom/issues/49))
-  — an opt-in config that upgrades inferred-contract warnings to structured
-  refusals, for teams that want unvetted contracts to hard-fail. Deferred by
-  design; layerable with no schema change.
+  — ✓ **Shipped** (unreleased): `.hashloom/config.json` `{"strict_provenance":
+  true}` upgrades verify's inferred-contract warnings to structured refusals
+  (`inferred_contract`); reads and writes stay advisory. Landed with no schema
+  change, as designed.
 
 ## Bigger bets
 

contracts/verify.yaml

@@ -7,13 +7,15 @@ invariants:
   - the top-level ok is the gate — true iff every unit is green; errors and unknown names block
   - radius widens each name to itself plus every transitive dependent, spec-only units dropped, typos kept
   - failure summaries stay within the token budget, never a traceback
-  - inferred contracts anywhere in a unit's closure are named in its result, advisory only
+  - inferred contracts anywhere in a unit's closure are named in its result — advisory by default; with strict_provenance set, the unit refuses with inferred_contract instead of verifying, running no tests and writing no cache entry
 tests:
   - tests/test_verify.py::test_first_run_passes_then_caches
   - tests/test_verify.py::test_failures_are_not_served_from_cache
   - tests/test_verify.py::test_ok_bit_is_the_gate
   - tests/test_verify.py::test_radius_verifies_the_blast_radius_in_one_call
   - tests/test_verify.py::test_verify_flags_inferred_closure_even_on_cached_pass
   - tests/test_verify.py::test_confirming_inferred_contract_keeps_cached_green
+  - tests/test_verify.py::test_strict_provenance_refuses_inferred_unit
+  - tests/test_verify.py::test_strict_refusal_preserves_cached_green
 impl: src/hashloom/api.py::verify
 status: confirmed

docs/getting-started.md

@@ -100,8 +100,11 @@ One call verifies the unit plus everything it invalidates, serves cached greens
 for whatever nothing busted, runs tests for the rest, and returns a single
 `ok: true|false` (the CLI exits nonzero on false — the same gate works in CI or
 a pre-commit hook). Until an inferred contract is confirmed, every verify and
-blast-radius answer that rests on it carries an `inferred` flag: advisory,
-never an error, but visible.
+blast-radius answer that rests on it carries an `inferred` flag: advisory by
+default, but visible. (Teams that want unvetted contracts to hard-fail can set
+`{"strict_provenance": true}` in `.hashloom/config.json` — `verify` then
+refuses such units with a structured `inferred_contract` error until they're
+reviewed; see the README.)
 
 **Contract changes announce their blast radius.** When you later change a
 confirmed contract — a signature, an example — the `put_contract` response

src/hashloom/api.py

@@ -10,7 +10,7 @@
 
 import yaml
 
-from .config import resolve_python
+from .config import resolve_python, resolve_strict_provenance
 from .contract import contract_hash, diff_contracts, parse_contract
 from .errors import HashloomError, unknown_name
 from .langs import adapter_for
@@ -175,16 +175,30 @@ def verify(
         names = _radius(store, names)
     if not pycache_trust:
         clear_pycache(root)  # once per batch, before any pytest run
+    strict = resolve_strict_provenance(root)
     results = []
     for name in names:
         try:
+            # computed here, not in verify_one: outside the cache key, so the flag
+            # reflects *current* status even when the verdict is a cached-pass
+            inferred = []
+            if store.get_contract(name) is not None:  # unknown names keep erroring as unknown_contract
+                inferred = [n for n in (name, *store.transitive_deps(name)) if _is_inferred(store, n)]
+            if strict and inferred:
+                # refuse before verify_one: no pytest runs, no cache entry is
+                # written, and any existing green survives for after the confirm
+                e = HashloomError(
+                    "inferred_contract",
+                    "strict provenance: verification rests on unvetted contracts: "
+                    f"{', '.join(inferred)} — review and confirm them (`hashloom status` lists the queue)",
+                    contract=name,
+                )
+                results.append({"name": name, "status": "error", "inferred": inferred, **e.to_dict()})
+                continue
             r = verify_one(root, store, name, python=python, timeout=timeout)
             r.pop("key")  # internal cache key — pure token weight to an agent
             if not r["summary"]:
                 r.pop("summary")
-            # computed here, not in verify_one: outside the cache key, so the flag
-            # reflects *current* status even when the verdict is a cached-pass
-            inferred = [n for n in (name, *store.transitive_deps(name)) if _is_inferred(store, n)]
             if inferred:
                 r["inferred"] = inferred
             results.append(r)

src/hashloom/config.py

@@ -115,6 +115,17 @@ def resolve_pycache_trust(root: Path, override: bool | None = None) -> bool:
     return value
 
 
+def resolve_strict_provenance(root: Path) -> bool:
+    """Whether verify refuses units whose closure contains inferred contracts
+    (default False — inferred stays advisory unless a team opts in)."""
+    value = load_config(root).get("strict_provenance")
+    if value is None:
+        return False
+    if not isinstance(value, bool):
+        raise HashloomError("bad_config", f"strict_provenance must be true or false, got {value!r}")
+    return value
+
+
 def resolve_shared_store(root: Path) -> dict | None:
     """Config for a shared/remote verification cache, or None if not configured.
 

src/hashloom/server.py

@@ -70,7 +70,9 @@ def verify(names: list[str], radius: bool = False) -> dict:
         already green in the cache. `radius=true` widens each name to its full
         blast radius (itself plus every transitive dependent); the top-level
         `ok` is the hard pass/fail to gate on. An `inferred` list names any
-        unconfirmed contracts a verdict rests on."""
+        unconfirmed contracts a verdict rests on; with `strict_provenance`
+        set in .hashloom/config.json such units refuse (`inferred_contract`)
+        instead of verifying."""
         return _respond(
             "verify",
             lambda: api.verify(

tests/test_cli.py

@@ -74,6 +74,21 @@ def test_verify_cli_outside_project_errors(tmp_path, monkeypatch, capsys):
     assert err["error"]["code"] == "no_project"
 
 
+def test_verify_cli_strict_provenance_refuses_with_exit_1(project, monkeypatch, capsys):
+    root, store = project
+    text = (root / "contracts" / "total.yaml").read_text()
+    (root / "contracts" / "total.yaml").write_text(text + "status: inferred\n")
+    from hashloom.indexer import index
+
+    index(root, store)
+    (root / ".hashloom" / "config.json").write_text('{"strict_provenance": true}')
+    monkeypatch.chdir(root)
+    rc = main(["verify", "total"])
+    out = json.loads(capsys.readouterr().out)
+    assert rc == 1
+    assert out["results"][0]["error"]["code"] == "inferred_contract"
+
+
 def test_init_cli_creates_then_reports_already_initialised(tmp_path, monkeypatch, capsys):
     monkeypatch.chdir(tmp_path)
     assert main(["init"]) == 0

tests/test_verify.py

@@ -2,7 +2,13 @@
 changes anywhere in the dep closure bust the cache; failure summaries stay
 within the token budget."""
 
+import json
+
+import pytest
+
 from hashloom import api, tokens
+from hashloom.config import config_path, resolve_strict_provenance
+from hashloom.errors import HashloomError
 from hashloom.indexer import index
 from hashloom.verify import SUMMARY_MAX_TOKENS
 
@@ -202,6 +208,70 @@ def test_confirming_inferred_contract_keeps_cached_green(project):
     assert all("inferred" not in r for r in out["results"])
 
 
+def _strict_on(root) -> None:
+    config_path(root).write_text(json.dumps({"strict_provenance": True}), encoding="utf-8")
+
+
+def test_strict_provenance_refuses_inferred_unit(project):
+    root, store = project
+    text = (root / "contracts" / "total.yaml").read_text()
+    api.put_contract(root, store, "total", text + "status: inferred\n")
+    _strict_on(root)
+    out = api.verify(root, store, ["total"])
+    assert out["ok"] is False
+    r = out["results"][0]
+    assert r["status"] == "error"
+    assert r["error"]["code"] == "inferred_contract"
+    assert "total" in r["error"]["message"]
+    assert r["inferred"] == ["total"]
+    # refused before verify_one: no pytest ran, no verdict was cached
+    assert store.counters().get("test_runs", 0) == 0
+
+
+def test_strict_provenance_refuses_dependent_of_inferred(project):
+    root, store = project
+    text = (root / "contracts" / "total.yaml").read_text()
+    api.put_contract(root, store, "total", text + "status: inferred\n")
+    _strict_on(root)
+    # report is confirmed, but its closure rests on the unvetted total
+    out = api.verify(root, store, ["report"])
+    assert out["ok"] is False
+    assert out["results"][0]["error"]["code"] == "inferred_contract"
+    assert out["results"][0]["inferred"] == ["total"]
+
+
+def test_strict_refusal_preserves_cached_green(project):
+    root, store = project
+    assert statuses(api.verify(root, store, ["total"])) == {"total": "pass"}
+    runs_before = store.counters()["test_runs"]
+    text = (root / "contracts" / "total.yaml").read_text()
+    api.put_contract(root, store, "total", text + "status: inferred\n")
+    _strict_on(root)
+    assert api.verify(root, store, ["total"])["ok"] is False  # refused, not failed
+    # the review flip: the refusal wrote nothing, so the old green revives
+    api.put_contract(root, store, "total", text)
+    out = api.verify(root, store, ["total"])
+    assert statuses(out) == {"total": "cached-pass"}
+    assert store.counters()["test_runs"] == runs_before
+
+
+def test_strict_unknown_name_still_errors_as_unknown(project):
+    root, store = project
+    _strict_on(root)
+    out = api.verify(root, store, ["nope"])
+    assert out["ok"] is False
+    assert out["results"][0]["error"]["code"] == "unknown_contract"
+
+
+def test_strict_provenance_resolver_defaults_off_and_rejects_bad_values(project):
+    root, _ = project
+    assert resolve_strict_provenance(root) is False  # no key -> advisory as before
+    config_path(root).write_text(json.dumps({"strict_provenance": "yes"}), encoding="utf-8")
+    with pytest.raises(HashloomError) as exc:
+        resolve_strict_provenance(root)
+    assert exc.value.code == "bad_config"
+
+
 def test_status_reports_dirty_and_hit_rate(project):
     root, store = project
     s = api.status(root, store)