# Hearth procedural composition

Hearth generates furnished timber-and-stone buildings and a connected settlement for Minecraft Java
1.21.1. The default seed is **0**; it produces five buildings, public paths, a well terrace, lights,
planters, trees and grass. Structural choices include room counts/functions/adjacencies, wings,
storeys, stair allocation, roof runs/pitches, porches, foundation strategies and street topology.
There is no whole-building family selector in the kernel or settlement generator.

Version **1.2.0** added a separate [extension package](hearth_extensions/README.md): diagonal bridges
and covered galleries, curve-following boundaries with attachment sockets, polygon halls with hipped
roofs, furnished activity areas, and explicit access graphs. New clients form branching campuses and
perimeter circuits. That phase preserved the original default content; its evidence remains archived.

Version **1.3.0** improves individual buildings with profile roofs, mounted dormers, deeper timber
facades, usable balconies, furnished activity groups, supported chimneys and domestic garden courts.
The kernel and CLI interfaces are unchanged. The default settlement now uses these shared improvements,
so its content changes deliberately with this version. Three new short building programs retain seeded
structural choices. See the [building-quality assessment](reports/building-quality/ASSESSMENT.md)
for that phase's results, retained failures, inspected views and the remaining gap to the lodge references.

Version **1.4.0** continues individual-building work: fitted rear openings, taller lodge windows,
framed window boxes, purpose-specific interior stations, fitted ceiling timbers, contrasting guards
and clustered planting around public building boundaries. A new lightweight garden-house program
forms varied wings around an open court. The kernel and original CLI remain unchanged. Current
results and limitations are recorded in [the building-detail assessment](reports/building-detail/ASSESSMENT.md).

## Quickstart

```sh
python generate.py
python generate.py --seed 0 --output example.litematic
python generate.py --seed 1 --count 6 --output "samples/six building village.litematic"
python -m pytest -q test
```

A successful command validates the composition, exports a nonempty single region, reloads it and
verifies its semantic content. Each schematic has a `.litematic.structure.json` companion. Keep the
pair together. Explicit paths may be relative, absolute or contain spaces.

No downloads, reference generator, previous output or credentials are used. Python 3.12 and numpy
are required; transport uses the provided MCIO **0.2.0** public API. It is imported normally, then
from `/work/generator/MCIO` in this environment. On another host, install MCIO from its source before
using export/reload. The Java blockstate reference is bundled under `hearth/data/`. Exact versions
observed here are recorded in [reports/dependencies.json](reports/dependencies.json); no additional
packages were installed. Rendering additionally needs the optional supplied MCRender toolset.

Importable generation itself uses the Python standard library and bundled block schema; numpy and
MCIO are loaded for schematic transport. The extension's import test forbids native/transport imports
during generation. This preserves the portability boundary, but is not a Pyodide execution test.

## Short compositions

These are intent descriptions; clients do not write voxels, repair geometry or assign block owners.

```python
from hearth.components.building import Blueprint, RoomSpec
from hearth.programs import building_scene

plan = Blueprint((
    RoomSpec(0, 0, 0, "living"),
    RoomSpec(0, 0, 1, "bedroom"),
    RoomSpec(1, 0, 0, "workshop"),
), bay=11, porch=True, roof_axis="auto")
scene = building_scene(plan, seed=17)  # No file export required.
```

Place on a previously generated environment:

```python
from hearth import Scene, Box, Frame
from hearth.environment import Terrain, gradient, wave
from hearth.components.building import adapted

scene = Scene(seed=17, domain=Box((-15, -4, -20), (40, 60, 40)))
field = gradient(x=0.025, base=4) + wave(amplitude=0.7)
scene.place("land", Terrain(scene.domain, field))
scene.compose_choice(adapted("home", plan, "/land", Frame((3, 0, 4), 1)))
scene.finalize()
```

Discover and substitute implementations:

```python
from hearth.kernel import Registry
from hearth.components.interior import Light
from extension_demo import Pendant

registry = Registry()
registry.register(Light())
registry.register(Pendant())
candidates = registry.select("room-light")
# Either implementation can be supplied as Blueprint(..., light_component=...).
public_ports = scene.view.offers("/home", "access")
capability = scene.view.capability("/home")
```

`hearth.composition` provides `encapsulate`, `attach`, `arrange`, `repeat`, `scatter` and `constrain`.
A composition returns `Plan(children=[Child(...), Choice(...)])` and uses the same component protocol
as a light or tree. Building, reading-suite and settlement interfaces support recursive port
forwarding. [ARCHITECTURE.md](ARCHITECTURE.md) documents frames, grants and the complete lifecycle.

## Runnable examples and batches

```sh
python -m examples.prototype --seed 0
python -m examples.building dwelling --seed 3 --output samples/dwelling-demo.litematic
python -m examples.building atelier --seed 5 --output samples/atelier-demo.litematic
python -m examples.building commons --seed 6 --output samples/commons-demo.litematic
python -m examples.courtyard --seed 0
python -m examples.gallery --seed 0
python -m examples.extension --seed 0
python -m examples.inspection --seed 0
python -m examples.assess --seed 0 --output reports/reassessment --artifacts
python -m examples.verify_replay --seed 0
```

The three primary programs are short room-graph recipes in `hearth/programs.py`. The courtyard and
gallery clients were written after the abstractions existed. The independent extension supplies an
actual pendant light and a nested reading suite using public components/validators. The gallery uses
that extension without geometry repairs. The courtyard exposed a generic concave-corner decoration
conflict, corrected by moving facade climbers away from corner installation margins.

The assessment command is an explicit batch output: it writes all inputs, results, rejections,
candidate scores, summaries and selected samples. Unit tests create only cleaned temporary files
under `test/`; they do not silently produce corpus artifacts.

Optional rendering, in the supplied proc-tool environment:

```sh
python -m examples.preview --seed 0 --input output.litematic --output previews/settlement --size 1500
python -m examples.preview --seed 6 --input samples/commons-6.litematic --output previews/commons-6 --cutaways
python -m examples.preview --seed 0 --input samples/adaptation-00.litematic --output previews/adaptation-00 --cutaways
python -m examples.preview --seed 1 --input samples/atelier-1.litematic --output previews/atelier-1
python -m examples.preview --seed 0 --input samples/courtyard.litematic --output previews/courtyard-0 --cutaways
```

The preview command checks the source pair and seed, then uses the supplied MCRender and cutaway
utilities. It writes labeled views, camera records and `views.json`. The stair section is chosen
from an actual stair instance's current cells. Geometry-only slices are not exported as completed
components and have no structural companion. See [previews/README.md](previews/README.md) for inspected
views and observations. Rendering is not needed for generation or tests and must not be invoked on
another host without the optional tools/assets.

## Individual buildings and shared craft

```sh
python -m examples.lodge home --seed 0 --environment-seed 0 --output "samples/my home.litematic"
python -m examples.lodge hall --seed 6 --environment-seed 6 --output "samples/my hall.litematic"
python -m examples.lodge high --seed 1 --environment-seed 1 --output "samples/my high house.litematic"
python -m examples.lodge_inspection --seed 0 --environment-seed 0 --output "samples/glass inspection.litematic"
```

These command labels select lightweight user programs in [hearth/lodges.py](hearth/lodges.py), not
building families inside the kernel. Their public intent can be recombined directly:

```python
from hearth.components.building import Blueprint, RoomSpec
from hearth.components.roofcraft import RoofDesign
from hearth.lodges import lodge_scene

design = Blueprint((
    RoomSpec(0, 0, 0, 'living'),
    RoomSpec(0, 0, 1, 'bedroom'),
    RoomSpec(1, 0, 0, 'kitchen'),
), bay=11, roof_design=RoofDesign(rise=(1, 2), dormer_spacing=8),
   porch_depth=4, balcony=True, chimney=True)
scene = lodge_scene(design, seed=17, environment_seed=5)
# Importable generation and exact inspection need no schematic export.
```

`lodge_scene` freezes a general field-generated terrain first. `field`, `water` and `garden=False`
are explicit alternatives; the garden requires dry planting space and is not silently omitted to
make a wet site pass. Use the existing `adapted` operation directly to place the same design on an
already generated environment. The original site/edit limits remain in force.

The new public building options are `roof_design=None`, `porch_depth=3`, `balcony=False` and
`chimney=False`. Balcony intent requires a porch and the front upper room. All room functions and
principal placements remain locked. The default room planner still uses bays 9/11/13 and six-cell
floor spacing. This phase improves its composition and completeness rather than replacing it with
an arbitrary floor-plan solver.

`RoofDesign` repeats integer rises of 1 or 2. Dormer spacing is 0 (disabled) or 7-16, with distinct
`left`/`right` sides. The assessed materials are deepslate tile or brick, with spruce/dark-oak trim.
`ProfileRoof` advertises width 7-64, depth 7-128 and axis x/z; scene bounds and existing supports still
apply. These parameter domains describe usable inputs, not exhaustive validation of every combination.
Obstructed dormer mounts are optional and every omission is recorded. Attics are explicitly
nonhabitable voids above sealed room ceilings, not extra furnished rooms.

A roof policy exposes `heights(span)` and `component(width, depth, axis, material)`. The latter returns
an ordinary component. The substitution test supplies a separate policy returning the original roof
without editing the building parent. For an external facade program, place a `RoofCover` with
`populate=False`, discover `scene.view.offers(host, 'roof-installation')`, and install `Dormer()`
using its port frame and `Binding(host, port.key)`. The 5-by-3 mount supplies scoped replacement
authority; callers need no private roof coordinates. Dormer glass retains its real window/wall/roof
chain even when the installing program is outside the host.

Furniture groups expose `interaction` ports. Their actual stations, paired beds, inventories and
routes are validated. Two groups leave space around a stair, four furnish an ordinary room, and
wider bays add domestic stations. Porches use depth 3-5; balconies include actual guards and an upper door.
`BearingCourse` provides a bounded support plate for a chimney over piers, preserving existing owners.
The shipped chimney uses a 3-by-2 plate and maximum anchor distance two, filling at most six cells.
The plate does not grant permission to alter a foreign support. Masonry flues do not simulate heating.

`GardenCourt`, `RaisedBed`, `GardenSoil`, `BedBorder` and `Landscape` reuse terrain grants, planting
support and public access. Landscape now exposes candidate step, separation and tree-height choices.
Garden refinements preserve three required trees rather than silently reducing the count.

Run a fresh bounded assessment without overwriting historical outputs:

```sh
python -m examples.building_quality --seed 0 --output reports/my-building-corpus --artifacts samples/my-building-corpus
python -m examples.building_holdout --seed 0 --output reports/my-building-holdout --artifacts samples/my-building-holdout
python -m examples.building_views --seed 0 --input samples/building-quality/final/home-0.litematic --output previews/my-home --size 1200
python -m pytest -q test/test_building_quality.py
python -m pytest -q test
```

The recorded policies precede their assessments. The main batch has 24 client runs, 64 frozen
environment/building pairings and 16 stress inputs. The post-fix holdout has 16 new pairings using
previously untried blend/transform compositions. Every input is attempted once with the same two
bounded contact alternatives; candidate acceptance is distinct from input success. The original
64-input sweep became regression evidence after revealing a missing bearing, so the subsequent
holdout is identified separately. All prior failures and their generating expressions remain recorded.

Selected full pairs in [samples/building-quality](samples/building-quality/README.md) retain every
node and current-cell query after reload. The inspection example prints a selected roof-window glass
coordinate, typed relationships, exact membership and the identical reloaded query. Final
[previews](previews/building-quality/README.md) include three exterior angles and floor/circulation
cuts. Cuts are geometry-only render aids; validation and identity claims concern the full pairs.

The third-phase [API delta](reports/building-quality/api-delta.md) records unchanged kernel, transport
and earlier extension modules. The standard-library import guard passes for new generation; this is
not a new browser execution. The previously reported Pyodide evidence remains historical.

