feat(audio): add provider-neutral MusicPlan contract

[zedarvates]

Summary

Adds a provider-neutral symbolic MusicPlan between StoryCore narrative intent and music generation.

• Defines MusicPlan v1 with full, guided, and free modes, section timing, motifs, instrumentation roles, synchronization cues and separate dependency provenance.
• Composes Draft 2020-12 schema validation with deterministic timeline/reference checks and declared non-commercial/unknown model-weight licence policy.
• Reports recursive requested/executed differences, including shortened duration, emptied lists and nested cue changes.
• Adds a deterministic mock provider and a portable data-only handoff containing identity, deltas, candidate metadata and verification declarations.
• Adds 18 focused regression tests, three reference fixtures and five controlled invalid-input cases.
• Adds a JSON-stdin private holdout evaluator protocol containing no holdout cases. It is intended to be invoked by Botte Secrète's private holdout runner; private cases remain outside this repository.

Current exact-head evidence

Current head: 385a2ea631c271bc44e0169d81b8062f2408bd9d.

MusicPlan Contract run #17 executes on Python 3.10 and 3.12. Both jobs completed successfully, including:

• focused MusicPlan tests;
• controlled negative mutation probe;
• private holdout evaluator protocol smoke;
• Draft 2020-12 schema check and reference fixture validation;
• compilation of validator, provider, mutation probe and holdout evaluator.

The public holdout protocol smoke uses only the already-public reference fixture. It proves evaluator wiring, not secrecy or adequacy of any future private holdout.

Private holdout boundary

scripts/music_plan_holdout_evaluator.py accepts one JSON request on stdin:

{"id":"opaque-id","input":{"plan":{},"expected_valid":true}}

and emits only:

{"passed":true}

The evaluator contains no private cases and performs no network I/O, model activation, publication or promotion. Private case payloads and hidden expected outcomes must remain outside the public repository and should be supplied only by an external/operator-owned holdout runner.

Previous proven correction

At 189d3d15fc711b006405ecd997485a4583ab5e4c, MusicPlan Contract #15 proved 18 tests on both Python versions, all five controlled invalid inputs rejected, Draft 2020-12 schema/fixture validation, and the corrected module-mode mutation command. The current head extends that contract only with the holdout evaluator protocol and its CI smoke.

Remaining proof boundary

Still unproven:

• execution of a genuinely private/external MusicPlan holdout set;
• independent authorship/quality of that holdout;
• authenticated holdout issuer identity/signature;
• real audio generation and quality;
• complete legal/output-rights qualification;
• hardware performance;
• end-to-end StoryCore/Botte integration beyond the data/protocol boundary;
• last-known-good promotion/recovery.

The handoff still carries caller-supplied digest/evidence references rather than independently resolving them. Private holdout attestation and artifact verification remain separate evidence layers.

Activation boundary

No real provider/model activation, weight download, network inference, publication, automatic promotion or merge is authorized. Keep draft.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud