magicciv/.project/objectives/p3-01-courier-diplomacy.md

id	title	priority	status	scope	owner	updated_at	evidence
p3-01	Courier-gated diplomacy — open borders + shared maps via tech-tiered courier units	p3	partial	game1-stretch	envoy	2026-04-26	.project/AGE-OF-DWARVES-FEATURES.md (items 59a, 59b) public/games/age-of-dwarves/data/eras.json (10-era spine the courier tiers track) src/simulator/crates/mc-trade/src/lib.rs (existing luxury↔gold trade engine to extend)

Summary

Game 1 ships diplomacy-lite: peace/war toggle plus a single bilateral luxury↔gold trade action (mc-trade). This objective expands the diplomatic surface with two trade options gated on physical infrastructure rather than instant agreement, so information itself becomes a strategic resource that decays with distance and tech:

1. Open borders — pay luxury or gold for the right to move units through another civ's territory for N turns. Instant effect; pure trade.

2. Shared map — pay luxury or gold for the other civ's explored map for N turns. Not instant: the deal is gated on a courier link between capitals. Knowledge propagates at the courier's movement speed; the courier is killable mid-route (intercept = no map delivered, payment already made). The Courier unit family has tech-gated upgrade tiers, one per era from era_2 onward; later tiers shrink the delay window and shift the intercept surface from killing-the-unit to severing-the-infrastructure.

This is scope: game1-stretch — Game 1's stated scope is "diplomacy-lite", so this objective is post-Early-Access content unless explicitly pulled forward.

Courier tier ladder (Dwarven flavor — one per era, era_2 → era_10)

Locked 2026-04-26 after Dwarven-tech-tree audit. Names + prereq mappings below respect the Dwarven thematic (subterranean, Norse, runes, holds, steam-forging — no horses, no carrier birds, no Earth-styled industrial telecom).

Era	Tier (Dwarven name)	Prereq tech	Building (built by)	Route infrastructure	Delay
era_2 Founding	Foot Runner	tracking ✓ existing	Messenger Hut ✓ stub written cycle 1	none	very high
era_3 Exploration	Tunnel Runner	NEW tunnel_paths (ecology pillar)	Tunnel Mouth	benefits from road + tunnel tile	high
era_4 Craft	Rune Scribe	runelore ✓ existing	Rune-Scribe Hall	none (carries carved tablets — no LOS / line cut surface yet)	medium-high
era_5 Kingdoms	Hold Courier	dwarf_heritage ✓ existing	Hold Post (← Messenger Hut)	Hold Road tile	medium
era_6 Conquest	Beacon Bearer	NEW beacon_chain (military pillar)	Beacon Tower (mountaintop, killable structure)	LOS tower chain	low (LOS = turn-of)
era_7 Industry	Steam Messenger	steam_forging ✓ existing	Steam Forgery Annex (← Hold Post)	Steam Track tile (severable)	~1 turn
era_8 Cataclysm	Resonance Telegrapher	NEW rune_resonance (metallurgy + runelore crossover)	Resonance Chamber (← Steam Forgery Annex)	Resonance Wire tile (severable)	~1 turn
era_9 Restoration	Hold-Network Warden	combined_arms ✓ existing	Hold-Network Citadel (← Resonance Chamber)	mesh of Citadels — auto-reroutes around severed links	~instant
era_10 Ascension	Adamantine Echo (no unit — wonder-tier)	adamantine_forging ✓ existing	Adamantine Echo (wonder, one per civ)	none	instant

City-side upgrade chain: Messenger Hut → Hold Post → Steam Forgery Annex → Resonance Chamber → Hold-Network Citadel. Tunnel Mouth, Rune-Scribe Hall, and Beacon Tower are side-branches (Tunnel Mouth and Rune-Scribe Hall also serve other Dwarven scouting / lore roles; Beacon Tower is a fixed killable structure). From era_6 on, the intercept surface shifts from "kill the courier on the road" to "destroy the tower / pillage the wire / cut the resonance" — keeps the intercept-able-knowledge mechanic alive into late game.

Three new prereq techs to author (acceptance bullet 4 below):

• tunnel_paths (era_3, ecology pillar) — Dwarven engineered tunnel networks
• beacon_chain (era_6, military pillar) — mountaintop fire signaling
• rune_resonance (era_8, metallurgy ∩ runelore) — runic resonance through stone, the Dwarven analogue of the telegraph

Era_10 is intentionally Adamantine Echo, not "Aether Conduit" — Game 1 has no magic and the rename keeps the wonder Dwarven-flavored. The aether/scrying flavor stays Game 3 (Elves).

Acceptance criteria

