Compiler

The forge compiler transforms a validated ForgeGraph into ForgeArtifacts — compiled nodes, dependency links, initial chem state, provenance, and dirty tracking — without any spatial or domain-specific knowledge.

Entry Point

pub fn compile_forge<S: ForgeSeedLike>(
    graph: &ForgeGraph,
    seed: S,
    extension: Option<&dyn ForgeExtension<S>>,
) -> Result<ForgeArtifacts, String>;

The caller provides a validated graph, a seed value, and an optional extension hook. The compiler:

1. Validates the graph (returns an error on the first violation).
2. Computes a deterministic topological ordering over dependency edges.
3. Assigns each node a compiled id and a deterministically derived Genome.
4. Assembles compiled nodes and links into ForgeArtifacts.
5. Calls the extension hook's on_node and on_link for each item (if provided).
6. Records a CompileEvent in the provenance log.

Output is deterministic: same graph + same seed always produces the same artifacts.

ForgeSeedLike

pub trait ForgeSeedLike: Copy + Send + Sync {
    fn base_seed(&self) -> u64;
}

Implement this on your seed type. The base seed drives genome assignment across all nodes. For region the implementation is:

impl ForgeSeedLike for RegionSeed {
    fn base_seed(&self) -> u64 {
        self.deterministic_seed()
    }
}

ForgeArtifacts

pub struct ForgeArtifacts {
    pub forge_id: String,
    pub nodes: Vec<CompiledForgeNode>,
    pub links: Vec<ForgeLink>,
    pub chem_state: BTreeMap<String, serde_json::Value>,
    pub provenance: ProvenanceLog,
    pub dirty: DirtySet,
    pub warnings: Vec<String>,
}

Field	Purpose
forge_id	Copied from graph.graph_id
nodes	Compiled nodes in topological order (dependency nodes first)
links	All compiled edges, carrying kind and dependency flag
chem_state	Initial key-value output entries (generic node- and graph-level counts)
provenance	Append-only compile history
dirty	Tracks which node ids were modified during this compile pass
warnings	Non-fatal issues encountered during compilation

CompiledForgeNode

pub struct CompiledForgeNode {
    pub id: String,
    pub source_node_id: String,
    pub kind: String,
    pub genome: Genome,
    pub properties: BTreeMap<String, serde_json::Value>,
}

id is derived deterministically from the graph id and the source node id. genome comes from node_genome(base_seed, &[graph_id, node_id]) which uses a stable hash over those parts.

ForgeLink

pub struct ForgeLink {
    pub from_id: String,
    pub to_id: String,
    pub kind: String,
    pub is_dependency: bool,
}

is_dependency is true for Constraint and Produces edges. Domain-specific projection code can filter on this to reconstruct ordering constraints.

ForgeExtension

pub trait ForgeExtension<S: ForgeSeedLike> {
    fn on_node(&self, node: &mut CompiledForgeNode, seed: S);
    fn on_link(&self, link: &mut ForgeLink, seed: S);
}

The extension hook is called after each node and link is assembled. Use it for brand-specific property injection that does not belong in the generic compiler. Pass None if no per-node overrides are needed.

plant_region currently passes None; the hook is present for future brand extension points.

Helper Functions

/// Deterministic u64 hash over any sequence of string parts.
pub fn deterministic_hash(parts: &[&str]) -> u64;

/// Genome derived from a base seed and a sequence of id parts.
pub fn node_genome(base_seed: u64, parts: &[&str]) -> Genome;

Both are public so domain consumers can derive their own sub-identities using the same algorithm.

Provenance

Every compile call appends a CompileEvent to the provenance log:

pub struct CompileEvent {
    pub forge_id: String,
    pub node_count: usize,
    pub link_count: usize,
    pub timestamp_ms: u64,
}

The log is returned inside ForgeArtifacts.provenance. Consumers may attach additional WriteEvent entries as they project artifacts into domain-specific runtime structures.

Dirty Tracking

ForgeArtifacts.dirty is a DirtySet containing the compiled node ids that were modified in this pass (currently all nodes from a fresh compile). Consumers use it to identify which downstream projections need to be regenerated incrementally.