@oasys/oecs 0.3.1 → 0.5.0

package/dist/core/ecs/utils/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const UNASSIGNED = -1;
+export declare const NO_SWAP = -1;
+export declare const EMPTY_VALUES: Record<string, number>;
+export declare const HASH_GOLDEN_RATIO = 2654435769;
+export declare const HASH_SECONDARY_PRIME = 1367130551;
+export declare const DEFAULT_COLUMN_CAPACITY = 1024;
+export declare const INITIAL_GENERATION = 0;
+export declare const TOTAL_PACKED_BITS = 31;
+export declare const DEFAULT_FIXED_TIMESTEP: number;
+export declare const DEFAULT_MAX_FIXED_STEPS = 4;
+export declare const STARTUP_DELTA_TIME = 0;
+//# sourceMappingURL=constants.d.ts.map

package/dist/core/ecs/utils/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/core/ecs/utils/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,OAAO,KAAK,CAAC;AAC1B,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAsC,CAAC;AAGvF,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAC5C,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAG/C,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAG5C,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAGpC,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAGzC,eAAO,MAAM,kBAAkB,IAAI,CAAC"}

package/dist/core/ecs/utils/error.d.cts

@@ -0,0 +1,61 @@
+import { AppError } from '../../../utils/error.cjs';
+export declare enum ECS_ERROR {
+    EID_MAX_INDEX_OVERFLOW = "EID_MAX_INDEX_OVERFLOW",
+    EID_MAX_GEN_OVERFLOW = "EID_MAX_GEN_OVERFLOW",
+    COMPONENT_NOT_REGISTERED = "COMPONENT_NOT_REGISTERED",
+    COMPONENT_LIMIT_EXCEEDED = "COMPONENT_LIMIT_EXCEEDED",
+    ENTITY_NOT_ALIVE = "ENTITY_NOT_ALIVE",
+    CIRCULAR_SYSTEM_DEPENDENCY = "CIRCULAR_SYSTEM_DEPENDENCY",
+    DUPLICATE_SYSTEM = "DUPLICATE_SYSTEM",
+    ARCHETYPE_NOT_FOUND = "ARCHETYPE_NOT_FOUND",
+    RESOURCE_NOT_REGISTERED = "RESOURCE_NOT_REGISTERED",
+    RESOURCE_ALREADY_REGISTERED = "RESOURCE_ALREADY_REGISTERED",
+    EVENT_ALREADY_REGISTERED = "EVENT_ALREADY_REGISTERED",
+    EVENT_NOT_REGISTERED = "EVENT_NOT_REGISTERED",
+    FIELD_NOT_REGISTERED = "FIELD_NOT_REGISTERED",
+    RELATION_NOT_REGISTERED = "RELATION_NOT_REGISTERED",
+    RELATION_MODE_INVALID = "RELATION_MODE_INVALID",
+    RELATION_MODE_MISMATCH = "RELATION_MODE_MISMATCH",
+    RELATION_CYCLE = "RELATION_CYCLE",
+    SPARSE_CACHE_KEY_OVERFLOW = "SPARSE_CACHE_KEY_OVERFLOW",
+    SPARSE_QUERY_DENSE_PATH = "SPARSE_QUERY_DENSE_PATH",
+    HIERARCHY_ALREADY_SET = "HIERARCHY_ALREADY_SET",
+    HIERARCHY_INVALID_MAX_DEPTH = "HIERARCHY_INVALID_MAX_DEPTH",
+    OBSERVER_NON_CONVERGENT = "OBSERVER_NON_CONVERGENT",
+    OBSERVER_INVALID_CONFIG = "OBSERVER_INVALID_CONFIG",
+    OBSERVER_ONSET_EMIT = "OBSERVER_ONSET_EMIT",
+    INVALID_FIXED_TIMESTEP = "INVALID_FIXED_TIMESTEP",
+    INVALID_MAX_FIXED_STEPS = "INVALID_MAX_FIXED_STEPS",
+    INVALID_RECORDER_SCHEDULE = "INVALID_RECORDER_SCHEDULE",
+    EMPTY_ARCHETYPE_MATERIALIZE = "EMPTY_ARCHETYPE_MATERIALIZE",
+    COMPONENT_INDEX_INVARIANT = "COMPONENT_INDEX_INVARIANT",
+    OPTIONAL_TERM_NOT_DECLARED = "OPTIONAL_TERM_NOT_DECLARED",
+    QUERY_ACCESS_UNDECLARED = "QUERY_ACCESS_UNDECLARED",
+    /** A system touched a component/sparse/relation/resource it didn't declare
+     * in its access surface — distinct from *_NOT_REGISTERED (which means the
+     * thing was never registered with the world at all). */
+    ACCESS_UNDECLARED = "ACCESS_UNDECLARED",
+    /** `Query.singleEntity` found 0 or >1 matches (dev-only assertion). */
+    QUERY_NOT_SINGLETON = "QUERY_NOT_SINGLETON",
+    /** A run-condition factory was given invalid arguments (dev-only). */
+    INVALID_RUN_CONDITION = "INVALID_RUN_CONDITION",
+    SYSTEM_FN_ARITY = "SYSTEM_FN_ARITY",
+    PARTITION_APPEND_NEEDS_ENTITY_ROW = "PARTITION_APPEND_NEEDS_ENTITY_ROW",
+    PARTITION_BULK_INTO_DISABLED = "PARTITION_BULK_INTO_DISABLED",
+    ENTITY_NOT_DISABLED = "ENTITY_NOT_DISABLED",
+    STRUCTURAL_DURING_ITERATION = "STRUCTURAL_DURING_ITERATION",
+    BACKEND_ALREADY_ATTACHED = "BACKEND_ALREADY_ATTACHED",
+    DETERMINISM_DISABLED = "DETERMINISM_DISABLED",
+    NON_DETERMINISTIC_COLUMN_TYPE = "NON_DETERMINISTIC_COLUMN_TYPE",
+    INVALID_MEMORY_OPTIONS = "INVALID_MEMORY_OPTIONS",
+    STORE_CAP_EXCEEDED = "STORE_CAP_EXCEEDED",
+    REGION_NOT_DECLARED = "REGION_NOT_DECLARED",
+    COMMAND_LOG_TAG_COLLISION = "COMMAND_LOG_TAG_COLLISION",
+    INVALID_FRAME_STEP = "INVALID_FRAME_STEP"
+}
+export declare class ECSError extends AppError {
+    readonly category: ECS_ERROR;
+    constructor(category: ECS_ERROR, message?: string, context?: Record<string, unknown>);
+}
+export declare function isEcsError(error: unknown): error is ECSError;
+//# sourceMappingURL=error.d.ts.map