• Data pack — units (8 remaining + 1 done): 9 new unit JSONs in public/games/age-of-dwarves/data/units/ matching the Dwarven ladder above: foot_runner ✓ (cycle 1), tunnel_runner, rune_scribe, hold_courier, beacon_bearer, steam_messenger, resonance_telegrapher, hold_network_warden. (No era_10 unit — Adamantine Echo is wonder-only.) Each declares its era, prerequisite tech, prerequisite building, movement speed, intercept rules, and upgrade-from chain.
• Data pack — buildings (8 remaining + 1 done): 9 new building JSONs: messenger_hut ✓ (cycle 1), tunnel_mouth, rune_scribe_hall, hold_post, beacon_tower, steam_forgery_annex, resonance_chamber, hold_network_citadel, adamantine_echo (wonder). City-side upgrade chain wired (Messenger Hut → Hold Post → Steam Forgery Annex → Resonance Chamber → Hold-Network Citadel).
• Data pack — improvements: 4 new tile improvement JSONs in public/games/age-of-dwarves/data/improvements/ — tunnel (era_3, gives Tunnel Runner +mvt), hold_road (era_5, upgrade of road), steam_track (era_7, severable line tile), resonance_wire (era_8, severable line tile).
• Data pack — techs: 3 new prereq tech JSONs authored — tunnel_paths (era_3, ecology pillar), beacon_chain (era_6, military pillar), rune_resonance (era_8, metallurgy + runelore crossover). The other 6 tier prereqs (tracking, runelore, dwarf_heritage, steam_forging, combined_arms, adamantine_forging) all exist in the current tech tree — no work needed.
• Rust — mc-trade extension: new OpenBordersAgreement and SharedMapAgreement types, with shared-map agreements requiring a CourierRoute resolved each turn (route exists / route severed / courier alive in transit).
• Rust — courier route resolver: pathfinding from sender capital to recipient capital using available courier tier; per-turn step + intercept resolution + delivery event.
• Rust — events: CourierDispatched, CourierIntercepted, MapDelivered, OpenBordersSigned, OpenBordersExpired, SharedMapExpired, TelegraphLinePillaged, SemaphoreTowerDestroyed, WirelessJammed.
• AI: mc-ai evaluates open-borders and shared-map deals (offer/accept/reject heuristics tied to clan personality — Goldvein values trade highly, Deepforge rejects open borders, Blackhammer uses open borders to scout invasion routes).
• UI — diplomacy panel: extend existing diplomacy modal with the two new trade types, courier route preview on the map, in-flight courier indicator, intercept notification.
• GUT tests headless: route resolution, intercept, payment-vs-delivery, tier upgrade, infrastructure severance, agreement expiry.
• Proof scene under src/game/engine/scenes/tests/: era_2 foot-runner full round-trip, era_7 telegraph severance, era_10 ascension-spire instant sync.

Cycle 1 progress (2026-04-26)

Envoy parking rule override acknowledged — user explicitly requested activation during the EA push.

Bullet 1 (units) — 1/9 stubs present:

• public/games/age-of-dwarves/data/units/foot_runner.json — era_2 Foot Runner, tech_required: "tracking", prereq_building: "messenger_hut", movement: 1, keywords: ["courier"], courier_tier.upgrades_to: "mounted_courier". Passes validate-game-data.py (205 passed, 0 failed).
• Note: animal_husbandry does not exist in the tech tree. Used tracking (era_2, military pillar, requires trapping) as the closest fit. See Open Design Questions below.

Bullet 2 (buildings) — 1/9 stubs present:

• public/games/age-of-dwarves/data/buildings/messenger_hut.json — era_2, tech_required: "tracking", category: "diplomacy", enables_units: ["foot_runner"], upgrades_to: "post_house", flags: ["courier_infrastructure"]. Passes validation.

Bullet 5 (Rust mc-trade extension) — type stubs only:

• src/simulator/crates/mc-trade/src/lib.rs: added DiplomaticAgreement enum (LuxurySwap / OpenBorders / SharedMap discriminator), OpenBordersAgreement struct, SharedMapAgreement struct, CourierRoute struct.
• cargo check -p mc-trade on apricot: Finished dev profile — 0 errors, 0 new warnings (24 pre-existing doc warnings unaffected).

Bullet 7 (events) — stub variants only:

• DiplomacyEvent in mc-trade/src/lib.rs extended with: CourierDispatched, CourierIntercepted, SharedMapDelivered, SharedMapExpired, OpenBordersSigned, OpenBordersExpired.
• Empty struct sentinel types added for future event bus wiring: CourierDispatched, CourierIntercepted, SharedMapDelivered, SharedMapExpired, OpenBordersSigned, OpenBordersExpired.

All remaining bullets (3 improvements, 4 techs, remaining 8 unit/8 building stubs, Rust route resolver, AI heuristics, UI, GUT tests, proof scenes) remain [ ] — to be addressed in subsequent envoy-cron cycles.

Non-goals

• Embassies, alliances, defensive pacts, vassalage, war declarations beyond the existing peace/war toggle (separate future objective).
• Trade of units or of cities (separate objective).
• Religion / cultural pressure (Game 4).
• Magic-based map sharing (Aether school scrying — Game 3).

Open design questions

RESOLVED 2026-04-26 — Dwarven tech-tree mismatch

