Crates and clients

Toki is a Cargo workspace of Rust crates plus a generated TypeScript client. None of them is published to a package registry yet; use them from the repository.

Rust crates

Crate	What it holds
toki	The binaries (toki, toki-worker, toki-benchmark) and the library behind them: coordinator, network worker, build coordinator, client, daemon and updates, adapters, CAS, materialiser, checkouts, source providers and toolchain provisioning.
toki-core	The coordination core: identities, supersession and action keys, hermeticity classification, placement, containment, source manifests and identities, selection records, the receipt payload schemas, and injectable clock, I/O and scheduler seams. It owns no process, thread, socket or wall clock of its own.
toki-store	The durable store: a single-writer SQLite (WAL) database of jobs, attempts, leases, fencing epochs, receipts, idempotency keys, credentials and the publication outbox.
toki-transport	The versioned gRPC contract (toki.v1) and authenticated local and remote endpoints.
toki-client-gen	Generates the toki client operation table and the TypeScript client from the versioned client schema, and checks they are up to date.
toki-tests	The test history model: language-neutral test identities and the run, result and attempt records history is built from. Storage and analysis are planned.

toki-core

toki-core is designed so the same code runs against the operating system and against deterministic test doubles. Time comes through a clock seam, commands through a command I/O seam, concurrency through a scheduler seam, and identity minting through an id source.

Its main modules:

Module	Purpose
action_key	versioned action keys over every input that can change a result
hermeticity	action kinds and their hermeticity classes
supersession	supersession keys: landing target, operation and configuration
placement	platform requirements for results
containment	per-command limits and the containment report
source	source manifests and provider-qualified identities
checkout	the pinned per-platform Git checkout reference
selection	dependency-selection records and launch manifests
evidence	the toki.execution and toki.terminal payloads
adapter	the versioned language adapter boundary
workload	per-attempt resource accounting

toki-store

The store is the authority for leases, fencing and publication. Receipts and their outbox entries commit together; receipts, payloads, observations and ended attempts are immutable and never deleted. Schema upgrades are transactional and keep earlier records.

Its correctness is checked by an independent state machine that replays seeded scheduler histories (admission, lease takeovers, expired and delayed reports, retries, publication, restarts) and by crash tests that interrupt writes at every sync boundary.

toki-transport

All remote connections use HTTPS with an explicitly trusted CA and a matching server name; there is no plaintext remote mode. Clients and workers have separate random 256-bit bearer tokens; only digests are stored.

Peers call Negotiate with their role and a version range before anything else. Additive fields may be added within major version 1; removing fields or changing mandatory meaning requires a new major version. Workers open a bidirectional Work stream to the coordinator and expose no listener of their own.

The protocol source is proto/toki/v1/transport.proto in the crate. Rust bindings are generated at build time with a vendored protoc, so no system protoc is needed.

Language adapters

Adapters are compiled into toki behind a versioned, in-process Rust interface. Each adapter plans commands with their inputs and outputs, and parses results.

Adapter	Plans
rust	cargo <operation> --message-format=json <flags>; understands build, check, test, bench, run, doc, clippy, rustc and rustdoc, and parses Cargo's JSON messages
js	node <flags>, with the script path as the first flag
project-script	one opaque project script (such as a Node gate.mjs) in a private copy of the checkout

These are whole-command adapters and make no hermeticity claims. Both rust and js advertise whole-run test evidence and no dependency completeness.

TypeScript client: @toki/client

Item	Value
Package	@toki/client, version 0.1.0
Location	clients/typescript in the repository (not published to npm)
Format	dependency-free ES module (toki-client.mjs) with declarations (toki-client.d.mts)
Runtime	Node 18 or later, with a toki executable available
Schema	toki.client 1.3

The client is generated: do not edit it by hand. After changing the schema or protocol, regenerate it from the repository root:

cargo run -p toki-client-gen --locked -- --write

CI runs the same generator with --check and fails when the generated files are out of date. See Client for usage.