narraeon 0.6.0 → 0.6.2

package/dist/node/runtime/world/WorldOperationCoordinator.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, open, readFile, readlink, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { worldQueueFor } from "./WorldQueue.js";
 export class WorldOperationClaimLostError extends Error {
     constructor() {
         super("world operation claim was lost");
@@ -13,104 +14,70 @@ export class WorldOperationBusyError extends Error {
         this.name = "WorldOperationBusyError";
     }
 }
-const worldLockHeartbeatIntervalMilliseconds = 5_000;
-const worldLockHeartbeatStaleMilliseconds = 30_000;
 /**
- * Coordinates current world mutations across processes.
+ * Coordinates world mutations inside the single service process.
  *
- * Short mutations hold a persistent world lock for their full duration.
- * Continuity correction also owns a renewable claim while the user reviews a
- * candidate, so another process cannot change the bound world in between.
+ * Every world-changing operation runs through the data root's `WorldQueue`,
+ * so no cross-process lock files exist. A continuity correction candidate
+ * holds an in-memory claim until it is applied, discarded, or the process
+ * exits. The world-revision epoch is the only persisted marker, because it
+ * is edit-mode state that survives restarts.
  */
 export class FileNativeWorldOperationCoordinator {
-    #correctionClaimsRoot;
     #revisionLocksRoot;
-    #locksRoot;
-    #authorityLocksRoot;
-    #now;
-    #claimDurationMs;
+    #claims;
     #owner;
+    #queue;
     constructor(dataRoot, options = {}) {
         const root = join(resolve(dataRoot), "operations");
-        this.#correctionClaimsRoot = join(root, "correction-claims");
         this.#revisionLocksRoot = join(root, "world-revision-locks");
-        this.#locksRoot = join(root, "world-locks");
-        this.#authorityLocksRoot = join(root, "authority-locks");
-        this.#now = options.now ?? Date.now;
-        this.#claimDurationMs = options.claimDurationMs ?? 60_000;
         this.#owner = options.owner ?? randomUUID;
-        if (!Number.isSafeInteger(this.#claimDurationMs) ||
-            this.#claimDurationMs < 100)
-            throw new TypeError("world operation claim duration is invalid");
+        this.#queue = worldQueueFor(resolve(dataRoot));
+        this.#claims = claimsFor(resolve(dataRoot));
     }
     async claimCorrectionWorld(worldId, operationId, action) {
         assertNonEmptyIdentity(worldId, "world ID");
         assertNonEmptyIdentity(operationId, "correction operation ID");
-        return this.#withWorldLock(worldId, async () => {
-            if ((await this.#reconcileCorrectionClaim(worldId)) !== null ||
+        return this.#queue.run(worldId, async () => {
+            if (this.#claims.has(worldId) ||
                 (await this.#readRevisionLock(worldId)) !== null)
                 return { kind: "busy" };
-            const now = this.#now();
-            const record = {
-                schemaVersion: 1,
-                kind: "continuity_correction_claim",
+            const handle = {
                 worldId,
                 operationId,
                 owner: this.#owner(),
-                acquiredAt: now,
-                renewedAt: now,
-                expiresAt: now + this.#claimDurationMs,
-                renewalCount: 0,
             };
-            await publishJson(this.#correctionClaimPath(worldId), record);
+            this.#claims.set(worldId, handle);
             try {
-                return {
-                    kind: "claimed",
-                    handle: correctionClaimHandle(record),
-                    value: await action(),
-                };
+                return { kind: "claimed", handle, value: await action() };
             }
             catch (error) {
-                await this.#removeCorrectionClaim(record);
+                this.#releaseClaim(handle);
                 throw error;
             }
         });
     }
-    async renewCorrectionWorld(handle) {
+    async withCorrectionWorldClaim(handle, action) {
         assertCorrectionClaimHandle(handle);
-        await this.#withWorldLock(handle.worldId, async () => {
-            const current = await this.#readCorrectionClaim(handle.worldId);
-            if (!sameCorrectionClaimOwner(current, handle))
+        return this.#queue.run(handle.worldId, async () => {
+            const current = this.#claims.get(handle.worldId);
+            if (current?.operationId !== handle.operationId ||
+                current.owner !== handle.owner)
                 throw new WorldOperationClaimLostError();
-            if (current.expiresAt <= this.#now()) {
-                await this.#removeCorrectionClaim(current);
-                throw new WorldOperationClaimLostError();
-            }
-            const renewedAt = Math.max(current.renewedAt, this.#now());
-            await publishJson(this.#correctionClaimPath(handle.worldId), {
-                ...current,
-                renewedAt,
-                expiresAt: renewedAt + this.#claimDurationMs,
-                renewalCount: current.renewalCount + 1,
-            });
+            return action();
         });
     }
-    async withCorrectionWorldClaim(handle, action) {
-        await this.renewCorrectionWorld(handle);
-        return action();
-    }
     async releaseCorrectionWorld(handle) {
         assertCorrectionClaimHandle(handle);
-        await this.#withWorldLock(handle.worldId, async () => {
-            const current = await this.#readCorrectionClaim(handle.worldId);
-            if (sameCorrectionClaimOwner(current, handle))
-                await this.#removeCorrectionClaim(current);
+        await this.#queue.run(handle.worldId, () => {
+            this.#releaseClaim(handle);
+            return Promise.resolve();
         });
     }
     async withExclusiveWorldStateMutation(worldId, action) {
         assertNonEmptyIdentity(worldId, "world ID");
-        return this.#withWorldLock(worldId, async () => {
-            if ((await this.#reconcileCorrectionClaim(worldId)) !== null ||
+        return this.#queue.run(worldId, async () => {
+            if (this.#claims.has(worldId) ||
                 (await this.#readRevisionLock(worldId)) !== null)
                 throw new WorldOperationBusyError();
             return action();
@@ -123,7 +90,7 @@ export class FileNativeWorldOperationCoordinator {
     async acquireWorldRevision(worldId, epochId) {
         assertNonEmptyIdentity(worldId, "world ID");
         assertNonEmptyIdentity(epochId, "world-revision epoch ID");
-        return this.#withWorldLock(worldId, async () => {
+        return this.#queue.run(worldId, async () => {
             const existing = await this.#readRevisionLock(worldId);
             if (existing !== null)
                 return existing.epochId === epochId
@@ -132,14 +99,14 @@ export class FileNativeWorldOperationCoordinator {
                         handle: revisionLockHandle(existing),
                     }
                     : { kind: "busy", epochId: existing.epochId };
-            if ((await this.#reconcileCorrectionClaim(worldId)) !== null)
+            if (this.#claims.has(worldId))
                 return { kind: "busy" };
             const record = {
                 schemaVersion: 1,
                 kind: "world_revision_lock",
                 worldId,
                 epochId,
-                acquiredAt: this.#now(),
+                acquiredAt: Date.now(),
             };
             await publishJson(this.#revisionLockPath(worldId), record);
             return { kind: "acquired", handle: revisionLockHandle(record) };
@@ -147,17 +114,18 @@ export class FileNativeWorldOperationCoordinator {
     }
     async readWorldRevisionLock(worldId) {
         assertNonEmptyIdentity(worldId, "world ID");
-        const record = await this.#readRevisionLock(worldId);
+        const record = await this.#queue.run(worldId, () => this.#readRevisionLock(worldId));
         return record === null ? null : revisionLockHandle(record);
     }
     async assertWorldRevisionUnlocked(worldId) {
         assertNonEmptyIdentity(worldId, "world ID");
-        if ((await this.#readRevisionLock(worldId)) !== null)
+        const record = await this.#queue.run(worldId, () => this.#readRevisionLock(worldId));
+        if (record !== null)
             throw new WorldOperationBusyError();
     }
     async withWorldRevisionLock(handle, action) {
         assertWorldRevisionLockHandle(handle);
-        return this.#withWorldLock(handle.worldId, async () => {
+        return this.#queue.run(handle.worldId, async () => {
             const current = await this.#readRevisionLock(handle.worldId);
             if (current?.epochId !== handle.epochId)
                 throw new WorldOperationClaimLostError();
@@ -166,35 +134,31 @@ export class FileNativeWorldOperationCoordinator {
     }
     async releaseWorldRevision(handle) {
         assertWorldRevisionLockHandle(handle);
-        await this.#withWorldLock(handle.worldId, async () => {
+        await this.#queue.run(handle.worldId, async () => {
             const current = await this.#readRevisionLock(handle.worldId);
             if (current?.epochId !== handle.epochId)
                 return;
             await rm(this.#revisionLockPath(handle.worldId), { force: true });
-            await syncDirectory(this.#revisionLocksRoot);
         });
     }
     async withWorldLocalMetadataMutation(worldId, action) {
         assertNonEmptyIdentity(worldId, "world ID");
-        return this.#withWorldLock(worldId, action);
+        return this.#queue.run(worldId, action);
     }
+    /** Runs a world-changing action in the world's in-process queue. */
     async withWorldAuthorityLock(worldId, action) {
         assertNonEmptyIdentity(worldId, "world ID");
-        return this.#withPersistentWorldLock(this.#authorityLocksRoot, worldId, 6_000, action);
+        return this.#queue.run(worldId, action);
     }
-    async #readCorrectionClaim(worldId) {
-        let value;
-        try {
-            value = JSON.parse(await readFile(this.#correctionClaimPath(worldId), "utf8"));
-        }
-        catch (error) {
-            if (isNodeError(error) && error.code === "ENOENT")
-                return null;
-            throw error;
-        }
-        if (!isCorrectionClaimRecord(value) || value.worldId !== worldId)
-            throw new Error("invalid continuity correction claim");
-        return value;
+    /** True while the current async context already holds this world's queue slot. */
+    isWorldHeld(worldId) {
+        return this.#queue.isHeld(worldId);
+    }
+    #releaseClaim(handle) {
+        const current = this.#claims.get(handle.worldId);
+        if (current?.operationId === handle.operationId &&
+            current.owner === handle.owner)
+            this.#claims.delete(handle.worldId);
     }
     async #readRevisionLock(worldId) {
         let value;
@@ -210,92 +174,20 @@ export class FileNativeWorldOperationCoordinator {
             throw new Error("invalid world revision lock");
         return value;
     }
-    async #reconcileCorrectionClaim(worldId) {
-        const claim = await this.#readCorrectionClaim(worldId);
-        if (claim === null)
-            return null;
-        if (claim.expiresAt > this.#now())
-            return claim;
-        await this.#removeCorrectionClaim(claim);
-        return null;
-    }
-    async #removeCorrectionClaim(claim) {
-        const current = await this.#readCorrectionClaim(claim.worldId);
-        if (current?.operationId !== claim.operationId ||
-            current.owner !== claim.owner)
-            return;
-        await rm(this.#correctionClaimPath(claim.worldId), { force: true });
-        await syncDirectory(this.#correctionClaimsRoot);
-    }
-    async #withWorldLock(worldId, action) {
-        return this.#withPersistentWorldLock(this.#locksRoot, worldId, 200, action);
-    }
-    async #withPersistentWorldLock(locksRoot, worldId, maxAttempts, action) {
-        await mkdir(locksRoot, { recursive: true, mode: 0o700 });
-        const path = join(locksRoot, digest(worldId));
-        const token = randomUUID();
-        const ownerRecord = {
-            schemaVersion: 1,
-            kind: "world_operation_lock_owner",
-            token,
-            pid: process.pid,
-            processIdentity: await localProcessIdentity(),
-        };
-        let acquired = false;
-        for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
-            if (await publishWorldLock(path, ownerRecord, locksRoot)) {
-                acquired = true;
-                break;
-            }
-            const owner = await readWorldLockOwner(path);
-            if (owner !== null && (await worldLockOwnerIsAlive(owner, path))) {
-                await delay(5);
-                continue;
-            }
-            const metadata = await stat(path).catch(() => null);
-            if (owner !== null ||
-                (metadata !== null && Date.now() - metadata.mtimeMs > 30_000))
-                await retireWorldLock(path, owner, metadata, locksRoot);
-            await delay(5);
-        }
-        if (!acquired)
-            throw new WorldOperationBusyError();
-        const heartbeatHandle = await open(join(path, "heartbeat"), "r+");
-        let heartbeatStopped = false;
-        let heartbeatTimer;
-        let heartbeat = Promise.resolve();
-        const scheduleHeartbeat = () => {
-            heartbeatTimer = setTimeout(() => {
-                const now = new Date();
-                heartbeat = heartbeatHandle
-                    .utimes(now, now)
-                    .catch(() => undefined)
-                    .finally(() => {
-                    if (!heartbeatStopped)
-                        scheduleHeartbeat();
-                });
-            }, worldLockHeartbeatIntervalMilliseconds);
-        };
-        scheduleHeartbeat();
-        try {
-            return await action();
-        }
-        finally {
-            heartbeatStopped = true;
-            if (heartbeatTimer !== undefined)
-                clearTimeout(heartbeatTimer);
-            await heartbeat;
-            await heartbeatHandle.close();
-            await releaseWorldLock(path, token, locksRoot);
-        }
-    }
-    #correctionClaimPath(worldId) {
-        return join(this.#correctionClaimsRoot, `${digest(worldId)}.json`);
-    }
     #revisionLockPath(worldId) {
         return join(this.#revisionLocksRoot, `${digest(worldId)}.json`);
     }
 }
+const claimsByDataRoot = new Map();
+/** In-memory correction claims, shared by every store under one data root. */
+function claimsFor(dataRoot) {
+    let claims = claimsByDataRoot.get(dataRoot);
+    if (claims === undefined) {
+        claims = new Map();
+        claimsByDataRoot.set(dataRoot, claims);
+    }
+    return claims;
+}
 function isWorldRevisionLockRecord(value) {
     return (record(value) &&
         hasExactKeys(value, [
@@ -318,50 +210,11 @@ function assertWorldRevisionLockHandle(handle) {
 function revisionLockHandle(record) {
     return { worldId: record.worldId, epochId: record.epochId };
 }
-function isCorrectionClaimRecord(value) {
-    return (record(value) &&
-        hasExactKeys(value, [
-            "schemaVersion",
-            "kind",
-            "worldId",
-            "operationId",
-            "owner",
-            "acquiredAt",
-            "renewedAt",
-            "expiresAt",
-            "renewalCount",
-        ]) &&
-        value.schemaVersion === 1 &&
-        value.kind === "continuity_correction_claim" &&
-        nonEmptyString(value.worldId) &&
-        nonEmptyString(value.operationId) &&
-        nonEmptyString(value.owner) &&
-        finiteNumber(value.acquiredAt) &&
-        finiteNumber(value.renewedAt) &&
-        finiteNumber(value.expiresAt) &&
-        Number(value.acquiredAt) <= Number(value.renewedAt) &&
-        Number(value.renewedAt) < Number(value.expiresAt) &&
-        Number.isSafeInteger(value.renewalCount) &&
-        Number(value.renewalCount) >= 0);
-}
 function assertCorrectionClaimHandle(handle) {
     assertNonEmptyIdentity(handle.worldId, "world ID");
     assertNonEmptyIdentity(handle.operationId, "correction operation ID");
     assertNonEmptyIdentity(handle.owner, "correction claim owner");
 }
-function correctionClaimHandle(record) {
-    return {
-        worldId: record.worldId,
-        operationId: record.operationId,
-        owner: record.owner,
-    };
-}
-function sameCorrectionClaimOwner(record, handle) {
-    return (record !== null &&
-        record.worldId === handle.worldId &&
-        record.operationId === handle.operationId &&
-        record.owner === handle.owner);
-}
 async function publishJson(path, value) {
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
     const temporary = `${path}.${randomUUID()}.tmp`;
@@ -369,178 +222,7 @@ async function publishJson(path, value) {
         encoding: "utf8",
         mode: 0o600,
     });
-    await syncFile(temporary);
     await rename(temporary, path);
-    await syncDirectory(dirname(path));
-}
-async function publishWorldLock(path, owner, locksRoot) {
-    const temporary = `${path}.${owner.token}.tmp`;
-    await mkdir(temporary, { mode: 0o700 });
-    try {
-        const ownerPath = join(temporary, "owner.json");
-        await writeFile(ownerPath, `${JSON.stringify(owner, null, 2)}\n`, {
-            encoding: "utf8",
-            mode: 0o600,
-        });
-        const heartbeatPath = join(temporary, "heartbeat");
-        await writeFile(heartbeatPath, "", { encoding: "utf8", mode: 0o600 });
-        await syncFile(ownerPath);
-        await syncFile(heartbeatPath);
-        await syncDirectory(temporary);
-        try {
-            await rename(temporary, path);
-        }
-        catch (error) {
-            if (await renameWasFencedByExistingDestination(error, path))
-                return false;
-            throw error;
-        }
-        await syncDirectory(locksRoot);
-        return true;
-    }
-    finally {
-        await rm(temporary, { recursive: true, force: true });
-    }
-}
-async function retireWorldLock(path, observedOwner, observedMetadata, locksRoot) {
-    if (observedOwner === null && observedMetadata === null)
-        return;
-    const currentOwner = await readWorldLockOwner(path);
-    const currentMetadata = await stat(path).catch(() => null);
-    const sameGeneration = observedOwner === null
-        ? currentOwner === null &&
-            observedMetadata !== null &&
-            currentMetadata !== null &&
-            observedMetadata.dev === currentMetadata.dev &&
-            observedMetadata.ino === currentMetadata.ino
-        : currentOwner?.token === observedOwner.token;
-    if (!sameGeneration)
-        return;
-    if (currentOwner !== null &&
-        (await worldLockOwnerIsAlive(currentOwner, path)))
-        return;
-    if (currentOwner === null &&
-        (currentMetadata === null || Date.now() - currentMetadata.mtimeMs <= 30_000))
-        return;
-    const generation = observedOwner === null
-        ? `inode-${observedMetadata.dev}-${observedMetadata.ino}`
-        : observedOwner.token;
-    const retired = `${path}.${digest(generation)}.retired`;
-    try {
-        await rename(path, retired);
-        await syncDirectory(locksRoot);
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ENOENT")
-            return;
-        if (await renameWasFencedByExistingDestination(error, retired))
-            return;
-        throw error;
-    }
-}
-async function releaseWorldLock(path, token, locksRoot) {
-    const owner = await readWorldLockOwner(path);
-    if (owner?.token !== token)
-        return;
-    const retired = `${path}.${digest(token)}.retired`;
-    try {
-        await rename(path, retired);
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ENOENT")
-            return;
-        if (await renameWasFencedByExistingDestination(error, retired))
-            return;
-        throw error;
-    }
-    await syncDirectory(locksRoot);
-}
-async function renameWasFencedByExistingDestination(error, destination) {
-    if (!isNodeError(error))
-        return false;
-    if (error.code === "EEXIST" || error.code === "ENOTEMPTY")
-        return true;
-    if (error.code !== "EACCES" && error.code !== "EPERM")
-        return false;
-    return (await stat(destination).catch(() => null)) !== null;
-}
-async function readWorldLockOwner(lockPath) {
-    let value;
-    try {
-        value = JSON.parse(await readFile(join(lockPath, "owner.json"), "utf8"));
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ENOENT")
-            return null;
-        throw error;
-    }
-    if (!record(value) ||
-        !hasExactKeys(value, [
-            "schemaVersion",
-            "kind",
-            "token",
-            "pid",
-            "processIdentity",
-        ]) ||
-        value.schemaVersion !== 1 ||
-        value.kind !== "world_operation_lock_owner" ||
-        !nonEmptyString(value.token) ||
-        !positiveInteger(value.pid) ||
-        !nonEmptyString(value.processIdentity))
-        throw new Error("invalid world operation lock owner");
-    return {
-        schemaVersion: 1,
-        kind: "world_operation_lock_owner",
-        token: value.token,
-        pid: value.pid,
-        processIdentity: value.processIdentity,
-    };
-}
-let cachedLocalProcessIdentity;
-function localProcessIdentity() {
-    cachedLocalProcessIdentity ??= operatingSystemProcessIdentity(process.pid).then((identity) => identity ?? `fallback:${process.pid}:${randomUUID()}`);
-    return cachedLocalProcessIdentity;
-}
-async function worldLockOwnerIsAlive(owner, lockPath) {
-    const identity = await operatingSystemProcessIdentity(owner.pid);
-    if (identity === owner.processIdentity)
-        return true;
-    if (identity !== null)
-        return false;
-    try {
-        process.kill(owner.pid, 0);
-        return true;
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ESRCH")
-            return false;
-    }
-    const heartbeat = await stat(join(lockPath, "heartbeat")).catch(() => null);
-    return (heartbeat !== null &&
-        Date.now() - heartbeat.mtimeMs <= worldLockHeartbeatStaleMilliseconds);
-}
-async function operatingSystemProcessIdentity(pid) {
-    try {
-        const [bootId, namespace, processStat] = await Promise.all([
-            readFile("/proc/sys/kernel/random/boot_id", "utf8"),
-            readlink(`/proc/${pid}/ns/pid`),
-            readFile(`/proc/${pid}/stat`, "utf8"),
-        ]);
-        const commandEnd = processStat.lastIndexOf(") ");
-        if (commandEnd < 0)
-            return null;
-        const fields = processStat
-            .slice(commandEnd + 2)
-            .trim()
-            .split(/\s+/u);
-        const startTicks = fields[19];
-        if (startTicks === undefined || !/^\d+$/u.test(startTicks))
-            return null;
-        return `linux:${bootId.trim()}:${namespace}:${startTicks}`;
-    }
-    catch {
-        return null;
-    }
 }
 function assertNonEmptyIdentity(value, label) {
     if (value.trim() === "")
@@ -549,9 +231,6 @@ function assertNonEmptyIdentity(value, label) {
 function nonEmptyString(value) {
     return typeof value === "string" && value.trim() !== "";
 }
-function positiveInteger(value) {
-    return Number.isSafeInteger(value) && Number(value) > 0;
-}
 function finiteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
@@ -565,27 +244,6 @@ function hasExactKeys(value, keys) {
 function isNodeError(error) {
     return error instanceof Error && "code" in error;
 }
-function delay(milliseconds) {
-    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
-}
-async function syncFile(path) {
-    const handle = await open(path, "r");
-    try {
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
-async function syncDirectory(path) {
-    const handle = await open(path, "r");
-    try {
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
 function digest(value) {
     return createHash("sha256").update(value).digest("hex");
 }

package/dist/node/runtime/world/WorldQueue.js

@@ -0,0 +1,46 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { resolve } from "node:path";
+/**
+ * Serializes world-changing operations inside one service process.
+ *
+ * One data directory is served by one process (ADR-0044), so ordering is
+ * enforced with promise chains instead of cross-process lock files. Re-entry
+ * is recognized through AsyncLocalStorage: an action already running for a
+ * world runs its nested world operations directly instead of waiting on
+ * itself.
+ */
+export class WorldQueue {
+    #tails = new Map();
+    #held = new AsyncLocalStorage();
+    run(worldId, action) {
+        const held = this.#held.getStore();
+        if (held?.has(worldId))
+            return action();
+        const previous = this.#tails.get(worldId) ?? Promise.resolve();
+        const nextHeld = new Set(held ?? []);
+        nextHeld.add(worldId);
+        const result = previous.then(() => this.#held.run(nextHeld, action));
+        const tail = result.then(() => undefined, () => undefined);
+        this.#tails.set(worldId, tail);
+        void tail.then(() => {
+            if (this.#tails.get(worldId) === tail)
+                this.#tails.delete(worldId);
+        });
+        return result;
+    }
+    /** True while the current async context is inside an operation for worldId. */
+    isHeld(worldId) {
+        return this.#held.getStore()?.has(worldId) ?? false;
+    }
+}
+const queuesByDataRoot = new Map();
+/** The queue shared by every store that changes a world under one data root. */
+export function worldQueueFor(dataRoot) {
+    const key = resolve(dataRoot);
+    let queue = queuesByDataRoot.get(key);
+    if (queue === undefined) {
+        queue = new WorldQueue();
+        queuesByDataRoot.set(key, queue);
+    }
+    return queue;
+}