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

package/src/shared-ref-store.ts

@@ -0,0 +1,418 @@
+// @forgeax/engine-ecs - SharedRefStore.
+//
+// Reference-counted store for AssetRegistry-style shared handles. Schema vocab
+// `shared<T>` fields derive `Handle<T, 'shared'>` whose lifecycle is tracked
+// by retain/release on the holder side - allocators (typically the asset
+// registry) call `alloc` once and let consumers retain/release as the asset
+// flows through ECS components and external systems. When rc transitions
+// 1 -> 0 the store publishes release evidence. External owners dispose their
+// payloads from their own lifecycle effects; ECS does not invoke callbacks.
+//
+// Companion to UniqueRefStore (1-holder-direct-release semantics). The two
+// stores share storage shape and code patterns; only the lifecycle differs:
+//
+//   UniqueRefStore: alloc -> store; release -> drop. No retain.
+//   SharedRefStore: alloc -> rc=1; retain -> rc++; release -> rc--; rc=0 -> drop.
+//
+// §contract - shared handles are refcounted AND carry a generation
+//   The handle u32 packs `(generation << 24) | slot` via the shared codec in
+//   `@forgeax/engine-types` (same SSOT codec as UniqueRefStore and ECS
+//   EntityHandle). `alloc` welds the slot's current generation; resolve /
+//   retain / release compare the handle generation against
+//   `_generations[slot]` BEFORE any refcount/payload work, so a handle whose
+//   slot was released and re-allocated returns `SharedRefStaleError`
+//   ('shared-ref-stale') instead of silently resolving the next payload.
+//   Generation advances on the rc=0 drop and retires the slot when gen would
+//   exceed MAX_GEN (gen 255 is still usable; retire at would-be 256, no wrap).
+//   AI users keep the rule "don't cache a handle
+//   past release" - the AssetRegistry mediates most shared handle lifecycles,
+//   but a stale handle now fails structurally rather than silently.
+//
+// §tier boundary (feat-20260614 M6 D-15)
+//   This store manages ONLY user-tier slots (`slot >= BUILTIN_BASE`). Builtin
+//   asset payloads in the builtin range are process-static and live in their
+//   authoring package; they
+//   are never reference-counted. `nextSlot` starts at `BUILTIN_BASE` so minted
+//   handles never collide with builtin slots, and alloc/retain/release/resolve
+//   fail-fast with `BuiltinSlotNotOwnedError` when handed a builtin slot.
+//
+// Storage shape:
+//   - `payloads: Map<number, unknown>` - key = handle u32 = slot index.
+//   - `refcounts: Map<number, number>` - key = handle u32; rc >= 1 while live;
+//                                  removed (not set to 0) on final release
+//                                  so resolve / retain can detect the
+//                                  released state via `payloads.has(raw)`.
+//   - `freeSlots: number[]`        - LIFO stack of recyclable slot indices.
+//   - `nextSlot`                   - bump counter for the never-recycled tail
+//                                  (starts at BUILTIN_BASE; user tier only).
+//
+// 24 bits = 16_777_215 simultaneous live shared handles - same ceiling as
+// UniqueRefStore + Entity, so the three managed-handle resources fail-fast
+// at the same bound.
+//
+// Release path (D-1 codes):
+//   - resolve(h): err(SharedRefReleasedError)        if payload absent.
+//   - markChanged(h): publish an in-place payload mutation to subscribers.
+//   - retain(h):  err(SharedRefReleasedError)        if payload absent.
+//   - release(h): err(SharedRefDoubleReleaseError, rc=0) on rc=0 input.
+//   - any(builtin slot): err(BuiltinSlotNotOwnedError) (D-15).
+//
+// Identity invariant (mirrors UniqueRefStore): resolve(h) returns the SAME
+// payload object on every call until the final release. Archetype migration
+// preserves this trivially - the column carries the u32 handle, never the
+// payload reference.
+
+import type { Handle } from '@forgeax/engine-types';
+import {
+  BUILTIN_BASE,
+  err,
+  handleGeneration,
+  handleSlot,
+  isRetiredSlot,
+  MAX_SLOT,
+  ok,
+  pack,
+  type Result,
+  toShared,
+  unwrapHandle,
+} from '@forgeax/engine-types';
+import {
+  BuiltinSlotNotOwnedError,
+  SharedRefDoubleReleaseError,
+  SharedRefPayloadInvalidError,
+  SharedRefReleasedError,
+  SharedRefStaleError,
+} from './errors';
+
+const SHARED_REF_MUTATION_JOURNAL_CAPACITY = 4096;
+
+export interface SharedRefMutation {
+  readonly epoch: number;
+  readonly handle: number;
+}
+
+export interface SharedRefReleaseEvidence {
+  readonly payload: unknown;
+  readonly refcount: 0;
+  readonly generation: number;
+  readonly evidence: 'released';
+}
+
+export type SharedRefMutationRead =
+  | {
+      readonly status: 'ok';
+      readonly cursor: number;
+      readonly records: readonly SharedRefMutation[];
+    }
+  | {
+      readonly status: 'overflow';
+      readonly cursor: number;
+      readonly oldestAvailable: number;
+    };
+
+// MAX_SLOT is now imported from @forgeax/engine-types (codec SSOT, D-1).
+// The local constant is removed to avoid drift (AC-15).
+
+/**
+ * Reference-counted store for ECS-aware `Handle<T, 'shared'>` lifecycles.
+ *
+ * The producer (typically AssetRegistry) calls `alloc` once and owns the
+ * "alloc-grant" rc=1; consumers (ECS schema fields, external systems) call
+ * `retain` on each new holder and `release` when the holder drops. When rc
+ * transitions 1 -> 0 the store publishes one structured release-evidence
+ * record; it does not invoke a user callback or own payload disposal.
+ *
+ * D-15: manages ONLY user-tier slots (`slot >= BUILTIN_BASE`). Builtin slots
+ * (`< BUILTIN_BASE`) fail-fast with `BuiltinSlotNotOwnedError`.
+ *
+ * Public API:
+ *   - alloc(target, payload)        -> Handle<T, 'shared'> (rc=1)
+ *   - intern(target, payload)        -> stable producer handle per target + object identity
+ *   - resolve(handle)             -> Result<T, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError>
+ *   - markChanged(handle)         -> Result<void, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError>
+ *   - getMutationEpoch()          -> monotonic payload-mutation cursor
+ *   - retain(handle)              -> Result<void, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError>
+ *   - release(handle)             -> Result<release evidence | undefined, ...>
+ *   - refcount(handle)            -> number (0 == released; debug + tests)
+ *   - _liveCount()                -> live slot count (debug + inspector)
+ */
+export class SharedRefStore {
+  private readonly payloads = new Map<number, unknown>();
+  private readonly refcounts = new Map<number, number>();
+  private readonly freeSlots: number[] = [];
+  private readonly internedByTarget = new Map<string, WeakMap<object, number>>();
+  private readonly internedKeys = new Map<
+    number,
+    { readonly target: string; readonly payload: object }
+  >();
+  private nextSlot = BUILTIN_BASE;
+  private mutationEpoch = 0;
+  private readonly mutationJournal: SharedRefMutation[] = [];
+  private readonly releaseJournal: SharedRefReleaseEvidence[] = [];
+
+  /**
+   * Generation table indexed by slot (D-6). Each entry tracks the current
+   * generation for the slot — written to during alloc (welded into the
+   * returned handle via pack) and incremented on release (M4).
+   *
+   * @internal
+   */
+  // biome-ignore lint/style/useNamingConvention: internal field — @internal JSDoc suppresses lint:internal gate
+  private readonly _generations: number[] = [];
+
+  /**
+   * Allocate a fresh shared handle for `payload`, branded against `target`.
+   * Refcount starts at 1 (the alloc-grant). Nullish payloads are rejected
+   * before a slot or free-list is touched.
+   *
+   * The returned handle carries a generation tag welded via codec.pack
+   * (D-8, OOS-2): first allocation gen=0 (AC-06), reused slot gen = the
+   * current generation from _generations[slot]. The toShared brand cast
+   * happens internally — external callers no longer construct Handle<...>
+   * directly.
+   *
+   * Minted slots are user-tier (`>= BUILTIN_BASE`); builtin slots are never
+   * produced here (D-15).
+   */
+  alloc<Target extends string, T = unknown>(target: Target, payload: T): Handle<Target, 'shared'> {
+    void target; // target is a phantom - tag flows only at the type level via Handle<Target,_>.
+    if (payload === null || payload === undefined) {
+      throw new SharedRefPayloadInvalidError(target, payload === null ? 'null' : 'undefined');
+    }
+    const slot = this.freeSlots.pop() ?? this.nextSlot++;
+    if (slot > MAX_SLOT) {
+      throw new RangeError(
+        `SharedRefStore: slot index ${slot} exceeds 24-bit max (${MAX_SLOT}). ` +
+          'Reduce simultaneous shared handles or investigate handle leaks.',
+      );
+    }
+    const gen = this._generations[slot] ?? 0;
+    const raw = pack(slot, gen);
+    this.payloads.set(raw, payload);
+    this.refcounts.set(raw, 1);
+    return toShared(raw);
+  }
+
+  /**
+   * Return the idempotent producer handle for one object payload in this
+   * store. Identity includes `target`, so the same object branded for two
+   * asset kinds does not alias.
+   *
+   * A cache hit deliberately does not retain: this is one producer grant,
+   * discovered repeatedly by an asset catalogue. Actual holders retain and
+   * release through the ECS write barrier. Callers needing independent
+   * grants or a per-handle deleter must use {@link alloc}.
+   */
+  intern<Target extends string, T extends object>(
+    target: Target,
+    payload: T,
+  ): Handle<Target, 'shared'> {
+    let byPayload = this.internedByTarget.get(target);
+    if (byPayload === undefined) {
+      byPayload = new WeakMap<object, number>();
+      this.internedByTarget.set(target, byPayload);
+    }
+
+    const existingRaw = byPayload.get(payload);
+    if (existingRaw !== undefined && this.payloads.has(existingRaw)) {
+      return toShared(existingRaw);
+    }
+
+    const handle = this.alloc(target, payload);
+    const raw = unwrapHandle(handle);
+    byPayload.set(payload, raw);
+    this.internedKeys.set(raw, { target, payload });
+    return handle;
+  }
+
+  /**
+   * Look up `payload` by handle. Returns `err(shared-ref-released)` when
+   * the handle's slot has no live payload (rc reached 0, no re-alloc has
+   * filled the slot); `err(builtin-slot-not-owned)` for a builtin slot.
+   *
+   * §contract - mirrors UniqueRefStore: a stale handle whose slot has been
+   * released and re-allocated returns `err(shared-ref-stale)` - the handle's
+   * welded generation no longer matches `_generations[slot]`. The gen check
+   * runs before payload lookup, so stale-by-reuse is caught deterministically.
+   */
+  resolve<Target extends string, T = unknown>(
+    handle: Handle<Target, 'shared'>,
+  ): Result<T, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError> {
+    const raw = unwrapHandle(handle);
+    if (raw < BUILTIN_BASE) return err(new BuiltinSlotNotOwnedError(raw));
+    // Gen comparison (M4): extract slot + handle gen, compare against
+    // store's current gen. Mismatch means slot was released and re-allocated —
+    // the caller's handle is stale. This check runs BEFORE payload lookup so
+    // stale-by-reuse is always caught (AC-01).
+    const slot = handleSlot(handle);
+    const handleGen = handleGeneration(handle);
+    const storeGen = this._generations[slot] ?? 0;
+    if (handleGen !== storeGen) {
+      return err(new SharedRefStaleError(slot, handleGen, storeGen));
+    }
+    const payload = this.payloads.get(raw);
+    if (payload === undefined) {
+      return err(new SharedRefReleasedError(raw, '<unknown>'));
+    }
+    return ok(payload as T);
+  }
+
+  /**
+   * Publish that a live payload was mutated in place. Consumers that retain
+   * projections of shared payload data compare the monotonic epoch and
+   * explicitly refresh instead of rescanning every payload each frame.
+   */
+  markChanged<Target extends string>(
+    handle: Handle<Target, 'shared'>,
+  ): Result<void, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError> {
+    const resolved = this.resolve(handle);
+    if (!resolved.ok) return resolved;
+    if (this.mutationEpoch >= Number.MAX_SAFE_INTEGER) {
+      throw new RangeError('SharedRefStore mutation epoch exhausted');
+    }
+    this.mutationEpoch += 1;
+    this.mutationJournal.push({ epoch: this.mutationEpoch, handle: unwrapHandle(handle) });
+    if (this.mutationJournal.length > SHARED_REF_MUTATION_JOURNAL_CAPACITY) {
+      this.mutationJournal.shift();
+    }
+    return ok(undefined);
+  }
+
+  /** Current upper bound for explicitly published payload mutations. */
+  getMutationEpoch(): number {
+    return this.mutationEpoch;
+  }
+
+  /** Read exact changed handles after `cursor`; overflow requires consumer resync. */
+  readChangesSince(cursor: number): SharedRefMutationRead {
+    const oldestAvailable = this.mutationJournal[0]?.epoch ?? this.mutationEpoch + 1;
+    if (cursor < oldestAvailable - 1) {
+      return { status: 'overflow', cursor: this.mutationEpoch, oldestAvailable };
+    }
+    return {
+      status: 'ok',
+      cursor: this.mutationEpoch,
+      records: this.mutationJournal.filter((record) => record.epoch > cursor),
+    };
+  }
+
+  /**
+   * Increment the refcount of a live shared handle. Returns
+   * `err(shared-ref-released)` when the handle is not live - retain MUST
+   * NOT resurrect a released slot (charter P3 explicit failure; would
+   * defeat the rc=0 -> drop invariant); `err(builtin-slot-not-owned)` for a
+   * builtin slot.
+   */
+  retain<Target extends string>(
+    handle: Handle<Target, 'shared'>,
+  ): Result<void, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError> {
+    const raw = unwrapHandle(handle);
+    if (raw < BUILTIN_BASE) return err(new BuiltinSlotNotOwnedError(raw));
+    // Gen comparison runs before rc read (q12: all three operations compare gen first).
+    const slot = handleSlot(handle);
+    const handleGen = handleGeneration(handle);
+    const storeGen = this._generations[slot] ?? 0;
+    if (handleGen !== storeGen) {
+      return err(new SharedRefStaleError(slot, handleGen, storeGen));
+    }
+    const rc = this.refcounts.get(raw);
+    if (rc === undefined) {
+      return err(new SharedRefReleasedError(raw, '<unknown>'));
+    }
+    this.refcounts.set(raw, rc + 1);
+    return ok(undefined);
+  }
+
+  /**
+   * Decrement the refcount. When rc transitions 1 -> 0, the slot is dropped
+   * and one structured release-evidence record is published. The evidence
+   * captures the payload, zero refcount, next generation and `released` marker
+   * after the store has removed the live slot.
+   *
+   * Returns `err(shared-ref-double-release, rc=0)` when the handle has
+   * already reached rc=0 (or was never live); `err(builtin-slot-not-owned)`
+   * for a builtin slot. AI users branch on `.code` and route the
+   * second-release log to Layer 3 ErrorHandler without aborting the despawn
+   * chain.
+   */
+  release<Target extends string>(
+    handle: Handle<Target, 'shared'>,
+  ): Result<
+    SharedRefReleaseEvidence | undefined,
+    SharedRefDoubleReleaseError | SharedRefStaleError | BuiltinSlotNotOwnedError
+  > {
+    const raw = unwrapHandle(handle);
+    if (raw < BUILTIN_BASE) return err(new BuiltinSlotNotOwnedError(raw));
+    // Gen comparison runs FIRST — before rc read, before any mutation (q12).
+    const slot = handleSlot(handle);
+    const handleGen = handleGeneration(handle);
+    const storeGen = this._generations[slot] ?? 0;
+    if (handleGen !== storeGen) {
+      // AC-03: stale release MUST NOT touch rc / payload / freeSlots.
+      return err(new SharedRefStaleError(slot, handleGen, storeGen));
+    }
+    const rc = this.refcounts.get(raw);
+    if (rc === undefined) {
+      return err(new SharedRefDoubleReleaseError(raw, '<unknown>', 0));
+    }
+    if (rc > 1) {
+      this.refcounts.set(raw, rc - 1);
+      return ok(undefined);
+    }
+    // rc === 1 -> drop. Capture the payload for release evidence before
+    // clearing the live slot; nullish payloads never enter the store.
+    const payload = this.payloads.get(raw);
+    const internedKey = this.internedKeys.get(raw);
+    if (internedKey !== undefined) {
+      const byPayload = this.internedByTarget.get(internedKey.target);
+      if (byPayload?.get(internedKey.payload) === raw) {
+        byPayload.delete(internedKey.payload);
+      }
+      this.internedKeys.delete(raw);
+    }
+    this.refcounts.delete(raw);
+    this.payloads.delete(raw);
+    // Gen increment + retire (AC-07): bump gen; once it would exceed MAX_GEN
+    // (gen 255 is still usable; the bump to 256 triggers retire) the slot is
+    // permanently retired — NOT pushed to freeSlots. This prevents handle
+    // aliasing. Shares the isRetiredSlot SSOT predicate with EntityHandle.
+    const generation = storeGen + 1;
+    this._generations[slot] = generation;
+    if (!isRetiredSlot(generation)) {
+      this.freeSlots.push(slot);
+    }
+    // else: slot retired (gen exceeded MAX_GEN) - never returns to freeSlots.
+    const evidence = Object.freeze({
+      payload,
+      refcount: 0 as const,
+      generation,
+      evidence: 'released' as const,
+    });
+    this.releaseJournal.push(evidence);
+    if (this.releaseJournal.length > SHARED_REF_MUTATION_JOURNAL_CAPACITY) {
+      this.releaseJournal.shift();
+    }
+    return ok(evidence);
+  }
+
+  /** Read the bounded release evidence owned by this store. */
+  readReleaseEvidence(): readonly SharedRefReleaseEvidence[] {
+    return this.releaseJournal;
+  }
+
+  /**
+   * Return the current refcount for `handle`. Returns 0 for a released
+   * (or never-allocated) slot. Primarily a debug + tests entry point;
+   * production code rarely reads rc directly (the rc=0 -> drop invariant
+   * is the surface AI users consume via release / the per-handle deleter).
+   */
+  refcount<Target extends string>(handle: Handle<Target, 'shared'>): number {
+    const raw = unwrapHandle(handle);
+    return this.refcounts.get(raw) ?? 0;
+  }
+
+  /** @internal Diagnostic count of live slots. Exposed for tests + inspector. */
+  _liveCount(): number {
+    return this.payloads.size;
+  }
+}

