capability-reasoning-kernel 0.4.1__py3-none-any.whl

reasoning_kernel/schemas/policy.py

@@ -0,0 +1,64 @@
+"""The Verifier's vocabulary: a run's trusted context, a verdict, and the declassify hook.
+
+``DeclassPolicy`` is the single, auditable seam where tainted data is allowed to cross into a
+WRITE effect. It is a deterministic predicate — never an LLM — and (per the paper) it should
+compare against *trusted* (USER_QUERY) values only, never against substrings of tainted text.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from reasoning_kernel.schemas.ids import RunId
+from reasoning_kernel.schemas.provenance import ProvenanceLabel
+from reasoning_kernel.schemas.registry import ToolSpec
+from reasoning_kernel.schemas.values import TaintedValue
+
+
+class TrustedQuery(BaseModel):
+    """The controlled user query as an explicit trusted channel (Invariant A).
+
+    Carrying the label (not a bare ``str``/``NewType``) makes the trust assumption explicit and lets
+    planner-supplied literals DERIVE their provenance from the query: if the query were ever not
+    trusted, every ``const`` would inherit that taint automatically.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    text: str
+    label: ProvenanceLabel = ProvenanceLabel.trusted()
+
+
+class RunContext(BaseModel):
+    """Trusted, controlled facts about a run — available to the Verifier and declassifier."""
+
+    model_config = ConfigDict(frozen=True)
+
+    run_id: RunId
+    user: str  # the trusted requesting identity (e.g. the user's own email)
+    query: TrustedQuery  # the controlled user query (the only thing the P-LLM ever sees)
+
+
+class VerifierVerdict(BaseModel):
+    """The outcome of a verification check."""
+
+    allowed: bool
+    reason: str
+    issues: list[str] = Field(default_factory=list)
+
+
+class DeclassPolicy(Protocol):
+    """Decides whether tainted arguments may flow into a WRITE effect.
+
+    Implementations MUST be deterministic and free of LLM calls: the kernel invokes this on
+    the commit path and cannot enforce that contract through the type system.
+    """
+
+    def may_declassify(
+        self,
+        tool: ToolSpec,
+        named_args: dict[str, TaintedValue],
+        ctx: RunContext,
+    ) -> VerifierVerdict: ...

reasoning_kernel/schemas/provenance.py

