accountable-surface 0.3.1__py3-none-any.whl

accountable_surface/__init__.py

@@ -0,0 +1,105 @@
+"""The Accountable Surface -- a live seam where a model perceives and acts only
+through accountability: witnessed perception, a pre-execution gate, and a
+tamper-evident, durable memory, under human stewardship.
+
+Mission: "Senses and sensibility are what lead to the new frontier. Machines
+learning to hold themselves accountable."
+
+The core (`surface`) is stdlib + coherence-membrane + proof-surface. The live
+MCP server (`server`) additionally needs `mcp` (the `[server]` extra).
+"""
+
+from __future__ import annotations
+
+from .api_effector import (
+    GITHUB_ISSUE_COMMENTS,
+    ApiCall,
+    ApiEffector,
+    ApiOperation,
+    ApiService,
+    FakeApiDriver,
+)
+from .action_receipt import (
+    ActionReceiptReceptor,
+    receipt_from_outcome,
+    verify_receipts,
+)
+from .credentials import MissingCredential, has_secret, require_secret
+from .effector import FilesystemEffector, Plan, RefusedActuation, Verdict
+from .native_control_effector import (
+    SAFE_READ_VERBS,
+    FakeNativeControlRunner,
+    NativeControlListEffector,
+    NativeControlRunner,
+    NativeControlWriteEffector,
+)
+from .http_driver import HttpDriver, parse_html
+from .os_effector import CommandEffector, SubprocessRunner
+from .registry import EffectorRegistry, Exposed, load_effectors
+from .reference import ArxivSource, FakeSource, Grounding, Reference, ReferenceCortex, parse_arxiv_atom
+from .surface import (
+    AccountableSurface,
+    ActionOutcome,
+    ActuationOutcome,
+    GoalOutcome,
+    JournalEntry,
+    Step,
+)
+from .browser_effector import (
+    BrowserAction,
+    BrowserDriver,
+    BrowserEffector,
+    FakeBrowserDriver,
+)
+from .web_effector import FakePageDriver, WebAction, WebEffector
+
+__all__ = [
+    "AccountableSurface",
+    "ActionOutcome",
+    "ActuationOutcome",
+    "GoalOutcome",
+    "Step",
+    "JournalEntry",
+    "FilesystemEffector",
+    "Plan",
+    "RefusedActuation",
+    "Verdict",
+    "WebEffector",
+    "WebAction",
+    "FakePageDriver",
+    "BrowserEffector",
+    "BrowserAction",
+    "BrowserDriver",
+    "FakeBrowserDriver",
+    "HttpDriver",
+    "parse_html",
+    "CommandEffector",
+    "SubprocessRunner",
+    "ApiEffector",
+    "ApiCall",
+    "ApiOperation",
+    "ApiService",
+    "FakeApiDriver",
+    "GITHUB_ISSUE_COMMENTS",
+    "MissingCredential",
+    "require_secret",
+    "has_secret",
+    "EffectorRegistry",
+    "Exposed",
+    "load_effectors",
+    "ReferenceCortex",
+    "Reference",
+    "Grounding",
+    "FakeSource",
+    "ArxivSource",
+    "parse_arxiv_atom",
+    "NativeControlListEffector",
+    "NativeControlWriteEffector",
+    "NativeControlRunner",
+    "FakeNativeControlRunner",
+    "SAFE_READ_VERBS",
+    "ActionReceiptReceptor",
+    "receipt_from_outcome",
+    "verify_receipts",
+]
+__version__ = "0.3.1"

accountable_surface/action_receipt.py

