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

package/scripts/buildchain-cli-help.mjs

@@ -0,0 +1,256 @@
+export const BUILDCHAIN_USAGE = `Usage:
+  buildchain --help
+  buildchain version
+  buildchain layout [--cwd <dir>] [--json]
+  buildchain portable-cache plan --manifest <file-or-json> [--output <file>]
+                                 [--github-output <file>] [--json]
+  buildchain portable-cache receipt --plan <file-or-json> [--matched-key <key>]
+                                    [--cache-hit true|false]
+                                    [--validation-status pass|fail]
+                                    [--validation-reason <text>]
+                                    [--cold-fallback-status not-run|passed|failed]
+                                    [--output <file>] [--json]
+  buildchain candidate timeline --input <file-or-json> [--output <file>] [--json]
+  buildchain init [--cwd <dir>] [--type package|native|web-surface|infra-contract|publication-artifact|anchored-package] [--force]
+                  [--package-manager pnpm|npm|yarn] [--runner-preset <preset>]
+                  [--artifact-name <template>]
+  buildchain validate [--cwd <dir>] [--require-version-state]
+                      [--require-lifecycle-stages <comma-list>]
+  buildchain lifecycle run <stage> [--cwd <dir>] [--required]
+                             [--artifact-name <name>] [--artifact-path <path>]...
+                             [--manifest-path <path>] [--summary-path <path>]
+                             [--process-summary <json>]
+  buildchain npm dry-run [--cwd <dir>] [--expected-tag <tag>] [--registry <url>]
+                         [--dist-tag <tag>] [--skip-npm-publish-dry-run] [--json]
+  buildchain release --dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
+                                 [--tags <comma-list>] [--json]
+  buildchain release explain --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
+                                     [--tags <comma-list>] [--json]
+  buildchain release dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
+                                      [--tags <comma-list>] [--json]
+  buildchain release line open --major <n> --minor <n> [--source-ref <ref>]
+                               [--initial-version <version>] [--write] [--json]
+  buildchain release-governance reconcile --repository <owner/repo>
+                               --branch <dev|alpha|release/vN/vN.N>
+                               --candidate-sha <sha> [--apply] [--json]
+  buildchain github-governance <plan|apply|rollback|protection-policy-plan|ruleset-policy-plan> ...
+  buildchain release <inspect|recover|finalize|abort> ...
+  buildchain transaction inspect ...
+  buildchain collect github-release --tag <tag> [--repository <owner/repo>]
+                                    [--assets-dir <dir>] [--assets-json <json-or-path>]
+                                    [--release-json <json-or-path>] [--package-set-json <json-or-path>]
+                                    [--product-name <name>]
+                                    [--publish-evidence-json <json-or-path>]
+                                    [--trusted-publishing-json <json-or-path>]
+                                    [--transaction-json <json-or-path>]
+                                    [--anchor-manifest-json <json-or-path>]
+                                    [--impact-json <json-or-path>]
+                                    [--build-summary-json <json-or-path>]
+                                    [--build-facts-json <json-or-path>]...
+                                    [--platform-manifest-json <json-or-path>]...
+                                    [--dist-tag-evidence-json <json-or-path>]
+                                    [--kfd-1-witness-json <json-or-path>]...
+                                    [--kfd-2-claim-json <json-or-path>]...
+                                    [--kfd-3-prebuild-witness-json <json-or-path>]...
+                                    [--kfd-3-artifact-witness-json <json-or-path>]...
+                                    [--kfd-3-artifact-verify-cmd <command>]
+                                    [--kfd-support-matrix-json <json-or-path>]
+                                    [--kfd-product-gate-json <json-or-path>]...
+                                    [--invariant-passport-json <json-or-path>]...
+                                    [--invariant-passport-cmd <command>]
+                                    [--release-evidence-json <json-or-path>]...
+                                    [--github-artifact-attestation-policy-json <json-or-path>]...
+                                    [--kfd-agent-hub-evidence-json <json-or-path>]
+                                    [--base-passport-json <json-or-path>] [--require-base-kfd]
+                                    [--release-extra-json <json-or-path>]
+                                    [--publish-json <json-or-path>] [--output-dir <dir>] [--json]
+  buildchain create publication-admission --input-json <file-or-json> [--output <file>] [--json]
+  buildchain create runner-provenance --input-json <file-or-json> [--output <file>] [--json]
+  buildchain create github-artifact-attestation-policy --input-json <file-or-json> [--output <file>] [--json]
+  buildchain verify release-passport <file-or-url> [--json]
+  buildchain verify github-artifact-attestation <artifact>
+                          --evidence <file> --bundle <file>
+                          --platform-manifest <file> --release-passport <file> [--json]
+  buildchain verify publication-admission <file-or-json>
+                          --registry-json <file-or-json>
+                          --runner-json <file-or-json>
+                          --control-plane-audit-json <file-or-json>
+                          --publication-evidence-json <file-or-json>
+                          [--expected-json <file-or-json>] [--used-nonce <nonce>]... [--json]
+  buildchain audit publication-control-plane --repository <owner/repo> --branch <protected-branch>
+  buildchain audit github-governance [--organization <owner>] [--repository <owner/repo>]
+                                     [--output <file>] [--require-qualifying] [--json]
+                          [--source-sha <merged-branch-sha>] [--workflow-repository <owner/repo>]
+                          [--workflow <path>] [--workflow-ref <sha-or-ref>]
+                          [--job <id>] [--environment <name>] [--package <name>]
+                          [--publisher-mode npm-trusted-publisher|github-token|oidc-role]
+                          [--npm-trust-json <file-or-json>]
+                          [--provider-audit-json <file>] [--output <file>] [--allow-nonqualifying]
+  buildchain verify artifact <file|dir|url|npm:...|oci:...|github-release:...>
+                             [--passport <file-or-url>] [--locator-config <json>]
+                             [--repository <owner/repo>] [--tag <tag>]
+                             [--npm-registry <url>] [--json]
+  buildchain verify artifact-envelope <file-or-json> [--assessment-time <epoch>]
+                             [--expected-root <sha256:...>] [--expected-issuer <issuer>]
+                             [--expected-publisher <publisher>]
+                             [--expected-contract <version>] [--json]
+  buildchain project kfx-admission <file-or-json> [--assessment-time <epoch>]
+                             [--expected-root <sha256:...>] [--expected-issuer <issuer>]
+                             [--expected-publisher <publisher>]
+                             [--expected-contract <version>] [--json]
+  buildchain verify infra-contract-evidence-bundle <file> [--json]
+  buildchain verify observability-log <jsonl> [--min-events <n>]
+                                             [--require-phase <csv>]
+                                             [--require-component <csv>]
+                                             [--require-event <csv>] [--allow-errors] [--json]
+  buildchain explain release --passport <file-or-url> [--for human|agent] [--json]
+  buildchain explain artifact <subject> [--passport <file-or-url>] [--npm-registry <url>] [--for human|agent] [--json]
+  buildchain inspect release --passport <file-or-url> [--json]
+  buildchain inspect artifact <subject> [--passport <file-or-url>] [--npm-registry <url>] [--json]
+  buildchain doctor [--cwd <dir>] [--require-publish-source-lock] [--json]
+  buildchain dev merge-queue --repository <owner/repo> --branch <dev/vN/vN.M>
+                             [--from-config | --workflow <required-workflow.yml>...] [--cwd <dir>]
+                             [--check-response-timeout-minutes <n>]
+                             [--max-entries-to-build <n>] [--apply]
+  buildchain log <info|warn|error> --event <name> [--phase <phase>]
+                 [--component <name>] [--source <name>] [--attribute key=value]...
+                 [--path <jsonl>] [--json]
+  buildchain log summary [--path <jsonl>] [--json]
+  buildchain diagnostics summary <diagnostics.json>... [--artifact <file>]...
+                                      [--output <file>] [--json]
+  buildchain facts module [--cwd <dir>] [--module <id>] [--module-root <path>]
+                          [--version-source <id>] [--output <file>]
+                          [--output-path <path>]... [--legacy-kungfu-buildinfo <file>] [--json]
+  buildchain facts aggregate [--cwd <dir>] [--product <id>]
+                             [--module-fact <file>]... [--artifact <path>]...
+                             [--output <file>] [--json]
+  buildchain facts verify [--cwd <dir>] --fact <file> [--json]
+  buildchain kfd ...
+  buildchain kfd hub <init|inspect|test|explain> [--cwd <dir>]
+                     [--declaration <path>] [--output-dir <path>]
+                     [--write] [--force] [--for agent] [--json]
+  buildchain kfd status [--cwd <dir>] [--json]
+  buildchain kfd migrate-layout [--cwd <dir>] [--write] [--force] [--json]
+  buildchain kfd schema list [--standard kfd-1|kfd-2|kfd-3|kfd-4] [--json]
+  buildchain kfd schema show <kfd-1|kfd-2|kfd-3|kfd-4> [--schema <name>] [--json]
+  buildchain kfd upstream roles [--json]
+  buildchain kfd upstream collect [--cwd <dir>] [--output <file>] [--json]
+  buildchain kfd upstream check [--cwd <dir>] [--aggregate-json <file-or-json>] [--json]
+  buildchain kfd aggregate [--cwd <dir>] [--json]
+  buildchain kfd 1 schema [--schema <name>] [--json]
+  buildchain kfd 1 witness [--cwd <dir>] [--source-sha <sha>] [--output <file>] [--json]
+  buildchain kfd 1 gate --witness-json <file-or-json>... [--cwd <dir>] [--artifact-root <dir>]
+                        [--output <file>] [--json]
+  buildchain kfd 1 verify --gate-json <file-or-json> [--json]
+  buildchain kfd 2 schema [--schema <name>] [--json]
+  buildchain kfd 2 taxonomy --entry-json <file-or-json>... [--kind residualRisk|downgradeReason] [--json]
+  buildchain kfd 2 claims [--cwd <dir>] [--output-dir <dir>] [--json]
+  buildchain kfd 2 product-claims <check|write|render> [--cwd <dir>] [--registry <path>]
+                                      [--output-dir <dir>] [--version <version>]
+                                      [--channel <channel>] [--tag <tag>] [--source-sha <sha>] [--json]
+  buildchain kfd 2 trust-claims [--claims-json <file-or-json>] [--json]
+  buildchain kfd 2 trust-assessment [--assessment-json <file-or-json>] [--json]
+  buildchain kfd 3 ...
+  buildchain kfd 3 detect [--cwd <dir>] [--kind <kind>]... [--artifact <path>] [--json]
+  buildchain kfd 3 register <node-api|python-api|cli|binary|documentation|site-bundle>
+                           [--cwd <dir>] [--registry <path>] [--artifact <path>]
+                           [--product <name>] [--json]
+  buildchain kfd 3 audit [--cwd <dir>] [--registry <path>] [--artifact <path>] [--json]
+  buildchain kfd 3 witness [--cwd <dir>] [--registry <path>] [--kind prebuild|artifact]
+                            [--source-sha <sha>] [--artifact <path>] [--output <file>] [--json]
+  buildchain kfd 3 query [<product>] [--cwd <dir>] [--registry <path>]
+                          [--passport <file-or-url>] [--artifact <path>] [--json]
+  buildchain kfd 4 schema [--schema <name>] [--json]
+  buildchain kfd 4 gate --input-json <file-or-json> [--cwd <dir>] [--output <file>] [--json]
+  buildchain kfd 4 verify --gate-json <file-or-json> [--expected-source-sha <sha>] [--json]
+  buildchain kfd 5 schema [--schema <name>] [--json]
+  buildchain kfd 5 gate --input-json <file-or-json> [--cwd <dir>] [--output <file>] [--json]
+  buildchain kfd 5 verify --gate-json <file-or-json> [--expected-source-sha <sha>] [--json]
+  buildchain kfd 7 schema [--schema <name>] [--json]
+  buildchain kfd 7 gate --input-json <file-or-json> [--cwd <dir>] [--output <file>] [--json]
+  buildchain kfd 7 verify --gate-json <file-or-json> [--expected-source-sha <sha>] [--json]
+  buildchain kfd support project --matrix-json <file-or-json> --gate-json <file-or-json>...
+                                  [--expected-source-sha <sha>] [--checked-at <date-time>]
+                                  [--output <file>] [--json]
+  buildchain kfd support verify --projection-json <file-or-json>
+                                  [--expected-source-sha <sha>] [--checked-at <date-time>] [--json]
+  buildchain sample process-tree [--interval-ms <n>] [--label <name>]
+                                 [--output <jsonl>] [--summary-output <json>]
+                                 [--requested-parallelism <n>] [--json]
+                                 -- <command> [args...]
+  buildchain mark --event <name> [--phase <phase>] [--component <name>]
+                  [--attribute key=value]... [--path <jsonl>] [--json]
+  buildchain span --event <name> [--phase <phase>] [--component <name>]
+                  [--path <jsonl>] -- <command> [args...]
+  buildchain web-surface ...
+  buildchain infra-contract ...
+  buildchain publication-artifact manifest [--cwd <dir>] [--source-sha <sha>]
+                                           [--output <file>] [--passport-output <file>]
+                                           [--registry-output <file>] [--source-bundle <file>]
+                                           [--no-source-bundle] [--json]
+  buildchain publication-artifact npm-package [--cwd <dir>] [--output-dir <dir>] [--package-name <name>] [--json]
+  buildchain publication-artifact reproducibility [--cwd <dir>] [--source-sha <sha>]
+                                                   [--output <file>] [--promote]
+                                                   [--no-toolchain-pull]
+                                                   [--allow-unpinned-toolchain] [--json]
+  buildchain paper scaffold --package <name> --repository <owner/repo> [--write] [--json]
+  buildchain paper migrate [--cwd <dir>] [--write] [--json]
+  buildchain paper work start <topic> [--cwd <dir>] [--branch <branch>] [--execute] [--json]
+  buildchain paper work submit [--cwd <dir>] [--title <title>] [--body <body>] [--execute] [--json]
+  buildchain paper fleet audit [--root <dir>] [--offline] [--json]
+  buildchain paper fleet update [--root <dir>] [--write] [--json]
+  buildchain paper preflight [--cwd <dir>] [--offline] [--json]
+  buildchain paper bootstrap npm [--cwd <dir>] [--execute]
+                                  [--confirm-public-package <name>] [--json]
+  buildchain paper build [--cwd <dir>] [--execute] [--json]
+  buildchain paper alpha [--cwd <dir>] [--source-ref <ref>] [--target-ref <ref>]
+                          [--execute] [--json]
+  buildchain paper status [--cwd <dir>] [--json]
+  buildchain paper resume [--cwd <dir>] [--buildchain-ref <ref>] [--execute] [--json]
+  buildchain release-propagation <plan|write-lock> ...
+  buildchain badges readme [--cwd <dir>] [--readme <path>] [--check] [--write] [--json]
+  buildchain badges bundle [--cwd <dir>] [--readme <path>] [--claims <csv>] [--check] [--write] [--json]
+  buildchain homebrew update-formula --package <name> --release-passport <file-or-url> [--write] [--json]
+  buildchain homebrew check [--cwd <dir>] [--package <name>] [--release-passport <file-or-url>] [--json]
+  buildchain publish-source <lock|manifest|verify-lock|verify-channel-ref|validate-anchored-release> ...
+  buildchain build-contract ...
+
+Examples:
+  buildchain init --type package --package-manager pnpm
+  buildchain validate --require-version-state --require-lifecycle-stages build,verify
+  buildchain lifecycle run build --artifact-path dist --artifact-name "{repo}-{version}-{platform}"
+  buildchain npm dry-run --json
+  buildchain release --dry-run --target-ref alpha/v3/v3.0
+  buildchain release line open --major 3 --minor 1 --source-ref release/v3/v3.0 --json
+  buildchain span --event native.build -- cmake --build build
+  buildchain collect github-release --tag v3.0.0 --assets-dir dist --output-dir .buildchain/release-passport
+  buildchain create publication-admission --input-json admission-input.json --output admission.json
+  buildchain create runner-provenance --input-json runner-input.json --output runner.json
+  buildchain verify release-passport .buildchain/release-passport/buildchain.release.json
+  buildchain verify publication-admission admission.json --registry-json publication-authority-registry.json --runner-json runner.json --control-plane-audit-json control-plane.json --expected-json expected.json --json
+  buildchain audit publication-control-plane --repository kungfu-systems/buildchain --branch release/v3/v3.0
+  buildchain verify artifact ./dist/buildchain-x86_64-unknown-linux-gnu.tar.gz --passport .buildchain/release-passport/buildchain.release.json
+  buildchain verify artifact-envelope .buildchain/kfx/artifact-verification-envelope.json --json
+  buildchain project kfx-admission .buildchain/kfx/artifact-verification-envelope.json --json
+  buildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json
+  buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build
+  buildchain infra-contract --mode plan --source-sha <sha>
+  buildchain infra-contract --mode ci --source-sha <sha>
+  buildchain infra-contract --mode plan --source-sha <sha> --execute-adapter-commands true
+  buildchain infra-contract --mode apply --plan <plan.json> --source-sha <sha> --approval-id <id>
+  buildchain infra-contract --mode apply --plan <plan.json> --source-sha <sha> --approval-id <id> --dry-run false --execute-adapter-commands true
+  buildchain infra-contract --mode propagation-apply --propagation-plan <plan.json> --dry-run true
+  buildchain infra-contract --mode evidence-bundle --artifact <artifact.json> --propagation-result <result.json>
+  buildchain publication-artifact manifest --source-sha <sha> --json
+  buildchain paper preflight --json
+  buildchain paper status --json
+  buildchain release-propagation plan --graph graph.json --upstream-release release.json --json
+  buildchain kfd status --json
+  buildchain kfd schema list --json
+  buildchain kfd 1 witness --json
+  buildchain kfd 2 claims --json
+  buildchain kfd 2 trust-assessment --json
+  buildchain kfd upstream collect --json
+  buildchain kfd aggregate --json
+  buildchain kfd 3 query buildchain --json
+`;

