# kuilt > kuilt is a Kotlin Multiplatform library for apps whose devices talk to each other — phones, browsers, desktops and servers. It gives them one way to find each other and pass messages over whichever connection is available, shared data that stays in sync when two people change it at once or one of them was offline, and — where everyone has to agree on one order of events — a leader and a shared history. The same application code runs over a relay server, a local network, a direct link between two nearby phones or a browser connection, and over two peers or twenty. If you are a coding agent writing networking, session or shared-state code against kuilt, read the cookbook first. It is a lookup table from the thing you are about to hand-roll — a reconnect loop, a heartbeat, a seen-ids set, a merge rule — to the kuilt primitive that already does it, with a compile-checked snippet for each. Targets: JVM, Android, iOS, macOS and wasmJs. Every module below is published to Maven Central as `us.tractat.kuilt:`; import `us.tractat.kuilt:kuilt-bom` once and then declare modules without versions. The README links the current release. Links to `raw.githubusercontent.com` are markdown source; links to `https://tractat-us.github.io/kuilt/` are the rendered guide and the generated API reference. This file is generated from the repository by `.github/scripts/llms-txt.py` — from the cookbook's own headings, the guide's table of contents and the published modules' descriptions. Edit those, then re-run it; do not edit this file by hand. ## Start here - [kuilt](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/overview.md): The guide's opening page — what kuilt gives you, in plain language. - [README](https://raw.githubusercontent.com/tractat-us/kuilt/main/README.md): What kuilt is, and the Maven coordinates to add it to a build. - [Using kuilt in an application](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/usage.md): Setup, dependency wiring and the platform notes a consumer needs. - [API reference](https://tractat-us.github.io/kuilt/api/): Generated API documentation for every module, cross-linked. - [Guide](https://tractat-us.github.io/kuilt/guide/): The rendered guide, if you would rather read it as a site than as markdown. ## Cookbook for coding agents - [kuilt cookbook — for coding agents](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook.md): Read this before writing networking, session or shared-state code against kuilt: what you are about to build, and the kuilt primitive that already does it. The links below are sections of the agent cookbook index and its family files. - [Don't build this yourself](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook.md#dont-build-this-yourself) - [Families](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook.md#families) - [Consensus](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/consensus.md) - [Consensus & turns](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/consensus.md#consensus--turns) - [When one of the peers is a server](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/consensus.md#when-one-of-the-peers-is-a-server) - [Durable consensus state](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/consensus.md#durable-consensus-state) - [Fabrics](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/fabrics.md) - [Discovery](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/fabrics.md#discovery) - [Your own transport](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/fabrics.md#your-own-transport) - [Sending to yourself](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/fabrics.md#sending-to-yourself) - [Payload limits](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/fabrics.md#payload-limits) - [Long-lived pumps](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/fabrics.md#long-lived-pumps) - [A seam's terminal state](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/fabrics.md#a-seams-terminal-state) - [Durable storage](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/fabrics.md#durable-storage) - [Heddle](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/heddle.md) - [Fair share & placement](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/heddle.md#fair-share--placement) - [Otel](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/otel.md) - [Telemetry & log capture](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/otel.md#telemetry--log-capture) - [Reporting a failure that will be retried](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/otel.md#reporting-a-failure-that-will-be-retried) - [Replication](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/replication.md) - [Replicated data](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/replication.md#replicated-data) - [Scaling to many peers](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/replication.md#scaling-to-many-peers) - [Dealing cards nobody can peek at](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/replication.md#dealing-cards-nobody-can-peek-at) - [Dedup](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/replication.md#dedup) - [Archiving what the live replica forgets](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/replication.md#archiving-what-the-live-replica-forgets) - [Session](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/session.md) - [Rejoin & reconnect](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/session.md#rejoin--reconnect) - [Liveness & presence](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/session.md#liveness--presence) - [Per-member frames](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/session.md#per-member-frames) - [Host election & the lobby](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/session.md#host-election--the-lobby) - [Warp](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/warp.md) - [Where a task may run (location eligibility)](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/warp.md#where-a-task-may-run-location-eligibility) - [Code mobility](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/agent-cookbook/warp.md#code-mobility) ## Guide: Getting Started - [Install](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/install.md) - [Getting started](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/getting-started.md) - [Quick start](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/quick-start.md) ## Guide: Network Fabric - [How connections work](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/contract.md) - [Connections](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/fabrics.md) - [Nearby Apple devices](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/nw.md) - [Fabric kit](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/fabric-kit.md) - [Multipath](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/multipath.md) - [Composing a Seam](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/composing-a-seam.md) - [Scaling to many peers](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/partial-mesh.md) ## Guide: Consensus - [Consensus](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/raft.md) - [Picking a host](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/picking-a-host.md) - [Turn-based game bootstrap (kuilt-game)](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/game-bootstrap.md) - [Server-Cluster Topology](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/cluster-server-client.md) ## Guide: Replicated Data - [Replicated Data](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-overview.md) - [GCounter](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-gcounter.md): Counters - [GCounterDouble](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-gcounterdouble.md): Counters - [PNCounter](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-pncounter.md): Counters - [BoundedCounter](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-bounded-counter.md): Counters - [ResettableCounter](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-resettablecounter.md): Counters - [HyperLogLog](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-hyperloglog.md): Counters - [Count-Min Sketch](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-countminsketch.md): Counters - [Histogram](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-histogram.md): Counters - [DDSketch](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-ddsketch.md): Counters - [GSet](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-gset.md): Sets - [ORSet](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-orset.md): Sets - [TwoPhaseSet](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-twophaseset.md): Sets - [Bloom Filter](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-bloomfilter.md): Sets - [LWWRegister](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-lwwregister.md): Registers - [MVRegister](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-mvregister.md): Registers - [Gauge](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-gauge.md): Registers - [LWWMap](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-lwwmap.md): Maps - [ORMap](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-ormap.md): Maps - [RGA](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-rga.md): Sequences - [Fugue](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-fugue.md): Sequences - [Movable Tree](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-movabletree.md): Trees - [JsonCrdt](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-jsoncrdt.md): JSON Documents - [EphemeralMap](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-ephemeralmap.md): Presence & Activity - [Quilter](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-quilter.md): Live Replication - [Bolt](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/bolt.md): Keeping History - [Causal primitives](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-causal.md): Building Your Own - [Implementing your own CRDT](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/crdt-custom.md): Building Your Own ## Guide: Observability - [Device to dashboard](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/observability.md) - [Traces](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/otel-traces.md) - [Metrics](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/otel-metrics.md) - [Logs](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/otel-logs.md) - [Capturing](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/log-capture.md): Logs ## Guide: Testing - [Testing](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/testing.md) ## Guide: Internals - [Performance and Scaling](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/performance.md) - [All modules](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/modules.md) ## Guide: Playground - [Warp](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/warp.md) - [Following a job](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/warp-jobs.md): Warp - [Planning the work](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/warp-planning.md): Warp - [The compiler node](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/warp-compiler.md): Warp - [Fair share with Heddle](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/heddle.md) - [Inside Heddle](https://raw.githubusercontent.com/tractat-us/kuilt/main/Writerside/topics/heddle-accounting.md): Fair share with Heddle ## Modules: Contract & core - [kuilt-core](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-core/module.md): The kuilt contract — Loom, Seam and Swatch — with the InMemoryLoom reference fabric, MuxSeam channel multiplexing and CompositeLoom multipath bonding. ## Modules: Libraries layered on the contract - [kuilt-crdt](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-crdt/module.md): Delta-state CRDTs — counters, sets, registers, maps, sequences and JSON — as plain serializable values, usable with any transport or none at all. - [kuilt-quilter](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-quilter/module.md): Live CRDT replication over a kuilt Seam: delta exchange, causal garbage collection and anti-entropy. - [kuilt-store](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-store/module.md): Durable key-to-bytes storage for Kotlin Multiplatform: a write returns only once the bytes will survive a crash, with a crash-safe implementation per platform. - [kuilt-bolt](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-bolt/module.md): Write-only history archive kept beside a live CRDT replica, so a server can keep a year of edits while the phone feeding it keeps an hour. - [kuilt-raft](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-raft/module.md): Raft consensus over a kuilt Seam: leader election, log replication, snapshots, dynamic membership, linearizable reads and leadership transfer. - [kuilt-cluster](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-cluster/module.md): Server-cluster facade over kuilt-raft: a voter core with a learner periphery, learner-to-leader forwarding, and cross-relay failover. - [kuilt-game](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-game/module.md): Turn-based game sessions over kuilt-raft: propose and commit typed actions, apply them optimistically, and roll back deterministically. - [kuilt-deal](https://tractat-us.github.io/kuilt/api/kuilt-deal/index.html): Cryptographically fair card dealing and dealer-less random seed agreement over a kuilt Seam. - [kuilt-gossip](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-gossip/module.md): Partial-mesh overlay for a kuilt Seam: broadcast floods to a few neighbours rather than everyone, so large sessions scale. - [kuilt-heddle](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-heddle/module.md): Fair-share scheduling of one pooled resource across peers with no central referee, and it keeps working while the network is partitioned. - [kuilt-liveness](https://tractat-us.github.io/kuilt/api/kuilt-liveness/index.html): Peer-liveness detection over a kuilt Seam: heartbeats, partition events and reachability. - [kuilt-session](https://tractat-us.github.io/kuilt/api/kuilt-session/index.html): Membership-aware Room over a kuilt Loom: admit/identify handshake, roster, reconnect tokens and partition detection. - [kuilt-stream](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-stream/module.md): Wraps a byte stream as a kuilt Connection, with length-prefix framing and oversize protection. ## Modules: Fabrics & discovery - [kuilt-websocket](https://tractat-us.github.io/kuilt/api/kuilt-websocket/index.html): Ktor WebSocket fabric for kuilt. - [kuilt-tcp](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-tcp/module.md): Raw TCP fabric for kuilt, on JVM and Android. - [kuilt-nw](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-nw/module.md): Apple Network.framework peer-to-peer fabric for kuilt: nearby devices find each other and connect directly, with no server. - [kuilt-multipeer](https://tractat-us.github.io/kuilt/api/kuilt-multipeer/index.html): Apple Multipeer Connectivity fabric for kuilt. Superseded by kuilt-nw. - [kuilt-nearby](https://tractat-us.github.io/kuilt/api/kuilt-nearby/index.html): Google Nearby Connections fabric for kuilt. - [kuilt-webrtc](https://tractat-us.github.io/kuilt/api/kuilt-webrtc/index.html): WebRTC data-channel fabric for kuilt. - [kuilt-mdns](https://tractat-us.github.io/kuilt/api/kuilt-mdns/index.html): Bonjour/mDNS discovery for kuilt. ## Modules: Observability - [kuilt-otel](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-otel/module.md): Offline-first OpenTelemetry: record traces, metrics and logs on any device and have them reconcile when connectivity returns, with no duplicates and no data loss. - [kuilt-otel-tap](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-otel-tap/module.md): Pull the logs off a running device by joining it as a peer and reading the offline-first buffer it already keeps. - [kuilt-otel-logging](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-otel-logging/module.md): Routes an app's kotlin-logging output into the kuilt offline-first telemetry buffer, through one call on every platform. - [kuilt-otel-logback](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-otel-logback/module.md): Captures Logback output — including other libraries' — into the kuilt offline-first telemetry buffer. - [kuilt-otel-log4j2](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-otel-log4j2/module.md): Captures Log4j2 output — including other libraries' — into the kuilt offline-first telemetry buffer. - [kuilt-otel-sdk](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-otel-sdk/module.md): Bridges an existing OpenTelemetry SDK setup into the kuilt offline-first telemetry buffer, trace-context propagation included. - [kuilt-otel-otlp](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-otel-otlp/module.md): Forwards buffered spans, logs and metrics to any OTLP/HTTP collector when the network returns, sending only what the endpoint has not already received. ## Modules: Warp — the coordination-free distributed scheduler - [kuilt-warp](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-warp/module.md): Spreads a pile of work across whoever is connected, with no central scheduler and no peer doing the same job twice. - [kuilt-warp-runtime](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-warp-runtime/module.md): The sandbox that runs code another peer sent you: a walled-off WASM engine with no files, no network, no clock, and no way to run forever. - [kuilt-warp-compiler](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-warp-compiler/module.md): Real Binaryen wasm-opt optimizer for warp compiler nodes (bundled, extract-and-exec). - [kuilt-warp-ksp](https://github.com/tractat-us/kuilt/tree/main/kuilt-warp-ksp): KSP symbol processor for warp: generates OpRegistrar wiring for @WarpOp-annotated ops. - [kuilt-warp-planning](https://tractat-us.github.io/kuilt/api/kuilt-warp-planning/index.html): Coordination-cost model and planner for warp: scores what a pipeline would pay and rewrites it to minimise that. - [kuilt-warp-ml](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-warp-ml/module.md): Federated learning over warp: train one shared model from everybody's data without anybody handing over their data. - [kuilt-warp-otel](https://tractat-us.github.io/kuilt/api/kuilt-warp-otel/index.html): Records warp execution metrics — executions, duplicates, failovers — into a kuilt-otel exporter. Idempotent under retry. - [kuilt-warp-heddle](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-warp-heddle/module.md): Fair share for warp: express that interactive work gets more of the grid than batch work, without changing how warp picks who runs what. ## Modules: Conformance & test support - [kuilt-conformance](https://tractat-us.github.io/kuilt/api/kuilt-conformance/index.html): Conformance TCKs (SeamConformanceSuite, RoomConformanceSuite) for kuilt fabrics and rooms. - [kuilt-test](https://tractat-us.github.io/kuilt/api/kuilt-test/index.html): Shared test utilities and fakes for kuilt, built on kuilt-core. - [kuilt-session-test](https://tractat-us.github.io/kuilt/api/kuilt-session-test/index.html): Session test support (FakeRoomFactory, …) for kuilt. - [kuilt-raft-test](https://tractat-us.github.io/kuilt/api/kuilt-raft-test/index.html): Raft test harness (FakeRaftNode, …) for kuilt. - [kuilt-deal-test](https://tractat-us.github.io/kuilt/api/kuilt-deal-test/index.html): Conformance TCK for kuilt CommutativeScheme implementations. - [kuilt-gossip-test](https://tractat-us.github.io/kuilt/api/kuilt-gossip-test/index.html): Gossip test support for kuilt: a started in-memory star of GossipSeams, with a handle for admitting a fresh client mid-test. - [kuilt-warp-test](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-warp-test/module.md): Warp test infrastructure: the sandboxed-WASM conformance TCK and a deterministic virtual-time multi-node simulator. - [kuilt-otel-tap-test](https://raw.githubusercontent.com/tractat-us/kuilt/main/kuilt-otel-tap-test/module.md): Test and CI support for live-tailing the logs of a tapped device over kuilt-otel-tap. ## Modules: Packaging - [kuilt-bom](https://github.com/tractat-us/kuilt/tree/main/kuilt-bom): Bill of Materials for kuilt — import once to align all module versions. ## Optional - [Architecture](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/architecture.md): The design behind the contract — read this to extend kuilt, not to use it. - [Writing a new fabric](https://raw.githubusercontent.com/tractat-us/kuilt/main/docs/extending-fabrics.md): How to put a transport kuilt does not ship behind the same contract.