@alife-sdk/core 0.1.1 → 0.4.0

package/dist/entity/EntityHandle.js

@@ -0,0 +1,133 @@
+/**
+ * EntityHandle — versioned entity references with use-after-free protection.
+ *
+ * Instead of holding raw entity references that can become dangling after an
+ * entity is destroyed, systems hold an EntityHandle. The handle encodes both
+ * the entity's slot index and a generation counter. When a slot is reused for
+ * a new entity the generation is bumped, making all old handles stale.
+ *
+ * Bit layout (fits in a JavaScript safe integer):
+ *   [47..20] generation  (28 bits, up to ~268 M versions per slot)
+ *   [19.. 0] index       (20 bits, up to ~1 M concurrent slots)
+ *
+ * Usage:
+ *   const manager = new EntityHandleManager();
+ *   const handle  = manager.alloc('wolf-1');
+ *   manager.resolve(handle);   // → 'wolf-1'
+ *   manager.free(handle);
+ *   manager.resolve(handle);   // → null  (stale)
+ */
+// ---------------------------------------------------------------------------
+// Bit-layout constants
+// ---------------------------------------------------------------------------
+const INDEX_BITS = 20;
+const GEN_BITS = 28;
+const INDEX_MASK = (1 << INDEX_BITS) - 1; // 0x000FFFFF — 1 048 575 max slots
+const GEN_MASK = (1 << GEN_BITS) - 1; // 0x0FFFFFFF — 268 435 455 max gen
+const MAX_SLOTS = 1 << INDEX_BITS;
+/** Sentinel value for an absent or invalid handle. */
+export const NULL_HANDLE = 0;
+/** Pack (index, generation) into a single handle. */
+export function makeHandle(index, generation) {
+    // Use multiplication instead of bit-shift to avoid 32-bit truncation.
+    return ((generation & GEN_MASK) * MAX_SLOTS + (index & INDEX_MASK));
+}
+/** Extract the slot index from a handle. */
+export function indexOf(handle) {
+    return handle & INDEX_MASK;
+}
+/** Extract the generation counter from a handle. */
+export function genOf(handle) {
+    return Math.floor(handle / MAX_SLOTS) & GEN_MASK;
+}
+/** Return `true` if the handle is not the null sentinel. */
+export function isValidHandle(handle) {
+    return handle !== NULL_HANDLE;
+}
+/** Human-readable description for logging / debugging. */
+export function handleToString(handle) {
+    if (!isValidHandle(handle))
+        return 'Entity(NULL)';
+    return `Entity(idx=${indexOf(handle)}, gen=${genOf(handle)})`;
+}
+// ---------------------------------------------------------------------------
+// EntityHandleManager
+// ---------------------------------------------------------------------------
+/**
+ * Central registry that owns the slot → entity-id mapping.
+ *
+ * Recycles freed slots so slot count stays bounded. Old handles pointing at
+ * recycled slots resolve to `null` because their stored generation no longer
+ * matches the slot's current generation.
+ */
+export class EntityHandleManager {
+    constructor() {
+        /** Generation counter per slot (index = slot index). */
+        this.generations = [];
+        /** Entity ID stored in each live slot. `null` = free. */
+        this.ids = [];
+        /** Slot indices available for reuse. */
+        this.freeList = [];
+        /** Next slot to allocate when freeList is empty. */
+        this.nextSlot = 0;
+    }
+    /**
+     * Allocate a new handle for the given entity id.
+     * @throws if the slot limit is exhausted.
+     */
+    alloc(id) {
+        let index;
+        if (this.freeList.length > 0) {
+            index = this.freeList.pop();
+        }
+        else {
+            if (this.nextSlot >= MAX_SLOTS) {
+                throw new Error(`EntityHandleManager: slot limit (${MAX_SLOTS}) reached`);
+            }
+            index = this.nextSlot++;
+            this.generations[index] = 1;
+        }
+        this.ids[index] = id;
+        return makeHandle(index, this.generations[index]);
+    }
+    /**
+     * Release a handle, incrementing the slot's generation.
+     * All existing handles pointing at this slot become stale.
+     *
+     * Does nothing (and does not throw) if the handle is already stale.
+     */
+    free(handle) {
+        if (!this.isAlive(handle))
+            return;
+        const index = indexOf(handle);
+        this.ids[index] = null;
+        this.generations[index] = (this.generations[index] + 1) & GEN_MASK || 1; // skip 0
+        this.freeList.push(index);
+    }
+    /**
+     * Resolve a handle to its entity id.
+     * Returns `null` if the handle is stale (entity was freed) or null.
+     */
+    resolve(handle) {
+        if (!isValidHandle(handle))
+            return null;
+        const index = indexOf(handle);
+        if (this.generations[index] !== genOf(handle))
+            return null;
+        return this.ids[index] ?? null;
+    }
+    /**
+     * Return `true` if the handle points to a currently-live slot.
+     */
+    isAlive(handle) {
+        if (!isValidHandle(handle))
+            return false;
+        const index = indexOf(handle);
+        return this.generations[index] === genOf(handle) && this.ids[index] !== null;
+    }
+    /** Number of currently-live slots. */
+    get size() {
+        return this.nextSlot - this.freeList.length;
+    }
+}
+//# sourceMappingURL=EntityHandle.js.map

