From b692979c6a7ac7a19683245cb2b15f78f770d38b Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 28 Jul 2026 14:55:37 +1000 Subject: [PATCH] G-135 + G-136: per-asset assetorigin sidecars replace the directory record Pre-activation review outcome (user-approved wording): G-135's record shape pivots from one assetorigin.toml per directory to a per-asset sidecar, .assetorigin.toml beside the asset it describes. G-135 contract: Scope (both tiers, mirror-identical) names per-asset *.assetorigin.toml sidecars. Acceptance rebuilt - records are bound by the sidecar's own filename (suffix stripped, same directory; files ending in the suffix are records, never assets; reader tolerance kept); the checker's state model is repaired to six states evaluated in table order with first match winning (artifact-absent added for records whose paired asset is gone; verified now requires every hash the sidecar records to match, so a hash-only sidecar verifies on the artifact hash alone; fixtures must distinguish stale / replaced / artifact-absent); the generator clause requires byte-identity per the invocation profile that produced each .ico and that the generator (re)writes each produced artifact's sidecar, so regeneration cannot leave a stale record; the final clause requires sidecars to exist and verify for every generated artifact under the four asset directories. G-135 body: Approach carries the pairing rationale (no path key, file- pair lifecycle, survives wholesale and single-asset copies, composes under merge_over same-path replacement) and the hash-required minimum; the six-row state table gains the evaluation-order and unhashed-claims notes. Alternatives inverted: the per-directory [[asset]] record is now the rejected shape (shared-state writers - the punkcheck G-094/G-095 lesson; file-level clobber at a .vfs root under overlay merges; invisible dangling entries; single-asset copies lose their record), and a fauxlink-carried record is recorded as considered-and-rejected (the filename would encode a mutable fact; overlay pairing would need a nominal-keyed composition invariant in every composer), preserving the nominal-keyed idea as fauxlink hardening independent of this goal (71 fauxlinks in tree, zero same-directory nominal collisions, surveyed 2026-07-28). Notes add the override-without-sidecar kit behaviour (travelled common sidecar truthfully reads replaced), the eased checker parsing posture, and the open pre-activation items (which of the four build-consumed punkshell.ico copies get sidecars; whether a _vfscommon.vfs sidecar shipping inside every baked kit is the intent). G-136: acceptance names icon.ico.assetorigin.toml and the per-asset dependency; Approach/Notes reworded to match. G-057: one Notes sentence disambiguates its per-kit icon sidecar from G-135's record sidecars. goals_lint clean (index/detail mirrors exact, archived-goal references markered); goals_xref score G-135 re-run - G-136 and G-057 linked. G-135 stays proposed; activation is the user's flip. Claude-Session: https://claude.ai/code/session_014wNGMsdNFFrU1duADeirgm Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 2 +- goals/G-057-kit-icon-embedding.md | 2 +- goals/G-135-asset-provenance-records.md | 95 ++++++++++++++----- goals/G-136-generated-project-icon-seeding.md | 18 ++-- 4 files changed, 84 insertions(+), 33 deletions(-) diff --git a/GOALS.md b/GOALS.md index dc108ec6..3c1be4ec 100644 --- a/GOALS.md +++ b/GOALS.md @@ -416,7 +416,7 @@ Scope: src/make.tcl (post-assembly offset-style probe at the G-133 advisory-chec Detail: goals/G-134-baked-kits-pinned-archive-relative.md ### G-135 [proposed] Asset provenance records: a verifiable master-to-derived icon chain with a platform-neutral generator -Scope: src/assets/logo/ (assetorigin.toml records, 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) +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) Detail: goals/G-135-asset-provenance-records.md ### G-136 [proposed] Generated projects are seeded with a default icon from a single punkshell-held master diff --git a/goals/G-057-kit-icon-embedding.md b/goals/G-057-kit-icon-embedding.md index 0b23a762..9a70e065 100644 --- a/goals/G-057-kit-icon-embedding.md +++ b/goals/G-057-kit-icon-embedding.md @@ -131,7 +131,7 @@ delete-then-write). Requirements sketch agreed 2026-07-10: in the Acceptance that the override is shared across a kit definition's targets. - Related: G-135 - the source-tree provenance records this goal's sidecar can read. The sidecar is emitted per kit at bake time and describes what got embedded; G-135's - assetorigin.toml is committed and describes a derivation. Populating the sidecar's + per-asset assetorigin sidecars are committed and describe a derivation. Populating the sidecar's "source .ico identity and provenance" from those records closes the gap where this goal's provenance otherwise stops at the .ico bytes, one tier short of the SVG master they were generated from. diff --git a/goals/G-135-asset-provenance-records.md b/goals/G-135-asset-provenance-records.md index 33a181e7..2eea74f7 100644 --- a/goals/G-135-asset-provenance-records.md +++ b/goals/G-135-asset-provenance-records.md @@ -1,9 +1,9 @@ # G-135 Asset provenance records: a verifiable master-to-derived icon chain with a platform-neutral generator Status: proposed -Scope: src/assets/logo/ (assetorigin.toml records, 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) +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: `assetorigin.toml` is documented with a `schema` key and directory-scoped relative paths, and a reader tolerates an absent file, 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 recorded asset as exactly one of `unrecorded`, `verified`, `source-absent`, `replaced` or `stale`, demonstrably distinguishing `stale` (source changed since the artifact was generated) from `replaced` (artifact changed since recording) 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), producing byte-identical `.ico` output to the current `make-ico.ps1` for every master under `src/assets/logo/` before that script is removed; and records exist and verify for `src/assets/logo/`, `alternative/`, `web/` and `project-default/`. +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 @@ -42,27 +42,39 @@ container assembly downstream is pure `binary format`. - 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. -- Directory-scoped `assetorigin.toml` carrying an `[[asset]]` array with - RELATIVE paths, so it survives being copied wholesale into a derived tree with - no rewriting (the property G-136 depends on). -- Every field except `path` is optional. An entry carrying only a path and 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. +- 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. -- Five states, with policy left to the consumer rather than baked into the - format: +- 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: - | State | Condition | - |---|---| - | `unrecorded` | no record file | - | `verified` | artifact and source hashes both match | - | `source-absent` | artifact matches, source not present in the tree | - | `replaced` | artifact hash differs from the record | - | `stale` | artifact matches the record, source present but changed | + | 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 | - `stale` is the point of the whole goal; it is also distinguishable from - `replaced`, which means the opposite thing and deserves the opposite response. + 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 @@ -81,15 +93,34 @@ container assembly downstream is pure `binary format`. - `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. -- Per-file sidecars instead of one record per directory - rejected: - `src/assets/logo/web/` alone would carry six, and a directory record with - relative paths is what makes verbatim copying work. +- 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 sidecar is specified to carry "source +- 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 @@ -113,3 +144,21 @@ container assembly downstream is pure `binary format`. 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). diff --git a/goals/G-136-generated-project-icon-seeding.md b/goals/G-136-generated-project-icon-seeding.md index 17b23cc4..3b72363b 100644 --- a/goals/G-136-generated-project-icon-seeding.md +++ b/goals/G-136-generated-project-icon-seeding.md @@ -3,7 +3,7 @@ Status: proposed Scope: src/assets/logo/project-default/ (the single held seed artwork); src/modules/punk/mix/commandset/project-999999.0a1.0.tm (generation-time asset injection beside bootsupport_inject); src/project_layouts/ (per-layout icon-slot declaration with no artwork stored in layout trees); src/modules/punkcheck-999999.0a1.0.tm (install records for injected assets) Goal: A newly generated project arrives with a working and inspectable icon - a readable vector master plus a ready-to-use `.ico` - injected from punkshell's single held copy at generation time, with no icon artwork stored in any layout payload tree, and regeneration never silently discards an owner's replacement. -Acceptance: `dev project.new` against a layout declaring an icon slot produces `src/assets/logo/` in the generated project containing `icon.svg`, `icon.ico` and an `assetorigin.toml` that the G-135 checker reports as `verified` in that tree (source and artifact both present, hashes matching), with the artwork sourced from `src/assets/logo/project-default/` at generation time rather than from any file under `src/project_layouts/` - verified by that tree containing no icon `.svg` or `.ico` payload; each injected file is recorded as a punkcheck install event in the same manner as `bootsupport_inject`; a layout declaring no icon slot generates a project with no `src/assets/logo/` and no warning; and re-running generation over a project whose `icon.svg` or `icon.ico` differs from the injected original leaves the owner's file intact and reports the skip by name. +Acceptance: `dev project.new` against a layout declaring an icon slot produces `src/assets/logo/` in the generated project containing `icon.svg`, `icon.ico` and `icon.ico.assetorigin.toml` that the G-135 checker reports as `verified` in that tree (artifact and recorded source both present, hashes matching), with the artwork sourced from `src/assets/logo/project-default/` at generation time rather than from any file under `src/project_layouts/` - verified by that tree containing no icon `.svg` or `.ico` payload; each injected file is recorded as a punkcheck install event in the same manner as `bootsupport_inject`; a layout declaring no icon slot generates a project with no `src/assets/logo/` and no warning; and re-running generation over a project whose `icon.svg` or `icon.ico` differs from the injected original leaves the owner's file intact and reports the skip by name. ## Context @@ -42,10 +42,11 @@ unbranded so it reads "replace me" rather than as a product identity. a rasterizer, and requiring one of a fresh project would defeat the purpose; the pair also gives the owner a complete worked example of the master-to-derived relationship, which no amount of documentation prose achieves. -- The `assetorigin.toml` copies verbatim. Because G-135's record is - directory-scoped with relative paths, it needs no rewriting at the destination - and reads `verified` there - source and artifact are both present in the - generated tree. +- The `icon.ico.assetorigin.toml` sidecar copies verbatim. Because G-135's + record is a per-asset sidecar bound by its own filename with + directory-relative source references, it needs no rewriting at the + destination and reads `verified` there - artifact and recorded source are + both present in the generated tree. - Per-layout icon-slot declaration. A layout may decline, and declining is not a failure or a warning. - Never clobber a replacement. Re-running generation over a project whose icon @@ -70,9 +71,10 @@ unbranded so it reads "replace me" rather than as a product identity. ## Notes -- Related: G-135 - depends on. Consumes the `assetorigin.toml` format and the - checker, and relies specifically on the record being directory-scoped with - relative paths so it survives injection unchanged. +- Related: G-135 - depends on. Consumes the sidecar record format and the + checker, and relies specifically on the record being a per-asset sidecar + with directory-relative references so it survives injection unchanged (and + a single asset re-injected travels with its record as a pair). - Related: G-027 - consumer. Pull-based infrastructure updates for derived projects would later refresh seeded assets, and both goals record their installs through punkcheck.