narraeon 0.7.2 → 0.7.5

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

@@ -8,6 +8,8 @@ import { renderPromptDeltaMessage, } from "../prompt/FileNativePromptCompiler.js
 import { aggregateAnthropicModelStream, aggregateChatModelStream, aggregateResponsesModelStream, } from "./ModelHostStream.js";
 import { defaultRuntimeToolDefinitionStrategy, portableRuntimeToolInputSchema, } from "../prompt/FileNativeToolRegistry.js";
 import { AiExchangeCapture, errorDescription, } from "./AiFailureLog.js";
+/** Anthropic allows four cache_control breakpoints per request. */
+const explicitCacheBreakpointLimit = 4;
 const providerContinuationCodecVersion = 1;
 function resolveConnection(connection) {
     const resolved = structuredClone({
@@ -17,6 +19,7 @@ function resolveConnection(connection) {
         reasoningSummary: connection.reasoningSummary ?? "provider_default",
         thinkingMode: connection.thinkingMode ?? "provider_default",
         thinkingBudgetTokens: connection.thinkingBudgetTokens ?? null,
+        cacheSuffixBreakpoint: connection.cacheSuffixBreakpoint ?? true,
     });
     const issue = modelReasoningPolicyIssue({
         provider: resolved.provider,
@@ -95,6 +98,8 @@ export class FileNativeModelHost {
             throw new ModelHostBindingMismatchError("The request protocol does not match the selected model host");
         return new _a({
             ...request.modelConfig,
+            // A frozen request without this choice predates the transcript breakpoint.
+            cacheSuffixBreakpoint: request.modelConfig.cacheSuffixBreakpoint === true,
             baseUrl: this.#connection.baseUrl,
             apiKey: this.#connection.apiKey,
         }, this.#fetch, this.#failureLog);
@@ -458,19 +463,16 @@ async function trace(kind, value) {
         // Explicit acceptance diagnostics must never change provider semantics.
     }
 }
-function items(request) {
-    return request.appended;
-}
 function chatRequestBody(connection, request) {
     const tools = providerToolDefinitions(request);
     const allowedTools = providerAllowedTools(request);
     const hasPolicy = hasFrozenToolPolicy(request);
-    return {
+    return checkedCacheBreakpoints({
         model: connection.modelId,
         ...chatReasoningRequest(connection),
         messages: [
             ...chatBootstrapMessages(connection, request),
-            ...chatAppend(request),
+            ...chatAppend(connection, request),
         ],
         ...(connection.dialect === "cliproxyapi"
             ? { prompt_cache_key: promptCacheKey(connection, request) }
@@ -495,17 +497,17 @@ function chatRequestBody(connection, request) {
         max_tokens: request.maxOutputTokens,
         stream: true,
         stream_options: { include_usage: true },
-    };
+    });
 }
 function anthropicRequestBody(connection, request) {
     const tools = providerToolDefinitions(request);
-    return {
+    return checkedCacheBreakpoints({
         model: connection.modelId,
         ...anthropicReasoningRequest(connection),
         system: request.bootstrap.provider.system,
         messages: [
             ...anthropicBootstrapMessages(request),
-            ...anthropicAppend(request),
+            ...anthropicAppend(connection, request),
         ],
         ...(tools.length === 0
             ? {}
@@ -522,14 +524,14 @@ function anthropicRequestBody(connection, request) {
             : {}),
         max_tokens: request.maxOutputTokens,
         stream: true,
-    };
+    });
 }
 function responsesRequestInput(connection, request) {
     return {
         connection,
         input: [
             ...responsesBootstrapMessages(connection, request),
-            ...responsesAppend(request),
+            ...responsesAppend(connection, request),
         ],
         tools: providerToolDefinitions(request).map((tool) => ({
             name: tool.name,
@@ -555,7 +557,7 @@ function responsesRequestBody(input) {
                 tools: allowedTools.map((name) => ({ type: "function", name })),
             }
             : "auto";
-    return {
+    return checkedCacheBreakpoints({
         model: input.connection.modelId,
         ...responsesReasoningRequest(resolveConnection(input.connection)),
         input: input.input,
@@ -582,7 +584,7 @@ function responsesRequestBody(input) {
         store: false,
         include: ["reasoning.encrypted_content"],
         stream: true,
-    };
+    });
 }
 /**
  * A frozen policy is present when the caller supplies the logical operation's
@@ -758,8 +760,88 @@ function promptCacheKey(connection, request) {
         .update(`${connection.provider}\0${connection.dialect}\0${connection.modelId}\0${scope}`)
         .digest("hex");
 }
-function chatAppend(request) {
-    return items(request).flatMap((item) => {
+/**
+ * Explicit-breakpoint encodings mark the last transcript item before the
+ * request-level suffix, so the next dispatch reads back the transcript it sent.
+ * A request without a suffix keeps its request end as the transcript's entry,
+ * so it is encoded exactly as before.
+ */
+function appendWithSuffixBreakpoint(connection, request, encode, markLast) {
+    const { transcript, suffix } = splitRequestSuffix(request.appended);
+    const encoded = encode(transcript);
+    const breakpoint = suffix.length > 0 &&
+        encoded.length > 0 &&
+        connection.cacheSuffixBreakpoint &&
+        modelCacheStrategy(connection) !== "provider_managed";
+    return [...(breakpoint ? markLast(encoded) : encoded), ...encode(suffix)];
+}
+/** Request-level suffix items are recompiled for every dispatch and never stored. */
+function splitRequestSuffix(appended) {
+    let end = appended.length;
+    while (end > 0 && isRequestSuffix(appended[end - 1]))
+        end -= 1;
+    return { transcript: appended.slice(0, end), suffix: appended.slice(end) };
+}
+function isRequestSuffix(item) {
+    return item.kind === "runtime_notice" && item.notice === "turn_guide";
+}
+/** Message-level cache_control, the form the CLIProxyAPI prefix breakpoints use. */
+function markLastMessage(messages) {
+    const last = messages.at(-1);
+    if (!isRecord(last))
+        throw new Error("The transcript tail cannot carry a cache breakpoint.");
+    return [
+        ...messages.slice(0, -1),
+        { ...last, cache_control: { type: "ephemeral" } },
+    ];
+}
+/** Thinking blocks reject cache_control, so the breakpoint lands on the last block that accepts it. */
+function markLastAnthropicBlock(messages) {
+    const last = messages.at(-1);
+    if (!isRecord(last))
+        throw new Error("The transcript tail cannot carry a cache breakpoint.");
+    const content = typeof last.content === "string"
+        ? [{ type: "text", text: last.content }]
+        : Array.isArray(last.content)
+            ? last.content
+            : [];
+    const index = content.findLastIndex((block) => isRecord(block) &&
+        block.type !== "thinking" &&
+        block.type !== "redacted_thinking");
+    if (index < 0)
+        throw new Error("The Anthropic transcript tail has no block that can carry a cache breakpoint.");
+    return [
+        ...messages.slice(0, -1),
+        {
+            ...last,
+            content: content.map((block, position) => position === index
+                ? {
+                    ...block,
+                    cache_control: { type: "ephemeral" },
+                }
+                : block),
+        },
+    ];
+}
+/** Refuses a request over the breakpoint limit instead of silently dropping one. */
+function checkedCacheBreakpoints(body) {
+    const count = countCacheBreakpoints(body);
+    if (count > explicitCacheBreakpointLimit)
+        throw new Error(`The request has ${count} cache breakpoints; the Anthropic limit is ${explicitCacheBreakpointLimit}.`);
+    return body;
+}
+function countCacheBreakpoints(value) {
+    if (Array.isArray(value))
+        return value.reduce((total, item) => total + countCacheBreakpoints(item), 0);
+    if (!isRecord(value))
+        return 0;
+    return Object.entries(value).reduce((total, [key, item]) => total + (key === "cache_control" ? 1 : 0) + countCacheBreakpoints(item), 0);
+}
+function chatAppend(connection, request) {
+    return appendWithSuffixBreakpoint(connection, request, chatItems, markLastMessage);
+}
+function chatItems(items) {
+    return items.flatMap((item) => {
         if (item.kind === "player" ||
             item.kind === "user" ||
             item.kind === "runtime_notice")
@@ -782,7 +864,10 @@ function chatAppend(request) {
         throw continuationError("Chat Completions");
     });
 }
-function anthropicAppend(request) {
+function anthropicAppend(connection, request) {
+    return appendWithSuffixBreakpoint(connection, request, anthropicItems, markLastAnthropicBlock);
+}
+function anthropicItems(items) {
     const messages = [];
     let toolResults = [];
     const flushToolResults = () => {
@@ -791,7 +876,7 @@ function anthropicAppend(request) {
         messages.push({ role: "user", content: toolResults });
         toolResults = [];
     };
-    for (const item of items(request)) {
+    for (const item of items) {
         if (item.kind === "tool") {
             toolResults.push({
                 type: "tool_result",
@@ -825,8 +910,11 @@ function anthropicAppend(request) {
     flushToolResults();
     return messages;
 }
-function responsesAppend(request) {
-    return items(request).flatMap((item) => {
+function responsesAppend(connection, request) {
+    return appendWithSuffixBreakpoint(connection, request, responsesItems, markLastMessage);
+}
+function responsesItems(items) {
+    return items.flatMap((item) => {
         if (item.kind === "player" ||
             item.kind === "user" ||
             item.kind === "runtime_notice")

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

@@ -1,30 +1,33 @@
 import { isNarrativeOrigin, } from "../history/HistoryBackground.js";
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { isDeepStrictEqual } from "node:util";
+/** Written last by the released-record cleanup (ADR-0034); its absence means "not yet run". */
+const LAYOUT_MARKER = "play-advance-layout.json";
 /**
  * The single in-progress play advance of a call chain, if any.
  *
  * It exists only between `begin` and `markSettled`. A marker that survives a
  * restart means the advance was interrupted; the runtime marks the chain
- * interrupted and the player retries. Legacy records from earlier layouts are
- * ignored, so they never block a world from opening.
+ * interrupted and the player retries. Released records from earlier layouts
+ * never block a world from opening, and the storage upgrade removes them
+ * (see `migrateLayout`).
  */
 export class FileNativePlayAdvanceStore {
     #worldsRoot;
     constructor(dataRoot) {
         this.#worldsRoot = join(resolve(dataRoot), "worlds-file-native");
     }
-    async begin(base) {
-        assertBase(base);
-        const current = await this.readCurrent(base.worldId, base.chainId);
+    async begin(advance) {
+        assertBase(advance);
+        const marker = persistedAdvance(advance);
+        const current = await this.readCurrent(marker.worldId, marker.chainId);
         if (current !== null) {
-            if (!sameAdvanceBase(current, base))
+            if (!sameAdvance(current, marker))
                 throw new Error("Another play advance is still awaiting settlement");
             return;
         }
-        await publishJson(this.#markerPath(base.worldId, base.chainId), base);
+        await publishJson(this.#markerPath(marker.worldId, marker.chainId), marker);
     }
     async readCurrent(worldId, chainId) {
         assertIdentity(worldId, "World ID");
@@ -37,13 +40,15 @@ export class FileNativePlayAdvanceStore {
             throw new Error("Play advance marker belongs to another context");
         return value;
     }
-    async markSettled(base) {
-        const current = await this.readCurrent(base.worldId, base.chainId);
+    async markSettled(advance) {
+        const current = await this.readCurrent(advance.worldId, advance.chainId);
         if (current === null)
             return;
-        if (!sameAdvanceBase(current, base))
+        if (!sameAdvance(current, advance))
             throw new Error("Play advance is no longer current");
-        await rm(this.#markerPath(base.worldId, base.chainId), { force: true });
+        await rm(this.#markerPath(advance.worldId, advance.chainId), {
+            force: true,
+        });
     }
     /** Remove the in-progress marker and all advance records of a discarded chain. */
     async discardChain(worldId, chainId) {
@@ -52,16 +57,73 @@ export class FileNativePlayAdvanceStore {
             force: true,
         });
     }
+    /**
+     * Whether the world's advance records are free of the pre-ADR-0044 layout
+     * (ADR-0034). Reads never write: a world with no released records is current
+     * without a marker.
+     */
+    async layoutCurrent(worldId) {
+        assertIdentity(worldId, "World ID");
+        if ((await readOptionalJson(this.#layoutMarkerPath(worldId))) !==
+            null)
+            return true;
+        return (await this.#releasedChainRoots(worldId)).length === 0;
+    }
+    /**
+     * Remove the released `records/` and `current.json` of every chain. Each
+     * chain's `in-progress.json` stays as it is, and a chain left empty is removed.
+     * The marker is written last, so an interrupted run simply runs again.
+     */
+    async migrateLayout(worldId) {
+        assertIdentity(worldId, "World ID");
+        if (await this.layoutCurrent(worldId))
+            return;
+        for (const chainRoot of await this.#releasedChainRoots(worldId)) {
+            await rm(join(chainRoot, "records"), { recursive: true, force: true });
+            await rm(join(chainRoot, "current.json"), { force: true });
+            if ((await readdir(chainRoot)).length === 0)
+                await rm(chainRoot, { recursive: true, force: true });
+        }
+        await publishJson(this.#layoutMarkerPath(worldId), layoutMarker());
+    }
+    /** Chain directories that still hold a released record or pointer. */
+    async #releasedChainRoots(worldId) {
+        const advancesRoot = join(this.#worldsRoot, worldId, "runtime", "play-advances");
+        const roots = [];
+        for (const name of await readDirectoryNames(advancesRoot)) {
+            const chainRoot = join(advancesRoot, name);
+            if ((await pathExists(join(chainRoot, "records"))) ||
+                (await pathExists(join(chainRoot, "current.json"))))
+                roots.push(chainRoot);
+        }
+        return roots;
+    }
+    #layoutMarkerPath(worldId) {
+        return join(this.#worldsRoot, worldId, "runtime", LAYOUT_MARKER);
+    }
     #markerPath(worldId, chainId) {
         return join(this.#worldsRoot, worldId, "runtime", "play-advances", digest(chainId), "in-progress.json");
     }
 }
-function sameAdvanceBase(left, right) {
-    const { createdAt: leftCreatedAt, ...leftIdentity } = left;
-    const { createdAt: rightCreatedAt, ...rightIdentity } = right;
-    void leftCreatedAt;
-    void rightCreatedAt;
-    return isDeepStrictEqual(leftIdentity, rightIdentity);
+/**
+ * Whether two advances are the same one. The marker is confirmed by these
+ * identity fields alone; the frozen request is never compared (ADR-0044).
+ */
+function sameAdvance(left, right) {
+    return (left.advanceKind === right.advanceKind &&
+        left.worldId === right.worldId &&
+        left.chainId === right.chainId &&
+        left.advanceId === right.advanceId &&
+        left.operationId === right.operationId &&
+        left.eventId === right.eventId);
+}
+/** The marker form of an advance: a player advance's frozen request stays in memory. */
+function persistedAdvance(advance) {
+    if (!("nextRequest" in advance))
+        return advance;
+    const { nextRequest: _nextRequest, ...marker } = advance;
+    void _nextRequest;
+    return marker;
 }
 function assertBase(value) {
     if (!isRecord(value) ||
@@ -90,9 +152,10 @@ function assertBase(value) {
             !Number.isSafeInteger(value.transcriptStart) ||
             Number(value.transcriptStart) < 0 ||
             !Number.isSafeInteger(value.exchange) ||
-            Number(value.exchange) < 1 ||
-            !isRecord(value.nextRequest))
+            Number(value.exchange) < 1)
             throw new Error("Player advance has an invalid shape");
+        // A marker released before ADR-0044 may still carry `nextRequest`. Recovery
+        // never reads it, so the field is tolerated and not validated.
     }
     else if (!Number.isSafeInteger(value.exchange) ||
         Number(value.exchange) < 0 ||
@@ -120,6 +183,26 @@ async function readOptionalJson(path) {
         throw error;
     }
 }
+async function readDirectoryNames(directory) {
+    try {
+        return await readdir(directory);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function pathExists(path) {
+    return stat(path).then(() => true, (error) => {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return false;
+        throw error;
+    });
+}
+function layoutMarker() {
+    return { schemaVersion: 1, kind: "play_advance_layout" };
+}
 /** Atomic publish: write a temporary file, then rename over the target. */
 async function publishJson(path, value) {
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });

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

@@ -0,0 +1,211 @@
+import { ModelHostBindingMismatchError, ModelHostCancelledError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, modelHostFailureRequiresFreshContext, } from "../model/ModelHost.js";
+import { classifyPlayFailure } from "./PlayFailure.js";
+const messages = {
+    playerCommitted: "The player message is committed; the frozen model request is ready to continue.",
+    toolStepSettled: "The completed tool response is settled; its frozen continuation request is ready.",
+    cancelledBeforeDispatch: "The player cancelled before the next Provider dispatch; the frozen request can be resumed without replaying a completed model result.",
+    followupsCancelled: "The player cancelled the remaining follow-up generation after the narrative was committed.",
+    noContinuation: "The complete model response has no provider-native continuation payload; use a fresh context.",
+    noOutput: "The model returned neither text nor a complete tool call.",
+    serviceStoppedAfterHead: "The service stopped after the world was updated; use a fresh context.",
+    serviceStoppedSavingPlayer: "The service stopped while saving the player message; use a fresh context.",
+    serviceStoppedRetryable: "The service stopped while the model request was in progress; retry to call the model again.",
+    serviceStoppedNoRequest: "The service stopped before preparing a model request; use a fresh context.",
+    dispatchInterrupted: "The model request was interrupted.",
+};
+export class PlayAdvanceLifecycle {
+    #ports;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    /**
+     * Marks a Provider dispatch as in progress. `running` is not an ending: it is
+     * the state that every dispatch replaces with an ending before it returns.
+     */
+    beginDispatch(session, request, attempt) {
+        session.status = "running";
+        session.canRetry = false;
+        session.lastFailure = null;
+        delete session.lastFailureKind;
+        session.lastRequest = structuredClone(request);
+        session.lastRequestAttempt = attempt;
+    }
+    /**
+     * Applies an ending, persists the session, then clears the advance marker
+     * and notifies. Every ending of an advance goes through here, so no path
+     * can persist without clearing the marker it settles.
+     */
+    async end(session, ending, advance, notify) {
+        applyEnding(session, ending);
+        await this.#ports.persist(session);
+        if (advance !== null)
+            await this.#ports.clearMarker(advance);
+        notify?.();
+    }
+    /**
+     * Ends an advance that a process exit cut off (ADR-0044). Nothing is
+     * replayed: the exchange is interrupted, and only the chain's own frozen
+     * request can be retried, and only while the world has not moved on.
+     */
+    async recoverAbandoned(session, advance, headMoved) {
+        const playerPhase = advance?.advanceKind === "player";
+        const streaming = playerPhase
+            ? undefined
+            : session.events.findLast((event) => event.kind === "assistant" &&
+                event.status === "streaming" &&
+                (advance === null || event.id === advance.eventId));
+        const canRetry = !headMoved && !playerPhase && session.lastRequest !== null;
+        const message = headMoved
+            ? messages.serviceStoppedAfterHead
+            : playerPhase
+                ? messages.serviceStoppedSavingPlayer
+                : canRetry
+                    ? messages.serviceStoppedRetryable
+                    : messages.serviceStoppedNoRequest;
+        await this.end(session, {
+            kind: "failed",
+            message,
+            failureKind: canRetry ? "retryable" : "other",
+            canRetry,
+            streamingEventId: streaming?.id,
+        }, advance);
+    }
+}
+/**
+ * The ending of an exchange that raised an error before its response was
+ * settled. Cancellation after dispatch is named explicitly here and is never
+ * a retry, even though `ModelHostCancelledError` is also an outcome-unknown
+ * error (ADR-0030).
+ */
+export function dispatchFailureEnding(error, streamingEventId) {
+    const message = errorMessage(error, messages.dispatchInterrupted);
+    if (error instanceof ModelHostCancelledError)
+        return { kind: "cancelled_after_dispatch", message, streamingEventId };
+    const requiresFreshContext = error instanceof ModelHostBindingMismatchError ||
+        error instanceof ModelHostContinuationError ||
+        error instanceof ModelHostOutcomeUnknownError ||
+        modelHostFailureRequiresFreshContext(error);
+    const canRetry = !requiresFreshContext && error instanceof ModelHostFailureError;
+    return {
+        kind: "failed",
+        message,
+        failureKind: classifyPlayFailure(error, canRetry),
+        canRetry,
+        streamingEventId,
+    };
+}
+/**
+ * The ending of an error raised after a response was read or a player message
+ * was written. These failures never grant a retry: Authority may already have
+ * moved past the frozen request.
+ */
+export function settlementFailureEnding(error, fallbackMessage) {
+    return {
+        kind: "failed",
+        message: errorMessage(error, fallbackMessage),
+        failureKind: classifyPlayFailure(error, false),
+        canRetry: false,
+    };
+}
+/** A settled response with no provider-native continuation payload (ADR-0035). */
+export function noContinuationEnding() {
+    return {
+        kind: "failed",
+        message: messages.noContinuation,
+        failureKind: "context_unavailable",
+        canRetry: false,
+    };
+}
+/** A settled response with neither text nor a complete tool call. */
+export function emptyResponseEnding() {
+    return {
+        kind: "failed",
+        message: messages.noOutput,
+        failureKind: "other",
+        canRetry: false,
+    };
+}
+/**
+ * Whether a chain's last ending was the player's cancellation. Every
+ * cancellation ending writes its event last, so the tail identifies it; callers
+ * read the projected flag instead of the event list.
+ */
+export function lastEndingCancelled(session) {
+    return session.events.at(-1)?.kind === "cancellation";
+}
+function applyEnding(session, ending) {
+    switch (ending.kind) {
+        case "ready":
+            if (ending.followupsCancelled === true)
+                session.events.push({
+                    id: session.nextEventId++,
+                    kind: "cancellation",
+                    message: messages.followupsCancelled,
+                });
+            session.status = "ready";
+            session.canRetry = false;
+            session.lastFailure = null;
+            delete session.lastFailureKind;
+            return;
+        case "resumable":
+            session.lastRequest = structuredClone(ending.request);
+            session.lastRequestAttempt = 0;
+            session.status = "interrupted";
+            session.canRetry = true;
+            session.lastFailure =
+                ending.reason === "player_committed"
+                    ? messages.playerCommitted
+                    : messages.toolStepSettled;
+            session.lastFailureKind = "retryable";
+            return;
+        case "cancelled_before_dispatch":
+            interruptStreamingEvent(session, ending.streamingEventId);
+            session.events.push({
+                id: session.nextEventId++,
+                kind: "cancellation",
+                message: messages.cancelledBeforeDispatch,
+            });
+            session.status = "interrupted";
+            session.canRetry = true;
+            session.lastRequest = structuredClone(ending.request);
+            session.lastRequestAttempt = Math.max(0, ending.attempt - 1);
+            session.lastFailure = messages.cancelledBeforeDispatch;
+            delete session.lastFailureKind;
+            return;
+        case "cancelled_after_dispatch":
+            interruptStreamingEvent(session, ending.streamingEventId);
+            session.status = "interrupted";
+            session.canRetry = false;
+            session.lastFailure = ending.message;
+            delete session.lastFailureKind;
+            session.events.push({
+                id: session.nextEventId++,
+                kind: "cancellation",
+                message: ending.message,
+            });
+            return;
+        case "failed":
+            interruptStreamingEvent(session, ending.streamingEventId);
+            session.status = "interrupted";
+            session.canRetry = ending.canRetry;
+            session.lastFailure = ending.message;
+            session.lastFailureKind = ending.failureKind;
+            session.events.push({
+                id: session.nextEventId++,
+                kind: "failure",
+                message: ending.message,
+                failureKind: ending.failureKind,
+            });
+            return;
+    }
+}
+function interruptStreamingEvent(session, eventId) {
+    if (eventId === undefined)
+        return;
+    const event = session.events.find(({ id }) => id === eventId);
+    if (event?.kind === "assistant")
+        event.status = "interrupted";
+}
+function errorMessage(error, fallback) {
+    return error instanceof Error ? error.message : fallback;
+}