@forgeax/engine-ecs 0.1.2

package/dist/world-component-access.d.ts

@@ -0,0 +1,264 @@
+import { type Result } from '@forgeax/engine-types';
+import type { BufferPool } from './buffer-pool';
+import { type Component, type ComponentSchema, type InputShapeOf, type ShapeOf } from './component';
+import { type EntityHandle } from './entity-handle';
+import { RelationshipIndex } from './relationship-index';
+import type { SharedRefStore } from './shared-ref-store';
+import { type Archetype } from './storage/archetype';
+import { type ArchetypeGraph } from './storage/archetype-graph';
+import { type FieldView } from './storage/column';
+import type { UniqueRefStore } from './unique-ref-store';
+import type { ComponentData, EcsError, EntityRecord } from './world';
+type ErrorContext = {
+    readonly systemName: string;
+};
+export interface ComponentAccessState {
+    readonly graph: ArchetypeGraph;
+    readonly records: EntityRecord[];
+    readonly freeIndices: number[];
+    readonly bufferPool: BufferPool;
+    readonly uniqueRefs: UniqueRefStore;
+    readonly sharedRefs: SharedRefStore;
+    readonly relationshipIndexes: Map<number, RelationshipIndex>;
+    readonly markComponentAdded: (entity: EntityHandle, componentId: number) => void;
+    readonly markComponentsAdded: (entity: EntityHandle, componentIds: readonly number[]) => void;
+    readonly markComponentChanged: (entity: EntityHandle, componentId: number) => void;
+    readonly removeComponentChange: (entity: EntityHandle, componentId: number) => void;
+    readonly markStructureChanged: () => void;
+    routeError(err: unknown, ctx: ErrorContext): void;
+}
+export declare class WorldComponentAccess {
+    private readonly state;
+    private readonly storage;
+    constructor(state: ComponentAccessState);
+    private get graph();
+    private get records();
+    private table;
+    private tableRow;
+    private get freeIndices();
+    private get bufferPool();
+    private get uniqueRefs();
+    private routeError;
+    private relationshipIndex;
+    /** Read the World-owned materialized target array; never consults a shadow list. */
+    relationshipTargetEntries(source: Component, target: EntityHandle): readonly EntityHandle[];
+    private markComponentAdded;
+    private markComponentChanged;
+    private markStructureChanged;
+    relationshipTargetEntity(component: Component, value: Record<string, unknown>): EntityHandle | null;
+    /**
+     * Validate one structural component payload without touching archetypes,
+     * columns, relationship mirrors, epochs, or managed-reference stores.
+     * CommandBuffer uses this same owner-level gate as the direct World facade;
+     * the optional pending set lets a batch refer to an entity reserved earlier
+     * in that batch without mistaking it for a stale live handle.
+     */
+    preflightComponentData(holder: EntityHandle | null, componentData: ComponentData, pendingEntities?: ReadonlySet<number>, unavailableEntities?: ReadonlySet<number>): Result<void, EcsError>;
+    private relationshipCycleHit;
+    /** Prepare the target side before a source archetype mutation commits. */
+    private prepareRelationshipInsert;
+    /** Append `holder` to the materialized target list. */
+    relationshipOnInsert(holder: EntityHandle, component: Component, value: Record<string, unknown>): Result<void, EcsError>;
+    /** Remove `holder` from the materialized target list. */
+    relationshipOnRemove(holder: EntityHandle, component: Component, oldValue: Record<string, unknown>): Result<void, EcsError>;
+    /**
+     * Read component data from an entity.
+     *
+     * **Transient view contract (feat-20260602):** for fixed-capacity
+     * `array<T,N>` and `buffer<N>` fields, the returned `TypedArray` (and any
+     * subarray of it) aliases the archetype column buffer directly. The view is
+     * valid only until the next structural change (`spawn` / `despawn` /
+     * `addComponent` / `removeComponent`). Holding a view across a structural
+     * change is undefined behaviour -- the backing `ArrayBuffer` is detached on
+     * column growth, and swap-remove at the same row index points to the wrong
+     * entity. **Re-fetch `world.get(e, C)` on every access.** See
+     * `packages/ecs/README.md` Transient view contract section.
+     *
+     * @returns `Result<ShapeOf<S>, EcsError>` —
+     *   `ok(ShapeOf<S>)` on success;
+     *   `err(StaleEntityError)` (`.code = 'stale-entity'`) if entity is dead;
+     *   `err(ComponentNotPresentError)` (`.code = 'component-not-present'`) if
+     *   the entity does not have the component (a never-present component on
+     *   this entity degrades to the same `component-not-present` path — there is
+     *   no separate "not registered" failure; components are global at
+     *   `defineComponent` time).
+     *
+     * @example
+     * ```ts
+     * const Position = defineComponent('Position', { x: 'f32', y: 'f32' });
+     * const world = new World();
+     * const e = world.spawn({ component: Position, data: { x: 1, y: 2 } }).unwrap();
+     * const r = world.get(e, Position);
+     * if (!r.ok) { return; } // r.error.code === 'stale-entity' on dead handle
+     * const pos = r.value;
+     * ```
+     */
+    get<S extends ComponentSchema>(entity: EntityHandle, component: Component<string, S>): Result<ShapeOf<S>, EcsError>;
+    /**
+     * Column-level zero-copy view of an `array<T, N>` / `array<T>` field.
+     *
+     * Resolves the live byte region for `(entity, component, fieldName)`
+     * directly at the column level and returns the element-typed TypedArray
+     * aliasing it (`view.buffer` is the SSOT byte region; mutations route
+     * through `world.set`). Unlike `get`, this does NOT build the
+     * `{}` whole-component object nor walk every schema field. Per-frame
+     * consumers that need one column (the resolved world mat4) take this path to
+     * avoid the `get` overhead (1 `{}` alloc + N-field readRow walk).
+     *
+     * Fixed `array<T,N>` columns (feat-20260602) store their elements inline, so
+     * the view aliases the archetype column buffer directly (no BufferPool
+     * indirection); variable `array<T>` columns still alias the BufferPool slot.
+     * The returned view's element type follows the schema element type
+     * (`array<entity,N>` -> `Uint32Array`, `array<f32,N>` -> `Float32Array`,
+     * etc.) -- the prior f32-only early-return gate is removed.
+     *
+     * **Transient view contract:** the returned `TypedArray` aliases the column
+     * buffer and is valid only until the next structural change (`spawn` /
+     * `despawn` / `addComponent` / `removeComponent`). Column growth
+     * (`growColumn`) detaches the old `ArrayBuffer` via `transfer()`; a
+     * swap-remove at the same row index leaves the view pointing to the wrong
+     * entity. **Callers must re-fetch `_getArrayView` on every access** and must
+     * not hold the view across any operation that may cause archetype migration.
+     * All existing per-frame consumers (`propagateTransforms` / `render-extract`
+     * / `pick`) already conform -- they fetch the view inside a single pass with
+     * no intervening structural changes.
+     *
+     * Returns `undefined` when the entity is dead, the component is absent, the
+     * field does not exist, or the field is not an `array<...>` column.
+     *
+     * @internal Engine-internal fast path; AI users read the typed view through
+     *   `world.get(e, Transform).world`. The accessor is the zero-materialization
+     *   route the propagate kernel and render walk use.
+     */
+    _getArrayView(entity: EntityHandle, component: Component, fieldName: string): FieldView | undefined;
+    /**
+     * Write (partial) component data to an entity.
+     *
+     * @returns `Result<void, EcsError>` —
+     *   `ok(void)` on success;
+     *   `err(StaleEntityError)` (`.code = 'stale-entity'`) if entity is dead;
+     *   `err(ComponentNotPresentError)` (`.code = 'component-not-present'`) if
+     *   entity does not have the component (F-02: no longer silently ignores).
+     *
+     * @example
+     * ```ts
+     * const Position = defineComponent('Position', { x: 'f32', y: 'f32' });
+     * const world = new World();
+     * const e = world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+     * const r = world.set(e, Position, { x: 10 });
+     * if (!r.ok) { return; } // r.error.code === 'stale-entity' on dead handle
+     * r.unwrap();
+     * ```
+     */
+    set<S extends ComponentSchema>(entity: EntityHandle, component: Component<string, S>, value: Partial<InputShapeOf<S>>, markChanged?: boolean): Result<void, EcsError>;
+    /**
+     * Append `value` to the variable `array<T>` field `fieldName` on `entity`.
+     *
+     * BufferPool grow is amortized O(1) via the size-class freelist (research
+     * Finding 5). Relationship target arrays grow byte-wise.
+     *
+     * @returns `Result<void, EcsError>` with the normal stale/component errors.
+     *
+     * The helper is called only by relationship synchronization.
+     */
+    private appendArrayElement;
+    private ensureArrayCapacity;
+    /**
+     * Remove one variable-array element at a known slot. Relationship holders
+     * supply the slot from their backpointer, so this is O(1) and never scans
+     * the materialized target array.
+     */
+    private removeArrayElementAt;
+    /**
+     * Add a component to an existing entity, triggering archetype migration.
+     *
+     * @returns `Result<void, EcsError>` —
+     *   `ok(void)` on success;
+     *   `err(StaleEntityError)` (`.code = 'stale-entity'`) if entity is dead;
+     *   `err(ComponentAlreadyPresentError)` (`.code = 'component-already-present'`)
+     *   if entity already has the component (E-03).
+     *
+     * @example
+     * ```ts
+     * const Position = defineComponent('Position', { x: 'f32', y: 'f32' });
+     * const Velocity = defineComponent('Velocity', { dx: 'f32', dy: 'f32' });
+     * const world = new World();
+     * const e = world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+     * const r = world.addComponent(e, { component: Velocity, data: { dx: 1, dy: 0 } });
+     * if (!r.ok) { return; } // r.error.code === 'stale-entity' on dead handle
+     * r.unwrap();
+     * ```
+     */
+    addComponent<S extends ComponentSchema>(entity: EntityHandle, componentData: ComponentData<S>): Result<void, EcsError>;
+    /**
+     * Core implementation of `addComponent` with reentry guard.
+     *
+     * @param internal — `true` when called from relationship maintenance
+     *   (lazy mirror create or exclusive reparent).
+     * @internal
+     */
+    _addComponentCore<S extends ComponentSchema>(entity: EntityHandle, componentData: ComponentData<S>, internal: boolean): Result<void, EcsError>;
+    /**
+     * Remove a component from an existing entity, triggering archetype migration.
+     *
+     * @returns `Result<void, EcsError>` —
+     *   `ok(void)` on success;
+     *   `err(StaleEntityError)` (`.code = 'stale-entity'`) if entity is dead;
+     *   `err(ComponentNotPresentError)` (`.code = 'component-not-present'`)
+     *   if entity doesn't have the component (E-04).
+     *
+     * @example
+     * ```ts
+     * const Position = defineComponent('Position', { x: 'f32', y: 'f32' });
+     * const world = new World();
+     * const e = world.spawn({ component: Position, data: { x: 0, y: 0 } }).unwrap();
+     * const r = world.removeComponent(e, Position);
+     * if (!r.ok) { return; } // r.error.code === 'stale-entity' on dead handle
+     * r.unwrap();
+     * ```
+     */
+    removeComponent<S extends ComponentSchema>(entity: EntityHandle, component: Component<string, S>): Result<void, EcsError>;
+    /**
+     * Core implementation of `removeComponent` with reentry guard.
+     *
+     * @param internal — `true` when called from relationship maintenance
+     *   (exclusive reparent).
+     * @internal
+     */
+    _removeComponentCore<S extends ComponentSchema>(entity: EntityHandle, component: Component<string, S>, internal: boolean): Result<void, EcsError>;
+    /**
+     * @internal Allocate a pending entity for deferred spawn.
+     * Returns an Entity handle. The entity is "pending" because
+     * archetypeId === -1 (set by allocateIndex); no separate flag needed.
+     */
+    _allocatePendingEntity(): EntityHandle;
+    /**
+     * Return a deferred-spawn reservation to the free-list without publishing a
+     * row or advancing an epoch.  CommandBuffer.abort is the sole caller; a
+     * materialized entity is intentionally left untouched so an unexpected
+     * post-write failure poisons the World instead of attempting an unsafe undo.
+     */
+    _cancelPendingEntity(entity: EntityHandle): void;
+    /**
+     * @internal Materialize a pending entity: actually place it into an archetype.
+     * Idempotent: a record with archetypeId !== -1 is already materialized.
+     */
+    _materializePendingEntity(entity: EntityHandle, componentDatas: ComponentData[]): Result<void, EcsError>;
+    allocateIndex(): number;
+    /**
+     * Single liveness predicate (feat-20260602 / plan-strategy D-4): a slot is
+     * live for a given handle generation iff the record exists, its generation
+     * still matches the handle (despawn bumps generation, so a stale or recycled
+     * handle fails here), and the slot is materialized into an archetype
+     * (archetypeId !== -1). Replaces the former `record.alive && record.generation
+     * === gen` conjunction and the intermediate `!record.pending` clause.
+     */
+    recordIsLive(record: EntityRecord | undefined, gen: number): record is EntityRecord;
+    lookupAlive(entity: EntityHandle, operation: string, component?: string): Result<EntityRecord, EcsError>;
+    readRow<S extends ComponentSchema>(arch: Archetype, component: Component<string, S>, row: number): ShapeOf<S>;
+    writeEntitySelf(arch: Archetype, row: number, handle: EntityHandle): void;
+    writeRow<S extends ComponentSchema>(arch: Archetype, component: Component<string, S>, row: number, value: ShapeOf<S>): void;
+    releaseManagedRefsOnRow(arch: Archetype, component: Component, row: number): void;
+}
+export {};
+//# sourceMappingURL=world-component-access.d.ts.map

