Wix Replatform

lib/url-redirect-plan.js

'use strict';

// Deterministic old-URL preservation planning.
//
// Input: the import's URL ledger (current source page addresses), source-authored redirect
// definitions, the website builder's final route manifest, the declared production origins,
// and (optionally) the destination site's current redirect inventory.
// Output: one obligation per known old address, and at most one remote rule per
// site + path + API scope. Nothing here writes, publishes or guesses: a missing or ambiguous
// destination is an obligation with a reason and an operator action, never a best guess.

const crypto = require('node:crypto');

const PLAN_SCHEMA_VERSION = 1;
const MAX_SOURCE_CHAIN_HOPS = 10;
const PLACEHOLDER_BASE = 'http://placeholder.invalid';

function sha256(value) {
  return crypto.createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
}

function stable(value) {
  if (Array.isArray(value)) return value.map(stable);
  if (value && typeof value === 'object') {
    return Object.keys(value).sort().reduce((out, key) => {
      if (value[key] !== undefined) out[key] = stable(value[key]);
      return out;
    }, {});
  }
  return value;
}

function digest(value) {
  return sha256(JSON.stringify(stable(value)));
}

// --- URL parsing ------------------------------------------------------------------------

// Structural parse of an old address. Reserved escapes such as %2F are kept as-is (never
// decoded), hex case is normalized, non-ASCII is percent-encoded, and the query/fragment are
// kept separately so they are never discarded.
function parseAddress(raw, { origins = [] } = {}) {
  if (typeof raw !== 'string' || !raw.trim()) return { ok: false, reason: 'malformed_url' };
  const value = raw.trim();
  if (/%(?![0-9A-Fa-f]{2})/.test(value)) return { ok: false, reason: 'malformed_encoding' };
  let url;
  let absolute = false;
  try {
    if (/^[a-z][a-z0-9+.-]*:/i.test(value)) {
      absolute = true;
      url = new URL(value);
    } else if (value.startsWith('//')) {
      return { ok: false, reason: 'scheme_relative_url' };
    } else if (value.startsWith('/')) {
      url = new URL(value, PLACEHOLDER_BASE);
    } else {
      return { ok: false, reason: 'not_site_relative' };
    }
  } catch {
    return { ok: false, reason: 'malformed_url' };
  }
  if (absolute && url.protocol !== 'http:' && url.protocol !== 'https:') return { ok: false, reason: 'unsupported_scheme' };
  if (url.username || url.password) return { ok: false, reason: 'credentials_in_url' };
  let origin = null;
  if (absolute) {
    const scheme = url.protocol.slice(0, -1);
    const port = url.port ? Number(url.port) : (scheme === 'https' ? 443 : 80);
    origin = `${scheme}://${url.hostname}:${port}`;
    const declared = origins.some((o) => `${o.scheme}://${o.hostname}:${o.effectivePort}` === origin);
    if (!declared) return { ok: true, external: true, origin, href: url.href };
  }
  const pathName = url.pathname.replace(/%[0-9a-f]{2}/gi, (m) => m.toUpperCase());
  return {
    ok: true,
    external: false,
    origin,
    path: pathName,
    conflictPath: conflictPath(pathName),
    query: url.search || '',
    fragment: url.hash || '',
  };
}

// Provider trailing-slash equivalence, applied only to redirect conflict keys.
function conflictPath(pathName) {
  if (pathName.length > 1 && pathName.endsWith('/')) return pathName.replace(/\/+$/, '') || '/';
  return pathName;
}

function isPathPrefix(prefix, candidate) {
  if (prefix === '/') return true;
  return candidate === prefix || candidate.startsWith(`${prefix}/`);
}

// --- remote identity -------------------------------------------------------------------

// The API stores one site-level rule per path; origins are not part of its identity.
function apiScopeOf(rule) {
  return {
    groupRedirect: Boolean(rule && rule.options && rule.options.groupRedirect),
    language: (rule && rule.language) || '*',
  };
}

function remoteRuleKey(siteId, fromConflictPath, scope = { groupRedirect: false, language: '*' }) {
  return `${siteId}|${fromConflictPath}|${scope.groupRedirect ? 'group' : 'exact'}|${scope.language}`;
}

function normalizeInventoryRule(rule) {
  const from = parseAddress(rule.from || '');
  const to = parseAddress(rule.to || '');
  return {
    id: rule.id || null,
    from: rule.from,
    to: rule.to,
    fromConflict: from.ok && !from.external ? from.conflictPath : null,
    toConflict: to.ok && !to.external ? to.conflictPath : null,
    toExternal: Boolean(to.ok && to.external),
    toQuery: to.ok && !to.external ? to.query : '',
    scope: apiScopeOf(rule),
  };
}

