Skip to content

amanpal3/Dr-SKILLs / .agent/skills/archify

archify

Unverified

Create validated architecture, workflow, sequence, data-flow, lifecycle/state, ERD, class, tree, timeline, and waterfall diagrams as explorable standalone HTML with dark/light themes, motion and image/SVG/WebM export. Accept requirements or Mermaid; inspect repository evidence for code-backed diagrams. Use when visualizing systems, API calls, pipelines, schemas, histories, timings, or everyday steps, parts, relationships and states. Also turn an answer into a one-page explainer, with the conclusion first, structured panels, native diagrams and charts, when the user asks for a page, an explainer or an answer to share (做成一页, 用页面讲), or proactively when the user's rules opt in with an [archify explainer: ...] line. Not for dashboards.

FileKindSize
LICENSEother11.1 KB
LICENSE-MITother1.1 KB
NOTICEother1.3 KB
SKILL.mdskill md18.4 KB
THIRD_PARTY_NOTICES.mdmarkdown5.5 KB
assets/JetBrainsMono-OFL.txtmarkdown4.3 KB
assets/template.htmlother768.9 KB
bin/archify.mjsscript282.0 KB
bin/delivery-update.mjsscript3.6 KB
bin/finalize.mjsscript48.9 KB
bin/open-artifact.mjsscript4.0 KB
bin/preview.mjsscript35.8 KB
bin/recover-output.mjsscript1.3 KB
bin/visual-check.mjsscript117.7 KB
brand-marks/README.mdmarkdown1.4 KB
brand-marks/catalog.jsonconfig13.8 KB
delta/architecture-delta.mjsscript77.2 KB
examples/agent-run.lifecycle.jsonconfig3.2 KB
examples/agent-tool-call.workflow.jsonconfig4.8 KB
examples/archify-dev-activity.timeline.jsonconfig4.4 KB
examples/archify-repository.tree.jsonconfig4.3 KB
examples/async-job-roundtrip.sequence.jsonconfig3.7 KB
examples/brand-aware-delivery.architecture.jsonconfig2.7 KB
examples/cache-miss-request.sequence.jsonconfig3.7 KB
examples/checkout-platform.base.architecture.jsonconfig2.2 KB
examples/checkout-platform.head.architecture.jsonconfig2.4 KB
examples/checkout-request.waterfall.jsonconfig1.2 KB
examples/class-payment-processors-rendered.htmlother854.5 KB
examples/class-payments-rendered.htmlother821.1 KB
examples/dataflow-product-analytics.htmlother824.1 KB
examples/delivery.explainer.jsonconfig4.5 KB
examples/deployment-release.lifecycle.jsonconfig4.1 KB
examples/erd-orders-rendered.htmlother841.1 KB
examples/event-stream.dataflow.jsonconfig4.7 KB
examples/example-rebuild.waterfall.jsonconfig4.5 KB
examples/holiday-planning.workflow.jsonconfig2.9 KB
examples/incident-response.workflow.jsonconfig4.6 KB
examples/lifecycle-agent-run.htmlother827.8 KB
examples/locales/de.jsonconfig27.8 KB
examples/locales/fr.jsonconfig28.6 KB
examples/locales/fr.partial.jsonconfig959 B
examples/locales/it.jsonconfig28.1 KB
examples/locales/ja.jsonconfig31.7 KB
examples/locales/pt.jsonconfig27.8 KB
examples/locales/ru.jsonconfig36.1 KB
examples/orders.erd.jsonconfig7.1 KB
examples/payment-incident.timeline.jsonconfig1.4 KB
examples/payment-platform.tree.jsonconfig1.2 KB
examples/payment-processors.class.jsonconfig7.1 KB
examples/payments.class.jsonconfig2.8 KB
examples/product-analytics.dataflow.jsonconfig4.9 KB
examples/production-deployment.architecture.jsonconfig4.6 KB
examples/release-delivery.workflow.jsonconfig4.4 KB
examples/sequence-cache-miss-request.htmlother821.8 KB
examples/subscription-billing-rendered.htmlother863.5 KB
examples/subscription-billing.erd.jsonconfig11.5 KB
examples/timeline-archify-dev-activity-rendered.htmlother846.2 KB
examples/timeline-payment-incident-rendered.htmlother814.5 KB
examples/tree-archify-repository-rendered.htmlother856.8 KB
examples/tree-payment-platform-rendered.htmlother820.0 KB
examples/waterfall-checkout-request-rendered.htmlother813.9 KB
examples/waterfall-example-rebuild-rendered.htmlother843.0 KB
examples/web-app-rendered.htmlother826.4 KB
examples/web-app.architecture.jsonconfig3.1 KB
examples/workflow-agent-tool-call-rendered.htmlother831.3 KB
explainer/browser-check.mjsscript30.0 KB
explainer/charts.mjsscript5.9 KB
explainer/check.mjsscript14.5 KB
explainer/diagrams.mjsscript37.8 KB
explainer/diff.mjsscript8.3 KB
explainer/inline.mjsscript8.5 KB
explainer/layout.mjsscript2.5 KB
explainer/page-bundle.mjsscript1.1 KB
explainer/parse.mjsscript26.6 KB
explainer/patch.mjsscript11.8 KB
explainer/prepare.mjsscript9.6 KB
explainer/reader.cssother46.1 KB
explainer/reader.jsscript50.5 KB
explainer/render.mjsscript33.2 KB
explainer/revision.mjsscript1.9 KB
explainer/sources.mjsscript20.4 KB
explainer/validate.mjsscript14.2 KB
explainer/writing.mjsscript11.1 KB
locales/README.mdmarkdown2.2 KB
locales/ar.jsonconfig33.0 KB
locales/en.jsonconfig26.7 KB
locales/es.jsonconfig28.8 KB
locales/ko.jsonconfig30.1 KB
locales/manifest.jsonconfig293 B
locales/zh-CN.jsonconfig26.4 KB
locales/zh-TW.jsonconfig26.5 KB
migrations/workflow-v2.mjsscript9.0 KB
package.jsonmanifest400 B
recipes/scenarios.mjsscript40.5 KB
references/architecture-layout-repair.mdmarkdown4.3 KB
references/authoring-contract.mdmarkdown41.7 KB
references/authoring-defaults.mdmarkdown12.6 KB
references/brand-marks.mdmarkdown5.6 KB
references/delivery-contract.mdmarkdown48.7 KB
references/explainer-authoring.mdmarkdown18.5 KB
references/repository-authoring.mdmarkdown7.8 KB
references/update-awareness.mdmarkdown1.9 KB
references/viewer-runtime.mdmarkdown5.6 KB
renderers/architecture/grid.mjsscript2.0 KB
renderers/architecture/labels.mjsscript155 B
renderers/architecture/render-architecture.mjsscript57.2 KB
renderers/architecture/routing.mjsscript72.7 KB
renderers/class/README.mdmarkdown6.6 KB
renderers/class/render-class.mjsscript52.3 KB
renderers/dataflow/README.mdmarkdown9.0 KB
renderers/dataflow/dataflow-compiler.mjsscript89.1 KB
renderers/dataflow/joint-label-routing.mjsscript10.6 KB
renderers/dataflow/label-capacity.mjsscript4.3 KB
renderers/dataflow/render-dataflow.mjsscript960 B
renderers/erd/README.mdmarkdown14.2 KB
renderers/erd/grid.mjsscript6.9 KB
renderers/erd/render-erd.mjsscript78.6 KB
renderers/explainer/render-explainer.mjsscript3.2 KB
renderers/lifecycle/README.mdmarkdown6.0 KB
renderers/lifecycle/render-lifecycle.mjsscript59.9 KB
renderers/sequence/README.mdmarkdown8.5 KB
renderers/sequence/render-sequence.mjsscript55.8 KB
renderers/shared/atomic-output.mjsscript68.7 KB
renderers/shared/automatic-labels.mjsscript14.4 KB
renderers/shared/brand-marks.mjsscript28.3 KB
renderers/shared/cli.mjsscript18.6 KB
renderers/shared/desktop-readability.mjsscript6.8 KB
renderers/shared/diagnostics.mjsbinary8.1 KB
renderers/shared/engineering-profiles.mjsscript6.8 KB
renderers/shared/generated-brand-marks.mjsscript159.8 KB
renderers/shared/generated-validators.mjsscript996.1 KB
renderers/shared/geometry.mjsscript87.8 KB
renderers/shared/i18n.mjsscript13.5 KB
renderers/shared/layout-report.mjsscript1.5 KB
renderers/shared/legend.mjsscript9.0 KB
renderers/shared/node-card-style.mjsscript2.4 KB
renderers/shared/output-path.mjsscript18.6 KB
renderers/shared/owned-temp-directory.mjsscript3.1 KB
renderers/shared/path-semantics.mjsscript31.6 KB
renderers/shared/portable-path.mjsscript12.2 KB
renderers/shared/repository-evidence.mjsscript19.9 KB
renderers/shared/repository-location.mjsscript4.2 KB
renderers/shared/route-quality.mjsscript26.3 KB
renderers/shared/sidecar-path.mjsscript1.2 KB
renderers/shared/software-notices.mjsscript506 B
renderers/shared/spatial-grid.mjsscript2.4 KB
renderers/shared/svg-path-analysis.mjsscript5.3 KB
renderers/shared/text-fit.mjsscript5.1 KB
renderers/shared/utils.mjsscript12.7 KB
renderers/shared/validator.mjsscript3.3 KB
renderers/timeline/README.mdmarkdown4.0 KB
renderers/timeline/render-timeline.mjsscript29.6 KB
renderers/tree/README.mdmarkdown4.2 KB
renderers/tree/render-tree.mjsscript29.9 KB
renderers/waterfall/README.mdmarkdown3.4 KB
renderers/waterfall/render-waterfall.mjsscript22.5 KB
renderers/workflow/README.mdmarkdown17.3 KB
renderers/workflow/render-workflow.mjsscript1.6 KB
renderers/workflow/workflow-compiler.mjsscript244.3 KB
renderers/workflow/workflow-migration-geometry.mjsscript6.2 KB
renderers/workflow/workflow-placement-repair.mjsscript4.7 KB
schemas/README.mdmarkdown14.7 KB
schemas/architecture.schema.jsonconfig5.9 KB
schemas/class.schema.jsonconfig7.9 KB
schemas/common.schema.jsonconfig5.6 KB
schemas/dataflow.schema.jsonconfig6.2 KB
schemas/erd.schema.jsonconfig9.1 KB
schemas/explainer.schema.jsonconfig18.8 KB
schemas/lifecycle.schema.jsonconfig5.2 KB
schemas/sequence.schema.jsonconfig6.0 KB
schemas/timeline.schema.jsonconfig3.9 KB
schemas/tree.schema.jsonconfig3.1 KB
schemas/waterfall.schema.jsonconfig3.4 KB
schemas/workflow.schema.jsonconfig9.9 KB
scripts/check-render-output.mjsscript66.9 KB
scripts/check-update.mjsscript57.9 KB
scripts/delivery-update-child.mjsscript1.3 KB
scripts/render-examples.mjsscript2.0 KB
scripts/update-contract.mjsscript6.7 KB
skill-release.jsonconfig260 B

bin/archify.mjs

View on GitHub
#!/usr/bin/env node

import { spawnSync } from 'node:child_process';
import { createHash, randomUUID } from 'node:crypto';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '..');

const TYPES = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle', 'erd', 'tree', 'class', 'timeline', 'waterfall', 'explainer']);
const DELIVERY_SIDECAR_SUFFIXES = Object.freeze([
  '.delivery.json',
  '.delivery-pending.json',
  '.delivery-lock.json',
]);
const COMPARE_SIDECAR_SUFFIXES = Object.freeze(['.receipt.json']);
const DELIVERY_DIRECTORY_LOCK = '.archify-delivery-lock.json';
let sidecarNamespaceComponentKeyRuntime;
let boundedSidecarStem;
let isBoundedSidecarStem;
let sidecarStemFromComponent;
let sidecarStemNeedsBounding;

async function loadSidecarPathRuntime() {
  ({
    boundedSidecarStem,
    isBoundedSidecarStem,
    sidecarStemFromComponent,
    sidecarStemNeedsBounding,
  } = await import('../renderers/shared/sidecar-path.mjs'));
}

function deliverySidecarNamespace(artifactPath) {
  let artifact = path.resolve(artifactPath);
  try {
    artifact = fs.realpathSync.native(artifact);
  } catch (error) {
    if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
  }
  if (typeof sidecarNamespaceComponentKeyRuntime !== 'function') {
    throw new Error('The sidecar namespace runtime is unavailable.');
  }
  const namespace = sidecarNamespaceComponentKeyRuntime(
    path.dirname(artifact),
    path.basename(artifact),
  );
  if (namespace.status !== 'resolved') {
    const error = new Error(
      `Could not establish a stable sidecar namespace (${namespace.reason?.code || 'unknown'}).`,
    );
    error.code = 'ARCHIFY_SIDECAR_NAMESPACE_INDETERMINATE';
    error.sidecarNamespaceReason = namespace.reason;
    throw error;
  }
  return { directory: namespace.directoryPath, ...sidecarStemFromComponent(namespace.componentKey) };
}

function deliverySidecarPath(artifactPath, suffix) {
  const { directory, stem, options } = deliverySidecarNamespace(artifactPath);
  return path.join(
    directory,
    `${boundedSidecarStem(stem, DELIVERY_SIDECAR_SUFFIXES, options)}${suffix}`,
  );
}

function deliveryProvenancePath(artifactPath) {
  return deliverySidecarPath(artifactPath, '.delivery.json');
}

function deliveryPendingPath(artifactPath) {
  return deliverySidecarPath(artifactPath, '.delivery-pending.json');
}

function rawHeadDeliverySidecarPath(artifactPath, suffix) {
  const { directory, stem, options } = deliverySidecarNamespace(artifactPath);
  if (options?.force) return undefined;
  if (sidecarStemNeedsBounding(stem, DELIVERY_SIDECAR_SUFFIXES)
    || !isBoundedSidecarStem(stem)) return undefined;
  return path.join(directory, `${stem}${suffix}`);
}

function rawHeadDeliveryProvenancePath(artifactPath) {
  return rawHeadDeliverySidecarPath(artifactPath, '.delivery.json');
}

function rawHeadDeliveryPendingPath(artifactPath) {
  return rawHeadDeliverySidecarPath(artifactPath, '.delivery-pending.json');
}

function legacyExtensionDeliverySidecarPath(artifactPath, suffix) {
  let artifact = path.resolve(artifactPath);
  try {
    artifact = fs.realpathSync.native(artifact);
  } catch (error) {
    if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
  }
  const component = path.basename(artifact);
  if (!/\.html$/iu.test(component) || component.endsWith('.html')) return undefined;
  const legacyComponent = `${component.slice(0, -'.html'.length)}${suffix}`;
  if (legacyComponent.length > 255 || Buffer.byteLength(legacyComponent, 'utf8') > 255) {
    return undefined;
  }
  return path.join(path.dirname(artifact), legacyComponent);
}

function canonicalExistingDeliveryOutput(outputPath) {
  const output = path.resolve(outputPath);
  try {
    return fs.realpathSync.native(output);
  } catch (error) {
    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return output;
    throw error;
  }
}

function legacyDeliveryLockPath(artifactPath) {
  const artifact = path.resolve(artifactPath);
  return `${artifact.replace(/\.html?$/i, '')}.delivery-lock.json`;
}

function legacyDeliveryLockPaths(artifactPaths) {
  const paths = [];
  for (const artifactPath of artifactPaths) {
    const lockPath = legacyDeliveryLockPath(artifactPath);
    const name = path.basename(lockPath);
    const canExist = process.platform === 'win32'
      ? name.length <= 255
      : Buffer.byteLength(name, 'utf8') <= 255;
    if (canExist && !paths.includes(lockPath)) paths.push(lockPath);
  }
  return paths;
}

function deliveryLockPath(artifactPath) {
  // A directory-wide mutex is deliberately conservative. Future 8.3, case,
  // and Unicode aliases cannot be assigned a sound canonical filename before
  // the artifact exists, so a per-artifact lock can split one delivery into
  // multiple owners. Provenance and pending journals remain artifact-specific.
  const artifact = path.resolve(artifactPath);
  let directory;
  try {
    directory = path.dirname(fs.realpathSync.native(artifact));
  } catch (error) {
    if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
    const authoredDirectory = path.dirname(artifact);
    try {
      directory = fs.realpathSync.native(authoredDirectory);
    } catch (directoryError) {
      if (directoryError?.code !== 'ENOENT' && directoryError?.code !== 'ENOTDIR') throw directoryError;
      directory = authoredDirectory;
    }
  }
  return path.join(directory, DELIVERY_DIRECTORY_LOCK);
}

function deliveryLockInvalid(lockPath) {
  return Object.assign(new Error(`Unrecognized delivery lock at "${lockPath}"; inspect the existing entry before retrying.`), {
    deliveryLockCode: 'delivery/lock-invalid',
    deliveryLockPath: lockPath,
  });
}

function regularDeliveryLockExists(lockPath) {
  try {
    if (!fs.lstatSync(lockPath).isFile()) throw deliveryLockInvalid(lockPath);
    return true;
  } catch (error) {
    if (error.deliveryLockCode) throw error;
    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
    throw deliveryLockInvalid(lockPath);
  }
}

function rejectExistingDeliveryLock(lockPath, output, fileBindingRuntime) {
  const {
    captureRegularFileBinding,
    releaseRegularFileBinding,
  } = fileBindingRuntime || {};
  let lock;
  let captured;
  try {
    if (typeof captureRegularFileBinding !== 'function'
      || typeof releaseRegularFileBinding !== 'function') {
      throw new Error('The regular-file binding runtime is unavailable.');
    }
    captured = captureRegularFileBinding(lockPath, {
      subject: 'delivery-lock',
      expectedLinks: 1,
      includeContent: true,
    });
    if (captured.status !== 'captured') throw new Error('Not a stable regular lock file.');
    lock = JSON.parse(captured.content.buffer.toString('utf8'));
    if (lock?.schemaVersion !== 1 || !Number.isSafeInteger(lock.pid) || lock.pid <= 0
      || typeof lock.receiptId !== 'string'
      || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(lock.receiptId)) {
      throw new Error('Unrecognized delivery lock.');
    }
  } catch {
    throw deliveryLockInvalid(lockPath);
  } finally {
    if (captured?.binding) releaseRegularFileBinding(captured.binding);
  }
  if (processIsRunning(lock.pid)) {
    throw Object.assign(new Error(`Another delivery attempt owns "${output}" through lock "${lockPath}".`), {
      deliveryLockCode: 'delivery/concurrent-attempt',
      deliveryLockPath: lockPath,
    });
  }
  throw Object.assign(new Error(`A stale delivery lock remains at "${lockPath}"; recover it serially before retrying.`), {
    deliveryLockCode: 'delivery/lock-stale',
    deliveryLockPath: lockPath,
    deliveryLockOwner: { pid: lock.pid, receiptId: lock.receiptId },
  });
}

function processIsRunning(pid) {
  if (!Number.isInteger(pid) || pid <= 0) return false;
  try {
    process.kill(pid, 0);
    return true;
  } catch (error) {
    return error.code !== 'ESRCH';
  }
}

const deliveryOwnershipStates = new WeakMap();

function deliveryOwnershipFailure(state, operation, reason, evidence = {}) {
  const error = new Error(`Delivery ownership was lost while attempting to ${operation}: ${reason}`);
  error.deliveryOwnershipCode = 'delivery/ownership-lost';
  error.deliveryOwnershipDetails = {
    operation,
    lock: state?.lockPath,
    expectedReceiptId: state?.receiptId,
    reason,
    ...evidence,
  };
  if (state && state.phase !== 'released') state.phase = 'lost';
  return error;
}

function deliveryOwnershipState(ownership, operation) {
  const state = deliveryOwnershipStates.get(ownership);
  if (!state) throw deliveryOwnershipFailure(undefined, operation, 'the ownership capability is invalid');
  if (state.phase === 'lost' || state.phase === 'released') {
    throw deliveryOwnershipFailure(state, operation, `the capability is already ${state.phase}`);
  }
  return state;
}

function sameFileIdentity(actual, expected) {
  const hasIdentity = (entry) => entry?.ino !== undefined && entry.ino !== 0 && entry.ino !== 0n;
  return hasIdentity(actual)
    && hasIdentity(expected)
    && actual.dev === expected.dev
    && actual.ino === expected.ino;
}

function assertOwnedDeliveryLock(state, ownedLock, operation, { verifyReceipt = true } = {}) {
  const {
    captureRegularFileBinding,
    releaseRegularFileBinding,
  } = state?.fileBindingRuntime || {};
  let captured;
  try {
    if (typeof captureRegularFileBinding !== 'function'
      || typeof releaseRegularFileBinding !== 'function') {
      throw new Error('The regular-file binding runtime is unavailable.');
    }
    captured = captureRegularFileBinding(ownedLock.path, {
      subject: 'owned-delivery-lock',
      ...(ownedLock.content ? {
        expectedSha256: ownedLock.content.sha256,
        expectedBytes: ownedLock.content.bytes,
      } : {}),
      expectedMode: Number(ownedLock.identity.mode & 0o777n),
      expectedLinks: 1,
      includeContent: verifyReceipt,
    });
  } catch (error) {
    throw deliveryOwnershipFailure(state, operation, 'an owned lock entry can no longer be inspected', {
      lock: ownedLock.path,
      ...(error?.code ? { systemCode: error.code } : {}),
    });
  }
  if (captured.status !== 'captured'
    || captured.identity.device !== ownedLock.identity.dev
    || captured.identity.inode !== ownedLock.identity.ino) {
    if (captured?.binding) releaseRegularFileBinding(captured.binding);
    throw deliveryOwnershipFailure(state, operation, 'an owned lock path no longer names the entry created by this attempt', {
      lock: ownedLock.path,
      ...(captured?.reason ? { lockState: captured.reason } : {}),
    });
  }
  try {
    if (!verifyReceipt) return;
    let lock;
    try {
      lock = JSON.parse(captured.content.buffer.toString('utf8'));
    } catch (error) {
      throw deliveryOwnershipFailure(state, operation, 'an owned lock receipt can no longer be verified', {
        lock: ownedLock.path,
        ...(error?.code ? { systemCode: error.code } : {}),
      });
    }
    if (lock?.schemaVersion !== 1 || lock.receiptId !== state.receiptId || lock.pid !== state.pid) {
      throw deliveryOwnershipFailure(state, operation, 'an owned lock receipt no longer matches this attempt', {
        lock: ownedLock.path,
        ...(typeof lock?.receiptId === 'string' ? { observedReceiptId: lock.receiptId } : {}),
      });
    }
  } catch (error) {
    throw error;
  } finally {
    releaseRegularFileBinding(captured.binding);
  }
}

function assertDeliveryOwnership(ownership, operation, { allowInitializing = false, pending = 'ignore' } = {}) {
  const state = deliveryOwnershipState(ownership, operation);
  const verifyReceipt = !allowInitializing || !['acquiring', 'initializing'].includes(state.phase);
  for (const ownedLock of state.ownedLocks) {
    assertOwnedDeliveryLock(state, ownedLock, operation, { verifyReceipt });
  }
  if (pending !== 'ignore') {
    const pendingPath = state.pendingPath;
    if (pending === 'absent') {
      try {
        fs.lstatSync(pendingPath);
      } catch (error) {
        if (error.code === 'ENOENT') return state;
        throw deliveryOwnershipFailure(state, operation, 'the finalized delivery journal can no longer be inspected', {
          journal: pendingPath,
          ...(error?.code ? { systemCode: error.code } : {}),
        });
      }
      throw deliveryOwnershipFailure(state, operation, 'the finalized delivery journal was recreated', { journal: pendingPath });
    }
    const {
      captureRegularFileBinding,
      releaseRegularFileBinding,
    } = state.fileBindingRuntime || {};
    let captured;
    try {
      if (typeof captureRegularFileBinding !== 'function'
        || typeof releaseRegularFileBinding !== 'function') {
        throw new Error('The regular-file binding runtime is unavailable.');
      }
      captured = captureRegularFileBinding(pendingPath, {
        subject: 'owned-delivery-journal',
        expectedSha256: state.pendingContent?.sha256,
        expectedBytes: state.pendingContent?.bytes,
        expectedMode: state.pendingIdentity?.mode,
        expectedLinks: 1,
        includeContent: pending === 'owned',
      });
    } catch (error) {
      throw deliveryOwnershipFailure(state, operation, 'the owned delivery journal can no longer be inspected', {
        journal: pendingPath,
        ...(error?.code ? { systemCode: error.code } : {}),
      });
    }
    if (captured.status !== 'captured'
      || !state.pendingIdentity
      || captured.identity.device !== state.pendingIdentity.dev
      || captured.identity.inode !== state.pendingIdentity.ino) {
      if (captured?.binding) releaseRegularFileBinding(captured.binding);
      throw deliveryOwnershipFailure(state, operation, 'the delivery journal no longer names the entry created by this attempt', {
        journal: pendingPath,
        ...(captured?.reason ? { journalState: captured.reason } : {}),
      });
    }
    try {
      if (pending === 'owned') {
        let journal;
        try {
          journal = JSON.parse(captured.content.buffer.toString('utf8'));
        } catch {
          throw deliveryOwnershipFailure(state, operation, 'the delivery journal receipt is malformed', {
            journal: pendingPath,
          });
        }
        if (journal?.receiptId !== state.receiptId) {
          throw deliveryOwnershipFailure(state, operation, 'the delivery journal receipt belongs to another attempt', {
            journal: pendingPath,
            ...(typeof journal?.receiptId === 'string' ? { observedReceiptId: journal.receiptId } : {}),
          });
        }
      }
    } finally {
      releaseRegularFileBinding(captured.binding);
    }
  }
  return state;
}

function quarantineRemoveOwnedDeliveryEntry(state, {
  filePath,
  identity,
  content,
  subject,
  operation,
  evidenceKey,
}) {
  const {
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    releaseRegularFileBinding,
  } = state?.fileBindingRuntime || {};
  let captured;
  try {
    if (typeof captureRegularFileBinding !== 'function'
      || typeof quarantineRemoveRegularFileBinding !== 'function'
      || typeof releaseRegularFileBinding !== 'function') {
      throw new Error('The regular-file binding runtime is unavailable.');
    }
    captured = captureRegularFileBinding(filePath, {
      subject,
      ...(content ? {
        expectedSha256: content.sha256,
        expectedBytes: content.bytes,
      } : {}),
      expectedMode: typeof identity?.mode === 'bigint'
        ? Number(identity.mode & 0o777n)
        : identity?.mode,
      expectedIdentity: {
        device: identity?.dev,
        inode: identity?.ino,
      },
      expectedLinks: 1,
    });
  } catch (error) {
    throw deliveryOwnershipFailure(state, operation, `the owned ${subject} can no longer be captured for removal`, {
      [evidenceKey]: filePath,
      ...(error?.code ? { systemCode: error.code } : {}),
    });
  }
  if (captured.status !== 'captured') {
    throw deliveryOwnershipFailure(state, operation, `the owned ${subject} changed before removal`, {
      [evidenceKey]: filePath,
      entryState: captured.reason,
    });
  }
  try {
    const removed = quarantineRemoveRegularFileBinding(captured.binding, filePath, {
      subject,
      expectedLinks: 1,
    });
    if (removed.status === 'removed') return;
    const removalCode = removed.reason?.code;
    if (removed.status === 'unknown'
      && ['removal-quarantine-create-failed', `${subject}-quarantine-move-failed`]
        .includes(removalCode)) {
      const detail = removed.reason?.message ? `: ${removed.reason.message}` : '';
      const error = new Error(`The owned ${subject} could not be moved into its private removal quarantine (${removalCode})${detail}.`);
      if (removed.reason?.systemCode) error.code = removed.reason.systemCode;
      if (subject === 'delivery-lock') {
        error.deliveryOwnershipCode = 'delivery/lock-release';
        error.deliveryOwnershipDetails = {
          operation,
          lock: filePath,
          reason: error.message,
          entryState: removed.reason,
        };
      } else {
        error.deliveryJournalRemovalState = removed;
      }
      throw error;
    }
    throw deliveryOwnershipFailure(
      state,
      operation,
      removed.status === 'recovery-required'
        ? `a replacement ${subject} could not be restored from quarantine`
        : `the public ${subject} changed during removal and was preserved`,
      {
        [evidenceKey]: filePath,
        entryState: removed.reason,
        ...(removed.status === 'recovery-required' ? {
          recoveryRequired: true,
          recoveryDirectory: removed.recoveryDirectory,
          recoveryFiles: [{
            label: `preserved replacement ${subject}`,
            path: removed.recoveryFile,
            target: filePath,
          }],
        } : {}),
      },
    );
  } finally {
    releaseRegularFileBinding(captured.binding);
  }
}

function releaseDeliveryOwnership(ownership, { allowInitializing = false } = {}) {
  const current = deliveryOwnershipState(ownership, 'release the delivery lock');
  const pending = current.phase === 'finalized'
    ? 'absent'
    : current.pendingIdentity
      ? 'identity'
      : 'ignore';
  const state = assertDeliveryOwnership(ownership, 'release the delivery lock', { allowInitializing, pending });
  const verifyReceipt = !allowInitializing || !['acquiring', 'initializing'].includes(state.phase);
  for (const ownedLock of state.ownedLocks) {
    assertOwnedDeliveryLock(state, ownedLock, 'release the delivery lock', { verifyReceipt });
    quarantineRemoveOwnedDeliveryEntry(state, {
      filePath: ownedLock.path,
      identity: ownedLock.identity,
      content: ownedLock.content,
      subject: 'delivery-lock',
      operation: 'release the delivery lock',
      evidenceKey: 'lock',
    });
  }
  state.phase = 'released';
}

function acquireDeliveryLock(
  output,
  receiptId,
  inputPath,
  pathsAlias,
  recordInitializationFailure,
  legacyOutputPaths = [],
  fileBindingRuntime,
) {
  const stableOutput = canonicalExistingDeliveryOutput(output);
  const lockPath = deliveryLockPath(stableOutput);
  const comparableLockPath = (candidate) => {
    const absolute = path.resolve(candidate);
    try {
      return path.join(fs.realpathSync.native(path.dirname(absolute)), path.basename(absolute));
    } catch (error) {
      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
      return absolute;
    }
  };
  const lockPathsAlias = (left, right) => {
    const comparableLeft = comparableLockPath(left);
    const comparableRight = comparableLockPath(right);
    if (!pathsAlias(path.dirname(comparableLeft), path.dirname(comparableRight))) return false;
    return pathsAlias(comparableLeft, comparableRight);
  };
  const legacyFencePathsAlias = (left, right) => {
    const comparableLeft = comparableLockPath(left);
    const comparableRight = comparableLockPath(right);
    if (comparableLeft === comparableRight) return true;
    try {
      return lockPathsAlias(comparableLeft, comparableRight);
    } catch {
      // An indeterminate future-name relation is not evidence of aliasing.
      // Keep both candidates; an EEXIST below is accepted only when dev/ino
      // proves that it names a lock already created by this attempt.
      return false;
    }
  };
  const legacyLockPaths = [];
  for (const candidate of legacyDeliveryLockPaths([
    ...legacyOutputPaths.filter(Boolean),
    output,
    stableOutput,
  ])) {
    if (!legacyLockPaths.some((existing) => legacyFencePathsAlias(candidate, existing))) {
      legacyLockPaths.push(candidate);
    }
  }
  const pendingPath = deliveryPendingPath(stableOutput);
  const provenancePath = deliveryProvenancePath(stableOutput);
  const rawHeadPendingPath = rawHeadDeliveryPendingPath(stableOutput);
  const existingLegacyLocks = legacyLockPaths.filter((candidate) => regularDeliveryLockExists(candidate));
  regularDeliveryLockExists(lockPath);
  const conflictingLockPath = [lockPath, ...legacyLockPaths]
    .find((candidate) => lockPathsAlias(candidate, inputPath));
  if (conflictingLockPath) {
    throw Object.assign(new Error('Delivery lock path aliases the input specification; choose another output path.'), {
      deliveryLockCode: 'delivery/lock-path-conflict',
      deliveryLockPath: conflictingLockPath,
    });
  }
  if (existingLegacyLocks.length) {
    rejectExistingDeliveryLock(existingLegacyLocks[0], output, fileBindingRuntime);
  }
  const openedLocks = [];
  const ownership = Object.freeze({});
  deliveryOwnershipStates.set(ownership, {
    output: stableOutput,
    lockPath,
    pendingPath,
    provenancePath,
    receiptId,
    pid: process.pid,
    ownedLocks: openedLocks,
    fileBindingRuntime,
    phase: 'acquiring',
  });
  let collisionPath;
  try {
    const openOwnedLock = (ownedLockPath, { allowOwnedAlias = false } = {}) => {
      let descriptor;
      try {
        descriptor = fs.openSync(ownedLockPath, 'wx', 0o600);
      } catch (error) {
        if (error.code === 'EEXIST' && allowOwnedAlias) {
          try {
            const existingEntry = fs.lstatSync(ownedLockPath, { bigint: true });
            if (existingEntry.isFile()
              && openedLocks.some((ownedLock) => sameFileIdentity(existingEntry, ownedLock.identity))) {
              return undefined;
            }
          } catch {
            // Preserve the original EEXIST classification below.
          }
        }
        if (error.code === 'EEXIST') collisionPath = ownedLockPath;
        throw error;
      }
      let handleIdentity;
      let handleIdentityError;
      try {
        handleIdentity = fs.fstatSync(descriptor, { bigint: true });
      } catch (error) {
        // A transient first inspection failure must not strand the public
        // lock. Bind ownership from the still-open handle before cleanup.
        try {
          handleIdentity = fs.fstatSync(descriptor, { bigint: true });
        } catch {
          // Both handle metadata reads failed. Stamp the still-open inode with
          // this attempt's unpredictable receipt before consulting the public
          // path. A replacement claimant cannot be mistaken for our empty
          // lock, while a successful content-bound capture gives cleanup the
          // identity it needs after the original descriptor is closed.
          const recoveryReceipt = `${JSON.stringify({ schemaVersion: 1, receiptId, pid: process.pid })}\n`;
          const recoveryContent = artifactIdentity(Buffer.from(recoveryReceipt));
          let captured;
          try {
            fs.writeFileSync(descriptor, recoveryReceipt);
            captured = fileBindingRuntime?.captureRegularFileBinding?.(ownedLockPath, {
              subject: 'owned-delivery-lock',
              expectedSha256: recoveryContent.sha256,
              expectedBytes: recoveryContent.bytes,
              expectedLinks: 1,
            });
          } catch {}
          if (captured?.status === 'captured') {
            fileBindingRuntime.releaseRegularFileBinding(captured.binding);
            openedLocks.push({
              path: ownedLockPath,
              identity: {
                dev: captured.identity.device,
                ino: captured.identity.inode,
                mode: BigInt(captured.mode),
              },
              content: recoveryContent,
              descriptor,
            });
          } else {
            try {
              fs.closeSync(descriptor);
            } catch (closeError) {
              error.lockCleanupError = closeError.message;
            }
          }
          throw error;
        }
        handleIdentityError = error;
      }
      const ownedLock = {
        path: ownedLockPath,
        identity: handleIdentity,
        descriptor,
      };
      openedLocks.push(ownedLock);
      const pathIdentity = fs.lstatSync(ownedLockPath, { bigint: true });
      if (!handleIdentity.isFile()
        || handleIdentity.ino === 0n
        || !pathIdentity.isFile()
        || pathIdentity.isSymbolicLink()
        || pathIdentity.ino === 0n
        || !sameFileIdentity(pathIdentity, handleIdentity)) {
        throw new Error('Delivery lock path identity could not be verified safely.');
      }
      if (handleIdentityError) throw handleIdentityError;
      return ownedLock;
    };

    openOwnedLock(lockPath);
    for (const legacyLockPath of legacyLockPaths) {
      openOwnedLock(legacyLockPath, { allowOwnedAlias: true });
    }
    const state = deliveryOwnershipStates.get(ownership);
    if (rawHeadPendingPath && pathEntryExists(rawHeadPendingPath)) {
      throw Object.assign(new Error(`A pre-namespace delivery journal remains at "${rawHeadPendingPath}"; recover it before retrying.`), {
        deliveryLockCode: 'delivery/legacy-pending',
        deliveryLockPath: rawHeadPendingPath,
      });
    }
    state.phase = 'initializing';
    const lockReceipt = `${JSON.stringify({ schemaVersion: 1, receiptId, pid: process.pid })}\n`;
    const lockContent = artifactIdentity(Buffer.from(lockReceipt));
    for (const ownedLock of openedLocks) {
      fs.writeFileSync(ownedLock.descriptor, lockReceipt);
      ownedLock.content = lockContent;
    }
    for (const ownedLock of openedLocks) {
      fs.closeSync(ownedLock.descriptor);
      ownedLock.descriptor = undefined;
    }
    state.phase = 'owned';
    return ownership;
  } catch (error) {
    for (const ownedLock of openedLocks) {
      if (ownedLock.descriptor === undefined) continue;
      try {
        fs.closeSync(ownedLock.descriptor);
        ownedLock.descriptor = undefined;
      } catch (closeError) {
        error.lockCleanupError = closeError.message;
      }
    }
    const state = deliveryOwnershipStates.get(ownership);
    let preserveOwnership = false;
    try {
      if (state.phase === 'initializing') {
        assertDeliveryOwnership(ownership, 'record a lock initialization failure', { allowInitializing: true });
        error.deliveryFailureRecord = recordInitializationFailure?.(error, ownership);
        if (error.deliveryFailureRecord?.journalRecovery) {
          error.deliveryJournalRecovery = error.deliveryFailureRecord.journalRecovery.deliveryJournalRecovery;
          preserveOwnership = true;
        }
        if (error.deliveryFailureRecord?.provenanceRecovery) {
          error.deliveryProvenanceRecovery = error.deliveryFailureRecord.provenanceRecovery.deliveryProvenanceRecovery;
          preserveOwnership = true;
        }
      }
      if (!preserveOwnership) {
        releaseDeliveryOwnership(ownership, { allowInitializing: true });
      }
    } catch (cleanupError) {
      if (cleanupError.deliveryOwnershipCode) {
        cleanupError.deliveryOwnershipDetails = {
          ...(cleanupError.deliveryOwnershipDetails || {}),
          initializationError: error.message,
          ...(error?.code ? { initializationSystemCode: error.code } : {}),
        };
        if (cleanupError.deliveryOwnershipCode === 'delivery/lock-release' && error.deliveryFailureRecord) {
          cleanupError.deliveryFailureRecord = error.deliveryFailureRecord;
        }
        throw cleanupError;
      }
      error.lockCleanupError = cleanupError.message;
    }
    if (collisionPath) rejectExistingDeliveryLock(collisionPath, output, fileBindingRuntime);
    throw error;
  }
}

