Skip to content

Latest commit

 

History

History
146 lines (100 loc) · 34.3 KB

capability-contract.md

File metadata and controls

146 lines (100 loc) · 34.3 KB

Capability mapping contract

GET /v1/omni/capabilities reports what a deployment says about itself; the product needs to know what that deployment can do. packages/core/src/opendirector/domain/capability_contract.py is the only place that translates upstream's vocabulary into opendirector.domain.capabilities ids. It performs no HTTP, holds no display text, and introduces no second set of operation constants.

The upstream vocabulary (as evidenced)

Source: vllm-project/vllm-omni PR #10102 (issue #10007). Schema and protocol citations are from d1104f8; the entrypoints/openai/serving_capabilities.py citations (:339-343, :383-387, :400) and the vllm_omni/serving_capabilities.py block citations (:15,19-26, :43-54) are from 43ff7b9, where both files carry those anchors at exactly those lines (405 and 176 lines respectively). Each anchor names its revision where the two differ.

Six closed operations (vllm_omni/serving_capabilities.py:15,19-26): chat, image_generation, image_edit, video_generation, speech, audio_generation. There is no asr, transcription, segmentation, depth or music.

Twelve profiles (:43-54) and the ids this repository has for them. Profiles with a different output modality are not merged: text.chat here is consumed by a text-only adapter (integrations/model_adapters.py:631-647 reads choices[0]["message"]["content"] as a string), so an image-only chat deployment must not read as able to chat.

operation profile upstream required_inputs → outputs capability here
chat text_response ("text",) → ("text",) text.chat
chat image_response ("text",) → ("image",) none — the output is an image, not this repo's text.chat
chat audio_response ("text",) → ("audio",) none — the output is audio, not this repo's text.chat
image_generation text_to_image ("text",) → ("image",) image.generate
image_edit image_to_image ("text","image") → ("image",) image.edit
video_generation text_to_video ("text",) → ("video",) video.generate
video_generation image_to_video ("text","image") → ("video",) video.first_frame
video_generation video_to_video ("video",) → ("video",) video.edit
speech text_to_speech ("text",) → ("audio",) audio.speech
speech lyrics_to_music ("text","instructions") → ("audio",) audio.music
speech caption_to_audio ("text",) → ("audio",) none — sound effect / ambience
audio_generation text_to_audio ("text",) → ("audio",) none — the diffusion /v1/audio/generate contract, not this repo's audio.music

The three video_generation rows are one-to-one, and the two narrow ones are role-gated. The adapter distinguishes the shapes (VllmOmniVideo.video / .edit_video, integrations/model_adapters.py:405-540): text_to_video carries no reference and sends task=t2va, image_to_video carries input_reference with task=fl2va, video_to_video carries source_video plus the picture and audio masks. Folding all three onto video.generate let an image-to-video-only deployment read as able to do text-to-video, which is a false available.

One-to-one alone is still too generous, because the document's granularity stops at modality. A profile saying image_to_video proves it accepts an image, not that the image is a first frame: VACE feeds that image to reference_images (R2V; diffusion/models/wan2_2/pipeline_wan2_2_vace.py:135, forwarded at :158). A profile saying video_to_video proves it accepts a video, not that it takes latent masks: SeedVR2 declares V2V for video restoration and leaves supports_latent_mask_editing at its default False (diffusion/model_metadata.py:53,175). Both would read as available under a plain one-to-one table, and both would fail the request the tool actually sends.

