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

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"}

package/dist/world-internal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ECS package-internal World seam.
+ *
+ * This module is intentionally not re-exported by the package entry points.
+ * It keeps implementation access out of World's discoverable API while
+ * retaining direct bound calls for the hot query and structural paths.
+ */
+export declare const worldInternal: unique symbol;
+type InternalName = 'addComponentCore' | 'allocateIndex' | 'allocatePendingEntity' | 'cancelPendingEntity' | 'despawnCore' | 'getArrayView' | 'getBufferPool' | 'getChangeCursor' | 'getClockWriter' | 'getComponentChange' | 'getComponentMutationEpoch' | 'getEntityArchetype' | 'getFixedAccumulator' | 'getFreeIndices' | 'getGraph' | 'getMutationEpoch' | 'getQueryRow' | 'getRecords' | 'getRelationshipEpoch' | 'getRelationshipTargetEntities' | 'getResources' | 'getSchedule' | 'getSchedules' | 'getSharedRefs' | 'getStructureEpoch' | 'getUniqueRefs' | 'lookupAlive' | 'markComponentAdded' | 'markComponentChanged' | 'markComponentRangeChanged' | 'markComponentsAdded' | 'markDerivedComponentChanges' | 'markStructureChanged' | 'materializePendingEntity' | 'nextMutationEpoch' | 'poisonExecution' | 'preflightComponentData' | 'readChangesSince' | 'readRow' | 'recordIsLive' | 'relationshipOnInsert' | 'relationshipOnRemove' | 'releaseManagedRefsOnRow' | 'removeComponentChange' | 'removeComponentCore' | 'removeEntityChanges' | 'routeError' | 'setFixedAccumulator' | 'setQueryRow' | 'spawnCore' | 'writeEntitySelf' | 'writeRow';
+export type WorldInternal = {
+    readonly [K in InternalName]: (...args: any[]) => any;
+};
+export {};
+//# sourceMappingURL=world-internal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"world-internal.d.ts","sourceRoot":"","sources":["../src/world-internal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,eAAO,MAAM,aAAa,EAAE,OAAO,MAEC,CAAC;AAErC,KAAK,YAAY,GACb,kBAAkB,GAClB,eAAe,GACf,uBAAuB,GACvB,qBAAqB,GACrB,aAAa,GACb,cAAc,GACd,eAAe,GACf,iBAAiB,GACjB,gBAAgB,GAChB,oBAAoB,GACpB,2BAA2B,GAC3B,oBAAoB,GACpB,qBAAqB,GACrB,gBAAgB,GAChB,UAAU,GACV,kBAAkB,GAClB,aAAa,GACb,YAAY,GACZ,sBAAsB,GACtB,+BAA+B,GAC/B,cAAc,GACd,aAAa,GACb,cAAc,GACd,eAAe,GACf,mBAAmB,GACnB,eAAe,GACf,aAAa,GACb,oBAAoB,GACpB,sBAAsB,GACtB,2BAA2B,GAC3B,qBAAqB,GACrB,6BAA6B,GAC7B,sBAAsB,GACtB,0BAA0B,GAC1B,mBAAmB,GACnB,iBAAiB,GACjB,wBAAwB,GACxB,kBAAkB,GAClB,SAAS,GACT,cAAc,GACd,sBAAsB,GACtB,sBAAsB,GACtB,yBAAyB,GACzB,uBAAuB,GACvB,qBAAqB,GACrB,qBAAqB,GACrB,YAAY,GACZ,qBAAqB,GACrB,aAAa,GACb,WAAW,GACX,iBAAiB,GACjB,UAAU,CAAC;AAEf,MAAM,MAAM,aAAa,GAAG;IAE1B,QAAQ,EAAE,CAAC,IAAI,YAAY,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;CACtD,CAAC"}

package/dist/world-scheduling.d.ts

@@ -0,0 +1,30 @@
+import type { Handle } from '@forgeax/engine-types';
+import { type Result } from '@forgeax/engine-types';
+import { CommandFailedError, CyclicDependencyError, ScheduleScopeMismatchError, SystemFailedError, type SystemSetNotRegisteredError, TimeConfigInvalidError, TimeDeltaInvalidError } from './errors';
+import { SharedKernelFailureError, WorldPoisonedError } from './execution/shared-kernel';
+import type { QueryDescriptor } from './query/query';
+import { type SystemDescriptor, type SystemSet, removeSystem as scheduleRemoveSystem, replaceSystem as scheduleReplaceSystem } from './schedule';
+import { type ScheduleToken } from './schedule-token';
+import type { World, WorldInspection, WorldScheduleData } from './world';
+type ResourceKey = string | {
+    readonly name: string;
+};
+export declare function worldAddSystem<const Qs extends ReadonlyArray<QueryDescriptor>>(world: World, token: ScheduleToken, descriptor: SystemDescriptor<Qs>): Result<void, ScheduleScopeMismatchError>;
+export declare function worldRemoveSystem(world: World, token: ScheduleToken, name: string): ReturnType<typeof scheduleRemoveSystem> | Result<never, ScheduleScopeMismatchError>;
+export declare function worldReplaceSystem<const Qs extends ReadonlyArray<QueryDescriptor>>(world: World, token: ScheduleToken, name: string, descriptor: SystemDescriptor<Qs>): ReturnType<typeof scheduleReplaceSystem> | Result<never, ScheduleScopeMismatchError>;
+export declare function worldAddSystems<const Qs extends ReadonlyArray<QueryDescriptor>>(world: World, token: ScheduleToken, set: SystemSet, systems: ReadonlyArray<SystemDescriptor<Qs>>): Result<void, SystemSetNotRegisteredError | ScheduleScopeMismatchError>;
+export declare function worldUpdate(world: World, deltaSeconds?: number): Result<void, TimeDeltaInvalidError | TimeConfigInvalidError | ScheduleScopeMismatchError | WorldPoisonedError | CommandFailedError | SystemFailedError | CyclicDependencyError | SharedKernelFailureError>;
+export declare function worldInsertResource<T>(world: World, key: ResourceKey, value: T): void;
+export declare function worldGetResource<T>(world: World, key: ResourceKey): T;
+export declare function worldHasResource(world: World, key: ResourceKey): boolean;
+export declare function worldRemoveResource(world: World, key: ResourceKey): void;
+export declare function worldInspect(world: World): WorldInspection;
+/** Project schedule registration into a JSON-safe graph for tooling and AI inspection. */
+export declare function worldScheduleData(world: World): ReadonlyArray<WorldScheduleData>;
+/** Control-plane guard used before releasing a World-local component registration. */
+export declare function worldScheduleUsesComponent(world: World, component: object): boolean;
+export declare function worldAllocUniqueRef<Target extends string, T>(world: World, target: Target, payload: T, onRelease?: (payload: T) => void): Handle<Target, 'unique'>;
+export declare function worldAllocSharedRef<Target extends string, T>(world: World, target: Target, payload: T): Handle<Target, 'shared'>;
+export declare function worldInternSharedRef<Target extends string, T extends object>(world: World, target: Target, payload: T): Handle<Target, 'shared'>;
+export {};
+//# sourceMappingURL=world-scheduling.d.ts.map

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

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