foundry-task-orchestration-actor 0.1.0__tar.gz

foundry_task_orchestration_actor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,124 @@
+name: ci
+on: [push, pull_request]
+
+# NO CREDENTIAL. Nothing here authenticates to anything: no peer actor, no cluster, no GitHub API,
+# no PyPI upload, no image push. Everything this pipeline asserts about THIS package, it asserts
+# from source and from artifacts it built itself — the wheel it just built, and an image built from
+# that wheel rather than from a published one.
+#
+# It does reach the network for inputs: public base images (python, the Kubernetes project's
+# kubectl image) and PyPI. That is fetching, not authenticating — no secret is available to this
+# workflow, so nothing it runs can reach a real capability's repositories or a real cluster.
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: the test suite
+        # Includes round 0 against real loopback HTTP peers; Kubernetes and GitHub are replaced.
+        run: uv run --extra dev pytest -q
+
+      - name: build
+        run: uv build
+
+      # ── the gates a contract-shipping package runs against its own artifact ─────────────────
+      #
+      # The suite above proves the code works in a source checkout. These prove the WHEEL works,
+      # which is a different claim and the one a consumer actually depends on. A schema left out
+      # of the build passes every test in tests/ and fails here.
+
+      - name: the wheel must carry its contract
+        run: |
+          uv venv /tmp/probe
+          uv pip install --python /tmp/probe/bin/python -q dist/*.whl
+          /tmp/probe/bin/foundry-task-orchestration-actor lint examples/ACME.PARTS.CAP.SUP.007.WID-task-orchestration
+          /tmp/probe/bin/foundry-task-orchestration-actor show examples/ACME.PARTS.CAP.SUP.007.WID-task-orchestration \
+            --registry reg.example.com | tee /tmp/show.txt
+          grep -q 'reg.example.com/acme.parts/sup.007.wid/backend/tests:<version>' /tmp/show.txt
+          grep -q 'http://foundry-acme-parts-cap-sup-007-wid-implementation  (derived)' /tmp/show.txt
+
+      - name: the wheel must carry the actor's own cards
+        # The `-actor` suffix asserts a papeete-actor underneath, which lint-card can check
+        # (ADR-ECO-0022). The suite proves the cards are conformant in a source checkout; this
+        # proves they SHIPPED. `papeete-actor-synchronous-messaging` is a runtime dependency, so its
+        # gate is already in the probe venv.
+        run: |
+          /tmp/probe/bin/papeete-actor-synchronous-messaging lint-card \
+            "$(/tmp/probe/bin/python -c 'from foundry_task_orchestration_actor import cards_path; print(cards_path())')"
+
+      - name: the gate must run
+        # A gate that cannot fail is not a gate. Lint a deliberately non-conformant sidecar with
+        # the INSTALLED wheel and require a non-zero exit.
+        run: |
+          if /tmp/probe/bin/foundry-task-orchestration-actor lint tests/fixtures/broken; then
+            echo "::error::lint accepted a non-conformant sidecar — the gate is not running"
+            exit 1
+          fi
+          echo "the gate refused a non-conformant sidecar, as it should"
+
+  # ── the other half of what this package ships ─────────────────────────────────────────────────
+  #
+  # A use is a sidecar (and the platform stand-in it names), and the image is what turns one into a
+  # running actor. The job above proves the WHEEL works. This one proves that a folder holding
+  # nothing but those builds into an actor that boots and answers its door. Nothing here reaches a
+  # registry: the image is built, run and thrown away in the runner.
+  image:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: build the wheel this image will carry
+        run: uv build
+
+      - name: the base image
+        run: docker build -f docker/Dockerfile -t foundry-task-orchestration-actor:ci .
+
+      - name: the image and the wheel are one release
+        run: |
+          wheel="$(ls dist/*.whl | sed -E 's/.*-([0-9][^-]*)-py3.*/\1/')"
+          in_image="$(docker run --rm --entrypoint python foundry-task-orchestration-actor:ci \
+            -c 'from foundry_task_orchestration_actor import version; print(version())')"
+          echo "wheel=$wheel image=$in_image"
+          [ "$wheel" = "$in_image" ] || { echo "::error::image carries $in_image, wheel is $wheel"; exit 1; }
+
+      - name: the image carries the kubectl it pins
+        # papeete-deploy and deploy.py shell out to it on every attempt; an image without it builds,
+        # boots, answers /health, and fails the first task that gets past round 0.
+        run: docker run --rm --entrypoint kubectl foundry-task-orchestration-actor:ci version --client
+
+      - name: a use is a sidecar
+        # The example folder holds its sidecar, its platform stand-in and its Dockerfile — nothing
+        # else. If this builds, the claim in the README is true of a real folder rather than of prose.
+        run: |
+          test "$(ls examples/ACME.PARTS.CAP.SUP.007.WID-task-orchestration | sort | tr '\n' ' ')" = \
+            "Dockerfile actor-agentic-context.yaml platform-standin "
+          docker build --build-arg ACTOR_IMAGE=foundry-task-orchestration-actor:ci \
+            -t use:ci examples/ACME.PARTS.CAP.SUP.007.WID-task-orchestration
+
+      - name: the rendered cards are what a caller is validated against
+        run: docker run --rm use:ci foundry-task-orchestration-actor lint /actor
+
+      - name: it boots, and answers the door its cards declare
+        # The credential is deliberately junk and no run is exercised: a 400 means routed and
+        # refused the payload, a 404 would mean the route was never built. Outside a cluster the
+        # kubeconfig bootstrap has nothing to write, and says so rather than failing the boot.
+        run: |
+          docker run -d --name smoke -p 18080:8080 -e GITHUB_TOKEN=ci use:ci
+          for _ in $(seq 1 30); do
+            curl -fsS -m 2 http://localhost:18080/health >/dev/null 2>&1 && break
+            sleep 1
+          done
+          curl -fsS -m 5 http://localhost:18080/health | grep -q ok
+          code="$(curl -sS -o /dev/null -w '%{http_code}' -m 5 -X POST \
+            -H 'content-type: application/json' -d '{}' http://localhost:18080/orchestrate-task)"
+          [ "$code" = "400" ] || { echo "::error::POST /orchestrate-task answered $code, expected 400 (routed, bad payload)"; exit 1; }
+          code="$(curl -sS -o /dev/null -w '%{http_code}' -m 5 -X POST \
+            -H 'content-type: application/json' -d '{}' http://localhost:18080/no-such-door)"
+          [ "$code" = "404" ] || { echo "::error::an undeclared door answered $code, expected 404"; exit 1; }
+          docker logs smoke | grep -q actor-started
+          docker logs smoke | grep -q '"step": "kubeconfig"'
+          docker rm -f smoke

