Guitar Pro Loss Observatory: support matrix, stable loss codes, corpus prevalence and minimized fixtures

[PhysShell]

Classification

• Change type: enhancement / adapter quality and corpus observability
• Priority: P1
• Expected value: very high — makes GP fidelity gaps measurable and prioritizable from the real corpus
• Estimated effort: medium-high
• Implementation risk: medium — incomplete instrumentation can under-report losses
• Recommendation: YES, strong quality improvement; implement before adding GP features by intuition alone
• Related: engine: auto-derive chord-quality / structural / rhythm tags; parse pull-off, tap, let-ring #75
• Stage ownership: S3 adapter quality; consumers may include S5 corpus and S8 inspector

Problem

S3 requires Guitar Pro import to preserve guitar semantics and emit a LossReport. The code and docs identify individual unsupported/missing mappings, but there is no single machine-readable coverage matrix answering:

Which GP constructs are observed?
Which are parsed by the upstream library?
Which reach Griff's canonical model?
Which survive projections/generation/export?
Which are lost, flattened or approximated?
How frequently does each loss affect the actual corpus?

Issue #75 already exposes the practical failure mode: pull-off exists upstream but is not mapped; tap and let-ring require additional model work. Without prevalence data, roadmap priority is still driven partly by whichever missing articulation happened to be noticed last. Humans have used worse prioritization methods, but that is not a reason to preserve them.

Goal

Build a Guitar Pro Loss Observatory that combines:

1. a machine-readable construct support matrix;
2. stable typed loss codes;
3. per-file and corpus-wide prevalence reports;
4. minimized regression fixtures for confirmed losses;
5. CI gates preventing supported constructs from silently regressing.

Support matrix

Track each construct across explicit stages:

construct
upstream parser observed
GP adapter mapped
canonical model representation
source provenance retained
preview/tab projection
regeneration preservation
export support
loss/approximation code
fixture coverage
fuzz seed coverage

Initial vocabulary should include at least:

string/fret assignment
bend
slide
hammer-on
pull-off
tap
let-ring span
palm-mute span
natural/artificial/pinch harmonic
grace note
tie
tuplet
vibrato
accent/ghost/staccato/dead note
whammy
multiple voices
repeat / alternate ending
tempo change
time-signature change
triplet feel / swing metadata

The matrix is data, not a hand-maintained README table that can drift politely for months.

Stable loss codes

Introduce versioned codes such as:

GPLOSS001  parsed construct has no canonical representation
GPLOSS002  canonical representation exists but adapter does not map it
GPLOSS003  construct is flattened/approximated
GPLOSS004  provenance (string/fret/technique extent) is lost
GPLOSS005  unsupported container/version feature

Specific codes may be finer-grained, for example pull-off-unmapped vs let-ring-model-missing. Requirements:

• stable identity across wording changes;
• severity/fidelity class separate from message text;
• source location/track/bar/note context where available;
• one file may carry multiple occurrences of the same loss;
• unknown constructs fail visibly rather than disappearing into a generic warning count.

CLI/report surface

Suggested commands:

griff gp-losses song.gp5 --format human|json
griff gp-support corpus/gp --format markdown|json
griff gp-loss-minimize <file> --loss GPLOSSxxx

Corpus report should include:

occurrence count
affected file count
affected accepted-chunk count / percentage
format/version distribution
construct examples
first/minimized fixture references

Minimization

For each confirmed loss, provide a bounded reducer that attempts to remove unrelated:

• tracks;
• bars;
• voices;
• notes;
• techniques/metadata;

while preserving the same loss code after import.

The reducer must preserve a valid parseable GP fixture. If safe structural rewriting is not possible for a format/version, support a fixture-extraction path or explicit not-minimizable result rather than corrupting binary files and calling it science.

CI policy

1. Every supported construct has at least one fixture.
2. Every confirmed loss has a fixture or explicit corpus-only evidence.
3. A construct moving from unsupported to supported updates the matrix and turns its fixture into a positive conformance test.
4. Known loss counts on pinned fixtures cannot silently drop because instrumentation stopped firing.
5. Corpus prevalence runs may be scheduled/non-blocking; fixture conformance remains blocking.

Required controls

1. Pull-off fixture currently reports the expected unmapped loss; after engine: auto-derive chord-quality / structural / rhythm tags; parse pull-off, tap, let-ring #75 support lands it becomes mapped with no stale loss.
2. Let-ring fixture distinguishes model-missing from parser-missing.
3. Multiple occurrences in one file are counted independently.
4. Unsupported GP version/container reports a typed container loss.
5. A fully supported fixture produces an empty loss set and proves the observer has teeth with a paired lossy fixture.
6. Unknown upstream construct/enum value fails visibly.
7. Re-running a pinned corpus produces deterministic normalized counts.
8. Minimizer preserves the selected loss code and removes unrelated content.
9. Loss report retains source format/version and track/bar/note context where known.
10. Support matrix, code vocabulary and fixture expectations cannot drift independently in CI.

Acceptance

• Versioned support-matrix schema and loss-code catalog are documented.
• GP importer emits stable typed loss occurrences with source context.
• CLI can report one file and aggregate a corpus.
• Initial matrix covers the existing mapped techniques plus engine: auto-derive chord-quality / structural / rhythm tags; parse pull-off, tap, let-ring #75 gaps.
• At least three real loss types have permanent minimal fixtures.
• CI pins positive support and known-loss behavior.
• Corpus prevalence identifies the highest-impact unsupported constructs without modifying generation behavior.
• S8 can consume loss/provenance data without reimplementing adapter logic.

Non-goals

• No requirement to implement every missing GP construct in this issue.
• No GP export implementation.
• No automatic acceptance/rejection of corpus chunks solely from loss count.
• No replacement of fuzzing; this is semantic coverage, not only robustness.
• No claim that absence of a reported loss proves perfect fidelity until the matrix covers the construct.