docs(spec): the interactive-machinery design of record (spec-0031, spec-0032)

[stellarfeline]

Records an owner design session so it is executed, not re-asked.

The finding that shaped both specs

Four commissioned capabilities — a lift, a currency, a shop, a death-and-recovery loop — were surveyed against vanilla 1.21.11 and against the engine. They share one missing primitive, so building any of them alone would have produced a private copy of the shared part: the defect CLAUDE.md names first.

The missing primitive is clearable, comparable runtime state. The only author-visible state today is FlagId — boolean, party-wide, and monotonic, with no verb that clears one. A lift needs car_at_floor and ride_in_progress; a purse needs a balance; a stake needs an amount. All numeric, all must go down as well as up, and every one is read as a condition on some other effect.

So the comparison goes into the shared gate struct, not onto a shop verb. The gate struct's consumers — 16 effect variants, all 5 objective kinds, triggers, traps, cast placements, dialogue options, branch declarations — are exactly the comparison's consumers. Decided at the first site; retrofitting at the second costs a dsl_version bump and an adoption round on every active campaign.

What else was already there, privately

• open-gate / close-gate already fill and clear a declared region at runtime, and close-gate already teaches the completability model to treat it as solid from its DAG point. collapse's then_floor already paves standable ground at runtime. The capability exists twice, inside two verbs; the only general spelling, set-block, places one block. spec-0031 moves it to the object class it acts on.
• The engine emits status effects internally and exposes none; it teleports players and has no verb.
• on_death does not exist — only on_respawn. With it, "the purse drops on death" becomes content expressed in a general mechanism rather than an engine feature.

The lift is a worked example, and explicitly not a verb

Once the primitives exist, the owner's lift is a sequence of them — and so is a rising drawbridge, a materialising bridge, an opening wall, a summonable cargo platform. Its full timing, its one-car invariant (create before clear, so no tick can be saved with no car), and every corner case ruled that day are in the spec.

Transport is by teleport, by owner ruling — not levitation, not a ridden entity, and no redstone mechanism. A separate consultation established why a solid moving platform is unavailable in vanilla 1.21.11 at all: display entities have no collision, /data refuses player data so player motion cannot be written, and the one stand-on entity drops its rider on ascent.

Economy

The first decision was already made silently by a default: gamerule keep_inventory true means an item currency cannot drop on death, and keepInventory is all-or-nothing — switching it off would also drop the pre-provided class kit in a zero-grind map. So the ledger is a score. Written down with its reasoning so a future session finds the why, not just the outcome. Villager Offers is excluded for three independent reasons, any one sufficient.

The recovery stake is a glowing interaction point collected by right-click, not an item entity, placed at the nearest point to the death point on the walkable route between the respawn point in force and where the player died — restated so it is a compile-time table rather than a runtime search, and honest about the one substitution it makes: reachable-under-quest-state stands in for "explored", which the engine does not track. That is recorded in the spec rather than quietly equated.

CLAUDE.md

Two rules this session earned:

• A settled ruling is never re-asked. Both questions put to the owner that day were already answered in the repo — the traversal override in an earlier session, and "traps: redstone or commands" by the title of spec-0022-traps-v2-command-driven.md, her own directive of 2026-08-03.
• A release is built from a frozen approved tree, never from a moving branch. Tagging main at release time is what shipped a package the owner had not approved, with no place in the pipeline able to ask whether it was the accepted thing.

What this PR does not do

No code. Both specs carry machine-checkable acceptance criteria and an explicit unverified list, led by whether the pre-respawn death advancement fires for void, fall and drowning deaths — load-bearing for a souls-shaped delve, and to be answered by a live spike rather than recall.