`mod campaign`¶

module campaign¶

Declarative campaign configuration: TOML in, channels explicit. Declarative campaign configuration.

A coordinated campaign is configured by roughly seventy CATALOG_* environment variables, and an absent variable silently selects a default. That shape cannot fail loudly: the c48 LJ75 campaign ran for hours with its recognition-refund channel dark because one export was missing from an sbatch script, and nothing anywhere was obliged to say so.

This module is the replacement surface. A campaign is a TOML file: unknown keys are rejected, the coordination channels are a required block with no defaults (every channel is an explicit true or false, so “forgot to mention it” is a parse error, not a silent off), and the resolved configuration is echoed as a banner so every worker log opens by saying which channels it runs.

Loading bridges onto the existing environment-variable transport: CampaignConfig::bootstrap reads the file named by CATALOG_CONFIG, validates it, refuses to run if the environment already carries conflicting CATALOG_* settings, and then exports the file’s values into the environment before any thread spawns. Call sites keep reading the variables they always read; the file is the single place a human writes them.

Functions

fn catalog_transport_is_shared(mode: Option<&str>, endpoint_present: bool) -> Result<bool, CampaignError>¶

Resolve whether a catalog transport crosses replica boundaries.

A private catalog still has an RPC endpoint, so transport presence alone cannot label a causal control. An absent mode retains the endpoint-based behavior used by existing launchers.

Structs and Unions

struct CampaignConfig¶

A validated campaign definition.

campaign: String¶: Campaign name (CATALOG_CAMPAIGN); the output namespace.

channels: Channels¶: The coordination channels, all explicit.

ensemble: Ensemble¶: The ensemble shape.

extra: BTreeMap<String, String>¶: Everything else the run wants set, verbatim CATALOG_* (or other) variables. Optional, but still schema’d: keys must be SCREAMING_SNAKE_CASE, values are strings.

Implementations

impl CampaignConfig¶

Functions

fn banner(&self) -> String¶: The launch banner: one line per channel, every state explicit. Printed by whoever bootstraps, so every log opens with the channel table and a dark channel is visible in the first screenful, not at hour three.

fn bootstrap() -> Result<Option<Self>, CampaignError>¶

Load the campaign named by CATALOG_CONFIG, validate it, refuse on collisions, export it into the process environment, and return it (the caller prints the banner). Returns None when CATALOG_CONFIG is unset: legacy env-var operation.

Safety contract Must run before any thread is spawned; it writes the process environment.

fn channel_states(&self) -> [(&'static str, bool); 6]¶: Channel names and their explicit states.

fn collisions(&self) -> Vec<String>¶: Environment variables this config would export that are already set to a different value: the two-sources-of-truth hazard, reported instead of resolved.

fn env_pairs(&self) -> Vec<(String, String)>¶: The environment this campaign resolves to, as pairs. Boolean channels export “1” when on and stay unset when off, matching how every existing read site tests them; the banner still names the off channels explicitly.

fn parse(text: &str) -> Result<Self, CampaignError>¶: Parse and validate a campaign file’s contents.

struct CampaignError(String)¶

A loading failure. The message is the user interface: it names the file, the key, and what to do.

Traits implemented

impl std::fmt::Display for CampaignError¶

impl std::error::Error for CampaignError¶

struct Channels¶

The coordination channels. Every field is required: a campaign file that does not mention a channel does not parse, which is the entire point.

shared_screen: bool¶: The shared recognition screen: chains offer validated minima and a trial descending into any chain’s known basin takes the stored minimum instead of finishing the descent (CATALOG_SHARED_SCREEN).

shared_bias: bool¶: Continuous shared bias: the quench feels the ensemble’s visited cloud at every step rather than only at steering decisions (CATALOG_SHARED_BIAS). Distinct from the always-on reference pullback that rec+catalog mode applies regardless.

entropic_bias: bool¶: Entropic occupancy bias on selection (CATALOG_ENTROPIC_BIAS).

histo_screen: bool¶: Histogram screen on arrivals (CATALOG_HISTO_SCREEN).

seam_ladder: bool¶: The per-chain seam ladder: banked doorway states with epsilon-greedy restarts after stagnation (CATALOG_SEAM_LADDER).

frontier_exchange: bool¶: The ensemble frontier exchange: raw doorway states shared through the coordinator so every chain’s ladder holds the union’s progress (CATALOG_FRONTIER_EXCHANGE). Requires the seam ladder, which is where arrivals land.

struct Ensemble¶

The ensemble shape. Required: a campaign that does not say how many chains it runs is not a campaign.

replicas: u32¶: Chain count (CATALOG_REPLICAS).

wave: u32¶: Wave width for selection sync (CATALOG_WAVE).

slice: u32¶: Hops per slice between waves (CATALOG_SLICE).

max_hops: u64¶: Hop cap per chain (CATALOG_MAX_HOPS).

population_interval: u64¶: Census interval in evaluations (CATALOG_POPULATION_INTERVAL).

mod campaign¶

`mod campaign`¶