@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-replatform/lib/url-redirect-plan.js

@@ -0,0 +1,728 @@
+'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,
+};