narraeon 0.5.5 → 0.5.7

package/README.md

@@ -178,7 +178,7 @@ TMPDIR=/tmp npm run test:package
 
 Project contracts and architecture:
 
-- [CONTEXT.md](CONTEXT.md) — domain vocabulary
+- [GLOSSARY.md](GLOSSARY.md) — domain vocabulary
 - [docs/product-foundation.md](docs/product-foundation.md) — current V1 product contract
 - [docs/adr/](docs/adr/) — architectural decisions
 

package/README.zh-CN.md

@@ -168,7 +168,7 @@ TMPDIR=/tmp npm run test:package
 
 项目契约与架构文档：
 
-- [CONTEXT.md](CONTEXT.md) —— 领域词汇
+- [GLOSSARY.md](GLOSSARY.md) —— 领域词汇
 - [docs/product-foundation.md](docs/product-foundation.md) —— 当前 V1 产品契约
 - [docs/adr/](docs/adr/) —— 架构决策
 

package/dist/node/protocol/appPreferences.js

@@ -7,6 +7,7 @@ export const defaultAppReadingPreferences = {
     lineHeight: 1.7,
     letterSpacing: 0.01,
     measure: 48,
+    showTechnicalInfo: false,
 };
 export function isAppLocale(value) {
     return appLocales.includes(value);
@@ -15,12 +16,13 @@ export function isAppReadingPreferences(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return false;
     const candidate = value;
-    return (Object.keys(candidate).length === 5 &&
+    return (Object.keys(candidate).length === 6 &&
         readingDensities.includes(candidate.density) &&
         isNumberInRange(candidate.fontSize, 15, 24) &&
         isNumberInRange(candidate.lineHeight, 1.4, 2.4) &&
         isNumberInRange(candidate.letterSpacing, 0, 0.12) &&
-        isNumberInRange(candidate.measure, 32, 72));
+        isNumberInRange(candidate.measure, 32, 72) &&
+        typeof candidate.showTechnicalInfo === "boolean");
 }
 function isNumberInRange(value, minimum, maximum) {
     return (typeof value === "number" &&

package/dist/node/protocol/playFailure.js

@@ -0,0 +1,13 @@
+export const playFailureKinds = [
+    "outcome_unknown",
+    "context_limit",
+    "output_limit",
+    "context_unavailable",
+    "retryable",
+    "provider_error",
+    "other",
+    "configuration_mismatch",
+];
+export function isPlayFailureKind(value) {
+    return playFailureKinds.some((kind) => kind === value);
+}

package/dist/node/protocol/protagonistTemplates.js

@@ -0,0 +1,13 @@
+export function isProtagonistTemplateId(value) {
+    return (typeof value === "string" &&
+        /^template-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value));
+}
+export function isProtagonistTemplateContent(name, body) {
+    return (typeof name === "string" &&
+        name.trim().length > 0 &&
+        [...name].length <= 80 &&
+        !/[\r\n\u0085\u2028\u2029]/u.test(name) &&
+        typeof body === "string" &&
+        body.trim().length > 0 &&
+        new TextEncoder().encode(body).byteLength <= 16 * 1024);
+}

package/dist/node/protocol/v1.js

@@ -1,3 +1,4 @@
+import { isAppReadingPreferences, } from "./appPreferences.js";
 import { maxPortableContentArchiveBase64Characters } from "./contentTree.js";
 export const v1Protocol = "narraeon.runtime/v1";
 export class V1ProtocolError extends Error {
@@ -20,11 +21,15 @@ export function parseV1Envelope(value) {
 }
 const requiredFields = {
     "preferences.save": {},
+    "protagonist-templates.save": { name: "string", body: "string" },
+    "protagonist-templates.copy": { id: "string" },
+    "protagonist-templates.delete": { id: "string" },
     "model.save": { connection: "object" },
     "model.copy": { connectionId: "string", name: "string" },
     "model.select": { connectionId: "string" },
     "model.delete": { connectionId: "string" },
     "model.models": { provider: "string", baseUrl: "string" },
+    "content.create-sample": { locale: "string" },
     "content.scripts.read": { packageId: "string" },
     "content.scripts.set": { packageId: "string", enabled: "boolean" },
     "world.package-scripts.read": { worldId: "string" },
@@ -82,8 +87,11 @@ const requiredFields = {
         packageId: "string",
         model: "object",
     },
+    "world.archive.export": { worldId: "string", operationId: "string" },
+    "world.archive.import": { operationId: "string", uploadId: "string" },
     "world.read": { worldId: "string" },
     "world.rename": { worldId: "string", name: "string" },
+    "world.story.export": { worldId: "string", format: "string" },
     "world.delete": { worldId: "string" },
     "artifacts.read": { worldId: "string" },
     "artifacts.debug": { worldId: "string" },
@@ -204,6 +212,14 @@ function validateRequestFields(request) {
         if (!valid || (kind === "string" && value === "" && !allowsEmptyString))
             throw new V1ProtocolError("invalid_request", `${String(request.type)}.${field} is invalid`);
     }
+    if (request.type === "world.story.export" &&
+        request.format !== "markdown" &&
+        request.format !== "text")
+        throw new V1ProtocolError("invalid_request", "world.story.export.format must be markdown or text");
+    if (request.type === "content.create-sample" &&
+        (Object.keys(request).some((key) => key !== "type" && key !== "locale") ||
+            (request.locale !== "en" && request.locale !== "zh-CN")))
+        throw new V1ProtocolError("invalid_request", "content.create-sample.locale must be en or zh-CN, with no extra fields");
     if (request.type === "world.extensions.set" &&
         !["on", "off", "default"].includes(String(request.value)))
         throw new V1ProtocolError("invalid_request", "Invalid world extension choice");
@@ -216,7 +232,7 @@ function validateRequestFields(request) {
             request.locale !== "zh-CN")
             throw new V1ProtocolError("invalid_request", "preferences.save.locale must be en or zh-CN");
         if (request.reading !== undefined &&
-            !isValidReadingPreferences(request.reading))
+            !isAppReadingPreferences(request.reading))
             throw new V1ProtocolError("invalid_request", "preferences.save.reading is invalid");
     }
     if (request.type === "content.import") {
@@ -359,6 +375,10 @@ function validateRequestFields(request) {
 const requestTypes = new Set([
     "workspace.read",
     "preferences.read",
+    "protagonist-templates.read",
+    "protagonist-templates.save",
+    "protagonist-templates.copy",
+    "protagonist-templates.delete",
     "preferences.save",
     "model.read",
     "model.save",
@@ -367,6 +387,7 @@ const requestTypes = new Set([
     "model.delete",
     "model.models",
     "content.create",
+    "content.create-sample",
     "content.scripts.read",
     "content.scripts.set",
     "world.package-scripts.read",
@@ -401,8 +422,11 @@ const requestTypes = new Set([
     "play.workbench.read",
     "prompt.preview",
     "world.create",
+    "world.archive.export",
+    "world.archive.import",
     "world.read",
     "world.rename",
+    "world.story.export",
     "world.delete",
     "artifacts.read",
     "artifacts.debug",
@@ -447,21 +471,3 @@ const requestTypes = new Set([
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isValidReadingPreferences(value) {
-    if (!isRecord(value))
-        return false;
-    return (Object.keys(value).length === 5 &&
-        (value.density === "compact" ||
-            value.density === "standard" ||
-            value.density === "relaxed") &&
-        isFiniteRange(value.fontSize, 15, 24) &&
-        isFiniteRange(value.lineHeight, 1.4, 2.4) &&
-        isFiniteRange(value.letterSpacing, 0, 0.12) &&
-        isFiniteRange(value.measure, 32, 72));
-}
-function isFiniteRange(value, minimum, maximum) {
-    return (typeof value === "number" &&
-        Number.isFinite(value) &&
-        value >= minimum &&
-        value <= maximum);
-}

package/dist/node/protocol/worldArchives.js

@@ -0,0 +1,7 @@
+export const worldArchiveFormat = "narraeon.world-archive/v1";
+export const worldArchiveLimits = {
+    archiveBytes: 1024 ** 3,
+    extractedBytes: 2 * 1024 ** 3,
+    entries: 200_000,
+    entryBytes: 256 * 1024 ** 2,
+};

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,14 @@ import { SettingImprovementRollbackError, SettingImprovementSession, } from "./s
 import { FileNativeWorldStore } from "./world/FileNativeWorldStore.js";
 import { WorldDocumentStore } from "./world/WorldDocumentStore.js";
 import { FileNativeAiFailureLog } from "./model/AiFailureLog.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;
@@ -40,12 +45,14 @@ export class V1Runtime {
     #playCallChains;
     #failureLog;
     #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,
         });
@@ -59,6 +66,11 @@ export class V1Runtime {
                 ? undefined
                 : new FileNativeAiFailureLog(join(input.logRoot, "ai-failures"));
         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,
@@ -116,6 +128,7 @@ export class V1Runtime {
                     controlFingerprint: fingerprintControl(Object.fromEntries(snapshot.files.map(({ path, contents }) => [path, contents]))),
                     documentSnapshot: snapshot,
                     history: structuredClone(binding.history),
+                    historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                     narrativeCheckpoint: binding.narrativeCheckpoint,
                     ...maintenance,
                     additionalMaterials: structuredClone(binding.additionalMaterials),
@@ -132,16 +145,28 @@ 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);
             return { protocol: v1Protocol, result };
         }
+        catch (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) {
@@ -212,6 +237,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,6 +259,8 @@ export class V1Runtime {
                 return this.#models.listModels(request);
             case "content.create":
                 return this.#content.createCurrentTreeContentPackage();
+            case "content.create-sample":
+                return this.#content.createSampleContentPackage(request.locale);
             case "content.scripts.read":
                 return this.#content.packageScriptPermissions(request.packageId);
             case "content.scripts.set":
@@ -401,12 +436,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);
@@ -434,6 +475,7 @@ export class V1Runtime {
                     playCallChain: null,
                     playTimeline,
                     worldRevision: revisionEpoch,
+                    archiveNeedsFreshContext: await this.#worlds.archiveNeedsFreshContext(request.worldId),
                 };
             }
             case "world.surface.read":
@@ -541,7 +583,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 = {
@@ -633,8 +675,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;
@@ -653,6 +694,7 @@ export class V1Runtime {
                         }),
                         additionalMaterials: structuredClone(binding.additionalMaterials),
                         history: structuredClone(binding.history),
+                        historyBackgrounds: structuredClone(binding.historyBackgrounds ?? {}),
                         narrativeCheckpoint: baseline.narrativeCheckpoint,
                         historyAlreadyAppended: Object.keys(binding.history).filter((key) => !(key in baseline.history)),
                         ...(await this.#worlds.inspectDocumentMaintenance(request.worldId, binding.parentHead)),
@@ -926,7 +968,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();
+    }
+}