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

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

@@ -0,0 +1,92 @@
+import { publicationArtifactProducer } from "./build-segments.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  STAGE_CAPSULE_CONTRACT,
+  STAGE_CAPSULE_IDENTITY_CONTRACT,
+  stageCapsuleIdentityRoot,
+  stageCapsuleRoot,
+  validateStageCapsule,
+} from "../../build/stage-capsule.js";
+import { verifyPipelineQualification } from "./documents.js";
+
+export function pipelineProductCapsules({
+  plan,
+  materialization,
+  qualified,
+  bundles,
+  evaluatedAt,
+}) {
+  verifyPipelineQualification({
+    plan,
+    materialization,
+    qualified,
+    evaluatedAt,
+  });
+  const capsules = qualified.artifacts.map((artifact) => {
+    const bundle = bundles.find(
+      ({ providerArtifact }) =>
+        providerArtifact.id === artifact.providerArtifactId,
+    );
+    if (
+      !bundle ||
+      !bundle.providerArtifact.expires_at ||
+      Date.parse(bundle.providerArtifact.expires_at) <=
+        Date.parse(qualified.qualification.issuedAt)
+    )
+      throw new Error(
+        "Product Capsule requires a live provider retention promise",
+      );
+    const producer = publicationArtifactProducer(
+      qualified.build,
+      artifact.providerArtifactId,
+    );
+    const identity = {
+      schema: STAGE_CAPSULE_IDENTITY_CONTRACT,
+      sourceRoot: recordDigest(qualified.source),
+      platform: artifact.platform,
+      platformRoot: recordDigest({ platform: artifact.platform }),
+      stage: "verify",
+      toolchainRoots: [],
+      runtimeRoot: recordDigest(producer.plan?.runtime || plan.runtime),
+      policyRoot: plan.contractRoot,
+      declaredInputs: [
+        { name: "publication-plan", root: producer.plan?.root || plan.root },
+      ],
+      transformationRoot: recordDigest({
+        source: qualified.source,
+        product: artifact.product,
+        artifact: artifact.id,
+        kind: artifact.kind,
+      }),
+      outputManifestRoot: artifact.manifestRoot,
+      qualificationRoot: qualified.qualification.receiptRoot,
+      observationRoots: [
+        { name: "provider-build", root: qualified.build.root },
+      ],
+    };
+    const capsule = {
+      schema: STAGE_CAPSULE_CONTRACT,
+      writerAuthority: "typescript-v3",
+      rustAuthority: "validation-only",
+      identity,
+      identityRoot: stageCapsuleIdentityRoot(identity),
+      retentionPromise: {
+        class: "github-artifact",
+        retainUntil: bundle.providerArtifact.expires_at.replace(
+          /T(\d{2}:\d{2}:\d{2})Z$/u,
+          "T$1.000Z",
+        ),
+      },
+      capsuleRoot: `sha256:${"0".repeat(64)}`,
+    };
+    capsule.capsuleRoot = stageCapsuleRoot(capsule);
+    validateStageCapsule(capsule);
+    return { id: artifact.id, artifact, capsule };
+  });
+  const body = {
+    schema: "buildchain.pipeline-product-capsules/v1",
+    qualificationRoot: qualified.root,
+    capsules,
+  };
+  return { ...body, root: recordDigest(body) };
+}

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

@@ -0,0 +1,39 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { resumePipelineSession } from "../../workflow/pipeline/session.js";
+import { pipelinePublicationJournal } from "./journal.js";
+
+export async function publicationContext(context, host) {
+  if (
+    context.schema !== "buildchain.pipeline-publication-context/v1" ||
+    context.runId !== host.runId ||
+    context.runAttempt !== host.runAttempt
+  )
+    throw new Error(
+      "Publication context is not from this exact provider execution",
+    );
+  const session = await resumePipelineSession(
+    { ...host, attempt: context.attempt },
+    host,
+  );
+  if (session.observed.generation !== context.generation)
+    throw new Error(
+      "Publication context belongs to a superseded source generation",
+    );
+  const journal = pipelinePublicationJournal(session, host);
+  await journal.fence();
+  const contexts = await journal.materials("publication/context/");
+  if (!contexts.some((value) => recordDigest(value) === recordDigest(context)))
+    throw new Error(
+      "Publication context is not retained in the authoritative attempt",
+    );
+  return { session, journal, archive: host.productArchive(session) };
+}
+
+export async function uniquePublicationMaterial(journal, prefix) {
+  const values = await journal.materials(prefix);
+  if (values.length !== 1)
+    throw new Error(
+      `Publication requires one exact retained material: ${prefix}`,
+    );
+  return values[0];
+}

