@oasys/oecs 0.4.0 → 0.5.0

package/dist/shallow-DfnAm9vG.js

@@ -0,0 +1,150 @@
+import { s as y, b as O, u as j } from "./kernel-DgyrLFjW.js";
+function S(p = Object.is) {
+  const l = /* @__PURE__ */ new Map(), [e, f] = y(0);
+  let i = 0;
+  const a = (s, r) => s !== void 0 && r !== void 0 ? p(s, r) : s === r;
+  return {
+    get(s) {
+      const r = l.get(s);
+      if (r !== void 0) return r[0]();
+      e();
+    },
+    set(s, r) {
+      const o = l.get(s);
+      o !== void 0 ? o[1](r) : (l.set(s, y(r, a)), f(++i));
+    },
+    delete(s) {
+      const r = l.get(s);
+      return r === void 0 ? !1 : (l.delete(s), O(() => {
+        r[1](void 0), f(++i);
+      }), !0);
+    },
+    has(s) {
+      return e(), l.has(s);
+    },
+    size() {
+      return e(), l.size;
+    },
+    keys() {
+      return e(), [...l.keys()];
+    }
+  };
+}
+function M(p, l = {}) {
+  const e = {}, f = {}, i = Object.keys(p), a = new Set(i);
+  for (const r of i) {
+    const [o, m] = y(
+      p[r],
+      l[r]
+    );
+    e[r] = o, f[r] = m;
+  }
+  return [new Proxy({}, {
+    // A field read subscribes; a NON-field key must not throw. `JSON.stringify`
+    // (`toJSON`), `await proxy` (`then`), `String(proxy)` (`Symbol.toPrimitive`)
+    // and `for..of` (`Symbol.iterator`) all probe keys that aren't fields — fall
+    // through to the (empty) target so they see the ordinary undefined/inherited
+    // value instead of calling `undefined()`. `fieldSet` (not `k in reads`) so
+    // inherited `toString`/`constructor` aren't mistaken for fields.
+    get: (r, o) => a.has(o) ? e[o]() : Reflect.get(r, o),
+    has: (r, o) => a.has(o),
+    // Enumerable without subscribing: enumeration calls `ownKeys` +
+    // `getOwnPropertyDescriptor`, never `get`, so `Object.keys(proxy)` returns
+    // the field set and tracks nothing. The descriptor is an ACCESSOR whose `get`
+    // reads the live signal, so `{...proxy}` / `Object.values(proxy)` /
+    // `Object.getOwnPropertyDescriptor(proxy, f).value` see the current value
+    // (a value-less descriptor would normalize to `value: undefined`). Non-field
+    // keys report no own descriptor. The target is the empty (extensible) object,
+    // so these configurable own keys satisfy the Proxy invariants.
+    ownKeys: () => i,
+    getOwnPropertyDescriptor: (r, o) => a.has(o) ? { get: () => e[o](), enumerable: !0, configurable: !0 } : void 0,
+    // Writes go through `set.field(v)` — the proxy is a READ surface, and its
+    // public type says so (`Readonly<T>`, POLISH_AUDIT #8). The trap backs the
+    // type for JS callers / policed casts: without it, a field assignment threw
+    // an opaque "Cannot redefine property" (the accessor descriptor above has no
+    // setter) and a TYPO'D field silently stuck on the hidden target as a
+    // non-reactive value.
+    set: (r, o) => !1
+  }), f];
+}
+const v = Symbol("reactiveArray.absent");
+function x(p = [], l = Object.is) {
+  const e = [], [f, i] = y(0);
+  let a = 0;
+  const s = (t, n) => t !== v && n !== v ? l(t, n) : t === n, r = (t) => y(t, s), o = (t) => j(e[t][0]);
+  for (const t of p) e.push(r(t));
+  function m(t) {
+    O(() => {
+      const n = e.length, h = t.length, g = h < n ? h : n;
+      for (let c = 0; c < g; c++) e[c][1](t[c]);
+      if (h > n) {
+        for (let c = n; c < h; c++) e.push(r(t[c]));
+        i(++a);
+      } else if (h < n) {
+        const c = e.splice(h);
+        for (let d = 0; d < c.length; d++) c[d][1](v);
+        i(++a);
+      }
+    });
+  }
+  return {
+    get(t) {
+      if (t >= 0 && t < e.length) {
+        const n = e[t][0]();
+        if (n !== v) return n;
+      }
+      f();
+    },
+    length() {
+      return f(), e.length;
+    },
+    snapshot() {
+      f();
+      const t = new Array(e.length);
+      for (let n = 0; n < e.length; n++) t[n] = e[n][0]();
+      return t;
+    },
+    set(t, n) {
+      t >= 0 && t < e.length && e[t][1](n);
+    },
+    push(t) {
+      e.push(r(t)), i(++a);
+    },
+    pop() {
+      const t = e.length;
+      if (t === 0) return;
+      const n = o(t - 1), [h] = e.splice(t - 1);
+      return O(() => {
+        h[1](v), i(++a);
+      }), n;
+    },
+    splice(t, n, ...h) {
+      const g = e.length, c = t < 0 ? Math.max(g + t, 0) : Math.min(t, g), d = n === void 0 ? g - c : Math.max(0, Math.min(n, g - c)), w = [];
+      for (let u = 0; u < d; u++) w.push(o(c + u));
+      const b = [];
+      for (let u = 0; u < c; u++) b.push(o(u));
+      for (let u = 0; u < h.length; u++) b.push(h[u]);
+      for (let u = c + d; u < g; u++) b.push(o(u));
+      return m(b), w;
+    },
+    reconcile(t) {
+      m(t);
+    }
+  };
+}
+function A(p, l) {
+  if (Object.is(p, l)) return !0;
+  const e = p, f = l, i = Object.keys(e);
+  if (i.length !== Object.keys(f).length) return !1;
+  for (let a = 0; a < i.length; a++) {
+    const s = i[a];
+    if (!Object.prototype.hasOwnProperty.call(f, s) || !Object.is(e[s], f[s])) return !1;
+  }
+  return !0;
+}
+export {
+  M as a,
+  x as b,
+  S as r,
+  A as s
+};

