punkshell/goals/G-116-suite-built-tcltls.md

G-116 Suite-built tcltls with a zig-built crypto backend: bi-family battery, prebuilt replacement path

Status: proposed Scope: src/buildsuites/suite_tcl90/ (build_tcltls module + crypto-backend build, sources.config + build.zig.zon source records, kit-family bi payload + metadata extension, test_gate record step), src/vfs kit payloads carrying vendored tcltls binaries (current-state reference + recorded disposition only - removal stays G-004-era work), punkbin (as eventual artifact destination via the G-067 library class); consumers punk::imap4 / punk::netbox (package require tls) as verification context Goal: suite_tcl90 builds tcltls (core.tcl-lang.org/tcltls fossil, the thread/tclvfs/tk fetch pattern) together with its crypto backend (LibreSSL-portable or no-asm OpenSSL - decided and recorded in this file) entirely under the zig-only toolchain policy, statically linked so the resulting tcl9 tls extension is self-contained; it joins the bi-family attached payload as the first battery beyond Tk, loads via package require tls from a bi family kit, and its own testsuite runs under the suite-built shell through the G-107 machinery - replacing the need for the vendored prebuilt tcltls binaries and advancing G-004. Acceptance: the crypto-backend choice (LibreSSL-portable vs no-asm OpenSSL) is recorded here with rationale and pinned source records in BOTH suite flows (sources.config + build.zig.zon); a suite step builds backend + tcltls reproducibly and the extension loads in the suite shell AND in a rebuilt bi family kit (package require tls plus a functional handshake: a loopback connection to an ephemeral local TLS server using a generated self-signed certificate - no external network); tcltls's own tests/ suite runs as a record-mode test_gate step emitting the G-107 evidence summary (gate promotion per the standard disposition-plus-two-run-deterministic bar, recorded either way); the bi kit-family payload and artifact metadata carry the tls version and the backend name+version; the disposition of the existing vendored tcltls kit payloads (tcltls1.7.22/1.7.23, tls2.0b2, punk9linux tcltls.so) is recorded here - they REMAIN until user-directed removal, actual removal being G-004-era work outside this goal.

Context

Drafted 2026-07-22 (user-approved wording) to give the tcltls bi-battery line a live goal home after G-103's archive (achieved 2026-07-22 - see goals/archive/G-103-runtime-kit-family.md, whose Notes carry the original 2026-07-21 material this goal formalizes):

• DECISION 2026-07-21 (user, recorded in archived G-103): tcltls approved into the bi-battery enumeration - deliberately NOT gating family progress; a dedicated goal was named as the option "if the crypto build proves large" - this is that goal, drafted at the natural point rather than under pressure.
• FEASIBILITY (the crux, unchanged from the archived analysis): tcltls itself is a thin C extension (tls.c/tlsIO.c compile under zig cc like thread/tclvfs/tk) but LINKS a crypto backend - upstream OpenSSL, LibreSSL also supported. No crypto library is in the tree, so the real work is the backend build under the zig-only policy: pragmatic paths are LibreSSL-portable (autoconf/cmake, no perl Configure) or a no-asm OpenSSL, compiled with zig cc, with tcltls linked STATIC against it (mirroring the tcllibc/tk build shape). This is the largest new build dependency the family takes on - hence its own goal with its own acceptance.
• TEST VALUE (archived G-103 observation): zig-built crypto + tcltls against a static tclsh is a combination nobody upstream tests - the record-mode run is evidence of exactly the kind G-107 (achieved - see goals/archive/G-107-buildsuite-library-tests.md) was built to capture.
• INTERIM STATE: TLS ships today ONLY as vendored prebuilt binaries in kit .vfs payloads (tcltls1.7.22/1.7.23 + tls2.0b2 dlls; punk9linux tcltls.so) - committed binaries G-004 wants gone, tolerated pending their build story. Real consumers exist now: punk::imap4 and punk::netbox both 'package require tls'.

Relationships: G-004 (a suite-built tls is the prebuilts' replacement path), G-067 (once built, per-platform tls artifacts are library-class punkbin candidates), G-105 (tls joins the family x target matrix when cross-targets land), G-107 (achieved - test machinery this goal's record step uses), archived G-103 (family payload contract and metadata shape this battery extends).

Notes

• G-117 relationship (G-117 achieved 2026-07-24 - see goals/archive/G-117-self-describing-runtimes.md; recorded 2026-07-24 after overlap review; neither file previously referenced the other): this goal's Acceptance extends the artifact metadata (tls version + backend name/version) - those fields ride G-117's schema v1 as the extension point, not a parallel record.
• G-006 relationship: the suite-built tls is the replacement for the prebuilt tcltls binaries G-006's consent-gated channel would otherwise have to carry long-term - when this lands, the G-004-era removal of those prebuilts unblocks.
• G-005 relationship: this is the living edge of G-005's "expand to other dependencies" (native extensions from source under the zig-only policy) - the crypto backend is the largest such dependency taken on.
• G-108 relationship: when the debug tier lands, this goal's static crypto + tls extension joins the TCL_MEM_DEBUG all-or-nothing set - G-108's debug-define rebuild feasibility must cover it.