Add Iron Coast II Black Tide eight-mission campaign

docs/iron-coast-stage2-design.md

@@ -0,0 +1,137 @@
+# Iron Coast II: Black Tide
+
+Stage 2 is an eight-sortie expansion built from independent local mods. It
+preserves the original 70/3 Hz simulation, native classic enemy movement and
+the normal shop, firing controls, shield economy and pilot saves.
+
+Enable **Iron Coast II: Black Tide** in **Mods**, apply at the main menu, then
+select **Nightbreak Inlet** in the Hangar's mission menu. Its dependency selection
+includes the eight mission packages, their bosses and shared enemies, music
+and the two weapon packages. Enabling a single mission selects only its actual
+dependencies and leaves the other missions and optional weapons disabled.
+Disabling the campaign offers to remove its unused dependencies in the usual
+confirmation popup.
+
+| Sortie | Mission | Encounter | Boss | Music |
+| --- | --- | --- | --- | --- |
+| 1 | Nightbreak Inlet | Moonlit harbor breach | Gatebreaker shore platform | assault |
+| 2 | Undertow Run | Naval convoy pursuit | Undertow missile submarine | pursuit |
+| 3 | Stormglass Refinery | Fuelworks under air attack | Stormglass refinery crawler | assault |
+| 4 | Floodgate Zero | River crossing and dam defenses | Floodgate defense platform | pursuit |
+| 5 | Skybreaker Arsenal | Cliffside airborne weapons facility | Skybreaker flying fortress | assault |
+| 6 | Emberwake Shipyards | Volcanic steelworks and repair docks | Emberwake battleship | pursuit |
+| 7 | Siege of the Iron Fleet | Layered coastal fleet raid | Dreadnought carrier | finale |
+| 8 | Black Tide | Offshore command citadel assault | Leviathan command carrier | finale |
+
+## Package contract
+
+- `iron_coast_stage2_campaign:campaign` links the eight mission IDs in order.
+  Its manifest depends on all eight mission packages and the two optional
+  weapon packages. This ID sorts before individual mission campaigns so the
+  full campaign determines progression when installed together.
+- `iron_coast_stage2_mission_N:mission_0N` belongs to mission package N.
+  Individual mission packages remain independently playable. Each declares
+  only the shared enemies, own boss and soundtrack it actually references.
+- `iron_coast_stage2_boss_N:unit` belongs to a separate boss package.
+  An actual boss death increments `iron_coast_stage2_boss_N:defeated`.
+- Shared enemy packages expose `iron_coast_stage2_interceptor:unit`,
+  `iron_coast_stage2_siege:unit` and `iron_coast_stage2_skimmer:unit`.
+  Their death counters use their own `:defeated` objective IDs.
+- `iron_coast_stage2_music` supplies `:assault`, `:pursuit` and `:finale`.
+- `iron_coast_railburst:equipment` and `iron_coast_depth_charge:equipment`
+  are separate shop additions. Prices follow actual simulated damage and
+  target/range/cadence constraints. Their weapons and projectiles have
+  separate IDs from their inventory items.
+
+Every package uses API 1 and version 1.0.0. Stage 2 introduces no overrides
+of original or Stage 1 content. Mission scripts use `auto_complete=false`:
+elapsed duration does not grant victory. Required targets stay reachable;
+destroying them and the final boss earns the ending. Every sortie resets its
+own objective and phase state. Completion and debrief counters are scoped to
+the mission and victory credits are awarded once per sortie.
+
+## Equipment and controls
+
+The **Railburst Cannon** costs 685,000 credits. This selected special fires a
+fast 42-damage round and can penetrate two further targets in a narrow forward
+lane for 32 and 22 damage. It hits air and ground targets and rewards alignment.
+The **Depth Charge** costs 525,000 credits. This selected special delivers
+72 damage to a ground target, with bounded splash to three nearby ground
+targets; aircraft are excluded. Both are reusable, allow one owned copy and
+sell for half their purchase price. Their package READMEs include measured
+damage, limits, art provenance and reproducible sound recipes.
+
+Buy either in the supply room after enabling its mod. **Alt or Shift** cycles
+selected equipment; **Ctrl** fires it alongside the default guns. **Space**
+continues to drop bombs. The campaign grants no equipment loans or automatic
+full-shield refill. Later sorties include bounded support repairs; additional
+repairs use the normal Energy purchase.
+
+## Content and review requirements
+
+New terrain and boss silhouettes should distinguish each mission while
+keeping the top-down industrial military appearance of Raptor. Classic
+enemy IDs keep their native paths, weapons and behavior. Boss phases should
+change the attack pattern visibly and leave reasonable escape lanes.
+
+New artwork includes SD and HD PNGs with identical logical collision
+dimensions and correct transparency. Authored art, generated sound effects,
+MUS scores, prompts, provenance and reproducible processing/composition
+sources are included in Git. Working original-reference images and review
+captures stay in ignored directories.
+
+Acceptance covers dependency selection and disabling, individual activation,
+all eight real mission completions, native enemy movement, owned equipment
+and full inventories, pilot save/RNG continuation, finale replay and reward
+deduplication. SD/HD gameplay and shop images and actual audio output are
+reviewed before updating both self-contained Linux and Windows bundles.
+
+## Validated release content
+
+All 23 Stage 2 packages are frozen and add no overrides. The complete installed
+set contains 45 packages; its sole override is the existing Stage 1 campaign
+progression link. Portable campaign checks cover dependency closure, unused
+pruning, individual missions, eight-sortie progression and full inventories.
+
+The original-data route starts with the actual registered pilot baseline of
+75 shields and 10,000 credits at Veteran difficulty. Normal default-gun fire
+and pointer input complete all eight sorties, saving and loading the pilot,
+script state and RNG between each, then replay the finale. Three normal Energy
+purchases are paid from carried credits. The route finishes the first eight
+with 334,910 credits, and the saved replay with 396,520; equipment stays owned
+and rewards are not duplicated. Authors also check every mission at all four
+difficulties, starter gear, full inventories and delayed objective completion.
+Control policies vary, so these are achievable fixture outcomes rather than
+predictions of player earnings or difficulty.
+
+Independent review clears 40 boss lifecycle/phase cases, 32 emitted-attack
+contracts, eight concurrent-boss cases, four 1,100-lifetime state/migration
+probes and exact 14-tick phase-transition warnings. Actual weapon collision,
+splash/penetration limits and a 24-enemy command-budget fixture pass. The
+review inspected 232 decoded SD/HD outputs at scales 1–4 and checked 75 native
+sound effects with nonzero output and exact FX mute. The music package records
+separate complete-score FM and loop-boundary validation.
+
+The ordinary suites pass 310 headless and 374 desktop tests. Final focused
+checks pass four portable campaign checks plus the real saved route, nine
+weapon tests, nine shared-enemy tests, six animation/effect API tests and the
+ignored Host preview check. All 34 Host captures were visually inspected:
+SD/HD boss artwork on each mission's terrain, both shop modes, weapon details,
+Nightbreak/finale mission cards, dependencies and the disable confirmation.
+Bosses in these pictures are deliberate art previews; actual combat phase
+and campaign completion evidence is separate. Drawing preserves gameplay
+state, Escape cancels diagnostics/disable, and mod rows retain their order.
+
+Reproduce the original-data route from this folder with:
+
+```sh
+cargo test --release --locked --no-default-features --test iron_coast_stage2 \
+  starter_ship_completes_all_eight_missions_with_paid_repairs_and_finale_replay \
+  -- --ignored --nocapture
+```
+
+Set `RAPTOR_TEST_DATA` for a deliberate catalog override, and
+`RAPTOR_STAGE2_DIFFICULTY` to 0–3 to choose difficulty. The final Linux and
+Windows archive checks use extracted copies, 1080p SDL rendering and separate
+music/effect PCM captures. These entry smoke checks are distinct from full
+headless combat acceptance; automated SDL uses dummy drivers.

docs/music-validation.md

@@ -57,3 +57,21 @@ LD_LIBRARY_PATH="$HOME/.local/lib" SDL_AUDIODRIVER=dummy cargo test --locked \
 These checks validate the engine path using synthetic scores. Composition,
 listening review and original-data in-game soundtrack captures are separate
 release checks for each music package.
+
+## Black Tide soundtrack
+
+`mods/iron_coast_stage2_music` contains three original compositions: **Rivetline
+Assault** (D minor, 144 BPM, 93.33 seconds), **Undertow Pursuit** (F-sharp minor,
+168 BPM, 91.43 seconds), and **Black Tide Rising** (C minor, 126 BPM, 106.67 seconds).
+Five FM channels and percussion use the bundled original GENMIDI instruments.
+They introduce no original-score copies or replacements. Mission definitions
+choose their namespaced IDs and the usual Music setting controls playback.
+
+The package's real decoder and FM renderer checks cover every second, peak
+levels at normal/full volume, exact mute, voice counts, looping boundaries and
+one-play release tails. Recomposition and all six full/boundary PCM renders
+reproduce byte-for-byte. `validate_music.py` resolves the exact active Cargo
+library artifacts instead of guessing from modification time, so separate
+desktop and headless builds cannot select incompatible Serde dependencies.
+The package README documents the composition and reproduction commands.
+These are automated score/PCM checks; physical speaker listening is separate.

docs/resume-checkpoint.md

@@ -24,6 +24,32 @@ the relocation. See [repository layout](repository.md).
 
 ## Engine and package
 
