@kungfu-tech/buildchain 2.1.1-alpha.0 → 2.2.0-alpha.1

package/README.md

@@ -51,6 +51,11 @@ future minor refs can each receive many patch releases such as `v2.0.1234`.
 `v2` points at the selected stable major line, while `v2.0` points at the
 latest production patch for that minor line.
 
+Buildchain opens a new minor line when it adds a new compatible welded surface:
+a reusable workflow contract, public CLI command family, published package
+subpath, evidence protocol, or installable binary distribution shape. The local
+decision log lives in [`docs/versioning.md`](docs/versioning.md).
+
 `publish-gate/major` replaces the old ABV `main` channel. It is deliberately
 not named `main` because it is not the active development trunk. Maintainers use
 the same PR flow as other channel promotions: merging
@@ -111,6 +116,9 @@ Buildchain v2 ships these active surfaces:
 - `actions/run-lifecycle` for callers that need the same lifecycle/manifest
   contract inside their own workflows;
 - governance-closed self-promotion through `Buildchain Ref Promotion`.
+- `v2.2` release passport and binary distribution contracts for GitHub Release
+  assets, artifact evidence, impact ledgers, agent indexes, and standalone CLI
+  archives.
 
 Stable consumers should reference actions as:
 

package/bin/buildchain.mjs

@@ -13,13 +13,20 @@ import {
   createBuildchainLogger,
   defaultBuildchainLogPath,
   summarizeBuildchainLogEvents,
+  verifyBuildchainLogEvents,
 } from "../packages/core/logging.js";
 import {
   explainReleaseLineDryRun,
   formatReleaseLineDryRun,
 } from "../packages/core/release-line-dry-run.js";
+import {
+  collectGitHubReleasePassport,
+  explainReleasePassport,
+  verifyReleasePassport,
+} from "../packages/core/release-passport.js";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const embeddedPackageVersion = process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION || "";
 
 function usage() {
   return `Usage:
@@ -42,6 +49,16 @@ function usage() {
                                       [--tags <comma-list>] [--json]
   buildchain release <inspect|recover|finalize|abort> ...
   buildchain transaction inspect ...
+  buildchain collect github-release --tag <tag> [--repository <owner/repo>]
+                                    [--assets-dir <dir>] [--assets-json <json-or-path>]
+                                    [--release-json <json-or-path>] [--output-dir <dir>] [--json]
+  buildchain verify release-passport <file-or-url> [--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 inspect release --passport <file-or-url> [--json]
   buildchain doctor [--cwd <dir>] [--json]
   buildchain log <info|warn|error> --event <name> [--phase <phase>]
                  [--component <name>] [--source <name>] [--attribute key=value]...
@@ -62,6 +79,9 @@ Examples:
   buildchain npm dry-run --json
   buildchain release --dry-run --target-ref alpha/v2/v2.0
   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 observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build
 `;
 }
 
@@ -176,6 +196,9 @@ function printJson(value) {
 }
 
 function packageVersion() {
+  if (embeddedPackageVersion) {
+    return embeddedPackageVersion;
+  }
   const packageJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
   return packageJson.version;
 }
