narraeon 0.5.7 → 0.6.0

package/dist/node/runtime/content/CurrentTreeContentLibrary.js

@@ -4,6 +4,7 @@ import { readFileSync, unlinkSync } from "node:fs";
 import { link, open, mkdir, readFile, readdir, rename, rm, stat, unlink, } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, posix, win32 } from "node:path";
 import { portableContentTreePathKey } from "../../protocol/contentTree.js";
+import { assertSameGameplayMode, gameplayFile, gameplayPath, readGameplay, } from "../../protocol/gameplay.js";
 import { defaultContentWorkspaceLimits, } from "./ContentLimits.js";
 import { inspectContentPackageCurrentTree, isContentPackageWorldDocumentPath, worldDocumentTextRequirement, } from "./FileNativeContentTree.js";
 const localIdPattern = /^package-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
@@ -228,6 +229,29 @@ export class CurrentTreeContentLibrary {
             }
         });
     }
+    /**
+     * Change only the resolution scheme of a tabletop package. The edit reads the
+     * tree under the same lease as ordinary saves, so it publishes atomically and
+     * follows the same conflict rules.
+     */
+    setGameplayScheme(localId, scheme, options = {}) {
+        return this.#mutate(async () => {
+            const lease = await this.acquireOperationLease(localId, {
+                wait: options.waitForLease !== false,
+            });
+            try {
+                options.signal?.throwIfAborted();
+                const current = lease.package;
+                if (current.gameplay.mode !== "tabletop")
+                    throw new InvalidContentTreeError("Only a tabletop content package has a resolution scheme / 只有跑团内容包有判定方案");
+                const replacement = gameplayFile({ mode: "tabletop", scheme });
+                return await lease.replace(current.files.map((file) => file.path === gameplayPath ? replacement : file), options);
+            }
+            finally {
+                lease.release();
+            }
+        });
+    }
     async acquireOperationLease(localId, options = {}) {
         this.#packageRoot(localId);
         await mkdir(this.#locksRoot, { recursive: true, mode: 0o700 });
@@ -281,6 +305,7 @@ export class CurrentTreeContentLibrary {
                         throw new CurrentTreeContentPackageBusyError();
                     options.signal?.throwIfAborted();
                     const normalized = normalizeCurrentContentTreeFiles(files, this.#limits);
+                    assertGameplayModeUnchanged(package_.files, normalized);
                     return this.#replaceNormalizedCurrentTree(localId, package_.title, normalized, options.signal);
                 },
                 release: () => {
@@ -476,7 +501,7 @@ export class CurrentTreeContentLibrary {
 }
 function detail(localId, title, files, inspection) {
     return {
-        ...summary(localId, title, inspection),
+        ...summary(localId, title, readGameplay(files), inspection),
         files: files.map((file) => ({ ...file })),
         documents: structuredClone(inspection.documents),
         issues: structuredClone(inspection.issues),
@@ -484,8 +509,9 @@ function detail(localId, title, files, inspection) {
         control: structuredClone(inspection.control),
     };
 }
-function summary(localId, title, inspection) {
+function summary(localId, title, gameplay, inspection) {
     return {
+        gameplay: { ...gameplay },
         localId,
         title,
         status: inspection.status,
@@ -495,6 +521,7 @@ function summary(localId, title, inspection) {
 }
 function packageSummary(package_) {
     return {
+        gameplay: { ...package_.gameplay },
         localId: package_.localId,
         title: package_.title,
         status: package_.status,
@@ -547,8 +574,22 @@ export function normalizeCurrentContentTreeFiles(files, limits = defaultLimits)
             ...(file.encoding === undefined ? {} : { encoding: file.encoding }),
         });
     }
+    try {
+        readGameplay(normalized);
+    }
+    catch (error) {
+        throw new InvalidContentTreeError(error instanceof Error ? error.message : "Invalid gameplay identity");
+    }
     return normalized.sort((left, right) => compareStrings(left.path, right.path));
 }
+function assertGameplayModeUnchanged(before, after) {
+    try {
+        assertSameGameplayMode(before, after);
+    }
+    catch (error) {
+        throw new InvalidContentTreeError(error instanceof Error ? error.message : "Gameplay mode is fixed");
+    }
+}
 function decodeCanonicalBase64(contents, path) {
     if (contents.length % 4 !== 0 ||
         !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(contents)) {

package/dist/node/runtime/content/FileNativeContentTree.js

@@ -1,3 +1,4 @@
+import { gameplayPath, readGameplay } from "../../protocol/gameplay.js";
 import { readPackageFollowups } from "./PackageFollowups.js";
 import { parseDocument } from "yaml";
 import { WorldDocumentStore, } from "../world/WorldDocumentStore.js";
@@ -45,7 +46,7 @@ export function inspectContentPackageCurrentTree(files, options = {}) {
     }
     const unsupportedPaths = new Set();
     for (const file of snapshotFiles) {
-        if (/\.json$/iu.test(file.path)) {
+        if (/\.json$/iu.test(file.path) && file.path !== gameplayPath) {
             unsupportedPaths.add(file.path);
             issue(issues, "unsupported_content_file", file.path, "The current content package does not accept manifest, seven-field JSON, schema, record, or revision files");
         }
@@ -116,6 +117,12 @@ export function inspectContentPackageCurrentTree(files, options = {}) {
                 issue(issues, "invalid_player_view", "control/player-views.yaml", `${formatProblems.length - maxReportedPlayerViewProblems} more player-view issues were omitted`);
         }
     }
+    try {
+        readGameplay(snapshotFiles);
+    }
+    catch (error) {
+        issue(issues, "invalid_gameplay", gameplayPath, error instanceof Error ? error.message : "Invalid gameplay");
+    }
     try {
         readPackageFollowups(snapshotFiles);
     }

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

@@ -1,5 +1,5 @@
 import { isNarrativeOrigin, isHistoryBackground, } from "../history/HistoryBackground.js";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomBytes, 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";
@@ -57,6 +57,33 @@ export class FileNativePlayAdvanceStore {
             recordedAt: durableBase.createdAt,
         });
     }
+    /**
+     * Return the advance's secret resolution seed, creating it on first need.
+     * Recovery reads the same fact, so every tool call in the advance draws from
+     * one persisted stream and a crashed batch cannot resample.
+     */
+    async resolutionSeed(base) {
+        const durableBase = await this.#assertCurrent(base);
+        const path = this.#factPath(base, "resolution-seed.json");
+        if ((await readOptionalJson(path)) === null) {
+            try {
+                await publishImmutableJson(path, {
+                    schemaVersion: 1,
+                    stage: "resolution_seed",
+                    seed: randomBytes(32).toString("hex"),
+                    recordedAt: durableBase.createdAt,
+                });
+            }
+            catch (error) {
+                // A concurrent writer may have published first; the stored fact wins.
+                if ((await readOptionalJson(path)) === null)
+                    throw error;
+            }
+        }
+        const fact = await readJson(path);
+        assertResolutionSeedFact(fact);
+        return fact.seed;
+    }
     async markSettled(base, head) {
         const durableBase = await this.#assertCurrent(base);
         await publishImmutableJson(this.#factPath(base, "settled.json"), {
@@ -115,6 +142,15 @@ function sameAdvanceBase(left, right) {
     void rightCreatedAt;
     return isDeepStrictEqual(leftIdentity, rightIdentity);
 }
+function assertResolutionSeedFact(value) {
+    if (!isRecord(value) ||
+        value.schemaVersion !== 1 ||
+        value.stage !== "resolution_seed" ||
+        typeof value.seed !== "string" ||
+        !/^[a-f0-9]{64}$/.test(value.seed) ||
+        typeof value.recordedAt !== "number")
+        throw new Error("Invalid persisted resolution seed");
+}
 function assertBase(value) {
     if (!isRecord(value) ||
         value.schemaVersion !== 1 ||

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

@@ -3,7 +3,7 @@ export { validatePlayPresetArtifactPayload } from "../../shared/artifact-payload
 import { defaultFollowupItems, } from "../../shared/ordered-followups.js";
 import { parseFollowupItems } from "./OrderedFollowups.js";
 import { builtinAuthorPrompts, defaultOrderedAuthorPrompts, } from "../../shared/ordered-author-prompts.js";
-import { parseOrderedPlayPrompts, migrateLegacyPlayPrompts, } from "./OrderedPlayPrompts.js";
+import { parseOrderedPlayPrompts, migrateLegacyPlayPrompts, withTabletopPromptBuiltins, } from "./OrderedPlayPrompts.js";
 import { defaultOrderedPlayPrompts, } from "../../shared/ordered-play-prompts.js";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
@@ -203,12 +203,17 @@ export class FileNativePlayPresetStore {
         };
         this.#locale = options.locale ?? (() => defaultAppLocale);
     }
+    /**
+     * Startup is the only place that upgrades stored presets. Reads never write:
+     * list, bind and freeze observe the library as it was last saved.
+     */
     async initialize() {
         await this.#change(async () => {
             const document = await this.#read();
             const migrated = this.#markLegacyBuiltinDefault(document);
             const synchronized = this.#synchronizeBuiltinDefault(document);
-            if (migrated || synchronized)
+            const tabletop = this.#migrateTabletopPromptBuiltins(document);
+            if (migrated || synchronized || tabletop)
                 await this.#write(document);
         });
     }
@@ -452,7 +457,8 @@ export class FileNativePlayPresetStore {
             .map((path) => ({ path, contents: binding.files[path] }));
     }
     async importPortable(input) {
-        const files = toFileMap(input.files, this.#limits);
+        // A released preset gains the tabletop builtins at import, as at upgrade.
+        const files = withTabletopPromptBuiltins(toFileMap(input.files, this.#limits));
         const parsed = parsePlayPresetFiles(files, this.#limits);
         if (parsed.kind === "invalid")
             throw parsed.error;
@@ -561,6 +567,45 @@ export class FileNativePlayPresetStore {
         preset.builtinDefault = true;
         return true;
     }
+    /**
+     * One-time upgrade for ordered presets saved before the tabletop builtins
+     * existed. An affected revision is replaced by a new revision that inserts
+     * them; the old revision stays for frozen requests. A pending draft gets the
+     * same insertion, because a draft that kept the old list would fail the
+     * builtin-retention rule on save. The library is one atomically written file,
+     * so an interrupted upgrade leaves the released bytes and reruns cleanly.
+     */
+    #migrateTabletopPromptBuiltins(document) {
+        let changed = false;
+        for (const stored of document.presets) {
+            const current = stored.revisions[stored.currentRevision];
+            if (current !== undefined) {
+                const migrated = withTabletopPromptBuiltins(current);
+                if (migrated !== current) {
+                    const revision = revisionForFiles(migrated, this.#limits);
+                    stored.revisions[revision] = cloneFiles(migrated);
+                    stored.currentRevision = revision;
+                    changed = true;
+                }
+            }
+            const draft = stored.draftRevision === undefined
+                ? undefined
+                : stored.revisions[stored.draftRevision];
+            if (draft !== undefined) {
+                const migrated = withTabletopPromptBuiltins(draft);
+                if (migrated !== draft) {
+                    const revision = revisionForFiles(migrated, this.#limits);
+                    stored.revisions[revision] = cloneFiles(migrated);
+                    if (revision === stored.currentRevision)
+                        delete stored.draftRevision;
+                    else
+                        stored.draftRevision = revision;
+                    changed = true;
+                }
+            }
+        }
+        return changed;
+    }
     #synchronizeBuiltinDefault(document) {
         const preset = document.presets.find(({ builtinDefault }) => builtinDefault === true);
         if (preset === undefined || preset.draftRevision !== undefined)

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

@@ -1,3 +1,4 @@
+import { isResolutionReceipt } from "../../protocol/resolution.js";
 import { legacyModelBindingFailure, projectLegacyModelBindingFailure, } from "./LegacyModelBindingFailure.js";
 import { isPlayFailureKind, } from "../../protocol/playFailure.js";
 import { isNarrativeOrigin, } from "../history/HistoryBackground.js";
@@ -1028,6 +1029,9 @@ function assertPlayEvent(value) {
         return;
     }
     if (value.kind === "tool_result") {
+        if (value.resolution !== undefined &&
+            !isResolutionReceipt(value.resolution))
+            throw new Error("Invalid resolution receipt");
         if (typeof value.callId !== "string" ||
             typeof value.name !== "string" ||
             typeof value.ok !== "boolean" ||
@@ -1091,6 +1095,9 @@ function assertTimelineEventSummary(value) {
         return;
     }
     if (value.kind === "tool_result") {
+        if (value.resolution !== undefined &&
+            !isResolutionReceipt(value.resolution))
+            throw new Error("Invalid resolution receipt");
         if (typeof value.callId !== "string" ||
             typeof value.name !== "string" ||
             typeof value.ok !== "boolean" ||

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

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { parseDocument } from "yaml";
+import { isMap, isSeq, parseDocument } from "yaml";
 import { builtinPlayPrompts, isPromptMessageRole, } from "../../shared/ordered-play-prompts.js";
 /** The same strict permission gate is used by portable imports and structured saves. */
 export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"), worldRequired = true) {
@@ -24,20 +24,23 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
             !isPromptMessageRole(item.messageRole))
             return fail();
         const messageRole = item.messageRole === undefined ? {} : { messageRole: item.messageRole };
-        const exact = (keys) => Object.keys(item).length ===
-            keys.length + (item.messageRole === undefined ? 0 : 1) &&
-            keys.every((key) => Object.hasOwn(item, key));
+        const exact = (keys, optional = []) => Object.keys(item).every((key) => keys.includes(key) ||
+            optional.includes(key) ||
+            key === "messageRole" ||
+            key === "id" ||
+            key === "kind") && keys.every((key) => Object.hasOwn(item, key));
         if (item.kind === "world" && exact(["id", "kind"])) {
             worlds++;
             return { id: item.id, kind: "world", ...messageRole };
         }
         if (item.kind === "user" &&
-            exact(["id", "kind", "name", "enabled", "body"]) &&
+            exact(["id", "kind", "name", "enabled", "body"], ["gameplay"]) &&
             typeof item.name === "string" &&
             item.name.trim().length > 0 &&
             /^[^\r\n\0]{1,160}$/u.test(item.name) &&
             typeof item.body === "string" &&
-            typeof item.enabled === "boolean")
+            typeof item.enabled === "boolean" &&
+            (item.gameplay === undefined || item.gameplay === "tabletop"))
             return {
                 id: item.id,
                 kind: "user",
@@ -45,6 +48,9 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
                 enabled: item.enabled,
                 body: item.body,
                 ...messageRole,
+                ...(item.gameplay === "tabletop"
+                    ? { gameplay: "tabletop" }
+                    : {}),
             };
         const builtin = catalog.find((entry) => entry.id === item.builtin);
         if (item.kind !== "builtin" ||
@@ -70,6 +76,54 @@ export function parseOrderedPlayPrompts(value, catalog = builtinPlayPrompts("en"
         return fail();
     return entries;
 }
+/**
+ * Insert the tabletop builtins that an ordered preset does not list yet.
+ * play.tabletop goes just before the world placeholder and author.tabletop just
+ * after author.guidance. Files that are not ordered v2 or do not parse come back
+ * unchanged, and nothing else in them is rewritten. The same object is returned
+ * when nothing needs inserting, so callers can detect a change by identity.
+ */
+export function withTabletopPromptBuiltins(files) {
+    const source = files["preset.yaml"];
+    if (source === undefined)
+        return files;
+    const document = parseDocument(source, { uniqueKeys: true });
+    if (document.errors.length > 0 ||
+        document.warnings.length > 0 ||
+        !isMap(document.contents) ||
+        document.get("format") !== "narraeon.play-preset/v2")
+        return files;
+    let changed = false;
+    const playPrompts = document.get("playPrompts", true);
+    if (isSeq(playPrompts) && !hasEntry(playPrompts, "play.tabletop")) {
+        const world = playPrompts.items.findIndex((item) => entryField(item, "kind") === "world");
+        playPrompts.items.splice(world < 0 ? playPrompts.items.length : world, 0, document.createNode({
+            id: "play.tabletop",
+            kind: "builtin",
+            builtin: "play.tabletop",
+            enabled: true,
+        }));
+        changed = true;
+    }
+    const authorPrompts = document.get("authorPrompts", true);
+    if (isSeq(authorPrompts) && !hasEntry(authorPrompts, "author.tabletop")) {
+        const guidance = authorPrompts.items.findIndex((item) => entryField(item, "id") === "author.guidance");
+        authorPrompts.items.splice(guidance < 0 ? authorPrompts.items.length : guidance + 1, 0, document.createNode({
+            id: "author.tabletop",
+            kind: "builtin",
+            builtin: "author.tabletop",
+            enabled: true,
+        }));
+        changed = true;
+    }
+    return changed ? { ...files, "preset.yaml": document.toString() } : files;
+}
+function hasEntry(sequence, id) {
+    return sequence.items.some((item) => entryField(item, "id") === id);
+}
+function entryField(item, key) {
+    return isMap(item) ? item.get(key) : undefined;
+}
 /** Recognized v1 content becomes user text, never a locked builtin inferred from a path. */
 export function migrateLegacyPlayPrompts(files, narrative, excludedPaths = []) {
     const document = parseDocument(files["frame.yaml"] ?? "", {
@@ -185,5 +239,13 @@ export function migrateLegacyPlayPrompts(files, narrative, excludedPaths = []) {
         if ((path.startsWith("blocks/") || path.startsWith("prompts/")) &&
             path.endsWith(".md"))
             add(path, false);
+    // The tabletop builtin joins converted presets just before the world placeholder.
+    const worldIndex = entries.findIndex((entry) => entry.kind === "world");
+    entries.splice(worldIndex, 0, {
+        id: "play.tabletop",
+        kind: "builtin",
+        builtin: "play.tabletop",
+        enabled: true,
+    });
     return entries;
 }

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

@@ -1,5 +1,6 @@
 import { projectLegacyModelBindingFailure } from "./LegacyModelBindingFailure.js";
 import { classifyPlayFailure } from "./PlayFailure.js";
+import { isResolutionTool, resolutionMarkdown, resolutionToolNames, resolveTabletop, seededRandom, } from "./TabletopResolution.js";
 import { captureNarrativeOrigin, snapshotBackground, narrativeBackground, } from "../history/HistoryBackground.js";
 import { isDeepStrictEqual } from "node:util";
 import { hasLegacyHistoryTools } from "../prompt/FileNativeToolRegistry.js";
@@ -18,6 +19,7 @@ import { parsePlayPresetFiles, } from "./FileNativePlayPresetStore.js";
 import { runPlayFollowupRequests, } from "./PlayFollowupRequests.js";
 import { FileNativePlayDocuments, fingerprintControl, } from "./PlayDocumentTools.js";
 const callChainToolNames = new Set([
+    ...resolutionToolNames,
     "state_list",
     "history_list",
     "history_search",
@@ -660,10 +662,15 @@ export class PlayCallChain {
         const timelineGeneration = playerRevisionTimelineGeneration(input.source.timelineGeneration, request.operationId, request.worldId, request.continuation);
         const requestFingerprint = playerRevisionRequestFingerprint(request, input.selectedEvent.committedHead, restoresHead);
         const traceRetention = preparePlayerRevisionTrace(sourceContext, input.selectedEventIndex);
+        // A timeline revision appends on the current audit head and restores the
+        // selected message's logical parent, so a chain that lags the world (an
+        // out-of-story world revision, or an earlier revision whose chain was not
+        // published) must not block it. The commit still rechecks this head under
+        // the world lock.
         const outcome = await this.#worlds.reviseTimeline({
             operationId: request.operationId,
             worldId: request.worldId,
-            expectedCurrentHead: input.source.parentHead,
+            expectedCurrentHead: await this.#worlds.currentHead(request.worldId),
             restoresHead,
             replacesHead: input.selectedEvent.committedHead,
             replacementText: request.replacementText,
@@ -1152,8 +1159,15 @@ export class PlayCallChain {
         const prepared = [];
         const trailingEvents = [];
         let nextEventId = advance.eventId + 1;
+        // One persisted seed per advance: every resolution call draws from it by
+        // call identity, so recovery reproduces the same receipts.
+        const resolutionSeed = calls.some(({ name }) => isResolutionTool(name))
+            ? await this.#worlds.playAdvances.resolutionSeed(advance)
+            : undefined;
         for (const call of calls) {
-            const item = prepareTool(session, workingTools, advance.exchange, call, this.#compiler.locale);
+            const item = prepareTool(session, workingTools, advance.exchange, call, this.#compiler.locale, resolutionSeed);
+            if (item.result.resolution !== undefined)
+                crashAtPlayAdvanceEdge("after_resolution");
             prepared.push(item);
             trailingEvents.push({
                 id: nextEventId++,
@@ -2068,7 +2082,7 @@ function appendCommittedHistory(session, head, messages) {
         });
     }
 }
-function prepareTool(session, working, exchange, call, locale) {
+function prepareTool(session, working, exchange, call, locale, resolutionSeed) {
     const key = `${exchange}:${call.id}`;
     const signature = JSON.stringify(call.arguments);
     const completed = working.get(key);
@@ -2095,8 +2109,9 @@ function prepareTool(session, working, exchange, call, locale) {
     }
     else {
         try {
-            result =
-                call.name === "world_checkpoint"
+            result = isResolutionTool(call.name)
+                ? resolutionToolResult(call.name, call.arguments, resolutionSeed, key, locale)
+                : call.name === "world_checkpoint"
                     ? typeof call.arguments === "object" &&
                         call.arguments !== null &&
                         !Array.isArray(call.arguments) &&
@@ -2139,6 +2154,9 @@ function prepareTool(session, working, exchange, call, locale) {
         name: call.name,
         ok: result.ok,
         markdown: result.markdown,
+        ...(result.resolution === undefined
+            ? {}
+            : { resolution: structuredClone(result.resolution) }),
         replayed,
     };
     return {
@@ -2409,6 +2427,16 @@ function notifyAssistantDelta(observer, delta) {
         // Like snapshot projection, the Provider exchange outlives its browser stream.
     }
 }
+function resolutionToolResult(name, args, seed, identity, locale) {
+    if (seed === undefined)
+        throw new Error("The resolution seed for this advance is unavailable.");
+    const resolution = resolveTabletop(name, args, seededRandom(seed, identity));
+    return {
+        ok: true,
+        markdown: resolutionMarkdown(resolution, locale),
+        resolution,
+    };
+}
 function crashAtPlayAdvanceEdge(edge) {
     if (process.env.NODE_ENV === "test" &&
         process.env.NARRAEON_INTERNAL_TEST_CRASH_AT_PLAY_ADVANCE_EDGE === edge)