function pathEntryExists(file) {
  try {
    fs.lstatSync(file);
    return true;
  } catch (error) {
    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
    throw error;
  }
}

function captureOwnedStagingFile(registry, filePath, fileBindingRuntime, {
  subject = 'private-staging-entry',
  content,
  expectedLinks = 1,
} = {}) {
  const { captureRegularFileBinding } = fileBindingRuntime || {};
  if (typeof captureRegularFileBinding !== 'function') {
    throw new Error('The regular-file binding runtime is unavailable.');
  }
  let captured = captureRegularFileBinding(filePath, {
    subject,
    ...(content ? {
      expectedSha256: content.sha256,
      expectedBytes: content.bytes,
    } : {}),
    expectedLinks,
  });
  if (captured.status === 'unsupported'
    && String(captured.reason?.code || '').endsWith('-hardlinked')
    && content) {
    const observedLinks = Number(captured.reason?.links);
    if (Number.isSafeInteger(observedLinks) && observedLinks > expectedLinks) {
      captured = captureRegularFileBinding(filePath, {
        subject,
        expectedSha256: content.sha256,
        expectedBytes: content.bytes,
        expectedLinks: observedLinks,
      });
      expectedLinks = observedLinks;
    }
  }
  if (captured.status !== 'captured') {
    const error = new Error(`Could not bind the owned staging entry "${filePath}" (${captured.reason?.code || 'unknown state'}).`);
    error.stagingCapture = captured;
    throw error;
  }
  registry.push({ filePath, binding: captured.binding, subject, expectedLinks });
  return captured;
}

function cleanupOwnedStagingDirectory(directory, identity, registry, fileBindingRuntime) {
  const {
    quarantineRemoveRegularFileBinding,
    releaseRegularFileBinding,
  } = fileBindingRuntime || {};
  if (typeof quarantineRemoveRegularFileBinding !== 'function'
    || typeof releaseRegularFileBinding !== 'function') {
    throw new Error('The regular-file binding runtime is unavailable.');
  }
  const failures = [];
  for (const entry of [...registry].reverse()) {
    try {
      const removed = quarantineRemoveRegularFileBinding(entry.binding, entry.filePath, {
        subject: entry.subject,
        expectedLinks: entry.expectedLinks,
      });
      // A missing path means the transaction already moved or finalized this
      // owned inode. Every other non-removal result is deliberately preserved:
      // it may be a concurrent claimant rather than an entry we created.
      if (removed.status !== 'removed'
        && !['ENOENT', 'ENOTDIR'].includes(removed.reason?.systemCode)) {
        failures.push(`${entry.filePath}: ${removed.reason?.code || removed.status}`);
      }
    } catch (error) {
      failures.push(`${entry.filePath}: ${error.message}`);
    } finally {
      const released = releaseRegularFileBinding(entry.binding);
      if (released.status !== 'released') {
        failures.push(`${entry.filePath}: ${released.reason?.code || released.status}`);
      }
    }
  }
  registry.length = 0;
  try {
    if (!removeOwnedEmptyStagingDirectory(directory, identity, { throwOnFailure: true })) {
      failures.push(`${directory}: staging directory was retained because its identity changed`);
    }
  } catch (error) {
    failures.push(`${directory}: ${error.message}`);
  }
  if (failures.length) throw new Error(failures.join('; '));
}

function createOwnedEmptyStagingDirectory(prefix) {
  // Node's Windows mkdtemp binding does not consistently promote an ordinary
  // UNC prefix past MAX_PATH. Use the equivalent namespaced spelling for the
  // syscall while preserving the same physical directory identity.
  const directory = fs.mkdtempSync(path.toNamespacedPath(prefix));
  const metadata = fs.lstatSync(directory, { bigint: true });
  if (!metadata.isDirectory() || metadata.isSymbolicLink() || metadata.ino === 0n) {
    throw new Error(`Private staging directory identity is unavailable: ${directory}`);
  }
  return {
    directory,
    identity: { device: metadata.dev, inode: metadata.ino },
  };
}

function createStagingRetirementQuarantine(parent) {
  for (let attempt = 0; attempt < 8; attempt += 1) {
    const directory = path.join(parent, `.archify-staging-remove-${randomUUID()}`);
    try {
      fs.mkdirSync(directory, { mode: 0o700 });
      return directory;
    } catch (error) {
      if (error?.code !== 'EEXIST') return undefined;
    }
  }
  return undefined;
}

const stagingRemovalSignal = new Int32Array(new SharedArrayBuffer(4));
const stagingRemovalAttempts = 10;

function removeEmptyStagingDirectoryWithRetry(directory) {
  let failure;
  for (let attempt = 0; attempt < stagingRemovalAttempts; attempt += 1) {
    try {
      fs.rmdirSync(directory);
      return;
    } catch (error) {
      failure = error;
      // SMB can acknowledge the last file removal before the directory view
      // catches up. Retrying an empty-directory removal is claimant-safe: any
      // real entry keeps returning ENOTEMPTY and is never removed recursively.
      if (error?.code !== 'ENOTEMPTY' || attempt === stagingRemovalAttempts - 1) break;
      Atomics.wait(
        stagingRemovalSignal,
        0,
        0,
        Math.min(5 * (2 ** attempt), 250),
      );
    }
  }
  throw failure;
}

function stagingDirectoryAppearsEmpty(directory) {
  for (let attempt = 0; attempt < stagingRemovalAttempts; attempt += 1) {
    try {
      if (fs.readdirSync(directory).length === 0) return true;
    } catch {
      return false;
    }
    if (attempt === stagingRemovalAttempts - 1) break;
    Atomics.wait(
      stagingRemovalSignal,
      0,
      0,
      Math.min(5 * (2 ** attempt), 250),
    );
  }
  return false;
}

function removeOwnedEmptyStagingDirectory(directory, identity, { throwOnFailure = false } = {}) {
  let current;
  try {
    current = fs.lstatSync(directory, { bigint: true });
  } catch (error) {
    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return false;
    throw error;
  }
  if (!current.isDirectory()
    || current.isSymbolicLink()
    || current.ino === 0n
    || current.dev !== identity.device
    || current.ino !== identity.inode) return false;
  if (!stagingDirectoryAppearsEmpty(directory)) return false;
  const quarantine = createStagingRetirementQuarantine(path.dirname(directory));
  if (!quarantine) return false;
  const movedPath = path.join(quarantine, path.basename(directory));
  try {
    fs.renameSync(directory, movedPath);
  } catch (error) {
    if (throwOnFailure) throw error;
    return false;
  }
  let moved;
  try {
    moved = fs.lstatSync(movedPath, { bigint: true });
  } catch {
    return false;
  }
  if (!moved.isDirectory()
    || moved.isSymbolicLink()
    || moved.ino === 0n
    || moved.dev !== identity.device
    || moved.ino !== identity.inode) {
    // A claimant won the public move boundary. Preserve it under the private
    // quarantine name; directories have no portable no-clobber restore link.
    return false;
  }
  try {
    // The unpredictable 0700 quarantine closes the public replacement race.
    // Never recurse: unexpected contents remain available for recovery.
    removeEmptyStagingDirectoryWithRetry(movedPath);
    removeEmptyStagingDirectoryWithRetry(quarantine);
    return true;
  } catch (error) {
    if (throwOnFailure) throw error;
    return false;
  }
}

function releaseOwnedStagingBindings(registry, fileBindingRuntime) {
  const { releaseRegularFileBinding } = fileBindingRuntime || {};
  if (typeof releaseRegularFileBinding !== 'function') return;
  for (const entry of registry) releaseRegularFileBinding(entry.binding);
  registry.length = 0;
}

function artifactIdentity(artifact) {
  return { sha256: createHash('sha256').update(artifact).digest('hex'), bytes: artifact.byteLength };
}

function beginDeliveryAttempt({ ownership, input, pathsAlias, fileBindingRuntime }) {
  const state = assertDeliveryOwnership(ownership, 'begin the delivery journal', { allowInitializing: true });
  const {
    output, pendingPath: journal, provenancePath, receiptId,
  } = state;
  for (const protectedPath of [input, output, provenancePath].filter(Boolean)) {
    if (pathsAlias(journal, protectedPath)) throw new Error('Delivery journal aliases an input or output.');
  }
  const published = writeDeliveryProvenance(journal, {
    schemaVersion: 1, command: 'deliver', status: 'pending', receiptId,
    input, output: path.resolve(output),
  }, {
    beforeReplace: () => assertDeliveryOwnership(ownership, 'create the delivery journal', { allowInitializing: true }),
    fileBindingRuntime,
  });
  state.pendingIdentity = {
    dev: published.identity.device,
    ino: published.identity.inode,
    mode: published.identity.mode,
  };
  state.pendingContent = published.content;
  assertDeliveryOwnership(ownership, 'finish creating the delivery journal', { allowInitializing: true });
}

function writeDeliveryProvenance(file, value, { beforeReplace, fileBindingRuntime } = {}) {
  const {
    backupPublicRegularFileBinding,
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    verifyRegularFileBinding,
    releaseRegularFileBinding,
  } = fileBindingRuntime || {};
  if (typeof captureRegularFileBinding !== 'function'
    || typeof backupPublicRegularFileBinding !== 'function'
    || typeof quarantineRemoveRegularFileBinding !== 'function'
    || typeof verifyRegularFileBinding !== 'function'
    || typeof releaseRegularFileBinding !== 'function') {
    const error = new Error('The regular-file binding runtime is unavailable.');
    error.deliveryJournalState = {
      status: 'unknown',
      reason: { code: 'atomic-output-runtime-unavailable' },
    };
    throw error;
  }
  const staging = createOwnedEmptyStagingDirectory(
    path.join(path.dirname(file), '.archify-provenance-'),
  );
  const stagingDirectory = staging.directory;
  const temporary = path.join(stagingDirectory, path.basename(file));
  const backup = path.join(stagingDirectory, '.previous-journal');
  const serialized = Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
  const expectedContent = artifactIdentity(serialized);
  let candidateCapture;
  let previousCapture;
  let candidatePresent = false;
  let backupPresent = false;
  let backupVerified = false;
  let published = false;
  let retainStaging = false;
  const bindingError = (result, action) => {
    const error = new Error(`Could not ${action} delivery journal "${file}" safely (${result.reason?.code || 'unknown target state'}).`);
    error.deliveryJournalState = result;
    return error;
  };
  try {
    fs.writeFileSync(temporary, serialized, { flag: 'wx' });
    candidatePresent = true;
    candidateCapture = captureRegularFileBinding(temporary, {
      subject: 'delivery-journal-candidate',
      expectedSha256: expectedContent.sha256,
      expectedBytes: expectedContent.bytes,
      expectedLinks: 1,
    });
    if (candidateCapture.status !== 'captured') throw bindingError(candidateCapture, 'prepare the');

    let existing = false;
    try {
      fs.lstatSync(file);
      existing = true;
    } catch (error) {
      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
    }
    if (existing) {
      previousCapture = captureRegularFileBinding(file, {
        subject: 'previous-delivery-journal',
        expectedLinks: 1,
      });
      if (previousCapture.status !== 'captured') {
        throw bindingError(previousCapture, 'snapshot the existing');
      }
    }
    beforeReplace?.();
    if (previousCapture) {
      const moved = backupPublicRegularFileBinding(previousCapture.binding, file, backup, {
        subject: 'previous-delivery-journal',
      });
      backupPresent = moved.backupCreated === true;
      backupVerified = moved.backupVerified === true;
      if (moved.status !== 'backed-up') throw bindingError(moved, 'back up the existing');
    }

    const ready = verifyRegularFileBinding(candidateCapture.binding, {
      filePath: temporary,
      expectedLinks: 1,
    });
    if (ready.status !== 'match') throw bindingError(ready, 'verify the staged');
    try {
      fs.linkSync(temporary, file);
    } catch (error) {
      if (error?.code === 'EEXIST') {
        throw bindingError({
          status: 'different',
          reason: { code: 'target-claimed-during-publish', phase: 'journal-publish' },
        }, 'publish the');
      }
      throw error;
    }
    published = true;
    for (const target of [temporary, file]) {
      const linked = verifyRegularFileBinding(candidateCapture.binding, {
        filePath: target,
        expectedLinks: 2,
      });
      if (linked.status !== 'match') throw bindingError(linked, 'verify the published');
    }
    const retiredCandidate = quarantineRemoveRegularFileBinding(
      candidateCapture.binding,
      temporary,
      { subject: 'delivery-journal-candidate', expectedLinks: 2 },
    );
    if (retiredCandidate.status !== 'removed') {
      retainStaging = true;
      throw bindingError(retiredCandidate, 'retire the staged');
    }
    candidatePresent = false;
    const finalized = verifyRegularFileBinding(candidateCapture.binding, {
      filePath: file,
      expectedLinks: 1,
    });
    if (finalized.status !== 'match') throw bindingError(finalized, 'finalize the');
    if (backupPresent) {
      const previous = verifyRegularFileBinding(previousCapture.binding, {
        filePath: backup,
        expectedLinks: 1,
      });
      if (previous.status !== 'match') throw bindingError(previous, 'verify the previous');
      const retiredBackup = quarantineRemoveRegularFileBinding(
        previousCapture.binding,
        backup,
        { subject: 'previous-delivery-journal', expectedLinks: 1 },
      );
      if (retiredBackup.status !== 'removed') {
        retainStaging = true;
        throw bindingError(retiredBackup, 'retire the previous');
      }
      backupPresent = false;
    }
    return {
      identity: candidateCapture.identity,
      content: candidateCapture.content,
    };
  } catch (cause) {
    const rollbackErrors = [];
    const publicRecoveryFiles = [];
    if (cause.deliveryJournalState?.status === 'recovery-required'
      && cause.deliveryJournalState.recoveryFile) {
      publicRecoveryFiles.push({
        label: 'preserved journal replacement',
        path: cause.deliveryJournalState.recoveryFile,
        target: file,
      });
    }
    if (published) {
      try {
        const removed = quarantineRemoveRegularFileBinding(candidateCapture.binding, file, {
          subject: 'published-delivery-journal',
          expectedLinks: candidatePresent ? 2 : 1,
        });
        if (removed.status === 'removed') {
          published = false;
        } else {
          rollbackErrors.push(`the published journal could not be removed safely (${removed.reason?.code || 'unknown target state'})`);
          if (removed.status === 'recovery-required') {
            publicRecoveryFiles.push({
              label: 'preserved journal replacement',
              path: removed.recoveryFile,
              target: file,
            });
          }
        }
      } catch (error) {
        if (error?.code !== 'ENOENT') rollbackErrors.push(`published journal cleanup failed (${error.message})`);
      }
    }
    if (candidatePresent) {
      try {
        const current = verifyRegularFileBinding(candidateCapture.binding, {
          filePath: temporary,
          expectedLinks: published ? 2 : 1,
        });
        if (current.status === 'match') {
          const retiredCandidate = quarantineRemoveRegularFileBinding(
            candidateCapture.binding,
            temporary,
            {
              subject: 'delivery-journal-candidate',
              expectedLinks: published ? 2 : 1,
            },
          );
          if (retiredCandidate.status !== 'removed') {
            throw bindingError(retiredCandidate, 'retire the staged');
          }
          candidatePresent = false;
        } else {
          rollbackErrors.push('the staged journal candidate was replaced before cleanup');
          retainStaging = true;
        }
      } catch (error) {
        if (error?.code !== 'ENOENT') rollbackErrors.push(`staged journal cleanup failed (${error.message})`);
      }
    }
    if (backupPresent) {
      try {
        if (!backupVerified) {
          throw new Error('the backup entry was never verified as the previous journal');
        }
        if (pathEntryExists(file)) throw new Error('a new journal claimant prevents restoring the previous journal');
        const previous = verifyRegularFileBinding(previousCapture.binding, {
          filePath: backup,
          expectedLinks: 1,
        });
        if (previous.status !== 'match') {
          backupVerified = false;
          throw bindingError(previous, 'verify the previous');
        }
        try {
          fs.linkSync(backup, file);
        } catch (error) {
          if (error?.code === 'EEXIST') {
            throw new Error('a new journal claimant prevents restoring the previous journal');
          }
          throw error;
        }
        for (const target of [backup, file]) {
          const restored = verifyRegularFileBinding(previousCapture.binding, {
            filePath: target,
            expectedLinks: 2,
          });
          if (restored.status !== 'match') throw bindingError(restored, 'verify the restored');
        }
        const retiredBackup = quarantineRemoveRegularFileBinding(
          previousCapture.binding,
          backup,
          { subject: 'previous-delivery-journal', expectedLinks: 2 },
        );
        if (retiredBackup.status !== 'removed') {
          throw bindingError(retiredBackup, 'retire the restored backup');
        }
        backupPresent = false;
        const restored = verifyRegularFileBinding(previousCapture.binding, {
          filePath: file,
          expectedLinks: 1,
        });
        if (restored.status !== 'match') throw bindingError(restored, 'finalize the restored');
      } catch (error) {
        rollbackErrors.push(`previous journal restore failed (${error.message})`);
        retainStaging = backupPresent || candidatePresent;
      }
    }
    const claimantConflict = cause.deliveryJournalState?.reason?.code === 'target-claimed-during-publish';
    if (rollbackErrors.length || claimantConflict) {
      cause.deliveryJournalRecovery = {
        recoveryRequired: true,
        journal: file,
        ...(claimantConflict ? { claimantConflict: true } : {}),
        rollbackErrors,
        ...(retainStaging ? {
          recoveryDirectory: stagingDirectory,
        } : publicRecoveryFiles.length ? {
          recoveryDirectory: path.dirname(publicRecoveryFiles[0].path),
        } : {}),
        ...(backupPresent || (candidatePresent && retainStaging) || publicRecoveryFiles.length ? {
          recoveryFiles: [
            ...(backupPresent ? [{
              label: backupVerified
                ? 'previous delivery journal'
                : 'unverified preserved journal backup entry',
              path: backup,
              target: file,
              verifiedPrevious: backupVerified,
            }] : []),
            ...(candidatePresent && retainStaging ? [{ label: 'preserved staged journal entry', path: temporary }] : []),
            ...publicRecoveryFiles,
          ],
        } : {}),
      };
    }
    throw cause;
  } finally {
    if (candidateCapture?.binding) releaseRegularFileBinding(candidateCapture.binding);
    if (previousCapture?.binding) releaseRegularFileBinding(previousCapture.binding);
    if (!retainStaging) removeOwnedEmptyStagingDirectory(stagingDirectory, staging.identity);
  }
}

function writeCapturedDeliveryProvenance(file, value, {
  beforeCommit,
  capture,
  verifyAtomicOutput,
  fileBindingRuntime,
} = {}) {
  const {
    backupPublicRegularFileBinding,
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    verifyRegularFileBinding,
    releaseRegularFileBinding,
  } = fileBindingRuntime || {};
  if (!capture
    || typeof verifyAtomicOutput !== 'function'
    || typeof backupPublicRegularFileBinding !== 'function'
    || typeof captureRegularFileBinding !== 'function'
    || typeof quarantineRemoveRegularFileBinding !== 'function'
    || typeof verifyRegularFileBinding !== 'function'
    || typeof releaseRegularFileBinding !== 'function') {
    throw deliveryTargetStateError(file, 'delivery provenance', {
      status: 'unknown',
      reason: { code: 'atomic-output-runtime-unavailable' },
    });
  }
  const staging = createOwnedEmptyStagingDirectory(
    path.join(path.dirname(file), '.archify-provenance-'),
  );
  const stagingDirectory = staging.directory;
  const candidate = path.join(stagingDirectory, path.basename(file));
  const backup = path.join(stagingDirectory, '.previous-provenance');
  let candidateIdentity;
  let candidateBinding;
  let previousBinding;
  let candidatePresent = false;
  let backupPresent = false;
  let backupVerified = false;
  let published = false;
  let retainStaging = false;
  try {
    const serialized = Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
    const expectedContent = artifactIdentity(serialized);
    fs.writeFileSync(candidate, serialized, { flag: 'wx' });
    candidatePresent = true;
    if (capture.mode !== null) fs.chmodSync(candidate, capture.mode);
    const candidateCapture = captureRegularFileBinding(candidate, {
      subject: 'delivery-provenance-candidate',
      expectedSha256: expectedContent.sha256,
      expectedBytes: expectedContent.bytes,
      ...(capture.mode === null ? {} : { expectedMode: capture.mode }),
      expectedLinks: 1,
    });
    if (candidateCapture.status !== 'captured') {
      throw deliveryTargetStateError(file, 'delivery provenance', candidateCapture);
    }
    candidateBinding = candidateCapture.binding;
    candidateIdentity = {
      dev: candidateCapture.identity.device,
      ino: candidateCapture.identity.inode,
    };
    beforeCommit?.();
    const verification = verifyAtomicOutput(capture.snapshot);
    if (verification.status !== 'match') {
      throw deliveryTargetStateError(file, 'delivery provenance', verification);
    }
    if (capture.snapshot.target.kind === 'file') {
      const expected = capture.snapshot.target;
      const previous = captureRegularFileBinding(capture.commitPath, {
        subject: 'previous-delivery-provenance',
        expectedIdentity: { device: expected.device, inode: expected.inode },
        expectedMode: expected.mode,
        expectedLinks: 1,
      });
      if (previous.status !== 'captured') {
        throw deliveryTargetStateError(file, 'delivery provenance', previous);
      }
      previousBinding = previous.binding;
      const moved = backupPublicRegularFileBinding(
        previousBinding,
        capture.commitPath,
        backup,
        { subject: 'previous-delivery-provenance' },
      );
      backupPresent = moved.backupCreated === true;
      backupVerified = moved.backupVerified === true;
      if (moved.status !== 'backed-up') {
        throw deliveryTargetStateError(file, 'delivery provenance', moved);
      }
    }
    const currentCandidate = verifyRegularFileBinding(candidateBinding, {
      filePath: candidate,
      expectedLinks: 1,
    });
    if (currentCandidate.status !== 'match') {
      throw deliveryTargetStateError(file, 'delivery provenance', currentCandidate);
    }
    try {
      fs.linkSync(candidate, capture.commitPath);
    } catch (error) {
      if (error?.code === 'EEXIST') {
        throw deliveryTargetStateError(file, 'delivery provenance', {
          status: 'different',
          reason: { code: 'target-claimed-during-publish' },
        });
      }
      throw error;
    }
    published = true;
    for (const target of [candidate, capture.commitPath]) {
      const linked = verifyRegularFileBinding(candidateBinding, {
        filePath: target,
        expectedLinks: 2,
      });
      if (linked.status !== 'match') {
        throw deliveryTargetStateError(file, 'delivery provenance', linked);
      }
    }
    const retiredCandidate = quarantineRemoveRegularFileBinding(
      candidateBinding,
      candidate,
      { subject: 'delivery-provenance-candidate', expectedLinks: 2 },
    );
    if (retiredCandidate.status !== 'removed') {
      retainStaging = true;
      throw deliveryTargetStateError(file, 'delivery provenance', retiredCandidate);
    }
    candidatePresent = false;
    const finalized = verifyRegularFileBinding(candidateBinding, {
      filePath: capture.commitPath,
      expectedLinks: 1,
    });
    if (finalized.status !== 'match') {
      throw deliveryTargetStateError(file, 'delivery provenance', finalized);
    }
    if (backupPresent) {
      const currentBackup = verifyRegularFileBinding(previousBinding, {
        filePath: backup,
        expectedLinks: 1,
      });
      if (currentBackup.status !== 'match') {
        backupVerified = false;
        throw deliveryTargetStateError(file, 'delivery provenance', {
          status: 'different',
          reason: { code: 'backup-identity-changed-before-finalize' },
        });
      }
      const retiredBackup = quarantineRemoveRegularFileBinding(
        previousBinding,
        backup,
        { subject: 'previous-delivery-provenance', expectedLinks: 1 },
      );
      if (retiredBackup.status !== 'removed') {
        retainStaging = true;
        throw deliveryTargetStateError(file, 'delivery provenance', retiredBackup);
      }
      backupPresent = false;
    }
  } catch (cause) {
    const rollbackErrors = [];
    const publicRecoveryFiles = [];
    if (cause.deliveryTargetState?.status === 'recovery-required'
      && cause.deliveryTargetState.recoveryFile) {
      publicRecoveryFiles.push({
        label: 'preserved provenance replacement',
        path: cause.deliveryTargetState.recoveryFile,
        target: capture.commitPath,
      });
    }
    if (published) {
      try {
        const removed = quarantineRemoveRegularFileBinding(candidateBinding, capture.commitPath, {
          subject: 'published-delivery-provenance',
          expectedLinks: candidatePresent ? 2 : 1,
        });
        if (removed.status === 'removed') {
          published = false;
        } else {
          rollbackErrors.push(`the published provenance could not be removed safely (${removed.reason?.code || 'unknown target state'})`);
          if (removed.status === 'recovery-required') {
            publicRecoveryFiles.push({
              label: 'preserved provenance replacement',
              path: removed.recoveryFile,
              target: capture.commitPath,
            });
          }
        }
      } catch (error) {
        if (error?.code !== 'ENOENT') rollbackErrors.push(`published provenance cleanup failed (${error.message})`);
      }
    }
    if (candidatePresent) {
      try {
        const current = verifyRegularFileBinding(candidateBinding, {
          filePath: candidate,
          expectedLinks: published ? 2 : 1,
        });
        if (current.status === 'match') {
          const retiredCandidate = quarantineRemoveRegularFileBinding(
            candidateBinding,
            candidate,
            {
              subject: 'delivery-provenance-candidate',
              expectedLinks: published ? 2 : 1,
            },
          );
          if (retiredCandidate.status !== 'removed') {
            throw deliveryTargetStateError(
              file,
              'delivery provenance',
              retiredCandidate,
            );
          }
          candidatePresent = false;
        } else {
          rollbackErrors.push('the staged provenance candidate was replaced before cleanup');
          retainStaging = true;
        }
      } catch (error) {
        if (error?.code !== 'ENOENT') {
          rollbackErrors.push(`staged provenance cleanup failed (${error.message})`);
          retainStaging = true;
        }
      }
    }
    if (backupPresent) {
      try {
        if (!backupVerified) {
          throw new Error('the backup entry was never verified as the previous provenance');
        }
        if (pathEntryExists(capture.commitPath)) {
          throw new Error('a new target claimant prevents restoring the previous provenance');
        }
        const currentBackup = verifyRegularFileBinding(previousBinding, {
          filePath: backup,
          expectedLinks: 1,
        });
        if (currentBackup.status !== 'match') {
          backupVerified = false;
          throw new Error('the previous provenance backup identity changed');
        }
        fs.linkSync(backup, capture.commitPath);
        for (const target of [backup, capture.commitPath]) {
          const restored = verifyRegularFileBinding(previousBinding, {
            filePath: target,
            expectedLinks: 2,
          });
          if (restored.status !== 'match') {
            throw new Error('the restored provenance identity could not be verified');
          }
        }
        const retiredBackup = quarantineRemoveRegularFileBinding(
          previousBinding,
          backup,
          { subject: 'previous-delivery-provenance', expectedLinks: 2 },
        );
        if (retiredBackup.status !== 'removed') {
          throw deliveryTargetStateError(file, 'delivery provenance', retiredBackup);
        }
        backupPresent = false;
        const restoredFinal = verifyRegularFileBinding(previousBinding, {
          filePath: capture.commitPath,
          expectedLinks: 1,
        });
        if (restoredFinal.status !== 'match') {
          throw new Error('the restored provenance link count could not be verified');
        }
      } catch (error) {
        rollbackErrors.push(`previous provenance restore failed (${error.message})`);
        retainStaging = true;
      }
    }
    const recoveryFiles = [
      ...(backupPresent ? [{
        label: backupVerified
          ? 'preserved delivery provenance backup entry'
          : 'unverified preserved delivery provenance backup entry',
        path: backup,
        target: capture.commitPath,
        verifiedPrevious: backupVerified,
      }] : []),
      ...(candidatePresent && retainStaging ? [{ label: 'preserved staged provenance entry', path: candidate }] : []),
      ...publicRecoveryFiles,
    ];
    if (rollbackErrors.length) {
      cause.deliveryProvenanceRecovery = {
        recoveryRequired: true,
        rollbackErrors,
        ...(recoveryFiles.length ? {
          recoveryDirectory: retainStaging
            ? stagingDirectory
            : path.dirname(recoveryFiles[0].path),
          recoveryFiles,
        } : {}),
      };
    }
    if (rollbackErrors.length && cause?.archifyDiagnostics?.[0]) {
      const [issue] = cause.archifyDiagnostics;
      issue.evidence = {
        ...(issue.evidence || {}),
        rollbackErrors,
        ...(recoveryFiles.length ? {
          recoveryDirectory: retainStaging
            ? stagingDirectory
            : path.dirname(recoveryFiles[0].path),
          recoveryFile: recoveryFiles[0].path,
          recoveryFiles,
        } : {}),
      };
    }
    throw cause;
  } finally {
    if (candidateBinding) releaseRegularFileBinding(candidateBinding);
    if (previousBinding) releaseRegularFileBinding(previousBinding);
    if (!retainStaging) removeOwnedEmptyStagingDirectory(stagingDirectory, staging.identity);
  }
}

