feat: add api-envelope fixture, showcase cleanup, generics validation, CI hardening

- Add fixtures/api-envelope.yaml testing double-wrapping ApiEnvelopeTemplate<T>
  pattern with inline route-level binding
- Clean up petstore-dynamicref-showcase.yaml: remove ErrorDetail, replace
  default responses with 400/404, reduce Redocly warnings from 12 to 5
- Add generic template detection to matrix quality analyzer (recognizes
  parameterized output like PaginatedTemplate<User>)
- Fix stale CONCRETE_TYPES (remove BaseFolder/BaseResource, add FolderTemplate,
  ApiEnvelopeTemplate, PaginatedUserItems)
- Mark nested-workspace-resources invalid AJV test as knownGap, fix knownGap
  label logic to distinguish FIXED from KNOWN-GAP
- Wire api-envelope into SCENARIOS, QUALITY_SIGNALS, orval.config.ts,
  validate-jsonschema.mjs, and GitHub Actions matrix
- Update CI to record actual generator status from JSON instead of step outcome
- Update docs: fixtures/README.md, state-of-the-union.md, IMPLEMENTATION_GUIDE.md,
  RUNBOOK.md, README.md, issue template
- Update GitHub issues #1 (Orval), #4 (openapi-typescript), #5 (hey-api) with
  explicit generics validation criteria (PASS/PARTIAL/DEGRADED)
- Remove empty fixtures/instances/ directory

Author: aqeelat

.github/ISSUE_TEMPLATE/generator-tracking.md

@@ -19,15 +19,19 @@ assignees: ""
 - Generation:
 - Typecheck:
 - `$dynamicRef` fidelity:
+  - Recursive fixtures: dynamic scope resolves to the active recursive type
+  - Generic fixtures: generators emit reusable parameterized types when the target language supports generics (concrete materialization is PARTIAL — correct content, lost reuse)
 - Last checked:
 
 ## Fixture Coverage
 
 - [ ] `baseline-duplicated-pagination`
 - [ ] `generic-schema-binding`
 - [ ] `paginated-response`
+- [ ] `api-envelope`
 - [ ] `recursive-category-tree`
 - [ ] `nested-workspace-resources`
+- [ ] `non-identifier-schema-key`
 
 ## Evidence
 

.github/workflows/matrix.yml

@@ -58,8 +58,10 @@ jobs:
           - baseline-duplicated-pagination
           - generic-schema-binding
           - paginated-response
+          - api-envelope
           - recursive-category-tree
           - nested-workspace-resources
+          - non-identifier-schema-key
         version:
           - '3.1.0'
           - '3.1.1'
@@ -118,6 +120,8 @@ jobs:
       - name: Generate SDK
         if: steps.select.outputs.selected == 'true'
         id: generate
+        env:
+          MATRIX_RESULTS_FILE: logs/matrix-results-${{ matrix.tool }}-${{ matrix.scenario }}-${{ matrix.version }}.json
         run: node scripts/matrix-runner.mjs --tools=${{ matrix.tool }} --scenarios=${{ matrix.scenario }} --versions=${{ matrix.version }} --no-typecheck --no-analysis
         continue-on-error: true
 
@@ -155,7 +159,12 @@ jobs:
             echo "${{ matrix.tool }}.${{ matrix.scenario }}.${{ matrix.version }}.typecheck=filtered" >> "$result_file"
             exit 0
           fi
-          gen_outcome="${{ steps.generate.outcome }}"
+          matrix_result="logs/matrix-results-${{ matrix.tool }}-${{ matrix.scenario }}-${{ matrix.version }}.json"
+          if [ -f "$matrix_result" ]; then
+            gen_outcome=$(node -e "const r=require('./${matrix_result}'); console.log(r.results?.[0]?.generate || 'unknown')")
+          else
+            gen_outcome="${{ steps.generate.outcome }}"
+          fi
           tc_outcome="${{ steps.typecheck.outcome }}"
           tc_skip="${{ steps.typecheck.outputs.skip }}"
           echo "${{ matrix.tool }}.${{ matrix.scenario }}.${{ matrix.version }}.generate=${gen_outcome:-skipped}" >> "$result_file"

