#!/usr/bin/env node

import crypto from 'node:crypto';
import { constants as fsConstants } from 'node:fs';
import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { performance } from 'node:perf_hooks';
import { fileURLToPath } from 'node:url';

import {
  DEFAULT_MANIFEST_URL,
  SKILL_ID,
  UpdateContractError,
  compareSemver,
  isStableCoreVersion,
  parseSemver,
  validateLocalRelease,
  validateReleaseNotesUrl,
  validateStableUpdateManifest,
} from './update-contract.mjs';

const OPERATION_STATE_FILE = 'state.json';
const OPERATION_OWNER_FILE = 'owner.json';
const ACTIVE_CLAIM_DIRECTORY = 'active-claim';
const OPERATION_NAME = /^(reserved|pending|committed|fenced|cancelled)-(\d{1,20})$/;
const MAX_OPERATION_GENERATION = (10n ** 20n) - 1n;
const CHECK_TTL_MS = 72 * 60 * 60 * 1_000;
const MAX_CACHE_HORIZON_MS = Math.ceil(CHECK_TTL_MS * 1.2);
const FIRST_FAILURE_DELAY_MS = 6 * 60 * 60 * 1_000;
const LATER_FAILURE_DELAY_MS = 24 * 60 * 60 * 1_000;
const DEFAULT_TIMEOUT_MS = 1_000;
const MAX_RESPONSE_BYTES = 32 * 1_024;
const MAX_LOCAL_RELEASE_BYTES = 4 * 1_024;
const MAX_CACHE_STATE_BYTES = 64 * 1_024;
const MAX_CLAIM_OWNER_BYTES = 1_024;
const LONGEST_ISO_TIMESTAMP = '+275760-09-13T00:00:00.000Z';
const LOCK_STALE_MS = 30_000;
const ACK_LOCK_WAIT_MS = 1_200;
const LOCK_RETRY_DELAY_MS = 20;
const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
const defaultReleasePath = path.resolve(scriptDirectory, '..', 'skill-release.json');

class FileIdentityChangedError extends Error {}

function silent(reason) {
  return { status: 'silent', reason };
}

function isPlainObject(value) {
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
}

function hasOnlyKeys(value, allowed) {
  return Object.keys(value).every((key) => allowed.has(key));
}

function validateManifest(value) {
  const manifest = validateStableUpdateManifest(value);
  return {
    version: manifest.version,
    targetDigest: `sha256:${manifest.artifact.sha256}`,
    severity: manifest.severity,
    releaseNotes: manifest.releaseNotes,
  };
}

function validateCachedCandidate(value) {
  if (!isPlainObject(value)
    || !hasOnlyKeys(value, new Set([
      'version', 'targetDigest', 'severity', 'releaseNotes',
    ]))) return null;
  try {
    if (!isStableCoreVersion(value.version)) return null;
    if (!DIGEST_PATTERN.test(value.targetDigest)
      || !['normal', 'security'].includes(value.severity)) return null;
    validateReleaseNotesUrl(value.releaseNotes, value.version);
    return { ...value };
  } catch {
    return null;
  }
}

function emptyState(installedVersion = null) {
  return {
    schemaVersion: 1,
    skillId: SKILL_ID,
    installedVersion,
    check: {
      nextCheckAt: null,
      consecutiveFailures: 0,
    },
    notification: {
      offeredDigests: [],
      acknowledgedDigests: [],
    },
  };
}

function encodeBoundedState(state) {
  const encoded = Buffer.from(`${JSON.stringify(state)}\n`, 'utf8');
  return encoded.length <= MAX_CACHE_STATE_BYTES ? encoded : null;
}

function stateAfterAcknowledgement(state, targetDigest) {
  const alreadyAcknowledged = state.notification.acknowledgedDigests.includes(targetDigest);
  return {
    ...state,
    notification: {
      offeredDigests: state.notification.offeredDigests
        .filter((digest) => digest !== targetDigest),
      acknowledgedDigests: alreadyAcknowledged
        ? [...state.notification.acknowledgedDigests]
        : [...state.notification.acknowledgedDigests, targetDigest],
    },
  };
}

function stateWithFailureCheck(state, nextCheckAt, consecutiveFailures, withdrawCandidate = false) {
  const failedState = {
    ...state,
    check: { nextCheckAt, consecutiveFailures },
  };
  if (withdrawCandidate) delete failedState.candidate;
  return failedState;
}

function encodeRecoverableState(state) {
  const encoded = encodeBoundedState(state);
  if (!encoded) return null;
  if (!encodeBoundedState(stateWithFailureCheck(state, LONGEST_ISO_TIMESTAMP, 2))) return null;
  let acknowledgementState = state;
  for (const targetDigest of state.notification.offeredDigests) {
    acknowledgementState = stateAfterAcknowledgement(acknowledgementState, targetDigest);
    if (!encodeBoundedState(acknowledgementState)
      || !encodeBoundedState(stateWithFailureCheck(
        acknowledgementState,
        LONGEST_ISO_TIMESTAMP,
        2,
      ))) return null;
  }
  return encoded;
}

function versionCacheDirectory(cacheDirectory, installedVersion) {
  const partition = crypto.createHash('sha256').update(installedVersion).digest('hex').slice(0, 24);
  return path.join(cacheDirectory, `version-${partition}`);
}

function normalizeState(value, installedVersion) {
  const effectiveInstalledVersion = installedVersion ?? value?.installedVersion ?? null;
  if (!isPlainObject(value) || value.schemaVersion !== 1 || value.skillId !== SKILL_ID
    || (installedVersion !== null && value.installedVersion !== installedVersion)
    || (value.installedVersion !== null && typeof value.installedVersion !== 'string')
    || !isPlainObject(value.check)
    || !(value.check.nextCheckAt === null || typeof value.check.nextCheckAt === 'string')
    || !Number.isSafeInteger(value.check.consecutiveFailures)
    || value.check.consecutiveFailures < 0
    || !isPlainObject(value.notification)) return null;
  if (effectiveInstalledVersion !== null) {
    try {
      parseSemver(effectiveInstalledVersion);
    } catch {
      return null;
    }
  }

  const state = emptyState(effectiveInstalledVersion);
  state.check.nextCheckAt = value.check.nextCheckAt;
  state.check.consecutiveFailures = value.check.consecutiveFailures;
  const { offeredDigests, acknowledgedDigests } = value.notification;
  if (!Array.isArray(offeredDigests)
    || offeredDigests.some((digest) => typeof digest !== 'string' || !DIGEST_PATTERN.test(digest))) {
    return null;
  }
  state.notification.offeredDigests = [...new Set(offeredDigests)];

  if (!Array.isArray(acknowledgedDigests)
    || acknowledgedDigests.some((digest) => typeof digest !== 'string' || !DIGEST_PATTERN.test(digest))) {
    return null;
  }
  state.notification.acknowledgedDigests = [...new Set(acknowledgedDigests)];
  const hasCandidate = Object.hasOwn(value, 'candidate');
  const candidate = validateCachedCandidate(value.candidate);
  if (hasCandidate && !candidate) return null;
  if (candidate) {
    if (effectiveInstalledVersion !== null
      && compareSemver(candidate.version, effectiveInstalledVersion) > 0
      && !state.notification.offeredDigests.includes(candidate.targetDigest)
      && !state.notification.acknowledgedDigests.includes(candidate.targetDigest)) return null;
    state.candidate = candidate;
  }
  return encodeRecoverableState(state) ? state : null;
}

