jharness-kernel 0.1.0__py3-none-any.whl

jharness/kernel/__init__.py

@@ -0,0 +1,200 @@
+"""Model-neutral immutable execution kernel."""
+
+from jharness.kernel.approval import (
+    ApprovalAllow,
+    ApprovalDecision,
+    ApprovalDeny,
+    ApprovalPolicy,
+    ApprovalRequest,
+    ApprovalSuspend,
+)
+from jharness.kernel.checkpoint import (
+    Checkpoint,
+    ControlFact,
+    ConversationInsertFact,
+    Fact,
+    FailedControl,
+    HistoryRewriteFact,
+    LimitedControl,
+    ModelTurnFact,
+    ModelTurnResult,
+    ResumedFact,
+    StartedFact,
+    SuspendedControl,
+    SuspensionView,
+    ToolBatchFact,
+    ToolOutcomeKind,
+)
+from jharness.kernel.commands import SuspensionSelector
+from jharness.kernel.context import RunContext
+from jharness.kernel.errors import (
+    CommitError,
+    KernelError,
+    ModelError,
+    ModelErrorInfo,
+    ProtocolError,
+    RepositoryError,
+    RevisionConflict,
+    ToolError,
+)
+from jharness.kernel.events import Event, EventKind
+from jharness.kernel.history import HistoryReducer, HistoryRewrite
+from jharness.kernel.invocation import Invocation
+from jharness.kernel.json_values import (
+    JsonScalar,
+    JsonValue,
+    freeze_json_value,
+    thaw_json_value,
+)
+from jharness.kernel.limits import LimitReason, RunLimits
+from jharness.kernel.messages import ArtifactRef, ContentPart, ErrorInfo, Message, TaskRef, ToolCall
+from jharness.kernel.models import (
+    DeltaSink,
+    Model,
+    ModelCapabilities,
+    ModelContentDelta,
+    ModelDelta,
+    ModelOptions,
+    ModelReasoningDelta,
+    ModelRequest,
+    ModelResponse,
+    ModelToolCallDelta,
+    ModelUsage,
+    ModelUsageDelta,
+    ResponseFormat,
+    ToolChoice,
+)
+from jharness.kernel.repository import EphemeralRepository, RunRepository
+from jharness.kernel.runtime import Runtime
+from jharness.kernel.snapshot import RunSnapshot
+from jharness.kernel.state import (
+    ActiveState,
+    Completed,
+    Failed,
+    Limited,
+    Planning,
+    RunMetrics,
+    RunState,
+    Suspended,
+    Suspension,
+    ToolsPending,
+)
+from jharness.kernel.tools import (
+    BatchPolicy,
+    SettledOutcome,
+    SettledResult,
+    ToolAccepted,
+    ToolBatch,
+    ToolBinding,
+    ToolCatalog,
+    ToolCatalogProvider,
+    ToolContext,
+    ToolExecution,
+    ToolFailure,
+    ToolOutcome,
+    ToolResult,
+    ToolRisk,
+    ToolSpec,
+    ToolSuccess,
+    ToolWaiting,
+    WaitingResult,
+    tool_message,
+)
+
+__all__ = [
+    "ActiveState",
+    "ApprovalAllow",
+    "ApprovalDecision",
+    "ApprovalDeny",
+    "ApprovalPolicy",
+    "ApprovalRequest",
+    "ApprovalSuspend",
+    "ArtifactRef",
+    "BatchPolicy",
+    "Checkpoint",
+    "CommitError",
+    "Completed",
+    "ContentPart",
+    "ControlFact",
+    "ConversationInsertFact",
+    "DeltaSink",
+    "EphemeralRepository",
+    "ErrorInfo",
+    "Event",
+    "EventKind",
+    "Fact",
+    "Failed",
+    "FailedControl",
+    "HistoryReducer",
+    "HistoryRewrite",
+    "HistoryRewriteFact",
+    "Invocation",
+    "JsonScalar",
+    "JsonValue",
+    "KernelError",
+    "LimitReason",
+    "Limited",
+    "LimitedControl",
+    "Message",
+    "Model",
+    "ModelCapabilities",
+    "ModelContentDelta",
+    "ModelDelta",
+    "ModelError",
+    "ModelErrorInfo",
+    "ModelOptions",
+    "ModelReasoningDelta",
+    "ModelRequest",
+    "ModelResponse",
+    "ModelToolCallDelta",
+    "ModelTurnFact",
+    "ModelTurnResult",
+    "ModelUsage",
+    "ModelUsageDelta",
+    "Planning",
+    "ProtocolError",
+    "RepositoryError",
+    "ResponseFormat",
+    "ResumedFact",
+    "RevisionConflict",
+    "RunContext",
+    "RunLimits",
+    "RunMetrics",
+    "RunRepository",
+    "RunSnapshot",
+    "RunState",
+    "Runtime",
+    "SettledOutcome",
+    "SettledResult",
+    "StartedFact",
+    "Suspended",
+    "SuspendedControl",
+    "Suspension",
+    "SuspensionSelector",
+    "SuspensionView",
+    "TaskRef",
+    "ToolAccepted",
+    "ToolBatch",
+    "ToolBatchFact",
+    "ToolBinding",
+    "ToolCall",
+    "ToolCatalog",
+    "ToolCatalogProvider",
+    "ToolChoice",
+    "ToolContext",
+    "ToolError",
+    "ToolExecution",
+    "ToolFailure",
+    "ToolOutcome",
+    "ToolOutcomeKind",
+    "ToolResult",
+    "ToolRisk",
+    "ToolSpec",
+    "ToolSuccess",
+    "ToolWaiting",
+    "ToolsPending",
+    "WaitingResult",
+    "freeze_json_value",
+    "thaw_json_value",
+    "tool_message",
+]