package/dist/shared-BU1Cd40h.js

@@ -0,0 +1,103 @@
+class u extends Error {
+  constructor(t, e, r, n) {
+    super(t, n), this.requestedBytes = e, this.capBytes = r, this.name = "StoreCapExceededError";
+  }
+}
+class c extends Error {
+  constructor() {
+    super(
+      "SharedArrayBuffer is not available in this runtime. The chosen world backing is SAB-based and cannot start without it. In browsers this requires cross-origin isolation: serve the page with `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (or `credentialless`). Alternatively choose the pure-TS heap profile (`memory: { heap: {} }`), which is backed by a plain ArrayBuffer and needs no SAB / no COOP+COEP. In Bun/Node SAB is available unconditionally — if you see this there, the runtime is older than expected or the global was shadowed."
+    ), this.name = "SabUnavailableError";
+  }
+}
+const d = (a) => {
+  if (typeof SharedArrayBuffer > "u") throw new c();
+  return new SharedArrayBuffer(a);
+}, h = 64 * 1024;
+function f(a, t, e) {
+  if (e <= 0 || !Number.isInteger(e))
+    throw new Error(`${a}: maxBytes must be a positive integer (got ${e})`);
+  let r = null;
+  const n = (o) => {
+    if (o > e)
+      throw new u(
+        `${a}: requested ${o} bytes exceeds the by-design maxBytes cap of ${e}. This is a hard ceiling with no grow-beyond-cap fallback (#380); a real workload stays ~16 MiB. Reaching it signals runaway entity/column growth upstream — diagnose that rather than raising the cap blindly.`,
+        o,
+        e
+      );
+    return r === null ? (r = t.create(o, e), r) : (o > r.byteLength && t.growTo(r, o), r);
+  };
+  return Object.defineProperty(n, "isInPlace", { value: !0, enumerable: !0 }), n;
+}
+function w(a = 256 * 1024 * 1024) {
+  if (typeof SharedArrayBuffer > "u") throw new c();
+  return f(
+    "growable_sab_allocator",
+    {
+      create: (t, e) => {
+        const r = SharedArrayBuffer;
+        return new r(t, { maxByteLength: e });
+      },
+      // boundary: SharedArrayBuffer.grow is in the spec but not in all
+      // lib types; widen here so the rest of the layer doesn't need to.
+      growTo: (t, e) => t.grow(e)
+    },
+    a
+  );
+}
+function b(a = 256 * 1024 * 1024) {
+  return f(
+    "heap_arraybuffer_allocator",
+    {
+      create: (t, e) => {
+        const r = ArrayBuffer;
+        return new r(t, { maxByteLength: e });
+      },
+      // boundary: `ArrayBuffer.prototype.resize` is ES2024, not in the ES2022
+      // lib types; widen here. Resize keeps the same buffer object and
+      // preserves existing views (the in-place contract).
+      growTo: (t, e) => t.resize(e)
+    },
+    a
+  );
+}
+function g(a) {
+  if (!(a.buffer instanceof SharedArrayBuffer))
+    throw new Error(
+      "wasm_memory_allocator: WebAssembly.Memory must be constructed with `shared: true` so its buffer is a SharedArrayBuffer"
+    );
+  const t = () => a.buffer, e = (r) => {
+    const n = a.buffer.byteLength;
+    if (r <= n)
+      return t();
+    const o = Math.ceil((r - n) / h), s = (i) => (
+      // The JS API doesn't expose the Memory's `maximum`, so the cap is
+      // reported as unknowable (`null`) — the caller declared it at
+      // `new WebAssembly.Memory({ maximum })` time.
+      new u(
+        `wasm_memory_allocator: memory.grow(${o}) failed (current=${n} bytes, requested=${r} bytes, maximum may be reached)`,
+        r,
+        null,
+        { cause: i }
+      )
+    );
+    let l;
+    try {
+      l = a.grow(o);
+    } catch (i) {
+      throw s(i);
+    }
+    if (l === -1)
+      throw s();
+    return t();
+  };
+  return Object.defineProperty(e, "isInPlace", { value: !0, enumerable: !0 }), e;
+}
+export {
+  d as D,
+  u as S,
+  c as a,
+  w as g,
+  b as h,
+  g as w
+};

