epiphany/spec/CONTRACT_GENESIS_G1_INSTRUMENT.md

Contract: genesis tranche G1 — CreateInstrument, and the from-empty spine

Repo root /home/jeans/Repos/active/epiphany. Governed by spec/RULING_GENESIS_PERSISTENCE.md (011c68a; identity sub-decision ruled at ec17d06) and spec/PLAN_GENESIS_OPS.md §4 (439e1e2), whose G1/G2/G3 ladder the user ratified 2026-07-24.

Execution model as every tranche on this track: Sonnet subagent, coordinator line-level review with independent mutation re-runs, user deep-dive at contract sign-off and final report. Mutation discipline throughout: anchor-assert before substituting, restore by reversing, never git checkout.

Parallel safety. The editor track owns epiphany-editor-core, epiphany-editor-gui, epiphany-layout-ir, epiphany-render-svg, the new epiphany-glyphs crate, every crates/epiphany-editor-gui/goldens/*.png, and spec/PLAN_EDITOR_APP.md + spec/CONTRACT_EDITOR_*.md. This packet touches none of them. Do not stage them; do not git add -A.

---

What this packet does, in one sentence

Adds one operation kind, CreateInstrument, so that a Score::empty(identity) plus an operation log can materialize a note-bearing score — and makes the from-empty path correct in the two ways the ruling requires.

Why it is this small

CreateInstrument is the single missing link between an empty score and a note. Score::empty (core/src/graph.rs:1747) yields Canvas::default() and empty vectors; from there the chain is

Score::empty → CreateInstrument (MISSING) → CreateStaff ✓ → CreateRegion ✓
             → CreateStaffInstance ✓ → CreateVoice ✓ → InsertEvent ✓

Every later arrow exists today with graph-aware preconditions. CreateStaff already requires a live Instrument (reduce.rs:3824-3833) — which nothing can currently create. That is the whole gap.

Instrument (core/src/graph.rs, fields id, name, range, abbreviation, sound_config, transposition, default_clef, default_staff_lines, unpitched_members) holds no outbound entity references. It is a root, so this operation needs no referential preconditions — only mint/idempotence.

Design pins

1. No wire layout is designed. Instrument already has a Codec and already ships inside Score. Add Instrument to canonical_value! (core/src/codec.rs:3484) and encode the payload as push_lp_bytes(out, &self.instrument.canonical_bytes()) — the CreateStaffOp template verbatim (ops/src/payload.rs:1411). The generated decode_canonical already rejects non-canonical encodings, so strict-form enforcement is inherited, not written.
2. Discriminants: kind 31, tag 31. Both spaces currently top out at 30 (TransposeInterval). They coincide here by accident, not by rule — the two spaces are independent and misaligned elsewhere (RespellPitch is kind 2 / tag 3; CreateVoice is kind 19 / tag 20). Append-only under req:binfmt:kind-discriminants.
3. Name it CreateInstrument in both spaces, catalog name "create-instrument". The tag layer's older Create→Insert convention (InsertStaff for kind CreateStaff) is not followed: the two most recent additions, CreateVoice and CreateRepeatStructure, use Create in the tag, and a gratuitous homonym costs more than the convention buys.
4. schema_major() is unconditionally 2. Instrument's major-2 appends (sound_config, default_clef, default_staff_lines) are mandatory, not Option-hidden, so no lower-major layout for this payload exists. Put it in the existing | OperationKind::CreateStaff(_) | OperationKind::SetMetadata(_) => 2 arm (payload.rs:219). Do not copy the value-dependent arm shape used by CreateRegion/SetStaffLayout.
5. No accept-set change. max_supported_major(OperationEnvelopeBlock) is already 2 (bundle.rs:69) and stays 2. Do not touch epiphany-bundle. The raise to 3 belongs to G2 (SetTuningContext) and to nothing else.
6. Reduction follows create_staff exactly (reduce.rs:3794-3855): live + byte-identical value → NoOp{AlreadyApplied}; live + differing value → NoOp{PreconditionFailedUnderReduction{RecreateContentMismatch}}; tombstoned → NoOp{TargetTombstoned}; otherwise mint_container + Applied.
7. No DeleteInstrument. CreateStaff ships today with no DeleteStaff; the ruling states full CRUD is not automatically owed. Delete coverage is G3's design work.

The two cross-cutting items

These are the reason G1 is not merely "one more kind".

8. instrument_values must exist and be seeded. TypedObjectId::Instrument liveness is already seeded from the base (reduce.rs:1319-1321), but there is no value map, so re-carry idempotence against a base instrument has nothing to compare. Add instrument_values: BTreeMap<InstrumentId, Instrument> mirroring staff_values at every one of its sites: the two struct decls (:914, :1004), the init (:1282), the base seed (beside :1327), and the snapshot/restore pair (:7234, :7270). Missing the snapshot/restore pair is the silent failure here — it would surface only under undo/replay.
9. The identity cursor (ruling §3). From-empty reduction sets next_counter to 1 + max(counter) over ids authored by the reducing replica in the log, leaving the seed untouched when that replica authored none. This is the first time reduction writes identity at all — epiphany-ops has no .identity reference today. Note Score::identity is an authoring cursor reduction has never advanced; under from-empty it would otherwise sit at the seed while the log already holds that replica's ids at 0..N, so minting from a reduced score re-issues used counters. Nothing catches that: invariant 11 (core/src/invariants.rs:1746-1752) checks only the reserved replica, never the counter.
10. From-empty must reduce with a graph. Use reduce_operation_set_onto(&set, &Score::empty(identity)) (reduce.rs:617), never reduce_operation_set(&set) (:612). Graph-aware preconditions are skipped in the base-free mode by design — it has no universe to check against (reduce.rs:3721, :3824). A from-empty document through the base-free entry point silently loses referential enforcement. Document this at both entry points.

Touch points

Derived by enumerating every CreateStaff site. Twelve non-test surfaces — two of which the plan under-counted (v0.rs, migrate.rs):

#	File	Site (CreateStaff analogue)
1	core/src/codec.rs	canonical_value! — add Instrument (:3484)
2	ops/src/payload.rs	CreateInstrumentOp struct + CanonicalEncode (:1400, :1411)
3	ops/src/payload.rs	OperationKind variant (:177)
4	ops/src/payload.rs	schema_major() → 2 arm (:219)
5	ops/src/payload.rs	discriminant() → 31 (:280)
6	ops/src/payload.rs	tag() (:323) + encode dispatch (:367)
7	ops/src/payload.rs	operation_kind_tag_vocabulary! entry (:440) — compile-enforced
8	ops/src/envdecode.rs	discriminant-31 decode (:542) + tag→kind (:830)
9	ops/src/v0.rs	V0OperationKind variant (:96)
10	ops/src/migrate.rs	both directions (:171, :325)
11	ops/src/reduce.rs	dispatch (:2632) + create_instrument + pin 8's map
12	ops/src/textproj_kind.rs	production (:185) + parse (:470)
13	ops/src/fuzz.rs	generator arm (:214)
14	ops/src/vectors.rs	a decode vector for the new payload
15	spec/operation_catalog.tex	§CreateInstrument

The tag vocabulary macro (#7) is a single source of truth: the decoder, fuzz corpus, conformance vectors, and edit-barrier round-trip all read PAYLOAD_FREE, and a variant missing an entry fails to compile. It exists because Push 4a added TransposeInterval to a hand-written match and nothing else, and four hand-maintained lists stayed green while the decoder rejected its own encoding. OperationKind::discriminant() (#5) has no such guard — it is hand-written.

Tests + minimum mutations

Every test must be mutation-verified: re-introduce the bug it exists to catch and show it dies. A test that cannot see its own bug is not a test.

• (i1) the spine reaches a note. From Score::empty(identity), operations only — CreateInstrument → CreateStaff → CreateRegion → CreateStaffInstance → CreateVoice → InsertEvent — materializes a note-bearing Score. No fixture, no base. This is the packet's load-bearing test and the ruling's acceptance criterion 1. Mutation: drop the CreateInstrument envelope → CreateStaff must NoOp{TargetMissing} and no note appears.
• (i2) re-carry idempotence. The same CreateInstrument twice → AlreadyApplied, and the state is byte-identical. Mutation: make the second carry differ in one field → RecreateContentMismatch.
• (i3) re-carry against a base instrument — the pin-8 case. Reduce onto a base that already contains the instrument. Mutation: skip seeding instrument_values → the byte-identical re-carry is misreported as a mismatch.
• (i4) order independence. Two replicas applying a concurrent genesis-era set in opposite delivery orders converge to byte-identical MaterializedState (ruling acceptance criterion 2; the existing pattern is reduce.rs:10031). Mutation: perturb one op's reduction order.
• (i5) the identity cursor. Mint from a reduced-from-empty score and assert the id collides with nothing in the log. Mutation: leave next_counter at the seed → collision.
• (i6) base-free loses enforcement. Assert explicitly that reduce_operation_set (base-free) does not enforce the instrument precondition while reduce_operation_set_onto does. This test documents a designed asymmetry rather than guarding a bug — state that in its doc comment so a later reader does not "fix" it.
• (i7) minimal stamping. CreateInstrument.schema_major() == 2 unconditionally — including for an instrument whose optional fields are all None. Extend schema_majors_follow_the_minimal_stamping_rule (reduce.rs:10386). Mutation: make the arm value-dependent → dies.
• (i8) decode vector pinned to literal bytes, not round-trip. Round-trip locking cannot see a self-consistent encoder/decoder reorder — that is the 3b-i lesson, where a swap applied to both halves passed 1283 tests and 8/8 conformance.
• (i9) text-projection round-trip for the new kind, matching the existing per-kind coverage.

Blast radius

crates/epiphany-core/src/codec.rs (one canonical_value! line) and its DECISIONS.md; crates/epiphany-ops/src/{payload,envdecode,v0,migrate,reduce,textproj_kind,fuzz,vectors}.rs and its DECISIONS.md; spec/operation_catalog.tex (+ its rebuilt PDF — every other .tex commit carries one). Nothing else. No epiphany-bundle, no binary_format.tex, no editor-track crate, no golden re-blessing.

Gate (report actual output, never stale numbers)

cargo fmt --check; cargo clippy --workspace --all-targets at 0 warnings; cargo test --workspace at 0 failed; cargo test --doc at 0 failed; conformance 8/8; requirement_labels 6/6 with its three observed counts reported as seen (they were 212/282/282 at 439e1e2 and will move with the catalog section). Plus:

• max_supported_major(OperationEnvelopeBlock) is still 2 — assert it, and state it in the report.
• No crates/epiphany-editor-gui/goldens/*.png byte changes.

What I will verify independently before committing

Build to survive this. I re-run every mutation myself, and I check specifically: that #5's hand-written discriminant match and #7's macro entry agree; that pin 8's snapshot/restore pair (:7234/:7270) was not missed; that i1 fails for the stated reason rather than incidentally; that the accept-set really did not move; and that no claim in the report is copied forward from this contract rather than observed — the recurring failure mode on this project is a plausible claim propagating because nobody re-derived it.

Report

Files + summary, exact asserted values, every mutation with kill evidence, gate output verbatim, deviations flagged explicitly. If any pin here turns out to be wrong, say so rather than working around it silently.