# punkbin — punkshell binary artifact repository

## Purpose

Pinned binary artifacts for the punkshell project (github/gitea: jn/shellspy - the
project is punkshell; "shellspy" is a legacy repo name): per-platform Tcl runtime
executables used as the basis for building punkshell kits/zipkits, plus selected
build tools. This repository exists so that build and test environments can retrieve
exact, checksummed runtime binaries instead of depending on moving upstream releases
(e.g. beta runtimes such as tclsfe-x64.exe from github.com/apnadkarni/tcl-sfe) or on
binaries that exist only on one developer machine.

This artifact repository is specific to the punkshell project.

## Ownership

- Owned by the punkshell project maintainer.
- Agents may add artifacts and update checksums when the punkshell project work
  calls for it (e.g. preserving a runtime that punkshell tests depend on) - report
  additions in the completion summary.
- Agents must not modify or delete existing binaries; superseding a runtime means
  adding the new file, not overwriting the old one.

## Local Contracts

- Layout: one folder per platform (`win32-x86_64/`, `linux-x86_64/`, `linux-arm/`,
  `macosx/`, `freebsd-arm64/`, ...), optional `tools/` subfolders for build tooling
  (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
  (`punk-runtime.cmd platforms -remote`, and third-party mirrors using the same
  layout should carry the same file). Regenerated by `src/build_sha1sums.tcl`.
- `defaults.txt` at the repo root is the CURATED per-platform recommended default
  fetch runtime (`<platform> <runtimename>` per line; `#` comments/blanks
  ignored) consulted by `punk-runtime.cmd fetch` when no runtime name is given.
  Hand-edited, never generated - it records a release DECISION. The release
  process: publish the artifact (add, `git add`, run `src/build_sha1sums.tcl`),
  then point the platform's `defaults.txt` line at it IN THE SAME CHANGE-SET -
  the script validates entries (warns on unknown platforms or missing artifact
  files) so drift between the halves is caught. A platform with no line has no
  recommendation (punk-runtime tells the user to name a runtime explicitly).
  Mirrors may curate their own recommendations.
- Every platform folder (and tool subfolder) carries a `sha1sums.txt` with one
  `<sha1> *<filename>` line per artifact (binary-mode marker `*`).
- `sha1sums.txt` (and `platforms.txt`) are regenerated with
  `tclsh src/build_sha1sums.tcl` from the repo root. The script only sums
  git-tracked files - `git add` a new artifact BEFORE running it. It reports
  NEW/SAME/CHANGED per file; a CHANGED line for an existing artifact is a red
  flag (artifacts are immutable - investigate, don't commit).
- Binaries are deliberately committed here - this repo is the exception to the
  punkshell source repo's no-committed-binaries direction (shellspy G-004): the
  source repo points at this one (G-006 retrieval direction) instead of carrying
  binaries itself.
- Runtime expectations (see README.md): self-contained Tcl interpreters usable as
  kit bases; punk runtimes load Tk as an extension (no separate Tk runtime).
  Runtimes with statically-linked packages (e.g. tclsfe-x64.exe: Thread, twapi,
  sqlite3, tdbc) are supported by punkshell boot as of shellspy G-058.

## Artifact metadata records (schema v1)

Family runtime artifacts (shellspy G-103/G-117) are metadata-carrying in TWO copies:

- SIDECAR: `<artifact rootname>.toml` beside the artifact, listed in `sha1sums.txt`.
  The sidecar + sha1sums are the INTEGRITY AUTHORITY.
- EMBEDDED: the same record minus the finished-binary facts, at
  `punkbin-artifact.toml` inside the artifact's attached (exe-appended) zip image -
  written at kit-family staging BEFORE wrapping and hashing (embed-then-hash: the
  embedded copy can never contain its own sha1). It makes a runtime separated from
  its sidecar (out-of-band copy, rename) self-describing:
  `punk-runtime info <name-or-path>` reads it WITHOUT executing the target (zip
  central-directory read of the exe-appended archive - .NET in the ps1 payload,
  unzip in the bash payload; a cooperative probe piping a reader script into the
  EXECUTED target is the documented fallback for hosts with no zip reader, with
  the obvious caveat about running untrusted binaries) and flags
  embedded-vs-sidecar disagreements. The record survives punkshell's make.tcl kit
  wrapping (the kit vfs overlays the image without clearing it), so wrapped kits
  inherit their runtime's record (shellspy G-025 treats it as the
  runtime-provenance layer of kit self-reporting).

Field semantics (v1; `schema = 1` at the top of both copies):

- `schema` - record format version. Absent = pre-v1 (r1-era records; consumers
  parse them tolerantly).
- `[artifact]` `name`/`class`/`variant`/`working_name`/`revision`/`target` - the
  G-103 identity: immutable `-r<N>` artifact name, `runtime` class, family variant
  (plain/punk/punk-bi), the working name `use` materializes to, assembly revision,
  punkbin platform target.
- `sha1`/`size`/`built` - SIDECAR-ONLY finished-binary facts.
- `build_id` - offline correlation key re-joining a renamed stray copy to its
  record; IDENTICAL in embedded and sidecar copies. A deterministic uuid-shaped
  digest of stable identity inputs (artifact name, toolchain/optimize, patchlevel,
  per-member source checkout uuids) - a correlation key, NOT an integrity key
  (sha1sums is).
- `origin` - the canonical artifact repo this artifact was BUILT FOR (suite option
  `-Doriginurl`, default this repo's url) - NOT necessarily where it is hosted;
  mirrors preserve it, so an artifact found on a third-party repo still declares
  its home. Where an artifact actually lives is the hosting repo's own business.
- `packager` - DECLARED builder identity (`-Dpackager` > env `PUNKBIN_PACKAGER` >
  the building checkout's git identity > `"unrecorded"`). Declarative, not proof:
  the verification layer is signing - per-artifact `.minisig` sidecars (this
  repo's existing minisign practice for zig tool archives) are the natural
  complement, deliberately outside the metadata file (a signature cannot live
  inside what it signs).
- `project`/`project_url` - what a stray artifact belongs to beyond its origin
  repo (`-Dprojecturl`; `unrecorded` until a canonical url is chosen).
- `license` - summary for the distributed artifact (`TCL` for family runtimes);
  component license texts ride inside the attached image.
- `build_host_platform` - platform the artifact was built ON (meaningful once
  cross-builds exist; equals `target` today).
- `[runtime]` `tcl_patchlevel`, `piperepl`/`piperepl_default`/`piperepl_opt_out`,
  `attached_batteries` - probed-verifiable runtime facts (the suite's
  family_check asserts them against the actual binary).
- `[provenance]` `suite`/`toolchain`/`optimize`/`*_checkout` - build provenance
  (fossil checkout uuids per component).
- `[tests]` - per-suite test-gate result lines (sidecar only; from the G-107
  evidence summaries).

Records carry `#` comment lines documenting the non-obvious fields; consumers are
line-based and ignore comments and unknown fields by construction - new fields
(e.g. the planned tls battery fields, shellspy G-116) extend v1 rather than fork
it. Emission/verification tooling lives in shellspy `src/buildsuites/suite_tcl90`
(`build905.zig` staging embed, `tools/family_artifacts.tcl` emission - the sidecar
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
  `tclsh src/build_sha1sums.tcl`, verify the NEW line's checksum, commit with a
  message recording provenance (upstream URL/version/build source).
- Consumers: the punkshell project retrieves runtimes into its
  `bin/runtime/<platform>/` via `bin/punk-runtime.cmd` or manual copy; punkshell's
  `src/runtime/mapvfs.config` maps runtimes to vfs payloads.
- Do not push on an agent's initiative - the remote is the project's upstream
  artifact store; the maintainer controls what is published.

## Verification

- `tclsh src/build_sha1sums.tcl` reports SAME for every pre-existing artifact and
  NEW only for intended additions.

## Child DOX Index

(None - flat platform folders with artifacts, checksums and README.md; `src/` is a
single maintenance script.)