package/dist/shared-BymrGTyR.cjs

@@ -0,0 +1 @@
+"use strict";class s extends Error{constructor(o,r,e,n){super(o,n),this.requestedBytes=r,this.capBytes=e,this.name="StoreCapExceededError"}}class l extends Error{constructor(){super("SharedArrayBuffer is not available in this runtime. The chosen world backing is SAB-based and cannot start without it. In browsers this requires cross-origin isolation: serve the page with `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (or `credentialless`). Alternatively choose the pure-TS heap profile (`memory: { heap: {} }`), which is backed by a plain ArrayBuffer and needs no SAB / no COOP+COEP. In Bun/Node SAB is available unconditionally — if you see this there, the runtime is older than expected or the global was shadowed."),this.name="SabUnavailableError"}}const h=a=>{if(typeof SharedArrayBuffer>"u")throw new l;return new SharedArrayBuffer(a)},d=64*1024;function f(a,o,r){if(r<=0||!Number.isInteger(r))throw new Error(`${a}: maxBytes must be a positive integer (got ${r})`);let e=null;const n=t=>{if(t>r)throw new s(`${a}: requested ${t} bytes exceeds the by-design maxBytes cap of ${r}. This is a hard ceiling with no grow-beyond-cap fallback (#380); a real workload stays ~16 MiB. Reaching it signals runaway entity/column growth upstream — diagnose that rather than raising the cap blindly.`,t,r);return e===null?(e=o.create(t,r),e):(t>e.byteLength&&o.growTo(e,t),e)};return Object.defineProperty(n,"isInPlace",{value:!0,enumerable:!0}),n}function b(a=256*1024*1024){if(typeof SharedArrayBuffer>"u")throw new l;return f("growable_sab_allocator",{create:(o,r)=>{const e=SharedArrayBuffer;return new e(o,{maxByteLength:r})},growTo:(o,r)=>o.grow(r)},a)}function w(a=256*1024*1024){return f("heap_arraybuffer_allocator",{create:(o,r)=>{const e=ArrayBuffer;return new e(o,{maxByteLength:r})},growTo:(o,r)=>o.resize(r)},a)}function A(a){if(!(a.buffer instanceof SharedArrayBuffer))throw new Error("wasm_memory_allocator: WebAssembly.Memory must be constructed with `shared: true` so its buffer is a SharedArrayBuffer");const o=()=>a.buffer,r=e=>{const n=a.buffer.byteLength;if(e<=n)return o();const t=Math.ceil((e-n)/d),c=i=>new s(`wasm_memory_allocator: memory.grow(${t}) failed (current=${n} bytes, requested=${e} bytes, maximum may be reached)`,e,null,{cause:i});let u;try{u=a.grow(t)}catch(i){throw c(i)}if(u===-1)throw c();return o()};return Object.defineProperty(r,"isInPlace",{value:!0,enumerable:!0}),r}exports.DEFAULT_SAB_ALLOCATOR=h;exports.SabUnavailableError=l;exports.StoreCapExceededError=s;exports.growableSabAllocator=b;exports.heapArraybufferAllocator=w;exports.wasmMemoryAllocator=A;

