tech/ directory: Organization & Mental Model for Talos Principle Planning Problems

How the technology files relate to each other, and how to add a new one without breaking what's already there.

Overview

Every technology-assembled Talos problem (e.g. problem-claustro4a.lisp) declares its own leaf object types and instances in a define-types block, then pulls in behavior via a list of (include-tech ...) directives that the stage-time splicer expands in place before translation. Other standalone Wouldwork problems need not use technologies. This document is a map of what lives in tech/, why it's organized the way it is, and a checklist for integrating a new object type so that additions stay consistent with what's already there instead of quietly drifting from it.

The core idea: a role system, not a type hierarchy

A leaf object type (box, gate, jammer, ...) is inert until it acquires roles. A role is one shared composite type plus the single relation that makes it useful — "has a location," "can be held," "can rest on / be rested on," "has a fixed position," "has a height." Each role has exactly one canonical owner file. A technology file's job is almost always one of a small number of things: own a role, own a derived-fact service, or assemble a leaf type by nesting whichever roles it needs and adding whatever is genuinely unique to that object.

Every (either ...) declaration in tech/ is written in leaf-normal form: its members are base types, never other composites. Named composites remain useful as relation, query, update, and action parameter types, but do not serve as shorthand inside another either. This makes the complete membership of each role visible at its declaration and keeps changes to one role from silently extending another. Wouldwork alphabetizes the member names when it synthesizes an inline composite's unique label, so source order does not affect that identity.

Filename visibility is independent of those kinds. A bare filename such as gate.lisp or walkability.lisp is a public, problem-facing technology. A dash-prefixed filename is a private component normally nested by another technology. The dash says nothing about whether that component is a role, default hook interface, geometry derivation, initialization-check companion, solution service, or action-bearing composite; its descriptive name and header state that responsibility. Characterization problems may include a private component directly when they are deliberately testing its contract, but ordinary problem include lists contain only public names.

Initialization semantics follow the same ownership rule. A technology registers a define-init-check over the complete raw define-init form; deliberate authoring failures use fail-init-check, so the staging error names the owning check. Larger clusters keep their Lisp helpers in a nested -*-init-checks.lisp companion. Those helpers are problem-local and are removed at the next stage, just like queries and updates. Optional (:consumes ...) metadata identifies object types consumed only inside untyped list values, keeping inert-type diagnostics accurate without teaching the engine Talos names.

Vocabulary

The tier picture

Stacking the vocabulary above by what depends on what gives three tiers. Substrate roles sit at the bottom; capability services sit in the middle and consume roles; object & behavior assemblies sit on top and consume both. The one wrinkle: gate is an assembly by ownership, but every service reads its open fact, so there's a real dependency arrow running back up from the service tier into the object tier.

File inventory

What every file in tech/ currently owns, what it nests, and what kind it is. Kept up to date as the directory evolves.

Relaxed-heuristic runtime: after goal relevance is compiled, ww-relaxed-heuristics maps the retained facts and operators to integer vectors and builds reusable dependent and achiever indexes. H-max and LM-cut then share those indexes instead of reconstructing per-state hash indexes and allocated justification arcs. analyze-topo-relaxed-lm-cut returns domain-independent records for every cost-partitioning round, including the selected goal and each cut operator's name, supporter, preconditions, and goal-entering effects; report-topo-relaxed-lm-cut-analysis prints a compact operator-family summary for any staged Topo goal.

Tray relaxation: ordinary tray placement supplies the tray's destination, and zero-cost support consequences propagate that destination only through the retained on chain. This preserves joint one-action relocation for actual nested riders without allowing unrelated support occupants to hitchhike.

Finite-domain resource bound: supported cargo-location goals are routed without accumulating deleted agent locations. The bound minimizes over task order, agent assignment, and across-reach vantages, then adds disjoint MOVE, pickup/placement, and recorder-session costs. analyze-topo-finite-resource-bound returns those three components, the supported goals, and retained cargo tasks without changing the production estimate; report-topo-finite-resource-bound-analysis prints the same decomposition for any staged Topo state and goal. The diagnostic-only analyze-topo-control-setup then sets those already-charged action classes to zero and reruns LM-cut in shared- and dedicated-effect modes. Its typed variant replaces the generic action trigger with plate, receiver, and relocation triggers derived from installed capability types and abstract operator families: beam-blocker movement/manipulation can change receivers, plate changes can propagate through gates, and explicit overlap such as placing cargo on a plate remains intact. A final beam-provenance view ignores hue and corridor clearance while following directional coupled and undirected paired links from every transmitter. It reports one only when the permissive route model still needs an unlinked receiver, so standard relay topology requires a separate connector-link action; existing structural links and alternate routes remain free. The view abstains for happenings, unsupported relay providers, missing connectors, and connector manipulation already charged by the finite-resource term. The reporter lists the receiver classification and binary link cut, and topo-finite-beam-resource-bound exposes its sum with the finite term for explicit analysis. Bounded search measurements showed that evaluating this relaxed beam model either on every selected node or through the reactivating aggregate fallback costs more than its extra prunes save, so it is deliberately not registered for production pruning. Carried trays and tray riders retain their specialized movement semantics; propagating relocation and exogenous happenings cause the partial resource term to abstain. Static reach/traversal indexes and the concrete state-fact extraction are shared with the relaxed evaluator.

Worked example: box

