# 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.
- Every platform folder (and tool subfolder) carries a `sha1sums.txt` with one
  `<sha1> *<filename>` line per artifact (binary-mode marker `*`).
- `sha1sums.txt` is 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.

## 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/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.)