# Task: Contract-Based Procedural Composition, Adaptation, and Structural Provenance Build an extensible Python generation and validation library for Minecraft Java 1.21.1. First build its executable architecture, then use its public interfaces to generate complete, attractive, logically sound content. A higher-level program must be able to discover what a lower-level component offers, decide whether and how to use it, and compose it without reading its private implementation. Components may vary their realization with seed and surroundings while fulfilling their negotiated contracts. A composition must itself be a reusable component. Deliver working generation from small objects through rooms and buildings to a coherent settlement of 3-6 buildings. The kernel must support further growth toward cities and other complex content without treating this demonstration scale as a fundamental architectural limit. Users write short, high-level programs and explicitly control the seed. Running `python generate.py` must produce the complete default settlement as one region in `output.litematic`. The requirements below fix semantics and observable behavior, not Python class names, signatures, storage encodings, or a particular solver. Choose those details deliberately and document them. Requirement identifiers are used for the evidence ledger requested under Deliverables. ## 1. Priorities and reference policy **R01 - Architecture first, with real implementations.** Establish clear module boundaries, public protocols, component lifecycles, transactions, provenance, and tests before expanding into extensive building geometry. Deliver an executable foundation, not empty interfaces or a framework proposal. Then complete the generated results. Do not optimize library line count, file count, or implementation length. Write as much well-factored shared code as the result requires. Keep clients lightweight without code-golf, opaque configuration dumps, or long hidden building-specific example helpers. **R02 - References are aesthetic outcomes only.** Two source snapshot sets and their original reference images are supplied under `references/exp8/`, `references/lodge/`, and task-root image files. `references/README.md` indexes all 16 examples and records their provenance and hashes. The supplied reference programs and images are aesthetic examples of building outcomes only. They are not architectural or implementation templates for your library. You are not required to study or reuse their code, follow their algorithms, reproduce them one-to-one, read every source file, or cover an enumerated list of building families. Design the framework independently. You may run or render a reference solely to inspect its resulting architecture. Keep the supplied snapshots unchanged. The images are original reference images, not a claim that each historical program reproduced them exactly or passed the new requirements. New styles are welcome. **R03 - Maximize meaningful, valid variety.** Broaden the space of possible component compositions and compatible parameter combinations. Prioritize component counts, connection topology, massing, footprints, wings, storeys, room functions and adjacency, roof systems, entrances, circulation, attachments, and site organization. Materials, planting, weathering, and decoration also contribute, but rank below structural variation. Randomness must affect a client's structure and composition, not only surface texture. The public API supports explicit decisions and bounded seeded choices. Do not introduce a whole-building family selector, reference-name dispatch, or a collection of fixed buildings disguised by a short API. New compositions must be expressible through existing public capabilities. Finite implementations of useful primitives and engineering strategies are appropriate when they can compose and be extended through contracts. Make parameter domains and dependencies explicit. Do not silently discard explicit intent. Arbitrarily unbounded dimensions, extra seeds, new names, file hashes, global rotations, or translations alone are not meaningful additional types. Retain believable scale, proportions, correctness, and aesthetics. Do not calculate, estimate, enumerate, or report the total number of possible combinations. Report observed finite-sample diversity only. ## 2. Kernel and recursive public contracts **R04 - Separate responsibilities.** Keep a general composition kernel, environment/geometry services, component and rule implementations, and high-level user programs distinct. The kernel must not import concrete building implementations. Components use public kernel protocols; ordinary clients use public composition APIs. Separate generation from CLI handling, rendering, filesystem export, and harness execution. Keep generation usable as an importable library and straightforward to adapt to a future browser runtime. A Houdini installation is not required. The kernel handles component instances, contract negotiation, spatial transforms, attachment, permissions, transactions, dependencies, random scopes, provenance, and validation orchestration. Environment/geometry services expose fields, spatial queries, geometry operations, block states, storage, and transport. Concrete components and rules contain architectural knowledge. High-level programs describe intent, select capabilities, arrange relationships, and package new components. **R05 - Executable component contracts.** A component must expose enough information for another component or planner to use it without inspecting private fields or switching on its implementation type. Its contract must describe, as applicable: | Concern | Required semantics | | --- | --- | | Inputs and assumptions | Accepted dimensions, orientations, support and environmental conditions, style constraints, variable parameters, and locked decisions | | Spatial claims | Actual occupied geometry, conservative possible extent, affected region, support regions, and space that must remain clear | | Connection interfaces | Points, surfaces, or regions with local frames, directions, dimensions, capacity, and alignment conditions | | Environmental access | Public fields, nearby geometry, and constraints the component can query | | Modification authority | What may be replaced or excavated, where, under which conditions, and with what limits | | Adaptation capabilities | Parts that may change and connection strategies that may fulfill the interface | | Guarantees and obligations | Connectivity, sealing, support, lighting, and requirements that an enclosing composition must satisfy | | Validation and diagnostics | Checks over actual results, with failing rule, component path, position, and conflicting conditions | An interface is not necessarily a single coordinate. A wall can expose an installation region with sill heights, framing exclusions, margins, and bay alignment. Terrain can expose an irregular plantable surface. Separate a component's feasible capability/domain description from the concrete or conservative instance contract negotiated for one realization. A larger canopy or wider footing requires renegotiation if it exceeds the accepted envelope; realization cannot silently exceed it. **R06 - Recursive composition and substitution.** Leaves and composites must implement the same usable protocol. A room may internally compose walls, windows, doors, furniture, and lights, while exposing purpose, entrances, envelope, and internal reachability. A building may expose footprint, height envelope, access ports, attachment opportunities, environmental assumptions, and guarantees. The framework retains internal composition and validation evidence for recursive inspection; parents work through public interfaces. Contract-compatible implementations must be substitutable without changing their parent program. Provide high-level operations sufficient to select, attach, arrange, repeat, scatter, constrain, and encapsulate components. A high-level program can generate different composition graphs, not merely resize an immutable graph. Shared rules can coordinate multiple children: a facade planner can establish bay alignment and sill levels while independent window implementations vary within those rules. A room planner allocates functions and circulation while furniture components realize them. Avoid absolute voxel loops, blockstate edits, NBT handling, and geometry repair in ordinary clients. Adding a component or validator must integrate through extension points, not core dispatch edits or duplicated validation code. ## 3. Spatial authority and atomic composition **R07 - Conditional replacement and preservation.** Check where an operation writes, who currently owns or shares the affected content, which permissions its binding grants, and whether other live components still satisfy their assumptions afterward. A universal numeric priority or last-write-wins rule is insufficient. Required examples: | Operation | Expected behavior | | --- | --- | | A pool replaces ground | Allowed within an authorized excavation region, producing a valid basin, boundary, and updated surface | | A tree is planted on ground | Uses a planting interface and depends on substrate support; an ordinary tree cannot excavate the terrain | | A tree replaces grass | Allowed when the grass exposes permission for that planting replacement | | Grass attempts to replace a tree | Reject that candidate; a scatter operation may try another legal location | | A pool excavates beneath an existing tree | Reject because it destroys an active support requirement, even if the soil itself is editable | | A window is installed in a wall | Permit the scoped replacement while preserving agreed support, sealing, margins, and alignment | | Decoration enters stair headroom | Reject because the clearance obligation remains protected | Permissions can refine or consume a host capability: terrain need not promise that every original soil cell survives an authorized pool excavation, but existing consumers of that soil must remain valid. Identical block states do not by themselves authorize shared occupancy. Shared supports, ownership, and write authority need explicit semantics. Replacement must maintain whole logical objects and their records; do not leave half a door, half a tall plant, dangling ports, or stale claims. **R08 - Functional boundaries and atomic transactions.** Components receive explicit inputs, read-only environmental access, and scoped randomness, and return plans or effect sets. Efficient mutable internals are acceptable, but components cannot bypass the kernel to mutate shared scene state. Every committed geometry write must have a kernel-bound component context. Negotiate a binding, generate a candidate, inspect its tentative resulting geometry and affected contracts, then commit all effects together. Failed attempts must leave geometry, ports, claims, ownership, dependencies, and other random branches unchanged. Initial implementations may recheck all relevant contracts rather than implementing a complex incremental validator. **R09 - Construction phases and obligations.** Distinguish invariants that must hold throughout composition from obligations that must be discharged when the current scope is finalized. A room can acquire walls before lights; a completed room must have lighting and an accessible exit. A building supplies internal reachability; a settlement connects its entrance to a public path. Unfinished scopes can continue local construction but cannot be returned or exported as completed valid components. Each room needs access and lighting; it does not need its own private staircase. Vertical circulation is required where the composed levels require it. ## 4. Automatic block-to-structure provenance **R10 - Record semantic structure in the kernel.** At instantiation, automatically assign stable component instance IDs and record type, resolved parameters, and random scope. At composition and attachment, automatically record semantic relationships. At geometry submission, automatically associate blocks with their current semantic component and generating operation. Component authors declare component types and interfaces normally; high-level clients must not supply per-block owner maps, handwritten ancestor chains, or a post-generation tagging pass. Semantic objects such as windows and walls must actually be generated as components. Querying a window's glass must recover relationships such as: ```text glass block -> window instance -> host wall -> house -> plot or settlement ``` This comes from real composition and binding, not source-code stack traces, material names, or post-hoc geometry classification. A window installed by a higher-level facade program must still identify its host wall through the attachment interface. Helper functions must not become fake semantic ancestors merely because they were called during generation. **R11 - Distinguish meaning, dependencies, and history.** Represent current structural membership and typed associations separately from data/constraint dependencies and generation/modification records. A window replacing wall infill owns its glass while remaining attached to the wall. A later property adjustment preserves that semantic membership even if another operation performs the write. Tree-over-grass replacement changes current ownership; displaced grass must not appear as a current owner. Preserve useful compact operation records for explanation and replay. Shared walls, bridges, and platforms joining multiple buildings can relate to multiple structures. Expose a useful primary structural chain plus typed related structures without forcing every relationship into a single-parent tree. Record containment, attachment, connection, and support according to their actual meaning. **R12 - Queryable, synchronized provenance.** Provide public APIs and a runnable headless example to inspect a block by coordinate and return its state, instance ID, structural chain, typed related structures, and generating information. Also query the actual current cells of a component, with optional descendants, for future highlighting. A bounding box alone is not an exact membership map. Document coordinate spaces and conversion through export offsets, translations, and supported rotations. This experiment requires the underlying query functionality, not a clickable viewer. Maintain coordinate and appropriate reverse indexes. Share the structure graph rather than storing a complete ancestor string on every voxel or scanning the whole scene on each query. Keep provenance transactionally consistent with replacement, deletion, rollback, and regeneration. Removing a block removes its current block ownership; clearance reservations remain separate. Recomputed branches must not leave stale cells, structure nodes, or associations. **R13 - Persist and verify structural identity.** Export sufficient companion data with the schematic to restore the same public queries, contracts, and validation context after reload. Include format version, coordinate transforms, and a semantic geometry identity/digest to check the pairing. A mismatched record must not be treated as trustworthy structure metadata. Equivalent blockstate property ordering must not create a mismatch. Handle unknown or missing structural data explicitly. Do not claim that arbitrary schematic geometry alone recovers the original semantic component graph. ## 5. General procedural environments **R14 - Compose environments from general operations.** Use Houdini-inspired data flow, attributes, fields, masks, scattering, connections, and encapsulated subnetworks in Python. Environments should come from composable parameterized operations such as field layering and transforms, mask blending, local shape operations, material distribution, water volumes, and constrained scattering. Operations can nest, repeat, and be packaged into new components. Use appropriate procedural-generation data structures throughout the library. You may combine splines/parametric curves and polylines, graphs and trees, polygons and meshes, point clouds with attributes, heightfields, scalar/vector fields, signed distance fields (SDFs), sparse voxel grids, and spatial indexes. For example, curves can guide paths, rivers, branches, or swept profiles; graphs can express circulation and structural relationships; fields can guide density and blending. These are optional tools, not a required checklist or a closed vocabulary. Choose representations that make each operation clear and extensible; intermediate design geometry need not be limited to boxes or Minecraft voxels. When converting representations into blocks, preserve component identity, coordinate transforms, and contract meaning, and validate the realized voxel geometry. Do not define a fixed list of environment classes or a `terrain_type` selector that dispatches to handwritten whole-scene cases. Flat terrain, gradients, shorelines, and other recognizable conditions must emerge as special cases of general parameters and compositions. For example, zero perturbation can yield flat ground, a field gradient can yield a slope, and an intersection of terrain with water can yield a shoreline. These are explanatory examples, not a required classification or a finite coverage checklist. One environment may contain many interacting conditions simultaneously. Adaptation must not inspect environment implementation types, source recipe names, reference names, or particular seeds to choose special-case behavior. Branching on measured geometry or contract facts is appropriate: support depth, water presence, available clearance, or local height difference can justify different engineering strategies. A finite set of useful primitive algorithms is fine; it must support new combinations and implementations through the public contracts. **R15 - Public environmental queries and control.** Expose relevant elevation, slope, materials, water levels, actual support, obstacle distance, occupancy, protected regions, access opportunities, and shared style information. Initial terrain generation may use heightfields, but the public environment interface must also support actual three-dimensional solid/support/clearance queries. A surface height alone does not prove that the material below can support a footing. Queries have explicit coordinate frames, valid domains, and input versions or dependency identities. Unknown space is not silently treated as flat terrain or empty air. Distinguish hard constraints (protected regions, locked placement, headroom, edit limits) from preference fields (planting density, buildability preference, access proximity, landscape preservation). Masks can control an operation's extent and strength; a high preference or mask value does not grant write authority. ## 6. Context-sensitive realization and connection adapters **R16 - Reusable adapters.** Treat connection adapters as ordinary components with contracts, provenance, and validators. Capabilities can include stepped foundations, retaining work, footings, posts to the actual bed beneath water, window reveals for varying wall thickness, entrance platforms and stairs, and sealed roof junctions. These are examples of reusable engineering, not an exhaustive adapter registry hardcoded into the kernel. New techniques must be addable through public interfaces. **R17 - Adapt at placement time.** For a workflow that generates terrain before placing a building: 1. Query the candidate location and neighborhood for support, elevation differences, water, obstacles, access, and protected regions. 2. Establish explicit user decisions and the remaining permitted variation. 3. Negotiate the binding and propose suitable contact geometry, adapters, and any permitted terrain edits. 4. Check the resulting combined scene, including affected existing components, in a tentative transaction. 5. Compare feasible candidates and atomically commit the chosen complete result. By default allow local excavation/fill, plinths, posts, retaining walls, and approach changes within explicit bounds. Preserve the terrain's major shape, the building's principal design, and locked requirements. Keep buildings sensibly aligned to gravity rather than tilting them wholesale with a slope. Explicitly bound and expose edit extent, excavation/fill volume, support height, and access detours. Do not make everything succeed by leveling the entire site, adding enormous solid pedestals, or extending arbitrarily tall posts. Regenerate contact geometry from the environment, rather than only translating a rigid finished building vertically. Adaptation should generalize across scales: a window can fit wall thickness within its contract, an approach can respond to height differences, and permitted branch/canopy variation can preserve nearby clearance. Shared facade grids, material roles, proportion rules, and layout constraints keep independently varying children coherent. **R18 - Quality-aware bounded planning.** First satisfy hard conditions: authority, support, reachability, sealing, spatial bounds, and explicit architectural intent. Then evaluate permissible alternatives for terrain disturbance, support proportions, boundary transitions, entrance/path quality, alignment, palette coherence, and landscape relationships. Use seeded selection among acceptable alternatives to retain diversity rather than always converging on one fixed form. Prefer constraint propagation and feasible-domain construction to blindly rejecting random complete builds. Bounded local search or backtracking is allowed; replan the smallest affected composition where practical. Distinguish proven/established incompatibility from search-budget exhaustion and validated success. Never claim a failed bounded search proves no solution exists. Do not silently drop required components, move locked placements, relax hard constraints, or recover to the same fixed building across most seeds. Optional omissions must respect declared minimum counts and be reported, not used to disguise failures. Return useful failed constraints and component locations. ## 7. Dependencies, deterministic regeneration, and bounds **R19 - Re-evaluate actual dependencies.** Composition structure defines encapsulation and responsibility. A separate data/constraint dependency graph identifies which changes require regeneration or revalidation. Terrain changes must invalidate affected foundations, approaches, and paths. Initial implementations may recompute whole affected nodes; sophisticated caching is not required. Recompute from inputs and recorded operations, replacing obsolete output rather than accumulating repeated cuts or fills. Keep current provenance and spatial indexes synchronized. Coupled building/terrain adjustments belong inside an explicit bounded solve that jointly produces the building and terrain edits. Do not create hidden, endlessly oscillating update loops. Record the environmental inputs on which a component's validity depends. An invalidated old result must not remain presented as a valid completed component. **R20 - Hierarchical deterministic randomness.** Derive stable child random scopes from the user's root seed and stable instance/operation keys. Separate planning, geometry, adaptation, and decoration. Users can override a subtree seed. Keys must not depend on traversal order or Python's process-random `hash()`. Sort unordered candidates with deterministic tie-breakers. Failed retries must not consume other branches' randomness. Scope attempted alternatives deterministically. With unchanged interfaces and no changed spatial/global constraint dependencies, adding a planter must not alter an unrelated building's layout. Changes that really affect dependencies can require replanning, and their cause must be inspectable. Independent operations can commute; dependent replacement and attachment operations obey their contracts. Do not falsely promise order independence for tree/grass replacement. Document the seed domain and retain inputs, resolved decisions, component structure, environmental versions, seeds, and implementation versions for replay. The same inputs and seed must reproduce semantic schematic content in the same environment: dimensions, coordinates, actual block states, entities, and block-entity data. Timestamps, compression, palette numbering and property ordering may differ; byte-identical files are not required. Use scoped streams for this task; all stochastic choices must still derive from explicit seeds, never ambient global randomness. **R21 - Resource and coordinate bounds.** Expose configurable limits for dimensions, recursion, search effort, and generation cost. Derive final export bounds from the realized composition, including terrain, roofs, adapters, vegetation, and external connections. Never silently clip. Library boundaries must not bake in the demonstration's building count or an environment category. ## 8. Architecture-first work sequence **R22 - Implement and verify in this order.** 1. Write `ARCHITECTURE.md` in your workspace before extensive scene geometry. Explain module dependencies, public protocols, lifecycle, contracts, effects/transactions, automatic provenance, environment queries, seeds, persistence, and extension mechanisms. Include short intended client compositions that make the proposed abstractions concrete. 2. Implement the working kernel. Pass tests for composition, binding, conditional replacement, rollback, automatic ownership, transforms, queries, and persistence before expanding the content. 3. Build a small end-to-end composition using terrain, grass, trees, walls, and windows. Exercise recursive composition, real attachment, provenance, and adaptation. Repair inadequate abstractions. 4. Build complete furnished buildings, roofs, circulation, lights, and connection adapters using the same public protocols. Demonstrate substitution and an independent extension. 5. Compose settlements, broaden high-level programs, run multi-seed validation, inspect renders, and fix generic defects exposed by the corpus. Proceed autonomously through these stages; do not stop for approval at each stage. Architecture can evolve when evidence calls for it, but rerun foundational tests after changing its semantics. Update the design rationale. Do not satisfy this sequence by writing placeholder interfaces and then routing all real work through a monolithic mutable compiler or a building-specific bypass. Large coherent implementation is acceptable; incomplete promises of future extensibility are not the deliverable. ## 9. Validation and finite evidence **R23 - Contract and extensibility tests.** Provide meaningful `test/test_*.py` tests for: - At least two visibly different implementations satisfying the same contract, substituted with no parent-program change; a composite remains usable at a higher level through the same protocol. - An independent extension package adding one low-level and one composite component without editing the kernel; ordinary clients need no geometry repairs or copied validators. - All conditional replacement examples above, including existing-consumer support preservation, whole-object consistency, rejected candidates, shared occupancy rules, and complete rollback. - Translation and horizontal rotations transforming states, interfaces, claims, and provenance together. - Determinism, stable independent branches, and failed attempts not perturbing sibling random streams. **R24 - Provenance tests.** Query window glass and recover its real window/wall/building relationships. Two windows using identical glass must have distinct instance identities. High-level examples must not contain per-voxel ownership tables or handwritten ancestry. Test replacement, deletion, property updates, rollback, shared walls/connections, exact current-cell queries, and branch regeneration. No obsolete node or voxel reference may survive as current structure. Test export/reload and coordinate changes, as well as detecting mismatched geometry and companion records. **R25 - General environmental adaptation tests.** Generate test environments with the same general operations, not a hand-authored list of terrain cases. Organize tests around independent environment and building seeds, parameter boundaries and degenerate values, rule interactions, previously unused operation compositions, local perturbations, and contract-compatible environment implementations. Derive special inputs such as flat ground from the general generator's parameters. Persist failures as generating expressions, parameters, and seeds; fix general rules, not seed-specific exceptions. Retain at least 64 reproducible environment/building pairings as a finite adaptation test budget. This count does not enumerate environment classes or define capability boundaries. Define the sampling recipe and supported parameter domains before evaluating results. Generate and freeze environmental inputs independently before placing buildings; do not secretly shape terrain to suit one house. Include untried combinations when assessing generalization, rather than only development examples. For explicitly satisfiable test specifications within documented domains, require valid results: contact geometry actually responds to surroundings, locked principal layout/functions remain intact, protected objects and terrain outside authorized modifications are unchanged, and there are no floating joins, buried doors, disconnected approaches, or invalid supports. Exercise multiple compatible adaptation strategies without reducing every case to a flat platform. Also run bounded stress sampling. Keep and report all successes, incompatibilities, retries, and budget-exhausted cases. Separate per-input success rate from per-candidate acceptance rate. Report edit costs and runtime, with denominators and sampling policy, rather than hiding hard inputs by resampling until only successes remain. A finite corpus is not a proof about every possible composition. **R26 - Whole-building and settlement corpus.** Supply at least three distinct lightweight building composition programs, each exercised at seeds 0-7. Exercise a settlement program at seeds 0-7 and test both 3-building and 6-building count boundaries. Programs use the same shared API and exhibit actual structural choices; they are not named reference dispatchers. Include new high-level compositions written after the abstractions exist, without changing the library for each new client. **R27 - Actual-geometry validators and negative tests.** Check generated and reloaded blocks, not only declared plans or claims. Validate Java 1.21.1 blockstates, bounds, support, multi-block consistency, doors/windows, room reachability, at least two blocks of player headroom on required routes including stairs, usable vertical connections, actual lights, appropriate furnishing, enclosed-space integrity, pool containment, exterior approaches, and settlement path connections. Late decoration must preserve earlier guarantees. Distinguish intended open spaces from enclosed spaces in the contracts. Deliberately remove supports, block stairs or exits, break paired door parts, remove room light sources, and exceed edit permissions. Validators must detect the resulting defects and identify the rule, component, and location. Support assumptions and the movement/lighting model must be explicit; a metadata declaration is not evidence of physical reachability or a placed light. Use the proc toolset's `blockstates_equivalent` semantics for round trips. Compare parsed block names and explicit property mappings, ignoring property order only. Changed names, values, missing properties, and extra properties still fail; do not infer defaults during equivalence checking. MCIO can reorder properties even after a single write. Repeated writes to a coordinate can be valid when the contract permits them and the final state is correct. Retain checks for relevant block-entity NBT and inventories. You may copy the independent comparison helper into your library or implement equivalent semantics; do not couple library validation to the CLI entry point. **R28 - Diversity and visual quality.** Measure observed differences in actual massing, component connections, room topology, roofs, and settlement organization, both within a client's seeds and between compositions. Exclude cosmetic noise, instance names, and global transforms from structural signatures. Report contact/foundation adaptation separately so it cannot substitute for diversity in principal architecture. Preserve harmonious material roles, useful proportions, complete hidden sides and interiors, meaningful furnished spaces, coherent roof joins, clear access, and composed landscapes. Keep all corpus results and failures. Render representative structural and adaptation variations from multiple exterior angles and with cutaways for circulation and furnishing. Inspect the images and fix visible problems. Do not present only favorable seeds while leaving known reproducible defects unreported. Rules and tests constrain quality; renders support aesthetic assessment. Neither formal contracts nor passing sampled tests constitute a proof of beauty or exhaustive validity. Keep tests bounded and rerunnable. Temporary test files belong in temporary directories under `test/` and must be cleaned up. Persistent samples, rendered previews, and corpus reports are explicit batch outputs, not unnoticed side effects of unit tests. ## 10. Harness contract and deliverables **R29 - Public generation, inspection, and export.** Work inside `/work/generator/workspace`. `python generate.py` is a thin public-API client and must generate, validate, and export the complete default 3-6 building settlement as one region in `output.litematic`. Support `python generate.py --seed INTEGER --output PATH` and document the default seed. Every example and batch command supports explicit seeds. Use the proc toolset and create your own entry point and library; no generator template is seeded. Preserve valid export and semantic reload checks while keeping substantial shared implementation in the library. The harness independently runs the default command, two seed-0 replays with different PYTHONHASHSEED values, seed 1, and your pytest suite in isolated offline workspace copies. Each command has a 1800-second limit. This checks the program interface and replay, not all R01-R30 requirements. The finished package must work without invoking reference programs, depending on the harness CLI, or downloading additional assets. Keep public generation and inspection callable without file export. Include an example that selects a coordinate from a generated artifact, prints the real structural chain and typed related structures, retrieves its component's cells, exports, reloads, and demonstrates the same query. A clickable viewer, node-editor UI, HTML report, or full city generator is outside this experiment; provide the foundation those later tools can use. **R30 - Complete artifacts and evidence ledger.** Deliver: - An importable shared library: kernel, environmental operations, components, adapters, validators, automatic structural provenance, public inspection, deterministic generation, and persistence. - `ARCHITECTURE.md`: the actual design, public protocol, dependencies, lifecycle, and rationale, updated as implementation evolves. - `GENERATOR.md`: quickstart, short client compositions, seed behavior, domains/dependencies, adaptation policy, resource limits, inspection and export/reload usage, extension instructions, diagnostics, batch/test/render commands, and known limitations. - `generate.py`, lightweight runnable examples, and an independent extension demonstration. - `output.litematic` with its verified structural/validation companion data. - `test/test_*.py`, representative samples with a replay manifest, labeled previews/cutaways, and rerunnable finite-corpus/assessment commands. - An evidence ledger in the documentation mapping **every R01-R30 requirement** to the responsible public API or module, tests/examples/render evidence, and any incomplete part. Use actual results; do not mark an unimplemented interface or an unrun test as complete. Preserve all requirements when refining the implementation. Document tradeoffs and limitations rather than silently shrinking the task. Spend effort on the reusable architecture and its verified generated results. State plainly in your final message what is complete and what remains unfinished. Environment details, available libraries, rendering tools, and repository conventions are in the workspace `AGENTS.md`.

