@postman/sdk-config 0.3.4 → 0.4.0

package/src/sdk-config-ir/v1/README.md

@@ -54,6 +54,7 @@ messages. Valid IR requests route only to the IR bridge and never fall through t
 - Package and publication identity belongs in `package`; publication mechanics belong in
   `output.publish`.
 - Shared client behavior belongs in `client`; shared generator behavior belongs in `generation`.
+- Request replay behavior belongs in the top-level `replay` block.
 - `generation.language` contains only behavior that remains language-specific after normalization.
 - A simple on/off option is a boolean. A feature with additional settings is an object containing a
   required `enabled` boolean so settings can be added without changing its shape.
@@ -63,7 +64,7 @@ messages. Valid IR requests route only to the IR bridge and never fall through t
 Examples of the boolean rule:
 
 - Boolean: `generation.webSockets`, `generation.multipleResponses`.
-- Configurable feature: `client.retry`, `client.tokenRefresh`, `docs.snippets`,
+- Configurable feature: `replay`, `client.retry`, `client.tokenRefresh`, `docs.snippets`,
   `generation.analytics`, `generation.hooks`, `generation.streams`, `generation.wireTests`, and
   `generation.unitTests`.
 
@@ -142,6 +143,7 @@ For Python Fern configs, `skip_validation` is read from the nested `pydantic_con
 | `license`, `authors`, `developers`, `homepage`      | `package` and `output.github.license`                             | Manifest metadata and GitHub-specific repository license settings.                            |
 | TypeScript package privacy / JSR publication        | `output.publish.isPackagePrivate` / `output.publish.publishToJsr` | NPM-specific publication options.                                                             |
 | registry workflow, credential, and env-var settings | `output.publish`                                                  | Per-registry workflow toggles, credential values/refs/env vars, and trusted publishing flags. |
+| request replay                                      | `replay`                                                          | `enabled` is explicit when the object is present.                                             |
 | `documentation.url`                                 | `docs.referenceBaseUrl`                                           | Base URL for generated reference-file links.                                                  |
 | `documentation.snippets`                            | `docs.snippets`                                                   | `enabled` is explicit when the object is present.                                             |
 | `docs[]`                                            | `docs`                                                            | Legacy API/snippet selections are lowered to typed documentation settings.                    |
@@ -274,22 +276,28 @@ normalized contract.
 These settings remain under `source.apiImportSettings` because they affect spec conversion rather
 than generated-language presentation.
 
-| Fern setting                              | Normalized field                     |                       Observed projects |
-| ----------------------------------------- | ------------------------------------ | --------------------------------------: |
-| `respect-nullable-schemas`                | `respectNullableSchemas`             |                                      10 |
-| `title-as-schema-name`                    | `titleAsSchemaName`                  |                                      16 |
-| `ignore-tags`                             | `ignoreTags`                         | Not in the project snapshot; see below. |
-| `disambiguate-request-names`              | `disambiguateRequestNames`           | Not in the project snapshot; see below. |
-| `coerce-enums-to-literals`                | `coerceEnumsToLiterals`              |                                      14 |
-| `idiomatic-request-names`                 | `idiomaticRequestNames`              |                                      12 |
-| `wrap-references-to-nullable-in-optional` | `wrapReferencesToNullableInOptional` |                                       9 |
-| `coerce-optional-schemas-to-nullable`     | `coerceOptionalSchemasToNullable`    |                                       9 |
-| `object-query-parameters`                 | `objectQueryParameters`              |                                       9 |
-| `only-include-referenced-schemas`         | `onlyIncludeReferencedSchemas`       |                                       4 |
-| `group-multi-api-environments`            | `groupMultiApiEnvironments`          |                                       2 |
-| `path-parameter-order`                    | `pathParameterOrder`                 |                                       2 |
-| `type-dates-as-strings`                   | `typeDatesAsStrings`                 |                                      12 |
-| `default-integer-format`                  | `defaultIntegerFormat`               |           Importer defaults to `int32`. |
+| Fern setting                                                | Normalized field                     |                       Observed projects |
+| ----------------------------------------------------------- | ------------------------------------ | --------------------------------------: |
+| `respect-nullable-schemas`                                  | `respectNullableSchemas`             |                                      10 |
+| `title-as-schema-name`                                      | `titleAsSchemaName`                  |                                      16 |
+| `ignore-tags`                                               | `ignoreTags`                         | Not in the project snapshot; see below. |
+| `disambiguate-request-names`                                | `disambiguateRequestNames`           | Not in the project snapshot; see below. |
+| `respect-readonly-schemas`                                  | `respectReadonlySchemas`             | Not in the project snapshot; see below. |
+| `unions: v1`, `prefer-undiscriminated-unions-with-literals` | `discriminatedUnionV2`               | Not in the project snapshot; see below. |
+| `prefer-undiscriminated-unions-with-literals`               | `undiscriminatedUnionsWithLiterals`  | Not in the project snapshot; see below. |
+| `inline-all-of-schemas`                                     | `inlineAllOfSchemas`                 | Not in the project snapshot; see below. |
+| `resolve-schema-collisions`                                 | `resolveSchemaCollisions`            | Not in the project snapshot; see below. |
+| `message-naming`                                            | `asyncApiMessageNaming`              | Not in the project snapshot; see below. |
+| `coerce-enums-to-literals`                                  | `coerceEnumsToLiterals`              |                                      14 |
+| `idiomatic-request-names`                                   | `idiomaticRequestNames`              |                                      12 |
+| `wrap-references-to-nullable-in-optional`                   | `wrapReferencesToNullableInOptional` |                                       9 |
+| `coerce-optional-schemas-to-nullable`                       | `coerceOptionalSchemasToNullable`    |                                       9 |
+| `object-query-parameters`                                   | `objectQueryParameters`              |                                       9 |
+| `only-include-referenced-schemas`                           | `onlyIncludeReferencedSchemas`       |                                       4 |
+| `group-multi-api-environments`                              | `groupMultiApiEnvironments`          |                                       2 |
+| `path-parameter-order`                                      | `pathParameterOrder`                 |                                       2 |
+| `type-dates-as-strings`                                     | `typeDatesAsStrings`                 |                                      12 |
+| `default-integer-format`                                    | `defaultIntegerFormat`               |           Importer defaults to `int32`. |
 
 `ignoreTags` and `disambiguateRequestNames` postdate the project snapshot. Twilio declares both
 across its namespaced API specs. They stay undefaulted so omission remains distinguishable from an
@@ -298,23 +306,44 @@ of authored tags, not generation-time service-name inference; `disambiguateReque
 request/schema collisions, not idiomatic request naming. Producers and generators must map and
 honour these fields before they change generated output.
 
