bruriah 0.1.0__py3-none-any.whl

bruriah/__init__.py

@@ -0,0 +1,30 @@
+"""Bruriah: a read-only, two-tool MCP knowledge router over your own corpus."""
+from __future__ import annotations
+
+import importlib.util
+
+__version__ = "0.1.0"
+
+# Bruriah needs POSIX file primitives and there is no partial mode without them. Activation swaps a
+# pointer under `flock` with `O_NOFOLLOW` and re-confirms the file's identity afterwards, which is
+# what makes promoting a snapshot atomic and unspoofable; Windows has different primitives with
+# different semantics, and a half-ported version of that guarantee is worse than none, because it
+# would fail silently instead of loudly.
+#
+# The wheel is `py3-none-any`, so pip installs it happily on Windows and the first command then
+# died with a bare `ModuleNotFoundError: No module named 'fcntl'` raised several frames deep. That
+# reads as a broken package rather than an unsupported platform. Detecting the capability rather
+# than checking `sys.platform` keeps this honest about what is actually required.
+if importlib.util.find_spec("fcntl") is None:  # pragma: no cover -- POSIX-only by construction
+    raise ImportError(
+        "Bruriah requires macOS or Linux: it depends on POSIX file locking (fcntl), which this "
+        "platform does not provide.\n"
+        "\n"
+        "On Windows, run it under WSL -- that is a real Linux and needs no changes:\n"
+        "    wsl --install          (once, then reopen your terminal)\n"
+        "    pip install bruriah    (inside WSL)\n"
+        "\n"
+        "Native Windows support would mean reimplementing the atomic pointer swap that makes "
+        "activation safe, and that is deliberately not done half-way. If you want it, open an "
+        "issue saying so -- knowing someone is waiting is what would make it worth doing."
+    )