So video.first_frame and video.edit carry REQUIRED_ROLES, and a yes verdict survives only when one of the profile's own open postable routes declares every one of those roles with support=supported in request.inputs (a closed route, or a path this operation does not own, counts for nothing). Otherwise the id is unknown, or missing once every open postable route refuses at least one of those roles. support alone is not the whole answer: the count window published beside it (min_count / max_count, both optional inclusive counts) is part of it. The tool sends one item, so support=supported with max_count: 0 is a refusal in effect — a role capped at zero cannot carry it — and min_count: 2 is one too, because that one item cannot satisfy the minimum. An absent bound is no bound on that side; a bound that is not a whole number leaves the entry undecided rather than guessed. One route, not the union of them: a request leaves on a single route, so source_video declared on /v1/videos beside the two noise masks on /v1/videos/sync is not an edit request either route would accept — that stays unknown with role_not_declared. Upstream publishes those four roles as of b934b642 (head 12d834c2): Wan I2V declares first_frame supported with min_count: 0 / max_count: 1 beside a required image — the same supplied image, so the two counts are not additive — and both VACE architectures declare first_frame unsupported with max_count: 0 on every profile they publish; the editing roles (source_video, video_noise_mask, audio_noise_mask) are declared supported with min_count: 0 / max_count: 1 where the handler accepts latent-mask editing, and unsupported with max_count: 0 where it does not. So video.first_frame reads available on Wan I2V and missing with unsupported on VACE, and video.edit reads missing with unsupported where those roles are refused — with no code change, because the gate reads the declaration rather than a written-in role list. A body that publishes modality roles only still leaves both ids unknown, and the report says why with role_not_declared. When at least one postable route is open and every open postable route refuses at least one required role, the document has said no — one role refused everywhere, or two routes each refusing a different one, even when neither route mentions the other roles — and the id is missing with reasons[cid] = "unsupported", exactly like a refusing profile: "the deployment will not take that input" is a different fact from "the document does not say", and it needs a different fix. A declared route this table cannot place — /v1/videos/sync, the socket, an unrecognised path — is reported and nothing more: whatever its own exposure says, it cannot keep the answer open. Only one of the profile's own postable routes with an absent, unreadable or unknown exposure is a channel this tool can still use; unless another reference to that same path is declared enabled, it keeps the answer unknown.

Four rows carry no id here (image_response, audio_response, caption_to_audio, text_to_audio), and they read together: image_response and audio_response are published upstream but have no id here, so they stay unknown and, while their route is open, are reported as no_local_capability instead of being folded into text.chat — the same scope as the no_local_capability row below, so a closed or undecided route on such a profile says nothing. text_to_audio uses the separate diffusion request contract behind /v1/audio/generate (no voice, no lyrics, no instructions; docs/serving/capabilities.md:59-60), while the only audio.music adapter in this repository (VllmOmniMusic, integrations/model_adapters.py:573-604) posts /v1/audio/speech with lyrics and instructions, both required. Upstream says that profile has neither and this repository demands both, so mapping it to audio.music would promise a request the deployment never accepted: the profile is reported as no_local_capability and audio.music is decided by lyrics_to_music alone (no evidence → unknown). That is the same rule that keeps caption_to_audio off audio.speech.

Operation → routes (:42-54) as (transport, method, path), because upstream's RouteKey is exactly that and the websocket method literal is WEBSOCKET: chat → http POST /v1/chat/completions; image_generation → http POST /v1/images/generations; image_edit → http POST /v1/images/edits; video_generation → http POST /v1/videos, http POST /v1/videos/sync, websocket WEBSOCKET /v1/realtime/video; speech → http POST /v1/audio/speech; audio_generation → http POST /v1/audio/generate. DELETE /v1/chat/completions would be a 405 and a websocket declaration on an http route is wrong, so both are route_mismatch. transport defaults to http upstream (protocol/capabilities.py:16-21) and an absent transport is not a mismatch; method has no default and an absent one cannot be confirmed.

Only the route this adapter actually posts counts as evidence: POSTABLE_ROUTES names it per operation — audio_generation keeps its placement row even though no adapter here posts /v1/audio/generate, so its declaration is still placed rather than discarded — an open /v1/audio/generate reports no_local_capability, while a closed or undecided one says nothing, like any other profile — and the synchronous variant, the websocket route and another operation's paths are reported (route_mismatch / unknown_route) without moving a verdict — this tool posts http POST /v1/videos, so a role named only beside /v1/videos/sync or on the socket is a role no request of ours can carry. The same reading applies to the key's three fields: an absent transport takes upstream's default, while a present but unreadable transport, method or path is malformed_route — a shape no published body can carry — and is never evidence.