package/src/shared.ts

@@ -0,0 +1,23 @@
+export type {
+  KernelDispatchFailure,
+  KernelDispatchResult,
+  KernelDispatchSpan,
+  SharedFieldView,
+  SharedKernelDefinition,
+  SharedKernelDispatch,
+  SharedKernelEligibilityReason,
+  SharedKernelExecutor,
+  SharedKernelHandle,
+  SharedSpanBinding,
+  WorldExecutionHealth,
+} from './execution/shared-kernel';
+export {
+  bindSharedSpan,
+  defineSharedKernel,
+  isKernelDispatchFailure,
+  isSharedSpan,
+  SHARED_KERNEL_ELIGIBILITY_REASONS,
+  SHARED_KERNEL_EXECUTOR_RESOURCE_KEY,
+  sharedKernelEligibility,
+  splitSharedSpan,
+} from './execution/shared-kernel';

package/src/storage/archetype-graph.ts

@@ -0,0 +1,166 @@
+// @forgeax/engine-ecs — ArchetypeGraph: manages archetype creation and edge caching.
+//
+// O(1) archetype migration lookup via cached edges (D-02 / Finding 2).
+// Global `generation` counter incremented on each new archetype creation
+// (ArchetypeGeneration for query cache incremental update).
+
+import type { Component, ComponentId } from '../component';
+import * as componentOwner from '../component';
+import { type Archetype, type ArchetypeId, archetypeKey, createArchetype } from './archetype';
+import { createSparseTagSet, type SparseTagSet } from './change-detection';
+import { canonicalComponents, createTable, type Table, type TableId, tableKey } from './table';
+
+/**
+ * The ArchetypeGraph owns all archetypes and their edge caches.
+ *
+ * `archetypes` is the SSOT: a dense array indexed by `ArchetypeId` (the id is
+ * allocated as the next array slot, so `archetypes[id].id === id`).
+ * `dedupByKey` is a derived index `key → ArchetypeId` used only at archetype
+ * creation to dedupe; consumers always read through `archetypes[id]`
+ * (architecture-principles.md §1 SSOT, §2 Derive — replaces the historical
+ * `byKey: Map<string, Archetype>` / `byId: Archetype[]` pair which carried two
+ * full Archetype refs per row).
+ */
+export interface ArchetypeGraph {
+  /** SSOT: dense array indexed by `ArchetypeId` (id == array slot). */
+  archetypes: Archetype[];
+  /** Derived dedup index: canonical-key string → ArchetypeId. */
+  dedupByKey: Map<string, ArchetypeId>;
+  /** Global generation counter. Incremented on each new archetype. */
+  generation: number;
+  tables: Table[];
+  tableDedupByKey: Map<string, TableId>;
+  tableGeneration: number;
+  sparseTags: Map<ComponentId, SparseTagSet>;
+  readonly shared: boolean;
+}
+
+/**
+ * Create a fresh ArchetypeGraph.
+ */
+export function createArchetypeGraph(shared = false): ArchetypeGraph {
+  return {
+    archetypes: [],
+    dedupByKey: new Map(),
+    generation: 0,
+    tables: [],
+    tableDedupByKey: new Map(),
+    tableGeneration: 0,
+    sparseTags: new Map(),
+    shared,
+  };
+}
+
+export function getTable(graph: ArchetypeGraph, id: TableId): Table {
+  const table = graph.tables[id];
+  if (table === undefined) throw new Error(`Table ${id} does not exist.`);
+  return table;
+}
+
+export function getOrCreateTable(
+  graph: ArchetypeGraph,
+  components: ReadonlyArray<Component>,
+): Table {
+  const tableComponents = canonicalComponents(
+    components.filter((component) => component.storage === 'table'),
+  );
+  const key = tableKey(tableComponents.map((component) => componentOwner.componentId(component)));
+  const existingId = graph.tableDedupByKey.get(key);
+  if (existingId !== undefined) return getTable(graph, existingId);
+  const table = createTable(tableComponents, graph.tables.length, graph.shared);
+  graph.tables.push(table);
+  graph.tableDedupByKey.set(key, table.id);
+  graph.tableGeneration += 1;
+  return table;
+}
+
+export function getOrCreateSparseTagSet(graph: ArchetypeGraph, component: Component): SparseTagSet {
+  const current = graph.sparseTags.get(componentOwner.componentId(component));
+  if (current !== undefined) return current;
+  const set = createSparseTagSet(component);
+  graph.sparseTags.set(componentOwner.componentId(component), set);
+  return set;
+}
+
+/**
+ * Get or create an archetype for the given component set.
+ * ComponentIds are sorted to produce a canonical key.
+ */
+export function getOrCreateArchetype(
+  graph: ArchetypeGraph,
+  componentIds: ReadonlyArray<ComponentId>,
+  components: ReadonlyArray<Component>,
+): Archetype {
+  const key = archetypeKey(componentIds);
+  const existingId = graph.dedupByKey.get(key);
+  if (existingId !== undefined) {
+    // biome-ignore lint/style/noNonNullAssertion: dedupByKey only ever holds ids that were pushed into archetypes[].
+    return graph.archetypes[existingId]!;
+  }
+
+  const fullComponents = canonicalComponents(components);
+  const table = getOrCreateTable(graph, fullComponents);
+  const archId = graph.archetypes.length;
+  const arch = createArchetype(fullComponents, archId, table.id);
+  graph.archetypes.push(arch);
+  graph.dedupByKey.set(key, archId);
+  graph.generation += 1;
+  return arch;
+}
+
+/**
+ * Get the target archetype after adding `componentId` to `src`.
+ * Caches the edge for O(1) subsequent lookups.
+ */
+export function getAddEdge(
+  graph: ArchetypeGraph,
+  src: Archetype,
+  componentId: ComponentId,
+  component: Component,
+): Archetype {
+  const cached = src.addEdges.get(componentId);
+  if (cached !== undefined) {
+    const target = graph.archetypes[cached];
+    if (target) {
+      return target;
+    }
+  }
+
+  // Compute target archetype: src components + new component.
+  const newIds = [...src.components.map((c) => componentOwner.componentId(c)), componentId];
+  const newComponents = [...src.components, component];
+  const target = getOrCreateArchetype(graph, newIds, newComponents);
+  src.addEdges.set(componentId, target.id);
+  return target;
+}
+
+/**
+ * Get the target archetype after removing `componentId` from `src`.
+ * Caches the edge for O(1) subsequent lookups.
+ *
+ * Component list is derived from `src.components.filter(c => componentOwner.componentId(c) !== componentId)`
+ * (no separate componentRegistry — feat-20260611 AC-09).
+ */
+export function getRemoveEdge(
+  graph: ArchetypeGraph,
+  src: Archetype,
+  componentId: ComponentId,
+): Archetype {
+  const cached = src.removeEdges.get(componentId);
+  if (cached !== undefined) {
+    const target = graph.archetypes[cached];
+    if (target) {
+      return target;
+    }
+  }
+
+  // Compute target archetype: src components minus removed component.
+  // Derive componentIds from src.components (single-field Archetype).
+  const newIds = src.components
+    .map((c) => componentOwner.componentId(c))
+    .filter((id) => id !== componentId);
+  const newComponents = src.components.filter((c) => componentOwner.componentId(c) !== componentId);
+  const target = getOrCreateArchetype(graph, newIds, newComponents);
+  src.removeEdges.set(componentId, target.id);
+  return target;
+}

