PATHFINDER — Gameplay Specification

Route Planning & Convoy Management Module — KN-86 Deckline Capability Module

Version 2.0 | April 2026 | Status: Engineering-Ready

CIPHER-LINE revision note (2026-04-24): Pathfinder’s Cipher voice — route commentary, hazard warnings, fuel observations, convoy status — renders on the CIPHER-LINE OLED, not the main 80×25 grid. Pacific Rim Dynamics’s third cart; the voice inherits Drift’s coordinate precision and adds logistics vocabulary. See the CIPHER-LINE Contributions section at the end. Canonical engine spec: docs/software/runtime/cipher-voice.md.

---

Mission Contributions

Mission Composition Grammar declaration — verb vocabulary, affinity tag set, and mission-contributions schema are defined in docs/plans/post-v0.1/2026-04-25-mission-composition-grammar.md §1–§3.

(mission-contributions
  :verbs (DELIVER OBSERVE DECIDE)
  :affinities (PHYSICAL MARITIME AERIAL))

Pathfinder is the launch library’s logistics/courier cart and the canonical multi-environment cart called out in addendum §2 Q2. Convoy execution from origin to destination satisfies DELIVER; threat-zone reading satisfies OBSERVE; route commitment under Phase-B time pressure satisfies DECIDE. Affinities span PHYSICAL (overland routes), MARITIME (port handoffs and coastal corridors), and AERIAL (drone-drop fuel caches and air-corridor traversal). Per addendum Q2, the flat list is intentional for v1; per-verb affinity sets remain a future option. Default biases.

---

Design Philosophy

PATHFINDER is not a resource management puzzle. It is a two-phase sport: turn-based strategic planning followed by real-time execution under dynamic pressure. The operator experiences the full lifecycle of a logistics operation: the calm where they design the perfect route, then the chaos where reality deviates and they must improvise.

The core tension is the collision between plan and reality. In Phase A (Planning), the operator has unlimited time to analyze the map, plot waypoints, allocate fuel and convoy resources, and pre-stage countermeasures. This is intellectual work. No pressure. In Phase B (Execution), the convoy moves in real-time. Road conditions change. Threat corridors activate. Fuel runs short. The operator cycles through an OODA loop every 3-5 seconds, making tactical decisions about speed, route diversions, and crisis response. The gap between what was planned and what actually happens IS the game.

PATHFINDER teaches the operator that no plan survives contact with the world, but a well-designed plan survives longer. An operator who learns to plan with redundancy (multiple waypoints, alternate routes, fuel buffers) executes Phase B with grace. An operator who plans rigidly fails catastrophically when the first threat appears.

The YM2149 is a real-time convoy health monitor: Voice 1 is the heartbeat of the convoy (strong hum = healthy, stuttering pulse = damaged). Voice 2 is route progress (steady rhythm = forward momentum, stuttering = obstacles). Voice 3 is environmental threat (silence = safe, rising dissonance = danger closing in). An expert operator can navigate Phase B with the screen off, using audio alone.

---

1. THE TWO-PHASE ARCHITECTURE

PATHFINDER’s unique design is the two-phase structure. This is not a single continuous gameplay loop. It is two distinct modes with completely different pacing and pressure profiles.

Phase A: The Planning Loop (Turn-Based, Relaxed)

Duration: 5-15 minutes (operator controls pacing)
Pressure: Zero. Unlimited thinking time.
Input Model: CAR/CDR to navigate map, CONS to link waypoints, numpad to place/adjust, EVAL to finalize.
Screen: Full procedural map showing cities (nodes), roads, threat zones, rivers, mountains.
Audio: Ambient soundscape (no urgency); YM2149 plays soft background tones (140Hz baseline).

The operator’s task in Phase A:

1. View the procedural map seeded by contract parameters (origin city, destination city, cargo type, distance, threat level).
2. Plot an origin point and destination point.
3. Design an intermediate route by placing waypoints (CAR to enter route planner, select waypoint location from menu or manual entry).
4. Allocate convoy resources: fuel allocation (more fuel = slower but safer; less fuel = faster but fragile), armor rating (higher armor = slower but survivable), speed tier (affects fuel burn and threat detection).
5. Pre-stage countermeasures: fuel caches (place at waypoints to extend range), safe houses (hide convoy from surveillance), supply drops (repair convoy damage), diplomatic passes (negotiate through controlled territory).
6. Review the complete plan and press EVAL to lock it. Phase B begins immediately.

Phase B: The Execution Loop (Real-Time, High Pressure)

Duration: 10-20 minutes (determined by plan and unforeseen events)
Pressure: Extreme. New threats appear; convoy health degrades; fuel countdown accelerates.
Input Model: numpad 8/2/4/6 to change speed (up/down) or navigate detours (left/right), EVAL to confirm route change, LAMBDA to take a risky shortcut, BACK to retreat (emergency abort).
Screen: Real-time convoy status (position on map, fuel remaining, damage level), next waypoint, active threats, time remaining.
Audio: Voice 1 = convoy heartbeat (rises as damage accumulates), Voice 2 = route progress rhythm, Voice 3 = threat proximity alarm.

---

2. PHASE A: PLANNING LOOP SPECIFICATION

OODA Timing

The Planning Loop is turn-locked but operator-paced:

• OBSERVE (5 seconds): Operator examines current map view, reads waypoint list, reviews threat zones, notes supply locations.
• ORIENT (3 seconds): Operator analyzes route options, calculates fuel requirements, estimates threat exposure.
• DECIDE (variable, 30-180 seconds): Operator commits to waypoint, allocates fuel, places countermeasures. The operator controls the pace; they can spend 30 seconds or 3 minutes deciding.
• ACT (1 second): Operator presses EVAL to confirm decision. System updates route visualization.

Menu context-gating:

• When cursor is positioned on map: CAR/CDR navigate cursor, numpad 8/2/4/6 move cursor, numpad 5 selects location.
• When in route planning mode: CAR confirms waypoint, CDR removes last waypoint, CONS links alternate route, EVAL locks final route.
• When viewing resource allocation screen: CAR/CDR scroll resource options, numpad 2/8 adjust values, EVAL confirms allocation.

Phase A transitions:

• To Phase A Route View: Press CAR when on map (enters waypoint placement mode).
• To resource allocation: Press numpad 0 (toggle map/resources view).
• To Phase B: Press EVAL when route is finalized (locks plan, begins Phase B execution).

Map Navigation

The operator navigates the procedural map using a cursor. The cursor movement is discrete (grid-based): each numpad press moves cursor by one city grid cell or one region.

• Numpad 8: Move cursor north.
• Numpad 2: Move cursor south.
• Numpad 4: Move cursor west.
• Numpad 6: Move cursor east.
• Numpad 5: Select current city/location under cursor as waypoint.

Diagonal movement (Phase A only, cursor navigation):

• Numpad 7: Move northwest.
• Numpad 9: Move northeast.
• Numpad 1: Move southwest.
• Numpad 3: Move southeast.

Reserved keys (Phase A):

• Numpad 7, 9, 1, 3: Available for diagonal cursor movement in map view. In Phase B, reserved for future tactical options (not yet implemented).

Additional Phase A controls:

• CAR (top-left): Enter route planning mode / confirm waypoint selection.
• CDR (top-center): Navigate previous waypoint / undo last waypoint placed.
• CONS (top-right): Create alternate route branch / link two waypoints directly.
• EVAL (bottom bar): Confirm final route and lock plan; transition to Phase B.
• QUOTE (side-left): Exit route planning, return to map view.
• LAMBDA (side-center): Quick-plan shortcut (auto-generate safe route based on threat level).
• BACK (side-right): Cancel current plan, restart route design.
• INFO: Show map legend + threat zone info + resource locations.

---

3. PHASE B: EXECUTION LOOP SPECIFICATION

Real-Time OODA Timing

The Execution Loop runs every 3-5 seconds (operator controls decision speed):

• OBSERVE (1s): Screen shows convoy status: fuel remaining, health %, cargo integrity, current waypoint, time remaining, active threat (if any).
• ORIENT (1s): YM2149 Voice 1 (health heartbeat), Voice 2 (progress rhythm), Voice 3 (threat alarm) provide multi-channel telemetry.
• DECIDE (1-2s): Operator chooses action: proceed as planned, adjust speed, divert route, activate countermeasure, or abort mission.
• ACT (0.5s): Keypress commits decision; screen updates; fuel/health/threat tick down.

Cycle timing scale:

• Early game (Threat 1-2): 5-second cycles (relaxed).
• Mid game (Threat 3-4): 3-4 second cycles (moderate pressure).
• Expert play (Threat 5-6): 1-2 second cycles (extreme pressure).

Operators learn to compress the DECIDE phase as they gain experience. Expert operators routinely press action keys within 1 second of observing a threat.

Phase B Key Mapping

Left Hand (14 function keys) — Phase B:

