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

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

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { githubPipelinePublicationArtifacts } from "../../providers/github/pipeline-publication-artifacts.js";
+import { publicationContext, uniquePublicationMaterial } from "./context.js";
+import { qualifyPipelineProducts } from "./qualification.js";
+import { pipelineProductCapsules } from "./capsules.js";
+import { retainPipelineProducts } from "./sealed-products.js";
+import { preparePipelineSigning, verifyPipelineSigning } from "./signing.js";
+import { pipelineReleaseDocuments } from "./documents.js";
+import { downloadRecoveryPublicationBuild } from "./recovery-build-download.js";
+import { prepareRecoveredSigning } from "./recovery-signing.js";
+
+export async function preparePipelineQualification(context, host, directory) {
+  const { journal, archive } = await publicationContext(context, host);
+  if (context.recovery?.mode === "prepared")
+    return prepareRecoveredSigning(context, host, journal, archive, directory);
+  const products = githubPipelinePublicationArtifacts(host);
+  const productDirectory = path.join(directory, "products");
+  const { build, bundles } = context.recovery?.build
+    ? await downloadRecoveryPublicationBuild(context, host, productDirectory)
+    : await products.download(context, productDirectory);
+  const { plan, materialization } = context;
+  const qualified = qualifyPipelineProducts({
+    plan,
+    source: materialization.source,
+    bundles,
+    build,
+    policyRoot: plan.contractRoot,
+  });
+  const capsules = pipelineProductCapsules({
+    plan,
+    materialization,
+    qualified,
+    bundles,
+  });
+  const sealed = await retainPipelineProducts(archive, qualified, bundles);
+  const prepared = {
+    schema: "buildchain.pipeline-qualification-preparation/v1",
+    contextRoot: recordDigest(context),
+    qualified,
+    capsules,
+    sealed,
+  };
+  await journal.fence();
+  await journal.record(
+    `publication/qualification-prepared/${context.runId}-${context.runAttempt}`,
+    prepared,
+  );
+  return preparePipelineSigning({
+    plan,
+    materialization,
+    qualified,
+    directory: path.join(directory, "signing"),
+  });
+}
+
+export async function sealPipelineQualification(
+  context,
+  host,
+  directory,
+  bundlePath,
+) {
+  const { journal, archive } = await publicationContext(context, host);
+  const prepared = await uniquePublicationMaterial(
+    journal,
+    `publication/qualification-prepared/${context.runId}-${context.runAttempt}/`,
+  );
+  if (prepared.contextRoot !== recordDigest(context))
+    throw new Error("Signing preparation changed provider context");
+  const { plan, materialization } = context;
+  const signing = verifyPipelineSigning({
+    plan,
+    materialization,
+    qualified: prepared.qualified,
+    directory: path.join(directory, "verify-signing"),
+    bundlePath,
+    token: host.token,
+  });
+  const bundle = await archive.put(fs.readFileSync(bundlePath), {
+    name: "attestation.json",
+    mediaType: "application/json",
+  });
+  if (bundle.digest !== signing.bundleDigest)
+    throw new Error("Retained attestation differs from verified signing bytes");
+  await archive.read(bundle);
+  const documents = pipelineReleaseDocuments({
+    plan,
+    materialization,
+    qualified: prepared.qualified,
+    capsules: prepared.capsules,
+    signing,
+  });
+  const result = {
+    ...prepared,
+    schema: "buildchain.pipeline-qualified-products/v1",
+    signing,
+    bundle,
+    documents,
+  };
+  await journal.fence();
+  await journal.record("publication/qualified", result);
+  return result;
+}

package/packages/core/publication/pipeline/recovery-admission.js

