orion-variate-engineering

name	orion-variate-engineering
description	Use when working with the Rust crate orion-variate: variable/value modeling, ValueType parsing and serialization, case-insensitive ValueDict/OriginDict usage, environment placeholder expansion with EnvEvaluable/EnvChecker, VarDefinition/VarCollection mutability, CwdGuard project directory helpers, and source-accurate API migration from older names.

Orion Variate Engineering

Use this skill for source-accurate work with orion-variate, the Orion crate for variable/value management and environment interpolation.

First Checks

1. Locate the crate root. In this workspace it is usually orion-variate/.
2. Treat src/vars/*, crate-root re-exports in src/lib.rs, and tests as source of truth.
3. AGENTS.md appears stale for this crate; it mentions modules that are not present. Do not follow it blindly.
4. Prefer importing public crate-root items: use orion_variate::{ValueDict, ValueType, EnvEvaluable, ...};.
5. Verify behavior changes from orion-variate/ with cargo test --all-features -- --test-threads=1.

Current API Facts

• Package version observed: 0.11.2, Rust edition 2024.
• Core modules are under src/vars: types, dict, definition, collection, origin, env_eval, global, constraint, and error.
• ValueType is an untagged serde enum: String, Bool, Number(u64), Float(f64), Ip, Obj(IndexMap<String, ValueType>), and List(Vec<ValueType>).
• ValueDict stores keys as UpperKey, so insertion normalizes keys to uppercase and lookups are case-insensitive when using get_case_insensitive.
• EnvDict is a type alias for ValueDict; dictionary variables take precedence over system environment variables.
• EnvEvaluable consumes self. Clone first if the original value/dict must be retained.
• VarCollection groups variables by Mutability: Immutable, System, and Module (default).
• VarsResult<T> is Result<T, StructError<VarsReason>> from orion-error.

Common Workflow

1. Use ValueType::from(...) for simple values and ValueObj/ValueVec for nested structures.
2. Store config/env values in ValueDict or EnvDict; use get_case_insensitive for user-facing keys.
3. Before interpolation, use needs_env_eval() and list_env_vars() when you need validation or diagnostics.
4. Use .env_eval(&env_dict) for String, Option<String>, ValueType, ValueDict, OriginValue, and OriginDict.
5. Use VarDefinition::from((name, value)) plus .with_mut_immutable(), .with_mut_system(), or .with_mut_module() to define configuration variables.
6. Use VarCollection::define(vars) to classify variables, then value_dict() and optionally .env_eval(...).
7. Use OriginDict when source labels and mutability-aware merge behavior matter.
8. Use CwdGuard::change(path) for temporary current-directory changes and find_project_root(_from) for _gal/project.toml discovery.

Migration Guardrails

• Prefer CwdGuard over deprecated WorkDir.
• Prefer get_case_insensitive over deprecated ucase_get.
• Prefer ValueType::variant_name over deprecated type_name.
• Prefer ValueType::update_from_str over deprecated update_by_str.
• Prefer EnvEvaluable over deprecated EnvEvalable.
• Prefer find_project_root and find_project_root_from over older find_project_define names.
• Prefer Mutability::module() over deprecated model().
• Prefer desc()/with_desc(...) over deprecated desp().

Important Semantics

• Placeholder syntax is ${VAR} and ${VAR:default}. A colon in the resolved value, such as postgresql://..., is valid and must not be treated as a default separator.
• Unresolved ${VAR} stays unchanged if no default is provided.
• ValueMap/ValueDict interpolation is sequential: later values can reference earlier values added during the same evaluation.
• ValueDict::merge(&other) does not overwrite existing keys.
• VarCollection::merge(other) does not overwrite immutable variables, but later system and module variables with the same name override within their own group.
• VarCollection::value_dict() inserts in immutable -> system -> module order; duplicate names across groups are overwritten by later groups.
• OriginDict::merge(&other) overwrites an existing value only if the existing value is mutable.
• In Rust 2024, std::env::set_var and remove_var are unsafe; prefer EnvDict in examples and tests unless system env interaction is the point.

References

Read references/patterns.md when you need copyable Rust templates, merge examples, or validation commands.