function recordDeliveryFailure(options) {
  const {
    output, stage, input, error, receiptId, pathsAlias, ownership: suppliedOwnership,
    releaseOwnership: shouldReleaseSuppliedOwnership = false, legacyOutputPaths = [],
    captureAtomicOutput, verifyAtomicOutput, fileBindingRuntime,
  } = options;
  if (!output || !/\.html?$/i.test(output)) return { ok: true, status: 'not-applicable' };
  let ownership = suppliedOwnership;
  let acquiredHere = false;
  if (!ownership) {
    try {
      ownership = acquireDeliveryLock(
        output,
        receiptId,
        input,
        pathsAlias,
        (lockError, initializingOwnership) => recordDeliveryFailure({
          ...options,
          error: `Could not start delivery for "${output}": ${lockError.message}`,
          ownership: initializingOwnership,
          releaseOwnership: false,
        }),
        legacyOutputPaths,
        fileBindingRuntime,
      );
      acquiredHere = true;
    } catch (lockError) {
      const reportedLockError = lockError?.code === 'ARCHIFY_SIDECAR_NAMESPACE_INDETERMINATE'
        && lockError.sidecarNamespaceReason?.code === 'sidecar-directory-missing'
        ? Object.assign(
          new Error(`Delivery lock parent directory does not exist for "${output}".`),
          { code: 'ENOENT', cause: lockError },
        )
        : lockError;
      return {
        ...(lockError.deliveryFailureRecord || { ok: false, status: 'unrecorded' }),
        lockError: reportedLockError,
      };
    }
  }
  const state = deliveryOwnershipStates.get(ownership);
  let recorded;
  if (!state?.deliveryTargets) {
    try {
      captureDeliveryTargetState({
        state,
        requestedOutput: legacyOutputPaths[0] || output,
        pathsAlias,
        captureAtomicOutput,
        verifyAtomicOutput,
      });
    } catch (captureError) {
      recorded = {
        ok: false,
        status: 'unrecorded',
        diagnostic: captureError.archifyDiagnostics?.[0] || diagnostic({
          code: 'output/target-indeterminate',
          message: captureError.message,
          subject: { output },
          evidence: { ...(captureError?.code ? { systemCode: captureError.code } : {}) },
          supportedFixes: ['use ordinary absent or regular-file delivery targets, then retry'],
        }),
      };
    }
  }
  const stableOutput = state?.output || canonicalExistingDeliveryOutput(output);
  // Keep independent evidence even when the artifact is unreadable or the
  // provenance target is locked, aliases the input, or cannot be replaced.
  let journalError;
  if (!recorded && !state?.pendingIdentity) {
    try {
      beginDeliveryAttempt({ ownership, input, pathsAlias, fileBindingRuntime });
    } catch (cause) {
      if (cause.deliveryOwnershipCode === 'delivery/ownership-lost') {
        recorded = { ok: false, status: 'unrecorded', ownershipError: cause };
      } else if (cause.deliveryJournalRecovery?.recoveryRequired) {
        recorded = {
          ok: false,
          status: 'unrecorded',
          journalRecovery: cause,
          diagnostic: deliveryJournalRecoveryDiagnostic(stableOutput, cause),
        };
      }
      journalError = cause;
    }
  }
  if (!recorded) {
    let artifact;
    let artifactBinding;
    const {
      captureRegularFileBinding,
      verifyRegularFileBinding,
      releaseRegularFileBinding,
    } = fileBindingRuntime || {};
    try {
      if (typeof captureRegularFileBinding === 'function') {
        const artifactCapture = captureRegularFileBinding(stableOutput, {
          subject: 'failed-delivery-artifact',
          expectedLinks: 1,
          includeContent: true,
        });
        if (artifactCapture.status === 'captured') {
          artifact = artifactCapture.content.buffer;
          artifactBinding = artifactCapture.binding;
        } else if (['ENOENT', 'ENOTDIR'].includes(artifactCapture.reason?.systemCode)) {
          recorded = { ok: true, status: 'absent' };
        }
        // A failed marker does not need an artifact hash to invalidate old
        // evidence. Non-regular or changing paths are never followed.
      }
      if (!recorded) {
      const provenancePath = state?.provenancePath || deliveryProvenancePath(stableOutput);
      let aliasesProtectedPath;
      try {
        aliasesProtectedPath = (input && pathsAlias(provenancePath, input))
          || pathsAlias(provenancePath, stableOutput);
      } catch (aliasError) {
        recorded = {
          ok: false,
          status: 'unrecorded',
          diagnostic: diagnostic({
            code: 'delivery/provenance-path-resolution',
            message: 'Delivery failure provenance could not resolve its target safely.',
            subject: { output: stableOutput, provenance: provenancePath },
            evidence: {
              reason: aliasError.message,
              ...(aliasError?.code ? { systemCode: aliasError.code } : {}),
            },
            supportedFixes: ['remove the sidecar path conflict or symbolic-link cycle, then rerun deliver'],
          }),
        };
      }
      if (!recorded && aliasesProtectedPath) {
        recorded = {
          ok: false,
          status: 'unrecorded',
          diagnostic: diagnostic({
            code: 'delivery/provenance-target-alias',
            message: 'Delivery failure provenance could not be recorded without replacing an input or the artifact.',
            subject: { output: stableOutput, provenance: provenancePath },
            evidence: { ...(input ? { input: path.resolve(input) } : {}) },
            supportedFixes: ['choose an output whose .delivery.json sidecar is distinct from every input and the HTML artifact'],
          }),
        };
      }
      if (!recorded) {
        try {
          writeCapturedDeliveryProvenance(provenancePath, {
            schemaVersion: 1,
            receiptId,
            status: 'failed',
            command: 'deliver',
            stage,
            input,
            output: stableOutput,
            ...(artifact ? { artifact: artifactIdentity(artifact) } : {}),
            error,
          }, {
            beforeCommit: () => {
              assertDeliveryOwnership(ownership, 'record failed delivery provenance', {
                allowInitializing: true,
                pending: state?.pendingIdentity ? 'owned' : 'ignore',
              });
              if (artifactBinding) {
                const verification = verifyRegularFileBinding(artifactBinding, {
                  filePath: stableOutput,
                  expectedLinks: 1,
                });
                if (verification.status !== 'match') {
                  throw deliveryTargetStateError(
                    stableOutput,
                    'failed delivery artifact',
                    verification,
                  );
                }
              }
            },
            capture: state?.deliveryTargets?.provenance,
            verifyAtomicOutput,
            fileBindingRuntime,
          });
          recorded = { ok: true, status: 'failed' };
        } catch (writeError) {
          if (writeError.deliveryOwnershipCode === 'delivery/ownership-lost') {
            recorded = { ok: false, status: 'unrecorded', ownershipError: writeError };
          } else if (writeError.deliveryProvenanceRecovery?.recoveryRequired) {
            const recovery = writeError.deliveryProvenanceRecovery;
            recorded = {
              ok: false,
              status: 'unrecorded',
              provenanceRecovery: writeError,
              diagnostic: diagnostic({
                code: 'delivery/provenance-recovery-required',
                message: 'Failed-delivery provenance could not be rolled back safely.',
                subject: { output: stableOutput, provenance: provenancePath },
                evidence: {
                  reason: writeError.message,
                  recoveryRequired: true,
                  ...(recovery.recoveryDirectory ? { recoveryDirectory: recovery.recoveryDirectory } : {}),
                  ...(recovery.recoveryFiles?.length ? { recoveryFiles: recovery.recoveryFiles } : {}),
                  ...(recovery.rollbackErrors?.length ? { rollbackErrors: recovery.rollbackErrors } : {}),
                },
                supportedFixes: ['leave the delivery lock and journal untouched, inspect the retained recovery files, then recover serially'],
              }),
            };
          } else if (writeError.deliveryTargetState) {
            recorded = {
              ok: false,
              status: 'unrecorded',
              diagnostic: writeError.archifyDiagnostics?.[0],
            };
          } else {
            recorded = {
              ok: false,
              status: 'unrecorded',
              diagnostic: diagnostic({
                code: 'delivery/provenance-write',
                message: 'The failed delivery could not persist its stale-artifact marker.',
                subject: { output: stableOutput, provenance: provenancePath },
                evidence: {
                  reason: writeError.message,
                  ...(writeError?.code ? { systemCode: writeError.code } : {}),
                  failureJournalRecorded: !journalError,
                  ...(journalError ? { journalError: journalError.message } : {}),
                },
                supportedFixes: ['restore write access to the output directory, then rerun deliver before trusting the artifact'],
              }),
            };
          }
        }
      }
      }
    } finally {
      if (artifactBinding && typeof releaseRegularFileBinding === 'function') {
        releaseRegularFileBinding(artifactBinding);
      }
    }
  }
  if (recorded?.journalRecovery || recorded?.provenanceRecovery) return recorded;
  if (acquiredHere || shouldReleaseSuppliedOwnership) {
    try {
      releaseDeliveryOwnership(ownership, { allowInitializing: true });
    } catch (lockError) {
      if (lockError.deliveryOwnershipCode === 'delivery/ownership-lost') {
        const ownershipError = recorded.ownershipError || lockError;
        if (options.recoveryDirectory) {
          ownershipError.deliveryCommitDetails = {
            ...(ownershipError.deliveryCommitDetails || {}),
            recoveryRequired: true,
            recoveryDirectory: options.recoveryDirectory,
            recoverableBackups: [],
          };
        }
        return {
          ...recorded,
          ok: false,
          status: 'unrecorded',
          ownershipError,
          lockError,
        };
      }
      return { ...recorded, lockError: recorded.ownershipError || lockError };
    }
  }
  return recorded;
}

// Locale warnings for a successfully rendered candidate. Diagnostic renderers
// record them without printing text; validate/deliver disclose them before
// checking the artifact and reuse the same diagnostics in successful receipts.
async function specificationLocaleDiagnostics(type, specification) {
  let meta;
  try {
    meta = JSON.parse(String(specification)).meta;
  } catch {
    return [];
  }
  if (!meta?.locale) return [];
  const { localeDiagnostics } = await import('../renderers/shared/i18n.mjs');
  return localeDiagnostics(type, meta);
}

function deliverySuccessProvenance(receipt) {
  return {
    schemaVersion: 1,
    receiptId: receipt.receiptId,
    status: 'current',
    command: 'deliver',
    type: receipt.type,
    input: receipt.input,
    output: receipt.output,
    specification: receipt.specification,
    artifact: receipt.artifact,
    ...(receipt.explainer ? { explainer: receipt.explainer } : {}),
  };
}

function inspectDeliveryProvenance(artifactPath, artifact, {
  requireProvenance = false,
  pathIdentityRuntime,
  expectedSidecar,
  inspection,
} = {}) {
  let sidecar = deliveryProvenancePath(artifactPath);
  const rawHeadSidecar = rawHeadDeliveryProvenancePath(artifactPath);
  const pending = deliveryPendingPath(artifactPath);
  const rawHeadPending = rawHeadDeliveryPendingPath(artifactPath);
  const legacyExtensionPending = legacyExtensionDeliverySidecarPath(
    artifactPath,
    '.delivery-pending.json',
  );
  const legacyExtensionSidecar = legacyExtensionDeliverySidecarPath(
    artifactPath,
    '.delivery.json',
  );
  const stableOutput = canonicalExistingDeliveryOutput(artifactPath);
  const locks = [
    deliveryLockPath(stableOutput),
    ...legacyDeliveryLockPaths([artifactPath, stableOutput]),
  ];
  let foundPending;
  try {
    for (const candidate of [...new Set([
      pending,
      rawHeadPending,
      legacyExtensionPending,
    ].filter(Boolean))]) {
      if (pathEntryExists(candidate)) {
        foundPending = candidate;
        break;
      }
    }
    if (foundPending) {
      return {
        ok: false, status: 'failed',
        diagnostics: [diagnostic({
          code: 'delivery/provenance-failed',
          message: 'A delivery attempt is unfinished or failed; complete a successful deliver before trusting this artifact.',
          subject: { artifact: path.resolve(artifactPath), provenance: sidecar },
          evidence: { pendingJournal: foundPending, found: true },
          supportedFixes: ['finish any active delivery, then rerun deliver successfully; retain the pending journal until recovery succeeds'],
        })],
      };
    }
  } catch (error) {
    return invalidProvenance(artifactPath, foundPending || pending, error.message);
  }
  for (const lock of locks) {
    try {
      if (pathEntryExists(lock)) {
        return {
          ok: false, status: 'locked',
          diagnostics: [diagnostic({
            code: 'delivery/provenance-locked',
            message: 'Delivery ownership is unresolved while the output lock remains; complete or recover delivery before trusting this artifact.',
            subject: { artifact: path.resolve(artifactPath), lock },
            evidence: { deliveryLock: lock, found: true },
            supportedFixes: ['finish the active delivery or inspect and recover the preserved lock, then rerun deliver successfully'],
          })],
        };
      }
    } catch (error) {
      return invalidProvenance(artifactPath, lock, error.message);
    }
  }
  let found;
  try {
    found = pathEntryExists(sidecar);
  } catch (error) {
    return invalidProvenance(artifactPath, sidecar, error.message);
  }
  if (!found && rawHeadSidecar) {
    try {
      found = pathEntryExists(rawHeadSidecar);
      if (found) sidecar = rawHeadSidecar;
    } catch (error) {
      return invalidProvenance(artifactPath, rawHeadSidecar, error.message);
    }
  }
  if (!found && legacyExtensionSidecar) {
    try {
      found = pathEntryExists(legacyExtensionSidecar);
      if (found) sidecar = legacyExtensionSidecar;
    } catch (error) {
      return invalidProvenance(artifactPath, legacyExtensionSidecar, error.message);
    }
  }
  if (!found) {
    if (!requireProvenance) return { ok: true, status: 'unknown' };
    const message = 'Delivery provenance is required, but the artifact has no .delivery.json sidecar.';
    return {
      ok: false,
      status: 'unknown',
      diagnostics: [diagnostic({
        code: 'delivery/provenance-required',
        message,
        subject: { artifact: path.resolve(artifactPath), provenance: sidecar },
        evidence: { required: true, found: false },
        supportedFixes: ['rerun deliver for the current specification, then retry with --require-provenance'],
      })],
    };
  }
  let receipt;
  let sidecarCapture;
  try {
    const {
      captureRegularFileBinding,
      releaseRegularFileBinding,
    } = pathIdentityRuntime || {};
    if (typeof captureRegularFileBinding !== 'function'
      || typeof releaseRegularFileBinding !== 'function') {
      throw new Error('The regular-file binding runtime is unavailable.');
    }
    sidecarCapture = captureRegularFileBinding(sidecar, {
      subject: 'delivery-provenance',
      ...(expectedSidecar ? {
        expectedIdentity: expectedSidecar.identity,
        expectedSha256: expectedSidecar.content.sha256,
        expectedBytes: expectedSidecar.content.bytes,
        expectedMode: expectedSidecar.mode,
      } : {}),
      expectedLinks: 1,
      includeContent: true,
    });
    if (sidecarCapture.status !== 'captured') {
      if (sidecarCapture.reason?.code === 'delivery-provenance-hardlinked') {
      return {
        ok: false,
        status: 'unsupported',
        diagnostics: [diagnostic({
          code: 'delivery/provenance-hardlink-unsupported',
          message: 'Delivery provenance is hard-linked and cannot prove that every linked name was updated atomically.',
          subject: { artifact: path.resolve(artifactPath), provenance: sidecar },
          evidence: { links: sidecarCapture.reason.links },
          supportedFixes: ['remove extra hard links to the provenance sidecar, then rerun deliver'],
        })],
      };
      }
      throw new Error(`Delivery provenance is not a stable regular file (${sidecarCapture.reason?.code || 'unknown target state'}).`);
    }
    receipt = JSON.parse(sidecarCapture.content.buffer.toString('utf8'));
    const identityValid = (value) => value && typeof value.sha256 === 'string' && /^[0-9a-f]{64}$/.test(value.sha256)
      && Number.isSafeInteger(value.bytes) && value.bytes >= 0;
    if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)
      || receipt.schemaVersion !== 1 || receipt.command !== 'deliver'
      || typeof receipt.receiptId !== 'string'
      || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(receipt.receiptId)
      || typeof receipt.output !== 'string' || !path.isAbsolute(receipt.output)
      || typeof receipt.input !== 'string' || !path.isAbsolute(receipt.input)
      || !['current', 'failed'].includes(receipt.status)
      || (receipt.status === 'current' && (!TYPES.has(receipt.type)
        || !identityValid(receipt.specification) || !identityValid(receipt.artifact)))
      || (receipt.status === 'failed' && typeof receipt.stage !== 'string')) {
      throw new Error('Delivery provenance does not conform to the supported receipt schema.');
    }
    if (inspection) {
      inspection.sidecar = {
        path: sidecar,
        identity: {
          device: sidecarCapture.identity.device,
          inode: sidecarCapture.identity.inode,
        },
        content: {
          sha256: sidecarCapture.content.sha256,
          bytes: sidecarCapture.content.bytes,
        },
        mode: sidecarCapture.mode,
      };
    }
  } catch (error) {
    const message = `Could not read delivery provenance: ${error.message}`;
    return {
      ok: false,
      status: 'invalid',
      diagnostics: [diagnostic({
        code: 'delivery/provenance-invalid',
        message,
        subject: { artifact: path.resolve(artifactPath), provenance: sidecar },
        evidence: { reason: error.message },
        supportedFixes: ['rerun deliver to replace the invalid provenance sidecar'],
      })],
    };
  } finally {
    if (sidecarCapture?.binding) {
      pathIdentityRuntime.releaseRegularFileBinding(sidecarCapture.binding);
    }
  }
  let outputIdentity;
  if (typeof pathIdentityRuntime?.sameEntry !== 'function') {
    const error = pathIdentityRuntime?.error;
    outputIdentity = {
      status: 'unknown',
      reason: {
        code: 'path-semantics-runtime-unavailable',
        ...(typeof error?.code === 'string' ? { systemCode: error.code } : {}),
      },
    };
  } else {
    try {
      outputIdentity = pathIdentityRuntime.sameEntry(receipt.output, artifactPath);
    } catch (error) {
      outputIdentity = {
        status: 'unknown',
        reason: {
          code: 'path-identity-check-failed',
          ...(typeof error?.code === 'string' ? { systemCode: error.code } : {}),
        },
      };
    }
  }
  if (outputIdentity.status === 'unknown') {
    return {
      ok: false,
      status: 'invalid',
      diagnostics: [diagnostic({
        code: 'delivery/provenance-output-indeterminate',
        message: 'Delivery provenance could not determine whether its recorded output identifies the inspected artifact.',
        subject: {
          artifact: path.resolve(artifactPath),
          provenance: sidecar,
          recordedOutput: receipt.output,
        },
        evidence: { pathIdentity: outputIdentity.reason },
        supportedFixes: ['restore access to both the artifact and its recorded output path, then rerun deliver successfully'],
      })],
    };
  }
  if (outputIdentity.status !== 'match') {
    return invalidProvenance(
      artifactPath,
      sidecar,
      'The recorded delivery output does not identify this artifact.',
      { recordedOutput: receipt.output, pathIdentity: outputIdentity.reason },
    );
  }
  const actualSha256 = createHash('sha256').update(artifact).digest('hex');
  if (receipt.status === 'failed') {
    const message = 'The artifact is stale because the latest delivery attempt failed.';
    return {
      ok: false,
      status: 'failed',
      receiptId: receipt.receiptId,
      diagnostics: [diagnostic({
        code: 'delivery/provenance-failed',
        message,
        subject: { artifact: path.resolve(artifactPath), provenance: sidecar },
        evidence: { stage: receipt.stage, deliveryReceiptId: receipt.receiptId },
        supportedFixes: ['repair the specification and complete a successful deliver before checking this artifact'],
      })],
    };
  }
  if (receipt.artifact?.sha256 !== actualSha256 || receipt.artifact?.bytes !== artifact.byteLength) {
    const message = 'The artifact bytes do not match their delivery provenance.';
    return {
      ok: false,
      status: 'mismatch',
      receiptId: receipt.receiptId,
      diagnostics: [diagnostic({
        code: 'delivery/provenance-mismatch',
        message,
        subject: { artifact: path.resolve(artifactPath), provenance: sidecar },
        evidence: {
          expectedSha256: receipt.artifact?.sha256,
          actualSha256,
          expectedBytes: receipt.artifact?.bytes,
          actualBytes: artifact.byteLength,
        },
        supportedFixes: ['restore the delivered artifact or rerun deliver to create a matching artifact and provenance pair'],
      })],
    };
  }
  return { ok: true, status: 'current', receiptId: receipt.receiptId, artifact: receipt.artifact, type: receipt.type };
}

function invalidProvenance(artifactPath, sidecar, reason, evidence = {}) {
  return {
    ok: false, status: 'invalid',
    diagnostics: [diagnostic({
      code: 'delivery/provenance-invalid', message: 'Delivery provenance could not be verified.',
      subject: { artifact: artifactPath, provenance: sidecar }, evidence: { reason, ...evidence },
      supportedFixes: ['restore access to the delivery records, then rerun deliver successfully'],
    })],
  };
}

const COMMAND_USAGE = {
  render: '<type> <input.json> [output.html] [--quality standard|showcase] [--repo-root path]',
  compare: 'architecture <base.json> <head.json> [output.html] [--receipt path] [--json] [--quality standard|showcase] [--repo-root path]',
  deliver: '<type> <input.json> [output.html] [--json] [--open] [--quality standard|showcase] [--repo-root path]',
  patch: 'explainer <artifact.html> <panel-id> <replacement-file> <output.html> [--json] [--quality standard|showcase] [--repo-root path]',
  finalize: '<type> <input.json> <output.html> [--json] [--browser-check] [--receipt path] [--out-dir <dir>] [--quality standard|showcase] [--repo-root path] [--candidate-sha256 hex]',
  preview: '<diagram-type (excludes explainer)> <input.json> [output.html] [--no-open] [--quality standard|showcase] [--repo-root path]',
  validate: '<type> <input.json> [--json] [--layout-json] [--quality standard|showcase] [--repo-root path]',
  migrate: 'workflow <old.json> <new.json> --to-schema 2 [--output portable.html] [--json] [--repo-root path]',
  inspect: '<type> <input.json>',
  check: '<output.html> [--json] [--require-provenance]',
  'browser-check': '<output.html> [--json|--summary] [--require-provenance] [--out-dir <dir>]',
  'visual-check': '<output.html> [--json|--summary] [--require-provenance] [--out-dir <dir>]',
  guide: '[scenario or question] [--json] [--lang en|zh]',
  brands: ['[name, alias, domain, or category] [--json]', 'capture <url> [--json]'],
  examples: '',
  doctor: '',
  demo: '[output-directory]',
};

function usage() {
  const commands = Object.entries(COMMAND_USAGE).flatMap(([command, forms]) =>
    (Array.isArray(forms) ? forms : [forms]).map(form => `  archify ${command}${form ? ` ${form}` : ''}`));
  return `Usage:
${commands.join('\n')}
  (finalize --out-dir relocates browser-check and default finalize receipts; HTML and its delivery receipt stay at the requested output path)

Types:
  architecture, workflow, sequence, dataflow, lifecycle, erd, tree, class, timeline, waterfall, explainer

Explainer writing checks (validate, deliver, finalize, patch):
  --writing warn|strict|off (default: warn)
`;
}

function fail(message, code = 2) {
  console.error(message);
  process.exit(code);
}

function rejectCliArgument(message, details = {}) {
  const error = new Error(message);
  error.archifyArgument = {
    code: details.code || 'cli/invalid-arguments',
    subject: details.subject || {},
    evidence: details.evidence || {},
    supportedFixes: details.supportedFixes || ['correct the command arguments and retry'],
  };
  throw error;
}

function rendererPath(type) {
  if (!TYPES.has(type)) {
    rejectCliArgument(`Unknown diagram type "${type}". Expected one of: ${[...TYPES].join(', ')}`, {
      code: 'cli/unknown-diagram-type',
      subject: { type },
      evidence: { supportedTypes: [...TYPES] },
      supportedFixes: [`use one of: ${[...TYPES].join(', ')}`],
    });
  }
  return path.join(skillRoot, 'renderers', type, `render-${type}.mjs`);
}

// Default capture ceiling for piped child output. spawnSync's own default
// is 1 MiB, which is below what a dense diagram's checker receipt reaches.
const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;

function runNode(args, options = {}) {
  const result = spawnSync(process.execPath, args, {
    cwd: options.cwd || process.cwd(),
    encoding: 'utf8',
    stdio: options.stdio || 'inherit',
    maxBuffer: options.maxBuffer ?? DEFAULT_MAX_BUFFER,
    env: options.env ? { ...process.env, ...options.env } : process.env,
  });
  // spawnSync can report a system failure after a child has exited zero. A
  // truncated renderer or checker result is never a successful invocation.
  if (result.error && result.status === 0) {
    result.archifyRawStatus = result.status;
    result.status = 1;
  }
  return result;
}

// The artifact checker prints its whole receipt on stdout; a dense,
// warning-heavy diagram can grow that receipt past spawnSync's 1 MiB
// default, which kills the child before it reports a verdict. Deliver,
// validate, migrate, compare, and check share this explicit limit so one
// environment knob moves them together.
function artifactCheckMaxBuffer() {
  const raw = process.env.ARCHIFY_CHECK_MAX_BUFFER;
  if (raw === undefined || raw === '') return DEFAULT_MAX_BUFFER;
  const parsed = Number(raw);
  return Number.isFinite(parsed) && Math.floor(parsed) >= 1 ? Math.floor(parsed) : DEFAULT_MAX_BUFFER;
}

// A checker terminated while streaming its output never judged the
// artifact; its truncated stdout must not be reinterpreted as a verdict.
function checkerOutputLimitDiagnostics(check, limitBytes) {
  if (check.error?.code !== 'ENOBUFS') return null;
  const receivedBytes = Buffer.byteLength(check.stdout || '', 'utf8');
  return [diagnostic({
    code: 'artifact/check-output-limit',
    message: `The artifact checker exceeded the ${limitBytes} byte output buffer and was terminated before reporting a verdict (${receivedBytes} stdout bytes received); the artifact was not judged.`,
    subject: { check: 'render_output' },
    evidence: {
      systemCode: check.error.code,
      ...(check.signal ? { signal: check.signal } : {}),
      status: check.archifyRawStatus ?? check.status ?? null,
      limitBytes,
      receivedBytes,
    },
    supportedFixes: [
      'set ARCHIFY_CHECK_MAX_BUFFER to a much larger limit (for example 1073741824) and re-run',
    ],
  })];
}

function extractQualityArgs(args) {
  const rest = [];
  let quality;
  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (arg === '--quality') {
      quality = args[index + 1];
      if (!quality || quality.startsWith('--')) rejectCliArgument('--quality requires standard or showcase.', {
        code: 'cli/missing-option-value',
        subject: { option: '--quality' },
        supportedFixes: ['provide --quality standard or --quality showcase'],
      });
      index += 1;
      continue;
    }
    if (arg.startsWith('--quality=')) {
      quality = arg.slice('--quality='.length);
      if (!quality) rejectCliArgument('--quality requires standard or showcase.', {
        code: 'cli/missing-option-value',
        subject: { option: '--quality' },
        supportedFixes: ['provide --quality standard or --quality showcase'],
      });
      continue;
    }
    rest.push(arg);
  }
  if (quality !== undefined && !['standard', 'showcase'].includes(quality)) {
    rejectCliArgument(`Unknown quality profile "${quality}". Expected standard or showcase.`, {
      code: 'cli/invalid-option-value',
      subject: { option: '--quality' },
      evidence: { value: quality, supportedValues: ['standard', 'showcase'] },
      supportedFixes: ['use --quality standard or --quality showcase'],
    });
  }
  return { rest, quality };
}

function extractRepoRootArgs(args) {
  const rest = [];
  let repoRoot;
  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (arg === '--repo-root') {
      repoRoot = args[index + 1];
      if (!repoRoot || repoRoot.startsWith('--')) rejectCliArgument('--repo-root requires a repository path.', {
        code: 'cli/missing-option-value',
        subject: { option: '--repo-root' },
        supportedFixes: ['provide one repository path after --repo-root'],
      });
      index += 1;
      continue;
    }
    if (arg.startsWith('--repo-root=')) {
      repoRoot = arg.slice('--repo-root='.length);
      if (!repoRoot) rejectCliArgument('--repo-root requires a repository path.', {
        code: 'cli/missing-option-value',
        subject: { option: '--repo-root' },
        supportedFixes: ['provide one repository path after --repo-root'],
      });
      continue;
    }
    rest.push(arg);
  }
  return { rest, repoRoot: repoRoot ? path.resolve(repoRoot) : undefined };
}

function extractOutDirArgs(args) {
  const rest = [];
  let outDir;
  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (arg === '--out-dir') {
      outDir = args[index + 1];
      if (!outDir || outDir.startsWith('--')) fail('--out-dir requires a directory path.');
      index += 1;
      continue;
    }
    if (arg.startsWith('--out-dir=')) {
      outDir = arg.slice('--out-dir='.length);
      if (!outDir) fail('--out-dir requires a directory path.');
      continue;
    }
    rest.push(arg);
  }
  return { rest, outDir };
}

function extractExplainerWritingArgs(args) {
  const rest=[];
  let writingMode;
  for(let index=0;index<args.length;index++) {
    const argument=args[index];
    if(argument==='--writing' || argument.startsWith('--writing=')) {
      const value=argument==='--writing' ? args[++index] : argument.slice('--writing='.length);
      if(writingMode!==undefined || !['warn','strict','off'].includes(value)) rejectCliArgument('--writing requires one of warn, strict or off.', {
        code:'cli/invalid-arguments',subject:{option:'--writing'},supportedFixes:['Use --writing warn, --writing strict or --writing off once.'],
      });
      writingMode=value;
    } else rest.push(argument);
  }
  if(writingMode!==undefined && rest.find(argument=>!argument.startsWith('--'))!=='explainer') rejectCliArgument('--writing is supported for explainer documents only.', {
    code:'cli/unsupported-option',subject:{option:'--writing'},supportedFixes:['Remove --writing or use an explainer document.'],
  });
  return {rest,writingMode};
}

async function prepareExplainerInput(specification, inputPath, options = {}) {
  const runtime = await import('../explainer/prepare.mjs');
  const text = specification.toString('utf8');
  if (!Buffer.from(text).equals(specification)) {
    const message='Explainer draft must contain valid UTF-8 bytes.';
    throw Object.assign(new Error(message),{archifyDiagnostics:[diagnostic({code:'explainer/source-encoding',message,subject:{input:inputPath,line:1,component:'document'},evidence:{reason:'invalid-utf8',example:'Save the original draft as UTF-8 text.'},supportedFixes:['Save the original draft as UTF-8 text.']})]});
  }
  return process.env.ARCHIFY_EXPLAINER_PREPARED
    ? runtime.readPreparedBundle(process.env.ARCHIFY_EXPLAINER_PREPARED, text, inputPath, { quality: options.quality, writingMode: options.writingMode || 'warn' })
    : runtime.prepareExplainer(text, { ...options, inputPath });
}

function rendererEnv(quality, repoRoot, diagnosticJson = false) {
  return {
    ...(quality ? { ARCHIFY_QUALITY_PROFILE: quality } : {}),
    ...(repoRoot ? { ARCHIFY_REPO_ROOT: repoRoot } : {}),
    ...(diagnosticJson ? { ARCHIFY_DIAGNOSTIC_FORMAT: 'json' } : {}),
  };
}

function diagnostic({ code, message, subject = {}, evidence = {}, supportedFixes = [], severity = 'error' }) {
  return {
    code,
    severity,
    message,
    subject,
    evidence,
    supportedFixes,
  };
}

function deliveryLockFailureDiagnostic(output, error) {
  const code = error.deliveryOwnershipCode || error.deliveryLockCode || 'delivery/lock-acquire';
  if (code === 'delivery/legacy-pending') {
    return diagnostic({
      code,
      message: `A pre-namespace delivery journal blocks delivery for "${output}".`,
      subject: { output, journal: error.deliveryLockPath },
      evidence: { pendingJournal: error.deliveryLockPath, found: true },
      supportedFixes: ['recover the unfinished delivery and remove only its journal after recovery succeeds'],
    });
  }
  const lock = error.deliveryOwnershipDetails?.lock
    || error.deliveryLockPath
    || deliveryLockPath(output);
  return diagnostic({
    code,
    message: code === 'delivery/lock-release'
      ? `Delivery lock could not be released for "${output}": ${error.message}`
      : code === 'delivery/ownership-lost'
        ? `Delivery ownership was lost for "${output}": ${error.message}`
        : `Could not start delivery for "${output}": ${error.message}`,
    subject: { output, lock },
    evidence: {
      reason: error.message,
      ...(error.code ? { systemCode: error.code } : {}),
      ...(error.lockCleanupError ? { cleanupError: error.lockCleanupError } : {}),
      ...(error.deliveryLockOwner || {}),
      ...(error.deliveryOwnershipDetails || {}),
      ...(error.deliveryCommitDetails || {}),
    },
    supportedFixes: code === 'delivery/concurrent-attempt'
        ? ['wait for the active delivery to finish, then retry']
      : code === 'delivery/lock-stale'
        ? [
          'confirm no delivery attempt is active for this output',
          `remove only the preserved lock "${lock}", then rerun deliver successfully`,
        ]
      : code === 'delivery/lock-path-conflict'
        ? ['choose an output whose lock path is distinct from the input specification']
        : code === 'delivery/lock-invalid'
          ? ['inspect and preserve the unrecognized lock entry, or choose another output path']
          : code === 'delivery/ownership-lost'
            ? ['leave the replacement lock and journal untouched, inspect the reported owner, then retry only after that attempt finishes or is recovered']
            : code === 'delivery/lock-release'
              ? ['preserve the reported lock, restore permission to remove that exact entry, then recover serially before retrying']
          : ['resolve the reported filesystem error and any lock cleanup error, then retry'],
  });
}

function deliveryJournalRecoveryDiagnostic(output, error) {
  const recovery = error.deliveryJournalRecovery || {};
  const location = recovery.recoveryDirectory
    ? ` Recovery material was retained at "${recovery.recoveryDirectory}".`
    : '';
  return diagnostic({
    code: 'delivery/journal-recovery-required',
    message: `Delivery journal publication could not be rolled back safely.${location}`,
    subject: { output, journal: recovery.journal || deliveryPendingPath(output) },
    evidence: {
      reason: error.message,
      recoveryRequired: true,
      ...(recovery.recoveryDirectory ? { recoveryDirectory: recovery.recoveryDirectory } : {}),
      ...(recovery.recoveryFiles?.length ? { recoveryFiles: recovery.recoveryFiles } : {}),
      ...(recovery.rollbackErrors?.length ? { rollbackErrors: recovery.rollbackErrors } : {}),
    },
    supportedFixes: recovery.recoveryDirectory
      ? [
        'leave the delivery lock and current journal claimant untouched',
        `inspect every recovery file in ${JSON.stringify(recovery.recoveryDirectory)} and restore the previous journal only after the claimant is resolved`,
      ]
      : ['leave the delivery lock and journal untouched, inspect their current owners, then recover serially'],
  });
}

function deliveryCommitRecoveryDiagnostic(output, error) {
  const recovery = error.deliveryCommitDetails || {};
  return diagnostic({
    code: 'delivery/commit-recovery-required',
    message: `Delivery rollback could not safely restore the previous output pair for "${output}".`,
    subject: { output },
    evidence: {
      reason: recovery.reason || error.message,
      recoveryRequired: true,
      ...(recovery.recoveryDirectory ? { recoveryDirectory: recovery.recoveryDirectory } : {}),
      ...(recovery.recoverableBackups?.length
        ? { recoverableBackups: recovery.recoverableBackups }
        : {}),
      ...(recovery.rollbackErrors?.length ? { rollbackErrors: recovery.rollbackErrors } : {}),
    },
    supportedFixes: [
      'leave the delivery lock, journal, current claimants, and retained backups untouched',
      'inspect the reported files and restore the previous pair only after resolving every claimant',
    ],
  });
}

function deliveryTargetStateDiagnostic(output, role, result) {
  const reason = result?.reason || { code: 'target-state-unavailable' };
  const hardlinked = typeof reason.code === 'string' && reason.code.endsWith('-hardlinked');
  const provenanceTarget = /provenance/iu.test(role);
  const code = hardlinked
    ? provenanceTarget ? 'delivery/provenance-hardlink-unsupported' : 'output/target-hardlinked'
    : ['target-not-regular-file', 'requested-entry-symbolic-link', 'requested-entry-not-regular-file'].includes(reason.code)
      ? 'output/target-not-regular-file'
      : result?.status === 'different'
        ? 'output/target-changed'
        : 'output/target-indeterminate';
  const message = hardlinked
    ? `The ${role} target is hard-linked and cannot be replaced atomically.`
    : code === 'output/target-not-regular-file'
      ? `The ${role} target is not a regular file.`
      : code === 'output/target-changed'
        ? `The ${role} target changed while the verified delivery pair was being prepared.`
        : `The ${role} target identity could not be determined safely.`;
  return diagnostic({
    code,
    message,
    subject: { output: path.resolve(output), role },
    evidence: { targetState: reason },
    supportedFixes: hardlinked
      ? ['remove extra hard links or choose a new output path, then rerun deliver']
      : code === 'output/target-not-regular-file'
        ? ['choose an absent or regular-file target, then rerun deliver']
        : code === 'output/target-changed'
          ? ['retry only after other processes stop creating, replacing, retargeting, or changing the output pair']
          : ['use an ordinary local filesystem path with stable file identity, then retry'],
  });
}

