Skip to content

t1k:playablelabs:base:params-audit

FieldValue
Modulebase
Version2.29.2
Effortmedium
Tools—

Keywords: dead param, dirty set, LOGIC-DEAD, param audit, param cache, parameter audit web, params audit incremental, playthrough, UNWIRED, visual gate

/t1k:playablelabs:base:params-audit
[--root <dir>] [--adapter <path>] [--full] [--no-runtime] [--runtime-results <file>] [--json] [--no-write] [--check] [--explain <key>]

Incremental Param Audit (engine-neutral core, contract v1.3)

Section titled “Incremental Param Audit (engine-neutral core, contract v1.3)”

Finds parameters declared but never reaching the game (UNWIRED, NO-OP, LOGIC-DEAD, NULL-REF), then plays every visually testable one and checks the target’s region really changes, re-doing only what a change could have affected. An adapter holds the engine specifics; this skill owns scan, cache, dirty set, status, report, receipt, exit code. Spec (binding): references/cache-contract.md; change the contract first, never this file alone.

  1. Scans every source file once (token counts, declaration index), classifies each LIVE key from .param-audit/probe.json.
  2. Computes the dirty set, calls adapter.auditParams for dirty keys only, carries the rest from cache.json.
  3. Playthrough (default-on): each visual key’s closureHash carries a valid result from status.json; the rest go to runtime.needed, the adapter’s probe plays them and writes probe-results.json.
  4. Committed: status.json, plus probe.json (hand-authored or scaffolded by the probe’s --init). Local, ignored: cache.json, report.json, probe-results.json, local/shots/ (the core writes .param-audit/.gitignore once, never rewrites it).

bun <skill>/scripts/param-audit.cjs --root <game> [--adapter <adapter.cjs>] (no --adapter: the one installed adapter that detects the root, else an error).

flagmeaning
--fullignore the cache (reason forced), carry no runtime result
--no-runtimeopt out of the playthrough: receipt not-run, verdict UNKNOWN, never PASS; stored results kept
--runtime / --runtime-results <file>deprecated no-op (default-on; note on stderr) / stamp a probe’s rows with each key’s current closureHash, conflicts with --no-runtime
--checkexit 1 if the cache or the committed status.json is stale; never writes; CI runs this
--json / --no-writemachine output (dirty keys carry explain) / write nothing
--explain <key>print why the key is dirty: reasons, the shortest declaration chain to each changed declaration, hub counts that moved

Exit 0 ran, no DEAD param, no runtime FAIL; 1 DEAD, runtime FAIL, or --check stale; 2 could not run (adapter threw, unreadable probe.json, conflicting flags), nothing written.

Every LIVE key in probe.json is visual ({key, values >= 2 distinct, stateExpr, region}), not-visual ({key, visual:false, reason}, reason audio | sdk | store-link | logic-only | other:<text>) or unclassified (unprobed). A run never applies suggestVisual. The visual gate (scripts/lib/visual-gate.cjs) diffs only the target’s own region against two control shots: VISIBLE | NOT-VISIBLE | UNVERIFIABLE-visual; noisy controls are UNVERIFIABLE-visual, never NOT-VISIBLE. A VISIBLE change must also clear the perceptibility floor minMeanDelta (default 4 of 255, a margin override).

inputcounts as
visual key, gate PASSprobed, pass
APPLIED-OK-NOT-VISIBLE, NO-EFFECT, WRONG-TARGETprobed, failed
UNVERIFIABLE, UNVERIFIABLE-visual, no result, unclassifiedunprobed, never carried
not-visualexempt (counted, listed)

Receipt fail if any failed; unknown if anything is unprobed or the probe ran --no-visual; clean otherwise; not-run under --no-runtime. Verdict FAIL on a DEAD param or runtime fail; PASS only with no DEAD, no UNKNOWN param and a clean receipt.

A key is re-audited when its definition, read spans, a tracked token count, OR any declaration it flows through changed: editing hpHandler in applyHp -> setHp -> hpHandler dirties exactly Hp (reason reach), static and playthrough together. Reach follows names from the read spans (3 hops) plus the readers of the field the key writes; comments, whitespace and JSON/CSS never dirty. Real 81-param game: a SfxVolume default or apply edit audits 1, the setSfxVolume sink body 4, a config comment 0.

String-keyed dispatch and reflection are invisible to the graph (--full forces). Name collisions over-dirty, never under-dirty. A hub identifier (declared by more than 8 or mentioned by more than 60 declarations) is never expanded, so flow through a generic hub name is invisible. A require/import is followed only through names the code mentions; code without semicolons merges statements. Identical frames read NOT-VISIBLE (no capture-degenerate verdict). A tracked token in a comment dirties its keys.

Export { id, version, detect, listParams, readSpans, auditParams } (optional scan, runtimeSpans, suggestVisual; contract section 3). readSpans returns text found verbatim; auditParams lists in reads.tokens every identifier whose occurrence count the verdict used. Prove it: copy tests/fixtures/toy-adapter.cjs, run the differential suite, make the toy-adapter-broken-*.cjs stubs go red against yours. Probe, region resolution and probe.json scaffold stay in the adapter’s skill.

The mechanical steps (running scripts/param-audit.cjs and its selftests, and reading the audit status it writes) are run by the cheap-tier t1k-tester agent. The verdict and any dirty-set decision stay with the calling agent.

t1k-playablelabs-base-params is the runtime and WEB publish side; t1k-cocos-playable-parameter-audit the heavy Cocos-only audit. Tests: bun test <skill>/tests/*.test.cjs; a new check is not done until it has gone red on a broken core.