refactor: preview generation around a reusable in-memory workspace

[lloydrichards]

Context

Stack Effect already applies plans to an in-memory filesystem for CLI dry-runs and Recipe Builder previews. The current preview path prepares the virtual repository, runs Apply, reads the generated files, and builds the preview response.

This works today, but it makes preview-specific code responsible for workspace setup and result capture.

Benefits

• Give CLI previews, browser previews, and tests one consistent way to run Apply in isolation.
• Keep filesystem setup, path mapping, repository seeding, and cleanup in one module.
• Ensure the Apply result and captured files describe the same workspace state.
• Provide a reusable foundation for stronger catalog tests and future programmatic consumers.

Expected changes

• Introduce a scaffold-layer module that materializes an Apply intent inside an isolated workspace.
• Let callers inspect the Apply outcome and resulting files without knowing how the filesystem is wired.
• When a caller plans and applies in one workflow, ensure both operations observe the same owned workspace.
• Keep the existing preview response stable unless consumers clearly benefit from a change.
• Keep Effect VFS volume and snapshot types internal unless a stable consumer needs them.

This should remain narrower than #181. It owns isolated workspace creation, seeding, path wiring, and result capture—not end-to-end workflow orchestration, user decisions, presentation, Finalize, or configuration mutation. It must not replace Plan or Apply with filesystem state.

Repository-state authority and drift semantics remain owned by #175. This issue consumes that contract when preparing and materializing the workspace.

Done when

• Workspace setup and result capture are owned by one scaffold module.
• The Apply result and captured files always describe the same workspace state.
• Existing CLI and Recipe Builder preview behavior continues to work.
• Tests seed an existing repository, materialize an Apply, and assert both the ApplyResult and resulting files.

Blocked by

• Ensure Apply executes the repository state represented by Plan #175

Related

• Virtual File Tree / In-Memory Generation #108
• Separate scaffold workflow orchestration from CLI interaction #181

[lloydrichards]

The VFS research found two workspace allocations in the current Recipe preview: one for Plan, then another inside ApplyPreviewService. The latter seeds changed, non-skipped paths and returns successful changed files, not a complete repository tree.

This gives the refactor a concrete target: one owned workspace for callers that plan and apply together, plus explicit capture scope. Include ancestor obstructions when seeding existing repositories. Ordinary dry-run and file preview should exercise consistent Apply validation.

Keep #175 responsible for host authority and #179 responsible for Finalize. Snapshot-backed decision experiments can build on this module later without adding workflow policy to it.

[lloydrichards]

Direction confirmed for #175 before starting this refactor:

• Ensure Apply executes the repository state represented by Plan #175 will bind Plan to a canonical repository root and a baseline for every path planning inspected, including missing paths and ancestors; existing text files use fingerprints. Preview and Apply will reject detected drift and require replanning.
• Ensure Apply executes the repository state represented by Plan #175 will keep the existing memory filesystem preview and publish through guarded Apply writes. It will not introduce a shared Plan/preview/Apply volume or use TreeTransfer.toFileSystem as a host writer.
• This issue remains the place to own a selective, workflow-scoped VFS workspace and consistent Plan/Apply result capture. Explicit planned paths must be included even when .gitignore matches them. A future guarded exporter would need Plan baseline checks; toFileSystem does not provide them.

The agreed #175 contract and tests are recorded in .okf/research/issue-175-plan-apply-state.md.