[systemfsoftware-maker]

Summary

A sandbox preprocessor can no longer write into the Project it receives: files and filesToMutate are now ReadonlyMaps, each preprocessor returns a new Project, and the decision about how a tsconfig is rewritten for the sandbox moves into the rewriteSandboxTsconfig workflow, where property tests can now reach it. Before this change, mergeUpdatedFile called MutableHashMap.set on the caller's maps, and the tsconfig rewriter used Object.assign on the caller's ProjectFile.

This is PR 2 (U2) of the grab-bag decomposition series. PR 1 (#260) retired the Checker plans and protocol modules. U3 (sandbox acquisition cells) builds on this branch next.

What a reviewer should check

• Breaking change to Engine.Project. files/filesToMutate change from MutableHashMap to ReadonlyMap<string, ProjectFile>. The changeset bumps @systemfsoftware/stryker-js major (BREAK-1). etc/stryker-js.api.md lists Engine.Project by name only, so the report itself does not change. Instrument.MutateDescriptionSchema is newly exported (instrumenter minor) so ProjectFile can be a schema rather than a hand-written copy.
• The merge stays where the type lives. withPreprocessedFiles sits in Project.schema.ts (ADR-0002), not in a merge-preprocessed-files.workflow.ts. Its law snapshots the caller's entries before the call and requires the returned maps to be new objects, so an in-place merge fails. ReadonlyMap is only a type-level guarantee, which is why the law checks this. An update whose name is not in files is added to files only, as MutableHashMap.set did.
• One tsconfig per cell run. sandboxTsconfigCell reads, decides, and returns the rewritten file plus its follow list. Sandbox.blueprint.ts walks the follow list depth-first and rewrites followed files before the parent, which is the pre-refactor order. A cell never runs another cell (ADR-0001 *.cell.ts row).
• Behaviour is unchanged, including two pre-existing quirks. A diamond of tsconfigs is still rewritten once per parent with last-write-wins, and an extends cycle still recurses. Adding a visited set would change behaviour, so both stay as follow-ups.
• Plan. U1 executed against 2026-10-09-1840, so the corrected contract is a new dated plan (2026-10-10-0431, supersedes:) and the old file is removed. KTD4 now records ReadonlyMap + withPreprocessedFiles instead of HashMap + a merge workflow.

Sandbox.blueprint.ts goes from 734 to 511 lines. The 400-line bar for it belongs to U3, which splits acquisition into cells.

Tests

• src/__tests__/rewrite-sandbox-tsconfig.workflow.property.test.ts: escape, shape and follow laws, with the expectation built from the drawn entries rather than from production helpers. The schema-derived command generator emits all three arms (TsconfigMissing, TsconfigUnparsable, TsconfigParsed). Checked by sampling 300 commands.
• In-source laws: withPreprocessedFiles (non-aliasing, last update wins, unknown names join files only); referencedEntriesOf and entriesOf (order, absent arrays contribute nothing).
• tests/sandbox-tsconfig.integration.test.ts (new): real mutation runs through Engine.strykerCell on a temp project whose tsconfig extends and references files both inside and outside it. It asserts the exact text written into the sandbox, the missing-file skip, the unparsable-file warning, and that an in-place run rewrites nothing. It also passes unchanged against origin/main d2f018d, which is the parity evidence for "behaviour unchanged".
• Mutation targets (main run 38023408744, mutation-report-420): the two Sandbox.schema.ts survivors 5d7353b99a24bd51 and 0e47ce21d936380f are the [JsonRecord] rest arrays of TsConfigSchema (main lines 26 and 34, now 14 and 19). The integration fixture carries compilerOptions and a reference prepend key and asserts the exact written text, so dropping either rest array should fail it. This is inferred: no mutation run happens locally.

Run locally on the merged head: pnpm typecheck (exit 0); vitest run src (196 files, 1179 tests); instrument-stage, framework-run, clean-temp-dir, plan-without-sandbox, sandbox-tsconfig and compile-error-reuse integration suites each run on their own, all passing; pnpm build and api:check for stryker-js and the instrumenter. The e2e lanes and mutation run only in CI.

Review record

Report-only ce-code-review (correctness, adversarial, project-standards, testing, maintainability, learnings). The validator confirmed 7 findings and rejected 2. All 7 confirmed findings are fixed here, along with the below-bar cell-runs-cell finding and the test-helper placement residual. The two rejected findings were a refactor preference and a placement preference. The cross-model pass did not run because no second-family CLI is installed in the container.

Known pre-existing bug, not fixed here

On main, a successful inPlace run leaves the mutated source instrumented on disk. Reproduced on d2f018d with the new suite's fixture. Likely cause [inference]: the in-place backup writes file.content (the instrumented text) rather than the original (project-files.service.ts writeInto → read). The in-place scenario therefore asserts only on tsconfig files. A fix is out of scope for a behaviour-unchanged PR.

Stacking note

This branch is a one-layer stack on main. It shares one line with #261 (stream-a/l1-ports-topology) in mutation-reporting.service.ts (MutableHashMap.get → files.get), a file #261 almost entirely removes. Per the operator's direction for this series (independent PRs off main that Stream A merges up), it is not stacked on #261.

[ryanleecode]

Root verified: 10/10 green on 0776b03, no open threads, no skips/disables.