@wix/agent-skills 1.36.0 → 1.36.1

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

@@ -1,315 +0,0 @@
-'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

@@ -1,42 +0,0 @@
-'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

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