@forgeax/engine-ecs 0.1.2

package/dist/storage/archetype.d.ts

@@ -0,0 +1,23 @@
+import type { Component, ComponentId } from '../component';
+import type { TableId } from './table';
+export type ArchetypeId = number;
+export interface Archetype {
+    readonly id: ArchetypeId;
+    readonly key: string;
+    readonly components: ReadonlyArray<Component>;
+    readonly tableId: TableId;
+    rows: Uint32Array;
+    size: number;
+    capacity: number;
+    addEdges: Map<ComponentId, ArchetypeId>;
+    removeEdges: Map<ComponentId, ArchetypeId>;
+}
+export declare function archetypeKey(componentIds: ReadonlyArray<ComponentId>): string;
+export declare function createArchetype(components: ReadonlyArray<Component>, id: ArchetypeId, tableId: TableId): Archetype;
+export declare function appendArchetypeRow(archetype: Archetype, tableRow: number): number;
+export declare function removeArchetypeRow(archetype: Archetype, row: number): {
+    movedTableRow: number;
+    newRow: number;
+} | null;
+export declare function growArchetype(archetype: Archetype, targetCapacity: number): void;
+//# sourceMappingURL=archetype.d.ts.map

package/dist/storage/archetype.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archetype.d.ts","sourceRoot":"","sources":["../../src/storage/archetype.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIvC,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACxC,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;CAC5C;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,MAAM,CAE7E;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,EACpC,EAAE,EAAE,WAAW,EACf,OAAO,EAAE,OAAO,GACf,SAAS,CAeX;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMjF;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,GACV;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAUlD;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAQhF"}

package/dist/storage/change-detection.d.ts

@@ -0,0 +1,40 @@
+import type { Component } from '../component';
+import { type EntityHandle } from '../entity-handle';
+export { WorldChangeJournal, type WorldChangeRead } from '../world-change-journal';
+import type { ArchetypeGraph } from './archetype-graph';
+import type { Table } from './table';
+export interface ComponentEpochColumns {
+    added: Float64Array;
+    changed: Float64Array;
+}
+export declare function createComponentEpochColumns(capacity: number): ComponentEpochColumns;
+export declare function growComponentEpochColumns(columns: ComponentEpochColumns, capacity: number): ComponentEpochColumns;
+export declare function copyComponentEpoch(source: ComponentEpochColumns, sourceRow: number, target: ComponentEpochColumns, targetRow: number): void;
+export interface SparseTagSet {
+    readonly component: Component;
+    sparse: Int32Array;
+    dense: Uint32Array;
+    added: Float64Array;
+    changed: Float64Array;
+    size: number;
+}
+export declare function createSparseTagSet(component: Component): SparseTagSet;
+export declare function sparseTagIndex(set: SparseTagSet, entity: EntityHandle): number;
+export declare function sparseTagHas(set: SparseTagSet, entity: EntityHandle): boolean;
+export declare function insertSparseTag(set: SparseTagSet, entity: EntityHandle, epoch: number): number;
+export declare function removeSparseTag(set: SparseTagSet, entity: EntityHandle): boolean;
+export interface ChangeTicks {
+    added: number;
+    changed: number;
+}
+export declare const NEVER_CHANGED_TICK = -1;
+export declare function createChangeTicks(tick: number): ChangeTicks;
+interface EntityLocation {
+    readonly archetypeId: number;
+    readonly archetypeRow: number;
+}
+export declare function readComponentChange(graph: ArchetypeGraph, location: EntityLocation, entity: EntityHandle, componentId: number): ChangeTicks | undefined;
+export declare function markComponentsAdded(graph: ArchetypeGraph, location: EntityLocation, entity: EntityHandle, componentIds: readonly number[], epoch: number): void;
+export declare function markComponentChanged(graph: ArchetypeGraph, location: EntityLocation, entity: EntityHandle, componentId: number, epoch: () => number): void;
+export declare function readTableEntityRange(table: Table, rowStart: number, rowCount: number): readonly EntityHandle[];
+//# sourceMappingURL=change-detection.d.ts.map

