@forgeax/engine-vfx 0.0.0-dev.8d955ade1c79

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@forgeax/engine-vfx",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Runtime-safe code-first GPU VFX source, asset loading, player intent, and fixed-tick GPU work contracts.",
+  "keywords": [
+    "vfx",
+    "gpu-particles",
+    "particle-effect-player",
+    "wgsl",
+    "fixed-update"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-assets-runtime": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-plugin": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "runtime contract package; no frame loop or canvas"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "GPU performance requires an adapter-qualified renderer benchmark, not the runtime contract package"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "public contract covered by package tests and workspace gates"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/authoring-descriptor.unit.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import { describeVfxGpuEffect, isVfxGpuEffectAsset } from '../authoring-descriptor.js';
+import type { VfxGpuEffectAsset } from '../gpu-program.js';
+import { VFX_GPU_PROGRAM_ARTIFACT_KEY, VFX_GPU_PROGRAM_FORMAT } from '../gpu-program.js';
+
+const effect: VfxGpuEffectAsset = {
+  guid: 'effect-guid',
+  kind: 'particle-effect',
+  schemaVersion: 2,
+  programFingerprint: 'sha256:effect',
+  emitters: [{ id: 'sparks', capacity: 128 }],
+  program: {
+    format: 'forgeax-vfx-program-2',
+    fingerprint: 'sha256:effect',
+    emitters: [
+      {
+        id: 'sparks',
+        module: 'sparks.vfx.wgsl',
+        capacity: 128,
+        backend: { required: 'gpu' },
+        space: 'world',
+        schedule: { rate: 8, bursts: [{ time: 0, count: 4 }], loopDuration: 2 },
+        bounds: { kind: 'sphere', center: [0, 1, 0], radius: 4 },
+        renderers: [
+          { kind: 'billboard', material: 'material-guid', sorting: 'back-to-front' },
+          { kind: 'beam', material: 'beam-material-guid', endpointField: 'velocity', capacity: 32 },
+        ],
+        channels: [{ id: 'impact', payload: 'impact', capacity: 8, overflow: 'drop-newest' }],
+        events: [
+          {
+            id: 'impact-event',
+            channel: 'impact',
+            subEmitter: 'sparks',
+            fanOut: 1,
+            recursionDepth: 1,
+          },
+        ],
+        simulationWhenCulled: 'continue',
+        wgsl: 'cooked',
+        reflection: {
+          hooks: ['vfx_spawn', 'vfx_update'],
+          imports: ['game::noise'],
+          resources: ['particles'],
+          entryPoints: ['forgeax_vfx_spawn_main'],
+          bindings: [],
+          layout: {
+            version: 1,
+            parameters: {
+              name: 'VfxParameters',
+              fields: [
+                {
+                  name: 'strength',
+                  type: 'f32',
+                  offset: 0,
+                  size: 4,
+                  alignment: 4,
+                  defaultValue: 1,
+                },
+              ],
+              size: 16,
+              alignment: 16,
+            },
+            custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+            fingerprint: 'sha256:layout',
+          },
+          stages: [
+            {
+              id: 'turbulence',
+              entry: 'vfx_turbulence',
+              entryPoint: 'forgeax_vfx_stage_turbulence',
+              domain: 'particle',
+              resources: [{ name: 'particles', access: 'read-write' }],
+              dependsOn: [],
+              iterationBudget: 2,
+            },
+          ],
+        },
+      },
+    ],
+  },
+};
+
+describe('VFX authoring descriptor', () => {
+  it('keeps the complete program format and asset-local artifact key canonical', () => {
+    expect(VFX_GPU_PROGRAM_FORMAT).toBe('forgeax-vfx-program-2');
+    expect(VFX_GPU_PROGRAM_ARTIFACT_KEY).toBe('particle-effect/program.json');
+    expect(effect.program.format).toBe(VFX_GPU_PROGRAM_FORMAT);
+    expect(effect.programFingerprint).toMatch(/^sha256:/);
+  });
+
+  it('owns the cooked asset type guard at the producer boundary', () => {
+    expect(isVfxGpuEffectAsset(effect)).toBe(true);
+    expect(
+      isVfxGpuEffectAsset({ ...effect, program: { ...effect.program, format: 'legacy' } }),
+    ).toBe(false);
+    expect(isVfxGpuEffectAsset({ kind: 'particle-effect', schemaVersion: 2 })).toBe(false);
+  });
+  it('projects one producer-owned system tree, timeline, dependencies, and capability truth', () => {
+    const descriptor = describeVfxGpuEffect(effect);
+
+    expect(descriptor).toMatchObject({
+      version: 1,
+      assetGuid: 'effect-guid',
+      artifactFingerprint: 'sha256:effect',
+      timeline: [{ emitterId: 'sparks', rate: 8, loopDuration: 2 }],
+    });
+    expect(descriptor.emitters[0]).toMatchObject({
+      id: 'emitter:sparks',
+      role: 'emitter',
+      label: 'sparks',
+      module: 'sparks.vfx.wgsl',
+    });
+    expect(descriptor.emitters[0]?.children.map((node) => node.role)).toEqual([
+      'program',
+      'parameters',
+      'stage',
+      'channel',
+      'event',
+      'renderer',
+      'renderer',
+    ]);
+    expect(descriptor.dependencies).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ kind: 'module', identity: 'sparks.vfx.wgsl' }),
+        expect.objectContaining({ kind: 'asset', identity: 'material-guid' }),
+        expect.objectContaining({ kind: 'asset', identity: 'beam-material-guid' }),
+        expect.objectContaining({ kind: 'module', identity: 'game::noise' }),
+      ]),
+    );
+    expect(descriptor.capabilities).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ id: 'runtime-parameters', state: 'partial' }),
+        expect.objectContaining({ id: 'deterministic-replay', state: 'executable' }),
+      ]),
+    );
+    expect(JSON.stringify(descriptor)).not.toContain('wgsl":"cooked');
+  });
+});

