@kungfu-tech/buildchain 4.0.1 → 4.0.2-alpha.10

package/packages/core/dev-delivery-writer-protocol-transition.js

@@ -0,0 +1,72 @@
+import { devDeliveryContentRoot } from "./dev-delivery-common.js";
+import {
+  DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT,
+  TERMINAL_STATES,
+  transitionDevDeliveryQueue,
+} from "./dev-delivery-warrant-state.js";
+
+export const DEV_DELIVERY_WRITER_PROTOCOL = Object.freeze({
+  schema: "kungfu.buildchain.dev-delivery-writer-protocol/v1",
+  requiredCandidateCapabilities: [
+    "environment-root-v1",
+    "native-command-contract-v1",
+  ],
+});
+export const DEV_DELIVERY_WRITER_PROTOCOL_FENCE_RECEIPT_SCHEMA =
+  "kungfu.buildchain.dev-delivery-writer-protocol-fence-receipt/v1";
+if (
+  devDeliveryContentRoot(DEV_DELIVERY_WRITER_PROTOCOL) !==
+  DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT
+) {
+  throw new Error("dev delivery writer protocol root drift");
+}
+
+export function fenceDevDeliveryWriterProtocol(
+  queueInput,
+  { now = new Date().toISOString() } = {},
+) {
+  const transaction = transitionDevDeliveryQueue(
+    queueInput,
+    (queue) => {
+      if (
+        queue.policy.minimumWriterProtocolRoot ===
+        DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT
+      ) {
+        return {
+          action: "minimum-writer-protocol-already-fenced",
+          preserveState: true,
+        };
+      }
+      if (
+        queue.activeWarrant ||
+        queue.candidates.some(
+          (candidate) => !TERMINAL_STATES.has(candidate.status),
+        )
+      ) {
+        throw new Error(
+          "minimum writer protocol can be fenced only while the queue is idle",
+        );
+      }
+      queue.policy.minimumWriterProtocolRoot =
+        DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT;
+      return { action: "minimum-writer-protocol-fenced" };
+    },
+    now,
+  );
+  const receipt = {
+    schema: DEV_DELIVERY_WRITER_PROTOCOL_FENCE_RECEIPT_SCHEMA,
+    action: transaction.result.action,
+    repository: transaction.after.repository,
+    protectedBase: transaction.after.protectedBase,
+    minimumWriterProtocolRoot: DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT,
+    expectedOldStateRoot: transaction.expectedOldStateRoot,
+    nextStateRoot: transaction.after.stateRoot,
+    nextAction:
+      "Use only a Buildchain runtime that preserves the rooted minimum writer protocol.",
+  };
+  return {
+    queue: transaction.after,
+    receipt,
+    receiptRoot: devDeliveryContentRoot(receipt),
+  };
+}

package/packages/core/release-tail-product-capabilities.js

@@ -0,0 +1,29 @@
+export const RELEASE_TAIL_PRODUCT_CAPABILITIES = Object.freeze([
+  Object.freeze({
+    id: "product.version-state.materialize",
+    executor: "provider-adapter",
+    adapter: "github-version-state",
+    effectKind: "product-version-state-materialization",
+    observationKind: "product-version-state-readback",
+    receiptKind: "product-version-state",
+    transactionState: "preparing",
+  }),
+  Object.freeze({
+    id: "product.package.publish",
+    executor: "provider-adapter",
+    adapter: "npm-trusted-publishing",
+    effectKind: "product-package-publication",
+    observationKind: "product-package-readback",
+    receiptKind: "product-package-publication",
+    transactionState: "publishing",
+  }),
+  Object.freeze({
+    id: "product.release-refs.converge",
+    executor: "provider-adapter",
+    adapter: "github-release-refs",
+    effectKind: "product-release-ref-convergence",
+    observationKind: "product-release-ref-readback",
+    receiptKind: "product-release-ref-convergence",
+    transactionState: "committing",
+  }),
+]);

