@arc-e-tect/api-only-publisher 0.16.1 → 0.17.0

package/README.adoc

@@ -6,7 +6,7 @@
 :source-highlighter: rouge
 // The released version of this component: its snippets use it. The release
 // workflow updates it; do not change it by hand.
-:api-only-publisher-version: 0.16.1
+:api-only-publisher-version: 0.17.0
 
 [NOTE]
 .About this documentation
@@ -191,11 +191,16 @@ Without `--target`, it also fails on a fragment no target reaches, as <<unrefere
 |Report which targets' closures changed between a git ref and the working tree.
 A target whose closure is untouched needs no new version, however much else in the repository moved.
 
+|`check [--target <t>]... [--pre-release <ids>] [--since <ref>]`
+|Fail on every published target that changed without a new version, from git alone, as <<version-guard,A changed target needs a new version §>> describes.
+Made for a pull request's pipeline: no network, no credentials, nothing built.
+
 |`pack [--pre-release <ids>] [--target <t>]... [--out <dir>]`
 |Archive each built, published target with a `manifest.json`, at the version its version file declares.
 
-|`publish [--pre-release <ids>] [--target <t>]... [--channel <c>]... [--out <dir>]`
-|Pack each target once, then ship those same bytes to each of its channels, or only to those of them each `--channel` names (<<channel-routing,Which channels a target goes to §>>).
+|`publish [--pre-release <ids>] [--target <t>]... [--channel <c>]... [--since <ref>] [--out <dir>]`
+|Check every target as `check` does, then pack each target once and ship those same bytes to each of its channels, or only to those of them each `--channel` names (<<channel-routing,Which channels a target goes to §>>).
+A channel that cannot take a version is a warning, not a failure (<<channel-problems,When a channel cannot take a version §>>).
 
 |`split [--out <dir>] [--by kind\|target]`
 |Make the library safe to break into separate repositories.
@@ -212,6 +217,7 @@ A target whose closure is untouched needs no new version, however much else in t
 npm run apionly -- build --target orders --openapi
 npm run apionly -- publish --target orders --pre-release rc.1
 npm run apionly -- changed --since origin/main --quiet
