@visa/cli 4.1.0-rc.99 → 5.0.0-rc.335

package/dist/managed-runtime/update-and-restart.mjs

@@ -0,0 +1,1079 @@
+#!/usr/bin/env node
+/** Supervisor-owned exact-RC deployment transaction for managed runtimes. */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { execFileSync, execSync } from 'node:child_process'
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  assertSameRuntimeBuild,
+  assertSameShopifyRuntime,
+  commerceSkillArgs,
+  parseRuntimeReadiness,
+  resolveRuntimeUpdateConfig,
+  runtimeReadinessExecOptions,
+} from './runtime-readiness.mjs'
+
+const PREFIX = '[managed-runtime-update]'
+const EXACT_RC_RE = /^\d+\.\d+\.\d+-rc\.\d+$/
+const SRI_RE = /^sha512-[A-Za-z0-9+/]+={0,2}$/
+const DEFAULT_COMMAND_TIMEOUT_MS = 120_000
+const MAX_ROLLBACK_ATTEMPTS = 2
+const COMMANDS_PER_TRANSACTION_BOUND = 12
+const READINESS_PROBES_PER_TRANSACTION_BOUND = 3
+const RELEASE_INTEGRITY_RE = /^sha512-[A-Za-z0-9+/]+={0,2}$/
+const PENDING_TRANSACTION_FILE = '.pending-update.json'
+
+function exactRcParts(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)-rc\.(\d+)$/.exec(version)
+  if (!match) return null
+  const parts = match.slice(1).map(Number)
+  return parts.every(Number.isSafeInteger) ? parts : null
+}
+
+export function compareExactRc(left, right) {
+  const leftParts = exactRcParts(left)
+  const rightParts = exactRcParts(right)
+  if (!leftParts || !rightParts) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      'managed release version is not an exact RC'
+    )
+  }
+  for (let index = 0; index < leftParts.length; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index]
+  }
+  return 0
+}
+
+export class ManagedRuntimeUpdateError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, options)
+    this.name = 'ManagedRuntimeUpdateError'
+    this.code = code
+  }
+}
+
+function structuredLog(event, fields = {}, logger = console) {
+  logger.log(`${PREFIX} ${JSON.stringify({ event, ...fields })}`)
+}
+
+function safeInteger(value, fallback, name) {
+  if (value === undefined || value === '') return fallback
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_configuration',
+      `${name} must be a positive integer`
+    )
+  }
+  return parsed
+}
+
+export function resolveManagedUpdateConfig(env = process.env) {
+  const exactVersion = env.VISA_CLI_EXACT_VERSION?.trim() || ''
+  if (!EXACT_RC_RE.test(exactVersion) || !exactRcParts(exactVersion)) {
+    throw new ManagedRuntimeUpdateError(
+      'exact_target_required',
+      'VISA_CLI_EXACT_VERSION must be an exact RC such as 4.1.0-rc.253; floating dist-tags are refused'
+    )
+  }
+  const managedDir = env.VISA_MANAGED_RUNTIME_DIR?.trim() || ''
+  if (!managedDir || !isAbsolute(managedDir)) {
+    throw new ManagedRuntimeUpdateError(
+      'unmanaged_runtime',
+      'VISA_MANAGED_RUNTIME_DIR must be an absolute supervisor-owned directory'
+    )
+  }
+  const runtime = resolveRuntimeUpdateConfig(env)
+  if (!runtime.restartCommand || !runtime.readinessCommand) {
+    throw new ManagedRuntimeUpdateError(
+      'unmanaged_runtime',
+      'managed updates require RUNTIME_RESTART_COMMAND and RUNTIME_READINESS_COMMAND'
+    )
+  }
+  const expectedEnvironment = env.VISA_RUNTIME_EXPECTED_ENVIRONMENT?.trim() || ''
+  if (!/^(?:development|staging|production)$/.test(expectedEnvironment)) {
+    throw new ManagedRuntimeUpdateError(
+      'expected_environment_required',
+      'VISA_RUNTIME_EXPECTED_ENVIRONMENT must be development, staging, or production'
+    )
+  }
+  const resolvedManagedDir = resolve(managedDir)
+  if (existsSync(resolvedManagedDir) && realpathSync(resolvedManagedDir) !== resolvedManagedDir) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      'VISA_MANAGED_RUNTIME_DIR and its parents must not contain symbolic links'
+    )
+  }
+  const commandTimeoutMs = safeInteger(
+    env.VISA_RUNTIME_UPDATE_TIMEOUT_MS,
+    DEFAULT_COMMAND_TIMEOUT_MS,
+    'VISA_RUNTIME_UPDATE_TIMEOUT_MS'
+  )
+  return {
+    ...runtime,
+    exactVersion,
+    expectedEnvironment,
+    managedDir: existsSync(resolvedManagedDir)
+      ? realpathSync(resolvedManagedDir)
+      : resolvedManagedDir,
+    commandTimeoutMs,
+    lockLeaseMs:
+      commandTimeoutMs * COMMANDS_PER_TRANSACTION_BOUND +
+      runtime.readinessTimeoutMs * READINESS_PROBES_PER_TRANSACTION_BOUND,
+  }
+}
+
+function ensureCanonicalDirectory(path, label) {
+  mkdirSync(path, { recursive: true, mode: 0o700 })
+  if (lstatSync(path).isSymbolicLink() || realpathSync(path) !== resolve(path)) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      `${label} and its parents must not contain symbolic links`
+    )
+  }
+}
+
+function processIsAlive(pid, processKill = process.kill) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false
+  try {
+    processKill(pid, 0)
+    return true
+  } catch (error) {
+    return error?.code === 'EPERM'
+  }
+}
+
+export function acquireUpdateLock(managedDir, correlationId, options = {}) {
+  const now = options.now?.() ?? Date.now()
+  const leaseMs =
+    options.leaseMs ??
+    DEFAULT_COMMAND_TIMEOUT_MS * COMMANDS_PER_TRANSACTION_BOUND +
+      60_000 * READINESS_PROBES_PER_TRANSACTION_BOUND
+  mkdirSync(managedDir, { recursive: true, mode: 0o700 })
+  ensureCanonicalDirectory(managedDir, 'VISA_MANAGED_RUNTIME_DIR')
+  const lockDir = join(managedDir, '.update-lock')
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const candidate = join(managedDir, `.update-lock-candidate-${correlationId}-${attempt}`)
+    try {
+      mkdirSync(candidate, { mode: 0o700 })
+      try {
+        writeFileSync(
+          join(candidate, 'owner.json'),
+          JSON.stringify({
+            correlationId,
+            pid: process.pid,
+            createdAtMs: now,
+            expiresAtMs: now + leaseMs,
+          }),
+          { mode: 0o600, flag: 'wx' }
+        )
+        fsyncDirectory(candidate)
+        renameSync(candidate, lockDir)
+        fsyncDirectory(managedDir)
+      } catch (error) {
+        rmSync(candidate, { recursive: true, force: true })
+        throw error
+      }
+      return () => {
+        try {
+          const owner = JSON.parse(readFileSync(join(lockDir, 'owner.json'), 'utf8'))
+          if (owner.correlationId === correlationId) {
+            rmSync(lockDir, { recursive: true, force: true })
+          }
+        } catch {
+          // Never remove a lock whose ownership can no longer be proven.
+        }
+      }
+    } catch (error) {
+      rmSync(candidate, { recursive: true, force: true })
+      if (error?.code !== 'EEXIST' && error?.code !== 'ENOTEMPTY') throw error
+      let owner = null
+      try {
+        owner = JSON.parse(readFileSync(join(lockDir, 'owner.json'), 'utf8'))
+      } catch {
+        // An incomplete owner record is stale because owner creation is atomic under mkdir.
+      }
+      const active =
+        owner &&
+        Number.isSafeInteger(owner.expiresAtMs) &&
+        owner.expiresAtMs > now &&
+        processIsAlive(owner.pid, options.processKill)
+      if (active) {
+        throw new ManagedRuntimeUpdateError(
+          'update_in_progress',
+          'another supervisor-owned runtime update is already in progress'
+        )
+      }
+      const stale = join(managedDir, `.stale-update-lock-${correlationId}-${attempt}`)
+      try {
+        renameSync(lockDir, stale)
+        rmSync(stale, { recursive: true, force: true })
+      } catch (renameError) {
+        if (renameError?.code !== 'ENOENT') throw renameError
+      }
+    }
+  }
+  throw new ManagedRuntimeUpdateError('update_in_progress', 'could not acquire runtime update lock')
+}
+
+function parseJson(raw, label) {
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_package_metadata',
+      `${label} returned invalid JSON`,
+      {
+        cause: error,
+      }
+    )
+  }
+}
+
+function assertManagedChild(managedDir, candidate, label) {
+  const rel = relative(managedDir, candidate)
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      `${label} escaped the managed directory`
+    )
+  }
+}
+
+export function releaseTreeIntegrity(releaseDir) {
+  const hash = createHash('sha512')
+  const visit = (directory, prefix = '') => {
+    for (const name of readdirSync(directory).sort()) {
+      if (!prefix && name === 'deployment-receipt.json') continue
+      const absolute = join(directory, name)
+      const entry = lstatSync(absolute)
+      const path = prefix ? `${prefix}/${name}` : name
+      if (entry.isDirectory()) {
+        hash.update(`directory\0${path}\0${entry.mode & 0o777}\0`)
+        visit(absolute, path)
+      } else if (entry.isFile()) {
+        hash.update(`file\0${path}\0${entry.mode & 0o777}\0${entry.size}\0`)
+        hash.update(readFileSync(absolute))
+      } else if (entry.isSymbolicLink()) {
+        const target = readlinkSync(absolute)
+        const resolvedTarget = resolve(dirname(absolute), target)
+        assertManagedChild(releaseDir, resolvedTarget, `release symlink ${path}`)
+        assertManagedChild(releaseDir, realpathSync(absolute), `release symlink ${path}`)
+        hash.update(`symlink\0${path}\0${target}\0`)
+      } else {
+        throw new ManagedRuntimeUpdateError(
+          'invalid_runtime_state',
+          `managed release contains unsupported filesystem entry ${path}`
+        )
+      }
+    }
+  }
+  visit(releaseDir)
+  return `sha512-${hash.digest('base64')}`
+}
+
+function verifyReleaseReceipt(releaseDir, receipt) {
+  if (!RELEASE_INTEGRITY_RE.test(receipt.releaseIntegrity || '')) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      'managed deployment receipt omitted release integrity'
+    )
+  }
+  if (releaseTreeIntegrity(releaseDir) !== receipt.releaseIntegrity) {
+    throw new ManagedRuntimeUpdateError(
+      'release_integrity_mismatch',
+      'managed release bytes no longer match the known-good deployment receipt'
+    )
+  }
+}
+
+function fsyncDirectory(path) {
+  const fd = openSync(path, 'r')
+  try {
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+function atomicWritePrivateJson(path, value, id = randomUUID()) {
+  const temp = join(dirname(path), `.${basename(path)}-${id}.tmp`)
+  let fd
+  try {
+    fd = openSync(temp, 'wx', 0o600)
+    writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`)
+    fsyncSync(fd)
+    closeSync(fd)
+    fd = undefined
+    renameSync(temp, path)
+    chmodSync(path, 0o600)
+    fsyncDirectory(dirname(path))
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+    rmSync(temp, { force: true })
+  }
+}
+
+export function readCurrentRelease(managedDir) {
+  const current = join(managedDir, 'current')
+  if (!existsSync(current)) return null
+  if (!lstatSync(current).isSymbolicLink()) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      'current runtime pointer is not a symbolic link'
+    )
+  }
+  const target = realpathSync(resolve(dirname(current), readlinkSync(current)))
+  assertManagedChild(managedDir, target, 'current runtime link')
+  const receiptPath = join(target, 'deployment-receipt.json')
+  if (!existsSync(receiptPath)) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      'current managed runtime has no deployment receipt and cannot be used as known-good'
+    )
+  }
+  const receipt = parseJson(readFileSync(receiptPath, 'utf8'), 'known-good deployment receipt')
+  const commerceReady = receipt.commerceReady ?? Boolean(receipt.shopifyRuntime)
+  if (
+    !EXACT_RC_RE.test(receipt.version) ||
+    receipt.releaseDir !== target ||
+    typeof receipt.targetEnvironment !== 'string' ||
+    typeof commerceReady !== 'boolean' ||
+    (commerceReady &&
+      (typeof receipt.shopifyRuntime !== 'object' || receipt.shopifyRuntime === null))
+  ) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      'known-good deployment receipt is invalid'
+    )
+  }
+  verifyReleaseReceipt(target, receipt)
+  return {
+    releaseDir: target,
+    receipt: {
+      ...receipt,
+      commerceReady,
+      commerceActionRequired: receipt.commerceActionRequired ?? null,
+    },
+  }
+}
+
+function visaBinary(releaseDir) {
+  return join(releaseDir, 'node_modules', '.bin', 'visa')
+}
+
+function sha512Integrity(filePath) {
+  return `sha512-${createHash('sha512').update(readFileSync(filePath)).digest('base64')}`
+}
+
+export function stageExactRelease(config, dependencies = {}) {
+  const execFile = dependencies.execFileSync ?? execFileSync
+  const id = dependencies.randomUUID?.() ?? randomUUID()
+  const correlationId = config.correlationId ?? 'standalone-stage'
+  const observedNpm = (operation, args, options) => {
+    const startedAt = Date.now()
+    structuredLog(
+      'external_request',
+      { correlationId, service: 'npm_registry', operation, targetVersion: config.exactVersion },
+      dependencies.logger
+    )
+    try {
+      const result = execFile('npm', args, options)
+      structuredLog(
+        'external_response',
+        {
+          correlationId,
+          service: 'npm_registry',
+          operation,
+          ok: true,
+          durationMs: Date.now() - startedAt,
+        },
+        dependencies.logger
+      )
+      return result
+    } catch (error) {
+      structuredLog(
+        'external_response',
+        {
+          correlationId,
+          service: 'npm_registry',
+          operation,
+          ok: false,
+          durationMs: Date.now() - startedAt,
+        },
+        dependencies.logger
+      )
+      throw error
+    }
+  }
+  const releasesDir = join(config.managedDir, 'releases')
+  const releaseDir = join(releasesDir, config.exactVersion)
+  ensureCanonicalDirectory(releasesDir, 'managed releases directory')
+
+  if (existsSync(releaseDir)) {
+    if (lstatSync(releaseDir).isSymbolicLink()) {
+      throw new ManagedRuntimeUpdateError(
+        'invalid_runtime_state',
+        'managed release directory must not be a symbolic link'
+      )
+    }
+    const receiptPath = join(releaseDir, 'deployment-receipt.json')
+    if (existsSync(receiptPath) && existsSync(visaBinary(releaseDir))) {
+      const installed = parseJson(
+        readFileSync(join(releaseDir, 'node_modules', '@visa', 'cli', 'package.json'), 'utf8'),
+        'installed package manifest'
+      )
+      const receipt = parseJson(readFileSync(receiptPath, 'utf8'), 'deployment receipt')
+      if (
+        installed.version !== config.exactVersion ||
+        receipt.version !== config.exactVersion ||
+        receipt.releaseDir !== releaseDir
+      ) {
+        throw new ManagedRuntimeUpdateError(
+          'invalid_runtime_state',
+          'existing managed release does not match its deployment receipt'
+        )
+      }
+      verifyReleaseReceipt(releaseDir, receipt)
+      return releaseDir
+    }
+    // A prior attempt that never passed loaded-process health is not known-good.
+    const quarantine = join(releasesDir, `.quarantine-${config.exactVersion}-${id}`)
+    renameSync(releaseDir, quarantine)
+  }
+
+  const stagingDir = join(releasesDir, `.staging-${config.exactVersion}-${id}`)
+  mkdirSync(stagingDir, { recursive: true, mode: 0o700 })
+  try {
+    const packageSpec = `@visa/cli@${config.exactVersion}`
+    const metadata = parseJson(
+      observedNpm(
+        'view_exact_metadata',
+        ['view', packageSpec, 'version', 'dist.integrity', '--json'],
+        {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: config.commandTimeoutMs,
+        }
+      ),
+      'npm view'
+    )
+    const expectedIntegrity = metadata?.dist?.integrity ?? metadata?.['dist.integrity'] ?? ''
+    if (metadata.version !== config.exactVersion || !SRI_RE.test(expectedIntegrity)) {
+      throw new ManagedRuntimeUpdateError(
+        'target_not_authorized',
+        'registry metadata did not attest the exact requested RC and sha512 integrity'
+      )
+    }
+
+    const pack = parseJson(
+      observedNpm(
+        'download_exact_tarball',
+        ['pack', packageSpec, '--json', '--pack-destination', stagingDir],
+        {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: config.commandTimeoutMs,
+        }
+      ),
+      'npm pack'
+    )
+    const packed = Array.isArray(pack) ? pack[0] : null
+    if (
+      !packed ||
+      packed.version !== config.exactVersion ||
+      packed.integrity !== expectedIntegrity ||
+      basename(packed.filename) !== packed.filename
+    ) {
+      throw new ManagedRuntimeUpdateError(
+        'package_integrity_mismatch',
+        'packed artifact metadata did not match the exact authorized RC'
+      )
+    }
+    const tarball = join(stagingDir, packed.filename)
+    if (sha512Integrity(tarball) !== expectedIntegrity) {
+      throw new ManagedRuntimeUpdateError(
+        'package_integrity_mismatch',
+        'packed artifact bytes did not match the registry sha512 integrity'
+      )
+    }
+
+    try {
+      observedNpm(
+        'install_staged_tarball',
+        ['install', '--prefix', stagingDir, '--omit=dev', tarball],
+        {
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: config.commandTimeoutMs,
+        }
+      )
+    } catch (error) {
+      throw new ManagedRuntimeUpdateError(
+        'package_install_failed',
+        'the exact verified package could not be installed into the staged release',
+        { cause: error }
+      )
+    }
+    const installed = parseJson(
+      readFileSync(join(stagingDir, 'node_modules', '@visa', 'cli', 'package.json'), 'utf8'),
+      'installed package manifest'
+    )
+    if (installed.version !== config.exactVersion || !existsSync(visaBinary(stagingDir))) {
+      throw new ManagedRuntimeUpdateError(
+        'installed_version_mismatch',
+        'staged CLI did not expose the exact requested version'
+      )
+    }
+    rmSync(tarball, { force: true })
+    renameSync(stagingDir, releaseDir)
+    return releaseDir
+  } catch (error) {
+    rmSync(stagingDir, { recursive: true, force: true })
+    throw error
+  }
+}
+
+export function activateRelease(managedDir, releaseDir, id = randomUUID()) {
+  assertManagedChild(managedDir, releaseDir, 'release')
+  const current = join(managedDir, 'current')
+  const next = join(managedDir, `.current-${id}`)
+  symlinkSync(relative(managedDir, releaseDir), next, 'dir')
+  renameSync(next, current)
+  fsyncDirectory(managedDir)
+}
+
+function removeCurrentIfTarget(managedDir, releaseDir) {
+  const current = join(managedDir, 'current')
+  if (!existsSync(current) && !lstatExists(current)) return
+  if (!lstatSync(current).isSymbolicLink()) return
+  if (resolve(dirname(current), readlinkSync(current)) === releaseDir) {
+    unlinkSync(current)
+    fsyncDirectory(managedDir)
+  }
+}
+
+function lstatExists(path) {
+  try {
+    lstatSync(path)
+    return true
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+function pendingTransactionPath(managedDir) {
+  return join(managedDir, PENDING_TRANSACTION_FILE)
+}
+
+function writePendingTransaction(config, targetRelease, previous, id) {
+  atomicWritePrivateJson(
+    pendingTransactionPath(config.managedDir),
+    {
+      correlationId: config.correlationId,
+      targetRelease,
+      previousRelease: previous?.releaseDir ?? null,
+      createdAt: new Date().toISOString(),
+    },
+    id
+  )
+}
+
+function clearPendingTransaction(managedDir) {
+  const path = pendingTransactionPath(managedDir)
+  if (!lstatExists(path)) return
+  unlinkSync(path)
+  fsyncDirectory(managedDir)
+}
+
+export function recoverInterruptedActivation(managedDir, logger = console) {
+  const path = pendingTransactionPath(managedDir)
+  if (!lstatExists(path)) return false
+  const pending = parseJson(readFileSync(path, 'utf8'), 'pending managed update')
+  if (typeof pending.targetRelease !== 'string') {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      'pending managed update is invalid'
+    )
+  }
+  assertManagedChild(managedDir, pending.targetRelease, 'pending target release')
+  if (pending.previousRelease !== null && typeof pending.previousRelease !== 'string') {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      'pending previous release is invalid'
+    )
+  }
+  if (pending.previousRelease) {
+    assertManagedChild(managedDir, pending.previousRelease, 'pending previous release')
+  }
+
+  const targetReceipt = join(pending.targetRelease, 'deployment-receipt.json')
+  if (existsSync(targetReceipt)) {
+    clearPendingTransaction(managedDir)
+    return false
+  }
+
+  if (pending.previousRelease) {
+    const previousReceiptPath = join(pending.previousRelease, 'deployment-receipt.json')
+    const receipt = parseJson(
+      readFileSync(previousReceiptPath, 'utf8'),
+      'previous deployment receipt'
+    )
+    verifyReleaseReceipt(pending.previousRelease, receipt)
+    activateRelease(managedDir, pending.previousRelease)
+  } else {
+    removeCurrentIfTarget(managedDir, pending.targetRelease)
+  }
+  clearPendingTransaction(managedDir)
+  structuredLog(
+    'interrupted_activation_recovered',
+    {
+      correlationId: pending.correlationId || null,
+      restoredPrevious: Boolean(pending.previousRelease),
+    },
+    logger
+  )
+  return true
+}
+
+function runCommerceInstall(releaseDir, env, execFile, timeout) {
+  try {
+    execFile(visaBinary(releaseDir), commerceSkillArgs(env), {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout,
+    })
+  } catch (error) {
+    throw new ManagedRuntimeUpdateError(
+      'rebuild_or_remount_required',
+      'the managed runtime could not refresh its installer-owned commerce mount; rebuild or remount it',
+      { cause: error }
+    )
+  }
+}
+
+function certifyLocalBinary(releaseDir, execFile, timeout) {
+  const rawCapabilities = execFile(visaBinary(releaseDir), ['capabilities', '--format', 'json'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout,
+  })
+  const capabilities = parseJson(rawCapabilities, 'visa capabilities')
+  const build = capabilities?.data?.build ?? capabilities?.build
+  if (typeof build?.version !== 'string' || typeof build?.targetEnvironment !== 'string') {
+    throw new ManagedRuntimeUpdateError(
+      'local_readiness_failed',
+      'local capabilities omitted build identity'
+    )
+  }
+
+  return {
+    version: build.version,
+    targetEnvironment: build.targetEnvironment,
+    minCompatibleVersion: build.minCompatibleVersion || null,
+  }
+}
+
+function certifyLocalCommerce(releaseDir, env, execFile, timeout) {
+  let rawCommerce
+  try {
+    rawCommerce = execFile(visaBinary(releaseDir), commerceSkillArgs(env, true), {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout,
+    })
+  } catch (error) {
+    throw new ManagedRuntimeUpdateError(
+      'commerce_runtime_not_ready',
+      'local Shopify UCP runtime readiness command failed',
+      { cause: error }
+    )
+  }
+  const commerce = parseJson(rawCommerce, 'commerce readiness')
+  if (
+    commerce?.localBundleReady !== true ||
+    commerce?.shopifyRuntime?.status !== 'ready' ||
+    typeof commerce?.shopifyRuntime?.toolSchemaFingerprint !== 'string'
+  ) {
+    throw new ManagedRuntimeUpdateError(
+      'commerce_runtime_not_ready',
+      'local Shopify UCP runtime did not certify its required tools'
+    )
+  }
+  return commerce.shopifyRuntime
+}
+
+function assessLocalCommerce(releaseDir, env, execFile, timeout) {
+  try {
+    runCommerceInstall(releaseDir, env, execFile, timeout)
+    return {
+      commerceReady: true,
+      commerceActionRequired: null,
+      shopifyRuntime: certifyLocalCommerce(releaseDir, env, execFile, timeout),
+    }
+  } catch (error) {
+    const code =
+      error instanceof ManagedRuntimeUpdateError && error.code === 'rebuild_or_remount_required'
+        ? 'rebuild_or_remount_required'
+        : 'commerce_runtime_not_ready'
+    return {
+      commerceReady: false,
+      commerceActionRequired: code,
+      shopifyRuntime: null,
+    }
+  }
+}
+
+function assessLoadedCommerce(loaded, localCommerce) {
+  if (!localCommerce.commerceReady) return localCommerce
+  try {
+    assertSameShopifyRuntime(loaded.shopifyRuntime, localCommerce.shopifyRuntime)
+    return localCommerce
+  } catch {
+    return {
+      commerceReady: false,
+      commerceActionRequired: 'commerce_runtime_not_ready',
+      shopifyRuntime: null,
+    }
+  }
+}
+
+function restartSupervisor(config, dependencies, operation = 'restart') {
+  const execShell = dependencies.execSync ?? execSync
+  const startedAt = Date.now()
+  structuredLog(
+    'supervisor_request',
+    { correlationId: config.correlationId, operation },
+    dependencies.logger
+  )
+  try {
+    execShell(config.restartCommand, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: config.commandTimeoutMs,
+    })
+  } catch (error) {
+    structuredLog(
+      'supervisor_response',
+      {
+        correlationId: config.correlationId,
+        operation,
+        ok: false,
+        durationMs: Date.now() - startedAt,
+      },
+      dependencies.logger
+    )
+    throw new ManagedRuntimeUpdateError('restart_failed', 'runtime supervisor restart failed', {
+      cause: error,
+    })
+  }
+  structuredLog(
+    'supervisor_response',
+    {
+      correlationId: config.correlationId,
+      operation,
+      ok: true,
+      durationMs: Date.now() - startedAt,
+    },
+    dependencies.logger
+  )
+}
+
+function restartAndReadLoaded(config, dependencies) {
+  const execShell = dependencies.execSync ?? execSync
+  restartSupervisor(config, dependencies)
+  let raw
+  const startedAt = Date.now()
+  structuredLog(
+    'supervisor_request',
+    { correlationId: config.correlationId, operation: 'loaded_readiness' },
+    dependencies.logger
+  )
+  try {
+    raw = execShell(config.readinessCommand, runtimeReadinessExecOptions(config.readinessTimeoutMs))
+  } catch (error) {
+    structuredLog(
+      'supervisor_response',
+      {
+        correlationId: config.correlationId,
+        operation: 'loaded_readiness',
+        ok: false,
+        durationMs: Date.now() - startedAt,
+      },
+      dependencies.logger
+    )
+    throw new ManagedRuntimeUpdateError(
+      'loaded_readiness_failed',
+      'loaded runtime readiness command failed or timed out',
+      { cause: error }
+    )
+  }
+  structuredLog(
+    'supervisor_response',
+    {
+      correlationId: config.correlationId,
+      operation: 'loaded_readiness',
+      ok: true,
+      durationMs: Date.now() - startedAt,
+    },
+    dependencies.logger
+  )
+  return parseRuntimeReadiness(raw)
+}
+
+export function writeReceipt(releaseDir, receipt, id) {
+  const path = join(releaseDir, 'deployment-receipt.json')
+  atomicWritePrivateJson(path, receipt, id)
+}
+
+function rollbackKnownGood(config, previous, dependencies, correlationId) {
+  if (!previous) {
+    throw new ManagedRuntimeUpdateError(
+      'rollback_unavailable',
+      'fresh managed runtime had no known-good release to restore'
+    )
+  }
+  let lastError
+  for (let attempt = 1; attempt <= MAX_ROLLBACK_ATTEMPTS; attempt += 1) {
+    try {
+      verifyReleaseReceipt(previous.releaseDir, previous.receipt)
+      activateRelease(config.managedDir, previous.releaseDir)
+      const loaded = restartAndReadLoaded(config, dependencies)
+      assertSameRuntimeBuild(loaded, {
+        version: previous.receipt.version,
+        targetEnvironment: previous.receipt.targetEnvironment,
+      })
+      structuredLog(
+        'rollback_succeeded',
+        { correlationId, attempt, version: loaded.version },
+        dependencies.logger
+      )
+      return loaded
+    } catch (error) {
+      lastError = error
+    }
+  }
+  throw new ManagedRuntimeUpdateError(
+    'rollback_failed',
+    `known-good runtime could not be restored after ${MAX_ROLLBACK_ATTEMPTS} attempts`,
+    { cause: lastError }
+  )
+}
+
+export async function runManagedRuntimeUpdate(env = process.env, dependencies = {}) {
+  const baseConfig = resolveManagedUpdateConfig(env)
+  // Prefer a caller-supplied id so a convergence run's discovery logs and this
+  // transaction's logs join on one correlation id.
+  const correlationId = dependencies.correlationId ?? dependencies.randomUUID?.() ?? randomUUID()
+  const config = { ...baseConfig, correlationId }
+  const releaseLock = acquireUpdateLock(config.managedDir, correlationId, {
+    leaseMs: config.lockLeaseMs,
+  })
+  const startedAt = Date.now()
+  let previous
+  let activated = false
+  let targetRelease
+  try {
+    recoverInterruptedActivation(config.managedDir, dependencies.logger)
+    previous = readCurrentRelease(config.managedDir)
+    if (previous && previous.receipt.targetEnvironment !== config.expectedEnvironment) {
+      throw new ManagedRuntimeUpdateError(
+        'target_environment_mismatch',
+        `known-good runtime targets ${previous.receipt.targetEnvironment}, expected ${config.expectedEnvironment}`
+      )
+    }
+    if (previous && compareExactRc(config.exactVersion, previous.receipt.version) < 0) {
+      throw new ManagedRuntimeUpdateError(
+        'target_rollback_refused',
+        `exact target ${config.exactVersion} is older than known-good ${previous.receipt.version}`
+      )
+    }
+    structuredLog(
+      'update_started',
+      {
+        correlationId,
+        targetVersion: config.exactVersion,
+        previousVersion: previous?.receipt.version ?? null,
+      },
+      dependencies.logger
+    )
+    targetRelease = stageExactRelease(config, dependencies)
+    const execFile = dependencies.execFileSync ?? execFileSync
+    const local = certifyLocalBinary(targetRelease, execFile, config.commandTimeoutMs)
+    if (local.version !== config.exactVersion) {
+      throw new ManagedRuntimeUpdateError(
+        'installed_version_mismatch',
+        `staged CLI reported ${local.version} instead of ${config.exactVersion}`
+      )
+    }
+    if (local.targetEnvironment !== config.expectedEnvironment) {
+      throw new ManagedRuntimeUpdateError(
+        'target_environment_mismatch',
+        `staged CLI targets ${local.targetEnvironment}, expected ${config.expectedEnvironment}`
+      )
+    }
+    const localCommerce = assessLocalCommerce(targetRelease, env, execFile, config.commandTimeoutMs)
+
+    const releaseIntegrity = releaseTreeIntegrity(targetRelease)
+    writePendingTransaction(config, targetRelease, previous, correlationId)
+    activateRelease(config.managedDir, targetRelease)
+    activated = true
+    const loaded = restartAndReadLoaded(config, dependencies)
+    assertSameRuntimeBuild(loaded, local)
+    const commerce = assessLoadedCommerce(loaded, localCommerce)
+    if (!commerce.commerceReady) {
+      structuredLog(
+        'commerce_action_required',
+        {
+          correlationId,
+          version: local.version,
+          code: commerce.commerceActionRequired,
+          checkoutBlocked: true,
+        },
+        dependencies.logger
+      )
+    }
+
+    const receipt = {
+      ok: true,
+      binaryReady: true,
+      correlationId,
+      version: local.version,
+      targetEnvironment: local.targetEnvironment,
+      minCompatibleVersion: local.minCompatibleVersion,
+      releaseDir: targetRelease,
+      previousVersion: previous?.receipt.version ?? null,
+      releaseIntegrity,
+      commerceReady: commerce.commerceReady,
+      checkoutBlocked: !commerce.commerceReady,
+      commerceActionRequired: commerce.commerceActionRequired,
+      shopifyRuntime: commerce.commerceReady
+        ? {
+            serverName: 'shopify-ucp',
+            installedVersion: commerce.shopifyRuntime.installedVersion,
+            toolSchemaFingerprint: commerce.shopifyRuntime.toolSchemaFingerprint,
+            command: commerce.shopifyRuntime.command,
+            args: commerce.shopifyRuntime.args,
+            blockedTools: commerce.shopifyRuntime.blockedTools,
+          }
+        : null,
+      durationMs: Date.now() - startedAt,
+    }
+    try {
+      ;(dependencies.writeReceipt ?? writeReceipt)(targetRelease, receipt, correlationId)
+    } catch (error) {
+      throw new ManagedRuntimeUpdateError(
+        'receipt_write_failed',
+        'loaded runtime passed health but its durable deployment receipt could not be written',
+        { cause: error }
+      )
+    }
+    clearPendingTransaction(config.managedDir)
+    structuredLog(
+      'update_succeeded',
+      {
+        correlationId,
+        version: receipt.version,
+        binaryReady: receipt.binaryReady,
+        targetEnvironment: receipt.targetEnvironment,
+        releaseIntegrity: receipt.releaseIntegrity,
+        commerceReady: receipt.commerceReady,
+        checkoutBlocked: receipt.checkoutBlocked,
+        commerceActionRequired: receipt.commerceActionRequired,
+        durationMs: receipt.durationMs,
+      },
+      dependencies.logger
+    )
+    return {
+      ok: true,
+      binaryReady: true,
+      correlationId,
+      version: receipt.version,
+      targetEnvironment: receipt.targetEnvironment,
+      minCompatibleVersion: receipt.minCompatibleVersion,
+      previousVersion: receipt.previousVersion,
+      releaseIntegrity: receipt.releaseIntegrity,
+      commerceReady: receipt.commerceReady,
+      checkoutBlocked: receipt.checkoutBlocked,
+      commerceActionRequired: receipt.commerceActionRequired,
+      durationMs: receipt.durationMs,
+      shopifyRuntime: receipt.shopifyRuntime
+        ? {
+            serverName: receipt.shopifyRuntime.serverName,
+            installedVersion: receipt.shopifyRuntime.installedVersion,
+            toolSchemaFingerprint: receipt.shopifyRuntime.toolSchemaFingerprint,
+            blockedTools: receipt.shopifyRuntime.blockedTools,
+          }
+        : null,
+    }
+  } catch (error) {
+    const updateError =
+      error instanceof ManagedRuntimeUpdateError
+        ? error
+        : new ManagedRuntimeUpdateError('loaded_readiness_mismatch', error.message, {
+            cause: error,
+          })
+    structuredLog(
+      'update_failed',
+      { correlationId, code: updateError.code, activated },
+      dependencies.logger
+    )
+    if (activated) {
+      try {
+        if (previous) {
+          rollbackKnownGood(config, previous, dependencies, correlationId)
+        } else if (targetRelease) {
+          removeCurrentIfTarget(config.managedDir, targetRelease)
+          // A successful first activation has no managed known-good release to
+          // restore. Restart after removing its pointer so the supervisor
+          // cannot keep serving the now-uncommitted target process while
+          // `current` says that no managed release is active.
+          restartSupervisor(config, dependencies, 'deactivation_restart')
+        }
+        clearPendingTransaction(config.managedDir)
+      } catch (rollbackError) {
+        throw new ManagedRuntimeUpdateError(
+          'rollback_failed',
+          `update failed with ${updateError.code}; the prior runtime could not be restored`,
+          { cause: new AggregateError([updateError, rollbackError]) }
+        )
+      }
+    }
+    throw updateError
+  } finally {
+    releaseLock()
+  }
+}
+
+async function main() {
+  try {
+    const result = await runManagedRuntimeUpdate(process.env)
+    process.stdout.write(`${JSON.stringify(result)}\n`)
+  } catch (error) {
+    const code = error instanceof ManagedRuntimeUpdateError ? error.code : 'update_failed'
+    process.stderr.write(`${JSON.stringify({ ok: false, code, message: error.message })}\n`)
+    process.exitCode = 1
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  void main()
+}