The facility model catalog: LanguageModel aggregate, governance gate, at-risk results (#558)

* Add the LanguageModel aggregate: the facility model catalog entry

The R3 component of the facility-LLM-budget reference architecture:
one aggregate carrying what a gateway's routing table cannot, the
governance attributes of an approved model. Identity reuses the Agent
aggregate's ModelRef so an agent's declared model and a catalog entry
compare field-for-field; served_via names the serving route (Direct,
Argo, InHouse) without ever carrying credentials (the serving layer
owns those); cost_basis is a discriminated union (TokenPricing
field-for-field with the observability ModelPricing so the future
pricing bridge needs no translation, or GpuHourPricing for in-house
pools; Argo-served entries carry facility-set shadow prices); and two
orthogonal tier axes, DataSensitivityTier (which data may reach the
model) and ArchivabilityTier (Pinned weights the facility can serve
forever vs an Alias the provider may move).

The FSM separates the two ways a model's service life ends because
they answer different audit questions: RetirementAnnounced -> Retired
is the VENDOR's lifecycle (the governance-event arm the at-risk-results
projection will read; Retired is also reachable straight from Approved
because providers remove models without notice), while Deprecated is
the FACILITY withdrawing approval. Approval itself is the
bootstrap-then-promote ceremony the agent fleet already follows: a
Defined entry is registered but not yet usable.

Homed in the agent BC beside the fleet it governs; the equipment BC
already owns the Model stream type, hence the longer name (single-word
alternatives all failed intent-matching; recorded in the design memo).
Fitness conformance: LanguageModelName uses the bounded_name
decorator; retirement_effective_at joins the fold-symmetry intrinsic
allowlist (a vendor schedule, not a CORA fact-act; the announcing
actor lives on the event envelope); all ten domain errors register as
HTTP handlers ahead of their slices.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Add the five LanguageModel catalog slices

define_language_model (genesis: guard + VO/enum validation + canonical
cost-basis re-encode so the event always carries exactly the canonical
key set) plus the four lifecycle transitions (approve,
announce-retirement, retire, deprecate) through a new
make_language_model_update_handler, the second aggregate slotting into
the per-aggregate factory shape _agent_update_handler promised. Routes
and MCP tools ship with each slice but register in the wiring commit.
112 unit tests pin the deciders (every wrong-source status per slice,
Hypothesis total-partition properties), reason validation, and
handler envelopes including deny-does-not-write.

Checkpoint commit (--no-verify): hooks run on the wiring commit that
completes the registration this commit's routes reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Add the catalog read side: projection, identity lookup, migration

proj_language_model_summary carries the one query shape the catalog
needs, by model identity: the define_agent gate and the startup fleet
check hold only (provider, model), never an entry id. The projection
folds all five lifecycle events; cost_basis stays off the read model so
pricing keeps exactly one home (the aggregate). LanguageModelLookup
follows the neutral-port family (always-approved stub as the kernel
default, so a catalog-less deployment stays permissive: declaring a
catalog is what arms the gate), with the agent BC's Postgres adapter
resolving latest-entry-wins over the projection.

Checkpoint commit (--no-verify): hooks run on the wiring commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Wire the model catalog: handlers, gate, fleet seeds, registration

The connective commit that turns the catalog from parts into a
governed surface:

- AgentHandlers/wire_agent carry the five slices (define with
  idempotency like define_agent; transitions traced); routes and MCP
  tools registered; the projection registered beside the agent
  summary; kernel gains language_model_lookup (always-approved
  default) with the Postgres adapter bound at the composition root
  when a pool exists.
- define_agent now refuses to register an agent whose model identity
  lacks an Approved catalog entry (LanguageModelNotApprovedError,
  raised before the vault upsert so refusal leaves no orphan profile
  row). The kernel default approves everything, so the gate arms only
  where a real catalog is stood up.
