Package-level declarations

Types

Link copied to clipboard
fun interface AdmissionControl

An opaque admission gate over warp's free (CoordinationKind.Free) execution path.

Link copied to clipboard
fun interface AdmissionTicket

A handle returned by AdmissionControl.admit for an admitted task. WarpNode calls settle exactly once when the task completes, so an enforcement adapter can release or charge whatever it reserved at admission time.

Link copied to clipboard
@Serializable
sealed interface Affinity

A location-eligibility predicate — the "can I execute here" question, riding the opaque task envelope (H8, design §14.6, Model A).

Link copied to clipboard
class BobbinExchange(seam: Seam, val creel: Creel, scope: CoroutineScope, quilterConfig: QuilterConfig = QuilterConfig())

Lazy-bobbin exchange over a Seam.

Link copied to clipboard
@Serializable
value class BobbinHash(val value: String)

The content address of a bobbin — a warp kernel stored in the local Creel.

Link copied to clipboard
@Serializable
data class BobbinMeta(val hash: BobbinHash, val variantOf: VariantKey?)

A manifest entry: a content-addressed bobbin plus optional variant provenance.

Link copied to clipboard
@Serializable
data class CapSet(val tokens: Set<String> = emptySet(), val attributes: Map<String, String> = emptyMap())

The set of capabilities a peer advertises about itself — the value carried in a peer's slot of the capability board (H8, design §14.6).

Link copied to clipboard
sealed interface ClaimStrategy

Selects how WarpNode claims the tasks it owns on the consistent-hash ring.

Link copied to clipboard
object CompileOp

The well-known symbolic identity of the ring-dispatched compile op.

Link copied to clipboard
@Serializable
data class CompileRequest(val sourceHash: BobbinHash, val target: Target, val optLevel: OptLevel)

The arguments of a ring-dispatched compile task: which source kernel to compile, for which Target, at which OptLevelcompile(sourceHash, target, optLevel) → variantHash.

Link copied to clipboard
class ConvergentExecution<L : Quilted<L>>(val draft: Draft<*>, scope: CoroutineScope, initial: L)

A minimal local runtime that ties a Draft pipeline to a converging IncrementalResult.

Link copied to clipboard
class Coordinated<A>(val value: A)

A task that requires coordination — it is not safe to apply without a consensus round-trip. This is the escalation path: tasks that are non-idempotent, require strict exactly-once delivery, or whose correctness depends on a globally-agreed ordering must be placed here.

Link copied to clipboard
class CoordinationFree<A : Quilted<A>>(val state: A)

A task or contribution that is safe to apply without coordination — it lives in a join-semilattice, so concurrent applications from any number of peers converge to the same result regardless of order, duplication, or delivery gaps.

Link copied to clipboard
sealed class CoordinationKind

Tags each task in the warp queue as either coordination-free or coordinated.

Link copied to clipboard
class Creel

The local rack of loaded bobbins — a content-addressed store keyed by BobbinHash.

Link copied to clipboard
class Draft<out T>(val nodes: List<DraftNode>)

An immutable, inspectable dataflow graph that captures a distributed computation without running it.

Link copied to clipboard
data class DraftNode(val id: NodeId, val stage: DraftStage, val predecessors: Set<NodeId>)

One node in a Draft dependency DAG — a DraftStage plus its predecessor edges.

Link copied to clipboard
sealed class DraftStage

One step in a Draft dataflow graph.

Link copied to clipboard
class GuestRegion(val ptr: Long, val len: Long)

A guest-controlled window [ptr, ptr + len) of WASM linear memory, decoded from a packed warp_run result by unpackWarpResult.

Link copied to clipboard
class IncrementalResult<L : Quilted<L>>(initial: L)

A converging result backed by a join-semilattice — the observation side of monotone (convergent) query execution in :kuilt-warp.

Link copied to clipboard
@Serializable
value class Lane(val tag: String)

An opaque fair-share lane tag carried on a TaskDescriptor.

Link copied to clipboard
value class NodeId(val value: Int)

An opaque node identifier in a Draft dependency DAG.

Link copied to clipboard
fun interface Op

A single registered operation in the warp op registry.

