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

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);
+}

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

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  inspectPipelineSource,
+  buildPipelineProducts,
+} from "../../workflow/pipeline/build.js";
+import { verifyPipelineVersionPreparation } from "./version-preparation.js";
+import { guardPipelineVersionSource } from "./version-source-guard.js";
+import { materializePipelineVersion } from "./version.js";
+import {
+  pipelineVersionMaterialPaths,
+  pipelineVersionRegenerationResult,
+  collectPipelineVersionMaterial,
+} from "./version-regeneration.js";
+
+function materialFiles(cwd, paths) {
+  return Object.fromEntries(
+    paths.map((file) => {
+      const absolute = path.resolve(cwd, file);
+      const stat = fs.lstatSync(absolute);
+      if (
+        !stat.isFile() ||
+        stat.size > 4 * 1024 * 1024 ||
+        fs.realpathSync(absolute) !== absolute
+      )
+        throw new Error(
+          "Version preparation requires bounded regular source files without symlinks",
+        );
+      const bytes = fs.readFileSync(absolute);
+      const content = bytes.toString("utf8");
+      if (!Buffer.from(content).equals(bytes))
+        throw new Error("Version preparation cannot rewrite non-UTF8 material");
+      return [file, content];
+    }),
+  );
+}
+
+function trackedModes(cwd, paths) {
+  const entries = execFileSync(
+    "git",
+    ["-C", cwd, "ls-files", "--stage", "-z", "--", ...paths],
+    { encoding: "utf8" },
+  )
+    .split("\0")
+    .filter(Boolean);
+  const modes = Object.fromEntries(
+    entries.map((entry) => {
+      const match = /^(100644|100755) [0-9a-f]{40} 0\t(.+)$/u.exec(entry);
+      if (!match)
+        throw new Error("Version preparation requires tracked regular files");
+      return [match[2], match[1]];
+    }),
+  );
+  if (recordDigest(Object.keys(modes).sort()) !== recordDigest(paths))
+    throw new Error(
+      "Version preparation material is absent from the source tree",
+    );
+  return modes;
+}
+
+function assertPreparedDiff(cwd, paths, modes) {
+  const changes = execFileSync(
+    "git",
+    ["-C", cwd, "diff", "HEAD", "--name-status", "-z"],
+    { encoding: "utf8" },
+  )
+    .split("\0")
+    .filter(Boolean);
+  for (let index = 0; index < changes.length; index += 2)
+    if (changes[index] !== "M" || !paths.includes(changes[index + 1]))
+      throw new Error(
+        "Version product commands changed undeclared source paths",
+      );
+  if (recordDigest(trackedModes(cwd, paths)) !== recordDigest(modes))
+    throw new Error("Version product commands changed tracked file modes");
+  const raw = execFileSync("git", ["-C", cwd, "diff", "HEAD", "--summary"], {
+    encoding: "utf8",
+  });
+  if (raw.trim())
+    throw new Error(
+      "Version product commands changed source file kinds or modes",
+    );
+}
+
+export async function buildPipelineVersionMaterial({
+  cwd,
+  preparation,
+  platform,
+  environment = process.env,
+}) {
+  cwd = fs.realpathSync(cwd);
+  const contract = inspectPipelineSource(cwd, preparation.source);
+  verifyPipelineVersionPreparation(preparation, contract);
+  if (environment.BUILDCHAIN_RUNTIME_SHA !== preparation.runtime.sha)
+    throw new Error(
+      "Version preparation is not using its admitted execution runtime",
+    );
+  const paths = pipelineVersionMaterialPaths(
+    preparation.versionPolicy,
+    preparation.source.configPath,
+  );
+  const modes = trackedModes(cwd, paths);
+  const guard = guardPipelineVersionSource(cwd, preparation.source, paths);
+  const before = materialFiles(cwd, paths);
+  const material = materializePipelineVersion(
+    preparation.versionPolicy,
+    before,
+    preparation.version,
+  );
+  // Product code runs only in this credentialless job. The provider writer
+  // independently observes job completion and verifies these exact bytes.
+  for (const { path: file, content } of material.changes)
+    fs.writeFileSync(path.join(cwd, file), content);
+  await buildPipelineProducts({ cwd, plan: contract, platform, environment });
+  guard();
+  assertPreparedDiff(cwd, paths, modes);
+  const result = pipelineVersionRegenerationResult(
+    preparation,
+    platform,
+    materialFiles(cwd, paths),
+  );
+  collectPipelineVersionMaterial(
+    { ...preparation, platforms: [platform] },
+    before,
+    [result],
+  );
+  return result;
+}

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

