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

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

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

@@ -0,0 +1,130 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { pipelineNpmChannel } from "../npm/pipeline-channel.js";
+import { applyPipelineEffects, pipelinePublicationEffects } from "./effects.js";
+
+export async function distributePipelineProducts(
+  context,
+  host,
+  journal,
+  retained,
+  environment,
+) {
+  const { plan, materialization } = context;
+  const channel = `v${plan.version.split(".")[0]}${plan.channel === "alpha" ? "-alpha" : ""}`;
+  const refPath = `/repos/${host.repository}/git/ref/tags/${channel}`;
+  const npm = pipelineNpmChannel({ environment });
+  async function observe(effect) {
+    if (effect.kind === "git-channel") {
+      const value = await host.request(refPath, { allow404: true });
+      if (value && value.object?.type !== "commit")
+        throw new Error("Floating channel requires a lightweight commit ref");
+      return value
+        ? { state: "present", commit: value.object.sha }
+        : { state: "absent", commit: null };
+    }
+    // Only retained historical plans contain npm channel effects. New releases
+    // set their channel in npm publish and never enter a separate npm operation.
+    const value = await npm.observe(effect);
+    if (value.version !== effect.version)
+      throw new Error(
+        `Historical npm channel ${effect.name}@${effect.tag} requires a one-time authenticated correction to ${effect.version}; recovery never republishes or rewrites npm tags`,
+      );
+    return value;
+  }
+  const plans = await journal.materials("publication/distribution-plan/");
+  if (plans.length > 1)
+    throw new Error("Distribution has conflicting retained plans");
+  let effects = plans[0]?.effects;
+  if (!effects) {
+    const raw = [
+      {
+        id: "git-channel",
+        kind: "git-channel",
+        channel,
+        commit: materialization.source.commit,
+      },
+    ];
+    const receipts = await journal.materials("publication/effect/");
+    if (receipts.length) {
+      const published = pipelinePublicationEffects({
+        plan,
+        ...retained,
+        receipts,
+      });
+      for (const effect of published.filter(
+        (item) =>
+          item.kind === "npm-package" && item.tag.startsWith("buildchain-"),
+      ))
+        raw.push({
+          id: `npm-channel:${effect.product}`,
+          kind: "npm-channel",
+          name: effect.name,
+          access: effect.access,
+          tag: plan.channel === "alpha" ? "alpha" : "latest",
+          version: effect.version,
+        });
+    }
+    effects = [];
+    for (const effect of raw) {
+      const before = await observe(effect);
+      const body = { ...effect, expected: before };
+      effects.push({ ...body, root: recordDigest(body) });
+    }
+    await journal.record(
+      "publication/distribution-plan",
+      { planRoot: plan.root, effects },
+      { phase: "distribution" },
+    );
+  }
+  const matches = (effect, value) =>
+    value.state === "present" &&
+    (effect.kind === "git-channel"
+      ? value.commit === effect.commit
+      : value.version === effect.version);
+  const provider = {
+    observe,
+    matches,
+    canApply: (effect, value) =>
+      recordDigest(value) === recordDigest(effect.expected),
+    async apply(effect) {
+      const current = await observe(effect);
+      if (matches(effect, current)) return;
+      if (recordDigest(current) !== recordDigest(effect.expected))
+        throw new Error(
+          "Floating channel changed since retained distribution admission",
+        );
+      await journal.fence();
+      if (effect.kind === "git-channel") {
+        if (current.state === "absent")
+          return host.request(`/repos/${host.repository}/git/refs`, {
+            method: "POST",
+            body: { ref: `refs/tags/${channel}`, sha: effect.commit },
+          });
+        // Provider-enforced fast-forward preserves published history. A
+        // divergent channel requires a separately proved source reconciliation.
+        return host.request(
+          `/repos/${host.repository}/git/refs/tags/${channel}`,
+          { method: "PATCH", body: { sha: effect.commit, force: false } },
+        );
+      }
+      throw new Error("Distribution cannot write npm channels");
+    },
+  };
+  const receipts = await applyPipelineEffects({
+    effects,
+    transactionRoot: retained.documents.transaction.transactionRoot,
+    receipts: await journal.materials("publication/distribution-effect/"),
+    provider,
+    fence: journal.fence,
+    retain: (receipt) =>
+      journal.record("publication/distribution-effect", receipt, {
+        phase: "distribution",
+      }),
+  });
+  return {
+    schema: "buildchain.pipeline-distribution-complete/v1",
+    planRoot: plan.root,
+    effects,
+    receipts,
+  };
+}

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