• CAR (top-left): Accelerate to Tier 3 speed (risky, high fuel cost, high threat exposure).
• CDR (top-center): Decelerate to Tier 1 speed (safe, fuel-efficient, low threat exposure).
• CONS (top-right): Switch to alternate route (if pre-planned in Phase A). Costs 1 turn to pivot.
• EVAL (bottom bar): Confirm current action / commit to decision / proceed as planned.
• QUOTE (side-left): Activate countermeasure (bribe checkpoint officer, military escort initiation, etc.). Requires countermeasure pre-purchased in Phase A.
• LAMBDA (side-center): Take risky shortcut (off-road, time-saving but dangerous). Roll 30% ambush chance per turn shortcut is active.
• BACK (side-right): Retreat / abort mission (emergency eject). Mission ends; payout reduced by 50%, reputation damage -1.
• INFO: Display detailed status screen (convoy health %, fuel remaining, cargo %, next waypoint, threat proximity, time remaining).
• LINK: Toggle link mode (if multi-vehicle convoy active; used to switch which vehicle operator is controlling).
• SYS: Access system menu (pause, load, settings). Not used during active contract execution.
• APPLY: Reserved for countermeasure selection menu (if multiple countermeasures available).

Right Hand (16 numpad keys) — Phase B:

• Numpad 8 (speed-up): Increase speed (duplicate CAR function).
• Numpad 2 (slow-down): Decrease speed (duplicate CDR function).
• Numpad 4 (detour-left): Deviate left from planned route. Adds 2 turns, -5 fuel cost (shorter route), but 40% chance new threat appears.
• Numpad 6 (detour-right): Deviate right from planned route. Adds 3 turns, -3 fuel cost, but 30% chance road is blocked.
• Numpad 7 (reserved): Future tactical option (not yet implemented).
• Numpad 9 (reserved): Future tactical option (not yet implemented).
• Numpad 1 (reserved): Future tactical option (not yet implemented).
• Numpad 3 (reserved): Future tactical option (not yet implemented).
• Numpad 5 (continue): Continue with current plan (no change). Procedurally generates next game state.
• Numpad 0 (info): Display convoy status / threat info (full telemetry).
• Numpad * (tactical): Enter tactical decision menu (if threat active). Shows threat type, location, consequences, and 5 numbered options (negotiate, fight, evade, retreat, countermeasure).
• Numpad / (abort): Emergency abort (same as BACK). Mission ends.

Phase B Decision Flow

Every 3-5 seconds, the game state advances:

1. Current state: Convoy is at waypoint N, traveling toward waypoint N+1. Health H%, fuel F units, time T turns remaining.
2. Procedural event generation: Roll for obstacle or threat.
   • 30% chance: No event (proceed as planned).
   • 20% chance: Obstacle event (bridge washout, road closure, weather).
   • 25% chance: Threat activation (pirate ambush, checkpoint, surveillance).
   • 15% chance: Resource event (fuel cache available, repair station, safe house).
   • 10% chance: Cascade event (multiple simultaneous threats).
3. Screen update: If event, display threat alert or obstacle notification.
4. Operator decision: Operator chooses action (within 3-5 seconds).
5. Consequence resolution: Update convoy state (fuel depletes, health changes, time advances).
6. Audio update: Voice 1/2/3 shift to reflect new state.
7. Repeat.

---

4. SYSTEM ONE: THE MAP

Procedural Topology

The map is a procedurally generated network of cities (nodes), roads (edges), and geographic hazards (rivers, mountains). The operator does not see the entire map at once. They see a regional view (10-15 cities) and the route they plotted.

Seeding parameters:

• Region: Asia (Hong Kong, Singapore, Mumbai, Shanghai, Bangkok, Manila, Hanoi, Yangon, etc.)
• Distance: 500 km - 5000 km (15-60 game turns at standard speed)
• Node density: 8-15 cities visible in operator’s current view
• Road types: Highway (fast, visible), back road (slower, less surveillance), water route (dangerous, only for coastal cities), mountain pass (slow, expensive fuel)
• Geographic hazards: Rivers (bridge required), mountains (slow passage), urban sprawl (speed restricted), coastal waters (pirate zones)

Procedural generation (deterministic):

Using Voronoi-seeded graph generation:

1. Seed LFSR with contract threat level + contract type + date.
2. Generate 15-20 Voronoi sites (city locations) across 2000×2000 km regional grid.
3. Connect cities with roads: direct highways between adjacent Voronoi regions, plus scenic routes and pass routes.
4. Assign road types based on regional characteristics.
5. Place geographic hazards: rivers at natural boundaries, mountains on rough terrain, urban sprawl around major cities.
6. Result: realistic regional logistics network with 3-5 primary routes and numerous alternates.

Fuel Calculation

Base consumption: 1 unit per turn (standard speed, highway).

Modifiers:

• Speed: Slow ×0.7, Normal ×1.0, Fast ×1.3.
• Road: Highway ×1.0, Back road ×1.2, Mountain pass ×1.5, Water ×1.8.
• Convoy weight: 5000 kg ×1.0, 10,000 kg ×1.1, 15,000 kg ×1.2.

Formula:

fuel_cost = turns_required × base_rate × speed_mod × road_mod × weight_mod

Planning guideline: Operator should allocate 1.5x calculated fuel as safety margin. A 13-turn route should plan 19-20 fuel units, leaving 2-turn buffer.

---

5. SYSTEM TWO: THE CONVOY

Convoy State Variables

Health (0-100%):

• Decreases on: damage events (ambush, collision, accident).
• Increases on: repair station use (costs credits + turns).
• At <50%: convoy becomes fragile (speed limited to Tier 2 max, acceleration penalties).
• At 0%: mission fails.

Fuel (0-X units):

• Depletes each turn based on speed and road type.
• At 0: convoy stalls, mission fails in 2 turns unless fuel cache activated.
• At <25%: fuel warning (audio alert).

Cargo Integrity (0-100%):

• Decreases on: confiscation (checkpoint), rough driving damage, environmental hazards.
• At 0: mission fails.
• At <50%: payout halved.

Speed Tier (1-3):

• Tier 1 (Slow): 0.7x fuel, +50% time, 0% threat exposure penalty.
• Tier 2 (Normal): 1.0x fuel, standard time, standard threat exposure.
• Tier 3 (Fast): 1.3x fuel, -30% time, +100% threat exposure.

Damage Model

Damage sources:

1. Speed-related accident: Tier 3 on mountain pass = 20% chance 10% damage per turn.
2. Pirate ambush: Armor rating determines survivability (Tier 1 armor = 100% damage, Tier 2 = 50%, Tier 3 = 25%).
3. Checkpoint confiscation: 50% base chance, reduced by bribe (20%) or diplomatic pass (0%).
4. Environmental hazard: River crossing failure = 50% damage, weather damage = 20-30% health reduction.
5. Fragmentation penalty: Multi-vehicle convoy separation = 20% damage per separated vehicle.

---

6. SYSTEM THREE: THREAT MODEL

Threat Types

Pirate Zone:

• Activation: Specific corridor regions, scheduled randomized availability.
• Trigger: Convoy enters at high speed (Tier 3).
• Consequence: 20-40% ambush chance.
• Mitigation: Slow down (Tier 1 = 0% detection), military escort (100% safe, 100 credits cost), stealth routing.
• Audio signature: Voice 3 rises sharply.

Military Checkpoint:

• Activation: Fixed location.
• Trigger: Convoy passes through; 50% inspection rate.
• Consequence: 30-50% cargo confiscation if inspected.
• Mitigation: Bribe (50 credits, 20% inspection), documents (100 credits, 0% inspection), divert (+2 turns).
• Audio signature: Voice 2 becomes irregular (administrative friction).

Surveillance Corridor:

• Activation: RF monitoring zone.
• Trigger: Tier 3 speed in corridor; alerts downstream checkpoints.
• Consequence: Doubled inspection rate at next checkpoint.
• Mitigation: Slow down, avoid, or diplomatic pass (75 credits).
• Audio signature: Voice 3 subtle hum (low-level threat).

Environmental Hazard:

• Bridge washout: Detour +3-5 turns or risky crossing (50% damage).
• Landslide: Blocks route; alternate required.
• Weather (monsoon): Slows roads ×1.2, increases fuel cost.
• Flooding: Monsoon + river crossing = 70% damage.
• Mitigation: Pre-planning with alternates, cargo waterproofing (50 credits).

Threat Escalation

• Threat 1-2 (Low): 0-1 threat zones active.
• Threat 3-4 (Medium): 2-3 threat zones active.
• Threat 5-6 (High): 3-5 threat zones active. Multiple simultaneous threats possible.

---

7. SYSTEM FOUR: SOUND DESIGN (YM2149 PSG)

YM2149 Register Assignments

Voice 1 (Convoy Health):

• Registers: R0/R1 (Tone Period A), R8 (Amplitude A).
• Base frequency (100% health): 400Hz (R0=0x7C, R1=0x01 in 12-bit period encoding).
• Damage descent: Each 10% damage = 20Hz decrease = ~period +7 ticks.
• Envelope: Steady (R13 attack/decay off). At <50% health, switch to envelope mode (R13=0x08, attack=2, sustain off, decay=6 = stuttering pulse effect).

Voice 2 (Route Progress):

• Registers: R2/R3 (Tone Period B), R9 (Amplitude B).
• Baseline (standard speed, highway): 2 Hz rhythm = period 4000 (~2Hz at 44.1kHz).
• Tier 1 (slow): period 8000 (1 Hz).
• Tier 3 (fast): period 2667 (3 Hz).
• Obstacle stuttering: Modulate period ±500 every 2 turns (creates irregularity).
• Envelope: Rhythmic gate envelope (R13=0x0A, decay=8 = regular pulse).

Voice 3 (Environmental Threat):