@@ -0,0 +1,143 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { resumePipelineSession } from "../../workflow/pipeline/session.js";
+import { pipelinePlatforms } from "../../workflow/pipeline/platforms.js";
+import { githubPipelineVersion } from "../../providers/github/pipeline-version.js";
+import { githubPipelineVersionArtifacts } from "../../providers/github/pipeline-version-artifacts.js";
+import { pipelinePublicationJournal } from "./journal.js";
+import {
+  planPipelineVersionPreparation,
+  verifyPipelineVersionPreparation,
+} from "./version-preparation.js";
+import { collectPipelineVersionMaterial } from "./version-regeneration.js";
+
+const phaseOf = (purpose) =>
+  purpose === "publication" ? "publish" : "next-development";
+
+export async function preparePipelineVersionContext(
+  parent,
+  purpose,
+  publication,
+  host,
+  journal,
+  definitionSha,
+) {
+  const admitted = await host.source.source(
+    parent.source.commit,
+    parent.source.configPath,
+  );
+  if (
+    recordDigest(admitted.identity) !== recordDigest(parent.source) ||
+    recordDigest(admitted.plan) !== publication.plan.contractRoot
+  )
+    throw new Error(
+      "Version preparation source or contract differs from its retained parent",
+    );
+  const preparation = planPipelineVersionPreparation({
+    attempt: publication.attempt,
+    generation: publication.generation,
+    source: parent.source,
+    contract: admitted.plan,
+    version: parent.version,
+    runtime: host.runtime,
+    purpose,
+    parentRoot: parent.root,
+  });
+  const context = {
+    schema: "buildchain.pipeline-version-context/v1",
+    attempt: publication.attempt,
+    generation: publication.generation,
+    preparation,
+    definitionSha,
+    runId: host.runId,
+    runAttempt: host.runAttempt,
+    platforms: pipelinePlatforms(admitted.plan),
+    publication,
+  };
+  await journal.record(`publication/version-${purpose}-context`, context, {
+    phase: phaseOf(purpose),
+  });
+  return context;
+}
+
+export async function qualifyPipelineVersionContext(
+  context,
+  host,
+  directory,
+  artifactClient,
+) {
+  if (
+    context.schema !== "buildchain.pipeline-version-context/v1" ||
+    context.runId !== host.runId ||
+    context.runAttempt !== host.runAttempt
+  )
+    throw new Error(
+      "Version context belongs to a different provider execution",
+    );
+  const session = await resumePipelineSession(
+    { ...host, attempt: context.attempt },
+    host,
+  );
+  const journal = pipelinePublicationJournal(session, host);
+  await journal.fence();
+  const { preparation } = context;
+  if (
+    context.generation !== session.observed.generation ||
+    preparation.attempt !== context.attempt ||
+    preparation.generation !== context.generation ||
+    recordDigest(preparation.runtime) !== recordDigest(host.runtime)
+  )
+    throw new Error(
+      "Version context changed its admitted attempt, generation or runtime",
+    );
+  const retained = await journal.materials(
+    `publication/version-${preparation.purpose}-context/`,
+  );
+  if (!retained.some((value) => recordDigest(value) === recordDigest(context)))
+    throw new Error(
+      "Version context is not retained in the authoritative attempt",
+    );
+  const admitted = await host.source.source(
+    preparation.source.commit,
+    preparation.source.configPath,
+  );
+  if (recordDigest(admitted.identity) !== recordDigest(preparation.source))
+    throw new Error("Version context source changed before qualification");
+  verifyPipelineVersionPreparation(preparation, admitted.plan);
+  const artifacts = githubPipelineVersionArtifacts(host, artifactClient);
+  const observed = await artifacts.download(context, directory);
+  const adapter = githubPipelineVersion(host.request, host.repository);
+  const before = await adapter.inspect(
+    preparation.source,
+    preparation.versionPolicy,
+  );
+  collectPipelineVersionMaterial(preparation, before.files, observed.results);
+  const regeneration = { context, ...observed };
+  await journal.fence();
+  await journal.record(
+    `publication/version-${preparation.purpose}-qualified`,
+    regeneration,
+    { phase: phaseOf(preparation.purpose) },
+  );
+  return { session, journal, regeneration };
+}
+
+export async function retainedPipelineVersionRegeneration(
+  journal,
+  parent,
+  purpose,
+  runtime,
+) {
+  const values = (
+    await journal.materials(`publication/version-${purpose}-qualified/`)
+  ).filter(
+    ({ context }) =>
+      context.preparation.parentRoot === parent.root &&
+      recordDigest(context.preparation.runtime) === recordDigest(runtime),
+  );
+  if (
+    values.length > 1 &&
+    new Set(values.map(({ results }) => recordDigest(results))).size !== 1
+  )
+    throw new Error("Version regeneration has conflicting qualified bytes");
+  return values.at(-1);
+}

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