package/dist/core/ecs/utils/error.d.ts

@@ -0,0 +1,61 @@
+import { AppError } from '../../../utils/error.js';
+export declare enum ECS_ERROR {
+    EID_MAX_INDEX_OVERFLOW = "EID_MAX_INDEX_OVERFLOW",
+    EID_MAX_GEN_OVERFLOW = "EID_MAX_GEN_OVERFLOW",
+    COMPONENT_NOT_REGISTERED = "COMPONENT_NOT_REGISTERED",
+    COMPONENT_LIMIT_EXCEEDED = "COMPONENT_LIMIT_EXCEEDED",
+    ENTITY_NOT_ALIVE = "ENTITY_NOT_ALIVE",
+    CIRCULAR_SYSTEM_DEPENDENCY = "CIRCULAR_SYSTEM_DEPENDENCY",
+    DUPLICATE_SYSTEM = "DUPLICATE_SYSTEM",
+    ARCHETYPE_NOT_FOUND = "ARCHETYPE_NOT_FOUND",
+    RESOURCE_NOT_REGISTERED = "RESOURCE_NOT_REGISTERED",
+    RESOURCE_ALREADY_REGISTERED = "RESOURCE_ALREADY_REGISTERED",
+    EVENT_ALREADY_REGISTERED = "EVENT_ALREADY_REGISTERED",
+    EVENT_NOT_REGISTERED = "EVENT_NOT_REGISTERED",
+    FIELD_NOT_REGISTERED = "FIELD_NOT_REGISTERED",
+    RELATION_NOT_REGISTERED = "RELATION_NOT_REGISTERED",
+    RELATION_MODE_INVALID = "RELATION_MODE_INVALID",
+    RELATION_MODE_MISMATCH = "RELATION_MODE_MISMATCH",
+    RELATION_CYCLE = "RELATION_CYCLE",
+    SPARSE_CACHE_KEY_OVERFLOW = "SPARSE_CACHE_KEY_OVERFLOW",
+    SPARSE_QUERY_DENSE_PATH = "SPARSE_QUERY_DENSE_PATH",
+    HIERARCHY_ALREADY_SET = "HIERARCHY_ALREADY_SET",
+    HIERARCHY_INVALID_MAX_DEPTH = "HIERARCHY_INVALID_MAX_DEPTH",
+    OBSERVER_NON_CONVERGENT = "OBSERVER_NON_CONVERGENT",
+    OBSERVER_INVALID_CONFIG = "OBSERVER_INVALID_CONFIG",
+    OBSERVER_ONSET_EMIT = "OBSERVER_ONSET_EMIT",
+    INVALID_FIXED_TIMESTEP = "INVALID_FIXED_TIMESTEP",
+    INVALID_MAX_FIXED_STEPS = "INVALID_MAX_FIXED_STEPS",
+    INVALID_RECORDER_SCHEDULE = "INVALID_RECORDER_SCHEDULE",
+    EMPTY_ARCHETYPE_MATERIALIZE = "EMPTY_ARCHETYPE_MATERIALIZE",
+    COMPONENT_INDEX_INVARIANT = "COMPONENT_INDEX_INVARIANT",
+    OPTIONAL_TERM_NOT_DECLARED = "OPTIONAL_TERM_NOT_DECLARED",
+    QUERY_ACCESS_UNDECLARED = "QUERY_ACCESS_UNDECLARED",
+    /** A system touched a component/sparse/relation/resource it didn't declare
+     * in its access surface — distinct from *_NOT_REGISTERED (which means the
+     * thing was never registered with the world at all). */
+    ACCESS_UNDECLARED = "ACCESS_UNDECLARED",
+    /** `Query.singleEntity` found 0 or >1 matches (dev-only assertion). */
+    QUERY_NOT_SINGLETON = "QUERY_NOT_SINGLETON",
+    /** A run-condition factory was given invalid arguments (dev-only). */
+    INVALID_RUN_CONDITION = "INVALID_RUN_CONDITION",
+    SYSTEM_FN_ARITY = "SYSTEM_FN_ARITY",
+    PARTITION_APPEND_NEEDS_ENTITY_ROW = "PARTITION_APPEND_NEEDS_ENTITY_ROW",
+    PARTITION_BULK_INTO_DISABLED = "PARTITION_BULK_INTO_DISABLED",
+    ENTITY_NOT_DISABLED = "ENTITY_NOT_DISABLED",
+    STRUCTURAL_DURING_ITERATION = "STRUCTURAL_DURING_ITERATION",
+    BACKEND_ALREADY_ATTACHED = "BACKEND_ALREADY_ATTACHED",
+    DETERMINISM_DISABLED = "DETERMINISM_DISABLED",
+    NON_DETERMINISTIC_COLUMN_TYPE = "NON_DETERMINISTIC_COLUMN_TYPE",
+    INVALID_MEMORY_OPTIONS = "INVALID_MEMORY_OPTIONS",
+    STORE_CAP_EXCEEDED = "STORE_CAP_EXCEEDED",
+    REGION_NOT_DECLARED = "REGION_NOT_DECLARED",
+    COMMAND_LOG_TAG_COLLISION = "COMMAND_LOG_TAG_COLLISION",
+    INVALID_FRAME_STEP = "INVALID_FRAME_STEP"
+}
+export declare class ECSError extends AppError {
+    readonly category: ECS_ERROR;
+    constructor(category: ECS_ERROR, message?: string, context?: Record<string, unknown>);
+}
+export declare function isEcsError(error: unknown): error is ECSError;
+//# sourceMappingURL=error.d.ts.map