function deliveryTargetStateError(output, role, result) {
  const issue = deliveryTargetStateDiagnostic(output, role, result);
  const error = new Error(issue.message);
  error.archifyDiagnostics = [issue];
  error.deliveryTargetState = result;
  return error;
}

function captureDeliveryTargetState({
  state,
  requestedOutput,
  pathsAlias,
  captureAtomicOutput,
  verifyAtomicOutput,
  preparedTargets,
}) {
  if (typeof captureAtomicOutput !== 'function' || typeof verifyAtomicOutput !== 'function') {
    throw deliveryTargetStateError(requestedOutput, 'delivery pair', {
      status: 'unknown',
      reason: { code: 'atomic-output-runtime-unavailable' },
    });
  }
  const artifactTarget = preparedTargets?.artifact || {
    requestedPath: requestedOutput,
    ...captureAtomicOutput(requestedOutput),
  };
  if (artifactTarget.status !== 'captured') {
    throw deliveryTargetStateError(requestedOutput, 'HTML artifact', artifactTarget);
  }
  if (!pathsAlias(artifactTarget.commitPath, state.output)) {
    throw deliveryTargetStateError(requestedOutput, 'HTML artifact', {
      status: 'different',
      reason: {
        code: 'write-slot-changed-before-snapshot',
        plannedCommitPath: state.output,
        currentCommitPath: artifactTarget.commitPath,
      },
    });
  }
  const requestedProvenancePath = preparedTargets?.provenance?.requestedPath
    || deliveryProvenancePath(artifactTarget.commitPath);
  const provenanceTarget = preparedTargets?.provenance || {
    requestedPath: requestedProvenancePath,
    ...captureAtomicOutput(requestedProvenancePath, {
      requestedEntryPolicy: 'regular-or-absent',
    }),
  };
  if (provenanceTarget.status !== 'captured') {
    throw deliveryTargetStateError(requestedProvenancePath, 'delivery provenance', provenanceTarget);
  }
  for (const [role, target] of [
    ['HTML artifact', artifactTarget],
    ['delivery provenance', provenanceTarget],
  ]) {
    const verification = verifyAtomicOutput(target.snapshot);
    if (verification.status !== 'match') {
      throw deliveryTargetStateError(target.requestedPath, role, verification);
    }
  }
  state.output = artifactTarget.commitPath;
  state.provenancePath = provenanceTarget.commitPath;
  state.pendingPath = deliveryPendingPath(artifactTarget.commitPath);
  state.verifyAtomicOutput = verifyAtomicOutput;
  state.deliveryTargets = {
    artifact: artifactTarget,
    provenance: provenanceTarget,
  };
  return state.deliveryTargets;
}

function inputDiagnostic(error, inputPath) {
  const isSyntax = error instanceof SyntaxError;
  return diagnostic({
    code: isSyntax ? 'input/json-parse' : 'input/read',
    message: isSyntax
      ? `Input JSON could not be parsed: ${error.message}`
      : `Input could not be read: ${error.message}`,
    subject: { input: inputPath },
    evidence: {
      ...(error?.code ? { systemCode: error.code } : {}),
      reason: error.message,
    },
    supportedFixes: [isSyntax
      ? 'repair the JSON syntax and run validation again'
      : 'provide one readable JSON input file'],
  });
}

function rendererFailure(result) {
  if (result.error) {
    return {
      error: 'Renderer process could not start.',
      diagnostics: [diagnostic({
        code: 'internal/renderer-process',
        message: 'Renderer process could not start.',
        evidence: { reason: result.error.message },
      })],
    };
  }
  try {
    const payload = JSON.parse((result.stderr || '').trim());
    if (payload?.ok === false && Array.isArray(payload.diagnostics) && payload.diagnostics.length) {
      return {
        error: payload.error || payload.diagnostics[0].message,
        diagnostics: payload.diagnostics,
      };
    }
  } catch {
    // The diagnostic boundary is intentionally fail-closed. Never copy a raw
    // Node stack into a machine receipt when a renderer exits unexpectedly.
  }
  return {
    error: 'Renderer failed before emitting a structured diagnostic.',
    diagnostics: [diagnostic({
      code: 'internal/unclassified',
      message: 'Renderer failed before emitting a structured diagnostic.',
      evidence: { exitCode: result.status ?? 1 },
    })],
  };
}

const COMPOSITION_CHECKS = new Set([
  'label_route_clearance',
  'relationship_crossings',
  'relationship_corridors',
  'container_border_runs',
  'route_rhythm',
]);

const CHECK_FIXES = {
  single_svg: ['remove additional SVG roots so the artifact contains exactly one diagram SVG'],
  finite_svg: ['replace non-finite coordinates before rendering again'],
  orthogonal_arrows: ['use renderer-supported orthogonal routing controls'],
  legend_clearance: ['move the route or enlarge the viewBox so relationships do not enter the legend'],
};

const COMPOSITION_FIXES = {
  'composition/proper-crossing': ['if authored via/route/channelX/channelY controls exist and are not required by the user, remove them to let the renderer re-plan; otherwise preserve that intent and adjust route/via or channel coordinates so unrelated relationships use separate corridors'],
  'composition/ambiguous-corridor': ['if authored via/route/channelX/channelY controls exist and are not required by the user, remove them to let the renderer re-plan; otherwise preserve that intent and adjust route/via or channel coordinates so unrelated relationships do not visually merge'],
  'composition/container-border-run': ['if authored via/route/channelX/channelY controls exist and are not required by the user, remove them to let the renderer re-plan; otherwise preserve that intent and route across the frame perpendicularly through a clear opening'],
  'composition/label-route-clearance': ['if authored labelAt/labelDx/labelDy/labelSegment controls exist and are not required by the user, remove them to let the renderer re-plan; otherwise preserve that intent and adjust labelAt, labelDx, labelDy, labelSegment, message y, or the other relationship route'],
  'composition/label-canvas-containment': ['if authored labelAt/labelDx/labelDy/labelSegment controls exist and are not required by the user, remove them to let the renderer re-plan; otherwise preserve that intent and adjust labelAt, labelDx, labelDy, or labelSegment so the label rect stays inside the viewBox, or enlarge meta.viewBox'],
  'composition/micro-segment': ['if authored via/route/channelX/channelY controls exist and are not required by the user, remove them to let the renderer re-plan; otherwise preserve that intent and move the route/channel/via point so every visible segment is at least 8px'],
  'composition/short-interior-segment': ['if authored via/route/channelX/channelY controls exist and are not required by the user, remove them to let the renderer re-plan; otherwise preserve that intent and move the route/channel/via point so every interior turn has at least 16px'],
};

function checkerDiagnostics(checker) {
  if (checker?.family === 'explainer' && checker.diagnostics?.some(entry => entry.severity === 'error')) return checker.diagnostics.filter(entry => entry.severity === 'error').map(entry => diagnostic(entry));
  const diagnostics = [];
  for (const issue of checker?.composition?.issues || []) {
    if (issue.severity !== 'error') continue;
    const { severity, code, relationship, nodeId, ...evidence } = issue;
    diagnostics.push(diagnostic({
      code,
      severity,
      message: `Final artifact failed ${code}.`,
      subject: relationship ? { relationship } : { check: 'composition', ...(nodeId ? { nodeId } : {}) },
      evidence,
      supportedFixes: compositionFixes(issue),
    }));
  }
  for (const check of checker?.checks || []) {
    if (check.ok || COMPOSITION_CHECKS.has(check.name)) continue;
    if (check.name === 'svg_path_data') {
      const pathDiagnostics = (checker.diagnostics || []).filter(item => (
        item?.severity === 'error'
        && ['artifact/svg-path-malformed', 'artifact/svg-path-unsupported'].includes(item.code)
      ));
      if (pathDiagnostics.length) {
        diagnostics.push(...pathDiagnostics.map(item => diagnostic(item)));
        continue;
      }
    }
    diagnostics.push(diagnostic({
      code: `artifact/${check.name.replaceAll('_', '-')}`,
      message: (check.details || []).find(Boolean) || `Final artifact failed ${check.name}.`,
      subject: { check: check.name },
      evidence: { details: check.details || [] },
      supportedFixes: CHECK_FIXES[check.name] || [],
    }));
  }
  return diagnostics.length ? diagnostics : [diagnostic({
    code: 'artifact/check-failed',
    message: 'Final artifact check failed without a classified diagnostic.',
    subject: { check: 'unknown' },
    evidence: {},
  })];
}

function compositionFixes(issue) {
  if (issue.code === 'composition/viewport-height') return [String(issue.detail || '').replace(/^\[[^\]]+\]\s*/, '')];
  if (issue.code !== 'composition/desktop-readability') return COMPOSITION_FIXES[issue.code] || [];
  const sourceFontPx = Number(issue.sourceFontPx);
  const actualBudgetPx = Number(issue.availableDiagramWidth);
  const hardFloorPx = Number(issue.minimumProjectedFontPx);
  const viewBoxWidth = Number(issue.viewBoxWidth);
  const preserveIntent = 'Preserve the semantic text and any supplied coordinates, routes, sides, channels, and labels.';
  const readerCap = issue.budgetBasis === 'recognized-declared-wide'
    ? ` The declared Reader reports a ${issue.budgetLimit} limit and ${actualBudgetPx}px actual diagram budget; do not assume an uncapped viewport.`
    : '';
  if (![sourceFontPx, actualBudgetPx, hardFloorPx, viewBoxWidth].every(Number.isFinite)
    || actualBudgetPx <= 0 || hardFloorPx <= 0 || viewBoxWidth <= 0) {
    return [`${preserveIntent} Repair the measured source font, desktop budget, or complete viewBox width; position-only label controls do not change projected text size.`];
  }
  if (sourceFontPx < hardFloorPx) {
    return [`${preserveIntent} The diagnosed ${sourceFontPx}px source text is below the ${hardFloorPx}px hard floor even at scale 1, so use a renderer-supported semantic text-size setting or renderer-level fix. Position-only label controls cannot repair its projection.${readerCap}`];
  }
  const maximumViewBoxWidth = Math.floor((sourceFontPx * actualBudgetPx) / hardFloorPx);
  return [`${preserveIntent} Compactly reflow automatic spacing and empty corridors so the complete viewBox width is at most ${maximumViewBoxWidth}px (current ${viewBoxWidth}px; ${sourceFontPx}px source text at ${actualBudgetPx}px desktop budget). If supplied geometry fixes that width, use a renderer-supported semantic text-size setting or renderer-level fix instead. Position-only label controls cannot repair its projection.${readerCap}`];
}

function formatDiagnostics(error, diagnostics = []) {
  if (!diagnostics.length) return error;
  return [
    error,
    ...diagnostics.map((entry) => {
      const fix = entry.supportedFixes?.length ? ` Fix: ${entry.supportedFixes.join('; ')}.` : '';
      return `[${entry.code}] ${entry.message}${fix}`;
    }),
  ].join('\n');
}

function exitFrom(result) {
  if (result.error) fail(result.error.message, 1);
  process.exit(result.status ?? 1);
}

function reportCompareFailure({ json, stage, error, code = 'delta/internal', details = {}, status = 1 }) {
  const receipt = {
    schemaVersion: 1,
    ok: false,
    command: 'compare',
    type: 'architecture',
    stage,
    error,
    diagnostics: [{
      code,
      severity: 'error',
      message: error,
      subject: details.side ? { side: details.side, ...(details.path ? { path: details.path } : {}) } : {},
      evidence: Object.fromEntries(Object.entries(details).filter(([key]) => !['side', 'path', 'supportedFixes'].includes(key))),
      supportedFixes: details.supportedFixes || [],
    }],
  };
  if (json) console.log(JSON.stringify(receipt, null, 2));
  else console.error(formatDiagnostics(error, receipt.diagnostics));
  process.exitCode = status;
}

function extractCompareOptions(args) {
  const positional = [];
  let receipt;
  let json = false;
  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (arg === '--json') {
      json = true;
      continue;
    }
    if (arg === '--receipt') {
      receipt = args[index + 1];
      if (!receipt || receipt.startsWith('--')) fail('--receipt requires a JSON output path.');
      index += 1;
      continue;
    }
    if (arg.startsWith('--receipt=')) {
      receipt = arg.slice('--receipt='.length);
      if (!receipt) fail('--receipt requires a JSON output path.');
      continue;
    }
    if (arg.startsWith('--')) fail(`Unknown compare option "${arg}".`);
    positional.push(arg);
  }
  return { positional, receipt, json };
}

function compareReceiptPath(outputPath) {
  const { directory, stem, options } = deliverySidecarNamespace(outputPath);
  return path.join(
    directory,
    `${boundedSidecarStem(stem, COMPARE_SIDECAR_SUFFIXES, options)}.receipt.json`,
  );
}

function compareCommitError(message, code, details = {}) {
  const error = new Error(message);
  error.compareStage = 'commit';
  error.compareCode = code;
  error.compareDetails = details;
  return error;
}

function compareAtomicOutputFailure(result, label, requestedPath, stage) {
  const reason = result.reason || { code: 'atomic-output-unknown' };
  let code = 'output/target-indeterminate';
  let message = `The compare ${label} target identity could not be verified safely.`;
  let supportedFixes = ['use an ordinary local filesystem path with stable file identity, then retry'];
  if (typeof reason.code === 'string' && reason.code.endsWith('-hardlinked')) {
    code = 'output/target-hardlinked';
    message = `The compare ${label} target has multiple hard links and cannot be replaced atomically.`;
    supportedFixes = [`choose a ${label} path that is absent or names a regular file with one link`];
  } else if (reason.code === 'target-not-regular-file') {
    code = 'output/target-not-regular-file';
    message = `The compare ${label} target is not a regular file.`;
    supportedFixes = [`choose an absent or regular-file path for the ${label}`];
  } else if (result.status === 'different') {
    code = 'output/target-changed';
    message = `The compare ${label} target changed while the artifact pair was being prepared.`;
    supportedFixes = ['retry after other processes stop creating, replacing, or redirecting compare outputs'];
  }
  return {
    stage,
    code,
    message,
    details: {
      side: label,
      path: requestedPath,
      atomicOutput: reason,
      supportedFixes,
    },
  };
}

function commitComparePair({
  htmlCandidate,
  htmlContent,
  receiptCandidate,
  receiptContent,
  outputCapture,
  receiptCapture,
  stagingDirectory,
  verifyAtomicOutput,
  fileBindingRuntime,
}) {
  const {
    backupPublicRegularFileBinding,
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    verifyRegularFileBinding,
    releaseRegularFileBinding,
  } = fileBindingRuntime || {};
  const targets = [
    {
      label: 'HTML artifact', capture: outputCapture, candidate: htmlCandidate, content: htmlContent, backup: path.join(stagingDirectory, '.previous-output'),
    },
    {
      label: 'receipt', capture: receiptCapture, candidate: receiptCandidate, content: receiptContent, backup: path.join(stagingDirectory, '.previous-receipt'),
    },
  ];
  const targetChanged = (item, result) => {
    const normalized = typeof result === 'string'
      ? { status: 'different', reason: { code: result } }
      : result;
    const failure = compareAtomicOutputFailure(
      normalized,
      item.label,
      item.capture.snapshot.requestedPath,
      'commit',
    );
    const error = compareCommitError(failure.message, failure.code, failure.details);
    error.compareFailure = failure;
    return error;
  };

  const backedUp = [];
  const committed = [];
  let retainSuccessfulBackupBindings = false;
  try {
    if (typeof backupPublicRegularFileBinding !== 'function'
      || typeof captureRegularFileBinding !== 'function'
      || typeof quarantineRemoveRegularFileBinding !== 'function'
      || typeof verifyRegularFileBinding !== 'function'
      || typeof releaseRegularFileBinding !== 'function') {
      throw targetChanged(targets[0], {
        status: 'unknown',
        reason: { code: 'atomic-output-runtime-unavailable' },
      });
    }
    // Re-resolve and bind both requested write slots and candidate inodes
    // before moving either target. The held handles keep bytes, mode and
    // identity authoritative across every publish/finalize transition.
    for (const item of targets) {
      const verification = verifyAtomicOutput(item.capture.snapshot);
      if (verification.status !== 'match') throw targetChanged(item, verification);
      if (item.capture.mode !== null) fs.chmodSync(item.candidate, item.capture.mode);
      const candidate = captureRegularFileBinding(item.candidate, {
        subject: 'compare-candidate',
        expectedSha256: item.content.sha256,
        expectedBytes: item.content.bytes,
        ...(item.capture.mode === null ? {} : { expectedMode: item.capture.mode }),
        expectedLinks: 1,
      });
      if (candidate.status !== 'captured') throw targetChanged(item, candidate);
      item.candidateBinding = candidate.binding;
      item.candidatePresent = true;
      item.candidateIdentity = {
        dev: candidate.identity.device,
        ino: candidate.identity.inode,
      };
      item.candidateMode = candidate.mode;
      if (item.capture.snapshot.target.kind === 'file') {
        const expected = item.capture.snapshot.target;
        const previous = captureRegularFileBinding(item.capture.commitPath, {
          subject: 'previous-compare-target',
          expectedIdentity: { device: expected.device, inode: expected.inode },
          expectedMode: expected.mode,
          expectedLinks: 1,
        });
        if (previous.status !== 'captured') throw targetChanged(item, previous);
        item.previousBinding = previous.binding;
      }
    }
    for (const item of targets) {
      if (item.capture.snapshot.target.kind !== 'file') continue;
      const moved = backupPublicRegularFileBinding(
        item.previousBinding,
        item.capture.commitPath,
        item.backup,
        { subject: 'previous-compare-target' },
      );
      item.backupPresent = moved.backupCreated === true;
      item.backupVerified = moved.backupVerified === true;
      if (item.backupPresent) backedUp.push(item);
      if (moved.status === 'recovery-required' && moved.recoveryFile) {
        item.backupRecovery = moved.recoveryFile;
      }
      if (moved.status !== 'backed-up') throw targetChanged(item, moved);
    }
    for (const item of targets) {
      const candidate = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.candidate,
        expectedLinks: 1,
      });
      if (candidate.status !== 'match') throw targetChanged(item, candidate);
      try {
        // linkSync is the no-clobber publish primitive: unlike renameSync, it
        // fails with EEXIST if another writer claims an absent slot after the
        // final snapshot verification.
        fs.linkSync(item.candidate, item.capture.commitPath);
      } catch (error) {
        if (error?.code === 'EEXIST') {
          throw targetChanged(
            item,
            'target-claimed-during-publish',
          );
        }
        throw error;
      }
      item.committedIdentity = item.candidateIdentity;
      committed.push(item);
      const linked = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.capture.commitPath,
        expectedLinks: 2,
      });
      if (linked.status !== 'match') throw targetChanged(item, linked);
    }
    for (const item of committed) {
      const current = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.capture.commitPath,
        expectedLinks: 2,
      });
      if (current.status !== 'match') throw targetChanged(item, current);
    }
    // The target remains the durable link. Removing the staging links inside
    // the transaction keeps successful outputs at nlink=1 even if the outer
    // best-effort staging-directory cleanup later fails.
    for (const item of committed) {
      const staged = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.candidate,
        expectedLinks: 2,
      });
      if (staged.status !== 'match') throw targetChanged(item, staged);
      const retired = quarantineRemoveRegularFileBinding(
        item.candidateBinding,
        item.candidate,
        { subject: 'compare-candidate', expectedLinks: 2 },
      );
      if (retired.status !== 'removed') throw targetChanged(item, retired);
      item.candidatePresent = false;
    }
    for (const item of committed) {
      const finalized = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.capture.commitPath,
        expectedLinks: 1,
      });
      if (finalized.status !== 'match') throw targetChanged(item, finalized);
    }
    retainSuccessfulBackupBindings = true;
    return {
      ownedBackupEntries: backedUp
        .filter((item) => item.backupPresent)
        .map((item) => ({
          filePath: item.backup,
          binding: item.previousBinding,
          subject: 'previous-compare-backup',
          expectedLinks: 1,
        })),
    };
  } catch (cause) {
    const rollbackErrors = [];
    const recoveryFiles = targets
      .filter((item) => item.backupRecovery)
      .map((item) => ({
        backup: item.backupRecovery,
        target: item.capture.commitPath,
        verifiedPrevious: false,
      }));
    for (const item of [...committed].reverse()) {
      try {
        const removed = quarantineRemoveRegularFileBinding(
          item.candidateBinding,
          item.capture.commitPath,
          {
            subject: 'published-compare-target',
            expectedLinks: item.candidatePresent ? 2 : 1,
          },
        );
        if (removed.status !== 'removed') {
          if (removed.status === 'recovery-required') {
            recoveryFiles.push({
              backup: removed.recoveryFile,
              target: item.capture.commitPath,
            });
          }
          throw new Error(`the committed target could not be removed safely (${removed.reason?.code || 'unknown target state'})`);
        }
      } catch (error) {
        rollbackErrors.push(`${item.label}: remove failed (${error.message})`);
      }
    }
    for (const item of [...backedUp].reverse()) {
      try {
        if (pathEntryExists(item.capture.commitPath)) {
          const current = item.candidateBinding
            ? verifyRegularFileBinding(item.candidateBinding, {
              filePath: item.capture.commitPath,
              expectedLinks: item.candidatePresent ? 2 : 1,
            })
            : { status: 'different' };
          if (current.status !== 'match') {
            throw new Error(`a changed target claimant prevents restoring the previous file (${current.reason?.code || 'unknown target state'})`);
          }
          const removed = quarantineRemoveRegularFileBinding(
            item.candidateBinding,
            item.capture.commitPath,
            {
              subject: 'published-compare-target',
              expectedLinks: item.candidatePresent ? 2 : 1,
            },
          );
          if (removed.status !== 'removed') {
            if (removed.status === 'recovery-required') {
              recoveryFiles.push({
                backup: removed.recoveryFile,
                target: item.capture.commitPath,
              });
            }
            throw new Error(`the committed target could not be removed safely (${removed.reason?.code || 'unknown target state'})`);
          }
        }
        if (item.backupVerified !== true) {
          throw new Error('the backup entry was never verified as the previous file');
        }
        const currentBackup = verifyRegularFileBinding(item.previousBinding, {
          filePath: item.backup,
          expectedLinks: 1,
        });
        if (currentBackup.status !== 'match') {
          item.backupVerified = false;
          throw new Error('the recoverable backup was replaced before rollback');
        }
        // Publish the previous file without clobbering a claimant that appears
        // after the absence check. The backup remains the recovery source until
        // the restored hard link has been identity-verified.
        fs.linkSync(item.backup, item.capture.commitPath);
        for (const restoredPath of [item.capture.commitPath, item.backup]) {
          const restored = verifyRegularFileBinding(item.previousBinding, {
            filePath: restoredPath,
            expectedLinks: 2,
          });
          if (restored.status !== 'match') {
            throw new Error('the restored target identity could not be verified');
          }
        }
        const retired = quarantineRemoveRegularFileBinding(
          item.previousBinding,
          item.backup,
          { subject: 'previous-compare-target', expectedLinks: 2 },
        );
        if (retired.status !== 'removed') {
          throw new Error(`the restored backup could not be retired safely (${retired.reason?.code || 'unknown target state'})`);
        }
        item.backupPresent = false;
        const finalized = verifyRegularFileBinding(item.previousBinding, {
          filePath: item.capture.commitPath,
          expectedLinks: 1,
        });
        if (finalized.status !== 'match') {
          throw new Error('the restored target changed before rollback finalized');
        }
      } catch (error) {
        rollbackErrors.push(`${item.label}: restore failed (${error.message})`);
        // Track failed restoration rather than probing existence: a permission
        // error must not make cleanup discard a potentially recoverable backup.
        if (item.backupPresent !== false) {
          recoveryFiles.push({
            backup: item.backup,
            target: item.capture.commitPath,
            verifiedPrevious: item.backupVerified === true,
          });
        }
      }
    }
    if (!rollbackErrors.length && cause.compareFailure) {
      throw compareCommitError(
        cause.message,
        cause.compareFailure.code,
        {
          ...cause.compareFailure.details,
          reason: cause.message,
        },
      );
    }
    throw compareCommitError(
      (rollbackErrors.length
        ? 'Architecture Delta pair commit failed and its previous files could not be fully restored.'
        : 'Architecture Delta pair commit failed; the previous files were restored.')
        + (recoveryFiles.length
          ? ` Recovery directory retained at ${path.dirname(recoveryFiles[0].backup)}.`
          : ''),
      rollbackErrors.length ? 'delta/commit-rollback-failed' : 'delta/commit-failed',
      {
        reason: cause.message,
        ...(rollbackErrors.length ? { rollbackErrors } : {}),
        ...(recoveryFiles.length ? {
          recoveryDirectory: path.dirname(recoveryFiles[0].backup),
          recoveryDirectories: [...new Set(recoveryFiles.map(({ backup }) => path.dirname(backup)))],
          recoveryFiles,
        } : {}),
        supportedFixes: recoveryFiles.length
          ? [
            ...recoveryFiles.map(({ backup, target, verifiedPrevious }) => verifiedPrevious
              ? `resolve the filesystem error, inspect the current target, then restore ${JSON.stringify(backup)} to ${JSON.stringify(target)} before retrying`
              : `preserve and inspect the unverified entry at ${JSON.stringify(backup)}; do not treat it as the previous file for ${JSON.stringify(target)}`),
            'remove the recovery directory only after the previous files have been recovered and verified',
          ]
          : ['check that both output paths are writable regular files, then retry'],
      },
    );
  } finally {
    for (const item of targets) {
      if (item.candidateBinding) releaseRegularFileBinding(item.candidateBinding);
      if (item.previousBinding
        && !(retainSuccessfulBackupBindings && item.backupPresent)) {
        releaseRegularFileBinding(item.previousBinding);
      }
    }
  }
}

function commitDeliveryPair({
  htmlCandidate,
  htmlContent,
  provenanceCandidate,
  provenanceContent,
  stagingDirectory,
  ownership,
  verifyAtomicOutput,
  fileBindingRuntime,
}) {
  const {
    backupPublicRegularFileBinding,
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    verifyRegularFileBinding,
    releaseRegularFileBinding,
  } = fileBindingRuntime || {};
  const state = assertDeliveryOwnership(ownership, 'start the delivery pair commit', { pending: 'owned' });
  const snapshots = state.deliveryTargets;
  if (!snapshots?.artifact || !snapshots?.provenance) {
    throw deliveryTargetStateError(state.output, 'delivery pair', {
      status: 'unknown',
      reason: { code: 'target-snapshot-missing' },
    });
  }
  const targets = [
    {
      label: 'HTML artifact',
      target: snapshots.artifact.commitPath,
      candidate: htmlCandidate,
      content: htmlContent,
      backup: path.join(stagingDirectory, '.previous-output'),
      capture: snapshots.artifact,
    },
    {
      label: 'delivery provenance',
      target: snapshots.provenance.commitPath,
      candidate: provenanceCandidate,
      content: provenanceContent,
      backup: path.join(stagingDirectory, '.previous-provenance'),
      capture: snapshots.provenance,
    },
  ];
  const backedUp = [];
  const retainedBackups = new Set();
  const publicRecoveryBackups = [];
  let retainSuccessfulBackupBindings = false;
  const committed = [];
  try {
    if (typeof backupPublicRegularFileBinding !== 'function'
      || typeof captureRegularFileBinding !== 'function'
      || typeof quarantineRemoveRegularFileBinding !== 'function'
      || typeof verifyRegularFileBinding !== 'function'
      || typeof releaseRegularFileBinding !== 'function') {
      throw deliveryTargetStateError(state.output, 'delivery pair', {
        status: 'unknown',
        reason: { code: 'atomic-output-runtime-unavailable' },
      });
    }
    for (const item of targets) {
      const verification = verifyAtomicOutput(item.capture.snapshot);
      if (verification.status !== 'match') {
        throw deliveryTargetStateError(item.capture.requestedPath, item.label, verification);
      }
      if (item.capture.mode !== null) fs.chmodSync(item.candidate, item.capture.mode);
      const candidate = captureRegularFileBinding(item.candidate, {
        subject: 'delivery-candidate',
        expectedSha256: item.content.sha256,
        expectedBytes: item.content.bytes,
        ...(item.capture.mode === null ? {} : { expectedMode: item.capture.mode }),
        expectedLinks: 1,
      });
      if (candidate.status !== 'captured') {
        throw deliveryTargetStateError(item.capture.requestedPath, item.label, candidate);
      }
      item.candidateBinding = candidate.binding;
      item.candidatePresent = true;
      item.candidateIdentity = {
        dev: candidate.identity.device,
        ino: candidate.identity.inode,
      };
      item.candidateMode = candidate.mode;
      if (item.capture.snapshot.target.kind === 'file') {
        const expected = item.capture.snapshot.target;
        const previous = captureRegularFileBinding(item.target, {
          subject: 'previous-delivery-target',
          expectedIdentity: { device: expected.device, inode: expected.inode },
          expectedMode: expected.mode,
          expectedLinks: 1,
        });
        if (previous.status !== 'captured') {
          throw deliveryTargetStateError(item.capture.requestedPath, item.label, previous);
        }
        item.previousBinding = previous.binding;
      }
    }
    for (const item of targets) {
      if (item.capture.snapshot.target.kind !== 'file') continue;
      assertDeliveryOwnership(ownership, `back up the ${item.label}`, { pending: 'owned' });
      const moved = backupPublicRegularFileBinding(
        item.previousBinding,
        item.target,
        item.backup,
        { subject: 'previous-delivery-target' },
      );
      item.backupPresent = moved.backupCreated === true;
      item.backupVerified = moved.backupVerified === true;
      if (item.backupPresent) backedUp.push(item);
      if (moved.status === 'recovery-required' && moved.recoveryFile) {
        publicRecoveryBackups.push({
          label: `preserved replacement for ${item.label}`,
          path: moved.recoveryFile,
          target: item.target,
        });
      }
      if (moved.status !== 'backed-up') {
        throw deliveryTargetStateError(item.capture.requestedPath, item.label, moved);
      }
      retainedBackups.add(item);
    }
    for (const item of targets) {
      assertDeliveryOwnership(ownership, `commit the ${item.label}`, { pending: 'owned' });
      const candidate = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.candidate,
        expectedLinks: 1,
      });
      if (candidate.status !== 'match') {
        throw deliveryTargetStateError(item.capture.requestedPath, item.label, candidate);
      }
      try {
        fs.linkSync(item.candidate, item.target);
      } catch (error) {
        if (error?.code === 'EEXIST') {
          throw deliveryTargetStateError(item.capture.requestedPath, item.label, {
            status: 'different',
            reason: { code: 'target-claimed-during-publish' },
          });
        }
        throw error;
      }
      item.committedIdentity = item.candidateIdentity;
      committed.push(item);
      const linked = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.target,
        expectedLinks: 2,
      });
      if (linked.status !== 'match') {
        throw deliveryTargetStateError(item.capture.requestedPath, item.label, linked);
      }
    }
    for (const item of committed) {
      assertDeliveryOwnership(ownership, `verify the committed ${item.label}`, { pending: 'owned' });
      const current = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.target,
        expectedLinks: 2,
      });
      if (current.status !== 'match') {
        throw deliveryTargetStateError(item.capture.requestedPath, item.label, current);
      }
    }
    for (const item of committed) {
      const staged = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.candidate,
        expectedLinks: 2,
      });
      if (staged.status !== 'match') {
        throw deliveryTargetStateError(item.capture.requestedPath, item.label, staged);
      }
      const retired = quarantineRemoveRegularFileBinding(
        item.candidateBinding,
        item.candidate,
        { subject: 'delivery-candidate', expectedLinks: 2 },
      );
      if (retired.status !== 'removed') {
        throw deliveryTargetStateError(item.capture.requestedPath, item.label, retired);
      }
      item.candidatePresent = false;
    }
    for (const item of committed) {
      const finalized = verifyRegularFileBinding(item.candidateBinding, {
        filePath: item.target,
        expectedLinks: 1,
      });
      if (finalized.status !== 'match') {
        throw deliveryTargetStateError(item.capture.requestedPath, item.label, finalized);
      }
    }
    // Finalization is part of the commit: keep the old files recoverable until
    // the journal has been removed and checkers can accept the new artifact.
    assertDeliveryOwnership(ownership, 'finalize the delivery journal', { pending: 'owned' });
    quarantineRemoveOwnedDeliveryEntry(state, {
      filePath: state.pendingPath,
      identity: state.pendingIdentity,
      content: state.pendingContent,
      subject: 'delivery-journal',
      operation: 'finalize the delivery journal',
      evidenceKey: 'journal',
    });
    assertDeliveryOwnership(ownership, 'finish finalizing the delivery journal', { pending: 'absent' });
    state.pendingIdentity = undefined;
    state.pendingContent = undefined;
    state.phase = 'finalized';
    retainSuccessfulBackupBindings = true;
    return {
      recoverableBackups: [
        ...[...retainedBackups].map((item) => ({ label: item.label, path: item.backup })),
        ...publicRecoveryBackups,
      ],
      ownedBackupEntries: backedUp
        .filter((item) => item.backupPresent)
        .map((item) => ({
          filePath: item.backup,
          binding: item.previousBinding,
          subject: 'previous-delivery-backup',
          expectedLinks: 1,
        })),
    };
  } catch (cause) {
    const recoveryDetails = () => ({
      recoveryRequired: true,
      recoveryDirectory: stagingDirectory,
      recoverableBackups: [
        ...[...retainedBackups].map((item) => ({ label: item.label, path: item.backup })),
        ...publicRecoveryBackups,
      ],
    });
    if (cause.deliveryOwnershipCode === 'delivery/ownership-lost') {
      cause.deliveryCommitDetails = { ...(cause.deliveryCommitDetails || {}), ...recoveryDetails() };
      throw cause;
    }
    const rollbackErrors = [];
    const recoverableBackups = [];
    try {
      for (const item of [...committed].reverse()) {
        try {
          assertDeliveryOwnership(ownership, `roll back the ${item.label}`, { pending: 'identity' });
          const removed = quarantineRemoveRegularFileBinding(item.candidateBinding, item.target, {
            subject: 'published-delivery-target',
            expectedLinks: item.candidatePresent ? 2 : 1,
          });
          if (removed.status !== 'removed') {
            if (removed.status === 'recovery-required') {
              publicRecoveryBackups.push({
                label: `preserved replacement for ${item.label}`,
                path: removed.recoveryFile,
                target: item.target,
              });
            }
            throw new Error(`the committed target could not be removed safely (${removed.reason?.code || 'unknown target state'})`);
          }
        } catch (error) {
          if (error.deliveryOwnershipCode === 'delivery/ownership-lost') throw error;
          rollbackErrors.push(`${item.label}: remove failed (${error.message})`);
        }
      }
      for (const item of [...backedUp].reverse()) {
        try {
          assertDeliveryOwnership(ownership, `restore the previous ${item.label}`, { pending: 'identity' });
          if (pathEntryExists(item.target)) {
            const current = item.candidateBinding
              ? verifyRegularFileBinding(item.candidateBinding, {
                filePath: item.target,
                expectedLinks: item.candidatePresent ? 2 : 1,
              })
              : { status: 'different' };
            if (current.status !== 'match') {
              throw new Error(`a changed target claimant prevents restoring the previous file (${current.reason?.code || 'unknown target state'})`);
            }
            const removed = quarantineRemoveRegularFileBinding(item.candidateBinding, item.target, {
              subject: 'published-delivery-target',
              expectedLinks: item.candidatePresent ? 2 : 1,
            });
            if (removed.status !== 'removed') {
              if (removed.status === 'recovery-required') {
                publicRecoveryBackups.push({
                  label: `preserved replacement for ${item.label}`,
                  path: removed.recoveryFile,
                  target: item.target,
                });
              }
              throw new Error(`the committed target could not be removed safely (${removed.reason?.code || 'unknown target state'})`);
            }
          }
          assertDeliveryOwnership(ownership, `restore the previous ${item.label}`, { pending: 'identity' });
          if (item.backupVerified !== true) {
            throw new Error('the backup entry was never verified as the previous delivery file');
          }
          const currentBackup = verifyRegularFileBinding(item.previousBinding, {
            filePath: item.backup,
            expectedLinks: 1,
          });
          if (currentBackup.status !== 'match') {
            item.backupVerified = false;
            retainedBackups.delete(item);
            throw new Error('the previous delivery backup identity changed');
          }
          try {
            fs.linkSync(item.backup, item.target);
          } catch (error) {
            if (error?.code === 'EEXIST') {
              throw new Error('a new target claimant prevents restoring the previous file');
            }
            throw error;
          }
          for (const restoredPath of [item.target, item.backup]) {
            const restored = verifyRegularFileBinding(item.previousBinding, {
              filePath: restoredPath,
              expectedLinks: 2,
            });
            if (restored.status !== 'match') {
              throw new Error('the restored delivery target identity could not be verified');
            }
          }
          const retired = quarantineRemoveRegularFileBinding(
            item.previousBinding,
            item.backup,
            { subject: 'previous-delivery-target', expectedLinks: 2 },
          );
          if (retired.status !== 'removed') {
            throw new Error(`the restored delivery backup could not be retired safely (${retired.reason?.code || 'unknown target state'})`);
          }
          item.backupPresent = false;
          const restoredFinal = verifyRegularFileBinding(item.previousBinding, {
            filePath: item.target,
            expectedLinks: 1,
          });
          if (restoredFinal.status !== 'match') {
            throw new Error('the restored delivery target link count could not be verified');
          }
          retainedBackups.delete(item);
        } catch (error) {
          if (error.deliveryOwnershipCode === 'delivery/ownership-lost') throw error;
          rollbackErrors.push(`${item.label}: restore failed (${error.message})`);
          // A failed restoration leaves this exact backup at its source path.
          // Record it without probing the failing recovery path again.
          if (item.backupPresent !== false) {
            recoverableBackups.push({
              label: item.backupVerified === true
                ? item.label
                : `unverified preserved backup entry for ${item.label}`,
              path: item.backup,
              target: item.target,
              verifiedPrevious: item.backupVerified === true,
            });
          }
        }
      }
      assertDeliveryOwnership(ownership, 'finish the delivery rollback', { pending: 'identity' });
    } catch (rollbackError) {
      if (rollbackError.deliveryOwnershipCode === 'delivery/ownership-lost') {
        rollbackError.deliveryCommitDetails = {
          ...(rollbackError.deliveryCommitDetails || {}),
          commitError: {
            reason: cause.message,
            ...(cause?.code ? { systemCode: cause.code } : {}),
          },
          ...recoveryDetails(),
        };
        throw rollbackError;
      }
      rollbackErrors.push(rollbackError.message);
    }
    const error = new Error(rollbackErrors.length
      ? 'Delivery pair commit failed and its previous files could not be fully restored.'
      : 'Delivery pair commit failed; the previous files were restored.');
    error.deliveryCommitDetails = {
      reason: cause.message,
      ...(rollbackErrors.length ? {
        rollbackErrors,
        recoveryRequired: true,
        recoveryDirectory: stagingDirectory,
        recoverableBackups: [...recoverableBackups, ...publicRecoveryBackups],
      } : {}),
    };
    if (cause.deliveryTargetState) {
      error.deliveryTargetState = cause.deliveryTargetState;
      error.archifyDiagnostics = cause.archifyDiagnostics;
    }
    throw error;
  } finally {
    for (const item of targets) {
      if (item.candidateBinding) releaseRegularFileBinding(item.candidateBinding);
      if (item.previousBinding
        && !(retainSuccessfulBackupBindings && item.backupPresent)) {
        releaseRegularFileBinding(item.previousBinding);
      }
    }
  }
}

