4.0 KiB
G-178 punk::args multi-provider safety: id ownership, idempotent registration, declared format level
Status: proposed Scope: src/modules/punk/args-999999.0a1.0.tm (duplicate-id detection and policy, register protocol idempotency and diagnostics, definition format-level declaration, display-field command-substitution trust boundary); src/modules/AGENTS.md (third-party definition authoring guidance); src/tests/modules/punk/args/testsuites/args/ (new coverage) Goal: punk::args is safe to open to definition providers outside this repo - a second definition claiming an existing id is detected and reported rather than silently overwriting the first, namespace registration is idempotent and its failures are diagnosable rather than silent, a definition can declare the punk::args feature level it requires so an older punk::args fails with a named error instead of an opaque parse failure, and the trust boundary for command substitution inside third-party help text is documented and enforceable. Acceptance: a second definition claiming an existing id produces a named duplicate-id diagnostic identifying both providers with the resolution policy documented (today the todo at ~args:5137 - "last will silently win"); registering the same namespace twice leaves exactly one registry entry (pin) and a registered namespace that never materializes is reported rather than silently skipped; a definition may declare a required format/feature level and one requiring a level above the running punk::args raises a named error naming both levels (pin) while an unmarked definition keeps today's behaviour; the command-substitution trust boundary for display fields is documented in define -help and src/modules/AGENTS.md with a mode in which untrusted definitions render without command substitution, pinned by a fixture whose help text would otherwise execute a command; full punk/args suite passes.
Context
Drafted 2026-08-08 from the same scalability review as G-177 (see that file for the measured baseline). Where G-177 is about cost, this goal is about what happens when the definition corpus stops being single-authored.
-
Flat global id namespace with silent collisions. Ids are plain strings in one dict, and update_definitions carries an explicit
#todo - detect duplicate ids (last will silently win.. should be reported somewhere)(~args:5137). Ids such as (script)::build are plausible collisions across vendors, and the loser vanishes without a trace. -
Registration is lappend into a foreign namespace variable (
lappend ::punk::args::register::NAMESPACES ::punk::lib ...) - no dedup (measured: two entries after a double append), no unregister, no diagnostic if the namespace never appears. The lazy no-load-required design here is GOOD and worth preserving; only its bookkeeping is unguarded. -
No format-level declaration. There is no @requires-style directive and one interp holds one punk::args. A library authored against newer directives fails opaquely on an older punk::args, with no way to state the dependency.
-
Help text is executed code. ${...} bodies are tstr-evaluated with -allowcommands in the defining namespace at resolve time (~args:2197). Rendering third-party documentation runs third-party code - defensible in-repo, but it needs stating before external providers arrive.
Notes
- Related: G-167 (version-delta availability) - adjacent but distinct, and named here to prevent conflation. G-167 declares deltas in a COMMAND'S OWN INTERFACE across Tcl versions; G-178 declares the DEFINITION FORMAT LEVEL a definition needs from punk::args.
- Related: G-075 (punk::args (package) ids) - shares the id registry; a duplicate-id policy must cover (package)- and (autodef)-prefixed ids.
- Related: G-177 (scale independence) - the engine goal. Registration dedup is a performance requirement there and a correctness requirement here; whichever lands first satisfies the other's share.
- Ordering: G-177 first is the natural sequence - its set-based registry work is where dedup and the "registered but never materialized" diagnostic naturally sit.