revisão e complementação da documentação do projeto

RI/docs/interfaces/registry-capability-manifest.en-us.md

@@ -0,0 +1,92 @@
+# Interface: capability manifest and Registry lifecycle
+
+Capability manifest schema and the publishing pipeline, for whoever is going to publish a new
+capability to the Global Capability Registry. Implementation:
+[`src/emcp_bus/registry/models.py`](../../src/emcp_bus/registry/models.py),
+[`registry/pipeline.py`](../../src/emcp_bus/registry/pipeline.py),
+[`registry/lifecycle.py`](../../src/emcp_bus/registry/lifecycle.py),
+[`registry/store.py`](../../src/emcp_bus/registry/store.py). See
+[`AS-BUILT.md`](../AS-BUILT.md#global-capability-registry-ep-02).
+
+## Manifest schema (`CapabilityManifest`)
+
+```yaml
+# config/capabilities/finance/payment-execute.yaml
+name: finance.payment.execute      # <domain>.<capability>, validated (domain must prefix name)
+version: 1.0.0                     # SemVer
+domain: finance
+owner: finance-platform
+risk_tier: R3                      # R0-R4
+side_effects: true
+idempotent: false
+data_classification: [confidential, restricted]   # public | internal | confidential | restricted
+entitlements: [Finance.Payments]   # ClientProfile names that may see/call this capability
+backend:
+  type: mcp                        # mcp | rest | grpc (only "mcp" has live dispatch in this RI)
+  service: finance-domain          # id resolved by config/backends/<service>.yaml
+approval:
+  required: true                   # required if risk_tier is in {R3, R4} — pipeline gate
+```
+
+(real example: `config/capabilities/finance/payment-execute.yaml`)
+
+Fields with defaults: `observability.audit_level` (`"full"`), `lifecycle.status`
+(`"nominate"` — a new manifest never declares itself `active` directly).
+
+## Lifecycle (`LifecycleStatus`)
+
+```
+NOMINATE → REVIEW → REGISTER → ACTIVE ⇄ ACTIVE → DEPRECATED → RETIRED
+              ↑________________|
+           (rejected review goes back to NOMINATE)
+```
+
+Only an `ACTIVE` capability is resolvable by the Fabric (`CapabilityRouter`) — any other status
+is a matter exclusively for the control plane. Nothing reaches `ACTIVE` without passing through
+`REVIEW` (`registry/lifecycle.py:validate_transition`, mechanically verified).
+
+## Publishing pipeline
+
+```python
+pipeline = PublishingPipeline(store)
+registered = pipeline.submit(manifest)  # runs the gates -> NOMINATE -> REVIEW -> REGISTER
+pipeline.publish(registered.name)  # REGISTER -> ACTIVE
+```
+
+`submit()` runs business gates before any state transition (schema/naming is already the
+responsibility of `CapabilityManifest` itself at construction time):
+
+| Gate | Rule |
+|---|---|
+| Owner | `owner` cannot be empty. |
+| Backend | `backend.service` cannot be empty. |
+| Risk-based approval | `risk_tier` in `{R3, R4}` requires `approval.required: true`. |
+
+Any failed gate raises `PublishingRejectedError(reasons)` — nothing enters the Registry
+partially (fail-closed, no ad hoc manual registration).
+
+## How the Fabric resolves a capability
+
+`CapabilityRouter.route(tool)` looks up `tool`'s `ACTIVE` manifest, resolves
+`backend.service` to a URL+credential via `BackendCredentialProvider` (see
+[`downstream-identity.md`](downstream-identity.md)), and returns a `BackendRoute`. Without a
+matching `ACTIVE` manifest, or an unresolvable backend: `UnroutableCapabilityError` — the Gateway
+treats this as `UNROUTABLE_CAPABILITY` (DENY).
+
+## Errors
+
+| Situation | Exception |
+|---|---|
+| `name` without a `.` (not `<domain>.<capability>`) | `pydantic.ValidationError` at manifest construction. |
+| `domain` is not the prefix of `name` | `pydantic.ValidationError` at manifest construction. |
+| Business gate failed in `submit()` | `PublishingRejectedError` |
+| Invalid lifecycle transition (e.g. `NOMINATE` → `ACTIVE` directly) | `InvalidLifecycleTransitionError` |
+| `tool` without an `ACTIVE` manifest, or nonexistent backend | `UnroutableCapabilityError` |
+
+## Not implemented in this RI
+
+An administrative HTTP endpoint to publish/revoke via API (today `PublishingPipeline` and the
+lifecycle transitions are direct Python calls, exercised in tests, not exposed over the
+network) — see `../Production-Recommendations.md`. A `backend.service` health check as a
+publishing gate also does not exist (it would be a disguised `TODO` without a real registry of
+backend health endpoints in this RI).