punkshell/goals/G-099-suite-tcl86-buildsuite.md

G-099 suite_tcl86: zig buildsuite for core-8-6-branch (runtime, thread, tclvfs, core-test gate)

Status: active Scope: src/buildsuites/suite_tcl86/ (new: suite.tcl driver, 8.6 zig recipe + helper modules, expected_test_failures baseline); src/buildsuites/_build/ (untracked sources/outputs via existing globs); bin/tools/ (pinned zig as consumed); PUNK_FOSSIL_STORE / ~/.punkshell/fossils (hermetic clone store shared with suite_tcl90) Goal: a tracked suite_tcl86 buildsuite builds a Tcl 8.6 windows runtime from fossil core-8-6-branch sources using the pinned zig toolchain only (zig-only build policy; msys/mingw and MS toolchains remain test/validation-only), together with the core binary companions punkshell's Tcl 8 targets need - an 8.6-compatible thread branch and tclvfs - and gates the result against the 8.6 core testsuite via parsed all.tcl totals against a tracked, dispositioned expected-failure baseline, mirroring the suite_tcl90 gate mechanism. Acceptance: from the pinned zig and fetched core-8-6-branch sources (hermetic clone store, no MS toolchain) the suite produces a working tclsh86 executable and tcl86 dll with an installed lib tree the shell resolves without external Tcl installations (TCLLIBPATH/TCL_LIBRARY unset in all suite child invocations); an 8.6-compatible thread package and tclvfs build and load in that shell (versions recorded); suite.tcl test runs the 8.6 core testsuite, parses totals (exit codes not trusted), and gates against a tracked expected_test_failures baseline with every entry dispositioned with a reason - a full-run PASS deterministic across two consecutive runs is recorded in this file; an interactive-smoke record (script execution, package require checks) is captured here.

Context

Follow-on arc to G-096/G-098 (suite_tcl90, achieved 2026-07-20), per user direction 2026-07-20: "we need a similar set of goals around building for core-8-6-branch".

8.6 remains punkshell's real Tcl 8 target (punk86-class kits; 8.7 is unreleased dev convenience only). Today the 8.6 kits ride on prebuilt third-party runtimes (tclkit86bi.exe, tclkit-win64-dyn.exe) - a provenance and rebuildability gap this arc ultimately closes.

Known differences from suite_tcl90 to expect (assessments to verify at activation):

• NO zipfs in 8.6: no szip-style self-contained runtime is possible. This suite delivers exe + dll + on-disk lib tree only. Kit containment (metakit/cookfs/zipvfs candidates) is deliberately OUT of scope - see G-101.
• thread: trunk (3.x) targets Tcl 9; 8.6 pairs with the thread 2.8 branch - exact branch/tag selection to verify and pin.
• Source-tree/build differences vs the 9.0.5 recipe: 8.6's bundled zlib/libtommath arrangements differ; no tclUuid.h; manifest/rc generation to re-derive from 8.6's win/makefile.vc; TCL_BROKEN_MAINARGS-era entry-point handling differs from the mingw-unicode-entry work done for 9.0.5. Helper modules (build_zlib, build_libtommath, wrapfiletofile) reusable where the trees align - assess rather than assume.
• Test gate: a separate 8.6 expected_test_failures baseline (failure census unknown until the first full run; the 9.0.5 census does not transfer). Machine traits already dispositioned for 9.0.5 (OS username vs profile dir, admin shares) will likely reappear under their 8.6 test names.
• 8.6 has no tcl::process: runtests -jobs child handling falls back to blocking execs (documented convoy behaviour) - the core-test gate runs via suite.tcl, not runtests, so this only affects later punkshell-suite work (G-100).
• Shared scaffolding: fossil_source/clone-store/env-hygiene conventions exist in suite_tcl90/suite.tcl. Factor shared parts out only when this second consumer makes the right shape obvious - avoid premature generalization; duplication with a note is acceptable at first.

SEQUENCING (2026-07-20 discussion): drafted as proposed while suite_tcl90 matures - recommendation is to complete G-096's remaining items (TCLSH_PIPEREPL patch rebase + behaviour matrix, punk-getzig per-version fetch) and run the punk905_beta interactive trial through to promotion before activating this goal, so the shared suite scaffolding settles before it is forked. Also weigh G-102 (zig-driver hybrid bootstrap, achieved 2026-07-21 - the driver shape is now SETTLED: pipeline as zig recipe steps, zon-pinned + fossil-checkout source flows converging on one staged invocation): its natural slot was before or alongside this goal so suite_tcl86 is born onto the chosen driver shape rather than ported later.

Progress

• 2026-07-25 activation + first increment (suite born on the settled driver shape, satisfying the G-104 contract by construction):
  • suite_tcl86/ created: sources.config (source records + G-104 description/product/doc/zigpin self-description records), suite.tcl (forked from suite_tcl90 per the duplication-with-a-note posture; log/fail prefix derives from the folder name, required sources {tcl tclthread tclvfs}, recipe file build86.zig, build steps default {install}), build86.zig (deliberate pending-derivation skeleton - staging succeeds, the recipe fails with a clear G-099 message), build.zig.zon (real content-hashed pins fetched with the pinned zig 0.16.0), README.md (deliverables, selections, DERIVATION record).
  • THREAD 2.8 SELECTION: thread-2-8-branch, tip checkin e14fa771ae tagged thread-2-8-13 (2.8.13, 2026-04-30); the checkout's configure.ac guards TCL_MAJOR_VERSION == 8 (pairing confirmed from source). Dev flow rides the branch; the zon pins the 2-8-13 checkin.
  • 8.6 SOURCE RECORDS IN BOTH FLOWS: sources.config refs (tcl core-8-6-branch -> dir tcl86; tclthread thread-2-8-branch; tclvfs trunk - 1.4.2 era per the recorded tcl9-only forTcl9 decision) and build.zig.zon per-checkin pins (tcl 1d1d5cbd91 = 8.6.18 era, thread e14fa771ae, tclvfs 9954261983) with zig-fetch hashes.
  • FIRST STAGING RUN through the G-104 surface ('make.tcl buildsuite build suite_tcl86'): checkouts staged from the shared hermetic clone store into _build/suite_tcl86 (TCL_PATCH_LEVEL "8.6.18" read from the staged tree), recipe fails at the skeleton as designed (exit status propagated through the surface). 'buildsuite list/info' show the suite with its own records.
  • RECIPE DERIVATION STARTED from the staged 8.6.18 win/makefile.vc - findings recorded in suite_tcl86/README.md DERIVATION, including two Context-assessment corrections: (a) 8.6.18 DOES generate tclUuid.h (makefile.vc 797-802 - the "no tclUuid.h" note was outdated); (b) the zlib arrangement is PREBUILT zdll.lib/zlib1.dll copies (not compiled) - the zig-only recipe compiles compat/zlib statically instead (decision recorded). TCLOBJS composition, in-tree libtommath, TCL_BROKEN_MAINARGS in win/tclAppInit.c, dde 1.4.6 / registry 1.3.5 versions recorded.
• Remains for acceptance: author build86.zig (COREOBJS/PLATFORMOBJS + defines, static zlib, tommath, manifest/rc step, entry-point handling), thread 2.8 + tclvfs build wiring, install-tree layout + hermetic resolution proof, suite.tcl test -> test-gate with parsed totals, FIRST CORE-TEST CENSUS and the dispositioned expected_test_failures.txt baseline (file deliberately not created until the census exists), two-consecutive-run deterministic PASS record, interactive-smoke record.

Notes

• Activation freshness 2026-07-25: goals_xref.tcl score G-099 re-run at the proposed->active flip (gate honoured: activated only after the G-112 rename core and G-104 self-description contract landed - both achieved earlier today). Top pairs G-100/G-105/G-101/G-116/G-108 all already linked or recorded (G-108 via the archive re-bridge Related line below); remaining unlinked hits are term noise - no new relationships.
• 2026-07-21 (user): SEQUENCING CONFIRMED - G-097 (achieved 2026-07-21) then G-103 (achieved 2026-07-22 - see goals/archive/G-103-runtime-kit-family.md) precede this arc - BOTH LANDED, the arc is unblocked; the suite_tcl86 fork is taken after the kit-family assembly steps exist in suite_tcl90 so the 8.6 suite is born expressing family products (and G-101 inherits a concrete payload contract).
• G-106 (archived) recorded a verification item for this arc's twapi-less 8.6 runtimes: the powershell console-mode fallback's disableraw-via-server path (the branch runtimes without -inputmode rely on to restore cooked mode) is coded but only tcl9-verified - run the G-106 recipe against a suite-built 8.6 runtime when one exists. See goals/archive/G-106-powershell-consolemode-fallback.md (Notes).
• G-104 relationship (recorded 2026-07-24; G-104 achieved 2026-07-25 - see goals/archive/G-104-maketcl-buildsuite-surface.md): the list/info/build surface and the sources.config self-description contract (description/product/doc/zigpin records, parsed by both suite.tcl and make.tcl) are live. suite_tcl86 must be BORN satisfying the contract (its sources.config carries the records from the first commit, so it lists and describes itself with no make.tcl edits) and its builds run via 'make.tcl buildsuite build suite_tcl86 ?driver-args?'.
• G-105 relationship: G-105's cross-target parameterization (zig -target) is inherited by this suite when it lands - the suite.tcl/recipe shape should not preclude a target dimension (per-target out prefixes, no per-target tree copies).
• Related: G-108 (debug buildsuite tier) - sibling suite-arc goal, queued behind this arc per user sequencing 2026-07-25; its -dbg/tcl::test debug-variant pattern is suite_tcl90-scoped, but the recipe shape this suite derives should not preclude a future 8.6 debug tier (recorded at the G-104 archive re-bridge - the pair's former bridges were all archived goals).
• G-005 relationship: G-005 owns the zig-build-of-binary-dependencies direction for the normal project build (vendored extensions, make.tcl-integrated); this suite is the arm's-length runtime-factory shape that direction took for Tcl cores. The two zig surfaces share the pinned-zig / zig-only toolchain policy; G-116's extension-build pattern is the living edge of G-005's expansion list.