@gjsify/cli 0.46.0 → 0.47.0

package/lib/commands/onboard.js

@@ -660,6 +660,17 @@ function describePublishFailure(pub) {
             return 'OIDC/token auth failed';
         case 'diagnostic':
             return `HTTP 404 (${pub.diag.reason})`;
+        case 'publish-unconfirmed':
+            // npm claimed the version and the registry does not serve it. Counted
+            // as a FAILURE here on purpose: onboard's next step is `configureTrust`
+            // on a package it just decided exists. `onboard` passes `tolerate:
+            // true`, so `already-published` is the claim it meets on a RE-RUN —
+            // and #1407 is exactly a re-run that counted a half-stored publish
+            // as done.
+            return (`npm ${pub.claim === 'already-published' ? 'reported it already published' : 'accepted the upload'} ` +
+                `(HTTP ${pub.putStatus}) but ${pub.name}@${pub.version} did not ` +
+                `resolve on ${pub.registry} after ${pub.readback.attempts} probe(s) over ` +
+                `${(pub.readback.elapsedMs / 1000).toFixed(1)}s`);
         case 'error':
             return `HTTP ${pub.status} ${pub.statusText}`;
         default:

package/lib/commands/publish.d.ts

@@ -1,5 +1,6 @@
 import type { Command } from '../types/index.js';
 import { type Diagnose404Result } from '../utils/publish-diagnose.js';
+import { type ReadbackResult } from '../utils/publish-readback.js';
 import { OtpProvider } from '../utils/npm-otp.js';
 interface PublishOptions {
     path?: string;
@@ -8,6 +9,8 @@ interface PublishOptions {
     otp?: string;
     'tolerate-republish'?: boolean;
     'tolerate-untrusted-new'?: boolean;
+    'verify-timeout'?: number;
+    'verify-defer'?: boolean;
     provenance?: boolean;
     'dry-run'?: boolean;
     json?: boolean;
@@ -37,6 +40,13 @@ export interface PublishWorkspaceInput {
     otpProvider: OtpProvider;
     /** Send the cached code on the first PUT (publish `--otp`). */
     seedOtpFirst: boolean;
+    /**
+     * Polling budget for the post-PUT read-back, in ms. Default
+     * {@link DEFAULT_VERIFY_BUDGET_MS}; `0` skips the read-back entirely and the
+     * returned `published` outcome then carries no `readback` — an UNVERIFIED
+     * success, which is the pre-v0.46.0 behaviour and why this defaults on.
+     */
+    verifyBudgetMs?: number;
 }
 /** Discriminated result of {@link publishWorkspace}; the caller owns presentation. */
 export type PublishOutcome = {
@@ -49,12 +59,43 @@ export type PublishOutcome = {
     integrity: string;
     tag: string;
     registry: string;
+    /** The read-back that CONFIRMED it. `undefined` only when disabled. */
+    readback?: ReadbackResult;
+}
+/**
+ * npm returned 2xx and the registry does not serve the version. Its own
+ * outcome on purpose: not `published` (nothing is installable), not
+ * `republish-tolerated` (npm never claimed it existed), not `error` (the
+ * HTTP exchange succeeded). The v0.46.0 incident had no name at all — it
+ * came out as `+ name@version`, exit 0.
+ */
+ | {
+    ok: false;
+    action: 'publish-unconfirmed';
+    /**
+     * What npm claimed before the read-back disagreed: a 2xx (`accepted`)
+     * or a tolerated 409 (`already-published`). It selects the remediation
+     * sentence, which is the OPPOSITE one for a conflict — re-running
+     * answers the same 409.
+     */
+    claim: 'accepted' | 'already-published';
+    name: string;
+    version: string;
+    registry: string;
+    /** The PUT that was accepted. */
+    putStatus: number;
+    putStatusText: string;
+    putUrl: string;
+    payloadBytes: number;
+    readback: ReadbackResult;
 } | {
     ok: true;
     action: 'republish-tolerated';
     name: string;
     version: string;
     status: number;
+    /** The read-back that CONFIRMED the conflicting version. */
+    readback?: ReadbackResult;
 } | {
     ok: true;
     action: 'skipped-untrusted-new';

package/lib/commands/publish.js

@@ -19,6 +19,12 @@
 //     a sigstore signer that gjsify doesn't ship; we record the flag in the
 //     publish manifest but don't sign yet. Surface a warning so callers know.
 //   - --dry-run: pack only, no PUT.
+//   - --verify-timeout / --verify-defer: the post-PUT READ-BACK. npm's 2xx is an
+//     accepted write, not a durable one, so a successful PUT is confirmed by
+//     asking the registry for that exact version before `+ name@version` is
+//     printed. The incident, the measured lag distribution and the choice of
+//     window live in `utils/publish-readback.ts`; WHERE the read-back runs and
+//     what it costs is argued at its call site below.
 //
 // The request body matches npm's "publish" payload shape:
 //   {
@@ -41,6 +47,7 @@ import { buildPublishHeaders, escapePackageName } from '../utils/publish-headers
 import { packWorkspace } from './pack.js';
 import { getNpmTrustedToken, hasGithubOidcEnv, OidcExchangeError, OidcUnavailableError } from '../utils/npm-oidc.js';
 import { diagnose404, is404DiagnosticCandidate } from '../utils/publish-diagnose.js';
+import { DEFAULT_VERIFY_BUDGET_MS, formatUnconfirmedPublish, verifyPublishedVersion, } from '../utils/publish-readback.js';
 import { loadNpmrc } from '../utils/load-npmrc.js';
 import { OtpProvider, withOtpRetry, isOtpChallenge } from '../utils/npm-otp.js';
 import { promptLine } from '../utils/prompt.js';
@@ -71,6 +78,16 @@ export const publishCommand = {
         description: 'Skip (exit 0) when OIDC token exchange returns `package not found` AND no fallback token is configured — i.e. a never-before-published `@scope/<name>` whose Trusted Publisher entry hasn\'t been set up on npmjs.com yet. Without this flag, one un-bootstrapped new package breaks the entire serialized `gjsify foreach publish` loop. Pair with `--tolerate-republish` in CI release workflows so a fresh-merged package gracefully skips its first CI publish, leaving the manual-bootstrap step to a maintainer (see AGENTS.md "New @gjsify/* package: first-publish + Trusted Publisher bootstrap").',
         type: 'boolean',
         default: false,
+    })
+        .option('verify-timeout', {
+        description: 'Seconds to keep asking the registry for the just-published version before giving up. npm answers 2xx to a write it has only ACCEPTED: in the v0.46.0 release 19 of 199 packages were recorded 56-252s after their 2xx and one was never recorded at all, so a shorter window turns normal queueing into a false red. `0` disables the read-back — for a registry with no packument read path.',
+        type: 'number',
+        default: DEFAULT_VERIFY_BUDGET_MS / 1000,
+    })
+        .option('verify-defer', {
+        description: 'Report an unconfirmed read-back and exit 0 instead of 1. ONLY for a caller that re-checks the same set afterwards — `gjsify run npm:publish` passes it because `scripts/verify-published-closure.mjs` sweeps the whole roster at the end of release.yml. Everywhere else an unconfirmed publish must fail the job that made it.',
+        type: 'boolean',
+        default: false,
     })
         .option('provenance', {
         description: "Pass-through flag — recorded in the payload but no signing happens (gjsify doesn't ship a sigstore signer yet).",
@@ -107,6 +124,17 @@ export const publishCommand = {
         const otp = args.otp;
         const tolerate = args['tolerate-republish'] === true;
         const tolerateUntrustedNew = args['tolerate-untrusted-new'] === true;
+        const verifySeconds = args['verify-timeout'] ?? DEFAULT_VERIFY_BUDGET_MS / 1000;
+        // A non-number reaches here as NaN (yargs coerces `--verify-timeout abc`
+        // silently), and NaN would fall through every `> 0` test and turn the
+        // read-back OFF without saying so — the failure mode this whole change
+        // exists to remove. Refuse it instead.
+        if (!Number.isFinite(verifySeconds) || verifySeconds < 0) {
+            console.error(`gjsify publish: --verify-timeout must be a non-negative number of seconds, got ${JSON.stringify(args['verify-timeout'])}`);
+            return process.exit(2);
+        }
+        const verifyBudgetMs = Math.round(verifySeconds * 1000);
+        const deferUnconfirmed = args['verify-defer'] === true;
         const provenance = args.provenance === true;
         const dryRun = args['dry-run'] === true;
         const checkTrustedOnly = args['check-trusted'] === true;
@@ -219,8 +247,9 @@ export const publishCommand = {
             json: args.json === true,
             otpProvider,
             seedOtpFirst: otp !== undefined,
+            verifyBudgetMs,
         });
-        reportPublishOutcome(outcome, args.json === true);
+        reportPublishOutcome(outcome, args.json === true, deferUnconfirmed);
     },
 };
 /**
@@ -329,12 +358,128 @@ export async function publishWorkspace(input) {
         return fetch(url, { method: 'PUT', headers: reqHeaders, body: bodyStr });
     };
     const res = await withOtpRetry(doPut, otpProvider, { seedFirstAttempt: input.seedOtpFirst });
+    if (verbose) {
+        // The debug output used to print the request and then the `+` success
+        // line, so a 200 and a 201 were indistinguishable and no body was ever
+        // recorded — which is why reconstructing the v0.46.0 incident needed the
+        // registry rather than the log it already had. Print what npm answered.
+        // `clone()` because the error path below reads `res.text()` itself.
+        console.error(`  response:      ${res.status} ${res.statusText}`);
+        const peek = await res
+            .clone()
+            .text()
+            .catch(() => '');
+        if (peek)
+            console.error(`  body:          ${peek.slice(0, 300)}`);
+    }
+    /**
+     * Ask the registry for what we just PUT. `undefined` when the read-back is
+     * off (`--verify-timeout 0`).
+     *
+     * The PUT's own `authorization` goes with it: a registry that requires a
+     * credential to READ answers 401/403 to an anonymous packument GET, which is
+     * an `error` probe, so an intact publish to GitHub Packages or an
+     * authenticated Verdaccio would spend the whole budget and then report
+     * `publish-unconfirmed`. Same origin, same credential, one request later.
+     */
+    const readBack = async () => {
+        const budgetMs = input.verifyBudgetMs ?? DEFAULT_VERIFY_BUDGET_MS;
+        if (budgetMs <= 0)
+            return undefined;
+        return verifyPublishedVersion({
+            registry: registryClean,
+            name: packed.name,
+            version: packed.version,
+            budgetMs,
+            authorization: headers['authorization'],
+            log: verbose ? (m) => console.error(m) : undefined,
+        });
+    };
     // A surviving OTP challenge means the provider gave up (no code entered /
     // non-interactive). Surface it so the caller can point at --otp.
     if (await isOtpChallenge(res)) {
         return { ok: false, action: 'otp-required', name: packed.name, version: packed.version, status: res.status };
     }
     if (res.ok) {
+        // WHERE THE READ-BACK BELONGS — per package, here, immediately.
+        //
+        // This path runs ~209 times per release (199 in the serial
+        // `foreach --exec` sweep behind `npm:publish`, plus the per-bundle
+        // single-package jobs), so its cost is measured rather than assumed:
+        //
+        //   CONFIRMED ON THE FIRST PROBE — 180 of 199 packages in v0.46.0. One
+        //   abbreviated-packument GET, 0.59 s against registry.npmjs.org, so
+        //   ~2 min across the whole sweep against a publish job that ran 33 min.
+        //
+        //   NOT CONFIRMED YET — the other 19. Here the read-back waits out
+        //   npm's own write queue, and those residual lags SUM TO 2554 s: a
+        //   sweep that waited them all out with the 300 s default would have
+        //   added ~43 min to that 33 min job. That single number decides the
+        //   shape below.
+        //
+        // A BATCHED END-OF-SWEEP CHECK CANNOT LIVE IN THIS FILE. `npm:publish`
+        // is `gjsify foreach --exec -- gjsify publish`, one CHILD PROCESS per
+        // package: there is no in-process hook after the last one to collect a
+        // pending set in. So the batched half already sits where it can —
+        // `scripts/verify-published-closure.mjs`, its own job at the end of
+        // `release.yml`, rounds and retries over the whole roster. It is what
+        // named the missing package in the incident.
+        //
+        // AND A FATAL READ-BACK INSIDE THAT SWEEP WOULD ABORT THE RELEASE, which
+        // is the argument the 2554 s only quantifies. `foreach --exec` THROWS on
+        // a non-zero child (`foreach.ts`: `exited with code ${result.code}`),
+        // and pack time has already rewritten every `workspace:*` to the exact
+        // released version — so one lagging package would stop the sweep
+        // mid-roster and leave a PARTIAL publish, the state
+        // `verify-published-closure.mjs` exists because it is worse than no
+        // publish at all. A deferral here is not leniency; it is the only shape
+        // that does not trade this incident for that one.
+        //
+        // Hence BOTH, split along that cost. The read-back runs per package
+        // everywhere and is FATAL by default — that is what turns the
+        // incident's green single-package job red, for up to 300 s of
+        // patience on a job that otherwise ran 59 s. The
+        // 199-package sweep passes `--verify-defer --verify-timeout 5`: it
+        // still CONFIRMS nine packages in ten and still names the suspect
+        // against the package that PUT it, but the minutes-long tail is left to
+        // the closure job that re-asks the same question over the same set —
+        // which had to be MADE able to answer it (`dist.tarball`, and a
+        // propagation retry that never fired for a roster-only name).
+        //
+        // What the deferred annotation is NOT is the ledger. At a 5 s budget
+        // every one of a release's ~19 lagging packages emits one, and GitHub
+        // renders only the first few annotations per step (documented as 10 per
+        // level; not verified from a run here). The closure job is the fatal
+        // half; the annotation points a human at the name.
+        const readback = await readBack();
+        if (readback?.confirmed && verbose) {
+            // The CONFIRMED half of the read-back is printed too, and it is not
+            // decoration: it is the only client-side measurement of when a
+            // version became RESOLVABLE, as against `time[version]`, which is
+            // when the registry recorded the write. The two are assumed equal by
+            // the 4.2-minute figure and the 300 s window, and nothing had ever
+            // measured the gap. The pre-registered comparison — and what each
+            // outcome would change — is in #1509's description; this line, under
+            // GJSIFY_PUBLISH_DEBUG (which release.yml sets), is its input. Note
+            // the value is quantised by the backoff grid, so it is the UPPER end
+            // of a bracket whose lower end is the previous probe.
+            console.error(`  read-back:     confirmed after ${readback.attempts} probe(s) in ${readback.elapsedMs} ms`);
+        }
+        if (readback && !readback.confirmed) {
+            return {
+                ok: false,
+                action: 'publish-unconfirmed',
+                claim: 'accepted',
+                name: packed.name,
+                version: packed.version,
+                registry: registryClean,
+                putStatus: res.status,
+                putStatusText: res.statusText,
+                putUrl: url,
+                payloadBytes: bodyStr.length,
+                readback,
+            };
+        }
         return {
             ok: true,
             action: 'published',
@@ -345,18 +490,50 @@ export async function publishWorkspace(input) {
             integrity: packed.integrity,
             tag,
             registry: registryClean,
+            readback,
         };
     }
     const text = await res.text().catch(() => '<no body>');
     // "version already published" — 409 Conflict, or 403 + "previously published".
+    //
+    // READ BACK HERE TOO, and the reason it was first written the other way is
+    // worth keeping: a 2xx is npm accepting a write it has not necessarily
+    // durably applied, whereas a 409 is npm ASSERTING the version exists and
+    // refusing to overwrite it — sounding like a positive statement about the
+    // registry's own state rather than a promise about a queued one. The
+    // incident's own recovery says otherwise. Attempt 3 re-PUT
+    // @gjsify/node-runtime-darwin-arm64 and was answered `409 already
+    // published` at 09:48:49.19, while that packument's `time["0.46.0"]` is
+    // 09:49:07.419 — 18 s LATER — and the closure job had found the name absent
+    // at 09:44:28. So the assertion can precede the version being served, and
+    // this is the path a `publish-unconfirmed` re-run always lands on: exempting
+    // it would leave the documented remediation reporting a success nothing
+    // checked. Cost is one GET, on a path that only runs on a re-publish.
     const isRepublishConflict = res.status === 409 || (res.status === 403 && /previously published/i.test(text));
     if (isRepublishConflict && tolerate) {
+        const readback = await readBack();
+        if (readback && !readback.confirmed) {
+            return {
+                ok: false,
+                action: 'publish-unconfirmed',
+                claim: 'already-published',
+                name: packed.name,
+                version: packed.version,
+                registry: registryClean,
+                putStatus: res.status,
+                putStatusText: res.statusText,
+                putUrl: url,
+                payloadBytes: bodyStr.length,
+                readback,
+            };
+        }
         return {
             ok: true,
             action: 'republish-tolerated',
             name: packed.name,
             version: packed.version,
             status: res.status,
+            readback,
         };
     }
     // 404 diagnostic (token-auth): disambiguate dead-token vs missing-package.
@@ -384,8 +561,13 @@ export async function publishWorkspace(input) {
 /**
  * Present a {@link PublishOutcome} on stdout/stderr and exit non-zero on
  * failure — the single-command `gjsify publish` behaviour, reproduced exactly.
+ *
+ * `deferUnconfirmed` (`--verify-defer`) affects exactly one outcome: it downgrades
+ * `publish-unconfirmed` from exit 1 to a printed warning, for a caller that
+ * re-checks the same set afterwards. It is policy, so it lives here and not in
+ * {@link publishWorkspace}, which stays a pure fact-finder.
  */
-function reportPublishOutcome(outcome, asJson) {
+function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
     switch (outcome.action) {
         case 'published': {
             const out = {
@@ -404,6 +586,44 @@ function reportPublishOutcome(outcome, asJson) {
                 process.stdout.write(`+ ${outcome.name}@${outcome.version}\n`);
             return;
         }
+        case 'publish-unconfirmed': {
+            const message = formatUnconfirmedPublish(outcome);
+            if (asJson) {
+                process.stdout.write(`${JSON.stringify({
+                    ok: false,
+                    action: 'publish-unconfirmed',
+                    name: outcome.name,
+                    version: outcome.version,
+                    registry: outcome.registry,
+                    claim: outcome.claim,
+                    putStatus: outcome.putStatus,
+                    probes: outcome.readback.attempts,
+                    elapsedMs: outcome.readback.elapsedMs,
+                    readbackUrl: outcome.readback.url,
+                    readbackState: outcome.readback.last.state,
+                    deferred: deferUnconfirmed,
+                }, null, 2)}\n`);
+            }
+            else {
+                process.stderr.write(`${message}\n`);
+            }
+            // Under `--verify-defer` the multi-line message is one entry in a
+            // serial log carrying a line per package, i.e. exactly the channel
+            // the incident's `+` line hid in. An annotation renders beside the
+            // job's own check and needs no writable file, the same reason
+            // `verify-published-closure.mjs` emits its notes as `::warning::`.
+            // On STDERR, because `--json` owns stdout.
+            if (deferUnconfirmed) {
+                if (process.env.GITHUB_ACTIONS) {
+                    const claimed = outcome.claim === 'already-published' ? 'was reported already published' : 'was accepted';
+                    process.stderr.write(`::warning title=Publish unconfirmed::${outcome.name}@${outcome.version} ${claimed} ` +
+                        `(HTTP ${outcome.putStatus}) but did not resolve on ${outcome.registry} within ` +
+                        `${(outcome.readback.elapsedMs / 1000).toFixed(1)}s — the release-closure job must confirm it\n`);
+                }
+                return;
+            }
+            return process.exit(1);
+        }
         case 'republish-tolerated': {
             const out = {
                 ok: true,

package/lib/utils/publish-readback.d.ts

@@ -0,0 +1,132 @@
+/** One registry answer, classified. `absent` and `error` are NOT the same fact. */
+export type ReadbackProbe = {
+    state: 'present';
+    status: number;
+    tarball: string;
+} | {
+    state: 'absent';
+    status: number;
+    detail: string;
+}
+/**
+ * We do not KNOW. A 5xx, a timeout, unparseable JSON — treating any of them
+ * as "absent" would fabricate a "never published" verdict out of a registry
+ * hiccup, the same distinction `verify-published-closure.mjs` draws between
+ * `false` and an `Error`.
+ */
+ | {
+    state: 'error';
+    status?: number;
+    detail: string;
+};
+export interface ReadbackResult {
+    /** True iff a probe saw the exact version with a tarball on it. */
+    confirmed: boolean;
+    /** Probes actually sent (≥ 1). */
+    attempts: number;
+    elapsedMs: number;
+    /** The URL that was asked, verbatim — it belongs in the failure message. */
+    url: string;
+    /** What the registry said last. On `confirmed` this is the `present` probe. */
+    last: ReadbackProbe;
+}
+export interface VerifyPublishedVersionInput {
+    /** Registry URL, with or without a trailing slash. */
+    registry: string;
+    /** Full package name including scope. */
+    name: string;
+    version: string;
+    /** Total polling budget in ms. Must be > 0 — a disabled read-back is the caller's decision. */
+    budgetMs: number;
+    /** Per-probe request timeout. Default 30 s, matching the closure script. */
+    probeTimeoutMs?: number;
+    /**
+     * The `authorization` header the PUT used, forwarded verbatim.
+     *
+     * A registry that requires a credential to READ answers 401/403 to an
+     * anonymous packument GET, which classifies as `error` — so an intact
+     * publish to GitHub Packages, an Artifactory repo or a Verdaccio with
+     * `access: $authenticated` reports `publish-unconfirmed` and, on the fatal
+     * default, exits 1 after the whole budget on a publish that worked.
+     * Measured against the first version of this file: 15 read-back GETs, every
+     * one anonymous, one second after a PUT that carried a token. Same origin,
+     * same credential, one request later — it adds no exposure the PUT did not
+     * already have.
+     */
+    authorization?: string;
+    /** Injected in tests; resolved at call time so a `globalThis.fetch` stub is honoured. */
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Called once per probe under `GJSIFY_PUBLISH_DEBUG`. */
+    log?: (msg: string) => void;
+}
+/** Delay before probe `round + 2`. Past the table's end the last value repeats. */
+export declare function backoffFor(round: number): number;
+/**
+ * A probe's request timeout: what was configured, never more than the budget has
+ * left to spend — but never less than a probe needs to answer.
+ *
+ * Configured and budget are otherwise independent, and that makes
+ * `--verify-timeout 5` — what the 199-package sweep passes — a promise the code
+ * does not keep: one unanswered request may block for the 30 s default, six times
+ * the budget it was given, and 199 of those cost ~100 min against the ~11% the
+ * deferral is argued on. Clamping bounds the wall clock at
+ * `budget + MIN_PROBE_TIMEOUT_MS` instead. The floor is the other half of the
+ * same honesty: clamping all the way to zero traded a 30 s overshoot for an
+ * `error` verdict on a probe that was about to return the 404 (measured — it
+ * turned the incident's own e2e row from `absent: 404` into `request failed
+ * (This operation was aborted)`).
+ */
+export declare function probeTimeoutFor(configuredMs: number, remainingMs: number): number;
+/**
+ * Default polling budget: 300 s.
+ *
+ * The measured maximum lag between a 2xx and the registry recording the version
+ * was 251.7 s (@gjsify/child_process, v0.46.0), so a budget below ~4.2 minutes
+ * turns npm's normal queueing into a false red — and a false red at release time
+ * costs a manual re-run of a workflow that did its job. 300 s clears that
+ * maximum and is still short enough that a genuinely lost write is reported by
+ * the job that lost it rather than by a later sweep.
+ *
+ * THAT MAXIMUM IS A SAMPLE MAXIMUM, and the sample does not look truncated by
+ * nature. The 19 lags fall in buckets ~20-30 s apart — 56(2), 76(3), 96(3),
+ * 127(4), 157(3), 189(1), 251(3) — and the TOP bucket is as populated as the
+ * middle ones, which is the shape of a distribution cut off by the observation
+ * rather than one decaying to zero. One release is one sample, so a lag past
+ * 300 s is not ruled out; what makes 300 s affordable anyway is that the
+ * remediation is verified rather than assumed. The re-run this reports lands on
+ * the 409 path, and that path READS BACK too (see the conflict branch in
+ * `commands/publish.ts`), so a window that turns out to be too short costs one
+ * re-run that confirms — it does not hand back an unverified success.
+ */
+export declare const DEFAULT_VERIFY_BUDGET_MS = 300000;
+/**
+ * Poll the registry until `name@version` resolves, or the budget runs out.
+ *
+ * No side effects, no exits, no printing beyond the injected `log` — the caller
+ * owns presentation, same contract as {@link import('./publish-diagnose.js')}.
+ */
+export declare function verifyPublishedVersion(input: VerifyPublishedVersionInput): Promise<ReadbackResult>;
+/**
+ * The unconfirmed-publish diagnostic, ready for stderr.
+ *
+ * The message has to answer three questions the incident log could not, which is
+ * why it needed the registry to reconstruct at all: what was PUT, what was asked,
+ * and what came back.
+ */
+export declare function formatUnconfirmedPublish(opts: {
+    name: string;
+    version: string;
+    putUrl: string;
+    putStatus: number;
+    putStatusText: string;
+    payloadBytes: number;
+    readback: ReadbackResult;
+    /**
+     * What npm claimed before the read-back disagreed. `accepted` is a 2xx;
+     * `already-published` is a tolerated 409, where the remediation is the
+     * opposite one — a re-run answers the same conflict.
+     */
+    claim?: 'accepted' | 'already-published';
+}): string;