package/src/storage/archetype.ts

@@ -0,0 +1,78 @@
+import type { Component, ComponentId } from '../component';
+import { componentId } from '../component';
+import { foldEssentials } from '../entity';
+import type { TableId } from './table';
+
+const INITIAL_CAPACITY = 64;
+
+export type ArchetypeId = number;
+
+export interface Archetype {
+  readonly id: ArchetypeId;
+  readonly key: string;
+  readonly components: ReadonlyArray<Component>;
+  readonly tableId: TableId;
+  rows: Uint32Array;
+  size: number;
+  capacity: number;
+  addEdges: Map<ComponentId, ArchetypeId>;
+  removeEdges: Map<ComponentId, ArchetypeId>;
+}
+
+export function archetypeKey(componentIds: ReadonlyArray<ComponentId>): string {
+  return [...foldEssentials(componentIds)].sort((a, b) => a - b).join('+');
+}
+
+export function createArchetype(
+  components: ReadonlyArray<Component>,
+  id: ArchetypeId,
+  tableId: TableId,
+): Archetype {
+  const byId = new Map<ComponentId, Component>();
+  for (const component of components) byId.set(componentId(component), component);
+  const sorted = [...byId.values()].sort((a, b) => componentId(a) - componentId(b));
+  return {
+    id,
+    key: archetypeKey(sorted.map((component) => componentId(component))),
+    components: sorted,
+    tableId,
+    rows: new Uint32Array(INITIAL_CAPACITY),
+    size: 0,
+    capacity: INITIAL_CAPACITY,
+    addEdges: new Map(),
+    removeEdges: new Map(),
+  };
+}
+
+export function appendArchetypeRow(archetype: Archetype, tableRow: number): number {
+  if (archetype.size === archetype.capacity) growArchetype(archetype, archetype.capacity * 2);
+  const row = archetype.size;
+  archetype.rows[row] = tableRow;
+  archetype.size = row + 1;
+  return row;
+}
+
+export function removeArchetypeRow(
+  archetype: Archetype,
+  row: number,
+): { movedTableRow: number; newRow: number } | null {
+  const lastRow = archetype.size - 1;
+  if (row === lastRow) {
+    archetype.size = lastRow;
+    return null;
+  }
+  const movedTableRow = archetype.rows[lastRow] ?? 0;
+  archetype.rows[row] = movedTableRow;
+  archetype.size = lastRow;
+  return { movedTableRow, newRow: row };
+}
+
+export function growArchetype(archetype: Archetype, targetCapacity: number): void {
+  let capacity = archetype.capacity;
+  while (capacity < targetCapacity) capacity *= 2;
+  if (capacity === archetype.capacity) return;
+  const rows = new Uint32Array(capacity);
+  rows.set(archetype.rows);
+  archetype.rows = rows;
+  archetype.capacity = capacity;
+}