function isSameFile(left, right) {
  if (left.dev !== right.dev || left.ino !== right.ino) return false;
  if (left.ino !== 0n) return true;
  if (left.birthtimeNs === 0n || right.birthtimeNs === 0n) return false;
  return left.birthtimeNs === right.birthtimeNs
    && left.mode === right.mode;
}

function assertBoundedRegularFile(metadata, maxBytes) {
  if (!metadata.isFile()
    || metadata.isSymbolicLink()
    || metadata.size > BigInt(maxBytes)) {
    throw new Error('unsafe JSON file');
  }
}

async function readJsonFile(target, maxBytes, expectedMetadata = null) {
  const pathMetadata = await fs.lstat(target, { bigint: true });
  if (expectedMetadata && !isSameFile(expectedMetadata, pathMetadata)) {
    throw new FileIdentityChangedError('JSON file identity changed');
  }
  assertBoundedRegularFile(pathMetadata, maxBytes);
  const flags = fsConstants.O_RDONLY
    | (fsConstants.O_NOFOLLOW ?? 0)
    | (fsConstants.O_NONBLOCK ?? 0);
  const handle = await fs.open(target, flags);
  try {
    const handleMetadata = await handle.stat({ bigint: true });
    const currentPathMetadata = await fs.lstat(target, { bigint: true });
    assertBoundedRegularFile(handleMetadata, maxBytes);
    assertBoundedRegularFile(currentPathMetadata, maxBytes);
    if (!isSameFile(pathMetadata, handleMetadata)
      || !isSameFile(currentPathMetadata, handleMetadata)) {
      throw new FileIdentityChangedError('JSON file changed while opening');
    }

    const chunks = [];
    let size = 0;
    while (size <= maxBytes) {
      const chunk = Buffer.allocUnsafe(Math.min(8 * 1_024, (maxBytes + 1) - size));
      const { bytesRead } = await handle.read(chunk, 0, chunk.length, size);
      if (bytesRead === 0) break;
      chunks.push(chunk.subarray(0, bytesRead));
      size += bytesRead;
    }
    if (size > maxBytes) throw new Error('JSON file is too large');
    return JSON.parse(Buffer.concat(chunks, size).toString('utf8'));
  } finally {
    await handle.close();
  }
}

function isWithinDirectory(directory, target) {
  const relative = path.relative(directory, target);
  return relative === ''
    || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
}

async function canonicalizeTrustedDirectoryPrefix(target) {
  const absoluteTarget = path.resolve(target);
  const trustedDirectories = [...new Set([os.homedir(), os.tmpdir()].map((directory) => (
    path.resolve(directory)
  )))].sort((left, right) => right.length - left.length);
  for (const trustedDirectory of trustedDirectories) {
    if (!isWithinDirectory(trustedDirectory, absoluteTarget)) continue;
    try {
      const canonicalDirectory = await fs.realpath(trustedDirectory);
      return path.resolve(canonicalDirectory, path.relative(trustedDirectory, absoluteTarget));
    } catch {
      // Fall back to validating the absolute path from its filesystem root.
    }
  }
  return target;
}

function assertSafeDirectory(metadata) {
  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
    throw new Error('unsafe cache directory');
  }
}

class CachePathChangedError extends Error {}
class CacheOperationRaceError extends Error {}
class OperationFencedError extends Error {}

const preparedCacheDirectories = new Map();

function invalidateCacheToken(token, message, cause) {
  token.trusted = false;
  if (cause instanceof CachePathChangedError) return cause;
  const error = new CachePathChangedError(message);
  if (cause) error.cause = cause;
  return error;
}

async function verifyDirectorySnapshots(token, snapshots, description) {
  if (!token.trusted) throw new CachePathChangedError('cache directory is no longer trusted');
  try {
    for (const snapshot of snapshots) {
      const metadata = await fs.lstat(snapshot.directory, { bigint: true });
      assertSafeDirectory(metadata);
      if (!isSameFile(snapshot.metadata, metadata)) {
        throw new Error(`${description} changed`);
      }
    }
  } catch (error) {
    throw invalidateCacheToken(token, `${description} changed`, error);
  }
}

async function verifyCacheToken(token) {
  await verifyDirectorySnapshots(token, token.ancestorSnapshots, 'cache directory');
}

async function guardedCacheRead(token, read) {
  await verifyCacheToken(token);
  let result;
  try {
    result = await read();
  } catch (error) {
    await verifyCacheToken(token);
    throw error;
  }
  await verifyCacheToken(token);
  return result;
}

function cacheTokenFor(cacheDirectory) {
  const token = preparedCacheDirectories.get(path.resolve(cacheDirectory));
  if (!token || !token.trusted) {
    throw new CachePathChangedError('cache directory has not been prepared safely');
  }
  return token;
}

function resolveCacheTarget(token, target) {
  const resolved = path.resolve(target);
  if (resolved === token.directory || !isWithinDirectory(token.directory, resolved)) {
    throw invalidateCacheToken(token, 'cache mutation escaped its prepared directory');
  }
  return resolved;
}

async function captureMutationParentSnapshots(token, targets) {
  await verifyCacheToken(token);
  const snapshots = new Map();
  try {
    for (const target of targets) {
      const parent = path.dirname(resolveCacheTarget(token, target));
      const relative = path.relative(token.directory, parent);
      let current = token.directory;
      for (const component of relative.split(path.sep).filter(Boolean)) {
        current = path.join(current, component);
        if (snapshots.has(current)) continue;
        const metadata = await fs.lstat(current, { bigint: true });
        assertSafeDirectory(metadata);
        snapshots.set(current, { directory: current, metadata });
      }
    }
  } catch (error) {
    throw invalidateCacheToken(token, 'cache mutation parent changed', error);
  }
  const captured = [...snapshots.values()];
  await verifyMutationParentSnapshots(token, captured);
  await verifyCacheToken(token);
  return captured;
}

async function verifyMutationParentSnapshots(token, snapshots) {
  try {
    for (const snapshot of snapshots) {
      const metadata = await fs.lstat(snapshot.directory, { bigint: true });
      assertSafeDirectory(metadata);
      if (!isSameFile(snapshot.metadata, metadata)) {
        throw new Error('cache mutation parent changed');
      }
    }
  } catch (error) {
    const raced = new CacheOperationRaceError('cache mutation parent changed');
    raced.cause = error;
    throw raced;
  }
}

async function verifyMutationContext(token, parentSnapshots) {
  await verifyCacheToken(token);
  await verifyMutationParentSnapshots(token, parentSnapshots);
  await verifyCacheToken(token);
}

