Machines API
Discover and bind physical machines, read their directory, and preflight, transfer, or control prints.
Machines API
Import browser-safe contracts from @taucad/runtime/machine. MachineClient exposes the admitted machines route; its MachinePrintRequestClient facet manages requests that require approval. Discovery, binding, preparation, transfer, and start are distinct operations. A successful preparation or upload never means a physical print has started.
Discovery and directory
MachineListProvidersInput lists registered MachineProvider descriptors. MachineDiscoverInput starts bounded discovery for a provider and configuration; the returned MachineDiscoveryFrame stream carries MachineDiscoveryEvent values. A MachineCandidate contains a transient MachineCandidateEndpoint and untrusted MachineClaimedIdentity. MachineBeginBindingInput starts a non-secret ceremony and returns MachineBindingOutcome; native code completes credentials and trust. MachineRemoveBindingInput produces MachineBindingRemoval when safe. machineCredentialReference creates the host-local reference to a saved credential, not a portable secret.
The directory's MachineListInput, MachineGetInput, and MachineWatchInput yield MachineDirectorySnapshot, MachineDirectoryEntry, and streamed MachineDirectoryFrame values. MachineDirectoryCursor resumes observation; it is not a mutation authority. Each entry pairs a stable descriptor with observed state and freshness.
Import prepareMachineWebSocket, PrepareMachineWebSocketInput, and PreparedMachineWebSocket from @taucad/runtime/transport/websocket. The helper probes an exact authenticated HTTP(S) endpoint. A 204 yields a RuntimeTransportFacet whose connect() opens a fresh channel; 403 returns not-granted and 404 returns unsupported. Redirects and URL credentials are refused. Wait for channel readiness after connecting.
MachineDescriptor records physical identity and capabilities. MachineEnvelope uses canonical metres. MachineToolCapability, MachineMaterialSystem, and MachineQuantityDeclaration describe tool, slot, and native-unit facts needed for compatibility checks. MachineSnapshot holds connection/readiness and MachineObservedSetup; the latter includes MachineObservedMaterial. Live MachineRunSnapshot, MachineTemperatureSnapshot, MachineFanSnapshot, MachineMaterialUnitSnapshot, MachineMaterialSystemSnapshot, MachineNetworkSnapshot, MachineLightSnapshot, and MachineAlertSnapshot carry observations, not commands. MachineObservation is the provider's pull-stream item.
Physical operations
MachinePreparePrintInput asks for read-only preflight of a MachineArtifactReference against observed setup; the MachinePreparedPrint result binds artifact, machine, configuration and setup digests with an expiry. MachineUploadPrintInput transfers exactly that preparation under a caller-retained operation id. MachineStartPrintInput also requires the accepted upload's transfer id and expected setup digest. MachineControlRunInput names cancel, pause, resume, or urgent-stop against the exact observed provider run. MachineReconcileOperationInput checks a prior uncertain effect. MachineRunOperationKind and MachineOperationKind distinguish run commands from upload.
The resulting MachineOperationReceipt is accepted, rejected, or unknown. MachineOperationSnapshot is the durable projection, including planned and sending states; preserve the original operation id and reconcile an unknown outcome rather than issuing a new physical effect. MachineCaptureStillClientInput returns a short-lived MachineStill only when the provider declares MachineStillCaptureCapability.
Print requests
MachineRequestPrintInput creates a PrintRequest for a PrintRequester. PrintRequestState distinguishes approval, transfer, start, and terminal outcomes; PrintRequestSummary is the list projection. MachineListPrintRequestsInput and MachineWatchPrintRequestsInput read and follow requests. MachineResolvePrintRequestInput supplies an approval decision; MachineWithdrawPrintRequestInput withdraws a pending request. These methods sit on MachinePrintRequestClient, not on a provider's raw session.
Saved machine settings
Import persistence helpers from @taucad/runtime/machine/settings. A MachineTypeId identifies a namespaced machine type; machineTypeIdSchema rejects unsafe path spellings. machineSettingsPath({ typeId }) returns .tau/machines/settings/<typeId>.json within the project. These files contain preferences, not credentials or permission to operate hardware.
MachineSettingsRecord stores version 1, the machine type, an active MachineProfileId, and named profiles. Each MachineSettingsProfile maps configuration IDs to SavedMachineConfiguration blocks with an exact source version and sparse JSON values. Inactive and unknown blocks remain preserved.
| Helper | Result and failure contract |
|---|---|
readMachineSettings({ bytes, typeId }) | Returns ReadMachineSettingsResult: an immutable current record or MachineSettingsFailure. Refusals distinguish invalid data, a newer record version, and a different machine type. Preserve refused bytes. |
serializeMachineSettings({ record }) | Validates and writes deterministic JSON with a trailing newline. Throws for invalid records or output above machineSettingsMaximumBytes (262,144 UTF-8 bytes). |
readMachineConfiguration({ settings, profileId, definition, signal }) | Returns ReadMachineConfigurationResult with absent, current, or refused status. Current SavedSettingsValues are deeply immutable. |
setMachineConfiguration({ settings, profileId, definition, values, signal }) | Produces a replacement record without I/O. Passing undefined removes that configuration block. Persist the returned record through a checked write. |
A SettingsSchema admits sparse JSON objects. A SettingsDefinition preserves the schema's input and output values: validation cannot inject defaults or transform persisted values. MachineProfileFailure reports a missing selected profile. MachineConfigurationFailure reports an unsupported configuration version or invalid values; neither refusal falls back to defaults.
MachineSettingsProvenance, validated by machineSettingsProvenanceSchema, captures project scope, type, profile, and exact configuration versions for a prepared job. Subsequent preference edits do not change captured provenance.
Host ownership
Import MachineSettingsOwner and its boundary types from @taucad/runtime/host. Construct it with an exact rooted filesystem supporting bounded streaming reads and checked writes, plus trusted definitions. Its read and subscribe methods return MachineSettingsSnapshot, distinguishing current, absent, refused, and unavailable records.
An edit supplies a MachineSettingsEdit: operation ID, type ID, captured base record, and proposed next record. MachineSettingsSave reports saved, conflict, refused, or uncertain. Keep the operation ID and call settlement after an uncertain result; do not reinterpret uncertainty as success. Call dispose when the owner is no longer used.