# Capability Registry Schema — Layer 3 Domain Entity Type # KNO Schema Version: 0.1.0 # Status: Experimental # CHANGELOG: # 0.1.0 (M64 P3, #2814): Initial schema. The distribution-Registry descriptor # for the P14 federated Capability-distribution model. # Family B sibling (NOT an edit to registry-schema). # Minimal-but-extensible: required release-entry index # closes the testable-convergence loop; federation / # trust-tier / mirror / Genesis fields are declared as # `experimental: true` seams owned by #3094. # # A Capability Registry is the native Possibility AUTHORITY / MATERIALIZER that # distributes Capabilities (P14 — bedrock v1.27.0). It is the graph-write # authority over Capability release records; the flat release index is a # deterministic, content-addressed PROJECTION of it (never a mutation target). # This descriptor names a Registry's identity and the Capability releases it # indexes; the signed wire primitives it references (Registry Fact Envelope, # Genesis Descriptor, Mirror Descriptor, Trust Tiers) are owned by the # substrate track #3094 and bound here by reference. # # EXTENDS: document-schema.kno (which composes identity, history, quality) # # ────────────────────────────────────────────────────────────────────────── # THE REGISTRY FAMILY (polysemy disambiguation — Family B, ratified P3) # ────────────────────────────────────────────────────────────────────────── # "Registry" denotes THREE distinct kinds of thing in this codebase. They are # distinct sibling schemas (Family B), NOT subtypes of one schema, and NOT a # parent/child `extends` chain. See # docs/planning/bedrock-registry-and-capability-simplification/03-p3-directional-grounding.md. # # | Schema | Sense | type | # |-----------------------------------|------------------------|---------------------| # | registry-schema | discovery POINTER | service-config | # | public-collection-registry-schema | public-collection list | registry | # | capability-registry-schema (THIS) | distribution AUTHORITY | capability-registry | # # "Possibility Registry" (the `/.well-known/possibility-registry` endpoint and # the deployed Reference Registry) is the ENDPOINT / INSTANCE of a # `capability-registry-schema` authority — not a separate concept. # # DESIGN DECISIONS: # - DD-CREG-01: The native `.kno` Registry record is the semantic WRITE # authority (graph-authoritative); the flat release index is a generated # content-addressed projection (R10). Public surfaces (REST/MCP/A2A/llms.txt/ # well-known) PROJECT registry facts and may never upgrade trust state or # bless an install (P14). # - DD-CREG-02: Trust is an install-time POLICY over separately recorded # evidence, never a property of one signature/source/surface (P14, R11). The # trust-tier + evaluator shape is a deferred seam (#3086 / #3094); v0.1 # carries only the reference fields. # - DD-CREG-03: Identity is PROVISIONAL (R9). `registry_id` is an opaque # origin-anchored subject anchor; `xri` / `did:web` / DNS are aliases/hints # until the identity layer is re-grounded (#3090). v0.1 bootstraps from a # Registry Genesis Descriptor (#3084) pinned out-of-band — the genesis # bootstrap hazard (a Registry cannot be discovered through a Registry) is # resolved by out-of-band root pinning. # - DD-CREG-04: Mirrors are READ-ONLY, non-authoritative observers in v0.1 # (R9). `mirror_policy` is a declared seam; no mirror may confer authority # until a signed-delegation design exists. # - DD-CREG-05: Honesty boundary (P14 + api-contract-honesty). v0.1 advertises # ONLY implemented read operations. Federation, trust tiers, mirror # delegation, and offline bundles MUST NOT be advertised as present until # their implementation + verification gates exist. Every `experimental: true` # field is a declared-absent seam, not a working surface. # # ────────────────────────────────────────────────────────────────────────── # SCHEMA-MINIMIZATION — DC-2 (AC3, bedrock-claims pass) # ────────────────────────────────────────────────────────────────────────── # THREE-GATE TEST (whether a new schema is warranted at all): # Gate 1 (Distinctness): YES — a federated distribution AUTHORITY (graph-write # authority + projected index + trust-over-evidence + Genesis identity) is # fundamentally different from a discovery pointer or a public-collection # manifest. P14 defines it as a distinct primitive. # Gate 2 (Reusability): YES — every Capability that distributes is a registry # entry; the convergence test uses 1 of 3 capabilities today, with the # contribution-ready target being many (external contributors, then an # ecosystem). Crosses the 3-instance threshold by design. # Gate 3 (Clarity): YES — a distinctly-named sibling makes the system clearer; # folding distribution into the pointer schema would be the §0.6 God-Schema # anti-pattern (~80% disjoint fields, wrong base type). # # FIVE-TEST (sibling-vs-extend SHAPE; N>1 multi-corner rule — tested vs EACH # existing sibling. Discriminators: field-overlap>50%, shared lifecycle, shared # validation, shared display surface, shared resolver. Pass 4+ → extend; # pass <3 → sibling): # # vs registry-schema (discovery pointer): # 1 field-overlap NO (pointer: endpoint_path/spec_url/spec_version/compat; # this: release-index/fact_envelope_ref/trust/genesis) # 2 lifecycle NO (pointer: static hand-authored; this: publish/release/ # yank/deprecation lifecycle) # 3 validation NO (pointer: URL/path/version-string; this: digests, # signatures, trust evidence) # 4 display NO (pointer: "where to find" in manifest/bootstrap/card; # this: release index / catalog / install surface) # 5 resolver NO (pointer: → URL; this: capability_xri+version → # manifest+digest+envelope) # → 0/5 → SIBLING (decisive) # # vs public-collection-registry-schema (public-collection list): # 1 field-overlap NO (collection: collections[]/route_prefix/mcp knobs; # this: release/trust/envelope) # 2 lifecycle NO (collection: static REQ-18 config; this: release # lifecycle) # 3 validation NO (collection: collection-name + visibility:public; # this: digests + trust evidence) # 4 display NO (collection: REQ-18 four-surface routing; this: # release-index / install) # 5 resolver NO (collection: which collections are public + routing; # this: capability releases) # → 0/5 → SIBLING (decisive) # # N>1 bar (≥2 tests vs ≥1 sibling) far exceeded: 0/5 vs BOTH siblings. # # DEFERRED (Option C): the long-term clean ontology is an abstract `registry` # base with `extends`-specializations. Deferred to P6 #2817 (instance/interface # cascade out of P3 scope); instances migrate via non-breaking XRI # alias/redirect. P3-CONF-03 (the existing public-collection `extends` # registry-schema relationship is itself Five-Test-strained) folds into that # refactor. # # MAPS TO: the CapabilityRegistry descriptor consumed by the Reference Registry # (P4 #2815). Instances live at content/registries/*.kno once P4 seeds them. # ============================================================================= # SCHEMA DECLARATION (RFC-007) # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY (Layer 1) # ============================================================================= id: 01KTMQV4TV46ZEHFM4YP8663ET slug: capability-registry-schema type: spec version: 0.1.0 # ============================================================================= # VISIBILITY DECLARATION (REQ-18) — collection default # ============================================================================= # Capability-registry descriptors are public reference knowledge by default — # they describe an advertised distribution authority. Per REQ-18, individual # instances MAY override with their own `visibility:` field. Drives the # four-surface contract per kno-system_architecture.md § Agent Surface # Integration and public-surface-parity.instructions.md. visibility: public # ============================================================================= # STANDARD TIER # ============================================================================= title: "Capability Registry Schema" purpose: | Define the schema for a Capability Registry descriptor — the native Possibility authority that distributes Capabilities under the P14 federated model (bedrock v1.27.0). **What is a Capability Registry?** A native authority/materializer that holds the graph-write-authoritative record of Capability releases and projects a deterministic, content-addressed release index. It is NOT a generic public collection and NOT a wholesale adoption of an external package ecosystem (OCI/npm/Maven/Backstage are prior art for envelopes and indexes, not the source of truth for `.kno` / Capability semantics). **What this descriptor carries (v0.1 — minimal):** - `registry_identity` — the Registry's provisional identity (opaque anchor + alias hints + Genesis reference seam). - `entries[]` — the release-entry index: Capability releases keyed by `capability_xri` + `version`, each with a manifest digest and a Fact Envelope reference. This is the load-bearing surface that closes the testable-convergence loop (resolve → digest-verify → evaluate → install via the existing FSM). **Deferred seams (declared `experimental: true`, owned by #3094):** trust policy / tiers (R11, #3086), mirror policy (R9, #3085), federation (R9), Genesis descriptor (#3084). Declared as extension points so a contributed Capability and a future federated Registry fit without reshaping the schema — never advertised as working until their gates exist (P14 honesty boundary). **Layer 3 Position:** Capability Registry extends document (Layer 2), which composes identity, history, and quality (Layer 1). # ============================================================================= # RICH TIER — Provenance & Taxonomy # ============================================================================= provenance: origin: id: 01KTMQV4TV46ZEHFM4YP8663ET timestamp: "2026-06-08T00:00:00Z" tool: manual references: - "kno://docs/planning/bedrock-registry-and-capability-simplification/03-p3-directional-grounding" - "kno://research/council-research/2026-06-01-r10-reference-registry-shape" - "kno://research/council-research/2026-05-31-r09-federation-substrate" - "kno://research/council-research/2026-06-01-r11-trust-governance-attestation" taxonomy: topics: - registry - distribution - capability - federation - trust keywords: - capability-registry - distribution-authority - release-index - fact-envelope - trust-tier - genesis-descriptor - mirror-policy # ============================================================================= # RICH TIER — Relationships # ============================================================================= relationships: extends: - xri: "kno://specs/document-schema" reason: "Layer 2 base type for all documents" depends_on: - xri: "kno://specs/kno-spec" reason: "Conforms to KNO format specification v0.0.9" composes: - xri: "kno://specs/identity-schema" reason: "Layer 1: id, slug, provenance" - xri: "kno://specs/history-schema" reason: "Layer 1: _history, changelog" - xri: "kno://specs/quality-schema" reason: "Layer 1: quality, validation" related_to: - xri: "kno://specs/registry-schema" reason: "Registry-family sibling (Family B) — the discovery-POINTER sense; distinct schema sharing the noun, NOT a parent/child relationship" - xri: "kno://specs/public-collection-registry-schema" reason: "Registry-family sibling (Family B) — the public-collection sense; distinct schema sharing the noun" - xri: "kno://specs/platform-capability-schema" reason: "Registry entries index platform-capability releases via capability_xri" # ============================================================================= # RICH TIER — Quality # ============================================================================= quality: status: experimental completeness: 0.60 last_reviewed: "2026-06-08" review_status: draft reviewed_by: "claude" validation: - "type is `capability-registry` (auto-discovered from filename)" - "entries[].capability_xri matches ^pspace://capability[/:]" - "entries[].manifest_digest is a digest string (algo:hex)" - "experimental seams (trust_policy, mirror_policy, federation, genesis) are declared-absent until #3094 lands their wire primitives" # ============================================================================= # HISTORY (P9 Temporal) # ============================================================================= _history: retention: full format: changelog changelog: - version: "0.1.0" date: "2026-06-08" author: "claude" summary: "M64 P3 (#2814): initial Capability Registry descriptor schema — Family B sibling; minimal release-index + experimental federation/trust/ mirror/genesis seams owned by #3094." changes: - "Initial schema. Distribution-authority descriptor for the P14 federated Capability-distribution model (bedrock v1.27.0)." - "Required: registry_identity + entries[] release index (closes the testable-convergence loop). Deferred experimental seams: trust_policy (R11/#3086), mirror_policy (R9/#3085), federation (R9), Genesis reference (#3084) — all owned by #3094." - "DC-2 Three-Gate PASS; Five-Test 0/5 vs registry-schema AND vs public-collection-registry-schema (N>1 multi-corner satisfied → sibling decisive). Recorded in the header THREE-GATE/FIVE-TEST block and the P3 directional grounding doc." # ============================================================================= # SCHEMA DEFINITION # ============================================================================= spec: status: Experimental description: | ## Capability Registry Descriptor Structure A Layer 3 entity that extends document-schema. The minimal v0.1 surface is `registry_identity` + `entries[]`; everything federation/trust/mirror is a declared `experimental: true` seam owned by the #3094 substrate track. schema: type: object required: - id - slug - type - version - title - registry_identity - entries properties: $schema: type: string const: "capability-registry@0.1.0" description: "Schema declaration" id: type: string format: ulid description: "Unique identifier (ULID). Immutable birth identity." slug: type: string format: kebab-case description: "Human-readable identifier for URLs and references. Mutable." examples: - "possibility-reference-registry" type: type: string const: "capability-registry" description: "Entity type — always 'capability-registry'" version: type: string format: semver description: "Descriptor version (semver)" examples: - "0.1.0" visibility: type: string enum: - public - private default: public description: "REQ-18 visibility (collection default public)." title: type: string description: "Human-readable display name of the Registry." description: type: string description: "Free-text prose describing the Registry and its scope." # ----------------------------------------------------------------------- # REGISTRY IDENTITY (provisional — R9) # ----------------------------------------------------------------------- registry_identity: type: object description: | The Registry's provisional identity (R9). `registry_id` is the opaque origin-anchored subject anchor; `xri` / `did:web` / DNS are aliases/hints until the identity layer is re-grounded (#3090). required: - registry_id properties: registry_id: type: string description: | Opaque, origin-anchored identifier for this Registry (the authoritative subject anchor). Stable; not derived from a mutable alias. xri: type: string description: | **Status: experimental** (alias/hint, not a re-grounded trust anchor — R9). Named XRI per RFC-013. pattern: "^pspace://capability-registry[/:][a-zA-Z0-9_-]+$" genesis_ref: type: object description: | **Status: experimental** (#3084 seam). Reference to the Registry Genesis Descriptor that bootstraps this Registry's root trust, pinned out-of-band. Resolves the genesis bootstrap hazard (a Registry cannot be discovered through a Registry). Full shape owned by #3084. properties: descriptor_digest: type: string description: "Digest of the Genesis Descriptor (algo:hex)." # ----------------------------------------------------------------------- # RELEASE-ENTRY INDEX (the load-bearing v0.1 surface) # ----------------------------------------------------------------------- entries: type: array description: | The release-entry index — the deterministic, content-addressed PROJECTION of the Registry's authoritative record (DD-CREG-01). Each entry is an immutable Capability release keyed by `capability_xri` + `version`. This is the surface that closes the testable-convergence loop: resolve `capability_xri`+`version` → `manifest_digest` + `fact_envelope_ref` → (P4 verifies the bytes and evaluates trust, then installs via the existing FSM). items: type: object required: - capability_xri - version - manifest_digest properties: capability_xri: type: string description: "Identity XRI of the indexed Capability (RFC-013)." pattern: "^pspace://capability[/:][a-zA-Z0-9_-]+$" version: type: string format: semver description: "Immutable release version (semver, R18)." manifest_digest: type: string description: | Digest of the Capability's `.kno` manifest bytes (algo:hex, e.g. `sha256:...`). Server-side verification is mandatory; a client-submitted digest is a claim, not a fact (R9/R10). pattern: "^[a-z0-9+.-]+:[A-Fa-f0-9]+$" fact_envelope_ref: type: string description: | **Status: experimental** (the #3083 wire-primitive seam, owned by #3094). Digest-pinned reference to this release's Registry Fact Envelope (verification state, trust tier, evidence, freshness). The Fact Envelope is the v0.1 trust blocker; this descriptor binds it by reference. Until #3083 lands, entries may omit it (the convergence test for the first capability wires it explicitly). release_metadata: type: object description: "Immutable release facts." properties: published_at: type: string format: date-time publisher_possibility_xri: type: string pattern: "^pspace://possibility[/:][a-zA-Z0-9_-]+$" distribution: type: object description: "Where the manifest bytes are fetched from." properties: links: type: array items: type: string verification_state: type: string description: | **Status: experimental** (R11 — full shape owned by #3094). The recorded verification state of this release's bytes. No public surface may UPGRADE this state (P14). Default-absent in v0.1. enum: - unverified - verified - failed - stale - revoked trust_tier: type: string description: | **Status: experimental** (R11/#3086). Recorded trust tier (graded evidence, not a label conferring trust). Trust is an install-time policy over this evidence, never the tier alone. # ----------------------------------------------------------------------- # DEFERRED SEAMS (experimental — owned by #3094; declared, not advertised) # ----------------------------------------------------------------------- trust_policy: type: object description: | **Status: experimental** (R11 / #3086 / #3094). The evaluator policy axes (governance label + machine-verifiable evidence tier + evaluator decision + release-state + distribution-scope). Declared as a seam; the working evaluator is P4. P14: no single overloaded trust enum. mirror_policy: type: object description: | **Status: experimental** (R9 / #3085 / #3094). Read-only, non-authoritative mirror semantics. v0.1 mirrors serve content only, referencing original anchors + digests; no mirror confers authority until a signed-delegation design exists. federation: type: object description: | **Status: experimental** (R9 / #3094). Single-origin federation in v0.1 (multi-master reconciliation out of scope). The `/.well-known/possibility-registry` discovery seam advertises ONLY implemented read operations (P14 honesty boundary).