@@ -0,0 +1,226 @@
+"""The action-receipt receptor -- the missing writer for `project-telos.action-receipt/v1`.
+
+The action-receipt contract (telos/demo/integrations/action-receipt-conventions.json)
+defines a durable, independently auditable event for agent work: proposed, admitted,
+executed, failed, and compensated actions, each carrying a verification verdict
+(MATCH / DRIFT / UNVERIFIABLE) and an append-only persistence rule. Until now nothing
+on the runtime path emitted one. This module is that receptor: it turns an
+`AccountableSurface.actuate` outcome into a conformant event and appends it to a
+hash-chained, append-only store, so a stranger holding only the file can re-derive
+the seal offline (`verify_receipts`).
+
+Two independent seals, both re-derivable with stdlib only:
+  * per-event content hash -- `receipts[].hash` over the event's semantic fields, so
+    editing any field (target, verdict, decision, ...) breaks it.
+  * chain hash -- `_hash = sha256(_prev | canonical(event))`, so deleting or reordering
+    an event breaks the linkage. This is the same construction as the surface journal
+    and `verify_journal.py`, applied to the exportable action-receipt stream.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from coherence_membrane.observation import sha256_hex
+
+SCHEMA = "project-telos.action-receipt/v1"
+RECEPTOR = {"name": "accountable-surface.native-control-receptor", "version": "0.1"}
+GENESIS = ""
+
+
+def canonical(value: Any) -> str:
+    """Deterministic JSON: sorted keys, tight separators. The re-derivable form."""
+    return json.dumps(value, sort_keys=True, separators=(",", ":"))
+
+
+def _digest(value: Any) -> str:
+    return "sha256:" + sha256_hex(canonical(value).encode("utf-8"))
+
+
+def _config_hash() -> str:
+    return _digest({"schema": SCHEMA, "receptor": RECEPTOR})
+
+
+def _outcome_terms(outcome: Any) -> tuple[str, str, str, str]:
+    """Map an ActuationOutcome onto (event_type, result_state, stop_reason, verdict),
+    using only the contract's typed vocabularies. Documented in docs/native-control-bridge.md."""
+    acted = bool(getattr(outcome, "acted", False))
+    verified = bool(getattr(outcome, "verified", False))
+    decision = str(getattr(outcome, "decision", "deny"))
+    verdict_status = str(getattr(outcome, "verdict", ""))
+    if acted and verified:
+        return "execution_completed", "completed", "completed", "MATCH"
+    if acted and not verified:
+        return "execution_failed", "failed", "tool_error", "DRIFT"
+    if verdict_status == "refused-by-effector":
+        return "execution_failed", "failed", "binding_failed", "UNVERIFIABLE"
+    if decision == "deny":
+        return "execution_failed", "cancelled", "policy_denied", "UNVERIFIABLE"
+    if decision == "needs-human":
+        return "execution_failed", "cancelled", "verification_unverifiable", "UNVERIFIABLE"
+    return "execution_failed", "failed", "error", "UNVERIFIABLE"
+
+
+def _external_request_id(nc: dict) -> str | None:
+    if not nc:
+        return None
+    return f"native-control:{nc.get('at', '')}:{sha256_hex(canonical(nc).encode('utf-8'))[:16]}"
+
+
+def _identity_block(base_id: str, idempotency_key: str, created_at: str, principal: str,
+                    action_kind: str, args_hash: str, side_effect_class: str,
+                    intent_ref: str, authority_ref: str | None, decision: str) -> dict:
+    """The identity, component, action, and authority fields -- everything about WHO
+    acted and under WHAT permission, before the execution facts are joined in."""
+    return {
+        "schema": SCHEMA,
+        "event_id": f"evt_{base_id}",
+        "action_id": f"act_{base_id}",
+        "action_intent_id": f"intent_{base_id}",
+        "idempotency_key": idempotency_key,
+        "created_at": created_at,
+        "agent": {"principal": principal},
+        "component": {"name": RECEPTOR["name"], "version": RECEPTOR["version"], "config_hash": _config_hash()},
+        "action": {"kind": action_kind, "side_effect_class": side_effect_class, "args_hash": args_hash},
+        "intent_ref": intent_ref,
+        "authority_ref": authority_ref,
+        "policy": {"decision": decision, "ref": "policy:native-control-read-v1"},
+    }
+
+
+def _execution_block(state: str, idempotency_key: str, outcome: Any, nc: dict) -> dict:
+    """The joinable execution facts: a durable external id, the idempotency key, the
+    redacted before/after digests, and the native-control receipt's own digest."""
+    return {
+        "terminal_status": state,
+        "external_request_id": _external_request_id(nc),
+        "idempotency_key": idempotency_key,
+        "redacted_before_ref": str(getattr(outcome, "before_digest", "")),
+        "redacted_after_ref": str(getattr(outcome, "after_digest", "") or ""),
+        "native_control_schema": nc.get("schema"),
+        "native_control_receipt_digest": _digest(nc) if nc else None,
+    }
+
+
+def receipt_from_outcome(
+    outcome: Any,
+    *,
+    action_kind: str,
+    target: str,
+    args_hash: str,
+    native_control_receipt: dict | None = None,
+    principal: str = "agent:accountable-surface.native-control",
+    intent_ref: str = "intent:native-control-read",
+    authority_ref: str | None = None,
+    idempotency_key: str,
+    created_at: str,
+    side_effect_class: str = "read",
+    reversible: bool = True,
+) -> dict:
+    """Build a `project-telos.action-receipt/v1` event from an actuation outcome.
+
+    IDs are derived from the invocation and the injected `created_at`, so a fixed clock
+    yields a byte-stable event. `receipts[].hash` is computed last, over every field
+    except itself, so it seals the event's semantic content."""
+    event_type, state, stop_reason, verdict = _outcome_terms(outcome)
+    nc = native_control_receipt or {}
+    base_id = sha256_hex(f"{action_kind}|{target}|{args_hash}|{created_at}".encode("utf-8"))[:24]
+    before = str(getattr(outcome, "before_digest", ""))
+    core = {
+        **_identity_block(base_id, idempotency_key, created_at, principal, action_kind,
+                          args_hash, side_effect_class, intent_ref, authority_ref,
+                          str(getattr(outcome, "decision", "deny"))),
+        "event_type": event_type,
+        "input_materials": [{"ref": f"dir://{target}", "digest": before}],
+        "side_effect": {"class": side_effect_class, "reversible": reversible},
+        "execution": _execution_block(state, idempotency_key, outcome, nc),
+        "evidence_ref": _digest({"before": before, "after": getattr(outcome, "after_digest", "")}),
+        "verification": {"verdict": verdict, "ref": "accountable-surface:native-control-list"},
+        "result": {"state": state, "stop_reason": stop_reason},
+        "retry": {"attempt": 1, "max_attempts": 1},
+        "compensation_ref": None,
+        "persistence": {"append_only": True, "storage_ref": f"receipt:{action_kind}/evt_{base_id}"},
+        "certificate": dict(getattr(outcome, "certificate", {}) or {}),
+    }
+    core["receipts"] = [{"kind": "content", "hash": _digest(core)}]
+    return core
+
+
+class ActionReceiptReceptor:
+    """Append-only, hash-chained writer for action-receipt/v1 events. `emit` returns the
+    persistence receipt the contract's receptor adapter promises: event_id, action_id,
+    write_hash, and storage_ref."""
+
+    def __init__(self, store_path: str | Path) -> None:
+        self._path = Path(store_path)
+        self._head = _chain_head(self._path)
+
+    def emit(self, event: dict) -> dict:
+        prev = self._head
+        line_hash = sha256_hex(f"{prev}|{canonical(event)}".encode("utf-8"))
+        record = {**event, "_prev": prev, "_hash": line_hash}
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        with self._path.open("a", encoding="utf-8") as handle:
+            handle.write(canonical(record) + "\n")
+        self._head = line_hash
+        return {
+            "event_id": event["event_id"],
+            "action_id": event["action_id"],
+            "write_hash": line_hash,
+            "storage_ref": event["persistence"]["storage_ref"],
+        }
+
+
+def _chain_head(path: str | Path) -> str:
+    p = Path(path)
+    if not p.exists():
+        return GENESIS
+    head = GENESIS
+    for line in p.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            rec = json.loads(stripped)
+            head = rec.get("_hash", head)
+        except ValueError:
+            continue
+    return head
+
+
+def verify_receipts(text: str) -> tuple[str, str]:
+    """Re-derive the receipt stream offline. Returns (label, detail):
+      MATCH        -- every content hash and chain link re-derives.
+      DRIFT        -- a content hash or chain linkage does not re-derive (edit/reorder/delete).
+      UNVERIFIABLE -- a line will not parse or is missing the fields to re-derive.
+    Depends only on stdlib + the shared canonical form; a stranger with the file runs it."""
+    head = GENESIS
+    seq = 0
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            rec = json.loads(stripped)
+        except ValueError:
+            return "UNVERIFIABLE", f"line {seq} is not valid JSON"
+        if not isinstance(rec, dict) or "_hash" not in rec or "receipts" not in rec:
+            return "UNVERIFIABLE", f"entry {seq} is missing chain or receipt fields"
+        event = {k: v for k, v in rec.items() if k not in ("_prev", "_hash")}
+        core = {k: v for k, v in event.items() if k != "receipts"}
+        try:
+            stored_content = rec["receipts"][0]["hash"]
+        except (KeyError, IndexError, TypeError):
+            return "UNVERIFIABLE", f"entry {seq} carries no content hash to re-derive"
+        if _digest(core) != stored_content:
+            return "DRIFT", f"entry {seq} content hash does not re-derive from its fields"
+        expected = sha256_hex(f"{head}|{canonical(event)}".encode("utf-8"))
+        if rec.get("_prev") != head:
+            return "DRIFT", f"entry {seq} _prev does not link to the running chain head"
+        if rec.get("_hash") != expected:
+            return "DRIFT", f"entry {seq} _hash does not re-derive from its fields"
+        head = rec["_hash"]
+        seq += 1
+    return "MATCH", f"chain intact over {seq} receipts"

