@kungfu-tech/buildchain 4.1.3-alpha.0 → 4.1.3-alpha.10

package/packages/core/workflow/attempt/store.js

@@ -0,0 +1,75 @@
+import { releaseDiscussionStore } from "../../release/discussion/store.js";
+import { validateAttemptRecord } from "./records.js";
+import { readBusinessAttempt } from "./reader.js";
+
+// exclusive.run owns the repository/intent-wide writer scope, not merely this
+// process. assertOwner rechecks the live provider fence before every mutation.
+// No default mutex: an in-memory lock cannot serialize independent workflows.
+export function businessAttemptStore(transport, exclusive, options = {}) {
+  if (typeof exclusive?.run !== "function")
+    throw new Error("Attempt writes require an exclusive provider writer");
+  const journal = releaseDiscussionStore(transport, options);
+  async function read(session) {
+    const observed = await journal.read(session);
+    return { ...observed, ...readBusinessAttempt(observed) };
+  }
+  async function scoped(intent, operation) {
+    return exclusive.run(
+      { repository: intent.repository, intent: intent.id },
+      async (owner) => {
+        if (typeof owner?.assertOwner !== "function")
+          throw new Error("Missing live writer fence");
+        await owner.assertOwner();
+        return operation(owner);
+      },
+    );
+  }
+  async function initialize(request) {
+    readBusinessAttempt({ intent: request.intent, records: [] });
+    return scoped(request.intent, async (owner) => {
+      const repository = await transport.repository(request.intent.repository);
+      if (repository.id !== request.intent.source.repositoryId)
+        throw new Error("Intent repository identity changed");
+      const fenced = { ...transport };
+      for (const name of ["create", "append"])
+        fenced[name] = async (...args) => {
+          await owner.assertOwner();
+          return transport[name](...args);
+        };
+      return releaseDiscussionStore(fenced, options).initialize(request);
+    });
+  }
+  async function append(session, record, expectedHead) {
+    return scoped(session.intent, async (owner) => {
+      validateAttemptRecord(record, session.intent);
+      const observed = await read(session);
+      const existing = observed.records.find((event) => event.id === record.id);
+      if (existing) return observed;
+      if ((observed.head || "") !== expectedHead)
+        throw new Error("Stale attempt head; reobserve before writing");
+      if (record.node === "attempt") {
+        if (record.predecessor !== (observed.attempt || ""))
+          throw new Error("Recovery must succeed the current attempt");
+      } else if (record.attempt !== observed.attempt)
+        throw new Error("A superseded attempt cannot append new results");
+      readBusinessAttempt({
+        intent: observed.intent,
+        records: [...observed.records, record],
+      });
+      await owner.assertOwner();
+      const fenced = {
+        ...transport,
+        append: async (...args) => {
+          await owner.assertOwner();
+          return transport.append(...args);
+        },
+      };
+      await releaseDiscussionStore(fenced, options).append(session, record);
+      const result = await read(session);
+      if (result.head !== record.id)
+        throw new Error("Attempt append readback has a conflicting writer");
+      return result;
+    });
+  }
+  return { initialize, read, append };
+}

package/packages/core/workflow/commands/pipeline-build.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { normalInputs } from "../../consumer/contract/entries.js";
+import { compileConsumerPlan } from "../../consumer/contract/plan.js";
+import { buildPipelineProducts } from "../pipeline/build.js";
+
+const args = process.argv.slice(2);
+if (
+  args.length !== 4 ||
+  args[0] !== "--platform" ||
+  args[2] !== "--config-path"
+)
+  throw new Error(
+    "usage: pipeline-build --platform <platform> --config-path <TOML>",
+  );
+const { configPath } = normalInputs({ "config-path": args[3] });
+const cwd = fs.realpathSync(process.cwd());
+const config = fs.realpathSync(path.join(cwd, configPath));
+if (!config.startsWith(`${cwd}${path.sep}`))
+  throw new Error("Candidate TOML escapes its checkout");
+const plan = compileConsumerPlan(fs.readFileSync(config, "utf8"));
+await buildPipelineProducts({ cwd, plan, platform: args[1] });

