simplicio-cli 0.16.2__tar.gz → 0.16.3__tar.gz

{simplicio_cli-0.16.2 → simplicio_cli-0.16.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-cli
-Version: 0.16.2
+Version: 0.16.3
 Summary: Portable task-to-code pipeline that works with any LLM. Turn a one-line task into a verified code change — diff + test + verify loop. +55 pts on a 156-check benchmark, 21% faster, ~same tokens.
 Author-email: Wesley Simplicio <wesleybob4@gmail.com>
 License: MIT
@@ -28,7 +28,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=2.1.0
-Requires-Dist: simplicio-mapper>=0.24.1
+Requires-Dist: simplicio-mapper>=0.24.2
 Requires-Dist: simplicio-prompt>=1.14.1
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: orjson>=3.11.9
@@ -538,10 +538,10 @@ Missing an extra never crashes with a raw traceback — every optional import
 is guarded and raises an actionable error naming the exact extra to install
 (e.g. `pip install 'simplicio-cli[providers]'`).
 
-#### Local quality gate
+#### CI and local quality gate
 
-GitHub Actions is disabled for this repository and `.github/workflows/` is
-intentionally absent. The reproducible merge gate runs locally; attach its
+The blocking `.github/workflows/ci.yml` coverage job runs on pull requests
+and pushes to `main`. The same gate is reproducible locally; attach its
 command output to the pull request:
 
 ```bash
@@ -780,7 +780,7 @@ user prompt. UserPromptSubmit is the right pre-hook for routing decisions.
 | GLM (z.ai) | `glm-4.6` | `https://api.z.ai/api/paas/v4` |
 | DeepSeek | `deepseek-chat` | `https://api.deepseek.com` |
 | OpenAI | `gpt-4.1` | `https://api.openai.com/v1` |
-| Local (llama.cpp) | `openbmb/minicpm5:latest` | *(leave unset)* |
+| Local (llama.cpp, paused by default) | `openbmb/minicpm5:latest` + `SIMPLICIO_LOCAL_INFERENCE=enabled` | *(leave unset)* |
 | Anthropic native | `claude-opus-4-7` | *(leave unset)* |
 
 If `SIMPLICIO_BASE_URL` is unset and the key is `ANTHROPIC_API_KEY`, it uses the
@@ -791,19 +791,25 @@ your `base_url` — so **any** OpenAI-like provider works without code changes.
 simplicio-py smoke      # prints provider config + one test call
 ```
 
-#### Path 4 — local llama.cpp GGUF default
+#### Path 4 — local llama.cpp GGUF (explicitly re-enabled only)
 
-When **no provider is configured** (`SIMPLICIO_MODEL` and
-`SIMPLICIO_BASE_URL` both unset), simplicio runs the in-process
-[`llama-cpp-python`](https://github.com/abetlen/llama-cpp-python) backend with
-`openbmb/minicpm5:latest`, backed by
+Local inference is **paused by default**.  With no provider configured, or
+when a loopback endpoint such as Ollama is selected, the CLI fails closed with
+the machine-readable reason `LOCAL_INFERENCE_PAUSED`; it does not read a
+cached completion, load a model, download weights, start a process, or open a
+socket. Existing GGUF artifacts are preserved.
+
+Use an explicit remote provider for normal operation. To intentionally enable
+the local route for a process, set `SIMPLICIO_LOCAL_INFERENCE=enabled` first.
+The in-process [`llama-cpp-python`](https://github.com/abetlen/llama-cpp-python)
+backend then uses `openbmb/minicpm5:latest`, backed by
 `openbmb/MiniCPM5-1B-GGUF::MiniCPM5-1B-Q4_K_M.gguf`.
 
 ```bash
 pip install 'simplicio-cli[local]'          # pulls llama-cpp-python + huggingface-hub
-simplicio-py doctor --install                  # downloads/validates the default GGUF
+SIMPLICIO_LOCAL_INFERENCE=enabled simplicio-py doctor --install
 
-simplicio-py task "add input validation to createUser" \
+SIMPLICIO_LOCAL_INFERENCE=enabled simplicio-py task "add input validation to createUser" \
   --target src/users.ts --local              # forces local llama.cpp
 
 # the GGUF is fetched once from the Hugging Face Hub, then reused

{simplicio_cli-0.16.2 → simplicio_cli-0.16.3}/README.md

@@ -472,10 +472,10 @@ Missing an extra never crashes with a raw traceback — every optional import
 is guarded and raises an actionable error naming the exact extra to install
 (e.g. `pip install 'simplicio-cli[providers]'`).
 
-#### Local quality gate
+#### CI and local quality gate
 
-GitHub Actions is disabled for this repository and `.github/workflows/` is
-intentionally absent. The reproducible merge gate runs locally; attach its
+The blocking `.github/workflows/ci.yml` coverage job runs on pull requests
+and pushes to `main`. The same gate is reproducible locally; attach its
 command output to the pull request:
 
 ```bash
@@ -714,7 +714,7 @@ user prompt. UserPromptSubmit is the right pre-hook for routing decisions.
 | GLM (z.ai) | `glm-4.6` | `https://api.z.ai/api/paas/v4` |
 | DeepSeek | `deepseek-chat` | `https://api.deepseek.com` |
 | OpenAI | `gpt-4.1` | `https://api.openai.com/v1` |
-| Local (llama.cpp) | `openbmb/minicpm5:latest` | *(leave unset)* |
+| Local (llama.cpp, paused by default) | `openbmb/minicpm5:latest` + `SIMPLICIO_LOCAL_INFERENCE=enabled` | *(leave unset)* |
 | Anthropic native | `claude-opus-4-7` | *(leave unset)* |
 
 If `SIMPLICIO_BASE_URL` is unset and the key is `ANTHROPIC_API_KEY`, it uses the
@@ -725,19 +725,25 @@ your `base_url` — so **any** OpenAI-like provider works without code changes.
 simplicio-py smoke      # prints provider config + one test call
 ```
 
-#### Path 4 — local llama.cpp GGUF default
+#### Path 4 — local llama.cpp GGUF (explicitly re-enabled only)
 
-When **no provider is configured** (`SIMPLICIO_MODEL` and
-`SIMPLICIO_BASE_URL` both unset), simplicio runs the in-process
-[`llama-cpp-python`](https://github.com/abetlen/llama-cpp-python) backend with
-`openbmb/minicpm5:latest`, backed by
+Local inference is **paused by default**.  With no provider configured, or
+when a loopback endpoint such as Ollama is selected, the CLI fails closed with
+the machine-readable reason `LOCAL_INFERENCE_PAUSED`; it does not read a
+cached completion, load a model, download weights, start a process, or open a
+socket. Existing GGUF artifacts are preserved.
+
+Use an explicit remote provider for normal operation. To intentionally enable
+the local route for a process, set `SIMPLICIO_LOCAL_INFERENCE=enabled` first.
+The in-process [`llama-cpp-python`](https://github.com/abetlen/llama-cpp-python)
+backend then uses `openbmb/minicpm5:latest`, backed by
 `openbmb/MiniCPM5-1B-GGUF::MiniCPM5-1B-Q4_K_M.gguf`.
 
 ```bash
 pip install 'simplicio-cli[local]'          # pulls llama-cpp-python + huggingface-hub
-simplicio-py doctor --install                  # downloads/validates the default GGUF
+SIMPLICIO_LOCAL_INFERENCE=enabled simplicio-py doctor --install
 
-simplicio-py task "add input validation to createUser" \
+SIMPLICIO_LOCAL_INFERENCE=enabled simplicio-py task "add input validation to createUser" \
   --target src/users.ts --local              # forces local llama.cpp
 
 # the GGUF is fetched once from the Hugging Face Hub, then reused

{simplicio_cli-0.16.2 → simplicio_cli-0.16.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simplicio-cli"
-version = "0.16.2"
+version = "0.16.3"
 description = "Portable task-to-code pipeline that works with any LLM. Turn a one-line task into a verified code change — diff + test + verify loop. +55 pts on a 156-check benchmark, 21% faster, ~same tokens."
 readme = "README.md"
 license = { text = "MIT" }
@@ -53,7 +53,7 @@ classifiers = [
 # (generated, `--check`-able) for the full graph and #99 for the audit.
 dependencies = [
   "numpy>=2.1.0",
-  "simplicio-mapper>=0.24.1",
+  "simplicio-mapper>=0.24.2",
   "simplicio-prompt>=1.14.1",
   "httpx>=0.28.1",
   "orjson>=3.11.9",
@@ -72,8 +72,8 @@ providers = ["anthropic>=0.112.0", "openai>=2.44.0"]
 # vectors yet); the numpy-only cosine-similarity math stays in base.
 ml = ["sentence-transformers>=5.6.0"]
 bench = ["fpdf2>=2.8.7"]
-# Offline fallback in-process inference. Pulls the llama.cpp Python bindings
-# plus huggingface-hub to fetch MiniCPM5-1B-Q4_K_M.gguf.
+# Explicit opt-in local inference. Pulls llama.cpp Python bindings and
+# huggingface-hub; the backend stays paused until SIMPLICIO_LOCAL_INFERENCE=enabled.
 local = ["llama-cpp-python>=0.3.32", "huggingface-hub>=1.21.0"]
 # Opt-in faster asyncio event loop for the structured-concurrency runtime
 # (simplicio.runtime_async, issue #212). Never required: `install_uvloop()`

{simplicio_cli-0.16.2 → simplicio_cli-0.16.3}/simplicio/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.16.2"
+__version__ = "0.16.3"
 
 from .mapper_api import mapper_module, mapper_version
 

{simplicio_cli-0.16.2 → simplicio_cli-0.16.3}/simplicio/_cache.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import ast
 import hashlib
 import json
 import os
@@ -12,6 +13,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from .hbp import HbpError, HbpEvidenceLedger
+
 
 def _env_flag(name: str, default: bool) -> bool:
     raw = os.environ.get(name)
@@ -111,8 +114,90 @@ class CompletionCache:
         return _env_flag("SIMPLICIO_BUST_CACHE", False)
 
     def path_for(self, key: str) -> Path:
+        return self.root / key[:2] / f"{key}.hbp"
+
+    def _legacy_path_for(self, key: str) -> Path:
         return self.root / key[:2] / f"{key}.json"
 
+    @staticmethod
+    def _fields(entry: CacheEntry) -> dict[str, str]:
+        # repr/literal_eval is used only for the bounded metadata scalar. It
+        # is never executed and keeps the internal cache free of JSON.
+        return {
+            "completion": entry.completion,
+            "created_at": repr(entry.created_at),
+            "metadata": repr(entry.metadata),
+            "model": entry.model,
+            "provider_id": entry.provider_id,
+        }
+
+    @staticmethod
+    def _entry_from_fields(fields: dict[str, str]) -> CacheEntry:
+        try:
+            metadata = ast.literal_eval(fields.get("metadata", "{}"))
+            created_at = float(fields.get("created_at", "0"))
+        except (ValueError, SyntaxError, TypeError) as exc:
+            raise HbpError("invalid completion cache fields") from exc
+        if not isinstance(metadata, dict):
+            raise HbpError("completion cache metadata must be a mapping")
+        return CacheEntry(
+            completion=fields.get("completion", ""),
+            provider_id=fields.get("provider_id", ""),
+            model=fields.get("model", ""),
+            created_at=created_at or time.time(),
+            metadata=metadata,
+        )
+
+    def _read_hbp(self, path: Path) -> CacheEntry:
+        rows = HbpEvidenceLedger(path.parent, file_name=path.name).verify()
+        if len(rows) != 1 or rows[0].topic != "completion-cache":
+            raise HbpError("completion cache must contain exactly one record")
+        payload = rows[0].payload
+        payload_bytes = payload.encode("utf-8")
+        prefix = b"hbp-fields/v1"
+        if not payload_bytes.startswith(prefix):
+            raise HbpError("completion cache has an unsupported payload")
+        fields: dict[str, str] = {}
+        cursor = len(prefix)
+        while cursor < len(payload_bytes):
+            if payload_bytes[cursor : cursor + 1] != b":":
+                raise HbpError("invalid completion cache field framing")
+            colon = payload_bytes.find(b":", cursor + 1)
+            if colon < 0:
+                raise HbpError("truncated completion cache field length")
+            try:
+                size = int(payload_bytes[cursor + 1 : colon])
+            except ValueError as exc:
+                raise HbpError("invalid completion cache field length") from exc
+            start = colon + 1
+            end = start + size
+            raw_field, cursor = payload_bytes[start:end], end
+            if len(raw_field) != size:
+                raise HbpError("truncated completion cache field")
+            try:
+                field = raw_field.decode("utf-8")
+            except UnicodeDecodeError as exc:
+                raise HbpError("completion cache field is not UTF-8") from exc
+            separator = field.find("=")
+            if separator < 1:
+                raise HbpError("completion cache field is missing a key")
+            key, value = field[:separator], field[separator + 1 :]
+            fields[key] = value
+        return self._entry_from_fields(fields)
+
+    def _write_hbp(self, path: Path, entry: CacheEntry) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temp_dir = Path(tempfile.mkdtemp(prefix=f".{path.stem}.", dir=str(path.parent)))
+        try:
+            temp_path = temp_dir / path.name
+            HbpEvidenceLedger(temp_dir, file_name=path.name).record_fields(
+                "completion-cache", self._fields(entry), "simplicio-dev-cli/cache"
+            )
+            HbpEvidenceLedger(temp_dir, file_name=path.name).verify()
+            os.replace(temp_path, path)
+        finally:
+            shutil.rmtree(temp_dir, ignore_errors=True)
+
     def get(self, key: str) -> CacheEntry | None:
         if not self.enabled or self.bust:
             self.misses += 1
@@ -120,8 +205,19 @@ class CompletionCache:
         path = self.path_for(key)
         try:
             if not path.exists():
-                self.misses += 1
-                return None
+                legacy = self._legacy_path_for(key)
+                if legacy.exists():
+                    try:
+                        with legacy.open("r", encoding="utf-8") as handle:
+                            self._write_hbp(path, CacheEntry.from_dict(json.load(handle)))
+                        legacy.unlink()
+                    except (OSError, ValueError, TypeError, json.JSONDecodeError, HbpError):
+                        self._safe_unlink(legacy)
+                        self.misses += 1
+                        return None
+                else:
+                    self.misses += 1
+                    return None
             if self._is_expired(path):
                 self._safe_unlink(path)
                 self.misses += 1
@@ -130,11 +226,10 @@ class CompletionCache:
             self.misses += 1
             return None
         try:
-            with path.open("r", encoding="utf-8") as handle:
-                entry = CacheEntry.from_dict(json.load(handle))
-                self.hits += 1
-                return entry
-        except (OSError, ValueError, TypeError):
+            entry = self._read_hbp(path)
+            self.hits += 1
+            return entry
+        except (OSError, ValueError, TypeError, HbpError):
             self._safe_unlink(path)
             self.misses += 1
             return None
@@ -144,24 +239,9 @@ class CompletionCache:
             return
         path = self.path_for(key)
         try:
-            path.parent.mkdir(parents=True, exist_ok=True)
-            fd, tmp_name = tempfile.mkstemp(
-                prefix=f".{path.stem}.",
-                suffix=".tmp",
-                dir=str(path.parent),
-            )
+            self._write_hbp(path, entry)
         except OSError:
             return
-        try:
-            with os.fdopen(fd, "w", encoding="utf-8") as handle:
-                json.dump(entry.to_dict(), handle, sort_keys=True)
-            try:
-                os.replace(tmp_name, path)
-            except OSError:
-                return
-        finally:
-            if os.path.exists(tmp_name):
-                self._safe_unlink(Path(tmp_name))
         self.puts += 1
         evict_every = max(1, _env_int("SIMPLICIO_CACHE_EVICT_EVERY", 16))
         if self.puts == 1 or self.puts % evict_every == 0:
@@ -202,7 +282,7 @@ class CompletionCache:
                 return []
             return [
                 path
-                for path in self.root.rglob("*.json")
+                for path in self.root.rglob("*.hbp")
                 if path.is_file() and _is_completion_cache_file(self.root, path)
             ]
         except OSError:

simplicio_cli-0.16.3/simplicio/atomic_execution.py

@@ -0,0 +1,306 @@
+"""One-dispatch/one-attempt execution boundary for integrated coordinators.
+
+This module deliberately has no scheduler, retry loop, provider selection,
+worktree creation, queue, or terminal-state writer.  The coordinator supplies
+one already-selected PlanNode and its causal attempt/lease context; Dev CLI
+may submit at most the single effect belonging to that node and returns an
+observation.  What happens next is exclusively a coordinator decision.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import hashlib
+import time
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from simplicio.plan_compiler.effect_sink import EffectDispatchContext, EffectOutcome, EffectSink
+from simplicio.plan_compiler.models import EffectPlan, PlanNode, VerificationPlan
+
+ATOMIC_OBSERVATION_SCHEMA = "simplicio.dev-cli.atomic-observation/v1"
+Outcome = Literal[
+    "completed",
+    "effect_submitted",
+    "failed",
+    "cancelled",
+    "lease_lost",
+    "stale_fence",
+    "effect_unknown",
+]
+Retryability = Literal["retryable", "non_retryable", "unknown"]
+CancellationCheck = Callable[[], bool]
+LeaseCheck = Callable[[str, str], bool]
+FenceCheck = Callable[[str], bool]
+
+
+class IntegratedOwnershipError(RuntimeError):
+    """An integrated caller attempted to reintroduce local lifecycle ownership."""
+
+
+@dataclass(frozen=True)
+class AttemptContext:
+    """Coordinator-owned identity and guards for exactly one dispatch."""
+
+    attempt_id: str
+    lease_id: str
+    fencing_token: str
+    context_handle: str
+    deadline_monotonic: float | None = None
+    cancellation_requested: CancellationCheck = field(default=lambda: False, repr=False, compare=False)
+    lease_valid: LeaseCheck = field(default=lambda _lease, _fence: True, repr=False, compare=False)
+    fence_current: FenceCheck = field(default=lambda _fence: True, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        for name in ("attempt_id", "lease_id", "fencing_token", "context_handle"):
+            if not getattr(self, name).strip():
+                raise ValueError(f"{name} is required for integrated execution")
+
+
+@dataclass(frozen=True)
+class AtomicObservation:
+    """Executor facts sufficient for an external coordinator's next decision."""
+
+    outcome: Outcome
+    reason: str
+    failure_fingerprint: str | None
+    retryability: Retryability
+    attempt_id: str
+    lease_id: str
+    fencing_token: str
+    context_handle: str
+    plan_node_id: str
+    effect_ids: tuple[str, ...]
+    evidence_handles: tuple[str, ...]
+    receipt_handles: tuple[str, ...]
+    validation: tuple[Mapping[str, Any], ...]
+    resources: Mapping[str, int | float | None]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema": ATOMIC_OBSERVATION_SCHEMA,
+            "outcome": self.outcome,
+            "reason": self.reason,
+            "failure_fingerprint": self.failure_fingerprint,
+            "retryability": self.retryability,
+            "attempt_id": self.attempt_id,
+            "lease_id": self.lease_id,
+            "fencing_token": self.fencing_token,
+            "context_handle": self.context_handle,
+            "plan_node_id": self.plan_node_id,
+            "effect_ids": list(self.effect_ids),
+            "evidence_handles": list(self.evidence_handles),
+            "receipt_handles": list(self.receipt_handles),
+            "validation": [dict(item) for item in self.validation],
+            "resources": dict(self.resources),
+        }
+
+
+_ACTIVE_ATTEMPT: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "simplicio_integrated_attempt", default=None
+)
+
+
+def _fingerprint(reason: str) -> str:
+    return hashlib.sha256(reason.encode("utf-8", errors="replace")).hexdigest()[:16]
+
+
+def _guard_reason(attempt: AttemptContext) -> tuple[Outcome, str] | None:
+    if attempt.cancellation_requested():
+        return "cancelled", "coordinator cancellation requested"
+    if attempt.deadline_monotonic is not None and time.monotonic() >= attempt.deadline_monotonic:
+        return "cancelled", "coordinator deadline elapsed"
+    if not attempt.fence_current(attempt.fencing_token):
+        return "stale_fence", "coordinator fencing token is stale"
+    if not attempt.lease_valid(attempt.lease_id, attempt.fencing_token):
+        return "lease_lost", "coordinator lease is no longer valid"
+    return None
+
+
+def _observation(
+    outcome: Outcome,
+    reason: str,
+    retryability: Retryability,
+    *,
+    node: PlanNode,
+    attempt: AttemptContext,
+    started: float,
+    effect_ids: tuple[str, ...] = (),
+    evidence_handles: tuple[str, ...] = (),
+    receipt_handles: tuple[str, ...] = (),
+    validation: tuple[Mapping[str, Any], ...] = (),
+) -> AtomicObservation:
+    return AtomicObservation(
+        outcome=outcome,
+        reason=reason,
+        failure_fingerprint=None if outcome in {"completed", "effect_submitted"} else _fingerprint(reason),
+        retryability=retryability,
+        attempt_id=attempt.attempt_id,
+        lease_id=attempt.lease_id,
+        fencing_token=attempt.fencing_token,
+        context_handle=attempt.context_handle,
+        plan_node_id=node.node_id,
+        effect_ids=effect_ids,
+        evidence_handles=evidence_handles,
+        receipt_handles=receipt_handles,
+        validation=validation,
+        resources={
+            "atomic_attempts": 1,
+            "effect_calls": len(effect_ids),
+            "model_calls": 0,
+            "subprocesses": 0,
+            "threads_created": 0,
+            "worktrees_created": 0,
+            "tokens": 0,
+            "latency_ms": round((time.monotonic() - started) * 1000, 3),
+        },
+    )
+
+
+def execute_work_item_once(
+    plan_node: PlanNode,
+    attempt: AttemptContext,
+    *,
+    effects: Sequence[EffectPlan],
+    verifications: Sequence[VerificationPlan],
+    effect_sink: EffectSink,
+    dispatch_context: EffectDispatchContext | None = None,
+) -> AtomicObservation:
+    """Execute one selected node once, without making lifecycle decisions.
+
+    An effectful node must have exactly one matching effect.  This structural
+    restriction makes a single dispatch incapable of hiding a retry/batch.
+    Guard checks run immediately before the only mutating boundary.  Sink
+    exceptions become ``effect_unknown`` and are never retried here.
+    """
+    active = _ACTIVE_ATTEMPT.get()
+    if active is not None:
+        raise IntegratedOwnershipError(
+            f"nested integrated attempt is forbidden: active={active}, requested={attempt.attempt_id}"
+        )
+    matching_effects = tuple(effect for effect in effects if effect.plan_node_id == plan_node.node_id)
+    unrelated = [effect.effect_id for effect in effects if effect.plan_node_id != plan_node.node_id]
+    if unrelated:
+        raise IntegratedOwnershipError("one dispatch may contain effects only for its selected PlanNode")
+    if len(matching_effects) > 1:
+        raise IntegratedOwnershipError("one integrated PlanNode may submit at most one effect per dispatch")
+    if dispatch_context is not None:
+        if dispatch_context.plan_node.node_id != plan_node.node_id:
+            raise IntegratedOwnershipError(
+                "dispatch context PlanNode must match the selected integrated PlanNode"
+            )
+        if dispatch_context.coordinator_id != attempt.attempt_id:
+            raise IntegratedOwnershipError(
+                "dispatch context coordinator_id must preserve the coordinator attempt_id"
+            )
+
+    started = time.monotonic()
+    token = _ACTIVE_ATTEMPT.set(attempt.attempt_id)
+    try:
+        guard = _guard_reason(attempt)
+        if guard is not None:
+            outcome, reason = guard
+            return _observation(
+                outcome, reason, "retryable", node=plan_node, attempt=attempt, started=started
+            )
+
+        matching_validations = tuple(
+            {
+                "verification_id": item.verification_id,
+                "verifier": item.verifier,
+                "acceptance_criteria_refs": list(item.acceptance_criteria_refs),
+            }
+            for item in verifications
+            if item.plan_node_id == plan_node.node_id
+        )
+        if not matching_effects:
+            return _observation(
+                "completed",
+                "effect-free node observed; coordinator retains verification scheduling",
+                "non_retryable",
+                node=plan_node,
+                attempt=attempt,
+                started=started,
+                validation=matching_validations,
+            )
+
+        # Re-check at the last possible instant before the only effect boundary.
+        guard = _guard_reason(attempt)
+        if guard is not None:
+            outcome, reason = guard
+            return _observation(
+                outcome, reason, "retryable", node=plan_node, attempt=attempt, started=started
+            )
+        effect = matching_effects[0]
+        try:
+            context = dispatch_context or EffectDispatchContext(
+                plan_id="",
+                goal_id="",
+                plan_node=plan_node,
+                verifications=list(verifications),
+                coordinator_id=attempt.attempt_id,
+            )
+            result: EffectOutcome = effect_sink.submit(effect, context)
+        except IntegratedOwnershipError:
+            raise
+        except Exception as exc:
+            reason = f"effect outcome unknown after sink failure: {type(exc).__name__}"
+            return _observation(
+                "effect_unknown",
+                reason,
+                "unknown",
+                node=plan_node,
+                attempt=attempt,
+                started=started,
+                effect_ids=(effect.effect_id,),
+            )
+
+        receipt_payload = result.receipt or {}
+        receipt = str(receipt_payload.get("receipt_handle", result.idempotency_key)).strip()
+        evidence = tuple(
+            str(item) for item in receipt_payload.get("evidence_handles", ()) if str(item).strip()
+        )
+        accepted_states = {"running", "completed"}
+        if result.state not in accepted_states:
+            reason = ", ".join(result.reason_codes) or f"runtime effect state: {result.state}"
+            retryability: Retryability = (
+                "unknown"
+                if result.state == "effect_unknown"
+                else "retryable"
+                if result.state in {"not_started", "blocked_conflict"}
+                else "non_retryable"
+            )
+            return _observation(
+                "effect_unknown" if result.state == "effect_unknown" else "failed",
+                reason,
+                retryability,
+                node=plan_node,
+                attempt=attempt,
+                started=started,
+                effect_ids=(effect.effect_id,),
+                receipt_handles=(receipt,) if receipt else (),
+            )
+        return _observation(
+            "effect_submitted",
+            f"runtime accepted atomic submission with state {result.state}",
+            "non_retryable",
+            node=plan_node,
+            attempt=attempt,
+            started=started,
+            effect_ids=(effect.effect_id,),
+            evidence_handles=evidence,
+            receipt_handles=(receipt,) if receipt else (),
+            validation=matching_validations,
+        )
+    finally:
+        _ACTIVE_ATTEMPT.reset(token)
+
+
+__all__ = [
+    "ATOMIC_OBSERVATION_SCHEMA",
+    "AtomicObservation",
+    "AttemptContext",
+    "IntegratedOwnershipError",
+    "execute_work_item_once",
+]