box.lisp doesn't own mobile-object, cargo, support/support-occupant, heighted-object, fixed floor elevation, or support elevation — it nests the role files that do and adds only box pickup and placement. Jumping is a separate capability in jump.lisp, which may use box tops as landings without making box manipulation own locomotion. That's the pattern to imitate for any new movable, stackable object: figure out which existing roles it needs, nest those files, and write only the bespoke remainder.

Special cases

recorder — explicit mapping, not a naming convention

-recorder-core.lisp identifies live and playback-ghost objects through authored recording-copy> facts. The relation is directional and one-to-one from live to ghost, with static indexes supporting constant-time lookup from either endpoint; initialization validation also rejects overlap between the two sides, self-mapping, and cross-category pairs such as an agent mapped to a connector. Every cargo instance must be the live or ghost endpoint of exactly one mapping, whether or not a test happens to use that copy. A fixed combined blower is shared apparatus rather than a cargo fan, as are plates and other fixed objects. Every mobile object carrying a has-location fact must also be mapped. Consequently only mapped objects acquire a recording side, and neither starred symbol names nor problem-local real/ghost composite types carry semantic weight.

Symmetry treats each recording-copy> tuple as one ordered row. Rows with the same complete static role may exchange, but the live and ghost columns never exchange independently and a live-only permutation is invalid. State canonicalization applies one row permutation to both columns and includes every dynamic occurrence, including objects stored in fluent values and recording-shadow facts. Shared apparatus is outside those rows. Goal constants, transition constants, identity-sensitive action parameters, and any static fact that a proposed row exchange would change remove the affected objects from usable symmetry.

Shared actions remain single definitions. They call the neutral hooks from -interaction-policy.lisp; -recorder-core overrides those hooks so pickup, mounting, standing, stacking, jumping, physical landings, and ordinary carried placement keep mapped movable objects on their own layer. Rule 19 supplies one directional support exception during playback: a live occupant may be placed on a ghost tray while a ghost is holding it. A grounded ghost tray remains inert, ordinary ghost mobile supports remain insubstantial to live occupants, and a ghost occupant still cannot depend on a live support introduced during playback. Plates and fixed beam apparatus stay shared — and shared means simultaneously: a support top carries one occupant per layer, so start-recorder's fork puts a ghost box on the very plate its live original already stands on, and both stay. Weight remains layer-blind, since ghost objects have weight (rule 15). Lit connectors exclude another placement only on their own recorder layer, so a live connector does not make the corresponding physical location unavailable to a ghost connector or vice versa. A live connector may select a mapped ghost connector as a terminus during playback, but a ghost connector cannot depend on a live movable connector that was absent during recording. A ghost additionally cannot act at all until recording-in-progress is true (rule 5): a live actor is unrestricted by session timing, but object-manipulation-allowed and connector-pairing-allowed both refuse a ghost actor before the session opens.

The public recorder.lisp assembles private capability-specific components and, at the end, installs the complete recorder solution policy. The core owns only mapping, object presence, and cross-layer interaction policy; plate, receiver, controls, jamming, gate, and blower-drive files each own their recording-side state and derivation. To support another capability, add one focused -recorder-*-shadow.lisp component, give it the matching state/update and actor-aware hook, include it from recorder.lisp, then remove that capability's initialization rejection. Ordinary capability files remain recorder-independent.

Recording begins only when the search executes a real start-recorder action while no cycle is open, its live agent is at a recorder and empty-handed, the closed state contains no stale ghost references, and either the stateful cycle count is below *max-recorder-cycles* (default 1) or that parameter is nil for no limit. The count increments at start even when use is unrestricted, so reports and validation retain exact cycle numbers and a final cycle that reaches the problem goal while still open is counted. At that moment, every mapped ghost's has-location, holding, and on state -- and, when the owning tech is included, paired, jamming, and mounted-on -- forks from its live counterpart's current state, recording-in-progress becomes true, and the recording shadow is reset, seeded, and propagated from that snapshot. A ghost has no dynamic state and cannot act before this point (rule 5).

stop-recorder and cancel-playback are cost-1 planner actions just like start-recorder. Normal STOP requires every mapped ghost agent at a recorder and empty-handed. It is rejected when a live and ghost object are still connected by holding or on, because deleting either relation would leave the surviving object's physical state undefined. Live cancellation instead requires an empty-handed live agent at a recorder while playback is open; it deliberately permits an unfinished ghost, cargo, and cross-layer support dependencies because the remainder is being discarded. Either ending preserves live objects and ordinary persistent state such as toggle latches, removes every dynamic ghost reference (including locations, holdings, supports, pairings, jamming, and mounting), resets all recording-shadow components, seeds stateful memory from the committed live playback baseline, propagates consequences, and asserts recorder-cycle-closed. recorder-cycle-ended recognizes both endings; ghost-stops-recorder additionally requires the strict normal-stop marker. Recording and playback remain two derived views of the one integrated path; each ending is a repeatable primitive boundary rather than a nested planner invocation.

parse-recorder-path walks the integrated path as a state machine: closed setup, start, open window, ending, then setup again. It accepts STOP or CANCEL as an explicit ending, any number of completed cycles up to the stateful maximum (or without a maximum when the parameter is nil), trailing setup after an ending, and one optional final open cycle. Nested starts, unmatched endings, and starts beyond a finite maximum are rejected with the cycle number. Authored focused-test states that begin with recording-in-progress retain one implicit legacy window.