package/packages/core/workflow/pipeline/action-output.js

@@ -0,0 +1,11 @@
+export function pipelineActionOutputs(core, result) {
+  core.setOutput("operation", result.operation);
+  core.setOutput("context", JSON.stringify(result.context || {}));
+  core.setOutput(
+    "matrix",
+    JSON.stringify({ include: result.context?.platforms || [] }),
+  );
+  core.setOutput("request", JSON.stringify(result.request || {}));
+  core.setOutput("attempt", result.attempt || result.context?.attempt || "");
+  core.info(result.reason || result.operation);
+}

package/packages/core/workflow/pipeline/actions.js

@@ -0,0 +1,52 @@
+import { pipelineActionOutputs } from "./action-output.js";
+import fs from "node:fs";
+import path from "node:path";
+import { normalInputs } from "../../consumer/contract/entries.js";
+import { pipelineHost } from "./host.js";
+import { controlPipeline } from "./controller.js";
+import { buildPipelineSource } from "./build.js";
+import { wakePipelineStableWait } from "../../publication/pipeline/stable-wait.js";
+
+export async function controlPipelineAction(core, env) {
+  const { configPath } = normalInputs({
+    "config-path": core.getInput("config-path") || undefined,
+  });
+  const host = await pipelineHost(core, env, "Buildchain pipeline controller");
+  const result = await controlPipeline(
+    env.GITHUB_EVENT_NAME,
+    JSON.parse(fs.readFileSync(env.GITHUB_EVENT_PATH, "utf8")),
+    { "config-path": configPath },
+    host,
+  );
+  pipelineActionOutputs(core, result);
+}
+
+export async function buildPipelineAction(core, env) {
+  const context = JSON.parse(core.getInput("context", { required: true }));
+  const result = await buildPipelineSource({
+    cwd: path.join(env.GITHUB_WORKSPACE, ".buildchain/product"),
+    source: context.source,
+    platform: core.getInput("platform", { required: true }),
+    environment: env,
+  });
+  core.info(
+    `Verified ${result.products.length} products on ${result.platform}`,
+  );
+}
+
+export async function wakePipelineAction(core, env) {
+  const waiting = core.getInput("stable-wait");
+  const host = await pipelineHost(
+    core,
+    env,
+    waiting ? "Recheck stable publication" : "Record delivery attempt",
+  );
+  if (waiting) {
+    const wait = JSON.parse(waiting);
+    if (wait.attempt !== core.getInput("attempt", { required: true }))
+      throw new Error("Stable wake changed its exact business attempt");
+    core.info(JSON.stringify(await wakePipelineStableWait(wait, host)));
+    return;
+  }
+  await host.wake(core.getInput("attempt", { required: true }));
+}

package/packages/core/workflow/pipeline/build-control.js

