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

package/dist/simulation/toolkit/dynamic_mechanics.js

@@ -0,0 +1,910 @@
+export class DynamicMechanicContractError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DynamicMechanicContractError';
+    }
+}
+export function validateDynamicMechanicCatalog(definitions) {
+    if (!Array.isArray(definitions) || definitions.length === 0 || definitions.length > 64) {
+        fail('mechanic-catalog-invalid', 'A mechanic catalog needs one to sixty-four definitions');
+    }
+    assertUnique(definitions.map(definition => definition.id), 'mechanic identifiers');
+    for (const definition of definitions) {
+        assertIdentifier(definition.id, 'mechanic identifier');
+        assertText(definition.description, 'mechanic description', 500);
+        if (!['required', 'optional', 'game-master'].includes(definition.actor)) {
+            fail('mechanic-catalog-invalid', `Mechanic ${definition.id} has an invalid actor rule`);
+        }
+        if (!['none', 'optional', 'required'].includes(definition.target)) {
+            fail('mechanic-catalog-invalid', `Mechanic ${definition.id} has an invalid target rule`);
+        }
+        if (!Array.isArray(definition.intentParameters)
+            || !Array.isArray(definition.resolutionParameters)
+            || definition.intentParameters.length > 12
+            || definition.resolutionParameters.length > 12) {
+            fail('mechanic-catalog-invalid', `Mechanic ${definition.id} has too many parameters`);
+        }
+        const parameters = [
+            ...definition.intentParameters,
+            ...definition.resolutionParameters,
+        ];
+        assertUnique(parameters.map(parameter => parameter.id), `parameters for ${definition.id}`);
+        for (const parameter of parameters)
+            validateParameterDefinition(parameter, definition.id);
+        if (definition.resolutionParameters.some((parameter) => ((parameter.kind === 'object-reference' || parameter.kind === 'object-reference-list')
+            && parameter.actorLinks !== undefined)))
+            fail('mechanic-catalog-invalid', 'Actor links constrain intent references only');
+        validateScalarBindings(definition.intentParameters);
+        if (definition.resolutionParameters.some((parameter) => parameter.valueFrom !== undefined)) {
+            fail('mechanic-catalog-invalid', 'Scalar bindings constrain intent parameters only');
+        }
+        referencePairDefinition(definition.intentParameters);
+        referencePairDefinition(definition.resolutionParameters);
+    }
+    return structuredClone(definitions);
+}
+export function validateDynamicMechanicAction(action, definitions, context, mode, resolutionContext = { ...context, actingActorId: null }) {
+    const validatedDefinitions = validateDynamicMechanicCatalog(definitions);
+    const definition = validatedDefinitions.find(candidate => candidate.id === action.mechanic);
+    if (!definition)
+        fail('mechanic-not-allowed', `Mechanic ${action.mechanic} is not defined`);
+    validateActors(action, definition, context);
+    const parameters = assertRecord(action.parameters, 'action parameters');
+    const allowedEnvelopeKeys = mode === 'intent' || definition.resolutionParameters.length === 0
+        ? ['intent']
+        : ['intent', 'resolution'];
+    assertExactKeys(parameters, allowedEnvelopeKeys, ['intent'], 'action parameter envelope');
+    const intent = assertRecord(parameters.intent, 'intent parameters');
+    const participantContext = { ...context, actingActorId: action.actorId ?? null, targetActorId: action.targetActorId ?? null };
+    validateParameterRecord(intent, definition.intentParameters, participantContext);
+    if (mode === 'intent' && parameters.resolution !== undefined) {
+        fail('mechanic-parameter-invalid', 'An intent cannot author Game Master resolution fields');
+    }
+    if (mode === 'resolution' && definition.resolutionParameters.length > 0) {
+        const requiredResolution = definition.resolutionParameters.some(parameter => parameter.required !== false);
+        if (parameters.resolution === undefined) {
+            if (requiredResolution) {
+                fail('mechanic-parameter-invalid', 'Required resolution parameters are missing');
+            }
+        }
+        else {
+            validateParameterRecord(assertRecord(parameters.resolution, 'resolution parameters'), definition.resolutionParameters, resolutionContext);
+        }
+    }
+    return structuredClone(action.parameters);
+}
+export function dynamicMechanicParametersSchema(definition, context, mode) {
+    validateDynamicMechanicCatalog([definition]);
+    const properties = {
+        intent: parameterRecordSchema(definition.intentParameters, context),
+    };
+    const required = ['intent'];
+    if (mode === 'resolution' && definition.resolutionParameters.length > 0) {
+        properties.resolution = parameterRecordSchema(definition.resolutionParameters, { ...context, actingActorId: null });
+        if (definition.resolutionParameters.some(parameter => parameter.required !== false)) {
+            required.push('resolution');
+        }
+    }
+    return strictObjectSchema(required, properties);
+}
+export function constrainDynamicMechanicActionSchema(schema, definition, context) {
+    if (!definition.intentParameters.some(parameter => ((parameter.kind === 'object-reference' || parameter.kind === 'object-reference-list')
+        && parameter.actorLinks?.target !== undefined)))
+        return schema;
+    const properties = schema.properties;
+    const targetSchema = properties.targetActorId;
+    const targets = targetSchema?.enum ?? (targetSchema?.const === undefined ? [] : [targetSchema.const]);
+    return { oneOf: targets.flatMap(targetActorId => {
+            const bound = { ...context, targetActorId };
+            if (targetActorId === context.actingActorId || !dynamicMechanicHasRequiredReferences(definition, bound))
+                return [];
+            return [{ ...schema, properties: { ...properties, targetActorId: { const: targetActorId },
+                        parameters: dynamicMechanicParametersSchema(definition, bound, 'intent'),
+                    } }];
+        }) };
+}
+export function dynamicMechanicHasRequiredReferences(definition, context) {
+    const pair = referencePairDefinition(definition.intentParameters);
+    if (pair !== null && compatibleReferencePairs(pair, context).length === 0)
+        return false;
+    if (definition.intentParameters.some(parameter => parameter.valueFrom !== undefined)
+        && parameterRecordSchema(definition.intentParameters, context).anyOf.length === 0)
+        return false;
+    return definition.intentParameters.every(parameter => {
+        if (parameter.required === false)
+            return true;
+        switch (parameter.kind) {
+            case 'object-reference':
+                return compatibleObjects(parameter, context).length > 0;
+            case 'object-reference-list':
+                return compatibleObjects(parameter, context).length >= parameter.minimumItems;
+            case 'actor-reference':
+                return context.actorIds.some(actorId => parameter.allowSelf === true || actorId !== context.actingActorId);
+            case 'resource-reference':
+                return parameter.resourceIds.some(resourceId => context.resourceIds.includes(resourceId));
+            default:
+                return true;
+        }
+    });
+}
+export function makeDynamicFallbackParameters(definition, context, variant = 0) {
+    validateDynamicMechanicCatalog([definition]);
+    if (!Number.isSafeInteger(variant) || variant < 0) {
+        fail('mechanic-fallback-variant-invalid', 'A fallback variant must be a non-negative integer');
+    }
+    const intent = fallbackParameterRecord(definition.intentParameters, context, variant);
+    return { intent };
+}
+export function makeDynamicFallbackResolution(definition, context, variant = 0) {
+    validateDynamicMechanicCatalog([definition]);
+    if (!Number.isSafeInteger(variant) || variant < 0) {
+        fail('mechanic-fallback-variant-invalid', 'A fallback variant must be a non-negative integer');
+    }
+    return fallbackParameterRecord(definition.resolutionParameters, { ...context, actingActorId: null }, variant);
+}
+export function resolveDynamicActionParticipantIds(action, definition, objects, effects) {
+    const actorIds = new Set();
+    if (action.actorId !== undefined)
+        actorIds.add(action.actorId);
+    if (action.targetActorId !== undefined)
+        actorIds.add(action.targetActorId);
+    const referencedObjectIds = new Set([
+        ...objectReferenceValues(action.parameters.intent, definition.intentParameters),
+        ...objectReferenceValues(action.parameters.resolution, definition.resolutionParameters),
+    ]);
+    const actionEffectObjects = effects.flatMap(effect => (effect.actionId === action.id && effect.operation === 'object.put' ? [effect.object] : []));
+    for (const object of actionEffectObjects)
+        referencedObjectIds.add(object.id);
+    const objectById = new Map(objects.map(object => [object.id, object]));
+    for (const object of actionEffectObjects)
+        objectById.set(object.id, object);
+    for (let pass = 0; pass <= objectById.size; pass += 1) {
+        let changed = false;
+        for (const object of objectById.values()) {
+            const reachesAffected = object.links.some(link => (link.targetType === 'object' && referencedObjectIds.has(link.targetId)));
+            if (reachesAffected && !referencedObjectIds.has(object.id)) {
+                referencedObjectIds.add(object.id);
+                changed = true;
+            }
+            if (!referencedObjectIds.has(object.id))
+                continue;
+            for (const link of object.links) {
+                if (link.targetType === 'object' && !referencedObjectIds.has(link.targetId)) {
+                    referencedObjectIds.add(link.targetId);
+                    changed = true;
+                }
+            }
+        }
+        if (!changed)
+            break;
+    }
+    for (const objectId of referencedObjectIds) {
+        const object = objectById.get(objectId);
+        if (!object)
+            continue;
+        if (object.ownerActorId !== null)
+            actorIds.add(object.ownerActorId);
+        for (const link of object.links) {
+            if (link.targetType === 'actor')
+                actorIds.add(link.targetId);
+        }
+    }
+    return [...actorIds];
+}
+export function dynamicObjectGraph(objects) {
+    return objects.map(({ id, ownerActorId, links }) => ({
+        id, ownerActorId, links: structuredClone(links),
+    }));
+}
+export function dynamicActionObjectGraph(actionId, actions, objects, effects) {
+    const graph = new Map(dynamicObjectGraph(objects).map(object => [object.id, object]));
+    for (const action of actions) {
+        for (const effect of effects) {
+            if (effect.actionId === action.id && effect.operation === 'object.put') {
+                const { id, ownerActorId, links } = effect.object;
+                graph.set(id, { id, ownerActorId, links: structuredClone(links) });
+                for (const retiredId of effect.sceneRetention?.retiredIds ?? [])
+                    graph.delete(retiredId);
+            }
+        }
+        if (action.id === actionId)
+            break;
+    }
+    return [...graph.values()];
+}
+function objectReferenceValues(value, definitions) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    const record = value;
+    return definitions.flatMap((definition) => {
+        if (definition.kind === 'object-reference') {
+            const objectId = record[definition.id];
+            return typeof objectId === 'string' ? [objectId] : [];
+        }
+        if (definition.kind === 'object-reference-list') {
+            const objectIds = record[definition.id];
+            return Array.isArray(objectIds)
+                ? objectIds.filter((item) => typeof item === 'string')
+                : [];
+        }
+        return [];
+    });
+}
+function validateScalarBindings(definitions) {
+    for (const [index, parameter] of definitions.entries()) {
+        if (parameter.valueFrom === undefined)
+            continue;
+        const binding = parameter.valueFrom;
+        if (!['text', 'integer', 'number', 'boolean', 'enum'].includes(parameter.kind)
+            || binding === null || typeof binding !== 'object' || Array.isArray(binding)
+            || Object.keys(binding).sort().join(',') !== 'objectParameter,path'
+            || typeof binding.objectParameter !== 'string' || !Array.isArray(binding.path)
+            || binding.path.length === 0 || binding.path.length > 4
+            || binding.path.some(key => typeof key !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(key)
+                || ['constructor', 'prototype', '__proto__'].includes(key))) {
+            fail('mechanic-catalog-invalid', `Scalar parameter ${parameter.id} has an invalid value binding`);
+        }
+        const source = definitions.slice(0, index).find(candidate => candidate.id === binding.objectParameter);
+        if (source?.kind !== 'object-reference' || source.required === false) {
+            fail('mechanic-catalog-invalid', `Scalar parameter ${parameter.id} needs a preceding required object reference`);
+        }
+    }
+}
+function scalarBindingValue(parameter, record, definitions, context) {
+    const binding = parameter.valueFrom;
+    const source = definitions.find(candidate => candidate.id === binding.objectParameter);
+    if (source.kind !== 'object-reference')
+        fail('mechanic-catalog-invalid', 'Scalar source must be an object reference');
+    const object = compatibleObjects(source, context).find(candidate => candidate.id === record[source.id]);
+    if (!object)
+        fail('mechanic-reference-invalid', `${source.label} must reference a visible compatible object`);
+    let value = object;
+    for (const key of binding.path) {
+        if (value === null || typeof value !== 'object' || Array.isArray(value) || !Object.hasOwn(value, key)) {
+            fail('mechanic-value-binding-invalid', `${parameter.label} has no current bound value`);
+        }
+        value = value[key];
+    }
+    try {
+        validateParameterValue(value, parameter, context);
+    }
+    catch (error) {
+        if (!(error instanceof DynamicMechanicContractError))
+            throw error;
+        fail('mechanic-value-binding-invalid', `${parameter.label} has an invalid current bound value`);
+    }
+    return value;
+}
+function validateParameterDefinition(parameter, mechanicId) {
+    assertIdentifier(parameter.id, `parameter identifier for ${mechanicId}`);
+    assertText(parameter.label, `parameter label for ${mechanicId}`, 120);
+    switch (parameter.kind) {
+        case 'text': {
+            const minimum = parameter.minimumLength ?? 1;
+            if (!Number.isSafeInteger(minimum)
+                || !Number.isSafeInteger(parameter.maximumLength)
+                || minimum < 0
+                || parameter.maximumLength < Math.max(1, minimum)
+                || parameter.maximumLength > 2_000) {
+                fail('mechanic-catalog-invalid', `Text parameter ${parameter.id} has invalid length bounds`);
+            }
+            return;
+        }
+        case 'number':
+        case 'integer':
+            if (!Number.isFinite(parameter.minimum)
+                || !Number.isFinite(parameter.maximum)
+                || parameter.minimum > parameter.maximum
+                || (parameter.kind === 'integer'
+                    && (!Number.isSafeInteger(parameter.minimum) || !Number.isSafeInteger(parameter.maximum)))) {
+                fail('mechanic-catalog-invalid', `Numeric parameter ${parameter.id} has invalid bounds`);
+            }
+            return;
+        case 'boolean':
+            return;
+        case 'enum':
+            if (!Array.isArray(parameter.values)
+                || parameter.values.length === 0
+                || parameter.values.length > 32
+                || parameter.values.some(value => typeof value !== 'string' || value.trim() === '' || value.length > 100)) {
+                fail('mechanic-catalog-invalid', `Enum parameter ${parameter.id} has invalid choices`);
+            }
+            assertUnique(parameter.values, `choices for ${parameter.id}`);
+            return;
+        case 'actor-reference':
+            return;
+        case 'resource-reference':
+            if (!Array.isArray(parameter.resourceIds)
+                || parameter.resourceIds.length === 0
+                || parameter.resourceIds.length > 16) {
+                fail('mechanic-catalog-invalid', `Resource parameter ${parameter.id} needs bounded resources`);
+            }
+            for (const resourceId of parameter.resourceIds) {
+                assertIdentifier(resourceId, `resource for ${parameter.id}`);
+            }
+            assertUnique(parameter.resourceIds, `resources for ${parameter.id}`);
+            return;
+        case 'object-reference':
+        case 'object-reference-list':
+            if (!Array.isArray(parameter.objectKinds)
+                || parameter.objectKinds.length === 0
+                || parameter.objectKinds.length > 16) {
+                fail('mechanic-catalog-invalid', `Object parameter ${parameter.id} needs bounded kinds`);
+            }
+            for (const kind of parameter.objectKinds)
+                assertIdentifier(kind, `object kind for ${parameter.id}`);
+            assertUnique(parameter.objectKinds, `object kinds for ${parameter.id}`);
+            if (parameter.ownedByActor !== undefined && typeof parameter.ownedByActor !== 'boolean') {
+                fail('mechanic-catalog-invalid', `Object parameter ${parameter.id} has an invalid ownership rule`);
+            }
+            if (parameter.statuses !== undefined) {
+                if (!Array.isArray(parameter.statuses) || parameter.statuses.length === 0 || parameter.statuses.length > 16) {
+                    fail('mechanic-catalog-invalid', `Object parameter ${parameter.id} has invalid statuses`);
+                }
+                for (const status of parameter.statuses)
+                    assertIdentifier(status, `object status for ${parameter.id}`);
+                assertUnique(parameter.statuses, `object statuses for ${parameter.id}`);
+            }
+            if (parameter.actorLinks !== undefined) {
+                const links = parameter.actorLinks;
+                if (links === null || typeof links !== 'object' || Array.isArray(links)
+                    || Object.keys(links).length === 0 || Object.keys(links).some(key => key !== 'actor' && key !== 'target')) {
+                    fail('mechanic-catalog-invalid', `Object parameter ${parameter.id} needs valid actor links`);
+                }
+                for (const relation of Object.values(links))
+                    assertIdentifier(relation, `actor link for ${parameter.id}`);
+            }
+            if (parameter.actorLinkExceptions !== undefined) {
+                const exceptions = parameter.actorLinkExceptions;
+                if (parameter.actorLinks?.actor === undefined || !Array.isArray(exceptions)
+                    || exceptions.length === 0 || exceptions.length > 8) {
+                    fail('mechanic-catalog-invalid', `Object parameter ${parameter.id} needs bounded actor-link exceptions`);
+                }
+                for (const actorId of exceptions)
+                    assertIdentifier(actorId, `actor-link exception for ${parameter.id}`);
+                assertUnique(exceptions, `actor-link exceptions for ${parameter.id}`);
+            }
+            if (parameter.requiredNumericData !== undefined) {
+                const constraints = parameter.requiredNumericData;
+                if (constraints === null || typeof constraints !== 'object' || Array.isArray(constraints)
+                    || Object.keys(constraints).length === 0 || Object.keys(constraints).length > 8) {
+                    fail('mechanic-catalog-invalid', `Object parameter ${parameter.id} needs bounded numeric filters`);
+                }
+                for (const [key, bounds] of Object.entries(constraints)) {
+                    assertIdentifier(key, `numeric data key for ${parameter.id}`);
+                    if (bounds === null || typeof bounds !== 'object' || Array.isArray(bounds)
+                        || (bounds.minimum === undefined && bounds.maximumExclusive === undefined)
+                        || Object.keys(bounds).some(name => name !== 'minimum' && name !== 'maximumExclusive')
+                        || (bounds.minimum !== undefined && !Number.isFinite(bounds.minimum))
+                        || (bounds.maximumExclusive !== undefined && !Number.isFinite(bounds.maximumExclusive))
+                        || (bounds.minimum !== undefined && bounds.maximumExclusive !== undefined && bounds.minimum >= bounds.maximumExclusive)) {
+                        fail('mechanic-catalog-invalid', `Object parameter ${parameter.id} has invalid numeric bounds`);
+                    }
+                }
+            }
+            if (parameter.requiredData !== undefined) {
+                const data = parameter.requiredData;
+                if (data === null || typeof data !== 'object' || Array.isArray(data)
+                    || Object.keys(data).length === 0 || Object.keys(data).length > 8) {
+                    fail('mechanic-catalog-invalid', `Object parameter ${parameter.id} needs bounded data filters`);
+                }
+                for (const [key, value] of Object.entries(data)) {
+                    assertIdentifier(key, `object data key for ${parameter.id}`);
+                    if (!(typeof value === 'boolean'
+                        || (typeof value === 'number' && Number.isFinite(value))
+                        || (typeof value === 'string' && value.length <= 240))) {
+                        fail('mechanic-catalog-invalid', `Object parameter ${parameter.id} has an invalid data filter`);
+                    }
+                }
+            }
+            if (parameter.kind === 'object-reference-list'
+                && (!Number.isSafeInteger(parameter.minimumItems)
+                    || !Number.isSafeInteger(parameter.maximumItems)
+                    || parameter.minimumItems < 1
+                    || parameter.maximumItems < parameter.minimumItems
+                    || parameter.maximumItems > 16)) {
+                fail('mechanic-catalog-invalid', `Object list parameter ${parameter.id} has invalid item bounds`);
+            }
+            return;
+    }
+}
+function validateActors(action, definition, context) {
+    if (definition.actor === 'required' && action.actorId === undefined) {
+        fail('mechanic-actor-invalid', `Mechanic ${definition.id} needs an actor`);
+    }
+    if (definition.actor === 'game-master' && action.actorId !== undefined) {
+        fail('mechanic-actor-invalid', `Mechanic ${definition.id} is Game Master only`);
+    }
+    if (action.actorId !== undefined && !context.actorIds.includes(action.actorId)) {
+        fail('mechanic-actor-invalid', `Actor ${action.actorId} is unknown`);
+    }
+    if (context.actingActorId !== null
+        && action.actorId !== undefined
+        && context.actingActorId !== action.actorId) {
+        fail('mechanic-actor-invalid', 'The acting character cannot author another actor action');
+    }
+    if (definition.target === 'required' && action.targetActorId === undefined) {
+        fail('mechanic-target-invalid', `Mechanic ${definition.id} needs a target actor`);
+    }
+    if (definition.target === 'none' && action.targetActorId !== undefined) {
+        fail('mechanic-target-invalid', `Mechanic ${definition.id} cannot target an actor`);
+    }
+    if (action.targetActorId !== undefined && !context.actorIds.includes(action.targetActorId)) {
+        fail('mechanic-target-invalid', `Target ${action.targetActorId} is unknown`);
+    }
+    if (action.actorId !== undefined && action.actorId === action.targetActorId) {
+        fail('mechanic-target-invalid', 'An actor cannot target itself');
+    }
+}
+function validateParameterRecord(record, definitions, context) {
+    const allowed = definitions.map(definition => definition.id);
+    const required = definitions
+        .filter(definition => definition.required !== false)
+        .map(definition => definition.id);
+    assertExactKeys(record, allowed, required, 'mechanic parameters');
+    for (const definition of definitions) {
+        const value = record[definition.id];
+        if (value === undefined && definition.required === false)
+            continue;
+        validateParameterValue(value, definition, context);
+        if (definition.valueFrom !== undefined && value !== scalarBindingValue(definition, record, definitions, context)) {
+            fail('mechanic-value-binding-invalid', `${definition.label} differs from the selected object's current value`);
+        }
+    }
+    const relation = referencePairDefinition(definitions);
+    if (relation !== null && !compatibleReferencePairs(relation, context).some(pair => (record[relation.peer.id] === pair.peerId && record[relation.parameter.id] === pair.parameterId))) {
+        fail('mechanic-reference-invalid', `${relation.parameter.label} must match the selected ${relation.peer.label}`);
+    }
+}
+function validateParameterValue(value, definition, context) {
+    switch (definition.kind) {
+        case 'text': {
+            const minimum = definition.minimumLength ?? 1;
+            if (typeof value !== 'string' || value.length < minimum || value.length > definition.maximumLength) {
+                fail('mechanic-parameter-invalid', `${definition.label} has invalid text`);
+            }
+            return;
+        }
+        case 'number':
+        case 'integer':
+            if (typeof value !== 'number'
+                || !Number.isFinite(value)
+                || (definition.kind === 'integer' && !Number.isSafeInteger(value))
+                || value < definition.minimum
+                || value > definition.maximum) {
+                fail('mechanic-parameter-invalid', `${definition.label} is outside its bounds`);
+            }
+            return;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                fail('mechanic-parameter-invalid', `${definition.label} must be true or false`);
+            return;
+        case 'enum':
+            if (typeof value !== 'string' || !definition.values.includes(value)) {
+                fail('mechanic-parameter-invalid', `${definition.label} is not an allowed choice`);
+            }
+            return;
+        case 'actor-reference':
+            if (typeof value !== 'string'
+                || !context.actorIds.includes(value)
+                || (definition.allowSelf !== true && value === context.actingActorId)) {
+                fail('mechanic-reference-invalid', `${definition.label} must reference an allowed actor`);
+            }
+            return;
+        case 'resource-reference':
+            if (typeof value !== 'string'
+                || !definition.resourceIds.includes(value)
+                || !context.resourceIds.includes(value)) {
+                fail('mechanic-reference-invalid', `${definition.label} must reference an allowed resource`);
+            }
+            return;
+        case 'object-reference': {
+            if (typeof value !== 'string') {
+                fail('mechanic-reference-invalid', `${definition.label} must reference an object`);
+            }
+            const object = compatibleObjects(definition, context).find(candidate => candidate.id === value);
+            if (!object) {
+                fail('mechanic-reference-invalid', `${definition.label} must reference a visible compatible object`);
+            }
+            return;
+        }
+        case 'object-reference-list': {
+            if (!Array.isArray(value)
+                || value.length < definition.minimumItems
+                || value.length > definition.maximumItems
+                || value.some(candidate => typeof candidate !== 'string')
+                || new Set(value).size !== value.length) {
+                fail('mechanic-reference-invalid', `${definition.label} must contain unique object references`);
+            }
+            for (const objectId of value) {
+                const object = compatibleObjects(definition, context).find(candidate => candidate.id === objectId);
+                if (!object) {
+                    fail('mechanic-reference-invalid', `${definition.label} must reference visible compatible objects`);
+                }
+            }
+            return;
+        }
+    }
+}
+function parameterRecordSchema(definitions, context) {
+    const bindings = definitions.filter(parameter => parameter.valueFrom !== undefined);
+    if (bindings.length > 0) {
+        const unbound = definitions.map(({ valueFrom: _binding, ...parameter }) => parameter);
+        const base = parameterRecordSchema(unbound, context);
+        let branches = (base.anyOf ?? [base]);
+        for (const sourceId of new Set(bindings.map(parameter => parameter.valueFrom.objectParameter))) {
+            const source = definitions.find(parameter => parameter.id === sourceId);
+            if (source.kind !== 'object-reference')
+                fail('mechanic-catalog-invalid', 'Scalar source must be an object reference');
+            const objects = compatibleObjects(source, context);
+            if (branches.length * objects.length > 4096)
+                fail('mechanic-catalog-invalid', 'Scalar binding schema exceeds its branch bound');
+            branches = branches.flatMap(branch => objects.flatMap(object => {
+                const offered = branch.properties[sourceId].enum;
+                if (!offered.includes(object.id))
+                    return [];
+                const properties = { ...branch.properties, [sourceId]: { enum: [object.id] } };
+                for (const parameter of bindings.filter(item => item.valueFrom.objectParameter === sourceId)) {
+                    try {
+                        properties[parameter.id] = { const: scalarBindingValue(parameter, { [sourceId]: object.id }, definitions, context) };
+                    }
+                    catch (error) {
+                        if (!(error instanceof DynamicMechanicContractError) || error.code !== 'mechanic-value-binding-invalid')
+                            throw error;
+                        if (parameter.required !== false)
+                            return [];
+                        delete properties[parameter.id];
+                    }
+                }
+                return [{ ...branch, properties }];
+            }));
+        }
+        return { anyOf: branches };
+    }
+    const relation = referencePairDefinition(definitions);
+    if (relation !== null) {
+        const choices = new Map();
+        for (const pair of compatibleReferencePairs(relation, context)) {
+            const values = choices.get(pair.peerId) ?? [];
+            values.push(pair.parameterId);
+            choices.set(pair.peerId, values);
+        }
+        return {
+            anyOf: [...choices].map(([peerId, parameterIds]) => strictObjectSchema(definitions.filter(definition => definition.required !== false).map(definition => definition.id), Object.fromEntries(definitions.map(definition => [definition.id,
+                definition.id === relation.peer.id ? { enum: [peerId] }
+                    : definition.id === relation.parameter.id ? { enum: parameterIds }
+                        : parameterSchema(definition, context),
+            ])))),
+        };
+    }
+    return strictObjectSchema(definitions
+        .filter(definition => definition.required !== false)
+        .map(definition => definition.id), Object.fromEntries(definitions.map(definition => [
+        definition.id,
+        parameterSchema(definition, context),
+    ])));
+}
+function parameterSchema(definition, context) {
+    switch (definition.kind) {
+        case 'text':
+            return {
+                type: 'string',
+                minLength: definition.minimumLength ?? 1,
+                maxLength: definition.maximumLength,
+            };
+        case 'number':
+        case 'integer':
+            return {
+                type: definition.kind,
+                minimum: definition.minimum,
+                maximum: definition.maximum,
+            };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'enum':
+            return { enum: [...definition.values] };
+        case 'actor-reference':
+            return {
+                enum: context.actorIds.filter(actorId => (definition.allowSelf === true || actorId !== context.actingActorId)),
+            };
+        case 'resource-reference':
+            return { enum: definition.resourceIds.filter(resourceId => context.resourceIds.includes(resourceId)) };
+        case 'object-reference':
+            return {
+                enum: compatibleObjects(definition, context).map(object => object.id),
+            };
+        case 'object-reference-list':
+            return {
+                type: 'array',
+                minItems: definition.minimumItems,
+                maxItems: definition.maximumItems,
+                uniqueItems: true,
+                items: {
+                    enum: compatibleObjects(definition, context).map(object => object.id),
+                },
+            };
+    }
+}
+function fallbackValue(definition, context, variant) {
+    switch (definition.kind) {
+        case 'text': {
+            const minimum = Math.max(1, definition.minimumLength ?? 1);
+            const base = definition.label.slice(0, definition.maximumLength);
+            const candidate = base.length >= minimum ? base : 'x'.repeat(minimum);
+            if (variant === 0)
+                return candidate;
+            const width = Math.max(minimum, candidate.length);
+            const stem = candidate.padEnd(width, 'x').slice(0, width);
+            const marker = String.fromCharCode(97 + ((variant - 1) % 26));
+            const alternative = `${stem.slice(0, -1)}${marker}`;
+            if (alternative !== candidate)
+                return alternative;
+            return `${stem.slice(0, -1)}${marker === 'z' ? 'a' : String.fromCharCode(marker.charCodeAt(0) + 1)}`;
+        }
+        case 'number':
+            return variant === 0 || definition.minimum === definition.maximum
+                ? definition.minimum
+                : definition.maximum;
+        case 'integer': {
+            const bounded = (value) => Math.min(definition.maximum, Math.max(definition.minimum, value));
+            const candidates = [
+                definition.minimum,
+                definition.maximum,
+                bounded(0),
+                bounded(1),
+                bounded(-1),
+                Math.floor((definition.minimum + definition.maximum) / 2),
+                Math.ceil((definition.minimum + definition.maximum) / 2),
+            ];
+            const candidate = candidates[variant % candidates.length];
+            if (candidate === undefined)
+                fail('mechanic-fallback-unavailable', `${definition.label} has no fallback number`);
+            return candidate;
+        }
+        case 'boolean':
+            return variant % 2 === 1;
+        case 'enum': {
+            const value = definition.values[variant % definition.values.length];
+            if (value === undefined)
+                fail('mechanic-fallback-unavailable', `${definition.label} has no fallback choice`);
+            return value;
+        }
+        case 'actor-reference': {
+            const candidates = context.actorIds.filter(actorId => (definition.allowSelf === true || actorId !== context.actingActorId));
+            const value = candidates[variant % candidates.length];
+            if (value === undefined)
+                fail('mechanic-fallback-unavailable', `${definition.label} has no visible actor`);
+            return value;
+        }
+        case 'resource-reference': {
+            const candidates = definition.resourceIds.filter(resourceId => context.resourceIds.includes(resourceId));
+            const value = candidates[variant % candidates.length];
+            if (value === undefined)
+                fail('mechanic-fallback-unavailable', `${definition.label} has no resource`);
+            return value;
+        }
+        case 'object-reference': {
+            const objects = compatibleObjects(definition, context);
+            const value = objects[variant % objects.length]?.id;
+            if (value === undefined)
+                fail('mechanic-fallback-unavailable', `${definition.label} has no visible object`);
+            return value;
+        }
+        case 'object-reference-list': {
+            const objects = compatibleObjects(definition, context);
+            const offset = objects.length === 0 ? 0 : variant % objects.length;
+            const values = [...objects.slice(offset), ...objects.slice(0, offset)]
+                .slice(0, definition.minimumItems)
+                .map(object => object.id);
+            if (values.length < definition.minimumItems) {
+                fail('mechanic-fallback-unavailable', `${definition.label} has too few visible objects`);
+            }
+            return values;
+        }
+    }
+}
+function fallbackParameterRecord(definitions, context, variant) {
+    const relation = referencePairDefinition(definitions);
+    const pairs = relation === null ? null : compatibleReferencePairs(relation, context);
+    if (pairs !== null && pairs.length === 0) {
+        fail('mechanic-fallback-unavailable', 'The mechanic has no compatible reference pair');
+    }
+    const selected = pairs === null ? null : pairs[variant % pairs.length];
+    let stride = pairs?.length ?? 1;
+    const entries = definitions
+        .filter(definition => definition.required !== false)
+        .map((definition) => {
+        if (relation !== null && selected !== null) {
+            if (definition.id === relation.peer.id)
+                return [definition.id, selected.peerId];
+            if (definition.id === relation.parameter.id)
+                return [definition.id, selected.parameterId];
+        }
+        if (definition.valueFrom !== undefined)
+            return [definition.id, null];
+        const parameterVariant = Math.floor(variant / stride);
+        const entry = [
+            definition.id,
+            fallbackValue(definition, context, parameterVariant),
+        ];
+        stride = Math.min(Number.MAX_SAFE_INTEGER, stride * Math.max(1, fallbackVariantCount(definition, context)));
+        return entry;
+    });
+    const record = Object.fromEntries(entries);
+    for (const definition of definitions) {
+        if (definition.valueFrom !== undefined && definition.required !== false) {
+            record[definition.id] = scalarBindingValue(definition, record, definitions, context);
+        }
+    }
+    return record;
+}
+function referencePairDefinition(definitions) {
+    const linked = definitions.filter((parameter) => (parameter.kind === 'object-reference' && (parameter.dataMatch !== undefined || parameter.capacityMatch !== undefined || parameter.linkMatch !== undefined)));
+    if (linked.length === 0)
+        return null;
+    if (linked.length > 1) {
+        fail('mechanic-catalog-invalid', 'A parameter record supports one reference pair');
+    }
+    const parameter = linked[0];
+    const capacity = parameter.capacityMatch;
+    const link = parameter.linkMatch;
+    const match = capacity ?? link ?? parameter.dataMatch;
+    const keys = link !== undefined ? ['parameterId', 'relation'] : capacity === undefined ? ['parameterId', 'key', 'otherKey']
+        : ['parameterId', 'amountKey', 'capacityKey', 'usedKey', 'excludePeerReferenceKey'];
+    const required = capacity === undefined ? keys : keys.slice(0, 4);
+    if (match === null || typeof match !== 'object' || Array.isArray(match)
+        || [capacity, link, parameter.dataMatch].filter(value => value !== undefined).length !== 1
+        || required.some(key => !Object.hasOwn(match, key))
+        || Object.keys(match).some(key => !keys.includes(key))) {
+        fail('mechanic-catalog-invalid', 'A reference pair needs one complete supported constraint');
+    }
+    for (const value of Object.values(match))
+        assertIdentifier(value, 'reference pair field');
+    const peer = definitions.find(candidate => candidate.id === match.parameterId);
+    if (peer === undefined || peer.kind !== 'object-reference' || peer.id === parameter.id
+        || peer.required === false || parameter.required === false) {
+        fail('mechanic-catalog-invalid', 'A reference pair needs two distinct required object parameters');
+    }
+    if (link !== undefined) {
+        return { parameter, peer, matches: (candidate, other) => {
+                const links = other.links.filter(edge => edge.relation === link.relation);
+                return links.length === 1 && links[0].targetType === 'object' && links[0].targetId === candidate.id;
+            } };
+    }
+    if (capacity !== undefined) {
+        return { parameter, peer, matches: (candidate, other) => {
+                const amount = other.data[capacity.amountKey];
+                const maximum = candidate.data[capacity.capacityKey];
+                const used = candidate.data[capacity.usedKey];
+                if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0
+                    || typeof maximum !== 'number' || !Number.isFinite(maximum) || maximum < 0
+                    || typeof used !== 'number' || !Number.isFinite(used) || used < 0 || used > maximum)
+                    return false;
+                if (capacity.excludePeerReferenceKey !== undefined) {
+                    const sourceId = other.data[capacity.excludePeerReferenceKey];
+                    if (typeof sourceId !== 'string' || sourceId.length === 0 || sourceId === candidate.id)
+                        return false;
+                }
+                return amount <= maximum - used;
+            } };
+    }
+    const equality = parameter.dataMatch;
+    return { parameter, peer, matches: (candidate, other) => {
+            const value = other.data[equality.otherKey];
+            return (typeof value === 'string' || typeof value === 'boolean'
+                || (typeof value === 'number' && Number.isFinite(value))) && candidate.data[equality.key] === value;
+        } };
+}
+function compatibleReferencePairs(relation, context) {
+    const candidates = compatibleObjects(relation.parameter, context);
+    return compatibleObjects(relation.peer, context).flatMap(peer => (candidates.filter(candidate => relation.matches(candidate, peer))
+        .map(candidate => ({ peerId: peer.id, parameterId: candidate.id }))));
+}
+function fallbackVariantCount(definition, context) {
+    switch (definition.kind) {
+        case 'text':
+            return 27;
+        case 'number':
+            return definition.minimum === definition.maximum ? 1 : 2;
+        case 'integer':
+            return 7;
+        case 'boolean':
+            return 2;
+        case 'enum':
+            return definition.values.length;
+        case 'actor-reference':
+            return context.actorIds.filter(actorId => (definition.allowSelf === true || actorId !== context.actingActorId)).length;
+        case 'resource-reference':
+            return definition.resourceIds.filter(resourceId => context.resourceIds.includes(resourceId)).length;
+        case 'object-reference':
+        case 'object-reference-list':
+            return compatibleObjects(definition, context).length;
+    }
+}
+function compatibleObjects(definition, context) {
+    return context.objects.filter(object => (definition.objectKinds.includes(object.kind)
+        && (definition.ownedByActor !== true || (context.actingActorId !== null && object.ownerActorId === context.actingActorId))
+        && (definition.statuses === undefined || definition.statuses.includes(object.status))
+        && (definition.requiredData === undefined
+            || Object.entries(definition.requiredData).every(([key, value]) => object.data[key] === value))
+        && (definition.actorLinks === undefined || Object.entries(definition.actorLinks).every(([role, relation]) => {
+            const links = object.links.filter(link => link.targetType === 'actor' && link.relation === relation);
+            if (links.length !== 1)
+                return false;
+            const linked = links[0].targetId;
+            if (role === 'actor')
+                return linked === context.actingActorId
+                    || (context.actingActorId !== null && context.actorIds.includes(context.actingActorId)
+                        && definition.actorLinkExceptions?.includes(context.actingActorId) === true);
+            return context.targetActorId === undefined
+                ? context.actorIds.includes(linked) && linked !== context.actingActorId
+                : linked === context.targetActorId;
+        }))
+        && (definition.requiredNumericData === undefined || Object.entries(definition.requiredNumericData).every(([key, bounds]) => {
+            const value = object.data[key];
+            return typeof value === 'number' && Number.isFinite(value)
+                && (bounds.minimum === undefined || value >= bounds.minimum)
+                && (bounds.maximumExclusive === undefined || value < bounds.maximumExclusive);
+        }))
+        && isObjectVisibleToActor(object, context.actingActorId))).map((object, index) => ({ object, index })).sort((left, right) => {
+        if (definition.statuses === undefined)
+            return left.index - right.index;
+        const statusOrder = definition.statuses.indexOf(left.object.status)
+            - definition.statuses.indexOf(right.object.status);
+        return statusOrder === 0 ? left.index - right.index : statusOrder;
+    }).map(item => item.object);
+}
+function isObjectVisibleToActor(object, actorId) {
+    if (actorId === null || object.visibility.scope === 'world')
+        return true;
+    if (object.visibility.scope === 'shared')
+        return object.visibility.actorIds.includes(actorId);
+    return object.ownerActorId === actorId;
+}
+function strictObjectSchema(required, properties) {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: [...required],
+        properties: structuredClone(properties),
+    };
+}
+function assertRecord(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        fail('mechanic-parameter-invalid', `${label} must be an object`);
+    }
+    return value;
+}
+function assertExactKeys(value, allowed, required, label) {
+    const keys = Object.keys(value);
+    if (keys.some(key => !allowed.includes(key))) {
+        fail('mechanic-parameter-invalid', `${label} contains an unknown field`);
+    }
+    if (required.some(key => !Object.prototype.hasOwnProperty.call(value, key))) {
+        fail('mechanic-parameter-invalid', `${label} is missing a required field`);
+    }
+}
+function assertIdentifier(value, label) {
+    if (typeof value !== 'string'
+        || value.trim() !== value
+        || value.length === 0
+        || value.length > 128
+        || !/^[a-zA-Z][a-zA-Z0-9-]*$/.test(value)) {
+        fail('mechanic-catalog-invalid', `${label} is invalid`);
+    }
+}
+function assertText(value, label, maximum) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > maximum) {
+        fail('mechanic-catalog-invalid', `${label} must contain bounded text`);
+    }
+}
+function assertUnique(values, label) {
+    if (new Set(values).size !== values.length) {
+        fail('mechanic-catalog-invalid', `${label} must be unique`);
+    }
+}
+function fail(code, message) {
+    throw new DynamicMechanicContractError(code, message);
+}