- seed_language_models ships the fleet's three default models as
  entries born Defined AND Approved in one idempotent append. Born
  Approved on purpose: seeds bypass handlers, and a fresh deployment
  must not refuse define_agent for its own shipped fleet; the
  operator's governance lever is deprecate_language_model. Pricing
  figures copy PRICING exactly, pinned by a consistency test, as is
  the mirror of the operation BC's default steering model (tach
  forbids the agent BC importing cora.operation).
- Fitness updates each carry a one-line justification: the
  projection-table ownership maps gain the two-aggregate agent BC,
  slice-coverage allowlists defer the contract/integration tiers with
  citations, the aggregate-count anti-drift pin bumps 41 to 42, and
  the OpenAPI snapshot gains the five /language-models routes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Add the at-risk-results surface: retirement becomes a queryable fact

The design's flagship claim made real: when a provider announces a
model's retirement, GET /language-models/{id}/at-risk-results
enumerates every Decision whose recorded LLM calls used that model,
graded by the entry's archivability tier. Pinned weights the facility
can serve grade ReExecutable; an Alias the provider may move grades
AttributableOnly, and at_risk is true only when that grade meets a
RetirementAnnounced or Retired status. The endpoint answers for ANY
status on purpose: an operator deciding whether to approve an Alias
entry wants to know what WOULD be at risk before any announcement.

The cross-BC seam follows the SpendLookup grammar: a neutral
ModelUsageLookup port (empty stub as the kernel default) whose
Postgres adapter ships from the decision BC, because it owns
entries_decision_inferences and the fitness suite rightly forbids the
agent BC reading that table. Matching covers the dated-snapshot case
(response_model LIKE model-%): calls served on a snapshot the provider
resolved from an alias are equally at risk when the alias retires.
DISTINCT ON keeps one row per Decision, newest first.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Apply the catalog arc's five-reviewer panel: shadow fix and renames

The load-bearing security fix: the gate-purpose lookup now answers
with the newest APPROVED entry only (plus a deterministic tiebreak),
so an unapproved or deprecated newer entry can never shadow an older
Approved one. That single change kills both the reviewer-found
governance denial-of-service (the weakest catalog write flipping
define_agent to refusal for any identity) and the accidental-duplicate
trap (deprecating a mistake now restores the prior Approved entry).
Its sibling: the seed skip path detects a squatted deterministic seed
id and warns loudly instead of logging "already seeded".

Correctness: gate refusals now finalize their idempotency claim as a
400 like every sibling validation error instead of stranding it
Claimed; the snapshot-matching arm escapes LIKE metacharacters and
matches exactly an eight-character dated suffix, so a base alias can
never swallow a sibling minor version's decisions while its own dated
snapshots still count; and first boot drains the agent projections
synchronously after seeding, closing the window where define_agent
would refuse the very models the seed just approved.

Naming per the panel: ModelUsageLookupResult (the bespoke
ModelTouchedDecision read with inverted agency and broke the
LookupResult family), AlwaysEmptyModelUsageLookup (joins the Always
stub family), and the projection table becomes
proj_agent_language_model_summary, restoring the multi-aggregate
BC-prefix rule and deleting the carve-out the build had added, with
conventions.md now documenting the rule the tree already followed.

Conventions: both new lookups bind through the factory grammar at
kernel construction instead of post-construction setattr; the phantom
"startup fleet check" wording now names the unit consistency test that
actually exists; born-Approved seeds cite their true precedent (the
clearance-template seed's Defined+Activated pair, not the agent fleet,
whose runtime gate is Actor.active).

Tests close every mutation survivor the panel found: the evolver file
(the Retired arm had never executed under test), Retired/Deprecated
at-risk cases, the Postgres lookup integration test that pins the
shadow fix itself, gate lookup-args pins, the LIKE boundary matrix in
both directions, and honest scoping on the contract-suite deferral
comments.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: xmap <16776958+xmap@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: xmap

apps/api/openapi.json