IMPLEMENTATION_GUIDE.md

@@ -6,7 +6,7 @@ This repository is a public compatibility lab for OpenAPI `$dynamicRef` / `$dyna
 
 ## Current Headline
 
-OpenAPI 3.1.x allows JSON Schema 2020-12 schema objects, and OpenAPI 3.2 explicitly recommends dynamic references for generic/template data structures. In the current matrix, tools still either fail to parse `$dynamicAnchor`, generate syntactically valid but semantically degraded TypeScript, or lose concrete dynamic types such as `User[]`, `LocalizedCategory[]`, or `WorkspaceFolder[]`.
+OpenAPI 3.1.x allows JSON Schema 2020-12 schema objects, and OpenAPI 3.2 explicitly recommends dynamic references for generic/template data structures. In the current matrix, tools still either fail to parse `$dynamicAnchor`, generate syntactically valid but semantically degraded output (e.g., `unknown`, `any`, or `Object`), lose dynamic scope resolution for recursive types, or materialize generic/template patterns as duplicate concrete types instead of reusable parameterized types.
 
 Generator and typecheck failures in this repo are **report-only** because those failures are the compatibility data. Fixture validity and generated spec freshness are the CI gates.
 
@@ -56,8 +56,12 @@ Top-level fixtures feed the SDK generator matrix:
 | `baseline-duplicated-pagination.yaml` | Control case with duplicated concrete paginated wrappers |
 | `generic-schema-binding.yaml` | Generic pagination with named concrete schemas |
 | `paginated-response.yaml` | Generic pagination with inline response-level binding |
+| `api-envelope.yaml` | Generic response envelope with inline route-level binding |
 | `recursive-category-tree.yaml` | Recursive dynamic override using `$dynamicAnchor: category` |
-| `nested-workspace-resources.yaml` | Nested resource graph with multiple dynamic anchors |
+| `nested-workspace-resources.yaml` | Multi-parameter generic template for nested folder/resource graphs |
+| `non-identifier-schema-key.yaml` | Recursive dynamic override with schema keys that need generated identifier normalization |
+
+A combined showcase fixture, [`petstore-dynamicref-showcase.yaml`](petstore-dynamicref-showcase.yaml), exercises all `$dynamicRef` patterns together (generic pagination, response envelopes, nested generics, recursive trees, multi-parameter generic templates, non-identifier keys, typed request/response bodies) and is intended for SDK samples and maintainer demos.
 
 Focused semantics fixtures live under `fixtures/spec-semantics/`. They cover JSON Schema behaviors that are important for parser/validator correctness but are intentionally kept out of the SDK matrix.
 

README.md

@@ -41,7 +41,7 @@ CI also checks `git diff --exit-code -- specs/` after Stage 1. Fixture validity
 npm run matrix
 ```
 
-Runs all 9 generators × 5 scenarios × 4 OAS versions in parallel (default: 8 workers). Generators that aren't installed are skipped with a clear message.
+Runs all 9 generators × 7 scenarios × 4 OAS versions in parallel (default: 8 workers). Generators that aren't installed are skipped with a clear message.
 
 ### Generators in the Matrix
 
@@ -116,10 +116,13 @@ scenarios=generic-schema-binding,recursive-category-tree
 ```bash
 grep -n "items\|children" generated/orval/generic-schema-binding/3.1.2/model/paginatedTemplate.ts
 grep -n "items\|children" generated/orval/recursive-category-tree/3.1.2/model/baseCategory.ts
-grep -n "items\|children" generated/orval/nested-workspace-resources/3.1.2/model/baseFolder.ts
+grep -n "children\|shortcuts" generated/orval/nested-workspace-resources/3.1.2/model/folderTemplate.ts
+grep -n "data" generated/orval/api-envelope/3.1.2/model/apiEnvelopeTemplate.ts
 ```
 