function renderValidatedArchitecture(inputPath, outputPath, quality, repoRoot, captureStagingFile) {
  const render = runNode([rendererPath('architecture'), inputPath, outputPath], {
    stdio: 'pipe',
    env: rendererEnv(quality, repoRoot, true),
  });
  if (render.status !== 0) {
    const failure = rendererFailure(render);
    const error = new Error(failure.error);
    error.compareStage = 'input';
    error.compareStatus = render.status ?? 1;
    error.diagnostics = failure.diagnostics;
    throw error;
  }
  let artifact;
  if (captureStagingFile) {
    artifact = fs.readFileSync(outputPath);
    captureStagingFile(outputPath, artifactIdentity(artifact));
  }
  const checkMaxBuffer = artifactCheckMaxBuffer();
  const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), outputPath], {
    stdio: 'pipe',
    maxBuffer: checkMaxBuffer,
  });
  if (check.status !== 0) {
    const error = new Error('Validated snapshot failed final artifact checks.');
    error.compareStage = 'check';
    error.compareStatus = check.status ?? 1;
    const outputLimit = checkerOutputLimitDiagnostics(check, checkMaxBuffer);
    if (outputLimit) {
      error.diagnostics = outputLimit;
    } else {
      try {
        error.checker = JSON.parse(check.stdout);
        error.diagnostics = checkerDiagnostics(error.checker);
      } catch {
        error.diagnostics = [];
      }
    }
    throw error;
  }
  artifact ||= fs.readFileSync(outputPath);
  return {
    artifact,
    html: artifact.toString('utf8'),
    checks: JSON.parse(check.stdout),
    sourceEvidence: sourceEvidenceFromArtifact(artifact),
  };
}

async function commandCompare(args) {
  await loadSidecarPathRuntime();
  const {
    canonicalFuturePath,
    resolveOutputPath,
    validateAuthoredOutputPath,
  } = await import('../renderers/shared/output-path.mjs');
  const {
    captureAtomicOutput,
    verifyAtomicOutput,
    backupPublicRegularFileBinding,
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    verifyRegularFileBinding,
    releaseRegularFileBinding,
  } = await import('../renderers/shared/atomic-output.mjs');
  const fileBindingRuntime = {
    backupPublicRegularFileBinding,
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    verifyRegularFileBinding,
    releaseRegularFileBinding,
  };
  const {
    sameParent,
    sidecarNamespaceComponentKey,
  } = await import('../renderers/shared/path-semantics.mjs');
  sidecarNamespaceComponentKeyRuntime = sidecarNamespaceComponentKey;
  const qualityArgs = extractQualityArgs(args);
  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
  const options = extractCompareOptions(repoArgs.rest);
  const [type, baseInput, headInput, requestedOutput] = options.positional;
  if (type !== 'architecture' || !baseInput || !headInput || options.positional.length > 4) fail(usage());
  let deltaRuntime;
  try {
    deltaRuntime = await import(pathToFileURL(path.join(skillRoot, 'delta/architecture-delta.mjs')).href);
  } catch (error) {
    reportCompareFailure({ json: options.json, stage: 'prepare', error: 'Architecture compare runtime is unavailable.', code: 'delta/runtime-missing', details: { reason: error.message, supportedFixes: ['install the complete Archify skill package'] } });
    return;
  }
  const {
    ArchitectureDeltaError,
    annotateArchitectureSideSvg,
    buildDeltaSvg,
    canonicalArchitecture,
    canonicalArchitectureJson,
    compareArchitecture,
    extractArchitectureSvg,
    extractArtifactCss,
    renderArchitectureDeltaHtml,
    validateArchitectureDeltaHtml,
  } = deltaRuntime;

  const basePath = path.resolve(baseInput);
  const headPath = path.resolve(headInput);
  const explicitReceiptTarget = options.receipt ? path.resolve(options.receipt) : undefined;
  const rawOutputTarget = requestedOutput || 'architecture-delta.html';
  const rawOutputExtension = path.extname(rawOutputTarget);
  // Preserve the established alias-first diagnostic for an already-invalid
  // CLI extension without letting this legacy spelling select the real
  // sidecar namespace for any valid compare output.
  const invalidOutputAliasPreflight = !explicitReceiptTarget
    && rawOutputExtension.toLowerCase() !== '.html'
    ? path.resolve(rawOutputExtension
      ? `${rawOutputTarget.slice(0, -rawOutputExtension.length)}.receipt.json`
      : `${rawOutputTarget}.receipt.json`)
    : undefined;
  let outputPath;
  try {
    ({ outputPath } = resolveOutputPath({
      requestedOutput,
      defaultOutput: 'architecture-delta.html',
      inputPaths: [basePath, headPath],
      otherOutputPaths: explicitReceiptTarget
        ? [explicitReceiptTarget]
        : (invalidOutputAliasPreflight ? [invalidOutputAliasPreflight] : []),
    }));
  } catch (error) {
    const outputDiagnostic = error.archifyDiagnostics?.[0];
    reportCompareFailure({
      json: options.json,
      stage: 'prepare',
      error: error.message,
      code: outputDiagnostic?.code || 'output/path-resolution',
      details: {
        ...(outputDiagnostic?.subject || {}),
        ...(outputDiagnostic?.evidence || {}),
        supportedFixes: outputDiagnostic?.supportedFixes || ['choose a safe output path and retry'],
      },
    });
    return;
  }
  const requestedOutputPath = outputPath;
  let receiptPath;
  let requestedReceiptPath;
  if (explicitReceiptTarget) {
    try {
      ({ outputPath: receiptPath } = resolveOutputPath({
        requestedOutput: options.receipt,
        defaultOutput: options.receipt,
        requiredExtension: '.json',
        inputPaths: [basePath, headPath],
        otherOutputPaths: [outputPath],
      }));
      requestedReceiptPath = receiptPath;
    } catch (error) {
      const outputDiagnostic = error.archifyDiagnostics?.[0];
      reportCompareFailure({
        json: options.json,
        stage: 'prepare',
        error: error.message,
        code: outputDiagnostic?.code || 'output/path-resolution',
        details: {
          ...(outputDiagnostic?.subject || {}),
          ...(outputDiagnostic?.evidence || {}),
          supportedFixes: outputDiagnostic?.supportedFixes || ['choose a safe receipt path and retry'],
        },
      });
      return;
    }
  }
  try {
    outputPath = canonicalFuturePath(requestedOutputPath);
    if (requestedReceiptPath) receiptPath = canonicalFuturePath(requestedReceiptPath);
  } catch (error) {
    const outputDiagnostic = error.archifyDiagnostics?.[0];
    reportCompareFailure({
      json: options.json,
      stage: 'prepare',
      error: error.message,
      code: outputDiagnostic?.code || 'output/path-resolution',
      details: {
        ...(outputDiagnostic?.subject || {}),
        ...(outputDiagnostic?.evidence || {}),
        supportedFixes: outputDiagnostic?.supportedFixes || ['choose safe compare output paths and retry'],
      },
    });
    return;
  }
  let baseBuffer;
  let headBuffer;
  let base;
  let head;
  try {
    baseBuffer = fs.readFileSync(basePath);
    base = JSON.parse(baseBuffer.toString('utf8'));
  } catch (error) {
    reportCompareFailure({ json: options.json, stage: 'input', error: `Could not read base input: ${error.message}`, code: 'delta/base-input', details: { side: 'base', reason: error.message } });
    return;
  }
  try {
    headBuffer = fs.readFileSync(headPath);
    head = JSON.parse(headBuffer.toString('utf8'));
  } catch (error) {
    reportCompareFailure({ json: options.json, stage: 'input', error: `Could not read head input: ${error.message}`, code: 'delta/head-input', details: { side: 'head', reason: error.message } });
    return;
  }

  for (const [side, document] of [['base', base], ['head', head]]) {
    try {
      validateAuthoredOutputPath(document?.meta?.output);
    } catch (error) {
      const diagnosticEntry = error.archifyDiagnostics?.[0];
      reportCompareFailure({
        json: options.json,
        stage: 'input',
        error: `${side === 'base' ? 'Base' : 'Head'} snapshot failed validation: ${error.message}`,
        code: diagnosticEntry?.code || `delta/${side}-validation`,
        details: {
          side,
          ...(diagnosticEntry?.subject?.path ? { path: diagnosticEntry.subject.path } : {}),
          ...(diagnosticEntry?.evidence || {}),
          supportedFixes: diagnosticEntry?.supportedFixes || [],
        },
      });
      return;
    }
  }

  let outputDirectory = path.dirname(outputPath);
  if (receiptPath) {
    const explicitReceiptDirectoryIdentity = sameParent(outputPath, receiptPath);
    if (explicitReceiptDirectoryIdentity.status === 'unknown') {
      reportCompareFailure({
        json: options.json,
        stage: 'prepare',
        error: 'The compare receipt directory identity could not be verified.',
        code: 'delta/receipt-directory-identity-indeterminate',
        details: {
          artifactDirectory: outputDirectory,
          receiptDirectory: path.dirname(receiptPath),
          pathIdentity: explicitReceiptDirectoryIdentity.reason,
          supportedFixes: ['restore access to both output directories or choose paths in one verifiable directory'],
        },
      });
      return;
    }
    if (explicitReceiptDirectoryIdentity.status !== 'match') {
      reportCompareFailure({
        json: options.json,
        stage: 'prepare',
        error: 'The compare receipt must be written beside the HTML artifact.',
        code: 'delta/receipt-directory',
        details: {
          artifactDirectory: outputDirectory,
          receiptDirectory: path.dirname(receiptPath),
          pathIdentity: explicitReceiptDirectoryIdentity.reason,
          supportedFixes: ['choose a --receipt path in the same directory as output.html'],
        },
      });
      return;
    }
  }
  try {
    fs.mkdirSync(outputDirectory, { recursive: true });
  } catch (error) {
    reportCompareFailure({ json: options.json, stage: 'prepare', error: `Could not create compare output directory: ${error.message}`, code: 'delta/output-directory', details: { reason: error.message } });
    return;
  }

  if (!receiptPath) {
    try {
      const defaultReceiptPath = compareReceiptPath(outputPath);
      ({ outputPath: receiptPath } = resolveOutputPath({
        requestedOutput: defaultReceiptPath,
        defaultOutput: defaultReceiptPath,
        requiredExtension: '.json',
        inputPaths: [basePath, headPath],
        otherOutputPaths: [outputPath],
      }));
      requestedReceiptPath = receiptPath;
      receiptPath = canonicalFuturePath(requestedReceiptPath);
    } catch (error) {
      const outputDiagnostic = error.archifyDiagnostics?.[0];
      const namespaceIndeterminate = error?.code === 'ARCHIFY_SIDECAR_NAMESPACE_INDETERMINATE';
      reportCompareFailure({
        json: options.json,
        stage: 'prepare',
        error: error.message,
        code: namespaceIndeterminate
          ? 'delta/receipt-namespace-indeterminate'
          : outputDiagnostic?.code || 'output/path-resolution',
        details: {
          ...(outputDiagnostic?.subject || {}),
          ...(outputDiagnostic?.evidence || {}),
          ...(namespaceIndeterminate ? { pathIdentity: error.sidecarNamespaceReason } : {}),
          supportedFixes: outputDiagnostic?.supportedFixes
            || ['choose a safe receipt path beside the compare artifact and retry'],
        },
      });
      return;
    }
  }

  const receiptDirectoryIdentity = sameParent(outputPath, receiptPath);
  if (receiptDirectoryIdentity.status === 'unknown') {
    reportCompareFailure({
      json: options.json,
      stage: 'prepare',
      error: 'The compare receipt directory identity could not be verified.',
      code: 'delta/receipt-directory-identity-indeterminate',
      details: {
        artifactDirectory: outputDirectory,
        receiptDirectory: path.dirname(receiptPath),
        pathIdentity: receiptDirectoryIdentity.reason,
        supportedFixes: ['restore access to both output directories or choose paths in one verifiable directory'],
      },
    });
    return;
  }
  if (receiptDirectoryIdentity.status !== 'match') {
    reportCompareFailure({
      json: options.json,
      stage: 'prepare',
      error: 'The compare receipt must be written beside the HTML artifact.',
      code: 'delta/receipt-directory',
      details: {
        artifactDirectory: outputDirectory,
        receiptDirectory: path.dirname(receiptPath),
        pathIdentity: receiptDirectoryIdentity.reason,
        supportedFixes: ['choose a --receipt path in the same directory as output.html'],
      },
    });
    return;
  }

  const outputCapture = captureAtomicOutput(requestedOutputPath);
  const receiptCapture = captureAtomicOutput(requestedReceiptPath);
  for (const [capture, label, requestedPath] of [
    [outputCapture, 'HTML artifact', requestedOutputPath],
    [receiptCapture, 'receipt', requestedReceiptPath],
  ]) {
    if (capture.status === 'captured') continue;
    const failure = compareAtomicOutputFailure(capture, label, requestedPath, 'prepare');
    reportCompareFailure({
      json: options.json,
      stage: failure.stage,
      error: failure.message,
      code: failure.code,
      details: failure.details,
    });
    return;
  }
  const outputParent = outputCapture.snapshot.slot;
  const receiptParent = receiptCapture.snapshot.slot;
  if (outputParent.parentDevice !== receiptParent.parentDevice
    || outputParent.parentInode !== receiptParent.parentInode) {
    reportCompareFailure({
      json: options.json,
      stage: 'prepare',
      error: 'The compare receipt must be written beside the HTML artifact.',
      code: 'delta/receipt-directory',
      details: {
        artifactDirectory: outputParent.parentPath,
        receiptDirectory: receiptParent.parentPath,
        supportedFixes: ['choose a --receipt path in the same physical directory as output.html'],
      },
    });
    return;
  }
  outputPath = outputCapture.commitPath;
  receiptPath = receiptCapture.commitPath;
  outputDirectory = path.dirname(outputPath);

  let stagingDirectory;
  let stagingIdentity;
  try {
    const staging = createOwnedEmptyStagingDirectory(
      path.join(outputDirectory, '.archify-compare-'),
    );
    stagingDirectory = staging.directory;
    stagingIdentity = staging.identity;
  } catch (error) {
    reportCompareFailure({ json: options.json, stage: 'prepare', error: `Could not create compare candidate: ${error.message}`, code: 'delta/candidate-directory', details: { reason: error.message } });
    return;
  }

  const baseCandidate = path.join(stagingDirectory, 'base.html');
  const headCandidate = path.join(stagingDirectory, 'head.html');
  const rawBaseCandidate = path.join(stagingDirectory, 'base.raw.html');
  const rawHeadCandidate = path.join(stagingDirectory, 'head.raw.html');
  const rawBaseInput = path.join(stagingDirectory, 'base.snapshot.json');
  const rawHeadInput = path.join(stagingDirectory, 'head.snapshot.json');
  const canonicalBaseInput = path.join(stagingDirectory, 'base.architecture.json');
  const canonicalHeadInput = path.join(stagingDirectory, 'head.architecture.json');
  const htmlCandidate = path.join(stagingDirectory, path.basename(outputPath));
  const receiptCandidate = path.join(stagingDirectory, path.basename(receiptPath));
  let preserveRecoveryDirectory = false;
  const stagingOwnership = [];
  const captureCompareStagingFile = (filePath, content) => captureOwnedStagingFile(
    stagingOwnership,
    filePath,
    fileBindingRuntime,
    { subject: 'compare-staging-entry', content },
  );

  try {
    let baseResult;
    let headResult;
    for (const { side, snapshotPath, buffer } of [
      { side: 'base', snapshotPath: rawBaseInput, buffer: baseBuffer },
      { side: 'head', snapshotPath: rawHeadInput, buffer: headBuffer },
    ]) {
      try {
        fs.writeFileSync(snapshotPath, buffer, { flag: 'wx' });
        captureCompareStagingFile(snapshotPath, artifactIdentity(buffer));
      } catch (error) {
        const message = `Could not freeze ${side} compare snapshot: ${error.message}`;
        reportCompareFailure({
          json: options.json,
          stage: 'prepare',
          error: message,
          code: 'delta/freeze-snapshot',
          details: {
            side,
            ...(error?.code ? { systemCode: error.code } : {}),
            reason: error.message,
            supportedFixes: ['choose a writable compare output directory on the target filesystem'],
          },
        });
        return;
      }
    }
    try {
      renderValidatedArchitecture(
        rawBaseInput,
        rawBaseCandidate,
        qualityArgs.quality,
        repoArgs.repoRoot,
        captureCompareStagingFile,
      );
    } catch (error) {
      const diagnosticEntry = error.diagnostics?.[0];
      reportCompareFailure({
        json: options.json,
        stage: error.compareStage || 'validate',
        error: `Base snapshot failed validation: ${error.message}`,
        code: diagnosticEntry?.code || 'delta/base-validation',
        details: { side: 'base', ...(diagnosticEntry?.subject?.path ? { path: diagnosticEntry.subject.path } : {}), ...(diagnosticEntry?.evidence || {}), supportedFixes: diagnosticEntry?.supportedFixes || [] },
        status: error.compareStatus || 1,
      });
      return;
    }
    try {
      renderValidatedArchitecture(
        rawHeadInput,
        rawHeadCandidate,
        qualityArgs.quality,
        repoArgs.repoRoot,
        captureCompareStagingFile,
      );
    } catch (error) {
      const diagnosticEntry = error.diagnostics?.[0];
      reportCompareFailure({
        json: options.json,
        stage: error.compareStage || 'validate',
        error: `Head snapshot failed validation: ${error.message}`,
        code: diagnosticEntry?.code || 'delta/head-validation',
        details: { side: 'head', ...(diagnosticEntry?.subject?.path ? { path: diagnosticEntry.subject.path } : {}), ...(diagnosticEntry?.evidence || {}), supportedFixes: diagnosticEntry?.supportedFixes || [] },
        status: error.compareStatus || 1,
      });
      return;
    }

    // Validation must see the exact authored inputs. Only after both sides
    // pass do we canonicalize their collection order for deterministic SVG
    // geometry and stable artifact bytes.
    const canonicalBase = canonicalArchitecture(base);
    const canonicalHead = canonicalArchitecture(head);
    canonicalBase.meta.output = base.meta.output;
    canonicalHead.meta.output = head.meta.output;
    const canonicalBaseBytes = Buffer.from(JSON.stringify(canonicalBase));
    const canonicalHeadBytes = Buffer.from(JSON.stringify(canonicalHead));
    fs.writeFileSync(canonicalBaseInput, canonicalBaseBytes);
    captureCompareStagingFile(canonicalBaseInput, artifactIdentity(canonicalBaseBytes));
    fs.writeFileSync(canonicalHeadInput, canonicalHeadBytes);
    captureCompareStagingFile(canonicalHeadInput, artifactIdentity(canonicalHeadBytes));
    baseResult = renderValidatedArchitecture(
      canonicalBaseInput,
      baseCandidate,
      qualityArgs.quality,
      repoArgs.repoRoot,
      captureCompareStagingFile,
    );
    headResult = renderValidatedArchitecture(
      canonicalHeadInput,
      headCandidate,
      qualityArgs.quality,
      repoArgs.repoRoot,
      captureCompareStagingFile,
    );

    const semanticHash = (diagram) => createHash('sha256').update(canonicalArchitectureJson(diagram)).digest('hex');
    let compareIr;
    try {
      compareIr = compareArchitecture(base, head, {
        baseRawSha256: createHash('sha256').update(baseBuffer).digest('hex'),
        headRawSha256: createHash('sha256').update(headBuffer).digest('hex'),
        baseSemanticSha256: semanticHash(base),
        headSemanticSha256: semanticHash(head),
        baseBytes: baseBuffer.byteLength,
        headBytes: headBuffer.byteLength,
        baseVerified: Boolean(baseResult.sourceEvidence),
        headVerified: Boolean(headResult.sourceEvidence),
      });
    } catch (error) {
      if (!(error instanceof ArchitectureDeltaError)) throw error;
      reportCompareFailure({ json: options.json, stage: 'compare', error: error.message, code: error.code, details: error.details });
      return;
    }

    const baseSourceSvg = extractArchitectureSvg(baseResult.html);
    const headSourceSvg = extractArchitectureSvg(headResult.html);
    const baseSvg = annotateArchitectureSideSvg(baseSourceSvg, compareIr, 'base');
    const headSvg = annotateArchitectureSideSvg(headSourceSvg, compareIr, 'head');
    const deltaSvg = buildDeltaSvg(baseSourceSvg, headSourceSvg, compareIr);
    // Raw input hashes and byte counts belong in the sidecar receipt, not the
    // artifact. Keeping them out makes formatting-only input rewrites produce
    // the exact same canonical review HTML and artifact hash.
    const artifactIr = {
      ...compareIr,
      base: Object.fromEntries(Object.entries(compareIr.base).filter(([key]) => !['rawSha256', 'bytes'].includes(key))),
      head: Object.fromEntries(Object.entries(compareIr.head).filter(([key]) => !['rawSha256', 'bytes'].includes(key))),
    };
    const html = renderArchitectureDeltaHtml({
      receipt: artifactIr,
      baseSvg,
      deltaSvg,
      headSvg,
      baseHtml: baseResult.html,
      headHtml: headResult.html,
      artifactCss: extractArtifactCss(headResult.html),
    });
    const deltaValidation = validateArchitectureDeltaHtml(html, artifactIr);
    fs.writeFileSync(htmlCandidate, html);
    if (outputCapture.mode !== null) fs.chmodSync(htmlCandidate, outputCapture.mode);
    const artifact = fs.readFileSync(htmlCandidate);
    captureCompareStagingFile(htmlCandidate, artifactIdentity(artifact));
    const baseChecks = baseResult.checks.checks.filter((check) => check.ok).length;
    const headChecks = headResult.checks.checks.filter((check) => check.ok).length;
    const finalReceipt = {
      ...compareIr,
      artifact: artifactIdentity(artifact),
      validation: {
        checksPassed: baseChecks + headChecks + deltaValidation.checksPassed,
        checkCount: baseResult.checks.checks.length + headResult.checks.checks.length + deltaValidation.checkCount,
        baseComposition: baseResult.checks.composition.status,
        headComposition: headResult.checks.composition.status,
      },
    };
    const receiptBytes = Buffer.from(`${JSON.stringify(finalReceipt, null, 2)}\n`);
    fs.writeFileSync(receiptCandidate, receiptBytes);
    if (receiptCapture.mode !== null) fs.chmodSync(receiptCandidate, receiptCapture.mode);
    captureCompareStagingFile(receiptCandidate, artifactIdentity(receiptBytes));

    try {
      const currentOutput = resolveOutputPath({
        requestedOutput,
        defaultOutput: 'architecture-delta.html',
        inputPaths: [basePath, headPath],
        otherOutputPaths: [requestedReceiptPath],
      }).outputPath;
      resolveOutputPath({
        requestedOutput: options.receipt || compareReceiptPath(currentOutput),
        defaultOutput: compareReceiptPath(currentOutput),
        requiredExtension: '.json',
        inputPaths: [basePath, headPath],
        otherOutputPaths: [currentOutput],
      });
    } catch (error) {
      const outputDiagnostic = error.archifyDiagnostics?.[0];
      reportCompareFailure({
        json: options.json,
        stage: 'commit',
        error: error.message,
        code: outputDiagnostic?.code || 'output/path-resolution',
        details: {
          ...(outputDiagnostic?.subject || {}),
          ...(outputDiagnostic?.evidence || {}),
          supportedFixes: outputDiagnostic?.supportedFixes || ['restore safe output paths and retry'],
        },
      });
      return;
    }

    const committed = commitComparePair({
      htmlCandidate,
      htmlContent: finalReceipt.artifact,
      receiptCandidate,
      receiptContent: artifactIdentity(receiptBytes),
      outputCapture,
      receiptCapture,
      stagingDirectory,
      verifyAtomicOutput,
      fileBindingRuntime,
    });
    stagingOwnership.push(...committed.ownedBackupEntries);
    if (options.json) console.log(JSON.stringify(finalReceipt, null, 2));
    else {
      console.log(`compared architecture ${requestedOutputPath}`);
      console.log(`${finalReceipt.validation.checksPassed}/${finalReceipt.validation.checkCount} checks; completeness ${finalReceipt.completeness}; ${finalReceipt.proofLevel}; sha256 ${finalReceipt.artifact.sha256.slice(0, 12)}`);
      console.log(`receipt ${requestedReceiptPath}`);
    }
  } catch (error) {
    if (error instanceof ArchitectureDeltaError) {
      reportCompareFailure({ json: options.json, stage: 'artifact', error: error.message, code: error.code, details: error.details });
    } else if (error.compareStage === 'commit') {
      preserveRecoveryDirectory = Boolean(error.compareDetails?.recoveryFiles?.length);
      reportCompareFailure({
        json: options.json,
        stage: error.compareStage,
        error: error.message,
        code: error.compareCode,
        details: error.compareDetails,
      });
    } else {
      reportCompareFailure({ json: options.json, stage: 'internal', error: 'Architecture compare failed before commit.', code: 'delta/internal', details: { reason: error.message } });
    }
  } finally {
    try {
      if (!preserveRecoveryDirectory) {
        cleanupOwnedStagingDirectory(
          stagingDirectory,
          stagingIdentity,
          stagingOwnership,
          fileBindingRuntime,
        );
      } else {
        releaseOwnedStagingBindings(stagingOwnership, fileBindingRuntime);
      }
    } catch (error) {
      console.error(`Warning: could not remove compare staging directory: ${error.message}`);
    }
  }
}

function commandRender(args) {
  const qualityArgs = extractQualityArgs(args);
  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
  // render takes no options of its own once --quality and --repo-root are
  // stripped, so anything left starting with -- is a typo. Without this a
  // mistyped flag was taken as the output path: `render architecture spec.json
  // --json out.html` wrote a file literally named `--json` and never wrote
  // out.html, exiting 0. Every sibling subcommand already guards this.
  const unknown = repoArgs.rest.filter((arg) => arg.startsWith('--'));
  if (unknown.length) fail(`Unknown render option "${unknown[0]}".`);
  const [type, input, output] = repoArgs.rest;
  if (!type || !input || repoArgs.rest.length > 3) fail(usage());
  const result = runNode([rendererPath(type), input, ...(output ? [output] : [])], {
    env: rendererEnv(qualityArgs.quality, repoArgs.repoRoot),
  });
  if (result.status !== 0) exitFrom(result);
}

function reportArtifactFailure({ command, json, stage, type, input, output, error, diagnostics = [], status = 1, checker, receiptId, provenance, update }) {
  const receipt = {
    schemaVersion: 1,
    ok: false,
    command,
    ...(receiptId ? { receiptId } : {}),
    stage,
    type,
    input,
    ...(output === undefined ? {} : { output }),
    error,
    diagnostics,
    ...(provenance ? { provenance } : {}),
    ...(checker ? { checker } : {}),
    ...(update ? { update } : {}),
  };
  if (json) console.log(JSON.stringify(receipt, null, 2));
  else {
    console.error(formatDiagnostics(error, diagnostics));
    if (update?.noticeRequired) console.log(update.noticeText);
  }
  process.exitCode = status;
}

function writeDeliveryFailureReceipt(options) {
  const receiptId = options.receiptId || randomUUID();
  const recorded = recordDeliveryFailure({ ...options, receiptId });
  const ownershipOrLockError = recorded.ownershipError || recorded.lockError;
  if (ownershipOrLockError) {
    const failureWasRecorded = recorded.status && recorded.status !== 'unrecorded';
    const lockOrOwnershipFailure = Boolean(
      ownershipOrLockError.deliveryLockCode
      || ownershipOrLockError.deliveryOwnershipCode,
    );
    reportArtifactFailure({
      ...options,
      command: 'deliver',
      receiptId,
      status: 1,
      error: lockOrOwnershipFailure
        ? `Could not safely continue delivery for "${options.output}": ${ownershipOrLockError.message}`
        : options.error,
      ...(failureWasRecorded ? { provenance: recorded.status } : {}),
      diagnostics: lockOrOwnershipFailure
        ? [
          deliveryLockFailureDiagnostic(options.output, ownershipOrLockError),
          ...(options.diagnostics || []),
          ...(recorded.diagnostic ? [recorded.diagnostic] : []),
        ]
        : [
          ...(options.diagnostics || []),
          deliveryLockFailureDiagnostic(options.output, ownershipOrLockError),
          ...(recorded.diagnostic ? [recorded.diagnostic] : []),
        ],
    });
    return recorded;
  }
  const recoveryDiagnosticFirst = Boolean(recorded.journalRecovery || recorded.provenanceRecovery);
  const diagnostics = recoveryDiagnosticFirst
    ? [
      ...(recorded.diagnostic ? [recorded.diagnostic] : []),
      ...(options.diagnostics || []),
    ]
    : [
      ...(options.diagnostics || []),
      ...(recorded.diagnostic ? [recorded.diagnostic] : []),
    ];
  reportArtifactFailure({
    ...options,
    command: 'deliver',
    receiptId,
    provenance: recorded.status,
    diagnostics,
  });
  return recorded;
}

function reportArtifactArgumentFailure(command, error) {
  const details = error.archifyArgument || {};
  reportArtifactFailure({
    command,
    json: true,
    stage: 'arguments',
    error: error.message,
    diagnostics: [diagnostic({
      code: details.code || 'cli/invalid-arguments',
      message: error.message,
      subject: { command, ...(details.subject || {}) },
      evidence: details.evidence || {},
      supportedFixes: details.supportedFixes || ['correct the command arguments and retry'],
    })],
    status: 2,
  });
}

function sourceEvidenceFromArtifact(artifact) {
  const html = artifact.toString('utf8');
  const match = html.match(/<script id="archify-source-evidence-data" type="application\/json">([\s\S]*?)<\/script>/);
  if (!match) return null;
  const evidence = JSON.parse(match[1]);
  if (evidence?.verified !== true || !evidence.repository?.url || !evidence.repository?.revision || !Number.isInteger(evidence.referenceCount)) {
    throw new Error('Rendered source evidence receipt is incomplete.');
  }
  return evidence;
}

function engineeringProfileFromArtifact(artifact) {
  const match = artifact.toString('utf8').match(/<svg[^>]*\sdata-engineering-profile="([^"]+)"/);
  return match ? match[1] : null;
}

