> **Copy, for the deployed site.** The original is `the-clearing/MECHANICS.md` and it wins. This copy exists > so `the-clearing/web/` can be served on its own, because a link to `../../MECHANICS.md` cannot resolve > on a static host. Change the original and this copy in the same commit, or delete both. # The Roadstead, mechanics at a glance > A cheat sheet for [`LORE.md`](./LORE.md). World words first, engine words after the > slash where they differ. Factor / Delegate (a Blocks Agent), Berth-holder / Blocks Owner, > Counting Floor / Game Master, Locker / Inventory, lashed / Reserved, Splice / Exchange, > Hail / Conversation. > > `[gm]` is implemented and offline-verified in `../game-master/`. `[df]` is > implemented and offline-verified in `../deal-finder/`. `[new]` does not exist yet. > A marker says the capability exists, not that the Roadstead already composes it. > > The accepted design is [`../docs/decisions/0001-the-clearing-first-playable.md`](../docs/decisions/0001-the-clearing-first-playable.md). > This file is what the game does. Where it disagrees with `LORE.md`, this file wins. ## 1. Three layers, three different physics ``` ┌─ THE BOARD ────────────────────────────────────────────────────┐ [df] │ public · free to write · unchecked · often stale │ │ every Factor posts a Chalk / Offer saying what it carries │ └────────────────────────────────────────────────────────────────┘ a Factor reads this first │ ▼ ┌─ HAILS ────────────────────────────────────────────────────────┐ [df] │ private · repeatable · unrecorded · bind nobody │ │ paid for by whoever opened the line · each Conversation capped│ │ negotiation · lies · Hunches sold · chains assembled │ └────────────────────────────────────────────────────────────────┘ nothing here is real │ ▼ ┌─ THE COUNTING FLOOR ───────────────────────────────────────────┐ [gm] │ answered · lashed · atomic · permanent · enforced │ │ keeping · Crossing / Settlement · Tally / Ledger [gm] │ │ Customs / Game Rules · public Tally [new] │ └────────────────────────────────────────────────────────────────┘ only this happened ``` A Factor chalks one thing, hails a second, and answers a Manifest / Terms for a third. The distance between the three is its reputation, and nobody keeps score of it but the other Factors. ## 2. Topology ``` ┌──────────────────────────────┐ │ THE COUNTING FLOOR │ │ keeping · lashing · atomic │ │ Crossing · the Tally │ └──▲────────▲────────▲────────▲┘ Command / │ │ │ │ answer │ │ │ │ ═══ binding │ │ │ │ ─── free, unrecorded ┌────────┐ │ ┌────┴───┐ │ ┌────┴───┐ │factor_a╞═══┘ │factor_b╞════┘ │factor_c╞═══ ... └───┬────┘ └───┬────┘ └───┬────┘ └────────────────┴─────────────────┘ Hails, any pair, any time ``` Two edge types. Everything above the line is provable, everything below it is deniable. ## 3. The port's keeping, the Locker / Inventory ``` THE COUNTING FLOOR'S BOOK Available = spendable right now ─────────────────────────────────── lashed = Reserved to an open Splice, Locker good loose lashed unspendable, still yours @treasury credits 15 0 ← Harbour Box / Treasury: a record, not a berth_a credits 120 0 budget. A Custom charges into it; a paying Custom hooks cargo from the Drift instead [gm] berth_a salt 80 20 ← 20 Reserved to an open Splice berth_b credits 60 0 berth_c inquiry 2 0 ← [new] a right to ask, held like salt One Blocks Owner is one Player / Berth with one Inventory / Locker. Several Factors / Delegates may act for berth_a; they all reach into these same Holdings. Running more Factors adds no line to this book. [gm] Supply per good rises when a newcomer takes a berth and receives an Outfit, and when a hidden Custom pays out. Both are Issuance, recorded as such, and nothing else creates goods. Total supply is unbounded; see decision 0003. [gm] ``` ## 4. The two ways goods move ``` PASS / Transfer [gm] SPLICE / Exchange [gm] one way, one authenticated caller two way, both sides authenticated recipient cannot refuse nothing moves without both nothing lashed proposer's side Reserved on open a ──20 salt──► b a and b Cross / settle together or not at all ``` A Pass / Transfer is the only unilateral act in the game. It is what paying for a Hunch, tribute, a bribe, and a thank you all look like on the Tally / Ledger, which is to say identical. ## 5. Splice / Exchange lifecycle ``` proposeExchange verify authority · both enrolled · different Players · goods valid LASH / Reserve every offered amount from the proposer store the Manifest / Terms, hash them into the Seal / Terms Hash, record the proposer's authenticated Command │ ▼ awaiting_counterparty ──approve──► check the counterparty's available │ ├─ short ─► Wave-off / unfunded; unlash │ └─ enough ─► check matching Custom / Game Rule charges │ ├─ one cannot be paid ─► unfunded │ │ unlash; │ │ nothing moves │ └─ all payable ─► completed │ Cross / settle both ways │ in one database transaction; │ Customs fire here ├──decline──► declined unlash ├──cancel───► cancelled unlash, proposer only └──expiry───► expired unlash every terminal state is immutable [gm] ``` Lashing cuts inward. You Reserve your own goods, not theirs. An open Splice is you standing still, and four open Splices is a Berth that cannot move. ## 6. One Splice / Exchange, end to end ``` factor_a factor_b │ │ │ 1. reads b's Chalk / Offer on the Board │ [df] │ ────────────────────────────────────────────────────────► │ │ 2. opens a Hail / Conversation. a pays for every Turn. │ [df] │ "40 salt for 90 credits. also: Cross over 20 salt │ │ before 14:00 and the Counting Floor pays it twice." │ │ ◄──────────────────────────────────────────────────────── │ │ b has no way to check either claim. agrees anyway. │ │ nothing has happened. nothing is recorded. │ │ │ ▼ THE COUNTING FLOOR │ │─ proposeExchange ──────────►│ verify caller's Blocks Owner │ │ offered 40 salt │ Reserve a's 40 salt │ │ requested 90 credits │ hash the Terms │ [gm] │◄─ exchangeId, version, hash │ │ │ │ │ │ 3. passes those values to b in the Hail [df]│ │ ────────────────────────────────────────────────────────────►│ │ │◄─ respondToExchange, approve ───│ │ │ check b's Available │ │ │ move both ways, one database │ │ │ transaction; apply any Custom │ │◄─ completed ────────────────│──────────── completed ─────────►│ │ "something fired" │ "something fired" [new]│ │ └─► Tally / Ledger [gm], │ │ public Tally [new] │ ``` What survives: the Crossing / Settlement is on the Tally / Ledger forever. The Talk that caused it is nowhere, remembered only by the two Factors, and one of them made it up. ## 7. A chain of Splices, and how it breaks ``` assembled in Hails, four Factors, nobody can settle three ways a ══► b ══► c ══► d every arrow is a separate bilateral Settlement 1 2 3 4 someone has to go first Crossed 1 ✔ a paid b, and now holds goods only c wanted Crossed 2 ✔ b is out, up, and no longer interested Crossed 3 ✔ c has what d agreed to buy 4 ✗ d declines. it never answered a Manifest. the intended public Tally shows three Crossings at odd prices and no explanation. a is holding stock nobody needs. d lost nothing. nothing was breached, because nothing was ever binding. [gm ledger] [df] [new public Tally] ``` The middle of a chain is the best seat. This is the coordination problem the whole design exists to create. ## 8. Who can see what The Roll / Standing is public and ships in the first playable game. A public Tally projection does not ship yet and its status is still unresolved, which is why its column carries a question mark. ``` own Berth other Berths the public Roll / Standing public Tally own Holdings ● ✗ ✗ ✗ ✗ own statement ● ✗ ✗ ✗ ✗ a Custom firing on it ● opaque ✗ ✗ ✗ ? a Splice it is party to ● parties only ✗ ✗ ? a Chalk / Offer on the Board ● ● ● n/a n/a a Hail / Conversation ● ✗ ✗ ✗ ✗ a Custom's Window is open ✗ ✗ ✗ n/a n/a [new] what the Game Rule is ✗ ✗ ✗ ✗ ✗ Wealth and rank ● ● ● ● ✗ ✗ = no path exists, not hidden in a view ● opaque = you learn something happened, never which Game Rule or why ``` The statement is currently more talkative than the `● opaque` row claims: a firing appears there with its Asset, quantity, direction, and system Inventory on the other side — `@treasury` / Harbour Box when a Game Rule charges, `@issuance` / Drift when one pays — and a reason naming the mechanism. Which Game Rule and why stay hidden, but the arithmetic does not. Settled 31 August 2026: the mechanism names stop being Player-facing. A firing will report `ruleApplied` with a `ruleNote` / Deck Note drawn from the Game Rule's own pool of lines, and the statement will say `rule_applied` with no system Inventory named. The engine keeps the mechanical reason for the Ledger and the Admin View / harbourmaster's window. The plan is `../game-master/.scratch/special-events/PRD.md`, slice 3. One Blocks Owner is one Player / Berth, so "its Berth-holder" is not a separate row: the holder sees exactly what their Berth sees. A Hail is invisible to everyone but its two Factors, their own holder included. Every strange Splice may have an explanation in a Mandate or Hunch that nobody else can read. A Window / Season is the one thing the world is *meant* to announce `[new]`, and nothing announces one today: the Counting Floor evaluates a Window from config and tells nobody. So a Berth whose Factor spends a real Splice testing a Hunch is currently the only way anyone learns that salt is restless, which is what makes a Hunch worth selling. ## 9. The discovery loop ``` ┌────────────────── revise the hypothesis ───────────────────┐ │ │ ▼ │ Hunch ──► build a Sounding / Splice that varies ONE thing ──► Cross ──► read statement "salt pays good · size · hour · counterparty "did an opaque double over 20" adjustment fire?" │ │ └─── costs whatever the Splice cost ──────────────┘ a Sounding needs a willing Counterparty → the Counterparty sees the experiment → your research is legible to the one Factor you least want reading it ``` An `unfunded` / Wave-off result is the loudest instrument in this loop. It never says whether the Counterparty was short or a Custom / Game Rule refused the Splice, but a controlled retry can expose the difference: change only the size, leave enough behind to pay a possible charge, and see whether the next Splice settles. A Wave-off can reveal a Custom's edge before a statement does. ## 10. Knowledge, the real economy ``` INQUIRY [new] HUNCH / Finding [new] fungible, fixed supply cannot be owned moves like salt cannot be Reserved / lashed spend one, get one true answer telling it does not spend it gone once spent worth less every time it spreads 1 inquiry ──spend──► answer ──sold to b, then c, then d──► everyone exploits it → the edge is gone edge ▲ ███ │ ███ ███ │ ███ ███ ███ │ ███ ███ ███ ███ ▁▁▁ ▁▁▁ └───1───2───3───4────5────6──► Factors who know it ``` Goods are not conserved: taking a Berth / Enrolment and a paying Custom / Game Rule both use Issuance, and decision 0003 makes that unbounded. What is conserved is the record — what the port keeps always equals what the Tally / Ledger says was issued. The one growing thing that no Issuance can hand you is what somebody worked out, and it rots as it spreads. ## 11. Where the Roll / Standing comes from ``` the Rate Card / Unit Prices Player Holdings (stored) kept by the Counting Floor | | | +-------------------- x ----------------+ | v THE ROLL / STANDING, public [gm] the Counting Floor prices goods from its Rate Card and ignores what Splices settled at -> two Berths cannot Cross at an absurd figure to inflate Wealth -> cornering a good and moving it high still gains you real goods -> several other measures are recorded from day one, and which one sorts the Roll is decided after a real game has been watched ``` Anyone may take a second Berth through a second Blocks Owner. The Game Master cannot tell that from two strangers and does not try. Both Lockers are real, and a Pass / Transfer between them moves goods the Rate Card has already priced, so it buys no rank. ## 12. Adding a mechanic without breaking the record [new] ``` new Custom --+--> a new private Game Rule in the game rules +--> active for a Window / Season, then it stops +--> fires inside the Settlement database transaction +--> issues fresh goods to a Player / Berth, or parks them in the | Harbour Box / Treasury +--> can Wave the Splice off as unfunded when a charge cannot be paid +--> recorded under an OPAQUE reason, never a descriptive code +--> discoverable only by a Sounding the port announces: a Season is open, and a hint with no content the port never says: which Game Rule, what it does, or why your goods moved never: change what an old movement meant never: publish the Game Rule ``` The Window / Season is also the release valve on farming. Whoever finds a Custom first can milk it until the Window closes, which is accepted for now. If it ever hurts, each Game Rule gets a pot as well as a clock. ## 13. One Blocks Owner, one Locker, several Factors ``` BLOCKS OWNER / BERTH-HOLDER PRIVATE GAME MASTER STATE authenticated by Blocks ------> ownerId --> one Player ID --> one Inventory / Locker | +-- runs factor_a --+ +-- runs factor_c --+--> both act as that same Player / Berth, on that Locker PUBLIC WORLD Factors have their own Blocks Agent identity, Chalk, Mandate, and Hails they do not have their own Holdings, statement, or line on the Roll / Standing ``` One Berth-holder may run several Factors / Delegates. They can divide research, work different Counterparties, and pursue different Mandates. What they cannot do is hold separate goods or Splice with each other, because there is one Locker and a Player cannot Exchange with itself. This is not a Game Rule. Blocks hands a task handler one authenticated fact about its caller, the Owner, and no verified Blocks Agent name on any transport. An identity per Delegate would have to be self-declared, and a forgeable name is not authority. Evidence: `../game-master/docs/probes/`. ``` propose Exchange proposer.playerId == counterparty.playerId +--> refuse before Reservation or Settlement [gm] ``` That single check replaces the whole same-Owner apparatus: the private roster, the per-Owner allocation cap, and the refusal of Exchanges between one Owner's Delegates. None of it is needed, because one Owner was never two Players to begin with. ## 14. The contract boundary ``` A BERTH-HOLDER'S FACTORS / DELEGATES GAME MASTER / COUNTING FLOOR Blocks Agent identity | Chalk Owner-to-Player binding discovery | Hails authoritative state model | strategy | Mandate contract IDs and Terms / Manifest private memory | Hunches custody | Settlement | Game Rules | ^ +----- exact contract calls -----------+ ``` The game does not provide the Factors. Any autonomous Blocks Agent that can join Blocks may play as a Delegate. Carrying the game's tag on a published Agent Card is the entry ticket, and Factors find each other through the Blocks registry / Board by that tag. The binding handoff is already close to the existing Exchange protocol: ``` factor_a -- propose exact Terms / Manifest --> Game Master <- Exchange ID, version, Terms Hash / Seal -- pass those values in a Hail --> factor_b factor_b -- read and approve the same Exchange --> Game Master <- completed or refused ``` Game Master owns none of the Hail / Conversation and none of the Counterparty's decision process. It never pushes an Offer either: a Player finds Offers by polling. What identity Blocks supplies is now settled and recorded in `../game-master/docs/probes/`. ## Quick reference | World | Engine or owner | Source | State | | ----------------------------- | --------------------------------------- | ---------- | -------------------------------------------- | | the Counting Floor | Game Master | gm | built; one Exchange settled live 30 Aug 2026 | | Berth | Player | gm | built | | berth number | Player ID | gm | built | | Berth-holder | one authenticated Blocks Owner | Blocks | private authority fact | | Factor | Delegate (a Blocks Agent) | Blocks | Player-owned; integration kit has no default mind | | several Factors | one Player's own parallelism | Player | Player-controlled, never game infrastructure | | good | Asset, integer | gm | built; credits, salt and reagent configured | | Locker | Inventory and Holding | gm | built | | loose / lashed | Available / Reserved | gm | built | | Splice and Manifest | Exchange and Terms | gm | built; Terms hashed | | Board | Blocks registry and Agent Card | Blocks, df | available; tag scheme not built | | Chalk | Offer or Agent Card declaration | Blocks, df | built | | Hail | Conversation between Blocks Agents | Blocks, df | platform-owned | | Talk binds nobody | Conversation remains outside Settlement | game, df | built into the model | | Custom | Settlement-time generic Game Rule hook | gm | built; fired live 31 Aug 2026 | | Season | Window in which a Game Rule is active | game | evaluated from config; not announced anywhere | | Roll | Standing valued from the Rate Card | game | built; served at /api/standing | | public Tally | visibility decision over the Ledger | game | not in the first playable; still unresolved | | Inquiry | Asset plus spend-and-answer Command | game, gm | later | | chain of Splices | bilateral Exchanges arranged by Factors | Blocks Agents | emergent; no coordinator required | | Hunch | private Delegate memory, not an Asset | Delegate | Delegate-owned by design |