function assertSafeCacheEntry(metadata) {
  if (metadata.isSymbolicLink() || (!metadata.isDirectory() && !metadata.isFile())) {
    throw new Error('unsafe cache entry');
  }
}

function assertSafeRegularFile(metadata) {
  if (!metadata.isFile() || metadata.isSymbolicLink()) {
    throw new Error('unsafe cache file');
  }
}

function assertRenameableCacheEntry(metadata) {
  if (!metadata.isDirectory() && !metadata.isFile() && !metadata.isSymbolicLink()) {
    throw new Error('unsafe cache rename entry');
  }
}

async function stableCacheEntry(
  token,
  target,
  validate,
  expectedMetadata = null,
  missingIsOperationRace = false,
) {
  const resolved = resolveCacheTarget(token, target);
  try {
    const first = await fs.lstat(resolved, { bigint: true });
    validate(first);
    if (expectedMetadata && !isSameFile(expectedMetadata, first)) {
      throw new Error('cache entry identity changed');
    }
    await verifyCacheToken(token);
    const second = await fs.lstat(resolved, { bigint: true });
    validate(second);
    if (!isSameFile(first, second)
      || (expectedMetadata && !isSameFile(expectedMetadata, second))) {
      throw new Error('cache entry identity changed');
    }
    return second;
  } catch (error) {
    if (missingIsOperationRace && error?.code === 'ENOENT') {
      await verifyCacheToken(token);
      throw error;
    }
    throw invalidateCacheToken(token, 'cache mutation produced an untrusted object', error);
  }
}

async function guardedCacheEntryRead(
  token,
  target,
  validate,
  read,
  expectedMetadata = null,
) {
  const metadata = await stableCacheEntry(
    token,
    target,
    validate,
    expectedMetadata,
    true,
  );
  let result;
  try {
    result = await read(metadata);
  } catch (error) {
    await stableCacheEntry(token, target, validate, metadata, true);
    throw error;
  }
  await stableCacheEntry(token, target, validate, metadata, true);
  return result;
}

async function stablePreparedDirectory(token, target) {
  try {
    const first = await fs.lstat(target, { bigint: true });
    assertSafeDirectory(first);
    await verifyCacheToken(token);
    const second = await fs.lstat(target, { bigint: true });
    assertSafeDirectory(second);
    if (!isSameFile(first, second)) throw new Error('prepared directory identity changed');
    return second;
  } catch (error) {
    throw invalidateCacheToken(token, 'prepared directory could not be verified', error);
  }
}

async function assertCacheTargetAbsent(token, target) {
  const resolved = resolveCacheTarget(token, target);
  try {
    await fs.lstat(resolved, { bigint: true });
  } catch (error) {
    if (error?.code === 'ENOENT') return;
    throw invalidateCacheToken(token, 'cache mutation target could not be verified', error);
  }
  throw invalidateCacheToken(token, 'cache mutation left an unexpected object');
}

async function guardedCacheMutation(token, parentSnapshots, {
  mutate,
  verifyBefore = null,
  verifyAfter,
}) {
  await verifyMutationContext(token, parentSnapshots);
  if (verifyBefore) await verifyBefore();
  let result;
  try {
    result = await mutate();
  } catch (error) {
    await verifyMutationContext(token, parentSnapshots);
    throw error;
  }
  try {
    await verifyMutationContext(token, parentSnapshots);
    const verified = await verifyAfter(result);
    await verifyMutationContext(token, parentSnapshots);
    return verified ?? result;
  } catch (error) {
    if (error instanceof CacheOperationRaceError) throw error;
    throw invalidateCacheToken(token, 'cache mutation could not be verified', error);
  }
}

async function cacheMkdirWithToken(token, target, options, parentSnapshots = null) {
  const resolved = path.resolve(target);
  const parents = parentSnapshots ?? await captureMutationParentSnapshots(token, [resolved]);
  return guardedCacheMutation(token, parents, {
    mutate: () => fs.mkdir(resolved, options),
    verifyAfter: () => (parentSnapshots === null
      ? stableCacheEntry(token, resolved, assertSafeDirectory)
      : stablePreparedDirectory(token, resolved)),
  });
}

async function cacheMkdir(cacheDirectory, target, options) {
  return cacheMkdirWithToken(cacheTokenFor(cacheDirectory), target, options);
}

async function cacheWriteFile(cacheDirectory, target, data, options) {
  if (options?.flag !== 'wx') {
    throw new Error('cache files must be created exclusively');
  }
  const token = cacheTokenFor(cacheDirectory);
  const resolved = resolveCacheTarget(token, target);
  const parents = await captureMutationParentSnapshots(token, [resolved]);
  return guardedCacheMutation(token, parents, {
    mutate: async () => {
      const flags = fsConstants.O_WRONLY
        | fsConstants.O_CREAT
        | fsConstants.O_EXCL
        | (fsConstants.O_NOFOLLOW ?? 0);
      const handle = await fs.open(resolved, flags, options.mode);
      try {
        const openedMetadata = await handle.stat({ bigint: true });
        if (!openedMetadata.isFile() || openedMetadata.isSymbolicLink()) {
          throw new Error('cache write did not open a regular file');
        }
        await handle.writeFile(data, options.encoding ? { encoding: options.encoding } : undefined);
        const writtenMetadata = await handle.stat({ bigint: true });
        const expectedBytes = Buffer.isBuffer(data)
          ? data.length
          : Buffer.byteLength(data, options.encoding || 'utf8');
        if (!isSameFile(openedMetadata, writtenMetadata)
          || writtenMetadata.size !== BigInt(expectedBytes)) {
          throw new Error('cache write did not preserve the opened file identity and size');
        }
        return writtenMetadata;
      } finally {
        await handle.close();
      }
    },
    verifyAfter: (writtenMetadata) => stableCacheEntry(token, resolved, (metadata) => {
      if (!metadata.isFile() || metadata.isSymbolicLink()) {
        throw new Error('cache write did not create a regular file');
      }
    }, writtenMetadata),
  });
}

async function cacheRename(
  cacheDirectory,
  source,
  destination,
  validate,
  expectedSourceMetadata = null,
) {
  if (typeof validate !== 'function') {
    throw new TypeError('cache rename requires an explicit entry validator');
  }
  const token = cacheTokenFor(cacheDirectory);
  const resolvedSource = resolveCacheTarget(token, source);
  const resolvedDestination = resolveCacheTarget(token, destination);
  const parents = await captureMutationParentSnapshots(
    token,
    [resolvedSource, resolvedDestination],
  );
  const sourceMetadata = await stableCacheEntry(
    token,
    resolvedSource,
    validate,
    expectedSourceMetadata,
    true,
  );
  return guardedCacheMutation(token, parents, {
    verifyBefore: () => stableCacheEntry(
      token,
      resolvedSource,
      validate,
      sourceMetadata,
      true,
    ),
    mutate: () => fs.rename(resolvedSource, resolvedDestination),
    verifyAfter: async () => {
      await assertCacheTargetAbsent(token, resolvedSource);
      return stableCacheEntry(
        token,
        resolvedDestination,
        validate,
        sourceMetadata,
      );
    },
  });
}

