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

package/src/__tests__/externalization-projection.unit.test.ts

@@ -0,0 +1,325 @@
+// m3-projection-kernel-test — ECS externalization projection kernel semantic tests.
+//
+// Validates pure-kernel behaviours: owned snapshot production, default fill,
+// component/field transient exclusion, portable scalar/array values, injectable
+// entity and fixed/variable entity array remap. Uses reflection arrayMeta rather
+// than schema-text classifiers.
+//
+// TDD red phase: these tests are expected to FAIL until the kernel implementation
+// (m3-externalization-kernel-impl) is complete.
+
+import { describe, expect, it } from 'vitest';
+import { type Component, defineComponent } from '../component';
+import {
+  classifyEntityField,
+  createEntityRemap,
+  projectComponentData,
+  remapEntityFieldValue,
+} from '../externalization/index';
+import { World } from '../world';
+
+// ── Test components ──────────────────────────────────────────────────────────
+
+const Pos = defineComponent('TestPos', {
+  x: { type: 'f32', default: 0 },
+  y: { type: 'f32', default: 0 },
+  z: { type: 'f32', default: 0 },
+});
+
+const Mixed = defineComponent('TestMixed', {
+  health: { type: 'u32', default: 100 },
+  name: { type: 'string', default: 'unnamed' },
+  active: { type: 'bool', default: true },
+  scale: { type: 'f32', default: 1.0 },
+});
+
+const WithEntity = defineComponent('TestWithEntity', {
+  target: { type: 'entity' },
+  friends: { type: 'array<entity>', default: [] },
+});
+
+const FixedArrayEntity = defineComponent('TestFixedArrayEntity', {
+  slots: { type: 'array<entity, 4>', default: [0, 0, 0, 0] },
+  // biome-ignore lint/suspicious/noExplicitAny: test component with array<entity,4> default; literal array shape is a branded handle
+} as any) as Component;
+
+const VariableArrayEntity = defineComponent('TestVariableArrayEntity', {
+  items: { type: 'array<entity>', default: [] },
+});
+
+const TransientComp = defineComponent(
+  'TestTransientComp',
+  {
+    x: { type: 'f32', default: 0 },
+  },
+  { transient: true },
+);
+
+const FieldTransient = defineComponent('TestFieldTransient', {
+  keep: { type: 'f32', default: 0 },
+  derived: { type: 'f32', default: 0, transient: true },
+});
+
+const EnumComp = defineComponent('TestEnumComp', {
+  kind: { type: 'enum', default: 0, labels: { static: 0, dynamic: 1 } },
+});
+
+const BufferComp = defineComponent('TestBufferComp', {
+  data: { type: 'buffer', default: 0 },
+});
+
+const FixedBufferComp = defineComponent('TestFixedBufferComp', {
+  data: { type: 'buffer<256>', default: 0 },
+});
+
+const FixedArrayComp = defineComponent('TestFixedArrayComp', {
+  coords: {
+    type: 'array<f32, 3>', // biome-ignore lint/suspicious/noExplicitAny: test component with array<f32,3> default; literal array shape is a branded handle
+    default: [0, 0, 0] as any,
+  },
+});
+
+const EnumNoLabels = defineComponent('TestEnumNoLabels', {
+  kind: { type: 'enum', default: 0 },
+});
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function fieldsOf(r: Record<string, unknown>): string[] {
+  return Object.keys(r).sort();
+}
+
+function hasField(r: Record<string, unknown>, field: string): boolean {
+  return field in r;
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('m3 — projection kernel: owned snapshot and default fill', () => {
+  it('(a) produces a record with all schema fields filled', () => {
+    const result = projectComponentData(Pos as Component, {});
+    expect(fieldsOf(result)).toEqual(['x', 'y', 'z']);
+  });
+
+  it('(b) layer-1 explicit values survive projection', () => {
+    const result = projectComponentData(Pos as Component, { x: 42, y: 7, z: 99 });
+    expect(result.x).toBe(42);
+    expect(result.y).toBe(7);
+    expect(result.z).toBe(99);
+  });
+
+  it('(c) layer-2 defaults fill missing fields', () => {
+    // Mixed.health has layer-2 default 100
+    const result = projectComponentData(Mixed as Component, { name: 'hero' });
+    expect(result.health).toBe(100);
+    expect(result.name).toBe('hero');
+    expect(result.active).toBe(true);
+    expect(result.scale).toBe(1.0);
+  });
+
+  it('(d) layer-3 type defaults fill completely missing input', () => {
+    const result = projectComponentData(Pos as Component, undefined);
+    expect(result.x).toBe(0);
+    expect(result.y).toBe(0);
+    expect(result.z).toBe(0);
+  });
+
+  it('(e) projection produces a new object (owned snapshot)', () => {
+    const input = { x: 1, y: 2, z: 3 };
+    const result = projectComponentData(Pos as Component, input);
+    // Mutating the result should not affect the input
+    (result as Record<string, number>).x = 999;
+    expect(input.x).toBe(1);
+  });
+
+  it('(f) string field survives projection', () => {
+    const result = projectComponentData(Mixed as Component, { name: 'warrior' });
+    expect(result.name).toBe('warrior');
+  });
+
+  it('(g) bool field survives projection', () => {
+    const result = projectComponentData(Mixed as Component, { active: false });
+    expect(result.active).toBe(false);
+  });
+});
+
+describe('m3 — projection kernel: component/field transient exclusion', () => {
+  it('(a) component-level transient excludes all fields from projection', () => {
+    // TransientComp is transient: true — should be detected as fully transient
+    const result = projectComponentData(TransientComp as Component, { x: 5 });
+    // The stub currently returns all fields — this will FAIL until kernel is implemented
+    expect(fieldsOf(result)).toEqual([]);
+  });
+
+  it('(b) field-level transient excludes only that field', () => {
+    const result = projectComponentData(FieldTransient as Component, { keep: 10, derived: 20 });
+    expect(hasField(result, 'keep')).toBe(true);
+    // `derived` is transient — should NOT be in the projection
+    expect(hasField(result, 'derived')).toBe(false);
+    expect(result.keep).toBe(10);
+  });
+
+  it('(c) non-transient component with no transient fields projects all fields', () => {
+    const result = projectComponentData(Pos as Component, { x: 1, y: 2, z: 3 });
+    expect(fieldsOf(result)).toEqual(['x', 'y', 'z']);
+  });
+});
+
+describe('m3 — projection kernel: portable scalar/array values', () => {
+  it('(a) fixed array<f32,3> field survives projection', () => {
+    const result = projectComponentData(FixedArrayComp as Component, { coords: [1, 2, 3] });
+    expect(Array.isArray(result.coords)).toBe(true);
+    expect((result.coords as number[]).length).toBe(3);
+  });
+
+  it('(b) enum field with labels survives projection', () => {
+    const result = projectComponentData(EnumComp as Component, { kind: 1 });
+    expect(result.kind).toBe(1);
+  });
+
+  it('(c) enum field without labels survives projection', () => {
+    const result = projectComponentData(EnumNoLabels as Component, { kind: 0 });
+    expect(result.kind).toBe(0);
+  });
+
+  it('(d) buffer field survives projection', () => {
+    const result = projectComponentData(BufferComp as Component, {});
+    expect(hasField(result, 'data')).toBe(true);
+  });
+
+  it('(e) fixed buffer<256> field survives projection', () => {
+    const result = projectComponentData(FixedBufferComp as Component, {});
+    expect(hasField(result, 'data')).toBe(true);
+  });
+});
+
+describe('m3 — projection kernel: injectable entity remap', () => {
+  it('(a) scalar entity field is remapped through injectable function', () => {
+    const remap = (e: number) => e + 1000;
+    const result = projectComponentData(WithEntity as Component, { target: 42 }, remap);
+    expect(result.target).toBe(1042);
+  });
+
+  it('(b) variable array<entity> field elements are remapped', () => {
+    const remap = (e: number) => e + 1000;
+    const result = projectComponentData(WithEntity as Component, { friends: [1, 2, 3] }, remap);
+    const friends = result.friends as number[];
+    expect(friends).toEqual([1001, 1002, 1003]);
+  });
+
+  it('(c) fixed array<entity,4> field elements are remapped', () => {
+    const remap = (e: number) => e + 1000;
+    const result = projectComponentData(
+      FixedArrayEntity as Component,
+      { slots: [5, 6, 7, 8] },
+      remap,
+    );
+    const slots = result.slots as number[];
+    expect(slots).toEqual([1005, 1006, 1007, 1008]);
+  });
+
+  it('(d) no remap function leaves entity values unchanged', () => {
+    const result = projectComponentData(WithEntity as Component, { target: 42, friends: [1, 2] });
+    expect(result.target).toBe(42);
+    expect(result.friends).toEqual([1, 2]);
+  });
+
+  it('(e) entity field with ENTITY_NULL_RAW is remapped if in range', () => {
+    const remap = (e: number) => (e === 0xffffffff ? e : e + 1000);
+    const result = projectComponentData(WithEntity as Component, { target: 0xffffffff }, remap);
+    expect(result.target).toBe(0xffffffff);
+  });
+
+  it('(f) remaps a typed entity array read from an actual World', () => {
+    const world = new World();
+    const target = world.spawn().unwrap();
+    const holder = world
+      .spawn({ component: VariableArrayEntity, data: { items: [target] } as never })
+      .unwrap();
+    const raw = world.get(holder, VariableArrayEntity).unwrap();
+    const result = projectComponentData(
+      VariableArrayEntity as Component,
+      raw,
+      (entity) => entity + 1000,
+    );
+
+    expect(result.items).toEqual([target + 1000]);
+  });
+});
+
+describe('m3 — projection kernel: entity field classification (arrayMeta-driven)', () => {
+  it('(a) `entity` type field is classified as scalar entity', () => {
+    const kind = classifyEntityField(WithEntity as Component, 'target');
+    expect(kind).toEqual({ kind: 'entity', isArray: false });
+  });
+
+  it('(b) `array<entity>` type field is classified as array entity', () => {
+    const kind = classifyEntityField(WithEntity as Component, 'friends');
+    expect(kind).toEqual({ kind: 'entity', isArray: true });
+  });
+
+  it('(c) `array<entity,4>` type field is classified as array entity', () => {
+    const kind = classifyEntityField(FixedArrayEntity as Component, 'slots');
+    expect(kind).toEqual({ kind: 'entity', isArray: true });
+  });
+
+  it('(d) non-entity field returns null classification', () => {
+    const kind = classifyEntityField(Pos as Component, 'x');
+    expect(kind).toBeNull();
+  });
+
+  it('(e) classification uses arrayMeta.length presence, not schema text parsing', () => {
+    // `array<entity,4>` → arrayMeta has length=4; `array<entity>` → arrayMeta has no length
+    // Both classify as isArray: true regardless of fixed/variable
+    const fixedKind = classifyEntityField(FixedArrayEntity as Component, 'slots');
+    const variableKind = classifyEntityField(VariableArrayEntity as Component, 'items');
+    expect(fixedKind?.isArray).toBe(true);
+    expect(variableKind?.isArray).toBe(true);
+  });
+});
+
+describe('m3 — remap: createEntityRemap from mapping table', () => {
+  it('(a) creates a remap function that translates source ids to target ids', () => {
+    const mapping = new Uint32Array([0, 100, 200, 300]);
+    const remap = createEntityRemap(mapping);
+    expect(remap(0)).toBe(0);
+    expect(remap(1)).toBe(100);
+    expect(remap(2)).toBe(200);
+    expect(remap(3)).toBe(300);
+  });
+
+  it('(b) out-of-range indices return identity', () => {
+    const mapping = new Uint32Array([0, 10]);
+    const remap = createEntityRemap(mapping);
+    expect(remap(5)).toBe(5);
+    expect(remap(999)).toBe(999);
+  });
+
+  it('(c) works with plain number arrays', () => {
+    const mapping = [0, 10, 20];
+    const remap = createEntityRemap(mapping);
+    expect(remap(0)).toBe(0);
+    expect(remap(1)).toBe(10);
+    expect(remap(2)).toBe(20);
+  });
+});
+
+describe('m3 — remap: remapEntityFieldValue', () => {
+  it('(a) scalar entity value is remapped', () => {
+    const remap = (e: number) => e + 100;
+    const result = remapEntityFieldValue(42, { kind: 'entity', isArray: false }, remap);
+    expect(result).toBe(142);
+  });
+
+  it('(b) array<entity> values are remapped element-wise', () => {
+    const remap = (e: number) => e + 100;
+    const result = remapEntityFieldValue([1, 2, 3], { kind: 'entity', isArray: true }, remap);
+    expect(result).toEqual([101, 102, 103]);
+  });
+
+  it('(c) null kind passes value through unchanged', () => {
+    const remap = (e: number) => e + 100;
+    const result = remapEntityFieldValue(42, null, remap);
+    expect(result).toBe(42);
+  });
+});

package/src/__tests__/externalization-render-read-lease.test-d.ts

@@ -0,0 +1,30 @@
+import { expectTypeOf } from 'vitest';
+import { defineComponent } from '../component';
+import {
+  createRenderReadLease,
+  type RenderChangeBatch,
+  type RenderProjectionRequest,
+} from '../projection/index';
+import { World } from '../world';
+
+const Position = defineComponent('RenderReadTypePosition', { x: 'f32' });
+const world = new World();
+const lease = createRenderReadLease(world);
+const request: RenderProjectionRequest = {
+  components: [{ component: Position, fields: ['x'] }],
+};
+const batch = lease.readChanges(lease.inspectCursor());
+const projection = lease.querySpans(request);
+
+expectTypeOf(lease.worldIdentity).toEqualTypeOf<string>();
+expectTypeOf(lease.generation).toBeNumber();
+expectTypeOf(batch).toMatchTypeOf<RenderChangeBatch>();
+expectTypeOf(projection.generation).toBeNumber();
+expectTypeOf<NonNullable<(typeof projection.spans)[number]['fields']['x']>>().toMatchTypeOf<
+  ArrayLike<number>
+>();
+
+// @ts-expect-error RenderReadLease does not expose storage internals.
+lease._getArrayView;
+// @ts-expect-error a renderer projection is not a public lease.
+projection.readChanges;

package/src/__tests__/externalization-render-read-lease.unit.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { createRenderReadLease, type RenderProjectionRequest } from '../projection/index';
+import { World } from '../world';
+
+const Position = defineComponent('RenderReadPosition', {
+  x: 'f32',
+  y: 'f32',
+});
+
+const request: RenderProjectionRequest = {
+  components: [{ component: Position, fields: ['x', 'y'] }],
+};
+
+describe('RenderReadLease contract', () => {
+  it('attaches, exposes a world generation, and reads continuous spans', () => {
+    const world = new World();
+    world.spawn({ component: Position, data: { x: 1, y: 2 } }).unwrap();
+    const lease = createRenderReadLease(world);
+
+    expect(lease.worldIdentity).toBe(world.identity);
+    expect(lease.generation).toBeGreaterThan(0);
+    const projection = lease.querySpans(request);
+    expect(projection.generation).toBe(lease.generation);
+    expect(projection.spans).toHaveLength(1);
+    expect(projection.spans[0]?.fields.x).toEqual(new Float32Array([1]));
+    expect(projection.spans[0]?.fields.y).toEqual(new Float32Array([2]));
+  });
+
+  it('publishes world and shared-ref changes through one cursor contract', () => {
+    const world = new World();
+    const lease = createRenderReadLease(world);
+    const cursor = lease.inspectCursor();
+    const entity = world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+    world.set(entity, Position, { x: 3 }).unwrap();
+    const batch = lease.readChanges(cursor);
+
+    expect(batch.status).toBe('ok');
+    if (batch.status !== 'ok') return;
+    expect(batch.cursor).toBeGreaterThan(cursor);
+    expect(batch.world.records.some((record) => record.kind === 'component-changed')).toBe(true);
+    expect(batch.sharedRefs.status).toBe('ok');
+  });
+
+  it('reports overflow and requires an explicit resync', () => {
+    const world = new World();
+    const lease = createRenderReadLease(world);
+    const staleCursor = 0;
+
+    for (let index = 0; index < 65537; index += 1) {
+      const entity = world.spawn({ component: Position, data: { x: index, y: 0 } }).unwrap();
+      world.despawn(entity).unwrap();
+    }
+
+    const batch = lease.readChanges(staleCursor);
+    expect(batch.status).toBe('overflow');
+    if (batch.status !== 'overflow') return;
+    expect(batch.resync).toBe(true);
+    expect(batch.oldestAvailable).toBeGreaterThan(staleCursor);
+  });
+
+  it('detaches idempotently and rejects reads after dispose', () => {
+    const lease = createRenderReadLease(new World());
+    lease.dispose();
+    lease.dispose();
+
+    expect(() => lease.inspectCursor()).toThrow(/disposed/i);
+    expect(() => lease.querySpans(request)).toThrow(/disposed/i);
+  });
+
+  it('distinguishes leases from renderer-owned projections', () => {
+    const world = new World();
+    const lease = createRenderReadLease(world);
+    const projection = lease.querySpans(request);
+
+    expect(projection).not.toBe(lease);
+    expect(Object.keys(projection)).toEqual(['generation', 'sharedRefEpoch', 'spans']);
+  });
+});

package/src/__tests__/externalization-root-surface.unit.test.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const rootSource = readFileSync(new URL('../index.ts', import.meta.url), 'utf8');
+
+const redundantRootNames = [
+  'createEntityRemap',
+  'isComponentFullyTransient',
+  'isComponentPortable',
+  'isFieldPortable',
+  'remapEntityFieldValue',
+] as const;
+
+describe('ECS externalization root surface', () => {
+  it('keeps the kernel on its dedicated subpath', async () => {
+    for (const name of redundantRootNames) {
+      expect(rootSource).not.toContain(name);
+    }
+
+    const root = (await import('../index')) as Record<string, unknown>;
+    for (const name of redundantRootNames) {
+      expect(root).not.toHaveProperty(name);
+    }
+
+    const externalization = (await import('../externalization/index')) as Record<string, unknown>;
+    for (const name of redundantRootNames) {
+      expect(externalization).toHaveProperty(name);
+    }
+    expect(externalization).toHaveProperty('classifyEntityField');
+    expect(externalization).toHaveProperty('projectComponentData');
+    expect(externalization).toHaveProperty('validateProfileComponents');
+  });
+});

package/src/__tests__/field-enum-labels-reflection.test.ts

@@ -0,0 +1,66 @@
+// solo round-24 (P7 residue): field-level enum-labels reflection.
+//
+// An `enum` field stores a bare u32 variant index; the label→value map
+// historically lived in a SEPARATE per-package const map (`RigidBodyTypeValue`)
+// with no schema attachment, so no reflection consumer (the editor's
+// describeComponent, an inspector UI) could learn the legal variants + their
+// integers — a docs-only user had to read engine source (a back door, recurring
+// friction #1 in solo rounds 15/20/22).
+//
+// The fix attaches an optional `labels` map to the enum FieldDescriptor,
+// aggregated into `component.fields[field].labels` (FieldReflection), mirroring
+// how `default` / `transient` / `arrayMeta` are already per-field reflection
+// data. This test asserts the reflection round-trips (revert-to-red: drop the
+// `if (desc.labels !== undefined) row.labels = …` aggregation line → red).
+
+import { describe, expect, it } from 'vitest';
+import { type Component, defineComponent } from '../component';
+
+function fieldLabels(comp: Component, field: string): Readonly<Record<string, number>> | undefined {
+  const reflection = comp.fields[field as keyof typeof comp.fields] as
+    | { readonly labels?: Readonly<Record<string, number>> }
+    | undefined;
+  return reflection?.labels;
+}
+
+describe('field-level enum-labels reflection (solo round-24)', () => {
+  it('(a) an enum field declared with labels reflects the label→value map', () => {
+    const C = defineComponent('R24_EnumLabelsA', {
+      type: { type: 'enum', default: 1, labels: { static: 0, dynamic: 1, kinematic: 2 } },
+      mass: { type: 'f32', default: 1 },
+    });
+
+    expect(fieldLabels(C, 'type')).toEqual({ static: 0, dynamic: 1, kinematic: 2 });
+  });
+
+  it('(b) a non-enum / label-less field reflects labels as absent (control)', () => {
+    const C = defineComponent('R24_EnumLabelsB', {
+      type: { type: 'enum', default: 1, labels: { static: 0, dynamic: 1, kinematic: 2 } },
+      mass: { type: 'f32', default: 1 },
+    });
+
+    // exactOptionalPropertyTypes: undeclared → absence (undefined), not {}.
+    expect(fieldLabels(C, 'mass')).toBeUndefined();
+  });
+
+  it('(c) bare-keyword field form leaves labels absent', () => {
+    const C = defineComponent('R24_EnumLabelsC', {
+      shape: 'enum',
+    });
+
+    expect(fieldLabels(C, 'shape')).toBeUndefined();
+  });
+
+  it('(d) the reflected labels map is frozen (a stable read-only projection)', () => {
+    const source = { static: 0, dynamic: 1, kinematic: 2 };
+    const C = defineComponent('R24_EnumLabelsD', {
+      type: { type: 'enum', default: 0, labels: source },
+    });
+
+    const labels = fieldLabels(C, 'type');
+    expect(Object.isFrozen(labels)).toBe(true);
+    // Copied, not aliased: mutating the source afterward does not leak in.
+    (source as Record<string, number>).extra = 9;
+    expect(labels).toEqual({ static: 0, dynamic: 1, kinematic: 2 });
+  });
+});

package/src/__tests__/field-shape-fixture.test.ts

@@ -0,0 +1,61 @@
+// R0-03A — producer-owned component field-shape coverage.
+//
+// The fixture is deliberately imported from the engine owner. This test proves
+// the registry and FieldReflection carry the same eight shape facts that a
+// downstream Inspector/Gateway consumer will read; it does not maintain a
+// second editor-side component list.
+
+import { describe, expect, it } from 'vitest';
+import {
+  FieldShapeContainerFixture,
+  FieldShapePrimitiveFixture,
+} from '../__fixtures__/field-shape-fixture';
+import { componentSchema } from '../component';
+import { componentDefinition } from '../component-schema';
+
+describe('R0-03A producer-owned field-shape fixtures', () => {
+  it('covers every required field shape through component reflection', () => {
+    const primitive = FieldShapePrimitiveFixture.fields;
+    const container = FieldShapeContainerFixture.fields;
+
+    expect({
+      scalar: primitive.scalar.shape,
+      boolean: primitive.enabled.shape,
+      enum: primitive.mode.shape,
+      vector: primitive.vector.shape,
+      quaternion: primitive.quaternion.shape,
+      array: primitive.values.shape,
+      'asset-ref': primitive.material.shape,
+      optional: container.optionalEntity.shape,
+      nested: container.nestedState.shape,
+    }).toEqual({
+      scalar: 'scalar',
+      boolean: 'boolean',
+      enum: 'enum',
+      vector: 'vector',
+      quaternion: 'quaternion',
+      array: 'array',
+      'asset-ref': 'asset-ref',
+      optional: 'optional',
+      nested: 'nested',
+    });
+  });
+
+  it('keeps storage type, defaults, and enum labels alongside the shape tag', () => {
+    expect(componentSchema(FieldShapePrimitiveFixture)).toMatchObject({
+      scalar: 'f32',
+      enabled: 'bool',
+      mode: 'enum',
+      vector: 'array<f32, 3>',
+      quaternion: 'array<f32, 4>',
+      values: 'array<f32>',
+      material: 'shared<MaterialAsset>',
+    });
+    expect(componentDefinition(FieldShapePrimitiveFixture).defaults).toMatchObject({
+      scalar: 0,
+      enabled: false,
+      mode: 0,
+    });
+    expect(FieldShapePrimitiveFixture.fields.mode.labels).toEqual({ idle: 0, active: 1 });
+  });
+});

package/src/__tests__/field-transient-reflection.test.ts

@@ -0,0 +1,59 @@
+// feat-20260709-transform-serialization-vec-fields-and-field-trans M1 / w1:
+// Field-level transient reflection (AC-01, TDD red-first).
+//
+// AC-01: after a component declares a field with `transient: true`, the fact is
+// readable at runtime off `component.fields[field].transient === true` through
+// the FieldReflection layer (component.ts:1048-1052). A field without a
+// transient declaration reflects `transient` as absent/undefined (control), the
+// same shape as the component-level `transient` reflection (D-5 same-word-same-
+// meaning, granularity sunk to field level).
+//
+// Application-point discipline (task w1 rationale): AC-01 is asserted on a real
+// `defineComponent` product's FieldReflection, NOT via a standalone *.test-d.ts.
+// This file uses runtime `defineComponent` calls + value assertions on
+// `.fields[field].transient`.
+
+import { describe, expect, it } from 'vitest';
+import { type Component, defineComponent } from '../component';
+
+// `transient` is a field-level reflection fact (w2 adds it to FieldReflection).
+// Read it off the concrete component product without widening to `any`.
+function fieldTransient(comp: Component, field: string): boolean | undefined {
+  const reflection = comp.fields[field as keyof typeof comp.fields] as
+    | { readonly transient?: boolean }
+    | undefined;
+  return reflection?.transient;
+}
+
+describe('w1 — field-level transient reflection (AC-01)', () => {
+  it('(a) a field declared transient:true reflects transient===true at runtime', () => {
+    const C = defineComponent('W1_FieldTransientA', {
+      keep: { type: 'f32', default: 0 },
+      derived: { type: 'array<f32, 16>', default: new Float32Array(16), transient: true },
+    });
+
+    // Runtime-readable through FieldReflection (component.ts:1048-1052).
+    expect(fieldTransient(C, 'derived')).toBe(true);
+  });
+
+  it('(b) a field without a transient declaration reflects transient as absent (control)', () => {
+    const C = defineComponent('W1_FieldTransientB', {
+      keep: { type: 'f32', default: 0 },
+      derived: { type: 'array<f32, 16>', default: new Float32Array(16), transient: true },
+    });
+
+    // exactOptionalPropertyTypes: undeclared fields never carry an explicit
+    // transient key -- absence (undefined), not `false`.
+    expect(fieldTransient(C, 'keep')).toBeUndefined();
+  });
+
+  it('(c) bare-keyword field form leaves transient absent', () => {
+    const C = defineComponent('W1_FieldTransientC', {
+      x: 'f32',
+      y: 'f32',
+    });
+
+    expect(fieldTransient(C, 'x')).toBeUndefined();
+    expect(fieldTransient(C, 'y')).toBeUndefined();
+  });
+});