bruriah/approvals.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+from .candidates import AnalysisReport, CandidateError, analyze_candidate
+
+# Human approval: the second of the two STRONG axes in this project's trust model, the other being
+# the permission envelope. A signature says who published a skill; only this says a person read it.
+#
+# Two properties this module exists to hold, both enforced rather than documented:
+#
+# 1. APPROVAL IS BOUND TO A DIGEST, never to a name or a version. `load_approvals` returns
+#    `skill_id -> body_digest`, which `skillset.validate_skillset` re-checks at every activation.
+#    Editing an approved body does not merely invalidate a record filed away somewhere; it makes the
+#    whole skill set fail to activate.
+#
+# 2. EVERY ADVISORY MUST BE ACKNOWLEDGED INDIVIDUALLY. Not a count, not a blanket flag, not "I read
+#    them all" -- each finding by its own identifier. A single "yes" over a list is the interface
+#    equivalent of a checkbox nobody reads, and it is exactly the affordance that turns a review gate
+#    into a formality.
+#
+# Approval RE-RUNS the analysis from the candidate file rather than accepting a report from the
+# caller. A report passed in is a report that can be fabricated, and the one place that must not be
+# possible is the gate that grants trust.
+
+_APPROVALS_DIRNAME = "approvals"
+
+
+class ApprovalError(ValueError):
+    def __init__(self, code: str):
+        self.code = code
+        super().__init__(code)
+
+
+@dataclass(frozen=True)
+class ApprovalRecord:
+    """One approved skill. Deliberately records what was acknowledged, not a conclusion about it:
+    there is no `safe` here either, for the same reason `AnalysisReport` has none."""
+
+    skill_id: str
+    body_digest: str
+    candidate_digest: str
+    acknowledged: tuple[str, ...]
+    approved_on: date
+
+    def as_json(self) -> dict[str, object]:
+        return {
+            "skill_id": self.skill_id, "body_digest": self.body_digest,
+            "candidate_digest": self.candidate_digest, "acknowledged": list(self.acknowledged),
+            "approved_on": self.approved_on.isoformat(),
+        }
+
+
+def approve_candidate(
+    candidate: Path, data_dir: Path, *, acknowledge: Iterable[str], today: date,
+) -> tuple[ApprovalRecord, ...]:
+    """Approve every skill in a candidate, binding each to its current body digest.
+
+    Re-runs static analysis from the file itself. Refuses unless every advisory it produces is
+    acknowledged by identifier, and refuses just as firmly if acknowledgments are offered for
+    findings that do not exist -- a stale acknowledgment list means the reviewer approved a
+    different candidate than the one in front of them, which is precisely the case where waving it
+    through is worst.
+
+    `today` is injected, never read from the clock, so an approval record is reproducible."""
+    try:
+        report = analyze_candidate(candidate)
+    except CandidateError as error:
+        raise ApprovalError(error.code) from error
+
+    required = {item.identifier for item in report.advisories}
+    offered = set(acknowledge)
+    if required - offered:
+        raise ApprovalError("unacknowledged_advisories")
+    if offered - required:
+        raise ApprovalError("unknown_acknowledgment")
+
+    records = tuple(
+        ApprovalRecord(
+            skill_id=skill_id,
+            body_digest=digest,
+            candidate_digest=report.digest,
+            acknowledged=tuple(sorted(identifier for identifier in required
+                                      if identifier.startswith(f"{skill_id}:"))),
+            approved_on=today,
+        )
+        for skill_id, digest in _body_digests(candidate).items()
+    )
+    directory = data_dir / "skills" / _APPROVALS_DIRNAME
+    directory.mkdir(parents=True, exist_ok=True)
+    for record in records:
+        _write_private(directory / f"{record.skill_id}.json", record)
+    return records
+
+
+def load_approvals(data_dir: Path) -> dict[str, str]:
+    """Return `skill_id -> body_digest` for `skillset.validate_skillset`.
+
+    An unreadable or malformed record is a hard failure, never a skipped entry. Silently dropping one
+    would turn a corrupted approval into an unapproved skill, and an unapproved skill fails
+    activation with a message about the wrong thing entirely."""
+    directory = data_dir / "skills" / _APPROVALS_DIRNAME
+    if not directory.is_dir():
+        return {}
+    approvals: dict[str, str] = {}
+    for path in sorted(directory.glob("*.json")):
+        record = read_approval(path)
+        approvals[record.skill_id] = record.body_digest
+    return approvals
+
+
+def read_approval(path: Path) -> ApprovalRecord:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return ApprovalRecord(
+            skill_id=data["skill_id"], body_digest=data["body_digest"],
+            candidate_digest=data["candidate_digest"],
+            acknowledged=tuple(data["acknowledged"]),
+            approved_on=date.fromisoformat(data["approved_on"]),
+        )
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        raise ApprovalError("malformed_approval") from error
+
+
+def revoke_approval(data_dir: Path, skill_id: str) -> bool:
+    """Withdraw an approval. Returns whether one existed. Revocation is a first-class operation: a
+    reviewer who changes their mind must not have to hand-delete a file to act on it."""
+    path = data_dir / "skills" / _APPROVALS_DIRNAME / f"{skill_id}.json"
+    if not path.is_file():
+        return False
+    path.unlink()
+    return True
+
+
+def _body_digests(candidate: Path) -> dict[str, str]:
+    from .candidates import _parse, _read_candidate  # local: internal reuse, not a public seam
+
+    pack = _parse(_read_candidate(candidate), candidate.suffix.lower())
+    return {skill.skill_id: skill.body_digest for skill in pack.skills}
+
+
+def _write_private(destination: Path, record: ApprovalRecord) -> None:
+    payload = (json.dumps(record.as_json(), indent=2, sort_keys=True) + "\n").encode("utf-8")
+    handle = tempfile.NamedTemporaryFile(
+        prefix=f".{destination.name}.", suffix=".tmp", dir=destination.parent, delete=False
+    )
+    temporary = Path(handle.name)
+    try:
+        handle.write(payload)
+        handle.flush()
+        os.fsync(handle.fileno())
+        handle.close()
+        os.chmod(temporary, 0o600)
+        os.replace(temporary, destination)
+    except BaseException:
+        handle.close()
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+__all__ = [
+    "ApprovalError",
+    "ApprovalRecord",
+    "approve_candidate",
+    "load_approvals",
+    "read_approval",
+    "revoke_approval",
+]

bruriah/audit.py

