loom-kernel 2.1.4__tar.gz → 2.2.1__tar.gz

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Unreleased
 
+## ✨ Features
+
+### core
+
+- **core:** `loom.core.model` (module `_loom_type`) is the one module that decides whether
+  a boundary type is a `msgspec.Struct` or a strict `pydantic.BaseModel`.
+  `loom_type(symbol)` resolves an authored symbol by `issubclass`,
+  `msgspec_type(annotation)` wraps a compiler-generated annotation, and both
+  return a `LoomType` (`type`, `schema()`, `decode_json()`, `to_builtins()`).
+  Strictness (`forbid_unknown_fields=True` or `model_config["extra"] ==
+  "forbid"`) is required and checked once, in the factory, for either
+  library, raising `UnsupportedBoundaryType`; a decode or validation failure
+  raises `BoundaryValidationError`. `pydantic` stays optional: the module
+  gates on `sys.modules` and imports it locally, so a process that never
+  declares a pydantic type never loads it.
+- **core:** `LoomType` gains `from_builtins(payload)`, the entry point for a
+  value that already arrived as Python builtins — a cache hit, an MCP tool
+  result — rather than as raw JSON. `CachedRepository`,
+  `CacheGateway.get_value`/`multi_get_values`, `@cache_call`/`@cache_query`
+  and `McpHandle.call(expect=...)` accept a strict `pydantic.BaseModel` next
+  to a `msgspec.Struct`; an annotation mixing both libraries is rejected.
+
+### ai
+
+- **ai:** `output.type_ref` and `deps_type` accept a strict
+  `pydantic.BaseModel` (`model_config["extra"] == "forbid"`) wherever they
+  accept a `msgspec.Struct`. A pydantic output is handed to pydantic-ai as
+  its own `output_type`, so pydantic-ai builds its schema, validates the
+  answer with its own coercion, feeds a rejection back to the model and
+  retries within `policies.retries`, unlike a Struct output, which loom
+  keeps decoding strictly and failing fast on the first rejection. Whichever
+  library produced the answer, the hook payload, `/agents/{name}/run`, the
+  SSE `final` frame and the A2A output artifact all carry it as plain JSON
+  builtins, built from the plan's `LoomType`.
+
+### rest
+
+- **rest:** a strict `pydantic.BaseModel` result, a `list` of them or an
+  envelope holding one now renders directly on a REST route, through
+  `MsgspecJSONResponse`'s `enc_hook`, and documents in OpenAPI
+  (`_safe_pydantic_schema`) through the same `LoomType` the cache and MCP
+  boundaries already use; `LoomRestAdapter`'s Struct projection goes
+  through it too.
+
+## ⚠ Behaviour changes
+
+### core
+
+- **core:** the miss path of a cached `@cache_query`/`@cache_call` read,
+  `McpHandle.call` and `CacheGateway.get_value`/`multi_get_values` now raise
+  `BoundaryValidationError` — a `ValueError` — on a stale or malformed cached
+  payload or MCP result, instead of `msgspec.ValidationError` or
+  `pydantic.ValidationError` directly; an `except ValueError` keeps catching
+  it. A `@cache_query` argument that is a pydantic instance now contributes
+  its builtins rendering to the cache key rather than the instance's own
+  `repr`, a one-time key change.
+
+### ai
+
+- **ai:** `CompiledOutput.decoder` and `StateShape.decoder` are gone,
+  replaced by `loom_type: LoomType` (`LoomType | None` on `StateShape`); a
+  reader of either field must move to `loom_type.type` / `.decode_json()` /
+  `.to_builtins()`. `AgentRuntime.output_type(name) -> LoomType` is added
+  next to `state_shape(name)`. A pydantic `output.type_ref` is now validated
+  by pydantic-ai itself, not by loom, and a rejected answer retries within
+  `policies.retries` instead of failing the run on the first attempt; a
+  `msgspec.Struct` output is unchanged (strict decode, fail fast). The root
+  `title` is dropped from a pydantic output's `CompiledOutput.schema`, to
+  match the untitled document a Struct output always produced. Three
+  residuals, documented rather than closed: `bytes` needs
+  `ser_json_bytes`/`val_json_bytes = "base64"` set on the pydantic model to
+  reach parity with msgspec's default base64 rendering, strictness is still
+  checked on the root type only, for either library, and an artefact that
+  declares both a pydantic `type_ref` output and `output_check` serialises
+  an accepted answer twice per attempt — once for the check's own builtins
+  projection, once for the wire — accepted rather than optimised away.
+
+### rest
+
+- **rest:** a JSON object body that fails `Command` validation now answers
+  `422 boundary_validation` with a `violations` list (`{field, message}`
+  pairs, `field` being the wire name the client sent, the same shape
+  `rule_violations` already uses) instead of a generic `500`; malformed
+  JSON and a non-object body are unchanged. `Command.from_payload` now
+  raises `BoundaryValidationError` — a `ValueError` — instead of
+  `msgspec.ValidationError`. The root `title` is dropped on pydantic
+  OpenAPI schemas for request bodies and responses alike, matching the
+  untitled document a Struct always produced.
+
 ## 🐛 Fixes
 
 ### core
