Stdlib Portals

Version: v0.1
Last Updated: 2026-05-10

Distribution and resolution rules:

1. The stdlib is distributed as bundled Culsma source.
2. Frontend resolution injects the bundled stdlib before component expansion unless the caller explicitly disables bundled stdlib loading.
3. Stdlib workflow truth is expressed by bundled Culsma source, not by portal-specific compiler/runtime expansion rules.

Boundary:

1. Core language execution truth remains:
   • <<
   • with env
   • with constraint
   • repeat / if / break / continue
   • sep / frac / img / ecp / phy / stream
   • constructor/init path
2. Stdlib portals are upper-layer workflow APIs that lower to the core forms above.
3. The bundled stdlib defines runnable workflow skeletons; it is not a complete biological simulation library.
4. Legacy portals may remain documented for continuity, but they are not part of the stdlib target set.

SP.1 Stdlib Set

Portal	Availability	Source shape	Return policy	Lowering summary
Incubate	supported	Incubate(sample=..., temp=..., duration=...)	returns sample; statement-form may discard	with env(...) { hold(sample); }
Lyse	supported	Lyse(sample=..., buffer=..., duration=..., temp=...)	returns sample; statement-form may discard	with env + << [buffer] + sep(program=disrupt_program(...)) + << [lysate]
ExtractDNAPrecipitation	supported	ExtractDNAPrecipitation(sample=..., precip_buffer=..., wash_inputs=[...], dissolve_buffer=..., output=..., cleanup_temp=..., cleanup_duration=...)	returns output; statement-form may discard	precipitation skeleton over << + sep(program=centrifuge_program(...)) + with env
ExtractDNAColumn	supported	ExtractDNAColumn(sample=..., bind_buffer=..., wash_inputs=[...], elution_buffer=..., column=..., waste=..., output=..., cleanup_temp=..., cleanup_duration=...)	returns output; statement-form may discard	column skeleton over << + sep(program=filtration_program(...)) + with env
PCR	supported	PCR(sample=..., primers=..., cycles=..., annealing_temp=...)	returns sample; statement-form may discard	reaction workflow template over repeat + schedule + with env(thermal_program)
Electrophoresis	supported	Electrophoresis(sample=..., gel_type=..., stain=..., voltage=..., duration=..., readout_schema=...)	returns final data_ref; statement-form may discard	sep(program=field_program(voltage=...)) + << [stain] + img(quantity=customized, schema_ref=...)

Global rules:

1. Stdlib authoring supports both let-bound and statement-form component calls.
2. statement-form stdlib call discards the component return value.
3. Stdlib portals MUST lower to core language contracts; they MUST NOT introduce a second execution semantics.

SP.2 Portal Contracts

SP.2.1 Incubate

Signature:

Incubate(sample = tube_a, temp = 37C, duration = 30min);

Contract:

1. sample: target container.
2. temp: scalar temperature or thermal_program(...).
3. duration: required for the scalar-thermal Incubate portal because it lowers to a pure environment hold; forbidden when temp is a thermal_program(...).
4. Canonical lowering target is with env(...) { hold(sample); }; bare sample is content-facing in HoldTarget position.
5. Incubate(...) returns the target sample/container reference.

SP.2.2 Lyse

Signature:

Lyse(sample = sample_tube, buffer = lysis_input, duration = 10min, temp = 4C);

Contract:

1. sample: input sample container.
2. buffer: single-use actual lysis input container/aliquot for this step; default semantics add the whole provided input.
3. duration: lysis duration; the lysis workflow also passes this value to disrupt_program(...).
4. temp: lysis temperature.
5. Lowering target:
   • with env(thermal=temp, duration=duration) {
   • sample << [buffer]
   • let lyse_group = sep(sample=sample, program=disrupt_program(...));
   • sample << [lyse_group[0]]
   • }
6. The stdlib workflow does not materialize implicit alias names such as Lysate.
7. Lyse(...) returns the lysis target/sample reference.

SP.2.3 ExtractDNAPrecipitation

Signature:

ExtractDNAPrecipitation(
    sample = lysate,
    precip_buffer = precip_input,
    wash_inputs = [wash_1, wash_2],
    dissolve_buffer = dissolve_input,
    output = dna_out,
    cleanup_temp = 25C,
    cleanup_duration = 3min
);

Contract:

1. sample: lysate/sample container to extract from.
2. precip_buffer: single-use precipitation reagent input.
3. wash_inputs: ordered list of single-use wash inputs; list length determines wash rounds.
4. dissolve_buffer: single-use dissolve/resuspension input.
5. output: target output container.
6. cleanup_temp / cleanup_duration: cleanup incubation before re-clarification.
7. Lowering target is precipitation-specific << + sep(program=centrifuge_program(...)) + with env.
8. ExtractDNAPrecipitation(...) returns output.