function inventoryDigest(inventory) {
  return digest((inventory || []).map((rule) => ({
    id: rule.id || null, from: rule.from, to: rule.to, scope: apiScopeOf(rule),
  })).sort((a, b) => `${a.from}|${a.to}|${a.id}`.localeCompare(`${b.from}|${b.to}|${b.id}`)));
}

// --- planning --------------------------------------------------------------------------

const ENTITY_URL_SKIP = new Set(['not_public', 'source_url_missing']);
// Import-era unresolved rows that a final route manifest is expected to settle. Any other open
// or manual_review row keeps its decision: the obligation stays manual_review, never a write.
const IMPORT_RESOLVABLE_STATUS = new Set(['target_url_missing', 'pending_target_route', 'redirect_required', 'preserved']);
// Only these documented routing uncertainties can be settled by an exact final route.
// Privacy, explicit decisions, missing reasons and all other causes remain restrictions.
const BASE_PATH_ROUTING_REASONS = new Set(['target_route_unknown', 'target_url_missing', 'pending_target_route', 'final_route_missing']);

function addReason(target, code) {
  if (!target.reasonCodes.includes(code)) target.reasonCodes.push(code);
}

function obligationKeyOf(parsed) {
  return `${parsed.path}${parsed.query}${parsed.fragment}`;
}

function buildEntityIndex(ledgerRows) {
  const byConflictPath = new Map();
  for (const row of ledgerRows) {
    if (ENTITY_URL_SKIP.has(row.urlStatus) || !row.sourceRelativeUrl) continue;
    const parsed = parseAddress(row.sourceRelativeUrl);
    if (!parsed.ok || parsed.external) continue;
    const list = byConflictPath.get(parsed.conflictPath) || [];
    if (!list.some((entry) => entry.sourceStableKey === row.sourceStableKey)) list.push(row);
    byConflictPath.set(parsed.conflictPath, list);
  }
  return byConflictPath;
}

function buildRouteIndexes(finalRoutes) {
  const bySourceKey = new Map();
  const byConflictPath = new Map();
  for (const route of (finalRoutes && finalRoutes.routes) || []) {
    const parsed = parseAddress(route.relativeUrl);
    if (!parsed.ok || parsed.external) continue;
    const entry = { ...route, conflictPath: parsed.conflictPath, path: parsed.path, query: parsed.query };
    bySourceKey.set(route.sourceKey, [...(bySourceKey.get(route.sourceKey) || []), entry]);
    byConflictPath.set(parsed.conflictPath, [...(byConflictPath.get(parsed.conflictPath) || []), entry]);
  }
  return { bySourceKey, byConflictPath };
}

function distinctRoutes(routes) {
  const seen = new Map();
  for (const route of routes) seen.set(`${route.targetEntityType}|${route.targetEntityId}|${route.conflictPath}`, route);
  return [...seen.values()];
}

// Follow enabled exact source rules to the current source entity whose page they reach.
function resolveSourceChain(startRule, ctx) {
  const visited = [];
  let rule = startRule;
  for (let hop = 0; hop <= MAX_SOURCE_CHAIN_HOPS; hop += 1) {
    visited.push(rule.ruleKey);
    const dest = parseAddress(rule.destination || '', { origins: ctx.origins });
    if (!dest.ok) return { status: 'manual_review', reason: `destination_${dest.reason}`, edges: visited };
    if (dest.external) return { status: 'manual_review', reason: 'external_destination', edges: visited };
    if (dest.query) return { status: 'manual_review', reason: 'destination_query_semantics', edges: visited };
    const entities = ctx.entityIndex.get(dest.conflictPath) || [];
    if (entities.length > 1) return { status: 'manual_review', reason: 'ambiguous_destination_entity', edges: visited };
    if (entities.length === 1) return { status: 'resolved', entity: entities[0], edges: visited };
    const next = ctx.exactRulesBySource.get(dest.conflictPath) || [];
    if (next.length > 1) return { status: 'manual_review', reason: 'conflicting_source_rules', edges: visited };
    if (next.length === 0) return { status: 'unresolved', reason: 'destination_not_found', edges: visited };
    if (visited.includes(next[0].ruleKey)) return { status: 'manual_review', reason: 'source_rule_cycle', edges: visited };
    rule = next[0];
  }
  return { status: 'manual_review', reason: 'source_chain_too_long', edges: visited };
}

function classifySourceRule(rule) {
  if (!rule.enabled) return 'disabled_rule_excluded';
  if (rule.matchType !== 'exact') return 'unsupported_match_type';
  // Only exact 301 rules can be written (the API takes an unqualified from/to rule). A 308
  // keeps the request method; rewriting it as a 301 would silently change its semantics.
  if (rule.statusCode === 308) return 'status_308_not_writable';
  if (rule.statusCode !== 301) return 'non_permanent_status';
  if (rule.language) return 'language_scoped_rule';
  if (Array.isArray(rule.conditions) && rule.conditions.length) {
    const onlyHost = rule.conditions.every((c) => c && c.type === 'host');
    if (!onlyHost) return 'conditional_rule';
  }
  return null;
}