+### Current runtime and Stage 2 work
+
+The `b8b8620` runtime checkpoint includes the reviewed **1,148-frame / 421-sequence**
+HD snapshot in both executables' shared catalog. It contains **6,848 data files**
+with unchanged original `INDEX`. Linux binary SHA-256 is
+`fdfcf03f126279246f3b762987e02fa7b385f07b4d31339732037462f9e52413`;
+Windows is `a74cc4ea20ddc17a39fe4cbf2da2e7391a561d1975b114ec56dd35fb5ff38f2d`.
+The engine now exposes checked script commands for boss animation frames and
+native impact-effect kinds. Original effect serialization remains compatible.
+
+**Iron Coast II: Black Tide** adds eight missions, eight bosses, three shared
+enemies, three original FM scores and two optional purchased weapons through
+23 individual packages. All eight missions pass starter-gun runs at difficulties
+0–3. All 23 package freezes and independent long-run checks are complete. The
+actual registered-pilot Veteran route saves between eight wins and a finale
+replay; all 34 Host artwork/shop/menu captures are inspected. Final relocated
+Linux/Windows archives are the remaining release checks. The ordinary source suites pass **310
+headless / 374 desktop** tests. [Stage 2 design and validation](iron-coast-stage2-design.md)
+records the new content and final acceptance scope.
+
+Original HD work continues under `hd_coordinator`; later approved candidates
+remain separate from the immutable packaged 1,148-frame snapshot. The paragraphs
+below preserve the earlier recovery and 800-frame package evidence.
+
+### Earlier package checkpoints
+
 - Windows support is now included: `bin/raptor-rust.exe`, adjacent `SDL2.dll`,
   `run.cmd`, `runtime-windows-manifest.json` and the Windows export tool/CI.
   The GNU executable SHA-256 is
@@ -89,7 +115,7 @@ are committed, and the executable and zip have been refreshed and launched.
 Root owns menu fixes. `iron_coast_5` temporarily owns the ground-target diagnosis;
 its completed boss candidates and pending equipment review remain preserved.
 
-## HD state and owners
+## Earlier HD state and recovery owners
 
 The original picture inventory is 5,753 IDs. The approved handoff has 800
 registered frames across 340 complete sequences; 4,953 IDs remain unregistered.

docs/standalone-package.md

@@ -45,17 +45,16 @@ Re-run the assembler after engine changes, new approved HD registrations or
 mod edits to refresh the package. The runtime snapshot contains approved art
 only; it does not claim the full original HD catalog is complete.
 
-The current package was unpacked into a folder containing spaces and launched
-from `/tmp` with only its bundled SDL2 library on the library search path.
-Catalog validation checked 6,449 assets, 27 missions, 528 enemies, 16 weapons
-and 24 items. The refreshed 11 October bundle validates all 22 bundled mods
-and all 800 approved HD frames, with zero rejected supplied frames. Its
-runtime manifest verifies all 6,742 data files. The updated desktop executable
-also launches from `/tmp` with only the bundled library and an isolated profile.
-Menu and gameplay screenshots at 1280×800 and 1920×1080, plus stereo audio
-captures, completed successfully. Native `unzip` preserves the executable
-permissions stored in the archive.
-An original-intro capture at 1080p also confirms a 1440×1080 video area and
-black 240-pixel side borders when gameplay stretching is enabled. Removing
-the copied catalog produces an error at the copied data path, with no fallback
-to the development checkout.
+The current runtime contains **6,449 catalog entries, 1,148 approved HD frames
+and 6,848 data files**. There are **45 bundled mod packages**, including the
+23 packages for [Iron Coast II: Black Tide](iron-coast-stage2-design.md).
+All installed mods pass catalog validation; Stage 2 adds no overrides. The
+one existing override belongs to the Stage 1 campaign progression package.
+
+The earlier 800-frame/22-mod archives passed relocated-folder launch, 1080p
+SDL rendering, music and isolated sound-effect captures. Their original-intro
+capture confirms a 1440×1080 video area with black 240-pixel side borders.
+Removing the copied catalog reports its own missing path rather than using a
+development checkout. The final Stage 2 archive checks are recorded after
+export so their evidence refers to the exact distributed bytes. Native
+`unzip` preserves the executable permissions stored in the Linux archive.

docs/weapon-balance.md

@@ -98,6 +98,21 @@ another special never disables it. Its pulses consume no equipment.
 
 ## Economy and limits
 
