Core Concepts

Culsma represents a laboratory protocol as source text that can be checked and executed by a kernel pipeline.

Protocol

A protocol is the top-level executable unit.

protocol PublicMinimal {
    ...
}

Protocols contain declarations and statements. The CLI runs a protocol through parse, compile, validation, planning, runtime execution, and replay.

Content

Content describes the material identity being tracked, such as a buffer, reagent, biosample, or fraction.

buffer(code = "BUF01", type = "water")

Content identity is distinct from where the material is located.

Container

A container is a logical vessel identity that can hold content.

tube(label = "Target", capacity = 100uL)

Runtime material state tracks container contents, quantities, and metadata.

Operation

Operations are executable protocol actions. The minimal public operation is a transfer:

target << [source:5uL];

Operations lower into plan steps and then execute through the runtime.

Environment

An environment block applies execution conditions to enclosed steps.

with env(thermal = 37C, duration = 10min) {
    hold(sample = reactor);
}

Environment conditions are execution context, not biological-result prediction.

Readout

Readout operations consume container state and produce structured data references.

let obs = phy(sample = reactor, quantity = temperature);

Readout results are data artifacts, not material mutations.

Plan

After validation and type checking, Culsma lowers source into a plan. The plan contains executable steps, dependencies, gates, and operation arguments.

Trace and Replay

Runtime emits events while executing the plan. Replay reconstructs runtime state from those events, which supports audit and reproducibility.