@forgeax/engine-runtime 0.1.2

package/src/__tests__/asi-world-ci-config.unit.test.ts

@@ -0,0 +1,186 @@
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch / M5 / w19.
+//
+// Forward-looking contract for the asi-world package.json metrics
+// declaration + ci.yml 2-step smoke registration — plan-tasks w19 targets.
+//
+// R-NEW-1 fallback engaged: apps/hello/asi-world/package.json does not
+// exist on this branch (upstream tweak-20260624 not landed per
+// m0-probe.json). Adding a `pnpm --filter @forgeax/hello-asi-world smoke`
+// step to .github/workflows/ci.yml against a missing workspace member
+// would fail CI immediately on every PR (pnpm filter match=0). The same
+// applies to `pnpm --filter @forgeax/hello-tilemap smoke` since
+// apps/hello/tilemap also does not exist on this branch.
+//
+// This test locks the configuration intent (both the package.json
+// forgeax.metrics 5-class declaration shape and the ci.yml 2-step
+// insertion) so a follow-up commit lands the literal edits once upstream
+// materialises. The follow-up is a single PR that:
+//   1. Writes apps/hello/asi-world/package.json with smoke script +
+//      5-class forgeax.metrics declaration.
+//   2. Adds 2 named steps to .github/workflows/ci.yml inside the
+//      existing `primary-pnpm` job's smoke matrix section.
+//   3. Runs `pnpm run lint && pnpm ci:channel-align` per AGENTS.md
+//      Commands "CI edit pre-commit" guidance.
+//
+// Anchors:
+//   - plan-strategy.md section 5.5 (2 new ci.yml steps for hello-tilemap
+//     + asi-world).
+//   - plan-strategy.md section 5.6 (pnpm ci:channel-align rerun in M5).
+//   - plan-strategy.md section 7 M5 boundary.
+//   - AGENTS.md Commands "CI edit pre-commit".
+//   - AGENTS.md Metric registry (5 closed MetricKind).
+
+import { describe, it } from 'vitest';
+
+/** Closed MetricKind union per AGENTS.md Metric registry (order locked). */
+type MetricKind = 'bundle-size' | 'fps' | 'bench' | 'gate' | 'spike-report';
+
+interface MetricEntry {
+  readonly kind: MetricKind;
+  readonly enabled: boolean;
+  readonly reasonRequiredWhenDisabled: boolean;
+}
+
+/** asi-world package.json#forgeax.metrics declaration shape. */
+const ASI_WORLD_METRICS: readonly MetricEntry[] = [
+  // gate = headless smoke (newly enabled by w19; w18 smoke 300 frames).
+  { kind: 'gate', enabled: true, reasonRequiredWhenDisabled: false },
+  // The other 4 categories follow hello-tilemap template: all disabled
+  // with reason strings explaining why this demo workspace does not opt
+  // into that metric kind.
+  { kind: 'bundle-size', enabled: false, reasonRequiredWhenDisabled: true },
+  { kind: 'fps', enabled: false, reasonRequiredWhenDisabled: true },
+  { kind: 'bench', enabled: false, reasonRequiredWhenDisabled: true },
+  { kind: 'spike-report', enabled: false, reasonRequiredWhenDisabled: true },
+];
+
+/** ci.yml two new steps shape. */
+interface CiStep {
+  readonly name: string;
+  readonly run: string;
+  readonly insertionAnchor: 'inside primary-pnpm job, smoke matrix section';
+}
+
+const CI_STEPS: readonly CiStep[] = [
+  {
+    name: 'Hello-tilemap headless smoke',
+    run: 'pnpm --filter @forgeax/hello-tilemap smoke',
+    insertionAnchor: 'inside primary-pnpm job, smoke matrix section',
+  },
+  {
+    name: 'asi-world headless smoke',
+    run: 'pnpm --filter @forgeax/hello-asi-world smoke',
+    insertionAnchor: 'inside primary-pnpm job, smoke matrix section',
+  },
+];
+
+describe('asi-world package.json forgeax.metrics declaration contract (w19, R-NEW-1 fallback)', () => {
+  it('declares all 5 MetricKind values', () => {
+    const declared = new Set(ASI_WORLD_METRICS.map((m) => m.kind));
+    const required: readonly MetricKind[] = ['bundle-size', 'fps', 'bench', 'gate', 'spike-report'];
+    for (const k of required) {
+      if (!declared.has(k)) {
+        throw new Error(`MetricKind '${k}' missing from asi-world declaration`);
+      }
+    }
+    if (declared.size !== 5) {
+      throw new Error(`declaration count drift: expected 5 unique kinds, got ${declared.size}`);
+    }
+  });
+
+  it('gate is enabled (smoke materialises in w18)', () => {
+    const gate = ASI_WORLD_METRICS.find((m) => m.kind === 'gate');
+    if (gate === undefined) throw new Error('gate entry missing');
+    if (gate.enabled !== true) {
+      throw new Error('gate must flip enabled=true after w18 smoke lands');
+    }
+  });
+
+  it('the 4 non-gate metrics are disabled with reason required', () => {
+    const nonGate = ASI_WORLD_METRICS.filter((m) => m.kind !== 'gate');
+    for (const m of nonGate) {
+      if (m.enabled !== false) {
+        throw new Error(`metric ${m.kind} unexpectedly enabled in demo workspace`);
+      }
+      if (m.reasonRequiredWhenDisabled !== true) {
+        throw new Error(`metric ${m.kind} must require reason when disabled`);
+      }
+    }
+  });
+});
+
+describe('ci.yml 2-step smoke insertion contract (w19, R-NEW-1 fallback)', () => {
+  it('exactly 2 new steps (hello-tilemap + asi-world)', () => {
+    if (CI_STEPS.length !== 2) {
+      throw new Error(`ci.yml insertion count drift: expected 2 got ${CI_STEPS.length}`);
+    }
+  });
+
+  it('each step uses pnpm filter --filter @forgeax/<demo> smoke', () => {
+    for (const step of CI_STEPS) {
+      if (!step.run.startsWith('pnpm --filter @forgeax/')) {
+        throw new Error(`ci.yml step '${step.name}' run command drift: ${step.run}`);
+      }
+      if (!step.run.endsWith(' smoke')) {
+        throw new Error(`ci.yml step '${step.name}' must invoke smoke script: got ${step.run}`);
+      }
+    }
+  });
+
+  it('insertion anchor is the existing primary-pnpm smoke matrix section', () => {
+    for (const step of CI_STEPS) {
+      if (step.insertionAnchor !== 'inside primary-pnpm job, smoke matrix section') {
+        throw new Error(`ci.yml insertion anchor drift on ${step.name}`);
+      }
+    }
+  });
+
+  it('hello-asi-world and hello-tilemap demos are both covered', () => {
+    const covered = new Set(
+      CI_STEPS.map((s) => {
+        const m = s.run.match(/@forgeax\/(\S+)/);
+        return m === null ? 'unknown' : m[1];
+      }),
+    );
+    if (!covered.has('hello-tilemap')) {
+      throw new Error('hello-tilemap step missing from CI insertion plan');
+    }
+    if (!covered.has('hello-asi-world')) {
+      throw new Error('hello-asi-world step missing from CI insertion plan');
+    }
+  });
+});
+
+describe('w19 R-NEW-1 fallback boundary', () => {
+  it('ci.yml is NOT modified in this commit (would fail CI immediately)', () => {
+    // If apps/hello/asi-world/package.json (and apps/hello/tilemap/) do
+    // not exist as workspace members, `pnpm --filter @forgeax/hello-*`
+    // returns no matched packages and pnpm errors out, failing every PR.
+    // The follow-up commit that lands w19 literal edits must run AFTER
+    // upstream feat-20260622 + tweak-20260624 land in main.
+    //
+    // AGENTS.md CI edit pre-commit invariant: when this fallback clears
+    // and ci.yml is edited, the follow-up commit MUST run
+    //   pnpm run lint && pnpm ci:channel-align
+    // before commit (plan-strategy section 5.6).
+    const preCommitDiscipline = {
+      mustRun: ['pnpm run lint', 'pnpm ci:channel-align'],
+      anchor: 'AGENTS.md Commands "CI edit pre-commit"',
+    };
+    if (preCommitDiscipline.mustRun.length !== 2) {
+      throw new Error('CI edit pre-commit discipline drifted');
+    }
+  });
+
+  it('documents the metrics:check + ci:channel-align gates that the follow-up edit must satisfy', () => {
+    const acceptanceGates = [
+      'pnpm metrics:check',
+      'pnpm ci:channel-align',
+      'pnpm --filter @forgeax/hello-tilemap smoke',
+      'pnpm --filter @forgeax/hello-asi-world smoke',
+    ];
+    if (acceptanceGates.length !== 4) {
+      throw new Error('w19 acceptance gate set drifted');
+    }
+  });
+});

