Contribution kind: capability. Ingestion: biome-host parser (CapabilityParser).
A capability is the only way an agent reaches a side effect. Contributing one
declares WHAT it is; the platform decides who may call it. Two authoring paths produce
the identical wire payload and reach the identical endpoint, so the choice is purely
ergonomic:
- Contribution file —
contributions/<slug>.capability.contribution.json
with { "kind": "capability", "manifest": { … } }, or the equivalent
xema.contributions.inline[] entry. No codegen step.
- Decorator — annotate a service provider method with the full
@XemaCapability
option set and opt the service into the boot-time registration scanner. A partial
descriptor is skipped, never silently defaulted.
Provenance (biome.id / biome.version) is NOT a field below — the ingestion pipeline
stamps it from the discovering biome's manifest. Authors never declare it inline.
manifest
| Field | Type | Required | Notes |
|---|
ref | string | yes | pattern /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*@\d+$/ |
title | string | yes | max 200 chars |
summary | string | yes | max 1000 chars |
sideEffects | string | yes | max 1000 chars |
inputSchema | map<string, unknown (free-form JSON)> | yes | — |
outputSchema | map<string, unknown (free-form JSON)> | yes | — |
riskTier | enum | yes | one of: low, medium, high, critical |
requiresApproval | boolean | yes | — |
examples | map<string, unknown (free-form JSON)>[] | no | max 20 entries |
externalServiceRef | string | no | max 200 chars |
defaultCredentialBindingRef | string | no | max 200 chars |
outputClassification | enum | no | one of: public, internal, confidential, secret, regulated |
authorityEffect | enum | no | one of: none, expanding |
reach | enum | no | one of: owner, integration, platform |
effectClass | enum | no | one of: read, write, admin |
trustedContextProjection | object — see trustedContextProjection | no | — |
requiredBindings | array of objects — see requiredBindings[] | no | max 20 entries |
safeForAgents | boolean | no | — |
humanBaseline | object (discriminated on kind) — see humanBaseline (kind: "explicit-only"), humanBaseline (kind: "org-role"), humanBaseline (kind: "org-administrators") | no | — |
delegable | literal true | no | — |
instanceGrade | object — see instanceGrade | no | — |
descriptorKind | enum | no | one of: invocable, authority |
callerConstraint | enum | no | one of: workflow-step |
trustedContextProjection
| Field | Type | Required | Notes |
|---|
schemaVersion | literal 1 | yes | — |
profile | enum | yes | one of: critical-operation-v1 |
delivery | literal "server-envelope" | yes | — |
requiredBindings[]
| Field | Type | Required | Notes |
|---|
roleKey | object — see requiredBindings[].roleKey | yes | — |
ownerKind | enum | yes | one of: system, org, project, app, session, biome, user |
remedyCapabilityRef | string | no | pattern /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*@\d+$/ |
humanBaseline (kind: "explicit-only")
| Field | Type | Required | Notes |
|---|
kind | literal "explicit-only" | yes | — |
humanBaseline (kind: "org-role")
| Field | Type | Required | Notes |
|---|
kind | literal "org-role" | yes | — |
minimumOrgRole | enum | yes | one of: org_owner, org_admin, org_member |
environments | enum[] | yes | entries one of: system, org, project, app, session, sandbox, public, store-review, trusted-dev |
dimensions | map<string, string[]> | no | — |
humanBaseline (kind: "org-administrators")
| Field | Type | Required | Notes |
|---|
kind | literal "org-administrators" | yes | — |
environments | enum[] | yes | entries one of: system, org, project, app, session, sandbox, public, store-review, trusted-dev |
dimensions | map<string, string[]> | no | — |
instanceGrade
| Field | Type | Required | Notes |
|---|
resourceType | string | yes | pattern /^[a-z][a-z0-9-]*_[a-z][a-z0-9_]*$/ |
relation | string | yes | pattern /^[a-z][a-z0-9_]*$/ |
environments | enum[] | yes | entries one of: system, org, project, app, session, sandbox, public, store-review, trusted-dev |
requiredBindings[].roleKey
| Field | Type | Required | Notes |
|---|
resourceKind | string | yes | pattern /^[a-z][a-z0-9-]{0,62}$/u |
role | string | yes | pattern /^[a-z][a-z0-9-]{0,62}$/u |
qualifier | string | no | pattern /^[a-z][a-z0-9-]{0,62}$/u |
Publish-time envelope
The parser and the decorator scanner both validate the manifest above plus the
invocation half, as one CapabilitySyncManifest. WHAT the capability is and HOW it is
invoked are split across kernel subpaths to keep the subpath graph acyclic; they are
recomposed here:
An optional invocation is not a soft default. A capability must be reachable by
exactly one of: a declared invocation binding, an org-level provider binding, or a
live runner. A ref with none of the three fails fast at the capability router rather
than degrading.