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

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.recordImport(bundle, phase);
+}

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

@@ -0,0 +1,218 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { verifyPipelinePublicationPlan } from "./plan.js";
+import {
+  verifyPipelineQualification,
+  pipelineReleaseDocuments,
+} from "./documents.js";
+import { restorePipelineProducts } from "./sealed-products.js";
+import { verifyPipelineSigning } from "./signing.js";
+import { writeImmutablePublicationFile } from "./files.js";
+import {
+  readRecoveryPublicationMaterials,
+  recoveryPublicationMaterial,
+  publicationLineageMaterial,
+} from "./recovery-materials.js";
+import { planRecoveryPublicationBuild } from "./recovery-build-plan.js";
+import { qualifyRecoveryIntegration } from "../../workflow/pipeline/recovery-integration.js";
+
+async function inspectRetainedBytes(
+  { plan, materialization, retained, archive, host },
+  verifySigning,
+) {
+  const directory = fs.mkdtempSync(
+    path.join(fs.realpathSync(os.tmpdir()), "buildchain-publication-recovery-"),
+  );
+  try {
+    // Historical validation proves the original document's integrity only.
+    // Fresh execution authorization is a separate admission before any effect.
+    const evaluatedAt = retained.qualified.qualification.issuedAt;
+    verifyPipelineQualification({
+      plan,
+      materialization,
+      qualified: retained.qualified,
+      evaluatedAt,
+    });
+    await restorePipelineProducts(
+      archive,
+      retained.qualified,
+      retained.sealed,
+      path.join(directory, "products"),
+    );
+    if (!retained.signing)
+      return { sealed: retained.sealed.root, signing: null };
+    const bundlePath = writeImmutablePublicationFile(
+      path.join(directory, "attestation.json"),
+      await archive.read(retained.bundle),
+    );
+    const signing = verifySigning({
+      plan,
+      materialization,
+      qualified: retained.qualified,
+      bundlePath,
+      directory: path.join(directory, "signing"),
+      token: host.token,
+      evaluatedAt,
+    });
+    const documents = pipelineReleaseDocuments({
+      plan,
+      materialization,
+      qualified: retained.qualified,
+      capsules: retained.capsules,
+      signing,
+      evaluatedAt,
+    });
+    if (
+      recordDigest(signing) !== recordDigest(retained.signing) ||
+      recordDigest(documents) !== recordDigest(retained.documents)
+    )
+      throw new Error(
+        "Recovery signature or original release documents changed",
+      );
+    return {
+      sealed: retained.sealed.root,
+      signing: recordDigest(signing),
+      documents: recordDigest(documents),
+    };
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+export async function inspectRecoveryPublication(
+  session,
+  admitted,
+  host,
+  { verifySigning = verifyPipelineSigning } = {},
+) {
+  const integration = await qualifyRecoveryIntegration(
+    session,
+    admitted.admission,
+    host,
+  );
+  const materials = await readRecoveryPublicationMaterials(session, host);
+  const plan = recoveryPublicationMaterial(materials, "publication/plan/");
+  if (!plan) {
+    if (materials.some((item) => !item.id.startsWith("publication/worker/")))
+      throw new Error(
+        "Publication recovery has materials without their authoritative plan",
+      );
+    return {
+      schema: "buildchain.pipeline-recovery-publication/v1",
+      mode: "unprepared",
+      integration,
+      materials,
+    };
+  }
+  verifyPipelinePublicationPlan(plan);
+  const original = session.observed.history.find(
+    (item) => item.identity.id === plan.attempt,
+  );
+  if (
+    !original ||
+    plan.generation !== session.observed.generation ||
+    recordDigest(plan.intentSource) !==
+      recordDigest(original.generation.source) ||
+    plan.source.commit !== integration.integration.mergeCommit
+  )
+    throw new Error(
+      "Recovered publication plan changed its original source or protected integration",
+    );
+  const materialization = recoveryPublicationMaterial(
+    materials,
+    "publication/materialization/",
+  );
+  if (!materialization)
+    return {
+      schema: "buildchain.pipeline-recovery-publication/v1",
+      mode: "materialize",
+      integration,
+      materials,
+    };
+  const source = await host.source.source(
+    materialization.source.commit,
+    plan.source.configPath,
+  );
+  if (
+    recordDigest(source.identity) !== recordDigest(materialization.source) ||
+    recordDigest(source.plan) !== plan.contractRoot
+  )
+    throw new Error(
+      "Recovered publication materialization changed its exact source or contract",
+    );
+  const qualified = recoveryPublicationMaterial(
+    materials,
+    "publication/qualified/",
+  );
+  const prepared =
+    materials
+      .filter((item) =>
+        item.id.startsWith("publication/qualification-prepared/"),
+      )
+      .at(-1)?.value ||
+    recoveryPublicationMaterial(materials, "publication/predecessor-prepared/");
+  const retained = qualified || prepared;
+  if (
+    !qualified &&
+    materials.some((item) => item.id.startsWith("publication/effect/"))
+  )
+    throw new Error(
+      "Partial publication lost its original signed qualification; rebuilding cannot replace published bytes",
+    );
+  const originalPlan = retained
+    ? publicationLineageMaterial(
+        materials,
+        "buildchain.pipeline-publication-plan/v1",
+        (value) => value.root === retained.qualified.planRoot,
+      )
+    : plan;
+  const originalMaterialization = retained
+    ? publicationLineageMaterial(
+        materials,
+        "buildchain.pipeline-version-materialization/v1",
+        (value) =>
+          value.planRoot === originalPlan.root &&
+          recordDigest(value.source) ===
+            recordDigest(retained.qualified.source),
+      )
+    : materialization;
+  if (
+    originalPlan.version !== plan.version ||
+    originalPlan.contractRoot !== plan.contractRoot ||
+    recordDigest(originalPlan.outputs) !== recordDigest(plan.outputs)
+  )
+    throw new Error(
+      "Recovered publication lineage changed the sealed product contract",
+    );
+  const readback = retained
+    ? await inspectRetainedBytes(
+        {
+          plan: originalPlan,
+          materialization: originalMaterialization,
+          retained,
+          archive: host.productArchive(session),
+          host,
+        },
+        verifySigning,
+      )
+    : null;
+  return {
+    schema: "buildchain.pipeline-recovery-publication/v1",
+    mode: qualified ? "qualified" : prepared ? "prepared" : "build",
+    integration,
+    materials,
+    readback,
+    preparedRoot: prepared ? recordDigest(prepared) : null,
+    build: retained
+      ? null
+      : await planRecoveryPublicationBuild(
+          session,
+          plan,
+          materialization,
+          materials,
+          host,
+        ),
+  };
+}

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

@@ -0,0 +1,104 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { retainedRecoveryEvidence } from "../../workflow/pipeline/recovery-session.js";
+import {
+  PUBLICATION_IMPORT,
+  publicationImportedValues,
+} from "./imported-materials.js";
+
+export async function readRecoveryPublicationMaterials(session, host) {
+  const current = session.observed.history.at(-1);
+  const references = current.events
+    .flatMap((event) => event.payload.materials)
+    .filter((item) => item.id.startsWith("publication/"));
+  const unique = [
+    ...new Map(
+      references.map((reference) => [
+        `${reference.id}:${reference.digest}`,
+        reference,
+      ]),
+    ).values(),
+  ];
+  if (unique.length > 1000)
+    throw new Error(
+      "Publication recovery material inventory exceeds its bound",
+    );
+  const result = [];
+  for (const reference of unique) {
+    const value = await host.materialStore(session).read(reference);
+    if (value.schema === PUBLICATION_IMPORT)
+      result.push(
+        ...publicationImportedValues(value).map((item) => ({
+          id: item.id,
+          reference,
+          memberId: item.id,
+          value: item.value,
+        })),
+      );
+    else result.push({ id: reference.id, reference, value });
+  }
+  if (
+    !result.some((item) => item.id.startsWith("publication/plan/")) &&
+    current.identity.requestKey.startsWith("recover:")
+  ) {
+    const { evidence } = await retainedRecoveryEvidence(session, host);
+    for (const item of evidence.publication?.materials || []) {
+      const producer = session.observed.history.find(
+        (entry) => entry.identity.id === item.reference.producerAttempt,
+      );
+      if (!producer)
+        throw new Error(
+          "Publication recovery material has no canonical predecessor",
+        );
+      const retained = {
+        ...session,
+        observed: { ...session.observed, history: [producer] },
+      };
+      const container = await host.materialStore(retained).read(item.reference);
+      const value = item.memberId
+        ? publicationImportedValues(container).find(
+            (member) => member.id === item.memberId,
+          )?.value
+        : container;
+      if (recordDigest(value) !== recordDigest(item.value))
+        throw new Error("Retained predecessor publication material changed");
+      result.push({ ...item, value });
+    }
+  }
+  if (result.length > 1000)
+    throw new Error(
+      "Expanded publication recovery inventory exceeds its bound",
+    );
+  return result;
+}
+
+export function recoveryPublicationMaterial(
+  materials,
+  prefix,
+  required = false,
+) {
+  const values = [
+    ...new Map(
+      materials
+        .filter((item) => item.id.startsWith(prefix))
+        .map((item) => [recordDigest(item.value), item.value]),
+    ).values(),
+  ];
+  if (values.length > 1 || (required && values.length !== 1))
+    throw new Error(
+      `Publication recovery needs one exact retained material: ${prefix}`,
+    );
+  return values[0] || null;
+}
+
+export function publicationLineageMaterial(materials, schema, accepts) {
+  const values = [
+    ...new Map(
+      materials.map((item) => [recordDigest(item.value), item.value]),
+    ).values(),
+  ].filter((value) => value.schema === schema && accepts(value));
+  if (values.length !== 1)
+    throw new Error(
+      `Publication recovery has no exact original lineage material: ${schema}`,
+    );
+  return values[0];
+}

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

@@ -0,0 +1,46 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { verifyPipelinePublicationPlan } from "./plan.js";
+import { verifyRootedPublication } from "./documents.js";
+
+// Before signing or publishing, a new publisher may qualify the already sealed
+// bytes under an explicit derived plan. Original manifests and source stay exact.
+export function deriveRecoveryPublicationPlan(
+  original,
+  materialization,
+  execution,
+  recoveryPlanRoot,
+) {
+  verifyPipelinePublicationPlan(original);
+  const { root: previous, ...body } = original;
+  const value = {
+    ...body,
+    attempt: execution.attempt,
+    runtime: execution.runtime,
+    publisher: execution.publisher,
+    recovery: {
+      predecessorPlanRoot: previous,
+      admissionRoot: recoveryPlanRoot,
+    },
+  };
+  const plan = { ...value, root: recordDigest(value) };
+  if (!materialization) return { plan, materialization: null };
+  verifyRootedPublication(
+    materialization,
+    "buildchain.pipeline-version-materialization/v1",
+  );
+  if (
+    materialization.planRoot !== original.root ||
+    recordDigest(materialization.protectedSource) !==
+      recordDigest(original.source)
+  )
+    throw new Error(
+      "Recovery version materialization changed its original plan",
+    );
+  const { root, ...source } = materialization;
+  const derived = {
+    ...source,
+    planRoot: plan.root,
+    recovery: { predecessorRoot: root, predecessorPlanRoot: previous },
+  };
+  return { plan, materialization: { ...derived, root: recordDigest(derived) } };
+}