Skip to main content

Glossary

Every term the Orca Framework docs use, defined once. Each entry gives you one sentence and a link to the page that goes deeper.

Writing a workflow​

Action​

One step of a workflow that runs at a single device, such as shaking a plate or sealing it. It is the unit the runtime reserves a device for. See Actions.

Operation​

One call to a device: an aspirate, a dispense, a shake. This is the smallest unit of work, and one action issues one or more of them. See Actions.

Method​

A named, reusable sequence of actions. Actions inside a method can sit on different devices, and the runtime moves the labware between them. See Methods.

Labware thread​

The route one piece of labware takes through the lab: which methods run on it, where it starts and where it ends. Threads run in parallel, one per piece of labware. See Labware threads.

Workflow​

The top-level unit you submit: which labware threads exist, which one starts, what variables it accepts and which event handlers fire. See Workflows.

Variable​

A typed, validated value a workflow declares. You read it inside actions, and an operator overrides it at submit time or mid-run. See Variables.

Plates, tips and troughs​

Labware​

Anything that holds sample or reagent and moves around the lab: plates, tip racks, troughs, tube racks. See Labware.

Catalog​

The list of labware types the runtime knows about, one row per type, named by the labware_type string a template passes. A catalog row is not proof you can place that labware: most seeded rows have no model behind them, and the refusal only arrives when you try to register one. See Labware.

Labware template​

The description of a type of labware, which is what you write in your workflow. It names a catalog entry and carries no geometry of its own. See Labware.

Labware instance​

One physical piece of labware moving through the lab, with its own name and its own position. Workflows reference templates; the runtime tracks instances. See Labware.

Plate​

A microplate: 96, 384 or 1536 wells. Declare one with PlateTemplate, and pass with_lid=True if it starts lidded. See Labware.

Tip rack​

A rack of pipette tips. Its template has to say whether the rack starts full or empty. See Labware.

Tip spot​

One position in a tip rack, which either holds a tip or does not. Ask for the next ones that still hold a tip rather than naming positions by hand. See Labware.

Trough​

A reservoir holding bulk reagent. In simulation a trough can be declared as never running dry. See Labware.

Well​

One cavity in a plate or trough, with a volume the runtime tracks. Its capacity and dimensions come from the catalog entry the template names. See Labware.

Your lab​

Topology​

Your physical lab written down: which devices exist, where they sit, and which arms move labware between them. Defined once, separately from any workflow. See Topology.

Location​

A named position in your lab that can hold labware. It holds either a device or a passive resting spot such as a plate pad. See Topology.

Deck site​

One addressable position on a liquid handler's deck, for example mlstar_1/carrier-9-0. A thread can start or end at one, but it is not a routing stop of its own. See Topology.

Teachpoint​

The physical coordinates an arm needs to reach one named position, captured by jogging the arm there and recording where it is. See Transporters.

Device​

An instrument in your lab: a shaker, a sealer, a reader, a liquid handler. The device is what your workflow talks to. See Devices.

Transporter​

Anything that moves labware between locations: a robot arm, a rail carriage, a liquid handler's own on-deck gripper, or a person. See Transporters.

Translator​

A single carriage on a rail, such as a shuttle between two robot zones. Its taught positions are one physical seat seen from each zone, so it holds at most one piece of labware. See Transporters.

Resource pool​

A group of identical devices addressed as one. An action aimed at a pool runs on whichever member the runtime can reserve. See Topology.

Driver​

The code that talks to the hardware, or to a simulator standing in for it. The device is what your workflow calls; the driver is what moves the instrument. See Devices.

Capability​

A command a device can be sent. There is no separate registry: the methods on the driver's interfaces are exactly what it can do. See Devices.

Vendor surface​

A declaration that makes commands on a vendor object the driver holds, such as a gripper, visible and callable. Undeclared means uncallable. See Devices.

Grip profile​

Saved grip numbers for one labware type, used by every arm that carries it. An operator edits them without touching workflow source. See Move and pipetting parameters.

Move defaults​

Saved move numbers for one arm, applying everywhere that arm goes. A grip profile for a specific labware overrides them. See Move and pipetting parameters.

Access config​

A named approach and retract pattern for one position: a horizontal slide into a sealer, a vertical drop into a centrifuge bucket. A teachpoint references one, and it is the site layer of the move-parameter stack. See Move and pipetting parameters.

Running a workflow​

Submission​

A request to the runtime to run a workflow. It carries the run mode, any variable overrides, and the labware groups. See Submissions.

Execution​

One run of a workflow, created by a submission and stamped with its run mode. It accepts more work, then drains, then finishes. See Submissions.

Labware group​

A bundle of labware that travels through a workflow together. One submission carrying four groups runs four samples, each with its own copy of every thread. See Submissions.

Batch mode​

Whether a submission starts a fresh execution, which is the default, or joins one already running and still accepting work. See Submissions.

Run mode​

Which world a submission runs in: PURE_SIM, DEVICE_SIM or LIVE. Required on every submission; there is no deployment default. See Sim hierarchy.

Simulation​

Running a workflow against software stand-ins instead of instruments, so you can build and test one with no hardware. PURE_SIM never reaches the wire; DEVICE_SIM does, with simulated devices at the far end. See Sim hierarchy.

