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

package/dist/simulation/plugin_host.js

@@ -1,4 +1,6 @@
 /** Private adapter from the public simulation plugin contract to the ZTC kernel. */
+import { createRequire } from 'node:module';
+import { CODEX_REASONING_EFFORTS } from '../config/types.js';
 import { SIMULATION_PLUGIN_API_VERSION } from '../plugin/simulation_contract.js';
 import { llmComplete, SimulationAbortedError } from './llm.js';
 import { getOrchestrator, registerOrchestrator, } from './orchestration/registry.js';
@@ -6,17 +8,28 @@ import { registerSimulationRuntimeBinding } from './runtime_bindings.js';
 import { DEFAULT_SIM_CONFIG } from './types.js';
 import { SIMULATION_CHECKPOINT_VERSION, } from './world/checkpoint.js';
 import { SimState, getSimState, setSimState } from './world/state.js';
+import { validateDocumentWrite, validateSessionDocuments } from './session_documents.js';
 import { getVersion } from '../utils/version.js';
+const require = createRequire(import.meta.url);
+const dynamicStateToolkit = () => require('./toolkit/dynamic_state.js');
+const inputValidation = () => require('./session_input_validation.js');
 const HOST_VERSION = getVersion();
 const HOST_CHECKPOINT_NAMESPACE = 'ztc.host';
 const HOST_CAPABILITIES = Object.freeze([
     'atomic-transitions',
     'checkpoint-extensions',
+    'dynamic-state',
     'notifications',
+    'per-request-inference-routing',
+    'player-commands',
     'provider-inference',
+    'simulation-catalog',
 ]);
 const MAX_RETAINED_SESSIONS = 32;
+const MAX_PLAYER_COMMAND_BYTES = 16_384;
+const MAX_PLAYER_COMMAND_IDS = 256;
 const registrations = new Map();
+const definitions = new Map();
 const sessions = new Map();
 const activeDrivers = new Map();
 const startSignals = new Map();
@@ -89,6 +102,83 @@ function assertCreateRequest(request) {
         throw new Error('Simulation startTime must be an ISO date');
     }
 }
+function assertNonEmptyBoundedString(name, value, maximum) {
+    const length = value.trim().length;
+    if (length === 0 || length > maximum) {
+        throw new RangeError(`${name} must contain from 1 to ${maximum} characters`);
+    }
+}
+function assertDefinition(definition, kind, maximumTurns = 100) {
+    if (definition.kind !== kind) {
+        throw new Error(`Simulation definition kind ${definition.kind} must match driver ${kind}`);
+    }
+    assertNonEmptyBoundedString('Simulation definition title', definition.title, 80);
+    assertNonEmptyBoundedString('Simulation definition summary', definition.summary, 400);
+    assertNonEmptyBoundedString('Simulation definition objective', definition.objective, 400);
+    if (!Number.isSafeInteger(definition.maxTurns) || definition.maxTurns < 1 || definition.maxTurns > maximumTurns) {
+        throw new RangeError(`Simulation definition maxTurns must be an integer from 1 to ${maximumTurns}`);
+    }
+    if (!Number.isSafeInteger(definition.estimatedMinutes)
+        || definition.estimatedMinutes < 1
+        || definition.estimatedMinutes > 1_440) {
+        throw new RangeError('Simulation definition estimatedMinutes must be an integer from 1 to 1440');
+    }
+    for (const [name, values, maximum] of [
+        ['playerRoles', definition.playerRoles, 16],
+        ['mechanics', definition.mechanics, 64],
+    ]) {
+        if (values.length === 0 || values.length > maximum) {
+            throw new RangeError(`Simulation definition ${name} must contain from 1 to ${maximum} values`);
+        }
+        for (const value of values) {
+            assertNonEmptyBoundedString(`Simulation definition ${name} value`, value, 80);
+        }
+        if (new Set(values).size !== values.length) {
+            throw new Error(`Simulation definition ${name} must not contain duplicates`);
+        }
+    }
+}
+function cloneDefinition(definition) {
+    return {
+        ...definition,
+        playerRoles: [...definition.playerRoles],
+        mechanics: [...definition.mechanics],
+    };
+}
+function parsePlayerCommand(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError('Simulation player command must be an object');
+    }
+    const candidate = value;
+    if (typeof candidate.commandId !== 'string') {
+        throw new TypeError('Simulation player command commandId must be a string');
+    }
+    if (typeof candidate.kind !== 'string') {
+        throw new TypeError('Simulation player command kind must be a string');
+    }
+    assertNonEmptyBoundedString('Simulation player command commandId', candidate.commandId, 200);
+    assertNonEmptyBoundedString('Simulation player command kind', candidate.kind, 120);
+    if (candidate.actorId !== undefined
+        && (typeof candidate.actorId !== 'string' || candidate.actorId.trim().length === 0)) {
+        throw new TypeError('Simulation player command actorId must be a non-empty string');
+    }
+    if (candidate.payload === null
+        || typeof candidate.payload !== 'object'
+        || Array.isArray(candidate.payload)) {
+        throw new TypeError('Simulation player command payload must be an object');
+    }
+    const serialized = JSON.stringify(candidate);
+    if (serialized === undefined || Buffer.byteLength(serialized, 'utf8') > MAX_PLAYER_COMMAND_BYTES) {
+        throw new RangeError(`Simulation player command must be at most ${MAX_PLAYER_COMMAND_BYTES} bytes`);
+    }
+    const parsed = JSON.parse(serialized);
+    return {
+        commandId: parsed.commandId,
+        kind: parsed.kind,
+        ...(parsed.actorId === undefined ? {} : { actorId: parsed.actorId }),
+        payload: parsed.payload,
+    };
+}
 function driverKindForState(state) {
     return state.config.runtimeBinding?.kind ?? state.config.orchestration ?? 'gamemaster';
 }