package/dist/entity/EntityHandle.js.map

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

package/dist/entity/index.d.ts

@@ -1,3 +1,5 @@
 export type { IEntity } from './IEntity';
 export type { IComponent } from './IComponent';
+export type { EntityHandle } from './EntityHandle';
+export { NULL_HANDLE, makeHandle, indexOf, genOf, isValidHandle, handleToString, EntityHandleManager, } from './EntityHandle';
 //# sourceMappingURL=index.d.ts.map

package/dist/entity/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EACL,WAAW,EACX,UAAU,EACV,OAAO,EACP,KAAK,EACL,aAAa,EACb,cAAc,EACd,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/entity/index.js

@@ -1,2 +1,2 @@
-export {};
+export { NULL_HANDLE, makeHandle, indexOf, genOf, isValidHandle, handleToString, EntityHandleManager, } from './EntityHandle';
 //# sourceMappingURL=index.js.map

package/dist/entity/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,WAAW,EACX,UAAU,EACV,OAAO,EACP,KAAK,EACL,aAAa,EACb,cAAc,EACd,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export { Clock } from './core/Clock';
 export type { IClockConfig, IClockState } from './core/Clock';
 export { SpatialGrid } from './core/SpatialGrid';
 export type { IRect } from './core/SpatialGrid';
+export { ReactiveQuery } from './core/ReactiveQuery';
+export type { QueryChanges, QueryChangeListener } from './core/ReactiveQuery';
 export type { ISerializable } from './core/ISerializable';
 export * from './core/math/index';
 export * from './events/index';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1I,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACpE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAK1D,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1I,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACpE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAK1D,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -11,6 +11,7 @@ export { Ports, REQUIRED_PORTS } from './core/PortTokens';
 export { DiagnosticsCollector, ALifeValidationError } from './core/Diagnostics';
 export { Clock } from './core/Clock';
 export { SpatialGrid } from './core/SpatialGrid';
+export { ReactiveQuery } from './core/ReactiveQuery';
 // ---------------------------------------------------------------------------
 // Sub-path re-exports
 // ---------------------------------------------------------------------------

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,sEAAsE;AACtE,+CAA+C;AAE/C,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAC9E,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIjD,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAC9E,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,sEAAsE;AACtE,+CAA+C;AAE/C,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAC9E,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAIrD,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAC9E,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}

package/dist/registry/AIStateRegistry.d.ts