async function commandDeliver(args) {
  await loadSidecarPathRuntime();
  const qualityArgs = extractQualityArgs(args);
  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
  const writingArgs = extractExplainerWritingArgs(repoArgs.rest);
  repoArgs.rest = writingArgs.rest;
  const json = repoArgs.rest.includes('--json');
  const open = repoArgs.rest.includes('--open');
  const knownOptions = new Set(['--json', '--open']);
  const unknown = repoArgs.rest.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
  if (unknown.length) rejectCliArgument(`Unknown deliver option "${unknown[0]}".`, {
    code: 'cli/unknown-option',
    subject: { option: unknown[0] },
    supportedFixes: ['remove the unknown option and retry'],
  });
  const positional = repoArgs.rest.filter((arg) => !knownOptions.has(arg));
  const [type, input, requestedOutput] = positional;
  if (!type || !input || positional.length > 3) rejectCliArgument(usage(), {
    code: 'cli/usage',
    supportedFixes: ['use: archify deliver <type> <input.json> [output.html] [options]'],
  });
  const renderer = rendererPath(type);
  const {
    canonicalFuturePath,
    pathsAlias,
    resolveOutputPath,
    validateAuthoredOutputPath,
  } = await import('../renderers/shared/output-path.mjs');
  const {
    captureAtomicOutput,
    verifyAtomicOutput,
    backupPublicRegularFileBinding,
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    verifyRegularFileBinding,
    releaseRegularFileBinding,
  } = await import('../renderers/shared/atomic-output.mjs');
  ({ sidecarNamespaceComponentKey: sidecarNamespaceComponentKeyRuntime }
    = await import('../renderers/shared/path-semantics.mjs'));
  const fileBindingRuntime = {
    backupPublicRegularFileBinding,
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    verifyRegularFileBinding,
    releaseRegularFileBinding,
  };
  const receiptId = randomUUID();
  let updateCheck;
  let deliveryOwnership;
  let recoveryRequired = false;
  let stagingDirectory;
  let stagingIdentity;
  let deliveryAliasOutput;
  const reportDeliveryFailure = async (options) => {
    const ownership = deliveryOwnership;
    deliveryOwnership = undefined;
    const recorded = writeDeliveryFailureReceipt({
      ...options,
      ...(updateCheck ? { update: await updateCheck } : {}),
      pathsAlias,
      receiptId,
      ownership,
      releaseOwnership: Boolean(ownership),
      recoveryDirectory: stagingDirectory,
      legacyOutputPaths: deliveryAliasOutput ? [deliveryAliasOutput] : [],
      captureAtomicOutput,
      verifyAtomicOutput,
      fileBindingRuntime,
    });
    if (ownership && (recorded?.ownershipError || recorded?.lockError)?.deliveryOwnershipCode === 'delivery/ownership-lost') {
      recoveryRequired = true;
    }
  };
  const reportPreparedArtifactFailure = async (options) => reportArtifactFailure({
    ...options,
    ...(updateCheck ? { update: await updateCheck } : {}),
  });
  const inputPath = path.resolve(input);
  let specification;
  let diagram;
  let explainerBundle;
  try {
    specification = fs.readFileSync(inputPath);
    if (type === 'explainer') {
      explainerBundle = await prepareExplainerInput(specification, inputPath, { repoRoot: repoArgs.repoRoot, quality: qualityArgs.quality, writingMode: writingArgs.writingMode });
      diagram = explainerBundle.document;
    } else diagram = JSON.parse(specification.toString('utf8'));
  } catch (error) {
    const repair = inputDiagnostic(error, inputPath);
    await reportDeliveryFailure({
      json,
      stage: 'input',
      type,
      input: inputPath,
      output: path.resolve(requestedOutput || `${type}.html`),
      error: `Could not read delivery input "${inputPath}": ${error.message}`,
      diagnostics: error.archifyDiagnostics || [repair],
    });
    return;
  }

  const authoredOutput = diagram?.meta?.output;
  let outputPath;
  let provenancePath;
  let preparedDeliveryTargets;
  try {
    if (type !== 'explainer' || authoredOutput !== undefined) validateAuthoredOutputPath(authoredOutput);
    ({ outputPath } = resolveOutputPath({
      requestedOutput,
      authoredOutput,
      defaultOutput: `${type}.html`,
      inputPaths: [inputPath],
    }));
    deliveryAliasOutput = outputPath;
    // Redelivery through a case, normalization, 8.3, or file-symlink alias
    // must replace the existing physical artifact without changing its stored
    // spelling. That keeps its realpath-derived sidecars discoverable.
    outputPath = canonicalFuturePath(outputPath);
  } catch (error) {
    const attemptedOutput = path.resolve(
      requestedOutput
      || (typeof authoredOutput === 'string' && authoredOutput)
      || `${type}.html`,
    );
    const failure = {
      json,
      stage: 'prepare',
      type,
      input: inputPath,
      output: attemptedOutput,
      error: error.message,
      diagnostics: error.archifyDiagnostics || [diagnostic({
        code: 'output/path-resolution',
        message: error.message,
        subject: { output: attemptedOutput },
        evidence: { ...(error?.code ? { systemCode: error.code } : {}) },
        supportedFixes: ['choose a safe output path and retry'],
      })],
    };
    if (outputPath) {
      await reportDeliveryFailure(failure);
    } else {
      await reportPreparedArtifactFailure({ ...failure, command: 'deliver', receiptId });
    }
    return;
  }
  let outputDirectory = path.dirname(outputPath);
  try {
    fs.mkdirSync(outputDirectory, { recursive: true });
  } catch (error) {
    const message = `Could not create delivery directory "${outputDirectory}": ${error.message}`;
    await reportDeliveryFailure({
      json,
      stage: 'prepare',
      type,
      input: inputPath,
      output: outputPath,
      error: message,
      diagnostics: [diagnostic({
        code: 'delivery/prepare-directory',
        message,
        subject: { outputDirectory },
        evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
        supportedFixes: ['choose a writable output directory'],
      })],
    });
    return;
  }

  // Name semantics such as NTFS per-directory case sensitivity cannot be
  // projected through an unmaterialized directory. Creating the requested
  // physical parent is directory preparation, not artifact/sidecar
  // publication; all input, portable-path and native-resolution contracts
  // above have already passed. Only now may sidecar naming probe the actual
  // directory. A later target snapshot still rejects any authored alias that
  // was retargeted across this boundary.
  try {
    const defaultProvenancePath = deliveryProvenancePath(outputPath);
    ({ outputPath: provenancePath } = resolveOutputPath({
      requestedOutput: defaultProvenancePath,
      defaultOutput: defaultProvenancePath,
      requiredExtension: '.json',
      inputPaths: [inputPath],
      inputDescription: 'the delivery input',
      otherOutputPaths: [outputPath],
    }));
  } catch (error) {
    const attemptedOutput = path.resolve(requestedOutput || authoredOutput || `${type}.html`);
    const failure = {
      json,
      stage: 'prepare',
      type,
      input: inputPath,
      output: attemptedOutput,
      error: error.message,
      diagnostics: error.archifyDiagnostics || [diagnostic({
        code: 'output/path-resolution',
        message: error.message,
        subject: { output: attemptedOutput },
        evidence: { ...(error?.code ? { systemCode: error.code } : {}) },
        supportedFixes: ['choose a safe output path and retry'],
      })],
    };
    if (error?.code === 'ARCHIFY_SIDECAR_NAMESPACE_INDETERMINATE') {
      await reportPreparedArtifactFailure({ ...failure, command: 'deliver', receiptId });
    } else {
      await reportDeliveryFailure(failure);
    }
    return;
  }

  try {
    const plannedOutputPath = outputPath;
    const artifactCapture = {
      requestedPath: deliveryAliasOutput || outputPath,
      ...captureAtomicOutput(deliveryAliasOutput || outputPath),
    };
    if (artifactCapture.status !== 'captured') {
      throw deliveryTargetStateError(artifactCapture.requestedPath, 'HTML artifact', artifactCapture);
    }
    if (!pathsAlias(artifactCapture.commitPath, plannedOutputPath)) {
      throw deliveryTargetStateError(artifactCapture.requestedPath, 'HTML artifact', {
        status: 'different',
        reason: {
          code: 'write-slot-changed-before-snapshot',
          plannedCommitPath: plannedOutputPath,
          currentCommitPath: artifactCapture.commitPath,
        },
      });
    }
    const requestedProvenancePath = deliveryProvenancePath(artifactCapture.commitPath);
    const provenanceCapture = {
      requestedPath: requestedProvenancePath,
      ...captureAtomicOutput(requestedProvenancePath, {
        requestedEntryPolicy: 'regular-or-absent',
      }),
    };
    if (provenanceCapture.status !== 'captured') {
      throw deliveryTargetStateError(requestedProvenancePath, 'delivery provenance', provenanceCapture);
    }
    preparedDeliveryTargets = { artifact: artifactCapture, provenance: provenanceCapture };
    outputPath = artifactCapture.commitPath;
    provenancePath = provenanceCapture.commitPath;
    outputDirectory = path.dirname(outputPath);
    const { startDeliveryUpdateCheck } = await import('./delivery-update.mjs');
    updateCheck = startDeliveryUpdateCheck();
  } catch (error) {
    await reportPreparedArtifactFailure({
      command: 'deliver', json, stage: 'prepare', type, input: inputPath, output: outputPath, receiptId,
      error: error.message,
      diagnostics: error.archifyDiagnostics || [diagnostic({
        code: 'output/target-indeterminate',
        message: error.message,
        subject: { output: outputPath },
        evidence: { ...(error?.code ? { systemCode: error.code } : {}) },
        supportedFixes: ['retry only after the output path and its parent directories stop changing'],
      })],
    });
    return;
  }

  // Keep the candidate beside the target so the final rename is one
  // same-filesystem commit. A render or artifact-check failure never touches
  // an existing trusted output.
  try {
    const staging = createOwnedEmptyStagingDirectory(
      path.join(outputDirectory, '.archify-delivery-'),
    );
    stagingDirectory = staging.directory;
    stagingIdentity = staging.identity;
  } catch (error) {
    const message = `Could not create a delivery candidate beside "${outputPath}": ${error.message}`;
    await reportDeliveryFailure({
      json,
      stage: 'prepare',
      type,
      input: inputPath,
      output: outputPath,
      error: message,
      diagnostics: [diagnostic({
        code: 'delivery/prepare-candidate',
        message,
        subject: { output: outputPath },
        evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
        supportedFixes: ['choose a writable output directory on the target filesystem'],
      })],
    });
    return;
  }
  const candidatePath = path.join(stagingDirectory, path.basename(outputPath));
  const specificationSnapshotPath = path.join(stagingDirectory, 'specification.snapshot.json');
  const provenanceCandidatePath = path.join(stagingDirectory, 'delivery-provenance.json');
  let commitRecoveryBackups = [];
  const stagingOwnership = [];
  const captureDeliveryStagingFile = (filePath, content) => captureOwnedStagingFile(
    stagingOwnership,
    filePath,
    fileBindingRuntime,
    { subject: 'delivery-staging-entry', content },
  );

  try {
    try {
      deliveryOwnership = acquireDeliveryLock(
        outputPath,
        receiptId,
        inputPath,
        pathsAlias,
        (lockError, initializingOwnership) => recordDeliveryFailure({
          output: outputPath,
          stage: 'prepare',
          input: inputPath,
          error: `Could not start delivery for "${outputPath}": ${lockError.message}`,
          receiptId,
          pathsAlias,
          ownership: initializingOwnership,
          captureAtomicOutput,
          verifyAtomicOutput,
          fileBindingRuntime,
        }),
        deliveryAliasOutput ? [deliveryAliasOutput] : [],
        fileBindingRuntime,
      );
    } catch (error) {
      const message = `Could not start delivery for "${outputPath}": ${error.message}`;
      const recorded = error.deliveryFailureRecord;
      await reportPreparedArtifactFailure({
        command: 'deliver', json, stage: 'prepare', type, input: inputPath, output: outputPath, receiptId,
        error: message,
        ...(recorded ? { provenance: recorded.status } : {}),
        diagnostics: error.deliveryJournalRecovery?.recoveryRequired
          ? [deliveryJournalRecoveryDiagnostic(outputPath, error)]
          : error.deliveryProvenanceRecovery?.recoveryRequired
            ? [
              ...(recorded?.diagnostic ? [recorded.diagnostic] : []),
              deliveryLockFailureDiagnostic(outputPath, error),
            ]
            : [
              deliveryLockFailureDiagnostic(outputPath, error),
              ...(recorded?.diagnostic ? [recorded.diagnostic] : []),
            ],
      });
      return;
    }

    try {
      const state = deliveryOwnershipStates.get(deliveryOwnership);
      const targets = captureDeliveryTargetState({
        state,
        requestedOutput: deliveryAliasOutput || outputPath,
        pathsAlias,
        captureAtomicOutput,
        verifyAtomicOutput,
        preparedTargets: preparedDeliveryTargets,
      });
      outputPath = targets.artifact.commitPath;
      provenancePath = targets.provenance.commitPath;
    } catch (error) {
      let releaseError;
      try {
        releaseDeliveryOwnership(deliveryOwnership);
      } catch (cause) {
        releaseError = cause;
      }
      deliveryOwnership = undefined;
      await reportPreparedArtifactFailure({
        command: 'deliver', json, stage: 'prepare', type, input: inputPath, output: outputPath, receiptId,
        error: error.message,
        diagnostics: [
          ...(releaseError ? [deliveryLockFailureDiagnostic(outputPath, releaseError)] : []),
          ...(error.archifyDiagnostics || [diagnostic({
            code: 'output/target-indeterminate',
            message: error.message,
            subject: { output: outputPath },
            evidence: { ...(error?.code ? { systemCode: error.code } : {}) },
          })]),
        ],
      });
      return;
    }

    try {
      beginDeliveryAttempt({
        ownership: deliveryOwnership,
        input: inputPath,
        pathsAlias,
        fileBindingRuntime,
      });
    } catch (error) {
      if (error.deliveryJournalRecovery?.recoveryRequired) {
        // The lock is the remaining fail-closed barrier. Do not write failure
        // provenance or release it after journal rollback itself became unsafe.
        deliveryOwnership = undefined;
        await reportPreparedArtifactFailure({
          command: 'deliver', json, stage: 'prepare', type, input: inputPath, output: outputPath, receiptId,
          error: `Could not persist the delivery attempt before rendering: ${error.message}`,
          diagnostics: [deliveryJournalRecoveryDiagnostic(outputPath, error)],
        });
        return;
      }
      if (error.deliveryOwnershipCode === 'delivery/ownership-lost') {
        deliveryOwnership = undefined;
        recoveryRequired = true;
        error.deliveryCommitDetails = {
          recoveryRequired: true,
          recoveryDirectory: stagingDirectory,
          recoverableBackups: [],
        };
        await reportPreparedArtifactFailure({
          command: 'deliver', json, stage: 'prepare', type, input: inputPath, output: outputPath, receiptId,
          error: `Could not persist the delivery attempt before rendering: ${error.message}`,
          diagnostics: [deliveryLockFailureDiagnostic(outputPath, error)],
        });
        return;
      }
      await reportDeliveryFailure({
        json, stage: 'prepare', type, input: inputPath, output: outputPath,
        error: 'Could not persist the delivery attempt before rendering.',
        diagnostics: [diagnostic({
          code: 'delivery/journal-write', message: 'Could not persist the delivery attempt before rendering.',
          subject: {
            output: outputPath,
            journal: deliveryOwnershipStates.get(deliveryOwnership)?.pendingPath
              || deliveryPendingPath(outputPath),
          },
          evidence: { reason: error.message },
          supportedFixes: ['choose a writable output directory with a journal path distinct from the input'],
        })],
      });
      return;
    }

    try {
      fs.writeFileSync(specificationSnapshotPath, specification, { flag: 'wx' });
      captureDeliveryStagingFile(
        specificationSnapshotPath,
        artifactIdentity(Buffer.from(specification)),
      );
    } catch (error) {
      const message = `Could not freeze the delivery specification: ${error.message}`;
      await reportDeliveryFailure({
        json,
        stage: 'prepare',
        type,
        input: inputPath,
        output: outputPath,
        error: message,
        diagnostics: [diagnostic({
          code: 'delivery/freeze-specification',
          message,
          subject: { input: inputPath },
          evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
          supportedFixes: ['choose a writable output directory on the target filesystem'],
        })],
      });
      return;
    }

    let preparedBundlePath;
    if (explainerBundle) {
      try {
        const { writePreparedBundle } = await import('../explainer/prepare.mjs');
        preparedBundlePath = writePreparedBundle(stagingDirectory, explainerBundle);
        captureDeliveryStagingFile(preparedBundlePath, artifactIdentity(fs.readFileSync(preparedBundlePath)));
      } catch (error) {
        await reportDeliveryFailure({json,stage:'prepare',type,input:inputPath,output:outputPath,error:error.message,
          diagnostics:error.archifyDiagnostics || [diagnostic({code:'explainer/freeze-resource-bundle',message:error.message,subject:{input:inputPath,line:1,component:'document'},evidence:{reason:error.code || 'bundle-write-failed',example:'Use a writable delivery directory and a document within the resource budget.'},supportedFixes:['Use a writable delivery directory and a document within the resource budget.']})]});
        return;
      }
    }
    const render = runNode([renderer, specificationSnapshotPath, candidatePath], {
      stdio: 'pipe',
      // The page is rendered in staging; paths inside it are written relative to where it is delivered.
      env: { ...rendererEnv(qualityArgs.quality, repoArgs.repoRoot, true), ...(preparedBundlePath ? { ARCHIFY_EXPLAINER_PREPARED: preparedBundlePath, ARCHIFY_EXPLAINER_SNAPSHOT_INPUT: inputPath, ARCHIFY_EXPLAINER_PAGE_DIR: path.dirname(outputPath) } : {}) },
    });
    if (render.status !== 0) {
      const failure = rendererFailure(render);
      await reportDeliveryFailure({
        json,
        stage: 'render',
        type,
        input: inputPath,
        output: outputPath,
        error: failure.error,
        diagnostics: failure.diagnostics,
        status: render.status ?? 1,
      });
      return;
    }
    if (render.stderr) process.stderr.write(render.stderr);
    const localeWarnings = [...await specificationLocaleDiagnostics(type, specification), ...(explainerBundle?.diagnostics.filter(entry => entry.severity === 'warning') || [])];
    for (const warning of localeWarnings) process.stderr.write(`archify: ${warning.message}\n`);
    try {
      const renderedCandidate = fs.readFileSync(candidatePath);
      if (preparedDeliveryTargets.artifact.mode !== null) {
        fs.chmodSync(candidatePath, preparedDeliveryTargets.artifact.mode);
      }
      captureDeliveryStagingFile(candidatePath, artifactIdentity(renderedCandidate));
    } catch {
      // The commit path performs the authoritative candidate classification.
      // Leave an unbound entry untouched during private-directory cleanup.
    }

    const checkMaxBuffer = artifactCheckMaxBuffer();
    const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), candidatePath], {
      stdio: 'pipe',
      maxBuffer: checkMaxBuffer,
    });
    if (check.status !== 0) {
      if (check.stderr) process.stderr.write(check.stderr);
      const outputLimit = checkerOutputLimitDiagnostics(check, checkMaxBuffer);
      if (outputLimit) {
        await reportDeliveryFailure({
          json,
          stage: 'check',
          type,
          input: inputPath,
          output: outputPath,
          error: `The artifact checker exceeded its ${checkMaxBuffer} byte output buffer and was terminated before reporting a verdict; the previous artifact was preserved.`,
          diagnostics: outputLimit,
          status: check.status ?? 1,
        });
        return;
      }
      let checker;
      try {
        checker = JSON.parse(check.stdout);
        checker.file = outputPath;
      } catch {
        checker = { ok: false, file: outputPath, diagnostic: check.stdout.trim() };
      }
      await reportDeliveryFailure({
        json,
        stage: 'check',
        type,
        input: inputPath,
        output: outputPath,
        error: 'Final artifact check failed; the previous artifact was preserved.',
        diagnostics: checkerDiagnostics(checker),
        status: check.status ?? 1,
        checker,
      });
      return;
    }

    let result;
    try {
      result = JSON.parse(check.stdout);
    } catch (error) {
      const message = `Could not parse the successful artifact-check receipt: ${error.message}`;
      await reportDeliveryFailure({
        json,
        stage: 'receipt',
        type,
        input: inputPath,
        output: outputPath,
        error: message,
        diagnostics: [diagnostic({
          code: 'delivery/receipt-invalid',
          message,
          subject: { output: outputPath },
          evidence: { reason: error.message },
        })],
      });
      return;
    }
    let artifact;
    try {
      artifact = fs.readFileSync(candidatePath);
    } catch (error) {
      const message = `Could not read the verified delivery candidate: ${error.message}`;
      await reportDeliveryFailure({
        json,
        stage: 'receipt',
        type,
        input: inputPath,
        output: outputPath,
        error: message,
        diagnostics: [diagnostic({
          code: 'delivery/candidate-unreadable',
          message,
          subject: { output: outputPath },
          evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
        })],
      });
      return;
    }
    let sourceEvidence;
    try {
      sourceEvidence = sourceEvidenceFromArtifact(artifact);
    } catch (error) {
      const message = `Could not read the repository evidence receipt: ${error.message}`;
      await reportDeliveryFailure({
        json,
        stage: 'receipt',
        type,
        input: inputPath,
        output: outputPath,
        error: message,
        diagnostics: [diagnostic({
          code: 'delivery/evidence-receipt-invalid',
          message,
          subject: { output: outputPath },
          evidence: { reason: error.message },
        })],
      });
      return;
    }
    const engineeringProfile = engineeringProfileFromArtifact(artifact);
    const receipt = {
      schemaVersion: 1,
      receiptId,
      ok: true,
      command: 'deliver',
      type,
      input: inputPath,
      output: outputPath,
      ...(explainerBundle ? { explainer: { preparedSha256: explainerBundle.digest, dependencies: explainerBundle.dependencies.map(({contentBase64, ...entry}) => entry) } } : {}),
      specification: {
        sha256: createHash('sha256').update(specification).digest('hex'),
        bytes: specification.byteLength,
      },
      artifact: {
        sha256: createHash('sha256').update(artifact).digest('hex'),
        bytes: artifact.byteLength,
      },
      validation: {
        checksPassed: result.checks.filter((checkItem) => checkItem.ok).length,
        checkCount: result.checks.length,
        compositionProfile: result.composition.profile,
        compositionStatus: result.composition.status,
        ...(engineeringProfile ? { engineeringProfile } : {}),
        errors: result.composition.summary.errors,
        warnings: result.composition.summary.warnings,
        ...(result.composition.summary.warnings ? {
          compositionIssues: result.composition.issues.filter((issue) => issue.severity === 'warning'),
        } : {}),
      },
      ...(sourceEvidence ? {
        evidence: {
          verified: true,
          repository: sourceEvidence.repository.url,
          revision: sourceEvidence.repository.revision,
          references: sourceEvidence.referenceCount,
          ...(sourceEvidence.repository.linkMode ? { linkMode: sourceEvidence.repository.linkMode } : {}),
        },
      } : {}),
      ...(localeWarnings.length ? { diagnostics: localeWarnings } : {}),
    };

    const provenanceBytes = Buffer.from(`${JSON.stringify(deliverySuccessProvenance(receipt), null, 2)}\n`);
    try {
      fs.writeFileSync(provenanceCandidatePath, provenanceBytes, { flag: 'wx' });
      if (preparedDeliveryTargets.provenance.mode !== null) {
        fs.chmodSync(provenanceCandidatePath, preparedDeliveryTargets.provenance.mode);
      }
      try {
        captureDeliveryStagingFile(
          provenanceCandidatePath,
          artifactIdentity(provenanceBytes),
        );
      } catch {
        // commitDeliveryPair classifies this path against the expected bytes;
        // cleanup must not claim a candidate that could not be bound here.
      }
    } catch (error) {
      await reportDeliveryFailure({
        json,
        stage: 'commit',
        type,
        input: inputPath,
        output: outputPath,
        error: `Could not prepare delivery provenance for "${outputPath}": ${error.message}`,
        diagnostics: [diagnostic({
          code: 'delivery/provenance-prepare',
          message: 'Could not prepare the artifact-bound delivery provenance.',
          subject: { output: outputPath },
          evidence: { reason: error.message },
          supportedFixes: ['choose a writable output directory and rerun deliver'],
        })],
      });
      return;
    }

    try {
      const currentOutputPath = canonicalFuturePath(resolveOutputPath({
        requestedOutput,
        authoredOutput,
        defaultOutput: `${type}.html`,
        inputPaths: [inputPath],
        otherOutputPaths: [provenancePath],
      }).outputPath);
      resolveOutputPath({
        requestedOutput: deliveryProvenancePath(currentOutputPath),
        defaultOutput: deliveryProvenancePath(currentOutputPath),
        requiredExtension: '.json',
        inputPaths: [inputPath],
        inputDescription: 'the delivery input',
        otherOutputPaths: [currentOutputPath],
      });
    } catch (error) {
      await reportDeliveryFailure({
        json,
        stage: 'commit',
        type,
        input: inputPath,
        output: outputPath,
        error: error.message,
        diagnostics: error.archifyDiagnostics || [diagnostic({
          code: 'output/path-resolution',
          message: error.message,
          subject: { output: outputPath },
          evidence: { ...(error?.code ? { systemCode: error.code } : {}) },
          supportedFixes: ['restore a safe output path and retry'],
        })],
      });
      return;
    }

    try {
      if (explainerBundle) {
        const { assertPreparedDependencies } = await import('../explainer/prepare.mjs');
        assertPreparedDependencies(explainerBundle);
      }
      const committed = commitDeliveryPair({
        htmlCandidate: candidatePath,
        htmlContent: receipt.artifact,
        provenanceCandidate: provenanceCandidatePath,
        provenanceContent: artifactIdentity(provenanceBytes),
        stagingDirectory,
        ownership: deliveryOwnership,
        verifyAtomicOutput,
        fileBindingRuntime,
      });
      commitRecoveryBackups = committed.recoverableBackups;
      stagingOwnership.push(...committed.ownedBackupEntries);
    } catch (error) {
      if (error.deliveryOwnershipCode === 'delivery/ownership-lost' && !error.deliveryCommitDetails) {
        error.deliveryCommitDetails = {
          recoveryRequired: true,
          recoveryDirectory: stagingDirectory,
          recoverableBackups: [],
        };
      }
      recoveryRequired = error.deliveryCommitDetails?.recoveryRequired === true;
      const message = `Could not commit verified delivery "${outputPath}": ${error.message}`;
      if (recoveryRequired) {
        // The owned lock and pending journal are the remaining fail-closed
        // barrier around retained backups and any claimant we did not create.
        // Do not write failure provenance or release ownership here.
        deliveryOwnership = undefined;
        await reportPreparedArtifactFailure({
          command: 'deliver', json, stage: 'commit', type, input: inputPath, output: outputPath, receiptId,
          error: message,
          diagnostics: [
            ...(error.deliveryOwnershipCode === 'delivery/ownership-lost'
              ? [deliveryLockFailureDiagnostic(outputPath, error)]
              : []),
            ...(error.archifyDiagnostics || []),
            deliveryCommitRecoveryDiagnostic(outputPath, error),
          ],
        });
        return;
      }
      if (error.deliveryTargetState) {
        let releaseError;
        try {
          releaseDeliveryOwnership(deliveryOwnership);
        } catch (cause) {
          releaseError = cause;
        }
        deliveryOwnership = undefined;
        await reportPreparedArtifactFailure({
          command: 'deliver', json, stage: 'commit', type, input: inputPath, output: outputPath, receiptId,
          error: message,
          diagnostics: [
            ...(releaseError ? [deliveryLockFailureDiagnostic(outputPath, releaseError)] : []),
            ...(error.archifyDiagnostics || []),
          ],
        });
        return;
      }
      if (error.deliveryOwnershipCode === 'delivery/ownership-lost') {
        deliveryOwnership = undefined;
        await reportPreparedArtifactFailure({
          command: 'deliver', json, stage: 'commit', type, input: inputPath, output: outputPath, receiptId,
          error: message,
          diagnostics: [deliveryLockFailureDiagnostic(outputPath, error)],
        });
        return;
      }
      await reportDeliveryFailure({
        json,
        stage: 'commit',
        type,
        input: inputPath,
        output: outputPath,
        error: message,
        diagnostics: error.archifyDiagnostics || [diagnostic({
          code: 'delivery/commit',
          message,
          subject: { output: outputPath },
          evidence: {
            ...(error?.code ? { systemCode: error.code } : {}),
            reason: error.message,
            ...(error.deliveryCommitDetails || {}),
          },
          supportedFixes: ['choose replaceable regular-file artifact and provenance targets on the same writable filesystem'],
        })],
      });
      return;
    }

    try {
      releaseDeliveryOwnership(deliveryOwnership);
      deliveryOwnership = undefined;
    } catch (error) {
      deliveryOwnership = undefined;
      if (error.deliveryOwnershipCode === 'delivery/ownership-lost') {
        recoveryRequired = true;
        error.deliveryCommitDetails = {
          recoveryRequired: true,
          recoveryDirectory: stagingDirectory,
          recoverableBackups: commitRecoveryBackups,
        };
      }
      const message = `Delivery committed, but its lock could not be released for "${outputPath}": ${error.message}`;
      await reportPreparedArtifactFailure({
        command: 'deliver', json, stage: 'release', type, input: inputPath, output: outputPath, receiptId,
        error: message,
        diagnostics: [deliveryLockFailureDiagnostic(outputPath, error)],
      });
      return;
    }

    if (open) {
      try {
        const { openArtifact } = await import('./open-artifact.mjs');
        receipt.open = openArtifact(outputPath);
      } catch {
        receipt.open = {
          requested: true,
          status: 'unsupported',
          target: outputPath,
          method: null,
        };
      }
      if (receipt.open.status !== 'opened') {
        console.error(`Could not open the verified artifact (${receipt.open.status}). ${receipt.open.failure?.reason || 'Open it manually.'} Target: ${outputPath}`);
      }
    }

    receipt.update = await updateCheck;

    if (json) {
      console.log(JSON.stringify(receipt, null, 2));
    } else {
      console.log(`delivered ${type} ${outputPath}`);
      const engineering = receipt.validation.engineeringProfile
        ? `; engineering ${receipt.validation.engineeringProfile}: pass`
        : '';
      console.log(`${receipt.validation.checksPassed}/${receipt.validation.checkCount} artifact checks; composition ${receipt.validation.compositionProfile}: ${receipt.validation.compositionStatus}${engineering}; sha256 ${receipt.artifact.sha256.slice(0, 12)}`);
      if (receipt.open?.status === 'opened') console.log(`opened ${outputPath}`);
      if (receipt.update.noticeRequired) console.log(receipt.update.noticeText);
    }
  } finally {
    if (deliveryOwnership) {
      try {
        releaseDeliveryOwnership(deliveryOwnership, { allowInitializing: true });
      } catch (error) {
        if (error.deliveryOwnershipCode === 'delivery/ownership-lost') {
          recoveryRequired = true;
          error.deliveryCommitDetails = {
            ...(error.deliveryCommitDetails || {}),
            recoveryRequired: true,
            recoveryDirectory: stagingDirectory,
            recoverableBackups: commitRecoveryBackups,
          };
        }
        console.error(formatDiagnostics(
          `Delivery cleanup could not release its lock for "${outputPath}".`,
          [deliveryLockFailureDiagnostic(outputPath, error)],
        ));
        process.exitCode = 1;
      }
    }
    if (recoveryRequired) {
      releaseOwnedStagingBindings(stagingOwnership, fileBindingRuntime);
      console.error(`Recovery required: delivery backups were retained at "${stagingDirectory}".`);
    } else {
      try {
        cleanupOwnedStagingDirectory(
          stagingDirectory,
          stagingIdentity,
          stagingOwnership,
          fileBindingRuntime,
        );
      } catch (error) {
        console.error(`Warning: could not remove delivery staging directory "${stagingDirectory}": ${error.message}`);
      }
    }
  }
}

async function commandPatch(rawArgs) {
  const qualityArgs = extractQualityArgs(rawArgs);
  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
  const writingArgs = extractExplainerWritingArgs(repoArgs.rest);
  repoArgs.rest = writingArgs.rest;
  const json = repoArgs.rest.includes('--json');
  const positional = repoArgs.rest.filter(arg => arg !== '--json');
  const [type, artifact, panelId, replacement, output] = positional;
  if (type !== 'explainer' || !artifact || !panelId || !replacement || !output || positional.length !== 5 || positional.some(arg => arg.startsWith('--'))) {
    rejectCliArgument('Use: archify patch explainer <artifact.html> <panel-id> <replacement-file> <output.html> [--json]', {
      code:'cli/usage',supportedFixes:['Provide an explainer artifact, stable panel id, replacement file and output HTML path.'],
    });
  }
  let temporary;
  try {
    const checked = runNode([path.join(skillRoot,'scripts/check-render-output.mjs'),path.resolve(artifact)], {stdio:'pipe',maxBuffer:artifactCheckMaxBuffer()});
    if(checked.status !== 0) {
      let receipt; try { receipt=JSON.parse(checked.stdout); } catch {}
      throw Object.assign(new Error('The original explainer artifact failed validation.'), {archifyDiagnostics:receipt?.diagnostics || [{code:'explainer/patch-artifact',severity:'error',message:'The original explainer artifact failed validation.',subject:{input:path.resolve(artifact),line:1,component:'document'},evidence:{reason:'invalid-original-artifact',example:'Use an unchanged formal explainer artifact.'},supportedFixes:['Rebuild the original artifact.']}]});
    }
    const originalCheck=JSON.parse(checked.stdout);
    const { preparePanelPatch } = await import('../explainer/patch.mjs');
    const prepared = await preparePanelPatch({artifactPath:path.resolve(artifact),panelId,replacementPath:path.resolve(replacement),repoRoot:repoArgs.repoRoot,quality:qualityArgs.quality,writingMode:writingArgs.writingMode,expectedArtifact:originalCheck.artifact});
    const { resolveOutputPath } = await import('../renderers/shared/output-path.mjs');
    resolveOutputPath({requestedOutput:output,inputPaths:[path.resolve(replacement),prepared.sourcePath]});
    const { createOwnedTempDirectory } = await import('../renderers/shared/owned-temp-directory.mjs');
    const { writePreparedBundle } = await import('../explainer/prepare.mjs');
    temporary=createOwnedTempDirectory('archify-explainer-patch-');
    const input=path.join(temporary.path,'patched-draft.json');
    fs.writeFileSync(input,prepared.sourceText,{flag:'wx'});
    const { rebindPreparedBundle } = await import('../explainer/prepare.mjs');
    prepared.bundle=rebindPreparedBundle({...prepared.bundle,inputPath:input},{sourceText:prepared.bundle.sourceText,document:prepared.bundle.document,sourceMap:prepared.bundle.sourceMap,format:prepared.bundle.format,diagnostics:prepared.bundle.diagnostics});
    const preparedFile=writePreparedBundle(temporary.path,prepared.bundle);
    const delivery=runNode([fileURLToPath(import.meta.url),'deliver','explainer',input,output,'--quality',qualityArgs.quality || prepared.bundle.quality || 'standard','--writing',prepared.bundle.writingMode || 'warn',...(repoArgs.repoRoot?['--repo-root',repoArgs.repoRoot]:[]),'--json'],{stdio:'pipe',env:{ARCHIFY_EXPLAINER_PREPARED:preparedFile},maxBuffer:artifactCheckMaxBuffer()});
    let receipt;
    try {receipt=JSON.parse(delivery.stdout);} catch {throw new Error('Patch delivery did not return a structured receipt.');}
    const { computeExplainerRevision } = await import('../explainer/revision.mjs');
    const result={...receipt,command:'patch',panelId,original:{path:path.resolve(artifact),revision:prepared.previousRevision,sourceSha256:prepared.previousSourceSha256},replacement:{path:path.resolve(replacement)},revision:computeExplainerRevision(prepared.bundle),sourceSha256:prepared.bundle.source.sha256};
    if(json)console.log(JSON.stringify(result,null,2));
    else if(result.ok)console.log(`patched ${panelId} ${result.output}`);
    else console.error(formatDiagnostics(result.error,result.diagnostics));
    if(delivery.stderr)process.stderr.write(delivery.stderr);
    process.exitCode=delivery.status ?? 1;
  } catch(error) {
    reportArtifactFailure({command:'patch',json,stage:'prepare',type:'explainer',input:path.resolve(artifact),output:path.resolve(output),error:error.message,diagnostics:error.archifyDiagnostics || [diagnostic({code:'explainer/patch-runtime',message:error.message,subject:{input:path.resolve(artifact),line:1,component:'panel',panelId},evidence:{reason:error.code || 'patch-failure',example:'Use a complete replacement panel with the same stable id.'},supportedFixes:['Repair the replacement panel and retry.']})]});
  } finally {if(temporary)await temporary.cleanup();}
}

