reversed.py

"""
Reversed SBPL normalization.

Normalizes reversed SBPL by combining:
1. Standard source normalization
2. Reconstructed predicate injection
3. Compiler-model-aware adjustments
4. Import expansion simulation for filtering compiler-added rules
"""

from __future__ import annotations

from dataclasses import asdict
from pathlib import Path
from typing import Any, Sequence

from pawl.normalize.policy import CanonicalPolicy, CanonicalPredicate, CanonicalRule
from pawl.normalize.source import (
    normalize_source,
    _normalize_predicate,
    _substitute_params,
    _lowercase_filter_paths,
    _flatten_string_append,
)
from pawl.normalize.passes.reconstruction import (
    decode_disconnected_filters,
    ReconstructedPredicate,
)
from pawl.normalize.baseline.imports import (
    compute_import_expansion,
    filter_imported_operations,
    ImportExpansion,
)
from pawl.normalize.baseline.predicates import filter_baseline_from_diff
from pawl.normalize.passes.deny_denormalize import (
    denormalize_policy,
    guided_denormalize,
)
from pawl.normalize.passes.predicate_dropout import (
    analyze_predicate_dropout,
    filter_dropped_predicates,
    PredicateDropoutInfo,
    BARE_ALLOW_THRESHOLD,
)
from pawl.normalize.passes.predicate_filter import (
    PredicateFilterInfo,
    PredicateSidecar,
)
from pawl.normalize.passes.shared_predicate import (
    SharedPredicateInfo,
    detect_shared_predicate_echoes,
    filter_shared_predicate_echoes,
)
from pawl.normalize.passes.redundant_rule import (
    RedundantRuleInfo,
    filter_redundant_rule_diffs,
)
from pawl.normalize.passes.wildcard_collapse import (
    WildcardCollapseInfo,
    collapse_wildcard_subops,
)
from pawl.normalize.passes.regex_equivalence import (
    RegexEquivalenceInfo,
    filter_regex_predicate_equivalences,
)
from pawl.normalize.passes.compiler_node_sharing import (
    CompilerNodeSharingInfo,
    annotate_compiler_node_sharing,
)


def _infer_action_from_hints(
    preds: list[ReconstructedPredicate],
    default_action: str,
) -> tuple[str, str]:
    """Infer action from reconstructed predicates' match_action hints.

    Returns (action, evidence) where evidence is "hint" or "default".
    Uses hint only when ALL predicates for the operation agree;
    otherwise falls back to default_action and marks unresolved.
    """
    actions = {p.match_action for p in preds if p.match_action is not None}
    if len(actions) == 1:
        return actions.pop(), "hint"
    return default_action, "default"


def _apply_wildcard_collapse(
    canonical: CanonicalPolicy,
    *,
    enabled: bool,
) -> tuple[CanonicalPolicy, WildcardCollapseInfo | None]:
    """Apply wildcard collapse and persist sidecar metadata when enabled."""
    if not enabled:
        return canonical, None

    collapsed, collapse_info = collapse_wildcard_subops(canonical)
    return CanonicalPolicy(
        default_action=collapsed.default_action,
        rules=collapsed.rules,
        metadata={
            **collapsed.metadata,
            "wildcard_collapse_info": asdict(collapse_info),
        },
    ), collapse_info


def _normalize_predicate_text(
    text: str,
    param_bindings: dict[str, str] | None,
    lowercase_paths: bool,
) -> str:
    """Apply param/path normalization to a single predicate text string.

    Reconstructed predicates are injected after the bulk normalize_source()
    call, so they miss param substitution, path lowering, and string-append
    flattening.  This helper applies the same transforms individually.
    """
    if param_bindings:
        text = _substitute_params(text, param_bindings)
    if lowercase_paths:
        text = _lowercase_filter_paths(text)
        text = _flatten_string_append(text)
    return text