package/dist/world-component-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-component-access.d.ts","sourceRoot":"","sources":["../src/world-component-access.ts"],"names":[],"mappings":"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"}

package/dist/world-component-storage.d.ts

@@ -0,0 +1,282 @@
+import type { BufferPool } from './buffer-pool';
+import { type ArrayMeta, type Component, type ComponentSchema, type ManagedArrayElementType, type ShapeOf } from './component';
+import { type EntityHandle } from './entity-handle';
+import type { ManagedArrayErrorEnvelope } from './errors';
+type ErrorContext = {
+    readonly systemName: string;
+};
+import type { SharedRefStore } from './shared-ref-store';
+import { type Archetype } from './storage/archetype';
+import { type ArchetypeGraph } from './storage/archetype-graph';
+import { type FieldView } from './storage/column';
+import type { UniqueRefStore } from './unique-ref-store';
+import type { EntityRecord } from './world';
+export interface ComponentStorageState {
+    readonly graph: ArchetypeGraph;
+    readonly records: EntityRecord[];
+    readonly bufferPool: BufferPool;
+    readonly uniqueRefs: UniqueRefStore;
+    readonly sharedRefs: SharedRefStore;
+    routeError(err: unknown, ctx: ErrorContext): void;
+}
+export declare class ComponentStorage {
+    private readonly state;
+    constructor(state: ComponentStorageState);
+    private get records();
+    private table;
+    private get bufferPool();
+    private get uniqueRefs();
+    private get sharedRefs();
+    private routeError;
+    readArrayView(arch: Archetype, component: Component, row: number, fieldName: string): FieldView | undefined;
+    readRow<S extends ComponentSchema>(arch: Archetype, component: Component<string, S>, row: number): ShapeOf<S>;
+    /**
+     * Write the full packed entity handle into the row's essential id=0 `Entity`
+     * column (`self` field). Called by `spawn` / `_materializePendingEntity`
+     * after the row is appended (feat-20260602 / plan-strategy D-3). The column
+     * always exists -- `createArchetype` folds the Entity column into every
+     * archetype -- so this is a direct u32 store, no readRow/writeRow walk.
+     */
+    writeEntitySelf(arch: Archetype, row: number, handle: EntityHandle): void;
+    writeRow<S extends ComponentSchema>(arch: Archetype, component: Component<string, S>, row: number, value: ShapeOf<S>): void;
+    /**
+     * Release every managed-resource field on `component` for the row at
+     * `row` in `arch`. Walks the schema once and delegates each field to
+     * `releaseManagedFieldOnRow` (feat-20260614 M2 SSOT). Family coverage
+     * (per-field) lives in that helper's JSDoc.
+     *
+     * Naming note (D-6 whitelist): the prefix `managed` here means
+     * `managed = ECS-tracked` — i.e. fields whose lifecycle the ECS
+     * actively releases on despawn / overwrite / removeComponent. It does
+     * NOT refer to the retired `'managed' | 'unmanaged'` Handle brand
+     * (renamed to `'unique' | 'shared'` in feat-20260614 M1). The helper
+     * walks BOTH `'unique<T>'` and `'shared<T>'` fields because both are
+     * ECS-tracked from the column's perspective; the per-field dispatch
+     * inside `releaseManagedFieldOnRow` distinguishes drop-on-despawn
+     * (unique) vs ref-counted release (shared).
+     *
+     * Skips sentinel slots (handle / id 0) and missing stores. Failures
+     * (double release / lookup mismatch) route to the Layer 3 ErrorHandler so
+     * the despawn / removeComponent chain never aborts (charter: explicit-
+     * failure boundary; the chain is total).
+     *
+     * Four release paths route through this helper (AC-11, plan §6 M2):
+     *   1. `world.despawn(e)`             - every component on `e`.
+     *   2. `world.removeComponent(e, C)`  - the removed component only.
+     *   3. `world.set` ref/string/buffer overwrite - per-field, before the new
+     *                                                value lands in the column.
+     *   4. `writeArrayField` set arm prior-slot release (variable array<T>).
+     *
+     * After feat-20260614 M2 SSOT collapse the schema-field 3-arm dispatch
+     * lives in `releaseManagedFieldOnRow` (one site); this method walks the
+     * component schema and delegates per field.
+     *
+     * BufferPool slot id is reusable post-release: same-bucket free-list LIFO
+     * (D-7) returns the freed id on the next `alloc(byteLength)`. Tests:
+     * `__tests__/managed-array-release.test.ts` (w10) +
+     * `__tests__/world-managed-roundtrip.unit.test.ts` (w3 net-zero matrix).
+     */
+    releaseManagedRefsOnRow(arch: Archetype, component: Component, row: number): void;
+    /**
+     * SSOT release dispatch for a single managed field on a row (feat-20260614
+     * M2 / D-2). Inspects the component schema's field type and routes to the
+     * matching release path:
+     *
+     *   - `'unique<T>'` / `'string'` (`isManagedField`)         — release the
+     *     UniqueRefStore handle u32 stored in the column.
+     *   - `'buffer'` variable     (`isManagedBufferField`)   — release the
+     *     BufferPool slot id stored in the column. Fixed `'buffer<N>'` is
+     *     inline stride-N (feat-20260602) and has no slot to release.
+     *   - `array<T>` variable     (`isManagedArrayField`)    — release the
+     *     BufferPool slot id in the primary column + zero the column and the
+     *     `<fieldName>:count` sidecar so post-recycle reads observe count=0
+     *     (defense-in-depth; the swap-pop row migration overwrites both
+     *     columns anyway). Fixed `array<T,N>` is inline stride-N — nothing to
+     *     release.
+     *
+     * Sentinel handle / slot id 0 short-circuits silently. Double-release /
+     * lookup mismatch routes via Layer 3 ErrorHandler so the despawn /
+     * removeComponent / set chain never aborts (charter explicit-failure
+     * boundary; the chain is total).
+     *
+     * SceneInstance state alloc/release rollback at world.ts:3494/3522 stays
+     * a direct `uniqueRefs.release(stateRef)` (research Finding 1.8 / D-5):
+     * those two sites are alloc-pair rollback, not schema-field dispatch.
+     *
+     * Naming note (D-6 whitelist): `releaseManagedFieldOnRow` uses
+     * `managed = ECS-tracked` — every field family this dispatcher knows
+     * (`'unique<T>'`, `'shared<T>'`, `'string'`, variable `'buffer'`,
+     * variable `'array<T>'`) is one whose lifecycle the ECS owns. The
+     * `'managed' | 'unmanaged'` Handle brand is gone (M1 renamed to
+     * `'unique' | 'shared'`); the helper name was deliberately kept
+     * because `managed` here is a column-side semantic, not a brand label.
+     */
+    releaseManagedFieldOnRow(arch: Archetype, component: Component, row: number, fieldName: string): void;
+    /**
+     * Release a single managed handle u32. Routes failures through Layer 3.
+     * Slot-0 sentinel short-circuits silently (no error); already-released
+     * slots surface `unique-ref-double-release` through the ErrorHandler so
+     * AI users see the structured payload (`.code` / `.hint` / `.expected` /
+     * `.detail`) - charter explicit-failure boundary.
+     *
+     * Helper-internal only after feat-20260614 M2 (AC-03 grep gate). External
+     * callers route via `releaseManagedFieldOnRow`.
+     */
+    releaseManagedRefHandle(handleU32: number, componentName: string, fieldName: string): void;
+    /**
+     * Release a single shared-ref handle u32 (feat-20260614 M4 / AC-08).
+     * Decrements the SharedRefStore refcount; the slot drops on rc 1 -> 0.
+     * Slot-0 sentinel short-circuits silently. Already-released slots route
+     * `shared-ref-double-release` through Layer 3 ErrorHandler so AI users
+     * see structured payloads (charter explicit-failure boundary).
+     *
+     * Mirrors `releaseManagedRefHandle` in shape; the store + error code are
+     * the only differences. Helper-internal — external callers route via
+     * `releaseManagedFieldOnRow` (D-2 SSOT).
+     */
+    releaseSharedRefHandle(handleU32: number, componentName: string, fieldName: string): void;
+    /**
+     * Retain a single `shared<T>` scalar slot id (feat-20260614 M5 / D-5).
+     * Mirrors `releaseSharedRefHandle`; called from spawn / set scalar write
+     * paths so each ECS holder participates in the SharedRefStore rc.
+     * Sentinel slot 0 is a no-op. Failures (handle already released) route
+     * via Layer 3 ErrorHandler so the spawn / set chain stays total.
+     */
+    retainSharedScalarHandle(handleU32: number, componentName: string, fieldName: string): void;
+    /**
+     * Release a single managed buffer slot id. Routes failures through Layer 3.
+     * Slot id 0 (sentinel for unallocated buffer fields) short-circuits
+     * silently. M2 v1 release surface is total - `BufferPool.release` returns
+     * `Result<void, never>` for unknown ids, so the chain stays noise-free.
+     *
+     * Helper-internal only after feat-20260614 M2 (AC-03 grep gate). External
+     * callers route via `releaseManagedFieldOnRow`.
+     */
+    releaseManagedBufferSlot(slotId: number, componentName: string, fieldName: string): void;
+    /**
+     * Bridge a Layer-3 ErrorHandler call from a `ManagedArrayErrorEnvelope`.
+     * The envelope shape (`code / hint / expected / detail`) already mirrors
+     * the EcsError contract; this helper only attaches the systemName context
+     * so AI users can correlate the error with the holder component / field.
+     */
+    routeArrayError(err: ManagedArrayErrorEnvelope, componentName: string, fieldName: string): void;
+    /**
+     * Write the value of an `array<T>` / `array<T,N>` field at `row` (D-3 +
+    /**
+     * Write an `array<T>` / `array<T,N>` field's payload at `row` (M1 / w7,
+     * D-1; feat-20260614 M2 / D-3). Spawn and set both delegate here without
+     * an `operation` parameter — the caller's calling convention encodes the
+     * difference:
+     *   - Set path: caller invokes `releaseManagedFieldOnRow(arch, comp, row,
+     *     fieldName)` BEFORE this method to release the prior slot (variable
+     *     `array<T>`). Fixed `array<T,N>` is inline stride-N (feat-20260602)
+     *     and has no slot to release on either path.
+     *   - Spawn path: caller does NOT call the helper — fresh rows treat any
+     *     non-zero u32 in the column as stale swap-pop debris owned by the
+     *     migrated entity in the new archetype.
+     *
+     * Body:
+     *   - Alloc a fresh BufferPool slot of `payload.length * elementBytes`.
+     *   - Copy bytes from the payload's typed-array buffer into the slot view.
+     *   - Persist slot id in the primary u32 column. For `array<T>` (variable),
+     *     persist the live count in the sidecar `<fieldName>:count` column.
+     *
+     * Errors flow through `routeArrayError` with a uniform `World.write` label.
+     */
+    writeArrayField(arch: Archetype, component: Component, row: number, fieldName: string, _fieldType: string, arrayMeta: ArrayMeta, raw: unknown): void;
+    /**
+     * Walk the first `count` u32 handles in `bytes` and call
+     * `SharedRefStore.retain` on each non-sentinel slot id (feat-20260614 M4 /
+     * D-3). Failures route via Layer 3 ErrorHandler so the write chain stays
+     * total; charter explicit-failure boundary lets AI users see structured
+     * `shared-ref-released` payloads when retaining a stale handle.
+     *
+     * Helper-internal -- only called from `writeArrayField`'s `'shared'` arm.
+     */
+    retainSharedArrayElements(bytes: Uint8Array, count: number): void;
+    /**
+     * Walk the first `count` u32 handles in `bytes` and call
+     * `SharedRefStore.release` on each non-sentinel slot id (feat-20260614 M4 /
+     * D-3). Mirrors `retainSharedArrayElements`; called from
+     * `releaseManagedFieldOnRow`'s array arm BEFORE the BufferPool slot is
+     * released so the underlying bytes are still valid.
+     */
+    releaseSharedArrayElements(bytes: Uint8Array, count: number): void;
+    writeArrayElementAt(bytes: Uint8Array, idx: number, elementType: ManagedArrayElementType, value: number): void;
+    readArrayElementAt(bytes: Uint8Array, idx: number, elementType: ManagedArrayElementType): number;
+    /**
+     * Materialise a fresh `TypedArray` snapshot for an `array<T,N>` /
+     * `array<T>` field at `row` (plan-strategy §2.2 -- read-only snapshot
+     * contract; mutations route through `world.set` / `world.push` /
+     * `world.pop`).
+     *
+     * **Transient view contract (feat-20260602):** for fixed `array<T,N>`
+     * columns the returned `TypedArray` aliases the inline column buffer
+     * directly (`col.view.subarray(row * arity, ...)`); for variable
+     * `array<T>` columns it aliases the live `BufferPool` slot bytes
+     * (zero-copy; `pool.view(slotId)` is the SSOT byte region). In both
+     * cases the view is valid only until the next structural change. Writing
+     * into the snapshot is undefined behaviour -- the contract is read-only
+     * and the implementation may switch to a copy in the future without
+     * breaking AI users who consume only `length` / index reads.
+     *
+     * For variable arrays the typed-array length matches the live count from
+     * the sidecar `<fieldName>:count` column; for fixed arrays it matches the
+     * schema-declared `N`. `entity` element fields surface as a `Uint32Array`
+     * view (Entity packs slot+gen into u32).
+     */
+    materializeArrayView(arch: Archetype, component: Component, row: number, fieldName: string, elementType: ManagedArrayElementType, fixedLength: number | undefined, slotId: number): Float32Array | Float64Array | Int32Array | Uint32Array | Int16Array | Uint16Array | Int8Array | Uint8Array;
+    /**
+     * Migrate an entity from srcArch to targetArch.
+     * Copies all shared component data, then removes from src via swap-pop.
+     *
+     * AC-04 carry-over contract (M4): for every component that survives the
+     * migration (i.e. the target archetype carries the same `compId`), every
+     * field column's u32 value is copied verbatim from src to target. This
+     * preserves every managed resource handle in place:
+     *
+     *   - `ref<T>` field   - the u32 (managed handle = (slot << 8) | gen) is
+     *                        bit-equal across migrate, so `Object.is` on the
+     *                        handle holds and `UniqueRefStore.resolve` returns
+     *                        the same payload object reference (per-(slot, gen)
+     *                        wrapper singleton, D-3).
+     *   - `buffer<N>` field - fixed-capacity inline stride-N `u8` column
+     *                          (feat-20260602): the N bytes are copied verbatim
+     *                          by the generic per-column row copy, so the live
+     *                          bytes survive byte-for-byte. No BufferPool slot
+     *                          (only variable `buffer` carries a pool slot id).
+     *   - `entity` field   - the u32 (encoded slot+gen) is bit-equal across
+     *                        migrate.
+     *   - `array<T,N>` field - fixed-capacity inline stride-N column
+     *                          (feat-20260602): the N elements live contiguously
+     *                          in the column row and are copied verbatim by the
+     *                          generic per-column row copy, so they survive
+     *                          byte-for-byte (no BufferPool slot). The TypedArray
+     *                          snapshot is rematerialised on every `world.get`
+     *                          (D-4 no cache); we do NOT guarantee `Object.is` on
+     *                          the wrapper — only the underlying bytes (D-R7 weak
+     *                          carry-over).
+     *   - `array<T>` field   - dual u32 columns: primary slot id + sidecar
+     *                          `<fieldName>:count`. Both columns are copied via
+     *                          the generic per-column loop below, so count and
+     *                          slot id stay in lock-step. Capacity is derived
+     *                          from `BufferPool.view(slotId).byteLength /
+     *                          elementBytes` and is therefore preserved by the
+     *                          slot-id carry-over alone (no separate column).
+     *
+     * Negative invariant: this routine MUST NOT call UniqueRefStore.release /
+     * BufferPool.release for surviving components. The pre-migrate release
+     * loop lives at `removeComponent` (only for the component being removed)
+     * and `despawn` (every component); migrate is only a column copy. The
+     * array-field release-loop split (D-3 / D-5) further guarantees that
+     * spawn into a vacated row treats stale slot-id debris as no-op (the slot
+     * is owned by the migrated entity in the new archetype) — see
+     * `writeArrayField`'s `operation: 'spawn' | 'set'` discriminant.
+     * Tests: `__tests__/managed-carry-over.test.ts` (w16),
+     * `__tests__/managed-array-carry-over.test.ts` (w8).
+     */
+    migrateEntity(record: EntityRecord, srcArch: Archetype, targetArch: Archetype): void;
+    moveEntityArchetype(record: EntityRecord, srcArch: Archetype, targetArch: Archetype): void;
+}
+export {};
+//# sourceMappingURL=world-component-storage.d.ts.map

