@woosh/meep-engine 3.14.6 → 3.15.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.14.6",
+  "version": "3.15.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/engine/network/orchestrator/ServerAuthoritativeClient.d.ts

@@ -18,6 +18,19 @@
  *    {@link onReplay} handler re-executes the same SimActions the original
  *    predict path produced.
  *
+ *  - A replay also reapplies the records in the rewound window that ARRIVED
+ *    from a peer, which {@link onReplay} cannot: it re-executes this client's
+ *    own input, and the AUTH_STATE that precedes it carries one `network_id`.
+ *    Without this step a rewind about one entity discards the owner's published
+ *    state for every OTHER entity in the window — permanently, for anything
+ *    published on change rather than every frame, because nothing re-sends it
+ *    and nothing else restores it. This is the client half of the rule
+ *    `SimAction` states and `ServerAuthoritativeServer.#read_historical`
+ *    implements: a record's `sender_id` says whether it arrived, was authored,
+ *    or was derived, and a replay reapplies the first two and recomputes the
+ *    third. Here the authored half is `onReplay`'s job and the arrived half is
+ *    this one's.
+ *
  *  - A no-op short-circuit is built in: before doing the rewind+replay, the
  *    orchestrator gives the user a chance to compute what the replay WOULD
  *    produce via {@link onComputeExpected}; if that matches the current
