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

package/src/__tests__/world-managed-roundtrip.unit.test.ts

@@ -0,0 +1,98 @@
+// feat-20260614-ecs-shared-component-and-unique-rename M6 w52 (AC-31, R-14):
+// write-barrier slot-range short-circuit.
+//
+// D-15: builtin asset handles (slot < BUILTIN_BASE, e.g. HANDLE_CUBE=1) are
+// process-static and NEVER reference-counted. The ECS write barrier for
+// `shared<T>` columns must short-circuit on builtin slots: retain/release on a
+// builtin handle makes ZERO calls to World.sharedRefs and never surfaces a
+// SharedRefReleasedError / BuiltinSlotNotOwnedError. R-14 requires the
+// short-circuit cover BOTH the scalar `shared<T>` arm AND the
+// `array<shared<T>>` element dispatch (single helper SSOT).
+//
+// User-tier handles (slot >= BUILTIN_BASE, minted by allocSharedRef) keep
+// flowing through World.sharedRefs as before.
+
+import { BUILTIN_BASE, toShared } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { type Component, defineComponent } from '../component';
+import { World } from '../world';
+
+// HANDLE_CUBE's runtime slot (1) — a builtin-tier handle constructed without
+// importing @forgeax/engine-runtime (ecs must not depend on runtime).
+const BUILTIN_HANDLE = toShared<'MeshAsset'>(1);
+
+describe('M6 w52: write-barrier builtin-slot short-circuit (AC-31 / R-14)', () => {
+  it('scalar shared<T> field = builtin handle: spawn retains 0 calls + no error', () => {
+    const Holder = defineComponent('W52ScalarHolder', { asset: { type: 'shared<MeshAsset>' } });
+    const w = new World();
+    const retainSpy = vi.spyOn(w.sharedRefs, 'retain');
+    const releaseSpy = vi.spyOn(w.sharedRefs, 'release');
+
+    const e = w
+      .spawn({
+        component: Holder as unknown as Component,
+        data: { asset: BUILTIN_HANDLE } as never,
+      })
+      .unwrap();
+    // spawn write-barrier must short-circuit on the builtin slot.
+    expect(retainSpy).not.toHaveBeenCalled();
+
+    w.despawn(e).unwrap();
+    // despawn write-barrier must short-circuit on the builtin slot.
+    expect(releaseSpy).not.toHaveBeenCalled();
+  });
+
+  it('array<shared<T>> field = [builtin handle]: retain/release 0 calls, no SharedRefReleasedError (R-14)', () => {
+    const Holder = defineComponent('W52ArrayHolder', {
+      assets: { type: 'array<shared<MeshAsset>>' },
+    });
+    const w = new World();
+    const retainSpy = vi.spyOn(w.sharedRefs, 'retain');
+    const releaseSpy = vi.spyOn(w.sharedRefs, 'release');
+
+    const e = w
+      .spawn({
+        component: Holder as unknown as Component,
+        data: { assets: [BUILTIN_HANDLE, BUILTIN_HANDLE] } as never,
+      })
+      .unwrap();
+    expect(retainSpy).not.toHaveBeenCalled();
+
+    expect(() => w.despawn(e).unwrap()).not.toThrow();
+    expect(releaseSpy).not.toHaveBeenCalled();
+  });
+
+  it('user-tier scalar handle still flows through World.sharedRefs (retain on spawn)', () => {
+    const Holder = defineComponent('W52UserScalarHolder', {
+      asset: { type: 'shared<MeshAsset>' },
+    });
+    const w = new World();
+    const userHandle = w.allocSharedRef('MeshAsset', { kind: 'mesh' });
+    expect(userHandle).toBeGreaterThanOrEqual(BUILTIN_BASE);
+    const retainSpy = vi.spyOn(w.sharedRefs, 'retain');
+
+    w.spawn({
+      component: Holder as unknown as Component,
+      data: { asset: userHandle } as never,
+    }).unwrap();
+    // user-tier handle is retained by the write barrier (rc 1 -> 2).
+    expect(retainSpy).toHaveBeenCalled();
+    expect(w.sharedRefs.refcount(userHandle)).toBe(2);
+  });
+
+  it('user-tier array element still flows through World.sharedRefs (R-14 control)', () => {
+    const Holder = defineComponent('W52UserArrayHolder', {
+      assets: { type: 'array<shared<MeshAsset>>' },
+    });
+    const w = new World();
+    const userHandle = w.allocSharedRef('MeshAsset', { kind: 'mesh' });
+    const retainSpy = vi.spyOn(w.sharedRefs, 'retain');
+
+    w.spawn({
+      component: Holder as unknown as Component,
+      data: { assets: [userHandle] } as never,
+    }).unwrap();
+    expect(retainSpy).toHaveBeenCalled();
+    expect(w.sharedRefs.refcount(userHandle)).toBe(2);
+  });
+});

