@kungfu-tech/buildchain 2.0.17 → 2.1.0-alpha.0

package/bin/buildchain.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -7,6 +8,12 @@ import { initBuildchainRepo } from "../scripts/init-repo.mjs";
 import { npmPublishDryRun } from "../scripts/npm-publish-dry-run.mjs";
 import { runLifecycle } from "../scripts/run-lifecycle-core.mjs";
 import { validateBuildchainConfig } from "../packages/core/buildchain-config.js";
+import { detectPackageManager } from "../packages/core/package-manager.js";
+import {
+  createBuildchainLogger,
+  defaultBuildchainLogPath,
+  summarizeBuildchainLogEvents,
+} from "../packages/core/logging.js";
 import {
   explainReleaseLineDryRun,
   formatReleaseLineDryRun,
@@ -29,9 +36,21 @@ function usage() {
                          [--dist-tag <tag>] [--skip-npm-publish-dry-run] [--json]
   buildchain release --dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
                                  [--tags <comma-list>] [--json]
+  buildchain release explain --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
+                                     [--tags <comma-list>] [--json]
   buildchain release dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
                                       [--tags <comma-list>] [--json]
   buildchain release <inspect|recover|finalize|abort> ...
+  buildchain transaction inspect ...
+  buildchain doctor [--cwd <dir>] [--json]
+  buildchain log <info|warn|error> --event <name> [--phase <phase>]
+                 [--component <name>] [--source <name>] [--attribute key=value]...
+                 [--path <jsonl>] [--json]
+  buildchain log summary [--path <jsonl>] [--json]
+  buildchain mark --event <name> [--phase <phase>] [--component <name>]
+                  [--attribute key=value]... [--path <jsonl>] [--json]
+  buildchain span --event <name> [--phase <phase>] [--component <name>]
+                  [--path <jsonl>] -- <command> [args...]
   buildchain web-surface ...
   buildchain publish-source <lock|manifest|verify-lock> ...
   buildchain build-contract ...
@@ -42,6 +61,7 @@ Examples:
   buildchain lifecycle run build --artifact-path dist --artifact-name "{repo}-{version}-{platform}"
   buildchain npm dry-run --json
   buildchain release --dry-run --target-ref alpha/v2/v2.0
+  buildchain span --event native.build -- cmake --build build
 `;
 }
 
@@ -68,6 +88,76 @@ function readRepeatedFlag(args, name) {
   return values;
 }
 
+function readAttributes(args) {
+  const attributes = {};
+  for (const value of readRepeatedFlag(args, "attribute")) {
+    const separator = value.indexOf("=");
+    if (separator === -1) {
+      attributes[value] = true;
+    } else {
+      attributes[value.slice(0, separator)] = value.slice(separator + 1);
+    }
+  }
+  return attributes;
+}
+
+function defaultCliLogPath(args) {
+  return readFlag(args, "path", process.env.BUILDCHAIN_LOG_PATH || defaultBuildchainLogPath({ cwd: process.cwd() }));
+}
+
+function cliLogger(args, defaults = {}) {
+  return createBuildchainLogger({
+    cwd: process.cwd(),
+    path: defaultCliLogPath(args),
+    console: !readBooleanFlag(args, "quiet"),
+    source: readFlag(args, "source", defaults.source || "user"),
+    component: readFlag(args, "component", defaults.component || "cli"),
+    phase: readFlag(args, "phase", defaults.phase || ""),
+  });
+}
+
+function checkStatus(ok, id, message, details = {}) {
+  return { id, status: ok ? "pass" : "fail", message, details };
+}
+
+function runDoctor({ cwd = process.cwd() } = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const checks = [];
+  checks.push(checkStatus(fs.existsSync(resolvedCwd), "cwd.exists", "working directory exists", { cwd: resolvedCwd }));
+  try {
+    const validation = validateBuildchainConfig(resolvedCwd);
+    checks.push(checkStatus(true, "config.valid", "buildchain.toml is valid", {
+      projectType: validation.project.type,
+      lifecycleStages: validation.lifecycleStages.map((stage) => stage.name),
+    }));
+  } catch (error) {
+    checks.push(checkStatus(false, "config.valid", error.message));
+  }
+  try {
+    const manager = detectPackageManager(resolvedCwd);
+    checks.push(checkStatus(true, "package-manager.detected", `package manager: ${manager.name}`, manager));
+  } catch (error) {
+    checks.push(checkStatus(false, "package-manager.detected", error.message));
+  }
+  const git = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+    cwd: resolvedCwd,
+    encoding: "utf8",
+  });
+  checks.push(checkStatus(git.status === 0 && git.stdout.trim() === "true", "git.repository", "directory is a git repository"));
+  const workflowPath = path.join(resolvedCwd, ".github", "workflows", "build.yml");
+  checks.push(checkStatus(fs.existsSync(workflowPath), "workflow.build", "reusable workflow caller exists", {
+    path: ".github/workflows/build.yml",
+  }));
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-doctor",
+    cwd: resolvedCwd,
+    ok: checks.every((check) => check.status === "pass"),
+    checks,
+    docsUrl: "https://buildchain.libkungfu.dev/docs/cli",
+  };
+}
+
 function runScript(scriptName, args) {
   const scriptPath = path.join(root, "scripts", scriptName);
   const result = spawnSync(process.execPath, [scriptPath, ...args], {
@@ -127,6 +217,111 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "doctor") {
+    const result = runDoctor({ cwd: readFlag(args, "cwd", process.cwd()) });
+    if (readBooleanFlag(args, "json")) {
+      printJson(result);
+    } else {
+      process.stdout.write(`buildchain doctor: ${result.ok ? "ok" : "failed"}\n`);
+      for (const check of result.checks) {
+        process.stdout.write(`- ${check.status}: ${check.id}: ${check.message}\n`);
+      }
+    }
+    return;
+  }
+
+  if (command === "log") {
+    const [levelOrSubcommand = "info", ...logArgs] = args;
+    if (levelOrSubcommand === "summary") {
+      const logPath = defaultCliLogPath(logArgs);
+      const summary = summarizeBuildchainLogEvents({ path: logPath });
+      if (readBooleanFlag(logArgs, "json")) {
+        printJson(summary);
+      } else {
+        process.stdout.write(`buildchain log summary: ${summary.eventCount} events\n`);
+        process.stdout.write(`sources: ${Object.keys(summary.sources).join(", ") || "none"}\n`);
+        process.stdout.write(`phases: ${Object.keys(summary.phases).join(", ") || "none"}\n`);
+      }
+      return;
+    }
+    if (!["info", "warn", "error"].includes(levelOrSubcommand)) {
+      throw new Error("usage: buildchain log <info|warn|error> --event <name>");
+    }
+    const eventName = readFlag(logArgs, "event", "");
+    if (!eventName) {
+      throw new Error("buildchain log requires --event <name>");
+    }
+    const logger = cliLogger(logArgs);
+    const event = logger.emit(levelOrSubcommand, eventName, {
+      message: readFlag(logArgs, "message", ""),
+      attributes: readAttributes(logArgs),
+    });
+    if (readBooleanFlag(logArgs, "json")) {
+      printJson(event);
+    }
+    return;
+  }
+
+  if (command === "mark") {
+    const eventName = readFlag(args, "event", "");
+    if (!eventName) {
+      throw new Error("buildchain mark requires --event <name>");
+    }
+    const logger = cliLogger(args);
+    const event = logger.mark(eventName, {
+      message: readFlag(args, "message", ""),
+      attributes: readAttributes(args),
+    });
+    if (readBooleanFlag(args, "json")) {
+      printJson(event);
+    }
+    return;
+  }
+
+  if (command === "span") {
+    const separator = args.indexOf("--");
+    const spanArgs = separator === -1 ? args : args.slice(0, separator);
+    const commandArgs = separator === -1 ? [] : args.slice(separator + 1);
+    const eventName = readFlag(spanArgs, "event", "");
+    if (!eventName || commandArgs.length === 0) {
+      throw new Error("usage: buildchain span --event <name> -- <command> [args...]");
+    }
+    const logger = cliLogger(spanArgs);
+    const spanId = crypto.randomUUID();
+    const startedAt = Date.now();
+    logger.info(`${eventName}.start`, {
+      spanId,
+      message: readFlag(spanArgs, "message", ""),
+      attributes: readAttributes(spanArgs),
+    });
+    const result = spawnSync(commandArgs[0], commandArgs.slice(1), {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: "inherit",
+    });
+    const durationMs = Date.now() - startedAt;
+    if (result.error || result.status !== 0) {
+      logger.error(`${eventName}.error`, {
+        spanId,
+        durationMs,
+        message: result.error?.message || `command exited with ${result.status ?? "signal"}`,
+        attributes: {
+          ...readAttributes(spanArgs),
+          status: result.status ?? "",
+          signal: result.signal || "",
+        },
+      });
+      process.exitCode = result.status ?? 1;
+      return;
+    }
+    logger.info(`${eventName}.end`, {
+      spanId,
+      durationMs,
+      attributes: readAttributes(spanArgs),
+    });
+    return;
+  }
+
   if (command === "lifecycle") {
     const [subcommand, stageName = "", ...lifecycleArgs] = args;
     if (subcommand !== "run" || !stageName) {
@@ -140,6 +335,7 @@ async function main(argv = process.argv.slice(2)) {
       artifactName: readFlag(lifecycleArgs, "artifact-name", "buildchain-artifact"),
       artifactPaths,
       expectedArtifactsJson: readFlag(lifecycleArgs, "expected-artifacts-json", ""),
+      logPath: readFlag(lifecycleArgs, "log-path", process.env.BUILDCHAIN_LOG_PATH || ".buildchain/logs/events.jsonl"),
       workspace: process.cwd(),
     });
     printJson(manifest);
@@ -168,8 +364,9 @@ async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === "release") {
-    const releaseArgs = args[0] === "dry-run" ? args.slice(1) : args;
-    if (args[0] === "dry-run" || readBooleanFlag(args, "dry-run")) {
+    const explainMode = args[0] === "dry-run" || args[0] === "explain";
+    const releaseArgs = explainMode ? args.slice(1) : args;
+    if (explainMode || readBooleanFlag(args, "dry-run")) {
       const plan = explainReleaseLineDryRun({
         cwd: readFlag(releaseArgs, "cwd", process.cwd()),
         targetRef: readFlag(releaseArgs, "target-ref", ""),
@@ -190,6 +387,15 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "transaction") {
+    const [subcommand = "inspect", ...transactionArgs] = args;
+    if (subcommand !== "inspect") {
+      throw new Error("usage: buildchain transaction inspect ...");
+    }
+    runScript("release-transaction.mjs", ["inspect", ...transactionArgs]);
+    return;
+  }
+
   if (command === "web-surface") {
     runScript("web-surface.mjs", args);
     return;

package/docs/cli.md

@@ -58,6 +58,54 @@ buildchain lifecycle run build \
   --artifact-name "{repo}-{version}-{platform}"
 ```
 
+Lifecycle runs also write a Buildchain observability JSONL log at
+`.buildchain/logs/events.jsonl` by default. Framework events use
+`source=buildchain`; consumer lifecycle commands use `source=user`. This lets a
+maintainer tell apart time spent inside Buildchain's artifact/manifest
+framework from time spent in the repository's own build, test, packaging, or
+publish commands. The artifact manifest and summary embed the observability
+summary for that lifecycle run id, so uploaded artifacts preserve the timing
+facts without mixing in older JSONL events.
+
+`buildchain log`, `buildchain mark`, and `buildchain span` expose the same event
+protocol to repository scripts:
+
+```bash
+buildchain mark --event configure.ready --phase configure --attribute target=release
+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
+```
+
+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.
+
+The event protocol is JSONL and is also available from the SDK:
+
+```js
+import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+
+const logger = createBuildchainLogger({ source: "user", component: "native-build" });
+logger.mark("configure.ready", { phase: "configure" });
+```
+
+Secret-looking attribute keys such as `token`, `password`, `secret`,
+`authorization`, `cookie`, and `private-key` are redacted before they are written.
+Full command strings are not recorded by `span`; scripts should provide stable
+event names and safe attributes instead.
+
+`buildchain doctor` checks repository readiness before remote side effects:
+
+```bash
+buildchain doctor --json
+```
+
+It validates `buildchain.toml`, package-manager detection, Git repository state,
+and the reusable workflow caller. The JSON result is shaped for future
+`buildchain.libkungfu.dev` fact ingestion.
+
 `buildchain release`, `buildchain web-surface`, `buildchain publish-source`,
 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
@@ -70,6 +118,7 @@ maintainer opens or merges a channel PR:
 buildchain release --dry-run --target-ref alpha/v2/v2.0
 buildchain release --dry-run --target-ref release/v2/v2.0 --sha <verified-sha>
 buildchain release dry-run --target-ref publish-gate/major --source-ref release/v2/v2.0
+buildchain release explain --target-ref alpha/v2/v2.1 --json
 ```
 
 This is a Buildchain-level dry-run, not an npm dry-run. It explains the legal
@@ -77,7 +126,21 @@ source branch, exact release or alpha tags, floating tags, channel branches,
 version-state files, governance checks, and publish transaction behavior that
 would apply if the corresponding PR merge were promoted. It does not move
 branches, move tags, edit files, publish npm packages, or run lifecycle publish
-commands. Pass `--json` for a machine-readable plan.
+commands. `release explain` is the same explanation surface with a clearer name.
+Pass `--json` for a machine-readable plan.
+
+`buildchain transaction inspect` is the top-level recovery inspection command
+for the publish transaction state:
+
+```bash
+buildchain transaction inspect --version v2.1.0-alpha.0
+```
+
+It reads or locally initializes the durable transaction record and validates
+available publish evidence. Remote durable refs and public Git ref finalization
+remain owned by `actions/promote-buildchain-ref`; the CLI inspection surface is
+for preflight and recovery reasoning before a maintainer reruns or resumes a
+promotion.
 
 `buildchain npm dry-run` verifies the package shape before a release tag exists:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.0.17",
+  "version": "2.1.0-alpha.0",
   "private": false,
   "description": "Kungfu Buildchain reusable workflows, release governance, and CLI tooling.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -13,6 +13,7 @@
   "exports": {
     ".": "./packages/core/index.js",
     "./core": "./packages/core/index.js",
+    "./logging": "./packages/core/logging.js",
     "./package.json": "./package.json"
   },
   "files": [

package/packages/core/index.js

@@ -39,3 +39,15 @@ export {
   explainReleaseLineDryRun,
   formatReleaseLineDryRun,
 } from "./release-line-dry-run.js";
+
+export {
+  BUILDCHAIN_LOG_EVENT_CONTRACT,
+  BUILDCHAIN_LOG_SUMMARY_CONTRACT,
+  appendBuildchainLogEvent,
+  createBuildchainLogger,
+  defaultBuildchainLogPath,
+  normalizeBuildchainLogEvent,
+  readBuildchainLogEvents,
+  redactBuildchainLogAttributes,
+  summarizeBuildchainLogEvents,
+} from "./logging.js";

package/packages/core/logging.js

@@ -0,0 +1,197 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const BUILDCHAIN_LOG_EVENT_CONTRACT = "kungfu-buildchain-log-event";
+export const BUILDCHAIN_LOG_SUMMARY_CONTRACT = "kungfu-buildchain-log-summary";
+
+const SECRET_KEY_PATTERN =
+  /(authorization|cookie|credential|password|passwd|private[_-]?key|secret|token|api[_-]?key)/i;
+
+function compactObject(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined && entry !== ""));
+}
+
+function scalarValue(value) {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
+export function redactBuildchainLogAttributes(attributes = {}) {
+  const redacted = {};
+  for (const [key, value] of Object.entries(attributes || {})) {
+    redacted[key] = SECRET_KEY_PATTERN.test(key) ? "[REDACTED]" : scalarValue(value);
+  }
+  return redacted;
+}
+
+export function defaultBuildchainLogPath({ cwd = process.cwd() } = {}) {
+  return path.join(cwd, ".buildchain", "logs", "events.jsonl");
+}
+
+export function normalizeBuildchainLogEvent(input = {}, defaults = {}) {
+  const timestamp = input.timestamp || new Date().toISOString();
+  return compactObject({
+    schemaVersion: 1,
+    contract: BUILDCHAIN_LOG_EVENT_CONTRACT,
+    timestamp,
+    level: input.level || defaults.level || "info",
+    source: input.source || defaults.source || "buildchain",
+    component: input.component || defaults.component || "cli",
+    event: input.event || defaults.event || "event",
+    phase: input.phase || defaults.phase,
+    spanId: input.spanId || defaults.spanId,
+    parentSpanId: input.parentSpanId || defaults.parentSpanId,
+    durationMs: Number.isFinite(input.durationMs) ? Math.round(input.durationMs) : undefined,
+    message: input.message || defaults.message,
+    attributes: redactBuildchainLogAttributes({
+      ...(defaults.attributes || {}),
+      ...(input.attributes || {}),
+    }),
+  });
+}
+
+export function appendBuildchainLogEvent(filePath, event) {
+  if (!filePath) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, `${JSON.stringify(event)}\n`);
+}
+
+export function readBuildchainLogEvents(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return [];
+  }
+  return fs
+    .readFileSync(filePath, "utf8")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function groupSummary(events, field) {
+  const groups = {};
+  for (const event of events) {
+    const key = event[field] || "unknown";
+    const current = groups[key] || { count: 0, durationMs: 0 };
+    current.count += 1;
+    current.durationMs += Number(event.durationMs || 0);
+    groups[key] = current;
+  }
+  return Object.fromEntries(
+    Object.entries(groups).sort(([left], [right]) => left.localeCompare(right)),
+  );
+}
+
+export function summarizeBuildchainLogEvents(input = {}) {
+  const events = Array.isArray(input)
+    ? input
+    : typeof input === "string"
+      ? readBuildchainLogEvents(input)
+      : readBuildchainLogEvents(input.path);
+  const errorCount = events.filter((event) => event.level === "error").length;
+  const warningCount = events.filter((event) => event.level === "warn").length;
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_LOG_SUMMARY_CONTRACT,
+    generatedAt: new Date().toISOString(),
+    eventCount: events.length,
+    warningCount,
+    errorCount,
+    durationMs: events.reduce((sum, event) => sum + Number(event.durationMs || 0), 0),
+    sources: groupSummary(events, "source"),
+    phases: groupSummary(events, "phase"),
+    components: groupSummary(events, "component"),
+  };
+}
+
+export function createBuildchainLogger(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const runningInActions = process.env.GITHUB_ACTIONS === "true";
+  const resolvedPath =
+    options.path === false
+      ? ""
+      : options.path || process.env.BUILDCHAIN_LOG_PATH || (runningInActions ? defaultBuildchainLogPath({ cwd }) : "");
+  const consoleEnabled = options.console ?? !resolvedPath;
+  const defaults = {
+    source: options.source || "buildchain",
+    component: options.component || "cli",
+    phase: options.phase || "",
+    attributes: {
+      ...(process.env.BUILDCHAIN_LOG_RUN_ID
+        ? { buildchainLogRunId: process.env.BUILDCHAIN_LOG_RUN_ID }
+        : {}),
+      ...(options.attributes || {}),
+    },
+  };
+  const inMemoryEvents = [];
+
+  function emit(level, eventName, details = {}) {
+    const event = normalizeBuildchainLogEvent(
+      {
+        ...details,
+        level,
+        event: eventName,
+      },
+      defaults,
+    );
+    try {
+      appendBuildchainLogEvent(resolvedPath, event);
+    } catch (error) {
+      if (options.strict) {
+        throw error;
+      }
+    }
+    inMemoryEvents.push(event);
+    if (consoleEnabled) {
+      const message = event.message ? ` ${event.message}` : "";
+      process.stderr.write(`[buildchain] ${event.level} ${event.event}${message}\n`);
+    }
+    return event;
+  }
+
+  async function span(eventName, details = {}, callback = async () => undefined) {
+    const spanId = details.spanId || crypto.randomUUID();
+    const startedAt = Date.now();
+    emit("info", `${eventName}.start`, { ...details, spanId });
+    try {
+      const result = await callback({ spanId });
+      emit("info", `${eventName}.end`, {
+        ...details,
+        spanId,
+        durationMs: Date.now() - startedAt,
+      });
+      return result;
+    } catch (error) {
+      emit("error", `${eventName}.error`, {
+        ...details,
+        spanId,
+        durationMs: Date.now() - startedAt,
+        message: error.message,
+        attributes: {
+          ...(details.attributes || {}),
+          errorName: error.name,
+        },
+      });
+      throw error;
+    }
+  }
+
+  return {
+    path: resolvedPath,
+    events: inMemoryEvents,
+    emit,
+    info: (eventName, details) => emit("info", eventName, details),
+    warn: (eventName, details) => emit("warn", eventName, details),
+    error: (eventName, details) => emit("error", eventName, details),
+    mark: (eventName, details) => emit("info", eventName, details),
+    span,
+    summary: () => summarizeBuildchainLogEvents(resolvedPath ? { path: resolvedPath } : inMemoryEvents),
+  };
+}

package/scripts/check-inventory.mjs

@@ -55,6 +55,9 @@ if (rootPackage.bin?.buildchain !== "./bin/buildchain.mjs") {
 if (rootPackage.exports?.["."] !== "./packages/core/index.js") {
   throw new Error("root package must export packages/core/index.js");
 }
+if (rootPackage.exports?.["./logging"] !== "./packages/core/logging.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/logging");
+}
 if (rootPackage.publishConfig?.access !== "public") {
   throw new Error("root package publishConfig.access must be public");
 }

package/scripts/run-lifecycle-core.mjs

@@ -8,6 +8,11 @@ import {
   normalizeLifecycleStage,
   runLifecycleStage,
 } from "../packages/core/buildchain-config.js";
+import {
+  createBuildchainLogger,
+  readBuildchainLogEvents,
+  summarizeBuildchainLogEvents,
+} from "../packages/core/logging.js";
 import {
   createArtifactSummary,
   parseExpectedArtifactsJson,
@@ -46,6 +51,15 @@ function manifestPathFor(root, filePath) {
   return toPosix(path.resolve(filePath));
 }
 
+function lifecycleErrorAttributes(error, extra = {}) {
+  return {
+    ...extra,
+    errorName: error.name,
+    status: error.status ?? "",
+    signal: error.signal || "",
+  };
+}
+
 function collectArtifactFiles(root, patterns) {
   const files = new Set();
   for (const pattern of patterns) {
@@ -70,38 +84,142 @@ export function runLifecycle({
   artifactPaths = [],
   expectedArtifactsJson = "",
   workspace = process.cwd(),
+  logPath = process.env.BUILDCHAIN_LOG_PATH || ".buildchain/logs/events.jsonl",
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const resolvedWorkspace = path.resolve(workspace);
   const resolvedManifestPath = path.resolve(resolvedWorkspace, manifestPath);
   const resolvedSummaryPath = path.resolve(resolvedWorkspace, summaryPath);
+  const resolvedLogPath = logPath ? path.resolve(resolvedWorkspace, logPath) : "";
+  const relativeLogPath = resolvedLogPath ? toPosix(path.relative(resolvedWorkspace, resolvedLogPath)) : "";
+  const logRunId = crypto.randomUUID();
+  const frameworkLog = createBuildchainLogger({
+    cwd: resolvedWorkspace,
+    path: resolvedLogPath || false,
+    console: false,
+    source: "buildchain",
+    component: "lifecycle",
+    phase: stageName || "lifecycle",
+    attributes: { buildchainLogRunId: logRunId },
+  });
+  const userLog = createBuildchainLogger({
+    cwd: resolvedWorkspace,
+    path: resolvedLogPath || false,
+    console: false,
+    source: "user",
+    component: "lifecycle",
+    phase: stageName || "lifecycle",
+    attributes: { buildchainLogRunId: logRunId },
+  });
   const loadedConfig = loadBuildchainConfig(resolvedCwd);
   let commandSource = "none";
   let executed = false;
 
+  frameworkLog.info("lifecycle.start", {
+    attributes: {
+      stage: stageName,
+      artifactName,
+      platformId,
+    },
+  });
+
   if (command.trim()) {
     commandSource = "workflow-input";
-    execSync(command, {
-      cwd: resolvedCwd,
-      env: process.env,
-      shell: true,
-      stdio: "inherit",
+    const startedAt = Date.now();
+    userLog.info("lifecycle.command.start", {
+      attributes: {
+        commandSource,
+        stage: stageName || "command",
+      },
     });
-    executed = true;
+    try {
+      execSync(command, {
+        cwd: resolvedCwd,
+        env: {
+          ...process.env,
+          ...(resolvedLogPath
+            ? {
+                BUILDCHAIN_LOG_PATH: resolvedLogPath,
+                BUILDCHAIN_LOG_RUN_ID: logRunId,
+              }
+            : {}),
+        },
+        shell: true,
+        stdio: "inherit",
+      });
+      executed = true;
+      userLog.info("lifecycle.command.end", {
+        durationMs: Date.now() - startedAt,
+        attributes: {
+          commandSource,
+          stage: stageName || "command",
+        },
+      });
+    } catch (error) {
+      userLog.error("lifecycle.command.error", {
+        durationMs: Date.now() - startedAt,
+        message: "lifecycle command failed",
+        attributes: lifecycleErrorAttributes(error, {
+          commandSource,
+          stage: stageName || "command",
+        }),
+      });
+      throw error;
+    }
   } else if (stageName) {
     commandSource = "buildchain.toml";
-    executed = runLifecycleStage({
-      cwd: resolvedCwd,
-      loadedConfig,
-      name: stageName,
+    const startedAt = Date.now();
+    userLog.info("lifecycle.stage.start", {
+      attributes: {
+        commandSource,
+        stage: stageName,
+      },
     });
+    try {
+      executed = runLifecycleStage({
+        cwd: resolvedCwd,
+        loadedConfig,
+        name: stageName,
+        env: resolvedLogPath
+          ? {
+              BUILDCHAIN_LOG_PATH: resolvedLogPath,
+              BUILDCHAIN_LOG_RUN_ID: logRunId,
+            }
+          : {},
+      });
+      userLog.info("lifecycle.stage.end", {
+        durationMs: Date.now() - startedAt,
+        attributes: {
+          commandSource,
+          stage: stageName,
+          executed,
+        },
+      });
+    } catch (error) {
+      userLog.error("lifecycle.stage.error", {
+        durationMs: Date.now() - startedAt,
+        message: "lifecycle stage failed",
+        attributes: lifecycleErrorAttributes(error, {
+          commandSource,
+          stage: stageName,
+        }),
+      });
+      throw error;
+    }
   }
 
   if (required && !executed) {
+    frameworkLog.error("lifecycle.required-missing", {
+      attributes: {
+        stage: stageName || "command",
+        commandSource,
+      },
+    });
     throw new Error(`required lifecycle stage did not run: ${stageName || "command"}`);
   }
 
   fs.mkdirSync(path.dirname(resolvedManifestPath), { recursive: true });
+  const scanStartedAt = Date.now();
   const files = collectArtifactFiles(resolvedWorkspace, artifactPaths);
   const manifestFiles = files.map((file) => {
     const stat = fs.statSync(file);
@@ -111,6 +229,12 @@ export function runLifecycle({
       sha256: sha256File(file),
     };
   });
+  frameworkLog.info("artifact.scan", {
+    durationMs: Date.now() - scanStartedAt,
+    attributes: {
+      fileCount: manifestFiles.length,
+    },
+  });
   const platform = {
     id: platformId,
     name: platformName,
@@ -128,6 +252,37 @@ export function runLifecycle({
     files: manifestFiles,
     summary,
   });
+  frameworkLog.info("artifact.manifest.write", {
+    attributes: {
+      manifestPath: toPosix(path.relative(resolvedWorkspace, resolvedManifestPath)),
+      summaryPath: toPosix(path.relative(resolvedWorkspace, resolvedSummaryPath)),
+    },
+  });
+  frameworkLog.info("lifecycle.end", {
+    attributes: {
+      stage: stageName,
+      executed,
+      fileCount: manifestFiles.length,
+    },
+  });
+  const observability = {
+    log: {
+      contract: "kungfu-buildchain-log-event",
+      runId: logRunId,
+      path: relativeLogPath,
+      summary: resolvedLogPath
+        ? summarizeBuildchainLogEvents(
+            readBuildchainLogEvents(resolvedLogPath).filter(
+              (event) => event.attributes?.buildchainLogRunId === logRunId,
+            ),
+          )
+        : summarizeBuildchainLogEvents([...frameworkLog.events, ...userLog.events]),
+    },
+  };
+  const summaryWithObservability = {
+    ...summary,
+    observability,
+  };
   const manifest = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-artifact",
@@ -145,14 +300,15 @@ export function runLifecycle({
       commandSource,
       executed,
     },
-    summary,
+    observability,
+    summary: summaryWithObservability,
     expectedArtifacts,
     files: manifestFiles,
   };
 
   fs.writeFileSync(resolvedManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
   fs.mkdirSync(path.dirname(resolvedSummaryPath), { recursive: true });
-  fs.writeFileSync(resolvedSummaryPath, `${JSON.stringify(summary, null, 2)}\n`);
+  fs.writeFileSync(resolvedSummaryPath, `${JSON.stringify(summaryWithObservability, null, 2)}\n`);
   console.log(`buildchain_manifest=${path.relative(resolvedWorkspace, resolvedManifestPath)}`);
   return manifest;
 }