@riddledc/riddle-proof-packs 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof-packs",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Reusable proof pack profiles and metadata helpers for the Riddle proof framework.",
   "license": "MIT",
   "author": "RiddleDC",
@@ -31,7 +31,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@riddledc/riddle-proof": "^0.7.227"
+    "@riddledc/riddle-proof": "^0.8.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/packs/audio-mix/README.md

@@ -0,0 +1,30 @@
+# audio-mix
+
+Reusable Riddle Proof authoring guidance for browser apps that need objective audio evidence.
+
+## Proof claims and evidence roles
+
+- evidence_role: `current_target`
+- atomic claim
+  - claim: a running browser target exposes enough audio state and rendered metrics to support an objective mix-health verdict.
+  - target: an app route with a small proof contract for selected song, mixer state, source readiness, and render metrics.
+  - setup/actions: prepare the audio proof state, render a bounded offline window, capture a screenshot and compact metrics JSON, then classify the result.
+  - evidence: route state, selected song, mixer/source state, mix peak/RMS/headroom, required track energy, console health, and artifact links.
+  - verdict: pass when the objective guardrails hold; review when the evidence is real but taste/listening judgment remains.
+- does not prove
+  - that a mix sounds good to every listener.
+  - mastering quality, room translation, or long-form musical arrangement quality.
+  - backend audio asset correctness unless the profile explicitly checks source fetches and decode receipts.
+
+## Intended use
+
+Use this pack as the generic layer for audio proof packs. App-specific packs should copy the profile template, declare their evidence-role pattern, and record what each run does not prove.
+
+The useful baseline is:
+
+1. State a concrete audio claim.
+2. Capture the route and app proof contract.
+3. Render a short, deterministic audio window.
+4. Assert no silence, no clipping, and required track energy.
+5. Preserve a compact summary plus the full metrics artifact.
+6. Classify failures as product behavior, profile calibration, app-contract gap, runtime environment, or human-review boundary.

package/packs/audio-mix/authoring-guide.md

@@ -0,0 +1,35 @@
+# Audio Mix Authoring Guide
+
+Audio proof works best when the claim is objective. Do not ask the browser to prove that a mix is good. Ask whether a running app can prove no silence, no clipping, expected track energy, UI/render agreement, and a useful listening handoff.
+
+## Start with a small claim
+
+Use a short render window and one route before expanding the matrix. A good first claim is:
+
+> The current target can expose selected song, mixer state, source readiness, and one rendered metrics receipt without clipping or silence.
+
+## Keep the app contract small
+
+The app contract should expose only redacted diagnostic state:
+
+- selected song or fixture id
+- current route
+- mixer state
+- source readiness
+- playback state
+- offline render metrics
+- optional proof-preparation helper
+
+Do not expose secrets, user tokens, private song data, or full audio buffers.
+
+## Calibrate windows before thresholds
+
+If a required track has no energy, first check whether the rendered bars actually contain that instrument. Many apparent audio failures are profile-calibration failures: wrong bars, wrong song fixture, wrong mix preset, or a muted trainer state.
+
+## Preserve both summary and detail
+
+The terminal summary should stay compact. Full per-frame or per-band metrics belong in `proof.json` or a named JSON artifact. A proof pack should explain which fields a reviewer should read first.
+
+## Human review boundary
+
+Objective proof can say the mix is not silent, not clipped, and changed in the intended direction. It cannot replace listening judgment. When taste matters, include a human-review rubric and mark the proof as evidence for review rather than final truth.

package/packs/audio-mix/human-review-rubric.md

@@ -0,0 +1,31 @@
+# Human Review Rubric
+
+Use this rubric when objective metrics pass but the claim still depends on listening judgment.
+
+## Review packet
+
+Include:
+
+- target URL and route
+- selected song or fixture
+- mix profile
+- proof summary
+- screenshots
+- compact objective metrics
+- full metrics artifact
+- caveats about the render window
+
+## Listener prompts
+
+- Is the intended musical focus audible?
+- Does the mix avoid obvious distortion?
+- Are important midrange elements still present on the small-speaker monitor?
+- Did the proof window contain the instrument being judged?
+- Would a different song section change the verdict?
+
+## Verdicts
+
+- `accepted`: objective evidence and listening review support the claim.
+- `needs_profile_calibration`: the proof window or threshold was wrong.
+- `needs_product_change`: the app behavior or mix profile should change.
+- `needs_followup`: evidence is useful but the claim was too broad.

package/packs/audio-mix/metrics-schema.json

@@ -0,0 +1,30 @@
+{
+  "schema": "riddle-proof.audio-mix-metrics.v1",
+  "description": "Compact metrics expected from an audio-mix proof contract.",
+  "required": [
+    "ok",
+    "proofKind",
+    "mixHealth"
+  ],
+  "fields": {
+    "ok": "Boolean verdict for the render operation itself.",
+    "proofKind": "Stable receipt kind, usually offline-audio-metrics or offline-audio-window-set.",
+    "summary.total": "Optional mix score summary when the app has a scoring model.",
+    "mixHealth.rms": "Rendered mix root-mean-square level for the proof window.",
+    "mixHealth.peak": "Rendered mix peak amplitude; values >= 0.98 are treated as clipping risk by default.",
+    "mixHealth.clipping": "Boolean clipping guardrail.",
+    "mixHealth.headroomDb": "Headroom estimate derived from peak.",
+    "mixHealth.lowLevel": "Boolean low-level/silence guardrail.",
+    "instrumentMetrics.*.rms": "Per-instrument energy receipt when available.",
+    "instrumentMetrics.*.peak": "Per-instrument peak receipt when available.",
+    "monitorMetrics": "Optional translated-listening monitor, such as smallSpeaker."
+  },
+  "classification": {
+    "product_regression": "The app rendered objective audio evidence that violates the stated claim.",
+    "proof_insufficient": "The proof could not support the claim because a receipt was missing or too coarse.",
+    "profile_calibration": "The profile chose the wrong window, threshold, fixture, or viewport.",
+    "app_contract_gap": "The app needs a smaller or more stable proof contract surface.",
+    "runtime_environment_blocked": "The browser or preview runtime could not produce valid evidence.",
+    "needs_human_review": "The metrics are real, but the remaining question is subjective listening judgment."
+  }
+}

package/packs/audio-mix/profile.template.json