Three schema facts shape the table: the body has only object, schema_version, observed_at, models, stages, routes (protocol/capabilities.py:73-79) and is served with response_model_exclude_none=True (api_server.py:2196) — the top-level routes[] is what upstream aggregates an operation's exposure from (entrypoints/openai/serving_capabilities.py:383-387: any enabled → enabled, else any unknown → unknown, else disabled), and each profile's routes[] is a copy of that list, forced disabled only for profiles needing video/audio input on /v1/realtime/video (:339-343). A top-level disabled therefore means the operation's HTTP endpoint is closed and no profile-level enabled reopens it; closing something narrower would semantically have to live on the profile route, but this projection (43ff7b9) never rewrites a profile route except for /v1/realtime/video, so "top level enabled with that profile's route disabled" is not producible today — it is a forward-compatible consumer branch, not an available control. This module reads the operation's exposure — upstream has already aggregated it — instead of re-reading the top-level list, which is why publishing an unowned path there changes no verdict, and not because those routes are "display only"; exclude_none drops only None-valued optional fields — in practice the profile's request — while default_factory lists serialize as [] (profiles: [], never a missing key), support/reason_code are required on every operation and profile, exposure is required on every operation and top-level route (protocol/capabilities.py:24-52), and a profile has no exposure field of its own (:36-44): its reachability is the aggregation of the exposures of the routes it references; and models[].operations must list all six or pydantic raises (:60-64), with stage_ids numeric strings, the same full list for every model (entrypoints/openai/serving_capabilities.py:400).

The key is the pair (operation, profile)

Not the route: /v1/audio/speech is one path with three contracts — text_to_speech (voice), lyrics_to_music (music), caption_to_audio (sound effect). Upstream's own tests show MOSS-SoundEffect serving caption_to_audio while reporting text_to_speech unsupported on that same path (tests/config/test_serving_capabilities.py:233,251): one path, two answers. A path-only key makes a sound-effect deployment look able to speak, and the reverse.

Not the stage either: stages[] publishes only id / type / depends_on, the ids are opaque numeric strings, and every model carries the same list. Keying on stages gives all models one shared state and no diagnosis, so stages[] only becomes topology here and never decides a capability; a stage entry carrying routes or name is ignored, because upstream's CapabilityStage has no such fields.

Routes still matter, in two ways: OPERATION_ROUTES records which operation owns which (transport, method, path) and a profile referencing another operation's path — or the wrong method — grants nothing and is reported as route_mismatch; and the exposure on the profile's own postable route is upstream's third exposure layer, overridden per profile (a profile needing video/audio input is forced disabled on /v1/realtime/video, serving_capabilities.py:341-343 — a route this tool never posts to, so that override is a diagnostic here, not a verdict).

Untranslatable declarations

unknown_route (the path belongs to no operation, including registered-but-unowned /v1/images/segmentations), route_mismatch (another operation's path, or a wrong method/transport), unmapped_stage (no such operation upstream — asr, music; the name predates the pair-keyed table), unknown_profile (operation known, profile id unpublished), operation_mismatch (profile known under another operation), no_local_capability (profile supported, no id here), no_route_declared (a supported profile that declares no route this tool can post to — routes: [], every entry without a usable path, or only routes this tool never posts to), malformed_route (a route entry this table cannot read: no usable transport/method/path, or a routes value that is not a list), role_not_declared (profile supported, but no single open postable route declares the whole input-role set the id needs — a role is absent, split across routes, or refused on one route while another stays silent), exposure_unknown (a postable route whose exposure is absent, unreadable or the literal unknown, reported when that doubt is why an id stays unknown), malformed_profile (a profiles[] element whose id cannot be read, or a profiles value that is not a list), malformed_operation (an operations[<op>] value that is not an object), unsupported_format (the body's object or schema_version names a contract this table does not read, so its models are never read), malformed_model (a models[] element that is not an object, carries no operations object, or carries an empty one — upstream lists all six operations on every model). Each one lands in unresolved with operation / profile / route / reason, never dropped; unsupported_format and malformed_model carry no operation, profile or route, because they are about the body or the model, not a row in it, while malformed_profile and malformed_operation name the operation they were declared in.

