aggregate_api 1.0.0__py3-none-any.whl

aggregate_api/models.py

@@ -0,0 +1,1407 @@
+"""Pydantic v2 schemas for the api request and response bodies.
+
+Each endpoint takes / returns one of these dataclass-like models.
+FastAPI validates incoming JSON against the request model and
+serializes outgoing responses through the declared return-type
+model -- the trip through OpenAPI is automatic.
+
+Flask users: think Marshmallow / pydantic-flask, but tighter --
+the model *is* the function parameter type, not a separate
+schema you call ``schema.load(request.json)`` on.
+
+Conventions
+-----------
+
+* Field names are ``snake_case``.
+* All response models opt into ``ConfigDict(extra="forbid")`` so
+  the client can rely on the documented field set -- a typo in
+  the server code triggers a serialization error instead of
+  silently shipping a malformed payload.
+* The plan calls for ``InfoResponse.info`` to be a ``dict``,
+  but :attr:`aggregate.distributions.Aggregate.info` is a
+  multi-line string. We expose the string verbatim; clients can
+  display it monospaced. A future structured form is a v1.1
+  enhancement.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ----------------------------------------------------------------------
+# Shared response config
+# ----------------------------------------------------------------------
+# Pulled out into a constant so every response model uses identical
+# settings. ``extra="forbid"`` enforces that response models only
+# carry declared fields (catches accidental leakage of internal data).
+_RESPONSE_CFG = ConfigDict(extra="forbid")
+
+# A combined ratio, expected loss over premium. The library's own rule, which
+# this mirrors so a bad value is a 422 from the edge rather than a ValueError
+# from inside the build: "a positive finite number". No upper bound, because a
+# ratio above 1 is a cover priced below its expected loss, which is a thing a
+# reader may legitimately want to look at.
+_Ratio = Annotated[float, Field(gt=0, allow_inf_nan=False)]
+
+
+# ======================================================================
+# Objects -- POST /v1/objects and friends
+# ======================================================================
+
+class BuildRequest(BaseModel):
+    """Body for ``POST /v1/objects``.
+
+    ``log2`` and ``bs`` are optional -- the underlying ``build()``
+    will choose sensible defaults when they're omitted.
+    """
+
+    decl: str = Field(..., min_length=1, description="DecL source text.")
+    log2: int | None = Field(
+        None,
+        ge=4,
+        description="log2 of the FFT grid size. None means 'let the library pick'.",
+    )
+    bs: float | None = Field(
+        None,
+        gt=0,
+        description="Bucket size. None means 'let the library pick'.",
+    )
+
+
+class ExhibitCapability(BaseModel):
+    """One exhibit an object can serve, as the capability block reports it."""
+
+    model_config = _RESPONSE_CFG
+
+    name: str
+    title: str
+    # ``raw`` / ``insurer``; the two with a 1.0 implementation. An exhibit whose
+    # predicate fails is absent from the list rather than present with none.
+    perspectives: list[str] = []
+
+
+class Capability(BaseModel):
+    """What this object can answer, computed by the library, never declared.
+
+    Rides inline on the build response rather than answering a second request,
+    because the navigation has to paint immediately and a round trip per build
+    to learn the menu is a round trip too many. ``exhibits`` is the same payload
+    ``GET /v1/objects/{id}/exhibits`` serves, from the same helper.
+
+    Two facts are deliberately **not** here. ``kind`` and ``has_reins`` already
+    ride on the build response, and one field per fact is the point of the
+    block: the app's two hand-written per-kind tables died so that nothing says
+    the same thing twice.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    exhibits: list[ExhibitCapability] = []
+    charts: list[str] = []
+    # Which of `charts` is the object's own picture, which is what the Overview
+    # Plot leaf draws. `charts` answers what *can* be drawn (a reinsured
+    # aggregate answers two things); this answers which one to draw with no
+    # other instruction. None where nothing claims the object, and the app then
+    # says the picture does not exist yet.
+    primary_chart: str | None = None
+    # Flags for the leaves that are app behavior rather than a library
+    # document; each names its consumer in ``capability.py``.
+    has_premium: bool = False
+    # The premium itself, for the Evaluate form to prefill. `has_premium` is the
+    # yes or no the PnL form asks; this is the number, and null wherever that
+    # flag is false, so the two cannot disagree.
+    premium: float | None = None
+    can_sharpen: bool = False
+    # Whether a probe has already **run**, which is a different question from
+    # whether running one is worth offering: an object can answer True to both.
+    # Gates the More group's Sharpen leaf, since `sharpen_df` is None until then.
+    has_sharpen: bool = False
+    can_pnl: bool = False
+    # Can the wrap write each ceded premium as a `rate` clause? `can_pnl` plus
+    # the installed library accepting `pnl_program(premium_style=)`, which is an
+    # upstream ask; the two rate menu items grey off this until it ships.
+    can_pnl_rate: bool = False
+    # Can the Pentagon figure be drawn? A P&L, plus a library serving
+    # `pentagon_df`, which landed upstream at 1.0.0a393. A flag rather than an
+    # exhibit gate because the figure is a bespoke SVG this app draws, not a
+    # library document.
+    can_pnl_pentagon: bool = False
+    # Can one press produce the exploded P&L? A non-P&L answers when it can
+    # wrap and its engine is a single aggregate; a P&L answers through
+    # `can_explode`. Gates the xPnL menu item.
+    can_xpnl: bool = False
+    # Can this P&L be walked layer by layer? The explode route's own gate: a
+    # `pnl` over a single aggregate, so False once exploded and False over a
+    # portfolio engine.
+    can_explode: bool = False
+    # Can the object's realized grid be pinned into its own `hints{}`? Gates the
+    # action row's Hints button. True for exactly an Aggregate and a Portfolio
+    # today, the same pair as `can_pnl`, and kept separate because they answer
+    # different questions.
+    can_hints: bool = False
+    can_reins: bool = False
+    # Can the program be re-read as a gross / ceded / net pair? Gates the action
+    # row's GCN control. Narrower than `can_reins` and than `has_reins`: the
+    # three view prefixes build the joint *per-occurrence* aggregate, so an
+    # occurrence cession is required, not merely some cession.
+    can_views: bool = False
+    # Which calibration bases the reins pricing form may offer, known at build
+    # time so the buttons the object cannot answer grey rather than 400. Empty
+    # for an object with no cession.
+    reins_bases: list[str] = []
+    can_price: bool = False
+    can_evaluate: bool = False
+    can_bounds: bool = False
+    can_allocate: bool = False
+    # Are there parts to split one premium across: the units of a book, or the
+    # two halves of an occurrence program? Gates the Pricing group's Allocate
+    # leaf. A near neighbor of `can_allocate` and a different question: that one
+    # is the Bounds group's per-unit range and is a portfolio alone.
+    can_natural_allocation: bool = False
+    needs_premium: bool = False
+
+
+class Quantile(BaseModel):
+    """One probability and the loss at it, exact and rounded.
+
+    Both, because they answer different questions. ``snapped`` is what the
+    reinsurance quick-edit form writes into a program a person then reads, and
+    a layer is quoted at three significant figures; ``q`` is what anyone
+    checking the arithmetic wants.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    p: float
+    q: float
+    snapped: float
+
+
+class QuantilesResponse(BaseModel):
+    """Quantiles at the requested probabilities, in the order asked."""
+
+    model_config = _RESPONSE_CFG
+
+    quantiles: list[Quantile]
+
+
+class Component(BaseModel):
+    """One half of an object built from a pair: its grid and its moments.
+
+    A ``BivariateAggregate`` measures a grid per axis, so ``bs`` and ``log2``
+    are two numbers rather than one and the scalar headline fields cannot
+    carry them. This is what the status strip reads to print
+    ``bs = (a, b) · log2 = (m, n)``.
+
+    Every field is optional because a component is an ordinary ``Aggregate``
+    read through ``getattr``, and a kind that does not carry a moment reports
+    ``None`` rather than raising.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    name: str
+    bs: float | None = None
+    log2: int | None = None
+    mean: float | None = None
+    cv: float | None = None
+
+
+class BuildResponse(BaseModel):
+    """Slim response so the post-build page doesn't pay for unused data.
+
+    The SPA's per-button buttons (info, summary, plot, etc.) each
+    hit their own endpoint. With ``cached=True`` the data calls are
+    O(1) -- effectively the same as if the build returned everything
+    eagerly, minus the wasted serialization.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    id: str
+    # The parser's own kind vocabulary. ``bvagg`` (not ``bivariate``) because
+    # where the api and the library disagree on a name, the library wins.
+    kind: Literal["agg", "port", "sev", "distortion", "bvagg", "pnl"]
+    name: str
+    warnings: list[str] = []
+    cached: bool
+    elapsed_ms: int
+    # Headline stats for the SPA's one-line build summary. Optional so a
+    # future object kind without these accessors still serializes. ``bs`` and
+    # ``log2`` are the *resolved* grid (the library's auto-pick when the
+    # request said "auto"), and they belong together: bs alone says how fine
+    # the grid is and log2 says how far it reaches, so a reader given one of
+    # them cannot tell whether the window covers the distribution.
+    bs: float | None = None
+    log2: int | None = None
+    mean: float | None = None
+    cv: float | None = None
+    validation: str | None = None
+    # Does this object carry a cession? Two consumers: the SPA greys out the
+    # Reins tab when it does not (rather than opening a pane that says "no
+    # reinsurance on this object"), and it decides whether Price offers the
+    # gross / net basis selector. Cheap: read off the cession specs, never off
+    # ``reins_summary_df``, which would materialize a frame on every build.
+    has_reins: bool = False
+    # The largest occurrence limit the program declares, or ``None`` where the
+    # cover is unlimited or the kind declares none. Rides here rather than on
+    # ``/meta`` for the reason the note and the tags do: the Quick Re row caps
+    # its tower at the policy limit, so it needs the number on every build and
+    # not only while one pane is open. See ``layer_pricing.policy_limit``.
+    policy_limit: float | None = None
+    # The loss / payoff sign convention, on every object that has one.
+    #
+    # a57 sent it only for ``'payoff'``, to keep the status strip's first line
+    # from spending a word to say "normal". The result was that it printed for
+    # nothing: an ``Aggregate`` and a ``Portfolio`` both answer ``'loss'`` and
+    # were suppressed, and a ``PnL`` carries no ``value_type`` at all, so the
+    # field the author asked for never once appeared. ``None`` now means the
+    # kind has no orientation to report, not that its orientation is ordinary.
+    value_type: str | None = None
+    # The program's ``note{}`` body, verbatim, or ``None`` when it has none (or
+    # the kind carries no note at all), and its ``tags{}``. The status strip
+    # prints both under the facts line on every build, which is why they ride on
+    # the build response rather than being fetched from ``/meta``: that route was
+    # asked for once per object and only while the Overview group was open, so
+    # material the reader is meant to see whatever they are looking at could not
+    # come from there. The Overview header that did read it is gone at a120.
+    note: str | None = None
+    tags: list[str] = []
+    # Per-component grid and moments, for an object built from a pair. Empty
+    # for every kind but ``bvagg``, whose ``bs`` is genuinely two numbers (one
+    # grid per axis) and whose scalar fields above are therefore all ``None``.
+    #
+    # Additive on purpose: widening ``bs`` / ``log2`` / ``mean`` / ``cv`` to
+    # "scalar or pair" would change the shape every consumer reads, for one
+    # kind's benefit. See ``routes.objects._component_fields``.
+    components: list[Component] = []
+    # What this object can answer. The SPA paints its navigation from this and
+    # holds no per-kind table of its own.
+    capability: Capability = Field(default_factory=Capability)
+
+
+class ValueResponse(BaseModel):
+    """A program that means a number, from ``POST /v1/objects``.
+
+    DecL's top-level ``answer`` rule carries ``expr``, so ``(2+2)``, ``2/3``,
+    ``(2**10)`` and ``(exp(1))`` are programs like any other and ``build()``
+    answers each with a float. The api used to build them and then refuse the
+    result at the classify step, with "api supports 'agg', 'port', ... only; got
+    'float'". Serving it instead is the purist reading rather than an exception
+    to it: the library owns what a program means, including when it means a
+    number.
+
+    Notes
+    -----
+    Almost none of :class:`BuildResponse` applies. There is no object, so no
+    ``id`` to fetch panes against, no grid, no capability block and no cache
+    slot; a discriminated union on ``kind`` says that in the schema rather than
+    leaving a caller to read six null fields and infer it.
+
+    The float travels raw. The app formats it with the same helper that prints
+    ``mean`` and ``cv`` off a build, which arrive equally bare, so no format is
+    invented here for a number the library hands over without one.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    kind: Literal["value"] = "value"
+    value: float = Field(..., description="What the program evaluates to.")
+    decl: str = Field(..., description="The program, as the collapse left it.")
+    elapsed_ms: int
+
+
+class LayerRequest(BaseModel):
+    """One layer to quote, in the vocabulary the Quick Re row speaks.
+
+    The span is given as the two amounts it resolved to rather than as the
+    probabilities it was typed as: resolving a percentage is the quantiles
+    route's job and the row has already been there, so sending the probability
+    again would ask the server to redo a lookup whose answer the caller is
+    holding. ``limit`` admits no infinity through JSON, so an unlimited cover
+    is spelled by omitting it.
+    """
+
+    tier: Literal["occurrence", "aggregate"] = Field(
+        "occurrence",
+        description="Which distribution the layer is cut out of.",
+    )
+    attach: float = Field(..., ge=0.0, allow_inf_nan=False)
+    limit: float | None = Field(
+        None, gt=0.0, allow_inf_nan=False,
+        description="Width of the layer. Omit for an unlimited cover.",
+    )
+    share: float = Field(1.0, gt=0.0, le=1.0, allow_inf_nan=False)
+
+
+class LayerIndicationRequest(BaseModel):
+    """Body for ``POST /v1/objects/{id}/layers/indication``."""
+
+    layers: list[LayerRequest] = Field(
+        ..., min_length=1, max_length=64,
+        description="The layers to quote, answered in the order given.",
+    )
+    cede: float = Field(0.0, ge=0.0, lt=1.0)
+
+
+class LayerIndication(BaseModel):
+    """The no-build quote for one layer.
+
+    Every figure is a reading of the gross object's own distributions, so the
+    whole response costs no build and is cheap enough for a preview line that
+    recomposes on every settled keystroke.
+
+    ``premium`` is the indication itself. There is no second field for it: the
+    full press can only revise this number upward, never replace it with
+    something unrelated, so one number is the whole answer.
+
+    ``cv``, ``lol``, ``rol`` and ``loss_ratio`` are optional because a capacity
+    layer above the severity limit has no expected loss to divide by, and an
+    unlimited layer has no rate-on-line base. ``count`` is the expected number
+    of claims reaching the layer and is occurrence only: on the aggregate tier
+    the layer is pierced by the year's total, so a claim count to it means
+    nothing.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    tier: str
+    attach: float
+    # Null on an unlimited cover, the same way the request spells one.
+    limit: float | None = None
+    share: float
+    el: float
+    sd: float
+    cv: float | None = None
+    count: float | None = None
+    pr_attach: float
+    lol: float | None = None
+    floored: bool
+    premium: float
+    rol: float | None = None
+    spelling: str
+    cede: float
+    loss_ratio: float | None = None
+
+
+class LayerIndicationResponse(BaseModel):
+    """One indication per layer, in the order asked."""
+
+    model_config = _RESPONSE_CFG
+
+    indications: list[LayerIndication]
+
+
+class LayerQuote(LayerIndication):
+    """One layer's full quote, with the four candidates behind it.
+
+    The components ride along rather than only the winner, because which
+    measure bound is the interesting part: the dual transform loads the body of
+    a distribution and binds low in a tower, the proportional hazard transform
+    loads the tail and binds high. ``binds`` is ``'sd'``, ``'ph'``, ``'dual'``
+    or ``'min_rol'``.
+
+    ``min_rol`` is the minimum-rate-on-line premium, which is the fourth
+    candidate rather than a floor applied after the comparison, so ``binds``
+    names it where it set the price. Null on an unlimited layer, which has no
+    rate-on-line base and competes on three.
+
+    ``label`` is the layer's ``as "..."`` name where the clause carried one, and
+    otherwise ``Occ n`` / ``Agg n``, numbered within its own tier in clause
+    order. It is the quote sheet's first column, so a row says which tier the
+    layer sits on and where in the stack it is, which the span alone does not.
+    The fallback is the sheet's and not the program's: the clause keeps the
+    spec's own naming.
+    """
+
+    sd_load: float
+    ph: float
+    dual: float
+    min_rol: float | None = None
+    binds: str
+    label: str = ""
+
+
+class DerivedResponse(BuildResponse):
+    """A derivation's result: the program that made it, and the object.
+
+    The build manifest plus the DecL text that produced it, because every
+    derivation in this app is a program you can see. The text lands in the
+    editor, so you read what was built, you can edit it, and history, sharing
+    and rebuild all keep working. No hidden state, and no object mutated behind
+    a cached id.
+
+    ``id`` is the id an ordinary build of ``program`` would produce, so
+    rebuilding the text from the editor is a cache hit rather than a second
+    build.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    program: str = Field(..., description="The DecL that builds this object.")
+    description: str | None = Field(
+        None,
+        description=(
+            "What the derivation did, when it has something to say. Sharpen "
+            "fills it with the probe's verdict; the others leave it empty."
+        ),
+    )
+    quotes: list[LayerQuote] | None = Field(
+        None,
+        description=(
+            "The per-layer quote behind a priced cession, in the order the "
+            "clause spells it. Only a cession asked to price carries this; "
+            "every other derivation leaves it empty."
+        ),
+    )
+    ir: dict[str, Any] | None = Field(
+        None,
+        description=(
+            "Table document for the quote sheet, keyed 'quotes'. Carried the "
+            "way BoundsResponse carries its own, so the SPA can render the "
+            "rows in whichever table view the page is set to."
+        ),
+    )
+
+
+class PnlProgramRequest(BaseModel):
+    """Body for ``POST /v1/objects/{id}/pnl``.
+
+    Every field here is a convention rather than a fact, which is why the
+    library puts them in the signature where a caller reads them, and why they
+    are request fields rather than server settings. The button posts an empty
+    body and takes all five defaults, so this model is where the app's opinion
+    about a demo book is written down, documented and tested.
+
+    Notes
+    -----
+    **Three of the five defaults are the app's own**, and diverge from the
+    library's deliberately. Upstream, all three combined ratios default to
+    ``None``, which means "behave exactly as before" and leaves any cession
+    unpriced. This endpoint exists to serve one app whose PnL button is demo
+    sugar, so it defaults to a priced book: a 90 percent net combined ratio,
+    occurrence cover at 75 and aggregate cover at 65. ``loss_ratio`` and
+    ``expense_ratio`` match the library's own defaults exactly, and a test
+    holds all five field names to the library's signature so the two cannot
+    drift apart unnoticed.
+
+    **The ladder makes ``loss_ratio`` legacy.** With a combined ratio in hand
+    the premium is built from the bottom up, net technical premium plus the
+    cost of each cover, grossed up once for expenses, so ``loss_ratio`` is used
+    only when the ladder is off, which for this endpoint means a portfolio
+    engine. See ``aggregate`` 1.0.0a306, ``dev/done/plan-pnl-reinsurance-pricing.md``.
+
+    **Ceded premiums are written as ``deposit`` amounts by default.**
+    ``premium_style='rate'`` asks the library to spell each priced layer's
+    premium as a ``rate`` of the P&L's stated gross premium instead. That is
+    not the circularity the ladder refuses on its *inputs* (a layer arriving
+    with a ``rate`` clause quotes a fraction of a premium the ladder has not
+    computed yet); here the ladder has finished and the rate is a respelling
+    of the resolved deposit. The keyword is an upstream ask, so the route
+    refuses ``'rate'`` with a 400 until the installed library's signature
+    accepts it; see ``capability.PNL_PREMIUM_STYLE_SUPPORTED``.
+
+    **``form`` and ``premium_style`` are the app's routing, not library
+    kwargs** (``premium_style`` becomes one when it ships). ``form='xpnl'``
+    runs the wrapped program through the same explode machinery the explode
+    route uses, so one press answers "the exploded P&L of what is in the box".
+    """
+
+    form: Literal["pnl", "xpnl"] = Field(
+        "pnl",
+        description=("Which keyword leads the derived program: 'pnl' for the "
+                     "consolidated wrap, 'xpnl' to wrap and break the book out "
+                     "layer by layer. 'xpnl' refuses a portfolio engine."))
+    premium_style: Literal["deposit", "rate"] = Field(
+        "deposit",
+        description=("How each priced layer's premium is written: a 'deposit' "
+                     "amount, or a 'rate' of the P&L's stated gross premium. "
+                     "'rate' needs a library whose pnl_program accepts "
+                     "premium_style and is refused with a 400 otherwise."))
+
+    loss_ratio: float = Field(
+        0.70, gt=0, le=1,
+        description=("Sizes the premium as expected loss over this, when there is none to "
+                     "derive from. Unused once the combined-ratio ladder is engaged."))
+    expense_ratio: float = Field(
+        0.25, ge=0, lt=1,
+        description="Gross expense as a fraction of premium; 0 omits the clause.")
+    net_combined_ratio: _Ratio | None = Field(
+        0.90,
+        description=("Expected net loss over net technical premium. Engages the ladder, "
+                     "which prices every cession; null leaves cessions unpriced."))
+    occ_combined_ratio: _Ratio | list[_Ratio] | None = Field(
+        0.75,
+        description=("The occurrence tier's combined ratio: one value, or one per layer in "
+                     "declaration order. Null means the net ratio."))
+    agg_combined_ratio: _Ratio | list[_Ratio] | None = Field(
+        0.65,
+        description=("The aggregate tier's combined ratio, one value or one per layer. "
+                     "Null means the net ratio."))
+
+
+class NarrativeSection(BaseModel):
+    """One heading in the Narrative pane: a short form and a long one."""
+
+    model_config = _RESPONSE_CFG
+
+    name: str
+    description: str = ""
+    explanation: str = ""
+
+
+class NarrativeResponse(BaseModel):
+    """``GET /v1/objects/{id}/narrative``: everything the object says in prose.
+
+    The ``info`` block first, then a section per text field the object carries.
+    Sections are found by suffix rather than listed, so a narrative the library
+    adds upstream appears here on its own.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    info: str = ""
+    sections: list[NarrativeSection] = []
+
+
+class BoundsRequest(BaseModel):
+    """Body for the two tabular bounds routes.
+
+    ``premium`` is the calibration: the price some distortion puts on this
+    object. Everything reported is the range over the distortions consistent
+    with it, so without a premium there is no question to ask.
+    """
+
+    premium: float = Field(..., gt=0, description="Target premium for this object.")
+    assets: float | None = Field(
+        None, gt=0,
+        description="Asset cap; prices min(X, a). Unbounded when omitted.")
+    against: list[str] = Field(
+        default_factory=list,
+        description=("PricingBounds only: the risks to price against this one. "
+                     "Each is a unit of the current portfolio, or a DecL "
+                     "fragment for a line that does not exist yet. Empty on a "
+                     "portfolio means every unit, which is the question a "
+                     "portfolio invites; an aggregate has no units, so empty "
+                     "there is an error."),
+    )
+
+
+class BoundsResponse(BaseModel):
+    """A bounds table: one row per unit or per named risk.
+
+    ``lower`` and ``upper`` are the ends of the consistent range and ``width``
+    is the reading, being how much of the price is decided by the choice of
+    distortion rather than by the premium the object was calibrated to.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    premium: float
+    table: FrameResponse
+    ir: dict[str, Any] | None = Field(
+        None,
+        description="Table document for the static view, keyed 'table'.",
+    )
+
+
+class ReinsProgramRequest(BaseModel):
+    """Body for ``POST /v1/objects/{id}/reins``.
+
+    ``cession`` is one clause per tier, each opening with ``occurrence`` or
+    ``aggregate``. A clause is authoritative for its own tier and leaves the
+    other alone, which is how the grammar reads it too, so composing an
+    occurrence and an aggregate cession means sending both rather than sending
+    one and then ceding again.
+    """
+
+    cession: str | list[str] = Field(
+        ...,
+        description=("A cession clause, or one per tier: "
+                     "'occurrence net of 500 xs 500'."),
+    )
+    price: bool = Field(
+        False,
+        description=("Quote every layer and write the premium into the clause, "
+                     "as a 'deposit' or a 'rol'. Costs one small auxiliary "
+                     "build per layer."),
+    )
+    cede: float = Field(
+        0.0, ge=0.0, lt=1.0,
+        description=("Ceding commission. The quote is the reinsurer's net, so "
+                     "the written premium is grossed up by 1 / (1 - cede)."),
+    )
+
+
+class ObjectSummary(BaseModel):
+    """One row in ``GET /v1/objects`` (cache listing)."""
+
+    model_config = _RESPONSE_CFG
+
+    id: str
+    kind: str
+    name: str
+    ts: str  # ISO 8601
+
+
+class ObjectListResponse(BaseModel):
+    """Wrapper for ``GET /v1/objects``."""
+
+    model_config = _RESPONSE_CFG
+
+    objects: list[ObjectSummary]
+
+
+class ObjectManifest(BaseModel):
+    """``GET /v1/objects/{id}`` -- metadata about a single cached object."""
+
+    model_config = _RESPONSE_CFG
+
+    id: str
+    kind: str
+    name: str
+    decl: str
+    log2: int
+    bs: float
+    created_at: str  # ISO 8601
+
+
+class DeleteResponse(BaseModel):
+    model_config = _RESPONSE_CFG
+
+    ok: bool
+
+
+# ======================================================================
+# Tabular endpoints -- summary / stats_df / density_df / kappa
+# ======================================================================
+
+class FrameResponse(BaseModel):
+    """Pandas DataFrame as ``(columns, rows)``.
+
+    Rows are list-of-lists rather than list-of-dicts so a wide
+    density_df (50+ columns, 2**16+ rows) doesn't redundantly carry
+    the column name string with every cell. Trim payload by an
+    order of magnitude vs the dict-per-row form.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    columns: list[str]
+    rows: list[list[Any]]
+
+
+# ======================================================================
+# Info -- raw multi-line string from Aggregate.info / Portfolio.info
+# ======================================================================
+
+class InfoResponse(BaseModel):
+    model_config = _RESPONSE_CFG
+
+    info: str
+
+
+class ObjectMetaResponse(BaseModel):
+    """``GET /v1/objects/{id}/meta`` -- the object's own DecL metadata.
+
+    The trailer clauses a first-class citizen carries (``note`` / ``tags`` /
+    ``hints``) plus the two program renderings. Those three are the whole
+    trailer since ``aggregate`` 1.0.0a301.
+
+    ``program`` is what the parser was handed, after preprocessing (folded onto
+    one line, comments stripped), not the user's keystrokes. ``pprogram`` is
+    what the parser understood, re-rendered canonically, and is the one to show
+    a reader.
+
+    Every field is optional. They are read through ``getattr`` so a class that
+    does not carry one reports ``None`` rather than raising.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    kind: str
+    name: str
+    note: str | None = None
+    tags: list[str] = []
+    hints: str | None = None
+    program: str | None = None
+    pprogram: str | None = None
+
+
+# ======================================================================
+# Reinsurance -- text description block
+# ======================================================================
+
+class ReinsDescriptionResponse(BaseModel):
+    """``GET /v1/objects/{id}/reins_description``.
+
+    ``available`` is False (and ``text`` empty) when the object carries
+    no reinsurance, so the SPA can show a neutral "no reinsurance on this
+    object" line rather than an error.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    available: bool
+    text: str
+
+
+# ======================================================================
+# Pricing
+# ======================================================================
+
+class PricingPreviewRequest(BaseModel):
+    """Body for ``POST /v1/objects/{id}/pricing/preview``.
+
+    The same anchor and target the calibration takes, because the preview's job
+    is to say what that calibration is about to be struck at. ``basis`` names the
+    reinsurance view for a reinsured Aggregate and is rejected elsewhere.
+    """
+
+    p: float | None = Field(
+        None, gt=0, le=1, description="VaR probability in (0, 1] fixing capital.")
+    a: float | None = Field(
+        None, gt=0, description="Asset level fixing capital; snapped to the grid.")
+    coc: float | None = Field(None, gt=0, description="Cost-of-capital (ROE) target.")
+    lr: float | None = Field(None, gt=0, description="Loss-ratio target.")
+    premium: float | None = Field(
+        None, gt=0, description="Premium target; the pentagon's ``P``.")
+    basis: str | None = Field(
+        None, description="Reinsurance view: 'gross', 'net occ' or 'net'.")
+    expense_ratio: float | None = Field(
+        None, ge=0, lt=1,
+        description=("Gross expense as a fraction of premium. A premium "
+                     "target is read as gross and the pentagon runs on "
+                     "premium × (1 − e); the response reports gross_premium. "
+                     "Refused for a P&L, whose ledger states its own "
+                     "expenses."))
+
+
+class PricingPreviewResponse(BaseModel):
+    """The completed pentagon as scalars, for the Calibrate form's preview line.
+
+    The octet under wire names: ``loss``, ``margin``, ``premium``, ``capital``
+    and ``assets`` are the five levels (``L``, ``M``, ``P``, ``Q``, ``a``), and
+    ``lr``, ``pq``, ``coc`` the three ratios between them. ``p`` echoes the
+    probability the caller named, and is null when they anchored on assets.
+
+    ``premium`` is always the technical premium, net of expenses. The three
+    fields after the octet are the gross story. ``gross_premium`` rides when the
+    request carried an ``expense_ratio`` (the resolved technical premium grossed
+    back up) and on a P&L, where it is the ledger's own stated gross.
+    ``net_premium`` and ``net_of_expense_premium`` are a P&L's only, ``P`` and
+    ``P − E`` off the ledger's **closing** block: the position once every tier's
+    program has worked, which is what a reader looking at a peeled P&L is
+    pricing. Both are null everywhere else. On a single-group ledger the closing
+    block is the gross block and all three agree.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    p: float | None = None
+    assets: float | None = None
+    loss: float | None = None
+    margin: float | None = None
+    premium: float | None = None
+    capital: float | None = None
+    lr: float | None = None
+    pq: float | None = None
+    coc: float | None = None
+    gross_premium: float | None = None
+    net_premium: float | None = None
+    net_of_expense_premium: float | None = None
+
+
+class PnLPentagonRequest(BaseModel):
+    """Body for ``POST /v1/objects/{id}/pnl/pentagon``.
+
+    One field, and it is a **list**, which is the whole shape of the request.
+    The Pentagon leaf's control is a strip of mini pentagons, one per solvency
+    level, each labeled with the assets that level implies, and the reader picks
+    from what they can already see. So the answer has to carry every level at
+    once: serving one and re-asking on each press would mean the strip could
+    not label itself until the reader had pressed all six.
+    """
+
+    periods: list[float] | None = Field(
+        None, min_length=1, max_length=12,
+        description=("Return periods to answer at, so the 1-in-t state fixes "
+                     "capital on each. Defaults to the strip's own six. Each "
+                     "must exceed 1."))
+
+
+class PnLPentagonLevel(BaseModel):
+    """One solvency level's pentagon: the level, and the frame struck at it."""
+
+    model_config = _RESPONSE_CFG
+
+    t: float
+    frame: FrameResponse
+
+
+class PnLPentagonResponse(BaseModel):
+    """``POST /v1/objects/{id}/pnl/pentagon`` -- the ledger as a pentagon.
+
+    One entry per requested level, in the order asked for, so the first is the
+    strip's default. Each frame is ``PnL.pentagon_df`` with its index reset, so
+    ``Step`` is the first column: the figure picks ``Gross``, ``Ceded`` and
+    ``All`` and ignores the rest, which are the ledger's own steps and are what
+    a future stepper would walk.
+
+    The amounts are in the object's own currency units and the ratios are
+    fractions. Nothing here is formatted: the browser owns presentation, as it
+    does for every table in the app.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    levels: list[PnLPentagonLevel]
+
+
+class PricingCalibrateRequest(BaseModel):
+    """Body for ``POST /v1/objects/{id}/pricing/calibrate``.
+
+    Exactly one capital anchor (``p`` or ``a``) and exactly one pricing target
+    (``coc``, ``lr`` or ``premium``). The library owns the loss-ratio
+    conversion, so ``lr`` travels as itself rather than being turned into a cost
+    of capital here.
+
+    ``premium`` is the third target since 1.0.0a100, because
+    :meth:`price_pentagon` has always taken one and the Bounds forms ask the
+    same question in that spelling. It costs one extra library call: see
+    :func:`aggregate_api.pricing.run_calibration`.
+    """
+
+    p: float | None = Field(
+        None, gt=0, le=1, description="VaR probability in (0, 1] fixing capital.")
+    a: float | None = Field(
+        None, gt=0, description="Asset level fixing capital; snapped to the grid.")
+    coc: float | None = Field(None, gt=0, description="Cost-of-capital (ROE) target.")
+    lr: float | None = Field(None, gt=0, description="Loss-ratio target.")
+    premium: float | None = Field(
+        None, gt=0, description="Premium target; the pentagon's ``P``.")
+    basis: str | None = Field(
+        None, description="Calibration basis: 'gross', 'net occ' or 'net'.")
+    expense_ratio: float | None = Field(
+        None, ge=0, lt=1,
+        description=("Gross expense as a fraction of premium. A premium "
+                     "target is read as gross and the fit runs on "
+                     "premium × (1 − e); a CoC or LR target is unaffected."))
+
+
+class PricingAllocateRequest(PricingCalibrateRequest):
+    """Body for ``POST /v1/objects/{id}/pricing/allocate``.
+
+    The calibrate shape exactly, because the allocation is a calibration that is
+    then decomposed: the same anchor and the same target, struck once and split
+    across the parts. It is a separate model rather than a reuse so the basis
+    field can carry the narrower rule this route enforces.
+
+    ``basis`` is gated. The natural allocation splits a **gross** premium across
+    an occurrence program, so an ``Aggregate`` takes ``gross`` or nothing;
+    anything else is an HTTP 400. A ``Portfolio`` takes ``net`` or nothing, the
+    one basis a book answers end to end, matching the row the Calibrate form
+    offers it.
+    """
+
+    basis: str | None = Field(
+        None,
+        description=("Calibration basis: 'gross' for an Aggregate, 'net' for a "
+                     "Portfolio. Omit to take the object's own."),
+    )
+
+
+class PricingEvaluateRequest(BaseModel):
+    """Body for ``POST /v1/objects/{id}/pricing/evaluate``.
+
+    Every field is optional and every field is refused for a P&L, which carries
+    its premium in its ledger and evaluates each row on that row's own terms.
+    ``basis`` names **which premium is being input** on a reinsured Aggregate,
+    which is a narrower question than the gross versus net comparison the
+    Economics group answers.
+    """
+
+    premium: float | None = Field(
+        None,
+        gt=0,
+        description=(
+            "The consideration held against this position. Omit to use the "
+            "object's own; rejected for a P&L, whose ledger carries it."
+        ),
+    )
+    basis: str | None = Field(
+        None,
+        description=("Which premium this is: 'gross', 'net occ' or 'net'. "
+                     "A reinsured Aggregate only."),
+    )
+    p: float | None = Field(
+        None, gt=0, le=1,
+        description="VaR probability fixing the asset level the panel is solved at.")
+    a: float | None = Field(
+        None, gt=0, description="Asset level the panel is solved at.")
+    expense_ratio: float | None = Field(
+        None, ge=0, lt=1,
+        description=("Gross expense as a fraction of premium. A typed "
+                     "premium is read as gross and evaluated at "
+                     "premium × (1 − e). Refused for a P&L, whose ledger "
+                     "states its own expenses."))
+
+
+class PricingExhibitsResponse(BaseModel):
+    """One or more library exhibits, each under both perspectives.
+
+    The shape all three of ``pricing/calibrate``, ``pricing/allocate`` and
+    ``pricing/evaluate`` answer with. ``exhibits`` maps the registry name
+    (``pricing.calibrate``, ``pricing.stand_alone``, ``pricing.allocate``,
+    ``pricing.evaluate``) to a map of perspective to envelope, the same envelope
+    ``GET /objects/{id}/exhibit/{name}`` serves.
+
+    Bundling both perspectives is deliberate. The frames are small, the pane's
+    RAW / INSURER toggle then flips with no recompute, and the alternative would
+    be caching a result object server side so a second request could answer the
+    other reading of a calibration that has already been made.
+
+    ``warnings`` carries what the library said on the way, verbatim. A distortion
+    it declines to allocate is the standing case: the table shows the families
+    that answered and this says which one did not, and why.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    kind: str
+    exhibits: dict[str, dict[str, Any]]
+    warnings: list[str] = []
+
+
+class RuinRequest(BaseModel):
+    """Body for ``POST /v1/objects/{id}/ruin``.
+
+    The premium half is the Calibrate shape exactly: one capital anchor
+    (``p`` or ``a``) and one pricing target (``coc``, ``lr`` or ``premium``),
+    from which the runner derives the loss ratio the ruin engine takes,
+    through :meth:`price_pentagon` where the target is not already a loss
+    ratio. There is no ``basis``: the ruin reading is of the object's own
+    law, and a margin struck on another view would price a different
+    distribution than the one being simulated.
+
+    ``ruin_p`` is the initial capital, entered as a probability of eventual
+    default and resolved to a surplus through the ruin function's capital
+    lookup; ``u`` states the surplus directly. At most one travels; with
+    neither, the library's teaching default applies. The name is not ``p``
+    because ``p`` is already the VaR anchor everywhere on this surface.
+
+    ``sample`` is the Sample action: the server draws one fresh integer
+    seed, uses it for both the chart and the exhibit so they describe the
+    same draw, and reports it in the chart document's ``meta``. It is a
+    flag rather than ``seed: null`` because a typed model cannot tell an
+    omitted field from an explicit null on the wire.
+    """
+
+    p: float | None = Field(
+        None, gt=0, le=1, description="VaR probability in (0, 1] fixing capital.")
+    a: float | None = Field(
+        None, gt=0, description="Asset level fixing capital; snapped to the grid.")
+    coc: float | None = Field(None, gt=0, description="Cost-of-capital (ROE) target.")
+    lr: float | None = Field(None, gt=0, description="Loss-ratio target.")
+    premium: float | None = Field(
+        None, gt=0, description="Premium target; the pentagon's ``P``.")
+    ruin_p: float | None = Field(
+        None, gt=0, lt=1,
+        description=("Probability of eventual default; resolved to an initial "
+                     "surplus through the ruin function's capital lookup."))
+    u: float | None = Field(
+        None, ge=0, description="Initial surplus directly. At most one of "
+                                "``ruin_p`` or ``u``.")
+    seed: int | None = Field(
+        None, ge=0,
+        description=("rng seed for the simulated paths. Omit for the "
+                     "library's fixed teaching seed; ignored when ``sample`` "
+                     "is set."))
+    sample: bool = Field(
+        False,
+        description=("Draw a fresh seed server side and report it in the "
+                     "chart document's ``meta.seed``."))
+    n_plot: int | None = Field(
+        None, ge=1, le=200, description="Sample paths drawn; the library "
+                                        "default is 50.")
+    detail: int | None = Field(
+        None, ge=16, description="Per-path point budget for the display "
+                                 "decimation.")
+
+
+class RuinResponse(BaseModel):
+    """Answer for ``POST /v1/objects/{id}/ruin``.
+
+    ``chart`` is the ``ruin`` chart document, byte for byte what the generic
+    chart route would serve, parsed so it rides inside a JSON response; its
+    ``meta`` carries the scalars the pane labels itself with (the resolved
+    ``u``, exact and simulated psi, the seed). ``exhibits`` maps ``ruin`` to
+    a perspective-to-envelope pair, the :class:`PricingExhibitsResponse`
+    shape, because the exhibit registers on the
+    :class:`~aggregate.results.RuinResult` the request builds rather than on
+    the cached object.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    kind: str
+    chart: dict[str, Any]
+    exhibits: dict[str, dict[str, Any]]
+    warnings: list[str] = []
+
+
+# ======================================================================
+# DecL helpers
+# ======================================================================
+
+class DeclCompleteRequest(BaseModel):
+    decl: str
+    cursor: int = Field(..., ge=0)
+
+
+class Completion(BaseModel):
+    model_config = _RESPONSE_CFG
+
+    #: What to **insert**: the bare token, always valid DecL on its own.
+    #:
+    #: Added at a67. Editors were inserting ``label``, which for the 38 of 105
+    #: terminals carrying a gloss is a whole phrase and not a token, so
+    #: accepting a completion could put ``after' (profit-commission allowance)``
+    #: into a program. Nothing consuming this should insert anything else.
+    text: str
+    label: str
+    #: The gloss, where the terminal has one: ``or 'approx'``. Display only.
+    detail: str | None = None
+    terminal: str
+    kind: Literal["keyword", "identifier", "literal"]
+
+
+class CompletionsResponse(BaseModel):
+    model_config = _RESPONSE_CFG
+
+    completions: list[Completion]
+
+
+class DeclLexRequest(BaseModel):
+    decl: str
+
+
+class DeclFormatRequest(BaseModel):
+    decl: str
+
+
+class DeclFormatResponse(BaseModel):
+    """``POST /v1/decl/format`` -- canonicalized DecL.
+
+    ``decl`` is the program re-rendered through ``aggregate``'s
+    ``format_program`` (canonical clause order / spacing). On a format
+    failure the original text is echoed back unchanged.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    decl: str
+
+
+class DeclParseRequest(BaseModel):
+    decl: str
+
+
+class ParsedStatement(BaseModel):
+    """One statement of a program, as the parser understood it.
+
+    ``kind`` and ``name`` are the first two members of the
+    ``(kind, name, spec)`` triple ``aggregate``'s parser returns: the object
+    kind the statement declares (``agg``, ``sev``, ``port``, ``pnl``, ``xpnl``,
+    ``distortion``, and so on) and the name it declares it under.
+
+    Notes
+    -----
+    ``spec`` is deliberately an open ``dict``, not a mirrored schema. Its keys
+    are the **library's** vocabulary and they move when the grammar moves, so a
+    typed model here would be a second declaration of the transformer's output:
+    it would drift, and then it would start rejecting specs the library had
+    legitimately grown. The route's whole promise is "what the parser
+    understood, coerced to JSON".
+
+    Two coercions a reader has to know about. A tuple arrives as an array, so a
+    reinsurance layer reads as the three-element ``[share, limit, attach]`` and
+    not as an object. And a non-finite float arrives as the string ``"inf"``,
+    ``"-inf"`` or ``"nan"``, which is both the spelling the grammar accepts and
+    the only form that keeps an unlimited limit distinguishable from an absent
+    one. See :func:`aggregate_api.serializers.spec_to_payload`.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    kind: str
+    name: str
+    spec: dict[str, Any]
+
+
+class DeclParseResponse(BaseModel):
+    """``POST /v1/decl/parse`` -- the parser's answer as data.
+
+    One entry per statement, in source order. Nothing is built, cached or
+    audited on the way.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    statements: list[ParsedStatement]
+
+
+class LexToken(BaseModel):
+    model_config = _RESPONSE_CFG
+
+    type: str
+    value: str
+    start: int
+    end: int
+    line: int
+    column: int
+
+
+class LexResponse(BaseModel):
+    model_config = _RESPONSE_CFG
+
+    tokens: list[LexToken]
+
+
+# ======================================================================
+# Examples (aggregate's library.agg, via the recipe base)
+# ======================================================================
+
+class Pill(BaseModel):
+    """One render-ready label on an example row.
+
+    ``ns`` is the namespace the value came from and is what the SPA colors on:
+    ``kind`` off the recipe index, ``topic`` and ``role`` off the tag slugs. The
+    value is the bare word, so ``topic:reinsurance`` draws as ``reinsurance``,
+    and it is the text inside the pill, which is why a reader who cannot
+    separate the three hues still reads what the pill says.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    ns: Literal["kind", "topic", "role"]
+    value: str
+
+
+class FacetValue(BaseModel):
+    """One value of one facet, with how many of the returned entries carry it."""
+
+    model_config = _RESPONSE_CFG
+
+    value: str
+    count: int
+
+
+class ExampleItem(BaseModel):
+    """One library entry.
+
+    ``note`` is preferred but never guaranteed: most entries carry one, and an
+    entry without a note is ordinary, not defective. ``decl`` is the entry's
+    DecL as its ``.agg`` file spells it (``Recipe.as_read``), several lines,
+    indented as written and carrying its trailer, so it drops straight into the
+    editor teaching the spelling the author chose.
+
+    ``pills`` is the row as it should be drawn, already ordered kind, then
+    topics, then roles. ``tags`` is the same information as full slugs, kept for
+    the search haystack and for anyone reading the api directly, and ``kind``
+    keeps a field of its own because the recipe's type is not a tag.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    name: str
+    kind: str
+    tags: list[str] = []
+    note: str | None = None
+    decl: str
+    pills: list[Pill] = []
+
+
+class ExamplesResponse(BaseModel):
+    """``GET /v1/examples`` -- the whole library, one flat list in file order.
+
+    ``items`` is the library in its own reading order (``Recipe.seq``), each
+    entry appearing exactly once. There are no groups and no headings: the
+    ``# ---`` banners in ``library.agg`` are comments, nothing in ``aggregate``
+    parses them, and reading order is what the file actually carries.
+
+    ``facets`` is keyed by the three pill namespaces, and each list is ordered by
+    first appearance in ``items``, so a filter bar built from it reads in file
+    order too. Counts are over the entries returned, so a filtered payload adds
+    up to what the caller can see.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    items: list[ExampleItem]
+    facets: dict[str, list[FacetValue]]
+
+
+class HeroesResponse(BaseModel):
+    """``GET /v1/examples/heroes`` -- the entries tagged ``role:hero``."""
+
+    model_config = _RESPONSE_CFG
+
+    items: list[ExampleItem]
+
+
+class SparklinesResponse(BaseModel):
+    """``GET /v1/examples/heroes/sparklines`` -- thumbnail silhouettes.
+
+    ``sparklines`` maps an entry name to a short list of values in ``[0, 1]``,
+    the density binned and scaled so its peak is 1. Shape only: there are no
+    axes, no units and no way to read a number off it, which is what a card
+    thumbnail should promise.
+
+    A hero that fails to build is simply absent, so the client must treat a
+    missing key as ordinary and keep its placeholder.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    sparklines: dict[str, list[float]]
+
+
+# ======================================================================
+# Meta / health
+# ======================================================================
+
+class StyleResponse(BaseModel):
+    """``GET /v1/meta/style`` -- the house plot style from ``aggregate.style``.
+
+    Served so the SPA's interactive charts and the server-rendered matplotlib
+    plots share one source for their look. ``colors`` is the ``axes.prop_cycle``
+    color list, in order; ``fig_w`` / ``fig_h`` are the house per-panel figure
+    size in inches (``aggregate.constants.FIG_W`` / ``FIG_H``), whose ratio the
+    SPA uses to shape its own panels.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    colors: list[str]
+    grid_color: str
+    text_color: str
+    line_width: float
+    font_size: float
+    fig_w: float
+    fig_h: float
+
+
+class HealthResponse(BaseModel):
+    model_config = _RESPONSE_CFG
+
+    ok: bool
+    # ``version`` is this api package's version; ``aggregate_version``
+    # is the wrapped library's. Reported separately so a deploy can be
+    # pinned/debugged against both.
+    version: str
+    aggregate_version: str
+
+
+class PluginLeafInfo(BaseModel):
+    """One document a plugin contributes, with the strings the plugin authored.
+
+    Mirrors :class:`aggregate.plugins.PluginLeaf`. The labels ride on the plugin
+    rather than on the chart or exhibit registry entry, because a navigation hint
+    is a client concern and a registry entry is an IR one.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    name: str
+    kind: str
+    label: str
+    hint: str = ""
+    why: str = ""
+
+
+class PluginInfo(BaseModel):
+    """One discovered plugin, whether or not it loaded.
+
+    Notes
+    -----
+    ``error`` is **one line**, not a traceback. The traceback goes to the server
+    log; what a reader needs from the About panel is that a plugin failed and
+    roughly why. Meta already carries five other facts and must not become the
+    place tracebacks accumulate. A failed plugin does have to appear *somewhere*
+    a human looks, or an empty Lab tab becomes a debugging session.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    name: str
+    version: str | None = None
+    source: str
+    leaves: list[PluginLeafInfo] = []
+    error: str | None = None
+
+
+class MetaResponse(BaseModel):
+    model_config = _RESPONSE_CFG
+
+    version: str
+    aggregate_version: str
+    # The static-table engine. Reported because it is a *front-end* version as
+    # much as a backend one: the same install serves the walker the SPA loads
+    # from /v1/assets, so this one number covers both halves.
+    tables_version: str
+    log2_cap: int
+    log2_default: int
+    build_timeout_s: float
+    cache_max: int
+    # Third-party charts and exhibits, and the tab they land under. On meta
+    # rather than on a /v1/plugins route of its own because the SPA already
+    # fetches meta unconditionally at boot, on the very path that has to resolve
+    # before the tab strip can know whether Lab exists; a second route would buy
+    # a second round trip to carry a handful of strings. Empty on a stock
+    # install, which is what suppresses the tab entirely.
+    plugins: list[PluginInfo] = []
+
+
+class StatusResponse(BaseModel):
+    """The operator's view of the process, behind the private gate.
+
+    Notes
+    -----
+    **The blocks are typed as dicts, and that is a decision rather than a
+    shortcut.** Every other response model here describes a contract the SPA
+    depends on, so ``extra="forbid"`` on a fully declared field set is what
+    stops a typo shipping. This payload has one consumer, the page in
+    ``status_page.html``, which ships in the same commit as the route and reads
+    what it is given. Declaring forty nested models would freeze the shape of
+    an instrument that is expected to grow a panel whenever something new is
+    worth watching, and would put every future panel behind a schema edit for
+    no reader's benefit.
+
+    What *is* declared is the frame the page relies on: the block names, so a
+    panel cannot silently vanish, and ``generated_in_ms``, which is the payload
+    reporting its own cost so a future regression is self evident.
+
+    ``sessions`` and ``key_scope`` are always present. If the session isolation
+    work were ever reverted they would carry ``{"unavailable": "<reason>"}``
+    rather than being dropped, so a missing panel is always a stated fact and
+    never an absent key.
+    """
+
+    model_config = _RESPONSE_CFG
+
+    generated_at: str
+    generated_in_ms: float
+    identity: dict[str, Any]
+    settings: dict[str, Any]
+    sessions: dict[str, Any]
+    cache: dict[str, Any]
+    chart_cache: dict[str, Any]
+    exhibit_cache: dict[str, Any]
+    builds: dict[str, Any]
+    key_scope: dict[str, Any]
+    resources: dict[str, Any]
+    gate: dict[str, Any]
+    watch: dict[str, Any]