clm-kernel 0.0.21

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
// @generated by tools/types/sync_runtime_contract.py from types/lattice/runtime_contract.json
// DO NOT EDIT MANUALLY — run `python3 tools/types/sync_runtime_contract.py --write`
// Normative Invariant: INV-489 (Declarative Runtime Contract Univalence)

/// Canonical environment variable keys (canonical keys and secondary aliases).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ClmEnvVar {
    Runtime,
    Root,
    DbDir,
    DbBackend,
    ZeroFs,
    AgentDid,
    SponsorDid,
    ExecutionLocaleHash,
    LocaleTrust,
    HashAlgo,
    HashConfig,
    TargetFile,
    Payload,
    RunId,
    StateToken,
    BindingType,
    EventLogPath,
    GateOverride,
    SkipConditions,
    SkipGrammar,
    PetriHalt,
    PetriKenotic,
    PetriMarkingDir,
    PetriVisual,
    MembrokerPort,
    MembrokerNoDisk,
    MembrokerSnapDir,
    ForbidSubprocess,
    DbFile,
    MemTridb,
    IsolatedDb,
    Sandbox,
    AuthorDid,
    DelegatedParentDid,
    ResolveAllowedSponsors,
    KenoticCurrentMarkingHash,
    RuntimeFacts,
    LastMcardHash,
    NestedFile,
    LastMcardFile,
    MlpContext,
    TransportRef,
    NestedExec,
    DispatchSock,
    ReplTrace,
    MockLlmBehavior,
    MockOiBehavior,
    Debug,
    Verbose,
    SovereignStrict,
}

