@arbiterforge/ca-pi 0.15.10 → 0.16.0

package/plugins/ca-pi/hooks/_provenancelib.py

@@ -10,9 +10,9 @@
 # Design invariants (mirroring _taskboardlib.py / _metricslib.py):
 #   - Stdlib only; no third-party imports ever — runs on stock Python.
 #   - Zero side effects at import time: no git calls, no file I/O on import.
-#   - Pure functions are fully testable with synthetic data (no real file
-#     needed). write_provenance() and read_provenance() are the ONLY functions
-#     that touch the filesystem.
+#   - Pure comparisons are testable with synthetic data. The v1 reader/writer,
+#     strict v2 store reader, and live T-008 snapshot probe are explicit I/O
+#     boundaries.
 #   - Never raise on malformed input — degrade gracefully (this runs on the
 #     SessionStart linchpin path).
 #   - Hashing uses git hash-object via an injectable runner (batch_hash);
@@ -41,6 +41,10 @@
 #       }
 #     ]
 #   }
+# Schema v2 is a closed per-document record: canonical Markdown raw identity,
+# stable field/claim IDs, raw-content and bounded-membership evidence methods,
+# and separate stored semantic-review and owner references. Those references
+# are inert; storage validation never grants approval or semantic authority.
 #
 # Files live at: .codearbiter/.provenance/<doc>.json
 # JSON format: pretty-printed, sorted keys, trailing newline, utf-8, LF endings.
@@ -49,11 +53,10 @@
 #   new_record(doc, *, interview_derived=False, entries=None, created=None)
 #                                        -> dict   canonical record with schema=1
 #   write_provenance(path, record)       -> None   pretty JSON; creates parent dirs
-#   valid_provenance_record(record)      -> bool   True iff a well-formed v1
-#                                                  record (top-level shape)
+#   valid_provenance_record(record)      -> bool   v1 top-level or closed v2 shape
 #   read_provenance(path)                -> dict | None  None on missing/corrupt
 #                                                  — including valid JSON whose
-#                                                  shape is not a v1 record
+#                                                  shape is not a known record
 #   batch_hash(paths, runner)            -> dict[str, str]  one git hash-object --stdin-paths
 #                                                            call; input-order-preserving; {}
 #                                                            on empty paths or runner failure
@@ -73,7 +76,7 @@
 #                                                  never suppresses a later valid one.
 #                                                  `skipped` (optional list) collects up to
 #                                                  MAX_SKIPPED_REPORTED rejected basenames.
-#   startup_drift_line(root, runner=None)
+#   startup_drift_line(root, runner=None, cmd_ref=None, unknown=None)
 #                                        -> str    "" when clean (AC-06);
 #                                                  "context drift: N stale source(s) across M doc(s) -- run /ca:context-check"
 #                                                  when drift > 0 (AC-07). ASCII-only, exactly one line.
@@ -89,12 +92,19 @@
 #                                        drift_trigger:true with a diverged or absent
 #                                        current hash; [] when no staged file is tracked
 #                                        (cost guarantee — ordinary commits pay nothing, AC-13)
-#   lint_code_map(text)                  -> list[str]  UTF-8 size / entry cap / multi-line violations
+#   lint_code_map(text, root=None)       -> list[str]  bounded map/path diagnostics
 #   write_stub(path, doc, *, interview_derived=True, created=None) -> None
 #                                        write greenfield stub: interview_derived=True, entries=[]
+#   assess_context_provenance(provenance_dir, expected_docs, snapshot, snapshot_probe=None)
+#                                        -> dict   conservative v2 identity/coverage status;
+#                                                  semantic authority always remains separate
+#   startup_context_coverage_line(root, cmd_ref=None)
+#                                        -> str    bounded record-coverage diagnostic;
+#                                                  does not hash source or claim freshness
 
 import datetime
 import glob
+import hashlib
 import json
 import ntpath
 import os
@@ -111,6 +121,29 @@ import _hooklib
 # ---------------------------------------------------------------------------
 
 SCHEMA_VERSION = 1
