FDS/OS 1.0 fixes

2026-09-23 03:12:45 +08:00
parent 8a4788fca8
commit 6bfcce8070
23 changed files with 403 additions and 40 deletions
@@ -0,0 +1,77 @@
+# 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.