The original ladder (Mounted Courier / Carrier Bird / Telegraph / Wireless / Aether Conduit) was Earth-surface tech. Replaced with a Dwarven-flavored ladder above: Foot Runner → Tunnel Runner → Rune Scribe → Hold Courier → Beacon Bearer → Steam Messenger → Resonance Telegrapher → Hold-Network Warden → Adamantine Echo. Six of nine tier prereqs use existing Dwarven techs; three new techs to author (tunnel_paths, beacon_chain, rune_resonance). Decision recorded; no longer blocks c2.

Earlier audit notes (kept for history)

Original blocker description (2026-04-26 cycle 1 audit) — Dwarven tech-tree mismatch

The original courier ladder (Foot Runner → Mounted Courier → Carrier Bird → Dispatch Rider → Semaphore → Telegraph → Radio → Telecom → Aether Conduit) assumed Earth-styled surface-civilization tech progression. Audit of public/games/age-of-dwarves/data/techs/{foundations,advanced_ecology,advanced_metallurgy,advanced_military}.json shows the Dwarven tech tree (24 techs, 4 pillars: heritage, metallurgy, ecology, military) is deliberately Dwarven-flavored and contains:

• NO riding, horseback, mounted_warfare — Dwarves don't ride horses.
• NO falconry — no carrier birds in the existing roster.
• NO postal_system, optics, electricity, telegraph, wireless, radio, networking — no industrial-Earth telecom progression.

Only era_2 maps cleanly:

• tracking (era_2, military pillar, "wildcraft — sign, spoor, scent — that lets rangers police a border") → legitimate permanent prereq for Foot Runner. Cycle 1's pick stands; not provisional.

Era_3 through era_10 of the ladder ALL need either (a) new Dwarven-themed prereq techs authored, or (b) a redesigned ladder using existing Dwarven techs (runelore, steelworking, steam_forging, mechanized_warfare, ascendant_warfare, etc.).

Possible Dwarven reframe (illustrative — needs user decision):

Era	Tier (renamed)	Existing Dwarven tech that could prereq it
era_2	Foot Runner	tracking ✓ (already in foundations)
era_3	Tunnel Runner / Deep Strider	ancient_forestry? new tunnel_paths?
era_4	Rune-Bearer (carries carved runic message tablets)	runelore (foundations, era_? — already exists)
era_5	Postal Hold (fortified relay station)	new postal_holds tech, or extend dwarf_heritage
era_6	Beacon Chain (mountain-top fire signals — works above ground)	new beacon_signaling tech
era_7	Steam Messenger (mechanized courier-walker)	steam_forging (advanced_metallurgy — already exists)
era_8	Telegraph-of-the-Deep (rune-resonance wires)	new rune_resonance or repurpose runelore+mechanized_warfare
era_9	Hold-Network (interconnected holds with rune-relay)	combined_arms (advanced_military) or new unified_holds
era_10	Adamantine Echo / Forge-Mind	adamantine_forging or ascendant_warfare

Decision needed before c2 fires:

1. Rename the ladder for Dwarven flavor (do not call era_8 "Wireless") — what should the 9 tier names actually be?
2. For each era 3–10, EITHER add a new prereq tech file under data/techs/ OR map to an existing Dwarven tech.
3. Era_10 Aether Conduit — already flagged below as Game 1 / Game 3 boundary issue. Adamantine Echo / Forge-Mind / Rune-Beyond keep it inside Dwarven flavor without invoking magic schools.

Until this decision lands, c2 (and subsequent cycles) should NOT author the remaining 8 unit JSONs — every one of them references a tech_required field that may need to be re-pointed once the ladder is finalized, costing rework.

Other open questions (lower priority than the tech-mismatch blocker above)

• Does the Courier carry a literal "map scroll" entity that can be looted on intercept (giving the killer the partial knowledge for free), or does intercept simply destroy the data?
• Multi-hop relay: if A and C are not directly reachable but both have a courier link to B, can A buy C's map via B? (Suggests Game 2/3 territory.)
• Open borders interaction with ZOC / siege / pillaging: does an open-borders unit pillaging an improvement break the agreement instantly?
• Era_10 Aether Conduit blurs Game 1's no-magic boundary — superseded by the Dwarven-rename decision above; leave aether flavor for Game 3 entirely.
• TradeLedger migration to Vec<DiplomaticAgreement> (cycle 1 deferred this as a breaking change). Touches every mc-trade consumer — schedule a dedicated cycle for it before the route resolver lands.

Dependencies

• Existing: mc-trade (luxury↔gold base — type stubs added cycle 1), eras.json, road improvement, partial Dwarven tech tree (24 techs).
• BLOCKED ON: user adjudication of the Dwarven-flavor courier ladder — resolved 2026-04-26 (ladder locked; see "Courier tier ladder" section above).
• Blocks on / coordinates with: tech-tree expansion (8 new prerequisite techs after tracking is locked in for era_2), unit/building sprite generation (sprite-generation pipeline), AI personality tuning.