msd-core/docs/adr/3574-install-materialization-primitives.md

ADR-3574: Install materialization shares primitives, not one writer

• Status: Accepted
• Date: 2026-08-16
• Issue: #3574
• Epic: #2866 — Phase 6 (#2875)
• Amends: none. Constrained by ADR-58, ADR-3660, ADR-1508.

Context

Epic #2866 Phase 6 was scoped on the premise that "materialize this layout" is implemented three times and skipped once, and that the remedy is to extract the preserve → prune → stage → copy → restore choreography into one module with the three sites becoming callers.

That premise was measured against the tree on 2026-08-16, after Phase 5 (#2874) landed. It does not hold. The three sites overlap in shape and diverge in mechanism:

step	installRuntimeArtifacts src/install-engine.cts:770-958	applySurface src/surface.cts:359-452	agent loop bin/install.js:11120+
preserve	snapshot-based, skills kind only (_snapshotDir)	none	none
prune	_removeGsdEntries, prefix-scoped wipe	pruneSkillDirs — allow-list, never wipes	stale gsd-* unlink
stage	copies straight into dest	temp dir first, then syncs	inline transform, no staging dir
restore	_restoreDir the snapshot	none	none

The divergence is deliberate on at least one side. applySurface's prune is allow-list precisely so that it structurally cannot delete a user's files — its own doc comment ties that to the #2973/#3664 user-directory-preserving fix. installRuntimeArtifacts instead wipes a prefix-scoped set and restores a snapshot of the one user-owned directory it knows about.

A single writer must pick one of these. Forcing applySurface onto snapshot-restore would replace a design that cannot lose user files with one that deletes them and puts them back — trading a structural guarantee for a procedural one. Forcing installRuntimeArtifacts onto temp-staging adds a staging hop it does not need.

Two further premises of the original scoping are stale:

• The agents bypass is shrinking, not static. _DESCRIPTOR_AGENTS_RUNTIMES (bin/install.js:11152) already routes ten runtimes — cursor, windsurf, augment, trae, codebuddy, copilot, antigravity, qwen, kimi, zcode — through the descriptor. The inline _hostBehaviors() dispatch survives only for codex, cline, hermes and generic runtimes.
• The duplication comment is stale in the opposite direction. It lives at src/runtime-artifact-layout.cts:277-297 (not the range #2875 cites) and reads: "That duplication is deliberate until the second layout.kinds consumer — applySurface … — mirrors the legacy agent pipeline." That condition has partly been met, via agentCtx / stageAgentsForRuntimeWithConverter in applySurface.

Separately and independently, #1874-F19 is confirmed real: preserveUserArtifacts (src/install-engine.cts:168-179) builds an in-memory Map<string,string> via readFileSync, and restoreUserArtifacts (:187-195) writes it back. Nothing touches disk in between. Any process death between the intervening wipe and the restore loses the content outright, at four call sites (install-engine.cts:633, :705; bin/install.js:8658, :11056).

Decision

1. There will be no single materializer module

The three choreographies stay distinct. This ADR explicitly declines Phase 6's first acceptance criterion as written — "One module writes a Layout; the three former call sites delegate to it" — because satisfying it requires breaking one of two mechanisms that are each correct for their own caller.

Recording the refusal is the point: the next reader who notices three similar-looking loops should find this file rather than re-derive the extraction and rediscover the conflict.

2. What IS extracted: durable user-artifact staging (F19)

preserveUserArtifacts / restoreUserArtifacts move to a shared module and stage to a durable on-disk path before any wipe, reusing copyPreservingSymlink (src/installer-migrations.cts:166-177) — a pure two-argument function with no migration-specific state, already used by the backup-and-remove migration action in exactly this copy-strictly-before-delete order.

copyPreservingSymlink is the correct primitive for a second reason beyond durability: it never dereferences a symlink target. Its own doc comment records why — dereferencing could copy the bytes behind a link like ~/.ssh/id_rsa into the backup tree. A hand-rolled copyFileSync here would reintroduce that.

The journal / backupRoot / runId scaffolding around it is migration-specific and is not extracted. Only the primitive is shared.

3. What IS extracted: the retired-kind prune

pruneRetiredRuntimeArtifacts is already called by both installRuntimeArtifacts and applySurface with the same intent. That is genuine shared behavior rather than parallel evolution, and it is the one step where a single owner costs nothing.

4. The agents bypass is closed on its own terms

Removing the inline _hostBehaviors() agent dispatch so the descriptor is authoritative for every runtime is independent of the prune question and proceeds regardless. It is the part of Phase 6 whose evidence survived scrutiny intact, and ten runtimes have already made the trip.

5. Placement and content ownership are unchanged

Per ADR-3660, placement knowledge outside runtime-artifact-layout is drift; the extracted primitives consume Layout, never re-derive it. Per ADR-1508, "Layout owns placement; this module owns content", and the conversion module imports nothing upward. The primitives sit downstream of both and introduce no upward dependency.

Per ADR-58, these primitives are on the adapter side of the pure-policy/thin-adapter split — they execute IO. Phase 5 routed that IO through an injectable seam and established that the write-confinement decisions (hasExistingSymlinkBetween, assertDestWithinConfigHome) stay outside the adapter, so a fake cannot certify an install the real filesystem would refuse. The extraction must not relocate those decisions.

What this ADR does not decide

• Whether the three choreographies ever unify. The applySurface descriptor-agents migration is partly landed; when it completes, the shapes may converge enough that the question is worth reopening on evidence. Revisit then, not before — and not by re-deriving the extraction this file declines.
• The prune model itself. Whether allow-list or prefix-scoped-wipe is the better default across the installer is a real question and a separate one. Nothing here endorses either as canonical.
• USER_OWNED_ARTIFACTS' membership. #2875 names USER-PROFILE.md as at risk; that could not be confirmed in this codebase state — dev-preferences.md is confirmed at three of four call sites. The implementing phase must enumerate the list rather than inherit the claim.

Consequences

• Phase 6's acceptance criterion 1 is not met as written, deliberately. #2875 needs a scope update to match this decision before implementation. That is the cost of having measured the premise instead of executing it.
• Three loops that look duplicated remain, now with a recorded reason. Future reviews should treat this file, not the loops, as the answer.
• The agents bypass closes; the runtime-artifact-layout.cts:277-297 comment is rewritten rather than deleted, because its "deliberate until X" framing is stale in a way a plain deletion would not capture.
• F19's durability fix lands here rather than in #1874, per maintainer direction on #2875. #1874's F5, F6 and F18 are untouched.
• The regression test for F19 must inject the crash window by monkeypatching the fs method and restoring in a finally — never via chmod/permission tricks, which root bypasses, yielding a test that passes with zero coverage in root Docker and CI.

Alternatives considered

1. One materializer, three callers delegate — Phase 6 as originally scoped. Rejected on the measured evidence above: it forces either applySurface off its non-wiping prune or installRuntimeArtifacts into unnecessary temp-staging.
2. One materializer with a preservation-strategy parameter. Rejected. It preserves both behaviors but makes the module own two concepts and defer the choice to its callers — the exact widening ADR-2866 warns future reviews to resist, and a strategy flag is how a shared module becomes two modules wearing one name.
3. Do nothing; leave F19 to #1874. Rejected. This phase rewrites that precise choreography, so landing the durability fix elsewhere means two conflicting passes over the same code.
4. Delete the duplication comment as no longer true. Rejected. It is not simply false — it is stale in a specific, informative way, and its "deliberate until X" condition is now partly met. A rewrite carries that; a deletion loses it.

A note on the evidence

Blast-radius figures for this seam are not reliable and were not used to justify anything above. get_impact on installRuntimeArtifacts resolved to a same-named test helper (tests/adapter-declarative-equivalence.test.cjs:52) and reported zero affected — the same name-collision failure mode that produced a misleading clean radius during #3544. applySurface returned CRITICAL / 184+ from one tool and LOW / 0 from another, disambiguating to two different in-file matches of the same name. The decision above rests on read code, not on those numbers.

References

• Epic: #2866; this phase: #2875; this ADR: #3574
• Durability finding: #1874-F19 (and its closed child #1878 — do not re-file)
• Placement seam: ADR-3660 · content seam: ADR-1508 · policy/adapter split: ADR-58
• The epic's own frame: ADR-2866, which mandated that this module owe its own ADR
• User-directory preservation this ADR protects: #2973, #3664