vouchington-tooling 0.0.13 → 0.0.15

package/README.md

@@ -50,8 +50,12 @@ import {
 import { initSqlAst, extractCreateTableMetadata } from 'vouchington-tooling/sql-ast'
 import { splitSqlStatements, stripSqlComments } from 'vouchington-tooling/sql-scanner'
 import { auditCiJobRuntime } from 'vouchington-tooling/gha-runtime-audit'
-import { writeVitestBlobManifest } from 'vouchington-tooling/vitest-blob-manifest'
-import { runInstallLifecycle } from 'vouchington-tooling/pnpm-install'
+import {
+  readVitestReportAttempts,
+  writeVitestBlobManifest,
+} from 'vouchington-tooling/vitest-blob-manifest'
+import { prepareVitestReports } from 'vouchington-tooling/vitest-reports'
+import { runInstallLifecycle, validateReleaseAgePolicy } from 'vouchington-tooling/pnpm-install'
 import {
   buildSharedContext,
   installFakeGit,
@@ -69,4 +73,15 @@ import {
   renderSchemaMarkdown,
 } from 'vouchington-tooling/pg-schema-snapshot'
 import { buildOpenApiDocument, writeOpenApi } from 'vouchington-tooling/openapi-document'
+import { decide, deriveRetryAttempt } from 'vouchington-tooling/transient-retry'
+import { parseCsvRows, streamCsvRows } from 'vouchington-tooling/csv'
+import { readResponseBody } from 'vouchington-tooling/http-body'
+import { runAstGrepRule } from 'vouchington-tooling/ast-grep-rule'
+import { parseReviewPayload, remapReviewComments } from 'vouchington-tooling/gha-review-payload'
+import { nextPageUrlFromLinkHeader } from 'vouchington-tooling/http-link-pagination'
+import { cmdUpload, mintPresignedControl } from 'vouchington-tooling/coverage-transport'
 ```
+
+The artifact, review-payload, HTTP body, and pagination APIs validate untrusted inputs at their
+boundaries. They do not include provider credentials, product policy, network transport, or
+repository-specific package names; consumers supply those through their own adapters.

package/dist/ast-grep-rule/index.d.mts

@@ -0,0 +1,13 @@
+export interface AstGrepRuleInvocation {
+    readonly ruleId: string;
+    readonly passthrough: readonly string[];
+}
+export interface RunAstGrepRuleOptions {
+    readonly args: readonly string[];
+    readonly cwd?: string;
+    readonly rulesDirectory?: string;
+    readonly executable?: string;
+    readonly defaultScanArguments?: readonly string[];
+}
+export declare function parseAstGrepRuleArgs(args: readonly string[]): AstGrepRuleInvocation;
+export declare function runAstGrepRule(options: RunAstGrepRuleOptions): Promise<number>;

package/dist/ast-grep-rule/index.mjs

@@ -0,0 +1,43 @@
+import { spawn } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export function parseAstGrepRuleArgs(args) {
+    const normalized = args[0] === '--' ? args.slice(1) : args;
+    const [ruleId, ...passthrough] = normalized;
+    if (!ruleId)
+        throw new Error('Expected an AST-grep rule id');
+    if (ruleId.startsWith('-') || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(ruleId)) {
+        throw new Error(`Invalid AST-grep rule id: ${ruleId}`);
+    }
+    return { ruleId, passthrough };
+}
+function containedRulePath(rulesDirectory, ruleId) {
+    const root = realpathSync(rulesDirectory);
+    const path = realpathSync(join(root, `${ruleId}.yml`));
+    if (resolve(path).startsWith(`${resolve(root)}/`))
+        return path;
+    throw new Error(`AST-grep rule resolves outside the rules directory: ${ruleId}`);
+}
+export function runAstGrepRule(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const rulesDirectory = resolve(cwd, options.rulesDirectory ?? 'ast-grep-rules');
+    const { ruleId, passthrough } = parseAstGrepRuleArgs(options.args);
+    const unresolvedRulePath = join(rulesDirectory, `${ruleId}.yml`);
+    if (!existsSync(unresolvedRulePath))
+        throw new Error(`Unknown AST-grep rule id: ${ruleId}`);
+    const rulePath = containedRulePath(rulesDirectory, ruleId);
+    const executable = resolve(cwd, options.executable ?? join('node_modules', '@ast-grep', 'cli', 'ast-grep'));
+    const defaults = options.defaultScanArguments ?? [
+        '--no-ignore',
+        'hidden',
+        '--off=unused-suppression',
+    ];
+    return new Promise((resolveResult, reject) => {
+        const child = spawn(executable, ['scan', ...defaults, '--rule', rulePath, ...passthrough], {
+            cwd,
+            stdio: 'inherit',
+        });
+        child.once('error', reject);
+        child.once('close', (code) => resolveResult(code ?? 1));
+    });
+}

package/dist/coverage-transport/constants.d.mts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_COVERAGE_MANIFEST_FILENAME = "coverage-manifest.json";
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+export declare function assertCoverageManifestFilename(filename: string): void;

package/dist/coverage-transport/constants.mjs

@@ -0,0 +1,11 @@
+export const DEFAULT_COVERAGE_MANIFEST_FILENAME = 'coverage-manifest.json';
+export const DEFAULT_MAX_BODY_BYTES = 32 * 1024 * 1024;
+const MANIFEST_FILENAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.json$/;
+export function assertCoverageManifestFilename(filename) {
+    if (filename.includes('/') ||
+        filename.includes('\\') ||
+        filename.includes('..') ||
+        !MANIFEST_FILENAME_PATTERN.test(filename)) {
+        throw new Error('Coverage manifest filename is invalid');
+    }
+}

package/dist/coverage-transport/control.d.mts

@@ -0,0 +1,47 @@
+export interface PresignedCoverageUrls {
+    lcovPut: string;
+    lcovGet: string;
+    manifestPut: string;
+    manifestGet: string;
+}
+export interface PresignedBlobUrls {
+    put: string;
+    get: string;
+}
+interface TransportControlBase {
+    readonly version: 1;
+    readonly repository: string;
+    readonly revision: string;
+    readonly run: {
+        readonly id: string;
+        readonly controlAttempt: number;
+    };
+}
+export interface PresignedTransportControl extends TransportControlBase {
+    readonly mode: 'presigned';
+    readonly expiresAt: string;
+    readonly coverage: Record<string, PresignedCoverageUrls>;
+    readonly blobs: Record<string, PresignedBlobUrls>;
+}
+export interface FallbackOnlyTransportControl extends TransportControlBase {
+    readonly mode: 'fallback-only';
+    readonly reason: string;
+}
+export type TransportControl = PresignedTransportControl | FallbackOnlyTransportControl;
+export interface ExpectedTransportIdentity {
+    readonly repository: string;
+    readonly revision: string;
+    readonly runId: string;
+    readonly currentAttempt: number;
+}
+export interface RequestOptions {
+    readonly retryDelayMs?: number;
+    readonly timeoutMs?: number;
+    readonly maxBodyBytes?: number;
+    readonly maxMemberBytes?: number;
+    readonly log?: (line: string) => void;
+}
+export declare function parseTransportControl(raw: unknown): TransportControl;
+export declare function writeTransportControl(path: string, control: TransportControl): void;
+export declare function readTransportControl(path: string, expected?: ExpectedTransportIdentity): TransportControl;
+export {};

package/dist/coverage-transport/control.mjs

@@ -0,0 +1,112 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { VITEST_SUITE_PATTERN } from '../vitest-blob-manifest/index.mjs';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function positiveInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0;
+}
+function assertUrlMap(raw, fields, label) {
+    if (!isRecord(raw))
+        throw new Error(`${label} URL map must be an object`);
+    for (const [suite, urls] of Object.entries(raw)) {
+        if (!VITEST_SUITE_PATTERN.test(suite) ||
+            !isRecord(urls) ||
+            Object.keys(urls).toSorted().join('\0') !== fields.toSorted().join('\0')) {
+            throw new Error(`${label} URL map has an invalid entry`);
+        }
+        for (const field of fields) {
+            const value = urls[field];
+            if (typeof value !== 'string' || !URL.canParse(value) || !/^https?:/i.test(value)) {
+                throw new Error(`${label} URL map has an invalid URL`);
+            }
+        }
+    }
+}
+export function parseTransportControl(raw) {
+    if (!isRecord(raw) || raw.version !== 1 || !isRecord(raw.run)) {
+        throw new Error('Coverage transport control has an unsupported schema');
+    }
+    if (typeof raw.repository !== 'string' ||
+        !raw.repository ||
+        typeof raw.revision !== 'string' ||
+        !/^[0-9a-f]{40}$/.test(raw.revision) ||
+        typeof raw.run.id !== 'string' ||
+        !/^[1-9][0-9]*$/.test(raw.run.id) ||
+        !positiveInteger(raw.run.controlAttempt)) {
+        throw new Error('Coverage transport control has invalid identity fields');
+    }
+    if (Object.keys(raw.run).toSorted().join('\0') !== ['controlAttempt', 'id'].join('\0')) {
+        throw new Error('Coverage transport control run schema is invalid');
+    }
+    if (raw.mode === 'fallback-only') {
+        const fallbackKeys = ['mode', 'reason', 'repository', 'revision', 'run', 'version'];
+        if (Object.keys(raw).toSorted().join('\0') !== fallbackKeys.toSorted().join('\0') ||
+            typeof raw.reason !== 'string' ||
+            !raw.reason) {
+            throw new Error('Fallback-only coverage transport control is invalid');
+        }
+        return raw;
+    }
+    const presignedKeys = [
+        'blobs',
+        'coverage',
+        'expiresAt',
+        'mode',
+        'repository',
+        'revision',
+        'run',
+        'version',
+    ];
+    if (raw.mode !== 'presigned' ||
+        Object.keys(raw).toSorted().join('\0') !== presignedKeys.toSorted().join('\0') ||
+        typeof raw.expiresAt !== 'string' ||
+        !Number.isFinite(Date.parse(raw.expiresAt))) {
+        throw new Error('Presigned coverage transport control is invalid');
+    }
+    assertUrlMap(raw.coverage, ['lcovGet', 'lcovPut', 'manifestGet', 'manifestPut'], 'Coverage');
+    assertUrlMap(raw.blobs, ['get', 'put'], 'Blob');
+    return raw;
+}
+export function writeTransportControl(path, control) {
+    const validated = parseTransportControl(control);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(validated, null, 2)}\n`, {
+            flag: 'wx',
+            mode: 0o600,
+        });
+        chmodSync(temporary, 0o600);
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // The write/rename failure is the actionable error.
+        }
+        throw error;
+    }
+}
+export function readTransportControl(path, expected) {
+    if ((statSync(path).mode & 0o777) !== 0o600) {
+        throw new Error('Coverage transport control file must have mode 0600');
+    }
+    const control = parseTransportControl(JSON.parse(readFileSync(path, 'utf8')));
+    if (expected && !positiveInteger(expected.currentAttempt)) {
+        throw new Error('Coverage transport control identity does not match this run');
+    }
+    if (expected &&
+        (control.repository !== expected.repository ||
+            control.revision !== expected.revision ||
+            control.run.id !== expected.runId ||
+            control.run.controlAttempt > expected.currentAttempt)) {
+        throw new Error('Coverage transport control identity does not match this run');
+    }
+    if (control.mode === 'presigned' && Date.parse(control.expiresAt) <= Date.now()) {
+        throw new Error('Coverage transport control has expired');
+    }
+    return control;
+}

