# 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; achieved
  2026-07-22, archived at goals/archive/G-103-runtime-kit-family.md).

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

## Notes

- G-024 relationship (recorded 2026-07-24 after overlap review; neither file previously
  referenced the other): G-024 converts mapvfs.config to toml, and archived G-037 named
  that file as the natural home for per-kit vendorlib payload declarations - this goal's
  territory. The two toml surfaces (mapping/schemes there, payload declarations here)
  are designed as sibling grammars in one family; the vendorlib_vfs.toml fold/supersede
  decision (Acceptance) cites the G-024 scheme format.
- G-019 relationship: G-019's dependency-scan closure plus declared dynamic extras is a
  payload-determination INPUT this goal's materialization could consume - a trimmed kit
  is then a declared kit whose declaration was generated rather than hand-authored.
- G-065 relationship: G-065's declarative vendoring manifest and this goal's .vfs
  declaration are the same design space (toml-declared, pinned, provenance-tracked
  external content) - G-065's upstreams feed the sources, this goal's declarations
  materialize the folder. Keep the schemas aligned.