package/src/__tests__/asi-world-smoke.unit.test.ts

@@ -0,0 +1,192 @@
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch / M5 / w18.
+//
+// Forward-looking contract for the new asi-world headless smoke script
+// (`apps/hello/asi-world/scripts/smoke-dawn.mjs`) — plan-tasks w18 targets.
+//
+// R-NEW-1 + R-4 fallback chain engaged:
+//   - R-NEW-1: `apps/hello/asi-world/scripts/` does not exist on this
+//     branch (upstream tweak-20260624 not landed per m0-probe.json). The
+//     new smoke script cannot be authored against a non-existent demo
+//     workspace.
+//   - R-4: even with the demo, the wgpu_wasm import-binding gate
+//     (documented across M1-M4 milestone-completed events' gatesDeferred
+//     entries) blocks dawn-node init -> baseline PNG export (w16
+//     deferred) -> ε≤0.05 pixel-diff path -> falls back per plan-strategy
+//     section 4 R-4 to structural-only smoke (300 frames + ECS query
+//     bucket cap + drawcall cap + onError=0).
+//
+// Locks the smoke acceptance contract surface so a follow-up commit
+// authors the smoke-dawn.mjs (modelled on hello-tilemap template +
+// hello-transform-hierarchy dual-frame readback for the optional pixel
+// path when baseline PNG materialises).
+//
+// Anchors:
+//   - requirements.md AC-08 line 2 + AC-10 (terrain drawcall <= 16).
+//   - plan-strategy.md section 4 R-4 fallback.
+//   - plan-strategy.md section 5.4 falsifier variant convention.
+//   - plan-strategy.md section 7 M5 boundary.
+//   - m0-probe.json downstreamPropagation.M5_w18_terrainDrawcallUpperBound
+//     (11 drawcalls; single atlas; terrainLayerN=11; <= 16 cap).
+
+import { describe, it } from 'vitest';
+
+/**
+ * Closed contract for asi-world smoke acceptance after w18 lands.
+ *
+ *   - targetFrames: 300 (AC-08 line 2).
+ *   - readbackFrameIndex: 120 (matches w16 baseline export contract;
+ *     both scripts must read SSOT from the same frame).
+ *   - pixelDiffEpsilonCap: 0.05 (AC-08 line 2 ε≤0.05 vs baseline PNG).
+ *   - pixelDiffMode: 'baseline-vs-readback' when baseline PNG present;
+ *     'structural-only' when R-4 fallback engaged (current state).
+ *   - terrainBucketEntityCap: 16 * terrainLayerN; m0-probe reports
+ *     terrainLayerN=11 so cap = 176 entities. AC-10 says "<= 16N".
+ *   - terrainDrawcallCap: 16 (AC-10 hard ceiling; m0-probe says actual
+ *     value with single atlas + 11 layers = 11; structurally bounded by
+ *     atlasCount * layerCount which under single atlas reduces to
+ *     layerCount, capped at 16).
+ *   - rendererOnErrorCount: 0.
+ *   - falsifierVariant: 'regions-zero' — set every SpriteInstances.regions
+ *     entry to [0,0,0,0]; expected smoke FAIL (black frame). Not in CI
+ *     (one-off implement-time falsification check per plan-strategy
+ *     section 5.4).
+ */
+interface AsiWorldSmokeContract {
+  readonly targetFrames: 300;
+  readonly readbackFrameIndex: 120;
+  readonly pixelDiffEpsilonCap: 0.05;
+  readonly pixelDiffMode: 'baseline-vs-readback' | 'structural-only';
+  readonly terrainLayerN: 11;
+  readonly terrainBucketEntityCapMultiplier: 16;
+  readonly terrainDrawcallCap: 16;
+  readonly rendererOnErrorCount: 0;
+  readonly falsifierVariant: 'regions-zero';
+  readonly falsifierInCi: false;
+}
+
+const SMOKE_CONTRACT: AsiWorldSmokeContract = {
+  targetFrames: 300,
+  readbackFrameIndex: 120,
+  pixelDiffEpsilonCap: 0.05,
+  // R-4 fallback engaged on this commit: baseline PNG cannot be exported
+  // until wgpu_wasm gate clears + upstream demo lands. Follow-up commit
+  // flips this back to 'baseline-vs-readback' alongside the baseline PNG
+  // landing under w16.
+  pixelDiffMode: 'structural-only',
+  terrainLayerN: 11,
+  terrainBucketEntityCapMultiplier: 16,
+  terrainDrawcallCap: 16,
+  rendererOnErrorCount: 0,
+  falsifierVariant: 'regions-zero',
+  falsifierInCi: false,
+};
+
+describe('asi-world smoke 300-frame contract (w18, R-NEW-1 + R-4 fallback)', () => {
+  it('targetFrames matches AC-08 line 2 (300 frames)', () => {
+    if (SMOKE_CONTRACT.targetFrames !== 300) {
+      throw new Error(`targetFrames drift: expected 300 got ${SMOKE_CONTRACT.targetFrames}`);
+    }
+  });
+
+  it('readbackFrameIndex aligns with w16 baseline export contract (frame 120)', () => {
+    if (SMOKE_CONTRACT.readbackFrameIndex !== 120) {
+      throw new Error(
+        `readbackFrameIndex drift: expected 120 got ${SMOKE_CONTRACT.readbackFrameIndex} (w16 SSOT)`,
+      );
+    }
+    if (SMOKE_CONTRACT.readbackFrameIndex >= SMOKE_CONTRACT.targetFrames) {
+      throw new Error(
+        `readback frame ${SMOKE_CONTRACT.readbackFrameIndex} >= TARGET_FRAMES ${SMOKE_CONTRACT.targetFrames}`,
+      );
+    }
+  });
+
+  it('pixel diff epsilon cap is AC-08 ε=0.05', () => {
+    if (SMOKE_CONTRACT.pixelDiffEpsilonCap !== 0.05) {
+      throw new Error(`epsilon drift: expected 0.05 got ${SMOKE_CONTRACT.pixelDiffEpsilonCap}`);
+    }
+  });
+
+  it('pixel diff mode is structural-only under R-4 fallback (this commit) or baseline-vs-readback (post fallback clear)', () => {
+    const validModes: readonly AsiWorldSmokeContract['pixelDiffMode'][] = [
+      'baseline-vs-readback',
+      'structural-only',
+    ];
+    if (!validModes.includes(SMOKE_CONTRACT.pixelDiffMode)) {
+      throw new Error(`pixelDiffMode out of closed union: ${SMOKE_CONTRACT.pixelDiffMode}`);
+    }
+  });
+
+  it('terrain bucket entity cap = 16N derived from m0-probe terrainLayerN', () => {
+    // AC-10: terrain bucket entity count <= 16 * N where N = terrain
+    // layer count. m0-probe reports N=11; cap = 176.
+    const expectedCap =
+      SMOKE_CONTRACT.terrainBucketEntityCapMultiplier * SMOKE_CONTRACT.terrainLayerN;
+    if (expectedCap !== 176) {
+      throw new Error(
+        `terrain bucket entity cap math drift: 16 * 11 = 176 expected, got ${expectedCap}`,
+      );
+    }
+  });
+
+  it('terrain drawcall cap is AC-10 ceiling 16 (m0-probe actual=11 under single atlas; structurally bounded)', () => {
+    if (SMOKE_CONTRACT.terrainDrawcallCap !== 16) {
+      throw new Error(`drawcall cap drift: expected 16 got ${SMOKE_CONTRACT.terrainDrawcallCap}`);
+    }
+    // m0-probe.json says actual = atlasCount * layerCount = 1 * 11 = 11;
+    // 11 <= 16 satisfies AC-10. The cap stays at 16 to accommodate
+    // forward changes (additional atlas + layer combinations) without
+    // false-positive smoke failures.
+    if (SMOKE_CONTRACT.terrainLayerN > SMOKE_CONTRACT.terrainDrawcallCap) {
+      throw new Error(
+        `terrainLayerN ${SMOKE_CONTRACT.terrainLayerN} > drawcall cap ${SMOKE_CONTRACT.terrainDrawcallCap}; single-atlas assumption broken`,
+      );
+    }
+  });
+
+  it('renderer onError count target is 0', () => {
+    if (SMOKE_CONTRACT.rendererOnErrorCount !== 0) {
+      throw new Error(`onError drift: expected 0 got ${SMOKE_CONTRACT.rendererOnErrorCount}`);
+    }
+  });
+
+  it('falsifier variant is regions-zero (atlas-region degeneration; one-off implement-time check)', () => {
+    if (SMOKE_CONTRACT.falsifierVariant !== 'regions-zero') {
+      throw new Error(
+        `falsifier variant drift: expected regions-zero got ${SMOKE_CONTRACT.falsifierVariant}`,
+      );
+    }
+    if (SMOKE_CONTRACT.falsifierInCi !== false) {
+      throw new Error('falsifier must not run in CI (one-off implement-time falsification)');
+    }
+  });
+});
+
+describe('w18 R-NEW-1 + R-4 fallback documentation', () => {
+  it('declares the active fallback (structural-only mode this commit; baseline-vs-readback after w16 clears)', () => {
+    // When upstream feat-20260622 + tweak-20260624 land AND wgpu_wasm
+    // import-binding gate clears, a follow-up commit:
+    //   1. Writes apps/hello/asi-world/scripts/smoke-dawn.mjs end-to-end.
+    //   2. Runs w16 export-baseline.mjs against the feat-20260624
+    //      worktree to drop the baseline PNG into the assets submodule.
+    //   3. Flips SMOKE_CONTRACT.pixelDiffMode here from
+    //      'structural-only' to 'baseline-vs-readback' as a 1-line edit.
+    //   4. Registers the smoke step in ci.yml (w19 follow-up).
+    if (SMOKE_CONTRACT.pixelDiffMode !== 'structural-only') {
+      throw new Error('current commit must be structural-only under active R-4 fallback');
+    }
+  });
+
+  it('the smoke target package @forgeax/hello-asi-world is not registered in pnpm workspace this commit', () => {
+    // pnpm-workspace.yaml + apps/hello/asi-world/package.json are
+    // upstream-owned. w19 (config) creates the package.json once
+    // upstream lands. The acceptance check
+    //   `pnpm --filter @forgeax/hello-asi-world smoke`
+    // cannot execute on this commit; recorded as deferred in milestone
+    // CI sweep notes.
+    const acceptance = 'pnpm --filter @forgeax/hello-asi-world smoke';
+    if (!acceptance.includes('@forgeax/hello-asi-world')) {
+      throw new Error('acceptance command drifted');
+    }
+  });
+});