• Registers: R4/R5 (Tone Period C), R10 (Amplitude C).
• Baseline (safe): Silence or 220Hz pad (R4=0xF4, R5=0x0F sustain = very quiet baseline).
• Threat glissando: Pitch slides from 220Hz to threat pitch (600Hz checkpoint, 800Hz ambush, 500Hz surveillance) over 1-3 seconds.
• Polyphonic conflicts: Multiple threats = two pitches simultaneously using noise mixing (R6 noise generator = 0x08 adds dissonance).
• Envelope: Triggered ADSR (R13=0x0F, attack=4, decay=6, sustain=0, release=4).

Register Values (YM2149 Lookup Table)

Frequency to Period Mapping (12-bit tone periods):

400Hz → Period 0x007C (124)
380Hz → Period 0x0083 (131)
360Hz → Period 0x008B (139)
340Hz → Period 0x0095 (149)
320Hz → Period 0x00A0 (160)
300Hz → Period 0x00AC (172)
...
2800Hz (threat alarm) → Period 0x000D (13)
2000Hz (critical threat) → Period 0x0013 (19)
1200Hz → Period 0x001E (30)
800Hz → Period 0x002D (45)
600Hz → Period 0x003C (60)
500Hz → Period 0x0049 (73)
400Hz → Period 0x007C (124)
220Hz → Period 0x00F4 (244)

Amplitude Levels (R8, R9, R10: 0-15):

• 0-2: Silent or nearly inaudible (baseline pad).
• 3-5: Quiet (background).
• 6-9: Moderate (primary information).
• 10-13: Loud (warning).
• 14-15: Maximum (critical alarm).

Audio State Machine

Phase B Start:

• Voice 1: 400Hz (1 second opening tone), amp 12.
• Voice 2: 2Hz rhythm, amp 10, locks into steady pulse.
• Voice 3: 220Hz pad, amp 1 (silence).

Normal Execution (no threat):

• Voice 1: Steady at 400Hz, amp 10, regular envelope.
• Voice 2: Rhythm per speed tier (1-3Hz), amp 10, regular pulse envelope.
• Voice 3: Silence (amp 1).

Waypoint arrival:

• Voice 1: Triple pulse (3 quick beats), amp 12.
• Voice 2: Doubled rhythm tempo (6Hz burst), amp 12.
• Voice 3: Trill (220Hz → 600Hz → 220Hz, 1 second), amp 8.

Damage taken:

• Voice 1: Jump down 20Hz instantly, amp reduced to 8.
• Voice 2: Hiccup (rhythm breaks, resume), amp drops to 7.
• Voice 3: Spike up 200Hz, amp 12 (1 second alert).

Threat encounter (ambush/checkpoint approaching):

• All three voices activate simultaneously.
• Voice 1: Rises pitch (20Hz per second).
• Voice 2: Becomes erratic (period variance ±500).
• Voice 3: Dissonant cluster (mix 600Hz + 300Hz noise).

Fuel warning (<25% fuel):

• Voice 1: Stuttering pulse (envelope to 0x08 decay mode).
• Voice 2: Becomes irregular.
• Voice 3: Rises to 400Hz, amp 10.

Mission success (destination reached):

• All three voices resolve into major chord (C-E-G, periods 0x007C / 0x005D / 0x0044):
  • Voice 1: 400Hz (0x007C), amp 13.
  • Voice 2: 640Hz (0x005D), amp 13.
  • Voice 3: 800Hz (0x0044), amp 13.
• Sustained for 2 seconds. Resolving arpeggios (highest to lowest, 1-second sweep down).

Mission failure (fuel 0 / health 0):

• All voices cut to silence instantly.
• Voice 1 only: Descends rapidly from 400Hz to 100Hz (death tone), 1 second sweep.
• Complete silence follows.

---

8. CELL ARCHITECTURE

PATHFINDER’s cell types model the core data structures for route planning and convoy execution.

CELL_DEFINE(ROUTE_CELL)

CELL_DEFINE(ROUTE_CELL) {
    CellBase base;
    uint8_t num_waypoints;           /* 1–16 waypoints in route */
    uint16_t total_distance;         /* cumulative distance in km */
    uint8_t estimated_turns;         /* total turns estimated */
    uint8_t total_fuel_required;     /* sum of fuel across all segments */
    uint16_t total_cost;             /* sum of countermeasure costs in credits */
    uint8_t alternate_route_id;      /* reference to alternative ROUTE_CELL, 0 = none */
    uint8_t route_state;             /* 0=planning, 1=locked, 2=executing, 3=complete */
    uint8_t threat_exposure;         /* aggregate threat level (1-6) */
    uint8_t efficiency_score;        /* heuristic quality metric for scoring (0-100) */
    uint16_t payout_estimate;        /* estimated payout for this route */
    uint8_t reserved[12];
};

Size: ~40 bytes. Stores the complete planned route for Phase A and Phase B reference.

CELL_DEFINE(WAYPOINT_CELL)

CELL_DEFINE(WAYPOINT_CELL) {
    CellBase base;
    uint8_t waypoint_index;          /* sequential position in route (0-15) */
    uint8_t target_location_id;      /* which city this waypoint targets (0-255) */
    uint16_t waypoint_x_coord;       /* absolute map x coordinate */
    uint16_t waypoint_y_coord;       /* absolute map y coordinate */
    uint8_t fuel_allocated;          /* units of fuel budgeted for this segment (0-30) */
    uint8_t speed_tier;              /* 0=slow, 1=normal, 2=fast */
    uint8_t armor_rating;            /* 0=civilian, 1=light, 2=heavy */
    uint8_t countermeasure_flags;    /* bit flags: bribe(0), security(1), diplomatic(2), escape(3), waterproof(4) */
    uint8_t reserved_waypoint[8];
};

Size: ~28 bytes per waypoint. 16 waypoints = 448 bytes max (fits in cell pool).

CELL_DEFINE(CONVOY_CELL)

CELL_DEFINE(CONVOY_CELL) {
    CellBase base;
    uint8_t current_waypoint_index;  /* which waypoint convoy is traveling toward (0-15) */
    uint8_t position_on_segment;     /* 0-100 percentage progress toward next waypoint */
    uint8_t health;                  /* convoy health 0-100% */
    uint8_t fuel_remaining;          /* units remaining 0-30 */
    uint8_t cargo_integrity;         /* 0-100% */
    uint8_t speed_tier;              /* current speed (may differ from planned) */
    uint8_t damage_flags;            /* bit flags: ambush(0), accident(1), confiscation(2), water(3), fragmentation(4) */
    uint8_t threat_proximity;        /* closest active threat distance in turns (255 = none) */
    uint8_t current_turn;            /* absolute game turn counter (0-255) */
    uint8_t time_remaining;          /* turns until mission deadline (0-255) */
    uint16_t payout_accumulated;     /* credits earned so far (for incomplete multi-segment contracts) */
    uint16_t reputation_delta;       /* reputation change from this contract (signed) */
    uint8_t mission_state;           /* 0=planning, 1=executing, 2=success, 3=failure, 4=aborted */
    uint8_t reserved_convoy[8];
};

Size: ~34 bytes. Holds all live state during Phase B execution.

CELL_DEFINE(MAP_CELL)

CELL_DEFINE(MAP_CELL) {
    CellBase base;
    uint8_t location_id;             /* city identifier (0-255) */
    uint8_t threat_type;             /* 0=safe, 1=pirate_zone, 2=checkpoint, 3=surveillance, 4=weather, 5=war_zone */
    uint8_t supply_flags;            /* bit flags: fuel_cache(0), repair_station(1), safe_house(2), supply_drop(3) */
    uint16_t x_coord;                /* absolute map coordinates */
    uint16_t y_coord;
    uint8_t visited_flag;            /* operator has passed through in Phase B */
    uint8_t threat_intensity;        /* 1-6, determines damage magnitude */
    uint8_t activation_turn;         /* earliest turn threat becomes active (0=always active) */
    uint8_t reserved_map[8];
};

Size: ~22 bytes per city. 15 cities = 330 bytes.

CELL_DEFINE(EVENT_CELL)

CELL_DEFINE(EVENT_CELL) {
    CellBase base;
    uint8_t event_type;              /* 0=pirate_ambush, 1=checkpoint, 2=bridge_washout, 3=weather, 4=landslide, 5=surveillance */
    uint8_t activation_turn;         /* which turn event activates */
    uint8_t duration;                /* turns the event remains active */
    uint8_t location_id;             /* which city/segment is affected */
    uint8_t damage_amount;           /* health damage if caught (0-50) */
    uint8_t resolution_flags;        /* bit flags: bribe(0), military_escort(1), diplomatic_pass(2), speed_escape(3), alternate_route(4) */
    uint8_t threat_severity;         /* 1-5, determines audio intensity */
    uint8_t cargo_confiscation_pct;  /* 0-100, percent cargo lost if event resolves against operator */
    uint16_t event_seed;             /* LFSR seed for procedural event details */
    uint8_t reserved_event[8];
};

Size: ~24 bytes per active event. Typically 1-3 active per mission = 72 bytes.

CELL_DEFINE(SUPPLY_CELL)

CELL_DEFINE(SUPPLY_CELL) {
    CellBase base;
    uint8_t supply_type;             /* 0=fuel_cache, 1=repair_station, 2=safe_house, 3=supply_drop */
    uint8_t location_id;             /* city where supply is located */
    uint8_t capacity;                /* units available (fuel units, health recovery %, etc.) */
    uint8_t access_turn_range_min;   /* earliest turn supply is usable */
    uint8_t access_turn_range_max;   /* latest turn supply is usable (0=unlimited) */
    uint16_t cost;                   /* credits to use supply (0 if pre-purchased) */
    uint8_t used_flag;               /* supply has been consumed */
    uint8_t reserved_supply[8];
};

Size: ~20 bytes per supply. Typically 2-4 supplies per mission = 80 bytes.

Cell Pool Composition

Typical contract uses:

• ROUTE_CELL: 1 × 40 bytes = 40 bytes.
• WAYPOINT_CELL: 8 × 28 bytes = 224 bytes (avg 8 waypoints).
• CONVOY_CELL: 1 × 34 bytes = 34 bytes.
• MAP_CELL: 15 × 22 bytes = 330 bytes.
• EVENT_CELL: 2 × 24 bytes = 48 bytes (avg 2 active events).
• SUPPLY_CELL: 3 × 20 bytes = 60 bytes.

Total: ~736 bytes (fits comfortably in 4KB pool, leaving 3,200 bytes for firmware overhead and other cartridges).

---

9. HOT SWAP INTEGRATION

PATHFINDER is Phase 1 of the Supply Chain Sabotage campaign (PATHFINDER → ICE BREAKER → BLACK LEDGER).

Phase Chain Serialization Format

When Hot Swap occurs, the nOSh runtime serializes convoy state and route intelligence into the phase chain for the next cartridge to read.

Serialization structure (byte offsets from phase chain base):

Offset 0-19:   ROUTE_CELL data (20 bytes, complete route plan)
Offset 20-39:  CONVOY_CELL data (20 bytes, final convoy state)
Offset 40-49:  Destination coordinates (target network location seed for ICE BREAKER)
Offset 50-57:  Network seed (LFSR seed for ICE BREAKER procedural network generation)
Offset 58-67:  Mission payout breakdown (Phase 1 rewards, Phase 2 estimate, Phase 3 estimate)
Offset 68-73:  Operator reputation (8-bit value, 0-255)
Offset 74-79:  Economic fallout indicator (price changes triggered by supply disruption)
Offset 80-127: Reserved for future modules

Total serialized: 48 bytes committed to phase chain, 80 bytes reserved.

Campaign Flow

Phase 1 (PATHFINDER — 25-40 minutes):

• Objective: Execute supply delivery route while observing optimal moment to sabotage target network.
• Deliverable: Convoy reaches destination, delivers payload. Intelligence on target network location and access timing captured in route plan.
• Phase chain output: ROUTE_CELL + CONVOY_CELL + destination coordinates + network seed.
• Payout: 1,360 ¤ (40% of 3,400 campaign total).

Phase 2 (ICE BREAKER — 20-35 minutes):

• Objective: Intrude into target network (location from Phase 1 ROUTE_CELL). Compromise logistics systems.
• Input: Phase 1 destination coordinates (offset 40-49) generate network topology (offset 50-57 seed).
• Deliverable: Network sabotaged; financial impact calculated.
• Phase chain output: Sabotage coordinates, trace data, financial delta.
• Payout: 1,190 ¤ (35% of campaign).

Phase 3 (BLACK LEDGER — 15-25 minutes):

• Objective: Audit economic impact of Phase 1+2 sabotage. Quantify financial loss.
• Input: Phase 2 sabotage coordinates, financial impact data.
• Deliverable: Proof of sabotage (ledger corruption, transaction reversals).
• Phase chain output: Final payout calculation, reputation gain.
• Payout: 850 ¤ (25% of campaign).

Total Campaign: 3,400 ¤ + Rep +5 (if all phases successful, on-time).

Cross-Module Integration Examples

PATHFINDER + DRIFT:

• DRIFT cartridge loads with radio signal mapping.
• PATHFINDER Phase A displays signal corridors on map.
• Operator routes around surveillance hot spots (identified by DRIFT).
• Bonus: Routes avoiding DRIFT-identified surveillance gain +100 ¤ payout.

PATHFINDER + BLACK LEDGER:

• BLACK LEDGER provides commodity price data for delivery region.
• PATHFINDER contract payout varies by delivery location and time window (higher prices = higher payout).
• Operator uses BLACK LEDGER market data to optimize delivery timing.

---

10. MISSION TEMPLATES

PATHFINDER generates four primary contract types.

Contract Type 1: ROUTE OPTIMIZATION

Scenario: Transport cargo from A to B with minimum time/fuel/threat cost.

Duration: 15-30 turns
Threat Range: 1-2
Base Payout: 600-1400 ¤

Success conditions:

• Arrive within time window.
• Maintain cargo integrity (no confiscation, <25% damage).
• Minimize fuel overage.

Example: Hong Kong → Bangkok, 30 kg electronics, Threat 1, 30-turn window.

• Direct route: 15 turns, 18 fuel, passes through light pirate zone (avoidable by slowing).
• Scenic route: 18 turns, 14 fuel, safer but slower.
• Payout: 600 ¤ + time bonuses + cargo bonuses.

Contract Type 2: CONVOY MANAGEMENT

Scenario: Coordinate multi-vehicle convoy. Maintain synchronization at rendezvous points.

Duration: 20-35 turns
Threat Range: 2-3
Base Payout: 1000-2200 ¤

Mechanics:

• Synchronization target: All vehicles arrive within ±1 turn of rendezvous time.
• Cohesion bonus: ×1.3 payout if all vehicles synchronized.
• Fragmentation penalty: -20% health per separated vehicle.

Example: 3-vehicle convoy (Truck A fast, Armored B slow, Support C medium). Hong Kong → Port Authority, 50 tons cargo, Threat 2.

• Operator allocates speeds to sync arrival.
• Phase B: Monitor vehicle separation, adjust speeds to maintain formation.
• Payout: 1000 ¤ + 300 ¤ cohesion bonus (if synchronized) = 1300 ¤.

Contract Type 3: SUPPLY CHAIN COORDINATION

Scenario: Multi-stop delivery chain with time windows. Delays cascade (if Stop B late, subsequent stops shift later).

Duration: 30-50 turns
Threat Range: 2-4
Base Payout: 1200-3000 ¤

Cascade mechanic:

• Each stop has safe arrival window (e.g., 12-16 turns).
• Late arrival: subsequent windows shift later by same amount.
• Too many cascades: final stop becomes unreachable (window expires).

Example: 4-stop semiconductor supply chain. Hong Kong → Singapore → Bangkok → Manila → Hanoi.

• Operator plans delivery sequence and timing for all stops.
• Phase B: Execute deliveries on-time, adapt if threats appear.
• Payout: 1200 ¤ + on-time bonuses (×1.1 per stop, ×4 stops) = 1680 ¤.

Contract Type 4: THREAT EVASION

Scenario: Navigate heavily contested territory. Multiple simultaneous threats. Adapt in real-time.

Duration: 25-40 turns
Threat Range: 3-6
Base Payout: 1500-4000 ¤

Threat options:

• Fight (accept damage/confiscation).
• Evade (detour, costs time/fuel).
• Negotiate (bribe, costs credits).
• Escape (if security detail pre-purchased).
• Hack (if ICE BREAKER loaded, subcontract).

Example: War zone logistics. Port A → Port B, high-value cargo ($500,000 equivalent), Threat 5.

• Multiple threat zones (checkpoint, pirates, conflict).
• Operator pre-purchases security detail + diplomatic passes.
• Phase B: Navigate threats, use countermeasures strategically.
• Payout: 1500 ¤ + bonuses (speed, cargo integrity, threat evasion) = 2500 ¤.

---

11. SCREEN WIREFRAMES

Phase A: Route Planning Screen

╔════════════════════════════════════════════════════════════════════════════════╗
║ PATHFINDER — ROUTE PLANNING                                               [Rep] ║
╠════════════════════════════════════════════════════════════════════════════════╣
║                                                                                 ║
║   HONG KONG ═══════════════════════════════════════════════BANGKOK (DEST)     ║
║   (START)                                                                       ║
║                                                                                 ║
║        ┌─────────────────────────────────────────────┐                        ║
║        │                                             │                        ║
║        │  @ HK  ·GZ    ·HN  LAOS  ·BKK              │                        ║
║        │                                             │                        ║
║        │  PLANNED ROUTE:                            │                        ║
║        │  1. Hong Kong (start)                      │                        ║
║        │  2. Guangzhou (2 turns, highway)           │                        ║
║        │  3. Hunan (4 turns, back road)             │                        ║
║        │  4. Laos (3 turns, mountain pass)          │                        ║
║        │  5. Bangkok (2 turns, highway)             │                        ║
║        │                                             │                        ║
║        │  TOTALS: 11 turns | 13 fuel | 0 cost       │                        ║
║        │  SAFETY BUFFER: 2 turns fuel (acceptable)  │                        ║
║        │                                             │                        ║
║        └─────────────────────────────────────────────┘                        ║
║                                                                                 ║
║ THREAT ZONES ON MAP:  🛑 Checkpoint (turn 10)  💀 Pirate (turn 6-8)          ║
║ [CAR] Enter route | [CONS] Alternate | [EVAL] Lock plan | [INFO] Details      ║
╚════════════════════════════════════════════════════════════════════════════════╝

Phase B: Execution Screen (Normal State)

╔════════════════════════════════════════════════════════════════════════════════╗
║ PATHFINDER — REAL-TIME EXECUTION                             [Turn 7 of 18]  ║
╠════════════════════════════════════════════════════════════════════════════════╣
║                                                                                 ║
║  CONVOY STATUS:                 NEXT WAYPOINT:       THREAT ASSESSMENT:       ║
║  Health:        [████████░░░] 78%    Guangzhou        Distance: 2 turns       ║
║  Fuel:          [██████░░░░░░] 6/15    Progress: 60%    Proximity: Far        ║
║  Cargo:         [████████████] 100%    Distance: 80km   Status: CLEAR         ║
║  Speed:         NORMAL (Tier 2)        ETA: Turn 8       Alert Level: GREEN   ║
║                                                                                 ║
║  MAP VIEW:                                                                      ║
║  Hong Kong ━━━━━━ [CONVOY] ━━ Guangzhou ···· Hunan ···· Laos ···· Bangkok    ║
║                          ↑                                                     ║
║                    (Turn 7 position)                                           ║
║                                                                                 ║
║  TIME REMAINING: 12 turns (buffer: +4 turns)                                   ║
║  Payout (if successful): 680 ¤                                                 ║
║                                                                                 ║
║ [CAR] Speed up | [CDR] Slow | [CONS] Alternate | [EVAL] Continue | [INFO] Details
╚════════════════════════════════════════════════════════════════════════════════╝

Phase B: Threat Alert Screen

╔════════════════════════════════════════════════════════════════════════════════╗
║ ALERT: MILITARY CHECKPOINT DETECTED                                            ║
╠════════════════════════════════════════════════════════════════════════════════╣
║                                                                                 ║
║  CHECKPOINT LOCATION: Guangzhou (Turn 8)                                       ║
║  THREAT TYPE: Cargo inspection authority                                       ║
║  SEVERITY: MODERATE                                                            ║
║  CONSEQUENCES OF DISCOVERY: 50% cargo confiscation (fine: 1500 ¤)             ║
║                                                                                 ║
║  AVAILABLE OPTIONS:                                                            ║
║    [1] Proceed normally (50% inspection chance)                                ║
║    [2] Bribe officer (costs 50 credits, 20% inspection chance)                 ║
║    [3] Use diplomatic pass (costs 100 credits, no inspection)                  ║
║    [4] Divert around checkpoint (adds 2 turns, avoids entirely)                ║
║    [5] Abort mission (emergency retreat, payout -50%)                          ║
║                                                                                 ║
║  OPERATOR DECISION:  [Press 1-5]                                              ║
║                                                                                 ║
║  TIMER: 5 seconds                                                              ║
║                                                                                 ║
╚════════════════════════════════════════════════════════════════════════════════╝

Phase B: Mission Complete Screen

╔════════════════════════════════════════════════════════════════════════════════╗
║ MISSION COMPLETE: HONG KONG ↔ BANGKOK DELIVERY                                ║
╠════════════════════════════════════════════════════════════════════════════════╣
║                                                                                 ║
║  ROUTE SUMMARY:                                                                ║
║    Distance traveled: 320 km                                                   ║
║    Time elapsed: 14 turns (16-turn target, +2 turns early)                     ║
║    Fuel consumed: 11 units (13-unit allocation, +2 units remaining)            ║
║    Threats encountered: 1 checkpoint, 1 pirate ambush (avoided)                ║
║    Cargo delivered: 30 kg electronics, 100% integrity                          ║
║                                                                                 ║
║  PAYOUT BREAKDOWN:                                                             ║
║    Base contract payout:               600 ¤                                   ║
║    On-time bonus (2 turns early):    +  80 ¤                                   ║
║    Cargo integrity bonus (100%):     +   0 ¤                                   ║
║    Fuel efficiency bonus:            +  20 ¤                                   ║
║    Threat evasion bonus:             +  30 ¤                                   ║
║                                        ─────────                               ║
║    TOTAL PAYOUT:                       730 ¤                                   ║
║    REPUTATION GAIN:                      +1                                    ║
║                                                                                 ║
║  CIPHER DEBRIEF:                                                               ║
║    "Route planned well. Threat assessment accurate. Operator handled           ║
║     ambush avoidance correctly. Recommend Threat 2 contracts next."            ║
║                                                                                 ║
║                               [Continue / Load / Quit]                         ║
║                                                                                 ║
╚════════════════════════════════════════════════════════════════════════════════╝

---

12. SESSION WALKTHROUGH: THE SUPPLY RUN

Operator: CIPHER | Reputation: 5 | Threat tolerance: Medium

Contract offered: “MEDICAL SUPPLY DELIVERY: Hong Kong → Bangkok. 30 kg pharmaceutical cargo. Threat Level 3 (pirate zone active turns 6-12). Time window: 30 turns (flexible). Payout: 600-900 ¤ depending on execution quality.”

Operator decision: Accept. Begin Phase A.

PHASE A: Planning (8 minutes elapsed)

TURN 1-2 (0:00-1:00 | OBSERVE/ORIENT):

• Operator views procedural map. Hong Kong (start) and Bangkok (destination) are shown.
• Visible regions: Hong Kong, Guangzhou, Hunan, Laos, Bangkok.
• Threat zones: Pirate zone (red shading) around Malacca Strait equivalent (turns 6-12).
• Supply cache: Port at Guangzhou (turn 2) offers fuel refill (20 credits).
• Operator notes: “Direct route passes through pirate zone. Can divert north through Laos (slower, safer) or use pirate zone + armor mitigation (faster, risky).”

TURN 3-4 (1:00-2:30 | DECIDE):

• Operator chooses direct route (faster) + armor strategy.
• Calculates: Direct route = 15 turns, 18 fuel needed, passes through pirate zone.
• Allocation: Tier 2 speed (normal), Armor Tier 2 (light armor), fuel allocation = 20 units (2-unit buffer).
• Countermeasures: Purchases security detail (100 credits) for pirate zone segment.
• Phase A cost: 100 credits (security detail). Net credits remaining: 900 (from starting reputation 5 = 5 × 100 credits).

TURN 5 (2:30-3:00 | ACT/ROUTE FINALIZATION):

• Operator finalizes route and countermeasures.
• Route locked: Hong Kong → Guangzhou (2 turns) → Hunan (4 turns) → Laos (3 turns) → Bangkok (2 turns).
• Fuel budgeted: 20 units (18 base + 2 buffer).
• Armor: Tier 2 (light, 10% slower, 50% damage reduction on ambush).
• Speed: Tier 2 (normal, 1.0x fuel modifier).
• Countermeasures: Security detail active for turns 6-12 (pirate zone protection).
• PHASE A COMPLETE. Press EVAL to lock and transition to Phase B.

Operator presses EVAL. Phase B begins.

PHASE B: Execution (30 minutes elapsed, turns 1-18 game time)

TURN 1 (0:00-0:05 | Departure):

• Screen state:
  • Convoy position: Hong Kong (starting).
  • Health: 100%, Fuel: 20/20, Cargo: 100%, Speed: Tier 2.
  • Next waypoint: Guangzhou (turn 2).
  • Threat proximity: None detected.
• Audio state:
  • Voice 1: 400Hz opening tone (1 second, strong).
  • Voice 2: 2Hz rhythm locked in (steady).
  • Voice 3: Silence (safe start).
• Operator action: INFO (check initial status).
• Result: Confirmation tone. Convoy begins movement.

TURN 2 (0:05-0:10 | Waypoint 1 — Guangzhou arrival):

• Screen state:
  • Convoy position: 50% progress toward Guangzhou.
  • Fuel depleted: 19/20 (1 unit consumed per turn, standard speed).
  • No threats.
• Audio state:
  • Voice 1: 400Hz steady (health stable).
  • Voice 2: 2Hz rhythm continues.
  • Voice 3: Silence.
• Operator action: EVAL (continue as planned).
• Result: Convoy progresses. No decision required; auto-advance.

TURN 3 (0:10-0:15 | Waypoint 1 — Guangzhou arrival):

• Screen state:
  • Convoy reaches Guangzhou.
  • Fuel cache available (offers +3 fuel for 20 credits). Operator pre-purchased security detail, so budget is tight. Skip refill.
  • Fuel remaining: 18/20.
  • Next waypoint: Hunan (turn 4-6, +3 turns).
• Audio state:
  • Voice 1: Triple pulse (3 beats, waypoint arrival celebration).
  • Voice 2: Doubled rhythm (6Hz burst, celebration).
  • Voice 3: Trill (220Hz → 600Hz → 220Hz, success tone).
• Operator action: EVAL (continue).
• Result: Convoy departs Guangzhou toward Hunan.

TURN 4-5 (0:15-0:30 | En route to Hunan):

• Screen state:
  • Convoy progressing toward Hunan.
  • Fuel depleting: 17/20 → 16/20 per turn.
  • No obstacles.
• Audio state:
  • Voice 1: 400Hz steady.
  • Voice 2: 2Hz rhythm.
  • Voice 3: Silence.
• Operator actions: EVAL × 2 (continue as planned).
• Result: Standard execution. No complications.

TURN 6 (0:30-0:35 | Pirate zone entry):

• Screen state:
  • Convoy approaching Hunan.
  • ALERT: Pirate zone detected (turns 6-12). Security detail active. Threat status: NEUTRALIZED.
  • Health: 100%, Fuel: 15/20, Cargo: 100%.
• Audio state:
  • Voice 1: 400Hz steady (security detail is protecting, no threat spike).
  • Voice 2: 2Hz rhythm stable.
  • Voice 3: Faint hum (low-level awareness, but not alarming due to security).
• Operator observation: Security detail is working. Pirate zone is present but neutralized.
• Operator action: EVAL (continue as planned, confidence in security detail).
• Result: Convoy continues through pirate zone unharmed.

TURN 7 (0:35-0:40 | Waypoint 2 — Hunan arrival):

• Screen state:
  • Convoy reaches Hunan.
  • Fuel remaining: 14/20.
  • Next waypoint: Laos (turns 7-10, +3 turns via mountain pass).
• Audio state:
  • Voice 1: Triple pulse (waypoint celebration).
  • Voice 2: Doubled rhythm.
  • Voice 3: Trill.
• Operator action: EVAL (continue).
• Result: Convoy departs toward Laos.

TURN 8 (0:40-0:45 | Pirate zone, mid-zone passage):

• Screen state:
  • Convoy still in pirate zone (continues through turn 12).
  • Security detail status: ACTIVE.
  • Fuel: 13/20.
• Audio state:
  • Voice 1: 400Hz (steady, protected).
  • Voice 2: 2Hz (steady progress).
  • Voice 3: Quiet hum (awareness, but not threat).
• Operator action: EVAL (continue).
• Result: Pirate zone passage continues safely.

TURN 9 (0:45-0:50 | Pirate zone, approaching Laos):

• Screen state:
  • Convoy 70% toward Laos.
  • Fuel: 12/20.
  • Pirate zone still active.
• Audio state:
  • Voice 1: 400Hz (stable).
  • Voice 2: 2Hz.
  • Voice 3: Silence (security detail is reliable).
• Operator action: EVAL (continue).
• Result: Progress steady.

TURN 10 (0:50-0:55 | Waypoint 3 — Laos arrival):

• Screen state:
  • Convoy reaches Laos border.
  • Pirate zone ends (turn 12, but Laos is beyond typical pirate range).
  • Fuel: 11/20.
  • Next waypoint: Bangkok (turns 10-13, +2 turns via highway, exiting pirate zone).
• Audio state:
  • Voice 1: Triple pulse.
  • Voice 2: Doubled rhythm.
  • Voice 3: Trill (relief tone as pirate zone is navigated).
• Operator action: EVAL (continue toward Bangkok).
• Result: Convoy exits pirate zone. Security detail was successful.

TURN 11-12 (0:55-1:10 | En route to Bangkok, post-pirate zone):

• Screen state:
  • Convoy progressing toward Bangkok via highway.
  • Fuel: 10/20 → 9/20.
  • No threats. Safe passage.
• Audio state:
  • Voice 1: 400Hz (normal, damage-free).
  • Voice 2: 2Hz (normal speed).
  • Voice 3: Silence (safe zone).
• Operator actions: EVAL × 2 (continue).
• Result: Straightforward execution.

TURN 13 (1:10-1:15 | Waypoint 4 — Bangkok arrival):

• Screen state:
  • Convoy reaches Bangkok (destination).
  • Final fuel: 8/20 (well above zero, buffer maintained).
  • Cargo integrity: 100% (no damage, no confiscation).
  • Time: Turn 13 of 30-turn window (17 turns early, massive time bonus).
  • Health: 100% (no damage taken).
• Audio state:
  • All three voices resolve into major chord (C-E-G), 2-second sustained resolution.
  • Victory tone (rising arpeggio), complete success.
• Operator observation: Mission complete. All objectives met.

PHASE B: Debrief

Mission Summary:

• Route: 11 turns planned, 13 turns executed (within plan).
• Fuel: 18 units planned, 12 units consumed (6-unit buffer remaining).
• Threats: Pirate zone (neutralized by security detail, 0 damage).
• Cargo: 100% integrity (no loss, no confiscation).
• Time: 30-turn window, completed in 13 turns (17 turns early).

Payout Calculation:

• Base contract payout: 600 ¤
• Time bonus (17 turns early, base 3 ¤/turn): +51 ¤
• Cargo integrity bonus (100%, no reduction): +0 ¤ (already perfect)
• Fuel efficiency bonus (6 units remaining out of 20, 30% saved): +20 ¤
• Threat evasion bonus (pirate zone navigated without casualty): +30 ¤
• TOTAL PAYOUT: 701 ¤

Reputation Gain: +1 (successful Threat 3 contract, appropriate difficulty for Rep 5 operator).

Cipher Debrief: “Operator executed planned route flawlessly. Security detail application was optimal; alternative (diversion) would have added time and cost. Fuel buffer maintained appropriately. Threat assessment was accurate. Recommend progression to Threat 4 contracts or multi-vehicle convoy (Contract Type 2) to increase complexity. Well done.”

Net Operator State:

• Credits: 900 - 100 (security detail) + 701 (payout) = 1501 ¤.
• Reputation: 5 + 1 = 6.
• Next contract available: Threat 4 or Threat 3 variant (multi-vehicle or supply chain).

---

13. DESIGN NOTES

Why Two Phases?

The split between Phase A (planning) and Phase B (execution) reflects a real design truth: logistics planning is intellectual work; logistics execution is reactive work. Separating them teaches the operator that good design creates space for improvisation.

Why the YM2149 is Mechanical, Not Cosmetic

The three-voice PSG provides real information (health, progress, threat) that an operator can interpret without looking at the screen. This is not an accessibility feature — it is the primary information channel for expert players. Speedrunners navigate Threat 4 contracts with the screen off, using sound alone.

Why Hot Swap Matters

The multi-phase campaign structure (PATHFINDER → ICE BREAKER → BLACK LEDGER) teaches an important lesson: specialized tools are more powerful together than apart. An operator who owns three cartridges can approach a mixed-threat contract with three different capability sets. An operator with only one cartridge must solve all problems within its domain.

Why Cell Architecture is Complete

Every cell type includes explicit field sizes and memory layout. This is not documentation flourish — it is engineering specification. A C11 programmer should be able to read these definitions and immediately begin implementation without asking clarifying questions.

---

APPENDIX A: PROCEDURAL GENERATION PARAMETERS

LFSR Seed Construction

Seed = (threat_level << 8) | (contract_type << 4) | (date_day mod 16)

Example: Threat 3, Type 1 (ROUTE OPTIMIZATION), April 11 → seed = (3 << 8) | (1 << 4) | 11 = 0x031B.

Same seed = same map (deterministic; contracts are replayable).

Threat Level to Zone Count

• Threat 1-2: 0-1 active zones.
• Threat 3-4: 2-3 active zones.
• Threat 5-6: 3-5 active zones.

Distance to Turn Estimate

• 500 km = 15 turns.
• 1000 km = 30 turns.
• 2000 km = 60 turns.

(Linear approximation: distance_km / 33 = turns_estimate).

---

13. DETAILED SCREEN LAYOUTS

All screens fit 80 columns × 25 rows. Row 0 = header. Rows 1–23 = content. Row 24 = action bar.

Screen 1: Phase A — Route Planning Map View

ROW 0: PATHFINDER > ROUTE PLANNER                    [Rep: 6] [Credits: 1200]
ROW 1:
ROW 2:     HONG KONG (START) ═════════ BANGKOK (DESTINATION)
ROW 3:
ROW 4:         ┌─────────────────────────────────────────────┐
ROW 5:         │  @HK  ·GZ    ·HN      ·BKK                 │
ROW 6:         │                                             │
ROW 7:         │  PLANNED ROUTE (click waypoints):          │
ROW 8:         │  1. Hong Kong (START)                      │
ROW 9:         │  2. Guangzhou (2 turns, highway)           │
ROW 10:        │  3. Hunan (4 turns, back road)             │
ROW 11:        │  4. Laos (3 turns, mountain pass)         │
ROW 12:        │  5. Bangkok (2 turns, highway)            │
ROW 13:        │                                             │
ROW 14:        │  TOTALS: 11 turns | 13 fuel | 100 cr      │
ROW 15:        │  SAFETY BUFFER: +2 turns (acceptable)     │
ROW 16:        │                                             │
ROW 17:        └─────────────────────────────────────────────┘
ROW 18:
ROW 19: THREAT ZONES ON MAP:  🛑 Checkpoint (Guangzhou, turn 8)
ROW 20:                        💀 Pirate zone (turns 6–12, central corridor)
ROW 21:
ROW 22:  [CAR=edit route] [CONS=alternate] [INFO=threats] [EVAL=lock & start]
ROW 23: PATHFINDER MISSION BOARD | ROUTE PLANNED | READY FOR PHASE B | Rep: 6

Screen 2: Phase A — Resource Allocation

