@voce-engine/core 0.1.0-rc.2 → 0.1.0-rc.4

package/README.md

@@ -2,8 +2,29 @@
 
 Deterministic ScenarioPack resolution, constraint compilation, reference planning, Prompt IR, offline execution, and evaluation primitives.
 
-> `0.1.0-rc.2` is a release candidate, not production-ready. APIs may change before `0.1.0`.
+> `0.1.0-rc.4` is a release candidate, not production-ready. APIs may change before `0.1.0`.
 
 ```bash
-npm install @voce-engine/core@0.1.0-rc.2
+npm install @voce-engine/core@0.1.0-rc.4
 ```
+
+## Visual composition presets
+
+```ts
+import { compileConstraints, expandVisualCompositionPreset } from '@voce-engine/core'
+
+const compositionChanges = expandVisualCompositionPreset('dutch-angle', {
+  inputs: { direction: 'right' },
+  sourceHintIds: ['ui-card:dutch-angle'],
+})
+
+const result = compileConstraints({
+  ...existingCompilationInput,
+  changeIntents: [
+    ...existingCompilationInput.changeIntents,
+    ...compositionChanges,
+  ],
+})
+```
+
+Hosts should display the example artwork but submit only the stable preset ID and typed inputs. The artwork is not a reference asset and the selector does not consume reference budget. See the [complete preset and integration guide](../../docs/visual-composition.md) or its [简体中文 version](../../docs/zh-CN/visual-composition.md).

package/dist/composition.d.ts

@@ -0,0 +1,36 @@
+import type { ChangeIntent, JsonValue, OntologyPathDefinition, Provenance } from '@voce-engine/contracts';
+export declare const VISUAL_COMPOSITION_SCHEMA_VERSION: "voce.visual-composition/v1alpha1";
+export declare const VISUAL_COMPOSITION_CATALOG_ID = "visual-composition.v1";
+export declare const VISUAL_COMPOSITION_FIXED_TIME = "2026-01-01T00:00:00.000Z";
+export interface CompositionChangeTemplate {
+    operation: ChangeIntent['operation'];
+    targetPath: string;
+    requestedValue?: JsonValue;
+    valueFrom?: 'direction' | 'surface' | 'silhouette';
+}
+export interface VisualCompositionPreset {
+    id: string;
+    labelKey: string;
+    descriptionKey: string;
+    category: 'framing' | 'view' | 'layout' | 'depth' | 'lens';
+    compatibilityHints?: string[];
+    changes: CompositionChangeTemplate[];
+    requiredInputs?: string[];
+}
+export interface VisualCompositionCatalog {
+    schemaVersion: typeof VISUAL_COMPOSITION_SCHEMA_VERSION;
+    id: string;
+    paths: OntologyPathDefinition[];
+    presets: VisualCompositionPreset[];
+    catalogHash: string;
+}
+export declare const VISUAL_COMPOSITION_PATHS: OntologyPathDefinition[];
+export declare const VISUAL_COMPOSITION_PRESETS: VisualCompositionPreset[];
+export declare const VISUAL_COMPOSITION_CATALOG: VisualCompositionCatalog;
+export declare function computeVisualCompositionCatalogHash(catalog?: VisualCompositionCatalog): string;
+export declare function expandVisualCompositionPreset(presetId: string, options?: {
+    inputs?: Record<string, JsonValue>;
+    provenance?: Provenance;
+    sourceHintIds?: string[];
+}): ChangeIntent[];
+export declare function compositionCatalogCanonicalJson(catalog?: VisualCompositionCatalog): string;

package/dist/composition.js

@@ -0,0 +1,108 @@
+import { canonicalize, sha256 } from './canonical.js';
+export const VISUAL_COMPOSITION_SCHEMA_VERSION = 'voce.visual-composition/v1alpha1';
+export const VISUAL_COMPOSITION_CATALOG_ID = 'visual-composition.v1';
+export const VISUAL_COMPOSITION_FIXED_TIME = '2026-01-01T00:00:00.000Z';
+const enumPath = (path, allowedValues, defaultImportance = 'preferred') => ({ path, valueKind: 'enum', cardinality: 'one', allowedValues, defaultImportance });
+const boolPath = (path, defaultImportance = 'preferred') => ({ path, valueKind: 'boolean', cardinality: 'one', defaultImportance });
+const clone = (value) => JSON.parse(JSON.stringify(value));
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+export const VISUAL_COMPOSITION_PATHS = [
+    enumPath('camera.framing.shotScale', ['extreme_close_up', 'close_up', 'head_and_shoulders', 'bust_shot', 'medium_close_up', 'medium_shot', 'knee_shot', 'full_shot', 'long_shot', 'extreme_long_shot']),
+    boolPath('camera.framing.crop.keepHead'), boolPath('camera.framing.crop.keepHands'), boolPath('camera.framing.crop.keepBothFeet'), boolPath('camera.framing.crop.keepProduct'), boolPath('camera.framing.crop.keepSignatureProp'),
+    enumPath('camera.view.elevation', ['eye_level', 'low_angle', 'high_angle', 'birds_eye']), enumPath('camera.view.relationship', ['front', 'three_quarter', 'profile', 'rear', 'over_the_shoulder']),
+    enumPath('camera.roll.mode', ['level', 'dutch_left', 'dutch_right']), enumPath('camera.lens.focalLengthClass', ['ultra_wide', 'wide', 'normal', 'telephoto', 'super_telephoto']), enumPath('camera.lens.perspective', ['expanded', 'natural', 'compressed']),
+    boolPath('camera.composition.patterns.centeredSymmetry'), boolPath('camera.composition.patterns.ruleOfThirds'), boolPath('camera.composition.patterns.leadingLines'), boolPath('camera.composition.patterns.diagonal'), boolPath('camera.composition.patterns.sCurve'), boolPath('camera.composition.patterns.triangle'),
+    enumPath('camera.composition.placement', ['center', 'left_third', 'right_third', 'upper_third', 'lower_third']), enumPath('camera.composition.negativeSpace', ['none', 'left', 'right', 'above', 'below', 'surrounding']),
+    boolPath('camera.composition.leadingRoom.enabled'), enumPath('camera.composition.leadingRoom.direction', ['left', 'right', 'forward', 'up', 'down']),
+    enumPath('camera.composition.foregroundTreatment', ['clear', 'soft_obstruction', 'strong_obstruction']), boolPath('camera.composition.framingDevices.frameWithinFrame'), boolPath('camera.composition.framingDevices.environmentalPortrait'),
+    boolPath('camera.composition.reflection.enabled'), enumPath('camera.composition.reflection.surface', ['mirror', 'glass', 'water', 'screen', 'polished_surface']), enumPath('camera.composition.reflection.role', ['supporting', 'co_primary', 'primary']), enumPath('camera.composition.environmentRelationship', ['isolated', 'contextual', 'environment_dominant']),
+    enumPath('lighting.subjectRendering', ['natural', 'silhouette']),
+];
+const preset = (id, category, changes, requiredInputs = [], compatibilityHints = []) => ({ id, labelKey: `visualComposition.${id}.label`, descriptionKey: `visualComposition.${id}.description`, category, ...(compatibilityHints.length ? { compatibilityHints } : {}), changes, ...(requiredInputs.length ? { requiredInputs } : {}) });
+export const VISUAL_COMPOSITION_PRESETS = [
+    preset('extreme-close-up', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'extreme_close_up' }]),
+    preset('close-up', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'close_up' }]),
+    preset('head-and-shoulders', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'head_and_shoulders' }, { operation: 'adjust', targetPath: 'camera.framing.crop.keepHead', requestedValue: true }]),
+    preset('bust-shot', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'bust_shot' }, { operation: 'adjust', targetPath: 'camera.framing.crop.keepHead', requestedValue: true }]),
+    preset('medium-close-up', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'medium_close_up' }]),
+    preset('medium-shot', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'medium_shot' }]),
+    preset('knee-shot', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'knee_shot' }]),
+    preset('full-shot', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'full_shot' }, { operation: 'adjust', targetPath: 'camera.framing.crop.keepBothFeet', requestedValue: true }]),
+    preset('long-shot', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'long_shot' }, { operation: 'adjust', targetPath: 'camera.composition.environmentRelationship', requestedValue: 'contextual' }]),
+    preset('extreme-long-shot', 'framing', [{ operation: 'replace', targetPath: 'camera.framing.shotScale', requestedValue: 'extreme_long_shot' }, { operation: 'adjust', targetPath: 'camera.composition.environmentRelationship', requestedValue: 'environment_dominant' }]),
+    preset('low-angle', 'view', [{ operation: 'adjust', targetPath: 'camera.view.elevation', requestedValue: 'low_angle' }]),
+    preset('high-angle', 'view', [{ operation: 'adjust', targetPath: 'camera.view.elevation', requestedValue: 'high_angle' }]),
+    preset('birds-eye-view', 'view', [{ operation: 'adjust', targetPath: 'camera.view.elevation', requestedValue: 'birds_eye' }]),
+    preset('over-the-shoulder', 'view', [{ operation: 'adjust', targetPath: 'camera.view.relationship', requestedValue: 'over_the_shoulder' }], [], ['foreground-shoulder-subject-or-declared-equivalent']),
+    preset('dutch-angle', 'view', [{ operation: 'adjust', targetPath: 'camera.roll.mode', valueFrom: 'direction' }], ['direction']),
+    preset('centered-symmetry', 'layout', [{ operation: 'adjust', targetPath: 'camera.composition.patterns.centeredSymmetry', requestedValue: true }, { operation: 'adjust', targetPath: 'camera.composition.placement', requestedValue: 'center' }]),
+    preset('rule-of-thirds', 'layout', [{ operation: 'adjust', targetPath: 'camera.composition.patterns.ruleOfThirds', requestedValue: true }]),
+    preset('leading-lines', 'layout', [{ operation: 'adjust', targetPath: 'camera.composition.patterns.leadingLines', requestedValue: true }], [], ['suitable-scene-geometry-or-review']),
+    preset('leading-room', 'layout', [{ operation: 'adjust', targetPath: 'camera.composition.leadingRoom.enabled', requestedValue: true }, { operation: 'adjust', targetPath: 'camera.composition.leadingRoom.direction', valueFrom: 'direction' }], ['direction']),
+    preset('diagonal-composition', 'layout', [{ operation: 'adjust', targetPath: 'camera.composition.patterns.diagonal', requestedValue: true }]),
+    preset('s-curve-composition', 'layout', [{ operation: 'adjust', targetPath: 'camera.composition.patterns.sCurve', requestedValue: true }]),
+    preset('triangle-composition', 'layout', [{ operation: 'adjust', targetPath: 'camera.composition.patterns.triangle', requestedValue: true }]),
+    preset('negative-space', 'layout', [{ operation: 'adjust', targetPath: 'camera.composition.negativeSpace', valueFrom: 'direction' }], ['direction']),
+    preset('frame-within-frame', 'depth', [{ operation: 'adjust', targetPath: 'camera.composition.framingDevices.frameWithinFrame', requestedValue: true }]),
+    preset('foreground-obstruction', 'depth', [{ operation: 'adjust', targetPath: 'camera.composition.foregroundTreatment', requestedValue: 'soft_obstruction' }]),
+    preset('profile-silhouette', 'view', [{ operation: 'adjust', targetPath: 'camera.view.relationship', requestedValue: 'profile' }]),
+    preset('reflection-composition', 'depth', [{ operation: 'adjust', targetPath: 'camera.composition.reflection.enabled', requestedValue: true }, { operation: 'adjust', targetPath: 'camera.composition.reflection.surface', valueFrom: 'surface' }], ['surface']),
+    preset('mirror-composition', 'depth', [{ operation: 'adjust', targetPath: 'camera.composition.reflection.enabled', requestedValue: true }, { operation: 'adjust', targetPath: 'camera.composition.reflection.surface', requestedValue: 'mirror' }]),
+    preset('telephoto-compression', 'lens', [{ operation: 'adjust', targetPath: 'camera.lens.focalLengthClass', requestedValue: 'telephoto' }, { operation: 'adjust', targetPath: 'camera.lens.perspective', requestedValue: 'compressed' }]),
+    preset('environmental-portrait', 'depth', [{ operation: 'adjust', targetPath: 'camera.composition.framingDevices.environmentalPortrait', requestedValue: true }, { operation: 'adjust', targetPath: 'camera.composition.environmentRelationship', requestedValue: 'contextual' }]),
+];
+deepFreeze(VISUAL_COMPOSITION_PATHS);
+deepFreeze(VISUAL_COMPOSITION_PRESETS);
+const VISUAL_COMPOSITION_CATALOG_BODY = { schemaVersion: VISUAL_COMPOSITION_SCHEMA_VERSION, id: VISUAL_COMPOSITION_CATALOG_ID, paths: VISUAL_COMPOSITION_PATHS, presets: VISUAL_COMPOSITION_PRESETS };
+export const VISUAL_COMPOSITION_CATALOG = deepFreeze({ ...VISUAL_COMPOSITION_CATALOG_BODY, catalogHash: sha256(VISUAL_COMPOSITION_CATALOG_BODY) });
+export function computeVisualCompositionCatalogHash(catalog = VISUAL_COMPOSITION_CATALOG) {
+    return sha256({ schemaVersion: catalog.schemaVersion, id: catalog.id, paths: catalog.paths, presets: catalog.presets });
+}
+function valueForTemplate(template, options) {
+    let value = template.valueFrom === undefined ? template.requestedValue : options[template.valueFrom];
+    if (template.valueFrom !== undefined && value === undefined)
+        throw new Error('COMPOSITION_PRESET_INPUT_REQUIRED');
+    if (template.targetPath === 'camera.roll.mode') {
+        if (value !== 'left' && value !== 'right')
+            throw new Error('COMPOSITION_DIRECTION_INVALID');
+        value = value === 'left' ? 'dutch_left' : 'dutch_right';
+    }
+    if (value === undefined)
+        return undefined;
+    const definition = VISUAL_COMPOSITION_PATHS.find((item) => item.path === template.targetPath);
+    const valid = definition?.valueKind === 'boolean' ? typeof value === 'boolean'
+        : definition?.valueKind === 'string' ? typeof value === 'string'
+            : definition?.valueKind === 'number' ? typeof value === 'number' && Number.isFinite(value)
+                : definition?.valueKind === 'enum' && definition.allowedValues?.some((allowed) => canonicalize(allowed) === canonicalize(value));
+    if (!definition || !valid)
+        throw new Error('COMPOSITION_PRESET_INPUT_INVALID');
+    return clone(value);
+}
+export function expandVisualCompositionPreset(presetId, options = {}) {
+    const selected = VISUAL_COMPOSITION_PRESETS.find((item) => item.id === presetId);
+    if (!selected)
+        throw new Error('COMPOSITION_PRESET_NOT_FOUND');
+    const inputs = options.inputs ?? {};
+    for (const key of selected.requiredInputs ?? [])
+        if (inputs[key] === undefined)
+            throw new Error('COMPOSITION_PRESET_INPUT_REQUIRED');
+    const provenance = options.provenance ?? { source: 'user_explicit', sourceIds: [presetId], createdBy: 'visual-composition-preset', createdAt: VISUAL_COMPOSITION_FIXED_TIME };
+    const sourceHintIds = [...new Set([presetId, ...(options.sourceHintIds ?? [])])].sort();
+    const changes = selected.changes.map((template, index) => {
+        const requestedValue = valueForTemplate(template, inputs);
+        return { schemaVersion: 'voce.change-intent/v1alpha1', id: `composition.${presetId}.${index + 1}`, operation: template.operation, targetPath: template.targetPath, ...(requestedValue === undefined ? {} : { requestedValue }), sourceHintIds: [...sourceHintIds], importance: 'preferred', provenance: clone(provenance) };
+    });
+    if (presetId === 'profile-silhouette' && inputs.silhouette === true)
+        changes.push({ schemaVersion: 'voce.change-intent/v1alpha1', id: `composition.${presetId}.silhouette`, operation: 'adjust', targetPath: 'lighting.subjectRendering', requestedValue: 'silhouette', sourceHintIds: [...sourceHintIds], importance: 'preferred', provenance: clone(provenance) });
+    return changes;
+}
+export function compositionCatalogCanonicalJson(catalog = VISUAL_COMPOSITION_CATALOG) {
+    return canonicalize({ schemaVersion: catalog.schemaVersion, id: catalog.id, paths: catalog.paths, presets: catalog.presets });
+}

