@git.zone/cli 6.0.1 → 6.1.1

package/ts/mod_release/classes.releasejournal.ts

@@ -1,17 +1,28 @@
 import * as plugins from "./mod.plugins.js";
 import { InterProcessLock } from "../mod_services/classes.interprocesslock.js";
+import {
+  assertReleaseCleanupResult,
+  assertReleasePromotionEvidence,
+  assertReleaseQualificationRequest,
+  assertReleaseQualificationResult,
+  canonicalReleaseJson,
+  classifyReleasePromotionEvidence,
+  getReleasePromotionContexts,
+  type IReleaseCleanupResult,
+  type IReleasePromotionContext,
+  type IReleaseQualificationRequest,
+  type IReleaseQualificationResult,
+  type TReleasePromotionEvidence,
+} from "./helpers.tsdockerprotocol.js";
 
-export const releaseJournalSchemaVersion = 1 as const;
+export const releaseJournalStorageVersion = 1 as const;
+export const legacyReleaseJournalSchemaVersion = 1 as const;
+export const releaseJournalSchemaVersion = 2 as const;
 export const releaseArtifactFileName = "package.tgz" as const;
 export const releaseJournalFileName = "journal.json" as const;
 
 export type TReleaseTargetState =
-  | "pending"
-  | "publishing"
-  | "verified"
-  | "failed"
-  | "conflict"
-  | "skipped";
+  "pending" | "publishing" | "verified" | "failed" | "conflict" | "skipped";
 
 export type TReleaseErrorCode =
   | "command-failed"
@@ -55,7 +66,52 @@ export interface IReleaseNpmRegistryJournal extends IReleaseTargetStatus {
   registry: string;
 }
 