@@ -396,6 +419,129 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "collect") {
+    const [subcommand = "", ...collectArgs] = args;
+    if (subcommand !== "github-release") {
+      throw new Error("usage: buildchain collect github-release --tag <tag>");
+    }
+    const workflow = {
+      name: process.env.GITHUB_WORKFLOW || "",
+      runId: process.env.GITHUB_RUN_ID || "",
+      runAttempt: process.env.GITHUB_RUN_ATTEMPT || "",
+      url: process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID
+        ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+        : "",
+      runnerKind: process.env.BUILDCHAIN_RUNNER_KIND || "github-hosted",
+      runnerOs: process.env.RUNNER_OS || process.platform,
+      runnerArch: process.env.RUNNER_ARCH || process.arch,
+      runnerImage: process.env.ImageOS || "",
+    };
+    const result = collectGitHubReleasePassport({
+      cwd: readFlag(collectArgs, "cwd", process.cwd()),
+      tag: readFlag(collectArgs, "tag", ""),
+      repository: readFlag(collectArgs, "repository", process.env.GITHUB_REPOSITORY || ""),
+      sourceSha: readFlag(collectArgs, "source-sha", process.env.GITHUB_SHA || ""),
+      line: readFlag(collectArgs, "line", ""),
+      outputDir: readFlag(collectArgs, "output-dir", ".buildchain/release-passport"),
+      assetsDir: readFlag(collectArgs, "assets-dir", ""),
+      assetsJson: readFlag(collectArgs, "assets-json", ""),
+      releaseJson: readFlag(collectArgs, "release-json", ""),
+      packageName: readFlag(collectArgs, "package-name", "@kungfu-tech/buildchain"),
+      packageVersion: readFlag(collectArgs, "package-version", packageVersion()),
+      workflow,
+    });
+    if (readBooleanFlag(collectArgs, "json")) {
+      printJson(result);
+    } else {
+      process.stdout.write(`release passport collected: ${path.relative(process.cwd(), result.outputDir)}\n`);
+      process.stdout.write(`artifacts: ${result.artifactEvidence.artifacts.length}\n`);
+    }
+    return;
+  }
+
+  if (command === "verify") {
+    const [subcommand = "", location = "", ...verifyArgs] = args;
+    if (subcommand === "observability-log") {
+      if (!location) {
+        throw new Error("usage: buildchain verify observability-log <jsonl>");
+      }
+      const report = verifyBuildchainLogEvents({
+        path: location,
+        minEvents: Number(readFlag(verifyArgs, "min-events", "1")),
+        allowErrors: readBooleanFlag(verifyArgs, "allow-errors"),
+        requirePhases: readRepeatedFlag(verifyArgs, "require-phase"),
+        requireComponents: readRepeatedFlag(verifyArgs, "require-component"),
+        requireEvents: readRepeatedFlag(verifyArgs, "require-event"),
+      });
+      if (readBooleanFlag(verifyArgs, "json")) {
+        printJson(report);
+      } else {
+        process.stdout.write(`observability log: ${report.ok ? "ok" : "failed"}\n`);
+        process.stdout.write(`events: ${report.summary.eventCount}\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 !== "release-passport" || !location) {
+      throw new Error("usage: buildchain verify release-passport <file-or-url>");
+    }
+    const report = await verifyReleasePassport({ passportLocation: location });
+    if (readBooleanFlag(verifyArgs, "json")) {
+      printJson(report);
+    } else {
+      process.stdout.write(`release passport: ${report.ok ? "ok" : "failed"}\n`);
+      process.stdout.write(`artifacts: ${report.completeness.artifactCount}\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 (command === "explain") {
+    const [subcommand = "", ...explainArgs] = args;
+    if (subcommand !== "release") {
+      throw new Error("usage: buildchain explain release --passport <file-or-url>");
+    }
+    const passport = readFlag(explainArgs, "passport", "");
+    if (!passport) {
+      throw new Error("buildchain explain release requires --passport <file-or-url>");
+    }
+    const explanation = await explainReleasePassport({
+      passportLocation: passport,
+      forAudience: readFlag(explainArgs, "for", "human"),
+    });
+    if (readBooleanFlag(explainArgs, "json")) {
+      printJson(explanation);
+    } else {
+      process.stdout.write(`release: ${explanation.release?.tag || "unknown"}\n`);
+      process.stdout.write(`trust: ${explanation.trust}\n`);
+      process.stdout.write(`next action: ${explanation.nextAction}\n`);
+    }
+    return;
+  }
+
+  if (command === "inspect") {
+    const [subcommand = "", ...inspectArgs] = args;
+    if (subcommand !== "release") {
+      throw new Error("usage: buildchain inspect release --passport <file-or-url>");
+    }
+    const passport = readFlag(inspectArgs, "passport", "");
+    if (!passport) {
+      throw new Error("buildchain inspect release requires --passport <file-or-url>");
+    }
+    const explanation = await explainReleasePassport({
+      passportLocation: passport,
+      forAudience: readFlag(inspectArgs, "for", "human"),
+    });
+    printJson(explanation);
+    return;
+  }
+
   if (command === "web-surface") {
     runScript("web-surface.mjs", args);
     return;

package/docs/MAP.md

@@ -21,11 +21,13 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How do I install or run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |
 | How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |
+| How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |
 | What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |
 | What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |
 | What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |
 | How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
+| How do I publish or verify binary release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
 | How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |
 | How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |
 | How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md) | use | stable |
@@ -40,6 +42,8 @@ running artifact), *use* (consume / extend) - and a **status**:
 - **v2 / v2.0 / v2.0-alpha / exact tags / floating tags** ->
   [`release-governance.md`](release-governance.md) and
   [`release-flow.md`](release-flow.md).
+- **v2.1 vs v2.2 / when to open a new minor line** ->
+  [`versioning.md`](versioning.md).
 - **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)
   and [`release-flow.md`](release-flow.md).
 - **pnpm / npm / yarn / package-manager adapters** ->
@@ -51,6 +55,8 @@ running artifact), *use* (consume / extend) - and a **status**:
   [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).
 - **Trusted Publishing / npm / publish evidence / recovery** ->
   [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).
+- **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->
+  [`release-passport.md`](release-passport.md) and [`cli.md`](cli.md).
 - **sites / web previews / staging / production gates** ->
   [`web-surface-deployments.md`](web-surface-deployments.md).
 

package/docs/cli.md

@@ -75,12 +75,16 @@ buildchain mark --event configure.ready --phase configure --attribute target=rel
 buildchain span --event native.build --phase build -- cmake --build build
 buildchain log warn --event cache.miss --component conan --attribute token=hidden
 buildchain log summary --json
+buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build
 ```
 
 During `buildchain lifecycle run`, child processes receive
 `BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. A shell, Python, CMake, Conan,
 or JavaScript helper can call `buildchain mark` or `buildchain span` mid-build
 and have those events grouped into the same lifecycle summary.
+`buildchain verify observability-log` is a release gate: it fails when the log
+is missing, has too few events, contains error events, or does not include
+required phases, components, or event names.
 
 The event protocol is JSONL and is also available from the SDK:
 
@@ -111,6 +115,40 @@ and `buildchain build-contract` route to the same scripts used by Buildchain's
 GitHub Actions workflows. This keeps local inspection and CI behavior on the
 same implementation path.
 
+`buildchain collect github-release` creates a release passport bundle from
+GitHub Release assets or a local asset directory:
+
+```bash
+buildchain collect github-release \
+  --tag v2.2.0 \
+  --repository kungfu-systems/buildchain \
+  --assets-dir dist \
+  --output-dir .buildchain/release-passport
+```
+
+The bundle includes `buildchain.release.json`, `artifact-evidence.json`,
+`impact.json`, `agent-index.json`, `product-mechanism.json`, `check-report.json`,
+and `llms.txt`. Production binary distribution defaults to GitHub-hosted
+runners so other projects can reproduce the release lane; self-hosted runners
+remain compatibility fixtures and are recorded as runner facts when used.
+
+Buildchain dogfoods its observability toolkit in this lane. The standalone
+builder writes API-generated events, while the workflow uses `buildchain mark`,
+`buildchain span`, `buildchain verify observability-log`, and `buildchain log
+summary`; the event logs and summaries are published as release passport assets.
+
+Verify and explain release passports:
+
+```bash
+buildchain verify release-passport .buildchain/release-passport/buildchain.release.json
+buildchain explain release --passport .buildchain/release-passport/buildchain.release.json --for agent --json
+buildchain inspect release --passport .buildchain/release-passport/buildchain.release.json
+```
+
+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.
+
 `buildchain release --dry-run` explains the release-line state machine before a
 maintainer opens or merges a channel PR:
 

package/docs/release-passport.md

@@ -0,0 +1,99 @@
+# Release Passport and Binary Distribution
+
+Buildchain v2.2 adds a GitHub-native release passport protocol for binary and
+multi-artifact products. The protocol is meant for projects that want release
+evidence without migrating their whole CI/CD system to Buildchain.
+
+## Contract
+
+The release passport surface is a welded contract. Additive fields are allowed;
+breaking semantic changes require a new major line.
+
+P0 protocol artifacts:
+
+- `product-mechanism.json`
+- `buildchain.release.json`
+- `artifact-evidence.json`
+- `impact.json`
+- `agent-index.json`
+- `llms.txt`
+
+`buildchain.release.json` is the first file an agent should read. It points to
+artifact evidence, impact, recovery, product mechanism, and agent index facts.
+Buildchain's own binary lane also publishes observability artifacts generated by
+the Buildchain logging API and CLI:
+
+- `buildchain-log-events-<platform>.jsonl`
+- `buildchain-log-summary-<platform>.json`
+- `buildchain-log-events-passport.jsonl`
+- `buildchain-log-summary-passport.json`
+
+## Runner Policy
+
+Production binary distribution should use GitHub-hosted runners by default:
+
+- `ubuntu-24.04`
+- `macos-latest`
+- `windows-2022`
+
+This keeps the public release path easy for other projects to reproduce.
+Self-hosted runners remain compatibility fixtures: they prove that the protocol
+does not depend on GitHub-hosted images, but they are not the default public
+distribution lane.
+
+The protocol records runner facts in `artifact-evidence.json`; it does not
+require a specific runner class.
+
+## CLI
+
+Generate a local release passport bundle from release assets:
+
+```bash
+buildchain collect github-release \
+  --tag v2.2.0 \
+  --repository kungfu-systems/buildchain \
+  --assets-dir dist \
+  --output-dir .buildchain/release-passport
+```
+
+Verify a release passport:
+
+```bash
+buildchain verify release-passport .buildchain/release-passport/buildchain.release.json
+```
+
+Explain a release to an agent:
+
+```bash
+buildchain explain release \
+  --passport .buildchain/release-passport/buildchain.release.json \
+  --for agent \
+  --json
+```
+
+The verifier fails closed when a passport omits artifacts, omits evidence, has
+digest mismatches, or misses required protocol files.
+
+## Binary Distribution
+
+Initial binary distribution stays lightweight:
+
+- GitHub Release assets.
+- `checksums.txt`.
+- release passport artifacts.
+- install scripts and Homebrew tap fixtures after the passport is reliable.
+
+Heavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or
+asdf are out of the P0/P1 scope until there is real external demand.
+
+Standalone binaries are a distribution shape, not a second implementation. The
+source of truth remains the Node/ESM CLI and core library.
+
+The standalone binary builder imports `@kungfu-tech/buildchain/logging` directly
+and records setup, SEA blob generation, injection, signing, archiving, manifest,
+and evidence phases. The GitHub workflow wraps the same build and passport
+steps with `buildchain mark`, `buildchain span`,
+`buildchain verify observability-log`, and `buildchain log summary`. Logging is
+a hard release gate: missing events, error events, or missing required phases
+fail the job before assets are uploaded. The verified logs are release assets
+and are covered by the release passport digest checks.

package/docs/versioning.md

@@ -0,0 +1,57 @@
+# Buildchain Versioning
+
+Buildchain uses semantic version lines to describe public contracts, not only
+code size. A release can be small in diff size and still open a new minor line
+when it adds a durable surface that consumers, workflows, or agents can depend
+on.
+
+## Lines
+
+| Line | Meaning |
+| --- | --- |
+| Patch | Compatible fix, hardening, documentation correction, or implementation repair inside an existing surface. |
+| Minor | New compatible welded surface: reusable workflow output, CLI command family, config protocol, published subpath, evidence file, runner contract, or agent-readable artifact. |
+| Major | Breaking semantic change, removed stable surface, changed branch/tag governance, or incompatible protocol rewrite. |
+
+Kungfu minor lines are long-lived trains. `v2.0`, `v2.1`, and `v2.2` can each
+receive many patch releases. The major ref, such as `v2`, points at the
+selected stable major entrypoint; the minor ref, such as `v2.2`, points at the
+latest stable production patch for that minor line.
+
+## Welded Surfaces
+
+These surfaces require at least a minor bump when first introduced:
+
+- reusable workflow inputs, outputs, and artifact contracts;
+- public CLI command families and their machine-readable JSON shapes;
+- public npm exports such as `@kungfu-tech/buildchain/logging`;
+- config protocols such as `buildchain.toml`;
+- release governance state machines and protected ref semantics;
+- release evidence contracts such as passport, artifact evidence, impact
+  ledger, and agent index files;
+- binary distribution shapes that users can install or automate against.
+
+Additive fields inside an existing welded surface can be patch releases when
+old consumers continue to work and validation remains stricter, not looser.
+Removing fields, changing meanings, weakening trust gates, or changing the
+expected ref flow requires a major bump.
+
+## Decision Log
+
+| Date | Decision | Line | Reason |
+| --- | --- | --- | --- |
+| 2026-07-02 | Buildchain toolkit observability is a minor surface. | `v2.1` | It adds the public logging SDK, CLI observability commands, and package subpaths that consumers can import. |
+| 2026-07-02 | Release passport and binary distribution are a minor surface. | `v2.2` | They add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets. |
+
+## Runner Policy
+
+The `v2.2` binary distribution lane uses GitHub-hosted runners for production
+assets because that is the easiest release path for external users to reproduce:
+
+- `ubuntu-24.04`
+- `macos-latest`
+- `windows-2022`
+
+Self-hosted runners remain compatibility fixtures. They prove Buildchain's
+protocol does not depend on GitHub-hosted images, but they do not define the
+public binary distribution path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.1.1-alpha.0",
+  "version": "2.2.0-alpha.1",
   "private": false,
   "description": "Kungfu Buildchain reusable workflows, release governance, and CLI tooling.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -14,6 +14,7 @@
     ".": "./packages/core/index.js",
     "./core": "./packages/core/index.js",
     "./logging": "./packages/core/logging.js",
+    "./release-passport": "./packages/core/release-passport.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -31,9 +32,11 @@
     "docs/migration-inventory.md",
     "docs/ownership.md",
     "docs/publish-transaction.md",
+    "docs/release-passport.md",
     "docs/release-flow.md",
     "docs/release-governance.md",
     "docs/reusable-build-surface.md",
+    "docs/versioning.md",
     "docs/web-surface-deployments.md",
     "actions/*/README.md",
     "fixtures/*/README.md"

package/packages/core/index.js

@@ -50,4 +50,25 @@ export {
   readBuildchainLogEvents,
   redactBuildchainLogAttributes,
   summarizeBuildchainLogEvents,
+  verifyBuildchainLogEvents,
 } from "./logging.js";
+
+export {
+  AGENT_INDEX_CONTRACT,
+  ARTIFACT_EVIDENCE_CONTRACT,
+  IMPACT_LEDGER_CONTRACT,
+  PRODUCT_MECHANISM_CONTRACT,
+  RELEASE_CHECK_REPORT_CONTRACT,
+  RELEASE_PASSPORT_CONTRACT,
+  collectGitHubReleasePassport,
+  createArtifactEvidence,
+  createReleaseCheckReport,
+  createReleasePassport,
+  explainReleasePassport,
+  makeReleasePassportFixtureAssets,
+  readJsonFromLocation,
+  sha256File,
+  sha256Text,
+  validateKnownReleasePassportContracts,
+  verifyReleasePassport,
+} from "./release-passport.js";

package/packages/core/logging.js

@@ -111,6 +111,90 @@ export function summarizeBuildchainLogEvents(input = {}) {
   };
 }
 
