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

{foundry_implementation_actor-0.2.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,6 +44,10 @@ 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:
@@ -56,6 +60,10 @@ Beside them, two folders of committed contract, both shipped in the wheel:
 
 ## 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: foundry-implementation-actor
-Version: 0.2.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>
@@ -97,6 +97,16 @@ 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.

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

@@ -77,6 +77,16 @@ 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.

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

@@ -1,6 +1,6 @@
 [project]
 name = "foundry-implementation-actor"
-version = "0.2.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.2.0 → foundry_implementation_actor-0.2.1}/src/foundry_implementation_actor/__init__.py

@@ -22,7 +22,7 @@ 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",
@@ -33,6 +33,7 @@ __all__ = [
     "HandlerError",
     "Report",
     "cards_path",
+    "conformance",
     "correlation",
     "grounding",
     "lint",

{foundry_implementation_actor-0.2.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.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_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.2.0 → foundry_implementation_actor-0.2.1}/uv.lock

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