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

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

@@ -0,0 +1,144 @@
+import type { Handle } from '@forgeax/engine-types';
+import { type Result } from '@forgeax/engine-types';
+import { BuiltinSlotNotOwnedError, SharedRefDoubleReleaseError, SharedRefReleasedError, SharedRefStaleError } from './errors';
+export interface SharedRefMutation {
+    readonly epoch: number;
+    readonly handle: number;
+}
+export interface SharedRefReleaseEvidence {
+    readonly payload: unknown;
+    readonly refcount: 0;
+    readonly generation: number;
+    readonly evidence: 'released';
+}
+export type SharedRefMutationRead = {
+    readonly status: 'ok';
+    readonly cursor: number;
+    readonly records: readonly SharedRefMutation[];
+} | {
+    readonly status: 'overflow';
+    readonly cursor: number;
+    readonly oldestAvailable: number;
+};
+/**
+ * Reference-counted store for ECS-aware `Handle<T, 'shared'>` lifecycles.
+ *
+ * The producer (typically AssetRegistry) calls `alloc` once and owns the
+ * "alloc-grant" rc=1; consumers (ECS schema fields, external systems) call
+ * `retain` on each new holder and `release` when the holder drops. When rc
+ * transitions 1 -> 0 the store publishes one structured release-evidence
+ * record; it does not invoke a user callback or own payload disposal.
+ *
+ * D-15: manages ONLY user-tier slots (`slot >= BUILTIN_BASE`). Builtin slots
+ * (`< BUILTIN_BASE`) fail-fast with `BuiltinSlotNotOwnedError`.
+ *
+ * Public API:
+ *   - alloc(target, payload)        -> Handle<T, 'shared'> (rc=1)
+ *   - intern(target, payload)        -> stable producer handle per target + object identity
+ *   - resolve(handle)             -> Result<T, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError>
+ *   - markChanged(handle)         -> Result<void, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError>
+ *   - getMutationEpoch()          -> monotonic payload-mutation cursor
+ *   - retain(handle)              -> Result<void, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError>
+ *   - release(handle)             -> Result<release evidence | undefined, ...>
+ *   - refcount(handle)            -> number (0 == released; debug + tests)
+ *   - _liveCount()                -> live slot count (debug + inspector)
+ */
+export declare class SharedRefStore {
+    private readonly payloads;
+    private readonly refcounts;
+    private readonly freeSlots;
+    private readonly internedByTarget;
+    private readonly internedKeys;
+    private nextSlot;
+    private mutationEpoch;
+    private readonly mutationJournal;
+    private readonly releaseJournal;
+    /**
+     * 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).
+     *
+     * @internal
+     */
+    private readonly _generations;
+    /**
+     * Allocate a fresh shared handle for `payload`, branded against `target`.
+     * Refcount starts at 1 (the alloc-grant). Nullish payloads are rejected
+     * before a slot or free-list is touched.
+     *
+     * 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 toShared brand cast
+     * happens internally — external callers no longer construct Handle<...>
+     * directly.
+     *
+     * Minted slots are user-tier (`>= BUILTIN_BASE`); builtin slots are never
+     * produced here (D-15).
+     */
+    alloc<Target extends string, T = unknown>(target: Target, payload: T): Handle<Target, 'shared'>;
+    /**
+     * Return the idempotent producer handle for one object payload in this
+     * store. Identity includes `target`, so the same object branded for two
+     * asset kinds does not alias.
+     *
+     * A cache hit deliberately does not retain: this is one producer grant,
+     * discovered repeatedly by an asset catalogue. Actual holders retain and
+     * release through the ECS write barrier. Callers needing independent
+     * grants or a per-handle deleter must use {@link alloc}.
+     */
+    intern<Target extends string, T extends object>(target: Target, payload: T): Handle<Target, 'shared'>;
+    /**
+     * Look up `payload` by handle. Returns `err(shared-ref-released)` when
+     * the handle's slot has no live payload (rc reached 0, no re-alloc has
+     * filled the slot); `err(builtin-slot-not-owned)` for a builtin slot.
+     *
+     * §contract - mirrors UniqueRefStore: a stale handle whose slot has been
+     * released and re-allocated returns `err(shared-ref-stale)` - the handle's
+     * welded generation no longer matches `_generations[slot]`. The gen check
+     * runs before payload lookup, so stale-by-reuse is caught deterministically.
+     */
+    resolve<Target extends string, T = unknown>(handle: Handle<Target, 'shared'>): Result<T, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError>;
+    /**
+     * Publish that a live payload was mutated in place. Consumers that retain
+     * projections of shared payload data compare the monotonic epoch and
+     * explicitly refresh instead of rescanning every payload each frame.
+     */
+    markChanged<Target extends string>(handle: Handle<Target, 'shared'>): Result<void, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError>;
+    /** Current upper bound for explicitly published payload mutations. */
+    getMutationEpoch(): number;
+    /** Read exact changed handles after `cursor`; overflow requires consumer resync. */
+    readChangesSince(cursor: number): SharedRefMutationRead;
+    /**
+     * Increment the refcount of a live shared handle. Returns
+     * `err(shared-ref-released)` when the handle is not live - retain MUST
+     * NOT resurrect a released slot (charter P3 explicit failure; would
+     * defeat the rc=0 -> drop invariant); `err(builtin-slot-not-owned)` for a
+     * builtin slot.
+     */
+    retain<Target extends string>(handle: Handle<Target, 'shared'>): Result<void, SharedRefReleasedError | SharedRefStaleError | BuiltinSlotNotOwnedError>;
+    /**
+     * Decrement the refcount. When rc transitions 1 -> 0, the slot is dropped
+     * and one structured release-evidence record is published. The evidence
+     * captures the payload, zero refcount, next generation and `released` marker
+     * after the store has removed the live slot.
+     *
+     * Returns `err(shared-ref-double-release, rc=0)` when the handle has
+     * already reached rc=0 (or was never live); `err(builtin-slot-not-owned)`
+     * for a builtin slot. AI users branch on `.code` and route the
+     * second-release log to Layer 3 ErrorHandler without aborting the despawn
+     * chain.
+     */
+    release<Target extends string>(handle: Handle<Target, 'shared'>): Result<SharedRefReleaseEvidence | undefined, SharedRefDoubleReleaseError | SharedRefStaleError | BuiltinSlotNotOwnedError>;
+    /** Read the bounded release evidence owned by this store. */
+    readReleaseEvidence(): readonly SharedRefReleaseEvidence[];
+    /**
+     * Return the current refcount for `handle`. Returns 0 for a released
+     * (or never-allocated) slot. Primarily a debug + tests entry point;
+     * production code rarely reads rc directly (the rc=0 -> drop invariant
+     * is the surface AI users consume via release / the per-handle deleter).
+     */
+    refcount<Target extends string>(handle: Handle<Target, 'shared'>): number;
+    /** @internal Diagnostic count of live slots. Exposed for tests + inspector. */
+    _liveCount(): number;
+}
+//# sourceMappingURL=shared-ref-store.d.ts.map

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

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