@@ -0,0 +1,130 @@
+{
+  "version": "riddle-proof.profile.v1",
+  "name": "audio-mix-current-target-template",
+  "target": {
+    "route": "/replace-with-audio-route",
+    "viewports": [
+      {
+        "name": "desktop",
+        "width": 1440,
+        "height": 1000
+      }
+    ],
+    "timeout_sec": 180,
+    "wait_for_selector": "body",
+    "setup_actions": [
+      {
+        "type": "window_eval",
+        "label": "capture-audio-proof-contract",
+        "timeout_ms": 10000,
+        "store_return_to": "__audioProof.contract",
+        "script": "const contract=window.__AUDIO_MIX_PROOF__||window.__RIDDLE_AUDIO_PROOF__||window.__RIDDLE_PROOF_CONTRACT__; const summary=contract?.captureDiagnostic?.()||contract?.getState?.()||null; window.__audioProof={...(window.__audioProof||{}),contract:{available:Boolean(contract),summary}}; return window.__audioProof.contract;",
+        "return_summary_fields": [
+          {
+            "path": "available"
+          },
+          {
+            "path": "summary.route"
+          }
+        ]
+      },
+      {
+        "type": "assert_window_value",
+        "path": "__audioProof.contract.available",
+        "expected_value": true,
+        "timeout_ms": 10000
+      },
+      {
+        "type": "window_call",
+        "label": "render-audio-metrics",
+        "path": "__AUDIO_MIX_PROOF__.renderOfflineMetrics",
+        "args": [
+          {
+            "bars": 1,
+            "seed": "audio-mix-proof-template"
+          }
+        ],
+        "store_return_to": "__audioProof.metrics",
+        "capture_return": true,
+        "timeout_ms": 90000,
+        "return_summary_fields": [
+          {
+            "path": "ok"
+          },
+          {
+            "path": "mixHealth.peak"
+          },
+          {
+            "path": "mixHealth.rms"
+          },
+          {
+            "path": "mixHealth.clipping"
+          }
+        ]
+      },
+      {
+        "type": "assert_window_value",
+        "path": "__audioProof.metrics.ok",
+        "expected_value": true,
+        "timeout_ms": 10000
+      },
+      {
+        "type": "assert_window_number",
+        "path": "__audioProof.metrics.mixHealth.peak",
+        "max_value": 0.98,
+        "timeout_ms": 10000
+      },
+      {
+        "type": "assert_window_number",
+        "path": "__audioProof.metrics.mixHealth.rms",
+        "min_value": 0.005,
+        "timeout_ms": 10000
+      },
+      {
+        "type": "screenshot",
+        "label": "audio-mix-current-target",
+        "mode": "viewport"
+      }
+    ]
+  },
+  "checks": [
+    {
+      "type": "selector_visible",
+      "selector": "body"
+    },
+    {
+      "type": "no_fatal_console_errors"
+    }
+  ],
+  "artifacts": [
+    "screenshot",
+    "console",
+    "dom_summary",
+    "proof_json"
+  ],
+  "baseline_policy": "invariant_only",
+  "failure_policy": {
+    "environment_blocked": "neutral",
+    "proof_insufficient": "review",
+    "product_regression": "fail",
+    "needs_human_review": "review"
+  },
+  "metadata": {
+    "pack_id": "audio_mix",
+    "pack_public_name": "Audio Mix Pack",
+    "evidence_role_pattern": "current_target",
+    "purpose": "Template for objective audio mix-health checks against a running browser target.",
+    "required_receipts": [
+      "audio proof contract is available",
+      "offline audio metrics render completed",
+      "mix peak stays below clipping threshold",
+      "mix RMS stays above silence threshold",
+      "screenshot and console health are captured"
+    ],
+    "does_not_prove": [
+      "subjective taste or mastering quality",
+      "full-song coverage",
+      "backend asset correctness unless source readiness checks are added"
+    ]
+  }
+}

package/packs/audio-mix/ratchet-method.md

@@ -0,0 +1,26 @@
+# Audio Mix Ratchet Method
+
+The audio ratchet is:
+
+1. State a claim.
+2. Run the proof.
+3. Preserve evidence.
+4. Classify the failure.
+5. Change the smallest user-controlled layer.
+6. Rerun with a sharper claim.
+7. Extract reusable pack guidance.
+
+## Smallest layer order
+
+Prefer changes in this order:
+
+1. Profile JSON: route, fixture, viewport, render window, threshold.
+2. Proof pack docs/template: reusable language or receipt shape.
+3. App proof contract: expose a stable diagnostic helper.
+4. App fixture data: provide a deterministic proof window.
+5. Artifact summary/rubric: make evidence easier to review.
+6. Riddle Proof core: only when a missing primitive is general across apps.
+
+## Evidence-role naming
+
+Use `current_target` for audit/no-diff proof, `reference_candidate` for change proof across targets, and `interaction_snapshots` for pre-action/post-action evidence inside one run. Avoid using "before/after" by itself in user-facing docs.

package/packs/neon-step-sequencer/README.md