async function cacheRm(cacheDirectory, target, options) {
  if (options?.recursive) {
    throw new Error('recursive cache removal is not allowed');
  }
  const token = cacheTokenFor(cacheDirectory);
  const resolved = resolveCacheTarget(token, target);
  const parents = await captureMutationParentSnapshots(token, [resolved]);
  let initialMetadata;
  try {
    initialMetadata = await fs.lstat(resolved, { bigint: true });
  } catch (error) {
    if (error?.code === 'ENOENT' && options?.force) {
      await verifyMutationContext(token, parents);
      return;
    }
    throw error;
  }
  try {
    assertSafeCacheEntry(initialMetadata);
  } catch (error) {
    throw invalidateCacheToken(token, 'cache removal target is unsafe', error);
  }
  const targetMetadata = await stableCacheEntry(
    token,
    resolved,
    assertSafeCacheEntry,
    initialMetadata,
  );
  return guardedCacheMutation(token, parents, {
    verifyBefore: () => stableCacheEntry(
      token,
      resolved,
      assertSafeCacheEntry,
      targetMetadata,
    ),
    mutate: () => fs.rm(resolved, options),
    verifyAfter: () => assertCacheTargetAbsent(token, resolved),
  });
}

async function prepareCacheDirectory(cacheDirectory) {
  const absoluteTarget = path.resolve(cacheDirectory);
  const target = await canonicalizeTrustedDirectoryPrefix(absoluteTarget);
  const parsed = path.parse(target);
  const components = target.slice(parsed.root.length).split(path.sep).filter(Boolean);
  let current = parsed.root;
  const token = {
    directory: target,
    ancestorSnapshots: [],
    trusted: true,
  };

  for (const component of components) {
    current = path.join(current, component);
    let metadata;
    try {
      metadata = await fs.lstat(current, { bigint: true });
    } catch (error) {
      if (error?.code !== 'ENOENT') throw error;
      try {
        await cacheMkdirWithToken(token, current, { mode: 0o700 }, []);
      } catch (mkdirError) {
        if (mkdirError?.code !== 'EEXIST') throw mkdirError;
      }
      metadata = await fs.lstat(current, { bigint: true });
    }
    assertSafeDirectory(metadata);
    token.ancestorSnapshots.push({ directory: current, metadata });
  }

  await verifyCacheToken(token);
  preparedCacheDirectories.set(target, token);
  return target;
}

function operationName(kind, generation) {
  return `${kind}-${generation.toString().padStart(20, '0')}`;
}

function parseOperationName(name) {
  const match = OPERATION_NAME.exec(name);
  if (!match) return null;
  return { kind: match[1], generation: BigInt(match[2]) };
}

async function listOperations(cacheDirectory, token = cacheTokenFor(cacheDirectory)) {
  return guardedCacheRead(token, async () => {
    try {
      const entries = await fs.readdir(cacheDirectory, { withFileTypes: true });
      return entries.flatMap((entry) => {
        const parsed = parseOperationName(entry.name);
        if (!parsed) return [];
        if (!entry.isDirectory() || entry.isSymbolicLink()) {
          throw invalidateCacheToken(
            token,
            `cache operation ${entry.name} is not a safe directory`,
          );
        }
        return [{ ...parsed, name: entry.name, directory: path.join(cacheDirectory, entry.name) }];
      });
    } catch (error) {
      if (error?.code === 'ENOENT') return [];
      throw error;
    }
  });
}

async function readState(cacheDirectory, installedVersion = null) {
  const token = cacheTokenFor(cacheDirectory);
  return guardedCacheRead(token, async () => {
    const operations = (await listOperations(cacheDirectory, token))
      .filter((operation) => operation.kind === 'committed')
      .sort((left, right) => (left.generation > right.generation ? -1 : 1));
    for (const operation of operations) {
      try {
        const state = await guardedCacheEntryRead(
          token,
          operation.directory,
          assertSafeDirectory,
          async () => normalizeState(
            await readJsonFile(
              path.join(operation.directory, OPERATION_STATE_FILE),
              MAX_CACHE_STATE_BYTES,
            ),
            installedVersion,
          ),
        );
        if (state) return state;
      } catch (error) {
        if (error instanceof FileIdentityChangedError
          || error instanceof CachePathChangedError
          || error instanceof CacheOperationRaceError) throw error;
        // An incomplete or corrupt generation is ignored in favor of the previous commit.
      }
    }
    return emptyState(installedVersion);
  });
}

async function operationIsActive(
  cacheDirectory,
  operation,
  token = cacheTokenFor(cacheDirectory),
) {
  try {
    return await guardedCacheEntryRead(
      token,
      operation.directory,
      assertSafeDirectory,
      async (directoryMetadata) => {
        try {
          const ownerMetadata = await fs.lstat(
            path.join(operation.directory, OPERATION_OWNER_FILE),
            { bigint: true },
          );
          if (!ownerMetadata.isFile() || ownerMetadata.isSymbolicLink()) return false;
          return metadataIsWithinLease(ownerMetadata);
        } catch (error) {
          if (error?.code !== 'ENOENT') throw error;
          return metadataIsWithinLease(directoryMetadata);
        }
      },
    );
  } catch (error) {
    if (error?.code === 'ENOENT') return false;
    throw error;
  }
}

function validateClaimOwner(value) {
  if (!isPlainObject(value)
    || !hasOnlyKeys(value, new Set(['pid', 'token', 'generation']))
    || !Number.isSafeInteger(value.pid)
    || value.pid <= 0
    || typeof value.token !== 'string'
    || !/^[a-f0-9]{32}$/.test(value.token)
    || typeof value.generation !== 'string'
    || !/^[1-9]\d*$/.test(value.generation)) return null;
  return { ...value, generation: BigInt(value.generation) };
}

function metadataIsWithinLease(metadata) {
  if (typeof metadata.mtimeNs === 'bigint') {
    const ageNs = (BigInt(Date.now()) * 1_000_000n) - metadata.mtimeNs;
    const absoluteAgeNs = ageNs < 0n ? -ageNs : ageNs;
    return absoluteAgeNs <= BigInt(LOCK_STALE_MS) * 1_000_000n;
  }
  return Math.abs(Date.now() - metadata.mtimeMs) <= LOCK_STALE_MS;
}

function corruptClaimStatus(directory, directoryMetadata, ownerMetadata = directoryMetadata) {
  if (metadataIsWithinLease(ownerMetadata)) {
    return { state: 'busy', directory, metadata: directoryMetadata, owner: null };
  }
  const fingerprint = crypto.createHash('sha256')
    .update(JSON.stringify({
      directory: {
        dev: directoryMetadata.dev.toString(),
        ino: directoryMetadata.ino.toString(),
        mode: directoryMetadata.mode.toString(),
        birthtimeNs: directoryMetadata.birthtimeNs.toString(),
      },
    }))
    .digest('hex')
    .slice(0, 24);
  return {
    state: 'releasable',
    directory,
    metadata: directoryMetadata,
    key: `corrupt-${fingerprint}`,
    owner: null,
  };
}

