@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/simulation/toolkit/dynamic_story_review.js

@@ -0,0 +1,333 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { evaluateChapterStanding } from './dynamic_progress.js';
+import { dynamicHistory } from '../dynamic_history.js';
+import { compileStrictSimulationSchema } from './structured_output.js';
+import { assertDynamicInferenceKnowledge, dynamicPrivateKnowledge, dynamicPublishedKnowledge } from './dynamic_knowledge.js';
+export const STORY_REVIEW_INTERVAL = 5;
+export const STORY_REVIEW_INPUT_BYTES = 65_536;
+export const STORY_REVIEW_TIMEOUT_MS = 30_000;
+export const STORY_REVIEW_MAX_TOKENS = 2_048;
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+function canonicalJson(value) {
+    return JSON.stringify(value, (_key, item) => item !== null && typeof item === 'object' && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([left], [right]) => left.localeCompare(right))) : item);
+}
+function requestBytes(packet) {
+    const request = storyReviewCall(packet);
+    const { responseSchema, ...facts } = JSON.parse(request.input);
+    const outputSchema = compileStrictSimulationSchema(responseSchema);
+    return Math.max(Buffer.byteLength(request.system + request.input), Buffer.byteLength(request.system + JSON.stringify(facts) + JSON.stringify(outputSchema)));
+}
+const id = z.string().min(1).max(128);
+const sha = z.string().regex(/^[a-f0-9]{64}$/u);
+const text = (maximum) => z.string().trim().min(1).max(maximum);
+const evidenceSchema = z.object({
+    eventIds: z.array(id).min(1).max(16),
+    objects: z.array(z.object({ objectId: id, version: z.number().int().positive() }).strict()).max(16),
+    resources: z.array(z.object({ resourceId: id, value: z.number().finite() }).strict()).max(32),
+}).strict();
+const identityShape = { version: z.literal(1), reviewId: sha, basedOnRevision: z.number().int().positive(),
+    evidenceDigest: sha, explanation: text(600), evidence: evidenceSchema };
+export const storyReviewDecisionSchema = z.discriminatedUnion('kind', [
+    z.object({ ...identityShape, kind: z.literal('close'), title: text(160), narrative: text(2_000),
+        outcome: z.enum(['triumph', 'mixed', 'collapse']), unresolvedStakes: z.array(text(400)).max(8) }).strict(),
+    z.object({ ...identityShape, kind: z.literal('continue'), unresolvedStake: text(400) }).strict(),
+    z.object({ ...identityShape, kind: z.literal('stalled'), unresolvedStake: text(400), requestPressure: z.boolean() }).strict(),
+]);
+export const storyReviewReceiptSchema = z.object({
+    version: z.literal(1), revision: z.number().int().positive(), acceptedBeat: z.number().int().positive(),
+    reviewId: sha, evidenceDigest: sha, model: z.enum(['gpt-5.6-sol', 'modal/deepseek-v4.1-flash']), reasoningEffort: z.literal('none'),
+    inputDigest: sha, outputDigest: sha, outputBytes: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    requested: z.boolean(), status: z.enum(['accepted', 'rejected']), decision: storyReviewDecisionSchema.nullable(), failureCode: id.optional(),
+}).strict().refine(value => value.status === 'accepted'
+    ? value.requested && value.decision !== null && value.failureCode === undefined
+    : value.decision === null && value.failureCode !== undefined);
+const share = z.number().min(0).max(1);
+const chapterStandingSchema = z.object({ act: z.number().int().min(1).max(3), acts: z.number().int().min(1).max(3),
+    decisions: z.number().int().min(0), workingDecisions: z.number().int().min(0), decisionsLeft: z.number().int().min(0),
+    goals: z.array(z.object({ id, label: text(160), met: z.boolean(), share }).strict()).min(1).max(32), score: share,
+    dangers: z.array(z.object({ resourceId: id, label: text(160), value: z.number().finite(), bound: z.number().finite(), room: share }).strict()).max(64),
+    result: z.enum(['open', 'win', 'mixed', 'loss']),
+    lossCause: z.union([z.null(), z.object({ kind: z.literal('meter'), resourceId: id, label: text(160) }).strict(), z.object({ kind: z.literal('out-of-decisions') }).strict()]) }).strict();
+const chapterResultsSchema = z.array(z.object({ act: z.number().int().min(1).max(3), result: z.enum(['win', 'mixed', 'loss']),
+    revision: z.number().int().positive(), title: text(160), narrative: text(2_000) }).strict()).max(3);
+export const storyReviewViewSchema = z.object({ version: z.literal(1), acceptedBeats: z.number().int().min(0),
+    nextReviewAtAcceptedBeat: z.number().int().positive(), last: storyReviewReceiptSchema.nullable(),
+    chapter: chapterStandingSchema.optional(), results: chapterResultsSchema.optional() }).strict();
+export const storyEpisodeSchema = (world) => z.object({ version: z.literal(1),
+    origin: z.object({ objective: text(2_000), world }).strict(), acceptedBeats: z.number().int().min(0),
+    lastReview: storyReviewReceiptSchema.nullable(),
+    chapter: z.object({ startRevision: z.number().int().min(0), startResources: z.record(id, z.number().finite()), standing: chapterStandingSchema }).strict().optional(),
+    results: chapterResultsSchema.optional() }).strict();
+export class StoryReviewError extends Error {
+    code;
+    request;
+    constructor(code, message, request) {
+        super(message);
+        this.code = code;
+        this.request = request;
+        this.name = 'StoryReviewError';
+    }
+}
+function publicStoryObject(object, visibleIds) {
+    return { ...structuredClone(object), links: object.links.filter(link => link.targetType !== 'object' || visibleIds.has(link.targetId)).map(link => ({ ...link })) };
+}
+export function publicStoryWorld(world, policy) {
+    const objects = world.domainObjects.filter(object => object.visibility.scope === 'world');
+    const visibleIds = new Set(objects.map(object => object.id));
+    return { resources: Object.fromEntries(policy.resources.filter(resource => resource.visibility !== 'private')
+            .map(resource => [resource.id, world.resources[resource.id]])), facts: [...world.facts],
+        domainObjects: objects.map(object => publicStoryObject(object, visibleIds)) };
+}
+function chapterStanding(policy, world, act, decisions, workingDecisions, revision, startResources) {
+    const open = publicStoryWorld(world, policy);
+    return evaluateChapterStanding({ rules: policy.milestones ?? [], act, decisions, workingDecisions, startResources,
+        frame: { revision, world: policy.resources.filter(resource => resource.visibility !== 'private').map(resource => ({ id: resource.id, label: resource.label,
+                value: open.resources[resource.id], minimum: resource.minimum, maximum: resource.maximum, initial: resource.initial, dangerDirection: resource.dangerDirection })),
+            domainObjects: open.domainObjects.map(object => ({ id: object.id, kind: object.kind, label: object.label, status: object.status, version: object.version,
+                ownerActorId: object.ownerActorId, data: {}, links: [], updatedRevision: object.provenance.updatedRevision })) } });
+}
+export function initialStoryEpisode(world, policy) {
+    const origin = publicStoryWorld(world, policy);
+    return { version: 1, origin: { objective: policy.definition.objective, world: origin }, acceptedBeats: 0, lastReview: null,
+        ...(policy.chapterVersion !== 1 ? {} : { chapter: { startRevision: 0, startResources: origin.resources,
+                standing: chapterStanding(policy, world, 1, 0, 0, 0, origin.resources) }, results: [] }) };
+}
+/** Every committed turn moves the episode the same way, live and in replay. A chapter result latches once it is no longer open. */
+export function advanceStoryEpisode(episode, policy, entry, world) {
+    const next = { ...episode, acceptedBeats: episode.acceptedBeats + (entry.usedFallback ? 0 : 1) };
+    const chapter = episode.chapter;
+    if (policy.chapterVersion !== 1 || chapter === undefined || chapter.standing.result !== 'open')
+        return next;
+    const decided = !entry.usedFallback && entry.playerActionId !== null;
+    // Real work: the rules accepted an action that came from the player's pick, and it was not an abandonment.
+    const worked = decided && entry.gmProposal.domainActions.some(action => action.sourcePlayerActionId === entry.playerActionId
+        && action.mechanic !== 'abandon-work' && entry.acceptedActionIds.includes(action.id));
+    return { ...next, chapter: { ...chapter, standing: chapterStanding(policy, world, chapter.standing.act, chapter.standing.decisions + (decided ? 1 : 0), chapter.standing.workingDecisions + (worked ? 1 : 0), entry.revision, chapter.startResources) } };
+}
+const CHAPTER_OUTCOME = { win: 'triumph', mixed: 'mixed', loss: 'collapse' };
+/** The words code uses when the model's closing words are missing or refused. */
+export function plainChapterEnding(standing) {
+    const open = standing.goals.filter(goal => !goal.met).map(goal => goal.label).join('; ');
+    const met = standing.goals.filter(goal => goal.met).map(goal => goal.label).join('; ');
+    if (standing.result === 'win')
+        return { title: `Chapter ${standing.act} won`, narrative: `You met every goal: ${met}.` };
+    if (standing.result === 'mixed')
+        return { title: `Chapter ${standing.act}: a mixed result`, narrative: `You ran out of decisions part way.${met === '' ? '' : ` Met: ${met}.`} Still open: ${open}.` };
+    return { title: `Chapter ${standing.act} lost`, narrative: standing.lossCause?.kind === 'meter'
+            ? `${standing.lossCause.label} reached its limit. That ended the chapter.${open === '' ? '' : ` Still open: ${open}.`}`
+            : `You ran out of decisions. Still open: ${open}.` };
+}
+/**
+ * Applies a settled review to a chapter. Code has already decided the result; the receipt only supplies the words.
+ * A loss or the last act ends the run. Any other result is recorded and the next act opens in the same world.
+ */
+export function closeStoryChapter(episode, policy, receipt, world, eventId) {
+    const chapter = episode.chapter;
+    if (policy.chapterVersion !== 1 || chapter === undefined || receipt.failureCode === STORY_REVIEW_INPUT_PENDING)
+        return null;
+    const { standing } = chapter;
+    const result = standing.result;
+    if (result === 'open')
+        return null;
+    const decision = receipt.status === 'accepted' && receipt.decision?.kind === 'close' ? receipt.decision : null;
+    const words = decision === null ? plainChapterEnding(standing) : { title: decision.title, narrative: decision.narrative };
+    const results = [...(episode.results ?? []), { act: standing.act, result, revision: receipt.revision, ...words }];
+    const ends = result === 'loss' || standing.act >= standing.acts;
+    const startResources = publicStoryWorld(world, policy).resources;
+    return { ends, ending: { ...words, outcome: CHAPTER_OUTCOME[result], causalEventIds: [...new Set([...(decision?.evidence.eventIds ?? []), eventId])] },
+        episode: { ...episode, lastReview: receipt, results, chapter: ends ? chapter
+                : { startRevision: receipt.revision, startResources, standing: chapterStanding(policy, world, standing.act + 1, 0, 0, receipt.revision, startResources) } } };
+}
+export function storyReviewView(episode) {
+    return { version: 1, acceptedBeats: episode.acceptedBeats,
+        nextReviewAtAcceptedBeat: (Math.floor(episode.acceptedBeats / STORY_REVIEW_INTERVAL) + 1) * STORY_REVIEW_INTERVAL,
+        last: episode.lastReview,
+        ...(episode.chapter === undefined ? {} : { chapter: episode.chapter.standing, results: episode.results ?? [] }) };
+}
+/** A close would strand accepted player input, so the engine keeps the receipt and a later review may close. */
+export const STORY_REVIEW_INPUT_PENDING = 'story-review-input-pending';
+export function deferStoryReviewClose(receipt) {
+    if (receipt.decision?.kind !== 'close')
+        return receipt;
+    return { ...receipt, status: 'rejected', decision: null, failureCode: STORY_REVIEW_INPUT_PENDING };
+}
+export function storyReviewFailed(state) {
+    // Under chapter rules a refused ending is replaced by plain words from code, so the player sees no failure.
+    return state.episode?.chapter === undefined && state.episode?.lastReview?.revision === state.revision && state.episode.lastReview.status === 'rejected'
+        && state.episode.lastReview.failureCode !== STORY_REVIEW_INPUT_PENDING;
+}
+export function storyReviewDue(state) {
+    if (state.episode === undefined || state.status !== 'active')
+        return false;
+    // Under chapter rules the model is asked for closing words only when code has already settled the result.
+    if (state.episode.chapter !== undefined)
+        return state.episode.chapter.standing.result !== 'open'
+            && state.episode.lastReview?.revision !== state.history.at(-1)?.revision;
+    return state.history.at(-1)?.usedFallback === false
+        && state.episode.acceptedBeats > 0 && state.episode.acceptedBeats % STORY_REVIEW_INTERVAL === 0
+        && state.episode.lastReview?.acceptedBeat !== state.episode.acceptedBeats;
+}
+const objectSchema = (properties) => ({ type: 'object', additionalProperties: false,
+    required: Object.keys(properties), properties });
+const stringSchema = (maximum) => ({ type: 'string', minLength: 1, maxLength: maximum });
+function responseSchema(reviewId, revision, evidenceDigest, settledOutcome) {
+    const array = (items, maximum, minimum = 0) => ({ type: 'array', items, minItems: minimum, maxItems: maximum });
+    const common = { version: { const: 1 }, reviewId: { const: reviewId }, basedOnRevision: { const: revision },
+        evidenceDigest: { const: evidenceDigest }, explanation: stringSchema(600), evidence: objectSchema({
+            eventIds: array(stringSchema(128), 16, 1),
+            objects: array(objectSchema({ objectId: stringSchema(128), version: { type: 'integer', minimum: 1 } }), 16),
+            resources: array(objectSchema({ resourceId: stringSchema(128), value: { type: 'number' } }), 32),
+        }) };
+    // Code has settled this chapter: the model may only close it, with the outcome code computed.
+    if (settledOutcome !== undefined)
+        return objectSchema({ decision: objectSchema({ kind: { const: 'close' }, ...common, title: stringSchema(160),
+                narrative: stringSchema(2_000), outcome: { const: settledOutcome }, unresolvedStakes: array(stringSchema(400), 8) }) });
+    return objectSchema({ decision: { anyOf: [objectSchema({ kind: { const: 'close' }, ...common, title: stringSchema(160), narrative: stringSchema(2_000),
+                    outcome: { enum: ['triumph', 'mixed', 'collapse'] }, unresolvedStakes: array(stringSchema(400), 8) }),
+                objectSchema({ kind: { const: 'continue' }, ...common, unresolvedStake: stringSchema(400) }),
+                objectSchema({ kind: { const: 'stalled' }, ...common, unresolvedStake: stringSchema(400), requestPressure: { type: 'boolean' } })] } });
+}
+export function makeDynamicStoryReviewRequest(input) {
+    const { state, policy } = input;
+    if (policy.storyReviewVersion !== 1 || !state.episode || !storyReviewDue(state))
+        throw new StoryReviewError('story-review-not-due', 'This candidate is not due for a story review');
+    const history = dynamicHistory(state);
+    const current = publicStoryWorld(state.world, policy);
+    const available = current.domainObjects.length;
+    const visibleIds = new Set(current.domainObjects.map(object => object.id));
+    const objects = [...current.domainObjects].sort((a, b) => b.provenance.updatedRevision - a.provenance.updatedRevision || a.id.localeCompare(b.id)).slice(0, 16);
+    const prior = state.episode.lastReview;
+    const priorCauses = prior?.decision?.evidence.eventIds ?? [];
+    const recent = history.slice(-8);
+    const older = history.slice(0, -8).filter(entry => priorCauses.includes(entry.eventId) || entry.revision === 1).slice(-8);
+    const selected = [...older, ...recent];
+    const events = selected.map(entry => ({ eventId: entry.eventId, revision: entry.revision,
+        accepted: !entry.usedFallback, digest: hash(canonicalJson({ eventId: entry.eventId, revision: entry.revision,
+            event: entry.gmProposal.event, effects: entry.effects.filter(effect => effect.operation === 'resource.change'
+                ? Object.hasOwn(current.resources, effect.resourceId) : effect.operation === 'object.put' && effect.object.visibility.scope === 'world')
+                .map(effect => {
+                if (effect.operation !== 'object.put')
+                    return effect;
+                const { sceneRetention: _retirement, ...visibleEffect } = effect;
+                return { ...visibleEffect, object: publicStoryObject(effect.object, visibleIds) };
+            }) })) }));
+    const originObjects = state.episode.origin.world.domainObjects.slice(0, 16);
+    const standing = policy.chapterVersion === 1 ? state.episode.chapter?.standing : undefined;
+    const settled = standing === undefined || standing.result === 'open' ? undefined : CHAPTER_OUTCOME[standing.result];
+    const evidence = { ...(standing === undefined ? {} : { chapter: { act: standing.act, acts: standing.acts, result: standing.result, decisions: standing.decisions,
+                goals: standing.goals.map(goal => ({ label: goal.label, met: goal.met })), lossCause: standing.lossCause } }),
+        origin: { ...state.episode.origin, world: { ...state.episode.origin.world, domainObjects: originObjects } },
+        current: { ...current, domainObjects: objects }, events, priorReview: prior,
+        coverage: { totalAcceptedBeats: state.episode.acceptedBeats, totalHistoryBeats: history.length,
+            includedRevisions: selected.map(entry => entry.revision), omittedHistoryBeats: history.length - selected.length,
+            narrativeEventIds: [], omittedNarrativeRecords: selected.length,
+            currentObjectsIncluded: objects.length, currentObjectsOmitted: available - objects.length,
+            originObjectsIncluded: originObjects.length, originObjectsOmitted: state.episode.origin.world.domainObjects.length - originObjects.length,
+            meaning: 'Only selected public records are shown. Omitted records remain stored and are unknown, not absent.' } };
+    const evidenceDigest = hash(canonicalJson(evidence));
+    const reviewId = hash(canonicalJson([state.gameKind, state.rulesVersion, state.seed, state.revision, state.episode.acceptedBeats, evidenceDigest]));
+    const packet = { version: 1, phase: 'story-review', game: { kind: state.gameKind, rulesVersion: state.rulesVersion },
+        reviewId, basedOnRevision: state.revision, acceptedBeat: state.episode.acceptedBeats, evidenceDigest,
+        ...evidence, recentDevelopments: [],
+        responseSchema: responseSchema(reviewId, state.revision, evidenceDigest, settled) };
+    if (requestBytes(packet) > STORY_REVIEW_INPUT_BYTES)
+        throw new StoryReviewError('story-review-budget-exceeded', 'Required story evidence exceeds its byte budget', storyReviewCall(packet));
+    for (const entry of [...selected].reverse()) {
+        const item = { eventId: entry.eventId, ...entry.gmProposal.event };
+        const recentDevelopments = [item, ...packet.recentDevelopments];
+        const coverage = { ...packet.coverage, narrativeEventIds: recentDevelopments.map(event => event.eventId),
+            omittedNarrativeRecords: selected.length - recentDevelopments.length };
+        const candidate = { ...packet, recentDevelopments, coverage };
+        if (requestBytes(candidate) <= STORY_REVIEW_INPUT_BYTES) {
+            packet.recentDevelopments = recentDevelopments;
+            packet.coverage = coverage;
+        }
+    }
+    packet.evidenceDigest = hash(canonicalJson({ ...evidence, coverage: packet.coverage }));
+    packet.reviewId = hash(canonicalJson([state.gameKind, state.rulesVersion, state.seed, state.revision, state.episode.acceptedBeats, packet.evidenceDigest]));
+    packet.responseSchema = responseSchema(packet.reviewId, state.revision, packet.evidenceDigest, settled);
+    return storyReviewCall(packet);
+}
+const EPISODE_REVIEW_SYSTEM = 'Assess this episode from the supplied public evidence. Close when its central situation reaches a meaningful conclusion; success or world perfection is not required. Preserve unresolved duties honestly. Continue for a concrete unresolved stake; quiet activity can be meaningful. Mark stalled only when the story lacks meaningful movement, not because characters choose silence. You may request a lawful environmental opportunity, never compel a character or invent effects, fulfilled promises, or achievements. Citations ground your judgment; the engine validates identity and authority. Return the supplied schema.';
+const CHAPTER_ENDING_SYSTEM = 'The rules have already decided how this chapter ended: read chapter.result, chapter.goals and chapter.lossCause. Write the ending for the player: a short title and a narrative of two to four plain sentences that says what the player did, which goals they met or missed, and why the chapter ended this way. Use only the supplied public evidence. Do not explain your reasoning, do not judge whether the story should end, and do not change the outcome. Return kind close with the outcome given in the schema.';
+function storyReviewCall(packet) {
+    const { responseSchema, ...facts } = packet;
+    return { role: 'game-master', model: 'gpt-5.6-sol', reasoningEffort: 'none', timeoutMs: STORY_REVIEW_TIMEOUT_MS,
+        maxTokens: STORY_REVIEW_MAX_TOKENS,
+        system: packet.chapter !== undefined ? CHAPTER_ENDING_SYSTEM : EPISODE_REVIEW_SYSTEM,
+        input: JSON.stringify({ ...JSON.parse(canonicalJson(facts)), responseSchema }) };
+}
+export function validateStoryReviewDecision(request, value) {
+    const parsed = storyReviewDecisionSchema.safeParse(value);
+    if (!parsed.success)
+        throw new StoryReviewError('story-review-invalid', 'The story decision does not match its strict contract');
+    const decision = parsed.data;
+    const packet = JSON.parse(request.input);
+    if (decision.reviewId !== packet.reviewId || decision.basedOnRevision !== packet.basedOnRevision || decision.evidenceDigest !== packet.evidenceDigest)
+        throw new StoryReviewError('story-review-identity-invalid', 'The story decision does not match its candidate evidence');
+    if (packet.chapter !== undefined && (decision.kind !== 'close' || decision.outcome !== CHAPTER_OUTCOME[packet.chapter.result]))
+        throw new StoryReviewError('story-review-outcome-invalid', 'Code settled this chapter; the ending must close it with that outcome');
+    const { evidence } = decision;
+    if (new Set(evidence.eventIds).size !== evidence.eventIds.length
+        || new Set(evidence.objects.map(item => item.objectId)).size !== evidence.objects.length
+        || new Set(evidence.resources.map(item => item.resourceId)).size !== evidence.resources.length
+        || evidence.eventIds.some(eventId => !packet.events.some((event) => event.eventId === eventId && event.accepted))
+        || evidence.objects.some(item => !packet.current.domainObjects.some((object) => object.id === item.objectId && object.version === item.version))
+        || evidence.resources.some(item => !Object.hasOwn(packet.current.resources, item.resourceId) || packet.current.resources[item.resourceId] !== item.value))
+        throw new StoryReviewError('story-review-evidence-invalid', 'The story decision cites unavailable or different public evidence');
+    return decision;
+}
+export function replayDynamicStoryReview(input) {
+    const request = makeDynamicStoryReviewRequest(input);
+    if (Buffer.byteLength(input.output) > 32_768)
+        throw new StoryReviewError('story-review-invalid', 'The story decision exceeds its response budget');
+    let value;
+    try {
+        value = JSON.parse(input.output);
+    }
+    catch {
+        throw new StoryReviewError('story-review-invalid', 'The story decision is not JSON');
+    }
+    const envelope = z.object({ decision: storyReviewDecisionSchema }).strict().safeParse(value);
+    if (!envelope.success)
+        throw new StoryReviewError('story-review-invalid', 'The story response does not match its strict decision envelope');
+    assertDynamicInferenceKnowledge({ request: JSON.stringify(request), output: input.output,
+        privateKnowledge: dynamicPrivateKnowledge(input.state), publishedKnowledge: dynamicPublishedKnowledge(input.state) });
+    const decision = validateStoryReviewDecision(request, envelope.data.decision);
+    return storyReviewReceipt(request, input.output, decision);
+}
+export function storyReviewReceipt(request, output, decision, failureCode, requested = true) {
+    const packet = JSON.parse(request.input);
+    return { version: 1, revision: packet.basedOnRevision, acceptedBeat: packet.acceptedBeat, reviewId: packet.reviewId,
+        evidenceDigest: packet.evidenceDigest, model: 'gpt-5.6-sol', reasoningEffort: 'none', inputDigest: hash(request.input),
+        outputDigest: hash(output), outputBytes: Buffer.byteLength(output), requested, status: decision === null ? 'rejected' : 'accepted', decision,
+        ...(failureCode === undefined ? {} : { failureCode }) };
+}
+export function validateStoredStoryReview(state, policy, receipt) {
+    let request;
+    let constructionFailure;
+    try {
+        request = makeDynamicStoryReviewRequest({ state, policy });
+    }
+    catch (error) {
+        if (!(error instanceof StoryReviewError) || error.request === undefined)
+            throw error;
+        request = error.request;
+        constructionFailure = error.code;
+    }
+    if (receipt.requested !== (constructionFailure === undefined) || (constructionFailure !== undefined
+        && (receipt.status !== 'rejected' || receipt.failureCode !== constructionFailure || receipt.outputBytes !== 0 || receipt.outputDigest !== hash(''))))
+        throw new StoryReviewError('story-review-receipt-invalid', 'Request dispatch differs from its retained construction outcome');
+    const packet = JSON.parse(request.input);
+    if (!storyReviewReceiptSchema.safeParse(receipt).success || receipt.revision !== state.revision
+        || receipt.acceptedBeat !== state.episode?.acceptedBeats || receipt.reviewId !== packet.reviewId
+        || receipt.evidenceDigest !== packet.evidenceDigest || receipt.inputDigest !== hash(request.input))
+        throw new StoryReviewError('story-review-receipt-invalid', 'The stored review differs from its reconstructed candidate');
+    if (receipt.status === 'accepted') {
+        assertDynamicInferenceKnowledge({ request: JSON.stringify(request), output: canonicalJson(receipt.decision),
+            privateKnowledge: dynamicPrivateKnowledge(state), publishedKnowledge: dynamicPublishedKnowledge(state) });
+        validateStoryReviewDecision(request, receipt.decision);
+    }
+}

