@forgeax/engine-ecs 0.1.26 → 0.1.27

package/dist/world.d.ts

@@ -1,8 +1,8 @@
 import type { Handle, Result } from '@forgeax/engine-types';
 import { type Component, ComponentCatalog, type ComponentSchema, type InputShapeOf, type ShapeOf } from './component';
 import { type EntityHandle } from './entity-handle';
-import type { CommandFailedError, ComponentAlreadyPresentError, ComponentFieldInvalidValueError, ComponentNotDefinedError, ComponentNotPresentError, ComponentNumericValueInvalidError, DerivedRangeOutOfBoundsError, FixedSizeMismatchError, ManagedArrayInvalidValueError, ManagedBufferOutOfBoundsError, ManagedBufferShrinkNotSupportedError, RelationshipDetachMismatchError, RelationshipMirrorComponentNotRegisteredError, RelationshipMirrorFieldTypeMismatchError, RelationshipSelfCycleError, RemoveEssentialComponentError, ScheduleMutationError, ScheduleScopeMismatchError, SharedKernelEligibilityError, SharedKernelFailureError, StaleEntityError, SystemFailedError, SystemSetNotRegisteredError, TimeConfigInvalidError, TimeDeltaInvalidError, UniqueRefDoubleReleaseError, UniqueRefReleasedError, WorldPoisonedError } from './errors';
-import { ChangeEpochExhaustedError, RelationshipTargetReadonlyError } from './errors';
+import type { CommandFailedError, ComponentFieldInvalidValueError, ComponentNotDefinedError, ComponentNumericValueInvalidError, DerivedRangeOutOfBoundsError, ManagedArrayInvalidValueError, ManagedBufferShrinkNotSupportedError, RelationshipDetachMismatchError, RelationshipMirrorComponentNotRegisteredError, RelationshipMirrorFieldTypeMismatchError, ScheduleMutationError, ScheduleScopeMismatchError, SharedKernelEligibilityError, SharedKernelFailureError, SystemFailedError, SystemSetNotRegisteredError, TimeConfigInvalidError, TimeDeltaInvalidError, UniqueRefDoubleReleaseError, UniqueRefReleasedError } from './errors';
+import { ChangeEpochExhaustedError, ComponentAlreadyPresentError, ComponentNotPresentError, FixedSizeMismatchError, ManagedBufferOutOfBoundsError, RelationshipSelfCycleError, RelationshipTargetReadonlyError, RemoveEssentialComponentError, StaleEntityError, WorldPoisonedError } from './errors';
 import { type WorldExecutionState } from './execution/shared-kernel';
 import type { QueryDescriptor } from './query/query';
 import { type Query, type QueryCreationError } from './query/query';
@@ -11,7 +11,7 @@ import { type SystemDescriptor, type SystemSet } from './schedule';
 import type { SharedRefStore } from './shared-ref-store';
 import { type ChangeTicks } from './storage/change-detection';
 import { type WorldOptions } from './time';
