handcode 0.3.0rc1__py3-none-any.whl

agentctl/kernel/ledger/models.py

@@ -0,0 +1,160 @@
+"""Core types for the effect ledger.
+
+Spec: `docs/0012` §2. No I/O here, no dependencies beyond the stdlib — this
+module is imported by everything in the kernel.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class EffectClass(str, Enum):
+    """How a tool's side effect behaves under repetition.
+
+    Ordering matters: `DESTRUCTIVE` is the safe default direction, so an
+    unknown tool must never classify below `EXTERNAL`.
+    """
+
+    PURE_READ = "PURE_READ"
+    IDEMPOTENT_WRITE = "IDEMPOTENT_WRITE"
+    NON_IDEMPOTENT_WRITE = "NON_IDEMPOTENT_WRITE"
+    EXTERNAL = "EXTERNAL"
+    DESTRUCTIVE = "DESTRUCTIVE"
+
+    @property
+    def severity(self) -> int:
+        """Rank by danger. Used to resolve competing classification rules.
+
+        A command can match several rules (`ls && rm -rf x` matches both a
+        benign prefix and a destructive one). The classifier must take the
+        most dangerous match, never the first.
+        """
+        return _SEVERITY[self]
+
+    @property
+    def replay_safe(self) -> bool:
+        """Safe to run again when we cannot tell whether it already ran."""
+        return self in (EffectClass.PURE_READ, EffectClass.IDEMPOTENT_WRITE)
+
+    @property
+    def speculation_safe(self) -> bool:
+        """Safe to run *before* we know we want to, then discard.
+
+        Strictly stricter than `replay_safe` (`docs/0010` §6.4): an idempotent
+        write is safe to repeat but a discarded speculative write has still
+        mutated the world.
+        """
+        return self is EffectClass.PURE_READ
+
+
+_SEVERITY: dict[EffectClass, int] = {
+    EffectClass.PURE_READ: 0,
+    EffectClass.IDEMPOTENT_WRITE: 1,
+    EffectClass.NON_IDEMPOTENT_WRITE: 2,
+    EffectClass.EXTERNAL: 3,
+    EffectClass.DESTRUCTIVE: 4,
+}
+
+
+class EffectState(str, Enum):
+    INTENT = "INTENT"        # written before execution; the ambiguous state
+    COMMITTED = "COMMITTED"  # tool returned; observation stored
+    #: The tool's result -- success OR reported failure -- is durably in the
+    #: conversation history the model reads. A later identical call is then
+    #: the model deciding to repeat, not the harness replaying (`docs/0045`).
+    OBSERVED = "OBSERVED"
+    FAILED = "FAILED"        # provably did not land
+    BLOCKED = "BLOCKED"      # fail-closed; awaiting a human
+
+
+#: Legal transitions. Anything else is a bug and raises.
+TRANSITIONS: dict[EffectState | None, set[EffectState]] = {
+    None: {EffectState.INTENT},
+    EffectState.INTENT: {
+        EffectState.COMMITTED, EffectState.FAILED,
+        EffectState.BLOCKED, EffectState.INTENT,   # retry after FAILED bumps attempt
+        # Straight to OBSERVED in one write when the harness has already
+        # persisted the observation. Going through COMMITTED would open a crash
+        # window in which a reported failure sat as COMMITTED (`docs/0031`).
+        EffectState.OBSERVED,
+    },
+    EffectState.COMMITTED: {EffectState.OBSERVED},
+    EffectState.FAILED: {EffectState.INTENT},
+    EffectState.BLOCKED: {
+        EffectState.COMMITTED, EffectState.FAILED, EffectState.INTENT,
+    },  # human resolution only
+    EffectState.OBSERVED: set(),
+}
+
+
+class IllegalTransition(RuntimeError):
+    """Raised inside the store, never past `EffectGate.guard`."""
+
+
+class Verdict(str, Enum):
+    EXECUTE = "EXECUTE"          # run the tool
+    SUBSTITUTE = "SUBSTITUTE"    # return the stored observation (Seam C only)
+    BLOCK = "BLOCK"              # refuse; fail closed
+    ESCALATE = "ESCALATE"        # refuse; a human must decide
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """One tool invocation, normalised away from any harness."""
+
+    tool_call_id: str
+    conversation_id: str
+    turn_id: str
+    tool_name: str
+    args: dict = field(default_factory=dict)
+
+    def intent_hash(self) -> str:
+        """Stable fingerprint of *what this call would do*.
+
+        Guards against a `tool_call_id` being reused with different arguments,
+        which would otherwise let the ledger substitute the wrong observation.
+        """
+        canonical = json.dumps(
+            {"t": self.tool_name, "a": self.args},
+            sort_keys=True, separators=(",", ":"), default=str,
+        )
+        return hashlib.sha256(canonical.encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class EffectRecord:
+    tool_call_id: str
+    conversation_id: str
+    turn_id: str
+    tool_name: str
+    intent_hash: str
+    effect_class: EffectClass
+    state: EffectState
+    fence_token: int
+    attempt: int
+    started_at: float
+    committed_at: float | None = None
+    observation: bytes | None = None
+    probe_verdict: str | None = None
+    pre_state: str | None = None
+    error: str | None = None
+    action_event_id: str | None = None
+
+
+@dataclass(frozen=True)
+class GateDecision:
+    verdict: Verdict
+    effect_class: EffectClass | None = None
+    observation: bytes | None = None
+    reason: str | None = None
+    #: For SUBSTITUTE: the record whose result is being handed back. Under
+    #: intent-hash aliasing it is not the caller's id, and it is the record to
+    #: mark OBSERVED once the substituted result reaches the model.
+    record_id: str | None = None
+
+    @property
+    def allows_execution(self) -> bool:
+        return self.verdict is Verdict.EXECUTE

agentctl/kernel/ledger/schema.sql

@@ -0,0 +1,62 @@
+-- Effect ledger. docs/0012 §2.1
+--
+-- synchronous = FULL is deliberate and non-negotiable: NORMAL can lose the
+-- last commit on power failure, and that is exactly the record whose absence
+-- causes a double effect.
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous  = FULL;
+
+CREATE TABLE IF NOT EXISTS effect_record (
+    tool_call_id     TEXT    PRIMARY KEY,
+    conversation_id  TEXT    NOT NULL,
+    turn_id          TEXT    NOT NULL,
+    action_event_id  TEXT,
+    tool_name        TEXT    NOT NULL,
+    intent_hash      TEXT    NOT NULL,
+    effect_class     TEXT    NOT NULL,
+    state            TEXT    NOT NULL,
+    fence_token      INTEGER NOT NULL,
+    attempt          INTEGER NOT NULL DEFAULT 1,
+    started_at       REAL    NOT NULL,
+    committed_at     REAL,
+    observation      BLOB,
+    probe_verdict    TEXT,
+    -- World fingerprint captured BEFORE execution, so a probe can later ask
+    -- "did anything change?" without the tool having cooperated. docs/0016b
+    pre_state        TEXT,
+    error            TEXT,
+    CHECK (state IN ('INTENT','COMMITTED','OBSERVED','FAILED','BLOCKED')),
+    CHECK (effect_class IN
+        ('PURE_READ','IDEMPOTENT_WRITE','NON_IDEMPOTENT_WRITE','EXTERNAL','DESTRUCTIVE'))
+);
+
+CREATE INDEX IF NOT EXISTS ix_effect_conv ON effect_record(conversation_id, turn_id);
+
+-- The recovery scan: everything needing attention after a crash.
+CREATE INDEX IF NOT EXISTS ix_effect_open ON effect_record(state)
+    WHERE state IN ('INTENT','BLOCKED');
+
+-- Fencing: one live writer per conversation.
+CREATE TABLE IF NOT EXISTS lease (
+    conversation_id TEXT PRIMARY KEY,
+    holder          TEXT    NOT NULL,
+    fence_token     INTEGER NOT NULL,
+    expires_at      REAL    NOT NULL
+);
+
+-- Decisions a human made on actions that asked first (docs/0042 I-06). With
+-- no terminal to ask at, a dangerous action is queued as BLOCKED awaiting
+-- approval; `agentctl approve` / `deny` records the answer here, keyed by
+-- what the action IS (its intent hash), so the identical call the agent makes
+-- on resume is recognised. An approval is used once.
+CREATE TABLE IF NOT EXISTS approval (
+    conversation_id TEXT    NOT NULL,
+    intent_hash     TEXT    NOT NULL,
+    tool_call_id    TEXT,
+    summary         TEXT,
+    decision        TEXT    NOT NULL CHECK (decision IN ('approve', 'deny')),
+    decided_at      REAL    NOT NULL,
+    told_at         REAL,
+    used_at         REAL,
+    PRIMARY KEY (conversation_id, intent_hash)
+);