interlock-escrow 0.3.0__py3-none-any.whl

interlock/__init__.py

@@ -0,0 +1,224 @@
+"""Interlock: a reference monitor for agent side effects.
+
+An agent proposes a plan. It holds no credentials and cannot execute. Interlock
+applies the plan against a real but uncommitted substrate, measures what
+actually changed, evaluates deterministic predicates against that measurement,
+and only then commits or rolls back.
+
+The position exists because a prompt-injected agent is a fully authorized
+agent. It is doing something it has permission to do, so an authorization check
+passes, and the injected instruction arrived inside a tool result after every
+provider-side filter had run, so a provider-side filter does not see it. What
+is left is measuring the consequence before it becomes durable.
+
+    from interlock import EscrowRuntime, TableSpec
+
+    runtime = EscrowRuntime(
+        "prod.db",
+        tables=[TableSpec("orders", columns=["id", "tenant", "total"],
+                          tenant_column="tenant")],
+        scope_id="support-agent",
+    )
+    result = runtime.execute_sql(
+        "UPDATE orders SET total = :total WHERE id = :id",
+        {"total": 100.0, "id": 1},
+        tenant_id="acme",
+        stated_rows=1,
+    )
+
+    if not result.committed:
+        print(result.blocked_by, result.diff.blast_radius)
+
+``EscrowRuntime`` owns the substrate, chain, anchor and engine. Drop to
+:class:`EscrowEngine` and :class:`PlanBuilder` when you need the primitives;
+the runtime is sugar over them and hands both back.
+
+Every adjudication is written to a hash-linked chain, anchored to an AgentGov
+ledger when one is attached. See :mod:`interlock.anchor` for the seam, which is
+read-only by default.
+
+Two substrates, SQLite and PostgreSQL, and a measurement scoped to the tables
+each was configured to observe. ``docs/ESCROW_SPEC.md`` has a conformance
+section listing what is implemented, partial and unimplemented; read it before
+putting this in front of a production database.
+"""
+
+from __future__ import annotations
+
+from interlock.anchor import AnchorPoint, LedgerAnchor
+from interlock.builder import PlanBuilder, new_effect_id, new_plan_id
+from interlock.cascade import CascadeReport
+from interlock.chain import EscrowChain, EscrowRecord, RecordType
+from interlock.engine import EscrowEngine, StageResult
+from interlock.exceptions import (
+    AdmissionError,
+    AnchorError,
+    ChainIntegrityError,
+    ChainInUseError,
+    CommitUnsettledError,
+    CyclicPlanError,
+    ExtensionError,
+    ForbiddenStatementError,
+    InterlockError,
+    LedgerUnverifiedError,
+    PlanError,
+    RecordIntegrityError,
+    RecoveryError,
+    RecoveryExhaustedError,
+    ScopeHaltedError,
+    StageConflictError,
+    StageError,
+    StageExpiredError,
+    SubstrateConfigurationError,
+    SubstrateUnavailableError,
+    ToolRevokedError,
+    UncompensatableEffectError,
+)
+from interlock.extension import (
+    BudgetGuard,
+    Estimate,
+    ExtensionGrant,
+    ExtensionRequest,
+    Milestones,
+    Progress,
+    Spend,
+)
+from interlock.feedback import AgentFeedback, ConstraintFeedback, OperatorEvidence, Refusal
+from interlock.invariants import (
+    BlastRadius,
+    ColumnValueGuard,
+    InvariantChecker,
+    NoDelete,
+    NoSchemaChange,
+    StatedFootprint,
+    TableAllowlist,
+    TenantDrawdownGuard,
+    TenantIsolation,
+    TruncationGuard,
+    default_checkers,
+)
+from interlock.postgres import PostgresSubstrate
+from interlock.receipts import ReceiptIssuer
+from interlock.records import RecordKind, RecordLog, SignedRecord, check_anchors, verify_records
+from interlock.recovery import (
+    Channel,
+    Directive,
+    RecoveryPolicy,
+    RecoveryRuntime,
+    RecoveryStep,
+    Rung,
+    Trip,
+    TripKind,
+)
+from interlock.repair import DroppedEffect, Repair, RepairFeedback
+from interlock.runtime import EscrowRuntime
+from interlock.substrate import ShadowSubstrate, SqliteSubstrate, TableSpec
+from interlock.types import (
+    Compensation,
+    Effect,
+    EffectDiff,
+    EffectId,
+    EffectKind,
+    EffectPlan,
+    InvariantViolation,
+    PlanId,
+    RowDelta,
+    Severity,
+    StageState,
+    Verdict,
+)
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "AdmissionError",
+    "AgentFeedback",
+    "AnchorError",
+    "AnchorPoint",
+    "BlastRadius",
+    "BudgetGuard",
+    "CascadeReport",
+    "ChainInUseError",
+    "ChainIntegrityError",
+    "Channel",
+    "ColumnValueGuard",
+    "CommitUnsettledError",
+    "Compensation",
+    "ConstraintFeedback",
+    "CyclicPlanError",
+    "Directive",
+    "DroppedEffect",
+    "Effect",
+    "EffectDiff",
+    "EffectId",
+    "EffectKind",
+    "EffectPlan",
+    "EscrowChain",
+    "EscrowEngine",
+    "EscrowRecord",
+    "EscrowRuntime",
+    "Estimate",
+    "ExtensionError",
+    "ExtensionGrant",
+    "ExtensionRequest",
+    "ForbiddenStatementError",
+    "InterlockError",
+    "InvariantChecker",
+    "InvariantViolation",
+    "LedgerAnchor",
+    "LedgerUnverifiedError",
+    "Milestones",
+    "NoDelete",
+    "NoSchemaChange",
+    "OperatorEvidence",
+    "PlanBuilder",
+    "PlanError",
+    "PlanId",
+    "PostgresSubstrate",
+    "Progress",
+    "ReceiptIssuer",
+    "RecordIntegrityError",
+    "RecordKind",
+    "RecordLog",
+    "RecordType",
+    "RecoveryError",
+    "RecoveryExhaustedError",
+    "RecoveryPolicy",
+    "RecoveryRuntime",
+    "RecoveryStep",
+    "Refusal",
+    "Repair",
+    "RepairFeedback",
+    "RowDelta",
+    "Rung",
+    "ScopeHaltedError",
+    "Severity",
+    "ShadowSubstrate",
+    "SignedRecord",
+    "Spend",
+    "SqliteSubstrate",
+    "StageConflictError",
+    "StageError",
+    "StageExpiredError",
+    "StageResult",
+    "StageState",
+    "StatedFootprint",
+    "SubstrateConfigurationError",
+    "SubstrateUnavailableError",
+    "TableAllowlist",
+    "TableSpec",
+    "TenantDrawdownGuard",
+    "TenantIsolation",
+    "ToolRevokedError",
+    "Trip",
+    "TripKind",
+    "TruncationGuard",
+    "UncompensatableEffectError",
+    "Verdict",
+    "__version__",
+    "check_anchors",
+    "default_checkers",
+    "new_effect_id",
+    "new_plan_id",
+    "verify_records",
+]