package/dist/index.d.ts

@@ -19,3 +19,4 @@ export * from './evidence.js';
 export * from './m4.js';
 export * from './m5.js';
 export * from './m6.js';
+export * from './composition.js';

package/dist/index.js

@@ -164,6 +164,74 @@ function contributionDigest(value) {
     delete copy.contentDigest;
     return sha256(copy);
 }
+function validateTypedContribution(category, value) {
+    if (category === 'ontologyVocabulary') {
+        if (!Array.isArray(value.paths))
+            throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+        const ids = new Set();
+        for (const raw of value.paths) {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+            const path = raw;
+            if (typeof path.path !== 'string' || !path.path || (path.valueKind !== 'boolean' && path.valueKind !== 'enum' && path.valueKind !== 'string' && path.valueKind !== 'number') || (path.cardinality !== 'one' && path.cardinality !== 'many') || ids.has(path.path))
+                throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+            if (path.valueKind === 'enum' && (!Array.isArray(path.allowedValues) || path.allowedValues.length === 0))
+                throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+            ids.add(path.path);
+        }
+        return;
+    }
+    if (category === 'rulePacks') {
+        if (!Array.isArray(value.rules))
+            throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+        const ids = new Set();
+        for (const raw of value.rules) {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+            const rule = raw;
+            if (typeof rule.id !== 'string' || !rule.id || ids.has(rule.id) || !['incompatibility', 'dependency', 'cardinality', 'occlusion', 'resource'].includes(String(rule.kind)) || !Array.isArray(rule.operands) || rule.operands.length < 2 || !rule.resolution || typeof rule.resolution !== 'object' || Array.isArray(rule.resolution) || typeof rule.explanation !== 'string')
+                throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+            const operandIds = new Set();
+            for (const rawOperand of rule.operands) {
+                if (!rawOperand || typeof rawOperand !== 'object' || Array.isArray(rawOperand))
+                    throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+                const operand = rawOperand;
+                if (typeof operand.id !== 'string' || !operand.id || operandIds.has(operand.id) || !Array.isArray(operand.conditions) || operand.conditions.length === 0)
+                    throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+                operandIds.add(operand.id);
+                for (const rawCondition of operand.conditions) {
+                    if (!rawCondition || typeof rawCondition !== 'object' || Array.isArray(rawCondition))
+                        throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+                    const condition = rawCondition;
+                    if (typeof condition.path !== 'string' || !condition.path || !['present', 'absent', 'equals', 'contains'].includes(String(condition.operator)))
+                        throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+                    if ((condition.operator === 'present' || condition.operator === 'absent') && condition.value !== undefined)
+                        throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+                    if ((condition.operator === 'equals' || condition.operator === 'contains') && condition.value === undefined)
+                        throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+                }
+            }
+            const resolution = rule.resolution;
+            if ((resolution.strategy !== 'block' && resolution.strategy !== 'degrade_operand') || typeof resolution.reasonCode !== 'string' || !resolution.reasonCode || (resolution.strategy === 'degrade_operand' && (typeof resolution.operandId !== 'string' || !operandIds.has(resolution.operandId))))
+                throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+            ids.add(rule.id);
+        }
+        return;
+    }
+    if (category === 'promptSections') {
+        if (!Array.isArray(value.sections))
+            throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+        const ids = new Set();
+        for (const raw of value.sections) {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+            const section = raw;
+            if (typeof section.id !== 'string' || !section.id || ids.has(section.id) || typeof section.group !== 'string' || !Number.isInteger(section.order) || !Array.isArray(section.pathPrefixes) || section.pathPrefixes.length === 0 || section.pathPrefixes.some((item) => typeof item !== 'string' || !item) || typeof section.templateKey !== 'string' || !section.templateKey)
+                throw new Error('PACK_TYPED_CONTRIBUTION_INVALID');
+            ids.add(section.id);
+        }
+    }
+}
 function descriptorFor(definition, files) {
     if (!definition || typeof definition !== 'object' || Array.isArray(definition) || !definition.manifest)
         throw new Error('PACK_MANIFEST_INVALID');
@@ -197,6 +265,8 @@ function descriptorFor(definition, files) {
             bodyIds.add(id);
             if (indexed.get(id) !== contribution.contentDigest || contributionDigest(contribution) !== contribution.contentDigest)
                 throw new Error('PACK_DIGEST_MISMATCH');
+            if ((category === 'ontologyVocabulary' && Array.isArray(contribution.paths)) || (category === 'rulePacks' && Array.isArray(contribution.rules)) || (category === 'promptSections' && Array.isArray(contribution.sections)))
+                validateTypedContribution(category, contribution);
         }
     }
     const manifestHash = sha256(json(definition.manifest));
@@ -335,6 +405,29 @@ function composeCategory(category, ordered, packages, disabled, defaultValues) {
     }
     return { values: [...byId.values()].map((item) => withSource(item.value, item.packId, category, item.sourcePackIds)) };
 }