package/dist/storage/change-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-detection.d.ts","sourceRoot":"","sources":["../../src/storage/change-detection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,kBAAkB,CAAC;AAElE,OAAO,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAEnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIrC,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAEnF;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAMvB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,qBAAqB,EAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,qBAAqB,EAC7B,SAAS,EAAE,MAAM,GAChB,IAAI,CAGN;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,YAAY,CAWrE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAG9E;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAE7E;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAe9F;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAchF;AA0BD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAE3D;AAED,UAAU,cAAc;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,MAAM,GAClB,WAAW,GAAG,SAAS,CAmBzB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,KAAK,EAAE,MAAM,GACZ,IAAI,CAiBN;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,MAAM,GAClB,IAAI,CAaN;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,SAAS,YAAY,EAAE,CAKzB"}

package/dist/storage/column.d.ts

@@ -0,0 +1,111 @@
+import { type ComponentSchema, type ScalarFieldType } from '../component';
+/**
+ * Read-only access shape for the 4 managed-vocab column keywords --
+ * `'string'` / `` `ref<T>` `` / variable `'buffer'` / variable `` `array<T>` ``.
+ *
+ * The column carries u32 slot ids (`UniqueRefStore` / `BufferPool`); direct
+ * index assignment would corrupt the slot table. The reader exposes
+ * `.length` + `.get(i): number` so consumers can walk row indices and
+ * retrieve slot ids, then route through the public dispatch (`world.set`,
+ * `world.push`, `world.allocUniqueRef`, etc.) for any mutation.
+ *
+ * Phantom brand `__managed` (D-7 / requirements-decisions q2): the
+ * double-underscore + semantic-word pattern matches `Handle.__handle`. The
+ * brand is a structural-typing safety net; the class name already
+ * disambiguates against `Uint32Array` / `Uint8Array` / fixed inline views.
+ *
+ * Intentionally minimal -- no iterator, no `toArray`, no `slice`. Adding
+ * those invites a "cache the slot ids, mutate later" anti-pattern that
+ * silently desyncs from the live column on the next archetype migration
+ * (charter P4 / plan-strategy §8.4).
+ */
+export interface ManagedColumnReader<T extends string> {
+    readonly length: number;
+    get(i: number): number;
+    readonly __managed: T;
+}
+/**
+ * Sidecar column name for the live `count` of an `array<T>` (variable-
+ * capacity) field. Format `<fieldName>:count` keeps the suffix outside the
+ * legal user-facing schema name space (the colon is forbidden in user
+ * field names by convention) so the archetype Map can carry both columns
+ * under one `Map<fieldName, Column>` keyed namespace without collision
+ * (D-3 double-column allocation in M1 / w7).
+ */
+export declare function arrayCountColumnName(fieldName: string): string;
+/** TypedArray view types used by columns. */
+export type FieldView = Float32Array | Float64Array | Int32Array | Uint32Array | Int16Array | Uint16Array | Int8Array | Uint8Array;
+/** A single column: one field's ArrayBuffer + TypedArray view. */
+export interface Column {
+    buffer: ArrayBuffer | SharedArrayBuffer;
+    view: FieldView;
+    capacity: number;
+    fieldType: ScalarFieldType;
+    /**
+     * Number of elements per row (stride). Scalar and variable-capacity columns
+     * default to 1 (one u32 slot id or one scalar value per row). Fixed-capacity
+     * `array<T,N>` / `buffer<N>` inline columns (feat-20260602) have arity = N.
+     *
+     * For inline columns, the TypedArray view returned by `col.view.subarray()`
+     * aliases the column buffer directly. The view is transient: `growColumn`
+     * detaches the old `ArrayBuffer` via `transfer()`, so callers must re-fetch
+     * the view after any structural change. See `packages/ecs/README.md`
+     * Transient view contract section.
+     */
+    arity: number;
+}
+/**
+ * Create a column for a single field with given capacity.
+ *
+ * @param fieldType - scalar storage type for the column view ctor
+ * @param capacity - number of rows
+ * @param arity - elements per row (stride); default 1 for scalar/variable columns
+ */
+export declare function createColumn(fieldType: ScalarFieldType, capacity: number, arity?: number, shared?: boolean): Column;
+/**
+ * Module-level cache for `ArrayBuffer.prototype.transfer` support (O-1).
+ * Checked once at import time; avoids per-call feature detection overhead.
+ *
+ * Note: `transfer()` is ES2024. We use runtime feature detection + type cast
+ * so that tsconfig does not need `lib: ["es2024"]`.
+ */
+export declare const HAS_TRANSFER: boolean;
+/**
+ * Grow a column to a new capacity, preserving existing data.
+ * Returns a new Column; the old column is not modified.
+ *
+ * When the runtime supports `ArrayBuffer.transfer()` (ES2024, Node 22+,
+ * modern browsers), uses zero-copy buffer transfer. Otherwise falls back
+ * to `new ArrayBuffer` + `Uint8Array.set` copy.
+ *
+ * Both paths produce data-equivalent results (O-1 acceptance criterion).
+ */
+export declare function growColumn(col: Column, newCapacity: number): Column;
+/**
+ * Normalize a `'buffer'` / `'buffer<N>'` write payload to a `Uint8Array` view
+ * over its raw bytes. The write surface (`FieldInputType<'buffer'>`) accepts
+ * any `AllowSharedBufferSource` (Float32Array / ArrayBuffer / Uint8Array / any
+ * TypedArray); the column store and read side speak `Uint8Array` only. This is
+ * the single ingestion point that bridges the two — a strict superset of the
+ * prior Uint8Array-only behavior (an existing `Uint8Array` caller round-trips
+ * through `new Uint8Array(buffer, byteOffset, byteLength)`, same bytes, same
+ * length), so existing callers see zero behavior change.
+ *
+ * Returns `null` for non-buffer-source inputs (e.g. a forced cast feeding a
+ * number) so callers keep their existing "no-op / alloc(0)" branch for raw
+ * that is not a real buffer view.
+ */
+export declare function normalizeBufferWrite(raw: unknown): Uint8Array | null;
+/**
+ * Determine if a schema is "hot" (all fields are scalar → TypedArray SoA).
+ * Returns true if all fields are in the scalar field type set.
+ * Empty schema (tag component) returns true by convention (vacuously true).
+ *
+ * Schema-vocab keywords (`buffer:<N>` / `ref<T>` / `handle<T>` / `entity` /
+ * `array<T,N>` / `array<T>`) are explicitly cold — their storage is owned by
+ * separate subsystems (UniqueRefStore / BufferPool), not the column SoA path. The keyword check uses an unsafe narrowing because
+ * `SchemaFieldType` is wider than the set's `ScalarFieldType` element type;
+ * the `has` test is the runtime gate.
+ */
+export declare function isHotSchema(schema: ComponentSchema): boolean;
+//# sourceMappingURL=column.d.ts.map

