hashloom 0.4.0__py3-none-any.whl

hashloom/__init__.py

@@ -0,0 +1,8 @@
+"""Hashloom treats software units as content-addressed contracts rather than
+files: contracts with a hash-keyed verification cache for spec-driven agent
+loops, exposed over MCP.
+
+Contracts are warp. Code is weft.
+"""
+
+__version__ = "0.4.0"

hashloom/api.py

@@ -0,0 +1,274 @@
+"""The five tool implementations, as plain functions over (root, store).
+
+server.py exposes these over MCP; the CLI and benchmark call them directly.
+Every function either returns a JSON-able dict or raises HashloomError.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from .config import resolve_python
+from .contract import contract_hash, diff_contracts, parse_contract
+from .errors import HashloomError, unknown_name
+from .langs import adapter_for
+from .project import atomic_write_text, case_collision, contract_lock, safe_contract_path
+from .store import Store
+from .verify import clear_pycache, verification_key, verify_one
+
+
+# responses carry 12-hex-char hashes — plenty to compare against, a quarter of
+# the tokens; full hashes never leave the store/verification keys
+SHORT = 12
+
+
+def _short(h: str) -> str:
+    return h[:SHORT]
+
+
+def _load(store: Store, name: str) -> tuple[dict, str]:
+    row = store.get_contract(name)
+    if row is None:
+        raise unknown_name("unknown_contract", name, store.contract_names())
+    return yaml.safe_load(row["yaml"]), row["hash"]
+
+
+def _is_inferred(store: Store, name: str) -> bool:
+    """A contract is inferred (machine-derived, not human-vetted) only when it
+    says so; absent status = confirmed, so 0.1.0 contracts keep full authority."""
+    data, _ = _load(store, name)
+    return data.get("status") == "inferred"
+
+
+def get_contract(root: Path, store: Store, name: str) -> dict:
+    """The ~300-token context packet: contract + hash + dep signatures + callers."""
+    data, chash = _load(store, name)
+    deps = []
+    for dep in data.get("deps", []):
+        dep_data, dep_hash = _load(store, dep)
+        entry = {"name": dep, "signature": dep_data["signature"], "hash": _short(dep_hash)}
+        if dep_data.get("status") == "inferred":
+            entry["inferred"] = True
+        deps.append(entry)
+    return {
+        "name": name,
+        "hash": _short(chash),
+        # name and deps would duplicate the envelope — the deps array below
+        # carries them with signatures attached
+        "contract": {k: v for k, v in data.items() if k not in ("name", "deps")},
+        "deps": deps,
+        "callers": store.dependents_of(name),
+    }
+
+
+def put_contract(root: Path, store: Store, name: str, yaml_text: str) -> dict:
+    """Validate, write to contracts/, reindex the one unit, invalidate dependents."""
+    data = parse_contract(yaml_text, expect_name=name)
+    known = set(store.contract_names()) | {name}
+    for dep in data.get("deps", []):
+        if dep == name:
+            raise HashloomError("invalid_shape", f"'{name}' cannot depend on itself", contract=name)
+        if dep not in known:
+            raise unknown_name("unknown_dep", dep, sorted(known - {name}), contract=name)
+
+    new_hash = contract_hash(data)
+    target = safe_contract_path(root, name)  # also refuses a name that escapes contracts/
+    collision = case_collision(target)
+    if collision is not None:
+        raise HashloomError(
+            "name_collision",
+            f"'{name}' collides with existing contract file '{collision}' on a case-insensitive filesystem",
+            contract=name,
+        )
+    # lock the name so concurrent put_contract on it can't interleave the file
+    # write and the store update and leave the two disagreeing
+    with contract_lock(root, name):
+        old = store.get_contract(name)
+        changed = old is None or old["hash"] != new_hash
+        # what changed vs the previously stored contract: empty for a new unit or
+        # a cosmetic-only edit, using the same normalisation as the hash
+        diff = diff_contracts(yaml.safe_load(old["yaml"]), data) if old is not None else {}
+
+        atomic_write_text(target, yaml_text)
+        store.upsert_contract(name, new_hash, yaml_text)
+        store.set_deps(name, data.get("deps", []))
+        if "impl" in data:
+            adapter = adapter_for(data["impl"])
+            try:
+                ihash = adapter.impl_hash(root, data["impl"], contract=name)
+            except HashloomError:
+                ihash = None
+            store.upsert_impl(name, ihash, data["impl"].partition("::")[0])
+
+        invalidated: list[str] = []
+        if changed:
+            invalidated = store.dependents_of(name, transitive=True)
+            store.mark_stale([name, *invalidated])
+    result = {"name": name, "hash": _short(new_hash), "changed": changed, "invalidated": invalidated}
+    # advisory provenance flags — present only when something is actually inferred
+    if data.get("status") == "inferred":
+        result["inferred"] = True
+    invalidated_inferred = [n for n in invalidated if _is_inferred(store, n)]
+    if invalidated_inferred:
+        result["invalidated_inferred"] = invalidated_inferred
+    if diff:
+        result["diff"] = diff
+    return result
+
+
+def get_dependents(root: Path, store: Store, name: str, transitive: bool = False) -> dict:
+    """Blast-radius query: who is invalidated if this contract changes."""
+    if store.get_contract(name) is None:
+        raise unknown_name("unknown_contract", name, store.contract_names())
+    hashes = store.contract_hashes()
+    names = store.dependents_of(name, transitive=transitive)
+    dependents = []
+    for n in names:
+        d = {"name": n, "hash": _short(hashes[n])}
+        if _is_inferred(store, n):
+            d["inferred"] = True  # advisory: this dependent's contract is unvetted
+        dependents.append(d)
+    return {"name": name, "transitive": transitive, "dependents": dependents}
+
+
+def _radius(store: Store, names: list[str]) -> list[str]:
+    """Each seed plus its transitive dependents, deduped in encounter order.
+
+    Spec-only units (no impl) are dropped — nothing to verify, the same rule
+    `status` uses for dirtiness. Unknown names are kept so they surface as
+    error results and fail the gate rather than vanishing silently.
+    """
+    out: list[str] = []
+    seen: set[str] = set()
+    for name in names:
+        for n in (name, *store.dependents_of(name, transitive=True)):
+            if n in seen:
+                continue
+            seen.add(n)
+            row = store.get_contract(n)
+            if row is not None and "impl" not in yaml.safe_load(row["yaml"]):
+                continue
+            out.append(n)
+    return out
+
+
+def verify(
+    root: Path,
+    store: Store,
+    names: str | list[str],
+    python: str | None = None,
+    timeout: int | float | None = None,
+    pycache_trust: bool = True,
+    radius: bool = False,
+) -> dict:
+    """Per-unit cached-pass / pass / fail. Runs pytest only on cache misses.
+
+    `radius=True` widens each name to its full blast radius (itself plus every
+    transitive dependent), and the top-level `ok` is the hard pass/fail bit a
+    CI step or agent loop can block on.
+    """
+    if isinstance(names, str):
+        names = [names]
+    if radius:
+        names = _radius(store, names)
+    if not pycache_trust:
+        clear_pycache(root)  # once per batch, before any pytest run
+    results = []
+    for name in names:
+        try:
+            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)
+        except HashloomError as e:
+            results.append({"name": name, "status": "error", **e.to_dict()})
+    # the gate bit: true iff every unit is green (vacuously true for an empty
+    # radius — nothing invalidated means nothing to block on)
+    ok = all(r["status"] in ("pass", "cached-pass") for r in results)
+    return {"ok": ok, "results": results}
+
+
+def cached_impl_hash(root: Path, store: Store, impl: str, contract: str | None = None) -> str:
+    """`impl_hash` memoised by (impl ref, file mtime_ns, size).
+
+    `status` computes an impl hash for every contract; re-reading and re-parsing
+    each file on every call is the O(n) cost in ISSUES #10. `verify` never uses
+    this — a stale *verification* is unsafe, so it always hashes fresh — but
+    `status` is informational, and mtime_ns makes a same-size-same-instant miss
+    vanishingly unlikely.
+    """
+    adapter = adapter_for(impl)
+    path = root / impl.partition("::")[0]
+    try:
+        st = path.stat()
+    except OSError:
+        return adapter.impl_hash(root, impl, contract=contract)  # absent file: let it raise cleanly
+    cached = store.get_cached_impl_hash(impl)
+    if cached is not None and cached["mtime_ns"] == st.st_mtime_ns and cached["size"] == st.st_size:
+        return cached["impl_hash"]
+    h = adapter.impl_hash(root, impl, contract=contract)
+    store.put_cached_impl_hash(impl, st.st_mtime_ns, st.st_size, h)
+    return h
+
+
+def status(root: Path, store: Store) -> dict:
+    """Dirty contracts, stale verifications, cache hit-rate, token counters."""
+    dirty: list[str] = []
+    inferred: list[str] = []
+    for name in store.contract_names():
+        data, _ = _load(store, name)
+        if data.get("status") == "inferred":
+            inferred.append(name)  # the human review queue; spec-only units count too
+        if "impl" not in data:
+            continue  # spec-only contracts don't need verification
+        try:
+            ihash = cached_impl_hash(root, store, data["impl"], contract=name)
+        except HashloomError:
+            dirty.append(name)
+            continue
+        adapter = adapter_for(data["impl"])
+        thash = adapter.test_source_hash(root, data.get("tests", []))
+        try:
+            tid = adapter.toolchain_identity(root)  # same key component verify stored
+        except HashloomError:
+            dirty.append(name)  # can't resolve the toolchain -> can't claim a green
+            continue
+        v = store.get_verification(verification_key(store, name, ihash, thash, tid))
+        if v is None or v["status"] != "pass" or v["stale"]:
+            dirty.append(name)
+
+    c = store.counters()
+    hits, misses = c.get("cache_hits", 0), c.get("cache_misses", 0)
+    total = hits + misses
+    br, bru = c.get("bust_rechecks", 0), c.get("bust_rechecks_unchanged", 0)
+    tokens_by_tool = {k.removeprefix("tokens."): v for k, v in c.items() if k.startswith("tokens.")}
+    out = {
+        "contracts": len(store.contract_names()),
+        "dirty": dirty,
+        "stale_verifications": store.stale_verifications(),
+        "python": resolve_python(root),  # which interpreter verify shells pytest to
+        "cache": {
+            "hits": hits,
+            "misses": misses,
+            "hit_rate": round(hits / total, 3) if total else None,
+        },
+        # re-verifications triggered by a contract-hash bust, and how many changed
+        # no verdict (wasted work); wasted_rate falls once invariants leave the hash
+        "rechecks": {
+            "after_change": br,
+            "verdict_unchanged": bru,
+            "wasted_rate": round(bru / br, 3) if br else None,
+        },
+        "tokens": {"total": sum(tokens_by_tool.values()), "by_tool": tokens_by_tool},
+    }
+    if inferred:  # key absent on confirmed-only projects — zero token cost
+        out["inferred"] = inferred
+    return out

hashloom/cache_server.py

@@ -0,0 +1,154 @@
+"""The hashloom shared verification-cache server.
+
+A minimal stdlib HTTP server wrapping one `SqliteStore`, exposing exactly the four
+team-portable Store operations `LayeredStore` needs -- get/record a verdict,
+get/put a blob -- as a tiny JSON API behind a bearer token. A team points each
+developer's `.hashloom/config.json` `{"shared": {...}}` at one of these, so a unit
+verified green once is served to everyone (see docs/hosted-store.md).
+
+It is intentionally NOT a `hashloom` subcommand (the 5-CLI surface is fixed); run it
+as a separate operational process:
+
+    python -m hashloom.cache_server --db cache.db --token SECRET [--host H --port P]
+
+Single-threaded by design: a `SqliteStore` holds one sqlite connection (not
+thread-safe), and the verdict/blob writes are idempotent upserts, so
+last-writer-wins is fine for the MVP. A future throughput upgrade is
+`ThreadingHTTPServer` + a per-thread or lock-guarded connection; CAS and
+concurrent-writer ordering are deferred (docs/hosted-store.md #4).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hmac
+import json
+import os
+import sys
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import unquote
+
+from .store import SqliteStore
+
+DEFAULT_PORT = 8770
+
+
+class CacheServer(HTTPServer):
+    """An HTTPServer that holds the store and expected token for the handler."""
+
+    def __init__(self, addr: tuple[str, int], store: SqliteStore, token: str):
+        super().__init__(addr, _Handler)
+        self.store = store
+        self.token = token
+
+
+class _Handler(BaseHTTPRequestHandler):
+    server_version = "hashloom-cache/1"
+
+    # -- helpers ------------------------------------------------------------
+
+    def _send(self, status: int, body: dict | None = None) -> None:
+        payload = json.dumps(body).encode("utf-8") if body is not None else b""
+        self.send_response(status)
+        if payload:
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        if payload:
+            self.wfile.write(payload)
+
+    def _error(self, status: int, code: str, message: str) -> None:
+        self._send(status, {"error": {"code": code, "message": message}})
+
+    def _authed(self) -> bool:
+        header = self.headers.get("Authorization", "")
+        prefix = "Bearer "
+        if not header.startswith(prefix):
+            return False
+        return hmac.compare_digest(header[len(prefix):], self.server.token)
+
+    def _read_body(self) -> dict | None:
+        length = int(self.headers.get("Content-Length") or 0)
+        if length <= 0:
+            return None
+        try:
+            return json.loads(self.rfile.read(length).decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError, ValueError):
+            return None
+
+    def log_message(self, *args) -> None:  # keep the cache server quiet
+        pass
+
+    # -- routes -------------------------------------------------------------
+
+    def do_GET(self) -> None:
+        if not self._authed():
+            return self._error(401, "unauthorized", "missing or invalid bearer token")
+        store = self.server.store
+        if self.path.startswith("/verification/"):
+            row = store.get_verification(unquote(self.path[len("/verification/"):]))
+            return self._send(200, row) if row is not None else self._error(404, "not_found", "no such verdict")
+        if self.path.startswith("/blob/"):
+            content = store.get_blob(unquote(self.path[len("/blob/"):]))
+            return self._send(200, {"content": content}) if content is not None else self._error(404, "not_found", "no such blob")
+        return self._error(404, "not_found", "unknown route")
+
+    def do_POST(self) -> None:
+        if not self._authed():
+            return self._error(401, "unauthorized", "missing or invalid bearer token")
+        store = self.server.store
+        body = self._read_body()
+        if not isinstance(body, dict):
+            return self._error(400, "bad_request", "expected a JSON object body")
+        if self.path == "/verification":
+            try:
+                key, name, status = body["key"], body["contract_name"], body["status"]
+            except (KeyError, TypeError):
+                return self._error(400, "bad_request", "missing key/contract_name/status")
+            if status != "pass":
+                return self._error(400, "only_greens", "the shared cache stores passes only")
+            store.record_verification(key, name, status, body.get("summary", ""))
+            return self._send(204)
+        if self.path == "/blob":
+            content = body.get("content")
+            if not isinstance(content, str):
+                return self._error(400, "bad_request", "blob content must be a string")
+            return self._send(200, {"hash": store.put_blob(content)})
+        return self._error(404, "not_found", "unknown route")
+
+
+def serve(db: str, token: str, host: str = "127.0.0.1", port: int = DEFAULT_PORT) -> None:
+    store = SqliteStore(db, check_same_thread=False)  # used on the serve_forever thread
+    httpd = CacheServer((host, port), store, token)
+    print(f"hashloom cache server on http://{host}:{httpd.server_address[1]}  (db: {db})", file=sys.stderr)
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        httpd.server_close()
+        store.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="python -m hashloom.cache_server",
+        description="hashloom shared verification-cache server (operational, not a hashloom subcommand)",
+    )
+    p.add_argument("--db", default="cache.db", help="sqlite file for the shared cache (default: cache.db)")
+    p.add_argument("--host", default="127.0.0.1", help="bind host (default: 127.0.0.1; use 0.0.0.0 to share)")
+    p.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"bind port (default: {DEFAULT_PORT})")
+    p.add_argument(
+        "--token",
+        default=os.environ.get("HASHLOOM_CACHE_TOKEN"),
+        help="bearer token clients must present (or set HASHLOOM_CACHE_TOKEN)",
+    )
+    args = p.parse_args(argv)
+    if not args.token:
+        p.error("a --token (or HASHLOOM_CACHE_TOKEN env var) is required; refusing to run an unauthenticated cache")
+    serve(args.db, args.token, host=args.host, port=args.port)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hashloom/cli.py

