RFC 006: Capability registry vs spec Capability

[brettin]

Summary

Adds RFC 006 proposing a companion platform-capability schema for registry registration while retaining spec Capability for artifact binding.

Gap IDs

• op-listCapabilities
• op-registerCapability
• op-getCapability

Tracking

Part of #1. Base: RFC 004 branch (final RFC in the series).

Test plan

• Review against capability.schema.json and registry OpenAPI paths

Made with Cursor

[brettin]

Review: RFC 006 — Capability registry vs spec Capability

Overall the RFC names a real and important noun collision between the spec Capability (a scientific artifact descriptor) and the platform's registry record (an operational routing/owner descriptor), and proposes the right shape of fix: a companion schema rather than overloading the spine. The 9-line scaffold gets the diagnosis directionally right, but the evidence and the proposal both need to be fleshed out before this can guide implementation. A few observations and suggestions below.

---

✅ What works well

1. The diagnosis matches reality on both sides. The spec Capability at contracts/schemas/common/capability.schema.json does require exactly profile, executionContext, artifact, and a smoke-test status enum (declared / smoke_test_passed / smoke_test_failed / deprecated) — i.e. it is a scientific-reproducibility descriptor. The platform Capability in aria-server/aria_server/db/models.py (lines 157–186) and its CapabilityResponse / RegisterCapabilityRequest in aria-server/aria_server/api/routes/capabilities.py instead require capabilityType, owner, routing (MAG config), targets, costPerUnit, plus input/output JSON schemas — i.e. an operational catalog row. Same noun, two different objects.
2. Companion-schema approach is precedented. contracts/companion/schemas/ already houses data-movement-intent.schema.json, campaign-plan.schema.json, and eval-publication.schema.json. GAP_DISPOSITION_REGISTER.md entries GAP-008 and GAP-009 explicitly direct registry/skill-card concerns to capability_profile rather than spine — so a platform-capability.schema.json companion is consistent with the existing v3 governance posture.
3. Gap IDs are the right hooks. The three referenced operations (op-listCapabilities, op-registerCapability, op-getCapability) line up exactly with the CapabilityRegistry operations at contracts/openapi/gmp-core-v3.yaml:46-105, so the RFC's scope is unambiguous.

---

🔍 Suggestions

1. Make the noun collision explicit with a mapping table. A two-column table — spec Capability fields vs. platform record fields — would do most of the rhetorical work. In particular: spec has profile, executionContext, artifact, reproducibilityTier, accessPrerequisites; platform adds capabilityType (enum: foundation-model / simulation-tool / data-tool / orchestration-tool / agent), owner, provider, routing, targets, costPerUnit, inputSchema, outputSchema, tags. Only capabilityId, name, version, and status overlap — and even status has divergent enums (draft|active|deprecated|archived in the DB vs. declared|smoke_test_passed|smoke_test_failed|deprecated in the spec).
2. Pick a wire contract for POST /v3/capabilities. Today gmp-core-v3.yaml:71-82 says registerCapability accepts a spec capability.schema.json, but the server's RegisterCapabilityRequest doesn't require profile/executionContext/artifact and accepts routing/targets/costPerUnit that aren't in the spec schema. The RFC should state explicitly: does the registry endpoint accept (a) spec Capability only, (b) platform-capability only, (c) a union/envelope, or (d) spec Capability with a x-platform extension block? Each has different validator and client-codegen consequences.
3. Define the join key and lifecycle. If both objects coexist, do they share capabilityId? Is a platform-capability row required to point at a spec Capability (artifact binding) before it can be runnableOnly=true? What happens to a platform row when the spec capability is deprecated?
4. Address the status enum mismatch head-on. CapabilityStatus in db/models.py:42-48 and the spec's smoke-test enum are not reconcilable as-is. Either map them, or state that platform-capability.status is a separate field with separate semantics.
5. Cover access prerequisites and capability tokens. Spec Capability.accessPrerequisites (license/citizenship/training/embargo/agreement) already exists and the platform model mirrors it — but mintCapabilityToken (gmp-core-v3.yaml:311) keys off capabilityId. The RFC should say which object the token issuer reads from.

---

❓ Open questions

1. Does platform-capability live in contracts/companion/schemas/ (v3-governed) or in the platform repo (out-of-spine)? GAP_DISPOSITION_REGISTER places registry concerns in capability_profile, which would argue for the latter.
2. Should the OpenAPI registerCapability request body change to a oneOf / discriminated union, or should the platform expose a separate /v3/platform/capabilities path to avoid colliding with the spine operation?
3. How does this interact with aria_server/services/companion_schemas.py — is there already a registration pattern for companion schemas that platform-capability should follow?
4. Versioning: the platform version field is free-form ("1.0.0"); is a SemVer + compatibility-range contract needed for registry consumers, or is capabilityId expected to encode the version?
5. Discovery: list_capabilities filters by profile, type, tag, runnableOnly. Are those filters part of the spine contract or the platform extension? The current OpenAPI lists profile but the implementation also accepts type and tag that the spec query schema doesn't document.