# Native tcode and separate workcell services

Python runs in the solver. Serialize real `tcode-api==1.40.1` TCodeScript models
through `workcell.Workcell.validate(script)`, then `execute(script_id)`. It is a
supported SDK subset and symbolic workcell, not a hardware connection.

```python
import tcode_api.api as tc
from workcell import Workcell
cell = Workcell()
state = cell.state()
script = tc.TCodeScript(
    metadata=tc.Metadata(name="initial-declaration", timestamp="2026-11-12T00:00:00Z",
                         tcode_api_version="1.40.1"),
    commands=[tc.ADD_ROBOT(id="r", descriptor=tc.RobotDescriptor(serial_number="ORG-ROBOT"))])
checked = cell.validate(script)
result = cell.execute(checked["script_id"])
```

The public state shows labware, well names, capacities, contents, jobs, tips and
script cursors. Culture density/differentiated regions require an image; cell
concentration is hidden until counting. Images/counts are synthetic instrument
outputs. Access completed image results in `state['jobs'][...]['result']`; the
completed hemocytometer result is `state['current_count']`.

## Supported SDK commands

ADD_ROBOT, ADD_TOOL, ADD_LABWARE, RETRIEVE_TOOL, RETURN_TOOL, SWAP_TO_TOOL,
MOVE_TO_LOCATION, PICK_UP_PIPETTE_TIP, DISCARD_PIPETTE_TIP_GROUP, ASPIRATE,
DISPENSE, PICK_UP_LABWARE, PUT_DOWN_LABWARE, WAIT, PAUSE and COMMENT.
Other SDK commands and unknown fields are rejected. Fleet state persists across
scripts. Register each physical entity once. Tools are SingleChannelPipette
(serial ORG-P1000 or ORG-P20), EightChannelPipette (ORG-MULTI) and Gripper (ORG-GRIPPER).
The mounted hardware determines capacity; descriptors cannot enlarge it.

Labware uses WellPlateDescriptor(tags=['org:NAME']), except tips/tips8 use
PipetteTipBoxDescriptor and waste uses TrashDescriptor. Native aliases can be
chosen freely; tags bind to the supplied physical inventory. Custom geometry is
unsupported. Public names: source, aggregate, final, harvest, batch, dose,
reservoir, count, pbs, accutase, sasai1, sasai2, water, dmso, Y27632, SB431542,
IWR1e, tips, tips20, tips8 and waste. Containers have a single index-zero position;
source/final six-well and aggregate 96-well indices are row-major.

Use LocationAsLabwareIndex with TOP or BOTTOM and an identity 4x4
location_offset plus translation **in metres**. SAFE paths are required between
wells; DIRECT is allowed within a well. Custom flange, rotation, grasp and
trajectory transforms are unsupported. The fixture radii are 3 mm for 96-well
and 17.4 mm for six-well labware; x offsets ≥0.8 radii designate wall withdrawal.
Below-floor and outside-wall plate targets are rejected. These checks are not
robot collision-clearance validation.

ASPIRATE/DISPENSE require a mounted pipette, actual tips and a current target.
ValueWithUnits uses `magnitude` and `units`, e.g. magnitude=100,
units='microliter'; speed uses 'microliter/second'. The modeled ranges are P20: 2–20 µL, P1000: 100–1,000 µL, and eight-channel: 10–200 µL per channel; tip capacity matches the selected instrument. Split large transfers
explicitly. Native speed advances simulated duration; 0–1,000 µL/s is supported
with zero excluded. No liquid is automatically split into strokes.

Pick P20 tips from tips20 and P1000 tips from tips; the eight-channel head picks eight consecutive tips
from tips8. A top-row index 0–11 on aggregate selects the entire column A–H.
A 100 µL multichannel aspiration from reservoir consumes 800 µL; its dispense
places 100 µL in each of eight addressed wells. The eight-channel head cannot
span six-well labware. Tip positions are finite and cannot be reused.

Position and aspiration determine which suspended and settled material is collected. A completed aspiration and dispense back into the same pool records a mixing cycle. The conical has a modeled 20 µL residual heel. The sample tube is tagged sample and the dye trypan. Select the disposable slide with counter, load the count position, and call count to insert and read the slide.

Gripper transport uses PICK_UP_LABWARE and PUT_DOWN_LABWARE with
LabwareHolderName(robot_id='r', name=SITE). Sites: deck:1, deck:2, deck:3,
incubator, centrifuge, imager. Labware must be closed; park tips first. The
centrifuge is physically locked while spinning. Removing an incubating source
early cancels incubation and retains its actual elapsed time for grading.

## Services

`cell.service(OP, **fields)`:

| OP | Required fields |
| --- | --- |
| lid | labware, closed (boolean) |
| retrieve | labware (sasai1, from the fridge) |
| tilt | enabled (boolean, source on deck) |
| thaw | labware |
| equilibrate | labware, temperature_c |
| image | labware (source) |
| clean_clusters, scrape | none; operator works on open source on deck |
| gentle | enabled (boolean acknowledgement) |
| incubate | labware, seconds, temperature_c |
| spin | labware (harvest), seconds, rcf |
| counter | kind: reusable or disposable |
| count | none; load the count chamber first |
| wait | seconds |
| finish | none |

Jobs expose ready_at; advance simulation time, do not sleep in real time.
Only a job's target is locked, allowing medium preparation during incubation
and centrifugation. Warm/thaw durations are fixed fixture timings; biological
incubation/spin durations and temperatures are graded from actual execution.

`gentle` acknowledges handling intent; it does not replace actual native
pipetting. No numeric gentle-flow threshold was supplied, so none is invented.
The source releases cells through native pipetting.

## Execution, recovery and evidence

Validation checks schema/version/type/quantity bounds. Runtime checks resource,
capacity, access and instrument prerequisites. Scientific mistakes such as wrong
PBS temperature, rcf, medium, duration, feed amount or calendar execute when
physically supported and are graded independently. Accutase is supplied ready for use. `ok` reports execution, not scientific success.

Scripts commit command by command. A mechanical error rolls back only that
command; earlier aspiration/dispense and tip contents remain. Resume the same
script ID at its saved next_command, or build a replacement against current
state. Completed IDs are idempotent. PAUSE returns with an intact cursor.
No client operation automatically retries transfers. Requests are bounded to
1 MB, each script to 2,000 commands and the episode to 4,096 script IDs.

The solver has no runtime import, reset endpoint, journal or grader access.
A separate verifier replays the simulator-owned journal exactly before emitting
a reward. Only the grader assigns milestone PASS/FAIL. Internal conservation
faults are terminal. Media arithmetic and scientific assumptions are in
PROTOCOL.md and MEDIA.md, not hidden in runtime error strings.
