simplicio-cli 0.18.9__tar.gz → 0.18.11__tar.gz

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-cli
-Version: 0.18.9
+Version: 0.18.11
 Summary: Deterministic task-to-code contract and verification CLI. It never executes or provisions an LLM.
 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.27,>=0.26.11
+Requires-Dist: simplicio-mapper<0.27,>=0.26.20
 Requires-Dist: simplicio-prompt>=1.14.1
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: orjson>=3.11.9
@@ -40,7 +40,7 @@ Requires-Dist: sentence-transformers>=5.6.0; extra == "ml"
 Provides-Extra: bench
 Requires-Dist: fpdf2>=2.8.7; extra == "bench"
 Provides-Extra: fast
-Requires-Dist: simplicio-fast<3,>=2.0.22; python_version >= "3.11" and extra == "fast"
+Requires-Dist: simplicio-fast<3,>=2.0.28; python_version >= "3.11" and extra == "fast"
 Provides-Extra: performance
 Requires-Dist: uvloop>=0.21.0; sys_platform != "win32" and extra == "performance"
 Provides-Extra: all
@@ -94,6 +94,10 @@ Turn a one-line task into a verified code change: mapper context, six-layer cont
 
 > **Deterministic-only boundary:** `simplicio-py` never sends prompts or completions to a local model, OpenRouter, Anthropic, OpenAI-compatible endpoint, or CLI provider. It does not load or download model weights. Provider execution has been removed; the adapter only performs local contracts, edits, tests, and evidence.
 
+> **Operational boundary:** no local or remote LLM is required. The supported mutation inputs are an explicit mechanical-edit plan, a Fast changeset, or a Runtime EffectTransaction proposal. The CLI validates, applies, tests, and records evidence.
+>
+> The provider/model benchmark and setup material later in this file is historical evidence only; those routes are no longer supported by the package.
+
 ## Project DNA
 
 simplicio-dev-cli is the focused implementation and verification operator in the Simplicio ecosystem. It receives a decided task, loads repository context, applies a bounded diff, runs tests, and emits evidence that another operator can inspect. It is not the runtime, the mapper, or the LLM itself: it is the disciplined execution layer between a plan and a trustworthy change.
@@ -192,7 +196,7 @@ flowchart LR
 
 The section below restores the project-specific README material that existed before the globalization pass. Keep this substance when refreshing the top-level narrative: add polish, do not erase operational memory.
 