@@ -1,8 +1,10 @@
 """Agent bounded context.
 
-One aggregate, `Agent`. Genesis plus a lifecycle FSM
+Two aggregates. `Agent`: genesis plus a lifecycle FSM
 (`Defined -> Versioned -> Suspended? -> Deprecated`) with tool
-grants and budget envelopes.
+grants and budget envelopes. `LanguageModel`: the facility's
+catalog entry for one approved LLM, homed beside the fleet whose
+`Agent.model_ref` it governs.
 
 Production `AnthropicLLM` ships at
 `cora.agent.adapters.AnthropicLLM` and is wired into the
@@ -67,6 +69,7 @@
     EXPERIMENT_STEERER_AGENT_ID,
     seed_experiment_steerer_agent,
 )
+from cora.agent.seed_language_models import seed_language_models
 from cora.agent.seed_procedure_watcher import (
     PROCEDURE_WATCHER_AGENT_ID,
     seed_procedure_watcher_agent,
@@ -118,6 +121,7 @@
     "seed_clearance_expirer_agent",
     "seed_clearance_watcher_agent",
     "seed_experiment_steerer_agent",
+    "seed_language_models",
     "seed_procedure_watcher_agent",
     "seed_ratification_enforcer_agent",
     "seed_run_debriefer_agent",

apps/api/src/cora/agent/__init__.py

@@ -0,0 +1,76 @@
+"""LanguageModel's update-handler factory (thin wrapper).
+
+Mirrors `cora.agent._agent_update_handler` per the per-aggregate
+factory convention: that file's docstring kept its module shape lined
+up with the cross-BC factory precisely so a future second aggregate
+in the BC would slot in cleanly, and LanguageModel is that aggregate.
+Four transition slices bind through here (`approve_language_model`,
+`announce_language_model_retirement`, `retire_language_model`,
+`deprecate_language_model`).
+
+Thin variant only: none of the catalog's transition deciders takes
+the acting principal (the approving / retiring actor's identity lives
+on the event envelope, `StoredEvent.principal_id`), so the
+actor-stamping `make_agent_actor_update_handler` sibling stays
+Agent-only until a fold-symmetry LanguageModel slice needs one.
+
+## LanguageModel-side knobs closed over
+
+  - `stream_type = "LanguageModel"`.
+  - `target_id_attr = "language_model_id"` -- every LanguageModel
+    transition command exposes `language_model_id: UUID`.
+  - `unauthorized_error = UnauthorizedError` from the Agent BC (both
+    aggregates share the BC's application-error namespace, so an
+    Agent-BC 403 stays one class in log search).
+  - The four codec functions imported from
+    `cora.agent.aggregates.language_model`.
+
+`extra_log_fields` is a per-slice optional extractor for command-
+specific fields the structured log should emit, same contract as the
+Agent factory.
+"""
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from cora.agent.aggregates.language_model import (
+    LanguageModelEvent,
+    event_type_name,
+    fold,
+    from_stored,
+    to_payload,
+)
+from cora.agent.errors import UnauthorizedError
+from cora.infrastructure.kernel import Kernel
+from cora.infrastructure.update_handler import make_update_handler
+
+_STREAM_TYPE = "LanguageModel"
+_TARGET_ID_ATTR = "language_model_id"
+
+
+def make_language_model_update_handler(
+    deps: Kernel,
+    *,
+    command_name: str,
+    log_prefix: str,
+    decide_fn: Callable[..., Sequence[LanguageModelEvent]],
+    extra_log_fields: Callable[[Any], dict[str, Any]] | None = None,
+):
+    """Build an update-style handler for one LanguageModel slice (fold-NEITHER posture)."""
+    return make_update_handler(
+        deps,
+        stream_type=_STREAM_TYPE,
+        target_id_attr=_TARGET_ID_ATTR,
+        from_stored=from_stored,
+        to_payload=to_payload,
+        event_type_name=event_type_name,
+        fold=fold,
+        unauthorized_error=UnauthorizedError,
+        command_name=command_name,
+        log_prefix=log_prefix,
+        decide_fn=decide_fn,
+        extra_log_fields=extra_log_fields,
+    )
+
+
+__all__ = ["make_language_model_update_handler"]

apps/api/src/cora/agent/_language_model_update_handler.py

@@ -2,13 +2,13 @@
 
 The composition root (`cora.api.main`) calls
 `register_agent_projections(registry, deps)` during the FastAPI
-lifespan to populate the worker's registry. Agent BC's first
-projection ships per the Path C lock (state stays decider-minimal;
-lifecycle timestamps live on the projection — mirrors
+lifespan to populate the worker's registry. Agent BC's projections
+ship per the Path C lock (state stays decider-minimal; lifecycle
+timestamps live on the projection, mirroring
 Method/Plan/Practice/Family/Capability).
 """
 