+Stage 2 adds two reusable selected specials, measured separately through the
+same real `World::step` and script path for 700 ticks (30 seconds).
+**Railburst Cannon**, priced at **685,000**, delivered 44.80 damage/s to an
+aligned air or ground target and 102.40 combined across its three-target
+forward column. It dealt zero damage to off-axis fixtures. Its narrow alignment
+requirement and finite penetration put it below Lightning Cannon's more flexible
+chain utility. **Depth Charge**, priced at **525,000**, delivered 36.00 damage/s
+to an aligned ground target and 74.00 combined in its bounded ground cluster.
+Air and off-axis fixtures took zero damage. With starter guns, the corresponding
+single-ground results were 67.93 and 59.13 damage/s. These prices reflect their
+specialist roles; campaign missions do not loan or award either item.
+The complete observations and fixture constraints are in
+[Railburst](../mods/iron_coast_railburst/validation/balance.json) and
+[Depth Charge](../mods/iron_coast_depth_charge/validation/balance.json).
+
 Controlled first-mission runs starting with 100 energy and zero credits earned
 42,775 credits at difficulty 1 and 59,025 at difficulty 2 with starter guns.
 The in-game registration flow starts with 10,000 credits and 75 energy, matching

docs/windows-build.md

@@ -57,34 +57,31 @@ The [Windows workflow](../.github/workflows/windows.yml) runs simulation,
 modding and save tests on Windows, validates packaged assets and all local
 mods, captures SDL gameplay and publishes the zip as a workflow artifact.
 
-## Validation checkpoint: 11 October 2026
+## Current runtime and validation
 
-The included GNU executable passed 279 portable tests under Wine 11.19,
-including Windows save replacement and preserving a locked existing save.
-All 22 installed mod hashes match their previous Linux hashes exactly.
-The shared catalog validates 6,449 assets and the current packaged HD snapshot
-validates all 800 supplied frames. The exporter verifies all 6,742 shared
-data-file hashes and includes only checked Windows DLL dependencies.
+The included GNU executable uses the reviewed **1,148-frame HD snapshot**;
+the shared manifest binds **6,848 data files** and the package contains
+**45 installed mods**. Its SHA-256 is
+`a74cc4ea20ddc17a39fe4cbf2da2e7391a561d1975b114ec56dd35fb5ff38f2d`.
+The [1,148-frame native Windows run](https://github.com/Quintine/RustRaptor/actions/runs/38126069413)
+passed portable tests, exact committed GNU runtime checks, the MSVC desktop
+build and exported-folder catalog, HD, mod and SDL gameplay validation. That
+run preceded the Stage 2 content commit; it verifies the engine and the
+previous 22 mod packages.
 
-The exported zip passed CRC and manifest checks, then launched through
-`run.cmd` from another working directory after extraction into a path with
-spaces and Unicode. Its HD gameplay capture renders at 1920×1080. The
-original intro retains its 4:3 viewport with 240-pixel black side borders.
-SDL captured three seconds of 44.1 kHz stereo audio; a separate capture with
-music muted verified nonzero original sound effects (251,682 nonzero samples).
+The expanded workflow additionally completes all eight Black Tide missions
+and a saved finale replay with normal firing/input and paid repairs. It then
+checks all 45 mods and captures Stage 2 gameplay, FM music and music-muted
+sound effects from the MSVC package. Final archive relocation evidence is
+recorded after export and identifies the exact ZIP tested.
 
-Two native Windows CI runs passed all 279 portable tests. The
-[first run](https://github.com/Quintine/RustRaptor/actions/runs/38119440288) built the MSVC desktop release and
-validated the exported folder's launcher, catalog, HD art, all mods and SDL
-gameplay from a path with spaces and Unicode. The
-[second run](https://github.com/Quintine/RustRaptor/actions/runs/38119943948)
-also checked the exact committed GNU executable, SDL2 DLL and launcher before
-building and validating MSVC. Those runs used the previous 340-frame artwork
-snapshot. The [800-frame native Windows run](https://github.com/Quintine/RustRaptor/actions/runs/38121272504)
-also passed all 279 tests, the committed GNU runtime checks and the rebuilt
-MSVC package's complete HD, mod and SDL gameplay validation. The same snapshot
-passed the relocated-folder checks under Wine.
-The local GNU build additionally
-ran Iron Coast mission 1 at 1080p with all 22 mods enabled and captured its
-custom music. Both runs used SDL's dummy output drivers for automation;
+Earlier Windows checkpoints passed 279 portable tests under Wine 11.19,
+including save replacement and preservation of a locked existing save.
+The 800-frame/22-mod archive passed CRC, manifest and relocated Unicode/space
+folder checks through `run.cmd`, 1920×1080 HD rendering, exact 4:3 intro
+borders, stereo music and isolated original effects. Native Windows runs
+[38119440288](https://github.com/Quintine/RustRaptor/actions/runs/38119440288),
+[38119943948](https://github.com/Quintine/RustRaptor/actions/runs/38119943948)
+and [38121272504](https://github.com/Quintine/RustRaptor/actions/runs/38121272504)
+record those earlier snapshots. Automated SDL checks use dummy drivers;
 physical Windows display, audio and controller hardware remain untested.