Skip to main content

Crate lm_provision_driver

Crate lm_provision_driver 

Source
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 — the transport::Transport trait plus the shared transport::PodPaths / transport::ExecOutput / transport::TransportError types every implementation shares (08 §Driver steps: “transport-agnostic … SSH, provider exec API, docker exec all satisfy it”). Two implementations ship: local_exec and ssh. A docker exec transport 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 any transport::Transport, plus driver::hash_locally for 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 in lm-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 every lm_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 machine acquire created, one per machine given back, and acquisition::outstanding, the list a sweep works from. It lives in lm-provision-protocol for 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 contract ConnectionSpec): 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 shape lm-provision apply exposes 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 — plus infra::acquire and infra::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 through infra and rendered as the one JSON document both the operator CLI’s machine list and the MCP lm_machine_list tool 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: one usage document (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, like inventory: 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 what crate::probe is 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 Transport implementation.
forward
The forwards record (09-apply-report-and-ledger.md §Forwards record): what port-forward --detach left running, one row per detached ssh, 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: the crate::transport::Transport that reaches no further than the driver’s own host — the other shipped implementation is crate::ssh, and a docker exec transport is a documented extension point (08-push-driver-protocol.md §Stability: “SSH, provider exec API, docker exec all 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): run owns 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’s ssh / scp binaries — no in-process SSH library, matching the crate’s dependency posture; the two commands are operator-host prerequisites the way apt-get / pip are 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::run drives. 08 names SSH, a provider exec API, and docker exec as transports that all satisfy the same protocol; this crate ships two (crate::ssh::SshTransport and crate::local_exec::LocalExecTransport) and keeps Transport itself as the extension point for the rest (08 §Stability: “Driver implementation home … internal — the protocol, not the caller, is the contract”).