@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/lib/url-verification.js

@@ -0,0 +1,315 @@
+'use strict';
+
+// Old-address verification: deterministic HTTP checks that each known old URL reaches its
+// intended page. No model call per URL; the caller receives counts and exceptions only, and
+// response bodies never leave this module (only a bounded status/location trace is stored).
+//
+// Stages:
+//   preparation      before the DNS switch, against the destination deployment through a
+//                    host/SNI connect override. Never satisfies the public check.
+//   verified_public  after the DNS switch, against the original public URLs via public DNS.
+//                    The only stage that can earn a verified result.
+
+const http = require('node:http');
+const https = require('node:https');
+const state = require('./url-preservation-state.js');
+const planLib = require('./url-redirect-plan.js');
+
+const STAGES = new Set(['preparation', 'verified_public']);
+const PERMANENT = new Set([301, 308]);
+const TEMPORARY = new Set([302, 303, 307]);
+const TRANSIENT_REASONS = new Set(['timeout', 'connection_error', 'server_error', 'dns_unresolved']);
+const MAX_BODY_BYTES = 512 * 1024;
+const MAX_EXCEPTIONS_RETURNED = 50;
+
+function endpointFor(origin, endpoint) {
+  const target = endpoint.mode === 'connect_override'
+    ? `override:${endpoint.connectHost}:${endpoint.connectPort || origin.effectivePort}`
+    : 'public-dns';
+  return `${origin.scheme}://${origin.hostname}:${origin.effectivePort}@${target}`;
+}
+
+function checkpointKeyOf({ obligationKey, planDigest, deploymentId, stage, effectiveEndpoint }) {
+  return [obligationKey, planDigest, deploymentId, stage, effectiveEndpoint].join('␟');
+}
+
+// A checkpoint satisfies only an identical key. A preparation row can never stand in for a
+// verified_public check, whatever endpoint it used; the caller's claim is not trusted.
+function checkpointSatisfies(row, wanted) {
+  if (!row || row.stage !== wanted.stage) return false;
+  if (wanted.stage === 'verified_public' && row.stage !== 'verified_public') return false;
+  return row.checkpointKey === checkpointKeyOf(wanted);
+}
+
+function executionDigestFor(obligation, executionByKey) {
+  if (obligation.externalTarget) return planLib.digest([
+    obligation.externalTarget, obligation.externalEvidenceDigest, obligation.externalSetup,
+  ]);
+  const row = obligation.remoteRuleKey ? executionByKey[obligation.remoteRuleKey] : null;
+  return planLib.digest(row ? [row.ruleKey, row.disposition, row.to, row.remoteId || null] : null);
+}
+
+function classifyError(error) {
+  const code = (error && (error.code || error.name)) || '';
+  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return 'dns_unresolved';
+  if (/CERT|TLS|SSL|SELF_SIGNED|UNABLE_TO_VERIFY|DEPTH_ZERO|ERR_TLS/i.test(code)) return 'certificate_error';
+  if (code === 'ETIMEDOUT' || code === 'TimeoutError' || code === 'ESOCKETTIMEDOUT' || code === 'timeout') return 'timeout';
+  return 'connection_error';
+}
+
+// Default transport: one GET, no redirect following, no credentials, bounded body.
+function nodeHttpGet({ url, connect, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const options = {
+      method: 'GET',
+      hostname: connect ? connect.host : parsed.hostname,
+      port: connect ? connect.port : (parsed.port || (parsed.protocol === 'https:' ? 443 : 80)),
+      path: `${parsed.pathname}${parsed.search}`,
+      headers: { Host: parsed.host, 'User-Agent': 'replatform-url-verification/1', Accept: 'text/html,*/*' },
+      servername: parsed.hostname,
+      timeout: timeoutMs,
+    };
+    const req = lib.request(options, (res) => {
+      const chunks = [];
+      let size = 0;
+      res.on('data', (chunk) => {
+        if (size < MAX_BODY_BYTES) { chunks.push(chunk); size += chunk.length; }
+      });
+      res.on('end', () => resolve({ status: res.statusCode, location: res.headers.location || null, body: Buffer.concat(chunks).toString('utf8') }));
+      res.on('error', reject);
+    });
+    req.on('timeout', () => req.destroy(Object.assign(new Error('request timed out'), { code: 'ETIMEDOUT' })));
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function defaultPort(scheme) {
+  return scheme === 'https' ? 443 : 80;
+}
+
+// Declared origins are identified by scheme, hostname and effective port: a same-host origin
+// on another port is a different origin, and an undeclared port is off-site.
+function originKeyOfUrl(url) {
+  const scheme = url.protocol.slice(0, -1);
+  return `${scheme}://${url.hostname}:${url.port ? Number(url.port) : defaultPort(scheme)}`;
+}
+
+function originUrlBase(origin) {
+  return `${origin.scheme}://${origin.hostname}${origin.effectivePort === defaultPort(origin.scheme) ? '' : `:${origin.effectivePort}`}`;
+}
+
+// Query semantics compare as an order-insensitive multiset of decoded name/value pairs.
+function querySignature(search) {
+  return JSON.stringify([...new URLSearchParams(search || '').entries()].sort((a, b) => (a[0] === b[0] ? a[1].localeCompare(b[1]) : a[0].localeCompare(b[0]))));
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function checkOne({ obligation, origin, endpoint, originsByKey, httpGet, timeoutMs, maxHops, rateGate }) {
+  const start = new URL(`${originUrlBase(origin)}${obligation.path}${obligation.query || ''}`);
+  const trace = [];
+  if (obligation.disposition === 'external_redirect') {
+    const connect = endpoint.mode === 'connect_override'
+      ? { host: endpoint.connectHost, port: endpoint.connectPort || origin.effectivePort } : null;
+    await rateGate(start.hostname);
+    let response;
+    try { response = await httpGet({ url: start.href, connect, timeoutMs }); }
+    catch (error) { return { result: 'not_verified', reason: classifyError(error), trace: [{ url: start.href, error: classifyError(error) }] }; }
+    trace.push({ url: start.href, status: response.status, location: response.location || null });
+    if (response.status !== 301) return { result: 'failed', reason: 'external_source_status_mismatch', trace };
+    if (!response.location) return { result: 'failed', reason: 'redirect_without_location', trace };
+    let actual;
+    try { actual = new URL(response.location, start); }
+    catch { return { result: 'failed', reason: 'redirect_malformed_location', trace }; }
+    if (actual.href !== new URL(obligation.externalTarget).href) {
+      return { result: 'failed', reason: 'external_location_mismatch', trace };
+    }
+    return { result: 'verified_redirect', reason: null, trace };
+  }
+  let current = start;
+  let permanentOnly = true;
+  for (let hop = 0; hop <= maxHops; hop += 1) {
+    const host = current.hostname;
+    const hopOrigin = originsByKey.get(originKeyOfUrl(current));
+    if (!hopOrigin) return { result: 'failed', reason: 'redirect_off_site', trace };
+    const connect = endpoint.mode === 'connect_override'
+      ? { host: endpoint.connectHost, port: endpoint.connectPort || hopOrigin.effectivePort }
+      : null;
+    await rateGate(host);
+    let response;
+    try {
+      response = await httpGet({ url: current.href, connect, timeoutMs });
+    } catch (error) {
+      trace.push({ url: current.href, error: classifyError(error) });
+      return { result: 'not_verified', reason: classifyError(error), trace };
+    }
+    trace.push({ url: current.href, status: response.status, location: response.location || null });
+    if (PERMANENT.has(response.status) || TEMPORARY.has(response.status)) {
+      if (TEMPORARY.has(response.status)) permanentOnly = false;
+      if (!response.location) return { result: 'failed', reason: 'redirect_without_location', trace };
+      let next;
+      try {
+        next = new URL(response.location, current);
+      } catch {
+        return { result: 'failed', reason: 'redirect_malformed_location', trace };
+      }
+      if (next.protocol !== 'http:' && next.protocol !== 'https:') return { result: 'failed', reason: 'redirect_non_http', trace };
+      if (next.username || next.password) return { result: 'failed', reason: 'redirect_with_credentials', trace };
+      current = next;
+      continue;
+    }
+    if (response.status === 404 || response.status === 410) return { result: 'failed', reason: 'not_found', trace };
+    if (response.status >= 500) return { result: 'not_verified', reason: 'server_error', trace };
+    if (response.status !== 200) return { result: 'failed', reason: `http_${response.status}`, trace };
+    const finalPath = planLib.conflictPath(current.pathname.replace(/%[0-9a-f]{2}/gi, (m) => m.toUpperCase()));
+    if (finalPath !== obligation.expected.conflictPath) return { result: 'failed', reason: 'wrong_final_route', trace };
+    const expectedQuery = obligation.expected.query !== undefined ? obligation.expected.query : (obligation.query || '');
+    if (querySignature(current.search) !== querySignature(expectedQuery)) return { result: 'failed', reason: 'final_query_mismatch', trace };
+    const body = String(response.body || '');
+    if (!body.includes(obligation.expected.pageMarker)) return { result: 'failed', reason: 'page_marker_missing', trace };
+    if (obligation.fragment) {
+      const anchor = escapeRegExp(decodeURIComponent(obligation.fragment.slice(1)));
+      if (!new RegExp(`(id|name)=["']${anchor}["']`).test(body)) return { result: 'failed', reason: 'fragment_anchor_missing', trace };
+    }
+    if (trace.length > 1 && !permanentOnly) return { result: 'failed', reason: 'non_permanent_redirect', trace };
+    return { result: trace.length > 1 ? 'verified_redirect' : 'verified_direct', reason: null, trace };
+  }
+  return { result: 'failed', reason: 'too_many_redirects', trace };
+}
+
+async function runPool(items, concurrency, worker) {
+  let next = 0;
+  const workers = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, async () => {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      await worker(items[index]);
+    }
+  });
+  await Promise.all(workers);
+}
+
+async function verifyUrls(options) {
+  const {
+    projectDir,
+    plan,
+    sourceDomains,
+    stage,
+    endpoint = { mode: 'public' },
+    afterDnsSwitch = false,
+    httpGet = nodeHttpGet,
+    concurrency = 8,
+    timeoutMs = 10000,
+    retryBudget = 2,
+    perHostIntervalMs = 50,
+    maxHops = 5,
+    runId,
+    now = () => new Date().toISOString(),
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  } = options;
+  if (!STAGES.has(stage)) throw new Error(`stage must be one of: ${[...STAGES].join(', ')}`);
+  if (stage === 'verified_public' && (!afterDnsSwitch || endpoint.mode !== 'public')) {
+    throw new Error('verified_public runs only after the DNS switch, against public DNS for the original URLs');
+  }
+  if (stage === 'preparation' && endpoint.mode === 'public') {
+    throw new Error('preparation checks must target the destination deployment through a connect override; public DNS still reaches the source site');
+  }
+  if (!plan.websiteBuilt) throw new Error('no final route manifest: verification needs a built destination website');
+  const startedAt = Date.now();
+  const origins = sourceDomains.origins;
+  const originsByKey = new Map(origins.map((o) => [`${o.scheme}://${o.hostname}:${o.effectivePort}`, o]));
+  const execution = await state.loadRedirectExecution(projectDir);
+  const existing = await state.loadUrlVerification(projectDir);
+  const lastByHost = new Map();
+  const rateGate = async (host) => {
+    const wait = (lastByHost.get(host) || 0) + perHostIntervalMs - Date.now();
+    lastByHost.set(host, Math.max(Date.now(), (lastByHost.get(host) || 0) + perHostIntervalMs));
+    if (wait > 0) await sleep(wait);
+  };
+
+  const inScope = plan.obligations.filter((ob) => ob.disposition === 'direct' || ob.disposition === 'redirect' ||
+    (ob.disposition === 'external_redirect' && ob.externalSetup));
+  const work = [];
+  for (const obligation of inScope) {
+    for (const key of obligation.origins) {
+      const origin = origins.find((o) => `${o.scheme}://${o.hostname}:${o.effectivePort}` === key);
+      if (!origin) continue;
+      const effectiveEndpoint = endpointFor(origin, endpoint);
+      const wanted = { obligationKey: obligation.obligationKey, planDigest: plan.planDigest, deploymentId: plan.deploymentId, stage, effectiveEndpoint };
+      const checkpointKey = checkpointKeyOf(wanted);
+      const execDigest = executionDigestFor(obligation, execution.byKey);
+      const prior = existing.byCheckpoint[checkpointKey];
+      const reusable = checkpointSatisfies(prior, wanted) && prior.executionDigest === execDigest && (
+        prior.result === 'verified_direct' || prior.result === 'verified_redirect'
+        || (stage === 'verified_public' && prior.result === 'failed'));
+      work.push({ obligation, origin, effectiveEndpoint, checkpointKey, execDigest, skip: reusable });
+    }
+  }
+
+  const summary = { stage, checks: 0, skippedFromCheckpoint: 0, retries: 0, results: { verified_direct: 0, verified_redirect: 0, failed: 0, not_verified: 0 }, durationMs: 0 };
+  const exceptions = [];
+  await runPool(work, concurrency, async (item) => {
+    if (item.skip) { summary.skippedFromCheckpoint += 1; return; }
+    let outcome = null;
+    // The public pass tests the switched domain only; an origin still serving the source site
+    // cannot produce destination proof, so nothing is sent to it.
+    if (stage === 'verified_public' && item.origin.cutoverStatus !== 'destination_serving') {
+      outcome = { result: 'not_verified', reason: 'origin_not_cut_over', trace: [] };
+    }
+    for (let attempt = 0; !outcome || (outcome.result === 'not_verified' && TRANSIENT_REASONS.has(outcome.reason) && attempt <= retryBudget); attempt += 1) {
+      if (outcome) { summary.retries += 1; await sleep(200 * 2 ** (attempt - 1)); }
+      outcome = await checkOne({ obligation: item.obligation, origin: item.origin, endpoint, originsByKey, httpGet, timeoutMs, maxHops, rateGate });
+    }
+    summary.checks += 1;
+    summary.results[outcome.result] += 1;
+    const row = {
+      schemaVersion: state.SCHEMA_VERSION,
+      checkpointKey: item.checkpointKey,
+      obligationKey: item.obligation.obligationKey,
+      planDigest: plan.planDigest,
+      deploymentId: plan.deploymentId,
+      executionDigest: item.execDigest,
+      stage,
+      effectiveEndpoint: item.effectiveEndpoint,
+      origin: `${item.origin.scheme}://${item.origin.hostname}:${item.origin.effectivePort}`,
+      originalUrl: `${originUrlBase(item.origin)}${item.obligation.path}${item.obligation.query || ''}${item.obligation.fragment || ''}`,
+      expected: item.obligation.externalTarget
+        ? { externalTarget: item.obligation.externalTarget, setup: item.obligation.externalSetup }
+        : { targetEntityType: item.obligation.expected.targetEntityType, targetEntityId: item.obligation.expected.targetEntityId, relativeUrl: item.obligation.expected.relativeUrl },
+      result: outcome.result,
+      reason: outcome.reason,
+      trace: outcome.trace.slice(0, maxHops + 1),
+      runId,
+      checkedAt: now(),
+    };
+    await state.appendUrlVerificationRow(projectDir, row);
+    if (outcome.result !== 'verified_direct' && outcome.result !== 'verified_redirect') {
+      exceptions.push({ obligationKey: row.obligationKey, origin: row.origin, result: row.result, reason: row.reason });
+    }
+  });
+  summary.durationMs = Date.now() - startedAt;
+  exceptions.sort((a, b) => `${a.obligationKey}${a.origin}`.localeCompare(`${b.obligationKey}${b.origin}`));
+  return {
+    summary,
+    exceptionCount: exceptions.length,
+    exceptions: exceptions.slice(0, MAX_EXCEPTIONS_RETURNED),
+    evidence: state.relativeStatePath('urlVerification'),
+  };
+}
+
+module.exports = {
+  STAGES,
+  endpointFor,
+  checkpointKeyOf,
+  checkpointSatisfies,
+  executionDigestFor,
+  classifyError,
+  querySignature,
+  nodeHttpGet,
+  verifyUrls,
+};

package/skills/wix-replatform/lib/user-action-effects.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// The one place a durable user-action answer changes orchestration state. Both CLI entry
+// points (`replatform answer` and `scripts/user-action.js answer`) call this, so an effect
+// cannot behave differently depending on where the person answered.
+const path = require('node:path');
+const { loadArtifacts, updateDecisionObject, writeJsonAtomic } = require('./orchestration-state.js');
+const { applySiteTypePair, pairForChoice } = require('./destination-choice.js');
+
+async function applyUserActionEffect(projectDir, request, answer) {
+  if (!request.effect) return;
+  if (request.effect.kind === 'read-back-omission-ack') return require('./read-back-approval.js').acknowledge(projectDir, request, answer);
+  if (request.effect.kind === 'approval') return require('./read-back-approval.js').applyApproval(projectDir, request, answer);
+  const artifacts = await loadArtifacts(projectDir);
+  const decisionsPath = path.join(projectDir, 'orchestration', 'decisions.json');
+  const effect = request.effect;
+  if (effect.kind === 'decision' && effect.key === 'managementImportMode') {
+    const value = effect.choices?.[answer.choice];
+    if (!value) return;
+    updateDecisionObject(artifacts.decisions, 'managementImportMode', value, { source: 'user', rationale: request.title });
+    await writeJsonAtomic(decisionsPath, artifacts.decisions);
+    return;
+  }
+  if (effect.kind === 'decision' && effect.key === 'targetSiteType') {
+    // One choice id → both decisions, one write.
+    applySiteTypePair(artifacts.decisions, pairForChoice(effect, answer.choice), { rationale: request.title });
+    await writeJsonAtomic(decisionsPath, artifacts.decisions);
+    return;
+  }
+  if (effect.kind === 'decision' && effect.key === 'editorWebsiteDecision') {
+    const value = effect.choices?.[answer.choice];
+    if (!value) throw new Error('editor website decision requires a declared choice');
+    updateDecisionObject(artifacts.decisions, 'editorWebsiteDecision', value, { source: 'user', rationale: request.title });
+    // "Backend only" is an explicit scope change to management.
+    if (value === 'management_only') updateDecisionObject(artifacts.decisions, 'deliveryMode', 'management', { source: 'user', rationale: request.title });
+    await writeJsonAtomic(decisionsPath, artifacts.decisions);
+    return;
+  }
+  throw new Error('unsupported user-action effect');
+}
+
+module.exports = { applyUserActionEffect };

package/skills/wix-replatform/lib/user-actions.js

@@ -0,0 +1,264 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const { hashArtifact } = require('./artifact-freshness.js');
+const { isValidSiteTypeEffect, isValidEditorWebsiteEffect } = require('./destination-choice.js');
+
+const SCHEMA_VERSION = 1;
+const KINDS = new Set(['question', 'review', 'approval', 'manual_action']);
+const RESPONSE_MODES = new Set(['choice', 'text', 'none']);
+
+function userActionsDir(projectDir) {
+  return path.join(projectDir, 'orchestration', 'user-actions');
+}
+
+function requestPath(projectDir, requestId) {
+  return path.join(userActionsDir(projectDir), `${requestId}.json`);
+}
+
+function newRequestId() {
+  return `uar_${crypto.randomUUID()}`;
+}
+
+async function writeJsonAtomic(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await fs.rename(tempPath, filePath);
+}
+
+function assertSafeText(value, label, { max = 4000, required = true } = {}) {
+  if ((value === undefined || value === null || value === '') && !required) return null;
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} must be non-empty text`);
+  if (value.length > max) throw new Error(`${label} exceeds ${max} characters`);
+  if (/\x00/.test(value)) throw new Error(`${label} contains a null byte`);
+  return value;
+}
+
+function normalizeArtifact(projectDir, ref) {
+  if (!ref || typeof ref !== 'object') throw new Error('artifactRef must be an object');
+  const relativePath = assertSafeText(ref.path, 'artifactRef.path', { max: 512 });
+  const resolved = path.resolve(projectDir, relativePath);
+  const root = `${path.resolve(projectDir)}${path.sep}`;
+  if (!resolved.startsWith(root)) throw new Error('artifactRef.path must remain inside project');
+  if (relativePath.split(/[\\/]/).includes('..')) throw new Error('artifactRef.path must not traverse parent directories');
+  if (ref.kind !== undefined && ref.kind !== 'census-reconciliation') throw new Error('artifactRef.kind is unsupported');
+  if (ref.kind === 'census-reconciliation' && !/^[0-9a-f]{64}$/i.test(ref.sha256 || '')) throw new Error('census reconciliation artifact requires sha256');
+  return {
+    ...(ref.kind ? { kind: ref.kind } : {}),
+    path: relativePath.replaceAll('\\', '/'),
+    mediaType: assertSafeText(ref.mediaType || 'text/plain', 'artifactRef.mediaType', { max: 100 }),
+    ...(ref.sha256 ? { sha256: assertSafeText(ref.sha256, 'artifactRef.sha256', { max: 128 }) } : {}),
+  };
+}
+
+// Optional machine-readable context a deterministic producer attaches so it can find its own
+// request again (for example, the destination recovery request records the metasite ID and
+// the observation it was raised for). Plain JSON only; never credentials.
+function normalizeSubject(subject) {
+  if (!subject || typeof subject !== 'object' || Array.isArray(subject)) throw new Error('subject must be an object');
+  const text = JSON.stringify(subject);
+  if (text.length > 4000) throw new Error('subject exceeds 4000 characters');
+  assertSafeText(subject.type, 'subject.type', { max: 100 });
+  return JSON.parse(text);
+}
+
+function normalizeRequest(projectDir, input = {}) {
+  const kind = input.kind;
+  if (!KINDS.has(kind)) throw new Error(`invalid user action kind: ${kind}`);
+  const response = input.response || {};
+  const mode = response.mode || 'choice';
+  if (!RESPONSE_MODES.has(mode)) throw new Error(`invalid response mode: ${mode}`);
+  const choices = Array.isArray(input.choices) ? input.choices.map((choice) => ({
+    id: assertSafeText(choice && choice.id, 'choice.id', { max: 100 }),
+    label: assertSafeText(choice && choice.label, 'choice.label', { max: 200 }),
+    ...(choice.description ? { description: assertSafeText(choice.description, 'choice.description', { max: 500 }) } : {}),
+  })) : [];
+  if (mode === 'choice' && choices.length === 0) throw new Error('choice response requires choices');
+  if (new Set(choices.map((choice) => choice.id)).size !== choices.length) throw new Error('choice ids must be unique');
+  if (mode !== 'choice' && choices.length) throw new Error('only choice responses may declare choices');
+  const artifactRefs = Array.isArray(input.artifactRefs) ? input.artifactRefs.map((ref) => normalizeArtifact(projectDir, ref)) : [];
+  const requestId = input.requestId || newRequestId();
+  if (!/^uar_[0-9a-f-]+$/.test(requestId)) throw new Error('invalid request id');
+  if (input.effect) {
+    const isApproval = input.effect.kind === 'approval' && ['mapping', 'execution'].includes(input.effect.approvalType);
+    const isImportModeDecision = input.effect.kind === 'decision'
+      && input.effect.key === 'managementImportMode'
+      && input.effect.choices
+      && typeof input.effect.choices === 'object'
+      && !Array.isArray(input.effect.choices)
+      && Object.keys(input.effect.choices).length > 0
+      && Object.entries(input.effect.choices).every(([choice, value]) => choices.some((item) => item.id === choice) && ['standard', 'quick'].includes(value));
+    const isReadBackAck = input.effect.kind === 'read-back-omission-ack' && kind === 'manual_action' && mode === 'none'
+      && ['order', 'member', 'contact', 'product'].includes(input.effect.entity) && typeof input.effect.runId === 'string'
+      && /^[a-f0-9]{64}$/.test(input.effect.omissionSetDigest);
+    // The combined site-type choice and the Editor website scope guard.
+    const isSiteTypeDecision = isValidSiteTypeEffect(input.effect, choices);
+    const isEditorWebsiteDecision = isValidEditorWebsiteEffect(input.effect, choices);
+    if (!isApproval && !isImportModeDecision && !isSiteTypeDecision && !isEditorWebsiteDecision && !isReadBackAck) throw new Error('unsupported user-action effect');
+  }
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    requestId,
+    status: 'pending',
+    kind,
+    stage: assertSafeText(input.stage, 'stage', { max: 100 }),
+    title: assertSafeText(input.title, 'title', { max: 200 }),
+    prompt: assertSafeText(input.prompt, 'prompt', { max: 4000 }),
+    response: { mode, required: response.required !== false },
+    choices,
+    artifactRefs,
+    ...(input.effect ? { effect: input.effect } : {}),
+    ...(input.subject ? { subject: normalizeSubject(input.subject) } : {}),
+    createdAt: new Date().toISOString(),
+    answer: null,
+  };
+}
+
+async function rebuildIndex(projectDir) {
+  const dir = userActionsDir(projectDir);
+  let entries = [];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return [];
+    throw error;
+  }
+  const rows = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json') || entry.name === 'index.json') continue;
+    const value = JSON.parse(await fs.readFile(path.join(dir, entry.name), 'utf8'));
+    rows.push({ requestId: value.requestId, status: value.status, kind: value.kind, title: value.title, createdAt: value.createdAt, answeredAt: value.answer?.answeredAt || null });
+  }
+  rows.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  await writeJsonAtomic(path.join(dir, 'index.json'), { schemaVersion: SCHEMA_VERSION, actions: rows });
+  return rows;
+}
+
+async function createUserAction(projectDir, input) {
+  const request = normalizeRequest(projectDir, input);
+  await fs.mkdir(userActionsDir(projectDir), { recursive: true });
+  const filePath = requestPath(projectDir, request.requestId);
+  try {
+    await fs.access(filePath);
+    throw new Error(`user action already exists: ${request.requestId}`);
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+  }
+  await writeJsonAtomic(filePath, request);
+  await rebuildIndex(projectDir);
+  return request;
+}
+
+async function readUserAction(projectDir, requestId) {
+  if (!/^uar_[0-9a-f-]+$/.test(requestId)) throw new Error('invalid request id');
+  return JSON.parse(await fs.readFile(requestPath(projectDir, requestId), 'utf8'));
+}
+
+async function listUserActions(projectDir, { status = null } = {}) {
+  const rows = await rebuildIndex(projectDir);
+  return status ? rows.filter((row) => row.status === status) : rows;
+}
+
+// A ref recorded with `sha256` pins the artifact the person reviewed. Answering
+// after that artifact changed (or disappeared) would approve something nobody looked at, so
+// the answer is refused and the request stays pending. Refs without `sha256` are unchecked.
+// Accepts a bare hex digest or a `sha256:`-prefixed one.
+function staleArtifactRefs(projectDir, request) {
+  const stale = [];
+  for (const ref of Array.isArray(request.artifactRefs) ? request.artifactRefs : []) {
+    if (!ref || !ref.sha256) continue;
+    const expected = String(ref.sha256).trim().toLowerCase().replace(/^sha256:/, '');
+    let actual = null;
+    try {
+      actual = hashArtifact(projectDir, ref.path);
+    } catch {
+      actual = null;
+    }
+    if (actual !== expected) stale.push({ path: ref.path, expected, actual });
+  }
+  return stale;
+}
+
+class UserActionStaleError extends Error {
+  constructor(requestId, stale) {
+    super(`user_action_stale: ${stale.map((entry) => entry.path).join(', ')} changed since request ${requestId} was created; the answer was not recorded. Regenerate the request from the current artifacts and ask again.`);
+    this.code = 'user_action_stale';
+    this.requestId = requestId;
+    this.staleArtifacts = stale;
+  }
+}
+
+async function answerUserAction(projectDir, requestId, answer, { applyEffect } = {}) {
+  const request = await readUserAction(projectDir, requestId);
+  const mode = request.response?.mode;
+  let normalized;
+  if (answer.choice !== undefined) {
+    if (mode !== 'choice') throw new Error('this request does not accept a choice');
+    if (!request.choices.some((choice) => choice.id === answer.choice)) throw new Error('choice is not allowed for this request');
+    const note = assertSafeText(answer.note, 'answer note', { max: 10000, required: false });
+    normalized = { choice: answer.choice, ...(note ? { note } : {}) };
+  } else if (answer.text !== undefined) {
+    if (mode !== 'text') throw new Error('this request does not accept text');
+    normalized = { text: assertSafeText(answer.text, 'answer text', { max: 10000 }) };
+  } else if (answer.acknowledged === true) {
+    if (mode !== 'none' || request.kind !== 'manual_action') throw new Error('only a manual action with response mode none accepts acknowledgement');
+    const note = assertSafeText(answer.note, 'acknowledgement note', { max: 10000, required: false });
+    normalized = { acknowledged: true, ...(note ? { note } : {}) };
+  } else {
+    throw new Error('answer requires choice, text, or acknowledgement');
+  }
+  if (request.status === 'answered') {
+    const existing = request.answer && (request.answer.choice ? { choice: request.answer.choice, ...(request.answer.note ? { note: request.answer.note } : {}) } : request.answer.text ? { text: request.answer.text } : { acknowledged: request.answer.acknowledged === true, ...(request.answer.note ? { note: request.answer.note } : {}) });
+    if (JSON.stringify(existing) === JSON.stringify(normalized)) {
+      if (request.effect?.kind === 'read-back-omission-ack' && typeof applyEffect === 'function') await applyEffect(request, normalized);
+      return request;
+    }
+    throw new Error('user action already has a different answer');
+  }
+  if (request.status !== 'pending') throw new Error(`user action is not pending: ${request.status}`);
+  const stale = staleArtifactRefs(projectDir, request);
+  const mappingApproval = request.effect?.kind === 'approval' && request.effect.approvalType === 'mapping';
+  const rejectingMapping = mappingApproval && ['declined', 'reject'].includes(normalized.choice);
+  // The mapping binder owns census-reference refusal ordering (missing, stale inputs,
+  // then stale request). Other pinned artifacts retain the generic freshness gate.
+  const unboundStale = mappingApproval && typeof applyEffect === 'function'
+    ? stale.filter(entry => !request.artifactRefs.some(ref => ref.kind === 'census-reconciliation' && ref.path === entry.path))
+    : stale;
+  if (!rejectingMapping && unboundStale.length) throw new UserActionStaleError(requestId, unboundStale);
+  if (request.effect && typeof applyEffect === 'function') await applyEffect(request, normalized);
+  request.status = 'answered';
+  request.answer = { ...normalized, answeredAt: new Date().toISOString() };
+  await writeJsonAtomic(requestPath(projectDir, requestId), request);
+  await rebuildIndex(projectDir);
+  return request;
+}
+
+// Every public approval dispatcher uses this disk-bound reference builder.
+async function approvalArtifactRefs(projectDir, { approvalType, status, decidedBy, artifactRefs = [], requireRequestRef = false }) {
+  const requestRef = artifactRefs.find(ref => ref && typeof ref === 'object' && ref.kind === 'census-reconciliation') || null;
+  const { bindCensusReconciliation } = require('./census-reconciliation.js');
+  const bound = await bindCensusReconciliation(projectDir, { approvalType, status, decidedBy, requestRef: requireRequestRef ? requestRef : null });
+  if (!bound.ok) throw Object.assign(new Error(bound.code), bound);
+  if (bound.ref && requireRequestRef && !requestRef) throw Object.assign(new Error('approval_missing_census_reference'), { code: 'approval_missing_census_reference' });
+  const refs = artifactRefs.filter(ref => !ref || typeof ref !== 'object' || ref.kind !== 'census-reconciliation').map(ref => typeof ref === 'object' ? ref.path : ref);
+  return bound.ref ? [...refs, bound.ref] : refs;
+}
+
+module.exports = {
+  approvalArtifactRefs,
+  normalizeArtifact,
+  SCHEMA_VERSION,
+  userActionsDir,
+  requestPath,
+  createUserAction,
+  readUserAction,
+  listUserActions,
+  answerUserAction,
+  rebuildIndex,
+  staleArtifactRefs,
+  UserActionStaleError,
+};