foundry_task_orchestration_actor-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,212 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+  # A REGISTRY ADDED AFTER A TAG WAS ALREADY CUT. The image job below publishes to two registries,
+  # and the second one was not always there. Running this workflow by hand backfills the image for
+  # a version whose wheel is already on PyPI — without inventing a version number whose only
+  # content is "the last release missed a registry".
+  #
+  # THE TAG IS AN INPUT, NOT THE REF THIS RUNS FROM. GitHub takes the workflow FILE from the ref it
+  # is dispatched on, and the tag needing a backfill is by definition older than the workflow that
+  # can do it — dispatching on that tag would run the very file that lacks this trigger. So run it
+  # from the default branch and name the tag here; the checkout below takes the CONTENT from the
+  # tag, and the version gate still refuses a tag that disagrees with the `pyproject.toml` beside
+  # it.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to publish an image for, e.g. v0.1.0"
+        required: true
+
+# PyPI Trusted Publishing (OIDC) — no token is stored anywhere. The one-time setup is a pending
+# publisher on pypi.org naming this repo and this workflow; after the first release it becomes a
+# normal publisher. See README.
+permissions:
+  id-token: write   # PyPI Trusted Publishing
+  contents: read
+  packages: write   # the image, to this repo's own container registry
+
+jobs:
+  publish:
+    # ONLY ON A TAG PUSH. A manual run exists to backfill an IMAGE (see `on:` above), and PyPI
+    # refuses a version it already holds — so re-uploading is not merely redundant, it fails, and
+    # would take the image job down with it.
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: build
+        # No fetch step and no external token: the contract is committed here. A release depends
+        # on nothing but this checkout and PyPI.
+        run: uv build
+
+      - name: the wheel must carry its contract
+        run: |
+          uv venv /tmp/probe
+          uv pip install --python /tmp/probe/bin/python -q dist/*.whl
+          /tmp/probe/bin/foundry-task-orchestration-actor lint examples/ACME.PARTS.CAP.SUP.007.WID-task-orchestration
+
+      - name: the wheel must carry the actor's own cards
+        # Same reason as the line above, for the other half of what this package ships. The
+        # `-actor` suffix asserts a papeete-actor underneath (ADR-ECO-0022); a wheel published
+        # without its cards makes the name a claim the artifact cannot honour, and a published
+        # version is not something to discover that from.
+        run: |
+          /tmp/probe/bin/papeete-actor-synchronous-messaging lint-card \
+            "$(/tmp/probe/bin/python -c 'from foundry_task_orchestration_actor import cards_path; print(cards_path())')"
+
+      - name: the gate must run
+        # BEFORE the upload, not after. A wheel whose lint silently passes everything, or that
+        # shipped without its schema, is not something to discover from a published version.
+        run: |
+          if /tmp/probe/bin/foundry-task-orchestration-actor lint tests/fixtures/broken; then
+            echo "::error::lint accepted a non-conformant sidecar — refusing to publish"
+            exit 1
+          fi
+
+      - name: publish to PyPI
+        run: uv publish --trusted-publishing always
+
+  # ── the image, from the same tag and the same checkout ────────────────────────────────────────
+  #
+  # TWO ARTIFACTS, ONE RELEASE (ADR-FIA-0005, ADR-FTOA-0001). A use pins an image; an embedder pins
+  # a wheel; both are this package at this version. A tag that produced one and not the other leaves a consumer
+  # unable to take the release at all — so this job builds the wheel again from the same checkout
+  # rather than installing the one just uploaded: the image must not depend on PyPI having already
+  # indexed it, and must not be able to pick up a different build of the same version.
+  #
+  # It runs AFTER the wheel is published, not beside it. A failed upload should not leave an image
+  # published for a version that does not exist on PyPI; the reverse — a wheel with the image still
+  # to come — is recoverable by re-running this job alone.
+  image:
+    needs: publish
+    # `needs` still orders this after the wheel on a tag push. On a manual backfill `publish` is
+    # skipped, and a skipped dependency skips its dependents too unless `always()` says otherwise —
+    # so the condition has to name both cases rather than relying on `needs` alone.
+    if: always() && (needs.publish.result == 'success' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Empty on a tag push, which is `checkout`'s own default — the ref that triggered the
+          # run. On a manual backfill it is the tag being republished, so every step below reads
+          # that tag's own tree rather than whatever the default branch has moved on to.
+          ref: ${{ inputs.tag }}
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: the version is the tag
+        # The tag is what a consumer writes in a FROM line. A tag that disagrees with
+        # pyproject.toml would publish an image whose own `version()` contradicts its name, which
+        # is exactly the confusion the CI gate above exists to prevent for the wheel. On a backfill
+        # this compares the named tag against the `pyproject.toml` checked out FROM that tag, so a
+        # typo in the input is refused rather than published under the wrong name.
+        id: version
+        env:
+          TAG: ${{ inputs.tag || github.ref_name }}
+        run: |
+          tag="${TAG#v}"
+          declared="$(uv run --quiet python -c             'import tomllib,pathlib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          [ "$tag" = "$declared" ] || { echo "::error::tag $TAG does not match pyproject version $declared"; exit 1; }
+          echo "version=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: build
+        run: uv build
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: the image, tagged and latest
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          # `latest` FOLLOWS THE RELEASE STREAM, NOT A BACKFILL. A manual run exists to give an
+          # already-released version an image in a registry it missed; run against an older tag it
+          # would otherwise drag `latest` backwards onto it, silently, in whichever registry a
+          # consumer happens to pull from. The version tag is the whole point of a backfill —
+          # `latest` already names something newer, and stays there.
+          MOVE_LATEST: ${{ github.event_name == 'push' }}
+        run: |
+          image="ghcr.io/${{ github.repository }}"
+          docker build -f docker/Dockerfile -t "$image:$VERSION" -t "$image:latest" .
+          docker push "$image:$VERSION"
+          if [ "$MOVE_LATEST" = "true" ]; then docker push "$image:latest"; fi
+
+      # ── the product's own registry ────────────────────────────────────────────────────────────
+      #
+      # TWO REGISTRIES, ONE IMAGE. GHCR is where this package publishes; a product that RUNS uses
+      # of it pulls from its own registry, which its cluster already authenticates to and which a
+      # `FROM` line inside that cluster's builder can reach without a second credential. The base
+      # image has to exist in both, because the two are reached by different things: an embedder
+      # writing a Dockerfile reads the README and pins GHCR, while a use built by an in-cluster
+      # builder resolves its `FROM` against the registry that builder has a push token for.
+      #
+      # THE SAME IMAGE, NOT ANOTHER BUILD. `docker tag` re-points the build the step above already
+      # pushed, so both registries hold one digest. Building a second time would let them diverge —
+      # a base-image refresh between two steps of one job is enough — and nothing downstream would
+      # ever notice that `:0.1.0` meant two different things depending on where you pulled it.
+      #
+      # ONE VARIABLE NAMES THE WHOLE TARGET. `vars.PRODUCT_IMAGE` is the full repository path, e.g.
+      # `<name>.azurecr.io/<product>/foundry-task-orchestration-actor`; the login server is its first
+      # segment. This package is generic across capabilities and names no product of its own — the
+      # same rule `tests/test_portability.py` enforces over `src/` — so the product that hosts a
+      # registry names itself in a repository variable rather than in this file.
+      #
+      # UNSET IS A VALID STATE, AND IT SAYS SO. A fork, or this repo before its credentials were
+      # added, publishes to GHCR alone; that is a `::notice`, not a failure. Configured-but-broken
+      # IS a failure — the push below is not best-effort, because an image the product's cluster
+      # cannot pull is the whole reason this block exists.
+      - name: is a product registry configured?
+        id: product
+        env:
+          PRODUCT_IMAGE: ${{ vars.PRODUCT_IMAGE }}
+        run: |
+          if [ -z "$PRODUCT_IMAGE" ]; then
+            echo "::notice::PRODUCT_IMAGE is unset — publishing to GHCR only"
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          case "$PRODUCT_IMAGE" in
+            */*/*) : ;;
+            *) echo "::error::PRODUCT_IMAGE must be <registry>/<path>/<repository>, got $PRODUCT_IMAGE"; exit 1 ;;
+          esac
+          echo "server=${PRODUCT_IMAGE%%/*}" >> "$GITHUB_OUTPUT"
+          echo "configured=true" >> "$GITHUB_OUTPUT"
+
+      - uses: docker/login-action@v3
+        if: steps.product.outputs.configured == 'true'
+        with:
+          registry: ${{ steps.product.outputs.server }}
+          username: ${{ secrets.ACR_PUSH_USERNAME }}
+          password: ${{ secrets.ACR_PUSH_PASSWORD }}
+
+      - name: the same image, in the product's registry
+        if: steps.product.outputs.configured == 'true'
+        env:
+          PRODUCT_IMAGE: ${{ vars.PRODUCT_IMAGE }}
+          VERSION: ${{ steps.version.outputs.version }}
+          MOVE_LATEST: ${{ github.event_name == 'push' }}
+        run: |
+          ghcr="ghcr.io/${{ github.repository }}"
+          docker tag "$ghcr:$VERSION" "$PRODUCT_IMAGE:$VERSION"
+          docker push "$PRODUCT_IMAGE:$VERSION"
+          if [ "$MOVE_LATEST" = "true" ]; then
+            docker tag "$ghcr:latest" "$PRODUCT_IMAGE:latest"
+            docker push "$PRODUCT_IMAGE:latest"
+          fi
+
+      - name: a use built on it is still an actor
+        # BEFORE the image is something anyone can pin — the same reason the gates run before the
+        # upload above. An image that builds but produces a use that does not conform is
+        # not something to discover from a published tag.
+        run: |
+          docker build --build-arg ACTOR_IMAGE=ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }} \
+            -t use:release examples/ACME.PARTS.CAP.SUP.007.WID-task-orchestration
+          docker run --rm use:release foundry-task-orchestration-actor lint /actor

foundry_task_orchestration_actor-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+*.egg-info/
+__pycache__/
+.venv/
+.pytest_cache/
+.serena/

foundry_task_orchestration_actor-0.1.0/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this
+repository.
+
+## What this is
+
+`foundry-task-orchestration-actor` drives one capability's task through the three amigos round
+(testing proposes, implementation assesses), then implement → ephemeral deploy → black-box test →
+retry, and opens the paired pull requests on a pass. It is the **machinery** — it carries no
+capability of its own and runs no engine. The capability arrives in a sidecar
+(`actor-agentic-context.yaml`, contract `foundry-task-orchestration-actor/agentic-context/v1`).
+
+Its shape is copied from `foundry-implementation-actor` (FIA) with names changed — see
+`adr/ADR-FTOA-0001-*.md`. There is deliberately no shared kit between the two.
+
+## Commands
+
+```bash
+uv run --extra dev pytest -q                                    # full suite (what CI runs)
+uv run --extra dev pytest -q tests/test_round0.py               # one file
+uv run --extra dev pytest -q tests/test_round0.py::test_name    # one test
+uv build                                                        # sdist/wheel (hatchling)
+uv run foundry-task-orchestration-actor lint <folder>           # validate a sidecar
+uv run foundry-task-orchestration-actor show <folder> --registry r   # every derived rendering
+```
+
+There is no separate lint/format command configured in this repo.
+
+## Architecture
+
+Under `src/foundry_task_orchestration_actor/`:
+
+- **`config.py`** — `CapabilityConfig`. Loads the sidecar and derives every identifier from
+  `capability` and `source_repo`: peers' repos and URLs, registry path, workload names, image
+  names, run ids, service URLs; renders `ephemeral.secrets` templates. Also `lint()` / `Report`.
+- **`settings.py`** — `Settings`: operational tuning (attempts, timeouts, kube context, registry,
+  pull secret, base branch, peer URL overrides), from constructor or environment. Never sidecar.
+- **`round0.py`** — the three amigos round as a pure function over two injected door calls.
+  All the wire contract's stop rules and the commitment attachment rule live here.
+- **`peers.py`** — `call_door`: POST `{from, payload}` with a long timeout and `traceparent`;
+  400/transport/non-object → `PeerError`.
+- **`deploy.py`** — one attempt's ephemeral namespace: clone `impl/<task_id>` read-only, pull
+  secret, platform stand-in, component secrets + components, test Jobs, best-effort teardown.
+- **`pulls.py`** — the paired PRs; body renders the agreed surface. Implementation PR required,
+  the rest best-effort.
+- **`handler.py`** — `make_orchestrate_task(config, settings)`: round 0, the attempt loop, the
+  `stage` of every failure.
+- **`kubeconfig.py`** — in-cluster kubeconfig from the ServiceAccount (replaces `entrypoint.sh`).
+- **`correlation.py`** — byte-identical to FIA's below the docstring.
+- **`conformance.py`**, **`instance.py`**, **`serve.py`**, **`cli.py`** — FIA's, names changed;
+  `serve` wires no engine and bootstraps the kubeconfig.
+
+Committed contract, shipped in the wheel: `schemas/agentic-context.schema.yaml` and `cards/`.
+
+## Core invariants that any change must preserve
+
+- **The wire contract is shared with two other packages.** Door ids (`propose-acceptance`,
+  `assess-task`, `implement-task`, `test-task`, `orchestrate-task`), message names, fields, and the
+  round-0 rules are fixed across `foundry-implementation-actor`, `foundry-testing-actor` and this
+  package. Do not change a field or a stop rule here alone.
+- **Round 0 stops before implementation is asked** when the tester has open questions. Never
+  "assess anyway".
+- **The agreed surface goes to implement-task AND test-task on EVERY attempt.**
+- **A failed result always names its `stage`**, and omits unknown fields rather than sending null
+  — both completion schemas are closed and typed.
+- **No capability literal, ever.** `tests/test_portability.py` greps `src/` for the originating
+  instance's identifiers (id, workload prefix, database name, the hardcoded kube context). The
+  platform stand-in and its credentials are the USE's (`ephemeral:`), never the wheel's.
+- **The image ref is a three-way contract.** `<registry>/<capability_path>/<component>[/tests]:<v>`
+  is parsed by path segment in `config.parse_images`; never re-derive or invent a tag.
+- **Teardown is best-effort and always runs**, and deletes the namespace last.
+- **The image is one build in two registries** (FIA's ADR-FIA-0006) — never a second `docker build`
+  in `release.yml`, never a hardcoded registry.
+- **`kubectl` is pinned** in `docker/Dockerfile`. Move it deliberately with the clusters it drives.
+
+## Scope discipline
+
+Generic across **capabilities**, not across actor *kinds*. No hooks or base classes for a
+hypothetical second orchestration shape. A component layout other than
+`<component>/deployment/dev/k8s/overlays/ephemeral` is not supported until a real capability needs
+it — and then it is a sidecar declaration, not a strategy object.
+
+Design rationale lives in `adr/`. Add a new ADR (copy `adr/template.md`) for any decision of
+similar weight rather than only writing it into code comments.
+
+## Releasing
+
+Tag-triggered (`v*`) via `.github/workflows/release.yml`: PyPI through Trusted Publishing, the image
+to GHCR and, when `vars.PRODUCT_IMAGE` names one, to a product's own registry. A manual run with a
+tag input backfills an image only. `ci.yml` runs the suite, the wheel gates, and builds and boots
+the example use — and reaches nothing outside its own checkout.

foundry_task_orchestration_actor-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: foundry-task-orchestration-actor
+Version: 0.1.0
+Summary: Drives one capability's task through the three amigos round, implementation, an ephemeral black-box test run and a paired pull request — a papeete-actor for one use, with the capability supplied by a sidecar.
+Project-URL: Homepage, https://github.com/papeete-hub/foundry-task-orchestration-actor
+Author-email: Papeete Consulting <yoann.remy@outlook.com>
+License-Expression: MIT
+Keywords: actor-model,capability,orchestration,papeete,three-amigos
+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-deploy>=0.5.0
+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-task-orchestration-actor
+
+Drives one task of one capability from agreement to pull request: a three amigos round between the
+testing and implementation actors, then implement → deploy into an ephemeral namespace → black-box
+test → retry, and the paired pull requests on a pass. It writes no code, writes no tests, judges
+nothing and merges nothing.
+
+An **actor, for one use**, with a [`papeete-actor`](https://github.com/papeete-hub/papeete-actor)
+underneath. The `-actor` suffix is that claim (`ADR-ECO-0022`). It is the orchestration kind of the
+shape [`foundry-implementation-actor`](https://github.com/papeete-hub/foundry-implementation-actor)
+established; the machinery was copied from there with names changed (ADR-FTOA-0001).
+
+```bash
+pip install foundry-task-orchestration-actor
+```
+
+> **New here?** [`examples/`](examples/) walks through a complete, working use of this actor. Every
+> command in it except `docker build` runs with no credentials and no network.
+
+## What it is
+
+The actor's **definition** — its four cards, and the machinery behind them. It carries **no
+capability of its own**: the capability arrives in a sidecar the consuming repo writes:
+
+```yaml
+# actor-agentic-context.yaml
+context: foundry-task-orchestration-actor/agentic-context/v1
+capability: ACME.PARTS.CAP.SUP.007.WID
+source_repo: acme-lab/ACME.PARTS.CAP.SUP.007.WID-task-orchestration
+components: [backend, stub]
+ephemeral:
+  platform: platform-standin
+  secrets:
+    - name: "{workload}-db"
+      data: {dsn: "postgresql://widgets:widgets@{run_id}-platform-postgres:5432/widgets"}
+```
+
+and, beside it, a Dockerfile of three lines:
+
+```dockerfile
+FROM ghcr.io/papeete-hub/foundry-task-orchestration-actor:0.1.0
+COPY actor-agentic-context.yaml /actor/
+COPY platform-standin /actor/platform-standin
+RUN foundry-task-orchestration-actor render-cards /actor && foundry-task-orchestration-actor lint /actor
+```
+
+**That is the whole repository**, plus the platform stand-in folder if its components need one. No
+cards, no `app.py`, no `entrypoint.sh`, no `handler.py`.
+
+### Embedding it instead
+
+```python
+from foundry_task_orchestration_actor import CapabilityConfig, Settings, make_orchestrate_task
+
+config = CapabilityConfig.load(".")
+actor = Actor.from_card(".", mailbox=mailbox,
+                        actions={"orchestrate-task": make_orchestrate_task(config, Settings())})
+```
+
+No `engines=`: the door names none. The mailbox and observability backend `serve` needs live in the
+`[serve]` extra.
+
+## The sidecar — `foundry-task-orchestration-actor/agentic-context/v1`
+
+| field | required | what it is | default |
+|---|---|---|---|
+| `context` | yes | the contract string | — |
+| `capability` | yes | `<ENT>.<DOMAIN>.CAP.<TYPE>.<NNN>.<CODE>` | — |
+| `source_repo` | yes | `<owner>/<repo>` of this actor's own repo; the repo half is its name | — |
+| `components` | yes | component names, as the implementation actor's sidecar names them; round 0 sends them to the tester | — |
+| `peers.implementation.repo` | no | where implementation is pushed and the PR is opened | `<owner>/<capability>-implementation` |
+| `peers.implementation.url` | no | base URL of its doors | `http://foundry-<capability lowercased, dots→hyphens>-implementation` |
+| `peers.testing.repo` | no | where tests are pushed and the paired PR is opened | `<owner>/<capability>-testing` |
+| `peers.testing.url` | no | base URL of its doors | `http://foundry-<capability slug>-testing` |
+| `ephemeral.platform` | no | folder beside the sidecar with `k8s/overlays/ephemeral/` — stand-ins applied before any component | none |
+| `ephemeral.secrets[]` | no | `{name, data}` templates created for each touched component; `{run_id}`, `{component}`, `{workload}`, `{capability}` substituted | none |
+
+`IMPLEMENTATION_URL` / `TESTING_URL` in the environment override both the declared and the derived
+URL. A misspelt role or key under `peers:` is refused rather than silently falling back to the
+default. What is **not** in the sidecar, on purpose, is operational tuning — see *Settings*.
+
+## One door
+
+| door | verb | engine | what it does |
+|---|---|---|---|
+| `orchestrate-task` | request | none | round 0, then up to N attempts, then the PRs |
+
+Request `orchestrate-task-cmd`: `task_id`, `title`, `definition_of_done`, optional `context`.
+
+Completions (closed; a reply matches exactly one):
+
+- `orchestration-succeeded-result` — `accepted`, `pr_url`, `branch`, `test_branch`, `attempts`,
+  `verdict`, `acceptance_surface`; optional `test_pr_url`.
+- `orchestration-failed-result` — `accepted`, `because`, `stage`, `attempts`; optional `branch`,
+  `test_branch`, `verdict`, `acceptance_surface`, `open_questions`, `objections`, `commitments`.
+  `stage` ∈ `round-0` | `implementation` | `testing` | `verdict`.
+
+```
+round 0      testing.propose-acceptance      → expectations, open_questions
+             implementation.assess-task      → feasible, objections, commitments
+             stop (stage round-0) on a transport error, open questions, no expectations,
+             infeasible, or any objection — carrying what was said
+attempt n    implementation.implement-task   (acceptance_surface, remediation_context?)
+             testing.test-task               (acceptance_surface, touched components)
+             clone impl/<task_id> read-only → namespace test-<task_id> → pull Secret →
+             platform stand-in → Secrets + each touched component → a test Job per test image →
+             teardown
+             green → paired PRs, succeed      red → remediation context, next attempt
+exhausted    stop (stage verdict)
+```
+
+The **agreed surface** is the tester's expectations, with each of the implementer's commitments that
+names an expectation (`id`, `expectation` or `expectation_id`) attached under `commitments`, and
+every other commitment appended as `{id: commitment-<n>, statement, handle, commitment}`. It goes to
+both doors on every attempt and is rendered into the PR body. See ADR-FTOA-0002.
+
+## Every rendering, from two fields
+
+`foundry-task-orchestration-actor show` prints the table for a given sidecar:
+
+| rendering | example |
+|---|---|
+| actor name | `ACME.PARTS.CAP.SUP.007.WID-task-orchestration` |
+| registry path | `acme.parts/sup.007.wid` |
+| component image | `<registry>/acme.parts/sup.007.wid/backend:<version>` |
+| test image | `<registry>/acme.parts/sup.007.wid/backend/tests:<version>` |
+| image name the base manifest carries | `acme.parts.cap.sup.007.wid-backend` |
+| namespace / papeete-deploy product | `test-task-042` |
+| component Deployment / Service | `test-task-042-sup-007-wid-backend` |
+| what the test Job gets | `BACKEND_URL=http://test-task-042-sup-007-wid-backend` |
+
+**The image ref is a three-way contract.** Both peers publish refs this actor parses back apart by
+path segment; nothing is re-derived or looked up.
+
+## Settings
+
+Environment, read once at boot by `serve`; constructor keywords on `Settings` for an embedder.
+
+| variable | default | |
+|---|---|---|
+| `IMAGE_REGISTRY` | — | where component and test images are pulled from; required once a run deploys |
+| `IMPLEMENTATION_URL` / `TESTING_URL` | sidecar, else derived | |
+| `MAX_ATTEMPTS` | `3` | |
+| `DOOR_CALL_TIMEOUT_S` | `2400` | implement-task, test-task |
+| `PROPOSE_TIMEOUT_S` / `ASSESS_TIMEOUT_S` | `900` | round 0 |
+| `DEPLOYMENT_READY_TIMEOUT_S` / `TEST_JOB_TIMEOUT_S` | `600` | |
+| `KUBE_CONTEXT` | `in-cluster` | the context `serve` writes from the ServiceAccount |
+| `IMAGE_PULL_SECRET` | `acr-pull` | copied from this Pod's namespace into each run's |
+| `BASE_BRANCH` | `main` | what the PRs target |
+
+`GITHUB_TOKEN` is the one credential: read on the implementation repo (the per-attempt clone),
+`pull-requests:write` on both peer repos, `contents:write` on the testing repo (a long test log is
+committed beside the tests and linked). No `CLAUDE_CODE_OAUTH_TOKEN` — nothing here runs a session.
+
+## Running in a cluster
+
+`serve` writes a kubeconfig from the Pod's projected ServiceAccount (token by path, so a rotation is
+picked up) under the context `KUBE_CONTEXT` names, before the door opens. Outside a cluster it
+writes nothing and says so. The ServiceAccount needs cluster-wide RBAC to create and delete
+namespaces and manage Deployments, Services, Secrets, ServiceAccounts, Jobs and Pods/logs in them —
+the namespace does not exist when the RBAC is written.
+
+## CLI
+
+```bash
+foundry-task-orchestration-actor lint .                              # the sidecar, and the cards if rendered
+foundry-task-orchestration-actor show . --registry reg.example.com   # every derived identifier
+foundry-task-orchestration-actor render-cards .                      # the four cards, from the wheel
+foundry-task-orchestration-actor serve .                             # boot it (needs the `serve` extra)
+```
+
+## Observability
+
+The same record schema as the implementation actor — `correlation.py` is byte-identical below its
+docstring: `{event: "step", step, phase, duration_ms}`, `{event: "event", step, **fields}`, with
+`correlation_id` (the W3C trace id, propagated to both peers via `traceparent`), `task_id`,
+`run_id` and `attempt` as structured metadata. Steps: `round-0`, `call-propose-acceptance`,
+`call-assess-task`, `call-implement-task`, `call-test-task`, `clone-implementation`,
+`deploy-pull-secret`, `deploy-platform-standin`, `deploy-component`, `run-test-job`, `teardown`,
+`open-pr`. The step names are free to change; the record shape is not.
+
+## Releasing, and which registry to pin
+
+Identical to the implementation actor's (ADR-FIA-0006): a `v*` tag publishes the wheel to PyPI
+(Trusted Publishing) and one image build to `ghcr.io/papeete-hub/foundry-task-orchestration-actor`
+and, when `vars.PRODUCT_IMAGE` names one, to a product's own registry. A manual run with a tag input
+backfills an image without touching PyPI or `latest`:
+
+```bash
+gh workflow run release.yml --ref main -f tag=v0.1.0
+```
+
+## Where this came from
+
+Extracted from one capability's hand-written task-orchestration repository. Behaviour was ported,
+with the capability's literals turned into derivations or sidecar declarations, round 0 added, and
+known drift fixed (ADR-FTOA-0001). Decisions live in `adr/`.
+
+## Development
+
+```bash
+uv run --extra dev pytest -q     # what CI runs
+uv build
+```
+
+There is no separate lint/format command configured in this repo.