@@ -75,6 +88,20 @@ export class ServerAuthoritativeClient {
     reconcile_count: number;
     /** @type {number} */
     replay_frame_count: number;
+    /**
+     * Records that arrived from a peer and were reapplied by a replay, over the
+     * life of this client. Zero on a client whose peers publish nothing the
+     * rewind window covers; non-zero is the fix for the discard above doing
+     * work, and is what a test can assert on rather than inferring from a value.
+     * @type {number}
+     */
+    replayed_arrived_count: number;
+    /**
+     * Reconciliations abandoned because the action log no longer held the frames
+     * the rewind needed. See {@link onReconcileAbandoned}.
+     * @type {number}
+     */
+    reconcile_abandoned_count: number;
     /** @type {NetworkPeer} */
     peer: NetworkPeer;
     /** @type {EntityComponentDataset} */
@@ -199,6 +226,26 @@ export class ServerAuthoritativeClient {
      * @type {Signal}
      */
     onReconcileComplete: Signal;
+    /**
+     * Fires when a reconciliation is abandoned because the action log no
+     * longer holds the frames its rewind needed. Args:
+     * `(server_frame, network_id)`.
+     *
+     * This is a real loss of replicated state and not a hiccup: state a peer
+     * does not own reaches it on the action stream, and an owner that
+     * publishes on change never sends it again — so whatever that window
+     * carried for every entity other than `network_id` is gone. The server
+     * would normally back-fill via `RECOVERY_REQUEST`/`STATE_BURST`, which
+     * is request-driven, so something has to know to ask. That is what this
+     * signal is for; {@link reconcile_abandoned_count} is the same event as
+     * a counter.
+     *
+     * A client seeing this repeatedly is running further ahead of the server
+     * frame than its `frame_capacity` covers.
+     *
+     * @type {Signal}
+     */
+    onReconcileAbandoned: Signal;
     /**
      * Connect to a server peer over a transport.
      * @param {number} peer_id
@@ -262,4 +309,5 @@ import { InputRing } from "../state/InputRing.js";
 import { RewindEngine } from "../sim/RewindEngine.js";
 import { TimeDilation } from "../time/TimeDilation.js";
 import Signal from "../../../core/events/signal/Signal.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 //# sourceMappingURL=ServerAuthoritativeClient.d.ts.map

package/src/engine/network/orchestrator/ServerAuthoritativeClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerAuthoritativeClient.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeClient.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAsBI;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,iOAxBW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,eAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,iBAAqB,CAAC,EAAE,MAAM,CAAC;QAC/B,aAAiB,CAAC,EAAE,YAAY,CAAC;QACjC,oBAAwB,CAAC,EAAE,MAAM,CAAC;KAC/B,EA6LH;IAjND,qBAAqB;IACrB,iBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,oBADW,MAAM,CACM;IAyCnB,0BAA0B;IAC1B,MADW,WAAW,CAUpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAClC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAEhD;;;;OAIG;IACH,YAFU,SAAS,CAKjB;IAEF,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;OAKG;IACH,mBAFU,MAAM,CAE0B;IAE1C;;;;;OAKG;IACH,eAFU,YAAY,CAEY;IAElC;;;;OAIG;IACH,mBAFU,MAAM,CAEW;IAE3B;;;;;;;;OAQG;IACH,iBAFU,MAAM,CAEU;IAO1B;;;;;;;;;OASG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;;;;;;OASG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,kBAFU,MAAM,CAEoB;IAEpC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;;OAQG;IACH,kBAFU,MAAM,CAEoB;IAEpC;;;;OAIG;IACH,qBAFU,MAAM,CAEuB;IAQ3C;;;;OAIG;IACH,2BAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,gCAFW,MAAM,QAIhB;IAED;iCAC6B;IAC7B,qBADW,MAAM,6CAGhB;IAED;;;;;;;;;;OAUG;IACH,oBAFW,MAAM,QAahB;IAED;;;;;;;OAOG;IACH,qBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,iBAHW,MAAM,gBAKhB;IAiFD;;;;;OAKG;IACH,oBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,oBAFW,MAAM,QAIhB;;CACJ;4BA7a2B,kBAAkB;0BAFpB,uBAAuB;6BADpB,wBAAwB;6BAExB,yBAAyB;mBAJnC,uCAAuC"}
+{"version":3,"file":"ServerAuthoritativeClient.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeClient.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IA8DI;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,iOAxBW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,eAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,iBAAqB,CAAC,EAAE,MAAM,CAAC;QAC/B,aAAiB,CAAC,EAAE,YAAY,CAAC;QACjC,oBAAwB,CAAC,EAAE,MAAM,CAAC;KAC/B,EAqNH;IAzPD,qBAAqB;IACrB,iBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,oBADW,MAAM,CACM;IAEvB;;;;;;OAMG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;;OAIG;IACH,2BAFU,MAAM,CAEc;IAyC1B,0BAA0B;IAC1B,MADW,WAAW,CAUpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAClC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAEhD;;;;OAIG;IACH,YAFU,SAAS,CAKjB;IAEF,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;OAKG;IACH,mBAFU,MAAM,CAE0B;IAE1C;;;;;OAKG;IACH,eAFU,YAAY,CAEY;IAElC;;;;OAIG;IACH,mBAFU,MAAM,CAEW;IAE3B;;;;;;;;OAQG;IACH,iBAFU,MAAM,CAEU;IAO1B;;;;;;;;;OASG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;;;;;;OASG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,kBAFU,MAAM,CAEoB;IAEpC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;;OAQG;IACH,kBAFU,MAAM,CAEoB;IAEpC;;;;OAIG;IACH,qBAFU,MAAM,CAEuB;IAEvC;;;;;;;;;;;;;;;;;;OAkBG;IACH,sBAFU,MAAM,CAEwB;IAW5C;;;;OAIG;IACH,2BAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,gCAFW,MAAM,QAIhB;IAED;iCAC6B;IAC7B,qBADW,MAAM,6CAGhB;IAED;;;;;;;;;;OAUG;IACH,oBAFW,MAAM,QAahB;IAED;;;;;;;OAOG;IACH,qBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,iBAHW,MAAM,GACJ,YAAY,CAIxB;IA6OD;;;;;OAKG;IACH,oBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,oBAFW,MAAM,QAIhB;;CACJ;4BA9pB2B,kBAAkB;0BAFpB,uBAAuB;6BADpB,wBAAwB;6BAExB,yBAAyB;mBALnC,uCAAuC;6BAF7B,sCAAsC"}

package/src/engine/network/orchestrator/ServerAuthoritativeClient.js

@@ -1,12 +1,22 @@
 import { assert } from "../../../core/assert.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import { Uint32Map } from "../../../core/collection/Uint32Map.js";
 import Signal from "../../../core/events/signal/Signal.js";
 import { AlwaysRelevantScope } from "../replication/ScopeFilter.js";
+import { ActionRecordCursor } from "../sim/ActionRecordCursor.js";
 import { RewindEngine } from "../sim/RewindEngine.js";
 import { InputRing } from "../state/InputRing.js";
 import { TimeDilation } from "../time/TimeDilation.js";
 import { NetworkPeer } from "./NetworkPeer.js";
 
+/**
+ * Ints per harvested record in {@link ServerAuthoritativeClient}'s replay index:
+ * action type id, sender id, and the offset of its payload.
+ *
+ * @type {number}
+ */
+const HARVEST_STRIDE = 3;
+
 /**
  * Client-side orchestrator for the predict-reconcile model.
  *
@@ -27,6 +37,19 @@ import { NetworkPeer } from "./NetworkPeer.js";
  *    {@link onReplay} handler re-executes the same SimActions the original
  *    predict path produced.
  *
+ *  - A replay also reapplies the records in the rewound window that ARRIVED
+ *    from a peer, which {@link onReplay} cannot: it re-executes this client's
+ *    own input, and the AUTH_STATE that precedes it carries one `network_id`.
+ *    Without this step a rewind about one entity discards the owner's published
+ *    state for every OTHER entity in the window — permanently, for anything
+ *    published on change rather than every frame, because nothing re-sends it
+ *    and nothing else restores it. This is the client half of the rule
+ *    `SimAction` states and `ServerAuthoritativeServer.#read_historical`
+ *    implements: a record's `sender_id` says whether it arrived, was authored,
+ *    or was derived, and a replay reapplies the first two and recomputes the
+ *    third. Here the authored half is `onReplay`'s job and the arrived half is
+ *    this one's.
+ *
  *  - A no-op short-circuit is built in: before doing the rewind+replay, the
  *    orchestrator gives the user a chance to compute what the replay WOULD
  *    produce via {@link onComputeExpected}; if that matches the current
@@ -55,6 +78,30 @@ export class ServerAuthoritativeClient {
     #expected_scratch;
     #measured_scratch;
 
+    /**
+     * Records of one log frame that arrived from a peer, indexed
+     * {@link HARVEST_STRIDE} ints apiece into {@link #harvest_payloads}. Filled
+     * by {@link #harvest_arrived} before the frame is reopened and drained by
+     * {@link #execute_harvested} once it is.
+     * @type {Int32Array}
+     */
+    #harvest_index = new Int32Array(HARVEST_STRIDE * 32);
+
+    /** @type {number} records currently described by {@link #harvest_index} */
+    #harvest_count = 0;
+
+    /**
+     * The harvested records' action payloads, back to back. A frame's bytes have
+     * to be copied out before the frame is reopened: opening it rewinds its
+     * buffer to zero and the re-execution then writes over exactly the bytes
+     * being read.
+     * @type {BinaryBuffer}
+     */
+    #harvest_payloads = new BinaryBuffer();
+
+    /** @type {ActionRecordCursor} */
+    #harvest_cursor = new ActionRecordCursor();
+
     // Counters
     /** @type {number} */
     reconcile_count = 0;
@@ -62,6 +109,22 @@ export class ServerAuthoritativeClient {
     /** @type {number} */
     replay_frame_count = 0;
 
+    /**
+     * Records that arrived from a peer and were reapplied by a replay, over the
+     * life of this client. Zero on a client whose peers publish nothing the
+     * rewind window covers; non-zero is the fix for the discard above doing
+     * work, and is what a test can assert on rather than inferring from a value.
+     * @type {number}
+     */
+    replayed_arrived_count = 0;
+
+    /**
+     * Reconciliations abandoned because the action log no longer held the frames
+     * the rewind needed. See {@link onReconcileAbandoned}.
+     * @type {number}
+     */
+    reconcile_abandoned_count = 0;
+
     /**
      * @param {{
      *   world: EntityComponentDataset,
@@ -261,6 +324,30 @@ export class ServerAuthoritativeClient {
          */
         this.onReconcileComplete = new Signal();
 
+        /**
+         * Fires when a reconciliation is abandoned because the action log no
+         * longer holds the frames its rewind needed. Args:
+         * `(server_frame, network_id)`.
+         *
+         * This is a real loss of replicated state and not a hiccup: state a peer
+         * does not own reaches it on the action stream, and an owner that
+         * publishes on change never sends it again — so whatever that window
+         * carried for every entity other than `network_id` is gone. The server
+         * would normally back-fill via `RECOVERY_REQUEST`/`STATE_BURST`, which
+         * is request-driven, so something has to know to ask. That is what this
+         * signal is for; {@link reconcile_abandoned_count} is the same event as
+         * a counter.
+         *
+         * A client seeing this repeatedly is running further ahead of the server
+         * frame than its `frame_capacity` covers.
+         *
+         * @type {Signal}
+         */
+        this.onReconcileAbandoned = new Signal();
+
+        // One packet's worth of action payloads, grown on demand from there.
+        this.#harvest_payloads.setCapacity(1024);
+
         // Wire the AUTH_STATE handler to the algorithm above.
         this.peer.onAuthState.add((_peer_id, server_frame, network_id, buffer) => {
             this.#handle_auth_state(server_frame, network_id, buffer);
@@ -379,17 +466,51 @@ export class ServerAuthoritativeClient {
 
         // Real divergence: rewind, apply server's bytes, replay forward.
         const rewind_target = server_frame - 1;
+        let rewound = false;
         if (this.#current_frame > rewind_target) {
             try {
                 this.rewind_engine.rewind_to(this.#current_frame, rewind_target);
+                rewound = true;
             } catch (e) {
-                // The action_log probably rolled past server_frame. The
-                // server would normally back-fill us via STATE_BURST; for now
-                // skip this reconciliation.
+                /*
+                 The action_log rolled past server_frame, so the window this
+                 reconciliation needs no longer exists and skipping it is the
+                 only option left. Counted and announced rather than swallowed:
+                 what the window carried for every entity other than this one is
+                 gone for good, and an application that cannot see that happen
+                 cannot ask for the back-fill that would repair it.
+                */
+                this.reconcile_abandoned_count++;
+                this.onReconcileAbandoned.send2(server_frame, network_id);
                 return;
             }
         }
 
+        /*
+         Frame `server_frame` was just undone and is NOT replayed below: the
+         AUTH_STATE is the server's state at the END of it, so re-running this
+         client's own input for that frame would apply that input twice.
+
+         Its ARRIVED records are the other half of the frame, and the half that
+         was being dropped. The bytes below repair one `network_id`; every other
+         entity the frame touched has nothing else to restore it. They go back in
+         BEFORE those bytes, so the authoritative value still wins wherever the
+         two describe the same component.
+
+         In the ordinary owner-scoped arrangement this is the frame that matters
+         most: the owner's records for a frame land in the log at the owner's
+         frame number, which is at or below `server_frame`, so they sit at the
+         very bottom of the rewound window rather than inside the replay range.
+        */
+        if (rewound && this.#harvest_arrived(server_frame) > 0) {
+            this.action_log.begin_frame(server_frame);
+            try {
+                this.#execute_harvested();
+            } finally {
+                this.action_log.end_frame();
+            }
+        }
+
         // Apply the server's authoritative state bytes. The handler does the
         // adapter-specific deserialize.
         this.onApplyAuthState.send3(server_frame, network_id, buffer);
@@ -397,6 +518,10 @@ export class ServerAuthoritativeClient {
         // Replay forward from (server_frame + 1) through current_frame.
         let replay_count = 0;
         for (let f = server_frame + 1; f <= this.#current_frame; f++) {
+            // Harvested before `begin_frame`, which rewinds the frame's buffer
+            // over the bytes being read. Nothing to harvest if nothing was undone.
+            const arrived = rewound ? this.#harvest_arrived(f) : 0;
+
             this.action_log.begin_frame(f);
             try {
                 let input_reader = null;
@@ -405,6 +530,15 @@ export class ServerAuthoritativeClient {
                     input_reader.position = 0;
                 }
                 this.onReplay.send2(f, input_reader);
+
+                /*
+                 After the local input, which is the order the frame was written
+                 in the first time: this client's prediction was logged as it
+                 ticked the frame, and the owner's mutations for that frame
+                 arrived later. It also leaves the owner's value last, which is
+                 the one that should win where both touch a component.
+                */
+                if (arrived > 0) this.#execute_harvested();
             } finally {
                 this.action_log.end_frame();
             }
@@ -416,6 +550,115 @@ export class ServerAuthoritativeClient {
         this.onReconcileComplete.send2(server_frame, replay_count);
     }
 
+    /**
+     * Copy the records of `frame` that arrived from a peer out of the action
+     * log, ready for {@link #execute_harvested} to put back.
+     *
+     * MUST be called before `action_log.begin_frame(frame)`. Opening a frame
+     * rewinds its buffer to zero without clearing it, and the re-execution
+     * writes over exactly the bytes this reads, so the payloads are copied into
+     * {@link #harvest_payloads} rather than read in place.
+     *
+     * Provenance decides what a replay does with a record, and this client keeps
+     * a narrower set than the server does:
+     *
+     *  - a CONNECTED peer's id — it arrived from that peer, and nothing else
+     *    here reproduces it. `onApplyAuthState` covers one `network_id` and
+     *    {@link onReplay} covers this client's own input. Kept.
+     *  - `SENDER_DERIVED` — output a replay recomputes. Skipped, same as
+     *    `ServerAuthoritativeServer.#read_historical` skips it.
+     *  - `SENDER_LOCAL`, and this client's own peer id — its own input, which
+     *    {@link onReplay} reapplies from the sampled-action ledger. Skipped:
+     *    reapplying it from the log as well would apply it twice.
+     *
+     * Connectedness is the test rather than a comparison against the local peer
+     * id because it is the same question stated directly — the sender byte of an
+     * arrived record is the peer it arrived from, and a client never connects to
+     * itself, so its own records can never match.
+     *
+     * @param {number} frame
+     * @returns {number} how many records were harvested
+     * @private
+     */
+    #harvest_arrived(frame) {
+        this.#harvest_count = 0;
+        this.#harvest_payloads.position = 0;
+
+        if (!this.action_log.has_frame(frame)) return 0;
+
+        const cursor = this.#harvest_cursor;
+        cursor.open(this.action_log, frame);
+        const bytes = cursor.buffer.raw_bytes;
+
+        while (cursor.next()) {
+            if (!this.peer.is_connected(cursor.sender_id)) continue;
+
+            if ((this.#harvest_count + 1) * HARVEST_STRIDE > this.#harvest_index.length) {
+                this.#grow_harvest_index();
+            }
+
+            const i = this.#harvest_count * HARVEST_STRIDE;
+            this.#harvest_index[i] = cursor.action_type_id;
+            this.#harvest_index[i + 1] = cursor.sender_id;
+            this.#harvest_index[i + 2] = this.#harvest_payloads.position;
+            this.#harvest_count++;
+
+            this.#harvest_payloads.writeBytes(bytes, cursor.payload_start, cursor.payload_len);
+        }
+
+        return this.#harvest_count;
+    }
+
+    /**
+     * Re-execute what {@link #harvest_arrived} took, in log order, into the
+     * currently-open frame.
+     *
+     * Going back through the executor is the point rather than an implementation
+     * detail: it captures each record's prior bytes again as it applies, so the
+     * reopened frame describes what is now live and the next rewind can undo it.
+     * A record whose action class is no longer registered is skipped — the same
+     * thing `Replicator.#apply_groups` does on the way in.
+     *
+     * @private
+     */
+    #execute_harvested() {
+        const payloads = this.#harvest_payloads;
+
+        for (let record = 0; record < this.#harvest_count; record++) {
+            const i = record * HARVEST_STRIDE;
+            const type_id = this.#harvest_index[i];
+            const sender_id = this.#harvest_index[i + 1];
+            const payload_start = this.#harvest_index[i + 2];
+
+            const klass = this.action_registry.klass_for(type_id);
+            if (klass === undefined) continue;
+
+            const action = this.action_registry.acquire(klass);
+            try {
+                payloads.position = payload_start;
+                action.deserialize(payloads);
+                // `execute` returns false when an authorization policy rejects
+                // the action, in which case nothing was applied or logged — so
+                // the counter follows the return value rather than the attempt.
+                if (this.executor.execute(action, sender_id)) {
+                    this.replayed_arrived_count++;
+                }
+            } finally {
+                this.action_registry.release(action);
+            }
+        }
+    }
+
+    /**
+     * @private
+     */
+    #grow_harvest_index() {
+        const old = this.#harvest_index;
+        const next = new Int32Array(old.length * 2);
+        next.set(old);
+        this.#harvest_index = next;
+    }
+
     /**
      * Helper for the {@link onComputeExpected} handler: stash the
      * computed scalar so the orchestrator can read it. Called inside the