@kungfu-tech/buildchain 2.5.7 → 2.6.0-alpha.0

package/bin/buildchain.mjs

@@ -25,6 +25,10 @@ import {
   explainReleasePassport,
   verifyReleasePassport,
 } from "../packages/core/release-passport.js";
+import {
+  explainArtifactPassport,
+  verifyArtifactPassport,
+} from "../packages/core/artifact-passport.js";
 import {
   BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT,
   formatDiagnosticsSummaryTable,
@@ -74,13 +78,18 @@ function usage() {
                                     [--release-extra-json <json-or-path>]
                                     [--publish-json <json-or-path>] [--output-dir <dir>] [--json]
   buildchain verify release-passport <file-or-url> [--json]
+  buildchain verify artifact <file|dir|url|npm:...|oci:...|github-release:...>
+                             [--passport <file-or-url>] [--locator-config <json>]
+                             [--repository <owner/repo>] [--tag <tag>] [--json]
   buildchain verify infra-contract-evidence-bundle <file> [--json]
   buildchain verify observability-log <jsonl> [--min-events <n>]
                                              [--require-phase <csv>]
                                              [--require-component <csv>]
                                              [--require-event <csv>] [--allow-errors] [--json]
   buildchain explain release --passport <file-or-url> [--for human|agent] [--json]
+  buildchain explain artifact <subject> [--passport <file-or-url>] [--for human|agent] [--json]
   buildchain inspect release --passport <file-or-url> [--json]
+  buildchain inspect artifact <subject> [--passport <file-or-url>] [--json]
   buildchain doctor [--cwd <dir>] [--require-publish-source-lock] [--json]
   buildchain log <info|warn|error> --event <name> [--phase <phase>]
                  [--component <name>] [--source <name>] [--attribute key=value]...
@@ -110,6 +119,7 @@ Examples:
   buildchain span --event native.build -- cmake --build build
   buildchain collect github-release --tag v2.2.0 --assets-dir dist --output-dir .buildchain/release-passport
   buildchain verify release-passport .buildchain/release-passport/buildchain.release.json
+  buildchain verify artifact ./dist/buildchain-x86_64-unknown-linux-gnu.tar.gz --passport .buildchain/release-passport/buildchain.release.json
   buildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json
   buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build
   buildchain infra-contract --mode plan --source-sha <sha>
@@ -736,6 +746,34 @@ async function main(argv = process.argv.slice(2)) {
 
   if (command === "verify") {
     const [subcommand = "", location = "", ...verifyArgs] = args;
+    if (subcommand === "artifact") {
+      if (!location) {
+        throw new Error("usage: buildchain verify artifact <subject>");
+      }
+      const report = await verifyArtifactPassport({
+        subject: location,
+        cwd: process.cwd(),
+        passportLocation: readFlag(verifyArgs, "passport", ""),
+        locatorConfig: readFlag(verifyArgs, "locator-config", ""),
+        repository: readFlag(verifyArgs, "repository", ""),
+        tag: readFlag(verifyArgs, "tag", ""),
+        githubReleaseBaseUrl: readFlag(verifyArgs, "github-release-base-url", ""),
+        subjectDigest: readFlag(verifyArgs, "subject-digest", ""),
+        subjectKind: readFlag(verifyArgs, "subject-kind", ""),
+      });
+      if (readBooleanFlag(verifyArgs, "json")) {
+        printJson(report);
+      } else {
+        process.stdout.write(`artifact: ${report.outcome}\n`);
+        process.stdout.write(`subject: ${report.subject?.name || location}\n`);
+        process.stdout.write(`passport: ${report.passport?.location || report.discovery?.passportLocation || "unresolved"}\n`);
+        for (const entry of report.issues) {
+          process.stdout.write(`- ${entry.level}: ${entry.code}: ${entry.message}\n`);
+        }
+      }
+      process.exitCode = report.ok ? 0 : 1;
+      return;
+    }
     if (subcommand === "observability-log") {
       if (!location) {
         throw new Error("usage: buildchain verify observability-log <jsonl>");
@@ -797,6 +835,33 @@ async function main(argv = process.argv.slice(2)) {
 
   if (command === "explain") {
     const [subcommand = "", ...explainArgs] = args;
+    if (subcommand === "artifact") {
+      const subject = explainArgs[0] || "";
+      if (!subject) {
+        throw new Error("usage: buildchain explain artifact <subject>");
+      }
+      const explanation = await explainArtifactPassport({
+        subject,
+        cwd: process.cwd(),
+        passportLocation: readFlag(explainArgs, "passport", ""),
+        locatorConfig: readFlag(explainArgs, "locator-config", ""),
+        repository: readFlag(explainArgs, "repository", ""),
+        tag: readFlag(explainArgs, "tag", ""),
+        githubReleaseBaseUrl: readFlag(explainArgs, "github-release-base-url", ""),
+        subjectDigest: readFlag(explainArgs, "subject-digest", ""),
+        subjectKind: readFlag(explainArgs, "subject-kind", ""),
+        forAudience: readFlag(explainArgs, "for", "human"),
+      });
+      if (readBooleanFlag(explainArgs, "json")) {
+        printJson(explanation);
+      } else {
+        process.stdout.write(`artifact: ${explanation.subject?.name || subject}\n`);
+        process.stdout.write(`trust: ${explanation.trust}\n`);
+        process.stdout.write(`next action: ${explanation.nextAction}\n`);
+      }
+      process.exitCode = explanation.trust === "pass" ? 0 : 1;
+      return;
+    }
     if (subcommand !== "release") {
       throw new Error("usage: buildchain explain release --passport <file-or-url>");
     }
@@ -820,6 +885,26 @@ async function main(argv = process.argv.slice(2)) {
 
   if (command === "inspect") {
     const [subcommand = "", ...inspectArgs] = args;
+    if (subcommand === "artifact") {
+      const subject = inspectArgs[0] || "";
+      if (!subject) {
+        throw new Error("usage: buildchain inspect artifact <subject>");
+      }
+      const report = await verifyArtifactPassport({
+        subject,
+        cwd: process.cwd(),
+        passportLocation: readFlag(inspectArgs, "passport", ""),
+        locatorConfig: readFlag(inspectArgs, "locator-config", ""),
+        repository: readFlag(inspectArgs, "repository", ""),
+        tag: readFlag(inspectArgs, "tag", ""),
+        githubReleaseBaseUrl: readFlag(inspectArgs, "github-release-base-url", ""),
+        subjectDigest: readFlag(inspectArgs, "subject-digest", ""),
+        subjectKind: readFlag(inspectArgs, "subject-kind", ""),
+      });
+      printJson(report);
+      process.exitCode = report.ok ? 0 : 1;
+      return;
+    }
     if (subcommand !== "release") {
       throw new Error("usage: buildchain inspect release --passport <file-or-url>");
     }

package/dist/site/release-provenance.json

@@ -10,6 +10,7 @@
     "exports": {
       ".": "./packages/core/index.js",
       "./core": "./packages/core/index.js",
+      "./artifact-passport": "./packages/core/artifact-passport.js",
       "./diagnostics": "./packages/core/diagnostics.js",
       "./issue-reporting": "./packages/core/issue-reporting.js",
       "./logging": "./packages/core/logging.js",

package/docs/cli.md

@@ -304,6 +304,58 @@ The verifier fails closed when required protocol files are absent, artifacts are
 not covered by evidence, or digests disagree. The explanation output is shaped
 for agents: trust, completeness, impact, recovery route, and next action.
 
+Verify a published artifact by subject:
+
+```bash
+buildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe
+buildchain inspect artifact ./Kungfu-2.8.0-windows-x64.exe --json
+buildchain explain artifact ./Kungfu-2.8.0-windows-x64.exe --for agent --json
+```
+
+`verify artifact` computes or obtains the subject digest, discovers the
+detached release passport, verifies the passport, then requires that the
+subject digest appears in the passport's release assets, package set, publish
+evidence, or artifact evidence. Outcomes are explicit: `pass`, `fail`, or
+`unverifiable`. A filename is only a hint; trust comes from digest equality.
+
+Discovery is fail-closed and ordered:
+
+1. `--passport <file-or-url>`.
+2. Sidecar pointer, such as `<artifact>.buildchain-passport.json`.
+3. Embedded/package pointer, such as `package.json` `buildchain.releasePassport`.
+4. Local config or org index, such as `.buildchain/artifact-passport-locators.json`.
+5. GitHub Release default discovery from `github-release:` subjects, GitHub
+   Release asset URLs, or `--repository <owner/repo> --tag <tag>`.
+6. Custom `--locator-config <json-or-url>`.
+7. `unverifiable` with retry guidance.
+
+Locator files are policy, not protocol. They map subject fields such as
+`name`, `kind`, `version`, `digest`, `repository`, or `tag` to a detached
+passport location:
+
+```json
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-artifact-passport-locator",
+  "locators": [
+    {
+      "match": {
+        "name": "Kungfu-2.8.0-windows-x64.exe",
+        "digest": "sha256:..."
+      },
+      "passport": "../release-passport/buildchain.release.json"
+    }
+  ]
+}
+```
+
+Supported subject shapes include local files and directories, URLs,
+`npm:<name>@<version>`, `oci:...`, `s3:...`,
+`github-release:<owner/repo>@<tag>/<asset>`, and deployment endpoints. Local
+files, directories, and URLs are digestable directly; remote package, OCI,
+object storage, and deployment subjects should provide a digest or resolve to a
+locator that records one.
+
 Verify infra-contract lifecycle evidence bundles:
 
 ```bash

package/docs/release-governance.md

@@ -250,6 +250,23 @@ After each merge, the next PR is re-evaluated before it can move the protected
 dev branch. This prevents one merge from silently making the next candidate
 stale or conflicting.
 
+The required check should be the `check` job. Repositories can keep that job
+name stable while changing the actual verification command declaratively in
+`buildchain.toml`:
+
+```toml
+[lifecycle.install]
+command = "cargo fetch --locked"
+
+[lifecycle.verify]
+command = "cargo test --workspace --locked"
+```
+
+Consumers that want Buildchain to own the check wrapper can call
+`.github/workflows/check.yml@v2`. The wrapper runs the declared
+`lifecycle.install` and `lifecycle.verify` stages and fails the `check` job when
+either declaration is missing or the command exits non-zero.
+
 Typical consumer wrapper:
 
 ```yaml
@@ -273,8 +290,8 @@ jobs:
       checks: read
       statuses: read
     with:
-      target-branch: dev/v2/v2.5
-      required-status-checks: Verify
+      target-branch: dev/v2/v2.6
+      required-status-checks: check
       ready-label: ready
       block-labels: blocked,do-not-merge
       max-merges: 1
@@ -315,7 +332,6 @@ jobs:
   patrol:
     uses: kungfu-systems/buildchain/.github/workflows/patrol-daily.yml@v2
     with:
-      target-branch: dev/v2/v2.5
       dry-run: false
       max-actions: 1
 ```
@@ -327,14 +343,14 @@ jobs:
   patrol:
     uses: kungfu-systems/buildchain/.github/workflows/patrol-weekly.yml@v2
     with:
-      target-branch: dev/v2/v2.5
       dry-run: true
 ```
 
-All three wrappers call the same underlying Buildchain patrol protocol, but the
-separate workflow names keep consumer schedules readable and stable. Buildchain
-can add new checks behind the cadence wrappers without forcing every consumer
-repository to rewrite its schedule YAML.
+All three wrappers default to the `v2` floating Buildchain runtime. When
+`target-branch` is omitted, the caller's current/default branch selects the
+active semver dev line, so consumers do not pin patrol to a stale minor branch.
+The separate workflow names keep consumer schedules readable and stable while
+Buildchain adds new checks behind the cadence wrappers.
 
 ## Package-Manager Adapters
 

package/docs/release-passport.md

@@ -122,6 +122,34 @@ Verify a release passport:
 buildchain verify release-passport .buildchain/release-passport/buildchain.release.json
 ```
 
+Verify a specific artifact by discovering its detached passport:
+
+```bash
+buildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe
+```
+
+Artifact verification is subject-centric. Buildchain identifies the subject,
+computes or obtains its digest, discovers a detached `buildchain.release.json`,
+verifies that release passport and its evidence, then proves the subject digest
+appears in the passport's artifacts, package set, publish evidence, or artifact
+evidence. The command returns `pass`, `fail`, or `unverifiable`; missing
+passports and digest mismatches fail closed.
+
+Discovery is ordered and auditable:
+
+1. explicit `--passport`;
+2. sidecar pointer;
+3. embedded/package pointer;
+4. local config or org index;
+5. GitHub Release default from artifact naming/repository/tag hints;
+6. custom locator;
+7. unverifiable with retry guidance.
+
+For Buildchain-managed GitHub Release lanes, release passport files are
+published as release assets by default when the upload backend is enabled, so a
+GitHub Release asset URL can discover the sibling `buildchain.release.json`
+without a consumer copying YAML resolver logic.
+
 Explain a release to an agent:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.5.7",
+  "version": "2.6.0-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -13,6 +13,7 @@
   "exports": {
     ".": "./packages/core/index.js",
     "./core": "./packages/core/index.js",
+    "./artifact-passport": "./packages/core/artifact-passport.js",
     "./diagnostics": "./packages/core/diagnostics.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
     "./logging": "./packages/core/logging.js",

package/packages/core/artifact-passport.js

@@ -0,0 +1,748 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import path from "node:path";
+import { readJsonFromLocation, sha256File, verifyReleasePassport } from "./release-passport.js";
+
+export const ARTIFACT_VERIFICATION_CONTRACT = "kungfu-buildchain-artifact-verification";
+export const ARTIFACT_PASSPORT_POINTER_CONTRACT = "kungfu-buildchain-artifact-passport-pointer";
+export const ARTIFACT_PASSPORT_LOCATOR_CONTRACT = "kungfu-buildchain-artifact-passport-locator";
+
+function optionalString(value) {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function isHttpLocation(value = "") {
+  return /^https?:\/\//i.test(String(value));
+}
+
+function isRemoteSubject(value = "") {
+  return isHttpLocation(value) || /^(npm|oci|s3|deployment|github-release):/i.test(String(value));
+}
+
+function issue(level, code, message, details = {}) {
+  return { level, code, message, details };
+}
+
+function sha256Buffer(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+export function sha512IntegrityBuffer(buffer) {
+  return `sha512-${crypto.createHash("sha512").update(buffer).digest("base64")}`;
+}
+
+export function sha512IntegrityFile(filePath) {
+  return sha512IntegrityBuffer(fs.readFileSync(filePath));
+}
+
+async function readBufferFromHttp(location) {
+  const client = location.startsWith("https:") ? https : http;
+  return new Promise((resolve, reject) => {
+    client
+      .get(location, (response) => {
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          reject(new Error(`HTTP ${response.statusCode} while reading ${location}`));
+          response.resume();
+          return;
+        }
+        const chunks = [];
+        response.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        response.on("end", () => resolve(Buffer.concat(chunks)));
+      })
+      .on("error", reject);
+  });
+}
+
+async function readTextMaybe(location) {
+  if (isHttpLocation(location)) {
+    return (await readBufferFromHttp(location)).toString("utf8");
+  }
+  return fs.readFileSync(location, "utf8");
+}
+
+function readJsonMaybe(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function digestDirectory(dir) {
+  const files = [];
+  const visit = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.name === ".git") {
+        continue;
+      }
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        visit(fullPath);
+      } else if (entry.isFile()) {
+        const relativePath = path.relative(dir, fullPath).split(path.sep).join("/");
+        files.push({
+          path: relativePath,
+          size: fs.statSync(fullPath).size,
+          sha256: sha256File(fullPath),
+        });
+      }
+    }
+  };
+  visit(dir);
+  files.sort((left, right) => left.path.localeCompare(right.path));
+  const manifest = files.map((file) => `${file.path}\0${file.size}\0${file.sha256}`).join("\n");
+  return {
+    sha256: sha256Buffer(Buffer.from(manifest, "utf8")),
+    fileCount: files.length,
+  };
+}
+
+function inferKindFromName(name = "") {
+  const lower = name.toLowerCase();
+  if (lower.endsWith(".exe") || lower.endsWith(".msi") || lower.endsWith(".dmg") || lower.endsWith(".pkg")) {
+    return "native-installer";
+  }
+  if (lower.endsWith(".tgz")) {
+    return "npm-package";
+  }
+  if (lower.endsWith(".zip") || lower.endsWith(".tar.gz") || lower.endsWith(".tar.xz") || lower.endsWith(".tar")) {
+    return "archive";
+  }
+  return "artifact";
+}
+
+function parseNpmSubject(subject) {
+  const spec = subject.replace(/^npm:/, "");
+  const atIndex = spec.startsWith("@") ? spec.indexOf("@", 1) : spec.lastIndexOf("@");
+  if (atIndex <= 0) {
+    return { name: spec, version: "" };
+  }
+  return { name: spec.slice(0, atIndex), version: spec.slice(atIndex + 1) };
+}
+
+function parseGitHubReleaseSubject(subject) {
+  const value = subject.replace(/^github-release:/, "");
+  const match = value.match(/^([^/]+\/[^@/]+)@([^/]+)\/(.+)$/);
+  if (!match) {
+    return {};
+  }
+  return { repository: match[1], tag: match[2], name: match[3] };
+}
+
+function parseGitHubReleaseUrl(location) {
+  try {
+    const parsed = new URL(location);
+    const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+)\/releases\/download\/([^/]+)\/(.+)$/);
+    if (!match) {
+      return {};
+    }
+    return {
+      repository: `${match[1]}/${match[2]}`,
+      tag: decodeURIComponent(match[3]),
+      name: decodeURIComponent(match[4]),
+    };
+  } catch {
+    return {};
+  }
+}
+
+function resolveLocation(baseLocation, relativeLocation) {
+  const relative = optionalString(relativeLocation).trim();
+  if (!relative) {
+    return "";
+  }
+  if (isHttpLocation(relative) || isRemoteSubject(relative)) {
+    return relative;
+  }
+  if (isHttpLocation(baseLocation)) {
+    return new URL(relative, baseLocation).toString();
+  }
+  return path.resolve(path.dirname(baseLocation), relative);
+}
+
+async function readOptionalJson(location) {
+  if (!location) {
+    return {};
+  }
+  try {
+    return await readJsonFromLocation(location);
+  } catch {
+    return {};
+  }
+}
+
+function relativeTo(baseDir, maybeRelative) {
+  if (!maybeRelative) {
+    return "";
+  }
+  if (isHttpLocation(maybeRelative) || isRemoteSubject(maybeRelative) || path.isAbsolute(maybeRelative)) {
+    return maybeRelative;
+  }
+  return path.resolve(baseDir, maybeRelative);
+}
+
+async function readPassportPointer(pointerLocation) {
+  const pointer = JSON.parse(await readTextMaybe(pointerLocation));
+  const passport = pointer.passport || pointer.passportLocation || pointer.releasePassport || pointer.url || "";
+  if (!passport) {
+    throw new Error(`passport pointer ${pointerLocation} does not include passport`);
+  }
+  return {
+    pointer,
+    passportLocation: resolveLocation(pointerLocation, passport),
+  };
+}
+
+function localConfigCandidates({ cwd, subject }) {
+  const starts = [cwd];
+  if (subject.localPath) {
+    starts.push(subject.kind === "directory" || subject.kind === "npm-package" ? subject.localPath : path.dirname(subject.localPath));
+  }
+  const seen = new Set();
+  const result = [];
+  for (const start of starts) {
+    let current = path.resolve(start || cwd);
+    while (!seen.has(current)) {
+      seen.add(current);
+      for (const name of [
+        ".buildchain/artifact-passport-locators.json",
+        "buildchain.artifact-passport.json",
+      ]) {
+        result.push(path.join(current, name));
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  return result;
+}
+
+function locatorMatchesSubject(locator, subject) {
+  const match = locator.match || locator.subject || {};
+  const digest = optionalString(match.digest || match.sha256 || match.integrity);
+  if (digest && !subjectDigestMatches(subject, digest)) {
+    return false;
+  }
+  for (const [left, right] of [
+    [match.name, subject.name],
+    [match.kind, subject.kind],
+    [match.version || match.ref, subject.version],
+    [match.repository, subject.githubRelease?.repository],
+    [match.tag, subject.githubRelease?.tag],
+  ]) {
+    if (left && right && String(left) !== String(right)) {
+      return false;
+    }
+    if (left && !right) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function readLocatorConfig(location, baseDir) {
+  const resolved = relativeTo(baseDir, location);
+  const value = await readJsonFromLocation(resolved);
+  const locators = Array.isArray(value) ? value : value.locators || value.passports || [];
+  return { location: resolved, locators };
+}
+
+async function findPassportInLocator(location, subject, baseDir) {
+  const config = await readLocatorConfig(location, baseDir);
+  for (const locator of config.locators) {
+    if (!locatorMatchesSubject(locator, subject)) {
+      continue;
+    }
+    const passportLocation = locator.passport || locator.passportLocation || locator.releasePassport || locator.url || "";
+    if (passportLocation) {
+      return {
+        passportLocation: resolveLocation(config.location, passportLocation),
+        locator: config.location,
+        entry: locator,
+      };
+    }
+  }
+  return undefined;
+}
+
+function sidecarPointerCandidates(subject) {
+  if (!subject.localPath) {
+    return [];
+  }
+  const candidates = [];
+  if (subject.kind === "directory" || subject.kind === "npm-package") {
+    candidates.push(path.join(subject.localPath, ".buildchain-passport.json"));
+    candidates.push(path.join(subject.localPath, ".buildchain", "artifact-passport.json"));
+  } else {
+    candidates.push(`${subject.localPath}.buildchain-passport.json`);
+    candidates.push(`${subject.localPath}.passport.json`);
+    candidates.push(path.join(path.dirname(subject.localPath), ".buildchain-passport.json"));
+  }
+  return candidates;
+}
+
+function embeddedPointerCandidates(subject) {
+  if (!subject.packageJsonPath || !fs.existsSync(subject.packageJsonPath)) {
+    return [];
+  }
+  const packageJson = readJsonMaybe(subject.packageJsonPath);
+  const passport =
+    packageJson.buildchain?.releasePassport ||
+    packageJson.buildchain?.passport ||
+    packageJson.releasePassport ||
+    "";
+  return passport
+    ? [{ passport, packageJsonPath: subject.packageJsonPath }]
+    : [];
+}
+
+function githubReleasePassportLocation(subject, options) {
+  const repository = options.repository || subject.githubRelease?.repository || "";
+  const tag = options.tag || subject.githubRelease?.tag || "";
+  if (!repository || !tag) {
+    return "";
+  }
+  const baseUrl = (options.githubReleaseBaseUrl || "https://github.com").replace(/\/$/, "");
+  return `${baseUrl}/${repository}/releases/download/${encodeURIComponent(tag)}/buildchain.release.json`;
+}
+
+export async function resolveArtifactSubject(subject, {
+  cwd = process.cwd(),
+  subjectDigest = "",
+  subjectKind = "",
+} = {}) {
+  const input = optionalString(subject).trim();
+  if (!input) {
+    throw new Error("artifact subject must be a non-empty string");
+  }
+  if (/^npm:/i.test(input)) {
+    const parsed = parseNpmSubject(input);
+    return {
+      input,
+      kind: subjectKind || "npm-package",
+      name: parsed.name,
+      version: parsed.version,
+      digest: subjectDigest,
+      localPath: "",
+    };
+  }
+  if (/^github-release:/i.test(input)) {
+    const parsed = parseGitHubReleaseSubject(input);
+    return {
+      input,
+      kind: subjectKind || inferKindFromName(parsed.name || input),
+      name: parsed.name || input,
+      version: "",
+      digest: subjectDigest,
+      localPath: "",
+      githubRelease: parsed,
+    };
+  }
+  if (/^(oci|s3|deployment):/i.test(input)) {
+    return {
+      input,
+      kind: subjectKind || input.split(":", 1)[0],
+      name: input,
+      version: "",
+      digest: subjectDigest,
+      localPath: "",
+    };
+  }
+  if (isHttpLocation(input)) {
+    const buffer = await readBufferFromHttp(input);
+    const githubRelease = parseGitHubReleaseUrl(input);
+    return {
+      input,
+      kind: subjectKind || inferKindFromName(githubRelease.name || path.basename(new URL(input).pathname)),
+      name: githubRelease.name || path.basename(new URL(input).pathname),
+      version: "",
+      digest: subjectDigest || `sha256:${sha256Buffer(buffer)}`,
+      sha256: sha256Buffer(buffer),
+      integrity: sha512IntegrityBuffer(buffer),
+      size: buffer.length,
+      localPath: "",
+      githubRelease,
+    };
+  }
+  const localPath = path.resolve(cwd, input);
+  if (!fs.existsSync(localPath)) {
+    return {
+      input,
+      kind: subjectKind || inferKindFromName(path.basename(input)),
+      name: path.basename(input),
+      version: "",
+      digest: subjectDigest,
+      localPath,
+      missing: true,
+    };
+  }
+  const stat = fs.statSync(localPath);
+  if (stat.isDirectory()) {
+    const packageJsonPath = path.join(localPath, "package.json");
+    const packageJson = fs.existsSync(packageJsonPath) ? readJsonMaybe(packageJsonPath) : {};
+    const directoryDigest = digestDirectory(localPath);
+    return {
+      input,
+      kind: subjectKind || (packageJson.name ? "npm-package" : "directory"),
+      name: packageJson.name || path.basename(localPath),
+      version: packageJson.version || "",
+      digest: subjectDigest || `sha256:${directoryDigest.sha256}`,
+      sha256: directoryDigest.sha256,
+      integrity: "",
+      size: stat.size,
+      fileCount: directoryDigest.fileCount,
+      localPath,
+      packageJsonPath: fs.existsSync(packageJsonPath) ? packageJsonPath : "",
+    };
+  }
+  const buffer = fs.readFileSync(localPath);
+  const sha256 = sha256Buffer(buffer);
+  return {
+    input,
+    kind: subjectKind || inferKindFromName(path.basename(localPath)),
+    name: path.basename(localPath),
+    version: "",
+    digest: subjectDigest || `sha256:${sha256}`,
+    sha256,
+    integrity: sha512IntegrityBuffer(buffer),
+    size: stat.size,
+    localPath,
+  };
+}
+
+export async function discoverArtifactPassport({
+  subject,
+  cwd = process.cwd(),
+  passportLocation = "",
+  locatorConfig = "",
+  repository = "",
+  tag = "",
+  githubReleaseBaseUrl = "",
+} = {}) {
+  const attempts = [];
+  const found = (method, location, details = {}) => ({
+    status: "found",
+    method,
+    passportLocation: location,
+    attempts: attempts.concat({ method, status: "found", location, details }),
+    details,
+  });
+  if (passportLocation) {
+    const resolved = relativeTo(cwd, passportLocation);
+    return found("explicit-passport", resolved);
+  }
+  for (const candidate of sidecarPointerCandidates(subject)) {
+    attempts.push({ method: "sidecar-pointer", location: candidate, status: fs.existsSync(candidate) ? "found" : "miss" });
+    if (fs.existsSync(candidate)) {
+      const pointer = await readPassportPointer(candidate);
+      return found("sidecar-pointer", pointer.passportLocation, { pointer: candidate });
+    }
+  }
+  for (const pointer of embeddedPointerCandidates(subject)) {
+    attempts.push({ method: "embedded-package-pointer", location: pointer.packageJsonPath, status: "found" });
+    return found("embedded-package-pointer", resolveLocation(pointer.packageJsonPath, pointer.passport), {
+      packageJson: pointer.packageJsonPath,
+    });
+  }
+  for (const candidate of localConfigCandidates({ cwd, subject })) {
+    attempts.push({ method: "local-config-index", location: candidate, status: fs.existsSync(candidate) ? "checked" : "miss" });
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+    const matched = await findPassportInLocator(candidate, subject, cwd);
+    if (matched) {
+      return found("local-config-index", matched.passportLocation, { locator: matched.locator });
+    }
+  }
+  const githubLocation = githubReleasePassportLocation(subject, { repository, tag, githubReleaseBaseUrl });
+  if (githubLocation) {
+    try {
+      await readJsonFromLocation(githubLocation);
+      attempts.push({ method: "github-release-default", location: githubLocation, status: "found" });
+      return found("github-release-default", githubLocation, { repository: repository || subject.githubRelease?.repository || "", tag: tag || subject.githubRelease?.tag || "" });
+    } catch (error) {
+      attempts.push({
+        method: "github-release-default",
+        location: githubLocation,
+        status: "miss",
+        error: error.message,
+      });
+    }
+  }
+  if (locatorConfig) {
+    const resolved = relativeTo(cwd, locatorConfig);
+    attempts.push({ method: "custom-locator", location: resolved, status: fs.existsSync(resolved) || isHttpLocation(resolved) ? "checked" : "miss" });
+    let matched;
+    try {
+      matched = await findPassportInLocator(resolved, subject, cwd);
+    } catch (error) {
+      attempts.push({ method: "custom-locator", location: resolved, status: "error", error: error.message });
+    }
+    if (matched) {
+      return found("custom-locator", matched.passportLocation, { locator: matched.locator });
+    }
+  }
+  return {
+    status: "unverifiable",
+    method: "unresolved",
+    passportLocation: "",
+    attempts: attempts.concat({
+      method: "unverifiable",
+      status: "unverifiable",
+      guidance: "Provide --passport, add a sidecar pointer, publish buildchain.release.json to the GitHub Release, or configure a locator.",
+    }),
+  };
+}
+
+function digestValues(value = {}) {
+  return [
+    value.digest,
+    value.sha256 ? `sha256:${value.sha256}` : "",
+    value.integrity,
+    value.shasum,
+  ].map(optionalString).filter(Boolean);
+}
+
+function normalizeDigest(value = "") {
+  return optionalString(value).trim();
+}
+
+function digestEquivalent(left = "", right = "") {
+  const a = normalizeDigest(left);
+  const b = normalizeDigest(right);
+  if (!a || !b) {
+    return false;
+  }
+  return a === b || a === `sha256:${b}` || `sha256:${a}` === b;
+}
+
+function subjectDigestMatches(subject, digest) {
+  return digestValues(subject).some((value) => digestEquivalent(value, digest));
+}
+
+function packageSetArtifacts(passport = {}) {
+  const packageSet = passport.packageSet || {};
+  return [
+    ...(packageSet.main?.name ? [{ role: "main", ...packageSet.main }] : []),
+    ...((packageSet.platforms || []).map((entry) => ({ role: "platform", ...entry }))),
+  ].map((entry) => ({
+    group: "node",
+    kind: "npm",
+    name: entry.name,
+    ref: entry.version,
+    digest: entry.digest,
+    role: entry.role,
+    platform: entry.platform || "",
+    source: "packageSet",
+  }));
+}
+
+function publishSummaryArtifacts(passport = {}) {
+  return (passport.publish?.packages || []).map((entry) => ({
+    group: "node",
+    kind: "npm",
+    name: entry.name,
+    ref: entry.publishedVersion || entry.version,
+    digest: entry.digest,
+    role: entry.role,
+    platform: entry.platform || "",
+    source: "publish.packages",
+  }));
+}
+
+function passportArtifacts({ passport = {}, artifactEvidence = {}, publishEvidence = {} } = {}) {
+  return [
+    ...(passport.artifacts || []).map((entry) => ({ ...entry, source: "passport.artifacts" })),
+    ...(artifactEvidence.artifacts || []).map((entry) => ({ ...entry, source: "artifact-evidence.artifacts" })),
+    ...(publishEvidence.artifacts || []).map((entry) => ({ ...entry, source: "publish-evidence.artifacts" })),
+    ...packageSetArtifacts(passport),
+    ...publishSummaryArtifacts(passport),
+  ];
+}
+
+function artifactMatchesSubject(artifact, subject) {
+  const artifactDigests = digestValues(artifact);
+  const digestMatch = artifactDigests.some((digest) => subjectDigestMatches(subject, digest));
+  const nameMatch = !artifact.name || !subject.name || artifact.name === subject.name;
+  const refMatch = !artifact.ref || !subject.version || artifact.ref === subject.version;
+  const packageIdentityMatch =
+    subject.kind === "npm-package" &&
+    artifact.name === subject.name &&
+    (!artifact.ref || !subject.version || artifact.ref === subject.version);
+  if (digestMatch && (nameMatch || packageIdentityMatch)) {
+    return { matched: true, reason: "digest" };
+  }
+  if (digestMatch) {
+    return { matched: true, reason: "digest-only" };
+  }
+  return { matched: false, reason: packageIdentityMatch ? "package-identity-without-digest" : "no-match" };
+}
+
+async function loadPassportBundle(passportLocation) {
+  const passport = await readJsonFromLocation(passportLocation);
+  const artifactEvidenceLocation = resolveLocation(passportLocation, passport.evidence?.artifactEvidence);
+  const publishEvidenceLocation = resolveLocation(passportLocation, passport.evidence?.publishEvidence);
+  const impactLocation = resolveLocation(passportLocation, passport.evidence?.impact);
+  const agentIndexLocation = resolveLocation(passportLocation, passport.evidence?.agentIndex);
+  const productMechanismLocation = resolveLocation(passportLocation, passport.product?.mechanism);
+  const [artifactEvidence, publishEvidence] = await Promise.all([
+    readOptionalJson(artifactEvidenceLocation),
+    readOptionalJson(publishEvidenceLocation),
+  ]);
+  return {
+    passport,
+    artifactEvidence,
+    publishEvidence,
+    locations: {
+      artifactEvidenceLocation,
+      publishEvidenceLocation,
+      impactLocation,
+      agentIndexLocation,
+      productMechanismLocation,
+    },
+  };
+}
+
+export async function verifyArtifactPassport({
+  subject,
+  cwd = process.cwd(),
+  passportLocation = "",
+  locatorConfig = "",
+  repository = "",
+  tag = "",
+  githubReleaseBaseUrl = "",
+  subjectDigest = "",
+  subjectKind = "",
+} = {}) {
+  const resolvedSubject = await resolveArtifactSubject(subject, { cwd, subjectDigest, subjectKind });
+  const issues = [];
+  if (resolvedSubject.missing) {
+    issues.push(issue("error", "subject.missing", "artifact subject does not exist locally", { subject: resolvedSubject.input }));
+    return {
+      schemaVersion: 1,
+      contract: ARTIFACT_VERIFICATION_CONTRACT,
+      outcome: "unverifiable",
+      ok: false,
+      trust: "unverifiable",
+      subject: resolvedSubject,
+      discovery: { status: "unverifiable", method: "subject-missing", attempts: [] },
+      issues,
+    };
+  }
+  const discovery = await discoverArtifactPassport({
+    subject: resolvedSubject,
+    cwd,
+    passportLocation,
+    locatorConfig,
+    repository,
+    tag,
+    githubReleaseBaseUrl,
+  });
+  if (!discovery.passportLocation) {
+    issues.push(issue("error", "passport.unavailable", "no release passport could be discovered for artifact subject"));
+    return {
+      schemaVersion: 1,
+      contract: ARTIFACT_VERIFICATION_CONTRACT,
+      outcome: "unverifiable",
+      ok: false,
+      trust: "unverifiable",
+      subject: resolvedSubject,
+      discovery,
+      issues,
+    };
+  }
+  let bundle;
+  let passportReport;
+  try {
+    bundle = await loadPassportBundle(discovery.passportLocation);
+    passportReport = await verifyReleasePassport({
+      passportLocation: discovery.passportLocation,
+      artifactEvidenceLocation: bundle.locations.artifactEvidenceLocation,
+      publishEvidenceLocation: bundle.locations.publishEvidenceLocation,
+      impactLocation: bundle.locations.impactLocation,
+      agentIndexLocation: bundle.locations.agentIndexLocation,
+      productMechanismLocation: bundle.locations.productMechanismLocation,
+    });
+  } catch (error) {
+    issues.push(issue("error", "passport.read", "release passport could not be read or parsed", {
+      passportLocation: discovery.passportLocation,
+      error: error.message,
+    }));
+    return {
+      schemaVersion: 1,
+      contract: ARTIFACT_VERIFICATION_CONTRACT,
+      outcome: "fail",
+      ok: false,
+      trust: "fail",
+      subject: resolvedSubject,
+      discovery,
+      issues,
+    };
+  }
+  if (!passportReport.ok) {
+    issues.push(issue("error", "passport.verification", "release passport verification failed"));
+  }
+  const candidates = passportArtifacts(bundle);
+  const match = candidates.map((artifact) => ({ artifact, result: artifactMatchesSubject(artifact, resolvedSubject) }))
+    .find((entry) => entry.result.matched);
+  if (!match) {
+    issues.push(issue("error", "subject.digest.missing", "artifact subject digest was not found in the release passport evidence", {
+      digest: resolvedSubject.digest || resolvedSubject.integrity || "",
+      name: resolvedSubject.name,
+      kind: resolvedSubject.kind,
+    }));
+  }
+  const ok = passportReport.ok && Boolean(match);
+  const outcome = ok ? "pass" : "fail";
+  return {
+    schemaVersion: 1,
+    contract: ARTIFACT_VERIFICATION_CONTRACT,
+    outcome,
+    ok,
+    trust: outcome,
+    subject: resolvedSubject,
+    discovery,
+    passport: {
+      location: discovery.passportLocation,
+      product: bundle.passport.product,
+      release: bundle.passport.release,
+      verification: {
+        ok: passportReport.ok,
+        trust: passportReport.trust,
+        completeness: passportReport.completeness,
+        issues: passportReport.issues,
+      },
+    },
+    match: match
+      ? {
+          source: match.artifact.source,
+          reason: match.result.reason,
+          artifact: match.artifact,
+        }
+      : undefined,
+    issues,
+  };
+}
+
+export async function explainArtifactPassport(options = {}) {
+  const report = await verifyArtifactPassport(options);
+  const nextAction = report.ok
+    ? "use-artifact-after-policy-review"
+    : report.outcome === "unverifiable"
+      ? "locate-passport-or-add-artifact-passport-pointer"
+      : "block-artifact-and-report-verification-failure";
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-artifact-explanation",
+    audience: options.forAudience || "human",
+    subject: report.subject,
+    outcome: report.outcome,
+    trust: report.trust,
+    passport: report.passport,
+    discovery: report.discovery,
+    match: report.match,
+    nextAction,
+    issues: report.issues,
+  };
+}

package/packages/core/index.js

@@ -92,6 +92,18 @@ export {
   validateReleaseCandidatePassport,
 } from "./release-candidate.js";
 
+export {
+  ARTIFACT_PASSPORT_LOCATOR_CONTRACT,
+  ARTIFACT_PASSPORT_POINTER_CONTRACT,
+  ARTIFACT_VERIFICATION_CONTRACT,
+  discoverArtifactPassport,
+  explainArtifactPassport,
+  resolveArtifactSubject,
+  sha512IntegrityBuffer,
+  sha512IntegrityFile,
+  verifyArtifactPassport,
+} from "./artifact-passport.js";
+
 export {
   AGENT_INDEX_CONTRACT,
   ARTIFACT_EVIDENCE_CONTRACT,

package/packages/core/release-line-dry-run.js

@@ -173,7 +173,7 @@ function explainReleaseLineDryRun({
       "target branch protection must be readable",
       "branch protection must enforce administrators",
       "required pull request review must be enabled",
-      "strict required status check must include the Verify check",
+      "strict required status check must include the check job",
       `source PR must be a merged same-repository PR from ${rule.sourceRef} to ${targetRef}`,
     ],
     publishTransaction: {

package/scripts/buildchain-patrol.mjs

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { runDevPrAutoMerge } from "./dev-pr-auto-merge.mjs";
 
-const DEFAULT_TARGET_BRANCH = "dev/v2/v2.5";
+const DEFAULT_TARGET_BRANCH = "";
 const DEFAULT_OUTPUT_PATH = ".buildchain/patrol/result.json";
 const VALID_CADENCES = new Set(["daily", "weekly", "monthly"]);
 const VALID_MODES = new Set(["cadence-default", "inspect", "merge-ready-dev-prs", "cleanup-safe"]);
@@ -47,9 +47,9 @@ function normalizeRepository(value) {
 }
 
 function normalizeTargetBranch(value) {
-  const branch = String(value || DEFAULT_TARGET_BRANCH).replace(/^refs\/heads\//, "");
+  const branch = String(value || process.env.GITHUB_REF_NAME || DEFAULT_TARGET_BRANCH).replace(/^refs\/heads\//, "");
   if (!/^dev\/v\d+\/v\d+\.\d+$/.test(branch)) {
-    throw new Error(`target-branch must be a semver dev branch such as dev/v2/v2.5, got: ${branch}`);
+    throw new Error(`target-branch must be a semver dev branch such as dev/v2/v2.N, got: ${branch || "<empty>"}`);
   }
   return branch;
 }

package/scripts/check-inventory.mjs

@@ -271,6 +271,7 @@ for (const requiredSnippet of [
   "bin/buildchain.mjs log summary",
   "collect github-release",
   "verify release-passport",
+  "verify artifact",
   "scripts/create-release-bundle.mjs",
   "buildchain-release-bundle",
   "gh release upload",

package/scripts/dev-pr-auto-merge.mjs

@@ -4,7 +4,7 @@ import path from "node:path";
 
 const DEFAULT_BLOCK_LABELS = ["blocked", "do-not-merge", "work-in-progress"];
 const DEFAULT_ALLOWED_HEAD_PREFIXES = ["feature/", "fix/", "chore/", "docs/", "ci/", "refactor/"];
-const DEFAULT_REQUIRED_CHECKS = ["Verify"];
+const DEFAULT_REQUIRED_CHECKS = ["check"];
 const SUCCESS_STATES = new Set(["success"]);
 const SUCCESS_CONCLUSIONS = new Set(["success", "neutral", "skipped"]);