+`respectReadonlySchemas` and `discriminatedUnionV2` also postdate the snapshot. The 2026-07-17 audit
+read declared project configuration, which is why the first pass recorded no use: both are reached
+through effective-setting resolution rather than a literal key in `generators.yml`. Auth0 declares
+`respect-readonly-schemas` directly, but `discriminatedUnionV2` has two declared spellings that
+resolve to it — `prefer-undiscriminated-unions-with-literals` and `unions: v1` — so a config can be
+refused for a key that appears nowhere in it. The two spellings are not interchangeable, which is
+why `undiscriminatedUnionsWithLiterals` is a separate field rather than an alias: `unions: v1` sets
+only `discriminatedUnionV2`, while `prefer-undiscriminated-unions-with-literals` sets both. A
+contract carrying one of the pair cannot reproduce a config that set the other. All three stay
+undefaulted for the same reason as the
+fields above: `respectReadonlySchemas` changes which properties an imported schema exposes, and
+`discriminatedUnionV2` changes how union variants are converted, so an absent value must leave an
+existing SDK's shapes alone rather than assert one.
+
+`inlineAllOfSchemas`, `resolveSchemaCollisions`, and `asyncApiMessageNaming` complete the retained
+import settings with observed customer use. Each is refused today whenever it differs from the
+importer default, which blocks the declaring customer from a post-cutover generator version.
+`asyncApiMessageNaming` is the only enum of the three, and `v2` is its sole non-default value. It
+names AsyncAPI messages, but the importer resolves it as part of one shared settings object, so a
+project's OpenAPI specs carry it too and are refused for it.
+
 ## Fern language-specific migration map
 
 Only options that remain language-specific stay in `generation.language`.
 
