feat(ir)!: give parameters, groups and enum members stable IDs

[fuad-daoud]

Summary

Closes #596. Closes #673. Part of #255 (item 1, enum-member identity; items 2–4 have no code yet, and their decisions are recorded on #255).

Three named things in the IR had no stable identity, so anything that needed to point at one could only use its name. Names are presentation (invariant 3), and here they also collide. This gives each of the three a synthetic ID and moves every reference onto it. The three changes ship together because each changes the IR's shape, and together they make one version bump: 0.6.0 → 0.7.0.

Parameters: ParamID (#596)

OpenAPI identifies a parameter by (name, in), so id in the query and id in the path are both legal on one operation. The IR referenced parameters by name, so their two bindings could not say which one they bound.

• Parameter.ID is param/<space>/<operation mount pointer>/parameters/<name>/<in>.
  • It is scoped per operation. A path-item parameter is copied into every operation on the item, and a $ref'd path item can be mounted at several paths, so the mount pointer is what keeps each copy distinct.
  • It uses no list index, so reordering parameters leaves every ID unchanged.
• References. HTTPParamBinding.Param, Pagination.InputCursor/InputLimit (ParamPath.Param) and Idempotency.TokenParam now hold a ParamID.
• Validation. pass/validate rejects any of them naming a parameter its own operation does not declare. An ID nobody declares stays with the existing dangling-reference check, so it is reported once.

Operation groups: GroupID (#673)

emitter-design §3.4 derived GroupKey from a group identity that did not exist. A declared tag default and the fallback group for untagged operations both came out as default.

• Declared tags get g/openapi/tags/<escaped tag name>, flat, with no parent chain.
  • The tag name is the key operations reference a tag by, the role a component key plays.
  • A position-derived #/tags/<i> was rejected. It would silently rebind to a different tag on reorder (ir: an ID derived from an array index names a different entity after the array changes #678), and an undeclared tag has no position at all.
  • The escaping is injective: ~→~0, /→~1, empty→~.
  • ir-design §3.1 states what the ID promises across revisions (docs: several design documents say IDs survive renames, which pointer-derived IDs don't #677).
• Synthesized groups (the fallback, webhooks, path-prefix) get IDs under g/synth/openapi/…, so they can never equal a declared group's ID.
• Synthesized names step aside when a declared tag already uses the same canonical words. So the fallback becomes default_2 beside a tag default, and the same rule applies to the webhook group.
• OperationGroup also gains Provenance.
• GroupKey is defined in emitter-design §3.4 as carrying the group's ID.
• 3.2 tag nesting is openapi: OpenAPI 3.2 tag parent and kind are dropped #613 and out of scope. The flat ID is chosen so nesting can land later without renaming any group.

Enum members: EnumMemberID (#255, item 1)

emitter-design §4.12 resolves naming collisions in a table keyed by IR ID, and the commonest collision, enum members canonicalizing to the same words, had no ID to key it.

• Scope and source. EnumMember.ID is scoped to its enum and derived from the member's wire value, never its position, so reordering or inserting members changes no existing ID.
• Encoding. The value encoding is kind-tagged, so 1 and "1" differ.
• Repeated values. Both members are kept. The second takes a #2 suffix, and the compiler warns openapi/duplicate-enum-value.
• Docs. §4.12 names EnumMember.ID as the collision-resolver key.

Checks

• pass/validate reports duplicate group IDs and duplicate member IDs within one enum.
• irverify reaches all three classes. Empty and duplicate IDs are found automatically through its reflection-derived declarations. The grammar and scope checks for groups and members are hand-written.

Breaking

• IRVersion is 0.7.0. CompatibleVersion accepts only an exact match, so a stored 0.6.0 document is refused.
• HTTPParamBinding.Param, ParamPath.Param and Idempotency.TokenParam change from a parameter name to a ParamID.
• Parameter, OperationGroup and EnumMember gain a required id. OperationGroup also gains provenance.
• Goldens are regenerated: 89 files under testdata/.

Test plan

• make gate passes on the branch tip after merging main (build: move to Go 1.27.2, golangci-lint v2.14.0, openapi v1.25.5 #804: Go 1.27.2, golangci-lint v2.14.0), including 100% statement coverage, lint, fuzz and bench smoke. The statement count fell from 10000 to 9352 with the merge. build: move to Go 1.27.2, golangci-lint v2.14.0, openapi v1.25.5 #804 changes no Go code; Go 1.27.2 counts fewer statements per coverage block, with the same block set (checked on compilers/openapi/internal/schema: 1005 blocks under both, 1535 → 1453 statements). Run with GOFLAGS=-p=4, because two wall-clock-budget tests (TestDetectCycles_MergeChainPastBoundStaysFastAndWarns, TestResolverOracle_RefusalMatchesResolverBehavior) overrun under the full parallel race run on a loaded laptop. They do the same on main; see test: replace the merge-walk timing ratio with a deterministic bound #746.

• Every new test was checked by planting the defect it guards against and watching it go red, then reverting. For example:

  • an index-derived ID (params, groups, members);
  • in dropped from the param ID;
  • a fixed default hint;
  • an unsuffixed repeated enum value;
  • each new validate and irverify check removed.

• Two-order tests: parameter declaration order, tag and path order, and enum member order each leave every ID unchanged.

• Goldens are not a no-op regeneration. Deleting a parameter, a tag, or an enum member from a source spec reddens the suite without -update.

• Probes with morphic compile/validate:

  • the ir: parameters are bound by name, so same-named parameters in different locations are ambiguous #596 operation gets two distinct IDs, each binding naming one of them;
  • a $ref'd path item mounted at /a/{id} and /b/{id} with get and delete gets four distinct param IDs;
  • the ir: operation groups have no identity, though GroupKey is derived from it #673 document gives g/openapi/tags/default and g/synth/openapi/default (hint default_2);
  • [a-b, a_b, "A B", "a/b", "a#b", a-b] gives six distinct member IDs and one duplicate warning.

  All of them validate with exit 0.

🤖 Generated with Claude Code

https://claude.ai/code/session_016MQFAkYBVaqgSxGwe9ZJSn

[fuad-daoud]

Closing in favour of a replacement built on current main. #801 landed operation-group identity (closing #673) and declared ID namespaces (Document.IDSpaces) while this was in review, so this branch now conflicts in 105 files and carries a second, incompatible group-ID scheme.

The replacement keeps what #801 does not cover:

• parameter IDs (ir: parameters are bound by name, so same-named parameters in different locations are ambiguous #596);
• enum-member IDs (docs/emitter-design: four gaps the first target will hit #255 item 1).

Both new ID kinds will be registered in #801's namespace declaration and held to its verifier rules. The IR version moves to 0.8.0, since 0.7.0 is already on main. The fallback-group name collision from #673 goes in a separate small PR.

[fuad-daoud]

Replaced by #811.