package/dist/shared.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("./shared-BXSZnxx4.cjs");exports.DEFAULT_SAB_ALLOCATOR=a.DEFAULT_SAB_ALLOCATOR;exports.SabUnavailableError=a.SabUnavailableError;exports.growableSabAllocator=a.growableSabAllocator;exports.wasmMemoryAllocator=a.wasmMemoryAllocator;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("./shared-BymrGTyR.cjs");exports.DEFAULT_SAB_ALLOCATOR=a.DEFAULT_SAB_ALLOCATOR;exports.SabUnavailableError=a.SabUnavailableError;exports.growableSabAllocator=a.growableSabAllocator;exports.wasmMemoryAllocator=a.wasmMemoryAllocator;

package/dist/shared.d.cts

@@ -0,0 +1,22 @@
+/**
+ * `@oasys/oecs/shared` — the opt-in SharedArrayBuffer / WASM profile.
+ *
+ * The default `@oasys/oecs` profile runs the column store over a plain
+ * resizable `ArrayBuffer` (no cross-origin isolation). This entry surfaces the
+ * `SharedArrayBuffer`-backed allocators for worlds that opt into worker offload
+ * or a WASM compute backend — construct with `new ECS({ memory: { shared: {} } })`,
+ * or pass one of these allocators through `memory: { allocator }`.
+ *
+ * **Requires cross-origin isolation (COOP/COEP) in browsers** — that's the
+ * whole reason it's a separate, opt-in profile.
+ *
+ * The WASM compute backend itself is NOT bundled here: oecs ships the
+ * `ComputeBackend` *seam* (`@oasys/oecs` → `attachBackend`) plus the
+ * cross-thread ring transport (`HostCommandDispatcher`). The worker entrypoint
+ * and the compiled WASM module are the consumer's to provide.
+ *
+ * @module
+ */
+export { growableSabAllocator, wasmMemoryAllocator, DEFAULT_SAB_ALLOCATOR, SabUnavailableError } from './core/store/index.cjs';
+export type { SharedMemoryArm } from './core/ecs/ecs_memory.cjs';
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts

@@ -17,6 +17,6 @@
  *
  * @module
  */
-export { growableSabAllocator, wasmMemoryAllocator, DEFAULT_SAB_ALLOCATOR, SabUnavailableError } from './core/store';
-export type { SharedMemoryArm } from './core/ecs/ecs_memory';
+export { growableSabAllocator, wasmMemoryAllocator, DEFAULT_SAB_ALLOCATOR, SabUnavailableError } from './core/store/index.js';
+export type { SharedMemoryArm } from './core/ecs/ecs_memory.js';
 //# sourceMappingURL=shared.d.ts.map

package/dist/shared.js

