Architecture
Colloq is proposed as a language, compiler, runtime, and wire contract. Those components should be separable so the project can reuse proven infrastructure.
Text · visual editor · AI graph transactions
│ parse/project, resolve, type/effect/capability check
▼
Canonical semantic Colloq Conversation Graph
├── History graph: patches, evidence, lineage, promotion
│
│ endpoint-project, partition, place, schedule, specialize
▼
Signed execution plan
├── endpoint machines: one local protocol state machine per role
├── compute backends: native, accelerator DSLs, Nuro, framework interop
├── transports: shared memory, QUIC, Iroh, TCP, RDMA, collective libraries
├── storage: local, object, distributed log
└── control plane: discovery, identity, policy, rollout
Compiler
The compiler and graph store should perform progressively lower transformations:
- Accept a text import or typed graph transaction against a known content identity.
- Resolve types, shapes, effects, capabilities, holes, and failure contracts.
- Canonicalize and content-address the semantic Colloq Graph.
- Project the global conversation into compatible local endpoint machines.
- Partition those machines into cells and communication transitions.
- Accept a topology and capability inventory from the target environment.
- Produce and cost candidate placement, encoding, and transport plans.
- Emit signed artifacts and a reproducible plan manifest.
MLIR is a strong candidate for internal compiler infrastructure, but Colloq's portable semantics should not be defined merely as whichever MLIR dialects happen to exist.
Runtime
The runtime is responsible for:
- node discovery and authenticated membership;
- artifact loading and capability assignment;
- stream creation, flow control, and transport negotiation;
- conversation-state validation, choice propagation, delegation, and cancellation;
- clock and cancellation propagation;
- state checkpoints and deterministic replay where requested;
- metrics and causal tracing using stable program identities;
- controlled rollout, comparison, and rollback of variants.
The fast data plane should not route every message through a central coordinator. The control plane may establish policy and placement while cells communicate directly over the selected transport.
Each endpoint executes a projected local state machine. A frame that is type-correct but invalid in the current conversation state is rejected or handled by a declared failure transition.
Wire contract
The semantic graph fixes message meaning while an execution plan chooses representation. The first Colloq wire format should prioritize correctness and measurement over novelty:
- a small versioned envelope for identity, schema, deadlines, tracing, and capabilities;
- canonical schema hashes and compatibility rules;
- separate control and bulk-data paths;
- transport negotiation rather than one mandatory transport;
- zero-copy descriptors when both endpoints and the security policy permit them;
- no implicit code execution when decoding data.
Existing encodings and transports should be used until a benchmark demonstrates a material reason to replace them.
Evolution service
Evolution is an optional runtime service, not a privileged escape hatch. It receives candidates, validates them, runs bounded evaluations, records provenance, and asks the policy engine whether promotion is permitted. See evolution.md.
Candidates arrive as typed patches against an immutable parent graph. The active graph is never rewritten in place.
Interoperability
Initial interoperability should be pragmatic:
- a C ABI for embedding cells;
- import/export of a stable schema representation;
- adapters for Python and Rust host applications;
- tensor exchange through established array interfaces where possible;
- compiler hooks for existing kernel and model compilers.
The prototype should prove that Colloq adds semantic and performance value without requiring an entire ecosystem to be rewritten.
Current prototype
The first Rust implementation covers the top of this pipeline:
Conversation v0 JSON
├── direct import
└── Automerge collaborative draft
→ conflict-rejecting promotion gate
→ representation and semantic validation
→ global conversation state graph
→ client endpoint machine + server endpoint machine
→ verified, identified Colloq Plan v0
+ deterministic compact transition dictionary
→ lightweight sessions over shared endpoint graphs
+ strict plan/role/encoding preface on network connections
├── memory plan
├── length-delimited TCP plan
├── TLS-authenticated QUIC plan
└── mutually authenticated Iroh plan
→ optional Miren manifest + pinned container adapter
→ successful trace equivalence or declared terminal failure
Each endpoint checks the conversation name, experimental semantic hash, expected state, and sequence before accepting a frame. The compiler validates and projects once into an Colloq Plan with its own deterministic identity; sessions share immutable projected graphs. Memory, TCP, QUIC, and Iroh can serialize either the self-describing reference envelope or a plan-backed compact envelope containing only transition ID, sequence, and optional payload. Network peers first exchange a strict session preface binding plan identity, roles, and exact encoding. Iroh additionally binds both authenticated endpoint identities and the concrete TLS connection. Both encodings reconstruct the same semantic trace. The reference Generate workload completes normally, through cancellation, or at declared closed/timeout/reset/unreachable/uncertain terminal states without transport-specific application logic. A deterministic wrapper can fail an exact role, transport operation, and occurrence for repeatable, asymmetric counterexamples.
This runtime remains an experiment rather than a general deployment substrate. It is blocking, supports two static roles, and sends JSON payloads. QUIC authenticates a pinned ephemeral server certificate; Iroh authenticates persistent keys on both endpoints. Automerge contributes draft collaboration without bypassing Colloq validation, and Miren packages the current TCP server as a testbed rather than redefining placement semantics. Identity admission, authorization, key rotation, replay-resistant freshness, flow control, structural payload validation from Colloq type definitions, deadline enforcement, recovery, and distributed failure agreement remain unimplemented. The compact-wire measurement shows a 1.32× isolated transition improvement and a 1.11× warm-workload improvement, while total overhead remains above target. See pluggable substrates for the exact boundary.