Skip to main content

lm_provision/
lib.rs

1//! # lm-provision
2//!
3//! ## Architecture
4//!
5//! A spec-first pod provisioner built entirely in Rust around a typed
6//! [`profile_ast::ProfileNode`] AST. A profile is authored as JSON or the
7//! canonical text form, parsed into the AST by the [`frontend`], and then
8//! run through the read-only pipeline stages (validate / canonical / hash
9//! / plan) or the effectful [`exec`] engine (apply). There is no embedded
10//! scripting runtime: the earlier embedded-Lua authoring frontend and its
11//! VM / sandbox / bridge stack have been removed in favour of the single
12//! AST pipeline.
13//!
14//! ## Modules
15//!
16//! - [`frontend`] — parse a profile file (`.json` → serde bridge,
17//!   canonical text → PEG grammar, `.lua` → explicit rejection) into a
18//!   [`profile_ast::ProfileNode`] AST.
19//! - [`profile_ast`] — the `ProfileNode` AST (spec + the phase catalog
20//!   kinds), the semantics adapter (`ProfileSemantics` / `ProfileValue`),
21//!   and the dsl-kit engine wiring that drives execution.
22//! - [`resolve`] — the fragment-import resolve stage between load and
23//!   validate (11-fragment-import.md §Resolution): every `Import` node
24//!   is replaced by its fragment's expanded phase list, so everything
25//!   downstream sees a plain expanded `Spec`.
26//! - [`validate`] — the AST validate stage (03-pipeline-stage-artifacts.md
27//!   §validate).
28//! - [`canonical`] — deterministic byte encoder + SHA-256 profile hash
29//!   over the [`profile_ast::ProfileNode`] AST
30//!   (03-pipeline-stage-artifacts.md §canonical / §hash). Frontend-
31//!   independent by construction: `NodeId` is excluded, declared lists
32//!   are sorted, phase order preserved.
33//! - [`pin`] — the resolver-layer `pin` subcommand (spec 11 §The
34//!   resolver layer): rewrite `name@version` imports in a JSON profile
35//!   into the explicit pinned `src` + `hash` form against an
36//!   `index.json`, verifying the rewritten document resolves before
37//!   overwriting it.
38//! - [`plan`] — the AST plan stage: expand a profile into the plan
39//!   artifact (03-pipeline-stage-artifacts.md §plan).
40//! - [`to_bridge_json`] — expanded AST → serde-JSON serializer whose
41//!   output the JSON serde bridge accepts (spec 11 §Cache last
42//!   paragraph: the pin-verifiable cache entries the resolve stage
43//!   writes, and — later — the payload the driver preflight uploads).
44//! - [`resource`] — what a phase creates (`produces`) and what it needs
45//!   already there (`requires` / `assumes`), and the forward fold that
46//!   decides whether a profile is well-formed under that. Every
47//!   ComfyUI-relative path is derived here from one declared root
48//!   instead of being a host constant.
49//! - [`digest`] — the crate's single SHA-256 implementation, shared by
50//!   the profile hash, the Assert model's content predicate, and the
51//!   driver's `ensure-binary` check.
52//! - [`exec`] — the execution layer, with no embedded scripting
53//!   runtime: the capability gate, the declaration-derived path / HTTP
54//!   / secret policies, the pure-Rust effect implementations, and the
55//!   per-step report builder (05-sandbox-layer-contract.md,
56//!   09-apply-report-and-ledger.md).
57//! - [`machine`] — what the machine itself must be, and the contract a
58//!   target implements to be judged against it: [`machine::admit`]
59//!   before one exists, [`machine::observe`] once one does.
60//! - [`normalize`] — the canonical phase order every stage reads,
61//!   imposed on a profile's as-written order.
62//! - [`derive`] — the `dsl_exec` attribute's expansion surface.
63//! - [`apply`] — host-side `plan → dispatch → apply → report` entry point
64//!   ([`apply::run_apply_ast`], 09-apply-report-and-ledger.md).
65//! - [`cli`] — subcommand / flag surface (07-cli.md).
66//!
67//! ## Static binary
68//!
69//! Build a musl static binary requiring zero preinstalled dependencies on
70//! the target pod (08-push-driver-protocol.md §Inputs):
71//!
72//! ```text
73//! rustup target add x86_64-unknown-linux-musl
74//! cargo build --release --target x86_64-unknown-linux-musl
75//! ```
76
77#![warn(missing_docs)]
78
79pub mod apply;
80pub mod canonical;
81pub mod cli;
82pub mod derive;
83pub mod digest;
84pub mod egress;
85pub mod exec;
86pub mod fetch;
87pub mod frontend;
88pub mod machine;
89pub mod normalize;
90pub mod pin;
91pub mod plan;
92pub mod profile_ast;
93pub mod resolve;
94pub mod resource;
95pub mod to_bridge_json;
96pub mod validate;