package/scripts/buildchain-contract-lock.mjs

@@ -131,7 +131,7 @@ export function writeBuildchainContractLock({
   output = env("BUILDCHAIN_CONTRACT_LOCK_PATH", BUILDCHAIN_CONTRACT_LOCK_PATH),
   currentContractPath = env("BUILDCHAIN_CONTRACT_CURRENT_PATH", "dist/site/buildchain-contract.json"),
   runtimeRoot = env("BUILDCHAIN_RUNTIME_ROOT", process.cwd()),
-  buildchainRef = env("BUILDCHAIN_RUNTIME_REF", "v2"),
+  buildchainRef = env("BUILDCHAIN_RUNTIME_REF", "v3"),
   resolvedSha = env("BUILDCHAIN_RUNTIME_SHA"),
   compatibilityPolicy = env("BUILDCHAIN_CONTRACT_COMPATIBILITY_POLICY", "major-compatible"),
   acceptedAt = env("BUILDCHAIN_CONTRACT_ACCEPTED_AT") || new Date().toISOString(),

package/scripts/check-internal-architecture.mjs

@@ -42,6 +42,52 @@ function resolveImportTarget(root, sourcePath, specifier) {
   return normalizeRelative(root, absolute);
 }
 
+function resolveGraphTarget(root, sourcePath, specifier, implementationPaths) {
+  const target = resolveImportTarget(root, sourcePath, specifier);
+  return [
+    target,
+    `${target}.js`,
+    `${target}.mjs`,
+    `${target}.cjs`,
+    `${target}/index.js`,
+    `${target}/index.mjs`,
+  ].find((candidate) => implementationPaths.has(candidate));
+}
+
+function dependencyCycles(graph) {
+  const cycles = [];
+  const visited = new Set();
+  const active = new Set();
+  const stack = [];
+  const canonical = new Set();
+  const visit = (node) => {
+    if (active.has(node)) {
+      const start = stack.indexOf(node);
+      const cycle = [...stack.slice(start), node];
+      const members = cycle.slice(0, -1);
+      const rotations = members.map((_, index) => [
+        ...members.slice(index),
+        ...members.slice(0, index),
+      ].join(" -> "));
+      const key = rotations.sort()[0];
+      if (!canonical.has(key)) {
+        canonical.add(key);
+        cycles.push(cycle);
+      }
+      return;
+    }
+    if (visited.has(node)) return;
+    visited.add(node);
+    active.add(node);
+    stack.push(node);
+    for (const target of graph.get(node) || []) visit(target);
+    stack.pop();
+    active.delete(node);
+  };
+  for (const node of [...graph.keys()].sort()) visit(node);
+  return cycles;
+}
+
 function assertIndexShape(index) {
   if (index?.schemaVersion !== 1) {
     throw new Error("internal architecture index schemaVersion must be 1");
@@ -74,6 +120,9 @@ function checkInternalArchitecture({
       continue;
     }
     capabilityIds.add(capability.id);
+    if (!capability.owner || typeof capability.owner !== "string") {
+      issues.push(`${capability.id}: owner is empty`);
+    }
     if (!Array.isArray(capability.implementation) || capability.implementation.length === 0) {
       issues.push(`${capability.id}: implementation mapping is empty`);
     }
@@ -139,6 +188,22 @@ function checkInternalArchitecture({
     }
   }
 
+  const graph = new Map([...expectedImplementation].map((file) => [file, new Set()]));
+  for (const sourcePath of expectedImplementation) {
+    if (![".js", ".mjs", ".cjs"].includes(path.extname(sourcePath))) continue;
+    const source = sourceOverrides.has(sourcePath)
+      ? sourceOverrides.get(sourcePath)
+      : fs.readFileSync(path.resolve(root, sourcePath), "utf8");
+    for (const specifier of relativeImports(source)) {
+      const target = resolveGraphTarget(root, sourcePath, specifier, expectedImplementation);
+      if (target) graph.get(sourcePath).add(target);
+    }
+  }
+  const cycles = dependencyCycles(graph);
+  for (const cycle of cycles) {
+    issues.push(`internal dependency cycle: ${cycle.join(" -> ")}`);
+  }
+
   if (issues.length > 0) {
     throw new Error(
       `internal architecture check failed:\n- ${issues.join("\n- ")}`,
@@ -149,6 +214,7 @@ function checkInternalArchitecture({
     capabilities: index.capabilities.length,
     implementations: expectedImplementation.size,
     dependencyRules: index.dependencyRules.length,
+    dependencyCycles: cycles.length,
   };
 }
 
@@ -160,7 +226,8 @@ if (
     const report = checkInternalArchitecture();
     console.log(
       `internal architecture check passed: ${report.capabilities} capabilities, ` +
-        `${report.implementations} implementations, ${report.dependencyRules} dependency rules`,
+        `${report.implementations} implementations, ${report.dependencyRules} dependency rules, ` +
+        `${report.dependencyCycles} cycles`,
     );
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
@@ -168,4 +235,4 @@ if (
   }
 }
 
-export { checkInternalArchitecture, relativeImports };
+export { checkInternalArchitecture, dependencyCycles, relativeImports };

package/scripts/check-inventory.mjs

@@ -56,6 +56,9 @@ const requiredPaths = [
   "packages/core/anchored-version-material.js",
   "packages/core/build-facts.js",
   "packages/core/publication-package.js",
+  "packages/core/publication-reproducibility.js",
+  "packages/core/publication-sealed-bundle.js",
+  "packages/core/paper.js",
   "packages/core/release-line-bootstrap.js",
   "packages/core/public-surface-audit.js",
   "docs/MAP.md",
@@ -73,10 +76,14 @@ const requiredPaths = [
   "docs/auditable-demo.md",
   "contracts/auditable-demo-media-profiles-v1.json",
   "contracts/evidence/auditable-demo-web-delivery-v1.json",
+  "contracts/evidence/auditable-demo-responsive-web-delivery-v1.json",
   "contracts/buildchain-v2-residuals-v1.json",
   "contracts/fixtures/auditable-demo-web-delivery-v1/complete-transcript.txt",
   "contracts/fixtures/auditable-demo-web-delivery-v1/public-projection.json",
   "contracts/fixtures/auditable-demo-web-delivery-v1/scene.json",
+  "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/complete-transcript.txt",
+  "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/public-projection.json",
+  "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/scene.json",
   "docs/release-propagation.md",
   "docs/site-bundle-contract.md",
   "docs/toolkit-observability.md",
@@ -102,8 +109,10 @@ const requiredPaths = [
   "scripts/anchored-version-material.mjs",
   "scripts/npm-publish-dry-run.mjs",
   "scripts/npm-publish-transaction.mjs",
+  "scripts/paper.mjs",
   "scripts/publication-package.mjs",
   "scripts/publication-commit-evidence.mjs",
+  "scripts/publication-reproducibility.mjs",
   "scripts/release-candidate-resolver.mjs",
   "scripts/buildchain-patrol.mjs",
   "scripts/observed-evidence.mjs",
@@ -114,6 +123,7 @@ const requiredPaths = [
   "docs/observed-evidence-patrol.md",
   "docs/ownership.md",
   "tests/buildchain-inventory.json",
+  "tests/paper.test.mjs",
   ".buildchain/buildchain.toml",
   ".buildchain/contract-lock.json",
   ".buildchain/alpha-contract-lock.json",
@@ -261,12 +271,19 @@ for (const requiredSnippet of [
   `/${promotionShellRouting.stable.workflowPath}@${promotionShellRouting.stable.callRef}`,
   `STABLE_SHELL_REF: v${selfDogfoodMajor}`,
   "promotion-contract-lock-digest:",
-  "promotion runtime override is only allowed for trusted workflow_dispatch runs",
+  "authorize-promotion-runtime-override.cjs",
 ]) {
   if (!channelPromotionWorkflow.includes(requiredSnippet)) {
     throw new Error(`channel promotion workflow missing routing contract: ${requiredSnippet}`);
   }
 }
+const promotionOverrideAuthorization = fs.readFileSync(
+  path.join(root, "scripts/authorize-promotion-runtime-override.cjs"),
+  "utf8",
+);
+if (!promotionOverrideAuthorization.includes("promotion runtime override is only allowed for trusted workflow_dispatch runs")) {
+  throw new Error("promotion runtime override authorization must remain fail closed");
+}
 for (const requiredSnippet of [
   "buildchain-channel:",
   "uses: ./.github/workflows/.build.yml",
@@ -383,6 +400,9 @@ if (rootPackage.exports?.["./buildchain-kfd-claims"] !== "./packages/core/buildc
 if (rootPackage.exports?.["./public-surface-audit"] !== "./packages/core/public-surface-audit.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/public-surface-audit");
 }
+if (rootPackage.exports?.["./paper"] !== "./packages/core/paper.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/paper");
+}
 if (rootPackage.exports?.["./site/buildchain-site.json"] !== "./dist/site/buildchain-site.json") {
   throw new Error("root package must export @kungfu-tech/buildchain/site/buildchain-site.json");
 }
@@ -647,16 +667,60 @@ for (const manual of manualRegistry.manuals || []) {
   }
 }
 const cliRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/cli-registry.json"), "utf8"));
+const requiredPublicLifecycleFields = [
+  "owner",
+  "maturity",
+  "introducedVersion",
+  "compatibilityPromise",
+  "deprecationReplacement",
+  "sunsetCondition",
+  "capabilityGroup",
+  "nonDuplicationRationale",
+];
+function assertPublicLifecycle(entry, label) {
+  for (const field of requiredPublicLifecycleFields) {
+    if (!Object.prototype.hasOwnProperty.call(entry, field) || typeof entry[field] !== "string") {
+      throw new Error(`${label} missing public lifecycle field: ${field}`);
+    }
+  }
+  if (!entry.owner || !entry.maturity || !entry.introducedVersion || !entry.compatibilityPromise || !entry.sunsetCondition || !entry.nonDuplicationRationale) {
+    throw new Error(`${label} has incomplete public lifecycle metadata`);
+  }
+}
 for (const command of cliRegistry.commands || []) {
   if (!command.capabilityGroup || !capabilityGroupIds.has(command.capabilityGroup) || !Array.isArray(command.audience) || !command.maturity || !command.purpose || command.purpose.includes("Add a specific purpose")) {
     throw new Error(`cli-registry.json command missing capability metadata: ${command.id || command.usage}`);
   }
+  assertPublicLifecycle(command, `cli-registry.json command ${command.id || command.usage}`);
 }
 const nodeApiRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/node-api-registry.json"), "utf8"));
 for (const exported of nodeApiRegistry.exports || []) {
   if (!exported.capabilityGroup || !capabilityGroupIds.has(exported.capabilityGroup) || !Array.isArray(exported.audience) || !exported.maturity || !exported.summary) {
     throw new Error(`node-api-registry.json export missing capability metadata: ${exported.export || exported.specifier}`);
   }
+  assertPublicLifecycle(exported, `node-api-registry.json export ${exported.export || exported.specifier}`);
+}
+const workflowRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/workflow-registry.json"), "utf8"));
+for (const workflow of workflowRegistry.workflows || []) {
+  assertPublicLifecycle(workflow, `workflow-registry.json workflow ${workflow.id || workflow.path}`);
+}
+for (const action of workflowRegistry.actions || []) {
+  assertPublicLifecycle(action, `workflow-registry.json action ${action.id || action.path}`);
+}
+const registeredActionIds = (workflowRegistry.actions || []).map((entry) => entry.id).sort();
+const readmeActionIndex = fs.readFileSync(path.join(root, "README.md"), "utf8");
+const mapActionIndex = fs.readFileSync(path.join(root, "docs/MAP.md"), "utf8");
+const retrospectiveActionIndex = fs.readFileSync(path.join(root, ".github/retrospectives/2026-07-10-buildchain-consolidation.md"), "utf8");
+if (registeredActionIds.length !== 6) {
+  throw new Error(`workflow-registry.json must expose the six current action entries, got ${registeredActionIds.length}`);
+}
+for (const actionId of registeredActionIds) {
+  if (!readmeActionIndex.includes(`actions/${actionId}`) || !mapActionIndex.includes(`actions/${actionId}`)) {
+    throw new Error(`README and docs/MAP.md must index registered action: ${actionId}`);
+  }
+}
+if (!retrospectiveActionIndex.includes("snapshot of the four consumer-facing actions")) {
+  throw new Error("the v2 four-action retrospective must remain explicitly classified as historical");
 }
 if (!pageRegistry.pages?.some((page) => page.sourcePath === "actions/promote-buildchain-ref/README.md")) {
   throw new Error("page-registry.json must include action manuals");
@@ -1069,7 +1133,10 @@ if (commonJsSourcePattern.test(npmDryRunScript)) {
 }
 for (const requiredSnippet of [
   "BUILDCHAIN_PUBLISH_EVIDENCE",
-  "\"publish\", \"--access\", access, \"--tag\", distTag",
+  "BUILDCHAIN_SEALED_NPM_TARBALL",
+  "...(pack.tarballPath ? [pack.tarballPath] : [])",
+  "\"--access\"",
+  "\"--tag\"",
   "artifact digest mismatch",
 ]) {
   if (!npmPublishTransactionScript.includes(requiredSnippet)) {

package/scripts/check-javascript-syntax.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+
+const root = process.cwd();
+const files = execFileSync(
+  "git",
+  ["ls-files", "--cached", "--others", "--exclude-standard"],
+  { cwd: root, encoding: "utf8" },
+)
+  .split("\n")
+  .filter((file) => [".js", ".mjs", ".cjs"].includes(path.extname(file)))
+  .filter((file) => !/^actions\/[^/]+\/dist\//u.test(file))
+  .sort();
+
+const failures = [];
+for (const file of files) {
+  const result = spawnSync(process.execPath, ["--check", file], {
+    cwd: root,
+    encoding: "utf8",
+  });
+  if (result.status !== 0) {
+    failures.push(`${file}: ${(result.stderr || result.stdout).trim()}`);
+  }
+}
+
+if (failures.length > 0) {
+  throw new Error(`JavaScript syntax check failed:\n${failures.join("\n")}`);
+}
+console.log(`JavaScript syntax check passed: ${files.length} files`);