@kungfu-tech/buildchain 2.11.13-alpha.1 → 2.11.13-alpha.3

package/docs/lifecycle-protocol.md

@@ -59,6 +59,14 @@ path = "pyproject.toml"
 key = "project.version"
 ```
 
+Configured JSON and TOML version files are semantic no-ops when the declared
+key already equals the requested version. Buildchain preserves the repository's
+original TOML bytes in that case instead of serializing the whole document and
+creating formatter-only release state. When a TOML version really changes,
+Buildchain applies a parser-verified lossless edit to that key and fails closed
+if it cannot prove a unique edit; unrelated arrays, comments, and formatting
+remain repository-owned.
+
 Regex files must expose the current version through a named capture group called
 `version`:
 
@@ -248,6 +256,14 @@ refs. After the command finishes, Buildchain checks that only declared
 version-state files changed. This prevents verification from quietly adding
 extra source changes to the release commit.
 
+Buildchain-owned untracked runtime evidence is excluded only through an exact
+internal allowlist. This includes contract-drift issue material under
+`.buildchain/contract-drift/` and the paper workflow's
+`.buildchain/publication-result.json`, alongside release-candidate, passport,
+release-state, KFD, and runtime evidence directories. Tracked changes, ordinary
+source files, and undeclared `.buildchain/*` paths still fail version
+verification.
+
 On protected alpha and release branches, the generated version-state commit is
 applied by the promotion automation after the reviewed channel PR has merged.
 Buildchain keeps review requirements, conversation resolution, strict status

package/docs/publication-artifacts.md

@@ -86,6 +86,16 @@ same-version republish is allowed only when the immutable digest is unchanged;
 if PDF, source bundle, route, metadata, or toolchain evidence changes for an
 existing version, Buildchain fails before the registry is rewritten.
 
+The Buildchain web-surface adapter consumes this boundary from a surface-local
+`manifest.json` whose `archivePolicy.contract` is
+`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive
+root from every owning or parent `sync --delete`, verifies existing object
+digests, uploads only missing immutable files with `--no-overwrite`, and verifies
+them again before mutable site content is synchronized. A current package set
+does not need to rebuild or enumerate every historical version: the protected
+archive root remains outside deletion even when older versions disappear from
+the current artifact.
+
 `publication.toolchain` makes the source-to-PDF transformation part of the
 machine-readable contract. `latex-docker` is the preferred LaTeX profile. The
 Buildchain paper scaffold and reusable workflow default to
@@ -169,6 +179,8 @@ jobs:
       contents: write
       id-token: write
       issues: write
+    secrets:
+      BUILDCHAIN_PROMOTION_TOKEN: ${{ secrets.RELEASE_AUTHORITY_TOKEN }}
     with:
       buildchain-ref: ${{ inputs.buildchain-ref || '' }}
       toolchain-type: config
@@ -176,10 +188,21 @@ jobs:
       buildchain-contract-lock-path: .buildchain/contract-lock.json
 ```
 
+`RELEASE_AUTHORITY_TOKEN` is a caller-chosen release authority secret name.
+Map whichever repository or organization secret owns protected release
+bookkeeping into the reusable workflow's `BUILDCHAIN_PROMOTION_TOKEN` contract;
+the reusable workflow does not require that provider-side secret to use a
+specific name. Before it builds the paper, the workflow uses that authority to
+read the target channel's branch protection and fails with a configuration
+diagnostic if the protection is not readable. `github.token` remains a fallback
+for repositories where its permissions are sufficient.
+
 The preset:
 
 - resolves the same floating Buildchain runtime and contract lock as the build
   workflow;
+- verifies that the declared promotion authority can read the protected target
+  channel before starting the publication build;
 - builds the PDF through the declared pinned LaTeX Docker toolchain or custom
   command;
 - verifies the paper repository;

package/docs/web-surface-deployments.md

@@ -371,6 +371,39 @@ node scripts/web-surface.mjs \
   --output .buildchain/web-surface-staging-apply.json
 ```
 
+### Immutable publication paths
+
+When a surface artifact contains `manifest.json` with
+`archivePolicy.contract = "kungfu-buildchain-publication-archive-policy"`,
+Buildchain treats every declared `publications[].versions[].immutablePath` as
+an append-only publication boundary. This applies identically to preview,
+staging, and production adapters.
+
+The adapter derives the protected archive root from those declared version
+paths and applies four ordered safeguards:
+
+1. every local immutable file is checked against an existing S3 object;
+2. missing files are uploaded with `aws s3 sync --no-overwrite` and a SHA-256
+   checksum;
+3. every immutable file is checked again after upload, closing the race between
+   the first check and the no-overwrite transfer;
+4. mutable site content keeps normal `sync --delete` behavior, but every parent
+   or owning surface sync excludes the protected archive root from deletion.
+
+An existing object with a different SHA-256 digest fails apply before mutable
+content is changed. Older objects without a stored S3 SHA-256 checksum are read
+and byte-hashed for compatibility. Directory-index alias writes are skipped
+under protected roots so they cannot overwrite immutable route objects; viewer
+request rewriting remains the directory-index authority.
+
+The deploy plan and manifest record `immutablePublication`,
+`mutableDeleteExcludes`, and the parent-surface coverage. Apply output records
+`immutablePreservation` plus every pre-check, no-overwrite sync, post-check, and
+mutable sync operation. Health output adds an `__immutable__` check proving that
+the owning and parent surface syncs carried their required delete exclusions.
+The runner must provide an AWS CLI version whose `s3 sync` supports
+`--no-overwrite`.
+
 For multi-surface sites, each surface host is treated as a root-relative view
 of that surface's artifact path prefix. For example, a `buildchain` surface with
 `path = "/buildchain/"` and preview URL
@@ -457,7 +490,8 @@ node scripts/web-surface.mjs \
 
 Apply output records the channel, alias, source SHA, artifact hash, target
 bucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN
-invalidation paths, actor/run metadata, and every adapter operation with
+invalidation paths, actor/run metadata, immutable preservation evidence, and
+every adapter operation with
 `executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,
 Buildchain records the failed operation, stops subsequent adapter operations,
 and exits non-zero after writing the result JSON. Buildchain records secret

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.11.13-alpha.1",
+  "version": "2.11.13-alpha.3",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/buildchain-config.js

@@ -2,7 +2,8 @@ import { execSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { parse, stringify } from "smol-toml";
+import { isDeepStrictEqual } from "node:util";
+import { parse } from "smol-toml";
 import {
   BUILDCHAIN_CONFIG_PATH,
   resolveBuildchainConfigPath,
@@ -103,6 +104,44 @@ function setByDottedKey(target, key, value) {
   current[segments[segments.length - 1]] = value;
 }
 
+function updateTomlStringValuePreservingSource({ source, content, key, value, filePath }) {
+  const currentValue = getByDottedKey(content, key);
+  if (currentValue === value) {
+    return source;
+  }
+  if (typeof currentValue !== "string" || currentValue.length === 0) {
+    throw new Error(`Configured TOML version key is missing or empty: ${filePath}:${key}`);
+  }
+
+  const expected = structuredClone(content);
+  setByDottedKey(expected, key, value);
+  const candidates = [];
+  let offset = 0;
+  while (offset <= source.length - currentValue.length) {
+    const index = source.indexOf(currentValue, offset);
+    if (index === -1) {
+      break;
+    }
+    const candidate = `${source.slice(0, index)}${value}${source.slice(index + currentValue.length)}`;
+    try {
+      if (isDeepStrictEqual(parse(candidate), expected)) {
+        candidates.push(candidate);
+      }
+    } catch {
+      // Keep searching. Only a parser-confirmed single-field update is safe.
+    }
+    offset = index + currentValue.length;
+  }
+
+  if (candidates.length !== 1) {
+    throw new Error(
+      `Configured TOML version key cannot be updated losslessly: ${filePath}:${key} ` +
+        `(matching candidates: ${candidates.length})`,
+    );
+  }
+  return candidates[0];
+}
+
 export function loadBuildchainConfig(cwd = process.cwd()) {
   const configPath = resolveBuildchainConfigPath(cwd);
   const filePath = path.join(cwd, configPath);
@@ -1359,14 +1398,23 @@ export function updateConfiguredVersionStateContents(files, version) {
   return files
     .map((file) => {
       let content;
-      if (file.type === "json") {
+      if (
+        (file.type === "json" || file.type === "toml") &&
+        getByDottedKey(file.content, file.key) === version
+      ) {
+        content = file.source;
+      } else if (file.type === "json") {
         const next = structuredClone(file.content);
         setByDottedKey(next, file.key, version);
         content = `${JSON.stringify(next, null, 2)}\n`;
       } else if (file.type === "toml") {
-        const next = structuredClone(file.content);
-        setByDottedKey(next, file.key, version);
-        content = stringify(next);
+        content = updateTomlStringValuePreservingSource({
+          source: file.source,
+          content: file.content,
+          key: file.key,
+          value: version,
+          filePath: file.path,
+        });
       } else if (file.type === "regex") {
         content = file.source.replace(file.pattern, (...args) => {
           const groups = args.at(-1) || {};