feat(data): Schema.createCoerceFunction + convertTypedBuffer (#183)

* feat(data): Schema.createCoerceFunction + convertTypedBuffer

A schema→schema value-coercion factory and a TypedBuffer converter built on it,
the foundation for automated persisted-data migration.

Schema.createCoerceFunction(input, output) analyzes the pair ONCE and returns a
reusable per-value converter, or null when no automatic conversion exists (the
null return is the feasibility check — no separate predicate). Supported:
numbers (clamp to the output's min/max; precision/width loss applied by the
destination buffer), boolean/string identity, enum→enum when the input values
are a subset, →const, object→object (reorder / drop / fill new fields from their
default / recurse), and array→array (element-wise, extend a fixed vector from the
item default). Cross-kind changes return null.

convertTypedBuffer(source, targetSchema, capacity?) compiles one coerce fn and
maps it over the source's elements into a new buffer of the target schema;
throws when not convertible. Source values are shared by reference (ECS values
are never mutated in place); newly-introduced field defaults are cloned per
element.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(data): in-place coerce for archetype columns and store components

Follow-ups on the coerce foundation:

- Objects: only a numeric STRUCT (all fields packed) requires a default for a
  new field; a plain object may lack a non-required property, which is now
  simply omitted rather than blocking the conversion. Red/green tests for both.
- convertTypedBuffer gains a `count` param (default: full range) so a table can
  convert only its live rows, leaving unused capacity at the new default —
  avoids running an array buffer's undefined tail through the coercer.
- coerceArchetypeColumn(archetype, component, targetSchema): converts one column
  in place, preserving rows and rebuilding the archetype's baked insert (via
  fromData) so later inserts write through the new column.
- coerceStoreComponent(store, component, targetSchema): converts that component
  in every archetype that carries it and adopts the new schema, so the store's
  schema is migrated in place.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(data)!: convertTypedBuffer takes a named options object

Replace the two similar trailing number params (capacity, count) with
`{ capacity?, count? }`. Breaking for direct callers, but the buffer converter
is rarely called directly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(data)!: convertTypedBuffer takes a single named-arguments object

Fold source/targetSchema/capacity/count into one options object so the call is
fully named and never exceeds two ordinal arguments.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: krisnye

packages/data/src/ecs/archetype/coerce-archetype-column.ts

@@ -0,0 +1,35 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Schema } from "../../schema/index.js";
+import { TypedBuffer, convertTypedBuffer } from "../../typed-buffer/index.js";
+import type { Archetype } from "./archetype.js";
+
+/**
+ * Convert one component column of `archetype` to `targetSchema` IN PLACE,
+ * preserving the archetype's live rows. Returns `false` (a no-op) when the
+ * component is absent from this archetype.
+ *
+ * An archetype (a table) bakes its column references into a specialized `insert`;
+ * swapping a column therefore goes through `archetype.fromData`, which replaces
+ * the columns AND rebuilds that baked insert so later inserts write through the
+ * converted column. Only the live `rowCount` rows are converted — unused capacity
+ * stays at the new column's default.
+ *
+ * Throws (via {@link convertTypedBuffer}) if no automatic conversion exists.
+ */
+export function coerceArchetypeColumn(
+    archetype: Archetype<any>,
+    component: string,
+    targetSchema: Schema,
+): boolean {
+    const columns = archetype.columns as Record<string, TypedBuffer<unknown>>;
+    const existing = columns[component];
+    if (existing === undefined) return false;
+    const converted = convertTypedBuffer({ source: existing, targetSchema, capacity: archetype.rowCapacity, count: archetype.rowCount });
+    archetype.fromData({
+        columns: { ...columns, [component]: converted },
+        rowCount: archetype.rowCount,
+        rowCapacity: archetype.rowCapacity,
+    });
+    return true;
+}

packages/data/src/ecs/archetype/index.ts

@@ -2,3 +2,4 @@
 export * from "./archetype.js";
 export * from "./create-archetype.js";
 export * from "./delete-row.js";
+export * from "./coerce-archetype-column.js";

packages/data/src/ecs/store/coerce-store-component.test.ts