+function listOption(value) {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => listOption(entry));
+  }
+  if (typeof value !== "string") {
+    return [];
+  }
+  return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
+
+function issue(level, code, message) {
+  return { level, code, message };
+}
+
+export function verifyBuildchainLogEvents({
+  path: filePath = "",
+  events: inputEvents = undefined,
+  minEvents = 1,
+  allowErrors = false,
+  requirePhases = [],
+  requireComponents = [],
+  requireEvents = [],
+} = {}) {
+  const issues = [];
+  let events = [];
+  try {
+    events = Array.isArray(inputEvents) ? inputEvents : readBuildchainLogEvents(filePath);
+  } catch (error) {
+    issues.push(issue("error", "log.read.failed", error.message));
+  }
+  if (!events.length) {
+    issues.push(issue("error", "log.events.empty", `no Buildchain log events found at ${filePath || "<memory>"}`));
+  }
+  for (const [index, event] of events.entries()) {
+    if (event?.contract !== BUILDCHAIN_LOG_EVENT_CONTRACT) {
+      issues.push(issue("error", "log.contract.invalid", `event ${index} has invalid contract`));
+    }
+    for (const key of ["timestamp", "level", "source", "component", "event"]) {
+      if (!event?.[key]) {
+        issues.push(issue("error", "log.field.missing", `event ${index} is missing ${key}`));
+      }
+    }
+  }
+  const summary = summarizeBuildchainLogEvents(events);
+  const requiredEventCount = Number(minEvents || 0);
+  if (summary.eventCount < requiredEventCount) {
+    issues.push(issue("error", "log.events.too_few", `expected at least ${requiredEventCount} events, found ${summary.eventCount}`));
+  }
+  if (!allowErrors && summary.errorCount > 0) {
+    issues.push(issue("error", "log.errors.present", `expected no error events, found ${summary.errorCount}`));
+  }
+  for (const phase of listOption(requirePhases)) {
+    if (!summary.phases[phase]) {
+      issues.push(issue("error", "log.phase.missing", `required phase missing: ${phase}`));
+    }
+  }
+  for (const component of listOption(requireComponents)) {
+    if (!summary.components[component]) {
+      issues.push(issue("error", "log.component.missing", `required component missing: ${component}`));
+    }
+  }
+  const eventNames = new Set(events.map((event) => event.event).filter(Boolean));
+  for (const eventName of listOption(requireEvents)) {
+    if (!eventNames.has(eventName)) {
+      issues.push(issue("error", "log.event.missing", `required event missing: ${eventName}`));
+    }
+  }
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-log-verification",
+    ok: !issues.some((entry) => entry.level === "error"),
+    path: filePath,
+    summary,
+    requirements: {
+      minEvents: requiredEventCount,
+      allowErrors,
+      phases: listOption(requirePhases),
+      components: listOption(requireComponents),
+      events: listOption(requireEvents),
+    },
+    issues,
+  };
+}
+
 export function createBuildchainLogger(options = {}) {
   const cwd = path.resolve(options.cwd || process.cwd());
   const runningInActions = process.env.GITHUB_ACTIONS === "true";