async function inspectActiveClaim(cacheDirectory) {
  const token = cacheTokenFor(cacheDirectory);
  return guardedCacheRead(token, async () => {
    const directory = path.join(cacheDirectory, ACTIVE_CLAIM_DIRECTORY);
    let directoryMetadata;
    try {
      directoryMetadata = await fs.lstat(directory, { bigint: true });
    } catch (error) {
      if (error?.code === 'ENOENT') return { state: 'absent', directory };
      throw error;
    }
    if (!directoryMetadata.isDirectory() || directoryMetadata.isSymbolicLink()) {
      return corruptClaimStatus(directory, directoryMetadata);
    }
    return guardedCacheEntryRead(
      token,
      directory,
      assertSafeDirectory,
      async (stableDirectoryMetadata) => {
        const ownerPath = path.join(directory, OPERATION_OWNER_FILE);
        let ownerMetadata = stableDirectoryMetadata;
        let owner = null;
        try {
          ownerMetadata = await fs.lstat(ownerPath, { bigint: true });
          if (!ownerMetadata.isFile()
            || ownerMetadata.isSymbolicLink()
            || ownerMetadata.size > BigInt(MAX_CLAIM_OWNER_BYTES)) {
            return corruptClaimStatus(directory, stableDirectoryMetadata, ownerMetadata);
          }
          const ownerSource = await readJsonFile(
            ownerPath,
            MAX_CLAIM_OWNER_BYTES,
            ownerMetadata,
          );
          owner = validateClaimOwner(ownerSource);
        } catch (error) {
          if (error instanceof FileIdentityChangedError) throw error;
          // A malformed claim is recoverable only after the same hard lease as a crashed owner.
        }

        if (owner) {
          const operations = await listOperations(cacheDirectory, token);
          if (operations.some((operation) => operation.generation === owner.generation
            && ['committed', 'fenced', 'cancelled'].includes(operation.kind))) {
            return {
              state: 'releasable',
              directory,
              metadata: stableDirectoryMetadata,
              key: owner.generation.toString(),
              owner,
            };
          }
          const pending = operations.find((operation) => operation.kind === 'pending'
            && operation.generation === owner.generation);
          if (pending) {
            if (await operationIsActive(cacheDirectory, pending, token)) {
              return {
                state: 'busy',
                directory,
                metadata: stableDirectoryMetadata,
                owner,
              };
            }
            return {
              state: 'releasable',
              directory,
              metadata: stableDirectoryMetadata,
              key: owner.generation.toString(),
              owner,
            };
          }
        }

        return corruptClaimStatus(directory, stableDirectoryMetadata, ownerMetadata);
      },
      directoryMetadata,
    );
  });
}

async function retireActiveClaim(cacheDirectory, claim) {
  const retirement = path.join(cacheDirectory, `retired-claim-${claim.key}`);
  await cacheMkdir(cacheDirectory, retirement, { mode: 0o700 }).catch((error) => {
    if (error?.code !== 'EEXIST') throw error;
  });
  try {
    const retirementMetadata = await fs.lstat(retirement);
    if (!retirementMetadata.isDirectory() || retirementMetadata.isSymbolicLink()) return false;
  } catch (error) {
    if (error instanceof CacheOperationRaceError) return false;
    if (error?.code === 'ENOENT') return false;
    throw error;
  }
  try {
    const metadata = await fs.lstat(claim.directory);
    if (metadata.isDirectory() && !metadata.isSymbolicLink()) {
      await cacheWriteFile(
        cacheDirectory,
        path.join(claim.directory, '.retirement-guard'),
        `${claim.key}\n`,
        { encoding: 'utf8', flag: 'wx', mode: 0o600 },
      ).catch((error) => {
        if (error?.code !== 'EEXIST') throw error;
      });
    }
  } catch (error) {
    if (error instanceof CacheOperationRaceError) return false;
    if (error?.code === 'ENOENT') return false;
    throw error;
  }
  try {
    await cacheRename(
      cacheDirectory,
      claim.directory,
      path.join(retirement, 'active'),
      assertRenameableCacheEntry,
      claim.metadata,
    );
    return true;
  } catch (error) {
    if (error instanceof CacheOperationRaceError) return false;
    if (['ENOENT', 'EEXIST', 'ENOTEMPTY', 'EPERM'].includes(error?.code)) return false;
    throw error;
  }
}

async function prepareOperationClaim(cacheDirectory, operation) {
  const directory = path.join(cacheDirectory, operationName('claim', operation.generation));
  await cacheMkdir(cacheDirectory, directory, { mode: 0o700 });
  await cacheWriteFile(
    cacheDirectory,
    path.join(directory, OPERATION_OWNER_FILE),
    `${JSON.stringify({
      pid: process.pid,
      token: operation.token,
      generation: operation.generation.toString(),
    })}\n`,
    { encoding: 'utf8', flag: 'wx', mode: 0o600 },
  );
  operation.preparedClaimDirectory = directory;
}

async function discardPreparedClaim(cacheDirectory, operation) {
  if (!operation.preparedClaimDirectory) return;
  const discarded = path.join(
    cacheDirectory,
    `discarded-claim-${operation.generation.toString().padStart(20, '0')}-${operation.token}`,
  );
  try {
    await cacheRename(
      cacheDirectory,
      operation.preparedClaimDirectory,
      discarded,
      assertSafeDirectory,
    );
  } catch (error) {
    if (error?.code !== 'ENOENT') throw error;
  }
  delete operation.preparedClaimDirectory;
}

async function promoteOperationClaim(cacheDirectory, operation) {
  await prepareOperationClaim(cacheDirectory, operation);
  const activeDirectory = path.join(cacheDirectory, ACTIVE_CLAIM_DIRECTORY);
  for (let attempt = 0; attempt < 8; attempt += 1) {
    if (await operationIsSuperseded(cacheDirectory, operation)) {
      await discardPreparedClaim(cacheDirectory, operation);
      return false;
    }
    const active = await inspectActiveClaim(cacheDirectory);
    if (active.state === 'busy') {
      await discardPreparedClaim(cacheDirectory, operation);
      return false;
    }
    if (active.state === 'releasable') {
      if (active.owner?.generation > operation.generation) {
        await discardPreparedClaim(cacheDirectory, operation);
        return false;
      }
      await retireActiveClaim(cacheDirectory, active);
      continue;
    }
    try {
      await cacheRename(
        cacheDirectory,
        operation.preparedClaimDirectory,
        activeDirectory,
        assertSafeDirectory,
      );
      delete operation.preparedClaimDirectory;
      if (!await operationIsActive(cacheDirectory, operation)) return false;
      return true;
    } catch (promotionError) {
      const raced = await inspectActiveClaim(cacheDirectory);
      if (raced.state === 'absent') {
        if (['EEXIST', 'ENOTEMPTY', 'EPERM'].includes(promotionError?.code)) continue;
        await discardPreparedClaim(cacheDirectory, operation);
        throw promotionError;
      }
      continue;
    }
  }
  await discardPreparedClaim(cacheDirectory, operation);
  return false;
}

