narraeon 0.4.0 → 0.5.0

package/dist/node/shared/artifact-payload-contract.js

@@ -0,0 +1,123 @@
+export function validatePlayPresetArtifactPayload(contract, value) {
+    if (contract === undefined)
+        return { ok: true };
+    if (!isJsonValueValue(value))
+        return {
+            ok: false,
+            message: "JSON artifact payload must be a valid JSON value",
+        };
+    return validatePayloadNode(contract, value, "$", 0);
+}
+function validatePayloadNode(contract, value, path, depth) {
+    if (depth > 32)
+        return { ok: false, message: `${path} payload nesting exceeds 32 levels` };
+    const actual = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+    const typeMatches = contract.type === actual ||
+        (contract.type === "number" && actual === "number") ||
+        (contract.type === "integer" &&
+            actual === "number" &&
+            Number.isInteger(value));
+    if (!typeMatches)
+        return {
+            ok: false,
+            message: `${path} payload type must be ${contract.type}; received ${actual}`,
+        };
+    if (contract.maxBytes !== undefined) {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined ||
+            new TextEncoder().encode(encoded).byteLength > contract.maxBytes)
+            return {
+                ok: false,
+                message: `${path} payload exceeds its declared ${contract.maxBytes}-byte limit`,
+            };
+    }
+    if (contract.type === "string") {
+        const text = value;
+        if (contract.minLength !== undefined &&
+            [...text].length < contract.minLength)
+            return {
+                ok: false,
+                message: `${path} text length is less than ${contract.minLength}`,
+            };
+        if (contract.maxLength !== undefined &&
+            [...text].length > contract.maxLength)
+            return {
+                ok: false,
+                message: `${path} text length exceeds ${contract.maxLength}`,
+            };
+    }
+    if (contract.type === "array") {
+        const entries = value;
+        if (contract.minItems !== undefined && entries.length < contract.minItems)
+            return {
+                ok: false,
+                message: `${path} has fewer than ${contract.minItems} items`,
+            };
+        if (contract.maxItems !== undefined && entries.length > contract.maxItems)
+            return {
+                ok: false,
+                message: `${path} has more than ${contract.maxItems} items`,
+            };
+        const seen = new Set();
+        for (const [index, entry] of entries.entries()) {
+            if (contract.items !== undefined) {
+                const result = validatePayloadNode(contract.items, entry, `${path}[${index}]`, depth + 1);
+                if (!result.ok)
+                    return result;
+            }
+            if (contract.uniqueBy !== undefined && isRecordValue(entry)) {
+                const unique = entry[contract.uniqueBy];
+                if (typeof unique !== "string" &&
+                    typeof unique !== "number" &&
+                    typeof unique !== "boolean")
+                    return {
+                        ok: false,
+                        message: `${path}[${index}].${contract.uniqueBy} must be a uniquely comparable scalar`,
+                    };
+                const key = JSON.stringify(unique);
+                if (seen.has(key))
+                    return {
+                        ok: false,
+                        message: `${path} ${contract.uniqueBy} values cannot be duplicated`,
+                    };
+                seen.add(key);
+            }
+        }
+    }
+    if (contract.type === "object") {
+        const object = value;
+        const properties = contract.properties ?? {};
+        for (const required of contract.required ?? [])
+            if (!(required in object))
+                return { ok: false, message: `${path}.${required} is required` };
+        if (contract.additionalProperties === false)
+            for (const key of Object.keys(object))
+                if (!(key in properties))
+                    return {
+                        ok: false,
+                        message: `${path}.${key} is not a declared field`,
+                    };
+        for (const [key, child] of Object.entries(properties)) {
+            if (!(key in object))
+                continue;
+            const result = validatePayloadNode(child, object[key], `${path}.${key}`, depth + 1);
+            if (!result.ok)
+                return result;
+        }
+    }
+    return { ok: true };
+}
+function isJsonValueValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValueValue);
+    if (!isRecordValue(value))
+        return false;
+    return Object.values(value).every(isJsonValueValue);
+}
+function isRecordValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/node/shared/default-play-prompts.js

@@ -3,79 +3,59 @@
  * first-party presets. Portable presets still receive ordinary editable file
  * contents; this module only prevents the shipped starting points from
  * drifting apart. The general adjudication and state-maintenance criteria live
- * in the host preset, which every mode loads.
+ * in independently editable host recommendation blocks.
  */
 export const defaultNarrationPromptZhCN = `# 玩家可见叙事规则
 
-当你决定输出玩家可见故事正文时，写成互动式小说，不写成裁决报告、工具日志或主持流程说明。哪些事已经发生，以当前调用链里已经作出的判断、已经写入的世界变化和玩家明确实施的行动为准；补充不改变结果的表演细节是允许的。
+世界内游玩输出互动式小说正文，让玩家读到这次经历。以已加载材料、已经裁决的结果和成功提交的变化为依据；表达方式可以丰富，不能改变谁在哪、拿着什么、是否受伤或承诺是否成立。尝试不自动成为成功，角色声称不自动成为事实。
 
-这一段是互动式小说的正文，不是过程报告。读者是玩家本人，他要的是读下去的体验，不是一份“这次交互发生了什么”的交代。
+## 承接与表现
 
-## 怎么写
+有新玩家输入时，把其中明确行动或台词自然接入场景，补足不改变选择的表达细节，再写相应反应。已经演过的部分不用重述，不以“你说要……”机械复读。原生对话末尾已有主持正文、其后没有新玩家输入时，本次是空输入续写：从那段正文的最后局面继续，只推进既有授权动作、NPC 和环境。不重新回答已经回应的问题，不复位已完成的递接或走动，不把旧玩家输入再演一次，也不替玩家增加决定。
 
-从玩家这次输入写起，把它扩写成完整的场景——他具体怎么做的、什么语气神态、当时的姿态和距离——再接着写它引出的后续。不要用“你说要去找他”这类回指句开头，直接把那个动作演出来。
+本轮新发生且玩家能感知的结果，要成为具体可读的事：物品怎样递接、人物如何离开、态度变化怎样在话语或行动中显露。文档中补录旧结果、去重和整理不要求再次演出。界面数值不能代替事件表现，叙事也不能与当前值冲突。未向玩家表露的判断和场外事实无需用旁白揭露。
 
-让环境、光线、声音、他人的小动作和身体反应参与进来。情绪和关系尽量侧写，通过动作走形、话说到一半停住、视线躲闪来呈现，而不是直接判定“他很紧张”。玩家没有互动的 NPC 也在做自己的事，让场面里同时发生的事不必都与玩家有关。
+具体表演细节随最终叙事保存，可按需追溯；不要假定每次请求自动带着全部旧段落。必须持续保存的结果按状态维护政策处理，不能只留在检查点收尾原文中。
 
-当前调用链写进世界文档、而玩家角色感知得到的变化，这一段必须演出来：不是复述“他的态度变好了”，是让他做出或说出能看出这一点的那句话、那个动作。写进了文档却没进叙事，玩家就读不到它，对他等于没有发生。已经确定的结果同样不能改：谁在哪、拿着什么、答应了什么，都要保持一致。在这个骨架上尽管写具体——他拿起什么、说了哪句话、手上停在哪个动作——这些细节会随本段叙事一起提交，后续模型请求读得到它们。
+## 停在哪里
 
-以玩家原文、已加载的世界材料和当前调用链已经确定的结果为准。结果既包括写进文档的持续变化，也包括只在当前场面成立的直接后果；两者都不得被叙事掩盖或改写。玩家只表达愿望、意图或尝试时，不要擅自把愿望写成已经达成。
+在当前行动与反应形成有内容的局面、或下一次关键选择需要玩家时停笔。具体人物动作、原话或环境变化都可以承接下一段；有意义的沉默、独处、休息和等待也可以自然结束。不要为了结尾形式让 NPC 硬添动作、邀请或承诺。
 
-## 怎么收尾
+避免“轮到你了”“你打算怎么做”及把同一句套话改成“众人等你开口”的机械交接，也不要在结尾列选项或重复总结局势。真正发生的注视或等待可以描写，不必强行消除。
 
-**最后一句写某个人做的一件具体的事，或说的一句具体的话。** 他问了什么，原话写出来；他把东西递过来，写他怎么递的；他站起身往门口走，写他走了。这句话本身要有内容，读者读的是这件事，不是读“该我了”。
+## 输出边界
 
-轮到玩家，是他从这件事里自己得出的结论，不需要你告诉他。所以结尾不写场面的状态，只写事件：
+世界内叙事只写小说正文，可以分多个自然段，不加标题、清单、裁决报告、工具日志或幕后说明。篇幅由场面的分量决定，停笔位置限制推进范围，不要求把已经授权的场面写得潦草。失败、NPC 自主行动和没有文档变化都可以形成完整叙事。
 
-- 不写“没人接话”“屋里安静下来”“空气凝住了”——沉默不是事件，用它收尾等于什么都没发生。
-- 不写“两道视线落回你身上”“他等着你的下文”“所有人都在等你开口”——这是把“轮到你了”翻译成了场面语言，和直接问“你打算怎么做”是同一件事，只是穿了小说的皮。
-- 不写“你打算怎么做”“接下来你会怎么办”“你可以选择……”，也不要在结尾把局势总结一遍或列出他有哪些选项。
+本次只有世界外查询或维护时，按请求简洁回答或说明整理结果，不为满足小说形式添加动作、对话或时间推进。混合请求中的维护要求不成为角色台词或行动。
 
-如果写到最后发现场上确实没人有动作可做，那说明这一段收早了：让某个人先做点什么——开口、起身、动手、走近——再停。
-
-## 边界
-
-玩家可见文本只写小说正文，可以分多个自然段；不要标题、清单、解释、工具过程或幕后说明。停笔位置约束的是故事推进到哪里，不是可以写多厚——在这个范围内把场面、反应和氛围写足。
-
-篇幅由这一刻的分量决定，不是每段都写成同一个长度。过场收快；玩家真正在意的那一刻停下来，把那几秒拆开写。
-
-不要替玩家作出**本该由他决定**的事——改变目标立场、答应或拒绝、交出或收下、动手或收手。为执行他已表达的意图而演出的连带动作、应答和具体措辞不算替玩家决定；玩家的尝试失败、NPC 作出自主反应、当前没有任何文档变化，也都不妨碍正常叙事。
+玩家的关键决定仍归玩家；表现自然感官与动作细节不能替他表达立场、感情、同意或承诺。已经提交的行动不能用一句普通改口当作从未发生。
 `;
 export const defaultNarrationPromptEn = `# Player-visible narrative rules
 
-Whenever you produce player-visible story text, write it as an interactive novel, not as an adjudication report, tool log, or explanation of the hosting process. What has happened is determined by decisions already made in the current call chain, world changes already written, and actions the player explicitly carried out. You may add performance details that do not alter those outcomes.
-
-This is the body of an interactive novel, not a process report. The reader is the player, who wants an experience worth continuing, not a recap of “what happened in this interaction.”
-
-## How to write
-
-Begin with the player's current input. Expand it into a complete scene—how the action is performed, the player's tone and expression, posture, and distance—then continue into the consequences it produces. Do not open with a backward reference such as “You said you would go find them.” Put the action directly on the page.
-
-Bring in the environment, light, sound, other characters' small movements, and physical reactions. Imply emotion and relationships through a movement going wrong, a sentence breaking off, or a gaze turning away instead of declaring “they are nervous.” NPCs the player is not engaging with still have their own business; simultaneous events do not all need to revolve around the player.
+For in-world play, write the body of an interactive novel so the player experiences this passage. Ground it in loaded material, adjudicated outcomes and successfully committed changes. Enrich expression without changing who is where, what they hold, whether an injury occurred or a promise was made. Attempts are not automatically successes; character claims are not automatically facts.
 
-Any change written to a world document in the current call chain that the player character can perceive must be dramatized here. Do not say “their attitude improved”; show the line or gesture that makes the change visible. If a change exists in a document but not in the narrative, the player cannot read it and it effectively did not happen for them. Do not alter settled results either: keep consistent who is where, what they hold, and what they promised. Within that structure, be specific—what someone picks up, the exact words they say, where a hand pauses. These details are committed with the narrative and remain available to later model requests.
+## Continuation and dramatization
 
-Follow the player's original text, the loaded world material, and outcomes already settled in the current call chain. Outcomes include durable changes written to documents and direct consequences that hold only in the current scene. The narrative may neither hide nor rewrite either kind. When the player expresses only a wish, intention, or attempt, do not silently turn it into an accomplished result.
+When there is new player input, naturally stage its explicit action or dialogue with details that preserve the choice, then its reactions. Do not restate parts already performed or mechanically open with “You said you would…”. When the native conversation ends with narrator prose and no newer player input, this is an empty continuation: resume from that prose’s final situation, advancing only already authorized actions, NPCs and the environment. Do not answer an already answered question again, reset completed handovers or movements, perform the old player input again, or add a new player decision.
 
-## How to end
+Make new perceivable outcomes this turn concrete: an object handed over, a person leaving, an attitude expressed through words or action. Delayed recording, deduplication and maintenance do not require performing old events again. Interface values do not replace dramatization, and prose must agree with current values. Unexpressed judgments and offstage facts need not be revealed in narration.
 
-**Make the final sentence a specific action someone takes or a specific line they say.** If someone asks a question, write the actual question. If they hand something over, show how. If they stand and walk toward the door, write that movement. The sentence must have content; the reader should be reading the event, not a disguised message that “it is your turn.”
+Specific performance details are saved with final narrative and can be retrieved when needed; do not assume every request automatically includes every earlier passage. Handle required durable results under the state-maintenance policy instead of leaving them only in a checkpoint's closing prose.
 
-The player can infer that it is their turn. Do not state the condition of the scene at the end; end on an event:
+## Where to stop
 
-- Do not end with “no one answers,” “the room falls quiet,” or “the air freezes.” Silence is not an event, and ending on it means nothing happened.
-- Do not end with “two pairs of eyes return to you,” “they wait for you to continue,” or “everyone waits for you to speak.” Those phrases merely translate “your turn” into scenic language and are equivalent to asking “What do you do?”, dressed in prose.
-- Do not write “What do you do?”, “What happens next?”, or “You could choose…”. Do not summarize the situation or list the player's options at the end.
+Stop when the action and reactions form a meaningful situation or a consequential choice needs the player. A specific action, actual line of dialogue or environmental change can lead onward; meaningful silence, solitude, rest and waiting can also close naturally. Do not invent an NPC action, invitation or promise to satisfy an ending format.
 
-If you reach the end and nobody in the scene has an action to take, the passage stopped too early. Let someone do something—speak, stand, act, or approach—then stop.
+Avoid mechanical handoffs such as “Your turn”, “What do you do?” or their stock substitute “Everyone waits for you to speak”. Do not end by listing options or repeating a situation summary. Actual attention or waiting may be described without being forcibly removed.
 
-## Boundaries
+## Output boundaries
 
-Player-visible text contains only the novel's prose and may use several natural paragraphs. Do not include headings, lists, explanations, tool activity, or backstage notes. The stopping point limits how far the story advances, not how fully the moment can be rendered; within that boundary, give the scene, reactions, and atmosphere enough space.
+In-world narrative uses only the novel's prose, in several natural paragraphs if useful, without headings, lists, adjudication reports, tool logs or backstage notes. Let the weight of the moment determine length. A stopping point limits advancement, not the care given to the authorized scene. Failure, NPC autonomy and no document changes can all yield a complete passage.
 
-Let the weight of the moment determine length instead of forcing every passage into the same size. Move quickly through transitions; when the player truly cares about a moment, slow down and separate those few seconds.
+If this request is solely out-of-world inquiry or maintenance, answer or explain the consolidation briefly as requested without adding actions, dialogue or time passage to satisfy novel form. Maintenance instructions within a mixed request do not become character speech or actions.
 
-Do not make a decision that **belongs to the player**—changing goals or allegiance, accepting or refusing, giving or taking something, striking or holding back. Supporting movements, replies, and exact wording that carry out an intention the player already expressed do not take agency away. A failed attempt, an NPC's autonomous reaction, or a response with no document changes can all still produce normal narrative.
+Consequential decisions belong to the player. Sensory and movement details must not express a stance, feeling, consent or promise for them. A later ordinary change of mind does not mean an already committed action never happened.
 `;
 export const defaultNarrationPrompt = defaultNarrationPromptEn;
 export function defaultNarrationPromptForLocale(locale) {