foundry-task-orchestration-actor 0.1.0__py3-none-any.whl

foundry_task_orchestration_actor/__init__.py

@@ -0,0 +1,63 @@
+"""foundry-task-orchestration-actor — drive one capability's task from agreement to pull request.
+
+An actor, for one use, with a `papeete-actor` underneath. It holds a three amigos round between
+the testing and implementation actors, then drives implement → deploy → black-box test → retry,
+and opens the paired pull requests on a pass. It judges nothing: every step is a fixed rule, so its
+one door names no engine. The capability it serves is supplied by a sidecar
+(`actor-agentic-context.yaml`, `foundry-task-orchestration-actor/agentic-context/v1`), never by
+this package.
+
+Wiring one up is three lines:
+
+    from foundry_task_orchestration_actor import CapabilityConfig, make_orchestrate_task
+
+    config = CapabilityConfig.load(".")
+    actor = Actor.from_card(".", mailbox=mailbox,
+                            actions={"orchestrate-task": make_orchestrate_task(config)})
+
+`make_orchestrate_task` takes an optional `Settings` too; without one it reads the environment.
+
+Those lines are for embedding. A use that just wants the actor writes no Python at all: the image
+this package publishes renders the cards from the sidecar and runs `serve`, which is those lines
+plus the observability wiring and the in-cluster kubeconfig that used to be copied into every repo.
+"""
+from .config import (CapabilityConfig, ConfigError, Peer, Report, Secret, SecretTemplate,
+                     cards_path, lint, version)
+from .deploy import DeployError
+from .handler import HandlerError, make_orchestrate_task
+from .instance import render_cards
+from .peers import PeerError
+from .pulls import PullRequestError
+from .serve import ServeError, serve
+from .settings import Settings, SettingsError
+from . import conformance, correlation, deploy, instance, kubeconfig, peers, pulls, round0
+
+__all__ = [
+    "CapabilityConfig",
+    "ConfigError",
+    "DeployError",
+    "HandlerError",
+    "Peer",
+    "PeerError",
+    "PullRequestError",
+    "Report",
+    "Secret",
+    "SecretTemplate",
+    "ServeError",
+    "Settings",
+    "SettingsError",
+    "cards_path",
+    "conformance",
+    "correlation",
+    "deploy",
+    "instance",
+    "kubeconfig",
+    "lint",
+    "make_orchestrate_task",
+    "peers",
+    "pulls",
+    "render_cards",
+    "round0",
+    "serve",
+    "version",
+]

foundry_task_orchestration_actor/cards/actor-data.yaml

@@ -0,0 +1,91 @@
+# 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, the
+# surface two peers agreed on, and how far a run got. Nothing names a capability, a component or a
+# peer repository, 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 to orchestrate (e.g. "TASK-011")
+  - 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 — forwarded
+      unchanged to every peer door, never re-derived or fetched
+  - name: accepted
+    type: boolean
+    description: >-
+      whether the task was agreed, implemented, tested passing, and its pull request opened
+  - name: because
+    type: string
+    description: >-
+      why the orchestration did not succeed, in prose — the stage says where, this says what
+  - name: stage
+    type: enum
+    values: [round-0, implementation, testing, verdict]
+    description: >-
+      where a run stopped. round-0: the testing and implementation actors did not agree on an
+      acceptance surface, or one of them did not answer — nothing was built. implementation:
+      implement-task could not be reached, refused, or reported nothing to test. testing:
+      test-task could not be reached, refused, published nothing to run, or the ephemeral
+      deployment and test run failed. verdict: the tests kept failing on every attempt, or passed
+      and the pull request could not be opened
+  - name: attempts
+    type: integer
+    description: >-
+      how many implement-task -> test-task cycles this run used; 0 when round 0 stopped it
+  - name: verdict
+    type: string
+    description: >-
+      a summary of the final test verdict — the passed/total count, or the failing criteria on a
+      failure
+  - name: pr_url
+    type: string
+    description: the URL of the pull request opened on the implementation repository, once testing passed
+  - name: test_pr_url
+    type: string
+    description: >-
+      the URL of the paired pull request opened on the testing repository — titled with the same
+      [task_id] tag as pr_url's so the two are reviewed and merged together; absent if only the
+      first could be opened
+  - name: branch
+    type: string
+    description: >-
+      the branch the implementation actor's implement-task pushed to (impl/TASK-NNN) — present
+      whenever an implement-task call was accepted, whether or not testing passed
+  - name: test_branch
+    type: string
+    description: >-
+      the branch the testing actor's test-task pushed to (test/TASK-NNN) — present whenever a
+      test-task call was accepted, whether or not testing passed
+  - name: acceptance_surface
+    type: list
+    description: >-
+      the observable expectations the increment must satisfy, each with a stable id, a statement
+      of what must hold, and the handle a black-box caller reaches it through — proposed by the
+      testing actor in round 0, before anything was built. Once agreed, each expectation carries
+      the implementation actor's commitments that name it under `commitments`, and a commitment
+      naming none is appended as an entry of its own. On a round-0 failure it is the proposal as
+      made
+  - name: open_questions
+    type: list
+    description: >-
+      what the testing actor said the task does not determine — each a string, or an object with
+      `about` and `question`. Non-empty stops the run in round 0: it is for a human to answer, by
+      amending the task
+  - name: objections
+    type: list
+    description: >-
+      the implementation actor's objections to the proposed surface, one per expectation it cannot
+      meet, as its assess-task door returned them
+  - name: commitments
+    type: list
+    description: >-
+      what the implementation actor undertook to pin for the expectations it accepted, as its
+      assess-task door returned them — carried on a round-0 failure so nothing it offered is lost