## Continued building detail

The public additions are `Blueprint(facade_design=..., rail_material=...)`, `FacadeDesign`,
`DomesticSuite`, `WindowBox`, `CeilingTimbers`, `GardenPlant` and `BoundaryPlanting`.
Existing constructor defaults remain compatible. The lodge programs and default settlement explicitly
request the new facade policy and dark-oak guards. Current component realizations change with version
1.4; same-version seeded replay remains required.

```python
from hearth.components import Blueprint, RoomSpec, FacadeDesign
from hearth.components.roofcraft import RoofDesign
from hearth.lodges import lodge_scene

design = Blueprint(
    (RoomSpec(0, 0, 0, 'living'), RoomSpec(1, 0, 0, 'kitchen'),
     RoomSpec(0, 0, 1, 'bedroom')),
    bay=11, roof_design=RoofDesign((1, 2)), chimney=True,
    porch_depth=4, balcony=True, facade_design=FacadeDesign(),
    rail_material='dark_oak')
scene = lodge_scene(design, seed=7, environment_seed=4101)
```

Facade widths are 1 or 2, heights 2 or 3, and sill height is at least 1 with `sill + height <= 4`.
The default policy uses tall openings with framed planters. Window projection is negotiated as one
or two cells; enclosing room and building envelopes expand deliberately for framed boxes. Windows
beside a lower roof can be flush. Faces within conservative gable envelopes have their optional
openings omitted, recorded in `room.contract.decisions['omitted_optional_facades']`. Service exclusions
are room-local `Box` values shared by the facade components. They reserve design space, never edit authority.

External installers discover mounts without using private geometry:

```python
from hearth import Binding
from hearth.components import WindowBox

# window_path identifies a placed window whose garden mount has not been used.
mount = scene.view.offers(window_path, 'window-garden')[0]
scene.place('flowers', WindowBox(), frame=mount.frame,
            bindings=(Binding(window_path, mount.key),))
scene.finalize()
```

`Window(garden_depth=2)` exposes the larger mount; `planter=True` populates it internally. A box's
query chain includes the actual window and host wall. Its soil, flowers and boards share an atomic
object, and failed installation rolls back all cells, port uses and ownership. `ceiling-decoration`
ports similarly support independent installers, with zero replacement authority. Ceiling timbers
fit around actual stair clearance and lights; they cannot overwrite those fixtures.

`DomesticSuite(purpose, width)` supports widths 2/3 and purposes `gathering`, `study`, `cooking`,
`craft` and `cabinet`. All expose an `interaction` apron and actual support/function checks.
The shared room planner composes these alongside complete beds, workstations and inventory-bearing
barrels. Adding an unrelated planted border leaves the building's geometry and primary structure stable.
Adding a connected path may legitimately transfer ownership of the approach endpoint; that is a real dependency.

`BoundaryPlanting(building, terrain, density=.55, minimum_distance=2, maximum_distance=4)` discovers
the host's `footprint-boundary` outline. Distances are Manhattan distances, bounded 1-6; density is
0-1. A clustered preference field selects candidates, while actual soil, occupancy, protected routes
and planting permission decide legality. Its optional minimum is zero and rejected candidates are
reported. Tall plants remain whole objects. No terrain edits occur. Tree crowns now have tapered,
separated branch tiers within the original radius/height domain.

```sh
python -m examples.garden_house --seed 2 --environment-seed 4100 --output "samples/my garden house.litematic"
python -m examples.building_detail --seed 0 --output reports/my-detail-corpus --artifacts samples/my-detail-corpus
python -m examples.building_quality --seed 0 --output reports/my-detail-regression --artifacts samples/my-detail-regression
python -m examples.building_holdout --seed 0 --output reports/my-detail-prior-holdout --artifacts samples/my-detail-prior-holdout
python -m examples.building_views --seed 2 --input samples/building-detail/release-new-composition/court-2.litematic --output previews/my-garden-house --size 1200
python -m pytest -q test/test_building_detail.py
python -m pytest -q test
```

The [sampling policy](reports/building-detail/sampling-policy.json) declares inputs and domains.
Earlier corpus outputs remain unchanged. This phase retains intermediate failures separately and
uses `release*` directories for the assessed final implementation. Raw proc renders and camera/cut
records are under `previews/building-detail`. A diagnostic tint demonstrated that the previously
"missing" spruce furniture and fences were present but visually blended into spruce decks; no
renderer patch or schematic repair is needed. Current contrasting timber makes those details legible.

## Seeds, domains and adaptation

Seeds are explicit signed Python integers. SHA-256 derives streams from seed, stable instance keys
and purpose; Python `hash()` and ambient randomness are never used. Planning, adaptation, geometry,
materials and decoration use separate purpose keys. `Child(..., seed=...)`, `Scene.place(..., seed=...)`
and `regenerate(..., seed=...)` override a subtree. `Scene.fork(seed=...)` preserves existing frozen
content and changes only the seed for future placements. Stable independent branches commute;
dependent grass/tree replacement intentionally does not.

The delivered building planner supports connected grid rooms with bay sizes **9, 11 or 13**, six
furnishing purposes, supported stacked levels, shared horizontal circulation and one vertical flight
per upper connected group. Ordinary room contracts support the same bay sizes. Walls expose widths
5-64, heights 4-12 and thicknesses 1-3. Other implementations can advertise different feasible domains;
the kernel has no room-grid or building-count dispatch.

Site policy defaults: measured relief at most **5**, bed-to-floor support height at most **8**, at least **two contiguous solid bed cells**, approach
length at most **12**, foundation fill at most **1,600** cells and excavation authority bounded by the
terrain grant (default 2,500 changes per binding). `SiteLimits` and grants expose these values. Contact
alternatives compare actual effects, permitting local piers, stepped perimeter work and access treads.
The default buildings do not excavate; the pool component exercises authorized excavation separately.
Small terraces fill bounded local differences. The major terrain surface is not flattened.

