@adobe/ecs 0.1.0 → 0.2.0

package/src/implementation/world/index-hash.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { allocateArray, freeArray } from './arrays.js';
 import type { Memory } from './memory.js';
 
@@ -17,9 +18,19 @@ const freedCapacity = 0xFFFFFFFF;
 /**
  * A hash index: an open-addressing table of buckets by key, linear probing, at most half full, each slot a key's hash
  * and its bucket, so a probe reads one line until a hash matches; each bucket a record of its hash, segment and key,
- * its segment of one entries buffer with spare slots holding its entries in entity order. Every array is in the arena,
- * so other threads read it where the world's thread wrote it. By entity index, the bucket it's filed in, so its old
- * bucket is found without its old key.
+ * its segment of one entries buffer with spare slots holding its entries in entity order. Every array readers use is
+ * in the arena, so other threads read it where the world's thread wrote it. By entity index, the bucket it's filed in,
+ * so its old bucket is found without its old key.
+ *
+ * A change to a bucket of at least `unsortedMinimum` entries, in an index that isn't unique, may leave it unsorted:
+ * its entries in entity order up to its tail, with holes where entries left (archetype -1, the entity index kept for
+ * binary search), then a tail of entries appended in any order, each one's position kept by entity index. Its
+ * record's length counts its entries, not its holes, so reading `length` needs no order. It's sorted before anything
+ * reads its entries by position: on the world's thread by a list's `at`, and every unsorted bucket before the index's
+ * arrays are handed to a kernel or another thread; when its segment is full and has holes, which sorting closes in
+ * place; and once its holes and tail pass four times its entries. A segment an unsorted bucket outgrows gets half its
+ * length more spare slots, so sorts to make room come once every so many changes, O(1) amortized each. What only
+ * unsorted buckets use is the world's thread's alone, outside the arena.
  */
 export type HashTable = {
     readonly memory: Memory;
@@ -47,16 +58,42 @@ export type HashTable = {
     size: number;
     /** By component a lookup watches: by bucket, the newest tick its value may have changed in a row there. */
     readonly watched: Map<number, Float64Array>;
+    /** How many buckets are unsorted, and a list holding each of them once, and some sorted since; by bucket, 1 when listed. */
+    unsorted: number;
+    unsortedBuckets: Int32Array;
+    unsortedListed: number;
+    listed: Uint8Array;
+    /**
+     * By bucket id: where its tail starts, or -1 when it's sorted; the slots its entries and holes take; and a position
+     * no hole is before.
+     */
+    tails: Int32Array;
+    extents: Int32Array;
+    holes: Int32Array;
+    /** By entity index: its position in its bucket's tail, valid only while it's there. */
+    positionOf: Int32Array;
+    /** Scratch for sorting a tail: twice its words. */
+    spare: Int32Array;
+    /** The entries as 8-byte words, and a scratch as 8- and 4-byte words, for long moves (`moveWide`). */
+    wide: Float64Array;
+    scratch: Float64Array;
+    scratchWords: Int32Array;
 };
 
 /** What lookups read of a hash table: on the world's thread the table, on a joined thread its views of it. */
-export type HashView = Pick<HashTable, "words" | "stride" | "slots" | "records" | "ticks" | "cleared" | "entries"> & { readonly watched: ReadonlyMap<number, Float64Array> };
+export type HashView = Pick<HashTable, "words" | "stride" | "slots" | "records" | "ticks" | "cleared" | "entries" | "unsorted"> & { readonly watched: ReadonlyMap<number, Float64Array> };
+
+/** Whether a view is the world's table itself, whose unsorted buckets a list sorts before reading them by position. */
+export const isHashTable = (view: HashView): view is HashTable => "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: number, buckets: number): boolean => slotsPerBucket * buckets + 2 <= slots;
 
@@ -77,6 +114,18 @@ export const createHashTable = (memory: Memory, words: number): HashTable => ({
     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. */
@@ -95,10 +144,19 @@ const regrow = <T extends Int32Array | Uint32Array | Float64Array>(memory: Memor
     return grown;
 };
 
+/** A copy of `array`, `length` long, the rest filled with `fill`. */
+const grown = (array: Int32Array, length: number, fill: number): Int32Array => {
+    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: HashTable, length: number): void => {
     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. */
@@ -110,6 +168,12 @@ export const coverBuckets = (table: HashTable, count: number): void => {
     table.records = regrow(memory, table.records, Uint32Array, length * stride, capacity * stride, 0);
     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. */
@@ -202,29 +266,110 @@ const allocateSegment = (table: HashTable, capacity: number): number => {
     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: HashTable, bucket: number, length: number): void => {
+/** The slots a bucket's entries take, with an unsorted one's holes. */
+const extentOf = (table: HashTable, bucket: number): number => 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: HashTable, bucket: number, slots: number): void => {
     const base = bucket * table.stride;
-    if (table.records[base + recordCapacity] >= length) return;
-    const capacity = capacityFor(length);
+    if (table.records[base + recordCapacity] >= slots) return;
+    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: HashTable): Float64Array => {
+    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: HashTable, words: number): Float64Array => {
+    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: Int32Array, to: number, from: number, words: number): void => {
-    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: HashTable, to: number, from: number, words: number): void => {
+    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: HashTable, to: number, from: number, words: number): void => {
+    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];
@@ -241,15 +386,16 @@ const move = (entries: Int32Array, to: number, from: number, words: number): voi
     }
 };
 
-/** 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: HashTable, bucket: number, index: number): number => {
-    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: Int32Array, start: number, end: number, index: number): number => {
     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) high = middle;
         else return middle;
@@ -257,9 +403,24 @@ export const positionIn = (table: HashTable, bucket: number, index: number): num
     return ~low;
 };
 
+/** Where entity index `index`'s entry is in a bucket, or -1 when it isn't there. */
+const findEntry = (table: HashTable, bucket: number, index: number): number => {
+    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: HashTable, bucket: number, index: number, archetype: number, row: number): void => {
-    const position = positionIn(table, bucket, index);
+    const position = findEntry(table, bucket, index);
     if (position < 0) return;
     const at = (startOf(table, bucket) + position) * entryWords;
     table.entries[at + 1] = archetype;
@@ -272,82 +433,299 @@ const countEmpty = (table: HashTable, before: number, after: number): void => {
     else if (before > 0 && after === 0) table.empty++;
 };
 
-/** Removes entity index `index` from a bucket, stamping it. */
-export const removeEntry = (table: HashTable, bucket: number, index: number, tick: number): void => {
-    const position = positionIn(table, bucket, index);
-    if (position < 0) return;
+/** Empties the list of unsorted buckets, each one listed no longer. */
+const clearList = (table: HashTable): void => {
+    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: HashTable, bucket: number): void => {
+    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: HashTable, bucket: number): void => {
+    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: HashTable, bucket: number): void => {
+    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: HashTable, bucket: number, index: number, tick: number, unsorting: boolean): void => {
     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: HashTable, bucket: number, index: number, archetype: number, row: number, tick: number): void => {
-    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: HashTable, bucket: number, index: number, archetype: number, row: number): void => {
+    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: HashTable, bucket: number, index: number, archetype: number, row: number, tick: number, unsorting: boolean): void => {
+    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: Int32Array, to: number, source: Int32Array, from: number): void => {
+    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: HashTable, bucket: number, removed: Int32Array, removedCount: number, added: Int32Array, addedCount: number, scratch: Int32Array, tick: number): void => {
-    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: Int32Array, count: number): void => {
+    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;
+        }
+    }
+    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++);
+            }
         }
-        if (r < removedCount && removed[r] === index) {
-            r++;
+        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: HashTable, bucket: number): void => {
+    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: HashTable): void => {
+    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: HashTable): void => {
+    const list = table.unsortedBuckets;
+    for (let k = 0; k < table.unsortedListed; k++) table.tails[list[k]] = -1;
+    table.unsorted = 0;
+    clearList(table);
 };
 
 /**
@@ -373,8 +751,9 @@ export const tidyHashTable = (table: HashTable, tick: number): void => {
     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: HashTable): void => {
+    sortHashTable(table);
     const { records, stride } = table;
     let total = 0;
     for (let bucket = 0; bucket < table.count; bucket++) if (!isFreed(table, bucket)) total += capacityFor(records[bucket * stride + recordLength]);
@@ -404,6 +783,7 @@ const compact = (table: HashTable): void => {
  */
 export const loadHashTable = (table: HashTable, count: number, entries: Int32Array, keys: Uint32Array, hashes: Uint32Array, bucketOfEntry: Int32Array, tick: number, entityCount: number): void => {
     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.