punkshell/goals/G-111-modpod-tidy-tests.md

G-111 modpod tidy: fix/remove tar-era remnants + first test baseline

Status: achieved 2026-08-03 Scope: modpod canonical source (c:/repo/jn/tclmodules/modpod fossil checkout, src/modules/modpod-999999.0a1.0.tm) with re-vendor into shellspy (src/vendormodules/modpod-.tm + bootsupport copies via established channels); punkshell-side tarjar artifacts ASSESSED ONLY (cli #tarjar- module-type branch, libunknown skip-globs, vendored tarjar-2.4.3.tm, src/modules/_build/#tarjar-tarjar-2.3 - dispositions individually user-confirmed, preservation-aware per the c:/tclmodules/main manual-migration intent); new modpod testsuite (home settled in the work; shellspy src/tests/modules/ harness is the natural fit) Goal: modpod's surviving zip-based surface is sound and tested: the tar-era broken/dead code inside the modpod module is fixed or removed with each item dispositioned, tarjar-SYSTEM artifacts elsewhere get user-confirmed preservation-aware dispositions only (old tarjar material at c:/tclmodules/main is preserved/migrated manually by the user, outside this goal), and modpod gains its first test baseline covering wrap and load round-trips including a binary payload. Acceptance: each enumerated tar-era defect in modpod-999999.0a1.0.tm is dispositioned with the outcome recorded here (undefined tar::readHeader connect path; ::tarjar::connected reference in myfullname; con/connected and versionpart/versionparts typos; the malformed set/lindex constructs; connect's debug stderr puts; get's unimplemented wrapped branch); after the pass a grep of the modpod module for tarjar returns nothing or only deliberate keeps recorded here; punkshell-side tarjar artifacts each carry a recorded keep/remove/migrate disposition explicitly confirmed by the user, with none deleted absent that confirmation; a modpod testsuite exists and passes on the tcl9 kit and on 8.6 (or the 8.6 limitation is recorded per G-034), covering make_zip_modpod wrap then package require from a real-disk module path and from a zipfs module path, a binary-payload load, the unwrapped #modpod-folder redirect form, and both -offsettype forms; the fixed module is re-vendored into shellspy with the suite passing there.

Context

Drafted 2026-07-21 during the modpod binary-.tm characterization session (G-066 Notes hold the characterization; G-109/G-110 were split out of the same session). The user: modpod "was beaten into shape from [the] earlier tarjar system that operated on .tm files that were tar archives ... there may be cruft from the earlier iteration that we should tidy, and I'm not sure what tests are in place for modpod."

TEST FINDING: none exist anywhere. The modpod project (c:/repo/jn/tclmodules/modpod, fossil-only like tomlish - vendor-into- shellspy workflow) has no test directories; shellspy has no modpod suites (nearest neighbour is src/tests/modules/zipper - a different module, and the natural harness precedent for where modpod suites can live). The zip surface that works today (modpod::lib::make_zip_modpod + the self-mount stub + modpod::system::make_mountable_zip) was proven by the 2026-07-21 characterization runs but has zero automated coverage.

DEFECT INVENTORY (canonical modpod-999999.0a1.0.tm, line refs at drafting; the tar-era connect/get family is dead-or-broken while the zip stub path is the live surface):

• L102: puts stderr "modpod::connect--->>$args" debug output in connect.
• L144: set con(type,...) typo for connected (writes a stray array); ~L170 compounds it ($con(package,$modpod) - undefined var references).
• L149-150: malformed set unwrapped_tm_file [file join ...] "..." (3-arg set - runtime error if reached) followed by a value-less set connected(tmfile,$modpodpath) (reads an unset entry).
• L194: connect's tar path calls ::modpod::system::tar::readHeader - no tar namespace exists anywhere in the file (caught, so every wrapped-tar connect falls through to "not a valid modpod").
• L294: is_valid_tm_version uses $versionparts vs its $versionpart argument - the substitution error fires BEFORE the catch, so the proc always errors.
• L598: connect_if_not has misplaced brackets ([lindex [modpod::connect $podpath]] 0]) - runtime error when reached.
• L652: myfullname returns $::tarjar::connected(fullpackage,$script) - always errors under modpod.
• get: wrapped-pod branch is a "not implemented" stderr stub.
• tarjar-named comments/messages/placeholder token (L632/647/650/659) - cosmetic; disposition = rename or deliberate-keep note.

TARJAR-SYSTEM INVENTORY (assess-only in this goal; per the user 2026-07-21, old tarjar material at c:/tclmodules/main - which also holds the intermediate 'tarpack' generation (tarpack-1.1.x + loadscripts; lineage tarjar -> tarpack -> modpod) - is to be PRESERVED and partly migrated manually, so nothing here is deletable cruft by default):

• src/vendormodules/tarjar-2.4.3.tm (a tar-format .tm; carries the .TclSoCache code recorded as G-110 prior art) + _aside/tarjar-2.3.tm.
• src/modules/_build/#tarjar-tarjar-2.3/ unwrapped tree (docs, todo, loadscript, loader snippets) + _build/tarjar-2.3.tm.
• punk::mix cli-999999.0a1.0.tm: #tarjar-* module-type build branch (~L240/719-796/1037) - dead if no #tarjar source dirs remain in scanned trees, but coupled to the preservation question.
• libunknown skip-globs for #tarjar-* (harmless/defensive - likely keep).

Relationships: precursor to G-109 (manifest emission edits the same module - tidy first so it lands on sound code); G-066/G-067 (modpod generation + publish consumers); G-110 (tarjar .TclSoCache prior art lives inside the vendored tarjar tm - preserve access to it); G-034 (8.6 mount path - the 8.6 leg of the testsuite).

Progress

2026-08-03 tidy pass landed in the canonical module (modpod checkout src/modules/modpod-999999.0a1.0.tm, buildversion -> 0.1.6). Disposition per enumerated defect:

• connect's debug stderr puts (L102): REMOVED with connect.
• con/connected typo (L144) + its ~L170 compound ($con(package,$modpod)): REMOVED with connect.
• malformed set constructs (L149-150, 3-arg set + value-less set): REMOVED with connect.
• undefined tar::readHeader connect path (L194): REMOVED with connect.
• versionpart/versionparts typo (L294): FIXED in place - is_valid_tm_version now catches a braced [package vcompare] of its real argument; returns 1/0 correctly (verified both ways).
• connect_if_not misplaced brackets (L598): REMOVED - proc deleted (its only caller was get).
• myfullname's $::tarjar::connected reference (L652): REMOVED - proc deleted, and myname with it (both depended on the connect registry).
• get's unimplemented wrapped branch: REMOVED - proc deleted.
• tarjar-named comments/messages/placeholder (L632/647/650/659): REMOVED; tilde token renamed <modpod_tilde_placeholder>. Post-pass grep of the module for tarjar (case-insensitive): ZERO hits - no deliberate keeps.

Whole-proc summary: connection API removed entirely (connect, disconnect, get, system::connect_if_not, system::myname, system::myfullname) - zip modpods are self-mounting and no caller of the registry exists anywhere in shellspy or the modpod checkout (survey 2026-08-03: only modpod's own synced copies and commented-out loadscript lines reference these names).

Additional items dispositioned in the same pass (not in the drafted inventory):

• connected(to) init bug (literal string "list") + unused modpodscript / connected(self) / loadables / sourceables variables: REMOVED with the registry.
• make_mountable_zip debug output REMOVED: three stderr EOCD dumps, per-item central-directory header dumps including ansistring VIEW (an undeclared dependency - made -offsettype file ERROR under the module's declared deps), duplicate mid-branch showdict, stray ::last_header global write. The catch-wrapped end-of-run showdict report is retained unchanged.
• struct::set dependency DROPPED (only connect used it; the stub carries its own inline intersect).
• myversion KEPT (standalone and working): dead upvar ::modpod::connected and tar-era comment removed. Pre-existing limitation noted, out of scope: its scan %[a-z] classes misparse package names containing digits or underscores (e.g. win32_x86_64_tcl8).
• STUB ADDITION (required by this goal's acceptance, and promised by the stub's own comments): unwrapped redirect - an extracted #modpod-- folder (exact name-version match) beside the .tm is sourced directly BEFORE any mount attempt, giving a zero-dependency load path when neither zipfs nor vfs::zip is available (G-034-relevant).

Smoke evidence (bin/punk91 src, tcl 9.1, 2026-08-03): wrap via punk::zip::mkzip + make_zip_modpod then require -> zipfs mount load + data read OK (archive offsets); unwrapped-redirect load with NO mount OK; -offsettype file wrap + mount load OK; API surface checks (removed procs gone, kept procs present) OK.

2026-08-03 testsuite + re-vendor landed:

• Suite: src/tests/modules/modpod/testsuites/modpod/roundtrip.test (the module's first tests). Fixture pods generated per run (no committed binaries); child processes of [info nameofexecutable] (kit 'script' subcommand or plain script-file dispatch, probed script-form-first). Covers: wrap emits stub+zip (\x1A separator, PK header), fixed is_valid_tm_version both ways, require from real-disk module path (archive offsets), -offsettype file form, unwrapped #modpod-folder redirect (exact extracted path asserted, no #mounted-modpod- signature), probe-discovered dll payload loading from the mounted pod in a fresh child, and tm-on-zipfs-path (zip-in-zip container).
• Results: punk91 (tcl 9.1 kit) 7/7 PASS; native tclsh90 (9.0.3) 7/7 PASS; punk86 (8.6.17 kit) 6 pass / 1 skip / 0 fail - the skip is modpod-4.1 (zipfs module path), gated on childzipfs: RECORDED LIMITATION per G-034 - Tcl 8.6 has no zipfs, so the tm-inside-a-zip-container form needs it; the disk-tm forms load via the stub's vfs::zip fallback (verified by the passing 2.x tests) and the BINARY payload loads on 8.6 too (modpod-3.1 PASS - tclvfs copy-to-temp load path).
• Re-vendor chain (established channels): modpod checkout mint via its own make.tcl (tclsh90, modules/modpod-0.1.6.tm, 0.1.5 pruned; stamp-only diff vs canonical verified) -> src/vendormodules/modpod-0.1.6.tm (0.1.5 removed) -> make.tcl bootsupport (src/bootsupport/modules 0.1.6, 0.1.5 pruned) -> make.tcl modules (root modules staging 0.1.6; the mint itself exercised make_zip_modpod 0.1.6 over the repo's #modpod-* trees) -> make.tcl vfscommonupdate (src/vfs/_vfscommon.vfs/modules 0.1.6) -> bake.
• Observation: runtests' own environment registers unwrapped #modpod-* source trees via package ifneeded (runtestmodules.tcl boot lines) - the harness itself consumes the unwrapped form.

2026-08-03 ACHIEVED FLIP: all acceptance items verified met - per-defect dispositions recorded above with the module grepping tarjar-free (zero keeps); suite green on punk91 tcl9.1 kit (7/7), native tclsh90 (7/7) and punk86 8.6.17 (6/7, modpod-4.1 zipfs-container skip recorded per G-034 - the 8.6 limitation clause); 0.1.6 re-vendored with the suite passing in shellspy (git bba10012 / fossil 1b803031; kits rebaked, both report 0.1.6); tarjar-artifact dispositions below CONFIRMED by the user 2026-08-03 ("all five as proposed"), none deleted.

Tarjar-system artifact assessment (2026-08-03; dispositions CONFIRMED by user 2026-08-03, all five as proposed)

Inventory verified on disk; VCS tracking checked in both git and fossil. Nothing deleted. Confirmed dispositions:

1. src/vendormodules/tarjar-2.4.3.tm (TRACKED git+fossil; contains the .TclSoCache prior art G-110 references): KEEP - the G-110 investigation needs it accessible; migration to c:/tclmodules/main remains the user's manual lane. Channel fact (found 2026-08-03): this file is vendorupdate-managed - src/vendormodules/include_modules.config lists c:/repo/jn/tarjar/modules tarjar, so a live tarjar source repo exists at c:/repo/jn/tarjar and a removal decision would also cover that config line.
2. src/vendormodules/_aside/tarjar-2.3.tm (untracked, machine-local): KEEP IN PLACE pending the user's manual preserve/migrate to c:/tclmodules/main (per the tarjar preservation intent; no VCS presence to tidy).
3. src/modules/_build/#tarjar-tarjar-2.3/ tree + _build/tarjar-2.3.tm (untracked, machine-local; richest historical material - DESCRIPTION, CHANGES, README.tarjar.txt, todo.txt, loadscript, codesnippets): KEEP IN PLACE pending user-manual migrate to c:/tclmodules/main (G-155, achieved - see goals/archive/G-155-mint-stage-vocabulary.md - already records _build leftovers as deliberate).
4. punk::mix cli-999999.0a1.0.tm #tarjar-* build branch (~L1048-1300 + tarjarglob plumbing): KEEP for now - dead in practice (the only #tarjar-* dir on disk is under src/modules/_build, one level below the scanned source dirs, so the branch never fires) but coupled to the preservation question; removal is a cheap later tidy once the user's migration completes.
5. punk::libunknown skip-globs for #modpod-/#tarjar-/_build (libunknown-*.tm deep-scan filter): KEEP - the #modpod glob is required regardless; the #tarjar glob is defensive and free.

Notes

• 2026-07-21: drafted from the session findings and approved (user: "approved - apply G-111").
• G-029 relationship (recorded 2026-07-24 after overlap review): its testmodpod generation exercises the same wrap+load round-trips this goal's baseline pins - the two suites share fixtures where sensible.
• 2026-08-03: ACTIVATED at user request. Activation-freshness overlap survey re-run (goals_xref score G-111): existing refs (G-034/G-066/G-067/G-109/ G-110/G-029) stand. Goals drafted since: Related: G-114 (per-platform tm roots - its acceptance names a modpod demonstration artifact consuming the wrap surface this goal pins). Related: G-156 (alpha-window census lists the modpod repo in its fork/tool-repo lane - rename-window coordination only, no code overlap).