@@ -0,0 +1,41 @@
+# neon-step-sequencer
+
+Reusable Riddle Proof profiles for Neon Step Sequencer audio and mix-health ratcheting.
+
+This pack is the first app-specific lab for the open Riddle Proof architecture. It is intentionally built from user-controlled layers: profile JSON, proof-pack docs, app proof contracts, metrics fixtures, and human-review rubrics. Riddle Proof core should change only if the lab discovers a missing primitive that is generally useful across apps.
+
+## Proof claims and evidence roles
+
+- evidence_role: `current_target`, `interaction_snapshots`
+- atomic claim
+  - claim: Neon Step Sequencer can connect visible mixer state, app proof-contract state, and rendered audio metrics for a bounded proof window.
+  - target: `/games/drum-sequencer` with a selected song/mix fixture.
+  - setup/actions: wait for Neon, install proof helpers, prepare audio sources, render offline metrics, optionally apply a visible mix change, and capture screenshot/console/proof artifacts.
+  - evidence: route state, selected song, mixer/source/playback state, rendered metrics, pre-action/post-action snapshots, viewport layout, and browser health.
+  - verdict: pass when objective guardrails hold; review when evidence is useful but subjective listening judgment remains.
+- does not prove
+  - that the mix is aesthetically good.
+  - every song section or every song/mix combination unless the exploration profile is run.
+  - production audio asset availability unless source-readiness receipts are included.
+
+## Profiles
+
+- `profiles/fast-mix-health.json`: current-target audit for one quick render.
+- `profiles/source-readiness.json`: current-target audit for sample/source decode readiness.
+- `profiles/playback-sync.json`: interaction proof for visible playback and contract state.
+- `profiles/mix-change-before-after.json`: interaction proof using pre-action/post-action snapshots inside one run.
+- `profiles/mobile-trainer-layout.json`: current-target audit for phone/tablet trainer reachability.
+- `profiles/full-mix-health-matrix.json`: current-target matrix across desktop, phone, iPad Mini, and iPad.
+- `profiles/explore-songs-and-mixes.json`: exploration sweep for proof-window health.
+
+## Example evidence
+
+The `examples/` directory contains three local Playwright proof results captured against LilArcade Neon Step Sequencer on May 24, 2026:
+
+- `run-001-fast-mix-health`: passing `current_target` audit with proof contract, source readiness, mix RMS `0.1234`, peak `0.8321`, and no clipping.
+- `run-002-mix-change`: passing `interaction_snapshots` proof where a bass-level edit moved bass RMS from `0.0507` to `0.1071` and mix RMS from `0.073` to `0.1264` without clipping.
+- `run-003-full-matrix`: passing `current_target` viewport matrix across desktop, phone, iPad Mini, and iPad with `0 px` horizontal overflow.
+
+## Naming note
+
+The file `mix-change-before-after.json` keeps the project shorthand from the original Neon plan. The evidence-role pattern is `interaction_snapshots`: pre-action and post-action snapshots inside one proof run. It is not the universal Riddle Proof model.

package/packs/neon-step-sequencer/case-study/findings.md