accountable_surface/api_effector.py

@@ -0,0 +1,287 @@
+"""API actuation for the efferent arm -- write through a third party's OFFICIAL API,
+under the same Effector contract as the other four.
+
+The answer to "the agents operate our API, and our API operates theirs". What a
+remote agent hands in is an intent: `post_comment` and a body. It cannot name a
+credential, cannot set a header, cannot choose a host, and cannot read a token
+back, because the secret is resolved inside `act` from an environment variable the
+agent has no way to address.
+
+Three bounds, each enforced at the moment of the call rather than trusted from the
+plan:
+
+  * the service allowlist -- method, host, and path SHAPE. An intent the service
+    does not declare is refused; a target path the intent's shape does not match is
+    refused, so `post_comment` cannot reach an admin route.
+  * the gate allow -- the receipt has to be bound to this exact plan.
+  * the credential -- drawn through `require_secret` at call time and sent in a
+    header. The token is checked against the URL first, because the URL is what the
+    surface witnesses into the journal and a secret must never land there.
+
+Verification reads the RESOURCE, never the response. A service that answers 201 and
+drops the write is the obvious way a passing verify could accept a wrong result, and
+re-reading the collection is the only thing that catches it. `tests/test_false_success.py`
+holds that case.
+
+`FakeApiDriver` makes the whole contract testable offline with no network and no real
+credential. The stdlib transport lives in `api_transport.py`, deliberately apart.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from coherence_membrane.observation import Observation, Provenance, Status, sha256_hex
+
+from accountable_surface.credentials import require_secret
+from accountable_surface.effector import Plan, RefusedActuation, Verdict
+
+
+def _canon(obj: Any) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+@dataclass(frozen=True)
+class ApiOperation:
+    """One thing a remote agent may ask for, named by intent rather than by route."""
+
+    intent: str  # what the agent names: "post_comment"
+    action_kind: str  # what the gate authorizes: "api.post"
+    method: str
+    path_shape: str  # anchored regex the target path must match; named groups feed the undo
+    undo_method: str = ""  # empty when the service offers no undo -> the plan is irreversible
+    undo_shape: str = ""  # e.g. "/repos/{owner}/{repo}/issues/comments/{id}"
+
+    @property
+    def reversible(self) -> bool:
+        return bool(self.undo_method)
+
+
+@dataclass(frozen=True)
+class ApiService:
+    """A single third-party API, and the complete set of writes allowed against it."""
+
+    name: str
+    host: str
+    auth_env: str
+    operations: tuple[ApiOperation, ...]
+    auth_scheme: str = "Bearer"
+    scheme: str = "https"
+
+    @property
+    def origin(self) -> str:
+        return f"{self.scheme}://{self.host}"
+
+
+@dataclass(frozen=True)
+class ApiCall:
+    """What the agent hands in. No token, no header, no host, no method."""
+
+    intent: str
+    body: dict = field(default_factory=dict)
+
+
+GITHUB_ISSUE_COMMENTS = ApiService(
+    name="github",
+    host="api.github.com",
+    auth_env="ACCOUNTABLE_SURFACE_GITHUB_TOKEN",
+    operations=(
+        ApiOperation(
+            intent="post_comment",
+            action_kind="api.post",
+            method="POST",
+            path_shape=r"/repos/(?P<owner>[^/]+)/(?P<repo>[^/]+)/issues/(?P<number>\d+)/comments",
+            undo_method="DELETE",
+            undo_shape="/repos/{owner}/{repo}/issues/comments/{id}",
+        ),
+    ),
+)
+
+
+class FakeApiDriver:
+    """Deterministic in-memory API for tests and offline demos.
+
+    Holds collections keyed by path. A POST appends a member and assigns an id; a
+    DELETE removes one by id. Records every request it was handed, so a test can
+    assert what did and did not travel (a credential, above all).
+    """
+
+    def __init__(self, collections: dict[str, list[dict]] | None = None) -> None:
+        self._collections: dict[str, list[dict]] = collections or {}
+        self._next_id = 1
+        self.requests: list[dict] = []
+
+    def request(self, method: str, url: str, headers: dict, body: bytes | None) -> dict:
+        self.requests.append({"method": method, "url": url, "headers": dict(headers), "body": body})
+        path = url.split("//", 1)[-1].split("/", 1)[-1]
+        path = "/" + path if not path.startswith("/") else path
+        if method == "GET":
+            return {"status": 200, "body": _canon(self._collections.get(path, []))}
+        if method == "POST":
+            member = dict(json.loads(body or b"{}"))
+            member["id"] = self._next_id
+            self._next_id += 1
+            self._collections.setdefault(path, []).append(member)
+            return {"status": 201, "body": _canon(member)}
+        if method == "DELETE":
+            wanted = path.rsplit("/", 1)[-1]
+            for members in self._collections.values():
+                members[:] = [m for m in members if str(m.get("id")) != wanted]
+            return {"status": 204, "body": b""}
+        return {"status": 405, "body": b""}
+
+
+class ApiEffector:
+    """Writes through one service's official API, bounded by that service's declared
+    operations, acting only on a gate allow for the exact plan, verified by re-reading
+    the resource rather than by believing the response."""
+
+    name = "api-effector"
+
+    def __init__(self, driver: Any, service: ApiService) -> None:
+        self._driver = driver
+        self._service = service
+        self._planned: dict[str, tuple[ApiOperation, dict]] = {}  # plan.digest -> intent (no secret)
+        self._prior: dict[str, str] = {}  # plan.digest -> the undo path, resolved at act time
+
+    def bound(self) -> dict:
+        """Origin AND intents: both decide how far a gate allow can travel."""
+        return {
+            "kind": "api",
+            "origins": [self._service.origin],
+            "intents": sorted(op.intent for op in self._service.operations),
+        }
+
+    # --- perception ----------------------------------------------------------
+
+    def perceive(self, target: str) -> Observation:
+        """A witnessed read of the resource the action will change. This is the
+        before-state, and it is what makes verification possible at all."""
+        url = self._url(target)
+        response = self._send("GET", url, None)
+        members = self._members(response.get("body") or b"")
+        return Observation(
+            organ=self.name,
+            subject=url,
+            summary=f"{self._service.name} {target}: {len(members)} members",
+            # a read that did not land establishes nothing about the resource
+            status=Status.PASS if response.get("status") == 200 else Status.UNVERIFIED,
+            provenance=Provenance.witness_bytes(url, _canon(members), "high"),
+            data={"url": url, "status": response.get("status"), "members": members,
+                  "sha256": sha256_hex(_canon(members))},
+        )
+
+    # --- the efferent contract ----------------------------------------------
+
+    def preview(self, target: str, call: ApiCall, before: Observation | None = None) -> Plan:
+        """Resolve the intent against the service allowlist and content-address the
+        request. No side effect, no credential read, no network."""
+        op = self._operation(call.intent)
+        if re.fullmatch(op.path_shape, target) is None:
+            raise RefusedActuation(
+                f"target {target!r} does not match the path shape for intent {call.intent!r}")
+        body = _canon(call.body)
+        url = self._url(target)
+        content_sha = sha256_hex(body)
+        digest = "sha256:" + sha256_hex(f"{op.action_kind}|{url}|{content_sha}".encode("utf-8"))
+        self._planned[digest] = (op, dict(call.body))
+        return Plan(op.action_kind, url, content_sha, op.reversible, False, digest)
+
+    def act(self, plan: Plan, allow_receipt: Any, call: ApiCall) -> Observation:
+        """Send the request. Refuses without a gate allow bound to this plan, and
+        resolves the credential only here, at the moment of the call."""
+        if getattr(allow_receipt, "decision", None) != "allow":
+            raise RefusedActuation("no gate allow -- the effector will not call anything")
+        request = getattr(allow_receipt, "request", {}) or {}
+        planned = request.get("planned_action", {}) if isinstance(request, dict) else {}
+        if planned.get("action_kind") != plan.action_kind or planned.get("target") != plan.target:
+            raise RefusedActuation("allow receipt does not match the plan's action/target")
+        op, _ = self._planned.get(plan.digest, (None, None))
+        if op is None or op.intent != call.intent:
+            raise RefusedActuation("call does not match the previewed (authorized) plan")
+        body = _canon(call.body)
+        if sha256_hex(body) != plan.content_sha256:
+            raise RefusedActuation("request body does not match the previewed (authorized) plan")
+        response = self._send(op.method, plan.target, body)
+        if op.reversible:
+            self._prior[plan.digest] = self._undo_path(op, plan.target, response)
+        return self.perceive(self._path(plan.target))
+
+    def verify(self, plan: Plan, after: Observation) -> Verdict:
+        """Does the RESOURCE now carry the intent? Re-reads the collection; a 201 on
+        the write is not evidence and is never consulted here."""
+        op, intent = self._planned.get(plan.digest, (None, None))
+        if intent is None:
+            return Verdict("failed", "no previewed intent for this plan")
+        for member in after.data.get("members", []):
+            projection = {k: member.get(k) for k in intent if k in member}
+            if projection == intent:
+                return Verdict("pass", "resource carries the intent")
+        return Verdict("failed", "resource does NOT carry the intent (the write did not land)")
+
+    def rollback(self, plan: Plan) -> Observation:
+        """The service's own undo, where it declares one."""
+        path = self._prior.get(plan.digest)
+        if path is None:
+            raise RefusedActuation("no undo recorded for this plan -- the call is irreversible")
+        op, _ = self._planned[plan.digest]
+        self._send(op.undo_method, self._url(path), None)
+        return self.perceive(self._path(plan.target))
+
+    def selftest(self) -> bool:
+        """Falsifiable: an act without a gate allow must raise and send nothing."""
+        driver = FakeApiDriver({"/repos/o/r/issues/1/comments": []})
+        effector = ApiEffector(driver, GITHUB_ISSUE_COMMENTS)
+        call = ApiCall("post_comment", {"body": "hi"})
+        plan = effector.preview("/repos/o/r/issues/1/comments", call)
+        try:
+            effector.act(plan, allow_receipt=None, call=call)
+            return False
+        except RefusedActuation:
+            return not driver.requests
+
+    # --- internals -----------------------------------------------------------
+
+    def _operation(self, intent: str) -> ApiOperation:
+        for op in self._service.operations:
+            if op.intent == intent:
+                return op
+        declared = sorted(o.intent for o in self._service.operations)
+        raise RefusedActuation(f"intent {intent!r} is not declared by {self._service.name}: {declared}")
+
+    def _url(self, target: str) -> str:
+        return target if target.startswith(self._service.origin) else self._service.origin + target
+
+    def _path(self, url: str) -> str:
+        return url[len(self._service.origin):] if url.startswith(self._service.origin) else url
+
+    def _members(self, payload: bytes) -> list[dict]:
+        try:
+            data = json.loads(payload or b"[]")
+        except json.JSONDecodeError:
+            return []
+        if isinstance(data, dict):
+            return [data]
+        return [m for m in data if isinstance(m, dict)] if isinstance(data, list) else []
+
+    def _undo_path(self, op: ApiOperation, url: str, response: dict) -> str:
+        parts = re.fullmatch(op.path_shape, self._path(url))
+        created = self._members(response.get("body") or b"")
+        ident = created[0].get("id") if created else None
+        return op.undo_shape.format(id=ident, **(parts.groupdict() if parts else {}))
+
+    def _send(self, method: str, url: str, body: bytes | None) -> dict:
+        """The single place a credential is read, and the single place one leaves."""
+        token = require_secret(self._service.auth_env)
+        if token in url:
+            # the URL is witnessed into the journal; the secret travels in a header only
+            raise RefusedActuation("the credential must not appear in the URL; it is sent as a header")
+        if not url.startswith(self._service.origin + "/"):
+            raise RefusedActuation(f"url {url!r} is outside the service origin {self._service.origin}")
+        headers = {"Authorization": f"{self._service.auth_scheme} {token}", "Accept": "application/json"}
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        return self._driver.request(method, url, headers, body)