function hostConditionOrigins(rule, origins) {
  const hosts = (rule.conditions || []).filter((c) => c && c.type === 'host').map((c) => String(c.value || '').toLowerCase());
  if (!hosts.length) return null;
  return origins.filter((o) => hosts.includes(o.hostname));
}

function planRedirects(input) {
  const {
    siteId,
    ledgerRows = [],
    sourceRules = [],
    importedRedirectOutcomes = [],
    coverage = null,
    finalRoutes = null,
    sourceDomains = null,
    targetInventory = null,
    importRedirects = [],
    invalidImportRedirects = [],
    importUnresolved = [],
    basePaths = [],
  } = input;
  const origins = (sourceDomains && sourceDomains.origins) || [];
  const originKeys = origins.map((o) => `${o.scheme}://${o.hostname}:${o.effectivePort}`);
  const deploymentId = finalRoutes ? finalRoutes.deploymentId : null;
  const ruleFindings = [];
  const importedByRule = new Map(importedRedirectOutcomes.map((row) => [row.sourceStableKey, row]));
  const capturedRuleKeys = new Set(sourceRules.filter((rule) => rule.enabled && rule.storage?.kind !== 'export')
    .map((rule) => `${rule.provider}:redirect:${rule.sourceRuleId || rule.stableId}`));
  const inventoryBySource = new Map();
  for (const rule of targetInventory || []) {
    const normalized = normalizeInventoryRule(rule);
    if (!normalized.fromConflict) continue;
    if (!inventoryBySource.has(normalized.fromConflict)) inventoryBySource.set(normalized.fromConflict, []);
    inventoryBySource.get(normalized.fromConflict).push({ rule, normalized });
  }

  // Source-rule inventory: deduplicate identical definitions across providers, keep evidence.
  const activeRules = [];
  const semantic = new Map();
  for (const rule of sourceRules) {
    const exclusion = classifySourceRule(rule);
    if (exclusion === 'disabled_rule_excluded') {
      ruleFindings.push({ ruleKey: rule.ruleKey, provider: rule.provider, disposition: 'excluded', reasonCodes: [exclusion] });
      continue;
    }
    const src = parseAddress(rule.source, { origins });
    const key = src.ok && !src.external ? `${src.conflictPath}${src.query}` : `raw:${rule.source}`;
    const signature = JSON.stringify([key, rule.destination, rule.statusCode, rule.matchType, rule.conditions || null, rule.language || null]);
    if (semantic.has(signature)) {
      semantic.get(signature).duplicateEvidence.push({ ruleKey: rule.ruleKey, provider: rule.provider, storage: rule.storage });
      continue;
    }
    const entry = { ...rule, parsedSource: src, exclusion, duplicateEvidence: [] };
    semantic.set(signature, entry);
    activeRules.push(entry);
  }
  const exactRulesBySource = new Map();
  for (const rule of activeRules) {
    if (rule.exclusion || !rule.parsedSource.ok || rule.parsedSource.external || rule.parsedSource.query) continue;
    const list = exactRulesBySource.get(rule.parsedSource.conflictPath) || [];
    list.push(rule);
    exactRulesBySource.set(rule.parsedSource.conflictPath, list);
  }

  const entityIndex = buildEntityIndex(ledgerRows);
  const entityTypesByKey = new Map();
  for (const row of ledgerRows) {
    if (!row.sourceStableKey || !row.sourceEntityType) continue;
    if (!entityTypesByKey.has(row.sourceStableKey)) entityTypesByKey.set(row.sourceStableKey, new Set());
    entityTypesByKey.get(row.sourceStableKey).add(row.sourceEntityType);
  }
  const routes = buildRouteIndexes(finalRoutes);
  const ctx = { origins, entityIndex, exactRulesBySource };
  const obligations = new Map();

  function obligationFor(parsed, rawUrl) {
    const key = parsed.ok && !parsed.external ? obligationKeyOf(parsed) : `refused:${rawUrl}`;
    if (!obligations.has(key)) {
      obligations.set(key, {
        obligationKey: key,
        originalUrl: rawUrl,
        path: parsed.ok ? parsed.path || null : null,
        conflictPath: parsed.ok ? parsed.conflictPath || null : null,
        query: parsed.ok ? parsed.query || '' : '',
        fragment: parsed.ok ? parsed.fragment || '' : '',
        provenance: [],
        origins: new Set(),
        targets: [],
        disposition: null,
        reasonCodes: [],
        expected: null,
        remoteRuleKey: null,
      });
    }
    return obligations.get(key);
  }

  function attachTarget(ob, entity, via, originSubset) {
    const types = new Set(entityTypesByKey.get(entity.sourceStableKey) || []);
    if (entity.sourceEntityType) types.add(entity.sourceEntityType);
    const resolvedEntity = { ...entity, sourceEntityType: types.size === 1 ? [...types][0] : null };
    ob.targets.push({ entity: resolvedEntity, via, origins: originSubset || originKeys });
    for (const key of originSubset || originKeys) ob.origins.add(key);
  }

  for (const row of ledgerRows) {
    if (ENTITY_URL_SKIP.has(row.urlStatus) || !row.sourceRelativeUrl) continue;
    const parsed = parseAddress(row.sourceRelativeUrl, { origins });
    const ob = obligationFor(parsed, row.sourceRelativeUrl);
    ob.provenance.push({ kind: 'entity_url', sourceStableKey: row.sourceStableKey, sourceEntityType: row.sourceEntityType, urlStatus: row.urlStatus });
    if (!parsed.ok) { addReason(ob, parsed.reason); continue; }
    // A recorded manual decision is never turned into an automatic write.
    if (row.urlStatus === 'manual_review') addReason(ob, 'import_manual_review');
    attachTarget(ob, row, 'entity_url');
  }

  // Replay import-era redirect requirements: each one stays an obligation for its entity even
  // when the ledger no longer lists that address. The final route decides the destination;
  // the import-era target is kept as evidence.
  for (const row of importRedirects) {
    // Source-authored exact rules also have their full semantics in sourceRules. Their
    // import-era relative plan is compatibility evidence, not a second entity owner.
    if (capturedRuleKeys.has(row.sourceStableKey)) continue;
    if (/:redirect:/.test(row.sourceStableKey || '')) {
      const parsed = parseAddress(row.sourceRelativeUrl, { origins });
      const ob = obligationFor(parsed, row.sourceRelativeUrl);
      ob.provenance.push({ kind: 'inactive_import_redirect', sourceStableKey: row.sourceStableKey,
        recordedDestination: row.targetRelativeUrl });
      addReason(ob, 'inactive_import_redirect_plan_requires_reconciliation');
      continue;
    }
    const parsed = parseAddress(row.sourceRelativeUrl, { origins });
    const ob = obligationFor(parsed, row.sourceRelativeUrl);
    ob.provenance.push({ kind: 'import_redirect', sourceStableKey: row.sourceStableKey, importTarget: row.targetRelativeUrl, status: row.status });
    if (!parsed.ok) { addReason(ob, parsed.reason); continue; }
    attachTarget(ob, { sourceStableKey: row.sourceStableKey, sourceEntityType: row.sourceEntityType || null }, 'import_redirect');
  }

  for (const row of invalidImportRedirects) {
    const source = row.sourceRelativeUrl || `redirects.ndjson line ${row.line}: address missing`;
    const parsed = parseAddress(source, { origins });
    const ob = obligationFor(parsed, source);
    ob.provenance.push({ kind: 'import_redirect_rejected', line: row.line, recordedDestination: row.recordedDestination || null, recordedStatus: row.recordedStatus || null });
    addReason(ob, row.reason || 'import_redirect_invalid_row');
    if (!parsed.ok) addReason(ob, parsed.reason);
  }

  // Replay import-era unresolved rows. Resolved rows are evidence only. Open rows that only
  // waited for a final route stay obligations; anything else keeps a manual decision.
  for (const row of importUnresolved) {
    const parsed = parseAddress(row.sourceRelativeUrl, { origins });
    const evidence = { kind: 'import_unresolved', sourceStableKey: row.sourceStableKey, urlStatus: row.urlStatus, status: row.status, reason: row.reason || null };
    if (row.status === 'resolved') {
      const key = parsed.ok && !parsed.external ? obligationKeyOf(parsed) : `refused:${row.sourceRelativeUrl}`;
      if (obligations.has(key)) obligations.get(key).provenance.push(evidence);
      continue;
    }
    const ob = obligationFor(parsed, row.sourceRelativeUrl);
    ob.provenance.push(evidence);
    if (!parsed.ok) { addReason(ob, parsed.reason); continue; }
    if (row.status === 'manual_review' || row.urlStatus === 'manual_review') addReason(ob, 'import_manual_review');
    else if (!IMPORT_RESOLVABLE_STATUS.has(row.urlStatus)) addReason(ob, `import_unresolved_${row.urlStatus}`);
    attachTarget(ob, { sourceStableKey: row.sourceStableKey, sourceEntityType: row.sourceEntityType }, 'import_unresolved');
  }

  for (const row of importedRedirectOutcomes) {
    if (row.disposition !== 'removed_input') continue;
    const parsed = parseAddress(row.originalSource || '', { origins });
    const remoteRuleExists = parsed.ok && !parsed.external &&
      (inventoryBySource.get(parsed.conflictPath) || []).length > 0;
    if (!row.requiresReconciliation && !remoteRuleExists) continue;
    const ob = obligationFor(parsed, row.originalSource || `removed:${row.sourceStableKey}`);
    ob.provenance.push({ kind: 'imported_redirect_removed', sourceStableKey: row.sourceStableKey,
      evidenceDigest: row.evidenceDigest });
    addReason(ob, 'removed_source_rule_requires_reconciliation');
  }

  for (const rule of activeRules) {
    const parsed = rule.parsedSource;
    const ob = obligationFor(parsed, rule.source);
    ob.provenance.push({ kind: 'source_rule', ruleKey: rule.ruleKey, provider: rule.provider,
      storage: rule.storage, stableId: rule.stableId, sourceRuleId: rule.sourceRuleId || rule.stableId,
      duplicates: rule.duplicateEvidence });
    ruleFindings.push({ ruleKey: rule.ruleKey, provider: rule.provider, disposition: 'obligation', obligationKey: ob.obligationKey, duplicates: rule.duplicateEvidence.map((d) => d.ruleKey), reasonCodes: rule.exclusion ? [rule.exclusion] : [] });
    if (!parsed.ok) { addReason(ob, parsed.reason); continue; }
    if (parsed.external) { addReason(ob, 'source_on_undeclared_origin'); continue; }
    if (rule.exclusion) { addReason(ob, rule.exclusion); continue; }
    if (parsed.query) { addReason(ob, 'query_conditional_rule'); continue; }
    const imported = importedByRule.get(`${rule.provider}:redirect:${rule.sourceRuleId || rule.stableId}`);
    const target = parseAddress(imported?.resolvedTarget || rule.destination || '', { origins });
    if (target.ok && target.external) {
      if (ob.externalTarget && ob.externalTarget !== rule.destination) {
        addReason(ob, 'conflicting_source_rules');
        continue;
      }
      if (!imported || imported.originalTarget !== rule.destination || imported.destinationKind !== 'external') {
        addReason(ob, 'external_destination');
        addReason(ob, 'external_target_audit_missing_or_stale');
        continue;
      }
      if (ob.targets.length || ob.provenance.some((item) => item.kind !== 'source_rule')) {
        addReason(ob, 'source_address_ownership_conflict');
        continue;
      }
      ob.externalTarget = imported.resolvedTarget || imported.originalTarget;
      ob.externalOriginalTarget = imported.originalTarget;
      ob.externalDisposition = imported.disposition;
      ob.externalEvidenceDigest = imported.evidenceDigest;
      continue;
    }
    const subset = hostConditionOrigins(rule, origins);
    if (subset && subset.length === 0) { addReason(ob, 'host_condition_undeclared'); continue; }
    const chain = resolveSourceChain(rule, ctx);
    ob.provenance[ob.provenance.length - 1].chain = chain.edges;
    if (chain.status !== 'resolved') { addReason(ob, chain.reason); ob.chainStatus = chain.status; continue; }
    attachTarget(ob, chain.entity, 'source_rule', subset ? subset.map((o) => `${o.scheme}://${o.hostname}:${o.effectivePort}`) : null);
  }

  // Import-era base-path decisions: a base path held for manual review, or recorded as not
  // public, is evaluated by reason for each matching occurrence. Unknown type cannot bypass it.
  const heldBasePaths = basePaths
    .filter((entry) => entry.status === 'manual_review' || entry.public === false)
    .map((entry) => ({ entry, parsed: parseAddress(entry.sourceBasePath) }));

  // Resolve each obligation's intended final page and whether a redirect is needed.
  for (const ob of obligations.values()) {
    if (ob.externalTarget) {
      if (ob.reasonCodes.length || !origins.length || ob.path === '/') {
        ob.disposition = 'manual_review';
        if (!origins.length) addReason(ob, 'origins_not_declared');
        if (ob.path === '/') addReason(ob, 'source_root');
      } else if (!['external_pending_execution', 'external_redirect_automation_unavailable'].includes(ob.externalDisposition)) {
        ob.disposition = 'manual_review';
        addReason(ob, ob.externalDisposition || 'external_target_not_ready');
      } else {
        ob.disposition = 'external_redirect';
        // The same-site API writer never accepts an external destination. A matching
        // inventory row is setup evidence only; public source verification is separate.
        const atSource = inventoryBySource.get(ob.conflictPath) || [];
        const matching = atSource.filter(({ rule, normalized }) =>
          !normalized.scope.groupRedirect && normalized.scope.language === '*' &&
          rule.to === ob.externalTarget);
        ob.externalSetup = matching.length === 1 ?
          { remoteId: matching[0].rule.id || null, target: matching[0].rule.to } : null;
        if (matching.length > 1) { ob.disposition = 'manual_review'; addReason(ob, 'external_setup_conflict'); }
        if (atSource.some((entry) => !matching.includes(entry))) {
          ob.disposition = 'manual_review'; addReason(ob, 'existing_rule_conflict'); ob.externalSetup = null;
        }
      }
      continue;
    }
    ob.origins = [...ob.origins].sort();
    const routingHolds = [];
    for (const { entry, parsed } of heldBasePaths) {
      const unknownType = !ob.targets.length || ob.targets.some((target) => !target.entity.sourceEntityType);
      if (!unknownType && !ob.targets.some((target) => target.entity.sourceEntityType === entry.sourceEntityType)) continue;
      if (!ob.conflictPath) continue;
      if (!parsed.ok || parsed.external) { addReason(ob, 'base_path_unparseable'); continue; }
      if (!isPathPrefix(parsed.conflictPath, ob.conflictPath)) continue;
      const reasons = Array.isArray(entry.reasonCodes) && entry.reasonCodes.every((code) => typeof code === 'string' && code.trim()) ? entry.reasonCodes : [];
      const hold = { kind: 'base_path_hold', sourceBasePath: entry.sourceBasePath,
        sourceEntityType: entry.sourceEntityType, reasonCodes: reasons, resolution: 'unresolved' };
      ob.provenance.push(hold);
      if (entry.public === false) { addReason(ob, 'base_path_not_public'); continue; }
      if (unknownType) { addReason(ob, 'base_path_entity_type_unknown'); continue; }
      if (!reasons.length) { addReason(ob, 'base_path_hold_reason_missing'); continue; }
      if (!reasons.every((reason) => BASE_PATH_ROUTING_REASONS.has(reason))) {
        addReason(ob, 'base_path_manual_review'); continue;
      }
      // Resolve only this occurrence, and only after the normal exact-route/ownership checks.
      routingHolds.push(hold);
    }
    if (!origins.length) addReason(ob, 'origins_not_declared');
    if (ob.path === '/' || ob.conflictPath === '/') addReason(ob, 'source_root');
    if (ob.reasonCodes.length) {
      const unresolvedOnly = ob.reasonCodes.every((code) => code === 'destination_not_found' || code === 'origins_not_declared');
      ob.disposition = unresolvedOnly ? 'unresolved' : 'manual_review';
      continue;
    }
    if (!finalRoutes) { ob.disposition = 'pending_website_build'; addReason(ob, 'final_routes_missing'); continue; }
    const entityKeys = [...new Set(ob.targets.map((t) => t.entity.sourceStableKey))];
    if (entityKeys.length !== 1) { ob.disposition = 'manual_review'; addReason(ob, 'conflicting_intended_entities'); continue; }
    const candidates = distinctRoutes(routes.bySourceKey.get(entityKeys[0]) || []);
    if (candidates.length === 0) { ob.disposition = 'unresolved'; addReason(ob, 'final_route_missing'); continue; }
    if (candidates.length > 1) { ob.disposition = 'manual_review'; addReason(ob, 'ambiguous_final_route'); continue; }
    const route = candidates[0];
    // The old address's query is part of what it means. A final route that carries its own,
    // different query leaves the expected result undefined, so a person decides.
    if (ob.query && route.query && ob.query !== route.query) { ob.disposition = 'manual_review'; addReason(ob, 'query_semantics_conflict'); continue; }
    ob.expected = {
      sourceKey: route.sourceKey,
      targetEntityType: route.targetEntityType,
      targetEntityId: route.targetEntityId,
      relativeUrl: route.relativeUrl,
      conflictPath: route.conflictPath,
      query: route.query || ob.query || '',
      pageMarker: route.pageMarker,
    };
    const owners = distinctRoutes(routes.byConflictPath.get(ob.conflictPath) || []);
    if (owners.some((owner) => owner.targetEntityId !== route.targetEntityId || owner.targetEntityType !== route.targetEntityType)) {
      ob.disposition = 'manual_review';
      addReason(ob, 'ownership_conflict');
      continue;
    }
    for (const hold of routingHolds) {
      hold.resolution = 'resolved_by_exact_final_route';
      hold.evidence = { sourceStableKey: route.sourceKey, targetEntityType: route.targetEntityType,
        targetEntityId: route.targetEntityId, relativeUrl: route.relativeUrl, deploymentId };
    }
    if (owners.length || route.conflictPath === ob.conflictPath) {
      ob.disposition = 'direct';
      continue;
    }
    ob.disposition = 'redirect';
  }

  // Fold per-origin intent into remote rules: one site-level rule per path and API scope.
  const remote = new Map();
  for (const ob of obligations.values()) {
    if (!ob.conflictPath || ob.conflictPath === '/' || !origins.length) continue;
    if (!['redirect', 'direct'].includes(ob.disposition)) continue;
    const key = remoteRuleKey(siteId, ob.conflictPath);
    if (!remote.has(key)) remote.set(key, { ruleKey: key, fromConflict: ob.conflictPath, from: ob.path, intents: [], obligationKeys: [] });
    const entry = remote.get(key);
    entry.obligationKeys.push(ob.obligationKey);
    for (const originKeyValue of originKeys) {
      const serves = ob.targets.some((t) => t.origins.includes(originKeyValue));
      entry.intents.push({
        origin: originKeyValue,
        obligationKey: ob.obligationKey,
        need: !serves ? 'none' : ob.disposition === 'direct' ? 'no_redirect' : ob.expected.relativeUrl,
      });
    }
  }

  const remoteRules = [];
  for (const entry of remote.values()) {
    const perOrigin = new Map();
    for (const intent of entry.intents) {
      if (!perOrigin.has(intent.origin)) perOrigin.set(intent.origin, new Set());
      perOrigin.get(intent.origin).add(intent.need);
    }
    // An origin with no obligation at this path has no requirement; an origin whose only
    // requirement is "none" while another needs a redirect blocks the whole key.
    const needs = new Set();
    const conflicts = [];
    for (const [origin, set] of perOrigin) {
      const concrete = [...set].filter((need) => need !== 'none');
      // A 'none' beside a concrete need means a second obligation at this path serves the
      // origin; only an origin with no concrete need contributes 'none'.
      if (concrete.length === 0) needs.add('none');
      else if (concrete.length > 1) conflicts.push({ origin, reason: 'conflicting_targets' });
      else needs.add(concrete[0]);
    }
    const rule = {
      ruleKey: entry.ruleKey,
      from: entry.from,
      fromConflict: entry.fromConflict,
      to: null,
      origins: [...perOrigin.keys()].sort(),
      obligationKeys: [...new Set(entry.obligationKeys)].sort(),
      disposition: null,
      reasonCodes: [],
      perOriginConflicts: conflicts,
    };
    if (conflicts.length) {
      rule.disposition = 'manual_review';
      rule.reasonCodes.push('origin_intent_conflict');
    } else if (needs.size > 1) {
      rule.disposition = 'manual_review';
      rule.reasonCodes.push('origin_intent_conflict');
      for (const [origin, set] of perOrigin) rule.perOriginConflicts.push({ origin, reason: `needs:${[...set].join(',')}` });
    } else {
      const only = [...needs][0];
      if (only === 'no_redirect' || only === 'none') {
        rule.disposition = 'no_write';
        rule.reasonCodes.push('route_serves_original_address');
      } else {
        rule.to = only;
        rule.disposition = 'write_candidate';
      }
    }
    remoteRules.push(rule);
  }

  // Whole-candidate-set checks: a destination that is itself a planned source would be a chain.
  const candidateSources = new Set(remoteRules.filter((r) => r.disposition === 'write_candidate').map((r) => r.fromConflict));
  for (const rule of remoteRules) {
    if (rule.disposition !== 'write_candidate') continue;
    const to = parseAddress(rule.to);
    rule.toConflict = to.ok ? to.conflictPath : null;
    if (!to.ok || to.external) { rule.disposition = 'manual_review'; rule.reasonCodes.push('invalid_destination'); continue; }
    if (to.conflictPath === rule.fromConflict) { rule.disposition = 'manual_review'; rule.reasonCodes.push('self_loop'); continue; }
    if (candidateSources.has(to.conflictPath)) { rule.disposition = 'manual_review'; rule.reasonCodes.push('candidate_chain'); }
  }

  const preflight = targetInventory ? preflightAgainstInventory(remoteRules, targetInventory, siteId) : null;
  const effectiveRules = preflight ? preflight.rules : remoteRules;

  // Blocked remote rules block every obligation they serve.
  const byRemote = new Map(effectiveRules.map((rule) => [rule.ruleKey, rule]));
  for (const ob of obligations.values()) {
    if (!ob.conflictPath) continue;
    const key = remoteRuleKey(siteId, ob.conflictPath);
    const rule = byRemote.get(key);
    if (!rule) continue;
    ob.remoteRuleKey = key;
    if (rule.disposition === 'manual_review' && ['redirect', 'direct'].includes(ob.disposition)) {
      if (ob.disposition === 'redirect' || rule.reasonCodes.includes('origin_intent_conflict')) {
        ob.disposition = 'manual_review';
        for (const code of rule.reasonCodes) addReason(ob, code);
      }
    }
  }

  const obligationList = [...obligations.values()].sort((a, b) => a.obligationKey.localeCompare(b.obligationKey));
  // The plan identity covers its inputs, not the live inventory: inventory drift is caught by
  // the apply-time preflight, while a changed ledger, rule set, route manifest, deployment or
  // origin list is a different plan.
  const planDigest = digest({
    siteId,
    deploymentId,
    origins: originKeys,
    ledger: ledgerRows.map((row) => [row.sourceStableKey, row.sourceRelativeUrl, row.sourceEntityType || null, row.urlStatus]),
    sourceRules: sourceRules.map((rule) => [rule.ruleKey, rule.enabled, rule.matchType, rule.source, rule.destination, rule.statusCode, rule.conditions || null, rule.language || null]),
    importedRedirectOutcomes: importedRedirectOutcomes.map((row) => [row.sourceStableKey, row.originalTarget, row.disposition, row.evidenceDigest]),
    routes: ((finalRoutes && finalRoutes.routes) || []).map((r) => [r.sourceKey, r.targetEntityType, r.targetEntityId, r.relativeUrl, r.pageMarker]),
    importRedirects: importRedirects.map((row) => [row.sourceStableKey, row.sourceRelativeUrl, row.sourceEntityType || null, row.targetRelativeUrl, row.status]),
    invalidImportRedirects: invalidImportRedirects.map((row) => [row.line, row.sourceRelativeUrl, row.reason, row.recordedDestination || null, row.recordedStatus || null]),
    importUnresolved: importUnresolved.map((row) => [row.sourceStableKey, row.sourceRelativeUrl, row.sourceEntityType || null, row.urlStatus, row.status]),
    basePaths: basePaths.map((entry) => [entry.sourceEntityType, entry.sourceBasePath, entry.sourceUrlPattern, entry.public, entry.status, entry.reasonCodes || null]),
  });
  const coverageRows = (coverage && coverage.providers) || [];
  return {
    schemaVersion: PLAN_SCHEMA_VERSION,
    planDigest,
    siteId,
    deploymentId,
    productionHostname: sourceDomains ? sourceDomains.productionHostname : null,
    origins: originKeys,
    websiteBuilt: Boolean(finalRoutes),
    coverage: coverageRows,
    coverageComplete: coverageRows.length > 0 && coverageRows.every((row) => row.status === 'extracted' || row.status === 'confirmed_empty'),
    obligations: obligationList.map((ob) => ({
      obligationKey: ob.obligationKey,
      originalUrl: ob.originalUrl,
      path: ob.path,
      query: ob.query,
      fragment: ob.fragment,
      origins: ob.origins.length ? ob.origins : originKeys,
      disposition: ob.disposition,
      reasonCodes: ob.reasonCodes,
      expected: ob.expected,
      externalTarget: ob.externalTarget || null,
      externalOriginalTarget: ob.externalOriginalTarget || null,
      externalDisposition: ob.externalDisposition || null,
      externalEvidenceDigest: ob.externalEvidenceDigest || null,
      externalSetup: ob.externalSetup || null,
      remoteRuleKey: ob.remoteRuleKey,
      provenance: ob.provenance,
    })),
    // Pre-inventory candidates: apply always re-runs the preflight against a fresh inventory.
    remoteRules,
    preflight,
    sourceRuleFindings: ruleFindings,
  };
}