Runtime​

The long-lived service that operates your lab. It accepts submissions, schedules them, moves labware, fires events, and keeps the record of where everything is. See Runtime.

Daemon​

A local web service exposing the runtime over REST and an event stream, bound to 127.0.0.1. orca start launches it, and the CLI talks to it. See Runtime.

Facade​

One grouped part of the runtime's API, reached as a property: runtime.labware, runtime.devices, runtime.threads and the rest. See Runtime.

Deployment profile​

A named bundle of variable values loaded at submit time, so one lab can run a shared workflow with its own numbers. See Variables.

Spawn sentinel​

How a thread's labware arrives and leaves: an operator places it, a stacker dispenses it, or it stays on the deck between runs. See Labware threads.

Manual place​

A thread waiting for a person to put labware at a location, which is what a plain start location means. Simulation fulfils it instantly; a LIVE run waits until the operator says the labware is there. See Labware threads.

Scheduling​

Reservation​

A hold a thread takes on a device and the positions that device owns, so nothing else can use them while its action runs. Long holds are normal: a two-hour incubation holds for two hours. See Architecture.

Deadlock​

Threads each holding a reservation another one is waiting for. The runtime finds the knot and tells one thread to move its labware out of the way; what it cannot untangle it pauses for you. See Recovery.

Stall​

Every live thread blocked and none of them acting, holding that shape across repeated checks. The runtime pauses the execution and gives you something to act on instead of hanging. See Runtime.

Join​

A step a thread yields to take part in another thread's method instead of running one of its own. This is how tips, troughs and pooled plates meet the thread that uses them. See Labware threads.

Park​

A step that holds labware at a spot you declared until the runtime wakes the thread again. It only ever completes at a spot you named. See Labware threads.

Contributor thread​

A thread that feeds another thread's method rather than running one of its own: a tip rack, a reagent trough, a sample plate pooling into a final plate. See Labware threads.

Receiver​

The thread being fed. It loops, taking one contribution at a time, until its slot closes or fills, or its own labware runs out. See Workflows.

Slot​

A receiver's intake: how many more contributions it can take, and whether it is still open. See Workflows.

Contributes to​

The thread argument naming the receivers this thread feeds. It takes labware template names, not thread function names. See Labware threads.

Overflow​

What happens when a receiver is full or its labware is spent: start a fresh receiver, fail the workflow, or hand it to an operator. See Workflows.

When something goes wrong​

Failure policy​

What the runtime does when an action raises: pause the thread and wait for an operator, which is the default, or kill the thread. Set it on the action. See Failure policies.

Device fault​

A device whose command did not come back clean is marked faulted, and the engine will not drive that instrument at all until an operator clears it. A refusal that moved nothing does not fault a device. See Devices.

Incident​

A structured record of something worth tracking: what happened, where, how bad it is, and what response is suggested. An operator acknowledges it. See Recovery.

Pause site​

The place a thread stopped. It decides which recovery decisions the thread will accept, and the runtime publishes that list so you never have to guess. See Recovery.

Recovery decision​

The verb an operator answers a paused thread with: retry, re-run just the failed device call, continue, or abort the action, the method or the thread. See Failure policies.

Blocker​

One entry in the single list of everything stopping the run: a faulted device, a paused thread, a plate waiting on a person. Each one carries the remedies that clear it. See Runtime.

State and history​

Ledger​

The one place a physical fact is written. Where a labware is, what it holds, and what a pipetting head is carrying each have exactly one, and nothing else answers for them. See Runtime state.

Provenance​

How well an answer is known: UNKNOWN, KNOWN or STALE. UNKNOWN means nobody has ever said, which is not the same as empty. See Runtime state.

Stale​

There is a value, it is still the best one there is, and time passed with nothing watching since. Only a person's word clears it. See Runtime state.

Observation gap​

A stretch of time nothing recorded: a restart, an agent reconnecting, an error pause. It changes no number, and it stops earlier answers counting as current. See Runtime state.

Unsettled​

Anything the record cannot answer or now contradicts, gathered into one worklist with the verb that settles each row. See Runtime state.

Ops history​

The append-only list of every operation any action performed. Well volumes and tip counts are folded out of it on every read rather than stored as numbers. See Stores.

Store​

A small pluggable interface the runtime reads and writes one kind of state through. Every one ships with a working default you can swap out. See Stores.

Event​

A message fired on every status change: an action completed, a thread started, an execution finished. See Events.

Event bus​

Where a workflow's own events are published and where its handlers subscribe, scoped to that workflow's executions. See Events.

Sink​

A listener registered on the runtime that receives every event from every execution. Use one for audit trails, dashboards, or feeding another system. See Events.

Deployment​

Worktree​

The code files on disk in a hosted deployment, as opposed to what has been committed to git. A submission writes its file straight into it. See Code deployment.

Orca AI​

The hosted product that wraps this runtime with authenticated network access: REST, MCP and WebSocket for remote clients and AI assistants. Orca Framework's own daemon is localhost only. See Orca AI.

See also​

  • Quick Start: build and run a workflow in simulation, end to end.
  • Architecture: how the terms above fit together.
  • CLI overview: the commands an operator runs against a live deployment.