-For dynamicRef fixtures, the desired result is concrete types (e.g., `items: User[]`, `children: Category[]`). Current generator output degrades to `unknown[]`, `Array<any>`, or `any`.
+For dynamicRef fixtures, the desired result depends on fixture category:
+- **Recursive/nested fixtures:** dynamic refs must resolve to the correct active type through dynamic scope (e.g., `children: LocalizedCategory[]`, not `children: unknown[]`).
+- **Generic/template fixtures:** generators must emit reusable parameterized types when the target language supports generics (e.g., `PaginatedTemplate<T>` with `PaginatedUserResponse = PaginatedTemplate<User>`). Concrete duplicate wrappers do not pass validation for these fixtures — the point of `$dynamicRef` for generics is type reuse. Current generator output degrades to `unknown[]`, `Array<any>`, `any`, or materializes duplicates instead of parameterized types.
 
 ## Optional: JSON Schema Runtime Validation
 

RUNBOOK.md

@@ -13,10 +13,20 @@ npm run validate:fixtures
 | Fixture | Purpose | What It Tests |
 |---|---|---|
 | `baseline-duplicated-pagination.yaml` | Control case with explicit `PaginatedUserResponse` and `PaginatedGroupResponse` schemas | Confirms a generator can handle ordinary duplicated wrappers before testing `$dynamicRef` |
-| `generic-schema-binding.yaml` | Reusable paginated wrapper with named concrete schemas (`PaginatedUserResponse`, `PaginatedGroupResponse`) | Tests JSON Schema generic-type pattern using `$dynamicRef` / `$dynamicAnchor` with named type instantiations |
+| `generic-schema-binding.yaml` | Reusable paginated wrapper with named concrete schemas (`PaginatedUserResponse`, `PaginatedGroupResponse`) | Tests JSON Schema generic-type pattern using `$dynamicRef` / `$dynamicAnchor` — generators must emit reusable parameterized types when the target language supports generics, not duplicate concrete wrappers |
 | `paginated-response.yaml` | Reusable paginated wrapper with type binding at the route response level | Tests the same generic pattern but with `$dynamicAnchor` overrides inline in the path operation response — no separate named wrapper schemas |
+| `api-envelope.yaml` | Generic response envelope (`ApiEnvelopeTemplate<T>`) with inline `$defs` binding at the route level — one route binds a single resource, another binds a paginated wrapper | Tests two-level `$dynamicRef` nesting: `ApiEnvelopeTemplate<T>` where `T` is bound inline per route. Generators must emit `ApiEnvelopeTemplate<T>` as a reusable parameterized type. The paginated-list route additionally chains `PaginatedTemplate<User>` as the bound type |
 | `recursive-category-tree.yaml` | Canonical dynamic recursive override | Tests dynamic scope for recursive schemas (`children` should use the active category type) |
-| `nested-workspace-resources.yaml` | Multiple anchors and nested dynamic refs | Tests more than one `$dynamicAnchor` / `$dynamicRef` pair in a nested resource graph |
+| `nested-workspace-resources.yaml` | Multi-parameter generic template for nested folder/resource graphs | Tests a `$dynamicRef` template with two generic slots (`folderType`, `resourceType`) that are bound together in the concrete schema, producing a self-referential folder/resource graph |
+| `non-identifier-schema-key.yaml` | Recursive dynamic override with non-identifier schema keys (`base-category`, `localized-category`) | Tests that generators preserve `$dynamicRef` semantics while normalizing schema keys into valid generated identifiers |
+
+A combined showcase fixture at [`petstore-dynamicref-showcase.yaml`](../petstore-dynamicref-showcase.yaml) exercises all `$dynamicRef` patterns together (generic pagination, response envelopes, nested generics, recursive trees, multi-parameter generic templates, non-identifier keys, typed request/response bodies) and is intended for SDK samples, maintainer demos, and "what good output looks like" examples. It is not a replacement for the focused minimal fixtures above.
+
+## Generator Edge Fixtures
+
+Generator edge fixtures are top-level SDK matrix scenarios when the behavior is portable across generators. `non-identifier-schema-key.yaml` is one of these: it tests schema-key normalization plus dynamic reference fidelity, not any one tool's internal implementation.
+
+Tool-specific switches, such as Orval's `enableUnstableDynamicRefSupport`, are not modeled as schema fixtures. Track those in the relevant GitHub issue and tool docs instead.
 
 ## Spec Semantics Fixtures
 
