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

foundry_testing_actor/schemas/agentic-context.schema.yaml

@@ -0,0 +1,168 @@
+# agentic-context.schema.yaml — the foundry-testing-actor/agentic-context contract.
+#
+# WHAT THIS FILE IS FOR. One capability's own declaration of what this actor's non-deterministic
+# doors should ground themselves in, where each component's black-box tests live, which runner
+# builds them, and which implementation they are written against. The machinery in this package
+# carries no capability literal of its own — every identifier it needs is DERIVED from
+# `capability` and `source_repo` below (see `config.py`), so a second capability instantiates the
+# same actor by writing this file and nothing else.
+#
+# THE CONTRACT IS COMMITTED SOURCE, NOT A FETCHED GATE. It lives inside the package, the same path
+# in a source checkout and in an installed wheel, so `foundry-testing-actor lint` needs no network
+# and no credential. Same discipline as papeete-actor's own manifest schema, and as the sibling
+# `foundry-implementation-actor/agentic-context/v1` this one is shaped after.
+#
+# ─── WHY A SIDECAR AND NOT THE CARD ───────────────────────────────────────────────────────────
+# `papeete_actor_synchronous_messaging.card` opens exactly four hardcoded filenames and never
+# globs, so `Actor.from_card()` will never see this file. That is deliberate: this is the actor's
+# own operational configuration, not part of any published card contract, and it is loaded by this
+# package's `config.py` directly.
+#
+# ─── WHY `writes_only_under` IS NOT DECLARED HERE ─────────────────────────────────────────────
+# The hand-written actor this replaces declared it beside a hardcoded copy in the module that
+# ENFORCED it. There is now exactly one source: `components[].tests`. A boundary that can be stated
+# twice will eventually be stated differently.
+#
+# ─── WHY THE READS OF `required` ARE FROM HERE ────────────────────────────────────────────────
+# `config.py` reads both `required` lists below rather than carrying its own copy. The sibling
+# package carried a hardcoded key tuple beside its schema's `items.required`, and noticed only when
+# a removal had to touch both (ADR-FIA-0002's follow-up). This package starts without the second
+# copy.
+
+contract: foundry-testing-actor/agentic-context/v1
+
+kind: agentic-context
+
+location: actor-agentic-context.yaml    # at the actor's folder root, beside actor.yaml
+
+required:
+  - context
+  - engine
+  - capability
+  - source_repo
+  - registry_repo
+  - components
+  - ground_in
+
+fields:
+
+  context:
+    type: string
+    const: foundry-testing-actor/agentic-context/v1
+    doc: >-
+      The contract this file claims. A file declaring some other value is read, warned, and not
+      checked further — UNMIGRATED is not the same as non-conformant, and migration is each
+      pair's own act.
+
+  engine:
+    type: string
+    doc: >-
+      The engine name this actor's doors name on its card (both of them). Registered under
+      exactly this key in `Actor.from_card(engines={...})`.
+
+  capability:
+    type: string
+    doc: >-
+      The capability id, in its canonical dotted form with the `CAP` segment present — e.g.
+      `<ENT>.<DOMAIN>.CAP.<TYPE>.<NNN>.<CODE>`. Every other rendering of the id is derived from
+      this one; none is declared. See `config.py` for the full table.
+
+  source_repo:
+    type: string
+    doc: >-
+      `<owner>/<repo>` of the TESTING repository this actor clones, writes black-box tests into,
+      and pushes a `test/<task_id>` branch to. The actor's own name and its git commit identity
+      are derived from the repo half.
+
+  implementation_repo:
+    type: string
+    optional: true
+    default: "<owner of source_repo>/<capability>-implementation"
+    doc: >-
+      `<owner>/<repo>` of the repository the implementation actor pushes to. Read, never written.
+      `propose-acceptance` reads its DEFAULT BRANCH only — the state before the increment, never
+      `impl/<task_id>` (ADR-FTA-0002). `test-task` checks out `impl/<task_id>` solely to recompute
+      the image refs that actor published; the session is not shown that source. Declare it only
+      when the repo does not follow the `<capability>-implementation` convention.
+
+  registry_repo:
+    type: string
+    doc: >-
+      `<owner>/<repo>` of the knowledge registry the `ground_in` fetches resolve through. There is
+      NO default: a fetch that silently reaches a fallback registry is worse than one that fails.
+
+  components:
+    type: array
+    doc: >-
+      The components this actor writes black-box tests for and publishes one test image of. Each
+      entry declares where its tests live and, optionally, which runner builds them — two things
+      that were hardcoded, in two different files, before this contract existed. A component's
+      `name` is also the folder its implementation lives under in `implementation_repo`, which is
+      where the ref of the image under test is recomputed from.
+    items:
+      required: [name, tests]
+      fields:
+        name:
+          type: string
+          doc: >-
+            The component's own name — as a caller names it in a payload's `components`, and as it
+            appears in both the image under test and the published test image refs.
+        tests:
+          type: string
+          doc: >-
+            The component's PERSISTENT, accumulated test root inside the testing repo, trailing
+            slash included (e.g. `backend/tests/`). The union of these IS the write boundary —
+            nothing else declares it. It is also the build context of the test image, so the image
+            always carries the full regression suite rather than one task's slice. May be more than
+            one segment deep; the component a staged path belongs to is resolved by longest
+            prefix.
+        runner:
+          type: string
+          optional: true
+          default: "the runner shipped in foundry-testing-actor (runner/Dockerfile)"
+          doc: >-
+            The directory holding the Dockerfile that turns this component's tests root into a
+            runnable image, as `buildctl --local dockerfile=` takes it — relative to the testing
+            repo's root, and it must exist in the clone. OMIT IT to use the runner this package
+            ships: a lean pytest image whose CMD is the contract the orchestrating actor runs. A
+            capability declares its own only when its tests need something that runner does not
+            carry; the declared one then owns that contract.
+
+  ground_in:
+    type: array
+    doc: >-
+      What the session is grounded in, before its first turn, at both doors. Each entry is a
+      command to run and a place to put its output inside the clone — this package hardcodes no
+      knowledge tool. A fourth knowledge source is an entry here, not a change to this package.
+    items:
+      required: [name, answers, fetch, into, load]
+      fields:
+        name:
+          type: string
+          doc: Short identifier for the source. Titles its section in the rendered Markdown.
+        answers:
+          type: string
+          doc: >-
+            One line saying what question this source answers. It is not decoration: for an
+            on-demand entry it is the ONLY thing the session sees, and what it decides to read
+            the file on.
+        fetch:
+          type: array
+          doc: >-
+            argv to run, as a list. `{capability}`, `{registry_repo}`, `{source_repo}` and
+            `{implementation_repo}` are substituted from the fields above. Non-zero exit, a missing
+            binary, or a timeout all fail the request before any session time is spent.
+        into:
+          type: string
+          doc: >-
+            Repo-relative path to write the envelope to, INSIDE the clone. Inside, because a
+            CLAUDE.md `@`-import resolves relative to the file that contains it — an envelope in
+            a sibling tempdir cannot be imported, only described.
+        load:
+          type: string
+          enum: [eager, on-demand]
+          doc: >-
+            `eager` is `@`-imported by the generated CLAUDE.md and enters the window before turn
+            one, unconditionally, every session. `on-demand` is listed by its `answers` line and
+            its path, and costs nothing until the session opens it. Choose from a measurement of
+            the envelope, not from taste.

foundry_testing_actor/serve.py

@@ -0,0 +1,129 @@
+"""The entrypoint — moved here so two uses cannot wire their observability differently.
+
+WHAT THIS REPLACES. A hand-written `app.py` in every use's repo: some sixty lines that configure
+observability, add a console handler beside the OTLP one, install the correlation filter, read
+`PORT`, build an `HttpMailbox`, call `Actor.from_card`, and emit an `actor-started` event. Not one
+line of it is about the capability. Worse, the reasoning behind the strangest line — the console
+handler — was discovered the hard way by an operator and then existed only as a comment someone
+would have to copy correctly (ADR-FIA-0005, copied here by ADR-FTA-0001).
+
+WHY THE IMPORTS ARE LAZY. `papeete-actor-synchronous-messaging-http` and `papeete-observability`
+are how this actor is CARRIED. ADR-PAM-0001 keeps wire out of the message contract, and the same
+discipline keeps an HTTP server out of the dependency set of a consumer that only wants
+`CapabilityConfig`. They arrive through the `serve` extra, and importing them inside the function
+is what lets `foundry-testing-actor lint` run in a venv that has neither.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from . import correlation
+from .config import CapabilityConfig
+from .engine import ClaudeCodeTesterEngine
+from .handler import make_test_task
+from .instance import CARD_FILES, render_cards
+
+DEFAULT_PORT = 8080
+
+
+class ServeError(RuntimeError):
+    """Raised when the wire half of this actor is not installed."""
+
+
+def _imports():
+    try:
+        from papeete_actor_synchronous_messaging.actor import Actor
+        from papeete_actor_synchronous_messaging_http.mailbox import HttpMailbox
+        from papeete_observability import configure
+    except ImportError as e:  # pragma: no cover - exercised in the image, not the suite
+        raise ServeError(
+            f"the `serve` extra is not installed: {e}. `foundry-testing-actor serve` needs "
+            f"a mailbox and an observability backend, which are wire concerns this package does "
+            f"not depend on by default — install `foundry-testing-actor[serve]`, or use "
+            f"the image this package publishes, which already has."
+        ) from e
+    return Actor, HttpMailbox, configure
+
+
+def _cards_for(config: CapabilityConfig, folder: Path) -> Path:
+    """The folder `Actor.from_card` is pointed at.
+
+    Rendered at `docker build` time in the normal case, and this finds them already sitting beside
+    the sidecar. A use that skipped that step gets them rendered into a tempdir now — the cards are
+    derived from the definition either way, so there is no version of this that reads differently.
+    Build time is still the better place: it is inspectable (`cat /actor/actor.yaml`), it fails
+    while someone is watching a build rather than at a boot, and it needs no writable filesystem.
+    """
+    if all((folder / name).exists() for name in CARD_FILES):
+        return folder
+    rendered = Path(tempfile.mkdtemp(prefix=f"{config.actor_slug}-cards-"))
+    render_cards(config, rendered)
+    correlation.event(
+        "cards-rendered", folder=str(rendered), actor=config.actor_name,
+        because="the actor's folder carried no cards; render them at build time to have them "
+                "beside the sidecar instead",
+    )
+    return rendered
+
+
+def serve(folder: str | Path = ".", port: int | None = None) -> None:
+    """Boot this actor and answer its doors until the process is stopped."""
+    Actor, HttpMailbox, configure = _imports()
+
+    configure()
+    # papeete_observability.configure() attaches an OTLP log handler to the root logger but never
+    # raises its level off the stdlib default WARNING, so logging.info(...) calls (including
+    # HttpMailbox's own access log) would otherwise never reach it.
+    logging.getLogger().setLevel(logging.INFO)
+    # ...and a console handler beside it. The OTLP handler alone is write-only from an operator's
+    # seat: with nothing on stdout, `kubectl logs` shows this pod's startup line and nothing else —
+    # so a record that never reaches the log backend is indistinguishable from a record that was
+    # never emitted, exactly when the telemetry backend is the thing under suspicion. Found the
+    # hard way, against an HTTP binding that predated its own OTel wiring and emitted no records at
+    # all, where `kubectl logs` could not have shown it. `StreamHandler.emit()` flushes per record,
+    # so this needs no PYTHONUNBUFFERED to survive a container's block-buffered stdout.
+    #
+    # The formatter applies to THIS handler only — the OTLP `LoggingHandler` builds its body from
+    # `record.getMessage()`, so what the log backend stores stays the bare message (for the
+    # engine's own stream-json records, exactly the JSON object it logged).
+    console = logging.StreamHandler(sys.stdout)
+    console.setFormatter(
+        correlation.ConsoleFormatter("%(asctime)s %(levelname)s %(name)s %(message)s")
+    )
+    logging.getLogger().addHandler(console)
+    # ...and, on both handlers, the filter that stamps every record with this request's own
+    # correlation ids. On the HANDLERS, not the root logger: a record from a named logger (the HTTP
+    # binding's own access log, most of all) reaches the root's handlers without the root LOGGER's
+    # filters ever seeing it — see correlation.py's own docstring.
+    correlation.install()
+
+    folder = Path(folder)
+    # The sidecar is the only thing in that folder this package did not put there.
+    config = CapabilityConfig.load(folder)
+    cards = _cards_for(config, folder)
+
+    # PORT, not a hardcoded default: an env var is how an environment moves it without editing an
+    # image, and it is what a Service's targetPort is set against.
+    port = port if port is not None else int(os.environ.get("PORT", str(DEFAULT_PORT)))
+    mailbox = HttpMailbox(port=port)  # 0.0.0.0:<port> — one POST per door, plus GET /health
+    actor = Actor.from_card(
+        cards,
+        mailbox=mailbox,
+        # One engine instance serves every door that names one: `Actor.judge()` hands it the door
+        # id and it dispatches on that. The key comes from the sidecar rather than a literal here,
+        # so a use whose sidecar names another engine is caught by its own card.
+        engines={config.engine: ClaudeCodeTesterEngine(config)},
+        # `propose-acceptance` needs no entry: it is a query with an engine and no handler, so
+        # the engine's own judgement is the reply and there is no deterministic half to contain.
+        actions={"test-task": make_test_task(config)},
+    )
+    # An `event` record rather than a `print`: a restart in the middle of a run is one of the most
+    # explanatory things a pipeline panel can show, and `print` reaches only the container's own
+    # stdout — never the OTLP handler, so never the log backend.
+    correlation.event("actor-started", actor=actor.name, port=port, capability=config.capability,
+                      cards=str(cards))
+    mailbox.serve_forever()

foundry_testing_actor-0.1.0.dist-info/METADATA

@@ -0,0 +1,258 @@
+Metadata-Version: 2.5
+Name: foundry-testing-actor
+Version: 0.1.0
+Summary: Runs a headless Claude Code black-box test-authoring session against one capability's own testing repo — a papeete-actor for one use, with the capability supplied by a sidecar.
+Project-URL: Homepage, https://github.com/papeete-hub/foundry-testing-actor
+Author-email: Papeete Consulting <yoann.remy@outlook.com>
+License-Expression: MIT
+Keywords: actor-model,agentic,capability,claude-code,papeete,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: papeete-actor-synchronous-messaging>=0.2.1
+Requires-Dist: papeete-version>=0.1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: serve
+Requires-Dist: papeete-actor-synchronous-messaging-http>=0.4.0; extra == 'serve'
+Requires-Dist: papeete-observability>=0.1.0; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# foundry-testing-actor
+
+Runs a headless [Claude Code](https://claude.com/claude-code) session that authors **black-box
+tests** for one capability's increment, inside that capability's own testing repository — then
+commits, pushes and publishes a runnable test image, inside a write boundary the actor enforces
+rather than requests. Before anything is built, it proposes what it will assert.
+
+An **actor, for one use**, with a [`papeete-actor`](https://github.com/papeete-hub/papeete-actor)
+underneath. The `-actor` suffix is that claim; `papeete-actor-*` names, by contrast, are transverse
+features *of* the framework (`ADR-ECO-0022`). It is the sibling of
+[`foundry-implementation-actor`](https://github.com/papeete-hub/foundry-implementation-actor), and
+is built exactly the way that package is.
+
+```bash
+pip install foundry-testing-actor
+```
+
+> **New here?** [`examples/`](examples/) walks through a complete, working use of this actor. Every
+> command in it that does not build an image runs with no credentials and no network.
+
+**It authors a harness; it does not execute it.** No session this actor starts brings up docker,
+hits a live endpoint, or renders a pass/fail verdict. The orchestrating actor deploys the
+increment into an ephemeral namespace, runs the test image this one published, and judges.
+
+## What it is
+
+The actor's **definition** — its four cards, and the machinery behind them. It carries **no
+capability of its own**: the capability it serves arrives in a sidecar the consuming repo writes:
+
+```yaml
+# actor-agentic-context.yaml
+context: foundry-testing-actor/agentic-context/v1
+engine: claude-code
+capability: ACME.PARTS.CAP.SUP.007.WID
+source_repo: acme-lab/ACME.PARTS.CAP.SUP.007.WID-testing
+registry_repo: acme-lab/acme-governance
+# implementation_repo: acme-lab/ACME.PARTS.CAP.SUP.007.WID-implementation   ← derived; declare to override
+components:
+  - {name: backend, tests: backend/tests/}                                  # the runner this package ships
+  - {name: stub,    tests: stub/tests/, runner: deployment/stub-runner}     # a runner of its own
+ground_in:
+  - name: business
+    answers: the WHAT/WHY — domain vision, business events, ubiquitous language
+    fetch: [kpack, pack, "{capability}", --deep, --compact, --registry-repo, "{registry_repo}"]
+    into: .foundry/business.md
+    load: eager
+  - name: process
+    answers: the HOW — aggregates, commands, policies, read-models, bus, api, JSON schemas
+    fetch: [kontract, fetch, "{capability}", --compact, --registry-repo, "{registry_repo}"]
+    into: .foundry/process.md
+    load: eager
+```
+
+and, beside it, a four-line Dockerfile:
+
+```dockerfile
+FROM ghcr.io/papeete-hub/foundry-testing-actor:0.1.0
+RUN pip install --no-cache-dir kpack==2.0.1 kontract==0.1.0   # what this sidecar's ground_in names
+COPY actor-agentic-context.yaml /actor/
+RUN foundry-testing-actor render-cards /actor && foundry-testing-actor lint /actor
+```
+
+**That is the whole repository** — beside the tests themselves, which are what this actor writes.
+No cards, no entrypoint, no Python, and no runner Dockerfile unless a component wants its own.
+
+### The sidecar, field by field
+
+| field | required | default | what it is |
+|---|---|---|---|
+| `context` | yes | — | `foundry-testing-actor/agentic-context/v1` |
+| `engine` | yes | — | the engine key both doors name; `claude-code` |
+| `capability` | yes | — | the dotted id, `CAP` segment present |
+| `source_repo` | yes | — | `<owner>/<repo>` of the **testing** repo: cloned, written, pushed to |
+| `implementation_repo` | no | `<owner of source_repo>/<capability>-implementation` | read, never written |
+| `registry_repo` | yes | none, deliberately | the knowledge registry `ground_in` fetches resolve through |
+| `components[].name` | yes | — | as callers name it; also the implementation's folder for that component |
+| `components[].tests` | yes | — | the persistent tests root, trailing `/`. **The write boundary**, and the test image's build context |
+| `components[].runner` | no | the runner shipped in this package | a directory in the testing repo holding the runner's Dockerfile |
+| `ground_in[]` | yes | — | `name`, `answers`, `fetch` (argv), `into` (inside the clone), `load` (`eager`/`on-demand`) |
+
+**Why the runner ships in the package.** The hand-written actor kept a lean pytest Dockerfile in
+its own repo that named nothing about the capability — a Python base, pytest, `requests`,
+`aio-pika`, and `CMD pytest`. Its CMD is the contract between this actor and the orchestrating
+actor that runs what it publishes, so it belongs with the actor. `buildctl --local dockerfile=`
+reads a directory client-side, so the copy inside the installed wheel is addressed exactly as a
+directory in the clone would be. A capability whose tests need more declares `runner:` and owns
+that file.
+
+### Embedding it instead
+
+```python
+from foundry_testing_actor import CapabilityConfig, ClaudeCodeTesterEngine, make_test_task
+
+config = CapabilityConfig.load(".")
+actor = Actor.from_card(".", mailbox=mailbox,
+                        engines={config.engine: ClaudeCodeTesterEngine(config)},
+                        actions={"test-task": make_test_task(config)})
+```
+
+`propose-acceptance` needs no entry: it is a query with an engine and no handler, so the engine's
+own judgement is the reply. The mailbox and observability backend `serve` needs live in the
+`[serve]` extra.
+
+## Two doors
+
+| door | verb | what it does |
+|---|---|---|
+| `propose-acceptance` | query | proposes the acceptance surface, before anything is built. Writes nothing |
+| `test-task` | request | extends the suite, commits, pushes `test/<task_id>`, publishes one test image per touched component |
+
+Both name the same engine. `Actor.judge()` hands it the door id, and it dispatches on that.
+
+### `propose-acceptance` — this actor's half of the three amigos round
+
+```
+orchestration ──▶ testing:        propose-acceptance {task_id, title, definition_of_done, components, context?}
+              ◀──                 {expectations: [{id, statement, handle, component?}], open_questions: [...]}
+orchestration ──▶ implementation: assess-task {..., acceptance_surface: expectations}
+              ◀──                 {feasible, objections, commitments}
+```
+
+A **query**, read-only: a clone of the testing repo, a clone of the implementation repo's **default
+branch** — never `impl/<task_id>` — grounded exactly as the test door is, and a session invoked with
+`Read,Glob,Grep` and nothing that writes. Its budget is the implementation actor's assess budget
+(15 turns, 600 s), as constructor keywords.
+
+The session is told three things that matter: **nothing is built yet**; where a test needs a
+concrete value the task does not name — a fixture id, a routing key — **propose one**, for the
+implementer to commit to or object to; and anything the task does not determine goes in
+`open_questions`, **never** into an invented statement. A non-empty `open_questions` stops the round
+and reaches a human. See `adr/ADR-FTA-0002-*.md`.
+
+The reply is **projected** onto `{expectations, open_questions}` — a session's stray keys never
+reach the orchestrating actor dressed as contract — after checking that every expectation carries
+an `id`, a `statement` and a `handle`, with ids unique. `open_questions` is always a list.
+
+### `test-task`
+
+```
+clone the testing repo (full) → checkout -b test/TASK-NNN
+clone the implementation repo  → checkout impl/TASK-NNN, recompute each image under test (never shown to the session)
+run every ground_in fetch, write it into the testing clone, render CLAUDE.md
+claude --print --output-format stream-json --permission-mode acceptEdits
+git add <each tests root>; refuse anything staged outside them
+commit as the actor, force-push test/TASK-NNN
+buildctl build + push one test image per touched component
+```
+
+With an `acceptance_surface`, the prompt says it was agreed with the implementer before anything
+was built: each expectation is asserted by its id, addressed exactly via its handle, wins where it
+is more specific than the DoD, and is named in each test. With a `remediation_context`, the session
+decides per failing criterion whether the test or the implementation is at fault, and fixes only
+the former.
+
+It never opens a pull request, and never runs what it wrote beyond `pytest --collect-only`.
+
+## Derived renderings, zero literals
+
+`foundry-testing-actor show` prints them for a given sidecar:
+
+| rendering | from |
+|---|---|
+| `ACME.PARTS.CAP.SUP.007.WID-testing` | actor name, git `user.name` (repo half of `source_repo`) |
+| `acme-lab/ACME.PARTS.CAP.SUP.007.WID-implementation` | `implementation_repo`, when not declared |
+| `acme.parts/sup.007.wid` | the id, split at its `CAP` segment |
+| `acme.parts.cap.sup.007.wid-backend-tests` | the name `papeete-version` versions the test image under |
+| `<registry>/acme.parts/sup.007.wid/backend/tests:<version>` | **the test image this actor publishes** |
+| `<registry>/acme.parts/sup.007.wid/backend:<version>` | **the image under test**, recomputed |
+
+**Both refs are a three-way contract.** The implementation actor publishes the second; the
+orchestrating actor runs the first and parses both apart. Derivation output or nothing.
+
+## Grounding, containment, observability
+
+Identical to `foundry-implementation-actor`'s, deliberately copied rather than shared
+(ADR-FTA-0001): envelopes are written **inside the clone** and `@`-imported from a generated
+`CLAUDE.md` (appended to a committed one, never substituting it); containment is `git add <root>`
+then a prefix assertion with longest-prefix component resolution; every emitted log line is
+budgeted to 64 KB; the record schema `{event: step|event|result, ...}` plus `correlation_id` and
+`task_id` is the contract, step names are not.
+
+Step names this actor emits: `clone-tests`, `clone-code`, `ground-<name>`, `claude-session` or
+`propose-session`, `containment-commit`, `push-branch`, `publish-test-image`, plus the events
+`images-under-test`, `acceptance-proposed`, `components-touched`, `test-image-published`,
+`test-task-refused`.
+
+## Credentials
+
+| variable | what for |
+|---|---|
+| `GITHUB_TOKEN` | fine-grained PAT: `contents:write` on `source_repo`; read-only `contents` on `implementation_repo` and on whatever the `ground_in` fetches resolve through |
+| `CLAUDE_CODE_OAUTH_TOKEN` | from `claude setup-token`, tied to a Pro/Max/Team/Enterprise subscription |
+| `IMAGE_REGISTRY`, `BUILDKIT_HOST`, `DOCKER_CONFIG` | `test-task` only: where images are recomputed from and pushed to |
+
+> **Do not also set `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`.** In `claude -p`
+> non-interactive mode an API key present in the environment is ALWAYS preferred over
+> `CLAUDE_CODE_OAUTH_TOKEN`, silently routing every session through metered billing.
+
+## CLI
+
+```bash
+foundry-testing-actor lint .                              # validate the sidecar and the cards
+foundry-testing-actor show . --registry reg.example.com   # every derived rendering
+foundry-testing-actor render-cards .                      # write the four cards from the wheel
+foundry-testing-actor serve .                             # boot it (needs the `serve` extra)
+```
+
+## Where this came from
+
+Ported from one capability's hand-written testing actor — an `app.py`, an engine that named two
+knowledge tools and their registry as module constants, a handler whose write boundary and
+capability path were module constants too, four cards, and a runner Dockerfile — using
+`foundry-implementation-actor` as the template. `adr/` records the decisions.
+
+## Releasing, and which registry to pin
+
+A tag (`v*`) publishes the wheel to PyPI and the image to two registries holding one digest, as
+`foundry-implementation-actor` does (ADR-FIA-0006):
+
+| Registry | Pin it when |
+|---|---|
+| `ghcr.io/papeete-hub/foundry-testing-actor` | you write a use's Dockerfile yourself and build it with your own Docker |
+| a product's own registry, `vars.PRODUCT_IMAGE` | the use is built in-cluster, by a builder whose one registry credential is that product's |
+
+A manual run backfills an image for an existing tag: `gh workflow run release.yml --ref main -f
+tag=v0.1.0`. It skips PyPI and does not move `latest`.
+
+## Development
+
+```bash
+uv run --extra dev pytest -q     # what CI runs
+uv build
+```
+
+There is no separate lint/format command configured in this repo.

foundry_testing_actor-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+foundry_testing_actor/__init__.py,sha256=S2AERZkWdEbqmoVoNzDixWM22NsepCHYFKnf_8eW6qc,2308
+foundry_testing_actor/cli.py,sha256=dxOIrjONTD8gtEk36JXtVTIvNF68OmqD5-gGr5GWun8,7621
+foundry_testing_actor/config.py,sha256=iBWT80hiB2yP4IYcbrO69lDfvK2Eg7XhAotGUoh7Hig,25324
+foundry_testing_actor/conformance.py,sha256=8WT_T75hJXRnoRlitqLE1JcM_kJTxiwQTrftIOad75E,7333
+foundry_testing_actor/correlation.py,sha256=PmnlGDKzu9ZBB8NEHaB4mNTimYZSHdWw31BNFbb0nNo,10658
+foundry_testing_actor/engine.py,sha256=cg9Yff2eq2O-79TXpa1-SE6EwxYnyNuE3meDkaEH4A0,50309
+foundry_testing_actor/grounding.py,sha256=JIj8K15TR1ctXNrjoeb1SLS8rrVe4YObrLuo011i8mM,9502
+foundry_testing_actor/handler.py,sha256=Yor47nNr2Mge0GdoAAwbVPC5hwYWcr3wjSWmjo3UrIo,12466
+foundry_testing_actor/instance.py,sha256=hSQ2bP0dj7fs_AuGiiZP063f_iI64gp7VU-aBeMxD98,6708
+foundry_testing_actor/serve.py,sha256=llRur42JG5E8h34Vs4e9MpXB02JzYSFif-dpwN6ngAk,7073
+foundry_testing_actor/cards/actor-data.yaml,sha256=isEMJwEAwqNCmCKGbC3dKgpq56JMm_Y9DUkLlxl0sDw,3737
+foundry_testing_actor/cards/actor-message.yaml,sha256=KW_uNIUJQ05UfVnodIh-xoa4uM_KRpnVcHEz8cJcsUY,1535
+foundry_testing_actor/cards/actor-synchronous-messaging.yaml,sha256=dlY6QCj_uioZxQ2YXfxyjE0MwWZTfoc7jVQnjP6rGwE,4149
+foundry_testing_actor/cards/actor.yaml,sha256=iSpegjN7VT_8oocfgX_Ily4GmUqzu-33GF9fgvAGDYM,1373
+foundry_testing_actor/runner/Dockerfile,sha256=lCGX5wMRmAi--AbiMcXi9A6IA75p45DjgvtaATYVKg8,1955
+foundry_testing_actor/schemas/agentic-context.schema.yaml,sha256=0UeeYF8TtT4C4SO0w_dr6f3QezyqK-tXqPLWRqQAtcQ,8629
+foundry_testing_actor-0.1.0.dist-info/METADATA,sha256=26pfkedlhhqOaT-udJS-RIWA0dXb7oLEPa9qIPwMzTU,13505
+foundry_testing_actor-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+foundry_testing_actor-0.1.0.dist-info/entry_points.txt,sha256=mmZNR9DfIhAQu3KXB-ruHwWNrmBsRjxQawxr4xZ8JQg,73
+foundry_testing_actor-0.1.0.dist-info/RECORD,,

foundry_testing_actor-0.1.0.dist-info/WHEEL

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

foundry_testing_actor-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+foundry-testing-actor = foundry_testing_actor.cli:main