Link copied to clipboard
@Serializable
value class OpId(val value: String)

A symbolic, stable name for a registered operation in the warp op registry.

Link copied to clipboard
fun interface OpRegistrar

A batch of op registrations, installable into an OpRegistry as one unit.

Link copied to clipboard

A local, startup-time registry that maps symbolic OpIds to their Op implementations.

Link copied to clipboard
@Serializable
class OpResult

The result of running an Op — opaque bytes (success) or a named error (failure), wrapped so it is safe to store in a CRDT.

Link copied to clipboard
@Serializable
enum OptLevel : Enum<OptLevel>

Optimization level of a compiled bobbin variant. Higher wins when several variants exist for the same Target. The spike's fake compiler produced a single level; the durable VariantKey address carries the level so a real optimizer (WasmOptimizer) can publish variants at distinct efforts for the same source.

Link copied to clipboard

The identity optimizer: returns bytes unchanged at every level — the OptLevel.O0 (passthrough) semantics.

Link copied to clipboard

A distributed results board — the dedup backstop for :kuilt-warp.

Link copied to clipboard
data class RosterSnapshot(val peers: Set<PeerId>)

A snapshot of the current peer roster that feeds the TaskRing.

Link copied to clipboard
@Serializable
enum Target : Enum<Target>

A compilation target — the platform a compiled bobbin variant is built for.

Link copied to clipboard
@Serializable
data class TaskDescriptor(val op: OpId, val args: ByteArray = ByteArray(0), val traceparent: String? = null, val pinnedOwner: PeerId? = null, val lane: Lane = Lane.ROOT, val affinity: Affinity = Affinity.Anywhere)

The unit of work that travels across the fabric — the task-descriptor envelope.

Link copied to clipboard
@Serializable
value class TaskId(val value: String)

An opaque, stable identifier for a single unit of work in the warp task scheduler.

Link copied to clipboard
class TaskRing(peers: Set<PeerId>, val vnodeCount: Int = 150, seed: Long = 0)

A consistent-hash ring that assigns tasks to peers in a deterministic, balanced way.

Link copied to clipboard
@Serializable
data class VariantKey(val sourceHash: BobbinHash, val target: Target, val optLevel: OptLevel)

The address of a compiled bobbin variant: which source kernel it was built from, for which Target, at which OptLevel. Recorded as the variantOf provenance on a BobbinMeta so a peer can discover "the compiled-for-my-target version of source S".

Link copied to clipboard
object Warp

Entry point for the :kuilt-warp module — distributed task scheduling over a connected mesh.

Link copied to clipboard
class WarpLazyFetch(val creel: Creel, val runtime: WasmRuntime, val opToBobbin: (OpId) -> BobbinHash?, val fetchTimeout: Duration = 30.seconds)

The all-or-nothing capability bundle that enables lazy bobbin fetch-and-run.

Link copied to clipboard
class WarpNode(val selfId: PeerId, seam: Seam, rosterFlow: Flow<Set<PeerId>>, scope: CoroutineScope, quilterConfig: QuilterConfig = QuilterConfig(), clock: () -> Instant, heartbeatConfig: HeartbeatConfig = HeartbeatConfig(), strategy: ClaimStrategy = ClaimStrategy.RingWithIntent(), registry: OpRegistry, coordinatedExecutor: suspend (TaskId) -> String = { taskId -> error("No coordinatedExecutor provided for task $taskId — supply one to WarpNode") }, raftNode: RaftNode? = null, lazyFetch: WarpLazyFetch? = null, target: Target? = null, admissionControl: AdmissionControl = AdmissionControl.OPEN, capabilityTtl: Duration = 30.seconds, epoch: Long)

Ties the warp foundation together over a real Seam.

Link copied to clipboard
@Target(allowedTargets = [AnnotationTarget.PROPERTY])
annotation class WarpOp(val id: String = "")

Marks a top-level val of type Op for build-time auto-registration.

Link copied to clipboard
@Serializable
class WarpStats : Quilted<WarpStats>

A CRDT-mergeable statistics map: per-source cardinality sketches gathered as HyperLogLog instances, so they converge when gossiped on the same anti-entropy as the rest of the warp state.