@@ -0,0 +1,78 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { Store } from "./index.js";
+import { coerceStoreComponent } from "./coerce-store-component.js";
+import { coerceArchetypeColumn, type Archetype } from "../archetype/index.js";
+import type { Schema } from "../../schema/index.js";
+
+const f32 = { type: "number", precision: 1 } as const satisfies Schema;
+const num = { type: "number" } as const satisfies Schema;
+const vec2 = { type: "object", properties: { x: f32, y: f32 } } as const satisfies Schema;
+const vec3 = { type: "object", properties: { x: f32, y: f32, z: { type: "number", precision: 1, default: 7 } } } as const satisfies Schema;
+const capped = { type: "integer", minimum: 0, maximum: 100 } as const satisfies Schema;
+
+describe("coerceArchetypeColumn — in-place column conversion on a table", () => {
+    it("adds a struct field to every live row and keeps insert working", () => {
+        const store = Store.create({ components: { pos: vec2 }, resources: {}, archetypes: { P: ["pos"] } });
+        const P = store.archetypes.P as any;
+        const e0 = P.insert({ pos: { x: 1, y: 2 } });
+        const e1 = P.insert({ pos: { x: 3, y: 4 } });
+
+        const arch = store.queryArchetypes(["pos"])[0] as unknown as Archetype<any>;
+        expect(coerceArchetypeColumn(arch, "pos", vec3)).toBe(true);
+
+        // Existing rows carry the new field's default.
+        expect(store.read(e0)).toEqual({ pos: { x: 1, y: 2, z: 7 } });
+        expect(store.read(e1)).toEqual({ pos: { x: 3, y: 4, z: 7 } });
+        // The column now reports the new schema.
+        expect(arch.columns.pos.schema).toBe(vec3);
+
+        // Insert AFTER the swap writes through the rebuilt (converted) column.
+        const e2 = P.insert({ pos: { x: 5, y: 6, z: 8 } });
+        expect(store.read(e2)).toEqual({ pos: { x: 5, y: 6, z: 8 } });
+    });
+
+    it("is a no-op returning false when the component is absent", () => {
+        const store = Store.create({ components: { pos: vec2 }, resources: {}, archetypes: { P: ["pos"] } });
+        const p = store.queryArchetypes(["pos"])[0] as unknown as Archetype<any>;
+        expect(coerceArchetypeColumn(p, "missing", num)).toBe(false);
+    });
+});
+
+describe("coerceStoreComponent — in-place schema change across the whole store", () => {
+    it("converts the component in every archetype and adopts the new schema", () => {
+        const store = Store.create({
+            components: { hp: num, mana: num },
+            resources: {},
+            archetypes: { A: ["hp"], AB: ["hp", "mana"] },
+        });
+        const A = store.archetypes.A as any;
+        const AB = store.archetypes.AB as any;
+        const e0 = A.insert({ hp: 50 });
+        const e1 = A.insert({ hp: 70000 });
+        const e2 = AB.insert({ hp: 90000, mana: 5 });
+
+        coerceStoreComponent(store, "hp", capped);
+
+        // Every archetype's existing rows are clamped into the new range.
+        expect(store.read(e0)).toEqual({ hp: 50 });
+        expect(store.read(e1)).toEqual({ hp: 100 });
+        expect(store.read(e2)).toEqual({ hp: 100, mana: 5 });
+
+        // The store adopts the new schema; the untouched component is unchanged.
+        expect((store.componentSchemas as Record<string, Schema>).hp).toBe(capped);
+        expect((store.componentSchemas as Record<string, Schema>).mana).toBe(num);
+
+        // Inserts now go through the new (integer-backed) storage: a fractional
+        // value truncates, proving the column was actually re-typed.
+        const e3 = A.insert({ hp: 42.9 });
+        expect(store.read(e3)).toEqual({ hp: 42 });
+    });
+
+    it("throws when a column cannot be automatically converted", () => {
+        const store = Store.create({ components: { hp: num }, resources: {}, archetypes: { A: ["hp"] } });
+        (store.archetypes.A as any).insert({ hp: 1 });
+        expect(() => coerceStoreComponent(store, "hp", vec2)).toThrow(/No automatic TypedBuffer conversion/);
+    });
+});

packages/data/src/ecs/store/coerce-store-component.ts

@@ -0,0 +1,36 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Schema } from "../../schema/index.js";
+import type { Archetype, ReadonlyArchetype } from "../archetype/index.js";
+import { coerceArchetypeColumn } from "../archetype/index.js";
+
+// The minimal store surface this helper needs. Declared structurally (with `any`
+// in the query signature) so a concretely-typed store assigns without the
+// generic-method variance that blocks assignment to `ReadonlyStore<any,…>`.
+interface CoercibleStore {
+    queryArchetypes(include: readonly any[], options?: any): readonly ReadonlyArchetype<any>[];
+    readonly componentSchemas: object;
+}
+
+/**
+ * Change a component's schema across the whole store IN PLACE: convert that
+ * component's column in every archetype that carries it, then adopt
+ * `targetSchema` as the component's declared schema so subsequently-created
+ * archetypes back it the new way.
+ *
+ * This is the store-level counterpart to {@link coerceArchetypeColumn}, and the
+ * building block for migrating a persisted schema forward without a full reload.
+ * Throws if any archetype's column has no automatic conversion to `targetSchema`.
+ */
+export function coerceStoreComponent(
+    store: CoercibleStore,
+    component: string,
+    targetSchema: Schema,
+): void {
+    // queryArchetypes returns ReadonlyArchetype, but these are the live Archetype
+    // instances that carry the fromData/insert surface the column swap needs.
+    for (const archetype of store.queryArchetypes([component])) {
+        coerceArchetypeColumn(archetype as unknown as Archetype<any>, component, targetSchema);
+    }
+    (store.componentSchemas as Record<string, Schema>)[component] = targetSchema;
+}

