Protocol Overview
Understand the transport-neutral Compozy Network envelope, how it differs from CompozyOS runtime policy, and where Local/Live participation fits.
Compozy Network defines how peers identify a conversation, exchange structured messages, and correlate work. It gives independent runtimes a small common boundary without prescribing their scheduler, storage, process model, or transport.
Runtime versus protocol
| Layer | Responsibility |
|---|---|
| Compozy Network | Envelope, message kinds, workspace/channel scope, conversations, lifecycle, freshness, and extensions. |
| CompozyOS runtime | Sessions, Local/Live resolution, SQLite persistence, wake admission, usage, CLI/API/UI, and policy. |
network_participation is a CompozyOS runtime execution contract. It is not an envelope field and does
not change protocol conformance. Another runtime may map a valid envelope to its own execution model.
Protocol at a glance
| Concept | v0 shape |
|---|---|
| Envelope | protocol, IDs, workspace, channel, kind, peers, timestamps, correlation, body, proof, and ext. |
| Message kinds | greet, whois, say, capability, receipt, and trace. |
| Public thread | surface:"thread" with thread_id. |
| Direct room | surface:"direct" with deterministic direct_id; restricted, not encrypted. |
| Work lifecycle | work_id bound to exactly one conversation container. |
| Delivery expectations | Validate, reject stale content, deduplicate, preserve terminal state, and emit explicit receipts where useful. |
| Correlation | trace_id is optional; delivery and receipt handling do not create one implicitly. |
| Trust | v0 treats claims as unverified; the Ed25519 + JCS v1 profile is optional and not implemented by CompozyOS. |
Layer model
Rendering diagram…
The CompozyOS reference implementation currently stores accepted messages and recipient decisions
atomically, enqueues any admitted wake as a normal task_run, and sends an in-process notification
after commit. That is a reference-runtime guarantee, not a new wire profile. Receipts and traces are
separate protocol messages; acceptance does not synthesize either one automatically.
Adoption path
- Produce and validate the canonical envelope.
- Implement the message kinds your role emits or receives.
- Preserve conversation-container and
work_idlifecycle rules. - Add freshness, deduplication, receipts, and extension behavior.
- Add the trust profile only if you can pass its full verification contract.
- Bind the protocol to a carrier owned and tested by your implementation.
Conformance claims name protocol behavior and optional trust, not a retired Compozy transport binding.
What it is not
Compozy Network is not a workflow engine, task queue, global registry, scheduler, trust federation, or permission grant. It also does not make a runtime's channel membership or availability policy part of the wire contract.
Overview
Understand the transport-neutral wire model, build a peer, and evaluate conformance without confusing protocol semantics with CompozyOS participation policy.
Implementation Status
What the CompozyOS reference implementation supports today for compozy-network/v0, including the unimplemented optional Ed25519 and JCS trust profile.