package/src/__tests__/channel-input.unit.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { createVfxEffectContract } from '../effect-contract.js';
+import { ParticleEffectInstance, type VfxChannelInput } from '../instance.js';
+
+const reflection = {
+  version: 1,
+  parameters: { name: 'VfxParameters', fields: [], size: 0, alignment: 1 },
+  custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+  fingerprint: 'sha256:channel-input',
+} as const;
+
+function instance() {
+  return new ParticleEffectInstance(createVfxEffectContract(reflection));
+}
+
+function input(sequence: number, strength: number): VfxChannelInput {
+  return {
+    channel: 'impact',
+    payload: { position: [sequence, 1, 0], strength },
+    sequence,
+  };
+}
+
+describe('VFX channel input', () => {
+  it('commits typed inputs once at the fixed-tick boundary in sequence order', () => {
+    const effect = instance();
+
+    expect(effect.submit(input(2, 0.4)).ok).toBe(true);
+    expect(effect.submit(input(1, 0.9)).ok).toBe(true);
+    const committed = effect.commit({ seed: 3, tick: 8 });
+
+    expect(committed.ok).toBe(true);
+    if (!committed.ok) return;
+    expect(committed.value.channelInputs).toEqual([input(1, 0.9), input(2, 0.4)]);
+    expect(committed.value.channelInputs[0]?.tick).toBe(8);
+  });
+
+  it('drops new input at capacity without changing another instance', () => {
+    const first = instance();
+    const second = instance();
+    first.setChannelCapacity('impact', 1);
+
+    expect(first.submit(input(1, 0.5)).ok).toBe(true);
+    const overflow = first.submit(input(2, 0.6));
+    expect(overflow.ok).toBe(false);
+    if (!overflow.ok) expect(overflow.error.code).toBe('vfx-channel-overflow');
+    expect(second.submit(input(1, 0.7)).ok).toBe(true);
+    const firstCommit = first.commit({ seed: 1, tick: 1 });
+    const secondCommit = second.commit({ seed: 2, tick: 1 });
+    expect(firstCommit.ok && firstCommit.value).toMatchObject({ droppedCount: 1 });
+    expect(secondCommit.ok && secondCommit.value).toMatchObject({ droppedCount: 0 });
+  });
+
+  it('clears pending inputs on despawn/reset and preserves replay ordering', () => {
+    const effect = instance();
+    effect.submit(input(4, 1));
+    const committed = effect.commit({ seed: 4, tick: 3 });
+    expect(committed.ok).toBe(true);
+    if (!committed.ok) return;
+    const replay = instance().replay(committed.value.replayInput);
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) return;
+    expect(replay.value.channelInputs).toEqual(committed.value.channelInputs);
+  });
+});