-from cora.agent.projections import AgentSummaryProjection
+from cora.agent.projections import AgentSummaryProjection, LanguageModelSummaryProjection
 from cora.infrastructure.kernel import Kernel
 from cora.infrastructure.projection import ProjectionRegistry
 
@@ -20,6 +20,7 @@ def register_agent_projections(
     """Register every Agent-owned projection on the worker registry."""
     _ = deps
     registry.register(AgentSummaryProjection())
+    registry.register(LanguageModelSummaryProjection())
 
 
 __all__ = ["register_agent_projections"]

apps/api/src/cora/agent/_projections.py

@@ -9,5 +9,6 @@
 
 from cora.agent.adapters.anthropic_llm import AnthropicLLM
 from cora.agent.adapters.budget_spend_guard import BudgetSpendGuard
+from cora.agent.adapters.postgres_language_model_lookup import PostgresLanguageModelLookup
 
-__all__ = ["AnthropicLLM", "BudgetSpendGuard"]
+__all__ = ["AnthropicLLM", "BudgetSpendGuard", "PostgresLanguageModelLookup"]

apps/api/src/cora/agent/adapters/__init__.py

@@ -0,0 +1,57 @@
+"""PostgresLanguageModelLookup: the catalog identity lookup over the projection.
+
+The agent BC ships the production adapter because it owns the fact:
+`proj_agent_language_model_summary` is this BC's read model of its own
+aggregate. The lookup answers the GATE's question, the newest APPROVED
+entry for the identity, so an unapproved or deprecated newer entry can
+never shadow an older Approved one into refusing agent registration,
+and deprecating a mistaken duplicate restores the previous Approved
+entry. The `language_model_id DESC` tiebreak makes equal-created_at
+rows deterministic.
+"""
+
+from __future__ import annotations
+
+# pyright: reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false
+from typing import TYPE_CHECKING
+
+from cora.infrastructure.ports.language_model_lookup import LanguageModelLookupResult
+
+if TYPE_CHECKING:
+    import asyncpg
+
+_FIND_SQL = """
+SELECT language_model_id, status, data_tier, archivability, snapshot_pin
+FROM proj_agent_language_model_summary
+WHERE provider = $1 AND model = $2 AND status = 'Approved'
+ORDER BY created_at DESC, language_model_id DESC
+LIMIT 1
+"""
+
+
+class PostgresLanguageModelLookup:
+    """`LanguageModelLookup` over `proj_agent_language_model_summary`."""
+
+    def __init__(self, pool: asyncpg.Pool) -> None:
+        self._pool = pool
+
+    async def find_by_model(
+        self,
+        *,
+        provider: str,
+        model: str,
+    ) -> LanguageModelLookupResult | None:
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(_FIND_SQL, provider, model)
+        if row is None:
+            return None
+        return LanguageModelLookupResult(
+            language_model_id=row["language_model_id"],
+            status=row["status"],
+            data_tier=row["data_tier"],
+            archivability=row["archivability"],
+            snapshot_pin=row["snapshot_pin"],
+        )
+
+
+__all__ = ["PostgresLanguageModelLookup"]

apps/api/src/cora/agent/adapters/postgres_language_model_lookup.py

@@ -0,0 +1,100 @@
+"""LanguageModel aggregate: status FSM, serving route, cost-basis union,
+tier axes, bounded-text VOs, errors, events, evolver, read repo.
+
+The facility's catalog entry for one approved LLM, homed in the agent
+BC beside the fleet whose `Agent.model_ref` it governs. Design lock:
+[[project_model_catalog_design]].
+
+Vertical slices that operate on this aggregate live under
+`cora.agent.features.<verb>_language_model/` and import from here for
+state and event types.
+
+Public surface: enums + VOs + cost-basis union + errors + events +
+evolver + load_language_model. `ModelRef` is deliberately NOT
+re-exported here; its home stays the Agent aggregate (this entry
+reuses the same VO so an agent's declared model and a catalog entry
+compare field-for-field).
+"""
+
+from cora.agent.aggregates.language_model.events import (
+    LanguageModelApproved,
+    LanguageModelDefined,
+    LanguageModelDeprecated,
+    LanguageModelEvent,
+    LanguageModelRetired,
+    LanguageModelRetirementAnnounced,
+    cost_basis_from_payload,
+    cost_basis_to_payload,
+    event_type_name,
+    from_stored,
+    to_payload,
+)
+from cora.agent.aggregates.language_model.evolver import evolve, fold
+from cora.agent.aggregates.language_model.read import load_language_model
+from cora.agent.aggregates.language_model.state import (
+    ENDPOINT_NOTE_MAX_LENGTH,
+    LANGUAGE_MODEL_NAME_MAX_LENGTH,
+    ArchivabilityTier,
+    CostBasis,
+    DataSensitivityTier,
+    EndpointNote,
+    GpuHourPricing,
+    InvalidCostBasisError,
+    InvalidEndpointNoteError,
+    InvalidLanguageModelNameError,
+    InvalidLanguageModelReasonError,
+    LanguageModel,
+    LanguageModelAlreadyExistsError,
+    LanguageModelCannotAnnounceRetirementError,
+    LanguageModelCannotApproveError,
+    LanguageModelCannotDeprecateError,
+    LanguageModelCannotRetireError,
+    LanguageModelName,
+    LanguageModelNotApprovedError,
+    LanguageModelNotFoundError,
+    LanguageModelReason,
+    LanguageModelStatus,
+    ServingRoute,
+    TokenPricing,
+)
+
+__all__ = [
+    "ENDPOINT_NOTE_MAX_LENGTH",
+    "LANGUAGE_MODEL_NAME_MAX_LENGTH",
+    "ArchivabilityTier",
+    "CostBasis",
+    "DataSensitivityTier",
+    "EndpointNote",
+    "GpuHourPricing",
+    "InvalidCostBasisError",
+    "InvalidEndpointNoteError",
+    "InvalidLanguageModelNameError",
+    "InvalidLanguageModelReasonError",
+    "LanguageModel",
+    "LanguageModelAlreadyExistsError",
+    "LanguageModelApproved",
+    "LanguageModelCannotAnnounceRetirementError",
+    "LanguageModelCannotApproveError",
+    "LanguageModelCannotDeprecateError",
+    "LanguageModelCannotRetireError",
+    "LanguageModelDefined",
+    "LanguageModelDeprecated",
+    "LanguageModelEvent",
+    "LanguageModelName",
+    "LanguageModelNotApprovedError",
+    "LanguageModelNotFoundError",
+    "LanguageModelReason",
+    "LanguageModelRetired",
+    "LanguageModelRetirementAnnounced",
+    "LanguageModelStatus",
+    "ServingRoute",
+    "TokenPricing",
+    "cost_basis_from_payload",
+    "cost_basis_to_payload",
+    "event_type_name",
+    "evolve",
+    "fold",
+    "from_stored",
+    "load_language_model",
+    "to_payload",
+]