+V2_SCHEMA_VERSION = 2
+V2_CONTRACT = "provenance-v2/1"
+# The store is shared by all three governance hosts. A v2 write needs an
+# observation from the owning integration for every installed consumer.
+V2_HOSTS = ("ca", "ca-codex", "ca-pi")
+V2_DOCUMENTS = {
+    "CONTEXT": ".codearbiter/CONTEXT.md",
+    "tech-stack": ".codearbiter/tech-stack.md",
+    "coding-standards": ".codearbiter/coding-standards.md",
+    "security-controls": ".codearbiter/security-controls.md",
+    "code-map": ".codearbiter/code-map.md",
+}
+# Match the native context writer's 8 MiB canonical input ceiling. The same
+# ceiling bounds the entire startup scan, including unusable JSON bytes.
+MAX_CONTEXT_RECORD_BYTES = 8 * 1024 * 1024
+MAX_CONTEXT_STORE_BYTES = 8 * 1024 * 1024
+MAX_CONTEXT_STORE_FILES = 256
+_V2_ID_RE = re.compile(r"(?:FIELD|CLAIM)-[A-Z0-9]+(?:-[A-Z0-9]+)*\Z")
+_SHA256_RE = re.compile(r"[0-9a-f]{64}\Z")
+_V2_MEMBERSHIP_PREDICATES = frozenset({
+    "manifests", "instructions", "configuration", "tests",
+    "infrastructure", "security", "data",
+})
 
 # Maximum seconds allowed for a single git read call.  A hung git process must
 # never stall the SessionStart linchpin hook indefinitely; timeout degrades to
@@ -130,6 +163,7 @@ CODE_MAP_MAX_BYTES = 20 * 1024
 # Regex matching a column-0 entry bullet: starts with '- `' (dash, space, backtick).
 # Concern '## heading' lines are NOT entries.  Captures the path between backticks.
 _ENTRY_RE = re.compile(r"^- `([^`]+)`")
+_CODE_MAP_ROLE_RE = re.compile(r"^- `[^`]+`\s+(?:--|—)\s+(.+)$")
 
 # ---------------------------------------------------------------------------
 # classify_source constants
@@ -224,7 +258,8 @@ def new_record(doc, *, interview_derived=False, entries=None, created=None):
 # ---------------------------------------------------------------------------
 
 
-def write_provenance(path, record):
+def write_provenance(path, record, *, capability_probe=None, ownership_probe=None,
+                     expected_previous_sha256=None):
     """Write `record` as pretty JSON to `path`, atomically.
 
     Format: indent=2, sorted keys, ensure_ascii=False, trailing newline, utf-8,
@@ -233,13 +268,182 @@ def write_provenance(path, record):
     temp file + os.replace) so a crash mid-write leaves the previous provenance
     record intact instead of a truncated/corrupt file (reliability-016).
     """