// Compare candidate rules against the site's existing redirects. Exact semantic match is
// `already_present`; anything that could replace, delete or overlap an existing rule is
// `manual_review` with zero writes.
function preflightAgainstInventory(remoteRules, inventory, siteId) {
  const existing = (inventory || []).map(normalizeInventoryRule);
  const rules = remoteRules.map((rule) => ({ ...rule, reasonCodes: [...rule.reasonCodes] }));
  for (const rule of rules) {
    if (rule.disposition !== 'write_candidate') continue;
    const toConflict = rule.toConflict || parseAddress(rule.to).conflictPath;
    const block = (code) => { rule.disposition = 'manual_review'; if (!rule.reasonCodes.includes(code)) rule.reasonCodes.push(code); };
    for (const ex of existing) {
      if (!ex.fromConflict) continue;
      const exKey = remoteRuleKey(siteId, ex.fromConflict, ex.scope);
      if (exKey === rule.ruleKey) {
        if (!ex.toExternal && ex.toConflict === toConflict && !ex.toQuery) {
          rule.disposition = 'already_present';
          rule.remoteId = ex.id;
        } else block('existing_rule_conflict');
        continue;
      }
      if (ex.fromConflict === rule.fromConflict && ex.scope.language !== '*') block('language_overlap');
      if (ex.fromConflict === rule.fromConflict && ex.scope.groupRedirect) block('group_overlap');
      if (ex.scope.groupRedirect && ex.fromConflict !== rule.fromConflict && (isPathPrefix(ex.fromConflict, rule.fromConflict) || isPathPrefix(rule.fromConflict, ex.fromConflict))) block('group_overlap');
      if (ex.fromConflict === toConflict) block('destination_is_existing_source');
      if (ex.scope.groupRedirect && isPathPrefix(ex.fromConflict, toConflict)) block('destination_under_group_rule');
      if (ex.toConflict && ex.toConflict === rule.fromConflict) block('creates_chain_with_existing_rule');
    }
  }
  return { rules, inventoryDigest: inventoryDigest(inventory) };
}

module.exports = {
  PLAN_SCHEMA_VERSION,
  MAX_SOURCE_CHAIN_HOPS,
  parseAddress,
  conflictPath,
  remoteRuleKey,
  apiScopeOf,
  inventoryDigest,
  normalizeInventoryRule,
  planRedirects,
  preflightAgainstInventory,
  digest,
};