diff --git a/GOALS-archive.md b/GOALS-archive.md index 5c0ee05a..8e8a1991 100644 --- a/GOALS-archive.md +++ b/GOALS-archive.md @@ -206,3 +206,7 @@ Acceptance: punk::zip extracts to a target directory from (a) a plain zip, (b) a ### G-125 [achieved 2026-07-27] A kit that cannot boot is not deployed: extraction failure gates the bake instead of warning past it → detail: goals/archive/G-125-unbootable-kit-deploy-gate.md Scope: src/make.tcl (kit extraction outcome handling, deploy step gating, the no-extraction BUILD-WARNING as the current behaviour being replaced); src/modules/punkboot/utils-999999.0a1.0.tm (the boot-precondition predicate, called guardedly from make.tcl as vcs_dirty_warnings is); src/tests/modules/punkboot/utils/ (predicate characterization over directory fixtures); src/tests/shell/testsuites/punkexe/ (characterization of the make.tcl-side gate reporting); src/AGENTS.md (bake failure-mode documentation) Acceptance: when extraction from the source runtime yields nothing and the kit's .vfs does not itself supply a bootable tcl library, the kit is recorded in FAILED KITS with a reason naming the cause and NEITHER src/_build nor bin receives a new artifact - the previously deployed kit is left untouched, verified by mtime and byte comparison across such a run; a kit whose .vfs legitimately supplies its own tcl library still builds and deploys, so the gate tests for the boot precondition rather than for the extraction step having run; the check is cheap enough to run on every kit and executes no artifact; the condition and its remedy are documented in src/AGENTS.md; existing punkexe suites pass unchanged and the gate itself is characterized. + +### G-129 [achieved 2026-07-27] Kit boot finds its payload wherever the archive mounted, not only at //zipfs:/app → detail: goals/archive/G-129-kitboot-mountpoint-derivation.md +Scope: src/vfs/_config/punk_main.tcl and src/vfs/_config/project_main.tcl (vfs capability detection plus mount-point derivation for the kit's internal module/lib path assembly - both carry the same code today); src/runtime/mapvfs.config (an active kit entry per verification runtime); bin/runtime/win32-ix86/ (the two third-party 32-bit runtimes that verify it - read-only input); src/tests/shell/testsuites/punkexe/ (characterization of the derivation); src/AGENTS.md + bin/AGENTS.md (what a runtime must provide to be kit-wrappable) +Acceptance: a kit baked from a runtime that mounts its attached archive at the executable's own path boots and resolves its own payload with no external package paths in play - the kit's internal modules/ and lib/ trees appear in tcl::tm::list and auto_path and a package that exists only inside the kit resolves - with bin/runtime/win32-ix86/tclsh8.6.10-luck-zip.exe recorded here as that verification runtime; a kit baked from bin/runtime/win32-ix86/tclsh9.1b0-tclsfe.exe (32-bit, modern //zipfs:/app convention) boots the same way, proving the 32-bit target itself needs nothing special and that the derivation did not regress the ordinary case; punkshell's existing 64-bit kits are unaffected, verified by comparing each kit's internal tcl::tm::list and auto_path entries before and after the change across at least one zipfs kit and one starkit-family kit (identical); a runtime that has an attached archive the boot cannot locate says so on stderr rather than continuing silently with no internal paths, which is today's failure shape; and the runtime requirements for kit-wrapping - which zipfs commands and mount conventions are supported - are documented in bin/AGENTS.md. diff --git a/GOALS.md b/GOALS.md index 4df32e08..c02c7dd8 100644 --- a/GOALS.md +++ b/GOALS.md @@ -403,10 +403,6 @@ Detail: goals/G-127-crosstarget-vfs-bake.md Scope: src/tools/punkres/ (vendored zig source - tool name settled in the work - with provenance and licence records); src/make.tcl (mechanism selection at the G-057 seam, sharing G-126's tool build step); bin/tools/zig* (pinned toolchain as consumed); bin/punkres.exe (untracked build output); src/tests/ (characterization - icon replaced, payload intact, idempotent, overlay-unsafe refusal); TEMP_REFERENCE/tcl-sfe (read-only reference for the resource structures) Detail: goals/G-128-portable-pe-resource-stamping.md -### G-129 [active] Kit boot finds its payload wherever the archive mounted, not only at //zipfs:/app -Scope: src/vfs/_config/punk_main.tcl and src/vfs/_config/project_main.tcl (vfs capability detection plus mount-point derivation for the kit's internal module/lib path assembly - both carry the same code today); src/runtime/mapvfs.config (an active kit entry per verification runtime); bin/runtime/win32-ix86/ (the two third-party 32-bit runtimes that verify it - read-only input); src/tests/shell/testsuites/punkexe/ (characterization of the derivation); src/AGENTS.md + bin/AGENTS.md (what a runtime must provide to be kit-wrappable) -Detail: goals/G-129-kitboot-mountpoint-derivation.md - ### G-130 [proposed] 32-bit windows runtimes from the buildsuites, both Tcl generations Scope: src/buildsuites/suite_tcl90/ and src/buildsuites/suite_tcl86/ (the win32-ix86 target invocation and any recipe or flag divergence 32-bit forces); src/buildsuites/ (target dimension as settled by G-105 - no per-target tree copies); bin/runtime/win32-ix86/ (output tier - already holds the third-party comparison runtimes); punkbin per-target artifact layout with G-103 metadata carrying the target Detail: goals/G-130-32bit-windows-buildsuites.md diff --git a/goals/G-024-mapvfs-toml.md b/goals/G-024-mapvfs-toml.md index 1d9be3c1..76e1456e 100644 --- a/goals/G-024-mapvfs-toml.md +++ b/goals/G-024-mapvfs-toml.md @@ -62,7 +62,9 @@ with the G-014 direction of toml + tomlish for declared configuration. - Design direction from the developer, recorded 2026-07-27: the toml move is where NAMED GROUPINGS of entries should be considered, since toml gives the structure the current line format cannot. The prompt for it was verification kits - two third-party 32-bit - runtimes were added to the win32-ix86 tier to verify G-129's boot-mount derivation, and + runtimes were added to the win32-ix86 tier to verify G-129's boot-mount derivation + (achieved 2026-07-27 - see goals/archive/G-129-kitboot-mountpoint-derivation.md; the + entries are punkluck86 + punk91ix86), and they want to sit as active entries while being obviously a verification set rather than shipped products. Grouping would also give `make.tcl bake` and `bakelist` a name to select on beyond per-kit names (the G-121 selective-bake surface takes kit names today), diff --git a/goals/G-101-tcl86-kit-container-strategy.md b/goals/G-101-tcl86-kit-container-strategy.md index 1eb8203b..9732bec6 100644 --- a/goals/G-101-tcl86-kit-container-strategy.md +++ b/goals/G-101-tcl86-kit-container-strategy.md @@ -336,7 +336,10 @@ to the suite-built 8.6 runtime, as undroidwish does. `tcl::zipfs::root`, cannot call a bare `zipfs`, and must not assume a codethread can see zipfs at all. - MOUNT CONVENTION: it mounts the executable's attached archive at the EXECUTABLE'S - OWN PATH, not at `//zipfs:/app` - the reason G-129 exists. + OWN PATH, not at `//zipfs:/app` - the reason G-129 exists (achieved 2026-07-27 - see + goals/archive/G-129-kitboot-mountpoint-derivation.md: the boot now derives the mount + base from the runtime's own mount table, and the undroidwish family's `app/main.tcl` + in-archive startup hook is served by a second fauxlink in punk8win.vfs). - WHERE THE SELF-MOUNT LIVES IS AN OPEN QUESTION. Stock `win/tclAppInit.c:192` and `unix/tclAppInit.c:130` call `Tclzipfs_Init` only under `#ifdef TCL_TEST`, so the boot-time self-mount is in the vanillatclsh/undroidwish application main rather diff --git a/goals/G-123-thirdparty-runtime-tiers.md b/goals/G-123-thirdparty-runtime-tiers.md index b940cbe4..be32e9b9 100644 --- a/goals/G-123-thirdparty-runtime-tiers.md +++ b/goals/G-123-thirdparty-runtime-tiers.md @@ -96,3 +96,9 @@ see goals/archive/G-058-static-runtime-packages.md). - Signing deferred by user decision 2026-07-26 ("server trust ... with signing for down the track") - flag a dedicated signing/attestation goal when the first genuinely external tier or server appears. +- G-129 (archived) wrote the kit-wrappable runtime requirements into + bin/AGENTS.md ("Kit-wrappable runtime requirements (G-129)") - the + criterion this goal's publication decisions would cite - and left the two + win32-ix86 third-party specimens wrapped as active verification kits + (punkluck86 / punk91ix86); see + goals/archive/G-129-kitboot-mountpoint-derivation.md. diff --git a/goals/G-129-kitboot-mountpoint-derivation.md b/goals/G-129-kitboot-mountpoint-derivation.md index 56be7c84..d6a1fa8b 100644 --- a/goals/G-129-kitboot-mountpoint-derivation.md +++ b/goals/G-129-kitboot-mountpoint-derivation.md @@ -1,6 +1,6 @@ # G-129 Kit boot finds its payload wherever the archive mounted -Status: active +Status: achieved 2026-07-27 Scope: src/vfs/_config/punk_main.tcl and src/vfs/_config/project_main.tcl (vfs capability detection plus mount-point derivation for the kit's internal module/lib path assembly - both carry the same code today); src/runtime/mapvfs.config (an active kit entry per verification runtime); bin/runtime/win32-ix86/ (the two third-party 32-bit runtimes that verify it - read-only input); src/tests/shell/testsuites/punkexe/ (characterization of the derivation); src/AGENTS.md + bin/AGENTS.md (what a runtime must provide to be kit-wrappable) Goal: a punk kit boots from wherever its attached archive actually mounted, so a runtime whose zipfs mounts at the executable's own path rather than at //zipfs:/app - as the androwish/undroidwish 8.6 backport does - yields a kit that finds its own modules and libs. The boot derives the mount point from the runtime's own mount list and detects zipfs by a command every generation provides, instead of keying on tcl::zipfs::root (a 9-era command absent from the 8.6 backport) and a compiled-in //zipfs:/app. Acceptance: a kit baked from a runtime that mounts its attached archive at the executable's own path boots and resolves its own payload with no external package paths in play - the kit's internal modules/ and lib/ trees appear in tcl::tm::list and auto_path and a package that exists only inside the kit resolves - with bin/runtime/win32-ix86/tclsh8.6.10-luck-zip.exe recorded here as that verification runtime; a kit baked from bin/runtime/win32-ix86/tclsh9.1b0-tclsfe.exe (32-bit, modern //zipfs:/app convention) boots the same way, proving the 32-bit target itself needs nothing special and that the derivation did not regress the ordinary case; punkshell's existing 64-bit kits are unaffected, verified by comparing each kit's internal tcl::tm::list and auto_path entries before and after the change across at least one zipfs kit and one starkit-family kit (identical); a runtime that has an attached archive the boot cannot locate says so on stderr rather than continuing silently with no internal paths, which is today's failure shape; and the runtime requirements for kit-wrapping - which zipfs commands and mount conventions are supported - are documented in bin/AGENTS.md. @@ -33,7 +33,7 @@ bracket the problem: | provenance | Lean Undroidwish Construction Kit | apnadkarni/tcl-sfe releases | | Tcl | 8.6.10 | 9.1b0 | | `tcl::zipfs::root` | absent | `//zipfs:/` | -| `::zipfs` ensemble | absent | present | +| `::zipfs` ensemble | present, but no `root` subcommand (corrected 2026-07-27) | present | | mount point | `` | `//zipfs:/app` | | `[info library]` | `/tcl8.6` | `//zipfs:/app/tcl_library` | | zipfs in child/thread interps | none | present | @@ -139,3 +139,73 @@ the source tree, not from a kit payload - which is what made the gap easy to mis that have to be dropped in, and no single source ships current Tcl for both major versions. That is separate work; this goal only ensures a 32-bit third-party runtime can carry a kit, and leaves two verification specimens in the win32-ix86 tier for it. + +## Progress + +2026-07-27 - implemented and verified in one pass; every Acceptance clause met +(implementation commit 191d8ff4, punkshell 0.28.0). Detail: + +- Boot derivation (punk_main.tcl + project_main.tcl, identical copies): zipfs presence + keys on `tcl::zipfs::mount`; the mount base comes from the new factored + `::punkboot::zipfs_kit_mountbase` (mount-table entry whose archive file is + `[info nameofexecutable]`, accepting the backport's drive-prefix-stripped spelling; + fallback = the mount containing `[info script]`; helpers `zipfs_mount_pairs` + + `path_within`; all remain defined post-boot for probing). The starkit quick-search line + that called `[zipfs root]/app/tcl_library` (an ERROR on the backport - no root + subcommand anywhere) uses the derived base; internal_paths gains the derived base when + no zipfs volume root covers it; the internal-only simulate-kit discriminator recognises + a script under the derived mount as kit-internal. starkit/cookfs branches untouched, + per Approach. +- Measured mount tables: both generations return flat {mountpoint archivefile} pairs. + LUCK 8.6.10 backport: mountpoint = the exe path itself, archive-file column WITHOUT the + windows drive prefix (/repo/... for C:/repo/...). tcl-sfe 9.1b0/9.0.x: //zipfs:/app + + full exe path. +- Boot-script hook (the second blocker, found during verification): the LUCK/undroidwish + family only auto-runs `app/main.tcl` INSIDE the attached archive (embedded + `/app/main.tcl` string in the exe) and ignores a root main.tcl - without it the kit + fell through to stock tclsh argv handling and main.tcl never ran. punk8win.vfs now + carries an `app/main.tcl` fauxlink beside the root one. Enabling that nested fauxlink + required make.tcl's merge_over to resolve fauxlink targets against the link file's own + directory (the fauxlink module's documented symlink semantics; identical for the + root-level links that were previously the only ones). +- Scope extension (flagged for user ratification, G-125 precedent): src/make.tcl was + necessarily touched - the runtime capability probe keyed has_zipfs on tcl::zipfs::root + (same defect class on the build side: it refused zip assembly for the backport with + "runtime ... doesn't have zipfs capability"; the block also rode a body-less + `if {![catch ..]}` that only worked because piped-stdin tclsh continues past command + errors) and the merge_over fauxlink base fix above. Also outside drafted Scope: + src/vfs/punk8win.vfs/app/ (the new fauxlink), src/vfs/AGENTS.md, + src/tests/shell/AGENTS.md, ARCHITECTURE.md (docs), and the layout/templates-modpod + synced copies of the boot mains + make.tcl. +- Kit names (agent-chosen, open to rename): punkluck86 / punk91ix86. + +### Verification records (2026-07-27) + +- bin/punkluck86.exe (LUCK runtime + punk8win.vfs, zip concat assembly): boots from the + exe-path mount; tcl::tm::list carries /modules; auto_path carries /lib + + /lib_tcl8 plus the runtime's own archive-internal trees (tcl8.6, tcl8/8.x - + correctly classified internal now); punk::args 0.12.7 resolves from + /modules/punk/args-0.12.7.tm; TCLLIBPATH-derived external paths stripped (default + internal mode); the `script` subcommand runs app-punkscript from the payload. Remaining + noise is expected 32-bit/8.6.10 degradations (no usable twapi -> is_interactive warning, + tsv unavailable notes), not boot-path issues. +- bin/punk91ix86.exe (tcl-sfe 9.1b0 32-bit + punk9win_for_tkruntime.vfs): modern + //zipfs:/app trees, punk::args from inside the mount, clean stderr - the 32-bit target + itself needed nothing special. +- 64-bit kits unaffected: punk905 + punk902z (zipfs) and punksys + punk86 (starkit + family) rebaked with the new boot; full probe output (tcl::tm::list + auto_path + + stderr) byte-identical to pre-change captures of the deployed kits. punk86 also + carries the new inert app/main.tcl payload file - no path or behaviour change. +- Attached-but-unattributable stderr report: tclkit902 (zipfs commands, empty mount + table) with a freshly mkzip'd foreign archive mounted, then sourcing the working-tree + punk_main.tcl - reports the archive and full mount table on stderr, continues booting + on the metakit branch, and the foreign mount contributes no kit paths. +- Both zip offset conventions boot on the backport: the deployed concat kit AND a + zipfs-mkimg (file-relative offsets) image of the same tree both mount and resolve - + recorded in bin/AGENTS.md so future zipfs-capable-host bakes are known-safe. +- Characterization: src/tests/shell/testsuites/punkexe/kitmountpoint.test (4/4; + self-gates on the untracked runtimes); punkexe subtree 69 tests, 0 fail; full suite + 1171 tests with only the documented exec-14.3 baseline failure. +- Runtime requirements documented: bin/AGENTS.md "Kit-wrappable runtime requirements + (G-129)" + src/AGENTS.md pointer, src/vfs/AGENTS.md boot contract, ARCHITECTURE.md + boot-chain bullet, src/tests/shell/AGENTS.md suite doc. diff --git a/goals/G-130-32bit-windows-buildsuites.md b/goals/G-130-32bit-windows-buildsuites.md index 9c1ba58e..3fa78e9e 100644 --- a/goals/G-130-32bit-windows-buildsuites.md +++ b/goals/G-130-32bit-windows-buildsuites.md @@ -67,9 +67,11 @@ the other's generation. - Related: G-123 - the artifacts publish through the runtime-tier mechanism, and `punk-runtime.cmd list -platform win32-ix86` is where a user would see suite-built runtimes appear beside the third-party ones. -- Related: G-129 - the third-party 8.6 specimen in this tier is what exposed punkshell's - kit-boot mount-point assumption. That is a boot-path concern and separate from producing - the runtime, but both goals use the same two specimens. +- Related: G-129 (achieved 2026-07-27 - see goals/archive/G-129-kitboot-mountpoint-derivation.md) + - the third-party 8.6 specimen in this tier is what exposed punkshell's kit-boot + mount-point assumption. That is a boot-path concern and separate from producing the + runtime, but both goals use the same two specimens, now wrapped as the active + verification kits punkluck86 + punk91ix86. - Related: G-018 (superseded) - plain zig-built tclsh kits carrying no punk infrastructure; the same "punkshell as a Tcl supplier, not only a shell" direction this goal serves. - `punk::platform::local` already reports `win32-ix86` correctly from a 32-bit interpreter diff --git a/goals/G-131-boot-payload-autodetection.md b/goals/G-131-boot-payload-autodetection.md index db9fdf32..950c772f 100644 --- a/goals/G-131-boot-payload-autodetection.md +++ b/goals/G-131-boot-payload-autodetection.md @@ -33,9 +33,10 @@ independently-written branches. ## Approach -- Extend, do not rewrite. G-129 lands the zipfs derivation and unblocks third-party kit - baking on its own; this goal generalises the same step to metakit and turns the branch - set into one detection decision. +- Extend, do not rewrite. G-129 (achieved 2026-07-27 - see + goals/archive/G-129-kitboot-mountpoint-derivation.md) landed the zipfs derivation and + unblocked third-party kit baking on its own; this goal generalises the same step to + metakit and turns the branch set into one detection decision. - PREINIT-SHAPED FROM THE START. G-101's Tcl 9 survey found that the `proc tclInit` override - which is what the tclkit lineage's boot.tcl IS - is dead in 9.1 (tclInterp.c:619-622) and `tcl_libPath` is gone. A design that works on both generations @@ -95,3 +96,12 @@ independently-written branches. probes `runtime_caps` for has_zipfs/has_starkit/has_cookfs and treats disagreement with the target kit type as an error condition; with both-capability runtimes that disagreement becomes the normal case. +- G-129 (archived) recorded material this goal builds on - see + goals/archive/G-129-kitboot-mountpoint-derivation.md: the derivation is already factored + as the requested standalone step (`::punkboot::zipfs_kit_mountbase` + `zipfs_mount_pairs` + + `path_within`, defined post-boot) so the metakit arm can be added beside it; the + measured mount-table shapes for both zipfs generations and the undroidwish-family + `app/main.tcl` in-archive startup hook (punk8win.vfs carries fauxlinks for both boot + conventions) are in its Progress records; and make.tcl's capability probe now keys + has_zipfs on `tcl::zipfs::mount` (the LUCK backport probes has_zipfs 1 + has_starkit 1 - + already a both-capability row this goal's mismatch-check work must accommodate).