Skip to content

docs/emitter-design: scope the first emitter to the IR a compiler produces, and degrade the rest with a diagnostic #961

Closed

Description

@OmarAlJarrah

Problem

A reflection walk over every compiled document found that much of the IR's declared surface never occurs in practice. The walk covered the 1,838 OpenAPI 3.x corpus specs plus the golden spec, the Cloudflare API schema (cloudflare/api-schemas openapi.json at 911ad78), all compiled at c387e25c. Of the IR's surface:

  • 245 of 528 exported fields (46%) are never non-zero;
  • 27 of 89 structs are never instantiated: Any, Availability, Channel, CtorValue, External, LongRunning, Message, MessageBinding, Pagination, PropPath, RPCBinding, ResourceInfo and 15 more;
  • 41 of 110 enum constants never occur. These include TypeKind any and external, ValueKind ref, ctor and symbol, all six PageStrategy values, and StreamingMode bidi.

For 195 of those fields, OpenAPI has no construct at all. Another 30 come only from inference or promotion policy that is not enabled.

emitter-design still asks the first emitter to lower all of it. §4.2 says every one of the eleven TypeKinds has a dispatch (test T-1). §9 asks for an emit path or a diagnosed degrade for every row. About 76 of the never-set fields sit under a §4.2 step or a §9 row: External; channels, messages and replies; Pagination; LongRunning; OneWay; value refs, constructors and symbols; Presence; the discriminator's Index, Default and Envelope; Model.Implements, Abstract and Positional; Enum.Flags and FallbackMember; List.Encoding; StreamDetail's fields.

With no producer, a lowering for these can be tested only against hand-built IR, and its wire behaviour against nothing real. Writing them for three targets at once (#901) multiplies that cost.

Direction

A proposal:

  • M3a to M3c lower what a compiler produces: the measured set, re-measured as compilers land.
  • Every other kind or fact dispatches to a coded emitters/<target>/unsupported-… diagnostic. This is T-7's degrade, not a silent fallback, and it keeps T-1's dispatch completeness.
  • A construct gains a real lowering in the change where a compiler first produces it, tested against that compiler's output.

Done when §14 lists the M3 scope by IR fact, together with the command that re-derives it.

Out of scope

Removing anything from the IR. The surface stays as designed (invariant 9); this issue concerns only what the first emitter implements.

Related: #901, #707

Priority: P2, rule 6 (indirect impact: emitter effort, not what the golden spec emits). jq '[.. | objects | select(has("longRunning") or has("pagination") or has("availability") or has("presence"))] | length' golden.ir.json → 0 (spec @911ad78, morphic @c387e25c).

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:P2Rarer spec shapes, or an IR decision to settle before the emittertype:docsDocumentation only

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions