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

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

@@ -0,0 +1,156 @@
+import { 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 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 };
+}

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

@@ -0,0 +1,162 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+const KINDS = new Set([
+  "exact-tag",
+  "npm-package",
+  "release-asset",
+  "release-visibility",
+  "npm-channel",
+  "git-channel",
+]);
+
+export function pipelinePublicationEffects({
+  plan,
+  qualified,
+  documents,
+  evidence = [],
+}) {
+  const effects = [
+    {
+      id: "exact-tag",
+      kind: "exact-tag",
+      tag: plan.tag,
+      commit: qualified.source.commit,
+    },
+  ];
+  for (const artifact of qualified.artifacts) {
+    for (const target of artifact.targets) {
+      if (target.provider === "npm")
+        effects.push({
+          id: `npm:${artifact.id}`,
+          kind: "npm-package",
+          product: artifact.id,
+          name: artifact.package.name,
+          version: artifact.package.version,
+          integrity: artifact.package.integrity,
+          access: target.access || "public",
+          tag: `buildchain-${plan.root.slice(7, 23)}`,
+        });
+      if (target.provider === "github-release")
+        effects.push({
+          id: `asset:${artifact.id}`,
+          kind: "release-asset",
+          product: artifact.id,
+          tag: plan.tag,
+          name: artifact.file.split("/").at(-1),
+          digest: artifact.digest,
+          size: artifact.size,
+        });
+    }
+  }
+  for (const asset of evidence)
+    effects.push({
+      id: `evidence:${asset.id}`,
+      kind: "release-asset",
+      product: `evidence:${asset.id}`,
+      tag: plan.tag,
+      name: asset.name,
+      digest: asset.digest,
+      size: asset.size,
+    });
+  effects.push({
+    id: "release-passport",
+    kind: "release-asset",
+    product: "release-passport",
+    tag: plan.tag,
+    name: "buildchain.release.json",
+    documentRoot: documents.passport.passportRoot,
+  });
+  effects.push({
+    id: "release-visibility",
+    kind: "release-visibility",
+    tag: plan.tag,
+    prerelease: plan.channel === "alpha",
+  });
+  return effects.map((effect) => ({ ...effect, root: recordDigest(effect) }));
+}
+
+// This executor owns only bounded provider operations. Journal admission/fencing
+// and provider implementations are required dependencies, never consumer hooks.
+// Each irreversible success is retained before a later operation is attempted.
+export async function applyPipelineEffects({
+  effects,
+  transactionRoot,
+  receipts,
+  provider,
+  fence,
+  retain,
+}) {
+  const results = [];
+  for (const effect of effects) {
+    const { root, ...body } = effect;
+    if (!KINDS.has(effect.kind) || root !== recordDigest(body))
+      throw new Error("Unrecognized or modified publication effect");
+    await fence();
+    const prior = receipts.filter((receipt) => receipt.effectId === effect.id);
+    if (
+      prior.some(
+        (receipt) =>
+          receipt.effectRoot !== root ||
+          receipt.transactionRoot !== transactionRoot,
+      )
+    )
+      throw new Error(
+        "Publication effect conflicts with immutable prior intent",
+      );
+    const completed = prior.find((receipt) => receipt.state === "success");
+    let observed = await provider.observe(effect);
+    if (completed) {
+      if (!provider.matches(effect, observed))
+        throw new Error(
+          "A completed publication no longer matches provider bytes",
+        );
+      results.push(completed);
+      continue;
+    }
+    if (
+      observed.state !== "absent" &&
+      !provider.matches(effect, observed) &&
+      !provider.canApply?.(effect, observed)
+    )
+      throw new Error(
+        "Publication destination already contains conflicting bytes",
+      );
+    if (!prior.length)
+      await retain(rootedReceipt(effect, transactionRoot, "pending", observed));
+    if (!provider.matches(effect, observed)) {
+      await fence();
+      // Preserve unknown outcomes. A lost response is reconciled from provider
+      // state before any retry; absence still propagates the original failure.
+      let failure;
+      try {
+        await provider.apply(effect);
+      } catch (error) {
+        failure = error;
+      }
+      observed = await provider.observe(effect);
+      if (!provider.matches(effect, observed)) {
+        if (failure) throw failure;
+        throw new Error(
+          "Publication write lacks exact successful provider readback",
+        );
+      }
+    }
+    await fence();
+    const receipt = rootedReceipt(effect, transactionRoot, "success", observed);
+    await retain(receipt);
+    results.push(receipt);
+  }
+  return results;
+}
+
+function rootedReceipt(effect, transactionRoot, state, observed) {
+  const body = {
+    schema: "buildchain.pipeline-publication-effect/v1",
+    effectId: effect.id,
+    effectRoot: effect.root,
+    transactionRoot,
+    state,
+    observed,
+  };
+  return { ...body, root: recordDigest(body) };
+}

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

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+export function publicationPath(root, relative, kind = "file") {
+  const base = fs.realpathSync(root);
+  const target = path.resolve(base, relative);
+  if (target !== base && !target.startsWith(`${base}${path.sep}`))
+    throw new Error("Publication path escapes its owned directory");
+  let current = base;
+  for (const part of path
+    .relative(base, target)
+    .split(path.sep)
+    .filter(Boolean)) {
+    current = path.join(current, part);
+    if (fs.lstatSync(current).isSymbolicLink())
+      throw new Error("Publication paths cannot traverse symbolic links");
+  }
+  const stat = fs.statSync(target);
+  if (
+    (kind === "file" && !stat.isFile()) ||
+    (kind === "directory" && !stat.isDirectory())
+  )
+    throw new Error(`Publication expected a ${kind}`);
+  return target;
+}
+
+export function publicationFile(file) {
+  const size = fs.statSync(file).size;
+  if (!size || size > 256 * 1024 * 1024)
+    throw new Error("Publication artifact must contain 1 byte to 256 MiB");
+  const bytes = fs.readFileSync(file);
+  if (!bytes.length || bytes.length > 256 * 1024 * 1024)
+    throw new Error("Publication artifact must contain 1 byte to 256 MiB");
+  return {
+    bytes,
+    size: bytes.length,
+    digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+    integrity: `sha512-${createHash("sha512").update(bytes).digest("base64")}`,
+  };
+}
+
+export function writeImmutablePublicationFile(file, bytes) {
+  // Refuse parent symlinks before mkdir/write, including during recovery into
+  // an existing output directory.
+  let parent = path.dirname(path.resolve(file));
+  while (parent !== path.dirname(parent)) {
+    if (fs.existsSync(parent) && fs.lstatSync(parent).isSymbolicLink())
+      throw new Error("Publication output cannot traverse symbolic links");
+    parent = path.dirname(parent);
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  try {
+    fs.writeFileSync(file, bytes, { flag: "wx" });
+  } catch (error) {
+    if (
+      error.code !== "EEXIST" ||
+      fs.lstatSync(file).isSymbolicLink() ||
+      !fs.readFileSync(file).equals(Buffer.from(bytes))
+    )
+      throw new Error(
+        `Publication refuses conflicting retained bytes: ${path.basename(file)}`,
+      );
+  }
+  return file;
+}

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

@@ -0,0 +1,32 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export const PUBLICATION_IMPORT = "buildchain.pipeline-publication-import/v1";
+
+export function publicationImportedValues(value) {
+  const { root, ...body } = value;
+  if (
+    body.schema !== PUBLICATION_IMPORT ||
+    root !== recordDigest(body) ||
+    !Array.isArray(body.values) ||
+    !body.values.length ||
+    body.values.length > 1000
+  )
+    throw new Error(
+      "Publication import is not one bounded immutable material bundle",
+    );
+  const ids = new Set();
+  for (const item of body.values) {
+    if (
+      typeof item.id !== "string" ||
+      !item.id.startsWith("publication/") ||
+      /^publication\/(?:worker|context|recovery-import)\//u.test(item.id) ||
+      ids.has(item.id) ||
+      !item.id.endsWith(`/${recordDigest(item.value).slice(7)}`)
+    )
+      throw new Error(
+        "Publication import contains duplicate, recursive or unbound materials",
+      );
+    ids.add(item.id);
+  }
+  return body.values;
+}

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

@@ -0,0 +1,110 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { assertPipelineExecution } from "../../workflow/pipeline/fence.js";
+import {
+  PUBLICATION_IMPORT,
+  publicationImportedValues,
+} from "./imported-materials.js";
+
+export function pipelinePublicationJournal(session, host) {
+  const initial = session.observed;
+  const expected = {
+    attempt: initial.attempt,
+    generation: initial.generation,
+    intent: session.intent.id,
+    sourceRoot: recordDigest(initial.history.at(-1).generation.source),
+  };
+  const store = host.materialStore(session);
+  async function fence() {
+    const observed = await session.journal.read();
+    assertPipelineExecution(observed, expected);
+    const writer = observed.history
+      .at(-1)
+      .events.filter((event) =>
+        event.payload.materials.some((material) =>
+          material.id.startsWith("publication/worker/"),
+        ),
+      )
+      .at(-1)?.payload.writer;
+    if (
+      writer &&
+      (writer.runId !== String(host.runId) ||
+        writer.runAttempt !== String(host.runAttempt))
+    )
+      throw new Error(
+        "Publication worker lost its exact provider execution reservation",
+      );
+    return observed;
+  }
+  async function materials(prefix) {
+    const observed = await session.journal.read();
+    if (observed.attempt !== initial.attempt)
+      throw new Error("Publication journal is no longer the current attempt");
+    const references = observed.history
+      .at(-1)
+      .events.flatMap((event) => event.payload.materials)
+      .filter(
+        (reference) =>
+          reference.id.startsWith(prefix) ||
+          reference.id.startsWith("publication/recovery-import/"),
+      );
+    const unique = [
+      ...new Map(
+        references.map((reference) => [reference.digest, reference]),
+      ).values(),
+    ];
+    const values = [];
+    for (const reference of unique) {
+      const value = await store.read(reference);
+      if (value.schema === PUBLICATION_IMPORT)
+        values.push(
+          ...publicationImportedValues(value)
+            .filter((item) => item.id.startsWith(prefix))
+            .map((item) => item.value),
+        );
+      else if (reference.id.startsWith(prefix)) values.push(value);
+    }
+    return [
+      ...new Map(values.map((value) => [recordDigest(value), value])).values(),
+    ];
+  }
+  async function record(
+    id,
+    value,
+    { phase = "publish", state = "running", expectedHead } = {},
+  ) {
+    const root = recordDigest(value);
+    const observed = await session.journal.read();
+    const eventKey = `publication:${id}:${root}`;
+    const prior = observed.history
+      .at(-1)
+      .events.find((event) => event.payload.eventKey === eventKey);
+    if (prior) {
+      if (
+        observed.attempt !== initial.attempt ||
+        prior.node !== phase ||
+        prior.payload.state !== state ||
+        prior.payload.materials.length !== 1 ||
+        recordDigest(await store.read(prior.payload.materials[0])) !== root
+      )
+        throw new Error(
+          "Publication retry changed its immutable recorded result",
+        );
+      return value;
+    }
+    const reference = await store.retain(
+      `${id}/${root.slice(7)}`,
+      value,
+      "receipt",
+    );
+    await session.progress.progress({
+      attempt: initial.attempt,
+      phase,
+      state,
+      eventKey,
+      materials: [reference],
+      ...(expectedHead !== undefined ? { expectedHead } : {}),
+    });
+    return value;
+  }
+  return { fence, materials, record };
+}

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

@@ -0,0 +1,116 @@
+import { observeAdvancedPipelineDevelopment } from "./development-current.js";
+import { createPipelineDevelopmentTransition } from "./development-transition.js";
+import { githubPipelineVersion } from "../../providers/github/pipeline-version.js";
+import { uniquePublicationMaterial } from "./context.js";
+import { observePipelineVersionAnchor } from "./development-anchor.js";
+import { developmentTransitionReadback } from "./development-proof.js";
+import { prepareNextDevelopmentPullRequest } from "./development-pr.js";
+
+export async function nextPipelineDevelopment(context, host, journal) {
+  const { plan } = context;
+  const publication = await uniquePublicationMaterial(
+    journal,
+    "publication/complete/",
+  );
+  const transitions = await journal.materials(
+    "publication/next-development-plan/",
+  );
+  if (transitions.length > 1)
+    throw new Error("Next-development has conflicting retained declarations");
+  let transition = transitions[0];
+  if (!transition) {
+    transition = createPipelineDevelopmentTransition(context, publication);
+    await journal.record("publication/next-development-plan", transition, {
+      phase: "next-development",
+    });
+  }
+  if (transition.model.strategy === "anchored")
+    return observePipelineVersionAnchor(context, host, transition);
+  const retained = await journal.materials("publication/next-development-pr/");
+  if (retained.length > 1)
+    throw new Error("Next-development has conflicting retained PRs");
+  let selected = retained[0];
+  const adapter = githubPipelineVersion(host.request, host.repository);
+  if (!selected) {
+    const advanced = await observeAdvancedPipelineDevelopment(
+      context,
+      host,
+      transition,
+      adapter,
+    );
+    if (advanced) return advanced;
+    selected = await prepareNextDevelopmentPullRequest(
+      context,
+      host,
+      journal,
+      transition,
+      adapter,
+    );
+  }
+  const pr = await host.request(
+    `/repos/${host.repository}/pulls/${selected.number}`,
+  );
+  if (
+    pr.head?.sha !== selected.source.commit ||
+    pr.head?.ref !== selected.branch ||
+    pr.base?.ref !== selected.base ||
+    pr.head?.repo?.full_name !== host.repository
+  )
+    throw new Error(
+      "Next-development PR changed its retained source or target",
+    );
+  const before = await adapter.inspect(
+    selected.materialization.protectedSource,
+    plan.versionPolicy,
+  );
+  const after = await adapter.inspect(selected.source, plan.versionPolicy);
+  const pending = developmentTransitionReadback(transition, {
+    before,
+    after,
+    evidence: selected,
+    createdAt: pr.created_at,
+  });
+  if (!pr.merged)
+    return {
+      state: "waiting",
+      reason:
+        pr.state === "open"
+          ? "next-development-protected-pr-pending"
+          : "next-development-pr-closed",
+      pullRequest: selected.number,
+      source: selected.source,
+      transition: pending,
+    };
+  const integration = await host.integration.observe({
+    intent: {
+      source: { pullRequest: selected.number, targetBranch: selected.base },
+    },
+    generation: {
+      source: { ...selected.source, configPath: plan.source.configPath },
+    },
+  });
+  const source = await host.source.source(
+    integration.mergeCommit,
+    plan.source.configPath,
+  );
+  const readback = await adapter.inspect(source.identity, plan.versionPolicy);
+  if (readback.version !== transition.target.version)
+    throw new Error(
+      "Protected next-development version readback differs from its declaration",
+    );
+  return {
+    state: "success",
+    reason: "protected-next-development-verified",
+    transitionRoot: transition.idempotencyKey,
+    integration,
+    version: readback.version,
+    publicationRoot: publication.release.receiptRoot,
+    transition: developmentTransitionReadback(transition, {
+      before,
+      after: readback,
+      evidence: integration,
+      createdAt: pr.created_at,
+      mergedAt: pr.merged_at,
+    }),
+  };
+}