-**A focused execution operator for turning decided engineering tasks into verified changes across LLM providers.**
+**A focused execution operator for turning decided engineering tasks into verified deterministic changes.**
 
 [![PyPI](https://img.shields.io/pypi/v/simplicio-cli.svg)](https://pypi.org/project/simplicio-cli/)
 [![Python](https://img.shields.io/pypi/pyversions/simplicio-cli.svg)](https://pypi.org/project/simplicio-cli/)
@@ -201,9 +205,7 @@ The section below restores the project-specific README material that existed bef
 [![simplicio-dev-cli pipeline: task to verified code change](https://raw.githubusercontent.com/wesleysimplicio/simplicio-dev-cli/main/output/imagegen/simplicio-cli-readme-hero-web.png)](output/imagegen/simplicio-cli-readme-hero.png)
 
 > *"hide the Delete button for non-admins"* → diff + test + applied + verified.
-> **Zero API key inside Claude Code** (auto-installs, uses your subscription) — or
-> bring your own key for any provider: OpenRouter, OpenAI, Anthropic, GLM,
-> DeepSeek, Ollama.
+> **No model or API key is required by the deterministic executor.** External coordinators may provide an explicit plan or changeset.
 
 ```bash
 pip install simplicio-cli
@@ -707,7 +709,7 @@ simplicio-py task "hide Delete button for non-admins" \
 - build passes"
 ```
 
-Provider-agnostic — see [Configure](#configure--any-llm-nothing-hardcoded) for the full matrix.
+Provider configuration is legacy documentation; the package no longer executes model providers.
 
 ---
 
@@ -820,7 +822,7 @@ 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
+Use an explicit mechanical-edit plan, changeset, or Runtime Effect API 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

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/README.md

@@ -34,6 +34,10 @@ Turn a one-line task into a verified code change: mapper context, six-layer cont
 
 > **Deterministic-only boundary:** `simplicio-py` never sends prompts or completions to a local model, OpenRouter, Anthropic, OpenAI-compatible endpoint, or CLI provider. It does not load or download model weights. Provider execution has been removed; the adapter only performs local contracts, edits, tests, and evidence.
 
+> **Operational boundary:** no local or remote LLM is required. The supported mutation inputs are an explicit mechanical-edit plan, a Fast changeset, or a Runtime EffectTransaction proposal. The CLI validates, applies, tests, and records evidence.
+>
+> The provider/model benchmark and setup material later in this file is historical evidence only; those routes are no longer supported by the package.
+
 ## Project DNA
 
 simplicio-dev-cli is the focused implementation and verification operator in the Simplicio ecosystem. It receives a decided task, loads repository context, applies a bounded diff, runs tests, and emits evidence that another operator can inspect. It is not the runtime, the mapper, or the LLM itself: it is the disciplined execution layer between a plan and a trustworthy change.
@@ -132,7 +136,7 @@ flowchart LR
 
 The section below restores the project-specific README material that existed before the globalization pass. Keep this substance when refreshing the top-level narrative: add polish, do not erase operational memory.
 
-**A focused execution operator for turning decided engineering tasks into verified changes across LLM providers.**
+**A focused execution operator for turning decided engineering tasks into verified deterministic changes.**
 
 [![PyPI](https://img.shields.io/pypi/v/simplicio-cli.svg)](https://pypi.org/project/simplicio-cli/)
 [![Python](https://img.shields.io/pypi/pyversions/simplicio-cli.svg)](https://pypi.org/project/simplicio-cli/)
@@ -141,9 +145,7 @@ The section below restores the project-specific README material that existed bef
 [![simplicio-dev-cli pipeline: task to verified code change](https://raw.githubusercontent.com/wesleysimplicio/simplicio-dev-cli/main/output/imagegen/simplicio-cli-readme-hero-web.png)](output/imagegen/simplicio-cli-readme-hero.png)
 
 > *"hide the Delete button for non-admins"* → diff + test + applied + verified.
-> **Zero API key inside Claude Code** (auto-installs, uses your subscription) — or
-> bring your own key for any provider: OpenRouter, OpenAI, Anthropic, GLM,
-> DeepSeek, Ollama.
+> **No model or API key is required by the deterministic executor.** External coordinators may provide an explicit plan or changeset.
 
 ```bash
 pip install simplicio-cli
@@ -647,7 +649,7 @@ simplicio-py task "hide Delete button for non-admins" \
 - build passes"
 ```
 
-Provider-agnostic — see [Configure](#configure--any-llm-nothing-hardcoded) for the full matrix.
+Provider configuration is legacy documentation; the package no longer executes model providers.
 
 ---
 
@@ -760,7 +762,7 @@ 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
+Use an explicit mechanical-edit plan, changeset, or Runtime Effect API 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

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simplicio-cli"
-version = "0.18.9"
+version = "0.18.11"
 description = "Deterministic task-to-code contract and verification CLI. It never executes or provisions an LLM."
 readme = "README.md"
 license = { text = "MIT" }
@@ -45,7 +45,7 @@ classifiers = [
 # (generated, `--check`-able) for the full graph and #99 for the audit.
 dependencies = [
   "numpy>=2.1.0",
-  "simplicio-mapper>=0.26.11,<0.27",
+  "simplicio-mapper>=0.26.20,<0.27",
   "simplicio-prompt>=1.14.1",
   "httpx>=0.28.1",
   "orjson>=3.11.9",
@@ -62,7 +62,7 @@ ml = ["sentence-transformers>=5.6.0"]
 bench = ["fpdf2>=2.8.7"]
 # Optional canonical Fast adapter. It remains outside the base install until
 # its release train is formally promoted.
-fast = ["simplicio-fast>=2.0.22,<3; python_version >= '3.11'"]
+fast = ["simplicio-fast>=2.0.28,<3; python_version >= '3.11'"]
 # Opt-in faster asyncio event loop for the structured-concurrency runtime
 # (simplicio.runtime_async, issue #212). Never required: `install_uvloop()`
 # no-ops on Windows or when this extra is absent, falling back to stdlib
@@ -269,4 +269,3 @@ module = [
   "simplicio.scratch.cli",
 ]
 ignore_errors = true
-

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/simplicio/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.18.9"
+__version__ = "0.18.10"
 
 
 def mapper_module():

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/simplicio/cli.py

@@ -344,6 +344,11 @@ def _build_parser() -> argparse.ArgumentParser:
         "--batch-path",
         help="persist the frozen multi-task batch at this path (explicitly mutating)",
     )
+    p_intake.add_argument(
+        "--print-contract-example",
+        action="store_true",
+        help="print a minimal simplicio.task-spec/v2 stdin example and exit",
+    )
     p_intake.add_argument("--json", action="store_true", help="emit stable structured JSON")
 
     p_doctor = sub.add_parser(
@@ -635,14 +640,22 @@ def _build_parser() -> argparse.ArgumentParser:
     p_runtime_capabilities.add_argument("--coordinator-kind")
     p_runtime_capabilities.add_argument("--coordinator-id")
     p_runtime_capabilities.add_argument("--json", action="store_true")
+    p_runtime_acquire = runtime_sub.add_parser(
+        "acquire-coordinator-context",
+        help="acquire or diagnose the integrated coordinator tuple without fabricating a lease",
+    )
+    p_runtime_acquire.add_argument("--root", default=".")
+    p_runtime_acquire.add_argument("--context-snapshot", help="canonical Mapper ContextSnapshot JSON path")
+    p_runtime_acquire.add_argument(
+        "--execution-context", help="Mapper execution-context/v1 provenance JSON path"
+    )
+    p_runtime_acquire.add_argument("--json", action="store_true")
 
     p_prototype = sub.add_parser(
         "prototype", help="Prototype-First plan, scaffold, validate and promotion gate"
     )
     prototype_sub = p_prototype.add_subparsers(dest="prototype_cmd", required=True)
-    p_proto_plan = prototype_sub.add_parser(
-        "plan", help="compile and freeze a prototype plan"
-    )
+    p_proto_plan = prototype_sub.add_parser("plan", help="compile and freeze a prototype plan")
     p_proto_plan.add_argument("--input", help="Loop/Mapper prototype-plan JSON")
     p_proto_plan.add_argument("--goal", default="")
     p_proto_plan.add_argument(

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/simplicio/commands/intake.py

@@ -10,14 +10,43 @@ from urllib.error import HTTPError, URLError
 from urllib.parse import urlparse
 from urllib.request import Request, urlopen
 
-from ..execution_contract import ContractCompilationError, compile_execution_contracts
+from ..execution_contract import (
+    SCHEMA as EXECUTION_CONTRACT_SCHEMA,
+)
+from ..execution_contract import (
+    ContractCompilationError,
+    ExecutionBlockedError,
+    compile_execution_contracts,
+)
 from ..orchestrator.multi_task import BatchBuildError, TaskBatch, build_batch_preview
 from ..plan_discovery import PlanDiscoveryError, build_plan_preview
-from ..task_spec import SourceRef, TaskSpecValidationError, parse_task_document
+from ..task_spec import TASK_SPEC_SCHEMA, SourceRef, TaskSpecValidationError, parse_task_document
 
 CLI_PROG = "simplicio-py"
 _URL_TIMEOUT_SECONDS = 10
 _MAX_URL_BYTES = 2 * 1024 * 1024
+CONTRACT_EXAMPLE = """System: Example
+Feature: Typed contract intake
+Tipo: Evolucao
+
+AS A operator,
+I WANT a valid simplicio.task-spec/v2 card,
+SO THAT unattended intake can compile an execution contract.
+
+## Acceptance criteria
+
+Scenario 1: typed card compiles
+  Given a TaskSpec v2 card with system, feature, type, narrative, and one AC
+  When intake runs with --contract --execution-mode --json
+  Then the result schema is simplicio.intake-result/v1
+"""
+ACCEPTED_SYNTAX = [
+    "System: / Sistema:",
+    "Feature: / Funcionalidade:",
+    "Tipo: / Task type:",
+    "AS A / I WANT / SO THAT or COMO / QUERO / PARA",
+    "Acceptance criteria section with Given/When/Then scenarios",
+]
 
 
 def _decode(raw: bytes) -> tuple[str, str]:
@@ -73,27 +102,58 @@ def _read_input(a: argparse.Namespace) -> tuple[str, SourceRef]:
     return text, SourceRef(kind="stdin", locator=a.source_url, encoding=encoding)
 
 
+def _contract_guidance() -> dict[str, object]:
+    return {
+        "required_schema": TASK_SPEC_SCHEMA,
+        "contract_schema": EXECUTION_CONTRACT_SCHEMA,
+        "accepted_syntax": list(ACCEPTED_SYNTAX),
+        "example": CONTRACT_EXAMPLE,
+        "print_contract_example": f"{CLI_PROG} intake --print-contract-example",
+    }
+
+
+def _emit_rejection(a: argparse.Namespace, schema: str, diagnostics: list[str]) -> None:
+    if a.json:
+        payload = {
+            "schema": schema,
+            "valid": False,
+            "errors": list(diagnostics),
+            **_contract_guidance(),
+        }
+        print(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+        return
+    for diagnostic in diagnostics:
+        print(f"{CLI_PROG} intake: {diagnostic}", file=sys.stderr)
+    print(
+        f"{CLI_PROG} intake: required schema is {TASK_SPEC_SCHEMA} "
+        f"(compile with {EXECUTION_CONTRACT_SCHEMA}); "
+        f"run `{CLI_PROG} intake --print-contract-example`",
+        file=sys.stderr,
+    )
+
+
 def run(a: argparse.Namespace) -> int:
-    try:
-        text, source = _read_input(a)
-        document = parse_task_document(text, source=source)
-    except (TaskSpecValidationError, ContractCompilationError) as exc:
-        diagnostics = getattr(exc, "diagnostics", None) or getattr(exc, "errors", None) or [str(exc)]
+    if getattr(a, "print_contract_example", False):
         if a.json:
             print(
                 json.dumps(
                     {
-                        "schema": "simplicio.task-spec-validation/v1",
-                        "valid": False,
-                        "errors": list(diagnostics),
+                        "schema": "simplicio.intake-contract-example/v1",
+                        **_contract_guidance(),
                     },
                     ensure_ascii=False,
                     sort_keys=True,
                 )
             )
         else:
-            for diagnostic in diagnostics:
-                print(f"{CLI_PROG} intake: {diagnostic}", file=sys.stderr)
+            print(CONTRACT_EXAMPLE, end="")
+        return 0
+    try:
+        text, source = _read_input(a)
+        document = parse_task_document(text, source=source)
+    except (TaskSpecValidationError, ContractCompilationError) as exc:
+        diagnostics = getattr(exc, "diagnostics", None) or getattr(exc, "errors", None) or [str(exc)]
+        _emit_rejection(a, "simplicio.task-spec-validation/v1", list(diagnostics))
         return 2
 
     payload = document.to_dict()
@@ -114,41 +174,18 @@ def run(a: argparse.Namespace) -> int:
                 document, execution_mode=getattr(a, "execution_mode", False)
             )
             batch_preview = build_batch_preview(document)
+        except ExecutionBlockedError as exc:
+            _emit_rejection(
+                a,
+                "simplicio.execution-contract-validation/v1",
+                list(exc.gate_ids) or [str(exc)],
+            )
+            return 2
         except ContractCompilationError as exc:
-            diagnostics = list(exc.errors)
-            if a.json:
-                print(
-                    json.dumps(
-                        {
-                            "schema": "simplicio.execution-contract-validation/v1",
-                            "valid": False,
-                            "errors": diagnostics,
-                        },
-                        ensure_ascii=False,
-                        sort_keys=True,
-                    )
-                )
-            else:
-                for diagnostic in diagnostics:
-                    print(f"{CLI_PROG} intake: {diagnostic}", file=sys.stderr)
+            _emit_rejection(a, "simplicio.execution-contract-validation/v1", list(exc.errors))
             return 2
         except BatchBuildError as exc:
-            diagnostics = list(exc.diagnostics)
-            if a.json:
-                print(
-                    json.dumps(
-                        {
-                            "schema": "simplicio.task-batch-validation/v1",
-                            "valid": False,
-                            "errors": diagnostics,
-                        },
-                        ensure_ascii=False,
-                        sort_keys=True,
-                    )
-                )
-            else:
-                for diagnostic in diagnostics:
-                    print(f"{CLI_PROG} intake: {diagnostic}", file=sys.stderr)
+            _emit_rejection(a, "simplicio.task-batch-validation/v1", list(exc.diagnostics))
             return 2
         contracts_payload = [contract.to_dict() for contract in contracts]
         if getattr(a, "batch_path", None):

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/simplicio/commands/runtime.py

@@ -58,6 +58,20 @@ def run(a: argparse.Namespace) -> int:
             json.dumps(payload, sort_keys=True) if a.json else json.dumps(payload, indent=2, sort_keys=True)
         )
         return 0
+    if a.runtime_cmd == "acquire-coordinator-context":
+        from ..execution_mode import acquire_coordinator_context
+
+        payload = acquire_coordinator_context(
+            root=getattr(a, "root", "."),
+            context_snapshot_path=getattr(a, "context_snapshot", None),
+            execution_context_path=getattr(a, "execution_context", None),
+        )
+        if a.json:
+            print(json.dumps(payload, sort_keys=True))
+        else:
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        return 0 if payload.get("status") == "ready_for_runtime_lease" else 2
+
     if a.runtime_cmd == "doctor":
         payload = doctor_contract(a.root)
         if a.json:

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/simplicio/commands/smoke.py

@@ -1,8 +1,6 @@
-"""``simplicio-py smoke`` — deterministic adapter health check.
+"""``simplicio-py smoke`` — one proof call: connect+generate.
 
-The Python adapter deliberately does not call a model or provider.  This
-command reports that policy without making a network, subprocess, or model
-load attempt.
+Extracted from `cli.py`'s `main()` body (issue #103); behavior unchanged.
 """
 
 from __future__ import annotations
@@ -12,11 +10,11 @@ import json
 
 
 def run(a: argparse.Namespace) -> int:
-    from ..providers import info
+    from ..providers import generate, info
     from ..runtime_contracts import smoke_contract
 
     provider = info()
-    out = "LLM execution disabled; deterministic-only adapter"
+    out = generate("Reply exactly: OK simplicio connected.")
     if a.json:
         print(json.dumps(smoke_contract(provider=provider, reply=out, root=a.root), sort_keys=True))
     else:

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/simplicio/commands/task.py

@@ -30,9 +30,9 @@ def _emit_blocked_diagnostics(result: dict) -> None:
 
 def _run_verification_only(a: argparse.Namespace) -> int:
     from ..pipeline_stages import _configured_test_command, _verification_timeout_seconds
-    from ..runtime_env import prepare_project_command
+    from ..runtime_env import prepare_project_command, project_subprocess_env
 
-    command, configuration_error = _configured_test_command()
+    command, configuration_error = _configured_test_command(getattr(a, "root", None))
     if configuration_error:
         payload = {
             "schema": "simplicio.dev-cli.verification-only/v1",
@@ -70,6 +70,7 @@ def _run_verification_only(a: argparse.Namespace) -> int:
             text=True,
             timeout=_verification_timeout_seconds(),
             check=False,
+            env=project_subprocess_env(a.root),
         )
         exit_code = completed.returncode
         stdout_tail = completed.stdout[-2000:]
@@ -188,6 +189,7 @@ def run(a: argparse.Namespace) -> int:
         )
         if a.json:
             print(json.dumps(result, sort_keys=True))
+            _emit_blocked_diagnostics(result)
         else:
             status = (
                 "BLOCKED" if result.get("status") == "blocked" else ("DRY-RUN" if a.dry_run_task else "DONE")

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/simplicio/execution_mode.py

@@ -22,6 +22,15 @@ from .standalone_migration import StandalonePolicy, effect_unknown_pending, stan
 ExecutionMode = Literal["auto", "integrated", "standalone"]
 RUNTIME_EFFECT_CAPABILITY = "simplicio.effect-transaction/v1"
 MAPPER_CONTEXT_SCHEMA = MAPPER_CONTEXT_SNAPSHOT_SCHEMA
+COORDINATOR_CONTEXT_SCHEMA = "simplicio.dev-cli.coordinator-context/v1"
+ACQUIRE_COORDINATOR_CONTEXT_COMMAND = "simplicio-py runtime acquire-coordinator-context --json"
+COORDINATOR_CONTEXT_FIELDS = ("attempt_id", "lease_id", "fencing_token", "context_handle")
+COORDINATOR_CONTEXT_LIFECYCLE = (
+    "acquire-coordinator-context",
+    "proposal --mode integrated",
+    "runtime effect authorize",
+    "mutate only with a Runtime lease",
+)
 
 
 @dataclass(frozen=True)
@@ -207,7 +216,8 @@ def _attempt_context(
     if not all(value and value.strip() for value in values):
         raise ExecutionInputError(
             "COORDINATOR_CONTEXT_REQUIRED",
-            "all coordinator attempt fields are required: attempt, lease, fence, and context handle",
+            "all coordinator attempt fields are required: attempt, lease, fence, and context handle; "
+            f"run `{ACQUIRE_COORDINATOR_CONTEXT_COMMAND}`",
         )
     return AttemptContext(*cast(tuple[str, str, str, str], values))
 
@@ -351,12 +361,106 @@ def require_coordinator_attempt(
     return replace(
         profile,
         effective_mode="blocked",
-        coordinator={**profile.coordinator, "attempt_ready": False},
+        coordinator={
+            **profile.coordinator,
+            "attempt_ready": False,
+            "acquisition_command": ACQUIRE_COORDINATOR_CONTEXT_COMMAND,
+            "lifecycle": list(COORDINATOR_CONTEXT_LIFECYCLE),
+        },
         default_eligible=False,
         reason_code="COORDINATOR_CONTEXT_REQUIRED",
     )
 
 
+def acquire_coordinator_context(
+    *,
+    root: str | os.PathLike[str] = ".",
+    context_snapshot: dict[str, Any] | None = None,
+    execution_context: dict[str, Any] | None = None,
+    context_snapshot_path: str | os.PathLike[str] | None = None,
+    execution_context_path: str | os.PathLike[str] | None = None,
+    runtime_handshake: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Documented local path to acquire the integrated coordinator tuple.
+
+    Mapper artifacts may yield a canonical ``context_handle``. Attempt, lease,
+    and fencing token remain Runtime-issued; this command never fabricates
+    those protected fields.
+    """
+    snapshot = (
+        context_snapshot
+        if context_snapshot is not None
+        else _load_context_snapshot(root, context_snapshot_path)
+    )
+    exec_ctx = (
+        execution_context
+        if execution_context is not None
+        else _load_execution_context(root, execution_context_path)
+    )
+    handle = _derived_context_handle(snapshot, exec_ctx)
+    from .runtime_contracts import runtime_verify_contract
+
+    handshake = runtime_handshake if runtime_handshake is not None else runtime_verify_contract()
+    runtime_ready = bool(isinstance(handshake, dict) and handshake.get("verified"))
+    payload: dict[str, Any] = {
+        "schema": COORDINATOR_CONTEXT_SCHEMA,
+        "status": "blocked",
+        "reason_code": "COORDINATOR_CONTEXT_REQUIRED",
+        "required_fields": list(COORDINATOR_CONTEXT_FIELDS),
+        "lifecycle": list(COORDINATOR_CONTEXT_LIFECYCLE),
+        "acquisition_command": ACQUIRE_COORDINATOR_CONTEXT_COMMAND,
+        "next_command": (
+            "simplicio-py proposal --mode integrated "
+            "--attempt-id <attempt_id> --lease-id <lease_id> "
+            "--fencing-token <fencing_token> --context-handle <context_handle>"
+        ),
+        "context_handle": handle,
+        "attempt_id": None,
+        "lease_id": None,
+        "fencing_token": None,
+        "mutation_authorized": False,
+        "runtime": {
+            "verified": runtime_ready,
+            "reason": handshake.get("reason") if isinstance(handshake, dict) else "RUNTIME_HANDSHAKE_INVALID",
+        },
+        "mapper": {
+            "snapshot_present": snapshot is not None,
+            "execution_context_present": exec_ctx is not None,
+        },
+    }
+    if handle and runtime_ready:
+        payload["status"] = "ready_for_runtime_lease"
+        payload["reason_code"] = "RUNTIME_LEASE_REQUIRED"
+        payload["next_command"] = (
+            f"simplicio effect authorize --json --context-handle {handle} && "
+            f"{ACQUIRE_COORDINATOR_CONTEXT_COMMAND} --context-snapshot "
+            "<snapshot> --execution-context <execution-context>"
+        )
+    elif handle:
+        payload["reason_code"] = "RUNTIME_LEASE_UNAVAILABLE"
+        payload["next_command"] = (
+            f"{ACQUIRE_COORDINATOR_CONTEXT_COMMAND} --context-snapshot <snapshot> "
+            "--execution-context <execution-context>"
+        )
+    return payload
+
+
+def _derived_context_handle(
+    snapshot: dict[str, Any] | None, execution_context: dict[str, Any] | None
+) -> str | None:
+    for payload in (execution_context, snapshot):
+        if not isinstance(payload, dict):
+            continue
+        for key in ("context_handle", "snapshot_id", "id"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    if isinstance(snapshot, dict):
+        canonical = json.dumps(snapshot, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        return "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    return None
+
+
 def negotiate_execution_mode(
     mode: str | None = None,
     *,

{simplicio_cli-0.18.9 → simplicio_cli-0.18.11}/simplicio/execution_receipts.py

@@ -36,6 +36,17 @@ def execution_mode_blocker(profile: Any) -> dict[str, Any]:
                 "next_action": "provide --context-snapshot and retry",
             }
         )
+    elif code == "COORDINATOR_CONTEXT_REQUIRED":
+        from .execution_mode import ACQUIRE_COORDINATOR_CONTEXT_COMMAND, COORDINATOR_CONTEXT_LIFECYCLE
+
+        blocker.update(
+            {
+                "message": "coordinator attempt, lease, fence, and context handle are required",
+                "retryable": True,
+                "next_action": f"run `{ACQUIRE_COORDINATOR_CONTEXT_COMMAND}`",
+                "lifecycle": list(COORDINATOR_CONTEXT_LIFECYCLE),
+            }
+        )
     elif code == "RUNTIME_SINK_REQUIRED":
         blocker.update(
             {