Capture current mission, AI, map and administration development

Include the current addon, terrain integrations, tools, regression tests and recorded development evidence.

docs/ai-delegation-workarounds-1.8.md

@@ -0,0 +1,118 @@
+# Reforger 1.8 AI offloading: workaround experiments
+
+7 October 2026. Follow-up to the [ownership-transfer investigation](ai-delegation-1.8.md).
+
+**User decision, 7 October 2026:** retain the findings, evidence and isolated
+prototypes. Defer choosing or integrating an offloading architecture until we have
+representative mission performance data, then review the options with the user.
+Start with the [existing HQ telemetry](hq-performance-measurements.md); assess
+actual bottlenecks, query workload cost, latency tolerance and communication
+overhead. That telemetry alone does not provide a native AI CPU breakdown.
+The successful query experiment is not evidence of a production speedup.
+
+**A limited native-query worker works. A worker-local copy of a soldier still does
+not run its normal AI.** These are measured results from separate dedicated and
+hidden client processes, both 1.8.0.13, on one physical host. They do not establish
+an Arma 3-style headless client or a production CPU improvement.
+
+No Escape gameplay code or production server configuration was changed. Both
+experiments completed and their owned processes were cleaned up. Source snapshots,
+launch commands, complete logs and [measured summary](evidence/ai-workarounds-1.8-2026-10-07/summary.json)
+are preserved. Vanilla resupply-station errors appeared during server shutdown,
+after completion; neither experiment had script errors in its observation phases.
+
+## Workaround 1: independently authoritative worker-local AI
+
+Instead of transferring the original soldier, the worker calls
+`SpawnEntityPrefabLocal()` to create its own ordinary soldier and group. This is a
+supported local-spawn API, separate from the server's replicated proxy:
+[pinned ChimeraGame declaration](https://github.com/BohemiaInteractive/Arma-Reforger-Script-Diff/blob/b46bdd8f4932f3a256c765f93a44417996a6da73/scripts/Game/generated/ChimeraGame.c).
+The test attempts activation, group membership when a control agent exists,
+LOD 0, a local move waypoint, and soldier-navmesh queries.
+
+Results across 60 worker-local soldier samples:
+
+- The local soldier exists and reports **Authority, Owner and Master**.
+- Its AI control component exists, but its control agent remains absent.
+- Native perception counter and soldier/group decision callback counts stay zero.
+- The worker has an AIWorld, but `GetNavmeshWorldComponent("Soldiers")` returns null.
+- The original dedicated soldier continues its native perception and BT updates.
+
+This rules out the simple “make a local authoritative duplicate and activate it”
+workaround for this ordinary connected-client setup. It does not prove that every
+possible custom world/component configuration or a separate standalone server is
+incapable of AI. Neither an independent standalone-world bridge nor a binary patch
+was implemented here.
+
+[Fixture](../tests/native/ai_worker_local/README.md),
+[worker log](evidence/ai-workarounds-1.8-2026-10-07/local-ai/client-console.log.txt),
+[server log](evidence/ai-workarounds-1.8-2026-10-07/local-ai/server-console.log.txt).
+
+## Workaround 2: offload explicit native world-collision queries via RPC
+
+This test creates an explicit query workload with `BaseWorld.TraceMove`, which
+enters native engine collision code. The dedicated sends one bounded batch request
+per second through the connected worker's PlayerController. The worker casts 256
+rays and sends back fractions; the authoritative server validates and consumes them.
+No HTTP and no ownership transfer of the soldier are involved.
+
+This is a **new diagnostic workload**, not an interception of stock perception's
+internal raycasts. It demonstrates a route for replacing custom script-issued
+query batches with remote execution. Stock AI perception, BT and movement remain
+on the dedicated server throughout.
+
+| Phase | Measured result |
+|---|---|
+| Both sides compute identical batches | 19 accepted comparison batches, 4,864 ray results; zero differences exceeding a trace-fraction tolerance of 0.005 |
+| Only the worker computes batches | 20 batches executed there; 19 replies accepted before the phase changed; the dedicated's test raycast counter stayed at 5,120 |
+| Dedicated consumes a result | A clear candidate became a server-side move waypoint; soldier moved 36.25 m horizontally while remaining server-owned Authority |
+| Worker deliberately stops replying | Dedicated resumed local query execution after the reply-age threshold; 19 fallback batches observed |
+
+Late replies spanning a phase change are rejected, explaining the distinction
+between executed and accepted batches. The `mismatches=0` log field is a comparison
+result **only in phase 1**; phase 2 deliberately has no server-side reference batch.
+
+The prototype checks the job sequence, phase, response age (2.5 seconds), array
+length, finite/in-range fractions and known terrain/sky control rays. It creates
+only one returned-result waypoint. Timeout recovery here proves local batch
+computation resumes; it does not implement a complete production worker dispatcher,
+AI failover or outstanding combat-order cancellation.
+
+[Fixture](../tests/native/ai_query_worker/README.md),
+[worker log](evidence/ai-workarounds-1.8-2026-10-07/native-queries/client-console.log.txt),
+[server log](evidence/ai-workarounds-1.8-2026-10-07/native-queries/server-console.log.txt).
+
+## Performance and correctness limits
+
+Each batch took **0–1 ms on the worker's integer-millisecond wall clock**; zero means
+below timer resolution, not free execution. Round trips for accepted worker-only
+batches were **33–67 ms** over the local test connection, including frame scheduling.
+This is a functional proof, **not a demonstrated speedup**. Moving such cheap batches
+may cost more in serialization, networking and validation than it saves. We did not
+capture exclusive native CPU or benchmark many AI/machines.
+
+Rays use `TraceFlags.WORLD`; dynamic entity collision queries were deliberately not
+included. Matching this loaded terrain sample does not validate dynamic doors,
+buildings with changed state, vehicles, infantry, streaming gaps or all terrain.
+A useful distributed query service would need suitable scene coverage, revision
+tracking and stale-result handling. A clear ray is also not a valid navmesh route;
+the authority's ordinary AI still performed navigation toward the returned waypoint.
+
+The worker's normal AI scheduler, native perception and soldier navmesh were not
+made to run by this protocol. The server still performs character simulation,
+physics, animation, AI decisions/perception/navigation and replication. Returning a
+candidate waypoint is not a substitute for a complete distributed AI simulation.
+
+## Practical direction
+
+There is now an engine-tested route for **selected custom query batches** using a
+normal Reforger client as a compute worker. Candidate code sites include custom
+line-of-fire, candidate cover/terrain checks and tactical searches that explicitly
+call engine query APIs. Only measured expensive, latency-tolerant batches justify
+moving across this boundary. The test itself does not show that those sites are a
+large part of Escape's CPU load.
+
+Keep this as an isolated research feature for now. Measure the actual mission's
+query batches before building a production dispatcher. Native full-soldier AI
+scaling remains unresolved; neither ownership transfer nor the worker-local-copy
+experiment unlocked it.