narraeon 0.1.0

package/dist/node/runtime/play/FileNativeContinuityCorrection.js

@@ -0,0 +1,304 @@
+import { createHash, randomUUID } from "node:crypto";
+import { FileNativePromptCompiler, } from "../prompt/FileNativePromptCompiler.js";
+import { validateMaterialList } from "../prompt/MaterialSelection.js";
+import { FileNativeWorldCreationError, } from "../world/FileNativeWorldStore.js";
+import { WorldOperationBusyError, } from "../world/WorldOperationCoordinator.js";
+import { beginWorldStateRevision, fileNativeStateChanges, reviseWorldState, worldDocumentRevisionFailureMessage, worldStateRevisionChanges, } from "../world/WorldStateRevision.js";
+const claimHeartbeatIntervalMilliseconds = 20_000;
+export class FileNativeContinuityCorrection {
+    #worlds;
+    #compiler;
+    #candidates = new Map();
+    constructor(worlds, options = {}) {
+        this.#worlds = worlds;
+        this.#compiler = options.compiler ?? new FileNativePromptCompiler();
+    }
+    async begin(input) {
+        let claimed;
+        try {
+            claimed = await this.#worlds.operations.claimCorrectionWorld(input.worldId, input.operationId, async () => {
+                if (!(await this.#worlds.reserveOperation(input.operationId)))
+                    return null;
+                try {
+                    const frozen = await this.#worlds.bindPlayCallChain(input.worldId);
+                    this.#worlds.freezeControl(input.worldId, input.operationId);
+                    return frozen;
+                }
+                catch (error) {
+                    this.#worlds.releaseControl(input.worldId, input.operationId);
+                    await this.#worlds.releaseOperationReservation(input.operationId);
+                    throw error;
+                }
+            });
+        }
+        catch (error) {
+            if (error instanceof WorldOperationBusyError)
+                throw new FileNativeWorldCreationError("operation_conflict", "A durable-state operation is already running for this world");
+            throw error;
+        }
+        if (claimed.kind === "busy")
+            throw new FileNativeWorldCreationError("operation_conflict", "A durable-state operation is already running for this world");
+        const binding = claimed.value;
+        if (binding === null) {
+            await this.#worlds.operations.releaseCorrectionWorld(claimed.handle);
+            const previous = await this.#worlds.getOperationOutcome(input.operationId);
+            throw new Error(`The correction operation already exists and cannot be reused: ${previous.outcome}`);
+        }
+        let revision;
+        try {
+            revision = beginWorldStateRevision(binding.files);
+        }
+        catch (error) {
+            this.#worlds.releaseControl(input.worldId, input.operationId);
+            await Promise.allSettled([
+                this.#worlds.releaseOperationReservation(input.operationId),
+                this.#worlds.operations.releaseCorrectionWorld(claimed.handle),
+            ]);
+            throw error;
+        }
+        if (revision.snapshot.status !== "usable") {
+            this.#worlds.releaseControl(input.worldId, input.operationId);
+            await this.#worlds.failOperation(input.operationId, "failed");
+            await this.#worlds.operations.releaseCorrectionWorld(claimed.handle);
+            throw new Error("The correction candidate's world-state snapshot is unavailable");
+        }
+        const claimHeartbeat = setInterval(() => {
+            void this.#worlds.operations
+                .renewCorrectionWorld(claimed.handle)
+                .catch(() => undefined);
+        }, claimHeartbeatIntervalMilliseconds);
+        claimHeartbeat.unref();
+        const candidate = {
+            ...revision,
+            id: `correction-${randomUUID()}`,
+            operationId: input.operationId,
+            worldId: input.worldId,
+            parentHead: binding.parentHead,
+            mode: input.mode,
+            version: 1,
+            materials: structuredClone(binding.additionalMaterials),
+            originalMaterials: structuredClone(binding.additionalMaterials),
+            history: structuredClone(binding.history),
+            reads: new Map(),
+            previewedVersion: null,
+            stateOperationClaim: claimed.handle,
+            claimHeartbeat,
+        };
+        this.#candidates.set(candidate.id, candidate);
+        return {
+            candidateId: candidate.id,
+            version: candidate.version,
+            parentHead: candidate.parentHead,
+        };
+    }
+    readDocument(candidateId, handle) {
+        const candidate = this.#candidate(candidateId);
+        const document = readCompleteDocument(candidate.snapshot, handle);
+        const contents = candidate.files[document.logicalPath];
+        if (contents === undefined)
+            throw new Error(`Correction document ${handle} has no corresponding candidate source`);
+        const hash = sha256(contents);
+        candidate.reads.set(document.documentId, {
+            snapshotId: candidate.snapshot.id,
+            hash,
+        });
+        return {
+            documentId: document.documentId,
+            ref: document.shortRef,
+            path: document.logicalPath,
+            codec: document.codec,
+            hash,
+            contents,
+        };
+    }
+    patchDocument(input) {
+        const candidate = this.#atVersion(input.candidateId, input.expectedVersion);
+        if (candidate.mode !== "documents")
+            throw new Error("A material-list-only correction cannot modify world documents");
+        const target = this.#writableDocument(candidate, input.target, input.expectedHash);
+        this.#reviseDocument(candidate, {
+            kind: "patch",
+            document: { documentId: target.documentId },
+            edits: input.edits,
+        });
+        return this.#advance(candidate);
+    }
+    replaceDocument(input) {
+        const candidate = this.#atVersion(input.candidateId, input.expectedVersion);
+        if (candidate.mode !== "documents")
+            throw new Error("A material-list-only correction cannot modify world documents");
+        const target = this.#writableDocument(candidate, input.target, input.expectedHash);
+        this.#reviseDocument(candidate, {
+            kind: "replace",
+            document: { documentId: target.documentId },
+            contents: input.contents,
+        });
+        return this.#advance(candidate);
+    }
+    replaceMaterials(input) {
+        const candidate = this.#atVersion(input.candidateId, input.expectedVersion);
+        if (candidate.mode !== "materials")
+            throw new Error("A document correction cannot also replace the additional-materials list");
+        const nextMaterials = validateMaterialList(input.nextMaterials);
+        this.#compile(candidate, input.prompt, nextMaterials);
+        candidate.materials = structuredClone(nextMaterials);
+        return this.#advance(candidate);
+    }
+    preview(input) {
+        const candidate = this.#atVersion(input.candidateId, input.expectedVersion);
+        const nextPrompt = this.#compile(candidate, input.prompt, candidate.materials);
+        candidate.previewedVersion = candidate.version;
+        return {
+            parentHead: candidate.parentHead,
+            candidateVersion: candidate.version,
+            diffs: worldStateRevisionChanges(candidate).map((change) => ({
+                documentId: change.documentId,
+                path: change.after.logicalPath.slice("state/".length),
+                beforeHash: change.before?.mechanicalHash ?? "missing",
+                afterHash: change.after.mechanicalHash,
+                before: change.before?.contents ?? "missing",
+                after: change.after.contents,
+            })),
+            materials: {
+                before: structuredClone(candidate.originalMaterials),
+                after: structuredClone(candidate.materials),
+            },
+            nextPrompt,
+        };
+    }
+    async apply(input) {
+        const candidate = this.#atVersion(input.candidateId, input.expectedVersion);
+        if (candidate.previewedVersion !== candidate.version)
+            throw new Error("Preview the current candidate version before applying a correction");
+        if (candidate.snapshot.status !== "usable")
+            throw new Error("Only a usable revision can commit a correction");
+        try {
+            return await this.#worlds.commitCorrection({
+                operationId: candidate.operationId,
+                worldId: candidate.worldId,
+                parentHead: candidate.parentHead,
+                nextMaterials: candidate.materials,
+                stateChanges: fileNativeStateChanges(candidate),
+                stateOperationClaim: candidate.stateOperationClaim,
+            });
+        }
+        catch (error) {
+            await this.#worlds.failOperation(candidate.operationId, "failed");
+            throw error;
+        }
+        finally {
+            clearInterval(candidate.claimHeartbeat);
+            this.#worlds.releaseControl(candidate.worldId, candidate.operationId);
+            this.#candidates.delete(candidate.id);
+            await this.#worlds.operations
+                .releaseCorrectionWorld(candidate.stateOperationClaim)
+                .catch(() => undefined);
+        }
+    }
+    async cancel(candidateId, expectedVersion) {
+        const candidate = this.#atVersion(candidateId, expectedVersion);
+        clearInterval(candidate.claimHeartbeat);
+        this.#candidates.delete(candidateId);
+        this.#worlds.releaseControl(candidate.worldId, candidate.operationId);
+        try {
+            await this.#worlds.failOperation(candidate.operationId, "cancelled");
+        }
+        finally {
+            await this.#worlds.operations.releaseCorrectionWorld(candidate.stateOperationClaim);
+        }
+    }
+    #compile(candidate, prompt, materials) {
+        return this.#compiler.preview({
+            endpoint: {
+                id: `${candidate.worldId}:${candidate.parentHead}`,
+                commit: candidate.parentHead,
+                operationId: candidate.operationId,
+            },
+            hostBinding: structuredClone(prompt.hostBinding),
+            world: {
+                controlFingerprint: fingerprintControl(candidate.files),
+                documentSnapshot: candidate.snapshot,
+                additionalMaterials: materials,
+                history: candidate.history,
+            },
+            playerInputPlacement: "bootstrap",
+            playerInput: "",
+            modelBinding: prompt.modelBinding,
+        });
+    }
+    #candidate(id) {
+        const candidate = this.#candidates.get(id);
+        if (candidate === undefined)
+            throw new Error("The correction candidate does not exist or has ended");
+        return candidate;
+    }
+    #atVersion(id, expected) {
+        const candidate = this.#candidate(id);
+        if (candidate.version !== expected)
+            throw new Error("The correction candidate version has changed");
+        return candidate;
+    }
+    #writableDocument(candidate, handle, expectedHash) {
+        const document = readCompleteDocument(candidate.snapshot, handle);
+        const read = candidate.reads.get(document.documentId);
+        if (read?.snapshotId !== candidate.snapshot.id ||
+            read.hash !== expectedHash)
+            throw new Error("A correction document must be read in full first and carry the same pre-write hash");
+        const contents = candidate.files[document.logicalPath];
+        if (contents === undefined || sha256(contents) !== expectedHash)
+            throw new Error("The correction document's pre-write hash has changed");
+        return document;
+    }
+    #reviseDocument(candidate, command) {
+        const revised = reviseWorldState(candidate, { commands: [command] });
+        if (!revised.ok || revised.snapshotStatus !== "usable")
+            throw new Error(worldDocumentRevisionFailureMessage(revised.diagnostics));
+        candidate.reads.clear();
+    }
+    #advance(candidate) {
+        candidate.version += 1;
+        candidate.previewedVersion = null;
+        return { version: candidate.version };
+    }
+}
+function readCompleteDocument(snapshot, handle) {
+    const requested = handle.replace(/^@/u, "");
+    const selectors = handle.startsWith("@")
+        ? [{ shortRef: requested }]
+        : [{ documentId: requested }, { shortRef: requested }];
+    for (const selector of selectors) {
+        let cursor = null;
+        let descriptor = null;
+        do {
+            const result = snapshot.query({
+                kind: "read_document",
+                document: selector,
+                maxBytes: 65_536,
+                cursor,
+            });
+            if (result.kind === "error") {
+                if (result.diagnostics.every(({ code }) => code === "document_not_found"))
+                    break;
+                throw new Error(worldDocumentRevisionFailureMessage(result.diagnostics));
+            }
+            if (result.kind !== "read_document")
+                throw new Error("The correction document's exact read returned the wrong query result");
+            descriptor = result.document;
+            cursor = result.page.nextCursor;
+        } while (cursor !== null);
+        if (descriptor !== null)
+            return descriptor;
+    }
+    throw new Error(`Correction document ${handle} does not exist`);
+}
+function fingerprintControl(files) {
+    const hash = createHash("sha256");
+    for (const [path, contents] of Object.entries(files)
+        .filter(([path]) => path.startsWith("control/"))
+        .sort(([left], [right]) => left.localeCompare(right)))
+        hash.update(path).update("\0").update(contents).update("\0");
+    return `sha256:${hash.digest("hex")}`;
+}
+function sha256(contents) {
+    return `sha256:${createHash("sha256").update(contents).digest("hex")}`;
+}