@@ -0,0 +1,122 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  createReleaseInvocation,
+  createReleaseReceipt,
+  RELEASE_RECEIPT_CONTRACT,
+} from "../../release/release-invocation.js";
+import {
+  createDomainPublicationQualificationReceipt,
+  validatePublicationQualificationReceipt,
+} from "../publication-qualification.js";
+import { verifyPipelineQualification } from "./documents.js";
+
+export const RECOVERY_PUBLICATION_ADMISSION =
+  "buildchain.pipeline-recovery-publication-admission/v1";
+
+// Only the publisher's byte/signature/provider requalification calls this pure
+// domain bridge. It creates fresh authority for the new execution and preserves
+// the original invocation, transaction, Passport and qualification unchanged.
+export function createRecoveryPublicationAdmission({
+  context,
+  retained,
+  execution,
+  readback,
+  now = new Date(),
+}) {
+  const { plan, materialization } = context;
+  const { qualified, documents } = retained;
+  const { root, ...body } = readback;
+  if (
+    !context.recovery ||
+    !/^sha256:[0-9a-f]{64}$/u.test(context.recovery.planRoot || "") ||
+    context.recovery.predecessor === context.attempt ||
+    execution.attempt !== context.attempt ||
+    execution.runId !== context.runId ||
+    execution.runAttempt !== context.runAttempt ||
+    body.schema !== "buildchain.pipeline-recovery-publication-readback/v1" ||
+    root !== recordDigest(body) ||
+    body.transactionRoot !== documents.transaction.transactionRoot ||
+    body.qualificationRoot !== qualified.root ||
+    body.signingRoot !== recordDigest(retained.signing) ||
+    body.sealedRoot !== retained.sealed.root
+  )
+    throw new Error(
+      "Recovery publication admission requires exact current execution and independent retained-byte readback",
+    );
+  verifyPipelineQualification({
+    plan,
+    materialization,
+    qualified,
+    evaluatedAt: qualified.qualification.issuedAt,
+  });
+  const qualification = createDomainPublicationQualificationReceipt({
+    ...qualified.qualification,
+    issuedAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + 60 * 60 * 1000).toISOString(),
+  });
+  // This observation reports the predecessor transaction at the recovery
+  // boundary. It is not a replacement for any original terminal receipt.
+  const predecessorReceipt = createReleaseReceipt({
+    schema: RELEASE_RECEIPT_CONTRACT,
+    transactionRoot: documents.transaction.transactionRoot,
+    outcome: "blocked",
+    releasePassportRoot: documents.passport.passportRoot,
+    providerTransactionRoot: body.effectsRoot,
+    providerStateRoot: readback.root,
+    providerReceiptRoots: [...new Set(body.receiptRoots)].sort(),
+  });
+  const invocation = createReleaseInvocation({
+    ...documents.invocation.invocation,
+    publisher: execution.publisher,
+    runtime: execution.runtime,
+    authority: {
+      policyRoot: plan.contractRoot,
+      qualificationRoot: qualification.receiptRoot,
+      warrantRoot: qualification.receiptRoot,
+    },
+    parent: {
+      invocationRoot: documents.invocation.roots.invocationRoot,
+      transactionRoot: documents.transaction.transactionRoot,
+      receiptRoot: predecessorReceipt.receiptRoot,
+    },
+  });
+  const value = {
+    schema: RECOVERY_PUBLICATION_ADMISSION,
+    contextRoot: recordDigest(context),
+    recoveryPlanRoot: context.recovery.planRoot,
+    execution,
+    originalDocumentsRoot: recordDigest(documents),
+    readbackRoot: readback.root,
+    qualification,
+    predecessorReceipt,
+    invocation,
+  };
+  return { ...value, root: recordDigest(value) };
+}
+
+export function verifyRecoveryPublicationAdmission(
+  admission,
+  { context, retained, execution, readback, now = new Date() },
+) {
+  const expected = createRecoveryPublicationAdmission({
+    context,
+    retained,
+    execution,
+    readback,
+    now: new Date(admission.qualification.issuedAt),
+  });
+  if (recordDigest(expected) !== recordDigest(admission))
+    throw new Error(
+      "Recovery publication authority changed its exact execution or original transaction",
+    );
+  validatePublicationQualificationReceipt(admission.qualification, {
+    repository: context.plan.source.repository,
+    candidateRoot: retained.qualified.qualification.candidateRoot,
+    sourceSha: retained.qualified.source.commit,
+    sourceRoot: recordDigest(retained.qualified.source),
+    artifactRoot: retained.qualified.qualification.artifactRoot,
+    policyDigest: context.plan.contractRoot,
+    evaluatedAt: now.toISOString(),
+  });
+  return admission;
+}