SP.2.4 ExtractDNAColumn

Signature:

ExtractDNAColumn(
    sample = lysate,
    bind_buffer = bind_input,
    wash_inputs = [wash_1, wash_2],
    elution_buffer = elution_input,
    column = spin_column,
    waste = waste_tube,
    output = dna_out,
    cleanup_temp = 25C,
    cleanup_duration = 2min
);

Contract:

1. sample: lysate/sample container.
2. bind_buffer: single-use binding input.
3. wash_inputs: ordered list of single-use wash inputs; list length determines wash rounds.
4. elution_buffer: single-use elution input.
5. column: work container used as column/stage carrier.
6. waste: waste collection container.
7. output: final eluate container.
8. cleanup_temp / cleanup_duration: elution incubation before final filtration.
9. Lowering target is column-specific << + sep(program=filtration_program(...)) + with env.
10. ExtractDNAColumn(...) returns output.

SP.2.5 PCR

Signature:

PCR(sample = pcr_well, primers = "Panel_12Plex", cycles = 35, annealing_temp = 60C);

Contract:

1. sample: reaction container.
2. primers: stdlib workflow contract field; it is not interpreted as a natural-result simulation input.
3. cycles: cycle count used to build repeated thermal workflow.
4. annealing_temp: annealing segment temperature.
5. Lowering target:
   • repeat cycle in schedule(start=1, end=cycles, step=1) { ... }
   • repeated single-segment thermal_program(from=..., duration=...)
   • with env(thermal=thermal_program(...)) { hold(sample); }
6. PCR semantics are workflow-only. They do not imply natural amplification simulation, hidden product objects, or implicit material multiplication.
7. PCR(...) returns the reaction/sample container reference.

SP.2.6 Electrophoresis

Signature:

let gel_obs = Electrophoresis(
    sample = gel_lane,
    gel_type = "Agarose_1.5pct",
    stain = stain_input,
    voltage = 100V,
    duration = 30min,
    readout_schema = gel_obs_schema
);

Contract:

1. sample: already-loaded gel lane/container.
2. gel_type: gel chemistry/type descriptor retained for workflow audit.
3. stain: single-use actual stain input for this run.
4. voltage: electrophoresis voltage setpoint (Q[ElectricPotential]).
5. duration: run duration.
6. readout_schema: explicit structure declaration used for final image/data readout.
7. let-bound stdlib Electrophoresis(...) returns the final data_ref from lowered img(...).
8. statement-form stdlib Electrophoresis(...) is also allowed; it performs the same workflow and discards the final observation binding.
9. Lowering target:
   • let run_group = sep(sample = sample, program = field_program(voltage=..., duration=...));
   • run_group[0] << [stain];
   • let obs = img(sample = run_group[0], quantity = customized, schema_ref = readout_schema, save_raw = true);
10. Legacy continuity signature Electrophoresis(sample, gel_type, staining_method) is not the stdlib execution contract.

SP.3 Stdlib Set Summary

Stdlib set:

1. Incubate
2. Lyse
3. ExtractDNAPrecipitation
4. ExtractDNAColumn
5. PCR
6. Electrophoresis

SP.4 Legacy / Non-Stdlib Portals

SP.4.1 Measure

Classification: legacy continuity only

Rule:

1. Measure(...) is not part of the bundled stdlib target.
2. Statement-form Measure(...) is rejected as an unknown step.
3. let-bound Measure(...) is rejected through the semantic diagnostic contract, commonly as SEM_UNKNOWN_STEP.
4. Diagnostic code definitions and stage placement are specified in Chapter 8.
5. Authoring SHOULD directly use img(...), ecp(...), phy(...), or decomposition paths.

SP.4.2 Generic ExtractDNA

Classification: legacy continuity only

Rule:

1. Generic ExtractDNA(sample, method) is not a stdlib portal.
2. Authoring SHOULD use:
   • ExtractDNAPrecipitation(...)
   • ExtractDNAColumn(...)

SP.5 Conformance Boundary

Bundled stdlib sources, portal injection, portal expansion, and portal lowering must conform to the portal contracts in this document and the cross-links below. File names and test file names are not part of the stdlib portal contract.

1. Core operator/program contracts remain in Chapter 6.
2. Validation/diagnostic stage placement remains in Chapter 8.
3. Execution/model semantics remain in Chapter 9.