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

reasoning_kernel/kernel/effects.py

@@ -0,0 +1,90 @@
+"""The effect dispatcher — the one and only place a real tool callable is invoked.
+
+This is where the no-bypass guarantee becomes structural rather than conventional:
+- it is the sole holder of the registry's callables;
+- it CANNOT be constructed without a ``Gate`` (the gate is a required constructor argument);
+- ``dispatch`` calls ``gate.check`` unconditionally and raises ``EffectBlocked`` *before* the
+  callable is ever reached.
+
+So "no effect bypasses the Verifier" reduces to "the only effect site always checks first" —
+which is true by construction, and witnessed in every trace.
+"""
+
+from __future__ import annotations
+
+from reasoning_kernel.kernel.gate import Gate
+from reasoning_kernel.kernel.taint import result_label
+from reasoning_kernel.memory.trace import TraceWriter
+from reasoning_kernel.schemas.capability import CapabilitySet
+from reasoning_kernel.schemas.ids import StepId
+from reasoning_kernel.schemas.policy import RunContext, VerifierVerdict
+from reasoning_kernel.schemas.registry import ToolSpec
+from reasoning_kernel.schemas.trace import EffectBlockedEvent, EffectCommitted, GateDecision, digest
+from reasoning_kernel.schemas.values import TaintedValue
+from reasoning_kernel.tools.registry import ToolRegistry
+
+
+class EffectBlocked(Exception):
+    """Raised when the Verifier denies a call. Carries the verdict; the callable did not run."""
+
+    def __init__(self, verdict: VerifierVerdict) -> None:
+        super().__init__(verdict.reason)
+        self.verdict = verdict
+
+
+class EffectDispatcher:
+    def __init__(
+        self,
+        registry: ToolRegistry,
+        gate: Gate,
+        trace: TraceWriter,
+        ctx: RunContext,
+    ) -> None:
+        self._registry = registry
+        self._gate = gate
+        self._trace = trace
+        self._ctx = ctx
+
+    def catalog(self) -> list[ToolSpec]:
+        return self._registry.catalog()
+
+    def grant(self) -> CapabilitySet:
+        """The capability grant the Gate enforces (the run's authority ceiling)."""
+        return self._gate.grant
+
+    def for_subkernel(self, grant: CapabilitySet, ctx: RunContext) -> EffectDispatcher:
+        """A dispatcher over the SAME registry and shared trace, at a reduced grant (a sub-kernel).
+
+        Same registry means the inner kernel cannot reach a callable the outer one couldn't; the
+        clamped Gate means it can authorize strictly less. Every effect still routes through a Gate.
+        """
+        return EffectDispatcher(self._registry, self._gate.for_grant(grant), self._trace, ctx)
+
+    def dispatch(self, tool_name: str, named_args: dict[str, TaintedValue]) -> TaintedValue:
+        rtool = self._registry.get(tool_name)
+        spec = rtool.spec
+        arg_labels = [v.label for v in named_args.values()]
+
+        verdict = self._gate.check(spec, named_args, self._ctx)
+        self._trace.emit(
+            GateDecision(
+                run_id=self._ctx.run_id, tool=spec.name, verdict=verdict, arg_labels=arg_labels
+            )
+        )
+        if not verdict.allowed:
+            self._trace.emit(
+                EffectBlockedEvent(run_id=self._ctx.run_id, tool=spec.name, verdict=verdict)
+            )
+            raise EffectBlocked(verdict)
+
+        # Past the gate: build the validated input model and invoke the real callable.
+        model_in = spec.input_schema(**{k: v.value for k, v in named_args.items()})
+        out = rtool.callable(model_in)
+        self._trace.emit(
+            EffectCommitted(run_id=self._ctx.run_id, tool=spec.name, output_digest=digest(out))
+        )
+        return TaintedValue(
+            value=out,
+            label=result_label(spec, arg_labels),
+            produced_by=StepId(f"__effect__{spec.name}"),
+        )

reasoning_kernel/kernel/gate.py