Hard constraints include write authority, existing consumers, declared support/headroom, protected
regions, locked room functions and placement. Preference fields and style roles are public observations.
Preferences do not override constraints. Unknown space is an error. The kernel rejects effects outside
accepted envelopes and derives export bounds from realized content, including vegetation and adapters.
`Limits` controls dimensions, block count, instances, recursion, candidate budget and dense export volume.

The new polygon vocabulary is independent of `Blueprint`'s bay grid. `Pavilion` accepts normalized
simple footprints 13..25 blocks across, multiple declared cardinal entrances, heights 5..7 and hipped
roof runs 1..3. `Link` supports simple diagonal/bending routes, width 3 or 5, bounded rise, actual-bed
trestles and narrow endpoint transitions. `BoundaryChain` composes continuous bounded contour segments.
The [extension domain table](hearth_extensions/README.md#supported-domains-and-limits) states exact
constraints and interfaces. There is no unlimited route planner, arbitrary concave-room solver, or
automatic graph embedding. Explicit vertex frames and port choices remain the client's intent.

A completed standalone building offers an exterior landing. Its enclosing composition is responsible
for a public path beyond that landing; a wet site can offer a boardwalk landing. The settlement fulfills
this obligation and exposes its own public gateway. It can be translated and rotated as a composite.

## Inspection, identity and regeneration

```python
from pathlib import Path
from hearth.persistence import export_scene, load_scene

point = next(p for p, cell in scene.blocks.items() if cell.state == "minecraft:glass")
explanation = scene.inspect(point)
print(explanation["chain"], explanation["related"], explanation["operation"])
cells = scene.cells(explanation["instance"], descendants=True)
export_scene(scene, Path("sample.litematic"))
restored = load_scene(Path("sample.litematic"))
assert restored.inspect(point) == explanation
```

The runnable inspection example selects actual room glass and prints its window, host wall, room and
building chain, typed relationships and exact cells before and after reload. See
[reports/inspection.txt](reports/inspection.txt). `cells(..., descendants=True)` follows semantic
attachment/containment indexes, including windows installed by a higher-level facade program.
`shared=True` includes explicitly shared supports. Removed/displaced objects are not current owners.

World coordinates are `(x,y,z)`. Export coordinates subtract the JSON `offset`; reload restores the
world coordinates. Quarter-turns transform states, ports, claims and ownership consistently. Explicit
property mappings compare regardless of order; omitted properties are never inferred for equality.
Inventory NBT is transported and verified. Missing, unknown or mismatched companions are rejected;
a bare schematic is not claimed to contain its original semantic graph.

`scene.regenerate("/land", new_terrain, dependents=("/house",))` explicitly replaces affected output
and replays dependent branches. Old displaced terrain is restored before replay. Dependency records
include automatic spatial/interface read traces and input versions. Invalidated branches cannot be
exported as completed. After reload, regeneration requires an explicit component implementation;
serialized metadata is never executed as Python.

When replay must first rebuild unchanged hosts and then replace a connector, use the additive
mapping introduced by the extension probe:

```python
scene.regenerate("/a", dependents=("/b", "/link"),
                 replacements={"/link": revised_link})
```

Every mapping key must be an explicit replay target. Target order, frames and stable random scopes
remain explicit. This is an atomic bounded replay, not an automatic dependency loop. `connect`
bindings now consume capacity without acquiring a host's separate mutation grant. The two changes
and their pre-change failures are recorded in [api-delta.md](reports/extensions-baseline/api-delta.md).

For extension artifacts, import `hearth_extensions` before `load_scene` to register its validators.
`python -m examples.extension_inspection --seed 0 --input samples/extensions/campus-0.litematic`
prints actual deck, glass and mounted-light queries, exports the pair and verifies the same queries
after reload. [inspection.json](reports/extension-corpus/inspection.json) retains a completed run.

## Diagnostics and failure behavior

`ContractError.diagnostic` contains `rule`, `component`, `position` and `conditions`.
`ValidationError.diagnostics` reports actual geometry violations. Examples include `write-authority`,
`whole-object`, `edit-limit`, `protected-region`, `support`, `clearance`, `reachability`, `lighting`,
`door-pair`, `pool-containment`, `forwarded-interface` and `geometry-mismatch`.

Failed candidates leave the entire scene unchanged. `SearchExhausted` distinguishes a search budget
from an established parameter/contact incompatibility. A failed finite search does not prove that
no other algorithm or composition can succeed. Tests include a budget-limited rejection where the
next, unvisited candidate is valid.

## First-phase evidence and continuing limits

The frozen sampling policy is [reports/sampling-policy.json](reports/sampling-policy.json).
The retained first-phase results are [reports/final-corpus/results.json](reports/final-corpus/results.json),
[summary.json](reports/final-corpus/summary.json) and
[adaptation-inputs.json](reports/final-corpus/adaptation-inputs.json). Earlier result records remain
under `reports/baseline-corpus/` and `reports/corpus/`; their historical sample paths are labeled as
superseded, not current matching artifacts.

[reports/ASSESSMENT.md](reports/ASSESSMENT.md) gives denominators, costs and timings: **134 tests
passed**, **64/64** adaptation inputs, **24/24** building runs and **10/10** settlement runs validated.
The stress batch retained **9 valid / 32 inputs**, plus **23 explicit limit incompatibilities**.
There were no budget-exhausted or unexplained-defect cases in the final corpus. Per-candidate
acceptance is reported separately. Seed-0 content matches across two Python hash seeds in
[reports/replay.json](reports/replay.json). All **24 delivered current artifact pairs** passed reload
and identity checks in [reports/artifact-audit.json](reports/artifact-audit.json).

The assessed finite budget consists of 64 independent environment/building pairings, 24 building
runs (three clients, seeds 0-7), ten settlement runs (seeds 0-7 plus both count boundaries), and 32
unresampled stress inputs. Sixteen complete terrain scenes are frozen independently before placing
buildings. Half the environment expressions use the held-out blend/transform composition. The same
public measured-geometry adapters handle all cases.

The reported successful building corpus has **18** observed principal signatures: dwelling **5/8**,
atelier **8/8**, commons **5/8**. The ten settlement runs have **10** observed signatures. Signatures
exclude names, surface materials and global placement; they include actual room extents, adjacencies,
storeys/stairs, roof geometry and path organization. Foundation/contact signatures are reported
separately and never counted as principal architectural variety. This is finite observation only.

Known limits remain explicit:

* The movement model uses integer standing positions, operable wooden doors, two-cell headroom and
  bounded one-block elevation changes. It is not the full Minecraft collision or jump simulation.
* Lighting uses actual source propagation/occlusion at required room locations; it is not a complete
  skylight, mob-spawning or Minecraft update simulation.
* Declared support paths and bounded spans are checked. Arbitrary structural stress, every decorative
  cantilever, and universal watertight flashing for arbitrary roof intersections are not proved.
  The original roof system handles bounded gables, runs and wall abutments over sealed ceilings.
  The extension adds polygon hip courses and a bounded roof lantern, not arbitrary roof intersections.
* General block/entity migration, arbitrary entity generation, a browser viewer, and a full city
  planner are not implemented. Exported entity lists are empty; barrel inventories are real NBT.
* Regeneration is explicit and can be coarse. The kernel records affected dependencies and refuses
  stale completion; it does not invent an unbounded automatic replan or resolve every terrain shape.
* The provided style is coherent timber/stone architecture, with visible modular bays. The small
  representative render set supports inspection, not an exhaustive aesthetic judgment or a claim
  to reproduce all sixteen reference images.
* The courtyard example's central planted void is an unoccupied lightwell. Its room ring is connected;
  visitor access to the central garden is not part of that client's contract.

## Extension-phase commands and evidence

The extension programs use the same public contracts; they do not alter the default CLI or invoke
reference generators. A low-level example connects already placed buildings without knowing their
private geometry, and a graph example substitutes different access providers, in
[hearth_extensions/README.md](hearth_extensions/README.md).

```sh
python -m examples.extension_generate campus --seed 3 --environment-seed 7 --output "samples/new campus.litematic"
python -m examples.extension_generate perimeter --seed 3 --environment-seed 3 --output "samples/new perimeter.litematic"
python -m examples.extension_assess --seed 0 --output reports/extension-reassessment --artifacts --samples samples/extension-reassessment
python -m examples.extension_audit --seed 0 --manifest samples/extension-reassessment/replay-manifest.json --output reports/extension-reassessment/artifact-audit.json --cli
python -m examples.extension_replay --seed 3 --environment-seed 7 --output reports/extension-reassessment/replay.json
python -m examples.extension_views --seed 0 --input samples/extensions/campus-0.litematic --output previews/extension-reassessment --sections
```

Each environment is generated independently and frozen before placement. `--seed` controls structure;
`--environment-seed` controls the field input. Assessment `--seed` selects the root environmental
seed range; structure seed ranges remain the explicit sampling policy. `--samples` prevents a new
assessment from overwriting earlier matching pairs. Unit tests continue to use cleaned temporary
directories under `test/`.

[reports/extension-corpus/ASSESSMENT.md](reports/extension-corpus/ASSESSMENT.md) reports the new test,
sampling, identity and render results with denominators and limits. It supplements every first-phase
result above. The [frozen policy](reports/extension-corpus/sampling-policy.json) defines 48 connector
pairings, 16 boundary pairings, 12 hall runs, 12 graph runs and 24 unresampled stress inputs. The
[interior refinement policy](reports/extension-corpus/interior-refinement-policy.json) repeats those
same inputs after a cutaway-driven furnishing improvement. Prior results and matching artifact pairs
are retained. Principal signatures exclude contact geometry and cosmetic/furnishing counts.

Only two general kernel behaviors changed: read-only connection authority and explicitly mapped
coupled replay replacements. There is no private-state access in the extension's components or
ordinary clients. Metadata inspection and assessment intentionally read the public structural records.
Clients still need documented public port kinds, frames, dimensions, grants and locked placement
intent. A new architectural technique requires an implementation with a valid contract; this is not
an unrestricted description-to-building solver. The supplied style remains relatively restrained,
and a finite render set does not establish universal aesthetic quality.

The user's external report describes successful prior Pyodide executions. This phase preserves the
pure-Python boundary, runs native hash-seed replay and restores complete structural records from its
new pairs. It does **not** claim a new browser execution or independent audit.

## Requirement ledger

| ID | Implemented API/module and evidence | Qualification |
|---|---|---|
| R01 | `kernel/*`, initial design, seven foundation tests before content; thin CLI | Executable foundation, not placeholder interfaces |
| R02 | Independent implementation; supplied snapshots unchanged; reference images used as aesthetic goals | No reference generator invoked or imported |
| R03 | `Blueprint`, room graph programs, `Choice`, roof planner, spine/loop paths; finite signatures | Room grid and roof primitives are bounded, openly documented |
| R04 | Module table in architecture; kernel has no component imports; transport separate | Browser host adapter not implemented |
| R05 | `Capability`, executable `Domain`, `Contract`, `Port`, `Grant`, rules and read-only `View` | Free-form descriptive assumptions complement executable checks |
| R06 | `Plan/Child/Choice`, registry, composition operations, forwarded ports; extension/nested tests | New primitives can extend beyond the shipped grid vocabulary |
| R07 | Scoped authority, whole-object replacement, shared support; tree/grass/pool/window/clearance tests | No universal priority or same-state sharing shortcut |
| R08 | Fork/validate/commit kernel, plans and automatic read traces; rollback snapshots | Trusted Python components, not a hostile-code sandbox |
| R09 | Open/complete scopes, ancestor-aware obligations, finalization; unfinished/light and late-edit tests | Standalone landing-to-public-path is an enclosing obligation |
| R10 | Automatic nodes/operation owners, real window/wall instances; inspection and cross-scope attachment tests | No per-voxel client owner maps or post-hoc tagging |
| R11 | Structural graph, dependency graph, operations/displacement records; update/share/removal tests | Historic actors may remain in history, never as current owners |
| R12 | `inspect`, owner/shared reverse indexes, semantic descendant index; regeneration and deletion tests | Headless queries delivered; no clickable viewer |
| R13 | Paired JSON/Litematica, version/digest/offset checks, actual reload validation; mismatch/NBT tests | Pairing integrity is not cryptographic authenticity |
| R14 | General field algebra, masks, transforms, strata, water and constrained scattering | No environment-family dispatch; finite shipped operations are extensible |
| R15 | Domain/version-aware 3D view, elevation cap, support/water/slope/clearance/style/preferences | Unknown space errors; no simulation of every Minecraft behavior |
| R16 | Foundation, approach, window-depth and roof-abutment components | Universal roof-junction/flashing solver not implemented |
| R17 | Frozen terrain, measured site survey, bounded complete candidates, joint tentative validation | Fixed principal intent; failures beyond bounds are retained |
| R18 | Hard checks then actual effect cost/exposure score, seeded near-best choice, rejection records | Search-budget negative test; no claim of exhaustive feasibility |
| R19 | Automatic/declared input dependencies, stale flags, explicit atomic co-regeneration | Dependency updates are conservative; no implicit arbitrary auto-replan |
| R20 | SHA-256 scope keys/purposes, overrides, copied environments; branch/order/retry and hash-seed replay tests | Genuine spatial dependencies may change descendants |
| R21 | Configurable `Limits`, `SiteLimits`, effect envelopes and realized export bounds | Demonstration count bound is only in the CLI |
| R22 | Initial design, kernel tests, prototype, buildings/extension, corpus/render stages | Generic defects and fixes recorded in development findings |
| R23 | `test_kernel`, `test_contracts_provenance`: substitution, independent extension, authority, rollback, sharing, transforms, seeds | Custom validator registration also tested |
| R24 | Glass chain, two identities, external attachment membership, updates/deletions/regeneration, shared cells, transport mismatch tests | Actual structure restored from companion, not inferred from materials |
| R25 | 64 frozen pairings, compatible independent field/environment, protected outside cells, perturbation and stress records | Finite supported domain; 32 stress inputs retained without resampling |
| R26 | Three short clients x eight seeds; settlement x eight seeds plus counts 3 and 6; later courtyard/gallery | Programs use public room/component APIs |
| R27 | Actual blocks/NBT: schema, support, headroom/routes, pair consistency, enclosure, lights, furnishings, pools and path joins; deliberate damage tests | Physical/lighting model limitations above apply |
| R28 | Structural/contact signatures, exterior views, circulation/furnishing cutaways, inspection notes | Modular aesthetic remains visible; no exhaustive beauty claim |
| R29 | `generate.py`, importable scene builders, inspection example, verified one-region transport | Offline runtime uses bundled schema and installed/provided MCIO |
| R30 | Library, docs, CLI, tests, extension, output pair, manifest, reports and labeled previews | Broader simulation, arbitrary entities, browser UI and city planner remain unfinished |

The first-phase ledger above remains applicable. This supplemental ledger maps every requirement
to the new work or its explicit regression evidence; qualifications from both phases apply.

| ID | Extension-phase API and evidence | Remaining boundary |
|---|---|---|
| R01 | Pre-change API/hash baseline; unchanged-kernel probe; separate extension modules and focused tests before client expansion | Self-authored exercise |
| R02 | New package, geometry and graph clients; original snapshots untouched | No reference code reused |
| R03 | `Polygon`, `Pavilion`, `HipRoof`, `Link`, `Campus`; actual massing/topology signatures | Finite vocabularies and explicit graph placements |
| R04 | `hearth_extensions` imports public kernel/services; generation, CLI, assessment and previews separate | No new browser runtime claimed |
| R05 | Endpoint kind/frame/width/capacity checks; fixture grants; domain/grade/fill/span contracts | Point endpoint offers are not broad landing replacements |
| R06 | `BoundaryChain`, `Campus`, `HallInterior`; forwarded mounts/access; platform/pavilion substitution test | Arbitrary concave layouts remain outside assessed domain |
| R07 | Read-only connection negative write test; scoped terrain edits; overflow, protected aisle and whole-removal tests | New connectors do not acquire host resurfacing permission |
| R08 | Full geometry/graph/index rollback snapshots in `test_extension_failures` | Same trusted-component boundary |
| R09 | Final graph routes and reachable interior stations; late blockers rejected | Open galleries deliberately lack enclosed-room obligations |
| R10 | Actual trestle/deck/window/shell/bay/lamp children; headless inspection output | No hand-authored ancestry |
| R11 | Two endpoint associations, attachment vs containment, separate input reads and operation records | Existing semantic graph model retained |
| R12 | Exact current cells across replacement/removal; transform and audit queries | No viewer added |
| R13 | New manifest audit compares regenerated nodes, graphs, inventories and queries with reloaded pairs | Validator package import required; bare geometry remains untrusted |
| R14 | General field expressions plus curves, polygon masks and explicit connection graphs | Simple discrete geometry, not a general mesh engine |
| R15 | Frozen 3D support/water/occupancy queries along routes and contour bases | Unknown space still errors |
| R16 | `Trestles`, bounded route profile, endpoint mouth transitions, terrain-following boundary | Finite engineering strategies |
| R17 | Frozen environments, locked endpoints/vertices, local grants, atomic link and campus placement | No moving locked buildings to hide failures |
| R18 | Feasible profile propagation and furnishing-domain construction; stress diagnostics retained | One locked complete candidate per assessed input; no exhaustive search claim |
| R19 | Explicit `regenerate(..., replacements=...)`; coupled host/link and boundary/lamp replay tests | Conservative coarse invalidation remains |
| R20 | Scoped streams, hash-seed subprocess replay, failed-choice stability; baseline default digest retained | Real constraints may affect dependent branches |
| R21 | Existing limits plus route length, span, fill, per-segment contour and bounded furnishing domains | Library count is not fixed to demo size |
| R22 | Baseline -> failing probe -> protocol delta -> components -> new clients -> corpus -> inspected refinement | Development failures retained |
| R23 | New extension protocol/geometry/failure/interior tests plus all unchanged original tests | Extension is not an external audit |
| R24 | Shared endpoint ownership, deletion/replacement, transforms, every-node audit, mounted-light and window chains | Companion format remains version 1 |
| R25 | 64 new independent environment/structure connector and boundary pairings; novel kink/polygon test; 24 stress rows | Not a proof over all parameter combinations |
| R26 | Original 3 clients x seeds 0-7 and count boundaries retained; two new graph clients x seeds 0-5 and 12 polygon halls | New graphs add to, not replace, original corpus |
| R27 | Actual route/headroom/support/guard/frame/fixture/interior tests, damage cases, inventory reload | Discrete movement, lighting and bounded-span model |
| R28 | New principal/contact signatures, multi-angle views, floor/connection sections; shared interior refinement | Open lawns and modular material language remain visible |
| R29 | Original `generate.py` unchanged; no-argument, seed-1, spaced paths and hash-seed replay checked | Transport dependencies unchanged |
| R30 | Separate docs/reports/samples/previews, replay manifests and runnable batches | Browser rerun, autonomous city planner and broader simulation remain unfinished |

## Third-phase requirement evidence

The two ledgers above describe retained earlier work. This ledger supplements every requirement for
the version-1.3 individual-building revision. [That assessment](reports/building-quality/ASSESSMENT.md)
reports 200 passing tests, 104/104 supported inputs and 5/16 stress successes with all outcomes kept.
The complete new tests are in [test_building_quality.py](test/test_building_quality.py).

| ID | Current public implementation and evidence | Qualification or remaining work |
|---|---|---|
| R01 | Pre-edit review/hash record; unchanged executable kernel; craft components, focused tests, then clients/corpus | No replacement architecture or monolithic compiler introduced |
| R02 | All eight lodge images opened; baseline/final proc views compared; no reference source used or changed | Aesthetic influence only, no one-to-one reconstruction claim |
| R03 | `RoofDesign`, seeded room graphs/wings/storeys, roof axes/profiles, dormers, balconies; 18 observed principal signatures in 24 clients | Regular bay planner remains; no estimate of total combinations |
| R04 | Separate craft modules, external registered validator, intent programs, assessment and preview clients; kernel/transport hashes unchanged | Native import guard passes; browser not rerun |
| R05 | Roof mounts expose frames/regions/height/capacity/grants; bearings, interaction ports and rules are negotiated | Domain bounds are not exhaustive proofs over every combination |
| R06 | `ProfileRoof` -> cover -> dormer -> wall -> window; independent policy substitution and external mount installation tests | Roof policy remains a documented Python structural interface |
| R07 | Scoped dormer cuts, read-only facade binding, support-preserving bearing course; overflow/late-blocker negatives | Existing tree/grass/pool/sharing/whole-object tests retained unchanged |
| R08 | Every new write returned in a normal Plan; candidate rollback snapshot tests include all graphs/indexes | Trusted-component model unchanged |
| R09 | Room furniture/access/light obligations, balcony exit, actual building-to-street route | Attics explicitly nonhabitable; no unfulfilled room claims |
| R10 | Real dormer walls/windows/groups/adapters, automatically recorded owner/operation/host chains | No client per-block maps or post-generation tagging |
| R11 | Public roof attachments, porch connection, bearing dependencies; inspected typed relations and generating records | Support and generation history remain separate from containment |
| R12 | Every selected pair checks all exact current-cell sets; old dormer branches disappear on regeneration | No interactive viewer requested or added |
| R13 | 15 new full pairs audited for complete graph and geometry/NBT identity; default also fully audited | Format 1 retained; bare schematic does not recover semantics |
| R14 | Same general fields, blended/transformed holdout and constrained garden scatter | No new environment selector or whole-scene recipes hidden in components |
| R15 | Measured roof abutments, bounded ground observation, actual bearing anchors, dry planting checks | Unknown space and protected geometry keep original behavior |
| R16 | `BearingCourse`, supported chimney/porch, measured dormer adapter | General structural mechanics and arbitrary flashing remain outside scope |
| R17 | Frozen environments, locked principal signatures, bounded pier/stepped candidates; wet sample rendered | No limit widening, whole-site flattening or unlocked relocation |
| R18 | Existing quality-scored candidates and hard checks; every rejection/attempt retained | Stress relief failures remain failures; finite search is not universal infeasibility |
| R19 | Existing dependency capture and atomic replay; remove old dormers and exact references test | Explicit replay remains coarse and implementation supplied after reload |
| R20 | Separate feature/geometry scopes, unchanged randomness service, failed-candidate regression, native hash-seed replay | Same-version determinism preserved; version 1.3 deliberately changes default content |
| R21 | Existing limits/envelopes plus roof, porch, chimney and bearing bounds; actual export extent | Demonstration building count remains outside the kernel |
| R22 | Review -> shared components/negative tests -> new clients -> frozen corpus -> inspected fixes -> complete regression | Earlier stages and failed attempts retained, not rewritten |
| R23 | All 179 earlier tests plus 21 craft cases; roof substitution, public external installation, rotations and rollback | Self-authored extension evidence, not an independent audit |
| R24 | Dormer glass/wall/building chain, distinct same-glass owners, regeneration, complete paired graph/index/query audits | Original deletion/property/shared-ownership tests remain |
| R25 | 64 current frozen pairings plus 16 new post-fix pairings, independent inputs and 16 retained stress cases | First 64 became regression evidence after finding the bearing defect |
| R26 | Three additional short building programs x seeds 0-7; original settlement seed/count-boundary tests retained | Settlement planning was not expanded this round |
| R27 | Actual roof cover, support, guards, paired parts, routes, light and furnishing/NBT checks; deliberate damage cases | Discrete movement/light/support approximation remains explicit |
| R28 | Principal/contact signatures separated; 20 final exterior/cutaway renders and retained visual findings | Still below lodge reference richness; some fence segments poorly shown by proc render |
| R29 | Unchanged CLI; default, seed 1/spaced output, two seed-0 hash replays, import-only generation and glass inspection succeed | MCIO remains a transport dependency; no new downloads |
| R30 | Updated architecture/usage/ledgers, new modules/examples/tests, current default pair, preserved samples/reports/previews | Unusable attics, regular bays, sparse landscape, broader simulation and browser rerun remain limitations |

## Continued building-detail requirement ledger

The earlier ledgers and historical results remain intact. This supplement describes version 1.4,
whose [assessment](reports/building-detail/ASSESSMENT.md) reports **230 passing tests**, **124/124
supported inputs**, **5/16 stress successes**, **26 principal signatures across 32 client inputs**,
and **25 inspected final images**. Development failures are retained and distinguished from final
`release*` evidence. The [API delta](reports/building-detail/api-delta.md) documents additions.

| ID | Current public implementation and executed evidence | Qualification or remaining work |
|---|---|---|
| R01 | Pre-edit review and hashes; shared facade/domestic/planting components; 30 focused new tests before final assessment | Existing architecture retained; no one-off compiler or geometry repair in clients |
| R02 | All eight original lodge images opened and compared with 25 final views; supplied sources unchanged | Aesthetic reference only; no reference generator invoked |
| R03 | New `garden_house` room graph, variable upper/long wings, profiles and bays; 26 observed principal signatures across 32 client inputs | Regular bays remain; interior/planting counts do not inflate principal diversity |
| R04 | New knowledge stays in `components/*`; kernel, transport, environment and extension hashes unchanged | Native import guard rerun; browser execution not rerun |
| R05 | Discoverable window-garden, ceiling-decoration and footprint-boundary interfaces; declared frames, domains, regions, grants and rules | Public mounting conventions remain necessary knowledge for implementers |
| R06 | `DomesticSuite` uses existing interaction convention; nested boxes, plants and late ceiling components use ordinary lifecycle; new U-shaped client | Components are reusable; no claim of arbitrary prose-to-building planning |
| R07 | Scoped sill replacement, zero-replacement ceiling grant, terrain planting bindings; whole-object, support, overflow and rollback tests | Boundary preference never grants authority; existing consumers remain protected |
| R08 | All new geometry uses `Plan`; failed frames/permissions restore cells, records and port uses; original transaction tests retained | Trusted Python component model unchanged |
| R09 | Existing completion obligations validate rooms and enclosing connections; late beams preserve headroom/lights | Wet building fixtures expose local access, leaving shore/public connection to an enclosing scope |
| R10 | Real WindowBox -> window -> wall -> room -> building and ceiling -> room chains arise from bindings | No client owner maps, handwritten ancestry or post-generation classification |
| R11 | Typed `landscapes` association remains separate from containment and support; endpoint ownership changes only through real path dependency | Adding a connected path is not claimed to be independent |
| R12 | Transformed install/removal/current-cell tests; selected pair queries; 1,663 default/seed-1 descendant queries match reload | Exact membership maintained; no viewer added |
| R13 | 22 selected pairs: 5,635 nodes, 5,213 component queries, 895 inventory cells; two complete CLI pair audits | Existing format/digest semantics unchanged; geometry alone remains insufficient |
| R14 | Existing general fields, new blended gradient/wave/radial inputs, clustered boundary density and measured planting | No environment category selector or terrain shaped for a locked house |
| R15 | Actual overhead support, soil, occupancy, protected routes and port-local boundaries; independent inputs frozen before use | Boundary outline is design geometry, not a support or permission claim |
| R16 | Existing contact/bearing adapters plus fitted public ceiling/window mounting | Contact strategy repertoire remains stepped/pier; no new general mechanics solver |
| R17 | Locked designs cross frozen environments; authority and contact bounds unchanged; water sample inspected | Garden-less wet fixture has no shore path; major terrain shape preserved |
| R18 | Existing hard checks and cost-based candidate choice; 183/248 supported candidate acceptance reported separately from 124/124 input success | Stress failures retained; neither finite failure nor finite success proves universal feasibility |
| R19 | Existing dependency capture/regeneration; exact window-box replacement and stale-owner tests; substrate/ceiling support consumers | Replay remains explicit and can be coarse |
| R20 | Station ordering and planting have scoped keys; independent border test, two hash-seed replays, same semantic digest | Version 1.4 changes content deliberately; no cross-version geometry guarantee |
| R21 | One/two-cell facade projection negotiated by window, room and building; bounded suite/border domains; actual export bounds | No silent clipping or widened site limits |
| R22 | Review -> component/render investigation -> focused tests -> new client -> full corpus/render review -> full regression | Concrete failures and fixes logged; no serious architectural flaw found |
| R23 | All 200 earlier tests unchanged plus 30 new cases; rotations, outside-host installers, rollback and independent branches | Self-authored implementation exercise, not independent audit |
| R24 | Box and ceiling host chains, deletion/regeneration, exact current cells, all record/index audits; earlier shared/property tests preserved | Operation history may retain old actors, current ownership does not |
| R25 | 64 original pairings rerun, 16 prior holdout pairings rerun, 12 new independent pairings; 16 unresampled stress inputs | New inputs became regression during development; no fresh external holdout claimed |
| R26 | Retained three lodge clients x seeds 0-7 plus new garden-house x seeds 0-7; original settlement seed/count tests pass | No settlement-layout expansion in this continuation |
| R27 | Actual block/schema/NBT, function, support, guard, planter, room access/light/headroom validation; deliberate damage/overflow cases | Discrete physical models and nonhabitable attic distinction remain explicit |
| R28 | Actual principal/contact/detail signatures separated; 25 exterior/interior/circulation images inspected with per-view notes | Below reference richness: regular facades, repeated roofs, heavy chimneys and simpler landscape |
| R29 | Unchanged default/seed/output CLI; current default pair, seed-1 spaced path, hash-seed replay, public inspection and native import guard pass | MCIO only at transport boundary; no downloads or new dependencies |
| R30 | Updated design/usage/API delta, full assessment, R01-R30 ledger, current output pair, manifests and preview index | Remaining limits stated above; earlier evidence and all failed attempts preserved |