async function commandPreview(args) {
  const qualityArgs = extractQualityArgs(args);
  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
  const noOpen = repoArgs.rest.includes('--no-open');
  const knownOptions = new Set(['--no-open']);
  const unknown = repoArgs.rest.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
  if (unknown.length) fail(`Unknown preview option "${unknown[0]}".`);
  const positional = repoArgs.rest.filter((arg) => !knownOptions.has(arg));
  const [type, input, output] = positional;
  if (!type || !input || positional.length > 3) fail(usage());
  if (type === 'explainer') fail('Live preview supports the ten diagram types only. For explainer, run finalize explainer <draft.md> <output.html>, then open the HTML in your browser.');
  rendererPath(type);

  try {
    const source = JSON.parse(fs.readFileSync(path.resolve(input), 'utf8'));
    const { validateAuthoredOutputPath } = await import('../renderers/shared/output-path.mjs');
    validateAuthoredOutputPath(source?.meta?.output);
  } catch (error) {
    // Preserve live repair for unreadable or malformed JSON. A parsed document,
    // however, must already carry the durable output contract before preview
    // allocates a server, watcher, or staging directory.
    if (error?.archifyDiagnostics) fail(`Could not start live preview: ${error.message}`, 1);
  }

  let runPreview;
  try {
    ({ runPreview } = await import('./preview.mjs'));
  } catch (error) {
    fail(`Could not load live preview: ${error.message}`, 1);
  }
  try {
    await runPreview({
      type,
      input,
      output,
      quality: qualityArgs.quality,
      repoRoot: repoArgs.repoRoot,
      open: !noOpen,
    });
  } catch (error) {
    fail(`Could not start live preview: ${error.message}`, 1);
  }
}

async function loadPathIdentityRuntime() {
  try {
    await loadSidecarPathRuntime();
    const {
      sameEntry,
      sidecarNamespaceComponentKey,
    } = await import('../renderers/shared/path-semantics.mjs');
    sidecarNamespaceComponentKeyRuntime = sidecarNamespaceComponentKey;
    const {
      captureRegularFileBinding,
      verifyRegularFileBinding,
      releaseRegularFileBinding,
    } = await import('../renderers/shared/atomic-output.mjs');
    return {
      sameEntry,
      captureRegularFileBinding,
      verifyRegularFileBinding,
      releaseRegularFileBinding,
    };
  } catch (error) {
    return { error };
  }
}

function inspectArtifactDeliveryProvenance(
  artifactPath,
  requireProvenance,
  pathIdentityRuntime,
  expectedBindings,
) {
  const {
    captureRegularFileBinding,
    verifyRegularFileBinding,
    releaseRegularFileBinding,
  } = pathIdentityRuntime || {};
  const stableArtifactPath = canonicalExistingDeliveryOutput(artifactPath);
  let artifactCapture;
  try {
    if (typeof captureRegularFileBinding !== 'function'
      || typeof verifyRegularFileBinding !== 'function'
      || typeof releaseRegularFileBinding !== 'function') {
      throw new Error('The regular-file binding runtime is unavailable.');
    }
    artifactCapture = captureRegularFileBinding(stableArtifactPath, {
      subject: 'delivery-artifact',
      ...(expectedBindings?.artifact ? {
        expectedIdentity: expectedBindings.artifact.identity,
        expectedSha256: expectedBindings.artifact.content.sha256,
        expectedBytes: expectedBindings.artifact.content.bytes,
        expectedMode: expectedBindings.artifact.mode,
      } : {}),
      expectedLinks: 1,
      includeContent: true,
    });
    if (artifactCapture.status !== 'captured') {
      if (artifactCapture.reason?.code === 'delivery-artifact-hardlinked') {
        const message = 'Delivery provenance is unsupported for a hard-linked artifact because one receipt cannot prove every linked name was updated atomically.';
        return {
          ok: false,
          status: 'unsupported',
          diagnostics: [diagnostic({
            code: 'output/target-hardlinked',
            message,
            subject: { artifact: path.resolve(artifactPath) },
            evidence: { links: artifactCapture.reason.links },
            supportedFixes: ['remove the extra hard links, then rerun deliver and strict check on the remaining artifact path'],
          })],
        };
      }
      throw new Error(`The artifact is not a stable regular file (${artifactCapture.reason?.code || 'unknown target state'}).`);
    }
  } catch (error) {
    return {
      ok: false, status: 'unknown',
      diagnostics: [diagnostic({
        code: 'input/artifact-unreadable', message: `Could not read the HTML artifact: ${error.message}`,
        subject: { artifact: artifactPath },
        evidence: { reason: error.message, ...(error.code ? { systemCode: error.code } : {}) },
        supportedFixes: ['provide an existing readable .html artifact, then rerun the checker'],
      })],
    };
  }
  try {
    const inspection = {};
    const provenance = inspectDeliveryProvenance(
      artifactPath,
      artifactCapture.content.buffer,
      {
        requireProvenance,
        pathIdentityRuntime,
        expectedSidecar: expectedBindings?.sidecar,
        inspection,
      },
    );
    const verification = verifyRegularFileBinding(artifactCapture.binding, {
      filePath: stableArtifactPath,
      expectedLinks: 1,
    });
    if (verification.status !== 'match') {
      return {
        ok: false,
        status: 'mismatch',
        diagnostics: [diagnostic({
          code: 'delivery/provenance-mismatch',
          message: 'The artifact changed while delivery provenance was being inspected.',
          subject: { artifact: artifactPath },
          evidence: { artifactState: verification.reason },
          supportedFixes: ['finish delivery and other writes before rerunning the checker'],
        })],
      };
    }
    const result = {
      ...provenance,
      artifact: {
        sha256: artifactCapture.content.sha256,
        bytes: artifactCapture.content.bytes,
      },
    };
    Object.defineProperty(result, 'fileBindings', {
      enumerable: false,
      value: {
        artifact: {
          identity: {
            device: artifactCapture.identity.device,
            inode: artifactCapture.identity.inode,
          },
          content: {
            sha256: artifactCapture.content.sha256,
            bytes: artifactCapture.content.bytes,
          },
          mode: artifactCapture.mode,
        },
        ...(inspection.sidecar ? { sidecar: inspection.sidecar } : {}),
      },
    });
    return result;
  } finally {
    releaseRegularFileBinding(artifactCapture.binding);
  }
}

function verifyDeliveryUnchanged(artifactPath, expected, checkedArtifact, pathIdentityRuntime) {
  const current = inspectArtifactDeliveryProvenance(
    artifactPath,
    false,
    pathIdentityRuntime,
    expected?.fileBindings,
  );
  if (current && !current.ok) return current;
  if (!current || !expected || current.status !== expected.status || current.receiptId !== expected.receiptId
    || current.artifact.sha256 !== expected.artifact.sha256 || current.artifact.bytes !== expected.artifact.bytes
    || checkedArtifact.sha256 !== expected.artifact.sha256 || checkedArtifact.bytes !== expected.artifact.bytes) {
    return {
      ok: false, status: 'mismatch',
      diagnostics: [diagnostic({
        code: 'delivery/provenance-mismatch', message: 'The artifact or delivery record changed during inspection.',
        subject: { artifact: artifactPath },
        evidence: { expected: expected?.artifact, checked: checkedArtifact, current: current?.artifact },
        supportedFixes: ['finish delivery and other writes before rerunning the checker'],
      })],
    };
  }
  return current;
}

function provenanceFailureReceipt({ command, artifactPath, provenance }) {
  const error = provenance.diagnostics[0].message;
  return {
    schemaVersion: 1,
    ok: false,
    command,
    ...(['visual-check', 'browser-check'].includes(command) ? {
      evidenceKind: 'automated-browser',
      status: 'fail',
      visualReview: command === 'visual-check' ? 'pending' : 'not-requested',
    } : {}),
    provenance: provenance.status,
    ...(provenance.receiptId ? { deliveryReceiptId: provenance.receiptId } : {}),
    artifact: { path: artifactPath },
    error,
    ...(command === 'check' ? { file: artifactPath, diagnostic: error } : {}),
    diagnostics: provenance.diagnostics,
  };
}

async function commandCheck(args) {
  const knownOptions = new Set(['--json', '--require-provenance']);
  const unknown = args.find((arg) => arg.startsWith('--') && !knownOptions.has(arg));
  if (unknown) fail(`Unknown check option "${unknown}".`);
  const requireProvenance = args.includes('--require-provenance');
  const positional = args.filter((arg) => !knownOptions.has(arg));
  const [html] = positional;
  if (!html || positional.length !== 1) fail(usage());
  const artifactPath = path.resolve(html);
  const pathIdentityRuntime = await loadPathIdentityRuntime();
  const provenance = inspectArtifactDeliveryProvenance(
    artifactPath,
    requireProvenance,
    pathIdentityRuntime,
  );
  if (provenance && !provenance.ok) {
    console.log(JSON.stringify(provenanceFailureReceipt({ command: 'check', artifactPath, provenance }), null, 2));
    process.exitCode = 1;
    return;
  }
  const checkMaxBuffer = artifactCheckMaxBuffer();
  const result = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), html], {
    stdio: 'pipe',
    maxBuffer: checkMaxBuffer,
  });
  if (result.error) {
    if (result.stderr) process.stderr.write(result.stderr);
    const outputLimit = checkerOutputLimitDiagnostics(result, checkMaxBuffer);
    if (outputLimit) {
      const file = path.resolve(html);
      const message = outputLimit[0].message;
      console.log(JSON.stringify({
        schemaVersion: 1,
        ok: false,
        command: 'check',
        artifact: { path: file },
        file,
        error: message,
        diagnostic: message,
        diagnostics: outputLimit,
      }, null, 2));
    } else {
      console.error(result.error.message);
    }
    process.exitCode = 1;
    return;
  }
  if (result.stdout) {
    let receipt;
    try {
      receipt = JSON.parse(result.stdout);
    } catch {
      process.stdout.write(result.stdout);
    }
    if (receipt) {
      if (provenance?.status === 'current' && ((provenance.type === 'explainer') !== (receipt.family === 'explainer'))) {
        receipt.ok = false;
        receipt.diagnostics = [...(receipt.diagnostics || []), diagnostic({code:'delivery/artifact-family-mismatch',message:'The checked artifact family differs from its delivery provenance.',subject:{artifact:artifactPath},evidence:{expectedType:provenance.type,actualFamily:receipt.family},supportedFixes:['Rebuild the artifact from its original specification.']})];
        process.exitCode = 1;
      }
      if (provenance) {
        const verified = verifyDeliveryUnchanged(
          artifactPath,
          provenance,
          receipt.artifact || {},
          pathIdentityRuntime,
        );
        if (!verified.ok) {
          console.log(JSON.stringify(provenanceFailureReceipt({ command: 'check', artifactPath, provenance: verified }), null, 2));
          process.exitCode = 1;
          return;
        }
        receipt.provenance = provenance.status;
        if (provenance.receiptId) receipt.deliveryReceiptId = provenance.receiptId;
      }
      console.log(JSON.stringify(receipt, null, 2));
    }
  }
  if (result.stderr) process.stderr.write(result.stderr);
  if (result.status !== 0) process.exitCode = result.status ?? 1;
}

async function executeBrowserEvidence({
  artifactPath, outDir, requireProvenance, command, capture, ...browserOptions
}) {
  const pathIdentityRuntime = await loadPathIdentityRuntime();
  const provenance = inspectArtifactDeliveryProvenance(artifactPath, requireProvenance, pathIdentityRuntime);
  let runEvidence;
  let persistFailure;
  try {
    const evidence = await import('./visual-check.mjs');
    runEvidence = command === 'browser-check' ? evidence.runBrowserCheck : evidence.runVisualCheck;
    persistFailure = command === 'browser-check'
      ? evidence.persistBrowserCheckFailure
      : evidence.persistVisualCheckFailure;
  } catch (error) {
    fail(`Could not load ${command}: ${error.message}`, 1);
  }
  if (provenance && !provenance.ok) {
    const receipt = persistFailure(artifactPath,
      provenanceFailureReceipt({ command, artifactPath, provenance }),
      { outDir });
    return { exitCode: 1, receipt, inputFailure: true };
  }

  let result;
  try {
    result = await runEvidence({
      ...browserOptions,
      artifactPath,
      outDir,
      ...(provenance ? { deliveryProvenance: provenance } : {}),
      verifyArtifact: (bytes) => {
        const verified = verifyDeliveryUnchanged(
          artifactPath,
          provenance,
          artifactIdentity(bytes),
          pathIdentityRuntime,
        );
        if (!verified.ok) {
          const error = new Error(verified.diagnostics[0].message);
          error.deliveryProvenance = verified;
          error.archifyDiagnostics = verified.diagnostics;
          throw error;
        }
      },
    });
  } catch (error) {
    const failure = persistFailure(artifactPath, {
        schemaVersion: 1,
        ok: false,
        command,
        evidenceKind: 'automated-browser',
        status: 'fail',
        visualReview: capture ? 'pending' : 'not-requested',
        ...(provenance ? {
          provenance: provenance.status,
          ...(provenance.receiptId ? { deliveryReceiptId: provenance.receiptId } : {}),
        } : {}),
        artifact: { path: artifactPath },
        error: error.message,
        diagnostics: [diagnostic({
          code: `viewer/${command}-input`,
          message: `${command} could not read a valid HTML input or prepare its evidence files.`,
          subject: { artifact: artifactPath },
          evidence: { reason: error.message, ...(error.code ? { systemCode: error.code } : {}) },
          supportedFixes: ['provide an existing readable .html artifact and a writable directory for evidence files'],
        })],
      }, { outDir });
    return { exitCode: 1, receipt: failure, inputFailure: true };
  }

  return result;
}

async function commandBrowserEvidence(rawArgs, { command, capture }) {
  const { rest: args, outDir: rawOutDir } = extractOutDirArgs(rawArgs);
  const summary = args.includes('--summary');
  const json = args.includes('--json') || summary;
  const printJson = async (receipt) => {
    const value = summary
      ? (await import('./visual-check.mjs')).summarizeBrowserEvidence(receipt)
      : receipt;
    console.log(JSON.stringify(value, null, summary ? undefined : 2));
  };
  const requireProvenance = args.includes('--require-provenance');
  const knownOptions = new Set(['--json', '--summary', '--require-provenance']);
  const unknown = args.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
  if (unknown.length) fail(`Unknown ${command} option "${unknown[0]}".`, 1);
  const positional = args.filter((arg) => !knownOptions.has(arg));
  if (positional.length !== 1) fail(usage(), 1);

  const artifactPath = path.resolve(positional[0]);
  let outDir;
  if (rawOutDir !== undefined) {
    const { resolveNativeOutputDirectory } = await import('../renderers/shared/output-path.mjs');
    try {
      outDir = resolveNativeOutputDirectory(rawOutDir);
    } catch (error) {
      const outputDiagnostic = error.archifyDiagnostics?.[0] || diagnostic({
        code: 'output/native-path-syntax',
        message: error.message,
        subject: { output: rawOutDir },
        evidence: { ...(error?.code ? { systemCode: error.code } : {}) },
        supportedFixes: ['choose an ordinary native filesystem directory and retry'],
      });
      const failure = {
        schemaVersion: 1,
        ok: false,
        command,
        evidenceKind: 'automated-browser',
        status: 'fail',
        visualReview: capture ? 'pending' : 'not-requested',
        artifact: { path: artifactPath },
        error: error.message,
        diagnostics: [outputDiagnostic],
      };
      if (json) await printJson(failure);
      else {
        console.error(formatDiagnostics(`automated browser evidence failed: ${failure.error}`, failure.diagnostics));
        console.error('perceptual visual review pending');
      }
      process.exitCode = 1;
      return;
    }
  }
  const result = await executeBrowserEvidence({ artifactPath, outDir, requireProvenance, command, capture });

  if (result.inputFailure) {
    if (json) await printJson(result.receipt);
    else {
      console.error(formatDiagnostics(`automated browser evidence failed: ${result.receipt.error}`, result.receipt.diagnostics));
      console.error(capture ? 'perceptual visual review pending' : 'perceptual visual review not requested');
    }
    process.exitCode = result.exitCode;
    return;
  }

  if (json) {
    await printJson(result.receipt);
  } else {
    const sidecarDirectory = outDir || path.dirname(result.receipt.artifact.path);
    console.log(`automated browser evidence ${result.receipt.status}: ${result.receipt.artifact.path}`);
    console.log(`${command} containment ${result.receipt.containment.status}; captures ${result.receipt.captures.status}; perceptual visual review ${result.receipt.visualReview}`);
    console.log(`receipt ${path.join(sidecarDirectory, result.receipt.sidecars.receipt)}`);
    if (result.receipt.captures.contactSheet) {
      console.log(`contact sheet ${path.join(sidecarDirectory, result.receipt.captures.contactSheet)}`);
    }
    if (result.receipt.error) console.error(result.receipt.error);
  }
  process.exitCode = result.exitCode;
}

async function commandVisualCheck(rawArgs) {
  return commandBrowserEvidence(rawArgs, { command: 'visual-check', capture: true });
}

async function commandBrowserCheck(rawArgs) {
  return commandBrowserEvidence(rawArgs, { command: 'browser-check', capture: false });
}

function extractFinalizeReceiptArgs(args) {
  const rest = [];
  let receiptPath;
  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (arg === '--receipt') {
      receiptPath = args[index + 1];
      if (!receiptPath || receiptPath.startsWith('--')) rejectCliArgument('--receipt requires a JSON output path.', {
        code: 'cli/missing-option-value',
        subject: { option: '--receipt' },
        supportedFixes: ['provide one .json path after --receipt'],
      });
      index += 1;
      continue;
    }
    if (arg.startsWith('--receipt=')) {
      receiptPath = arg.slice('--receipt='.length);
      if (!receiptPath) rejectCliArgument('--receipt requires a JSON output path.', {
        code: 'cli/missing-option-value',
        subject: { option: '--receipt' },
        supportedFixes: ['provide one .json path after --receipt'],
      });
      continue;
    }
    rest.push(arg);
  }
  return { rest, receiptPath };
}

function extractCandidateSha256Args(args) {
  const rest = [];
  let candidateSha256;
  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (arg === '--candidate-sha256') {
      candidateSha256 = args[index + 1];
      if (!candidateSha256 || candidateSha256.startsWith('--')) rejectCliArgument('--candidate-sha256 requires a SHA-256 digest.', {
        code: 'cli/missing-option-value',
        subject: { option: '--candidate-sha256' },
        supportedFixes: ['provide the candidate sha256 from the passing validate receipt'],
      });
      index += 1;
      continue;
    }
    if (arg.startsWith('--candidate-sha256=')) {
      candidateSha256 = arg.slice('--candidate-sha256='.length);
      if (!candidateSha256) rejectCliArgument('--candidate-sha256 requires a SHA-256 digest.', {
        code: 'cli/missing-option-value',
        subject: { option: '--candidate-sha256' },
        supportedFixes: ['provide the candidate sha256 from the passing validate receipt'],
      });
      continue;
    }
    rest.push(arg);
  }
  if (candidateSha256 !== undefined && !/^[0-9a-f]{64}$/.test(candidateSha256)) {
    rejectCliArgument('--candidate-sha256 must be 64 lowercase hexadecimal characters.', {
      code: 'cli/invalid-option-value',
      subject: { option: '--candidate-sha256' },
      evidence: { value: candidateSha256 },
      supportedFixes: ['copy candidate.sha256 from the passing validate receipt without modification'],
    });
  }
  return { rest, candidateSha256 };
}

async function commandFinalize(rawArgs) {
  const qualityArgs = extractQualityArgs(rawArgs);
  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
  const outDirArgs = extractOutDirArgs(repoArgs.rest);
  const receiptArgs = extractFinalizeReceiptArgs(outDirArgs.rest);
  const candidateArgs = extractCandidateSha256Args(receiptArgs.rest);
  const writingArgs = extractExplainerWritingArgs(candidateArgs.rest);
  candidateArgs.rest = writingArgs.rest;
  const json = candidateArgs.rest.includes('--json');
  const knownOptions = new Set(['--json','--browser-check']);
  const unknown = candidateArgs.rest.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
  if (unknown.length) rejectCliArgument(`Unknown finalize option "${unknown[0]}".`, {
    code: 'cli/unknown-option',
    subject: { option: unknown[0] },
    supportedFixes: ['remove the unknown option and retry'],
  });
  const positional = candidateArgs.rest.filter((arg) => !knownOptions.has(arg));
  const [type, input, output] = positional;
  if (!type || !input || !output || positional.length !== 3) rejectCliArgument(usage(), {
    code: 'cli/usage',
    supportedFixes: ['use: archify finalize <type> <input.json> <output.html> [options]'],
  });
  rendererPath(type);

  let runFinalize;
  try {
    ({ runFinalize } = await import('./finalize.mjs'));
  } catch (error) {
    fail(`Could not load finalize: ${error.message}`, 1);
  }

  let result;
  let explainerTemporary;
  try {
    let preparedExplainer;
    let preparedBundlePath;
    if (type === 'explainer') {
      preparedExplainer = await prepareExplainerInput(fs.readFileSync(path.resolve(input)), path.resolve(input), { repoRoot: repoArgs.repoRoot, quality: qualityArgs.quality || 'showcase', writingMode: writingArgs.writingMode });
      const { createOwnedTempDirectory } = await import('../renderers/shared/owned-temp-directory.mjs');
      const { writePreparedBundle } = await import('../explainer/prepare.mjs');
      explainerTemporary = createOwnedTempDirectory('archify-explainer-finalize-');
      preparedBundlePath = writePreparedBundle(explainerTemporary.path, preparedExplainer);
    }
    const pathIdentityRuntime = await loadPathIdentityRuntime();
    result = await runFinalize({
      ...(preparedExplainer ? { preparedExplainer, env: { ...process.env, ARCHIFY_EXPLAINER_PREPARED: preparedBundlePath } } : {}),
      cliPath: fileURLToPath(import.meta.url),
      type,
      input,
      output,
      quality: qualityArgs.quality || 'showcase',
      repoRoot: repoArgs.repoRoot,
      writingMode: writingArgs.writingMode,
      browserCheck: candidateArgs.rest.includes('--browser-check'),
      candidateSha256: candidateArgs.candidateSha256,
      outDir: outDirArgs.outDir,
      receiptPath: receiptArgs.receiptPath,
      inspectDelivery: artifact => inspectArtifactDeliveryProvenance(artifact, true, pathIdentityRuntime),
      deliveryPaths: artifact => ({
        provenance: deliveryProvenancePath(artifact),
        pending: deliveryPendingPath(artifact),
        lock: deliverySidecarPath(artifact, '.delivery-lock.json'),
        directoryLock: path.join(path.dirname(deliveryProvenancePath(artifact)), DELIVERY_DIRECTORY_LOCK),
      }),
      runBrowserCheck: options => executeBrowserEvidence({
        ...options, command: 'browser-check', capture: false, requireProvenance: true,
      }),
    });
  } catch (error) {
    const failure = {
      schemaVersion: 1,
      ok: false,
      command: 'finalize',
      status: 'fail',
      type,
      quality: qualityArgs.quality || 'showcase',
      specification: { path: path.resolve(input) },
      artifact: { path: path.resolve(output) },
      gates: Object.fromEntries(['validate', 'deliver', 'check', 'browser-check'].map((stage) => [stage, 'not-run'])),
      browserCheck: {requested:type !== 'explainer' || candidateArgs.rest.includes('--browser-check'),ran:false},
      diagnostics: error.archifyDiagnostics || [{
        code: error.finalizeCode || 'finalize/runtime',
        severity: 'error',
        message: error.message,
        ...(error.finalizeEvidence ? { evidence: error.finalizeEvidence } : {}),
      }],
      visualReview: 'not-requested',
    };
    if (json) console.log(JSON.stringify(failure));
    else console.error(formatDiagnostics('finalize could not start', failure.diagnostics));
    process.exitCode = 1;
    return;
  } finally {
    if (explainerTemporary) await explainerTemporary.cleanup();
  }

  if (json) {
    console.log(JSON.stringify(result.summary));
  } else {
    console.log(`finalize ${result.summary.status}: ${result.summary.artifact.path}`);
    console.log(`gates ${Object.entries(result.summary.gates).map(([stage, status]) => `${stage}:${status}`).join(' ')}`);
    console.log(`receipt ${result.summary.evidence.receipt}`);
    console.log(`perceptual visual review ${result.summary.visualReview}`);
    for (const entry of result.summary.diagnostics || []) {
      if (entry.severity === 'warning') console.error(`warning [${entry.code}] ${entry.message}`);
    }
    if (result.summary.update?.noticeRequired) console.log(result.summary.update.noticeText);
  }
  process.exitCode = result.exitCode;
}

function commandExamples(args) {
  const unknown = args.find((arg) => arg.startsWith('--'));
  if (unknown) fail(`Unknown examples option "${unknown}".`);
  if (args.length) fail(usage());
  const result = runNode([path.join(skillRoot, 'scripts/render-examples.mjs')], { cwd: skillRoot });
  if (result.status !== 0) exitFrom(result);
}

async function commandDoctor(args) {
  const unknown = args.find((arg) => arg.startsWith('--'));
  if (unknown) fail(`Unknown doctor option "${unknown}".`);
  if (args.length) fail(usage());
  const checks = [];
  const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
  checks.push({
    label: `Node.js v${process.versions.node} (requires >=18)`,
    ok: nodeMajor >= 18,
    missing: 0,
    failureLabel: 'unsupported',
  });

  const template = path.join(skillRoot, 'assets/template.html');
  checks.push({
    label: 'Core template',
    ok: fs.existsSync(template),
    missing: fs.existsSync(template) ? 0 : 1,
  });

  const examplesRenderer = path.join(skillRoot, 'scripts/render-examples.mjs');
  checks.push({
    label: 'Example renderer',
    ok: fs.existsSync(examplesRenderer),
    missing: fs.existsSync(examplesRenderer) ? 0 : 1,
  });

  const previewRuntime = path.join(skillRoot, 'bin/preview.mjs');
  checks.push({
    label: 'Live preview runtime',
    ok: fs.existsSync(previewRuntime),
    missing: fs.existsSync(previewRuntime) ? 0 : 1,
  });

  const visualCheckRuntime = path.join(skillRoot, 'bin/visual-check.mjs');
  checks.push({
    label: 'Visual-check runtime',
    ok: fs.existsSync(visualCheckRuntime),
    missing: fs.existsSync(visualCheckRuntime) ? 0 : 1,
  });

  const finalizeRuntime = path.join(skillRoot, 'bin/finalize.mjs');
  checks.push({
    label: 'Finalize runtime',
    ok: fs.existsSync(finalizeRuntime),
    missing: fs.existsSync(finalizeRuntime) ? 0 : 1,
  });

  const outputPathRuntime = path.join(skillRoot, 'renderers/shared/output-path.mjs');
  checks.push({
    label: 'Output path safety runtime',
    ok: fs.existsSync(outputPathRuntime),
    missing: fs.existsSync(outputPathRuntime) ? 0 : 1,
  });

  const atomicOutputRuntime = path.join(skillRoot, 'renderers/shared/atomic-output.mjs');
  checks.push({
    label: 'Atomic output safety runtime',
    ok: fs.existsSync(atomicOutputRuntime),
    missing: fs.existsSync(atomicOutputRuntime) ? 0 : 1,
  });

  const pathSemanticsRuntime = path.join(skillRoot, 'renderers/shared/path-semantics.mjs');
  checks.push({
    label: 'Physical path semantics runtime',
    ok: fs.existsSync(pathSemanticsRuntime),
    missing: fs.existsSync(pathSemanticsRuntime) ? 0 : 1,
  });

  const sidecarPathRuntime = path.join(skillRoot, 'renderers/shared/sidecar-path.mjs');
  checks.push({
    label: 'Sidecar path naming runtime',
    ok: fs.existsSync(sidecarPathRuntime),
    missing: fs.existsSync(sidecarPathRuntime) ? 0 : 1,
  });

  const portablePathRuntime = path.join(skillRoot, 'renderers/shared/portable-path.mjs');
  checks.push({
    label: 'Portable path contract runtime',
    ok: fs.existsSync(portablePathRuntime),
    missing: fs.existsSync(portablePathRuntime) ? 0 : 1,
  });

  const scenarioGuide = path.join(skillRoot, 'recipes/scenarios.mjs');
  checks.push({
    label: 'Scenario recipe guide',
    ok: fs.existsSync(scenarioGuide),
    missing: fs.existsSync(scenarioGuide) ? 0 : 1,
  });

  const authoringReferences = [
    path.join(skillRoot, 'references', 'authoring-contract.md'),
    path.join(skillRoot, 'references', 'viewer-runtime.md'),
    path.join(skillRoot, 'references', 'delivery-contract.md'),
  ];
  const authoringReferencesMissing = authoringReferences.filter((file) => !fs.existsSync(file)).length;
  checks.push({
    label: 'Progressive authoring references',
    ok: authoringReferencesMissing === 0,
    missing: authoringReferencesMissing,
  });

  const compareRuntime = path.join(skillRoot, 'delta/architecture-delta.mjs');
  const compareFixtures = [
    path.join(skillRoot, 'examples/checkout-platform.base.architecture.json'),
    path.join(skillRoot, 'examples/checkout-platform.head.architecture.json'),
  ];
  const compareMissing = [compareRuntime, ...compareFixtures].filter((file) => !fs.existsSync(file)).length;
  checks.push({
    label: 'Architecture compare runtime and proof fixtures',
    ok: compareMissing === 0,
    missing: compareMissing,
  });

  const validators = path.join(skillRoot, 'renderers/shared/generated-validators.mjs');
  const validatorsExist = fs.existsSync(validators);
  let validatorsValid = false;
  if (validatorsExist) {
    try {
      const module = await import(`${pathToFileURL(validators).href}?doctor=${Date.now()}`);
      validatorsValid = [...TYPES].every((type) => typeof module[type] === 'function');
    } catch {
      validatorsValid = false;
    }
  }
  checks.push({
    label: 'Standalone schema validators',
    ok: validatorsValid,
    missing: validatorsExist ? 0 : 1,
    invalid: validatorsExist && !validatorsValid ? 1 : 0,
    failureLabel: validatorsExist ? 'invalid' : 'missing',
  });

  const examples = {
    architecture: 'web-app.architecture.json',
    workflow: 'agent-tool-call.workflow.json',
    sequence: 'cache-miss-request.sequence.json',
    dataflow: 'product-analytics.dataflow.json',
    lifecycle: 'agent-run.lifecycle.json',
    erd: 'orders.erd.json',
    tree: 'payment-platform.tree.json',
    class: 'payments.class.json',
    timeline: 'payment-incident.timeline.json',
    waterfall: 'checkout-request.waterfall.json',
    explainer: 'delivery.explainer.json',
  };

  for (const type of TYPES) {
    const required = [
      path.join(skillRoot, 'renderers', type, `render-${type}.mjs`),
      path.join(skillRoot, 'schemas', `${type}.schema.json`),
      path.join(skillRoot, 'examples', examples[type]),
    ];
    const missing = required.filter((file) => !fs.existsSync(file)).length;
    checks.push({
      label: `${type} renderer, schema, and example`,
      ok: missing === 0,
      missing,
    });
  }

  const explainerRuntime = ['parse.mjs', 'validate.mjs', 'inline.mjs', 'sources.mjs', 'writing.mjs', 'diagrams.mjs', 'prepare.mjs', 'patch.mjs', 'diff.mjs', 'revision.mjs', 'layout.mjs', 'render.mjs', 'check.mjs', 'browser-check.mjs', 'charts.mjs', 'page-bundle.mjs', 'vendor/pele/core.js', 'reader.css', 'reader.js'];
  const missingExplainerRuntime = explainerRuntime.filter(file => !fs.existsSync(path.join(skillRoot, 'explainer', file))).length;
  checks.push({label:'Explainer runtime and reader assets',ok:missingExplainerRuntime===0,missing:missingExplainerRuntime});

  console.log('Archify doctor\n');
  for (const check of checks) {
    console.log(`[${check.ok ? 'ok' : (check.failureLabel || 'missing')}] ${check.label}`);
  }

  const nodeFailed = checks[0].ok ? 0 : 1;
  const missingFiles = checks.reduce((count, check) => count + check.missing, 0);
  const invalidRuntime = checks.reduce((count, check) => count + (check.invalid || 0), 0);
  if (nodeFailed === 0 && missingFiles === 0 && invalidRuntime === 0) {
    console.log('\nArchify is ready.');
    return;
  }

  const problems = [];
  if (nodeFailed) problems.push('Node.js 18 or newer is required');
  if (missingFiles) problems.push(`${missingFiles} required file${missingFiles === 1 ? '' : 's'} missing`);
  if (invalidRuntime) problems.push(`${invalidRuntime} runtime check${invalidRuntime === 1 ? '' : 's'} failed`);
  console.error(`\nArchify is not ready: ${problems.join('; ')}.`);
  process.exitCode = 1;
}