@@ -0,0 +1,63 @@
+"""Provenance labels — the taint a value carries through the interpreter.
+
+This is the §6.1 mechanism: the kernel does not *sanitize* untrusted text, it *scopes the
+capabilities* that untrusted-derived data is permitted to flow into. A label records where
+a value came from (``sources``) and which capabilities it may flow into (``readers``).
+``readers=None`` means unrestricted, reserved for purely trusted data.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+from reasoning_kernel.schemas.capability import Capability
+
+
+class Source(StrEnum):
+    """Origin of a value. ``USER_QUERY`` is trusted; the rest taint."""
+
+    USER_QUERY = "user_query"  # the controlled query and planner literals (trusted)
+    TOOL_READ = "tool_read"  # anything a READ tool returned (untrusted)
+    Q_LLM = "q_llm"  # anything the quarantined reasoner produced (untrusted)
+    DERIVED = "derived"  # combined from >1 input
+
+
+class DataSubject(StrEnum):
+    """Whose data a value is about — orthogonal to trust, used for declassification scoping."""
+
+    USER = "user"  # the requesting user's own data
+    THIRD_PARTY = "third_party"  # anyone else (contacts, other inboxes, ...)
+
+
+_UNTRUSTED: frozenset[Source] = frozenset({Source.TOOL_READ, Source.Q_LLM, Source.DERIVED})
+
+
+class ProvenanceLabel(BaseModel):
+    """Immutable provenance label: where a value came from, where it may flow, who it is about."""
+
+    model_config = ConfigDict(frozen=True)
+
+    sources: frozenset[Source]
+    readers: frozenset[Capability] | None = None  # None = unrestricted (trusted only)
+    subjects: frozenset[DataSubject] = frozenset()  # empty = no third-party content
+
+    @property
+    def is_tainted(self) -> bool:
+        return bool(self.sources & _UNTRUSTED)
+
+    @property
+    def has_third_party(self) -> bool:
+        return DataSubject.THIRD_PARTY in self.subjects
+
+    def allows_reader(self, cap: Capability) -> bool:
+        """True if a value with this label may flow into an effect requiring ``cap``."""
+        if self.readers is None:
+            return True
+        return cap in self.readers
+
+    @classmethod
+    def trusted(cls) -> ProvenanceLabel:
+        """A label for data derived solely from the controlled user query."""
+        return cls(sources=frozenset({Source.USER_QUERY}), readers=None, subjects=frozenset())

reasoning_kernel/schemas/registry.py

@@ -0,0 +1,41 @@
+"""Tool specifications — the declared contract the Verifier checks a call against.
+
+A ``ToolSpec`` is pure data: name, typed input/output, the capabilities the call requires,
+its effect level, and ``result_readers`` — the capabilities that data RETURNED by the tool
+is allowed to flow into. A READ tool that surfaces untrusted content sets
+``result_readers=frozenset()`` so its output may flow into no WRITE.
+
+The callable itself is held elsewhere (``tools.registry.RegisteredTool``), never in the schema
+layer — so the contract can be inspected and reasoned about without holding the effect.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from reasoning_kernel.schemas.capability import Capability, EffectLevel
+from reasoning_kernel.schemas.provenance import DataSubject
+
+
+class ToolSpec(BaseModel):
+    """Declared, inspectable contract for one tool. Immutable."""
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    name: str
+    input_schema: type[BaseModel]
+    output_schema: type[BaseModel]
+    required_caps: frozenset[Capability]
+    effect_level: EffectLevel
+    result_readers: frozenset[Capability] = frozenset()
+    result_subjects: frozenset[DataSubject] = frozenset()  # whose data this tool's output is about
+
+    @model_validator(mode="after")
+    def _write_must_declare_capability(self) -> ToolSpec:
+        # A world-mutating effect must be gated by at least one capability; otherwise the
+        # provenance check would have no capability to reason about (see kernel/gate.py).
+        if self.effect_level >= EffectLevel.WRITE and not self.required_caps:
+            raise ValueError(
+                f"WRITE tool {self.name!r} must declare at least one required capability"
+            )
+        return self

reasoning_kernel/schemas/trace.py

