punkshell/src/vfs

src/vfs - kit payload folders and per-.vfs payload declarations

Each <name>.vfs folder is the payload of a configured kit output (kit mapping: src/runtime/mapvfs.toml), merged with the auto-generated _vfscommon.vfs overlay at bake time. Folder ownership and payload rules: src/vfs/AGENTS.md.

Kit startup script (boot entry, G-031)

A kit's boot entry is a root-level main.tcl in its .vfs folder. Punkshell's kits do not carry the file directly: each .vfs holds a root fauxlink (main.tcl#..+_config+punk_main.tcl#@punk%3a%3aboot,merge_over#.fxlnk) whose target is materialized as main.tcl at bake time - several kits can share one main, and mains live together in _config/.

Since 0.45.0 the main is THIN (G-031): it declares the kit's subcommands and launch defaults at commented ==CUSTOMIZE== points, then hands over to the shared boot core.

• _config/punk_main.tcl - thin main for punkshell's own kits.
• _config/project_main.tcl - the heavily commented thin-main SAMPLE seeded into generated projects (project-0.1 layout). Read it for the customization contract: project subcommands (::punkboot::project_subcommands), launch defaults (noargs/unknownfirst), and the opt-out story.
• _config/punkboot_core.tcl - the boot core MASTER (layout-owned, pull-updatable): mount detection (zipfs incl the 8.6 backport, metakit/starkit, cookfs), package modes incl proj:, path assembly, punk::libunknown, src-mode modpod registration, default dispatch. Delivered into every kit as punkboot/core.tcl by make.tcl vfscommonupdate (the _vfscommon.vfs merge); a main executed as a plain script from _config finds this sibling master instead. Versioned: ::punkboot::core_version.

Rules the bake enforces / respects:

• ONE root startup script per source .vfs: an actual main.tcl OR a root fauxlink resolving to that name - never both, and not two such fauxlinks. The bake REFUSES a colliding kit (G-031 gate; predicate punkboot::utils::vfs_startup_script_report) because merge traversal order would otherwise silently decide which boot script won. A kit with NO startup script stays legal (BAKE-WARNING only). Nested app/main.tcl links (undroidwish-family runtimes, G-129) are a separate path and unaffected.
• _config content reaches kits ONLY as fauxlink targets - a file dropped into _config (e.g a stray main.tcl) does nothing until a .vfs root fauxlink names it.
• A plain hand-written root main.tcl in a .vfs (no fauxlink, no boot core) is fully supported - the punk boot layer is an offer, not an obligation (G-018's plain tclsh kits deliberately carry none).

The launch surface the default dispatch provides (package modes incl proj:, subcommand contracts) is documented runtime-queryably by the punk::args::moduledoc::punkexe package.

Per-.vfs payload declarations (G-115)

A .vfs folder's payload can be DECLARED in a sibling toml file and materialized by the build - while the folder remains the operative assembly area: dropping files in by hand needs no declaration, and materialization never clobbers what it did not itself install.

• Declaration file: src/vfs/<name>.vfs.toml (sibling of src/vfs/<name>.vfs/, so the declaration itself is never part of the kit payload).
• Processed by tclsh src/make.tcl vfslibs, and automatically as a phase of make.tcl bake / bakehouse (a selective bake narrows to the selected kits' folders).
• A .vfs with NO declaration file is untouched - pure drop-in mode, exactly as before.

Entry format

[payload.<entryname>]
source      = "vendorlib_tcl9/win32-x86_64/tcludp1.0.13"  # folder path, resolved per source_root
source_root = "src"        # optional: 'src' (default) or 'packages'
target      = "lib_tcl9"   # optional: folder INSIDE the .vfs (default: the .vfs root)
supersedes  = ["udp1.0.12"] # optional: legacy sibling folders removed from target first
replace     = true         # optional: clean-slate the SAME-NAMED target folder first

• source_root = "src" resolves against src/ - vendor trees (vendorlib*, vendormodules*), suite build products, any folder under src.
• source_root = "packages" resolves against <projectroot>/bin/packages - the untracked, consent-gated punkbin lib tier populated by tclsh src/make.tcl libfetch (artifact declarations + sha1 verification: src/runtime/libpackages.toml). This is how declared BINARY content arrives on a clean tree without being committed (G-004 direction).
• The source folder is installed AS <vfs>/<target>/<source-tail>/.
• target must be a relative path inside the .vfs folder (no ..).
• Unknown keys, missing sources, or an unparseable file fail the build naming the entry.

Per-platform entries (G-127)

A source containing %platform% declares ONE payload selected per consuming kit TARGET - the platform set is derived from the kit mapping (src/runtime/mapvfs.toml: every kit output pairing this vfs, whatever its bake_default), never declared a second time in the payload file:

[payload.tcllibc]
source_root = "packages"
source      = "%platform%/tcl9/tcllibc"   # resolved once per consuming kit target
target      = "lib_tcl9"

• Each platform's copy materializes under _targets/<platform>/<target>/ inside the .vfs folder - VCS-ignored staging (both VCS), regenerable from the declaration.
• At bake time the kit's merged image gets ONLY its own target's subtree: the staging tree is selected (_targets/<kit target>/ overlaid onto the image root) and dropped, upstream of the payload arch scan and the G-125 boot gate.
• supersedes/replace apply within each platform's staging subtree; target must not itself contain %platform% (the staging prefix is implicit).
• A %platform% entry on a vfs no kit mapping consumes has no platform set to derive - it warns and is skipped. A missing per-platform source fails the build naming the entry and platform, exactly like any missing source.
• Stale staging for a target no longer in the mapping is left in place (drop-in-wins posture) - it never reaches an image; delete _targets/<platform>/ by hand to tidy.

Precedence (drop-in wins)

Materialization is punkcheck-tracked (records in src/vfs/.punkcheck, outside kit payloads) using -overwrite synced-targets:

1. Files the mechanism never declared are never touched (undeclared drop-ins survive re-materialization by construction).
2. A file at a declared path is only overwritten when punkcheck's records show the mechanism itself installed it AND it is unmodified since. A pre-existing foreign copy (no install record) or a hand-modified installed copy is PRESERVED and reported ("changed file(s) NOT overwritten" note; per-file punkcheck skip lines).
3. The declared, explicit exceptions: supersedes removes the named legacy sibling folders, and replace = true clean-slates the same-named package folder before install. Use replace, or remove the files, to hand a collided path back to the declaration.

Relationship to the former vendorlib_vfs.toml

The per-package src/runtime/vendorlib_vfs.toml surface (G-037/G-139: [install.<name>] entries with cross-kit target lists) was migrated into these per-.vfs files 2026-07-31 and retired: per-kit files keep each kit's composition readable in one place, give new kits a copy-a-sibling starting point, and are the surface later goals consume (G-141 derivation, G-127 per-target payloads). A leftover vendorlib_vfs.toml is ignored with a warning. Rationale and decision record: goals/G-115-declarative-vfs-composition.md (archived to goals/archive/ once the goal flips).

Demonstration kit

punkdeclare.vfs + punkdeclare.vfs.toml demonstrate the mechanism end-to-end: the folder in VCS carries only the boot fauxlink; its whole binary payload (tcludp from the vendor tree, tcllibc from the packages tier) materializes from the declaration, and the kit's smoke-require (udp, tcllibc - see [kit.punkdeclare] in mapvfs.toml) proves the payload resolves inside the built artifact. tclsh src/make.tcl bake -confirm 0 punkdeclare builds it (bake_default=false keeps it out of full bakes). The materialized punkdeclare.vfs/lib_tcl9/ tree is deliberately NOT committed (ignored in both VCS) - reproducing it from the declaration is the point.