validate-recorder-solution reconstructs each cycle's snapshot by replaying the complete integrated prefix through every preceding normalized ending and subsequent setup. It replays that cycle's real start, ghost moves, and optional normal STOP in isolated recording view; live CANCEL is playback-only and is checked by the integrated replay. It then independently replays the complete integrated path and checks the problem goal. A final goal reached in an open cycle remains allowed when its isolated recording is executable; intermediate cycles must contain the physical ending that created their normalized boundary. Rejected nominal goals remain searchable states rather than solutions.

Every generated stop-recorder or cancel-playback successor receives mandatory cycle-boundary validation before goal handling or graph duplicate tracking. The validator has a newest-move trigger, so recorder problems do not reconstruct paths for unrelated successors. An invalid completed recording therefore never occupies the closed list and cannot suppress a valid route to the same normalized state. The same boundary check rejects a completed cycle whose ending state differs from its starting boundary only in the consumed-cycle count. The closure marker, every ordinary fact, and every recording-shadow fact remain part of this comparison, so closure itself may still be meaningful. A strict improvement to the active time/value objective is also progress. When exogenous happenings exist, the check conservatively retains the cycle because elapsed time may advance toward an event. Diagnostics carry :cycle alongside the failing phase and action or :reason :no-persistent-progress. Optional recording-prefix pruning is a technology-owned diagnostic and remains off by default. An experiment may place (defparameter *recorder-prefix-pruning* t) after (include-tech recorder); it then additionally replays the currently open cycle after starts and ghost moves so an irreversible failure is discarded earlier.

Graph identity remains the complete planner database. In an open cycle it includes recording-in-progress, the stateful cycle count, all current live and forked ghost state, and every recording-shadow component. The pre-start snapshot is therefore replay history needed to validate actions already taken, not hidden context that changes the future of two equal accepted open states. At ghost-free boundaries, a separate recorder Pareto frontier projects out only recorder-cycles-used and uses the engine's exact concrete or symmetry-canonical comparison. An equal boundary reached at no greater depth, time, or objective cost with strictly fewer cycles used dominates the more-used state; a cheaper more-used boundary and a more-expensive fewer-used boundary both remain. Same-count duplicates still go through the ordinary graph open/closed machinery. The frontier is reset for each search, synchronized in parallel search, inactive only when the finite maximum is one, and disabled for tree/backtracking, hybrid path enumeration, exogenous happenings, and solution-enumeration modes where dropping a resource-dominated path would change enumeration semantics.

Serial, non-hybrid depth-first recorder search automatically canonicalizes independent live/ghost interleavings. For each adjacent ghost-before-live pair, it conservatively replays the live action first and then the ghost action. Both swapped states must pass ordinary validity and every non-recorder prefix policy, and the complete resulting state must exactly equal the original ghost-before-live result. Otherwise the original ordering is retained. A certified inversion is discarded in favor of its live-before-ghost equivalent. The original successor has already passed recording-prefix validation, and swapping one adjacent live/ghost pair leaves the recording-only action sequence unchanged, so certification reuses that result rather than reconstructing and replaying the same recording prefix. No user setting or diagnostic output is involved. Parallel, hybrid, and backtracking search are unchanged.

Ghost locomotion and targeting read recording-side gate state. Plate-controlled gates use ghost-only plate state. Receiver-controlled gates use a recording beam view containing fixed apparatus, mapped ghosts, and unmapped fixed objects while excluding mapped live relays and blockers. Jamming remains one shared action fact: ordinary playback responds to every jammer, while recording-jammed admits only mapped ghost jammers into recording gate and supported blower-drive state. Fixed floor blowers are not copied: floor-stream launch and sustain checks select ordinary turning for live objects and recording turning for ghosts, so playback-only activations do not alter recorded ghost motion. Initial jamming facts must likewise name mapped jammers. Beam crossings, receiver-controlled blower drives, floor gears, angled blowers, threats, and movable recording-side wall-fan mounting remain outside the supported scope and are rejected during initialization.

build-recorder-report consumes a completed integrated solution and reconstructs it from *start-state*, returning a plist containing the unchanged original path, an ordered :cycles list, trailing setup, and complete-solution totals. Each cycle contains its number, its cycle-local integrated path, setup, recording and playback sequences, explicit, cancelled, or synthesized closure status, and local depth, elapsed-time, and value-change metrics. The local integrated path begins with that cycle's setup and ends with its searched ending when present. Actions after the final ended cycle remain under :trailing-setup with their own metrics. A legacy path with no explicit boundary is represented as one synthesized report cycle. For compatibility and convenient display, a one-cycle report also exposes its setup, recording, and playback sequences at the top level.

Within each recording sequence, every contiguous live-action block becomes one (pause) marker and only ghost actions remain between the recording's open and close. Searched start-recorder/stop-recorder actions open and close a normal recording sequence in place. cancel-playback is omitted from recording view and retained at the end of playback view with the live actions that led to it. A final goal reached before a searched ending instead receives a report-only (stop-recorder) marker after any available mapped-ghost return moves. This synthesized closure records the presentation implied by the existing final-open-cycle policy; it does not add actions to the accepted planner path or claim different physical validation. Playback retains only in-window moves, placing (pause) before each live block and (resume) before a following ghost block. All metrics exclude synthesized markers. Report construction replays every searched segment, so an inconsistent accepted path surfaces as an error rather than producing misleading local values.