package/dist/coverage-transport/http.d.mts

@@ -0,0 +1,6 @@
+import type { RequestOptions } from './control.mts';
+export declare function redactTransportLog(value: unknown): string;
+export declare function coveragePresignFailureLog(error: unknown): string;
+export declare function logTransport(options: RequestOptions, line: string): void;
+export declare function fetchPut(url: string, body: Buffer, options?: RequestOptions): Promise<boolean>;
+export declare function fetchGet(url: string, options?: RequestOptions): Promise<Buffer | null>;

package/dist/coverage-transport/http.mjs

@@ -0,0 +1,99 @@
+import { DEFAULT_MAX_BODY_BYTES } from './constants.mjs';
+const FETCH_TIMEOUT_MS = 30_000;
+const FETCH_ATTEMPTS = 2;
+const DEFAULT_RETRY_DELAY_MS = 1000;
+function formatTransportError(value, seen) {
+    if (typeof value === 'object' && value !== null) {
+        if (seen.has(value))
+            return '[circular]';
+        seen.add(value);
+    }
+    if (value instanceof Error) {
+        const cause = value.cause !== undefined ? `; cause: ${formatTransportError(value.cause, seen)}` : '';
+        return `${value.name}: ${value.message}${cause}`;
+    }
+    return String(value);
+}
+export function redactTransportLog(value) {
+    return formatTransportError(value, new WeakSet()).replaceAll(/https?:\/\/[^\s]+/gi, '[redacted-url]');
+}
+export function coveragePresignFailureLog(error) {
+    return `[coverage-transport] presign failed: ${redactTransportLog(error)}; artifact fallback required`;
+}
+export function logTransport(options, line) {
+    ;
+    (options.log ?? ((message) => process.stderr.write(`${message}\n`)))(redactTransportLog(line));
+}
+async function delay(milliseconds) {
+    if (milliseconds <= 0)
+        return;
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function cancelBody(response) {
+    await response.body?.cancel();
+}
+async function readLimitedBody(response, maxBytes) {
+    if (response.body === null)
+        return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            return Buffer.concat(chunks);
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new Error('[coverage-transport] GET body exceeds size limit');
+        }
+        chunks.push(value);
+    }
+}
+async function request(method, url, body, options) {
+    for (let attempt = 1; attempt <= FETCH_ATTEMPTS; attempt += 1) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? FETCH_TIMEOUT_MS);
+        try {
+            const response = await fetch(url, {
+                method,
+                ...(body ? { body: new Uint8Array(body) } : {}),
+                signal: controller.signal,
+            });
+            // A missing presigned object is terminal. Let fetchGet yield null or fetchPut yield false
+            // without retrying the same URL or emitting a misleading transport-error diagnostic.
+            if (response.ok || response.status === 404) {
+                const payload = method === 'GET' && response.ok
+                    ? await readLimitedBody(response, options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES)
+                    : undefined;
+                if (payload === undefined)
+                    await cancelBody(response);
+                return { ok: response.ok, status: response.status, body: payload };
+            }
+            await cancelBody(response);
+            logTransport(options, `[coverage-transport] ${method} failed: HTTP ${response.status}`);
+        }
+        catch (error) {
+            logTransport(options, `[coverage-transport] ${method} error: ${redactTransportLog(error)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (attempt < FETCH_ATTEMPTS) {
+            await delay(options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS);
+        }
+    }
+    return null;
+}
+export async function fetchPut(url, body, options = {}) {
+    const response = await request('PUT', url, body, options);
+    return response?.ok === true;
+}
+export async function fetchGet(url, options = {}) {
+    const response = await request('GET', url, undefined, options);
+    if (response?.status === 404)
+        return null;
+    if (!response?.ok)
+        throw new Error('[coverage-transport] GET exhausted');
+    return response.body;
+}

package/dist/coverage-transport/index.d.mts

@@ -0,0 +1,6 @@
+export { DEFAULT_COVERAGE_MANIFEST_FILENAME, cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, } from './lib.mts';
+export { parseTransportControl, readTransportControl, writeTransportControl, type ExpectedTransportIdentity, type FallbackOnlyTransportControl, type PresignedBlobUrls, type PresignedCoverageUrls, type PresignedTransportControl, type RequestOptions, type TransportControl, } from './control.mts';
+export { coveragePresignFailureLog, fetchGet, fetchPut, logTransport, redactTransportLog, } from './http.mts';
+export { assertCoverageTransportBlobOutcome, assertCoverageTransportOutcome, isBlobPrimaryState, isStepOutcome, writeUploadOutcomeOutput, type AppendOutput, type BlobPrimaryState, type StepOutcome, } from './outcome.mts';
+export { downloadVitestBlobBundles, packVitestBlobBundle } from './vitest-blob-transport.mts';
+export { mintPresignedControl, transportObjectKeys, type MintPresignedControlOptions, type ObjectSigner, type PresignIdentity, } from './presign.mts';

package/dist/coverage-transport/index.mjs

@@ -0,0 +1,6 @@
+export { DEFAULT_COVERAGE_MANIFEST_FILENAME, cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, } from './lib.mjs';
+export { parseTransportControl, readTransportControl, writeTransportControl, } from './control.mjs';
+export { coveragePresignFailureLog, fetchGet, fetchPut, logTransport, redactTransportLog, } from './http.mjs';
+export { assertCoverageTransportBlobOutcome, assertCoverageTransportOutcome, isBlobPrimaryState, isStepOutcome, writeUploadOutcomeOutput, } from './outcome.mjs';
+export { downloadVitestBlobBundles, packVitestBlobBundle } from './vitest-blob-transport.mjs';
+export { mintPresignedControl, transportObjectKeys, } from './presign.mjs';

package/dist/coverage-transport/lib.d.mts

@@ -0,0 +1,17 @@
+import { type ExpectedTransportIdentity, type RequestOptions } from './control.mts';
+export { DEFAULT_COVERAGE_MANIFEST_FILENAME } from './constants.mts';
+interface UploadOptions extends RequestOptions {
+    readonly cwd?: string;
+    readonly expectedIdentity: ExpectedTransportIdentity;
+    readonly coverageManifestFilename?: string;
+}
+interface DownloadOptions extends RequestOptions {
+    readonly expectedIdentity: ExpectedTransportIdentity;
+    readonly coverageManifestFilename?: string;
+}
+export declare function cmdUpload(controlPath: string, suite: string, options: UploadOptions): Promise<{
+    coverage: boolean;
+    blob: boolean;
+}>;
+export declare function cmdDownloadCoverage(controlPath: string, destinationRoot: string, options: DownloadOptions): Promise<void>;
+export declare function cmdDownloadVitestBlobs(controlPath: string, destinationRoot: string, options: DownloadOptions): Promise<void>;

package/dist/coverage-transport/lib.mjs

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DEFAULT_COVERAGE_MANIFEST_FILENAME, DEFAULT_MAX_BODY_BYTES, assertCoverageManifestFilename, } from './constants.mjs';
+import { readTransportControl, } from './control.mjs';
+import { fetchGet, fetchPut, logTransport } from './http.mjs';
+import { downloadVitestBlobBundles, packVitestBlobBundle } from './vitest-blob-transport.mjs';
+export { DEFAULT_COVERAGE_MANIFEST_FILENAME } from './constants.mjs';
+export async function cmdUpload(controlPath, suite, options) {
+    const control = readTransportControl(controlPath, options.expectedIdentity);
+    if (control.mode === 'fallback-only') {
+        logTransport(options, `[coverage-transport] S3 unavailable for ${suite}; artifact fallback required`);
+        return { coverage: false, blob: false };
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const manifestFilename = options.coverageManifestFilename ?? DEFAULT_COVERAGE_MANIFEST_FILENAME;
+    assertCoverageManifestFilename(manifestFilename);
+    const coverageUrls = control.coverage[suite];
+    const lcovPath = join(cwd, 'coverage', 'lcov.info');
+    const manifestPath = join(cwd, 'coverage', manifestFilename);
+    const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const lcov = coverageUrls && existsSync(lcovPath) && existsSync(manifestPath)
+        ? await readFile(lcovPath)
+        : null;
+    const manifest = lcov === null ? null : await readFile(manifestPath);
+    const lcovStored = coverageUrls &&
+        lcov !== null &&
+        manifest !== null &&
+        lcov.byteLength <= maxBytes &&
+        manifest.byteLength <= maxBytes
+        ? await fetchPut(coverageUrls.lcovPut, lcov, options)
+        : false;
+    const coverage = lcovStored && coverageUrls && manifest !== null && manifest.byteLength <= maxBytes
+        ? await fetchPut(coverageUrls.manifestPut, manifest, options)
+        : false;
+    if (coverageUrls && existsSync(lcovPath) && existsSync(manifestPath)) {
+        logTransport(options, coverage
+            ? `[coverage-transport] Uploaded coverage pair for ${suite}`
+            : `[coverage-transport] Coverage pair upload failed for ${suite}`);
+    }
+    const blobUrls = control.blobs[suite];
+    const blobData = blobUrls
+        ? packVitestBlobBundle(cwd, suite, options.expectedIdentity, options)
+        : null;
+    const blob = Boolean(blobUrls && blobData && (await fetchPut(blobUrls.put, blobData, options)));
+    if (blob)
+        logTransport(options, `[coverage-transport] Uploaded vitest blob for ${suite}`);
+    else if (blobUrls && blobData) {
+        logTransport(options, `[coverage-transport] Vitest blob upload failed for ${suite}`);
+    }
+    return { coverage, blob };
+}
+export async function cmdDownloadCoverage(controlPath, destinationRoot, options) {
+    const control = readTransportControl(controlPath, options.expectedIdentity);
+    if (control.mode === 'fallback-only') {
+        logTransport(options, '[coverage-transport] S3 unavailable; artifact fallback required');
+        return;
+    }
+    const manifestFilename = options.coverageManifestFilename ?? DEFAULT_COVERAGE_MANIFEST_FILENAME;
+    assertCoverageManifestFilename(manifestFilename);
+    await Promise.all(Object.entries(control.coverage).map(async ([suite, urls]) => {
+        const [lcov, manifest] = await Promise.all([
+            fetchGet(urls.lcovGet, options),
+            fetchGet(urls.manifestGet, options),
+        ]);
+        if (!lcov || !manifest) {
+            logTransport(options, `[coverage-transport] Skipped incomplete coverage pair for ${suite}`);
+            return;
+        }
+        const destination = join(destinationRoot, `coverage-${suite}`);
+        mkdirSync(destination, { recursive: true });
+        writeFileSync(join(destination, 'lcov.info'), lcov);
+        writeFileSync(join(destination, manifestFilename), manifest, { mode: 0o600 });
+        logTransport(options, `[coverage-transport] Downloaded coverage pair for ${suite}`);
+    }));
+}
+export async function cmdDownloadVitestBlobs(controlPath, destinationRoot, options) {
+    const control = readTransportControl(controlPath, options.expectedIdentity);
+    if (control.mode === 'fallback-only') {
+        logTransport(options, '[coverage-transport] S3 unavailable; artifact fallback required');
+        return;
+    }
+    await downloadVitestBlobBundles(control.blobs, destinationRoot, options);
+}

package/dist/coverage-transport/outcome.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Transport exhaustion guards for a coverage pair and a Vitest blob, plus the
+ * `$GITHUB_OUTPUT` writer producers use when the upload exit code is not the blob signal.
+ */
+export type StepOutcome = 'success' | 'failure' | 'cancelled' | 'skipped';
+/**
+ * CLI argv values arrive as plain strings (or `undefined` when a positional arg was omitted); this
+ * narrows to `StepOutcome` so a caller can validate a step-outcome argument without an unchecked
+ * `as` cast.
+ */
+export declare function isStepOutcome(value: string | undefined): value is StepOutcome;
+export declare function assertCoverageTransportOutcome(suite: string, primary: StepOutcome, artifactAttempt1: StepOutcome, artifactAttempt2: StepOutcome, emit?: (line: string) => void): boolean;
+export type BlobPrimaryState = 'true' | 'false' | 'skipped';
+export declare function isBlobPrimaryState(value: string | undefined): value is BlobPrimaryState;
+/**
+ * Sibling to `assertCoverageTransportOutcome` for the Vitest blob. `true`/`false` are the S3
+ * upload step's `blob` output; `skipped` means that step never ran. GitHub fallback is always
+ * attempted when enabled — workflows must not gate it on `blob != 'true'`.
+ */
+export declare function assertCoverageTransportBlobOutcome(suite: string, primaryPersisted: BlobPrimaryState, artifactAttempt1: StepOutcome, artifactAttempt2: StepOutcome, emit?: (line: string) => void): boolean;
+export type AppendOutput = (path: string, data: string) => void;
+/**
+ * Writes `blob=true|false` to `$GITHUB_OUTPUT` for outcome reporting. GitHub-fallback blob upload
+ * must always be attempted when enabled; do not gate it on this signal. The upload subcommand's
+ * exit code tracks the coverage pair, not the blob. A no-op outside CI (`githubOutputPath` unset).
+ */
+export declare function writeUploadOutcomeOutput(outcome: {
+    readonly blob: boolean;
+}, githubOutputPath: string | undefined, appendOutput?: AppendOutput): void;

package/dist/coverage-transport/outcome.mjs

@@ -0,0 +1,70 @@
+import { appendFileSync } from 'node:fs';
+const STEP_OUTCOMES = new Set([
+    'success',
+    'failure',
+    'cancelled',
+    'skipped',
+]);
+/**
+ * CLI argv values arrive as plain strings (or `undefined` when a positional arg was omitted); this
+ * narrows to `StepOutcome` so a caller can validate a step-outcome argument without an unchecked
+ * `as` cast.
+ */
+export function isStepOutcome(value) {
+    return value !== undefined && STEP_OUTCOMES.has(value);
+}
+export function assertCoverageTransportOutcome(suite, primary, artifactAttempt1, artifactAttempt2, emit = (line) => process.stderr.write(`${line}\n`)) {
+    const primarySucceeded = primary === 'success';
+    const artifactSucceeded = artifactAttempt1 === 'success' || artifactAttempt2 === 'success';
+    if (primarySucceeded && artifactSucceeded)
+        return true;
+    if (primarySucceeded) {
+        emit(`::warning::Coverage persisted only to S3 for suite=${suite}; GitHub artifact fallback is degraded.`);
+        return true;
+    }
+    if (artifactSucceeded) {
+        emit(`::warning::Coverage persisted only to GitHub artifacts for suite=${suite}; S3 primary is degraded.`);
+        return true;
+    }
+    emit(`::error::COVERAGE_TRANSPORT_EXHAUSTED suite=${suite} Neither S3 nor GitHub artifacts persisted the coverage pair.`);
+    return false;
+}
+const BLOB_PRIMARY_STATES = new Set([
+    'true',
+    'false',
+    'skipped',
+]);
+export function isBlobPrimaryState(value) {
+    return value !== undefined && BLOB_PRIMARY_STATES.has(value);
+}
+/**
+ * Sibling to `assertCoverageTransportOutcome` for the Vitest blob. `true`/`false` are the S3
+ * upload step's `blob` output; `skipped` means that step never ran. GitHub fallback is always
+ * attempted when enabled — workflows must not gate it on `blob != 'true'`.
+ */
+export function assertCoverageTransportBlobOutcome(suite, primaryPersisted, artifactAttempt1, artifactAttempt2, emit = (line) => process.stderr.write(`${line}\n`)) {
+    const artifactSucceeded = artifactAttempt1 === 'success' || artifactAttempt2 === 'success';
+    if (primaryPersisted === 'true') {
+        if (!artifactSucceeded) {
+            emit(`::warning::Vitest blob persisted only to S3 for suite=${suite}; GitHub artifact fallback is degraded.`);
+        }
+        return true;
+    }
+    if (artifactSucceeded) {
+        if (primaryPersisted === 'false') {
+            emit(`::warning::Vitest blob persisted only to GitHub artifacts for suite=${suite}; S3 primary is degraded.`);
+        }
+        return true;
+    }
+    emit(`::error::COVERAGE_TRANSPORT_BLOB_EXHAUSTED suite=${suite} Neither S3 nor GitHub artifacts persisted the vitest blob.`);
+    return false;
+}
+/**
+ * Writes `blob=true|false` to `$GITHUB_OUTPUT` for outcome reporting. GitHub-fallback blob upload
+ * must always be attempted when enabled; do not gate it on this signal. The upload subcommand's
+ * exit code tracks the coverage pair, not the blob. A no-op outside CI (`githubOutputPath` unset).
+ */
+export function writeUploadOutcomeOutput(outcome, githubOutputPath, appendOutput = appendFileSync) {
+    if (githubOutputPath)
+        appendOutput(githubOutputPath, `blob=${String(outcome.blob)}\n`);
+}

package/dist/coverage-transport/presign.d.mts

@@ -0,0 +1,22 @@
+import type { PresignedTransportControl } from './control.mts';
+export interface PresignIdentity {
+    readonly repository: string;
+    readonly revision: string;
+    readonly runId: string;
+    readonly controlAttempt: number;
+}
+export interface ObjectSigner {
+    signPut(key: string, ttlSeconds: number): Promise<string>;
+    signGet(key: string, ttlSeconds: number): Promise<string>;
+}
+export interface MintPresignedControlOptions {
+    readonly ttlSeconds?: number;
+    readonly now?: () => Date;
+    readonly manifestFilename?: string;
+}
+export declare function transportObjectKeys(repository: string, runId: string, controlAttempt: number, suite: string, manifestFilename?: string): {
+    readonly lcov: string;
+    readonly manifest: string;
+    readonly blob: string;
+};
+export declare function mintPresignedControl(identity: PresignIdentity, coverageSuites: readonly string[], blobSuites: readonly string[], signer: ObjectSigner, options?: MintPresignedControlOptions): Promise<PresignedTransportControl>;