# Hearth architecture, version 1.2.0

The initial design was written before the kernel or extensive scene geometry. The executable
foundation passed seven tests before the terrain/grass/tree/wall/window prototype, then furnished
rooms and buildings were added, followed by settlements and the finite corpus. The stage sequence and generic fixes
are recorded in [reports/development-findings.md](reports/development-findings.md). This document
describes the implemented design; [GENERATOR.md](GENERATOR.md) contains usage and the R01-R30 evidence ledger.

The second development phase tests expressive breadth through a separate `hearth_extensions`
package. Its pre-change [public API and module hashes](reports/extensions-baseline/public-api.md),
[failing probes and protocol delta](reports/extensions-baseline/api-delta.md), and
[retained development findings](reports/extension-corpus/development-findings.md) distinguish new
evidence from the completed first delivery. This is a self-authored extension exercise, not an
independent audit. The user's report of prior native/Pyodide agreement is preserved as external
context; no claim is made that this revision was executed in a browser.

## Module boundaries

| Layer | Modules | Responsibility |
|---|---|---|
| Values and geometry | `space`, `blocks`, `randomness` | Inclusive integer boxes, frames, Java blockstates, stable random scopes |
| Composition kernel | `kernel/contracts`, `scene`, `view`, `validation`, `errors` | Negotiation, permissions, transactions, instances, graphs, queries and rule scheduling |
| Environments | `environment/fields`, `terrain` | Composable field expressions, frozen sampled strata and water |
| Architectural knowledge | `components/*`, `adapters/site` | Windows, walls, furnishings, rooms, roofs, buildings, contact and access strategies |
| Public composition | `composition`, `programs` | Selection, encapsulation, arrangement, repetition, scattering, room graphs and settlement intent |
| Transport and assessment | `persistence`, `assessment`, `examples/*` | Verified Litematica export/reload, inspection, explicit batches |
| Independent extension | `extension_demo` | A different light and a composite reading suite with a forwarded entrance |
| Further geometry and architecture | `hearth_extensions/{geometry,circulation,boundaries,sites,halls,interiors,graphs}` | Ribbons, curves, polygon halls, functional interior allocation and access graphs through the same protocol |
| New lightweight clients | `hearth_extensions/programs`, `examples/extension_*` | Locked graph intent on independently frozen fields, assessment, replay and inspection |

The kernel imports no concrete architectural implementation and never imports the CLI. The CLI is
an ordinary client. A browser adapter could retain the kernel, field expressions, plans and JSON
records, replacing the Python host/transport. No browser runtime or UI is included.

## One protocol for leaves and composites

A component implements:

```python
capability() -> Capability
negotiate(context: Context, parameters: dict) -> Contract
realize(context: Context, contract: Contract) -> Plan
```

`Capability` separates feasible offers from a placed instance. It includes semantic tags, executable
`Domain` checks for constructor inputs and execution parameters, assumptions, adaptation strategies,
guarantees, implementation version and locked decisions. Nested constructor paths such as
`design.bay`, and `frame.turn`, have executable domains. Constructors carry explicit principal intent;
`parameters` contains only advertised runtime overrides. Unknown overrides fail. Recorded inputs
include public constructor fields, execution arguments and negotiated decisions.

`Contract` contains a conservative local envelope, ports, grants, rules, decisions, input regions and
whole-object status. It becomes a world-space contract through the instance frame. Occupied geometry
is derived from effects and indexed exactly; an envelope is never substituted for actual membership.
Rules express support, protected clearance, preservation, enclosure, lighting, furnishing and access.
Effect coordinates must stay within the negotiated envelope, and child envelopes within their
parent's envelope. Expansion requires another negotiation.

A `Port` has a kind, oriented frame, region, capacity, alignment, facts and an optional grant. Wall
ports expose thickness, sill and excluded frame margins. A `Binding` names a host and port, a verb,
and an optional further restriction in **world coordinates**. Installation requires compatible
orientation, anchor alignment, available capacity and a compatible grant. Windows negotiate their
reveal depth against the public port; parents can substitute shuttered and hooded implementations.