@@ -30,6 +30,10 @@ export interface IAIStateDefinition {
     readonly canEnter?: (entity: IEntity, fromState: string) => boolean;
     /** Guard: return `false` to prevent leaving this state for `toState`. */
     readonly canExit?: (entity: IEntity, toState: string) => boolean;
+    /** Categorical tags for querying state group membership (e.g. 'combat', 'grounded'). */
+    readonly tags?: readonly string[];
+    /** Arbitrary metadata for tooling/debugging (e.g. animation hints, priority weights). */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 /** Registry of AI FSM states with built-in transition evaluation. */
 export declare class AIStateRegistry extends Registry<string, IAIStateDefinition> {

package/dist/registry/AIStateRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIStateRegistry.d.ts","sourceRoot":"","sources":["../../src/registry/AIStateRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,0FAA0F;IAC1F,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,8DAA8D;IAC9D,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACjD,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,iFAAiF;IACjF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,iFAAiF;IACjF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAChE,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACpE,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAClE;AAED,qEAAqE;AACrE,qBAAa,eAAgB,SAAQ,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;;IAKvE,8FAA8F;IACrF,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAQ/D,8HAA8H;IAC9H,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;CAS1E"}
+{"version":3,"file":"AIStateRegistry.d.ts","sourceRoot":"","sources":["../../src/registry/AIStateRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,0FAA0F;IAC1F,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,8DAA8D;IAC9D,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACjD,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,iFAAiF;IACjF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,iFAAiF;IACjF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAChE,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACpE,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACjE,wFAAwF;IACxF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,qEAAqE;AACrE,qBAAa,eAAgB,SAAQ,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;;IAKvE,8FAA8F;IACrF,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAQ/D,8HAA8H;IAC9H,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;CAS1E"}

package/dist/registry/AIStateRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"AIStateRegistry.js","sourceRoot":"","sources":["../../src/registry/AIStateRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAqCtC,qEAAqE;AACrE,MAAM,OAAO,eAAgB,SAAQ,QAAoC;IACvE;QACE,KAAK,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,8FAA8F;IACrF,QAAQ,CAAC,EAAU,EAAE,MAA0B;QACtD,MAAM,MAAM,GAAG,MAAM,CAAC,oBAAoB;YACxC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,oBAAoB,EAAE,CAAC,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE;YAC/G,CAAC,CAAC,MAAM,CAAC;QACX,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8HAA8H;IAC9H,mBAAmB,CAAC,YAAoB,EAAE,MAAe;QACvD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,EAAE,oBAAoB;YAAE,OAAO,IAAI,CAAC;QAE9C,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,oBAAoB,EAAE,CAAC;YAC5C,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC;gBAAE,OAAO,EAAE,CAAC,WAAW,CAAC;QAClD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"AIStateRegistry.js","sourceRoot":"","sources":["../../src/registry/AIStateRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAyCtC,qEAAqE;AACrE,MAAM,OAAO,eAAgB,SAAQ,QAAoC;IACvE;QACE,KAAK,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,8FAA8F;IACrF,QAAQ,CAAC,EAAU,EAAE,MAA0B;QACtD,MAAM,MAAM,GAAG,MAAM,CAAC,oBAAoB;YACxC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,oBAAoB,EAAE,CAAC,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE;YAC/G,CAAC,CAAC,MAAM,CAAC;QACX,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8HAA8H;IAC9H,mBAAmB,CAAC,YAAoB,EAAE,MAAe;QACvD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,EAAE,oBAAoB;YAAE,OAAO,IAAI,CAAC;QAE9C,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,oBAAoB,EAAE,CAAC;YAC5C,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC;gBAAE,OAAO,EAAE,CAAC,WAAW,CAAC;QAClD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alife-sdk/core",
-  "version": "0.1.1",
+  "version": "0.4.0",
   "description": "Framework-agnostic A-Life simulation and AI decision-making system",
   "type": "module",
   "sideEffects": false,