loom-kernel 2.22.1__tar.gz → 2.22.3__tar.gz

{loom_kernel-2.22.1 → loom_kernel-2.22.3}/CHANGELOG.md

@@ -88,6 +88,18 @@
   naming a scalar leaf (`"api.token"`) and convert that value; before, they
   failed on anything but a mapping.
 
+- **core:** compile-issue catalogues as data (ADR 0003, part B).
+  `loom.core.errors.codes` gains `IssueCode`, `Template` and `CompileIssue`.
+  An `IssueCode` member is declared as `NAME = "NAME", Template(text,
+  field=..., component=...)`, and `Code.NAME.issue(**params)` builds its
+  `CompileIssue` (`code`, `message`, `component`, `field`). Each part of the
+  template is a `str.format` template. A sequence parameter is joined with
+  `", "` and renders `none` when empty, a set is ordered by the text of its
+  items, and a type renders as its `__qualname__`. A missing or unknown
+  parameter raises a `TypeError` naming the code. `AgentErrorCode`,
+  `StreamingErrorCode` and `ETLErrorCode` are such catalogues, and
+  `ETLCompilationError.from_issue(issue)` raises the ETL error for an issue.
+
 ### ai
 
 - **ai:** `AiConfig` logs a warning for every key of `ai.prices` that no
@@ -447,6 +459,14 @@
 
 ### core
 
+- **core:** `Rule.check(..., via=fn)` takes the violation from `fn`: a `str`
+  (the message) or a `RuleViolation` fails the rule, `None` passes it. A `bool`
+  or any other result raises `TypeError` naming the field, instead of `True`
+  failing the rule and `False` passing it. The `message=` parameter of
+  `Rule.check` is removed. `Rule.forbid` keeps its boolean condition; a `str`
+  or `RuleViolation` it returns no longer fails the rule. Migrate
+  `Rule.check(F(Order).total, via=lambda v: v <= 0, message="total must be > 0")`
+  to `Rule.check(F(Order).total, via=lambda v: "total must be > 0" if v <= 0 else None)`.
 - **core:** the `LoomType` protocol gains `from_query(params)`, which
   validates query-string values strictly. A number takes the JSON number
   grammar and must be finite, an integer its integer subset within
@@ -493,6 +513,24 @@
 
 ### ai
 
+- **ai:** compile issues come from the code catalogue, and the 89 issue
+  factory functions of `loom.ai.errors` are removed, without aliases: for
+  example `spec_malformed`, `engine_not_found` and `mcp_server_unreachable`.
+  Build an issue with `AgentErrorCode.X.issue(...)` and keyword arguments,
+  such as `AgentErrorCode.ENGINE_NOT_FOUND.issue(component="openai-agents",
+  available=["pydantic-ai"])`. `loom.ai.errors.from_message` is removed too:
+  `AgentCompilationError` still turns a bare string into an `UNSPECIFIED`
+  issue. Messages keep their text; a list that is empty renders `none`.
+- **ai:** `AgentCompilationIssue` is a type alias of
+  `CompileIssue[AgentErrorCode]` from `loom.core.errors.codes`, not a class.
+  It has the same fields, but `isinstance` against it raises `TypeError`
+  (check `CompileIssue` instead), and it no longer derives from
+  `LoomFrozenStruct`, so `loom_message_type()` is gone.
+- **ai:** an `Mcp()` include filter on a use case that matches no tool aborts
+  start-up with the new code `USECASE_TOOL_FILTER_MATCHES_NOTHING` instead of
+  `TOOL_FILTER_MATCHES_NOTHING`, which is now raised only by an agent
+  artifact's filter. The message and the `parameters.<name>` field are
+  unchanged.
 - **ai:** `AgentPlan.fingerprint`, and so the ETL `agent_version` column,
   changes once for every existing agent. It no longer covers any policy, so
   changing `retries`, a timeout, `max_iterations`, `max_tool_calls`,
@@ -646,6 +684,25 @@
 
 ### etl
 
+- **etl:** compile errors come from the code catalogue, and the 34
+  class-method factories of `ETLCompilationError` are removed, without
+  aliases: for example `upsert_no_keys`, `missing_target` and
+  `unknown_source_table`. Raise
+  `ETLCompilationError.from_issue(ETLErrorCode.X.issue(...))`; the
+  `ETLCompilationError(code, component, message, field)` constructor is
+  unchanged. Messages keep their text.
+- **etl:** each `IntoHistory` compile check has its own code instead of
+  `INVALID_TARGET_TYPE`: `HISTORIFY_KEYS_EMPTY`, `HISTORIFY_KEYS_TRACK_OVERLAP`,
+  `HISTORIFY_EFFECTIVE_DATE_IN_TRACK`, `HISTORIFY_BOUNDARY_IN_KEYS`,
+  `HISTORIFY_BOUNDARY_IN_TRACK`, `HISTORIFY_LOG_EFFECTIVE_DATE_NOT_COLUMN`,
+  `HISTORIFY_DELETE_MARKER_REQUIRES_LOG` and
+  `HISTORIFY_DELETE_MARKER_DECLARED_COLUMN`. Messages and fields are unchanged;
+  code that matched `INVALID_TARGET_TYPE` for these checks must match the new
+  codes. `INVALID_TARGET_TYPE` now means only a `target` that is not an
+  `IntoTable`, `IntoFile` or `IntoTemp`.
+- **etl:** `ETLErrorCode.INVALID_SOURCES_TYPE` is removed. No step could raise
+  it: a step's sources are grouped only when `sources` is a `Sources` or a
+  `SourceSet`, and both are valid.
 - **etl:** a `WithAgent` compiled by a runner whose config has no `ai:`
   section fails with the new code `AGENT_RUNNER_NOT_CONFIGURED` instead of
   `AGENT_NOT_FOUND`, which now means only that no artifact declares the name.
@@ -692,6 +749,20 @@
   `sNaN` used to raise `decimal.InvalidOperation`, and a `Decimal`
   `Infinity`, a `float` `inf` and a `float` `nan` were accepted.
 
+### streaming
+
+- **streaming:** compile issues come from the code catalogue
+  (`StreamingErrorCode.X.issue(...)`), and the compiler's private issue
+  factories are removed. `loom.streaming.compiler.CompilationIssue` is a type
+  alias of `CompileIssue[StreamingErrorCode]`, not a class: it has the same
+  fields, but `isinstance` against it raises `TypeError` (check
+  `CompileIssue` instead), `loom_message_type()` is gone, and
+  `CompilationIssue.prefixed()` is removed. Messages keep their text.
+- **streaming:** a `Broadcast` followed by another node reports
+  `BROADCAST_NOT_LAST` with component `broadcast`, at the top level, in a
+  branch and in a Router branch. It used to report `TERMINAL_NOT_LAST` with
+  component `Broadcast`.
+
 ## 🐛 Fixes
 
 ### core
@@ -916,6 +987,27 @@
   `$ref` wherever they occur, for msgspec tagged structs and pydantic
   discriminated unions alike, an optional (`X | Y | None`) union included.
 
+### streaming
+
+- **streaming:** a `Broadcast` is validated as a `Broadcast`. The compiler
+  treated it as a plain terminal, so the nodes of its branches were never
+  shape-checked. A branch with a shape mismatch, such as a record step after
+  `CollectBatch`, now fails compilation with `SHAPE_MISMATCH` scoped under
+  `broadcast branch <n>`; such flows used to compile. The code a misplaced
+  `Broadcast` reports is under Behaviour changes.
+- **streaming:** a bare `ErrorEnvelope` among the `payloads` of
+  `FromMultiTypeTopic` is refused with `ERROR_ENVELOPE_UNPARAMETERIZED`. The
+  check only matched `ErrorEnvelope[X]`, which always has a parameter, so the
+  bare class compiled as a plain payload and its messages never reached the
+  error dispatch. Declare `ErrorEnvelope[OrderEvent]` instead; such flows used
+  to compile.
+- **streaming:** an `ExpandRoutes` is validated. Its routes were never
+  shape-checked and nothing stopped a node from following it, although the
+  node is terminal and hands the expanded payloads, not rows, to whatever
+  follows. Each route is now checked on the record stream it receives, with
+  issues scoped under `expand_routes branch <type>`, and a node after an
+  `ExpandRoutes` fails with `TERMINAL_NOT_LAST`; such flows used to compile.
+
 ### prefect
 
 - **prefect:** every log line the bridge sends carries the run's