+    if isinstance(record, dict) and record.get("schema") == V2_SCHEMA_VERSION:
+        if not valid_provenance_record(record):
+            raise ValueError("INVALID_V2_RECORD")
+        if os.path.basename(os.fspath(path)) != record["doc"] + ".json":
+            raise ValueError("V2_WRONG_RECORD_PATH")
+        # The probe is a trusted integration seam, not a record field or an
+        # approval adapter. Current installed consumers supply no such probe,
+        # so source-only deployments cannot enroll v2 accidentally.
+        if not callable(capability_probe) or not callable(ownership_probe):
+            raise ValueError("V2_CAPABILITY_UNAVAILABLE")
+        try:
+            capability = capability_probe(V2_CONTRACT, V2_HOSTS)
+        except Exception:
+            raise ValueError("V2_CAPABILITY_UNAVAILABLE") from None
+        if not _v2_capability_supported(capability):
+            raise ValueError("V2_CAPABILITY_UNAVAILABLE")
+        text = json.dumps(record, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+        candidate_digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
+        field_ids = tuple(field["id"] for field in record["fields"])
+        try:
+            ownership = ownership_probe(candidate_digest, record["doc"], field_ids)
+        except Exception:
+            raise ValueError("V2_OWNERSHIP_UNVERIFIED") from None
+        if (type(ownership) is not dict or set(ownership) != {
+                "status", "record_digest", "doc", "field_ids"} or
+                ownership["status"] != "accepted" or
+                ownership["record_digest"] != candidate_digest or
+                ownership["doc"] != record["doc"] or
+                ownership["field_ids"] != list(field_ids)):
+            raise ValueError("V2_OWNERSHIP_UNVERIFIED")
+        if expected_previous_sha256 != "absent" and not _sha256(expected_previous_sha256):
+            raise ValueError("V2_PREIMAGE_REQUIRED")
+        try:
+            with open(path, "rb") as prior_file:
+                prior = prior_file.read()
+        except FileNotFoundError:
+            prior = None
+        except OSError:
+            raise ValueError("V2_PREIMAGE_UNKNOWN") from None
+        if prior is None:
+            if expected_previous_sha256 != "absent":
+                raise ValueError("V2_PREIMAGE_CHANGED")
+        else:
+            if hashlib.sha256(prior).hexdigest() != expected_previous_sha256:
+                raise ValueError("V2_PREIMAGE_CHANGED")
+            existing = read_provenance(path)
+            if existing is None or existing.get("doc") != record["doc"]:
+                raise ValueError("V2_UNSUPPORTED_PREVIOUS_RECORD")
+    else:
+        # Legacy creation and supported v1 updates retain their contract.
+        # An unreadable or unsupported existing record is not an absent slot;
+        # preserve it for explicit reconciliation even through an older caller.
+        existing = read_provenance(path)
+        if existing is None and os.path.lexists(path):
+            raise ValueError("UNSUPPORTED_PREVIOUS_RECORD")
+        if existing is not None and existing.get("schema") == V2_SCHEMA_VERSION:
+            raise ValueError("V2_DOWNGRADE_UNSUPPORTED")
+        text = json.dumps(record, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
     parent = os.path.dirname(path)
     if parent:
         os.makedirs(parent, exist_ok=True)
-    text = json.dumps(record, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
     _hooklib.write_text_atomic(path, text, newline="\n")
 
 
+def _sha256(value):
+    return type(value) is str and _SHA256_RE.fullmatch(value) is not None
+
+
+def _v2_capability_supported(value):
+    if type(value) is not dict or set(value) != {"contract", "producer", "consumers"}:
+        return False
+    if value["contract"] != V2_CONTRACT:
+        return False
+    producer = value["producer"]
+    consumers = value["consumers"]
+    if type(producer) is not dict or set(producer) != {"status", "contract"}:
+        return False
+    if producer != {"status": "supported", "contract": V2_CONTRACT}:
+        return False
+    if type(consumers) is not dict or set(consumers) != set(V2_HOSTS):
+        return False
+    return all(type(cell) is dict and cell == {
+        "status": "supported", "contract": V2_CONTRACT}
+        for cell in consumers.values())
+
+
+def _v2_text(value):
+    return (type(value) is str and 0 < len(value) <= 256 and
+            not any(ord(char) < 32 or ord(char) == 127 for char in value))
+
+
+def _v2_path(value, *, root=False):
+    if not _v2_text(value):
+        return False
+    if root and value == ".":
+        return True
+    if value.startswith(("/", "\\")) or "\\" in value or ":" in value:
+        return False
+    return all(part not in ("", ".", "..") for part in value.split("/"))
+
+
+def _valid_v2_evidence(evidence):
+    if type(evidence) is not dict or evidence.get("kind") not in ("content", "membership"):
+        return False
+    if evidence["kind"] == "content":
+        return (set(evidence) == {"kind", "path", "digest_method", "digest"} and
+                _v2_path(evidence["path"]) and
+                evidence["digest_method"] == "sha256-raw" and
+                _sha256(evidence["digest"]))
+    scopes = evidence.get("scope_paths")
+    return (set(evidence) == {"kind", "predicate", "scope_paths", "digest_method", "digest"} and
+            evidence["predicate"] in _V2_MEMBERSHIP_PREDICATES and
+            type(scopes) is list and 0 < len(scopes) <= 32 and
+            len(scopes) == len(set(scopes)) and
+            all(_v2_path(scope, root=True) for scope in scopes) and
+            evidence["digest_method"] == "sha256-membership-v1" and
+            _sha256(evidence["digest"]))
+
+
+def _valid_v2_record(record):
+    """Closed storage shape; review labels and references are inert data."""
+    if set(record) != {"schema", "doc", "created", "document", "fields"}:
+        return False
+    doc = record["doc"]
+    if doc not in V2_DOCUMENTS or not _v2_text(record["created"]):
+        return False
+    document = record["document"]
+    if (type(document) is not dict or
+            set(document) != {"path", "digest_method", "digest"} or
+            document["path"] != V2_DOCUMENTS[doc] or
+            document["digest_method"] != "sha256-raw" or
+            not _sha256(document["digest"])):
+        return False
+    fields = record["fields"]
+    if type(fields) is not list or not 0 < len(fields) <= 128:
+        return False
+    ids = set()
+    for field in fields:
+        if type(field) is not dict or set(field) != {"id", "owner_ref", "claims"}:
+            return False
+        field_id = field["id"]
+        if (type(field_id) is not str or not _V2_ID_RE.fullmatch(field_id) or
+                not field_id.startswith("FIELD-") or field_id in ids or
+                not _v2_text(field["owner_ref"])):
+            return False
+        ids.add(field_id)
+        claims = field["claims"]
+        if type(claims) is not list or not 0 < len(claims) <= 128:
+            return False
+        for claim in claims:
+            if type(claim) is not dict or set(claim) != {
+                    "id", "semantic_review", "evidence", "effective_authority_refs"}:
+                return False
+            claim_id = claim["id"]
+            if (type(claim_id) is not str or not _V2_ID_RE.fullmatch(claim_id) or
+                    not claim_id.startswith("CLAIM-") or claim_id in ids):
+                return False
+            ids.add(claim_id)
+            review = claim["semantic_review"]
+            if (type(review) is not dict or set(review) != {"state", "reference"} or
+                    review["state"] not in ("unreviewed", "reviewed", "identity_acknowledged") or
+                    (review["reference"] is not None and not _v2_text(review["reference"])) or
+                    (review["state"] == "reviewed" and not _v2_text(review["reference"]))):
+                return False
+            evidence = claim["evidence"]
+            if type(evidence) is not list or not 0 < len(evidence) <= 128:
+                return False
+            if not all(_valid_v2_evidence(item) for item in evidence):
+                return False
+            refs = claim["effective_authority_refs"]
+            if (type(refs) is not list or len(refs) > 32 or
+                    not all(_v2_text(ref) for ref in refs) or len(refs) != len(set(refs))):
+                return False
+    return True
+
+
 # Top-level provenance-record contract (v1). Each required key maps to the
 # type(s) a canonical record — the one new_record() builds — always carries.
 # `bool` is excluded from the `schema` check explicitly because in Python
@@ -253,17 +457,14 @@ _RECORD_FIELD_TYPES = (
 
 
 def valid_provenance_record(record):
-    """True iff `record` is a well-formed v1 provenance record (#410).
+    """True iff `record` is a known v1 or closed v2 provenance record.
 
-    Checks the TOP-LEVEL shape only: the store's own frame. Entry-level
-    tolerance stays where it already lives — compute_drift and the read-inject
-    pointer both skip a malformed entry without dropping its record — so one
-    odd claim never costs a doc its entire provenance.
+    For legacy v1, check the top-level frame only. Entry-level tolerance stays
+    where it already lives — compute_drift and read-inject skip malformed
+    entries without dropping a record. V2 is closed at every nested level.
 
-    A schema other than SCHEMA_VERSION is rejected rather than best-effort
-    parsed: every field expectation below is v1-specific, so admitting an
-    unknown version would mean reading it with the wrong rules. Bumping
-    SCHEMA_VERSION therefore requires revisiting this function deliberately.
+    Unknown versions are rejected rather than best-effort parsed. Adding a
+    version requires a deliberate new branch; v1 never becomes v2 by rehashing.
     Never raises.
     """
     if not isinstance(record, dict):
@@ -271,12 +472,17 @@ def valid_provenance_record(record):
     schema = record.get("schema")
     if isinstance(schema, bool) or not isinstance(schema, int):
         return False
-    if schema != SCHEMA_VERSION:
-        return False
-    for key, want in _RECORD_FIELD_TYPES:
-        if key not in record or not isinstance(record[key], want):
+    if schema == V2_SCHEMA_VERSION:
+        try:
+            return _valid_v2_record(record)
+        except (KeyError, TypeError, ValueError):
             return False
-    return True
+    if schema == SCHEMA_VERSION:
+        for key, want in _RECORD_FIELD_TYPES:
+            if key not in record or not isinstance(record[key], want):
+                return False
+        return True
+    return False
 
 
 def read_provenance(path):
@@ -286,7 +492,7 @@ def read_provenance(path):
     a permission error, or malformed JSON all return None; the caller degrades
     gracefully.
 
-    #410: "corrupt" now includes SYNTACTICALLY VALID JSON of the wrong shape.
+    #410: "corrupt" includes SYNTACTICALLY VALID JSON of the wrong shape.
     The documented return type is `dict | None`, but the raw json.load result
     was handed straight back — so a file containing `[]` was admitted to the
     store as a list and the first `.get()` downstream raised AttributeError.
@@ -301,6 +507,333 @@ def read_provenance(path):
     return record if valid_provenance_record(record) else None
 
 
+def _read_context_store(provenance_dir, expected_docs):
+    """Read bounded v2 candidates, preserving valid neighbors on bad records.
+
+    The returned completeness flag covers every JSON in the store, including
+    unsupported extra files. Per-document faults remain distinguishable from
+    absent files; neither can become a verified current identity.
+    """
+    records = {}
+    faults = {}
+    complete = True
+    truncated = False
+    total_bytes = 0
+
+    def unique_object(pairs):
+        value = {}
+        for key, item in pairs:
+            if key in value:
+                raise ValueError("duplicate JSON key")
+            value[key] = item
+        return value
+
+    try:
+        with os.scandir(provenance_dir) as listing:
+            for count, entry in enumerate(listing, 1):
+                if count > MAX_CONTEXT_STORE_FILES:
+                    complete = False
+                    truncated = True
+                    break
+                if not entry.name.endswith(".json"):
+                    continue
+                stem = entry.name[:-5]
+                try:
+                    if not entry.is_file(follow_symlinks=False):
+                        raise ValueError("non-file provenance entry")
+                    remaining = MAX_CONTEXT_STORE_BYTES - total_bytes
+                    if remaining <= 0:
+                        faults[stem] = "oversize"
+                        complete = False
+                        truncated = True
+                        break
+                    limit = min(MAX_CONTEXT_RECORD_BYTES, remaining)
+                    with open(entry.path, "rb") as source:
+                        raw = source.read(limit + 1)
+                    total_bytes += len(raw)
+                    if len(raw) > limit:
+                        faults[stem] = "oversize"
+                        complete = False
+                        if len(raw) > remaining:
+                            truncated = True
+                            break
+                        continue
+                    record = json.loads(raw.decode("utf-8"),
+                                        object_pairs_hook=unique_object)
+                except (OSError, UnicodeError, ValueError, RecursionError):
+                    complete = False
+                    faults[stem] = "corrupt"
+                    continue
+                if not valid_provenance_record(record):
+                    complete = False
+                    faults[stem] = "unsupported" if (type(record) is dict and
+                                                         record.get("schema") not in
+                                                         (SCHEMA_VERSION, V2_SCHEMA_VERSION)) else "corrupt"
+                    continue
+                doc = record["doc"]
+                if doc in V2_DOCUMENTS and entry.name != doc + ".json":
+                    complete = False
+                    faults[stem] = "corrupt"
+                    continue
+                if doc in records:
+                    complete = False
+                    faults[doc] = "corrupt"
+                    records.pop(doc, None)
+                    continue
+                records[doc] = record
+    except FileNotFoundError:
+        return {}, True, {}
+    except (OSError, TypeError, ValueError):
+        return {}, False, {doc: "store_unreadable" for doc in expected_docs}
+    if truncated:
+        for doc in expected_docs:
+            if doc not in records and doc not in faults:
+                faults[doc] = "store_unreadable"
+    return {doc: records.get(doc) for doc in expected_docs}, complete, faults
+
+
+def _first_manifest_after_interview_stub(provenance_dir, record, snapshot):
+    """Return currently observed manifest paths, or [] without a safe handoff.
+
+    This is an advisory first-input acquisition for the empty greenfield stack
+    stub. It neither reads manifest content nor writes guidance or provenance.
+    The stub's empty entries mean no acquired source facts, not proof that the
+    repository was empty. A complete prior empty snapshot or a fresh nonempty
+    one can initiate acquisition. Worktree, membership and target are rechecked
+    before reporting actual current paths.
+    """
+    if (record.get("schema") != SCHEMA_VERSION or
+            record.get("doc") != "tech-stack" or
+            record.get("interview_derived") is not True or
+            record.get("entries") != []):
+        return []
+    try:
+        import _contextsnapshotlib
+        root = snapshot["worktree"]["root"]
+        if (type(root) is not str or
+                os.path.normcase(os.path.realpath(provenance_dir)) !=
+                os.path.normcase(os.path.realpath(os.path.join(
+                    root, ".codearbiter", ".provenance")))):
+            return []
+        saved = next(item for item in snapshot["source"]["membership"]
+                     if item["predicate"] == "manifests" and
+                     item["scope_paths"] == ["."])
+        if saved["status"] != "complete":
+            return []
+        checked = _contextsnapshotlib.compare_context_dependencies(
+            snapshot, membership=(("manifests", (".",)),),
+            target_paths=(".codearbiter/tech-stack.md",))
+        if not checked["targets_current"]:
+            return []
+        current = _contextsnapshotlib.membership_snapshot(root, "manifests")
+        if current["status"] != "complete" or not current["matches"]:
+            return []
+        return current["matches"]
+    except (KeyError, TypeError, ValueError, AttributeError, StopIteration,
+            OSError, _contextsnapshotlib.SnapshotError,
+            _contextsnapshotlib.MembershipError):
+        return []
+
+
+def assess_context_provenance(provenance_dir, expected_docs, snapshot,
+                              snapshot_probe=None):
+    """Report bounded v2 coverage and current identities, never semantic approval.
+
+    Reads the bounded on-disk JSON store and flags malformed/unsupported files
+    without losing valid neighbors. The legacy loader intentionally skips bad
+    records for advisory availability; task-time reliance must not call that
+    omission complete coverage.
+    `snapshot` is the T-008 source/target snapshot; the default probe reacquires
+    it at an action boundary. An integration may supply an equivalent trusted
+    probe, but a stored record or source snapshot alone is never live truth.
+    The result cannot authorize the future native repository-context kind.
+    """
+    result = {"coverage": "incomplete", "identity": "unknown",
+              "semantic": "unverified", "verified_fresh": False,
+              "documents": {}, "first_input": {}}
+    if (not isinstance(provenance_dir, (str, os.PathLike)) or
+            type(expected_docs) not in (list, tuple) or
+            not expected_docs):
+        return result
+    try:
+        if (len(expected_docs) != len(set(expected_docs)) or
+                any(doc not in V2_DOCUMENTS for doc in expected_docs)):
+            return result
+    except TypeError:
+        return result
+    records, store_complete, faults = _read_context_store(provenance_dir, expected_docs)
+    for doc in expected_docs:
+        record = records.get(doc)
+        if doc in faults:
+            result["documents"][doc] = faults[doc]
+        elif record is None:
+            result["documents"][doc] = "missing"
+        elif not valid_provenance_record(record) or record.get("doc") != doc:
+            result["documents"][doc] = "unsupported"
+        elif record["schema"] == SCHEMA_VERSION:
+            result["documents"][doc] = "legacy_unverified"
+            if doc == "tech-stack" and snapshot_probe is None:
+                paths = _first_manifest_after_interview_stub(
+                    provenance_dir, record, snapshot)
+                if paths:
+                    result["documents"][doc] = "first_input_pending"
+                    result["first_input"][doc] = {
+                        "paths": paths, "refresh_docs": ["tech-stack"]}
+        else:
+            result["documents"][doc] = "v2_unchecked"
+    eligible = [doc for doc in expected_docs
+                if result["documents"][doc] == "v2_unchecked"]
+    if not eligible:
+        return result
+    probes = {}
+    if snapshot_probe is None:
+        # A provenance store belongs to one worktree. Its own JSON and marker
+        # writes are output effects, never source dependencies for a new scout.
+        try:
+            import _contextsnapshotlib
+            root = snapshot["worktree"]["root"]
+            if (type(root) is not str or
+                    os.path.normcase(os.path.realpath(provenance_dir)) !=
+                    os.path.normcase(os.path.realpath(os.path.join(
+                        root, ".codearbiter", ".provenance")))):
+                return result
+        except (KeyError, TypeError, ValueError, OSError):
+            return result
+        for doc in eligible:
+            record = records[doc]
+            evidence = [item for field in record["fields"]
+                        for claim in field["claims"] for item in claim["evidence"]]
+            paths = sorted({item["path"] for item in evidence
+                            if item["kind"] == "content"})
+            members = sorted({(item["predicate"], tuple(item["scope_paths"]))
+                              for item in evidence if item["kind"] == "membership"})
+            try:
+                probes[doc] = _contextsnapshotlib.compare_context_dependencies(
+                    snapshot, source_paths=paths, membership=members,
+                    target_paths=(record["document"]["path"],))
+            except Exception:
+                # Missing/unreadable inputs or a changed worktree cannot be
+                # promoted to current by another document's successful check.
+                continue
+    else:
+        try:
+            probe = snapshot_probe(snapshot)
+            if (type(probe) is not dict or
+                    type(probe.get("source_current")) is not bool or
+                    type(probe.get("targets_current")) is not bool):
+                return result
+        except Exception:
+            return result
+        probes = {doc: probe for doc in eligible}
+        if not probe["source_current"] or not probe["targets_current"]:
+            if store_complete and len(eligible) == len(expected_docs):
+                result["coverage"] = "complete"
+            result["identity"] = "stale"
+            for doc in eligible:
+                result["documents"][doc] = "v2_stale"
+            return result
+    try:
+        files = snapshot["source"]["files"]
+        membership = snapshot["source"]["membership"]
+        targets = snapshot["targets"]
+        if type(files) is not dict or type(membership) is not list or type(targets) is not dict:
+            return result
+        membership_by_key = {
+            (item["predicate"], tuple(item["scope_paths"])): item
+            for item in membership if type(item) is dict
+        }
+        for doc in eligible:
+            probe = probes.get(doc)
+            if probe is None:
+                continue
+            if not probe["source_current"] or not probe["targets_current"]:
+                result["identity"] = "stale"
+                result["documents"][doc] = "v2_stale"
+                continue
+            record = records[doc]
+            document = record["document"]
+            target = targets.get(document["path"])
+            if target is None:
+                continue
+            if (target.get("status") != "file" or
+                    target.get("digest_method") != document["digest_method"] or
+                    target.get("digest") != document["digest"]):
+                result["identity"] = "stale"
+                result["documents"][doc] = "v2_stale"
+                continue
+            unresolved = False
+            for field in record["fields"]:
+                for claim in field["claims"]:
+                    for evidence in claim["evidence"]:
+                        if evidence["kind"] == "content":
+                            current = files.get(evidence["path"])
+                        else:
+                            key = (evidence["predicate"], tuple(evidence["scope_paths"]))
+                            current = membership_by_key.get(key)
+                        if current is None:
+                            unresolved = True
+                            continue
+                        if (current.get("digest_method") != evidence["digest_method"] or
+                                current.get("digest") != evidence["digest"]):
+                            result["identity"] = "stale"
+                            result["documents"][doc] = "v2_stale"
+            if result["documents"][doc] == "v2_unchecked" and not unresolved:
+                result["documents"][doc] = "v2_current"
+    except (KeyError, TypeError, AttributeError, ValueError):
+        return result
+    if store_complete and all(result["documents"][doc] in
+                              ("v2_current", "v2_stale") for doc in expected_docs):
+        result["coverage"] = "complete"
+    if result["coverage"] == "complete" and result["identity"] != "stale":
+        result["identity"] = "current"
+    return result
+
+
+def startup_context_coverage_line(root, cmd_ref=None):
+    """Summarize bounded record coverage without doing startup source hashing.
+
+    This is a record-presence diagnostic, never a current-identity or semantic
+    verdict. Task-time reliance uses assess_context_provenance with a fresh
+    action-boundary snapshot instead.
+    """
+    try:
+        context = os.path.join(root, ".codearbiter", "CONTEXT.md")
+        if not os.path.isfile(context):
+            return ""
+        expected = tuple(V2_DOCUMENTS)
+        store = os.path.join(root, ".codearbiter", ".provenance")
+        records, complete, faults = _read_context_store(store, expected)
+        counts = {"v2": 0, "legacy": 0, "missing": 0,
+                  "corrupt": 0, "unsupported": 0, "oversize": 0,
+                  "unreadable": 0}
+        for doc in expected:
+            if doc in faults:
+                kind = faults[doc]
+                counts["unreadable" if kind == "store_unreadable" else kind] += 1
+            elif records.get(doc) is None:
+                counts["missing"] += 1
+            elif records[doc]["schema"] == V2_SCHEMA_VERSION:
+                counts["v2"] += 1
+            else:
+                counts["legacy"] += 1
+        ref = cmd_ref("context-check") if cmd_ref else "/ca:context-check"
+        if complete and counts["v2"] == len(expected):
+            return ("context coverage: {}/{} v2 records; identities and semantics "
+                    "unchecked at startup -- run {}").format(
+                        counts["v2"], len(expected), ref)
+        details = ["v2 {}/{}".format(counts["v2"], len(expected))]
+        details.extend("{} {}".format(key, counts[key]) for key in
+                       ("legacy", "missing", "corrupt", "unsupported",
+                        "oversize", "unreadable")
+                       if counts[key])
+        if not complete and not faults:
+            details.append("store incomplete")
+        return "context coverage: incomplete ({}); identities and semantics unchecked -- run {}".format(
+            "; ".join(details), ref)
+    except Exception:
+        return "context coverage: unknown -- run /ca:context-check"
+
+
 # ---------------------------------------------------------------------------
 # Git hashing (injectable runner contract)
 # ---------------------------------------------------------------------------
@@ -461,8 +994,9 @@ def compute_drift(provenance_map, current_hashes):
             doc_drifts = []
             for entry in entries:
                 try:
-                    # AC-09: only explicit True fires drift; absent/falsy → skip.
-                    if entry.get("drift_trigger") is not True:
+                    # A removed map target invalidates orientation even for old
+                    # records whose source was classified as ordinary code.
+                    if entry.get("drift_trigger") is not True and doc_name != "code-map":
                         continue
                     path = entry.get("path")
                     stored_hash = entry.get("hash")
@@ -473,6 +1007,8 @@ def compute_drift(provenance_map, current_hashes):
                         # current_hashes means the source was renamed/deleted.
                         doc_drifts.append({"path": path, "kind": "missing"})
                         continue
+                    if entry.get("drift_trigger") is not True:
+                        continue
                     current_hash = current_hashes[path]
                     if current_hash != stored_hash:
                         doc_drifts.append({"path": path, "kind": "changed"})
@@ -779,7 +1315,7 @@ def _is_confined_provenance_path(root, path):
         return False
 
 
-def startup_drift_line(root, runner=None, cmd_ref=None):
+def startup_drift_line(root, runner=None, cmd_ref=None, unknown=None):
     """Return a one-line drift summary for SessionStart, or '' when clean (AC-06).
 
     Pipeline:
@@ -812,6 +1348,8 @@ def startup_drift_line(root, runner=None, cmd_ref=None):
     provenance paths are resolved from root.  T-16 injects its own root-bound
     runner; tests inject a fake.
 
+    `unknown`, when a list is supplied, receives a bounded diagnostic on an
+    incomplete hash batch. The legacy string result remains fail-soft.
     Never raises — all errors degrade to '' (safe for the SessionStart path).
     """
     try:
@@ -826,6 +1364,7 @@ def startup_drift_line(root, runner=None, cmd_ref=None):
         # order-stable). Build a filtered in-memory map at the same time so a
         # rejected path cannot reappear as a false missing-file drift result.
         drift_trigger_paths = []
+        code_map_existing = {}
         safe_pm = {}
         seen = set()
         for doc, record in pm.items():
@@ -834,13 +1373,18 @@ def startup_drift_line(root, runner=None, cmd_ref=None):
                 safe_entries = []
                 for entry in entries:
                     try:
-                        if entry.get("drift_trigger") is True:
+                        if entry.get("drift_trigger") is True or doc == "code-map":
                             path = entry.get("path")
                             if not _is_confined_provenance_path(root, path):
                                 continue
-                            if path not in seen:
+                            if entry.get("drift_trigger") is True and path not in seen:
                                 drift_trigger_paths.append(path)
                                 seen.add(path)
+                            elif doc == "code-map" and os.path.exists(os.path.join(root, path)):
+                                # Ordinary source only needs a lifecycle check;
+                                # its changed contents do not ring the old drift
+                                # trigger. Preserve its stored hash for comparison.
+                                code_map_existing[path] = entry.get("hash")
                         safe_entries.append(entry)
                     except Exception:
                         continue
@@ -868,8 +1412,13 @@ def startup_drift_line(root, runner=None, cmd_ref=None):
         # partial/aborted stdout). Feeding a short hash map to compute_drift would
         # falsely report the un-hashed files as 'missing'. Conservative: stay silent.
         if len(current_hashes) < len(existing_paths):
+            if isinstance(unknown, list):
+                unknown.append("partial hash")
             return ""
 
+        for path, stored_hash in code_map_existing.items():
+            current_hashes.setdefault(path, stored_hash)
+
         drift = compute_drift(pm, current_hashes)
         if not drift:
             return ""
@@ -890,8 +1439,8 @@ def startup_drift_line(root, runner=None, cmd_ref=None):
 # ---------------------------------------------------------------------------
 
 
-def lint_code_map(text):
-    """Lint a code map for UTF-8 size, entry-cap and multi-line-role violations.
+def lint_code_map(text, root=None):
+    """Diagnose a coarse code map without rewriting it or reading source files.
 
     Code-map format: markdown where entries are column-0 '- `path` -- role'
     bullets.  Concern '## <name>' headings are structural labels, NOT entries.
@@ -909,7 +1458,9 @@ def lint_code_map(text):
          whitespace so are excluded automatically.
 
     Returns a list of human-readable ASCII warning strings; [] means clean.
-    Empty or None text -> [] (a missing/empty code map has no violations).
+    When root is supplied, check each safe target's existence on demand. A
+    malformed optional map remains human-owned; warnings never block source
+    inspection. Empty or None text -> [].
     Never raises.
     """
     if not text:
@@ -929,6 +1480,7 @@ def lint_code_map(text):
         lines = text.splitlines()
         entry_paths = []       # ordered list of extracted paths (one per entry)
         multi_warnings = []    # per-entry multi-line-role warnings (built inline)
+        path_warnings = []
 
         for i, line in enumerate(lines):
             m = _ENTRY_RE.match(line)
@@ -938,6 +1490,23 @@ def lint_code_map(text):
             entry_num = len(entry_paths) + 1   # 1-indexed
             entry_paths.append(entry_path)
 
+            role = _CODE_MAP_ROLE_RE.match(line)
+            if role is None or not role.group(1).strip():
+                path_warnings.append("invalid one-line role at entry {}".format(entry_num))
+            parts = entry_path.split("/")
+            if parts[-1] == "" and len(parts) > 1:
+                parts = parts[:-1]  # directory concern
+            safe = (entry_path == entry_path.strip() and "\\" not in entry_path
+                    and all(part not in ("", ".", "..") for part in parts)
+                    and not entry_path.startswith("/")
+                    and not ntpath.splitdrive(entry_path)[0]
+                    and not any(ord(char) < 32 or ord(char) == 127 for char in entry_path))
+            if not safe or root is not None and not _is_confined_provenance_path(root, entry_path):
+                path_warnings.append("unsafe code map path at entry {}".format(entry_num))
+            elif root is not None and not os.path.exists(os.path.join(root, entry_path)):
+                path_warnings.append("missing code map target at entry {} (path {})".format(
+                    entry_num, entry_path))
+
             # Multi-line role: the next physical line starts with whitespace AND
             # contains non-whitespace content (a genuine continuation, not blank
             # vertical spacing).  Column-0 bullets ('- ') and headings ('## ')
@@ -960,9 +1529,10 @@ def lint_code_map(text):
                 )
             )
         result.extend(multi_warnings)
+        result.extend(path_warnings)
         return result
     except Exception:
-        return []
+        return ["code map could not be inspected"]
 
 
 # ---------------------------------------------------------------------------