@adobe/ecs 0.1.0 → 0.2.1

package/dist/implementation/world/index-hash.js

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { allocateArray, freeArray } from './arrays.js';
 /** Words an entry takes: its entity index, its archetype's id and its row. */
 export const entryWords = 3;
@@ -9,9 +10,13 @@ export const recordCapacity = 3;
 export const recordKey = 4;
 /** A freed bucket's capacity. */
 const freedCapacity = 0xFFFFFFFF;
+/** Whether a view is the world's table itself, whose unsorted buckets a list sorts before reading them by position. */
+export const isHashTable = (view) => "tails" in view;
 const minimumSlots = 16;
 /** Slots the table keeps for each bucket at least: it's at most half full. */
 const slotsPerBucket = 2;
+/** Entries a bucket holds at least before a change may leave it unsorted; a shorter one shifts its entries. */
+export const unsortedMinimum = 64;
 /** Whether `slots` slots hold `buckets` buckets. */
 export const slotsHold = (slots, buckets) => slotsPerBucket * buckets + 2 <= slots;
 export const createHashTable = (memory, words) => ({
@@ -31,6 +36,18 @@ export const createHashTable = (memory, words) => ({
     bucketOf: allocateArray(memory, Int32Array, 64).fill(-1),
     size: 0,
     watched: new Map(),
+    unsorted: 0,
+    unsortedBuckets: new Int32Array(8),
+    unsortedListed: 0,
+    listed: new Uint8Array(8),
+    tails: new Int32Array(8).fill(-1),
+    extents: new Int32Array(8),
+    holes: new Int32Array(8),
+    positionOf: new Int32Array(64),
+    spare: new Int32Array(0),
+    wide: new Float64Array(0),
+    scratch: new Float64Array(0),
+    scratchWords: new Int32Array(0),
 });
 /** Frees every array, once nothing reads the table again. */
 export const releaseHashTable = (table) => {
@@ -47,11 +64,20 @@ const regrow = (memory, array, constructor, length, used, fill) => {
     freeArray(memory, array);
     return grown;
 };
+/** A copy of `array`, `length` long, the rest filled with `fill`. */
+const grown = (array, length, fill) => {
+    const copy = new Int32Array(length);
+    copy.set(array);
+    if (fill !== 0)
+        copy.fill(fill, array.length);
+    return copy;
+};
 /** Grows what's by entity index to cover `length` indexes. */
 export const coverEntities = (table, length) => {
     if (table.bucketOf.length >= length)
         return;
     table.bucketOf = regrow(table.memory, table.bucketOf, Int32Array, Math.max(length, 2 * table.bucketOf.length), table.bucketOf.length, -1);
+    table.positionOf = grown(table.positionOf, table.bucketOf.length, 0);
 };
 /** Grows what's by bucket id to hold `count` buckets. */
 export const coverBuckets = (table, count) => {
@@ -64,6 +90,12 @@ export const coverBuckets = (table, count) => {
     table.ticks = regrow(memory, table.ticks, Float64Array, length, capacity, 0);
     for (const [component, ticks] of table.watched)
         table.watched.set(component, regrow(memory, ticks, Float64Array, length, capacity, 0));
+    table.tails = grown(table.tails, length, -1);
+    table.extents = grown(table.extents, length, 0);
+    table.holes = grown(table.holes, length, 0);
+    const listed = new Uint8Array(length);
+    listed.set(table.listed);
+    table.listed = listed;
 };
 /** A bucket's segment's first entry, length and capacity. */
 export const startOf = (table, bucket) => table.records[bucket * table.stride + recordStart];
@@ -157,29 +189,115 @@ const allocateSegment = (table, capacity) => {
     table.used += capacity;
     return start;
 };
-/** Gives a bucket room for `length` entries, moving its segment to the end of the buffer when it doesn't fit. */
-const reserve = (table, bucket, length) => {
+/** The slots a bucket's entries take, with an unsorted one's holes. */
+const extentOf = (table, bucket) => table.tails[bucket] < 0 ? lengthOf(table, bucket) : table.extents[bucket];
+/**
+ * Gives a bucket room for `slots` slots, moving its segment to the end of the buffer when they don't fit; an unsorted
+ * one's gets half as many again spare, since its tail grows into them.
+ */
+const reserve = (table, bucket, slots) => {
     const base = bucket * table.stride;
-    if (table.records[base + recordCapacity] >= length)
+    if (table.records[base + recordCapacity] >= slots)
         return;
-    const capacity = capacityFor(length);
+    const capacity = capacityFor(slots) + (table.tails[bucket] >= 0 ? slots >> 1 : 0);
+    const kept = extentOf(table, bucket);
     const start = allocateSegment(table, capacity);
-    const { entries, records } = table;
-    const from = records[base + recordStart] * entryWords;
-    entries.copyWithin(start * entryWords, from, from + records[base + recordLength] * entryWords);
+    const { records } = table;
+    move(table, start * entryWords, records[base + recordStart] * entryWords, kept * entryWords);
     table.garbage += records[base + recordCapacity];
     records[base + recordStart] = start;
     records[base + recordCapacity] = capacity;
 };
+/** The table's entries as 8-byte words, made again when its entries were. */
+const wideOf = (table) => {
+    const { entries } = table;
+    // Its last 8-byte word may take 4 bytes past the entries, which are in its block: blocks are 64-byte aligned.
+    const length = (entries.length + 1) >> 1;
+    if (table.wide.buffer !== entries.buffer || table.wide.byteOffset !== entries.byteOffset || table.wide.length !== length) {
+        table.wide = new Float64Array(entries.buffer, entries.byteOffset, length);
+    }
+    return table.wide;
+};
+/** Scratch of at least `words` 4-byte words, as 4- and 8-byte words. */
+const scratchOf = (table, words) => {
+    if (2 * table.scratch.length < words) {
+        table.scratch = new Float64Array(Math.max((words + 1) >> 1, 2 * table.scratch.length));
+        table.scratchWords = new Int32Array(table.scratch.buffer);
+    }
+    return table.scratch;
+};
 /**
- * Moves `words` of entries, a multiple of `entryWords`, from `from` to `to` within one buffer: by hand, an entry a step,
- * when few, which a native call would cost more than.
+ * Words a move by an odd number of words takes at least before it goes through the scratch, which costs two views of
+ * it; a shorter one copies a word at a time, allocating nothing. A move this long takes about a microsecond, the views
+ * tens of nanoseconds.
  */
-const move = (entries, to, from, words) => {
-    if (words > 96) {
+const oddWideMinimum = 1024;
+/**
+ * Moves `words` of entries from `from` to `to` in a table's buffer. Shared memory copies an element at a time, so a
+ * long move copies 8-byte words, 8 times faster than 4-byte ones: directly when both ends have the same parity, an
+ * edge word by hand; else, past `oddWideMinimum`, through a scratch, which shifts them by a word, the target's edge
+ * words kept.
+ */
+const moveWide = (table, to, from, words) => {
+    const { entries } = table;
+    if (!table.memory.shared) {
         entries.copyWithin(to, from, from + words);
         return;
     }
+    const wide = wideOf(table);
+    if (((to ^ from) & 1) === 0) {
+        const odd = from & 1;
+        const even = (words - odd) & ~1;
+        const rest = words - odd - even;
+        if (to < from) {
+            if (odd === 1)
+                entries[to] = entries[from];
+            wide.copyWithin((to + odd) >> 1, (from + odd) >> 1, (from + odd + even) >> 1);
+            if (rest === 1)
+                entries[to + words - 1] = entries[from + words - 1];
+        }
+        else {
+            if (rest === 1)
+                entries[to + words - 1] = entries[from + words - 1];
+            wide.copyWithin((to + odd) >> 1, (from + odd) >> 1, (from + odd + even) >> 1);
+            if (odd === 1)
+                entries[to] = entries[from];
+        }
+        return;
+    }
+    if (words < oddWideMinimum) {
+        if (to < from)
+            for (let k = 0; k < words; k++)
+                entries[to + k] = entries[from + k];
+        else
+            for (let k = words - 1; k >= 0; k--)
+                entries[to + k] = entries[from + k];
+        return;
+    }
+    const sourceFirst = from & ~1;
+    const sourceEnd = (from + words + 1) & ~1;
+    const targetFirst = to & ~1;
+    const targetEnd = (to + words + 1) & ~1;
+    const scratch = scratchOf(table, Math.max(sourceEnd - sourceFirst, targetEnd - targetFirst) + 2);
+    const scratchWords = table.scratchWords;
+    scratch.set(wide.subarray(sourceFirst >> 1, sourceEnd >> 1));
+    scratchWords.copyWithin(to - targetFirst, from - sourceFirst, from - sourceFirst + words);
+    if ((to & 1) === 1)
+        scratchWords[0] = entries[targetFirst];
+    if (((to + words) & 1) === 1)
+        scratchWords[targetEnd - targetFirst - 1] = entries[to + words];
+    wide.set(scratch.subarray(0, (targetEnd - targetFirst) >> 1), targetFirst >> 1);
+};
+/**
+ * Moves `words` of entries, a multiple of `entryWords`, from `from` to `to` within a table's buffer: by hand, an entry
+ * a step, when few, which a native call would cost more than.
+ */
+const move = (table, to, from, words) => {
+    const { entries } = table;
+    if (words > 96) {
+        moveWide(table, to, from, words);
+        return;
+    }
     if (to < from) {
         for (let k = 0; k < words; k += 3) {
             entries[to + k] = entries[from + k];
@@ -195,15 +313,16 @@ const move = (entries, to, from, words) => {
         }
     }
 };
-/** Where entity index `index` is in a bucket, or where it would go, by binary search: `~position` when it isn't there. */
-export const positionIn = (table, bucket, index) => {
-    const { entries } = table;
-    const base = startOf(table, bucket);
+/**
+ * Where entity index `index` is among the `end` entries in entity order from entry `start`, holes included, or where it
+ * would go, by binary search: `~position` when it isn't there.
+ */
+const search = (entries, start, end, index) => {
     let low = 0;
-    let high = lengthOf(table, bucket);
+    let high = end;
     while (low < high) {
         const middle = (low + high) >>> 1;
-        const at = entries[(base + middle) * entryWords];
+        const at = entries[(start + middle) * entryWords];
         if (at < index)
             low = middle + 1;
         else if (at > index)
@@ -213,9 +332,24 @@ export const positionIn = (table, bucket, index) => {
     }
     return ~low;
 };
+/** Where entity index `index`'s entry is in a bucket, or -1 when it isn't there. */
+const findEntry = (table, bucket, index) => {
+    const { entries } = table;
+    const start = startOf(table, bucket);
+    const tail = table.tails[bucket];
+    if (tail < 0) {
+        const position = search(entries, start, lengthOf(table, bucket), index);
+        return position < 0 ? -1 : position;
+    }
+    const position = table.positionOf[index];
+    if (position >= tail && position < table.extents[bucket] && entries[(start + position) * entryWords] === index)
+        return position;
+    const found = search(entries, start, tail, index);
+    return found >= 0 && entries[(start + found) * entryWords + 1] >= 0 ? found : -1;
+};
 /** Updates where entity index `index` is: its archetype and row, in the bucket it's filed in. */
 export const relocate = (table, bucket, index, archetype, row) => {
-    const position = positionIn(table, bucket, index);
+    const position = findEntry(table, bucket, index);
     if (position < 0)
         return;
     const at = (startOf(table, bucket) + position) * entryWords;
@@ -229,82 +363,315 @@ const countEmpty = (table, before, after) => {
     else if (before > 0 && after === 0)
         table.empty++;
 };
-/** Removes entity index `index` from a bucket, stamping it. */
-export const removeEntry = (table, bucket, index, tick) => {
-    const position = positionIn(table, bucket, index);
-    if (position < 0)
+/** Empties the list of unsorted buckets, each one listed no longer. */
+const clearList = (table) => {
+    const list = table.unsortedBuckets;
+    for (let k = 0; k < table.unsortedListed; k++)
+        table.listed[list[k]] = 0;
+    table.unsortedListed = 0;
+};
+/** Marks a sorted bucket unsorted, with an empty tail and no holes, listing it unless it's listed still. */
+const unsort = (table, bucket) => {
+    const length = lengthOf(table, bucket);
+    table.tails[bucket] = length;
+    table.extents[bucket] = length;
+    table.holes[bucket] = length;
+    table.unsorted++;
+    if (table.listed[bucket] === 1)
         return;
+    let listed = table.unsortedListed;
+    const list = table.unsortedBuckets;
+    // The list drops the buckets sorted since they were listed once they're most of it, so each listing costs O(1)
+    // amortized.
+    if (listed >= 2 * table.unsorted + 8) {
+        let kept = 0;
+        for (let k = 0; k < listed; k++) {
+            if (table.tails[list[k]] >= 0)
+                list[kept++] = list[k];
+            else
+                table.listed[list[k]] = 0;
+        }
+        listed = kept;
+    }
+    if (listed === list.length)
+        table.unsortedBuckets = grown(list, 2 * listed, 0);
+    table.unsortedBuckets[listed] = bucket;
+    table.unsortedListed = listed + 1;
+    table.listed[bucket] = 1;
+};
+/** Marks an unsorted bucket sorted. */
+const sorted = (table, bucket) => {
+    table.tails[bucket] = -1;
+    if (--table.unsorted === 0)
+        clearList(table);
+};
+/**
+ * After a change to an unsorted bucket: sorted when it's empty or in order, or once its holes and tail pass four times
+ * its entries and 64 more, which bounds what a bucket nothing reads by position keeps.
+ */
+const settle = (table, bucket) => {
+    const length = lengthOf(table, bucket);
+    const extent = table.extents[bucket];
+    const tail = table.tails[bucket];
+    if (length === 0 || (extent === length && tail === extent))
+        sorted(table, bucket);
+    else if (2 * extent - length - tail > (length << 2) + unsortedMinimum)
+        sortBucket(table, bucket);
+};
+/** Removes entity index `index` from a bucket, stamping it; a long one may be left unsorted when `unsorting`. */
+export const removeEntry = (table, bucket, index, tick, unsorting) => {
     const record = bucket * table.stride;
     const length = table.records[record + recordLength];
-    const base = table.records[record + recordStart] * entryWords;
-    move(table.entries, base + position * entryWords, base + (position + 1) * entryWords, (length - position - 1) * entryWords);
+    const start = table.records[record + recordStart];
+    const { entries } = table;
+    const tail = table.tails[bucket];
+    if (tail < 0) {
+        const position = search(entries, start, length, index);
+        if (position < 0)
+            return;
+        if (position < length - 1) {
+            if (!unsorting || length < unsortedMinimum) {
+                const base = start * entryWords;
+                move(table, base + position * entryWords, base + (position + 1) * entryWords, (length - position - 1) * entryWords);
+            }
+            else {
+                unsort(table, bucket);
+                entries[(start + position) * entryWords + 1] = -1;
+                table.holes[bucket] = position;
+            }
+        }
+    }
+    else {
+        const extent = table.extents[bucket];
+        const position = table.positionOf[index];
+        if (position >= tail && position < extent && entries[(start + position) * entryWords] === index) {
+            // Out of the tail, its last entry taking its place.
+            const at = (start + position) * entryWords;
+            const last = (start + extent - 1) * entryWords;
+            if (at !== last) {
+                entries[at] = entries[last];
+                entries[at + 1] = entries[last + 1];
+                entries[at + 2] = entries[last + 2];
+                table.positionOf[entries[at]] = position;
+            }
+            table.extents[bucket] = extent - 1;
+        }
+        else {
+            const found = search(entries, start, tail, index);
+            if (found < 0 || entries[(start + found) * entryWords + 1] < 0)
+                return;
+            if (found === tail - 1 && tail === extent) {
+                table.tails[bucket] = tail - 1;
+                table.extents[bucket] = extent - 1;
+                table.holes[bucket] = Math.min(table.holes[bucket], tail - 1);
+            }
+            else {
+                entries[(start + found) * entryWords + 1] = -1;
+                table.holes[bucket] = Math.min(table.holes[bucket], found);
+            }
+        }
+    }
     table.records[record + recordLength] = length - 1;
     table.ticks[bucket] = tick;
     table.size--;
     countEmpty(table, length, length - 1);
+    if (table.tails[bucket] >= 0)
+        settle(table, bucket);
 };
-/** Inserts entity index `index` at its archetype and row into a bucket, in entity order, stamping it. */
-export const insertEntry = (table, bucket, index, archetype, row, tick) => {
-    const record = bucket * table.stride;
-    const length = table.records[record + recordLength];
-    reserve(table, bucket, length + 1);
-    const found = positionIn(table, bucket, index);
-    const position = found < 0 ? ~found : found;
-    const base = table.records[record + recordStart] * entryWords;
+/** Appends an entry to an unsorted bucket's tail. */
+const appendTail = (table, bucket, index, archetype, row) => {
+    const extent = table.extents[bucket];
+    reserve(table, bucket, extent + 1);
+    const at = (startOf(table, bucket) + extent) * entryWords;
     const { entries } = table;
-    move(entries, base + (position + 1) * entryWords, base + position * entryWords, (length - position) * entryWords);
-    const at = base + position * entryWords;
     entries[at] = index;
     entries[at + 1] = archetype;
     entries[at + 2] = row;
+    table.positionOf[index] = extent;
+    table.extents[bucket] = extent + 1;
+};
+/**
+ * Inserts entity index `index`, which the bucket doesn't hold, at its archetype and row, stamping it: in entity order,
+ * or when `unsorting`, into a long bucket's tail, or the hole it left.
+ */
+export const insertEntry = (table, bucket, index, archetype, row, tick, unsorting) => {
+    const record = bucket * table.stride;
+    const length = table.records[record + recordLength];
+    // A full unsorted bucket with holes closes them in place rather than moving its segment to grow it.
+    if (table.tails[bucket] >= 0 && table.extents[bucket] > length && table.extents[bucket] >= table.records[record + recordCapacity])
+        sortBucket(table, bucket);
+    const tail = table.tails[bucket];
+    if (tail < 0) {
+        reserve(table, bucket, length + 1);
+        const start = table.records[record + recordStart];
+        const { entries } = table;
+        const after = length === 0 || entries[(start + length - 1) * entryWords] < index;
+        if (after || !unsorting || length < unsortedMinimum) {
+            const found = after ? ~length : search(entries, start, length, index);
+            const position = found < 0 ? ~found : found;
+            const base = start * entryWords;
+            move(table, base + (position + 1) * entryWords, base + position * entryWords, (length - position) * entryWords);
+            const at = base + position * entryWords;
+            entries[at] = index;
+            entries[at + 1] = archetype;
+            entries[at + 2] = row;
+        }
+        else {
+            unsort(table, bucket);
+            appendTail(table, bucket, index, archetype, row);
+        }
+    }
+    else {
+        const start = table.records[record + recordStart];
+        const { entries } = table;
+        const extent = table.extents[bucket];
+        const found = search(entries, start, tail, index);
+        if (found >= 0) {
+            // The hole it left.
+            const at = (start + found) * entryWords;
+            entries[at + 1] = archetype;
+            entries[at + 2] = row;
+        }
+        else if (~found === tail && tail === extent) {
+            // After every entry in order, with no tail: still in order.
+            reserve(table, bucket, extent + 1);
+            const at = (startOf(table, bucket) + extent) * entryWords;
+            table.entries[at] = index;
+            table.entries[at + 1] = archetype;
+            table.entries[at + 2] = row;
+            if (table.holes[bucket] === tail)
+                table.holes[bucket] = tail + 1;
+            table.tails[bucket] = tail + 1;
+            table.extents[bucket] = extent + 1;
+        }
+        else
+            appendTail(table, bucket, index, archetype, row);
+    }
     table.records[record + recordLength] = length + 1;
     table.ticks[bucket] = tick;
     table.size++;
     countEmpty(table, length, length + 1);
+    if (table.tails[bucket] >= 0)
+        settle(table, bucket);
+};
+/** Copies entry `from` of `source` to entry `to` of `target`. */
+const copyEntry = (target, to, source, from) => {
+    target[to * entryWords] = source[from * entryWords];
+    target[to * entryWords + 1] = source[from * entryWords + 1];
+    target[to * entryWords + 2] = source[from * entryWords + 2];
 };
 /**
- * Applies many removals and insertions to one bucket in one merge: `removed` entity indexes and `added` entries
- * (`entryWords` each), both in entity order. Keeps the bucket's entries in entity order.
+ * Sorts `count` entries by entity index, the first `count * entryWords` words of `spare`, which holds twice that: runs
+ * of eight by insertion, then merged in passes between its halves.
  */
-export const mergeEntries = (table, bucket, removed, removedCount, added, addedCount, scratch, tick) => {
-    const record = bucket * table.stride;
-    const length = table.records[record + recordLength];
-    const result = length - removedCount + addedCount;
-    const base = table.records[record + recordStart] * entryWords;
-    // The bucket's current entries, copied out, merged back with the insertions, skipping the removals.
-    scratch.set(table.entries.subarray(base, base + length * entryWords));
-    reserve(table, bucket, result);
-    const target = table.entries;
-    let to = table.records[record + recordStart] * entryWords;
-    let r = 0;
-    let a = 0;
-    for (let k = 0; k < length; k++) {
-        const index = scratch[k * entryWords];
-        while (r < removedCount && removed[r] < index)
-            r++;
-        while (a < addedCount && added[a * entryWords] < index) {
-            target[to++] = added[a * entryWords];
-            target[to++] = added[a * entryWords + 1];
-            target[to++] = added[a * entryWords + 2];
-            a++;
+const sortEntries = (spare, count) => {
+    const run = 8;
+    for (let low = 0; low < count; low += run) {
+        for (let k = low + 1, high = Math.min(count, low + run); k < high; k++) {
+            const index = spare[k * entryWords];
+            const archetype = spare[k * entryWords + 1];
+            const row = spare[k * entryWords + 2];
+            let at = k;
+            while (at > low && spare[(at - 1) * entryWords] > index) {
+                copyEntry(spare, at, spare, at - 1);
+                at--;
+            }
+            spare[at * entryWords] = index;
+            spare[at * entryWords + 1] = archetype;
+            spare[at * entryWords + 2] = row;
         }
-        if (r < removedCount && removed[r] === index) {
-            r++;
+    }
+    let from = 0;
+    let to = count;
+    for (let width = run; width < count; width *= 2) {
+        for (let low = 0; low < count; low += 2 * width) {
+            const middle = Math.min(low + width, count);
+            const high = Math.min(low + 2 * width, count);
+            let a = low;
+            let b = middle;
+            for (let k = low; k < high; k++) {
+                if (b >= high || (a < middle && spare[(from + a) * entryWords] <= spare[(from + b) * entryWords]))
+                    copyEntry(spare, to + k, spare, from + a++);
+                else
+                    copyEntry(spare, to + k, spare, from + b++);
+            }
+        }
+        const swap = from;
+        from = to;
+        to = swap;
+    }
+    if (from !== 0)
+        spare.copyWithin(0, from * entryWords, (from + count) * entryWords);
+};
+/**
+ * Puts an unsorted bucket's entries in entity order again: its tail sorted aside, its holes closed from the first, and
+ * the tail merged in from the end, so only the entries past the first hole and the first tail entry's place move.
+ */
+export const sortBucket = (table, bucket) => {
+    const tail = table.tails[bucket];
+    const extent = table.extents[bucket];
+    const start = startOf(table, bucket);
+    const { entries } = table;
+    const count = extent - tail;
+    if (table.spare.length < 2 * count * entryWords)
+        table.spare = new Int32Array(Math.max(2 * count * entryWords, 2 * table.spare.length));
+    const { spare } = table;
+    for (let k = 0; k < count; k++)
+        copyEntry(spare, k, entries, start + tail + k);
+    sortEntries(spare, count);
+    // Holes closed, a run of entries at a time; past the last hole, the rest in one move.
+    let left = extent - lengthOf(table, bucket);
+    let write = Math.min(table.holes[bucket], tail);
+    let read = write;
+    while (read < tail) {
+        if (left === 0) {
+            if (write !== read)
+                move(table, (start + write) * entryWords, (start + read) * entryWords, (tail - read) * entryWords);
+            write += tail - read;
+            break;
+        }
+        if (entries[(start + read) * entryWords + 1] < 0) {
+            read++;
+            left--;
             continue;
         }
-        target[to++] = index;
-        target[to++] = scratch[k * entryWords + 1];
-        target[to++] = scratch[k * entryWords + 2];
+        let end = read + 1;
+        while (end < tail && entries[(start + end) * entryWords + 1] >= 0)
+            end++;
+        if (write !== read)
+            move(table, (start + write) * entryWords, (start + read) * entryWords, (end - read) * entryWords);
+        write += end - read;
+        read = end;
     }
-    for (; a < addedCount; a++) {
-        target[to++] = added[a * entryWords];
-        target[to++] = added[a * entryWords + 1];
-        target[to++] = added[a * entryWords + 2];
+    // The tail merged in from the end: each of its entries, from the last, after the run of entries above it.
+    let kept = write;
+    for (let k = count - 1; k >= 0; k--) {
+        const index = spare[k * entryWords];
+        const found = search(entries, start, kept, index);
+        const position = found < 0 ? ~found : found;
+        const to = position + k + 1;
+        if (kept > position)
+            move(table, (start + to) * entryWords, (start + position) * entryWords, (kept - position) * entryWords);
+        copyEntry(entries, start + position + k, spare, k);
+        kept = position;
     }
-    table.records[record + recordLength] = result;
-    table.ticks[bucket] = tick;
-    table.size += result - length;
-    countEmpty(table, length, result);
+    sorted(table, bucket);
+};
+/** Sorts every unsorted bucket, before the table's arrays are handed to a reader that reads entries by position. */
+export const sortHashTable = (table) => {
+    const list = table.unsortedBuckets;
+    // Sorting the last unsorted one empties the list.
+    for (let k = 0; k < table.unsortedListed; k++)
+        if (table.tails[list[k]] >= 0)
+            sortBucket(table, list[k]);
+};
+/** Forgets every unsorted bucket, before the table is built again. */
+export const forgetUnsorted = (table) => {
+    const list = table.unsortedBuckets;
+    for (let k = 0; k < table.unsortedListed; k++)
+        table.tails[list[k]] = -1;
+    table.unsorted = 0;
+    clearList(table);
 };
 /**
  * Drops the empty buckets once they outnumber those holding entries, compacting the segments when moves left more
@@ -330,8 +697,9 @@ export const tidyHashTable = (table, tick) => {
     if (table.garbage > Math.max(1024, table.used - table.garbage))
         compact(table);
 };
-/** Lays every bucket's segment out again, one after another, with their spare slots. */
+/** Lays every bucket's segment out again, one after another, with their spare slots, each sorted first. */
 const compact = (table) => {
+    sortHashTable(table);
     const { records, stride } = table;
     let total = 0;
     for (let bucket = 0; bucket < table.count; bucket++)
@@ -363,6 +731,7 @@ const compact = (table) => {
  */
 export const loadHashTable = (table, count, entries, keys, hashes, bucketOfEntry, tick, entityCount) => {
     const { words, stride } = table;
+    forgetUnsorted(table);
     coverEntities(table, entityCount);
     table.bucketOf.fill(-1);
     // Sized for as many buckets as it last held, growing as more are found, so the table is as small as its keys need.