jharness/kernel/_digest.py

@@ -0,0 +1,242 @@
+"""Small explicit digest writer for immutable kernel content."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from hashlib import sha256
+from typing import Protocol, cast
+
+from jharness.kernel.messages import ArtifactRef, ContentPart, ErrorInfo, Message, TaskRef, ToolCall
+from jharness.kernel.tools import ToolAccepted, ToolFailure, ToolOutcome, ToolWaiting
+
+
+class _Hash(Protocol):
+    def update(self, data: bytes, /) -> None: ...
+
+    def digest(self) -> bytes: ...
+
+
+class DigestWriter:
+    """Domain-separated, length-prefixed writer with explicit scalar types."""
+
+    __slots__ = ("_hash",)
+
+    def __init__(self, domain: str) -> None:
+        self._hash: _Hash = sha256()
+        self._chunk(b"d", domain.encode())
+
+    def field(self, name: str) -> None:
+        self._chunk(b"k", name.encode())
+
+    def none(self) -> None:
+        self._hash.update(b"n")
+
+    def boolean(self, value: bool) -> None:
+        self._hash.update(b"b1" if value else b"b0")
+
+    def integer(self, value: int) -> None:
+        self._chunk(b"i", str(value).encode())
+
+    def number(self, value: float) -> None:
+        self._chunk(b"f", value.hex().encode())
+
+    def string(self, value: str) -> None:
+        self._chunk(b"s", value.encode())
+
+    def bytes(self, value: bytes) -> None:
+        self._chunk(b"x", value)
+
+    def sequence(self, length: int) -> None:
+        self._chunk(b"q", str(length).encode())
+
+    def mapping(self, length: int) -> None:
+        self._chunk(b"m", str(length).encode())
+
+    def json(self, value: object) -> None:
+        """Write a validated JSON value with stable mapping order and scalar types."""
+
+        if value is None:
+            self.none()
+        elif isinstance(value, bool):
+            self.boolean(value)
+        elif isinstance(value, int):
+            self.integer(value)
+        elif isinstance(value, float):
+            self.number(value)
+        elif isinstance(value, str):
+            self.string(value)
+        elif isinstance(value, Mapping):
+            self._json_mapping(cast(Mapping[object, object], value))
+        elif isinstance(value, Sequence) and not isinstance(value, bytes | bytearray):
+            items = cast(Sequence[object], value)
+            self.sequence(len(items))
+            for item in items:
+                self.json(item)
+        else:
+            raise TypeError(f"unsupported JSON digest value: {type(value).__qualname__}")
+
+    def finish(self) -> bytes:
+        return self._hash.digest()
+
+    def _json_mapping(self, value: Mapping[object, object]) -> None:
+        if any(not isinstance(key, str) for key in value):
+            raise TypeError("JSON digest mapping keys must be strings")
+        items = cast(Mapping[str, object], value)
+        keys = sorted(items)
+        self.mapping(len(keys))
+        for key in keys:
+            self.string(key)
+            self.json(items[key])
+
+    def _chunk(self, tag: bytes, value: bytes) -> None:
+        self._hash.update(tag)
+        self._hash.update(len(value).to_bytes(8, "big"))
+        self._hash.update(value)
+
+
+def empty_history_digest() -> bytes:
+    return DigestWriter("jharness.kernel.history.empty.v0").finish()
+
+
+def append_history_digest(previous: bytes, message: Message) -> bytes:
+    writer = DigestWriter("jharness.kernel.history.append.v0")
+    writer.field("previous")
+    writer.bytes(previous)
+    writer.field("message")
+    write_message(writer, message)
+    return writer.finish()
+
+
+def write_message(writer: DigestWriter, value: Message) -> None:
+    writer.field("role")
+    writer.string(value.role)
+    writer.field("parts")
+    write_parts(writer, value.parts)
+    writer.field("tool_calls")
+    write_tool_calls(writer, value.tool_calls)
+    writer.field("tool_call_id")
+    write_optional_string(writer, value.tool_call_id)
+    writer.field("outcome")
+    if value.outcome is None:
+        writer.none()
+    else:
+        _write_tool_outcome(writer, value.outcome)
+    writer.field("metadata")
+    writer.json(value.metadata)
+
+
+def write_parts(writer: DigestWriter, values: tuple[ContentPart, ...]) -> None:
+    writer.sequence(len(values))
+    for value in values:
+        _write_content_part(writer, value)
+
+
+def _write_content_part(writer: DigestWriter, value: ContentPart) -> None:
+    writer.field("content_part")
+    writer.field("type")
+    writer.string(value.type)
+    writer.field("text")
+    write_optional_string(writer, value.text)
+    writer.field("uri")
+    write_optional_string(writer, value.uri)
+    writer.field("artifact")
+    if value.artifact is None:
+        writer.none()
+    else:
+        _write_artifact(writer, value.artifact)
+    writer.field("media_type")
+    write_optional_string(writer, value.media_type)
+    writer.field("name")
+    write_optional_string(writer, value.name)
+    writer.field("data")
+    writer.json(value.data)
+    writer.field("metadata")
+    writer.json(value.metadata)
+
+
+def _write_artifact(writer: DigestWriter, value: ArtifactRef) -> None:
+    writer.field("artifact_ref")
+    writer.field("ref")
+    writer.string(value.ref)
+    writer.field("media_type")
+    write_optional_string(writer, value.media_type)
+    writer.field("name")
+    write_optional_string(writer, value.name)
+    writer.field("size_bytes")
+    write_optional_integer(writer, value.size_bytes)
+    writer.field("sha256")
+    write_optional_string(writer, value.sha256)
+    writer.field("metadata")
+    writer.json(value.metadata)
+
+
+def write_tool_calls(writer: DigestWriter, values: tuple[ToolCall, ...]) -> None:
+    writer.sequence(len(values))
+    for value in values:
+        _write_tool_call(writer, value)
+
+
+def _write_tool_call(writer: DigestWriter, value: ToolCall) -> None:
+    writer.field("tool_call")
+    writer.field("id")
+    writer.string(value.id)
+    writer.field("name")
+    writer.string(value.name)
+    writer.field("arguments")
+    writer.json(value.arguments)
+
+
+def _write_tool_outcome(writer: DigestWriter, value: ToolOutcome) -> None:
+    writer.field("tool_outcome")
+    writer.field("kind")
+    writer.string(value.kind)
+    writer.field("parts")
+    write_parts(writer, value.parts)
+    writer.field("structured_content")
+    writer.json(value.structured_content)
+    if isinstance(value, ToolFailure):
+        writer.field("error")
+        write_error(writer, value.error)
+    elif isinstance(value, ToolAccepted):
+        writer.field("correlation_id")
+        writer.string(value.correlation_id)
+        writer.field("task")
+        _write_optional_task(writer, value.task)
+    elif isinstance(value, ToolWaiting):
+        writer.field("task")
+        _write_optional_task(writer, value.task)
+
+
+def _write_optional_task(writer: DigestWriter, value: TaskRef | None) -> None:
+    if value is None:
+        writer.none()
+        return
+    writer.field("task_ref")
+    writer.field("id")
+    writer.string(value.id)
+    writer.field("status")
+    writer.string(value.status)
+    writer.field("metadata")
+    writer.json(value.metadata)
+
+
+def write_error(writer: DigestWriter, value: ErrorInfo) -> None:
+    writer.field("error_info")
+    writer.field("code")
+    writer.string(value.code)
+    writer.field("message")
+    writer.string(value.message)
+
+
+def write_optional_string(writer: DigestWriter, value: str | None) -> None:
+    if value is None:
+        writer.none()
+    else:
+        writer.string(value)
+
+
+def write_optional_integer(writer: DigestWriter, value: int | None) -> None:
+    if value is None:
+        writer.none()
+    else:
+        writer.integer(value)

jharness/kernel/_engine/__init__.py

@@ -0,0 +1 @@
+"""Private execution engine."""

jharness/kernel/_engine/change.py

@@ -0,0 +1,117 @@
+"""Closed durable change consumed by the pure reducer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from time import time
+from typing import TYPE_CHECKING, cast
+
+from jharness.kernel._validation import expect_instance, expect_instance_tuple
+from jharness.kernel.checkpoint import (
+    ControlFact,
+    ConversationInsertFact,
+    Fact,
+    FailedControl,
+    LimitedControl,
+    SuspendedControl,
+)
+from jharness.kernel.control import Insert
+from jharness.kernel.limits import LimitReason
+from jharness.kernel.messages import ErrorInfo, Message
+from jharness.kernel.models import ModelUsage
+from jharness.kernel.state import (
+    ActiveState,
+    Failed,
+    Limited,
+    Planning,
+    RunState,
+    Suspended,
+    Suspension,
+)
+
+if TYPE_CHECKING:
+    from jharness.kernel.checkpoint import Checkpoint
+    from jharness.kernel.snapshot import RunSnapshot
+
+
+@dataclass(frozen=True, slots=True)
+class Change:
+    fact: Fact
+    state: RunState
+    append: tuple[Message, ...] = ()
+    replace: tuple[Message, ...] | None = None
+    planning_steps: int = 0
+    tool_calls: int = 0
+    usage: ModelUsage | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(cast(object, self.fact), Fact):
+            raise TypeError("change fact must be a Fact")
+        if not isinstance(cast(object, self.state), RunState):
+            raise TypeError("change state must be a RunState")
+        append = expect_instance_tuple(self.append, Message, "change append")
+        replace = (
+            None
+            if self.replace is None
+            else expect_instance_tuple(self.replace, Message, "change replacement")
+        )
+        if replace is not None and (not replace or append):
+            raise ValueError("change replacement must be non-empty and exclusive with append")
+        object.__setattr__(self, "append", append)
+        object.__setattr__(self, "replace", replace)
+
+
+def failed(code: str, message: str) -> Change:
+    return Change(
+        ControlFact(time(), FailedControl(code)),
+        Failed(ErrorInfo(code, message)),
+    )
+
+
+def limited(reason: LimitReason) -> Change:
+    return Change(ControlFact(time(), LimitedControl(reason)), Limited(reason))
+
+
+def insert(control: Insert) -> Change:
+    return Change(
+        ConversationInsertFact(time(), control.source),
+        Planning(),
+        append=(control.message,),
+    )
+
+
+def suspend(state: ActiveState, suspension: Suspension) -> Change:
+    return Change(
+        ControlFact(
+            time(),
+            SuspendedControl(
+                suspension.reason,
+                suspension.source,
+                suspension.wait_id,
+                tuple(sorted(suspension.metadata)),
+            ),
+        ),
+        Suspended(state, suspension),
+    )
+
+
+def reduce(snapshot: RunSnapshot, change: Change, *, checkpoint_id: str) -> Checkpoint:
+    """Purely apply one trusted change and return the next Checkpoint."""
+
+    from jharness.kernel.checkpoint import Checkpoint
+    from jharness.kernel.snapshot import RunSnapshot
+
+    snapshot = expect_instance(snapshot, RunSnapshot, "snapshot")
+    change = expect_instance(change, Change, "change")
+    metrics = snapshot.metrics.advance(
+        planning_steps=change.planning_steps,
+        tool_calls=change.tool_calls,
+        usage=change.usage,
+    )
+    next_snapshot = snapshot._evolve(  # pyright: ignore[reportPrivateUsage]
+        append=change.append,
+        replace=change.replace,
+        metrics=metrics,
+        state=change.state,
+    )
+    return Checkpoint(checkpoint_id, next_snapshot, change.fact)

jharness/kernel/_engine/commit.py

@@ -0,0 +1,82 @@
+"""Single Checkpoint construction and persistence path."""
+
+from __future__ import annotations
+
+import asyncio
+from uuid import uuid4
+
+from jharness.kernel._engine.change import Change, reduce
+from jharness.kernel._validation import expect_instance
+from jharness.kernel.checkpoint import Checkpoint
+from jharness.kernel.errors import CommitError
+from jharness.kernel.repository import RunRepository
+
+
+class WorkCommitDeadlineReached(Exception):
+    pass
+
+
+class Committer:
+    __slots__ = ("_repository", "_timeout")
+
+    def __init__(self, repository: RunRepository, *, timeout_seconds: float) -> None:
+        self._repository = expect_instance(repository, RunRepository, "repository")
+        if timeout_seconds <= 0:
+            raise ValueError("repository timeout must be > 0")
+        self._timeout = timeout_seconds
+
+    async def persist_start(
+        self,
+        checkpoint: Checkpoint,
+        *,
+        work_timeout_seconds: float | None = None,
+    ) -> Checkpoint:
+        checkpoint = expect_instance(checkpoint, Checkpoint, "start checkpoint")
+        if checkpoint.snapshot.revision != 0:
+            raise ValueError("start checkpoint revision must be 0")
+        return await self._persist(
+            checkpoint,
+            previous=None,
+            work_timeout_seconds=work_timeout_seconds,
+        )
+
+    async def apply(
+        self,
+        previous: Checkpoint,
+        change: Change,
+        *,
+        work_timeout_seconds: float | None = None,
+    ) -> Checkpoint:
+        previous = expect_instance(previous, Checkpoint, "previous checkpoint")
+        checkpoint = reduce(previous.snapshot, change, checkpoint_id=str(uuid4()))
+        return await self._persist(
+            checkpoint,
+            previous=previous,
+            work_timeout_seconds=work_timeout_seconds,
+        )
+
+    async def _persist(
+        self,
+        checkpoint: Checkpoint,
+        *,
+        previous: Checkpoint | None,
+        work_timeout_seconds: float | None = None,
+    ) -> Checkpoint:
+        work_limited = work_timeout_seconds is not None and work_timeout_seconds <= self._timeout
+        timeout = (
+            self._timeout
+            if work_timeout_seconds is None
+            else min(self._timeout, max(0.0, work_timeout_seconds))
+        )
+        if timeout <= 0:
+            raise WorkCommitDeadlineReached
+        try:
+            async with asyncio.timeout(timeout):
+                await self._repository.commit(checkpoint)
+        except TimeoutError as exc:
+            if work_limited:
+                raise WorkCommitDeadlineReached from exc
+            raise CommitError("repository commit timed out", last_checkpoint=previous) from exc
+        except Exception as exc:
+            raise CommitError(str(exc) or exc.__class__.__name__, last_checkpoint=previous) from exc
+        return checkpoint