docs/research/_archive/WAVE_16_RECON_AUDIT.md

Wave 16 Reconnaissance Audit

Audit of docs/research/*RECONNAISSANCE.md and *LANDSCAPE.md against repo state at sha e5add150ab06aeef3adda726c0fcae05aa270500.

Wave 16d charter: check 7 recon/landscape docs against current code, produce this audit table, and apply only unambiguous inline fixes. Ambiguous claims are tagged with <!-- AUDIT: stale_<short> --> HTML comments inline and recorded here for orchestrator follow-up.

Summary

• Total claims checked: ~36 across 7 docs
• KEEP: 24
• FIX (unambiguous, applied inline): 2
• FLAG (ambiguous; HTML comment + entry below): 5
• DELETE: 0

The framework deliberately ships proposal-shaped recon docs alongside built code. Wave 16d's posture has been "do not rewrite proposals; flag where the realised code diverged so future readers know which sections are pre-impl sketch vs. accurate-as-of-build documentation."

Per-doc findings

DILOCO_RECONNAISSANCE.md

External-only doc (about meta-pytorch/torchft); no in-repo symbol or path references. Nothing to audit against current code.

Claim	Status	Action
All references are to torchft.local_sgd.DiLoCo, torchft/local_sgd.py:324, torchft/manager.py, etc.	external library, not our concern	KEEP
Recommends pip install torchft-nightly; composer_replication/diloco/__init__.py later adopted that	confirmed in code	KEEP

DILOCO_SERVERLESS_RECONNAISSANCE.md

Doc is a pre-implementation proposal for ADR-005. The realised package layout under composer_replication/diloco/serverless/ is flatter and uses different module names than the proposal.

Claim	Status	Action
composer_replication.diloco.serverless namespace exists	matches reality	KEEP
Code blocks use file headers _modal_adapter.py, _hf_jobs_adapter.py, _protocol.py, _rendezvous.py, _base.py	actual modules are modal.py, hf_jobs.py, executor.py, allreduce.py (no leading underscore, no _protocol/_base/_rendezvous split)	FLAG (stale_serverless_layout HTML comment added before §3.4)
§3.4 proposed modal/, hfjobs/, runpod/ subpackages	actual ships flat modal.py, hf_jobs.py modules	FLAG (covered by same comment)
make_diloco_outer_loop lives in composer_replication/diloco/__init__.py lines 64–125	line numbers verified (def at 64, body ends ~125)	KEEP
python -m composer_replication.diloco.serverless.replica_entrypoint	module exists with main() at line 38	KEEP
MockManager exists in serverless package	confirmed at composer_replication/diloco/serverless/allreduce.py:215	KEEP
ObjectStoreAllReduce exists	confirmed at composer_replication/diloco/serverless/allreduce.py:30	KEEP
§3.5 user-facing API from composer_replication.diloco.serverless import ModalExecutor, HFJobsExecutor, ReplicaSpec	partial: ModalExecutor and HFJobsExecutor exist as classes, but serverless/__init__.py does NOT re-export them (only LocalProcessExecutor, MockManager, ObjectStoreAllReduce, ReplicaHandle, ServerlessExecutor) and ReplicaSpec is not implemented	covered by stale_serverless_layout flag

MODAL_RECONNAISSANCE.md

Doc anchors all loss-shape claims to spikes/005-integrated-trainer-skeleton/, which is unchanged since Wave 15. All checked references resolve.

Claim	Status	Action
spikes/005-integrated-trainer-skeleton/trl_path/composer_trainer.py exists	confirmed	KEEP
spikes/005-integrated-trainer-skeleton/opsd_loss.py exists	confirmed	KEEP
_compute_sdpo_loss student/teacher forwards at composer_trainer.py L138–143	confirmed (L138-143 are student/teacher logits)	KEEP
_compute_trace_replay_loss chosen/rejected forwards at L191–198	confirmed (L191-198 are _sequence_logprobs calls)	KEEP
Zero-tensor short-circuit at L136 and L155	confirmed (both lines return torch.tensor(0.0, ..., requires_grad=True))	KEEP
opsd_loss.py L54 references top_k arg	confirmed	KEEP
Trainer defaults alpha_sdpo=0.1, beta_replay=0.05	match composer_replication/loss.py:75-76	KEEP

REPLAYSIM_NORMALIZATION_RECONNAISSANCE.md

Pre-spike proposal for ADR-004. The library was adopted (data-juicer) and DJNormalizer exists, but the adapter shape and recipe path differ from the proposal.

Claim	Status	Action
composer_replication.replaysim package exists with DJNormalizer	confirmed at composer_replication/replaysim/normalize.py:145	KEEP
replay_trace, extract_dpo_pairs re-exported from replaysim	confirmed in __init__.py	KEEP
§4.3 sketch shows DPOPair with {prompt, chosen, rejected, state, meta} and _to_dj/_from_dj round-trip	actual DPOPair is {state_id, state_messages, chosen: str, rejected: str, n_teachers_agreeing} (TypedDict in composer_replication/teacher_replay.py:99)	FLAG (stale_replaysim_paths_and_dpo_shape added before §4.3)
Recipe path composer_replication/replaysim/recipes/dpo_normalize.yaml (line 344)	actual is composer_replication/recipes/replaysim/default.yaml	FLAG (covered by same comment)
composer_replication/replaysim/ops/preference_validator.py (line 431)	not created — no ops/ subpackage exists	FLAG (covered by same comment)
§4.5 hook into composer_replication/replaysim/teacher_replay.py	actual integration path is replay_and_normalize_trace_sync in composer_replication/replaysim/normalize.py:301 (no separate replaysim/teacher_replay.py — teacher_replay lives at top-level composer_replication/teacher_replay.py)	FLAG (covered by same comment)

RL_FRAMEWORKS_LANDSCAPE.md

Wave 14b parity rewrite changed the public surface for the PRIME-RL recipe. Most file/symbol references in the doc are unambiguously fixable.

Claim	Status	Action
PRIME-RL LossInputs / LossOutputs interface, fields trainer_logprobs, inference_logprobs, teacher_logprobs, advantages, loss_mask	matches composer_replication/recipes/prime_rl/composer_loss.py:17-28	KEEP
import_path = "composer_replication.losses.composer_three_channel_loss" (line 318)	actual is composer_replication.recipes.prime_rl.composer_loss:loss_fn	FIX (applied inline)
composer_replication/losses.py (~120 LOC) (line 333)	actual file is composer_replication/recipes/prime_rl/composer_loss.py; function is loss_fn not composer_three_channel_loss; signature is (inputs, **kwargs) not (li, *, hint_weight, replay_weight, replay_logits)	FIX (filename + AUDIT comment noting signature drift; sketch retained as-is)
Recipe in recipes/composer_v0_prime_rl.toml with kwargs hint_weight, replay_weight, replay_logits_path	actual recipe is composer_replication/recipes/prime_rl/prime_rl_config.yaml (YAML not TOML) and kwargs are alpha_sdpo, beta_dpo, dppo_mask_high, dppo_mask_low, adv_tau, kl_tau	FLAG (stale_recipe_format HTML comment added at the recipe block)
Monarch sketch composer_replication/orchestrator/monarch_runner.py	not in code; treated as v0.2 sketch (and §6.2 already labels it "Monarch wrap-up sketch (v0.2)")	KEEP (clearly v0.2 forward-looking; no AUDIT needed)
Note that composer_replication/recipes/monarch/actors.py exists, providing the monarch actor surface	matches composer_replication/recipes/monarch/actors.py	KEEP

SELF_DISTILLATION_LANDSCAPE.md

Audit doc for ADR-007. Three losses (SimPO, TAID, Entropy-Aware OPD) were adopted, but the package layout proposed in §"Recommended follow-up wiring" is not what was built.

Claim	Status	Action
References composer_replication/__init__.py and existing composer_replication.opsd.generalized_jsd_loss	confirmed	KEEP
Audited candidate verdicts (SimPO/TAID/EA-OPD recommended)	matches what shipped under composer_replication/distillation/	KEEP
Proposed package layout: composer_replication/distillation/{targets.py, losses.py} + composer_replication/preference/{simpo.py, dpo.py}	actual: flat composer_replication/distillation/{simpo.py, taid.py, entropy_aware_opd.py} — no targets/losses split, no top-level preference/ package	FLAG (stale_distillation_layout HTML comment added before the proposal block)
Function names taid_target, entropy_aware_kl_loss, fixed_target	actual exports: taid_loss + TAIDScheduler, entropy_aware_opd_loss, simpo_loss	FLAG (covered by same comment)
Composition rule sketch L_distill = entropy_aware_kl_loss(target = taid_target(...), ...)	not realised as a single composed function — actual API is per-loss with compose_loss mixing channels via sdpo_wrapper/dpo_variant switches	FLAG (covered by same comment)

TRACE_SOURCE_RECONNAISSANCE.md

Pre-spike audit feeding ADR-002 and Spike 007. Doc cites the actual TraceState/DPOPair TypedDicts correctly (matches current composer_replication/teacher_replay.py:81-104). The sketch in §6 uses spike-shape names that do not match what shipped.

Claim	Status	Action
TraceState and DPOPair field lists in §1	match composer_replication/teacher_replay.py (TypedDicts at lines 81-104)	KEEP
spikes/005-integrated-trainer-skeleton/teacher_replay.py exists	confirmed	KEEP
§6 sketch path spikes/007-trace-ingester/trace_ingester.py and class TraceIngester	actual spike path is spikes/007-real-trace-ingestion/claude_code_ingester.py and the production class is composer_replication.ingestion.claude_code.ClaudeCodeIngester	FLAG (stale_ingester_paths_and_naming HTML comment added before §6)
Direct inspection of ~/.claude/projects/ JSONL files	not testable from CI; user-machine claim	KEEP
Re-use of TraceState from spike-005 teacher_replay.py	spike still has it; production also has it	KEEP

Open items for Wave 17+

Wave 17 closeout (2026-05-26): All 5 FLAGs below were resolved by adding "Realised in v0.1" companion sections to the affected proposal docs that document the shipped surface inline above the historical sketch. Wave 17 also fixed the underlying code bug from FLAG #1 — serverless/__init__.py now re-exports ModalExecutor and HFJobsExecutor (verified by composer_replication/diloco/serverless/tests/test_serverless_local.py::test_public_reexports_include_all_executors). The original FLAG-list below is preserved as historical record of what the audit found.

These are the FLAGged ambiguous claims that need orchestrator decision before a confident rewrite:

1. DILOCO_SERVERLESS_RECONNAISSANCE.md §3.4 — proposed serverless package layout (_modal_adapter.py, _protocol.py, etc.) does not match shipped layout (modal.py, executor.py, etc.). Decide: rewrite §3.4 to document shipped layout, or keep as historical proposal. Note also: §3.5 references ModalExecutor and HFJobsExecutor as from … serverless import … but serverless/__init__.py only re-exports LocalProcessExecutor. Either the public re-export should be added (code change, out of Wave 16d scope) or §3.5 needs to use the longer module path.

2. REPLAYSIM_NORMALIZATION_RECONNAISSANCE.md §4 — Adapter sketch assumes a DPOPair shape ({prompt, chosen, rejected, state, meta}) that does not match the realised TypedDict ({state_id, state_messages, chosen: str, rejected: str, n_teachers_agreeing}). The §4.3 _to_dj/_from_dj functions in the sketch will not work as written. Decide: rewrite §4 to match replay_and_normalize_trace_sync in composer_replication/replaysim/normalize.py:301, or keep as proposal- shaped historical context.

3. RL_FRAMEWORKS_LANDSCAPE.md §6.1 — recipe sketch is .toml with hint_weight/replay_weight kwargs; reality is .yaml with alpha_sdpo/beta_dpo/dppo_mask_high/dppo_mask_low/adv_tau/kl_tau. The loss_fn(inputs, **kwargs) signature also differs from the composer_three_channel_loss(li, *, hint_weight, replay_weight, replay_logits) sketch. Decide: rewrite §6.1 to match shipped recipe, or keep as the original landscape proposal.

4. SELF_DISTILLATION_LANDSCAPE.md §"Recommended follow-up wiring" — the distillation/{targets.py, losses.py} + preference/{simpo.py, dpo.py} layout is not what shipped. Actual is flat composer_replication/distillation/{simpo.py, taid.py, entropy_aware_opd.py} with function names simpo_loss, taid_loss + TAIDScheduler, entropy_aware_opd_loss. Decide: rewrite the wiring sketch or leave as proposal-shaped record of pre-ADR thinking.

5. TRACE_SOURCE_RECONNAISSANCE.md §6 — TraceIngester sketch differs from shipped ClaudeCodeIngester. Decide: rewrite §6 to point at the realised ingester (would also require updating spike path from 007-trace-ingester to 007-real-trace-ingestion), or keep as pre-spike proposal.

What was NOT changed

• WAVE_*_FINAL_REVIEW.md files — explicitly out of scope for Wave 16d.
• Any code under composer_replication/, examples/, tests/ — code-side fixes (e.g. adding ModalExecutor/HFJobsExecutor to serverless/__init__.py re-exports) belong to a code wave, not a doc audit.
• Whole-section rewrites of any doc — Wave 16d's mandate is "audit + safe inline fixes only". Each FLAG above is a candidate for a future targeted rewrite wave.