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

package/src/storage/change-detection.ts

@@ -0,0 +1,231 @@
+// @forgeax/engine-ecs — per-entity and per-resource change ticks.
+
+import type { Component } from '../component';
+import * as componentOwner from '../component';
+import { Entity } from '../entity';
+import { type EntityHandle, entityIndex } from '../entity-handle';
+
+export { WorldChangeJournal, type WorldChangeRead } from '../world-change-journal';
+
+import type { ArchetypeGraph } from './archetype-graph';
+import { getOrCreateSparseTagSet } from './archetype-graph';
+import type { Table } from './table';
+
+const INITIAL_SPARSE_CAPACITY = 64;
+
+export interface ComponentEpochColumns {
+  added: Float64Array;
+  changed: Float64Array;
+}
+
+export function createComponentEpochColumns(capacity: number): ComponentEpochColumns {
+  return { added: new Float64Array(capacity), changed: new Float64Array(capacity) };
+}
+
+export function growComponentEpochColumns(
+  columns: ComponentEpochColumns,
+  capacity: number,
+): ComponentEpochColumns {
+  const added = new Float64Array(capacity);
+  const changed = new Float64Array(capacity);
+  added.set(columns.added);
+  changed.set(columns.changed);
+  return { added, changed };
+}
+
+export function copyComponentEpoch(
+  source: ComponentEpochColumns,
+  sourceRow: number,
+  target: ComponentEpochColumns,
+  targetRow: number,
+): void {
+  target.added[targetRow] = source.added[sourceRow] ?? 0;
+  target.changed[targetRow] = source.changed[sourceRow] ?? 0;
+}
+
+export interface SparseTagSet {
+  readonly component: Component;
+  sparse: Int32Array;
+  dense: Uint32Array;
+  added: Float64Array;
+  changed: Float64Array;
+  size: number;
+}
+
+export function createSparseTagSet(component: Component): SparseTagSet {
+  const sparse = new Int32Array(INITIAL_SPARSE_CAPACITY);
+  sparse.fill(-1);
+  return {
+    component,
+    sparse,
+    dense: new Uint32Array(INITIAL_SPARSE_CAPACITY),
+    added: new Float64Array(INITIAL_SPARSE_CAPACITY),
+    changed: new Float64Array(INITIAL_SPARSE_CAPACITY),
+    size: 0,
+  };
+}
+
+export function sparseTagIndex(set: SparseTagSet, entity: EntityHandle): number {
+  const denseIndex = set.sparse[entityIndex(entity)] ?? -1;
+  return denseIndex >= 0 && set.dense[denseIndex] === (entity as number) ? denseIndex : -1;
+}
+
+export function sparseTagHas(set: SparseTagSet, entity: EntityHandle): boolean {
+  return sparseTagIndex(set, entity) >= 0;
+}
+
+export function insertSparseTag(set: SparseTagSet, entity: EntityHandle, epoch: number): number {
+  const present = sparseTagIndex(set, entity);
+  if (present >= 0) {
+    set.changed[present] = epoch;
+    return present;
+  }
+  growSparseSlots(set, entityIndex(entity) + 1);
+  if (set.size === set.dense.length) growSparseDense(set, set.size + 1);
+  const denseIndex = set.size;
+  set.dense[denseIndex] = entity as number;
+  set.added[denseIndex] = epoch;
+  set.changed[denseIndex] = epoch;
+  set.sparse[entityIndex(entity)] = denseIndex;
+  set.size += 1;
+  return denseIndex;
+}
+
+export function removeSparseTag(set: SparseTagSet, entity: EntityHandle): boolean {
+  const denseIndex = sparseTagIndex(set, entity);
+  if (denseIndex < 0) return false;
+  const lastIndex = set.size - 1;
+  set.sparse[entityIndex(entity)] = -1;
+  if (denseIndex !== lastIndex) {
+    const movedEntity = set.dense[lastIndex] as EntityHandle;
+    set.dense[denseIndex] = movedEntity as number;
+    set.added[denseIndex] = set.added[lastIndex] ?? 0;
+    set.changed[denseIndex] = set.changed[lastIndex] ?? 0;
+    set.sparse[entityIndex(movedEntity)] = denseIndex;
+  }
+  set.size = lastIndex;
+  return true;
+}
+
+function growSparseSlots(set: SparseTagSet, targetCapacity: number): void {
+  if (targetCapacity <= set.sparse.length) return;
+  let capacity = set.sparse.length;
+  while (capacity < targetCapacity) capacity *= 2;
+  const sparse = new Int32Array(capacity);
+  sparse.fill(-1);
+  sparse.set(set.sparse);
+  set.sparse = sparse;
+}
+
+function growSparseDense(set: SparseTagSet, targetCapacity: number): void {
+  let capacity = set.dense.length;
+  while (capacity < targetCapacity) capacity *= 2;
+  const dense = new Uint32Array(capacity);
+  dense.set(set.dense);
+  set.dense = dense;
+  const added = new Float64Array(capacity);
+  added.set(set.added);
+  set.added = added;
+  const changed = new Float64Array(capacity);
+  changed.set(set.changed);
+  set.changed = changed;
+}
+
+export interface ChangeTicks {
+  added: number;
+  changed: number;
+}
+
+export const NEVER_CHANGED_TICK = -1;
+
+export function createChangeTicks(tick: number): ChangeTicks {
+  return { added: tick, changed: tick };
+}
+
+interface EntityLocation {
+  readonly archetypeId: number;
+  readonly archetypeRow: number;
+}
+
+export function readComponentChange(
+  graph: ArchetypeGraph,
+  location: EntityLocation,
+  entity: EntityHandle,
+  componentId: number,
+): ChangeTicks | undefined {
+  const sparseSet = graph.sparseTags.get(componentId);
+  if (sparseSet !== undefined) {
+    const denseIndex = sparseTagIndex(sparseSet, entity);
+    if (denseIndex < 0) return undefined;
+    return {
+      added: sparseSet.added[denseIndex] ?? 0,
+      changed: sparseSet.changed[denseIndex] ?? 0,
+    };
+  }
+  const archetype = graph.archetypes[location.archetypeId];
+  if (archetype === undefined) return undefined;
+  const epochs = graph.tables[archetype.tableId]?.storage.get(componentId)?.epochs;
+  if (epochs === undefined) return undefined;
+  const tableRow = archetype.rows[location.archetypeRow] ?? -1;
+  return {
+    added: epochs.added[tableRow] ?? 0,
+    changed: epochs.changed[tableRow] ?? 0,
+  };
+}
+
+export function markComponentsAdded(
+  graph: ArchetypeGraph,
+  location: EntityLocation,
+  entity: EntityHandle,
+  componentIds: readonly number[],
+  epoch: number,
+): void {
+  const archetype = graph.archetypes[location.archetypeId];
+  const table = archetype === undefined ? undefined : graph.tables[archetype.tableId];
+  const tableRow = archetype?.rows[location.archetypeRow] ?? -1;
+  for (const componentId of componentIds) {
+    const component = archetype?.components.find(
+      (candidate) => componentOwner.componentId(candidate) === componentId,
+    );
+    if (component?.storage === 'sparse') {
+      insertSparseTag(getOrCreateSparseTagSet(graph, component), entity, epoch);
+      continue;
+    }
+    const epochs = table?.storage.get(componentId)?.epochs;
+    if (epochs === undefined) continue;
+    epochs.added[tableRow] = epoch;
+    epochs.changed[tableRow] = epoch;
+  }
+}
+
+export function markComponentChanged(
+  graph: ArchetypeGraph,
+  location: EntityLocation,
+  entity: EntityHandle,
+  componentId: number,
+  epoch: () => number,
+): void {
+  const sparseSet = graph.sparseTags.get(componentId);
+  if (sparseSet !== undefined) {
+    const denseIndex = sparseTagIndex(sparseSet, entity);
+    if (denseIndex >= 0) sparseSet.changed[denseIndex] = epoch();
+    return;
+  }
+  const archetype = graph.archetypes[location.archetypeId];
+  if (archetype === undefined) return;
+  const epochs = graph.tables[archetype.tableId]?.storage.get(componentId)?.epochs;
+  if (epochs === undefined) return;
+  const tableRow = archetype.rows[location.archetypeRow] ?? -1;
+  epochs.changed[tableRow] = epoch();
+}
+
+export function readTableEntityRange(
+  table: Table,
+  rowStart: number,
+  rowCount: number,
+): readonly EntityHandle[] {
+  const entities = table.storage.get(componentOwner.componentId(Entity))?.fields.get('self')
+    ?.view as Uint32Array | undefined;
+  if (entities === undefined) return [];
+  return entities.subarray(rowStart, rowStart + rowCount) as unknown as readonly EntityHandle[];
+}