package/packages/core/publication/pipeline/development-anchor.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { bindPipelineDevelopmentAnchor } from "./development-transition.js";
+import { githubPipelineVersion } from "../../providers/github/pipeline-version.js";
+import { developmentTransitionReadback } from "./development-proof.js";
+
+export async function observePipelineVersionAnchor(context, host, transition) {
+  const { plan } = context;
+  const commit = await host.source.branchHead(plan.developmentBranch);
+  const source = await host.source.source(commit, plan.source.configPath);
+  const ancestry =
+    plan.channel === "stable"
+      ? null
+      : await host.request(
+          `/repos/${host.repository}/compare/${plan.intentSource.commit}...${commit}`,
+        );
+  if (
+    ancestry &&
+    (!["identical", "ahead"].includes(ancestry.status) ||
+      ancestry.merge_base_commit?.sha !== plan.intentSource.commit)
+  )
+    throw new Error(
+      "Version anchor is not descended from the released development source",
+    );
+  if (recordDigest(source.plan) !== plan.contractRoot)
+    throw new Error("Protected anchor changed the product contract");
+  const version = await githubPipelineVersion(
+    host.request,
+    host.repository,
+  ).inspect(source.identity, plan.versionPolicy);
+  if (version.version === plan.version)
+    return {
+      state: "waiting",
+      reason: "waiting-for-protected-version-anchor",
+      transitionRoot: transition.idempotencyKey,
+    };
+  const pulls = await host.request(
+    `/repos/${host.repository}/commits/${commit}/pulls?per_page=100`,
+  );
+  const candidates = pulls.filter(
+    (pr) =>
+      pr.base?.ref === plan.developmentBranch && pr.merge_commit_sha === commit,
+  );
+  if (candidates.length !== 1)
+    throw new Error("Version anchor requires one exact protected merged PR");
+  const pr = await host.request(
+    `/repos/${host.repository}/pulls/${candidates[0].number}`,
+  );
+  const integration = await host.integration.observe({
+    intent: {
+      source: { pullRequest: pr.number, targetBranch: plan.developmentBranch },
+    },
+    generation: {
+      source: { commit: pr.head.sha, configPath: plan.source.configPath },
+    },
+  });
+  if (
+    plan.channel === "stable" &&
+    Date.parse(pr.merged_at) <=
+      Date.parse(transition.completedStable.completedAt)
+  )
+    return {
+      state: "waiting",
+      reason: "waiting-for-protected-version-anchor",
+      transitionRoot: transition.idempotencyKey,
+    };
+  const file = plan.versionPolicy.files[0].path;
+  const anchor = {
+    manifestPath: file,
+    manifestRoot: `sha256:${createHash("sha256").update(version.files[file]).digest("hex")}`,
+  };
+  const bound = bindPipelineDevelopmentAnchor(transition, {
+    targetVersion: version.version,
+    anchor,
+  });
+  const verified = developmentTransitionReadback(bound, {
+    before: version,
+    after: version,
+    evidence: integration,
+    createdAt: pr.created_at,
+    mergedAt: pr.merged_at,
+  });
+  return {
+    state: "success",
+    reason: "protected-version-anchor-verified",
+    transition: verified,
+    source: source.identity,
+    integration,
+    anchor,
+  };
+}

package/packages/core/publication/pipeline/development-current.js