+function ontologyPathDefinitionCollision(contributions) {
+    const byPath = new Map();
+    for (const contribution of contributions) {
+        const paths = Array.isArray(contribution.paths) ? contribution.paths : [];
+        for (const raw of paths) {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                continue;
+            const definition = raw;
+            if (typeof definition.path !== 'string')
+                continue;
+            const entries = byPath.get(definition.path) ?? [];
+            entries.push({ canonical: canonicalize(raw), packId: contribution.packId, contributionId: contribution.contributionId });
+            byPath.set(definition.path, entries);
+        }
+    }
+    for (const path of [...byPath.keys()].sort(compareCodeUnits)) {
+        const entries = byPath.get(path);
+        if (new Set(entries.map((entry) => entry.canonical)).size <= 1)
+            continue;
+        return conflict('PACK_RULE_CONFLICT', [...new Set(entries.map((entry) => entry.packId))].sort(compareCodeUnits), `Ontology path ${path} has conflicting definitions after ScenarioPack composition.`, 'Make duplicate path definitions canonically identical or use distinct ontology paths.', [...new Set(entries.map((entry) => entry.contributionId))].sort(compareCodeUnits));
+    }
+    return undefined;
+}
 function overridePayload(override) {
     return { id: override.id, operation: override.operation, reasonCode: override.reasonCode };
 }
@@ -550,6 +643,9 @@ export function resolveScenario(selection, catalog, packages, descriptors = new
             return { status: 'blocked', report: failureReport(selected, dependencyTrace, compositionTrace, overrideTraces, [composed.collision], warnings) };
         effectiveValues[category] = composed.values;
     }
