settled-reach/docs/diagrams/architecture/d239-tile-derivation-contract.d2

# D-239 — Tile derivation contract (resolves Q-101)
# Coarse->fine refinement chain: RegionProfile (~1km) -> ChunkContext (64m) -> VoxelColumn (1m)

vars: {
  color-bg: "#2a3040"
  color-stroke: "#333340"
  color-text: "#c8d0e0"
  color-accent: "#c8d8f0"
  color-prim: "#3a4a4a"
  color-warp: "#4a3a4a"
}

direction: right

inputs: Inputs (authored upstream only) {
  style.fill: ${color-bg}
  style.font-color: ${color-text}
  style.stroke: ${color-stroke}

  seed: seed {
    style.fill: ${color-bg}
    style.font-color: ${color-text}
  }
  atlas: atlas (L0-L4) {
    style.fill: ${color-bg}
    style.font-color: ${color-text}
  }
  body: "body-params\n(stellar / orbit / hydrosphere / lithology)" {
    style.fill: ${color-bg}
    style.font-color: ${color-text}
  }
}

climate: "Climate primitives (per 2x2 km district)" {
  style.fill: ${color-prim}
  style.font-color: ${color-text}
  style.stroke: ${color-accent}

  temp: "temperature  C  (nullable)\nsun + planet + atmosphere\nseason + day/night swing" {
    style.fill: ${color-prim}
    style.font-color: ${color-text}
  }
  moist: "moisture\n(separate primitive)" {
    style.fill: ${color-prim}
    style.font-color: ${color-text}
  }
  derived: "derived: precipitation / GlaciationGrade /\nvegetation+treeline / seasonal-clock (Q-105)\n+ scattered transient freeze+snow" {
    style.fill: ${color-prim}
    style.font-color: ${color-text}
  }
  temp -> derived
  moist -> derived
}

chain: Three-carrier refinement chain (pure, deterministic D-010) {
  style.fill: ${color-bg}
  style.font-color: ${color-text}
  style.stroke: ${color-accent}

  region: "RegionProfile  (~1 km)\nmorphology family + tectonic_class\n+ derived RIVER_THRESHOLD" {
    shape: hexagon
    style.fill: ${color-bg}
    style.font-color: ${color-text}
    style.stroke: ${color-accent}
  }
  chunk: "ChunkContext  (64 m)\nbasin-dir + meander-curve params\n(no per-tile flow grid)" {
    shape: hexagon
    style.fill: ${color-bg}
    style.font-color: ${color-text}
    style.stroke: ${color-accent}
  }
  voxel: "VoxelColumn  (1 m)\non-demand, cached, never persisted" {
    shape: hexagon
    style.fill: ${color-bg}
    style.font-color: ${color-text}
    style.stroke: ${color-accent}
  }
  region -> chunk -> voxel
}

morph: "8 morphology families\n(gated decision tree)" {
  style.fill: ${color-bg}
  style.font-color: ${color-text}
  fams: "Lava / Fjord / CliffCoast / BraidedDelta /\nDuneStrand / IncisedGorge / Meander / AlluvialPlain" {
    style.fill: ${color-bg}
    style.font-color: ${color-text}
  }
  gates: "hard gates: fjord>=Glaciation2 |\nLava=Volcanic | lithology bounds slope" {
    style.fill: ${color-bg}
    style.font-color: ${color-text}
  }
  vocab: "frozen 17-zone MorphologyZone vocab\n(enum = freeze point; change needs D-amendment)" {
    style.fill: ${color-bg}
    style.font-color: ${color-text}
  }
}

warp: "Domain warp (anti-squaring)\nstateless hash(seed, body, pos)\nf64 sub-metre -> truncate to voxel addr" {
  shape: parallelogram
  style.fill: ${color-warp}
  style.font-color: ${color-text}
  style.stroke: ${color-accent}
}

cache: "BodyWorldState cache (D-203)\nRegionProfile labels for the Atlas\n(populated in D-206 background pass)" {
  style.fill: ${color-bg}
  style.font-color: ${color-text}
}

# wiring
inputs -> chain.region: "(seed, atlas, body-params, position)" {
  style.stroke: ${color-accent}
}
inputs.body -> climate.temp {
  style.stroke: ${color-accent}
  style.stroke-dash: 3
}
climate.derived -> chain.region: gates morphology + freeze {
  style.stroke: ${color-accent}
  style.stroke-dash: 3
}
chain.region -> morph.fams: select family {
  style.stroke: ${color-accent}
}
morph.gates -> morph.fams {
  style.stroke: ${color-stroke}
}
warp -> chain.chunk: "organic, seam-free" {
  style.stroke: ${color-accent}
  style.stroke-dash: 5
}
warp -> chain.voxel {
  style.stroke: ${color-accent}
  style.stroke-dash: 5
}
chain.region -> cache: store labels {
  style.stroke: ${color-accent}
  style.stroke-dash: 3
}