AGENTS: artifact metadata schema v1 documentation (shellspy G-117)

Embedded-vs-sidecar record relationship (embed-then-hash; sidecar + sha1sums
stay the integrity authority; record survives kit wrapping), per-field
semantics incl origin's built-for-not-hosted-on meaning, packager's
declarative-not-verified status with minisign sidecars as the verification
complement, build_id as deterministic correlation key, and the comment-
documented extension point (G-116 tls fields extend v1). Also: stale
bin/runtime.cmd consumer reference corrected to bin/punk-runtime.cmd.

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

AGENTS.md

@@ -59,13 +59,80 @@ This artifact repository is specific to the punkshell project.
   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).
+
 ## 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
+  `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.