Multi-window paths are valid candidates for one planner search, so the report's complete totals and the planner's depth, time, and value optimization cover every setup, start, integrated window, stop, and trailing action in the accepted path. Single-cycle printing keeps the compact setup/recording/playback presentation. Multi-cycle printing adds one numbered section per cycle, followed by trailing setup when present and complete totals. The public recorder assembly registers this printer alongside validation and recorder-aware goal chaining; all three registrations are cleared whenever a different problem is staged.

Recorder performance controls are deliberately layered. *max-recorder-cycles* defaults to one, preserving the original search space; a positive integer imposes that finite limit and nil permits unrestricted starts. At the default value the closed-boundary dominance frontier is disabled completely; it remains active for eligible unbounded graph searches so equivalent boundaries with needlessly greater cycle histories do not grow the graph without limit. Mandatory completed-cycle validation reconstructs a path only for a generated STOP or CANCEL successor, and rejects invalid or no-progress cycles before ordinary graph insertion. The technology-owned diagnostic *recorder-prefix-pruning* defaults to nil; enabling it spends additional replay work after starts and ghost moves in exchange for abandoning an unplayable open recording earlier. It is not a persisted problem parameter and is omitted from (params). Exact live/ghost interleaving canonicalization remains automatic for serial non-hybrid depth-first search. Raising or removing the cycle maximum adds legal starts and therefore search states even when the selected solution still uses one cycle.

*depth-cutoff* is the total planner-native bound: setup, every start, every integrated window, every explicit ending, and trailing setup all consume it. There is intentionally no generic per-cycle depth parameter. An open cycle's remaining local allowance would affect its future and would therefore have to be represented in graph identity; computing it only from a node's parent path would make equal databases merge unsafely. A problem needing a hard local limit should model the relevant progress in its own state. Guided chaining can apply a separate total cutoff to each search, but those locally bounded searches do not optimize one complete multi-cycle path.

Cycle-aware lower-bound terms and ordering remain problem-specific. The optional topo-lower-bound.lisp service automatically contributes only its finite-resource term; its explicit relaxed h-max and LM-cut diagnostics can model a recorder start and either ending, but deliberately ignore other ghost-object goals. The problem goal does not reveal how many additional cycles are necessary, and the final-open policy means even a closing action is not universally required. A problem may define its own min-steps-remaining? or heuristic? from recording-in-progress, recorder-cycles-used, the live/ghost database, and persistent progress facts. Any added cycle-aware bound must remain admissible for the actual goal and permitted final closure policy.

For first searches, an inexpensive practical escalation is to try one cycle and only retry with two when the first search finds nothing:

(ww-set *max-recorder-cycles* 1)
(solve)
;; If no solution was found:
(ww-set *max-recorder-cycles* 2)
(solve)

This establishes only that a solution was found at the first attempted cycle limit that succeeded. It cannot establish global minimum length: a two-cycle solution may be shorter than every one-cycle solution, so stopping after the one-cycle success would miss it. To optimize the complete path, run min-length with the final cycle maximum and a suitable total depth cutoff.

A problem whose rules impose no recorder-use limit may instead set (ww-set *max-recorder-cycles* nil). The total depth cutoff still bounds any finite search run, and eligible graph searches retain recorder-boundary dominance to suppress equivalent histories that merely used more cycles.

A focused serial graph-search measurement with first and fixed total cutoffs characterized the current cost without running Rumin. The one-cycle snapshot fixture used 12 states and 8 search cycles at maximum one, versus 13 states and 9 search cycles at maximum two; both found the same depth-3 solution. The required-two-cycle fixture used 9 states and 8 search cycles before exhausting maximum one, versus 24 states and 18 search cycles to find its depth-7 solution at maximum two. Measured wall times were approximately 1.020 ms, 0.838 ms, 0.747 ms, and 2.090 ms respectively; at this scale timing order is dominated by measurement noise, so state counts are the useful comparison. These figures characterize the present fixtures and action order rather than predicting a large problem's branching factor.

problem-recorder-two-cycle-test.lisp is the focused non-flattenability proof. In its first cycle a ghost creates a transient priming condition that a live action consumes to latch a persistent plate; neither side can create the accepted boundary alone, and the priming condition itself does not survive. The second cycle's ghost can use the resulting recording-side gate only after stop normalization seeds the new snapshot. Moving both advances into one window fails isolated recording replay because the live latch action is absent there. With a seven-action depth bound the fixture has no solution when *max-recorder-cycles* is one, while one ordinary solve finds and reports the explicit two-cycle solution when the maximum is two.

Guided chaining remains a convenience rather than the implementation of planner-native cycles. (solve-subgoal goal) searches for the next user-selected milestone without adding a cycle count or closure requirement. A checkpoint may be before a recording starts, inside an open recording, or after one or more boundaries; actual START, STOP, and CANCEL actions determine the cycle structure. If the next milestone exhaustively has no solution, generic goal chaining records that the exact preceding endpoint is unsuitable for that complete requested suffix under its saved cutoff and feasibility-affecting settings. It restarts the preceding milestone search while excluding that contextual endpoint, retries the suffix, and propagates exhaustion backward as necessary. It retains only the active phase solutions and exact nogood keys rather than a frontier or candidate pool. An interrupted, cancelled, capped, out-of-memory, or otherwise incomplete search is unknown: it rejects no checkpoint and leaves the last committed chain intact. The following (solve) searches for the original problem goal and returns one cumulative solution and recorder report. Earlier subgoal formulas remain ordered milestones rather than persistent state constraints unless the user repeats them in a conjunction. An advanced subgoal may request recorder-cycle-ended explicitly when a boundary is intentional.