async function operationOwnsActiveClaim(cacheDirectory, operation) {
  const active = await inspectActiveClaim(cacheDirectory);
  return active.state === 'busy'
    && active.owner?.generation === operation.generation
    && active.owner.token === operation.token;
}

async function hasActivePendingOperation(cacheDirectory) {
  const token = cacheTokenFor(cacheDirectory);
  return guardedCacheRead(token, async () => {
    const pending = (await listOperations(cacheDirectory, token))
      .filter((operation) => operation.kind === 'pending');
    return (await Promise.all(pending.map(
      (operation) => operationIsActive(cacheDirectory, operation, token),
    ))).some(Boolean);
  });
}

async function reserveOperation(cacheDirectory) {
  cacheDirectory = await prepareCacheDirectory(cacheDirectory);
  const operations = await listOperations(cacheDirectory);
  const occupied = new Set(operations.map((operation) => operation.generation.toString()));
  let generation = 1n;
  while (true) {
    while (occupied.has(generation.toString())) generation += 1n;
    if (generation > MAX_OPERATION_GENERATION) throw new Error('operation generation space exhausted');
    const reservation = path.join(cacheDirectory, operationName('reserved', generation));
    try {
      await cacheMkdir(cacheDirectory, reservation, { mode: 0o700 });
    } catch (error) {
      if (error?.code !== 'EEXIST') throw error;
      occupied.add(generation.toString());
      generation += 1n;
      continue;
    }
    const directory = path.join(cacheDirectory, operationName('pending', generation));
    try {
      await cacheMkdir(cacheDirectory, directory, { mode: 0o700 });
      const operation = {
        generation,
        token: crypto.randomBytes(16).toString('hex'),
        directory,
      };
      try {
        await cacheWriteFile(
          cacheDirectory,
          path.join(directory, OPERATION_OWNER_FILE),
          `${JSON.stringify({ pid: process.pid, token: operation.token })}\n`,
          { encoding: 'utf8', flag: 'wx', mode: 0o600 },
        );
      } catch (error) {
        if (await operationWasFenced(cacheDirectory, operation)) {
          const fencedError = new OperationFencedError('operation was fenced while reserving');
          fencedError.cause = error;
          throw fencedError;
        }
        await cacheRename(
          cacheDirectory,
          directory,
          path.join(cacheDirectory, operationName('cancelled', generation)),
          assertSafeDirectory,
        ).catch(() => {});
        throw error;
      }
      return operation;
    } catch (error) {
      if (error?.code !== 'EEXIST') throw error;
      occupied.add(generation.toString());
      generation += 1n;
    }
  }
}

async function operationIsSuperseded(cacheDirectory, operation) {
  return (await listOperations(cacheDirectory))
    .some((candidate) => candidate.generation > operation.generation);
}

async function operationWasFenced(cacheDirectory, operation) {
  const token = cacheTokenFor(cacheDirectory);
  return guardedCacheRead(token, async () => {
    try {
      await fs.lstat(operation.directory, { bigint: true });
      return false;
    } catch (error) {
      if (error?.code !== 'ENOENT') throw error;
    }
    const fencedDirectory = path.join(
      cacheDirectory,
      operationName('fenced', operation.generation),
    );
    try {
      await stableCacheEntry(
        token,
        fencedDirectory,
        assertSafeDirectory,
        null,
        true,
      );
      return true;
    } catch (error) {
      if (error?.code === 'ENOENT') return false;
      throw error;
    }
  });
}

async function transitionOperation(cacheDirectory, operation, kind) {
  const destination = path.join(cacheDirectory, operationName(kind, operation.generation));
  await cacheRename(cacheDirectory, operation.directory, destination, assertSafeDirectory);
}

async function cancelOperation(cacheDirectory, operation) {
  try {
    await transitionOperation(cacheDirectory, operation, 'cancelled');
  } catch (error) {
    // A higher generation may already have fenced this unique pending directory.
    if (error?.code !== 'ENOENT') throw error;
  }
}

async function acquireOperation(cacheDirectory) {
  cacheDirectory = await prepareCacheDirectory(cacheDirectory);
  if ((await inspectActiveClaim(cacheDirectory)).state === 'busy') return null;
  if (await hasActivePendingOperation(cacheDirectory)) return null;
  let operation;
  try {
    operation = await reserveOperation(cacheDirectory);
  } catch (error) {
    if (error instanceof OperationFencedError) return null;
    throw error;
  }
  if (!await operationIsSuperseded(cacheDirectory, operation)
    && await promoteOperationClaim(cacheDirectory, operation)) return operation;
  await cancelOperation(cacheDirectory, operation);
  return null;
}

async function fenceLowerOperations(cacheDirectory, operation) {
  const lower = (await listOperations(cacheDirectory))
    .filter((candidate) => candidate.kind === 'pending'
      && candidate.generation < operation.generation)
    .sort((left, right) => (left.generation < right.generation ? -1 : 1));
  for (const candidate of lower) {
    try {
      await cacheRename(
        cacheDirectory,
        candidate.directory,
        path.join(cacheDirectory, operationName('fenced', candidate.generation)),
        assertSafeDirectory,
      );
    } catch (error) {
      if (error?.code !== 'ENOENT') throw error;
    }
  }
}

async function commitOperation(cacheDirectory, operation, installedVersion, mutate) {
  if (!await operationOwnsActiveClaim(cacheDirectory, operation)) {
    await cancelOperation(cacheDirectory, operation);
    return { fenced: true, result: silent('check-in-progress') };
  }
  await fenceLowerOperations(cacheDirectory, operation);
  if (!await operationOwnsActiveClaim(cacheDirectory, operation)) {
    await cancelOperation(cacheDirectory, operation);
    return { fenced: true, result: silent('check-in-progress') };
  }
  const state = await readState(cacheDirectory, installedVersion);
  const decision = mutate(state);
  if (!decision.state) {
    await cancelOperation(cacheDirectory, operation);
    return { fenced: false, result: decision.result };
  }
  let committedState = decision.state;
  let committedResult = decision.result;
  let encodedState = encodeRecoverableState(committedState);
  if (!encodedState && decision.capacityFallback) {
    committedState = decision.capacityFallback.state;
    committedResult = decision.capacityFallback.result;
    encodedState = encodeRecoverableState(committedState);
  }
  if (!encodedState) {
    await cancelOperation(cacheDirectory, operation);
    return { fenced: false, result: silent('cache-unavailable') };
  }
  const temporary = path.join(
    operation.directory,
    `.state.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`,
  );
  try {
    await cacheWriteFile(cacheDirectory, temporary, encodedState, {
      flag: 'wx',
      mode: 0o600,
    });
    await cacheRename(
      cacheDirectory,
      temporary,
      path.join(operation.directory, OPERATION_STATE_FILE),
      assertSafeRegularFile,
    );
    await transitionOperation(cacheDirectory, operation, 'committed');
    return { fenced: false, result: committedResult };
  } catch (error) {
    if (await operationWasFenced(cacheDirectory, operation)) {
      return { fenced: true, result: silent('check-in-progress') };
    }
    await cacheRm(cacheDirectory, temporary, { force: true }).catch(() => {});
    throw error;
  }
}