@@ -34,6 +123,21 @@
   The `etl-polars` extra now requires `polars>=1.24`, the release that
   named that join option `nulls_equal`.
 
+### ai
+
+- **ai:** an MCP session that dies after it opened no longer fails every later
+  call until the worker restarts. The worker holds one session per server for
+  its whole life, and that holder kept the dead client from ever being
+  re-entered: after a transport error under an in-flight call, a redeploy of
+  the server or a stdio child that exited, each call through `Mcp()` failed in
+  a millisecond while the health probe answered `ok`. `_ToolsetSession` now
+  treats an exception out of a call's round trip as the transport failing: that
+  call is raised as it is and never repeated, and the next call opens a new
+  session first, once even under concurrency. A renewal that cannot connect
+  raises and is tried again by the following call. An agent's own `mcp`
+  capability does not recover yet; see "A session that died after it opened is
+  replaced by the next call" in `docs/ai/mcp.md`.
+
 ## ♻️ Refactor
 
 ### etl

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.1.4
+Version: 2.2.1
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/docs/ai/artifacts.md

@@ -198,6 +198,15 @@ deps_type: dict                         # open: an explicit waiver of validation
 indistinguishable from one that wrote the schema by hand. Declaring both
 `deps_type` and `deps_schema` is a compilation error.
 
+A strict `pydantic.BaseModel` subclass (`model_config["extra"] == "forbid"`)
+is accepted for `deps_type` exactly as a `msgspec.Struct` is: decoding is
+strict, the state a run renders when no `state` is sent comes from the
+model's own field defaults, and a request `state` with an undeclared field
+fails with `422 INVALID_STATE`, unchanged from the Struct path. State is
+always decoded strictly regardless of library — `"5"` for a declared `int`
+is rejected, never coerced — whereas a pydantic `type_ref` *output* is
+validated with pydantic-ai's own coercion (see "Output" below).
+
 The consequences an author needs, stated rather than left implicit:
 
 * **`deps_type: <symbol>` buys validation at start-up — every templated
@@ -286,6 +295,14 @@ output:
 The reference is `module:Symbol`. Filesystem paths are not representable by the
 pattern.
 
+A strict `pydantic.BaseModel` subclass (`model_config["extra"] == "forbid"`) is
+accepted alongside a strict `msgspec.Struct`. The two are validated
+differently: a pydantic `type_ref` is handed to pydantic-ai itself as the
+run's `output_type`, so pydantic-ai validates the answer with its own
+coercion, feeds a rejection back to the model and retries within
+`policies.retries`; a `msgspec.Struct` `type_ref` is decoded strictly by loom
+and fails fast on the first rejection.
+
 ### `output_check` — demanding the shape of the answer
 
 `output_check` names an `OutputCheck` (`loom.ai.OutputCheck`): a pure,

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/docs/ai/mcp.md