interlock/adjudication.py

@@ -0,0 +1,109 @@
+"""Running the checkers: one verdict, and a feedback hint for each violation.
+
+Split out of the engine because two paths adjudicate: :meth:`EscrowEngine.execute`
+for a submitted plan, and :meth:`EscrowEngine.repair` for every candidate
+sub-plan it tries. Both have to decide the same way.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from interlock.feedback import (
+    AgentFeedback,
+    FeedbackHint,
+    Guidance,
+    HintedViolation,
+    OperatorEvidence,
+    Refusal,
+    agent_feedback,
+)
+from interlock.invariants import BUILT_IN_CHECKERS, InvariantChecker
+from interlock.types import EffectDiff, EffectPlan, InvariantViolation, Severity, Verdict
+
+__all__ = ["Adjudication", "adjudicate"]
+
+logger = logging.getLogger("interlock.engine")
+
+
+@dataclass(frozen=True, slots=True)
+class Adjudication:
+    """A verdict, with what each of its violations may tell the agent."""
+
+    plan: EffectPlan
+    diff: EffectDiff
+    verdict: Verdict
+    hints: tuple[HintedViolation, ...]
+
+    @property
+    def admitted(self) -> bool:
+        return self.verdict.admitted
+
+    def feedback(self, *, committed: bool) -> AgentFeedback:
+        return agent_feedback(self.plan, self.hints, committed=committed)
+
+    def refusal(self) -> Refusal:
+        return Refusal(
+            evidence=OperatorEvidence.of(self.plan, diff=self.diff, verdict=self.verdict),
+            feedback=self.feedback(committed=False),
+        )
+
+
+def adjudicate(
+    plan: EffectPlan,
+    diff: EffectDiff,
+    checkers: Sequence[InvariantChecker],
+    *,
+    stage_id: uuid.UUID,
+) -> Adjudication:
+    """Run every checker and union the violations.
+
+    A checker that raises becomes a blocking violation: a predicate that did
+    not finish has not approved anything. A hint that raises, or is not a
+    :class:`FeedbackHint`, becomes the generic operator-constraint hint: the
+    agent loses detail, never the refusal.
+    """
+    violations: list[InvariantViolation] = []
+    hinted: list[HintedViolation] = []
+    names: list[str] = []
+    for checker in checkers:
+        names.append(checker.name)
+        try:
+            found = tuple(checker.check(plan, diff))
+        except Exception as exc:  # a broken checker must never approve
+            logger.exception("invariant %s raised", checker.name)
+            broken = InvariantViolation(
+                invariant=checker.name,
+                severity=Severity.BLOCKING,
+                message=f"checker raised {type(exc).__name__}: {exc}",
+            )
+            violations.append(broken)
+            hinted.append(HintedViolation(broken, FeedbackHint(kind=Guidance.OPERATOR)))
+            continue
+        violations.extend(found)
+        trusted = type(checker) in BUILT_IN_CHECKERS
+        offer = getattr(checker, "hint", None)
+        for violation in found:
+            hint = FeedbackHint(kind=Guidance.OPERATOR)
+            if callable(offer):
+                try:
+                    candidate = offer(plan, diff, violation)
+                except Exception:
+                    logger.exception("feedback hint for %s raised", checker.name)
+                else:
+                    if isinstance(candidate, FeedbackHint):
+                        hint = candidate
+            hinted.append(HintedViolation(violation, hint, trusted))
+    verdict = Verdict(
+        plan_id=plan.plan_id,
+        stage_id=stage_id,
+        diff_hash=diff.content_hash(),
+        decided_at=datetime.now(UTC),
+        checkers_run=tuple(names),
+        violations=tuple(violations),
+    )
+    return Adjudication(plan=plan, diff=diff, verdict=verdict, hints=tuple(hinted))