impl ClmEnvVar {
    pub const fn canonical_name(self) -> &'static str {
        match self {
            Self::Runtime => "CLM_RUNTIME",
            Self::Root => "CLM_ROOT",
            Self::DbDir => "CLM_DB_DIR",
            Self::DbBackend => "CLM_DB_BACKEND",
            Self::ZeroFs => "CLM_ZERO_FS",
            Self::AgentDid => "CLM_AGENT_DID",
            Self::SponsorDid => "CLM_SPONSOR_DID",
            Self::ExecutionLocaleHash => "CLM_EXECUTION_LOCALE_HASH",
            Self::LocaleTrust => "CLM_LOCALE_TRUST",
            Self::HashAlgo => "CLM_HASH_ALGO",
            Self::HashConfig => "CLM_HASH_CONFIG",
            Self::TargetFile => "CLM_TARGET_FILE",
            Self::Payload => "CLM_PAYLOAD",
            Self::RunId => "CLM_RUN_ID",
            Self::StateToken => "CLM_STATE_TOKEN",
            Self::BindingType => "CLM_BINDING_TYPE",
            Self::EventLogPath => "CLM_EVENT_LOG_PATH",
            Self::GateOverride => "CLM_GATE_OVERRIDE",
            Self::SkipConditions => "CLM_SKIP_CONDITIONS",
            Self::SkipGrammar => "CLM_SKIP_GRAMMAR",
            Self::PetriHalt => "CLM_PETRI_HALT",
            Self::PetriKenotic => "CLM_PETRI_KENOTIC",
            Self::PetriMarkingDir => "CLM_PETRI_MARKING_DIR",
            Self::PetriVisual => "CLM_PETRI_VISUAL",
            Self::MembrokerPort => "CLM_MEMBROKER_PORT",
            Self::MembrokerNoDisk => "CLM_MEMBROKER_NO_DISK",
            Self::MembrokerSnapDir => "CLM_MEMBROKER_SNAP_DIR",
            Self::ForbidSubprocess => "CLM_FORBID_SUBPROCESS",
            Self::DbFile => "CLM_DB_FILE",
            Self::MemTridb => "CLM_MEM_TRIDB",
            Self::IsolatedDb => "CLM_ISOLATED_DB",
            Self::Sandbox => "CLM_SANDBOX",
            Self::AuthorDid => "CLM_AUTHOR_DID",
            Self::DelegatedParentDid => "CLM_DELEGATED_PARENT_DID",
            Self::ResolveAllowedSponsors => "CLM_RESOLVE_ALLOWED_SPONSORS",
            Self::KenoticCurrentMarkingHash => "CLM_KENOTIC_CURRENT_MARKING_HASH",
            Self::RuntimeFacts => "CLM_RUNTIME_FACTS",
            Self::LastMcardHash => "CLM_LAST_MCARD_HASH",
            Self::NestedFile => "CLM_NESTED_FILE",
            Self::LastMcardFile => "CLM_LAST_MCARD_FILE",
            Self::MlpContext => "CLM_MLP_CONTEXT",
            Self::TransportRef => "CLM_TRANSPORT_REF",
            Self::NestedExec => "CLM_NESTED_EXEC",
            Self::DispatchSock => "CLM_DISPATCH_SOCK",
            Self::ReplTrace => "CLM_REPL_TRACE",
            Self::MockLlmBehavior => "CLM_MOCK_LLM_BEHAVIOR",
            Self::MockOiBehavior => "CLM_MOCK_OI_BEHAVIOR",
            Self::Debug => "CLM_DEBUG",
            Self::Verbose => "CLM_VERBOSE",
            Self::SovereignStrict => "CLM_SOVEREIGN_STRICT",
        }
    }

    pub const fn default_value(self) -> &'static str {
        match self {
            Self::Runtime => "rust",
            Self::Root => ".",
            Self::DbDir => "db",
            Self::DbBackend => "sqlite",
            Self::ZeroFs | Self::SkipConditions | Self::SkipGrammar | Self::PetriHalt | Self::PetriKenotic | Self::PetriVisual | Self::MembrokerNoDisk | Self::ForbidSubprocess | Self::MemTridb | Self::IsolatedDb | Self::Sandbox | Self::NestedExec | Self::Debug | Self::Verbose | Self::SovereignStrict => "false",
            Self::AgentDid => "did:clm:system:bootstrap",
            Self::SponsorDid | Self::TargetFile | Self::Payload | Self::RunId | Self::StateToken | Self::GateOverride | Self::DbFile | Self::AuthorDid | Self::DelegatedParentDid | Self::ResolveAllowedSponsors | Self::KenoticCurrentMarkingHash | Self::RuntimeFacts | Self::LastMcardHash | Self::NestedFile | Self::LastMcardFile | Self::MlpContext | Self::TransportRef | Self::DispatchSock | Self::ReplTrace | Self::MockLlmBehavior | Self::MockOiBehavior => "",
            Self::ExecutionLocaleHash => "locale:local:default",
            Self::LocaleTrust => "sovereign",
            Self::HashAlgo => "blake3",
            Self::HashConfig => "types/lattice/clm_features.yaml",
            Self::BindingType => "native",
            Self::EventLogPath => "data/execution_logs",
            Self::PetriMarkingDir => "data/execution_logs/markings",
            Self::MembrokerPort => "0",
            Self::MembrokerSnapDir => "data/db/snapshots",
        }
    }
    pub const fn aliases(self) -> &'static [&'static str] {
        match self {
            Self::Runtime => &["CLM_RUNNER", "CLM_RUNTIME_BACKEND", "CLM_POLYGLOT_RUNTIME"],
            Self::Root => &["PROJECT_ROOT", "CLM_PROJECT_ROOT", "CLM_HOME"],
            Self::DbDir => &[],
            Self::DbBackend => &[],
            Self::ZeroFs => &[],
            Self::AgentDid => &["ACTIVE_AGENT_DID"],
            Self::SponsorDid => &["CLM_KENOTIC_SPONSOR_DID"],
            Self::ExecutionLocaleHash => &[],
            Self::LocaleTrust => &[],
            Self::HashAlgo => &["CLM_HASH_DEFAULT"],
            Self::HashConfig => &[],
            Self::TargetFile => &["CLM_ACTIVE_FILE", "CLM_FILE", "TARGET_FILE"],
            Self::Payload => &[],
            Self::RunId => &[],
            Self::StateToken => &[],
            Self::BindingType => &[],
            Self::EventLogPath => &[],
            Self::GateOverride => &[],
            Self::SkipConditions => &[],
            Self::SkipGrammar => &[],
            Self::PetriHalt => &[],
            Self::PetriKenotic => &[],
            Self::PetriMarkingDir => &[],
            Self::PetriVisual => &[],
            Self::MembrokerPort => &[],
            Self::MembrokerNoDisk => &[],
            Self::MembrokerSnapDir => &[],
            Self::ForbidSubprocess => &[],
            Self::DbFile => &["CLM_DB_PATH", "CLM_MCARD_DB", "MCARD_DB_PATH"],
            Self::MemTridb => &[],
            Self::IsolatedDb => &[],
            Self::Sandbox => &[],
            Self::AuthorDid => &[],
            Self::DelegatedParentDid => &[],
            Self::ResolveAllowedSponsors => &[],
            Self::KenoticCurrentMarkingHash => &[],
            Self::RuntimeFacts => &[],
            Self::LastMcardHash => &[],
            Self::NestedFile => &[],
            Self::LastMcardFile => &[],
            Self::MlpContext => &[],
            Self::TransportRef => &[],
            Self::NestedExec => &[],
            Self::DispatchSock => &[],
            Self::ReplTrace => &[],
            Self::MockLlmBehavior => &[],
            Self::MockOiBehavior => &[],
            Self::Debug => &[],
            Self::Verbose => &[],
            Self::SovereignStrict => &[],
        }
    }
}

fn warn_env_key(key: &'static str, canonical: &'static str, split: bool) {
    static WARNED: std::sync::OnceLock<std::sync::Mutex<std::collections::HashSet<&'static str>>> = std::sync::OnceLock::new();
    let mut warned = WARNED.get_or_init(Default::default).lock().unwrap_or_else(|e| e.into_inner());
    if warned.insert(key) {
        if split { eprintln!("{key} is now independent of {canonical} (runtime contract 0.0.21)"); }
        else { eprintln!("{key} is deprecated; use {canonical} (runtime contract 0.0.21)"); }
    }
}

fn resolve_env_value(var: ClmEnvVar, get: impl Fn(&str) -> Option<String>) -> Option<String> {
    let previous = match var {
        ClmEnvVar::DbFile => Some(ClmEnvVar::DbDir.canonical_name()),
        ClmEnvVar::MemTridb => Some(ClmEnvVar::DbBackend.canonical_name()),
        ClmEnvVar::IsolatedDb => Some(ClmEnvVar::DbBackend.canonical_name()),
        ClmEnvVar::Sandbox => Some(ClmEnvVar::DbBackend.canonical_name()),
        ClmEnvVar::MembrokerNoDisk => Some(ClmEnvVar::ZeroFs.canonical_name()),
        ClmEnvVar::AuthorDid => Some(ClmEnvVar::AgentDid.canonical_name()),
        ClmEnvVar::DelegatedParentDid => Some(ClmEnvVar::SponsorDid.canonical_name()),
        ClmEnvVar::ResolveAllowedSponsors => Some(ClmEnvVar::SponsorDid.canonical_name()),
        ClmEnvVar::KenoticCurrentMarkingHash => Some(ClmEnvVar::ExecutionLocaleHash.canonical_name()),
        ClmEnvVar::RuntimeFacts => Some(ClmEnvVar::LocaleTrust.canonical_name()),
        ClmEnvVar::LastMcardHash => Some(ClmEnvVar::HashConfig.canonical_name()),
        ClmEnvVar::NestedFile => Some(ClmEnvVar::TargetFile.canonical_name()),
        ClmEnvVar::LastMcardFile => Some(ClmEnvVar::TargetFile.canonical_name()),
        ClmEnvVar::MlpContext => Some(ClmEnvVar::Payload.canonical_name()),
        ClmEnvVar::TransportRef => Some(ClmEnvVar::Payload.canonical_name()),
        ClmEnvVar::NestedExec => Some(ClmEnvVar::RunId.canonical_name()),
        ClmEnvVar::DispatchSock => Some(ClmEnvVar::StateToken.canonical_name()),
        ClmEnvVar::ReplTrace => Some(ClmEnvVar::EventLogPath.canonical_name()),
        ClmEnvVar::MockLlmBehavior => Some(ClmEnvVar::GateOverride.canonical_name()),
        ClmEnvVar::MockOiBehavior => Some(ClmEnvVar::GateOverride.canonical_name()),
        ClmEnvVar::Debug => Some(ClmEnvVar::PetriVisual.canonical_name()),
        ClmEnvVar::Verbose => Some(ClmEnvVar::PetriVisual.canonical_name()),
        ClmEnvVar::SovereignStrict => Some(ClmEnvVar::ForbidSubprocess.canonical_name()),
        _ => None,
    };
    if let Some(value) = get(var.canonical_name()).filter(|v| !v.is_empty()) {
        if let Some(parent) = previous { warn_env_key(var.canonical_name(), parent, true); }
        return Some(value);
    }
    for key in var.aliases() {
        if let Some(value) = get(key).filter(|v| !v.is_empty()) {
            warn_env_key(key, var.canonical_name(), false);
            return Some(value);
        }
    }
    None
}

pub fn resolve_env(var: ClmEnvVar) -> Option<String> {
    resolve_env_value(var, |key| std::env::var(key).ok())
}

pub fn resolve_env_or_default(var: ClmEnvVar) -> String {
    resolve_env(var).unwrap_or_else(|| var.default_value().to_string())
}

pub const ENV_PASSTHROUGH_WHITELIST: &[&str; 69] = &[
    "CLM_RUNTIME",
    "CLM_RUNNER",
    "CLM_RUNTIME_BACKEND",
    "CLM_POLYGLOT_RUNTIME",
    "CLM_ROOT",
    "PROJECT_ROOT",
    "CLM_DB_DIR",
    "CLM_DB_PATH",
    "CLM_DB_BACKEND",
    "CLM_MEM_TRIDB",
    "CLM_ZERO_FS",
    "CLM_AGENT_DID",
    "ACTIVE_AGENT_DID",
    "CLM_SPONSOR_DID",
    "CLM_KENOTIC_SPONSOR_DID",
    "CLM_EXECUTION_LOCALE_HASH",
    "CLM_KENOTIC_CURRENT_MARKING_HASH",
    "CLM_LOCALE_TRUST",
    "CLM_HASH_ALGO",
    "CLM_HASH_CONFIG",
    "CLM_TARGET_FILE",
    "CLM_ACTIVE_FILE",
    "CLM_FILE",
    "TARGET_FILE",
    "CLM_PAYLOAD",
    "CLM_PAYLOAD_FILE",
    "CLM_RUN_ID",
    "CLM_STATE_TOKEN",
    "CLM_BINDING_TYPE",
    "CLM_EVENT_LOG_PATH",
    "CLM_GATE_OVERRIDE",
    "CLM_SKIP_CONDITIONS",
    "CLM_SKIP_GRAMMAR",
    "CLM_PETRI_HALT",
    "CLM_PETRI_KENOTIC",
    "CLM_PETRI_MARKING_DIR",
    "CLM_PETRI_VISUAL",
    "CLM_FORBID_SUBPROCESS",
    "CLM_NESTED_EXEC",
    "CLM_RUST_DAEMON_PORT",
    "CLM_RUST_PORT_FILE",
    "CLM_ACTIVE_A_HASH",
    "CLM_ACTIVE_B_HASH",
    "CLM_ACTIVE_C_HASH",
    "CLM_MLP_CONTEXT",
    "CLM_SESSION_DELEGATION",
    "CLM_TRANSPORT_REF",
    "CLM_REPL_TRACE",
    "CLM_NO_SANDBOX",
    "CLM_SYMBOL_HANDLES",
    "CLM_MEMBROKER_PORT",
    "CLM_MEMBROKER_NO_DISK",
    "CLM_MEMBROKER_SNAP_DIR",
    "CLM_SCRATCH",
    "CLM_TEST_FAST_BOOT",
    "CLM_QUIET",
    "CLM_NATIVE_PETRI_VM",
    "CLM_DISPATCH_SOCK",
    "CLM_SCRIPT_CONTENT",
    "CLM_ENTRY_POINT",
    "CLM_TARGET_PATH",
    "CLM_AGENT_CLASS",
    "CLM_AGENT_ROLE",
    "CLM_RISK_LEVEL",
    "CLM_EOA_APPROVAL",
    "CLM_LAST_MCARD_HASH",
    "CLM_LAST_MCARD_FILE",
    "ELAN_HOME",
    "TLA2TOOLS_JAR",
];

pub fn resolve_env_from_map<S: ::std::hash::BuildHasher>(
    var: ClmEnvVar,
    env: &std::collections::HashMap<String, String, S>,
) -> Option<String> {
    resolve_env_value(var, |key| env.get(key).cloned())
}