@@ -25,6 +35,8 @@ npm run validate:fixtures
 | Fixture | What It Tests |
 |---|---|
 | `spec-semantics/dynamicref-core-semantics.yaml` | Same-resource dynamic anchors, `$dynamicRef` to `$anchor`, `$ref` to `$dynamicAnchor`, fallback to ordinary anchor behavior, non-fragment URI dynamic refs, multi-parameter generic binding, and allOf sibling order |
+| `spec-semantics/external-dynamic-ref.yaml` | `$dynamicRef` to an external JSON Schema resource (`external-dynamic-target.json`) for parser/bundler research |
+| `spec-semantics/ambiguous-sibling-anchors.yaml` | Multiple sibling schemas with the same `$dynamicAnchor` name, documenting where static sibling scans are only an approximation of dynamic scope |
 
 ## Why Keep The Baseline?
 
@@ -63,9 +75,13 @@ Run via `scripts/validate-openapi.sh` as part of the Stage 1 pipeline. This incl
 | `baseline-duplicated-pagination.yaml` | Pass | Pass | Pass | Pass |
 | `generic-schema-binding.yaml` | Pass | Pass | Pass | Pass |
 | `paginated-response.yaml` | Pass | Pass | Pass | Pass |
+| `api-envelope.yaml` | Pass | Pass | Pass | Pass |
 | `recursive-category-tree.yaml` | Pass | Pass | Pass | Pass |
 | `nested-workspace-resources.yaml` | Pass | Pass | Pass | Pass |
+| `non-identifier-schema-key.yaml` | Pass | Pass | Pass | Pass |
+| `spec-semantics/ambiguous-sibling-anchors.yaml` | Pass | Pass | Pass | Pass |
 | `spec-semantics/dynamicref-core-semantics.yaml` | Pass | Pass | Pass | Pass |
+| `spec-semantics/external-dynamic-ref.yaml` | Pass | Pass | Pass | Pass |
 
 ## JSON Schema Runtime Validation
 
@@ -78,11 +94,15 @@ Validators: AJV 2020 and Hyperjump 2020-12.
 | `baseline-duplicated-pagination.yaml` | Pass | Pass | Not tested | Control passes |
 | `generic-schema-binding.yaml` | Valid user/group pages fail; invalid item cases fail | Valid user/group pages pass; invalid item cases fail | Valid user/group pages pass; invalid item cases fail | AJV PR #2615 fixes this |
 | `paginated-response.yaml` | Valid user/group pages fail; invalid item cases fail | Valid user/group pages pass; invalid item cases fail | Valid user/group pages pass; invalid item cases fail | AJV PR #2615 fixes this |
+| `api-envelope.yaml` | Valid wrapped-user page fails; invalid item cases fail | Not tested | Not tested | Expected same gap as pagination fixtures; AJV PR #2615 should fix this |
 | `recursive-category-tree.yaml` | Valid localized category tree passes; child missing localized fields fails | Pass | Not tested | Runtime check passes |
-| `nested-workspace-resources.yaml` | Valid nested workspace passes; nested folder missing permissions fails | Fails: "resolves to more than one schema" for multiple same-name `$dynamicAnchor` | Not tested | Separate AJV gap: multiple schemas with same `$dynamicAnchor` name |
+| `nested-workspace-resources.yaml` | Valid nested workspace passes; AJV accepts invalid nested folder data (missing `permissions` field) | Fails: "resolves to more than one schema" for multiple same-name `$dynamicAnchor` in the same document (`FolderTemplate.$defs.folderType` and `WorkspaceFolder.$defs.folderType` share an anchor name) — this is an AJV limitation, not a fixture bug | Not tested | AJV does not correctly resolve the multi-parameter generic template pattern; the fixture is semantically sound |
+| `non-identifier-schema-key.yaml` | Valid localized category tree passes; child missing localized fields fails | Not tested | Valid localized category tree passes; child missing localized fields fails | Runtime check passes; generator matrix tests identifier normalization |
+| `spec-semantics/ambiguous-sibling-anchors.yaml` | Not tested | Not tested | Not tested | OpenAPI-valid research fixture for static-scan limitations |
 | `spec-semantics/dynamicref-core-semantics.yaml` | `$ref` to `$dynamicAnchor` passes; several `$dynamicRef` core cases are known gaps, including non-fragment URI refs | Not tested | Core cases, non-fragment URI refs, allOf order, and multi-parameter generic cases pass | Semantics fixture tier; AJV gaps are documented by case output |
