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

package/dist/simulation/toolkit/dynamic_storyteller_runtime.js

@@ -0,0 +1,126 @@
+import { isDeepStrictEqual } from 'node:util';
+import { planStoryteller, storytellerMemory, pendingStorytellerSetbacks } from './dynamic_storyteller.js';
+export function storytellerPlan(state, policy) {
+    if (state.initialization === null)
+        return null;
+    if (policy.storyteller === undefined)
+        throw new Error('Storyteller policy is unavailable');
+    const receipts = state.history.flatMap(entry => entry.storyteller === undefined ? [] : [entry.storyteller]);
+    let decision = planStoryteller({ initialization: state.initialization, revision: state.revision,
+        observation: policy.storyteller.observe(state), receipts });
+    const review = policy.storyReviewVersion === 1 ? state.history.at(-1)?.storyReview : undefined;
+    const requested = review?.revision === state.revision && review.status === 'accepted' && review.decision?.kind === 'stalled' && review.decision.requestPressure;
+    if (requested)
+        decision = { ...decision, mode: 'pressure', strengthTier: Math.max(1, decision.strengthTier) };
+    const pressure = decision.mode === 'pressure' ? policy.storyteller.pressure(state, decision.strengthTier).filter(action => !requested || action.actorId === undefined) : [];
+    const recovery = decision.offerRecovery && pressure.length === 0 ? policy.storyteller.recoveryActions(state) : [];
+    return { decision, pressure, recovery };
+}
+export function makeStorytellerReceipt(before, after, policy, entry, choices) {
+    const plan = storytellerPlan(before, policy);
+    if (plan === null)
+        return undefined;
+    const adapter = policy.storyteller;
+    if (before.initialization.storyteller.policyVersion === 'storyteller-2') {
+        if (!adapter.setbacks || !adapter.opportunity || !adapter.relief)
+            throw new Error('Cause-linked recovery policy is unavailable');
+        const receipts = before.history.flatMap(item => item.storyteller ? [item.storyteller] : []);
+        const pending = pendingStorytellerSetbacks(receipts);
+        const setbacks = adapter.setbacks(before, entry.gmProposal.domainActions, entry.effects);
+        const reliefStates = new Map();
+        let rolling = before;
+        for (const action of entry.gmProposal.domainActions) {
+            reliefStates.set(action.id, rolling);
+            const resources = { ...rolling.world.resources };
+            const objects = new Map(rolling.world.domainObjects.map(object => [object.id, object]));
+            const facts = new Set(rolling.world.facts);
+            for (const effect of entry.effects.filter(effect => effect.actionId === action.id)) {
+                if (effect.operation === 'resource.change')
+                    resources[effect.resourceId] = resources[effect.resourceId] + effect.delta;
+                if (effect.operation === 'object.put') {
+                    objects.set(effect.object.id, effect.object);
+                    for (const retiredId of effect.sceneRetention?.retiredIds ?? [])
+                        objects.delete(retiredId);
+                }
+                if (effect.operation === 'fact.add')
+                    facts.add(effect.fact);
+                if (effect.operation === 'fact.remove')
+                    facts.delete(effect.fact);
+            }
+            let agents = rolling.agents;
+            if (action.actorId !== undefined) {
+                // The host quotes the accepted batch against its opening state.
+                const quote = policy.quotePersonalResource(before, { actorId: action.actorId, mechanic: action.mechanic,
+                    intent: action.parameters.intent,
+                    ...(action.targetActorId ? { targetActorId: action.targetActorId } : {}) });
+                agents = agents.map(actor => actor.actorId === action.actorId ? { ...actor, resources: {
+                        ...actor.resources, [quote.resourceId]: actor.resources[quote.resourceId] - quote.cost
+                    } } : actor);
+            }
+            rolling = { ...rolling, agents, world: { resources, domainObjects: [...objects.values()], facts: [...facts] } };
+        }
+        const opportunities = pending.flatMap(cause => {
+            if (after.revision <= cause.revision)
+                return [];
+            if (after.status === 'active')
+                for (const choice of choices) {
+                    const proof = adapter.opportunity(after, choice, cause);
+                    if (proof)
+                        return [proof];
+                }
+            for (const action of entry.gmProposal.domainActions) {
+                const proof = adapter.relief(reliefStates.get(action.id), after, action, entry.effects.filter(effect => effect.actionId === action.id), cause);
+                if (proof)
+                    return [proof];
+            }
+            return [];
+        });
+        const publicCauses = setbacks.filter(cause => !cause.private);
+        return { decision: plan.decision, proposedPressure: plan.pressure, proposedRecovery: plan.recovery,
+            acceptedPressureActionIds: adapter.classify(before, entry.gmProposal.domainActions, entry.effects).pressureActionIds,
+            majorCrisis: publicCauses.some(cause => cause.major), setbackResourceIds: [...new Set(publicCauses.flatMap(cause => cause.resourceIds))],
+            recoveryChoiceIds: [...new Set(opportunities.filter(proof => !pending.find(cause => cause.id === proof.causeId).private).flatMap(proof => proof.choiceId ? [proof.choiceId] : []))].slice(0, 1),
+            recoveryForRevisions: [...new Set(pending.filter(cause => pending.filter(other => other.revision === cause.revision)
+                    .every(other => opportunities.some(proof => proof.causeId === other.id))).map(cause => cause.revision))],
+            recovery: { version: 2, setbacks, opportunities } };
+    }
+    const classified = adapter.classify(before, entry.gmProposal.domainActions, entry.effects);
+    const receipts = before.history.flatMap(item => item.storyteller === undefined ? [] : [item.storyteller]);
+    const memory = storytellerMemory(before.initialization, receipts);
+    const recoveryChoices = choices.filter(choice => choice.id.startsWith(`storyteller-recovery-${after.revision}-`));
+    const helped = new Set(recoveryChoices.flatMap(choice => adapter.recoveryResources(after, choice)));
+    // Beneficial accepted world actions also supply recovery without inventing a choice.
+    for (const effect of entry.effects) {
+        if (effect.operation !== 'resource.change')
+            continue;
+        const resource = policy.resources.find(item => item.id === effect.resourceId);
+        if (resource?.visibility !== 'private' && ((resource?.dangerDirection === 'low' && effect.delta > 0)
+            || (resource?.dangerDirection === 'high' && effect.delta < 0)))
+            helped.add(effect.resourceId);
+    }
+    const recoveryForRevisions = memory.setbacks.filter(revision => {
+        const setback = before.history.find(item => item.revision === revision)?.storyteller;
+        return setback !== undefined && setback.setbackResourceIds.every(id => helped.has(id));
+    });
+    return { decision: plan.decision, proposedPressure: plan.pressure, proposedRecovery: plan.recovery,
+        acceptedPressureActionIds: classified.pressureActionIds,
+        majorCrisis: classified.major, setbackResourceIds: classified.setbackResourceIds,
+        recoveryChoiceIds: recoveryChoices.map(choice => choice.id), recoveryForRevisions };
+}
+export function assertStorytellerReceipt(before, after, policy, entry) {
+    const expected = makeStorytellerReceipt(before, after, policy, entry, entry.gmProposal.availableActions);
+    if (!isDeepStrictEqual(expected, entry.storyteller))
+        throw new Error('Storyteller receipt does not match accepted history');
+    if (expected === undefined || before.agencyVersion === 'emergent-v1')
+        return;
+    const receipts = before.history.flatMap(item => item.storyteller === undefined ? [] : [item.storyteller]);
+    const memory = storytellerMemory(before.initialization, receipts);
+    if (before.initialization.storyteller.policyVersion === 'storyteller-1' && memory.quiet >= expected.decision.quietLimit && expected.acceptedPressureActionIds.length === 0 && after.status === 'active') {
+        throw new Error('Storyteller pressure unavailable at quiet limit');
+    }
+    if (entry.gmProposal.domainActions.some(action => action.actorId === undefined && policy.storyteller.isPressure(action)
+        && !expected.proposedPressure.some(scheduled => scheduled.id === action.id && scheduled.mechanic === action.mechanic
+            && scheduled.targetActorId === action.targetActorId && isDeepStrictEqual(scheduled.parameters, action.parameters)))) {
+        throw new Error('Storyteller pressure was not scheduled');
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { SimulationDomainActionProposalV1, SimulationDynamicDomainObjectV1, SimulationDynamicWorldEffectV1, SimulationDynamicWorldStateV1 } from '../../plugin/simulation_contract.js';
+export declare class DynamicWorldStateError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface DynamicWorldEffectContextV1 {
+    readonly agencyVersion?: 'emergent-v1';
+    readonly revision: number;
+    readonly eventId: string;
+    readonly actorIds: readonly string[];
+    readonly actionIds: readonly string[];
+    readonly knownActionIds: readonly string[];
+    readonly eventIds: readonly string[];
+    readonly documentIds: readonly string[];
+}
+export declare function applyDynamicWorldEffects(worldValue: SimulationDynamicWorldStateV1 & {
+    readonly domainObjects?: readonly SimulationDynamicDomainObjectV1[];
+}, effects: readonly SimulationDynamicWorldEffectV1[], context: DynamicWorldEffectContextV1): SimulationDynamicWorldStateV1 & {
+    readonly domainObjects: readonly SimulationDynamicDomainObjectV1[];
+};
+export declare function sceneRecordsToRetire(objects: readonly SimulationDynamicDomainObjectV1[], revision: number): string[];
+export declare function applyDynamicWorldActions(worldValue: SimulationDynamicWorldStateV1, actions: readonly SimulationDomainActionProposalV1[]): SimulationDynamicWorldStateV1;

package/dist/simulation/toolkit/dynamic_world.js

@@ -0,0 +1,377 @@
+import { isDeepStrictEqual } from 'node:util';
+const ACTION_PARAMETER_KEYS = new Set(['worldDeltas', 'factsToAdd', 'factsToRemove']);
+export class DynamicWorldStateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DynamicWorldStateError';
+    }
+}
+export function applyDynamicWorldEffects(worldValue, effects, context) {
+    if (!Number.isSafeInteger(context.revision) || context.revision < 1) {
+        fail('effect-context-invalid', 'Effect revision is invalid');
+    }
+    assertIdentifier(context.eventId, 'effect event');
+    assertUnique(context.actorIds, 'actor-identifiers-invalid');
+    assertUnique(context.actionIds, 'action-identifiers-invalid');
+    assertUnique(context.knownActionIds, 'action-identifiers-invalid');
+    assertUnique(context.eventIds, 'event-identifiers-invalid');
+    assertUnique(context.documentIds, 'document-identifiers-invalid');
+    if (!context.eventIds.includes(context.eventId)) {
+        fail('effect-context-invalid', 'Effect event is not in the known event set');
+    }
+    if (context.actionIds.some(actionId => !context.knownActionIds.includes(actionId))) {
+        fail('effect-context-invalid', 'Current effects need known action identifiers');
+    }
+    if (effects.length > 64)
+        fail('effect-count-invalid', 'A beat may commit at most 64 effects');
+    const world = {
+        resources: { ...worldValue.resources },
+        facts: [...worldValue.facts],
+        domainObjects: (worldValue.domainObjects ?? []).map(object => structuredClone(object)),
+    };
+    validateDomainObjects(world.domainObjects, context);
+    for (const effect of effects) {
+        assertIdentifier(effect.actionId, 'effect action');
+        if (!context.actionIds.includes(effect.actionId)) {
+            fail('effect-action-invalid', `Effect action ${effect.actionId} is unavailable`);
+        }
+        if (effect.operation === 'resource.change') {
+            applyResourceChange(world, effect);
+        }
+        else if (effect.operation === 'object.put') {
+            applyObjectPut(world, effect, context);
+            if (effect.sceneRetention !== undefined)
+                retireSceneRecords(world, effect, context);
+        }
+        else {
+            applyFactChange(world, effect);
+        }
+    }
+    validateDomainObjects(world.domainObjects, context);
+    return world;
+}
+// Retire only the transient scene projection. Committed effects retain the full message history.
+function retireSceneRecords(world, effect, context) {
+    if (effect.sceneRetention?.version !== 1 || effect.object.kind !== 'scene-attempt') {
+        fail('scene-retention-invalid', 'Only versioned scene attempts can retire transient scene records');
+    }
+    const retiredIds = sceneRecordsToRetire(world.domainObjects, context.revision);
+    if (!isDeepStrictEqual(effect.sceneRetention.retiredIds, retiredIds)) {
+        fail('scene-retention-invalid', 'Scene retirement must match the deterministic transient retention plan');
+    }
+    const retired = new Set(retiredIds);
+    world.domainObjects = world.domainObjects.filter(object => !retired.has(object.id));
+}
+export function sceneRecordsToRetire(objects, revision) {
+    const records = objects.filter(object => object.kind === 'scene-attempt' || object.kind === 'scene-message');
+    const current = records.filter(object => object.provenance.updatedRevision === revision);
+    if (current.length > 28)
+        fail('scene-retention-capacity', 'Current scene consequences exceed the retained scene budget');
+    const recent = records.filter(object => object.provenance.updatedRevision < revision
+        && object.provenance.updatedRevision > revision - 4)
+        .sort((a, b) => b.provenance.updatedRevision - a.provenance.updatedRevision || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+    const retained = new Set([...current, ...recent.slice(0, 28 - current.length)].map(object => object.id));
+    return records.filter(object => !retained.has(object.id)).map(object => object.id).sort();
+}
+function applyResourceChange(world, effect) {
+    assertIdentifier(effect.resourceId, 'resource');
+    const before = world.resources[effect.resourceId];
+    if (before === undefined) {
+        fail('resource-unknown', `Resource ${effect.resourceId} is unavailable`);
+    }
+    if (!Number.isFinite(effect.delta)) {
+        fail('resource-delta-invalid', 'Resource deltas must be finite numbers');
+    }
+    if (effect.delta === 0) {
+        fail('effect-noop-invalid', 'A resource effect must change its resource');
+    }
+    const after = before + effect.delta;
+    if (!Number.isFinite(after) || after < -1_000_000 || after > 1_000_000) {
+        fail('resource-out-of-bounds', `Resource ${effect.resourceId} is outside its bounds`);
+    }
+    world.resources[effect.resourceId] = after;
+}
+function applyFactChange(world, effect) {
+    assertText(effect.fact, 'fact', 240);
+    const factExists = world.facts.includes(effect.fact);
+    if ((effect.operation === 'fact.add' && factExists)
+        || (effect.operation === 'fact.remove' && !factExists)) {
+        fail('effect-noop-invalid', 'A fact effect must change the world');
+    }
+    world.facts = effect.operation === 'fact.add'
+        ? [...new Set([...world.facts, effect.fact])]
+        : world.facts.filter(fact => fact !== effect.fact);
+    if (world.facts.length > 100)
+        fail('fact-invalid', 'World facts exceed their shared bound');
+}
+function applyObjectPut(world, effect, context) {
+    if (effect.object.provenance.actionId !== effect.actionId
+        || effect.object.provenance.eventId !== context.eventId) {
+        fail('object-provenance-invalid', 'Object provenance must match its effect');
+    }
+    const existingIndex = world.domainObjects.findIndex(object => object.id === effect.object.id);
+    const existing = existingIndex < 0 ? undefined : world.domainObjects[existingIndex];
+    if (existing === undefined) {
+        if (effect.expectedVersion !== null || effect.object.version !== 1) {
+            fail('object-version-conflict', 'A new object must start at version one');
+        }
+        if (effect.object.provenance.createdRevision !== context.revision
+            || effect.object.provenance.updatedRevision !== context.revision) {
+            fail('object-provenance-invalid', 'New object provenance must match this revision');
+        }
+        world.domainObjects.push(structuredClone(effect.object));
+        return;
+    }
+    if (effect.expectedVersion !== existing.version
+        || effect.object.version !== existing.version + 1) {
+        fail('object-version-conflict', 'Object update does not match the current version');
+    }
+    if (effect.object.kind !== existing.kind
+        || effect.object.provenance.createdRevision !== existing.provenance.createdRevision
+        || effect.object.provenance.updatedRevision !== context.revision) {
+        fail('object-provenance-invalid', 'Object update cannot rewrite identity or creation history');
+    }
+    const { version: _existingVersion, provenance: _existingProvenance, ...existingContent } = existing;
+    const { version: _nextVersion, provenance: _nextProvenance, ...nextContent } = effect.object;
+    if (isDeepStrictEqual(existingContent, nextContent)) {
+        fail('effect-noop-invalid', 'An object effect must change gameplay state');
+    }
+    world.domainObjects[existingIndex] = structuredClone(effect.object);
+}
+function validateDomainObjects(objects, context) {
+    if (objects.length > 128)
+        fail('object-count-invalid', 'World objects exceed their shared bound');
+    assertUnique(objects.map(object => object.id), 'duplicate-object');
+    const objectIds = new Set(objects.map(object => object.id));
+    let aggregateDataBytes = 0;
+    for (const object of objects) {
+        assertIdentifier(object.id, 'object');
+        assertIdentifier(object.kind, 'object kind');
+        assertText(object.label, 'object label', 160);
+        assertText(object.status, 'object status', 80);
+        if (!Number.isSafeInteger(object.version) || object.version < 1 || object.version > 100_000) {
+            fail('object-version-invalid', 'Object version is invalid');
+        }
+        if (object.ownerActorId !== null && !context.actorIds.includes(object.ownerActorId)) {
+            fail('object-owner-invalid', 'Object owner is unavailable');
+        }
+        validateObjectVisibility(object, context);
+        const dataBytes = validateObjectData(object.data);
+        aggregateDataBytes += dataBytes;
+        if (object.links.length > 16)
+            fail('object-link-invalid', 'Object links exceed their bound');
+        const linkKeys = object.links.map(link => (`${link.relation}:${link.targetType}:${link.targetId}`));
+        assertUnique(linkKeys, 'object-link-invalid');
+        for (const link of object.links) {
+            assertIdentifier(link.relation, 'object link relation');
+            assertIdentifier(link.targetId, 'object link target');
+            const validTarget = link.targetType === 'actor'
+                ? context.actorIds.includes(link.targetId)
+                : link.targetType === 'object'
+                    ? objectIds.has(link.targetId) && link.targetId !== object.id
+                    : link.targetType === 'event'
+                        ? context.eventIds.includes(link.targetId)
+                        : context.documentIds.includes(link.targetId);
+            if (!validTarget)
+                fail('object-link-invalid', 'Object link target is unavailable');
+        }
+        if (object.provenance.createdRevision < 0
+            || object.provenance.createdRevision > object.provenance.updatedRevision
+            || object.provenance.updatedRevision > context.revision
+            || !context.eventIds.includes(object.provenance.eventId)
+            || !context.knownActionIds.includes(object.provenance.actionId)) {
+            fail('object-provenance-invalid', 'Object provenance is invalid');
+        }
+        if (object.provenance.updatedRevision === context.revision
+            && (object.provenance.eventId !== context.eventId)) {
+            fail('object-provenance-invalid', 'Current object provenance must match the effect event');
+        }
+    }
+    if (context.agencyVersion !== 'emergent-v1')
+        validateObjectDataVisibility(objects, context.actorIds);
+    if (aggregateDataBytes > 98_304) {
+        fail('object-data-bound', 'Aggregate object data exceeds its shared bound');
+    }
+}
+function validateObjectDataVisibility(objects, actorIds) {
+    for (const source of objects) {
+        const sourceAudience = objectAudience(source, actorIds);
+        const text = normalizeReferenceText(collectObjectDataStrings(source.data).join(' '));
+        if (text === '')
+            continue;
+        for (const target of objects) {
+            if (target.id === source.id)
+                continue;
+            const targetAudience = new Set(objectAudience(target, actorIds));
+            if (sourceAudience.every(actorId => targetAudience.has(actorId)))
+                continue;
+            const targetLabel = normalizeReferenceText(target.label);
+            const references = [
+                normalizeReferenceText(target.id),
+                ...(targetLabel.length >= 8 ? [targetLabel] : []),
+                ...collectObjectDataStrings(target.data)
+                    .map(normalizeReferenceText)
+                    .filter(reference => reference.length >= 12),
+            ];
+            if (references.some(reference => containsReference(text, reference))) {
+                fail('object-data-visibility-invalid', 'Visible object data cannot expose a hidden object');
+            }
+        }
+    }
+}
+function objectAudience(object, actorIds) {
+    if (object.visibility.scope === 'world')
+        return actorIds;
+    if (object.visibility.scope === 'shared')
+        return object.visibility.actorIds;
+    return object.ownerActorId === null ? [] : [object.ownerActorId];
+}
+function collectObjectDataStrings(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(collectObjectDataStrings);
+    if (!isJsonRecord(value))
+        return [];
+    return Object.values(value).flatMap(collectObjectDataStrings);
+}
+function normalizeReferenceText(value) {
+    return value
+        .normalize('NFKC')
+        .toLocaleLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .trim();
+}
+function containsReference(text, reference) {
+    return reference !== '' && ` ${text} `.includes(` ${reference} `);
+}
+function validateObjectVisibility(object, context) {
+    if (object.visibility.scope === 'private') {
+        if (object.ownerActorId === null) {
+            fail('object-owner-invalid', 'A private object needs an owner');
+        }
+        return;
+    }
+    if (object.visibility.scope === 'shared') {
+        const actorIds = object.visibility.actorIds;
+        if (actorIds.length < 1
+            || actorIds.length > 8
+            || new Set(actorIds).size !== actorIds.length
+            || actorIds.some(actorId => !context.actorIds.includes(actorId))) {
+            fail('object-visibility-invalid', 'Shared object audience relationships are inconsistent');
+        }
+    }
+}
+function validateObjectData(value) {
+    let keyCount = 0;
+    const visit = (item, depth) => {
+        if (depth > 4)
+            fail('object-data-bound', 'Object data nesting exceeds its bound');
+        if (item === null || typeof item === 'boolean')
+            return;
+        if (typeof item === 'number') {
+            if (!Number.isFinite(item))
+                fail('object-data-invalid', 'Object data numbers must be finite');
+            return;
+        }
+        if (typeof item === 'string') {
+            if (item.length > 2_000)
+                fail('object-data-bound', 'Object data text exceeds its bound');
+            return;
+        }
+        if (Array.isArray(item)) {
+            if (item.length > 32)
+                fail('object-data-bound', 'Object data arrays exceed their bound');
+            for (const child of item)
+                visit(child, depth + 1);
+            return;
+        }
+        if (!isJsonRecord(item))
+            fail('object-data-invalid', 'Object data must be JSON');
+        const entries = Object.entries(item);
+        keyCount += entries.length;
+        if (keyCount > 32)
+            fail('object-data-bound', 'Object data keys exceed their bound');
+        for (const [key, child] of entries) {
+            assertIdentifier(key, 'object data key');
+            visit(child, depth + 1);
+        }
+    };
+    visit(value, 0);
+    const serialized = JSON.stringify(value);
+    const bytes = Buffer.byteLength(serialized, 'utf8');
+    if (bytes > 4_096)
+        fail('object-data-bound', 'Object data exceeds its byte bound');
+    return bytes;
+}
+function assertUnique(values, code) {
+    if (new Set(values).size !== values.length) {
+        fail(code, 'Identifiers must be unique');
+    }
+}
+function assertIdentifier(value, label) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > 128) {
+        fail('identifier-invalid', `${label} identifier is invalid`);
+    }
+}
+function assertText(value, label, maximum) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > maximum) {
+        fail('text-invalid', `${label} text is invalid`);
+    }
+}
+export function applyDynamicWorldActions(worldValue, actions) {
+    const world = structuredClone(worldValue);
+    for (const action of actions) {
+        if (Object.keys(action.parameters).some(key => !ACTION_PARAMETER_KEYS.has(key))) {
+            fail('domain-action-parameter-invalid', 'Domain action parameters contain an unsupported key');
+        }
+        const rawDeltas = action.parameters.worldDeltas;
+        if (rawDeltas !== undefined) {
+            if (!isJsonRecord(rawDeltas)) {
+                fail('resource-delta-invalid', 'worldDeltas must be an object');
+            }
+            for (const [resourceId, rawDelta] of Object.entries(rawDeltas)) {
+                if (!(resourceId in world.resources)) {
+                    fail('resource-unknown', `Resource ${resourceId} is unavailable`);
+                }
+                if (typeof rawDelta !== 'number' || !Number.isFinite(rawDelta)) {
+                    fail('resource-delta-invalid', 'Resource deltas must be finite numbers');
+                }
+                const next = (world.resources[resourceId] ?? 0) + rawDelta;
+                if (!Number.isFinite(next) || next < -1_000_000 || next > 1_000_000) {
+                    fail('resource-out-of-bounds', `Resource ${resourceId} is outside its bounds`);
+                }
+                world.resources[resourceId] = next;
+            }
+        }
+        const removals = new Set(parseFacts(action.parameters.factsToRemove, 'factsToRemove'));
+        const additions = parseFacts(action.parameters.factsToAdd, 'factsToAdd');
+        world.facts = [
+            ...new Set([...world.facts.filter(fact => !removals.has(fact)), ...additions]),
+        ];
+        if (world.facts.length > 100) {
+            fail('fact-invalid', 'World facts exceed their shared bound');
+        }
+    }
+    return world;
+}
+function parseFacts(value, name) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)
+        || value.length > 8
+        || value.some(item => (typeof item !== 'string'
+            || item.trim() === ''
+            || item.length > 240))) {
+        fail('fact-invalid', `${name} must be a bounded string array`);
+    }
+    return [...value];
+}
+function isJsonRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function fail(code, message) {
+    throw new DynamicWorldStateError(code, message);
+}

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

@@ -0,0 +1,5 @@
+type Schema = Record<string, unknown>;
+/** Translate the inference schema only. Canonical validators still own acceptance. */
+export declare function compileStrictSimulationSchema(schema: Schema): Schema;
+export declare function decodeStrictSimulationOutput(text: string, schema: Schema): string;
+export {};