+    const pathCollision = ontologyPathDefinitionCollision(effectiveValues.ontologyVocabulary);
+    if (pathCollision)
+        return { status: 'blocked', report: failureReport(selected, dependencyTrace, compositionTrace, overrideTraces, [pathCollision], warnings) };
     const entries = ordered.map((entry) => ({
         packId: entry.manifest.packId,
         version: entry.manifest.version,
@@ -563,7 +659,7 @@ export function resolveScenario(selection, catalog, packages, descriptors = new
     const lockBase = { schemaVersion: 'voce.scenario-pack-lock/v1alpha1', contractVersion: CONTRACT_VERSION, resolverVersion: catalog.resolverVersion, catalogHash: catalog.catalogHash, canonicalization: 'voce.canonical-json/v1alpha1', rootPackId: root.manifest.packId, entries, compositionOrder: order, ...(overlay ? { hostPolicyOverlayHash: overlay.overlayHash } : {}), hostOverrideHashes: appliedOverrides.map((item) => item.contentHash) };
     const lock = { ...lockBase, compositionHash: sha256(json(lockBase)), lockHash: '' };
     lock.lockHash = hashWithoutSelf(lock, 'lockHash');
-    const effective = { lockHash: lock.lockHash, rootPackId: root.manifest.packId, extensionPackIds: ordered.filter((entry) => entry.manifest.kind === 'extension').map((entry) => entry.manifest.packId), compositionOrder: order, configurations: Object.fromEntries([...configs].sort((left, right) => compareCodeUnits(left[0], right[0]))), ...effectiveValues, capabilityRequirements: ordered.flatMap((entry) => entry.manifest.capabilityRequirements), declarations: ordered.map((entry) => entry.manifest.declarations), appliedOverrides, effectiveScenarioHash: '' };
+    const effective = { lockHash: lock.lockHash, rootPackId: root.manifest.packId, extensionPackIds: ordered.filter((entry) => entry.manifest.kind === 'extension').map((entry) => entry.manifest.packId), compositionOrder: order, configurations: Object.fromEntries([...configs].sort((left, right) => compareCodeUnits(left[0], right[0]))), ontologyVocabulary: effectiveValues.ontologyVocabulary, rulePacks: effectiveValues.rulePacks, interpretationScopes: effectiveValues.interpretationScopes, promptSections: effectiveValues.promptSections, reviewTemplates: effectiveValues.reviewTemplates, defaults: effectiveValues.defaults, capabilityRequirements: ordered.flatMap((entry) => entry.manifest.capabilityRequirements), declarations: ordered.map((entry) => entry.manifest.declarations), appliedOverrides, effectiveScenarioHash: '' };
     effective.effectiveScenarioHash = hashWithoutSelf(effective, 'effectiveScenarioHash');
     const reportBase = { status: 'resolved', lockHash: lock.lockHash, effectiveScenarioHash: effective.effectiveScenarioHash, selected: selected.map((entry) => ({ packId: entry.manifest.packId, version: entry.manifest.version, kind: entry.manifest.kind, packageDigest: entry.packageDigest, manifestHash: entry.manifestHash })), dependencyTrace, compositionTrace, overrideTraces, conflicts: [], warnings };
     return { status: 'resolved', lock, effectiveScenario: effective, report: { ...reportBase, reportHash: hashWithoutSelf(reportBase, 'reportHash') } };
@@ -606,3 +702,4 @@ export * from './evidence.js';
 export * from './m4.js';
 export * from './m5.js';
 export * from './m6.js';
+export * from './composition.js';

package/dist/m4.js

@@ -450,27 +450,68 @@ function internalRule(value, contributionId) {
     const id = typeof object.id === 'string' ? object.id : typeof object.ruleId === 'string' ? object.ruleId : undefined;
     if (!id)
         return undefined;
-    const type = object.ruleType ?? object.type ?? object.kind;
-    const kind = type === 'resource' ? 'resource' : type === 'dependency' ? 'dependency' : type === 'occlusion' ? 'occlusion' : 'incompatibility';
-    const leftPaths = Array.isArray(object.leftPaths) ? object.leftPaths.filter((item) => typeof item === 'string') : Array.isArray(object.whenPaths) ? object.whenPaths.filter((item) => typeof item === 'string') : [];
-    const rightPaths = Array.isArray(object.rightPaths) ? object.rightPaths.filter((item) => typeof item === 'string') : Array.isArray(object.conflictingPaths) ? object.conflictingPaths.filter((item) => typeof item === 'string') : [];
-    if (leftPaths.length === 0 || rightPaths.length === 0)
+    const kind = object.kind;
+    if (kind !== 'incompatibility' && kind !== 'dependency' && kind !== 'cardinality' && kind !== 'occlusion' && kind !== 'resource')
         return undefined;
-    const tokenList = (field) => Array.isArray(object[field]) ? object[field].filter((item) => typeof item === 'string') : [];
-    const severity = normalizeImportance(object.importance ?? object.severity);
+    if (!Array.isArray(object.operands) || object.operands.length < 2)
+        return undefined;
+    const conditionOperator = (value) => value === 'present' || value === 'absent' || value === 'equals' || value === 'contains';
+    const conditions = (value) => {
+        if (!Array.isArray(value) || value.length === 0)
+            return undefined;
+        const result = [];
+        for (const candidate of value) {
+            if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
+                return undefined;
+            const condition = candidate;
+            if (typeof condition.path !== 'string' || !condition.path || !conditionOperator(condition.operator))
+                return undefined;
+            if ((condition.operator === 'present' || condition.operator === 'absent') && condition.value !== undefined)
+                return undefined;
+            if ((condition.operator === 'equals' || condition.operator === 'contains') && condition.value === undefined)
+                return undefined;
+            result.push({ path: condition.path, operator: condition.operator, ...(condition.value === undefined ? {} : { value: jsonReady(condition.value) }) });
+        }
+        return result;
+    };
+    const operands = [];
+    const operandIds = new Set();
+    for (const candidate of object.operands) {
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
+            return undefined;
+        const operand = candidate;
+        if (typeof operand.id !== 'string' || !operand.id || operandIds.has(operand.id))
+            return undefined;
+        const operandConditions = conditions(operand.conditions);
+        if (!operandConditions)
+            return undefined;
+        operandIds.add(operand.id);
+        operands.push({ id: operand.id, conditions: operandConditions, match: 'all' });
+    }
+    const resolutionValue = object.resolution;
+    if (!resolutionValue || typeof resolutionValue !== 'object' || Array.isArray(resolutionValue))
+        return undefined;
+    const resolutionObject = resolutionValue;
+    if (resolutionObject.strategy !== 'block' && resolutionObject.strategy !== 'degrade_operand')
+        return undefined;
+    if (typeof resolutionObject.reasonCode !== 'string' || !resolutionObject.reasonCode)
+        return undefined;
+    const operandId = resolutionObject.operandId;
+    if (resolutionObject.strategy === 'degrade_operand' && (typeof operandId !== 'string' || !operandIds.has(operandId)))
+        return undefined;
+    const resolution = { strategy: resolutionObject.strategy, reasonCode: resolutionObject.reasonCode, ...(operandId === undefined ? {} : { operandId: operandId }) };
+    const severity = normalizeImportance(object.importance);
     const code = typeof object.code === 'string' ? object.code : `RULE_${id.toUpperCase().replaceAll(/[^A-Z0-9]+/g, '_')}`;
-    const reasonCode = typeof object.reasonCode === 'string' ? object.reasonCode : code;
-    const message = typeof object.message === 'string' ? object.message : `Declarative rule ${id} found incompatible constraints.`;
+    const reasonCode = resolution.reasonCode;
+    const message = typeof object.explanation === 'string' ? object.explanation : typeof object.message === 'string' ? object.message : `Declarative rule ${id} found incompatible constraints.`;
     const dependencyKind = object.dependencyKind === 'parent_detail' || object.dependencyKind === 'identity_garment' || object.dependencyKind === 'source_isolation' || object.dependencyKind === 'visibility' || object.dependencyKind === 'occludes' || object.dependencyKind === 'ordered_before' || object.dependencyKind === 'supports' || object.dependencyKind === 'excludes' || object.dependencyKind === 'requires' ? object.dependencyKind : undefined;
     return {
         id,
         contributionId,
         code,
         kind,
-        leftPaths: sortedStrings(leftPaths),
-        rightPaths: sortedStrings(rightPaths),
-        leftTokens: sortedStrings(tokenList('leftTokens')),
-        rightTokens: sortedStrings(tokenList('rightTokens')),
+        operands,
+        resolution,
         importance: severity,
         reasonCode,
         message,
@@ -479,25 +520,40 @@ function internalRule(value, contributionId) {
     };
 }
 function allRules(effectiveScenario, collisionIds = []) {
-    const values = M4_DECLARATIVE_RULE_FIXTURES.map((value) => ({ value }));
+    const values = [];
     for (const contribution of effectiveScenario?.rulePacks ?? []) {
         const object = contribution;
         const rules = Array.isArray(object.rules) ? object.rules : [];
         for (const rule of rules)
             values.push({ value: rule, contributionId: typeof object.contributionId === 'string' ? object.contributionId : undefined });
-        if (rules.length === 0)
-            values.push({ value: contribution, contributionId: typeof object.contributionId === 'string' ? object.contributionId : undefined });
     }
     const byId = new Map();
-    for (const entry of values) {
-        const rule = internalRule(entry.value, entry.contributionId);
-        if (!rule)
-            continue;
+    const add = (rule) => {
         const prior = byId.get(rule.id);
-        if (prior && canonicalize(jsonReady(rule)) !== canonicalize(jsonReady(prior)))
+        const semantic = (value) => canonicalize(jsonReady(cleanWithout(value, 'contributionId')));
+        if (prior && semantic(rule) !== semantic(prior))
             collisionIds.push(rule.id);
         if (!prior || canonicalize(jsonReady(rule)) < canonicalize(jsonReady(prior)))
             byId.set(rule.id, rule);
+    };
+    for (const value of M4_DECLARATIVE_RULE_FIXTURES) {
+        const left = Array.from(value.leftPaths);
+        const right = Array.from(value.rightPaths);
+        if (left.length === 0 || right.length === 0)
+            continue;
+        const toConditions = (paths, tokens = []) => [
+            ...paths.map((path) => ({ path, operator: 'present' })),
+            ...tokens.map((token) => ({ path: paths[0], operator: 'contains', value: token })),
+        ];
+        const leftOperand = { id: 'left', conditions: left.map((path) => ({ path, operator: 'present' })), match: 'any' };
+        const rightOperand = { id: 'right', conditions: toConditions(right, value.rightTokens), match: 'any' };
+        add({ id: value.id, code: value.code, kind: value.ruleType === 'resource' ? 'resource' : 'occlusion', operands: [leftOperand, rightOperand], resolution: { strategy: 'block', reasonCode: value.reasonCode }, importance: value.importance, reasonCode: value.reasonCode, message: value.message, resourceId: 'resourceId' in value ? value.resourceId : undefined });
+    }
+    for (const entry of values) {
+        const rule = internalRule(entry.value, entry.contributionId);
+        if (!rule)
+            continue;
+        add(rule);
     }
     return sortedBy([...byId.values()], (item) => item.id);
 }
@@ -522,12 +578,174 @@ function semanticItems(input) {
     }));
     return sortedBy([...intentItems, ...factItems], (item) => `${item.path}|${item.id}`);
 }
+function conditionMatches(condition, items) {
+    const candidates = items.filter((item) => pathMatches(item.path, condition.path));
+    if (condition.operator === 'absent')
+        return { matched: candidates.length === 0, items: [] };
+    if (condition.operator === 'present')
+        return { matched: candidates.length > 0, items: candidates };
+    if (condition.operator === 'equals') {
+        const matched = candidates.filter((item) => canonicalize(item.value) === canonicalize(condition.value));
+        return { matched: matched.length > 0, items: matched };
+    }
+    const value = condition.value;
+    const matched = typeof value === 'string'
+        ? candidates.filter((item) => valueHasToken(item.value, [value]))
+        : candidates.filter((item) => Array.isArray(item.value) && item.value.some((entry) => canonicalize(entry) === canonicalize(value)));
+    return { matched: matched.length > 0, items: matched };
+}
+function compositionVocabulary(effectiveScenario, collisionPaths = []) {
+    const definitions = new Map();
+    for (const contribution of effectiveScenario?.ontologyVocabulary ?? []) {
+        for (const raw of (contribution.paths ?? [])) {
+            if (!raw || typeof raw.path !== 'string' || !raw.path)
+                continue;
+            const prior = definitions.get(raw.path);
+            if (prior && canonicalize(jsonReady(raw)) !== canonicalize(jsonReady(prior)))
+                collisionPaths.push(raw.path);
+            else if (!prior)
+                definitions.set(raw.path, clone(raw));
+        }
+    }
+    return definitions;
+}
+function ontologyScalarMatches(definition, value) {
+    if (definition.valueKind === 'boolean')
+        return typeof value === 'boolean';
+    if (definition.valueKind === 'string')
+        return typeof value === 'string';
+    if (definition.valueKind === 'number')
+        return typeof value === 'number' && Number.isFinite(value);
+    return Array.isArray(definition.allowedValues) && definition.allowedValues.some((allowed) => canonicalize(allowed) === canonicalize(value));
+}
+function ontologyValueMatches(definition, value) {
+    if (definition.cardinality === 'many' && Array.isArray(value))
+        return value.every((entry) => ontologyScalarMatches(definition, entry));
+    return ontologyScalarMatches(definition, value);
+}
+function applyCardinalityResolution(constraints, goals, vocabulary) {
+    const remap = new Map();
+    const conflicts = [];
+    const degradations = [];
+    const traces = [];
+    const mergedConstraints = [];
+    const cardinalityConstraintIds = new Set();
+    const byPath = new Map();
+    for (const constraint of constraints) {
+        if (!constraint.targetPath || constraint.value === undefined || constraint.status === 'unsatisfied' || !vocabulary.has(constraint.targetPath))
+            continue;
+        if (vocabulary.get(constraint.targetPath).cardinality !== 'one')
+            continue;
+        byPath.set(constraint.targetPath, [...(byPath.get(constraint.targetPath) ?? []), constraint]);
+    }
+    const degraded = new Set();
+    const markUnsatisfied = (constraint, ruleId, reasonCode) => {
+        constraint.status = 'unsatisfied';
+        constraint.ruleId = ruleId;
+        constraint.reasonCode = reasonCode;
+        constraint.constraintHash = computeConstraintHash(constraint);
+    };
+    for (const [path, pathConstraints] of [...byPath.entries()].sort((left, right) => compareCodeUnits(left[0], right[0]))) {
+        for (const item of pathConstraints)
+            cardinalityConstraintIds.add(item.id);
+        const valueGroups = new Map();
+        for (const constraint of sortedBy(pathConstraints, (item) => item.id)) {
+            const key = canonicalize(jsonReady(constraint.value));
+            valueGroups.set(key, [...(valueGroups.get(key) ?? []), constraint]);
+        }
+        const merged = [];
+        for (const group of [...valueGroups.values()].sort((left, right) => compareCodeUnits(canonicalize(jsonReady(left[0].value)), canonicalize(jsonReady(right[0].value))))) {
+            const representative = sortedBy(group, (item) => item.id)[0];
+            const mergedConstraint = createConstraint({
+                ...representative,
+                id: hashId('constraint-value', { path, value: representative.value }),
+                status: group.some((item) => item.status === 'active') ? 'active' : 'satisfied',
+                importance: importanceFromValues(group.map((item) => item.importance), representative.importance),
+                sourceIds: sortedStrings(group.flatMap((item) => item.sourceIds)),
+                goalIds: sortedStrings(group.flatMap((item) => item.goalIds)),
+            });
+            merged.push(mergedConstraint);
+            mergedConstraints.push(mergedConstraint);
+            for (const item of group)
+                remap.set(item.id, mergedConstraint.id);
+        }
+        for (const goal of goals)
+            goal.constraintIds = sortedStrings(goal.constraintIds.map((id) => remap.get(id) ?? id));
+        const strongGroups = merged.filter((item) => item.importance === 'hard' || item.importance === 'required');
+        const ruleId = `rule.cardinality.${path}`;
+        if (merged.length > 1) {
+            const blocking = strongGroups.length !== 1;
+            const conflict = createConstraintConflict({
+                schemaVersion: CONSTRAINT_CONFLICT_SCHEMA_VERSION,
+                id: hashId('constraint-conflict', { code: 'CARDINALITY_CONFLICT', path, constraintIds: merged.map((item) => item.id) }),
+                code: 'CARDINALITY_CONFLICT',
+                severity: importanceFromValues(merged.map((item) => item.importance), 'preferred'),
+                targetPath: path,
+                constraintIds: merged.map((item) => item.id),
+                dependencyIds: [], resourceClaimIds: [],
+                message: `Cardinality one path ${path} received incompatible values.`,
+                blocking,
+                waiverAllowed: !blocking,
+            });
+            conflicts.push(conflict);
+            if (!blocking && strongGroups.length === 1) {
+                for (const loser of merged.filter((item) => item.importance === 'preferred')) {
+                    markUnsatisfied(loser, ruleId, 'CARDINALITY_PREFERENCE_DEGRADED');
+                    if (degraded.has(loser.id))
+                        continue;
+                    degraded.add(loser.id);
+                    const degradation = createDegradation({
+                        schemaVersion: DEGRADATION_SCHEMA_VERSION,
+                        id: hashId('degradation', { conflictId: conflict.id, constraintId: loser.id }),
+                        preferenceId: loser.id,
+                        constraintId: loser.id,
+                        reasonCode: 'CARDINALITY_PREFERENCE_DEGRADED',
+                        impact: conflict.message,
+                        affectedIds: [loser.id, strongGroups[0].id],
+                        explanation: `Preferred value for ${path} was excluded in favor of the stronger constraint.`,
+                    });
+                    degradations.push(degradation);
+                    traces.push(createRuleTrace({ schemaVersion: RULE_TRACE_SCHEMA_VERSION, id: hashId('rule-trace', { ruleId, constraintId: loser.id }), ruleId, inputIds: [loser.id, strongGroups[0].id], outputIds: [degradation.id], outcome: 'degraded', reasonCode: degradation.reasonCode, message: degradation.explanation }));
+                }
+            }
+            else {
+                traces.push(createRuleTrace({ schemaVersion: RULE_TRACE_SCHEMA_VERSION, id: hashId('rule-trace', { ruleId, constraintIds: merged.map((item) => item.id) }), ruleId, inputIds: merged.map((item) => item.id), outputIds: [conflict.id], outcome: 'blocked', reasonCode: 'CARDINALITY_CONFLICT', message: conflict.message }));
+            }
+        }
+    }
+    for (const goal of goals)
+        goal.constraintIds = sortedStrings(goal.constraintIds.map((id) => remap.get(id) ?? id));
+    return { constraints: sortedBy([...constraints.filter((item) => !cardinalityConstraintIds.has(item.id)), ...mergedConstraints], (item) => item.id), remap, conflicts, degradations, traces };
+}
+function operandMatches(operand, items) {
+    const matches = operand.conditions.map((condition) => conditionMatches(condition, items));
+    if (operand.match === 'any') {
+        const matched = matches.filter((value) => value.matched);
+        return matched.length > 0 ? uniqueSortedObjects(matched.flatMap((value) => value.items), (item) => item.id) : undefined;
+    }
+    if (matches.some((value) => !value.matched))
+        return undefined;
+    return uniqueSortedObjects(matches.flatMap((value) => value.items), (item) => item.id);
+}
 function ruleMatches(rule, items) {
-    const left = items.filter((item) => pathPresent([item.path], rule.leftPaths) && (rule.leftTokens.length === 0 || valueHasToken(item.value, rule.leftTokens)));
-    const right = items.filter((item) => pathPresent([item.path], rule.rightPaths) && (rule.rightTokens.length === 0 || valueHasToken(item.value, rule.rightTokens)));
-    if (left.length === 0 || right.length === 0)
+    const operands = new Map();
+    const missingOperandIds = [];
+    for (const operand of rule.operands) {
+        const match = operandMatches(operand, items);
+        if (match === undefined)
+            missingOperandIds.push(operand.id);
+        else
+            operands.set(operand.id, match);
+    }
+    if (missingOperandIds.length === 0)
+        return { operands, missingOperandIds };
+    if (rule.kind !== 'dependency')
+        return undefined;
+    const trigger = rule.operands[0];
+    const triggerMatch = operands.get(trigger.id);
+    if (triggerMatch === undefined || triggerMatch.length === 0)
         return undefined;
-    return { left, right };
+    return { operands, missingOperandIds };
 }
 function goalForIntent(intent) {
     const base = {
@@ -608,20 +826,20 @@ function outputConstraints(contract) {
 function makeRuleTrace(rule, inputIds, outputIds, outcome, reasonCode = rule.reasonCode, message = rule.message) {
     return createRuleTrace({ schemaVersion: RULE_TRACE_SCHEMA_VERSION, id: hashId('rule-trace', { ruleId: rule.id, inputIds, outputIds, outcome, reasonCode }), ruleId: rule.id, ...(rule.contributionId ? { contributionId: rule.contributionId } : {}), inputIds, outputIds, outcome, reasonCode, message });
 }
-function conflictForRule(rule, left, right) {
-    const constraintIds = sortedStrings([...left, ...right].map((item) => item.id));
-    const severity = importanceFromValues([...left, ...right].map((item) => item.importance), rule.importance);
+function conflictForRule(rule, constraints, blocking = true) {
+    const constraintIds = sortedStrings(constraints.map((item) => item.id));
+    const severity = importanceFromValues(constraints.map((item) => item.importance), rule.importance);
     return createConstraintConflict({
         schemaVersion: CONSTRAINT_CONFLICT_SCHEMA_VERSION,
         id: hashId('constraint-conflict', { code: rule.code, ruleId: rule.id, constraintIds }),
         code: rule.code,
         severity,
-        targetPath: [...left, ...right].map((item) => item.targetPath).find((item) => typeof item === 'string'),
+        targetPath: constraints.map((item) => item.targetPath).find((item) => typeof item === 'string'),
         constraintIds,
         dependencyIds: [],
         resourceClaimIds: rule.resourceId ? [hashId('resource', { resourceId: rule.resourceId, constraintIds })] : [],
         message: rule.message,
-        blocking: severity !== 'preferred',
+        blocking,
         waiverAllowed: severity === 'required',
     });
 }
@@ -822,6 +1040,16 @@ export class ConstraintGraphCompiler {
         allRules(input.effectiveScenario, ruleCollisionIds);
         if (ruleCollisionIds.length)
             return blockedConstraintIR(input, ['DECLARATIVE_RULE_ID_COLLISION']);
+        const vocabularyCollisionPaths = [];
+        const vocabulary = compositionVocabulary(input.effectiveScenario, vocabularyCollisionPaths);
+        if (vocabularyCollisionPaths.length)
+            return blockedConstraintIR(input, ['ONTOLOGY_PATH_DEFINITION_COLLISION']);
+        const invalidOntologyValues = semanticItems(input).filter((item) => {
+            const definition = vocabulary.get(item.path);
+            return definition !== undefined && !ontologyValueMatches(definition, item.value);
+        });
+        if (invalidOntologyValues.length)
+            return blockedConstraintIR(input, ['ONTOLOGY_VALUE_INVALID']);
         const goals = [];
         const constraints = [];
         const dependencies = [];
@@ -881,32 +1109,89 @@ export class ConstraintGraphCompiler {
         const output = outputConstraints(input.outputContract);
         constraints.push(...output);
         traces.push(createRuleTrace({ schemaVersion: RULE_TRACE_SCHEMA_VERSION, id: hashId('rule-trace', { kind: 'output', id: output[0].id }), ruleId: 'rule.output-contract', inputIds: [], outputIds: output.map((item) => item.id), outcome: 'applied', reasonCode: 'OUTPUT_CONTRACT_REQUIRED', message: 'OutputContract was compiled into provider-neutral output constraints.' }));
+        const cardinality = applyCardinalityResolution(constraints, goals, vocabulary);
+        constraints.splice(0, constraints.length, ...cardinality.constraints);
+        conflicts.push(...cardinality.conflicts);
+        degradations.push(...cardinality.degradations);
+        traces.push(...cardinality.traces);
+        for (const goal of goals)
+            goal.goalHash = computeGoalHash(goal);
+        constraintByPath.clear();
+        for (const constraint of constraints)
+            if (constraint.targetPath)
+                constraintByPath.set(constraint.targetPath, [...(constraintByPath.get(constraint.targetPath) ?? []), constraint]);
         const ruleItems = items;
+        const degradedConstraintIds = new Set(degradations.map((item) => item.constraintId).filter((item) => typeof item === 'string'));
+        const markUnsatisfied = (constraint, rule, reasonCode) => {
+            constraint.status = 'unsatisfied';
+            constraint.ruleId = rule.id;
+            constraint.reasonCode = reasonCode;
+            constraint.constraintHash = computeConstraintHash(constraint);
+        };
+        const degrade = (constraint, rule, conflict, affectedIds) => {
+            const target = constraints.find((item) => item.id === constraint.id);
+            if (!target || target.importance !== 'preferred' || degradedConstraintIds.has(target.id))
+                return undefined;
+            markUnsatisfied(target, rule, rule.resolution.reasonCode);
+            degradedConstraintIds.add(target.id);
+            const degradation = createDegradation({ schemaVersion: DEGRADATION_SCHEMA_VERSION, id: hashId('degradation', { conflictId: conflict.id, constraintId: target.id }), preferenceId: target.id, constraintId: target.id, reasonCode: rule.resolution.reasonCode, impact: conflict.message, affectedIds: sortedStrings([target.id, ...affectedIds]), explanation: `Preferred constraint ${target.id} was excluded because ${conflict.message}` });
+            degradations.push(degradation);
+            return degradation;
+        };
         for (const rule of allRules(input.effectiveScenario)) {
             const match = ruleMatches(rule, ruleItems);
             if (!match) {
                 traces.push(makeRuleTrace(rule, [], [], 'skipped', 'RULE_PRECONDITION_NOT_MET', 'Declarative rule preconditions were not met.'));
                 continue;
             }
-            const leftConstraints = match.left.flatMap((item) => constraintByPath.get(item.path) ?? []);
-            const rightConstraints = match.right.flatMap((item) => constraintByPath.get(item.path) ?? []);
+            const matchedItems = [...match.operands.values()].flat();
+            const matchedConstraints = uniqueSortedObjects(matchedItems.flatMap((item) => constraintByPath.get(item.path) ?? []), (item) => item.id);
+            const inputIds = sortedStrings(matchedItems.map((item) => item.id));
             if (rule.kind === 'dependency') {
-                const parent = leftConstraints[0];
-                const child = rightConstraints[0];
-                if (parent && child) {
-                    const dependency = createConstraintDependency({ schemaVersion: CONSTRAINT_DEPENDENCY_SCHEMA_VERSION, id: hashId('constraint-dependency', { ruleId: rule.id, parent: parent.id, child: child.id }), parentId: parent.id, childId: child.id, kind: rule.dependencyKind ?? 'requires', importance: rule.importance, explanation: rule.message });
-                    dependencies.push(dependency);
-                    traces.push(makeRuleTrace(rule, [...match.left, ...match.right].map((item) => item.id), [dependency.id], 'applied', rule.reasonCode));
+                const parentItems = match.operands.get(rule.operands[0].id) ?? [];
+                const parentConstraints = uniqueSortedObjects(parentItems.flatMap((item) => constraintByPath.get(item.path) ?? []), (item) => item.id);
+                if (match.missingOperandIds.length > 0) {
+                    const dependencyConflict = createConstraintConflict({ schemaVersion: CONSTRAINT_CONFLICT_SCHEMA_VERSION, id: hashId('constraint-conflict', { code: 'CONSTRAINT_DEPENDENCY_MISSING', ruleId: rule.id, constraintIds: parentConstraints.map((item) => item.id), missingOperandIds: match.missingOperandIds }), code: 'CONSTRAINT_DEPENDENCY_MISSING', severity: importanceFromValues(parentConstraints.map((item) => item.importance), rule.importance), targetPath: parentConstraints[0]?.targetPath, constraintIds: parentConstraints.map((item) => item.id), dependencyIds: [], resourceClaimIds: [], message: `${rule.message} Required dependency operand(s) missing: ${match.missingOperandIds.join(', ')}.`, blocking: !(rule.resolution.strategy === 'degrade_operand' && parentConstraints.every((item) => item.importance === 'preferred')), waiverAllowed: rule.importance === 'required' });
+                    conflicts.push(dependencyConflict);
+                    const dependencyDegradations = rule.resolution.strategy === 'degrade_operand' ? parentConstraints.map((constraint) => degrade(constraint, rule, dependencyConflict, parentConstraints.map((item) => item.id))).filter((item) => item !== undefined).map((item) => item.id) : [];
+                    traces.push(makeRuleTrace(rule, inputIds, [dependencyConflict.id, ...dependencyDegradations], dependencyConflict.blocking ? 'blocked' : 'degraded', 'CONSTRAINT_DEPENDENCY_MISSING', dependencyConflict.message));
+                }
+                else {
+                    const dependencyIds = [];
+                    for (const operand of rule.operands.slice(1)) {
+                        const childItems = match.operands.get(operand.id) ?? [];
+                        const child = uniqueSortedObjects(childItems.flatMap((item) => constraintByPath.get(item.path) ?? []), (item) => item.id)[0];
+                        const parent = parentConstraints[0];
+                        if (!parent || !child)
+                            continue;
+                        const dependency = createConstraintDependency({ schemaVersion: CONSTRAINT_DEPENDENCY_SCHEMA_VERSION, id: hashId('constraint-dependency', { ruleId: rule.id, parent: parent.id, child: child.id }), parentId: parent.id, childId: child.id, kind: rule.dependencyKind ?? 'requires', importance: rule.importance, explanation: rule.message });
+                        dependencies.push(dependency);
+                        dependencyIds.push(dependency.id);
+                    }
+                    traces.push(makeRuleTrace(rule, inputIds, dependencyIds, 'applied', rule.reasonCode));
                 }
                 continue;
             }
-            const conflict = conflictForRule(rule, leftConstraints, rightConstraints);
+            if (matchedConstraints.length < 2) {
+                traces.push(makeRuleTrace(rule, inputIds, [], 'skipped', 'RULE_SINGLE_OPERAND_MATCH', 'A declarative rule matched fewer than two constraint operands.'));
+                continue;
+            }
+            const strong = matchedConstraints.filter((constraint) => constraint.importance === 'hard' || constraint.importance === 'required');
+            let degradable = matchedConstraints.filter((constraint) => constraint.importance === 'preferred');
+            if (strong.length === 0 && rule.resolution.strategy === 'degrade_operand' && rule.resolution.operandId) {
+                const targetedItems = match.operands.get(rule.resolution.operandId) ?? [];
+                const targetedIds = new Set(targetedItems.map((item) => item.id));
+                degradable = matchedConstraints.filter((constraint) => constraint.importance === 'preferred' && constraint.sourceIds.some((sourceId) => targetedIds.has(sourceId)) || constraint.importance === 'preferred' && targetedItems.some((item) => item.path === constraint.targetPath));
+            }
+            const autoDegrade = strong.length === 1 ? matchedConstraints.filter((constraint) => constraint.importance === 'preferred') : strong.length === 0 && degradable.length > 0 && degradable.length < matchedConstraints.length ? degradable : [];
+            const conflict = conflictForRule(rule, matchedConstraints, autoDegrade.length === 0);
             conflicts.push(conflict);
+            const degradationIds = autoDegrade.map((constraint) => degrade(constraint, rule, conflict, strong.map((item) => item.id))).filter((item) => item !== undefined).map((item) => item.id);
             if (rule.resourceId) {
-                const claim = createResourceClaim({ schemaVersion: RESOURCE_CLAIM_SCHEMA_VERSION, id: conflict.resourceClaimIds[0] ?? hashId('resource', { resourceId: rule.resourceId, constraintIds: conflict.constraintIds }), resourceId: rule.resourceId, mode: 'exclusive', claimantIds: [...match.left, ...match.right].map((item) => item.id), constraintIds: conflict.constraintIds, quantity: 1, explanation: rule.message });
+                const claim = createResourceClaim({ schemaVersion: RESOURCE_CLAIM_SCHEMA_VERSION, id: conflict.resourceClaimIds[0] ?? hashId('resource', { resourceId: rule.resourceId, constraintIds: conflict.constraintIds }), resourceId: rule.resourceId, mode: 'exclusive', claimantIds: inputIds, constraintIds: conflict.constraintIds, quantity: 1, explanation: rule.message });
                 resourceClaims.push(claim);
             }
-            traces.push(makeRuleTrace(rule, [...match.left, ...match.right].map((item) => item.id), conflict.constraintIds, conflict.blocking ? 'blocked' : 'degraded', conflict.code));
+            traces.push(makeRuleTrace(rule, inputIds, [conflict.id, ...degradationIds], conflict.blocking ? 'blocked' : 'degraded', conflict.code));
         }
         const allConstraintIds = new Set(constraints.map((constraint) => constraint.id));
         for (const dependency of dependencies) {
@@ -936,12 +1221,6 @@ export class ConstraintGraphCompiler {
                 adjustedConflicts.push(rehashConflict({ ...conflict, blocking: false, message: `${conflict.message} Proceeding only under an explicit scoped waiver.` }));
                 warnings.push('REQUIRED_CONFLICT_WAIVED');
             }
-            else if (conflict.severity === 'preferred') {
-                adjustedConflicts.push(rehashConflict({ ...conflict, blocking: false }));
-                const degradation = createDegradation({ schemaVersion: DEGRADATION_SCHEMA_VERSION, id: hashId('degradation', { conflictId: conflict.id }), preferenceId: conflict.id, constraintId: conflict.constraintIds[0], reasonCode: conflict.code, impact: conflict.message, affectedIds: conflict.constraintIds, explanation: `Preferred constraint was degraded deterministically because ${conflict.message}` });
-                degradations.push(degradation);
-                traces.push(createRuleTrace({ schemaVersion: RULE_TRACE_SCHEMA_VERSION, id: hashId('rule-trace', { degradation: degradation.id }), ruleId: 'rule.preferred-degradation', inputIds: conflict.constraintIds, outputIds: [degradation.id], outcome: 'degraded', reasonCode: conflict.code, message: degradation.explanation }));
-            }
             else
                 adjustedConflicts.push(conflict);
         }

package/dist/m5.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactHandle, ArtifactReplayResult, CompilationContext, CompensationReceipt, ConstraintIR, CleanupReceipt, Evaluation, ExecutionAuthorization, ExecutionRun, ExecutionTraceProjection, HumanAcceptance, JsonObject, PipelinePlan, PipelineStep, PromptCandidateIR, PromptCompilationInput, PromptGuardInput, PromptGuardResult, PromptIR, PromptOptimizationInput, PromptOptimizer, PromptTransformation, ProviderAdapter, ProviderRenderRequest, ProviderRenderResult, ReferencePlan, RemoteCallRun, RemoteCallAuthorization, StepReceipt, VersionPin } from '@voce-engine/contracts';
+import type { ArtifactHandle, ArtifactReplayResult, CompilationContext, CompensationReceipt, ConstraintIR, CleanupReceipt, Evaluation, ExecutionAuthorization, ExecutionRun, ExecutionRunState, ExecutionTraceProjection, HumanAcceptance, JsonObject, PipelinePlan, PipelineStep, PromptCandidateIR, PromptCompilationInput, PromptGuardInput, PromptGuardResult, PromptIR, PromptOptimizationInput, PromptOptimizer, PromptTransformation, ProviderAdapter, ProviderRenderRequest, ProviderRenderResult, ReferencePlan, RemoteCallRun, RemoteCallAuthorization, StepReceipt, VersionPin } from '@voce-engine/contracts';
 export declare const PROMPT_COMPILER_VERSION = "voce.prompt-compiler/v1alpha1";
 export declare const PROMPT_OPTIMIZER_VERSION = "voce.deterministic-prompt-optimizer/v1alpha1";
 export declare const PROMPT_GUARD_VERSION = "voce.prompt-guard/v1alpha1";
@@ -75,7 +75,7 @@ export interface OfflineExecutionInput {
     options?: OfflineExecutionOptions;
 }
 export interface OfflineExecutionResult {
-    status: 'blocked' | 'completed' | 'failed' | 'submission_unknown' | 'cancelled' | 'needs_review';
+    status: 'blocked' | ExecutionRunState;
     code: string;
     reasons: string[];
     executionRun?: ExecutionRun;

package/dist/m5.js

@@ -152,6 +152,7 @@ function normalizedPromptIRProjection(prompt) {
         forbidden: sortedBy(prompt.forbidden, (item) => item.id),
         output: clone(prompt.output),
         constraintCoverage: sortedBy(prompt.constraintCoverage, (item) => item.constraintId).map(promptCoverageProjection),
+        excludedConstraints: sortedBy(prompt.excludedConstraints, (item) => item.constraintId),
         sourceIds: sortedStrings(prompt.sourceIds),
         constraintIds: sortedStrings(prompt.constraintIds),
         decisionIds: sortedStrings(prompt.decisionIds),
@@ -230,6 +231,7 @@ function normalizedPromptCandidateProjection(candidate) {
         parameters: sortedBy(parameters, (item) => item.id).map(promptParameterProjection),
         referenceMappings: [...candidate.referenceMappings].sort((left, right) => left.order - right.order || compareCodeUnits(left.id, right.id)).map(promptReferenceMappingProjection),
         constraintCoverage: sortedBy(coverage, (item) => item.constraintId).map(promptCoverageProjection),
+        excludedConstraints: sortedBy(candidate.excludedConstraints, (item) => item.constraintId),
         transformations: candidate.transformations.map(transformationProjection),
         optimizer: clone(candidate.optimizer),
         mode: candidate.mode,
@@ -337,6 +339,24 @@ function integrityReasonsForConstraintIR(ir, context, caseId, caseRevision) {
     for (const item of ir.degradedPreferences)
         if (!isHash(item.degradationHash) || computeDegradationHash(item) !== item.degradationHash)
             reasons.push('DEGRADATION_HASH_MISMATCH');
+    const degradationCounts = new Map();
+    for (const degradation of ir.degradedPreferences) {
+        if (!degradation.constraintId) {
+            reasons.push('DEGRADATION_CONSTRAINT_MISSING');
+            continue;
+        }
+        degradationCounts.set(degradation.constraintId, (degradationCounts.get(degradation.constraintId) ?? 0) + 1);
+        const constraint = ir.constraints.find((item) => item.id === degradation.constraintId);
+        if (!constraint || constraint.importance !== 'preferred' || constraint.status !== 'unsatisfied')
+            reasons.push('DEGRADATION_DISPOSITION_INVALID');
+    }
+    for (const constraint of ir.constraints) {
+        const count = degradationCounts.get(constraint.id) ?? 0;
+        if (constraint.status === 'unsatisfied' && count !== 1)
+            reasons.push('UNSATISFIED_CONSTRAINT_DEGRADATION_MISMATCH');
+        if (constraint.status !== 'unsatisfied' && count > 0)
+            reasons.push('DEGRADATION_DISPOSITION_INVALID');
+    }
     for (const item of ir.reviewRequirements)
         if (!isHash(item.reviewHash) || computeReviewRequirementHash(item) !== item.reviewHash)
             reasons.push('REVIEW_REQUIREMENT_HASH_MISMATCH');
@@ -420,22 +440,57 @@ function promptCompilationInputReasons(input) {
         reasons.push('TARGET_ADAPTER_INVALID');
     if (!input.targetCapabilityProfile || !isHash(input.targetCapabilityProfile.digest))
         reasons.push('TARGET_PROFILE_INVALID');
+    if (!input.effectiveScenario || !isHash(input.context?.effectiveScenarioHash ?? '') || input.effectiveScenario?.effectiveScenarioHash !== input.context?.effectiveScenarioHash)
+        reasons.push('EFFECTIVE_SCENARIO_CONTEXT_MISMATCH');
+    if (input.effectiveScenario) {
+        const scenarioProjection = clone(input.effectiveScenario);
+        delete scenarioProjection.effectiveScenarioHash;
+        if (!isHash(input.effectiveScenario.effectiveScenarioHash) || sha256(jsonReady(scenarioProjection)) !== input.effectiveScenario.effectiveScenarioHash)
+            reasons.push('EFFECTIVE_SCENARIO_HASH_MISMATCH');
+        const definitions = input.effectiveScenario.promptSections.flatMap((contribution) => contribution.sections ?? []);
+        const definitionIds = new Set();
+        for (const definition of definitions) {
+            if (definitionIds.has(definition.id) || !Number.isInteger(definition.order) || !Array.isArray(definition.pathPrefixes) || definition.pathPrefixes.length === 0 || typeof definition.templateKey !== 'string')
+                reasons.push('PROMPT_SECTION_POLICY_INVALID');
+            definitionIds.add(definition.id);
+        }
+    }
     if (input.pipelinePlan && input.pipelinePlan.profileDigest !== input.targetCapabilityProfile?.digest)
         reasons.push('TARGET_PROFILE_PLAN_MISMATCH');
     if (input.pipelinePlan && !input.pipelinePlan.adapterDigests.includes(input.targetAdapter?.digest ?? ''))
         reasons.push('TARGET_ADAPTER_PLAN_MISMATCH');
     return sortedStrings(reasons);
 }
-function sectionForConstraint(constraint, order, decisionIds) {
+function pathRelates(left, right) {
+    return left === right || left.startsWith(`${right}.`) || right.startsWith(`${left}.`);
+}
+function promptSectionDefinitions(scenario) {
+    const definitions = scenario.promptSections.flatMap((contribution) => contribution.sections ?? []).map((definition) => clone(definition));
+    return definitions.sort((left, right) => left.order - right.order || compareCodeUnits(left.id, right.id));
+}
+function sectionDefinitionForConstraint(constraint, definitions) {
+    const paths = constraint.targetPaths.length ? constraint.targetPaths : constraint.targetPath ? [constraint.targetPath] : [];
+    return definitions.find((definition) => definition.pathPrefixes.some((prefix) => paths.some((path) => pathRelates(path, prefix))));
+}
+function promptExclusions(constraintIR) {
+    return sortedBy(constraintIR.constraints.filter((constraint) => constraint.status === 'unsatisfied').map((constraint) => {
+        const degradations = constraintIR.degradedPreferences.filter((item) => item.constraintId === constraint.id);
+        if (degradations.length !== 1)
+            throw new Error('UNSATISFIED_CONSTRAINT_DEGRADATION_MISMATCH');
+        return { constraintId: constraint.id, degradationId: degradations[0].id, reasonCode: degradations[0].reasonCode, sourceIds: sortedStrings(constraint.sourceIds) };
+    }), (item) => item.constraintId);
+}
+function sectionForConstraint(constraint, order, decisionIds, definition) {
     const locked = constraint.importance === 'hard' || constraint.importance === 'required' || constraint.kind === 'output';
+    const content = `${definition?.templateKey ? `${definition.templateKey}: ` : ''}${constraintText(constraint)}`;
     return {
         schemaVersion: PROMPT_SECTION_SCHEMA_VERSION,
-        id: hashId('prompt-section', { kind: constraint.importance, constraintId: constraint.id, order }),
+        id: hashId('prompt-section', { kind: constraint.importance, constraintId: constraint.id, order, definitionId: definition?.id }),
         kind: constraint.importance === 'hard' ? 'hard_constraint' : constraint.importance === 'required' ? 'required_constraint' : 'preferred',
         priority: constraint.importance === 'hard' ? 100 : constraint.importance === 'required' ? 80 : 40,
         order,
-        content: constraintText(constraint),
-        text: constraintText(constraint),
+        content,
+        text: content,
         constraintIds: [constraint.id],
         sourceIds: sortedStrings(constraint.sourceIds),
         decisionIds: sortedStrings(decisionIds),
@@ -446,7 +501,8 @@ function sectionForConstraint(constraint, order, decisionIds) {
     };
 }
 function referenceMapping(reference, constraints, decisionIds) {
-    const required = reference.constraintIds.some((id) => constraints.find((constraint) => constraint.id === id)?.importance !== 'preferred') || reference.sourceBindingIds.length > 0;
+    const effectiveConstraintIds = sortedStrings(reference.constraintIds.filter((id) => constraints.some((constraint) => constraint.id === id)));
+    const required = effectiveConstraintIds.some((id) => constraints.find((constraint) => constraint.id === id)?.importance !== 'preferred') || reference.sourceBindingIds.length > 0;
     return {
         schemaVersion: PROMPT_REFERENCE_MAPPING_SCHEMA_VERSION,
         id: hashId('prompt-reference-mapping', { plannedReferenceId: reference.id, assetId: reference.assetId, contentHash: reference.contentHash, order: reference.order }),
@@ -458,7 +514,7 @@ function referenceMapping(reference, constraints, decisionIds) {
         role: reference.role,
         order: reference.order,
         required,
-        constraintIds: sortedStrings(reference.constraintIds),
+        constraintIds: effectiveConstraintIds,
         sourceBindingIds: sortedStrings(reference.sourceBindingIds),
         decisionIds: sortedStrings(decisionIds),
     };
@@ -505,7 +561,9 @@ export class PromptCompiler {
             if (reasons.length)
                 throw new Error(reasons.join('|'));
             const decisionIds = sortedStrings(safeInput.context.decisionHashes);
-            const constraints = sortedBy(safeInput.constraintIR.constraints, (item) => item.id);
+            const excludedConstraints = promptExclusions(safeInput.constraintIR);
+            const constraints = sortedBy(safeInput.constraintIR.constraints.filter((constraint) => constraint.status === 'active' || constraint.status === 'satisfied'), (item) => item.id);
+            const definitions = promptSectionDefinitions(safeInput.effectiveScenario);
             const sections = [];
             const objective = safeInput.objective ?? 'Produce the requested visual result using only the approved constraints and references.';
             const positiveDescription = safeInput.positiveDescription ?? 'Express the approved target properties clearly and preserve all locked requirements.';
@@ -521,7 +579,11 @@ export class PromptCompiler {
                 kind: 'positive', priority: 110, order: 1, content: positiveDescription, text: positiveDescription,
                 constraintIds: [], sourceIds: [], decisionIds, assetIds: [], importance: 'required', mutability: 'rephraseable', locked: false,
             });
-            constraints.forEach((constraint, index) => sections.push(sectionForConstraint(constraint, 10 + index, decisionIds)));
+            constraints.forEach((constraint, index) => {
+                const definition = sectionDefinitionForConstraint(constraint, definitions);
+                const policyOrder = definition?.order ?? 500;
+                sections.push(sectionForConstraint(constraint, 10 + policyOrder * 10 + index, decisionIds, definition));
+            });
             const mappings = [...safeInput.referencePlan.ordered].sort((left, right) => left.order - right.order || compareCodeUnits(left.id, right.id)).map((reference) => referenceMapping(reference, constraints, decisionIds));
             mappings.forEach((mapping, index) => sections.push({
                 schemaVersion: PROMPT_SECTION_SCHEMA_VERSION,
@@ -566,6 +628,7 @@ export class PromptCompiler {
                 forbidden: sortedBy(forbidden, (item) => item.id),
                 output: clone(safeInput.outputContract),
                 constraintCoverage: sortedBy(coverage, (item) => item.constraintId),
+                excludedConstraints,
                 sourceIds: sortedStrings([...constraints.flatMap((constraint) => constraint.sourceIds), ...mappings.flatMap((mapping) => mapping.sourceBindingIds)]),
                 constraintIds: sortedStrings(constraints.map((constraint) => constraint.id)),
                 decisionIds,
@@ -654,6 +717,7 @@ export function createPromptCandidateIR(prompt, transformations = [], options =
         parameters: clone(parameters),
         referenceMappings: clone(safePrompt.referenceMappings),
         constraintCoverage: clone(safePrompt.constraintCoverage),
+        excludedConstraints: clone(safePrompt.excludedConstraints),
         transformations: normalizedTransformations,
         optimizer: clone(options.optimizer ?? { id: PROMPT_OPTIMIZER_VERSION, version: '1.0.0', digest: sha256({ optimizer: PROMPT_OPTIMIZER_VERSION }) }),
         mode: options.mode ?? 'strict',
@@ -733,7 +797,7 @@ function guardFinding(value) {
 }
 function guardInputReasons(input) {
     const reasons = [];
-    if (!input || input.schemaVersion !== 'voce.prompt-guard-input/v1alpha1')
+    if (!input || input.schemaVersion !== 'voce.prompt-guard-input/v1alpha2')
         reasons.push('PROMPT_GUARD_INPUT_SCHEMA_INVALID');
     if (!input.promptIR || input.promptIR.schemaVersion !== PROMPT_IR_SCHEMA_VERSION || !isHash(input.promptIR.deterministicSignature) || computePromptIRHash(input.promptIR) !== input.promptIR.deterministicSignature)
         reasons.push('PROMPT_IR_SIGNATURE_MISMATCH');
@@ -751,6 +815,19 @@ function guardInputReasons(input) {
         reasons.push('PROMPT_CONTEXT_MISMATCH');
     if (input.constraintIR && integrityReasonsForConstraintIR(input.constraintIR, input.context, input.promptIR?.caseId ?? '', input.promptIR?.caseRevision ?? -1).length)
         reasons.push('CONSTRAINT_IR_INVALID');
+    if (input.promptIR && input.constraintIR) {
+        const excludedIds = new Set(input.promptIR.excludedConstraints.map((item) => item.constraintId));
+        if (excludedIds.size !== input.promptIR.excludedConstraints.length)
+            reasons.push('PROMPT_EXCLUSION_DUPLICATE');
+        for (const exclusion of input.promptIR.excludedConstraints) {
+            const constraint = input.constraintIR.constraints.find((item) => item.id === exclusion.constraintId);
+            const degradation = input.constraintIR.degradedPreferences.find((item) => item.id === exclusion.degradationId && item.constraintId === exclusion.constraintId);
+            if (!constraint || constraint.status !== 'unsatisfied' || !degradation || input.promptIR.constraintIds.includes(exclusion.constraintId))
+                reasons.push('PROMPT_EXCLUSION_INVALID');
+        }
+        if (input.constraintIR.constraints.some((constraint) => constraint.status === 'unsatisfied' && !excludedIds.has(constraint.id)))
+            reasons.push('PROMPT_EXCLUSION_MISSING');
+    }
     if (input.referencePlan && input.constraintIR && integrityReasonsForReferencePlan(input.referencePlan, input.constraintIR, input.promptIR?.caseId ?? '', input.promptIR?.caseRevision ?? -1, input.context?.contextHash ?? '').length)
         reasons.push('REFERENCE_PLAN_INVALID');
     if (input.pipelinePlan && input.constraintIR && input.referencePlan && integrityReasonsForPipelinePlan(input.pipelinePlan, input.constraintIR, input.referencePlan, input.outputContract, input.promptIR?.caseId ?? '', input.promptIR?.caseRevision ?? -1, input.context?.contextHash ?? '').length)
@@ -806,6 +883,24 @@ export class PromptGuard {
         const candidateMappings = candidate.referenceMappings;
         const baseCoverage = new Map(prompt.constraintCoverage.map((coverage) => [coverage.constraintId, coverage]));
         const candidateCoverageMap = new Map(candidateCoverage(candidate).map((coverage) => [coverage.constraintId, coverage]));
+        const excludedIds = new Set(prompt.excludedConstraints.map((item) => item.constraintId));
+        if (canonicalize(sortedBy(candidate.excludedConstraints, (item) => item.constraintId)) !== canonicalize(sortedBy(prompt.excludedConstraints, (item) => item.constraintId)))
+            addGuardFinding(findings, { code: 'PROMPT_EXCLUSION_SET_CHANGED', severity: 'critical', blocking: true, constraintIds: [...excludedIds], sourceIds: [], sectionIds: [], decisionIds: [], assetIds: [], explanation: 'Candidate changed the explicit Prompt IR exclusion set.' });
+        const reportExcludedLinks = (ids, sectionIds = []) => {
+            const linked = ids.filter((id) => excludedIds.has(id));
+            if (linked.length)
+                addGuardFinding(findings, { code: 'EXCLUDED_CONSTRAINT_REINTRODUCED', severity: 'critical', blocking: true, constraintIds: sortedStrings(linked), sourceIds: [], sectionIds, decisionIds: [], assetIds: [], explanation: 'Candidate re-linked an excluded constraint into prompt structure.' });
+        };
+        for (const section of candidateSectionList)
+            reportExcludedLinks(section.constraintIds, [section.id]);
+        for (const parameter of candidateParameterList)
+            reportExcludedLinks(parameter.constraintIds);
+        for (const mapping of candidateMappings)
+            reportExcludedLinks(mapping.constraintIds);
+        for (const coverage of candidateCoverage(candidate))
+            reportExcludedLinks([coverage.constraintId], coverage.sectionIds);
+        for (const transformation of candidate.transformations)
+            reportExcludedLinks('proof' in transformation ? transformation.proof?.preservedConstraintIds ?? [] : [], transformation.kind === 'rephrase' ? [transformation.sectionId] : []);
         for (const section of prompt.sections) {
             const candidateSection = candidateSectionMap.get(section.id);
             const locked = section.locked === true || section.mutability === 'locked' || section.kind === 'hard_constraint' || section.kind === 'required_constraint' || section.kind === 'output' || section.kind === 'reference';

package/dist/m6.d.ts

@@ -52,6 +52,7 @@ export declare class RecordingMockTransport implements ProviderTransport {
     enqueue(response: ProviderResponseEnvelope): void;
     enqueueLookup(response: ProviderResponseEnvelope): void;
     private consume;
+    private consumeResponse;
     send(request: ProviderRequestEnvelope, context: ProviderTransportContext): Promise<ProviderResponseEnvelope>;
     lookup(request: ProviderSubmissionLookup, context: ProviderTransportContext): Promise<ProviderResponseEnvelope>;
 }

package/dist/m6.js

@@ -436,6 +436,15 @@ export class RecordingMockTransport {
             throw new ProviderTransportError('REMOTE_CALL_BUDGET_EXHAUSTED', `Remote ${kind} budget has been exhausted.`);
         counts.set(key, count + 1);
     }
+    consumeResponse(queued, requestHash, missingCode, missingMessage) {
+        const exactIndex = queued.findIndex((item) => item.requestHash === requestHash);
+        if (exactIndex >= 0)
+            return queued.splice(exactIndex, 1)[0];
+        const wildcardIndex = queued.findIndex((item) => item.requestHash === '');
+        if (wildcardIndex >= 0)
+            return queued.splice(wildcardIndex, 1)[0];
+        return errorResponse(requestHash, missingCode, missingMessage);
+    }
     async send(request, context) {
         assertRemoteCallAuthorization(request, context);
         this.consume('send', context.authorization);
@@ -445,7 +454,7 @@ export class RecordingMockTransport {
             throw new ProviderTransportError('REMOTE_CALL_IDENTITY_REUSED', 'Idempotency identity cannot be reused for a different provider request.');
         this.sentRequests.set(identity, clone(request));
         this.calls.push({ requestId: request.id, requestHash: request.requestHash, adapterId: request.adapterId, profileDigest: request.profileDigest, destination: request.destination, ...(request.region === undefined ? {} : { region: request.region }), inputHash: request.inputHash, idempotencyKey: request.idempotencyKey });
-        const response = this.responses.shift() ?? errorResponse(request.requestHash, 'MOCK_RESPONSE_MISSING', 'Recording mock response was not registered.');
+        const response = this.consumeResponse(this.responses, request.requestHash, 'MOCK_RESPONSE_MISSING', 'Recording mock response was not registered.');
         const normalized = response.requestHash === request.requestHash ? response : { ...response, requestHash: request.requestHash, responseHash: '' };
         if (!normalized.responseHash)
             normalized.responseHash = computeProviderResponseEnvelopeHash(normalized);
@@ -459,7 +468,7 @@ export class RecordingMockTransport {
         if (!original || !providerBindingMatches(original, request))
             throw new ProviderTransportError('PROVIDER_LOOKUP_BINDING_MISMATCH', 'Submission lookup is not bound to a prior provider request.');
         this.lookupCalls.push({ requestId: request.providerRequestId ?? request.lookupHash, requestHash: request.requestHash, adapterId: request.adapterId, profileDigest: request.profileDigest, destination: request.destination, ...(request.region === undefined ? {} : { region: request.region }), inputHash: request.inputHash, idempotencyKey: request.idempotencyKey });
-        const response = this.lookups.shift() ?? errorResponse(request.requestHash, 'MOCK_LOOKUP_RESPONSE_MISSING', 'Recording lookup response was not registered.');
+        const response = this.consumeResponse(this.lookups, request.requestHash, 'MOCK_LOOKUP_RESPONSE_MISSING', 'Recording lookup response was not registered.');
         const normalized = response.requestHash === request.requestHash ? response : { ...response, requestHash: request.requestHash, responseHash: '' };
         if (!normalized.responseHash)
             normalized.responseHash = computeProviderResponseEnvelopeHash(normalized);
@@ -1053,11 +1062,14 @@ export function compileEvaluationReport(input) {
     const human = input.humanAcceptance ? normalizeHumanAcceptance(input.humanAcceptance, input.run.id) : undefined;
     if (human && (human.annotations.some((annotation) => humanAnnotationHash(annotation) !== annotation.annotationHash) || computeHumanAcceptanceDecisionHash(human) !== human.decisionHash))
         throw new ProviderTransportError('HUMAN_DECISION_HASH_MISMATCH', 'Human acceptance decision hash is invalid.');
+    if (human && human.runId !== input.run.id)
+        throw new ProviderTransportError('HUMAN_DECISION_RUN_MISMATCH', 'Human acceptance decision belongs to a different execution run.');
     const cleanup = cleanupStatus(input.cleanup ?? []);
     const replay = input.replay ?? { mode: 'none', status: 'not_requested', artifactIds: [] };
     const technicalStatus = input.run.technicalOutcome === 'succeeded' ? 'passed' : input.run.technicalOutcome === 'failed' ? 'failed' : input.run.technicalOutcome === 'pending' ? 'pending' : 'needs_review';
-    const status = input.run.technicalOutcome === 'failed' || input.structural?.status === 'failed' ? 'failed' : input.semanticProposal?.status === 'submission_unknown' || human?.status === 'pending' || human?.status === 'declined' || cleanup.status === 'failed' ? 'needs_review' : input.structural?.status === 'needs_review' ? 'partial' : 'complete';
-    const base = { schemaVersion: EVALUATION_REPORT_SCHEMA_VERSION, id: hashId('evaluation-report', { runId: input.run.id, structural: input.structural?.reportHash, semantic: input.semanticProposal?.reportHash, human: human?.decisionHash }), runId: input.run.id, technicalOutcome: input.run.technicalOutcome, technicalStatus, ...(input.structural === undefined ? {} : { structural: clone(input.structural) }), ...(input.semanticProposal === undefined ? {} : { semanticProposal: clone(input.semanticProposal) }), ...(human === undefined ? {} : { humanAcceptance: human }), cleanup, replay: clone(replay), artifactIds: sortedStrings((input.artifacts ?? []).map((item) => item.id)), sourceHashes: Object.fromEntries(Object.entries(input.sourceHashes ?? {}).sort((left, right) => compareCodeUnits(left[0], right[0]))), status, warnings: sortedStrings([...(input.run.state === 'needs_review' ? ['HUMAN_ACCEPTANCE_REQUIRED'] : []), ...(cleanup.failureCodes)]) };
+    const semanticNeedsReview = Boolean(input.semanticProposal?.findings.some((finding) => finding.status === 'fail' || finding.status === 'uncertain')) && human?.status !== 'accepted' && human?.status !== 'waived';
+    const status = input.run.technicalOutcome === 'failed' || input.structural?.status === 'failed' ? 'failed' : input.semanticProposal?.status === 'submission_unknown' || semanticNeedsReview || human?.status === 'pending' || human?.status === 'declined' || cleanup.status === 'failed' ? 'needs_review' : input.structural?.status === 'needs_review' ? 'partial' : 'complete';
+    const base = { schemaVersion: EVALUATION_REPORT_SCHEMA_VERSION, id: hashId('evaluation-report', { runId: input.run.id, structural: input.structural?.reportHash, semantic: input.semanticProposal?.reportHash, human: human?.decisionHash }), runId: input.run.id, technicalOutcome: input.run.technicalOutcome, technicalStatus, ...(input.structural === undefined ? {} : { structural: clone(input.structural) }), ...(input.semanticProposal === undefined ? {} : { semanticProposal: clone(input.semanticProposal) }), ...(human === undefined ? {} : { humanAcceptance: human }), cleanup, replay: clone(replay), artifactIds: sortedStrings((input.artifacts ?? []).map((item) => item.id)), sourceHashes: Object.fromEntries(Object.entries(input.sourceHashes ?? {}).sort((left, right) => compareCodeUnits(left[0], right[0]))), status, warnings: sortedStrings([...(input.run.state === 'needs_review' ? ['HUMAN_ACCEPTANCE_REQUIRED'] : []), ...(semanticNeedsReview ? ['SEMANTIC_FINDING_REQUIRES_REVIEW'] : []), ...(cleanup.failureCodes)]) };
     return clone({ ...base, reportHash: computeEvaluationReportHash(base) });
 }
 export const compileEvaluation = compileEvaluationReport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voce-engine/core",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.4",
   "description": "Deterministic visual ontology, constraint, reference, prompt, execution-planning, and evaluation runtime.",
   "license": "Apache-2.0",
   "type": "module",
@@ -21,6 +21,8 @@
     "dist/m5.d.ts",
     "dist/m6.js",
     "dist/m6.d.ts",
+    "dist/composition.js",
+    "dist/composition.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -41,7 +43,7 @@
     "tag": "next"
   },
   "dependencies": {
-    "@voce-engine/contracts": "0.1.0-rc.2",
+    "@voce-engine/contracts": "0.1.0-rc.4",
     "semver": "7.7.2"
   },
   "devDependencies": {