package/src/storage/column.ts

@@ -0,0 +1,247 @@
+// @forgeax/engine-ecs — per-field independent buffer column storage (D-01).
+//
+// Each component field gets its own ArrayBuffer/SharedArrayBuffer + TypedArray view.
+// This enables independent per-column transfer() expansion and
+// supports dynamic column add/remove during archetype migration.
+//
+// `array<T>` (variable-capacity) fields take TWO columns in archetype layout
+// (D-3): the primary u32 column carries the BufferPool slot id; a sidecar
+// column carries the live element count, named `<fieldName>:count` and
+// keyed by `arrayCountColumnName(fieldName)`. `array<T,N>` (fixed-capacity)
+// fields (feat-20260602) take a SINGLE inline stride-N column (arity = N) --
+// no BufferPool slot id, no sidecar count column. The elements live
+// contiguously per row. `buffer<N>` likewise takes a single stride-N u8
+// column. Variable `buffer` still uses a u32 BufferPool slot id column.
+// Capacity is never stored as an independent column: for variable-capacity
+// fields it is derived from `BufferPool.view(slotId).byteLength /
+// elementBytes`; for fixed-capacity fields the schema-declared N is the
+// capacity.
+
+import { type ComponentSchema, type ScalarFieldType, TYPE_METADATA } from '../component';
+
+// ────────────────────────────────────────────────────────────────────────────
+// ManagedColumnReader — read-only view onto a managed-vocab column
+// (feat-20260614 M4 / D-4 / AC-08 / AC-09 / AC-10)
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Read-only access shape for the 4 managed-vocab column keywords --
+ * `'string'` / `` `ref<T>` `` / variable `'buffer'` / variable `` `array<T>` ``.
+ *
+ * The column carries u32 slot ids (`UniqueRefStore` / `BufferPool`); direct
+ * index assignment would corrupt the slot table. The reader exposes
+ * `.length` + `.get(i): number` so consumers can walk row indices and
+ * retrieve slot ids, then route through the public dispatch (`world.set`,
+ * `world.push`, `world.allocUniqueRef`, etc.) for any mutation.
+ *
+ * Phantom brand `__managed` (D-7 / requirements-decisions q2): the
+ * double-underscore + semantic-word pattern matches `Handle.__handle`. The
+ * brand is a structural-typing safety net; the class name already
+ * disambiguates against `Uint32Array` / `Uint8Array` / fixed inline views.
+ *
+ * Intentionally minimal -- no iterator, no `toArray`, no `slice`. Adding
+ * those invites a "cache the slot ids, mutate later" anti-pattern that
+ * silently desyncs from the live column on the next archetype migration
+ * (charter P4 / plan-strategy §8.4).
+ */
+export interface ManagedColumnReader<T extends string> {
+  readonly length: number;
+  get(i: number): number;
+  readonly __managed: T;
+}
+
+/**
+ * Sidecar column name for the live `count` of an `array<T>` (variable-
+ * capacity) field. Format `<fieldName>:count` keeps the suffix outside the
+ * legal user-facing schema name space (the colon is forbidden in user
+ * field names by convention) so the archetype Map can carry both columns
+ * under one `Map<fieldName, Column>` keyed namespace without collision
+ * (D-3 double-column allocation in M1 / w7).
+ */
+export function arrayCountColumnName(fieldName: string): string {
+  return `${fieldName}:count`;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Column: one field's storage
+// ────────────────────────────────────────────────────────────────────────────
+
+/** TypedArray view types used by columns. */
+export type FieldView =
+  | Float32Array
+  | Float64Array
+  | Int32Array
+  | Uint32Array
+  | Int16Array
+  | Uint16Array
+  | Int8Array
+  | Uint8Array;
+
+type FieldViewConstructor = new (buffer: ArrayBufferLike) => FieldView;
+
+function createFieldView(
+  Ctor: NonNullable<(typeof TYPE_METADATA)[string]['viewCtor']>,
+  buffer: ArrayBufferLike,
+): FieldView {
+  return new (Ctor as FieldViewConstructor)(buffer);
+}
+
+function isSharedBuffer(buffer: ArrayBufferLike): buffer is SharedArrayBuffer {
+  return typeof SharedArrayBuffer !== 'undefined' && buffer instanceof SharedArrayBuffer;
+}
+
+/** A single column: one field's ArrayBuffer + TypedArray view. */
+export interface Column {
+  buffer: ArrayBuffer | SharedArrayBuffer;
+  view: FieldView;
+  capacity: number;
+  fieldType: ScalarFieldType;
+  /**
+   * Number of elements per row (stride). Scalar and variable-capacity columns
+   * default to 1 (one u32 slot id or one scalar value per row). Fixed-capacity
+   * `array<T,N>` / `buffer<N>` inline columns (feat-20260602) have arity = N.
+   *
+   * For inline columns, the TypedArray view returned by `col.view.subarray()`
+   * aliases the column buffer directly. The view is transient: `growColumn`
+   * detaches the old `ArrayBuffer` via `transfer()`, so callers must re-fetch
+   * the view after any structural change. See `packages/ecs/README.md`
+   * Transient view contract section.
+   */
+  arity: number;
+}
+
+/**
+ * Create a column for a single field with given capacity.
+ *
+ * @param fieldType - scalar storage type for the column view ctor
+ * @param capacity - number of rows
+ * @param arity - elements per row (stride); default 1 for scalar/variable columns
+ */
+export function createColumn(
+  fieldType: ScalarFieldType,
+  capacity: number,
+  arity = 1,
+  shared = false,
+): Column {
+  const meta = TYPE_METADATA[fieldType];
+  if (!meta) throw new Error(`Missing TYPE_METADATA entry for scalar field type ${fieldType}`);
+  const bytesPerElement =
+    // biome-ignore lint/style/noNonNullAssertion: ScalarFieldType rows always carry a byteSize
+    meta.byteSize!;
+  const buffer = shared
+    ? new SharedArrayBuffer(bytesPerElement * capacity * arity)
+    : new ArrayBuffer(bytesPerElement * capacity * arity);
+  // biome-ignore lint/style/noNonNullAssertion: ScalarFieldType rows always carry a viewCtor
+  const Ctor = meta.viewCtor!;
+  const view = createFieldView(Ctor, buffer);
+  return { buffer, view, capacity, fieldType, arity };
+}
+
+/**
+ * Module-level cache for `ArrayBuffer.prototype.transfer` support (O-1).
+ * Checked once at import time; avoids per-call feature detection overhead.
+ *
+ * Note: `transfer()` is ES2024. We use runtime feature detection + type cast
+ * so that tsconfig does not need `lib: ["es2024"]`.
+ */
+export const HAS_TRANSFER: boolean =
+  typeof (ArrayBuffer.prototype as { transfer?: unknown }).transfer === 'function';
+
+/**
+ * Grow a column to a new capacity, preserving existing data.
+ * Returns a new Column; the old column is not modified.
+ *
+ * When the runtime supports `ArrayBuffer.transfer()` (ES2024, Node 22+,
+ * modern browsers), uses zero-copy buffer transfer. Otherwise falls back
+ * to `new ArrayBuffer` + `Uint8Array.set` copy.
+ *
+ * Both paths produce data-equivalent results (O-1 acceptance criterion).
+ */
+export function growColumn(col: Column, newCapacity: number): Column {
+  const meta = TYPE_METADATA[col.fieldType];
+  if (!meta) throw new Error(`Missing TYPE_METADATA entry for scalar field type ${col.fieldType}`);
+  const bytesPerElement =
+    // biome-ignore lint/style/noNonNullAssertion: ScalarFieldType rows always carry a byteSize
+    meta.byteSize!;
+  const newByteLength = bytesPerElement * newCapacity * col.arity;
+  // biome-ignore lint/style/noNonNullAssertion: ScalarFieldType rows always carry a viewCtor
+  const Ctor = meta.viewCtor!;
+
+  let buffer: ArrayBuffer | SharedArrayBuffer;
+  if (isSharedBuffer(col.buffer)) {
+    buffer = new SharedArrayBuffer(newByteLength);
+    new Uint8Array(buffer).set(new Uint8Array(col.buffer));
+  } else if (HAS_TRANSFER) {
+    // Zero-copy path: transfer() resizes the underlying buffer in-place
+    // and detaches the source. The old column's buffer becomes detached,
+    // but we return a new Column object so callers never touch the old one.
+    buffer = (col.buffer as unknown as { transfer(newByteLength: number): ArrayBuffer }).transfer(
+      newByteLength,
+    );
+  } /* istanbul ignore next -- fallback for runtimes without ES2024 transfer() */ else {
+    // Fallback path: allocate new buffer + byte-level copy.
+    buffer = new ArrayBuffer(newByteLength);
+    new Uint8Array(buffer).set(new Uint8Array(col.buffer));
+  }
+
+  const view = createFieldView(Ctor, buffer);
+  return { buffer, view, capacity: newCapacity, fieldType: col.fieldType, arity: col.arity };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Buffer-write input normalization (feat-20260621 V2 / AC-A4)
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Normalize a `'buffer'` / `'buffer<N>'` write payload to a `Uint8Array` view
+ * over its raw bytes. The write surface (`FieldInputType<'buffer'>`) accepts
+ * any `AllowSharedBufferSource` (Float32Array / ArrayBuffer / Uint8Array / any
+ * TypedArray); the column store and read side speak `Uint8Array` only. This is
+ * the single ingestion point that bridges the two — a strict superset of the
+ * prior Uint8Array-only behavior (an existing `Uint8Array` caller round-trips
+ * through `new Uint8Array(buffer, byteOffset, byteLength)`, same bytes, same
+ * length), so existing callers see zero behavior change.
+ *
+ * Returns `null` for non-buffer-source inputs (e.g. a forced cast feeding a
+ * number) so callers keep their existing "no-op / alloc(0)" branch for raw
+ * that is not a real buffer view.
+ */
+export function normalizeBufferWrite(raw: unknown): Uint8Array | null {
+  if (raw instanceof Uint8Array) {
+    return raw;
+  }
+  if (ArrayBuffer.isView(raw)) {
+    return new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+  }
+  if (raw instanceof ArrayBuffer) {
+    return new Uint8Array(raw);
+  }
+  if (typeof SharedArrayBuffer !== 'undefined' && raw instanceof SharedArrayBuffer) {
+    return new Uint8Array(raw);
+  }
+  return null;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Hot/cold classification
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Determine if a schema is "hot" (all fields are scalar → TypedArray SoA).
+ * Returns true if all fields are in the scalar field type set.
+ * Empty schema (tag component) returns true by convention (vacuously true).
+ *
+ * Schema-vocab keywords (`buffer:<N>` / `ref<T>` / `handle<T>` / `entity` /
+ * `array<T,N>` / `array<T>`) are explicitly cold — their storage is owned by
+ * separate subsystems (UniqueRefStore / BufferPool), not the column SoA path. The keyword check uses an unsafe narrowing because
+ * `SchemaFieldType` is wider than the set's `ScalarFieldType` element type;
+ * the `has` test is the runtime gate.
+ */
+export function isHotSchema(schema: ComponentSchema): boolean {
+  for (const fieldType of Object.values(schema)) {
+    if (!TYPE_METADATA[fieldType]?.isScalar) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/storage/table.ts

@@ -0,0 +1,153 @@
+import {
+  bufferFieldByteLength,
+  type Component,
+  type ComponentId,
+  componentId,
+  componentSchema,
+  fieldTypeToMetaKey,
+  isManagedBufferField,
+  parseManagedArraySchema,
+  type ScalarFieldType,
+  TYPE_METADATA,
+} from '../component';
+import { Entity, foldEssentials } from '../entity';
+import type { EntityHandle } from '../entity-handle';
+import {
+  type ComponentEpochColumns,
+  copyComponentEpoch,
+  createComponentEpochColumns,
+  growComponentEpochColumns,
+} from './change-detection';
+import { arrayCountColumnName, type Column, createColumn, growColumn } from './column';
+
+const INITIAL_CAPACITY = 64;
+
+export type TableId = number;
+
+export interface TableComponentStorage {
+  readonly component: Component;
+  fields: Map<string, Column>;
+  epochs: ComponentEpochColumns;
+}
+
+export interface Table {
+  readonly id: TableId;
+  readonly key: string;
+  readonly components: ReadonlyArray<Component>;
+  storage: Map<ComponentId, TableComponentStorage>;
+  size: number;
+  capacity: number;
+  version: number;
+}
+
+export function tableKey(componentIds: ReadonlyArray<ComponentId>): string {
+  return [...foldEssentials(componentIds)].sort((a, b) => a - b).join('+');
+}
+
+export function canonicalComponents(components: ReadonlyArray<Component>): Component[] {
+  const byId = new Map<ComponentId, Component>();
+  byId.set(componentId(Entity), Entity as unknown as Component);
+  for (const component of components) byId.set(componentId(component), component);
+  return [...byId.values()].sort((a, b) => componentId(a) - componentId(b));
+}
+
+export function createTable(
+  components: ReadonlyArray<Component>,
+  id: TableId,
+  shared = false,
+): Table {
+  const sortedComponents = canonicalComponents(components);
+  const capacity = INITIAL_CAPACITY;
+  const storage = new Map<ComponentId, TableComponentStorage>();
+  for (const component of sortedComponents) {
+    const fields = new Map<string, Column>();
+    for (const [fieldName, fieldType] of Object.entries(componentSchema(component))) {
+      const arrayMeta = parseManagedArraySchema(fieldType);
+      if (arrayMeta !== null && arrayMeta.length !== undefined) {
+        const metaKey = fieldTypeToMetaKey(arrayMeta.elementType);
+        const scalarType: ScalarFieldType | null =
+          metaKey === null ? null : (TYPE_METADATA[metaKey]?.storage ?? null);
+        if (scalarType !== null) {
+          fields.set(fieldName, createColumn(scalarType, capacity, arrayMeta.length, shared));
+        }
+        continue;
+      }
+      if (isManagedBufferField(fieldType) && fieldType !== 'buffer') {
+        fields.set(
+          fieldName,
+          createColumn('u8', capacity, bufferFieldByteLength(fieldType), shared),
+        );
+        continue;
+      }
+      const metaKey = fieldTypeToMetaKey(fieldType);
+      const scalarType: ScalarFieldType | null =
+        metaKey === null ? null : (TYPE_METADATA[metaKey]?.storage ?? null);
+      if (scalarType === null) continue;
+      fields.set(fieldName, createColumn(scalarType, capacity, 1, shared));
+      if (arrayMeta !== null && arrayMeta.length === undefined) {
+        fields.set(arrayCountColumnName(fieldName), createColumn('u32', capacity, 1, shared));
+      }
+    }
+    storage.set(componentId(component), {
+      component,
+      fields,
+      epochs: createComponentEpochColumns(capacity),
+    });
+  }
+  return {
+    id,
+    key: tableKey(sortedComponents.map((component) => componentId(component))),
+    components: sortedComponents,
+    storage,
+    size: 0,
+    capacity,
+    version: 0,
+  };
+}
+
+export function appendTableRow(table: Table, entity: EntityHandle): number {
+  if (table.size === table.capacity) growTable(table, table.capacity * 2);
+  const row = table.size;
+  const self = table.storage.get(componentId(Entity))?.fields.get('self');
+  if (self !== undefined) self.view[row] = entity as number;
+  table.size = row + 1;
+  return row;
+}
+
+export function removeTableRow(
+  table: Table,
+  row: number,
+): { movedEntity: EntityHandle; newRow: number } | null {
+  const lastRow = table.size - 1;
+  if (row === lastRow) {
+    table.size = lastRow;
+    return null;
+  }
+  const movedEntity = (table.storage.get(componentId(Entity))?.fields.get('self')?.view[lastRow] ??
+    0) as EntityHandle;
+  for (const componentStorage of table.storage.values()) {
+    for (const column of componentStorage.fields.values()) {
+      const arity = column.arity;
+      column.view.set(column.view.subarray(lastRow * arity, lastRow * arity + arity), row * arity);
+    }
+    copyComponentEpoch(componentStorage.epochs, lastRow, componentStorage.epochs, row);
+  }
+  table.size = lastRow;
+  return { movedEntity, newRow: row };
+}
+
+export function growTable(table: Table, targetCapacity: number): void {
+  let capacity = table.capacity;
+  while (capacity < targetCapacity) capacity *= 2;
+  if (capacity === table.capacity) return;
+  for (const componentStorage of table.storage.values()) {
+    const fields = new Map<string, Column>();
+    for (const [fieldName, column] of componentStorage.fields) {
+      fields.set(fieldName, growColumn(column, capacity));
+    }
+    componentStorage.fields = fields;
+    componentStorage.epochs = growComponentEpochColumns(componentStorage.epochs, capacity);
+  }
+  table.capacity = capacity;
+  table.version += 1;
+}