The generic checkpoint identity includes both planner databases, happenings, time, value, and the staged-problem generation. Recorder supplies only its cycle/resource context and saved Talos search settings. When revisiting a phase, the engine restores its depth cutoff, search algorithm, graph/tree mode, solution type, ordering and random state, symmetry and waiting controls, lower-bound switch, and the registered recorder/Talos settings. A contextual nogood includes the entire later goal suffix and those settings, so changing a later formula or cutoff cannot reuse an invalid stale rejection. Rejected goal states are filtered before graph duplicate handling but remain ordinary searchable successors, allowing a descendant to satisfy the milestone differently. first obtains the next endpoint by restart-and-exclusion; min-length reruns its normal bounded optimization over non-rejected endpoints; a positive solution count remains a transient candidate batch whose unselected members are not retained.

The recorder chain history retains each accepted goal, segment solution and exact endpoint, saved solution policy, cumulative depth, elapsed time and value change, and recorder cycle count and open/closed status. Every tentative retained prefix is replayed exactly from the original staged state and passes validate-recorder-solution; a successful alternative replaces the rejected suffix atomically. Recorder phases and closures are not assigned to checkpoints or stored separately, and final display delegates to the ordinary path-derived recorder report. Search counters and objective optimization restart for every segment, so the combined result makes no claim of global minimum total length. Chaining requires *threads* = 0. ww-undo reverses one explicit solve-subgoal or mid-chain solve command: after automatic recovery it restores the formerly selected prefix in one step, including recorder history, alternatives, and contextual nogoods. Staging or resetting a problem clears the chain, undo history, policy, retained alternatives, and nogoods. An incomplete accepted chain can instead be carried across a restart with export-subgoal-progress and import-subgoal-progress. The human-readable .txt archive contains milestone goals, saved settings, action segments, and symbolic endpoint facts. Import requires a freshly staged matching problem, replays and validates the entire prefix, and builds new stage-local state keys and recorder segments rather than restoring serialized planner objects.

Checkpoint candidate screening is a separate generic layer with three results. impossible requires a sound proof and excludes only the exact state under the original final goal and applicable remaining-budget context; possible requires a concrete replayable continuation; unknown retains the candidate. Engine inconsistency and a relaxed model explicitly certified complete for unreachability are generic proof sources. The optional Topo lower-bound service contributes its explicit-goal finite-resource bound only when the known remaining phase cutoffs form a finite total budget, and rejects only when the admissible bound is strictly greater than that budget. Recorder contributes normalization and cycle-state consistency without moving recorder semantics into the engine. Ordinary heuristic scores, incomplete relaxed models, interrupted or failed bounded probes, timeouts, resource caps, and out-of-memory results remain unknown and cannot remove a checkpoint.

Proof-based screening rejections are stored separately from exhaustive continuation nogoods. Their key includes the exact checkpoint, original final goal, complete later request suffix, and derived remaining-depth budget; changing a goal or cutoff therefore cannot reuse stale screening evidence. Automatic recovery, ww-undo, and staging treat both stores transactionally. Screening ranks or removes only user-requested milestone candidates: it does not generate subgoals or turn uncertain landmarks into mandatory checkpoints.

gate — the hub

gate.lisp owns a real leaf type and its own update-gate-status!, which makes it look like an ordinary assembly. Its gate optional type and (open gate) relation are declared once, in -gate.lisp, nested by every file that reads open — walkability (via -passability), reachability, visibility, beam-direct, beam-crossing, and -passability itself — so the declaration is a hard, enforced dependency rather than a hand-copied one. What stays soft is the assertion: only gate.lisp's update-gate-status! ever makes open true, and something must still call it before anything downstream reads a current value. That call used to be the problem's job; since Phase 3 the driver is derived, so including gate is now sufficient on its own. That write-once-read-everywhere shape — not the declaration — is why gate keeps the widest blast radius in the directory. The controller wiring itself (controls and energized) migrated out of gate.lisp into -controls.lisp when blower drives became a second controlled-device family; control-on now evaluates that DNF aggregate once for gates, blower drives, and guns alike, taking the uncontrolled default as an argument, since that was the only thing that differed between the copies (a gate reduces to open <=> jammed, uncontrolled blower drives and guns to running unless jammed — a jam always disables the barrier, opening a gate but stopping a blower drive). Recorder's recording-side aggregate stays a separate query in -recorder-controls-shadow.lisp rather than a view argument, so that the propagation walker sees disjoint read sets for the playback and recording strata.

-gears-fan — a composite substrate

-gears-fan.lisp is nested by -floor-blowing, wall-blower, and angled-blower — never by an ordinary problem's own include-tech list. It owns the mountable gears leaves, the fixed blower leaves, the gears and blower unions, removable-fan actions, and shared driver helpers. The public floor-gears and floor-blower technologies both nest -floor-blowing, which owns the floor-directed physics shared by those distinct object forms. Floor, wall, and angled behavior use the same drive interface whether the source is a mounted fan or a fixed blower, while only removable fans participate in cargo actions. Composite substrate names that structural shape; the dash independently says that the bundle is private.