def normalize_reversed(
    reversed_sbpl: str,
    *,
    disconnected_filters: list[dict] | None = None,
    pool_records: list[dict] | None = None,
    regex_records: list[dict] | None = None,
    nodes_by_offset: dict | None = None,
    collapse_wildcards: bool = False,
    denormalize_require_not: bool = False,
    param_bindings: dict[str, str] | None = None,
    lowercase_paths: bool = False,
) -> CanonicalPolicy:
    """Normalize reversed SBPL to canonical form.

    This extends source normalization with:
    - Reconstruction of predicates from disconnected filter nodes
    - Compiler-model-aware adjustments
    - Optional deny denormalization (splitting require-not to separate deny rules)

    Parameters
    ----------
    reversed_sbpl : str
        Reversed SBPL text from the reverser.
    disconnected_filters : list[dict] | None
        Disconnected filter information from reverse metadata.
    pool_records : list[dict] | None
        Literal pool records for predicate decoding.
    regex_records : list[dict] | None
        Regex bytecode records for pattern decoding.
    nodes_by_offset : dict | None
        Node lookup for argument extraction.
    collapse_wildcards : bool
        If True, collapse structurally equivalent wildcard-family sub-ops
        into wildcard operations and record collapse metadata.
    denormalize_require_not : bool
        If True, split require-not patterns into separate deny rules.
        This handles cases where the reverser normalized deny overrides
        into allow-with-require-not. Default False.
    param_bindings : dict[str, str] | None
        Mapping of param names to their resolved values. When provided,
        (param "NAME") and (string-append (param "NAME") ...) forms are
        substituted and paths lowercased to match compiler behavior.
    lowercase_paths : bool
        If True, lowercase all quoted path strings. Default False.

    Returns
    -------
    CanonicalPolicy
        Normalized canonical representation with reconstructed predicates.
    """
    # First, normalize the reversed SBPL using standard source normalization.
    # When param_bindings/lowercase_paths are provided (comparison path),
    # apply them symmetrically so roundtrip predicates like
    # (subpath (string-append (param "HOME") "/Library")) flatten to the
    # same concrete form as the source side.
    base_canonical = normalize_source(
        reversed_sbpl,
        param_bindings=param_bindings,
        lowercase_paths=lowercase_paths,
    )

    # If no disconnected filters, we're done (but may still collapse/denormalize)
    if not disconnected_filters:
        result = CanonicalPolicy(
            default_action=base_canonical.default_action,
            rules=base_canonical.rules,
            metadata={
                "source": "normalize_reversed",
                "has_reconstruction": False,
            },
        )
        result, _ = _apply_wildcard_collapse(result, enabled=collapse_wildcards)
        if denormalize_require_not:
            result = denormalize_policy(result)
        return result

    # Decode disconnected filters into reconstructed predicates
    reconstructed = decode_disconnected_filters(
        disconnected_filters,
        pool_records=pool_records,
        regex_records=regex_records,
        nodes_by_offset=nodes_by_offset,
    )

    # Group reconstructed predicates by operation
    by_operation: dict[str, list[ReconstructedPredicate]] = {}
    for pred in reconstructed:
        if pred.is_decoded:
            by_operation.setdefault(pred.operation, []).append(pred)

    # Merge reconstructed predicates into canonical rules
    augmented_rules = set()
    existing_ops = {r.operation for r in base_canonical.rules}

    for rule in base_canonical.rules:
        if rule.operation in by_operation:
            # Add reconstructed predicates to this rule
            new_predicates = set(rule.predicates)
            for rpred in by_operation[rule.operation]:
                if rpred.predicate_text:
                    pred_text = _normalize_predicate_text(
                        rpred.predicate_text, param_bindings, lowercase_paths,
                    )
                    canonical_pred = CanonicalPredicate(
                        text=pred_text,
                        filter_type=rpred.filter_name,
                        reconstructed=True,
                    )
                    new_predicates.add(canonical_pred)

            augmented_rules.add(CanonicalRule(
                action=rule.action,
                operation=rule.operation,
                predicates=frozenset(new_predicates),
            ))
        else:
            augmented_rules.add(rule)

    # Handle reconstructed predicates for operations not in reversed SBPL.
    # If an operation has disconnected filters but doesn't appear in the
    # reversed output, infer the action from match_action hints when
    # available; fall back to the profile's default action otherwise.
    for op, preds in by_operation.items():
        if op not in existing_ops:
            action, action_evidence = _infer_action_from_hints(
                preds, base_canonical.default_action,
            )
            reconstructed_predicates = frozenset(
                CanonicalPredicate(
                    text=_normalize_predicate_text(
                        p.predicate_text, param_bindings, lowercase_paths,
                    ),
                    filter_type=p.filter_name,
                    reconstructed=True,
                )
                for p in preds if p.predicate_text
            )
            if reconstructed_predicates:
                augmented_rules.add(CanonicalRule(
                    action=action,
                    operation=op,
                    predicates=reconstructed_predicates,
                ))

    result = CanonicalPolicy(
        default_action=base_canonical.default_action,
        rules=frozenset(augmented_rules),
        metadata={
            "source": "normalize_reversed",
            "has_reconstruction": bool(by_operation),
            "reconstructed_count": sum(len(v) for v in by_operation.values()),
            "reconstructed_operations": list(by_operation.keys()),
        },
    )
    result, _ = _apply_wildcard_collapse(result, enabled=collapse_wildcards)
    if denormalize_require_not:
        result = denormalize_policy(result)
    return result


_COMPILER_LOSS_AE_ARO_OPS = frozenset({
    "appleevent-send",
    "authorization-right-obtain",
})


def _filter_compiler_loss_ae_aro(
    diff: dict,
    disconnected_filters: list[dict] | None,
) -> tuple[dict, int]:
    """Filter AE/ARO operations from only_self when no filter evidence exists.

    Strict gate: only applies when the operation is AE/ARO AND there are
    zero disconnected filter records for it (no relevant filter nodes in blob).
    """
    if not disconnected_filters:
        reconstructed_ops: set[str] = set()
    else:
        reconstructed_ops = {df["operation"] for df in disconnected_filters}

    only_self = diff.get("only_self", [])
    filtered = []
    remaining = []
    for op in only_self:
        if op in _COMPILER_LOSS_AE_ARO_OPS and op not in reconstructed_ops:
            filtered.append(op)
        else:
            remaining.append(op)

    if filtered:
        diff = dict(diff)
        diff["only_self"] = remaining
        diff["compiler_loss_filtered"] = filtered
        diff["compiler_loss_filtered_count"] = len(filtered)

    return diff, len(filtered)


def _operations_in_diff(diff: dict[str, Any]) -> set[str]:
    """Return operations that still diverge in a canonical diff payload."""
    operations: set[str] = set()
    for op in diff.get("only_self", []) or []:
        if isinstance(op, str):
            operations.add(op)
    for op in diff.get("only_other", []) or []:
        if isinstance(op, str):
            operations.add(op)
    for row in diff.get("predicate_diffs", []) or []:
        if isinstance(row, dict):
            operation = row.get("operation")
            if isinstance(operation, str):
                operations.add(operation)
    return operations