@@ -0,0 +1,36 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { collectPipelineVersionMaterial } from "./version-regeneration.js";
+import { materializePipelineVersion } from "./version.js";
+
+// Provider execution is qualified and journaled by version-context before this
+// pure byte check. A self-reported digest never grants Git write authority.
+export function preparedPipelineVersionMaterial(plan, files, regeneration) {
+  if (!regeneration) {
+    if (plan.versionPolicy.derived_files?.length)
+      throw new Error(
+        "Derived version files require retained qualified regeneration",
+      );
+    return materializePipelineVersion(plan.versionPolicy, files, plan.version);
+  }
+  const { context, build, results } = regeneration;
+  const { preparation } = context;
+  const { root: buildRoot, ...buildBody } = build;
+  if (
+    preparation.parentRoot !== plan.root ||
+    preparation.version !== plan.version ||
+    recordDigest(preparation.source) !== recordDigest(plan.source) ||
+    recordDigest(preparation.versionPolicy) !==
+      recordDigest(plan.versionPolicy) ||
+    build.preparationRoot !== preparation.root ||
+    build.runId !== context.runId ||
+    build.runAttempt !== context.runAttempt ||
+    buildRoot !== recordDigest(buildBody)
+  )
+    throw new Error(
+      "Qualified regeneration does not belong to this exact version materialization",
+    );
+  return {
+    ...collectPipelineVersionMaterial(preparation, files, results),
+    regenerationBuildRoot: buildRoot,
+  };
+}

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

@@ -0,0 +1,69 @@
+import {
+  recordDigest,
+  validateRuntime,
+} from "../../release/discussion/envelope.js";
+import { validateConsumerSource } from "../../workflow/attempt/identity.js";
+import { pipelinePlatforms } from "../../workflow/pipeline/platforms.js";
+import { choice, text } from "../../consumer/contract/shape.js";
+import { pipelineVersionMaterialPaths } from "./version-regeneration.js";
+
+export function planPipelineVersionPreparation({
+  attempt,
+  generation,
+  source,
+  contract,
+  version,
+  runtime,
+  purpose,
+  parentRoot,
+}) {
+  text(attempt, "version preparation attempt", /^attempt-[0-9a-f]{64}$/u);
+  text(generation, "version preparation generation", /^sha256:[0-9a-f]{64}$/u);
+  text(parentRoot, "version preparation parent", /^sha256:[0-9a-f]{64}$/u);
+  text(
+    source.repository,
+    "version preparation repository",
+    /^[\w.-]+\/[\w.-]+$/u,
+  );
+  validateConsumerSource(source, source.repository);
+  validateRuntime(runtime);
+  choice(
+    runtime.repository,
+    ["kungfu-systems/buildchain"],
+    "version preparation runtime",
+  );
+  choice(
+    purpose,
+    ["publication", "development"],
+    "version preparation purpose",
+  );
+  text(
+    version,
+    "version preparation target",
+    /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u,
+  );
+  pipelineVersionMaterialPaths(contract.version, source.configPath);
+  const body = {
+    schema: "buildchain.pipeline-version-preparation/v1",
+    attempt,
+    generation,
+    source,
+    version,
+    runtime,
+    purpose,
+    parentRoot,
+    contractRoot: recordDigest(contract),
+    versionPolicy: contract.version,
+    platforms: pipelinePlatforms(contract).map(({ platform }) => platform),
+  };
+  return structuredClone({ ...body, root: recordDigest(body) });
+}
+
+export function verifyPipelineVersionPreparation(preparation, contract) {
+  const expected = planPipelineVersionPreparation({ ...preparation, contract });
+  if (recordDigest(preparation) !== recordDigest(expected))
+    throw new Error(
+      "Version preparation changed its source-bound product contract or root",
+    );
+  return preparation;
+}