package/src/__tests__/world-scheduling.m4.test.ts

@@ -0,0 +1,52 @@
+import { err } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { SystemFailedError } from '../errors';
+import { FixedUpdate, Update, World } from '../index';
+
+describe('M4 world scheduling failure boundary', () => {
+  it('stops the frame and poisons the World when a system throws', () => {
+    const world = new World();
+    world.addSystem(Update, {
+      name: 'thrower',
+      queries: [],
+      fn: () => {
+        throw new Error('system');
+      },
+    });
+
+    const result = world.update(1 / 60);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toBeInstanceOf(SystemFailedError);
+    expect(world.execution.health).toBe('poisoned');
+    expect(world.update(1 / 60).ok).toBe(false);
+  });
+
+  it('poisons a frame when a system returns an expected command failure', () => {
+    const world = new World();
+    const failure = new Error('command failure');
+    world.addSystem(Update, { name: 'result-failure', queries: [], fn: () => err(failure) });
+
+    const result = world.update();
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(SystemFailedError);
+      expect((result.error as SystemFailedError).detail.cause).toBe(failure);
+    }
+    expect(world.execution.health).toBe('poisoned');
+  });
+
+  it('advances the clock only for a successful frame and keeps fixed order stable', () => {
+    const world = new World({ time: { fixedDeltaSeconds: 0.01, maxStepsPerUpdate: 4 } });
+    const order: string[] = [];
+    world.addSystem(Update, { name: 'update', queries: [], fn: () => order.push('update') });
+    world.addSystem(FixedUpdate, {
+      name: 'fixed',
+      queries: [],
+      fn: () => order.push('fixed'),
+    });
+
+    expect(world.update(0.02).ok).toBe(true);
+    expect(order).toEqual(['update', 'fixed', 'fixed']);
+    expect(world.getResource<{ elapsed: number }>('Time').elapsed).toBeCloseTo(0.02);
+  });
+});

package/src/__tests__/world-unique-roundtrip.unit.test.ts

