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

package/dist/simulation/session_input_validation.d.ts

@@ -0,0 +1,43 @@
+export { SimulationInputError, fail, actors, inputActorId, sessionDocuments, validateDocumentWrite } from './session_documents.js';
+import { z } from 'zod';
+import type { SimulationDynamicMechanicDefinitionV1, SimulationDynamicStateV1, SimulationJsonObjectV1, SimulationSessionSnapshotV1, SimulationTransitionBatchV1 } from '../plugin/simulation_contract.js';
+import type { SimulationPrivateInputTextV1, ActorInterventionContext, SimulationInputBatchV1, SimulationInputJournalV1, SimulationInterventionResolutionV1 } from '../plugin/simulation_interventions.js';
+export declare const requestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    inputId: z.ZodString;
+    kind: z.ZodLiteral<"message">;
+    recipientActorIds: z.ZodArray<z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    inputId: z.ZodString;
+    kind: z.ZodLiteral<"document-edit">;
+    documentId: z.ZodString;
+    expectedVersion: z.ZodNumber;
+    body: z.ZodString;
+}, z.core.$strict>], "kind">;
+export declare function parseInputJournal(value: unknown): SimulationInputJournalV1;
+/** Validate cross-record references before a restored session can expose any projection. */
+export declare function validateSessionInputSnapshot(snapshot: SimulationSessionSnapshotV1): void;
+export declare function emptyJournal(): SimulationInputJournalV1;
+export declare function inputDigest(value: unknown): string;
+export declare function worldDigest(snapshot: SimulationSessionSnapshotV1): string;
+export declare function batchDigest(snapshot: SimulationSessionSnapshotV1, batch: Omit<SimulationInputBatchV1, 'digest'>): string;
+export declare function checkedCheckpoint(value: SimulationJsonObjectV1): SimulationJsonObjectV1;
+export declare function assertSealedReadSet(snapshot: SimulationSessionSnapshotV1, digest: string): SimulationInputBatchV1;
+export declare function actorInterventionContext(snapshot: SimulationSessionSnapshotV1, actorId: string): ActorInterventionContext | null;
+export declare function validateInputResolutions(journal: SimulationInputJournalV1, next: SimulationDynamicStateV1 | null, digest: string, values: readonly SimulationInterventionResolutionV1[], previous?: SimulationDynamicStateV1 | null): void;
+export declare function validateInputTransition(snapshot: SimulationSessionSnapshotV1, batch: SimulationTransitionBatchV1): void;
+export declare function interventionResolutionSchema(context: ActorInterventionContext, updateSchema: Record<string, unknown>, goalIds: readonly string[], causeIds: readonly string[], agencyVersion?: 'emergent-v1'): Record<string, unknown>;
+export declare function interventionPrivacyCorpus(snapshot: SimulationSessionSnapshotV1): SimulationPrivateInputTextV1[];
+/** Recover only a complete canonical match already present in authored public text. */
+export declare function literalInterventionPrivacyPhrase(texts: readonly string[], phrase: string): string | undefined;
+export declare function assertInterventionPrivacy(value: unknown, contexts: readonly ActorInterventionContext[], permittedActorId?: string, baseline?: unknown, retained?: readonly SimulationPrivateInputTextV1[], onMatch?: (phrase: string) => void): void;
+/** Diagnostic candidates come only from the exact recipient input, never the private world corpus. */
+export declare function collectActorInputPrivacyPhrases(value: unknown, actorInput: string, permittedActorId: string | undefined, baseline: unknown): {
+    complete: boolean;
+    phrases: string[];
+};
+export declare function checkpointInputJournal(checkpoint: SimulationJsonObjectV1): SimulationInputJournalV1 | undefined;
+/** Authorize exact declared key/value bindings only when the owning object is world-visible. */
+export declare function publicInterventionEnumBindings(world: SimulationDynamicStateV1['world'], mechanics: readonly SimulationDynamicMechanicDefinitionV1[]): string[];
+/** Exact authored reference slots for world-public objects; never a shared word vocabulary. */
+export declare function publicInterventionReferenceBindings(world: SimulationDynamicStateV1['world'], mechanics: readonly SimulationDynamicMechanicDefinitionV1[]): string[];

package/dist/simulation/session_input_validation.js

