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.

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. 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 wall-gears 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 the stateful cycle count is below *max-recorder-cycles* (default 1). The count increments at start, so 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 is a cost-1 planner action just like start-recorder. It requires every mapped ghost agent at a recorder and empty-handed. Closure 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. A connector pairing is only a nonphysical link, so it may cross the boundary and simply disappears with its ghost endpoint. A successful stop 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. Recording and playback remain two derived views of the one integrated path; stop 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, stop, then setup again. It accepts any number of completed cycles up to the stateful maximum, trailing setup after a stop, and one optional final open cycle. Nested starts, unmatched stops, and excess starts 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 stop and subsequent setup. It replays that cycle's real start, ghost moves, and optional real stop in isolation, 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 stop that created their normalized boundary. Rejected nominal goals remain searchable states rather than solutions.

Every generated stop-recorder successor receives mandatory isolated-cycle 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 remains off by default; when enabled with (ww-set *recorder-prefix-pruning* t), it 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 when the 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 wall-gears state. Initial jamming facts must likewise name mapped jammers. Beam crossings, receiver-controlled wall gears, floor and 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 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 stop when present. Actions after the final stopped 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 the sequence in place. A final goal reached before a searched stop 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; at that value the closed-boundary dominance frontier is disabled completely. Mandatory completed-cycle validation reconstructs a path only for a generated stop-recorder successor, and rejects invalid or no-progress cycles before ordinary graph insertion. Optional *recorder-prefix-pruning* spends additional replay work only after starts and ghost moves, in exchange for abandoning an unplayable open recording earlier. Exact live/ghost interleaving canonicalization remains automatic for serial non-hybrid depth-first search. Raising 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 stop, 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 bounds and ordering are likewise problem-specific. A problem's existing min-steps-remaining? or heuristic? can read recording-in-progress, recorder-cycles-used, the live/ghost database, and its own persistent progress facts. Recorder supplies no domain-independent positive lower bound: the problem goal does not reveal how many additional cycles are necessary, and the final-open policy means even a closing stop is not universally required. Any authored lower bound must remain admissible for the problem's 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 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 and commits one closed intermediate cycle; the following (solve) searches and commits the original problem goal as the last cycle. Each guided call strengthens its requested goal with both the exact next recorder-cycles-used value and ghost-stops-recorder, and dynamically narrows the search maximum to that next value. A call therefore cannot silently use multiple native cycles or commit an already-satisfied zero-cycle boundary. The configured *max-recorder-cycles* still limits the complete guided history and must be at least the intended number of calls.

The chain history retains each cycle's subgoal, strengthened goal, selected integrated solution, shared path-derived cycle report, immutable boundary state, search policy, and per-cycle plus cumulative depth, elapsed time, and value change. Its phase display delegates to the same cycle-report printer as an ordinary planner-native result, while its extra output is limited to guided-goal metadata and cumulative chain totals. Its accepted boundary likewise uses the primitive stop's normalizer, so ghost removal, shadow reset/seed/propagation, and cycle reporting each have one implementation. Search counters and minimum-length depth restart for every guided cycle, so optimization remains local and the combined report makes no claim of global completeness or minimum total length. Chaining requires *threads* = 0. If a later cycle finds no solution, retry it from the prepared baseline or use (ww-undo) to restore the preceding committed session; undo again to roll back another boundary and rerun that earlier cycle under a different subgoal or search policy.

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, or where a receiver accepts a beam. It does not create a walkable or occupiable location. Transmitters, receivers, and guns have zero physical height; their functional elevation defaults to 1. A 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. 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 and 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: two locations are reachable when they are identical. 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. 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. -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 supports are singleton configuration-transition routes consumed by the same move action, so the closure still stops at every support-state boundary.

Clearing a barrier and rising in elevation are the same physical constraint, both bounded by the identical managed problem parameter *vertical-reach-limit* (default 1, consumed 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.