-export interface IReleaseJournal {
+export interface IReleaseJournalV1 {
+  kind: "gitzone-release-journal";
+  schemaVersion: typeof legacyReleaseJournalSchemaVersion;
+  revision: number;
+  release: {
+    version: string;
+    tag: string;
+    mainOid: string;
+    tagOid: string;
+  };
+  artifact: IReleaseArtifact | null;
+  git: IReleaseGitJournal;
+  npm: {
+    access: "public";
+    tag: "latest";
+    alreadyPublished: "success" | "error";
+    registries: IReleaseNpmRegistryJournal[];
+  };
+  createdAt: string;
+  updatedAt: string;
+  completedAt: string | null;
+}
+
+export interface IReleaseDockerQualificationJournal extends IReleaseTargetStatus {
+  result: IReleaseQualificationResult | null;
+}
+
+export interface IReleaseDockerPromotionJournal extends IReleaseTargetStatus {
+  promotionId: string;
+  evidence: TReleasePromotionEvidence[];
+}
+
+export interface IReleaseDockerCleanupJournal extends IReleaseTargetStatus {
+  result: IReleaseCleanupResult | null;
+}
+
+export interface IReleaseDockerJournal {
+  engine: "tsdocker";
+  protocolVersion: 1;
+  request: IReleaseQualificationRequest;
+  qualification: IReleaseDockerQualificationJournal;
+  promotions: IReleaseDockerPromotionJournal[];
+  cleanup: IReleaseDockerCleanupJournal;
+}
+
+export interface IReleaseJournalV2 {
   kind: "gitzone-release-journal";
   schemaVersion: typeof releaseJournalSchemaVersion;
   revision: number;
@@ -73,18 +129,22 @@ export interface IReleaseJournal {
     alreadyPublished: "success" | "error";
     registries: IReleaseNpmRegistryJournal[];
   };
+  docker: IReleaseDockerJournal;
   createdAt: string;
   updatedAt: string;
   completedAt: string | null;
 }
 
+export type TReleaseJournal = IReleaseJournalV1 | IReleaseJournalV2;
+
 const releaseVersionRegex = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 const gitOidRegex = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const attemptIdRegex = /^[0-9a-f]{32}$/;
 const sha1Regex = /^[0-9a-f]{40}$/;
 const sha256Regex = /^[0-9a-f]{64}$/;
 const sha512IntegrityRegex = /^sha512-[A-Za-z0-9+/]+={0,2}$/;
-const packageNameRegex = /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
+const packageNameRegex =
+  /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
 const gitRemoteNameRegex = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 const targetStates: TReleaseTargetState[] = [
   "pending",
@@ -103,7 +163,9 @@ const errorCodes: TReleaseErrorCode[] = [
   "attempt-recovery-required",
 ];
 
-const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
+const isPlainObject = (
+  valueArg: unknown,
+): valueArg is Record<string, unknown> =>
   typeof valueArg === "object" && valueArg !== null && !Array.isArray(valueArg);
 
 const isCanonicalRegistryUrl = (valueArg: string): boolean => {
@@ -135,7 +197,9 @@ const assertExactKeys = (
     actualKeys.length !== keysArg.length ||
     actualKeys.some((keyArg, indexArg) => keyArg !== keysArg[indexArg])
   ) {
-    throw new Error(`${contextArg} must use the exact canonical key set and order.`);
+    throw new Error(
+      `${contextArg} must use the exact canonical key set and order.`,
+    );
   }
 };
 
@@ -153,7 +217,9 @@ const assertIsoTimestamp = (valueArg: unknown, contextArg: string): string => {
 export const normalizeReleaseVersion = (valueArg: string): string => {
   const version = valueArg.startsWith("v") ? valueArg.slice(1) : valueArg;
   if (!releaseVersionRegex.test(version)) {
-    throw new Error("Release journal versions must use canonical x.y.z semver.");
+    throw new Error(
+      "Release journal versions must use canonical x.y.z semver.",
+    );
   }
   return version;
 };
@@ -165,7 +231,9 @@ export const normalizeReleaseGitRemoteName = (valueArg: string): string => {
     valueArg.includes("..") ||
     valueArg.endsWith("/")
   ) {
-    throw new Error("Release journals require a canonical credential-free Git remote name.");
+    throw new Error(
+      "Release journals require a canonical credential-free Git remote name.",
+    );
   }
   return valueArg;
 };
@@ -181,7 +249,9 @@ const assertTargetStatus = (
     !Number.isSafeInteger(valueArg.attempts) ||
     (valueArg.attempts as number) < 0
   ) {
-    throw new Error(`${contextArg}.attempts must be a non-negative safe integer.`);
+    throw new Error(
+      `${contextArg}.attempts must be a non-negative safe integer.`,
+    );
   }
   if (
     valueArg.error !== null &&
@@ -194,7 +264,11 @@ const assertTargetStatus = (
     if (!isPlainObject(valueArg.attempt)) {
       throw new Error(`${contextArg}.attempt is required while publishing.`);
     }
-    assertExactKeys(valueArg.attempt, ["id", "pid", "startedAt"], `${contextArg}.attempt`);
+    assertExactKeys(
+      valueArg.attempt,
+      ["id", "pid", "startedAt"],
+      `${contextArg}.attempt`,
+    );
     if (
       typeof valueArg.attempt.id !== "string" ||
       !attemptIdRegex.test(valueArg.attempt.id) ||
@@ -203,12 +277,17 @@ const assertTargetStatus = (
     ) {
       throw new Error(`${contextArg}.attempt owner is invalid.`);
     }
-    assertIsoTimestamp(valueArg.attempt.startedAt, `${contextArg}.attempt.startedAt`);
+    assertIsoTimestamp(
+      valueArg.attempt.startedAt,
+      `${contextArg}.attempt.startedAt`,
+    );
     if ((valueArg.attempts as number) < 1 || valueArg.error !== null) {
       throw new Error(`${contextArg} publishing state is inconsistent.`);
     }
   } else if (valueArg.attempt !== null) {
-    throw new Error(`${contextArg}.attempt must be null outside publishing state.`);
+    throw new Error(
+      `${contextArg}.attempt must be null outside publishing state.`,
+    );
   }
 
   if (
@@ -237,7 +316,16 @@ const assertArtifact = (valueArg: unknown): IReleaseArtifact | null => {
   }
   assertExactKeys(
     valueArg,
-    ["kind", "file", "packageName", "version", "size", "sha1", "sha256", "integrity"],
+    [
+      "kind",
+      "file",
+      "packageName",
+      "version",
+      "size",
+      "sha1",
+      "sha256",
+      "integrity",
+    ],
     "Release journal artifact",
   );
   if (
@@ -261,14 +349,30 @@ const assertArtifact = (valueArg: unknown): IReleaseArtifact | null => {
   return valueArg as unknown as IReleaseArtifact;
 };
 
-const isComplete = (journalArg: IReleaseJournal): boolean =>
-  [
+const isComplete = (journalArg: TReleaseJournal): boolean => {
+  const commonComplete = [
     journalArg.git.state,
     ...journalArg.npm.registries.map((registryArg) => registryArg.state),
   ].every((stateArg) => stateArg === "verified" || stateArg === "skipped");
+  if (
+    !commonComplete ||
+    journalArg.schemaVersion === legacyReleaseJournalSchemaVersion
+  ) {
+    return commonComplete;
+  }
+  return (
+    journalArg.docker.qualification.state === "verified" &&
+    journalArg.docker.promotions.length > 0 &&
+    journalArg.docker.promotions.every(
+      (promotionArg) => promotionArg.state === "verified",
+    ) &&
+    journalArg.docker.cleanup.state === "verified"
+  );
+};
 
-const immutableJournalIdentity = (journalArg: IReleaseJournal): string =>
+const immutableJournalIdentity = (journalArg: TReleaseJournal): string =>
   JSON.stringify({
+    schemaVersion: journalArg.schemaVersion,
     release: journalArg.release,
     artifact: journalArg.artifact,
     git: {
@@ -280,13 +384,21 @@ const immutableJournalIdentity = (journalArg: IReleaseJournal): string =>
       access: journalArg.npm.access,
       tag: journalArg.npm.tag,
       alreadyPublished: journalArg.npm.alreadyPublished,
-      registries: journalArg.npm.registries.map((registryArg) =>
-        registryArg.registry
+      registries: journalArg.npm.registries.map(
+        (registryArg) => registryArg.registry,
       ),
     },
+    docker:
+      journalArg.schemaVersion === releaseJournalSchemaVersion
+        ? {
+            engine: journalArg.docker.engine,
+            protocolVersion: journalArg.docker.protocolVersion,
+            request: journalArg.docker.request,
+          }
+        : undefined,
   });
 
-export const assertReleaseJournal = (valueArg: unknown): IReleaseJournal => {
+const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
   if (!isPlainObject(valueArg)) {
     throw new Error("Release journal root must be a JSON object.");
   }
@@ -308,7 +420,7 @@ export const assertReleaseJournal = (valueArg: unknown): IReleaseJournal => {
   );
   if (
     valueArg.kind !== "gitzone-release-journal" ||
-    valueArg.schemaVersion !== releaseJournalSchemaVersion ||
+    valueArg.schemaVersion !== legacyReleaseJournalSchemaVersion ||
     !Number.isSafeInteger(valueArg.revision) ||
     (valueArg.revision as number) < 1
   ) {
@@ -325,7 +437,8 @@ export const assertReleaseJournal = (valueArg: unknown): IReleaseJournal => {
   );
   if (
     typeof valueArg.release.version !== "string" ||
-    normalizeReleaseVersion(valueArg.release.version) !== valueArg.release.version ||
+    normalizeReleaseVersion(valueArg.release.version) !==
+      valueArg.release.version ||
     valueArg.release.tag !== `v${valueArg.release.version}` ||
     typeof valueArg.release.mainOid !== "string" ||
     !gitOidRegex.test(valueArg.release.mainOid) ||
@@ -337,7 +450,9 @@ export const assertReleaseJournal = (valueArg: unknown): IReleaseJournal => {
 
   const artifact = assertArtifact(valueArg.artifact);
   if (artifact && artifact.version !== valueArg.release.version) {
-    throw new Error("Release journal artifact version does not match the release.");
+    throw new Error(
+      "Release journal artifact version does not match the release.",
+    );
   }
 
   if (!isPlainObject(valueArg.git)) {
@@ -363,11 +478,14 @@ export const assertReleaseJournal = (valueArg: unknown): IReleaseJournal => {
       valueArg.git.destinationHash !== null ||
       valueArg.git.expectedRemoteMainOid !== null
     ) {
-      throw new Error("Skipped Git journal targets must not retain destination data.");
+      throw new Error(
+        "Skipped Git journal targets must not retain destination data.",
+      );
     }
   } else if (
     typeof valueArg.git.remote !== "string" ||
-    normalizeReleaseGitRemoteName(valueArg.git.remote) !== valueArg.git.remote ||
+    normalizeReleaseGitRemoteName(valueArg.git.remote) !==
+      valueArg.git.remote ||
     typeof valueArg.git.destinationHash !== "string" ||
     !sha256Regex.test(valueArg.git.destinationHash) ||
     typeof valueArg.git.expectedRemoteMainOid !== "string" ||
@@ -396,7 +514,9 @@ export const assertReleaseJournal = (valueArg: unknown): IReleaseJournal => {
   const registryUrls: string[] = [];
   for (const [index, rawRegistry] of valueArg.npm.registries.entries()) {
     if (!isPlainObject(rawRegistry)) {
-      throw new Error(`Release journal npm registry ${index} must be an object.`);
+      throw new Error(
+        `Release journal npm registry ${index} must be an object.`,
+      );
     }
     assertExactKeys(
       rawRegistry,
@@ -416,12 +536,441 @@ export const assertReleaseJournal = (valueArg: unknown): IReleaseJournal => {
   if (new Set(registryUrls).size !== registryUrls.length) {
     throw new Error("Release journal npm registries must be unique.");
   }
-  if ((valueArg.npm.registries.length > 0) !== Boolean(artifact)) {
-    throw new Error("Release journal npm targets and artifact must exist together.");
+  if (valueArg.npm.registries.length > 0 !== Boolean(artifact)) {
+    throw new Error(
+      "Release journal npm targets and artifact must exist together.",
+    );
+  }
+
+  const createdAt = assertIsoTimestamp(
+    valueArg.createdAt,
+    "Release journal createdAt",
+  );
+  const updatedAt = assertIsoTimestamp(
+    valueArg.updatedAt,
+    "Release journal updatedAt",
+  );
+  if (updatedAt < createdAt) {
+    throw new Error("Release journal updatedAt predates createdAt.");
+  }
+  if (valueArg.completedAt !== null) {
+    const completedAt = assertIsoTimestamp(
+      valueArg.completedAt,
+      "Release journal completedAt",
+    );
+    if (
+      completedAt < createdAt ||
+      !isComplete(valueArg as unknown as IReleaseJournalV1)
+    ) {
+      throw new Error("Release journal completion state is inconsistent.");
+    }
+    if (completedAt > updatedAt) {
+      throw new Error("Release journal completedAt exceeds updatedAt.");
+    }
+  } else if (isComplete(valueArg as unknown as IReleaseJournalV1)) {
+    throw new Error("Complete release journal must record completedAt.");
+  }
+
+  return valueArg as unknown as IReleaseJournalV1;
+};
+
+export interface IReleaseDockerPromotionContext extends IReleasePromotionContext {}
+
+const assertDockerAttemptHistory = (
+  statusArg: IReleaseTargetStatus,
+  contextArg: string,
+): void => {
+  if (statusArg.state === "pending" && statusArg.attempts !== 0) {
+    throw new Error(
+      `${contextArg} pending state cannot retain prior attempts.`,
+    );
+  }
+  if (statusArg.state !== "pending" && statusArg.attempts < 1) {
+    throw new Error(
+      `${contextArg} state requires publication attempt history.`,
+    );
+  }
+  if (
+    (statusArg.state === "conflict") !==
+    (statusArg.error === "destination-conflict")
+  ) {
+    throw new Error(
+      `${contextArg} destination-conflict must be terminal conflict state.`,
+    );
+  }
+};
+
+export const getReleaseDockerPromotionContext = (
+  journalArg: IReleaseJournalV2,
+  promotionIdArg: string,
+): IReleaseDockerPromotionContext => {
+  const result = journalArg.docker.qualification.result;
+  if (!result) {
+    throw new Error("Docker qualification evidence is not available.");
+  }
+  const context = getReleasePromotionContexts(result).find(
+    (entryArg) => entryArg.promotionId === promotionIdArg,
+  );
+  if (!context) {
+    throw new Error(
+      "Docker promotion is not part of the qualification result.",
+    );
+  }
+  return context;
+};
+
+const assertDockerJournal = (
+  valueArg: unknown,
+  releaseArg: IReleaseJournalV2["release"],
+): IReleaseDockerJournal => {
+  if (!isPlainObject(valueArg)) {
+    throw new Error("Release journal Docker target is missing.");
+  }
+  assertExactKeys(
+    valueArg,
+    [
+      "engine",
+      "protocolVersion",
+      "request",
+      "qualification",
+      "promotions",
+      "cleanup",
+    ],
+    "Release journal Docker target",
+  );
+  if (
+    valueArg.engine !== "tsdocker" ||
+    valueArg.protocolVersion !== 1 ||
+    !isPlainObject(valueArg.qualification) ||
+    !Array.isArray(valueArg.promotions) ||
+    !isPlainObject(valueArg.cleanup)
+  ) {
+    throw new Error("Release journal Docker target is invalid.");
+  }
+  const request = assertReleaseQualificationRequest(valueArg.request);
+  if (
+    request.release.version !== releaseArg.version ||
+    request.release.revision !== releaseArg.mainOid
+  ) {
+    throw new Error(
+      "Release journal Docker request does not match the release.",
+    );
+  }
+
+  assertExactKeys(
+    valueArg.qualification,
+    ["state", "attempts", "attempt", "error", "result"],
+    "Release journal Docker qualification",
+  );
+  assertTargetStatus(
+    valueArg.qualification,
+    "Release journal Docker qualification",
+  );
+  assertDockerAttemptHistory(
+    valueArg.qualification as unknown as IReleaseTargetStatus,
+    "Release journal Docker qualification",
+  );
+  if (valueArg.qualification.state === "skipped") {
+    throw new Error("Schema 2 Docker qualification cannot be skipped.");
+  }
+  const qualificationResult =
+    valueArg.qualification.result === null
+      ? null
+      : assertReleaseQualificationResult(
+          valueArg.qualification.result,
+          request,
+        );
+  if (
+    (valueArg.qualification.state === "verified") !==
+    Boolean(qualificationResult)
+  ) {
+    throw new Error(
+      "Release journal Docker qualification result is inconsistent.",
+    );
+  }
+  const promotionContexts = qualificationResult
+    ? getReleasePromotionContexts(qualificationResult)
+    : [];
+  if (valueArg.promotions.length !== promotionContexts.length) {
+    throw new Error(
+      "Release journal Docker promotions do not match qualification evidence.",
+    );
+  }
+  for (const [index, rawPromotion] of valueArg.promotions.entries()) {
+    if (!isPlainObject(rawPromotion)) {
+      throw new Error(`Release journal Docker promotion ${index} is invalid.`);
+    }
+    assertExactKeys(
+      rawPromotion,
+      ["state", "attempts", "attempt", "error", "promotionId", "evidence"],
+      `Release journal Docker promotion ${index}`,
+    );
+    assertTargetStatus(
+      rawPromotion,
+      `Release journal Docker promotion ${index}`,
+    );
+    assertDockerAttemptHistory(
+      rawPromotion as unknown as IReleaseTargetStatus,
+      `Release journal Docker promotion ${index}`,
+    );
+    if (
+      rawPromotion.state === "skipped" ||
+      rawPromotion.promotionId !== promotionContexts[index].promotionId ||
+      !Array.isArray(rawPromotion.evidence) ||
+      rawPromotion.evidence.length > 2
+    ) {
+      throw new Error(`Release journal Docker promotion ${index} is invalid.`);
+    }
+    const evidence = rawPromotion.evidence.map((entryArg) =>
+      assertReleasePromotionEvidence(
+        entryArg,
+        request,
+        promotionContexts[index],
+      ),
+    );
+    const classifications = evidence.map(classifyReleasePromotionEvidence);
+    const verifiedEvidence =
+      rawPromotion.state === "verified" &&
+      classifications.length === 1 &&
+      classifications[0] === "exact";
+    const initialConflictEvidence =
+      rawPromotion.state === "conflict" &&
+      classifications.length === 1 &&
+      classifications[0] === "conflict";
+    const verifiedDriftEvidence =
+      rawPromotion.state === "conflict" &&
+      classifications.length === 2 &&
+      classifications[0] === "exact" &&
+      (classifications[1] === "pending" || classifications[1] === "conflict");
+    const noEvidenceExpected =
+      (rawPromotion.state === "pending" ||
+        rawPromotion.state === "publishing" ||
+        rawPromotion.state === "failed") &&
+      classifications.length === 0;
+    if (
+      (!verifiedEvidence &&
+        !initialConflictEvidence &&
+        !verifiedDriftEvidence &&
+        !noEvidenceExpected) ||
+      (rawPromotion.state === "conflict" &&
+        rawPromotion.error !== "destination-conflict")
+    ) {
+      throw new Error(
+        `Release journal Docker promotion ${index} evidence is inconsistent.`,
+      );
+    }
   }
 
-  const createdAt = assertIsoTimestamp(valueArg.createdAt, "Release journal createdAt");
-  const updatedAt = assertIsoTimestamp(valueArg.updatedAt, "Release journal updatedAt");
+  assertExactKeys(
+    valueArg.cleanup,
+    ["state", "attempts", "attempt", "error", "result"],
+    "Release journal Docker cleanup",
+  );
+  assertTargetStatus(valueArg.cleanup, "Release journal Docker cleanup");
+  assertDockerAttemptHistory(
+    valueArg.cleanup as unknown as IReleaseTargetStatus,
+    "Release journal Docker cleanup",
+  );
+  if (
+    valueArg.cleanup.state === "skipped" ||
+    valueArg.cleanup.state === "conflict"
+  ) {
+    throw new Error("Release journal Docker cleanup state is invalid.");
+  }
+  const cleanupResult =
+    valueArg.cleanup.result === null
+      ? null
+      : assertReleaseCleanupResult(valueArg.cleanup.result, request);
+  if ((valueArg.cleanup.state === "verified") !== Boolean(cleanupResult)) {
+    throw new Error("Release journal Docker cleanup result is inconsistent.");
+  }
+  const promotionsVerified =
+    valueArg.promotions.length > 0 &&
+    valueArg.promotions.every(
+      (promotionArg) =>
+        isPlainObject(promotionArg) && promotionArg.state === "verified",
+    );
+  const qualificationConflictCleanup =
+    valueArg.qualification.state === "conflict" &&
+    valueArg.qualification.error === "destination-conflict" &&
+    valueArg.promotions.length === 0;
+  if (
+    (valueArg.cleanup.state === "publishing" ||
+      valueArg.cleanup.state === "verified") &&
+    !promotionsVerified &&
+    !qualificationConflictCleanup
+  ) {
+    throw new Error(
+      "Release journal Docker cleanup requires verified promotions or a terminal qualification conflict.",
+    );
+  }
+  return valueArg as unknown as IReleaseDockerJournal;
+};
+
+const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
+  if (!isPlainObject(valueArg)) {
+    throw new Error("Release journal root must be a JSON object.");
+  }
+  assertExactKeys(
+    valueArg,
+    [
+      "kind",
+      "schemaVersion",
+      "revision",
+      "release",
+      "artifact",
+      "git",
+      "npm",
+      "docker",
+      "createdAt",
+      "updatedAt",
+      "completedAt",
+    ],
+    "Release journal",
+  );
+  if (
+    valueArg.kind !== "gitzone-release-journal" ||
+    valueArg.schemaVersion !== releaseJournalSchemaVersion ||
+    !Number.isSafeInteger(valueArg.revision) ||
+    (valueArg.revision as number) < 1
+  ) {
+    throw new Error("Release journal header is invalid or unsupported.");
+  }
+  if (!isPlainObject(valueArg.release)) {
+    throw new Error("Release journal release identity is missing.");
+  }
+  assertExactKeys(
+    valueArg.release,
+    ["version", "tag", "mainOid", "tagOid"],
+    "Release journal release",
+  );
+  if (
+    typeof valueArg.release.version !== "string" ||
+    normalizeReleaseVersion(valueArg.release.version) !==
+      valueArg.release.version ||
+    valueArg.release.tag !== `v${valueArg.release.version}` ||
+    typeof valueArg.release.mainOid !== "string" ||
+    !gitOidRegex.test(valueArg.release.mainOid) ||
+    typeof valueArg.release.tagOid !== "string" ||
+    !gitOidRegex.test(valueArg.release.tagOid)
+  ) {
+    throw new Error("Release journal Git identity is invalid.");
+  }
+  const artifact = assertArtifact(valueArg.artifact);
+  if (artifact && artifact.version !== valueArg.release.version) {
+    throw new Error(
+      "Release journal artifact version does not match the release.",
+    );
+  }
+  if (!isPlainObject(valueArg.git)) {
+    throw new Error("Release journal Git target is missing.");
+  }
+  assertExactKeys(
+    valueArg.git,
+    [
+      "state",
+      "attempts",
+      "attempt",
+      "error",
+      "remote",
+      "destinationHash",
+      "expectedRemoteMainOid",
+    ],
+    "Release journal Git target",
+  );
+  assertTargetStatus(valueArg.git, "Release journal Git target");
+  if (valueArg.git.state === "skipped") {
+    if (
+      valueArg.git.remote !== null ||
+      valueArg.git.destinationHash !== null ||
+      valueArg.git.expectedRemoteMainOid !== null
+    ) {
+      throw new Error(
+        "Skipped Git journal targets must not retain destination data.",
+      );
+    }
+  } else if (
+    typeof valueArg.git.remote !== "string" ||
+    normalizeReleaseGitRemoteName(valueArg.git.remote) !==
+      valueArg.git.remote ||
+    typeof valueArg.git.destinationHash !== "string" ||
+    !sha256Regex.test(valueArg.git.destinationHash) ||
+    typeof valueArg.git.expectedRemoteMainOid !== "string" ||
+    !gitOidRegex.test(valueArg.git.expectedRemoteMainOid)
+  ) {
+    throw new Error("Active Git journal target destination data is invalid.");
+  }
+  if (!isPlainObject(valueArg.npm)) {
+    throw new Error("Release journal npm target is missing.");
+  }
+  assertExactKeys(
+    valueArg.npm,
+    ["access", "tag", "alreadyPublished", "registries"],
+    "Release journal npm target",
+  );
+  if (
+    valueArg.npm.access !== "public" ||
+    valueArg.npm.tag !== "latest" ||
+    (valueArg.npm.alreadyPublished !== "success" &&
+      valueArg.npm.alreadyPublished !== "error") ||
+    !Array.isArray(valueArg.npm.registries)
+  ) {
+    throw new Error("Release journal npm settings are invalid.");
+  }
+  const registryUrls: string[] = [];
+  for (const [index, rawRegistry] of valueArg.npm.registries.entries()) {
+    if (!isPlainObject(rawRegistry)) {
+      throw new Error(
+        `Release journal npm registry ${index} must be an object.`,
+      );
+    }
+    assertExactKeys(
+      rawRegistry,
+      ["state", "attempts", "attempt", "error", "registry"],
+      `Release journal npm registry ${index}`,
+    );
+    assertTargetStatus(rawRegistry, `Release journal npm registry ${index}`);
+    if (
+      typeof rawRegistry.registry !== "string" ||
+      !isCanonicalRegistryUrl(rawRegistry.registry) ||
+      rawRegistry.state === "skipped"
+    ) {
+      throw new Error(`Release journal npm registry ${index} URL is invalid.`);
+    }
+    registryUrls.push(rawRegistry.registry);
+  }
+  if (new Set(registryUrls).size !== registryUrls.length) {
+    throw new Error("Release journal npm registries must be unique.");
+  }
+  if (valueArg.npm.registries.length > 0 !== Boolean(artifact)) {
+    throw new Error(
+      "Release journal npm targets and artifact must exist together.",
+    );
+  }
+  const docker = assertDockerJournal(
+    valueArg.docker,
+    valueArg.release as unknown as IReleaseJournalV2["release"],
+  );
+  const activePublishers = [
+    valueArg.git as unknown as IReleaseTargetStatus,
+    ...(valueArg.npm.registries as unknown as IReleaseTargetStatus[]),
+    docker.qualification,
+    ...docker.promotions,
+    docker.cleanup,
+  ].filter((statusArg) => statusArg.state === "publishing");
+  if (activePublishers.length > 1) {
+    throw new Error(
+      "Schema 2 release journals permit at most one active publication owner.",
+    );
+  }
+  const createdAt = assertIsoTimestamp(
+    valueArg.createdAt,
+    "Release journal createdAt",
+  );
+  const updatedAt = assertIsoTimestamp(
+    valueArg.updatedAt,
+    "Release journal updatedAt",
+  );
   if (updatedAt < createdAt) {
     throw new Error("Release journal updatedAt predates createdAt.");
   }
@@ -430,23 +979,73 @@ export const assertReleaseJournal = (valueArg: unknown): IReleaseJournal => {
       valueArg.completedAt,
       "Release journal completedAt",
     );
-    if (completedAt < createdAt || !isComplete(valueArg as unknown as IReleaseJournal)) {
+    if (
+      completedAt < createdAt ||
+      !isComplete(valueArg as unknown as IReleaseJournalV2)
+    ) {
       throw new Error("Release journal completion state is inconsistent.");
     }
     if (completedAt > updatedAt) {
       throw new Error("Release journal completedAt exceeds updatedAt.");
     }
-  } else if (isComplete(valueArg as unknown as IReleaseJournal)) {
+  } else if (isComplete(valueArg as unknown as IReleaseJournalV2)) {
     throw new Error("Complete release journal must record completedAt.");
   }
+  return valueArg as unknown as IReleaseJournalV2;
+};
+
+export const assertReleaseJournal = (valueArg: unknown): TReleaseJournal => {
+  if (!isPlainObject(valueArg)) {
+    throw new Error("Release journal root must be a JSON object.");
+  }
+  if (valueArg.schemaVersion === legacyReleaseJournalSchemaVersion) {
+    return assertReleaseJournalV1(valueArg);
+  }
+  if (valueArg.schemaVersion === releaseJournalSchemaVersion) {
+    return assertReleaseJournalV2(valueArg);
+  }
+  throw new Error("Release journal header is invalid or unsupported.");
+};
+
+const canonicalizeProtocolValue = <T>(valueArg: T): T =>
+  JSON.parse(canonicalReleaseJson(valueArg)) as T;
 
-  return valueArg as unknown as IReleaseJournal;
+const prepareReleaseJournalSerialization = (
+  journalArg: TReleaseJournal,
+): TReleaseJournal => {
+  const journal = assertReleaseJournal(journalArg);
+  if (journal.schemaVersion === legacyReleaseJournalSchemaVersion) {
+    return journal;
+  }
+  return {
+    ...journal,
+    docker: {
+      ...journal.docker,
+      request: canonicalizeProtocolValue(journal.docker.request),
+      qualification: {
+        ...journal.docker.qualification,
+        result: journal.docker.qualification.result
+          ? canonicalizeProtocolValue(journal.docker.qualification.result)
+          : null,
+      },
+      promotions: journal.docker.promotions.map((promotionArg) => ({
+        ...promotionArg,
+        evidence: promotionArg.evidence.map(canonicalizeProtocolValue),
+      })),
+      cleanup: {
+        ...journal.docker.cleanup,
+        result: journal.docker.cleanup.result
+          ? canonicalizeProtocolValue(journal.docker.cleanup.result)
+          : null,
+      },
+    },
+  };
 };
 
-export const serializeReleaseJournal = (journalArg: IReleaseJournal): string =>
-  `${JSON.stringify(assertReleaseJournal(journalArg), null, 2)}\n`;
+export const serializeReleaseJournal = (journalArg: TReleaseJournal): string =>
+  `${JSON.stringify(prepareReleaseJournalSerialization(journalArg), null, 2)}\n`;
 
-export const parseReleaseJournal = (contentArg: string): IReleaseJournal => {
+export const parseReleaseJournal = (contentArg: string): TReleaseJournal => {
   let parsed: unknown;
   try {
     parsed = JSON.parse(contentArg);
@@ -462,6 +1061,173 @@ export const parseReleaseJournal = (contentArg: string): IReleaseJournal => {
   return journal;
 };
 
+const assertDockerStatusAppendOnly = (
+  currentArg: IReleaseTargetStatus,
+  nextArg: IReleaseTargetStatus,
+  contextArg: string,
+  optionsArg: { allowVerifiedConflict?: boolean } = {},
+): void => {
+  if (currentArg.state === nextArg.state) {
+    if (canonicalReleaseJson(currentArg) !== canonicalReleaseJson(nextArg)) {
+      throw new Error(
+        `${contextArg} cannot change without a state transition.`,
+      );
+    }
+    return;
+  }
+  if (
+    (currentArg.state === "pending" || currentArg.state === "failed") &&
+    nextArg.state === "publishing" &&
+    nextArg.attempts === currentArg.attempts + 1
+  ) {
+    return;
+  }
+  if (
+    currentArg.state === "publishing" &&
+    (nextArg.state === "verified" ||
+      nextArg.state === "failed" ||
+      nextArg.state === "conflict") &&
+    nextArg.attempts === currentArg.attempts
+  ) {
+    return;
+  }
+  if (
+    optionsArg.allowVerifiedConflict &&
+    currentArg.state === "verified" &&
+    nextArg.state === "conflict" &&
+    nextArg.attempts === currentArg.attempts
+  ) {
+    return;
+  }
+  throw new Error(`${contextArg} state transition is not append-only.`);
+};
+
+const assertSchema2AppendOnlyTransition = (
+  currentArg: IReleaseJournalV2,
+  nextArg: IReleaseJournalV2,
+): void => {
+  const currentDocker = currentArg.docker;
+  const nextDocker = nextArg.docker;
+  if (
+    currentDocker.qualification.state === "conflict" &&
+    canonicalReleaseJson(currentDocker.qualification) !==
+      canonicalReleaseJson(nextDocker.qualification)
+  ) {
+    throw new Error("Docker qualification conflict is terminal.");
+  }
+  assertDockerStatusAppendOnly(
+    currentDocker.qualification,
+    nextDocker.qualification,
+    "Docker qualification",
+  );
+  if (
+    currentDocker.qualification.result &&
+    canonicalReleaseJson(currentDocker.qualification.result) !==
+      canonicalReleaseJson(nextDocker.qualification.result)
+  ) {
+    throw new Error("Docker qualification evidence is append-only.");
+  }
+  if (
+    currentDocker.qualification.result &&
+    nextDocker.qualification.state !== "verified"
+  ) {
+    throw new Error("Verified Docker qualification cannot regress.");
+  }
+  if (
+    !currentDocker.qualification.result &&
+    nextDocker.qualification.result &&
+    (currentDocker.qualification.state !== "publishing" ||
+      nextDocker.qualification.state !== "verified")
+  ) {
+    throw new Error(
+      "Docker qualification evidence requires its owned publishing transition.",
+    );
+  }
+  if (
+    currentDocker.promotions.length === 0 &&
+    nextDocker.promotions.length > 0
+  ) {
+    if (
+      currentDocker.qualification.state !== "publishing" ||
+      nextDocker.qualification.state !== "verified" ||
+      nextDocker.promotions.some(
+        (promotionArg) =>
+          promotionArg.state !== "pending" ||
+          promotionArg.attempts !== 0 ||
+          promotionArg.attempt !== null ||
+          promotionArg.error !== null ||
+          promotionArg.evidence.length !== 0,
+      )
+    ) {
+      throw new Error(
+        "Docker promotions must begin pending with no attempt or evidence.",
+      );
+    }
+  } else if (currentDocker.promotions.length > 0) {
+    if (
+      currentDocker.promotions.length !== nextDocker.promotions.length ||
+      currentDocker.promotions.some(
+        (promotionArg, indexArg) =>
+          promotionArg.promotionId !==
+          nextDocker.promotions[indexArg]?.promotionId,
+      )
+    ) {
+      throw new Error("Docker promotion identity is append-only.");
+    }
+    for (const [
+      index,
+      currentPromotion,
+    ] of currentDocker.promotions.entries()) {
+      const nextPromotion = nextDocker.promotions[index];
+      if (
+        currentPromotion.state === "conflict" &&
+        canonicalReleaseJson(currentPromotion) !==
+          canonicalReleaseJson(nextPromotion)
+      ) {
+        throw new Error(
+          `Docker promotion ${currentPromotion.promotionId} conflict is terminal.`,
+        );
+      }
+      assertDockerStatusAppendOnly(
+        currentPromotion,
+        nextPromotion,
+        `Docker promotion ${currentPromotion.promotionId}`,
+        { allowVerifiedConflict: true },
+      );
+      if (
+        nextPromotion.evidence.length < currentPromotion.evidence.length ||
+        currentPromotion.evidence.some(
+          (evidenceArg, evidenceIndexArg) =>
+            canonicalReleaseJson(evidenceArg) !==
+            canonicalReleaseJson(nextPromotion.evidence[evidenceIndexArg]),
+        )
+      ) {
+        throw new Error(
+          `Docker promotion ${currentPromotion.promotionId} evidence is append-only.`,
+        );
+      }
+    }
+  }
+  assertDockerStatusAppendOnly(
+    currentDocker.cleanup,
+    nextDocker.cleanup,
+    "Docker cleanup",
+  );
+  if (
+    currentDocker.cleanup.result &&
+    canonicalReleaseJson(currentDocker.cleanup.result) !==
+      canonicalReleaseJson(nextDocker.cleanup.result)
+  ) {
+    throw new Error("Docker cleanup evidence is append-only.");
+  }
+  if (
+    currentDocker.cleanup.state === "verified" &&
+    canonicalReleaseJson(currentDocker) !== canonicalReleaseJson(nextDocker)
+  ) {
+    throw new Error("Completed Docker publication state is terminal.");
+  }
+};
+
 export const createReleaseAttempt = (): IReleaseAttempt => ({
   id: plugins.crypto.randomBytes(16).toString("hex"),
   pid: process.pid,
@@ -497,7 +1263,9 @@ export const resolveGitCommonDirectory = async (
     !plugins.path.isAbsolute(commonDirectory) ||
     !commonDirectory
   ) {
-    throw new Error("Unable to resolve the Git common directory for release state.");
+    throw new Error(
+      "Unable to resolve the Git common directory for release state.",
+    );
   }
   return plugins.path.resolve(commonDirectory);
 };
@@ -507,13 +1275,15 @@ export class ReleaseJournalStore {
 
   constructor(gitCommonDirectoryArg: string) {
     if (!plugins.path.isAbsolute(gitCommonDirectoryArg)) {
-      throw new Error("Release journal storage requires an absolute Git common directory.");
+      throw new Error(
+        "Release journal storage requires an absolute Git common directory.",
+      );
     }
     this.rootPath = plugins.path.join(
       plugins.path.resolve(gitCommonDirectoryArg),
       "gitzone",
       "releases",
-      `v${releaseJournalSchemaVersion}`,
+      `v${releaseJournalStorageVersion}`,
     );
   }
 
@@ -532,10 +1302,12 @@ export class ReleaseJournalStore {
   public async createTemporaryDirectory(versionArg: string): Promise<string> {
     const version = normalizeReleaseVersion(versionArg);
     await plugins.fs.mkdir(this.rootPath, { recursive: true, mode: 0o700 });
-    return plugins.fs.mkdtemp(plugins.path.join(this.rootPath, `.v${version}.tmp-`));
+    return plugins.fs.mkdtemp(
+      plugins.path.join(this.rootPath, `.v${version}.tmp-`),
+    );
   }
 
-  public async read(versionArg: string): Promise<IReleaseJournal> {
+  public async read(versionArg: string): Promise<TReleaseJournal> {
     const version = normalizeReleaseVersion(versionArg);
     const filePath = plugins.path.join(
       this.getReleaseDirectory(version),
@@ -543,7 +1315,18 @@ export class ReleaseJournalStore {
     );
     let content: string;
     try {
-      content = await plugins.fs.readFile(filePath, "utf8");
+      const bytes = await plugins.fs.readFile(filePath);
+      if (
+        bytes.byteLength >= 3 &&
+        bytes[0] === 0xef &&
+        bytes[1] === 0xbb &&
+        bytes[2] === 0xbf
+      ) {
+        throw new Error(
+          "Release journal must not contain a UTF-8 byte-order mark.",
+        );
+      }
+      content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") {
         throw new Error(`Release journal v${version} does not exist.`);
@@ -559,10 +1342,12 @@ export class ReleaseJournalStore {
     return journal;
   }
 
-  public async list(): Promise<IReleaseJournal[]> {
+  public async list(): Promise<TReleaseJournal[]> {
     let entries: Array<{ name: string; isDirectory: () => boolean }>;
     try {
-      entries = await plugins.fs.readdir(this.rootPath, { withFileTypes: true });
+      entries = await plugins.fs.readdir(this.rootPath, {
+        withFileTypes: true,
+      });
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") {
         return [];
@@ -572,9 +1357,12 @@ export class ReleaseJournalStore {
       });
     }
     const versions = entries
-      .filter((entryArg) => entryArg.isDirectory() && /^v\d+\.\d+\.\d+$/.test(entryArg.name))
+      .filter(
+        (entryArg) =>
+          entryArg.isDirectory() && /^v\d+\.\d+\.\d+$/.test(entryArg.name),
+      )
       .map((entryArg) => entryArg.name.slice(1));
-    const journals: IReleaseJournal[] = [];
+    const journals: TReleaseJournal[] = [];
     for (const version of versions) {
       journals.push(await this.read(version));
     }
@@ -585,18 +1373,51 @@ export class ReleaseJournalStore {
 
   public async installPrepared(
     temporaryDirectoryArg: string,
-    journalArg: IReleaseJournal,
-  ): Promise<IReleaseJournal> {
+    journalArg: TReleaseJournal,
+  ): Promise<TReleaseJournal> {
     const journal = assertReleaseJournal(journalArg);
     if (journal.revision !== 1) {
       throw new Error("New release journals must start at revision 1.");
     }
+    if (journal.schemaVersion === releaseJournalSchemaVersion) {
+      const commonTargets = [journal.git, ...journal.npm.registries];
+      const commonTargetsUnclaimed = commonTargets.every(
+        (targetArg) =>
+          (targetArg.state === "pending" || targetArg.state === "skipped") &&
+          targetArg.attempts === 0 &&
+          targetArg.attempt === null &&
+          targetArg.error === null,
+      );
+      if (
+        !commonTargetsUnclaimed ||
+        journal.completedAt !== null ||
+        journal.docker.qualification.state !== "pending" ||
+        journal.docker.qualification.attempts !== 0 ||
+        journal.docker.qualification.attempt !== null ||
+        journal.docker.qualification.error !== null ||
+        journal.docker.qualification.result !== null ||
+        journal.docker.promotions.length !== 0 ||
+        journal.docker.cleanup.state !== "pending" ||
+        journal.docker.cleanup.attempts !== 0 ||
+        journal.docker.cleanup.attempt !== null ||
+        journal.docker.cleanup.error !== null ||
+        journal.docker.cleanup.result !== null
+      ) {
+        throw new Error(
+          "New schema 2 release journals must start with unclaimed publication targets.",
+        );
+      }
+    }
     const temporaryDirectory = plugins.path.resolve(temporaryDirectoryArg);
     if (
       plugins.path.dirname(temporaryDirectory) !== this.rootPath ||
-      !plugins.path.basename(temporaryDirectory).startsWith(`.v${journal.release.version}.tmp-`)
+      !plugins.path
+        .basename(temporaryDirectory)
+        .startsWith(`.v${journal.release.version}.tmp-`)
     ) {
-      throw new Error("Prepared release directory is outside canonical storage.");
+      throw new Error(
+        "Prepared release directory is outside canonical storage.",
+      );
     }
     if (journal.artifact) {
       const artifactPath = plugins.path.join(
@@ -610,14 +1431,20 @@ export class ReleaseJournalStore {
       const artifactBytes = await plugins.fs.readFile(artifactPath);
       if (
         artifactBytes.byteLength !== journal.artifact.size ||
-        plugins.crypto.createHash("sha1").update(artifactBytes).digest("hex") !==
-          journal.artifact.sha1 ||
-        plugins.crypto.createHash("sha256").update(artifactBytes).digest("hex") !==
-          journal.artifact.sha256 ||
+        plugins.crypto
+          .createHash("sha1")
+          .update(artifactBytes)
+          .digest("hex") !== journal.artifact.sha1 ||
+        plugins.crypto
+          .createHash("sha256")
+          .update(artifactBytes)
+          .digest("hex") !== journal.artifact.sha256 ||
         `sha512-${plugins.crypto.createHash("sha512").update(artifactBytes).digest("base64")}` !==
           journal.artifact.integrity
       ) {
-        throw new Error("Prepared release artifact does not match its journal identity.");
+        throw new Error(
+          "Prepared release artifact does not match its journal identity.",
+        );
       }
     }
 
@@ -659,8 +1486,8 @@ export class ReleaseJournalStore {
   public async transact(
     versionArg: string,
     expectedRevisionArg: number,
-    operationArg: (journalArg: IReleaseJournal) => IReleaseJournal,
-  ): Promise<IReleaseJournal> {
+    operationArg: (journalArg: TReleaseJournal) => TReleaseJournal,
+  ): Promise<TReleaseJournal> {
     const version = normalizeReleaseVersion(versionArg);
     const releaseDirectory = this.getReleaseDirectory(version);
     const lock = new InterProcessLock({
@@ -682,8 +1509,18 @@ export class ReleaseJournalStore {
         createdAt: current.createdAt,
         updatedAt: now,
       });
-      if (immutableJournalIdentity(next) !== immutableJournalIdentity(current)) {
-        throw new Error("Release journal immutable identity changed during a transaction.");
+      if (
+        immutableJournalIdentity(next) !== immutableJournalIdentity(current)
+      ) {
+        throw new Error(
+          "Release journal immutable identity changed during a transaction.",
+        );
+      }
+      if (
+        current.schemaVersion === releaseJournalSchemaVersion &&
+        next.schemaVersion === releaseJournalSchemaVersion
+      ) {
+        assertSchema2AppendOnlyTransition(current, next);
       }
       await this.writeAtomic(version, next);
       return next;
@@ -692,10 +1529,13 @@ export class ReleaseJournalStore {
 
   private async writeAtomic(
     versionArg: string,
-    journalArg: IReleaseJournal,
+    journalArg: TReleaseJournal,
   ): Promise<void> {
     const releaseDirectory = this.getReleaseDirectory(versionArg);
-    const journalPath = plugins.path.join(releaseDirectory, releaseJournalFileName);
+    const journalPath = plugins.path.join(
+      releaseDirectory,
+      releaseJournalFileName,
+    );
     const temporaryPath = plugins.path.join(
       releaseDirectory,
       `.journal.tmp-${process.pid}-${plugins.crypto.randomBytes(12).toString("hex")}`,
@@ -712,9 +1552,12 @@ export class ReleaseJournalStore {
     } catch (error) {
       await handle?.close().catch(() => {});
       await plugins.fs.rm(temporaryPath, { force: true }).catch(() => {});
-      throw new Error(`Release journal v${versionArg} could not be updated atomically.`, {
-        cause: error,
-      });
+      throw new Error(
+        `Release journal v${versionArg} could not be updated atomically.`,
+        {
+          cause: error,
+        },
+      );
     }
   }
 }
@@ -728,10 +1571,36 @@ export const createInitialTargetStatus = (
   error: null,
 });
 
+export const createInitialReleaseDockerJournal = (
+  requestArg: IReleaseQualificationRequest,
+): IReleaseDockerJournal => ({
+  engine: "tsdocker",
+  protocolVersion: 1,
+  request: assertReleaseQualificationRequest(requestArg),
+  qualification: {
+    ...createInitialTargetStatus(true),
+    result: null,
+  },
+  promotions: [],
+  cleanup: {
+    ...createInitialTargetStatus(true),
+    result: null,
+  },
+});
+
+export const createReleaseDockerPromotions = (
+  resultArg: IReleaseQualificationResult,
+): IReleaseDockerPromotionJournal[] =>
+  getReleasePromotionContexts(resultArg).map((contextArg) => ({
+    ...createInitialTargetStatus(true),
+    promotionId: contextArg.promotionId,
+    evidence: [],
+  }));
+
 export const finalizeJournalCompletion = (
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   completedAtArg = new Date().toISOString(),
-): IReleaseJournal => {
+): TReleaseJournal => {
   const completed = isComplete(journalArg);
   return {
     ...journalArg,