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

package/dist/simulation/living/model-input.js

@@ -0,0 +1,215 @@
+import { LivingWorldError } from './types.js';
+export const LIVING_INPUT_BUDGETS = { attempt: 16_000, world: 16_000, 'speech-impact': 16_000,
+    reaction: 32_000, reply: 32_000, plan: 14_000, 'message-reply': 16_000, epilogue: 12_000, define: 12_000 };
+export const LIVING_RESPONSE_SCHEMA_BUDGET = 96_000;
+export const MODEL_VIEW_NOTE = 'Selected context: other people and facts remain in the world. Descriptions may be excerpts. Use only the IDs shown; omission does not mean absence.';
+export function assertLivingModelCall(call) {
+    const size = JSON.stringify(call.input).length;
+    const budget = LIVING_INPUT_BUDGETS[call.phase];
+    if (size > budget)
+        throw new LivingWorldError('inference-invalid', `${call.phase} input ${size} exceeds ${budget} characters`);
+    const schemaSize = JSON.stringify(call.responseSchema).length;
+    if (schemaSize > LIVING_RESPONSE_SCHEMA_BUDGET)
+        throw new LivingWorldError('inference-invalid', `${call.phase} schema ${schemaSize} exceeds ${LIVING_RESPONSE_SCHEMA_BUDGET} characters`);
+}
+// These fields describe the decision being made. Background records may yield to them.
+const decisionFields = new Set(['attempt', 'words', 'happening', 'happened', 'message', 'duePlan', 'request']);
+function isDecisionField(input, path) {
+    return decisionFields.has(path) || path === 'plan' && input.phase === 'plan' && input.duePlan == null;
+}
+export function decisionInputBudget(input, ordinaryBudget) {
+    const phase = input.phase ?? (input.words === undefined ? undefined : 'speech-impact');
+    const maximum = LIVING_INPUT_BUDGETS[phase] ?? ordinaryBudget;
+    const decision = Object.fromEntries(Object.entries(input).filter(([key]) => isDecisionField(input, key)));
+    // Reserve a small background window even when valid current text needs six JSON characters per unit.
+    return Math.min(maximum, Math.max(ordinaryBudget, JSON.stringify(decision).length + 4_000));
+}
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+const list = (value) => Array.isArray(value) ? value : [];
+const personPaths = [['scene', 'people'], ['world', 'people'], ['world', 'elsewhere'], ['world', 'away'], ['directory', 'people'], ['listeners'], ['elsewhere']];
+export const MODEL_PEOPLE_LIMIT = 24;
+function at(input, path) {
+    let value = input;
+    for (const key of path)
+        value = object(value)?.[key];
+    return value;
+}
+// Select by typed references only, after the role has projected its known people.
+export function selectModelPeople(input, close) {
+    const candidates = new Map();
+    for (const path of personPaths)
+        for (const item of list(at(input, path))) {
+            const card = object(item);
+            if (typeof card?.id === 'string')
+                candidates.set(card.id, card);
+        }
+    const self = object(input.actor)?.id ?? object(input.identity)?.id;
+    const explicit = [self, object(input.happened)?.byId, object(input.message)?.fromId, object(input.duePlan)?.targetId,
+        object(input.plan)?.targetId, object(input.about)?.id];
+    const priority = [...new Set([...close, ...explicit.filter((value) => typeof value === 'string')])]
+        .filter(id => candidates.has(id)).slice(0, MODEL_PEOPLE_LIMIT);
+    const selected = new Set([...priority, ...candidates.keys()].slice(0, MODEL_PEOPLE_LIMIT));
+    if (selected.size < candidates.size) {
+        input.view = MODEL_VIEW_NOTE;
+        for (const path of personPaths) {
+            const parent = path.length === 1 ? input : object(input[path[0]]);
+            if (parent && Array.isArray(parent[path.at(-1)]))
+                parent[path.at(-1)] = list(parent[path.at(-1)]).filter(item => selected.has(String(object(item)?.id)));
+        }
+        if (Array.isArray(input.relationships))
+            input.relationships = input.relationships.filter(item => selected.has(String(object(item)?.id)));
+        const balances = object(input.money);
+        if (balances && Array.isArray(balances.balances))
+            balances.balances = balances.balances.filter(item => {
+                const id = String(object(item)?.id);
+                return !candidates.has(id) || selected.has(id);
+            });
+    }
+    const happened = object(input.happened);
+    if (happened && Array.isArray(happened.to)) {
+        const names = new Set([...selected].map(id => candidates.get(id).name));
+        names.add(object(input.identity)?.name);
+        let remaining = 3000;
+        const recipients = happened.to.filter(name => {
+            const size = JSON.stringify(name).length + 1;
+            if (!names.has(name) || size > remaining)
+                return false;
+            remaining -= size;
+            return true;
+        });
+        if (recipients.length < happened.to.length) {
+            input.view = MODEL_VIEW_NOTE;
+            happened.otherAddresseeCount = happened.to.length - recipients.length;
+            happened.to = recipients;
+        }
+    }
+    return new Set(priority);
+}
+export function syncModelPeople(input) {
+    const people = object(input.scene)?.people;
+    if (!Array.isArray(people))
+        return;
+    const ids = new Set(people.map(person => object(person)?.id));
+    for (const key of ['possiblePerceiverIds', 'presentCharacterIds'])
+        if (Array.isArray(input[key]))
+            input[key] = input[key].filter(id => ids.has(id));
+}
+// Bound the serialized spelling too: a valid control character can take six JSON characters.
+export function modelTextExcerpt(text, limit = 300) {
+    let end = Math.min(text.length, limit);
+    while (end > 0 && JSON.stringify(text.slice(0, end)).length > limit + 2)
+        end -= 1;
+    const last = text.charCodeAt(end - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        end -= 1;
+    return text.slice(0, end);
+}
+// When ordinary relevance trimming is insufficient, shorten descriptions, then shed whole optional
+// records. IDs remain exact, and stored words stay whole. The view notice marks excerpts. The things
+// a decision is about give way only after every other record that may.
+export function compactModelInput(input, budget, priority, maximum = budget, things = new Set()) {
+    if (JSON.stringify(input).length <= budget)
+        return;
+    input.view = MODEL_VIEW_NOTE;
+    const shorten = (value, path, limit) => {
+        if (isDecisionField(input, path) || path === 'phase' || path === 'view')
+            return value;
+        if (typeof value === 'string') {
+            const key = path.slice(path.lastIndexOf('/') + 1);
+            return key === 'id' || key.endsWith('Id') || key.endsWith('Ids') ? value : modelTextExcerpt(value, limit);
+        }
+        if (Array.isArray(value))
+            return value.map((item, index) => shorten(item, `${path}/${index}`, limit));
+        const record = object(value);
+        return record ? Object.fromEntries(Object.entries(record).map(([key, child]) => [key, shorten(child, path ? `${path}/${key}` : key, limit)])) : value;
+    };
+    Object.assign(input, shorten(input, '', 300));
+    let shielded = things;
+    while (JSON.stringify(input).length > budget) {
+        let choice;
+        const visit = (value, path) => {
+            if (isDecisionField(input, path))
+                return;
+            if (Array.isArray(value)) {
+                // Keep a focused person's card and a kept thing's; their optional descriptions can still give way below.
+                const people = personPaths.some(parts => parts.join('/') === path);
+                const kept = (item) => (people ? priority : shielded).has(String(object(item)?.id));
+                let index = value.length - 1;
+                while (index >= 0 && kept(value[index]))
+                    index -= 1;
+                if (index >= 0) {
+                    const size = JSON.stringify(value[index]).length;
+                    if (!choice || size > choice.size)
+                        choice = { array: value, index, size };
+                }
+                // A kind's slots and rules stay together: omit a whole kind rather than change its contract.
+                if (path !== 'kinds')
+                    value.forEach((item, index) => visit(item, `${path}/${index}`));
+            }
+            else if (object(value))
+                for (const [key, child] of Object.entries(value))
+                    visit(child, path ? `${path}/${key}` : key);
+        };
+        visit(input, '');
+        if (!choice && shielded.size > 0) {
+            shielded = new Set();
+            continue;
+        }
+        if (!choice) {
+            const removable = [...priority].slice(3).reverse().find(id => personPaths.some(path => list(at(input, path)).some(item => object(item)?.id === id)));
+            if (removable === undefined)
+                break;
+            for (const path of personPaths) {
+                const parent = path.length === 1 ? input : object(input[path[0]]);
+                if (parent && Array.isArray(parent[path.at(-1)]))
+                    parent[path.at(-1)] = list(parent[path.at(-1)]).filter(item => object(item)?.id !== removable);
+            }
+            syncModelPeople(input);
+            continue;
+        }
+        choice.array.splice(choice.index, 1);
+        syncModelPeople(input);
+    }
+    if (JSON.stringify(input).length > maximum && !isDecisionField(input, 'plan'))
+        delete input.plan;
+    // Kept cards can still hold escaped text at six JSON characters per unit; their words give way, never the decision.
+    for (const limit of [120, 40, 16])
+        if (JSON.stringify(input).length > maximum)
+            Object.assign(input, shorten(input, '', limit));
+    if (JSON.stringify(input).length > maximum)
+        throw new LivingWorldError('inference-invalid', 'The selected model input exceeds its character budget');
+}
+// A model can ask for exact identities outside the selected view before proposing effects.
+export function withContextLookup(schema, input) {
+    if (input.view !== MODEL_VIEW_NOTE)
+        return schema;
+    return { type: 'object', additionalProperties: false, required: ['contextRequest'], properties: { contextRequest: {
+                type: 'array', maxItems: 2, items: { type: 'string', minLength: 1, maxLength: 200 },
+                description: 'Exact names or IDs of at most two people needed for this decision but omitted from the shown cards. Return an empty array when the shown people suffice.',
+            } } };
+}
+// The selector reads the current decision and admitted identity cards, not unrelated world history.
+export function contextSelectionInput(input) {
+    const selected = Object.fromEntries(['phase', 'clock', 'clockMinutes', 'attempt', 'happening', 'happened', 'words', 'duePlan', 'message', 'plan', 'goals', 'view']
+        .filter(key => input[key] !== undefined).map(key => [key, input[key]]));
+    for (const key of ['actor', 'identity', 'speaker']) {
+        const card = object(input[key]);
+        if (card)
+            selected[key] = { ...(card.id === undefined ? {} : { id: card.id }), name: card.name };
+    }
+    for (const path of personPaths) {
+        const cards = at(input, path);
+        if (!Array.isArray(cards))
+            continue;
+        const minimal = cards.map(value => { const card = object(value); return { id: card.id, name: card.name }; });
+        if (path.length === 1)
+            selected[path[0]] = minimal;
+        else {
+            const parent = (selected[path[0]] ??= {});
+            parent[path[1]] = minimal;
+            if (path[0] === 'scene')
+                parent.id = object(input.scene)?.id;
+        }
+    }
+    return selected;
+}

package/dist/simulation/living/open-world.d.ts

@@ -0,0 +1,257 @@
+import { z } from 'zod';
+export declare const scheduleIntentSchema: z.ZodString;
+export declare const levelSchema: z.ZodEnum<{
+    none: "none";
+    low: "low";
+    medium: "medium";
+    high: "high";
+}>;
+export declare const propertyValueSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodEnum<{
+    none: "none";
+    low: "low";
+    medium: "medium";
+    high: "high";
+}>, z.ZodString]>;
+export declare const propertyDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        id: "id";
+        flag: "flag";
+        text: "text";
+        level: "level";
+        time: "time";
+    }>;
+    requiredOnCreate: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const relationDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    targetKindId: z.ZodString;
+}, z.core.$strip>;
+export declare const mechanicSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"spread">;
+    propertyId: z.ZodString;
+    relationId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"signal">;
+    propertyId: z.ZodString;
+    relationId: z.ZodString;
+    channel: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"change">;
+    propertyId: z.ZodString;
+    deltaPerMinute: z.ZodNumber;
+    onEvent: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"move">;
+        subjectPropertyId: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodEnum<{
+            none: "none";
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>, z.ZodString]>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"trigger">;
+    propertyId: z.ZodString;
+    threshold: z.ZodNumber;
+    direction: z.ZodEnum<{
+        "at-least": "at-least";
+        "at-most": "at-most";
+    }>;
+    intent: z.ZodString;
+    delayMinutes: z.ZodNumber;
+    minImportance: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"gate">;
+    propertyId: z.ZodString;
+    subjectPropertyId: z.ZodString;
+    atLeast: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    blockedActionKinds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"norm">;
+    actionKind: z.ZodString;
+    roleId: z.ZodNullable<z.ZodString>;
+    forbidden: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"authority">;
+    roleId: z.ZodString;
+    relationId: z.ZodNullable<z.ZodString>;
+    propertyId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export declare const kindDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    meaning: z.ZodString;
+    properties: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            number: "number";
+            id: "id";
+            flag: "flag";
+            text: "text";
+            level: "level";
+            time: "time";
+        }>;
+        requiredOnCreate: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    relations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        targetKindId: z.ZodString;
+    }, z.core.$strip>>;
+    mechanics: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"spread">;
+        propertyId: z.ZodString;
+        relationId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"signal">;
+        propertyId: z.ZodString;
+        relationId: z.ZodString;
+        channel: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"change">;
+        propertyId: z.ZodString;
+        deltaPerMinute: z.ZodNumber;
+        onEvent: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"move">;
+            subjectPropertyId: z.ZodString;
+            value: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodEnum<{
+                none: "none";
+                low: "low";
+                medium: "medium";
+                high: "high";
+            }>, z.ZodString]>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"trigger">;
+        propertyId: z.ZodString;
+        threshold: z.ZodNumber;
+        direction: z.ZodEnum<{
+            "at-least": "at-least";
+            "at-most": "at-most";
+        }>;
+        intent: z.ZodString;
+        delayMinutes: z.ZodNumber;
+        minImportance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"gate">;
+        propertyId: z.ZodString;
+        subjectPropertyId: z.ZodString;
+        atLeast: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>>;
+        blockedActionKinds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"norm">;
+        actionKind: z.ZodString;
+        roleId: z.ZodNullable<z.ZodString>;
+        forbidden: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"authority">;
+        roleId: z.ZodString;
+        relationId: z.ZodNullable<z.ZodString>;
+        propertyId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+export type LivingKindDefinition = z.infer<typeof kindDefinitionSchema>;
+export declare const kindRequestSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    meaning: z.ZodString;
+}, z.core.$strip>;
+export declare const slotSchema: z.ZodObject<{
+    value: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodEnum<{
+        none: "none";
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>, z.ZodString]>;
+    changedSeq: z.ZodNumber;
+    previousSeq: z.ZodNullable<z.ZodNumber>;
+    knownTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    updatedAt: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const relationSlotSchema: z.ZodObject<{
+    targetId: z.ZodString;
+    changedSeq: z.ZodNumber;
+    previousSeq: z.ZodNullable<z.ZodNumber>;
+    knownTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const entitySchema: z.ZodObject<{
+    id: z.ZodString;
+    kindId: z.ZodString;
+    name: z.ZodString;
+    placeId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    paperViews: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        words: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+    holderId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    condition: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    aspects: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    sideOrder: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hidden: z.ZodOptional<z.ZodLiteral<true>>;
+    members: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ballots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        yes: "yes";
+        no: "no";
+        abstain: "abstain";
+    }>>>;
+    result: z.ZodOptional<z.ZodEnum<{
+        failed: "failed";
+        passed: "passed";
+        lapsed: "lapsed";
+    }>>;
+    settles: z.ZodOptional<z.ZodString>;
+    transfers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        fromId: z.ZodNullable<z.ZodString>;
+        toId: z.ZodNullable<z.ZodString>;
+        amount: z.ZodNumber;
+    }, z.core.$strip>>>;
+    properties: z.ZodRecord<z.ZodString, z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodEnum<{
+            none: "none";
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>, z.ZodString]>;
+        changedSeq: z.ZodNumber;
+        previousSeq: z.ZodNullable<z.ZodNumber>;
+        knownTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        updatedAt: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    relations: z.ZodRecord<z.ZodString, z.ZodObject<{
+        targetId: z.ZodString;
+        changedSeq: z.ZodNumber;
+        previousSeq: z.ZodNullable<z.ZodNumber>;
+        knownTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    introducedSeq: z.ZodNumber;
+    knownTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type LivingEntity = z.infer<typeof entitySchema>;
+export declare const changeSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    entityId: z.ZodString;
+    slotKind: z.ZodEnum<{
+        property: "property";
+        relation: "relation";
+    }>;
+    slotId: z.ZodString;
+    value: z.ZodNullable<z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodEnum<{
+        none: "none";
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>, z.ZodString]>>;
+}, z.core.$strip>;
+export type LivingChange = z.infer<typeof changeSchema>;
+export declare function valueMatchesType(type: z.infer<typeof propertyDefinitionSchema>['type'], value: z.infer<typeof propertyValueSchema>): boolean;

package/dist/simulation/living/open-world.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+const id = z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/u);
+const text = z.string().min(1).max(2000);
+export const scheduleIntentSchema = text;
+export const levelSchema = z.enum(['none', 'low', 'medium', 'high']);
+export const propertyValueSchema = z.union([z.boolean(), z.number().finite(), levelSchema, z.string().min(1).max(2000)]);
+export const propertyDefinitionSchema = z.object({
+    id,
+    // A time is a moment on the world clock, in minutes from the start of day 1.
+    type: z.enum(['flag', 'level', 'number', 'time', 'id', 'text']),
+    requiredOnCreate: z.boolean().optional(),
+});
+export const relationDefinitionSchema = z.object({
+    id,
+    targetKindId: id,
+});
+const property = id.describe('Property of this kind that the rule reads or changes.');
+const relation = id.describe('Relation of this kind that the rule follows.');
+const subject = id.describe('Id property naming the person or thing affected.');
+const role = id.describe('Role id.');
+export const mechanicSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('spread'), propertyId: property, relationId: relation }),
+    z.object({ kind: z.literal('signal'), propertyId: property, relationId: relation, channel: id.describe('Sense channel, such as sight, sound, smell, or touch.') }),
+    z.object({ kind: z.literal('change'), propertyId: property, deltaPerMinute: z.number().finite().describe('Change per minute; 0 for a change on an event.'),
+        onEvent: z.object({ kind: z.literal('move'), subjectPropertyId: subject, value: propertyValueSchema.describe('Value set when the subject moves.') }).optional()
+            .describe('Set the property when the subject moves; omit for changes over time.') }),
+    z.object({ kind: z.literal('trigger'), propertyId: property, threshold: z.number().finite().describe('Value the property must cross.'),
+        direction: z.enum(['at-least', 'at-most']).describe('Whether it fires rising to or falling to the threshold.'), intent: scheduleIntentSchema.describe('What happens when it fires.'),
+        delayMinutes: z.number().int().min(1).describe('Minutes from crossing to the happening.'), minImportance: z.number().int().min(1).max(10).optional().describe('Least importance of the happening.') }),
+    z.object({ kind: z.literal('gate'), propertyId: property, subjectPropertyId: subject, atLeast: levelSchema.optional().describe('Lowest level at which the gate holds.'),
+        blockedActionKinds: z.array(id).describe('Action kinds the subject cannot take while it holds.') }),
+    z.object({ kind: z.literal('norm'), actionKind: id.describe('Action kind the norm covers.'), roleId: role.nullable().describe('Role it applies to; null for everyone.'), forbidden: z.boolean().describe('Whether the act is forbidden.') }),
+    z.object({ kind: z.literal('authority'), roleId: role.describe('Role granted the right.'), relationId: relation.nullable().describe('Relation the role may change; null when it grants a property.'),
+        propertyId: property.nullable().describe('Property the role may change; null when it grants a relation.') }),
+]);
+export const kindDefinitionSchema = z.object({
+    id: id.describe('Stable id of the requested reusable kind.'),
+    name: text.describe('Short name for this kind.'),
+    meaning: text.describe('General meaning independent of one event or person.'),
+    properties: z.array(propertyDefinitionSchema).describe('Typed flags, levels, numbers, text or entity ids. Mark essential ones requiredOnCreate.'),
+    relations: z.array(relationDefinitionSchema).describe('Directed links to kinds in scope.'),
+    mechanics: z.array(mechanicSchema).describe('Automatic state changes and constraints this kind needs; else empty.'),
+});
+export const kindRequestSchema = z.object({ id, name: text, meaning: text });
+export const slotSchema = z.object({
+    value: propertyValueSchema,
+    changedSeq: z.number().int().min(1),
+    previousSeq: z.number().int().min(1).nullable(),
+    knownTo: z.array(id).default([]),
+    updatedAt: z.number().int().min(0).default(0),
+});
+export const relationSlotSchema = z.object({
+    targetId: id,
+    changedSeq: z.number().int().min(1),
+    previousSeq: z.number().int().min(1).nullable(),
+    knownTo: z.array(id).default([]),
+});
+export const entitySchema = z.object({
+    id,
+    kindId: id,
+    name: text,
+    placeId: id.nullable().default(null),
+    // Last text each reader perceived survives unseen edits and erasure.
+    paperViews: z.record(id, z.object({ name: text, words: z.string().nullable() })).optional(),
+    // A thing that is somewhere can be held; it then goes wherever its holder goes.
+    holderId: id.nullable().default(null),
+    // What anyone who sees it can tell of its state, such as torn or burned; null while unremarkable.
+    condition: z.string().min(1).max(200).nullable().default(null),
+    // Each named side of the condition, in the order first set; the condition line shows them all.
+    aspects: z.record(z.string().min(1).max(40), z.string().min(1).max(200)).optional(),
+    // From engine 48, the order the sides were first set.
+    sideOrder: z.array(z.string().min(1).max(40)).max(5).optional(),
+    // A thing the world's data hides, which no one who comes to its place sees.
+    hidden: z.literal(true).optional(),
+    // A decision's members, the vote each has cast, its result once counted, and the problem it settles.
+    members: z.array(id).optional(),
+    ballots: z.record(id, z.enum(['yes', 'no', 'abstain'])).optional(),
+    result: z.enum(['passed', 'failed', 'lapsed']).optional(),
+    settles: id.optional(),
+    transfers: z.array(z.object({ fromId: id.nullable(), toId: id.nullable(), amount: z.number().positive() })).optional(),
+    properties: z.record(id, slotSchema),
+    relations: z.record(id, relationSlotSchema),
+    introducedSeq: z.number().int().min(1),
+    knownTo: z.array(id).default([]),
+});
+export const changeSchema = z.object({
+    seq: z.number().int().min(1),
+    entityId: id,
+    slotKind: z.enum(['property', 'relation']),
+    slotId: id,
+    value: propertyValueSchema.nullable(),
+});
+export function valueMatchesType(type, value) {
+    switch (type) {
+        case 'flag': return typeof value === 'boolean';
+        case 'level': return levelSchema.safeParse(value).success;
+        case 'number': return typeof value === 'number';
+        case 'time': return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+        case 'id': return typeof value === 'string' && id.safeParse(value).success;
+        case 'text': return typeof value === 'string';
+    }
+}

