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 functional from live to ghost; initialization validation also rejects repeated ghost targets, 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 itself finds and executes a real start-recorder action. 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, and recording-in-progress becomes true. A ghost has no state and cannot act before this point (rule 5). stop-recorder simply clears the flag again; neither action restores or seeds anything on its own. Recording and playback are not two separate simulated runs with a rollback between them -- they are two derived views of the one path the search actually found, as validate-recorder-solution shows next.

validate-recorder-solution first replays the actions before the real start-recorder move to reconstruct the snapshot captured at that point. It then extracts the recording sub-path -- start-recorder, every ghost move within the window it opens, and the real stop-recorder move when present -- and replays that sub-path from the reconstructed snapshot through the recording shadow. Thus pre-recording changes to live object locations, holdings, supports, pairings, jamming, and mounting are present when start-recorder forks the ghosts. The legacy focused-test form with no explicit start continues to use its authored, already-open start state directly. The validator requires every mapped ghost agent to finish able to return to a recorder. It then independently replays the complete integrated path, live and ghost moves together in their original order, from the original problem start through the ordinary action rules, so all dependencies are checked at their exact prefixes. A search that reaches the problem's own goal without a real stop-recorder still validates, provided every mapped ghost could still reach a recorder from where it stopped (recording-agent-can-close); a problem that wants the return trip spelled out in the solution path adds ghost-stops-recorder as a goal conjunct instead. Including the public recorder assembly automatically installs candidate validation, the two-phase report, and recorder-aware goal chaining together after all recorder components have been defined. Rejected nominal goals remain searchable states rather than solutions. Focused tests that need recorder mechanics without the complete policy include the relevant private -recorder-* components instead.

Recording-prefix pruning is off by default. A recorder problem enables it with (ww-set *recorder-prefix-pruning* t). When a generated start-recorder, ghost, or stop-recorder move changes the isolated recording sequence, validate-recorder-recording-prefix runs before that state is accepted as a goal or entered into duplicate-state tracking. It reconstructs the same snapshot and replays the recording actions accumulated so far. Ordinary live moves are skipped; their pre-recording effects are captured when start-recorder is checked, and later live moves do not belong to the recording sequence. A failed action or malformed recorder boundary cannot be repaired by appending later actions, so that branch is abandoned immediately. The prefix check deliberately does not require the ghost to be able to close the recording and does not test final playback or the goal: those conditions can still change later. It works in serial, parallel, and backtracking search; ordinary problems and recorder problems that leave the option disabled pay no path-reconstruction or replay cost.

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 returns a plist containing the unchanged original path plus recording and playback sequences. It classifies each move by the single mapped agent named in the action; connector names and starred-name conventions are irrelevant. In the recording sequence, each contiguous live-action block becomes one (pause) marker, and only ghost actions remain between the recording's open and close. When the searched path contains a real start-recorder/stop-recorder move, that move opens/closes the sequence in place, exactly like any other searched action. When it does not -- a search that reached the problem's own goal without one -- the report synthesizes a bare (start-recorder) and/or (stop-recorder) marker instead, appending each mapped ghost's outstanding return move first; this is the original, pre--recorder-session behavior, kept as a fallback. In playback, the integrated actions remain intact, with (pause) before each live block and (resume) when a following ghost block begins. The public recorder assembly registers print-recorder-report alongside the validator and recorder-aware goal chaining, so the normal integrated solution is printed first and the recording/playback report follows immediately. All three registrations are cleared whenever a problem is staged, preventing recorder policy from leaking into another problem; restaging a recorder problem installs one fresh copy of each service. A synthesized marker and its appended return moves exist only in the report and never enter the planner's actions, cost, successors, or depth; a real start-recorder/stop-recorder move, by contrast, is an ordinary searched action and already carries its own cost and depth.

Chained solving remains an explicit layer above the single-cycle validator while using the ordinary goal-chaining interface. (solve-subgoal goal) searches and commits at most one intermediate recording cycle; the following (solve) searches and commits the original problem goal as the last cycle. An initial (solve), before any subgoal, remains an ordinary whole-problem search. Chained calls strengthen the requested goal with ghost-stops-recorder, so every mapped ghost physically returns to a recorder in the searched path before the integrated playback state can become a boundary. This stronger chained-cycle invariant deliberately excludes the standalone report's weaker option of appending an unapplied return-walk marker.

After an intermediate commit, the accepted integrated playback state is copied as the next baseline and the just-completed recorded program is discarded. Each shadow component resets the recording relations it owns; after all resets, stateful components seed their memory from the committed playback baseline, and ordinary propagation derives the remaining fresh recording view. This supports sequential cycles only: no nested or concurrent recordings, persistent multiple programs, or global planner search over cycle boundaries.

The chain history retains each cycle's subgoal, strengthened goal, selected integrated solution, recording/playback report, immutable boundary state, search policy, and per-cycle plus cumulative depth, elapsed time, and value change. Search counters and minimum-length depth restart for every 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 that base plus declared-height, default 1. A wall repeater's has-elevation is already its mounting and beam-anchor elevation, default 1. Its declared height measures how far it projects horizontally from the wall, so changing that height does not raise or lower the beam anchor. No separate wall identity is needed: apparatus-coords>, mounting subtype, elevation, 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) — a location's raw 2D placement, 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-walk-via-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 walk-via 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 walk-via> 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 jump-via/climb-via> edges (see problem-claustro-topo's slab). 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

-walkability.lisp owns authored or coordinate-derived walking edges and the canonical DNF-family operations used by the coordinate derivation. Public walkability turns currently enabled edges into normalized walk segments. -mobility.lisp composes those segments with stairs, ladder, and grounded-jump providers into one canonical closure. -configuration-transition.lisp separately retains one support-changing boundary at a time. -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 *vertical-reach-limit* (default 1, owned by -support-elevation.lisp and shared with cargo reach -- see declared-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.

declared-height — a consolidated role query

-height.lisp's single declared-height query owns four role defaults: gate, screen, and wall default to 4; edge and agent both default to 3/2; and box, jammer, connector, and repeater default to 1. An explicit has-height always overrides the role default, and 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 and LOS clearance both call this same query, so their physical barrier height cannot drift apart.

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 own beam anchor is its occupant/base elevation plus that declared height. beam-relay.lisp receives -height through -placement (which nests -support-elevation), so connector pickup and placement can also apply *vertical-reach-limit* via within-agent-vertical-reach.

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. -walkability/walkability, -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 walk-via and jump-via are symmetric, while ladder-via>, jump-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.