@@ -98,9 +188,28 @@ function makeSessionRecord(state, requestedDriverKind) {
     const restoredPluginData = hostExtension?.data.pluginData;
     const restoredRevision = hostExtension?.data.revision;
     const restoredActorMetadata = hostExtension?.data.actorMetadata;
-    return {
+    const restoredPlayerCommandIds = hostExtension?.data.submittedPlayerCommandIds;
+    const restoredPendingPlayerCommand = hostExtension?.data.pendingPlayerCommand;
+    const restoredDynamicState = hostExtension?.data.dynamicState;
+    const driverKind = requestedDriverKind ?? driverKindForState(state);
+    const revision = typeof restoredRevision === 'number'
+        && Number.isSafeInteger(restoredRevision)
+        && restoredRevision >= 0
+        ? restoredRevision
+        : 0;
+    const dynamicState = restoredDynamicState === undefined || restoredDynamicState === null
+        ? null
+        : dynamicStateToolkit().parseDynamicSimulationState(restoredDynamicState);
+    if (dynamicState !== null
+        && (dynamicState.gameKind !== driverKind || dynamicState.revision !== revision)) {
+        throw new Error('Checkpoint dynamic state does not match its host revision or driver');
+    }
+    validateRegisteredDynamicState(dynamicState, driverKind);
+    const record = {
         state,
-        driverKind: requestedDriverKind ?? driverKindForState(state),
+        inputJournal: hostExtension?.data.inputJournal === undefined ? undefined : inputValidation().parseInputJournal(hostExtension.data.inputJournal),
+        lastTransition: null,
+        driverKind,
         appliedTransitions: new Set(Array.isArray(restoredIds)
             ? restoredIds.filter((value) => typeof value === 'string')
             : []),
@@ -110,18 +219,30 @@ function makeSessionRecord(state, requestedDriverKind) {
             ? Object.entries(restoredActorMetadata)
                 .filter((entry) => (entry[1] !== null && typeof entry[1] === 'object' && !Array.isArray(entry[1])))
             : []),
+        submittedPlayerCommandIds: new Set(Array.isArray(restoredPlayerCommandIds)
+            ? restoredPlayerCommandIds
+                .filter((value) => typeof value === 'string')
+                .slice(-MAX_PLAYER_COMMAND_IDS)
+            : []),
+        pendingPlayerCommand: restoredPendingPlayerCommand === undefined
+            || restoredPendingPlayerCommand === null
+            ? null
+            : parsePlayerCommand(restoredPendingPlayerCommand),
+        dynamicState,
         pluginData: restoredPluginData !== null
             && typeof restoredPluginData === 'object'
             && !Array.isArray(restoredPluginData)
             ? structuredClone(restoredPluginData)
             : {},
         status: 'ready',
-        revision: typeof restoredRevision === 'number'
-            && Number.isSafeInteger(restoredRevision)
-            && restoredRevision >= 0
-            ? restoredRevision
-            : 0,
+        revision,
     };
+    if (record.inputJournal)
+        inputValidation().validateSessionInputSnapshot(toSnapshot(record));
+    else
+        validateSessionDocuments(toSnapshot(record));
+    validateRegisteredDocuments(record);
+    return record;
 }
 function ensureSessionRecord(state, requestedDriverKind) {
     const existing = sessions.get(state.id);
@@ -149,6 +270,8 @@ function requireSessionRecord(ref) {
 }
 function toDocumentSnapshot(document) {
     return {
+        ...(document.provenance === undefined ? {} : { provenance: structuredClone(document.provenance) }),
+        ...(document.ownerActorId === undefined ? {} : { ownerActorId: document.ownerActorId }),
         documentId: document.id,
         label: document.label,
         type: document.type,
@@ -185,6 +308,7 @@ function toSnapshot(record) {
         })
         : null;
     return {
+        ...(record.inputJournal === undefined ? {} : { inputJournal: structuredClone(record.inputJournal) }),
         ref: sessionRef(record),
         status: record.status,
         revision: record.revision,
@@ -203,6 +327,9 @@ function toSnapshot(record) {
         })),
         documents: state.getDocumentTrail().map(toDocumentSnapshot),
         world,
+        dynamicState: record.dynamicState === null
+            ? null
+            : structuredClone(record.dynamicState),
         pluginData: asJsonObject(record.pluginData),
     };
 }