Link copied to clipboard
sealed class WasmException : Exception

Base class for all WASM-runtime failures.

Link copied to clipboard
class WasmExecutionException(message: String, cause: Throwable? = null) : WasmException

Thrown by an Op returned from WasmRuntime.load when the WASM module traps or raises an unhandled exception at runtime, or exceeds the sandbox's execution-time budget (WasmSandboxConfig.executionTimeout).

Link copied to clipboard
class WasmLoadException(message: String, cause: Throwable? = null) : WasmException

Thrown by WasmRuntime.load when a WASM module cannot be loaded into the sandbox.

Link copied to clipboard
interface WasmOptimizer

Injectable contract for a wasm→wasm optimizer — the transform a compiler node runs on a raw kernel before publishing the result as a gossiped variant.

Link copied to clipboard
interface WasmRuntime

Injectable contract for a sandboxed WASM execution environment.

Link copied to clipboard
data class WasmSandboxConfig(val maxMemoryPages: Int = 16, val executionTimeout: Duration = 1.seconds)

Configuration for the sandboxed WASM execution environment.

Link copied to clipboard

A distributed set of pending task IDs — the task-distribution primitive for :kuilt-warp.

Functions

Link copied to clipboard
infix fun Affinity.and(other: Affinity): Affinity

Conjunction: a and b is satisfied when both this and other are.

Link copied to clipboard
inline fun decodeWarpResult(packed: Long, memorySize: Long, read: (ptr: Long, len: Long) -> ByteArray): ByteArray

The bounds-checked warp-ABI result decode: unpackWarpResult + requireInBounds + one read of the validated window.

Link copied to clipboard
fun <A : Quilted<A>> joinAll(contributions: List<CoordinationFree<A>>): CoordinationFree<A>

Compute the join (least upper bound) of all values in contributions.

Link copied to clipboard

Compute the join (least upper bound) of all values in contributions, or null if the list is empty.

Link copied to clipboard

Lift a raw Quilted value into the coordination-free path.

Link copied to clipboard
fun <A : Quilted<A>, B : Quilted<B>> CoordinationFree<A>.monotoneMap(transform: (A) -> B): CoordinationFree<B>

Apply transform to this value's state, producing a new CoordinationFree with the transformed state. The caller is responsible for ensuring transform is itself monotone — i.e. that the output lattice's join is preserved under the mapping.

Link copied to clipboard
fun not(affinity: Affinity): Affinity

Negation: not(a) is satisfied when affinity is not.

Link copied to clipboard
fun opRegistryOf(vararg registrars: OpRegistrar): OpRegistry

Builds an OpRegistry populated by registrars, installed in the given order.

Link copied to clipboard
infix fun Affinity.or(other: Affinity): Affinity

Disjunction: a or b is satisfied when either this or other is.

Link copied to clipboard
fun requireInBounds(ptr: Long, len: Long, memorySize: Long)

Validates a guest-controlled window [ptr, ptr + len) against the live linear-memory size, in Long space so no operand can have sign-wrapped.

Link copied to clipboard

Returns a Flow of the current peer set derived from Seam.peers, suitable for passing to WarpNode as its rosterFlow.

Returns a Flow of voter PeerIds derived from this RaftNode's current us.tractat.kuilt.raft.ClusterConfig, suitable for passing to WarpNode as its rosterFlow.

Link copied to clipboard
fun shuttle(op: Op): Op

Declares a warp op so it reads like an ordinary lambda.

Link copied to clipboard

Unpacks a warp_run result — (resPtr << 32) | (resLen & 0xFFFF_FFFF) — into its unsigned pointer/length words.

Link copied to clipboard

Return a copy of this descriptor requiring affinity at its execution site — the producer-side eligibility tagging step, the sibling of TaskDescriptor.inLane(...). Everything else (op, args, trace, pin, lane) is preserved, so eligibility composes with a lane. This is the shipped .where { } surface: build a TaskDescriptor, tag it with where, and enqueue it on a WarpNode. Placement then hashes over the eligible subset.

Link copied to clipboard

Pair this value with other into a LatticeProduct, combining both states into a single coordination-free snapshot.