Integrate radio-delivered convoy cover and conservative squad ammunition reports

docs/hq-ammunition.md

@@ -0,0 +1,112 @@
+# Delivered HQ small-arms ammunition reports
+
+The current addition reports physical small-arms ammunition through the existing
+formation status uplink and lets HQ withhold a new armed infantry task when a
+fresh, complete report proves the squad empty. It is not general resupply,
+convoy rearming, ammunition manufacture or an urgent refill-request system.
+A controlled native radio/inventory run is recorded below; multiplayer and resupply remain unqualified.
+
+## What the local sampler observes
+
+[StatusSampler](../addons/ai/Scripts/Game/ERR/ERR_HQStatusSampler.c) enumerates the
+same immutable original roster used for casualty accounting. Each living,
+still-owned member contributes to an
+[AmmoSnapshot](../addons/ai/Scripts/Game/ERR/ERR_HQAmmoSampler.c); unconscious living
+members remain part of that roster. A surviving original owned radio caller is
+still required to send status. Unknown/deleted or transferred members do not
+become fabricated ammunition counts or replacement soldiers.
+
+The sampler reads owned inventory and weapon components, muzzle magazine wells,
+loaded magazines, carried compatible magazines and chambered barrels. Exact magazine-well types contribute known counts. A differing type accepted by
+the native inherited-well search makes the corresponding total incomplete, so
+potentially compatible modded magazines cannot create a false empty report. Physical
+item identity deduplicates loaded/carried enumeration and weapons sharing a
+compatible well. Magazine rounds and chambered rounds remain separate fields.
+Rifles, sniper rifles, machine guns and handguns form the small-arms category;
+supported launcher magazines/chambers are separate. Grenades and smoke do not
+stand in for rifle ammunition. Vehicle-mounted weapons, cargo stock, mines and
+loose launcher projectiles are outside this ammunition model.
+
+Work is bounded to 32 members, 128 inventory items and eight weapons per inspected
+actor, four muzzles per weapon and four barrels per muzzle. Missing components,
+unsupported relevant weapon geometry, invalid loaded magazine wells/counts or an
+exceeded bound mark the affected information incomplete. Loose items with no
+magazine well cannot reload a well-bearing rifle under vanilla compatibility
+rules; they leave small-arms completeness intact and launcher information unknown. Launcher completeness
+is tracked separately where the unsupported data concerns only a launcher.
+Incomplete inventory never means an empty rifle squad. A squad with no observed
+small-arms muzzle is also not treated as proven empty.
+
+## What reaches HQ
+
+The snapshot travels with the routine status report, scheduled every 180 seconds;
+an HQ check-in request can make the next status due sooner. Busy radios and
+physical route delivery still govern arrival. Local inspection, queuing and an
+interrupted uplink do not update HQ ammunition knowledge.
+[Watch](../addons/ai/Scripts/Game/ERR/ERR_HQWatch.c) validates and copies the payload
+only on delivered status, keeping the status source, message ID and observation
+time. Later mutation of the sender's object cannot alter the delivered copy.
+An accepted status without ammunition payload clears a previous ammunition claim.
+The journal displays small-arms magazine rounds and chambered rounds when complete,
+otherwise `unknown`.
+
+`ArmedSearchBlocked` returns true only for a nonclosed formation with a complete
+snapshot matching its current delivered living count, at least one member and
+one small-arms muzzle, zero magazine rounds, zero chambered rounds, and status
+age no greater than 180 seconds. A newer body report that changes the living
+count invalidates that match until suitable fresh status arrives. Missing,
+stale, incomplete or roster-mismatched information adds no veto: HQ does not
+interpret uncertainty as proof that ammunition exists or that it is exhausted.
+
+## Effect on orders
+
+[HQ](../addons/ai/Scripts/Game/ERR/ERR_HQ.c) checks the delivered empty-ammunition
+veto while selecting new pursuit/intercept/contain/search tasks, retasking a
+search, and selecting a missing-patrol investigator. It checks again before
+applying a newly delivered infantry order, so an empty status arriving during
+that downlink can prevent the new assignment. A rejected pending replacement
+does not cancel the previously active assignment. Already active orders are not
+interrupted merely because ammunition evidence changes. Delivered release-only
+commands still work for an empty squad.
+
+Only small-arms emptiness drives this initial decision. Launcher totals do not
+authorize anti-air fire or block tasks; no vehicle-weapon or mine budget is inferred.
+There is no automatic low-ammunition broadcast, low-stock threshold, ammunition
+transfer, refill, replacement unit or independent polling timer. Existing finite
+mortar/courier logistics remain their own implemented service; this new payload
+does not imply that the original broad truck/helicopter/depot supply network has
+been migrated.
+
+## Validation boundary
+
+[Sampler tests](../tests/test_hq_ammo_sampler.py) execute actual inspection and
+snapshot methods with native-component doubles: loaded/carried deduplication,
+shared wells, chambers, separate launcher information, unsupported/invalid inputs,
+work bounds and ownership refusal. [Watch tests](../tests/test_hq_watch.py) cover
+immutable delivered snapshots, exact freshness limits, absent payload and roster
+changes. [Dispatch tests](../tests/test_hq_ammo_dispatch.py) check the new-task gate locations and execute the actual
+delivery admission while preserving active orders and release commands.
+They do not prove native inventory API behavior or real client replication.
+
+The [04:08:57 native run](evidence/native-2026-09-20-040857-hq-ammunition/report.json)
+completes 49 assertions and one round with zero script/runtime failures. Five
+original surviving members report 1,120 compatible magazine rounds, 33 magazines
+and five chambered rounds. A separate native read observes 160 rounds in five
+loaded magazines and a full original-roster rescan matches the queued totals.
+The actual radio route delivers a distinct Watch snapshot, unchanged twenty
+seconds later. No inventory was drained or replenished. The arrangement is the
+existing controlled body-visibility fixture; it does not prove native depletion,
+ordinary squad resupply or multiplayer. This run predates the final conservative
+derived-well refinement, which has actual-method coverage and is compiled in the
+subsequent convoy run. It retains four external localization errors, so strict
+native/release qualification still fails. Cleanup and unchanged source/dependency
+inputs are confirmed for this run.
+
+Failed attempts remain visible: [compiler-expression limit](evidence/native-2026-09-20-035541-ammo-expression-diagnostic/report.json),
+[incomplete-inventory diagnostic](evidence/native-2026-09-20-035730-ammo-inventory-diagnostic/diagnostic.json),
+and [component classification diagnostic](evidence/native-2026-09-20-040049-ammo-component-diagnostic/report.json).
+The second attempt has an original cleanup-verification failure and is explicitly
+unsealed; a later independent check verified the private prefix idle. Its runner
+was not rewritten or promoted. Native diagnostics identified loose rocket/flare
+projectiles with no magazine well; the category correction follows the stock
+reload/search predicates instead of claiming those items refill a rifle.