code-foundry 1.17.0 → 1.18.0

package/.github/workflows/qualified-foundry-publish.yml

@@ -0,0 +1,144 @@
+name: Qualified Foundry Publication
+
+on:
+  workflow_call:
+    inputs:
+      tag:
+        description: Published immutable release tag at the caller commit.
+        required: true
+        type: string
+      asset:
+        description: Exact pre-attached Code Foundry npm tarball name.
+        required: true
+        type: string
+      environment:
+        description: Protected GitHub environment for npm publication.
+        required: false
+        default: npm
+        type: string
+    secrets:
+      NPM_TOKEN:
+        required: false
+
+permissions:
+  attestations: read
+  contents: read
+
+jobs:
+  qualify:
+    name: Qualify Node ${{ matrix.node }}
+    if: vars.CI_BILLING_PAUSED != 'true' && github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ['20', '22', '24']
+    steps:
+      - name: Checkout trusted qualification runtime
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Install pinned Actionlint
+        run: go install github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
+      - name: Download and cryptographically verify the release archive
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.tag }}
+          RELEASE_ASSET: ${{ inputs.asset }}
+        run: |
+          set -euo pipefail
+          node src/commands/qualified-publication.mjs download \
+            "$GITHUB_REPOSITORY" "$RELEASE_TAG" "$GITHUB_SHA" "$RELEASE_ASSET" \
+            "$RUNNER_TEMP/candidate" > "$RUNNER_TEMP/download.json"
+      - name: Qualify those exact bytes
+        env:
+          RELEASE_ASSET: ${{ inputs.asset }}
+        run: |
+          set -euo pipefail
+          node src/lib/consumer-qualification.mjs \
+            "$RUNNER_TEMP/candidate/$RELEASE_ASSET" "$GITHUB_SHA" \
+            "$RUNNER_TEMP/report.json" "$(go env GOPATH)/bin/actionlint"
+      - name: Retain this attempt's qualification report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: qualified-${{ github.run_attempt }}-node-${{ matrix.node }}
+          path: ${{ runner.temp }}/report.json
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    name: Publish qualified archive
+    needs: qualify
+    if: vars.CI_BILLING_PAUSED != 'true' && github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment: ${{ inputs.environment }}
+    concurrency:
+      group: qualified-foundry-npm-${{ github.repository }}-${{ inputs.tag }}
+      cancel-in-progress: false
+    permissions:
+      actions: read
+      attestations: read
+      contents: read
+      id-token: write
+    env:
+      HAS_NPM_TOKEN: ${{ secrets.NPM_TOKEN != '' }}
+      RELEASE_TAG: ${{ inputs.tag }}
+      RELEASE_ASSET: ${{ inputs.asset }}
+    steps:
+      - name: Checkout trusted publication runtime
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - name: Setup Node for trusted publishing
+        if: env.HAS_NPM_TOKEN != 'true'
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '24'
+      - name: Setup Node for token publishing
+        if: env.HAS_NPM_TOKEN == 'true'
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '24'
+          registry-url: https://registry.npmjs.org
+      - name: Retrieve only this run attempt's evidence
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          for node in 20 22 24; do
+            gh run download "$GITHUB_RUN_ID" --repo "$GITHUB_REPOSITORY" \
+              --name "qualified-$GITHUB_RUN_ATTEMPT-node-$node" \
+              --dir "$RUNNER_TEMP/reports/$node"
+          done
+          node src/commands/qualified-publication.mjs download \
+            "$GITHUB_REPOSITORY" "$RELEASE_TAG" "$GITHUB_SHA" "$RELEASE_ASSET" \
+            "$RUNNER_TEMP/candidate" > "$RUNNER_TEMP/download.json"
+      - name: Reverify and publish the tested tarball without lifecycle hooks
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+          node src/commands/qualified-publication.mjs publish \
+            "$GITHUB_REPOSITORY" "$RELEASE_TAG" "$GITHUB_SHA" "$RELEASE_ASSET" \
+            "$RUNNER_TEMP/candidate" \
+            "$RUNNER_TEMP/reports/20/report.json" \
+            "$RUNNER_TEMP/reports/22/report.json" \
+            "$RUNNER_TEMP/reports/24/report.json" > "$RUNNER_TEMP/publication.json"
+      - name: Retain publication identity
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: qualified-publication-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/publication.json
+          if-no-files-found: warn
+          retention-days: 14

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.18.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.17.0...v1.18.0) (2026-09-09)
+
+
+### Features
+
+* **releases:** stage qualified assets and publish verified identical archives ([#547](https://github.com/0xPlayerOne/code-foundry/issues/547)) ([dffcb83](https://github.com/0xPlayerOne/code-foundry/commit/dffcb834c8ee8c5c2bcba606350276e6a7de58d0))
+
 ## [1.17.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.16.0...v1.17.0) (2026-09-09)
 
 

package/docs/PERFORMANCE.md

@@ -15,8 +15,8 @@ belong to the run that produced them, not the source tree.
 | Format, lint, type-check, and build |   15 s | Bound the local CI feedback loop                     |
 | Runtime dependencies                |      0 | Keep the installed CLI dependency-free               |
 | Development dependencies            |      4 | Prevent unreviewed toolchain growth                  |
-| Packed artifact                     | 240 kB | Bound registry transfer and install cost             |
-| Unpacked artifact                   | 900 kB | Bound installed footprint                            |
+| Packed artifact                     | 250 kB | Bound registry transfer and install cost             |
+| Unpacked artifact                   | 930 kB | Bound installed footprint                            |
 | Packed files                        |    110 | Detect accidental release contents                   |
 
 The performance workflow disables build-cache reads and writes for this task.
@@ -30,6 +30,10 @@ budgets leave a small margin while continuing to bound package growth. The
 product-quality profiles and consumer qualification workflow measured 232,650
 packed bytes, 890,418 unpacked bytes, and 103 files on Node 24.18.0, so the
 limits remain intentionally bounded while covering both opt-in feature sets.
+The qualified-publication workflow adds the release staging and publication
+contract to the distributable. This candidate measured 238,816 packed bytes,
+915,957 unpacked bytes, and 106 files on Node 24.18.0; the 250 kB and 930 kB
+limits retain a measured margin while covering the required release path.
 
 ## v1.6.1 baseline
 

package/docs/qualified-publication.md

@@ -0,0 +1,111 @@
+# Qualified Publication
+
+Publish only the same immutable Code Foundry archive that passed consumer qualification.
+
+**Dependencies:** Consumer qualification (#544) and release integrity (#537).
+**Activation:** Opt-in replacement publisher; no existing publisher is silently changed.
+
+The reusable `qualified-foundry-publish.yml` downloads an explicitly named npm
+archive from an already-published immutable release, verifies the release and
+asset attestations against the caller's exact commit, qualifies that same archive
+on Node 20/22/24, and only then admits a protected npm publication job. The final
+job downloads only reports from its own workflow run **and run attempt**, rechecks
+all required fixtures and archive/source identities, repeats cryptographic asset
+verification, validates the package name/version, and publishes the tarball with
+lifecycle scripts disabled. It never publishes a directory or rebuilds the package.
+
+The publishing job uses a GitHub environment, serializes publication for a tag,
+and has no dependency installation/build step. Qualification has no npm credential.
+Normal npm trusted publishing is preferred; an explicit optional token supports
+existing consumers. Configure the trusted publisher for the **actual caller and
+reusable-workflow relationship** before enabling this route. Existing version
+publication is not overwritten: retrying an already-published version fails rather
+than treating a registry conflict or network error as proof of identity.
+
+## Release producer contract
+
+Build and test a package once, attach its tarball to a **draft** release, then
+publish that release with immutability enabled. The archive must contain the
+Code Foundry CLI/templates; this is intentionally not a generic package harness.
+The candidate's `package.json` name must be `code-foundry` and its version must
+match the explicit tag. All qualification modules must exist in the caller commit.
+A recent GitHub CLI with `release verify` and `release verify-asset` is required;
+missing support or authentication errors fail closed.
+
+This workflow blocks npm publication, not a GitHub Release that was already
+published. It does **not** add assets after an immutable release is published.
+The `stage` command implements the draft-asset producer: it verifies qualification,
+checks immutability without changing settings, resolves the existing tag to the
+qualified commit, uploads the archive and digest-bound qualification receipt,
+rechecks uploaded digests, then publishes and verifies the release. It requires
+an existing draft and existing tag; it never creates/moves tags or overwrites
+conflicting assets. Settings permission failures block writes. Matching existing
+assets can resume staging; conflicting assets require manual reconciliation.
+The pre-release gate in #544 supplies the required matrix reports.
+The legacy Release Please workflow creates releases without
+this archive staging step. Wire the new `stage` command into a draft-producing
+caller instead of pointing the old direct-release caller at the new publisher:
+
+```sh
+node src/commands/qualified-publication.mjs stage \
+  "$GITHUB_REPOSITORY" "$TAG" "$SOURCE_SHA" "$ASSET" "$CANDIDATE_DIRECTORY" \
+  "$REPORT_NODE_20" "$REPORT_NODE_22" "$REPORT_NODE_24"
+```
+
+The stage command needs a credential with immutable-setting read, release
+write, and attestation-read access; a normal Actions token may lack the
+administration-read permission.
+No elevated credential is installed or requested automatically. The producer must
+also prevent concurrent tag mutation (for example with protected release-tag
+rules and a single tag-scoped producer); GitHub does not offer an atomic
+"publish this draft only if the tag still resolves to SHA" operation. The final
+verification blocks npm if that invariant is violated, but cannot undo an
+already-published immutable release.
+
+Disable the old npm path before
+activating the replacement to prevent racing publishers. None of those production
+settings or existing release workflows are changed in this PR.
+
+Example caller job after its release producer (illustrative job IDs):
+
+```yaml
+permissions:
+  actions: read
+  attestations: read
+  contents: read
+  id-token: write
+jobs:
+  publish:
+    needs: release-producer
+    uses: ./.github/workflows/qualified-foundry-publish.yml
+    with:
+      tag: ${{ needs.release-producer.outputs.tag }}
+      asset: ${{ needs.release-producer.outputs.npm-asset }}
+      environment: npm
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Only main-branch `push` and `workflow_dispatch` callers are admitted. Pull-request
+events (including fork PRs), release-event shortcuts, and billing-paused runs
+cannot publish through this workflow. The event guard does not itself verify
+branch protection or prohibit a fork's independent main-branch workflow; configure
+branch/environment protections and registry publisher identity separately.
+The tag must resolve to `github.sha`, not a caller-selected old commit. To retry
+an older release after main moves, use a separately reviewed recovery procedure;
+do not weaken the identity gate ad hoc.
+
+## Local policy tests and trust
+
+`node --test test/qualified-publication.test.mjs` uses CLI/verifier fixtures to
+exercise missing matrix members, skipped checks, absent Actionlint, changed
+archives, invalid asset names, wrong package identity, and prevention of npm
+execution before verification. These tests do not establish live GitHub signing,
+OIDC permissions, registry publication, or runner tool availability.
+
+Qualification reports are not standalone signatures: they are trusted only after
+selection from this workflow's successful jobs in the same run attempt. Supplying
+arbitrary local JSON to the library is not a security boundary. The reusable
+workflow and its caller must be reviewed/trusted and protected; repository-owned
+code executes with the permissions of its job. No credentials or production
+resources were configured by adding this feature.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "A fast, language-aware repository factory for agent-ready workflows, testing, security, and release automation.",
   "homepage": "https://github.com/0xPlayerOne/code-foundry#readme",
   "bugs": {

package/src/commands/qualified-publication.mjs

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+// @ts-check
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import {
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { tmpdir } from 'node:os'
+
+export const REQUIRED_NODES = ['20', '22', '24']
+export const REQUIRED_FIXTURES = [
+  'npm-direct',
+  'pnpm-direct',
+  'yarn-staging',
+  'bun-mise',
+  'nested-rust',
+  'nested-python',
+]
+/** @typedef {{ repository: string, tag: string, sourceSha: string, asset: string, directory: string }} Candidate */
+/** @typedef {(command:string, args:string[], cwd?:string) => string} Run */
+/** @param {unknown} condition @param {string} message @returns {asserts condition} */
+function ensure(condition, message) {
+  if (!condition) throw new Error(message)
+}
+/** @type {Run} */
+export function runCommand(command, args, cwd) {
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    timeout: 180_000,
+    maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, GH_HOST: 'github.com', GH_PROMPT_DISABLED: '1' },
+  })
+  ensure(
+    !result.error && result.status === 0,
+    `${command} failed (${result.status ?? result.error?.message}); publication remains blocked`
+  )
+  return result.stdout
+}
+/** @param {Candidate} candidate */
+export function validateCandidate(candidate) {
+  ensure(
+    /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(candidate.repository) &&
+      !candidate.repository.split('/').some((part) => ['.', '..'].includes(part)),
+    'Expected an owner/repository'
+  )
+  ensure(
+    /^v\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(candidate.tag),
+    'Expected an explicit version tag'
+  )
+  ensure(/^[a-f0-9]{40}$/.test(candidate.sourceSha), 'Expected an exact source SHA')
+  ensure(
+    /^[A-Za-z0-9][A-Za-z0-9._-]*\.tgz$/.test(candidate.asset),
+    'Expected one exact tarball asset name'
+  )
+}
+/** @param {string} file */
+export function sha256(file) {
+  ensure(
+    lstatSync(file).isFile() && !lstatSync(file).isSymbolicLink(),
+    'Expected a regular non-symlink file'
+  )
+  const bytes = readFileSync(file)
+  ensure(bytes.length > 0, 'Empty artifact or report')
+  return createHash('sha256').update(bytes).digest('hex')
+}
+/** Pure policy check. Only reports from this workflow run are accepted by the caller.
+ * @param {unknown[]} reports @param {string} sourceSha @param {string} artifactSha256
+ */
+export function validateQualificationReports(reports, sourceSha, artifactSha256) {
+  ensure(
+    reports.length === REQUIRED_NODES.length,
+    'Every required Node qualification report is mandatory'
+  )
+  const seen = new Set()
+  for (const value of reports) {
+    const report = /** @type {Record<string, any>} */ (value)
+    ensure(
+      report?.schema_version === 1 && report.complete === true && report.actionlint === true,
+      'Incomplete or unlinted qualification report'
+    )
+    ensure(
+      report.source_sha === sourceSha && report.artifact_sha256 === artifactSha256,
+      'Qualification source or archive identity mismatch'
+    )
+    const node = /^v(\d+)\.\d+\.\d+$/.exec(report.node ?? '')?.[1]
+    ensure(
+      node && REQUIRED_NODES.includes(node) && !seen.has(node),
+      'Unexpected or duplicate Node qualification'
+    )
+    seen.add(node)
+    ensure(
+      Array.isArray(report.fixtures) && report.fixtures.length === REQUIRED_FIXTURES.length,
+      'Incomplete consumer fixture matrix'
+    )
+    for (const fixture of REQUIRED_FIXTURES)
+      ensure(
+        report.fixtures.filter(
+          (/** @type {Record<string,any>} */ entry) =>
+            entry.name === fixture && entry.status === 'passed'
+        ).length === 1,
+        `Missing successful fixture: ${fixture}`
+      )
+  }
+  return {
+    nodes: REQUIRED_NODES.filter((node) => seen.has(node)),
+    fixtures: [...REQUIRED_FIXTURES],
+  }
+}
+/** @param {Candidate} candidate */
+async function verifier(candidate) {
+  // Supplied by the separately reviewed release-integrity feature (#537).
+  const { verifyRelease } = await import('./release-integrity.mjs')
+  return verifyRelease({
+    repository: candidate.repository,
+    tag: candidate.tag,
+    expectedSha: candidate.sourceSha,
+    root: candidate.directory,
+    assets: [candidate.asset],
+  })
+}
+/** @typedef {(candidate:Candidate) => Promise<any>} Verify */
+/** @param {Candidate} candidate @param {{run?:Run, verify?:Verify}} [adapters] */
+export async function downloadVerifiedArchive(candidate, adapters = {}) {
+  validateCandidate(candidate)
+  const run = adapters.run ?? runCommand
+  const verify = adapters.verify ?? verifier
+  mkdirSync(candidate.directory, { recursive: true })
+  ensure(
+    lstatSync(candidate.directory).isDirectory() &&
+      !lstatSync(candidate.directory).isSymbolicLink(),
+    'Download directory must be a real directory'
+  )
+  ensure(readdirSync(candidate.directory).length === 0, 'Use a fresh empty download directory')
+  run('gh', [
+    'release',
+    'download',
+    candidate.tag,
+    '--repo',
+    candidate.repository,
+    '--pattern',
+    candidate.asset,
+    '--dir',
+    candidate.directory,
+  ])
+  ensure(
+    readdirSync(candidate.directory).length === 1 &&
+      readdirSync(candidate.directory)[0] === candidate.asset,
+    'Unexpected downloaded release files'
+  )
+  const file = join(realpathSync(candidate.directory), candidate.asset)
+  const digest = sha256(file)
+  const identity = await verify(candidate)
+  ensure(
+    identity.status === 'passed' &&
+      identity.immutable === true &&
+      identity.sourceSha === candidate.sourceSha,
+    'Release verification did not establish candidate identity'
+  )
+  ensure(
+    identity.assets?.length === 1 && identity.assets[0].digest === `sha256:${digest}`,
+    'Verified release asset differs from downloaded bytes'
+  )
+  ensure(sha256(file) === digest, 'Archive changed during verification')
+  return { file, digest, identity }
+}
+/** @param {Candidate} candidate @param {string[]} reportPaths @param {Run} [run] */
+export function qualifyArchive(candidate, reportPaths, run = runCommand) {
+  validateCandidate(candidate)
+  const file = join(realpathSync(candidate.directory), candidate.asset)
+  const digest = sha256(file)
+  const reports = reportPaths.map((path) => {
+    sha256(path)
+    return JSON.parse(readFileSync(path, 'utf8'))
+  })
+  const qualification = validateQualificationReports(reports, candidate.sourceSha, digest)
+  // Read one manifest without extracting archive paths into the workspace.
+  const manifest = JSON.parse(run('tar', ['-xOf', file, 'package/package.json']))
+  ensure(
+    manifest.name === 'code-foundry' && manifest.version === candidate.tag.slice(1),
+    'Archive package identity does not match this Code Foundry release'
+  )
+  return {
+    schemaVersion: 1,
+    kind: 'code-foundry-publication-eligibility',
+    repository: candidate.repository,
+    tag: candidate.tag,
+    sourceSha: candidate.sourceSha,
+    asset: candidate.asset,
+    digest: `sha256:${digest}`,
+    qualification,
+  }
+}
+/** @param {Candidate} candidate @param {string[]} reports @param {{run?:Run, verify?:Verify}} [adapters] */
+export async function publishQualifiedArchive(candidate, reports, adapters = {}) {
+  const run = adapters.run ?? runCommand
+  const before = qualifyArchive(candidate, reports, run)
+  const identity = await (adapters.verify ?? verifier)(candidate)
+  ensure(
+    identity.status === 'passed' &&
+      identity.immutable === true &&
+      identity.sourceSha === before.sourceSha &&
+      identity.assets?.length === 1 &&
+      identity.assets[0].digest === before.digest,
+    'Current release verification does not match qualified bytes'
+  )
+  const file = join(realpathSync(candidate.directory), candidate.asset)
+  ensure(`sha256:${sha256(file)}` === before.digest, 'Qualified archive changed before publication')
+  // Never publish a directory, rebuild, or invoke package lifecycle hooks here.
+  run(
+    'npm',
+    ['publish', file, '--ignore-scripts', '--provenance', '--access', 'public'],
+    candidate.directory
+  )
+  ensure(`sha256:${sha256(file)}` === before.digest, 'Archive changed during publication')
+  return { ...before, status: 'published' }
+}
+
+/** Stage only a previously-created draft: never move tags, overwrite assets, or
+ * treat an API/permissions failure as an absent release. Authentication needs
+ * immutable-settings read and release write; no setting is mutated.
+ * @param {Candidate} candidate @param {string[]} reports @param {{run?:Run, verify?:Verify}} [adapters]
+ */
+export async function stageQualifiedRelease(candidate, reports, adapters = {}) {
+  const run = adapters.run ?? runCommand
+  const qualification = qualifyArchive(candidate, reports, run)
+  const api = (/** @type {string} */ endpoint) =>
+    JSON.parse(run('gh', ['api', '--hostname', 'github.com', endpoint]))
+  const prefix = `repos/${candidate.repository}`
+  ensure(
+    api(`${prefix}/immutable-releases`).enabled === true,
+    'Release immutability is not confirmed enabled; no release write performed'
+  )
+  const checkTag = () => {
+    let object = api(`${prefix}/git/ref/tags/${encodeURIComponent(candidate.tag)}`).object
+    for (let depth = 0; object?.type === 'tag' && depth < 8; depth++) {
+      ensure(/^[a-f0-9]{40}$/.test(object.sha ?? ''), 'Invalid annotated tag')
+      object = api(`${prefix}/git/tags/${object.sha}`).object
+    }
+    ensure(
+      object?.type === 'commit' && object.sha === candidate.sourceSha,
+      'Release tag does not identify the qualified commit'
+    )
+  }
+  checkTag()
+  const endpoint = `${prefix}/releases/tags/${encodeURIComponent(candidate.tag)}`
+  const release = api(endpoint)
+  ensure(
+    Number.isSafeInteger(release.id) &&
+      release.draft === true &&
+      release.tag_name === candidate.tag &&
+      Array.isArray(release.assets),
+    'An existing draft release with the exact tag is required'
+  )
+  const temporary = mkdtempSync(join(tmpdir(), 'foundry-release-receipt-'))
+  try {
+    const receipt = join(temporary, 'qualification.json')
+    writeFileSync(receipt, JSON.stringify(qualification, null, 2) + '\n')
+    const files = [join(realpathSync(candidate.directory), candidate.asset), receipt]
+    const expected = [qualification.digest, `sha256:${sha256(receipt)}`]
+    const names = [candidate.asset, 'qualification.json']
+    for (let index = 0; index < files.length; index++) {
+      const existing = release.assets.filter(
+        (/** @type {Record<string, any>} */ asset) => asset.name === names[index]
+      )
+      ensure(existing.length <= 1, 'Ambiguous existing release asset')
+      if (existing.length)
+        ensure(
+          existing[0].state === 'uploaded' && existing[0].digest === expected[index],
+          'Existing draft asset differs; refusing to overwrite it'
+        )
+      else
+        run('gh', [
+          'release',
+          'upload',
+          candidate.tag,
+          files[index],
+          '--repo',
+          candidate.repository,
+        ])
+    }
+    const uploaded = api(endpoint)
+    ensure(
+      uploaded.id === release.id && uploaded.draft === true && uploaded.tag_name === candidate.tag,
+      'Draft changed during staging'
+    )
+    for (let index = 0; index < names.length; index++) {
+      const assets =
+        uploaded.assets?.filter(
+          (/** @type {Record<string, any>} */ asset) => asset.name === names[index]
+        ) ?? []
+      ensure(
+        assets.length === 1 &&
+          assets[0].state === 'uploaded' &&
+          assets[0].digest === expected[index],
+        'Uploaded release asset digest mismatch'
+      )
+      ensure(
+        `sha256:${sha256(files[index])}` === expected[index],
+        'Local asset changed during staging'
+      )
+    }
+    checkTag()
+    run('gh', [
+      'release',
+      'edit',
+      candidate.tag,
+      '--draft=false',
+      '--verify-tag',
+      '--repo',
+      candidate.repository,
+    ])
+    const identity = await (adapters.verify ?? verifier)(candidate)
+    ensure(
+      identity.status === 'passed' &&
+        identity.immutable === true &&
+        identity.sourceSha === qualification.sourceSha &&
+        identity.assets?.length === 1 &&
+        identity.assets[0].digest === qualification.digest,
+      'Published release verification failed; npm remains blocked'
+    )
+    return { ...qualification, status: 'release-published-and-verified' }
+  } finally {
+    rmSync(temporary, { recursive: true, force: true })
+  }
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  try {
+    const [command, repository, tag, sourceSha, asset, directory, ...reports] =
+      process.argv.slice(2)
+    if (!directory || !['download', 'qualify', 'stage', 'publish'].includes(command))
+      throw new Error(
+        'Usage: qualified-publication.mjs download|qualify|stage|publish REPO TAG SOURCE_SHA ASSET DIRECTORY [REPORT.json ...]'
+      )
+    const candidate = { repository, tag, sourceSha, asset, directory: resolve(directory) }
+    if (command === 'download' && reports.length)
+      throw new Error('download does not take report paths')
+    const result =
+      command === 'download'
+        ? await downloadVerifiedArchive(candidate)
+        : command === 'qualify'
+          ? qualifyArchive(candidate, reports)
+          : command === 'stage'
+            ? await stageQualifiedRelease(candidate, reports)
+            : await publishQualifiedArchive(candidate, reports)
+    console.log(JSON.stringify(result, null, 2))
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}