package/dist/world-component-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-component-storage.d.ts","sourceRoot":"","sources":["../src/world-component-storage.ts"],"names":[],"mappings":"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"}

package/dist/world-core.d.ts

@@ -0,0 +1,39 @@
+import { BufferPool } from './buffer-pool';
+import type { RelationshipIndex } from './relationship-index';
+import type { SharedRefStore } from './shared-ref-store';
+import { type ArchetypeGraph } from './storage/archetype-graph';
+import { WorldChangeJournal } from './storage/change-detection';
+import type { UniqueRefStore } from './unique-ref-store';
+import type { EntityRecord } from './world';
+interface WorldStorageCore {
+    readonly graph: ArchetypeGraph;
+    readonly records: EntityRecord[];
+    readonly freeIndices: number[];
+    readonly bufferPool: BufferPool;
+    readonly uniqueRefs: UniqueRefStore;
+    readonly sharedRefs: SharedRefStore;
+}
+/**
+ * Package-private state authority for World.  A World is the public facade;
+ * this object is the only owner of archetype storage, entity records, managed
+ * stores, epochs, and bounded change evidence.
+ */
+export declare class WorldCore {
+    readonly identity: string;
+    readonly uniqueRefs: UniqueRefStore;
+    readonly sharedRefs: SharedRefStore;
+    readonly storage: WorldStorageCore;
+    readonly componentMutationEpochs: number[];
+    readonly changeJournal: WorldChangeJournal;
+    /** One packed reverse index per relationship source component. */
+    readonly relationshipIndexes: Map<number, RelationshipIndex>;
+    mutationEpoch: number;
+    structureEpoch: number;
+    constructor(sharedStorage: boolean);
+    get graph(): ArchetypeGraph;
+    get records(): EntityRecord[];
+    get freeIndices(): number[];
+    get bufferPool(): BufferPool;
+}
+export {};
+//# sourceMappingURL=world-core.d.ts.map