foundry_task_orchestration_actor/cards/actor-message.yaml

@@ -0,0 +1,32 @@
+# 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.
+#
+# The two results are OUTCOMES of one door, so the binding closes both schemas: a field exclusive
+# to one (`pr_url`, `stage`) is what rules the other out. That is why `stage` is required on
+# failure and absent on success, rather than optional on both.
+message: papeete-actor-message/v1
+messages:
+  - name: orchestrate-task-cmd
+    intent: >-
+      ask this actor to drive a TASK-NNN card for the capability it serves through the three
+      amigos round, implementation, black-box testing and retries, to a pull request
+    references: [task_id, title, definition_of_done, context]
+    optional: [context]
+
+  - name: orchestration-succeeded-result
+    intent: >-
+      report that the task was agreed, implemented, tested passing against the agreed surface, and
+      that its paired pull requests were opened
+    references: [accepted, pr_url, test_pr_url, branch, test_branch, attempts, verdict,
+                 acceptance_surface]
+    optional: [test_pr_url]
+
+  - name: orchestration-failed-result
+    intent: >-
+      report where the task stopped and why, carrying whatever was known by then — including, when
+      round 0 stopped it, the questions or objections a human has to resolve
+    references: [accepted, because, stage, attempts, branch, test_branch, verdict,
+                 acceptance_surface, open_questions, objections, commitments]
+    optional: [branch, test_branch, verdict, acceptance_surface, open_questions, objections,
+               commitments]

foundry_task_orchestration_actor/cards/actor-synchronous-messaging.yaml

@@ -0,0 +1,38 @@
+# THE DOOR. `synchronous-messaging-doors/v1` — one action, and no engine on it.
+#
+# WHY NO ENGINE. Every decision behind this door is a fixed rule: stop on open questions or
+# objections, call the implementation and testing doors with the agreed surface, deploy, run, retry
+# on a red verdict up to a fixed number of attempts, open the PRs on a green one. There is nothing
+# to judge, so `Actor.receive()` calls the registered handler with `judged=None` and no sidecar of
+# this actor names an engine.
+#
+# WHY IT IS AN ACTION. It changes the world — namespaces are created and deleted, pull requests are
+# opened — and it is a promise to try, which is what an action is. It blocks for the whole run by
+# this pipeline's design: no callback door on any side, and escalation is this door's own refusal
+# with the objections, back to whoever called (ADR-FIA-0004 §5).
+manifest: synchronous-messaging-doors/v1
+actions:
+  - id: orchestrate-task
+    means: >-
+      the door for "drive TASK-NNN of the capability I serve, from agreement to pull request".
+      Send the task id, title, definition of done and, optionally, context — the caller supplies
+      everything, no task card is looked up here. First, round 0: I ask the testing actor's
+      propose-acceptance door what it intends to assert, naming the components my sidecar
+      declares; if it has open questions I stop, and the implementation actor is not asked. Then I
+      ask the implementation actor's assess-task door whether that surface can be delivered; if it
+      is not feasible, or it objects, I stop. Either way I hand back what they said, for a human to
+      resolve. Once they agree, I call implement-task and then test-task with the agreed
+      acceptance surface — on every attempt, not only the first — deploy the touched components
+      into an ephemeral test-<task_id> namespace, run the published test image against them, and
+      tear the namespace down. A passing verdict opens the paired pull requests on both
+      repositories and I stop. A failing verdict retries with the failing criteria as a
+      remediation context, up to a fixed number of attempts; no pull request is opened on a final
+      failure. I never merge, and I never write code or tests myself.
+    completion: >-
+      whether the task reached a passing verdict and had its pull requests opened (with the PR
+      urls, both branches, the attempts used, the verdict, and the agreed acceptance surface), or
+      did not — with why, the stage it stopped at, the attempts used, and whatever of the
+      branches, verdict and surface is known; when round 0 stopped it, also the open questions,
+      objections and commitments that did.
+    door_schema: orchestrate-task-cmd
+    completion_schema: [orchestration-succeeded-result, orchestration-failed-result]