@@ -0,0 +1,357 @@
+// feat-20260614-ecs-managed-lifecycle-ssot M2 t-w3: world-level round-trip
+// net-zero matrix for managed-resource fields.
+//
+// Verifies AC-12 (requirements §5 / §8 boundary table): every release-dispatch
+// path on World must net-zero the BufferPool and UniqueRefStore live counters
+// after a spawn -> mutate -> tear-down cycle, for each managed-vocab keyword.
+//
+// Matrix: 4 vocab x 2 round shapes = 8 cases.
+//
+// Vocab dimensions (keyword family routed through releaseManagedFieldOnRow
+// after w4):
+//   - 'string'           -> UniqueRefStore handle (isManagedField arm)
+//   - 'unique<T>'           -> UniqueRefStore handle (isManagedField arm)
+//   - 'buffer'  variable -> BufferPool slot id    (isManagedBufferField arm)
+//   - 'array<T>' variable-> BufferPool slot id    (isManagedArrayField arm)
+//
+// Round shapes:
+//   (R1) spawn -> world.set(e, C, { f: v2 }) -> world.despawn(e)
+//   (R2) spawn -> world.removeComponent(e, C) -> world.addComponent(e, C, ...)
+//
+// R2 uses addComponent (not a second spawn) to stress the same release-dispatch
+// path that releaseManagedRefsOnRow walks (research Finding 1.2 row 4 / plan-
+// strategy §5.3 M2 key test).
+//
+// OOS-1: this test only exercises increment release on per-entity despawn /
+// per-component remove; it does NOT call any World.clear/dispose path. OOS-2:
+// SceneInstance state alloc/release at world.ts:3494/3522 are out of scope
+// for the helper (D-5) and not exercised here.
+//
+// TDD positioning: the round-trip invariant is already in place pre-w4 because
+// the dispatch is correct, only duplicated; w3 locks in the invariant before
+// the SSOT collapse so w4/w5 reviewers see it stays green through the refactor.
+
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type { BufferPool } from '../buffer-pool';
+import { type Component, defineComponent } from '../component';
+import type { SharedRefStore } from '../shared-ref-store';
+import type { UniqueRefStore } from '../unique-ref-store';
+import { World } from '../world';
+
+interface MaterialAsset {
+  albedo: [number, number, number, number];
+}
+
+interface WorldInternals {
+  uniqueRefs: UniqueRefStore;
+  sharedRefs: SharedRefStore;
+  bufferPool: BufferPool;
+}
+
+function refsOf(w: World): UniqueRefStore {
+  return (w as unknown as WorldInternals).uniqueRefs;
+}
+function poolOf(w: World): BufferPool {
+  return (w as unknown as WorldInternals).bufferPool;
+}
+function liveRefs(w: World): number {
+  return refsOf(w)._liveCount();
+}
+function liveSlots(w: World): number {
+  return poolOf(w)._liveCount();
+}
+
+// Allocates a fresh ref<MaterialAsset> handle inside the same World so the
+// round-trip ledger stays self-contained: every alloc must net-zero too.
+function allocMat(
+  w: World,
+  albedo: [number, number, number, number],
+): Handle<'MaterialAsset', 'unique'> {
+  return refsOf(w).alloc<'MaterialAsset', MaterialAsset>('MaterialAsset', { albedo });
+}
+
+interface RoundCase {
+  vocab: 'string' | 'unique<T>' | 'buffer' | 'array<T>';
+  Component: Component;
+  v1: () => unknown;
+  v2: () => unknown;
+  v3: () => unknown;
+}
+
+// Build the 4 vocab cases. Each defines a fresh component with one managed
+// field of that vocab keyword; the value generators v1/v2/v3 produce
+// distinct payloads so the set / addComponent paths actually mutate.
+function buildCases(w: World): RoundCase[] {
+  const StrName = defineComponent('RtStrName', { value: { type: 'string' } });
+  const Mat = defineComponent('RtMat', { material: { type: 'unique<MaterialAsset>' } });
+  const Buf = defineComponent('RtBuf', { bytes: { type: 'buffer' } });
+  const Arr = defineComponent('RtArr', { ids: { type: 'array<u32>' } });
+
+  return [
+    {
+      vocab: 'string',
+      Component: StrName as unknown as Component,
+      v1: () => 'alpha',
+      v2: () => 'beta',
+      v3: () => 'gamma',
+    },
+    {
+      vocab: 'unique<T>',
+      Component: Mat as unknown as Component,
+      // The ref<T> vocab requires alloc'ing a handle into the World's
+      // UniqueRefStore. The generators alloc inside the round (after the
+      // counter snapshot), so the closing despawn / set / removeComponent
+      // path must release them back to net-zero.
+      v1: () => allocMat(w, [1, 0, 0, 1]),
+      v2: () => allocMat(w, [0, 1, 0, 1]),
+      v3: () => allocMat(w, [0, 0, 1, 1]),
+    },
+    {
+      vocab: 'buffer',
+      Component: Buf as unknown as Component,
+      v1: () => new Uint8Array([1, 2, 3, 4]),
+      v2: () => new Uint8Array([5, 6, 7, 8, 9]),
+      v3: () => new Uint8Array([10]),
+    },
+    {
+      vocab: 'array<T>',
+      Component: Arr as unknown as Component,
+      v1: () => new Uint32Array([1, 2, 3]),
+      v2: () => new Uint32Array([4, 5, 6, 7]),
+      v3: () => new Uint32Array([8]),
+    },
+  ];
+}
+
+describe('world managed round-trip net-zero matrix (feat-20260614 M2 / AC-12)', () => {
+  describe('R1: spawn -> set -> despawn', () => {
+    for (const vocab of ['string', 'unique<T>', 'buffer', 'array<T>'] as const) {
+      it(`${vocab}: live counters net-zero after spawn -> set -> despawn`, () => {
+        const w = new World();
+        const cases = buildCases(w);
+        const c = cases.find((cs) => cs.vocab === vocab);
+        if (!c) throw new Error('case missing');
+
+        // Snapshot counters BEFORE any value generation. ref<T>'s value
+        // generator alloc's into the World's UniqueRefStore inside the
+        // round, so the round's full release-dispatch must net-zero those
+        // back to 0 by the end of despawn.
+        const refsBefore = liveRefs(w);
+        const slotsBefore = liveSlots(w);
+
+        const e = w
+          .spawn({ component: c.Component, data: { [fieldOf(c)]: c.v1() } as never })
+          .unwrap();
+        w.set(e, c.Component, { [fieldOf(c)]: c.v2() } as never).unwrap();
+        w.despawn(e).unwrap();
+
+        expect(liveRefs(w)).toBe(refsBefore);
+        expect(liveSlots(w)).toBe(slotsBefore);
+      });
+    }
+  });
+
+  describe('R2: spawn -> removeComponent -> addComponent', () => {
+    for (const vocab of ['string', 'unique<T>', 'buffer', 'array<T>'] as const) {
+      it(`${vocab}: live counters net-zero after spawn -> removeComponent -> addComponent`, () => {
+        const w = new World();
+        const cases = buildCases(w);
+        const c = cases.find((cs) => cs.vocab === vocab);
+        if (!c) throw new Error('case missing');
+
+        // Snapshot before any v1/v3 alloc so ref<T>'s allocator hits land
+        // inside the round; the closing despawn must release both the
+        // v1-released-by-removeComponent and the v3-installed-by-addComponent
+        // payloads to net-zero the counters.
+        const refsBefore = liveRefs(w);
+        const slotsBefore = liveSlots(w);
+
+        const e = w
+          .spawn({ component: c.Component, data: { [fieldOf(c)]: c.v1() } as never })
+          .unwrap();
+        w.removeComponent(e, c.Component).unwrap();
+        w.addComponent(e, {
+          component: c.Component,
+          data: { [fieldOf(c)]: c.v3() } as never,
+        } as never).unwrap();
+        w.despawn(e).unwrap();
+
+        expect(liveRefs(w)).toBe(refsBefore);
+        expect(liveSlots(w)).toBe(slotsBefore);
+      });
+    }
+  });
+});
+
+function fieldOf(c: RoundCase): string {
+  switch (c.vocab) {
+    case 'string':
+      return 'value';
+    case 'unique<T>':
+      return 'material';
+    case 'buffer':
+      return 'bytes';
+    case 'array<T>':
+      return 'ids';
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// M4 / w11 — array<shared<T>> element-level retain/release coverage
+//
+// Covers AC-09 (array<shared<T>> independent meta key + element-level
+// retain/release) + AC-11 (archetype migration net-zero).
+//
+// `array<shared<T>>` differs from `array<handle<T>>` in that the ECS owns
+// retain/release on each element; the holder writes the array, and the
+// SharedRefStore refcount is the SSOT for liveness. Five scenarios cover
+// the full element-level lifecycle:
+//   (S1) set elements → SharedRefStore.retain called once per element
+//   (S2) overwrite element set → prior elements release, new elements retain
+//   (S3) clear (set to empty array) → all current elements release
+//   (S4) archetype migration (add component triggers row move) → net-zero
+//   (S5) spawn → despawn → all array<shared<T>> elements release back to producer rc=1
+// ──────────────────────────────────────────────────────────────────────────
+
+interface SharedAsset {
+  tag: string;
+}
+
+function sharedRefsOf(w: World): SharedRefStore {
+  return (w as unknown as WorldInternals).sharedRefs;
+}
+
+function allocSharedAsset(w: World, tag: string): Handle<'SharedAsset', 'shared'> {
+  return w.allocSharedRef<'SharedAsset', SharedAsset>('SharedAsset', { tag });
+}
+
+describe('array<shared<T>> element-level retain/release (feat-20260614 M4 / AC-09 / AC-11)', () => {
+  it('S1: set elements → each element retained (rc=2 = producer alloc-grant + ECS retain)', () => {
+    const w = new World();
+    const Holder = defineComponent('S1Holder', { assets: { type: 'array<shared<SharedAsset>>' } });
+
+    const h1 = allocSharedAsset(w, 'a');
+    const h2 = allocSharedAsset(w, 'b');
+    expect(sharedRefsOf(w).refcount(h1)).toBe(1);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(1);
+
+    w.spawn({
+      component: Holder as unknown as Component,
+      data: { assets: [h1, h2] } as never,
+    }).unwrap();
+
+    // Each array element is retained once by the ECS write barrier.
+    expect(sharedRefsOf(w).refcount(h1)).toBe(2);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(2);
+  });
+
+  it('S2: overwrite array → prior elements released, new elements retained (net-zero rc on shared elements)', () => {
+    const w = new World();
+    const Holder = defineComponent('S2Holder', { assets: { type: 'array<shared<SharedAsset>>' } });
+
+    const h1 = allocSharedAsset(w, 'a');
+    const h2 = allocSharedAsset(w, 'b');
+    const h3 = allocSharedAsset(w, 'c');
+
+    const e = w
+      .spawn({ component: Holder as unknown as Component, data: { assets: [h1, h2] } as never })
+      .unwrap();
+
+    // After spawn: h1.rc=2, h2.rc=2, h3.rc=1.
+    expect(sharedRefsOf(w).refcount(h1)).toBe(2);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(2);
+    expect(sharedRefsOf(w).refcount(h3)).toBe(1);
+
+    // Overwrite to [h3]. h1+h2 lose their ECS-retain, h3 gains it.
+    w.set(e, Holder as unknown as Component, { assets: [h3] } as never).unwrap();
+
+    expect(sharedRefsOf(w).refcount(h1)).toBe(1);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(1);
+    expect(sharedRefsOf(w).refcount(h3)).toBe(2);
+  });
+
+  it('S3: clear (set to empty array) → all current elements released', () => {
+    const w = new World();
+    const Holder = defineComponent('S3Holder', { assets: { type: 'array<shared<SharedAsset>>' } });
+
+    const h1 = allocSharedAsset(w, 'a');
+    const h2 = allocSharedAsset(w, 'b');
+
+    const e = w
+      .spawn({ component: Holder as unknown as Component, data: { assets: [h1, h2] } as never })
+      .unwrap();
+
+    expect(sharedRefsOf(w).refcount(h1)).toBe(2);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(2);
+
+    w.set(e, Holder as unknown as Component, { assets: [] } as never).unwrap();
+
+    // ECS-retain released on both; producer alloc-grant remains.
+    expect(sharedRefsOf(w).refcount(h1)).toBe(1);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(1);
+  });
+
+  it('S4: archetype migration (addComponent triggers row move) → element rc net-zero across migration', () => {
+    const w = new World();
+    const Holder = defineComponent('S4Holder', { assets: { type: 'array<shared<SharedAsset>>' } });
+    const Tag = defineComponent('S4Tag', { v: { type: 'u32' } });
+
+    const h1 = allocSharedAsset(w, 'a');
+    const h2 = allocSharedAsset(w, 'b');
+
+    const e = w
+      .spawn({ component: Holder as unknown as Component, data: { assets: [h1, h2] } as never })
+      .unwrap();
+
+    const before1 = sharedRefsOf(w).refcount(h1);
+    const before2 = sharedRefsOf(w).refcount(h2);
+    expect(before1).toBe(2);
+    expect(before2).toBe(2);
+
+    // addComponent triggers archetype migration (row swap-pop into a new
+    // archetype). The shared-array column bytes move with the row; the
+    // element refcount must NOT shift — this is the net-zero invariant
+    // (AC-11). Migration copies the slot id, no new retain/release.
+    w.addComponent(e, {
+      component: Tag as unknown as Component,
+      data: { v: 7 } as never,
+    } as never).unwrap();
+
+    expect(sharedRefsOf(w).refcount(h1)).toBe(before1);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(before2);
+
+    // removeComponent migrates back; still net-zero.
+    w.removeComponent(e, Tag as unknown as Component).unwrap();
+    expect(sharedRefsOf(w).refcount(h1)).toBe(before1);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(before2);
+  });
+
+  it('S5: spawn → despawn round-trip → all array<shared<T>> elements release back to producer rc=1', () => {
+    const w = new World();
+    const Holder = defineComponent('S5Holder', { assets: { type: 'array<shared<SharedAsset>>' } });
+
+    const h1 = allocSharedAsset(w, 'a');
+    const h2 = allocSharedAsset(w, 'b');
+    const h3 = allocSharedAsset(w, 'c');
+
+    const e = w
+      .spawn({
+        component: Holder as unknown as Component,
+        data: { assets: [h1, h2, h3] } as never,
+      })
+      .unwrap();
+
+    expect(sharedRefsOf(w).refcount(h1)).toBe(2);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(2);
+    expect(sharedRefsOf(w).refcount(h3)).toBe(2);
+
+    w.despawn(e).unwrap();
+
+    // Despawn releases the ECS-retain on every element; producer alloc-grant
+    // (rc=1) survives so consumers (e.g. AssetRegistry) keep ownership.
+    expect(sharedRefsOf(w).refcount(h1)).toBe(1);
+    expect(sharedRefsOf(w).refcount(h2)).toBe(1);
+    expect(sharedRefsOf(w).refcount(h3)).toBe(1);
+  });
+});

package/src/__tests__/world.test-d.ts

@@ -0,0 +1,156 @@
+// feat-20260517-spawn-default-fallback / M2 / t6.
+//
+// Compile-time type assertions for the `ComponentData<S>['data']` surface
+// after the M2 widening + the spawn mapped-tuple primary-inference probe.
+//
+// Three pinned invariants (Red until t9 lands):
+//
+//   (a) ComponentData<S>['data'] === Partial<ShapeOf<S>>      — AC-01
+//       The shared field bridge between `world.spawn` / `world.addComponent`
+//       / overrides; widening from ShapeOf<S> to Partial<ShapeOf<S>> is the
+//       single physical edit that takes the whole route off the ts(2739)
+//       cliff (AC-02).
+//
+//   (b) `world.spawn({ component: Camera, data: { fov, aspect, near, far } })`
+//       compiles                                              — AC-02
+//       hello-window:93 baseline. With ShapeOf<S> the same call reports
+//       ts(2739) "missing 5 properties"; with Partial<ShapeOf<S>> it
+//       compiles (and at runtime layer-2 / layer-3 fallback fills the
+//       remaining fields).
+//
+//   (c) `data: { fov: 'bad' }` fires field-level TS2322           — AC-03
+//       Mapped-tuple primary inference must NOT degrade after the
+//       widening: the wrong-VALUE case continues to surface as
+//       TS2322 ("Type 'string' is not assignable to type 'number'")
+//       directly on the offending key — NOT as the "No overload matches"
+//       wall the legacy fallback overload would fall back to (C-4).
+//
+// AI users grep `// @ts-expect-error AC-` here to find the regression
+// barrier that protects the mapped-tuple primary-inference behaviour
+// across TS upgrades (R-1 / plan-strategy §2.7 P3).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { defineComponent, type SchemaOf, type ShapeOf } from '../component';
+import { type ComponentData, World } from '../world';
+
+// Shared schema fixture — mirrors the runtime Camera token (9 f32) without
+// pulling @forgeax/engine-runtime in.
+const CameraLike = defineComponent('CameraLike', {
+  fov: { type: 'f32' },
+  aspect: { type: 'f32' },
+  near: { type: 'f32' },
+  far: { type: 'f32' },
+  projection: { type: 'f32' },
+  left: { type: 'f32' },
+  right: { type: 'f32' },
+  bottom: { type: 'f32' },
+  top: { type: 'f32' },
+});
+
+type CameraLikeSchema = SchemaOf<typeof CameraLike>;
+
+describe('ComponentData<S>.data — Partial<ShapeOf<S>> (AC-01, t6.a)', () => {
+  it('ComponentData<S>["data"] equals Partial<ShapeOf<S>>', () => {
+    type DataField = ComponentData<CameraLikeSchema>['data'];
+    expectTypeOf<DataField>().toEqualTypeOf<Partial<ShapeOf<CameraLikeSchema>>>();
+  });
+
+  it('ComponentData<S>["data"] is NOT the un-Partial ShapeOf<S>', () => {
+    type DataField = ComponentData<CameraLikeSchema>['data'];
+    // The wider Partial<ShapeOf<S>> is assignable to itself but the
+    // narrower ShapeOf<S> would need every key. After M2 widening,
+    // a Partial value is assignable to DataField; before M2 the same
+    // Partial is rejected by ShapeOf<S>'s required-keys contract.
+    const partial: Partial<ShapeOf<CameraLikeSchema>> = { fov: 1 };
+    const field: DataField = partial;
+    void field;
+  });
+
+  it('ComponentData<S>["data"] is NOT widened to any', () => {
+    type DataField = ComponentData<CameraLikeSchema>['data'];
+    expectTypeOf<DataField>().not.toBeAny();
+  });
+});
+
+describe('world.spawn — partial data accepted (AC-02, t6.b)', () => {
+  it('hello-window-shape 4-field call compiles after M2 widening', () => {
+    const w = new World();
+    // The hello-window:93 baseline call: drop the 5 ortho fields on a
+    // perspective spawn. Before M2 this fires ts(2739) ("missing 5
+    // properties"); after M2 it compiles and runtime layer-2 / layer-3
+    // fallback fills the missing fields.
+    const r = w.spawn({
+      component: CameraLike,
+      data: { fov: 1, aspect: 1, near: 1, far: 100 },
+    });
+    void r;
+  });
+
+  it('full 9-field call still compiles (no regression)', () => {
+    const w = new World();
+    const r = w.spawn({
+      component: CameraLike,
+      data: {
+        fov: 1,
+        aspect: 1,
+        near: 1,
+        far: 100,
+        projection: 0,
+        left: -1,
+        right: 1,
+        bottom: -1,
+        top: 1,
+      },
+    });
+    void r;
+  });
+
+  it('completely empty data: {} compiles (every field defaulted)', () => {
+    const w = new World();
+    const r = w.spawn({
+      component: CameraLike,
+      data: {},
+    });
+    void r;
+  });
+});
+
+describe('world.spawn — wrong-value fires field-level TS2322 (AC-03, t6.c)', () => {
+  it('data: { fov: "bad" } reports field-level TS2322 (mapped-tuple primary intact)', () => {
+    const w = new World();
+    // AC-03: mapped-tuple primary inference surfaces wrong-VALUE on the
+    // OFFENDING KEY (field-level TS2322), not as the overload wall.
+    // The directive sits directly above the offending key so vitest's
+    // ts-expect-error tracker sees the suppression land on the right
+    // expression.
+    w.spawn({
+      component: CameraLike,
+      data: {
+        // @ts-expect-error AC-03 fov is f32 (number), not string
+        fov: 'bad',
+      },
+    });
+  });
+
+  it('data: { aspect: false } reports field-level TS2322 (bool->f32 narrowing)', () => {
+    const w = new World();
+    w.spawn({
+      component: CameraLike,
+      data: {
+        // @ts-expect-error AC-03 aspect is f32 (number), not boolean
+        aspect: false,
+      },
+    });
+  });
+
+  it('data: { unknownKey: 1 } reports excess-property error, not "No overload matches"', () => {
+    const w = new World();
+    w.spawn({
+      component: CameraLike,
+      data: {
+        // @ts-expect-error AC-03 unknownKey is not part of CameraLike schema
+        unknownKey: 1,
+      },
+    });
+  });
+});