@kungfu-tech/buildchain 4.0.2 → 4.0.3-alpha.0

package/packages/core/next-development-projection.js

@@ -175,7 +175,13 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-11
+last_reviewed: 2026-09-07
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-07
+  visible_context: Release completion, protected development provider, and independent review sources.
+  invisible_context_boundary: No private credentials or external unpublished release state.
 ---
 
 # Next-development Transition
@@ -229,6 +235,23 @@ can settle, Patrol reads every prepared version path at the candidate SHA and
 requires the exact reserved blob identities; missing or stale state blocks
 before a Release Cut or heavy candidate build.
 
+## Stable publication and the next patch
+
+A completed stable publication with \`semver/auto\` schedules the next patch at
+Alpha zero: \`4.0.2\` prepares \`4.0.3-alpha.0\`. Publication settlement is
+retained before the development PR starts. Preparation reads the exact current
+protected Dev commit and regenerates only its declared version files, preserving
+code that arrived after the stable candidate. The independent reviewer verifies
+the completed stable publication and reconstructs every tracked byte from the
+protected parent; a PR body alone grants no authority.
+
+A replay returns \`already-current\` or \`already-advanced\` when Dev already
+contains the target or a later version. A late Alpha completion cannot regress
+Dev to an older patch. A moved protected base fails before creating the version
+commit and requires a fresh preparation attempt. Pending review leaves the
+completed publication intact. Anchored version models still require a reviewed
+manual anchor.
+
 ## Version models
 
 \`semver/auto\` increments the Alpha sequence on the same semantic patch. For

package/packages/core/next-development-transition.js

@@ -159,15 +159,14 @@ function normalizeModel(value = {}) {
   return model;
 }
 
-function normalizeCompletedAlpha(value = {}) {
+function normalizeCompletedAlpha(value = {}, model) {
   const version = String(value.version || "").trim();
-  if (!ALPHA.test(version))
+  const expression = model?.strategy === "anchored" ? /-alpha\.(0|[1-9]\d*)$/u : ALPHA;
+  if (!SEMVER.test(version) || !expression.test(version))
     throw new Error("completedAlpha.version must be an alpha semantic version");
   const exactTag = String(value.exactTag || "").trim();
   if (exactTag !== `v${version}`)
-    throw new Error(
-      "completedAlpha.exactTag must match completedAlpha.version",
-    );
+    throw new Error("completedAlpha.exactTag must match completedAlpha.version");
   const normalized = {
     outcome: String(value.outcome || "").trim(),
     version,
@@ -251,8 +250,8 @@ function initialStateRoot(status, idempotencyKey) {
 }
 
 export function createNextDevelopmentTransition(input = {}) {
-  const completedAlpha = normalizeCompletedAlpha(input.completedAlpha);
   const model = normalizeModel(input.model);
+  const completedAlpha = normalizeCompletedAlpha(input.completedAlpha, model);
   const adapter = normalizeAdapter(input);
   const declaredPaths = [
     ...adapter.sourcePaths,

package/packages/core/oci-compose-qualification.js

@@ -0,0 +1,143 @@
+import { domainContentRoot } from "./canonical-contracts.js";
+import { releaseTailRoot } from "./release-tail-provider-plane.js";
+import { ociPublicationTag } from "./oci-publication-graph.js";
+
+function check(condition, message) {
+  if (!condition) throw new Error(`Compose preview: ${message}`);
+}
+
+export function verifyComposePublication({
+  family,
+  readback,
+  documents,
+  repository,
+  tag,
+}) {
+  const { root, ...body } = family;
+  const version = tag.replace(/^v/u, "");
+  const operation = documents.productState.operations.find(
+    (entry) => entry.capabilityId === "product.oci.publish",
+  );
+  check(
+    family.schema === "kungfu-buildchain-oci-family/v2" &&
+      root === domainContentRoot("oci-publication-family", body) &&
+      family.repository === repository &&
+      family.version === version &&
+      family.sourceSha === documents.passport.source.builtSourceSha &&
+      documents.passport.source.builtSourceTreeSha ===
+        documents.invocation.candidate.tree &&
+      readback.sourceSha === documents.invocation.candidate.commit &&
+      readback.familyRoot === root &&
+      readback.version === version &&
+      readback.candidateSourceSha === family.sourceSha &&
+      operation?.receipt.evidenceRoots.includes(releaseTailRoot(readback)),
+    "unbound public OCI family",
+  );
+  const applications = family.images.filter(
+    (entry) => entry.kind === "compose" && entry.preview,
+  );
+  check(applications.length === 1, "expected one declared Compose preview");
+  const application = applications[0],
+    policy = application.preview;
+  check(
+    policy.alias === "compose-preview" &&
+      /^\.github\/workflows\/[a-z0-9-]+\.yml$/u.test(
+        policy.qualificationWorkflow,
+      ) &&
+      /^(none|sha256:[0-9a-f]{64})$/u.test(policy.previousDigest),
+    "invalid preview policy",
+  );
+  const image = family.images.find(
+    (entry) =>
+      entry.name === application.targetImage && entry.kind !== "compose",
+  );
+  check(
+    image &&
+      application.repository === image.repository &&
+      image.repository === `ghcr.io/${repository}/${image.name}` &&
+      /^[a-z0-9][a-z0-9._-]*$/u.test(image.name),
+    "foreign application destination",
+  );
+  for (const entry of [image, application])
+    check(
+      readback.images.some(
+        (observed) =>
+          observed.name === entry.name &&
+          observed.repository === entry.repository &&
+          observed.digest === entry.digest &&
+          observed.ref === ociPublicationTag(entry, version) &&
+          observed.anonymous === true,
+      ),
+      "missing public artifact readback",
+    );
+  return {
+    application,
+    image,
+    policy,
+    familyRoot: root,
+    repository,
+    tag,
+    sourceSha: documents.product.publication.releaseSha,
+    publicationReceiptRoot: documents.receipt.receiptRoot,
+  };
+}
+
+export function verifyComposeQualification(context, run, receipt) {
+  const { application, image, policy, repository, tag, sourceSha, familyRoot } =
+    context;
+  check(
+    run.repository?.full_name === repository &&
+      run.head_repository?.full_name === repository &&
+      run.event === "workflow_dispatch" &&
+      run.status === "completed" &&
+      run.conclusion === "success" &&
+      run.head_sha === sourceSha &&
+      run.path.split("@")[0] === policy.qualificationWorkflow,
+    "qualification run is not the exact published source",
+  );
+  if (!receipt) return;
+  check(
+    receipt.schema === "kungfu-buildchain-compose-qualification/v1" &&
+      receipt.repository === repository &&
+      receipt.tag === tag &&
+      receipt.sourceSha === sourceSha &&
+      receipt.familyRoot === familyRoot &&
+      String(receipt.runId) === String(run.id) &&
+      Number(receipt.runAttempt) === run.run_attempt &&
+      receipt.image === `${image.repository}@${image.digest}` &&
+      receipt.application ===
+        `${application.repository}@${application.digest}` &&
+      receipt.previousDigest === policy.previousDigest &&
+      receipt.passed === true,
+    "qualification receipt identity mismatch",
+  );
+  for (const name of [
+    "freshInstall",
+    "restartPersistence",
+    "upgradePersistence",
+    "rollbackPersistence",
+    "accountIsolation",
+    "hardenedRuntime",
+  ])
+    check(receipt.checks?.[name] === true, `qualification lacks ${name}`);
+  check(
+    Array.isArray(image.platforms) &&
+      image.platforms.length === 2 &&
+      JSON.stringify([...image.platforms].sort()) ===
+        JSON.stringify(["linux/amd64", "linux/arm64"]) &&
+      image.platforms.every(
+        (platform) => receipt.platforms?.[platform]?.passed === true,
+      ),
+    "qualification lacks both platforms",
+  );
+  check(
+    Array.isArray(receipt.evidence) &&
+      receipt.evidence.length > 0 &&
+      receipt.evidence.every(
+        (entry) =>
+          /^[a-zA-Z0-9][a-zA-Z0-9._-]*\.json$/u.test(entry.path) &&
+          /^sha256:[0-9a-f]{64}$/u.test(entry.sha256),
+      ),
+    "missing qualification evidence bindings",
+  );
+}

package/packages/core/oci-publication-bundle.js

@@ -0,0 +1,281 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { domainContentRoot } from "./canonical-contracts.js";
+import {
+  verifyOciGraph,
+  verifyOciDestination,
+} from "./oci-publication-graph.js";
+
+export const OCI_FAMILY_SCHEMA = "kungfu-buildchain-oci-family/v1";
+const digestPattern = /^sha256:[0-9a-f]{64}$/u;
+const namePattern = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/u;
+
+export function sealOciPublicationBundle({ bundleRoot, body }) {
+  const manifest = {
+    ...body,
+    root: domainContentRoot("oci-publication-family", body),
+  };
+  verifyOciPublicationBundle({
+    bundleRoot,
+    manifest,
+    repository: body.repository,
+    sourceSha: body.sourceSha,
+    version: body.version,
+  });
+  return manifest;
+}
+
+function requireValue(condition, message) {
+  if (!condition) throw new Error(`OCI bundle: ${message}`);
+}
+
+export function ociBundleFile(root, relative) {
+  requireValue(
+    typeof relative === "string" &&
+      relative.length > 0 &&
+      !relative.includes("\\") &&
+      !path.isAbsolute(relative) &&
+      !relative.split(/[\\/]/u).some((p) => p === ".." || p === "." || !p),
+    "unsafe file path",
+  );
+  const base = fs.realpathSync(root);
+  let current = base;
+  for (const segment of relative.split("/")) {
+    current = path.join(current, segment);
+    requireValue(
+      !fs.lstatSync(current).isSymbolicLink(),
+      "symlinks are forbidden",
+    );
+  }
+  requireValue(
+    fs.statSync(current).isFile() &&
+      fs.realpathSync(current).startsWith(`${base}${path.sep}`),
+    "file escapes bundle",
+  );
+  return current;
+}
+
+function fileDigest(file) {
+  const hash = crypto.createHash("sha256"),
+    buffer = Buffer.alloc(1024 * 1024);
+  const fd = fs.openSync(file, "r");
+  try {
+    for (;;) {
+      const size = fs.readSync(fd, buffer);
+      if (!size) break;
+      hash.update(buffer.subarray(0, size));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function verifyImageProvenance(image, config, sourceSha, version) {
+  const labels = config.config?.Labels || {};
+  requireValue(
+    image.content &&
+      /^[0-9a-f]{40}$/u.test(image.content.sourceSha) &&
+      typeof image.content.version === "string" &&
+      image.content.version.length > 0,
+    "missing image content provenance",
+  );
+  requireValue(
+    labels["org.opencontainers.image.revision"] === image.content.sourceSha &&
+      labels["org.opencontainers.image.version"] === image.content.version,
+    "image content provenance mismatch",
+  );
+  if (image.action === "built")
+    requireValue(
+      image.content.sourceSha === sourceSha &&
+        image.content.version === version,
+      "built image is not from the candidate source",
+    );
+  if (image.contractMajor !== undefined)
+    requireValue(
+      Number.isInteger(image.contractMajor) &&
+        image.contractMajor > 0 &&
+        labels["io.kungfu.image.contract-major"] ===
+          String(image.contractMajor),
+      "image contract major mismatch",
+    );
+  if (image.parentDigest)
+    requireValue(
+      digestPattern.test(image.parentDigest) &&
+        labels["io.kungfu.image.parent-digest"] === image.parentDigest,
+      "image parent digest mismatch",
+    );
+  if (image.content.materialSha)
+    requireValue(
+      /^[0-9a-f]{40}$/u.test(image.content.materialSha) &&
+        labels["io.kungfu.buildchain.release-material-sha"] ===
+          image.content.materialSha,
+      "image material provenance mismatch",
+    );
+}
+
+export function verifyOciPublicationBundle({
+  bundleRoot,
+  manifest,
+  repository,
+  sourceSha,
+  version,
+}) {
+  requireValue(
+    [OCI_FAMILY_SCHEMA, "kungfu-buildchain-oci-family/v2"].includes(
+      manifest?.schema,
+    ),
+    "unsupported manifest schema",
+  );
+  const { root, ...body } = manifest;
+  const computed = domainContentRoot("oci-publication-family", body);
+  requireValue(root === computed, "manifest root mismatch");
+  requireValue(
+    manifest.repository === repository &&
+      manifest.sourceSha === sourceSha &&
+      manifest.version === version,
+    "candidate identity mismatch",
+  );
+  requireValue(
+    /^[a-z0-9-]+\/[a-z0-9._-]+$/u.test(repository),
+    "invalid repository",
+  );
+  requireValue(
+    Array.isArray(manifest.images) && manifest.images.length > 0,
+    "empty image family",
+  );
+  const expected = manifest.expectedImages;
+  requireValue(
+    Array.isArray(expected) &&
+      expected.length === new Set(expected).size &&
+      expected.every((n) => namePattern.test(n)),
+    "invalid expected image family",
+  );
+  const actual = manifest.images.map((i) => i.name).sort();
+  requireValue(
+    JSON.stringify(actual) === JSON.stringify([...expected].sort()),
+    "incomplete or duplicate image family",
+  );
+  const files = new Map();
+  const graphs = new Map();
+  for (const image of manifest.images) {
+    verifyOciDestination(image, manifest, requireValue);
+    requireValue(
+      digestPattern.test(image.digest) &&
+        ["built", "reused"].includes(image.action),
+      "invalid image identity",
+    );
+    requireValue(
+      /^linux\/(amd64|arm64)$/u.test(image.platform) ||
+        (manifest.schema.endsWith("/v2") &&
+          ["multi-platform", "compose"].includes(image.platform)),
+      "unsupported image platform",
+    );
+    const prefix = image.layout;
+    const descriptorFile = (descriptor) => {
+      requireValue(
+        digestPattern.test(descriptor.digest) &&
+          Number.isSafeInteger(descriptor.size) &&
+          descriptor.size >= 0 &&
+          !descriptor.urls,
+        "invalid OCI descriptor",
+      );
+      const relative = `${prefix}/blobs/sha256/${descriptor.digest.slice(7)}`;
+      const file = ociBundleFile(bundleRoot, relative);
+      requireValue(
+        fs.statSync(file).size === descriptor.size,
+        "OCI blob size mismatch",
+      );
+      if (!files.has(file))
+        requireValue(
+          fileDigest(file) === descriptor.digest,
+          "OCI blob digest mismatch",
+        );
+      if (Object.hasOwn(descriptor, "data")) {
+        requireValue(
+          descriptor.size <= 1024 * 1024 &&
+            descriptor.data === fs.readFileSync(file).toString("base64"),
+          "embedded OCI content mismatch",
+        );
+      }
+      files.set(file, descriptor);
+      return file;
+    };
+    const layout = JSON.parse(
+      fs.readFileSync(ociBundleFile(bundleRoot, `${prefix}/oci-layout`)),
+    );
+    requireValue(
+      layout.imageLayoutVersion === "1.0.0",
+      "unsupported OCI layout",
+    );
+    const index = JSON.parse(
+      fs.readFileSync(ociBundleFile(bundleRoot, `${prefix}/index.json`)),
+    );
+    const selected = (index.manifests || []).filter(
+      (descriptor) =>
+        descriptor.digest === image.digest &&
+        (descriptor.annotations?.["org.opencontainers.image.ref.name"] ===
+          image.name ||
+          index.manifests.length === 1),
+    );
+    requireValue(
+      index.schemaVersion === 2 && selected.length === 1,
+      "OCI index must select one exact image manifest",
+    );
+    if (manifest.schema.endsWith("/v2")) {
+      graphs.set(
+        image.name,
+        verifyOciGraph({
+          image,
+          manifest,
+          descriptor: selected[0],
+          descriptorFile,
+          requireValue,
+          verifyProvenance: (config) =>
+            verifyImageProvenance(image, config, sourceSha, version),
+        }),
+      );
+    } else {
+      const document = JSON.parse(fs.readFileSync(descriptorFile(selected[0])));
+      requireValue(
+        document.schemaVersion === 2 &&
+          [
+            "application/vnd.oci.image.manifest.v1+json",
+            "application/vnd.docker.distribution.manifest.v2+json",
+          ].includes(document.mediaType) &&
+          Array.isArray(document.layers),
+        "unsupported OCI image manifest",
+      );
+      const config = JSON.parse(
+        fs.readFileSync(descriptorFile(document.config)),
+      );
+      requireValue(
+        `${config.os}/${config.architecture}` === image.platform,
+        "OCI platform mismatch",
+      );
+      verifyImageProvenance(image, config, sourceSha, version);
+      for (const layer of document.layers) descriptorFile(layer);
+      graphs.set(image.name, {
+        manifests: [selected[0]],
+        blobs: [document.config, ...document.layers],
+      });
+    }
+    const smokeFile = ociBundleFile(bundleRoot, image.smoke.path);
+    requireValue(
+      fileDigest(smokeFile) === image.smoke.sha256,
+      "smoke evidence digest mismatch",
+    );
+    const smoke = JSON.parse(fs.readFileSync(smokeFile));
+    requireValue(
+      smoke.passed === true && smoke.image === image.name,
+      "smoke qualification failed",
+    );
+  }
+  return {
+    root: computed,
+    manifest,
+    graphs,
+    bundleRoot: fs.realpathSync(bundleRoot),
+  };
+}

package/packages/core/oci-publication-graph.js

@@ -0,0 +1,206 @@
+import fs from "node:fs";
+
+const imageTypes = [
+  "application/vnd.oci.image.manifest.v1+json",
+  "application/vnd.docker.distribution.manifest.v2+json",
+];
+const indexTypes = [
+  "application/vnd.oci.image.index.v1+json",
+  "application/vnd.docker.distribution.manifest.list.v2+json",
+];
+const composeType = "application/vnd.docker.compose.project";
+
+export function ociPublicationTag(image, version) {
+  return `${image.kind === "compose" ? "compose-" : ""}v${version}`;
+}
+
+export function verifyOciDestination(image, manifest, requireValue) {
+  const compose = manifest.schema.endsWith("/v2") && image.kind === "compose";
+  requireValue(
+    manifest.schema.endsWith("/v2") || !image.kind,
+    "artifact kinds require family v2",
+  );
+  const target =
+    compose &&
+    manifest.images.find(
+      (entry) => entry.name === image.targetImage && entry.kind !== "compose",
+    );
+  requireValue(
+    !image.kind || ["image", "compose"].includes(image.kind),
+    "unsupported artifact kind",
+  );
+  requireValue(!compose || target, "Compose target image is absent");
+  requireValue(
+    image.repository ===
+      `ghcr.io/${manifest.repository}/${compose ? target.name : image.name}`,
+    "destination must belong to the consumer repository",
+  );
+  requireValue(
+    manifest.images.filter(
+      (entry) =>
+        entry.repository === image.repository &&
+        ociPublicationTag(entry, manifest.version) ===
+          ociPublicationTag(image, manifest.version),
+    ).length === 1,
+    "duplicate publication destination",
+  );
+}
+
+export function verifyOciGraph({
+  image,
+  manifest,
+  descriptor,
+  descriptorFile,
+  requireValue: check,
+  verifyProvenance,
+}) {
+  const manifests = [],
+    blobs = new Map(),
+    platforms = [],
+    attestations = [];
+  const visited = new Set();
+  const read = (entry) => JSON.parse(fs.readFileSync(descriptorFile(entry)));
+  function blob(entry) {
+    descriptorFile(entry);
+    blobs.set(entry.digest, entry);
+  }
+  function visit(entry, depth = 0) {
+    check(
+      depth < 4 && visited.size < 256 && !visited.has(entry.digest),
+      "duplicate or excessive OCI graph",
+    );
+    visited.add(entry.digest);
+    const document = read(entry);
+    check(
+      document.schemaVersion === 2 && document.mediaType === entry.mediaType,
+      "OCI descriptor media type mismatch",
+    );
+    if (indexTypes.includes(document.mediaType)) {
+      check(
+        image.kind !== "compose" &&
+          Array.isArray(document.manifests) &&
+          document.manifests.length > 0,
+        "invalid OCI index",
+      );
+      for (const child of document.manifests) visit(child, depth + 1);
+    } else {
+      check(
+        imageTypes.includes(document.mediaType) &&
+          Array.isArray(document.layers),
+        "unsupported OCI manifest",
+      );
+      const config = read(document.config);
+      blob(document.config);
+      for (const layer of document.layers) blob(layer);
+      if (image.kind === "compose") {
+        verifyCompose(document, image, manifest, read, check);
+      } else if (
+        entry.annotations?.["vnd.docker.reference.type"] ===
+        "attestation-manifest"
+      ) {
+        check(
+          entry.platform?.os === "unknown" &&
+            entry.platform?.architecture === "unknown" &&
+            document.layers.length > 0 &&
+            document.layers.every(
+              (layer) => layer.mediaType === "application/vnd.in-toto+json",
+            ),
+          "invalid image attestation",
+        );
+        attestations.push({
+          target: entry.annotations["vnd.docker.reference.digest"],
+          statements: document.layers.map(read),
+        });
+      } else {
+        const platform = `${config.os}/${config.architecture}`;
+        check(
+          /^linux\/(amd64|arm64)$/u.test(platform) &&
+            (!entry.platform ||
+              platform ===
+                `${entry.platform.os}/${entry.platform.architecture}`),
+          "OCI platform mismatch",
+        );
+        check(
+          !platforms.some((found) => found.platform === platform),
+          "duplicate image platform",
+        );
+        platforms.push({ platform, digest: entry.digest });
+        verifyProvenance(config);
+      }
+    }
+    manifests.push(entry);
+  }
+  visit(descriptor);
+  if (image.kind !== "compose") {
+    const expected =
+      image.platform === "multi-platform" ? image.platforms : [image.platform];
+    check(
+      Array.isArray(expected) &&
+        expected.length > 0 &&
+        new Set(expected).size === expected.length &&
+        JSON.stringify([...expected].sort()) ===
+          JSON.stringify(platforms.map((entry) => entry.platform).sort()),
+      "incomplete image platform family",
+    );
+    for (const attestation of attestations) {
+      check(
+        platforms.some((entry) => entry.digest === attestation.target) &&
+          attestation.statements.every((statement) =>
+            statement.subject?.some(
+              (subject) =>
+                `sha256:${subject.digest?.sha256}` === attestation.target,
+            ),
+          ),
+        "image attestation subject mismatch",
+      );
+    }
+  }
+  return { manifests, blobs: [...blobs.values()], platforms };
+}
+
+function verifyCompose(document, image, manifest, read, check) {
+  if (image.preview)
+    check(
+      image.preview.alias === "compose-preview" &&
+        /^\.github\/workflows\/[a-z0-9-]+\.yml$/u.test(
+          image.preview.qualificationWorkflow,
+        ) &&
+        /^(none|sha256:[0-9a-f]{64})$/u.test(image.preview.previousDigest),
+      "invalid Compose preview policy",
+    );
+  check(
+    image.platform === "compose" &&
+      document.artifactType === composeType &&
+      document.config.mediaType === "application/vnd.oci.empty.v1+json" &&
+      document.layers.length === 1 &&
+      document.layers[0].mediaType ===
+        "application/vnd.docker.compose.file+yaml",
+    "unsupported Compose artifact",
+  );
+  // JSON is a YAML subset; this bounded public form needs no executable YAML loader.
+  const project = read(document.layers[0]);
+  check(
+    project.services && Object.keys(project.services).length > 0,
+    "empty Compose application",
+  );
+  const target = manifest.images.find(
+    (entry) => entry.name === image.targetImage,
+  );
+  const references = Object.values(project.services).map(
+    (service) => service.image,
+  );
+  check(
+    references.every(
+      (ref) =>
+        typeof ref === "string" &&
+        /^[a-z0-9./:_-]+@sha256:[0-9a-f]{64}$/u.test(ref),
+    ) && references.includes(`${target.repository}@${target.digest}`),
+    "Compose images must bind exact digests",
+  );
+  check(
+    image.content?.sourceSha === manifest.sourceSha &&
+      image.content?.version === manifest.version &&
+      image.action === "built",
+    "Compose candidate provenance mismatch",
+  );
+}