package/dist/simulation/living/projection.d.ts

@@ -0,0 +1,7 @@
+import type { LivingEvent, LivingObject, LivingState } from './types.js';
+export declare function witnessed(event: LivingEvent, viewerId: string): boolean;
+export declare function receivedMessage(event: LivingEvent, viewerId: string): boolean;
+export declare function visibleTo(event: LivingEvent, viewerId: string): boolean;
+export declare function observedSummary(event: LivingEvent, viewerId: string): string | null;
+export declare function knowsCustody(state: LivingState, object: LivingObject, viewerId: string): boolean;
+export declare function observedObjectIds(event: LivingEvent): string[];

package/dist/simulation/living/projection.js

@@ -0,0 +1,31 @@
+// Objective events remain in the replay log. A viewer only receives recorded observations.
+export function witnessed(event, viewerId) {
+    return (event.perceivedBy ?? event.witnessIds).includes(viewerId);
+}
+// A message reaches its recipients wherever they are.
+export function receivedMessage(event, viewerId) {
+    return event.effects.some(effect => effect.kind === 'message' && effect.toIds.includes(viewerId));
+}
+export function visibleTo(event, viewerId) {
+    return event.actorId === viewerId || witnessed(event, viewerId) || event.nearbyIds.includes(viewerId) || receivedMessage(event, viewerId);
+}
+export function observedSummary(event, viewerId) {
+    if (witnessed(event, viewerId) || event.actorId === viewerId)
+        return event.observed ?? event.summary;
+    if (event.nearbyIds.includes(viewerId))
+        return event.notice ?? 'A commotion is heard nearby.';
+    if (event.kind === 'opening' || event.kind === 'finish' || event.kind === 'keep-playing')
+        return event.summary;
+    return null;
+}
+export function knowsCustody(state, object, viewerId) {
+    return object.holderId === viewerId || object.custodyKnownTo.includes(viewerId);
+}
+export function observedObjectIds(event) {
+    if (event.visibleObjectIds)
+        return event.visibleObjectIds;
+    // Old logs predate separate outward observations. Their witnesses saw physical effects.
+    if (event.observed === undefined)
+        return event.effects.flatMap(effect => effect.kind === 'object.update' || effect.kind === 'object.create' ? [effect.objectId] : []);
+    return [];
+}