package/src/__tests__/channel-inspect.unit.test.ts

@@ -0,0 +1,65 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { VfxGpuRuntime } from '../gpu-runtime.js';
+
+const player = 7 as EntityHandle;
+
+describe('VFX channel inspect counters', () => {
+  it('keeps bounded event counters observable without GPU readback', () => {
+    const runtime = new VfxGpuRuntime();
+    runtime.markEventDispatched(player, {
+      queued: 4,
+      produced: 4,
+      consumed: 0,
+      dropped: 2,
+      overflow: 1,
+      fanOut: 2,
+      recursionDepth: 1,
+      lastSequence: 9,
+    });
+
+    expect(runtime.eventCounters(player)).toEqual({
+      queued: 0,
+      produced: 4,
+      consumed: 4,
+      dropped: 2,
+      overflow: 1,
+      fanOut: 2,
+      recursionDepth: 1,
+      lastSequence: 9,
+    });
+  });
+
+  it('merges a consumer dispatch into the producer snapshot', () => {
+    const runtime = new VfxGpuRuntime();
+    runtime.markEventDispatched(player, {
+      queued: 1,
+      produced: 1,
+      consumed: 0,
+      dropped: 0,
+      overflow: 0,
+      fanOut: 2,
+      recursionDepth: 1,
+      lastSequence: 3,
+    });
+    runtime.markEventDispatched(player, {
+      queued: 1,
+      produced: 0,
+      consumed: 2,
+      dropped: 0,
+      overflow: 0,
+      fanOut: 2,
+      recursionDepth: 1,
+      lastSequence: 3,
+    });
+
+    expect(runtime.eventCounters(player)).toMatchObject({
+      queued: 0,
+      produced: 1,
+      consumed: 2,
+      fanOut: 2,
+      recursionDepth: 1,
+      lastSequence: 3,
+    });
+  });
+});

package/src/__tests__/channel-overflow-policy-owner.test-d.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+  ParticleChannelOverflowPolicy,
+  ParticleChannelSource,
+  ParticleRendererOverflowPolicy,
+  ParticleRendererSource,
+} from '../code-source.js';
+import type {
+  ParticleChannelOverflowPolicy as PublicParticleChannelOverflowPolicy,
+  ParticleRendererOverflowPolicy as PublicParticleRendererOverflowPolicy,
+} from '../index.js';
+
+type BillboardRenderer = Extract<ParticleRendererSource, { readonly kind: 'billboard' }>;
+type RendererOverflow = BillboardRenderer['overflow'];
+type ChannelOverflow = ParticleChannelSource['overflow'];
+type RendererOverflowSlot = Pick<BillboardRenderer, 'overflow'>;
+type ChannelOverflowSlot = Pick<ParticleChannelSource, 'overflow'>;
+
+const codeSource = readFileSync(new URL('../code-source.ts', import.meta.url), 'utf8');
+
+describe('VFX channel overflow policy owner', () => {
+  it('derives the channel policy from the renderer policy without changing field presence', () => {
+    expectTypeOf<ParticleChannelOverflowPolicy>().toEqualTypeOf<ParticleRendererOverflowPolicy>();
+    expectTypeOf<ParticleRendererOverflowPolicy>().toEqualTypeOf<ParticleChannelOverflowPolicy>();
+    expectTypeOf<PublicParticleChannelOverflowPolicy>().toEqualTypeOf<ParticleChannelOverflowPolicy>();
+    expectTypeOf<PublicParticleRendererOverflowPolicy>().toEqualTypeOf<ParticleRendererOverflowPolicy>();
+    expectTypeOf<RendererOverflow>().toEqualTypeOf<ParticleRendererOverflowPolicy | undefined>();
+    expectTypeOf<ParticleRendererOverflowPolicy | undefined>().toEqualTypeOf<RendererOverflow>();
+    expectTypeOf<ChannelOverflow>().toEqualTypeOf<ParticleChannelOverflowPolicy>();
+    expectTypeOf<ParticleChannelOverflowPolicy>().toEqualTypeOf<ChannelOverflow>();
+    expectTypeOf<RendererOverflowSlot>().toEqualTypeOf<{
+      readonly overflow?: ParticleRendererOverflowPolicy;
+    }>();
+    expectTypeOf<ChannelOverflowSlot>().toEqualTypeOf<{
+      readonly overflow: ParticleChannelOverflowPolicy;
+    }>();
+  });
+
+  it('keeps exactly the drop-newest and drop-oldest members', () => {
+    expectTypeOf<ParticleChannelOverflowPolicy>().toEqualTypeOf<'drop-newest' | 'drop-oldest'>();
+    expectTypeOf<'drop-newest'>().toExtend<ParticleChannelOverflowPolicy>();
+    expectTypeOf<'drop-oldest'>().toExtend<ParticleChannelOverflowPolicy>();
+    expectTypeOf<'drop-other'>().not.toExtend<ParticleChannelOverflowPolicy>();
+  });
+
+  it('keeps the authored renderer policy as the only production owner', () => {
+    expect(codeSource).toContain(
+      'export type ParticleChannelOverflowPolicy = ParticleRendererOverflowPolicy;',
+    );
+    expect(codeSource).not.toContain(
+      "export type ParticleChannelOverflowPolicy = 'drop-newest' | 'drop-oldest';",
+    );
+  });
+});

package/src/__tests__/code-source-v2.unit.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import { parseParticleEffectSourceV2, parseVfxStageDeclarations } from '../code-source.js';
+
+const source = {
+  schemaVersion: 2,
+  emitters: [
+    {
+      id: 'sparks',
+      capacity: 1024,
+      backend: { required: 'gpu' as const },
+      space: 'world',
+      schedule: { rate: 32, bursts: [{ time: 0, count: 16 }], loopDuration: 2 },
+      bounds: { kind: 'aabb', min: [-10, -10, -10], max: [10, 10, 10] },
+      program: { module: 'sparks.vfx.wgsl' },
+      renderers: [{ kind: 'billboard', material: 'material-guid' }],
+    },
+  ],
+};
+
+describe('ParticleCodeEffectSource v2', () => {
+  it('accepts typed bounded channels and same-effect visual events', () => {
+    const result = parseParticleEffectSourceV2({
+      ...source,
+      emitters: [
+        {
+          ...source.emitters[0],
+          channels: [{ id: 'impact', capacity: 2, overflow: 'drop-newest' }],
+          events: [
+            {
+              id: 'impact-event',
+              channel: 'impact',
+              subEmitter: 'sparks',
+              fanOut: 1,
+              recursionDepth: 1,
+            },
+          ],
+        },
+      ],
+    });
+    expect(result.ok).toBe(true);
+  });
+
+  it('accepts the code-first source without an operator stack', () => {
+    const result = parseParticleEffectSourceV2(source);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.emitters[0]?.program.module).toBe('sparks.vfx.wgsl');
+    }
+  });
+
+  it('keeps stage declarations in authored WGSL rather than the source manifest', () => {
+    const stage = parseVfxStageDeclarations(
+      '// #vfx stage turbulence entry=vfx_turbulence domain=particle resources=particles:read-write dependsOn=update iterationBudget=4',
+    );
+    expect(stage.ok).toBe(true);
+  });
+
+  it('rejects v1 with an executable recook hint', () => {
+    const result = parseParticleEffectSourceV2({ schemaVersion: 1, emitters: [] });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('vfx-source-version-unsupported');
+      expect(result.error.hint).toContain('WGSL');
+      expect(result.error.hint).toContain('recook');
+    }
+  });
+
+  it('requires one explicit GPU backend policy and rejects derived fields', () => {
+    const backend = structuredClone(source) as unknown as {
+      emitters: Array<Record<string, unknown>>;
+    };
+    const emitter = backend.emitters[0];
+    expect(emitter).toBeDefined();
+    if (emitter === undefined) return;
+    emitter.backend = { required: 'cpu' };
+    expect(parseParticleEffectSourceV2(backend).ok).toBe(false);
+    const derived = structuredClone(source) as typeof source & { backendPlan: string };
+    derived.backendPlan = 'gpu';
+    expect(parseParticleEffectSourceV2(derived).ok).toBe(false);
+  });
+
+  it.each([
+    ['bounds', { bounds: { kind: 'sphere', center: [0, 0, 0], radius: 1, dynamic: true } }],
+    ['schedule', { schedule: { rate: 1, legacyRate: 2 } }],
+    ['burst', { schedule: { rate: 1, bursts: [{ time: 0, count: 1, once: true }] } }],
+    ['program', { program: { module: 'sparks.vfx.wgsl', fallback: 'cpu' } }],
+    ['parameters', { parameters: { speed: 1 } }],
+    ['custom data', { customData: { value: 1 } }],
+  ])('rejects unknown nested %s fields', (_name, override) => {
+    const emitter = { ...source.emitters[0], ...override };
+    expect(parseParticleEffectSourceV2({ ...source, emitters: [emitter] }).ok).toBe(false);
+  });
+
+  it('keeps Data Interface requirements out of the source-side roster', () => {
+    const emitter = {
+      ...source.emitters[0],
+      dataInterfaces: [{ token: 'vfx:camera' }],
+    };
+    expect(parseParticleEffectSourceV2({ ...source, emitters: [emitter] }).ok).toBe(false);
+  });
+
+  it('accepts an explicit mesh submesh and rejects ambiguous indices', () => {
+    const mesh = structuredClone(source) as unknown as {
+      schemaVersion: number;
+      emitters: Array<Record<string, unknown>>;
+    };
+    const emitter = mesh.emitters[0];
+    expect(emitter).toBeDefined();
+    if (emitter === undefined) return;
+    const renderers: Array<Record<string, unknown>> = [
+      { kind: 'mesh', material: 'material-guid', mesh: 'mesh-guid', submesh: 2 },
+    ];
+    emitter.renderers = renderers;
+    expect(parseParticleEffectSourceV2(mesh).ok).toBe(true);
+    const renderer = renderers[0];
+    expect(renderer).toBeDefined();
+    if (renderer === undefined) return;
+    renderer.submesh = -1;
+    expect(parseParticleEffectSourceV2(mesh).ok).toBe(false);
+  });
+});