beam-direct / beam-relay / beam-crossing — peer-plugins

These three share one role file, -beam-substrate.lisp, which is unusual for a role file in that it also ships null-object default queries (e.g. direct-beam-reaches-receiver defaults to always nil). Each peer overrides only the hooks it owns; an absent peer contributes nothing rather than erroring. Use this pattern only when 2+ variants genuinely need to plug into the same interface — a single relation doesn't need it.

beam-direct owns every directional fixed-apparatus corridor: transmitter→receiver, transmitter→repeater, and repeater→repeater/receiver. Each coupled fact has one matching beam-via; fixed couplings are unlimited. It includes public visibility, records every coordinate-known wall, edge, gate, and boundary crossing for each coupling during initialization, and evaluates those finite barriers from the beam's current endpoint elevations at runtime. Equality with a barrier top blocks; the beam must be strictly above it (or below its base). A coordinate-known open gate is transparent, while a closed one can be cleared by height; an authored beam-via gate without crossing geometry keeps the legacy open-only rule. A location in the corridor blocks only when a beam blocker (agent/box/jammer/connector) with has-location there spans the beam's interpolated elevation.

beam-relay propagates one derived color through connectors and repeaters. Connector paired links are structurally undirected and visibility-dependent; repeater coupled links keep their authored direction and normal corridor checks. If differently colored sources reach a relay in the same propagation layer, that relay remains unlit. Both kinds of live link participate in beam crossings.

apparatus-coords> — apparatus functional points

apparatus-coords> is the XY coordinate of an apparatus's functional point: the point where a transmitter, repeater, or gun emits or acts, where a receiver accepts a beam, or where a switch is mounted. It does not create a walkable or occupiable location. Transmitters, receivers, switches, and guns have zero physical height; their functional elevation defaults to 1. A switch or repeater is fixed and likewise has no has-location.

A floor repeater's has-elevation is its base/floor elevation, default 0, and its beam anchor is its top — that base plus its height, default 1. A wall repeater's base is apparatus-coords>'s third coordinate, default 1; its height measures how far it projects horizontally from the wall, so its axis is horizontal and its top equals its base however large that height is. There is one anchor concept now, not four: a beam anchor is always the anchoring object's top. No separate wall identity is needed: apparatus-coords>, mounting subtype, and height fully determine the functional geometry used by the planner.

-location-coordinates — one role shared across two coordinate-derivation substrates

-location-coordinates.lisp owns nothing but (location-coords> location $rational $rational $rational) — a location's raw placement, the third coordinate optional, independent of any capability that might consume it. Both -beam-los-coordinates (nested under visibility, and transitively under beam-crossing via -beam-crossing-coordinates) and -walkability-coordinates (nested under walkability) nest it for a location's coordinates, so a problem using both capabilities enters each location's position exactly once, and a problem using only one of them never pulls in the other's machinery. This is the direct worked instance of the integration checklist's "new role, 2+ plausible consumers" rule below: the role got its own dash-prefixed file specifically because a second consumer showed up, rather than the second consumer copying the first's relation under a different name or requiring an unrelated capability just to get coordinates.

-walkability-coordinates's own derive-walking-from-segments also illustrates that a coordinate-derivation substrate need not use the same algorithm as its sibling: -beam-los-coordinates tests straight-line segment intersection (right for sightlines and beams), while -walkability-coordinates answers a region-connectivity question (right for walking, where the real path detours through a doorway or around a corner rather than following a straight line). It builds a coordinate-compressed arrangement from the segments, the boundary polygon, and each wall fan's derived air-stream band (center line from the solid backstop behind the fan to its aimed-at destination, widened to stream-width, default 3); flood-fills open cells into zones; and computes every subset-minimal door-set between zone pairs, emitted as DNF walking clause families. Co-located gates and screens form one conjunctive clause, so every fixture must pass; a stream curtain remains exclusive because its directional ride behavior is not ordinary conjunctive passability. A stream's swept location belongs to the band's interior zone only, so every edge to it carries the gears -- standable exactly while the stream is off; riding is instead the destination's property: from every zone flanking the band across a side curtain, a directional walking edge into the aimed-at destination carries that zone's own family (step laterally into the flow and be carried there while blowing, or walk across the dead band while off -- the unconditional edge is correct in both regimes), while entry against the front curtain stays gears-gated, so the mobility closure crosses a blowing stream only downstream, never against or through it. The derivation is single-layer after one vertical consistency distinction: a gate or screen may share a wall/edge interval when the solid's top is at or below the door's base, in which case the planar interval remains solid and an authored level-change edge handles the upper doorway; a genuine vertical overlap is rejected. Otherwise segment coverage remains elevation-blind: an elevated platform authors its ground-level footprint as walls, keeps its top locations inside, and connects levels only with authored jumping/climbing edges; even two locations sharing one x/y point remain separate endpoints whose raw derived edge one-step-walkable rejects when their elevations differ (see problem-claustro-topo's slab and problem-phobia-topo's ground/loft pair). See the file's own header for the full reasoning.

reachability — identity default with an optional extension

-reachability.lisp supplies the baseline reachable query used by manipulation actions: a target and the actor's location are reachable when they are the same location. Its reach-target role also admits fixed switches. box, jammer, and beam-relay nest this substrate, so they remain self-contained without authored reach edges. Including the public reachability technology overrides the same query with identity plus reach-via edges and gate checks; switch manipulation authors an edge from a nearby location directly to the switch apparatus. As with the beam hooks, nested-include deduplication installs the default once before any override, independent of the problem's include order.

