proposal: add work surface type metadata to `class` directives

[aofei]

Background

Some classfile frameworks have two different type-level roles for the same work file kind:

• A work base class used for lowering and embedding
• A public semantic interface that downstream tools should use to interpret work files

spx is a typical example. Its work files are lowered through SpriteImpl, while downstream tooling and user-facing semantics are often better modeled in terms of Sprite.

The current classfile spec already provides metadata for:

• The project base class
• The work base class
• The optional work prototype type

It does not provide metadata for that public semantic interface.

As a result, downstream consumers such as language servers have to hardcode framework-specific mappings when the lowering carrier type and the user-facing semantic type are not the same.

Current behavior in XGo

In current classfile metadata:

• project declares the project base class
• class declares the work base class
• The optional final symbol of class declares the work prototype type
• -embed and -prefix= adjust project assembly and generated type naming

There is no metadata that says:

• What public semantic type a work file kind should be interpreted as
• Whether generated work class types are required to satisfy that public interface

This makes the classfile registry sufficient for lowering, but not sufficient for downstream semantic consumers.

Proposal

Extend class directives with an optional -surface=<ExportedName> flag.

Semantics:

• -surface= names the work surface type of the declared work file kind
• The named symbol must resolve to an exported interface type in the framework package of the containing project group
• For every generated work class type T of that work file kind, *T must implement the declared work surface type
• The work surface type is additional classfile metadata only

The work surface type must not affect:

• File classification
• Class type naming
• Field layout
• Method lowering
• Project Main assembly
• Synthesized helper methods
• Runtime behavior

If -surface= is absent, no work surface type is defined for that work file kind.

Why this belongs in the classfile spec

It describes the semantic shape of a work file kind itself. Because of that, it belongs in classfile metadata rather than in downstream consumer-specific logic.

Standardizing it in the classfile spec would let all consumers read the same meaning from framework metadata instead of re-encoding framework-specific knowledge out of band.

Non-goals

This proposal is not intended to:

• Replace the work base class
• Replace the work prototype type
• Change lowering semantics
• Change runtime behavior

Acceptance criteria

• class directives may declare -surface=<ExportedName>
• The classfile loader and metadata model preserve it
• The compiler validates that the named symbol is an exported interface type
• The compiler validates that *T implements the declared work surface type for every generated work class type T
• Frameworks that do not use -surface= keep existing behavior unchanged