@danmoisan/drm-copilot-mcp 1.1.10 → 1.1.11

package/resources/claude-customizations/.claude/hooks/validate-bash.ps1

@@ -39,6 +39,11 @@ param(
 )
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+# Shared command-line parser (issue #545). Both detectors below run against the segment
+# list rather than against the unsegmented command string, so a dangerous phrase quoted
+# inside a message body is no longer a match and a relocating spelling no longer escapes.
+. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
+. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
 
 function Get-BlockedBashPattern {
     [CmdletBinding()]
@@ -55,7 +60,119 @@ function Get-BlockedBashPattern {
     )
 }
 
+function Test-BlockedPatternTokenRun {
+    <#
+    .SYNOPSIS
+        Report whether a literal's token sequence occurs as a contiguous run in a token list.
+    .DESCRIPTION
+        Whole-token equality, element by element. This is the comparison primitive that
+        replaces String.Contains. It is what makes '--force-with-lease' stop matching the
+        literal 'git push --force': the two are different tokens, whereas one is a substring
+        of the other.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][string[]] $Token,
+        [Parameter(Mandatory)][ValidateNotNullOrEmpty()][string[]] $PatternToken
+    )
+
+    if ($PatternToken.Count -eq 0 -or $Token.Count -lt $PatternToken.Count) {
+        return $false
+    }
+
+    for ($start = 0; $start -le $Token.Count - $PatternToken.Count; $start++) {
+        $matched = $true
+        for ($offset = 0; $offset -lt $PatternToken.Count; $offset++) {
+            if ($Token[$start + $offset] -ne $PatternToken[$offset]) {
+                $matched = $false
+                break
+            }
+        }
+        if ($matched) {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Get-BlockedStructuralGitMatch {
+    <#
+    .SYNOPSIS
+        Report the denylist literal a segment's structural git invocation stands for, or $null.
+    .DESCRIPTION
+        The flag conjunction is required rather than optional. Classifying on the bare
+        subcommand would deny 'git push --force-with-lease origin HEAD', which spec Test
+        Strategy row AT-8 requires to allow, and would deny 'git reset --soft HEAD~1'.
+
+        When a segment carries both '--force' and '-f' the '--force' leg is evaluated first,
+        so the returned value is 'git push --force'.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyString()][string] $SegmentText,
+        [Parameter(Mandatory)][AllowEmptyCollection()][string[]] $Token
+    )
+
+    if (Test-CommandLineInvocation -CommandText $SegmentText -CommandWord 'git' -SubcommandPath @('push')) {
+        if ($Token -contains '--force') { return 'git push --force' }
+        if ($Token -contains '-f') { return 'git push -f' }
+    }
+    if (Test-CommandLineInvocation -CommandText $SegmentText -CommandWord 'git' -SubcommandPath @('reset')) {
+        if ($Token -contains '--hard') { return 'git reset --hard' }
+    }
+
+    return $null
+}
+
 function Get-BlockedPatternMatch {
+    <#
+    .SYNOPSIS
+        Return the denylist literal a command matches, or $null.
+    .DESCRIPTION
+        Two legs, in this order, over the segment list produced by Read-CommandLineSegment.
+
+        Leg 1 (literal): each of the six byte-unchanged literals from Get-BlockedBashPattern
+        is split into its own whitespace-delimited token sequence and reported as a match
+        when that sequence occurs as a CONTIGUOUS RUN inside a segment's Tokens, every
+        element compared by whole-token equality. The value returned is the literal string
+        itself, and the literals are tested in their existing declaration order. Because a
+        quoted span is one token, 'git commit -m "why rm -rf is banned"' no longer matches.
+
+        Leg 1 has a second condition, the wrapper carve-out of D2 Piece 2 together with the two
+        other clauses under which the scanner selects raw scan text. A wrapper's quoted argument is
+        a nested command line rather than inert data, and ConvertTo-CommandLineToken collapses a
+        balanced quoted span into ONE token, so a multi-token literal can never form a contiguous
+        token run inside it. The same masking hides a literal carried inside a quoted span or a
+        heredoc that never closes. For a segment that is wrapper-led, that carries a live
+        substitution, or whose quoting or heredoc did not close, the scanner already selects
+        RawText as ScanText, and this leg reads that field with an Ordinal IndexOf, matching the
+        culture-insensitive String.Contains it replaced. The three disjuncts here are exactly the
+        three clauses of that ScanText selection, so no segment the scanner scans raw is left
+        unscanned by this leg. That is what keeps both 'bash -c "rm -rf /tmp/x"' and
+        'echo "rm -rf /tmp/x' denying. A segment matching none of the three is never scanned this
+        way, so 'git commit -m "docs: explain why rm -rf is banned"' still allows.
+
+        Leg 2 (structural): a relocating spelling such as 'git -C ../wt push --force origin
+        HEAD' contains no literal as a token run, so it is classified structurally instead.
+
+        Leg 1 is evaluated IN FULL, over every segment and every literal, before any leg 2
+        evaluation. That ordering is what keeps 'git push origin --force' returning the
+        literal 'git push origin --force' rather than the leg 2 value 'git push --force',
+        which is what the existing case at tests/scripts/claude-hooks/validate-bash.Tests.ps1
+        line 29 asserts.
+
+        Spec D11.3 rules that rule R2 governs the literal TEXT, not the comparison operator,
+        so all six literals stay byte-unchanged; only the comparison primitive changed.
+    .OUTPUTS
+        System.String or $null
+    #>
     [CmdletBinding()]
     [OutputType([string])]
     param(
@@ -69,9 +186,25 @@ function Get-BlockedPatternMatch {
         return $null
     }
 
+    $segments = @(Read-CommandLineSegment -CommandText $Command)
+
     foreach ($pattern in (Get-BlockedBashPattern)) {
-        if ($Command.Contains($pattern)) {
-            return $pattern
+        $patternTokens = [string[]]@($pattern -split '\s+' | Where-Object { $_ })
+        foreach ($segment in $segments) {
+            if (Test-BlockedPatternTokenRun -Token @($segment.Tokens) -PatternToken $patternTokens) {
+                return $pattern
+            }
+            if (($segment.IsWrapperLed -or $segment.HasLiveSubstitution -or $segment.Unbalanced) -and
+                $segment.ScanText.IndexOf($pattern, [System.StringComparison]::Ordinal) -ge 0) {
+                return $pattern
+            }
+        }
+    }
+
+    foreach ($segment in $segments) {
+        $structural = Get-BlockedStructuralGitMatch -SegmentText $segment.RawText -Token @($segment.Tokens)
+        if ($structural) {
+            return $structural
         }
     }
 
@@ -88,7 +221,50 @@ function Get-BlockedPatternMatch {
 # never chain `cd` with one of these in the same command.
 $script:CdChainedReadCommandPattern = 'cd\s+\S.*?(&&|;)\s*(grep|cat|head|tail|less|more|awk|sed\s+-n)\b'
 
+# The read-command family the pattern above enumerates, as command words. Retained
+# alongside the pattern so the rule R2 literal-text obligation stays visibly discharged:
+# the pattern string is byte-unchanged and is kept as a declared constant, while the
+# evaluation moves to the segment list.
+$script:CdChainedReadCommandWords = @('grep', 'cat', 'head', 'tail', 'less', 'more', 'awk', 'sed')
+
 function Get-CdChainedReadCommandMatch {
+    <#
+    .SYNOPSIS
+        Return the read command chained after a cd on the same command line, or $null.
+    .DESCRIPTION
+        Walks the segment list in order and reports a match when a segment whose CommandWord
+        is 'cd' and whose Tokens count is at least two is followed, at ANY later position in
+        the segment list, by a segment whose CommandWord is one of the read-command family.
+        The returned value is that later segment's CommandWord, except that a 'sed' segment
+        matches only when its second token is '-n' and then returns 'sed -n'. When more than
+        one later segment qualifies, the earliest supplies the return value.
+
+        The regex could not simply be evaluated per segment: '&&' and ';' are segment
+        delimiters under spec D2 Piece 1, so no single segment ever contains both sides of
+        the chain.
+
+        A second leg therefore runs first, before the walk: the retained regex constant is
+        evaluated against the ScanText of each segment the scanner already reads raw, which
+        is where a wrapper's quoted argument collapses a whole nested chain into one segment
+        the walk cannot decompose. The two legs are complementary and neither replaces the
+        other, so the ordering between them changes only which leg reports a chain that both
+        could see, never whether a chain is reported at all.
+
+        Adjacency is deliberately NOT required. The retained pattern places a lazy '.*?'
+        between the cd argument and the delimiter, so 'cd /x && npm test && grep foo bar.txt'
+        is denied today; requiring the read segment to follow the cd segment immediately
+        would turn that existing denial into an allow, which acceptance criterion 9 forbids.
+        This formulation also widens the delimiter set from '&&' and ';' to every segment
+        delimiter, so every command line in which a real cd segment precedes a real read
+        segment and is denied today is still denied.
+
+        One narrowing is intended and is stated rather than left implicit: a cd-then-read
+        phrase occurring only inside a quoted span or a heredoc body is denied today and
+        allows after this change, because the scanner masks that span before the segment list
+        is built. That narrowing is the over-match fix this issue exists to deliver.
+    .OUTPUTS
+        System.String or $null
+    #>
     [CmdletBinding()]
     [OutputType([string])]
     param(
@@ -102,12 +278,48 @@ function Get-CdChainedReadCommandMatch {
         return $null
     }
 
-    $match = [regex]::Match($Command, $script:CdChainedReadCommandPattern)
-    if (-not $match.Success) {
-        return $null
+    $segments = @(Read-CommandLineSegment -CommandText $Command)
+
+    # D12 call-site row for line 105: the retained pattern, evaluated per segment against
+    # ScanText. Complementary to the CommandWord walk below rather than a replacement for it.
+    # '&&' and ';' delimit segments, so an unquoted chain never puts both halves in one
+    # segment and only the walk can see it; a wrapper-led chain sits entirely inside one
+    # segment whose command word is the wrapper, and only this leg can see that. Restricting
+    # the leg to segments the scanner already scans raw preserves the intended narrowing:
+    # echo "cd /x && head f" is masked and still allows.
+    foreach ($segment in $segments) {
+        if ((Test-CommandLineSegmentRawScan -Segment $segment) -and
+            $segment.ScanText -match $script:CdChainedReadCommandPattern) {
+            return ($Matches[2] -replace '\s+', ' ')
+        }
     }
 
-    return $match.Groups[2].Value
+    $seenCd = $false
+
+    foreach ($segment in $segments) {
+        $tokens = @($segment.Tokens)
+        $word = [string]$segment.CommandWord
+
+        if (-not $seenCd) {
+            if ($word -eq 'cd' -and $tokens.Count -ge 2) {
+                $seenCd = $true
+            }
+            continue
+        }
+
+        if ($script:CdChainedReadCommandWords -notcontains $word) {
+            continue
+        }
+        if ($word -eq 'sed') {
+            if ($tokens.Count -ge 2 -and $tokens[1] -eq '-n') {
+                return 'sed -n'
+            }
+            continue
+        }
+        return $word
+    }
+
+    return $null
 }
 
 function Get-BashBlockReason {

package/resources/claude-customizations/.claude/lib/blast-radius/BlastRadius.psm1

@@ -6,10 +6,11 @@
     Destination-runtime PowerShell facade for the blast-radius library, porting
     scripts/dev_tools/compute_blast_radius.py (derive_blast_radius,
     radius_from_observed_paths, _feature_folder_glob) and
-    scripts/dev_tools/_blast_radius_conflicts.py (conflicts,
-    _smallest_path_overlap, _smallest_common). It imports the extraction, glob,
-    truth-table, and validation modules that sit beside it and re-exports the
-    five functions the spec PowerShell surface fixes:
+    scripts/dev_tools/_blast_radius_conflicts.py (conflicts). The ports of
+    _smallest_path_overlap and _smallest_common, and the mechanically-mergeable
+    path exclusion, live in BlastRadiusConflict.psm1. It imports the extraction,
+    glob, truth-table, conflict, and validation modules that sit beside it and
+    re-exports the five functions the spec PowerShell surface fixes:
 
       - Get-PlanPaths                     port of extract_plan_paths
       - Get-BlastRadius                   port of derive_blast_radius
@@ -58,6 +59,7 @@ Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusGlob.psm1')
 Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusConfig.psm1') -Force -ErrorAction Stop
 Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusNormalization.psm1') -Force -ErrorAction Stop
 Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusValidation.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusConflict.psm1') -Force -ErrorAction Stop
 
 # Feature-folder handling. Every radius contains its own feature folder, and a
 # caller may pass either a bare folder name or an already-qualified path.
@@ -81,10 +83,6 @@ $script:ConflictModuleOverlap = 'module_overlap'
 $script:ConflictSharedSurfaceOverlap = 'shared_surface_overlap'
 $script:ConflictContractDependency = 'contract_dependency'
 
-# Separator used in an overlapping-pair detail string. The pair is ordered
-# ordinally before formatting so the detail is identical in both argument orders.
-$script:PairDetailSeparator = ' ~ '
-
 
 # Port of _feature_folder_glob. Accepting an already-qualified path avoids
 # producing a doubled docs/features/active/docs/features/active/... entry when a
@@ -341,68 +339,6 @@ function Get-BlastRadiusFromObservedPaths {
     }
 }
 
-# Port of _smallest_path_overlap. Each overlapping pair is ordered before it is
-# recorded, so the minimum is taken over a set that does not depend on argument
-# order; that is what makes the reported detail symmetric.
-function Get-SmallestPathOverlap {
-    [CmdletBinding()]
-    [OutputType([string])]
-    param(
-        [Parameter(Mandatory = $true)]
-        [AllowEmptyCollection()]
-        [AllowEmptyString()]
-        [string[]] $PathA,
-        [Parameter(Mandatory = $true)]
-        [AllowEmptyCollection()]
-        [AllowEmptyString()]
-        [string[]] $PathB
-    )
-
-    $detail = [System.Collections.Generic.List[string]]::new()
-    foreach ($entryA in $PathA) {
-        foreach ($entryB in $PathB) {
-            if (-not (Test-EntryOverlap -EntryA $entryA -EntryB $entryB)) {
-                continue
-            }
-            $ordered = if ([string]::CompareOrdinal($entryA, $entryB) -le 0) {
-                @($entryA, $entryB)
-            } else {
-                @($entryB, $entryA)
-            }
-            $detail.Add($ordered -join $script:PairDetailSeparator)
-        }
-    }
-
-    return (Get-OrdinalSmallestEntry -Entry $detail.ToArray())
-}
-
-# Port of _smallest_common. Two empty collections share nothing, so the result is
-# $null and the level contributes no reason.
-function Get-SmallestCommonEntry {
-    [CmdletBinding()]
-    [OutputType([string])]
-    param(
-        [Parameter(Mandatory = $true)]
-        [AllowEmptyCollection()]
-        [AllowEmptyString()]
-        [string[]] $Left,
-        [Parameter(Mandatory = $true)]
-        [AllowEmptyCollection()]
-        [AllowEmptyString()]
-        [string[]] $Right
-    )
-
-    $rightSet = [System.Collections.Generic.HashSet[string]]::new($Right, [StringComparer]::Ordinal)
-    $common = [System.Collections.Generic.List[string]]::new()
-    foreach ($entry in $Left) {
-        if ($rightSet.Contains($entry)) {
-            $common.Add($entry)
-        }
-    }
-
-    return (Get-OrdinalSmallestEntry -Entry $common.ToArray())
-}
-
 function Test-BlastRadiusConflict {
     <#
     .SYNOPSIS
@@ -423,9 +359,10 @@ function Test-BlastRadiusConflict {
         Second radius record.
 
     .PARAMETER Config
-        Parsed config/blast-radius.json. The relation reads no key from it today;
-        it is validated and kept in the signature because the contract is frozen
-        for downstream consumers.
+        Parsed config/blast-radius.json. The relation reads exactly one key from
+        it, mergeable_paths, whose entries are dropped from both radii before the
+        path comparison; the mapping is otherwise validated and kept in the
+        signature because the contract is frozen for downstream consumers.
 
     .OUTPUTS
         System.Collections.Hashtable. Keys conflict (a boolean) and reasons (an
@@ -461,8 +398,14 @@ function Test-BlastRadiusConflict {
     $right = ConvertTo-NormalizedBlastRadius -Radius $RadiusB
 
     $reason = [System.Collections.Generic.List[hashtable]]::new()
-    $pathDetail = Get-SmallestPathOverlap -PathA ([string[]]@($left['paths'])) `
-        -PathB ([string[]]@($right['paths']))
+    # The mechanically-mergeable exclusion lives only here: it filters the two
+    # collections this comparison reads and rewrites no radius record, so a
+    # derived, declared, or observed radius still lists every project file it
+    # cited (issue #643).
+    $mergeable = [string[]]@(Get-ConfigMergeablePath -Config $Config)
+    $pathDetail = Get-SmallestPathOverlap `
+        -PathA ([string[]]@(Get-NonMergeablePathEntry -Entry ([string[]]@($left['paths'])) -MergeablePath $mergeable)) `
+        -PathB ([string[]]@(Get-NonMergeablePathEntry -Entry ([string[]]@($right['paths'])) -MergeablePath $mergeable))
     if ($null -ne $pathDetail) {
         $reason.Add(@{ kind = $script:ConflictPathOverlap; detail = $pathDetail })
     }

package/resources/claude-customizations/.claude/lib/blast-radius/BlastRadiusConflict.psm1

@@ -0,0 +1,290 @@
+<#
+.SYNOPSIS
+    Mechanically-mergeable path exclusion and the shared overlap helpers.
+
+.DESCRIPTION
+    Destination-runtime PowerShell mirror of
+    scripts/dev_tools/_blast_radius_mergeable.py (config_mergeable_paths,
+    matches_mergeable_path, exclude_mergeable_paths), plus the two overlap helpers
+    the relation calls (ports of _smallest_path_overlap and _smallest_common,
+    relocated here from BlastRadius.psm1).
+
+    The mergeable path class names the project-file shapes whose overlap a merge
+    step can reconcile without re-delegating the work (issue #643). Two items
+    touching the same .csproj are not genuinely in contention, so the class is
+    removed from both radii immediately before the relation compares them.
+
+    Parity notes for maintainers:
+      - The exclusion is applied ONLY inside Test-BlastRadiusConflict and changes
+        no radius record: a radius still lists every project file it cited, so
+        drift detection and validation see the paths they saw before this key.
+      - The key is optional and fail-closed: an absent mergeable_paths key and an
+        empty list both exclude nothing and reproduce pre-change behaviour.
+      - Every comparison is ordinal, matching the Python mirror's str equality.
+    CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusGlob.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusConfig.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusNormalization.psm1') -Force -ErrorAction Stop
+
+# Truth-table key naming the class, declared as a constant so the reader, its
+# tests, and the Python mirror all name one string rather than a literal.
+$script:ConfigMergeablePathKey = 'mergeable_paths'
+
+# Prefix making a configured pattern match at any depth. It is stripped in the
+# third matching step so a root-level file can satisfy it (Test-MergeablePath).
+$script:AnyDepthPrefix = '**/'
+
+# Separator used in an overlapping-pair detail string. The pair is ordered
+# ordinally before formatting so the detail is identical in both argument orders.
+$script:PairDetailSeparator = ' ~ '
+
+
+function Get-ConfigMergeablePath {
+    <#
+    .SYNOPSIS
+        Read the mechanically-mergeable path list from the truth table.
+
+    .DESCRIPTION
+        Port of config_mergeable_paths. The entries name project-file shapes,
+        normally anchored globs such as **/*.csproj (issue #643).
+
+    .PARAMETER Config
+        Parsed config/blast-radius.json. Only the mergeable_paths key is read.
+
+    .OUTPUTS
+        System.Object[]. Entries sorted and deduplicated by the underlying reader.
+        A config with no mergeable_paths key yields an empty array.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Object[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Config
+    )
+
+    return @(Get-ConfigStringList -Config $Config -Key $script:ConfigMergeablePathKey)
+}
+
+function Test-MergeablePath {
+    <#
+    .SYNOPSIS
+        Report whether one radius entry belongs to the mergeable path class.
+
+    .DESCRIPTION
+        Port of matches_mergeable_path. Three comparisons apply in order. The
+        first two are the read-by-mandate rules, delegated to Test-MandateRead
+        rather than restated: ordinal equality, the only rule that can settle a
+        glob entry, then glob containment for a concrete entry only. The third is
+        specific to this class, because an anchored pattern requires a separator
+        and so excludes a root-level file; retesting a concrete entry with the
+        anchor removed admits packages.config at the repository root.
+
+    .PARAMETER Entry
+        One radius paths entry: a concrete repository-relative path or a glob.
+
+    .PARAMETER MergeablePath
+        Configured patterns from Get-ConfigMergeablePath. An empty collection
+        matches nothing.
+
+    .OUTPUTS
+        System.Boolean. True when the entry belongs to the mergeable class and is
+        therefore excluded from the comparison. A glob entry is never mergeable
+        unless it equals a configured pattern character for character.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $Entry,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $MergeablePath
+    )
+
+    # Steps one and two are the mandate-read rules verbatim, reused rather than
+    # duplicated: a divergence would silently split two exclusions that share a
+    # vocabulary.
+    if (Test-MandateRead -Entry $Entry -MandateRead $MergeablePath) {
+        return $true
+    }
+
+    # A glob entry that did not match exactly is left alone. Only a concrete path
+    # reaches the anchor-stripping step.
+    if (Test-GlobEntry -Entry $Entry) {
+        return $false
+    }
+
+    # Retest against each anchored pattern with its anchor removed, which is the
+    # only way a root-level file can satisfy an anchored pattern.
+    foreach ($pattern in $MergeablePath) {
+        if (-not $pattern.StartsWith($script:AnyDepthPrefix, [System.StringComparison]::Ordinal)) {
+            continue
+        }
+
+        $stripped = $pattern.Substring($script:AnyDepthPrefix.Length)
+        # A stripped pattern that still carries a wildcard is a glob and is
+        # matched as one; a wildcard-free remainder can only be compared for
+        # ordinal equality.
+        if (Test-GlobEntry -Entry $stripped) {
+            if (Test-GlobMatch -Pattern $stripped -Candidate $Entry) {
+                return $true
+            }
+        } elseif ([string]::Equals($stripped, $Entry, [System.StringComparison]::Ordinal)) {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Get-NonMergeablePathEntry {
+    <#
+    .SYNOPSIS
+        Drop every mechanically-mergeable entry from a collection of paths.
+
+    .DESCRIPTION
+        Port of exclude_mergeable_paths. The caller passes the content by value,
+        so the radius record is never rewritten; only the contention comparison
+        sees the filtered collection.
+
+    .PARAMETER Entry
+        Radius paths entries to filter. An empty collection is accepted.
+
+    .PARAMETER MergeablePath
+        Configured patterns from Get-ConfigMergeablePath. An empty collection
+        excludes nothing, so the returned content equals the input.
+
+    .OUTPUTS
+        System.Object[]. Surviving entries, deduplicated and ordinally sorted.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Object[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Entry,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $MergeablePath
+    )
+
+    $survivor = [System.Collections.Generic.List[string]]::new()
+    foreach ($candidate in $Entry) {
+        # Deduplication and ordering are the sorter's job, matching the Python
+        # port's set-then-sorted construction.
+        if (-not (Test-MergeablePath -Entry $candidate -MergeablePath $MergeablePath)) {
+            $survivor.Add($candidate)
+        }
+    }
+
+    return @(Get-OrdinalSortedEntry -Entry $survivor.ToArray())
+}
+
+function Get-SmallestPathOverlap {
+    <#
+    .SYNOPSIS
+        Return the ordinally smallest overlapping path pair, or $null.
+
+    .DESCRIPTION
+        Port of _smallest_path_overlap. Each overlapping pair is ordered before
+        it is recorded, so the minimum is taken over a set that does not depend
+        on argument order; that is what makes the reported detail symmetric.
+
+    .PARAMETER PathA
+        First radius path collection. An empty collection is accepted.
+
+    .PARAMETER PathB
+        Second radius path collection. An empty collection is accepted.
+
+    .OUTPUTS
+        System.String. The smallest joined pair, or $null when nothing overlaps.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $PathA,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $PathB
+    )
+
+    $detail = [System.Collections.Generic.List[string]]::new()
+    foreach ($entryA in $PathA) {
+        foreach ($entryB in $PathB) {
+            if (-not (Test-EntryOverlap -EntryA $entryA -EntryB $entryB)) {
+                continue
+            }
+            $ordered = if ([string]::CompareOrdinal($entryA, $entryB) -le 0) {
+                @($entryA, $entryB)
+            } else {
+                @($entryB, $entryA)
+            }
+            $detail.Add($ordered -join $script:PairDetailSeparator)
+        }
+    }
+
+    return (Get-OrdinalSmallestEntry -Entry $detail.ToArray())
+}
+
+function Get-SmallestCommonEntry {
+    <#
+    .SYNOPSIS
+        Return the ordinally smallest entry present in both collections.
+
+    .DESCRIPTION
+        Port of _smallest_common. Two empty collections share nothing, so the
+        result is $null and the level contributes no reason.
+
+    .PARAMETER Left
+        First collection. An empty collection is accepted.
+
+    .PARAMETER Right
+        Second collection. An empty collection is accepted.
+
+    .OUTPUTS
+        System.String. The smallest common entry, or $null when there is none.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Left,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Right
+    )
+
+    $rightSet = [System.Collections.Generic.HashSet[string]]::new($Right, [StringComparer]::Ordinal)
+    $common = [System.Collections.Generic.List[string]]::new()
+    foreach ($entry in $Left) {
+        if ($rightSet.Contains($entry)) {
+            $common.Add($entry)
+        }
+    }
+
+    return (Get-OrdinalSmallestEntry -Entry $common.ToArray())
+}
+
+Export-ModuleMember -Function `
+    Get-ConfigMergeablePath, `
+    Test-MergeablePath, `
+    Get-NonMergeablePathEntry, `
+    Get-SmallestPathOverlap, `
+    Get-SmallestCommonEntry