@@ -0,0 +1,63 @@
+import { compareDevelopmentVersions } from "../publication-development.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export async function observeAdvancedPipelineDevelopment(
+  context,
+  host,
+  transition,
+  adapter,
+) {
+  const { plan } = context;
+  const commit = await host.source.branchHead(plan.developmentBranch);
+  const source = await host.source.source(commit, plan.source.configPath);
+  if (recordDigest(source.plan) !== plan.contractRoot)
+    throw new Error(
+      "Protected development contract changed before next-version readback",
+    );
+  const observed = await adapter.inspect(source.identity, plan.versionPolicy);
+  const order = compareDevelopmentVersions(
+    observed.version,
+    transition.target.version,
+  );
+  if (order < 0) return null;
+  const pulls = await host.request(
+    `/repos/${host.repository}/commits/${commit}/pulls?per_page=100`,
+  );
+  const matches = pulls.filter(
+    (pr) =>
+      pr.base?.ref === plan.developmentBranch && pr.merge_commit_sha === commit,
+  );
+  if (matches.length !== 1)
+    throw new Error(
+      "Advanced development requires one exact protected merged PR",
+    );
+  const pr = await host.request(
+    `/repos/${host.repository}/pulls/${matches[0].number}`,
+  );
+  const integration = await host.integration.observe({
+    intent: {
+      source: { pullRequest: pr.number, targetBranch: plan.developmentBranch },
+    },
+    generation: {
+      source: { commit: pr.head.sha, configPath: plan.source.configPath },
+    },
+  });
+  if (integration.mergeCommit !== commit)
+    throw new Error(
+      "Advanced development proof differs from the observed protected commit",
+    );
+  return {
+    state: "success",
+    reason:
+      order === 0
+        ? "protected-development-already-current"
+        : "protected-development-already-advanced",
+    transitionRoot: transition.idempotencyKey,
+    targetVersion: transition.target.version,
+    observedVersion: observed.version,
+    source: source.identity,
+    integration,
+    filesRoot: recordDigest(observed.files),
+    publicationOutcome: "preserved-success",
+  };
+}

package/packages/core/publication/pipeline/development-pr.js