@@ -0,0 +1,88 @@
+"""The Verifier — the single logical Invariant-B boundary.
+
+Every consequential call is checked here, deterministically, in three stages:
+  1. capability — the grant must contain every capability the tool requires;
+  2. schema     — the arguments must validate against the tool's input schema;
+  3. provenance — for a WRITE, no tainted argument may flow into a required capability unless
+     the (deterministic) declassification policy explicitly allows it.
+
+There is no LLM on this path: verification never depends on trusting a probabilistic component
+(the paper's §6.2 distinction between a real, deterministic boundary and a probabilistic one).
+"""
+
+from __future__ import annotations
+
+from pydantic import ValidationError
+
+from reasoning_kernel.schemas.capability import CapabilitySet, EffectLevel
+from reasoning_kernel.schemas.policy import DeclassPolicy, RunContext, VerifierVerdict
+from reasoning_kernel.schemas.registry import ToolSpec
+from reasoning_kernel.schemas.values import TaintedValue
+
+
+class Gate:
+    def __init__(self, grant: CapabilitySet, declass: DeclassPolicy) -> None:
+        self._grant = grant
+        self._declass = declass
+
+    @property
+    def grant(self) -> CapabilitySet:
+        return self._grant
+
+    def for_grant(self, grant: CapabilitySet) -> Gate:
+        """A Gate with the same declassification policy at a reduced grant (for sub-kernels)."""
+        return Gate(grant, self._declass)
+
+    def check(
+        self,
+        spec: ToolSpec,
+        named_args: dict[str, TaintedValue],
+        ctx: RunContext,
+    ) -> VerifierVerdict:
+        # 1. capability
+        missing = sorted(c.name for c in spec.required_caps if not self._grant.allows(c))
+        if missing:
+            return VerifierVerdict(
+                allowed=False,
+                reason=f"missing capabilities for {spec.name}",
+                issues=[f"not granted: {m}" for m in missing],
+            )
+
+        # 2. schema
+        try:
+            spec.input_schema(**{k: v.value for k, v in named_args.items()})
+        except ValidationError as exc:
+            return VerifierVerdict(
+                allowed=False,
+                reason=f"arguments do not satisfy {spec.input_schema.__name__}",
+                issues=[str(exc)],
+            )
+
+        # 3. provenance (only matters for WRITE effects)
+        if spec.effect_level >= EffectLevel.WRITE:
+            tainted = [v for v in named_args.values() if v.label.is_tainted]
+            has_third_party = any(v.label.has_third_party for v in named_args.values())
+            if tainted or has_third_party:
+                # Permitted without declassification ONLY if the tool declares capabilities, every
+                # tainted arg may flow into all of them, AND no argument carries third-party data.
+                # Two reasons it is otherwise routed to declassification:
+                #  - an empty required_caps set is not a free pass (capless WRITE would exfiltrate);
+                #  - third-party data must never be auto-permitted out, regardless of readers.
+                permitted = (
+                    not has_third_party
+                    and bool(spec.required_caps)
+                    and all(
+                        v.label.allows_reader(cap) for cap in spec.required_caps for v in tainted
+                    )
+                )
+                if not permitted:
+                    verdict = self._declass.may_declassify(spec, named_args, ctx)
+                    if not verdict.allowed:
+                        return VerifierVerdict(
+                            allowed=False,
+                            reason=f"untrusted-derived data may not flow into {spec.name}",
+                            issues=verdict.issues or [verdict.reason],
+                        )
+                    return verdict
+
+        return VerifierVerdict(allowed=True, reason=f"{spec.name} permitted")

reasoning_kernel/kernel/interpreter.py