@@ -0,0 +1,192 @@
+import { createHash } from "node:crypto";
+import {
+  canonicalJson,
+  recordDigest,
+} from "../../release/discussion/envelope.js";
+import { releaseTailRoot } from "../../release/release-tail-provider-plane.js";
+import {
+  RELEASE_INVOCATION_CONTRACT,
+  RELEASE_PROVIDER_CONTRACT,
+  createReleaseInvocation,
+  createDomainReleaseTransaction,
+} from "../../release/release-invocation.js";
+import {
+  validatePublicationQualificationReceipt,
+  domainPublicationQualificationRoot,
+} from "../publication-qualification.js";
+import { verifyPipelinePublicationPlan } from "./plan.js";
+
+export function pipelineReleaseEvidence({
+  plan,
+  qualified,
+  capsules,
+  documents,
+  bundle,
+}) {
+  verifyPipelinePublicationPlan(plan);
+  if (plan.evidenceVersion !== undefined && plan.evidenceVersion !== 1)
+    throw new Error("Unsupported retained publication evidence version");
+  // An older retained transaction keeps its original evidence inventory.
+  // Adding a disclosure during recovery would change its provider receipt.
+  const values = {
+    ...(plan.evidenceVersion === 1 ? { plan } : {}),
+    qualification: qualified,
+    capsules,
+    invocation: documents.invocation.invocation,
+  };
+  const bytes = Object.entries(values).map(([id, value]) => [
+    id,
+    Buffer.from(`${canonicalJson(value)}\n`),
+  ]);
+  bytes.push(["attestation", Buffer.from(bundle)]);
+  return bytes.map(([id, value]) => ({
+    id,
+    name: `buildchain.${id}.json`,
+    bytes: value,
+    size: value.length,
+    digest: `sha256:${createHash("sha256").update(value).digest("hex")}`,
+  }));
+}
+
+export function verifyRootedPublication(value, schema) {
+  const { root, ...body } = value || {};
+  if (body.schema !== schema || root !== recordDigest(body))
+    throw new Error(`Invalid retained ${schema} bytes`);
+  return value;
+}
+
+export function verifyPipelineQualification({
+  plan,
+  materialization,
+  qualified,
+  evaluatedAt,
+}) {
+  verifyPipelinePublicationPlan(plan);
+  verifyRootedPublication(
+    materialization,
+    "buildchain.pipeline-version-materialization/v1",
+  );
+  verifyRootedPublication(
+    qualified,
+    "buildchain.pipeline-publication-qualification/v1",
+  );
+  if (
+    qualified.planRoot !== plan.root ||
+    materialization.planRoot !== plan.root ||
+    recordDigest(materialization.protectedSource) !==
+      recordDigest(plan.source) ||
+    recordDigest(qualified.source) !== recordDigest(materialization.source) ||
+    materialization.material.version !== plan.version
+  )
+    throw new Error(
+      "Publication plan, materialized source and qualification differ",
+    );
+  const artifacts = qualified.artifacts
+    .map((artifact) => ({
+      role: `${artifact.product}/${artifact.artifact}`,
+      platform: artifact.platform,
+      artifactRoot: artifact.digest,
+      manifestRoot: artifact.manifestRoot,
+    }))
+    .sort((a, b) =>
+      `${a.role}\0${a.platform}`.localeCompare(`${b.role}\0${b.platform}`),
+    );
+  validatePublicationQualificationReceipt(qualified.qualification, {
+    repository: plan.source.repository,
+    sourceSha: qualified.source.commit,
+    sourceRoot: recordDigest(qualified.source),
+    candidateRoot: recordDigest({
+      planRoot: plan.root,
+      source: qualified.source,
+      artifacts: qualified.artifacts,
+    }),
+    artifactRoot: domainPublicationQualificationRoot(artifacts),
+    policyDigest: plan.contractRoot,
+    ...(evaluatedAt ? { evaluatedAt } : {}),
+  });
+  return qualified;
+}
+
+export function pipelineReleaseDocuments({
+  plan,
+  materialization,
+  qualified,
+  capsules,
+  signing,
+  evaluatedAt,
+}) {
+  verifyPipelineQualification({
+    plan,
+    materialization,
+    qualified,
+    evaluatedAt,
+  });
+  verifyRootedPublication(capsules, "buildchain.pipeline-product-capsules/v1");
+  if (
+    capsules.qualificationRoot !== qualified.root ||
+    signing.planRoot !== plan.root ||
+    signing.qualificationRoot !== qualified.root ||
+    signing.materializationRoot !== materialization.root ||
+    signing.verified !== true
+  )
+    throw new Error(
+      "Release requires independently verified signing and capsules for this qualification",
+    );
+  // The Rust domain still owns publisher admission and QUALIFY/APPLY/SETTLE.
+  const invocation = createReleaseInvocation({
+    schema: RELEASE_INVOCATION_CONTRACT,
+    publisher: plan.publisher,
+    runtime: plan.runtime,
+    candidate: {
+      repository: qualified.source.repository,
+      commit: qualified.source.commit,
+      tree: qualified.source.tree,
+      version: plan.version,
+    },
+    target: {
+      channel: plan.channel,
+      tag: plan.tag,
+      expectedOldSha: plan.expectedTagSha,
+    },
+    authority: {
+      policyRoot: plan.contractRoot,
+      qualificationRoot: qualified.qualification.receiptRoot,
+      warrantRoot: qualified.qualification.receiptRoot,
+    },
+    provider: {
+      adapter: "built-in-provider-plane",
+      contract: RELEASE_PROVIDER_CONTRACT,
+      repository: qualified.source.repository,
+    },
+    parent: { invocationRoot: null, transactionRoot: null, receiptRoot: null },
+  });
+  const transaction = createDomainReleaseTransaction({
+    invocationRoot: invocation.roots.invocationRoot,
+    publisherRoot: invocation.roots.publisherRoot,
+    runtimeRoot: invocation.roots.runtimeRoot,
+    providerRoot: invocation.roots.providerRoot,
+    parentRoot: invocation.roots.parentRoot,
+  });
+  const body = {
+    schema: "kungfu.buildchain.release-passport/v4",
+    repository: qualified.source.repository,
+    source: qualified.source,
+    // This binding explicitly retains the declared version overlay. It never
+    // claims tree equivalence with the protected commit.
+    versionMaterialization: materialization,
+    release: { version: plan.version, tag: plan.tag, channel: plan.channel },
+    candidateRoot: qualified.qualification.candidateRoot,
+    policyDigest: qualified.qualification.policyDigest,
+    artifactRoot: qualified.qualification.artifactRoot,
+    publicationQualificationRoot: qualified.qualification.receiptRoot,
+    stageCapsuleAggregateRoot: capsules.root,
+    stageCapsuleRoots: capsules.capsules
+      .map(({ capsule }) => capsule.capsuleRoot)
+      .sort(),
+    signingRoot: recordDigest(signing),
+    invocationRoot: invocation.roots.invocationRoot,
+    transactionRoot: transaction.transactionRoot,
+  };
+  const passport = { ...body, passportRoot: releaseTailRoot(body) };
+  return { invocation, transaction, passport };
+}