package/dist/core/ecs/utils/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../src/core/ecs/utils/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,oBAAY,SAAS;IACpB,sBAAsB,2BAA2B;IACjD,oBAAoB,yBAAyB;IAC7C,wBAAwB,6BAA6B;IACrD,wBAAwB,6BAA6B;IACrD,gBAAgB,qBAAqB;IACrC,0BAA0B,+BAA+B;IACzD,gBAAgB,qBAAqB;IACrC,mBAAmB,wBAAwB;IAC3C,uBAAuB,4BAA4B;IACnD,2BAA2B,gCAAgC;IAC3D,wBAAwB,6BAA6B;IACrD,oBAAoB,yBAAyB;IAC7C,oBAAoB,yBAAyB;IAC7C,uBAAuB,4BAA4B;IACnD,qBAAqB,0BAA0B;IAC/C,sBAAsB,2BAA2B;IACjD,cAAc,mBAAmB;IACjC,yBAAyB,8BAA8B;IACvD,uBAAuB,4BAA4B;IACnD,qBAAqB,0BAA0B;IAC/C,2BAA2B,gCAAgC;IAC3D,uBAAuB,4BAA4B;IACnD,uBAAuB,4BAA4B;IACnD,mBAAmB,wBAAwB;IAC3C,sBAAsB,2BAA2B;IACjD,uBAAuB,4BAA4B;IACnD,yBAAyB,8BAA8B;IACvD,2BAA2B,gCAAgC;IAC3D,yBAAyB,8BAA8B;IACvD,0BAA0B,+BAA+B;IACzD,uBAAuB,4BAA4B;IACnD;;4DAEwD;IACxD,iBAAiB,sBAAsB;IACvC,uEAAuE;IACvE,mBAAmB,wBAAwB;IAC3C,sEAAsE;IACtE,qBAAqB,0BAA0B;IAC/C,eAAe,oBAAoB;IACnC,iCAAiC,sCAAsC;IACvE,4BAA4B,iCAAiC;IAC7D,mBAAmB,wBAAwB;IAC3C,2BAA2B,gCAAgC;IAC3D,wBAAwB,6BAA6B;IACrD,oBAAoB,yBAAyB;IAC7C,6BAA6B,kCAAkC;IAC/D,sBAAsB,2BAA2B;IACjD,kBAAkB,uBAAuB;IACzC,mBAAmB,wBAAwB;IAC3C,yBAAyB,8BAA8B;IACvD,kBAAkB,uBAAuB;CACzC;AAED,qBAAa,QAAS,SAAQ,QAAQ;aAEpB,QAAQ,EAAE,SAAS;gBAAnB,QAAQ,EAAE,SAAS,EACnC,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAIlC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D"}