foundry_task_orchestration_actor/cards/actor.yaml

@@ -0,0 +1,22 @@
+# 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 task-orchestration
+# 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.
+#
+# A use's cards are rendered from these at `docker build` time (`render-cards`): the three below
+# byte-for-byte, and this one with `name:` set to the use's own actor name and its description
+# extended with the capability and the two peers it drives.
+manifest: papeete-actor-manifest/v0
+name: foundry-task-orchestration-actor
+description: >-
+  Drives one TASK-NNN card for the business capability its sidecar names, from agreement to pull
+  request. First holds the three amigos round: asks the testing actor what it intends to assert,
+  asks the implementation actor whether that can be delivered, and stops with the open questions
+  or objections if they do not agree. Then calls implement-task and test-task with the agreed
+  acceptance surface, deploys the touched components into an ephemeral namespace, runs the
+  published test image against them, and retries with the failing criteria up to a fixed number
+  of attempts. Only on a passing verdict does it open the paired pull requests. Purely mechanical
+  coordination: it writes no code and no tests and merges nothing, so it names no engine — every
+  decision here is a fixed rule, not a session's judgement.

foundry_task_orchestration_actor/cli.py

@@ -0,0 +1,186 @@
+"""`foundry-task-orchestration-actor` — the gate, and the derivation table.
+
+Four subcommands. `lint` is what CI runs against a sidecar; `show` prints every rendering
+`config.py` derives from the two fields that are actually written down — the peers this instance
+will call and where, the image repositories it will deploy from, the namespace, Service URLs and
+Secrets an attempt will create — so an operator can check all of it before a run spends a single
+peer session, rather than by reading a running actor's logs after the fact.
+
+`render-cards` and `serve` are what make a use's whole repository one sidecar (ADR-FTOA-0001): the
+first writes the actor's four cards beside it from the definition in this wheel, the second boots
+the thing. Both run inside the image this package publishes; both work in a plain venv too.
+
+House rule: every published package in this ecosystem ships a CLI named exactly the package.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import conformance
+from .config import CapabilityConfig, ConfigError, lint, version
+from .instance import render_cards
+from .serve import DEFAULT_PORT, ServeError, serve
+from .settings import ENV, Settings, SettingsError
+
+_REGISTRY_PLACEHOLDER = "<registry>"
+_SAMPLE_TASK = "TASK-NNN"
+
+
+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.
+    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:
+        print(f"  FAIL {error}")
+    if not report.ok:
+        print(f"✗ {len(report.errors)} error(s)")
+        return 1
+    for line in report.oks:
+        print(f"  ok   {line}")
+    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
+
+
+def _cmd_show(args: argparse.Namespace) -> int:
+    try:
+        config = CapabilityConfig.load(Path(args.folder))
+        settings = Settings.from_env()
+    except (ConfigError, SettingsError) as e:
+        print(f"  FAIL {e}")
+        return 2
+    registry = args.registry or settings.image_registry or _REGISTRY_PLACEHOLDER
+    run_id = config.run_id(_SAMPLE_TASK)
+
+    rows = [
+        ("capability", config.capability),
+        ("source_repo", config.source_repo),
+        ("actor name", config.actor_name),
+        ("registry path", config.capability_path),
+        ("workload prefix", config.workload_prefix),
+        ("clone prefix", config.clone_prefix(_SAMPLE_TASK)),
+        ("components (round 0)", ", ".join(config.components)),
+    ]
+    width = max(len(label) for label, _ in rows)
+    for label, value in rows:
+        print(f"  {label:<{width}}  {value}")
+
+    print("\n  peers")
+    for peer in (config.implementation, config.testing):
+        url = settings.peer_url(config, peer.role)
+        override = ENV[f"{peer.role}_url"]
+        url_from = (f"${override}" if url != peer.url
+                    else "sidecar" if peer.declared_url else "derived")
+        print(f"    {peer.role}")
+        print(f"      repo  {peer.repo}  ({'sidecar' if peer.declared_repo else 'derived'})")
+        print(f"      url   {url}  ({url_from})")
+
+    print(f"\n  one attempt at {_SAMPLE_TASK}")
+    print(f"    namespace / product  {run_id}")
+    print(f"    implementation clone {config.implementation.repo}@impl/{_SAMPLE_TASK}")
+    print(f"    platform stand-in    "
+          f"{config.platform_folder if config.platform is not None else '(none declared)'}")
+    for component in config.components:
+        print(f"    {component}")
+        print(f"      image name    {config.image_name(component)}")
+        print(f"      image         {config.image_repository(registry, component)}:<version>")
+        print(f"      test image    {config.image_repository(registry, component)}/tests:<version>")
+        print(f"      deployment    {config.prefixed(run_id, config.workload_name(component))}")
+        print(f"      service url   {config.service_url(run_id, component)}")
+        for secret in config.render_secrets(run_id, component):
+            print(f"      secret        {secret.name}  ({', '.join(sorted(secret.string_data))})")
+    return 0
+
+
+def _cmd_render_cards(args: argparse.Namespace) -> int:
+    # The step that deletes the hand copy. Run at `docker build` time, right after the sidecar is
+    # COPY'd in: from then on the cards in that folder came from a version, not from an editor.
+    try:
+        config = CapabilityConfig.load(Path(args.folder))
+    except ConfigError as e:
+        print(f"  FAIL {e}")
+        return 2
+    try:
+        written = render_cards(config, Path(args.folder))
+    except FileNotFoundError as e:
+        print(f"  FAIL {e}")
+        return 2
+    for path in written:
+        print(f"  ok   rendered {path}")
+    print(f"✓ {config.actor_name} — four cards from the definition in "
+          f"foundry-task-orchestration-actor=={version()}")
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    # No try/except around the boot itself. A misconfigured actor that starts anyway and refuses
+    # every caller at the door is strictly worse than a pod that crash-loops with the reason on
+    # stdout, which is what an uncaught error produces here.
+    try:
+        serve(Path(args.folder), port=args.port)
+    except (ConfigError, SettingsError, ServeError) as e:
+        print(f"  FAIL {e}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="foundry-task-orchestration-actor",
+        description="Inspect, validate and run one capability's task-orchestration actor.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    lint_parser = sub.add_parser(
+        "lint",
+        help="validate a sidecar against foundry-task-orchestration-actor/agentic-context/v1")
+    lint_parser.add_argument(
+        "folder", nargs="?", default=".",
+        help="the actor's folder, or the sidecar file itself (default: .)")
+    lint_parser.set_defaults(func=_cmd_lint)
+
+    show_parser = sub.add_parser(
+        "show", help="print every identifier derived from the sidecar and the environment")
+    show_parser.add_argument("folder", nargs="?", default=".")
+    show_parser.add_argument(
+        "--registry",
+        help=f"render image refs against this registry (default: $IMAGE_REGISTRY, else "
+             f"{_REGISTRY_PLACEHOLDER})")
+    show_parser.set_defaults(func=_cmd_show)
+
+    render_parser = sub.add_parser(
+        "render-cards",
+        help="write the actor's four cards into a use's folder, from the definition in this wheel")
+    render_parser.add_argument(
+        "folder", nargs="?", default=".",
+        help="the folder holding this use's actor-agentic-context.yaml (default: .)")
+    render_parser.set_defaults(func=_cmd_render_cards)
+
+    serve_parser = sub.add_parser(
+        "serve", help="boot this actor and answer its door (needs the `serve` extra)")
+    serve_parser.add_argument(
+        "folder", nargs="?", default=".",
+        help="the folder holding this use's sidecar and cards (default: .)")
+    serve_parser.add_argument(
+        "--port", type=int, default=None,
+        help=f"override $PORT (default: $PORT, else {DEFAULT_PORT})")
+    serve_parser.set_defaults(func=_cmd_serve)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())