# G-102 buildsuite bootstrap without a pre-existing tclsh: zig-driver hybrid

Status: proposed
Scope: src/buildsuites/suite_tcl90/ (driver split: zig-layer fetch/generate/compile + suite-tclsh-run Tcl phases; sources.config -> zon-shaped manifest migration), src/buildsuites/ (the pattern future suites fork - interplay with G-099), bin/tools/ (pinned zig acquisition per the consent-gated mechanism), src/scriptapps/bin/ punk-getzig (acquisition layer, unchanged in role)
Goal: a buildsuite is drivable end-to-end with only the pinned zig toolchain present - no pre-existing tclsh anywhere in the chain. Pre-tclsh phases (source fetch, configure-product generation, compile) move into the zig build layer, with sources declared in a content-hashed declarative manifest (build.zig.zon or a zon-shaped equivalent) that keeps the copy-and-tweak retargeting property; post-tclsh phases (tcllib/tklib installers, critcl accelerators, the parsed-totals test gate, smokes) remain Tcl scripts executed by the FRESHLY BUILT suite tclsh as build steps - Tcl stays the tool exactly where a tclsh is guaranteed to exist because the suite just built it. The plain-tclsh suite.tcl remains as an ergonomic dev driver during transition (or is reduced to a thin documented wrapper).
Acceptance: from a clean checkout plus the pinned zig (acquired via the consent-gated download mechanism or self-built), a documented zig invocation performs the whole pipeline in an environment where no pre-existing tclsh is resolvable (PATH-scrubbed demonstration recorded in this file): fetch/stage sources per the declarative manifest (content-integrity pins for zig-fetched trees; the fossil-checkout flow retained as a documented dev alternative for live-branch work), generate the configure-products, build the runtime, then run the post-tclsh phases under the suite-built shell - tcllib install with tcllibc accelerators via critcl, tklib, tk - and the expected-failure-baselined test gate, with results matching the suite.tcl-driven equivalents; the manifest is the documented tweak surface and copied suite trees remain isolated (G-096 copy-and-tweak property preserved); the recipe pins the zig version it is written against (API-churn mitigation - the 0.14->0.16 migration cost is the recorded precedent); the bash+powershell polyglot alternative for this layer is recorded as considered and rejected, with polyglot craft remaining the ACQUISITION layer's mechanism (punk-getzig/getpunk first-contact story).

## Context

Direction agreed 2026-07-20 (discussion recorded in G-096 notes; user decisions:
toml dropped for binary buildsuites, long-term no-tclsh bootstrap intent, zig
acquisition accepted as the root dependency, the freshly built tclsh accepted as
the legitimate intermediate for tcllib/tklib installers and critcl).

Why zig fits this layer:

- build.zig.zon is itself a declarative, content-hashed source manifest - fetch by
  url+hash gives declarative retargeting WITH integrity. Fossil sources pin as
  per-checkin tarball urls (branch-tip tarballs are not hash-stable); that is a
  provenance feature - '-refresh' becomes 'bump the pin' - with the fossil-checkout
  path kept for dev-friendly live-branch work.
- The recipe already generates configure-products (tclUuid.h, manifests, rc edits)
  inside the zig layer - the boundary just extends to cover fetch.
- zig Run steps execute artifacts they just built: 'zig build tcllib' = build tclsh
  -> run installer.tcl under it; 'zig build test-gate' = run the core suite under it
  and gate on parsed totals. The freshly-built-tclsh intermediate maps 1:1 onto the
  build graph.

Why NOT a bash+powershell polyglot for this layer (considered and rejected): the
polyglot's value is first contact - zero installed tools - but the suite driver runs
AFTER zig acquisition by definition, so a capable tool is always already present.
The driver's workload (manifest parsing, byte-exact file generation, totals parsing,
child-process orchestration) is what dual shell implementations do worst: two
codebases in lockstep or a fragile dual-parse dialect, divergent quoting/path
semantics as a permanent bug farm. Polyglot craft stays where it already earns its
keep in this repo: the acquisition layer (punk-getzig / getpunk cmd-or-powershell
first-contact twins).

Residual external tools, and their long-term story: fossil and git CLIs are used by
the current fetch flow. Under the zon path they become optional (tarball fetch with
pinned hashes needs neither); fossil itself is buildable with zig cc if live
checkouts without a preinstalled fossil are ever wanted.

Relationships: G-005 (this formalizes its zig-build-infrastructure intent for the
buildsuite path), G-006 (consent-gated artifact/toolchain download - the zig
acquisition gate), G-018 (plain tclsh kits - substantially delivered by
tclsh90szip.exe; reconciliation candidate), G-096 (origin discussion in its notes;
the suite.tcl scaffolding this splits), G-099 (sequencing interplay below).

SEQUENCING: proposed 2026-07-20. Natural slot is before or alongside G-099
activation so suite_tcl86 is born onto the chosen driver shape rather than ported
later - but this goal must not block G-096's remaining items (piperepl matrix,
punk-getzig per-version fetch), which close out on the current suite.tcl shape.
sources.config records are deliberately name/url/ref-shaped (close to zon records)
so the manifest migration is mechanical.

## Notes

- 2026-07-20 (user requirements batch): the build-graph products this driver shape
  must express grew concrete - the G-103 runtime kit FAMILY (plain/punk/bi kits with
  attached batteries) become named build outputs, G-105 adds -target as a build
  dimension, and G-104's make.tcl surface fronts whichever driver shape wins (its
  suite self-description contract must survive the migration).