@@ -0,0 +1,140 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { object } from "../../consumer/contract/shape.js";
+import { pipelinePlatforms } from "./platforms.js";
+import { resumePipelineSession } from "./session.js";
+import { retainPipelineBuildResult } from "./build-result.js";
+
+export async function beginPipelineBuild(session, admission, host) {
+  const observed = await session.journal.read();
+  const attempt = observed.attempt;
+  const previous = observed.phases.build;
+  if (
+    previous &&
+    (previous.payload.writer.runId !== String(host.runId) ||
+      previous.payload.writer.runAttempt !== String(host.runAttempt))
+  ) {
+    const { run } = await host.runs.read(
+      Number(previous.payload.writer.runId),
+      Number(previous.payload.writer.runAttempt),
+    );
+    if (run.status !== "completed") return null;
+    const material = await host
+      .materialStore(session)
+      .retain(
+        `build/incomplete-${run.id}-${run.run_attempt}`,
+        run,
+        "provider-readback",
+      );
+    await session.progress.progress({
+      attempt,
+      phase: "build",
+      state: "failure",
+      eventKey: `build-incomplete:${run.id}:${run.run_attempt}`,
+      reason: "build-recording-incomplete",
+      materials: [material],
+      expectedHead: observed.head,
+    });
+    return null;
+  }
+  if (!observed.phases.admission) {
+    const receipt = {
+      schema: "buildchain.pipeline-source-observation/v1",
+      repositoryId: admission.repositoryId,
+      source: admission.live.source,
+      baseCommit: admission.live.baseCommit,
+      protectedSource: admission.protectedSource,
+      route: admission.route,
+      runtime: host.runtime,
+    };
+    const reference = await host
+      .materialStore(session)
+      .retain("source/admission", receipt, "provider-readback");
+    await session.progress.progress({
+      attempt,
+      phase: "admission",
+      state: "success",
+      eventKey: `admission:${observed.generation}`,
+      materials: [reference],
+    });
+  }
+  const scheduling = await session.journal.read();
+  const scheduled = scheduling.phases.build?.payload.writer;
+  if (
+    scheduled &&
+    (scheduled.runId !== String(host.runId) ||
+      scheduled.runAttempt !== String(host.runAttempt))
+  )
+    return null;
+  await session.progress.progress({
+    attempt,
+    phase: "build",
+    state: "running",
+    eventKey: `build-start:${host.runId}:${host.runAttempt}`,
+    expectedHead: scheduling.head,
+  });
+  return {
+    schema: "buildchain.pipeline-build-context/v1",
+    attempt,
+    generation: observed.generation,
+    source: admission.live.source,
+    runId: host.runId,
+    runAttempt: host.runAttempt,
+    platforms: pipelinePlatforms(admission.plan),
+  };
+}
+
+export function validatePipelineBuildContext(context) {
+  object(context, [
+    "schema",
+    "attempt",
+    "generation",
+    "source",
+    "runId",
+    "runAttempt",
+    "platforms",
+  ]);
+  if (
+    context.schema !== "buildchain.pipeline-build-context/v1" ||
+    !/^attempt-[0-9a-f]{64}$/u.test(context.attempt) ||
+    !/^sha256:[0-9a-f]{64}$/u.test(context.generation) ||
+    ![context.runId, context.runAttempt].every(
+      (value) => Number.isSafeInteger(value) && value > 0,
+    )
+  )
+    throw new Error("Invalid internal pipeline build context");
+  return context;
+}
+
+export async function recordPipelineBuild(context, host) {
+  validatePipelineBuildContext(context);
+  if (context.runId !== host.runId || context.runAttempt !== host.runAttempt)
+    throw new Error("Build callback belongs to another provider execution");
+  const session = await resumePipelineSession(
+    { ...host, attempt: context.attempt },
+    host,
+  );
+  const current = session.observed.history.at(-1);
+  if (
+    context.generation !== current.generation.id ||
+    recordDigest(context.source) !== recordDigest(current.generation.source)
+  )
+    throw new Error("Build callback changed its admitted source generation");
+  const admitted = await host.source.source(
+    context.source.commit,
+    context.source.configPath,
+  );
+  if (
+    recordDigest(context.platforms) !==
+    recordDigest(pipelinePlatforms(admitted.plan))
+  )
+    throw new Error(
+      "Build callback omitted or changed a declared product platform",
+    );
+  const readback = await host.runs.build(
+    context.runId,
+    context.runAttempt,
+    context.source,
+    context.platforms.map((platform) => platform.platform),
+  );
+  return retainPipelineBuildResult(context, readback, session, host);
+}

package/packages/core/workflow/pipeline/build-evidence.js

