feat(ir)!: identify operation groups and declare ID namespaces

[OmarAlJarrah]

Summary

Two gaps in how the IR names things, closed together because both ride the same schema generation.

Operation groups had no identity. emitter-design.md §3.4 keys sub-clients by a GroupKey "derived from OperationGroup identity", but ir.OperationGroup serialized as a name, docs and operations. A sub-client could therefore be keyed only by its name, which §15 rules out for anything that has to survive a rename, and which two groups can share:

tags: [{name: default}]
paths:
  /tagged:   {get: {operationId: tagged,   tags: [default], responses: {"200": {description: ok}}}}
  /untagged: {get: {operationId: untagged,                   responses: {"200": {description: ok}}}}

This compiled to a group named {source: default} and a fallback group named {hint: default}: two groups that render the same, told apart only by the naming channel.

A lost separator in an ID was invisible for most classes. An ID is kind/namespace/path, and only its first two separators say where the namespace ends, so a path glued onto its namespace is a well-formed ID in a namespace nobody meant (op/openapipaths/~1pets/get). irverify could see that only where a node records the pointer its ID was derived from. An operation, a service and a group do not, so it verified clean.

Closes #673. Closes #802.

Change

Group identity

• ir.GroupID is a new ID class (kind prefix g), and OperationGroup gains ID. It is unique across the document, nested groups and every service included.

• The OpenAPI compiler mints it from the rule that formed the group, in a namespace named for the rule:

  Group	ID
  first tag of the operation	g/tags/<tag name>
  first path segment (path-prefix strategy)	g/path-prefix/<segment>
  untagged operations	g/default
  webhook operations	g/webhooks

  The tag name and segment are RFC 6901 escaped, so a/b and a~1b stay distinct. The accumulator that gathers operations into groups keys by this ID and stamps it, so a group's key and its identity are one value.

• emitter-design.md uses ir.GroupID where it had GroupKey, with the two optional references (GroupPlan.Parent, ShapeHint.Remount) spelled as nil pointers, as §3.1 requires of a reference that may be omitted.

Declared namespaces

• Document gains IDSpaces: the namespaces its IDs live in, keyed by kind prefix, stated by the producer as it stamps IRVersion.
• irverify reports an ID whose namespace the document does not declare for its kind (ir/id-space-undeclared), whatever the class and whether or not its node records a pointer. The primitive namespace is ir's and needs no entry. A document declaring nothing while carrying IDs is reported once (ir/id-spaces-absent), as a missing irVersion is. The declaration must itself be usable: keyed by real kinds, a kind with no namespace left out, each list sorted by the byte order of its UTF-8 spelling and without repeats, no namespace empty or carrying the separator (ir/id-spaces-unknown-kind, ir/id-spaces-not-canonical, ir/id-space-invalid).
• It is a vocabulary and not a usage report, so a namespace no ID uses is not an error in a document. The compiler's own test holds its list to what its corpus uses, in both directions.
• compile.Namespaces builds the declaration from the Space constants a compiler already derives IDs with. The OpenAPI compiler names its namespaces once and stamps them beside IRVersion.
• The namespaces a document's IDs use are derived in one test helper, irtest.SpacesUsed, which irverify's tests and the compiler's vocabulary test share.
• The check reads the declarations irverify already collects, so it adds no walk.

The rest of the verifier

• Operation, service, group and property IDs are now held to the ID grammar (well-formed). Properties are also held to agreement with their recorded pointer, as types and security schemes already were. Operations are not, because their provenance records where the body is declared and the ID where it is mounted, and the two differ for an operation reached through a $ref'd path item (openapi: referenced non-schema components hoist once per use site under fabricated pointers #107); holding them to it fails component-reuse.yaml and operation_id_remounts.yaml.
• All of that lives in checkDeclaredIDs, which now owns a node's own ID in one place (present, well-formed, in agreement), with one table mapping every ID class to its prefix.
• The empty-reference classification of a node's own ID (idElsewhere) had a case for Operation.ID only. Service.ID and Property.ID had no guard at all, and OperationGroup.ID had one only because shared fixtures happened to carry an ID-less group. Each now has its own case.
• Comments that listed the classes with no registry map (operations and services) include groups.

The architecture rule

A compile.Space may only be written as a string literal, because a namespace assembled from data can carry the path in with it. The rule also resolves each file's own imports, so an aliased import cannot hide a violation and an unrelated package called compile cannot cause one. It is syntactic, so two constants glued together are not seen by it; the declaration sees that as an undeclared namespace.

Docs

ir-design.md records the Document member, the g prefix, the derivation rule, what irverify holds IDs to and why, and the 0.7.0 history entry. architecture.md lists the new enforced rule.

Design choices

An ID, not a "name path". A name-derived key moves when a group is renamed, and ShapeHint.Remount is authored alongside the SDK and keyed by IR ID, so it would break on exactly the edit it exists to survive. Names stay presentation (invariant 3).

Not derived from the Tag Object. A Tag Object is metadata about a name, not the group: an operation may use a tag no Tag Object declares, a document may declare the same tag twice, and /tags/N shifts when the list is reordered. The grouping rule mints the group, so each rule gets a namespace of its own, which also keeps g/default and g/webhooks from colliding with a tag called default or webhooks. Name-keyed IDs extend without change to nested groups, such as the 3.2 tag parent chains in #613 and the dotted group keys in #582.

A per-kind declaration, required like irVersion. A flat set could not tell a namespace some other kind declares from one this kind may use. Making the declaration optional would let a producer that forgot opt out silently, the failure the version stamp's policy exists to avoid.

Now, not later. This PR already moves the schema to 0.7.0, so the declaration costs no further generation. Adding it afterwards would cost every consumer another break for a hole that is cheap to close here.

Alternatives rejected (#802 has the full list): recording the derivation pointer on Provenance (format-specific, widens every Provenance, and does nothing for services or groups); an unambiguous delimiter between namespace and path (rewrites every ID in every document); a prefix heuristic (false positives).

Out of scope, stated in groupFor

The issue also asks that the fallback group's name not collide with a declared one. That part is not done: the fallback keeps the hint default. Any hint can equal some tag's name, so renaming it only moves the collision. Emitters resolve name collisions by ID (emitter-design.md §4.12), which this change makes possible for groups. Telling a document author that two groups share a name is #647.

What catches a lost separator

Defect	Caught by
A group, operation or other ID built by converting a string	the architecture test
A namespace assembled from data (compile.Space("tags"+name))	the architecture test, and the declaration
Two constants glued together	the declaration
A producer outside this repository	the declaration
A property or type ID whose path disagrees with its pointer	agreement

Planted before this change, the second and third both passed the architecture test, irverify and every harness oracle. Both now fail TestVerify_Corpus and the other corpus oracles.

Test plan

• On the branch head with main (build: move to Go 1.27.2, golangci-lint v2.14.0, openapi v1.25.5 #804) merged in: gofmt, go vet, golangci-lint v2.14.0 and the whole suite, every package at 100% statement coverage. The race-detector coverage run, the fuzz search and the bench smoke run are the CI gate's.
• The harness over the whole testdata tree gives every spec the same outcome as main, the deliberately broken negative fixtures included. The only difference is the new fixture.
• A conformance case (group-identity) writes the group IDs out for every rule, including a declared tag default, a tag webhooks, an undeclared tag, and a/b against a~1b. Unit tests cover the path-prefix strategy, a tag declared twice, a two-order diff of one document with paths and tags reversed, and an exhaustive check that tag and path-prefix IDs never collide over every string of up to four characters from the alphabet RFC 6901 escapes.
• The namespace check is tried on all six ID classes: a lost separator, a namespace declared for another kind only, the primitive namespace, a forgotten declaration (reported once), a malformed ID (not reported twice), a declared-but-unused namespace (clean), each way a declaration can be unusable (a kind with an empty or null list included), and the order a list is sorted in, with a pair of namespaces that UTF-8 and UTF-16 order differently.
• The compiler's vocabulary is held to the namespaces the corpus uses, in both directions and under both grouping strategies; a path-prefix namespace is invisible to the default-strategy tests.
• Every defect below was planted, compiled, and turned at least one named test red before being reverted. Group IDs: escaping / but not ~, the fallback group taking a tag's ID, the accumulator not stamping the ID, path-prefix groups using the tag rule, path-prefix segments left unescaped, the webhook group taking a tag's ID, IDs derived from first-seen position. Verifier: swapped prefixes, a class dropped from the table, empty IDs not skipped, the pointer never read, operations held to agreement (which fails the real corpus), properties not held to it, each own-ID classification wrong. Namespace check: one flat set instead of one per kind, the primitive namespace not exempt, the primitive exemption widened beyond types, the forgotten declaration reported per ID, and the check not wired in. Declaration: an unknown kind also judged as a kind, a kind with no namespace not reported, a UTF-16 comparison in place of byte order, and a class dropped from, or sharing a kind in, the prefix table. Vocabulary: a declared namespace nothing uses, a used one undeclared, the path-prefix one dropped, the stamp removed. Shared helper: the primitive namespace not left out, repeats not removed, no sort, no kind filter, malformed IDs not skipped. Architecture rule: each clause of the namespace rule and of the import resolution.
• Pre-existing goldens change only in the irVersion line, the added group id lines and the new idSpaces block, and regenerating them changes nothing further. One golden is new, for group-identity.
• Cost: Verify makes about a thousand more allocations than on main (3,160 to 4,235 on enum-string.yaml, a small conformance spec; 38,511 to 39,600 on param-style-matrix.yaml, the largest committed one), because every reflection walk visits the new member. It is a per-document cost that does not follow the number of IDs.

Breaking

IRVersion moves to 0.7.0. Every group gains an id key and every document gains idSpaces, so a consumer pinned to 0.6.0 must be rebuilt against this generation; there is no migration path (ir-design.md §2.1).

#734 and #735 also set IRVersion to 0.7.0 from the same base. Whichever of the three merges later must merge main in, take the next number, re-anchor the three version literals in ir/document_test.go, add its history entry under the new number, and regenerate the goldens.