-| Language    | Fern fields retained in language config                                                                                                                                                                      | Shared mappings lifted out                                                                                                               |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| TypeScript  | `packageManager` (1), `testFramework` (2), `namespaceExportName`, `allowCustomFetcher` (13), branded aliases (1), legacy exports (1), `useBigInt`, and positive `serdeLayer` from `noSerdeLayer` (8)         | Namespace, validation, inline types, dependencies, wire tests, streams, WebSockets, pager/client names                                   |
-| Python      | Python/Pydantic versions, client filenames (13), Pydantic compatibility, frozen models (1), required optionals (2), union naming (1), field aliases (3), always-initialize optionals, TypedDict requests (3) | Package/module names, enum form, extra fields, response validation, request style, dependencies, timeout, layout, wire tests, WebSockets |
-| Java/Kotlin | Package layout (3), local dates (2), optional-nullable collapse (2), Gradle settings (7), and JVM async-client style                                                                                         | Maven identity, namespace, names, forward-compatible enums, inline properties, dependencies, pager, wire tests                           |
-| Go          | Legacy complex models, union version (3), legacy client options (1), and the fern root-client constructor name                                                                                               | Module/package identity, client name, environments, smart casing, inline properties, pager, wire tests                                   |
-| C#          | Optional wrapper, simplified dictionaries (1), explicit namespaces (7), core namespace behavior (1), exception handler (5), and the experimental explicit-nullable-optional switch                           | NuGet identity, namespace, class/error names, pager, wire tests                                                                          |
-| PHP         | Property access (2) and generated client interfaces (1)                                                                                                                                                      | Composer identity, namespace, client/pager names, request style, dependencies, wire tests                                                |
-| Ruby        | Require paths (2)                                                                                                                                                                                            | Gem identity, client name, dependencies, pager, wire tests                                                                               |
-| Rust        | Datetime representation, initialism casing, and Cargo features/default-features                                                                                                                              | Crate identity, client name, and package metadata use shared fields.                                                                     |
-| Swift       | Module name and the nullable-as-optional collapse                                                                                                                                                            | Client, environment and error naming use shared fields.                                                                                  |
-| CLI         | Pagination parameter names and the `skills` boolean                                                                                                                                                          | Go module and package identity use `package`.                                                                                            |
-| MCP         | Server identity, availability exclusions, tool filters and named toolsets, plus the TypeScript options                                                                                                       | npm package identity, client and serialization behavior                                                                                  |
+| Language    | Fern fields retained in language config                                                                                                                                                              | Shared mappings lifted out                                                                                                               |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| TypeScript  | `packageManager` (1), `testFramework` (2), `namespaceExportName`, `allowCustomFetcher` (13), branded aliases (1), legacy exports (1), `useBigInt`, and positive `serdeLayer` from `noSerdeLayer` (8) | Namespace, validation, inline types, dependencies, wire tests, streams, WebSockets, pager/client names                                   |
+| Python      | Python/Pydantic versions, client filenames, model switches, TypedDict requests, redirect/chunk/recursion compatibility, and package extras                                                           | Package/module names, enum form, extra fields, response validation, request style, dependencies, timeout, layout, wire tests, WebSockets |
+| Java/Kotlin | Package layout (3), local dates (2), optional-nullable collapse (2), Gradle settings (7), and JVM async-client style                                                                                 | Maven identity, namespace, names, forward-compatible enums, inline properties, dependencies, pager, wire tests                           |
+| Go          | Legacy complex models, union version (3), legacy client options (1), and the fern root-client constructor name                                                                                       | Module/package identity, client name, environments, smart casing, inline properties, pager, wire tests                                   |
+| C#          | Optional wrapper, simplified dictionaries (1), explicit namespaces (7), core namespace behavior (1), exception handler (5), and the experimental explicit-nullable-optional switch                   | NuGet identity, namespace, class/error names, pager, wire tests                                                                          |
+| PHP         | Property access (2) and generated client interfaces (1)                                                                                                                                              | Composer identity, namespace, client/pager names, request style, dependencies, wire tests                                                |
+| Ruby        | Require paths (2)                                                                                                                                                                                    | Gem identity, client name, dependencies, pager, wire tests                                                                               |
+| Rust        | Datetime representation, initialism casing, and Cargo features/default-features                                                                                                                      | Crate identity, client name, and package metadata use shared fields.                                                                     |
+| Swift       | Module name and the nullable-as-optional collapse                                                                                                                                                    | Client, environment and error naming use shared fields.                                                                                  |
+| CLI         | Pagination parameter names and the `skills` boolean                                                                                                                                                  | Go module and package identity use `package`.                                                                                            |
+| MCP         | Server identity, availability exclusions, tool filters and named toolsets, plus the TypeScript options                                                                                               | npm package identity, client and serialization behavior                                                                                  |
 
 ## Removed and deferred legacy configuration
 
@@ -327,16 +356,14 @@ the migration.
 - Common Fern generation: include/omit platform-header overrides. Output-profile defaults own this
   compatibility behavior instead of a second permanent switch.
 - Source import: optional-additional-properties defaults, environment grouping strategies,
-  discriminant removal, schema-collision recovery, forward-compatible inference, default
-  environment inference, const coercion, endpoint filters, example-depth controls, alias
-  resolution, single-schema oneOf preservation, readonly/read variants, binary-response import
-  coercion, form encoding defaults, additional-properties defaults, inline-allOf,
-  discriminated-union inference, and AsyncAPI message naming.
+  discriminant removal, forward-compatible inference, default environment inference, const
+  coercion, endpoint filters, example-depth controls, alias resolution, single-schema oneOf
+  preservation, read-variant responses, binary-response import coercion, form encoding defaults,
+  additional-properties defaults, and discriminated-union inference.
 - TypeScript: linter/formatter selection, consolidated type files, subpackage exports, and endpoint
   metadata.
 - Python: ORM/smart-union/coercion/wrapped-alias/positional-constructor/inheritance/validator
-  switches, flattened union bodies, stream chunk size, recursion limit, lazy imports, and custom
-  transport.
+  switches, flattened union bodies, lazy imports, and custom transport.
 - Java/JVM: JSON include, required-builder checks, public/extensible constructors, unknown-as-node,
   nullable annotations, and custom interceptors.
 - C#: union implementation switches, root-client access, generated error-type toggle, interceptor