@@ -0,0 +1,210 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  PIPELINE_BUILD_QUALIFICATION,
+  verifyPipelineBuildQualification,
+} from "./build-qualification.js";
+import { pipelinePlatforms } from "./platforms.js";
+
+const RECOVERY_CHECK = "Buildchain recovery verification";
+
+// Dispatch-created Actions checks do not satisfy protected PR checks. Preserve
+// their evidence under a diagnostic name instead of shadowing normal PR checks.
+export async function observePipelineBuildChecks(source, request, repository) {
+  if (
+    source.repository !== repository ||
+    !/^[0-9a-f]{40}$/u.test(source.commit)
+  )
+    throw new Error("Recovery check repository or source identity drift");
+  const base = `/repos/${repository}`,
+    renames = [],
+    eligible = [];
+  for (let page = 1; page <= 20; page++) {
+    const result = await request(
+      `${base}/commits/${source.commit}/check-runs?filter=all&per_page=100&page=${page}`,
+    );
+    if (!Array.isArray(result.check_runs) || result.check_runs.length > 100)
+      throw new Error("Recovery check inventory is incomplete");
+    for (const check of result.check_runs) {
+      const match = /^buildchain:(attempt-[0-9a-f]{64}):(\d+):(\d+)$/u.exec(
+        check.external_id || "",
+      );
+      if (
+        check.name !== "check" ||
+        check.app?.slug !== "github-actions" ||
+        !match
+      )
+        continue;
+      const runId = Number(match[2]),
+        runAttempt = Number(match[3]);
+      if (
+        check.head_sha !== source.commit ||
+        ![check.id, runId, runAttempt].every(
+          (value) => Number.isSafeInteger(value) && value > 0,
+        )
+      )
+        throw new Error("Recovery check provider identity drift");
+      const run = await request(
+        `${base}/actions/runs/${runId}/attempts/${runAttempt}`,
+      );
+      if (
+        run.id !== runId ||
+        run.run_attempt !== runAttempt ||
+        run.repository?.full_name !== repository
+      )
+        throw new Error("Recovery check execution identity drift");
+      if (["workflow_dispatch", "repository_dispatch"].includes(run.event))
+        renames.push({
+          id: check.id,
+          externalId: check.external_id,
+          sourceHead: source.commit,
+          runId,
+          runAttempt,
+          name: RECOVERY_CHECK,
+        });
+      else if (
+        [
+          "push",
+          "pull_request",
+          "pull_request_review",
+          "pull_request_target",
+        ].includes(run.event) &&
+        run.head_sha === source.commit
+      )
+        eligible.push({
+          id: check.id,
+          runId,
+          runAttempt,
+          conclusion: check.conclusion,
+        });
+    }
+    if (result.check_runs.length < 100) return { renames, eligible };
+  }
+  throw new Error("Recovery check inventory exceeds its complete-read bound");
+}
+
+// The archive reference is already validated against the current attempt. A
+// build result is still re-read from the provider before it can admit delivery.
+export async function pipelineBuildEvidence(session, host) {
+  const observed = await session.journal.read();
+  const current = observed.history.at(-1);
+  const phase = current.phases.build;
+  if (phase?.payload.state !== "success") return null;
+  const references = phase.payload.materials.filter(
+    (material) =>
+      material.id.startsWith("build/provider-") ||
+      material.id.startsWith("build/qualified-"),
+  );
+  if (references.length !== 1)
+    throw new Error("Pipeline build requires one retained provider receipt");
+  const retained = await host.materialStore(session).read(references[0]);
+  let { run } = await host.runs.read(retained.runId, retained.runAttempt);
+  if (run.status !== "completed" && run.id !== host.runId)
+    run = await host.runs.completed(retained.runId, retained.runAttempt);
+  if (retained.schema === PIPELINE_BUILD_QUALIFICATION) {
+    const source = await host.source.source(
+      current.generation.source.commit,
+      current.generation.source.configPath,
+    );
+    if (
+      recordDigest(source.identity) !== recordDigest(current.generation.source)
+    )
+      throw new Error("Recovered build source changed during qualification");
+    await verifyPipelineBuildQualification(
+      retained,
+      source.identity,
+      pipelinePlatforms(source.plan).map(({ platform }) => platform),
+      host.runs,
+    );
+  } else {
+    const verified = await host.runs.build(
+      retained.runId,
+      retained.runAttempt,
+      current.generation.source,
+      retained.jobs.map(
+        (job) => job.name.match(/Build product \(([^)]+)\)$/u)?.[1],
+      ),
+    );
+    if (recordDigest(verified) !== recordDigest(retained))
+      throw new Error("Retained product build provider result changed");
+  }
+  return {
+    run,
+    readback: retained,
+    sourceHead: current.generation.source.commit,
+    outcome: retained.outcome,
+  };
+}
+
+export async function publishPipelineBuildCheck(
+  context,
+  readback,
+  request,
+  repository,
+) {
+  if (
+    context.source.repository !== repository ||
+    recordDigest(context.source) !== recordDigest(readback.source) ||
+    context.runId !== readback.runId ||
+    context.runAttempt !== readback.runAttempt
+  )
+    throw new Error(
+      "Product check source differs from independently verified build",
+    );
+  const externalId = `buildchain:${context.attempt}:${context.runId}:${context.runAttempt}`;
+  const recovered = readback.schema === PIPELINE_BUILD_QUALIFICATION;
+  let checkName = recovered ? RECOVERY_CHECK : "check";
+  const output = {
+    title: recovered
+      ? "Buildchain recovered product verification"
+      : "Buildchain product verification",
+    summary: `Exact product jobs: ${readback.root}\nAttempt: ${context.attempt}`,
+  };
+  if (recovered) {
+    const checks = await observePipelineBuildChecks(
+      context.source,
+      request,
+      repository,
+    );
+    for (const change of checks.renames)
+      await request(`/repos/${repository}/check-runs/${change.id}`, {
+        method: "PATCH",
+        body: { name: change.name },
+      });
+    const original = checks.eligible.find((check) =>
+      readback.segments.some(
+        (segment) =>
+          segment.readback.runId === check.runId &&
+          segment.readback.runAttempt === check.runAttempt,
+      ),
+    );
+    // A complete replacement has no reusable original check to project onto.
+    // Retain that failed execution and publish this independently qualified
+    // aggregate as the required check. Protected landing still requalifies it
+    // and publishes the App-bound commit status before queue admission.
+    if (!original) checkName = "check";
+    // Keep the eligible normal-event check identity. Only a fully requalified
+    // source aggregate can repair its failed projection; original runs and
+    // immutable build receipts still retain their original failure outcomes.
+    if (
+      original &&
+      original.conclusion !== "success" &&
+      readback.outcome === "success"
+    )
+      await request(`/repos/${repository}/check-runs/${original.id}`, {
+        method: "PATCH",
+        body: { status: "completed", conclusion: "success", output },
+      });
+  }
+  return request(`/repos/${repository}/check-runs`, {
+    method: "POST",
+    body: {
+      name: checkName,
+      head_sha: context.source.commit,
+      external_id: externalId,
+      status: "completed",
+      conclusion: readback.outcome === "success" ? "success" : "failure",
+      output,
+      details_url: `https://github.com/${repository}/actions/runs/${context.runId}/attempts/${context.runAttempt}`,
+    },
+  });
+}