@@ -0,0 +1,102 @@
+# Neon Ratchet Findings
+
+This file records findings from live runs. Keep entries factual and classify the smallest weak layer.
+
+## Finding template
+
+- run:
+- claim:
+- observed evidence:
+- classification:
+- smallest layer changed:
+- change made:
+- rerun:
+- next sharper question:
+
+## Seed findings to watch for
+
+### App contract too coarse
+
+The proof can see route and UI state but not enough mixer or per-track metric state.
+
+Likely change:
+
+`lilarcade/src/proof/neonProofContract.ts`
+
+### Metric moved, but not as expected
+
+A visible mix control changes UI state but the offline render path remains stale.
+
+Likely change:
+
+Neon app render path or proof-preparation path.
+
+### Wrong musical window
+
+The selected proof bars do not contain the target instrument.
+
+Likely change:
+
+Profile render window, song fixture, or authoring guide.
+
+### Subjective boundary
+
+Metrics pass, but deciding whether the mix is better requires listening.
+
+Likely change:
+
+Human-review rubric and artifact summary.
+
+### Output too noisy
+
+Full metrics are useful in `proof.json`, but the terminal summary is hard to scan.
+
+Likely change:
+
+Pack summary guidance first; Riddle Proof core only if a general display primitive is missing.
+
+## Live findings
+
+### Run 001 established the app-contract baseline
+
+- run: `run-001-fast-mix-health`
+- claim: the current Neon target exposes route, selected-song, source, mixer, and offline render receipts.
+- observed evidence: route matched `/games/drum-sequencer`; proof contract available; all audio source readiness flags true; mix RMS `0.1234`; peak `0.8321`; clipping `false`; console fatal count `0`.
+- classification: none; passing `current_target` audit.
+- smallest layer changed: app proof contract and profile JSON.
+- change made: added a Neon proof contract and a fast profile that reads contract state and renders one bounded offline audio window.
+- rerun: passed on May 24, 2026.
+- next sharper question: can a visible mix edit produce measurable rendered movement?
+
+### Run 002 proved interaction movement without clipping
+
+- run: `run-002-mix-change`
+- claim: a bass-focus mix edit moves rendered audio metrics without clipping.
+- observed evidence: bass level changed from `0.62` to `1.35`; bass RMS moved from `0.0507` to `0.1071`; mix RMS moved from `0.073` to `0.1264`; post-action peak `0.6555`; clipping `false`.
+- classification: none; passing `interaction_snapshots` proof.
+- smallest layer changed: profile only.
+- change made: captured pre-action and post-action offline metrics in one proof run.
+- rerun: passed on May 24, 2026.
+- next sharper question: does the current target stay healthy across device-shaped viewports?
+
+### Run 003 widened the target audit to viewport matrix evidence
+
+- run: `run-003-full-matrix`
+- claim: route, contract, metrics, and layout guardrails hold across desktop, phone, iPad Mini, and iPad.
+- observed evidence: all viewports matched `/games/drum-sequencer`; all reported `0 px` horizontal overflow; all rendered RMS `0.0732`, peak `0.5402`, and no clipping; console fatal count `0`.
+- classification: none; passing `current_target` matrix audit.
+- smallest layer changed: profile only.
+- change made: widened the current-target proof from one desktop viewport to four viewport shapes.
+- rerun: passed on May 24, 2026.
+- next sharper question: can the exploration profile produce a prioritized song/mix confidence map?
+
+### Local runner shutdown needs a small ergonomics follow-up
+
+- run: `run-002-mix-change`, `run-003-full-matrix`
+- claim: proof artifacts should be written and the CLI process should exit cleanly.
+- observed evidence: complete passing artifacts were written, but the wrapper process lingered after artifact write and had to be stopped.
+- classification: `proof_insufficient` for operator ergonomics, not a Neon product regression.
+- smallest layer changed: none in this pack.
+- change made: documented the issue and used an outer timeout for the matrix run.
+- rerun: not yet rerun after a runner fix.
+- next sharper question: should the local runner force-close browser handles or expose a clearer artifact-written exit phase?

package/packs/neon-step-sequencer/case-study/ratchet-card.md

@@ -0,0 +1,39 @@
+# Neon Ratchet Card
+
+## Thesis
+
+We used Neon Step Sequencer to prove the new Riddle Proof architecture: not by replaying old bugs, but by creating a new proof pack and letting it discover what the next useful proof should be.
+
+## Tagline
+
+The ratchet is not a pass. The ratchet is the next sharper question.
+
+## Starting claim
+
+When the user applies a mix change in Neon Step Sequencer, the visible mixer state, app proof contract, and rendered offline audio metrics should agree.
+
+## User-controlled layers
+
+- profile JSON
+- proof pack template
+- thresholds and metrics config
+- app proof contract
+- app diagnostic helper
+- fixture data
+- runner selection
+- artifact summary
+- human-review rubric
+
+## Public value
+
+The project shows that a complex audio app can improve proof confidence mostly by editing proof packs, profiles, and app contracts, not Riddle Proof core.
+
+## Demonstrated runs
+
+- Run 001: a `current_target` audit connected the Neon route, proof contract, source readiness, and offline mix-health metrics.
+- Run 002: an `interaction_snapshots` proof showed a bass-level edit moving bass RMS from `0.0507` to `0.1071` and mix RMS from `0.073` to `0.1264` without clipping.
+- Run 003: a `current_target` matrix passed across desktop, phone, iPad Mini, and iPad with `0 px` horizontal overflow.
+
+## Honest boundary
+
+These runs prove objective claims about a running app target. They do not prove that the mix is tasteful, that every song section is healthy, or that a release candidate is better than production. Those are separate proof claims with separate evidence roles.