star-toml

Version: v26.6.29

A framework for loading, layering, validating, and admitting configuration files in Rust — the * in *.toml.

Most configuration frameworks parse a file into a struct and stop. star-toml treats configuration as operational law and provides the core substrate for config admission.

Do not build a path.
Build the bounded space of paths,
the laws that admit them,
the generators that manufacture them,
the detectors that falsify them,
the witnesses that preserve them,
and the gate that decides standing.

Crate Ecosystem

🏛️ The Core Thesis: Configuration is Operational Law

Most software systems do not fail because they lack code. They fail because their operational law is implicit, underbounded, or non-witnessed.

star-toml replaces narrative authority ("trust me, it works") with machine-visible standing:

• Raw Parse ≠ Trusted Config: Syntactically valid TOML is not an admitted configuration.
• OCEL = Lifecycle/Process History: Process-mining logs (wasm4pm-compat OCEL export) record the process history but do not compute $q_{config}$ or grant standing.
• q_config = Standing Decision: The configuration standing bit ($q_{config} = 1$) is calculated from pipeline completeness, witness integrity, and an empty failset.
• AdmittedConfig: The terminal, immutable, witness-backed envelope representing a configuration with standing.

🚀 The Config Admission Pipeline

star-toml provides two typestate-guaranteed pipelines depending on whether you need full provenance tracking:

Simple path (Loader) — compose layers, deserialize, validate, freeze:

Raw (String/File)
 ↳ Merged          — traced layer merge (deep_merge_traced + WinnerMap)
    ↳ Deserialized<T>  — schema alignment, serde
       ↳ Validated<T>  — Pydantic-grade custom rules (Validate trait)
          ↳ Frozen<T>  — immutable; save_canonical() writes sorted TOML to disk

Provenance-tracked admission path (TrustedLoader) — full standing decision with witness:

Raw (String/File)
 ↳ BoundedSources  — source list checked, provenance reports built
    ↳ EnvResolved  — prefixed environment variable overrides applied
       ↳ Deserialized<T>
          ↳ Validated<T>
             ↳ Frozen<T>
                ↳ AdmittedConfig<T>  — terminal admitted config
                   • ConfigWitness (BLAKE3) computed internally and bound to all provenance inputs
                   • save_canonical() available before this step on Validated/Frozen

Note: CanonicalSaved and Witnessed are not typestates — save_canonical() is a method on Config<Validated<T>> / Config<Frozen<T>>, and the ConfigWitness is computed inside load_admitted(). Merged only exists on the simple Loader path; TrustedLoader uses BoundedSources → EnvResolved instead.

load_admitted_strict() is deprecated since v26.6.28. Use load_admitted() (strict by default) or load_admitted_exploratory() to allow unknown fields during schema development.

🛠️ Usage Example

use serde::{Deserialize, Serialize};
use star_toml::{
    loader::{ConfigLifecycle, TrustedLoader},
    Validate, Validator,
};

#[derive(Debug, Deserialize, Serialize, Clone)]
struct AppConfig {
    name: String,
    port: u16,
}

impl Validate for AppConfig {
    fn validate(&self, v: &mut Validator) {
        v.check_non_empty("name", &self.name);
        v.check_range("port", self.port, 1024..=65535);
    }
}
impl ConfigLifecycle for AppConfig {}

fn main() {
    // TrustedLoader: provenance-tracked admission path with BLAKE3 witness
    match TrustedLoader::new()
        .layer_file_if_exists("config.toml")  // optional base file
        .env_prefix("APP_")                    // APP_NAME, APP_PORT override
        .load_admitted::<AppConfig>()          // strict: rejects unknown fields
    {
        Ok(admitted) => {
            println!("Admission Granted (q_config = 1)");
            println!("Config: {:?}", admitted.value());
            println!("Witness: {}", admitted.witness().hash()); // 64-char BLAKE3 hex
        }
        Err(e) => {
            println!("Admission Refused (q_config = 0): {e}");
        }
    }
}

Key API surface:

📐 DfCM (Design for Combinatorial Maximalism)

star-toml is designed under the DfCM discipline. MVP asks: "What is the smallest happy path?" DfCM asks: "What is the complete bounded variant space this system must survive?"

Every configuration loader evaluates:

1. Sources: Inline, required file, optional file, environment.
2. Layers: Defaults $\rightarrow$ base $\rightarrow$ profile $\rightarrow$ env.
3. Paths: Validated against Sandbox, RelativeOnly, or BlockForbidden policies.
4. Validation: Invariant rules with error or fatal severities.

🔍 Verification & Conformance

star-toml includes a built-in verifier that checks for active counterexamples (such as directory traversals, unknown fields accepted in trusted mode, and validation errors without paths) to ensure the release has absolute conformance.

Run the verifier report:

cargo run --bin verifier_report

Run DfCM examples (demonstrative):

cargo run --example basic_admitted_config
cargo run --example layered_profiles
cargo run --example env_overrides
cargo run --example strict_unknown_fields
cargo run --example path_policy_sandbox
cargo run --example witness_and_q_config
cargo run --example ocel_lifecycle_export

Run DfCM combinatorial integration tests (assertive — panic on violation):

cargo run --example dfcm_validation_matrix   # all 12 Validator checks × pass/fail + analytics
cargo run --example dfcm_error_variants      # all 5 Error variants produced and matched
cargo run --example dfcm_merge_semantics     # 7 layer-merge invariants asserted