Crate microvms_core 

The MicroVMs client: the control plane, the in-VM daemon, the cost engine, and every trap closure, in one library crate (ARCH-1).

What this crate is for

docs/PLATFORM.md records seventeen measured findings about AWS Lambda MicroVMs, fifteen of which a client can act on. Most of them are traps in the specific sense that the platform’s answer points away from the cause: an unsupported region answers AccessDeniedException with a null message, a clientToken replay wedges an image in CREATING for fifteen hours with no error at all, a minimumMemoryInMiB of 512 produces a guest reporting 2 GB. Each finding cost a measurement, and this crate is where that measurement is spent once so no caller has to make it again.

The Python client closed the same traps and stayed in the tree as the conformance oracle and the API reference until this port had driven the live suite green; it is git history now. The reason to port was that Rust can make several of those closures unavailable rather than merely rejected — see the strength ladder below.

How strongly a trap is closed

The spec ranks each closure, strongest first:

• S1, inexpressible — the mistake cannot be written down. region::Region is an enum over the five regions that carry MicroVMs, so a typo’d region is a compile error rather than a runtime check; sizing::SizeClass is closed over the five documented baselines; hooks::RunHookTimeout and hooks::BuildHookTimeout are separate types with no conversion between them, so a 3600-second build timeout cannot reach a field that caps at 60.
• S2, expressible but rejected — the mistake can be written and the client refuses it locally, before any control-plane call, with an error naming the docs/PLATFORM.md finding. Weaker because the guard is code that can regress, but it costs seconds rather than a build cycle. Every boundary where a bare integer or string still has to be judged lands here: sizing::SizeClass::from_baseline_mib, Region::from_str.
• S3, correct by default and overridable — weakest, because it protects the caller who does nothing and abandons the one who overrides. An S3 closure must say what the override costs: region::Region::unlisted says it costs you the diagnostic.

Every error message names its finding

A local reject explains itself by naming the docs/PLATFORM.md section that measured the behaviour, because the codes and the guards exist precisely so a reader can go to the measurement rather than to a constraint. “region ‘eu-central-1’ is invalid” sends someone to check their spelling; the message region::Region actually raises sends them to the null-message finding.

A guard that cannot fail is worse than no guard

Carried over from the Python era unchanged: every guard here has a falsification — a specific plausible edit that must turn a specific test red. “Delete the feature and the test fails” does not count. The clearest case is TRAP-13 in sizing: every documented peak is exactly four times its baseline, so a test against the shipped table cannot tell a table lookup from baseline * 4, and the guard has to drive the lookup over a table where the pattern does not hold.

Layout

error, region, sizing, hooks, and constants are the foundation every other module builds on. cost, control, session, and sandbox are the product surface. agents is the one layer above them: the coding-agent helpers docs/AGENT-VMS.md specifies, which compose the surface and which nothing below depends on. provision stands beside the surface rather than on it: it obtains the verified agentd binary an image is built from, and makes no AWS call.

Re-exports

pub use error::Error;

pub use error::ErrorKind;

pub use error::WireKind;

pub use hooks::BuildHookTimeout;

pub use hooks::RunHookTimeout;

pub use region::Region;

pub use sizing::SizeClass;

pub use protocol;

Modules

agents

Agent VMs: the L3 helpers over the lifecycle (docs/AGENT-VMS.md).

constants

Every hardcoded service constraint, and the JSON the build gate checks them with.

control

The control-plane client: SigV4-signed rest-json, and every trap closed before the request leaves the process.

cost

What a run cost, and what a plan will cost, with every figure labelled.

error

One error type, two granularities.

hooks

The two hook-timeout ceilings, as two types that cannot be swapped.

identity

The host’s half of the tunnel identity proof: seed generation, derivation, and the pin.

names

Named MicroVMs: records that let a later process find a VM by name and adopt it.

preflight

preflight: whether a harness can launch here, checked before it queues work (#223).

provision

Provisioning of the agentd daemon binary: one call that returns verified aarch64 bytes for the version a client drives (BIND-17 through BIND-20, issue #219).

region

The five regions that carry MicroVMs, as a closed enum (TRAP-6).

sandbox

The Sandbox lifecycle: one VM’s whole life, with the state machine the symspec model describes made true of the code.

session

The in-VM client: one MicroVM’s control API, with the proxy auth handled for you.

sizing

Size classes: what minimumMemoryInMiB actually buys, and what it bills.

Constants

VERSION

The crate’s own version, for a doctor or manifest command to report.