foundry-implementation-actor 0.1.0__tar.gz → 0.2.1__tar.gz

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/.github/workflows/ci.yml

@@ -32,6 +32,16 @@ jobs:
             --registry reg.example.com | tee /tmp/show.txt
           grep -q 'reg.example.com/acme.parts/sup.007.wid/backend:<version>' /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. A card folder left out of the build passes every test in tests/ and
+        # makes the name a claim the artifact cannot honour. `papeete-actor-synchronous-messaging`
+        # is already a runtime dependency, so its gate is in the probe venv with nothing to add.
+        run: |
+          /tmp/probe/bin/papeete-actor-synchronous-messaging lint-card \
+            "$(/tmp/probe/bin/python -c 'from foundry_implementation_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.

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/.github/workflows/release.yml

@@ -29,6 +29,15 @@ jobs:
           uv pip install --python /tmp/probe/bin/python -q dist/*.whl
           /tmp/probe/bin/foundry-implementation-actor lint tests/fixtures/valid
 
+      - 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_implementation_actor import cards_path; print(cards_path())')"
+
       - name: grounding renders a CLAUDE.md whose imports resolve
         # BEFORE the upload, not after. A wheel that ships without its schema, or whose grounding
         # emits an @-import to a file it never wrote, produces sessions grounded in nothing that

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/CLAUDE.md

@@ -29,7 +29,7 @@ There is no separate lint/format command configured in this repo.
 
 ## Architecture
 
-Six modules under `src/foundry_implementation_actor/`:
+Seven modules under `src/foundry_implementation_actor/`:
 
 - **`config.py`** — `CapabilityConfig`. The heart. Loads the sidecar and derives **every**
   rendering of the capability id from two declared fields (`capability`, `source_repo`). Also
@@ -44,10 +44,30 @@ Six modules under `src/foundry_implementation_actor/`:
   opens a pull request.
 - **`correlation.py`** — the two ids and the step vocabulary. Moved **verbatim** from the repo this
   was extracted from; its code below the docstring is byte-identical.
+- **`conformance.py`** — `check(folder)`. Compares a use's cards against the definition's, on
+  the derived wire contract only (door ids, each door's request/completion schema and engine).
+  Prose and `actor.yaml`'s `name:` are deliberately not compared — a use should name its own
+  capability. `lint` runs it beside the sidecar gate.
 - **`cli.py`** — argparse wiring only, no logic of its own.
 
+Beside them, two folders of committed contract, both shipped in the wheel:
+
+- **`schemas/agentic-context.schema.yaml`** — the sidecar contract this package owns, which
+  `lint` checks a use against.
+- **`cards/`** — the actor's own four cards: what this actor IS, as opposed to which capability a
+  use of it serves. `cards_path()` returns the folder. They name no capability, and they are what
+  a spawned instance would be rendered from once a use is not a static repository.
+
 ## Core invariants that any change must preserve
 
+- **A use's cards are a hand copy, and hand copies drift.** Both folders pass `lint-card`
+  independently, and neither gate looks at the other — so a definition that gains a field leaves
+  every un-updated use linting green and refusing callers at runtime. `conformance.check` is the
+  only thing that catches it. Compare the DERIVED contract, never the prose.
+- **The `-actor` suffix is a claim, and it is checked.** `ADR-ECO-0022`: a package ending in
+  `-actor` asserts a `papeete-actor` underneath, and one that ships no conformant card is
+  misnamed. `tests/test_cards.py` runs `lint-card` on `cards/` in the suite; CI and the release
+  workflow run it again against the built wheel, so the cards cannot silently stop shipping.
 - **No capability literal, ever.** `tests/test_portability.py` greps `src/` for the originating
   instance's identifiers *and* for any knowledge tool name (`kpack`, `kontract`, …), and fails on
   either. The tools a capability grounds itself in are the consumer's dependencies. A fourth

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: foundry-implementation-actor
-Version: 0.1.0
+Version: 0.2.1
 Summary: Runs a headless Claude Code implementation session against one capability's own repo — a papeete-actor for one use, with the capability supplied by a sidecar.
 Project-URL: Homepage, https://github.com/papeete-hub/foundry-implementation-actor
 Author-email: Papeete Consulting <yoann.remy@outlook.com>
@@ -34,8 +34,8 @@ pip install foundry-implementation-actor
 
 ## What it is
 
-The machinery. It carries **no capability of its own** — the capability it serves arrives in a
-sidecar the consuming repo writes:
+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
@@ -74,6 +74,43 @@ actor = Actor.from_card(".", mailbox=mailbox,
 A second capability instantiates the same actor by writing that file. Nothing here is subclassed,
 hooked, or configured with a strategy object — there is one shape, and it is this one.
 
+## The definition, and a use
+
+This package is where the actor is **defined**. `src/foundry_implementation_actor/cards/` holds its
+four cards — who it is, the data it knows, the messages it exchanges, and the one `implement-task`
+door it answers — and they ship in the wheel, reachable as `cards_path()`. They name no capability,
+because which capability an instance serves is not part of what the actor *is*.
+
+A **use** of this actor is one capability's own folder: its own copy of those four cards, named for
+the capability it serves, beside the `actor-agentic-context.yaml` that binds it to that capability's
+repository and knowledge base. Today that folder is a static repository, and the copy is made by
+hand. Once an instance can be spawned from a capability id alone, the cards here are what it would
+be rendered from — which is why they live in the wheel rather than in an `examples/` folder.
+
+The split is what the name asserts. `ADR-ECO-0022` makes the `-actor` suffix an obligation: a
+package ending in `-actor` claims a `papeete-actor` underneath, *"and a `<use>-<tier>-actor` that
+ships no conformant card is misnamed, not merely unusual."* `tests/test_cards.py` runs that check
+in the suite, and CI runs it again against the built wheel:
+
+```bash
+papeete-actor-synchronous-messaging lint-card \
+  "$(python -c 'from foundry_implementation_actor import cards_path; print(cards_path())')"
+```
+
+A use's copy is made by hand, so it can drift: both folders pass `lint-card` independently, and
+neither gate has an opinion about the other. `foundry-implementation-actor lint` therefore runs a
+second check — `conformance.check` — comparing the use's cards against the definition's on the
+**derived wire contract**: the set of doors, and each door's `request_schema`, `completion_schema`
+and `engine`. Those derivations already fold in the data dictionary and the message catalog, so a
+renamed item or a changed reference lands in the payload a caller is validated against.
+
+Prose is not compared, on purpose: a use *should* name its real capability and its real peers, and
+`actor.yaml`'s `name:` is its own identity and is required to differ.
+
+Because the cards sit under `src/`, `tests/test_portability.py` greps them too — a capability id or
+a knowledge tool name written into the actor's own definition fails the build exactly as it would
+in the code.
+
 ## What one request does
 
 ```

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/README.md

@@ -14,8 +14,8 @@ pip install foundry-implementation-actor
 
 ## What it is
 
-The machinery. It carries **no capability of its own** — the capability it serves arrives in a
-sidecar the consuming repo writes:
+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
@@ -54,6 +54,43 @@ actor = Actor.from_card(".", mailbox=mailbox,
 A second capability instantiates the same actor by writing that file. Nothing here is subclassed,
 hooked, or configured with a strategy object — there is one shape, and it is this one.
 
+## The definition, and a use
+
+This package is where the actor is **defined**. `src/foundry_implementation_actor/cards/` holds its
+four cards — who it is, the data it knows, the messages it exchanges, and the one `implement-task`
+door it answers — and they ship in the wheel, reachable as `cards_path()`. They name no capability,
+because which capability an instance serves is not part of what the actor *is*.
+
+A **use** of this actor is one capability's own folder: its own copy of those four cards, named for
+the capability it serves, beside the `actor-agentic-context.yaml` that binds it to that capability's
+repository and knowledge base. Today that folder is a static repository, and the copy is made by
+hand. Once an instance can be spawned from a capability id alone, the cards here are what it would
+be rendered from — which is why they live in the wheel rather than in an `examples/` folder.
+
+The split is what the name asserts. `ADR-ECO-0022` makes the `-actor` suffix an obligation: a
+package ending in `-actor` claims a `papeete-actor` underneath, *"and a `<use>-<tier>-actor` that
+ships no conformant card is misnamed, not merely unusual."* `tests/test_cards.py` runs that check
+in the suite, and CI runs it again against the built wheel:
+
+```bash
+papeete-actor-synchronous-messaging lint-card \
+  "$(python -c 'from foundry_implementation_actor import cards_path; print(cards_path())')"
+```
+
+A use's copy is made by hand, so it can drift: both folders pass `lint-card` independently, and
+neither gate has an opinion about the other. `foundry-implementation-actor lint` therefore runs a
+second check — `conformance.check` — comparing the use's cards against the definition's on the
+**derived wire contract**: the set of doors, and each door's `request_schema`, `completion_schema`
+and `engine`. Those derivations already fold in the data dictionary and the message catalog, so a
+renamed item or a changed reference lands in the payload a caller is validated against.
+
+Prose is not compared, on purpose: a use *should* name its real capability and its real peers, and
+`actor.yaml`'s `name:` is its own identity and is required to differ.
+
+Because the cards sit under `src/`, `tests/test_portability.py` greps them too — a capability id or
+a knowledge tool name written into the actor's own definition fails the build exactly as it would
+in the code.
+
 ## What one request does
 
 ```

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "foundry-implementation-actor"
-version = "0.1.0"
+version = "0.2.1"
 description = "Runs a headless Claude Code implementation session against one capability's own repo — a papeete-actor for one use, with the capability supplied by a sidecar."
 readme = "README.md"
 requires-python = ">=3.11"

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/src/foundry_implementation_actor/__init__.py

@@ -18,10 +18,11 @@ Wiring one up is four lines:
 `correlation` is exported too — an entrypoint installs its filter on the root logger's handlers
 after configuring observability, so every record the process emits carries this request's ids.
 """
-from .config import CapabilityConfig, Component, ConfigError, Grounding, Report, lint
+from .config import (CapabilityConfig, Component, ConfigError, Grounding, Report,
+                     cards_path, lint)
 from .engine import ClaudeCodeEngine
 from .handler import HandlerError, make_implement_task
-from . import correlation, grounding
+from . import conformance, correlation, grounding
 
 __all__ = [
     "CapabilityConfig",
@@ -31,6 +32,8 @@ __all__ = [
     "Grounding",
     "HandlerError",
     "Report",
+    "cards_path",
+    "conformance",
     "correlation",
     "grounding",
     "lint",

foundry_implementation_actor-0.2.1/src/foundry_implementation_actor/cards/actor-data.yaml

@@ -0,0 +1,38 @@
+# WHAT DATA EXISTS. `papeete-actor-data/v0`, owned by `papeete-actor-message` — a named, minimally
+# typed dictionary. Every field here belongs to the ACTOR, not to any capability: a task id, the
+# caller's statement of the task, and what came back. Nothing names a capability, a component or a
+# knowledge tool, because none of those are known until a sidecar supplies them.
+data: papeete-actor-data/v0
+items:
+  - name: task_id
+    type: string
+    description: the TASK-NNN card id this actor was asked about (e.g. "TASK-009")
+  - name: title
+    type: string
+    description: the task's short title/summary, supplied by the caller — no card lookup is performed here
+  - name: context
+    type: string
+    description: free-text elaboration beyond the title — background, constraints, links; optional
+  - name: definition_of_done
+    type: list
+    description: the acceptance criteria this task must satisfy, as the caller states them
+  - name: remediation_context
+    type: string
+    description: >-
+      on a retry, the prior attempt's failing test criteria — what the implementing session should
+      fix this time; optional, absent on a first attempt
+  - name: accepted
+    type: boolean
+    description: whether the implement-task request was accepted, pushed, and its images published
+  - name: because
+    type: string
+    description: why a request was refused (containment violation, nothing staged, ...)
+  - name: branch
+    type: string
+    description: the branch the implementation was pushed to (impl/TASK-NNN)
+  - name: images
+    type: list
+    description: >-
+      the full name:version ref of each touched component's published image (e.g.
+      "acme.parts.cap.sup.007.wid-backend:0.1.0-TASK-011-a1b2c3d"), by convention — no other actor
+      is ever told these tags explicitly

foundry_implementation_actor-0.2.1/src/foundry_implementation_actor/cards/actor-message.yaml

@@ -0,0 +1,17 @@
+# WHAT MESSAGES EXIST. `papeete-actor-message/v1`, owned by `papeete-actor-message` — named
+# messages, each a pure regrouping of references into the data dictionary, under an intent.
+# Wire-agnostic by that package's own design: WHAT a message is, never HOW it is carried.
+message: papeete-actor-message/v1
+messages:
+  - name: implement-task-cmd
+    intent: ask this actor to implement a TASK-NNN card for the capability it serves
+    references: [task_id, title, definition_of_done, context, remediation_context]
+    optional: [context, remediation_context]
+
+  - name: task-implemented-result
+    intent: report that the task was implemented, pushed, and its touched components' images published
+    references: [accepted, branch, images]
+
+  - name: task-refused-result
+    intent: report that the task was not implemented, and why
+    references: [accepted, because]

foundry_implementation_actor-0.2.1/src/foundry_implementation_actor/cards/actor-synchronous-messaging.yaml

@@ -0,0 +1,21 @@
+# THE DOORS. `synchronous-messaging-doors/v1` — one non-deterministic door, and no queries.
+#
+# `engine: claude-code` is this actor kind's declared engine. A use's sidecar repeats it in its own
+# `engine:` field, and the entrypoint registers the engine under exactly that key — so a use whose
+# sidecar names a different engine is caught by its own card rather than at the first request.
+manifest: synchronous-messaging-doors/v1
+actions:
+  - id: implement-task
+    means: >-
+      the door for "implement TASK-NNN for the capability I serve". Send it here with the task id,
+      title, definition of done, and (optionally) context and remediation_context — the caller
+      supplies everything, no task card is looked up here. I clone my capability's repository into
+      my own private copy, ground myself in that capability's own standing context, judge how to
+      implement the task (writing only under whichever of my declared components it touches), then
+      commit and push to impl/TASK-NNN, and build each touched component's image in the cluster's
+      shared buildkit and push it to the registry, named and versioned by convention. I never open
+      a pull request — an orchestrating actor does, once a testing actor also confirms.
+    completion: whether I accepted, pushed, and published images (with the branch and image refs), or refused, and why.
+    door_schema: implement-task-cmd
+    completion_schema: [task-implemented-result, task-refused-result]
+    engine: claude-code

foundry_implementation_actor-0.2.1/src/foundry_implementation_actor/cards/actor.yaml

@@ -0,0 +1,19 @@
+# WHO. The actor this package defines — `papeete-actor-manifest/v0`, owned by `papeete-actor`.
+#
+# THIS FOLDER IS THE DEFINITION, NOT A USE. The four cards here say what a foundry implementation
+# actor IS: the data it knows, the messages it exchanges, and the one door it answers. They name no
+# capability, because which capability an instance serves is not part of what the actor is — that
+# is `actor-agentic-context.yaml`, supplied per use.
+#
+# One use of this actor is a folder carrying its own copy of these four cards, named for the
+# capability it serves, beside the sidecar that binds it to that capability's knowledge base. Today
+# that folder is a static repository; the cards here are what a spawned instance would be rendered
+# from once it is not.
+manifest: papeete-actor-manifest/v0
+name: foundry-implementation-actor
+description: >-
+  Implements one TASK-NNN card for the business capability its sidecar names. Clones that
+  capability's own repository into a private copy, grounds the session in the capability's own
+  standing context, and writes only under the components the sidecar declares — then commits,
+  pushes a branch, and publishes one image per component the task actually touched. Never opens a
+  pull request: an orchestrating actor does that, once a testing actor also confirms.

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/src/foundry_implementation_actor/cli.py

@@ -13,13 +13,22 @@ import argparse
 import sys
 from pathlib import Path
 
+from . import conformance
 from .config import CapabilityConfig, ConfigError, lint
 
 _REGISTRY_PLACEHOLDER = "<registry>"
 
 
 def _cmd_lint(args: argparse.Namespace) -> int:
+    # Two gates, one command. The sidecar says which capability this use serves; the cards say
+    # which actor it claims to be. A use can be wrong about either independently, and the second
+    # check is the only thing standing between a hand-copied card set and a caller being refused
+    # at a door — see `conformance.py`.
     report = lint(Path(args.folder))
+    conformance_report = conformance.check(Path(args.folder))
+    report.oks.extend(conformance_report.oks)
+    report.warns.extend(conformance_report.warns)
+    report.errors.extend(conformance_report.errors)
     for warning in report.warns:
         print(f"  ! {warning}")
     for error in report.errors:
@@ -29,7 +38,8 @@ def _cmd_lint(args: argparse.Namespace) -> int:
         return 1
     for line in report.oks:
         print(f"  ok   {line}")
-    print("✓ sidecar conforms")
+    checked_cards = any((Path(args.folder) / name).exists() for name in conformance.CARD_FILES)
+    print("✓ sidecar and cards conform" if checked_cards else "✓ sidecar conforms")
     return 0
 
 

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/src/foundry_implementation_actor/config.py

@@ -45,6 +45,7 @@ CONTRACT = "foundry-implementation-actor/agentic-context/v1"
 SIDECAR = "actor-agentic-context.yaml"
 
 _SCHEMA_PATH = Path(__file__).resolve().parent / "schemas" / "agentic-context.schema.yaml"
+_CARDS_PATH = Path(__file__).resolve().parent / "cards"
 
 # The segment a capability id carries to say "capability". It is dropped from the registry path
 # because the path position already says it — every other token of the id survives, across
@@ -56,6 +57,21 @@ _CAPABILITY_SEGMENT = "cap"
 _PLACEHOLDER = re.compile(r"\{([a-z_]+)\}")
 
 
+def cards_path() -> Path:
+    """The folder holding this actor's own four cards — its definition, shipped in the wheel.
+
+    The cards say what a foundry implementation actor IS: its data dictionary, its message
+    catalog, and the one door it answers. They name no capability, because which capability an
+    instance serves is not part of what the actor is — that is the sidecar, supplied per use.
+
+    A use is today a static folder carrying its own copy of these four, named for the capability
+    it serves. This path is what a spawned instance would be rendered from once it is not, and it
+    is what `papeete-actor-synchronous-messaging lint-card` is pointed at to check that the
+    `-actor` suffix in this package's name is a claim it actually honours (ADR-ECO-0022).
+    """
+    return _CARDS_PATH
+
+
 def load_schema() -> dict:
     """The contract, as committed source inside this package.
 

foundry_implementation_actor-0.2.1/src/foundry_implementation_actor/conformance.py

@@ -0,0 +1,119 @@
+"""Does this use still answer the same doors as the actor it claims to be?
+
+WHY THIS EXISTS. This package ships the actor's DEFINITION — four cards under `cards/` saying what
+a foundry implementation actor is. A USE is one capability's own folder, carrying its own copy of
+those four, named for the capability it serves. The copy is made by hand, because a use is a static
+repository today rather than something spawned from a capability id.
+
+A hand copy drifts. Both folders pass `lint-card` independently — each is a conformant actor — and
+neither gate has any opinion about the other. So the day the definition gains a field, renames a
+message, or changes a door's completion set, a use that was not updated keeps linting green and
+starts refusing callers at runtime, with the rejection surfacing at the door rather than here.
+
+WHAT IS COMPARED, AND WHAT IS NOT. Only what a caller can observe: the set of doors, and for each
+one its derived `request_schema`, its `completion_schema`, and the `engine` key it resolves
+through. Those derivations already fold in the data dictionary and the message catalog — a renamed
+data item, a changed type, a reference added to a message, all of it lands in the schema a caller is
+validated against — so comparing them separately would be comparing the same fact twice.
+
+PROSE IS NOT COMPARED, ON PURPOSE. A use's `means:` should name its real capability and its real
+peer actors; the definition's cannot, because it serves no capability and its cards are grepped for
+exactly such literals. The use's wording is the better one for anyone reading `describe`, and
+flattening it to the definition's would delete information. Nor is `actor.yaml`'s `name:`: that is
+the use's own identity, and it is REQUIRED to differ.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from papeete_actor_synchronous_messaging import card as pas_card
+
+from .config import Report, cards_path
+
+CARD_FILES = ("actor.yaml", "actor-data.yaml", "actor-message.yaml",
+              "actor-synchronous-messaging.yaml")
+
+
+def check(folder: str | Path = ".") -> Report:
+    """Compare one use's cards against the definition this package ships."""
+    use = Path(folder)
+    report = Report(oks=[], warns=[], errors=[])
+
+    present = [name for name in CARD_FILES if (use / name).exists()]
+    if not present:
+        # Not an error. `lint` is also run against a sidecar on its own — in this package's own CI,
+        # among other places — and a folder with no cards is not a malformed use, just not a
+        # complete one.
+        report.warns.append(
+            f"{use}: no cards here, so nothing to compare — a use carries its own copy of the "
+            f"actor's four cards beside its sidecar"
+        )
+        return report
+    if len(present) != len(CARD_FILES):
+        missing = [name for name in CARD_FILES if name not in present]
+        report.errors.append(
+            f"{use}: an incomplete card set — missing {', '.join(missing)}. `Actor.from_card` "
+            f"opens exactly these four and never globs, so a use missing one does not boot."
+        )
+        return report
+
+    definition = cards_path()
+    if any(not (definition / name).exists() for name in CARD_FILES):
+        # A wheel that lost its cards. `lint-card` in CI and in the release workflow exists to stop
+        # that reaching PyPI; this turns the leftover case into a report rather than a traceback
+        # from inside a gate a consumer is running.
+        report.errors.append(
+            f"{definition}: this package's own cards are missing, so there is nothing to compare "
+            f"against. The build shipped without them — report it against the release."
+        )
+        return report
+
+    try:
+        theirs = pas_card.load(use)
+    except ValueError as e:
+        report.errors.append(f"{use}: its own cards do not pass the restriction, so they cannot "
+                             f"be compared: {e}")
+        return report
+    ours = pas_card.load(definition)
+
+    report.errors.extend(_compare(ours, theirs, "actions", use))
+    report.errors.extend(_compare(ours, theirs, "queries", use))
+    if not report.errors:
+        doors = ", ".join(sorted(theirs.actions) + sorted(theirs.queries))
+        report.oks.append(f"{use} answers the definition's doors, unchanged: {doors}")
+    return report
+
+
+def _compare(ours, theirs, kind: str, use: Path) -> list[str]:
+    """The differences in one door family, as messages. Empty means they agree."""
+    defined, used = getattr(ours, kind), getattr(theirs, kind)
+    errors = []
+
+    for extra in sorted(set(used) - set(defined)):
+        errors.append(f"{use}: {kind[:-1]} '{extra}' is not a door the definition declares — a use "
+                      f"answers the actor's doors, it does not add its own")
+    for absent in sorted(set(defined) - set(used)):
+        errors.append(f"{use}: {kind[:-1]} '{absent}' is missing — the definition declares it, so a "
+                      f"caller addressing this actor may send it")
+
+    for door in sorted(set(defined) & set(used)):
+        mine, yours = defined[door], used[door]
+        if mine.request_schema != yours.request_schema:
+            errors.append(
+                f"{use}: {kind[:-1]} '{door}' accepts a different payload than the definition. "
+                f"Its `door_schema` message and the data items that message references are what "
+                f"derive this, so one of the two drifted:\n"
+                f"      definition {mine.request_schema}\n"
+                f"      this use   {yours.request_schema}")
+        if mine.completion_schema != yours.completion_schema:
+            errors.append(
+                f"{use}: {kind[:-1]} '{door}' replies against a different completion set than the "
+                f"definition:\n"
+                f"      definition {mine.completion_schema}\n"
+                f"      this use   {yours.completion_schema}")
+        if mine.engine != yours.engine:
+            errors.append(
+                f"{use}: {kind[:-1]} '{door}' resolves through engine '{yours.engine}', the "
+                f"definition through '{mine.engine}' — the entrypoint registers the engine under "
+                f"the sidecar's `engine:` key, so these three must agree")
+    return errors

foundry_implementation_actor-0.2.1/tests/fixtures/valid/actor-data.yaml

@@ -0,0 +1,38 @@
+# WHAT DATA EXISTS. `papeete-actor-data/v0`, owned by `papeete-actor-message` — a named, minimally
+# typed dictionary. Every field here belongs to the ACTOR, not to any capability: a task id, the
+# caller's statement of the task, and what came back. Nothing names a capability, a component or a
+# knowledge tool, because none of those are known until a sidecar supplies them.
+data: papeete-actor-data/v0
+items:
+  - name: task_id
+    type: string
+    description: the TASK-NNN card id this actor was asked about (e.g. "TASK-009")
+  - name: title
+    type: string
+    description: the task's short title/summary, supplied by the caller — no card lookup is performed here
+  - name: context
+    type: string
+    description: free-text elaboration beyond the title — background, constraints, links; optional
+  - name: definition_of_done
+    type: list
+    description: the acceptance criteria this task must satisfy, as the caller states them
+  - name: remediation_context
+    type: string
+    description: >-
+      on a retry, the prior attempt's failing test criteria — what the implementing session should
+      fix this time; optional, absent on a first attempt
+  - name: accepted
+    type: boolean
+    description: whether the implement-task request was accepted, pushed, and its images published
+  - name: because
+    type: string
+    description: why a request was refused (containment violation, nothing staged, ...)
+  - name: branch
+    type: string
+    description: the branch the implementation was pushed to (impl/TASK-NNN)
+  - name: images
+    type: list
+    description: >-
+      the full name:version ref of each touched component's published image (e.g.
+      "acme.parts.cap.sup.007.wid-backend:0.1.0-TASK-011-a1b2c3d"), by convention — no other actor
+      is ever told these tags explicitly

foundry_implementation_actor-0.2.1/tests/fixtures/valid/actor-message.yaml

@@ -0,0 +1,17 @@
+# WHAT MESSAGES EXIST. `papeete-actor-message/v1`, owned by `papeete-actor-message` — named
+# messages, each a pure regrouping of references into the data dictionary, under an intent.
+# Wire-agnostic by that package's own design: WHAT a message is, never HOW it is carried.
+message: papeete-actor-message/v1
+messages:
+  - name: implement-task-cmd
+    intent: ask this actor to implement a TASK-NNN card for the capability it serves
+    references: [task_id, title, definition_of_done, context, remediation_context]
+    optional: [context, remediation_context]
+
+  - name: task-implemented-result
+    intent: report that the task was implemented, pushed, and its touched components' images published
+    references: [accepted, branch, images]
+
+  - name: task-refused-result
+    intent: report that the task was not implemented, and why
+    references: [accepted, because]

foundry_implementation_actor-0.2.1/tests/fixtures/valid/actor-synchronous-messaging.yaml

@@ -0,0 +1,21 @@
+# THE DOORS. `synchronous-messaging-doors/v1` — one non-deterministic door, and no queries.
+#
+# `engine: claude-code` is this actor kind's declared engine. A use's sidecar repeats it in its own
+# `engine:` field, and the entrypoint registers the engine under exactly that key — so a use whose
+# sidecar names a different engine is caught by its own card rather than at the first request.
+manifest: synchronous-messaging-doors/v1
+actions:
+  - id: implement-task
+    means: >-
+      the door for "implement TASK-NNN for the capability I serve". Send it here with the task id,
+      title, definition of done, and (optionally) context and remediation_context — the caller
+      supplies everything, no task card is looked up here. I clone my capability's repository into
+      my own private copy, ground myself in that capability's own standing context, judge how to
+      implement the task (writing only under whichever of my declared components it touches), then
+      commit and push to impl/TASK-NNN, and build each touched component's image in the cluster's
+      shared buildkit and push it to the registry, named and versioned by convention. I never open
+      a pull request — an orchestrating actor does, once a testing actor also confirms.
+    completion: whether I accepted, pushed, and published images (with the branch and image refs), or refused, and why.
+    door_schema: implement-task-cmd
+    completion_schema: [task-implemented-result, task-refused-result]
+    engine: claude-code

foundry_implementation_actor-0.2.1/tests/fixtures/valid/actor.yaml

@@ -0,0 +1,8 @@
+# A USE's identity card. The other three are copied verbatim from the definition this package
+# ships, which is exactly what `conformance.check` asserts — only this file is a use's own, and
+# only its `name:` and `description:` may differ.
+manifest: papeete-actor-manifest/v0
+name: ACME.PARTS.CAP.SUP.007.WID-implementation
+description: >-
+  Implements TASK-NNN cards for the fictional capability ACME.PARTS.CAP.SUP.007.WID. Exists so the
+  gates that run against the installed wheel have a complete use to check, not a sidecar alone.

foundry_implementation_actor-0.2.1/tests/test_cards.py

@@ -0,0 +1,49 @@
+"""The `-actor` suffix, checked rather than asserted.
+
+`ADR-ECO-0022` makes the suffix an obligation: "A package ending in `-actor` asserts a
+`papeete-actor` underneath, which lint-card can check. A future `<use>-<tier>-actor` that ships no
+conformant card is misnamed, not merely unusual."
+
+This file is that check. It runs the same gate `papeete-actor-synchronous-messaging lint-card` runs,
+against the cards this package ships — so the claim in the name is a test, not a sentence in a
+record.
+
+The cards live under `src/`, which means `test_portability.py` greps them too: a capability id or a
+knowledge tool name written into the actor's own definition fails the build exactly as it would in
+the code.
+"""
+from __future__ import annotations
+
+from papeete_actor_synchronous_messaging import card
+
+from foundry_implementation_actor import cards_path
+
+
+def test_the_package_ships_the_four_cards():
+    """A card folder is four files; `Actor.from_card` opens exactly these and never globs."""
+    folder = cards_path()
+    missing = [name for name in ("actor.yaml", "actor-data.yaml", "actor-message.yaml",
+                                 "actor-synchronous-messaging.yaml")
+               if not (folder / name).exists()]
+    assert not missing, f"the actor's definition is incomplete — missing: {', '.join(missing)}"
+
+
+def test_the_shipped_cards_are_conformant():
+    """The whole of the `-actor` claim: this folder is a papeete-actor, or the name is wrong."""
+    report = card.lint(cards_path())
+    assert not report.errors, ("the cards this package ships are not conformant:\n  "
+                               + "\n  ".join(report.errors))
+
+
+def test_the_door_names_the_engine_a_sidecar_must_declare():
+    """The card's door and a use's sidecar name the same engine key.
+
+    The entrypoint registers the engine under the sidecar's `engine:`, and the door resolves
+    through the card's. They are two statements of one fact, in two repos; this pins the half that
+    lives here so a use's `lint` failure is the only way they can disagree.
+    """
+    loaded = card.load(cards_path())
+    assert set(loaded.actions) == {"implement-task"}, (
+        f"expected the one implement-task door, got {sorted(loaded.actions)}")
+    engines = {offer.engine for offer in loaded.actions.values()}
+    assert engines == {"claude-code"}, f"expected the one claude-code door, got {engines}"

foundry_implementation_actor-0.2.1/tests/test_conformance.py

@@ -0,0 +1,111 @@
+"""A use answers the actor's doors, or it is not a use of that actor.
+
+The definition and a use are two folders, each independently conformant, and neither gate has any
+opinion about the other. `conformance.check` is the one that does — see `conformance.py` for what
+it compares and, just as deliberately, what it does not.
+"""
+from __future__ import annotations
+
+import shutil
+
+import pytest
+import yaml
+
+from foundry_implementation_actor import cards_path, conformance
+
+FIXTURE = "tests/fixtures/valid"
+
+
+def _use(tmp_path, source=None):
+    """A complete use folder, copied so a test can bend one thing in it."""
+    folder = tmp_path / "use"
+    folder.mkdir()
+    for name in conformance.CARD_FILES:
+        shutil.copy((source or cards_path()) / name, folder / name)
+    return folder
+
+
+def test_a_verbatim_copy_conforms(tmp_path):
+    assert conformance.check(_use(tmp_path)).ok
+
+
+def test_the_committed_fixture_conforms():
+    """The fixture the wheel gates run against is a real use, not a sidecar on its own."""
+    report = conformance.check(FIXTURE)
+    assert report.ok, report.errors
+    assert any("answers the definition's doors" in line for line in report.oks)
+
+
+def test_no_cards_warns_rather_than_fails(tmp_path):
+    """`lint` is also run against a bare sidecar. That is incomplete, not malformed."""
+    (tmp_path / "empty").mkdir()
+    report = conformance.check(tmp_path / "empty")
+    assert report.ok
+    assert any("no cards here" in w for w in report.warns)
+
+
+def test_an_incomplete_card_set_fails(tmp_path):
+    folder = _use(tmp_path)
+    (folder / "actor-message.yaml").unlink()
+    report = conformance.check(folder)
+    assert not report.ok
+    assert "actor-message.yaml" in report.errors[0]
+
+
+def test_a_drifted_payload_is_caught(tmp_path):
+    """The whole point: the use still lints, and still answers a different door.
+
+    A reference dropped from the door's own message is the cheapest realistic drift — the card set
+    remains internally valid, so every existing gate stays green.
+    """
+    folder = _use(tmp_path)
+    path = folder / "actor-message.yaml"
+    doc = yaml.safe_load(path.read_text())
+    doc["messages"][0]["references"].remove("title")
+    path.write_text(yaml.safe_dump(doc, sort_keys=False))
+
+    report = conformance.check(folder)
+    assert not report.ok
+    assert any("accepts a different payload" in e for e in report.errors)
+
+
+def test_a_dropped_completion_outcome_is_caught(tmp_path):
+    folder = _use(tmp_path)
+    path = folder / "actor-synchronous-messaging.yaml"
+    doc = yaml.safe_load(path.read_text())
+    doc["actions"][0]["completion_schema"] = ["task-implemented-result"]
+    path.write_text(yaml.safe_dump(doc, sort_keys=False))
+
+    report = conformance.check(folder)
+    assert not report.ok
+    assert any("different completion set" in e for e in report.errors)
+
+
+def test_a_different_engine_is_caught(tmp_path):
+    folder = _use(tmp_path)
+    path = folder / "actor-synchronous-messaging.yaml"
+    doc = yaml.safe_load(path.read_text())
+    doc["actions"][0]["engine"] = "some-other-engine"
+    path.write_text(yaml.safe_dump(doc, sort_keys=False))
+
+    report = conformance.check(folder)
+    assert not report.ok
+    assert any("resolves through engine" in e for e in report.errors)
+
+
+def test_prose_and_identity_are_not_compared(tmp_path):
+    """A use SHOULD name its own capability and its own peers. That is not drift."""
+    folder = _use(tmp_path)
+
+    identity = folder / "actor.yaml"
+    doc = yaml.safe_load(identity.read_text())
+    doc["name"] = "ACME.PARTS.CAP.SUP.007.WID-implementation"
+    doc["description"] = "Implements TASK-NNN cards for ACME.PARTS.CAP.SUP.007.WID."
+    identity.write_text(yaml.safe_dump(doc, sort_keys=False))
+
+    doors = folder / "actor-synchronous-messaging.yaml"
+    doc = yaml.safe_load(doors.read_text())
+    doc["actions"][0]["means"] = "the door for 'implement TASK-NNN for ACME.PARTS.CAP.SUP.007.WID'."
+    doors.write_text(yaml.safe_dump(doc, sort_keys=False))
+
+    assert conformance.check(folder).ok

{foundry_implementation_actor-0.1.0 → foundry_implementation_actor-0.2.1}/uv.lock

@@ -13,7 +13,7 @@ wheels = [
 
 [[package]]
 name = "foundry-implementation-actor"
-version = "0.1.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "papeete-actor-synchronous-messaging" },