accountable_surface/api_transport.py

@@ -0,0 +1,34 @@
+"""The stdlib transport behind `ApiEffector`. Kept apart from the effector on purpose.
+
+Zero dependencies: `urllib.request` and nothing else, matching the rest of this
+repository's native posture. It carries no policy. Every bound that matters (the
+service allowlist, the path shape, the gate allow, the credential door) is enforced
+in `ApiEffector` before a request reaches here, so this file is a socket and not a
+gate.
+
+Honest null: this driver has no test coverage. Exercising it needs a network and a
+real credential, and the suite has neither by design, so `FakeApiDriver` is what the
+tests drive. Treat a first real call as unproven and watch it.
+"""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+
+
+class UrllibApiDriver:
+    """Sends one request and returns `{"status", "body"}`. Raises nothing on a 4xx or
+    5xx: an error status is a fact the effector's verify has to see, not an exception
+    that hides what the service said."""
+
+    def __init__(self, timeout: float = 20.0) -> None:
+        self._timeout = timeout
+
+    def request(self, method: str, url: str, headers: dict, body: bytes | None) -> dict:
+        request = urllib.request.Request(url, data=body, headers=dict(headers), method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                return {"status": response.status, "body": response.read()}
+        except urllib.error.HTTPError as exc:
+            return {"status": exc.code, "body": exc.read()}