function nextSuccessfulCheck(nowMs, random) {
  const boundedRandom = Math.min(1, Math.max(0, Number(random()) || 0));
  const multiplier = 0.8 + (boundedRandom * 0.4);
  return new Date(nowMs + Math.round(CHECK_TTL_MS * multiplier)).toISOString();
}

function nextFailedCheck(nowMs, failures) {
  const delay = failures <= 1 ? FIRST_FAILURE_DELAY_MS : LATER_FAILURE_DELAY_MS;
  return new Date(nowMs + delay).toISOString();
}

function stateAfterFailedCheck(state, nowMs, withdrawCandidate = false) {
  const failures = Math.min(state.check.consecutiveFailures + 1, 2);
  return stateWithFailureCheck(
    state,
    nextFailedCheck(nowMs, failures),
    failures,
    withdrawCandidate,
  );
}

function eventKeyForDigest(targetDigest) {
  return `${SKILL_ID}@${targetDigest}`;
}

function digestForEventKey(eventKey) {
  const prefix = `${SKILL_ID}@`;
  if (typeof eventKey !== 'string' || !eventKey.startsWith(prefix)) return null;
  const digest = eventKey.slice(prefix.length);
  return DIGEST_PATTERN.test(digest) ? digest : null;
}

function notification(localRelease, candidate) {
  return {
    status: 'update_available',
    eventKey: eventKeyForDigest(candidate.targetDigest),
    installedVersion: localRelease.version,
    latestVersion: candidate.version,
    targetDigest: candidate.targetDigest,
    severity: candidate.severity,
    summary: `Archify ${candidate.version} is available; see the official release notes for details.`,
    releaseNotes: candidate.releaseNotes,
  };
}

function resultForCandidate(localRelease, state) {
  if (!state.candidate) return silent('cache-valid');
  const comparison = compareSemver(state.candidate.version, localRelease.version);
  if (comparison <= 0) return silent('current');
  if (state.notification.acknowledgedDigests.includes(state.candidate.targetDigest)) {
    return silent('already-notified');
  }
  return notification(localRelease, state.candidate);
}

async function readBoundedBody(response) {
  const contentLength = Number(response.headers.get('content-length'));
  if (Number.isFinite(contentLength) && contentLength > MAX_RESPONSE_BYTES) {
    await cancelResponseBody(response);
    throw new UpdateContractError('manifest response is too large');
  }
  if (!response.body || typeof response.body.getReader !== 'function') {
    throw new UpdateContractError('manifest response has no bounded stream');
  }
  const reader = response.body.getReader();
  const chunks = [];
  let size = 0;
  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      size += value.byteLength;
      if (size > MAX_RESPONSE_BYTES) {
        await reader.cancel().catch(() => {});
        throw new UpdateContractError('manifest response is too large');
      }
      chunks.push(value);
    }
  } finally {
    reader.releaseLock();
  }
  const joined = new Uint8Array(size);
  let offset = 0;
  for (const chunk of chunks) {
    joined.set(chunk, offset);
    offset += chunk.byteLength;
  }
  try {
    return new TextDecoder('utf-8', { fatal: true }).decode(joined);
  } catch {
    throw new UpdateContractError('manifest is not valid UTF-8');
  }
}

async function cancelResponseBody(response) {
  try {
    if (response.body && typeof response.body.cancel === 'function') {
      await response.body.cancel();
    }
  } catch {
    // Network cleanup is best-effort; the original response classification wins.
  }
}

async function fetchCandidate({ fetchImpl, manifestUrl, timeoutMs }) {
  if (manifestUrl !== DEFAULT_MANIFEST_URL) throw new UpdateContractError('unexpected manifest URL');
  const controller = new AbortController();
  let timer;
  const timeout = new Promise((_resolve, reject) => {
    timer = setTimeout(() => {
      controller.abort();
      reject(new Error('update check timed out'));
    }, timeoutMs);
  });
  const request = (async () => {
    const headers = { accept: 'application/json' };
    const response = await fetchImpl(manifestUrl, {
      method: 'GET',
      headers,
      redirect: 'error',
      signal: controller.signal,
    });
    if (response.status !== 200) {
      await cancelResponseBody(response);
      throw new Error(`manifest returned HTTP ${response.status}`);
    }
    const mediaType = response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase();
    if (mediaType !== 'application/json') {
      await cancelResponseBody(response);
      throw new UpdateContractError('manifest is not JSON');
    }
    const source = await readBoundedBody(response);
    let decoded;
    try {
      decoded = JSON.parse(source);
    } catch {
      throw new UpdateContractError('manifest is not valid bounded JSON');
    }
    return { candidate: validateManifest(decoded) };
  })();
  try {
    return await Promise.race([request, timeout]);
  } finally {
    clearTimeout(timer);
  }
}

function defaultCacheDirectory() {
  const homeDirectory = os.homedir();
  if (process.platform === 'win32') {
    const localData = process.env.LOCALAPPDATA;
    return path.join(localData && path.isAbsolute(localData) ? localData : path.join(homeDirectory, 'AppData', 'Local'), 'archify-skill');
  }
  if (process.platform === 'darwin') return path.join(homeDirectory, 'Library', 'Caches', 'archify-skill');
  const xdgCache = process.env.XDG_CACHE_HOME;
  return path.join(xdgCache && path.isAbsolute(xdgCache) ? xdgCache : path.join(homeDirectory, '.cache'), 'archify-skill');
}

function freshStateResult(localRelease, state, nowMs) {
  const nextCheckAt = Date.parse(state.check.nextCheckAt || '');
  if (Number.isFinite(nextCheckAt) && nextCheckAt > nowMs
    && nextCheckAt <= nowMs + MAX_CACHE_HORIZON_MS) {
    return resultForCandidate(localRelease, state);
  }
  return null;
}

async function resultAfterLosingOperation(cacheDirectory, operation, localRelease) {
  await cancelOperation(cacheDirectory, operation);
  const cached = await readState(cacheDirectory, localRelease.version);
  if (cached.candidate
    && cached.notification.offeredDigests.includes(cached.candidate.targetDigest)) {
    return resultForCandidate(localRelease, cached);
  }
  return silent('check-in-progress');
}

async function waitUntilRetry(deadline, monotonicNow) {
  let remaining;
  try {
    remaining = deadline - Number(monotonicNow());
  } catch {
    return false;
  }
  if (!Number.isFinite(remaining) || remaining <= 0) return false;
  await new Promise((resolve) => setTimeout(
    resolve,
    Math.min(LOCK_RETRY_DELAY_MS, remaining),
  ));
  return true;
}