package/packages/core/publication/pipeline/recovery-build-download.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { readPipelineCaller } from "../../providers/github/pipeline-run-entry.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { qualifyRecoveryRuntime } from "../../workflow/pipeline/recovery-runtime.js";
+import { githubPipelinePublicationArtifacts } from "../../providers/github/pipeline-publication-artifacts.js";
+import { qualifyPublicationBuildSegments } from "./build-segments.js";
+
+export async function downloadRecoveryPublicationBuild(
+  context,
+  host,
+  directory,
+) {
+  const recovery = context.recovery.build;
+  const { root, ...body } = recovery;
+  if (
+    root !== recordDigest(body) ||
+    recordDigest(recovery.source) !==
+      recordDigest(context.materialization.source)
+  )
+    throw new Error(
+      "Recovery publication build changed its retained source evidence",
+    );
+  const provider = githubPipelinePublicationArtifacts(host),
+    segments = [],
+    bundles = [];
+  for (const [index, segment] of recovery.segments.entries()) {
+    const comparison = await qualifyRecoveryRuntime(
+      segment.runtime,
+      host.runtime,
+      "publication-build",
+      host.request,
+    );
+    if (!comparison.compatible)
+      throw new Error(
+        "Recovered publication producer changed after runtime admission",
+      );
+    const original = {
+      plan: segment.plan,
+      materialization: segment.materialization,
+      runId: segment.build.runId,
+      runAttempt: segment.build.runAttempt,
+    };
+    const downloaded = await provider.download(
+      original,
+      path.join(directory, `predecessor-${index}`),
+      segment.build.platforms,
+    );
+    if (recordDigest(downloaded.build) !== recordDigest(segment.build))
+      throw new Error(
+        "Recovered publication artifact evidence changed after admission",
+      );
+    segments.push(segment);
+    bundles.push(...downloaded.bundles);
+  }
+  if (recovery.scheduled.length) {
+    const downloaded = await provider.download(
+      context,
+      path.join(directory, "current"),
+      recovery.scheduled,
+    );
+    segments.push({
+      plan: context.plan,
+      materialization: context.materialization,
+      runtime: host.runtime,
+      build: downloaded.build,
+    });
+    bundles.push(...downloaded.bundles);
+  }
+  const { run } = await host.runs.read(context.runId, context.runAttempt);
+  await readPipelineCaller(
+    run,
+    context.materialization.source.configPath,
+    host.request,
+    host.repository,
+  );
+  return {
+    build: qualifyPublicationBuildSegments(context, segments, run.head_sha),
+    bundles,
+  };
+}

package/packages/core/publication/pipeline/recovery-build-plan.js

@@ -0,0 +1,122 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { qualifyRecoveryRuntime } from "../../workflow/pipeline/recovery-runtime.js";
+import { githubPipelinePublicationArtifacts } from "../../providers/github/pipeline-publication-artifacts.js";
+import { verifyPipelinePublicationPlan } from "./plan.js";
+
+export function assertRecoveryProductContract(
+  original,
+  plan,
+  source,
+  materialization,
+) {
+  verifyPipelinePublicationPlan(original);
+  if (
+    original.version !== plan.version ||
+    original.contractRoot !== plan.contractRoot ||
+    recordDigest(original.outputs) !== recordDigest(plan.outputs) ||
+    recordDigest(original.source) !== recordDigest(plan.source) ||
+    recordDigest(source) !== recordDigest(materialization.source)
+  )
+    throw new Error(
+      "Recovered product build changed version, source or declared outputs",
+    );
+}
+
+async function completedPlatforms(context, platforms, host) {
+  const { run, jobs } = await host.runs.read(context.runId, context.runAttempt);
+  if (run.status !== "completed")
+    throw new Error("Publication recovery cannot reuse an active producer");
+  return platforms.filter((platform) => {
+    const name = `Build publication (${platform})`;
+    const matches = jobs.filter(
+      (job) => job.name === name || job.name.endsWith(` / ${name}`),
+    );
+    if (matches.length > 1)
+      throw new Error("Publication recovery product job is ambiguous");
+    return (
+      matches[0]?.status === "completed" && matches[0]?.conclusion === "success"
+    );
+  });
+}
+
+export async function planRecoveryPublicationBuild(
+  session,
+  plan,
+  materialization,
+  materials,
+  host,
+) {
+  const declared = [
+    ...new Set(plan.outputs.map(({ platform }) => platform)),
+  ].sort();
+  const contexts = [
+    ...new Map(
+      materials
+        .filter((item) =>
+          /^publication\/(?:context|predecessor-context)\//u.test(item.id),
+        )
+        .map(({ value }) => [recordDigest(value), value]),
+    ).values(),
+  ].reverse();
+  if (contexts.length > 100)
+    throw new Error("Publication producer history exceeds its bound");
+  const remaining = new Set(declared),
+    segments = [],
+    comparisons = [];
+  const provider = githubPipelinePublicationArtifacts(host);
+  for (const context of contexts) {
+    if (!remaining.size) break;
+    const owner = session.observed.history.find(
+      (item) => item.identity.id === context.attempt,
+    );
+    if (
+      !owner ||
+      owner.generation.id !== session.observed.generation ||
+      context.schema !== "buildchain.pipeline-publication-context/v1"
+    )
+      throw new Error(
+        "Publication producer has no canonical same-generation attempt",
+      );
+    assertRecoveryProductContract(
+      context.plan,
+      plan,
+      context.materialization.source,
+      materialization,
+    );
+    const producerRuntime = owner.events[0].runtime;
+    if (context.plan.runtime.commit !== producerRuntime.sha)
+      throw new Error(
+        "Publication product producer differs from its admitted runtime",
+      );
+    const comparison = await qualifyRecoveryRuntime(
+      producerRuntime,
+      host.runtime,
+      "publication-build",
+      host.request,
+    );
+    comparisons.push(comparison);
+    if (!comparison.compatible) continue;
+    const platforms = await completedPlatforms(context, [...remaining], host);
+    if (!platforms.length) continue;
+    const { build } = await provider.buildReadback(context, platforms);
+    segments.push({
+      plan: context.plan,
+      materialization: context.materialization,
+      runtime: producerRuntime,
+      build,
+    });
+    platforms.forEach((platform) => remaining.delete(platform));
+  }
+  const body = {
+    schema: "buildchain.pipeline-recovery-publication-build/v1",
+    source: materialization.source,
+    predecessorPlanRoot: plan.root,
+    segments,
+    comparisons,
+    scheduled: [...remaining].sort(),
+    reason: contexts.length
+      ? "Requalify exact successful producer artifacts; execute only missing or explicitly changed implementations"
+      : "No product execution was retained; execute the declared publication platforms",
+  };
+  return { ...body, root: recordDigest(body) };
+}