package/dist/world-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-core.d.ts","sourceRoot":"","sources":["../src/world-core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAE,KAAK,cAAc,EAAwB,MAAM,2BAA2B,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,UAAU,gBAAgB;IACxB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;CACrC;AAgBD;;;;GAIG;AACH,qBAAa,SAAS;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAyB;IAClD,QAAQ,CAAC,UAAU,EAAE,cAAc,CAA4B;IAC/D,QAAQ,CAAC,UAAU,EAAE,cAAc,CAA4B;IAC/D,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,EAAE,CAAM;IAChD,QAAQ,CAAC,aAAa,qBAA4B;IAClD,kEAAkE;IAClE,QAAQ,CAAC,mBAAmB,iCAAwC;IACpE,aAAa,SAAK;IAClB,cAAc,SAAK;gBAEP,aAAa,EAAE,OAAO;IAOlC,IAAI,KAAK,mBAER;IAED,IAAI,OAAO,mBAEV;IAED,IAAI,WAAW,aAEd;IAED,IAAI,UAAU,eAEb;CACF"}

package/dist/world-entity-lifecycle.d.ts

@@ -0,0 +1,30 @@
+import { type Result } from '@forgeax/engine-types';
+import type { Component, ComponentSchema, InputShapeOf } from './component';
+import { type EntityHandle } from './entity-handle';
+import type { EcsError, World } from './world';
+/**
+ * Core implementation of `spawn` with a relationship reentry guard.
+ *
+ * @param internal - `true` when relationship maintenance creates a mirror.
+ */
+export declare function spawnCore(world: World, componentDatas: {
+    component: Component;
+    data: Partial<Record<string, unknown>>;
+}[], internal: boolean): Result<EntityHandle, EcsError>;
+/**
+ * Core implementation of `despawn` with a linked-spawn cascade guard.
+ *
+ * @param internal - `true` while recursively retiring linked children.
+ */
+export declare function despawnCore(world: World, entity: EntityHandle, internal: boolean): Result<void, EcsError>;
+/** Attach a child and maintain the relationship mirror through component storage. */
+export declare function worldAddChild<S extends ComponentSchema>(world: World, parent: EntityHandle, child: EntityHandle, component: Component<string, S>, data: Partial<InputShapeOf<S>>): Result<void, EcsError>;
+/** Detach a child only when its current relationship target matches `parent`. */
+export declare function worldRemoveChild<S extends ComponentSchema>(world: World, parent: EntityHandle, child: EntityHandle, component: Component<string, S>): Result<void, EcsError>;
+/** Move a child to a new parent after cycle validation and old-mirror detachment. */
+export declare function worldReparent<S extends ComponentSchema>(world: World, child: EntityHandle, newParent: EntityHandle, component: Component<string, S>, data: Partial<InputShapeOf<S>>): Result<void, EcsError>;
+/** Iterate ancestors in child-to-root order while safely terminating corrupt cycles. */
+export declare function worldIterAncestors(world: World, entity: EntityHandle): Iterable<EntityHandle>;
+/** Iterate descendants depth-first through relationship mirror lists. */
+export declare function worldIterDescendants(world: World, entity: EntityHandle): Iterable<EntityHandle>;
+//# sourceMappingURL=world-entity-lifecycle.d.ts.map

package/dist/world-entity-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-entity-lifecycle.d.ts","sourceRoot":"","sources":["../src/world-entity-lifecycle.ts"],"names":[],"mappings":"AAMA,OAAO,EAAgC,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAW,MAAM,aAAa,CAAC;AAKrF,OAAO,EAEL,KAAK,YAAY,EAIlB,MAAM,iBAAiB,CAAC;AAczB,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAQ/C;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,KAAK,EACZ,cAAc,EAAE;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,EAAE,EAClF,QAAQ,EAAE,OAAO,GAChB,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CA0DhC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,OAAO,GAChB,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CA+DxB;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,CAAC,SAAS,eAAe,EACrD,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,EAC/B,IAAI,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAC7B,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CA+CxB;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,eAAe,EACxD,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,GAC9B,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CA6CxB;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,CAAC,SAAS,eAAe,EACrD,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,EAC/B,IAAI,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAC7B,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAiDxB;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC,CAkD7F;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC,CAuC/F"}