A `connect` binding now always consumes only connection capacity and records a dependency and typed
association. It acquires no mutation grant, including when that port separately offers resurfacing
authority. The unchanged-kernel probe failed because it previously demanded that unrelated mutation
permission even for a read-only endpoint consumer. A negative test proves the new connection cannot
write to the host. Installation, sharing and other mutation verbs retain their authority checks.

Composite ports may delegate to a named child port. The kernel resolves authority through the
chain, while callers bind to the composite. It verifies the realized child's frame, region and kind
against the negotiated public interface, including during later validation. Buildings forward their
street connection; settlements forward a public gateway through their path composition. The
independent reading suite forwards its room entrance. Parents do not name private approach children.

## Plans, candidates and transactions

`Plan` contains writes, children, bounded `Choice` operations and typed relationships. Component
code reads an environmental view and returns effects. It cannot receive the shared mutable store
through its context. The view copies contract/port records and exposes styles through a read-only
mapping. This is a trusted Python programming protocol, not an arbitrary-code security sandbox.

A placement forks the current state. The kernel:

1. Allocates a stable instance path and random scope; checks feasible domains.
2. Negotiates a contract and resolves binding authority.
3. Applies final per-coordinate effects under the executing component/operation identity.
4. Instantiates semantic children through the same protocol.
5. Checks tentative geometry, existing consumers and completed local obligations.
6. Commits the entire state or discards the entire candidate.

Multiple writes inside one candidate component are coalesced to their final operation. They do not
create false collisions with earlier versions of that component's own local plan. Foreign writes
still require authority. The kernel never uses a global priority or identical-state overwrite rule.
Failed transactions preserve geometry, nodes, ownership, ports, relationships, dependencies, history
and sibling random scopes.

`Choice` evaluates complete candidate child compositions in isolated forks. It first checks hard
conditions, then scores actual sitework cost and exposed support proportions. It selects by a scoped
seed among alternatives within an explicit quality tolerance. `adapted(...)` proposes stepped
perimeters and piers under the same locked principal design. Water/high relief constrain the feasible
strategy set. Candidate scores and all rejection diagnostics are recorded. A bounded search with
unvisited alternatives reports `SearchExhausted`; identical hard failures of every declared contact
alternative retain the specific failed constraint. This is not a proof about unimplemented techniques.

## Authority, phases and logical objects

A grant identifies an owner, region, allowed verbs, consumer tags, per-binding change limit and
whether whole-object replacement is allowed. Binding restrictions can narrow a grant. A high planting
preference never grants excavation rights. Soil grants local construction edits, planting consumes
substrate support, and grass explicitly grants whole-object replacement to trees. Existing support
and clearance rules survive unrelated edits. Pools cannot undermine a supported tree. Paired plants
and doors cannot be partially replaced through an ordinary binding.

Property adjustments retain the original semantic owner and require the same block type. Deletions
remove current ownership; erasure history is separate from current cells. Displaced cells are retained
compactly so branch removal/regeneration can restore surviving host content. Retired grass disappears
from current nodes, relationships and ownership, while the operation history can still explain its
replacement.

Explicit shared support records a participant, a capacity use, a support obligation and a typed
association. It does not transfer the primary owner. Shared writes require consumer rebinding;
identical states alone never authorize sharing.

Construction starts with a temporarily open scope. Invariants run throughout; completion rules run
when the scope closes. `complete=False` permits an explicitly unfinished scope, and `finish_scope`
closes it. Unfinished or stale content cannot be finalized or exported. Once a room is complete,
subsequent placements must preserve its access, lighting and enclosure. A building provides internal
circulation and an external landing. The settlement discharges its connection to public paths.

## Environmental observations and adaptation

`View` uses world coordinates and explicit known bounds. `Context.world/local` convert positions;
`Context.elevation/water/state` are local-frame convenience queries. Views expose actual 3D states,
owners, solid support, bounded elevation search, water, slope, substrate depth, clearance, protected
regions, obstacle distance, style roles, preferences and public interfaces. Unknown space raises an
error. A roof is not assumed to be the ground surface: path observations are bounded by the offered
access elevation.

