[Swimburger]

Implements RFC 0001 for FORGE-1: a metadata resolution layer between the vendor extensions in a spec and the engine.

What changes

• A native x-forge-* vocabulary (src/metadata/), listed in full below. Every native key begins with x-forge-; x-sensitive keeps working as a deprecated name of x-forge-sensitive.
• A compatibility layer (src/compat/, behind the default-on compat feature): the only code that knows x-fern-* and x-stainless-skip. It maps them onto the native keys, and is designed to be deleted as a whole.
• Native keys win. When a spec writes both, the native value is used whatever the key order; only the winning value is validated, and errors name the key the spec actually wrote.
• x-forge-group-name takes a dotted string ("accounts.members") or an array, read exactly as groups always have been. The dotted string is Cloudflare's convention rather than Fern's; FORGE-12 tracks moving specs off it and then making the Fern adapter match Fern.
• A boundary test (tests/boundary.rs) fails if x-fern or x-stainless appears in src/, tests/ or packages/forge/ outside the compatibility layer, doc comments included.

The native vocabulary

All decided native names, with the vendor key the compatibility layer reads in its place:

Native key	On	Value	Compat equivalent
x-forge-method-name	operation, alias	string	x-fern-sdk-method-name
x-forge-group-name	operation, alias	dotted string ("accounts.members") or array of strings, top level first	x-fern-sdk-group-name
x-forge-skip	operation, alias (no method) · property schema (no field)	boolean	x-fern-ignore (operation) · x-stainless-skip (property; a list of targets counts as false)
x-forge-availability	operation, alias	alpha | beta | preview | generally-available | deprecated	x-fern-availability
x-forge-model-name	schema in components.schemas / $defs	string	x-fern-type-name
x-forge-property-name	property schema	string	x-fern-property-name
x-forge-parameter-name	parameter	string	x-fern-parameter-name
x-forge-sensitive	schema	boolean	none (replaces x-sensitive)
x-sensitive	schema	boolean	none: deprecated native name of x-forge-sensitive, read only where that is not written

Existing native keys, unchanged: x-forge-hidden, x-forge-require-confirmation, x-forge-aliases (operation) and x-forge-commands (document root).

Not read, and unchanged: x-fern-enum, x-fern-audiences, x-stability and the other vendor keys without a Forge primitive (FORGE-5). Later renames (group → namespace, the availability word) are FORGE-3.

Compatibility

Not breaking. Existing specs build the same Forge, the WIT changes only in doc comments (forge:plugin@0.3.0 is unchanged), and generated output is byte-identical. Built without compat, the native keys behave the same, and vendor keys become ordinary extensions passed to plugins.

Verification

Checked against the unmodified engine on the released aggregate (openapi.forge.json, 27.6 MB), as detailed in the RFC's Verification section:

• the original Fern-keyed parse suite passed before any fixture was migrated;
• forge --target ts writes the same 3,381 files, byte for byte, and the full model dump is identical;
• native vs WASM output and dumps are identical; wit_is_current holds;
• cargo test passes with compat on and, run locally, with compat off (CI compiles but deliberately does not test the compat-off build; see the RFC); clippy is clean in the library-only, compat-off and all-features configurations;
• parse time is within about 1% of main (paired runs of the parse bench), with the same peak memory and allocation count.

Reviewing

The RFC is the place to start, then src/metadata/mod.rs, src/compat/ and src/link/resolve.rs. Most of the diff under tests/parse/ is fixtures moving to native keys.

Open questions for reviewers, also in the RFC:

• leaving x-fern-audiences unread, which differs from the ticket text;
• the empty group path: "" and [] should mean the root, but the model has no root methods yet (Known gaps).

Follow-ups: FORGE-3 (the breaking vocabulary renames), FORGE-4 (the versioning RFC), FORGE-5 (a Forge CI lint for vendor keys forge doesn't read) and FORGE-12.

[Swimburger]

1. I think we should rename x-forge-group to x-forge-group-name for now, keep it more consistent with Fern until we rename it to x-forge-namespace.
2. Are we unnecessarily slowing down CI at all?

[Swimburger]

1. Done in 471acdf: x-forge-group-name, which also keeps it apart from the legacy x-forge-group-info. The RFC notes FORGE-3 expects to rename it to x-forge-namespace.
2. No meaningful slowdown. The two new test binaries (boundary, compat) add a few seconds of compile and link, and their tests run in about 0.02 s. Testing the compat-off build is deliberately left out of CI to avoid a second full compile; clippy still compiles it. That is documented in the RFC (Enforcement).

[Swimburger]

@Swimburger Double check that downstream dependencies still receive raw extensions, cf CLI seems to depend on x-fern-... directly.
Edit: verified

[dimitropoulos]

love it! one thing I'd love to keep up-to-date is the AGENTS.md file for this work. I'd love to keep it clear that the intention is that any compat flags are intended to be sectioned off into their own little area of the codebase

[srikrsna]

I would like the compatibility layer to be exposed as a separate command so that the spec we produce itself can be transformed. It will also reduce the complexity we have introduced to account for metadata resolution. That way the core will always parse just the forge extensions. And compat can truly be a separate layer altogether.