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

package/dist/unique-ref-store.d.ts

@@ -0,0 +1,105 @@
+import type { Handle } from '@forgeax/engine-types';
+import { type Result } from '@forgeax/engine-types';
+import { UniqueRefDoubleReleaseError, UniqueRefReleasedError, UniqueRefStaleError } from './errors';
+/**
+ * Per-slot singleton store for ECS-managed `Handle<T, 'unique'>` lifecycles.
+ * World hooks the three release paths (despawn, removeComponent, set) into
+ * `release(handle)`; `resolve(handle)` is the read path AI users reach
+ * indirectly through `world.get(e, C)` for `ref<T>` schema fields.
+ *
+ * §contract — handles carry a generation; stale-by-reuse is detected: the
+ * handle u32 packs `(gen << 24) | slot` via the shared codec; `resolve` /
+ * `release` compare the handle generation against `_generations[slot]` and
+ * return `UniqueRefStaleError` ('unique-ref-stale') when a released slot has
+ * been re-allocated, instead of silently resolving to the next payload.
+ * README §"Managed handles carry a generation" is the canonical AI-user-
+ * facing statement.
+ *
+ * Identity invariant (AC-04 prelude): the payload returned by `resolve` is
+ * the same object reference on every call until `release`. Carry-over (M4)
+ * relies on this - archetype migrate moves the row index, not the payload.
+ *
+ * Storage is type-erased (`unknown`): the store routes lifecycle without ever
+ * inspecting payload fields. Per-call payload typing flows through method
+ * generics: `alloc<T>` accepts a `T` payload + matching `onRelease(T)`, and
+ * `resolve<T>` returns `Result<T, ...>`. Both narrow at the call boundary
+ * (the single read site is World.get's ref path); making the class generic
+ * on `T` was decoration with no internal use, so the parameter was dropped
+ * (architecture-principles.md §1 SSOT).
+ */
+export declare class UniqueRefStore {
+    private readonly payloads;
+    private readonly freeSlots;
+    private readonly releaseCallbacks;
+    private nextSlot;
+    /**
+     * 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).
+     *
+     * Slot 0 is the sentinel and always has gen=0 — it is never allocated
+     * and never incremented (R6).
+     *
+     * @internal
+     */
+    private readonly _generations;
+    /**
+     * Allocate a fresh managed handle for `payload`, branded against `target`.
+     *
+     * Slot 0 is reserved as the "null/unset" sentinel - schema-vocab `ref<T>`
+     * fields default to this sentinel before the first write, and World's
+     * release loop uses it to short-circuit (`shouldRelease(0) === false`).
+     *
+     * 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 toUnique brand cast
+     * happens internally — external callers no longer construct Handle<...>
+     * directly.
+     *
+     * @returns a `Handle<T, 'unique'>` u32. The branded number is safe to
+     *   widen to `number` for GPU upload (charter consistent abstraction).
+     */
+    alloc<Target extends string, T = unknown>(target: Target, payload: T, onRelease?: (payload: T) => void): Handle<Target, 'unique'>;
+    /**
+     * Look up `payload` by handle. Returns `err(unique-ref-released)` when
+     * the handle's slot has no live payload (release happened in between, and
+     * no re-alloc has filled the slot). Resolves the same payload object on
+     * every call - identity-stable until release.
+     *
+     * §contract: a stale handle whose slot has been released and re-allocated
+     * returns `err(unique-ref-stale)` — the generation welded into the handle
+     * no longer matches `_generations[slot]`. The gen check runs before the
+     * payload lookup, so stale-by-reuse is caught deterministically — see
+     * README §"Managed handles carry a generation".
+     *
+     * `T` flows from the caller's `Handle<T, 'unique'>` type; the store erases
+     * payload types at the storage layer and the call boundary re-narrows.
+     */
+    resolve<Target extends string, T = unknown>(handle: Handle<Target, 'unique'>): Result<T, UniqueRefReleasedError | UniqueRefStaleError>;
+    /**
+     * Release `handle` - drop the payload and push the slot onto the free list.
+     * Releasing the same handle twice surfaces `unique-ref-double-release`
+     * (D-1) so World's release loop can route the second release to Layer 3
+     * ErrorHandler without aborting the despawn chain. Detection is by
+     * payload-presence, not generation (§contract — managed handles are
+     * operational, not persistent).
+     *
+     * Releasing the slot-0 sentinel is a no-op - World's release loop calls
+     * `shouldRelease` first to filter sentinels.
+     */
+    release<Target extends string>(handle: Handle<Target, 'unique'>): Result<void, UniqueRefDoubleReleaseError | UniqueRefStaleError>;
+    /** @internal Replace the payload of a live slot without changing its handle. */
+    _setPayload<Target extends string, T>(handle: Handle<Target, 'unique'>, payload: T): void;
+    /**
+     * `true` if `handle` references a live slot - used by World's release loop
+     * to decide whether to call `release` (skips sentinel + already-released).
+     *
+     * The release loop differentiates "expected sentinel" (no error) from
+     * "leaked already-released handle" (`unique-ref-double-release`) at the
+     * caller layer; this helper handles only the no-op short-circuit.
+     */
+    isLive<Target extends string>(handle: Handle<Target, 'unique'>): boolean;
+    /** @internal Diagnostic count of live slots. Exposed for tests + inspector. */
+    _liveCount(): number;
+}
+//# sourceMappingURL=unique-ref-store.d.ts.map