{loom_kernel-2.22.1 → loom_kernel-2.22.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.22.1
+Version: 2.22.3
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
@@ -524,8 +524,8 @@ class PricingPreviewUseCase(UseCase[Record, PricingPreviewResponse]):
         ),
     )
     rules = (
-        Rule.check(F(PricingCommand).unit_price, via=lambda v: v <= 0, message="unit_price must be > 0"),
-        Rule.check(F(PricingCommand).country, via=lambda v: v not in TAX_RATES, message="Unsupported country"),
+        Rule.check(F(PricingCommand).unit_price, via=lambda v: "unit_price must be > 0" if v <= 0 else None),
+        Rule.check(F(PricingCommand).country, via=lambda v: None if v in TAX_RATES else "Unsupported country"),
     )
 
     async def execute(self, record_id: int, cmd: PricingCommand = Input()) -> PricingPreviewResponse:

{loom_kernel-2.22.1 → loom_kernel-2.22.3}/README.md

@@ -400,8 +400,8 @@ class PricingPreviewUseCase(UseCase[Record, PricingPreviewResponse]):
         ),
     )
     rules = (
-        Rule.check(F(PricingCommand).unit_price, via=lambda v: v <= 0, message="unit_price must be > 0"),
-        Rule.check(F(PricingCommand).country, via=lambda v: v not in TAX_RATES, message="Unsupported country"),
+        Rule.check(F(PricingCommand).unit_price, via=lambda v: "unit_price must be > 0" if v <= 0 else None),
+        Rule.check(F(PricingCommand).country, via=lambda v: None if v in TAX_RATES else "Unsupported country"),
     )
 
     async def execute(self, record_id: int, cmd: PricingCommand = Input()) -> PricingPreviewResponse:

{loom_kernel-2.22.1 → loom_kernel-2.22.3}/src/loom/ai/_startup.py

@@ -25,13 +25,7 @@ from typing import get_args
 
 from loom.ai.compiler import AgentPlan
 from loom.ai.config import McpServerConfig
-from loom.ai.errors import (
-    AgentCompilationError,
-    AgentCompilationIssue,
-    agent_marker_output_mismatch,
-    agent_marker_unknown,
-    mcp_marker_unknown,
-)
+from loom.ai.errors import AgentCompilationError, AgentCompilationIssue, AgentErrorCode
 from loom.core.engine.compilable import Compilable
 from loom.core.engine.plan import AgentBinding, McpBinding
 from loom.core.use_case.registry import UseCaseRegistry