@@ -0,0 +1,364 @@
+import { fail, actors, sessionDocuments, validateSessionDocuments } from './session_documents.js';
+export { SimulationInputError, fail, actors, inputActorId, sessionDocuments, validateDocumentWrite } from './session_documents.js';
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { z } from 'zod';
+import { agentSchema } from './toolkit/dynamic_state.js';
+import { hasMaterialInterventionChange } from './intervention_material.js';
+import { dynamicBeliefEvidenceHistory, dynamicHistory } from './dynamic_history.js';
+const id = z.string().min(1).max(200);
+const key = z.string().min(8).max(200).regex(/^[A-Za-z0-9_-]+$/);
+const revision = z.number().int().nonnegative();
+const hashSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const documentReference = z.object({ documentId: id, versionId: id, version: z.number().int().positive() }).strict();
+export const requestSchema = z.discriminatedUnion('kind', [
+    z.object({ inputId: key, kind: z.literal('message'), recipientActorIds: z.array(id).min(1).max(4), body: z.string().min(1) }).strict(),
+    z.object({ inputId: key, kind: z.literal('document-edit'), documentId: id, expectedVersion: z.number().int().positive(), body: z.string() }).strict(),
+]);
+const resolutionSchema = z.object({ inputId: key, actorId: id, revision, disposition: z.enum(['acted', 'refused', 'ignored', 'deferred']), reason: z.string().trim().min(1).max(400),
+    causeIds: z.array(id).min(1).max(16), change: z.object({ kind: z.enum(['intent', 'belief', 'relationship']), recordId: id }).strict().nullable(),
+}).strict();
+const journalSchema = z.object({ schemaVersion: z.literal(1),
+    materialFromRevision: z.number().int().positive().optional(),
+    inputs: z.array(z.object({ inputId: key, senderActorId: id, recipientActorIds: z.array(id).min(1).max(16), acceptedSequence: z.number().int().positive(), eligibleRevision: revision, fingerprint: hashSchema,
+        payload: z.discriminatedUnion('kind', [z.object({ kind: z.literal('message'), body: z.string() }).strict(), documentReference.extend({ kind: z.literal('document-edit') }).strict()]),
+    }).strict()).max(256),
+    acknowledgements: z.array(z.object({ inputId: key, recipientActorIds: z.array(id), recipientNames: z.array(z.string()), eligibleRevision: revision, acceptedSequence: z.number().int().positive(), document: documentReference.optional() }).strict()).max(256),
+    batches: z.array(z.object({ resolutionContract: z.object({ version: z.literal(2), actorsBefore: z.array(agentSchema).max(4) }).strict().optional(), revision, basedOnRevision: revision, documentVersionIds: z.array(id).max(512), inputIds: z.array(key).max(8), worldDigest: hashSchema, digest: hashSchema }).strict()).max(257),
+    resolutions: z.array(resolutionSchema).max(1024),
+}).strict();
+export function parseInputJournal(value) {
+    const parsed = journalSchema.safeParse(value);
+    if (!parsed.success)
+        return fail('input_state_invalid', 'Session input state is invalid');
+    const j = parsed.data;
+    if (new Set(j.inputs.map(input => input.inputId)).size !== j.inputs.length || j.inputs.some((input, index) => input.acceptedSequence !== index + 1)
+        || j.acknowledgements.length !== j.inputs.length || j.acknowledgements.some((ack, index) => ack.inputId !== j.inputs[index].inputId || ack.eligibleRevision !== j.inputs[index].eligibleRevision
+        || ack.acceptedSequence !== j.inputs[index].acceptedSequence || !isDeepStrictEqual(ack.recipientActorIds, j.inputs[index].recipientActorIds))
+        || new Set(j.batches.map(batch => batch.revision)).size !== j.batches.length
+        || j.batches.some(batch => Boolean(batch.resolutionContract) !== (j.materialFromRevision !== undefined && batch.revision >= j.materialFromRevision))
+        || j.batches.some(batch => batch.revision !== batch.basedOnRevision + 1 || batch.inputIds.some(inputId => !j.inputs.some(input => input.inputId === inputId && input.eligibleRevision === batch.revision)))
+        || new Set(j.resolutions.map(item => `${item.inputId}:${item.actorId}`)).size !== j.resolutions.length) {
+        return fail('input_state_invalid', 'Session input lineage is invalid');
+    }
+    return j;
+}
+/** Validate cross-record references before a restored session can expose any projection. */
+export function validateSessionInputSnapshot(snapshot) {
+    const invalid = () => fail('input_state_invalid', 'Session input references are invalid');
+    const roster = actors(snapshot);
+    const actorIds = new Set(roster.map(actor => actor.actorId));
+    const documents = sessionDocuments(snapshot);
+    validateSessionDocuments(snapshot);
+    const journal = snapshot.inputJournal;
+    if (!journal)
+        return;
+    for (const [index, input] of journal.inputs.entries()) {
+        const ack = journal.acknowledgements[index];
+        if (!roster.some(actor => actor.actorId === input.senderActorId && actor.humanControlled)
+            || new Set(input.recipientActorIds).size !== input.recipientActorIds.length
+            || input.recipientActorIds.some(id => !actorIds.has(id))
+            || !input.recipientActorIds.some(id => roster.some(actor => actor.actorId === id && !actor.humanControlled))
+            || !isDeepStrictEqual(ack.recipientNames, input.recipientActorIds.map(id => roster.find(actor => actor.actorId === id)?.name)))
+            invalid();
+        let request;
+        if (input.payload.kind === 'message') {
+            if (ack.document !== undefined || Buffer.byteLength(input.payload.body, 'utf8') > 4000 || input.payload.body.length === 0)
+                invalid();
+            request = { inputId: input.inputId, kind: 'message', recipientActorIds: input.recipientActorIds, body: input.payload.body };
+        }
+        else {
+            const payload = input.payload;
+            const doc = documents.find(doc => doc.versionId === payload.versionId);
+            const reference = { documentId: payload.documentId, versionId: payload.versionId, version: payload.version };
+            if (!doc || doc.documentId !== payload.documentId || doc.version !== payload.version || doc.version < 2
+                || doc.ownerActorId !== input.senderActorId || !isDeepStrictEqual(doc.recipientActorIds, input.recipientActorIds)
+                || !isDeepStrictEqual(ack.document, reference))
+                invalid();
+            request = { inputId: input.inputId, kind: 'document-edit', documentId: payload.documentId, expectedVersion: payload.version - 1, body: doc.body };
+        }
+        if (inputDigest({ senderActorId: input.senderActorId, request }) !== input.fingerprint
+            || input.eligibleRevision > snapshot.revision + 2 || input.eligibleRevision < 1)
+            invalid();
+    }
+    for (const batch of journal.batches) {
+        if (new Set(batch.documentVersionIds).size !== batch.documentVersionIds.length || new Set(batch.inputIds).size !== batch.inputIds.length || batch.basedOnRevision > snapshot.revision
+            || !isDeepStrictEqual(batch.inputIds, journal.inputs.filter(input => input.eligibleRevision === batch.revision).map(input => input.inputId)))
+            invalid();
+        if (journal.inputs.some(input => batch.inputIds.includes(input.inputId) && input.payload.kind === 'document-edit' && !batch.documentVersionIds.includes(input.payload.versionId)))
+            invalid();
+        if (batch.resolutionContract) {
+            const expected = [...new Set(journal.inputs.filter(input => batch.inputIds.includes(input.inputId)).flatMap(input => input.recipientActorIds))].filter(id => snapshot.dynamicState?.agents.some(actor => actor.actorId === id && !actor.humanControlled)).sort();
+            if (!isDeepStrictEqual(batch.resolutionContract.actorsBefore.map(actor => actor.actorId).sort(), expected))
+                invalid();
+            if (batch.revision === snapshot.revision + 1 && batch.resolutionContract.actorsBefore.some(before => !isDeepStrictEqual(before, snapshot.dynamicState?.agents.find(actor => actor.actorId === before.actorId))))
+                invalid();
+        }
+        const { digest, ...data } = batch;
+        if (batchDigest(snapshot, data) !== digest)
+            invalid();
+        if (batch.revision === snapshot.revision + 1 && worldDigest(snapshot) !== batch.worldDigest)
+            invalid();
+    }
+    for (const resolution of journal.resolutions) {
+        const input = journal.inputs.find(input => input.inputId === resolution.inputId);
+        if (!input || !input.recipientActorIds.includes(resolution.actorId)
+            || !roster.some(actor => actor.actorId === resolution.actorId && !actor.humanControlled)
+            || resolution.revision !== input.eligibleRevision || resolution.revision > snapshot.revision
+            || !resolution.causeIds.includes(resolution.inputId)
+            || !journal.batches.some(batch => batch.revision === resolution.revision && batch.inputIds.includes(resolution.inputId)))
+            invalid();
+        const entry = snapshot.dynamicState ? dynamicHistory(snapshot.dynamicState).find(entry => entry.revision === resolution.revision) : undefined;
+        const update = entry?.gmProposal.agentUpdates.find(update => update.actorId === resolution.actorId);
+        const validCauses = new Set([resolution.inputId, ...(update?.sourceActionIds ?? []), ...(update?.sourceAdjudicationProposalIds ?? [])]);
+        const emergent = snapshot.dynamicState?.agencyVersion === 'emergent-v1';
+        const change = resolution.change;
+        if ((!emergent && (change === null || !['acted', 'refused'].includes(resolution.disposition)))
+            || (change === null && (resolution.disposition === 'acted' || !isDeepStrictEqual(resolution.causeIds, [resolution.inputId])))
+            || (change !== null && ['ignored', 'deferred'].includes(resolution.disposition)))
+            invalid();
+        const recordExists = change === null ? emergent && resolution.disposition !== 'acted'
+            : change.kind === 'intent' ? update?.nextIntent?.goalId === change.recordId || (emergent && change.recordId === resolution.actorId && update !== undefined)
+                : change.kind === 'belief' ? update?.beliefsToAppend.some(item => item.id === change.recordId) || update?.beliefUpdates.some(item => item.beliefId === change.recordId)
+                    : update?.relationshipDeltas.some(item => item.targetActorId === change.recordId);
+        if ((change !== null && !update) || !recordExists || resolution.causeIds.some(id => !validCauses.has(id)))
+            invalid();
+        const contract = journal.batches.find(batch => batch.revision === resolution.revision)?.resolutionContract;
+        if (contract) {
+            const before = contract.actorsBefore.find(actor => actor.actorId === resolution.actorId);
+            if (!before || !entry || !hasMaterialInterventionChange(before, entry, resolution, undefined, snapshot.dynamicState?.agencyVersion, resolution.change?.kind === 'belief' && snapshot.dynamicState ? dynamicBeliefEvidenceHistory({ ...snapshot.dynamicState, revision: resolution.revision - 1 })?.[resolution.actorId] : undefined))
+                invalid();
+        }
+    }
+    for (const input of journal.inputs.filter(input => input.eligibleRevision <= snapshot.revision)) {
+        for (const actorId of input.recipientActorIds.filter(id => roster.some(actor => actor.actorId === id && !actor.humanControlled))) {
+            if (!journal.resolutions.some(result => result.inputId === input.inputId && result.actorId === actorId))
+                invalid();
+        }
+    }
+}
+export function emptyJournal() { return { schemaVersion: 1, inputs: [], acknowledgements: [], batches: [], resolutions: [] }; }
+export function inputDigest(value) {
+    const canonical = (item) => Array.isArray(item) ? item.map(canonical) : item !== null && typeof item === 'object'
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => [k, canonical(v)])) : item;
+    return createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex');
+}
+export function worldDigest(snapshot) {
+    return inputDigest({ ref: snapshot.ref, revision: snapshot.revision, state: snapshot.dynamicState ?? null, world: snapshot.world, actors: snapshot.actors });
+}
+export function batchDigest(snapshot, batch) {
+    const inputs = batch.inputIds.map(id => snapshot.inputJournal?.inputs.find(input => input.inputId === id) ?? fail('input_state_invalid', 'Sealed input is missing'));
+    const documents = sessionDocuments(snapshot);
+    return inputDigest({ ...batch, inputs, versions: batch.documentVersionIds.map(id => documents.find(doc => doc.versionId === id) ?? fail('input_state_invalid', 'Sealed document version is missing')) });
+}
+export function checkedCheckpoint(value) {
+    if (Buffer.byteLength(JSON.stringify(value), 'utf8') > 4194304)
+        fail('input_storage_exhausted', 'This run has reached its durable checkpoint storage limit; retrying cannot free storage');
+    return value;
+}
+export function assertSealedReadSet(snapshot, digest) {
+    const batch = snapshot.inputJournal?.batches.find(batch => batch.revision === snapshot.revision + 1);
+    if (!batch || batch.digest !== digest || batch.worldDigest !== worldDigest(snapshot))
+        return fail('input_batch_conflict', 'Sealed input world or rules changed');
+    const { digest: _digest, ...data } = batch;
+    if (batchDigest(snapshot, data) !== digest)
+        return fail('input_batch_conflict', 'Sealed input or document version changed');
+    return batch;
+}
+export function actorInterventionContext(snapshot, actorId) {
+    const batch = snapshot.inputJournal?.batches.find(batch => batch.revision === snapshot.revision + 1);
+    if (!batch)
+        return null;
+    assertSealedReadSet(snapshot, batch.digest);
+    const inputs = snapshot.inputJournal.inputs.filter(input => batch.inputIds.includes(input.inputId) && input.recipientActorIds.includes(actorId));
+    const docs = sessionDocuments(snapshot).filter(doc => doc.recipientActorIds.includes(actorId) && batch.documentVersionIds.includes(doc.versionId));
+    return { revision: batch.revision, batchId: batch.digest, actorId, addressedInputs: inputs, documents: docs, requiredResolutionInputIds: inputs.map(input => input.inputId) };
+}
+export function validateInputResolutions(journal, next, digest, values, previous) {
+    const resolutions = z.array(resolutionSchema).parse(values);
+    const batch = journal.batches.find(batch => batch.digest === digest);
+    if (!batch || !next || !previous || next.revision !== batch.revision)
+        fail('input_resolution_invalid', 'Input resolution revision is invalid');
+    const required = journal.inputs.filter(input => batch.inputIds.includes(input.inputId)).flatMap(input => input.recipientActorIds.filter(id => previous.agents.some(actor => actor.actorId === id && !actor.humanControlled)).map(actorId => ({ inputId: input.inputId, actorId })));
+    if (resolutions.length !== required.length || new Set(resolutions.map(item => `${item.inputId}:${item.actorId}`)).size !== required.length)
+        fail('input_resolution_invalid', 'Every addressed character needs exactly one input resolution');
+    for (const result of resolutions) {
+        if (!required.some(item => item.inputId === result.inputId && item.actorId === result.actorId) || result.revision !== batch.revision
+            || journal.resolutions.some(item => item.inputId === result.inputId && item.actorId === result.actorId))
+            fail('input_resolution_invalid', 'Input resolution is not addressed to this character');
+        const before = previous.agents.find(actor => actor.actorId === result.actorId);
+        const after = next.agents.find(actor => actor.actorId === result.actorId);
+        if (batch.resolutionContract && !isDeepStrictEqual(before, batch.resolutionContract.actorsBefore.find(actor => actor.actorId === result.actorId)))
+            fail('input_resolution_invalid', 'Sealed actor witness changed');
+        if (!after || !hasMaterialInterventionChange(before, next.history.at(-1), result, after, previous.agencyVersion, result.change?.kind === 'belief' ? dynamicBeliefEvidenceHistory(previous)?.[result.actorId] : undefined))
+            fail('input_resolution_invalid', 'Input needs a causally linked accepted change; an echo is insufficient');
+    }
+}
+export function validateInputTransition(snapshot, batch) {
+    const journal = snapshot.inputJournal;
+    const sealed = journal?.batches.find(item => item.revision === snapshot.revision + 1);
+    const resolutions = batch.operations.filter(op => op.operation === 'session-inputs.resolve');
+    if (!sealed) {
+        if (resolutions.length)
+            fail('input_batch_conflict', 'No input batch is sealed');
+        return;
+    }
+    assertSealedReadSet(snapshot, sealed.digest);
+    if (resolutions.length !== 1 || resolutions[0].sealedDigest !== sealed.digest)
+        fail('input_resolution_invalid', 'Transition must resolve its exact sealed input batch');
+    const next = batch.operations.find(op => op.operation === 'dynamic-state.commit');
+    if (!next)
+        fail('input_resolution_invalid', 'Inputs require a dynamic state transition');
+    validateInputResolutions(journal, next.state, sealed.digest, resolutions[0].resolutions, snapshot.dynamicState);
+    if (next.state.status !== 'active' && journal.inputs.some(input => input.eligibleRevision > sealed.revision))
+        fail('input_pending_ending', 'An ending cannot strand accepted input');
+}
+export function interventionResolutionSchema(context, updateSchema, goalIds, causeIds, agencyVersion) {
+    const properties = updateSchema.properties;
+    const relationshipItems = properties.relationshipDeltas.items;
+    const relationshipIds = relationshipItems.anyOf?.map(branch => branch.properties.targetActorId.const)
+        ?? relationshipItems.properties?.targetActorId.enum ?? [];
+    const variants = [
+        ['intent', [...(agencyVersion === 'emergent-v1' ? [context.actorId] : []), ...goalIds, ...properties.goalsToAppend.items.properties.id.enum]],
+        ['belief', [...(properties.beliefUpdates.items.properties.beliefId.enum ?? []), ...(properties.beliefsToAppend.items.properties.id.enum ?? [])]],
+        ['relationship', relationshipIds],
+    ];
+    const schema = { type: 'array', minItems: context.requiredResolutionInputIds.length, maxItems: context.requiredResolutionInputIds.length, items: {
+            type: 'object', additionalProperties: false, required: ['inputId', 'actorId', 'revision', 'disposition', 'reason', 'causeIds', 'change'], properties: {
+                inputId: { enum: context.requiredResolutionInputIds }, actorId: { const: context.actorId }, revision: { const: context.revision },
+                disposition: { enum: ['acted', 'refused'] }, reason: { type: 'string', minLength: 1, maxLength: 400 },
+                causeIds: { type: 'array', minItems: 1 + causeIds.length, maxItems: 1 + causeIds.length, uniqueItems: true, items: { enum: [...context.requiredResolutionInputIds, ...causeIds] } },
+                change: { anyOf: variants.filter(([, ids]) => ids.length > 0).map(([kind, ids]) => ({ type: 'object', additionalProperties: false, required: ['kind', 'recordId'], properties: { kind: { const: kind }, recordId: { enum: ids } } })) },
+            },
+        } };
+    if (agencyVersion !== 'emergent-v1')
+        return schema;
+    const item = schema.items;
+    return { ...schema,
+        description: 'Record each addressed input as acted, refused, ignored, or deferred. Acted names an actual change. Refusal, ignoring, and deferral may record change:null with only that inputId as cause. This decision does not invent speech or require a mental or physical change.',
+        items: { anyOf: [
+                { ...item, properties: { ...item.properties, disposition: { enum: ['acted', 'refused'] } } },
+                { ...item, properties: { ...item.properties, disposition: { enum: ['refused', 'ignored', 'deferred'] },
+                        causeIds: { type: 'array', minItems: 1, maxItems: 1, items: { enum: context.requiredResolutionInputIds } },
+                        change: { type: 'null' },
+                    } },
+            ] },
+    };
+}
+export function interventionPrivacyCorpus(snapshot) {
+    return [
+        ...(snapshot.inputJournal?.inputs ?? []).flatMap(input => input.payload.kind === 'message' ? [{ recipientActorIds: input.recipientActorIds, text: input.payload.body }] : []),
+        ...sessionDocuments(snapshot).flatMap(doc => [doc.body, doc.label].map(text => ({ recipientActorIds: doc.recipientActorIds, text }))),
+        ...(snapshot.inputJournal?.resolutions ?? []).map(resolution => ({ recipientActorIds: [resolution.actorId], text: resolution.reason })),
+    ];
+}
+const normalizePrivacyText = (text) => text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+const privacyContainsPhrase = (text, phrase) => ` ${text} `.includes(` ${phrase} `);
+const privacyStrings = (value) => typeof value === 'string' ? [value] : Array.isArray(value) ? value.flatMap(privacyStrings)
+    : value !== null && typeof value === 'object' ? Object.values(value).flatMap(privacyStrings) : [];
+function* interventionPrivacyMatches(value, contexts, permittedActorId, baseline = {}, retained = []) {
+    const text = normalizePrivacyText(JSON.stringify(value, (_key, item) => typeof item === 'string' ? normalizePrivacyText(item) : item));
+    const actorPhrases = permittedActorId === undefined ? [] : [
+        ...contexts.flatMap(context => [
+            ...context.addressedInputs.filter(input => input.recipientActorIds.includes(permittedActorId)).flatMap(input => input.payload.kind === 'message' ? [input.payload.body] : []),
+            ...context.documents.filter(doc => doc.recipientActorIds.includes(permittedActorId)).flatMap(doc => [doc.body, doc.label]),
+        ]),
+        ...retained.filter(item => item.recipientActorIds.includes(permittedActorId)).map(item => item.text),
+    ];
+    const permittedPhrases = [...privacyStrings(baseline), ...actorPhrases].map(normalizePrivacyText);
+    const privateBodies = contexts.filter(context => context.actorId !== permittedActorId).flatMap(context => [
+        ...context.addressedInputs.filter(input => permittedActorId === undefined || !input.recipientActorIds.includes(permittedActorId)).flatMap(input => input.payload.kind === 'message' ? [input.payload.body] : []),
+        ...context.documents.filter(doc => permittedActorId === undefined || !doc.recipientActorIds.includes(permittedActorId)).flatMap(doc => [doc.body, doc.label]),
+    ]);
+    privateBodies.push(...retained.filter(item => permittedActorId === undefined || !item.recipientActorIds.includes(permittedActorId)).map(item => item.text));
+    for (const body of privateBodies) {
+        const normalized = normalizePrivacyText(body);
+        const words = normalized.split(' ');
+        const stopWords = new Set(['with', 'from', 'that', 'this', 'then', 'your', 'their', 'have', 'make', 'over', 'next', 'more', 'before', 'after', 'will', 'must', 'only', 'into', 'each']);
+        const phrases = [normalized, ...words.slice(0, -2).map((_word, index) => words.slice(index, index + 3)).filter(tokens => tokens.every(token => token.length >= 4 && !stopWords.has(token))).map(tokens => tokens.join(' '))];
+        for (const phrase of phrases)
+            if (phrase.length >= 8 && !permittedPhrases.some(text => privacyContainsPhrase(text, phrase)) && privacyContainsPhrase(text, phrase))
+                yield phrase;
+    }
+}
+/** Recover only a complete canonical match already present in authored public text. */
+export function literalInterventionPrivacyPhrase(texts, phrase) {
+    const normalizedPhrase = normalizePrivacyText(phrase);
+    for (const text of texts) {
+        if (!privacyContainsPhrase(normalizePrivacyText(text), normalizedPhrase))
+            continue;
+        const offsets = [];
+        let position = 0;
+        for (const character of text) {
+            const end = position + character.length;
+            for (let index = 0; index < character.toLowerCase().length; index++)
+                offsets.push({ start: position, end });
+            position = end;
+        }
+        const words = [...text.toLowerCase().matchAll(/[\p{L}\p{N}]+/gu)];
+        for (let start = 0; start < words.length; start++) {
+            for (let end = start; end < words.length; end++) {
+                const last = words[end];
+                const literal = text.slice(offsets[words[start].index].start, offsets[last.index + last[0].length - 1].end);
+                const normalized = normalizePrivacyText(literal);
+                if (normalized === normalizedPhrase)
+                    return literal;
+                if (normalized.length > normalizedPhrase.length)
+                    break;
+            }
+        }
+    }
+    return undefined;
+}
+export function assertInterventionPrivacy(value, contexts, permittedActorId, baseline = {}, retained = [], onMatch) {
+    const matches = interventionPrivacyMatches(value, contexts, permittedActorId, baseline, retained);
+    const first = matches.next();
+    if (first.done)
+        return;
+    if (onMatch) {
+        onMatch(first.value);
+        for (const phrase of matches)
+            onMatch(phrase);
+    }
+    fail('input_privacy_violation', 'Private intervention text reached an unauthorized surface');
+}
+/** Diagnostic candidates come only from the exact recipient input, never the private world corpus. */
+export function collectActorInputPrivacyPhrases(value, actorInput, permittedActorId, baseline) {
+    const packet = JSON.parse(actorInput);
+    const context = packet.intervention;
+    const corpus = context === undefined ? [] : [
+        ...context.documents.flatMap(document => [document.body, document.label].map(text => ({ recipientActorIds: document.recipientActorIds, text }))),
+        ...context.addressedInputs.flatMap(input => input.payload.kind === 'message' ? [{ recipientActorIds: input.recipientActorIds, text: input.payload.body }] : []),
+    ];
+    if (corpus.length > 2_048)
+        return { complete: false, phrases: [] };
+    const phrases = new Set();
+    let examined = 0;
+    for (const phrase of interventionPrivacyMatches(value, [], permittedActorId, baseline, corpus)) {
+        if (++examined > 64)
+            return { complete: false, phrases: [] };
+        phrases.add(phrase);
+        if (phrases.size > 8)
+            return { complete: false, phrases: [] };
+    }
+    return { complete: true, phrases: [...phrases] };
+}
+export function checkpointInputJournal(checkpoint) {
+    const extensions = checkpoint.extensions;
+    const host = extensions?.['ztc.host'];
+    const data = host?.data;
+    return data?.inputJournal === undefined ? undefined : parseInputJournal(data.inputJournal);
+}
+/** Authorize exact declared key/value bindings only when the owning object is world-visible. */
+export function publicInterventionEnumBindings(world, mechanics) {
+    const parameters = mechanics.flatMap(mechanic => [...mechanic.intentParameters, ...mechanic.resolutionParameters]);
+    return [...new Set(world.domainObjects.filter(object => object.visibility.scope === 'world').flatMap(object => parameters.flatMap(parameter => {
+            const value = object.data[parameter.id];
+            return parameter.kind === 'enum' && typeof value === 'string' && parameter.values.includes(value) ? [`${parameter.id} ${value}`] : [];
+        })))];
+}
+/** Exact authored reference slots for world-public objects; never a shared word vocabulary. */
+export function publicInterventionReferenceBindings(world, mechanics) {
+    const parameters = mechanics.flatMap(mechanic => mechanic.intentParameters);
+    return [...new Set(world.domainObjects.filter(object => object.visibility.scope === 'world').flatMap(object => parameters.flatMap(parameter => parameter.kind === 'object-reference' && parameter.objectKinds.includes(object.kind) ? [`${parameter.id} ${object.id}`] : [])))];
+}

