# Clean upstream and writable Void workspace

FDS keeps upstream source separate from its build state:

| Path | Ownership and purpose |
| --- | --- |
| `vendor/void-packages/` | Clean upstream Git submodule at `VOID_PACKAGES_COMMIT` |
| `packages/` | Authoritative FDS base-package sources, including Dasung |
| `examples/software/*/void/` | Authoritative example PROGRAM package sources |
| `.host/void-packages/` | Generated writable checkout, package copies, local configuration, caches and build container |

`make bootstrap` creates the build checkout locally at the pinned commit. It
copies Git objects independently; there is no network fetch for this step, no
Git alternates dependency and no hardlinks into the upstream source. Normal
package bootstrap still uses its configured repositories.

`tools/prepare-void` copies FDS package overlays into the writable checkout and
retains the existing checks against replacing upstream packages or overwriting
changed generated copies. Workstation builds default to the same checkout.
Explicitly selecting a Git submodule with `--void-packages` is rejected before
source files or build state can be written there.

The workspace helper migrates old, matching generated files and build caches by
renaming them. It compares every file, mode and symlink in each known source
copy first. Unknown upstream files, staged changes, independent edits and
conflicting destinations stop migration. Run builds and migration sequentially.
The workspace lock prevents two preparations from changing the layout together.
Python is already a build-host prerequisite; this introduces no new dependency.

For this checkout, the 58 staged additions matched the main-repository sources.
Their local commit `47580322e801ef195c9bf279fd1fe4d8a1f723e9` and both staged
patches were saved under `.host/backups/void-overlays-20260922-134611/` before
unstaging those copies. The parent gitlink was restored to upstream commit
`02a3cbc132c3c4a3a9d59e9b98f517af5dd11cd1`, matching the declared pin. All eleven
package directories, `hostdir`, `masterdir-x86_64` and `etc/conf` were moved into
the build checkout. No upstream tracked source was changed.

An explicit future pin update advances the writable checkout without replacing
its caches. Git refuses updates that would overwrite local files. Continue to
record the parent gitlink and `VOID_PACKAGES_COMMIT` together.

Frozen-input creation uses the separate build checkout. New restores recreate
that layout. Older saved projects retain their
original layout and scripts; the frozen 0.1.0 release is untouched. Restore
compatibility tests do not imply a new reproducibility or physical-hardware claim.

## Validation

Fresh checks for this change passed:

- `make bootstrap`, `make smoke-test`, and `make check`: migrated container use,
  ARM/glibc package compilation, static-musl compilation, clean upstream state,
  exact overlay/cache preservation, shallow pin updates, rejection of independent
  edits and source conflicts, and cleanup protections.
- `make workstation-test`: `out/workstation-images.ckkodex6`; real Void source
  builds from `.host/void-packages`, image validation and confirmed file write/readback.
  Selecting the upstream submodule as a build target is rejected without writes.
- `make emulator-test`: `out/emu-test.op5azhlm`; full twelve-bay PROGRAM/DATA,
  foreground terminal, eject/unplug, legacy reading and service-restart checks.
- `make release-contract-test`: `out/m12-release-contracts.wmsfrcl0`; both separate
  and legacy frozen-layout restores, retained source caches, local offline
  repositories and existing tamper/release-comparison checks.
- Documentation links, formatting, Python syntax and a final empty upstream Git
  status, including ignored files, were checked.

Logs are in `out/logs/void-workspace/`; source and log hashes, pins, native binary
hashes and fixture results are recorded in `out/manifests/void-workspace-acceptance.json`.
The optional host-native ARM execution shortcut was skipped in smoke-test. ARM
execution was exercised by the full emulator suite. Physical hardware was not used.

The first emulator attempt (`out/emu-test.463emq8u`) failed on an empty cartridge
IPC response during initial discovery in its admin VM. The complete rerun passed
without target-system changes. SYSTEM, kernel and initramfs hashes matched the
previous accepted inputs. The cause of that first response failure was not
established; its command/serial logs are retained. Future failures now collect
live service diagnostics before VM shutdown, without retrying failed commands
or relaxing their acceptance conditions.