@@ -0,0 +1,238 @@
+"""The Conductor — the execution loop. Governs flow; does not reason.
+
+It assembles the planner context (Invariant A), obtains a typed ``Plan``, and walks the steps.
+``ToolCallStep`` is the only step kind that can reach reality, and it reaches it *only* through
+the ``EffectDispatcher`` (which always checks the Gate first). The Conductor never holds a tool
+callable and never calls a model except via the two reasoner roles. It is responsible for
+termination (``RunLimits``) and fails closed on any plan it cannot safely execute.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures as futures
+from collections.abc import Callable
+
+from pydantic import BaseModel, ValidationError
+
+from reasoning_kernel.context.assembler import build_planner_context, build_quarantine_context
+from reasoning_kernel.kernel.effects import EffectBlocked, EffectDispatcher
+from reasoning_kernel.kernel.taint import join_labels, quarantine_label
+from reasoning_kernel.memory.store import ValueStore
+from reasoning_kernel.memory.trace import TraceWriter
+from reasoning_kernel.reasoner.base import ReasonerError
+from reasoning_kernel.reasoner.roles import PLLM, QLLM
+from reasoning_kernel.schemas.capability import Capability, CapabilitySet
+from reasoning_kernel.schemas.ids import RunId
+from reasoning_kernel.schemas.limits import RunLimits
+from reasoning_kernel.schemas.plan import (
+    ConstStep,
+    MergeStep,
+    PlanStep,
+    QuarantineParseStep,
+    SubKernelStep,
+    ToolCallStep,
+)
+from reasoning_kernel.schemas.policy import RunContext, TrustedQuery
+from reasoning_kernel.schemas.trace import (
+    PlanEmitted,
+    PlanRejected,
+    QParseResult,
+    RunAborted,
+    RunBlocked,
+    RunCommitted,
+    RunErrored,
+    RunResult,
+    StepStarted,
+    digest,
+)
+from reasoning_kernel.schemas.values import TaintedValue
+
+# Errors that mean "the model produced a plan the kernel cannot safely execute", or a reasoner
+# failed to return usable output. They are failed closed (recorded, no effect committed), not
+# crashes. Unexpected errors still propagate.
+_PLAN_ERRORS = (ValidationError, ValueError, KeyError, ReasonerError)
+
+
+class _RunAborted(Exception):
+    """A run bound (RunLimits) was exceeded. Fails closed, like EffectBlocked."""
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+class Interpreter:
+    def __init__(
+        self,
+        *,
+        planner: PLLM,
+        quarantine: QLLM,
+        dispatcher: EffectDispatcher,
+        trace: TraceWriter,
+        q_schemas: dict[str, type[BaseModel]],
+        limits: RunLimits = RunLimits(),
+        depth: int = 0,
+    ) -> None:
+        # A reasoner may never plan beyond the kernel's authority (the §5.4 composition invariant).
+        if not planner.grant.is_subset_of(dispatcher.grant()):
+            raise ValueError("planner grant exceeds the dispatcher's capability grant")
+        self._planner = planner
+        self._quarantine = quarantine
+        self._dispatcher = dispatcher
+        self._trace = trace
+        self._q_schemas = q_schemas
+        self._limits = limits
+        self._depth = depth
+        self._store = ValueStore()  # replaced per run() with the query's label
+        self._effects = 0
+        self._q_parses = 0
+
+    def run(self, ctx: RunContext) -> RunResult:
+        # Per-run state — the store is labelled with the run's (trusted) query.
+        self._store = ValueStore(ctx.query.label)
+        self._effects = 0
+        self._q_parses = 0
+        prompt = build_planner_context(ctx.query.text, self._dispatcher.catalog(), self._q_schemas)
+
+        try:
+            plan = self._call_reasoner(lambda: self._planner.plan(prompt, run_id=ctx.run_id))
+        except _PLAN_ERRORS as exc:
+            self._trace.emit(PlanRejected(run_id=ctx.run_id, reason=str(exc)))
+            return self._closed()
+        except _RunAborted as ab:
+            self._trace.emit(RunAborted(run_id=ctx.run_id, reason=ab.reason))
+            return self._closed()
+        self._trace.emit(PlanEmitted(run_id=ctx.run_id, plan=plan))
+
+        if self._limits.max_steps is not None and len(plan.steps) > self._limits.max_steps:
+            self._trace.emit(
+                RunAborted(
+                    run_id=ctx.run_id,
+                    reason=f"plan has {len(plan.steps)} steps > max_steps {self._limits.max_steps}",
+                )
+            )
+            return self._closed()
+
+        for step in plan.steps:
+            self._trace.emit(StepStarted(run_id=ctx.run_id, step=step))
+            try:
+                value = self._eval_step(step, ctx)
+            except EffectBlocked:
+                self._trace.emit(RunBlocked(run_id=ctx.run_id, tool=_tool_name(step)))
+                return self._closed()
+            except _RunAborted as ab:
+                self._trace.emit(RunAborted(run_id=ctx.run_id, step_id=step.id, reason=ab.reason))
+                return self._closed()
+            except _PLAN_ERRORS as exc:
+                self._trace.emit(RunErrored(run_id=ctx.run_id, step_id=step.id, reason=str(exc)))
+                return self._closed()
+            self._store.put(step.id, value)
+
+        final = self._store.get(plan.final)
+        self._trace.emit(RunCommitted(run_id=ctx.run_id, final_digest=digest(final.value)))
+        return RunResult(trace=self._trace.snapshot(), committed=final)
+
+    def _closed(self) -> RunResult:
+        """A fail-closed outcome: the trace so far, with nothing committed."""
+        return RunResult(trace=self._trace.snapshot(), committed=None)
+
+    def _eval_step(self, step: PlanStep, ctx: RunContext) -> TaintedValue:
+        if isinstance(step, ConstStep):
+            # A planner literal inherits the (trusted) query's label — not hardcoded trust.
+            return TaintedValue(value=step.value, label=ctx.query.label, produced_by=step.id)
+        if isinstance(step, QuarantineParseStep):
+            self._q_parses += 1
+            if self._limits.max_q_parses is not None and self._q_parses > self._limits.max_q_parses:
+                raise _RunAborted(f"q_parse count exceeds max_q_parses {self._limits.max_q_parses}")
+            src = self._store.resolve(step.source)
+            if step.schema_ref not in self._q_schemas:
+                raise ValueError(
+                    f"unknown q_parse schema_ref {step.schema_ref!r} "
+                    f"(available: {', '.join(self._q_schemas)})"
+                )
+            schema = self._q_schemas[step.schema_ref]
+            q_prompt = build_quarantine_context(str(src.value), step.instruction)
+            parsed = self._call_reasoner(
+                lambda: self._quarantine.parse_blob(prompt=q_prompt, schema=schema)
+            )
+            label = quarantine_label(src.label)
+            self._trace.emit(QParseResult(run_id=ctx.run_id, step_id=step.id, label=label))
+            return TaintedValue(value=parsed, label=label, produced_by=step.id)
+        if isinstance(step, ToolCallStep):
+            self._effects += 1
+            if self._limits.max_effects is not None and self._effects > self._limits.max_effects:
+                raise _RunAborted(f"effect count exceeds max_effects {self._limits.max_effects}")
+            named = {k: self._store.resolve(a) for k, a in step.args.items()}
+            return self._dispatcher.dispatch(step.tool, named)
+        if isinstance(step, MergeStep):
+            return self._eval_merge(step, ctx)
+        # Only SubKernelStep remains. This is exhaustive over PlanStep: the param type makes pyright
+        # error here if a new step kind is added to the union but not handled above.
+        return self._eval_subkernel(step, ctx)
+
+    def _eval_merge(self, step: MergeStep, ctx: RunContext) -> TaintedValue:
+        # Combine the named inputs into one dict, labelled with the join of their labels: taint only
+        # ever increases (sources union + DERIVED, readers intersected, subjects union). The
+        # object-level over-approximation is sound — strictly safer than per-field labels.
+        resolved = {k: self._store.resolve(ref) for k, ref in step.inputs.items()}
+        merged: dict[str, object] = {k: tv.value for k, tv in resolved.items()}
+        label = join_labels([tv.label for tv in resolved.values()])
+        return TaintedValue(value=merged, label=label, produced_by=step.id)
+
+    def _eval_subkernel(self, step: SubKernelStep, ctx: RunContext) -> TaintedValue:
+        if self._limits.max_depth is not None and self._depth + 1 > self._limits.max_depth:
+            raise _RunAborted(f"sub-kernel depth exceeds max_depth {self._limits.max_depth}")
+        src = self._store.resolve(step.source)
+
+        # Clamp the requested grant to the outer authority — a sub-kernel can never widen it.
+        requested = frozenset(Capability(name=n) for n in step.grant)
+        inner_grant = CapabilitySet(granted=requested & self._dispatcher.grant().granted)
+
+        # The sub-planner's query is the (trusted) instruction plus the UNTRUSTED blob, labelled by
+        # the blob's label, so every literal it produces inherits that taint (Invariant A).
+        sub_text = f"{step.instruction}\n\n--- untrusted content ---\n{src.value}"
+        sub_ctx = RunContext(
+            run_id=RunId(f"{ctx.run_id}/{step.id}"),
+            user=ctx.user,
+            query=TrustedQuery(text=sub_text, label=src.label),
+        )
+        sub = Interpreter(
+            planner=self._planner.for_grant(inner_grant),
+            quarantine=self._quarantine,
+            dispatcher=self._dispatcher.for_subkernel(inner_grant, sub_ctx),
+            trace=self._trace,  # shared: sub events interleave under the suffixed run_id
+            q_schemas=self._q_schemas,
+            limits=self._limits,
+            depth=self._depth + 1,
+        )
+        result = sub.run(sub_ctx)
+        if result.committed is None:
+            # The sub-kernel committed nothing (blocked/aborted/errored): the task failed closed.
+            raise ValueError(f"sub-kernel {step.id} did not commit")
+        # The outer value must dominate everything the sub touched: join source + sub-final labels.
+        label = join_labels([quarantine_label(src.label), result.committed.label])
+        return TaintedValue(value=result.committed.value, label=label, produced_by=step.id)
+
+    def _call_reasoner[T](self, thunk: Callable[[], T]) -> T:
+        """Invoke a reasoner, enforcing the optional per-call timeout (deterministic when unset).
+
+        On timeout the run aborts *immediately*: we must not use the executor as a context manager,
+        because its ``__exit__`` calls ``shutdown(wait=True)`` and would block on the very call we
+        timed out. We shut down without waiting; Python cannot kill the orphan thread, so the bound
+        is on the run, not on the underlying call (which still relies on the provider's timeout).
+        """
+        timeout = self._limits.reasoner_timeout_s
+        if timeout is None:
+            return thunk()
+        pool = futures.ThreadPoolExecutor(max_workers=1)
+        future = pool.submit(thunk)
+        try:
+            return future.result(timeout=timeout)
+        except futures.TimeoutError:
+            raise _RunAborted(f"reasoner call exceeded {timeout}s") from None
+        finally:
+            pool.shutdown(wait=False, cancel_futures=True)
+
+
+def _tool_name(step: PlanStep) -> str:
+    return step.tool if isinstance(step, ToolCallStep) else "<none>"

reasoning_kernel/kernel/taint.py

@@ -0,0 +1,68 @@
+"""Provenance propagation — how taint flows and narrows through the interpreter.
+
+Rules (paper section 6.1):
+- join: ``sources = union(sources_i)`` (add ``DERIVED`` when combining >1 input);
+  ``readers = intersection(readers_i)`` with ``None`` (unrestricted) as the identity element.
+- a READ tool's output is freshly untrusted: add ``TOOL_READ`` and narrow ``readers`` to the
+  tool's declared ``result_readers``.
+- a Q-LLM parse cannot launder taint: it keeps the source blob's label and adds ``Q_LLM``.
+
+Restrictiveness only ever increases as untrusted data flows.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from reasoning_kernel.schemas.capability import Capability, EffectLevel
+from reasoning_kernel.schemas.provenance import DataSubject, ProvenanceLabel, Source
+from reasoning_kernel.schemas.registry import ToolSpec
+
+
+def join_labels(labels: Sequence[ProvenanceLabel]) -> ProvenanceLabel:
+    if not labels:
+        return ProvenanceLabel.trusted()
+    sources: set[Source] = set()
+    subjects: set[DataSubject] = set()
+    for label in labels:
+        sources |= label.sources
+        subjects |= label.subjects
+    if len(labels) > 1:
+        sources.add(Source.DERIVED)
+
+    readers: frozenset[Capability] | None = None
+    for label in labels:
+        if label.readers is None:
+            continue
+        readers = label.readers if readers is None else (readers & label.readers)
+    return ProvenanceLabel(
+        sources=frozenset(sources), readers=readers, subjects=frozenset(subjects)
+    )
+
+
+def result_label(spec: ToolSpec, arg_labels: Sequence[ProvenanceLabel]) -> ProvenanceLabel:
+    """Provenance of a tool's output, given its argument labels."""
+    base = join_labels(arg_labels)
+    sources = set(base.sources)
+    readers = base.readers
+    subjects = base.subjects | spec.result_subjects  # subjects only ever accumulate
+    if spec.effect_level == EffectLevel.READ:
+        sources.add(Source.TOOL_READ)
+        rr = spec.result_readers
+        readers = rr if readers is None else (readers & rr)
+    return ProvenanceLabel(
+        sources=frozenset(sources), readers=readers, subjects=frozenset(subjects)
+    )
+
+
+def quarantine_label(source_label: ProvenanceLabel) -> ProvenanceLabel:
+    """The label of a Q-LLM parse result: source taint and subjects preserved, ``Q_LLM`` added.
+
+    The Q-LLM cannot launder ``subjects`` any more than it can launder ``sources``: a summary of
+    third-party data is still third-party data.
+    """
+    return ProvenanceLabel(
+        sources=frozenset(source_label.sources | {Source.Q_LLM}),
+        readers=source_label.readers,
+        subjects=source_label.subjects,
+    )

reasoning_kernel/memory/store.py

@@ -0,0 +1,70 @@
+"""The value store — the interpreter's only place to keep step results.
+
+Holds ``StepId -> TaintedValue``, and resolves a plan ``ArgValue`` (a reference or an inline
+literal) into a ``TaintedValue``. Inline literals are labelled trusted: they come from the plan,
+which the planner produced having seen only the controlled query (Invariant A).
+
+Limit: taint is object-level. Navigating a ``path`` keeps the whole value's label. The
+value-combining step (``MergeStep``) labels its result with the *join* of its inputs, so a
+composite of differing provenances carries one label that over-approximates them all — safer than
+per-field labels. Field-level labels (recovering a trusted field from a mixed structure without
+over-tainting it) stay deferred: they buy precision, not soundness, until a use case needs them.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from pydantic import BaseModel
+
+from reasoning_kernel.schemas.ids import StepId
+from reasoning_kernel.schemas.plan import ArgRef, ArgValue
+from reasoning_kernel.schemas.provenance import ProvenanceLabel
+from reasoning_kernel.schemas.values import TaintedValue
+
+
+class ValueStore:
+    def __init__(self, query_label: ProvenanceLabel | None = None) -> None:
+        self._values: dict[StepId, TaintedValue] = {}
+        # Inline literals derive their label from the run's (trusted) query — see resolve().
+        self._query_label = query_label if query_label is not None else ProvenanceLabel.trusted()
+
+    def put(self, step_id: StepId, value: TaintedValue) -> None:
+        if step_id in self._values:
+            raise ValueError(f"step result already stored: {step_id!r}")
+        self._values[step_id] = value
+
+    def get(self, step_id: StepId) -> TaintedValue:
+        return self._values[step_id]
+
+    def resolve(self, arg: ArgValue) -> TaintedValue:
+        if isinstance(arg, ArgRef):
+            tv = self._values[arg.ref]
+            if arg.path is None:
+                return tv
+            return TaintedValue(
+                value=_navigate(tv.value, arg.path), label=tv.label, produced_by=tv.produced_by
+            )
+        # Inline literal: derives from the run's query label (trusted unless the query is not).
+        return TaintedValue(value=arg, label=self._query_label, produced_by=StepId("__literal__"))
+
+
+def _navigate(value: object, path: str) -> object:
+    cur: object = value
+    for part in path.split("."):
+        if isinstance(cur, BaseModel):
+            if part not in type(cur).model_fields:
+                raise ValueError(
+                    f"path {path!r}: {type(cur).__name__} has no field {part!r} "
+                    f"(available: {', '.join(type(cur).model_fields)})"
+                )
+            cur = getattr(cur, part)
+        elif isinstance(cur, dict):
+            # The kernel treats payloads as opaque: dict values are navigated as plain ``object``.
+            cur_dict = cast("dict[str, object]", cur)
+            if part not in cur_dict:
+                raise ValueError(f"path {path!r}: key {part!r} not in dict")
+            cur = cur_dict[part]
+        else:
+            raise ValueError(f"path {path!r}: {type(cur).__name__} has no {part!r}")
+    return cur

reasoning_kernel/memory/trace.py

@@ -0,0 +1,23 @@
+"""The trace writer — an append-only sink for the auditable record.
+
+Exposes only ``emit`` (append, assigning a monotonic ``seq``) and ``snapshot`` (read). There is
+no mutate or delete: the record can grow and be read, never rewritten.
+"""
+
+from __future__ import annotations
+
+from reasoning_kernel.schemas.ids import RunId
+from reasoning_kernel.schemas.trace import RunTrace, TraceEvent
+
+
+class TraceWriter:
+    def __init__(self, run_id: RunId) -> None:
+        self.run_id = run_id
+        self._events: list[TraceEvent] = []
+
+    def emit(self, event: TraceEvent) -> None:
+        event.seq = len(self._events)
+        self._events.append(event)
+
+    def snapshot(self) -> RunTrace:
+        return RunTrace(run_id=self.run_id, events=list(self._events))

reasoning_kernel/reasoner/anthropic.py

@@ -0,0 +1,78 @@
+"""Anthropic-backed provider (structured outputs + ephemeral prompt cache).
+
+Mirrors limolane's ``infra/llm/anthropic.py``. Imported lazily so the package works without
+the ``anthropic`` SDK installed (the default test suite uses the FakeProvider).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from reasoning_kernel.reasoner.base import LLMResult, LLMUsage, ReasonerError
+
+_BETA = "structured-outputs-2025-11-13"
+
+
+class AnthropicProvider:
+    name = "anthropic"
+    supports_prompt_cache = True
+    supports_structured_output = True
+
+    def __init__(self, client: Any | None = None) -> None:
+        self._client = client  # injection seam for tests
+
+    @property
+    def client(self) -> Any:
+        if self._client is None:
+            import anthropic
+
+            from reasoning_kernel.config import settings
+
+            self._client = anthropic.Anthropic(
+                api_key=settings.anthropic_api_key.get_secret_value() or None,
+                timeout=settings.llm_timeout_seconds,
+                default_headers={"anthropic-beta": _BETA},
+            )
+        return self._client
+
+    def parse[T: BaseModel](
+        self,
+        *,
+        prompt: str,
+        schema: type[T],
+        system: str | None,
+        model: str,
+        max_tokens: int,
+        cache_system: bool = True,
+    ) -> LLMResult[T]:
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "max_tokens": max_tokens,
+            "messages": [{"role": "user", "content": prompt}],
+            "output_format": schema,
+        }
+        if system:
+            block: dict[str, Any] = {"type": "text", "text": system}
+            if cache_system:
+                block["cache_control"] = {"type": "ephemeral"}
+            kwargs["system"] = [block]
+
+        response = self.client.messages.parse(**kwargs)
+        parsed = response.parsed_output
+        if parsed is None:
+            raise ReasonerError(f"Anthropic returned no parsed output for {schema.__name__}")
+        u = response.usage
+        usage = LLMUsage(
+            input_tokens=getattr(u, "input_tokens", 0),
+            output_tokens=getattr(u, "output_tokens", 0),
+            cache_read_tokens=getattr(u, "cache_read_input_tokens", 0),
+        )
+        return LLMResult(
+            data=parsed,
+            usage=usage,
+            model=getattr(response, "model", model),
+            provider=self.name,
+            raw=response,
+        )