package/dist/core/store/action_ring.d.cts

@@ -0,0 +1,136 @@
+/**
+ * Action ring — main-thread producer / worker-thread consumer SPSC ring
+ * for client input intents (`send_action`-shaped bytes). Plan §6.5 task
+ * 3 / `docs/ideas/buffer-wasm-sim-plan-2026-05-14T1600.md`.
+ *
+ * Same on-the-wire shape as `command_ring.ts`, but with two practical
+ * differences:
+ *
+ *   1. Producer/consumer roles flip — the action ring is main → worker,
+ *      whereas the command ring is sim → host.
+ *   2. Slot payload carries a `length` prefix because client actions are
+ *      variable-width (the encoded bytes that would normally go straight
+ *      to the WebSocket). `payload[0]` is the length in bytes; bytes
+ *      `[1..1+length)` are the action payload itself.
+ *
+ * Layout (identical to command ring header):
+ *
+ *   [ write_head:   u32 ]   monotonic; modulo `capacity_slots` for slot
+ *   [ read_head:    u32 ]   monotonic
+ *   [ capacity:     u32 ]   slot count, power-of-two
+ *   [ overflow:     u32 ]   0 = OK; 1 = ring exhausted (producer side)
+ *   [ slot 0:       16 B ]  length: u8, payload: [15]u8
+ *   [ slot 1:       16 B ]  ...
+ *
+ * SPSC contract:
+ *   - Producer: main thread, from `GameNetworkClient.send_action`. Pushes
+ *     one entry per user action; `Atomics.store`s `write_head` after each.
+ *   - Consumer: sim worker, drained on each `apply_diff` / `apply_snapshot`
+ *     boundary. `Atomics.store`s `read_head` after each pop.
+ *   - Today's consumer is a no-op observer (logs / counts in DEV) — the
+ *     wire path still goes main → WebSocket → server. PR 5N migrates the
+ *     `PredictionReconciler` into the worker so the action ring becomes
+ *     load-bearing for client-side prediction.
+ *
+ * Overflow:
+ *   - If main writes a slot when `(write_head - read_head) === capacity`,
+ *     it sets `overflow = 1` and the push returns `false`. The server
+ *     send path is independent (`_transport.send(...)` ran first), so an
+ *     overflow doesn't drop the action — it only drops worker
+ *     observability for that one entry.
+ *
+ * Atomics: the head fields (`write_head` / `read_head`) are the
+ * cross-thread synchronization edge — the producer runs on the main
+ * thread, the consumer in the sim worker, and both alias the same
+ * `SharedArrayBuffer`. The producer writes the slot bytes, then
+ * `Atomics.store`s `write_head`; the consumer `Atomics.load`s
+ * `write_head` before touching the slot, reads it, then `Atomics.store`s
+ * `read_head`. These SeqCst ops establish the happens-before that a
+ * plain `DataView` write does not under the JS memory model (#374):
+ * without them the worker could observe a bumped `write_head` before the
+ * producer's `setUint8(len)` + payload `set()` are visible and read a
+ * torn/stale slot, and the producer could read a stale `read_head`
+ * (false overflow, or overwrite a slot mid-read). Slot payload bytes
+ * stay on plain `DataView` / `Uint8Array` ops — the head Atomics fence
+ * them, so no per-byte atomic is needed. A future PR may still add an
+ * `Atomics.wait/notify` pair so the worker can block between actions
+ * instead of polling — additive change, no layout shift.
+ */
+/** Total bytes for the ring header. Identical to `command_ring`. */
+export declare const ACTION_RING_HEADER_BYTES = 16;
+/** Fixed slot size — 1-byte length + 15-byte payload. */
+export declare const ACTION_RING_SLOT_BYTES = 16;
+/** Default ring capacity in slots. Sized for ~250 ms of click-spam at 60
+ * Hz on the high end of human input rates; 256 × 16 B = 4 KiB + 16 B
+ * header. */
+export declare const ACTION_RING_DEFAULT_CAPACITY_SLOTS = 256;
+/** Max payload bytes per slot (slot size minus the length prefix). All
+ * actions defined in `packages/protocol/src/actions.ts` encode to under
+ * 8 bytes, so this is comfortably above today's max. */
+export declare const ACTION_RING_MAX_PAYLOAD_BYTES: number;
+/** Byte offsets within the ring header. Matches `command_ring` so a
+ * future shared helper can normalise across both rings without per-ring
+ * arithmetic. */
+export declare const ACTION_RING_HEADER_OFFSETS: {
+    readonly write_head: 0;
+    readonly read_head: 4;
+    readonly capacity_slots: 8;
+    readonly overflow_flag: 12;
+};
+/** Total bytes the ring occupies for `capacity_slots` slots. */
+export declare function actionRingBytes(capacitySlots: number): number;
+export declare class ActionRingError extends Error {
+    constructor(message: string);
+}
+/** Initialise the ring header at `ringOff` in the SAB. Zeroes heads
+ * and the overflow flag; sets `capacity_slots`. Slot bytes are left
+ * as-is (callers normally allocate the ring on a zero-initialised SAB). */
+export declare function initActionRing(view: DataView, ringOff: number, capacitySlots: number): void;
+/** Read live ring-header fields. Heads are stored signed but returned
+ * unsigned (`>>> 0`) so the monotonic-counter arithmetic below is
+ * identical to the prior `getUint32` behaviour. */
+export declare function actionRingWriteHead(view: DataView, ringOff: number): number;
+export declare function actionRingReadHead(view: DataView, ringOff: number): number;
+export declare function actionRingCapacitySlots(view: DataView, ringOff: number): number;
+export declare function actionRingOverflow(view: DataView, ringOff: number): boolean;
+/** Pending entry count = `(write_head - read_head) mod 2^32`. */
+export declare function pendingActionCount(view: DataView, ringOff: number): number;
+/** Push an action into the ring. `payload` must be in
+ * `[1, ACTION_RING_MAX_PAYLOAD_BYTES]`; longer payloads — and **empty**
+ * ones — are an `ActionRingError` (the producer is the only caller and it
+ * can size its inputs ahead of time). The zero-length rejection closes the
+ * lower-bound footgun: a 0-byte slot is indistinguishable from
+ * `popAction`'s empty-ring sentinel (`0`), so admitting one would let it
+ * masquerade as "ring empty". No encoder produces a 0-byte payload, so this
+ * only ever rejects the ABI-skew bug case (#430). Returns `false` on
+ * overflow and sets the overflow flag. */
+export declare function pushAction(view: DataView, ringOff: number, payload: Uint8Array): boolean;
+/** Pop one action from the ring. Returns the byte length written into
+ * `outPayload`, or `0` if the ring was empty. `outPayload` must be at
+ * least `ACTION_RING_MAX_PAYLOAD_BYTES`; only the first `length` bytes
+ * are meaningful after a non-zero return.
+ *
+ * NOTE: a `0` return is ambiguous — it means "ring empty" OR "a 0-byte
+ * slot" (the latter only reachable via ABI-skew, since `pushAction`
+ * rejects empty payloads). Callers that loop must decide emptiness from
+ * the heads (`pendingActionCount` / `write_head === read_head`), not
+ * from this return value; see `drainActionRing` and #430. */
+export declare function popAction(view: DataView, ringOff: number, outPayload: Uint8Array): number;
+/** Drain every pending action, invoking `handler(payload)` per entry.
+ * The `payload` passed to the handler is a freshly-copied
+ * `Uint8Array(length)` so handlers can hold it past the next pop without
+ * aliasing the scratch buffer. Returns the number of actions drained.
+ *
+ * Termination is decided from the heads (`pendingActionCount`), NOT from
+ * `popAction`'s return value. A genuine 0-byte slot returns `0` — the same
+ * value `popAction` yields on an empty ring — so terminating on `len === 0`
+ * would silently consume the zero-length entry and strand everything queued
+ * behind it for a tick (#430). The heads check is SPSC-safe: this consumer
+ * is the sole reader, so a non-zero pending count cannot race to empty before
+ * the `popAction` below. */
+export declare function drainActionRing(view: DataView, ringOff: number, handler: (payload: Uint8Array) => void): number;
+/** Clear the overflow flag. The producer sets it on a failed push; the
+ * consumer can reset it once it has observed and logged the condition,
+ * so a single overflow doesn't keep firing dev assertions. */
+export declare function clearActionRingOverflow(view: DataView, ringOff: number): void;
+//# sourceMappingURL=action_ring.d.ts.map

