foundry-testing-actor 0.1.0__py3-none-any.whl

foundry_testing_actor/config.py

@@ -0,0 +1,525 @@
+"""`CapabilityConfig` — one capability id and one testing repo, every other rendering derived.
+
+WHY THIS FILE EXISTS. The hand-written testing actor this package replaces spelled its capability
+in more places than its implementation sibling ever did: the dotted id, its own `<owner>/<repo>`,
+the implementation repo it read from, the knowledge registry, the registry path with `CAP` dropped,
+the test image name, the image name of the component under test, three tempdir prefixes, the git
+`user.name` and `user.email`, and the write boundary — once in the sidecar and once more in the
+module that enforced it. Every one of those was correct only for as long as someone remembered to
+change all of them together.
+
+They are now derivations of two fields. Nothing in this package spells a capability.
+
+    capability            ACME.PARTS.CAP.SUP.007.WID                   ← the only id anyone writes
+    source_repo           <owner>/ACME.PARTS.CAP.SUP.007.WID-testing   ← and the only repo
+
+    implementation_repo   <owner>/<capability>-implementation  (declared only when it differs)
+    actor_name            <repo half of source_repo>
+    actor_slug            same, lowercased, dots to hyphens
+    git_author_name       actor_name
+    git_author_email      {actor_slug}@users.noreply.github.com
+    clone_prefix(t)       {actor_slug}-{t}-
+    code_clone_prefix(t)  {actor_slug}-code-{t}-
+    capability_path       the id lowercased, split AT its `cap` segment: head / tail
+    test_image_name(c)    {capability lowercased}-{c}-tests
+    test_image_ref(r,c,v) {r}/{capability_path}/{c}/tests:{v}
+    image_name(c)         {capability lowercased}-{c}          ← what implementation versions
+    image_ref(r,c,v)      {r}/{capability_path}/{c}:{v}        ← what implementation published
+
+THE IMAGE REFS ARE A THREE-WAY CONTRACT. `image_ref` must stay byte-identical to what the
+implementation actor publishes, because this actor recomputes it rather than being told it — and
+`test_image_ref` is what the orchestrating actor parses back apart to run. A component's tests are
+a CHILD path of the component (`<component>/tests`), not a `-tests` sibling: unambiguous, and it
+makes retention one rule. Both are derivation output or nothing; no tag scheme is invented here.
+`test_the_image_refs_are_the_three_way_contract` in the test suite is what pins them.
+
+WHAT IS DERIVED AND WHAT IS DECLARED. Anything recoverable from the id or the repo is derived.
+Anything genuinely additional — which components exist, where each one's tests live, which runner
+builds them, what grounds the session — is declared in the sidecar, once. The write boundary in
+particular is `components[].tests` and nothing else: it used to be declared in the sidecar AND
+hardcoded in the module that actually enforced it, which is how a write boundary comes to be stated
+twice and eventually stated differently.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib import metadata
+from pathlib import Path
+
+import yaml
+
+CONTRACT = "foundry-testing-actor/agentic-context/v1"
+SIDECAR = "actor-agentic-context.yaml"
+
+_SCHEMA_PATH = Path(__file__).resolve().parent / "schemas" / "agentic-context.schema.yaml"
+_CARDS_PATH = Path(__file__).resolve().parent / "cards"
+_RUNNER_PATH = Path(__file__).resolve().parent / "runner"
+
+# The segment a capability id carries to say "capability". It is dropped from the registry path
+# because the path position already says it — every other token of the id survives, across
+# segments rather than concatenated.
+_CAPABILITY_SEGMENT = "cap"
+
+# The suffix the implementation repo carries when it is not declared. The same `<id>-<kind>`
+# naming that makes this repo `<id>-testing` (ADR-ECO-0022) — so a use that follows the
+# convention never writes the field at all, and one that does not says so in one line.
+_IMPLEMENTATION_SUFFIX = "-implementation"
+
+# What an unsubstituted placeholder looks like: a bare lowercase word in braces, and nothing else.
+# Narrow on purpose — see `CapabilityConfig.expand`.
+_PLACEHOLDER = re.compile(r"\{([a-z_]+)\}")
+
+
+def version() -> str:
+    """This package's own version, as installed.
+
+    Read from the installed distribution rather than written down a second time here: a literal in
+    the source and a version in `pyproject.toml` are two facts that can disagree, and the one a
+    rendered card would carry is the one nobody checks. In a source checkout with nothing
+    installed there is no distribution to ask, and `unknown` is the honest answer — a banner is
+    provenance, not a gate, and no behaviour turns on it.
+    """
+    try:
+        return metadata.version("foundry-testing-actor")
+    except metadata.PackageNotFoundError:
+        return "unknown"
+
+
+def cards_path() -> Path:
+    """The folder holding this actor's own four cards — its definition, shipped in the wheel.
+
+    The cards say what a foundry testing actor IS: its data dictionary, its message catalog, and
+    the two doors it answers. They name no capability, because which capability an instance serves
+    is not part of what the actor is — that is the sidecar, supplied per use.
+
+    This path is what `render-cards` renders a use from, and what
+    `papeete-actor-synchronous-messaging lint-card` is pointed at to check that the `-actor` suffix
+    in this package's name is a claim it actually honours (ADR-ECO-0022).
+    """
+    return _CARDS_PATH
+
+
+def runner_path() -> Path:
+    """The folder holding the default test-runner Dockerfile, shipped in the wheel.
+
+    `buildctl --local dockerfile=` takes a directory on the machine running `buildctl`, not a path
+    inside the build context — so a runner that ships with the actor is addressable exactly as one
+    committed in the testing repo is, with no copy step. A component that declares no `runner:` is
+    built with this one (see the schema for why that is the default rather than a requirement).
+    """
+    return _RUNNER_PATH
+
+
+def load_schema() -> dict:
+    """The contract, as committed source inside this package.
+
+    The path is the same in a source checkout and in an installed wheel, so there is no fallback
+    and no second location to reason about. A wheel that lost it is a gate with nothing to
+    enforce, which is worth failing loudly over rather than degrading past.
+    """
+    if not _SCHEMA_PATH.exists():
+        raise FileNotFoundError(
+            f"{_SCHEMA_PATH.name} not found in {_SCHEMA_PATH.parent}.\n"
+            "  The contract is committed source in this package, so this should be unreachable.\n"
+            "  In a source checkout: the file was deleted — restore it from git.\n"
+            "  In an installed wheel: the build shipped without its contract. Report it against "
+            "the release."
+        )
+    return yaml.safe_load(_SCHEMA_PATH.read_text())
+
+
+class ConfigError(ValueError):
+    """The sidecar is unusable — missing, malformed, or internally inconsistent."""
+
+
+@dataclass(frozen=True)
+class Component:
+    """One component this actor writes tests for and publishes a test image of."""
+
+    name: str
+    tests: str
+    runner: str | None = None     # None: the runner this package ships (`runner_path()`)
+
+
+@dataclass(frozen=True)
+class Grounding:
+    """One knowledge source the session is grounded in before its first turn."""
+
+    name: str
+    answers: str
+    fetch: tuple[str, ...]
+    into: str
+    load: str
+
+    @property
+    def eager(self) -> bool:
+        return self.load == "eager"
+
+
+@dataclass(frozen=True)
+class CapabilityConfig:
+    """Everything this actor needs to know about the capability it serves."""
+
+    capability: str
+    source_repo: str
+    registry_repo: str
+    engine: str
+    components: tuple[Component, ...]
+    ground_in: tuple[Grounding, ...]
+    # None: derived — see `implementation_repo`. Kept as the DECLARED value so `show` can say
+    # which of the two it is.
+    declared_implementation_repo: str | None = None
+
+    # ── loading ─────────────────────────────────────────────────────────────────────────────
+
+    @classmethod
+    def load(cls, folder: str | Path = ".") -> CapabilityConfig:
+        """Read the sidecar from `folder` (or from the file itself, if a file is given).
+
+        Raises `ConfigError` for anything that would otherwise surface much later — a missing
+        file, a contract this package does not implement, an absent required key, a component
+        whose `tests` root does not end in `/`. Every one of those is cheaper here than
+        mid-session.
+        """
+        path = Path(folder)
+        if path.is_dir():
+            path = path / SIDECAR
+        try:
+            raw = yaml.safe_load(path.read_text())
+        except OSError as e:
+            raise ConfigError(f"{path}: cannot be read: {e}") from e
+        except yaml.YAMLError as e:
+            raise ConfigError(f"{path}: does not parse: {e}") from e
+        return cls.from_dict(raw, source=str(path))
+
+    @classmethod
+    def from_dict(cls, raw: object, *, source: str = "<dict>") -> CapabilityConfig:
+        if not isinstance(raw, dict):
+            raise ConfigError(f"{source}: not a mapping")
+        if raw.get("context") != CONTRACT:
+            raise ConfigError(
+                f"{source}: declares context '{raw.get('context')}', not {CONTRACT}"
+            )
+
+        for key in load_schema()["required"]:
+            if key not in raw:
+                raise ConfigError(f"{source}: missing required key '{key}'")
+
+        components = tuple(_component(entry, source, i)
+                           for i, entry in enumerate(raw["components"] or ()))
+        if not components:
+            raise ConfigError(f"{source}: `components` is empty — nothing this actor may write to")
+        names = [c.name for c in components]
+        duplicates = sorted({n for n in names if names.count(n) > 1})
+        if duplicates:
+            # A caller names components by name at both doors. Two entries answering to one name
+            # would make "which tests root" a question with two answers.
+            raise ConfigError(f"{source}: component name(s) declared twice: {duplicates}")
+
+        ground_in = tuple(_grounding(entry, source, i)
+                          for i, entry in enumerate(raw["ground_in"] or ()))
+
+        implementation_repo = raw.get("implementation_repo")
+        config = cls(
+            capability=str(raw["capability"]),
+            source_repo=str(raw["source_repo"]),
+            registry_repo=str(raw["registry_repo"]),
+            engine=str(raw["engine"]),
+            components=components,
+            ground_in=ground_in,
+            declared_implementation_repo=(str(implementation_repo)
+                                          if implementation_repo else None),
+        )
+        # Force the derivations that can fail, here rather than at the first request that needs
+        # one. A capability id with no `cap` segment is a typo, and it should not survive startup.
+        _ = config.capability_path, config.actor_name, config.implementation_repo
+        return config
+
+    # ── the derived renderings ──────────────────────────────────────────────────────────────
+
+    @property
+    def actor_name(self) -> str:
+        """The repo half of `source_repo` — this actor's own name, and its git author name."""
+        return _split_repo(self.source_repo, "source_repo")[1]
+
+    @property
+    def actor_slug(self) -> str:
+        """The actor name as a path/address-safe token: lowercased, dots to hyphens."""
+        return self.actor_name.lower().replace(".", "-")
+
+    @property
+    def implementation_repo(self) -> str:
+        """`<owner>/<repo>` of the repository the implementation actor pushes to.
+
+        Declared when it differs; otherwise the same owner as `source_repo`, and the repo named
+        `<capability>-implementation` — the convention that already names this repo
+        `<capability>-testing`. Read, never written: this actor clones it and pushes nothing back.
+        """
+        if self.declared_implementation_repo:
+            _split_repo(self.declared_implementation_repo, "implementation_repo")
+            return self.declared_implementation_repo
+        owner, _ = _split_repo(self.source_repo, "source_repo")
+        return f"{owner}/{self.capability}{_IMPLEMENTATION_SUFFIX}"
+
+    @property
+    def git_author_name(self) -> str:
+        return self.actor_name
+
+    @property
+    def git_author_email(self) -> str:
+        return f"{self.actor_slug}@users.noreply.github.com"
+
+    def clone_prefix(self, task_id: str) -> str:
+        """`tempfile.mkdtemp` prefix for one task's private clone of the testing repo."""
+        return f"{self.actor_slug}-{task_id}-"
+
+    def code_clone_prefix(self, task_id: str) -> str:
+        """`tempfile.mkdtemp` prefix for one task's read-only clone of the implementation repo."""
+        return f"{self.actor_slug}-code-{task_id}-"
+
+    @property
+    def capability_path(self) -> str:
+        """The registry path form: the id lowercased and split AT its `cap` segment.
+
+        `<ENT>.<DOMAIN>.CAP.<TYPE>.<NNN>.<CODE>` becomes `<ent>.<domain>/<type>.<nnn>.<code>`.
+        `CAP` itself is dropped — the path position already says "capability". Nothing else is
+        shortened or abbreviated: every remaining token survives, across segments rather than
+        concatenated.
+        """
+        segments = self.capability.lower().split(".")
+        if _CAPABILITY_SEGMENT not in segments:
+            raise ConfigError(
+                f"capability '{self.capability}' has no '{_CAPABILITY_SEGMENT.upper()}' segment — "
+                "the registry path is derived by splitting the id there, so an id without one "
+                "cannot be placed"
+            )
+        cut = segments.index(_CAPABILITY_SEGMENT)
+        head, tail = segments[:cut], segments[cut + 1:]
+        if not head or not tail:
+            raise ConfigError(
+                f"capability '{self.capability}': nothing on "
+                f"{'the left of' if not head else 'the right of'} its "
+                f"'{_CAPABILITY_SEGMENT.upper()}' segment"
+            )
+        return f"{'.'.join(head)}/{'.'.join(tail)}"
+
+    def image_name(self, component: str) -> str:
+        """The name `papeete_version.compute` versions the COMPONENT UNDER TEST under.
+
+        The implementation actor's own derivation, recomputed rather than asked for. A divergence
+        does not raise — it silently names an image that was never built.
+        """
+        return f"{self.capability.lower()}-{component}"
+
+    def image_ref(self, registry: str, component: str, version: str) -> str:
+        """The ref the implementation actor published. A three-way contract — see the docstring."""
+        return f"{registry.rstrip('/')}/{self.capability_path}/{component}:{version}"
+
+    def test_image_name(self, component: str) -> str:
+        """The name `papeete_version.compute` versions this component's TEST image under."""
+        return f"{self.capability.lower()}-{component}-tests"
+
+    def test_image_ref(self, registry: str, component: str, version: str) -> str:
+        """The test image this actor publishes. A three-way contract — see the docstring."""
+        return f"{registry.rstrip('/')}/{self.capability_path}/{component}/tests:{version}"
+
+    # ── components ──────────────────────────────────────────────────────────────────────────
+
+    @property
+    def writes_only_under(self) -> tuple[str, ...]:
+        """The write boundary: the union of the components' own tests roots, and nothing else."""
+        return tuple(c.tests for c in self.components)
+
+    def component(self, name: str) -> Component | None:
+        """The declared component answering to `name`, or None."""
+        return next((c for c in self.components if c.name == name), None)
+
+    def component_for(self, path: str) -> Component | None:
+        """The component a repo-relative path belongs to, by LONGEST matching tests root.
+
+        Not the path's first segment. That shortcut is correct only while every tests root sits
+        one segment under a folder named after its component, and silently reports the wrong
+        component the day one of them is `src/gateway/tests/`.
+        """
+        matches = [c for c in self.components if path.startswith(c.tests)]
+        return max(matches, key=lambda c: len(c.tests)) if matches else None
+
+    def components_for(self, paths: list[str]) -> list[str]:
+        """The names of the components a set of staged paths touched, sorted."""
+        names = set()
+        for path in paths:
+            component = self.component_for(path)
+            if component is not None:
+                names.add(component.name)
+        return sorted(names)
+
+    # ── grounding ───────────────────────────────────────────────────────────────────────────
+
+    def expand(self, argv: tuple[str, ...] | list[str]) -> list[str]:
+        """Substitute this capability's own fields into a `ground_in` entry's `fetch:` argv.
+
+        LITERAL REPLACEMENT, NOT `str.format`. A fetch argv is somebody else's command line, and
+        braces are ordinary characters in one — a jq filter or a JSON literal passed as an
+        argument would raise or, worse, be silently mangled by `format`. Only the names below are
+        substituted; every other brace passes through untouched.
+
+        A leftover `{bare_word}` IS still refused, because that is what a typo'd placeholder looks
+        like and passing it through would hand a knowledge tool a literal `{registryrepo}` to fail
+        on somewhere far from here. The pattern is deliberately narrow (lowercase and underscores
+        only) so a real brace-bearing argument does not trip it.
+        """
+        values = {
+            "capability": self.capability,
+            "implementation_repo": self.implementation_repo,
+            "registry_repo": self.registry_repo,
+            "source_repo": self.source_repo,
+        }
+        out = []
+        for arg in argv:
+            rendered = arg
+            for key, value in values.items():
+                rendered = rendered.replace("{" + key + "}", value)
+            leftover = _PLACEHOLDER.search(rendered)
+            if leftover:
+                raise ConfigError(
+                    f"fetch argument {arg!r} names a placeholder this config cannot supply "
+                    f"({leftover.group(0)}); available: "
+                    + ", ".join("{" + k + "}" for k in sorted(values))
+                )
+            out.append(rendered)
+        return out
+
+
+def _split_repo(value: str, field: str) -> tuple[str, str]:
+    owner, _, repo = value.partition("/")
+    if not owner or not repo or "/" in repo:
+        raise ConfigError(f"{field} '{value}' is not '<owner>/<repo>'")
+    return owner, repo
+
+
+def _relative_inside(value: str) -> bool:
+    return not value.startswith("/") and ".." not in Path(value).parts
+
+
+def _component(entry: object, source: str, index: int) -> Component:
+    where = f"{source}: components[{index}]"
+    if not isinstance(entry, dict):
+        raise ConfigError(f"{where}: not a mapping")
+    # The one copy of this list. `load_schema()` states the same fact for a reader, and this reads
+    # it from there rather than restating it — FIA carried a hardcoded tuple beside its schema's
+    # `items.required`, which is the shape a boundary stated twice takes (ADR-FIA-0002).
+    for key in load_schema()["fields"]["components"]["items"]["required"]:
+        if not entry.get(key):
+            raise ConfigError(f"{where}: missing required key '{key}'")
+    tests = str(entry["tests"])
+    if not tests.endswith("/"):
+        # Containment is a `startswith` test. Without the trailing slash, a root at
+        # `backend/tests` would also claim `backend/tests_scratch.py`.
+        raise ConfigError(
+            f"{where}: tests '{tests}' must end in '/' — it is matched as a string prefix, and "
+            f"without the slash it would also match a sibling whose name merely starts with it"
+        )
+    if not _relative_inside(tests):
+        raise ConfigError(f"{where}: tests '{tests}' must be a relative path inside the repo")
+    runner = entry.get("runner")
+    if runner is not None:
+        runner = str(runner)
+        if not runner or not _relative_inside(runner):
+            # A declared runner is a directory in the TESTING repo's clone. The default runner is
+            # not declared at all — an absolute path here would be a path on whichever machine
+            # happened to run the actor, which no sidecar can know.
+            raise ConfigError(
+                f"{where}: runner '{runner}' must be a relative directory inside the testing "
+                f"repo — omit it to use the runner this package ships"
+            )
+    return Component(name=str(entry["name"]), tests=tests, runner=runner)
+
+
+def _grounding(entry: object, source: str, index: int) -> Grounding:
+    where = f"{source}: ground_in[{index}]"
+    if not isinstance(entry, dict):
+        raise ConfigError(f"{where}: not a mapping")
+    for key in ("name", "answers", "fetch", "into", "load"):
+        if not entry.get(key):
+            raise ConfigError(f"{where}: missing required key '{key}'")
+    fetch = entry["fetch"]
+    if not isinstance(fetch, list) or not all(isinstance(a, str) for a in fetch):
+        raise ConfigError(f"{where}: `fetch` must be a list of strings (argv), not a shell string")
+    load = str(entry["load"])
+    if load not in ("eager", "on-demand"):
+        raise ConfigError(f"{where}: load '{load}' is not one of eager, on-demand")
+    into = str(entry["into"])
+    if not _relative_inside(into):
+        # `into` is written inside a clone this actor then commits from. A path that escapes it
+        # would write outside the boundary the whole containment check exists to hold.
+        raise ConfigError(f"{where}: into '{into}' must be a relative path inside the clone")
+    return Grounding(name=str(entry["name"]), answers=str(entry["answers"]),
+                     fetch=tuple(fetch), into=into, load=load)
+
+
+# ── the gate ────────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class Report:
+    """What `lint` found. Errors fail; warnings are read and not acted on."""
+
+    oks: list[str]
+    warns: list[str]
+    errors: list[str]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def lint(folder: str | Path = ".") -> Report:
+    """Validate one sidecar against `foundry-testing-actor/agentic-context/v1`.
+
+    A sidecar declaring some other `context:` is read, warned, and not checked further — the same
+    discipline papeete-actor applies to a card: UNMIGRATED is not non-conformant, and migrating is
+    the owning pair's own act.
+    """
+    path = Path(folder)
+    if path.is_dir():
+        path = path / SIDECAR
+    report = Report(oks=[], warns=[], errors=[])
+
+    if not path.exists():
+        report.errors.append(f"{path}: no such file")
+        return report
+    try:
+        raw = yaml.safe_load(path.read_text())
+    except (OSError, yaml.YAMLError) as e:
+        report.errors.append(f"{path}: does not parse or cannot be read: {e}")
+        return report
+    if not isinstance(raw, dict):
+        report.errors.append(f"{path}: not a mapping")
+        return report
+    if raw.get("context") != CONTRACT:
+        report.warns.append(
+            f"{path}: declares '{raw.get('context')}' — UNMIGRATED, not checked against {CONTRACT}"
+        )
+        return report
+
+    try:
+        config = CapabilityConfig.from_dict(raw, source=str(path))
+    except ConfigError as e:
+        report.errors.append(str(e))
+        return report
+
+    report.oks.append(f"{path} conforms to {CONTRACT}")
+    report.oks.append(f"capability     {config.capability}")
+    report.oks.append(f"actor          {config.actor_name}")
+    report.oks.append(f"tests against  {config.implementation_repo}")
+    report.oks.append(f"registry path  {config.capability_path}")
+    report.oks.append(f"writes only under  {', '.join(config.writes_only_under)}")
+    eager = [g.name for g in config.ground_in if g.eager]
+    if not eager and config.ground_in:
+        # Not an error: an actor may legitimately want everything on demand. But it is the shape
+        # that silently un-grounds a session, so it is said out loud.
+        report.warns.append(
+            f"{path}: no `load: eager` source — the session starts with only the on-demand list, "
+            f"and whether it reads any of them is its own choice"
+        )
+    return report

foundry_testing_actor/conformance.py

@@ -0,0 +1,133 @@
+"""Does this use still answer the same doors as the actor it claims to be?
+
+WHY THIS EXISTS. This package ships the actor's DEFINITION — four cards under `cards/` saying what
+a foundry testing actor is. A USE is one capability's own folder, carrying those four beside
+its sidecar, named for the capability it serves.
+
+A USE DOES NOT WRITE THEM (ADR-FTA-0001, after ADR-FIA-0005). `instance.render_cards` produces
+them from the definition at `docker build` time, and cards that are generated from the thing they
+are compared against cannot disagree with it. This check remains for the copies that predate that — a use still
+carrying a hand copy, or one pinned to an older image — because those are exactly the ones that can
+be wrong, and because a gate that has become cheap to pass is not a reason to remove it.
+
+A hand copy drifts. Both folders pass `lint-card` independently — each is a conformant actor — and
+neither gate has any opinion about the other. So the day the definition gains a field, renames a
+message, or changes a door's completion set, a use that was not updated keeps linting green and
+starts refusing callers at runtime, with the rejection surfacing at the door rather than here.
+
+WHAT IS COMPARED, AND WHAT IS NOT. Only what a caller can observe: the set of doors, and for each
+one its derived `request_schema`, its `completion_schema`, and the `engine` key it resolves
+through. Those derivations already fold in the data dictionary and the message catalog — a renamed
+data item, a changed type, a reference added to a message, all of it lands in the schema a caller is
+validated against — so comparing them separately would be comparing the same fact twice.
+
+PROSE IS NOT COMPARED, ON PURPOSE. A use's `means:` should name its real capability and its real
+peer actors; the definition's cannot, because it serves no capability and its cards are grepped for
+exactly such literals. The use's wording is the better one for anyone reading `describe`, and
+flattening it to the definition's would delete information. Nor is `actor.yaml`'s `name:`: that is
+the use's own identity, and it is REQUIRED to differ.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from papeete_actor_synchronous_messaging import card as pas_card
+
+from .config import Report, cards_path
+
+CARD_FILES = ("actor.yaml", "actor-data.yaml", "actor-message.yaml",
+              "actor-synchronous-messaging.yaml")
+
+# Slicing the plural gets "action" from "actions" and "querie" from "queries". These messages are
+# what a use is told to act on, so the word they name the drift with has to be a word. The bug was
+# unreachable in the sibling package until its definition declared its first query (ADR-FIA-0004),
+# which is how it survived that long; this definition has had a query from its first version.
+_NOUN = {"actions": "action", "queries": "query"}
+
+
+def check(folder: str | Path = ".") -> Report:
+    """Compare one use's cards against the definition this package ships."""
+    use = Path(folder)
+    report = Report(oks=[], warns=[], errors=[])
+
+    present = [name for name in CARD_FILES if (use / name).exists()]
+    if not present:
+        # THE NORMAL CASE, not a shortfall. A use carries a sidecar; its cards
+        # are rendered from the definition at `docker build` time, and a folder checked before that
+        # step — in a source checkout, or in this package's own gates — has none to compare. There
+        # is nothing to report against a set of cards that will be generated from the very
+        # definition this check compares against.
+        report.oks.append(
+            f"{use}: no cards to compare — they are rendered from the definition "
+            f"(`foundry-testing-actor render-cards`), so they cannot drift from it"
+        )
+        return report
+    if len(present) != len(CARD_FILES):
+        missing = [name for name in CARD_FILES if name not in present]
+        report.errors.append(
+            f"{use}: an incomplete card set — missing {', '.join(missing)}. `Actor.from_card` "
+            f"opens exactly these four and never globs, so a use missing one does not boot."
+        )
+        return report
+
+    definition = cards_path()
+    if any(not (definition / name).exists() for name in CARD_FILES):
+        # A wheel that lost its cards. `lint-card` in CI and in the release workflow exists to stop
+        # that reaching PyPI; this turns the leftover case into a report rather than a traceback
+        # from inside a gate a consumer is running.
+        report.errors.append(
+            f"{definition}: this package's own cards are missing, so there is nothing to compare "
+            f"against. The build shipped without them — report it against the release."
+        )
+        return report
+
+    try:
+        theirs = pas_card.load(use)
+    except ValueError as e:
+        report.errors.append(f"{use}: its own cards do not pass the restriction, so they cannot "
+                             f"be compared: {e}")
+        return report
+    ours = pas_card.load(definition)
+
+    report.errors.extend(_compare(ours, theirs, "actions", use))
+    report.errors.extend(_compare(ours, theirs, "queries", use))
+    if not report.errors:
+        doors = ", ".join(sorted(theirs.actions) + sorted(theirs.queries))
+        report.oks.append(f"{use} answers the definition's doors, unchanged: {doors}")
+    return report
+
+
+def _compare(ours, theirs, kind: str, use: Path) -> list[str]:
+    """The differences in one door family, as messages. Empty means they agree."""
+    defined, used = getattr(ours, kind), getattr(theirs, kind)
+    noun = _NOUN[kind]
+    errors = []
+
+    for extra in sorted(set(used) - set(defined)):
+        errors.append(f"{use}: {noun} '{extra}' is not a door the definition declares — a use "
+                      f"answers the actor's doors, it does not add its own")
+    for absent in sorted(set(defined) - set(used)):
+        errors.append(f"{use}: {noun} '{absent}' is missing — the definition declares it, so a "
+                      f"caller addressing this actor may send it")
+
+    for door in sorted(set(defined) & set(used)):
+        mine, yours = defined[door], used[door]
+        if mine.request_schema != yours.request_schema:
+            errors.append(
+                f"{use}: {noun} '{door}' accepts a different payload than the definition. "
+                f"Its `door_schema` message and the data items that message references are what "
+                f"derive this, so one of the two drifted:\n"
+                f"      definition {mine.request_schema}\n"
+                f"      this use   {yours.request_schema}")
+        if mine.completion_schema != yours.completion_schema:
+            errors.append(
+                f"{use}: {noun} '{door}' replies against a different completion set than the "
+                f"definition:\n"
+                f"      definition {mine.completion_schema}\n"
+                f"      this use   {yours.completion_schema}")
+        if mine.engine != yours.engine:
+            errors.append(
+                f"{use}: {noun} '{door}' resolves through engine '{yours.engine}', the "
+                f"definition through '{mine.engine}' — the entrypoint registers the engine under "
+                f"the sidecar's `engine:` key, so these three must agree")
+    return errors