def compare_source_and_reversed(
    source_sbpl: str,
    reversed_sbpl: str,
    *,
    disconnected_filters: list[dict] | None = None,
    param_bindings: dict[str, str] | None = None,
    strict: bool = False,
    semantic: bool = True,
    filter_imports: bool = False,
    filter_baseline: bool = False,
    search_paths: Sequence[Path] | None = None,
    source_path: Path | None = None,
    tolerate_redundant: bool = True,
    augment_entitlements: bool = False,
    entitlement_import: str | None = None,
    denormalize_require_not: bool = True,
    filter_predicate_dropout: bool = True,
    filter_predicate_merge: bool = True,
    filter_regex_equivalence: bool = True,
    filter_shared_predicates: bool = True,
    shared_operations: Sequence[str] | None = None,
    filter_redundant_rules: bool = False,
    redundant_context: dict[str, Any] | None = None,
    predicate_sidecar: PredicateSidecar | None = None,
    collapse_wildcards: bool = False,
    wildcard_equivalence: bool = False,
    node_sharing_sidecar: dict[str, Any] | None = None,
    **kwargs,
) -> dict[str, Any]:
    """Compare source and reversed SBPL at canonical level.

    Uses relaxed equivalence by default: the reversed SBPL must capture all
    source rules (with matching predicates), but may include additional
    compiler-added rules (baseline implicits, promoted ops).

    Parameters
    ----------
    source_sbpl : str
        Original source SBPL.
    reversed_sbpl : str
        Reversed SBPL from the reverser.
    disconnected_filters : list[dict] | None
        Disconnected filter information.
    param_bindings : dict[str, str] | None
        Mapping of param names to their resolved values. When provided,
        (param "NAME") references in source are substituted and paths are
        lowercased to match compiler behavior before comparison.
    strict : bool
        If True, require exact rule set equality. Default False allows
        reversed to have extra rules (compiler-added implicits).
    semantic : bool
        If True (default), also compute semantic equivalence which ignores
        require-any/require-all grouping differences. This handles cases where
        source has (allow op (pred-a) (pred-b)) but reversed groups them into
        (allow op (require-any (pred-a) (pred-b))).
    filter_imports : bool
        If True, simulate import expansion and filter imported operations
        from the "only_other" list in the diff. This removes false positives
        caused by the compiler flattening imports. Requires search_paths.
    filter_baseline : bool
        If True, filter known baseline predicates from predicate_diffs.
        These are predicates added by the compiler from system imports
        (e.g., baseline mach-lookup services, file paths). Default False.
    search_paths : Sequence[Path] | None
        Directories to search for imported profiles. Required if filter_imports
        is True. Typically includes the source file's directory and system
        profile directories.
    source_path : Path | None
        Path to the source file (for relative import resolution).
    tolerate_redundant : bool
        If True (default), tolerate rules in source that don't appear in
        reversed if their action matches the default action. This handles
        cases like `(deny X)` with deny default being semantically equivalent
        to not having the rule.
    augment_entitlements : bool
        If True, inject entitlement let-binding blocks from source into
        reversed SBPL before comparison. This handles cases where source
        has (let ((x (entitlement "key"))) (allow op ...)) which compiles
        to no operations when entitlements aren't provided. Default False.
    entitlement_import : str | None
        Import statement to inject when augment_entitlements=True. If None,
        uses the appsandbox-common.sb import from source or a default.
    denormalize_require_not : bool
        If True (default), denormalize require-not patterns in reversed SBPL
        to separate deny rules when the source has corresponding deny rules.
        This handles cases where the reverser normalized deny overrides into
        allow-with-require-not.
    filter_predicate_dropout : bool
        If True (default), filter predicate differences that are expected due
        to compiler optimization. When a profile has (deny default) and many
        bare (allow X) rules, the compiler may drop predicates from other
        allow rules. This is detected and filtered from the comparison.
    filter_predicate_merge : bool
        If True (default), filter predicate differences caused by node-sharing
        contamination. When the compiler merges graph nodes across operations,
        predicates from one operation may appear under another. Known invalid
        pairings with high-confidence collapse rules are filtered.
    filter_regex_equivalence : bool
        If True (default), filter predicate differences that are proven
        representational rewrites between regex/path-regex predicates and
        equivalent literal/subpath forms.
    filter_shared_predicates : bool
        If True (default), filter shared-entrypoint predicate echoes for
        operations identified by ``shared_operations``. Admissibility decisions
        are delegated to the predicate sidecar.
    shared_operations : Sequence[str] | None
        Operation names classified as ``shared_entrypoint`` by the IR builder.
        When provided and ``filter_shared_predicates=True``, these operations
        receive shared-echo filtering in both structural and semantic diffs.
    filter_redundant_rules : bool
        If True, apply C09 REDUNDANT filtering for compiler-elided and bounded
        spillover signatures in ``only_self``. Disabled by default and enabled
        explicitly by the profile FPH path.
    redundant_context : dict[str, Any] | None
        Sideband context for REDUNDANT filtering. Expected keys include
        source explicit ops, source/reversed slot views, and structural parity
        gates (blob/ir/op_table/graph). Missing context fails closed.
    predicate_sidecar : PredicateSidecar | None
        Optional pre-loaded predicate sidecar. When provided, reused for both
        structural and semantic diff filtering. When None and
        ``filter_predicate_merge=True`` or ``filter_shared_predicates=True``,
        loads lazily via ``PredicateSidecar.load()``.
    collapse_wildcards : bool
        If True, collapse reversed wildcard-family sub-ops into wildcard ops
        before guided deny denormalization. Implies wildcard_equivalence=True
        (collapse synthesizes wildcards on the reversed side, so the diff must
        tolerate those wildcards matching source children). Default False.
    wildcard_equivalence : bool
        If True, recognize wildcard operations as equivalent to their children.
        For example, `user-preference*` in reversed matches `user-preference-read`
        and `user-preference-write` in source if predicates are compatible.
        Automatically enabled when collapse_wildcards=True. Default False.
    **kwargs
        Additional arguments passed to normalize_reversed.

    Returns
    -------
    dict
        Comparison result with:
        - equivalent: bool (structural equivalence)
        - semantic_equivalent: bool (ignores grouping differences, if semantic=True)
        - source_canonical: CanonicalPolicy
        - reversed_canonical: CanonicalPolicy
        - diff: detailed diff if not equivalent
        - import_expansion: ImportExpansion (if filter_imports=True)
        - baseline_filtered_count: int (if filter_baseline=True)
        - entitlement_augmented: bool (if augment_entitlements=True)
        - entitlement_keys: list[str] (if augment_entitlements=True)
        - deny_denormalized: bool (if denormalize_require_not=True)
        - predicate_dropout_info: PredicateDropoutInfo (if filter_predicate_dropout=True)
        - predicate_dropout_filtered: int (count of filtered predicate diffs)
        - predicate_merge_info: dict (if filter_predicate_merge=True)
        - regex_equivalence_info: dict (if filter_regex_equivalence=True)
        - shared_predicate_info: dict (if filter_shared_predicates=True and shared ops provided)
        - shared_predicate_filtered: int (count of structural shared-predicate removals)
        - redundant_info: dict (if filter_redundant_rules=True)
        - redundant_filtered: int (count of structural redundant removals)
        - wildcard_collapse_info: dict (if collapse_wildcards=True)
    """
    # Wildcard collapse synthesizes wildcards on the reversed side; the diff
    # must tolerate those wildcards matching source children.
    if collapse_wildcards:
        wildcard_equivalence = True

    # Apply entitlement augmentation if requested
    entitlement_augmented = False
    entitlement_keys: list[str] = []
    if augment_entitlements:
        from pawl.normalize.passes.entitlement import (
            augment_reversed_for_comparison,
            has_any_entitlement_blocks,
            get_all_entitlement_keys,
        )
        if has_any_entitlement_blocks(source_sbpl):
            reversed_sbpl = augment_reversed_for_comparison(
                reversed_sbpl,
                source_sbpl,
                import_stmt=entitlement_import,
            )
            entitlement_augmented = True
            entitlement_keys = get_all_entitlement_keys(source_sbpl)

    # Always lowercase paths to match compiler behavior. The compiler lowercases
    # paths during compilation, so source predicates with paths like
    # "/Users/Foo/Library" need to be lowercased to "/users/foo/library"
    # to match the reversed output from compiled blobs.
    source_canonical = normalize_source(
        source_sbpl,
        param_bindings=param_bindings,
        lowercase_paths=True,
    )
    # Pop keys already passed explicitly so **kwargs doesn't duplicate them.
    kwargs.pop("lowercase_paths", None)
    kwargs.pop("param_bindings", None)
    filtered_disconnected_filters = disconnected_filters
    if disconnected_filters:
        base_reversed_canonical = normalize_reversed(
            reversed_sbpl,
            disconnected_filters=None,
            collapse_wildcards=collapse_wildcards,
            param_bindings=param_bindings,
            lowercase_paths=True,
            **kwargs,
        )
        if denormalize_require_not:
            base_reversed_canonical = guided_denormalize(base_reversed_canonical, source_canonical)
        base_diff = source_canonical.diff(
            base_reversed_canonical,
            tolerate_redundant=tolerate_redundant,
            wildcard_equivalence=wildcard_equivalence,
        )
        stable_ops = {
            str(finfo.get("operation")).strip()
            for finfo in disconnected_filters
            if isinstance(finfo, dict)
            and isinstance(finfo.get("operation"), str)
            and str(finfo.get("operation")).strip()
            and str(finfo.get("operation")).strip() not in _operations_in_diff(base_diff)
        }
        if stable_ops:
            filtered_disconnected_filters = [
                finfo
                for finfo in disconnected_filters
                if str(finfo.get("operation", "")).strip() not in stable_ops
            ]

    reversed_canonical = normalize_reversed(
        reversed_sbpl,
        disconnected_filters=filtered_disconnected_filters,
        collapse_wildcards=collapse_wildcards,
        param_bindings=param_bindings,
        lowercase_paths=True,
        **kwargs,
    )

    # Apply guided deny denormalization if requested
    # This splits require-not patterns in reversed SBPL into separate deny rules
    # when the source has corresponding deny rules
    deny_denormalized = False
    if denormalize_require_not:
        reversed_canonical = guided_denormalize(reversed_canonical, source_canonical)
        deny_denormalized = reversed_canonical.metadata.get("deny_denormalized", False)

    # Compute diff for detailed analysis
    diff = source_canonical.diff(
        reversed_canonical,
        tolerate_redundant=tolerate_redundant,
        wildcard_equivalence=wildcard_equivalence,
    )

    shared_ops = {
        str(operation).strip()
        for operation in (shared_operations or [])
        if str(operation).strip()
    }
    shared_predicate_info: SharedPredicateInfo | None = None
    if filter_shared_predicates and shared_ops:
        if predicate_sidecar is None:
            predicate_sidecar = PredicateSidecar.load()
        shared_predicate_info = detect_shared_predicate_echoes(
            reversed_canonical,
            shared_operations=shared_ops,
            predicate_sidecar=predicate_sidecar,
        )

    # Simulate import expansion and filter imported operations if requested
    import_expansion: ImportExpansion | None = None
    if filter_imports and search_paths:
        import_expansion = compute_import_expansion(
            source_sbpl,
            search_paths,
            source_path=source_path,
        )
        diff = filter_imported_operations(diff, import_expansion)

    # Filter baseline predicates if requested
    baseline_filtered_count = 0
    if filter_baseline:
        diff = filter_baseline_from_diff(diff)
        baseline_filtered_count = diff.get("baseline_filtered_count", 0)

    # Filter REDUNDANT cluster-A/B signatures if requested.
    structural_redundant_info: RedundantRuleInfo | None = None
    if filter_redundant_rules:
        diff, structural_redundant_info = filter_redundant_rule_diffs(
            diff,
            context=redundant_context,
        )

    # Filter predicate dropout if requested
    # When reversed has (deny default) + many bare allows, predicates may be dropped
    # during roundtrip compilation. We analyze the REVERSED SBPL since that's what
    # gets recompiled, and the predicates from SOURCE are what may be lost.
    predicate_dropout_info: PredicateDropoutInfo | None = None
    predicate_dropout_filtered = 0
    if filter_predicate_dropout:
        # Analyze reversed SBPL for bare allows (compiler optimization trigger)
        reversed_dropout = analyze_predicate_dropout(reversed_sbpl)
        # But use source predicates as the "at risk" set
        source_dropout = analyze_predicate_dropout(source_sbpl)

        # Combine: reversed bare allow count triggers dropout of source predicates
        if reversed_dropout.bare_allow_count >= BARE_ALLOW_THRESHOLD:
            predicate_dropout_info = PredicateDropoutInfo(
                at_risk=True,
                default_action=reversed_dropout.default_action,
                bare_allow_count=reversed_dropout.bare_allow_count,
                predicated_allows=source_dropout.predicated_allows,
                trigger="reversed_has_many_bare_allows",
            )
            diff = filter_dropped_predicates(diff, predicate_dropout_info)
            predicate_dropout_filtered = diff.get("predicate_dropout_filtered", 0)

    # Filter shared-entrypoint predicate echoes if requested
    structural_shared_info: SharedPredicateInfo | None = None
    if filter_shared_predicates and shared_ops:
        if predicate_sidecar is None:
            predicate_sidecar = PredicateSidecar.load()
        diff, structural_shared_info = filter_shared_predicate_echoes(
            diff,
            shared_operations=shared_ops,
            predicate_sidecar=predicate_sidecar,
        )
        if shared_predicate_info is None:
            shared_predicate_info = structural_shared_info
        elif structural_shared_info is not None:
            shared_predicate_info.filtered_count = structural_shared_info.filtered_count
            shared_predicate_info.filtered_only_other_count = structural_shared_info.filtered_only_other_count
            shared_predicate_info.filtered_predicate_count = structural_shared_info.filtered_predicate_count
            shared_predicate_info.unresolved_count = structural_shared_info.unresolved_count
            shared_predicate_info.unresolved_pairings = structural_shared_info.unresolved_pairings

    # Filter predicate merge contamination if requested
    structural_merge_info: PredicateFilterInfo | None = None
    if filter_predicate_merge:
        if predicate_sidecar is None:
            predicate_sidecar = PredicateSidecar.load()
        diff, structural_merge_info = predicate_sidecar.filter_diff(diff)

    structural_regex_info: RegexEquivalenceInfo | None = None
    if filter_regex_equivalence:
        diff, structural_regex_info = filter_regex_predicate_equivalences(diff)

    # Filter compiler-loss AE/ARO operations if applicable
    compiler_loss_filtered = 0
    diff, compiler_loss_filtered = _filter_compiler_loss_ae_aro(
        diff, disconnected_filters,
    )

    # Annotate compiler node-sharing losses (non-destructive)
    node_sharing_info: CompilerNodeSharingInfo | None = None
    if node_sharing_sidecar is not None:
        diff, node_sharing_info = annotate_compiler_node_sharing(
            diff, node_sharing_sidecar,
        )

    if strict:
        # Strict mode: require exact rule set equality
        equivalent = source_canonical == reversed_canonical
    else:
        # Relaxed mode: source intent must be captured
        # - only_self must be empty (all source rules in reversed)
        # - predicate_diffs must be empty (predicates match for common rules)
        # - only_other is OK (compiler-added rules are tolerated)
        only_self = diff.get("only_self", [])
        predicate_diffs = diff.get("predicate_diffs", [])
        default_match = (
            diff.get("type") != "default_action_mismatch"
            and source_canonical.default_action == reversed_canonical.default_action
        )
        equivalent = (
            default_match
            and len(only_self) == 0
            and len(predicate_diffs) == 0
        )

    result = {
        "equivalent": equivalent,
        "source_canonical": source_canonical,
        "reversed_canonical": reversed_canonical,
        "has_reconstruction": reversed_canonical.metadata.get("has_reconstruction", False),
    }

    # Include import expansion metadata if computed
    if import_expansion is not None:
        result["import_expansion"] = import_expansion
        result["import_filtered_count"] = len(import_expansion.imported_operations)
        result["unresolved_imports"] = import_expansion.unresolved_imports

    # Include baseline filtering metadata if computed
    if filter_baseline:
        result["baseline_filtered_count"] = baseline_filtered_count

    # Include entitlement augmentation metadata if computed
    if augment_entitlements:
        result["entitlement_augmented"] = entitlement_augmented
        result["entitlement_keys"] = entitlement_keys

    # Include deny denormalization metadata if computed
    if denormalize_require_not:
        result["deny_denormalized"] = deny_denormalized
        ops_denormalized = reversed_canonical.metadata.get("ops_denormalized", [])
        if ops_denormalized:
            result["ops_denormalized"] = ops_denormalized

    # Include predicate dropout metadata if computed
    if filter_predicate_dropout and predicate_dropout_info is not None:
        if predicate_dropout_info.at_risk:
            result["predicate_dropout_info"] = {
                "at_risk": predicate_dropout_info.at_risk,
                "trigger": predicate_dropout_info.trigger,
                "bare_allow_count": predicate_dropout_info.bare_allow_count,
                "predicated_allows": predicate_dropout_info.predicated_allows,
            }
            if predicate_dropout_filtered > 0:
                result["predicate_dropout_filtered"] = predicate_dropout_filtered

    # Include predicate merge metadata if computed
    if filter_predicate_merge and structural_merge_info is not None:
        merge_meta: dict[str, Any] = {
            "enabled": True,
            "structural_filtered_count": structural_merge_info.filtered_count,
            "semantic_filtered_count": 0,
            "unresolved_count": structural_merge_info.unresolved_count,
            "unresolved_pairings": structural_merge_info.unresolved_pairings,
            "sidecar_source": structural_merge_info.sidecar_source,
            "world_id": structural_merge_info.world_id,
            "rule_count": structural_merge_info.rule_count,
        }
        result["predicate_merge_info"] = merge_meta

    if filter_regex_equivalence and structural_regex_info is not None:
        regex_meta = asdict(structural_regex_info)
        regex_meta["enabled"] = True
        regex_meta["structural_filtered_count"] = structural_regex_info.filtered_predicate_count
        regex_meta["semantic_filtered_count"] = 0
        result["regex_equivalence_info"] = regex_meta
        if structural_regex_info.filtered_predicate_count > 0:
            result["regex_equivalence_filtered"] = structural_regex_info.filtered_predicate_count

    # Include shared-predicate metadata when enabled and shared ops provided
    if filter_shared_predicates and shared_predicate_info is not None:
        shared_meta = asdict(shared_predicate_info)
        shared_meta["enabled"] = True
        shared_meta["structural_filtered_count"] = (
            structural_shared_info.filtered_count if structural_shared_info is not None else 0
        )
        shared_meta["semantic_filtered_count"] = 0
        result["shared_predicate_info"] = shared_meta
        if shared_meta["structural_filtered_count"] > 0:
            result["shared_predicate_filtered"] = shared_meta["structural_filtered_count"]

    # Include REDUNDANT metadata when enabled.
    if filter_redundant_rules and structural_redundant_info is not None:
        redundant_meta = asdict(structural_redundant_info)
        redundant_meta["enabled"] = True
        redundant_meta["structural_filtered_count"] = structural_redundant_info.filtered_count
        redundant_meta["semantic_filtered_count"] = 0
        result["redundant_info"] = redundant_meta
        if structural_redundant_info.filtered_count > 0:
            result["redundant_filtered"] = structural_redundant_info.filtered_count

    if compiler_loss_filtered > 0:
        result["compiler_loss_info"] = {
            "filtered_count": compiler_loss_filtered,
            "filtered_operations": diff.get("compiler_loss_filtered", []),
        }

    # Include node-sharing compiler-loss annotation metadata
    if node_sharing_info is not None:
        result["node_sharing_info"] = asdict(node_sharing_info)
        result["compiler_loss_adjusted_eq"] = (
            node_sharing_info.remaining_unexplained == 0
        )

    # Include wildcard collapse metadata when explicitly enabled
    if collapse_wildcards:
        result["wildcard_collapse_info"] = reversed_canonical.metadata.get(
            "wildcard_collapse_info",
            {
                "collapsed_count": 0,
                "collapse_groups": [],
                "retained_count": 0,
            },
        )

    # Include wildcard equivalence matches if computed
    if wildcard_equivalence and "wildcard_matches" in diff:
        result["wildcard_matches"] = diff["wildcard_matches"]
        result["wildcard_matched_count"] = sum(
            len(m["matched_children"]) for m in diff["wildcard_matches"]
        )

    # Compute semantic equivalence if requested
    if semantic:
        # Semantic comparison ignores require-any/require-all grouping
        semantic_diff = source_canonical.diff(
            reversed_canonical,
            semantic=True,
            tolerate_redundant=tolerate_redundant,
            wildcard_equivalence=wildcard_equivalence,
        )

        # Apply import filtering to semantic diff as well
        if import_expansion is not None:
            semantic_diff = filter_imported_operations(semantic_diff, import_expansion)

        # Apply baseline filtering to semantic diff as well
        if filter_baseline:
            semantic_diff = filter_baseline_from_diff(semantic_diff)

        # Apply predicate dropout filtering to semantic diff as well
        if filter_predicate_dropout and predicate_dropout_info is not None:
            if predicate_dropout_info.at_risk:
                semantic_diff = filter_dropped_predicates(semantic_diff, predicate_dropout_info)

        # Apply shared-entrypoint filtering to semantic diff as well
        semantic_shared_info: SharedPredicateInfo | None = None
        if filter_shared_predicates and shared_ops:
            if predicate_sidecar is None:
                predicate_sidecar = PredicateSidecar.load()
            semantic_diff, semantic_shared_info = filter_shared_predicate_echoes(
                semantic_diff,
                shared_operations=shared_ops,
                predicate_sidecar=predicate_sidecar,
            )

        semantic_redundant_info: RedundantRuleInfo | None = None
        if filter_redundant_rules:
            semantic_diff, semantic_redundant_info = filter_redundant_rule_diffs(
                semantic_diff,
                context=redundant_context,
            )

        # Apply predicate merge filtering to semantic diff as well
        semantic_merge_info: PredicateFilterInfo | None = None
        if filter_predicate_merge:
            if predicate_sidecar is None:
                predicate_sidecar = PredicateSidecar.load()
            semantic_diff, semantic_merge_info = predicate_sidecar.filter_diff(semantic_diff)

        semantic_regex_info: RegexEquivalenceInfo | None = None
        if filter_regex_equivalence:
            semantic_diff, semantic_regex_info = filter_regex_predicate_equivalences(semantic_diff)

        if compiler_loss_filtered > 0:
            semantic_diff, _ = _filter_compiler_loss_ae_aro(
                semantic_diff, disconnected_filters,
            )

        # Annotate compiler node-sharing losses on semantic diff as well
        if node_sharing_sidecar is not None:
            semantic_diff, _ = annotate_compiler_node_sharing(
                semantic_diff, node_sharing_sidecar,
            )

        only_self_sem = semantic_diff.get("only_self", [])
        predicate_diffs_sem = semantic_diff.get("predicate_diffs", [])
        default_match_sem = (
            semantic_diff.get("type") != "default_action_mismatch"
            and source_canonical.default_action == reversed_canonical.default_action
        )
        semantic_equivalent = (
            default_match_sem
            and len(only_self_sem) == 0
            and len(predicate_diffs_sem) == 0
        )
        # Structural equivalence implies semantic equivalence.
        # Structural checks both predicate content AND grouping; semantic
        # checks only content.  If the stricter check passes, the looser
        # one cannot legitimately fail.  The semantic diff can produce
        # false residuals when baseline filtering loses structured context
        # on flattened predicates — this guard prevents those false
        # negatives from blocking convergence.
        if equivalent and not semantic_equivalent:
            semantic_equivalent = True
        result["semantic_equivalent"] = semantic_equivalent

        # Update predicate merge metadata with semantic counts
        if filter_predicate_merge and semantic_merge_info is not None:
            if "predicate_merge_info" in result:
                result["predicate_merge_info"]["semantic_filtered_count"] = semantic_merge_info.filtered_count
                # Merge unresolved counts (take max to avoid double-counting)
                result["predicate_merge_info"]["unresolved_count"] = max(
                    result["predicate_merge_info"]["unresolved_count"],
                    semantic_merge_info.unresolved_count,
                )

        # Update shared-predicate metadata with semantic counts
        if filter_shared_predicates and semantic_shared_info is not None:
            if "shared_predicate_info" in result:
                result["shared_predicate_info"]["semantic_filtered_count"] = (
                    semantic_shared_info.filtered_count
                )
        if filter_regex_equivalence and semantic_regex_info is not None:
            if "regex_equivalence_info" in result:
                result["regex_equivalence_info"]["semantic_filtered_count"] = (
                    semantic_regex_info.filtered_predicate_count
                )
            else:
                regex_meta = asdict(semantic_regex_info)
                regex_meta["enabled"] = True
                regex_meta["structural_filtered_count"] = 0
                regex_meta["semantic_filtered_count"] = semantic_regex_info.filtered_predicate_count
                result["regex_equivalence_info"] = regex_meta
        if filter_redundant_rules and semantic_redundant_info is not None:
            if "redundant_info" in result:
                result["redundant_info"]["semantic_filtered_count"] = (
                    semantic_redundant_info.filtered_count
                )
        if not semantic_equivalent and not equivalent:
            result["semantic_diff"] = semantic_diff

    include_diff_for_measurement = (
        node_sharing_info is not None
        and node_sharing_info.remaining_unexplained > 0
    )
    if not equivalent or include_diff_for_measurement:
        result["diff"] = diff

    return result