Field expressions support constants, gradients, waves, radial masks, addition, multiplication,
blending, transforms and clamping. They can be nested and supplied by an independent compatible
implementation. Water intersects the sampled strata. Adaptation never inspects an environment class,
recipe label or particular seed. The 64-case assessment freezes sixteen complete 3D terrain scenes
before making four independently seeded building placements on copies of each.

Sitework measures support and water, preserves gravity alignment, and bounds relief, post height,
fill, excavation grants and approach length. Foundations produce support columns/perimeters to the
actual solid bed. The approach examines its full tread width and water surface. The principal room
graph, functions, footprint bays, locked horizontal placement and chosen roof intent remain intact.
No algorithm levels the whole site to guarantee success.

## Three distinct graphs and exact indexes

An instance ID is its stable parent/key path. The kernel automatically records creation type,
constructor inputs, resolved decisions, frame, implementation and random scope. Helper calls do not
create semantic ancestors. Windows, walls, floors, furniture, lights and adapters are actual instances.

* Structural containment and attachment form a graph. Attachment supplies the primary structural
  chain, while containment remains recorded. Bridges/path networks can relate to many structures.
* Data/constraint dependencies have a source, consumer, region, input version and reason. An automatic
  read trace coalesces actual spatial observations and records interface reads, supplementing declared
  regions and bindings. These are not false structural ancestors.
* Operations retain generating actor, operation key, write count, displaced identities and restorable
  old cells. These records do not make a displaced object a current owner.

The sparse coordinate map stores one current owner and operation per occupied cell. Reverse maps
provide exact cells by owner and shared participant. A structural adjacency index supports descendant
queries through attachment as well as containment: a window created by an external facade program
is still included when highlighting its host wall or building. Queries traverse this graph, never
scan the full voxel store or copy ancestor strings onto each cell.

Removing a branch updates all indexes. External attached/dependent consumers must be regenerated or
removed together; otherwise validation rejects the transaction. `regenerate(path, ..., dependents=...)`
restores displaced host output, removes obsolete nodes and replays affected branches from their
original inputs/scopes. It never repeatedly cuts the already modified terrain. Explicit co-regeneration
is intentional: there is no hidden oscillating terrain/building update loop.

Version 1.2 adds `replacements={path: component, ...}` to `regenerate`. Every replacement must be one
of the explicit, distinct replay targets (`path` followed by `dependents`). Targets replay in that
order under their original scopes, frames and bindings, within one transaction. This permits replaying
unchanged endpoint hosts before a changed connector, which the previous single-replacement API could
not express. It does not guess a dependency order, permit undeclared replacements, or clear stale
flags to force success. Reloaded targets can provide implementations through the same mapping.

## Extension data flow and architectural composition

The geometry layer adds finite polylines with arc projection, cubic sampling, cardinal rasterization
and width ribbons, plus integer polygon masks and perimeters. It stays independent of block storage.
The extension uses these operations because a curve needs coherent consecutive joins and a walkway
needs a connected discrete route. A general mesh package or environment-family registry is unnecessary.

`Link` resolves two public access interfaces, verifies outward frames and mouth widths, and samples
the frozen environment along a planned ribbon. Endpoint heights stay locked. Bounded upward profile
propagation clears measured ground/water, or reports an incompatible grade. Trestles reach two real
solid bed cells and obey depth, span and fill limits. Deck, guards and canopy are separate children;
scoped terrain grants authorize their edits while read-only host contacts preserve landing ownership.
Actual support, route, headroom and guard rules run on the tentative result. Span checks are an explicit
bounded load-path model, not structural mechanics. Covered connections are open galleries.

`Boundary` follows an open contour on measured terrain, builds continuous masonry and exposes framed
fixture sockets. `BoundaryChain` packages many bounded segments and forwards their sockets. An
external lighting composition installs lamps through those interfaces, so the actual boundary remains
their semantic host. Per-segment and cross-segment grade checks prevent disconnected joins.

`Pavilion` composes a polygon floor, foundation, shell, facade installations, independent approaches,
ceiling, lights, interior and hipped roof. Its shell exposes window/door regions; existing Hearth
implementations install through them. `HallInterior` allocates functional `WorkBay` components around
protected aisles and validates access to their interaction ports. The fitted count has a mandatory
minimum and an explicitly recorded optional shortfall. A cutaway exposed undersized inherited furniture
groupings, motivating this reusable interior planner without changing locked principal architecture.

`Campus` takes `Vertex` components with locked frames and explicit `Edge` connections. It verifies a
connected graph, then composes any compatible access provider; tests substitute a platform and polygon
hall without changing the parent. It does not inspect concrete types or private approach children.
One client forms a branching campus mixing new halls with the original stacked-room building. Another
forms a triangular circuit with broad halls and curved routes. Their fields are frozen independently
before placement. Principal geometry/topology signatures are separated from contact and furnishing
counts. Explicit graph placement is delivered; autonomous city packing is not.

## Persistence, coordinates and replay

Positions are `(x,y,z)`, Y up, north -Z. A positive quarter-turn maps `(x,y,z)` to `(-z,y,x)`.
Frames transform coordinates, boxes, rule cells, ports and directional block properties, including
cardinal connection keys, axes, rotation values and supported rail/orientation strings. Custom rule
`data` is uninterpreted; a validator needing directions uses its node frame.

Export bounds are derived from every realized occupied cell. MCIO indexing is converted explicitly
to `(y,z,x)`. Export-local coordinates equal world coordinates minus the companion's `offset`.
The original world frame is restored on reload, including negative coordinates.

`persistence` writes one Java 1.21.1 region (data version 3955) and a versioned structural JSON record.
It retains capabilities/contracts, nodes, frames, random scopes, styles, field inputs, dependency and
structure graphs, current ownership, operation/displacement records, and relevant inventory NBT.
The geometry digest canonicalizes parsed names and **explicit** property mappings and includes world
coordinates and block-entity data. It ignores property order only, not missing/defaulted properties.
Reload reads actual schematic blocks and NBT, verifies dimensions/digest/ownership and reruns the
validators. Missing/unknown metadata or mismatched geometry is rejected as untrusted.

The companion format remains version 1. Import `hearth_extensions` before loading its artifacts to
register the extension guard/span validators; unknown handlers fail rather than silently skipping
validation. The new manifest audit regenerates every selected recipe and compares all structural
nodes, relations, dependencies, operations, port uses, displacement records, inventories and exact
membership with the loaded artifact. It also queries a current cell from every nonempty component.

The companion is not a cryptographic signature, and arbitrary geometry cannot reconstruct a graph.
Reload does not execute serialized Python. To regenerate a reloaded branch, explicitly supply its
component implementation; inputs and source programs/manifests support replay. Arbitrary entity types
and a general block-entity migration system are not implemented; these artifacts export no entities.

## Validation model and limits

Validators register through `@validator(name)`; component authors use existing rules or add a named
handler without editing dispatch. Missing handlers are errors, including after reload. The physical
model uses integer standing positions, two air/passable cells, cardinal moves and elevation changes
of at most one block with extra clearance for ascending/descending. Wood doors are considered
operable. Stairs are checked as usable flights and declared clearance volumes. This is not a full
Minecraft collision/fluid/redstone simulator.

Lighting propagates actual source levels through passable/transparent cells with unit attenuation;
closed opaque boundaries block propagation. It checks required room locations, not a claim that all
possible mob-spawning cells are spawn-proof. Enclosure checks actual room floors/ceilings and wall
surfaces. Roof abutments are bounded voxel joins above sealed ceilings; universal flashing or
structural mechanics are not proved. Support checks declared load paths, substrate and support grids,
not an engineering stress solver for arbitrary blocks or decorative cantilevers.

Default limits are 512 blocks per axis, 1,000,000 occupied blocks, depth 40, 10,000 instances and 24
search alternatives, with at most 16,000,000 cells in the dense export bounding box. Demo count limits live in the CLI, not the kernel. Costs, bounds and failure
conditions are public. Existing tests and finite observations establish only the documented scope.