package/src/__tests__/asset-registry-scene.test-d.ts

@@ -0,0 +1,49 @@
+// asset-registry-scene.test-d - type-level assertion that the 5-element
+// AssetUnion exhaustive switch narrows correctly without a default arm
+// (feat-20260514-scene-as-world-blueprint w6 / AC-01 / AC-03; merged with
+// feat-20260514-ecs-children-instances-managed-buffer-array M3 / w15 which
+// retired the `'instanced-buffer-asset'` variant -> Asset closed-union
+// 5 -> 4, then widened to 5 again with the new `'scene'` member).
+//
+// w3 widens `Asset` to include `SceneAsset` and the runtime exhaustiveness
+// guard narrows correctly. The exhaustive switch below doubles as a
+// negative regression: deleting any case produces a `never` flow (TS reports
+// `Type 'SceneAsset' is not assignable to type 'never'` at the affected
+// arm), so this file fails fast if the union ever drifts.
+//
+// feat-20260623 M2 / w8: AssetBrand retired (PR #496 eliminated brand concept);
+// the brand(asset) function and local AssetBrand type are removed. The Asset
+// union exhaustive switch is the remaining type-level guard.
+//
+// Charter mapping: proposition 3 (machine-readable union > prose) +
+// proposition 4 (explicit failure: closed-union exhaustive switch needs no
+// default fallback; tsc strict mode guards completeness).
+
+import type { Asset } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('AssetUnion exhaustive switch covers all 15 members (feat-20260608 M0 baseline rebuild + feat-20260623-world-space-video-asset M1)', () => {
+  it('Asset union is the closed type-level discriminator for engine-known assets', () => {
+    // Asset is the SSOT for engine-known asset types; exhaustiveness is
+    // enforced by TypeScript's closed-union narrowing. A missing member
+    // triggers `Type 'XxxAsset' is not assignable to type 'never'`.
+    expectTypeOf<Asset['kind']>().toEqualTypeOf<
+      | 'mesh'
+      | 'texture'
+      | 'sampler'
+      | 'material'
+      | 'scene'
+      | 'equirect'
+      | 'skeleton'
+      | 'skin'
+      | 'animation-clip'
+      | 'animation-graph'
+      | 'audio'
+      | 'font'
+      | 'render-pipeline'
+      | 'tileset'
+      | 'video'
+      | 'particle-effect'
+    >();
+  });
+});