adopt-coverage 0.4.0__py3-none-any.whl

adopt_coverage/__init__.py

@@ -0,0 +1,51 @@
+"""`recompute_coverage` and the cache-disagreement alarm.
+
+Implemented in S4. Contracts §6, implementation spec §4.8.
+
+**The invariants this package carries.** It is the only writer of
+`covered_cache` and `covered_cache_at` -- enforced by the `no-covered-cache-write`
+import contract, not by convention. The recompute result is the authority and the
+cache is rebuilt from it, never the reverse. A disagreement alarms and is never
+silently reconciled, because a quietly self-healing cache reintroduces exactly
+the invisible coverage decay the rebuild exists to delete.
+
+**Computing and writing are two calls on purpose.** `recompute_coverage` reads
+and decides; `rebuild_cache` writes. `store doctor` calls the first and not the
+second, which is what lets it report a disagreement without destroying the
+evidence of who caused it.
+"""
+
+from adopt_coverage.cache import CacheWriter, rebuild_cache
+from adopt_coverage.recompute import (
+    COVERAGE_REASONS,
+    REASON_AUDIENCE_OR_ENVIRONMENT,
+    REASON_IDENTITY_NOT_ACTIVE,
+    REASON_NO_ACTIVE_KNOWLEDGE_REVISION,
+    REASON_NO_LIVE_BINDING,
+    REASON_NO_OBSERVABILITY_BOUNDARY,
+    REASON_VERIFICATION_CONFLICTED,
+    REASON_VERIFICATION_UNVERIFIED,
+    CoverageResult,
+    Disagreement,
+    IdentityCoverage,
+    recompute_coverage,
+)
+from adopt_coverage.records import CoverageRecords
+
+__all__ = [
+    "COVERAGE_REASONS",
+    "REASON_AUDIENCE_OR_ENVIRONMENT",
+    "REASON_IDENTITY_NOT_ACTIVE",
+    "REASON_NO_ACTIVE_KNOWLEDGE_REVISION",
+    "REASON_NO_LIVE_BINDING",
+    "REASON_NO_OBSERVABILITY_BOUNDARY",
+    "REASON_VERIFICATION_CONFLICTED",
+    "REASON_VERIFICATION_UNVERIFIED",
+    "CacheWriter",
+    "CoverageRecords",
+    "CoverageResult",
+    "Disagreement",
+    "IdentityCoverage",
+    "rebuild_cache",
+    "recompute_coverage",
+]

adopt_coverage/cache.py

@@ -0,0 +1,85 @@
+"""The coverage cache write. **The only one in either repository.**
+
+`no-covered-cache-write` scans every `.py` string literal and every `.sql` line
+under `packages/`, `scripts/`, `tools/`, `bench/` and `schema/` for the cache
+columns named alongside a write keyword, and `packages/adopt-coverage` is the
+only source path it permits. That is why the statement is here and not beside the
+other `identity` writes in `adopt_store.sqlite.records`, where it would be
+rejected by the gate -- correctly, because a setter reachable from the store is a
+setter every caller can reach.
+
+**Why this module holds SQL when nothing else in the package does.** The
+alternatives were each worse and are recorded so they are not re-proposed:
+
+* a generic ``update_identity_columns(id, mapping)`` on the store passes the
+  regex while opening a *wider* hole than the specific setter it replaces --
+  every column becomes writable by every caller, which is dodging the gate
+  rather than satisfying it (CR-24: a gate people work around stops meaning
+  anything);
+* splitting the statement so the column and the keyword land on different lines
+  is the same dodge, less visible;
+* adding ``adopt_store.sqlite`` to the contract's ``allowed_paths`` makes the
+  write reachable by anyone holding a store, which is the invariant itself.
+
+The executor is a **structural** protocol, so this package imports no store
+module and no chain reaches `sqlite3` -- `no-raw-sqlite` names `adopt_coverage`
+as a source module and would otherwise reject it.
+
+**Known cost, stated rather than discovered later.** One SQL statement lives in a
+package that is otherwise dialect-free, and the parameter marker differs under
+psycopg. No sprint assigns the Postgres realization of coverage; whichever one
+does inherits this seam and this note.
+"""
+
+from collections.abc import Sequence
+from contextlib import AbstractContextManager
+from typing import Final, Protocol
+
+from adopt_coverage.recompute import CoverageResult
+from adopt_obs import format_timestamp
+
+__all__ = ["CacheWriter", "rebuild_cache"]
+
+#: The statement, in one place. Parameter order is (covered, at, identity_id).
+_WRITE_CACHE: Final[str] = (
+    "UPDATE identity SET covered_cache = ?, covered_cache_at = ? WHERE id = ?"
+)
+
+
+class CacheWriter(Protocol):
+    """The two operations rebuilding the cache needs, and nothing else.
+
+    Satisfied structurally by `adopt_store.sqlite.store.SqliteStore`. Deliberately
+    **not** an import of that class: this package may not reach `sqlite3` even
+    transitively, and a protocol this narrow cannot be used to write anything the
+    caller did not already have the statement for.
+    """
+
+    def transaction(self) -> AbstractContextManager[None]: ...
+    def execute(self, sql: str, parameters: tuple[object, ...] = ()) -> None: ...
+
+
+def rebuild_cache(writer: CacheWriter, result: CoverageResult) -> int:
+    """Rebuild `covered_cache` from a recompute result. **Never the reverse.**
+
+    The direction is the whole contract (PRD F7.4, CUJ-3 step 4). This function
+    takes a `CoverageResult` and no store-read of its own precisely so that there
+    is no expression here in which the cache could influence the value written.
+
+    Args:
+        writer: The store to write through.
+        result: What `recompute_coverage` decided.
+
+    Returns:
+        How many rows were written -- every identity in scope, not only the
+        disagreeing ones. A cache rebuilt only where it disagreed would leave
+        `covered_cache_at` lying about when the rest was last confirmed.
+    """
+    stamp = format_timestamp(result.computed_at)
+    rows: Sequence[tuple[object, ...]] = [
+        (int(entry.covered), stamp, entry.identity_id) for entry in result.identities
+    ]
+    with writer.transaction():
+        for parameters in rows:
+            writer.execute(_WRITE_CACHE, parameters)
+    return len(rows)

adopt_coverage/recompute.py

