narraeon 0.2.0 → 0.3.1

package/dist/node/protocol/v1.js

@@ -106,6 +106,11 @@ const requiredFields = {
         exchangeId: "string",
         playerText: "string",
     },
+    "play.chain.cancel": {
+        worldId: "string",
+        chainId: "string",
+        exchangeId: "string",
+    },
     "play.chain.inspect": { worldId: "string" },
     "play.timeline.page": { worldId: "string", limit: "number" },
     "play.timeline.detail": {
@@ -289,6 +294,7 @@ const requestTypes = new Set([
     "play.chain.revise-player",
     "play.chain.start",
     "play.chain.append",
+    "play.chain.cancel",
     "play.chain.inspect",
     "play.timeline.page",
     "play.timeline.detail",

package/dist/node/runtime/FileNativePhysicalClone.js

@@ -0,0 +1,86 @@
+import { constants } from "node:fs";
+import { copyFile, link, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+const hardlinkFallbackCodes = new Set([
+    "EXDEV",
+    "EPERM",
+    "EACCES",
+    "EMLINK",
+    "ENOTSUP",
+    "EOPNOTSUPP",
+    "ENOSYS",
+]);
+const reflinkFallbackCodes = new Set([
+    "EXDEV",
+    "EPERM",
+    "EACCES",
+    "ENOTSUP",
+    "EOPNOTSUPP",
+    "EINVAL",
+    "ENOSYS",
+]);
+/**
+ * Retains one file without aliasing mutable bytes. Immutable files prefer a
+ * hard link; every other case walks reflink -> exclusive byte copy.
+ */
+export async function cloneFilePhysically(input) {
+    await mkdir(dirname(input.target), { recursive: true, mode: 0o700 });
+    const strategy = process.env.NARRAEON_INTERNAL_TEST_CLONE_STRATEGY;
+    if (input.immutable && strategy !== "reflink" && strategy !== "copy") {
+        try {
+            await link(input.source, input.target);
+            return;
+        }
+        catch (error) {
+            if (await acceptExistingTarget(error, input))
+                return;
+            if (!isFallbackError(error, hardlinkFallbackCodes))
+                throw error;
+        }
+    }
+    if (strategy !== "copy") {
+        try {
+            await copyFileAsReflink(input.source, input.target);
+            return;
+        }
+        catch (error) {
+            if (await acceptExistingTarget(error, input))
+                return;
+            if (!isFallbackError(error, reflinkFallbackCodes))
+                throw error;
+        }
+    }
+    try {
+        await copyFile(input.source, input.target, constants.COPYFILE_EXCL);
+    }
+    catch (error) {
+        if (await acceptExistingTarget(error, input))
+            return;
+        throw error;
+    }
+}
+async function copyFileAsReflink(source, target) {
+    const injectedErrorCode = process.env.NARRAEON_INTERNAL_TEST_REFLINK_ERROR_CODE;
+    if (injectedErrorCode !== undefined) {
+        const error = new Error(`${injectedErrorCode}: injected copy-on-write clone failure`);
+        error.code = injectedErrorCode;
+        error.path = source;
+        error.syscall = "copyfile";
+        throw error;
+    }
+    await copyFile(source, target, constants.COPYFILE_FICLONE_FORCE);
+}
+async function acceptExistingTarget(error, input) {
+    if (!isNodeError(error) ||
+        error.code !== "EEXIST" ||
+        input.onTargetExists === undefined)
+        return false;
+    await input.onTargetExists(input.source, input.target);
+    return true;
+}
+function isFallbackError(error, acceptedCodes) {
+    return isNodeError(error) && acceptedCodes.has(error.code ?? "");
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/node/runtime/V1Runtime.js

@@ -374,17 +374,12 @@ export class V1Runtime {
             }
             case "world.derive": {
                 const preset = await this.#playPresets.bindCurrent();
-                const result = await this.#worlds.deriveWorld({
+                const result = await this.#playCallChains.deriveWorld({
                     operationId: request.operationId,
                     sourceWorldId: request.sourceWorldId,
                     sourceHead: request.sourceHead,
                     hostPresetId: preset.id,
                 });
-                await this.#playCallChains.forkToDerivedWorld({
-                    sourceWorldId: request.sourceWorldId,
-                    sourceHead: request.sourceHead,
-                    targetWorldId: result.world.worldId,
-                });
                 await this.#reconcileResultArtifacts(result);
                 return result;
             }
@@ -427,6 +422,12 @@ export class V1Runtime {
                         ? {}
                         : { observer: playCallChainObserver }),
                 }));
+            case "play.chain.cancel":
+                return playCall(() => this.#playCallChains.cancel({
+                    worldId: request.worldId,
+                    chainId: request.chainId,
+                    exchangeId: request.exchangeId,
+                }));
             case "play.chain.inspect":
                 return this.#playCallChains.inspectWorld(request.worldId);
             case "play.timeline.page":

package/dist/node/runtime/model/FileNativeModelAdapters.js

@@ -3,7 +3,7 @@ import { appendFile, chmod, mkdir, stat } from "node:fs/promises";
 import { dirname } from "node:path";
 import { defaultAppLocale, } from "../../protocol/appPreferences.js";
 import { hasCLIProxyThinkingSuffix, modelReasoningPolicyIssue, } from "../../protocol/modelConnections.js";
-import { ModelHostBindingMismatchError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, } from "./ModelHost.js";
+import { ModelHostBindingMismatchError, ModelHostCancelledError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, } from "./ModelHost.js";
 import { renderPromptDeltaMessage, } from "../prompt/FileNativePromptCompiler.js";
 import { aggregateAnthropicSettingStream, aggregateChatSettingStream, } from "./SettingAuthorStream.js";
 import { aggregateAnthropicModelStream, aggregateChatModelStream, aggregateResponsesModelStream, } from "./ModelHostStream.js";
@@ -82,11 +82,22 @@ export class FileNativeModelHost {
     async exchange(request, observer) {
         assertExchangeCompatibility(this.#connection, request);
         await trace("model_host_exchange", modelHostTrace(request));
-        if (this.#connection.provider === "chat_completions")
-            return this.#chat(request, observer?.onDelta);
-        if (this.#connection.provider === "openai_responses")
-            return this.#responses(request, observer?.onDelta);
-        return this.#anthropic(request, observer?.onDelta);
+        const signal = observer?.signal;
+        if (signalWasAborted(signal))
+            throw cancelledModelRequest();
+        try {
+            if (this.#connection.provider === "chat_completions")
+                return await this.#chat(request, observer?.onDelta, signal);
+            if (this.#connection.provider === "openai_responses")
+                return await this.#responses(request, observer?.onDelta, signal);
+            return await this.#anthropic(request, observer?.onDelta, signal);
+        }
+        catch (error) {
+            if (signalWasAborted(signal) &&
+                !(error instanceof ModelHostCancelledError))
+                throw cancelledModelRequest(error);
+            throw error;
+        }
     }
     /** Uses the production encoders and deliberately omits credentials. */
     previewRequest(request) {
@@ -107,7 +118,7 @@ export class FileNativeModelHost {
             body: cloneProviderValue(body),
         };
     }
-    async #responses(request, onDelta) {
+    async #responses(request, onDelta, signal) {
         return openAIResponsesRequest({
             ...responsesRequestInput(this.#connection, request),
             fetchImplementation: this.#fetch,
@@ -117,9 +128,10 @@ export class FileNativeModelHost {
                 : { failureLog: this.#failureLog }),
             diagnosticContext: modelDiagnosticContext(request),
             ...(onDelta === undefined ? {} : { onDelta }),
+            ...(signal === undefined ? {} : { signal }),
         });
     }
-    async #chat(request, onDelta) {
+    async #chat(request, onDelta, signal) {
         const body = chatRequestBody(this.#connection, request);
         const bodyJson = JSON.stringify(body);
         await trace("chat_request", body);
@@ -135,11 +147,12 @@ export class FileNativeModelHost {
                     "Content-Type": "application/json",
                 },
                 body: bodyJson,
+                ...(signal === undefined ? {} : { signal }),
             }, "Chat Completions"));
             if (!response.ok)
                 throw await providerError(response);
             if (isProviderEventStream(response)) {
-                const streamed = await providerStreamResult(response, "Chat Completions", (body) => aggregateChatModelStream(body, diagnosticDelta));
+                const streamed = await providerStreamResult(response, "Chat Completions", (body) => aggregateChatModelStream(body, diagnosticDelta), signal);
                 capture?.setReasoning(streamed.reasoningContent);
                 await trace("chat_response", streamed);
                 return {
@@ -202,7 +215,7 @@ export class FileNativeModelHost {
             };
         });
     }
-    async #anthropic(request, onDelta) {
+    async #anthropic(request, onDelta, signal) {
         const body = anthropicRequestBody(this.#connection, request);
         const bodyJson = JSON.stringify(body);
         await trace("anthropic_request", body);
@@ -219,11 +232,12 @@ export class FileNativeModelHost {
                     "Content-Type": "application/json",
                 },
                 body: bodyJson,
+                ...(signal === undefined ? {} : { signal }),
             }, "Anthropic Messages"));
             if (!response.ok)
                 throw await providerError(response);
             if (isProviderEventStream(response)) {
-                const streamed = await providerStreamResult(response, "Anthropic Messages", (body) => aggregateAnthropicModelStream(body, diagnosticDelta));
+                const streamed = await providerStreamResult(response, "Anthropic Messages", (body) => aggregateAnthropicModelStream(body, diagnosticDelta), signal);
                 capture?.setReasoning(streamed.reasoningContent);
                 await trace("anthropic_response", streamed);
                 return {
@@ -380,6 +394,8 @@ async function capturedProviderOperation(failureLog, capture, operation) {
         return { ...value, diagnostics: capture.snapshot() };
     }
     catch (error) {
+        if (error instanceof ModelHostCancelledError)
+            throw error;
         if (capture !== undefined && failureLog !== undefined) {
             const exchange = capture.snapshot();
             const failure = {
@@ -1383,11 +1399,12 @@ async function openAIResponsesRequest(input) {
                 "Content-Type": "application/json",
             },
             body: bodyJson,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
         }, "OpenAI Responses"));
         if (!response.ok)
             throw await providerError(response);
         const payload = isProviderEventStream(response)
-            ? await providerStreamResult(response, "Responses API", (body) => aggregateResponsesModelStream(body, diagnosticDelta))
+            ? await providerStreamResult(response, "Responses API", (body) => aggregateResponsesModelStream(body, diagnosticDelta), input.signal)
             : await providerJson(response, "Responses API");
         await trace(`${input.tracePrefix}_response`, payload);
         if (!isRecord(payload) || !Array.isArray(payload.output))
@@ -1626,13 +1643,15 @@ function isProviderEventStream(response) {
         ?.toLowerCase()
         .includes("text/event-stream") === true);
 }
-async function providerStreamResult(response, label, read) {
+async function providerStreamResult(response, label, read, signal) {
     if (response.body === null)
         throw new ModelHostOutcomeUnknownError(`${label} was dispatched but its streaming response has no body`);
     try {
         return await read(response.body);
     }
     catch (error) {
+        if (signal?.aborted === true)
+            throw cancelledModelRequest(error);
         if (error instanceof ModelHostFailureError ||
             error instanceof ModelHostOutcomeUnknownError)
             throw error;
@@ -1644,11 +1663,19 @@ async function dispatchProviderRequest(fetchImplementation, url, init, label) {
         return await fetchImplementation(url, init);
     }
     catch (error) {
+        if (init.signal?.aborted === true)
+            throw cancelledModelRequest(error);
         throw new ModelHostOutcomeUnknownError(`${label} request was dispatched but its outcome is unknown`, {
             cause: error,
         });
     }
 }
+function cancelledModelRequest(cause) {
+    return new ModelHostCancelledError("The player cancelled the dispatched model request; its partial response was not committed and cannot be replayed.", cause === undefined ? undefined : { cause });
+}
+function signalWasAborted(signal) {
+    return signal?.aborted === true;
+}
 function unknownProviderResponse(label) {
     return new ModelHostOutcomeUnknownError(`${label} was dispatched but its response shape could not be confirmed`);
 }

package/dist/node/runtime/model/ModelHost.js

@@ -39,6 +39,13 @@ export class ModelHostOutcomeUnknownError extends Error {
         this.name = "ModelHostOutcomeUnknownError";
     }
 }
+/** The player explicitly stopped a dispatched request; it remains non-replayable. */
+export class ModelHostCancelledError extends ModelHostOutcomeUnknownError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ModelHostCancelledError";
+    }
+}
 /** Deterministic adapter for exercising the true external ModelHost port. */
 /**
  * Deterministic test double. Its synthetic provider state is fixture data, not

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

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { link, mkdir, open, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+import { cloneFilePhysically } from "../FileNativePhysicalClone.js";
 export class FileNativePlayTimelineStore {
     #worldsRoot;
     constructor(dataRoot) {
@@ -49,9 +50,69 @@ export class FileNativePlayTimelineStore {
             throw new Error("Released play-call-chain migration did not reproduce its context chain");
     }
     async persist(value, cursor) {
+        return this.#persistAtRuntimeRoot(this.#worldRuntimeRoot(value.worldId), value, cursor);
+    }
+    async persistStaged(targetWorldRoot, value, cursor) {
+        return this.#persistAtRuntimeRoot(join(resolve(targetWorldRoot), "runtime"), value, cursor);
+    }
+    async cloneContextPrefixToStaging(input) {
+        assertIdentity(input.sourceWorldId, "Source world ID");
+        assertIdentity(input.source.chainId, "Source call-chain ID");
+        const sourceRoot = this.#contextRoot(input.sourceWorldId, input.source.chainId);
+        const targetRuntime = join(resolve(input.targetWorldRoot), "runtime");
+        const targetRoot = join(targetRuntime, "play-contexts", createHash("sha256").update(input.target.chainId).digest("hex"));
+        const transcriptCount = prefixLength(input.source.transcript, input.target.transcript);
+        const eventCount = prefixLength(input.source.events, input.target.events);
+        const completedToolCount = prefixLength(input.source.completedTools, input.target.completedTools);
+        const authorizationCheckpointCount = prefixLength(input.source.documentAuthorizationCheckpoints ?? [], input.target.documentAuthorizationCheckpoints ?? []);
+        await Promise.all([
+            cloneNumberedPrefix({
+                sourceRoot,
+                targetRoot,
+                directory: "transcript",
+                count: transcriptCount,
+                immutable: true,
+            }),
+            cloneNumberedPrefix({
+                sourceRoot,
+                targetRoot,
+                directory: "events",
+                count: eventCount,
+                immutable: false,
+            }),
+            cloneNumberedPrefix({
+                sourceRoot,
+                targetRoot,
+                directory: "summaries",
+                count: eventCount,
+                immutable: false,
+            }),
+            cloneNumberedPrefix({
+                sourceRoot,
+                targetRoot,
+                directory: "completed-tools",
+                count: completedToolCount,
+                immutable: true,
+            }),
+            cloneNumberedPrefix({
+                sourceRoot,
+                targetRoot,
+                directory: "authorization",
+                count: authorizationCheckpointCount,
+                immutable: true,
+            }),
+        ]);
+        return this.persistStaged(input.targetWorldRoot, input.target, {
+            transcriptCount,
+            eventCount,
+            completedToolCount,
+            authorizationCheckpointCount,
+        });
+    }
+    async #persistAtRuntimeRoot(runtimeRoot, value, cursor) {
         assertIdentity(value.worldId, "World ID");
         assertIdentity(value.chainId, "Call-chain ID");
-        const root = this.#contextRoot(value.worldId, value.chainId);
+        const root = join(runtimeRoot, "play-contexts", createHash("sha256").update(value.chainId).digest("hex"));
         const index = contextIndex(value);
         const existingIndex = await readOptionalJson(join(root, "index.json"));
         if (existingIndex === null)
@@ -76,7 +137,7 @@ export class FileNativePlayTimelineStore {
         };
         const lastRequestDigest = value.lastRequest === null
             ? null
-            : await this.#publishRequest(value.worldId, value.lastRequest);
+            : await this.#publishRequest(runtimeRoot, value.lastRequest);
         const continuation = {
             schemaVersion: 3,
             kind: "play_context_continuation",
@@ -122,7 +183,7 @@ export class FileNativePlayTimelineStore {
             updatedAt: value.updatedAt,
         };
         await publishJson(join(root, "state.json"), state);
-        await publishJson(this.#timelineHeadPath(value.worldId), {
+        await publishJson(join(runtimeRoot, "play-timeline-head.json"), {
             schemaVersion: 3,
             worldId: value.worldId,
             chainId: value.chainId,
@@ -379,11 +440,11 @@ export class FileNativePlayTimelineStore {
         assertIdentity(value.chainId, "Call-chain ID");
         return value;
     }
-    async #publishRequest(worldId, request) {
+    async #publishRequest(runtimeRoot, request) {
         const digest = createHash("sha256")
             .update(JSON.stringify(request))
             .digest("hex");
-        await publishImmutableJson(join(this.#worldRuntimeRoot(worldId), "play-requests", `${digest}.json`), request);
+        await publishImmutableJson(join(runtimeRoot, "play-requests", `${digest}.json`), request);
         return digest;
     }
     async #initialCursor(worldId, generation, chainId) {
@@ -799,7 +860,8 @@ function assertPlayEvent(value) {
             throw new Error("Follow-up timeline event has an invalid shape");
         return;
     }
-    if (value.kind !== "failure" || typeof value.message !== "string")
+    if ((value.kind !== "failure" && value.kind !== "cancellation") ||
+        typeof value.message !== "string")
         throw new Error("Play timeline event has an invalid kind");
 }
 function assertTimelineEventSummary(value) {
@@ -807,7 +869,9 @@ function assertTimelineEventSummary(value) {
         !Number.isSafeInteger(value.id) ||
         Number(value.id) < 1)
         throw new Error("Play timeline summary has an invalid identity");
-    if (value.kind === "player" || value.kind === "failure") {
+    if (value.kind === "player" ||
+        value.kind === "failure" ||
+        value.kind === "cancellation") {
         assertPlayEvent(value);
         return;
     }
@@ -955,6 +1019,31 @@ function isRecord(value) {
 function isNodeError(value) {
     return value instanceof Error && "code" in value;
 }
+function prefixLength(source, target) {
+    return isDeepStrictEqual(source.slice(0, target.length), target)
+        ? target.length
+        : 0;
+}
+async function cloneNumberedPrefix(input) {
+    for (let index = 1; index <= input.count; index += 1)
+        await cloneTimelineFile(join(input.sourceRoot, input.directory, numbered(index)), join(input.targetRoot, input.directory, numbered(index)), input.immutable);
+}
+async function cloneTimelineFile(source, target, immutable) {
+    await cloneFilePhysically({
+        source,
+        target,
+        immutable,
+        onTargetExists: assertSameFileBytes,
+    });
+}
+async function assertSameFileBytes(source, target) {
+    const [sourceBytes, targetBytes] = await Promise.all([
+        readFile(source),
+        readFile(target),
+    ]);
+    if (!sourceBytes.equals(targetBytes))
+        throw new Error("Cloned play timeline prefix conflicts in target staging");
+}
 async function readNumbered(root, count) {
     return Promise.all(Array.from({ length: count }, (_, index) => readJson(join(root, numbered(index + 1)))));
 }