package/packages/core/workflow/pipeline/build-qualification.js

@@ -0,0 +1,145 @@
+import {
+  recordDigest,
+  validateRuntime,
+} from "../../release/discussion/envelope.js";
+import { object } from "../../consumer/contract/shape.js";
+
+export const PIPELINE_BUILD_QUALIFICATION =
+  "buildchain.pipeline-build-qualification/v1";
+
+export function buildReadbackPlatforms(readback) {
+  const { root, ...body } = readback;
+  if (
+    body.schema !== "buildchain.pipeline-build-readback/v1" ||
+    root !== recordDigest(body) ||
+    !Array.isArray(body.jobs) ||
+    !body.jobs.length
+  )
+    throw new Error(
+      "Build qualification requires immutable provider job readback",
+    );
+  const platforms = body.jobs.map(
+    (job) => job.name?.match(/Build product \(([^)]+)\)$/u)?.[1],
+  );
+  if (
+    platforms.some((platform) => !platform) ||
+    new Set(platforms).size !== platforms.length
+  )
+    throw new Error(
+      "Provider build has ambiguous or unsupported platform jobs",
+    );
+  return platforms;
+}
+
+function validateBuildInventory(platforms, segments, runId, runAttempt) {
+  if (
+    !Array.isArray(platforms) ||
+    !platforms.length ||
+    platforms.length > 5 ||
+    new Set(platforms).size !== platforms.length ||
+    !Array.isArray(segments) ||
+    !segments.length ||
+    segments.length > 5 ||
+    ![runId, runAttempt].every(
+      (value) => Number.isSafeInteger(value) && value > 0,
+    )
+  )
+    throw new Error(
+      "Build qualification requires bounded exact platform and execution coordinates",
+    );
+}
+
+export function qualifyPipelineBuild({
+  source,
+  platforms,
+  segments,
+  runId,
+  runAttempt,
+}) {
+  validateBuildInventory(platforms, segments, runId, runAttempt);
+  const selected = [];
+  let successful = true;
+  for (const segment of segments) {
+    object(segment, ["readback", "platforms", "runtime"]);
+    validateRuntime(segment.runtime);
+    if (
+      segment.runtime.repository !== "kungfu-systems/buildchain" ||
+      !Array.isArray(segment.platforms) ||
+      !segment.platforms.length ||
+      recordDigest(segment.readback.source) !== recordDigest(source)
+    )
+      throw new Error(
+        "Build segment changed its exact source or runtime repository",
+      );
+    const available = buildReadbackPlatforms(segment.readback);
+    for (const platform of segment.platforms) {
+      const index = available.indexOf(platform),
+        job = segment.readback.jobs[index];
+      if (
+        index < 0 ||
+        !platforms.includes(platform) ||
+        selected.includes(platform) ||
+        job.status !== "completed" ||
+        !job.conclusion ||
+        job.run_id !== segment.readback.runId ||
+        job.run_attempt !== segment.readback.runAttempt ||
+        !Number.isSafeInteger(job.id) ||
+        job.id < 1
+      )
+        throw new Error(
+          "Build segments omitted, duplicated or changed a real platform execution",
+        );
+      selected.push(platform);
+      successful &&= job.conclusion === "success";
+    }
+  }
+  if (selected.length !== platforms.length)
+    throw new Error("Build qualification is missing declared platforms");
+  const body = {
+    schema: PIPELINE_BUILD_QUALIFICATION,
+    source,
+    platforms: [...platforms].sort(),
+    runId,
+    runAttempt,
+    segments: structuredClone(segments),
+    outcome: successful ? "success" : "failure",
+  };
+  return { ...body, root: recordDigest(body) };
+}
+
+export async function verifyPipelineBuildQualification(
+  value,
+  source,
+  platforms,
+  runs,
+) {
+  object(value, [
+    "schema",
+    "source",
+    "platforms",
+    "runId",
+    "runAttempt",
+    "segments",
+    "outcome",
+    "root",
+  ]);
+  const expected = qualifyPipelineBuild({ ...value, source, platforms });
+  if (recordDigest(value) !== recordDigest(expected))
+    throw new Error(
+      "Retained build qualification changed its source or exact platform inventory",
+    );
+  for (const segment of value.segments) {
+    const old = segment.readback;
+    const fresh = await runs.build(
+      old.runId,
+      old.runAttempt,
+      source,
+      buildReadbackPlatforms(old),
+    );
+    if (recordDigest(fresh) !== recordDigest(old))
+      throw new Error(
+        "A recovered platform result changed during provider requalification",
+      );
+  }
+  return value;
+}