package/dist/simulation/toolkit/dynamic_storyteller.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import type { DynamicInitialization, DynamicInitializationV1, StorytellerDecisionV1, StorytellerObservationV1, StorytellerReceiptV1, StorytellerSetbackV2 } from '../../plugin/simulation_storyteller.js';
+export declare const storytellerSelectionSchema: z.ZodObject<{
+    policyVersion: z.ZodEnum<{
+        "storyteller-1": "storyteller-1";
+        "storyteller-2": "storyteller-2";
+    }>;
+    personality: z.ZodEnum<{
+        "rising-tension": "rising-tension";
+        "spacious-recovery": "spacious-recovery";
+    }>;
+}, z.core.$strict>;
+export declare const dynamicSelectionSchema: z.ZodObject<{
+    policyVersion: z.ZodLiteral<"selection-1">;
+    gameKind: z.ZodString;
+    rulesVersion: z.ZodString;
+    scenarioId: z.ZodString;
+    roleId: z.ZodString;
+}, z.core.$strict>;
+export declare const dynamicInitializationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    storyteller: z.ZodObject<{
+        policyVersion: z.ZodEnum<{
+            "storyteller-1": "storyteller-1";
+            "storyteller-2": "storyteller-2";
+        }>;
+        personality: z.ZodEnum<{
+            "rising-tension": "rising-tension";
+            "spacious-recovery": "spacious-recovery";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    documents: z.ZodOptional<z.ZodObject<{
+        policyVersion: z.ZodLiteral<"document-stream-1">;
+        authoredRevision: z.ZodOptional<z.ZodLiteral<2>>;
+    }, z.core.$strict>>;
+    selection: z.ZodObject<{
+        policyVersion: z.ZodLiteral<"selection-1">;
+        gameKind: z.ZodString;
+        rulesVersion: z.ZodString;
+        scenarioId: z.ZodString;
+        roleId: z.ZodString;
+    }, z.core.$strict>;
+    storyteller: z.ZodObject<{
+        policyVersion: z.ZodEnum<{
+            "storyteller-1": "storyteller-1";
+            "storyteller-2": "storyteller-2";
+        }>;
+        personality: z.ZodEnum<{
+            "rising-tension": "rising-tension";
+            "spacious-recovery": "spacious-recovery";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "version">;
+export declare const STORYTELLER_OPTIONS: readonly [{
+    readonly id: "rising-tension";
+    readonly label: "Rising tension";
+}, {
+    readonly id: "spacious-recovery";
+    readonly label: "Spacious recovery";
+}];
+export declare const DEFAULT_DYNAMIC_INITIALIZATION: DynamicInitializationV1;
+export declare function parseDynamicInitialization(value: unknown): DynamicInitialization;
+export declare function storytellerMemory(initialization: DynamicInitialization, receipts: readonly StorytellerReceiptV1[]): {
+    quiet: number;
+    major: number;
+    recovery: number;
+    setbacks: readonly number[];
+};
+export declare function planStoryteller(input: {
+    readonly initialization: DynamicInitialization;
+    readonly revision: number;
+    readonly observation: StorytellerObservationV1;
+    readonly receipts: readonly StorytellerReceiptV1[];
+}): StorytellerDecisionV1;
+export declare function pendingStorytellerSetbacks(receipts: readonly StorytellerReceiptV1[]): StorytellerSetbackV2[];

package/dist/simulation/toolkit/dynamic_storyteller.js

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+export const storytellerSelectionSchema = z.object({
+    policyVersion: z.enum(['storyteller-1', 'storyteller-2']),
+    personality: z.enum(['rising-tension', 'spacious-recovery']),
+}).strict();
+const legacyInitializationSchema = z.object({
+    version: z.literal(1),
+    storyteller: storytellerSelectionSchema,
+}).strict();
+export const dynamicSelectionSchema = z.object({
+    policyVersion: z.literal('selection-1'),
+    gameKind: z.string().min(1).max(64).regex(/^[a-z0-9-]+$/),
+    rulesVersion: z.string().min(1).max(128),
+    scenarioId: z.string().min(1).max(64).regex(/^[a-z0-9-]+$/),
+    roleId: z.string().min(1).max(64).regex(/^[a-z0-9-]+$/),
+}).strict();
+export const dynamicInitializationSchema = z.discriminatedUnion('version', [
+    legacyInitializationSchema,
+    z.object({ version: z.literal(2), documents: z.object({ policyVersion: z.literal('document-stream-1'), authoredRevision: z.literal(2).optional() }).strict().optional(), selection: dynamicSelectionSchema, storyteller: storytellerSelectionSchema }).strict(),
+]);
+export const STORYTELLER_OPTIONS = [
+    { id: 'rising-tension', label: 'Rising tension' },
+    { id: 'spacious-recovery', label: 'Spacious recovery' },
+];
+export const DEFAULT_DYNAMIC_INITIALIZATION = {
+    version: 1, storyteller: { policyVersion: 'storyteller-1', personality: 'rising-tension' },
+};
+export function parseDynamicInitialization(value) {
+    const result = dynamicInitializationSchema.safeParse(value);
+    if (!result.success)
+        throw new Error('Storyteller selection is invalid');
+    return result.data;
+}
+export function storytellerMemory(initialization, receipts) {
+    if (initialization.storyteller.policyVersion === 'storyteller-2')
+        receipts = publicStorytellerReceipts(receipts);
+    const spacious = initialization.storyteller.personality === 'spacious-recovery';
+    let quiet = 0;
+    let major = 0;
+    let recovery = 0;
+    const setbacks = new Set();
+    for (const receipt of receipts) {
+        quiet = receipt.acceptedPressureActionIds.length > 0 ? 0 : quiet + 1;
+        major = receipt.majorCrisis ? major + 1 : 0;
+        recovery = Math.max(0, recovery - 1);
+        if (receipt.acceptedPressureActionIds.length > 0)
+            recovery = Math.max(recovery, spacious ? 3 : 1);
+        for (const revision of receipt.recoveryForRevisions)
+            setbacks.delete(revision);
+        if (receipt.setbackResourceIds.length > 0) {
+            setbacks.add(receipt.decision.basedOnRevision + 1);
+            recovery = Math.max(recovery, spacious ? 4 : 2);
+        }
+    }
+    return { quiet, major, recovery, setbacks: [...setbacks] };
+}
+export function planStoryteller(input) {
+    const initialization = parseDynamicInitialization(input.initialization);
+    const { observation, revision } = input;
+    const receipts = initialization.storyteller.policyVersion === 'storyteller-2' ? publicStorytellerReceipts(input.receipts) : input.receipts;
+    if (!Number.isSafeInteger(revision) || revision < 0
+        || (initialization.storyteller.policyVersion === 'storyteller-1' && revision > 100)
+        || observation.headroom.length === 0 || observation.headroom.length > 32
+        || [...observation.headroom, observation.progress].some(value => !Number.isSafeInteger(value) || value < 0 || value > 1000)
+        || !Number.isSafeInteger(observation.activeThreats) || observation.activeThreats < 0) {
+        throw new Error('Storyteller observation is invalid');
+    }
+    const memory = storytellerMemory(initialization, input.receipts);
+    const quietLimit = initialization.storyteller.personality === 'spacious-recovery' ? 6 : 3;
+    const recentSetback = receipts.slice(-2).some(receipt => receipt.setbackResourceIds.length > 0);
+    const headroom = observation.headroom.reduce((sum, value) => sum + value, 0) / observation.headroom.length;
+    let comfort = Math.max(0, Math.min(1000, Math.floor(0.7 * headroom + 0.3 * observation.progress - 50 * Math.min(4, observation.activeThreats) - (recentSetback ? 250 : 0))));
+    if (Math.min(...observation.headroom) < 150)
+        comfort = Math.min(comfort, 250);
+    const offerRecovery = memory.recovery > 0 || memory.setbacks.length > 0;
+    const due = memory.quiet >= quietLimit - 1;
+    const tier = comfort < 400 ? 1 : comfort < 700 ? 2 : 3;
+    return {
+        basedOnRevision: revision,
+        mode: due ? 'pressure' : offerRecovery ? 'recovery' : 'quiet',
+        strengthTier: due ? (memory.recovery > 0 || memory.major >= 2 ? 1 : tier) : 0,
+        offerRecovery,
+        quietLimit,
+        inputDigest: createHash('sha256').update(JSON.stringify({ initialization, revision, observation, receipts })).digest('hex'),
+    };
+}
+export function pendingStorytellerSetbacks(receipts) {
+    const pending = new Map();
+    for (const receipt of receipts) {
+        for (const opportunity of receipt.recovery?.opportunities ?? [])
+            pending.delete(opportunity.causeId);
+        for (const cause of receipt.recovery?.setbacks ?? [])
+            pending.set(cause.id, cause);
+    }
+    return [...pending.values()];
+}
+/** Scheduling sees only public causal evidence; trusted private audit remains in history. */
+function publicStorytellerReceipts(receipts) {
+    const publicCauses = receipts.flatMap(receipt => receipt.recovery?.setbacks ?? []).filter(cause => !cause.private);
+    const addressed = new Set();
+    return receipts.map(receipt => {
+        const causes = (receipt.recovery?.setbacks ?? []).filter(cause => !cause.private);
+        for (const opportunity of receipt.recovery?.opportunities ?? []) {
+            if (publicCauses.some(cause => cause.id === opportunity.causeId))
+                addressed.add(opportunity.causeId);
+        }
+        const completed = [...new Set(publicCauses.filter(cause => cause.revision < receipt.decision.basedOnRevision + 1
+                && publicCauses.filter(other => other.revision === cause.revision).every(other => addressed.has(other.id))).map(cause => cause.revision))];
+        return { decision: receipt.decision, proposedPressure: receipt.proposedPressure, proposedRecovery: receipt.proposedRecovery,
+            acceptedPressureActionIds: receipt.acceptedPressureActionIds, majorCrisis: causes.some(cause => cause.major),
+            setbackResourceIds: causes.map(cause => cause.id), recoveryChoiceIds: [], recoveryForRevisions: completed };
+    });
+}

package/dist/simulation/toolkit/dynamic_storyteller_runtime.d.ts

@@ -0,0 +1,26 @@
+import type { SimulationDomainActionProposalV1, SimulationDynamicHistoryEntryV1, SimulationDynamicPlayerActionV1, SimulationDynamicWorldEffectV1 } from '../../plugin/simulation_contract.js';
+import type { StorytellerSetbackV2, StorytellerOpportunityV2, StorytellerDecisionV1, StorytellerObservationV1, StorytellerReceiptV1 } from '../../plugin/simulation_storyteller.js';
+import type { DynamicDomainPolicy, DynamicDomainPolicyState } from './dynamic_runtime.js';
+export interface DynamicStorytellerAdapter {
+    setbacks?(state: DynamicDomainPolicyState, actions: readonly SimulationDomainActionProposalV1[], effects: readonly SimulationDynamicWorldEffectV1[]): readonly StorytellerSetbackV2[];
+    opportunity?(state: DynamicDomainPolicyState, choice: SimulationDynamicPlayerActionV1, cause: StorytellerSetbackV2): StorytellerOpportunityV2 | null;
+    relief?(before: DynamicDomainPolicyState, after: DynamicDomainPolicyState, action: SimulationDomainActionProposalV1, effects: readonly SimulationDynamicWorldEffectV1[], cause: StorytellerSetbackV2): StorytellerOpportunityV2 | null;
+    observe(state: DynamicDomainPolicyState): StorytellerObservationV1;
+    pressure(state: DynamicDomainPolicyState, tier: number): readonly SimulationDomainActionProposalV1[];
+    isPressure(action: SimulationDomainActionProposalV1): boolean;
+    classify(state: DynamicDomainPolicyState, actions: readonly SimulationDomainActionProposalV1[], effects: readonly SimulationDynamicWorldEffectV1[]): {
+        readonly pressureActionIds: readonly string[];
+        readonly major: boolean;
+        readonly setbackResourceIds: readonly string[];
+    };
+    recoveryActions(state: DynamicDomainPolicyState): readonly SimulationDomainActionProposalV1[];
+    recovery(state: DynamicDomainPolicyState): readonly SimulationDynamicPlayerActionV1[];
+    recoveryResources(state: DynamicDomainPolicyState, choice: SimulationDynamicPlayerActionV1): readonly string[];
+}
+export declare function storytellerPlan(state: DynamicDomainPolicyState, policy: DynamicDomainPolicy): {
+    decision: StorytellerDecisionV1;
+    pressure: readonly SimulationDomainActionProposalV1[];
+    recovery: readonly SimulationDomainActionProposalV1[];
+} | null;
+export declare function makeStorytellerReceipt(before: DynamicDomainPolicyState, after: DynamicDomainPolicyState, policy: DynamicDomainPolicy, entry: Pick<SimulationDynamicHistoryEntryV1, 'gmProposal' | 'effects'>, choices: readonly SimulationDynamicPlayerActionV1[]): StorytellerReceiptV1 | undefined;
+export declare function assertStorytellerReceipt(before: DynamicDomainPolicyState, after: DynamicDomainPolicyState, policy: DynamicDomainPolicy, entry: SimulationDynamicHistoryEntryV1): void;