Library artifact lib/ tier recorded (shellspy G-138)

AGENTS.md: lib-tier layout contract (lib/allplatforms + lib/<target>, per-target
sha1sums, never in platforms.txt) and a "Library artifacts - lib tier (schema
v2)" section: generation-tagged immutable names
(<folder>-<tcl8|tcl9>-r<N>.zip), embedded class=library record at the package
root (embed-then-hash - finished-zip facts sidecar-only), schema-v2 field
delta ([artifact] package/package_version/folder/tcl_generation, [library]
driving_tcl_patchlevel, [provenance] class=suite-built + checkout uuids +
critcl) with the v2-superset and class-ordering caveats for line-based
consumers, punkzip determinism + deliberate-publish revision discipline (zig
dlls are not bit-reproducible), md5c disposition (not published - tcllib's md5
prefers tcllibc, which bundles the accelerator), emission tooling pointers and
the publication flow. README.md: tier mention.

src/build_sha1sums.tcl: processes lib/<target> subfolders (own sha1sums.txt
each; warns on a target that is neither allplatforms nor platform-named); lib
excluded from platform enumeration so it can never enter platforms.txt.
Verified against the current repo: all existing artifacts SAME, lib/ absent =
clean no-op, platforms.txt unchanged.

No artifacts are published by this change - publication remains a deliberate
maintainer step (the emitted zips live in the shellspy suites'
out/library/punkbin staging until then).

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

AGENTS.md

@@ -28,6 +28,11 @@ This artifact repository is specific to the punkshell project.
   (e.g. zig archives). `src/` holds maintenance scripts for this repository itself.
   Platform folder names follow the punkshell canonical platform names
   (punk::platform module / `help platforms` in the punk shell).
+- `lib/` is the LIBRARY artifact tier (shellspy G-138), distinct from the runtime
+  platform folders: `lib/allplatforms/` for platform-neutral packages (pure-Tcl),
+  `lib/<target>/` per platform for binary packages, each target subfolder with its
+  own `sha1sums.txt`. `lib/` never appears in `platforms.txt` (runtime folders
+  only). See "Library artifacts - lib tier (schema v2)" below.
 - `platforms.txt` at the repo root lists the platform folders this repo serves
   (one name per line; `#` comments and blanks ignored) - the discovery manifest
   for raw-file consumers that have no directory-listing capability