package/packages/core/publication/pipeline/recovery-build-readback.js

@@ -0,0 +1,68 @@
+import { PUBLICATION_BUILD_AGGREGATE } from "./build-segments.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { readPipelineCaller } from "../../providers/github/pipeline-run-entry.js";
+
+export async function reobservePublicationBuild(
+  build,
+  source,
+  host,
+  depth = 0,
+) {
+  const { root, ...body } = build;
+  if (
+    depth > 100 ||
+    root !== recordDigest(body) ||
+    recordDigest(build.source) !== recordDigest(source)
+  )
+    throw new Error(
+      "Publication recovery build lineage changed its source or exceeds its bound",
+    );
+  if (build.schema === PUBLICATION_BUILD_AGGREGATE) {
+    if (
+      !Array.isArray(build.segments) ||
+      !build.segments.length ||
+      build.segments.length > 100
+    )
+      throw new Error("Publication producer segment history exceeds its bound");
+    for (const segment of build.segments)
+      await reobservePublicationBuild(segment.build, source, host, depth + 1);
+    return build;
+  }
+  if (build.schema === "buildchain.pipeline-publication-requalification/v1")
+    return reobservePublicationBuild(
+      build.predecessorBuild,
+      source,
+      host,
+      depth + 1,
+    );
+  if (
+    build.schema !== "buildchain.pipeline-publication-build-readback/v1" ||
+    !Array.isArray(build.jobs) ||
+    !build.jobs.length ||
+    build.outcome !== "success"
+  )
+    throw new Error(
+      "Publication recovery requires actual retained successful product jobs",
+    );
+  const { run, jobs } = await host.runs.read(build.runId, build.runAttempt);
+  if (run.head_sha !== build.providerSource)
+    throw new Error("Publication producer changed its exact provider source");
+  await readPipelineCaller(
+    run,
+    source.configPath,
+    host.request,
+    host.repository,
+  );
+  for (const old of build.jobs)
+    if (
+      old.status !== "completed" ||
+      old.conclusion !== "success" ||
+      old.run_id !== build.runId ||
+      old.run_attempt !== build.runAttempt ||
+      !jobs.some((job) => recordDigest(job) === recordDigest(old))
+    )
+      throw new Error(
+        "Retained publication product job changed during requalification",
+      );
+  return build;
+}

package/packages/core/publication/pipeline/recovery-capsules.js

