Skip to content

Overview

plant_forge is the shared compile pipeline for all schema-driven simulation objects in Plantangenet. It owns graph validation, generator host plumbing, deterministic compilation, dirty tracking, and provenance logging. It has no knowledge of spatial models, world layout, or brand-specific types.

Purpose

Before plant_forge, each schema-based object (region, area, vehicle, creature) would have to independently reinvent:

  • A DAG of spec nodes and edges describing how runtime artifacts relate to each other
  • A JTL generator pass that populates node properties from genome traits
  • A deterministic compile step that assigns stable identities and propagates overrides through the graph

plant_forge captures that shared scaffold once. Region is the first consumer and the proof of correctness. Future ports (area, creature, vehicle, quest) inherit the same pipeline.

Crate Position in the Stack

plant_atom   (genome, entity, registry primitives)
     |
plant_frame  (ForgeService trait, FramePhase, HookContext)
     |
plant_forge  (ForgeGraph, compile_forge, ForgeRegistry, ForgeService)
     |
plant_region (RegionGraphSpec -> CompiledRegionArtifacts, spatial projection)
plant_world  (WorldSpecDocument, layout, services — consumes plant_runner)

plant_forge must not depend on plant_region, plant_world, or any brand crate. It may depend on plant_atom, plant_frame, and jtl-host.

The Compile Pipeline

Authored spec
    |
    v
ForgeGraph               — validated DAG of nodes and edges
    |
    v
run_generators           — JTL generators populate ForgeHost buckets
    |
    v
compile_forge            — topological compile; assigns deterministic genomes
    |
    v
ForgeArtifacts           — compiled nodes, links, chem_state, provenance
    |
    v  (domain-specific projection — stays in plant_region / plant_area / etc.)
Kind artifacts           — e.g. CompiledRegionArtifacts (cells, adjacency, subdivisions)
    |
    v
ForgeRegistry<TCompiled> — Pending -> Generating -> Compiled -> Registered -> Active
    |
    v
ForgeService             — ForgeService adapter; drives registry through frame phases

The projection step is the only place that knows about domain-specific types like Cell, CellAdjacency, or Subdivision. Everything above it is generic.

Modules

Module Purpose
graph ForgeGraph, ForgeNode, ForgeEdge, GraphValidationError, topological sort
host ForgeHost (JTL adapter), ForgeEvent, generator bucket extraction
generators run_generators(), sorted_generator_names()
compiler compile_forge(), ForgeArtifacts, ForgeSeedLike, ForgeExtension
dirty DirtySet, DirtyTracker — incremental rebuild tracking
provenance ProvenanceLog, CompileEvent, WriteEvent — append-only build history
registry ForgeRegistry<T>, ForgeRecord, ForgeLifecycleState
service ForgeService<TCompiled>, StateSnapshot — ForgeService bridge

Dependency Rule

If a type mentions Cell, CellAdjacency, Subdivision, WorldCellRect, or WorldGeometry, it stays in plant_region.

If a type only mentions graph ordering, generator overrides, compiled node identity, provenance, or frame lifecycle, it belongs in plant_forge.