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;