@@ -126,6 +131,54 @@ it. Emission/verification tooling lives in shellspy `src/buildsuites/suite_tcl90
 derives its identity fields from the embedded copy, `tools/family_check.tcl`
 embedded-record probe).
 
+## Library artifacts - lib tier (schema v2)
+
+The `lib/` tier (shellspy G-138) carries suite-built LIBRARY packages as immutable
+`-r<N>` zips of installed-shape package folders: `lib/allplatforms/` for
+platform-neutral packages (pure-Tcl tcllib), `lib/<target>/` for per-platform
+binary packages (tcllibc critcl accelerators). Consumption (shellspy G-139)
+materializes them into the punkshell repo's untracked `bin/packages/<target>/`
+input tier.
+
+- Naming: `<installed folder name>-<tcl8|tcl9>-r<N>.zip` (e.g.
+  `tcllib2.0-tcl9-r1.zip`, `tcllibc-tcl8-r1.zip`). The GENERATION tag is part of
+  artifact identity, not decoration: both Tcl generations install
+  identically-named package folders (tcllib2.0, tcllibc) with genuinely
+  different bytes (binary packages link per-generation; installer output
+  differs). `-r<N>` revisions are immutable exactly as in the runtime tier.
+- Each zip contains the package folder in installed pkgIndex.tcl shape plus the
+  EMBEDDED record at `<folder>/punkbin-artifact.toml` (package root, beside
+  pkgIndex.tcl - inert to package loading), written before zipping
+  (embed-then-hash: `sha1`/`size`/`built` remain SIDECAR-ONLY). Sidecar
+  `<artifact rootname>.toml` + per-target `sha1sums.txt` are the integrity
+  authority, exactly as for runtimes.
+- Record shape (`schema = 2`): the v1 identity set plus, in `[artifact]`,
+  `class = "library"` with `package`/`package_version`/`folder`/`tcl_generation`
+  (replacing the runtime tier's variant/working_name); a `[library]` table with
+  `driving_tcl_patchlevel` (patchlevel of the suite-built shell that ran the
+  installer/critcl - the generation witness, not a runtime requirement); and in
+  `[provenance]`, `class = "suite-built"` (schema-v2 build-origin class:
+  suite-built | third-party | local - the shellspy G-123 lineage), the source
+  checkout uuids (`tcllib_checkout`, `critcl_checkout`) and `critcl` (version
+  declared by the package's own critcl teapot.txt, accelerator packages only).
+- Schema v2 is a SUPERSET of v1: line-based v1 consumers ignore the new fields
+  by construction. Ordering caveat for whole-text single-key scanners:
+  `[artifact] class` is the FIRST `class =` line in every record by
+  construction; a consumer that wants `[provenance] class` must parse tables.
+- Determinism/publish discipline: zips are punkzip-assembled (sorted members,
+  staged mtimes synced) so re-emission over an unchanged install is
+  byte-identical - but the dlls INSIDE are not bit-reproducible across zig
+  rebuilds, so revisions bump only on deliberate publish, never per rebuild.
+- md5c is deliberately NOT published: tcllib's md5 accelerator resolution
+  prefers tcllibc (modules/md5/md5x.tcl), which bundles the md5 accelerator.
+- Emission tooling: shellspy `src/buildsuites/suite_tcl90` + `suite_tcl86`
+  `tools/library_artifacts.tcl` (`library-artifacts` step in both recipes;
+  suite READMEs document the mechanism). Publication remains a deliberate user
+  step: copy `out/library/punkbin/lib/*` into `lib/`, `git add`, run
+  `tclsh src/build_sha1sums.tcl` (it processes each `lib/<target>/` subfolder),
+  commit. Minisign posture unchanged: sha1sums are transport integrity;
+  per-artifact `.minisig` sidecars remain the anticipated verification layer.
+
 ## Work Guidance
 
 - Adding a runtime: copy it into the platform folder, `git add` it, run

README.md

@@ -16,6 +16,12 @@ Platforms:
 win32-x86_64 (zipfs and tclkit based)
 linux-x86_64 (tclkit based)
 
+The lib/ folder is a separate LIBRARY artifact tier (not a platform folder):
+suite-built Tcl library packages (tcllib, tcllibc) as versioned zips -
+lib/allplatforms for pure-tcl packages, lib/<platform> for binary packages,
+named <folder>-<tcl8|tcl9>-r<N>.zip with embedded provenance records and toml
+sidecars (see AGENTS.md "Library artifacts - lib tier").
+
 Builtin packages: Thread, tcllibc, vfs, vlerq
 
 vfs and vlerq are included even in zipfs runtimes to allow them to call .kit files such as sdx.kit and to extract and build metakit based starkit executables as well as zipfs based executables.

src/build_sha1sums.tcl

@@ -107,6 +107,7 @@ foreach dirtail $rootfolders {
     set level 0
     set indent ""
     if {$dirtail in $known_skip_tails} {continue}
+    if {$dirtail eq "lib"} {continue} ;#the G-138 library tier - processed below, never a platform folder
     set firstword [lindex [split $dirtail -] 0]
     if {$firstword ni $os_list} {
         puts stderr "skipping unrecognised folder: $dirtail"
@@ -117,6 +118,25 @@ foreach dirtail $rootfolders {
     do_sha1_in_folder $runtimefolder 0
 }
 
+#lib tier (G-138): library package artifacts under lib/<target>/ where <target>
+#is 'allplatforms' (platform-neutral packages) or a canonical platform-dir name
+#(per-platform binary packages). Each target subfolder carries its own
+#sha1sums.txt; lib/ itself holds no artifacts and is deliberately NOT listed in
+#platforms.txt (that file enumerates RUNTIME platform folders only).
+set libbase [file join $basedir lib]
+if {[file isdirectory $libbase]} {
+    foreach sftail [lsort [glob -nocomplain -dir $libbase -type d -tail *]] {
+        if {[string match .* $sftail]} {continue}
+        if {$sftail ne "allplatforms"} {
+            set firstword [lindex [split $sftail -] 0]
+            if {$firstword ni $os_list} {
+                puts stderr "${Y}WARNING: lib/$sftail is neither 'allplatforms' nor a platform-named target folder$RST"
+            }
+        }
+        do_sha1_in_folder [file join $libbase $sftail] 1
+    }
+}
+
 #platforms.txt - the machine-readable list of platform folders this repo serves,
 #at the repo root so raw-file consumers (punk-runtime 'platforms -remote', and
 #third-party mirrors using the same layout) can discover platforms without a