package/dist/shared.d.ts

@@ -0,0 +1,3 @@
+export type { KernelDispatchFailure, KernelDispatchResult, KernelDispatchSpan, SharedFieldView, SharedKernelDefinition, SharedKernelDispatch, SharedKernelEligibilityReason, SharedKernelExecutor, SharedKernelHandle, SharedSpanBinding, WorldExecutionHealth, } from './execution/shared-kernel';
+export { bindSharedSpan, defineSharedKernel, isKernelDispatchFailure, isSharedSpan, SHARED_KERNEL_ELIGIBILITY_REASONS, SHARED_KERNEL_EXECUTOR_RESOURCE_KEY, sharedKernelEligibility, splitSharedSpan, } from './execution/shared-kernel';
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,6BAA6B,EAC7B,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,EACZ,iCAAiC,EACjC,mCAAmC,EACnC,uBAAuB,EACvB,eAAe,GAChB,MAAM,2BAA2B,CAAC"}

package/dist/shared.mjs

@@ -0,0 +1,364 @@
+import '@forgeax/engine-types';
+
+// src/component.ts
+var FIELD_SIZE_BYTES = {
+  f32: 4,
+  f64: 8,
+  i32: 4,
+  u32: 4,
+  i16: 2,
+  u16: 2,
+  i8: 1,
+  u8: 1,
+  bool: 1,
+  enum: 4,
+  ref: 4
+};
+var COMPONENT_OWNER_REGISTRY = /* @__PURE__ */ Symbol.for("forgeax.ecs.componentOwnerRegistry");
+var ownerSymbols = globalThis;
+var ownerRegistry = ownerSymbols[COMPONENT_OWNER_REGISTRY] ?? (() => {
+  const registry = {
+    nextId: 1,
+    ids: /* @__PURE__ */ new WeakMap(),
+    schemas: /* @__PURE__ */ new WeakMap()
+  };
+  ownerSymbols[COMPONENT_OWNER_REGISTRY] = registry;
+  return registry;
+})();
+function componentId(component) {
+  const id = ownerRegistry.ids.get(component);
+  if (id === void 0) throw new Error(`Component identity missing for '${component.name}'.`);
+  return id;
+}
+function componentSchema(component) {
+  const schema = ownerRegistry.schemas.get(component);
+  if (schema === void 0) throw new Error(`Component schema missing for '${component.name}'.`);
+  return schema;
+}
+var VIEW_CTORS = {
+  f32: Float32Array,
+  f64: Float64Array,
+  i32: Int32Array,
+  u32: Uint32Array,
+  i16: Int16Array,
+  u16: Uint16Array,
+  i8: Int8Array,
+  u8: Uint8Array,
+  bool: Uint8Array,
+  enum: Uint32Array,
+  ref: Uint32Array
+};
+function scalarRow(t) {
+  return {
+    byteSize: FIELD_SIZE_BYTES[t],
+    viewCtor: VIEW_CTORS[t],
+    storage: t,
+    isScalar: true,
+    // The scalar `ref` shares its key with the vocab `ref<T>` family; mark
+    // it as managed so the single row covers both.
+    isManaged: t === "ref",
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: false
+  };
+}
+Object.freeze({
+  f32: scalarRow("f32"),
+  f64: scalarRow("f64"),
+  i32: scalarRow("i32"),
+  u32: scalarRow("u32"),
+  i16: scalarRow("i16"),
+  u16: scalarRow("u16"),
+  i8: scalarRow("i8"),
+  u8: scalarRow("u8"),
+  bool: scalarRow("bool"),
+  enum: scalarRow("enum"),
+  ref: scalarRow("ref"),
+  entity: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: false,
+    isBuffer: false,
+    isEntityRef: true,
+    isArray: false
+  },
+  string: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: true,
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: false
+  },
+  buffer: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: false,
+    isBuffer: true,
+    isEntityRef: false,
+    isArray: false
+  },
+  // feat-20260614-ecs-shared-component-and-unique-rename M3 (plan-strategy
+  // D-3): independent `'shared'` row, NOT a reuse of the `'ref'` (post-M2:
+  // `'unique<T>'` family) row. `isManaged: true` so write-barrier dispatch
+  // routes shared<T> fields through release on despawn / removeComponent /
+  // set-overwrite, but the M4 sub-dispatch in releaseManagedFieldOnRow will
+  // separate shared (rc--) from unique (direct slot drop) using the
+  // fieldType.startsWith('shared<') predicate. Keeping the meta key
+  // independent preserves the "meta key = release semantics" invariant
+  // (architecture-principles.md #1 SSOT).
+  shared: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: true,
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: false
+  },
+  array: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: false,
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: true
+  }
+});
+
+// src/world-internal.ts
+var worldInternal = /* @__PURE__ */ Symbol.for(
+  "forgeax.ecs.worldInternal"
+);
+
+// src/execution/shared-kernel.ts
+var SHARED_KERNEL_EXECUTOR_RESOURCE_KEY = "SharedKernelExecutor";
+function isKernelDispatchFailure(value) {
+  return "cause" in value;
+}
+var SHARED_KERNEL_ELIGIBILITY_REASONS = [
+  "callback-not-module-function",
+  "dom-access",
+  "missing-access-declaration",
+  "descriptor-conflict",
+  "object-field",
+  "span-unavailable"
+];
+var SharedKernelEligibilityError = class extends Error {
+  code = "shared-kernel-ineligible";
+  expected = "a module-loadable named kernel with one or more numeric QuerySpan read/write declarations";
+  hint = "export a named function from the kernel module and use only dense numeric QuerySpan columns";
+  detail;
+  constructor(kernelName, reason) {
+    super(`Shared kernel "${kernelName}" is ineligible: ${reason}.`);
+    this.name = "SharedKernelEligibilityError";
+    this.detail = { kernelName, reason };
+  }
+};
+var SharedKernelFailureError = class extends Error {
+  code = "shared-kernel-failed";
+  expected = "every dispatched shard completes without a possible partial write";
+  hint = "do not retry this World; inspect detail.cause and rebuild with a new World identity";
+  detail;
+  constructor(kernelName, worldIdentity, cause, partialWrite) {
+    super(`Shared kernel "${kernelName}" failed; World ${worldIdentity} is poisoned.`);
+    this.name = "SharedKernelFailureError";
+    this.detail = { kernelName, worldIdentity, cause, partialWrite, retryable: false };
+  }
+};
+var NUMERIC_FIELDS = /* @__PURE__ */ new Set([
+  "f32",
+  "f64",
+  "i32",
+  "u32",
+  "i16",
+  "u16",
+  "i8",
+  "u8",
+  "bool",
+  "enum",
+  "ref",
+  "entity"
+]);
+function components(descriptor) {
+  return [
+    ...descriptor.read ?? [],
+    ...descriptor.write ?? [],
+    ...descriptor.optional ?? [],
+    ...descriptor.with ?? [],
+    ...descriptor.without ?? [],
+    ...descriptor.changed ?? [],
+    ...descriptor.added ?? []
+  ];
+}
+function descriptorReason(descriptor) {
+  if ((descriptor.read?.length ?? 0) + (descriptor.write?.length ?? 0) === 0) {
+    return "missing-access-declaration";
+  }
+  if ((descriptor.optional?.length ?? 0) > 0 || (descriptor.changed?.length ?? 0) > 0 || (descriptor.added?.length ?? 0) > 0) {
+    return "span-unavailable";
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const component of components(descriptor)) {
+    if (seen.has(componentId(component))) return "descriptor-conflict";
+    seen.add(componentId(component));
+    if (component.storage === "sparse") return "span-unavailable";
+    if (Object.values(componentSchema(component)).some((field) => !NUMERIC_FIELDS.has(field))) {
+      return "object-field";
+    }
+  }
+  return void 0;
+}
+function sharedKernelEligibility(moduleUrl, definition) {
+  try {
+    new URL(moduleUrl);
+  } catch {
+    return "callback-not-module-function";
+  }
+  const source = Function.prototype.toString.call(definition.run);
+  if (definition.run.name.length === 0 || source.includes("=>")) {
+    return "callback-not-module-function";
+  }
+  if (/\b(?:document|window|globalThis|HTMLElement|GPUDevice|AudioContext)\b/u.test(source)) {
+    return "dom-access";
+  }
+  for (const query of definition.queries) {
+    const reason = descriptorReason(query);
+    if (reason !== void 0) return reason;
+  }
+  return void 0;
+}
+function defineSharedKernel(moduleUrl, definition) {
+  const reason = sharedKernelEligibility(moduleUrl, definition);
+  if (reason !== void 0) throw new SharedKernelEligibilityError(definition.name, reason);
+  const handle = Object.freeze({
+    kind: "shared-kernel",
+    moduleUrl,
+    name: definition.name,
+    queries: definition.queries,
+    minimumRows: definition.minimumRows ?? 16384,
+    run: definition.run,
+    ...definition.before !== void 0 ? { before: definition.before } : {},
+    ...definition.after !== void 0 ? { after: definition.after } : {},
+    fn: (world, queries) => {
+      const dispatchSpans = [];
+      for (const [queryIndex, query] of queries.entries()) {
+        const result = query.spans();
+        if (!result.ok) throw new SharedKernelEligibilityError(definition.name, "span-unavailable");
+        for (const span of result.value) dispatchSpans.push({ queryIndex, span });
+      }
+      const spans = dispatchSpans.map((entry) => entry.span);
+      const totalRows = spans.reduce((sum, span) => sum + span.length, 0);
+      try {
+        if (totalRows < (definition.minimumRows ?? 16384) || !world.hasResource(SHARED_KERNEL_EXECUTOR_RESOURCE_KEY)) {
+          definition.run(spans);
+          return;
+        }
+        const executor = world.getResource(
+          SHARED_KERNEL_EXECUTOR_RESOURCE_KEY
+        );
+        const result = executor.execute(handle, dispatchSpans);
+        if (isKernelDispatchFailure(result)) {
+          if (!result.partialWrite) {
+            definition.run(spans);
+            return;
+          }
+          world[worldInternal].poisonExecution({
+            code: "shared-kernel-failed",
+            kernelName: definition.name,
+            cause: result.cause,
+            partialWrite: result.partialWrite,
+            retryable: false
+          });
+          throw new SharedKernelFailureError(
+            definition.name,
+            world.execution.identity,
+            result.cause,
+            result.partialWrite
+          );
+        }
+      } catch (cause) {
+        if (world.execution.health !== "poisoned") {
+          world[worldInternal].poisonExecution({
+            code: "shared-kernel-failed",
+            kernelName: definition.name,
+            cause,
+            partialWrite: true,
+            retryable: false
+          });
+        }
+        if (cause instanceof SharedKernelFailureError) throw cause;
+        throw new SharedKernelFailureError(definition.name, world.execution.identity, cause, true);
+      }
+    }
+  });
+  return handle;
+}
+function sliceFields(fields, start, end) {
+  return Object.fromEntries(
+    Object.entries(fields).map(([name, view]) => [name, view.subarray(start, end)])
+  );
+}
+function bindSharedSpan(kernel, span, queryIndex) {
+  const descriptor = kernel.queries[queryIndex];
+  if (descriptor === void 0) throw new Error(`Missing query descriptor ${queryIndex}.`);
+  const read = Object.fromEntries(
+    (descriptor.read ?? []).map((component) => [
+      component.name,
+      span.get(component)
+    ])
+  );
+  const write = Object.fromEntries(
+    (descriptor.write ?? []).map((component) => [
+      component.name,
+      span.mut(component)
+    ])
+  );
+  return { entities: span.entities, length: span.length, read, write };
+}
+function splitSharedSpan(binding, shardCount) {
+  if (binding.length === 0 || shardCount <= 0) return [];
+  const count = Math.min(binding.length, shardCount);
+  const shards = [];
+  for (let index = 0; index < count; index += 1) {
+    const start = Math.floor(binding.length * index / count);
+    const end = Math.floor(binding.length * (index + 1) / count);
+    shards.push({
+      entities: binding.entities.subarray(start, end),
+      length: end - start,
+      read: Object.fromEntries(
+        Object.entries(binding.read).map(([component, fields]) => [
+          component,
+          sliceFields(fields, start, end)
+        ])
+      ),
+      write: Object.fromEntries(
+        Object.entries(binding.write).map(([component, fields]) => [
+          component,
+          sliceFields(fields, start, end)
+        ])
+      )
+    });
+  }
+  return shards;
+}
+function isSharedSpan(binding) {
+  if (typeof SharedArrayBuffer === "undefined") return false;
+  if (!(binding.entities.buffer instanceof SharedArrayBuffer)) return false;
+  return [...Object.values(binding.read), ...Object.values(binding.write)].every(
+    (fields) => Object.values(fields).every((view) => view.buffer instanceof SharedArrayBuffer)
+  );
+}
+
+export { SHARED_KERNEL_ELIGIBILITY_REASONS, SHARED_KERNEL_EXECUTOR_RESOURCE_KEY, bindSharedSpan, defineSharedKernel, isKernelDispatchFailure, isSharedSpan, sharedKernelEligibility, splitSharedSpan };
+//# sourceMappingURL=shared.mjs.map
+//# sourceMappingURL=shared.mjs.map