@@ -85,7 +79,9 @@ def _agent_binding_issues(
     for binding in agent_bindings:
         agent_plan = plans_by_name.get(binding.agent)
         if agent_plan is None:
-            yield agent_marker_unknown(uc_name, binding.name, binding.agent, available)
+            yield AgentErrorCode.AGENT_MARKER_UNKNOWN.issue(
+                component=uc_name, parameter=binding.name, agent=binding.agent, available=available
+            )
             continue
         expected_args = get_args(binding.annotation)
         if not expected_args:
@@ -97,10 +93,10 @@ def _agent_binding_issues(
         declared = agent_plan.output.loom_type.type
         if expected is declared:
             continue
-        yield agent_marker_output_mismatch(
-            uc_name,
-            binding.name,
-            binding.agent,
+        yield AgentErrorCode.AGENT_MARKER_OUTPUT_MISMATCH.issue(
+            component=uc_name,
+            parameter=binding.name,
+            agent=binding.agent,
             expected=getattr(expected, "__name__", str(expected)),
             declared=getattr(declared, "__name__", str(declared)),
         )
@@ -159,7 +155,12 @@ def _mcp_binding_issues(
     available = tuple(servers)
     for binding in mcp_bindings:
         if binding.server not in servers:
-            yield mcp_marker_unknown(uc_name, binding.name, binding.server, available)
+            yield AgentErrorCode.MCP_MARKER_UNKNOWN.issue(
+                component=uc_name,
+                parameter=binding.name,
+                server=binding.server,
+                available=available,
+            )
 
 
 __all__ = ["verify_agent_markers", "verify_mcp_markers"]

{loom_kernel-2.22.1 → loom_kernel-2.22.3}/src/loom/ai/a2a/_binding.py

@@ -25,11 +25,7 @@ from starlette.middleware import Middleware
 from loom.ai.a2a.card import build_agent_card, card_path
 from loom.ai.compiler import AgentPlan
 from loom.ai.config import AgentEndpointConfig, AiConfig
-from loom.ai.errors import (
-    AgentCompilationError,
-    auth_exclusion_overlaps_agents,
-    state_surface_unsupported,
-)
+from loom.ai.errors import AgentCompilationError, AgentErrorCode
 from loom.ai.fastapi.response import ENCODER
 from loom.ai.runtime import AgentRuntime
 from loom.core.config.errors import ConfigError
@@ -98,7 +94,9 @@ def published_agents(
             )
             continue
         if plan.state is not None:
-            raise AgentCompilationError([state_surface_unsupported(name, "a2a")])
+            raise AgentCompilationError(
+                [AgentErrorCode.STATE_SURFACE_UNSUPPORTED.issue(component=name, surface="a2a")]
+            )
         card = ENCODER.encode(build_agent_card(plan, a2a, mechanism=mechanism, prefix=prefix))
         published.append(
             PublishedAgent(
@@ -180,7 +178,9 @@ def verify_exclusions(
         and any(path == root or path.startswith(f"{root}/") for root in guarded)
     ]
     if offending:
-        raise AgentCompilationError([auth_exclusion_overlaps_agents(offending)])
+        raise AgentCompilationError(
+            [AgentErrorCode.AUTH_EXCLUSION_OVERLAPS_AGENTS.issue(paths=offending)]
+        )
 
 
 def _is_auth_middleware(entry: Middleware) -> bool:

{loom_kernel-2.22.1 → loom_kernel-2.22.3}/src/loom/ai/compiler/_compiler.py

@@ -31,11 +31,7 @@ from loom.ai.compiler.phases._output import compile_output, compile_output_check
 from loom.ai.compiler.phases._state import compile_state
 from loom.ai.config import AiConfig
 from loom.ai.declarative import AgentSpecV1, DecodedSpec
-from loom.ai.errors import (
-    AgentCompilationError,
-    AgentCompilationIssue,
-    agent_name_duplicate,
-)
+from loom.ai.errors import AgentCompilationError, AgentCompilationIssue, AgentErrorCode
 from loom.ai.inference import InferenceTarget
 from loom.ai.pricing import ModelPrice
 from loom.core.sql.config import SqlConfig
@@ -240,4 +236,8 @@ def _duplicate_name_issues(
     sources: dict[str, list[str]] = defaultdict(list)
     for spec, source_path in entries:
         sources[spec.name].append(source_path if source_path is not None else _UNNAMED_SOURCE)
-    return [agent_name_duplicate(name, paths) for name, paths in sources.items() if len(paths) > 1]
+    return [
+        AgentErrorCode.AGENT_NAME_DUPLICATE.issue(component=name, sources=paths)
+        for name, paths in sources.items()
+        if len(paths) > 1
+    ]

{loom_kernel-2.22.1 → loom_kernel-2.22.3}/src/loom/ai/compiler/phases/_capabilities.py

@@ -46,31 +46,7 @@ from loom.ai.declarative import (
     SqlCapability,
     UsecaseCapability,
 )
-from loom.ai.errors import (
-    AgentCompilationError,
-    AgentCompilationIssue,
-    a2a_agent_unknown,
-    anonymous_with_data_capability,
-    capability_empty,
-    capability_kind_unsupported,
-    mcp_server_unknown,
-    native_tool_duplicate,
-    native_tool_unsupported,
-    python_factory_not_callable,
-    python_factory_params_rejected,
-    python_factory_unresolvable,
-    skills_library_escapes,
-    skills_library_invalid,
-    skills_name_collision,
-    skills_root_missing,
-    sql_config_missing,
-    sql_connection_not_readonly,
-    sql_connection_roles_unbound,
-    sql_connection_unknown,
-    sql_result_bound_missing,
-    usecase_declares_query,
-    usecase_key_unknown,
-)
+from loom.ai.errors import AgentCompilationError, AgentCompilationIssue, AgentErrorCode
 from loom.ai.inference import InferenceTarget
 from loom.core.engine.compilable import Compilable
 from loom.core.sql.config import SqlConfig, roles_need_identity_binding
@@ -171,10 +147,16 @@ def compile_capabilities(
     for capability in spec.capabilities:
         kind = str(capability.__struct_config__.tag)
         if kind not in supported_kinds:
-            issues.append(capability_kind_unsupported(component, kind, config.engine))
+            issues.append(
+                AgentErrorCode.CAPABILITY_KIND_UNSUPPORTED.issue(
+                    component=component, kind=kind, engine=config.engine
+                )
+            )
             continue
         if context.anonymous and kind in _DATA_OR_REMOTE_KINDS:
-            issues.append(anonymous_with_data_capability(component, kind))
+            issues.append(
+                AgentErrorCode.ANONYMOUS_WITH_DATA_CAPABILITY.issue(component=component, kind=kind)
+            )
         item, item_issues = _HANDLERS[type(capability)](capability, context)
         issues.extend(item_issues)
         if item is not None:
@@ -195,7 +177,11 @@ def _native_duplicate_issues(
         if not isinstance(capability, CompiledNativeCapability):
             continue
         if capability.tool in seen:
-            issues.append(native_tool_duplicate(component, capability.tool))
+            issues.append(
+                AgentErrorCode.NATIVE_TOOL_DUPLICATE.issue(
+                    component=component, tool=capability.tool
+                )
+            )
             continue
         seen.add(capability.tool)
     return issues
@@ -214,7 +200,14 @@ def _skill_collision_issues(
         for name in capability.names:
             first = owner.setdefault(name, capability.library)
             if first != capability.library:
-                issues.append(skills_name_collision(component, name, first, capability.library))
+                issues.append(
+                    AgentErrorCode.SKILLS_NAME_COLLISION.issue(
+                        component=component,
+                        skill=name,
+                        first_library=first,
+                        second_library=capability.library,
+                    )
+                )
     return issues
 
 
@@ -230,11 +223,15 @@ def _compile_usecase(capability: UsecaseCapability, context: _Context) -> _Handl
         try:
             use_case = context.registry.resolve(key)
         except KeyError:
-            issues.append(usecase_key_unknown(context.component, key))
+            issues.append(
+                AgentErrorCode.USECASE_KEY_UNKNOWN.issue(component=context.component, key=key)
+            )
             continue
         execution = getattr(use_case, "__execution_plan__", None)
         if execution is not None and execution.query_binding is not None:
-            issues.append(usecase_declares_query(context.component, key))
+            issues.append(
+                AgentErrorCode.USECASE_DECLARES_QUERY.issue(component=context.component, key=key)
+            )
         use_cases.append(use_case)
     if issues:
         return None, issues
@@ -243,20 +240,36 @@ def _compile_usecase(capability: UsecaseCapability, context: _Context) -> _Handl
 
 def _compile_sql(capability: SqlCapability, context: _Context) -> _HandlerResult:
     if context.sql is None:
-        return None, [sql_config_missing(context.component)]
+        return None, [AgentErrorCode.SQL_CONFIG_MISSING.issue(component=context.component)]
     connection = context.sql.connections.get(capability.connection)
     if connection is None:
-        return None, [sql_connection_unknown(context.component, capability.connection)]
+        return None, [
+            AgentErrorCode.SQL_CONNECTION_UNKNOWN.issue(
+                component=context.component, connection=capability.connection
+            )
+        ]
     issues: list[AgentCompilationIssue] = []
     if not connection.readonly:
-        issues.append(sql_connection_not_readonly(context.component, capability.connection))
+        issues.append(
+            AgentErrorCode.SQL_CONNECTION_NOT_READONLY.issue(
+                component=context.component, connection=capability.connection
+            )
+        )
     binds_roles = not context.anonymous
     if roles_need_identity_binding(connection.allowed_roles, mechanism_binds_roles=binds_roles):
-        issues.append(sql_connection_roles_unbound(context.component, capability.connection))
+        issues.append(
+            AgentErrorCode.SQL_CONNECTION_ROLES_UNBOUND.issue(
+                component=context.component, connection=capability.connection
+            )
+        )
     # Defensive: the v1 struct already makes absent or non-positive bounds
     # unrepresentable, but a spec built through another path must not pass.
     if capability.max_rows < 1 or capability.max_result_bytes < 1:
-        issues.append(sql_result_bound_missing(context.component, capability.connection))
+        issues.append(
+            AgentErrorCode.SQL_RESULT_BOUND_MISSING.issue(
+                component=context.component, connection=capability.connection
+            )
+        )
     if issues:
         return None, issues
     return (
@@ -294,12 +307,14 @@ def compile_mcp_capability(
 
     Returns:
         The compiled capability, or ``None`` with one
-        :func:`~loom.ai.errors.mcp_server_unknown` issue when ``server_name``
-        is not in ``servers``.
+        :attr:`~loom.ai.errors.AgentErrorCode.MCP_SERVER_UNKNOWN` issue when
+        ``server_name`` is not in ``servers``.
     """
     server = servers.get(server_name)
     if server is None:
-        return None, [mcp_server_unknown(component, server_name)]
+        return None, [
+            AgentErrorCode.MCP_SERVER_UNKNOWN.issue(component=component, server=server_name)
+        ]
     return (
         CompiledMcpCapability(
             server=server_name,
@@ -347,7 +362,11 @@ def _compile_auth(auth: Mapping[str, str] | None) -> CompiledRemoteAuth | None:
 def _compile_a2a(capability: A2ACapability, context: _Context) -> _HandlerResult:
     agent = context.a2a_agents.get(capability.agent)
     if agent is None:
-        return None, [a2a_agent_unknown(context.component, capability.agent)]
+        return None, [
+            AgentErrorCode.A2A_AGENT_UNKNOWN.issue(
+                component=context.component, agent=capability.agent
+            )
+        ]
     return (
         CompiledA2ACapability(
             agent=capability.agent,
@@ -366,22 +385,34 @@ def _library_base(library: str, context: _Context) -> _ResolveResult:
     if library.startswith(_LOCAL_LIBRARY_PREFIX):
         if context.source_path is None:
             reason = "a './' library needs a known artifact path"
-            return None, [skills_library_invalid(context.component, library, reason)]
+            return None, [
+                AgentErrorCode.SKILLS_LIBRARY_INVALID.issue(
+                    component=context.component, library=library, reason=reason
+                )
+            ]
         return Path(context.source_path).parent, []
     if context.skills_root is None:
-        return None, [skills_root_missing(context.component)]
+        return None, [AgentErrorCode.SKILLS_ROOT_MISSING.issue(component=context.component)]
     return Path(context.skills_root), []
 
 
 def _resolve_library(library: str, context: _Context) -> _ResolveResult:
     if escapes(library.removeprefix(_LOCAL_LIBRARY_PREFIX)):
-        return None, [skills_library_escapes(context.component, library)]
+        return None, [
+            AgentErrorCode.SKILLS_LIBRARY_ESCAPES.issue(
+                component=context.component, library=library
+            )
+        ]
     base, issues = _library_base(library, context)
     if base is None:
         return None, issues
     resolved = base / library.removeprefix(_LOCAL_LIBRARY_PREFIX)
     if not is_within(resolved, base):
-        return None, [skills_library_escapes(context.component, library)]
+        return None, [
+            AgentErrorCode.SKILLS_LIBRARY_ESCAPES.issue(
+                component=context.component, library=library
+            )
+        ]
     return resolved.resolve(), []
 
 
@@ -413,14 +444,20 @@ def _compile_skills(capability: SkillsCapability, context: _Context) -> _Handler
         return None, issues
     discovered, reason = _discover_skills(directory)
     if reason is not None:
-        return None, [skills_library_invalid(context.component, library, reason)]
+        return None, [
+            AgentErrorCode.SKILLS_LIBRARY_INVALID.issue(
+                component=context.component, library=library, reason=reason
+            )
+        ]
     selected = select_names(
         discovered,
         include=capability.include,
         exclude=capability.exclude,
     )
     if not selected:
-        return None, [capability_empty(context.component, "skills")]
+        return None, [
+            AgentErrorCode.CAPABILITY_EMPTY.issue(component=context.component, kind="skills")
+        ]
     return (
         CompiledSkillsCapability(library=library, directory=str(directory), names=selected),
         [],
@@ -431,9 +468,17 @@ def _compile_python(capability: PythonCapability, context: _Context) -> _Handler
     try:
         factory = import_symbol(capability.factory)
     except (ImportError, AttributeError, ValueError) as exc:
-        return None, [python_factory_unresolvable(context.component, capability.factory, str(exc))]
+        return None, [
+            AgentErrorCode.PYTHON_FACTORY_UNRESOLVABLE.issue(
+                component=context.component, factory=capability.factory, reason=str(exc)
+            )
+        ]
     if not callable(factory):
-        return None, [python_factory_not_callable(context.component, capability.factory)]
+        return None, [
+            AgentErrorCode.PYTHON_FACTORY_NOT_CALLABLE.issue(
+                component=context.component, factory=capability.factory
+            )
+        ]
     issue = _rejected_params(factory, capability.params, context.component, capability.factory)
     if issue is not None:
         return None, [issue]
@@ -460,11 +505,13 @@ def _rejected_params(
     try:
         signature.bind_partial(_FIRST_POSITIONAL)
     except TypeError:
-        return python_factory_not_callable(component, ref)
+        return AgentErrorCode.PYTHON_FACTORY_NOT_CALLABLE.issue(component=component, factory=ref)
     try:
         signature.bind(_FIRST_POSITIONAL, **params)
     except TypeError as exc:
-        return python_factory_params_rejected(component, ref, str(exc))
+        return AgentErrorCode.PYTHON_FACTORY_PARAMS_REJECTED.issue(
+            component=component, factory=ref, reason=str(exc)
+        )
     return None
 
 
@@ -477,15 +524,19 @@ def _compile_native(capability: NativeCapability, context: _Context) -> _Handler
     if context.inference is None:
         return None, []
     if context.native_tools is None:
-        return None, [capability_kind_unsupported(context.component, "native", context.engine)]
+        return None, [
+            AgentErrorCode.CAPABILITY_KIND_UNSUPPORTED.issue(
+                component=context.component, kind="native", engine=context.engine
+            )
+        ]
     try:
         supported = context.native_tools(context.inference)
     except AgentCompilationError as exc:
         return None, list(exc.issues)
     if capability.tool not in supported:
         return None, [
-            native_tool_unsupported(
-                context.component,
+            AgentErrorCode.NATIVE_TOOL_UNSUPPORTED.issue(
+                component=context.component,
                 tool=capability.tool,
                 role=context.model_role,
                 provider=context.inference.provider,

{loom_kernel-2.22.1 → loom_kernel-2.22.3}/src/loom/ai/compiler/phases/_conversation.py

@@ -18,12 +18,7 @@ from __future__ import annotations
 from loom.ai.compiler._plan import CONVERSATION_CONTEXT_FIELDS, CompiledConversation
 from loom.ai.compiler.phases._feedable import feedable_input, is_granted
 from loom.ai.declarative import AgentSpecV1
-from loom.ai.errors import (
-    AgentCompilationIssue,
-    conversation_input_unsatisfied,
-    conversation_usecase_also_granted,
-    conversation_usecase_unknown,
-)
+from loom.ai.errors import AgentCompilationIssue, AgentErrorCode
 from loom.core.use_case.registry import UseCaseRegistry
 
 _ConversationResult = tuple[CompiledConversation | None, list[AgentCompilationIssue]]
@@ -59,17 +54,29 @@ def compile_conversation(
     key = spec.conversation.usecase
     issues: list[AgentCompilationIssue] = []
     if is_granted(spec.capabilities, key):
-        issues.append(conversation_usecase_also_granted(component, key))
+        issues.append(
+            AgentErrorCode.CONVERSATION_USECASE_ALSO_GRANTED.issue(component=component, key=key)
+        )
     try:
         use_case = registry.resolve(key)
     except KeyError:
-        issues.append(conversation_usecase_unknown(component, key))
+        issues.append(
+            AgentErrorCode.CONVERSATION_USECASE_UNKNOWN.issue(component=component, key=key)
+        )
         return None, issues
     accepted, reason = feedable_input(use_case, _OFFERED)
     if reason is not None:
-        issues.append(conversation_input_unsatisfied(component, key, reason))
+        issues.append(
+            AgentErrorCode.CONVERSATION_INPUT_UNSATISFIED.issue(
+                component=component, key=key, reason=reason
+            )
+        )
     elif _CONVERSATION_ID not in accepted:
-        issues.append(conversation_input_unsatisfied(component, key, _MISSING_CONVERSATION_ID))
+        issues.append(
+            AgentErrorCode.CONVERSATION_INPUT_UNSATISFIED.issue(
+                component=component, key=key, reason=_MISSING_CONVERSATION_ID
+            )
+        )
     if issues:
         return None, issues
     return CompiledConversation(usecase=key, use_case=use_case, accepted=accepted), []

{loom_kernel-2.22.1 → loom_kernel-2.22.3}/src/loom/ai/compiler/phases/_hook.py

@@ -20,12 +20,7 @@ from loom.ai.compiler._plan import (
 )
 from loom.ai.compiler.phases._feedable import feedable_input, is_granted
 from loom.ai.declarative import AgentSpecV1
-from loom.ai.errors import (
-    AgentCompilationIssue,
-    on_output_input_unsatisfied,
-    on_output_usecase_also_granted,
-    on_output_usecase_unknown,
-)
+from loom.ai.errors import AgentCompilationIssue, AgentErrorCode
 from loom.core.use_case.registry import UseCaseRegistry
 
 _HookResult = tuple[CompiledOutputHook | None, list[AgentCompilationIssue]]
@@ -55,15 +50,21 @@ def compile_output_hook(
     key = spec.on_output.usecase
     issues: list[AgentCompilationIssue] = []
     if is_granted(spec.capabilities, key):
-        issues.append(on_output_usecase_also_granted(component, key))
+        issues.append(
+            AgentErrorCode.ON_OUTPUT_USECASE_ALSO_GRANTED.issue(component=component, key=key)
+        )
     try:
         use_case = registry.resolve(key)
     except KeyError:
-        issues.append(on_output_usecase_unknown(component, key))
+        issues.append(AgentErrorCode.ON_OUTPUT_USECASE_UNKNOWN.issue(component=component, key=key))
         return None, issues
     accepted, reason = feedable_input(use_case, _OFFERED)
     if reason is not None:
-        issues.append(on_output_input_unsatisfied(component, key, reason))
+        issues.append(
+            AgentErrorCode.ON_OUTPUT_INPUT_UNSATISFIED.issue(
+                component=component, key=key, reason=reason
+            )
+        )
     if issues:
         return None, issues
     return CompiledOutputHook(usecase=key, use_case=use_case, accepted=accepted), []