# G-135 Asset provenance records: a verifiable master-to-derived icon chain with a platform-neutral generator Status: proposed Scope: src/assets/logo/ (per-asset *.assetorigin.toml sidecars, masters and generated icons); src/assets/logo/make-ico.ps1 (replaced in place by a Tcl generator, then removed); scriptlib/developer/ (provenance checker, sibling to goals_lint and architecture_lint); checker home revisited if it becomes a bake step (a punk:: module rather than scriptlib, which make.tcl must not depend on); src/runtime/punkshell.ico and src/vfs/_vfscommon.vfs/punkshell.ico (recorded as derived copies, not relocated) Goal: Any committed icon in the tree can state what it was derived from and be checked against that claim on any platform, and regenerating one from its master needs no Windows-only tooling - while an icon carrying no record stays a fully supported and silent case. Acceptance: the `.assetorigin.toml` sidecar format is documented with a `schema` key, the recorded asset bound by the sidecar's own filename (suffix stripped, same directory) and the source reference relative to that directory, files ending in the suffix being records, never assets; a reader tolerates a missing sidecar, unknown keys and an unrecognised schema version without erroring; a checker written in plain Tcl - no rasterizer, no external binary, runnable under any punkshell runtime - classifies each asset it examines as exactly one of `unrecorded` (no sidecar), `verified`, `artifact-absent` (a sidecar whose paired asset is gone), `source-absent`, `replaced` or `stale` per the state table in this file, where `verified` requires every hash the sidecar records to match, so a sidecar carrying only the artifact hash is verified on that alone, demonstrably distinguishing `stale` (source changed since the artifact was generated) from `replaced` (artifact changed since recording) and from `artifact-absent` on constructed fixtures, and is advisory only, never failing a build, in the manner of the G-133 payload checks; the icon generator is reimplemented with no Windows-only component (`System.Drawing` in particular), regenerating every generated `.ico` under `src/assets/logo/` byte-identically to the current `make-ico.ps1` under the invocation profile that produced it before that script is removed, and (re)writing the sidecar of each artifact it produces - artifact and source hashes plus the invocation options - so regeneration cannot leave a stale record; and sidecars exist and verify for every generated artifact under `src/assets/logo/`, `alternative/`, `web/` and `project-default/`. ## Context Before 2026-07-27 the tree held several byte-identical `punk1.ico` files with nothing above them. An `.ico` is a compiled artifact - a container of pre-rasterized bitmaps - so there was no file anyone could edit, no recorded way to produce a new one, and no way to verify that any copy was what someone intended. `src/assets/logo/` (91fa500e) introduced a vector master and a generator, establishing three tiers: the SVG master, the generated `.ico`, and the build-consumed copies (`src/runtime/punkshell.ico`, `_vfscommon.vfs`, `mkzipfix.vfs`, `punk8_statictwapi.vfs`). What is still missing is any record that ties the tiers together. Nothing states that `src/runtime/punkshell.ico` came from `punk-mark.svg`, so one specific failure is undetectable: someone edits the SVG, forgets to regenerate, and the committed `.ico` silently stops depicting the master. Design-time and bake-time are separate problems, and conflating them is what makes the manual copy into build trees feel wrong when it is not. G-057's acceptance requires that "a fresh checkout that fetches a runtime and bakes produces iconed kits with no build toolchain installed" - a rasterizer IS a build toolchain, so SVG-to-raster can never happen at bake time on any platform, including Windows. The `.ico` must remain a committed artifact. What is missing is therefore not automation but a recorded, checkable link. The generator's platform tie is narrower than it appears. `pwsh` and `rsvg-convert` are both cross-platform; the entire Windows dependency is one line - `Add-Type -AssemblyName System.Drawing`, used solely to decode a PNG into raw BGRA pixels, which throws on non-Windows under .NET 6+. Tcl core ships `zlib`, so PNG decode is inflate plus undoing the five row filters, and the ICO container assembly downstream is pure `binary format`. ## Approach - The record is OPTIONAL by construction. Absence means `unrecorded` - silent, never a warning. A record is an opt-in claim, and nothing may read it to decide whether a build proceeds. Most projects live in this state permanently. - Per-asset sidecar records: `.assetorigin.toml` beside the asset it describes. The pairing is the filename - no `path` key - so create, replace and remove are always the file pair, with no shared record to edit; the pair survives wholesale directory copies (the property G-136 depends on) and single-asset copies alike; and overlay merges compose correctly by construction (merge_over's same-path replacement carries asset and sidecar together). Files ending in `.assetorigin.toml` are records, never assets. - Every field except the artifact `hash` is optional. A sidecar carrying only a hash means "I know this file, I do not know where it came from" - which serves an owner who drops in their own `.ico` but still wants change detection. - Unknown keys and unrecognised `schema` versions are skipped, not errors, so a future writer cannot break an older reader. - Six states, evaluated in table order with the first match winning (which is what makes "exactly one" true by construction), policy left to the consumer rather than baked into the format: | Order | State | Condition | |---|---|---| | 1 | `unrecorded` | no sidecar for the file | | 2 | `artifact-absent` | a sidecar exists but its paired asset does not | | 3 | `replaced` | asset present, hash differs from the sidecar (regardless of source state) | | 4 | `source-absent` | asset matches, a recorded source is not present in the tree | | 5 | `stale` | asset matches, recorded source present but its hash differs | | 6 | `verified` | asset matches, and every other hash the sidecar records also matches | Hash comparisons apply only to hashes actually recorded - a claim with no hash contributes only a presence check, so a source named without a source hash can never produce `stale`; drift on unhashed claims is the record's own limitation, not the checker's. `stale` is the point of the whole goal; it is distinguishable from `replaced`, which means the opposite thing and deserves the opposite response, and from `artifact-absent`, which means the record itself has gone stale and needs repair. - A `role` field (`pe-resource` | `web` | `generic`) makes an existing hazard machine-checkable rather than a documentation footnote: `web/favicon.ico` is all-PNG, which is exactly what GDI+ and tklib's `ico` package cannot read, so a future embedding step can refuse anything marked `role = "web"`. - Generation and verification are separable and get different treatment. Verification must be portable and dependency-free, because it is what runs everywhere - including inside a bake and inside a derived project. Generation needs a rasterizer and runs only when artwork changes, so it may depend on `rsvg-convert` while still carrying no Windows-only component. ## Alternatives considered - `PROVENANCE.md` prose, the `src/tools/punkzip` convention - rejected: human prose is not machine-checkable, and the failure this goal targets is silent drift, which needs hashes. - `punkorigin.toml`, G-027's generated-project carrier - rejected: that answers project lineage ("this project came from punkshell layout X"), a different question from asset derivation. Keep them separate. - One record file per directory carrying an `[[asset]]` array - the original draft shape - rejected at the 2026-07-28 pre-activation review: entries are shared state (every writer does a read-modify-write - the punkcheck lesson: G-094 + G-095, both achieved 2026-07-21, archived at goals/archive/G-094-punkcheck-single-lifecycle.md and goals/archive/G-095-punkcheck-concurrent-writer-safety.md), a record at a .vfs root is clobbered file-level by overlay merges (a kit-tree record would replace the common one wholesale, entries and all), dangling entries are invisible in listings, and copying a single asset out of a directory loses its record. Accepted in exchange: `web/` carries one sidecar per generated raster, and per-directory facts (format documentation, cross-asset notes) live in AGENTS.md rather than in the record file. - A fauxlink-carried record (toml body per the fauxlink extension convention, source path encoded in the name) - rejected: the filename would encode a mutable fact, so master renames invalidate sidecar filenames, and overlay pairing would need a nominal-keyed composition invariant in merge_over and every other composer; the ls-visible derivation edge does not pay for that. The nominal-keyed idea itself (at most one fauxlink per effective nominal per directory, last layer wins) is recorded as generally useful fauxlink hardening independent of this goal - the tree already satisfies it (71 fauxlinks, no same-directory nominal collisions, surveyed 2026-07-28). - Making the `.ico` a build output regenerated at bake time - rejected: G-057 requires bakes to succeed with no build toolchain installed. ## Notes - Related: G-057 - consumer. Its per-kit icon sidecar is specified to carry "source .ico identity and provenance" in a documented plain-text form; these records are the natural thing it reads to populate those fields, which closes the gap where its provenance otherwise stops one tier short of the actual source. Its Scope names `src/runtime/punkshell.ico` as the project default, which this goal reframes as a recorded derived copy rather than the origin. - Related: G-128 - sibling surface. Portable PE resource stamping shares this goal's motivation that icon handling must not be Windows-bound. - The advisory posture the Acceptance borrows is G-133's (achieved 2026-07-27, archived at goals/archive/G-133-bake-payload-consistency-checks.md): its bake payload checks recap as BUILD-WARNINGs and never fail the build. - Generator and checker have different homes on purpose. The generator operates on the files beside it, runs only when artwork changes, and is already documented in `src/assets/logo/AGENTS.md`, so it is replaced in place. The checker is a lint in the shape of `goals_lint.tcl` and `architecture_lint.tcl` and belongs in `scriptlib/developer/` - unless it becomes a bake step, in which case it must move to a `punk::` module, because `scriptlib/` is user-only territory that `make.tcl` must not depend on. That decision is deliberately deferred to the work. - Open workflow question, deliberately kept out of the Acceptance: whether the checker runs during `make.tcl bake` or only as an explicit verification subcommand. `stale` is a design-time mistake rather than a build-time one, which argues for a subcommand plus an opportunistic check only when a bake actually consumes an icon. - Override behaviour in baked kits (recorded 2026-07-28): a kit .vfs that overrides a common asset without shipping its own sidecar produces a kit where the travelled common sidecar classifies the override as `replaced` - truthful and intended. An overrider that wants `verified` inside the built artifact ships its own sidecar beside the override; merge_over carries the pair by same-path replacement with no new machinery. - The sidecar shape eases the checker's parsing posture: each record is one small flat toml table, so a self-contained subset reader stays defensible if the tomlish dependency is unwanted in the scriptlib context - the checker's toml/hash dependency posture is still an open decision for the work (pre-activation review 2026-07-28). - Open (pre-activation review 2026-07-28): whether sidecars for the build-consumed `punkshell.ico` copies are acceptance-required - Scope names two of the four (`src/runtime/`, `_vfscommon.vfs`; `mkzipfix.vfs` and `punk8_statictwapi.vfs` carry byte-identical copies too) - and the explicit decision that a sidecar committed in `_vfscommon.vfs` ships inside every baked kit (the per-asset shape makes that collision-free; the shipping intent itself is the open call).