@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/lib/internal-link-reconciliation.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+
+function exactHosts(hosts) {
+  return new Set((hosts || []).map((host) => new URL(`https://${host}`).host.toLowerCase()));
+}
+
+function classifyNavigation(value, containingUrl, { sourceHosts = [], destinationHosts = [] } = {}) {
+  if (typeof value !== 'string' || !value) return { kind: 'invalid' };
+  if (/^(?:javascript|data|mailto|tel):/i.test(value)) return { kind: 'action', value };
+  let url;
+  try { url = new URL(value, containingUrl); } catch { return { kind: 'invalid', value }; }
+  if (!['http:', 'https:'].includes(url.protocol)) return { kind: 'external', value };
+  const hosts = exactHosts([...sourceHosts, ...destinationHosts]);
+  if (!hosts.has(url.host.toLowerCase())) return { kind: 'external', value };
+  const path = `${url.pathname}${url.search}${url.hash}`;
+  const stateful = /^\/(?:wp-admin|wp-login|account\/login|checkout\/order-pay)(?:\/|$)/i.test(url.pathname)
+    || [...url.searchParams.keys()].some((key) => /^(?:nonce|_wpnonce|token|auth|session|add-to-cart|remove_item|order-pay)$/i.test(key));
+  if (stateful) return { kind: 'stateful', original: value, path, host: url.host.toLowerCase() };
+  return { kind: 'internal', original: value, path, lookupPath: `${url.pathname}${url.search}`, host: url.host.toLowerCase(), fragmentOnly: value.startsWith('#') };
+}
+
+function occurrenceId({ sourceFile, sourceRecordId = '', field, location, original }) {
+  return createHash('sha256').update([sourceFile, sourceRecordId, field, location, original].join('\0')).digest('hex').slice(0, 24);
+}
+
+function verifiedDestination(row) {
+  if (!row || !row.targetRecordId || !row.path || !row.pageFamily || !row.deploymentId || !row.routeRevision || !row.checkedAt || row.identityMatched !== true || row.rendered !== true) {
+    throw new Error('verified destination requires target identity, served path and current deployment evidence');
+  }
+  if (!row.path.startsWith('/') || row.path.startsWith('//')) throw new Error('verified path must be root-relative');
+  return row;
+}
+
+function writerGuard(field, activeWriters, recordType) {
+  if (recordType === 'blog-post') return { ok: false, reason: 'blog-writer-integration-pending' };
+  if (!activeWriters || activeWriters.complete !== true || !Array.isArray(activeWriters.writers) || activeWriters.writers.some((row) => !row || !Array.isArray(row.fields))) {
+    return { ok: false, reason: 'unknown-writer-contract' };
+  }
+  const touching = activeWriters.writers.filter((row) => row.fields.includes(field));
+  if (touching.length !== 1 || touching[0].writer !== 'internal-link-reconciler' || touching[0].compatible !== true || touching[0].runsAfter !== 'post-frontend-verification') {
+    return { ok: false, reason: 'incompatible-writer-contract' };
+  }
+  return { ok: true };
+}
+
+// Mutation is per logical record. A guarded field may proceed while another field is held.
+// The adapter owns native field serialization; this function never edits blog post fields.
+async function reconcileRecord({ recordId, recordType, fields, destinations, activeWriters, destinationState, adapter, journal, intentKey = null, priorIntentKeys = [] }) {
+  if (!adapter || typeof adapter.patchField !== 'function' || !journal || !recordId) throw new Error('record, structured patch adapter and journal required');
+  if (destinationState !== 'migration-not-live') throw new Error('content writes require a confirmed non-live migration destination');
+  const blocked = [];
+  const eligible = [];
+  for (const field of fields) {
+    const guard = writerGuard(`${recordType}:${field.name}`, activeWriters, recordType);
+    if (!guard.ok) { blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: guard.reason }); continue; }
+    const destination = field.patches ? null : destinations[field.destinationId];
+    if (field.patches) {
+      if (!field.patches.length || field.patches.some((patch) => {
+        try { verifiedDestination(destinations[patch.destinationId]); return false; } catch { return true; }
+      })) {
+        blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'destination-unverified' }); continue;
+      }
+      eligible.push({ field, destination: null });
+      continue;
+    }
+    if (field.unresolvedNormalization === true) {
+      if (!destination || !destination.path || !destination.path.startsWith('/') || destination.path.startsWith('//')) {
+        blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'unresolved-original-path-invalid' }); continue;
+      }
+    } else {
+      try { verifiedDestination(destination); } catch {
+        blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'destination-unverified' }); continue;
+      }
+    }
+    eligible.push({ field, destination });
+  }
+  if (!eligible.length) return { recordId, blocked, written: [] };
+  const current = await adapter.read(recordId);
+  if (!current || !current.revision) throw new Error('content read needs revision');
+  if (intentKey && typeof journal.findCompleted === 'function') {
+    const completed = await journal.findCompleted(recordId, intentKey);
+    if (completed) {
+      if (!completed.changes.every((change) => isDeepStrictEqual(current.fields[change.name], change.after))) throw new Error('completed link repair conflicts with changed content');
+      return { recordId, blocked, written: completed.changes.map((change) => change.name), resumed: true, contentRevision: current.revision };
+    }
+  }
+  if (intentKey && typeof journal.findOpen === 'function') {
+    const open = await journal.findOpen(recordId, intentKey);
+    if (open) {
+      if (open.changes.every((change) => isDeepStrictEqual(current.fields[change.name], change.after))) {
+        await journal.complete(open);
+        return { recordId, blocked, written: open.changes.map((change) => change.name), resumed: true, contentRevision: current.revision };
+      }
+      if (current.revision !== open.baseRevision) throw new Error('uncertain write conflicts with changed content');
+      await adapter.write(recordId, Object.fromEntries(open.changes.map((change) => [change.name, change.after])), current.revision);
+      const readBack = await adapter.read(recordId);
+      if (!open.changes.every((change) => isDeepStrictEqual(readBack.fields[change.name], change.after))) throw new Error('content write read-back mismatch');
+      await journal.complete(open);
+      return { recordId, blocked, written: open.changes.map((change) => change.name), resumed: true, contentRevision: readBack.revision };
+    }
+  }
+  // A frontend redeploy invalidates served-link evidence, not a completed content write.
+  // Reuse the exact journaled after-image only when it still matches the current record.
+  if (typeof journal.findCompleted === 'function') {
+    for (const priorKey of priorIntentKeys) {
+      const completed = await journal.findCompleted(recordId, priorKey);
+      if (!completed || !eligible.every(({ field }) => completed.changes.some((change) =>
+        change.name === field.name && field.occurrenceIds.every((id) => change.occurrenceIds.includes(id)))) ||
+          !completed.changes.every((change) => isDeepStrictEqual(current.fields[change.name], change.after))) continue;
+      return { recordId, blocked, written: eligible.map(({ field }) => field.name), resumed: true, contentRevision: current.revision, priorIntentKey: priorKey };
+    }
+  }
+  for (const { field } of eligible) {
+    if (field.expectedRevision && field.expectedRevision !== current.revision) {
+      blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'concurrent-edit' });
+    }
+  }
+  if (blocked.some((row) => row.reason === 'concurrent-edit')) return { recordId, blocked, written: [] };
+  const intended = eligible.map(({ field, destination }) => {
+    const baseValue = field.baseValue === undefined ? current.fields[field.name] : field.baseValue;
+    let patch;
+    if (field.patches) {
+      const ordered = [...field.patches].sort((a, b) => {
+        const offset = (row) => Number(/char:(\d+)/.exec(row.occurrence.location || '')?.[1] || 0);
+        return offset(b) - offset(a);
+      });
+      patch = { value: baseValue, preservedUnrelated: true, changedLocations: [] };
+      for (const row of ordered) {
+        const next = adapter.patchField(patch.value, row.occurrence, row.path);
+        if (!next || next.preservedUnrelated !== true || !next.changedLocations?.length) throw new Error(`field ${field.name} lacks a verified structured link patch`);
+        patch = { value: next.value, preservedUnrelated: true, changedLocations: [...patch.changedLocations, ...next.changedLocations] };
+      }
+    } else patch = adapter.patchField(baseValue, field, destination.path);
+    if (!patch || patch.preservedUnrelated !== true || !Array.isArray(patch.changedLocations) || !patch.changedLocations.length) {
+      throw new Error(`field ${field.name} lacks a verified structured link patch`);
+    }
+    return { name: field.name, before: baseValue, after: patch.value, occurrenceIds: field.occurrenceIds, changedLocations: patch.changedLocations };
+  });
+  const attempt = intentKey ? null : await journal.find(recordId, intended);
+  if (attempt && intended.every((change) => isDeepStrictEqual(current.fields[change.name], change.after))) {
+    await journal.complete(attempt);
+    return { recordId, blocked, written: intended.map((change) => change.name), resumed: true };
+  }
+  if (attempt && current.revision !== attempt.baseRevision) throw new Error('uncertain write conflicts with changed content');
+  const changes = [];
+  for (const { field, destination } of eligible) {
+    if (!isDeepStrictEqual(current.fields[field.name], field.baseValue === undefined ? current.fields[field.name] : field.baseValue)) {
+      blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'concurrent-edit' });
+    } else {
+      const intendedChange = intended.find((row) => row.name === field.name);
+      if (!isDeepStrictEqual(current.fields[field.name], intendedChange.after)) changes.push(intendedChange);
+    }
+  }
+  if (!changes.length) return { recordId, blocked, written: [] };
+  const started = attempt || await journal.start(recordId, current.revision, changes, intentKey);
+  await adapter.write(recordId, Object.fromEntries(changes.map((change) => [change.name, change.after])), current.revision);
+  const readBack = await adapter.read(recordId);
+  if (!changes.every((change) => isDeepStrictEqual(readBack.fields[change.name], change.after))) throw new Error('content write read-back mismatch');
+  await journal.complete(started);
+  return { recordId, blocked, written: changes.map((change) => change.name), contentRevision: readBack.revision };
+}
+
+module.exports = { classifyNavigation, occurrenceId, verifiedDestination, writerGuard, reconcileRecord };