# Generate, validate and export the default complete Hearth settlement. import argparse from pathlib import Path from hearth.programs import settlement_scene from hearth.persistence import export_scene, semantic_digest def main(): parser = argparse.ArgumentParser(description='Generate a contract-composed Minecraft Java 1.21.1 settlement.') parser.add_argument('--seed', type=int, default=0, help='Explicit integer seed, default 0') parser.add_argument('--output', type=Path, default=Path('output.litematic')) parser.add_argument('--count', type=int, choices=range(3, 7), help='Optional explicit building count, 3 through 6') args = parser.parse_args() scene = settlement_scene(args.seed, args.count) export_scene(scene, args.output) print(f'Validated {sum(n.type=="building.rooms" for n in scene.nodes.values())} buildings, {len(scene.blocks)} blocks, {len(scene.nodes)} components.') print(f'{args.output} | semantic SHA256 {semantic_digest(scene)}') if __name__ == '__main__': main()

{ "samples": [ { "label": "building-0", "seed": "0", "digest": "be299dbd2fc591d6a38a8e6c7378aad3d765cb546de5f6df7c44773325c89dc3", "signature": "ab4f66e2ee4de325134b4a767a1faf1e39b11567c9147953780aceb2059aec00", "blocks": 15288, "components": 72, "rooms": 3, "python_s": 2.7494000000000005, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "building-replay", "seed": "0", "digest": "be299dbd2fc591d6a38a8e6c7378aad3d765cb546de5f6df7c44773325c89dc3", "signature": "ab4f66e2ee4de325134b4a767a1faf1e39b11567c9147953780aceb2059aec00", "blocks": 15288, "components": 72, "rooms": 3, "python_s": 2.603600000000001, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "building-bay13", "seed": "0", "digest": "52e06a1887c2e7ba3d083daf5a2d5706d6ff502f677546f9dc1b4f00102db9c2", "signature": "a42e34bd7bbbd09bec16c5e64dd5c21360cc31e99626ee741d30f05835a5bf6b", "blocks": 17970, "components": 72, "rooms": 3, "python_s": 3.2569, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "building-1", "seed": "1", "digest": "52e06a1887c2e7ba3d083daf5a2d5706d6ff502f677546f9dc1b4f00102db9c2", "signature": "a42e34bd7bbbd09bec16c5e64dd5c21360cc31e99626ee741d30f05835a5bf6b", "blocks": 17970, "components": 72, "rooms": 3, "python_s": 3.2006000000000014, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "terrain-wet", "seed": "0", "digest": "4a270f9f4ef771dcf6e6631da57349bdb6b6f3462e56f0fa2706fb7b2bf59c5c", "signature": "7676b0a0ab7b441021fd8a6f7034b32d0602402e654f33bc1be65f62fb413691", "blocks": 35463, "components": 50, "rooms": 2, "python_s": 3.722900001000003, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "settlement-0", "seed": "0", "digest": "e81b08063278b231b60eaa16e4120973ed688bb3fd7e6a8da439daa4e7f5caf9", "signature": "a5e69d2105108e2af50f7c163efd47a3e398765881fed1bd11ac7f95d20cacd6", "blocks": 125475, "components": 782, "rooms": 15, "python_s": 26.394799999999996, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "explore-17", "seed": "17", "digest": "8d7f4d7fe9906f79e944149b9254f067b8833ca4241d470cfa0ea97fca561fb4", "signature": "f8dc52aa4f4abdf8e57ae8ef6cfaec1c74092b92d2b55724876eea185cbab368", "blocks": 11308, "components": 47, "rooms": 2, "python_s": 1.6206000000000031, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "explore-18", "seed": "18", "digest": "ca008a4f80bb95aef18e2317f30e504468dd77dc8cccc9e5838a03b04f3d3c80", "signature": "abacaaee7de9f87371d9e2417ebca16e8595a99fd732895dcfacab5f2bcc0f75", "blocks": 8776, "components": 27, "rooms": 1, "python_s": 1.0853000000000037, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "large-seed", "seed": "9223372036854775807", "digest": "be299dbd2fc591d6a38a8e6c7378aad3d765cb546de5f6df7c44773325c89dc3", "signature": "ab4f66e2ee4de325134b4a767a1faf1e39b11567c9147953780aceb2059aec00", "blocks": 15288, "components": 72, "rooms": 3, "python_s": 2.5991999989999997, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "custom-python", "seed": "23", "digest": "62377e6641e1356897eb7fb39780222d0b410a32dbb067f8018d6c732167c0c5", "signature": "8ae5e9094521005be3dae105b1f232a36a7738fe6424437fb37948d166b3627e", "blocks": 8756, "components": 27, "rooms": 1, "python_s": 1.1036999999999964, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } }, { "label": "after-cancel", "seed": "0", "digest": "be299dbd2fc591d6a38a8e6c7378aad3d765cb546de5f6df7c44773325c89dc3", "signature": "ab4f66e2ee4de325134b4a767a1faf1e39b11567c9147953780aceb2059aec00", "blocks": 15288, "components": 72, "rooms": 3, "python_s": 2.6779000010000003, "runtime": { "python": "3.12.7", "numpy": "2.0.2", "platform": "Emscripten" } } ], "checks": { "seed_replay": true, "real_glass_ancestry": true, "ancestor_membership": true, "parameter_changes_structure": true, "wet_adaptation": true, "original_default": true, "exploration_changes_structure": true, "exact_integer_seed": true, "edited_python_executed": true, "cutaway_preserves_content": true, "mobile_no_horizontal_overflow": true, "invalid_seed_rejected": true, "error_visible": true, "stale_export_disabled": true, "cancel_stops_worker": true, "recovery_after_cancel": true, "mermaid_rendered": true, "charts_rendered": true, "pointer_queries_real_block": true, "explore_button_runs_sampler": true, "seed_button_preserves_client": true, "incompatible_environment_rejected": true }, "page_errors": [], "reviewed_at": "2026-09-26T21:30:16.601Z" }

{ "samples": [ { "label": "building-0", "checks": { "digest": true, "signature": true, "sample_query": true, "download_digest": true, "download_all_nodes": true, "download_query": true }, "native_seconds": 1.303840467997361, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "building-replay", "checks": { "digest": true, "signature": true, "sample_query": true }, "native_seconds": 1.2410594370012404, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "building-bay13", "checks": { "digest": true, "signature": true, "sample_query": true, "download_digest": true, "download_all_nodes": true, "download_query": true }, "native_seconds": 1.5772299230011413, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "building-1", "checks": { "digest": true, "signature": true, "sample_query": true }, "native_seconds": 1.575140447996091, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "terrain-wet", "checks": { "digest": true, "signature": true, "sample_query": true, "download_digest": true, "download_all_nodes": true, "download_query": true }, "native_seconds": 1.8810117620014353, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "settlement-0", "checks": { "digest": true, "signature": true, "sample_query": true, "download_digest": true, "download_all_nodes": true, "download_query": true }, "native_seconds": 13.422170275996905, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "explore-17", "checks": { "digest": true, "signature": true, "sample_query": true, "download_digest": true, "download_all_nodes": true, "download_query": true }, "native_seconds": 0.8272688430006383, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "explore-18", "checks": { "digest": true, "signature": true, "sample_query": true }, "native_seconds": 0.5270251920010196, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "large-seed", "checks": { "digest": true, "signature": true, "sample_query": true }, "native_seconds": 1.280684746991028, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "custom-python", "checks": { "digest": true, "signature": true, "sample_query": true, "download_digest": true, "download_all_nodes": true, "download_query": true }, "native_seconds": 0.532600154998363, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } }, { "label": "after-cancel", "checks": { "digest": true, "signature": true, "sample_query": true }, "native_seconds": 1.2756541090056999, "native_runtime": { "python": "3.12.13", "numpy": "2.5.3", "platform": "Linux" } } ], "cutaway_download_unchanged": true, "passed": true, "scope": "Finite cross-platform content, actual downloaded files, full structural nodes and glass query. No exhaustive seed claim." }