@flighthq/requirement-codegen 0.5.1-edge.1692.64cda40 → 0.5.1-edge.1892.cbd15bd

package/README.md

@@ -13,5 +13,5 @@ Import the supported application-facing API from `@flighthq/requirement-codegen`
 This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
 
 - [Flight project](https://github.com/flighthq/flight)
-- [Source for @flighthq/requirement-codegen@0.5.1-edge.1692.64cda40](https://github.com/flighthq/flight/tree/64cda403571cb0bbdc7ab29b4ec6cdf5929fff6d/packages/requirement-codegen)
-- [License](https://github.com/flighthq/flight/blob/64cda403571cb0bbdc7ab29b4ec6cdf5929fff6d/LICENSE.md)
+- [Source for @flighthq/requirement-codegen@0.5.1-edge.1892.cbd15bd](https://github.com/flighthq/flight/tree/cbd15bd13373265e8f6dcf0cb057a16aee812919/packages/requirement-codegen)
+- [License](https://github.com/flighthq/flight/blob/cbd15bd13373265e8f6dcf0cb057a16aee812919/LICENSE.md)

package/dist/contract.d.ts

@@ -1,3 +1,3 @@
-export * from './requirementCodegen';
-export { initializeRequirementCodegenPlan } from './requirementCodegen';
+export * from './requirementCodegen.ts';
+export { initializeRequirementCodegenPlan } from './requirementCodegen.ts';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/contract.js

@@ -1,3 +1,3 @@
-export * from './requirementCodegen';
-export { initializeRequirementCodegenPlan } from './requirementCodegen';
+export * from "./requirementCodegen.js";
+export { initializeRequirementCodegenPlan } from "./requirementCodegen.js";
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createRequirementCodegenPlan } from './requirementCodegen';
+export { createRequirementCodegenPlan } from './requirementCodegen.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createRequirementCodegenPlan } from './requirementCodegen';
+export { createRequirementCodegenPlan } from "./requirementCodegen.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/requirementCodegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requirementCodegen.d.ts","sourceRoot":"","sources":["../src/requirementCodegen.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,MAAM,EACN,kBAAkB,EAClB,kBAAkB,EAElB,sBAAsB,EAEtB,cAAc,EACf,MAAM,0BAA0B,CAAC;AAElC,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACrC,YAAY,EAAE,QAAQ,CAAC,cAAc,CAAC,EACtC,OAAO,EAAE,MAAM,GACd,sBAAsB,GAAG,MAAM,CAIjC;AAID,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,kBAAkB,CAAC,sBAAsB,GAAG,MAAM,CAAC,EACxD,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACrC,YAAY,EAAE,QAAQ,CAAC,cAAc,CAAC,EACtC,OAAO,EAAE,MAAM,GACd,IAAI,CAkBN"}
+{"version":3,"file":"requirementCodegen.d.ts","sourceRoot":"","sources":["../src/requirementCodegen.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,MAAM,EACN,kBAAkB,EAClB,kBAAkB,EAElB,sBAAsB,EAGtB,cAAc,EACf,MAAM,0BAA0B,CAAC;AAElC,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACrC,YAAY,EAAE,QAAQ,CAAC,cAAc,CAAC,EACtC,OAAO,EAAE,MAAM,GACd,sBAAsB,GAAG,MAAM,CAIjC;AAID,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,kBAAkB,CAAC,sBAAsB,GAAG,MAAM,CAAC,EACxD,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACrC,YAAY,EAAE,QAAQ,CAAC,cAAc,CAAC,EACtC,OAAO,EAAE,MAAM,GACd,IAAI,CAkCN"}

package/dist/requirementCodegen.js

@@ -9,25 +9,68 @@ export function createRequirementCodegenPlan(catalog, requirements, backend) {
 // is ruled; this kernel cannot encode that decision accidentally because it returns no source text.
 export function initializeRequirementCodegenPlan(out, catalog, requirements, backend) {
     const entries = [];
+    const declined = [];
     const unresolved = [];
     const seen = new Set();
-    for (const requirement of requirements.requirements) {
+    for (const requirement of expandRequirements(catalog, requirements.requirements)) {
         const identity = requirementIdentity(requirement);
         if (seen.has(identity))
             continue;
         seen.add(identity);
         const matches = findRequirementCatalogEntries(catalog, backend, requirement.facet, requirement.key);
-        if (matches.length === 0) {
+        if (matches.length > 0) {
+            entries.push(...matches);
+            continue;
+        }
+        // Nothing satisfies it HERE. A disposition says that is deliberate for this exact backend, facet
+        // and kind, so the gap is recorded with its reason instead of reported as an oversight. Matched
+        // exactly and per backend: a decision canvas made says nothing about gl, which still reports.
+        const disposition = catalog.dispositions?.find((candidate) => candidate.backend === backend && candidate.facet === requirement.facet && candidate.kind === requirement.key);
+        if (disposition === undefined) {
             unresolved.push({ facet: requirement.facet, key: requirement.key });
         }
         else {
-            entries.push(...matches);
+            declined.push({
+                reason: disposition.reason,
+                requirement: { facet: requirement.facet, key: requirement.key },
+            });
         }
     }
     out.backend = backend;
+    out.declined = declined;
     out.entries = entries;
     out.unresolved = unresolved;
 }
+/**
+ * Adds the render requirements a format requirement implies, so one pass resolves both halves.
+ *
+ * A `document.format` requirement names a TAG and a renderer is keyed by a NODE KIND, so without this
+ * a render backend resolves nothing and every fragment comes back empty while the parser fragment
+ * fills — which is exactly what the per-file manifest is supposed to prevent. Expansion is ADDITIVE:
+ * the original requirement stays, because the parser backend still has to resolve it.
+ *
+ * Two match shapes, both exact-string: a translation keyed on the full key applies to that requirement,
+ * and one keyed on a bare format namespace applies to every requirement in it. The namespace form is
+ * what carries the kinds a document produces regardless of its tags — a SWF's `MovieClip` root exists
+ * even in a file whose only tag is `SetBackgroundColor`, which no per-tag row could state.
+ */
+function expandRequirements(catalog, requirements) {
+    const translations = catalog.translations;
+    if (translations === undefined || translations.length === 0)
+        return requirements;
+    const expanded = [...requirements];
+    for (const requirement of requirements) {
+        const namespace = requirement.key.includes('.') ? requirement.key.slice(0, requirement.key.indexOf('.')) : null;
+        for (const translation of translations) {
+            if (translation.from.facet !== requirement.facet)
+                continue;
+            const matches = translation.from.key === requirement.key || (namespace !== null && translation.from.key === namespace);
+            if (matches)
+                expanded.push(...translation.to);
+        }
+    }
+    return expanded;
+}
 function requirementIdentity(requirement) {
     return `${requirement.facet}\0${requirement.key}`;
 }

package/dist/requirementCodegen.js.map

@@ -1 +1 @@
-{"version":3,"file":"requirementCodegen.js","sourceRoot":"","sources":["../src/requirementCodegen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AAWvF,MAAM,UAAU,4BAA4B,CAC1C,OAAqC,EACrC,YAAsC,EACtC,OAAe;IAEf,MAAM,GAAG,GAAG,cAAc,EAAmC,CAAC;IAC9D,gCAAgC,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IACtE,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED,wGAAwG;AACxG,oGAAoG;AACpG,MAAM,UAAU,gCAAgC,CAC9C,GAAwD,EACxD,OAAqC,EACrC,YAAsC,EACtC,OAAe;IAEf,MAAM,OAAO,GAA8B,EAAE,CAAC;IAC9C,MAAM,UAAU,GAAkB,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,WAAW,IAAI,YAAY,CAAC,YAAY,EAAE,CAAC;QACpD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,SAAS;QACjC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnB,MAAM,OAAO,GAAG,6BAA6B,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;QACpG,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;QACtE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IACtB,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IACtB,GAAG,CAAC,UAAU,GAAG,UAAU,CAAC;AAC9B,CAAC;AAED,SAAS,mBAAmB,CAAC,WAAkC;IAC7D,OAAO,GAAG,WAAW,CAAC,KAAK,KAAK,WAAW,CAAC,GAAG,EAAE,CAAC;AACpD,CAAC"}
+{"version":3,"file":"requirementCodegen.js","sourceRoot":"","sources":["../src/requirementCodegen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AAYvF,MAAM,UAAU,4BAA4B,CAC1C,OAAqC,EACrC,YAAsC,EACtC,OAAe;IAEf,MAAM,GAAG,GAAG,cAAc,EAAmC,CAAC;IAC9D,gCAAgC,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IACtE,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED,wGAAwG;AACxG,oGAAoG;AACpG,MAAM,UAAU,gCAAgC,CAC9C,GAAwD,EACxD,OAAqC,EACrC,YAAsC,EACtC,OAAe;IAEf,MAAM,OAAO,GAA8B,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAC9C,MAAM,UAAU,GAAkB,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,WAAW,IAAI,kBAAkB,CAAC,OAAO,EAAE,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;QACjF,MAAM,QAAQ,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,SAAS;QACjC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnB,MAAM,OAAO,GAAG,6BAA6B,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;QACpG,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,iGAAiG;QACjG,gGAAgG;QAChG,8FAA8F;QAC9F,MAAM,WAAW,GAAG,OAAO,CAAC,YAAY,EAAE,IAAI,CAC5C,CAAC,SAAS,EAAE,EAAE,CACZ,SAAS,CAAC,OAAO,KAAK,OAAO,IAAI,SAAS,CAAC,KAAK,KAAK,WAAW,CAAC,KAAK,IAAI,SAAS,CAAC,IAAI,KAAK,WAAW,CAAC,GAAG,CAC/G,CAAC;QACF,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;QACtE,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,WAAW,CAAC,MAAM;gBAC1B,WAAW,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE;aAChE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IACtB,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACxB,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IACtB,GAAG,CAAC,UAAU,GAAG,UAAU,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,kBAAkB,CACzB,OAAqC,EACrC,YAA8C;IAE9C,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1C,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,YAAY,CAAC;IACjF,MAAM,QAAQ,GAA4B,CAAC,GAAG,YAAY,CAAC,CAAC;IAC5D,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAChH,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACvC,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,KAAK,WAAW,CAAC,KAAK;gBAAE,SAAS;YAC3D,MAAM,OAAO,GACX,WAAW,CAAC,IAAI,CAAC,GAAG,KAAK,WAAW,CAAC,GAAG,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC;YACzG,IAAI,OAAO;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,mBAAmB,CAAC,WAAkC;IAC7D,OAAO,GAAG,WAAW,CAAC,KAAK,KAAK,WAAW,CAAC,GAAG,EAAE,CAAC;AACpD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/requirement-codegen",
-  "version": "0.5.1-edge.1692.64cda40",
+  "version": "0.5.1-edge.1892.cbd15bd",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,9 +38,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/entity": "0.5.1-edge.1692.64cda40",
-    "@flighthq/requirement-catalog": "0.5.1-edge.1692.64cda40",
-    "@flighthq/types": "0.5.1-edge.1692.64cda40"
+    "@flighthq/entity": "0.5.1-edge.1892.cbd15bd",
+    "@flighthq/requirement-catalog": "0.5.1-edge.1892.cbd15bd",
+    "@flighthq/types": "0.5.1-edge.1892.cbd15bd"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/requirementCodegen.test.ts

@@ -1,9 +1,15 @@
 import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
 import { createRequirementCatalog } from '@flighthq/requirement-catalog/contract';
-import type { RequirementCatalogEntry, RequirementSet } from '@flighthq/types/contract';
+import type {
+  Requirement,
+  RequirementCatalog,
+  RequirementCatalogEntry,
+  RequirementDisposition,
+  RequirementSet,
+} from '@flighthq/types/contract';
 import { EntityRuntimeKey, RequirementFacet } from '@flighthq/types/contract';
 
-import { createRequirementCodegenPlan, initializeRequirementCodegenPlan } from './requirementCodegen';
+import { createRequirementCodegenPlan, initializeRequirementCodegenPlan } from './requirementCodegen.ts';
 
 const shapeRenderer: RequirementCatalogEntry = {
   backend: 'webgl',
@@ -79,8 +85,126 @@ describe('createRequirementCodegenPlan', () => {
     });
   });
 });
+describe('createRequirementCodegenPlan with dispositions', () => {
+  it('routes a disposed requirement to declined rather than unresolved, carrying the reason', () => {
+    const plan = createRequirementCodegenPlan(
+      disposedCatalog([], [disposition('dom', 'Tilemap', 'no DOM tilemap path')]),
+      disposedSet([disposedRequirement('Tilemap')]),
+      'dom',
+    );
+
+    expect(plan.unresolved).toEqual([]);
+    expect(plan.declined).toEqual([
+      { reason: 'no DOM tilemap path', requirement: { facet: RequirementFacet.SceneNodeKind, key: 'Tilemap' } },
+    ]);
+  });
+
+  // The whole point: a decision and an oversight must not look alike.
+  it('leaves an undisposed gap in unresolved, so an oversight still reports', () => {
+    const plan = createRequirementCodegenPlan(
+      disposedCatalog([], []),
+      disposedSet([disposedRequirement('Tilemap')]),
+      'dom',
+    );
+    expect(plan.declined).toEqual([]);
+    expect(plan.unresolved).toEqual([{ facet: RequirementFacet.SceneNodeKind, key: 'Tilemap' }]);
+  });
+
+  // ★ EXACTNESS, ONE AXIS AT A TIME. A disposition names one backend, one facet and one kind. If any
+  // of the three were matched loosely it would silence requirements nobody considered, which is the
+  // failure this feature exists to prevent rather than introduce.
+  it('does not apply to another backend', () => {
+    const c = disposedCatalog([], [disposition('dom', 'Tilemap', 'no DOM tilemap path')]);
+    expect(createRequirementCodegenPlan(c, disposedSet([disposedRequirement('Tilemap')]), 'canvas').unresolved).toEqual(
+      [{ facet: RequirementFacet.SceneNodeKind, key: 'Tilemap' }],
+    );
+  });
+
+  it('does not apply to another kind', () => {
+    const c = disposedCatalog([], [disposition('dom', 'Tilemap', 'no DOM tilemap path')]);
+    expect(createRequirementCodegenPlan(c, disposedSet([disposedRequirement('QuadBatch')]), 'dom').unresolved).toEqual([
+      { facet: RequirementFacet.SceneNodeKind, key: 'QuadBatch' },
+    ]);
+  });
+
+  it('does not apply to another facet', () => {
+    const c = disposedCatalog(
+      [],
+      [{ ...disposition('dom', 'Tilemap', 'no DOM tilemap path'), facet: RequirementFacet.DocumentFormat }],
+    );
+    expect(createRequirementCodegenPlan(c, disposedSet([disposedRequirement('Tilemap')]), 'dom').unresolved).toEqual([
+      { facet: RequirementFacet.SceneNodeKind, key: 'Tilemap' },
+    ]);
+  });
+
+  it('emits no entry for a declined requirement, so nothing is imported or registered for it', () => {
+    const plan = createRequirementCodegenPlan(
+      disposedCatalog([], [disposition('dom', 'Tilemap', 'no DOM tilemap path')]),
+      disposedSet([disposedRequirement('Tilemap')]),
+      'dom',
+    );
+    expect(plan.entries).toEqual([]);
+  });
+
+  // A disposition is a fallback for a gap, never an override: if the backend CAN satisfy it, it does.
+  it('never overrides a row that actually resolves', () => {
+    const plan = createRequirementCodegenPlan(
+      disposedCatalog([disposedEntry('dom', 'Tilemap')], [disposition('dom', 'Tilemap', 'stale decision')]),
+      disposedSet([disposedRequirement('Tilemap')]),
+      'dom',
+    );
+    expect(plan.entries.map((e) => e.implementationSymbol)).toEqual(['domTilemapRenderer']);
+    expect(plan.declined).toEqual([]);
+    expect(plan.unresolved).toEqual([]);
+  });
+
+  it('reports one requirement declined and another missing in the same plan', () => {
+    const plan = createRequirementCodegenPlan(
+      disposedCatalog([], [disposition('dom', 'Tilemap', 'no DOM tilemap path')]),
+      disposedSet([disposedRequirement('Tilemap'), disposedRequirement('QuadBatch')]),
+      'dom',
+    );
+    expect(plan.declined.map((d) => d.requirement.key)).toEqual(['Tilemap']);
+    expect(plan.unresolved.map((r) => r.key)).toEqual(['QuadBatch']);
+  });
+});
+
 describe('initializeRequirementCodegenPlan', () => {
   it('is the construction initializer of createRequirementCodegenPlan', () => {
     expect(typeof initializeRequirementCodegenPlan).toBe('function');
   });
 });
+
+function disposedRequirement(kind: string): Requirement {
+  return { facet: RequirementFacet.SceneNodeKind, key: kind };
+}
+
+// Built the way every other set in this file is built, so the test needs no dependency the package
+// does not already declare.
+function disposedSet(requirements: readonly Requirement[]): RequirementSet {
+  const out = allocateEntity<RequirementSet>();
+  out.covers = [RequirementFacet.SceneNodeKind];
+  out.requirements = [...requirements];
+  return finishEntity(out);
+}
+
+function disposition(backend: string, kind: string, reason: string): RequirementDisposition {
+  return { backend, facet: RequirementFacet.SceneNodeKind, kind, reason };
+}
+
+function disposedEntry(backend: string, kind: string): RequirementCatalogEntry {
+  return {
+    backend,
+    facet: RequirementFacet.SceneNodeKind,
+    implementationImport: '@flighthq/scene2d-dom',
+    implementationSymbol: `${backend}${kind}Renderer`,
+    kind,
+  };
+}
+
+function disposedCatalog(
+  entries: readonly RequirementCatalogEntry[],
+  dispositions: readonly RequirementDisposition[],
+): RequirementCatalog {
+  return { dispositions: [...dispositions], entries: [...entries] };
+}