package/dist/storage/column.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column.d.ts","sourceRoot":"","sources":["../../src/storage/column.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAiB,MAAM,cAAc,CAAC;AAOzF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,MAAM;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE9D;AAMD,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GACjB,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,WAAW,GACX,UAAU,GACV,WAAW,GACX,SAAS,GACT,UAAU,CAAC;AAef,kEAAkE;AAClE,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAAC;IACxC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,eAAe,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,SAAI,EACT,MAAM,UAAQ,GACb,MAAM,CAaR;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,OACuD,CAAC;AAEnF;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CA6BnE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAcpE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAO5D"}

package/dist/storage/table.d.ts

@@ -0,0 +1,29 @@
+import { type Component, type ComponentId } from '../component';
+import type { EntityHandle } from '../entity-handle';
+import { type ComponentEpochColumns } from './change-detection';
+import { type Column } from './column';
+export type TableId = number;
+export interface TableComponentStorage {
+    readonly component: Component;
+    fields: Map<string, Column>;
+    epochs: ComponentEpochColumns;
+}
+export interface Table {
+    readonly id: TableId;
+    readonly key: string;
+    readonly components: ReadonlyArray<Component>;
+    storage: Map<ComponentId, TableComponentStorage>;
+    size: number;
+    capacity: number;
+    version: number;
+}
+export declare function tableKey(componentIds: ReadonlyArray<ComponentId>): string;
+export declare function canonicalComponents(components: ReadonlyArray<Component>): Component[];
+export declare function createTable(components: ReadonlyArray<Component>, id: TableId, shared?: boolean): Table;
+export declare function appendTableRow(table: Table, entity: EntityHandle): number;
+export declare function removeTableRow(table: Table, row: number): {
+    movedEntity: EntityHandle;
+    newRow: number;
+} | null;
+export declare function growTable(table: Table, targetCapacity: number): void;
+//# sourceMappingURL=table.d.ts.map