package/src/__tests__/data-interface-contract.unit.test.ts

@@ -0,0 +1,92 @@
+import { ok, type Result } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  resolveVfxDataInterfaces,
+  type VfxDataInterfaceError,
+  type VfxDataInterfaceProvider,
+  type VfxDataInterfaceRequirement,
+  type VfxDataInterfaceResource,
+} from '../index.js';
+
+const camera: VfxDataInterfaceRequirement = {
+  token: 'vfx:camera',
+  kind: 'camera',
+  binding: 8,
+  bindingType: 'uniform',
+  lifetime: 'generation',
+};
+
+function provider(
+  resource: Omit<VfxDataInterfaceResource, 'generation'> & { readonly generation?: number },
+): VfxDataInterfaceProvider {
+  return {
+    id: `${resource.token}-provider`,
+    token: resource.token,
+    kind: resource.kind,
+    bindingType: resource.bindingType,
+    provide: (generation) =>
+      ok({
+        ...resource,
+        generation: resource.generation ?? generation,
+      }),
+  };
+}
+
+describe('VFX Data Interface contract', () => {
+  it.each([
+    ['missing', [], 'vfx-data-interface-missing'],
+    [
+      'wrong type',
+      [provider({ token: 'vfx:camera', kind: 'camera', bindingType: 'sampled-depth' })],
+      'vfx-data-interface-wrong-type',
+    ],
+    [
+      'stale generation',
+      [provider({ token: 'vfx:camera', kind: 'camera', bindingType: 'uniform', generation: 2 })],
+      'vfx-data-interface-stale',
+    ],
+  ])('%s is a structured failure', (_name, providers, code) => {
+    const result = resolveVfxDataInterfaces([camera], providers as VfxDataInterfaceProvider[], 3);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe(code);
+      if (code === 'vfx-data-interface-stale') {
+        expect(result.error.expected).toContain('generation 3');
+      } else {
+        expect(result.error.expected).toContain('camera');
+      }
+      expect(result.error.hint.length).toBeGreaterThan(0);
+      expect(result.error.detail).toMatchObject({ token: 'vfx:camera' });
+    }
+  });
+
+  it('returns generation-scoped readiness for a valid provider', () => {
+    const result = resolveVfxDataInterfaces(
+      [camera],
+      [provider({ token: 'vfx:camera', kind: 'camera', bindingType: 'uniform' })],
+      7,
+    );
+    expect(result).toMatchObject({ ok: true, value: { generation: 7, readiness: 'ready' } });
+  });
+
+  it('keeps provider failures exhaustive without parsing messages', () => {
+    const result: Result<unknown, VfxDataInterfaceError> = resolveVfxDataInterfaces(
+      [camera],
+      [],
+      1,
+    );
+    if (!result.ok) {
+      switch (result.error.code) {
+        case 'vfx-data-interface-missing':
+        case 'vfx-data-interface-wrong-type':
+        case 'vfx-data-interface-stale':
+        case 'vfx-data-interface-duplicate':
+          break;
+        default: {
+          const exhaustive: never = result.error.code;
+          expect(exhaustive).toBeUndefined();
+        }
+      }
+    }
+  });
+});