@@ -154,8 +154,10 @@ behind an address; stdio is for the servers you only consume.
 
 What stdio does not do:
 
-- **it does not reconnect.** A dead subprocess fails the call, exactly as a
-  dead HTTP server does; nothing restarts it;
+- **it does not supervise the child.** A dead subprocess fails the call that
+  finds it, exactly as a dead HTTP server does. A call made through `Mcp()`
+  after that one spawns a new child (see "A session that died after it opened
+  is replaced by the next call"); an agent's own capability does not;
 - **it spawns one process per server, for the whole worker.** Start-up spawns
   it and every agent granted that server speaks to that one child. It dies with
   the last holder of the connection — normally the runtime, briefly a straggler
@@ -585,6 +587,43 @@ surfaces only on the first business request that reaches it, as
 `TOOL_UNAVAILABLE`. Extending the probe to a use-case-only server is future
 work, not something this version does.
 
+### A session that died after it opened is replaced by the next call
+
+A server that connected at start-up can still go away later: a transport error
+under an in-flight call, a redeploy of the server, a stdio child that exits.
+The worker's one session is held open for its whole life, and that holder is
+also what stops the underlying client from ever being re-entered — so before
+this was handled, every call through `Mcp()` failed from then on, in a
+millisecond each, until the worker restarted, while the health probe kept
+answering `ok`.
+
+`_ToolsetSession` now replaces the session itself. Nothing can be asked of the
+client: once its transport is gone it still reports itself connected. The
+evidence is the call. A tool's own error comes back as a result flagged
+`is_error`; **an exception out of the round trip is the transport failing**.
+So:
+
+- **the call that found it dead is raised as it is, and never repeated.** It
+  may have run on the server, and a tool with side effects is not run twice on
+  your behalf. Retrying it is your decision;
+- **the next call opens a new session first**, against the same connection —
+  over stdio, that is a new child process. Concurrent calls that find it dead
+  renew it once;
+- **a renewal that cannot connect raises**, and the call after it tries again:
+  an outage costs one connection attempt per call, bounded by the handshake
+  deadline, and ends with the first call made after the server is back;
+- **suspecting a healthy session costs one reconnection.** A single failed call
+  is not proof the session died; opening another is cheap and harmless, so it
+  is not weighed further.
+
+This covers the `Mcp()` path and whatever else calls through the runtime's
+session. **An agent's own `mcp` capability does not recover yet**: the compiled
+agent holds the toolset it was built with, and swapping that needs the engine
+build to go through an indirection it does not have. Two other things are
+unchanged: a server that never connected at start-up under `optional` is still
+not reconnected (above), and the health probe still does not see a
+use-case-only server.
+
 ### A use case's call runs in parallel with other grant views
 
 A use case's tool call goes through `_ToolsetSession`

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/docs/conf.py

@@ -156,6 +156,8 @@ intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
 
+suppress_warnings = ["ref.python"]
+
 # Optional dependencies are mocked to keep docs builds lightweight and stable.
 autodoc_mock_imports = [
     "aiocache",

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/docs/rest/use-case-dsl.md

@@ -513,7 +513,11 @@ UPDATE_NORMALIZE_PRICE = (
 ## Rule — validate before execute
 
 Rules run after all computes. A failing rule raises a structured 422 response
-before `execute()` is called.
+before `execute()` is called. A body that fails to convert into the `Command`
+in the first place — a wrong field type, a missing required field — never
+reaches a rule: it answers its own 422 with `code: "boundary_validation"` and
+a `violations` list shaped the same way (`{field, message}` pairs, `field`
+being the wire name the client sent).
 
 ### Rule.check — field validation
 

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/src/loom/ai/_startup.py

@@ -94,7 +94,7 @@ def _agent_binding_issues(
             # so it is not reported as a mismatch.
             continue
         expected = expected_args[0]
-        declared = agent_plan.output.decoder.type
+        declared = agent_plan.output.loom_type.type
         if expected is declared:
             continue
         yield agent_marker_output_mismatch(

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/src/loom/ai/_transport.py

@@ -22,16 +22,20 @@ from __future__ import annotations
 import asyncio
 from collections.abc import AsyncIterator, Iterator
 from contextlib import contextmanager
-from typing import Final
+from typing import Final, TypeVar
 
+import msgspec
 from starlette.requests import Request
 
-from loom.ai.abc import AgentUsage, ErrorEvent
+from loom.ai.abc import AgentEvent, AgentResult, AgentUsage, ErrorEvent, FinalEvent
 from loom.ai.config import AgentEndpointConfig
 from loom.ai.errors import AgentRunError, AgentRunErrorCode
 from loom.core.identity import Identity, current_identity
+from loom.core.model import LoomType
 from loom.core.observability.span import LoomSpan
 
+_WireResultT = TypeVar("_WireResultT", AgentResult, FinalEvent)
+
 BODY_OVERHEAD_BYTES: Final[int] = 64 * 1024
 """Headroom over the declared field caps for the JSON envelope around them.
 
@@ -259,6 +263,52 @@ def always_closed(span: LoomSpan) -> Iterator[None]:
         span.end()
 
 
+def project_output(value: _WireResultT, output_type: LoomType) -> _WireResultT:
+    """Rewrite ``value.output`` to builtins before it reaches a wire encoder.
+
+    The one place every surface — ``/run``, the SSE ``final`` frame and both
+    A2A paths — projects the run's already-validated answer, so
+    ``result_payload``, ``encode_sse_event``, ``_data_part`` and
+    ``_completed_task`` keep encoding whatever ``output`` already holds
+    (FR-010).
+
+    Args:
+        value: Result or terminal event whose ``output`` is still the
+            engine's validated instance.
+        output_type: The run's compiled boundary type, read from
+            :meth:`~loom.ai.runtime.AgentRuntime.output_type`.
+
+    Returns:
+        *value* with ``output`` replaced by its builtins projection.
+    """
+    return msgspec.structs.replace(value, output=output_type.to_builtins(value.output))
+
+
+async def projecting_final(
+    events: AsyncIterator[AgentEvent], output_type: LoomType
+) -> AsyncIterator[AgentEvent]:
+    """Relay *events*, projecting the terminal ``final`` event's ``output``.
+
+    Every event but ``final`` is yielded unchanged; ``final`` is passed
+    through :func:`project_output` first, so a consumer downstream — the SSE
+    encoder, the A2A projector — never sees the engine's validated instance
+    (FR-010). Both agent surfaces wrap their event stream with this generator
+    before their own projection consumes it.
+
+    Args:
+        events: Run events, terminal event last.
+        output_type: The run's compiled boundary type, read from
+            :meth:`~loom.ai.runtime.AgentRuntime.output_type`.
+
+    Yields:
+        Every event, in order; the ``final`` event's ``output`` projected.
+    """
+    async for event in events:
+        if isinstance(event, FinalEvent):
+            event = project_output(event, output_type)
+        yield event
+
+
 def failure_event(exc: BaseException) -> ErrorEvent:
     """Turn a post-first-byte failure into a stream's terminal error event.
 

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/src/loom/ai/a2a/_handlers.py

@@ -26,6 +26,8 @@ from loom.ai._transport import (
     always_closed,
     annotate_usage,
     failure_event,
+    project_output,
+    projecting_final,
     with_heartbeats,
 )
 from loom.ai.a2a._binding import PublishedAgent
@@ -276,6 +278,7 @@ def _make_send_handler(
             # catalogue detail travel outward.
             _logger.warning("a2a run of agent %r failed: %s", name, exc)
             return error_response(call.request_id, internal_error(exc.code))
+        result = project_output(result, runtime.output_type(name))
         task = _completed_task(uuid4().hex, context_id, result.output)
         return AgentJSONResponse(content=rpc_response(call.request_id, task))
 
@@ -296,7 +299,8 @@ def _run_frames(
             async with runtime.run_stream(
                 call.agent.name, prompt, identity=call.identity, conversation_id=context_id
             ) as events:
-                async for event in events:
+                projected_events = projecting_final(events, runtime.output_type(call.agent.name))
+                async for event in projected_events:
                     for projected in projector.project(event):
                         yield _sse_frame(call.request_id, projected)
         except Exception as exc:

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/src/loom/ai/abc.py

@@ -21,13 +21,11 @@ from contextlib import AbstractAsyncContextManager
 from decimal import Decimal
 from typing import Any, ClassVar, Final, Generic, Literal, Protocol, TypeAlias, TypeVar, overload
 
-import msgspec
-
 from loom.ai.errors import AgentRunErrorCode
 from loom.ai.inference import InferenceTarget
 from loom.core.di import LoomContainer
 from loom.core.identity import Identity
-from loom.core.model import LoomFrozenStruct
+from loom.core.model import LoomFrozenStruct, LoomType
 
 CONVERSATION_ID_MAX_LENGTH: Final[int] = 128
 """Longest ``conversation_id`` a run accepts; the value itself is opaque."""
@@ -51,21 +49,21 @@ class StateShape(LoomFrozenStruct, frozen=True, kw_only=True):
     authored spellings of one optional JSON Schema; the compiler resolves all
     three to this value, never to one of three interchangeable objects. Same
     idiom as its sibling :class:`~loom.ai.compiler._plan.CompiledOutput`,
-    including a ``decoder`` field msgspec cannot itself encode, under the
-    invariant :mod:`loom.ai.compiler._plan` documents.
+    including a :class:`~loom.core.model.LoomType` field msgspec cannot
+    itself encode, under the invariant :mod:`loom.ai.compiler._plan`
+    documents.
 
     Attributes:
         schema: JSON Schema the artifact's state must satisfy, or ``None``
             under the ``deps_type: dict`` waiver, where no schema exists and
             template markers are not validated (FR-006).
-        decoder: Built ``msgspec`` JSON decoder producing the normalised
-            state mapping, or ``None`` alongside ``schema is None``.
+        loom_type: Boundary type produced at compile, decoding and
+            normalising the state mapping, or ``None`` alongside
+            ``schema is None``.
     """
 
     schema: Mapping[str, Any] | None
-    # ``Any`` type parameter: the decoded type is derived from the artifact's
-    # declared state at compile time, so it cannot be named statically.
-    decoder: msgspec.json.Decoder[Any] | None
+    loom_type: LoomType | None
 
 
 class AgentUsage(LoomFrozenStruct, frozen=True, kw_only=True):
@@ -903,11 +901,17 @@ provider SDK is missing.
 OutputCheck: TypeAlias = Callable[[Mapping[str, Any]], str | None]
 """Target of an ``output_check`` reference: a pure predicate over an answer.
 
-Called once per attempt inside the engine's own output-retry loop, with the
-mapping the engine parsed from the model's answer — never loom's decoded
-object, so nothing is decoded twice. Returns ``None`` to accept the answer
-unchanged, or the text the model must read to correct itself, which drives a
-real retry bounded by the artifact's ``policies.retries``.
+Called once per attempt inside the engine's own output-retry loop. For a
+``msgspec.Struct`` output the mapping is the one the engine parsed from the
+model's answer — never loom's decoded object, so nothing is decoded twice.
+For a pydantic output (D7, FR-012) the check still receives a
+``Mapping[str, Any]``: the engine calls it with
+``loom_type.to_builtins(instance)`` of pydantic-ai's own validated instance,
+so a check written once serves both libraries. Returns ``None`` to accept the
+answer unchanged, or the text the model must read to correct itself, which
+drives a real retry bounded by the artifact's ``policies.retries`` — a real
+pydantic-ai output-tool retry for a pydantic output, exactly as for a
+``msgspec.Struct`` one.
 
 The return contract is the inverse of the usual predicate convention, which
 is why this alias is published rather than left for an author to spell: it
@@ -915,11 +919,13 @@ is the one name in this module carrying ``Mapping[str, Any]``, because the
 payload shape is the artifact's own declared schema, which loom cannot type
 statically.
 
-A returned mapping is never substituted for the answer: the engine decodes
-the model's own bytes independently of what this callable returns, so a
-check that builds and returns a different mapping has that mapping
-discarded. Synchronous and dependency-free, because any side effect inside
-the retry loop would run once per attempt.
+A returned mapping is never substituted for the answer: the engine never
+uses this callable's return value to build the answer. A ``msgspec.Struct``
+answer is decoded from the model's own bytes independently; a pydantic
+answer is pydantic-ai's own validated instance, read off ``result.output``.
+Either way, a check that builds and returns a different mapping has that
+mapping discarded. Synchronous and dependency-free, because any side effect
+inside the retry loop would run once per attempt.
 """
 
 

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/src/loom/ai/compiler/_plan.py

@@ -8,8 +8,9 @@ the SQL connection config, the imported toolset factory — never names.
 Secret containment (invariant 4): the plan carries no literal secret.  The
 one secret-bearing struct it embeds, :class:`~loom.ai.inference.InferenceTarget`,
 redacts its references in ``repr`` and refuses msgspec encoding; the built
-decoder in :class:`CompiledOutput` is likewise not msgspec-encodable, so an
-accidental wire encode of a plan raises instead of leaking.
+:class:`~loom.core.model.LoomType` in :class:`CompiledOutput` is likewise not
+msgspec-encodable, so an accidental wire encode of a plan raises instead of
+leaking.
 
 The plan is only ever built in memory by the compiler; it is never decoded
 from JSON, which is why fields may hold arbitrary runtime handles.
@@ -26,27 +27,39 @@ from loom.ai.abc import OutputCheck, StateShape
 from loom.ai.declarative import PolicySpec
 from loom.ai.inference import InferenceTarget
 from loom.core.engine.compilable import Compilable
-from loom.core.model import LoomFrozenStruct
+from loom.core.model import LoomFrozenStruct, LoomType
 from loom.core.sql.config import SqlConnectionConfig
 
 
 class CompiledOutput(LoomFrozenStruct, frozen=True, kw_only=True):
-    """Structured-output contract with a decoder built at compile time.
+    """Structured-output contract with a :class:`~loom.core.model.LoomType` built at compile time.
 
     Interpreting the schema per response would be per-item reflection, so the
-    decoder is constructed exactly once, at compile (research R-004,
-    invariant 5).  The decode is strict: unknown fields are rejected, which is
-    what makes returning the validated bytes unchanged safe.
+    boundary type is constructed exactly once, at compile (research R-004,
+    invariant 5).  For a ``msgspec.Struct`` output the decode is strict —
+    unknown fields are rejected, which is what makes returning the validated
+    bytes unchanged safe. For a pydantic output invariant 5 is satisfied
+    differently (D7, FR-012): ``.type`` is handed to pydantic-ai itself as the
+    run's ``output_type``, so pydantic-ai — not loom — validates, retries and
+    builds the instance; loom never decodes that answer a second time.
 
     Attributes:
         schema: JSON Schema object handed to the model.
-        decoder: Built ``msgspec`` JSON decoder producing the answer type.
+        loom_type: Boundary type produced at compile, whichever library built
+            it (:func:`~loom.core.model.loom_type` for a ``type_ref``,
+            :func:`~loom.core.model.msgspec_type` for a ``json_schema``): the
+            start-up marker check (``ai/_startup.py``) reads ``.type``. The
+            engine reads it differently per library: for a ``msgspec.Struct``,
+            ``ai/engines/pydantic_ai/_output.py`` decodes the model's raw
+            bytes through ``.decode_json(bytes)``; for a pydantic model,
+            ``.type`` reaches ``Agent.from_spec(output_type=...)`` and the
+            engine reads the validated answer straight off
+            ``result.output``. ``.to_builtins`` projects either answer to
+            JSON-mode builtins once, at the wire.
     """
 
     schema: Mapping[str, Any]
-    # ``Any`` type parameter: the decoded type is derived from the artifact's
-    # schema at compile time, so it cannot be named statically.
-    decoder: msgspec.json.Decoder[Any]
+    loom_type: LoomType
 
 
 class CompiledUsecaseCapability(LoomFrozenStruct, frozen=True, kw_only=True):
@@ -378,7 +391,7 @@ class AgentPlan(LoomFrozenStruct, frozen=True, kw_only=True):
             artifact declares neither ``deps_type`` nor ``deps_schema``.
         spec_version: Artifact format version, retained for self-description.
         inference: Resolved model binding; one binding, no fallback (FR-019a).
-        output: Structured-output contract with its built decoder.
+        output: Structured-output contract with its compiled boundary type.
         output_check: Resolved predicate over the answer the engine parsed,
             when the artifact declares ``output_check``; ``None`` otherwise.
         capabilities: Compiled capabilities with resolved handles.

{loom_kernel-2.1.4 → loom_kernel-2.2.1}/src/loom/ai/compiler/phases/_output.py

@@ -1,22 +1,27 @@
-"""Output phase: schema validation, ``type_ref`` resolution, decoder build.
+"""Output phase: schema validation, ``type_ref`` resolution, boundary type build.
 
 A ``json_schema`` output compiles to a concrete type via
-``msgspec.defstruct()`` and the plan stores a **built** decoder, so nothing
+``msgspec.defstruct()`` and the plan stores a :class:`~loom.core.model.LoomType`
+built once over it (:func:`~loom.core.model.msgspec_type`), so nothing
 reflects per invocation (research R-004, invariant 5).  A ``type_ref`` output
-accepts ``msgspec.Struct`` subclasses only in v1, so pydantic never enters the
-compiler path (T053).
+accepts a strict ``msgspec.Struct`` or ``pydantic.BaseModel`` subclass,
+resolved through :func:`~loom.core.model.loom_type`, which checks strictness
+for both libraries and rejects anything else with
+``UnsupportedBoundaryType``: both satisfy invariant 5 with a strict decode,
+so both may own the pass-through of the validated bytes.
 
-:func:`_resolve_symbol` and :func:`_schema_to_decoder` are shared with the
+:func:`_resolve_symbol` and :func:`_schema_to_annotation` are shared with the
 state phase (:mod:`loom.ai.compiler.phases._state`), which compiles the same
 two authored shapes — a symbol reference and a hand-written JSON Schema —
-into a schema-and-decoder pair. Each caller supplies its own issue factory
+into a schema and an annotation. Each caller supplies its own issue factory
 and, for the schema path, its own generated-struct name; nothing about the
 issue codes, the messages, or the exceptions caught changes between the two
 callers. What differs between the two ``type_ref``/``deps_type`` paths stays
-local to each phase: the output side additionally requires the resolved
-symbol to be a ``msgspec.Struct`` declaring ``forbid_unknown_fields=True``
-(invariant 5); the state side derives its schema straight from
-``msgspec.json.schema()`` and admits whatever symbol that call accepts.
+local to each phase: the output side requires every resolved symbol to
+compile through :func:`~loom.core.model.loom_type` (invariant 5); the state
+side only requires that of a resolved symbol that is a class, and falls back
+to ``msgspec.json.schema()`` for a container or alias, so a ``deps_type``
+that never named a class keeps compiling.
 """
 
 from __future__ import annotations
@@ -37,6 +42,7 @@ from loom.ai.errors import (
     output_type_ref_unresolvable,
     output_type_ref_unsupported,
 )
+from loom.core.model import LoomType, UnsupportedBoundaryType, loom_type, msgspec_type
 from loom.core.symbols import import_symbol
 
 _CompileResult = tuple[CompiledOutput | None, list[AgentCompilationIssue]]
@@ -95,36 +101,24 @@ def compile_output_check(
 
 
 def _compile_json_schema(output: JsonSchemaOutput, component: str) -> _CompileResult:
-    compiled, issues = _schema_to_decoder(
+    compiled, issues = _schema_to_annotation(
         output.schema, "CompiledOutputModel", component, output_schema_invalid
     )
     if compiled is None:
         return None, issues
-    schema, decoder = compiled
-    return CompiledOutput(schema=schema, decoder=decoder), []
+    schema, lt = compiled
+    return CompiledOutput(schema=schema, loom_type=lt), []
 
 
 def _compile_type_ref(output: TypeRefOutput, component: str) -> _CompileResult:
     symbol, issues = _resolve_symbol(output.ref, component, output_type_ref_unresolvable)
     if symbol is None:
         return None, issues
-    if not (isinstance(symbol, type) and issubclass(symbol, msgspec.Struct)):
-        return None, [
-            output_type_ref_unsupported(
-                component, output.ref, "only msgspec.Struct subclasses are supported in v1"
-            )
-        ]
-    if not symbol.__struct_config__.forbid_unknown_fields:
-        return None, [
-            output_type_ref_unsupported(
-                component,
-                output.ref,
-                "the struct must declare forbid_unknown_fields=True: pass-through of the "
-                "validated bytes is only safe under a strict decode (invariant 5)",
-            )
-        ]
-    decoder: msgspec.json.Decoder[Any] = msgspec.json.Decoder(symbol)
-    return CompiledOutput(schema=MappingProxyType(msgspec.json.schema(symbol)), decoder=decoder), []
+    try:
+        lt = loom_type(symbol)
+    except UnsupportedBoundaryType as exc:
+        return None, [output_type_ref_unsupported(component, output.ref, str(exc))]
+    return CompiledOutput(schema=MappingProxyType(lt.schema()), loom_type=lt), []
 
 
 def _resolve_symbol(
@@ -140,24 +134,27 @@ def _resolve_symbol(
         return None, [unresolvable_issue(component, ref)]
 
 
-def _schema_to_decoder(
+def _schema_to_annotation(
     schema: Mapping[str, Any], model_name: str, component: str, invalid_issue: _IssueFactory
-) -> tuple[tuple[Mapping[str, Any], msgspec.json.Decoder[Any]] | None, list[AgentCompilationIssue]]:
-    """Compile a hand-written JSON Schema object into a ``(schema, decoder)`` pair.
+) -> tuple[tuple[Mapping[str, Any], LoomType] | None, list[AgentCompilationIssue]]:
+    """Compile a hand-written JSON Schema object into a ``(schema, loom_type)`` pair.
 
     *model_name* names the generated struct type; *invalid_issue* reports a
-    structural fault or a build failure. Shared with the state ``deps_schema``
-    path (:mod:`loom.ai.compiler.phases._state`).
+    structural fault, a failure to map the schema to a runtime annotation, or
+    a failure of :func:`~loom.core.model.msgspec_type` to build a decoder over
+    it — the annotation mapping and the decoder build both run inside the same
+    guard, so either failure is a coded compilation issue and never an
+    unhandled exception.
     """
     fault = _schema_fault(schema)
     if fault is not None:
         return None, [invalid_issue(component, fault)]
     try:
         annotation = _annotation_for(schema, model_name)
-        decoder: msgspec.json.Decoder[Any] = msgspec.json.Decoder(annotation)
-    except (TypeError, ValueError) as exc:
+        lt = msgspec_type(annotation)
+    except (TypeError, ValueError, UnsupportedBoundaryType) as exc:
         return None, [invalid_issue(component, str(exc))]
-    return (MappingProxyType(dict(schema)), decoder), []
+    return (MappingProxyType(dict(schema)), lt), []
 
 
 def _schema_fault(schema: Mapping[str, Any]) -> str | None: