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

foundry_testing_actor/grounding.py

@@ -0,0 +1,206 @@
+"""Grounding — putting the capability's own context in front of the session before turn one.
+
+THE MECHANISM, AND WHY IT IS THIS ONE. `CLAUDE.md` at the working directory's root is loaded by
+the `claude` CLI **before the first turn**, and its `@relative/path.md` imports are resolved
+eagerly at the same moment. Verified live in this actor's exact invocation shape (`--print
+--output-format stream-json --permission-mode acceptEdits`): a question only the fetched context
+could answer came back in `num_turns: 1` with zero tool calls. Nothing was read, because nothing
+needed to be — it was already in the window.
+
+WHAT THIS REPLACES. The previous arrangement fetched the same envelopes into a tempdir **beside**
+the clone and asked the session, in prose, to "read it before you start". That is not broken —
+reads outside the cwd work and no permission denial was ever recorded — but it is *advisory*.
+Whether the context entered the window at all was the model's choice, re-made every session, and
+a session that skipped it looked exactly like one that had read it. Writing the envelopes inside
+the clone and naming them from a generated `CLAUDE.md` turns grounding from a request into a
+precondition.
+
+WHY INSIDE THE CLONE, SPECIFICALLY. A `@`-import resolves relative to the file that contains it.
+An envelope in a sibling tempdir can be *described* to a session but never imported by one, so
+the sibling-tempdir arrangement could not have been fixed by writing a better prompt.
+
+TWO TIERS, AND WHY THE CHOICE IS A MEASUREMENT. `load: eager` costs its full token weight on
+every session, unconditionally, whether or not the task touches what it describes. `load:
+on-demand` costs one line — its `answers:` and its path — and the session pays the rest only if
+it opens the file. Neither is the right default in general; the right one for a given source is
+whatever its measured envelope size says. One such read was already recorded as putting "40 kB of
+JSON on screen", so this is not a hypothetical budget.
+
+CONTAINMENT IS UNAFFECTED. The handler stages only `components[].tests`, so everything written
+here — the `.foundry/` envelopes and the generated `CLAUDE.md` alike — is never staged, never
+committed, and dies with the clone. No `.gitignore` entry is needed, and adding one would be a
+second place to state a boundary that is already stated once.
+
+BOTH DOORS GROUND IDENTICALLY, INTO THE TESTING CLONE. The session's working directory is always
+this actor's own clone — `propose-acceptance` reads the implementation repo beside it, but the
+standing context is the capability's, not either repo's, and a proposal needs exactly the context
+the tests it proposes will later be written from.
+
+MOVED FROM `foundry-implementation-actor` (ADR-FTA-0001), below the docstring changed only in the
+marker's name and the word the boundary is stated with. The two are copies by decision, not a
+shared kit: generic across capabilities, not across actor kinds.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from papeete_actor_synchronous_messaging.engine import EngineError
+
+from .config import CapabilityConfig, Grounding
+
+CLAUDE_MD = "CLAUDE.md"
+
+DEFAULT_FETCH_TIMEOUT_S = 120
+
+# The marker that lets a generated block be told apart from prose a repo wrote for itself. It is
+# not parsed — nothing here ever edits a previous block, because every clone is fresh — but a
+# human reading a session's clone should be able to see instantly which half is machine-written.
+_BEGIN = "<!-- foundry-testing-actor: generated grounding -->"
+
+
+def ground(config: CapabilityConfig, clone_dir: Path, *,
+           timeout: int = DEFAULT_FETCH_TIMEOUT_S) -> list[Grounding]:
+    """Fetch every `ground_in` source, write it into the clone, and render `CLAUDE.md`.
+
+    Returns the entries that were grounded, in declaration order. Raises `EngineError` if any
+    fetch fails — a session grounded in half its context is worse than one that never started,
+    because only the second is visible.
+    """
+    for entry in config.ground_in:
+        envelope = fetch(config, entry, timeout=timeout)
+        write_envelope(config, entry, clone_dir, envelope)
+    render_claude_md(config, clone_dir)
+    return list(config.ground_in)
+
+
+def fetch(config: CapabilityConfig, entry: Grounding, *,
+          timeout: int = DEFAULT_FETCH_TIMEOUT_S) -> str:
+    """Run one entry's `fetch:` argv and return its stdout.
+
+    This package knows no knowledge tool by name. It knows "run this, ground the session in what
+    comes back" — which is why a fourth source is a YAML entry rather than a change here.
+    """
+    argv = config.expand(entry.fetch)
+    try:
+        result = subprocess.run(argv, capture_output=True, text=True, timeout=timeout)
+    except FileNotFoundError as e:
+        raise EngineError(
+            f"grounding '{entry.name}': '{argv[0]}' is not on PATH. The sidecar names the tools "
+            f"this capability grounds itself in; installing them is the consuming image's job, "
+            f"not this package's."
+        ) from e
+    except subprocess.TimeoutExpired as e:
+        raise EngineError(
+            f"grounding '{entry.name}': {' '.join(argv)} timed out after {timeout}s"
+        ) from e
+    if result.returncode != 0:
+        raise EngineError(
+            f"grounding '{entry.name}': {' '.join(argv)} failed: {result.stderr.strip()}"
+        )
+    return result.stdout
+
+
+def write_envelope(config: CapabilityConfig, entry: Grounding, clone_dir: Path,
+                   envelope: str) -> Path:
+    """Write one fetched envelope into the clone, as Markdown wrapping the raw payload.
+
+    Markdown rather than the bare `.json` the previous arrangement wrote, for one reason: a
+    `CLAUDE.md` `@`-import pulls in a file whole, so the file has to carry its own title and its
+    own "what this answers" line, or the session receives a wall of JSON with no idea which
+    question it settles. The payload itself is untouched inside the fence.
+    """
+    destination = clone_dir / entry.into
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(
+        f"# {entry.name}\n\n"
+        f"{entry.answers}\n\n"
+        f"Fetched fresh for this session by `{' '.join(config.expand(entry.fetch))}`. Read it as "
+        f"given — it is this capability's own standing context, not something to re-derive.\n\n"
+        f"```json\n{_pretty(envelope)}\n```\n"
+    )
+    return destination
+
+
+def render_claude_md(config: CapabilityConfig, clone_dir: Path) -> Path:
+    """Write the clone's `CLAUDE.md`, or append to one the repo already commits.
+
+    APPEND, NEVER OVERWRITE. The capability repo has no `CLAUDE.md` of its own today, which is
+    exactly why this is safe to introduce now — there is nothing to clobber, so the clean-slate
+    case is the one being exercised. The day one is committed, it is the repo's own standing
+    guidance for anyone working in it, and silently replacing it with a generated block would
+    remove the very thing a session most needs to obey.
+    """
+    body = _claude_md_body(config)
+    path = clone_dir / CLAUDE_MD
+    if path.exists():
+        existing = path.read_text().rstrip("\n")
+        path.write_text(f"{existing}\n\n---\n\n{body}")
+    else:
+        path.write_text(body)
+    return path
+
+
+def _claude_md_body(config: CapabilityConfig) -> str:
+    eager = [g for g in config.ground_in if g.eager]
+    on_demand = [g for g in config.ground_in if not g.eager]
+
+    lines = [
+        _BEGIN,
+        "",
+        f"# {config.capability} — context for this session",
+        "",
+        "You are working inside a private clone made for one task. The context below was fetched "
+        "fresh for this session from this capability's own knowledge registry. It is authoritative: "
+        "read it as given rather than re-deriving what it already answers.",
+        "",
+    ]
+
+    if eager:
+        lines += ["## Standing context", ""]
+        for entry in eager:
+            lines.append(f"{entry.answers}:")
+            lines.append("")
+            lines.append(f"@{entry.into}")
+            lines.append("")
+
+    if on_demand:
+        lines += [
+            "## Available on demand",
+            "",
+            "Not loaded. Open the file if the task needs what it answers.",
+            "",
+        ]
+        for entry in on_demand:
+            lines.append(f"- **{entry.name}** — {entry.answers}. `{entry.into}`")
+        lines.append("")
+
+    lines += [
+        "## Boundaries",
+        "",
+        f"Write ONLY under {_join(config.writes_only_under)}. Nothing else in this clone is yours "
+        f"to change, and a staged path outside those roots is refused rather than committed.",
+        "",
+        "Do not `git add`, `git commit`, or `git push` — that is handled outside this session.",
+        "",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def _pretty(envelope: str) -> str:
+    """Pretty-print a JSON envelope; pass anything else through untouched.
+
+    The fetch contract is "whatever the tool prints", not "JSON" — a source that emits Markdown or
+    plain text is equally groundable, and reformatting is a convenience for the JSON case, never a
+    requirement placed on the tool.
+    """
+    text = envelope.strip()
+    try:
+        return json.dumps(json.loads(text), indent=2, ensure_ascii=False)
+    except (json.JSONDecodeError, ValueError):
+        return text
+
+
+def _join(items) -> str:
+    return ", ".join(items)

foundry_testing_actor/handler.py

@@ -0,0 +1,248 @@
+"""`test_task` — the deterministic, auditable half of the `test-task` door.
+
+`ClaudeCodeTesterEngine.judge()` embodies the creative decision: what black-box pytest to write or
+extend, grounded in the caller's own payload, the agreed acceptance surface, and the capability's
+own standing context. Everything here is mechanical and never trusted to the engine's own
+judgement:
+
+- **Containment.** `git add <tests root>` for each declared component — never `-A`, never a bare
+  `.` — then assert every `git diff --cached --name-only` path starts with one of those roots.
+  This check, not the session's own write-boundary instruction, is what actually enforces the
+  write boundary. A staged path outside it is refused rather than committed.
+- **The correlation id.** `TASK-NNN` is threaded through the branch name (from the engine), the
+  commit message, and — via `correlation.py`, bound at the top of this door — every log record
+  this actor emits for the request, alongside the trace id its caller propagated.
+- **Publishing.** For each component the commit actually touched, this actor builds a small
+  test-runner image in the cluster's shared buildkit and pushes it to the registry — the
+  component's FULL accumulated tests root as the build context (this task's increment plus every
+  prior task's), so the published image always runs the whole regression suite — named and
+  versioned by convention (`papeete_version.compute`). No Docker daemon is involved anywhere:
+  `buildctl` reaches `BUILDKIT_HOST`, which is why an actor running this can be an ordinary Pod.
+- **Never opens a PR, never renders a verdict.** This door accepts, pushes, and publishes. Running
+  the image and judging the result belongs to the orchestrating actor alone.
+
+THE BOUNDARY IS READ, NOT RESTATED. The hand-written actor this replaces kept `WRITES_ONLY_UNDER`
+as a module constant here, in sync by hand with the sidecar's own declaration of the same fact. It
+is now `config.writes_only_under`, derived from `components[].tests`. There is one source, and
+this file is not it.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from papeete_version.version import compute as compute_version
+from papeete_version.version import normalize_name
+
+from . import correlation
+from .config import CapabilityConfig, runner_path
+
+
+class HandlerError(RuntimeError):
+    """Raised for anything that stops this door short — including a containment violation.
+
+    `Actor.receive()` turns an uncaught exception from a handler into a `Refusal`
+    (`{self.name}'s own handler for '{offer.id}' failed: {e}`), which the HTTP binding replies as
+    400 — the same path an undeclared door or a schema violation already takes. A containment
+    breach is therefore refused, never silently swallowed or half-committed.
+    """
+
+
+def make_test_task(config: CapabilityConfig):
+    """Bind one capability's config to the `test-task` handler.
+
+    A factory rather than a module-level function reading `actor.engines["claude-code"]`: the
+    engine's registered name comes from the sidecar, so looking the config up through a hardcoded
+    engine key would reintroduce exactly the literal this package exists to remove.
+    """
+
+    def test_task(actor, payload: dict, from_: str, judged: dict | None = None) -> dict:
+        # Bound again here, not only in the engine's own `judge()`: a refusal path reaches this
+        # door with `judged=None`, having never entered the engine at all, and that refusal is
+        # exactly the record you want carrying a task id.
+        correlation.bind(correlation_id=correlation.correlation_id(),
+                         task_id=payload.get("task_id"), door="test-task", caller=from_)
+
+        if judged is None or not judged.get("testable"):
+            reason = (judged or {}).get("reason", "not testable")
+            correlation.event("test-task-refused", because=reason)
+            return {"accepted": False, "because": reason}
+
+        task_id = payload["task_id"]
+        clone_dir = Path(judged["clone_dir"])
+        code_clone_dir = Path(judged["code_clone_dir"]) if judged.get("code_clone_dir") else None
+        branch = judged["branch"]
+        summary = judged.get("summary", "")
+
+        try:
+            with correlation.stage("containment-commit",
+                                   writes_only_under=list(config.writes_only_under)):
+                components = _containment_commit(config, clone_dir, task_id, summary)
+            correlation.event("components-touched", components=components)
+            with correlation.stage("push-branch", branch=branch, repo=config.source_repo):
+                _push(config, clone_dir, branch, _github_token(actor, config))
+            images = []
+            for component in components:
+                with correlation.stage("publish-test-image", component=component):
+                    images.append(_publish_test_image(config, clone_dir, component, task_id))
+                    correlation.event("test-image-published", component=component,
+                                      image=images[-1])
+            return {"accepted": True, "branch": branch, "images": images}
+        finally:
+            shutil.rmtree(clone_dir, ignore_errors=True)
+            if code_clone_dir is not None:
+                shutil.rmtree(code_clone_dir, ignore_errors=True)
+
+    return test_task
+
+
+def _github_token(actor, config: CapabilityConfig) -> str:
+    engine = actor.engines.get(config.engine)
+    token = getattr(engine, "github_token", None) or os.environ.get("GITHUB_TOKEN")
+    if not token:
+        raise HandlerError("no GITHUB_TOKEN available (neither on the engine nor the environment)")
+    return token
+
+
+def _redact(text: str, secret: str) -> str:
+    return text.replace(secret, "***")
+
+
+def _run(clone_dir: Path, args: list[str], *, redact: str | None = None) -> str:
+    try:
+        result = subprocess.run(args, cwd=clone_dir, check=True, capture_output=True, text=True)
+    except subprocess.CalledProcessError as e:
+        stderr = _redact(e.stderr, redact) if redact else e.stderr
+        raise HandlerError(f"{' '.join(args[:2])} failed: {stderr}") from e
+    return result.stdout
+
+
+def _containment_commit(config: CapabilityConfig, clone_dir: Path,
+                        task_id: str, summary: str) -> list[str]:
+    boundary = config.writes_only_under
+    for path in boundary:
+        # `git add` errors hard (pathspec did not match any files) on a prefix that doesn't exist
+        # on disk AT ALL, not just one with zero changes — true the first time any task ever
+        # touches a given component's tests root, and verified live against exactly that.
+        if (clone_dir / path).exists():
+            _run(clone_dir, ["git", "add", path])
+    staged = [line for line in _run(clone_dir, ["git", "diff", "--cached", "--name-only"])
+              .splitlines() if line]
+
+    offending = [p for p in staged if not any(p.startswith(prefix) for prefix in boundary)]
+    if offending:
+        _run(clone_dir, ["git", "reset"])
+        raise HandlerError(
+            f"{task_id}: refusing to commit — staged path(s) outside "
+            f"{', '.join(boundary)}: {offending}"
+        )
+    if not staged:
+        raise HandlerError(
+            f"{task_id}: nothing staged under {', '.join(boundary)} — the session made no change "
+            f"there"
+        )
+
+    message = f"test({task_id}): tests written by {config.actor_name}\n\nTask: {task_id}"
+    if summary:
+        message += f"\n\n{summary}"
+    _run(clone_dir, [
+        "git", "-c", f"user.name={config.git_author_name}",
+        "-c", f"user.email={config.git_author_email}",
+        "commit", "-m", message,
+    ])
+
+    # Which component a staged path belongs to is resolved by LONGEST declared tests root, not by
+    # taking the path's first segment. The first-segment shortcut is correct only while every
+    # root sits directly under a folder named after its component, and reports the wrong
+    # component — silently — the day one of them does not.
+    return config.components_for(staged)
+
+
+def _push(config: CapabilityConfig, clone_dir: Path, branch: str, token: str) -> None:
+    # --force: `test/<task_id>` is rebuilt from the default branch on every attempt, so a retry's
+    # branch is a replacement for the last attempt's rather than a continuation of it.
+    push_url = f"https://x-access-token:{token}@github.com/{config.source_repo}.git"
+    _run(clone_dir, ["git", "push", "--force", push_url, f"HEAD:refs/heads/{branch}"],
+         redact=token)
+
+
+def _image_registry() -> str:
+    registry = os.environ.get("IMAGE_REGISTRY")
+    if not registry:
+        raise HandlerError(
+            "no IMAGE_REGISTRY set — this actor publishes to a registry, and refuses to build an "
+            "image nothing else could ever pull"
+        )
+    return registry.rstrip("/")
+
+
+def runner_dir(config: CapabilityConfig, clone_dir: Path, component: str) -> Path:
+    """The directory `buildctl --local dockerfile=` is pointed at for one component.
+
+    A declared `runner:` is the testing repo's own, and lives in the clone. An undeclared one is
+    the runner this package ships (`runner_path()`), which lives beside this module on whatever
+    machine runs the actor — `buildctl` reads a `--local` directory client-side, so the two are
+    addressed identically and neither needs copying anywhere.
+    """
+    declared = config.component(component)
+    if declared is None:                       # unreachable via `components_for`, cheap to hold
+        raise HandlerError(f"{component}: not a declared component of {config.capability}")
+    if declared.runner is None:
+        path = runner_path()
+        if not (path / "Dockerfile").is_file():
+            # A wheel that lost its runner. Said here rather than by `buildctl`, whose own error
+            # names a site-packages path an operator has no reason to connect to a release.
+            raise HandlerError(
+                f"{path}: the runner this package ships is missing — the build shipped without "
+                f"it. Report it against the release, or declare `runner:` for {component}."
+            )
+        return path
+    path = clone_dir / declared.runner
+    if not path.is_dir():
+        # Late failure here is expensive: the commit has already landed and the branch is already
+        # pushed. Saying which declared path is missing beats `buildctl`'s own error, which names
+        # a temp path the operator has no way to map back to the sidecar.
+        raise HandlerError(
+            f"{component}: declared runner directory '{declared.runner}' does not exist in the "
+            f"clone — the sidecar and the repo disagree"
+        )
+    return path
+
+
+def _publish_test_image(config: CapabilityConfig, clone_dir: Path,
+                        component: str, task_id: str) -> str:
+    """Build this component's test-runner image in the cluster's shared buildkit and push it —
+    versioned by convention, never an explicitly-passed tag.
+
+    No Docker daemon and no docker socket: `buildctl` talks to the buildkitd Service named by
+    `BUILDKIT_HOST`. It is pushed because the orchestrating actor runs it as a Job in an ephemeral
+    namespace, which can only reach it through a registry.
+
+    THE CONTEXT IS THE WHOLE TESTS ROOT. The component's own persistent, accumulated suite — every
+    prior task's tests plus this one's — so the published image always runs the full regression
+    suite for that component, never one task's slice.
+
+    THE REF IS A CONTRACT WITH ACTORS THIS PACKAGE NEVER SEES. The orchestrating actor parses it
+    back apart, so it is `config.test_image_ref` output or nothing. Never invent a tag scheme here.
+    """
+    declared = config.component(component)
+    dockerfile_dir = runner_dir(config, clone_dir, component)
+    context = declared.tests.rstrip("/")
+
+    version = compute_version(
+        folder=clone_dir / context,
+        name=config.test_image_name(component),
+        label="feature",
+        feature_name=normalize_name(task_id),
+    )
+    image = config.test_image_ref(_image_registry(), component, version)
+    _run(clone_dir, [
+        "buildctl", "build",
+        "--frontend", "dockerfile.v0",
+        "--local", f"context={context}",
+        "--local", f"dockerfile={dockerfile_dir}",
+        "--output", f"type=image,name={image},push=true",
+    ])
+    return image

foundry_testing_actor/instance.py

@@ -0,0 +1,129 @@
+"""Rendering one use's cards from the definition this package ships.
+
+WHAT A USE USED TO BE. A folder carrying its own copy of the actor's four cards, named for the
+capability it serves, beside the sidecar that binds it to that capability. The copy was made by
+hand, and `conformance.py` exists because a hand copy drifts: both folders pass `lint-card`
+independently, neither gate has an opinion about the other, and the day the definition gains a
+door every use in the world is silently wrong until someone edits four files in each of them.
+
+WHAT A USE IS NOW. A folder carrying a sidecar. The cards are rendered into it — at `docker build`
+time in the image this package ships, or by hand with `render-cards` anywhere else — from
+`cards_path()`, which `cards_path()`'s own docstring always said was "what a spawned instance
+would be rendered from". A gate that catches drift is strictly worse than a construction that
+cannot drift. `conformance.check` stays for the uses that still carry a copy, and for a use
+pinned to an older image; it just stops being the only thing between a stale card and a caller
+refused at a door (ADR-FIA-0005, whose construction this package copies — ADR-FTA-0001).
+
+WHAT IS RENDERED, AND WHAT IS COPIED. Three of the four cards name no capability and are copied
+byte-for-byte under a banner — the data dictionary, the message catalog, and the doors are what
+the actor IS, and a use that differed in any of them would be a different actor. Only
+`actor.yaml` is rendered, because only identity differs per use: `name:` is the `actor_name` the
+sidecar already derives, and the description says which capability this instance serves.
+
+WHAT IS DELIBERATELY LOST. The hand-written prose. A use's `means:` used to name its real peers by
+name; the rendered one says "an orchestrating actor", with no name, because the sidecar declares
+no peers. `conformance.check` already refuses to compare prose for
+exactly this reason, so nothing is checked that now fails — but a reader of `describe` gets less.
+That is the trade, and it is written down in ADR-FIA-0005 rather than discovered.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from .config import CapabilityConfig, cards_path, version
+
+# The four, in the order `papeete_actor_synchronous_messaging.card` opens them. It opens exactly
+# these and never globs, which is why a use missing one does not boot rather than booting smaller.
+CARD_FILES = ("actor.yaml", "actor-data.yaml", "actor-message.yaml",
+              "actor-synchronous-messaging.yaml")
+
+# Only identity differs per use. Everything else about the actor is the same actor.
+_RENDERED = "actor.yaml"
+
+
+def _banner(source: str = "") -> str:
+    """The comment that stops someone editing a file which is overwritten on every build."""
+    body = (
+        f"RENDERED — do not edit. `foundry-testing-actor render-cards` wrote this from the "
+        f"actor's own definition, shipped in foundry-testing-actor=={version()}{source}. "
+        f"Change it by changing the definition and taking a new version of the package, not by "
+        f"editing here: the next `docker build` discards whatever is written in this file."
+    )
+    return _wrap(body, width=98, indent="# ")
+
+
+def _render_manifest(config: CapabilityConfig, definition: Path) -> str:
+    """`actor.yaml`, the only card that differs per use.
+
+    Emitted rather than substituted-into: the definition's own header says "THIS FOLDER IS THE
+    DEFINITION, NOT A USE", which would be false the moment it were copied into one. The
+    description is the definition's own, with the capability this instance serves appended — so
+    the sentence a reader gets still comes from the definition and cannot silently diverge from it.
+    """
+    card = yaml.safe_load(definition.read_text())
+    described = " ".join(str(card["description"]).split())
+    return (
+        _banner(", named for the capability this use's sidecar declares")
+        + f"manifest: {card['manifest']}\n"
+        + f"name: {config.actor_name}\n"
+        + "description: >-\n"
+        + _wrap(f"{described} This instance serves {config.capability}, whose repository is "
+                f"{config.source_repo}.")
+    )
+
+
+def _wrap(text: str, width: int = 96, indent: str = "  ") -> str:
+    """Fold one paragraph into a YAML block scalar body.
+
+    `textwrap` would do this, and would also collapse the sentence differently across Python
+    versions' defaults for `break_on_hyphens` — a capability id is full of dots and a repo name is
+    full of hyphens, and a card that reflows between two machines is a diff nobody asked for.
+    """
+    lines: list[str] = []
+    current = ""
+    for word in text.split():
+        candidate = f"{current} {word}" if current else word
+        if current and len(indent) + len(candidate) > width:
+            lines.append(indent + current)
+            current = word
+        else:
+            current = candidate
+    if current:
+        lines.append(indent + current)
+    return "\n".join(lines) + "\n"
+
+
+def render_cards(config: CapabilityConfig, dest: str | Path) -> list[Path]:
+    """Write this actor's four cards into `dest`, named for the capability `config` serves.
+
+    Returns the paths written, in the order they were written. Overwrites: these files are build
+    output, and the banner on each one says so.
+    """
+    definition = cards_path()
+    missing = [name for name in CARD_FILES if not (definition / name).exists()]
+    if missing:
+        # A wheel that lost its cards. `lint-card` in CI and in the release workflow exists to stop
+        # that reaching a registry; this turns the leftover case into a sentence rather than a
+        # traceback from inside a `docker build` someone is watching.
+        raise FileNotFoundError(
+            f"{definition}: this package's own cards are missing ({', '.join(missing)}), so there "
+            f"is nothing to render from. The build shipped without them — report it against the "
+            f"release."
+        )
+
+    out = Path(dest)
+    out.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for name in CARD_FILES:
+        target = out / name
+        if name == _RENDERED:
+            target.write_text(_render_manifest(config, definition / name))
+        else:
+            # Byte-for-byte under a banner. Not parsed and re-emitted: a round-trip through
+            # `yaml.safe_dump` would drop every comment in the definition, and those comments are
+            # where the reasoning for each door and each data item is written down.
+            target.write_text(_banner("") + definition.joinpath(name).read_text())
+        written.append(target)
+    return written

foundry_testing_actor/runner/Dockerfile

@@ -0,0 +1,32 @@
+# The default test runner — the image this actor PUBLISHES for a component, never its own image.
+#
+# SHIPPED IN THE WHEEL, NOT IN EVERY TESTING REPO. The hand-written actor this package replaces kept
+# this file in its own repository, where it named nothing about the capability: a Python base, a
+# pytest, and a CMD. It is the contract between this actor and the orchestrating actor that runs
+# what it publishes, so it lives with the actor. A component whose sidecar entry declares no
+# `runner:` is built with this one; `buildctl --local dockerfile=` reads it straight out of the
+# installed package (see handler.py's `runner_dir`).
+#
+# Static and task-agnostic on purpose: `_publish_test_image` builds this same Dockerfile for every
+# task, pointing its build CONTEXT at that component's own persistent, accumulated tests root —
+#     buildctl build --local context=<component tests root> --local dockerfile=<this folder>
+# — every prior task's tests plus this one's, so the published image always runs the full
+# regression suite. Nothing here ever needs to know a task id or a capability.
+#
+# Run by the orchestrating actor's own Job: the generated tests read their target component's base
+# URL from an environment variable named <COMPONENT>_URL (uppercase, e.g. BACKEND_URL), or whichever
+# variable the agreed acceptance surface named — set by that Job to the in-namespace service
+# address, never baked into this image.
+#
+# WHAT IT CARRIES, AND WHEN TO DECLARE YOUR OWN. pytest to run the suite; requests for HTTP
+# handles; aio-pika for event handles on an AMQP bus. A capability whose tests need anything else
+# declares `runner:` on that component and owns the file — keeping its CMD a pytest run, because
+# that is what the orchestrating actor reads a verdict from.
+FROM python:3.12-slim
+
+RUN pip install --no-cache-dir "pytest==8.*" "requests==2.*" "aio-pika==9.*"
+
+WORKDIR /tests
+COPY . /tests
+
+CMD ["pytest", "-v", "--tb=line"]