@@ -0,0 +1,93 @@
+# Slice 9B (unit 1 of 2): the content-free redacted audit trail for `research.py`. Append-only
+# JSON Lines; every record carries ONLY identifiers, a closed destination classification,
+# decisions, counts, and timings -- NEVER the task/query text, the destination path or query
+# string (either can encode a secret token or the caller's private task), response body, request
+# or response headers, or any secret. design.md "Network": "Audit records IDs, destination
+# class, decisions, counts and timings -- never query/body/secret content." Only the destination
+# HOST is recorded, never the full URL.
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+
+AuditDecision = Literal[
+    "disabled", "not_warranted", "cached", "fetched", "refused", "degraded", "error",
+]
+DestinationClass = Literal["public_https", "none"]
+_RECORD_FIELDS = (
+    "request_id", "destination_host", "destination_class", "decision", "code",
+    "bytes_transferred", "elapsed_ms", "timestamp",
+)
+
+
+@dataclass(frozen=True)
+class AuditRecord:
+    request_id: str
+    destination_host: str | None
+    destination_class: DestinationClass
+    decision: AuditDecision
+    code: str
+    bytes_transferred: int
+    elapsed_ms: int
+    timestamp: datetime
+
+
+def _encode(record: AuditRecord) -> str:
+    return json.dumps(
+        {
+            "request_id": record.request_id,
+            "destination_host": record.destination_host,
+            "destination_class": record.destination_class,
+            "decision": record.decision,
+            "code": record.code,
+            "bytes_transferred": record.bytes_transferred,
+            "elapsed_ms": record.elapsed_ms,
+            "timestamp": record.timestamp.isoformat(),
+        },
+        sort_keys=True,
+    )
+
+
+def append_audit(audit_path: Path, record: AuditRecord) -> None:
+    """Append one redacted line; never truncates or reorders prior entries -- an audit trail, not
+    a cache. The directory/file are private (0700/0600) on POSIX after every write."""
+    audit_path.parent.mkdir(parents=True, exist_ok=True)
+    with audit_path.open("a", encoding="utf-8") as handle:
+        handle.write(_encode(record) + "\n")
+    if os.name == "posix":
+        os.chmod(audit_path.parent, 0o700)
+        os.chmod(audit_path, 0o600)
+
+
+def read_audit_records(audit_path: Path) -> list[AuditRecord]:
+    """Diagnostic/test helper: parse every line back into an `AuditRecord`. Not used by
+    `research.py` itself -- production audit access is append-only, write-side only."""
+    if not audit_path.is_file():
+        return []
+    records: list[AuditRecord] = []
+    for line in audit_path.read_text(encoding="utf-8").splitlines():
+        if not line:
+            continue
+        payload = json.loads(line)
+        if not isinstance(payload, dict) or set(payload) != set(_RECORD_FIELDS):
+            raise ValueError("corrupt_audit_record")
+        records.append(
+            AuditRecord(
+                request_id=payload["request_id"],
+                destination_host=payload["destination_host"],
+                destination_class=payload["destination_class"],
+                decision=payload["decision"],
+                code=payload["code"],
+                bytes_transferred=payload["bytes_transferred"],
+                elapsed_ms=payload["elapsed_ms"],
+                timestamp=datetime.fromisoformat(payload["timestamp"]),
+            )
+        )
+    return records
+
+
+__all__ = ["AuditDecision", "AuditRecord", "DestinationClass", "append_audit", "read_audit_records"]

bruriah/cache.py

