@aduek/ne-sy 0.1.0-alpha.0

package/dist/ir.js

@@ -0,0 +1,859 @@
+import { createHash } from "node:crypto";
+import { DECISION_RANK, errorCategoryForCode, } from "./types.js";
+import { BOUNDED_SIMULATION_CAPABILITIES, validateCapabilityList, validateRequiredCapabilities, } from "./capabilities.js";
+import { compactRecord, compareStrings, getDotted, isRecord, stableValue } from "./utils.js";
+export const POLICY_IR_HASH_ALGORITHM = "sha256";
+export const ANALYSIS_SEMANTIC_TRACE_VERSION = "analysis-semantics.v0";
+const POLICY_OPERATORS = new Set(["equals", "not_equals", "greater_than", "less_than", "in"]);
+export function normalizePolicyPack(policyInput) {
+    if (policyInput === undefined || policyInput === null) {
+        return {
+            kind: "PolicyPack",
+            id: null,
+            version: null,
+            defaultDecision: "review",
+            defaultReason: "No policies were configured for verification.",
+            policies: [],
+        };
+    }
+    if (!isRecord(policyInput)) {
+        return {
+            kind: "PolicyPack",
+            id: null,
+            version: null,
+            defaultDecision: "allow",
+            defaultReason: "No policy matched; action allowed by default.",
+            policies: [normalizePolicy(policyInput, 0)],
+        };
+    }
+    const policySource = "policies" in policyInput ? policyInput.policies : policyInput;
+    const policyItems = Array.isArray(policySource)
+        ? policySource
+        : isRecord(policySource)
+            ? [policySource]
+            : [];
+    const defaultDecision = String(policyInput.defaultDecision ?? "allow");
+    return {
+        kind: "PolicyPack",
+        id: policyInput.id === undefined ? null : String(policyInput.id),
+        version: policyInput.version === undefined ? null : String(policyInput.version),
+        defaultDecision,
+        defaultReason: String(policyInput.defaultReason ??
+            `No policy matched; default decision \`${defaultDecision}\` applied.`),
+        policies: policyItems.map((policy, index) => normalizePolicy(policy, index)),
+    };
+}
+export function analyzePolicyIr(policyIr) {
+    const findings = [];
+    const ids = new Map();
+    const signatures = new Map();
+    const fieldTypes = new Map();
+    for (const policy of policyIr.policies) {
+        ids.set(policy.id, (ids.get(policy.id) ?? 0) + 1);
+        if (!(policy.effect in DECISION_RANK)) {
+            findings.push({
+                severity: "error",
+                code: "unsupported_effect",
+                message: `Policy has unsupported effect: ${String(policy.effect)}`,
+                policyIds: [policy.id],
+                field: "effect",
+            });
+        }
+        findings.push(...conditionFindings(policy.condition, policy.id));
+        collectFieldTypes(policy.condition, fieldTypes);
+        findings.push(...contradictionFindings(policy.condition, policy.id));
+        const signature = conditionSignature(policy.condition);
+        signatures.set(signature, [...(signatures.get(signature) ?? []), policy]);
+    }
+    for (const [policyId, count] of ids.entries()) {
+        if (count > 1) {
+            findings.push({
+                severity: "error",
+                code: "duplicate_policy_id",
+                message: `Policy ID appears ${count} times.`,
+                policyIds: [policyId],
+                field: "id",
+            });
+        }
+    }
+    for (const policiesWithSignature of signatures.values()) {
+        if (policiesWithSignature.length < 2)
+            continue;
+        const effects = new Set(policiesWithSignature.map((policy) => policy.effect));
+        const policyIds = policiesWithSignature.map((policy) => policy.id);
+        if (effects.size > 1) {
+            findings.push({
+                severity: "warning",
+                code: "conflicting_identical_conditions",
+                message: "Policies share identical conditions but have different effects.",
+                policyIds,
+                field: "conditions",
+            });
+        }
+        const highestRank = Math.max(...[...effects].map(decisionRank));
+        const lowerPolicies = policiesWithSignature
+            .filter((policy) => decisionRank(policy.effect) < highestRank)
+            .map((policy) => policy.id);
+        if (lowerPolicies.length > 0) {
+            findings.push({
+                severity: "info",
+                code: "shadowed_policy",
+                message: "A lower-precedence policy shares conditions with a higher-precedence policy.",
+                policyIds: lowerPolicies,
+                field: "conditions",
+            });
+        }
+    }
+    for (const [field, types] of [...fieldTypes.entries()].sort(([left], [right]) => compareStrings(left, right))) {
+        const concreteTypes = [...types].filter((type) => type !== "unknown");
+        if (new Set(concreteTypes).size > 1) {
+            findings.push({
+                severity: "warning",
+                code: "inconsistent_field_type",
+                message: `Field \`${field}\` is compared against inconsistent value types.`,
+                policyIds: [],
+                field,
+            });
+        }
+    }
+    return findings.map(categorizeFinding);
+}
+export function canonicalPolicyIrJson(policyIr) {
+    return JSON.stringify(stableValue(policyIr));
+}
+export function hashPolicyIr(policyIr) {
+    return createHash(POLICY_IR_HASH_ALGORITHM)
+        .update(canonicalPolicyIrJson(policyIr), "utf8")
+        .digest("hex");
+}
+export function conditionSignature(conditionIr) {
+    return JSON.stringify(signatureValue(conditionIr));
+}
+export function checkPolicyProperty(policyIr, propertySpec) {
+    if (propertySpec.type !== "no_allowing_policy_for_condition") {
+        return {
+            result: "unknown",
+            reason: `Unsupported non-solver property type: ${String(propertySpec.type)}`,
+            policyIds: [],
+        };
+    }
+    const targetSignature = conditionSignature(normalizeCondition(propertySpec.condition));
+    const matchedPolicyIds = policyIr.policies
+        .filter((policy) => ["allow", "log"].includes(policy.effect))
+        .filter((policy) => conditionSignature(policy.condition) === targetSignature)
+        .map((policy) => policy.id);
+    if (matchedPolicyIds.length > 0) {
+        return {
+            result: "fail",
+            reason: "One or more allow/log policies have the forbidden condition signature.",
+            policyIds: matchedPolicyIds,
+        };
+    }
+    return {
+        result: "unknown",
+        reason: "No exact allow/log condition match was found; implication checks require a solver.",
+        policyIds: [],
+    };
+}
+export function simulatePolicyIr(policyIr, simulationSpec) {
+    const propertySpec = simulationSpec.property;
+    if (!isRecord(propertySpec)) {
+        return simulationUnknown("Simulation property must be an object.", { errorCode: "simulation_invalid_property" });
+    }
+    const capabilityValidation = validateSimulationCapabilities(simulationSpec);
+    if (capabilityValidation !== undefined)
+        return capabilityValidation;
+    const propertyType = String(propertySpec.type ?? "");
+    if (![
+        "no_allow_or_log_for_condition",
+        "must_review_for_condition",
+        "must_deny_for_condition",
+        "decision_must_be_one_of",
+        "policy_must_match_for_condition",
+    ].includes(propertyType)) {
+        return simulationUnknown(`Unsupported bounded simulation property type: ${String(propertySpec.type)}`, {
+            errorCode: "simulation_unsupported_property",
+        });
+    }
+    const propertyValidation = validateSimulationProperty(propertySpec);
+    if (propertyValidation !== undefined)
+        return propertyValidation;
+    if (!isRecord(simulationSpec.domains)) {
+        return simulationUnknown("Simulation domains must be an object.", { errorCode: "simulation_invalid_domain" });
+    }
+    const domains = {};
+    const fieldRegistry = simulationSpec.fieldRegistry;
+    if (fieldRegistry !== undefined && !isRecord(fieldRegistry)) {
+        return simulationUnknown("Simulation fieldRegistry must be an object.", { errorCode: "simulation_invalid_field_registry" });
+    }
+    if (fieldRegistry !== undefined) {
+        const registryCapabilities = validateCapabilityList(fieldRegistry.capabilities);
+        if (!registryCapabilities.ok) {
+            return simulationUnknown(registryCapabilities.reason ?? "Invalid capability metadata.", {
+                errorCode: registryCapabilities.errorCode,
+            });
+        }
+    }
+    for (const [field, values] of Object.entries(simulationSpec.domains)) {
+        if (!["agent", "action", "context"].includes(field.split(".")[0])) {
+            return simulationUnknown(`Simulation domain path must start with agent, action, or context: ${field}`, {
+                errorCode: "simulation_invalid_domain",
+            });
+        }
+        if (!Array.isArray(values) || values.length === 0) {
+            return simulationUnknown(`Simulation domain \`${field}\` must be a non-empty array.`, {
+                errorCode: "simulation_invalid_domain",
+            });
+        }
+        const registryValidation = validateDomainAgainstRegistry(field, values, fieldRegistry);
+        if (registryValidation !== undefined)
+            return registryValidation;
+        domains[field] = values.map(cloneValue);
+    }
+    const maxSamples = Number(simulationSpec.maxSamples ?? 500);
+    if (!Number.isFinite(maxSamples)) {
+        return simulationUnknown("Simulation maxSamples must be a number.", { errorCode: "simulation_invalid_max_samples" });
+    }
+    const sampleCount = Object.values(domains).reduce((count, values) => count * values.length, 1);
+    if (sampleCount > maxSamples) {
+        return simulationUnknown(`Simulation would generate ${sampleCount} samples, above maxSamples=${maxSamples}.`, {
+            errorCode: "simulation_sample_limit",
+        });
+    }
+    const propertyCondition = normalizeCondition(propertySpec.condition);
+    const decisionCounts = emptyDecisionCounts();
+    let checkedSamples = 0;
+    let matchingSamples = 0;
+    const policyIds = [];
+    const counterexamples = [];
+    const counterexampleLimit = Number(simulationSpec.counterexampleLimit ?? 5);
+    let index = 0;
+    for (const sample of simulationSamples(domains, simulationSpec.baseAgent ?? {}, simulationSpec.baseAction ?? {}, simulationSpec.baseContext ?? {})) {
+        const sampleIndex = index;
+        index += 1;
+        checkedSamples += 1;
+        const scope = { agent: sample.agent, action: sample.action, context: sample.context };
+        const propertyMatch = conditionMatches(propertyCondition, scope);
+        if (propertyMatch === undefined) {
+            return simulationUnknown("Simulation property condition could not be evaluated.", {
+                errorCode: "simulation_property_evaluation_unknown",
+                checkedSamples,
+                matchingSamples,
+                decisionCounts,
+                policyIds,
+                counterexamples,
+            });
+        }
+        const trace = tracePolicyIrSemantics(policyIr, scope);
+        if (isDecisionCountKey(trace.decision))
+            decisionCounts[trace.decision] += 1;
+        else
+            decisionCounts.unknown += 1;
+        for (const policyId of trace.matchedPolicyIds)
+            appendUnique(policyIds, policyId);
+        if (!propertyMatch)
+            continue;
+        matchingSamples += 1;
+        if (trace.result === "unknown" || trace.decision === "unknown") {
+            return simulationUnknown("A matching sample could not be evaluated.", {
+                errorCode: "simulation_evaluation_unknown",
+                checkedSamples,
+                matchingSamples,
+                decisionCounts,
+                policyIds,
+                counterexamples,
+            });
+        }
+        const decision = simulationDecisionFromTrace(trace);
+        const violation = propertyViolation(propertySpec, decision);
+        if (violation !== undefined) {
+            if (counterexamples.length < counterexampleLimit) {
+                counterexamples.push({
+                    sampleIndex,
+                    action: sample.action,
+                    context: sample.context,
+                    decision,
+                    reason: violation,
+                });
+            }
+        }
+    }
+    if (matchingSamples === 0) {
+        return simulationUnknown("No generated samples matched the property condition.", {
+            errorCode: "simulation_no_matching_samples",
+            checkedSamples,
+            matchingSamples,
+            decisionCounts,
+            policyIds,
+            counterexamples,
+        });
+    }
+    if (counterexamples.length > 0) {
+        return {
+            result: "fail",
+            reason: propertyFailureReason(propertySpec),
+            policyIds,
+            checkedSamples,
+            matchingSamples,
+            decisionCounts,
+            counterexamples,
+        };
+    }
+    return {
+        result: "pass",
+        reason: propertyPassReason(propertySpec),
+        policyIds,
+        checkedSamples,
+        matchingSamples,
+        decisionCounts,
+        counterexamples: [],
+    };
+}
+function normalizePolicy(policy, index) {
+    const policyRecord = isRecord(policy) ? policy : {};
+    const rawMetadata = policyRecord.metadata;
+    return compactRecord({
+        kind: "Policy",
+        index,
+        id: String(policyRecord.id ?? `policy-${index}`),
+        name: policyRecord.name === undefined ? undefined : String(policyRecord.name),
+        description: policyRecord.description === undefined ? undefined : String(policyRecord.description),
+        effect: String(policyRecord.effect ?? ""),
+        reason: String(policyRecord.reason ?? "Policy matched."),
+        condition: normalizeCondition(policyRecord.conditions),
+        metadata: isRecord(rawMetadata) ? rawMetadata : {},
+    });
+}
+function normalizeCondition(condition) {
+    if (condition === undefined || condition === null) {
+        return { kind: "all", children: [] };
+    }
+    if (!isRecord(condition)) {
+        return { kind: "invalid", error: "Policy conditions must be an object." };
+    }
+    if ("all" in condition || "any" in condition) {
+        const key = "all" in condition ? "all" : "any";
+        const group = condition[key];
+        if (!Array.isArray(group)) {
+            return {
+                kind: "invalid",
+                error: `Condition group \`${key}\` must be a list.`,
+                group: key,
+            };
+        }
+        return {
+            kind: key,
+            children: group.map(normalizeCondition).sort((left, right) => compareStrings(conditionSignature(left), conditionSignature(right))),
+        };
+    }
+    const value = condition.value;
+    return {
+        kind: "condition",
+        field: condition.field === undefined ? "" : String(condition.field),
+        operator: String(condition.operator ?? "equals"),
+        value,
+        valueType: valueType(value),
+    };
+}
+function valueType(value) {
+    if (typeof value === "boolean")
+        return "boolean";
+    if (typeof value === "number")
+        return "number";
+    if (typeof value === "string")
+        return "string";
+    if (Array.isArray(value)) {
+        const itemTypes = new Set(value.map(valueType));
+        if (itemTypes.size === 1 && ["string", "number", "boolean"].includes([...itemTypes][0])) {
+            return "enum";
+        }
+        return "object";
+    }
+    if (isRecord(value))
+        return "object";
+    return "unknown";
+}
+function conditionFindings(condition, policyId) {
+    const findings = [];
+    if (condition.kind === "invalid") {
+        findings.push({
+            severity: "error",
+            code: "malformed_condition_group",
+            message: condition.error,
+            policyIds: [policyId],
+            field: condition.group ? `conditions.${condition.group}` : "conditions",
+        });
+    }
+    if (condition.kind === "all" || condition.kind === "any") {
+        for (const child of condition.children)
+            findings.push(...conditionFindings(child, policyId));
+    }
+    if (condition.kind === "condition") {
+        if (!condition.field) {
+            findings.push({
+                severity: "error",
+                code: "missing_condition_field",
+                message: "Condition is missing a field.",
+                policyIds: [policyId],
+                field: "conditions.field",
+            });
+        }
+        if (!POLICY_OPERATORS.has(condition.operator)) {
+            findings.push({
+                severity: "error",
+                code: "unsupported_operator",
+                message: `Condition uses unsupported operator: ${condition.operator}`,
+                policyIds: [policyId],
+                field: "conditions.operator",
+            });
+        }
+    }
+    return findings;
+}
+function collectFieldTypes(condition, fieldTypes) {
+    if (condition.kind === "all" || condition.kind === "any") {
+        for (const child of condition.children)
+            collectFieldTypes(child, fieldTypes);
+    }
+    if (condition.kind === "condition" && condition.field) {
+        fieldTypes.set(condition.field, fieldTypes.get(condition.field) ?? new Set());
+        fieldTypes.get(condition.field)?.add(condition.valueType);
+    }
+}
+function contradictionFindings(condition, policyId) {
+    if (condition.kind !== "all")
+        return [];
+    const equalsByField = new Map();
+    const greaterThan = new Map();
+    const lessThan = new Map();
+    const findings = [];
+    for (const child of condition.children) {
+        if (child.kind !== "condition")
+            continue;
+        if (child.operator === "equals") {
+            equalsByField.set(child.field, equalsByField.get(child.field) ?? new Set());
+            equalsByField.get(child.field)?.add(JSON.stringify(child.value));
+        }
+        if (child.operator === "greater_than" && typeof child.value === "number") {
+            greaterThan.set(child.field, Math.max(greaterThan.get(child.field) ?? child.value, child.value));
+        }
+        if (child.operator === "less_than" && typeof child.value === "number") {
+            lessThan.set(child.field, Math.min(lessThan.get(child.field) ?? child.value, child.value));
+        }
+    }
+    for (const [field, values] of equalsByField.entries()) {
+        if (values.size > 1)
+            findings.push(contradiction(policyId, field));
+    }
+    for (const [field, lower] of greaterThan.entries()) {
+        const upper = lessThan.get(field);
+        if (upper !== undefined && lower >= upper)
+            findings.push(contradiction(policyId, field));
+    }
+    return findings;
+}
+function contradiction(policyId, field) {
+    return {
+        severity: "warning",
+        code: "contradictory_conditions",
+        message: `Policy contains contradictory conditions for \`${field}\`.`,
+        policyIds: [policyId],
+        field: `conditions.${field}`,
+    };
+}
+function simulationUnknown(reason, partial = {}) {
+    return {
+        result: "unknown",
+        reason,
+        errorCategory: "simulation_unknown",
+        errorCode: partial.errorCode ?? "simulation_unknown",
+        policyIds: partial.policyIds ?? [],
+        checkedSamples: partial.checkedSamples ?? 0,
+        matchingSamples: partial.matchingSamples ?? 0,
+        decisionCounts: partial.decisionCounts ?? emptyDecisionCounts(),
+        counterexamples: partial.counterexamples ?? [],
+    };
+}
+function validateSimulationCapabilities(simulationSpec) {
+    const validation = validateRequiredCapabilities(simulationSpec.capabilities, BOUNDED_SIMULATION_CAPABILITIES);
+    if (!validation.ok) {
+        return simulationUnknown(validation.reason ?? "Invalid capability metadata.", {
+            errorCode: validation.errorCode,
+        });
+    }
+    return undefined;
+}
+function validateSimulationProperty(propertySpec) {
+    const propertyType = String(propertySpec.type ?? "");
+    if (propertyType === "decision_must_be_one_of") {
+        const decisions = propertySpec.decisions;
+        if (!Array.isArray(decisions) || decisions.length === 0) {
+            return simulationUnknown("Property `decision_must_be_one_of` requires a non-empty decisions array.", {
+                errorCode: "simulation_invalid_property",
+            });
+        }
+        const unsupported = decisions.filter((decision) => !(String(decision) in DECISION_RANK));
+        if (unsupported.length > 0) {
+            return simulationUnknown(`Property \`decision_must_be_one_of\` contains unsupported decisions: ${JSON.stringify(unsupported)}`, { errorCode: "simulation_invalid_property" });
+        }
+    }
+    if (propertyType === "policy_must_match_for_condition" && propertyPolicyIds(propertySpec).length === 0) {
+        return simulationUnknown("Property `policy_must_match_for_condition` requires policyId or policyIds.", {
+            errorCode: "simulation_invalid_property",
+        });
+    }
+    return undefined;
+}
+function propertyViolation(propertySpec, decision) {
+    const propertyType = String(propertySpec.type ?? "");
+    if (propertyType === "no_allow_or_log_for_condition") {
+        return decision.decision === "allow" || decision.decision === "log"
+            ? "Decision allowed or logged a matching sample."
+            : undefined;
+    }
+    if (propertyType === "must_review_for_condition") {
+        return decision.decision !== "review" ? "Decision was not review for a matching sample." : undefined;
+    }
+    if (propertyType === "must_deny_for_condition") {
+        return decision.decision !== "deny" ? "Decision was not deny for a matching sample." : undefined;
+    }
+    if (propertyType === "decision_must_be_one_of") {
+        const decisions = new Set(propertySpec.decisions.map(String));
+        return decisions.has(decision.decision) ? undefined : `Decision \`${decision.decision}\` was outside the allowed set.`;
+    }
+    if (propertyType === "policy_must_match_for_condition") {
+        const expected = new Set(propertyPolicyIds(propertySpec));
+        return decision.matchedPolicyIds.some((policyId) => expected.has(policyId))
+            ? undefined
+            : "No expected policy matched a matching sample.";
+    }
+    return "Unsupported property type.";
+}
+function propertyPolicyIds(propertySpec) {
+    if (propertySpec.policyId !== undefined)
+        return [String(propertySpec.policyId)];
+    return Array.isArray(propertySpec.policyIds) ? propertySpec.policyIds.map(String) : [];
+}
+function propertyFailureReason(propertySpec) {
+    const propertyType = String(propertySpec.type ?? "");
+    if (propertyType === "no_allow_or_log_for_condition") {
+        return "One or more bounded samples matched the forbidden condition and resulted in allow/log.";
+    }
+    if (propertyType === "must_review_for_condition") {
+        return "One or more bounded samples matched the condition and did not result in review.";
+    }
+    if (propertyType === "must_deny_for_condition") {
+        return "One or more bounded samples matched the condition and did not result in deny.";
+    }
+    if (propertyType === "decision_must_be_one_of") {
+        return "One or more bounded samples matched the condition and selected a decision outside the allowed set.";
+    }
+    if (propertyType === "policy_must_match_for_condition") {
+        return "One or more bounded samples matched the condition without matching the expected policy.";
+    }
+    return "One or more bounded samples violated the property.";
+}
+function propertyPassReason(propertySpec) {
+    const propertyType = String(propertySpec.type ?? "");
+    if (propertyType === "no_allow_or_log_for_condition") {
+        return "All matching bounded samples avoided allow/log decisions.";
+    }
+    if (propertyType === "must_review_for_condition") {
+        return "All matching bounded samples resulted in review.";
+    }
+    if (propertyType === "must_deny_for_condition") {
+        return "All matching bounded samples resulted in deny.";
+    }
+    if (propertyType === "decision_must_be_one_of") {
+        return "All matching bounded samples selected an allowed decision.";
+    }
+    if (propertyType === "policy_must_match_for_condition") {
+        return "All matching bounded samples matched the expected policy.";
+    }
+    return "All matching bounded samples satisfied the property.";
+}
+function categorizeFinding(finding) {
+    return {
+        ...finding,
+        errorCategory: finding.errorCategory ?? errorCategoryForCode(finding.code),
+    };
+}
+function emptyDecisionCounts() {
+    return { allow: 0, log: 0, review: 0, deny: 0, unknown: 0 };
+}
+function validateDomainAgainstRegistry(field, values, fieldRegistry) {
+    if (fieldRegistry === undefined)
+        return undefined;
+    const fields = fieldRegistry.fields;
+    if (!isRecord(fields) || !(field in fields))
+        return undefined;
+    const entry = fields[field];
+    if (!isRecord(entry)) {
+        return simulationUnknown(`Field registry entry for \`${field}\` must be an object.`, {
+            errorCode: "simulation_invalid_field_registry",
+        });
+    }
+    const fieldType = String(entry.type ?? "");
+    if (!["string", "enum", "number", "boolean"].includes(fieldType)) {
+        return simulationUnknown(`Field registry entry for \`${field}\` has unsupported type: ${fieldType}`, {
+            errorCode: "simulation_unsupported_field_registry_type",
+        });
+    }
+    for (const value of values) {
+        if ((fieldType === "string" || fieldType === "enum") && typeof value !== "string") {
+            return simulationUnknown(`Simulation domain \`${field}\` contains non-string value for ${fieldType} field.`, {
+                errorCode: "simulation_invalid_domain",
+            });
+        }
+        if (fieldType === "boolean" && typeof value !== "boolean") {
+            return simulationUnknown(`Simulation domain \`${field}\` contains non-boolean value.`, {
+                errorCode: "simulation_invalid_domain",
+            });
+        }
+        if (fieldType === "number" && (typeof value !== "number" || !Number.isFinite(value))) {
+            return simulationUnknown(`Simulation domain \`${field}\` contains nonnumeric value.`, {
+                errorCode: "simulation_invalid_domain",
+            });
+        }
+        if (fieldType === "enum" && Array.isArray(entry.values) && !entry.values.includes(value)) {
+            return simulationUnknown(`Simulation domain \`${field}\` contains value outside registry enum values.`, {
+                errorCode: "simulation_invalid_domain",
+            });
+        }
+        if (fieldType === "number" && typeof value === "number") {
+            if (typeof entry.min === "number" && value < entry.min) {
+                return simulationUnknown(`Simulation domain \`${field}\` contains value below registry min.`, {
+                    errorCode: "simulation_invalid_domain",
+                });
+            }
+            if (typeof entry.max === "number" && value > entry.max) {
+                return simulationUnknown(`Simulation domain \`${field}\` contains value above registry max.`, {
+                    errorCode: "simulation_invalid_domain",
+                });
+            }
+        }
+    }
+    return undefined;
+}
+function isDecisionCountKey(value) {
+    return value === "allow" || value === "log" || value === "review" || value === "deny";
+}
+function* simulationSamples(domains, baseAgent, baseAction, baseContext) {
+    const keys = Object.keys(domains).sort(compareStrings);
+    if (keys.length === 0) {
+        yield {
+            agent: cloneValue(baseAgent),
+            action: cloneValue(baseAction),
+            context: cloneValue(baseContext),
+        };
+        return;
+    }
+    yield* simulationSampleAt(domains, keys, 0, {}, baseAgent, baseAction, baseContext);
+}
+function* simulationSampleAt(domains, keys, keyIndex, assignments, baseAgent, baseAction, baseContext) {
+    if (keyIndex >= keys.length) {
+        const agent = cloneValue(baseAgent);
+        const action = cloneValue(baseAction);
+        const context = cloneValue(baseContext);
+        const scope = { agent, action, context };
+        for (const [path, value] of Object.entries(assignments))
+            setDotted(scope, path, value);
+        yield { agent, action, context };
+        return;
+    }
+    const key = keys[keyIndex];
+    for (const value of domains[key]) {
+        assignments[key] = value;
+        yield* simulationSampleAt(domains, keys, keyIndex + 1, assignments, baseAgent, baseAction, baseContext);
+    }
+    delete assignments[key];
+}
+function setDotted(scope, path, value) {
+    const parts = path.split(".");
+    let current = scope;
+    for (const part of parts.slice(0, -1)) {
+        const next = current[part];
+        if (!isRecord(next))
+            current[part] = {};
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = cloneValue(value);
+}
+export function tracePolicyIrSemantics(policyIr, scope) {
+    if (!Array.isArray(policyIr.policies)) {
+        return unknownSemanticTrace("Policy IR policies must be a list.", "simulation_malformed_ir");
+    }
+    const matched = [];
+    for (const policy of policyIr.policies) {
+        const conditionMatch = conditionMatches(policy.condition, scope);
+        if (conditionMatch === undefined) {
+            return unknownSemanticTrace(`Policy \`${policy.id}\` condition could not be evaluated.`, "simulation_evaluation_unknown");
+        }
+        if (conditionMatch)
+            matched.push(policy);
+    }
+    if (matched.length === 0) {
+        const defaultDecision = policyIr.defaultDecision;
+        if (!(defaultDecision in DECISION_RANK)) {
+            return unknownSemanticTrace(`Unsupported default decision: ${defaultDecision}`, "simulation_unsupported_default_decision");
+        }
+        return evaluatedSemanticTrace({
+            decision: defaultDecision,
+            reason: policyIr.defaultReason,
+            matchedPolicyIds: [],
+            selectedPolicyId: null,
+            selectedMetadata: {},
+            enforcementSource: "policy_pack_default",
+        });
+    }
+    const selected = matched.reduce((current, next) => decisionRank(next.effect) > decisionRank(current.effect) ? next : current);
+    const matchedPolicyIds = matched.map((policy) => policy.id);
+    if (!(selected.effect in DECISION_RANK)) {
+        return unknownSemanticTrace(`Unsupported policy effect: ${selected.effect}`, "simulation_unsupported_effect", matchedPolicyIds);
+    }
+    return evaluatedSemanticTrace({
+        decision: selected.effect,
+        reason: selected.reason,
+        matchedPolicyIds,
+        selectedPolicyId: selected.id,
+        selectedMetadata: selected.metadata,
+        enforcementSource: "matched_policy",
+    });
+}
+function evaluatePolicyIr(policyIr, scope) {
+    return simulationDecisionFromTrace(tracePolicyIrSemantics(policyIr, scope));
+}
+function evaluatedSemanticTrace(input) {
+    const metadata = { enforcementSource: input.enforcementSource };
+    if (input.enforcementSource === "matched_policy") {
+        metadata.matchedPolicyCount = input.matchedPolicyIds.length;
+        metadata.selectedPolicyId = input.selectedPolicyId;
+        Object.assign(metadata, stableValue(input.selectedMetadata));
+    }
+    return {
+        semanticTraceVersion: ANALYSIS_SEMANTIC_TRACE_VERSION,
+        result: "evaluated",
+        decision: input.decision,
+        reason: input.reason,
+        matchedPolicyIds: input.matchedPolicyIds,
+        selectedPolicyId: input.selectedPolicyId,
+        selectedMetadata: stableValue(input.selectedMetadata),
+        enforcementSource: input.enforcementSource,
+        metadata,
+    };
+}
+function unknownSemanticTrace(reason, errorCode, matchedPolicyIds = []) {
+    const metadata = simulationErrorMetadata(errorCode);
+    return {
+        semanticTraceVersion: ANALYSIS_SEMANTIC_TRACE_VERSION,
+        result: "unknown",
+        decision: "unknown",
+        reason,
+        matchedPolicyIds,
+        selectedPolicyId: null,
+        selectedMetadata: {},
+        enforcementSource: String(metadata.enforcementSource),
+        unknownCategory: "simulation_unknown",
+        unknownCode: errorCode,
+        metadata,
+    };
+}
+function simulationDecisionFromTrace(trace) {
+    return {
+        decision: trace.decision,
+        reason: trace.reason,
+        matchedPolicyIds: trace.matchedPolicyIds,
+        metadata: stableValue(trace.metadata),
+    };
+}
+function simulationErrorMetadata(errorCode) {
+    return {
+        enforcementSource: "simulation_error",
+        errorCategory: "simulation_unknown",
+        errorCode,
+    };
+}
+function conditionMatches(condition, scope) {
+    if (condition.kind === "all") {
+        let unknown = false;
+        for (const child of condition.children) {
+            const childMatch = conditionMatches(child, scope);
+            if (childMatch === undefined) {
+                unknown = true;
+                continue;
+            }
+            if (!childMatch)
+                return false;
+        }
+        return unknown ? undefined : true;
+    }
+    if (condition.kind === "any") {
+        let unknown = false;
+        for (const child of condition.children) {
+            const childMatch = conditionMatches(child, scope);
+            if (childMatch === undefined) {
+                unknown = true;
+                continue;
+            }
+            if (childMatch)
+                return true;
+        }
+        return unknown ? undefined : false;
+    }
+    if (condition.kind === "condition")
+        return leafConditionMatches(condition, scope);
+    return undefined;
+}
+function leafConditionMatches(condition, scope) {
+    const actual = getDotted(scope, condition.field);
+    if (condition.operator === "equals")
+        return actual === condition.value;
+    if (condition.operator === "not_equals")
+        return actual !== condition.value;
+    if (condition.operator === "greater_than") {
+        const actualNumber = numericValue(actual);
+        const expectedNumber = numericValue(condition.value);
+        return actualNumber === undefined || expectedNumber === undefined ? false : actualNumber > expectedNumber;
+    }
+    if (condition.operator === "less_than") {
+        const actualNumber = numericValue(actual);
+        const expectedNumber = numericValue(condition.value);
+        return actualNumber === undefined || expectedNumber === undefined ? false : actualNumber < expectedNumber;
+    }
+    if (condition.operator === "in") {
+        return Array.isArray(condition.value) ? condition.value.includes(actual) : false;
+    }
+    return undefined;
+}
+function numericValue(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function appendUnique(values, value) {
+    if (!values.includes(value))
+        values.push(value);
+}
+function cloneValue(value) {
+    if (value === undefined)
+        return value;
+    return JSON.parse(JSON.stringify(value));
+}
+function decisionRank(effect) {
+    return effect in DECISION_RANK ? DECISION_RANK[effect] : -1;
+}
+function signatureValue(value) {
+    if (Array.isArray(value))
+        return value.map(signatureValue);
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key]) => key !== "index")
+            .sort(([left], [right]) => compareStrings(left, right))
+            .map(([key, entry]) => [key, signatureValue(entry)]));
+    }
+    return value;
+}