msd-core/docs/adr/0010-file-operation-engine-module.md

File Operation Engine Module owns safe runtime/config file mutations

• Status: Superseded by ADR-0009 (Shell Command Projection Module expansion, Phases 3–4, #3467–#3468)
• Date: 2026-05-12
• Superseded: 2026-05-13

Supersession note. Rather than build a separate File Operation Engine, the file-mutation safety policy this ADR proposed was absorbed into the Shell Command Projection Module (ADR-0009). Phase 3 (#3467) added platformWriteSync / platformReadSync / platformEnsureDir / normalizeContent to that seam, owning atomic write (tmp+rename), .md normalization, and directory creation as a single platform-conditional surface. Phase 4 (#3468) removed the duplicated atomicWriteFileSync / safeReadFile / normalizeMd wrappers from core.cjs. The applyFileMutationPlan / typed plan IR design proposed below was not built — the simpler per-call seam proved sufficient for the actual drift sites. Lock-file lifecycle (Track B item 3) remains owned by withPlanningLock in planning-workspace.cjs because its { flag: 'wx' } exclusive-create semantics differ from atomic-write rename semantics.

---

We propose introducing a File Operation Engine Module that owns policy for managed file reads, writes, deletes, locks, backups, and rollbacks across installer, migration, and planning surfaces. Today, file mutation behavior is duplicated across bin/install.js, gsd-core/bin/lib/installer-migrations.cjs, and multiple planning modules, with drift in atomic-write guarantees, path safety checks, and ownership classification.

This ADR also captures where Shell Command Projection Module policy should be consumed or expanded for hook-command-specific file mutations, so shell command drift and file mutation drift do not evolve as separate bug classes.

Decision

• Add a File Operation Engine Module under gsd-core/bin/lib/ as the single seam for file mutation safety policy.
• Keep command-text projection in the Shell Command Projection Module (ADR-0009), but route projection-adjacent hook file mutations through shared managed-hook ownership policy.
• Move file operation adapters to the new seam in two tracks:
  • Track A (projection-adjacent): runtime config hook-command detection/rewrite/delete paths consume shared managed-hook policy from the projection seam.
  • Track B (solution-wide): shared file operation engine owns atomic write, path containment, lock behavior, rollback bookkeeping, and best-effort cleanup policy.
• Keep internal subprocess execution out of this seam (same boundary as ADR-0009): this is a file operation seam, not a command runner.

Initial Scope

1. Unify managed-hook ownership classification used by install/uninstall/migration hook config rewrites.
2. Unify atomic write behavior currently duplicated in installer/core/migration paths.
3. Unify lock-file lifecycle policy used by planning workspace and installer migration journal flows.
4. Expose typed file mutation plan IR for tests (rewrite-json, rewrite-text with format (toml/markdown/plain), delete-file, backup-file, restore-file, ensure-dir).

Migration Inventory

Projection-adjacent file mutation drift (Track A)

• bin/install.js
  • hook cleanup command detection (isGsdHookCommand)
  • stale Codex hook strip basenames (STALE_HOOK_BASENAMES)
  • settings/config hook entry prune/rewrite paths
• gsd-core/bin/lib/installer-migrations/002-codex-legacy-hooks-json.cjs
  • isManagedCodexHookCommand regex/path detection duplicated from installer-owned hook policy
• gsd-core/bin/lib/shell-command-projection.cjs
  • isManagedHookBasename already owns part of this policy and should become the canonical owner

Solution-wide file operation drift (Track B)

• bin/install.js
  • local atomicWriteFileSync and temp cleanup registry
  • large inlined read/modify/write + backup/rollback logic for runtime config and hooks
• gsd-core/bin/lib/core.cjs
  • atomicWriteFileSync helper diverges in fallback behavior from installer/migration variants
• gsd-core/bin/lib/installer-migrations.cjs
  • separate writeFileAtomicSync, rollback journaling, lock handling, and containment checks
• gsd-core/bin/lib/planning-workspace.cjs and gsd-core/bin/lib/state.cjs
  • duplicated lock-file create/release/remove patterns and best-effort cleanup semantics
• gsd-core/bin/lib/roadmap.cjs, phase.cjs, milestone.cjs, frontmatter.cjs, drift.cjs
  • direct read/modify/write flows with inconsistent atomicity and normalization policy application

Interface sketch

The File Operation Engine Module should expose typed mutation planning and execution helpers:

planFileMutations({
  rootDir,
  operations: [
    { type: 'rewrite-json', relPath, mutate },
    { type: 'rewrite-text', relPath, mutate, format: 'toml' | 'markdown' | 'plain' },
    { type: 'delete-file', relPath },
    { type: 'ensure-dir', relPath },
  ],
  ownership: { mode: 'managed-only' | 'allow-user', classifier },
})

applyFileMutationPlan({
  plan,
  atomic: true,
  rollback: true,
  lock: { scope: 'config' | 'planning', id: '...' },
})

For projection-adjacent paths, adapters should consume projection policy:

isManagedHookCommand(commandText, { surface, configDir })

Consequences

• File mutation safety policy becomes local to one module, reducing drift across installer/migration/planning paths.
• Shell command projection and hook ownership classification stay aligned at one seam family.
• Tests can assert typed mutation IR and reason codes instead of source-grep and duplicated predicate mirrors.
• Initial migration is broad; sequencing should prioritize projection-adjacent hook config paths first, then converge atomic-write and lock semantics.

Open questions

• Whether lock semantics should be one shared policy for installer + planning, or two adapters over one lock primitive.
• Whether SDK query write paths should consume the same engine in the first pass or follow after CJS convergence.
• Whether file mutation telemetry (per-op reason codes and rollback events) should be required for all engine adapters.

References

• ADR-0008: 0008-installer-migration-module.md
• ADR-0009: 0009-shell-command-projection-module.md
• Related bug history: #1755, #2866, #2979, #3002, #3017, #3439