package/packages/core/release-tail-provider-plane.js

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-
+import { RELEASE_TAIL_PRODUCT_CAPABILITIES } from "./release-tail-product-capabilities.js";
 export const RELEASE_TAIL_DECLARATION_CONTRACT =
   "kungfu-buildchain-release-tail-capabilities";
 export const RELEASE_TAIL_TRANSACTION_POLICY = "buildchain.release-tail/v1";
@@ -27,8 +27,8 @@ export const RELEASE_TAIL_STATES = Object.freeze([
   "repair-required",
   "terminal-failure",
 ]);
-
 export const RELEASE_TAIL_CAPABILITY_REGISTRY = Object.freeze([
+  ...RELEASE_TAIL_PRODUCT_CAPABILITIES,
   Object.freeze({
     id: "artifact.publish",
     executor: "provider-adapter",

package/packages/core/v4-canonical-contracts.js

@@ -56,11 +56,25 @@ const ROOT_DOMAINS = new Set([
   "stable-publication-fence",
   "partial-mutation-recovery-checkpoint",
   "partial-mutation-recovery-plan",
+  "v4-product-required-artifacts",
+  "v4-product-publication-intent",
+  "v4-product-publication-operation",
+  "v4-product-publication-plan",
   "tail-reseal-plan",
   "tail-reseal-admission",
   "tail-reseal-artifact-files",
   "tail-reseal-receipt",
   "release-candidate-passport",
+  "release-invocation-publisher",
+  "release-invocation-runtime",
+  "release-invocation-candidate",
+  "release-invocation-target",
+  "release-invocation-authority",
+  "release-invocation-provider",
+  "release-invocation-parent",
+  "release-invocation",
+  "release-transaction",
+  "release-receipt",
 ]);
 const FAULT_CLASSES = new Set([
   "validation",

package/packages/core/v4-floating-consumer-policy.js

@@ -302,8 +302,11 @@ function classifyBuildchainUses(records, failures, { repository } = {}) {
       parsed.selector === ALPHA_RECOVERY_BOOTSTRAP.selector;
     const protectedBootstrap =
       repository === BUILDCHAIN_REPOSITORY && bootstrapShape;
+    const unauthorizedBootstrap =
+      repository !== BUILDCHAIN_REPOSITORY && bootstrapShape;
     const channel =
-      CHANNELS[parsed.selector] || (protectedBootstrap ? "alpha" : "");
+      !unauthorizedBootstrap &&
+      (CHANNELS[parsed.selector] || (protectedBootstrap ? "alpha" : ""));
     uses.push({
       ...record,
       ...parsed,

package/packages/core/v4-product-publication.js

@@ -0,0 +1,387 @@
+import { v4ContentRoot, validateV4Root } from "./v4-canonical-contracts.js";
+import {
+  RELEASE_TAIL_DECLARATION_CONTRACT,
+  RELEASE_TAIL_EFFECT_SCHEMA,
+  RELEASE_TAIL_OBSERVATION_SCHEMA,
+  RELEASE_TAIL_RECEIPT_SCHEMA,
+  RELEASE_TAIL_TRANSACTION_POLICY,
+} from "./release-tail-provider-plane.js";
+import { RELEASE_TAIL_PRODUCT_CAPABILITIES } from "./release-tail-product-capabilities.js";
+
+export const V4_PRODUCT_PUBLICATION_INTENT_CONTRACT =
+  "kungfu-buildchain-v4-product-publication-intent/v1";
+export const V4_PRODUCT_PUBLICATION_PLAN_CONTRACT =
+  "kungfu-buildchain-v4-product-publication-plan/v1";
+
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-alpha\.(\d+))?$/u;
+const SHA = /^[0-9a-f]{40}$/u;
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+const REPOSITORY = /^[^/\s]+\/[^/\s]+$/u;
+
+function fail(message) {
+  throw new Error(`invalid v4 product publication: ${message}`);
+}
+
+function parseVersion(value, label) {
+  const normalized = String(value || "").trim();
+  const match = normalized.match(VERSION);
+  if (!match) fail(`${label} must be an exact stable or alpha version`);
+  return {
+    value: normalized,
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    alpha: match[4] === undefined ? null : Number(match[4]),
+  };
+}
+
+function channelName(value) {
+  if (value === "alpha") return "alpha";
+  if (["release", "stable", "major"].includes(value)) return "stable";
+  fail(`unsupported channel '${value}'`);
+}
+
+function assertLane({ channel, targetRef, version }) {
+  const expression =
+    channel === "alpha"
+      ? /^alpha\/v(\d+)\/v(\d+)\.(\d+)$/u
+      : /^release\/v(\d+)\/v(\d+)\.(\d+)$/u;
+  const match = String(targetRef || "").match(expression);
+  if (!match) fail(`target ref '${targetRef}' is not a ${channel} lane`);
+  if (
+    Number(match[1]) !== version.major ||
+    Number(match[2]) !== version.major ||
+    Number(match[3]) !== version.minor
+  )
+    fail("target ref does not match the publication version line");
+}
+
+function observedAlphaNumber(version, expected) {
+  const parsed = parseVersion(version, "observed version");
+  return parsed.major === expected.major &&
+    parsed.minor === expected.minor &&
+    parsed.patch === expected.patch
+    ? parsed.alpha
+    : null;
+}
+
+function requiredString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) fail(`${label} must be a non-empty string`);
+  return normalized;
+}
+
+function requiredRoot(value, label) {
+  const normalized = requiredString(value, label).toLowerCase();
+  if (!ROOT.test(normalized)) fail(`${label} must be a sha256 content root`);
+  return normalized;
+}
+
+export function selectV4ProductPublicationIntent({
+  channel,
+  targetRef,
+  sourceSha,
+  sourceTimestamp,
+  repository,
+  packageName,
+  distTag,
+  sealedBundleRoot,
+  requiredArtifactsRoot,
+  candidateVersion,
+  recoveredVersion = "",
+  observedVersions = [],
+}) {
+  const normalizedChannel = channelName(channel);
+  if (!SHA.test(String(sourceSha || "")))
+    fail("sourceSha must be an exact Git SHA");
+  if (!REPOSITORY.test(String(repository || "")))
+    fail("repository must be owner/repo");
+  const normalizedTimestamp = requiredString(
+    sourceTimestamp,
+    "sourceTimestamp",
+  );
+  if (Number.isNaN(Date.parse(normalizedTimestamp)))
+    fail("sourceTimestamp must be an ISO timestamp");
+  const normalizedPackageName = requiredString(packageName, "packageName");
+  const normalizedDistTag = requiredString(distTag, "distTag");
+  if (!/^[a-z0-9][a-z0-9._-]*$/u.test(normalizedDistTag))
+    fail("distTag must be an npm dist-tag");
+  if (!Array.isArray(observedVersions))
+    fail("observedVersions must be an array");
+  const candidate = parseVersion(candidateVersion, "candidateVersion");
+  assertLane({ channel: normalizedChannel, targetRef, version: candidate });
+  const observed = [...new Set(observedVersions.map(String))].sort();
+  let version;
+  let mode = "fresh";
+  if (String(recoveredVersion || "").trim()) {
+    const recovered = parseVersion(recoveredVersion, "recoveredVersion");
+    if (
+      recovered.major !== candidate.major ||
+      recovered.minor !== candidate.minor ||
+      recovered.patch !== candidate.patch ||
+      (normalizedChannel === "alpha" && recovered.alpha === null) ||
+      (normalizedChannel === "stable" && recovered.alpha !== null)
+    )
+      fail("recoveredVersion is incompatible with the candidate release line");
+    version = recovered.value;
+    mode = "resume";
+  } else if (normalizedChannel === "alpha") {
+    if (candidate.alpha === null)
+      fail("fresh alpha publication requires an alpha candidate version");
+    const highest = observed.reduce(
+      (current, entry) =>
+        Math.max(current, observedAlphaNumber(entry, candidate) ?? -1),
+      candidate.alpha,
+    );
+    version = `${candidate.major}.${candidate.minor}.${candidate.patch}-alpha.${highest + 1}`;
+  } else {
+    version = `${candidate.major}.${candidate.minor}.${candidate.patch}`;
+  }
+  const intent = {
+    schema: V4_PRODUCT_PUBLICATION_INTENT_CONTRACT,
+    mode,
+    channel: normalizedChannel,
+    targetRef,
+    sourceSha,
+    sourceTimestamp: new Date(normalizedTimestamp).toISOString(),
+    repository,
+    packageName: normalizedPackageName,
+    distTag: normalizedDistTag,
+    sealedBundleRoot: requiredRoot(sealedBundleRoot, "sealedBundleRoot"),
+    requiredArtifactsRoot: requiredRoot(
+      requiredArtifactsRoot,
+      "requiredArtifactsRoot",
+    ),
+    candidateVersion: candidate.value,
+    version,
+    exactTag: `v${version}`,
+    observedVersions: observed,
+  };
+  return {
+    ...intent,
+    intentRoot: v4ContentRoot("v4-product-publication-intent", intent),
+  };
+}
+
+function alphaReferences(intent, version) {
+  const line = `v${version.major}.${version.minor}`;
+  return [
+    { ref: `refs/tags/${intent.exactTag}`, target: "source" },
+    { ref: `refs/heads/${intent.targetRef}`, target: "version-state" },
+    {
+      ref: `refs/heads/dev/v${version.major}/${line}`,
+      target: "version-state",
+    },
+    { ref: `refs/tags/${line}-alpha`, target: "version-state" },
+    { ref: `refs/tags/v${version.major}-alpha`, target: "version-state" },
+  ];
+}
+
+function stableReferences(intent, version) {
+  return [
+    { ref: `refs/tags/${intent.exactTag}`, target: "source" },
+    { ref: `refs/heads/${intent.targetRef}`, target: "version-state" },
+    {
+      ref: `refs/tags/v${version.major}.${version.minor}`,
+      target: "version-state",
+    },
+    { ref: `refs/tags/v${version.major}`, target: "version-state" },
+  ];
+}
+
+export function createV4ProductPublicationPlan({
+  intent,
+  invocationRoot,
+  transactionRoot,
+}) {
+  validateV4Root(invocationRoot, "$/productPlan/invocationRoot");
+  validateV4Root(transactionRoot, "$/productPlan/transactionRoot");
+  const selected = selectV4ProductPublicationIntent({
+    channel: intent.channel,
+    targetRef: intent.targetRef,
+    sourceSha: intent.sourceSha,
+    sourceTimestamp: intent.sourceTimestamp,
+    repository: intent.repository,
+    packageName: intent.packageName,
+    distTag: intent.distTag,
+    sealedBundleRoot: intent.sealedBundleRoot,
+    requiredArtifactsRoot: intent.requiredArtifactsRoot,
+    candidateVersion: intent.candidateVersion,
+    recoveredVersion: intent.mode === "resume" ? intent.version : "",
+    observedVersions: intent.observedVersions,
+  });
+  if (selected.intentRoot !== intent.intentRoot)
+    fail("intentRoot does not match the canonical publication intent");
+  const parsed = parseVersion(intent.version, "intent.version");
+  const references =
+    intent.channel === "alpha"
+      ? alphaReferences(intent, parsed)
+      : stableReferences(intent, parsed);
+  const stateRef = `refs/heads/buildchain/v4-product-state/${intent.sourceSha}-${intent.version.replaceAll(".", "-")}`;
+  const operations = [
+    {
+      id: "product.version-state.materialize",
+      adapter: "github-version-state",
+      authority: "contents-write",
+      target: {
+        repository: intent.repository,
+        version: intent.version,
+        sourceSha: intent.sourceSha,
+        sourceTimestamp: intent.sourceTimestamp,
+        stateRef,
+      },
+    },
+    {
+      id: "product.package.publish",
+      adapter: "npm-trusted-publishing",
+      authority: "oidc-provider-mutation",
+      target: {
+        packageName: intent.packageName,
+        version: intent.version,
+        distTag: intent.distTag,
+        sealedBundleRoot: intent.sealedBundleRoot,
+        requiredArtifactsRoot: intent.requiredArtifactsRoot,
+      },
+    },
+    {
+      id: "product.release-refs.converge",
+      adapter: "github-release-refs",
+      authority: "contents-write",
+      target: {
+        repository: intent.repository,
+        sourceSha: intent.sourceSha,
+        stateRef,
+        references,
+      },
+    },
+  ].map((operation) => ({
+    ...operation,
+    operationRoot: v4ContentRoot("v4-product-publication-operation", operation),
+  }));
+  const plan = {
+    schema: V4_PRODUCT_PUBLICATION_PLAN_CONTRACT,
+    intentRoot: intent.intentRoot,
+    invocationRoot,
+    transactionRoot,
+    operationOrder: operations.map(({ id }) => id),
+    operations,
+  };
+  return {
+    ...plan,
+    planRoot: v4ContentRoot("v4-product-publication-plan", plan),
+  };
+}
+
+const PRODUCT_CAPABILITIES = Object.fromEntries(
+  RELEASE_TAIL_PRODUCT_CAPABILITIES.map((capability) => [
+    capability.id,
+    {
+      ...capability,
+      destinationKind:
+        capability.id === "product.package.publish"
+          ? "npm-package"
+          : capability.adapter,
+    },
+  ]),
+);
+
+function exactTagPattern(tag) {
+  return `^${tag.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}$`;
+}
+
+export function createV4ProductPublicationDeclaration({ intent, plan }) {
+  const rebuilt = createV4ProductPublicationPlan({
+    intent,
+    invocationRoot: plan.invocationRoot,
+    transactionRoot: plan.transactionRoot,
+  });
+  if (rebuilt.planRoot !== plan.planRoot)
+    fail("planRoot does not match the canonical publication plan");
+  const operationById = new Map(
+    plan.operations.map((operation) => [operation.id, operation]),
+  );
+  return {
+    contract: RELEASE_TAIL_DECLARATION_CONTRACT,
+    schemaVersion: 1,
+    transactionPolicy: RELEASE_TAIL_TRANSACTION_POLICY,
+    subject: {
+      repository: intent.repository,
+      sourceSha: intent.sourceSha,
+      version: intent.version,
+      tag: intent.exactTag,
+      channel: intent.channel,
+    },
+    capabilities: plan.operationOrder.map((id) => {
+      const operation = operationById.get(id);
+      const descriptor = PRODUCT_CAPABILITIES[id];
+      if (!operation || !descriptor)
+        fail(`unsupported product publication operation '${id}'`);
+      return {
+        id,
+        executor: "provider-adapter",
+        adapter: operation.adapter,
+        artifactRoles: [
+          { role: "publication-intent", root: intent.intentRoot },
+          ...(id === "product.package.publish"
+            ? [
+                { role: "sealed-bundle", root: intent.sealedBundleRoot },
+                {
+                  role: "required-artifacts",
+                  root: intent.requiredArtifactsRoot,
+                },
+              ]
+            : []),
+        ],
+        destination: {
+          kind: descriptor.destinationKind,
+          locator: `${operation.adapter}:${operation.operationRoot}`,
+        },
+        channelPolicy: {
+          channel: intent.channel,
+          tagPattern: exactTagPattern(intent.exactTag),
+          authorityMove:
+            id === "product.package.publish" ? "none" : "verified-ref",
+        },
+        activationPolicy: { mode: "none", environment: "none" },
+        readbackPredicates: [
+          {
+            id: `${id}.target-root`,
+            kind: "exact-root",
+            expected: operation.operationRoot,
+          },
+        ],
+        effect: {
+          schema: RELEASE_TAIL_EFFECT_SCHEMA,
+          kind: descriptor.effectKind,
+        },
+        observation: {
+          schema: RELEASE_TAIL_OBSERVATION_SCHEMA,
+          kind: descriptor.observationKind,
+        },
+        receipt: {
+          schema: RELEASE_TAIL_RECEIPT_SCHEMA,
+          kind: descriptor.receiptKind,
+        },
+        operationIdentity: {
+          transactionRoot: plan.transactionRoot,
+          capabilityId: id,
+          subjectRoot: intent.intentRoot,
+          targetRoot: operation.operationRoot,
+          attemptKey: `${plan.planRoot}:${id}`,
+        },
+        idempotency: {
+          scope: "subject-target",
+          duplicate: "readback-before-retry",
+        },
+        retry: {
+          class: "provider-transient",
+          localAttempts: 1,
+          exhausted: "blocked",
+        },
+        evidenceRequirements: [
+          "provider readback must match the rooted publication operation",
+        ],
+      };
+    }),
+  };
+}

package/packages/core/v4-protected-publication-source.js

@@ -0,0 +1,93 @@
+import { v4ContentRoot } from "./v4-canonical-contracts.js";
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/u;
+
+function exactSha(value, label) {
+  const normalized = String(value || "").toLowerCase();
+  if (!SHA_PATTERN.test(normalized)) {
+    throw new Error(`${label} must be an exact Git SHA`);
+  }
+  return normalized;
+}
+
+function exactParents(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an ordered Git parent list`);
+  }
+  return value.map((entry, index) => exactSha(entry, `${label}[${index}]`));
+}
+
+export function bindV4ProtectedPublicationSource({
+  repository,
+  protectedCommit,
+  candidateCommit,
+  pullRequest,
+} = {}) {
+  if (!/^[^/\s]+\/[^/\s]+$/u.test(String(repository || ""))) {
+    throw new Error("protected publication source requires owner/repository");
+  }
+  const protectedSource = {
+    sha: exactSha(protectedCommit?.sha, "protected source SHA"),
+    tree: exactSha(protectedCommit?.tree, "protected source tree"),
+    parents: exactParents(protectedCommit?.parents, "protected source parents"),
+  };
+  const candidateSource = {
+    sha: exactSha(candidateCommit?.sha, "candidate source SHA"),
+    tree: exactSha(candidateCommit?.tree, "candidate source tree"),
+    parents: exactParents(candidateCommit?.parents, "candidate source parents"),
+  };
+  if (protectedSource.tree !== candidateSource.tree) {
+    throw new Error(
+      "protected publication source tree does not match the qualified candidate tree",
+    );
+  }
+
+  let mode = "exact-commit";
+  let pullRequestNumber = null;
+  if (protectedSource.sha !== candidateSource.sha) {
+    mode = "merge-equivalent";
+    const sameParents =
+      protectedSource.parents.length === candidateSource.parents.length &&
+      protectedSource.parents.every(
+        (parent, index) => parent === candidateSource.parents[index],
+      );
+    if (!sameParents) {
+      throw new Error(
+        "protected publication source is not parent-equivalent to the qualified merge candidate",
+      );
+    }
+    pullRequestNumber = Number(pullRequest?.number || 0);
+    const pullRequestHead = exactSha(
+      pullRequest?.headSha,
+      "publication pull request head SHA",
+    );
+    const pullRequestMerge = exactSha(
+      pullRequest?.mergeSha,
+      "publication pull request merge SHA",
+    );
+    if (
+      !Number.isSafeInteger(pullRequestNumber) ||
+      pullRequestNumber <= 0 ||
+      pullRequest?.merged !== true ||
+      pullRequestMerge !== protectedSource.sha ||
+      !candidateSource.parents.includes(pullRequestHead)
+    ) {
+      throw new Error(
+        "protected publication source does not match the merged pull request and qualified merge candidate",
+      );
+    }
+  }
+
+  const binding = {
+    schema: "kungfu.buildchain.v4-protected-publication-source/v1",
+    repository,
+    mode,
+    protectedSource,
+    candidateSource,
+    pullRequestNumber,
+  };
+  return {
+    ...binding,
+    bindingRoot: v4ContentRoot("candidate-identity", binding),
+  };
+}

package/packages/core/v4-publication-qualification.js

@@ -207,6 +207,7 @@ export function validateV4PublicationQualificationReceipt(
 export function assertV4DeclarativePromotionInputs(inputs) {
   const forbidden = Object.entries(inputs || {}).filter(
     ([name, value]) =>
+      name !== "dry-run" &&
       /(command|cmd|script|shell|run)$/iu.test(name) &&
       String(value || "").trim() !== "",
   );