design: portable generated-workspace artifact

[lloydrichards]

Context

Preview interfaces currently return a list of generated files. That is enough for rendering a dry-run, but some future consumers may need a complete, restorable representation of the generated workspace.

Before exposing a new format, we should identify whether a real consumer needs to restore, transfer, persist, or incrementally update a previewed workspace.

Potential benefits

• Restore or transfer exactly the workspace that was previewed.
• Support reproducible bug reports or saved Recipe Builder sessions.
• Provide a stable handoff for programmatic or remote consumers.
• Send smaller updates when two processes share a known base workspace.

Questions

• Which concrete consumer needs more than the existing file list?
• Should an artifact describe the complete workspace, only relevant repository state, or only generated changes?
• Which interface should produce and own it?
• What compatibility and versioning guarantees would it require?
• How would size limits and untrusted artifact decoding be handled?
• Should persistence belong to Stack Effect or to the embedding application?

Effect VFS snapshots and deltas demonstrate technical feasibility, but this discussion should not commit Stack Effect's domain interfaces to those implementation types. Any externally exchanged artifact should use a Stack Effect-owned, versioned schema at the scaffold or application seam so its storage encoding remains replaceable.

Useful outcome

• Decide whether a portable workspace artifact belongs on the roadmap.
• Identify the first consumer that justifies it.
• Record ownership, completeness, compatibility, size, and security requirements.
• If justified, create a narrower implementation issue.

Related

• refactor: preview generation around a reusable in-memory workspace #250
• Virtual File Tree / In-Memory Generation #108
• Add --output json flag for init and add commands #123
• Separate scaffold workflow orchestration from CLI interaction #181

[lloydrichards]

The research supports snapshots as a payload behind a Stack Effect-owned manifest. Current preview files are only changed files, and Recipe preview appends stack.effect.json separately, so completeness needs an explicit contract.

Choose the first consumer and whether the artifact is pre-Finalize source or tool-modified output. Candidate identity inputs include catalog version/digest, effective Selection and config, composer version, and generation stage. Preserve contributor provenance separately from payload integrity.

A focused VFS run confirmed that sibling deltas fail with BaseMismatch after either sibling changes, even on disjoint paths. Deltas are exact-base transitions, not a general module-composition format. Keep registry/profile identity exploration connected to #249.

The compiled-profile and cache-identity experiment is now tracked in #254.