@@ -0,0 +1,54 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  validateStageCapsule,
+  stageCapsuleIdentityRoot,
+  stageCapsuleRoot,
+} from "../../build/stage-capsule.js";
+import { verifyRootedPublication } from "./documents.js";
+
+export function requalifyPublicationCapsules(previous, qualified, plan) {
+  verifyRootedPublication(previous, "buildchain.pipeline-product-capsules/v1");
+  if (
+    recordDigest(previous.capsules.map((item) => item.artifact)) !==
+    recordDigest(qualified.artifacts)
+  )
+    throw new Error(
+      "Recovery capsules changed the exact sealed artifact inventory",
+    );
+  const capsules = previous.capsules.map((entry) => {
+    validateStageCapsule(entry.capsule);
+    const identity = {
+      ...entry.capsule.identity,
+      qualificationRoot: qualified.qualification.receiptRoot,
+      declaredInputs: [
+        { name: "predecessor-capsule", root: entry.capsule.capsuleRoot },
+        { name: "publication-plan", root: plan.root },
+      ],
+      observationRoots: [
+        { name: "provider-build", root: qualified.build.root },
+      ],
+    };
+    // Retain the producer's runtime and original retention promise, even when
+    // expired. The current sealed-byte readback supplies publication authority;
+    // this derived capsule does not invent a renewed Actions artifact lease.
+    const capsule = {
+      ...entry.capsule,
+      identity,
+      identityRoot: stageCapsuleIdentityRoot(identity),
+    };
+    capsule.capsuleRoot = stageCapsuleRoot(capsule);
+    validateStageCapsule(capsule);
+    return {
+      ...entry,
+      capsule,
+      predecessorCapsuleRoot: entry.capsule.capsuleRoot,
+    };
+  });
+  const body = {
+    schema: "buildchain.pipeline-product-capsules/v1",
+    qualificationRoot: qualified.root,
+    predecessorRoot: previous.root,
+    capsules,
+  };
+  return { ...body, root: recordDigest(body) };
+}

package/packages/core/publication/pipeline/recovery-import.js

@@ -0,0 +1,80 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { recoveryPublicationMaterial } from "./recovery-materials.js";
+import { deriveRecoveryPublicationPlan } from "./recovery-plan.js";
+import {
+  PUBLICATION_IMPORT,
+  publicationImportedValues,
+} from "./imported-materials.js";
+
+function importedId(item, publication) {
+  const id = item.id;
+  if (id.startsWith("publication/worker/")) return null;
+  if (id.startsWith("publication/context/"))
+    return "publication/predecessor-context";
+  if (
+    id.startsWith("publication/qualification-prepared/") ||
+    id.startsWith("publication/predecessor-prepared/")
+  )
+    return publication.mode !== "qualified" &&
+      recordDigest(item.value) === publication.preparedRoot
+      ? "publication/predecessor-prepared"
+      : null;
+  for (const name of [
+    "complete",
+    "distribution-complete",
+    "next-development-result",
+  ])
+    if (id.startsWith(`publication/${name}/`))
+      return `publication/predecessor-${name}`;
+  if (publication.mode !== "qualified")
+    for (const name of ["plan", "materialization"])
+      if (id.startsWith(`publication/${name}/`))
+        return `publication/predecessor-${name}`;
+  return id.slice(0, id.lastIndexOf("/"));
+}
+
+export async function importRecoveredPublication(
+  publication,
+  execution,
+  recoveryPlanRoot,
+  journal,
+  phase,
+) {
+  const values = [];
+  const add = (id, value) =>
+    values.push({ id: `${id}/${recordDigest(value).slice(7)}`, value });
+  for (const item of publication.materials) {
+    const id = importedId(item, publication);
+    if (id) add(id, item.value);
+  }
+  if (publication.mode !== "qualified") {
+    const original = recoveryPublicationMaterial(
+      publication.materials,
+      "publication/plan/",
+      true,
+    );
+    const materialization = recoveryPublicationMaterial(
+      publication.materials,
+      "publication/materialization/",
+    );
+    const derived = deriveRecoveryPublicationPlan(
+      original,
+      materialization,
+      execution,
+      recoveryPlanRoot,
+    );
+    add("publication/plan", derived.plan);
+    if (derived.materialization)
+      add("publication/materialization", derived.materialization);
+  }
+  const body = {
+    schema: PUBLICATION_IMPORT,
+    admissionRoot: recoveryPlanRoot,
+    values: [...new Map(values.map((item) => [item.id, item])).values()],
+  };
+  const bundle = { ...body, root: recordDigest(body) };
+  publicationImportedValues(bundle);
+  // One journal append publishes the complete import and derived source/plan.
+  // An interruption cannot expose a new plan beside an old materialization.
+  await journal.record("publication/recovery-import", bundle, { phase });
+}