-import { type WorldInternal, worldInternal } from './world-internal';
+import { type WorldRead, worldRead } from './world-read';
 /**
  * Union of all EcsError types that World methods can return via Result.
  * AI users: switch on `.code` for programmatic branching.
@@ -144,8 +144,10 @@ export interface WorldScheduleData {
  * permanently (it is never pushed back to `freeIndices`). The single liveness
  * predicate is therefore "handle gen matches AND archetypeId !== -1" -- see
  * `World.recordIsLive`. A deferred-spawn allocation is "pending" when
- * archetypeId === -1 (not yet materialized into an archetype row); no separate
- * boolean is needed.
+ * archetypeId === -1 (not yet materialized into an archetype row). During a
+ * failed append, `archetypeId` is reserved before the first storage write and
+ * `archetypeRow` remains `-1`; that marker prevents command abort from
+ * reclaiming a reservation that may already have touched table storage.
  */
 export interface EntityRecord {
     generation: number;
@@ -153,37 +155,32 @@ export interface EntityRecord {
     archetypeRow: number;
 }
 /**
- * The World owns:
- *   - the registry of known component schemas;
- *   - all archetypes (via ArchetypeGraph);
- *   - the entity index table (records by index slot);
- *   - the free-list of recyclable entity slots.
+ * The World owns the component registry, archetype graph, entity index table,
+ * and recyclable free-list.
  */
 export declare class World {
-    /** Package-internal implementation seam; not exported from any entry point. */
-    readonly [worldInternal]: WorldInternal;
-    /** The single package-private owner of storage, epochs, and change evidence. */
-    private readonly core;
+    readonly [worldRead]: WorldRead;
+    /** World-local state is kept together so one owner closes each mutation. */
+    private executionState;
+    private readonly graph;
+    private readonly records;
+    private readonly freeIndices;
+    /** BufferPool for schema-declared variable buffers and arrays. */
+    private readonly bufferPool;
+    /** Per-World managed unique-ref store used by lifecycle mutations. */
+    private readonly uniqueRefs;
+    /** Per-World shared-ref store; public read-only for direct handle operations. */
+    readonly sharedRefs: SharedRefStore;
+    private readonly componentMutationEpochs;
+    private readonly structuralEvidence;
+    /** One packed reverse index per relationship source component. */
+    private readonly relationshipIndexes;
+    private mutationEpoch;
+    private structureEpoch;
+    /** Keep identity as a prototype getter; it is a diagnostic capability, not enumerable state. */
     get identity(): string;
     /** Plugin-owned component discovery scoped to this World and removed through leases. */
     readonly components: ComponentCatalog;
-    private executionState;
-    /** Monotonic clock advanced exactly once per successful mutation. */
-    /** Monotonic revision for successful entity/component structure writes. */
-    /** Last mutation epoch for each component id, used by component-owned projections. */
-    /** Ordered, bounded evidence consumed by persistent engine-owned projections. */
-    private get mutationEpoch();
-    private set mutationEpoch(value);
-    private get structureEpoch();
-    private set structureEpoch(value);
-    private get componentMutationEpochs();
-    /** Free index slots (LIFO stack). */
-    private get records();
-    private get freeIndices();
-    /**
-     * Relationship-sync reentry guard (feat-20260531 M2 / plan-strategy D-7).
-     /** The archetype graph: manages all archetypes + edge caching. */
-    private get graph();
     /** DAG schedules for the two built-in execution scopes. */
     private readonly schedules;
     /** Resource store: typed key-value global singletons. */
@@ -191,56 +188,23 @@ export declare class World {
     private readonly clock;
     /** Remainder carried between fixed-step runs. */
     private fixedAccumulator;
-    /**
-     * ECS-managed handle store (M1). Owned by the World - constructed eagerly
-     * so every spawn / despawn / set path can dispatch managed-ref releases
-     * without caller-side wiring. AI users obtain `Handle<T,'unique'>` values
-     * by accessing the store through internal channels (the surface is
-     * private; managed-ref-bearing fields read through `world.get`).
-     */
-    private get uniqueRefs();
-    /**
-     * Per-World `SharedRefStore` (feat-20260614 M3). Backs every `shared<T>`
-     * schema field + the `world.allocSharedRef` facade. Public read-only so AI
-     * users can `retain` / `release` / `resolve` user-tier handles directly off
-     * the world (the surface is small enough that hiding it behind another
-     * facade would be a phantom indirection - charter F1 single-entry
-     * indexability).
-     *
-     * Final release publishes structured evidence; there is no callback surface.
-     * M6 D-15: the store manages only user-tier slots
-     * (`>= BUILTIN_BASE`); builtin handles are process-static in their
-     * authoring package and never reference-counted.
-     */
-    get sharedRefs(): SharedRefStore;
-    /**
-     * BufferPool backing every `buffer:<N>` schema-vocab field (M2). Eagerly
-     * constructed (per-World, D-2). `spawn` allocs slots for buffer fields and
-     * stores the slot id in the u32 column; `despawn` / `removeComponent`
-     * release the slots; `set(e, C, { field: Uint8Array })` copies bytes into
-     * the live view without re-allocating (schema-declared byteLength is
-     * fixed in v1; runtime grow is reserved for the M4 carry-over path).
-     */
-    private get bufferPool();
-    private readonly componentAccess;
     constructor(options?: WorldOptions);
     /** Immutable integrity state for execution coordinators and headless callers. */
     get execution(): WorldExecutionState;
     /** Resolve a schedule token owned by this World realm without package singleton identity. */
     scheduleToken(name: import('./schedule-token').ScheduleName): import('./schedule-token').ScheduleToken;
-    /** SharedKernel is the only writer; application code recovers by constructing a new World. */
+    /** Seal the first execution fault; application code recovers with a new World. */
     private internalpoisonExecution;
+    /**
+     * A poisoned identity is diagnostic evidence, not a mutable recovery path.
+     * Public entity mutation therefore returns the same structured fence as
+     * `update()` instead of allocating a new reservation or touching a partial
+     * row. Recovery remains construction of a fresh World.
+     */
+    private poisonedResult;
     query<const R extends readonly Component[] = readonly [], const W extends readonly Component[] = readonly [], const O extends readonly Component[] = readonly []>(descriptor: QueryDescriptor<R, W, O>): Result<Query<R, W, O>, QueryCreationError>;
-    /** Expose archetype graph for query engine. Not part of public API. */
-    private internalgetGraph;
     private componentIsInUse;
-    /** Current upper bound for mutation observation. */
-    private internalgetMutationEpoch;
-    /** Structure snapshot used to invalidate borrowed query facades. */
-    private internalgetStructureEpoch;
-    /** Typed structural facts are produced by this World and consumed by projections. */
-    private internalgetStructuralEvidence;
-    private internalrecordStructuralEvidence;
+    private recordStructuralEvidence;
     /** Resolve current logical identity for a packed entity handle. */
     private internalgetEntityArchetype;
     /** Component change state for query filters. */
@@ -250,55 +214,21 @@ export declare class World {
     private internalrestoreMutationEpoch;
     private internalpublishDerivedRange;
     /** Record one successful structural mutation. */
-    private internalmarkStructureChanged;
+    private advanceStructureEpoch;
     /** Current structural revision for mounted World projections. */
     getStructureEpoch(): number;
-    /** Mark a component as both added and changed at the current tick. */
-    private internalmarkComponentAdded;
     /** Mark one mutation's component instances with a shared epoch. */
     private internalmarkComponentsAdded;
     /** Mark an existing component as changed at the current tick. */
     private internalmarkComponentChanged;
     /** Mark one contiguous component range with a single epoch. */
     private internalmarkComponentRangeChanged;
-    /** Latest mutation token for one component-owned projection. */
-    private internalgetComponentMutationEpoch;
-    /** Borrow the component-version summary used to skip unrelated value columns. */
-    private internalgetComponentMutationEpochs;
-    /** Read a materialized relationship target in O(1 + k). */
-    private internalgetRelationshipTargetEntities;
-    /** Monotonic epoch for the materialized relationship index. */
-    private internalgetRelationshipEpoch;
     /** Query facade write after the facade has already marked evidence. */
     private internalsetQueryRow;
-    /** Query facade read that does not re-enter the public World API. */
-    private internalgetQueryRow;
     /** Return resource change ticks for diagnostics and resource-driven systems. */
     getResourceChange(name: string): ChangeTicks | undefined;
-    /**
-     * Route a structured error from
-     * an engine-internal subsystem (e.g. RenderSystem extract stage, w15).
-     *
-     * Mirrors the private `errorHandler(err, ctx)` call sites inside `World`
-     * itself; the dedicated accessor avoids exposing `errorHandler` directly
-     * and keeps the routing contract under the `_xxx` `@internal` umbrella so
-     * AI users do not discover it through IDE autocomplete on `World`.
-     *
-     * Not part of the public API.
-     */
-    private internalrouteError;
-    /** */ private internalgetRecords;
-    /** */ private internalgetFreeIndices;
-    /** */ private internalgetResources;
-    /** */ private internalgetFixedAccumulator;
-    /** */ private internalsetFixedAccumulator;
-    /** */ private internalgetUniqueRefs;
-    /** */ private internalgetBufferPool;
-    /** Scheduler-owned mutable clock capability. */
-    private internalgetClockWriter;
-    /** */ private internalgetSchedule;
-    /** */ private internalgetSchedules;
-    /** */ private internalgetSharedRefs;
+    /** Route an expected internal failure through the host-owned error channel. */
+    private routeError;
     /**
      * Register a system with query descriptor and optional ordering constraints.
      *
@@ -516,45 +446,326 @@ export declare class World {
     internSharedRef<Target extends string, T extends object>(target: Target, payload: T): Handle<Target, 'shared'>;
     private relationshipTargetWriteError;
     private relationshipTargetPayloadWrites;
+    /** Test live component presence without constructing a Result error. */
+    hasComponent(entity: EntityHandle, component: Component): boolean;
+    private table;
+    private tableRow;
+    private markComponentChanged;
+    private relationshipIndex;
+    /** Read the World-owned materialized target array; never consults a shadow list. */
+    private relationshipTargetEntries;
+    /** Read a relationship target length without materialising its array view. */
+    private relationshipTargetLength;
+    private relationshipTargetEntity;
+    private preflightComponentFieldValues;
+    /**
+     * 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.
+     */
+    private preflightComponentData;
+    private relationshipCycleHit;
+    /**
+     * Commit a relationship source through its owner-specific write path.
+     * Relationship sources have one entity field, so dispatching before the
+     * generic field loop avoids paying the ordinary component-field traversal on
+     * every hierarchy reparent while keeping mirror/index publication here.
+     */
+    private setRelationshipSource;
+    /** Prepare the target side before a source archetype mutation commits. */
+    private prepareRelationshipInsert;
+    /** Append `holder` to the materialized target list. */
+    private relationshipOnInsert;
+    /** Remove `holder` from the materialized target list. */
+    private relationshipOnRemove;
+    private linkedSpawnMirrorField;
+    private relationshipLinkedSpawnChildren;
+    /**
+     * 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>;
     /**
-     * Test live component presence without constructing a Result error.
+     * 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.
+     *
+     * Engine-internal fast path; AI users read the typed view through
+     * `world.get(e, GlobalTransform).world`. The accessor is the zero-materialization
+     * route the propagate kernel and render walk use.
+     */
+    private getArrayView;
+    /**
+     * 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, C extends Component<string, S>>(entity: EntityHandle, component: C & WritableComponent<C>, value: Partial<InputShapeOf<S>>, markChanged?: boolean): Result<void, EcsError>;
+    /**
+     * Append `value` to the variable `array<T>` field `fieldName` on `entity`.
      *
-     * Read projections commonly need to branch on optional components for many
-     * entities. Calling `get` for that branch allocates a structured
-     * ComponentNotPresentError on every ordinary miss (and StaleEntityError for
-     * a dangling handle). This predicate is deliberately non-throwing and
-     * returns false for both cases; callers that need the detailed error should
-     * continue to use `get`.
+     * 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();
+     * ```
      */
-    hasComponent(entity: EntityHandle, component: Component): boolean;
-    private internalgetArrayView;
-    private internalgetArrayLength;
-    private internalgetArrayElement;
-    private internalgetFieldValue;
-    set<S extends ComponentSchema, C extends Component<string, S>>(entity: EntityHandle, component: C & WritableComponent<C>, value: Partial<InputShapeOf<S>>): Result<void, EcsError>;
     addComponent<S extends ComponentSchema, C extends Component<string, S>>(entity: EntityHandle, componentData: ComponentData<S> & {
         component: C & WritableComponent<C>;
     }): Result<void, EcsError>;
-    private internaladdComponentCore;
+    /**
+     * Core implementation of `addComponent` with reentry guard.
+     *
+     * @param internal — `true` when called from relationship maintenance
+     *   (lazy mirror create or exclusive reparent).
+     */
+    private addComponentCore;
+    /**
+     * 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, C extends Component<string, S>>(entity: EntityHandle, component: C & WritableComponent<C>): Result<void, EcsError>;
-    private internalremoveComponentCore;
-    private internalallocatePendingEntity;
-    /** */ private internalcancelPendingEntity;
-    private internalmaterializePendingEntity;
-    /** Shared structural preflight for direct and deferred writes. */
-    private internalpreflightComponentData;
-    /** */ private internalallocateIndex;
-    /** */ private internalrecordIsLive;
-    /** */ private internallookupAlive;
-    /** */ private internalreadRow;
-    /** */ private internalwriteEntitySelf;
-    /** */ private internalwriteRow;
-    /** */ private internalreleaseManagedRefsOnRow;
-    /** */ private internalrelationshipOnInsert;
-    /** */ private internalprepareRelationshipInsert;
-    /** */ private internalreleaseRelationshipPreparation;
-    /** */ private internalrelationshipOnRemove;
+    /**
+     * Core implementation of `removeComponent` with reentry guard.
+     *
+     * @param internal — `true` when called from relationship maintenance
+     *   (exclusive reparent).
+     */
+    private removeComponentCore;
+    /**
+     * 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.
+     */
+    private allocatePendingEntity;
+    /**
+     * 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.
+     */
+    private cancelPendingEntity;
+    /**
+     * Materialize one already-reserved entity. Synchronous spawn and deferred
+     * command flush share this exact insertion/publication path; only the
+     * caller's validation and reservation boundary differs.
+     *
+     */
+    private materializeEntity;
+    private poisonAfterEntityMutation;
+    /** Deferred commands use the common materialization owner. */
+    private materializePendingEntity;
+    private allocateIndex;
+    /**
+     * 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. An
+     * append in progress keeps `archetypeRow === -1` until both storage indexes
+     * exist.
+     */
+    private recordIsLive;
+    private lookupAlive;
+    private readArrayView;
+    /** Read one scalar column without constructing a component snapshot. */
+    private internalgetFieldValue;
+    /** Read an array's live logical length without allocating a TypedArray. */
+    private internalgetArrayLength;
+    /** Read one array element directly from its column or BufferPool slot. */
+    private internalgetArrayElement;
+    private readRow;
+    /**
+     * 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.
+     */
+    private writeEntitySelf;
+    private writeRow;
+    /** Release all ECS-owned field handles before a row is removed or overwritten. */
+    private releaseManagedRefsOnRow;
+    /**
+     * Release one ECS-owned field according to its schema. Inline buffers have
+     * no pool slot; shared-array elements still release their handles. Store
+     * failures use the host error channel so row cleanup remains total.
+     */
+    private releaseManagedFieldOnRow;
+    /** Release one unique-ref handle; sentinel 0 is ignored. */
+    private releaseManagedRefHandle;
+    /** Release one shared-ref handle, preserving builtin slots and refcounts. */
+    private releaseSharedRefHandle;
+    /** Retain one shared-ref scalar handle for a World-owned field. */
+    private retainSharedScalarHandle;
+    /** Release one variable-buffer slot; id 0 is the unallocated sentinel. */
+    private releaseManagedBufferSlot;
+    /**
+     * Attach field context to 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.
+     */
+    private routeArrayError;
+    /**
+     * Write an array field for spawn or set. Fixed arrays stay inline; variable
+     * arrays use one BufferPool slot plus a live-count sidecar.
+     */
+    private writeArrayField;
+    /**
+     * 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 the error channel 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.
+     */
+    private retainSharedArrayElements;
+    /**
+     * 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.
+     */
+    private releaseSharedArrayElements;
+    /**
+     * Materialize an array snapshot. Fixed arrays alias their inline column;
+     * variable arrays alias the live BufferPool slot and use the count sidecar.
+     * Both views are transient and must not be held across structural changes.
+     */
+    private materializeArrayView;
+    /**
+     * Copy surviving component columns into the target row, then swap-remove
+     * the source row. Managed handles and variable-array sidecars are copied
+     * verbatim; release remains the responsibility of remove/despawn paths.
+     */
+    private migrateEntity;
+    private moveEntityArchetype;
+    /**
+     * Retire one live entity and any linked-spawn descendants. The complete
+     * row/relationship/managed-data mutation stays on World so a failure after
+     * the first write can poison this identity instead of crossing an extraction
+     * owner boundary.
+     */
+    private despawnEntity;
     /**
      * Spawn an entity with one or more components.
      * Multi-component spawn directly targets the correct archetype (AC-06).
@@ -577,13 +788,6 @@ export declare class World {
             data: Partial<InputShapeOf<SArr[K]>>;
         };
     }): Result<EntityHandle, EcsError>;
-    /**
-     * Core implementation of `spawn` with reentry guard.
-     *
-     * @param internal — `true` when called from relationship maintenance
-     *   (lazy mirror create or exclusive reparent).
-     */
-    private internalspawnCore;
     /**
      * Despawn an entity. Stale handles are silently ignored (E-01, AC-17).
      * Generation retirement: gen=255 → index permanently retired (D-08/E-08).
@@ -602,15 +806,6 @@ export declare class World {
     despawn(entity: EntityHandle): Result<void, EcsError>;
     /** Despawn every live entity through the normal lifecycle and ref cleanup path. */
     despawnAll(): Result<void, EcsError>;
-    /**
-     * Core implementation of `despawn` with reentry guard.
-     *
-     * @param internal — `true` when called from within linkedSpawn cascade.
-     *   Nested despawn skips relationship pruning after the parent is retired;
-     *   the linkedSpawn collection still walks the subtree so grandchildren
-     *   cascade correctly (tweak-20260714 M2, R-6).
-     */
-    private internaldespawnCore;
     addChild<S extends ComponentSchema>(parent: EntityHandle, child: EntityHandle, component: Component<string, S>, data: Partial<InputShapeOf<S>>): Result<void, EcsError>;
     removeChild<S extends ComponentSchema>(parent: EntityHandle, child: EntityHandle, component: Component<string, S>): Result<void, EcsError>;
     reparent<S extends ComponentSchema>(child: EntityHandle, newParent: EntityHandle, component: Component<string, S>, data: Partial<InputShapeOf<S>>): Result<void, EcsError>;