@@ -1,4 +1,4 @@
-import { D as r, a as l, g as A, w as s } from "./shared-C678TAPY.js";
+import { D as r, a as l, g as A, w as s } from "./shared-BU1Cd40h.js";
 export {
   r as DEFAULT_SAB_ALLOCATOR,
   l as SabUnavailableError,

package/dist/topological_sort-BDvEyb9W.cjs

@@ -0,0 +1 @@
+"use strict";class d{_denseKeys=[];_denseVals=[];_sparse=[];get size(){return this._denseKeys.length}get keys(){return this._denseKeys}has(s){return this._denseKeys[this._sparse[s]]===s}get(s){return this.has(s)?this._denseVals[this._sparse[s]]:void 0}set(s,t){if(this.has(s)){this._denseVals[this._sparse[s]]=t;return}this._sparse[s]=this._denseKeys.length,this._denseKeys.push(s),this._denseVals.push(t)}delete(s){if(!this.has(s))return!1;const t=this._sparse[s],i=this._denseKeys[this._denseKeys.length-1];return this._denseKeys[t]=i,this._denseVals[t]=this._denseVals[this._denseVals.length-1],this._sparse[i]=t,this._denseKeys.pop(),this._denseVals.pop(),!0}clear(){this._denseKeys.length=0,this._denseVals.length=0,this._sparse.length=0}forEach(s){for(let t=0;t<this._denseKeys.length;t++)s(this._denseKeys[t],this._denseVals[t])}[Symbol.iterator](){let s=0;const t=this._denseKeys,i=this._denseVals;return{next(){return s<t.length?{value:[t[s],i[s++]],done:!1}:{value:void 0,done:!0}}}}}class g{_compare;_data=[];constructor(s){this._compare=s}get size(){return this._data.length}peek(){return this._data[0]}push(s){this._data.push(s),this._siftUp(this._data.length-1)}pop(){const s=this._data;if(s.length===0)return;const i=s[0],h=s.pop();return s.length>0&&(s[0]=h,this._siftDown(0)),i}clear(){this._data.length=0}_siftUp(s){const t=this._data,i=this._compare,h=t[s];for(;s>0;){const n=s-1>>1;if(i(h,t[n])>=0)break;t[s]=t[n],s=n}t[s]=h}_siftDown(s){const t=this._data,i=this._compare,h=t.length,n=h>>1,c=t[s];for(;s<n;){let a=(s<<1)+1;const e=a+1;if(e<h&&i(t[e],t[a])<0&&(a=e),i(t[a],c)>=0)break;t[s]=t[a],s=a}t[s]=c}}function u(l,s,t,i){const h=i??(e=>String(e)),n=new Map;for(let e=0;e<l.length;e++)n.set(l[e],0);for(const[,e]of s)for(let r=0;r<e.length;r++){const o=e[r];n.has(o)&&n.set(o,n.get(o)+1)}const c=new g(t);for(let e=0;e<l.length;e++)n.get(l[e])===0&&c.push(l[e]);const a=[];for(;c.size>0;){const e=c.pop();a.push(e);const r=s.get(e);if(r!==void 0)for(let o=0;o<r.length;o++){const _=r[o];if(!n.has(_))continue;const p=n.get(_)-1;n.set(_,p),p===0&&c.push(_)}}if(a.length!==l.length){const e=[];for(const[r,o]of n)o>0&&e.push(h(r));throw new TypeError(`Cycle detected in topological sort. Nodes still pending: ${e.join(", ")}`)}return a}exports.BinaryHeap=g;exports.SparseMap=d;exports.topologicalSort=u;

package/dist/topological_sort-DK6EjpWa.js

@@ -0,0 +1,135 @@
+class g {
+  _denseKeys = [];
+  _denseVals = [];
+  _sparse = [];
+  get size() {
+    return this._denseKeys.length;
+  }
+  get keys() {
+    return this._denseKeys;
+  }
+  has(s) {
+    return this._denseKeys[this._sparse[s]] === s;
+  }
+  get(s) {
+    return this.has(s) ? this._denseVals[this._sparse[s]] : void 0;
+  }
+  set(s, t) {
+    if (this.has(s)) {
+      this._denseVals[this._sparse[s]] = t;
+      return;
+    }
+    this._sparse[s] = this._denseKeys.length, this._denseKeys.push(s), this._denseVals.push(t);
+  }
+  delete(s) {
+    if (!this.has(s)) return !1;
+    const t = this._sparse[s], h = this._denseKeys[this._denseKeys.length - 1];
+    return this._denseKeys[t] = h, this._denseVals[t] = this._denseVals[this._denseVals.length - 1], this._sparse[h] = t, this._denseKeys.pop(), this._denseVals.pop(), !0;
+  }
+  clear() {
+    this._denseKeys.length = 0, this._denseVals.length = 0, this._sparse.length = 0;
+  }
+  forEach(s) {
+    for (let t = 0; t < this._denseKeys.length; t++)
+      s(this._denseKeys[t], this._denseVals[t]);
+  }
+  [Symbol.iterator]() {
+    let s = 0;
+    const t = this._denseKeys, h = this._denseVals;
+    return {
+      next() {
+        return s < t.length ? { value: [t[s], h[s++]], done: !1 } : { value: void 0, done: !0 };
+      }
+    };
+  }
+}
+class d {
+  _compare;
+  _data = [];
+  constructor(s) {
+    this._compare = s;
+  }
+  get size() {
+    return this._data.length;
+  }
+  /** Returns the highest-priority element without removing it, or undefined if empty. */
+  peek() {
+    return this._data[0];
+  }
+  /** Inserts a value and restores heap order by sifting up. O(log n). */
+  push(s) {
+    this._data.push(s), this._siftUp(this._data.length - 1);
+  }
+  /** Removes and returns the highest-priority element, or undefined if empty. O(log n). */
+  pop() {
+    const s = this._data;
+    if (s.length === 0) return;
+    const h = s[0], i = s.pop();
+    return s.length > 0 && (s[0] = i, this._siftDown(0)), h;
+  }
+  /** Removes all elements. O(1). */
+  clear() {
+    this._data.length = 0;
+  }
+  /** Moves a node up toward the root until heap order is restored. */
+  _siftUp(s) {
+    const t = this._data, h = this._compare, i = t[s];
+    for (; s > 0; ) {
+      const n = s - 1 >> 1;
+      if (h(i, t[n]) >= 0) break;
+      t[s] = t[n], s = n;
+    }
+    t[s] = i;
+  }
+  /** Moves a node down away from the root until heap order is restored. */
+  _siftDown(s) {
+    const t = this._data, h = this._compare, i = t.length, n = i >> 1, c = t[s];
+    for (; s < n; ) {
+      let a = (s << 1) + 1;
+      const e = a + 1;
+      if (e < i && h(t[e], t[a]) < 0 && (a = e), h(t[a], c) >= 0) break;
+      t[s] = t[a], s = a;
+    }
+    t[s] = c;
+  }
+}
+function u(l, s, t, h) {
+  const i = h ?? ((e) => String(e)), n = /* @__PURE__ */ new Map();
+  for (let e = 0; e < l.length; e++)
+    n.set(l[e], 0);
+  for (const [, e] of s)
+    for (let r = 0; r < e.length; r++) {
+      const o = e[r];
+      n.has(o) && n.set(o, n.get(o) + 1);
+    }
+  const c = new d(t);
+  for (let e = 0; e < l.length; e++)
+    n.get(l[e]) === 0 && c.push(l[e]);
+  const a = [];
+  for (; c.size > 0; ) {
+    const e = c.pop();
+    a.push(e);
+    const r = s.get(e);
+    if (r !== void 0)
+      for (let o = 0; o < r.length; o++) {
+        const _ = r[o];
+        if (!n.has(_)) continue;
+        const p = n.get(_) - 1;
+        n.set(_, p), p === 0 && c.push(_);
+      }
+  }
+  if (a.length !== l.length) {
+    const e = [];
+    for (const [r, o] of n)
+      o > 0 && e.push(i(r));
+    throw new TypeError(
+      `Cycle detected in topological sort. Nodes still pending: ${e.join(", ")}`
+    );
+  }
+  return a;
+}
+export {
+  d as B,
+  g as S,
+  u as t
+};

package/dist/type_primitives/assertions.d.cts

@@ -0,0 +1,32 @@
+/***
+ * Assertions — Dev-only runtime validation and branded casting.
+ *
+ * All checks are guarded by DEV and tree-shaken in production builds.
+ * validateAndCast is the primary tool for creating branded IDs:
+ * it validates the input in dev and returns the value as the branded type.
+ * unsafeCast bypasses all checks (used when the caller guarantees validity).
+ *
+ ***/
+export declare const isNonNegativeInteger: (v: number) => boolean;
+export declare const isNonNull: (v: unknown) => boolean;
+/**
+ * Dev-only assertion that value is not null/undefined.
+ *
+ */
+export declare function assertNonNull<T>(value: T): asserts value is NonNullable<T>;
+export declare function assert<T, Result extends T = T>(value: T, condition: (v: T) => v is Result, errMessage: string): asserts value is Result;
+export declare function validateAndCast<T, Result extends T = T>(value: T, validator: (v: T) => boolean, errMessage: string): Result;
+export declare function unsafeCast<T>(value: unknown): T;
+/**
+ * Exhaustiveness backstop for tagged-union dispatches. Put it in the
+ * `default` arm (or after the final `case`) of a switch over a closed union:
+ * the `never` parameter makes "a union gained a variant but this dispatch
+ * didn't" a COMPILE error at the call site, and the throw catches runtime
+ * values that bypassed the type layer (deserialized/foreign data).
+ *
+ * Deliberately NOT `DEV`-gated, unlike the rest of this file: it marks a
+ * can't-happen branch, so it costs nothing until the day it fires — and that
+ * day it must fire in production too, not silently fall through.
+ */
+export declare function assertNever(value: never, label: string): never;
+//# sourceMappingURL=assertions.d.ts.map

package/dist/type_primitives/assertions.d.ts

@@ -1,7 +1,7 @@
 /***
  * Assertions — Dev-only runtime validation and branded casting.
  *
- * All checks are guarded by __DEV__ and tree-shaken in production builds.
+ * All checks are guarded by DEV and tree-shaken in production builds.
  * validateAndCast is the primary tool for creating branded IDs:
  * it validates the input in dev and returns the value as the branded type.
  * unsafeCast bypasses all checks (used when the caller guarantees validity).
@@ -17,4 +17,16 @@ export declare function assertNonNull<T>(value: T): asserts value is NonNullable
 export declare function assert<T, Result extends T = T>(value: T, condition: (v: T) => v is Result, errMessage: string): asserts value is Result;
 export declare function validateAndCast<T, Result extends T = T>(value: T, validator: (v: T) => boolean, errMessage: string): Result;
 export declare function unsafeCast<T>(value: unknown): T;
+/**
+ * Exhaustiveness backstop for tagged-union dispatches. Put it in the
+ * `default` arm (or after the final `case`) of a switch over a closed union:
+ * the `never` parameter makes "a union gained a variant but this dispatch
+ * didn't" a COMPILE error at the call site, and the throw catches runtime
+ * values that bypassed the type layer (deserialized/foreign data).
+ *
+ * Deliberately NOT `DEV`-gated, unlike the rest of this file: it marks a
+ * can't-happen branch, so it costs nothing until the day it fires — and that
+ * day it must fire in production too, not silently fall through.
+ */
+export declare function assertNever(value: never, label: string): never;
 //# sourceMappingURL=assertions.d.ts.map

package/dist/type_primitives/assertions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../../src/type_primitives/assertions.ts"],"names":[],"mappings":"AAAA;;;;;;;;KAQK;AAIL,eAAO,MAAM,oBAAoB,MAAO,MAAM,KAAG,OAAwC,CAAC;AAE1F,eAAO,MAAM,SAAS,MAAO,OAAO,KAAG,OAAqB,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CAU1E;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,SAAS,CAAC,GAAG,CAAC,EAC7C,KAAK,EAAE,CAAC,EACR,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,MAAM,EAChC,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,IAAI,MAAM,CAOzB;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,SAAS,CAAC,GAAG,CAAC,EACtD,KAAK,EAAE,CAAC,EACR,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,EAC5B,UAAU,EAAE,MAAM,GAChB,MAAM,CAQR;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAE/C"}
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../../src/type_primitives/assertions.ts"],"names":[],"mappings":"AAAA;;;;;;;;KAQK;AAKL,eAAO,MAAM,oBAAoB,MAAO,MAAM,KAAG,OAAwC,CAAC;AAE1F,eAAO,MAAM,SAAS,MAAO,OAAO,KAAG,OAAqB,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CAU1E;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,SAAS,CAAC,GAAG,CAAC,EAC7C,KAAK,EAAE,CAAC,EACR,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,MAAM,EAChC,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,IAAI,MAAM,CAOzB;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,SAAS,CAAC,GAAG,CAAC,EACtD,KAAK,EAAE,CAAC,EACR,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,EAC5B,UAAU,EAAE,MAAM,GAChB,MAAM,CAQR;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAE/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAK9D"}

package/dist/type_primitives/binary_heap/binary_heap.d.cts

@@ -0,0 +1,37 @@
+/***
+ * BinaryHeap — generic array-backed binary heap with configurable ordering.
+ *
+ * Array layout uses implicit indexing: root at index 0, children of node `i`
+ * at `2i + 1` and `2i + 2`, parent of node `i` at `(i - 1) >> 1`.
+ *
+ * The comparator determines ordering: when `compare(a, b) < 0`, `a` has
+ * higher priority and floats toward the root. A standard `(a, b) => a - b`
+ * comparator yields a min-heap; `(a, b) => b - a` yields a max-heap.
+ *
+ * push and pop are O(log n). peek and clear are O(1).
+ *
+ ***/
+export type CompareFn<T> = (a: T, b: T) => number;
+/**
+ * Generic array-backed binary heap with configurable comparator.
+ *
+ */
+export declare class BinaryHeap<T> {
+    private readonly _compare;
+    private readonly _data;
+    constructor(compare: CompareFn<T>);
+    get size(): number;
+    /** Returns the highest-priority element without removing it, or undefined if empty. */
+    peek(): T | undefined;
+    /** Inserts a value and restores heap order by sifting up. O(log n). */
+    push(value: T): void;
+    /** Removes and returns the highest-priority element, or undefined if empty. O(log n). */
+    pop(): T | undefined;
+    /** Removes all elements. O(1). */
+    clear(): void;
+    /** Moves a node up toward the root until heap order is restored. */
+    private _siftUp;
+    /** Moves a node down away from the root until heap order is restored. */
+    private _siftDown;
+}
+//# sourceMappingURL=binary_heap.d.ts.map

package/dist/type_primitives/bitset/bitset.d.cts

@@ -0,0 +1,54 @@
+/***
+ * BitSet — number[]-backed bit set with auto-grow.
+ *
+ * Used as the archetype component signature. Each bit position corresponds
+ * to a ComponentID. Operations (has/set/clear) are O(1), and mask
+ * comparisons (contains, equals, overlaps) are O(words) where
+ * words = ceil(maxComponentId / 32).
+ *
+ * Bit layout within each 32-bit word:
+ *   wordIndex = bit >>> BITS_PER_WORD_SHIFT   (divide by 32)
+ *   bit_offset = bit & BITS_PER_WORD_MASK      (mod 32)
+ *   test:  word & (1 << offset)
+ *   set:   word |= (1 << offset)
+ *   clear: word &= ~(1 << offset)
+ *
+ ***/
+export declare const BITS_PER_WORD = 32;
+export declare const BITS_PER_WORD_SHIFT = 5;
+export declare const BITS_PER_WORD_MASK = 31;
+export declare const FNV_OFFSET_BASIS = 2166136261;
+export declare const FNV_PRIME = 16777619;
+/**
+ * number[]-backed bit set with auto-grow. Used as the archetype component signature.
+ *
+ */
+export declare class BitSet {
+    _words: number[];
+    constructor(words?: number[]);
+    has(bit: number): boolean;
+    set(bit: number): void;
+    clear(bit: number): void;
+    /** True if no bit is set. */
+    isEmpty(): boolean;
+    /** True if any bit is set in both this and other (non-empty intersection). */
+    overlaps(other: BitSet): boolean;
+    /** True if this is a superset of other (all bits in other are set in this). */
+    contains(other: BitSet): boolean;
+    equals(other: BitSet): boolean;
+    copy(): BitSet;
+    /** Mutate `target` so it has the same set bits as `this`. Reuses
+     * `target._words` storage when capacity allows (no allocation) and
+     * grows it only when `this` is wider. Designed for hot-path scratch
+     * BitSets where callers want `.copy()` semantics without the
+     * per-call allocation. Returns `target` for chaining. */
+    copyInto(target: BitSet): BitSet;
+    copyWithSet(bit: number): BitSet;
+    copyWithClear(bit: number): BitSet;
+    /** FNV-1a hash. Skips trailing zero words so differently-sized arrays with the same bits hash equally. */
+    hash(): number;
+    /** Iterate all set bits via lowest-set-bit extraction. */
+    forEach(fn: (bit: number) => void): void;
+    private grow;
+}
+//# sourceMappingURL=bitset.d.ts.map

package/dist/type_primitives/brand.d.cts

@@ -0,0 +1,23 @@
+/***
+ * Brand — Nominal typing for TypeScript.
+ *
+ * Brand<T, Name> intersects T with a phantom readonly symbol property
+ * tagged with Name. The symbol never exists at runtime — it only prevents
+ * accidental assignment between structurally identical types.
+ *
+ * Example: EntityID and ComponentID are both numbers at runtime, but
+ * Brand<number, "entityId"> and Brand<number, "component_id"> are
+ * incompatible at compile time.
+ *
+ ***/
+declare const brand: unique symbol;
+/**
+ * Nominal typing helper — intersects T with a phantom readonly symbol
+ * so structurally identical types become compile-time incompatible.
+ *
+ */
+export type Brand<T, BrandName extends string> = T & {
+    readonly [brand]: BrandName;
+};
+export {};
+//# sourceMappingURL=brand.d.ts.map

package/dist/type_primitives/error.d.cts

@@ -0,0 +1,16 @@
+import { AppError } from '../utils/error.cjs';
+export declare enum TYPE_ERROR {
+    ASSERTION_FAIL_CONDITION = "ASSERTION_FAIL_CONDITION",
+    VALIDATION_FAIL_CONDITION = "VALIDATION_FAIL_CONDITION",
+    ASSERTION_FAIL_NON_NULLABLE = "ASSERTION_FAIL_NON_NULLABLE",
+    ASSERTION_FAIL_UNREACHABLE = "ASSERTION_FAIL_UNREACHABLE"
+}
+/**
+ * Error class thrown by std's runtime assertions. Non-operational.
+ *
+ */
+export declare class AssertionError extends AppError {
+    readonly category: TYPE_ERROR;
+    constructor(category: TYPE_ERROR, message: string, context?: Record<string, unknown>);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/type_primitives/error.d.ts

@@ -1,14 +1,15 @@
-import { AppError } from '../utils/error';
+import { AppError } from '../utils/error.js';
 export declare enum TYPE_ERROR {
     ASSERTION_FAIL_CONDITION = "ASSERTION_FAIL_CONDITION",
     VALIDATION_FAIL_CONDITION = "VALIDATION_FAIL_CONDITION",
-    ASSERTION_FAIL_NON_NULLABLE = "ASSERTION_FAIL_NON_NULLABLE"
+    ASSERTION_FAIL_NON_NULLABLE = "ASSERTION_FAIL_NON_NULLABLE",
+    ASSERTION_FAIL_UNREACHABLE = "ASSERTION_FAIL_UNREACHABLE"
 }
 /**
  * Error class thrown by std's runtime assertions. Non-operational.
  *
  */
-export declare class TypeError extends AppError {
+export declare class AssertionError extends AppError {
     readonly category: TYPE_ERROR;
     constructor(category: TYPE_ERROR, message: string, context?: Record<string, unknown>);
 }