package/dist/simulation/session_inputs.d.ts

@@ -0,0 +1,32 @@
+import type { SimulationJsonObjectV1, SimulationDynamicStateV1 } from '../plugin/simulation_contract.js';
+import type { ActorInterventionContext, SimulationPrivateInputTextV1, SimulationInputRequestV1, SimulationAddressedInputV1, SimulationInputAcknowledgementV1, SimulationInputBatchV1, SimulationAuthorizedDocumentV1, SimulationInterventionResolutionV1, SimulationDetachedInputCommitV1 } from '../plugin/simulation_interventions.js';
+export { getOriginalSessionTransition as getSessionTransition } from './plugin_host.js';
+export { SimulationInputError, actorInterventionContext, checkpointInputJournal } from './session_input_validation.js';
+/** Derives private validation context from a caller-owned sealed checkpoint. */
+export declare function checkpointInterventionContext(checkpoint: SimulationJsonObjectV1): Promise<{
+    sessionId: string;
+    state: SimulationDynamicStateV1;
+    privateContext: {
+        interventions: ActorInterventionContext[];
+        interventionPrivacy: SimulationPrivateInputTextV1[];
+    };
+}>;
+export declare function prepareSessionInput(checkpoint: SimulationJsonObjectV1, senderActorId: string, value: SimulationInputRequestV1): Promise<{
+    checkpoint: SimulationJsonObjectV1;
+    acknowledgement: SimulationInputAcknowledgementV1;
+    replayed: boolean;
+}>;
+export declare function sealSessionInputs(checkpoint: SimulationJsonObjectV1): Promise<{
+    checkpoint: SimulationJsonObjectV1;
+    batch: SimulationInputBatchV1;
+}>;
+export declare function projectSessionInputs(checkpoint: SimulationJsonObjectV1, actorId: string, includeDocumentHistory?: boolean): Promise<{
+    inputs: SimulationAddressedInputV1[];
+    documents: SimulationAuthorizedDocumentV1[];
+    acknowledgements: SimulationInputAcknowledgementV1[];
+    resolutions: SimulationInterventionResolutionV1[];
+}>;
+export declare function commitSessionInputBatch(request: SimulationDetachedInputCommitV1): Promise<{
+    checkpoint: SimulationJsonObjectV1;
+    state: SimulationDynamicStateV1;
+}>;