package/dist/simulation/living/recall.d.ts

@@ -0,0 +1,17 @@
+import type { LivingPerson, LivingState } from './types.js';
+export type RecalledMemory = LivingPerson['memories'][number] & {
+    score: number;
+};
+export declare function recallMemories(state: LivingState, person: LivingPerson, focusIds: readonly string[], limit: number, exclude?: ReadonlySet<string>, ranked?: boolean): RecalledMemory[];
+export declare function recallBeliefs(person: LivingPerson, cues: readonly string[], limit: number): {
+    score: number;
+    id: string;
+    subject: string;
+    claim: string;
+    source: {
+        kind: "initial" | "inferred" | "witnessed" | "told" | "discovered";
+        personId: string | null;
+        eventSeq: number;
+    };
+    at: number;
+}[];

package/dist/simulation/living/recall.js

@@ -0,0 +1,25 @@
+export function recallMemories(state, person, focusIds, limit, exclude = new Set(), ranked = false) {
+    const cueIds = new Set(focusIds);
+    const now = state.clock;
+    // A memory that shares more of the moment's people, places and things comes first. Among equals,
+    // importance keeps a significant memory easy to recall while recency fades ordinary ones.
+    const scored = person.memories.filter(memory => !exclude.has(memory.id)).map((memory) => {
+        const shared = new Set([...memory.participantIds, ...(memory.placeId === null ? [] : [memory.placeId]), ...(memory.thingIds ?? [])].filter(id => cueIds.has(id))).size;
+        const importance = memory.importance / 10;
+        const ageMinutes = Math.max(0, now - memory.at);
+        const recency = Math.exp(-ageMinutes / 720);
+        return { ...memory, shared, score: 0.6 * importance + 0.4 * recency };
+    });
+    const best = scored
+        .sort((a, b) => b.shared - a.shared || b.score - a.score || b.eventSeq - a.eventSeq)
+        .slice(0, limit)
+        .map(({ shared: _shared, ...memory }) => memory);
+    // Best first, when what matters most must survive a cut; otherwise in the order they happened.
+    return ranked ? best : best.sort((a, b) => a.eventSeq - b.eventSeq);
+}
+export function recallBeliefs(person, cues, limit) {
+    return person.beliefs
+        .map(belief => ({ ...belief, score: belief.source.personId !== null && cues.includes(belief.source.personId) ? 1 : 0 }))
+        .sort((a, b) => b.score - a.score || b.at - a.at)
+        .slice(0, limit);
+}