Three capability states, and missing needs positive evidence

available when a model's profile says supported, its operation is supported+enabled, and at least one of the profile's own postable routes is enabled (a role-gated id additionally needs one postable route carrying its whole REQUIRED_ROLES set as supported); missing only when a profile or operation says no, or when at least one postable route is open, every open postable route refuses at least one required role (or carries it only past a zero count bound), and no postable declaration is itself undecided; and only when every model says so — one model refusing while another does not mention the operation (or lists no operation at all) is unknown, because that silent model may serve, the same way one model granting it is enough for available; unknown for everything else — failed request, absent field, unknown enum value, unconfirmed reachability, an untranslatable declaration, or a capability no profile can express. resolve() also returns reasons, which names the kind of refusal for every missing capability: unsupported (the model refused), endpoint_disabled (the deployment closed the operation's routes) or route_disabled (every postable route the profile declares is closed). Reasons for unknown live in unresolved (declaration level) or in UNROUTED (capability level).

Status and reason mapping (the contract)

Every row below is read with the profile saying supported and its operation saying supported + enabled. A profile whose own support is unknown under an enabled operation is unknown with no note, and an operation whose exposure is unknown is unknown the same way; an operation that says unsupported, or is disabled, still decides the row on its own, because a refusal needs no profile evidence.

Upstream declaration status where the reason lives
profile support=unsupported missing reasons[cid] = "unsupported"
operation support=unsupported missing reasons[cid] = "unsupported"
operation supported + exposure=disabled missing reasons[cid] = "endpoint_disabled"
every route the profile can post to is exposure=disabled missing reasons[cid] = "route_disabled"
every postable route the profile declares is disabled, beside a route this table cannot place (/v1/videos/sync, the socket, an unrecognised path) whatever its own exposure says missing reasons[cid] = "route_disabled"; the unplaceable route is unresolved: route_mismatch / unknown_route, a diagnostic only
every postable route the profile declares is exposure=unknown unknown unresolved: exposure_unknown, one per distinct (profile, route) — reachability unconfirmed, not a refusal
profile declares no postable route (routes: [], no usable path, or only routes this tool never posts to) unknown unresolved: no_route_declared
a route entry with no usable transport/method/path, or a routes value that is not a list, with no usable postable route beside it unknown unresolved: malformed_route — the path is named when it can be read; no_route_declared too when that leaves no postable route
an unrecognised path, and nothing else usable unknown unresolved: unknown_route, and no_route_declared because no postable route is declared
another operation's path, or a wrong method/transport, with no usable postable route beside it unknown unresolved: route_mismatch, and no_route_declared when that leaves no usable postable route
upstream profile, no id here, declared on an open postable route unknown unresolved: no_local_capability — a closed or undecided route on that profile says nothing about it
profile supported, at least one postable route is open, but none declares the id's whole REQUIRED_ROLES set as supported — a role is absent, split across routes, or refused on one route while another is silent unknown unresolved: role_not_declared
a postable route whose exposure is absent, unreadable or the literal unknown, when that doubt is why the id stays unknown unknown unresolved: exposure_unknown, one per distinct (profile, route)
a profiles[] element whose id cannot be read, or a profiles value that is not a list no evidence from that profile unresolved: malformed_profile, once per operation
an operations[<op>] value that is not an object no evidence from that operation unresolved: malformed_operation, once per operation
profile supported, at least one postable route is open and every open postable route refuses at least one required role — one role refused everywhere, or two routes each refusing a different one, whether or not they mention the other roles (REQUIRED_ROLES) — with no postable declaration left undecided missing reasons[cid] = "unsupported"
profile supported, a required role declared support=supported with max_count: 0 on every open postable route that could carry it missing reasons[cid] = "unsupported" — the tool sends one item, a zero bound cannot take it
…the same, but a route this table cannot place names a required role as supported missing reasons[cid] = "unsupported" — an unplaceable route cannot rescue the refusal; it stays unresolved: route_mismatch / unknown_route
unknown operation / profile / misplaced profile no evidence → unknown unresolved: unmapped_stage / unknown_profile / operation_mismatch
supported, enabled, one enabled postable route (role-gated ids: one postable route carrying all REQUIRED_ROLES as supported) available none for the verdict — a diagnostic note may still sit in unresolved
a capability no upstream profile can express unknown UNROUTED[cid] (no_upstream_profile / no_upstream_operation / parameter_only / no_local_adapter)
no answer (None, no models, models not a list) all unknown endpoint = "absent"
answered, but no model declared an operation all unknown endpoint = "empty"
answered in another contract — object or schema_version is not omni.capabilities / 1 all unknown, models never read endpoint = "unreadable" + unresolved: unsupported_format
operation answered with profiles: [] unknown endpoint = "present"
one model refuses, another does not mention that operation unknown none — the silent model may serve, so the refusal is not deployment-wide; a model that lists no operation at all is unresolved: malformed_model instead
a models[] element that is not a model — not an object, no operations object, or an empty one no evidence from it; its silence keeps the affected ids unknown unresolved: malformed_model (reported once, only when another model declared something)

One boundary is left, and it now cuts the other way: a route this table cannot place is a diagnostic and never a channel — an unrecognised path, /v1/videos/sync or the socket cannot void a profile that answered, cannot keep a refusal undecided, and cannot turn "every postable route disabled" into anything but missing with route_disabled, whatever its own exposure says. What does keep a row undecided is a postable route whose exposure is absent, unreadable or the literal unknown: that route is one this tool can still post to, so the doubt is real, while the same doubt on an unplaceable route is nobody's channel. The three verdict notes — exposure_unknown, no_route_declared, role_not_declared — are attributed once the cross-model aggregate is known, and only to a (operation, profile) pair that still has an unknown capability id: a profile with no id here gets the shape reasons instead when it declares a route to report (route_mismatch, malformed_route, unknown_route, or no_local_capability while that route is open) and nothing at all when it declares none, because there is no id for a verdict note to explain. And endpoint distinguishes "did not answer" (absent) from "answered without declaring" (empty) from "declared" (present) from "answered in a contract this table does not read" (unreadable). Both keys are compared as published — object is the string "omni.capabilities", schema_version the integer 1, so "1" is a different shape and not the same version. A body that names neither key is read as v1 instead of being refused: upstream's response model always emits both, so a missing envelope cannot be told apart from a v1 body a proxy stripped. The gate runs before the absent / empty states, so a body with a foreign envelope is unreadable even when it carries no models at all, and topology comes back empty with it: stages[] of the refused body is the same unreviewed shape as its models. declarations() applies the same gate and returns None, so the two readers cannot disagree about one body.

Routes without an operation

/v1/images/segmentations, /v1/videos/segmentations and /v1/videos/depth are registered endpoints that no operation owns; upstream's docs state that "segmentation and depth estimation do not acquire one of these operations merely by being present in a registry" (docs/serving/capabilities.md:41-43). image.segment, video.matting and video.motion_capture therefore stay unknown with no_upstream_profile — the endpoint does not publish the ability, so it cannot be judged, and it must never read as missing. audio.score is no_upstream_operation; image.cutout is parameter_only (a request field of a published operation, granted per adapter rather than per profile); audio.separate is no_local_adapter. None of these six ids is a value of OPERATION_PROFILES, so unknown falls out of "no evidence" rather than a special case.

ASR: an upstream gap, not a missing row

Upstream publishes no recognition operation and omni's router never registers /v1/audio/transcriptions (absent from api_server.py; its own recipe says the endpoint is "not currently available with --omni"). A body naming asr gets unmapped_stage — the upstream vocabulary has no such operation, this table did not lose a row. That is not a claim that this repository ignores audio.score: the VllmOmniScore adapter does post to /audio/transcriptions (integrations/model_adapters.py:605-628, POST at :620), whose peer is the standalone tools/sheetsage2_serve.py:124. But a capabilities body never mentions that path, so audio.score can only be unknown (no_upstream_operation): a route we happen to know is not evidence of a published capability.

Relationship to the V2 discovery contract (#266)

This table is an input to #266, not a replacement and not a second schema: domain/omni_capabilities.py owns the discovery document and matching, this module owns only the (operation, profile) → capability layer, under a different file name. It no longer reads Model.stage_ids — that is topology, not a capability key — and declarations() reads only the published models[].operations[<op>].profiles[] shape. It does not modify domain/omni_capabilities.py, integrations/capability_probe.py, application/model_availability.py or src/**.

Feeding requests_for()

#266's application/model_availability.py currently hard-codes profile names per (kind, protocol); with a table the caller needs only the operation and profile it is about to use:

from opendirector.domain.capability_contract import capabilities_for

capabilities_for('speech', 'lyrics_to_music')   # ('audio.music',)
capabilities_for('speech', 'text_to_speech')    # ('audio.speech',)
capabilities_for('audio_generation', 'text_to_audio')  # () — upstream publishes it, no id here
candidates_for('video.first_frame')                     # (('video_generation', 'image_to_video'),)
candidates_for('audio.separate')                        # () — no profile supplies it
required_roles_for('video.first_frame')                 # ('first_frame',)
required_roles_for('video.edit')                        # ('source_video', 'video_noise_mask', 'audio_noise_mask')
required_roles_for('video.generate')                    # () — the profile's modality is the whole story
role_verdict(entry, 'video_generation', required_roles_for('video.edit'))
                                                        # 'yes' | 'no' | 'unknown' for one declaration

required_roles_for() is what keeps a modality-level profile from granting a narrower tool. A caller should ask role_verdict() rather than re-derive this: it reads the same postable routes resolve() reads, so the role question is answered the same way inside and outside resolve(). The profile's own verdict and its routes' reachability are decided before that gate runs, so a refused profile still reads refused. A role counts as satisfied only when one of the profile's own open postable routes names all of the required roles in request.inputs with support=supported and a count window that admits one item; roles spread over two routes count for nothing, because a request leaves on one; a role the document never names leaves the id unknown instead of available; a role that appears only on a closed route counts for nothing; and once every open postable route refuses at least one required role the id is missing with reasons[cid] = "unsupported", the same positive refusal a refusing profile produces — a route that refuses one role is out of the running whatever it leaves unmentioned (unless one of the profile's own postable routes has an absent, unreadable or unknown exposure, so it is still a channel this tool can use). resolve() applies the same rule, which is why both video tools read unknown on a deployment that declares i2v/v2v but publishes modalities only.

The reverse lookup is the same table read backwards (BY_CAPABILITY, derived from OPERATION_PROFILES, never a second vocabulary): a caller starting from local configuration — requests_for() does — holds a capability id and needs to know which (operation, profile) pairs could supply it. A candidate is not an authorisation: the adapter for the selected configuration still decides the route, the transmitted inputs and the output, and a submission must re-check that the pair it selected is the one admitted. Another profile being available does not vouch for it.

resolve(payload) returns per-capability states, per-capability reasons, topology (display only) and unresolved; classified_capabilities() returns the vocabulary in table order. Whether to wire this into requests_for() is #266's decision; this contract only guarantees the lookup is paired, ordered and testable.

resolve() is catalogue-level: it answers "what does this deployment declare", not "may this request go through". An available capability only says that at least one profile declares support with an open postable route; the caller must still check its own model, inputs, output and route, and stages[] describes pipeline topology only — it carries no admission evidence.

Fixtures and checks

tests/fixtures/omni-capabilities/{full,partial,absent}.json are the evaluated sample and follow the real response shape — stages[] as {id,type,depends_on} with numeric-string ids, six complete operations per model each with support/exposure/reason_code/profiles/execution, every profile carrying support, reason_code and routes (possibly []), and required_inputs/outputs transcribed from upstream's STANDARD_PROFILES including order (image_response/audio_response are ["image"]/["audio"]). full is the all-yes deployment, partial mixes refusals, a policy-disabled operation, an all-unknown body (with the routes stating unknown too) and the two role-gap cases, and absent covers no answer (absent), topology only (empty) and six operations that declare profiles: [] (present, all unknown). route_disabled appears only in malformed.json: upstream aggregates "all of the operation's routes disabled" into exposure=disabled, so a sample cannot carry that combination. In full, four profiles report no_local_capability (image_response, audio_response, caption_to_audio, text_to_audio) — text_to_audio grants no audio.music; audio.music is supplied by lyrics_to_music. The two video profiles that need an unpublished input role report role_not_declared and leave video.first_frame / video.edit unknown, which is the state an all-yes deployment gets until a document names those roles. partial also carries the two counterexamples as their own cases: vace-reference-images (a declaration whose route offers image as a reference role) and seedvr2-restoration (a video_to_video declaration with no mask role) — both keep the narrow id unknown.

A fourth file, malformed.json, is defensive input only and not a sample of what upstream can produce: its bodies are valid pydantic (the structural checks pass) but upstream's projection cannot emit them — a profile pointing at another operation's route, or owned routes all disabled beside an enabled path this table does not know. Only a proxy, a cache or an older revision can hand us one, so it is read by the defensive, structural and profile-row checks alone, never by the sample oracle.

Shapes upstream can never emit — an asr operation key, a profile filed under the wrong operation, a missing required support — are built inline in the tests that defend against malformed input, never in the sample fixtures. test_fixtures_are_schema_valid asserts only the structural invariants of upstream's model (six keys, observed_at parseable and timezone-aware, reason_code wherever support is, execution as {state,scope,observed_at}, the enum domains, profiles as a list, routes carrying transport/method/path, stage shape with numeric-string ids, and a video route's request carrying last_frame: unsupported plus the four transport parameters), not a copy of upstream's pydantic source.

Ten regressions keep coverage honest: test_real_shaped_body_resolves_non_empty_pairs, test_route_alone_cannot_distinguish_speech_profiles, test_stage_ids_do_not_collapse_capabilities, test_capabilities_without_an_upstream_profile_are_unknown_not_missing, test_a_profile_without_support_is_unknown_even_when_its_operation_is_supported, test_a_video_profile_grants_a_narrower_id_only_when_its_route_declares_the_role, test_a_count_window_that_excludes_one_item_is_not_a_grant, test_a_refusal_excludes_its_route_even_when_the_rest_is_silent, test_a_body_from_another_contract_is_unreadable_instead_of_v1 and test_one_model_refusing_while_another_stays_silent_is_not_missing; the route-level exposure, transport/method, chat-modality, text_to_audio, role-gating, count-window, foreign-envelope, multi-model-silence and missing-reason cases each have their own test, and test_documented_required_inputs_match_fixtures pins the twelve required_inputs/outputs rows against the doc table and every fixture.

PYTHONPATH=packages/core/src:apps/api/src python -m pytest tests/test_capability_contract.py -q