package/dist/storage/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/storage/table.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,WAAW,EAQjB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,KAAK,qBAAqB,EAI3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAwB,KAAK,MAAM,EAA4B,MAAM,UAAU,CAAC;AAIvF,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC9C,OAAO,EAAE,GAAG,CAAC,WAAW,EAAE,qBAAqB,CAAC,CAAC;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,MAAM,CAEzE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,SAAS,EAAE,CAKrF;AAED,wBAAgB,WAAW,CACzB,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,EACpC,EAAE,EAAE,OAAO,EACX,MAAM,UAAQ,GACb,KAAK,CAgDP;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAOzE;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,GACV;IAAE,WAAW,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiBtD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAcpE"}

package/dist/time.d.ts

@@ -0,0 +1,57 @@
+export interface TimeResource {
+    readonly delta: number;
+    readonly elapsed: number;
+    readonly maxDeltaSeconds: number;
+}
+export interface FixedTimeResource {
+    readonly delta: number;
+    readonly maxStepsPerUpdate: number;
+    readonly tick: number;
+    /** Seconds accumulated toward the next fixed update. */
+    readonly overstep: number;
+    readonly droppedSeconds: number;
+    readonly droppedUpdates: number;
+}
+export type MutableTimeResource = {
+    -readonly [K in keyof TimeResource]: TimeResource[K];
+};
+export type MutableFixedTimeResource = {
+    -readonly [K in keyof FixedTimeResource]: FixedTimeResource[K];
+};
+/** Scheduler-only mutable clock capability; World never exposes this publicly. */
+export interface ClockWriter {
+    readonly time: MutableTimeResource;
+    readonly fixed: MutableFixedTimeResource;
+}
+export interface WorldClock {
+    readonly time: TimeResource;
+    readonly fixed: FixedTimeResource;
+    readonly writer: ClockWriter;
+}
+interface ResourceToken<T> {
+    readonly name: string;
+    readonly __resourceType?: T;
+}
+export type ResourceValue<Key> = Key extends ResourceToken<infer Value> ? Value : never;
+export interface TimePolicy {
+    readonly fixedDeltaSeconds?: number;
+    readonly maxStepsPerUpdate?: number;
+    readonly maxDeltaSeconds?: number;
+}
+export interface WorldOptions {
+    readonly time?: TimePolicy;
+    /** SAB-backed dense numeric columns for a SharedKernel-capable Engine Realm. */
+    readonly storage?: 'local' | 'shared';
+}
+/** World-owned variable-rate clock resource key. */
+export declare const Time: ResourceToken<TimeResource> & TimeResource;
+/** World-owned fixed-rate clock, policy, and catch-up metric resource key. */
+export declare const FixedTime: ResourceToken<FixedTimeResource> & FixedTimeResource;
+export declare const TIME_RESOURCE_KEY: string;
+export declare const FIXED_TIME_RESOURCE_KEY: string;
+export declare const DEFAULT_TIME_POLICY: Required<TimePolicy>;
+export declare function createTimeResource(policy: Required<TimePolicy>): TimeResource;
+export declare function createFixedTimeResource(policy: Required<TimePolicy>): FixedTimeResource;
+export declare function createWorldClock(policy: Required<TimePolicy>): WorldClock;
+export {};
+//# sourceMappingURL=time.d.ts.map

package/dist/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAAG;IAAE,CAAC,UAAU,CAAC,IAAI,MAAM,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC;CAAE,CAAC;AAC3F,MAAM,MAAM,wBAAwB,GAAG;IACrC,CAAC,UAAU,CAAC,IAAI,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,CAAC,CAAC;CAC/D,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,UAAU,aAAa,CAAC,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;CAC7B;AAED,MAAM,MAAM,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,aAAa,CAAC,MAAM,KAAK,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC;AAExF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CACvC;AAED,oDAAoD;AACpD,eAAO,MAAM,IAAI,EAAsC,aAAa,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;AAClG,8EAA8E;AAC9E,eAAO,MAAM,SAAS,EAA2C,aAAa,CAAC,iBAAiB,CAAC,GAC/F,iBAAiB,CAAC;AAEpB,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAC3C,eAAO,MAAM,uBAAuB,QAAiB,CAAC;AAEtD,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,UAAU,CAIpD,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,YAAY,CAE7E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,iBAAiB,CASvF;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,CAuCzE"}

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