async function commandGuide(args) {
  let lang;
  let json = false;
  const queryParts = [];

  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (arg === '--json') {
      json = true;
    } else if (arg === '--lang') {
      const value = args[index + 1];
      if (value !== 'en' && value !== 'zh') fail('--lang must be "en" or "zh".');
      lang = value;
      index += 1;
    } else if (arg.startsWith('--lang=')) {
      const value = arg.slice('--lang='.length);
      if (value !== 'en' && value !== 'zh') fail('--lang must be "en" or "zh".');
      lang = value;
    } else if (arg.startsWith('--')) {
      fail(`Unknown guide option "${arg}".`);
    } else {
      queryParts.push(arg);
    }
  }

  const guidePath = path.join(skillRoot, 'recipes/scenarios.mjs');
  let guide;
  try {
    guide = await import(pathToFileURL(guidePath).href);
  } catch (error) {
    fail(`Could not load the scenario recipe guide: ${error.message}`, 1);
  }

  const query = queryParts.join(' ').trim();
  if (!query) {
    const selectedLang = lang || 'en';
    if (json) {
      console.log(JSON.stringify({
        ok: true,
        mode: 'list',
        lang: selectedLang,
        recipes: guide.listScenarioRecipes(selectedLang),
      }, null, 2));
    } else {
      console.log(guide.formatScenarioList(selectedLang));
    }
    return;
  }

  const result = guide.recommendScenario(query, lang ? { lang } : {});
  console.log(json ? JSON.stringify(result, null, 2) : guide.formatScenarioRecommendation(result));
}

async function commandBrands(args) {
  const json = args.includes('--json');
  const unknown = args.filter((arg) => arg.startsWith('--') && arg !== '--json');
  if (unknown.length) fail(`Unknown brands option "${unknown[0]}".`);
  const positional = args.filter((arg) => arg !== '--json');
  if (positional[0] === 'capture') {
    if (positional.length !== 2) fail('Usage: archify brands capture <url> [--json]');
    const { captureBrandReference } = await import('../renderers/shared/brand-marks.mjs');
    let capture;
    try {
      capture = await captureBrandReference(positional[1]);
    } catch (error) {
      fail(error.message);
    }
    const result = {
      schemaVersion: 1,
      ok: true,
      command: 'brands capture',
      brand: capture.brand,
      evidence: {
        status: capture.resolved.status,
        source: capture.resolved.sourceUrl,
        ...(capture.resolved.sha256 ? { sha256: capture.resolved.sha256 } : {}),
        ...(capture.resolved.contentType ? { contentType: capture.resolved.contentType } : {}),
      },
    };
    console.log(json ? JSON.stringify(result, null, 2) : JSON.stringify(result.brand));
    return;
  }
  const query = positional.join(' ').trim();
  const { listBrandMarks } = await import('../renderers/shared/brand-marks.mjs');
  const marks = listBrandMarks(query);
  if (json) {
    console.log(JSON.stringify({
      schemaVersion: 1,
      ok: true,
      command: 'brands',
      query,
      count: marks.length,
      marks,
      fallback: 'Run "archify brands capture <url> --json", then use the returned digest-pinned brand value.',
    }, null, 2));
    return;
  }
  if (!marks.length) {
    console.log(`No built-in brand matched "${query}". Run "archify brands capture <url> --json", then use the returned digest-pinned brand value.`);
    return;
  }
  const grouped = Map.groupBy
    ? Map.groupBy(marks, (mark) => mark.category)
    : marks.reduce((map, mark) => map.set(mark.category, [...(map.get(mark.category) || []), mark]), new Map());
  for (const [category, entries] of grouped) {
    console.log(`${category}: ${entries.map((mark) => mark.id).join(', ')}`);
  }
}

function commandDemo(args) {
  const unknown = args.find((arg) => arg.startsWith('--'));
  if (unknown) fail(`Unknown demo option "${unknown}".`);
  if (args.length > 1) fail(usage());

  const outputDirectory = path.resolve(args[0] || process.cwd());
  const output = path.join(outputDirectory, 'archify-demo.html');
  const input = path.join(skillRoot, 'examples/web-app.architecture.json');

  try {
    fs.mkdirSync(outputDirectory, { recursive: true });
  } catch (error) {
    fail(`Could not create demo directory "${outputDirectory}": ${error.message}`, 1);
  }

  const result = runNode([rendererPath('architecture'), input, output]);
  if (result.status !== 0) exitFrom(result);

  console.log(`\nDemo ready: ${output}`);
  console.log('Next: open the HTML in your browser, then render your own diagram:');
  console.log('  archify render architecture <input.json> <output.html>');
}

function migrationPathDiagnostics(error, sourcePath, destinationPath) {
  if (Array.isArray(error?.archifyDiagnostics) && error.archifyDiagnostics.length) {
    return error.archifyDiagnostics.map((entry) => ({
      ...entry,
      subject: { ...(entry.subject || {}) },
      evidence: { ...(entry.evidence || {}) },
      supportedFixes: [...(entry.supportedFixes || [])],
    }));
  }
  return [diagnostic({
    code: 'migration/path-preflight',
    message: 'Could not verify that the workflow migration paths are distinct.',
    subject: { source: sourcePath, destination: destinationPath },
    evidence: {
      ...(error?.code ? { systemCode: error.code } : {}),
      reason: error?.message || String(error),
    },
    supportedFixes: ['remove unsafe path aliases or choose a different destination path'],
  })];
}

function migrationReport({
  ok,
  sourcePath,
  destinationPath,
  sourceBytes,
  destinationBytes,
  fromSchemaVersion,
  preExistingDiagnostics = [],
  migrationDiagnostics = [],
  newSchemaDiagnostics = [],
  changedCoordinates = [],
  oldRequiredViewBox = null,
  newRequiredViewBox = null,
}) {
  const report = {
    ok,
    command: 'migrate',
    type: 'workflow',
    source: {
      path: sourcePath,
      ...(sourceBytes ? {
        sha256: createHash('sha256').update(sourceBytes).digest('hex'),
        bytes: sourceBytes.length,
      } : {}),
    },
    destination: {
      path: destinationPath,
      ...(destinationBytes ? {
        sha256: createHash('sha256').update(destinationBytes).digest('hex'),
        bytes: destinationBytes.length,
      } : {}),
    },
    fromSchemaVersion: fromSchemaVersion ?? null,
    toSchemaVersion: 2,
    preExistingDiagnostics,
    migrationDiagnostics,
    newSchemaDiagnostics,
    changedCoordinates,
    oldRequiredViewBox,
    newRequiredViewBox,
  };
  if (!ok) {
    report.diagnostics = [
      ...migrationDiagnostics,
      ...newSchemaDiagnostics,
      ...preExistingDiagnostics,
    ];
    if (!report.diagnostics.length) {
      report.diagnostics.push(diagnostic({
        code: 'migration/internal',
        message: 'Workflow migration failed without a classified diagnostic.',
      }));
    }
    report.error = report.diagnostics[0].message;
  }
  return report;
}

function extractMigrationOptions(args) {
  const positional = [];
  let json = false;
  let toSchema;
  let output;
  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (arg === '--json') {
      json = true;
      continue;
    }
    if (arg === '--to-schema') {
      toSchema = args[index + 1];
      if (!toSchema || toSchema.startsWith('--')) fail('--to-schema requires a schema version.');
      index += 1;
      continue;
    }
    if (arg.startsWith('--to-schema=')) {
      toSchema = arg.slice('--to-schema='.length);
      if (!toSchema) fail('--to-schema requires a schema version.');
      continue;
    }
    if (arg === '--output') {
      output = args[index + 1];
      if (!output || output.startsWith('--')) fail('--output requires a portable HTML path.');
      index += 1;
      continue;
    }
    if (arg.startsWith('--output=')) {
      output = arg.slice('--output='.length);
      if (!output) fail('--output requires a portable HTML path.');
      continue;
    }
    if (arg.startsWith('--')) fail(`Unknown migrate option "${arg}".`);
    positional.push(arg);
  }
  return { positional, json, toSchema, output };
}

async function commandMigrate(args) {
  const repoArgs = extractRepoRootArgs(args);
  const options = extractMigrationOptions(repoArgs.rest);
  const [type, sourceArgument, destinationArgument] = options.positional;
  if (
    type !== 'workflow'
    || !sourceArgument
    || !destinationArgument
    || options.positional.length !== 3
    || options.toSchema !== '2'
  ) {
    fail('Usage: archify migrate workflow <old.json> <new.json> --to-schema 2 [--output portable.html] [--json] [--repo-root path]');
  }

  const sourcePath = path.resolve(sourceArgument);
  const destinationPath = path.resolve(destinationArgument);
  let sourceBytes;
  let sourceDocument;
  const reportMigrationFailure = ({ status = 1, ...details }) => {
    const report = migrationReport({
      ...details,
      ok: false,
      sourcePath,
      destinationPath,
      sourceBytes,
      fromSchemaVersion: sourceDocument?.schema_version,
    });
    if (options.json) console.log(JSON.stringify(report, null, 2));
    else console.error(formatDiagnostics(report.error, report.diagnostics));
    process.exitCode = status;
  };
  try {
    sourceBytes = fs.readFileSync(sourcePath);
    sourceDocument = JSON.parse(sourceBytes.toString('utf8'));
  } catch (error) {
    reportMigrationFailure({
      preExistingDiagnostics: [inputDiagnostic(error, sourcePath)],
    });
    return;
  }
  const { pathsAlias, validateAuthoredOutputPath } = await import('../renderers/shared/output-path.mjs');
  const {
    backupPublicRegularFileBinding,
    captureAtomicOutput,
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    releaseRegularFileBinding,
    verifyAtomicOutput,
    verifyRegularFileBinding,
  } = await import('../renderers/shared/atomic-output.mjs');
  // `--output` repairs only the durable output field in the migration
  // candidate. It never writes the source and deliberately leaves every
  // other schema and compiler failure visible to the normal migration path.
  let migrationSourceDocument = sourceDocument;
  if (options.output !== undefined) {
    try {
      validateAuthoredOutputPath(options.output);
    } catch (error) {
      reportMigrationFailure({
        preExistingDiagnostics: migrationPathDiagnostics(error, sourcePath, destinationPath),
      });
      return;
    }
    if (sourceDocument?.meta && typeof sourceDocument.meta === 'object' && !Array.isArray(sourceDocument.meta)) {
      migrationSourceDocument = {
        ...sourceDocument,
        meta: { ...sourceDocument.meta, output: options.output },
      };
    }
  }
  if (migrationSourceDocument?.meta?.output !== undefined) {
    try {
      validateAuthoredOutputPath(migrationSourceDocument.meta.output);
    } catch (error) {
      reportMigrationFailure({
        preExistingDiagnostics: migrationPathDiagnostics(error, sourcePath, destinationPath),
      });
      return;
    }
  }
  // Unlike render/validate, migrate has no --quality override. Pin every stage
  // to the document's durable policy and scrub any ambient profile from the
  // staged renderer by passing this value explicitly.
  const activeQualityProfile = migrationSourceDocument?.meta?.quality_profile || 'standard';

  let sourceDestinationAlias;
  try {
    sourceDestinationAlias = pathsAlias(sourcePath, destinationPath);
  } catch (error) {
    reportMigrationFailure({
      migrationDiagnostics: migrationPathDiagnostics(error, sourcePath, destinationPath),
    });
    return;
  }
  if (sourceDestinationAlias) {
    reportMigrationFailure({
      migrationDiagnostics: [diagnostic({
        code: 'migration/source-destination',
        message: 'Workflow migration source and destination must be different files.',
        subject: { source: sourcePath, destination: destinationPath },
        supportedFixes: ['choose a different destination path and keep the source unchanged'],
      })],
    });
    return;
  }

  const { migrateWorkflowDocument, serializeMigratedWorkflow } = await import('../migrations/workflow-v2.mjs');
  let migration;
  try {
    migration = migrateWorkflowDocument(migrationSourceDocument);
  } catch (error) {
    migration = {
      ok: false,
      migrationDiagnostics: [diagnostic({
        code: 'migration/internal',
        message: 'Workflow migration failed unexpectedly.',
        evidence: { reason: error.message },
        supportedFixes: ['report the source workflow and this diagnostic to the Archify maintainers'],
      })],
    };
  }

  if (!migration.ok) {
    reportMigrationFailure(migration);
    return;
  }

  const destinationDirectory = path.dirname(destinationPath);
  let stagingDirectory;
  let stagingIdentity;
  let destinationCapture;
  try {
    fs.mkdirSync(destinationDirectory, { recursive: true });
    destinationCapture = captureAtomicOutput(destinationPath, {
      requestedEntryPolicy: 'regular-or-absent',
    });
    if (destinationCapture.status !== 'captured') {
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/destination-type',
          message: 'Workflow migration destination must be an absent or stable regular file path.',
          subject: { destination: destinationPath },
          evidence: { targetState: destinationCapture.reason },
          supportedFixes: ['choose a destination path that is absent or names one non-hardlinked regular file'],
        })],
      });
      return;
    }
    const staging = createOwnedEmptyStagingDirectory(
      path.join(destinationDirectory, '.archify-migration-'),
    );
    stagingDirectory = staging.directory;
    stagingIdentity = staging.identity;
  } catch (error) {
    reportMigrationFailure({
      ...migration,
      migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
        code: 'migration/prepare-destination',
        message: 'Could not prepare the workflow migration destination.',
        subject: { destination: destinationPath },
        evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
        supportedFixes: ['choose a writable destination directory'],
      })],
    });
    return;
  }

  const candidatePath = path.join(stagingDirectory, 'candidate.workflow.json');
  const artifactPath = path.join(stagingDirectory, 'migration-check.html');
  const destinationBytes = Buffer.from(serializeMigratedWorkflow(migration.document));
  let candidateBinding = null;
  let previousDestinationBinding = null;
  let preserveRecoveryDirectory = false;
  const fileBindingRuntime = {
    captureRegularFileBinding,
    quarantineRemoveRegularFileBinding,
    releaseRegularFileBinding,
  };
  const stagingOwnership = [];
  try {
    fs.writeFileSync(candidatePath, destinationBytes, { flag: 'wx' });
    if (destinationCapture.mode !== null) fs.chmodSync(candidatePath, destinationCapture.mode);
    const candidateCapture = captureOwnedStagingFile(
      stagingOwnership,
      candidatePath,
      fileBindingRuntime,
      {
        subject: 'migration-candidate',
        content: artifactIdentity(destinationBytes),
      },
    );
    candidateBinding = candidateCapture.binding;
    const render = runNode([rendererPath('workflow'), candidatePath, artifactPath], {
      stdio: 'pipe',
      env: rendererEnv(activeQualityProfile, repoArgs.repoRoot, true),
    });
    if (render.status !== 0) {
      const failure = rendererFailure(render);
      reportMigrationFailure({
        ...migration,
        newSchemaDiagnostics: [...migration.newSchemaDiagnostics, ...failure.diagnostics],
        status: render.status ?? 1,
      });
      return;
    }
    const migrationArtifact = fs.readFileSync(artifactPath);
    captureOwnedStagingFile(stagingOwnership, artifactPath, fileBindingRuntime, {
      subject: 'migration-check-artifact',
      content: artifactIdentity(migrationArtifact),
    });

    const checkMaxBuffer = artifactCheckMaxBuffer();
    const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), artifactPath], {
      stdio: 'pipe',
      maxBuffer: checkMaxBuffer,
    });
    if (check.status !== 0) {
      const outputLimit = checkerOutputLimitDiagnostics(check, checkMaxBuffer);
      if (outputLimit) {
        reportMigrationFailure({
          ...migration,
          newSchemaDiagnostics: [
            ...migration.newSchemaDiagnostics,
            ...outputLimit,
          ],
          status: check.status ?? 1,
        });
        return;
      }
      let checker;
      try {
        checker = JSON.parse(check.stdout);
      } catch {
        checker = null;
      }
      reportMigrationFailure({
        ...migration,
        newSchemaDiagnostics: [
          ...migration.newSchemaDiagnostics,
          ...checkerDiagnostics(checker),
        ],
        status: check.status ?? 1,
      });
      return;
    }

    if (pathsAlias(sourcePath, destinationPath)) {
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/source-destination',
          message: 'Workflow migration source and destination resolved to the same file before commit.',
          subject: { source: sourcePath, destination: destinationPath },
          supportedFixes: ['choose a different destination path and retry'],
        })],
      });
      return;
    }
    const currentSourceBytes = fs.readFileSync(sourcePath);
    if (!currentSourceBytes.equals(sourceBytes)) {
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/source-changed',
          message: 'Workflow migration source changed while the destination was being verified.',
          subject: { source: sourcePath },
          supportedFixes: ['retry the migration from a stable workflow source file'],
        })],
      });
      return;
    }

    const candidateVerification = verifyRegularFileBinding(candidateBinding, { expectedLinks: 1 });
    if (candidateVerification.status !== 'match') {
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/candidate-changed',
          message: 'Workflow migration candidate changed before the destination commit.',
          subject: { destination: destinationPath },
          evidence: { candidateState: candidateVerification.reason },
          supportedFixes: ['retry the migration from a stable workflow source and destination'],
        })],
      });
      return;
    }

    const destinationVerification = verifyAtomicOutput(destinationCapture.snapshot);
    if (destinationVerification.status !== 'match') {
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/destination-changed',
          message: 'Workflow migration destination changed while the candidate was being verified.',
          subject: { destination: destinationPath },
          evidence: { targetState: destinationVerification.reason },
          supportedFixes: ['retry only after other processes stop creating, replacing, or redirecting the destination'],
        })],
      });
      return;
    }
    const backupPath = path.join(stagingDirectory, '.previous-destination');
    let backupPresent = false;
    if (destinationCapture.snapshot.target.kind === 'file') {
      const expected = destinationCapture.snapshot.target;
      const previousCapture = captureRegularFileBinding(destinationCapture.commitPath, {
        subject: 'previous-migration-destination',
        expectedIdentity: { device: expected.device, inode: expected.inode },
        expectedMode: expected.mode,
        expectedLinks: 1,
      });
      if (previousCapture.status !== 'captured') {
        reportMigrationFailure({
          ...migration,
          migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
            code: 'migration/destination-changed',
            message: 'Workflow migration destination changed before publication.',
            subject: { destination: destinationPath },
            evidence: { targetState: previousCapture.reason },
            supportedFixes: ['retry only after other processes stop changing the destination'],
          })],
        });
        return;
      }
      previousDestinationBinding = previousCapture.binding;
      const backedUp = backupPublicRegularFileBinding(
        previousDestinationBinding,
        destinationCapture.commitPath,
        backupPath,
        { subject: 'previous-migration-destination' },
      );
      backupPresent = backedUp.backupCreated === true;
      if (backedUp.status !== 'backed-up') {
        preserveRecoveryDirectory = backupPresent || backedUp.status === 'recovery-required';
        reportMigrationFailure({
          ...migration,
          migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
            code: 'migration/destination-changed',
            message: 'Workflow migration destination changed while its previous value was being preserved.',
            subject: { destination: destinationPath },
            evidence: {
              targetState: backedUp.reason,
              ...(backedUp.recoveryFile ? { recoveryFile: backedUp.recoveryFile } : {}),
            },
            supportedFixes: ['inspect the retained recovery entry before retrying'],
          })],
        });
        return;
      }
    }

    const candidateBeforePublish = verifyRegularFileBinding(candidateBinding, {
      filePath: candidatePath,
      expectedLinks: 1,
    });
    if (candidateBeforePublish.status !== 'match') {
      preserveRecoveryDirectory = backupPresent;
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/candidate-changed',
          message: 'Workflow migration candidate changed before publication.',
          subject: { destination: destinationPath },
          evidence: { candidateState: candidateBeforePublish.reason },
          supportedFixes: ['inspect any retained previous destination, then retry'],
        })],
      });
      return;
    }
    try {
      fs.linkSync(candidatePath, destinationCapture.commitPath);
    } catch (error) {
      preserveRecoveryDirectory = backupPresent;
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/destination-changed',
          message: 'Workflow migration destination was claimed during publication.',
          subject: { destination: destinationPath },
          evidence: {
            ...(error?.code ? { systemCode: error.code } : {}),
            ...(backupPresent ? { recoveryFile: backupPath } : {}),
          },
          supportedFixes: backupPresent
            ? ['preserve the claimant and inspect the retained previous destination before retrying']
            : ['preserve the claimant and retry with a different destination'],
        })],
      });
      return;
    }
    const published = verifyRegularFileBinding(candidateBinding, {
      filePath: destinationCapture.commitPath,
      expectedLinks: 2,
    });
    if (published.status !== 'match') {
      preserveRecoveryDirectory = backupPresent;
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/destination-changed',
          message: 'Workflow migration destination changed during publication.',
          subject: { destination: destinationPath },
          evidence: { targetState: published.reason },
          supportedFixes: ['preserve the current claimant and inspect any retained recovery entry'],
        })],
      });
      return;
    }
    const removedCandidate = quarantineRemoveRegularFileBinding(candidateBinding, candidatePath, {
      subject: 'migration-candidate',
      expectedLinks: 2,
    });
    if (removedCandidate.status !== 'removed') {
      preserveRecoveryDirectory = backupPresent || removedCandidate.status === 'recovery-required';
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/candidate-changed',
          message: 'Workflow migration candidate changed while publication was finalized.',
          subject: { destination: destinationPath },
          evidence: { candidateState: removedCandidate.reason },
          supportedFixes: ['preserve the candidate claimant and inspect the published destination'],
        })],
      });
      return;
    }
    const finalized = verifyRegularFileBinding(candidateBinding, {
      filePath: destinationCapture.commitPath,
      expectedLinks: 1,
    });
    if (finalized.status !== 'match') {
      preserveRecoveryDirectory = backupPresent;
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/destination-changed',
          message: 'Published workflow migration changed before final verification.',
          subject: { destination: destinationPath },
          evidence: { targetState: finalized.reason },
          supportedFixes: ['preserve the current claimant and inspect any retained recovery entry'],
        })],
      });
      return;
    }
    if (backupPresent) {
      const removedBackup = quarantineRemoveRegularFileBinding(
        previousDestinationBinding,
        backupPath,
        { subject: 'previous-migration-destination', expectedLinks: 1 },
      );
      if (removedBackup.status === 'removed') backupPresent = false;
    }
    const finalPublishedState = verifyRegularFileBinding(candidateBinding, {
      filePath: destinationCapture.commitPath,
      expectedLinks: 1,
    });
    if (finalPublishedState.status !== 'match') {
      preserveRecoveryDirectory = backupPresent;
      reportMigrationFailure({
        ...migration,
        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
          code: 'migration/destination-changed',
          message: 'Published workflow migration did not remain stable through finalization.',
          subject: { destination: destinationPath },
          evidence: { targetState: finalPublishedState.reason },
          supportedFixes: ['preserve the current destination and inspect any retained recovery entry'],
        })],
      });
      return;
    }
    const report = migrationReport({
      ...migration,
      sourcePath,
      destinationPath,
      sourceBytes,
      destinationBytes,
      fromSchemaVersion: sourceDocument.schema_version,
    });
    if (options.json) console.log(JSON.stringify(report, null, 2));
    else if (sourceDocument.schema_version === 1) {
      console.log(`migrated workflow schema v1→v2: ${sourcePath} → ${destinationPath}`);
    } else {
      console.log(`verified workflow schema v2 migration: ${sourcePath} → ${destinationPath}`);
    }
  } catch (error) {
    const migrationDiagnostics = Array.isArray(error?.archifyDiagnostics)
      ? migrationPathDiagnostics(error, sourcePath, destinationPath)
      : [diagnostic({
        code: 'migration/commit',
        message: 'Could not commit the verified workflow migration.',
        subject: { destination: destinationPath },
        evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
        supportedFixes: ['choose a writable regular-file destination and retry'],
      })];
    reportMigrationFailure({
      ...migration,
      migrationDiagnostics: [...migration.migrationDiagnostics, ...migrationDiagnostics],
    });
  } finally {
    if (previousDestinationBinding) releaseRegularFileBinding(previousDestinationBinding);
    try {
      if (preserveRecoveryDirectory) {
        releaseOwnedStagingBindings(stagingOwnership, fileBindingRuntime);
      } else {
        cleanupOwnedStagingDirectory(
          stagingDirectory,
          stagingIdentity,
          stagingOwnership,
          fileBindingRuntime,
        );
      }
    } catch (error) {
      console.error(`Warning: could not remove workflow migration staging directory "${stagingDirectory}": ${error.message}`);
    }
  }
}

// `inspect` delegates here in layout-JSON mode, so argument failures must be
// attributed to the command the caller actually invoked.
async function commandValidate(args, invocation = {}) {
  const invokingCommand = invocation.command || 'validate';
  const reportFailure = (options) => reportArtifactFailure({ ...options, command: invokingCommand });
  const qualityArgs = extractQualityArgs(args);
  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
  const writingArgs = extractExplainerWritingArgs(repoArgs.rest);
  repoArgs.rest = writingArgs.rest;
  args = repoArgs.rest;
  const quality = qualityArgs.quality;
  const repoRoot = repoArgs.repoRoot;
  const knownOptions = new Set(['--json', '--layout-json']);
  const unknown = args.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
  if (unknown.length) rejectCliArgument(`Unknown ${invokingCommand} option "${unknown[0]}".`, {
    code: 'cli/unknown-option',
    subject: { option: unknown[0] },
    supportedFixes: ['remove the unknown option and retry'],
  });
  const json = args.includes('--json');
  const layoutJson = args.includes('--layout-json');
  const rest = args.filter((arg) => !knownOptions.has(arg));
  const [type, input] = rest;
  if (!type || !input || rest.length !== 2) rejectCliArgument(usage(), {
    code: 'cli/usage',
    supportedFixes: [`use: archify ${invokingCommand} <type> <input.json> [options]`],
  });
  const renderer = rendererPath(type);

  if (layoutJson && !['architecture', 'workflow'].includes(type)) {
    rejectCliArgument('--layout-json is currently supported for architecture and workflow diagrams only.', {
      code: 'cli/unsupported-option',
      subject: { option: '--layout-json', type },
      supportedFixes: ['remove --layout-json or use an architecture or workflow diagram'],
    });
  }

  const inputPath = path.resolve(input);
  let specification;
  let explainerBundle;
  try {
    specification = fs.readFileSync(inputPath);
    if (type === 'explainer') explainerBundle = await prepareExplainerInput(specification, inputPath, { repoRoot, quality, writingMode: writingArgs.writingMode });
    const document = explainerBundle?.document || JSON.parse(specification.toString('utf8'));
    const [{ validateAuthoredOutputPath }, { validateSchema }] = await Promise.all([
      import('../renderers/shared/output-path.mjs'),
      import('../renderers/shared/validator.mjs'),
    ]);
    if (document?.meta?.output !== undefined) validateAuthoredOutputPath(document.meta.output);
    else if (type !== 'explainer') validateSchema(type, document);
  } catch (error) {
    const diagnostics = error.archifyDiagnostics || [inputDiagnostic(error, inputPath)];
    reportFailure({
      json,
      stage: diagnostics.some((entry) => entry.code.startsWith('input/')) ? 'input' : 'render',
      type,
      input: inputPath,
      error: error.message,
      diagnostics,
      status: 1,
    });
    return;
  }

  if (layoutJson) {
    // Layout mode emits JSON without writing HTML; keep its unused target typed.
    const layoutOutput = path.join(os.tmpdir(), `archify-layout-${process.pid}-${type}.html`);
    const result = runNode([renderer, input, layoutOutput, '--layout-json'], {
      stdio: 'pipe',
      env: rendererEnv(quality, repoRoot, true),
    });
    if (result.status !== 0) {
      if (!result.error) {
        try {
          const receipt = JSON.parse(result.stdout);
          if (receipt?.contract && Array.isArray(receipt.diagnostics)) {
            process.stdout.write(`${JSON.stringify(receipt, null, 2)}\n`);
            process.exitCode = result.status ?? 1;
            return;
          }
        } catch {
          // Fall through to the renderer failure contract when no compiler
          // receipt was produced (for example, input JSON could not be read).
        }
      }
      const failure = rendererFailure(result);
      reportFailure({
        json,
        stage: failure.diagnostics.some((entry) => entry.code.startsWith('input/')) ? 'input' : 'render',
        type,
        input: path.resolve(input),
        error: failure.error,
        diagnostics: failure.diagnostics,
        status: result.status ?? 1,
      });
      return;
    }
    process.stdout.write(result.stdout);
    return;
  }

  const { createOwnedTempDirectory } = await import('../renderers/shared/owned-temp-directory.mjs');
  const temporary = createOwnedTempDirectory('archify-validate-');
  const tmp = temporary.path;
  const out = path.join(tmp, `${type}.html`);
  let exitCode = 0;
  let report = () => {};

  try {
    const snapshot = path.join(tmp, 'specification.snapshot.json');
    fs.writeFileSync(snapshot, specification, { flag: 'wx' });
    let preparedBundlePath;
    if (explainerBundle) {
      const { writePreparedBundle } = await import('../explainer/prepare.mjs');
      preparedBundlePath = writePreparedBundle(tmp, explainerBundle);
    }
    const render = runNode([renderer, snapshot, out], {
      stdio: 'pipe',
      env: { ...rendererEnv(quality, repoRoot, true), ...(preparedBundlePath ? { ARCHIFY_EXPLAINER_PREPARED: preparedBundlePath, ARCHIFY_EXPLAINER_SNAPSHOT_INPUT: inputPath } : {}) },
    });
    if (render.status !== 0) {
      const failure = rendererFailure(render);
      report = () => reportFailure({
        json,
        stage: failure.diagnostics.some((entry) => entry.code.startsWith('input/')) ? 'input' : 'render',
        type,
        input: path.resolve(input),
        error: failure.error,
        diagnostics: failure.diagnostics,
        status: render.status ?? 1,
      });
      exitCode = render.status ?? 1;
    } else {
      if (render.stderr) process.stderr.write(render.stderr);
      const localeWarnings = [...await specificationLocaleDiagnostics(type, specification), ...(explainerBundle?.diagnostics.filter(entry => entry.severity === 'warning') || [])];
      for (const warning of localeWarnings) process.stderr.write(`archify: ${warning.message}\n`);
      const checkMaxBuffer = artifactCheckMaxBuffer();
      const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), out], {
        stdio: 'pipe',
        maxBuffer: checkMaxBuffer,
      });
      if (check.status !== 0) {
        exitCode = check.status ?? 1;
        const outputLimit = checkerOutputLimitDiagnostics(check, checkMaxBuffer);
        if (outputLimit) {
          report = () => reportFailure({
            json,
            stage: 'check',
            type,
            input: path.resolve(input),
            error: `The artifact checker exceeded its ${checkMaxBuffer} byte output buffer and was terminated before reporting a verdict.`,
            diagnostics: outputLimit,
            status: check.status ?? 1,
          });
        } else {
          let checker;
          try {
            checker = JSON.parse(check.stdout);
            checker.file = path.resolve(input);
          } catch {
            checker = { ok: false, diagnostic: 'Artifact checker failed without a parseable receipt.' };
          }
          report = () => reportFailure({
            json,
            stage: 'check',
            type,
            input: path.resolve(input),
            error: 'Final artifact check failed.',
            diagnostics: checkerDiagnostics(checker),
            checker,
            status: check.status ?? 1,
          });
        }
      } else {
        const result = JSON.parse(check.stdout);
        const engineeringProfile = engineeringProfileFromArtifact(fs.readFileSync(out));
        if (json) {
          const candidate = {
            path: path.resolve(input),
            ...artifactIdentity(specification),
          };
          const resolvedQuality = quality || result.composition.profile || 'standard';
          const receipt = {
            schemaVersion: 1,
            ok: true,
            command: 'validate',
            type,
            input: candidate.path,
            candidate,
            candidateFrozen: true,
            nextAction: {
              command: 'finalize',
              arguments: [
                type,
                candidate.path,
                '<output.html>',
                '--quality',
                resolvedQuality,
                ...(repoRoot ? ['--repo-root', repoRoot] : []),
                '--candidate-sha256',
                candidate.sha256,
                '--json',
              ],
            },
            checks: result.checks,
            composition: result.composition,
            ...(engineeringProfile ? { engineeringProfile } : {}),
            ...(localeWarnings.length ? { diagnostics: localeWarnings } : {}),
          };
          report = () => console.log(JSON.stringify(receipt, null, 2));
        } else {
          const engineering = engineeringProfile
            ? `; engineering ${engineeringProfile}: pass`
            : '';
          report = () => console.log(`ok ${type} ${path.resolve(input)} (${result.checks.length} artifact checks; composition ${result.composition.profile}: ${result.composition.summary.errors} errors, ${result.composition.summary.warnings} warnings${engineering})`);
        }
      }
    }
  } finally {
    try {
      await temporary.cleanup();
    } catch (error) {
      exitCode = 1;
      report = () => reportFailure({
        json,
        stage: 'cleanup',
        type,
        input: path.resolve(input),
        error: error.message,
        diagnostics: [{
          code: 'validate/temp-cleanup-incomplete',
          severity: 'error',
          message: error.message,
          subject: { directory: tmp },
          evidence: { reason: error.cause?.code || error.code },
          supportedFixes: ['resolve the reported filesystem error and inspect the retained temporary directory before retrying'],
        }],
        status: 1,
      });
    }
  }

  report();
  if (exitCode !== 0) process.exitCode = exitCode;
}

const [command, ...args] = process.argv.slice(2);
// Reuse the canonical help metadata rather than a separate help registry.
// Only the sole --help form bypasses command argument parsing and operations.
const soleCommandHelp = args.length === 1 && args[0] === '--help'
  && Object.hasOwn(COMMAND_USAGE, command);

try {
  switch (soleCommandHelp ? '--help' : command) {
    case undefined:
    case '-h':
    case '--help':
    case 'help':
      console.log(usage());
      break;
    case 'render':
      commandRender(args);
      break;
    case 'compare':
      await commandCompare(args);
      break;
    case 'deliver':
      await commandDeliver(args);
      break;
    case 'patch':
      await commandPatch(args);
      break;
    case 'finalize':
      await commandFinalize(args);
      break;
    case 'preview':
      await commandPreview(args);
      break;
    case 'validate':
      await commandValidate(args);
      break;
    case 'migrate':
      await commandMigrate(args);
      break;
    case 'inspect':
      if (args[0] !== 'architecture') {
        rejectCliArgument('inspect is currently supported for architecture diagrams only.', {
          code: 'cli/unsupported-option',
          subject: { command: 'inspect', type: args[0] },
          supportedFixes: ['use an architecture diagram', 'use validate <type> <input.json> --layout-json for workflow diagrams'],
        });
      }
      await commandValidate([...args, '--layout-json'], { command: 'inspect' });
      break;
    case 'check':
      await commandCheck(args);
      break;
    case 'visual-check':
      await commandVisualCheck(args);
      break;
    case 'browser-check':
      await commandBrowserCheck(args);
      break;
    case 'guide':
      await commandGuide(args);
      break;
    case 'brands':
      await commandBrands(args);
      break;
    case 'examples':
      commandExamples(args);
      break;
    case 'doctor':
      await commandDoctor(args);
      break;
    case 'demo':
      commandDemo(args);
      break;
    default:
      fail(`Unknown command "${command}".\n\n${usage()}`);
  }
} catch (error) {
  if (!error.archifyArgument) throw error;
  if (['validate', 'deliver', 'finalize', 'inspect', 'patch'].includes(command) && args.includes('--json')) {
    reportArtifactArgumentFailure(command, error);
  } else {
    fail(error.message);
  }
}
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall