narraeon 0.5.6 → 0.6.0

package/dist/node/runtime/V1Runtime.js

@@ -1,3 +1,6 @@
+import { WorldArchives } from "./archive/WorldArchives.js";
+import { WorldArchiveError } from "./archive/WorldArchiveZip.js";
+import { FileNativeWorldCreationError } from "./world/FileNativeWorldStore.js";
 import { PackageScriptPermissions } from "./extension/PackageScriptPermissions.js";
 import { comparePromptPrefixes } from "./prompt/WorldPromptDiagnostics.js";
 import { join } from "node:path";
@@ -8,7 +11,7 @@ import { ContentPackageImportError, ContentWorkspace, InvalidContentTreeError, }
 import { contentTreeFingerprint } from "./content/ContentTreeFingerprint.js";
 import { inspectContentPackageCurrentTree } from "./content/FileNativeContentTree.js";
 import { FileNativeModelHost } from "./model/FileNativeModelAdapters.js";
-import { equalModelHostBinding, } from "./model/ModelHost.js";
+import {} from "./model/ModelHost.js";
 import { ModelConnectionStore } from "./model/ModelConnectionStore.js";
 import { FileNativeContinuityCorrection } from "./play/FileNativeContinuityCorrection.js";
 import { fingerprintControl } from "./play/PlayDocumentTools.js";
@@ -24,12 +27,15 @@ import { SettingImprovementRollbackError, SettingImprovementSession, } from "./s
 import { FileNativeWorldStore } from "./world/FileNativeWorldStore.js";
 import { WorldDocumentStore } from "./world/WorldDocumentStore.js";
 import { FileNativeAiFailureLog } from "./model/AiFailureLog.js";
+import { FileNativeRuntimeErrorLog } from "./RuntimeErrorLog.js";
+import { ProtagonistTemplateStore } from "./config/ProtagonistTemplateStore.js";
 import { AppPreferencesStore } from "./config/AppPreferencesStore.js";
 import { FileNativeWorldRevisionStore } from "./world-revision/FileNativeWorldRevisionStore.js";
 import { WorldRevisionSession } from "./world-revision/WorldRevisionSession.js";
 import { WorldRevisionWorkspace, WorldRevisionWorkspaceError, } from "./world-revision/WorldRevisionWorkspace.js";
 import { ConversationChanges } from "./ConversationChanges.js";
 export class V1Runtime {
+    worldArchives;
     #conversationChanges = new ConversationChanges();
     #content;
     #playPresets;
@@ -39,13 +45,16 @@ export class V1Runtime {
     #corrections;
     #playCallChains;
     #failureLog;
+    #errorLog;
     #preferences;
+    #protagonistTemplates;
     #settingImprovements;
     #worldRevisions;
     #compiler = new FileNativePromptCompiler();
     #locale = defaultAppLocale;
     constructor(input) {
         this.#preferences = new AppPreferencesStore(input.configRoot);
+        this.#protagonistTemplates = new ProtagonistTemplateStore(input.configRoot);
         this.#content = new ContentWorkspace(input.dataRoot, {
             locale: () => this.#locale,
         });
@@ -58,7 +67,16 @@ export class V1Runtime {
             input.logRoot === undefined
                 ? undefined
                 : new FileNativeAiFailureLog(join(input.logRoot, "ai-failures"));
+        this.#errorLog =
+            input.logRoot === undefined
+                ? undefined
+                : new FileNativeRuntimeErrorLog(join(input.logRoot, "runtime-errors"));
         this.#playCallChains = new PlayCallChain(this.#worlds, this.#compiler, this.#artifacts, this.#failureLog, (id) => this.#conversationChanges.publish(`play:${id}`));
+        this.worldArchives = new WorldArchives({
+            dataRoot: input.dataRoot,
+            worlds: this.#worlds,
+            chains: this.#playCallChains,
+        });
         this.#models = new ModelConnectionStore(input.configRoot);
         this.#corrections = new FileNativeContinuityCorrection(this.#worlds, {
             compiler: this.#compiler,
@@ -133,16 +151,30 @@ export class V1Runtime {
         this.#locale = (await this.#preferences.view()).locale;
         this.#compiler.setLocale(this.#locale);
         await this.#playPresets.initialize();
+        await this.worldArchives.initialize();
     }
     async handle(request, playCallChainObserver) {
         try {
             const result = await this.#dispatch(request, playCallChainObserver);
+            await this.#recordPlayInterruption(request, result);
             return { protocol: v1Protocol, result };
         }
+        catch (error) {
+            await this.#errorLog?.recordRequestFailure(request, error);
+            if (error instanceof WorldArchiveError)
+                throw new V1ProtocolError(error.code, error.message, { cause: error });
+            if (request.type === "world.archive.export" &&
+                error instanceof FileNativeWorldCreationError &&
+                (error.code === "operation_conflict" ||
+                    error.code === "inconsistent_materialization"))
+                throw new V1ProtocolError(error.code, error.message, { cause: error });
+            throw error;
+        }
         finally {
             // Explicit commands may partially settle before failing. Readers recover
             // through the same Runtime projection, never infer success from this signal.
-            if (!/\.(read|status|overview|inspect|page|detail|list|preview)$/.test(request.type)) {
+            if (request.type !== "world.story.export" &&
+                !/\.(read|status|overview|inspect|page|detail|list|preview)$/.test(request.type)) {
                 if ("packageId" in request)
                     this.#conversationChanges.publish(`setting:${request.packageId}`);
                 if ("worldId" in request) {
@@ -152,6 +184,32 @@ export class V1Runtime {
             }
         }
     }
+    async #recordPlayInterruption(request, result) {
+        if (this.#errorLog === undefined ||
+            (request.type !== "play.chain.start" &&
+                request.type !== "play.chain.append"))
+            return;
+        const chain = result;
+        if (chain?.status !== "interrupted" ||
+            typeof chain.lastFailure !== "string" ||
+            chain.events?.at(-1)?.kind === "cancellation")
+            return;
+        await this.#errorLog.recordPlayInterruption(request, {
+            message: chain.lastFailure,
+            ...(chain.lastFailureKind === undefined
+                ? {}
+                : { kind: chain.lastFailureKind }),
+        });
+    }
+    async recordConversationFailure(target, error) {
+        await this.#errorLog?.recordRequestFailure({
+            type: `${target.kind}.observe`,
+            targetId: target.id,
+            ...("sessionId" in target && target.sessionId !== undefined
+                ? { sessionId: target.sessionId }
+                : {}),
+        }, error);
+    }
     subscribeConversation(target, changed) {
         return this.#conversationChanges.subscribe(`${target.kind}:${target.id}`, changed);
     }
@@ -213,6 +271,14 @@ export class V1Runtime {
                 await this.#playPresets.syncBuiltinDefaultLocale();
                 return preferences;
             }
+            case "protagonist-templates.read":
+                return this.#protagonistTemplates.view();
+            case "protagonist-templates.save":
+                return this.#protagonistTemplates.save(request);
+            case "protagonist-templates.copy":
+                return this.#protagonistTemplates.copy(request.id);
+            case "protagonist-templates.delete":
+                return this.#protagonistTemplates.delete(request.id);
             case "model.read":
                 return this.#models.view();
             case "model.save":
@@ -226,7 +292,21 @@ export class V1Runtime {
             case "model.models":
                 return this.#models.listModels(request);
             case "content.create":
-                return this.#content.createCurrentTreeContentPackage();
+                return this.#content.createCurrentTreeContentPackage(request.gameplay);
+            case "content.gameplay.set": {
+                try {
+                    return await this.#content.setCurrentTreeContentGameplayScheme(request.packageId, request.scheme);
+                }
+                catch (error) {
+                    if (error instanceof InvalidContentTreeError)
+                        throw new V1ProtocolError("invalid_request", error.message, {
+                            cause: error,
+                        });
+                    throw error;
+                }
+            }
+            case "content.create-sample":
+                return this.#content.createSampleContentPackage(request.locale);
             case "content.scripts.read":
                 return this.#content.packageScriptPermissions(request.packageId);
             case "content.scripts.set":
@@ -238,7 +318,16 @@ export class V1Runtime {
             case "content.read":
                 return this.#content.readCurrentTreeContentPackage(request.packageId);
             case "content.replace":
-                return this.#content.replaceCurrentTreeContentPackage(request.packageId, request.files);
+                try {
+                    return await this.#content.replaceCurrentTreeContentPackage(request.packageId, request.files);
+                }
+                catch (error) {
+                    if (error instanceof InvalidContentTreeError)
+                        throw new V1ProtocolError("invalid_request", error.message, {
+                            cause: error,
+                        });
+                    throw error;
+                }
             case "content.copy":
                 return this.#content.copyCurrentTreeContentPackage(request.packageId);
             case "content.delete":
@@ -402,12 +491,18 @@ export class V1Runtime {
                 return this.#worlds.getCreationOutcome(request.operationId);
             case "world.rename":
                 return this.#worlds.renameWorld(request.worldId, request.name);
+            case "world.story.export":
+                return this.#worlds.exportStory(request.worldId, request.format, this.#locale);
             case "world.delete":
                 return playCall(async () => {
                     await this.#worlds.assertWorldRevisionUnlocked(request.worldId);
                     this.#playCallChains.forgetWorld(request.worldId);
                     return this.#worlds.deleteWorld(request.worldId);
                 });
+            case "world.archive.export":
+                return this.worldArchives.exportWorld(request);
+            case "world.archive.import":
+                return this.worldArchives.importWorld(request);
             case "world.read": {
                 const head = await this.#worlds.currentHead(request.worldId);
                 const playerViews = await this.#worlds.renderPlayerViewsAtHead(request.worldId, head);
@@ -435,6 +530,7 @@ export class V1Runtime {
                     playCallChain: null,
                     playTimeline,
                     worldRevision: revisionEpoch,
+                    archiveNeedsFreshContext: await this.#worlds.archiveNeedsFreshContext(request.worldId),
                 };
             }
             case "world.surface.read":
@@ -542,7 +638,7 @@ export class V1Runtime {
                     hostPresetId: preset.id,
                 });
                 await this.#reconcileResultArtifacts(result);
-                return result;
+                return { outcome: result.outcome, world: result.world };
             }
             case "play.chain.revise-player": {
                 const base = {
@@ -634,8 +730,7 @@ export class V1Runtime {
                 const frozenBinding = persisted?.value.modelBinding;
                 const continueContext = currentContext !== null &&
                     !currentContext.stale &&
-                    frozenBinding !== undefined &&
-                    equalModelHostBinding(frozenBinding, modelBinding);
+                    frozenBinding?.provider === modelBinding.provider;
                 const baseline = continueContext
                     ? await this.#worlds.bindPlayCallChainAt(request.worldId, currentContext.baselineHead)
                     : binding;
@@ -928,7 +1023,7 @@ async function playCall(operation) {
     }
     catch (error) {
         if (error instanceof PlayCallChainError)
-            throw new V1ProtocolError("invalid_request", error.message, {
+            throw new V1ProtocolError(error.code, error.message, {
                 cause: error,
             });
         throw error;

package/dist/node/runtime/archive/WorldArchiveZip.js

@@ -0,0 +1,202 @@
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, readdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import * as yauzl from "yauzl";
+import * as yazl from "yazl";
+export class WorldArchiveError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "WorldArchiveError";
+    }
+}
+export function archivePath(path) {
+    if (!path ||
+        path.startsWith("/") ||
+        Buffer.byteLength(path, "utf8") > 4096 ||
+        path.includes("\\") ||
+        Array.from(path).some((character) => character.charCodeAt(0) < 32 ||
+            character.charCodeAt(0) === 127 ||
+            '<>:"|?*'.includes(character)) ||
+        path
+            .split("/")
+            .some((part) => !part ||
+            part === "." ||
+            part === ".." ||
+            /[. ]$/u.test(part) ||
+            Buffer.byteLength(part, "utf8") > 255 ||
+            /^(?:AUX|CON|NUL|PRN|COM[1-9]|LPT[1-9])$/u.test(part.split(".", 1)[0].toUpperCase())))
+        throw new WorldArchiveError("unsafe_path", "The archive contains an unsafe path");
+}
+/** No whole-file buffers: hash, limit and persist in the same backpressured pipeline. */
+export async function streamFile(source, destination, maxBytes) {
+    let bytes = 0;
+    const hash = createHash("sha256");
+    await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+    const counter = new Transform({
+        transform(chunk, _encoding, callback) {
+            bytes += chunk.length;
+            if (bytes > maxBytes)
+                callback(new WorldArchiveError("limit_exceeded", "The archive exceeds its size limit"));
+            else {
+                hash.update(chunk);
+                callback(null, chunk);
+            }
+        },
+    });
+    await pipeline(source, counter, createWriteStream(destination, { flags: "wx", mode: 0o600 }));
+    return { bytes, sha256: hash.digest("hex") };
+}
+export async function inventory(root, prefix = "world") {
+    const result = [];
+    async function visit(directory, path) {
+        for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            const full = join(directory, entry.name);
+            const relative = `${path}/${entry.name}`;
+            archivePath(relative);
+            if (entry.isDirectory())
+                await visit(full, relative);
+            else if (entry.isFile()) {
+                const hash = createHash("sha256");
+                let bytes = 0;
+                for await (const chunk of createReadStream(full)) {
+                    const buffer = chunk;
+                    if (!Buffer.isBuffer(buffer))
+                        throw new Error("Archive file stream must be binary");
+                    bytes += buffer.length;
+                    hash.update(buffer);
+                }
+                result.push({ path: relative, bytes, sha256: hash.digest("hex") });
+            }
+            else
+                throw new WorldArchiveError("unsafe_path", "Only files and directories may be archived");
+        }
+    }
+    await visit(root, prefix);
+    return result;
+}
+export async function writeArchive(root, files, destination, limits) {
+    const manifestBytes = (await stat(join(root, "narraeon-world.json"))).size;
+    if (manifestBytes > limits.entryBytes ||
+        files.length + 1 > limits.entries ||
+        files.some((file) => file.bytes > limits.entryBytes) ||
+        files.reduce((sum, file) => sum + file.bytes, manifestBytes) >
+            limits.extractedBytes)
+        throw new WorldArchiveError("limit_exceeded", "The world exceeds archive limits");
+    const zip = new yazl.ZipFile();
+    const output = streamFile(zip.outputStream, destination, limits.archiveBytes);
+    zip.on("error", (error) => zip.outputStream.destroy(error));
+    zip.addFile(join(root, "narraeon-world.json"), "narraeon-world.json");
+    for (const file of files)
+        zip.addFile(join(root, file.path), file.path);
+    zip.end();
+    return (await output).bytes;
+}
+export async function extractArchive(archive, destination, limits) {
+    if ((await stat(archive)).size > limits.archiveBytes)
+        throw new WorldArchiveError("limit_exceeded", "The ZIP exceeds its size limit");
+    let zip;
+    try {
+        zip = await new Promise((resolve, reject) => yauzl.open(archive, { lazyEntries: true, decodeStrings: false, validateEntrySizes: true }, (error, value) => (error ? reject(error) : resolve(value))));
+    }
+    catch (error) {
+        throw new WorldArchiveError("invalid_archive", "Invalid ZIP archive", {
+            cause: error,
+        });
+    }
+    const files = new Map();
+    const paths = new Map();
+    let total = 0;
+    let count = 0;
+    const register = (path, directory, explicit) => {
+        const key = path.normalize("NFKC").toLowerCase();
+        const previous = paths.get(key);
+        if (previous &&
+            (previous.path !== path ||
+                previous.directory !== directory ||
+                (explicit && previous.explicit)))
+            throw new WorldArchiveError("unsafe_path", "Duplicate or conflicting archive paths");
+        paths.set(key, {
+            path,
+            directory,
+            explicit: explicit || previous?.explicit === true,
+        });
+    };
+    try {
+        if (zip.entryCount > limits.entries)
+            throw new WorldArchiveError("limit_exceeded", "Too many ZIP entries");
+        await new Promise((resolve, reject) => {
+            zip.on("error", reject);
+            zip.on("end", resolve);
+            zip.on("entry", (entry) => {
+                void (async () => {
+                    if (++count > limits.entries)
+                        throw new WorldArchiveError("limit_exceeded", "Too many ZIP entries");
+                    let raw;
+                    try {
+                        raw = new TextDecoder("utf-8", { fatal: true }).decode(entry.fileNameRaw);
+                    }
+                    catch {
+                        throw new WorldArchiveError("unsafe_path", "ZIP paths must be UTF-8");
+                    }
+                    const directory = raw.endsWith("/");
+                    const path = directory ? raw.slice(0, -1) : raw;
+                    archivePath(path);
+                    const mode = (entry.externalFileAttributes >>> 16) & 0o170000;
+                    if ((mode !== 0 && mode !== (directory ? 0o040000 : 0o100000)) ||
+                        ((entry.externalFileAttributes & 0x10) !== 0 && !directory))
+                        throw new WorldArchiveError("unsafe_path", "Only regular ZIP files and directories are allowed");
+                    if (entry.isEncrypted() || ![0, 8].includes(entry.compressionMethod))
+                        throw new WorldArchiveError("invalid_archive", "Unsupported ZIP encoding");
+                    const segments = path.split("/");
+                    for (let index = 1; index < segments.length; index++)
+                        register(segments.slice(0, index).join("/"), true, false);
+                    register(path, directory, true);
+                    if (path !== "world" &&
+                        !path.startsWith("world/") &&
+                        path !== "narraeon-world.json")
+                        throw new WorldArchiveError("invalid_archive", "Unexpected archive entry");
+                    if ((path === "world" && !directory) ||
+                        (path === "narraeon-world.json" && directory))
+                        throw new WorldArchiveError("invalid_archive", "Invalid archive layout");
+                    if (entry.uncompressedSize > limits.entryBytes ||
+                        total + entry.uncompressedSize > limits.extractedBytes)
+                        throw new WorldArchiveError("limit_exceeded", "Extracted ZIP exceeds its size limit");
+                    if (directory) {
+                        if (entry.uncompressedSize !== 0)
+                            throw new WorldArchiveError("invalid_archive", "ZIP directory contains data");
+                        await mkdir(join(destination, path), {
+                            recursive: true,
+                            mode: 0o700,
+                        });
+                    }
+                    else {
+                        const stream = await new Promise((resolveStream, rejectStream) => zip.openReadStream(entry, (error, value) => error ? rejectStream(error) : resolveStream(value)));
+                        const result = await streamFile(stream, join(destination, path), Math.min(limits.entryBytes, limits.extractedBytes - total));
+                        if (result.bytes !== entry.uncompressedSize)
+                            throw new WorldArchiveError("integrity_failed", "ZIP entry size does not match");
+                        total += result.bytes;
+                        files.set(path, { path, ...result });
+                    }
+                    zip.readEntry();
+                })().catch(reject);
+            });
+            zip.readEntry();
+        });
+        return files;
+    }
+    catch (error) {
+        if (error instanceof WorldArchiveError)
+            throw error;
+        throw new WorldArchiveError("invalid_archive", "Invalid ZIP archive", {
+            cause: error,
+        });
+    }
+    finally {
+        zip.close();
+    }
+}