narraeon 0.1.0

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

@@ -0,0 +1,490 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readlink, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+export class WorldOperationClaimLostError extends Error {
+    constructor() {
+        super("world operation claim was lost");
+        this.name = "WorldOperationClaimLostError";
+    }
+}
+export class WorldOperationBusyError extends Error {
+    constructor() {
+        super("world operation lock is busy");
+        this.name = "WorldOperationBusyError";
+    }
+}
+const worldLockHeartbeatIntervalMilliseconds = 5_000;
+const worldLockHeartbeatStaleMilliseconds = 30_000;
+/**
+ * Coordinates current world mutations across processes.
+ *
+ * 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.
+ */
+export class FileNativeWorldOperationCoordinator {
+    #correctionClaimsRoot;
+    #locksRoot;
+    #authorityLocksRoot;
+    #now;
+    #claimDurationMs;
+    #owner;
+    constructor(dataRoot, options = {}) {
+        const root = join(resolve(dataRoot), "operations");
+        this.#correctionClaimsRoot = join(root, "correction-claims");
+        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");
+    }
+    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 { kind: "busy" };
+            const now = this.#now();
+            const record = {
+                schemaVersion: 1,
+                kind: "continuity_correction_claim",
+                worldId,
+                operationId,
+                owner: this.#owner(),
+                acquiredAt: now,
+                renewedAt: now,
+                expiresAt: now + this.#claimDurationMs,
+                renewalCount: 0,
+            };
+            await publishJson(this.#correctionClaimPath(worldId), record);
+            try {
+                return {
+                    kind: "claimed",
+                    handle: correctionClaimHandle(record),
+                    value: await action(),
+                };
+            }
+            catch (error) {
+                await this.#removeCorrectionClaim(record);
+                throw error;
+            }
+        });
+    }
+    async renewCorrectionWorld(handle) {
+        assertCorrectionClaimHandle(handle);
+        await this.#withWorldLock(handle.worldId, async () => {
+            const current = await this.#readCorrectionClaim(handle.worldId);
+            if (!sameCorrectionClaimOwner(current, handle))
+                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,
+            });
+        });
+    }
+    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);
+        });
+    }
+    async withExclusiveWorldStateMutation(worldId, action) {
+        assertNonEmptyIdentity(worldId, "world ID");
+        return this.#withWorldLock(worldId, async () => {
+            if ((await this.#reconcileCorrectionClaim(worldId)) !== null)
+                throw new WorldOperationBusyError();
+            return action();
+        });
+    }
+    async withWorldLocalMetadataMutation(worldId, action) {
+        assertNonEmptyIdentity(worldId, "world ID");
+        return this.#withWorldLock(worldId, action);
+    }
+    async withWorldAuthorityLock(worldId, action) {
+        assertNonEmptyIdentity(worldId, "world ID");
+        return this.#withPersistentWorldLock(this.#authorityLocksRoot, worldId, 6_000, 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;
+    }
+    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`);
+    }
+}
+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`;
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+        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() === "")
+        throw new TypeError(`${label} is invalid`);
+}
+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);
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    return (Object.keys(value).length === keys.length &&
+        keys.every((key) => Object.hasOwn(value, key)));
+}
+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/WorldStateRevision.js

@@ -0,0 +1,75 @@
+import { WorldDocumentStore, } from "./WorldDocumentStore.js";
+export function beginWorldStateRevision(files) {
+    const snapshot = WorldDocumentStore.open({
+        layout: "world_state",
+        files: Object.entries(files).map(([path, contents]) => ({
+            path,
+            contents,
+        })),
+    });
+    return {
+        snapshot,
+        files: revisionFileRecord(snapshot),
+        changes: new Map(),
+    };
+}
+export function reviseWorldState(candidate, request) {
+    const revised = candidate.snapshot.revise(request);
+    return acceptWorldStateRevision(candidate, revised);
+}
+export function acceptWorldStateRevision(candidate, revised) {
+    if (!revised.ok || revised.snapshotStatus !== "usable")
+        return revised;
+    if (revised.sourceSnapshotId !== candidate.snapshot.id)
+        throw new Error("The revision result does not belong to the current candidate snapshot");
+    candidate.snapshot = revised.snapshot;
+    candidate.files = revisionFileRecord(revised.snapshot);
+    for (const change of revised.changes) {
+        const previous = candidate.changes.get(change.documentId);
+        const accumulated = {
+            ...change,
+            before: previous === undefined ? change.before : previous.before,
+        };
+        if (accumulated.before !== null &&
+            accumulated.before.logicalPath === accumulated.after.logicalPath &&
+            accumulated.before.mechanicalHash === accumulated.after.mechanicalHash &&
+            accumulated.before.contents === accumulated.after.contents)
+            candidate.changes.delete(change.documentId);
+        else
+            candidate.changes.set(change.documentId, Object.freeze(accumulated));
+    }
+    return revised;
+}
+export function worldStateRevisionChanges(candidate) {
+    return [...candidate.changes.values()].sort((left, right) => left.after.logicalPath.localeCompare(right.after.logicalPath));
+}
+export function fileNativeStateChanges(candidate) {
+    if (candidate.snapshot.status !== "usable")
+        throw new Error("Only a usable world-state revision can produce a commit payload");
+    return worldStateRevisionChanges(candidate).map((change) => {
+        const prefix = "state/";
+        if (!change.after.logicalPath.startsWith(prefix))
+            throw new Error("The world-state revision returned a path outside the layout");
+        return {
+            kind: change.before === null ? "create" : "replace",
+            documentId: change.documentId,
+            stableShortRef: change.shortRef,
+            relativePath: change.after.logicalPath.slice(prefix.length),
+            codec: change.codec,
+            expectedPreviousHash: change.before?.mechanicalHash ?? null,
+            nextHash: change.after.mechanicalHash,
+            canonicalNextBytes: change.after.contents,
+        };
+    });
+}
+export function worldDocumentRevisionFailureMessage(diagnostics) {
+    return (diagnostics.map(({ message }) => message).join("; ") ||
+        "The revision is invalid");
+}
+function revisionFileRecord(snapshot) {
+    return Object.fromEntries(snapshot.files.map((file) => {
+        if (file.encoding !== undefined)
+            throw new Error("World-state revisions do not accept binary candidate files");
+        return [file.path, file.contents];
+    }));
+}

package/dist/node/server/createRuntime.js

@@ -0,0 +1,6 @@
+import { V1Runtime } from "../runtime/V1Runtime.js";
+export async function createRuntime(input) {
+    const runtime = new V1Runtime(input);
+    await runtime.initialize();
+    return runtime;
+}