@kungfu-tech/buildchain 4.1.3-alpha.2 → 4.1.3-alpha.3

package/packages/core/publication/pipeline/stable-products.js

@@ -0,0 +1,317 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { readPipelineReleaseEvidence } from "../../providers/github/pipeline-release-evidence.js";
+import { readPipelineCaller } from "../../providers/github/pipeline-run-entry.js";
+import { verifyPipelinePublicationPlan } from "./plan.js";
+import {
+  verifyRootedPublication,
+  pipelineReleaseDocuments,
+} from "./documents.js";
+import { verifyPipelineSigning } from "./signing.js";
+import { reobservePublicationBuild } from "./recovery-build-readback.js";
+import { writeImmutablePublicationFile } from "./files.js";
+
+function assertPublishedPlan(stablePlan, source, values) {
+  const { plan, qualification: qualified, release } = values;
+  verifyPipelinePublicationPlan(plan);
+  if (
+    plan.evidenceVersion !== 1 ||
+    plan.channel !== "alpha" ||
+    plan.version !== stablePlan.candidateVersion ||
+    plan.tag !== source.candidate.tag ||
+    plan.contractRoot !== stablePlan.contractRoot ||
+    plan.route.operation !== "alpha" ||
+    plan.route.to !== stablePlan.route.from ||
+    plan.route.from !== stablePlan.developmentBranch ||
+    recordDigest(plan.outputs) !== recordDigest(stablePlan.outputs) ||
+    recordDigest(qualified.source) !== recordDigest(source.source) ||
+    recordDigest(release.source) !== recordDigest(source.source)
+  )
+    throw new Error(
+      "Published product evidence differs from the exact Alpha contract or source",
+    );
+  if (
+    plan.publisher.repository !== "kungfu-systems/buildchain" ||
+    plan.publisher.workflow !==
+      ".github/workflows/.release-pipeline-products.yml" ||
+    plan.publisher.job !== "apply" ||
+    !/^[0-9a-f]{40}$/u.test(plan.publisher.workflowSha || "") ||
+    plan.runtime.repository !== "kungfu-systems/buildchain"
+  )
+    throw new Error(
+      "Published product evidence requires the central publisher",
+    );
+  const issued = Date.parse(qualified.qualification?.issuedAt);
+  if (
+    !Number.isFinite(issued) ||
+    issued > Date.parse(source.candidate.publishedAt)
+  )
+    throw new Error(
+      "Published product qualification cannot postdate its Alpha release",
+    );
+}
+
+function buildLeaves(build) {
+  const pending = [build],
+    leaves = [];
+  let visited = 0;
+  while (pending.length) {
+    if (++visited > 100)
+      throw new Error("Published product build lineage exceeds its bound");
+    const value = pending.pop();
+    verifyRootedPublication(value, value.schema);
+    if (value.schema === "buildchain.pipeline-publication-build-readback/v1")
+      leaves.push(value);
+    else if (
+      value.schema === "buildchain.pipeline-publication-requalification/v1"
+    )
+      pending.push(value.predecessorBuild);
+    else if (
+      value.schema ===
+        "buildchain.pipeline-publication-build-qualification/v1" &&
+      Array.isArray(value.segments) &&
+      value.segments.length &&
+      value.segments.length <= 100
+    )
+      pending.push(...value.segments.map(({ build: segment }) => segment));
+    else
+      throw new Error(
+        "Published product build lineage has an unsupported producer",
+      );
+  }
+  return leaves;
+}
+
+function assertBuildInventory(plan, qualified) {
+  const expected = [
+    ...new Set(plan.outputs.map(({ platform }) => platform)),
+  ].sort();
+  const descriptors = qualified.artifacts
+    .map(
+      ({
+        file,
+        size,
+        digest,
+        package: pkg,
+        manifestRoot,
+        providerArtifactId,
+        ...value
+      }) => value,
+    )
+    .sort((a, b) => a.id.localeCompare(b.id));
+  if (recordDigest(descriptors) !== recordDigest(plan.outputs))
+    throw new Error(
+      "Published product evidence must cover every declared output exactly",
+    );
+  const leaves = buildLeaves(qualified.build),
+    platforms = [],
+    jobs = [];
+  for (const build of leaves) {
+    if (
+      build.outcome !== "success" ||
+      !Array.isArray(build.platforms) ||
+      !Array.isArray(build.jobs) ||
+      build.platforms.length !== build.jobs.length ||
+      !build.platforms.length ||
+      recordDigest(build.source) !== recordDigest(qualified.source)
+    )
+      throw new Error(
+        "Published product evidence lacks complete successful platform builds",
+      );
+    for (const [index, platform] of build.platforms.entries()) {
+      const job = build.jobs[index],
+        name = `Build publication (${platform})`;
+      if (
+        job.status !== "completed" ||
+        job.conclusion !== "success" ||
+        job.run_id !== build.runId ||
+        job.run_attempt !== build.runAttempt ||
+        !(job.name === name || job.name.endsWith(` / ${name}`))
+      )
+        throw new Error(
+          "Published product build job does not match its platform or attempt",
+        );
+      jobs.push(job);
+    }
+    platforms.push(...build.platforms);
+  }
+  if (
+    recordDigest(platforms.sort()) !== recordDigest(expected) ||
+    new Set(jobs.map(({ id }) => id)).size !== jobs.length
+  )
+    throw new Error(
+      "Published product jobs omit or repeat a declared platform",
+    );
+  return jobs;
+}
+
+async function signingRun(plan, qualified, host) {
+  const { run, jobs } = await host.runs.read(
+    qualified.build.runId,
+    qualified.build.runAttempt,
+  );
+  if (run.head_sha !== qualified.build.providerSource)
+    throw new Error("Published product signing run changed its source");
+  await readPipelineCaller(
+    run,
+    qualified.source.configPath,
+    host.request,
+    host.repository,
+  );
+  const definitions = (run.referenced_workflows || []).filter((value) =>
+    value.path?.startsWith(
+      `${plan.publisher.repository}/${plan.publisher.workflow}@`,
+    ),
+  );
+  const selected = jobs.filter(
+    (job) =>
+      job.name === "Qualify and sign products" ||
+      job.name.endsWith(" / Qualify and sign products"),
+  );
+  if (
+    definitions.length !== 1 ||
+    definitions[0].sha !== plan.publisher.workflowSha ||
+    selected.length !== 1 ||
+    selected[0].run_id !== qualified.build.runId ||
+    selected[0].run_attempt !== qualified.build.runAttempt ||
+    selected[0].status !== "completed" ||
+    selected[0].conclusion !== "success"
+  )
+    throw new Error(
+      "Published product signature lacks its exact successful provider job",
+    );
+  return selected[0];
+}
+
+function completionTime(jobs, qualified, candidate) {
+  const values = jobs.map((job) => Date.parse(job.completed_at));
+  const issued = Date.parse(qualified.qualification.issuedAt);
+  if (
+    values.some((value) => !Number.isFinite(value)) ||
+    values.slice(0, -1).some((value) => value > issued) ||
+    values.at(-1) < issued ||
+    Math.max(...values) > Date.parse(candidate.publishedAt)
+  )
+    throw new Error(
+      "Published product job timing disagrees with qualification or release",
+    );
+  return new Date(Math.max(...values)).toISOString();
+}
+
+function verifyPublishedDocuments(values, bundle, directory, host, execute) {
+  const {
+    plan,
+    qualification: qualified,
+    capsules,
+    release,
+    invocation,
+  } = values;
+  const materialization = release.versionMaterialization;
+  const signing = verifyPipelineSigning({
+    plan,
+    materialization,
+    qualified,
+    bundlePath: writeImmutablePublicationFile(
+      path.join(directory, "attestation.json"),
+      bundle,
+    ),
+    directory: path.join(directory, "signature"),
+    token: host.token,
+    // Historical evidence is checked at issue time. It never supplies fresh
+    // Stable publisher admission or extends the original receipt's lifetime.
+    evaluatedAt: qualified.qualification.issuedAt,
+    ...(execute ? { execute } : {}),
+  });
+  const expected = pipelineReleaseDocuments({
+    plan,
+    materialization,
+    qualified,
+    capsules,
+    signing,
+    evaluatedAt: qualified.qualification.issuedAt,
+  });
+  if (
+    recordDigest(expected.passport) !== recordDigest(release) ||
+    recordDigest(expected.invocation.invocation) !== recordDigest(invocation)
+  )
+    throw new Error(
+      "Published Passport or invocation differs from verified product evidence",
+    );
+  return signing;
+}
+
+export async function readPipelineStableProducts(
+  stablePlan,
+  source,
+  host,
+  { execute } = {},
+) {
+  verifyPipelinePublicationPlan(stablePlan);
+  verifyRootedPublication(source, "buildchain.pipeline-stable-source/v1");
+  if (
+    host.repository !== stablePlan.source.repository ||
+    source.planRoot !== stablePlan.root ||
+    source.contractRoot !== stablePlan.contractRoot ||
+    source.source.repository !== host.repository ||
+    recordDigest(source.source) !== recordDigest(stablePlan.intentSource) ||
+    source.candidate.sha !== source.source.commit ||
+    source.candidate.tree !== source.source.tree ||
+    source.candidate.tag !== `v${stablePlan.candidateVersion}` ||
+    !Number.isFinite(Date.parse(source.candidate.publishedAt)) ||
+    stablePlan.channel !== "stable"
+  )
+    throw new Error(
+      "Stable product collection changed its admitted source or repository",
+    );
+  const evidence = await readPipelineReleaseEvidence(host, source.candidate);
+  if (evidence.status === "missing") return evidence;
+  assertPublishedPlan(stablePlan, source, evidence.values);
+  const { plan, qualification: qualified } = evidence.values;
+  const jobs = assertBuildInventory(plan, qualified);
+  const directory = fs.mkdtempSync(
+    path.join(fs.realpathSync(os.tmpdir()), "buildchain-stable-products-"),
+  );
+  try {
+    const signing = verifyPublishedDocuments(
+      evidence.values,
+      evidence.bundle,
+      directory,
+      host,
+      execute,
+    );
+    await reobservePublicationBuild(qualified.build, qualified.source, host);
+    const signer = await signingRun(plan, qualified, host);
+    const completedAt = completionTime(
+      [...jobs, signer],
+      qualified,
+      source.candidate,
+    );
+    const body = {
+      schema: "buildchain.pipeline-stable-products/v1",
+      planRoot: stablePlan.root,
+      sourceRoot: source.root,
+      alphaPlanRoot: plan.root,
+      qualificationRoot: qualified.root,
+      signing,
+      signer,
+      buildRoot: qualified.build.root,
+      assets: evidence.assets,
+      canary: {
+        id: "product-build",
+        source: "release-candidate",
+        status: "success",
+        repository: host.repository,
+        candidateSha: source.candidate.sha,
+        completedAt,
+        attestor: "github-actions[bot]",
+        runtimeRef: plan.runtime.commit,
+        evidenceUrl: `https://github.com/${host.repository}/actions/runs/${qualified.build.runId}/attempts/${qualified.build.runAttempt}`,
+      },
+    };
+    return { ...body, root: recordDigest(body) };
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+}

package/packages/core/publication/pipeline/stable-wait.js

@@ -0,0 +1,170 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { readBusinessAttempt } from "../../workflow/attempt/reader.js";
+import { verifyRootedPublication } from "./documents.js";
+import { verifyPipelinePublicationPlan } from "./plan.js";
+import { assertPipelineStableQualification } from "./stable.js";
+
+const TIMERS = new Set(["stable.minimum_interval", "stable.canary_soak"]);
+const MAX_WAIT = 15 * 60 * 1000;
+
+export function planPipelineStableWait(
+  plan,
+  eligibility,
+  { attempt, generation, phase },
+) {
+  verifyPipelinePublicationPlan(plan);
+  verifyRootedPublication(
+    eligibility,
+    "buildchain.pipeline-stable-eligibility/v1",
+  );
+  if (
+    plan.channel !== "stable" ||
+    !plan.stablePolicy ||
+    eligibility.planRoot !== plan.root ||
+    generation !== plan.generation ||
+    !/^attempt-[0-9a-f]{64}$/u.test(attempt || "") ||
+    !["publish", "distribution", "next-development"].includes(phase)
+  )
+    throw new Error("Stable wait changed its admitted publication coordinates");
+  const failed = eligibility.report.checks.filter(
+    (check) => check.status !== "pass",
+  );
+  if (
+    eligibility.report.ok ||
+    !failed.length ||
+    failed.some((check) => !TIMERS.has(check.id))
+  )
+    return null;
+  const times = failed.map((check) => {
+    const interval = check.id === "stable.minimum_interval";
+    const expected = interval
+      ? plan.stablePolicy.minimum_interval_seconds
+      : plan.stablePolicy.minimum_soak_seconds;
+    const start = Date.parse(
+      interval
+        ? check.details.previousPublishedAt
+        : check.details.soakStartedAt,
+    );
+    if (
+      check.details.requiredSeconds !== expected ||
+      !Number.isSafeInteger(expected) ||
+      expected < 0
+    )
+      throw new Error("Stable wait timer differs from the source-bound policy");
+    return start + expected * 1000;
+  });
+  const ready = Math.max(...times);
+  const evaluatedAt = Date.parse(eligibility.evaluatedAt);
+  if (
+    !Number.isFinite(evaluatedAt) ||
+    !Number.isFinite(ready) ||
+    ready <= evaluatedAt ||
+    ready > 8640000000000000
+  )
+    throw new Error("Stable wait has no bounded future recheck timestamp");
+  const body = {
+    schema: "buildchain.pipeline-stable-wait/v1",
+    attempt,
+    generation,
+    phase,
+    sourceRoot: recordDigest(plan.intentSource),
+    planRoot: plan.root,
+    eligibilityRoot: eligibility.root,
+    notBefore: new Date(ready).toISOString(),
+  };
+  return { ...body, root: recordDigest(body) };
+}
+
+export async function preparePipelineStableQualification(
+  plan,
+  host,
+  journal,
+  coordinates,
+) {
+  try {
+    const eligibility = await assertPipelineStableQualification(plan, host);
+    if (eligibility) {
+      await journal.fence();
+      await journal.record("publication/stable-eligibility", eligibility, {
+        phase: coordinates.phase,
+      });
+    }
+    return null;
+  } catch (error) {
+    if (!error.eligibility) throw error;
+    const wait = planPipelineStableWait(plan, error.eligibility, coordinates);
+    if (!wait) throw error;
+    await journal.fence();
+    const options = { phase: coordinates.phase, state: "waiting" };
+    await journal.record(
+      "publication/stable-eligibility",
+      error.eligibility,
+      options,
+    );
+    await journal.record("publication/stable-wait", wait, options);
+    return wait;
+  }
+}
+
+export async function retainedPipelineStableWait(observed, host) {
+  const current = observed.history.at(-1);
+  if (observed.intent.repository !== host.repository)
+    throw new Error("Stable wait crossed the native repository boundary");
+  const phase = observed.missing[0];
+  if (
+    !["publish", "distribution", "next-development"].includes(phase) ||
+    current.phases[phase]?.payload.state !== "waiting"
+  )
+    return null;
+  const references = current.phases[phase].payload.materials.filter((item) =>
+    item.id.startsWith("publication/stable-wait/"),
+  );
+  if (references.length !== 1) return null;
+  const session = { intent: observed.intent, observed };
+  const retained = await host.materialStore(session).read(references[0]);
+  verifyRootedPublication(retained, "buildchain.pipeline-stable-wait/v1");
+  if (
+    observed.attempt !== retained.attempt ||
+    observed.generation !== retained.generation ||
+    recordDigest(current.generation.source) !== retained.sourceRoot ||
+    phase !== retained.phase ||
+    !Number.isFinite(Date.parse(retained.notBefore))
+  )
+    throw new Error(
+      "Retained stable wait changed its native publication coordinates",
+    );
+  return retained;
+}
+
+async function activeWait(wait, host) {
+  const loaded = await host.index.resolve(wait.attempt);
+  const observed = readBusinessAttempt(loaded.snapshot);
+  const retained = await retainedPipelineStableWait(observed, host);
+  if (!retained) return false;
+  return recordDigest(retained) === recordDigest(wait);
+}
+
+// This node runs outside the publication concurrency group. It only waits and
+// wakes the normal entry; every subsequent publication re-collects qualification.
+export async function wakePipelineStableWait(
+  wait,
+  host,
+  {
+    now = () => Date.now(),
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  } = {},
+) {
+  verifyRootedPublication(wait, "buildchain.pipeline-stable-wait/v1");
+  const target = Date.parse(wait.notBefore),
+    started = now();
+  if (!Number.isFinite(target) || !Number.isFinite(started))
+    throw new Error("Stable wake requires a finite retained timer");
+  const deadline = Math.min(target, started + MAX_WAIT);
+  while (now() < deadline) {
+    if (!(await activeWait(wait, host))) return { status: "obsolete" };
+    await sleep(Math.min(30000, deadline - now()));
+  }
+  if (!(await activeWait(wait, host))) return { status: "obsolete" };
+  await host.wake(wait.attempt);
+  return { status: "woken", attempt: wait.attempt, notBefore: wait.notBefore };
+}

package/packages/core/publication/pipeline/stable.js

@@ -0,0 +1,82 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { evaluateStableReleaseGate } from "../../release/stable-release-gate.js";
+import { readPipelineStableSource } from "../../providers/github/pipeline-stable-source.js";
+import { verifyPipelinePublicationPlan } from "./plan.js";
+import { readPipelineStableProducts } from "./stable-products.js";
+import { readPipelineStableEntry } from "./stable-entry.js";
+
+function stablePolicy(plan) {
+  const value = plan.stablePolicy;
+  const requiredCanaries = [
+    {
+      id: "product-build",
+      source: "release-candidate",
+      context: "",
+      allowedAttestors: [],
+    },
+  ];
+  if (value.require_published_entry)
+    requiredCanaries.push({
+      id: "published-entry",
+      source: "public-build",
+      context: "",
+      allowedAttestors: ["github-actions[bot]"],
+    });
+  return {
+    enabled: true,
+    minimumStableIntervalSeconds: value.minimum_interval_seconds,
+    minimumCanarySoakSeconds: value.minimum_soak_seconds,
+    productPathPrefixes: value.product_paths,
+    requiredCanaries,
+  };
+}
+
+export async function assertPipelineStableQualification(
+  plan,
+  host,
+  { now = new Date().toISOString() } = {},
+) {
+  verifyPipelinePublicationPlan(plan);
+  if (plan.channel !== "stable" || !plan.stablePolicy) return null;
+  const source = await readPipelineStableSource(plan, host);
+  const products = await readPipelineStableProducts(plan, source, host);
+  const entry =
+    plan.stablePolicy.require_published_entry && products.canary
+      ? await readPipelineStableEntry(plan, source, host)
+      : { status: "not-evaluated" };
+  if (
+    products.canary &&
+    recordDigest(await readPipelineStableSource(plan, host)) !==
+      recordDigest(source)
+  )
+    throw new Error("Stable source facts changed during product qualification");
+  const report = evaluateStableReleaseGate({
+    policy: stablePolicy(plan),
+    channel: "release",
+    now,
+    candidate: source.candidate,
+    previousStable: source.previousStable || undefined,
+    impact: source.impact.value,
+    changedPaths: source.changedPaths,
+    canaries: [products.canary, entry.canary].filter(Boolean),
+  });
+  report.previousStable ??= null;
+  const body = {
+    schema: "buildchain.pipeline-stable-eligibility/v1",
+    planRoot: plan.root,
+    source,
+    products,
+    entry,
+    evaluatedAt: now,
+    report,
+  };
+  const eligibility = { ...body, root: recordDigest(body) };
+  if (!report.ok)
+    throw Object.assign(
+      new Error(
+        `Stable pipeline qualification blocked: ${report.summary.failedChecks.join(", ")}`,
+      ),
+      { eligibility },
+    );
+  return eligibility;
+}

package/packages/core/publication/pipeline/version-actions.js

@@ -0,0 +1,93 @@
+import path from "node:path";
+import { pipelineHost } from "../../workflow/pipeline/host.js";
+import { githubJsonClient } from "../../providers/github/json-client.js";
+import { githubPipelineVersionArtifacts } from "../../providers/github/pipeline-version-artifacts.js";
+import { buildPipelineVersionMaterial } from "./version-build.js";
+import { qualifyPipelineVersionContext } from "./version-context.js";
+import { preparePipelinePublication } from "./prepare.js";
+import { settlePipelinePublication } from "./settle.js";
+
+const contextInput = (core) =>
+  JSON.parse(core.getInput("context", { required: true }));
+const directory = (env) =>
+  path.join(env.GITHUB_WORKSPACE, ".buildchain/version-material");
+
+export async function buildPipelineVersionAction(core, env) {
+  const context = contextInput(core);
+  if (
+    context.schema !== "buildchain.pipeline-version-context/v1" ||
+    context.runId !== Number(env.GITHUB_RUN_ID) ||
+    context.runAttempt !== Number(env.GITHUB_RUN_ATTEMPT)
+  )
+    throw new Error(
+      "Version build requires its exact provider execution context",
+    );
+  const result = await buildPipelineVersionMaterial({
+    cwd: path.join(env.GITHUB_WORKSPACE, ".buildchain/product"),
+    preparation: context.preparation,
+    platform: core.getInput("platform", { required: true }),
+    environment: env,
+  });
+  await githubPipelineVersionArtifacts({}).upload(
+    context,
+    result,
+    directory(env),
+  );
+}
+
+export async function materializePipelinePublicationAction(core, env) {
+  const context = contextInput(core);
+  const operation = core.getInput("operation", { required: true });
+  let result = { operation, context };
+  if (operation === "regenerate") {
+    if (context.preparation.purpose !== "publication")
+      throw new Error(
+        "Publication materialization received a different version purpose",
+      );
+    const host = await pipelineHost(core, env, "Materialize publication");
+    await qualifyPipelineVersionContext(context, host, directory(env));
+    result = await preparePipelinePublication(
+      context.attempt,
+      context.definitionSha,
+      host,
+    );
+    if (result.operation === "regenerate")
+      throw new Error(
+        "Qualified version preparation did not materialize its source",
+      );
+  }
+  core.setOutput("operation", result.operation);
+  core.setOutput("stable-wait", result.wait ? JSON.stringify(result.wait) : "");
+  core.setOutput("context", JSON.stringify(result.context || {}));
+  core.setOutput(
+    "matrix",
+    JSON.stringify({ include: result.context?.platforms || [] }),
+  );
+}
+
+export async function materializePipelineDevelopmentAction(core, env) {
+  const context = contextInput(core);
+  if (context.preparation.purpose !== "development")
+    throw new Error(
+      "Development materialization received a different version purpose",
+    );
+  const host = await pipelineHost(core, env, "Materialize next development");
+  const prToken = core.getInput("pr-token", { required: true });
+  if (prToken !== host.token)
+    host.pullRequests = githubJsonClient({
+      token: prToken,
+      userAgent: "buildchain-next-development",
+    });
+  await qualifyPipelineVersionContext(context, host, directory(env));
+  const result = await settlePipelinePublication(
+    context.publication,
+    host,
+    directory(env),
+    env,
+  );
+  if (result.versionContext)
+    throw new Error(
+      "Qualified development preparation did not materialize its source",
+    );
+  core.info(result.reason);
+}