walkability — walking topology and mobility provider

-traversal.lisp owns the symmetric traverse-via and directed traverse-via> relations shared by walking, stairs, jumping, and climbing, along with their common DNF-family operations and the single traversal-segments provider, which is content-cached on the state’s projection onto the dynamic relations the mode builders read. -walkability-coordinates.lisp derives the walking facts from geometry. Public walkability registers the walking predicate that requires equal endpoint elevations and a passable clause, turning currently enabled walking facts into normalized walk segments. -mobility.lisp composes those with the segments registered by stairs, ladder, and grounded jump into one canonical closure. -configuration-transition.lisp separately retains one support-changing boundary at a time, including a ladder climb that starts on a support. -mobility-action.lisp normalizes both result kinds as routes between agent configurations and applies either through the single move action. beam-relay consumes only the transparent mobility closure for pairing vantages. Recorder validation uses the same current-state closure after restoring its snapshot.

visibility — null default with an optional extension

-visibility.lisp supplies ordinary, beam, and endpoint-elevation-aware visibility interfaces with null defaults, allowing beam-relay and jammer to compile independently while granting no sight-dependent behavior. Including the public visibility technology adds authored LOS relations and coordinate derivation; beam-direct now includes it for fixed-coupling barrier geometry. Initialization retains every wall, edge, gate, and boundary crossing with its oriented beam parameter, including apparatus-to-apparatus fixed couplings. visible keeps solid barriers opaque; potentially-visible recognizes structural location pairing; beam and elevated-jammer sight interpolate their current endpoint elevations and clear only below a barrier base or strictly above its top. Open gates remain transparent, and actor-aware forms select playback or recording-shadow gate state.

A typed null hook is still installed when one of its optional object types has no objects in the current problem. Calling the hook returns its neutral value (usually NIL); the empty type matters only where an action or quantifier enumerates it, in which case there are no instantiations and therefore no calls. Query/update signatures type Wouldwork object parameters only. Computed Lisp values such as elevations, lists, and hash tables remain untyped parameters.

beam-relay uses potentially-visible across every location in the agent's current mobility-locations closure when selecting pairings, before placing the connector. Traversal obstacles use current passability when forming that closure, but gates and finite barriers on a potential LOS need not already clear. Live lighting and receiver propagation use the beam-specific visibility forms from the connector's exact placed location. jam-target evaluates each legal support at the jammer's resulting top elevation and aims at a gate's vertical midpoint or a point target's functional elevation; a mapped ghost still uses recording-side gate state. The same file owns put-connector, which shares placement rules with connect-connector but creates no pairings.

passability — shared traversal clearance

-passability.lisp owns the action-free rule for clearing a traversal edge's obstacle list: open gates pass, while screens and ladders require an empty-handed agent. walkability, jump, and ladder nest it for walking, jumping, and ladder traversal respectively. Public walkability is therefore needed only for walking behavior.

jump — mobility barrier clearance and support transitions

jump.lisp owns one capability with optional physical path features. An empty feature list is an unobstructed jump. Open gates and passable screens need no clearance; closed gates, non-passable screens, and walls contribute their top elevations, and the agent must clear the highest one. Ground-to-ground edges are pure mobility segments that may compose into a longer move route. Jumps onto, off, or between raised supports are singleton configuration-transition routes consumed by the same move action, so the closure still stops at every support-state boundary. A box offers its top wherever it is located; a tray offers its top only while another agent is holding it. Grounded trays remain inert, and recorder-side policy separately decides whether the jumping agent may use the held tray.