package/skills/wix-replatform/lib/link-audit.js

@@ -0,0 +1,173 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const RELATIVE_PATH = 'state/url-preservation/link-audit.json';
+const UNRESOLVED_REASONS = new Set([
+  'target-not-imported', 'source-broken', 'collision', 'ambiguous-target', 'unsupported-family',
+]);
+const INTEGRATION_PROMPT = 'Resume internal-link writer integration for the listed audit records: establish exclusive ownership of each content field, keep source-origin URL rewriting limited to non-content configuration, and connect the dedicated blog-post link writer to verified destinations and a checkpointed post-frontend update, publish and read-back phase. Run the scoped compatibility and end-to-end checks, resume only compatible writers, and return the refreshed link audit, report and handoff. If a required writer or lifecycle is unavailable, keep the affected repairs pending and report the missing contract.';
+const ROUTE_PROMPT = "Resume app page routing for the listed page families and original paths: inspect the destination's current route configuration, apply the supported source-matching configuration, record any unsupported family with its actual Wix destination and redirect requirement, and return the refreshed capability matrix, configuration read-back and report.";
+const UNRESOLVED_PROMPT = 'Resume app routing and internal-link reconciliation for the listed audit occurrence IDs; obtain missing capture/adapter access, resolve intended targets, apply approved repairs, and return the refreshed link audit and report.';
+const PENDING_PROMPT = 'Run the post-frontend routing and link verification step for this migration: confirm the frontend deployment origin and mount path, read back generated entity URLs, run the read-only calibration and budget estimate, and only within the approved budget check the per-family samples and verify and repair the stored destinations, and return the refreshed link audit and report.';
+const UNAVAILABLE_PROMPT = 'Rerun internal-link verification for the listed audit occurrence and destination IDs against the current Wix deployment: confirm deployment origin, mount path, permissions and safe session fixtures, re-check route identity, rendered links, fragments and actions, and return the refreshed link audit and report.';
+const BUDGET_PROMPT = 'Present the recorded link counts, estimate and budget to the migration owner and request a decision to continue, reduce scope or stop. Then resume verification and repair for the listed audit within the approved limit and return the refreshed link audit and report.';
+
+function auditPath(projectDir) {
+  return path.join(projectDir, RELATIVE_PATH);
+}
+
+function nonempty(value, label) {
+  if (typeof value !== 'string' || !value) throw new Error(`${label} must be a non-empty string`);
+  return value;
+}
+
+function unique(values, label) {
+  if (!Array.isArray(values) || values.some((value) => typeof value !== 'string' || !value)) {
+    throw new Error(`${label} must be an array of non-empty strings`);
+  }
+  if (new Set(values).size !== values.length) throw new Error(`${label} contains duplicates`);
+}
+
+// The queues partition navigation occurrences. A missing or duplicated occurrence must never
+// disappear from cutover just because a backend import succeeded.
+function validateLinkAudit(audit) {
+  if (!audit || audit.schemaVersion !== 1) throw new Error('link audit schemaVersion must be 1');
+  if (audit.postDnsStatus === 'verified' && (!audit.postDnsEvidence || !audit.postDnsEvidence.host || !audit.postDnsEvidence.checkedAt || audit.postDnsEvidence.wixIdentityMatched !== true)) {
+    throw new Error('verified post-DNS status requires public-host Wix identity evidence');
+  }
+  const occurrences = audit.occurrences || [];
+  const pending = audit.pendingDestinations || [];
+  const unresolved = audit.unresolved || [];
+  const outcomes = audit.outcomes || [];
+  const ids = new Set();
+  for (const row of occurrences) {
+    nonempty(row.id, 'occurrence.id');
+    if (ids.has(row.id)) throw new Error(`duplicate occurrence ${row.id}`);
+    ids.add(row.id);
+  }
+  const assigned = new Map();
+  const assign = (id, location) => {
+    if (!ids.has(id)) throw new Error(`${location} references missing occurrence ${id}`);
+    if (assigned.has(id)) throw new Error(`occurrence ${id} appears in both ${assigned.get(id)} and ${location}`);
+    assigned.set(id, location);
+  };
+  for (const row of pending) {
+    nonempty(row.id, 'pending.id');
+    nonempty(row.targetRecordId, 'pending.targetRecordId');
+    nonempty(row.expectedPath, 'pending.expectedPath');
+    if (!row.expectedPath.startsWith('/') || row.expectedPath.startsWith('//')) throw new Error('pending.expectedPath must be root-relative');
+    nonempty(row.pageFamily, 'pending.pageFamily');
+    unique(row.occurrenceIds, 'pending.occurrenceIds');
+    row.occurrenceIds.forEach((id) => assign(id, `pending ${row.id}`));
+  }
+  for (const row of unresolved) {
+    nonempty(row.id, 'unresolved.id');
+    if ('expectedPath' in row) throw new Error('unresolved entries cannot carry expectedPath');
+    if (!UNRESOLVED_REASONS.has(row.reason)) throw new Error(`invalid unresolved reason ${row.reason}`);
+    unique(row.occurrenceIds, 'unresolved.occurrenceIds');
+    row.occurrenceIds.forEach((id) => assign(id, `unresolved ${row.id}`));
+  }
+  for (const row of outcomes) {
+    nonempty(row.occurrenceId, 'outcome.occurrenceId');
+    nonempty(row.status, 'outcome.status');
+    assign(row.occurrenceId, 'outcome');
+  }
+  for (const id of ids) if (!assigned.has(id)) throw new Error(`unaccounted navigation occurrence ${id}`);
+  for (const row of audit.writerIntegrations || []) {
+    nonempty(row.field, 'writerIntegration.field');
+    nonempty(row.status, 'writerIntegration.status');
+    unique(row.occurrenceIds || [], 'writerIntegration.occurrenceIds');
+    for (const id of row.occurrenceIds || []) if (!ids.has(id)) throw new Error(`writer integration references missing occurrence ${id}`);
+  }
+  return audit;
+}
+
+async function readLinkAudit(projectDir) {
+  try {
+    return validateLinkAudit(JSON.parse(await fs.readFile(auditPath(projectDir), 'utf8')));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function writeLinkAudit(projectDir, audit) {
+  validateLinkAudit(audit);
+  const target = auditPath(projectDir);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify(audit, null, 2)}\n`);
+    await fs.rename(temporary, target);
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+  return target;
+}
+
+function linkOperatorActions(audit) {
+  if (!audit) return [];
+  validateLinkAudit(audit);
+  const actions = [];
+  const pendingWriter = (audit.writerIntegrations || []).filter((row) => row.status === 'pending');
+  if (pendingWriter.length) {
+    actions.push({
+      code: 'link_writer_integration', severity: 'high',
+      action: `Requires Import Operator. ${INTEGRATION_PROMPT} Affected fields: ${pendingWriter.map((row) => row.field).join(', ')}. Evidence: ${RELATIVE_PATH}.`,
+      deadlineReason: 'After compatible writers and lifecycle are available, before DNS; destination checks alone do not complete content repair.',
+      entity: 'internal-links', affectedCount: new Set(pendingWriter.flatMap((row) => row.occurrenceIds)).size,
+    });
+  }
+  const ownershipGaps = audit.unresolved.filter((row) => row.detail !== 'fragment-anchor-unverified');
+  if (ownershipGaps.length) actions.push({
+    code: 'unresolved_internal_links', severity: 'high',
+    action: `Requires Import Operator. ${UNRESOLVED_PROMPT} Evidence: ${RELATIVE_PATH}; ambiguous ownership needs a human decision.`,
+    deadlineReason: 'Before website handoff; unresolved navigation can open missing or wrong pages.',
+    entity: 'internal-links', affectedCount: ownershipGaps.reduce((count, row) => count + row.occurrenceIds.length, 0),
+  });
+  const routeIssues = (audit.routes || []).filter((row) => !['configured', 'reused'].includes(row.status));
+  if (routeIssues.length) actions.push({
+    code: 'app_route_configuration', severity: 'high',
+    action: `Requires Import Operator. ${ROUTE_PROMPT} Evidence: ${RELATIVE_PATH}. Conflicting ownership needs a human decision.`,
+    deadlineReason: 'After apps are installed and before DNS; a planned or unsupported route is not a served page.',
+    entity: 'app-routes', affectedCount: routeIssues.length,
+  });
+  const scanGaps = (audit.manifest || []).filter((row) => ['unsupported', 'unsupported-construct', 'unreadable', 'missing'].includes(row.disposition));
+  if (scanGaps.length) actions.push({
+    code: 'internal_link_scan_gaps', severity: 'high',
+    action: `Requires Import Operator. ${UNRESOLVED_PROMPT} Evidence: ${RELATIVE_PATH}.`,
+    deadlineReason: 'Before website handoff; unsupported or unreadable files cannot count as verified link coverage.',
+    entity: 'internal-links', affectedCount: scanGaps.length,
+  });
+  if (audit.stage !== 'verified' || audit.pendingDestinations.length) actions.push({
+    code: 'pending_link_verification', severity: 'high',
+    action: `Requires Import Operator. ${PENDING_PROMPT} Evidence: ${RELATIVE_PATH}.`,
+    deadlineReason: 'After frontend creation and before DNS; planned paths have not been shown to serve intended pages.',
+    entity: 'internal-links', affectedCount: audit.pendingDestinations.reduce((count, row) => count + row.occurrenceIds.length, 0),
+  });
+  const unavailable = (audit.pendingDestinations || []).filter((row) => row.reason && row.reason !== 'writer-or-link-verification-pending');
+  const fragmentGaps = (audit.unresolved || []).filter((row) => row.detail === 'fragment-anchor-unverified');
+  if (unavailable.length || fragmentGaps.length) actions.push({
+    code: 'link_verification_unavailable', severity: 'high',
+    action: `Requires Import Operator. ${UNAVAILABLE_PROMPT} Evidence: ${RELATIVE_PATH}.`,
+    deadlineReason: 'Before DNS; a served-page response alone does not prove link behavior, fragments or current content.',
+    entity: 'internal-links', affectedCount: unavailable.reduce((sum, row) => sum + row.occurrenceIds.length, 0) + fragmentGaps.reduce((sum, row) => sum + row.occurrenceIds.length, 0),
+  });
+  if (audit.stage === 'budget-hold') actions.push({
+    code: 'link_verification_budget', severity: 'high',
+    action: `Requires Import Operator. ${BUDGET_PROMPT} Evidence: ${RELATIVE_PATH}.`,
+    deadlineReason: 'The approved 30-minute live-work or 100,000 exception-review-token ceiling would be exceeded; resume only after an explicit decision.',
+    entity: 'internal-links', affectedCount: audit.pendingDestinations.reduce((count, row) => count + row.occurrenceIds.length, 0),
+  });
+  if (audit.postDnsStatus !== 'verified') actions.push({
+    code: 'post_dns_route_check', severity: 'medium',
+    action: `Cutover Operator: after DNS and HTTPS readiness, check the public host against the routes listed in ${RELATIVE_PATH}; return any local repair to the Import Operator.`,
+    deadlineReason: 'After DNS; preview-host checks do not prove the final public route.',
+    entity: 'app-routes', affectedCount: (audit.routes || []).length,
+  });
+  return actions;
+}
+
+module.exports = { RELATIVE_PATH, auditPath, validateLinkAudit, readLinkAudit, writeLinkAudit, linkOperatorActions };

package/skills/wix-replatform/lib/link-census.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { classifyNavigation, occurrenceId } = require('./internal-link-reconciliation.js');
+
+const NAV_KEYS = new Set(['href', 'url', 'link', 'destination', 'targetUrl']);
+const RESOURCE_KEYS = new Set(['src', 'srcset', 'image', 'media', 'download', 'backgroundImage']);
+const IGNORED_SEGMENTS = new Set(['config', '.git', 'node_modules', 'secrets']);
+
+function hash(value) { return createHash('sha256').update(value).digest('hex'); }
+
+function decodeHtmlEntities(value) {
+  return value.replace(/&(#(?:x[0-9a-f]+|[0-9]+)|amp|quot|apos|lt|gt);/gi, (_whole, entity) => {
+    if (entity[0] === '#') {
+      const number = entity[1].toLowerCase() === 'x' ? parseInt(entity.slice(2), 16) : parseInt(entity.slice(1), 10);
+      return number > 0 && number <= 0x10ffff ? String.fromCodePoint(number) : _whole;
+    }
+    return { amp: '&', quot: '"', apos: "'", lt: '<', gt: '>' }[entity.toLowerCase()];
+  });
+}
+
+// Tokenizes tags and quoted attributes. It does not treat arbitrary angle-bracket text as a
+// successful parse: malformed markup produces an explicit unsupported disposition.
+function htmlAttributes(html) {
+  const found = [];
+  let index = 0;
+  while (index < html.length) {
+    const open = html.indexOf('<', index);
+    if (open < 0) break;
+    if (html.startsWith('<!--', open)) {
+      const close = html.indexOf('-->', open + 4);
+      if (close < 0) throw new Error('unterminated HTML comment');
+      const comment = html.slice(open + 4, close).trim();
+      if (comment.startsWith('wp:')) {
+        const jsonStart = comment.indexOf('{');
+        const jsonEnd = comment.lastIndexOf('}');
+        if (jsonStart >= 0 && jsonEnd > jsonStart) {
+          try {
+            for (const link of extractJson(JSON.parse(comment.slice(jsonStart, jsonEnd + 1)))) found.push({ ...link, location: `block:${open}:${link.location}` });
+          } catch { throw new Error('unsupported WordPress block attributes'); }
+        }
+      }
+      index = close + 3; continue;
+    }
+    let cursor = open + 1;
+    if (!/[A-Za-z/!?]/.test(html[cursor] || '')) { index = cursor; continue; }
+    let quote = null;
+    for (; cursor < html.length; cursor += 1) {
+      const char = html[cursor];
+      if (quote) { if (char === quote) quote = null; }
+      else if (char === '"' || char === "'") quote = char;
+      else if (char === '>') break;
+    }
+    if (cursor >= html.length) throw new Error('unterminated HTML tag');
+    const tag = html.slice(open + 1, cursor);
+    const attr = /(?:^|\s)(href|action|src|srcset)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi;
+    let match;
+    while ((match = attr.exec(tag))) found.push({ key: match[1].toLowerCase(), value: decodeHtmlEntities(match[2] ?? match[3] ?? match[4]), location: `char:${open + 1 + match.index + match[0].indexOf(match[1])}` });
+    index = cursor + 1;
+  }
+  return found;
+}
+
+function countMetadataHrefs(value) {
+  if (Array.isArray(value)) return value.reduce((count, item) => count + countMetadataHrefs(item), 0);
+  if (!value || typeof value !== 'object') return 0;
+  return Object.entries(value).reduce((count, [key, child]) => count + (key === 'href' && typeof child === 'string' ? 1 : countMetadataHrefs(child)), 0);
+}
+
+function extractJson(value, location = '$', output = [], contentField = null, stats = null) {
+  if (Array.isArray(value)) { value.forEach((item, index) => extractJson(item, `${location}[${index}]`, output, contentField, stats)); return output; }
+  if (!value || typeof value !== 'object') return output;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === '_links' || key === '_embedded') {
+      if (stats) stats.metadataHrefsSkipped = (stats.metadataHrefsSkipped || 0) + countMetadataHrefs(child);
+      continue;
+    }
+    if (key === 'yoast_head' || key === 'yoast_head_json') {
+      if (stats && key === 'yoast_head' && typeof child === 'string') {
+        stats.metadataHrefsSkipped = (stats.metadataHrefsSkipped || 0) + (child.match(/(?:^|\s)href\s*=/gi) || []).length;
+      }
+      continue;
+    }
+    const next = `${location}.${key}`;
+    const owningField = contentField || (['records', 'items', 'data', 'entities'].includes(key) ? null : key);
+    if (typeof child === 'string') {
+      const resourceContext = /(?:^|\.)(?:image|media|attachment|thumbnail|download|logo|icon|background)(?:\.|\[|$)/i.test(location);
+      const navigationContext = /(?:^|\.)(?:content|body|description|button|menu|recommendation|link|anchor|action|richContent)(?:\.|\[|$)/i.test(location);
+      if (RESOURCE_KEYS.has(key) || resourceContext && key === 'url') output.push({ key, value: child, location: next, contentField: owningField, resource: true });
+      else if (NAV_KEYS.has(key) && (key === 'href' || key === 'targetUrl' || key === 'destination' || navigationContext)) output.push({ key, value: child, location: next, contentField: owningField });
+      else if (/<[a-z][^>]*>/i.test(child)) for (const attr of htmlAttributes(child)) output.push({ ...attr, contentField: owningField, location: `${next}:${attr.location}` });
+    } else extractJson(child, next, output, owningField, stats);
+  }
+  return output;
+}
+
+function extractFile(file, raw, stats = null) {
+  const ext = path.extname(file).toLowerCase();
+  if (ext === '.json') return extractJson(JSON.parse(raw), '$', [], null, stats);
+  if (ext === '.html' || ext === '.htm') return htmlAttributes(raw);
+  // CSS URLs are resources, not automatically navigational links.
+  if (ext === '.css') return [];
+  throw new Error('unsupported-format');
+}
+
+function containingRecord(file, location, containingPages) {
+  const config = containingPages[file];
+  if (typeof config === 'string') return { url: config, recordId: null };
+  if (!config || typeof config !== 'object') return null;
+  const prefix = Object.keys(config).filter((key) => location.startsWith(key)).sort((a, b) => b.length - a.length)[0];
+  if (!prefix) return null;
+  const row = config[prefix];
+  return typeof row === 'string' ? { url: row, recordId: null } : row;
+}
+
+async function walk(root, relative = '') {
+  const entries = await fs.readdir(path.join(root, relative), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (IGNORED_SEGMENTS.has(entry.name) || entry.name.startsWith('.')) continue;
+    const next = path.join(relative, entry.name);
+    if (entry.isDirectory()) files.push(...await walk(root, next));
+    else if (entry.isFile()) files.push(next);
+  }
+  return files;
+}
+
+async function census({ capturedRoots, expectedFiles = [], sourceHosts, destinationHosts, containingPages = {}, previous = null }) {
+  if (!Array.isArray(capturedRoots) || !capturedRoots.length) throw new Error('capturedRoots required');
+  const started = Date.now();
+  const manifest = [];
+  const occurrences = [];
+  for (const root of capturedRoots) {
+    const files = await walk(root);
+    for (const relative of files) {
+      const file = path.join(root, relative);
+      let raw;
+      try { raw = await fs.readFile(file); }
+      catch (error) { manifest.push({ file, disposition: 'unreadable', reason: error.code || 'read-error' }); continue; }
+      const digest = hash(raw);
+      const base = { file, bytes: raw.length, sha256: digest };
+      const old = previous && previous.censusVersion === 4 && previous.manifest && previous.manifest.find((row) => row.file === file && row.sha256 === digest);
+      if (old && previous.occurrences) {
+        manifest.push({ ...base, disposition: old.disposition, reason: old.reason || null, metadataHrefsSkipped: old.metadataHrefsSkipped || 0 });
+        occurrences.push(...previous.occurrences.filter((row) => row.sourceFile === file));
+        continue;
+      }
+      let links;
+      const scanStats = {};
+      try { links = extractFile(file, raw.toString('utf8'), scanStats); }
+      catch (error) { manifest.push({ ...base, disposition: 'unsupported', reason: error.message }); continue; }
+      const possibleUnparsedLink = !links.length && /https?:\/\/|href\s*=|location\.href/i.test(raw.toString('utf8')) && !scanStats.metadataHrefsSkipped;
+      manifest.push({ ...base, disposition: links.length ? 'scanned-links' : possibleUnparsedLink ? 'unsupported-construct' : 'scanned-no-links', metadataHrefsSkipped: scanStats.metadataHrefsSkipped || 0 });
+      for (const link of links) {
+        if (link.resource || RESOURCE_KEYS.has(link.key)) continue;
+        const containing = containingRecord(file, link.location, containingPages);
+        const containingUrl = containing && containing.url;
+        if (!containingUrl) {
+          // An absolute off-site URL needs no containing page to classify it.
+          if (/^https?:\/\//i.test(link.value) || /^\/\//.test(link.value)) {
+            const absolute = classifyNavigation(link.value, 'https://link-audit.invalid/', { sourceHosts, destinationHosts });
+            if (absolute.kind === 'external') continue;
+          }
+          occurrences.push({ id: occurrenceId({ sourceFile: file, field: link.key, location: link.location, original: link.value }), sourceFile: file, field: link.key, location: link.location, original: link.value, classification: 'missing-containing-page' });
+          continue;
+        }
+        const classification = classifyNavigation(link.value, containingUrl, { sourceHosts, destinationHosts });
+        if (classification.kind !== 'internal' && classification.kind !== 'stateful') continue;
+        occurrences.push({
+          id: occurrenceId({ sourceFile: file, field: link.key, location: link.location, original: link.value }),
+          sourceFile: file, sourceRecordId: containing.recordId || null, targetRecordId: containing.targetRecordId || null,
+          recordType: containing.recordType || null, targetContentRevision: containing.targetContentRevision || null,
+          field: containing.contentField || link.contentField || link.key, location: link.location, containingUrl,
+          original: link.value, classification: classification.kind === 'stateful' ? 'stateful-navigation' : 'internal-navigation',
+          originalPath: classification.path, ...(classification.fragmentOnly ? { fragmentOnly: true } : {}),
+        });
+      }
+    }
+  }
+  const scannedFiles = new Set(manifest.map((row) => row.file));
+  for (const file of expectedFiles) if (!scannedFiles.has(file)) manifest.push({ file, disposition: 'missing', reason: 'capture-file-absent' });
+  return { manifest, occurrences, counts: {
+    files: manifest.length, bytes: manifest.reduce((sum, row) => sum + (row.bytes || 0), 0),
+    internalOccurrences: occurrences.filter((row) => ['internal-navigation', 'stateful-navigation'].includes(row.classification)).length,
+    distinctInternalDestinations: new Set(occurrences.filter((row) => row.originalPath).map((row) => row.originalPath)).size,
+    unsupportedFiles: manifest.filter((row) => ['unsupported', 'unsupported-construct', 'unreadable', 'missing'].includes(row.disposition)).length,
+    metadataHrefsSkipped: manifest.reduce((sum, row) => sum + (row.metadataHrefsSkipped || 0), 0),
+    scanMs: Date.now() - started,
+  } };
+}
+
+module.exports = { decodeHtmlEntities, htmlAttributes, extractJson, extractFile, census };