packages/data/src/ecs/store/index.ts

@@ -1,5 +1,6 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 export * from "./store.js";
+export * from "./coerce-store-component.js";
 export * from "./archetype-components.js";
 export type { ArchetypeSchema, ArchetypeRowOf, ArchetypeHandleOf } from "./archetype-row.js";
 export type { EntityReadValues, EntityUpdateValues, ArchetypeQueryOptions } from "./core/core.js";

packages/data/src/schema/create-coerce-function.test.ts

@@ -0,0 +1,192 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { createCoerceFunction } from "./create-coerce-function.js";
+import { Schema } from "./index.js";
+import type { Schema as SchemaType } from "./schema.js";
+
+const num = { type: "number" } as const satisfies SchemaType;
+const f32 = { type: "number", precision: 1 } as const satisfies SchemaType;
+const bool = { type: "boolean" } as const satisfies SchemaType;
+const str = { type: "string" } as const satisfies SchemaType;
+
+// createCoerceFunction never returns null in the "possible" cases — narrow it.
+const coercer = (input: SchemaType, output: SchemaType) => {
+    const fn = createCoerceFunction(input, output);
+    expect(fn).not.toBeNull();
+    return fn!;
+};
+
+describe("createCoerceFunction — numbers", () => {
+    it("number → number with no bounds is identity (F64→F32 precision loss is the buffer's job)", () => {
+        const fn = coercer(num, f32);
+        expect(fn(3.14159)).toBe(3.14159);
+        expect(fn(-100)).toBe(-100);
+    });
+
+    it("clamps to the output maximum / minimum when declared", () => {
+        expect(coercer(num, { type: "number", maximum: 100 })(150)).toBe(100);
+        expect(coercer(num, { type: "number", maximum: 100 })(50)).toBe(50);
+        expect(coercer(num, { type: "number", minimum: 0 })(-5)).toBe(0);
+        const both = coercer(num, { type: "number", minimum: 0, maximum: 10 });
+        expect([both(-1), both(5), both(99)]).toEqual([0, 5, 10]);
+    });
+
+    it("caps a wide integer down to a narrow integer range (the U32→'U16' case)", () => {
+        const fn = coercer({ type: "integer" }, { type: "integer", minimum: 0, maximum: 65535 });
+        expect(fn(70000)).toBe(65535);
+        expect(fn(-5)).toBe(0);
+        expect(fn(40000)).toBe(40000);
+    });
+});
+
+describe("createCoerceFunction — scalars & enums", () => {
+    it("boolean → boolean and string → string are identity", () => {
+        expect(coercer(bool, bool)(true)).toBe(true);
+        expect(coercer(str, str)("hi")).toBe("hi");
+    });
+
+    it("enum → enum only when every input value is an output value", () => {
+        const widen = coercer({ enum: ["a", "b"] }, { enum: ["a", "b", "c"] });
+        expect(widen("a")).toBe("a");
+        expect(createCoerceFunction({ enum: ["a", "z"] }, { enum: ["a", "b"] })).toBeNull();
+    });
+
+    it("→ const collapses any input to the constant", () => {
+        const fn = coercer(num, { const: 42 });
+        expect(fn(1)).toBe(42);
+        expect(fn(999)).toBe(42);
+    });
+});
+
+describe("createCoerceFunction — objects", () => {
+    it("reorders fields (order is irrelevant to the produced value)", () => {
+        const fn = coercer(
+            { type: "object", properties: { x: f32, y: f32 } },
+            { type: "object", properties: { y: f32, x: f32 } },
+        );
+        expect(fn({ x: 1, y: 2 })).toEqual({ x: 1, y: 2 });
+    });
+
+    it("fills a new field from its default", () => {
+        const fn = coercer(
+            { type: "object", properties: { x: f32, y: f32 } },
+            { type: "object", properties: { x: f32, y: f32, z: { type: "number", default: 9 } } },
+        );
+        expect(fn({ x: 1, y: 2 })).toEqual({ x: 1, y: 2, z: 9 });
+    });
+
+    it("requires a default for a new field of a numeric STRUCT (every field is packed)", () => {
+        // f32 properties pack as a struct → a missing field would be NaN, so a
+        // new field without a default makes the conversion impossible.
+        expect(createCoerceFunction(
+            { type: "object", properties: { x: f32 } },
+            { type: "object", properties: { x: f32, z: f32 } },
+        )).toBeNull();
+    });
+
+    it("omits a new NON-required field with no default on a plain object", () => {
+        // f64 properties do not pack as a struct → a plain object may simply lack
+        // an optional field, so this is convertible and the field is left off.
+        const fn = coercer(
+            { type: "object", properties: { a: num } },
+            { type: "object", properties: { a: num, b: num } },
+        );
+        expect(fn({ a: 1 })).toEqual({ a: 1 });
+    });
+
+    it("still requires a default for a new REQUIRED field on a plain object", () => {
+        expect(createCoerceFunction(
+            { type: "object", properties: { a: num } },
+            { type: "object", properties: { a: num, b: num }, required: ["b"] },
+        )).toBeNull();
+    });
+
+    it("drops fields the output does not declare", () => {
+        const fn = coercer(
+            { type: "object", properties: { x: f32, y: f32, z: f32 } },
+            { type: "object", properties: { x: f32, y: f32 } },
+        );
+        expect(fn({ x: 1, y: 2, z: 3 })).toEqual({ x: 1, y: 2 });
+    });
+
+    it("coerces (and clamps) a retyped field", () => {
+        const fn = coercer(
+            { type: "object", properties: { x: num } },
+            { type: "object", properties: { x: { type: "integer", minimum: 0, maximum: 10 } } },
+        );
+        expect(fn({ x: 50 })).toEqual({ x: 10 });
+    });
+
+    it("gives each element its own copy of an object default (no aliasing)", () => {
+        const fn = coercer(
+            { type: "object", properties: { x: f32 } },
+            { type: "object", properties: { x: f32, meta: { type: "object", properties: { n: { type: "number", default: 0 } } } } },
+        );
+        const a = fn({ x: 1 }) as { meta: object };
+        const b = fn({ x: 2 }) as { meta: object };
+        expect(a.meta).toEqual({ n: 0 });
+        expect(a.meta).not.toBe(b.meta); // distinct instances
+    });
+
+    it("is not convertible when an existing sub-field cannot be converted", () => {
+        // Nested numeric struct gains a defaultless field ⇒ the sub-conversion,
+        // and therefore the whole conversion, is impossible.
+        expect(createCoerceFunction(
+            { type: "object", properties: { p: { type: "object", properties: { x: f32 } } } },
+            { type: "object", properties: { p: { type: "object", properties: { x: f32, y: f32 } } } },
+        )).toBeNull();
+    });
+});
+
+describe("createCoerceFunction — arrays", () => {
+    it("extends a fixed vector, filling from the item default (vec3 → vec4)", () => {
+        const fn = coercer(
+            { type: "array", items: f32, minItems: 3, maxItems: 3 },
+            { type: "array", items: { type: "number", default: 0 }, minItems: 4, maxItems: 4 },
+        );
+        expect(fn([1, 2, 3])).toEqual([1, 2, 3, 0]);
+    });
+
+    it("is not convertible when a longer fixed output has no item default", () => {
+        expect(createCoerceFunction(
+            { type: "array", items: f32, minItems: 3, maxItems: 3 },
+            { type: "array", items: f32, minItems: 4, maxItems: 4 },
+        )).toBeNull();
+    });
+
+    it("truncates a fixed vector (vec3 → vec2)", () => {
+        const fn = coercer(
+            { type: "array", items: f32, minItems: 3, maxItems: 3 },
+            { type: "array", items: f32, minItems: 2, maxItems: 2 },
+        );
+        expect(fn([1, 2, 3])).toEqual([1, 2]);
+    });
+
+    it("maps every element of a variable-length array (with clamp)", () => {
+        const fn = coercer(
+            { type: "array", items: num },
+            { type: "array", items: { type: "integer", minimum: 0, maximum: 5 } },
+        );
+        expect(fn([1, 10, 3])).toEqual([1, 5, 3]);
+    });
+});
+
+describe("createCoerceFunction — incompatible kinds return null", () => {
+    it.each([
+        ["number → object", num, { type: "object", properties: { x: f32 } } as SchemaType],
+        ["object → number", { type: "object", properties: { x: f32 } } as SchemaType, num],
+        ["number → boolean", num, bool],
+        ["number → enum", num, { enum: [1, 2, 3] } as SchemaType],
+        ["array → object", { type: "array", items: num } as SchemaType, { type: "object", properties: { x: f32 } } as SchemaType],
+    ])("%s", (_label, input, output) => {
+        expect(createCoerceFunction(input, output)).toBeNull();
+    });
+});
+
+describe("createCoerceFunction — namespace exposure", () => {
+    it("is reachable as Schema.createCoerceFunction", () => {
+        expect(typeof Schema.createCoerceFunction).toBe("function");
+        expect(Schema.createCoerceFunction(num, f32)!(1.5)).toBe(1.5);
+    });
+});