"""Resolve bounded gap handoffs without treating a partial route as a completed family."""
import re


def mentions_gap(value, gap_id):
    return bool(gap_id and isinstance(value, str) and re.search(
        r'(?<![A-Z0-9_-])' + re.escape(gap_id) + r'(?![A-Z0-9_-])', value))


def resolve_gap(seed, finding, delivery):
    item = dict(seed)
    gap_id = item['id']
    finding = finding or {}
    delivery = delivery or {}
    if finding:
        item['status'] = finding.get('status', item.get('status', 'open'))
        item['latestFinding'] = {key: finding.get(key)
                                 for key in ('cycle', 'reason', 'action', 'sourcePaths')}
    completed = [route for route in delivery.get('completedRoutes', [])
                 if mentions_gap(route, gap_id)]
    remaining = [route for route in delivery.get('remainingRoutes', [])
                 if mentions_gap(route, gap_id)]
    blocker = delivery.get('blockingRoute', '')
    if mentions_gap(blocker, gap_id) and blocker not in remaining:
        remaining.append(blocker)
    item['completedSubroutes'] = completed
    item['remainingSubroutes'] = remaining
    # Never override a newer observation with a stale completion reference.
    delivery_is_current = (delivery.get('cycle', 0) or 0) >= (finding.get('cycle', 0) or 0)
    if remaining and delivery_is_current:
        item['status'] = 'open'
        item['statusSource'] = 'explicit_remaining_over_partial_completion'
        item['missing'] = '\n'.join(remaining)
        action = delivery.get('nextAction', '')
        if mentions_gap(action, gap_id):
            item['nextAction'] = action
        item['latestFinding'] = dict(cycle=delivery.get('cycle'), reason=item['missing'],
                                     action=item.get('nextAction'),
                                     sourcePaths=delivery.get('sourcePaths', []))
    elif completed and delivery_is_current:
        item['status'] = 'implemented_unverified'
        item['statusSource'] = 'latest_delivery_completedRoute'
    # A root-authored, exact residual reconciliation may supersede a stale
    # cross-focus integration handoff. Never infer this from a build alone.
    reconciliation = seed.get('residualReconciliation') or {}
    covered = reconciliation.get('remainingSubroutes', [])
    through = reconciliation.get('throughCycle', 0)
    if (item.get('phase', 'implement') == 'implement' and remaining and covered
            and reconciliation.get('reportPath') and reconciliation.get('candidatePath')
            and max(delivery.get('cycle', 0) or 0, finding.get('cycle', 0) or 0) <= through
            and set(remaining) == set(covered)):
        item['supersededRemainingSubroutes'] = remaining
        item['remainingSubroutes'] = []
        item['status'] = 'implemented_unverified'
        item['statusSource'] = 'explicit_residual_reconciliation'
        item['missing'] = ''
        item['nextAction'] = '复用所引候选与源码；新功能缺口需要新的具体交接，未验证不等于需重做。'
        item['latestFinding'] = dict(cycle=through, reason=reconciliation.get('summary', ''),
                                     action=item['nextAction'], sourcePaths=seed.get('sourcePaths', []))
    if item.get('phase') == 'locate' and item.get('status') == 'implemented_unverified':
        # Source reuse/localization is not a production implementation handoff.
        # Retain the observation until an explicit implementation-phase contract
        # exists; never promote based on shared files or a substring match.
        item['status'] = 'open'
        item['statusSource'] = 'location_requires_explicit_disposition'
    return item