+| `spec-semantics/external-dynamic-ref.yaml` | Not tested | Not tested | Valid external node passes; invalid external node fails | External resource semantics fixture for parser/bundler research |
 
-AJV PR [#2615](https://github.com/ajv-validator/ajv/pull/2615) fixes the generic pagination dynamic binding pattern. The nested workspace fixture exposes a separate AJV limitation: multiple schemas declaring the same `$dynamicAnchor` name in a single document causes an ambiguous reference error.
+AJV PR [#2615](https://github.com/ajv-validator/ajv/pull/2615) fixes the generic pagination dynamic binding pattern. The nested workspace fixture exposes a separate AJV limitation: multiple schemas declaring the same `$dynamicAnchor` name in a single document causes an ambiguous reference error. This is a limitation of AJV PR #2615, not a bug in the fixture — `nested-workspace-resources.yaml` is semantically correct (both anchor declarations are scoped to different schemas in the `allOf` chain).
 
 ## Fixture To Spec Path
 

fixtures/README.md

@@ -0,0 +1,134 @@
+openapi: 3.1.0
+info:
+  title: DynamicRef API Envelope API
+  description: >
+    Tests the double-wrapping $dynamicRef pattern: a generic response envelope
+    (ApiEnvelopeTemplate<T>) whose data slot is bound at the route response level
+    using inline $defs + $dynamicAnchor. Both a single-resource and a paginated
+    resource response are included to exercise two distinct bindings against the
+    same template.
+  version: 0.1.0
+  license:
+    name: MIT
+    identifier: MIT
+servers:
+  - url: https://api.dynamicref.test
+security: []
+
+paths:
+  /users/{userId}:
+    get:
+      summary: Get a user
+      operationId: getUser
+      tags: [Users]
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: A single user wrapped in the response envelope
+          content:
+            application/json:
+              schema:
+                $defs:
+                  dataType:
+                    $dynamicAnchor: dataType
+                    $ref: '#/components/schemas/User'
+                $ref: '#/components/schemas/ApiEnvelopeTemplate'
+        '404':
+          description: Not found
+
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      tags: [Users]
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        '200':
+          description: Paginated user list wrapped in the response envelope
+          content:
+            application/json:
+              schema:
+                $defs:
+                  dataType:
+                    $dynamicAnchor: dataType
+                    $ref: '#/components/schemas/PaginatedUserItems'
+                $ref: '#/components/schemas/ApiEnvelopeTemplate'
+        '400':
+          description: Bad request
+
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email]
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+
+    ApiEnvelopeTemplate:
+      $id: https://example.com/schemas/ApiEnvelopeTemplate
+      $defs:
+        dataType:
+          $dynamicAnchor: dataType
+          not: {}
+      type: object
+      required: [data, requestId]
+      properties:
+        data:
+          $dynamicRef: '#dataType'
+        requestId:
+          type: string
+          format: uuid
+
+    PaginatedTemplate:
+      $id: https://example.com/schemas/PaginatedTemplate
+      $defs:
+        itemType:
+          $dynamicAnchor: itemType
+          not: {}
+      type: object
+      required: [items, total, page, pageSize]
+      properties:
+        items:
+          type: array
+          items:
+            $dynamicRef: '#itemType'
+        total:
+          type: integer
+          minimum: 0
+        page:
+          type: integer
+          minimum: 1
+        pageSize:
+          type: integer
+          minimum: 1
+
+    PaginatedUserItems:
+      $defs:
+        itemType:
+          $dynamicAnchor: itemType
+          $ref: '#/components/schemas/User'
+      $ref: '#/components/schemas/PaginatedTemplate'