Clearing a barrier and rising in elevation are the same physical constraint, both bounded by the identical technology-owned *vertical-reach-limit* (default 1, defined by -support-elevation.lisp and shared with cargo reach -- see object-height below) measured from the jump's explicit launch elevation — independent of the jumping agent's own declared height in either case. An agent standing high enough (on a box, a platform, or a prior jump's landing) can clear an arbitrarily tall wall as long as the remaining clearance from that launch point is within the fixed limit; downward and level landings remain unrestricted.

Every produced segment or transition is tagged JUMP or VAULT as its move-type — the same position WALK, STAIRS, and CLIMB occupy in a printed route. The tag is VAULT when some feature genuinely required clearance (again via jump-required-clearance-height's passability filtering, so an already-open gate or an empty-handed-passable screen in the list does not count), else JUMP. This is purely a descriptive label on the same normalized segment; it does not add a new action or change what MOVE can produce.

object-height — one height table

-vertical.lisp's object-height query reads an explicit has-height fact for a heighted-object, or falls back to the type's entry in *vertical-type-constants* for every vertical-object: gate, screen, and wall 4; edge and agent 3/2; box, jammer, connector, floor repeater, and wall repeater 1; and location, tray, fan, pressure plate, toggle plate, floor blower, angled blower, transmitter, receiver, and gun 0. Types outside heighted-object intentionally keep that table value. Wall gears and wall blowers are intentionally outside the table because their has-elevation denotes stream height rather than a solid object's base. Both has-height and has-elevation are declared $rational, so a fractional override such as edge's own default is a legal authored fact. Jump clearance reads the resulting top, while LOS clearance, beam occlusion, and jammer aiming use the same vertical model, so their physical barrier heights cannot drift apart. Gate aiming averages base and top; hypothetical jammer placement adds object-height to placement-elevation because the jammer is still held while the action evaluates its options, making its current structural top inapplicable. An object outside the table signals an error rather than reading as zero.

connector (from beam-relay.lisp) later joined heighted-object and beam-direct's beam-blocker composite, so a connector left sitting in a direct-beam corridor blocks it exactly like a box or jammer would, defaulting to the unit height of 1 rather than an agent's 3/2. Its beam anchor is its top: structural base plus that height. beam-relay.lisp directly nests -vertical for this geometry; its -placement dependency supplies -support-elevation's reach policy for connector pickup and placement.

Two axes of dependency: hard vs. soft

Hard dependencies are (include-tech ...) nests — resolved by the splicer at every level, so a present file can't quietly omit what it nests. A technology that doesn't exist yet is spliced as a skip-with-warning rather than a hard error, so a problem may be staged before every included technology is written. Soft dependencies are calls into relations or queries owned by another file without nesting it. An unguarded soft dependency requires the problem's own include-tech list to bring in the owning file.

A soft dependency can instead be conditional when every reference is guarded by an optional type. For example, gate calls jamming only inside (exists (?j jammer) ...), and calls depressed only in an and branch guarded by (plate ?controller). When the guarding type is empty, static translation removes that branch before translating the relation call, so the relation's owning technology may be absent. If the problem declares any objects of the guarding type, it must include the owning technology.

Keep conditional references in forms whose static truth the translator understands: quantifiers over the optional type; statically decidable and, or, not, if, and cond branches; or a case selected by a static key. An unreachable reference hidden inside an arbitrary Common Lisp call is not optional. Document both the owner and the guard in the referencing file's REQUIRES header.

A shared hook substrate is the third case. It supplies a complete baseline query, while an optional public technology overrides that query with extended behavior. Consumers nest the substrate and therefore never have a missing function; the problem includes the public technology only when it needs the extension. -reachability/reachability, -visibility/visibility, -beam-substrate/its peer technologies, -recording-shadow-policy/-recorder-core plus the matching apparatus shadow components, and -passability's actor-aware stream-obstacle-clear/-stream-passability use this pattern.

Integration checklist

For a new object type, work through these in order.

1. Classify it first. Does it just need to participate in existing roles (have a location, be held, rest on/be rested on, have a fixed position, have a height), or does it need a genuinely new relation nobody has? Most new objects are almost entirely the former.
2. New role, one consumer → declare its type + relation inline in the consuming assembly file (like jump's vaultable-object or jammer's target). Don't create a substrate file for something with exactly one user.
3. New role, 2+ plausible consumers → give it its own dash-prefixed, private file with only the shared types, relations, and queries needed for that role. No actions or driver logic by default — that's the shape to reach for first. Widen to a composite substrate (see Special cases) only when 2+ sibling assemblies genuinely share tightly-coupled actions that splitting further would fragment, as -gears-fan does for the three blowers; it remains dash-prefixed because it remains private.
4. Existing role → nest the owning substrate file. If the new leaf type isn't already a member of the role's either union, add it there — the union lives in exactly one place, and nesting alone doesn't extend it. Every either must list base types directly; do not put the role's name inside another composite as shorthand. Never retype the owning either form elsewhere (see the jump case study above); edit the one owning declaration instead. A new object touching several roles (mobile, occupant, heighted, ...) means one small edit per role it needs, in that role's own file — the cost of "exactly one owner per role."
5. Declare the leaf type optional (define-optional-types) in the new assembly and in every other file that references it as a bare pre-param type. This is idempotent and order-independent, so repeating it is always safe.
6. Design each relation signature deliberately. A $-prefixed declared type marks a functional/fluent value position. When the same normalized type appears in multiple positions, Wouldwork treats those positions as symmetric and installs their permutations; append > to the relation name when those repeated positions instead have ordered roles. Thus traverse-via is symmetric — its repeated type is location, so the leading mode argument does not disturb the mirrored pair — while traverse-via> and jam-disallowed> are directional.
7. Identify soft dependencies — which services (reachable/visible/mobility-results) or hub facts (open) the new actions will call. Document them in a REQUIRES header like the existing files do. The owning file must be in the problem's include-tech list unless every reference is guarded by an optional type that is empty for that problem, or the consumer nests a complete default hook substrate.
8. New derived boolean fact? Declare its relation with define-derived-relations, give it a zero-argument define-update, and nest -propagation. The declaration prevents a problem from authoring either polarity of the computed fact in define-init. A zero-argument update in a technology file is a driver update and is picked up automatically; a parameterized one is a helper whose relevance its callers decide. Do not write a call into propagate-consequences! and do not ask a problem to sequence it — the order is derived from the read/write graph at init. If the new update writes base facts that ordinary actions also write, it is a reaction and the derivation places it after every derivation, which is the one ordering constraint that is enforced rather than merely optimized.
9. Own initialization semantics. Put a small define-init-check beside the relation it validates, or nest a focused -*-init-checks.lisp companion when several helpers belong together. Use define-init-check-helper for those helpers and fail-init-check for authoring failures. Declare (:consumes ...) when a type is visible only inside an untyped list payload.
10. Write the actions. This is the one genuinely bespoke step.
11. Test via REPL, unless the new tech isn't referenced by any problem's include-tech yet, in which case the testing waiver applies.