Implement CapabilityLedger contract and UI/runtime capability reconciliation

[mdheller]

Parent spec

SourceOS-Linux/sourceos-spec#99

Intent

sourceos-shell must implement the CapabilityLedger ledger to ensure that any feature flag, runtime, or plugin capability is reconciled across config, UI, runtime, server, plugin, policy, schema, and transport planes. This prevents split-brain where a feature is locally claimed as enabled but rejected elsewhere.

Required behavior

• Each capability flag/state change must emit a CapabilityLedger receipt.
• Ledger must track declared, requested, negotiating, available, enabled, degraded, blocked_by_policy, unsupported_by_runtime, unsupported_by_server, missing_plugin, missing_schema, failed states.
• Reconciliation occurs at runtime startup, on feature toggle, and on plugin load/unload.
• Conflicts must be logged as warnings in the ledger with references to evidence.
• Receipt schema and example must be validated against sourceos-spec.

UI/runtime requirements

• Display effective capability state per feature.
• Indicate owner (UI, runtime, server, plugin, policy).
• Show policyDecisionRef and evidenceRefs.
• Prevent feature use until ledger reports enabled.

Acceptance criteria

• Ledger exists with runtime tests covering at least: enabling, denying, unsupported, missing plugin, failed reconciliation.
• UI surfaces effective state with owner and policy/evidence refs.
• Conflicting feature attempts generate receipts with correct state.
• Ledger and UI validate against sourceos-spec schema/examples.

Notes

This implements the CapabilityLedger portion of SourceOS-Linux/sourceos-spec#99. Ledger entries become the single source of truth for all capability state.

[mdheller]

Implementation handoff update

The upstream contract layer has landed in SourceOS-Linux/sourceos-spec via PR #101, merged at commit 5e3ba19d54ba479c03088a6d504948f48f8dcb52.

Primary contract files to consume:

• schemas/CapabilityLedger.json
• examples/capabilityledger.json
• docs/runtime-observability-contracts.md
• docs/adr/0012-runtime-observability-capability-governance.md

Implementation focus for this repo:

1. Implement a CapabilityLedger reconciliation path for config, UI, runtime, server, plugin, policy, schema, transport, user, agent, and workspace claims.
2. Treat CapabilityLedger.effectiveState as the displayed and operational source of truth for capability availability.
3. Emit ledger entries on runtime startup, feature toggle, plugin load/unload, denied feature use, unsupported runtime/server response, and schema mismatch.
4. Surface owner refs, conflict refs, policy decision refs, evidence refs, and state reason in the UI/runtime diagnostics panel.
5. Prevent capability use until the ledger records enabled or an explicitly permitted degraded state.

Validation expectation:

• Use the upstream schema and canonical example as fixtures.
• Add tests for enabled, blocked_by_policy, unsupported_by_server, unsupported_by_runtime, missing_plugin, missing_schema, and failed.
• Avoid a parallel local schema unless it has a clear sync/generation path from sourceos-spec.

[mdheller]

Closed: CapabilityLedger contract and UI/runtime capability reconciliation shipped in PR #24 (copilot/implement-capabilityledger-contract) and PR #29 (work/capability-ledger-replay). Ledger tracks declared/requested/negotiating/available/enabled/degraded/blocked_by_policy/unsupported/missing_plugin/failed states, reconciliation occurs at startup/toggle/plugin load, conflicts generate receipts, and schema validates against sourceos-spec.