ROW 0: PATHFINDER > RESOURCE ALLOCATION               [Phase A Setup]
ROW 1:
ROW 2: FUEL ALLOCATION (Route requires 13 units base)
ROW 3: ┌─────────────────────────────────────────────────────┐
ROW 4: │ Allocation: ████████░░░░░░░░░░ 20 / 30 units      │
ROW 5: │ Strategy: Safety buffer +7 units (recommended)      │
ROW 6: │ Cost: 0 ¤ (fuel is allocated, not purchased)       │
ROW 7: └─────────────────────────────────────────────────────┘
ROW 8:
ROW 9: ARMOR RATING (affects damage mitigation)
ROW 10: [ ] Civilian (none)     — Saves fuel, zero protection
ROW 11: [>] Light (Tier 2)      — 50% damage reduction, -10% fuel cost
ROW 12: [ ] Heavy (Tier 3)      — 75% damage reduction, -20% fuel cost
ROW 13:
ROW 14: COUNTERMEASURES (Optional, purchased with credits)
ROW 15: [ ] Security detail (protect pirate zone) ......... 100 ¤
ROW 16: [ ] Diplomatic pass (checkpoint clearance) ........ 100 ¤
ROW 17: [ ] Fuel cache (extend range, placed at waypoint) .  20 ¤
ROW 18: [>] Cargo waterproofing (monsoon protection) ...... 50 ¤
ROW 19:
ROW 20: COST SUMMARY:
ROW 21: Armor Tier 2: 0 ¤ (inherent), Countermeasures: 150 ¤, Total: 150 ¤
ROW 22: Credits remaining: 1200 − 150 = 1050 ¤
ROW 23:  [CDR=prev option] [CAR=select] [INFO=details] [EVAL=confirm & lock]

Screen 3: Phase B — Real-Time Execution (Normal State)

ROW 0: PATHFINDER — REAL-TIME EXECUTION               [Turn 7 of 30] [Threat 2]
ROW 1:
ROW 2: CONVOY STATUS:                 NEXT WAYPOINT:       THREAT ZONE AHEAD:
ROW 3: Health:        [████████░░] 85%  Guangzhou           Status: CLEAR
ROW 4: Fuel:          [██████░░░░] 7/20  Distance: 40 km     Distance: 2 turns
ROW 5: Cargo:         [████████████] 100% Progress: 60%       Alert Level: GREEN
ROW 6: Speed:         TIER 2 (Normal)    ETA: Turn 8
ROW 7:
ROW 8: ROUTE MAP (linear progress):
ROW 9: HK ━━━━━━ [CONVOY @ Turn 7] ━━ GZ ···· HN ···· Laos ···· BKK
ROW 10:                        ↑
ROW 11:                   Current position
ROW 12:
ROW 13: SPEED CONTROL:
ROW 14: [1] SLOW (Tier 1) — fuel ×0.7, +50% time, no threat exposure
ROW 15: [2] NORMAL (Tier 2) — fuel ×1.0, standard time, standard threat
ROW 16: [3] FAST (Tier 3) — fuel ×1.3, −30% time, +100% threat exposure
ROW 17:
ROW 18: TIME REMAINING: 23 turns (buffer: +23 turns beyond 7 base)
ROW 19: PAYOUT (if successful): 680 ¤
ROW 20:
ROW 21: AUDIO FEEDBACK: Voice 1 heartbeat 400Hz (health OK), Voice 2 steady rhythm
ROW 22:  [CAR=speed up] [CDR=slow down] [CONS=detour] [EVAL=continue] [INFO=detail]
ROW 23: CONVOY EXECUTING PLAN | WAYPOINT 1→2 | TRACE: 18/50 | Rep: 6

Screen 4: Phase B — Threat Alert (Checkpoint)

ROW 0: ALERT: MILITARY CHECKPOINT DETECTED              [Turn 8 of 30] [MODERATE]
ROW 1:
ROW 2: ⚠ ⚠ ⚠  CHECKPOINT DETECTED AHEAD (Guangzhou)  ⚠ ⚠ ⚠
ROW 3:
ROW 4: CHECKPOINT PROFILE:
ROW 5:  Type: Military vehicle inspection point
ROW 6:  Location: Guangzhou (turn 8 arrival)
ROW 7:  Inspection rate: 50% base chance (higher if detected)
ROW 8:  Consequence if inspected: 50% cargo confiscation (~250 ¤ loss)
ROW 9:  Fine: 1500 ¤ additional if contraband suspected
ROW 10:
ROW 11: YOUR OPTIONS (ranked by safety):
ROW 12:  [1] USE DIPLOMATIC PASS (costs 100 ¤, pre-purchased) — 0% inspection
ROW 13:       → Safe passage, no delays, no cargo risk
ROW 14:
ROW 15:  [2] BRIBE OFFICER (costs 50 ¤, on-the-spot) — 20% inspection
ROW 16:       → Reduced inspection chance, quick passage
ROW 17:
ROW 18:  [3] PROCEED NORMALLY — 50% inspection chance
ROW 19:       → Accept risk, save credits, proceed forward
ROW 20:
ROW 21:  [4] DETOUR AROUND (adds 2 turns) — 0% inspection
ROW 22:       → Safe but costly in time (reduces speedrun bonus)
ROW 23:  [1/2/3/4: select option] [INFO=detailed analysis]

Screen 5: Phase B — Waypoint Arrival & Supply Cache

ROW 0: PATHFINDER > WAYPOINT: GUANGZHOU                    [Turn 8 of 30]
ROW 1:
ROW 2: ╔════════════════════════════════════════════════════════════╗
ROW 3: ║              WAYPOINT REACHED: GUANGZHOU                   ║
ROW 4: ╚════════════════════════════════════════════════════════════╝
ROW 5:
ROW 6: CONVOY STATUS AT WAYPOINT:
ROW 7:  Health: 85%, Fuel: 7/20, Cargo: 100%
ROW 8:  Time elapsed: 8 turns (on pace, no delays)
ROW 9:
ROW 10: SUPPLIES AVAILABLE AT THIS LOCATION:
ROW 11:  ✓ Fuel cache (costs 20 ¤) — +3 fuel units, refill to 10/20
ROW 12:     → Helpful: Current fuel would be tight (need 6 more units to Bangkok)
ROW 13:  ✓ Repair station (costs 100 ¤) — restore +15% health
ROW 14:     → Not urgent: Health at 85% is acceptable
ROW 15:  ✓ Safe house (costs 50 ¤) — hide from surveillance 3 turns
ROW 16:     → Not needed: Pirate zone doesn't start until turn 6
ROW 17:
ROW 18: THREAT ZONES AHEAD:
ROW 19:  • Pirate zone active turns 6–12 (starts next turn!)
ROW 20:  • Security detail active and protecting (purchased in Phase A)
ROW 21:
ROW 22:  [1=fuel cache] [2=repair] [3=safe house] [0=skip] [EVAL=continue]
ROW 23: WAYPOINT STOP | SUPPLIES AVAILABLE | PIRATE ZONE IMMINENT | Rep: 6

Screen 6: Phase B — Threat Escalation (Pirate Ambush)

ROW 0: ALERT: PIRATE AMBUSH DETECTED!                    [Turn 10 of 30]
ROW 1:
ROW 2: ⚠ ⚠ ⚠  PIRATE ZONE: AMBUSH INCOMING (3 TURNS)  ⚠ ⚠ ⚠
ROW 3:
ROW 4: THREAT SEVERITY: HIGH (Threat 2 contract)
ROW 5: Pirate group: ~8–12 lightly-armed vessels
ROW 6: Interception time: 3 turns (turn 13 impact)
ROW 7: Your security detail status: ACTIVE (purchased, protecting)
ROW 8:
ROW 9: IMPACT ANALYSIS (if ambush succeeds):
ROW 10:  Health damage: 30% (with light armor: 15% after mitigation)
ROW 11:  Cargo confiscation: 25% (~125 ¤ loss)
ROW 12:  Time lost: 2 turns (detour to evade)
ROW 13:
ROW 14: YOUR OPTIONS:
ROW 15:  [CAR] MAINTAIN COURSE — Trust security detail, accept risk
ROW 16:       Security will intercept pirates 80% of time (pre-purchased)
ROW 17:
ROW 18:  [CDR] DETOUR AROUND — Add 2 turns, avoid pirate zone entirely
ROW 19:       Cost: Time (delays final arrival)
ROW 20:
ROW 21:  [CONS] EMERGENCY ABORT — Retreat now (50% payout, rep −1)
ROW 22:       Not recommended; you're 60% through the mission
ROW 23:  [CAR=maintain] [CDR=detour] [CONS=abort] [INFO=security detail]

Screen 7: Phase B — Mission Complete

ROW 0: PATHFINDER > MISSION COMPLETE
ROW 1:
ROW 2: ROUTE DELIVERY: HONG KONG → BANGKOK
ROW 3: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ROW 4:
ROW 5: EXECUTION SUMMARY:
ROW 6:  Distance traveled: 320 km
ROW 7:  Time elapsed: 14 turns (30-turn target, −16 turns EARLY)
ROW 8:  Fuel consumed: 11 units (allocated 20, +9 buffer remaining)
ROW 9:  Threats encountered: 1 checkpoint (diplomat pass used), 1 pirate
ROW 10:  Pirate ambush: DEFLECTED (security detail succeeded)
ROW 11:  Cargo delivered: 100% integrity (no confiscation, no damage)
ROW 12:  Health remaining: 83% (minimal damage exposure)
ROW 13:
ROW 14: PAYOUT BREAKDOWN:
ROW 15:  Base contract payout:               680 ¤
ROW 16:  Speedrun bonus (−16 turns early):  +80 ¤
ROW 17:  Cargo integrity (100%):            +0 ¤  (already perfect)
ROW 18:  Fuel efficiency (9 units saved):   +20 ¤
ROW 19:  Threat evasion (ambush averted):   +30 ¤
ROW 20:  ─────────────────────────────────────────────
ROW 21:  TOTAL PAYOUT:                      810 ¤
ROW 22:  REPUTATION GAIN:                    +1 → Total: 7
ROW 23:  [EVAL=next mission] [BACK=board] [SYS=save/exit]