@@ -0,0 +1,108 @@
+"""CLI: hashloom init · hashloom index · hashloom serve · hashloom status · hashloom verify."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .errors import HashloomError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="hashloom", description="Content-addressed contracts + cached verification over MCP.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("init", help="create .hashloom/ and contracts/ in the current directory")
+    sub.add_parser("index", help="rebuild the store from contracts/")
+    serve_parser = sub.add_parser("serve", help="run the MCP server on stdio")
+    serve_parser.add_argument(
+        "--python",
+        metavar="PATH",
+        help="interpreter to run pytest with (default: project .venv, else this interpreter)",
+    )
+    serve_parser.add_argument(
+        "--no-pycache-trust",
+        action="store_true",
+        help="clear project __pycache__ before each verify run (don't trust stale bytecode)",
+    )
+    sub.add_parser("status", help="dirty contracts, stale verifications, cache hit-rate, token counters")
+    verify_parser = sub.add_parser("verify", help="run cached verification for one or more contracts")
+    verify_parser.add_argument("names", nargs="+", metavar="NAME", help="contract names to verify")
+    verify_parser.add_argument(
+        "--radius",
+        action="store_true",
+        help="also verify every transitive dependent of each NAME (the blast radius)",
+    )
+    verify_parser.add_argument(
+        "--python",
+        metavar="PATH",
+        help="interpreter to run pytest with (default: project .venv, else this interpreter)",
+    )
+    verify_parser.add_argument(
+        "--no-pycache-trust",
+        action="store_true",
+        help="clear project __pycache__ before running (don't trust stale bytecode)",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "init":
+            from .project import init_project
+
+            created = init_project(Path.cwd())
+            print("\n".join(f"created {p}" for p in created) if created else "already initialised")
+            return 0
+
+        from .project import find_root
+
+        root = Path.cwd() if args.command == "init" else find_root()
+
+        if args.command == "serve":
+            from .server import serve
+
+            serve(root, python=args.python, pycache_trust=False if args.no_pycache_trust else None)
+            return 0
+
+        from .remote import build_store
+
+        store = build_store(root)  # local, or LayeredStore over a shared cache if configured
+        if args.command == "index":
+            from .indexer import index
+
+            print(json.dumps(index(root, store), indent=2))
+        elif args.command == "status":
+            from . import api
+
+            print(json.dumps(api.status(root, store), indent=2))
+        elif args.command == "verify":
+            from . import api
+            from .config import resolve_pycache_trust
+
+            trust = resolve_pycache_trust(root, override=False if args.no_pycache_trust else None)
+            result = api.verify(root, store, args.names, python=args.python, pycache_trust=trust, radius=args.radius)
+            print(json.dumps(result, indent=2))
+            # the CI/pre-commit gate: exit mirrors the response's `ok` bit
+            if not result["ok"]:
+                return 1
+        return 0
+    except HashloomError as e:
+        print(json.dumps(e.to_dict(), indent=2), file=sys.stderr)
+        return 1
+
+
+def serve_main(argv: list[str] | None = None) -> int:
+    """`hashloom-mcp` console script: `hashloom serve` as a single entry point.
+
+    The Docker image's ENTRYPOINT and a direct uvx target. Registry-listed
+    launches use `uvx hashloom serve` via server.json's packageArguments, since
+    the bare `hashloom` script is the CLI. A launch shim, not a sixth CLI
+    command.
+    """
+    return main(["serve", *(sys.argv[1:] if argv is None else argv)])
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hashloom/config.py

@@ -0,0 +1,135 @@
+"""Interpreter resolution for the verify pytest runner.
+
+`verify` shells pytest out to a python interpreter; which one is resolved by
+precedence (most explicit first):
+
+  1. an explicit override — the ``hashloom serve --python PATH`` flag
+  2. ``.hashloom/config.json`` -> ``{"python": "..."}``
+  3. an auto-detected project venv (``<root>/.venv/bin/python``, ...)
+  4. ``sys.executable`` — the interpreter running hashloom itself (the v0.1 default)
+
+This lets hashloom, even installed globally, run a target project's tests against
+that project's own venv — without being installed into it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from .errors import HashloomError
+from .project import HASHLOOM_DIR
+
+CONFIG_NAME = "config.json"
+DEFAULT_TIMEOUT = 300  # seconds for a single pytest run; override via verify_timeout
+
+# checked in order; first one that exists wins. The .hashloom/config.json file is
+# the future home for other project settings too (e.g. the verify timeout).
+_VENV_CANDIDATES = (
+    ".venv/bin/python",
+    ".venv/bin/python3",
+    "venv/bin/python",
+    "venv/bin/python3",
+    ".venv/Scripts/python.exe",  # Windows
+)
+
+
+def config_path(root: Path) -> Path:
+    return root / HASHLOOM_DIR / CONFIG_NAME
+
+
+def load_config(root: Path) -> dict:
+    """Read .hashloom/config.json. Returns {} if absent; raises on malformed JSON."""
+    path = config_path(root)
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        raise HashloomError("bad_config", f"could not read {path.name}: {e}")
+    if not isinstance(data, dict):
+        raise HashloomError("bad_config", f"{path.name} must be a JSON object")
+    return data
+
+
+def _is_executable(path: Path) -> bool:
+    return path.is_file() and os.access(path, os.X_OK)
+
+
+def _check(path: Path, source: str, raw: str) -> str:
+    """Validate an explicitly-configured interpreter — fail clean if unusable."""
+    if not _is_executable(path):
+        raise HashloomError("bad_python", f"{source} '{raw}' is not an executable interpreter")
+    return str(path)
+
+
+def resolve_python(root: Path, override: str | None = None) -> str:
+    """Resolve the interpreter verify should run pytest with. See module docstring."""
+    if override is not None:
+        return _check(Path(override).expanduser(), "--python", override)
+
+    configured = load_config(root).get("python")
+    if configured:
+        p = Path(configured).expanduser()
+        if not p.is_absolute():
+            p = root / p  # config paths are project-relative
+        return _check(p, ".hashloom/config.json python", configured)
+
+    for rel in _VENV_CANDIDATES:
+        cand = root / rel
+        if _is_executable(cand):
+            return str(cand)
+
+    return sys.executable
+
+
+def resolve_timeout(root: Path) -> int | float:
+    """Per-run pytest timeout in seconds (.hashloom/config.json verify_timeout)."""
+    value = load_config(root).get("verify_timeout")
+    if value is None:
+        return DEFAULT_TIMEOUT
+    # bool is an int subclass — reject it explicitly so `true` isn't read as 1
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+        raise HashloomError("bad_config", f"verify_timeout must be a positive number, got {value!r}")
+    return value
+
+
+def resolve_pycache_trust(root: Path, override: bool | None = None) -> bool:
+    """Whether verify may trust pre-existing __pycache__ (default True).
+
+    The runner already passes -B / PYTHONDONTWRITEBYTECODE so its own runs never
+    write bytecode, but a stale user-written .pyc that happens to share the
+    source's size and mtime-second could still be loaded. Set `pycache_trust:
+    false` in .hashloom/config.json (or pass `--no-pycache-trust`) to clear the
+    project's bytecode caches before each verify run instead.
+    """
+    if override is not None:
+        return override
+    value = load_config(root).get("pycache_trust")
+    if value is None:
+        return True
+    if not isinstance(value, bool):
+        raise HashloomError("bad_config", f"pycache_trust 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.
+
+    `.hashloom/config.json` -> `{"shared": {"url": "...", "token": "..."}}` selects a
+    remote cache the local store reads/writes through (see remote.py / shared.py).
+    Validated here so a malformed block fails clean; absent means local-only.
+    """
+    cfg = load_config(root).get("shared")
+    if cfg is None:
+        return None
+    if not isinstance(cfg, dict):
+        raise HashloomError("bad_config", "shared must be a JSON object")
+    url, token = cfg.get("url"), cfg.get("token")
+    if not isinstance(url, str) or not url:
+        raise HashloomError("bad_config", "shared.url must be a non-empty string")
+    if not isinstance(token, str) or not token:
+        raise HashloomError("bad_config", "shared.token must be a non-empty string")
+    return {"url": url, "token": token}