package/src/__tests__/effect-contract.unit.test.ts

@@ -0,0 +1,62 @@
+import type { ParticleEffectAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createVfxEffectContract } from '../effect-contract.js';
+
+const reflection = {
+  version: 1,
+  parameters: {
+    name: 'VfxParameters',
+    fields: [
+      { name: 'direction', type: 'vec3<f32>', offset: 0, size: 12, alignment: 16 },
+      { name: 'speed', type: 'f32', offset: 16, size: 4, alignment: 4 },
+    ],
+    size: 32,
+    alignment: 16,
+  },
+  custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+  fingerprint: 'sha256:0000000000000000000000000000000000000000000000000000000000000000',
+} as const;
+
+describe('VfxEffectContract', () => {
+  it('models the executable program on the ordinary particle asset', () => {
+    const asset: ParticleEffectAsset = {
+      kind: 'particle-effect',
+      schemaVersion: 2,
+      programFingerprint: 'sha256:program',
+      emitters: [{ id: 'sparks', capacity: 8 }],
+      program: {
+        format: 'forgeax-vfx-program-2',
+        fingerprint: 'sha256:program',
+        emitters: [],
+      },
+    };
+    expect(asset.program.fingerprint).toBe(asset.programFingerprint);
+  });
+
+  it('derives defaults and packed values from the same reflection result', () => {
+    const contract = createVfxEffectContract(reflection);
+    const values = contract.createValues({ speed: 2.5, direction: [0, 1, 0] });
+    expect(values.ok).toBe(true);
+    if (!values.ok) return;
+    expect(values.value.speed).toBe(2.5);
+    expect(values.value.direction).toEqual([0, 1, 0]);
+    expect(contract.pack(values.value).ok).toBe(true);
+    expect(contract.fingerprint).toBe(reflection.fingerprint);
+  });
+
+  it('rejects unknown names, wrong dimensions, and wrong scalar kinds without assertions', () => {
+    const contract = createVfxEffectContract(reflection);
+
+    const unknown = contract.createValues({ missing: 1 });
+    expect(unknown.ok).toBe(false);
+    if (!unknown.ok) expect(unknown.error.code).toBe('vfx-value-unknown-field');
+
+    const wrongDimension = contract.createValues({ direction: [0, 1] });
+    expect(wrongDimension.ok).toBe(false);
+    if (!wrongDimension.ok) expect(wrongDimension.error.code).toBe('vfx-value-type-mismatch');
+
+    const wrongScalar = contract.validateValues(JSON.parse('{"speed":"fast"}'));
+    expect(wrongScalar.ok).toBe(false);
+    if (!wrongScalar.ok) expect(wrongScalar.error.code).toBe('vfx-value-type-mismatch');
+  });
+});