G-115 proposed: declarative .vfs composition - toml-defined kit payloads with drop-in preservation

User-approved draft from the binary-policy framing discussion: per-.vfs
toml declarations materialize payload from suite build products, punkbin
artifact classes (consent-gated) and vendor trees, making kit payloads
buildable on a clean binary-free tree (G-004) - while the folder remains
the operative assembly area: declarations optional, undeclared drop-ins
preserved (permissive derived projects and gitignored test .vfs keep
drop-in simplicity). Context records the precedents (vendorlib_vfs.toml,
G-087 layout_materialize, vendored tomlish), the relationship to the
punkbin third-class question, and precedence design as the core work.

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

GOALS.md

@@ -385,3 +385,7 @@ Detail: goals/G-113-maketcl-tty-aware-colour.md
 ### G-114 [proposed] Per-platform tm module roots: platform-segregated binary .tm via tcl::tm::path
 Scope: src/vfs/_config/punk_main.tcl + src/vfs/_config/project_main.tcl + src/make.tcl (boot tm-path wiring), src/modules/punk/platform-999999.0a1.0.tm (canon names, as consumer), new per-platform tm root trees (layout/naming decision - sibling roots beside src/vendormodules_tclX / src/modules_tclX), src/project_layouts (layout seeding), modpod demonstration artifact, tree READMEs; coordinates with G-109 (manifest target-platform field stays that goal's item)
 Detail: goals/G-114-per-platform-tm-roots.md
+
+### G-115 [proposed] Declarative .vfs composition: toml-defined kit payloads with drop-in preservation
+Scope: src/make.tcl (vfs assembly), src/runtime/vendorlib_vfs.toml (existing per-package declaration surface - fold/supersede settled in the work), src/vfs/ (per-.vfs declaration files + README), punk::mix machinery as touched, src/project_layouts (seeding for derived projects); coordinates with G-067 (artifact sources), G-006 (consent), G-004 (binary-free committed tree)
+Detail: goals/G-115-declarative-vfs-composition.md

goals/G-115-declarative-vfs-composition.md

@@ -0,0 +1,44 @@
+# G-115 Declarative .vfs composition: toml-defined kit payloads with drop-in preservation
+
+Status: proposed
+Scope: src/make.tcl (vfs assembly), src/runtime/vendorlib_vfs.toml (existing per-package declaration surface - fold/supersede settled in the work), src/vfs/ (per-.vfs declaration files + README), punk::mix machinery as touched, src/project_layouts (seeding for derived projects); coordinates with G-067 (artifact sources), G-006 (consent), G-004 (binary-free committed tree)
+Goal: a .vfs folder's payload can be DECLARED in a toml definition (sources: suite build products, punkbin runtime/library artifacts via the consent-gated channels, vendor trees) and materialized into the folder by the build - while the folder remains the operative assembly area: undeclared dropped-in files (binary libs/modules included) are preserved with documented precedence, so derived projects with permissive binary policies and gitignored test .vfs folders keep drop-in simplicity with no declaration required.
+Acceptance: a punkshell kit .vfs (or demonstration .vfs) builds from a toml declaration reproducing its payload on a clean tree, with declared binary content arriving via consented retrieval or local build products; an undeclared dropped-in file survives re-materialization per the documented precedence; a .vfs with NO declaration builds exactly as today (pure drop-in mode unchanged); the declaration format and precedence rules are documented; the vendorlib_vfs.toml relationship is settled with rationale; the layout store seeds the convention for derived projects.
+
+## Context
+
+Drafted 2026-07-22 (user-approved wording) from the binary-policy framing
+discussion: with G-004 removing checked-in binaries from punkshell, the kit
+.vfs payloads' binary content must come from SOMEWHERE reproducible - suite
+build products (G-103-class batteries and library builds), punkbin artifact
+classes retrieved through the G-006/G-067 consent gates, or vendor trees.
+A per-.vfs toml declaration is the glue that makes a kit payload buildable
+on a clean binary-free tree, while the answer to "can we still just drop a
+dll in?" must stay YES - the folder remains operative, declarations are
+optional, and undeclared drop-ins are preserved (the operate-in-tree
+requirement recorded in G-004 Notes 2026-07-22: local experimentation and
+permissive derived projects are first-class forever).
+
+Precedents already in the tree that make this credible:
+
+- src/runtime/vendorlib_vfs.toml - per-package per-kit declarations ALREADY
+  drive vendorlib-to-vfs inclusion (with superseded-version removal); this
+  goal generalizes that surface (fold or supersede - settled in the work).
+- layout_materialize (G-087, achieved) - the declarative-plus-folder hybrid
+  with overlay/anti mechanics is proven machinery in this codebase.
+- tomlish is vendored, and toml is the accepted format for punkshell-context
+  configuration (the 2026-07-20 toml drop applies only to dependency-free
+  BUILDSUITE BOOTSTRAP configs - recorded in G-103 Context).
+
+Relationship to the punkbin third-class question (G-004 Notes 2026-07-22):
+declarative composition pulling per-package artifacts is the
+preferred-assessment alternative to storing whole zipped binary .vfs
+archives - if this goal lands, the third class likely stays unnecessary
+except as a release-snapshot convenience.
+
+Precedence design (the drop-in guarantee) is the core design work:
+materialization must never clobber an undeclared file, and the documented
+rules must state what happens when a declaration and a drop-in collide on
+the same path (drop-in wins vs declared wins vs error - decided in the work,
+with punkcheck-style tracking of materialized content the likely mechanism
+for telling the two apart).