@@ -0,0 +1,408 @@
+"""`recompute_coverage` -- the authority, and the cache-disagreement alarm.
+
+**Breaking change 3 of 3, second half.** In the withdrawn `0.1.x` line
+`identity_registry.covered` *was* truth, recomputed by whichever writer happened
+to touch it. Here the function is truth and `identity.covered_cache` is a cache,
+and the difference is the whole point: a cache that disagrees is a defect signal,
+never a value to be quietly corrected.
+
+**This module computes and never writes.** The write lives in
+`adopt_coverage.cache`, one call away, so that `store doctor` can ask for the
+comparison without the act of looking changing what is there. Implementation spec
+§8's incident card is explicit -- rebuilding the cache first destroys the
+evidence, and the writer that caused the drift is then unfindable.
+
+**The six inputs are evaluated here, not in SQL.** The port hands back rows; each
+predicate below is one input from contracts §6, named, so the property test that
+compares this function against an independent reference implementation is
+comparing two derivations rather than two callers of one clever query.
+"""
+
+import datetime as _dt
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Final
+
+from adopt_const import COVERAGE_ALARM_SAMPLE_MAX
+from adopt_coverage.records import CoverageRecords
+from adopt_model import Binding, Identity, KnowledgeItem, ObservabilityBoundary
+from adopt_obs import Clock, ErrorCode, SystemClock, get_logger, truncate_to_millisecond
+
+__all__ = [
+    "COVERAGE_REASONS",
+    "REASON_AUDIENCE_OR_ENVIRONMENT",
+    "REASON_IDENTITY_NOT_ACTIVE",
+    "REASON_NO_ACTIVE_KNOWLEDGE_REVISION",
+    "REASON_NO_LIVE_BINDING",
+    "REASON_NO_OBSERVABILITY_BOUNDARY",
+    "REASON_VERIFICATION_CONFLICTED",
+    "REASON_VERIFICATION_UNVERIFIED",
+    "CoverageResult",
+    "Disagreement",
+    "IdentityCoverage",
+    "recompute_coverage",
+]
+
+_LOGGER: Final = get_logger("adopt.coverage")
+
+# --------------------------------------------------------------------------
+# The six inputs of contracts §6, one reason each.
+#
+# A reason names why an identity is **not** covered. They are stable strings
+# because they reach the CLI envelope and a `store doctor` finding, and an
+# operator branching on "which of the six is missing" is the whole reason the
+# result is not a bare boolean.
+# --------------------------------------------------------------------------
+
+#: Input 1 -- "an active `identity_revision`".
+REASON_IDENTITY_NOT_ACTIVE: Final[str] = "identity_revision_not_active"
+
+#: Input 2 -- "at least one non-retired `binding`".
+REASON_NO_LIVE_BINDING: Final[str] = "no_live_binding"
+
+#: Input 3 -- "an active `knowledge_revision` on the bound item".
+REASON_NO_ACTIVE_KNOWLEDGE_REVISION: Final[str] = "no_active_knowledge_revision"
+
+#: Input 4 -- "applicable audience and environment".
+REASON_AUDIENCE_OR_ENVIRONMENT: Final[str] = "audience_or_environment_inapplicable"
+
+#: Input 5 -- "the `observability_boundary` for the scope".
+REASON_NO_OBSERVABILITY_BOUNDARY: Final[str] = "no_observability_boundary"
+
+#: Input 6 -- "verification requirements". A `conflicted` verification is Bet 4
+#: working as designed: intent and reality disagree, the disagreement is
+#: representable, and the identity is **not** reported as covered while it
+#: stands.
+REASON_VERIFICATION_CONFLICTED: Final[str] = "verification_conflicted"
+
+#: Input 6, second half -- **only `verified` knowledge counts** (v6.1 §6 Build 2,
+#: F6; plan decision D5).
+#:
+#: This tightens what Build 0 shipped, and the reason the original rule was
+#: written the other way is worth keeping: until Build 2 nothing could *make* an
+#: item verified, so requiring it would have made coverage unreachable by
+#: construction. Build 2 supplies both doors -- `adopt ingest` writes a
+#: human-authored document as `verified`, and confirming in `adopt review`
+#: promotes a mined candidate -- so the objection no longer holds, and the rule
+#: v6.1 actually requires can be enforced.
+#:
+#: What it buys is the honesty invariant: an unverified harvest candidate bound
+#: to an identity must not make `adopt gaps` stop asking for that identity's
+#: knowledge. A machine's unreviewed guess is not coverage, and counting it as
+#: coverage is how a gap report becomes a report about itself.
+REASON_VERIFICATION_UNVERIFIED: Final[str] = "verification_unverified"
+
+#: Every reason, in evaluation order. Exported so a caller can enumerate them
+#: without re-deriving the list and getting one fewer.
+COVERAGE_REASONS: Final[tuple[str, ...]] = (
+    REASON_IDENTITY_NOT_ACTIVE,
+    REASON_NO_LIVE_BINDING,
+    REASON_NO_ACTIVE_KNOWLEDGE_REVISION,
+    REASON_AUDIENCE_OR_ENVIRONMENT,
+    REASON_NO_OBSERVABILITY_BOUNDARY,
+    REASON_VERIFICATION_CONFLICTED,
+    REASON_VERIFICATION_UNVERIFIED,
+)
+
+#: The `identity_status` that counts as live. `moved` and `dead` do not: a moved
+#: identity's coverage belongs to the identity it aliases, and a dead one covers
+#: nothing.
+_ACTIVE_IDENTITY_STATUS: Final[str] = "active"
+
+#: The terminal `binding_status`. `active` and `moved` are both live -- a moved
+#: binding still ties the item to the referent, which is what CUJ-2 turns on.
+_RETIRED_BINDING_STATUS: Final[str] = "retired"
+
+#: The terminal `freshness_state` on a knowledge item. Knowledge carries its
+#: terminal state on the parent rather than on the revision (contracts §5
+#: obligation 4), so this is where "the revision is not active" is read.
+_RETIRED_ITEM_FRESHNESS: Final[str] = "retired"
+
+#: The `verification` that blocks coverage as a contradiction.
+_CONFLICTED_VERIFICATION: Final[str] = "conflicted"
+
+#: The only `verification` that carries coverage. A `NULL` verification blocks
+#: exactly as `unverified` does: a revision that never stated its verification
+#: has not been verified, and treating the absence as permission would let any
+#: writer that omitted the field manufacture coverage.
+_VERIFIED_VERIFICATION: Final[str] = "verified"
+
+
+@dataclass(frozen=True, slots=True)
+class IdentityCoverage:
+    """One identity's verdict, and why."""
+
+    identity_id: str
+    uri: str
+    covered: bool
+    #: Empty when covered. Sorted and deduplicated, so two runs over one store
+    #: produce one answer.
+    reasons: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class Disagreement:
+    """The cache said one thing and the recompute says another.
+
+    Alarm-grade on its own. Carries both values because "the cache is wrong" is
+    not actionable and "the cache says covered, the recompute says not" is.
+    """
+
+    identity_id: str
+    uri: str
+    cached: bool
+    recomputed: bool
+
+
+@dataclass(frozen=True, slots=True)
+class CoverageResult:
+    """What `recompute_coverage` returns.
+
+    Nothing here is a cache and nothing here has been written anywhere. The
+    caller decides whether to rebuild the cache from it (`adopt_coverage.cache`)
+    or merely to look (`store doctor`).
+    """
+
+    system_id: str
+    environment_id: str | None
+    identities: tuple[IdentityCoverage, ...]
+    disagreements: tuple[Disagreement, ...]
+    computed_at: _dt.datetime
+
+    @property
+    def covered(self) -> int:
+        return sum(1 for entry in self.identities if entry.covered)
+
+    @property
+    def uncovered(self) -> int:
+        return sum(1 for entry in self.identities if not entry.covered)
+
+    def verdict(self, identity_id: str) -> bool | None:
+        """The verdict for one identity, or `None` when it is out of scope."""
+        for entry in self.identities:
+            if entry.identity_id == identity_id:
+                return entry.covered
+        return None
+
+
+def _boundary_applies(boundary: ObservabilityBoundary, environment_id: str) -> bool:
+    """Whether a boundary row governs an identity in `environment_id`.
+
+    A boundary with no environment is the system-wide declaration and governs
+    every environment; one naming an environment governs only that one.
+    """
+    return boundary.environment_id is None or boundary.environment_id == environment_id
+
+
+def _environment_applies(item: KnowledgeItem, environment_id: str) -> bool:
+    """Whether an item's environment is applicable to an identity's.
+
+    `knowledge_item.environment_id` is nullable *because an item may span
+    environments* -- so null is "applies everywhere", not "applies nowhere".
+    Reading it the other way would make every cross-environment item silently
+    stop covering anything.
+    """
+    return item.environment_id is None or item.environment_id == environment_id
+
+
+def _binding_blockers(
+    binding: Binding,
+    *,
+    binding_status: str | None,
+    item: KnowledgeItem | None,
+    verification: str | None,
+    has_verification_row: bool,
+    audience_count: int,
+    environment_id: str,
+) -> frozenset[str]:
+    """Inputs 2, 3, 4 and 6, for one candidate binding.
+
+    Returns the reasons this binding fails to carry coverage. Empty means it
+    carries it, and one such binding is enough -- contracts §6 asks for "at least
+    one non-retired binding", not for all of them.
+    """
+    blockers: set[str] = set()
+
+    # Input 2 -- a binding whose head revision is retired is not live. A binding
+    # with no head revision at all is also not live: nothing has ever asserted
+    # the relationship.
+    if binding_status is None or binding_status == _RETIRED_BINDING_STATUS:
+        blockers.add(REASON_NO_LIVE_BINDING)
+
+    # Input 3 -- an active knowledge revision on the bound item.
+    if (
+        item is None
+        or item.current_revision_id is None
+        or item.freshness_state == _RETIRED_ITEM_FRESHNESS
+    ):
+        blockers.add(REASON_NO_ACTIVE_KNOWLEDGE_REVISION)
+        # Inputs 4 and 6 are statements about that item. With no item there is
+        # nothing to say about them, and inventing a second reason would report
+        # one defect as three.
+        return frozenset(blockers)
+
+    # Input 4 -- applicable audience and environment.
+    if audience_count == 0 or not _environment_applies(item, environment_id):
+        blockers.add(REASON_AUDIENCE_OR_ENVIRONMENT)
+
+    # Input 6 -- verification requirements. Two distinct failures, reported
+    # separately because they send an operator to different places: a conflict
+    # needs adjudicating, an unverified item needs reviewing.
+    if has_verification_row and verification == _CONFLICTED_VERIFICATION:
+        blockers.add(REASON_VERIFICATION_CONFLICTED)
+    elif verification != _VERIFIED_VERIFICATION:
+        blockers.add(REASON_VERIFICATION_UNVERIFIED)
+
+    return frozenset(blockers)
+
+
+def _evaluate(
+    identity: Identity,
+    *,
+    identity_status: str | None,
+    bindings: Sequence[Binding],
+    binding_statuses: Mapping[str, str],
+    items: Mapping[str, KnowledgeItem],
+    verifications: Mapping[str, str | None],
+    audience_counts: Mapping[str, int],
+    boundaries: Sequence[ObservabilityBoundary],
+) -> IdentityCoverage:
+    """All six inputs for one identity."""
+    blockers: set[str] = set()
+
+    # Input 1 -- an active identity revision. An identity with no revision has
+    # never been asserted to exist by anything.
+    if identity_status != _ACTIVE_IDENTITY_STATUS:
+        blockers.add(REASON_IDENTITY_NOT_ACTIVE)
+
+    # Input 5 -- the observability boundary for the scope. Without one, nothing
+    # has declared what may be observed here, and coverage would be a claim
+    # about a system nobody agreed to look at.
+    if not any(_boundary_applies(row, identity.environment_id) for row in boundaries):
+        blockers.add(REASON_NO_OBSERVABILITY_BOUNDARY)
+
+    # Inputs 2, 3, 4 and 6, per candidate binding.
+    if not bindings:
+        blockers.add(REASON_NO_LIVE_BINDING)
+    else:
+        per_binding = [
+            _binding_blockers(
+                binding,
+                binding_status=binding_statuses.get(binding.id),
+                item=items.get(binding.item_id),
+                verification=verifications.get(binding.item_id),
+                has_verification_row=binding.item_id in verifications,
+                audience_count=audience_counts.get(binding.item_id, 0),
+                environment_id=identity.environment_id,
+            )
+            for binding in bindings
+        ]
+        if all(reasons for reasons in per_binding):
+            # Every candidate failed. Report every distinct reason rather than
+            # the first: an operator fixing one binding's audience should not
+            # then discover the next binding was retired all along.
+            blockers.update(*per_binding)
+
+    return IdentityCoverage(
+        identity_id=identity.id,
+        uri=identity.uri,
+        covered=not blockers,
+        reasons=tuple(sorted(blockers)),
+    )
+
+
+def recompute_coverage(
+    records: CoverageRecords,
+    system_id: str,
+    environment_id: str | None = None,
+    *,
+    clock: Clock | None = None,
+) -> CoverageResult:
+    """Evaluate coverage for every identity in scope. **The authority.**
+
+    Args:
+        records: The read port. Supplied rather than reached for, because a
+            module-level store would make this function untestable against the
+            random graphs its correctness property needs.
+        system_id: The system whose identities are evaluated.
+        environment_id: One environment, or `None` for every environment of the
+            system.
+        clock: Injected clock; tests pass `ManualClock`.
+
+    Returns:
+        Per-identity coverage plus a `disagreements` list against
+        `covered_cache`. **Nothing is written.**
+
+    Emits:
+        `coverage_cache_disagreement` at `LogLevel.ALARM` when the disagreement
+        list is non-empty -- a defect signal that must page, not merely be
+        recorded (PRD F7.3). The **count is always complete**; the ids are a
+        sample bounded by `COVERAGE_ALARM_SAMPLE_MAX`, because a cold cache over
+        a 50k-identity store disagrees on every row and an uncapped field would
+        put a megabyte of ULIDs on one line. `store doctor` enumerates every
+        affected identity, so the alarm says *how bad* and the doctor says
+        *which*. Identity **ids** travel, never URIs: an id is minted by us and
+        carries no client-derived text.
+    """
+    now = truncate_to_millisecond((clock if clock is not None else SystemClock()).now())
+
+    identities = records.identities_in_scope(system_id=system_id, environment_id=environment_id)
+    identity_statuses = records.head_identity_statuses(
+        system_id=system_id, environment_id=environment_id
+    )
+    binding_statuses = records.head_binding_statuses(
+        system_id=system_id, environment_id=environment_id
+    )
+    items = {row.id: row for row in records.items_in_scope(system_id=system_id)}
+    verifications = records.head_item_verifications(system_id=system_id)
+    audience_counts = records.audience_counts(system_id=system_id)
+    boundaries = records.boundaries_for_system(system_id=system_id)
+
+    bindings_by_identity: dict[str, list[Binding]] = {}
+    for binding in records.bindings_in_scope(system_id=system_id, environment_id=environment_id):
+        bindings_by_identity.setdefault(binding.identity_id, []).append(binding)
+
+    verdicts = tuple(
+        _evaluate(
+            identity,
+            identity_status=identity_statuses.get(identity.id),
+            bindings=bindings_by_identity.get(identity.id, []),
+            binding_statuses=binding_statuses,
+            items=items,
+            verifications=verifications,
+            audience_counts=audience_counts,
+            boundaries=boundaries,
+        )
+        for identity in identities
+    )
+
+    cached = {row.id: row.covered_cache for row in identities}
+    disagreements = tuple(
+        Disagreement(
+            identity_id=verdict.identity_id,
+            uri=verdict.uri,
+            cached=cached[verdict.identity_id],
+            recomputed=verdict.covered,
+        )
+        for verdict in verdicts
+        if cached[verdict.identity_id] != verdict.covered
+    )
+
+    if disagreements:
+        _LOGGER.alarm(
+            "coverage_cache_disagreement",
+            code=str(ErrorCode.COVERAGE_CACHE_DISAGREEMENT),
+            system_id=system_id,
+            environment_id=environment_id,
+            disagreement_count=len(disagreements),
+            identity_ids=[entry.identity_id for entry in disagreements[:COVERAGE_ALARM_SAMPLE_MAX]],
+            identity_ids_truncated=len(disagreements) > COVERAGE_ALARM_SAMPLE_MAX,
+        )
+
+    return CoverageResult(
+        system_id=system_id,
+        environment_id=environment_id,
+        identities=verdicts,
+        disagreements=disagreements,
+        computed_at=now,
+    )