@@ -0,0 +1,112 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  preparePipelineVersionContext,
+  retainedPipelineVersionRegeneration,
+} from "./version-context.js";
+
+export async function prepareNextDevelopmentPullRequest(
+  context,
+  host,
+  journal,
+  transition,
+  adapter,
+) {
+  const { plan } = context;
+  const retained = await journal.materials(
+    "publication/next-development-source/",
+  );
+  if (retained.length > 1)
+    throw new Error("Next-development source reservation is ambiguous");
+  let request = retained[0];
+  if (!request) {
+    const baseCommit = await host.source.branchHead(plan.developmentBranch);
+    const source = await host.source.source(baseCommit, plan.source.configPath);
+    if (recordDigest(source.plan) !== plan.contractRoot)
+      throw new Error(
+        "Protected development contract changed before version preparation",
+      );
+    const input = await adapter.inspect(source.identity, plan.versionPolicy);
+    if (
+      plan.channel === "stable"
+        ? input.version.split("-alpha.")[0] !== plan.version
+        : input.version !== plan.version
+    )
+      throw new Error(
+        "Development version already changed; reconcile its protected provenance before preparing another PR",
+      );
+    request = {
+      source: source.identity,
+      versionPolicy: plan.versionPolicy,
+      version: transition.target.version,
+      root: recordDigest({
+        transitionRoot: transition.idempotencyKey,
+        source: source.identity,
+      }),
+      sourceTimestamp: input.sourceTimestamp,
+    };
+    await journal.record("publication/next-development-source", request, {
+      phase: "next-development",
+    });
+  }
+  const regeneration = await retainedPipelineVersionRegeneration(
+    journal,
+    request,
+    "development",
+    host.runtime,
+  );
+  if (request.versionPolicy.derived_files?.length && !regeneration)
+    return {
+      state: "waiting",
+      reason: "next-development-version-regeneration-required",
+      versionContext: await preparePipelineVersionContext(
+        request,
+        "development",
+        context,
+        host,
+        journal,
+        context.recovery?.execution.publisher.workflowSha ||
+          plan.publisher.workflowSha,
+      ),
+    };
+  await journal.fence();
+  const materialization = await adapter.materializeDevelopment(
+    request,
+    regeneration,
+  );
+  const branch = materialization.branch;
+  const pulls = await host.request(
+    `/repos/${host.repository}/pulls?state=all&head=${encodeURIComponent(`${host.repository.split("/")[0]}:${branch}`)}&base=${encodeURIComponent(plan.developmentBranch)}&per_page=100`,
+  );
+  if (!Array.isArray(pulls) || pulls.length > 1)
+    throw new Error("Next-development PR identity is ambiguous");
+  let pr = pulls[0];
+  if (!pr) {
+    await journal.fence();
+    if (!host.pullRequests)
+      throw new Error(
+        "Next-development requires the repository-authorized automation App or token to trigger ordinary PR checks",
+      );
+    pr = await host.pullRequests(`/repos/${host.repository}/pulls`, {
+      method: "POST",
+      body: {
+        title: `chore(version): prepare ${transition.target.version}`,
+        head: branch,
+        base: plan.developmentBranch,
+        body: `Prepare the declared next development version after ${plan.tag}.\n\nBuildchain-Parent-Attempt: ${context.attempt}\nBuildchain-Transition: ${transition.idempotencyKey}\n\nThe normal protected pipeline verifies the declared products before merge.`,
+      },
+    });
+  }
+  const selected = {
+    schema: "buildchain.pipeline-next-development-pr/v1",
+    number: pr.number,
+    branch,
+    base: plan.developmentBranch,
+    source: materialization.source,
+    materialization,
+    transitionRoot: transition.idempotencyKey,
+  };
+  await journal.record("publication/next-development-pr", selected, {
+    phase: "next-development",
+  });
+  return selected;
+}

