pgc-runtime 3.0.0__tar.gz → 5.0.0__tar.gz

{pgc_runtime-3.0.0/pgc_runtime.egg-info → pgc_runtime-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgc-runtime
-Version: 3.0.0
+Version: 5.0.0
 Summary: PGC protocol runtime — executes a sealed snapshot as governed DAG traversal and emits traces (import package: runtime)
 Author-email: Bhash Ganti <bachipeachy@gmail.com>
 License-Expression: Apache-2.0
@@ -22,6 +22,8 @@ License-File: LICENSE
 License-File: NOTICE
 Provides-Extra: reference
 Requires-Dist: pgc-governance>=2.0.0; extra == "reference"
+Provides-Extra: render
+Requires-Dist: pgc-inspector>=5.0.0; extra == "render"
 Dynamic: license-file
 
 # protocol_runtime
@@ -78,17 +80,17 @@ payload         external input (JSON)
 data-root       the state storage boundary; one data root is one instance
 ```
 
-A run writes an append-only trace alongside the state its declared side effects produce:
+A run writes an append-only trace beside the state its declared side effects produce, both under
+the data root:
 
 ```
-traces/<TRACE_ID>/
-    <TRACE_ID>.jsonl    append-only execution log
-    <TRACE_ID>.md       human-readable summary
-    <TRACE_ID>.png      the execution path, rendered
-
-data/
-    registry/           idempotent state
-    events/             append-only history
+<data-root>/traces/<domain>/<WF>/<TRACE_ID>/
+    <TRACE_ID>.jsonl    append-only execution log, one SCHEMA_TRACE_EVENT_V1 event per line
+    <TRACE_ID>.png      the path the run took, drawn only on request (`run --behavior-logic`,
+                        or `behavior-logic <trace>`)
+
+<data-root>/<domain>/<subdomain>/
+    the stores the domain's runtime binding declares
 ```
 
 ## Running
@@ -100,15 +102,18 @@ data/
 ./run.sh examine /abs/trace.jsonl
 ```
 
-`run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
-subcommands:
+`run.sh` wraps the CLI, also installed as the `protocol_runtime` console script:
 
 | command | what it does |
 |---|---|
 | `run` | execute a workflow against a data root |
+| `replay` | re-execute a run from its recorded outcomes and compare it with the original |
+| `conformance` | run a compiled domain's test vectors; report each transform proven, unproven or refused |
 | `boot` | warm-boot the assembled snapshot — load and hash-verify every manifest domain |
-| `examine` | analyze a completed trace file |
-| `behavior-logic` | render the execution path from a completed trace as a PNG |
+| `coordinator` | serve as the coordinating node of a federated node group |
+| `worker` | serve as a worker node of a federated node group |
+| `examine` | read a completed trace: its path by node, contracts, results, events and errors |
+| `behavior-logic` | render a completed trace as a PNG: the path, each route's outcome, and why each node decided as far as the trace records it (drawn from the inspector's `si.execution.explain`; needs `pgc-runtime[render]`) |
 
 `PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
 roots on `PYTHONPATH` for domain capability implementations.
@@ -117,6 +122,12 @@ roots on `PYTHONPATH` for domain capability implementations.
 establishes that the snapshot is intact and executable before any workflow runs. A surface-only
 snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
 
+**A process verifies a snapshot once.** `runtime.api` keeps a booted snapshot resident and runs
+against it as often as it is asked. A rewritten manifest, or a different trust anchor or profile
+root, is verified afresh, and a snapshot that no longer verifies is refused. `boot` itself always
+performs the full determination. A governed run then costs a few milliseconds, not a third of a
+second.
+
 **A data root is an instance, not an interface.** Two data roots against the same snapshot are two
 independent instances of the same governed behavior.
 
@@ -128,6 +139,21 @@ invoking transforms, applying side effects — and routes on the declared outcom
 nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
 on those.
 
+**A workflow may run one contract at several places.** Each place is a node key, and the contract
+it runs is named separately. The compiler seals each place's routing on its own, and refuses a sealed
+dispatch that does not realize every transition declared at that node. Routing is by node, and the
+trace names the place that ran.
+
+**Not every step is determined by its inputs.** A transform is a deterministic atom, a
+non-deterministic atom, or a molecule, and a different constitution governs each. A molecule has no
+implementation: the runtime runs its declared steps. A non-deterministic atom's result is recorded
+where it is produced, and `replay` substitutes the recorded result, so a run is reproducible even
+when a step is not.
+
+**One snapshot can run across nodes.** Under a federated placement, a coordinator schedules units of
+work to workers over a shared store. Under the signed federated profile, every node verifies the
+snapshot's signature before it runs anything.
+
 Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
 the path actually taken through a graph that was fixed before the run began, which is what makes a
 run reproducible and reviewable after the fact.
@@ -164,8 +190,19 @@ export PGC_PLATFORM_ROOT=$PWD/software_governance
 pgc            # reports what is installed and whether the anchor resolves
 ```
 
-`PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
-(additional domains contributing their own `registry/structures`) are optional.
+`PGC_DOMAIN_ROOTS` names an additional domain contributing its own `registry/structures` — the
+directory that *directly contains* it, not the repository above it; pointing one level too high is a
+silent no-op. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot profiles, required by the
+assembler and the runtime alike.
+
+**Where a build writes is declared, not supplied.** Each build configuration names its root in
+`output_configuration.root`, and every layer's output consolidates there. The compiler does not read
+`PGC_SNAPSHOT_ROOT`; the runtime does, with its own meaning — the assembled snapshot to execute.
+
+`PGC_BUILD_ROOT` is accepted and reported and **nothing reads it**.
+
+The full sequence, with the repositories it needs, is in
+[`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).
 
 **Versioning.** Two schemes, and the published version follows the second.
 
@@ -175,7 +212,7 @@ pgc            # reports what is installed and whether the anchor resolves
   cycle is tagged `release-<N>`. This is not published.
 - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v3`**.
 
-**The published version is the public one: `v3` is `3.0.0`.** The standard the packages implement is a
+**The published version is the public one: `v4` is `4.0.0`.** The standard the packages implement is a
 separate artifact on its own track and is not this number.
 
 The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616

{pgc_runtime-3.0.0 → pgc_runtime-5.0.0}/README.md

@@ -52,17 +52,17 @@ payload         external input (JSON)
 data-root       the state storage boundary; one data root is one instance
 ```
 
-A run writes an append-only trace alongside the state its declared side effects produce:
+A run writes an append-only trace beside the state its declared side effects produce, both under
+the data root:
 
 ```
-traces/<TRACE_ID>/
-    <TRACE_ID>.jsonl    append-only execution log
-    <TRACE_ID>.md       human-readable summary
-    <TRACE_ID>.png      the execution path, rendered
-
-data/
-    registry/           idempotent state
-    events/             append-only history
+<data-root>/traces/<domain>/<WF>/<TRACE_ID>/
+    <TRACE_ID>.jsonl    append-only execution log, one SCHEMA_TRACE_EVENT_V1 event per line
+    <TRACE_ID>.png      the path the run took, drawn only on request (`run --behavior-logic`,
+                        or `behavior-logic <trace>`)
+
+<data-root>/<domain>/<subdomain>/
+    the stores the domain's runtime binding declares
 ```
 
 ## Running
@@ -74,15 +74,18 @@ data/
 ./run.sh examine /abs/trace.jsonl
 ```
 
-`run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
-subcommands:
+`run.sh` wraps the CLI, also installed as the `protocol_runtime` console script:
 
 | command | what it does |
 |---|---|
 | `run` | execute a workflow against a data root |
+| `replay` | re-execute a run from its recorded outcomes and compare it with the original |
+| `conformance` | run a compiled domain's test vectors; report each transform proven, unproven or refused |
 | `boot` | warm-boot the assembled snapshot — load and hash-verify every manifest domain |
-| `examine` | analyze a completed trace file |
-| `behavior-logic` | render the execution path from a completed trace as a PNG |
+| `coordinator` | serve as the coordinating node of a federated node group |
+| `worker` | serve as a worker node of a federated node group |
+| `examine` | read a completed trace: its path by node, contracts, results, events and errors |
+| `behavior-logic` | render a completed trace as a PNG: the path, each route's outcome, and why each node decided as far as the trace records it (drawn from the inspector's `si.execution.explain`; needs `pgc-runtime[render]`) |
 
 `PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
 roots on `PYTHONPATH` for domain capability implementations.
@@ -91,6 +94,12 @@ roots on `PYTHONPATH` for domain capability implementations.
 establishes that the snapshot is intact and executable before any workflow runs. A surface-only
 snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
 
+**A process verifies a snapshot once.** `runtime.api` keeps a booted snapshot resident and runs
+against it as often as it is asked. A rewritten manifest, or a different trust anchor or profile
+root, is verified afresh, and a snapshot that no longer verifies is refused. `boot` itself always
+performs the full determination. A governed run then costs a few milliseconds, not a third of a
+second.
+
 **A data root is an instance, not an interface.** Two data roots against the same snapshot are two
 independent instances of the same governed behavior.
 
@@ -102,6 +111,21 @@ invoking transforms, applying side effects — and routes on the declared outcom
 nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
 on those.
 
+**A workflow may run one contract at several places.** Each place is a node key, and the contract
+it runs is named separately. The compiler seals each place's routing on its own, and refuses a sealed
+dispatch that does not realize every transition declared at that node. Routing is by node, and the
+trace names the place that ran.
+
+**Not every step is determined by its inputs.** A transform is a deterministic atom, a
+non-deterministic atom, or a molecule, and a different constitution governs each. A molecule has no
+implementation: the runtime runs its declared steps. A non-deterministic atom's result is recorded
+where it is produced, and `replay` substitutes the recorded result, so a run is reproducible even
+when a step is not.
+
+**One snapshot can run across nodes.** Under a federated placement, a coordinator schedules units of
+work to workers over a shared store. Under the signed federated profile, every node verifies the
+snapshot's signature before it runs anything.
+
 Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
 the path actually taken through a graph that was fixed before the run began, which is what makes a
 run reproducible and reviewable after the fact.
@@ -138,8 +162,19 @@ export PGC_PLATFORM_ROOT=$PWD/software_governance
 pgc            # reports what is installed and whether the anchor resolves
 ```
 
-`PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
-(additional domains contributing their own `registry/structures`) are optional.
+`PGC_DOMAIN_ROOTS` names an additional domain contributing its own `registry/structures` — the
+directory that *directly contains* it, not the repository above it; pointing one level too high is a
+silent no-op. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot profiles, required by the
+assembler and the runtime alike.
+
+**Where a build writes is declared, not supplied.** Each build configuration names its root in
+`output_configuration.root`, and every layer's output consolidates there. The compiler does not read
+`PGC_SNAPSHOT_ROOT`; the runtime does, with its own meaning — the assembled snapshot to execute.
+
+`PGC_BUILD_ROOT` is accepted and reported and **nothing reads it**.
+
+The full sequence, with the repositories it needs, is in
+[`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).
 
 **Versioning.** Two schemes, and the published version follows the second.
 
@@ -149,7 +184,7 @@ pgc            # reports what is installed and whether the anchor resolves
   cycle is tagged `release-<N>`. This is not published.
 - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v3`**.
 
-**The published version is the public one: `v3` is `3.0.0`.** The standard the packages implement is a
+**The published version is the public one: `v4` is `4.0.0`.** The standard the packages implement is a
 separate artifact on its own track and is not this number.
 
 The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616

{pgc_runtime-3.0.0 → pgc_runtime-5.0.0/pgc_runtime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgc-runtime
-Version: 3.0.0
+Version: 5.0.0
 Summary: PGC protocol runtime — executes a sealed snapshot as governed DAG traversal and emits traces (import package: runtime)
 Author-email: Bhash Ganti <bachipeachy@gmail.com>
 License-Expression: Apache-2.0
@@ -22,6 +22,8 @@ License-File: LICENSE
 License-File: NOTICE
 Provides-Extra: reference
 Requires-Dist: pgc-governance>=2.0.0; extra == "reference"
+Provides-Extra: render
+Requires-Dist: pgc-inspector>=5.0.0; extra == "render"
 Dynamic: license-file
 
 # protocol_runtime
@@ -78,17 +80,17 @@ payload         external input (JSON)
 data-root       the state storage boundary; one data root is one instance
 ```
 
-A run writes an append-only trace alongside the state its declared side effects produce:
+A run writes an append-only trace beside the state its declared side effects produce, both under
+the data root:
 
 ```
-traces/<TRACE_ID>/
-    <TRACE_ID>.jsonl    append-only execution log
-    <TRACE_ID>.md       human-readable summary
-    <TRACE_ID>.png      the execution path, rendered
-
-data/
-    registry/           idempotent state
-    events/             append-only history
+<data-root>/traces/<domain>/<WF>/<TRACE_ID>/
+    <TRACE_ID>.jsonl    append-only execution log, one SCHEMA_TRACE_EVENT_V1 event per line
+    <TRACE_ID>.png      the path the run took, drawn only on request (`run --behavior-logic`,
+                        or `behavior-logic <trace>`)
+
+<data-root>/<domain>/<subdomain>/
+    the stores the domain's runtime binding declares
 ```
 
 ## Running
@@ -100,15 +102,18 @@ data/
 ./run.sh examine /abs/trace.jsonl
 ```
 
-`run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
-subcommands:
+`run.sh` wraps the CLI, also installed as the `protocol_runtime` console script:
 
 | command | what it does |
 |---|---|
 | `run` | execute a workflow against a data root |
+| `replay` | re-execute a run from its recorded outcomes and compare it with the original |
+| `conformance` | run a compiled domain's test vectors; report each transform proven, unproven or refused |
 | `boot` | warm-boot the assembled snapshot — load and hash-verify every manifest domain |
-| `examine` | analyze a completed trace file |
-| `behavior-logic` | render the execution path from a completed trace as a PNG |
+| `coordinator` | serve as the coordinating node of a federated node group |
+| `worker` | serve as a worker node of a federated node group |
+| `examine` | read a completed trace: its path by node, contracts, results, events and errors |
+| `behavior-logic` | render a completed trace as a PNG: the path, each route's outcome, and why each node decided as far as the trace records it (drawn from the inspector's `si.execution.explain`; needs `pgc-runtime[render]`) |
 
 `PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
 roots on `PYTHONPATH` for domain capability implementations.
@@ -117,6 +122,12 @@ roots on `PYTHONPATH` for domain capability implementations.
 establishes that the snapshot is intact and executable before any workflow runs. A surface-only
 snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
 
+**A process verifies a snapshot once.** `runtime.api` keeps a booted snapshot resident and runs
+against it as often as it is asked. A rewritten manifest, or a different trust anchor or profile
+root, is verified afresh, and a snapshot that no longer verifies is refused. `boot` itself always
+performs the full determination. A governed run then costs a few milliseconds, not a third of a
+second.
+
 **A data root is an instance, not an interface.** Two data roots against the same snapshot are two
 independent instances of the same governed behavior.
 
@@ -128,6 +139,21 @@ invoking transforms, applying side effects — and routes on the declared outcom
 nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
 on those.
 
+**A workflow may run one contract at several places.** Each place is a node key, and the contract
+it runs is named separately. The compiler seals each place's routing on its own, and refuses a sealed
+dispatch that does not realize every transition declared at that node. Routing is by node, and the
+trace names the place that ran.
+
+**Not every step is determined by its inputs.** A transform is a deterministic atom, a
+non-deterministic atom, or a molecule, and a different constitution governs each. A molecule has no
+implementation: the runtime runs its declared steps. A non-deterministic atom's result is recorded
+where it is produced, and `replay` substitutes the recorded result, so a run is reproducible even
+when a step is not.
+
+**One snapshot can run across nodes.** Under a federated placement, a coordinator schedules units of
+work to workers over a shared store. Under the signed federated profile, every node verifies the
+snapshot's signature before it runs anything.
+
 Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
 the path actually taken through a graph that was fixed before the run began, which is what makes a
 run reproducible and reviewable after the fact.
@@ -164,8 +190,19 @@ export PGC_PLATFORM_ROOT=$PWD/software_governance
 pgc            # reports what is installed and whether the anchor resolves
 ```
 
-`PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
-(additional domains contributing their own `registry/structures`) are optional.
+`PGC_DOMAIN_ROOTS` names an additional domain contributing its own `registry/structures` — the
+directory that *directly contains* it, not the repository above it; pointing one level too high is a
+silent no-op. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot profiles, required by the
+assembler and the runtime alike.
+
+**Where a build writes is declared, not supplied.** Each build configuration names its root in
+`output_configuration.root`, and every layer's output consolidates there. The compiler does not read
+`PGC_SNAPSHOT_ROOT`; the runtime does, with its own meaning — the assembled snapshot to execute.
+
+`PGC_BUILD_ROOT` is accepted and reported and **nothing reads it**.
+
+The full sequence, with the repositories it needs, is in
+[`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).
 
 **Versioning.** Two schemes, and the published version follows the second.
 
@@ -175,7 +212,7 @@ pgc            # reports what is installed and whether the anchor resolves
   cycle is tagged `release-<N>`. This is not published.
 - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v3`**.
 
-**The published version is the public one: `v3` is `3.0.0`.** The standard the packages implement is a
+**The published version is the public one: `v4` is `4.0.0`.** The standard the packages implement is a
 separate artifact on its own track and is not this number.
 
 The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616

{pgc_runtime-3.0.0 → pgc_runtime-5.0.0}/pgc_runtime.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ runtime/api.py
 runtime/boot.py
 runtime/cli.py
 runtime/conformance.py
+runtime/coordinator.py
 runtime/ct_errors.py
 runtime/ct_execute.py
 runtime/ct_executor.py
@@ -21,12 +22,16 @@ runtime/dispatcher.py
 runtime/evidence.py
 runtime/loader.py
 runtime/memory.py
+runtime/replay.py
 runtime/scheduler.py
 runtime/trace_viz.py
 runtime/examine/__init__.py
-runtime/examine/classifier.py
 runtime/examine/cli.py
-runtime/examine/hint_engine.py
-runtime/examine/locator.py
 runtime/examine/parser.py
-runtime/examine/reporter.py
+runtime/examine/reporter.py
+runtime/federation/__init__.py
+runtime/federation/client.py
+runtime/federation/coordinator.py
+runtime/federation/defaults.py
+runtime/federation/store.py
+runtime/federation/worker.py

{pgc_runtime-3.0.0 → pgc_runtime-5.0.0}/pgc_runtime.egg-info/requires.txt

@@ -1,3 +1,6 @@
 
 [reference]
 pgc-governance>=2.0.0
+
+[render]
+pgc-inspector>=5.0.0

{pgc_runtime-3.0.0 → pgc_runtime-5.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pgc-runtime"
-version = "3.0.0"
+version = "5.0.0"
 description = "PGC protocol runtime — executes a sealed snapshot as governed DAG traversal and emits traces (import package: runtime)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -32,6 +32,9 @@ dependencies = []
 
 [project.optional-dependencies]
 reference = ["pgc-governance>=2.0.0"]
+# The PNG projection (`--behavior-logic`, `behavior-logic`) draws the inspector's explanation of a
+# run. Execution never imports the inspector; only `runtime.trace_viz` does.
+render = ["pgc-inspector>=5.0.0"]
 
 [project.scripts]
 protocol_runtime = "runtime.cli:main"

pgc_runtime-5.0.0/runtime/api.py

@@ -0,0 +1,173 @@
+"""Programmatic runtime entry — run a workflow against a snapshot and return its result surface.
+
+This is the in-process core behind `runtime run`: it loads the domain snapshot, opens a trace, drives
+the workflow topology via `scheduler.run_wf`, and returns the terminal status **and result surface**. The
+CLI is a thin wrapper over it, and out-of-process consumers that need the workflow surface programmatically
+(e.g. the change-management validation pipeline) call this directly instead of shelling out and parsing
+stdout or data files.
+"""
+from __future__ import annotations
+
+import functools
+import os
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from runtime.boot import BootedSnapshot, boot, default_snapshot_root
+from runtime.evidence import TraceWriter, make_trace_id
+from runtime.scheduler import run_wf
+
+
+@dataclass(frozen=True)
+class RunResult:
+    status: str                     # terminal workflow outcome (e.g. "SUCCESS", "ACK", "VIOLATION")
+    surface: dict[str, Any]         # workflow result surface (the observable outputs)
+    trace_id: str
+    trace_dir: Path
+
+
+def run_workflow(
+    *,
+    wf_fqdn: str,
+    payload: dict[str, Any],
+    data_root: str | Path,
+    snapshot_root: str | Path | None = None,
+    replay_trace: str | Path | None = None,
+) -> RunResult:
+    """Warm-boot the assembled snapshot and execute a workflow; return `(status, surface, trace)`.
+
+    The snapshot (assembled product) is read-only input, verified via its manifest (root of trust).
+    All mutable output is scoped to the instance root `data_root`: CS state and `data_root/traces/`.
+    `snapshot_root` defaults to the sibling `../snapshot` when None.
+    Raises on load/vocab errors and propagates runtime exceptions (after recording them to the trace).
+    """
+    data_root = Path(data_root)
+    domain = wf_fqdn.split("::")[0]
+
+    booted = resident(snapshot_root)
+    pkg = booted.domains.get(domain)
+    if pkg is None:
+        raise RuntimeError(
+            f"Domain {domain!r} is not in the assembled snapshot "
+            f"(manifest domains: {sorted(booted.domains)})."
+        )
+
+    trace_id = make_trace_id(domain, wf_fqdn, payload)
+    wf_code = wf_fqdn.split("::")[-1]
+    trace_dir = data_root / "traces" / domain / wf_code / trace_id
+    trace_dir.mkdir(parents=True, exist_ok=True)
+
+    wf_addr = pkg.vocab.addr(wf_fqdn)   # KeyError if the WF is not in the snapshot vocab
+    writer = TraceWriter(trace_dir=trace_dir, trace_id=trace_id, domain=domain,
+                         wf_addr=wf_addr, wf_fqdn=wf_fqdn, snapshot_root=booted.snapshot_root,
+                         snapshot_id=booted.snapshot_id)
+    if replay_trace is not None:
+        # A replay substitutes each recorded outcome of an atom declared not deterministic, so it
+        # reproduces the original determination rather than drawing a new one.
+        from runtime.replay import recorded_outcomes
+        writer.replay_from(recorded_outcomes(Path(replay_trace)))
+    try:
+        status, surface = run_wf(wf_fqdn=wf_fqdn, payload=payload, pkg=pkg,
+                                 writer=writer, data_root=str(data_root))
+    except Exception as exc:
+        writer.error(str(exc))
+        raise
+    finally:
+        # The JSONL is the evidence. A picture of the path is a view of it, drawn on request
+        # (`run --behavior-logic`, or `behavior-logic <trace>`), never as a cost of every run.
+        writer.close()
+
+    return RunResult(status=status, surface=surface or {}, trace_id=trace_id, trace_dir=trace_dir)
+
+
+# Warm boot is load once, verify once. Every call booting afresh re-verified the whole snapshot from
+# its bytes on each run — about 60% of a run's time, repeated by every server, worker and suite that
+# calls this in a loop. The package a boot produces is frozen, and nothing reads the snapshot again
+# after it, so one verified boot serves every run against the same snapshot.
+#
+# What makes it the same snapshot is the manifest — its identity, and the file itself — together
+# with what acceptance was judged against: the trust anchor and the profile root. A rebuild in place
+# rewrites the manifest, so it is verified afresh. `boot()` itself is never cached: the CLI's `boot`
+# and anything asking for acceptance get the full determination every time.
+_RESIDENT: dict[tuple, BootedSnapshot] = {}
+_RESIDENT_LOCK = threading.Lock()
+_RESIDENT_LIMIT = 4
+
+
+def _resident_key(root: Path) -> tuple | None:
+    manifest = root / "manifest.json"
+    try:
+        stat = manifest.stat()
+    except FileNotFoundError:
+        return None
+    return (str(root), stat.st_mtime_ns, stat.st_size,
+            os.environ.get("PGC_TRUST_ROOT_PUBKEY"), os.environ.get("PGC_SNAPSHOT_PROFILES"))
+
+
+def resident(snapshot_root: str | Path | None = None) -> BootedSnapshot:
+    """The booted snapshot at `snapshot_root`, verified once per process and per manifest."""
+    given = Path(snapshot_root) if snapshot_root is not None else default_snapshot_root()
+    key = _resident_key(given.resolve())
+    if key is None:
+        return boot(given)          # no manifest: let boot refuse it, and say why
+    with _RESIDENT_LOCK:
+        booted = _RESIDENT.get(key)
+        if booted is None:
+            booted = boot(given)
+            if len(_RESIDENT) >= _RESIDENT_LIMIT:
+                _RESIDENT.pop(next(iter(_RESIDENT)))
+            _RESIDENT[key] = booted
+        return booted
+
+
+@functools.lru_cache(maxsize=8)
+def _placement(snapshot_root: Path) -> str | None:
+    # The snapshot is immutable, so what it was permitted cannot change under a running process.
+    from runtime.coordinator import sealed_placement_mode
+    return sealed_placement_mode(snapshot_root)
+
+
+def invoke_workflow(
+    *,
+    wf_fqdn: str,
+    payload: dict[str, Any],
+    data_root: str | Path,
+    snapshot_root: str | Path | None = None,
+) -> RunResult:
+    """Have a workflow executed wherever the sealed composition places execution.
+
+    The entry point for a party that receives work but is not itself where work is placed — the
+    interaction boundary. Under `FEDERATED_NODE` the unit goes to the coordinator named by
+    `PGC_COORDINATOR_URL` and a worker executes it; under every other placement it runs here through
+    `run_workflow`. Either way the result is the same `RunResult`, with `trace_dir` under the shared
+    `data_root`.
+
+    Under `FEDERATED_NODE` this waits for the unit's outcome without limit once it is admitted, so
+    a failure it raises is always one in which nothing was admitted (see `submit_and_wait`).
+
+    Placement is read from the snapshot, not from configuration: a boundary that chose its own
+    arrangement would be granting itself what the composition was or was not permitted. Execution
+    itself never consults placement — this decides only where `run_workflow` is called.
+    """
+    root = Path(snapshot_root) if snapshot_root is not None else default_snapshot_root()
+    if _placement(root.resolve()) != "FEDERATED_NODE":
+        return run_workflow(wf_fqdn=wf_fqdn, payload=payload, data_root=data_root, snapshot_root=root)
+
+    from runtime.federation.client import submit_and_wait
+
+    coordinator_url = os.environ.get("PGC_COORDINATOR_URL")
+    if not coordinator_url:
+        raise RuntimeError(
+            "the snapshot places execution on FEDERATED_NODE and PGC_COORDINATOR_URL is not set: "
+            "this node does not execute, and has nowhere to send the work."
+        )
+    booted = resident(root)  # a boundary acts on no snapshot it has not authenticated (OB-1)
+    outcome = submit_and_wait(coordinator_url.rstrip("/"), wf_fqdn=wf_fqdn, payload=payload,
+                              snapshot_id=booted.snapshot_id)
+    if outcome.get("state") != "executed":
+        raise RuntimeError(f"unit {outcome.get('unit_id')} failed on {outcome.get('worker')}: "
+                           f"{outcome.get('detail')}")
+    return RunResult(status=outcome["status"], surface=outcome.get("surface") or {},
+                     trace_id=outcome["trace_id"], trace_dir=Path(data_root) / outcome["trace_dir"])