package/dist/core/store/action_ring.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Action ring — main-thread producer / worker-thread consumer SPSC ring
+ * for client input intents (`send_action`-shaped bytes). Plan §6.5 task
+ * 3 / `docs/ideas/buffer-wasm-sim-plan-2026-05-14T1600.md`.
+ *
+ * Same on-the-wire shape as `command_ring.ts`, but with two practical
+ * differences:
+ *
+ *   1. Producer/consumer roles flip — the action ring is main → worker,
+ *      whereas the command ring is sim → host.
+ *   2. Slot payload carries a `length` prefix because client actions are
+ *      variable-width (the encoded bytes that would normally go straight
+ *      to the WebSocket). `payload[0]` is the length in bytes; bytes
+ *      `[1..1+length)` are the action payload itself.
+ *
+ * Layout (identical to command ring header):
+ *
+ *   [ write_head:   u32 ]   monotonic; modulo `capacity_slots` for slot
+ *   [ read_head:    u32 ]   monotonic
+ *   [ capacity:     u32 ]   slot count, power-of-two
+ *   [ overflow:     u32 ]   0 = OK; 1 = ring exhausted (producer side)
+ *   [ slot 0:       16 B ]  length: u8, payload: [15]u8
+ *   [ slot 1:       16 B ]  ...
+ *
+ * SPSC contract:
+ *   - Producer: main thread, from `GameNetworkClient.send_action`. Pushes
+ *     one entry per user action; `Atomics.store`s `write_head` after each.
+ *   - Consumer: sim worker, drained on each `apply_diff` / `apply_snapshot`
+ *     boundary. `Atomics.store`s `read_head` after each pop.
+ *   - Today's consumer is a no-op observer (logs / counts in DEV) — the
+ *     wire path still goes main → WebSocket → server. PR 5N migrates the
+ *     `PredictionReconciler` into the worker so the action ring becomes
+ *     load-bearing for client-side prediction.
+ *
+ * Overflow:
+ *   - If main writes a slot when `(write_head - read_head) === capacity`,
+ *     it sets `overflow = 1` and the push returns `false`. The server
+ *     send path is independent (`_transport.send(...)` ran first), so an
+ *     overflow doesn't drop the action — it only drops worker
+ *     observability for that one entry.
+ *
+ * Atomics: the head fields (`write_head` / `read_head`) are the
+ * cross-thread synchronization edge — the producer runs on the main
+ * thread, the consumer in the sim worker, and both alias the same
+ * `SharedArrayBuffer`. The producer writes the slot bytes, then
+ * `Atomics.store`s `write_head`; the consumer `Atomics.load`s
+ * `write_head` before touching the slot, reads it, then `Atomics.store`s
+ * `read_head`. These SeqCst ops establish the happens-before that a
+ * plain `DataView` write does not under the JS memory model (#374):
+ * without them the worker could observe a bumped `write_head` before the
+ * producer's `setUint8(len)` + payload `set()` are visible and read a
+ * torn/stale slot, and the producer could read a stale `read_head`
+ * (false overflow, or overwrite a slot mid-read). Slot payload bytes
+ * stay on plain `DataView` / `Uint8Array` ops — the head Atomics fence
+ * them, so no per-byte atomic is needed. A future PR may still add an
+ * `Atomics.wait/notify` pair so the worker can block between actions
+ * instead of polling — additive change, no layout shift.
+ */
+/** Total bytes for the ring header. Identical to `command_ring`. */
+export declare const ACTION_RING_HEADER_BYTES = 16;
+/** Fixed slot size — 1-byte length + 15-byte payload. */
+export declare const ACTION_RING_SLOT_BYTES = 16;
+/** Default ring capacity in slots. Sized for ~250 ms of click-spam at 60
+ * Hz on the high end of human input rates; 256 × 16 B = 4 KiB + 16 B
+ * header. */
+export declare const ACTION_RING_DEFAULT_CAPACITY_SLOTS = 256;
+/** Max payload bytes per slot (slot size minus the length prefix). All
+ * actions defined in `packages/protocol/src/actions.ts` encode to under
+ * 8 bytes, so this is comfortably above today's max. */
+export declare const ACTION_RING_MAX_PAYLOAD_BYTES: number;
+/** Byte offsets within the ring header. Matches `command_ring` so a
+ * future shared helper can normalise across both rings without per-ring
+ * arithmetic. */
+export declare const ACTION_RING_HEADER_OFFSETS: {
+    readonly write_head: 0;
+    readonly read_head: 4;
+    readonly capacity_slots: 8;
+    readonly overflow_flag: 12;
+};
+/** Total bytes the ring occupies for `capacity_slots` slots. */
+export declare function actionRingBytes(capacitySlots: number): number;
+export declare class ActionRingError extends Error {
+    constructor(message: string);
+}
+/** Initialise the ring header at `ringOff` in the SAB. Zeroes heads
+ * and the overflow flag; sets `capacity_slots`. Slot bytes are left
+ * as-is (callers normally allocate the ring on a zero-initialised SAB). */
+export declare function initActionRing(view: DataView, ringOff: number, capacitySlots: number): void;
+/** Read live ring-header fields. Heads are stored signed but returned
+ * unsigned (`>>> 0`) so the monotonic-counter arithmetic below is
+ * identical to the prior `getUint32` behaviour. */
+export declare function actionRingWriteHead(view: DataView, ringOff: number): number;
+export declare function actionRingReadHead(view: DataView, ringOff: number): number;
+export declare function actionRingCapacitySlots(view: DataView, ringOff: number): number;
+export declare function actionRingOverflow(view: DataView, ringOff: number): boolean;
+/** Pending entry count = `(write_head - read_head) mod 2^32`. */
+export declare function pendingActionCount(view: DataView, ringOff: number): number;
+/** Push an action into the ring. `payload` must be in
+ * `[1, ACTION_RING_MAX_PAYLOAD_BYTES]`; longer payloads — and **empty**
+ * ones — are an `ActionRingError` (the producer is the only caller and it
+ * can size its inputs ahead of time). The zero-length rejection closes the
+ * lower-bound footgun: a 0-byte slot is indistinguishable from
+ * `popAction`'s empty-ring sentinel (`0`), so admitting one would let it
+ * masquerade as "ring empty". No encoder produces a 0-byte payload, so this
+ * only ever rejects the ABI-skew bug case (#430). Returns `false` on
+ * overflow and sets the overflow flag. */
+export declare function pushAction(view: DataView, ringOff: number, payload: Uint8Array): boolean;
+/** Pop one action from the ring. Returns the byte length written into
+ * `outPayload`, or `0` if the ring was empty. `outPayload` must be at
+ * least `ACTION_RING_MAX_PAYLOAD_BYTES`; only the first `length` bytes
+ * are meaningful after a non-zero return.
+ *
+ * NOTE: a `0` return is ambiguous — it means "ring empty" OR "a 0-byte
+ * slot" (the latter only reachable via ABI-skew, since `pushAction`
+ * rejects empty payloads). Callers that loop must decide emptiness from
+ * the heads (`pendingActionCount` / `write_head === read_head`), not
+ * from this return value; see `drainActionRing` and #430. */
+export declare function popAction(view: DataView, ringOff: number, outPayload: Uint8Array): number;
+/** Drain every pending action, invoking `handler(payload)` per entry.
+ * The `payload` passed to the handler is a freshly-copied
+ * `Uint8Array(length)` so handlers can hold it past the next pop without
+ * aliasing the scratch buffer. Returns the number of actions drained.
+ *
+ * Termination is decided from the heads (`pendingActionCount`), NOT from
+ * `popAction`'s return value. A genuine 0-byte slot returns `0` — the same
+ * value `popAction` yields on an empty ring — so terminating on `len === 0`
+ * would silently consume the zero-length entry and strand everything queued
+ * behind it for a tick (#430). The heads check is SPSC-safe: this consumer
+ * is the sole reader, so a non-zero pending count cannot race to empty before
+ * the `popAction` below. */
+export declare function drainActionRing(view: DataView, ringOff: number, handler: (payload: Uint8Array) => void): number;
+/** Clear the overflow flag. The producer sets it on a failed push; the
+ * consumer can reset it once it has observed and logged the condition,
+ * so a single overflow doesn't keep firing dev assertions. */
+export declare function clearActionRingOverflow(view: DataView, ringOff: number): void;
+//# sourceMappingURL=action_ring.d.ts.map

package/dist/core/store/action_ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action_ring.d.ts","sourceRoot":"","sources":["../../../src/core/store/action_ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;aAEa;AACb,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD;;wDAEwD;AACxD,eAAO,MAAM,6BAA6B,QAA6B,CAAC;AAExE;;iBAEiB;AACjB,eAAO,MAAM,0BAA0B;;;;;CAK7B,CAAC;AAwBX,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE7D;AAMD,qBAAa,eAAgB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI3B;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAiB3F;AAED;;mDAEmD;AACnD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3E;AACD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AACD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/E;AACD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;;;0CAQ0C;AAC1C,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAoCxF;AAED;;;;;;;;;6DAS6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAwBzF;AAED;;;;;;;;;;;4BAW4B;AAC5B,wBAAgB,eAAe,CAC9B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GACpC,MAAM,CAUR;AAED;;8DAE8D;AAC9D,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7E"}