export async function checkForUpdate({
  releasePath = defaultReleasePath,
  cacheDirectory = defaultCacheDirectory(),
  fetchImpl = globalThis.fetch,
  now = Date.now,
  random = Math.random,
  timeoutMs = DEFAULT_TIMEOUT_MS,
} = {}) {
  if (typeof fetchImpl !== 'function') return silent('runtime-unavailable');
  let localRelease;
  try {
    localRelease = validateLocalRelease(await readJsonFile(releasePath, MAX_LOCAL_RELEASE_BYTES));
  } catch {
    return silent('invalid-local-release');
  }

  const nowMs = Number(now());
  if (!Number.isFinite(nowMs)) return silent('invalid-clock');
  let stateDirectory = versionCacheDirectory(cacheDirectory, localRelease.version);
  let state;
  try {
    stateDirectory = await prepareCacheDirectory(stateDirectory);
    state = await readState(stateDirectory, localRelease.version);
  } catch {
    return silent('cache-unavailable');
  }
  const cachedResult = freshStateResult(localRelease, state, nowMs);
  if (cachedResult) return cachedResult;

  let operation;
  try {
    operation = await acquireOperation(stateDirectory);
  } catch {
    return silent('cache-unavailable');
  }
  if (!operation) {
    try {
      const cached = await readState(stateDirectory, localRelease.version);
      if (cached.candidate
        && cached.notification.offeredDigests.includes(cached.candidate.targetDigest)) {
        return resultForCandidate(localRelease, cached);
      }
    } catch {
      return silent('cache-unavailable');
    }
    return silent('check-in-progress');
  }

  try {
    state = await readState(stateDirectory, localRelease.version);
    const racedResult = freshStateResult(localRelease, state, nowMs);
    if (racedResult) {
      await cancelOperation(stateDirectory, operation);
      return racedResult;
    }

    if (!await operationOwnsActiveClaim(stateDirectory, operation)) {
      return await resultAfterLosingOperation(stateDirectory, operation, localRelease);
    }

    await verifyCacheToken(cacheTokenFor(stateDirectory));
    if (!await operationOwnsActiveClaim(stateDirectory, operation)) {
      return await resultAfterLosingOperation(stateDirectory, operation, localRelease);
    }
    let fetched;
    try {
      fetched = await fetchCandidate({
        fetchImpl,
        manifestUrl: localRelease.updateManifestUrl,
        timeoutMs,
      });
    } catch (error) {
      const reason = error instanceof UpdateContractError ? 'invalid-manifest' : 'check-failed';
      try {
        const committed = await commitOperation(
          stateDirectory,
          operation,
          localRelease.version,
          (current) => ({
            state: stateAfterFailedCheck(current, nowMs),
            result: silent(reason),
          }),
        );
        return committed.result;
      } catch {
        await cancelOperation(stateDirectory, operation).catch(() => {});
        return silent('cache-unavailable');
      }
    }

    try {
      const committed = await commitOperation(
        stateDirectory,
        operation,
        localRelease.version,
        (current) => {
          const next = {
            ...current,
            candidate: fetched.candidate,
            check: {
              nextCheckAt: nextSuccessfulCheck(nowMs, random),
              consecutiveFailures: 0,
            },
            notification: {
              offeredDigests: [...current.notification.offeredDigests],
              acknowledgedDigests: [...current.notification.acknowledgedDigests],
            },
          };
          const result = resultForCandidate(localRelease, next);
          if (result.status === 'update_available') {
            if (!next.notification.offeredDigests.includes(next.candidate.targetDigest)) {
              next.notification.offeredDigests.push(next.candidate.targetDigest);
            }
          }
          return {
            state: next,
            result,
            capacityFallback: {
              state: stateAfterFailedCheck(current, nowMs, true),
              result: silent('cache-unavailable'),
            },
          };
        },
      );
      return committed.result;
    } catch {
      await cancelOperation(stateDirectory, operation).catch(() => {});
      return silent('cache-unavailable');
    }
  } catch {
    await cancelOperation(stateDirectory, operation).catch(() => {});
    return silent('cache-unavailable');
  }
}

export async function acknowledgeUpdate({
  releasePath = defaultReleasePath,
  cacheDirectory = defaultCacheDirectory(),
  eventKey,
  monotonicNow = () => performance.now(),
} = {}) {
  const targetDigest = digestForEventKey(eventKey);
  if (!targetDigest || typeof monotonicNow !== 'function') {
    return silent('invalid-acknowledgement');
  }
  let localRelease;
  try {
    localRelease = validateLocalRelease(await readJsonFile(releasePath, MAX_LOCAL_RELEASE_BYTES));
  } catch {
    return silent('invalid-local-release');
  }
  let stateDirectory = versionCacheDirectory(cacheDirectory, localRelease.version);
  try {
    stateDirectory = await prepareCacheDirectory(stateDirectory);
  } catch {
    return silent('cache-unavailable');
  }
  let deadline;
  try {
    deadline = Number(monotonicNow()) + ACK_LOCK_WAIT_MS;
  } catch {
    return silent('invalid-acknowledgement');
  }
  if (!Number.isFinite(deadline)) return silent('invalid-acknowledgement');
  while (true) {
    let operation;
    try {
      operation = await acquireOperation(stateDirectory);
    } catch {
      return silent('cache-unavailable');
    }
    if (!operation) {
      if (!await waitUntilRetry(deadline, monotonicNow)) return silent('check-in-progress');
      continue;
    }
    try {
      const committed = await commitOperation(
        stateDirectory,
        operation,
        localRelease.version,
        (state) => {
          const wasOffered = state.notification.offeredDigests.includes(targetDigest);
          const wasAcknowledged = state.notification.acknowledgedDigests.includes(targetDigest);
          if (!wasOffered && !wasAcknowledged) {
            return { state: null, result: silent('invalid-acknowledgement') };
          }
          return {
            state: stateAfterAcknowledgement(state, targetDigest),
            result: { status: 'acknowledged', eventKey },
          };
        },
      );
      if (!committed.fenced) return committed.result;
      if (!await waitUntilRetry(deadline, monotonicNow)) return silent('check-in-progress');
    } catch {
      await cancelOperation(stateDirectory, operation).catch(() => {});
      return silent('cache-unavailable');
    }
  }
}

async function runCli() {
  if (process.env.ARCHIFY_UPDATE_CHECK_DISABLED === '1') return silent('disabled');
  const argumentsList = process.argv.slice(2);
  if (argumentsList.length === 0) return checkForUpdate();
  if (argumentsList.length === 2 && argumentsList[0] === '--ack') {
    return acknowledgeUpdate({ eventKey: argumentsList[1] });
  }
  return silent('invalid-arguments');
}

async function isMainModule() {
  if (!process.argv[1]) return false;
  try {
    const [entryPath, modulePath] = await Promise.all([
      fs.realpath(path.resolve(process.argv[1])),
      fs.realpath(fileURLToPath(import.meta.url)),
    ]);
    return entryPath === modulePath;
  } catch {
    return path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
  }
}

if (await isMainModule()) {
  let result;
  try {
    result = await runCli();
  } catch {
    result = silent('check-failed');
  }
  process.stdout.write(`${JSON.stringify(result)}\n`);
}