narraeon 0.3.1 → 0.5.0

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

@@ -1,3 +1,4 @@
+import { encodePlayPromptRun, decodePlayPromptRun, } from "./PlayPromptRun.js";
 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";
@@ -52,6 +53,10 @@ export class FileNativePlayTimelineStore {
     async persist(value, cursor) {
         return this.#persistAtRuntimeRoot(this.#worldRuntimeRoot(value.worldId), value, cursor);
     }
+    /** Write a sealed context segment without making it the active timeline. */
+    async persistDetached(value, cursor) {
+        return this.#persistAtRuntimeRoot(this.#worldRuntimeRoot(value.worldId), value, cursor, false);
+    }
     async persistStaged(targetWorldRoot, value, cursor) {
         return this.#persistAtRuntimeRoot(join(resolve(targetWorldRoot), "runtime"), value, cursor);
     }
@@ -65,6 +70,16 @@ export class FileNativePlayTimelineStore {
         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 ?? []);
+        if (input.target.events.some((event) => event.kind === "assistant" && event.status === "completed")) {
+            const encoding = await this.readInitialEncoding(input.sourceWorldId, input.source.chainId).catch(() => null);
+            if (encoding !== null)
+                await publishImmutableJson(join(targetRoot, "initial-request-encoding.json"), encoding);
+        }
+        for (const run of input.target.promptRuns ?? []) {
+            const encoding = await this.readInitialEncoding(input.sourceWorldId, input.source.chainId, run.exchange).catch(() => null);
+            if (encoding !== null)
+                await publishImmutableJson(join(targetRoot, `request-encoding-${run.exchange}.json`), encoding);
+        }
         await Promise.all([
             cloneNumberedPrefix({
                 sourceRoot,
@@ -109,7 +124,7 @@ export class FileNativePlayTimelineStore {
             authorizationCheckpointCount,
         });
     }
-    async #persistAtRuntimeRoot(runtimeRoot, value, cursor) {
+    async #persistAtRuntimeRoot(runtimeRoot, value, cursor, publishHead = true) {
         assertIdentity(value.worldId, "World ID");
         assertIdentity(value.chainId, "Call-chain ID");
         const root = join(runtimeRoot, "play-contexts", createHash("sha256").update(value.chainId).digest("hex"));
@@ -125,6 +140,9 @@ export class FileNativePlayTimelineStore {
             await publishImmutableJson(join(root, "base.json"), base);
         else if (!isDeepStrictEqual(existingBase, base))
             throw new Error("A play context identity is bound to different frozen data");
+        await publishImmutableJson(join(root, "reply-context.json"), {
+            contextId: value.continuityContextId ?? value.chainId,
+        });
         const supplied = cursor ?? emptyPersistenceCursor();
         // Recovery may replace the unresolved tail (for example, a generic crash
         // failure becomes the already-returned Provider response). Numbered files
@@ -164,6 +182,10 @@ export class FileNativePlayTimelineStore {
         const checkpoints = value.documentAuthorizationCheckpoints ?? [];
         for (let index = previous.authorizationCheckpointCount; index < checkpoints.length; index += 1)
             await publishImmutableJson(join(root, "authorization", numbered(index + 1)), checkpoints[index]);
+        const promptRuns = value.promptRuns ?? [];
+        for (let index = supplied.promptRunCount ?? 0; index < promptRuns.length; index += 1) {
+            await publishImmutableJson(join(root, "prompt-runs", numbered(index + 1)), encodePlayPromptRun(promptRuns[index]));
+        }
         const state = {
             schemaVersion: 3,
             chainId: value.chainId,
@@ -174,6 +196,7 @@ export class FileNativePlayTimelineStore {
             transcriptCount: value.transcript.length,
             completedToolCount: value.completedTools.length,
             authorizationCheckpointCount: checkpoints.length,
+            promptRunCount: promptRuns.length,
             changedDocuments: structuredClone(value.changedDocuments),
             nextEventId: value.nextEventId,
             exchange: value.exchange,
@@ -183,17 +206,19 @@ export class FileNativePlayTimelineStore {
             updatedAt: value.updatedAt,
         };
         await publishJson(join(root, "state.json"), state);
-        await publishJson(join(runtimeRoot, "play-timeline-head.json"), {
-            schemaVersion: 3,
-            worldId: value.worldId,
-            chainId: value.chainId,
-            generation: value.timelineGeneration,
-        });
+        if (publishHead)
+            await publishJson(join(runtimeRoot, "play-timeline-head.json"), {
+                schemaVersion: 3,
+                worldId: value.worldId,
+                chainId: value.chainId,
+                generation: value.timelineGeneration,
+            });
         return {
             eventCount: value.events.length,
             transcriptCount: value.transcript.length,
             completedToolCount: value.completedTools.length,
             authorizationCheckpointCount: checkpoints.length,
+            promptRunCount: promptRuns.length,
         };
     }
     async readCurrent(worldId) {
@@ -213,13 +238,14 @@ export class FileNativePlayTimelineStore {
         if (metadata === null)
             return null;
         const { index: indexValue, state: stateValue, root } = metadata;
-        const [baseValue, continuationValue, transcript, rawEvents, completedTools, checkpoints,] = await Promise.all([
+        const [baseValue, continuationValue, transcript, rawEvents, completedTools, checkpoints, promptRuns,] = await Promise.all([
             readJson(join(root, "base.json")),
             readJson(join(root, "continuations", `${stateValue.continuationDigest}.json`)),
             readNumbered(join(root, "transcript"), stateValue.transcriptCount),
             readNumberedValidated(join(root, "events"), stateValue.eventCount, assertPlayEvent),
             readNumbered(join(root, "completed-tools"), stateValue.completedToolCount),
             readNumbered(join(root, "authorization"), stateValue.authorizationCheckpointCount),
+            readNumbered(join(root, "prompt-runs"), stateValue.promptRunCount ?? 0).then((records) => records.map(decodePlayPromptRun)),
         ]);
         const events = rawEvents.map(normalizePlayEvent);
         assertContextBase(baseValue);
@@ -247,6 +273,12 @@ export class FileNativePlayTimelineStore {
             chainId,
             previousChainId: indexValue.previousChainId,
             timelineGeneration: indexValue.timelineGeneration,
+            ...(baseValue.continuityContextId === undefined
+                ? {}
+                : { continuityContextId: baseValue.continuityContextId }),
+            ...(baseValue.presetFiles === undefined
+                ? {}
+                : { presetFiles: structuredClone(baseValue.presetFiles) }),
             baselineHead: baseValue.baselineHead,
             parentHead: stateValue.parentHead,
             ...(baseValue.baselineHistoryLength === undefined
@@ -278,6 +310,7 @@ export class FileNativePlayTimelineStore {
             events,
             completedTools,
             documentAuthorizationCheckpoints: checkpoints,
+            promptRuns,
             changedDocuments: structuredClone(stateValue.changedDocuments),
             nextMaterials: structuredClone(continuationValue.nextMaterials),
             nextEventId: stateValue.nextEventId,
@@ -294,9 +327,33 @@ export class FileNativePlayTimelineStore {
                 transcriptCount: stateValue.transcriptCount,
                 completedToolCount: stateValue.completedToolCount,
                 authorizationCheckpointCount: stateValue.authorizationCheckpointCount,
+                promptRunCount: stateValue.promptRunCount ?? 0,
             },
         };
     }
+    /** The first dispatched request encoding is diagnostic evidence, not Authority. */
+    async recordInitialEncoding(worldId, chainId, encoding, exchange = 1) {
+        const path = join(this.#contextRoot(worldId, chainId), exchange === 1
+            ? "initial-request-encoding.json"
+            : `request-encoding-${exchange}.json`);
+        await publishImmutableJson(path, encoding);
+    }
+    async readInitialEncoding(worldId, chainId, exchange = 1) {
+        const value = await readOptionalJson(join(this.#contextRoot(worldId, chainId), exchange === 1
+            ? "initial-request-encoding.json"
+            : `request-encoding-${exchange}.json`));
+        if (value === null)
+            return null;
+        if (!isRecord(value) ||
+            value.method !== "POST" ||
+            !["chat_completions", "openai_responses", "anthropic_messages"].includes(String(value.provider)) ||
+            !isRecord(value.body) ||
+            typeof value.endpointPath !== "string" ||
+            !Array.isArray(value.headerNames) ||
+            !value.headerNames.every((name) => typeof name === "string"))
+            throw new Error("Initial request encoding has an invalid shape");
+        return value;
+    }
     async readAllContexts(worldId) {
         const current = await this.readCurrent(worldId);
         if (current === null)
@@ -312,6 +369,40 @@ export class FileNativePlayTimelineStore {
         }
         return reverse.reverse();
     }
+    /** Resolve only requested reply summaries; decoration reads never load Provider transcripts. */
+    async resolveReplies(worldId, targets) {
+        if (targets.length === 0)
+            return [];
+        const result = [];
+        let chainId = (await this.#readTimelineHead(worldId))?.chainId ?? null;
+        while (chainId !== null) {
+            const metadata = await this.#readContextMetadata(worldId, chainId);
+            if (metadata === null)
+                throw new Error("Play timeline points to a missing context");
+            const identity = await readOptionalJson(join(metadata.root, "reply-context.json"));
+            if (identity !== null &&
+                (!isRecord(identity) || typeof identity.contextId !== "string"))
+                throw new Error("Play reply context identity is invalid");
+            const contextId = identity === null
+                ? null
+                : identity.contextId;
+            for (const target of targets.filter((item) => item.contextId === contextId &&
+                item.eventId <= metadata.state.eventCount)) {
+                const event = await readJson(join(metadata.root, "summaries", numbered(target.eventId)));
+                assertTimelineEventSummary(event);
+                if (event.id === target.eventId &&
+                    event.kind === "assistant" &&
+                    event.committedHead === target.head)
+                    result.push({ ...target, chainId });
+            }
+            if (targets.every((target) => result.some((item) => item.contextId === target.contextId &&
+                item.eventId === target.eventId &&
+                item.head === target.head)))
+                break;
+            chainId = metadata.index.previousChainId;
+        }
+        return result;
+    }
     async readPage(worldId, limit, cursor) {
         assertIdentity(worldId, "World ID");
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
@@ -517,6 +608,12 @@ function contextBase(value) {
         kind: "play_context_frozen",
         worldId: value.worldId,
         chainId: value.chainId,
+        ...(value.continuityContextId === undefined
+            ? {}
+            : { continuityContextId: value.continuityContextId }),
+        ...(value.presetFiles === undefined
+            ? {}
+            : { presetFiles: structuredClone(value.presetFiles) }),
         baselineHead: value.baselineHead,
         ...(value.baselineHistoryLength === undefined
             ? {}
@@ -633,6 +730,9 @@ function assertContextBase(value) {
         typeof value.worldId !== "string" ||
         typeof value.chainId !== "string" ||
         typeof value.baselineHead !== "string" ||
+        (value.continuityContextId !== undefined &&
+            (typeof value.continuityContextId !== "string" ||
+                value.continuityContextId.length === 0)) ||
         (value.modelBinding !== undefined &&
             !validModelHostBinding(value.modelBinding)) ||
         !isRecord(value.bootstrap) ||
@@ -652,6 +752,7 @@ function assertContextState(value) {
         !validCount(value.transcriptCount) ||
         !validCount(value.completedToolCount) ||
         !validCount(value.authorizationCheckpointCount) ||
+        (value.promptRunCount !== undefined && !validCount(value.promptRunCount)) ||
         !Array.isArray(value.changedDocuments) ||
         !validCount(value.nextEventId) ||
         !validCount(value.exchange) ||
@@ -697,6 +798,9 @@ function isReleasedPlayContext(value) {
         return false;
     if (typeof value.chainId !== "string" ||
         typeof value.baselineHead !== "string" ||
+        (value.continuityContextId !== undefined &&
+            (typeof value.continuityContextId !== "string" ||
+                value.continuityContextId.length === 0)) ||
         (value.baselineHistoryLength !== undefined &&
             !validCount(value.baselineHistoryLength)) ||
         typeof value.parentHead !== "string" ||
@@ -918,7 +1022,12 @@ function assertTimelineEventSummary(value) {
         throw new Error("Follow-up timeline summary has an invalid shape");
 }
 function validAssistantEventCore(value) {
-    return (typeof value.text === "string" &&
+    return ((value.checkpoint === undefined ||
+        (value.checkpoint === true &&
+            value.status === "completed" &&
+            value.responseKind === "narrative" &&
+            typeof value.committedHead === "string")) &&
+        typeof value.text === "string" &&
         (value.status === "streaming" ||
             value.status === "completed" ||
             value.status === "interrupted") &&

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

@@ -0,0 +1,71 @@
+import { readPackageFollowups, packageFollowupResources, } from "../content/PackageFollowups.js";
+import { builtinFollowupExample, defaultFollowupItems, } from "../../shared/ordered-followups.js";
+/** Strict portable permissions, shared by import and structured saves. */
+export function parseFollowupItems(value, definitions) {
+    if (!Array.isArray(value))
+        throw new Error("Follow-up order must be an array");
+    const items = value.map((raw) => {
+        if (typeof raw !== "object" ||
+            raw === null ||
+            !("id" in raw) ||
+            !("kind" in raw) ||
+            !("enabled" in raw) ||
+            Object.keys(raw).some((key) => !["id", "kind", "enabled"].includes(key)) ||
+            typeof raw.id !== "string" ||
+            typeof raw.enabled !== "boolean" ||
+            !["user", "builtin", "content-package"].includes(String(raw.kind)))
+            throw new Error("Invalid follow-up reference; system content is read-only");
+        return {
+            id: raw.id,
+            kind: raw.kind,
+            enabled: raw.enabled,
+        };
+    });
+    if (new Set(items.map((item) => item.id)).size !== items.length ||
+        items.filter((item) => item.kind === "builtin").length !== 1 ||
+        !items.some((item) => item.kind === "builtin" && item.id === "builtin:summary") ||
+        items.filter((item) => item.kind === "content-package").length !== 1 ||
+        !items.some((item) => item.kind === "content-package" && item.id === "package:followups") ||
+        items.filter((item) => item.kind === "user").length !==
+            definitions.length ||
+        definitions.some((def) => !items.some((item) => item.kind === "user" && item.id === def.id)))
+        throw new Error("Follow-up order must contain every user request, the read-only system example and content-package group exactly once");
+    return items;
+}
+/** Resolve each source against its own files, before requests become immutable snapshots. */
+export function effectiveFollowupDefinitions(definition, locale, worldFiles = [], enabled) {
+    const packageSource = readPackageFollowups(worldFiles);
+    return (definition.followupItems ?? defaultFollowupItems(definition.followups)).flatMap((item) => {
+        if (!(item.kind === "content-package"
+            ? (enabled?.packageGroup ?? item.enabled)
+            : (enabled?.requests.get(item.id) ?? item.enabled)))
+            return [];
+        if (item.kind === "content-package")
+            return packageSource.followups
+                .filter((item) => enabled?.requests.get(`package:${item.definition.id}`) ??
+                item.enabled)
+                .map(({ definition: entry, mount }) => {
+                return {
+                    definition: {
+                        ...entry,
+                        id: `package:${entry.id}`,
+                        artifacts: entry.artifacts.map((artifact) => ({
+                            ...artifact,
+                            channel: `package:${artifact.channel}`,
+                        })),
+                    },
+                    body: packageSource.files[entry.prompt.path],
+                    frozenResources: {
+                        files: packageFollowupResources(entry, packageSource.files),
+                        mount,
+                    },
+                };
+            });
+        if (item.kind === "builtin")
+            return [builtinFollowupExample(locale)];
+        const entry = definition.followups.find((entry) => entry.id === item.id);
+        if (entry === undefined)
+            throw new Error(`Missing follow-up definition: ${item.id}`);
+        return [{ definition: entry, body: definition.files[entry.prompt.path] }];
+    });
+}

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

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { parseDocument } from "yaml";
+import { builtinPlayPrompts, } 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) {
+    const fail = () => {
+        throw new Error("Invalid ordered play prompts: unique identities, current builtins, enabled mechanics and one world placeholder are required");
+    };
+    if (!Array.isArray(value) || value.length > 256)
+        return fail();
+    const ids = new Set();
+    const builtins = new Set();
+    let worlds = 0;
+    const entries = value.map((raw) => {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return fail();
+        const item = raw;
+        if (typeof item.id !== "string" ||
+            !/^[a-zA-Z0-9._-]{1,128}$/u.test(item.id) ||
+            ids.has(item.id))
+            return fail();
+        ids.add(item.id);
+        const exact = (keys) => Object.keys(item).length === keys.length &&
+            keys.every((key) => Object.hasOwn(item, key));
+        if (item.kind === "world" && exact(["id", "kind"])) {
+            worlds++;
+            return { id: item.id, kind: "world" };
+        }
+        if (item.kind === "user" &&
+            exact(["id", "kind", "name", "enabled", "body"]) &&
+            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")
+            return {
+                id: item.id,
+                kind: "user",
+                name: item.name,
+                enabled: item.enabled,
+                body: item.body,
+            };
+        const builtin = catalog.find((entry) => entry.id === item.builtin);
+        if (item.kind !== "builtin" ||
+            !exact(["id", "kind", "builtin", "enabled"]) ||
+            !builtin ||
+            builtins.has(builtin.id) ||
+            typeof item.enabled !== "boolean" ||
+            (builtin.required && !item.enabled))
+            return fail();
+        builtins.add(builtin.id);
+        return {
+            id: item.id,
+            kind: "builtin",
+            builtin: builtin.id,
+            enabled: item.enabled,
+        };
+    });
+    if (worlds !== (worldRequired ? 1 : 0) ||
+        catalog.some((item) => item.required && !builtins.has(item.id)))
+        return fail();
+    return entries;
+}
+/** 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"] ?? "", {
+        uniqueKeys: true,
+        strict: true,
+    });
+    const frame = document.toJS({ maxAliasCount: 0 });
+    const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+    const roles = ["runtime_system", "author_instruction", "world_context"];
+    if (document.errors.length ||
+        document.warnings.length ||
+        !record(frame) ||
+        frame.format !== "narraeon.host-frame/v1" ||
+        !record(frame.roles) ||
+        Object.keys(frame.roles).length !== 3)
+        throw new Error("Legacy host frame is invalid; repair it before migrating");
+    const items = {};
+    const runtime = new Set();
+    let worldInstructions = 0;
+    let worldContext = 0;
+    let coverage = 0;
+    for (const role of roles) {
+        items[role] = [];
+        const roleItems = frame.roles[role];
+        if (!Array.isArray(roleItems))
+            throw new Error("Legacy host role must be an array");
+        for (const item of roleItems) {
+            if (!record(item) || Object.keys(item).length !== 1)
+                throw new Error("Legacy host entry is invalid");
+            if (role === "author_instruction" && typeof item.markdown === "string")
+                items[role].push({ markdown: item.markdown });
+            else if (role === "author_instruction" &&
+                item.include === "world.instructions") {
+                worldInstructions++;
+                items[role].push({ include: item.include });
+            }
+            else if (role === "world_context" && item.include === "world.context") {
+                worldContext++;
+                items[role].push({ include: item.include });
+            }
+            else if (role === "world_context" &&
+                item.builtin === "runtime.coverage")
+                coverage++;
+            else if (role === "runtime_system" &&
+                typeof item.builtin === "string" &&
+                [
+                    "runtime.play-contract",
+                    "runtime.tool-contract",
+                    "runtime.operation-contract",
+                ].includes(item.builtin) &&
+                !runtime.has(item.builtin))
+                runtime.add(item.builtin);
+            else
+                throw new Error("Legacy host entry is unknown or misplaced");
+        }
+    }
+    if (runtime.size !== 3 ||
+        coverage !== 1 ||
+        worldInstructions !== 1 ||
+        worldContext !== 1)
+        throw new Error("Legacy host frame is missing or duplicates required includes");
+    const entries = [
+        {
+            id: "play.mechanics",
+            kind: "builtin",
+            builtin: "play.mechanics",
+            enabled: true,
+        },
+    ];
+    const used = new Set(excludedPaths);
+    const occurrences = new Map();
+    let world = false;
+    const add = (path, enabled) => {
+        if (!enabled && used.has(path))
+            return;
+        const occurrence = occurrences.get(path) ?? 0;
+        occurrences.set(path, occurrence + 1);
+        used.add(path);
+        const body = files[path];
+        if (body === undefined)
+            throw new Error(`Missing legacy prompt: ${path}`);
+        const heading = /^#[ \t]+([^\r\n]+)$/mu.exec(body)?.[1]?.trim() ?? "";
+        const stem = path.replace(/^.*\//u, "").replace(/\.md$/u, "");
+        const name = heading.length > 0 ? heading : stem.length > 0 ? stem : "Prompt";
+        entries.push({
+            id: `legacy-${createHash("sha256").update(path).digest("hex").slice(0, 32)}-${occurrence}`,
+            kind: "user",
+            name: name.slice(0, 160),
+            enabled,
+            body,
+        });
+    };
+    for (const role of [
+        "runtime_system",
+        "author_instruction",
+        "world_context",
+    ]) {
+        for (const item of items[role] ?? []) {
+            if (item.markdown)
+                add(item.markdown, true);
+            if (item.include?.startsWith("world.") && !world) {
+                entries.push({ id: "world", kind: "world" });
+                world = true;
+            }
+        }
+        if (role === "author_instruction")
+            for (const prompt of narrative)
+                add(prompt.path, true);
+    }
+    if (!world)
+        entries.push({ id: "world", kind: "world" });
+    for (const path of Object.keys(files).sort())
+        if ((path.startsWith("blocks/") || path.startsWith("prompts/")) &&
+            path.endsWith(".md"))
+            add(path, false);
+    return entries;
+}