Skip to content

feat(contract): (operation, profile) capability mapping table / 能力映射表契约 #278

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Xingkai98 wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat(contract): (operation, profile) capability mapping table / 能力映射表契约 #278

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
66ed78c
feat(contract): stage/route capability mapping table
Xingkai98 Nov 10, 2026
cfd25d2
fix(contract): key the table by (operation, profile) per upstream voc…
Xingkai98 Nov 10, 2026
0c00455
fix(contract): separate states, validate transport/method, make fixtu…
Nov 10, 2026
6a19cc4
fix(contract): keep audio_generation local-unknown, align required_in…
Xingkai98 Nov 10, 2026
d950613
fix(contract): fixture construction invariants and unrecognised-route…
Xingkai98 Nov 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ This directory is the entry point for the repository's shared documentation. The
| [Contributing](../CONTRIBUTING.md) | Label taxonomy, how to pick labels, and what a PR must satisfy | Process, labels, or submission requirements change |
| [Unified project architecture](architecture/unified-project.md) | Business objects, shared entry points, and interaction rules | Object responsibilities, commands, persistence, or interaction rules change |
| [Test contracts](architecture/test-contracts.md) | Test/production boundaries, how to avoid stale assertions and environment-dependent red runs | Test infrastructure, capability gates, or contract ownership change |
| [Capability mapping contract / 能力映射表契约](architecture/capability-contract.md) | Evidenced upstream vocabulary, the `(operation, profile) → capability` table, the eight untranslatable declarations, and how it feeds discovery | Upstream vocabulary, capability ids, or discovery matching change |
| [Roadmap](development/roadmap.md) | Capability dependencies and delivery criteria | Scope, dependencies, or acceptance criteria change |
| [Validation guide](development/validation.md) | Reproducible checks and evidence requirements | Tools, runtime requirements, or validation entry points change |
| [Issue #87 Windows handoff](development/issue-87-windows-handoff.md) ([中文](development/issue-87-windows-handoff.zh-CN.md)) | Native ACL repair and final text acceptance | The shared checkpoint or native validation scope changes |
Expand Down
309 changes: 309 additions & 0 deletions docs/architecture/capability-contract.md
View file
Open in desktop

Large diffs are not rendered by default.

595 changes: 595 additions & 0 deletions packages/core/src/opendirector/domain/capability_contract.py
View file
Open in desktop

Large diffs are not rendered by default.

363 changes: 363 additions & 0 deletions tests/fixtures/omni-capabilities/absent.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,363 @@
{
"tier": "absent",
"upstreamEndpoint": "/v1/omni/capabilities",
"scope": "No usable capability evidence: no answer at all, an answer that carries only topology, and an answer whose operations declare no profile.",
"cases": [
{
"id": "endpoint-unreachable",
"note": "404, timeout or a disabled endpoint: nothing is claimed, nothing is missing.",
"payload": null,
"expected": {
"endpoint": "absent",
"topology": [],
"capabilities": {
"text.chat": "unknown",
"image.generate": "unknown",
"image.edit": "unknown",
"video.generate": "unknown",
"audio.speech": "unknown",
"audio.music": "unknown",
"image.segment": "unknown",
"video.matting": "unknown",
"video.motion_capture": "unknown",
"audio.score": "unknown",
"video.first_frame": "unknown",
"video.edit": "unknown",
"image.cutout": "unknown",
"audio.separate": "unknown"
},
"reasons": {},
"unresolved": []
}
},
{
"id": "topology-only-body",
"note": "Stages are published but no model declared an operation: the service answered without declaring anything (`empty`, not `absent`), and topology is display.",
"payload": {
"object": "omni.capabilities",
"schema_version": 1,
"observed_at": "2026-11-10T00:00:00Z",
"stages": [
{
"id": "7",
"type": "llm",
"depends_on": []
},
{
"id": "42",
"type": "diffusion",
"depends_on": [
"7"
]
}
],
"models": [],
"routes": [
{
"transport": "http",
"method": "POST",
"path": "/v1/chat/completions",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/images/generations",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/images/edits",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/videos",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/videos/sync",
"exposure": "enabled"
},
{
"transport": "websocket",
"method": "WEBSOCKET",
"path": "/v1/realtime/video",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/audio/speech",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/audio/generate",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/images/segmentations",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/videos/segmentations",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/videos/depth",
"exposure": "enabled"
}
]
},
"expected": {
"endpoint": "empty",
"topology": [
{
"id": "7",
"type": "llm",
"depends_on": []
},
{
"id": "42",
"type": "diffusion",
"depends_on": [
"7"
]
}
],
"capabilities": {
"text.chat": "unknown",
"image.generate": "unknown",
"image.edit": "unknown",
"video.generate": "unknown",
"audio.speech": "unknown",
"audio.music": "unknown",
"image.segment": "unknown",
"video.matting": "unknown",
"video.motion_capture": "unknown",
"audio.score": "unknown",
"video.first_frame": "unknown",
"video.edit": "unknown",
"image.cutout": "unknown",
"audio.separate": "unknown"
},
"reasons": {},
"unresolved": []
}
},
{
"id": "operations-without-profiles",
"note": "Six operations answered `supported`/`enabled` and each declares `profiles: []` — the published shape of \"no profile declared\" (`default_factory=list`), so every capability is `unknown`, not `missing`.",
"payload": {
"object": "omni.capabilities",
"schema_version": 1,
"observed_at": "2026-11-10T00:00:00Z",
"stages": [
{
"id": "7",
"type": "llm",
"depends_on": []
},
{
"id": "42",
"type": "diffusion",
"depends_on": [
"7"
]
}
],
"models": [
{
"id": "model-d",
"stage_ids": [
"7"
],
"operations": {
"chat": {
"support": "supported",
"exposure": "enabled",
"reason_code": "model_declared",
"profiles": [],
"execution": {
"state": "unpaused",
"scope": "worker",
"observed_at": "2026-11-10T00:00:00Z"
}
},
"image_generation": {
"support": "supported",
"exposure": "enabled",
"reason_code": "model_declared",
"profiles": [],
"execution": {
"state": "unpaused",
"scope": "worker",
"observed_at": "2026-11-10T00:00:00Z"
}
},
"image_edit": {
"support": "supported",
"exposure": "enabled",
"reason_code": "model_declared",
"profiles": [],
"execution": {
"state": "unpaused",
"scope": "worker",
"observed_at": "2026-11-10T00:00:00Z"
}
},
"video_generation": {
"support": "supported",
"exposure": "enabled",
"reason_code": "model_declared",
"profiles": [],
"execution": {
"state": "unpaused",
"scope": "worker",
"observed_at": "2026-11-10T00:00:00Z"
}
},
"speech": {
"support": "supported",
"exposure": "enabled",
"reason_code": "model_declared",
"profiles": [],
"execution": {
"state": "unpaused",
"scope": "worker",
"observed_at": "2026-11-10T00:00:00Z"
}
},
"audio_generation": {
"support": "supported",
"exposure": "enabled",
"reason_code": "model_declared",
"profiles": [],
"execution": {
"state": "unpaused",
"scope": "worker",
"observed_at": "2026-11-10T00:00:00Z"
}
}
}
}
],
"routes": [
{
"transport": "http",
"method": "POST",
"path": "/v1/chat/completions",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/images/generations",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/images/edits",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/videos",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/videos/sync",
"exposure": "enabled"
},
{
"transport": "websocket",
"method": "WEBSOCKET",
"path": "/v1/realtime/video",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/audio/speech",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/audio/generate",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/images/segmentations",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/videos/segmentations",
"exposure": "enabled"
},
{
"transport": "http",
"method": "POST",
"path": "/v1/videos/depth",
"exposure": "enabled"
}
]
},
"expected": {
"endpoint": "present",
"topology": [
{
"id": "7",
"type": "llm",
"depends_on": []
},
{
"id": "42",
"type": "diffusion",
"depends_on": [
"7"
]
}
],
"capabilities": {
"text.chat": "unknown",
"image.generate": "unknown",
"image.edit": "unknown",
"video.generate": "unknown",
"audio.speech": "unknown",
"audio.music": "unknown",
"image.segment": "unknown",
"video.matting": "unknown",
"video.motion_capture": "unknown",
"audio.score": "unknown",
"video.first_frame": "unknown",
"video.edit": "unknown",
"image.cutout": "unknown",
"audio.separate": "unknown"
},
"reasons": {},
"unresolved": []
}
}
]
}
Loading