+npm run apionly -- check
 ----
 
 [#init]
@@ -408,7 +414,54 @@ Cutting one never means editing the file, and then remembering to edit it back,
 
 A version names one set of documents.
 Publishing different documents under a version that was published before, after editing a fragment without changing the version file, is refused by the API-Only Subscriber in every project that locked the earlier ones.
-Change the version in the same commit as the fragments instead.
+Change the version in the same commit as the fragments instead; `check` and `publish` refuse a target that does not (<<version-guard,A changed target needs a new version §>>).
+
+[#version-guard]
+=== A changed target needs a new version
+
+`check` decides, for every published target, whether its version may be published, and fails naming each one that may not.
+`publish` decides the same before it packs or sends anything, so a target that fails it is never published anywhere.
+Both read only git: the target's release tags, its history, and the working tree, changes not yet committed included.
+
+[cols="1,3", options="header"]
+|===
+|What git tells |What `check` requires
+
+|A release tag for this exact version
+|The target unchanged since that tag: the version was released from what the tag points at, and publishing it again is safe only with the same specifications.
+
+|Release tags, but none for this version
+|A version above the latest release; one below it is refused.
+
+|No release tags at all
+|Compared with the merge-base with the main branch, or with the ref `--since` names: a target changed since then needs a higher version than its version file declared there, and a version lower than it was there is refused.
+A target whose version file was not there yet is new, and passes.
+|===
+
+Release tags are named by `versioning.tagFormat`, `{target}-v{version}` by default: `orders-v2.1.0`.
+The Publisher never creates them: the pipeline that publishes does, after it has published, because a tool that pushes to git needs write access to the repository it builds from.
+The reference pipelines show the step, and the `gitlab-package` channel's `release: true` creates the tag with the release.
+The main branch is `versioning.mainBranch`, `main` by default; its remote-tracking branch, `origin/main`, is preferred, as that is what a CI checkout has.
+
+A pre-release follows the same rules, by its full version:
+
+* Its version file need not change: `--pre-release rc.2` already makes a new version, so a target changed since the main branch passes with an unchanged file.
+* A pre-release that was released before -- a tag `orders-v2.1.0-rc.1` -- is refused when the target changed since, as a release is.
+* A pre-release of a version already released is refused: `2.1.0-rc.1` sorts before `2.1.0`, so it can never be the next version.
+
+Where the guard cannot decide, it says so, and only `check` fails on it: `check` is the gate, while `publish` fails on a proven violation alone.
+Outside a git repository, `check` fails and `publish` warns that the versions were not checked.
+A target with no release tag, in a checkout that has no merge-base with the main branch -- a shallow clone, or no main branch at all -- is `undecided`: `check` fails naming it, and `publish` warns and publishes it; a target with a release tag is decided all the same.
+In CI, fetch the full history and the tags -- `actions/checkout` with `fetch-depth: 0`, or `GIT_DEPTH: 0` on GitLab -- so that nothing is left undecided.
+Without release tags, the check on the main branch itself compares the main branch with itself, so it is in the pull request that it catches a missing bump; the tags are what make it exact everywhere.
+
+To catch it before a push, call `check` from whatever runs the repository's git hooks -- a `pre-push` hook, or a hook manager such as husky or lefthook:
+
+[source,sh]
+----
+#!/bin/sh
+exec npx --no-install api-only-publisher check
+----
 
 [#closure]
 == Independent versioning, and the dependency closure
@@ -638,7 +691,7 @@ Configured portfolio: paths=none, location=portfolios
 |`file`
 |A local directory, laid out as `<directory>/<target>/<version>/`.
 Not a distribution mechanism between repositories: it makes the pipeline testable end to end with no infrastructure, lets a library share one build with the projects that implement it, and is a local-iteration escape hatch.
-Publishing a version again writes it again and keeps the others (<<idempotent,Publishing the same version again §>>); with `clean: true` only the version being published is kept, for a directory that is a build output rather than a record of releases.
+Like a registry, it never replaces a version it holds with other documents (<<idempotent,Publishing the same version again §>>); with `clean: true` only the version being published is kept, for a directory that is a build output rather than a record of releases.
 
 |`maven`
 |A path publishes into a repository layout on disk; an `http(s)` URL deploys to a remote repository with an HTTP `PUT` per file, and keeps its `maven-metadata.xml` (<<maven-remote,Publishing to a remote Maven repository §>>).
@@ -700,9 +753,13 @@ A run that would publish nothing at all fails instead of succeeding quietly.
 [#idempotent]
 === Publishing the same version again
 
-`publish` is idempotent: publishing a version again with the same content changes nothing, on every channel.
+`publish` is idempotent: publishing a version again with the same documents changes nothing, on every channel.
+
+A published version is its documents: the names and SHA-256 hashes that `manifest.json` lists under `files`, which are exactly what a subscriber records in its lockfile.
+A remote channel compares those, not the bytes of what it holds.
+The manifest also records the commit a version was packed from, and that commit's time, so the same documents packed from a later commit are another archive, and the same version.
 
-That rests on `pack` being reproducible.
+Packing the same commit again gives the same bytes, because `pack` is reproducible.
 The same documents always pack to the same archive, byte for byte: the archive is written with a fixed mode, no owner and a fixed timestamp, and `manifest.json`'s `producedAt` is not the time `pack` ran but the time of the commit being packed.
 Set `SOURCE_DATE_EPOCH` (seconds since 1970, the https://reproducible-builds.org/specs/source-date-epoch/[reproducible-builds convention ↗]) to choose another; outside a git repository, where there is no commit, it is the only way to make two packs identical, and without it `producedAt` is the current time.
 
@@ -712,17 +769,43 @@ What happens when the destination already has the version:
 |===
 |Destination |Already has the version
 
-|`file`; `maven` and `nuget` to a directory; `npm` with `publish: false`
+|`maven` and `nuget` to a directory; `npm` with `publish: false`
 |Written again. With the same content the bytes are the same; with different content the version is replaced, and every subscriber whose lockfile recorded the old bytes fails its build until the change is published as a new version.
 
-|`maven` and `nuget` to a URL, `npm`, `github-release`, `gitlab-package`
-|The same bytes: nothing is sent, and the log says `already published, identical`. Different bytes: `publish` fails, naming the version -- a published version is never replaced, so publish the change as a new version.
+|`file`; `maven` and `nuget` to a URL, `npm`, `github-release`, `gitlab-package`
+|The same documents: nothing is written or sent, and the log says `already published, identical`, or `with the same documents` when the copy came from another commit.
+Other documents: the version is not published to that channel, and the run warns, naming the version -- a published version is never replaced, so publish the change as a new version (<<channel-problems,When a channel cannot take a version §>>).
+A copy that cannot be read, so there is nothing to compare, is treated as one with other documents, saying why it `cannot be compared`.
+`file` compares the `manifest.json` in the version's directory, and with `clean: true` removes the other versions, never this one.
 `maven` and `gitlab-package` read back every file before uploading any, so a run interrupted half-way is completed by the next one; a GitLab registry that allows duplicate packages, as it does by default, would otherwise replace a version.
-`github-release` compares the asset it would upload with the one the release has, and never overwrites one.
-`npm` compares the integrity hash the registry records, or the tarball's SHA-1 where it records only that, as GitLab's does; its files are packed with fixed modes, so the package is the same bytes whatever the umask of the machine that publishes it.
-A NuGet feed that cannot return the package it has, so there is nothing to compare, fails as a different one would.
+A version completed beside an archive from another commit gets that archive's `manifest.json`, so the two agree on where the version came from; a POM carries no documents, and one already there is left as it is.
+`github-release` reads the manifest in the asset the release has, and never overwrites one.
+`npm` takes the same integrity hash the registry records, or the same tarball SHA-1 where it records only that, as GitLab's does, for the same package; otherwise it downloads the registry's copy and compares its documents.
+Its files are packed with fixed modes, so the package is the same bytes whatever the umask of the machine that publishes it.
+`nuget` reads the manifest in the package the feed returns.
 |===
 
+[#channel-problems]
+=== When a channel cannot take a version
+
+A channel is an external party, so what it does or does not do never fails `publish` on its own.
+When a channel holds the version with other documents, cannot be reached, refuses the request, or has no credential in this run, the target is not published to that channel; the run warns, naming the target, the version, the channel and the reason, and goes on with every other channel and target:
+
+[source,text]
+----
+warning: orders 2.1.0 was not published to partner: no credential in $PARTNER_TOKEN, which channels.maven.tokenEnv names. ...
+
+Published 3 artifact(s).
+Listed 2 file(s) in build/packages/packages.sha256.
+Channel problems: 1 of 4 publication(s) did not complete.
+----
+
+The last line appears only when something did not complete, and ends `Nothing was published.` when nothing did; `publish` still exits 0.
+In GitHub Actions each problem is also a `::warning` annotation on the run.
+The hand-off records every channel's outcome (<<handoff,The hand-off §>>), and publishing is idempotent, so running `publish` again completes what is missing.
+
+What fails the run is the library's to fix: a channel's settings in `apionly.yaml`, such as a `maven` channel without a `groupId`; the remote switch (<<remote-switch,Refusing remote publishing §>>); and a target changed without a new version (<<version-guard,A changed target needs a new version §>>), which is checked before anything is sent.
+
 [#remote-switch]
 === Refusing remote publishing
 
@@ -766,6 +849,7 @@ Every `publish` run lists each file its channels wrote locally, with its SHA-256
 
 | `packages.json`
 | `schemaVersion`, and `files`: for each file, its `path`, `sha256`, `target`, `version`, `channel` -- the channel's name -- and `type`, the channel's type.
+And `outcomes`: for each target and channel of the run, its `target`, `version`, `channel`, `type` and `outcome` -- `published`, `already-published`, `conflict` or `unavailable` -- with the `reason` for the last two.
 
 | `packages.sha256`
 | The same files in the format `sha256sum -c` checks.
@@ -773,7 +857,7 @@ Every `publish` run lists each file its channels wrote locally, with its SHA-256
 
 Paths are relative to the library root, with forward slashes, so `sha256sum -c build/packages/packages.sha256` checks them from there.
 A run replaces both files.
-A channel in a remote mode writes nothing locally, so it adds nothing.
+A channel in a remote mode writes nothing locally, so it adds no files; a channel that did not take the version adds none either, only its outcome.
 
 The hand-off is for a later step that publishes those files itself -- the second of <<docker-two-steps,the image's two steps §>> -- so that it ships exactly the bytes the Publisher produced, and nothing else.
 
@@ -832,7 +916,7 @@ A .NET build uses it with `dotnet nuget add source <repository>`, or a `nuget.co
 *A remote feed* is configured by its service index, the URL a feed's settings show and that ends in `index.json`, such as `https://api.nuget.org/v3/index.json`.
 The Publisher reads the service index for its `PackagePublish/2.0.0` endpoint, then pushes the package there with one `PUT`, as `multipart/form-data`, with the key from the environment variable `tokenEnv` names in the `X-NuGet-ApiKey` header.
 The `PUT` goes to that endpoint with a trailing `/`, as `dotnet nuget push` sends it; a GitLab feed recognises the upload only there.
-Before the push, the Publisher reads the feed's copy of the version back (its `PackageBaseAddress/3.0.0` resource): the same package succeeds without a push, a different one fails, and a copy that cannot be read, other than one the feed does not have, fails rather than being pushed over (<<idempotent,Publishing the same version again §>>).
+Before the push, the Publisher reads the feed's copy of the version back (its `PackageBaseAddress/3.0.0` resource): a package with the same documents succeeds without a push, one with other documents is not pushed over, and neither is a copy that cannot be read, other than one the feed does not have; `publish` warns about both (<<idempotent,Publishing the same version again §>>).
 The check comes first because a feed may accept a different package under a version it already has: GitLab does, by default, and serves the new one from then on.
 A feed that answers the push with 409 -- the version appeared in the meantime -- is read back and compared the same way.
 Without the variable set, the push fails before anything is sent, naming it.
@@ -898,12 +982,12 @@ link:pipelines/gitlab-ci.yml[The reference pipeline →] publishes this way, fro
 | A GitLab CI job publishing to its own project.
 |===
 
-Without either, `publish` fails before anything is sent, naming both.
+Without either, nothing is sent to GitLab, and `publish` warns, naming both (<<channel-problems,When a channel cannot take a version §>>).
 A deploy token is the least privilege for packages alone: it reaches one project's package registry and nothing else.
 
 *The same version again.*
 GitLab allows duplicate packages by default: it accepts a different file under a version it already has, and serves that one from then on.
-So the channel reads every file back before uploading any: an identical file is left alone, a missing one is uploaded, and a different one fails `publish` (<<idempotent,Publishing the same version again §>>).
+So the channel reads every file back before uploading any: a file with the same documents is left alone, a missing one is uploaded, and one with other documents is never replaced; `publish` warns about it (<<idempotent,Publishing the same version again §>>).
 Turning *Allow duplicates* off for generic packages, in the group's *Settings › Packages and registries*, makes GitLab refuse a replaced file too, from every client; the Publisher keeps a version immutable either way.
 
 *`release: true`* also creates the tag's GitLab release, tagging `$CI_COMMIT_SHA` or, outside CI, the checkout's `HEAD`, and links both files as packages.
@@ -932,13 +1016,13 @@ channels:
 *The token* goes as a bearer token, `Authorization: Bearer <token>`, unless `tokenHeader` names another header, which then carries it as it is.
 GitLab's Maven registry takes a job token as `Job-Token`, a personal or project access token as `Private-Token`, and a deploy token as `Deploy-Token`; a GitLab Maven repository URL needs the project's numeric ID, since Gradle reads `%2F` in a path as `/`.
 
-*Every file is read back* before any is uploaded: identical is left alone, missing is uploaded, different fails `publish`, naming the file.
+*Every file is read back* before any is uploaded: the artifact and the manifest with the same documents are left alone, a missing file is uploaded, and other documents are never replaced, and `publish` warns, naming the file; the POM carries no documents, and one already there is left alone.
 
 *`maven-metadata.xml`* lists an artifact's versions, which is how Gradle resolves a version range and how Renovate and Dependabot see a new version.
 Nexus, Artifactory and GitHub Packages keep it themselves; GitLab does not for files uploaded this way.
 So after a version's files, the channel adds the version to it, as `mvn deploy` does: `latest` is the highest version, `release` the highest that is not a pre-release, and `lastUpdated` the time of the commit, so the same commit writes the same file.
 It is written only when it lacks the version, or its `latest` or `release` would change.
-A repository that refuses it fails `publish`, naming `metadata: false`; the version's files are published by then, and a re-run retries only the metadata.
+A repository that refuses it is a warning naming `metadata: false`; the version's files are published by then, and a re-run retries only the metadata.
 
 [#why-registries]
 === Why npm, Maven and NuGet rather than release assets alone
@@ -1046,6 +1130,10 @@ targets:
 
 portfolio:                # absent is fine; an aggregate builds on documented defaults
   location: portfolios    # see Aggregates §
+
+versioning:               # absent is fine; see A changed target needs a new version §
+  tagFormat: "{target}-v{version}"  # the release tags the pipeline creates; the default
+  mainBranch: main        # compared with when a target has no release tag; the default
 ----
 
 `targets` is the single source of truth for what gets built.
@@ -1309,8 +1397,8 @@ A service subscribes to its own contract to implement it, and to the contracts o
 
 * Versions are per target, so a change to one service's fragments releases only that service's contract.
 A change to a fragment several targets share changes all of them, and `changed` names which, as <<closure,Independent versioning, and the dependency closure §>> describes.
-* Publishing every target on every run is safe: a version that is already published, with the same bytes, is left alone (<<idempotent,Publishing the same version again §>>).
-What fails is a changed contract whose version was not changed, which is the mistake `changed` exists to catch first.
+* Publishing every target on every run is safe: a version that is already published, with the same documents, is left alone, whichever commit it was packed from (<<idempotent,Publishing the same version again §>>).
+What fails is a changed contract whose version was not changed, which is the mistake `check` exists to catch first.
 * `landscape` is optional: a whole-landscape view for reading, generated on every build and never published, as <<aggregates,Aggregates §>> describes.
 
 [#recipe-business-partners]
@@ -2035,7 +2123,7 @@ include::pipelines/github-actions.yml[]
 
 What the two steps lose, and how the pipeline makes up for it:
 
-* *Idempotence.* A channel's remote mode leaves a version the registry has alone when it is identical, and refuses it when it differs; `npm publish` or `dotnet nuget push` of an existing version fails instead.
+* *Idempotence.* A channel's remote mode leaves a version the registry has alone when it holds the same documents, and refuses it when it does not; `npm publish` or `dotnet nuget push` of an existing version fails instead.
 Each publishing step checks for the version first, compares the bytes, and publishes only what is missing, so a re-run is safe and a real conflict still fails.
 * *Maven checksums and metadata.* The local Maven layout holds the artifact, its POM and its manifest, and no `.md5`, `.sha1` or `maven-metadata.xml`.
 `mvn deploy:deploy-file` writes those when it uploads, so the repository ends up as a remote `maven` channel would leave it, and Gradle resolves it.
@@ -2154,7 +2242,7 @@ docker build -t api-only-publisher:local --build-arg VERSION=0.0.0-local .
 docker/smoke-test.sh api-only-publisher:local 0.0.0-local
 ----
 
-It runs every step with a read-only root and your own user, and all but the last with no network: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, a remote channel refused while sealed, the shell mode, and a build as an arbitrary UID.
+It runs every step with a read-only root and your own user, and all but the last with no network: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted, checked -- a change without a new version refused -- and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, a remote channel refused while sealed, the shell mode, and a build as an arbitrary UID.
 The last step publishes with `gitlab-package` and `maven` to a GitLab stand-in, run from the same image, on a Docker network it creates with no route out (`docker network create --internal`) and removes afterwards; it checks every request went to the project's package registries with the job token, and that a re-run uploads nothing.
 
 link:../.github/workflows/api-only-publisher-image-e2e.yml[`api-only-publisher-image-e2e.yml` →] runs the GitHub Actions reference pipeline for real, by hand only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",

package/src/bundle-version.js

@@ -22,8 +22,12 @@ class BundleVersionError extends Error {}
 // -- so a JVM build can read the same file with java.util.Properties. Only what a
 // version file needs: no escapes, no continuation lines.
 function readProperties(file) {
+    return parseProperties(fs.readFileSync(file, "utf8"));
+}
+
+function parseProperties(text) {
     const properties = {};
-    for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    for (const raw of text.split(/\r?\n/)) {
         const line = raw.trim();
         if (line === "" || line.startsWith("#") || line.startsWith("!")) continue;
         const separator = line.search(/[=:]/);
@@ -77,4 +81,4 @@ function versionOf(config, target, { preRelease = null } = {}) {
     return version;
 }
 
-module.exports = { versionOf, readProperties, BundleVersionError };
+module.exports = { versionOf, readProperties, parseProperties, BundleVersionError };

package/src/channel-error.js

@@ -1,7 +1,33 @@
 "use strict";
 
-// The error every distribution channel throws, in a module of its own so that a channel
-// implemented outside channels.js can throw it without requiring channels.js back.
+// The errors every distribution channel throws, in a module of its own so that a channel
+// implemented outside channels.js can throw them without requiring channels.js back.
+//
+// A ChannelError is the library's to fix -- a channel's settings in apionly.yaml -- and
+// fails the run. Its two subclasses are about the channel, an external party, and never
+// fail the run on their own: `publish` reports them and goes on with the other channels.
+
 class ChannelError extends Error {}
 
-module.exports = { ChannelError };
+/** The channel holds this version with other documents, or with a copy that cannot be compared. */
+class ChannelConflict extends ChannelError {}
+
+/** The channel could not be reached, refused the request, or this run has no credential for it. */
+class ChannelUnavailable extends ChannelError {}
+
+/**
+ * What became of a publication that threw `error`: `conflict` or `unavailable`, or null
+ * when the error is the library's own and must fail the run. A request that never got an
+ * answer -- fetch's "fetch failed" -- and a registry client that exited with an error,
+ * such as npm or gh, are the channel being unavailable.
+ */
+function outcomeOf(error) {
+    if (error instanceof ChannelConflict) return "conflict";
+    if (error instanceof ChannelUnavailable) return "unavailable";
+    if (error instanceof ChannelError) return null;
+    if (error instanceof TypeError && error.message === "fetch failed") return "unavailable";
+    if (error && typeof error.status === "number" && "stderr" in error) return "unavailable";
+    return null;
+}
+
+module.exports = { ChannelError, ChannelConflict, ChannelUnavailable, outcomeOf };

package/src/channels.js

@@ -13,10 +13,11 @@ const path = require("path");
 const { execFileSync } = require("child_process");
 
 const { parse, compare, isPrerelease, npmDistTag } = require("./version-policy");
-const { ChannelError } = require("./channel-error");
+const { ChannelError, ChannelConflict, ChannelUnavailable } = require("./channel-error");
 const { publishNuget } = require("./nuget");
 const { publishGitlabPackage } = require("./gitlab");
 const { refuseRemote } = require("./remote");
+const { judgeHeld } = require("./held-documents");
 
 /** What every package and release says it is, unless `description` says otherwise. */
 const DEFAULT_DESCRIPTION = "API description documents for {target}.";
@@ -32,26 +33,43 @@ function format(template, manifest) {
  *
  * Not a real distribution mechanism. It exists so the pipeline is testable end
  * to end before any remote exists, and as a local-iteration escape hatch
- * afterwards.
+ * afterwards. Like the registries, it never replaces a version: one it holds with
+ * the same documents is left alone, and one with other documents is refused.
  */
 function publishFile(archive, manifest, options, log) {
     // Relative to the library root, not to wherever the CLI happened to be run.
     const dir = path.resolve(options.baseDir || ".", options.directory || "publish");
     const targetDir = path.join(dir, manifest.target, manifest.version);
+    const archiveDest = path.join(targetDir, path.basename(archive));
+    const manifestDest = path.join(targetDir, "manifest.json");
+    const files = [archiveDest, manifestDest];
+
+    const held = fs.existsSync(manifestDest) ? judgeHeld(fs.readFileSync(manifestDest), "json", manifest) : null;
+    if (held && held.verdict !== "same") {
+        throw new ChannelConflict(`${dir} already has ${manifest.target} ${manifest.version}, and it ` +
+            `${held.verdict === "different" ? "is not this one" : `cannot be compared: ${held.reason}`}; ` +
+            "a published version is never replaced, so publish the change as a new version");
+    }
     // `clean: true` keeps only the version being published. Used where the
     // directory is a build output rather than a record of releases: an older
     // version is published again from the commit that declared it.
-    if (options.clean === true) {
-        fs.rmSync(path.join(dir, manifest.target), { recursive: true, force: true });
+    if (options.clean === true && fs.existsSync(path.join(dir, manifest.target))) {
+        for (const version of fs.readdirSync(path.join(dir, manifest.target))) {
+            if (version !== manifest.version) fs.rmSync(path.join(dir, manifest.target, version), { recursive: true, force: true });
+        }
+    }
+    if (held && fs.existsSync(archiveDest)) {
+        const identical = fs.readFileSync(archiveDest).equals(fs.readFileSync(archive));
+        log(`-- ${manifest.target} ${manifest.version} is already published, ` +
+            `${identical ? "identical" : "with the same documents"}, in ${dir}; nothing to do`);
+        return { location: archiveDest, files, alreadyPublished: true };
     }
     fs.mkdirSync(targetDir, { recursive: true });
-
-    const archiveDest = path.join(targetDir, path.basename(archive));
     fs.copyFileSync(archive, archiveDest);
-    fs.writeFileSync(path.join(targetDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    fs.writeFileSync(manifestDest, JSON.stringify(manifest, null, 2) + "\n");
 
     log(`-- Published ${manifest.target} ${manifest.version} to ${archiveDest}`);
-    return { location: archiveDest, files: [archiveDest, path.join(targetDir, "manifest.json")] };
+    return { location: archiveDest, files };
 }
 
 function pom(groupId, artifactId, version, packaging, description = `API description documents for ${artifactId}.`) {
@@ -175,29 +193,29 @@ function publishNpm(archive, manifest, options, log) {
             return { location, distTag, name, files: [location] };
         }
 
-        // Idempotent: a version the registry already has is left alone when it is the
-        // same package, and refused when it is not -- npm never replaces a version.
+        // Idempotent: a version the registry already has is left alone when it holds the
+        // same documents, and refused when it does not -- npm never replaces a version.
         const registry = options.registry ? ["--registry", options.registry] : [];
         const [local] = JSON.parse(execFileSync("npm", ["pack", "--dry-run", "--json"],
             { cwd: workDir, encoding: "utf8", stdio: "pipe" }));
         const published = npmPublishedDist(name, version, registry);
         if (published) {
             // The SHA-512 integrity when the registry records one; the tarball's SHA-1
-            // otherwise, as GitLab's npm registry records only that.
+            // otherwise, as GitLab's npm registry records only that. The same hash is the
+            // same package; any other answer is settled by the documents in the registry's copy.
             const [held, mine] = published.integrity ? [published.integrity, local.integrity]
                 : published.shasum ? [published.shasum, local.shasum] : [null, null];
-            if (!held) {
-                throw new ChannelError(
-                    `npm already has ${name}@${version}, and it cannot be compared: the registry records neither ` +
-                    "an integrity nor a shasum for it. A published version is never replaced; publish the change as a new version.");
-            }
-            if (held === mine) {
+            if (held && held === mine) {
                 log(`-- npm ${name}@${version} is already published, identical; nothing to do`);
                 return { location: name + "@" + version, distTag, name, alreadyPublished: true };
             }
-            throw new ChannelError(
-                `npm already has ${name}@${version}, and it is not this package (${held}, not ${mine}). ` +
+            const refused = (why) => new ChannelConflict(`npm already has ${name}@${version}, and it ${why}. ` +
                 "A published version is never replaced; publish the change as a new version.");
+            const judged = judgeHeld(npmPublishedPackage(name, version, registry), "tgz", manifest);
+            if (judged.verdict === "unreadable") throw refused(`cannot be compared: ${judged.reason}`);
+            if (judged.verdict === "different") throw refused(held ? `is not this package (${held}, not ${mine})` : "is not this package");
+            log(`-- npm ${name}@${version} is already published, with the same documents; nothing to do`);
+            return { location: name + "@" + version, distTag, name, alreadyPublished: true };
         }
 
         const args = ["publish", "--tag", distTag, ...registry];
@@ -224,7 +242,25 @@ function npmPublishedDist(name, version, registry) {
     } catch (error) {
         const output = `${error.stdout || ""}${error.stderr || ""}`;
         if (/E404/.test(output)) return null;
-        throw new ChannelError(`could not ask npm whether ${name}@${version} is published: ${output.trim() || error.message}`);
+        throw new ChannelUnavailable(`could not ask npm whether ${name}@${version} is published: ${output.trim() || error.message}`);
+    }
+}
+
+/** The package npm holds as `name@version`, downloaded with the registry's own credentials. */
+function npmPublishedPackage(name, version, registry) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "api-only-npm-held-"));
+    try {
+        let packed;
+        try {
+            packed = JSON.parse(execFileSync("npm", ["pack", `${name}@${version}`, "--pack-destination", dir, "--json", ...registry],
+                { encoding: "utf8", stdio: "pipe" }));
+        } catch (error) {
+            const output = `${error.stdout || ""}${error.stderr || ""}`.trim();
+            throw new ChannelUnavailable(`could not read ${name}@${version} back from npm to compare: ${output || error.message}`);
+        }
+        return fs.readFileSync(path.join(dir, packed[0].filename));
+    } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
     }
 }
 
@@ -265,26 +301,29 @@ function publishGithubRelease(archive, manifest, options, log) {
     }
 
     // Idempotent, as the registries are: an asset the release already has is left alone
-    // when it is the same bytes, and refused when it is not. Never --clobber: that would
-    // replace a published contract under the same version.
+    // when it holds the same documents, and refused when it does not. Never --clobber: that
+    // would replace a published contract under the same version.
     const asset = path.basename(archive);
     const assets = exists
         ? gh(["release", "view", tag, "--repo", repository, "--json", "assets", "--jq", ".assets[].name"]).split("\n").map((a) => a.trim())
         : [];
     if (assets.includes(asset)) {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), "api-only-gh-"));
+        let held;
         try {
             gh(["release", "download", tag, "--repo", repository, "--pattern", asset, "--dir", dir]);
-            if (fs.readFileSync(path.join(dir, asset)).equals(fs.readFileSync(archive))) {
-                log(`-- ${repository} release ${tag} already has ${asset}, identical; nothing to do`);
-                return { location: `${repository}@${tag}`, tag, alreadyPublished: true };
-            }
+            held = fs.readFileSync(path.join(dir, asset));
         } finally {
             fs.rmSync(dir, { recursive: true, force: true });
         }
-        throw new ChannelError(
-            `${repository} release ${tag} already has ${asset}, and it is not this archive. ` +
+        const refused = (why) => new ChannelConflict(`${repository} release ${tag} already has ${asset}, and it ${why}. ` +
             "A published version is never replaced; publish the change as a new version.");
+        const judged = judgeHeld(held, "tgz", manifest);
+        if (judged.verdict === "unreadable") throw refused(`cannot be compared: ${judged.reason}`);
+        if (judged.verdict === "different") throw refused("is not this archive");
+        const identical = held.equals(fs.readFileSync(archive));
+        log(`-- ${repository} release ${tag} already has ${asset}, ${identical ? "identical" : "with the same documents"}; nothing to do`);
+        return { location: `${repository}@${tag}`, tag, alreadyPublished: true };
     }
     gh(["release", "upload", tag, archive, "--repo", repository]);
     log(`-- Published ${manifest.target} ${manifest.version} to ${repository} release ${tag}`);
@@ -314,7 +353,7 @@ async function putFile(url, body, auth, contentType) {
         body,
     });
     if (!response.ok) {
-        throw new ChannelError(
+        throw new ChannelUnavailable(
             `PUT ${url} failed: ${response.status} ${response.statusText}. ` +
             (response.status === 401 || response.status === 403
                 ? "Check the token in the environment variable named by channels.maven.tokenEnv."
@@ -328,7 +367,7 @@ async function getFile(url, auth) {
     const response = await fetch(url, { headers: auth });
     if (response.status === 404) return null;
     if (!response.ok) {
-        throw new ChannelError(`GET ${url} failed: ${response.status} ${response.statusText}. ` +
+        throw new ChannelUnavailable(`GET ${url} failed: ${response.status} ${response.statusText}. ` +
             (response.status === 401 || response.status === 403
                 ? "Check the token in the environment variable named by channels.maven.tokenEnv." : ""));
     }
@@ -376,7 +415,7 @@ async function updateMetadata(url, groupId, artifactId, manifest, auth, log) {
     try {
         await putFile(url, Buffer.from(metadataXml(groupId, artifactId, listed, lastUpdated), "utf8"), auth, "application/xml");
     } catch (error) {
-        throw new ChannelError(`the repository refused maven-metadata.xml for ${groupId}:${artifactId}: ${error.message.trim()} ` +
+        throw new ChannelUnavailable(`the repository refused maven-metadata.xml for ${groupId}:${artifactId}: ${error.message.trim()} ` +
             "The version's files are published; a re-run retries only the metadata. For a repository that generates " +
             "its own maven-metadata.xml, set channels.maven.metadata: false.");
     }
@@ -387,7 +426,7 @@ function publishMavenRemote(archive, manifest, options, log) {
     const tokenEnv = options.tokenEnv || "MAVEN_TOKEN";
     const token = process.env[tokenEnv];
     if (!token) {
-        throw new ChannelError(
+        throw new ChannelUnavailable(
             `no credential in $${tokenEnv}, which channels.maven.tokenEnv names. ` +
             `Remote publication needs one; set it in the release job's environment.`
         );
@@ -408,41 +447,57 @@ function publishMavenRemote(archive, manifest, options, log) {
     const base = `${artifactDir}/${version}/${artifactId}-${version}`;
 
     const work = (async () => {
-        // Idempotent, file by file: each file the repository already has is left alone when
-        // it is the same bytes, and refuses the whole version when it is not. Every file is
-        // read back before any is uploaded, so a run interrupted after the artifact is
-        // completed by the next one, and a version that differs anywhere is not touched.
+        // Idempotent, by documents: each file the repository already has that carries them --
+        // the artifact and the manifest -- is left alone when it holds the same documents, and
+        // refuses the whole version when it does not; the POM carries none, and is left alone.
+        // Every file is read back before any is uploaded, so a run interrupted after the
+        // artifact is completed by the next one, and a version that differs anywhere is not
+        // touched.
         const files = [
-            { url: `${base}.${extension}`, bytes: fs.readFileSync(archive), type: "application/octet-stream" },
+            { url: `${base}.${extension}`, bytes: fs.readFileSync(archive), type: "application/octet-stream", kind: "tgz" },
             { url: `${base}.pom`, type: "application/xml",
               bytes: Buffer.from(pom(options.groupId, artifactId, version, extension, pomDescription(options, manifest)), "utf8") },
-            { url: `${base}-manifest.json`, type: "application/json",
+            { url: `${base}-manifest.json`, type: "application/json", kind: "json",
               bytes: Buffer.from(JSON.stringify(manifest, null, 2) + "\n", "utf8") },
         ];
+        const refused = (file, why) => new ChannelConflict(
+            `${options.repository} already has ${options.groupId}:${artifactId}:${version}, ` +
+            `and its ${file.url.split("/").pop()} ${why}. ` +
+            "A published version is never replaced; publish the change as a new version.");
         const missing = [];
+        let identical = true;
+        let heldArchiveManifest = null;
         for (const file of files) {
             const existing = await getFile(file.url, auth);
             if (!existing) {
                 missing.push(file);
-            } else if (!existing.equals(file.bytes)) {
-                throw new ChannelError(
-                    `${options.repository} already has ${options.groupId}:${artifactId}:${version}, ` +
-                    `and its ${file.url.split("/").pop()} is not this one. ` +
-                    "A published version is never replaced; publish the change as a new version.");
+                continue;
             }
+            identical = identical && existing.equals(file.bytes);
+            if (!file.kind) continue;
+            const judged = judgeHeld(existing, file.kind, manifest);
+            if (judged.verdict === "unreadable") throw refused(file, `cannot be compared: ${judged.reason}`);
+            if (judged.verdict === "different") throw refused(file, "is not this one");
+            if (file.kind === "tgz") heldArchiveManifest = judged.held.bytes;
+        }
+        for (const file of missing) {
+            // A version completed beside an artifact from another commit gets that artifact's
+            // manifest, so the two agree on where the version came from.
+            const bytes = file.kind === "json" && heldArchiveManifest ? heldArchiveManifest : file.bytes;
+            await putFile(file.url, bytes, auth, file.type);
         }
-        for (const file of missing) await putFile(file.url, file.bytes, auth, file.type);
         if (options.metadata !== false) {
             await updateMetadata(`${artifactDir}/maven-metadata.xml`, options.groupId, artifactId, manifest, auth, log);
         }
-        return missing.length === 0;
+        return { alreadyPublished: missing.length === 0, identical };
     })();
 
     // The CLI is synchronous throughout; surfacing the promise here would make
     // every caller async for one channel's benefit.
-    return work.then((alreadyPublished) => {
+    return work.then(({ alreadyPublished, identical }) => {
         log(alreadyPublished
-            ? `-- ${options.groupId}:${artifactId}:${version} is already in ${options.repository}, identical; nothing to do`
+            ? `-- ${options.groupId}:${artifactId}:${version} is already in ${options.repository}, ` +
+              `${identical ? "identical" : "with the same documents"}; nothing to do`
             : `-- Deployed ${options.groupId}:${artifactId}:${version} to ${options.repository}`);
         return {
             location: `${base}.${extension}`, coordinates: `${options.groupId}:${artifactId}:${version}@${extension}`,