@@ -279,7 +406,11 @@ function applyOperation(record, operation) {
             });
             return;
         case 'document.write':
+            if (operation.ownerActorId !== undefined)
+                validateDocumentWrite(toSnapshot(record), operation);
             record.state.addDocument({
+                ...(operation.provenance === undefined ? {} : { provenance: structuredClone(operation.provenance) }),
+                ...(operation.ownerActorId === undefined ? {} : { ownerActorId: operation.ownerActorId }),
                 type: operation.documentType,
                 label: operation.label,
                 content: operation.content,
@@ -289,6 +420,11 @@ function applyOperation(record, operation) {
                 revisionOf: operation.revisionOf,
             });
             return;
+        case 'session-inputs.resolve':
+            if (!record.inputJournal)
+                throw new Error('Session inputs are unavailable');
+            record.inputJournal.resolutions.push(...structuredClone(operation.resolutions));
+            return;
         case 'document.comment': {
             const result = record.state.addDocumentComment(operation.label, operation.author, operation.text, operation.authorActorId, operation.parentId, operation.sectionRef);
             if (!result.ok) {
@@ -298,10 +434,51 @@ function applyOperation(record, operation) {
         }
         case 'plugin-data.set':
             record.pluginData[operation.namespace] = asJsonObject(operation.value);
+            return;
+        case 'dynamic-state.commit': {
+            const next = dynamicStateToolkit().validateDynamicStateTransition({
+                previous: record.dynamicState,
+                next: operation.state,
+                driverKind: record.driverKind,
+                hostRevision: record.revision,
+            });
+            validateRegisteredDynamicState(next, record.driverKind);
+            if (next.history.at(-1)?.objectGraphBefore === undefined) {
+                throw new Error('A new dynamic state commit requires action-time context');
+            }
+            record.dynamicState = next;
+            return;
+        }
     }
 }
-function restoreTransitionMetadata(record, pluginData, revision, appliedTransitions) {
+const detachedValidators = new Map();
+/** Register canonical checkpoint validators without loading a driver or claiming its inference boundary. */
+export function registerSimulationCheckpointValidators(kind, validators) {
+    if (!kind.trim() || !validators.validateDynamicState || !validators.validateDocuments)
+        throw new Error('Checkpoint validators require a kind and both canonical validators');
+    detachedValidators.set(kind, validators);
+}
+function validateRegisteredDynamicState(state, driverKind) {
+    if (state === null)
+        return;
+    const validate = registrations.get(driverKind)?.validateDynamicState ?? detachedValidators.get(driverKind)?.validateDynamicState;
+    if (validate === undefined && state.initialization === null)
+        return;
+    if (validate === undefined)
+        throw new Error('Dynamic policy validator is unavailable');
+    validate(state);
+}
+function validateRegisteredDocuments(record) {
+    const validate = registrations.get(record.driverKind)?.validateDocuments ?? detachedValidators.get(record.driverKind)?.validateDocuments;
+    const initialization = record.dynamicState?.initialization;
+    if (initialization?.version === 2 && initialization.documents && !validate) {
+        throw new Error('Document policy validator is unavailable');
+    }
+    validate?.(toSnapshot(record));
+}
+function restoreTransitionMetadata(record, pluginData, dynamicState, revision, appliedTransitions) {
     record.pluginData = pluginData;
+    record.dynamicState = dynamicState;
     record.revision = revision;
     record.appliedTransitions.clear();
     for (const key of appliedTransitions)
@@ -314,26 +491,48 @@ async function applyTransition(record, batch) {
     if (batch.expectedRevision !== record.revision) {
         throw new Error(`Simulation transition expected revision ${batch.expectedRevision}; current revision is ${record.revision}`);
     }
+    if (record.inputJournal || batch.operations.some(operation => operation.operation === 'session-inputs.resolve')) {
+        inputValidation().validateInputTransition(toSnapshot(record), batch);
+    }
+    const advanceTimeSteps = batch.advanceTimeSteps ?? 1;
+    if (!Number.isSafeInteger(advanceTimeSteps) || advanceTimeSteps < 1 || advanceTimeSteps > 12) {
+        throw new RangeError('Simulation advanceTimeSteps must be an integer from 1 to 12');
+    }
+    const dynamicCommits = batch.operations.filter(operation => (operation.operation === 'dynamic-state.commit')).length;
+    if ((record.dynamicState !== null || dynamicCommits > 0) && dynamicCommits !== 1) {
+        throw new Error('A dynamic transition must contain exactly one dynamic state commit');
+    }
     const joinedPeriod = record.state.getActiveWorldTransitionPeriodNumber();
     if (joinedPeriod !== null) {
         if (batch.periodNumber !== undefined && batch.periodNumber !== joinedPeriod) {
             throw new Error(`Simulation transition period ${batch.periodNumber} does not match active world period ${joinedPeriod}`);
         }
+        const inputsBefore = structuredClone(record.inputJournal);
+        const lastTransitionBefore = record.lastTransition;
         const pluginDataBefore = structuredClone(record.pluginData);
+        const dynamicStateBefore = record.dynamicState === null
+            ? null
+            : structuredClone(record.dynamicState);
         const revisionBefore = record.revision;
         const appliedTransitionsBefore = new Set(record.appliedTransitions);
         try {
             for (const operation of batch.operations)
                 applyOperation(record, operation);
+            validateRegisteredDocuments(record);
             record.revision += 1;
             record.appliedTransitions.add(batch.idempotencyKey);
+            record.lastTransition = structuredClone(batch);
             record.state.registerWorldTransitionRollback(() => {
-                restoreTransitionMetadata(record, pluginDataBefore, revisionBefore, appliedTransitionsBefore);
+                record.inputJournal = inputsBefore;
+                record.lastTransition = lastTransitionBefore;
+                restoreTransitionMetadata(record, pluginDataBefore, dynamicStateBefore, revisionBefore, appliedTransitionsBefore);
             });
             return { applied: true, revision: record.revision };
         }
         catch (error) {
-            restoreTransitionMetadata(record, pluginDataBefore, revisionBefore, appliedTransitionsBefore);
+            record.inputJournal = inputsBefore;
+            record.lastTransition = lastTransitionBefore;
+            restoreTransitionMetadata(record, pluginDataBefore, dynamicStateBefore, revisionBefore, appliedTransitionsBefore);
             throw error;
         }
     }
@@ -345,21 +544,31 @@ async function applyTransition(record, batch) {
         }
     }
     const pluginDataBefore = structuredClone(record.pluginData);
+    const inputJournalBefore = structuredClone(record.inputJournal);
+    const dynamicStateBefore = record.dynamicState === null
+        ? null
+        : structuredClone(record.dynamicState);
     const proposal = record.state.beginWorldTransition(batch.kind, batch.periodNumber);
     try {
         if (batch.periodNumber !== undefined) {
             record.state.setRuntimePeriodNumber(batch.periodNumber);
-            record.state.advanceTime();
+            for (let step = 0; step < advanceTimeSteps; step += 1) {
+                record.state.advanceTime();
+            }
         }
         for (const operation of batch.operations)
             applyOperation(record, operation);
+        validateRegisteredDocuments(record);
         record.state.commitWorldTransition(proposal.id);
         record.revision += 1;
         record.appliedTransitions.add(batch.idempotencyKey);
+        record.lastTransition = structuredClone(batch);
         return { applied: true, revision: record.revision };
     }
     catch (error) {
+        record.inputJournal = inputJournalBefore;
         record.pluginData = pluginDataBefore;
+        record.dynamicState = dynamicStateBefore;
         record.state.rollbackWorldTransition(proposal.id, error);
         if (previousPeriod === null)
             record.state.clearRuntimePeriodNumber();
@@ -386,9 +595,33 @@ function hostCheckpointExtension(record) {
             appliedTransitionIds: [...record.appliedTransitions].sort(),
             pluginData: record.pluginData,
             actorMetadata: Object.fromEntries(record.actorMetadata),
+            submittedPlayerCommandIds: [...record.submittedPlayerCommandIds].sort(),
+            pendingPlayerCommand: record.pendingPlayerCommand === null
+                ? null
+                : asJsonObject(record.pendingPlayerCommand),
+            dynamicState: record.dynamicState === null
+                ? null
+                : asJsonObject(record.dynamicState),
+            ...(record.inputJournal === undefined ? {} : { inputJournal: asJsonObject(record.inputJournal) }),
         },
     };
 }
+export async function detachedSessionRecord(checkpoint) {
+    return makeSessionRecord(await SimState.fromCheckpoint(structuredClone(checkpoint), undefined, true));
+}
+export function detachedSessionSnapshot(record) {
+    return toSnapshot(record);
+}
+export function detachedSessionCheckpoint(record, source) {
+    const extensions = source.extensions;
+    return asJsonObject(record.state.createCheckpoint({ ...extensions, [HOST_CHECKPOINT_NAMESPACE]: hostCheckpointExtension(record) }));
+}
+export async function applyDetachedSessionTransition(record, batch) {
+    await applyTransition(record, batch);
+}
+export function getOriginalSessionTransition(ref) {
+    return structuredClone(requireSessionRecord(ref).lastTransition);
+}
 export function saveSimulationSessionCheckpoint(state, outputPath) {
     const record = ensureSessionRecord(state);
     return state.saveCheckpoint(outputPath, {
@@ -432,7 +665,7 @@ async function loadRegisteredDriver(kind) {
     }
     return driver;
 }
-function createDriverContext(record, controller, notify) {
+function createDriverContext(record, controller, notify, playerCommand = null) {
     const requireActiveAuthority = () => {
         const active = activeDrivers.get(record.state.id);
         if (record.status !== 'running'
@@ -449,6 +682,7 @@ function createDriverContext(record, controller, notify) {
                 return applyTransition(record, batch);
             },
         },
+        playerCommand: playerCommand === null ? null : parsePlayerCommand(playerCommand),
         signal: controller.signal,
         notify,
         completeInference: (request) => {
@@ -458,6 +692,14 @@ function createDriverContext(record, controller, notify) {
     };
 }
 async function completeInference(request, signal) {
+    const routing = request.routing;
+    if (routing !== undefined && (routing === null || typeof routing !== 'object'
+        || !['character', 'game-master'].includes(routing.role)
+        || typeof routing.provider !== 'string' || !routing.provider.trim()
+        || typeof routing.model !== 'string' || !routing.model.trim()
+        || !CODEX_REASONING_EFFORTS.includes(routing.reasoningEffort)
+        || (routing.serviceTier !== undefined && routing.serviceTier !== 'priority')))
+        throw new Error('Invalid simulation inference route');
     const text = await llmComplete(request.system, request.user, request.maxTokens, request.timeoutMs, {
         stage: request.context.stage,
         periodNumber: request.context.periodNumber,
@@ -466,7 +708,14 @@ async function completeInference(request, signal) {
         requestId: request.context.requestId,
         component: request.context.component,
         attempt: request.context.attempt,
-    }, signal);
+    }, signal, routing === undefined
+        ? undefined
+        : {
+            provider: routing.provider,
+            model: routing.model,
+            codexEffort: routing.reasoningEffort,
+            codexFastMode: routing.serviceTier === 'priority',
+        }, undefined, request.outputSchema, request.outputSchemaStrict, request.bufferedRecovery === undefined ? undefined : { ...request.bufferedRecovery, onAttempt: request.onTransportAttempt });
     return { text };
 }
 function pruneSessionRecords() {
@@ -501,7 +750,8 @@ async function makePrivateOrchestrator(kind) {
                 if (notification.type === 'progress')
                     onProgress(notification.message);
             };
-            const context = createDriverContext(record, controller, notify);
+            const playerCommand = record.pendingPlayerCommand;
+            const context = createDriverContext(record, controller, notify, playerCommand);
             if (controller.signal.aborted) {
                 throw new SimulationAbortedError('Simulation stopped');
             }
@@ -517,6 +767,10 @@ async function makePrivateOrchestrator(kind) {
                 if (controller.signal.aborted) {
                     throw new SimulationAbortedError('Simulation stopped');
                 }
+                if (playerCommand !== null
+                    && record.pendingPlayerCommand?.commandId === playerCommand.commandId) {
+                    record.pendingPlayerCommand = null;
+                }
                 record.status = 'completed';
                 onComplete('Simulation completed');
             }
@@ -548,6 +802,9 @@ export function validateSimulationDriverRegistration(registration) {
     assertCompatibility(registration.compatibility);
     if (!registration.kind.trim())
         throw new Error('Simulation driver kind must not be empty');
+    if (registration.definition !== undefined) {
+        assertDefinition(registration.definition, registration.kind, registration.validateDynamicState === undefined ? 100 : Number.MAX_SAFE_INTEGER);
+    }
     if (registrations.has(registration.kind) || getOrchestrator(registration.kind)) {
         throw new Error(`Simulation driver ${registration.kind} is already registered`);
     }
@@ -555,6 +812,9 @@ export function validateSimulationDriverRegistration(registration) {
 export function registerSimulationDriver(registration) {
     validateSimulationDriverRegistration(registration);
     registrations.set(registration.kind, registration);
+    if (registration.definition !== undefined) {
+        definitions.set(registration.kind, cloneDefinition(registration.definition));
+    }
     registerOrchestrator(registration.kind, () => makePrivateOrchestrator(registration.kind));
     registerSimulationRuntimeBinding(registration.kind, {
         rehydrate: async (state, context) => {
@@ -575,8 +835,21 @@ const simulationHost = {
         checkpointSchemaVersions: [SIMULATION_CHECKPOINT_VERSION],
         capabilities: HOST_CAPABILITIES,
     },
+    listSimulationDefinitions() {
+        return [...definitions.values()]
+            .sort((left, right) => left.title.localeCompare(right.title))
+            .map(cloneDefinition);
+    },
     async createSession(request) {
         assertCreateRequest(request);
+        const requestedDynamicState = request.dynamicState === undefined
+            ? null
+            : dynamicStateToolkit().parseDynamicSimulationState(request.dynamicState);
+        if (requestedDynamicState !== null
+            && (requestedDynamicState.gameKind !== request.driverKind || requestedDynamicState.revision !== 0)) {
+            throw new Error('Initial dynamic state must match its driver at revision zero');
+        }
+        validateRegisteredDynamicState(requestedDynamicState, request.driverKind);
         pruneSessionRecords();
         if (!registrations.has(request.driverKind) && request.driverKind !== 'gamemaster') {
             throw new Error(`Simulation driver ${request.driverKind} is not registered`);
@@ -613,18 +886,37 @@ const simulationHost = {
             if (actor.metadata)
                 actorMetadata.set(created.id, structuredClone(actor.metadata));
         }
-        setSimState(state);
-        const record = ensureSessionRecord(state, request.driverKind);
+        const record = makeSessionRecord(state, request.driverKind);
         for (const [actorId, metadata] of actorMetadata) {
             record.actorMetadata.set(actorId, metadata);
         }
+        if (request.dynamicState !== undefined) {
+            record.dynamicState = requestedDynamicState;
+        }
         if (request.pluginData)
             record.pluginData.root = asJsonObject(request.pluginData);
+        try {
+            if (requestedDynamicState !== null) {
+                const documents = registrations.get(request.driverKind)?.initializeDocuments?.(requestedDynamicState) ?? [];
+                for (const document of documents)
+                    applyOperation(record, document);
+            }
+            validateRegisteredDocuments(record);
+        }
+        catch (error) {
+            state.close();
+            throw error;
+        }
+        sessions.set(state.id, record);
+        setSimState(state);
         return makeSession(record);
     },
     async loadSession(request) {
         pruneSessionRecords();
-        const state = await SimState.loadCheckpoint(request.checkpointPath);
+        if (request.outputDirectory !== undefined && request.outputDirectory.trim() === '') {
+            throw new Error('Simulation output directory cannot be empty');
+        }
+        const state = await SimState.loadCheckpoint(request.checkpointPath, request.outputDirectory);
         try {
             const checkpointDriverKind = driverKindForState(state);
             if (request.driverKind !== undefined && request.driverKind !== checkpointDriverKind) {
@@ -656,6 +948,31 @@ const simulationHost = {
         const record = sessions.get(ref.sessionId);
         return record && record.driverKind === ref.driverKind ? makeSession(record) : null;
     },
+    async submitPlayerCommand(ref, command) {
+        const record = requireSessionRecord(ref);
+        if (sessionRuns.has(record.state.id) || ['running', 'stopping'].includes(record.status)) {
+            throw new Error(`Simulation session ${record.state.id} cannot accept a command while running`);
+        }
+        const parsed = parsePlayerCommand(command);
+        if (record.submittedPlayerCommandIds.has(parsed.commandId)) {
+            return { accepted: false };
+        }
+        if (record.pendingPlayerCommand !== null) {
+            throw new Error(`Simulation session ${record.state.id} already has a pending player command`);
+        }
+        if (record.submittedPlayerCommandIds.size >= MAX_PLAYER_COMMAND_IDS) {
+            throw new Error(`Simulation session ${record.state.id} reached its ${MAX_PLAYER_COMMAND_IDS}-command bound`);
+        }
+        if (parsed.actorId !== undefined) {
+            const actor = record.state.getAllAgents().find(candidate => candidate.id === parsed.actorId);
+            if (actor?.humanControlled !== true) {
+                throw new Error(`Simulation player command actorId must name a human-controlled actor in session ${record.state.id}`);
+            }
+        }
+        record.pendingPlayerCommand = parsed;
+        record.submittedPlayerCommandIds.add(parsed.commandId);
+        return { accepted: true };
+    },
     async startSession(request) {
         const record = requireSessionRecord(request.ref);
         if (sessionRuns.has(record.state.id) || ['running', 'stopping'].includes(record.status)) {

package/dist/simulation/session_documents.d.ts

@@ -0,0 +1,20 @@
+import type { SimulationDocumentWriteV1, SimulationSessionSnapshotV1 } from '../plugin/simulation_contract.js';
+import type { SimulationAuthorizedDocumentV1 } from '../plugin/simulation_interventions.js';
+export declare class SimulationInputError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare const fail: (code: string, message: string) => never;
+export declare function inputActorId(actor: SimulationSessionSnapshotV1['actors'][number]): string;
+export declare function actors(snapshot: SimulationSessionSnapshotV1): {
+    actorId: string;
+    name: string;
+    role: string;
+    organization?: string;
+    humanControlled: boolean;
+    currentAction?: string;
+    metadata?: import("../plugin/simulation_contract.js").SimulationJsonObjectV1;
+}[];
+export declare function validateDocumentWrite(snapshot: SimulationSessionSnapshotV1, write: SimulationDocumentWriteV1): void;
+export declare function sessionDocuments(snapshot: SimulationSessionSnapshotV1): SimulationAuthorizedDocumentV1[];
+export declare function validateSessionDocuments(snapshot: SimulationSessionSnapshotV1): void;

package/dist/simulation/session_documents.js

@@ -0,0 +1,62 @@
+import { isDeepStrictEqual } from 'node:util';
+export class SimulationInputError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SimulationInputError';
+    }
+}
+export const fail = (code, message) => { throw new SimulationInputError(code, message); };
+export function inputActorId(actor) {
+    return typeof actor.metadata?.dynamicActorId === 'string' ? actor.metadata.dynamicActorId : actor.actorId;
+}
+export function actors(snapshot) { return snapshot.actors.map(actor => ({ ...actor, actorId: inputActorId(actor) })); }
+export function validateDocumentWrite(snapshot, write) {
+    const roster = actors(snapshot);
+    if (!write.ownerActorId || !roster.some(actor => actor.actorId === write.ownerActorId)
+        || !write.recipientActorIds.includes(write.ownerActorId) || new Set(write.recipientActorIds).size !== write.recipientActorIds.length
+        || write.recipientActorIds.some(id => !roster.some(actor => actor.actorId === id)))
+        fail('recipient_invalid', 'Document owner and recipients must name the exact cast');
+    if (Buffer.byteLength(write.content, 'utf8') > 8192)
+        fail('body_too_large', 'Document exceeds its byte limit');
+    if (write.revisionOf) {
+        const prior = snapshot.documents.find(doc => doc.documentId === write.revisionOf);
+        if (!prior || snapshot.documents.some(doc => doc.revisionOf === prior.documentId)
+            || prior.ownerActorId !== write.ownerActorId || !isDeepStrictEqual(prior.recipientActorIds, write.recipientActorIds))
+            fail('document_version_conflict', 'Document version or recipients changed');
+    }
+}
+export function sessionDocuments(snapshot) {
+    const byId = new Map(snapshot.documents.map(doc => [doc.documentId, doc]));
+    return snapshot.documents.filter(doc => doc.ownerActorId !== undefined).map(doc => {
+        let root = doc;
+        let version = 1;
+        const seen = new Set([doc.documentId]);
+        while (root.revisionOf) {
+            const parent = byId.get(root.revisionOf);
+            if (!parent || seen.has(parent.documentId))
+                return fail('input_state_invalid', 'Document version chain is invalid');
+            seen.add(parent.documentId);
+            root = parent;
+            version += 1;
+        }
+        return { ...(doc.provenance === undefined ? {} : { provenance: structuredClone(doc.provenance) }), documentId: root.documentId, versionId: doc.documentId, version, ownerActorId: doc.ownerActorId, recipientActorIds: doc.recipientActorIds, body: doc.content, label: doc.label };
+    });
+}
+export function validateSessionDocuments(snapshot) {
+    sessionDocuments(snapshot);
+    for (const [index, doc] of snapshot.documents.entries()) {
+        if (doc.ownerActorId === undefined)
+            continue;
+        try {
+            validateDocumentWrite({ ...snapshot, documents: snapshot.documents.slice(0, index) }, {
+                operation: 'document.write', ownerActorId: doc.ownerActorId, recipientActorIds: doc.recipientActorIds,
+                label: doc.label, documentType: doc.type, content: doc.content, createdBy: doc.createdBy, revisionOf: doc.revisionOf,
+            });
+        }
+        catch {
+            fail('input_state_invalid', 'Session input references are invalid');
+        }
+    }
+}