@@ -0,0 +1,110 @@
+"""The auditable record (Memory/Trace role): an append-only log of everything that happened.
+
+Every plan, step, gate decision, commit, and block becomes a ``TraceEvent``. The trace is the
+home the paper gives to auditability: a wrong or blocked decision leaves a record of what was
+decided and why. Events carry a monotonic ``seq`` (assigned by the writer) rather than a wall
+clock, so traces are deterministic and comparable in tests.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from pydantic import BaseModel, ConfigDict
+
+from reasoning_kernel.schemas.ids import RunId, StepId
+from reasoning_kernel.schemas.plan import Plan, PlanStep
+from reasoning_kernel.schemas.policy import VerifierVerdict
+from reasoning_kernel.schemas.provenance import ProvenanceLabel
+from reasoning_kernel.schemas.values import TaintedValue
+
+
+def digest(value: object) -> str:
+    """A short, stable content digest for trace records (not a security primitive)."""
+    return hashlib.sha256(repr(value).encode("utf-8")).hexdigest()[:12]
+
+
+class TraceEvent(BaseModel):
+    """Base event. ``kind`` discriminates; ``seq`` is assigned by the TraceWriter on emit."""
+
+    kind: str = "event"
+    run_id: RunId
+    seq: int = -1
+
+
+class PlanEmitted(TraceEvent):
+    kind: str = "plan_emitted"
+    plan: Plan
+
+
+class StepStarted(TraceEvent):
+    kind: str = "step_started"
+    step: PlanStep
+
+
+class QParseResult(TraceEvent):
+    kind: str = "q_parse_result"
+    step_id: StepId
+    label: ProvenanceLabel
+
+
+class GateDecision(TraceEvent):
+    kind: str = "gate_decision"
+    tool: str
+    verdict: VerifierVerdict
+    arg_labels: list[ProvenanceLabel]
+
+
+class EffectCommitted(TraceEvent):
+    kind: str = "effect_committed"
+    tool: str
+    output_digest: str
+
+
+class EffectBlockedEvent(TraceEvent):
+    kind: str = "effect_blocked"
+    tool: str
+    verdict: VerifierVerdict
+
+
+class RunCommitted(TraceEvent):
+    kind: str = "run_committed"
+    final_digest: str
+
+
+class RunBlocked(TraceEvent):
+    kind: str = "run_blocked"
+    tool: str
+
+
+class PlanRejected(TraceEvent):
+    kind: str = "plan_rejected"
+    reason: str
+
+
+class RunErrored(TraceEvent):
+    kind: str = "run_errored"
+    step_id: StepId | None = None
+    reason: str
+
+
+class RunAborted(TraceEvent):
+    kind: str = "run_aborted"
+    step_id: StepId | None = None
+    reason: str
+
+
+class RunTrace(BaseModel):
+    """An immutable snapshot of a run's event log."""
+
+    run_id: RunId
+    events: list[TraceEvent]
+
+
+class RunResult(BaseModel):
+    """A run's outcome: the audit trace plus the committed final value (None if not committed)."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    trace: RunTrace
+    committed: TaintedValue | None = None

reasoning_kernel/schemas/values.py

@@ -0,0 +1,28 @@
+"""The wrapped value type that flows through the interpreter's value store.
+
+Every result the interpreter produces is a ``TaintedValue``: a payload plus its provenance
+label plus the step that produced it. Nothing reaches an effect except as a ``TaintedValue``,
+so the Verifier always has a label to reason about.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from reasoning_kernel.schemas.ids import StepId
+from reasoning_kernel.schemas.provenance import ProvenanceLabel
+
+
+class TaintedValue(BaseModel):
+    """A value carrying its provenance. Frozen; ``value`` is opaque to the kernel.
+
+    ``value`` is typed ``object`` rather than ``Any`` deliberately: the kernel never inspects the
+    payload, so the stricter type both documents that and keeps the trusted core free of ``Any``
+    leakage (the ``kernel`` and ``memory`` packages are type-checked in strict mode).
+    """
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    value: object
+    label: ProvenanceLabel
+    produced_by: StepId

reasoning_kernel/tools/demo_mail.py

@@ -0,0 +1,213 @@
+"""An in-memory mail world + tools, for the worked demo and tests.
+
+Three tools: ``read_inbox`` and ``read_contacts`` (READ — they introduce untrusted content, so
+their results may flow into no WRITE), and ``send_email`` (WRITE). The declassification policy
+allows a WRITE carrying tainted data only when the recipient is the trusted requesting user —
+a deterministic predicate over a USER_QUERY value, never over tainted text.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pydantic import BaseModel
+
+from reasoning_kernel.schemas.capability import Capability, CapabilitySet, EffectLevel
+from reasoning_kernel.schemas.policy import RunContext, VerifierVerdict
+from reasoning_kernel.schemas.provenance import DataSubject
+from reasoning_kernel.schemas.registry import ToolSpec
+from reasoning_kernel.schemas.values import TaintedValue
+from reasoning_kernel.tools.registry import ToolRegistry
+
+# --- capabilities -----------------------------------------------------------------
+CAP_MAIL_READ = Capability(name="mail.read")
+CAP_CONTACTS_READ = Capability(name="contacts.read")
+CAP_MAIL_SEND = Capability(name="mail.send")
+CAP_CALENDAR_WRITE = Capability(name="calendar.write")
+
+DEMO_GRANT = CapabilitySet(
+    granted=frozenset({CAP_MAIL_READ, CAP_CONTACTS_READ, CAP_MAIL_SEND, CAP_CALENDAR_WRITE})
+)
+
+
+# --- tool I/O schemas -------------------------------------------------------------
+class EmailMessage(BaseModel):
+    sender: str
+    subject: str
+    body: str
+
+
+class Contact(BaseModel):
+    name: str
+    email: str
+
+
+class ReadInboxIn(BaseModel):
+    pass
+
+
+class ReadInboxOut(BaseModel):
+    latest: EmailMessage
+
+
+class ReadContactsIn(BaseModel):
+    pass
+
+
+class ReadContactsOut(BaseModel):
+    contacts: list[Contact]
+
+
+class SendEmailIn(BaseModel):
+    to: str
+    body: str
+
+
+class SendEmailOut(BaseModel):
+    ok: bool
+    message_id: str
+
+
+class CreateEventIn(BaseModel):
+    title: str
+    date: str
+
+
+class CreateEventOut(BaseModel):
+    ok: bool
+    event_id: str
+
+
+class EmailSummary(BaseModel):
+    """Q-LLM output schema — data only, no actions."""
+
+    text: str
+
+
+# --- the mutable world ------------------------------------------------------------
+@dataclass
+class MailWorld:
+    inbox: list[EmailMessage]
+    contacts: list[Contact]
+    sent: list[SendEmailIn] = field(default_factory=list)
+    events: list[CreateEventIn] = field(default_factory=list)
+
+
+def build_registry(world: MailWorld) -> ToolRegistry:
+    """Register the demo tools against ``world``. READ tools taint their output."""
+
+    def read_inbox(_inp: BaseModel) -> BaseModel:
+        if not world.inbox:
+            raise ValueError("inbox is empty: no latest email to read")
+        return ReadInboxOut(latest=world.inbox[-1])
+
+    def read_contacts(_inp: BaseModel) -> BaseModel:
+        return ReadContactsOut(contacts=list(world.contacts))
+
+    def send_email(inp: BaseModel) -> BaseModel:
+        if not isinstance(inp, SendEmailIn):
+            raise TypeError(f"send_email expected SendEmailIn, got {type(inp).__name__}")
+        world.sent.append(inp)
+        return SendEmailOut(ok=True, message_id=f"msg-{len(world.sent)}")
+
+    def create_event(inp: BaseModel) -> BaseModel:
+        if not isinstance(inp, CreateEventIn):
+            raise TypeError(f"create_event expected CreateEventIn, got {type(inp).__name__}")
+        world.events.append(inp)
+        return CreateEventOut(ok=True, event_id=f"evt-{len(world.events)}")
+
+    registry = ToolRegistry()
+    registry.register(
+        ToolSpec(
+            name="read_inbox",
+            input_schema=ReadInboxIn,
+            output_schema=ReadInboxOut,
+            required_caps=frozenset({CAP_MAIL_READ}),
+            effect_level=EffectLevel.READ,
+            result_readers=frozenset(),  # untrusted content: may flow into no WRITE
+            result_subjects=frozenset({DataSubject.USER}),  # the user's own mailbox
+        ),
+        read_inbox,
+    )
+    registry.register(
+        ToolSpec(
+            name="read_contacts",
+            input_schema=ReadContactsIn,
+            output_schema=ReadContactsOut,
+            required_caps=frozenset({CAP_CONTACTS_READ}),
+            effect_level=EffectLevel.READ,
+            result_readers=frozenset(),
+            result_subjects=frozenset({DataSubject.THIRD_PARTY}),  # other people's data
+        ),
+        read_contacts,
+    )
+    registry.register(
+        ToolSpec(
+            name="send_email",
+            input_schema=SendEmailIn,
+            output_schema=SendEmailOut,
+            required_caps=frozenset({CAP_MAIL_SEND}),
+            effect_level=EffectLevel.WRITE,
+        ),
+        send_email,
+    )
+    registry.register(
+        ToolSpec(
+            name="create_event",
+            input_schema=CreateEventIn,
+            output_schema=CreateEventOut,
+            required_caps=frozenset({CAP_CALENDAR_WRITE}),
+            effect_level=EffectLevel.WRITE,
+        ),
+        create_event,
+    )
+    return registry
+
+
+Q_SCHEMAS: dict[str, type[BaseModel]] = {"EmailSummary": EmailSummary}
+
+
+class RecipientIsUserPolicy:
+    """Declassify a tainted WRITE only when the recipient is the trusted requesting user.
+
+    Note (limit): this permits self-directed sends of any tainted body — including third-party data
+    mailed to oneself. It blocks exfiltration to third parties, which is the demo's threat model; it
+    is a property of this policy, not of the pattern. A stricter policy would scope by data subject.
+    """
+
+    def may_declassify(
+        self,
+        tool: ToolSpec,
+        named_args: dict[str, TaintedValue],
+        ctx: RunContext,
+    ) -> VerifierVerdict:
+        # create_event: a calendar entry derived from the user's own data is fine; third-party not.
+        if tool.name == "create_event":
+            if any(v.label.has_third_party for v in named_args.values()):
+                return VerifierVerdict(
+                    allowed=False, reason="third-party data may not be written to the calendar"
+                )
+            return VerifierVerdict(allowed=True, reason="event derived from the user's own data")
+        if tool.name != "send_email":
+            return VerifierVerdict(allowed=False, reason="no declassification rule for this tool")
+        # Third-party data must not be transmitted at all — not even to the requesting user.
+        body = named_args.get("body")
+        if body is not None and body.label.has_third_party:
+            return VerifierVerdict(
+                allowed=False,
+                reason="third-party data may not be transmitted, even to the requesting user",
+            )
+        recipient = named_args.get("to")
+        if recipient is None:
+            return VerifierVerdict(allowed=False, reason="missing recipient")
+        # Compare against the trusted user only; the recipient itself must be untainted.
+        if (
+            not recipient.label.is_tainted
+            and isinstance(recipient.value, str)
+            and recipient.value == ctx.user
+        ):
+            return VerifierVerdict(allowed=True, reason="recipient is the trusted requesting user")
+        return VerifierVerdict(
+            allowed=False,
+            reason="recipient is not the trusted user — tainted data may not leave",
+        )

reasoning_kernel/tools/registry.py

@@ -0,0 +1,44 @@
+"""The tool registry — where the effect callables live, and nowhere else.
+
+A ``RegisteredTool`` binds a declared ``ToolSpec`` to its callable. The registry is the only
+holder of callables; it hands them solely to the ``EffectDispatcher``. The interpreter never
+receives the registry, so it has no reference path to a callable — half of the by-construction
+no-bypass guarantee (the other half is the dispatcher requiring a Gate).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from reasoning_kernel.schemas.registry import ToolSpec
+
+ToolCallable = Callable[[BaseModel], BaseModel]
+
+
+@dataclass(frozen=True)
+class RegisteredTool:
+    spec: ToolSpec
+    callable: ToolCallable
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, RegisteredTool] = {}
+
+    def register(self, spec: ToolSpec, fn: ToolCallable) -> None:
+        if spec.name in self._tools:
+            raise ValueError(f"tool already registered: {spec.name!r}")
+        self._tools[spec.name] = RegisteredTool(spec=spec, callable=fn)
+
+    def get(self, name: str) -> RegisteredTool:
+        try:
+            return self._tools[name]
+        except KeyError:
+            raise KeyError(f"unknown tool: {name!r}") from None
+
+    def catalog(self) -> list[ToolSpec]:
+        """Specs only — names, schemas, effect levels. Safe to show the planner."""
+        return [t.spec for t in self._tools.values()]