Screen 8: Phase A — Threat Zone Visualization

ROW 0: PATHFINDER > THREAT ASSESSMENT MAP               [Phase A Setup]
ROW 1:
ROW 2: REGIONAL THREAT ZONES (showing planned route)
ROW 3:
ROW 4:    ZONE 1: PIRATE CORRIDOR        ZONE 2: MILITARY CHECKPOINT
ROW 5:    ┌─────────────────────┐        ┌──────────────────────┐
ROW 6:    │ Active turns: 6–12  │        │ Location: Guangzhou  │
ROW 7:    │ Threat rating: 2/5  │        │ Inspection rate: 50% │
ROW 8:    │ Evasion: Armor +50% │        │ Evasion: Bribe/docs  │
ROW 9:    │        or Detour    │        │ Avoidance: Detour    │
ROW 10:   │        or Security  │        │ Impact: 0–50% cargo  │
ROW 11:   │ Impact: 15–30% dmg  │        │ Cost: 50–100 ¤      │
ROW 12:   └─────────────────────┘        └──────────────────────┘
ROW 13:
ROW 14: ZONE 3: WEATHER ZONE            RECOMMENDED STRATEGY
ROW 15: ┌─────────────────────┐        ┌──────────────────────┐
ROW 16: │ Active turns: 15–25 │        │ Route: Direct via HK │
ROW 17: │ Type: Monsoon/flood │        │ Speed: Tier 2 normal │
ROW 18: │ Evasion: Waterproof │        │ Armor: Light (Tier 2)│
ROW 19: │         or Detour   │        │ Defenses: Security   │
ROW 20: │ Impact: 20–50% dmg  │        │ Countermeasures: 3   │
ROW 21: │ Cost: 50 ¤ waterproof        │ Total cost: 150 ¤   │
ROW 22: └─────────────────────┘        └──────────────────────┘
ROW 23:  [INFO=detailed threat] [EVAL=accept & plan] [BACK=return]

---

END OF SPECIFICATION

---

CIPHER-LINE Contributions

Pathfinder voice: dispatch controller tracking a convoy across hostile terrain. Clipped logistics dialect.

Vocabulary Pools

(:subject       "convoy" "fuel" "road" "waypoint" "leader"
                "tail" "checkpoint" "ambush" "weather")
(:object        "buffer" "reserve" "link" "corridor" "bridge")
(:location      "segment" "corridor" "pass" "ridge" "waypoint")
(:verb-present  "holds" "rolls" "burns" "stalls" "bunches"
                "stretches" "crests")
(:verb-past-participle "lost" "held" "cleared" "routed" "burned"
                       "missed")
(:memory-keyword "corridor" "pass" "ambush" "buffer" "bridge")
(:affect-word   "thin" "heavy" "late" "clean" "watched")

Production Fragments

(:mode-observe
  (3 (:subject) ". " (:affect-word) ".")
  (2 (:location) " " (:verb-present) ".")
  (1 "fuel " (:synthfence/direction) "."))

(:mode-annotate
  (3 "convoy " (:affect-word) ".")
  (1 "buffer thin.")
  (1 "late on the pass."))

(:mode-reflect
  (3 "same pass. " (:memory-fragment))
  (2 "this bridge. " (:memory-fragment)))

(:mode-drift
  (2 "the ambush nobody planned for.")
  (1 "the cold night at the ridge."))

:event-types
  ((:type :waypoint-cleared  :affect (:routine))
   (:type :fuel-low          :affect (:tense))
   (:type :route-diverted    :affect (:significant))
   (:type :ambush-triggered  :affect (:tense :anomalous)))

Mode-Weight Biases

Beat	observe	annotate	reflect	drift	silent
:mission-brief (planning phase)	—	+0.05	+0.05	—	—
:active-hack (execution)	+0.10	—	—	—	+0.05
:high-tense (ambush)	—	—	—	—	+0.15

Planning-phase beat leans reflective (looking at the map pulls memories). Execution is terser.

Structurally Important Moments Preserved on CIPHER-LINE

Beat	Intent	CIPHER-LINE fragment(s)
Plan accepted	”Route locked. Convoy staging.”	route locked.
Waypoint cleared	”Checkpoint reached. Fuel adequate.”	cleared. fuel ok.
Fuel low	”Reserve fuel. 40% remaining.”	fuel low. (tense)
Ambush	”Hostile convoy ahead. Divert.”	ambush. then divert.
Convoy delivered	”Convoy arrived. Cargo intact.”	arrived. intact. (debrief)

---

nEmacs Contributions

Per ADR-0016 (nEmacs + REPL + Input Model), each cart declares what its scripted-mission surface looks like — grammar fragments contributed to the predictive palette, domain vocabulary that earns the +5 ranking boost (ADR-0016 §7), whether it uses prompt-text for raw text entry (§8), and whether any of its keys bind :double-tap or :long-press events (§9). Pathfinder’s two-phase structure (Planning + Execution) makes it a moderate scripting candidate — Phase A (unlimited time, intellectual work) is a natural fit for Lisp route authoring, even though Phase B stays primitive-orchestration.

Scripted Missions?

Maybe — route-planning scripting. Phase A can be expressed in Lisp as a sequence of waypoint + resource allocations; Rep-10+ operators unlock Convoy Doctrine bounties that reward this. Phase B (execution) is real-time and stays primitive-orchestration — you can’t pause to edit mid-ambush. Scripted missions remain optional on the critical path (ADR-0002).

Typical scripted-mission shapes:

• (route-plan (:waypoint A) (:waypoint B) (:fuel-buffer 0.20)) — Phase A plan.
• (on-threat-corridor (divert-to :alternate)) — Phase B reactive handler.
• (convoy-loadout :fuel 80 :countermeasures 2) — staging helper.

Cart Grammar Fragments

Contributed via (emacs-extend-grammar ...) at cart-load:

(emacs-extend-grammar
  ;; Map primitives
  (map)
  (cell               (coord))
  (terrain            (coord))
  (hazard             (coord))
  (threat-corridor    (region))
  (fuel-depot         (coord))
  ;; Convoy state
  (convoy)
  (fuel-remaining)
  (cargo-manifest)
  (convoy-speed)
  (health              (vehicle-id))
  ;; Phase A — planning
  (route-plan         (&rest waypoints))
  (waypoint           (coord &key :pause))
  (alternate-route    (from to))
  (fuel-buffer        (fraction))
  (stage-at           (coord))
  ;; Phase B — execution (read-only + reactive)
  (current-position)
  (distance-to        (waypoint))
  (on-threat-corridor (&body handler))
  (on-fuel-low        (&body handler))
  (on-ambush          (&body handler))
  (divert-to          (coord)))

Vocabulary Contribution

Via (emacs-extend-vocabulary ...). Logistics / convoy / route terms:

(emacs-extend-vocabulary
  "route" "plan" "waypoint" "checkpoint" "leg"
  "convoy" "vehicle" "escort" "lead" "trail"
  "fuel" "depot" "reserve" "buffer" "range"
  "cargo" "manifest" "intact" "damaged" "lost"
  "terrain" "road" "off-road" "bridge" "pass"
  "hazard" "threat" "corridor" "ambush" "interdict"
  "divert" "alternate" "reroute" "detour"
  "speed" "tempo" "pace" "rest" "stage"
  "delivery" "arrival" "dispatch" "return")

prompt-text FFI Usage

No. Waypoint selection is coordinate-based (numpad); convoy loadout is menu-driven. Pathfinder declares nothing via prompt-text. Mission / contract names come from the cart catalog.

Double-Tap and Long-Press Bindings

Pathfinder opts into ADR-0016 §9 on keys that benefit from drill-down during Phase A planning (Phase B is too fast for multi-level bindings):

Key	:tap	:double-tap	:long-press
INFO	show-cell-info	show-route-plan — overlay full plan on map	show-alternate-routes — rendering of A/B/C plans
CAR	drill-into-terrain	—	—
CONS	add-waypoint	—	show-waypoint-chain
EVAL	commit-plan (Phase A) / commit-action (Phase B)	—	—
QUOTE	flag-hazard	mark-threat-corridor	—

Row 24 renders: INFO:CELL INFO²:PLAN INFO…:ALT CAR:DRILL CONS:WAYPT EVAL:COMMIT QUOTE:FLAG.

Context-Polymorphic Key Semantics (Cart Gameplay)

Pathfinder has two primary cursor contexts matching its two phases: planning view (Phase A) and execution view (Phase B):

Key	Planning view	Execution view
INFO	show-cell-info	show-convoy-status
CAR	drill-into-terrain	(unused — no drill-down mid-run)
CDR	next-waypoint	next-event
CONS	add-waypoint	acknowledge-event
EVAL	commit-plan	commit-action (divert / press-on)
QUOTE	flag-hazard	flag-event
BACK	exit-planner	pause (Cipher goes silent, map freezes)
Numpad	coordinate entry	route-option select

When the operator opens nEmacs during Phase A, dispatch yields to :nemacs-nav per ADR-0016 §3 — standard editor dispatch. Phase B is real-time; the cart does not enter nEmacs from Phase B by default (the operator must pause first).