Cap n Proto primer

1. Defining a schema

Schemas live in .capnp files. Each struct is assigned a 64-bit file ID and field numbers are explicit, which lets you add fields later without breaking existing readers.

@0xb8d3e9c1f4a2b7d6;

struct InferenceRequest {
  id        @0 :Text;
  model     @1 :Text;
  prompt    @2 :Text;
  maxTokens @3 :UInt32 = 512;
  stream    @4 :Bool   = false;
}

2. Generating bindings

The compiler emits typed accessors for your target language. For TypeScript on the gateway and Rust on the worker, point capnp compile at the schema and check the generated files into the repo so CI does not need the toolchain.

• Run capnp compile -o ts schema.capnp for the gateway.
• Run capnp compile -o rust schema.capnp for workers.
• Pin the compiler version in tools/versions.lock.

3. Sending and receiving

Build a message in an arena allocator, then ship the raw segments over a socket. Readers traverse the buffer in place, so a 10 KB payload decodes in under a microsecond. Use the packed encoding when the wire is bandwidth bound, and the raw encoding when CPU matters.