bun-shared-memory 0.0.0-stage → 0.1.1

package/src/shared.ts

@@ -0,0 +1,957 @@
+import {
+  SharedMemory,
+  TYPE_ARRAY_REF,
+  TYPE_BIGINT_STR,
+  arrayRefSlot,
+  bigintSlot,
+  bigintStrSlot,
+  booleanSlot,
+  decodeSlot,
+  numberSlot,
+  stringRefSlot,
+  type ArrayRef,
+  type ObjectLayout,
+  type StringRef,
+  type ValueSlot,
+} from "./memory.ts";
+import type { RefCountTracker } from "./refcount.ts";
+import { getDefaultMemory, getDefaultTracker } from "./worker.ts";
+
+/** Array methods that mutate the array in place. */
+const MUTATING_METHODS = new Set([
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+  "sort",
+  "reverse",
+  "fill",
+  "copyWithin",
+]);
+
+type Primitive = number | string | boolean | bigint;
+
+/** Inclusive bounds of a signed 64-bit integer (stored as a fast int64 slot). */
+const MIN_INT64 = -(2n ** 63n);
+const MAX_INT64 = 2n ** 63n - 1n;
+
+/** Convert a JS value into a ValueSlot, storing strings/arrays in tables. */
+function encodeValue(
+  mem: SharedMemory,
+  value: unknown,
+  arrayCapacity?: number,
+): ValueSlot {
+  switch (typeof value) {
+    case "number":
+      return numberSlot(value);
+    case "boolean":
+      return booleanSlot(value);
+    case "bigint":
+      // Bigints that fit in 64 bits are stored as a fast int64 slot; larger
+      // ones are stored as their decimal string in the StringTable.
+      if (value >= MIN_INT64 && value <= MAX_INT64) {
+        return bigintSlot(value);
+      }
+      return bigintStrSlot(mem.storeString(value.toString()));
+    case "string":
+      return stringRefSlot(mem.storeString(value));
+    default:
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          if (Array.isArray(v) || (v !== null && typeof v === "object")) {
+            throw new TypeError(
+              "Arrays may only contain primitives and bigints (no nested arrays or objects)",
+            );
+          }
+        }
+        const slots = value.map((v) => encodeValue(mem, v, arrayCapacity));
+        return arrayRefSlot(mem.storeArray(slots, arrayCapacity));
+      }
+      throw new TypeError(
+        `Cannot store value of type ${typeof value}: only primitives, bigints, and arrays of these are allowed`,
+      );
+  }
+}
+
+/** Decode a ValueSlot into a JS value, reading strings/arrays from tables. */
+function decodeValue(mem: SharedMemory, slot: ValueSlot): unknown {
+  switch (slot.type) {
+    case 3: // string-ref
+      return mem.readString({ offset: slot.a, length: slot.b });
+    case TYPE_BIGINT_STR: // bigint stored as decimal string
+      return BigInt(mem.readString({ offset: slot.a, length: slot.b }));
+    case 4: // array-ref
+      return mem
+        .readArray({ offset: slot.a, count: slot.b, capacity: slot.c })
+        .map((s) => decodeValue(mem, s));
+    default:
+      return decodeSlot(slot);
+  }
+}
+
+/**
+ * A reference to a value stored in shared memory.
+ *
+ * Exposes direct property access to the shared value. For objects, properties
+ * are accessed directly (e.g. `user.name`). For arrays, index access and
+ * mutating methods (push, pop, splice, ...) work directly. All access is
+ * synchronized with an Atomics-based lock.
+ */
+export type SharedRef<T> = [T] extends [object]
+  ? T & {
+      read(): T;
+      write(value: T): void;
+      update(fn: (current: T) => T): T;
+      readonly key: string;
+      readonly buffer: SharedArrayBuffer;
+    }
+  : {
+      read(): T;
+      write(value: T): void;
+      update(fn: (current: T) => T): T;
+      readonly key: string;
+      readonly buffer: SharedArrayBuffer;
+    };
+
+/**
+ * Per-worker read cache: key -> { version, value, index }.
+ *
+ * Each worker has its own cache (module-level, not shared). A read hits the
+ * cache when the key's version cell (in shared memory) matches the cached
+ * version. Writes bump the version cell, so any worker's cache is invalidated
+ * automatically on the next read. The key's stable index is cached too, so a
+ * cache hit avoids the linear index-table lookup.
+ */
+const readCache = new Map<
+  string,
+  { version: number; value: unknown; index: number }
+>();
+
+/**
+ * Per-worker cache of a key's stable index in the Index Table.
+ *
+ * Keys are never removed, so a key's index is stable for its lifetime. Once
+ * resolved, it can be cached forever, avoiding the linear index-table lookup
+ * (which decodes every stored key string) on every access.
+ */
+const indexCache = new Map<string, number>();
+
+/** Resolve a key's stable index, caching it after the first lookup. */
+function getIndex(mem: SharedMemory, key: string): number {
+  const cached = indexCache.get(key);
+  if (cached !== undefined) return cached;
+  const index = mem.lookupIndex(key);
+  if (index === null) {
+    throw new Error(`No shared value found for key "${key}"`);
+  }
+  indexCache.set(key, index);
+  return index;
+}
+
+/**
+ * Resolve a key's current DataTable offset using the cached stable index.
+ * The offset can change on GC/defragmentation, so it is re-read from the
+ * Index Table each time (a single Int32 read), but the expensive linear
+ * key-string scan is avoided. Returns null if the key is not present.
+ */
+function getOffset(mem: SharedMemory, key: string): number | null {
+  const cached = indexCache.get(key);
+  if (cached !== undefined) {
+    return mem.lookupByIndex(cached);
+  }
+  const index = mem.lookupIndex(key);
+  if (index === null) return null;
+  indexCache.set(key, index);
+  return mem.lookupByIndex(index);
+}
+
+/** Whether a decoded value is a reference-countable object/array. */
+function isTrackable(value: unknown): boolean {
+  return value !== null && typeof value === "object";
+}
+
+/**
+ * Get the stable objectId of a key's top-level value, or null if it is a
+ * primitive (which is stored inline and not reference-counted).
+ */
+function getTopLevelObjectId(mem: SharedMemory, key: string): number | null {
+  const offset = getOffset(mem, key);
+  if (offset === null) return null;
+  const type = mem.dataTable.getView().getInt32(offset, true);
+  if (type === 5) {
+    return mem.getObjectId(offset);
+  }
+  const slot = mem.readValueSlot(offset);
+  if (slot.type === TYPE_ARRAY_REF) {
+    return mem.getArrayObjectId(slot.a);
+  }
+  return null;
+}
+
+/**
+ * Per-worker cache of decoded object properties: key -> { version, props }.
+ *
+ * When a property of an object is read via the layout (single-slot decode),
+ * the decoded value is cached here keyed by the object's version. A hit avoids
+ * re-decoding the property (e.g. re-reading a string from the StringTable) on
+ * repeated reads of the same property. Writes bump the object's version, so
+ * the whole entry is invalidated automatically.
+ */
+const propCache = new Map<
+  string,
+  { version: number; index: number; props: Map<string, unknown> }
+>();
+
+/**
+ * Per-worker cache of object layouts: key -> stable property slot offsets.
+ *
+ * Because object properties may not be added or removed, the layout is static
+ * for the lifetime of the object. It is built once (under the lock) and cached
+ * so individual property reads can decode only the requested slot instead of
+ * the whole object. If a future GC/defragmentation moves an object block, this
+ * cache must be invalidated (e.g. via a layout version cell).
+ */
+const layoutCache = new Map<string, ObjectLayout | null>();
+
+/** Get (and cache) the stable layout of an object value, or null if not an object. */
+function getObjectLayout(mem: SharedMemory, key: string): ObjectLayout | null {
+  if (layoutCache.has(key)) return layoutCache.get(key)!;
+  const layout = mem.withLock(() => mem.getObjectLayout(key));
+  layoutCache.set(key, layout);
+  return layout;
+}
+
+/** Deep-ish copy of a decoded value, so callers can't corrupt the cache. */
+function copyValue(value: unknown): unknown {
+  if (Array.isArray(value)) return [...value];
+  if (value !== null && typeof value === "object") {
+    const copy: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      copy[k] = Array.isArray(v) ? [...v] : v;
+    }
+    return copy;
+  }
+  return value;
+}
+
+/** Options for creating a shared value. */
+export interface SharedOptions {
+  /** Initial size of each shared buffer in bytes. */
+  initialSize?: number;
+  /** Maximum size of each shared buffer in bytes. */
+  maxByteLength?: number;
+  /**
+   * An existing SharedMemory instance to use. When provided, the value is
+   * stored in (and read from) this shared memory, allowing multiple workers
+   * to access the same buffers.
+   */
+  memory?: SharedMemory;
+  /**
+   * A worker-side reference-count tracker. When provided, `read()` acquires a
+   * reference to the returned object/array, released when it is GC'd.
+   */
+  refCount?: RefCountTracker;
+  /**
+   * Initial capacity (in elements) reserved for arrays when they are first
+   * stored. Arrays are created with this many slots, so subsequent `push`
+   * calls can append in place without growing/moving the array until the
+   * capacity is exhausted. Defaults to the array's length.
+   */
+  arrayCapacity?: number;
+}
+
+type Loader<T> = () => T | Promise<T>;
+
+const registry = new Map<string, SharedRef<unknown>>();
+
+/**
+ * Get a wrapper to a named value in shared memory.
+ *
+ * If the value does not exist yet, it is created using the provided initial
+ * value or loader function (which may be async). If it already exists, the
+ * existing wrapper is returned and the initial value/loader is ignored.
+ *
+ * Returns a Promise when a loader is provided (since it may be async), and a
+ * SharedRef directly when an initial value is provided.
+ */
+export function Shared<T>(
+  key: string,
+  loader: Loader<T>,
+  options?: SharedOptions,
+): Promise<SharedRef<T>>;
+export function Shared<T>(
+  key: string,
+  initial: T,
+  options?: SharedOptions,
+): SharedRef<T>;
+export function Shared<T>(
+  key: string,
+  initialOrLoader: T | Loader<T>,
+  options: SharedOptions = {},
+): SharedRef<T> | Promise<SharedRef<T>> {
+  const existing = registry.get(key);
+  if (existing) return existing as SharedRef<T>;
+
+  const mem = options.memory ?? getDefaultMemory();
+  const ref = createSharedRef<T>(
+    mem,
+    key,
+    options.refCount ?? getDefaultTracker() ?? undefined,
+    options.arrayCapacity,
+  );
+  registry.set(key, ref as SharedRef<unknown>);
+
+  if (typeof initialOrLoader === "function") {
+    return Promise.resolve((initialOrLoader as Loader<T>)()).then((value) => {
+      ref.write(value);
+      return ref;
+    });
+  }
+
+  // If the key already exists in shared memory (e.g. it was created by the
+  // main thread and this is a worker sharing the same buffers), don't
+  // overwrite it with the initial value.
+  if (getOffset(mem, key) === null) {
+    ref.write(initialOrLoader as T);
+  }
+  return ref;
+}
+
+/** Create a SharedRef proxy backed by a SharedMemory instance. */
+function createSharedRef<T>(
+  mem: SharedMemory,
+  key: string,
+  tracker?: RefCountTracker,
+  arrayCapacity?: number,
+): SharedRef<T> {
+  const target = {
+    key,
+    mem,
+    // Fast-path cache: mirrors the module-level readCache entry for this key
+    // so the proxy get handler can read it without a Map lookup. Invalidated
+    // on every local write/update; cross-worker invalidation is detected by
+    // the version check in the get handler.
+    __cache: undefined as
+      { version: number; value: unknown; index: number } | undefined,
+    read: () => {
+      const value = copyValue(readValue(mem, key, target)) as T;
+      if (tracker && isTrackable(value)) {
+        const objectId = getTopLevelObjectId(mem, key);
+        if (objectId !== null) tracker.track(value as object, objectId);
+      }
+      return value;
+    },
+    write: (value: T) => {
+      target.__cache = undefined;
+      writeValue(mem, key, value, arrayCapacity);
+    },
+    update: (fn: (current: T) => T) => {
+      target.__cache = undefined;
+      return updateValue(mem, key, fn, arrayCapacity);
+    },
+  };
+
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === "read") return t.read;
+      if (prop === "write") return t.write;
+      if (prop === "update") return t.update;
+      if (prop === "key") return t.key;
+      if (prop === "buffer") return mem.dataTable.buffer;
+      if (prop === Symbol.toPrimitive) return () => t.read();
+
+      // push/pop on a top-level array: operate directly on the array ref
+      // without decoding the whole array (O(1) amortized).
+      if (prop === "push" || prop === "pop") {
+        const slotOffset = findArrayRefSlot(mem, key, null);
+        if (slotOffset !== null) {
+          return (...args: unknown[]) =>
+            mutateArrayRef(mem, key, null, prop, args);
+        }
+      }
+
+      // Fast path: if the full value is cached and valid, read the property
+      // from the cached value (no decode, no lock). The cache entry is kept
+      // directly on the target to avoid a Map lookup on the hot path.
+      const cached = t.__cache;
+      if (
+        cached !== undefined &&
+        cached.version === mem.getVersion(cached.index)
+      ) {
+        const cachedValue = cached.value;
+        if (Array.isArray(cachedValue)) {
+          return getTopLevelArrayMember(
+            mem,
+            key,
+            cachedValue,
+            prop,
+            arrayCapacity,
+          );
+        }
+        const propValue = (cachedValue as Record<string | symbol, unknown>)[
+          prop
+        ];
+        if (Array.isArray(propValue)) {
+          return createArrayProxy(mem, key, prop as string, arrayCapacity);
+        }
+        return propValue;
+      }
+
+      // Cache miss: for objects, decode only the requested property's slot via
+      // the cached layout, avoiding a full-object decode. The decoded value is
+      // cached per property so repeated reads of the same property are cheap.
+      const layout = getObjectLayout(mem, key);
+      if (layout !== null) {
+        const slotOffset = layout.properties.get(prop as string);
+        if (slotOffset === undefined) return undefined;
+
+        // Property cache hit: the object's version is unchanged.
+        const pc = propCache.get(key);
+        const version = pc !== undefined ? mem.getVersion(pc.index) : -1;
+        if (pc !== undefined && pc.version === version) {
+          const cachedProp = pc.props.get(prop as string);
+          if (cachedProp !== undefined) {
+            if (Array.isArray(cachedProp)) {
+              return createArrayProxy(mem, key, prop as string, arrayCapacity);
+            }
+            return cachedProp;
+          }
+        }
+
+        // Decode the single slot and cache it under the object's version.
+        // The key's index is stable (keys are never removed), so reuse the
+        // cached index when available to avoid the linear index-table lookup.
+        const index =
+          pc !== undefined
+            ? pc.index
+            : (readCache.get(key)?.index ?? getIndex(mem, key));
+        const slot = mem.readValueSlot(slotOffset);
+        // Array properties are handled lazily by the array proxy; don't decode
+        // the whole array here (avoids O(n) work on every access).
+        if (slot.type === TYPE_ARRAY_REF) {
+          return createArrayProxy(mem, key, prop as string, arrayCapacity);
+        }
+        const propValue = decodeValue(mem, slot);
+        if (pc === undefined || pc.version !== version) {
+          propCache.set(key, {
+            version: mem.getVersion(index),
+            index,
+            props: new Map(),
+          });
+        }
+        propCache.get(key)!.props.set(prop as string, propValue);
+        if (Array.isArray(propValue)) {
+          return createArrayProxy(mem, key, prop as string, arrayCapacity);
+        }
+        return propValue;
+      }
+
+      // Primitive/array key: use the cached value directly (no copy).
+      const value = readValue(mem, key, t);
+      if (Array.isArray(value)) {
+        return getTopLevelArrayMember(mem, key, value, prop, arrayCapacity);
+      }
+      // Object value: property access.
+      const propValue = (value as Record<string | symbol, unknown>)[prop];
+      if (Array.isArray(propValue)) {
+        return createArrayProxy(mem, key, prop as string, arrayCapacity);
+      }
+      return propValue;
+    },
+    set(t, prop, val) {
+      // In-place update: write only the affected slot instead of decoding and
+      // re-encoding the whole value.
+      t.__cache = undefined;
+      return mem.withLock(() => {
+        // Object property: use the cached layout to write only that slot.
+        const layout = getObjectLayout(mem, key);
+        if (layout !== null) {
+          const slotOffset = layout.properties.get(prop as string);
+          if (slotOffset === undefined) {
+            throw new TypeError(
+              `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
+            );
+          }
+          mem.updateValueSlot(slotOffset, encodeValue(mem, val));
+          bump(mem, key);
+          return true;
+        }
+
+        // Top-level array index write: update only that array slot.
+        const offset = getOffset(mem, key);
+        if (offset === null) {
+          throw new Error(`No shared value found for key "${key}"`);
+        }
+        const slot = mem.readValueSlot(offset);
+        if (
+          slot.type === TYPE_ARRAY_REF &&
+          typeof prop === "string" &&
+          /^\d+$/.test(prop)
+        ) {
+          const index = Number(prop);
+          const ref = { offset: slot.a, count: slot.b, capacity: slot.c };
+          if (index >= ref.count) {
+            throw new RangeError(
+              `Index ${index} out of bounds for array of length ${ref.count}`,
+            );
+          }
+          mem.updateArraySlot(ref, index, encodeValue(mem, val));
+          bump(mem, key);
+          return true;
+        }
+
+        // Top-level array length write: shrink/grow the array in place without
+        // re-encoding the whole array (which would leave a dead slot behind).
+        if (slot.type === TYPE_ARRAY_REF && prop === "length") {
+          const newLen = Number(val);
+          if (!Number.isInteger(newLen) || newLen < 0) {
+            throw new RangeError("Invalid array length");
+          }
+          const ref = { offset: slot.a, count: slot.b, capacity: slot.c };
+          if (newLen <= ref.capacity) {
+            // Shrinking (or growing within capacity): just update the count.
+            mem.updateValueSlot(
+              offset,
+              arrayRefSlot({
+                offset: ref.offset,
+                count: newLen,
+                capacity: ref.capacity,
+              }),
+            );
+            bump(mem, key);
+            return true;
+          }
+          // Growing beyond capacity falls through to the full read-modify-write.
+        }
+
+        // Fallback: full read-modify-write (e.g. setting a primitive key's
+        // property, or a non-index property on an array).
+        return mutateValue<T, boolean>(
+          mem,
+          key,
+          (value) => {
+            if (Array.isArray(value)) {
+              (value as unknown as Record<string | symbol, unknown>)[prop] =
+                val;
+            } else {
+              (value as Record<string | symbol, unknown>)[prop] = val;
+            }
+            return true;
+          },
+          arrayCapacity,
+        );
+      });
+    },
+    deleteProperty() {
+      throw new TypeError(
+        "Shared values have a fixed shape: properties may not be added or removed",
+      );
+    },
+  }) as unknown as SharedRef<T>;
+}
+
+/**
+ * Read the full value for a key from shared memory, using the read cache.
+ *
+ * When `cacheTarget` is provided (the proxy target), the cache entry is also
+ * mirrored onto `cacheTarget.__cache` so the proxy get handler can read it
+ * without a Map lookup on the hot path.
+ */
+function readValue(
+  mem: SharedMemory,
+  key: string,
+  cacheTarget?: {
+    __cache?: { version: number; value: unknown; index: number };
+  },
+): unknown {
+  const cached = readCache.get(key);
+  const index = cached !== undefined ? cached.index : getIndex(mem, key);
+
+  // Lock-free fast path: if the cached version matches the current version
+  // cell, the cached value is still valid.
+  const version = mem.getVersion(index);
+  if (cached !== undefined && cached.version === version) {
+    return cached.value;
+  }
+
+  // Cache miss: decode under the lock and cache with the observed version.
+  const value = mem.withLock(() => {
+    const offset = getOffset(mem, key);
+    if (offset === null) {
+      throw new Error(`No shared value found for key "${key}"`);
+    }
+    const type = mem.dataTable.getView().getInt32(offset, true);
+    if (type === 5) {
+      // Object block.
+      const properties = mem.readObject(offset);
+      const obj: Record<string, unknown> = {};
+      for (const [name, slot] of properties) {
+        obj[name] = decodeValue(mem, slot);
+      }
+      return obj;
+    }
+    // Single value slot (primitive or array).
+    return decodeValue(mem, mem.readValueSlot(offset));
+  });
+
+  const entry = { version, value, index };
+  readCache.set(key, entry);
+  if (cacheTarget) cacheTarget.__cache = entry;
+  return value;
+}
+
+/** Write a full value for a key to shared memory. */
+function writeValue(
+  mem: SharedMemory,
+  key: string,
+  value: unknown,
+  arrayCapacity?: number,
+): void {
+  mem.withLock(() => {
+    const existing = getOffset(mem, key);
+    if (existing !== null) {
+      const type = mem.dataTable.getView().getInt32(existing, true);
+      if (type === 5) {
+        // Update existing object's property slots in place.
+        const properties = mem.readObject(existing);
+        const valueObj = value as Record<string, unknown>;
+        for (let i = 0; i < properties.length; i++) {
+          const [name] = properties[i]!;
+          if (!(name in valueObj)) {
+            throw new TypeError(
+              `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
+            );
+          }
+          mem.updateObjectSlot(
+            existing,
+            i,
+            encodeValue(mem, valueObj[name], arrayCapacity),
+          );
+        }
+        // Check for extra properties.
+        const existingNames = new Set(properties.map(([n]) => n));
+        for (const name of Object.keys(valueObj)) {
+          if (!existingNames.has(name)) {
+            throw new TypeError(
+              `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
+            );
+          }
+        }
+        bump(mem, key);
+        return;
+      }
+      // Update a single value slot in place.
+      mem.updateValueSlot(existing, encodeValue(mem, value, arrayCapacity));
+      bump(mem, key);
+      return;
+    }
+
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      // Create a new object.
+      const valueObj = value as Record<string, unknown>;
+      const props: Array<[string, ValueSlot]> = Object.entries(valueObj).map(
+        ([name, v]) => [name, encodeValue(mem, v, arrayCapacity)],
+      );
+      const offset = mem.createObject(props);
+      mem.insert(key, offset);
+      return;
+    }
+
+    // Create a single value slot (primitive or array).
+    const offset = mem.storeValueSlot(encodeValue(mem, value, arrayCapacity));
+    mem.insert(key, offset);
+  });
+}
+
+/** Bump the version cell for a key, invalidating read caches. */
+function bump(mem: SharedMemory, key: string): void {
+  mem.bumpVersion(getIndex(mem, key));
+}
+
+/** Atomically update the value for a key. */
+function updateValue<T>(
+  mem: SharedMemory,
+  key: string,
+  fn: (current: T) => T,
+  arrayCapacity?: number,
+): T {
+  return mem.withLock(() => {
+    const current = readValue(mem, key) as T;
+    const next = fn(current);
+    writeValue(mem, key, next, arrayCapacity);
+    return next;
+  });
+}
+
+/**
+ * Atomically read-modify-write a value under a single lock acquisition.
+ * Unlike `updateValue`, the transform may return a different value than the
+ * one written (e.g. array methods return the popped element).
+ */
+function mutateValue<T, R>(
+  mem: SharedMemory,
+  key: string,
+  fn: (current: T) => R,
+  arrayCapacity?: number,
+): R {
+  return mem.withLock(() => {
+    const current = readValue(mem, key) as T;
+    const result = fn(current);
+    writeValue(mem, key, current, arrayCapacity);
+    return result;
+  });
+}
+
+/**
+ * Find the DataTable offset of the array-ref slot for a key's array.
+ *
+ * `prop` is null for a top-level array value, or the property name for an
+ * array property of an object. Returns null if the value is not an array.
+ */
+function findArrayRefSlot(
+  mem: SharedMemory,
+  key: string,
+  prop: string | null,
+): number | null {
+  if (prop === null) {
+    const offset = getOffset(mem, key);
+    if (offset === null) return null;
+    const slot = mem.readValueSlot(offset);
+    return slot.type === TYPE_ARRAY_REF ? offset : null;
+  }
+  const layout = getObjectLayout(mem, key);
+  if (layout === null) return null;
+  const slotOffset = layout.properties.get(prop);
+  if (slotOffset === undefined) return null;
+  const slot = mem.readValueSlot(slotOffset);
+  return slot.type === TYPE_ARRAY_REF ? slotOffset : null;
+}
+
+/**
+ * O(1) in-place push/pop on a shared array ref, without decoding or
+ * re-encoding the whole array. `prop` is null for a top-level array, or the
+ * property name for an array property of an object.
+ */
+function mutateArrayRef(
+  mem: SharedMemory,
+  key: string,
+  prop: string | null,
+  method: "push" | "pop",
+  args: unknown[],
+): unknown {
+  return mem.withLock(() => {
+    const slotOffset = findArrayRefSlot(mem, key, prop);
+    if (slotOffset === null) {
+      throw new TypeError("Value is not an array");
+    }
+    const slot = mem.readValueSlot(slotOffset);
+    const ref: ArrayRef = { offset: slot.a, count: slot.b, capacity: slot.c };
+
+    if (method === "push") {
+      for (const arg of args) {
+        const next = mem.appendArraySlot(ref, encodeValue(mem, arg));
+        // Always persist the new count (and offset/capacity if moved).
+        mem.updateValueSlot(slotOffset, arrayRefSlot(next));
+        ref.offset = next.offset;
+        ref.count = next.count;
+        ref.capacity = next.capacity;
+      }
+      bump(mem, key);
+      return ref.count;
+    }
+
+    // pop
+    if (ref.count === 0) {
+      return undefined;
+    }
+    // Read the last element before decrementing.
+    const lastSlot = mem.readArraySlot(ref, ref.count - 1);
+    const result = decodeValue(mem, lastSlot);
+    const next = {
+      offset: ref.offset,
+      count: ref.count - 1,
+      capacity: ref.capacity,
+    };
+    mem.updateValueSlot(slotOffset, arrayRefSlot(next));
+    bump(mem, key);
+    return result;
+  });
+}
+
+/** Get a member of a top-level array value, with read-modify-write for mutating methods. */
+function getTopLevelArrayMember(
+  mem: SharedMemory,
+  key: string,
+  value: unknown[],
+  prop: string | symbol,
+  arrayCapacity?: number,
+): unknown {
+  if (prop === "length") return value.length;
+  if (typeof prop === "string" && /^\d+$/.test(prop)) {
+    return value[Number(prop)];
+  }
+  if (typeof prop === "symbol") {
+    if (prop === Symbol.iterator) return value[Symbol.iterator].bind(value);
+    return (value as unknown as Record<symbol, unknown>)[prop];
+  }
+  if (MUTATING_METHODS.has(prop)) {
+    const methodName = prop;
+    // push/pop are O(1) in-place operations on the array ref.
+    if (methodName === "push" || methodName === "pop") {
+      return (...args: unknown[]) => {
+        return mutateArrayRef(mem, key, null, methodName, args);
+      };
+    }
+    return (...args: unknown[]) => {
+      return mutateValue<unknown[], unknown>(
+        mem,
+        key,
+        (fresh) => {
+          const method = (
+            fresh as unknown as Record<string, (...a: unknown[]) => unknown>
+          )[methodName]!;
+          return method.apply(fresh, args);
+        },
+        arrayCapacity,
+      );
+    };
+  }
+  const method = (value as unknown as Record<string, unknown>)[prop];
+  if (typeof method === "function") return method.bind(value);
+  return method;
+}
+
+/** Create a proxy for an array property of a shared object. */
+function createArrayProxy(
+  mem: SharedMemory,
+  key: string,
+  prop: string,
+  arrayCapacity?: number,
+): unknown[] {
+  return new Proxy([] as unknown[], {
+    get(_target, arrProp) {
+      // push/pop on an array property: operate directly on the array ref
+      // without decoding the whole object (O(1) amortized).
+      if (arrProp === "push" || arrProp === "pop") {
+        const slotOffset = findArrayRefSlot(mem, key, prop);
+        if (slotOffset !== null) {
+          return (...args: unknown[]) =>
+            mutateArrayRef(mem, key, prop, arrProp, args);
+        }
+      }
+      const current = readValue(mem, key) as Record<string, unknown>;
+      const arr = current[prop] as unknown[];
+      if (!Array.isArray(arr)) {
+        throw new TypeError(`Property "${prop}" is not an array`);
+      }
+      if (arrProp === "length") return arr.length;
+      if (typeof arrProp === "string" && /^\d+$/.test(arrProp)) {
+        return arr[Number(arrProp)];
+      }
+      if (typeof arrProp === "symbol") {
+        if (arrProp === Symbol.iterator) return arr[Symbol.iterator].bind(arr);
+        return (arr as unknown as Record<symbol, unknown>)[arrProp];
+      }
+      if (MUTATING_METHODS.has(arrProp)) {
+        const methodName = arrProp;
+        // push/pop are O(1) in-place operations on the array ref.
+        if (methodName === "push" || methodName === "pop") {
+          return (...args: unknown[]) => {
+            return mutateArrayRef(mem, key, prop, methodName, args);
+          };
+        }
+        return (...args: unknown[]) => {
+          return mutateValue<Record<string, unknown>, unknown>(
+            mem,
+            key,
+            (fresh) => {
+              const freshArr = fresh[prop] as unknown[];
+              const method = (
+                freshArr as unknown as Record<
+                  string,
+                  (...a: unknown[]) => unknown
+                >
+              )[methodName]!;
+              return method.apply(freshArr, args);
+            },
+            arrayCapacity,
+          );
+        };
+      }
+      const method = (arr as unknown as Record<string, unknown>)[arrProp];
+      if (typeof method === "function") return method.bind(arr);
+      return method;
+    },
+    set(_target, arrProp, val) {
+      // In-place update: write only the affected array slot instead of
+      // decoding and re-encoding the whole object.
+      return mem.withLock(() => {
+        const layout = getObjectLayout(mem, key);
+        if (layout !== null) {
+          const slotOffset = layout.properties.get(prop);
+          if (slotOffset !== undefined) {
+            const propSlot = mem.readValueSlot(slotOffset);
+            if (
+              propSlot.type === TYPE_ARRAY_REF &&
+              typeof arrProp === "string" &&
+              /^\d+$/.test(arrProp)
+            ) {
+              const index = Number(arrProp);
+              const ref = {
+                offset: propSlot.a,
+                count: propSlot.b,
+                capacity: propSlot.c,
+              };
+              if (index >= ref.count) {
+                throw new RangeError(
+                  `Index ${index} out of bounds for array of length ${ref.count}`,
+                );
+              }
+              mem.updateArraySlot(ref, index, encodeValue(mem, val));
+              bump(mem, key);
+              return true;
+            }
+            // Array property length write: shrink/grow in place without
+            // re-encoding the whole object (which would leave a dead slot).
+            if (propSlot.type === TYPE_ARRAY_REF && arrProp === "length") {
+              const newLen = Number(val);
+              if (!Number.isInteger(newLen) || newLen < 0) {
+                throw new RangeError("Invalid array length");
+              }
+              const ref = {
+                offset: propSlot.a,
+                count: propSlot.b,
+                capacity: propSlot.c,
+              };
+              if (newLen <= ref.capacity) {
+                mem.updateValueSlot(
+                  slotOffset,
+                  arrayRefSlot({
+                    offset: ref.offset,
+                    count: newLen,
+                    capacity: ref.capacity,
+                  }),
+                );
+                bump(mem, key);
+                return true;
+              }
+              // Growing beyond capacity falls through to the full read-modify-write.
+            }
+          }
+        }
+        // Fallback: full read-modify-write.
+        return mutateValue<Record<string, unknown>, boolean>(
+          mem,
+          key,
+          (fresh) => {
+            const arr = fresh[prop] as unknown[];
+            (arr as unknown as Record<string | symbol, unknown>)[arrProp] = val;
+            return true;
+          },
+          arrayCapacity,
+        );
+      });
+    },
+  });
+}