moca-reader 0.6.0__py3-none-any.whl

moca_reader/citation.py

@@ -0,0 +1,213 @@
+"""Citation records and the default retrieval policy (Reader contract §7 and §8).
+
+A citation record is a dict valid against citation-record.schema.json: the same JSON in every Reader.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from ._js import effective_window, get, js_string, timestamp, truthy
+from .audience import audience_of
+from .content import ContentNode, Representation
+from .digest import utf8
+from .reviews import review_status_of
+
+if TYPE_CHECKING:
+    from .reader import PackageResult
+
+CitationRecord = dict[str, Any]
+RelationIndex = tuple[dict[str, list[str]], dict[str, list[str]]]  # superseded, contested
+
+
+def passes_default_policy(record: CitationRecord) -> bool:
+    """In force, not superseded, not deprecated (Reader contract §8)."""
+    trust = record["trust"]
+    return bool(trust.get("inForce")) and not trust.get("superseded") and trust.get("status") != "deprecated"
+
+
+def pick_representation(node: ContentNode, locale: str | None) -> Representation:
+    """The representation package spec §5 selects for a locale: exact, then a parent, then a child, then the default."""
+    if not locale:
+        return node.representations[0]
+    want = locale.lower()
+    reps = node.representations
+    # Package spec §5.4: exact; then the longest tag the request starts with (RFC 4647 Lookup); then the lowest
+    # tag, in code-point order, that starts with the request.
+    tagged = [r for r in reps if r.locale]
+    parents = sorted(
+        (r for r in tagged if want.startswith(f"{(r.locale or '').lower()}-")), key=lambda r: -len(r.locale or "")
+    )
+    children = sorted(
+        (r for r in tagged if (r.locale or "").lower().startswith(f"{want}-")), key=lambda r: r.locale or ""
+    )
+    return (
+        next((r for r in tagged if (r.locale or "").lower() == want), None)
+        or (parents[0] if parents else None)
+        or (children[0] if children else None)
+        or reps[0]
+    )
+
+
+def _declared(value: Any) -> dict[str, str]:
+    out = {"by": js_string(value.get("by"), "by" in value) if isinstance(value, dict) else "undefined"}
+    at = get(value, "at")
+    if truthy(at):
+        out["at"] = js_string(at)
+    return out
+
+
+def _date_or_none(value: Any) -> Any:
+    """A frontmatter or manifest date that parses, or None."""
+    if value is None or value == "":
+        return None
+    return None if math.isnan(timestamp(value)) else value
+
+
+def _has_actor(entry: Any) -> bool:
+    """An OKF ``generated`` or ``verified`` entry that names its actor."""
+    return isinstance(entry, dict) and entry.get("by") is not None and js_string(entry["by"]) != ""
+
+
+def citation_for(
+    result: PackageResult,
+    node: ContentNode,
+    rep: Representation,
+    now: datetime | None = None,
+    index: RelationIndex | None = None,
+    text: str | None = None,
+) -> CitationRecord:
+    """Builds one citation record."""
+    manifest = result.manifest
+    fm = rep.frontmatter
+    moca = fm["moca"] if isinstance(fm.get("moca"), (dict, list)) else {}
+    moca = moca if isinstance(moca, dict) else {}
+    key = f"{js_string(manifest.get('id'))}@{js_string(manifest.get('version'))}"
+    # Package spec §4.4: the node's window is the intersection of the package's and its own. A bound that does not
+    # parse, or a window whose end is not after its start, is ignored: it never takes a node out of force.
+    valid_from, valid_until, from_at, until_at = effective_window(
+        manifest.get("validFrom"), manifest.get("validUntil"), moca.get("valid_from"), moca.get("valid_until")
+    )
+    t = (now or datetime.now(UTC)).timestamp() * 1000
+    superseded_by = list(index[0].get(key, [])) if index else []
+    contested_by = [
+        *(moca["contested_by"] if isinstance(moca.get("contested_by"), list) else []),
+        *(index[1].get(key, []) if index else []),
+    ]
+    declared_sources = fm.get("sources")
+    sources: dict[Any, Any] = {}
+    for s in declared_sources if isinstance(declared_sources, list) else []:
+        sid = get(s, "id")
+        if truthy(sid) and isinstance(sid, (str, int, float, bool)):
+            sources[sid] = s
+
+    package: dict[str, Any] = {
+        "id": manifest.get("id"),
+        "version": manifest.get("version"),
+        "digest": result.digest,
+        "signed": len(result.signers) > 0,
+    }
+    if result.signers:
+        package["signers"] = list(result.signers)
+
+    node_part: dict[str, Any] = {
+        "id": f"{js_string(manifest.get('id'))}#{node.path}",
+        "ref": f"{key}#{node.path}",
+        "path": node.path,
+    }
+    if rep.locale:
+        node_part["locale"] = rep.locale
+    elif truthy(manifest.get("language")):
+        node_part["locale"] = manifest["language"]
+    node_part["type"] = fm.get("type")
+    if isinstance(fm.get("title"), str):
+        node_part["title"] = fm["title"]
+    if isinstance(fm.get("description"), str):
+        node_part["description"] = fm["description"]
+    if isinstance(fm.get("tags"), list):
+        node_part["tags"] = [x for x in fm["tags"] if isinstance(x, str)]
+    if rep.sha256:
+        node_part["digest"] = f"sha256:{rep.sha256}"
+
+    verified = fm.get("verified")
+    verified_list = verified if isinstance(verified, list) else [verified] if truthy(verified) else []
+    generated = fm.get("generated")
+    trust: dict[str, Any] = {
+        "status": fm["status"] if fm.get("status") in ("draft", "stable", "deprecated") else "stable",
+        # An entry with no actor (`by`) is dropped rather than reported as "undefined".
+        "generated": _declared(generated) if _has_actor(generated) else None,
+        "declaredVerified": [_declared(v) for v in verified_list if _has_actor(v)],
+        "attestedReviews": [
+            {**_review_json(r), "packageVerified": bool(result.signers)}
+            for r in result.reviews_by_file.get(rep.file, [])
+        ],
+        "reviewStatus": review_status_of(result.reviews_by_file.get(rep.file), bool(result.signers)),
+    }
+    stale_after = _date_or_none(fm.get("stale_after"))
+    if truthy(stale_after):
+        trust["staleAfter"] = js_string(stale_after)
+    if truthy(valid_from):
+        trust["validFrom"] = js_string(valid_from)
+    if truthy(valid_until):
+        trust["validUntil"] = js_string(valid_until)
+    trust["stale"] = t >= timestamp(stale_after) if truthy(stale_after) else False
+    trust["inForce"] = (from_at is None or t >= from_at.timestamp() * 1000) and (
+        until_at is None or t < until_at.timestamp() * 1000
+    )
+    trust["superseded"] = len(superseded_by) > 0
+    if superseded_by:
+        trust["supersededBy"] = superseded_by
+    trust["contested"] = len(contested_by) > 0
+    if contested_by:
+        trust["contestedBy"] = contested_by
+
+    evidence: list[dict[str, Any]] = []
+    for i, e in enumerate(moca["evidence"] if isinstance(moca.get("evidence"), list) else []):
+        if not truthy(e) or not isinstance(e, (dict, list)):
+            continue
+        source_key = get(e, "source")
+        hashable = isinstance(source_key, (str, int, float, bool))
+        if hashable and source_key in sources:
+            source = sources[source_key]
+        else:
+            source = {"id": source_key} if isinstance(e, dict) and "source" in e else {}
+        entry: dict[str, Any] = {"source": source}
+        if truthy(get(e, "selector")):
+            entry["selector"] = get(e, "selector")
+        if truthy(get(e, "note")):
+            entry["note"] = get(e, "note")
+        matched = rep.evidence_checks[i].matched if i < len(rep.evidence_checks) else None
+        if matched is not None:
+            entry["matched"] = matched
+        evidence.append(entry)
+
+    record: CitationRecord = {
+        "package": package,
+        "node": node_part,
+        "span": {"start": rep.body_offset, "end": rep.body_offset + len(utf8(rep.body))},
+        "trust": trust,
+        "evidence": evidence,
+    }
+    if rep.concepts:
+        record["concepts"] = list(rep.concepts)
+    label, invalid = audience_of(node, rep)
+    if label is not None:
+        record["audience"] = label
+    if invalid:
+        record["audienceInvalid"] = True
+    if result.profiles:
+        record["profiles"] = list(result.profiles)
+    if text is not None:
+        record["text"] = text
+    return record
+
+
+def _review_json(review: Any) -> dict[str, Any]:
+    out: dict[str, Any] = {"reviewer": review.reviewer, "reviewedAt": review.reviewed_at, "outcome": review.outcome}
+    if review.signer is not None:
+        out["signer"] = review.signer
+    if review.scope is not None:
+        out["scope"] = review.scope
+    return out

moca_reader/codes.py

@@ -0,0 +1,110 @@
+"""Diagnostic codes. This table mirrors Reader contract §11, which is normative: codes are the contract,
+message prose is not. A change here without the matching spec change is a bug."""
+
+from __future__ import annotations
+
+ERROR = "error"
+WARNING = "warning"
+INFO = "info"
+
+CODES: dict[str, tuple[str, str]] = {
+    "T001_TARGET_NOT_FOUND": (ERROR, "The target does not exist."),
+    "T002_MANIFEST_NOT_FOUND": (ERROR, "The target exists but has no moca.json at its root."),
+    "T003_ARCHIVE_REJECTED": (ERROR, "An archive or host source broke a safety rule or limit."),
+    "P001_UNSUPPORTED_ENTRY": (ERROR, "The package contains a symbolic link or other non-regular file."),
+    "P002_UNREADABLE_ENTRY": (ERROR, "A package entry could not be read."),
+    "P003_PATH_COLLISION": (ERROR, "Two package paths are equal after Unicode NFC normalisation or case folding."),
+    "M001_MANIFEST_INVALID_JSON": (ERROR, "moca.json is not valid UTF-8 JSON."),
+    "M002_MANIFEST_SCHEMA": (ERROR, "moca.json does not validate against the manifest schema."),
+    "M003_NO_CONTENT": (ERROR, "The package has neither a content node nor a member."),
+    "M004_UNKNOWN_KEY": (
+        INFO,
+        "A top-level manifest key is neither defined by the spec nor a vendor x-<vendor>-<key> key.",
+    ),
+    "M005_DUPLICATE_MEMBER": (ERROR, "The same member id appears more than once."),
+    "M006_VALIDITY_WINDOW_INVALID": (WARNING, "validUntil is not later than validFrom."),
+    "M007_UNREGISTERED_URN": (INFO, "The package id uses a URN namespace that is not registered with IANA."),
+    "M008_DIGEST_V1_PACKAGE": (
+        INFO,
+        "The package was written for a mocaVersion before 0.4; digests, pins and attestations made then will not match moca-digest-v2.",
+    ),
+    "M009_MOCA_VERSION_NEWER": (
+        WARNING,
+        "The package was written for a newer mocaVersion than this Reader implements; it is read on a best-effort basis.",
+    ),
+    "C001_FRONTMATTER_MISSING": (ERROR, "A concept document has no YAML frontmatter (OKF MUST)."),
+    "C002_FRONTMATTER_INVALID": (ERROR, "Frontmatter is not parseable YAML or is not a mapping."),
+    "C003_TYPE_MISSING": (ERROR, "Frontmatter has no non-empty type (OKF MUST)."),
+    "C004_RESERVED_FILE_INVALID": (ERROR, "index.md or log.md breaks the OKF reserved-file rules."),
+    "C005_FIELD_INVALID": (WARNING, "A frontmatter field does not match the node schema."),
+    "C006_EVIDENCE_SOURCE_UNKNOWN": (WARNING, "moca.evidence names a source id that sources[] does not declare."),
+    "C007_LINK_UNRESOLVED": (WARNING, "An internal Markdown link does not resolve."),
+    "C008_UNSAFE_PATH": (ERROR, "A package-relative path is absolute or escapes the package root."),
+    "C009_LOCALE_ORPHAN": (WARNING, "A locale variant has no default-language file."),
+    "C010_VALIDITY_WINDOW_INVALID": (WARNING, "moca.valid_until is not later than moca.valid_from."),
+    "C011_EVIDENCE_SELECTOR_UNMATCHED": (
+        WARNING,
+        "An evidence selector does not match the text source file it cites inside the package.",
+    ),
+    "A001_ATTESTATION_MALFORMED": (ERROR, "An attestation file is not a parseable envelope and statement."),
+    "A002_ATTESTATION_INVALID": (ERROR, "An attestation failed verification or does not match the package."),
+    "A003_ATTESTATION_UNVERIFIABLE": (
+        WARNING,
+        "An attestation could not be checked because no trust root was supplied.",
+    ),
+    "A004_ATTESTATION_INDETERMINATE": (WARNING, "Online verification was requested but could not complete."),
+    "A006_REVIEW_OUTDATED": (
+        WARNING,
+        "A review attestation covers a file whose bytes have since changed or been removed.",
+    ),
+    "A007_REVIEW_DATE_FUTURE": (WARNING, "A review is dated later than the host clock, so it does not count."),
+    "A008_PACKAGE_DIGEST_MISMATCH": (
+        ERROR,
+        "A package attestation names this id and version with a different digest: the content changed after it was signed.",
+    ),
+    "A009_SIGNATURE_REQUIRED": (ERROR, "The host requires a valid package attestation and the package has none."),
+    "R001_MEMBER_UNRESOLVED": (WARNING, "A member could not be resolved by the host resolver."),
+    "R002_MEMBER_DIGEST_MISMATCH": (ERROR, "A resolved member does not match its pinned digest."),
+    "R003_MEMBER_CYCLE": (ERROR, "Members form a cycle."),
+    "L001_IDENTITY_CONFLICT": (
+        ERROR,
+        "A library was given a second package with the same id and version but a different digest; the second is refused.",
+    ),
+    "R004_RELATION_UNAUTHORISED": (
+        INFO,
+        "A supersedes or conflictsWith relation is not authorised by a signer of the package, so it has no effect.",
+    ),
+    "F001_PROFILE_UNRECOGNISED": (INFO, "A declared profile is not recognised by this reader."),
+    "O001_ONTOLOGY_UNPARSEABLE": (
+        WARNING,
+        "A structure or overlay file is over the size or triple limit, or is not parseable Turtle.",
+    ),
+    "O002_CONCEPT_UNDECLARED": (
+        WARNING,
+        "A concept is used in a relation or node binding but not declared as a skos:Concept.",
+    ),
+    "O003_REMOTE_REFERENCE": (
+        WARNING,
+        "An ontology file or concept binding relies on something a Reader would have to fetch or resolve.",
+    ),
+    "O005_STRUCTURE_CYCLE": (WARNING, "requires, broader or hasPart forms a cycle."),
+    "S001_SIDECAR_INVALID": (ERROR, "index.json does not validate against the sidecar schema."),
+    "S002_SIDECAR_TARGET_MISMATCH": (ERROR, "The sidecar is bound to a different package id or version."),
+    "S003_SIDECAR_STALE": (WARNING, "The sidecar digest does not match the package; the sidecar is ignored."),
+    "S004_SIDECAR_ITEM_INVALID": (ERROR, "A payload item breaks the addressing rules."),
+    "S005_SIDECAR_FORMAT_UNKNOWN": (INFO, "The payload format is not recognised; the sidecar is ignored."),
+    "S006_MODEL_MISMATCH": (WARNING, "The host's embedder does not match the index's model; dense search is refused."),
+    "S007_NO_VECTORS": (
+        WARNING,
+        "A loaded package has no vectors a dense backend can search; that package is not searched.",
+    ),
+}
+
+# Codes that are no longer emitted. Codes are never reused.
+RETIRED_CODES = ("A005_SKILLS_WITHHELD", "K001_SKILL_INVALID", "O004_STRUCTURE_VIEW_MISMATCH")
+
+
+def default_severity(code: str) -> str:
+    if code not in CODES:
+        raise KeyError(f"unknown diagnostic code {code}")
+    return CODES[code][0]

moca_reader/conformance.py

@@ -0,0 +1,249 @@
+"""moca-spec's runner protocol (conformance/README.md): one JSON object ``{root, case}`` on stdin, one JSON result
+on stdout. What this Reader concludes for one case of conformance/cases.json. It ships with the package, so the
+corpus runs against the Reader you installed. From a moca-spec checkout:
+
+    node scripts/run-conformance.mjs --reader "python -m moca_reader.conformance"
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any
+
+from . import (
+    DenseBackend,
+    HybridBackend,
+    LexicalBackend,
+    Library,
+    MemoryStoreBackend,
+    Overlay,
+    Search,
+    SearchHooks,
+    StoreScope,
+    bind_sidecar,
+    directory_resolver,
+    ontology_guided,
+    read_package,
+)
+from .state import package_state
+
+UNLOADED = "sha256:" + "0" * 64
+
+
+class ConformanceEmbedder:
+    """The identity a case names, and [1, 0, 0, ...] for every text, whatever the role."""
+
+    def __init__(self, spec: dict[str, Any]) -> None:
+        self.name = spec["name"]
+        self.version = spec.get("version")
+        self.dimensions = spec["dimensions"]
+        self.query_prefix = spec.get("queryPrefix")
+        self.document_prefix = spec.get("documentPrefix")
+
+    def embed(self, texts: list[str], role: str) -> list[list[float]]:
+        return [[1.0 if i == 0 else 0.0 for i in range(self.dimensions)] for _ in texts]
+
+
+class EveryHitBackend:
+    """Ignores every filter, declares no features, and returns every representation plus one unknown digest."""
+
+    features: tuple[str, ...] = ()
+
+    def __init__(self, library: Library) -> None:
+        self.library = library
+
+    def search(self, query: str, limit: int, filters: dict[str, Any]) -> list[dict[str, Any]]:
+        hits: list[dict[str, Any]] = []
+        for p in self.library.packages:
+            for node in p.result.nodes:
+                for rep in node.representations:
+                    hit = {
+                        "digest": p.result.digest,
+                        "node": f"{p.result.manifest['id']}#{node.path}",
+                        "path": node.path,
+                    }
+                    if rep.locale:
+                        hit["locale"] = rep.locale
+                    hits.append({**hit, "score": 1})
+        hits.append({"digest": UNLOADED, "node": "https://example.com/not-loaded#x.md", "path": "x.md", "score": 2})
+        return hits
+
+
+def hostile_hooks() -> SearchHooks:
+    """An egress hook that tries to return everything, plus a record from a package that is not loaded."""
+
+    def egress(candidates: list[dict[str, Any]], ctx: Any) -> list[dict[str, Any]]:
+        everything = ctx.library.citations(include_text=True)
+        fake = [{**everything[0], "package": {**everything[0]["package"], "digest": UNLOADED}}] if everything else []
+        return [*candidates, *everything, *fake]
+
+    return SearchHooks(egress=egress)
+
+
+def hostile_ingress_hooks() -> SearchHooks:
+    """An ingress hook that asks for more than the caller did: the gate must follow the caller."""
+    return SearchHooks(ingress=lambda query, ctx: {"includeAll": True, "limit": 1000, "locale": "fr"})
+
+
+def concept_item(x: dict[str, Any] | None) -> dict[str, Any] | None:
+    if x is None:
+        return None
+    out = {"iri": x["iri"]}
+    if "label" in x:
+        out["label"] = x["label"]
+    out["layer"] = x["layer"]
+    return out
+
+
+def actual_for(root: str, c: dict[str, Any]) -> dict[str, Any]:
+    o = c.get("options") or {}
+    read_options: dict[str, Any] = {
+        "trust_root": os.path.join(root, o["trustRoot"]) if o.get("trustRoot") else None,
+        "resolve_member": directory_resolver([os.path.join(root, m) for m in o["members"]])
+        if o.get("members")
+        else None,
+        "limits": o.get("limits"),
+        # The host clock applies to reading too: keys expire (attestations §6).
+        "clock": (lambda: datetime.fromisoformat(o["now"])) if o.get("now") else None,
+        "require_signature": o.get("requireSignature") is True,
+        "strict": o.get("strict") is True,
+    }
+    overlays = [Overlay(v["id"], v["layer"], path=os.path.join(root, v["path"])) for v in o.get("overlays") or []]
+
+    if c.get("kind") == "structure":
+        library = Library(overlays=overlays)
+        for target in c["packages"]:
+            result = read_package(os.path.join(root, target), **read_options)
+            if result.valid:
+                library.add(result)
+        s = library.structure
+        a = c.get("args") or {}
+        iri = c["iri"]
+        ops: dict[str, Callable[[], Any]] = {
+            "concept": lambda: s.concept(iri),
+            "requires": lambda: [concept_item(x) for x in s.requires(iri, transitive=a.get("transitive", False))],
+            "requiredBy": lambda: [concept_item(x) for x in s.required_by(iri)],
+            "parts": lambda: [concept_item(x) for x in s.parts(iri)],
+            "narrower": lambda: [concept_item(x) for x in s.narrower(iri, transitive=a.get("transitive", False))],
+            "broader": lambda: [concept_item(x) for x in s.broader(iri)],
+            "related": lambda: [concept_item(x) for x in s.related(iri)],
+            "sequence": lambda: None if (seq := s.sequence(iri)) is None else [concept_item(x) for x in seq],
+            "nodes": lambda: [r["node"]["ref"] for r in s.nodes(iri, include=a.get("include", "none"))],
+        }
+        return {"codes": [d.code for d in library.diagnostics.items], "result": ops[c["op"]]()}
+
+    if c.get("kind") == "search":
+        now = datetime.fromisoformat(o["now"])
+        library = Library(
+            clock=lambda: now, overlays=overlays, allow_unsigned_relations=o.get("allowUnsignedRelations") is True
+        )
+        codes: list[str] = []
+        for target in c["packages"]:
+            result = read_package(os.path.join(root, target), **read_options)
+            if not result.valid:
+                continue
+            chunks, index = None, None
+            if o.get("sidecar"):
+                bound = bind_sidecar(os.path.join(root, o["sidecar"]), result)
+                codes.extend(d.code for d in bound.diagnostics)
+                if bound.usable:
+                    chunks, index = bound.chunks, bound.index
+            library.add(result, chunks, index)
+        hooks = (
+            hostile_hooks()
+            if o.get("hooks") == "hostile"
+            else hostile_ingress_hooks()
+            if o.get("hooks") == "hostile-ingress"
+            else ontology_guided()
+            if o.get("hooks") == "ontology-guided"
+            else None
+        )
+        s = c["search"]
+        options = {
+            "limit": s.get("limit", 50),
+            "include_all": s.get("includeAll", False),
+            "locale": s.get("locale"),
+            "concepts": s.get("concepts"),
+            "scope": s.get("scope"),
+        }
+        if o.get("backend") == "store":
+            # Everything listed is ingested (each package on its own with `ingestSeparately`); only the packages
+            # in `allow` are "loaded", and the search gets their package states (contract §9.4).
+            store = MemoryStoreBackend(filter_pushdown=False)
+            if o.get("ingestSeparately"):
+                for p in library.packages:
+                    single = Library(clock=lambda: now)
+                    single.add(p.result)
+                    store.ingest(single)
+            else:
+                store.ingest(library)
+            allow = {os.path.join(root, t) for t in o.get("allow") or []}
+            allowed = [
+                package_state(p.result)
+                for p in library.packages
+                if p.result.source and p.result.source.location in allow
+            ]
+            records = Search(
+                StoreScope(allowed, lambda: now, o.get("allowUnsignedRelations") is True),
+                store,
+                audiences=o.get("audiences"),
+                allow_unlabelled=o.get("allowUnlabelled") is True,
+            ).search(s["query"], **options)
+            return {"codes": codes, "records": records}
+
+        def dense() -> DenseBackend:
+            return DenseBackend(library, ConformanceEmbedder(o["embedder"]))
+
+        backend: Any
+        if o.get("backend") == "all":
+            backend = EveryHitBackend(library)
+        elif o.get("backend") == "dense":
+            backend = dense()
+        elif o.get("backend") == "hybrid":
+            h = o.get("hybrid") or {}
+            backend = HybridBackend(LexicalBackend(library), dense(), k=h.get("k", 60), weights=h.get("weights"))
+        else:
+            backend = LexicalBackend(library)
+        codes.extend(d.code for d in getattr(backend, "diagnostics", None) or [])
+        # Library diagnostics (L): for example two digests for one id@version.
+        codes.extend(d.code for d in library.diagnostics.items if d.code.startswith("L"))
+        records = Search(
+            library,
+            backend,
+            audiences=o.get("audiences"),
+            hooks=hooks,
+            allow_unlabelled=o.get("allowUnlabelled") is True,
+        ).search(s["query"], **options)
+        return {"codes": codes, "records": records}
+
+    result = read_package(os.path.join(root, c["target"]), **read_options)
+    codes = [d.code for d in result.diagnostics]
+    sidecar_usable = None
+    if o.get("sidecar"):
+        bound = bind_sidecar(os.path.join(root, o["sidecar"]), result)
+        codes.extend(d.code for d in bound.diagnostics)
+        sidecar_usable = bound.usable
+    evidence_matched: dict[str, list[Any]] = {}
+    if result.valid:
+        for r in Library().add(result).citations():
+            if r["evidence"]:
+                evidence_matched[r["node"]["path"]] = [e.get("matched") for e in r["evidence"]]
+    out: dict[str, Any] = {
+        "valid": result.valid,
+        "codes": codes,
+        "capabilities": result.capabilities,
+        "digest": result.digest,
+        "evidenceMatched": evidence_matched,
+    }
+    if sidecar_usable is not None:
+        out["sidecarUsable"] = sidecar_usable
+    return out
+
+
+if __name__ == "__main__":
+    request = json.loads(sys.stdin.read())
+    sys.stdout.write(json.dumps(actual_for(request["root"], request["case"]), ensure_ascii=False))