package/packages/core/publication/pipeline/development-proof.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { stablePipelineDevelopmentReadback } from "./development-transition.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  nextDevelopmentRoot,
+  recordNextDevelopmentMaterialization,
+  advanceNextDevelopmentTransition,
+} from "../../release/next-development-transition.js";
+
+export function developmentTransitionReadback(
+  transition,
+  { before, after, evidence, createdAt, mergedAt },
+) {
+  const hash = (bytes) =>
+    `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+  const paths = [
+    ...transition.adapter.sourcePaths,
+    ...transition.adapter.derivedPaths,
+  ]
+    .sort()
+    .map((file) => {
+      if (
+        typeof before.files[file] !== "string" ||
+        typeof after.files[file] !== "string"
+      )
+        throw new Error("Next-development lacks exact declared file bytes");
+      return {
+        path: file,
+        beforeRoot: hash(before.files[file]),
+        afterRoot: hash(after.files[file]),
+        changed: before.files[file] !== after.files[file],
+      };
+    });
+  if (after.version !== transition.target.version)
+    throw new Error(
+      "Next-development materialization does not match its authorized target",
+    );
+  const body = {
+    targetVersion: transition.target.version,
+    anchorRoot: transition.target.anchor?.manifestRoot || null,
+    paths,
+  };
+  if (!transition.completedAlpha)
+    return stablePipelineDevelopmentReadback(
+      transition,
+      body,
+      evidence,
+      createdAt,
+      mergedAt,
+    );
+  let state = recordNextDevelopmentMaterialization(transition, {
+    materialization: {
+      ...body,
+      materializationRoot: nextDevelopmentRoot(body),
+    },
+    evidenceRoot: recordDigest(evidence),
+    recordedAt: new Date(createdAt).toISOString(),
+  });
+  state = advanceNextDevelopmentTransition(state, {
+    to: "pr-pending",
+    event: "protected-version-pr-observed",
+    evidenceRoot: recordDigest(evidence),
+    expectedStateRoot: state.state.stateRoot,
+    recordedAt: new Date(createdAt).toISOString(),
+  });
+  if (mergedAt)
+    for (const phase of ["merged", "verified"])
+      state = advanceNextDevelopmentTransition(state, {
+        to: phase,
+        event: `protected-version-${phase}`,
+        evidenceRoot: recordDigest(evidence),
+        expectedStateRoot: state.state.stateRoot,
+        recordedAt: new Date(mergedAt).toISOString(),
+      });
+  return state;
+}

package/packages/core/publication/pipeline/development-transition.js

@@ -0,0 +1,112 @@
+import {
+  createNextDevelopmentTransition,
+  bindNextDevelopmentAnchor,
+  nextDevelopmentRoot,
+} from "../../release/next-development-transition.js";
+import { createStableDevelopmentTransition } from "../publication-development.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export function createPipelineDevelopmentTransition(context, publication) {
+  const { plan, materialization } = context;
+  const input = {
+    repository: plan.source.repository,
+    model: {
+      strategy: plan.versionPolicy.strategy,
+      next: plan.versionPolicy.strategy === "semver" ? "auto" : "manual",
+    },
+    sourcePaths: [
+      ...new Set(plan.versionPolicy.files.map(({ path }) => path)),
+    ].sort(),
+    derivedPaths: [...(plan.versionPolicy.derived_files || [])].sort(),
+  };
+  const completed = {
+    outcome: "succeeded",
+    version: plan.version,
+    exactTag: plan.tag,
+    releaseSha: materialization.source.commit,
+    treeSha: materialization.source.tree,
+    publicationRoot: publication.release.receiptRoot,
+    completedAt: publication.completedAt,
+  };
+  if (plan.channel === "alpha")
+    return createNextDevelopmentTransition({
+      ...input,
+      completedAlpha: completed,
+    });
+  const adapter = {
+    sourcePaths: input.sourcePaths,
+    derivedPaths: input.derivedPaths,
+  };
+  if (input.model.strategy === "semver")
+    return {
+      ...createStableDevelopmentTransition({
+        ...input,
+        completedStable: completed,
+      }),
+      adapter,
+    };
+  const identity = {
+    contract: "buildchain.pipeline-stable-anchor-transition/v1",
+    ...input,
+    completedStable: completed,
+  };
+  return {
+    ...identity,
+    idempotencyKey: nextDevelopmentRoot(identity),
+    adapter,
+    target: { version: null, anchor: null },
+    state: { status: "waiting-anchor" },
+    publicationOutcome: "preserved-success",
+  };
+}
+
+export function bindPipelineDevelopmentAnchor(transition, input) {
+  if (transition.completedAlpha)
+    return bindNextDevelopmentAnchor(transition, input);
+  if (
+    transition.contract !== "buildchain.pipeline-stable-anchor-transition/v1" ||
+    transition.state.status !== "waiting-anchor" ||
+    !input.targetVersion ||
+    !input.anchor?.manifestRoot
+  )
+    throw new Error(
+      "Stable manual development requires its explicit protected anchor",
+    );
+  return {
+    ...transition,
+    target: { version: input.targetVersion, anchor: input.anchor },
+  };
+}
+
+export function stablePipelineDevelopmentReadback(
+  transition,
+  materialization,
+  evidence,
+  createdAt,
+  mergedAt,
+) {
+  if (
+    ![
+      "buildchain.stable-development-transition/v1",
+      "buildchain.pipeline-stable-anchor-transition/v1",
+    ].includes(transition.contract)
+  )
+    throw new Error("Unknown stable development transition");
+  const state = {
+    status: mergedAt ? "verified" : "pr-pending",
+    evidenceRoot: recordDigest(evidence),
+    recordedAt: new Date(mergedAt || createdAt).toISOString(),
+    materializationRoot: nextDevelopmentRoot(materialization),
+  };
+  return {
+    ...transition,
+    materialization,
+    state: {
+      ...state,
+      stateRoot: nextDevelopmentRoot({
+        transitionRoot: transition.idempotencyKey,
+        ...state,
+      }),
+    },
+  };
+}