Research Brief Entitypipe

Identity

Worker w-entitypipe-a1; task entitypipe; implement. Read .agent-cache/WORKER.md. Bus: python "%USERPROFILE%/.claude/skills/agent-cache-orchestrator/scripts/acbus.py" Parallel: w-meshfmt-a1 (geometry), w-cmfmt-a1 (collision), w-matpipe-a1 (surfaces), w-mapmanifest-a1 (streaming). You own placement and authoring.

Objective

You are the one worker on this wave whose result can be PLAYABLE without any further format being cracked - so treat that as the goal, not a side effect.

Build the authoring pipeline for a custom map on existing geometry: read a retail map's .entities, change it meaningfully, rebuild the bundle, verify it. Concretely, produce a map that differs from retail in ways a player would notice: enemy placement and counts, item and weapon pickups, lights, triggers, spawn point. That is what "custom map" means for most id Tech games that ship without an editor, and everything needed for it is already solved.

What is already solved - build directly on it

• wolfsdk/idclwrite.py - container writer, round-trips retail archives BYTE-IDENTICALLY (3/3), 6/6 negative controls, finalize() recomputes every hash. Independently re-verified by the master today.
• The other master (codex/Astra) already proved ONE authored entity change survives a bundle build: a cyan lobby light at 8.72,-192.97,1.32 in re_probes/map_alias_v3/bundle_headerfixed/ - READ IT AS A REFERENCE, do not modify it, it is their only copy. Their docs/tnc_astra_findings_20260923.md documents the alias/MRL work.
• re_probes/idclwriter/chunk_22.resources is that same bundle with its four stale entry hashes repaired (7127/7127). Read-only for you.
• The .entities file is a compfile and is TEXT - compfile:maps/game/dlc/ c02/c2v1_custom.entities, 256319 bytes uncompressed. That is your input.
• tools/entities.py (part 1 entity work) and tools/build_entities_mod.py exist - read them, reuse what fits.

Sources / starting points

• Retail source map: <Steam library>/.../dlc/dlc_2/base/chunk_22.resources (c2v1, Gestapo Office). READ ONLY.
• re_probes/agent_reports/{small_custom_map,idclwriter,execcarrier}.md
• docs/karten.md, docs/kiscule.md (2408 script files, 205 node types - scripted events live there), docs/moddingflaeche-tnc.md.
• The entity grammar is id Tech 6 and close to Doom 2016's .entities. Public knowledge is a legitimate starting point, but VERIFY every claim against the actual file - do not import assumptions.

Ownership

tools/build_custom_map.py (new - the pipeline), tools/probe_entitypipe.py (new - checks), re_probes/entitypipe/ (new dir, the built map), and re_probes/agent_reports/entitypipe.md. Everything else is read-only: wolfsdk/*, other workers' tools, dlc_4, re_probes/{map_alias_v3,idclwriter,execcarrier,cfilekey}/.

Forbidden / do not touch

Do not install into the game folder and do not launch the game. The user runs installs themselves, in a five-minute window. No writes to "%USERPROFILE%/Saved Games". No pip install. Do not edit any other worker's files, docs/*, or config.json.

Hard constraints

Python 3.11, stdlib only. Reproducible from the command line.

Acceptance criteria

• A parser/serializer for .entities with a byte-exact round-trip on the real file: read it, write it back unchanged, get identical bytes. Without that, an edit is guesswork. State it as n/n over every compfile entity file you can find, not just one.
• Surgical edits: changing one property must leave every other byte untouched. Prove it with a diff, the way the part-1 decl editor does.
• A built map bundle under re_probes/entitypipe/ containing at least three DISTINCT, player-visible changes (not just a light), each listed in the report with its entity name and what a player would see.
• It must pass tools/probe_datahash.py n/n and tools/probe_idclhash.py OK.
• Negative controls: a malformed entity block, a dangling entity reference and a duplicate entity name must each be REJECTED by your checker. A checker that accepts everything measures nothing.
• A five-line runbook at the end of the report: install, launch, what to look for, how to tell it worked, uninstall.

Verification expectations

Nothing offline proves the map loads. Say "structurally valid by these checks, runtime unconfirmed". Be especially careful with entity references: a spawn that names a non-existent entityDef will not be caught by any hash check but will break the map.

Failure honesty

If the entities file turns out to be a compiled/binary form rather than the text it appears to be, say so immediately with evidence. If a change class (e.g. adding a new enemy rather than moving an existing one) needs an asset that is not in the map's chunk, name that dependency rather than shipping a map that will fail to resolve it.

Coordination / deliverable

Checkpoint at milestones. Publish a bus fact when the entities round-trip is byte-exact, and again when the bundle verifies - the other four workers are building the pieces that will eventually plug into YOUR pipeline. Concise German report in re_probes/agent_reports/entitypipe.md. Finish the bus task.