package/dist/unique-ref-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unique-ref-store.d.ts","sourceRoot":"","sources":["../src/unique-ref-store.ts"],"names":[],"mappings":"AAyDA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAQL,KAAK,MAAM,EAGZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAKpG;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+D;IAChG,OAAO,CAAC,QAAQ,CAAK;IAErB;;;;;;;;;OASG;IAEH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAE7C;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,MAAM,SAAS,MAAM,EAAE,CAAC,GAAG,OAAO,EACtC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,EACV,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAC/B,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;IAkB3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,CAAC,GAAG,OAAO,EACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAC/B,MAAM,CAAC,CAAC,EAAE,sBAAsB,GAAG,mBAAmB,CAAC;IAqB1D;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,SAAS,MAAM,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAC/B,MAAM,CAAC,IAAI,EAAE,2BAA2B,GAAG,mBAAmB,CAAC;IAyClE,gFAAgF;IAChF,WAAW,CAAC,MAAM,SAAS,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI;IAQzF;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,OAAO;IAMxE,+EAA+E;IAC/E,UAAU,IAAI,MAAM;CAGrB"}

package/dist/world-change-journal.d.ts

@@ -0,0 +1,34 @@
+import type { EntityHandle } from './entity-handle';
+export type WorldChangeKind = 'component-added' | 'component-changed' | 'component-removed' | 'derived-component-changed' | 'entity-removed';
+export interface WorldChangeRecord {
+    readonly sequence: number;
+    readonly kind: WorldChangeKind;
+    readonly entity: EntityHandle;
+    readonly componentId?: number;
+}
+export type WorldChange = Omit<WorldChangeRecord, 'sequence'>;
+export type WorldChangeRead = {
+    readonly status: 'ok';
+    readonly cursor: number;
+    readonly records: readonly WorldChangeRecord[];
+} | {
+    readonly status: 'overflow';
+    readonly cursor: number;
+    readonly oldestAvailable: number;
+};
+/**
+ * Bounded mutation evidence for engine-owned projections.
+ *
+ * Readers retain a cursor and rebuild their projection when the ring has
+ * overwritten unread records. An overflow never returns a partial delta.
+ */
+export declare class WorldChangeJournal {
+    readonly capacity: number;
+    private readonly records;
+    private nextSequence;
+    constructor(capacity?: number);
+    cursor(): number;
+    append(change: WorldChange): number;
+    readAfter(cursor: number): WorldChangeRead;
+}
+//# sourceMappingURL=world-change-journal.d.ts.map

package/dist/world-change-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-change-journal.d.ts","sourceRoot":"","sources":["../src/world-change-journal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,GACnB,2BAA2B,GAC3B,gBAAgB,CAAC;AAErB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,CAAC;AAE9D,MAAM,MAAM,eAAe,GACvB;IACE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAChD,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC,CAAC;AAIN;;;;;GAKG;AACH,qBAAa,kBAAkB;IAIjB,QAAQ,CAAC,QAAQ;IAH7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,YAAY,CAAK;gBAEJ,QAAQ,SAAS;IAOtC,MAAM,IAAI,MAAM;IAIhB,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM;IAOnC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;CAuB3C"}

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

@@ -0,0 +1,265 @@
+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;
+    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.
+     */
+    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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"}