Expand description
§lm-provision-driver
§Architecture
The operator / pod-manager half of the push driver protocol
(08-push-driver-protocol.md) plus the append-only apply ledger it
feeds (09-apply-report-and-ledger.md §Ledger) — the Phase G build
target. The crate split from lm-provision itself is an
implementation judgment 08 §Stability leaves open (“driver
implementation home … internal — the protocol, not the caller, is
the contract”).
Applying a profile happens on the pod, never here. That is
driven through the already-frozen CLI contract (07-cli.md) of the
Phase F provisioner binary (lm-provisioner), from the outside, over the
transport-agnostic upload / invoke / collect shape 08 defines — so
no effect an apply causes is an effect this crate performs. The
effects this crate does perform itself are the machine ones:
infra::acquire runs the provider’s CLI and creates a billable
machine, and infra::Acquired’s release destroys one.
What it does read from the library is the part an operator host has
to know before it connects: session parses, validates and hashes
the profile in process, because the host cannot run the musl
artifact it is about to push and the hash has to be comparable to
the pod’s; infra reads the profile’s machine requirements to
decide what to acquire. The first is a question about a profile
rather than execution of one; the second is where rendering ends
and acquiring — the spending call — begins.
§Modules
transport— thetransport::Transporttrait plus the sharedtransport::PodPaths/transport::ExecOutput/transport::TransportErrortypes every implementation shares (08 §Driver steps: “transport-agnostic … SSH, provider exec API,docker execall satisfy it”). Two implementations ship:local_execandssh. Adocker exectransport is a documented extension point and is not among them.local_exec—local_exec::LocalExecTransport, which runs the provisioner binary on the driver’s own host.driver—driver::run, the upload → hash-integrity-check → invoke → collect sequence (08 §Driver steps) driven against anytransport::Transport, plusdriver::hash_locallyfor the operator-side pre-upload hash 08 describes running “locally first”.ledger— the append-only ledger (09-apply-report-and-ledger.md §Ledger):ledger::append/ledger::list/ledger::get. The module itself now lives inlm-provision-protocol, the neutral permissive side of the license boundary, because the AGPL control plane takes custody of the same file; it is re-exported here, so everylm_provision_driver::ledger::*path a caller already writes keeps resolving.acquisition— the append-only acquisitions record (09-apply-report-and-ledger.md §Acquisitions record): one row per machineacquirecreated, one per machine given back, andacquisition::outstanding, the list a sweep works from. It lives inlm-provision-protocolfor the same reason the ledger does — the control plane reads the same file — and is re-exported here beside it.ssh—ssh::SshTransport, the SSH realization of the seam (08 §Session contractConnectionSpec): scp upload, explicit identity file, secrets over stdin (08 §Secret delivery).session—session::run, the session contract’s steps 0-5 with per-step gates (session::StepPlan); the shapelm-provision applyexposes as a one-shot CLI.infra—infra::Infra, the target a machine is placed on, with one implementation per target: what it can provide, the request that would obtain a machine meeting a profile’s requirements, and how to read one back and give it up — plusinfra::acquireandinfra::Acquired, which send that request and later destroy the machine: the crate’s two calls that create and stop bills.inventory— what a platform says it is running, read throughinfraand rendered as the one JSON document both the operator CLI’smachine listand the MCPlm_machine_listtool return. A read: it has no release path at all.prices— the price record’s writer (09 §Price record): ask a platform what its models cost and append what changed, so the inventory’s join has something to stand on. It writes that one file and reaches no machine.credentials— where a target’s credential is resolved from, and what is reported when it is not there.balance— what a platform this tool spends from says is left on the account (09 §Endpoint inventory,balance): RunPod, Vast and DeepInfra say, each in its own shape and sign; Together does not, and a name this tool has no adapter for is not asked at all —Ok(None)is that answer rather than a failure to ask. A read, over the platform’s own HTTP API, with the key travelling by name.probe— one token, now: the one-token completion that finds an exhausted account (402) or a dead key (401) before a run does. It spends money, which is why nothing here runs unless asked for.cost— what a run cost: oneusagedocument (in the shape the platform states it, translated at the door) priced by the record’s row for its (provider, model) at an instant. A reading, likeinventory: it writes nothing and reaches no machine.image— whether the image a profile names exists in its registry, asked before a machine exists to pull it and fail.provisioner— where the provisioner comes from: the CI-built, version-pinned, checksum-verified release asset, cached locally, so an apply needs a network rather than a toolchain.
Modules§
- acquisition
- Append-only acquisitions record (09-apply-report-and-ledger.md
§Acquisitions record): one row per machine the driver created, in
the same JSON Lines shape and with the same discipline as
crate::ledger. - balance
- What a platform this tool spends from says is left on the account
(09 §Endpoint inventory,
balance). Three of the four say — RunPod, Vast, DeepInfra — each in its own shape and sign; Together does not, and for it the account is read only by being refused with a 402, which is whatcrate::probeis for. A platform this tool has no adapter for is not asked: there is no account of this tool’s there. - cost
- The cost of a run, from what it used and what the record says a token cost where it ran (09 §Cost). A reading: nothing is written.
- credentials
- Where a target’s credential comes from, and what happens when it is not there.
- driver
- The driver protocol proper (08-push-driver-protocol.md §Driver
steps): upload → (hash integrity check) → invoke → collect, driven
against any
Transportimplementation. - forward
- The forwards record (09-apply-report-and-ledger.md §Forwards record):
what
port-forward --detachleft running, one row per detachedssh, so that a tunnel handed to the operator as a pid is not lost the moment the terminal that printed it closes. - image
- Whether the image a profile names actually exists where the machine will pull it from — asked before the machine exists.
- infra
- The targets a machine can be placed on, and what each can provide.
- inventory
- What a platform is running, read and rendered once.
- ledger
- Append-only apply ledger (09-apply-report-and-ledger.md §Ledger): one row per driver-collected apply invocation, physically encoded as newline-delimited JSON (JSON Lines) — the ledger owner’s internal choice (09 §Stability: “Ledger physical encoding: internal”, which leaves it open). A dependency-free flat file was chosen over an embedded SQLite table: the row shape is fixed and tiny (four fields, one verbatim JSON blob), the only access patterns are “append one row” and “read every row back”, and a SQL engine buys nothing over that for either.
- local_
exec LocalExecTransport: thecrate::transport::Transportthat reaches no further than the driver’s own host — the other shipped implementation iscrate::ssh, and adocker exectransport is a documented extension point (08-push-driver-protocol.md §Stability: “SSH, provider exec API,docker execall satisfy it”). Runs the provisioner binary on the same host the driver itself runs on, staging the uploaded artifacts under a directory of the caller’s choosing (08 §Driver steps step 1: “any byte-transport; paths are the driver’s choice”).- prices
- The price record’s writer: ask a platform what its models cost and append what changed (09 §Price record). Two platforms; the function per platform is the adapter knowledge, the loop around it is shared.
- probe
- One token, now: ask each endpoint for a one-token completion and
report what came back (09 §Endpoint inventory,
probe). The one question that finds an exhausted account (402) or a dead key (401) before a run spends a build on finding it. It spends money — a few input tokens and one output token per endpoint — which is why it runs only when asked for. - provisioner
- Where the provisioner comes from.
- session
- The driver session (08-push-driver-protocol.md §Session contract):
runowns everything between “the caller supplied connectivity, a profile, and secret values” and “a collected report plus a ledger row” — steps 0-5 with per-step gates (StepPlan). - ssh
SshTransport: the SSH realization of the session contract’s transport seam (08-push-driver-protocol.md §Session steps / §Secret delivery). Wraps the operator host’sssh/scpbinaries — no in-process SSH library, matching the crate’s dependency posture; the two commands are operator-host prerequisites the wayapt-get/pipare pod prerequisites of a profile (08 §Inputs).- transport
- Transport abstraction (08-push-driver-protocol.md §Driver steps):
the byte-transport-agnostic upload / exec seam
crate::driver::rundrives. 08 names SSH, a provider exec API, anddocker execas transports that all satisfy the same protocol; this crate ships two (crate::ssh::SshTransportandcrate::local_exec::LocalExecTransport) and keepsTransportitself as the extension point for the rest (08 §Stability: “Driver implementation home … internal — the protocol, not the caller, is the contract”).