adopt_coverage/records.py

@@ -0,0 +1,98 @@
+"""The storage port `recompute_coverage` reads through.
+
+Declared here rather than imported from `adopt_store`, following the precedent
+`adopt_scope.records` set: `no-raw-sqlite` names `adopt_coverage` as a source
+module and import-linter follows the chain, so a dependency on `adopt_store`
+would reach `sqlite3` transitively and break the contract. A structural protocol
+costs one file and keeps this package free of any driver.
+
+**Every method is a read.** The cache write is not on this port -- it lives in
+`adopt_coverage.cache`, which is the only place in either repository permitted to
+hold the statement (`no-covered-cache-write`).
+
+**The port fetches rows; it never decides.** Each method is one bulk read whose
+result is a plain mapping or a sequence of generated models. Pushing any of the
+six coverage inputs into SQL would move the authority out of
+`recompute_coverage` and into whichever realization ran -- and the property test
+that compares the function against an independent reference implementation would
+then be comparing two callers of one query.
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Protocol
+
+from adopt_model import Binding, Identity, KnowledgeItem, ObservabilityBoundary
+
+__all__ = ["CoverageRecords"]
+
+
+class CoverageRecords(Protocol):
+    """Row in, decision out. No SQL, connection or cursor crosses this boundary.
+
+    Every method takes the scope the recompute was asked for. `environment_id`
+    is optional because `recompute_coverage` is (contracts §6); `None` means
+    every environment of the system rather than "the environment that is null",
+    and the two readings differ for `knowledge_item`, whose `environment_id` is
+    nullable precisely because an item may span environments.
+    """
+
+    def identities_in_scope(
+        self, *, system_id: str, environment_id: str | None
+    ) -> Sequence[Identity]: ...
+
+    def systems_with_identities(self) -> Sequence[str]:
+        """Every `system_id` that has at least one identity.
+
+        `store doctor` sweeps coverage across the whole store and has no scope
+        argument to work from (implementation spec §4.7: `doctor(store)`). Making
+        it ask which systems exist is what stops the sweep silently checking
+        nothing when a caller forgets to name one.
+        """
+        ...
+
+    def head_identity_statuses(
+        self, *, system_id: str, environment_id: str | None
+    ) -> Mapping[str, str]:
+        """`identity_id` -> the status of its head revision.
+
+        `identity` carries no head pointer, so the head is *derived*: the
+        revision no other revision supersedes (contracts §5 obligation 3). An
+        identity with no revision at all is absent from the mapping rather than
+        present with a placeholder -- "no revision" and "a revision saying
+        nothing" are different facts and the caller treats them differently.
+        """
+        ...
+
+    def bindings_in_scope(
+        self, *, system_id: str, environment_id: str | None
+    ) -> Sequence[Binding]: ...
+
+    def head_binding_statuses(
+        self, *, system_id: str, environment_id: str | None
+    ) -> Mapping[str, str]:
+        """`binding_id` -> the status of its head revision."""
+        ...
+
+    def items_in_scope(self, *, system_id: str) -> Sequence[KnowledgeItem]:
+        """Scoped by system only.
+
+        `knowledge_item.environment_id` is nullable, so filtering it by
+        environment here would silently drop every item that spans environments
+        -- which is the population the environment check in `recompute_coverage`
+        exists to reason about.
+        """
+        ...
+
+    def head_item_verifications(self, *, system_id: str) -> Mapping[str, str | None]:
+        """`item_id` -> `verification` on its current knowledge revision.
+
+        Absent when the item has no current revision; `None` when the revision
+        carries no verification, which the column permits.
+        """
+        ...
+
+    def audience_counts(self, *, system_id: str) -> Mapping[str, int]:
+        """`item_id` -> how many `audience_tag` rows it carries."""
+        ...
+
+    def boundaries_for_system(self, *, system_id: str) -> Sequence[ObservabilityBoundary]: ...

adopt_coverage-0.4.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: adopt-coverage
+Version: 0.4.0
+Summary: recompute_coverage and the cache-disagreement alarm. Implemented in S4.
+Project-URL: Homepage, https://github.com/onboardux/onboard-core
+Project-URL: Source, https://github.com/onboardux/onboard-core
+Project-URL: Issues, https://github.com/onboardux/onboard-core/issues
+Author: The Adopt Authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: adopt-const
+Requires-Dist: adopt-model
+Requires-Dist: adopt-obs

adopt_coverage-0.4.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+adopt_coverage/__init__.py,sha256=i8waVAe9McdGcNU1lG3zz-sUc_NYsOZVqyvSbk8oJPo,1797
+adopt_coverage/cache.py,sha256=S_CV5gZUBuusO666FvP7W0LuyJf6Qxvm9Z8g2c5t6k8,3872
+adopt_coverage/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adopt_coverage/recompute.py,sha256=LCi02yZAROIi9HazA7VgHtNHACBv4vPZll3KXhylZvo,16584
+adopt_coverage/records.py,sha256=Eq3yfzSj4oeyy1BA0mCOVrOlGTN1WK5G32gK3fFDpvk,4198
+adopt_coverage-0.4.0.dist-info/METADATA,sha256=eQXEgqSp3RlrvPwOsv95dw9w3S7s6uB0wkVlaAqDZAY,540
+adopt_coverage-0.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+adopt_coverage-0.4.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+adopt_coverage-0.4.0.dist-info/licenses/NOTICE,sha256=2_mgo6v6IM9fAn52L5-wXFpISnC6PVU_geTutoRhbWk,1897
+adopt_coverage-0.4.0.dist-info/RECORD,,

adopt_coverage-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

adopt_coverage-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

adopt_coverage-0.4.0.dist-info/licenses/NOTICE

@@ -0,0 +1,39 @@
+Adopt — Adoption-Phase Platform, shared substrate (`adopt-core`)
+Copyright 2026 The Adopt Authors
+
+This product includes software developed by The Adopt Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+--------------------------------------------------------------------------------
+Attribution note
+--------------------------------------------------------------------------------
+
+The copyright holder is recorded here as "The Adopt Authors" pending the legal
+entity name. The owner must settle that attribution before the 0.3.0 tag,
+because published package metadata cannot be changed retroactively for a
+release that has already left the machine. The product name itself is settled:
+handoff-index CR-50 keeps `Adopt` distinct from the `onboard` URI namespace.
+
+--------------------------------------------------------------------------------
+Third-party dependencies
+--------------------------------------------------------------------------------
+
+Every third-party dependency linked into this distribution is permissively
+licensed. The complete list, with licence hash, security status, usage mode,
+owner and re-verification date, is maintained in `licence-verifications.md` and
+enforced by `scripts/licence_gate.py`.
+
+Copyleft-licensed tools are invoked as subprocesses only and are never linked
+into this distribution. They are declared in `subprocess-deps.toml` together
+with their invocation sites.