@git.zone/cli 6.0.1 → 6.1.0

package/ts/mod_release/helpers.releasepublication.ts

@@ -2,8 +2,11 @@ import * as plugins from "./mod.plugins.js";
 import {
   ReleaseJournalStore,
   createReleaseAttempt,
+  createReleaseDockerPromotions,
   finalizeJournalCompletion,
-  type IReleaseJournal,
+  getReleaseDockerPromotionContext,
+  type TReleaseJournal,
+  type IReleaseJournalV2,
   type IReleaseTargetStatus,
   type TReleaseErrorCode,
   type TReleaseTargetState,
@@ -17,6 +20,18 @@ import {
   type INpmArtifactProbeResult,
 } from "./helpers.npmartifact.js";
 import { releaseGitEnv } from "./helpers.releasebranch.js";
+import {
+  TsdockerReleaseCommandError,
+  TsdockerReleaseRequestCleanupError,
+  assertReleaseCleanupResult,
+  assertReleaseProbeResult,
+  assertReleasePromotionResult,
+  assertReleaseQualificationResult,
+  classifyReleasePromotionEvidence,
+  type ITsdockerReleaseClient,
+  type IReleaseProbeResult,
+  type TReleasePromotionEvidence,
+} from "./helpers.tsdockerprotocol.js";
 
 const gitProbeTimeoutMs = 60_000;
 const gitPushTimeoutMs = 5 * 60_000;
@@ -39,9 +54,7 @@ export function buildReleaseGitPushArgs(
     refspecs.push(`${optionsArg.mainOid}:refs/heads/main`);
   }
   if (optionsArg.pushTags) {
-    refspecs.push(
-      `${optionsArg.tagOid}:refs/tags/v${optionsArg.newVersion}`,
-    );
+    refspecs.push(`${optionsArg.tagOid}:refs/tags/v${optionsArg.newVersion}`);
   }
   const args = ["push", "--no-follow-tags"];
   if (refspecs.length > 1) {
@@ -58,7 +71,10 @@ export function buildReleaseGitPushArgs(
 
 type TReleaseTargetSelector =
   | { kind: "git" }
-  | { kind: "npm"; registry: string };
+  | { kind: "npm"; registry: string }
+  | { kind: "docker-qualification" }
+  | { kind: "docker-promotion"; promotionId: string }
+  | { kind: "docker-cleanup" };
 
 type TGitProbeStatus = "pending" | "exact" | "conflict" | "inconclusive";
 
@@ -70,37 +86,66 @@ export interface IReleasePublicationOptions {
   smartshell: plugins.smartshell.Smartshell;
   cwd: string;
   store: ReleaseJournalStore;
-  journal: IReleaseJournal;
+  journal: TReleaseJournal;
   pushUrl?: string;
   recoveryAttemptId?: string;
   npmProbeOptions?: INpmArtifactProbeOptions;
+  tsdocker?: ITsdockerReleaseClient;
   ensurePublicationState: (expectedRemoteMainOidArg?: string) => Promise<void>;
 }
 
 const getTargetStatus = (
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   selectorArg: TReleaseTargetSelector,
 ): IReleaseTargetStatus => {
   if (selectorArg.kind === "git") {
     return journalArg.git;
   }
+  if (selectorArg.kind === "docker-qualification") {
+    if (journalArg.schemaVersion !== 2) {
+      throw new Error("Release journal does not contain Docker qualification.");
+    }
+    return journalArg.docker.qualification;
+  }
+  if (selectorArg.kind === "docker-cleanup") {
+    if (journalArg.schemaVersion !== 2) {
+      throw new Error("Release journal does not contain Docker cleanup.");
+    }
+    return journalArg.docker.cleanup;
+  }
+  if (selectorArg.kind === "docker-promotion") {
+    if (journalArg.schemaVersion !== 2) {
+      throw new Error("Release journal does not contain Docker promotions.");
+    }
+    const promotion = journalArg.docker.promotions.find(
+      (promotionArg) => promotionArg.promotionId === selectorArg.promotionId,
+    );
+    if (!promotion) {
+      throw new Error(
+        `Release journal does not contain Docker promotion ${selectorArg.promotionId}.`,
+      );
+    }
+    return promotion;
+  }
   const registry = journalArg.npm.registries.find(
     (registryArg) => registryArg.registry === selectorArg.registry,
   );
   if (!registry) {
-    throw new Error(`Release journal does not contain npm registry ${selectorArg.registry}.`);
+    throw new Error(
+      `Release journal does not contain npm registry ${selectorArg.registry}.`,
+    );
   }
   return registry;
 };
 
 const updateTarget = async (
   storeArg: ReleaseJournalStore,
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   selectorArg: TReleaseTargetSelector,
   expectedStateArg: TReleaseTargetState | TReleaseTargetState[],
   expectedAttemptIdArg: string | null,
   updateArg: (statusArg: IReleaseTargetStatus) => void,
-): Promise<IReleaseJournal> => {
+): Promise<TReleaseJournal> => {
   const expectedStates = Array.isArray(expectedStateArg)
     ? expectedStateArg
     : [expectedStateArg];
@@ -113,7 +158,9 @@ const updateTarget = async (
         throw new Error("Release target state changed concurrently.");
       }
       if ((status.attempt?.id || null) !== expectedAttemptIdArg) {
-        throw new Error("Release target attempt ownership changed concurrently.");
+        throw new Error(
+          "Release target attempt ownership changed concurrently.",
+        );
       }
       updateArg(status);
       return finalizeJournalCompletion(currentArg);
@@ -123,9 +170,9 @@ const updateTarget = async (
 
 const claimTarget = async (
   storeArg: ReleaseJournalStore,
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   selectorArg: TReleaseTargetSelector,
-): Promise<IReleaseJournal> =>
+): Promise<TReleaseJournal> =>
   updateTarget(
     storeArg,
     journalArg,
@@ -142,11 +189,11 @@ const claimTarget = async (
 
 const finishPublishingTarget = async (
   storeArg: ReleaseJournalStore,
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   selectorArg: TReleaseTargetSelector,
   stateArg: "verified" | "failed" | "conflict",
   errorArg: TReleaseErrorCode | null,
-): Promise<IReleaseJournal> => {
+): Promise<TReleaseJournal> => {
   const attemptId = getTargetStatus(journalArg, selectorArg).attempt?.id;
   if (!attemptId) {
     throw new Error("Release target has no active publication attempt.");
@@ -167,12 +214,12 @@ const finishPublishingTarget = async (
 
 const markUnclaimedTarget = async (
   storeArg: ReleaseJournalStore,
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   selectorArg: TReleaseTargetSelector,
   expectedStatesArg: TReleaseTargetState[],
   stateArg: "verified" | "failed" | "conflict",
   errorArg: TReleaseErrorCode | null,
-): Promise<IReleaseJournal> =>
+): Promise<TReleaseJournal> =>
   updateTarget(
     storeArg,
     journalArg,
@@ -187,10 +234,10 @@ const markUnclaimedTarget = async (
 
 const recoverPublishingTarget = async (
   storeArg: ReleaseJournalStore,
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   selectorArg: TReleaseTargetSelector,
   recoveryAttemptIdArg: string | undefined,
-): Promise<IReleaseJournal> => {
+): Promise<TReleaseJournal> => {
   const status = getTargetStatus(journalArg, selectorArg);
   const attemptId = status.attempt?.id;
   if (!attemptId || recoveryAttemptIdArg !== attemptId) {
@@ -212,18 +259,12 @@ const inspectRemoteRelease = async (
   smartshellArg: plugins.smartshell.Smartshell,
   cwdArg: string,
   destinationArg: string,
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
 ): Promise<IGitProbeResult> => {
   const tagRef = `refs/tags/${journalArg.release.tag}`;
   const result = await smartshellArg.execSpawn(
     "git",
-    [
-      "ls-remote",
-      destinationArg,
-      "refs/heads/main",
-      tagRef,
-      `${tagRef}^{}`,
-    ],
+    ["ls-remote", destinationArg, "refs/heads/main", tagRef, `${tagRef}^{}`],
     {
       cwd: cwdArg,
       env: releaseGitEnv,
@@ -262,8 +303,8 @@ const inspectRemoteRelease = async (
 
 const executeGitTarget = async (
   optionsArg: IReleasePublicationOptions,
-  journalArg: IReleaseJournal,
-): Promise<IReleaseJournal> => {
+  journalArg: TReleaseJournal,
+): Promise<TReleaseJournal> => {
   const selector: TReleaseTargetSelector = { kind: "git" };
   if (journalArg.git.state === "skipped") {
     return journalArg;
@@ -335,7 +376,9 @@ const executeGitTarget = async (
   }
 
   if (journal.git.state === "conflict") {
-    throw new Error("Git release target is in conflict and cannot resume automatically.");
+    throw new Error(
+      "Git release target is in conflict and cannot resume automatically.",
+    );
   }
   probe = await inspectRemoteRelease(
     optionsArg.smartshell,
@@ -430,15 +473,13 @@ const executeGitTarget = async (
     journal,
     selector,
     "failed",
-    pushResult.exitCode === 0
-      ? "verification-inconclusive"
-      : "command-failed",
+    pushResult.exitCode === 0 ? "verification-inconclusive" : "command-failed",
   );
   throw new Error("Git publication did not produce verifiable remote refs.");
 };
 
 const probeNpm = async (
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   registryArg: string,
   optionsArg: IReleasePublicationOptions,
   waitArg = false,
@@ -463,11 +504,11 @@ const probeNpm = async (
 
 const markNpmProbeFailure = async (
   optionsArg: IReleasePublicationOptions,
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   selectorArg: TReleaseTargetSelector,
   expectedStatesArg: TReleaseTargetState[],
   probeArg: INpmArtifactProbeResult,
-): Promise<IReleaseJournal> => {
+): Promise<TReleaseJournal> => {
   const conflict = probeArg.status === "conflict";
   return markUnclaimedTarget(
     optionsArg.store,
@@ -481,10 +522,13 @@ const markNpmProbeFailure = async (
 
 const executeNpmRegistry = async (
   optionsArg: IReleasePublicationOptions,
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   registryArg: string,
-): Promise<IReleaseJournal> => {
-  const selector: TReleaseTargetSelector = { kind: "npm", registry: registryArg };
+): Promise<TReleaseJournal> => {
+  const selector: TReleaseTargetSelector = {
+    kind: "npm",
+    registry: registryArg,
+  };
   let journal = journalArg;
   let status = getTargetStatus(journal, selector);
   let probe = await probeNpm(journal, registryArg, optionsArg);
@@ -502,7 +546,9 @@ const executeNpmRegistry = async (
         "conflict",
         "artifact-conflict",
       );
-      throw new Error(`Previously verified npm registry drifted: ${registryArg}`);
+      throw new Error(
+        `Previously verified npm registry drifted: ${registryArg}`,
+      );
     }
     throw new Error(
       `Previously verified npm registry cannot currently be verified: ${registryArg}`,
@@ -526,10 +572,14 @@ const executeNpmRegistry = async (
         "conflict",
         "artifact-conflict",
       );
-      throw new Error(`npm registry contains conflicting bytes: ${registryArg}`);
+      throw new Error(
+        `npm registry contains conflicting bytes: ${registryArg}`,
+      );
     }
     if (probe.status === "inconclusive") {
-      throw new Error(`npm registry publication is inconclusive: ${registryArg}`);
+      throw new Error(
+        `npm registry publication is inconclusive: ${registryArg}`,
+      );
     }
     journal = await recoverPublishingTarget(
       optionsArg.store,
@@ -576,7 +626,9 @@ const executeNpmRegistry = async (
     throw new Error(`npm registry cannot be verified safely: ${registryArg}`);
   }
 
-  const artifactPath = optionsArg.store.getArtifactPath(journal.release.version);
+  const artifactPath = optionsArg.store.getArtifactPath(
+    journal.release.version,
+  );
   if (!journal.artifact) {
     throw new Error("npm release journal has no artifact.");
   }
@@ -620,10 +672,680 @@ const executeNpmRegistry = async (
   throw new Error(`npm publication could not be verified: ${registryArg}`);
 };
 
+const requireTsdocker = (
+  optionsArg: IReleasePublicationOptions,
+): ITsdockerReleaseClient => {
+  if (!optionsArg.tsdocker) {
+    throw new Error(
+      "Docker release journal requires the verified project-local tSDocker protocol client.",
+    );
+  }
+  return optionsArg.tsdocker;
+};
+
+const getDockerRequestDirectory = (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+): string => optionsArg.store.getReleaseDirectory(journalArg.release.version);
+
+const assertDockerRecoveryAttempt = (
+  statusArg: IReleaseTargetStatus,
+  recoveryAttemptIdArg: string | undefined,
+): string => {
+  const attemptId = statusArg.attempt?.id;
+  if (!attemptId || recoveryAttemptIdArg !== attemptId) {
+    throw new Error(
+      `Release target has unresolved publication attempt ${attemptId || "unknown"}. ` +
+        `After proving its publisher stopped, retry with --recover-attempt=${attemptId || "<attempt-id>"}.`,
+    );
+  }
+  return attemptId;
+};
+
+const reclaimDockerRequestOwnership = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+  statusArg: IReleaseTargetStatus,
+): Promise<string> => {
+  const attemptId = assertDockerRecoveryAttempt(
+    statusArg,
+    optionsArg.recoveryAttemptId,
+  );
+  await requireTsdocker(optionsArg).reclaimRequestFiles(
+    getDockerRequestDirectory(optionsArg, journalArg),
+    [attemptId],
+  );
+  return attemptId;
+};
+
+const recoverRequestCleanupOutcome = async <T>(
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+  ownerIdArg: string,
+  errorArg: unknown,
+  assertResultArg: (valueArg: unknown) => T,
+): Promise<T> => {
+  if (!(errorArg instanceof TsdockerReleaseRequestCleanupError)) {
+    throw errorArg;
+  }
+  try {
+    await requireTsdocker(optionsArg).reclaimRequestFiles(
+      getDockerRequestDirectory(optionsArg, journalArg),
+      [ownerIdArg],
+    );
+  } catch (reclamationError) {
+    errorArg.reclamationError = reclamationError;
+    throw errorArg;
+  }
+  if (errorArg.result !== undefined) {
+    return assertResultArg(errorArg.result);
+  }
+  if (errorArg.commandError !== undefined) {
+    throw errorArg.commandError;
+  }
+  throw errorArg;
+};
+
+const finishDockerQualification = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+  resultArg: IReleaseJournalV2["docker"]["qualification"]["result"],
+  stateArg: "verified" | "conflict",
+  errorArg: TReleaseErrorCode | null,
+): Promise<IReleaseJournalV2> => {
+  const attemptId = journalArg.docker.qualification.attempt?.id;
+  if (!attemptId) {
+    throw new Error("Docker qualification has no active publication attempt.");
+  }
+  return (await optionsArg.store.transact(
+    journalArg.release.version,
+    journalArg.revision,
+    (currentArg) => {
+      if (currentArg.schemaVersion !== 2) {
+        throw new Error("Docker qualification requires journal schema 2.");
+      }
+      const qualification = currentArg.docker.qualification;
+      if (
+        qualification.state !== "publishing" ||
+        qualification.attempt?.id !== attemptId
+      ) {
+        throw new Error("Docker qualification ownership changed concurrently.");
+      }
+      qualification.state = stateArg;
+      qualification.attempt = null;
+      qualification.error = errorArg;
+      qualification.result = resultArg;
+      if (resultArg) {
+        currentArg.docker.promotions = createReleaseDockerPromotions(resultArg);
+      }
+      return finalizeJournalCompletion(currentArg);
+    },
+  )) as IReleaseJournalV2;
+};
+
+const finishDockerCleanup = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+  resultArg: IReleaseJournalV2["docker"]["cleanup"]["result"],
+): Promise<IReleaseJournalV2> => {
+  const attemptId = journalArg.docker.cleanup.attempt?.id;
+  if (!attemptId) {
+    throw new Error("Docker cleanup has no active publication attempt.");
+  }
+  return (await optionsArg.store.transact(
+    journalArg.release.version,
+    journalArg.revision,
+    (currentArg) => {
+      if (currentArg.schemaVersion !== 2) {
+        throw new Error("Docker cleanup requires journal schema 2.");
+      }
+      const cleanup = currentArg.docker.cleanup;
+      if (cleanup.state !== "publishing" || cleanup.attempt?.id !== attemptId) {
+        throw new Error("Docker cleanup ownership changed concurrently.");
+      }
+      cleanup.state = "verified";
+      cleanup.attempt = null;
+      cleanup.error = null;
+      cleanup.result = resultArg;
+      return finalizeJournalCompletion(currentArg);
+    },
+  )) as IReleaseJournalV2;
+};
+
+const runClaimedDockerCleanup = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+): Promise<IReleaseJournalV2> => {
+  const client = requireTsdocker(optionsArg);
+  const ownerId = journalArg.docker.cleanup.attempt?.id;
+  if (!ownerId) {
+    throw new Error("Docker cleanup has no active publication attempt.");
+  }
+  let result: IReleaseJournalV2["docker"]["cleanup"]["result"];
+  try {
+    result = await client.cleanup(
+      journalArg.docker.request,
+      getDockerRequestDirectory(optionsArg, journalArg),
+      ownerId,
+    );
+  } catch (error) {
+    result = await recoverRequestCleanupOutcome(
+      optionsArg,
+      journalArg,
+      ownerId,
+      error,
+      (valueArg) =>
+        assertReleaseCleanupResult(valueArg, journalArg.docker.request),
+    );
+  }
+  return finishDockerCleanup(optionsArg, journalArg, result);
+};
+
+const executeDockerCleanup = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+): Promise<IReleaseJournalV2> => {
+  let journal = journalArg;
+  if (journal.docker.cleanup.state === "verified") return journal;
+  const qualificationConflict =
+    journal.docker.qualification.state === "conflict" &&
+    journal.docker.qualification.error === "destination-conflict" &&
+    journal.docker.promotions.length === 0;
+  const promotionsVerified =
+    journal.docker.promotions.length > 0 &&
+    journal.docker.promotions.every(
+      (promotionArg) => promotionArg.state === "verified",
+    );
+  if (!qualificationConflict && !promotionsVerified) {
+    throw new Error(
+      "Docker candidate cleanup requires verified promotions or a terminal qualification conflict.",
+    );
+  }
+  if (journal.docker.cleanup.state === "publishing") {
+    await reclaimDockerRequestOwnership(
+      optionsArg,
+      journal,
+      journal.docker.cleanup,
+    );
+    journal = (await finishPublishingTarget(
+      optionsArg.store,
+      journal,
+      { kind: "docker-cleanup" },
+      "failed",
+      "attempt-recovery-required",
+    )) as IReleaseJournalV2;
+  }
+  if (journal.docker.cleanup.state === "conflict") {
+    throw new Error("Docker cleanup is in conflict.");
+  }
+  if (!qualificationConflict) {
+    await optionsArg.ensurePublicationState(journal.release.mainOid);
+  }
+  journal = (await claimTarget(optionsArg.store, journal, {
+    kind: "docker-cleanup",
+  })) as IReleaseJournalV2;
+  return runClaimedDockerCleanup(optionsArg, journal);
+};
+
+const cleanupIncompleteQualificationPreparation = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+): Promise<void> => {
+  const ownerId = journalArg.docker.qualification.attempt?.id;
+  if (!ownerId) {
+    throw new Error("Docker qualification has no active publication attempt.");
+  }
+  const client = requireTsdocker(optionsArg);
+  try {
+    await client.cleanup(
+      journalArg.docker.request,
+      getDockerRequestDirectory(optionsArg, journalArg),
+      ownerId,
+    );
+  } catch (error) {
+    await recoverRequestCleanupOutcome(
+      optionsArg,
+      journalArg,
+      ownerId,
+      error,
+      (valueArg) =>
+        assertReleaseCleanupResult(valueArg, journalArg.docker.request),
+    );
+  }
+};
+
+const runClaimedDockerQualification = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+  incompletePreparationCleanupAvailableArg: boolean,
+): Promise<IReleaseJournalV2> => {
+  const client = requireTsdocker(optionsArg);
+  const ownerId = journalArg.docker.qualification.attempt?.id;
+  if (!ownerId) {
+    throw new Error("Docker qualification has no active publication attempt.");
+  }
+  let result: IReleaseJournalV2["docker"]["qualification"]["result"];
+  try {
+    result = await client.qualify(
+      journalArg.docker.request,
+      getDockerRequestDirectory(optionsArg, journalArg),
+      ownerId,
+    );
+  } catch (error) {
+    try {
+      result = await recoverRequestCleanupOutcome(
+        optionsArg,
+        journalArg,
+        ownerId,
+        error,
+        (valueArg) =>
+          assertReleaseQualificationResult(valueArg, journalArg.docker.request),
+      );
+    } catch (commandError) {
+      if (
+        commandError instanceof TsdockerReleaseCommandError &&
+        commandError.code === "DESTINATION_DIGEST_CONFLICT"
+      ) {
+        return finishDockerQualification(
+          optionsArg,
+          journalArg,
+          null,
+          "conflict",
+          "destination-conflict",
+        );
+      }
+      if (
+        incompletePreparationCleanupAvailableArg &&
+        commandError instanceof TsdockerReleaseCommandError &&
+        commandError.code === "RECOVERY_REQUIRED"
+      ) {
+        await cleanupIncompleteQualificationPreparation(optionsArg, journalArg);
+        let journal = (await finishPublishingTarget(
+          optionsArg.store,
+          journalArg,
+          { kind: "docker-qualification" },
+          "failed",
+          "attempt-recovery-required",
+        )) as IReleaseJournalV2;
+        journal = (await claimTarget(optionsArg.store, journal, {
+          kind: "docker-qualification",
+        })) as IReleaseJournalV2;
+        return runClaimedDockerQualification(optionsArg, journal, false);
+      }
+      throw commandError;
+    }
+  }
+  return finishDockerQualification(
+    optionsArg,
+    journalArg,
+    result,
+    "verified",
+    null,
+  );
+};
+
+const executeDockerQualification = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+): Promise<IReleaseJournalV2> => {
+  let journal = journalArg;
+  if (journal.docker.qualification.state === "verified") {
+    return journal;
+  }
+  if (journal.docker.qualification.state === "conflict") {
+    await executeDockerCleanup(optionsArg, journal);
+    throw new Error(
+      "Docker qualification destination conflict is terminal; the candidate was cleaned and Git/npm publication was not attempted.",
+    );
+  }
+  if (journal.docker.qualification.state === "publishing") {
+    await reclaimDockerRequestOwnership(
+      optionsArg,
+      journal,
+      journal.docker.qualification,
+    );
+    journal = (await finishPublishingTarget(
+      optionsArg.store,
+      journal,
+      { kind: "docker-qualification" },
+      "failed",
+      "attempt-recovery-required",
+    )) as IReleaseJournalV2;
+  }
+  await optionsArg.ensurePublicationState(
+    journal.git.expectedRemoteMainOid || undefined,
+  );
+  journal = (await claimTarget(optionsArg.store, journal, {
+    kind: "docker-qualification",
+  })) as IReleaseJournalV2;
+  journal = await runClaimedDockerQualification(optionsArg, journal, true);
+  if (journal.docker.qualification.state === "conflict") {
+    await executeDockerCleanup(optionsArg, journal);
+    throw new Error(
+      "Docker qualification destination conflict is terminal; the candidate was cleaned and Git/npm publication was not attempted.",
+    );
+  }
+  return journal;
+};
+
+const recordDockerPromotion = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+  promotionIdArg: string,
+  expectedStatesArg: TReleaseTargetState[],
+  expectedAttemptIdArg: string | null,
+  stateArg: "verified" | "failed" | "conflict",
+  errorArg: TReleaseErrorCode | null,
+  evidenceArg?: TReleasePromotionEvidence,
+): Promise<IReleaseJournalV2> =>
+  (await optionsArg.store.transact(
+    journalArg.release.version,
+    journalArg.revision,
+    (currentArg) => {
+      if (currentArg.schemaVersion !== 2) {
+        throw new Error("Docker promotion requires journal schema 2.");
+      }
+      const promotion = currentArg.docker.promotions.find(
+        (promotionArg) => promotionArg.promotionId === promotionIdArg,
+      );
+      if (
+        !promotion ||
+        !expectedStatesArg.includes(promotion.state) ||
+        (promotion.attempt?.id || null) !== expectedAttemptIdArg
+      ) {
+        throw new Error("Docker promotion ownership changed concurrently.");
+      }
+      promotion.state = stateArg;
+      promotion.attempt = null;
+      promotion.error = errorArg;
+      if (evidenceArg) promotion.evidence.push(evidenceArg);
+      return finalizeJournalCompletion(currentArg);
+    },
+  )) as IReleaseJournalV2;
+
+const probeDockerPromotion = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+  promotionIdArg: string,
+  ownerIdArg?: string,
+): Promise<IReleaseProbeResult> => {
+  const context = getReleaseDockerPromotionContext(journalArg, promotionIdArg);
+  try {
+    return await requireTsdocker(optionsArg).probe(
+      journalArg.docker.request,
+      context,
+      ownerIdArg
+        ? getDockerRequestDirectory(optionsArg, journalArg)
+        : undefined,
+      ownerIdArg,
+    );
+  } catch (error) {
+    if (!ownerIdArg) throw error;
+    return recoverRequestCleanupOutcome(
+      optionsArg,
+      journalArg,
+      ownerIdArg,
+      error,
+      (valueArg) =>
+        assertReleaseProbeResult(valueArg, journalArg.docker.request, context),
+    );
+  }
+};
+
+const executeDockerPromotion = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV2,
+  promotionIdArg: string,
+): Promise<IReleaseJournalV2> => {
+  let journal = journalArg;
+  let promotion = journal.docker.promotions.find(
+    (promotionArg) => promotionArg.promotionId === promotionIdArg,
+  );
+  if (!promotion) {
+    throw new Error(`Docker promotion ${promotionIdArg} is not journaled.`);
+  }
+  if (promotion.state === "conflict") {
+    throw new Error(`Docker promotion ${promotionIdArg} is in conflict.`);
+  }
+
+  if (promotion.state === "verified") {
+    const probe = await probeDockerPromotion(
+      optionsArg,
+      journal,
+      promotionIdArg,
+    );
+    const classification = classifyReleasePromotionEvidence(probe);
+    if (classification === "exact") return journal;
+    if (classification === "inconclusive") {
+      throw new Error(
+        `Previously verified Docker promotion cannot currently be verified: ${promotionIdArg}`,
+      );
+    }
+    await recordDockerPromotion(
+      optionsArg,
+      journal,
+      promotionIdArg,
+      ["verified"],
+      null,
+      "conflict",
+      "destination-conflict",
+      probe,
+    );
+    throw new Error(
+      `Previously verified Docker promotion drifted: ${promotionIdArg}`,
+    );
+  }
+
+  let recoveredPublishingAttempt = false;
+  if (promotion.state === "publishing") {
+    await reclaimDockerRequestOwnership(optionsArg, journal, promotion);
+    recoveredPublishingAttempt = true;
+  } else {
+    await optionsArg.ensurePublicationState(journal.release.mainOid);
+    journal = (await claimTarget(optionsArg.store, journal, {
+      kind: "docker-promotion",
+      promotionId: promotionIdArg,
+    })) as IReleaseJournalV2;
+    promotion = journal.docker.promotions.find(
+      (promotionArg) => promotionArg.promotionId === promotionIdArg,
+    )!;
+  }
+
+  let attemptId = promotion.attempt?.id;
+  if (!attemptId) {
+    throw new Error("Docker promotion has no active publication attempt.");
+  }
+  let probe: IReleaseProbeResult;
+  try {
+    probe = await probeDockerPromotion(
+      optionsArg,
+      journal,
+      promotionIdArg,
+      attemptId,
+    );
+  } catch (error) {
+    throw error;
+  }
+  let classification = classifyReleasePromotionEvidence(probe);
+  if (classification === "exact") {
+    return recordDockerPromotion(
+      optionsArg,
+      journal,
+      promotionIdArg,
+      ["publishing"],
+      attemptId,
+      "verified",
+      null,
+      probe,
+    );
+  }
+  if (classification === "conflict") {
+    await recordDockerPromotion(
+      optionsArg,
+      journal,
+      promotionIdArg,
+      ["publishing"],
+      attemptId,
+      "conflict",
+      "destination-conflict",
+      probe,
+    );
+    throw new Error(`Docker promotion conflicted: ${promotionIdArg}`);
+  }
+  if (classification === "inconclusive") {
+    if (!recoveredPublishingAttempt) {
+      await recordDockerPromotion(
+        optionsArg,
+        journal,
+        promotionIdArg,
+        ["publishing"],
+        attemptId,
+        "failed",
+        "verification-inconclusive",
+      );
+    }
+    throw new Error(
+      `Docker promotion probe is inconclusive: ${promotionIdArg}`,
+    );
+  }
+  if (recoveredPublishingAttempt) {
+    journal = (await finishPublishingTarget(
+      optionsArg.store,
+      journal,
+      { kind: "docker-promotion", promotionId: promotionIdArg },
+      "failed",
+      "attempt-recovery-required",
+    )) as IReleaseJournalV2;
+    promotion = journal.docker.promotions.find(
+      (promotionArg) => promotionArg.promotionId === promotionIdArg,
+    )!;
+    await optionsArg.ensurePublicationState(journal.release.mainOid);
+    journal = (await claimTarget(optionsArg.store, journal, {
+      kind: "docker-promotion",
+      promotionId: promotionIdArg,
+    })) as IReleaseJournalV2;
+    promotion = journal.docker.promotions.find(
+      (promotionArg) => promotionArg.promotionId === promotionIdArg,
+    )!;
+    attemptId = promotion.attempt!.id;
+  }
+
+  const context = getReleaseDockerPromotionContext(journal, promotionIdArg);
+  let result: TReleasePromotionEvidence;
+  try {
+    result = await requireTsdocker(optionsArg).promote(
+      journal.docker.request,
+      context,
+      getDockerRequestDirectory(optionsArg, journal),
+      attemptId,
+    );
+  } catch (error) {
+    let commandError = error;
+    if (error instanceof TsdockerReleaseRequestCleanupError) {
+      try {
+        result = await recoverRequestCleanupOutcome(
+          optionsArg,
+          journal,
+          attemptId,
+          error,
+          (valueArg) =>
+            assertReleasePromotionResult(
+              valueArg,
+              journal.docker.request,
+              context,
+            ),
+        );
+        commandError = undefined;
+      } catch (recoveredError) {
+        commandError = recoveredError;
+      }
+    }
+    if (
+      commandError instanceof TsdockerReleaseRequestCleanupError &&
+      commandError.reclamationError !== undefined
+    ) {
+      throw commandError;
+    }
+    if (commandError === undefined) {
+      classification = classifyReleasePromotionEvidence(result!);
+    } else {
+      try {
+        const reconciliation = await probeDockerPromotion(
+          optionsArg,
+          journal,
+          promotionIdArg,
+          attemptId,
+        );
+        const reconciled = classifyReleasePromotionEvidence(reconciliation);
+        if (reconciled === "exact") {
+          return recordDockerPromotion(
+            optionsArg,
+            journal,
+            promotionIdArg,
+            ["publishing"],
+            attemptId,
+            "verified",
+            null,
+            reconciliation,
+          );
+        }
+        if (reconciled === "conflict") {
+          await recordDockerPromotion(
+            optionsArg,
+            journal,
+            promotionIdArg,
+            ["publishing"],
+            attemptId,
+            "conflict",
+            "destination-conflict",
+            reconciliation,
+          );
+        }
+      } catch {
+        // Preserve publishing ownership when post-command reconciliation is unavailable.
+      }
+      throw commandError;
+    }
+  }
+
+  classification = classifyReleasePromotionEvidence(result!);
+  if (classification === "exact") {
+    return recordDockerPromotion(
+      optionsArg,
+      journal,
+      promotionIdArg,
+      ["publishing"],
+      attemptId,
+      "verified",
+      null,
+      result!,
+    );
+  }
+  if (classification === "conflict") {
+    await recordDockerPromotion(
+      optionsArg,
+      journal,
+      promotionIdArg,
+      ["publishing"],
+      attemptId,
+      "conflict",
+      "destination-conflict",
+      result!,
+    );
+    throw new Error(`Docker promotion conflicted: ${promotionIdArg}`);
+  }
+  throw new Error(
+    `Docker promotion outcome is inconclusive: ${promotionIdArg}`,
+  );
+};
+
 export const executeReleasePublication = async (
   optionsArg: IReleasePublicationOptions,
-): Promise<IReleaseJournal> => {
+): Promise<TReleaseJournal> => {
   let journal = optionsArg.journal;
+  if (journal.schemaVersion === 2) {
+    journal = await executeDockerQualification(optionsArg, journal);
+  }
   journal = await executeGitTarget(optionsArg, journal);
   const expectedRemoteMainOid =
     journal.git.state === "verified"
@@ -631,11 +1353,20 @@ export const executeReleasePublication = async (
       : journal.git.expectedRemoteMainOid || undefined;
   for (const registry of journal.npm.registries) {
     await optionsArg.ensurePublicationState(expectedRemoteMainOid);
-    journal = await executeNpmRegistry(
-      optionsArg,
-      journal,
-      registry.registry,
-    );
+    journal = await executeNpmRegistry(optionsArg, journal, registry.registry);
+  }
+  if (
+    journal.schemaVersion === 2 &&
+    journal.docker.cleanup.state !== "verified"
+  ) {
+    for (const promotion of journal.docker.promotions) {
+      journal = await executeDockerPromotion(
+        optionsArg,
+        journal,
+        promotion.promotionId,
+      );
+    }
+    journal = await executeDockerCleanup(optionsArg, journal);
   }
   return journal;
 };