package/dist/simulation/session_inputs.js

@@ -0,0 +1,154 @@
+import { applyDetachedSessionTransition, detachedSessionCheckpoint, detachedSessionRecord, detachedSessionSnapshot } from './plugin_host.js';
+import { actors, assertSealedReadSet, batchDigest, checkedCheckpoint, emptyJournal, fail, inputDigest, requestSchema, sessionDocuments, worldDigest, actorInterventionContext, interventionPrivacyCorpus } from './session_input_validation.js';
+export { getOriginalSessionTransition as getSessionTransition } from './plugin_host.js';
+export { SimulationInputError, actorInterventionContext, checkpointInputJournal } from './session_input_validation.js';
+/** Derives private validation context from a caller-owned sealed checkpoint. */
+export async function checkpointInterventionContext(checkpoint) {
+    const record = await detachedSessionRecord(checkpoint);
+    try {
+        const snapshot = detachedSessionSnapshot(record);
+        if (!snapshot.dynamicState)
+            return fail('input_invalid', 'Dynamic checkpoint state is missing');
+        const batch = snapshot.inputJournal?.batches.find(item => item.revision === snapshot.revision + 1);
+        if (!batch)
+            return fail('input_batch_conflict', 'The original input batch must be sealed');
+        assertSealedReadSet(snapshot, batch.digest);
+        return { sessionId: snapshot.ref.sessionId, state: snapshot.dynamicState,
+            privateContext: {
+                interventions: snapshot.dynamicState.agents.filter(actor => !actor.humanControlled).flatMap(actor => {
+                    const context = actorInterventionContext(snapshot, actor.actorId);
+                    return context ? [context] : [];
+                }),
+                interventionPrivacy: interventionPrivacyCorpus(snapshot),
+            },
+        };
+    }
+    finally {
+        record.state.close();
+    }
+}
+export async function prepareSessionInput(checkpoint, senderActorId, value) {
+    const record = await detachedSessionRecord(checkpoint);
+    try {
+        const snapshot = detachedSessionSnapshot(record);
+        const roster = actors(snapshot);
+        if (!roster.some(actor => actor.actorId === senderActorId && actor.humanControlled))
+            fail('sender_invalid', 'Only the authenticated player owner can submit input');
+        const parsed = requestSchema.safeParse(value);
+        if (!parsed.success)
+            return fail('input_invalid', 'Input request is invalid');
+        const request = parsed.data.kind === 'message' ? { ...parsed.data, recipientActorIds: [...parsed.data.recipientActorIds].sort() } : parsed.data;
+        const fingerprint = inputDigest({ senderActorId, request });
+        const journal = record.inputJournal ?? emptyJournal();
+        const prior = journal.inputs.find(input => input.inputId === request.inputId);
+        if (prior) {
+            if (prior.fingerprint !== fingerprint)
+                fail('idempotency_conflict', 'That input key was used for different input');
+            return { checkpoint, acknowledgement: structuredClone(journal.acknowledgements[journal.inputs.indexOf(prior)]), replayed: true };
+        }
+        if (record.dynamicState && record.dynamicState.status !== 'active')
+            fail('run_ended', 'This run cannot accept input');
+        if (Buffer.byteLength(JSON.stringify(request), 'utf8') > 16384 || Buffer.byteLength(request.body, 'utf8') > (request.kind === 'message' ? 4000 : 8192))
+            fail('body_too_large', 'Input exceeds its byte limit');
+        const docs = sessionDocuments(snapshot);
+        const document = request.kind === 'document-edit' ? docs.filter(doc => doc.documentId === request.documentId).at(-1) : undefined;
+        if (request.kind === 'document-edit') {
+            if (!document || !document.recipientActorIds.includes(senderActorId))
+                fail('document_not_found', 'Document was not found');
+            if (document.ownerActorId !== senderActorId)
+                fail('document_edit_denied', 'Only the document owner may edit');
+            if (document.version !== request.expectedVersion)
+                fail('document_version_conflict', 'Document version changed; keep your draft and reload the saved version');
+        }
+        const recipients = request.kind === 'message' ? [...request.recipientActorIds].sort() : [...document.recipientActorIds];
+        if (new Set(recipients).size !== recipients.length || recipients.some(id => !roster.some(actor => actor.actorId === id))
+            || !recipients.some(id => roster.some(actor => actor.actorId === id && !actor.humanControlled)))
+            fail('recipient_invalid', 'Input recipients must name the exact character cast');
+        const eligibleRevision = record.revision + (journal.batches.some(batch => batch.revision === record.revision + 1) ? 2 : 1);
+        if (record.dynamicState && eligibleRevision > record.dynamicState.safetyCeiling)
+            fail('input_after_final_beat', 'The world ends at this beat; messages and edits can no longer reach it');
+        if (journal.inputs.length >= 256)
+            fail('input_storage_exhausted', 'This run has reached its durable input storage limit; retrying cannot free storage');
+        const open = journal.inputs.filter(input => input.eligibleRevision === eligibleRevision);
+        const recipientSet = new Set([...open.flatMap(input => input.recipientActorIds), ...recipients].filter(id => !roster.find(actor => actor.actorId === id)?.humanControlled));
+        const bodyBytes = open.reduce((sum, input) => sum + Buffer.byteLength(input.payload.kind === 'message' ? input.payload.body : docs.find(doc => doc.versionId === input.payload.versionId).body, 'utf8'), Buffer.byteLength(request.body, 'utf8'));
+        if (open.length >= 8 || bodyBytes > 16384 || recipientSet.size > 4)
+            fail('input_capacity', 'The next input batch is full; retry after it advances');
+        let payload = { kind: 'message', body: request.body };
+        if (request.kind === 'document-edit') {
+            const written = record.state.addDocument({
+                ...(document.provenance === undefined ? {} : { provenance: { policyVersion: 'document-stream-1', documentKey: document.provenance.documentKey, eligibleRevision, kind: 'player-edit', inputId: request.inputId } }),
+                label: document.label, type: 'memo', content: request.body, summary: '', createdBy: senderActorId,
+                sentTo: recipients, ownerActorId: document.ownerActorId, revisionOf: document.versionId
+            });
+            payload = { kind: 'document-edit', documentId: document.documentId, versionId: written.id, version: document.version + 1 };
+        }
+        const input = { inputId: request.inputId, senderActorId, recipientActorIds: recipients, acceptedSequence: journal.inputs.length + 1, eligibleRevision, fingerprint, payload };
+        const acknowledgement = { inputId: input.inputId, recipientActorIds: recipients, recipientNames: recipients.map(id => roster.find(actor => actor.actorId === id).name), eligibleRevision, acceptedSequence: input.acceptedSequence,
+            ...(payload.kind === 'document-edit' ? { document: { documentId: payload.documentId, versionId: payload.versionId, version: payload.version } } : {}) };
+        journal.inputs.push(input);
+        journal.acknowledgements.push(acknowledgement);
+        record.inputJournal = journal;
+        return { checkpoint: checkedCheckpoint(detachedSessionCheckpoint(record, checkpoint)), acknowledgement, replayed: false };
+    }
+    finally {
+        record.state.close();
+    }
+}
+export async function sealSessionInputs(checkpoint) {
+    const record = await detachedSessionRecord(checkpoint);
+    try {
+        record.inputJournal ??= emptyJournal();
+        const snapshot = detachedSessionSnapshot(record);
+        const prior = record.inputJournal.batches.find(batch => batch.revision === record.revision + 1);
+        if (prior) {
+            assertSealedReadSet(snapshot, prior.digest);
+            return { checkpoint, batch: prior };
+        }
+        record.inputJournal.materialFromRevision ??= record.revision + 1;
+        record.inputJournal.batches = record.inputJournal.batches.filter(batch => batch.inputIds.length > 0 || batch.revision > record.revision);
+        const documents = sessionDocuments(snapshot);
+        const documentVersionIds = documents.filter(doc => !documents.some(next => next.documentId === doc.documentId && next.version > doc.version)
+            || record.inputJournal.inputs.some(input => input.eligibleRevision === record.revision + 1 && input.payload.kind === 'document-edit' && input.payload.versionId === doc.versionId)).map(doc => doc.versionId);
+        const inputIds = record.inputJournal.inputs.filter(input => input.eligibleRevision === record.revision + 1).map(input => input.inputId);
+        const recipientIds = new Set(record.inputJournal.inputs.filter(input => inputIds.includes(input.inputId)).flatMap(input => input.recipientActorIds));
+        const resolutionContract = { version: 2, actorsBefore: structuredClone(record.dynamicState?.agents.filter(actor => recipientIds.has(actor.actorId) && !actor.humanControlled) ?? []) };
+        const data = { resolutionContract, documentVersionIds, revision: record.revision + 1, basedOnRevision: record.revision, inputIds: record.inputJournal.inputs.filter(input => input.eligibleRevision === record.revision + 1).map(input => input.inputId), worldDigest: worldDigest(snapshot) };
+        const batch = { ...data, digest: batchDigest(snapshot, data) };
+        record.inputJournal.batches.push(batch);
+        return { checkpoint: checkedCheckpoint(detachedSessionCheckpoint(record, checkpoint)), batch };
+    }
+    finally {
+        record.state.close();
+    }
+}
+export async function projectSessionInputs(checkpoint, actorId, includeDocumentHistory = false) {
+    const record = await detachedSessionRecord(checkpoint);
+    try {
+        const snapshot = detachedSessionSnapshot(record);
+        if (!actors(snapshot).some(actor => actor.actorId === actorId))
+            fail('sender_invalid', 'Actor was not found');
+        const journal = record.inputJournal ?? emptyJournal();
+        const inputs = journal.inputs.filter(input => input.senderActorId === actorId || input.recipientActorIds.includes(actorId));
+        const all = sessionDocuments(snapshot).filter(doc => doc.recipientActorIds.includes(actorId));
+        return { inputs, documents: includeDocumentHistory ? all : all.filter(doc => !all.some(other => other.documentId === doc.documentId && other.version > doc.version)), acknowledgements: journal.acknowledgements.filter(ack => inputs.some(input => input.inputId === ack.inputId)), resolutions: journal.resolutions.filter(item => inputs.some(input => input.inputId === item.inputId)) };
+    }
+    finally {
+        record.state.close();
+    }
+}
+export async function commitSessionInputBatch(request) {
+    const record = await detachedSessionRecord(request.checkpoint);
+    try {
+        assertSealedReadSet(detachedSessionSnapshot(record), request.sealedDigest);
+        if (request.batch.operations.some(op => op.operation === 'document.write' && op.ownerActorId === undefined))
+            fail('input_invalid', 'Detached documents require explicit ownership');
+        await applyDetachedSessionTransition(record, request.batch);
+        if (!record.dynamicState)
+            return fail('input_state_invalid', 'Dynamic state is missing');
+        return { checkpoint: checkedCheckpoint(detachedSessionCheckpoint(record, request.checkpoint)), state: record.dynamicState };
+    }
+    finally {
+        record.state.close();
+    }
+}