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

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,85 @@
+import { recordDigest } from "../../release/discussion/envelope.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",
+    });
+  }
+  await journal.fence();
+  const materialization = await adapter.materializeDevelopment(request);
+  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,124 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { pipelineNpmChannel } from "../npm/pipeline-channel.js";
+import { applyPipelineEffects } from "./effects.js";
+import { compareDevelopmentVersions } from "../publication-development.js";
+
+export async function distributePipelineProducts(
+  context,
+  host,
+  journal,
+  retained,
+  environment,
+  directory,
+) {
+  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 npmTag = plan.channel === "alpha" ? "alpha" : "latest";
+  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 };
+    }
+    return npm.observe(effect);
+  }
+  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,
+      },
+    ];
+    for (const artifact of retained.qualified.artifacts.filter((entry) =>
+      entry.targets.some(({ provider }) => provider === "npm"),
+    ))
+      raw.push({
+        id: `npm-channel:${artifact.id}`,
+        kind: "npm-channel",
+        name: artifact.package.name,
+        access: artifact.targets.find(({ provider }) => provider === "npm")
+          .access,
+        tag: npmTag,
+        version: plan.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",
+        );
+      if (
+        effect.kind === "npm-channel" &&
+        current.version &&
+        compareDevelopmentVersions(current.version, effect.version) > 0
+      )
+        throw new Error("npm channel cannot regress a newer published version");
+      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 } },
+        );
+      }
+      await npm.apply(effect);
+    },
+  };
+  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,
+  };
+}