@@ -0,0 +1,320 @@
+# Slice 9B (unit 1 of 2): the private atomic evidence cache. Stores ONLY the permitted minimum
+# for captured live evidence -- design.md "Network": "Atomic private cache stores permitted
+# minimum excerpts plus digest, redirect chain, policy/pack versions, license and TTL; prohibited
+# bodies are discarded." and the lifecycle spec's "External Evidence and Cache Lifecycle" /
+# "Cache expiry or prohibited reuse": prohibited/unknown reuse MUST store only permitted
+# metadata, citation, and minimum necessary excerpt; expired content MUST NOT be presented as
+# current.
+#
+# `evidence: EvidenceRecord` is stored WHOLE -- it is already "permitted metadata" by contract
+# (digest, locator, citation_locator, redirect_chain, license/reuse state, pack_version -- no
+# body-text field exists on it at all), so persisting it fully is safe regardless of reuse state.
+# `excerpt` is the ONLY body-derived text ever written to disk; `excerpt_only=True` (the default
+# for every live fetch in this change, since `fetch.py` has no pack context and always reports
+# license=reuse="unknown") means `excerpt` is a small, bounded citation excerpt, never the full
+# body. `policy_version` records the research-policy pack version this cache decision was made
+# under -- distinct from `evidence.pack_version`, which belongs to the evidence's own source pack.
+#
+# Cache key: sha256 of the CANONICAL request URL (deterministic and content-addressed -- never a
+# random/UUID/timestamp name, matching the rest of the codebase's "no Date.now/random for
+# identity" convention). Write path: write-temp-then-rename (`os.replace`, atomic on the same
+# filesystem) with 0600 permissions applied BEFORE the rename makes the file visible under its
+# final name, so no reader can ever observe a partially-written or over-permissioned file.
+# `now` is injectable everywhere TTL is evaluated, so expiry is deterministic under test, never a
+# wall-clock race.
+#
+# Slice 12D: deletion controls (closes 9B WARNING 2 -- "no cache deletion/retention"; the
+# lifecycle spec's "External Evidence and Cache Lifecycle" requires the cache be "governed by TTL
+# and deletion controls", not just TTL staleness detection). Two pieces, both typed-total and both
+# free of wall-clock reads:
+#   - `prune_expired` is the explicit deletion control: it removes an entry once it has genuinely
+#     expired (`now > expires_at`, the same condition `read_cache` already treats as a miss) OR
+#     its `expires_at` exceeds what any legitimate write under the given `ttl` could have produced
+#     (`expires_at - now > ttl`) -- a tamper/corruption ceiling, since a freshly built live entry
+#     can never claim more than `ttl` of remaining life. Corrupt/unreadable entries are always
+#     removed (nothing about them is auditable or bound-checkable). `doctor` (cli.py) never calls
+#     this -- it only calls the read-only `cache_stats` below, preserving "doctor is read-only".
+#   - `write_cache_atomic` self-bounds by sweeping for already-expired entries once after every
+#     successful write, deriving `now` ENTIRELY from the entry just written
+#     (`entry.evidence.retrieved_at` stands in for "now"). This needs zero new parameters and zero
+#     wall-clock, so the frozen `research.py` callsite (`write_cache_atomic(deps.cache_dir,
+#     canonical, entry)`) gets self-bounding for free. Only the plain-expiry direction
+#     (`retrieved_at > other.expires_at`) is used here -- NOT the tamper ceiling -- because
+#     `retrieved_at` is always a real PAST timestamp of one fetch among possibly concurrent or
+#     out-of-order writes; wall-clock time only advances, so if this write's own retrieved_at
+#     already exceeds another entry's `expires_at`, the true current time exceeds it too, and the
+#     removal can never be a false positive. The ceiling check requires an authoritative, operator-
+#     supplied `now`/`ttl` pair (an out-of-order write's own `ttl` says nothing about whether
+#     ANOTHER entry's expiry is plausible), so it is reserved for the explicit `prune_expired` call
+#     below. If `retrieved_at` is absent (the field is optional on `EvidenceRecord`) or not
+#     comparable, self-pruning is skipped for that write -- best-effort, never a hard failure of
+#     the write itself.
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Literal
+
+from pydantic import ValidationError
+
+from .contracts import EvidenceRecord
+
+ReuseState = Literal["permitted", "restricted", "prohibited", "unknown"]
+_ENTRY_FIELDS = frozenset({"evidence", "expires_at", "excerpt", "excerpt_only", "policy_version"})
+
+
+class CacheError(ValueError):
+    def __init__(self, code: str):
+        self.code = code
+        super().__init__(code)
+
+
+@dataclass(frozen=True)
+class CacheEntry:
+    """One cached research result. See module docstring for the excerpt-only/reuse contract."""
+
+    evidence: EvidenceRecord
+    expires_at: datetime
+    excerpt: str
+    excerpt_only: bool
+    policy_version: str
+
+
+@dataclass(frozen=True)
+class CacheLookup:
+    hit: bool
+    expired: bool
+    entry: CacheEntry | None
+
+
+@dataclass(frozen=True)
+class PruneSummary:
+    """Result of one `prune_expired` sweep. `corrupt` is a subset of `removed` (every corrupt
+    entry found is also deleted); `bytes_reclaimed` counts freed disk space across all removals."""
+
+    scanned: int
+    removed: int
+    corrupt: int
+    bytes_reclaimed: int
+
+
+@dataclass(frozen=True)
+class CacheStats:
+    """Read-only visibility for `doctor` -- see `cache_stats`. Never deletes anything."""
+
+    entries: int
+    expired: int
+    total_bytes: int
+
+
+def cache_key(canonical_url: str) -> str:
+    """Deterministic, content-addressed cache filename stem -- the SAME canonical URL always
+    yields the SAME key, so a repeated request for the original URL hits cache even if the
+    fetched content ultimately resolved through redirects to a different final locator."""
+    return hashlib.sha256(canonical_url.encode("utf-8")).hexdigest()
+
+
+def _cache_path(cache_dir: Path, canonical_url: str) -> Path:
+    return cache_dir / f"{cache_key(canonical_url)}.json"
+
+
+def _encode(entry: CacheEntry) -> str:
+    payload = {
+        "evidence": json.loads(entry.evidence.model_dump_json()),
+        "expires_at": entry.expires_at.isoformat(),
+        "excerpt": entry.excerpt,
+        "excerpt_only": entry.excerpt_only,
+        "policy_version": entry.policy_version,
+    }
+    return json.dumps(payload, sort_keys=True)
+
+
+def _decode(raw: str) -> CacheEntry:
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise CacheError("corrupt_cache_entry") from error
+    if not isinstance(payload, dict) or set(payload) != _ENTRY_FIELDS:
+        raise CacheError("corrupt_cache_entry")
+    try:
+        # `model_validate` (Python-object mode) rejects an ISO datetime STRING under this
+        # project's `strict=True` `ClosedModel` config; re-serializing the nested dict and using
+        # `model_validate_json` (JSON mode, where a datetime is necessarily a string) is the same
+        # pattern `packs.py` uses for its own nested pydantic parsing.
+        evidence = EvidenceRecord.model_validate_json(json.dumps(payload["evidence"]))
+        return CacheEntry(
+            evidence=evidence,
+            expires_at=datetime.fromisoformat(payload["expires_at"]),
+            excerpt=payload["excerpt"],
+            excerpt_only=payload["excerpt_only"],
+            policy_version=payload["policy_version"],
+        )
+    except (KeyError, TypeError, ValueError, ValidationError) as error:
+        raise CacheError("corrupt_cache_entry") from error
+
+
+def write_cache_atomic(cache_dir: Path, canonical_url: str, entry: CacheEntry) -> Path:
+    """Write-temp-then-rename: a temp file created in the SAME directory (so `os.replace` is an
+    atomic rename on one filesystem, never a cross-device copy) is written, chmod'd 0600, then
+    atomically renamed onto the final content-addressed path. A reader can only ever observe the
+    prior complete entry or the new complete entry -- never a partial write. After the write lands,
+    an opportunistic self-prune sweep runs (see `_self_prune_after_write`) so the cache is
+    self-bounding without any new parameter or wall-clock read."""
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    if os.name == "posix":
+        os.chmod(cache_dir, 0o700)
+    final_path = _cache_path(cache_dir, canonical_url)
+    fd, tmp_name = tempfile.mkstemp(dir=cache_dir, prefix=".tmp-cache-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(_encode(entry))
+        os.chmod(tmp_name, 0o600)
+        os.replace(tmp_name, final_path)
+    except BaseException:
+        Path(tmp_name).unlink(missing_ok=True)
+        raise
+    _self_prune_after_write(cache_dir, entry)
+    return final_path
+
+
+def _unlink_quietly(path: Path) -> bool:
+    """Delete-if-possible, never raise: a concurrent deletion or transient OS error during a
+    best-effort sweep must not abort the sweep or, for `prune_expired`, escape untyped."""
+    try:
+        path.unlink()
+        return True
+    except OSError:
+        return False
+
+
+def _sweep_prunable(cache_dir: Path, is_prunable: Callable[[CacheEntry], bool]) -> PruneSummary:
+    """Shared typed-total core for both deletion paths: scan every `*.json` entry once, always
+    remove a corrupt/unreadable one, and remove a decodable one iff `is_prunable(entry)`. No
+    exception escapes a single bad or racing file."""
+    if not cache_dir.is_dir():
+        return PruneSummary(scanned=0, removed=0, corrupt=0, bytes_reclaimed=0)
+    scanned = removed = corrupt = bytes_reclaimed = 0
+    for path in sorted(cache_dir.glob("*.json")):
+        scanned += 1
+        try:
+            size = path.stat().st_size
+        except OSError:
+            continue
+        try:
+            entry = _decode(path.read_text(encoding="utf-8"))
+        except (CacheError, OSError):
+            corrupt += 1
+            if _unlink_quietly(path):
+                removed += 1
+                bytes_reclaimed += size
+            continue
+        if is_prunable(entry):
+            if _unlink_quietly(path):
+                removed += 1
+                bytes_reclaimed += size
+    return PruneSummary(scanned=scanned, removed=removed, corrupt=corrupt, bytes_reclaimed=bytes_reclaimed)
+
+
+def _self_prune_after_write(cache_dir: Path, entry: CacheEntry) -> PruneSummary | None:
+    """See module docstring "Slice 12D" for the monotonic-safety rationale. Returns `None` (skips
+    pruning for this write) when the entry carries no usable timestamp; this is a best-effort
+    maintenance step, never a reason to fail the write that just succeeded."""
+    retrieved_at = entry.evidence.retrieved_at
+    if retrieved_at is None:
+        return None
+    try:
+        return _sweep_prunable(cache_dir, lambda other: retrieved_at > other.expires_at)
+    except TypeError:
+        return None
+
+
+def prune_expired(cache_dir: Path, *, now: datetime, ttl: timedelta) -> PruneSummary:
+    """Explicit deletion control -- see module docstring "Slice 12D". An entry is removed once it
+    has genuinely expired (`now > expires_at`, the same condition `read_cache` already treats as a
+    miss) or its `expires_at` is implausibly far in the future for the given `ttl`
+    (`expires_at - now > ttl`, a tamper/corruption ceiling that a legitimately built live entry can
+    never trip, since `build_cache_entry` never grants more than `ttl` of remaining life). Corrupt
+    or unreadable entries are always removed. Typed-total throughout."""
+    return _sweep_prunable(cache_dir, lambda entry: now > entry.expires_at or entry.expires_at - now > ttl)
+
+
+def cache_stats(cache_dir: Path, *, now: datetime) -> CacheStats:
+    """Read-only visibility for `doctor` (design.md: "`doctor` is read-only"). Scans without ever
+    deleting, decoding into pruning decisions, or otherwise modifying a file -- `doctor` MUST NOT
+    delete anything; a separate explicit action would be required to expose `prune_expired` via the
+    CLI, and none is added here. A corrupt entry still occupies disk space, so it is counted in
+    `entries`/`total_bytes` even though it can never be validated as expired or live."""
+    if not cache_dir.is_dir():
+        return CacheStats(entries=0, expired=0, total_bytes=0)
+    entries = expired = total_bytes = 0
+    for path in sorted(cache_dir.glob("*.json")):
+        try:
+            size = path.stat().st_size
+        except OSError:
+            continue
+        entries += 1
+        total_bytes += size
+        try:
+            entry = _decode(path.read_text(encoding="utf-8"))
+        except CacheError:
+            continue
+        if now > entry.expires_at:
+            expired += 1
+    return CacheStats(entries=entries, expired=expired, total_bytes=total_bytes)
+
+
+def read_cache(cache_dir: Path, canonical_url: str, *, now: datetime) -> CacheLookup:
+    """Read the cache entry for `canonical_url`. A missing file, a corrupt file, and an expired
+    entry are ALL a miss for serving purposes (`hit=False`) -- expired content is never returned
+    as current. `expired=True` distinguishes "was cached but is stale" from "never cached" for
+    diagnostics without ever handing the caller stale content."""
+    path = _cache_path(cache_dir, canonical_url)
+    if not path.is_file():
+        return CacheLookup(hit=False, expired=False, entry=None)
+    try:
+        entry = _decode(path.read_text(encoding="utf-8"))
+    except CacheError:
+        return CacheLookup(hit=False, expired=False, entry=None)
+    if now > entry.expires_at:
+        return CacheLookup(hit=False, expired=True, entry=None)
+    return CacheLookup(hit=True, expired=False, entry=entry)
+
+
+def build_cache_entry(
+    evidence: EvidenceRecord,
+    *,
+    retrieved_at: datetime,
+    ttl: timedelta,
+    body: bytes,
+    max_excerpt_chars: int,
+    policy_version: str,
+) -> CacheEntry:
+    """Build the entry that will actually be persisted. Only `evidence.reuse == "permitted"` may
+    store a body-derived excerpt up to `max_excerpt_chars`; every other state (`restricted`,
+    `prohibited`, or `unknown` -- the DEFAULT, since `fetch.py` has no pack context and always
+    reports `license=reuse="unknown"`) is capped to a small, bounded citation excerpt only, never
+    treated as complete content -- "Cache expiry or prohibited reuse": "retained material is
+    limited to permitted fields."""
+    text = body.decode("utf-8", errors="replace")
+    excerpt_only = evidence.reuse != "permitted"
+    limit = min(max_excerpt_chars, 280) if excerpt_only else max_excerpt_chars
+    return CacheEntry(
+        evidence=evidence,
+        expires_at=retrieved_at + ttl,
+        excerpt=text[:limit],
+        excerpt_only=excerpt_only,
+        policy_version=policy_version,
+    )
+
+
+__all__ = [
+    "CacheEntry", "CacheError", "CacheLookup", "CacheStats", "PruneSummary", "ReuseState",
+    "build_cache_entry", "cache_key", "cache_stats", "prune_expired", "read_cache",
+    "write_cache_atomic",
+]