UCI — Universal Capability Interface

"What USB did for peripheral connectivity, UCI does for programs, AI agents, and services."

UCI is an open protocol for capability-based interoperability between software nodes — programs, AI agents, services, hardware bridges, and orchestrators — with governance, trust, and accountability built in from the start.

---

Cross-language interoperability

Direction	Status	Checks
Python → TypeScript	✓ PASS	29/29
TypeScript → Python	✓ PASS	42/42
Total	✓ PASS	87/87

Neither implementation calls the other's code. The only shared surface is the UCI specification and JSON schemas.

→ Full Interoperability Report

---

The four protocol objects

Object	Role
UCIManifest	Identity — who I am, what I can do, what my rules are
UCIInvocation	Request — do this, for this caller, with this payload
UCIResponse	Answer — what happened, what was the output, what did governance decide
UCIAuditSession	Record — tamper-evident, chain-hashed proof of everything that happened

---

Cryptographic node identity — v0.2 draft

Manifests and invocations can now carry an Ed25519 signature envelope over their canonical JSON, and orchestrators bind each node_id to its signing key via trust-on-first-use key pinning. A manifest signed with a different key than the one pinned is treated as possible impersonation and fails the handshake — key rotation is an explicit, audited operator action, never silent.

• New handshake stage: signature_verified — integrity failure prevents trust escalation
• Replay-resistant signed invocations (NonceCache on invocation_id)
• Six new audit events, including key_pin_mismatch
• Optional dependency: cryptography (lazily imported — the core remains dependency-free)

Status: Implemented in both SDKs with a bidirectional cross-language proof — Python-signed objects verify in TypeScript and vice versa, over byte-identical canonical form, with key pins carrying across languages. Run it: python uci-interop/run_signing_interop.py (12/12 checks).

→ Signing Envelope Draft Specification

---

Repositories

Repo	Description	Tests
uci-python-v2/	Python reference implementation	380 passing
uci-typescript/	TypeScript SDK	63 passing
uci-interop/	Cross-language interoperability harness	87/87 checks

---

Quick start

Python:

cd uci-python-v2
pip install pytest jsonschema
python run_rig.py          # live demo
python -m pytest test_rig/ # test suite
python uci_validate.py example_manifests/valid_document_service.json

TypeScript:

cd uci-typescript
npm install
npm test                   # compliance suite
open demo/index.html       # browser validator — no server needed

Interoperability:

cd uci-interop
python generate_report.py  # runs full cross-language proof, writes INTEROP_REPORT.md

---

Specification

The full protocol specification lives in uci-python-v2/docs/ — 23 documents covering every aspect of UCI.

Start here: uci-python-v2/SPEC.md

---

JSON Schemas

Three canonical schemas define the protocol's wire format, validated by both implementations independently:

Schema	URI
Manifest	https://uci-spec.org/schemas/uci_manifest_v0_1.json
Response	https://uci-spec.org/schemas/uci_response_v0_1.json
Audit Session	https://uci-spec.org/schemas/uci_audit_session_v0_1.json

Schemas live in both uci-python-v2/uci/schemas/ and uci-typescript/schemas/ — byte-for-byte identical.

---

Release

Current: v0.2.0-alpha — adds cryptographic node identity (Python reference)

→ Release Notes — v0.2.0-alpha → Release Notes — v0.1.0-alpha → Release Checklist → Changelog

---

Contributing

The single most valuable contribution is an external implementation — build a UCI node or orchestrator in Go, Rust, or any other language using only the JSON schemas and compliance suite as your guide.

→ Contributing Guide → Security Policy

---

Author

Leon Priest

UCI is an open protocol. The specification, schemas, and implementations are freely available for adoption under the Apache 2.0 licence.

---

UCI v0.1.0-alpha · © Leon Priest · Apache License 2.0