# G-024 mapvfs.config converted to toml (tomlish-parsed) with succinct scheme declarations

Status: proposed
Scope: src/runtime/mapvfs.config (replaced/deprecated), src/make.tcl (parsing), src/bootsupport/modules/tomlish-*.tm (parser dependency)
Goal: the runtime-to-vfs-to-executable build mapping moves from the custom line format of src/runtime/mapvfs.config to a toml file parsed with the tomlish package - still supporting explicit per-executable mappings (runtime, vfs folder, output name, kit type) while also expressing generative schemes like the G-023 versioned naming in a single succinct declaration.
Acceptance: a mapvfs toml file parsed via tomlish (no ad-hoc toml parsing) drives the build: every mapping currently active in mapvfs.config is expressible and at least one existing target builds identically from the toml; the G-023 versioned/dev/release-gated output scheme is declared in one entry that expands to its outputs without enumerating versions; malformed or unresolvable entries fail the build with a clear message naming the entry; the legacy .config format is either fully migrated (old parser removed) or explicitly deprecated with documented precedence between the two files.

## Context

src/runtime/mapvfs.config maps runtime binaries and .vfs folders to named
executables in a custom line format: one line per runtime, being the runtime
filename followed by kit-configuration lists of 1-3 elements
({vfsfolder ?outputname? ?kittype?}, kittype in kit|zip|zipcat, `-` as runtime
for runtime-less .kit builds, no-entry runtimes matching same-named .vfs
folders implicitly). make.tcl parses it inline (~2795-2845). The format works
but is idiosyncratic (comment/blank handling, positional defaults), is parsed
ad hoc, and has no way to express a *scheme* - every output is one literal
mapping, which conflicts with G-023 where output names derive from the project
version at build time.

tomlish is the project's toml parser (vendored at src/vendormodules and
src/bootsupport/modules - the bootsupport copy matters since make.tcl is build
tooling), so the replacement format is toml parsed via tomlish, consistent
with the G-014 direction of toml + tomlish for declared configuration.

## Approach

- A mapvfs toml file in src/runtime/ carrying two kinds of declarations:
  - **Explicit mappings** - the current capability, one entry per output:
    runtime, vfs folder, output name (defaulting from the vfs name), kit type.
    Everything active in mapvfs.config today must be expressible.
  - **Scheme declarations** - generative entries expanded by make.tcl, first
    consumer being the G-023 versioned scheme: one entry per Tcl generation
    declaring runtime + vfs + scheme=versioned (or similar) that expands to
    punkN-<M>-<m>-<p>.exe, punkN-dev.exe and the release-gated punkN.exe
    without enumerating versions.
- Validation with entry-level error reporting: a malformed or unresolvable
  entry (missing runtime file, missing vfs folder, unknown kit type/scheme)
  fails the build naming the offending entry - matching the current warnings
  but structured.
- Legacy handling is a decision to record here: either full migration (convert
  the file, delete the old parser) or a deprecation window (toml wins when
  present, .config honoured with a deprecation warning). Full migration is
  preferred - the file is small and repo-internal - unless project_layouts
  templates complicate it (layout copies of make.tcl/mapvfs.config sync via
  G-012 territory; note in completion report, do not hand-sync layouts).

## Alternatives considered

- Keeping the custom line format and extending it with scheme syntax -
  rejected: doubles down on an ad-hoc parser exactly where the project is
  standardising on toml + tomlish.
- Tcl-script config (source-able dict) - rejected for the same reason as in
  G-014: toml is the declared configuration format, editable without Tcl
  knowledge.

## Notes

- The commented-out historical entries in mapvfs.config (broken-runtime notes,
  test cases) are documentation of past pitfalls - carry the useful ones into
  toml comments or this file rather than losing them.
- Related: G-023 (first scheme consumer), G-014 (toml+tomlish direction and
  the tomlish punk::args-documentation precondition - that precondition gates
  punk::config consumption; build-tooling use here can proceed with tomlish
  as-is), G-012 (layout template refresh, if layout copies of runtime config
  are affected).