@kungfu-tech/buildchain 3.0.6 → 3.0.7-alpha.0

package/README.md

@@ -278,13 +278,14 @@ plus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These
 gates preserve product-owned qualification and support decisions; they do not
 turn a schema-valid record into certification or shipped support.
 
-Buildchain's action registry currently contains six active entries. Four are
+Buildchain's action registry currently contains seven active entries. Five are
 direct consumer integration actions:
 
 - `actions/validate-config`
 - `actions/run-lifecycle`
 - `actions/promote-buildchain-ref`
 - `actions/report-buildchain-issue`
+- `actions/release-tail`
 
 Two additional release-authority components are also registered and versioned:
 
@@ -292,7 +293,7 @@ Two additional release-authority components are also registered and versioned:
 - `actions/macos-credential-island`
 
 `dist/site/workflow-registry.json#actions` is the machine-readable inventory;
-this split keeps the older four-action consumer list from being mistaken for
+this split keeps the older four-action consumer snapshot from being mistaken for
 the complete current registry.
 
 The active reusable workflow surfaces are:
@@ -457,4 +458,5 @@ npm pack --dry-run --json --registry=https://registry.npmjs.org/
 - [Release candidate passport](docs/release-candidate.md)
 - [Consumer issue reporting](docs/consumer-issue-reporting.md)
 - [Publish transaction](docs/publish-transaction.md)
+- [Declarative release-tail contract](docs/release-tail-contract.md)
 - [Release governance](docs/release-governance.md)

package/actions/release-tail/README.md

@@ -0,0 +1,17 @@
+# Declarative Release Tail
+
+This Action restores one content-addressed
+`kungfu.buildchain.publication-rehearsal-capsule/v1` and invokes the same public
+rehearsal runtime used by the local CLI. The capsule binds the versioned
+`buildchain.release-tail/v1` declaration, candidate files, policies, Passport,
+transaction, data-only provider bindings and observations. It does not accept
+a command, script, executable path, plugin, repository callback, implicit
+workspace or GitHub runner semantic input.
+
+Every mutation is preceded and followed by provider readback. Buildchain core,
+not the adapter, compares the observed subject and target roots, owns retry and
+terminal classification, checkpoints state and emits the standardized receipt.
+Tokens remain Action inputs and are never written to the transaction or
+receipt. The wrapper contributes only credentials, GitHub/HTTPS transport and
+real provider observations. The rooted provider transcript and rehearsal
+evidence are retained with the transaction state.

package/bin/buildchain.mjs

@@ -9,6 +9,7 @@ import { npmPublishDryRun } from "../scripts/npm-publish-dry-run.mjs";
 import { runLifecycle } from "../scripts/run-lifecycle-core.mjs";
 import { runReleasePropagationCli } from "../scripts/release-propagation.mjs";
 import { runReleaseGovernanceCli } from "../scripts/reconcile-release-governance.mjs";
+import { runReleaseTailCli } from "../scripts/release-tail.mjs";
 import { runPublicationArtifactCli } from "../scripts/publication-artifact.mjs";
 import { runPublicationPackageCli } from "../scripts/publication-package.mjs";
 import { runPublicationReproducibilityCli } from "../scripts/publication-reproducibility.mjs";
@@ -1646,6 +1647,10 @@ async function handleReleaseGovernanceCommand(args) {
 
 }
 
+async function handleReleaseTailCommand(args) {
+  await runReleaseTailCli(args);
+}
+
 async function handleGitHubGovernanceCommand(args) {
     runScript("reconcile-github-governance.mjs", args);
     return;
@@ -1706,6 +1711,10 @@ async function handlePublishSourceCommand(args) {
 
 }
 
+async function handleArchitectureCommand(args) {
+  runScript("v4-architecture.mjs", args);
+}
+
 const BUILDCHAIN_COMMAND_HANDLERS = Object.freeze({
   "help": handleHelpCommand,
   "version": handleVersionCommand,
@@ -1737,11 +1746,13 @@ const BUILDCHAIN_COMMAND_HANDLERS = Object.freeze({
   "paper": handlePaperCommand,
   "release-propagation": handleReleasePropagationCommand,
   "release-governance": handleReleaseGovernanceCommand,
+  "release-tail": handleReleaseTailCommand,
   "github-governance": handleGitHubGovernanceCommand,
   "badges": handleBadgesCommand,
   "homebrew": handleHomebrewCommand,
   "build-contract": handleBuildContractCommand,
   "publish-source": handlePublishSourceCommand,
+  "architecture": handleArchitectureCommand,
 });
 
 async function main(argv = process.argv.slice(2)) {

package/bin/internal/command-registry.mjs

@@ -32,11 +32,13 @@ const BUILDCHAIN_COMMAND_REGISTRY = Object.freeze([
   { id: "paper", aliases: [] },
   { id: "release-propagation", aliases: [] },
   { id: "release-governance", aliases: [] },
+  { id: "release-tail", aliases: [] },
   { id: "github-governance", aliases: [] },
   { id: "badges", aliases: [] },
   { id: "homebrew", aliases: [] },
   { id: "build-contract", aliases: [] },
   { id: "publish-source", aliases: [] },
+  { id: "architecture", aliases: [] },
 ]);
 
 function buildCommandLookup(registry = BUILDCHAIN_COMMAND_REGISTRY) {

package/contracts/fixtures/release-tail-capabilities-v1/kungfu-alpha.json

@@ -0,0 +1,273 @@
+{
+  "contract": "kungfu-buildchain-release-tail-capabilities",
+  "schemaVersion": 1,
+  "transactionPolicy": "buildchain.release-tail/v1",
+  "subject": {
+    "repository": "kungfu-systems/kungfu",
+    "sourceSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "version": "4.0.0-alpha.1",
+    "tag": "v4.0.0-alpha.1",
+    "channel": "alpha"
+  },
+  "capabilities": [
+    {
+      "id": "artifact.publish",
+      "executor": "provider-adapter",
+      "adapter": "github-release-assets",
+      "artifactRoles": [
+        {
+          "role": "installable-product",
+          "root": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
+        },
+        {
+          "role": "release-passport",
+          "root": "sha256:2222222222222222222222222222222222222222222222222222222222222222"
+        }
+      ],
+      "destination": {
+        "kind": "github-release",
+        "locator": "github-release:kungfu-systems/kungfu@v4.0.0-alpha.1"
+      },
+      "channelPolicy": {
+        "channel": "alpha",
+        "tagPattern": "^v4\\.0\\.0-alpha\\.[0-9]+$",
+        "authorityMove": "verified-ref"
+      },
+      "activationPolicy": { "mode": "none", "environment": "none" },
+      "readbackPredicates": [
+        {
+          "id": "release-assets-match-roots",
+          "kind": "provider-assets",
+          "expected": "all declared artifact roots are publicly readable"
+        }
+      ],
+      "effect": {
+        "kind": "artifact-publication",
+        "schema": "kungfu.buildchain.release-tail.effect/v1"
+      },
+      "observation": {
+        "kind": "artifact-publication-readback",
+        "schema": "kungfu.buildchain.release-tail.observation/v1"
+      },
+      "receipt": {
+        "kind": "artifact-publication",
+        "schema": "kungfu.buildchain.release-tail.receipt/v1"
+      },
+      "operationIdentity": {
+        "transactionRoot": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+        "capabilityId": "artifact.publish",
+        "subjectRoot": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
+        "targetRoot": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
+        "attemptKey": "artifact.publish/1"
+      },
+      "idempotency": {
+        "scope": "subject-target",
+        "duplicate": "readback-before-retry"
+      },
+      "retry": {
+        "class": "provider-transient",
+        "localAttempts": 2,
+        "exhausted": "repair-required"
+      },
+      "evidenceRequirements": [
+        "kungfu-buildchain-publish-evidence",
+        "kungfu-buildchain-release-passport"
+      ]
+    },
+    {
+      "id": "signed-channel.commit",
+      "executor": "provider-adapter",
+      "adapter": "signed-static-channel",
+      "artifactRoles": [
+        {
+          "role": "signed-channel-index",
+          "root": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
+        },
+        {
+          "role": "installer-publication-bundle",
+          "root": "sha256:6666666666666666666666666666666666666666666666666666666666666666"
+        }
+      ],
+      "destination": {
+        "kind": "well-known-signed-channel",
+        "locator": "https://kungfu.tech/.well-known/kungfu/alpha.json"
+      },
+      "channelPolicy": {
+        "channel": "alpha",
+        "tagPattern": "^v4\\.0\\.0-alpha\\.[0-9]+$",
+        "authorityMove": "signed-cas"
+      },
+      "activationPolicy": { "mode": "none", "environment": "none" },
+      "readbackPredicates": [
+        {
+          "id": "signed-channel-root",
+          "kind": "public-signed-document",
+          "expected": "signature, payload root, source SHA, tag, and previous authority match"
+        }
+      ],
+      "effect": {
+        "kind": "signed-channel-commit",
+        "schema": "kungfu.buildchain.release-tail.effect/v1"
+      },
+      "observation": {
+        "kind": "signed-channel-readback",
+        "schema": "kungfu.buildchain.release-tail.observation/v1"
+      },
+      "receipt": {
+        "kind": "publication-commit",
+        "schema": "kungfu.buildchain.release-tail.receipt/v1"
+      },
+      "operationIdentity": {
+        "transactionRoot": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+        "capabilityId": "signed-channel.commit",
+        "subjectRoot": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
+        "targetRoot": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
+        "attemptKey": "signed-channel.commit/1"
+      },
+      "idempotency": {
+        "scope": "subject-target",
+        "duplicate": "return-observed-receipt"
+      },
+      "retry": {
+        "class": "readback",
+        "localAttempts": 2,
+        "exhausted": "repair-required"
+      },
+      "evidenceRequirements": [
+        "kungfu-buildchain-publication-commit-evidence/v1"
+      ]
+    },
+    {
+      "id": "release.activate",
+      "executor": "provider-adapter",
+      "adapter": "site-release-activation",
+      "artifactRoles": [
+        {
+          "role": "activation-receipt-set",
+          "root": "sha256:9999999999999999999999999999999999999999999999999999999999999999"
+        }
+      ],
+      "destination": {
+        "kind": "production-site",
+        "locator": "https://kungfu.tech/.well-known/kungfu-release-status.json"
+      },
+      "channelPolicy": {
+        "channel": "alpha",
+        "tagPattern": "^v4\\.0\\.0-alpha\\.[0-9]+$",
+        "authorityMove": "verified-ref"
+      },
+      "activationPolicy": {
+        "mode": "receipt-set",
+        "environment": "production"
+      },
+      "readbackPredicates": [
+        {
+          "id": "release-status-current",
+          "kind": "public-json",
+          "expected": "source, site source, version, tag, channel, and Passport roots match"
+        },
+        {
+          "id": "installable-product-qualified",
+          "kind": "public-product-qualification",
+          "expected": "a public qualification asset matches an admitted artifact root"
+        }
+      ],
+      "effect": {
+        "kind": "release-activation",
+        "schema": "kungfu.buildchain.release-tail.effect/v1"
+      },
+      "observation": {
+        "kind": "production-readback",
+        "schema": "kungfu.buildchain.release-tail.observation/v1"
+      },
+      "receipt": {
+        "kind": "activation-receipt-set",
+        "schema": "kungfu.buildchain.release-tail.receipt/v1"
+      },
+      "operationIdentity": {
+        "transactionRoot": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+        "capabilityId": "release.activate",
+        "subjectRoot": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "targetRoot": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "attemptKey": "release.activate/1"
+      },
+      "idempotency": {
+        "scope": "operation",
+        "duplicate": "readback-before-retry"
+      },
+      "retry": {
+        "class": "provider-transient",
+        "localAttempts": 2,
+        "exhausted": "blocked"
+      },
+      "evidenceRequirements": [
+        "kungfu-buildchain-release-activation-receipt-set/v1",
+        "kungfu.release-public-readback/v1",
+        "kungfu.cli-installed-product-qualification/v1"
+      ]
+    },
+    {
+      "id": "released-evidence.synthesize",
+      "executor": "buildchain-core",
+      "adapter": "activation-receipt-projector",
+      "artifactRoles": [
+        {
+          "role": "activation-receipt-set",
+          "root": "sha256:9999999999999999999999999999999999999999999999999999999999999999"
+        }
+      ],
+      "destination": {
+        "kind": "release-passport-attachment",
+        "locator": ".buildchain/release-evidence/ungfu-public-use.json"
+      },
+      "channelPolicy": {
+        "channel": "alpha",
+        "tagPattern": "^v4\\.0\\.0-alpha\\.[0-9]+$",
+        "authorityMove": "none"
+      },
+      "activationPolicy": {
+        "mode": "receipt-only",
+        "environment": "production"
+      },
+      "readbackPredicates": [
+        {
+          "id": "five-canonical-receipts",
+          "kind": "rooted-receipt-set",
+          "expected": "artifact, Passport, site, public readback, and product qualification receipts share one binding root"
+        }
+      ],
+      "effect": {
+        "kind": "released-evidence-projection",
+        "schema": "kungfu.buildchain.release-tail.effect/v1"
+      },
+      "observation": {
+        "kind": "released-evidence-validation",
+        "schema": "kungfu.buildchain.release-tail.observation/v1"
+      },
+      "receipt": {
+        "kind": "released-evidence",
+        "schema": "kungfu.buildchain.release-tail.receipt/v1"
+      },
+      "operationIdentity": {
+        "transactionRoot": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+        "capabilityId": "released-evidence.synthesize",
+        "subjectRoot": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+        "targetRoot": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+        "attemptKey": "released-evidence.synthesize/1"
+      },
+      "idempotency": {
+        "scope": "operation",
+        "duplicate": "return-observed-receipt"
+      },
+      "retry": {
+        "class": "never",
+        "localAttempts": 0,
+        "exhausted": "terminal-failure"
+      },
+      "evidenceRequirements": [
+        "kungfu-buildchain-release-activation-receipt-set/v1",
+        "kungfu-ungfu-release-evidence-index"
+      ]
+    }
+  ]
+}

package/contracts/publication-rehearsal-capsule-v1.schema.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.kungfu.ai/contracts/publication-rehearsal-capsule-v1.schema.json",
+  "title": "Buildchain publication rehearsal capsule",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contract",
+    "schemaVersion",
+    "root",
+    "declaration",
+    "policyRoots",
+    "passport",
+    "transaction",
+    "files",
+    "providerBindings",
+    "providerObservations",
+    "runtime"
+  ],
+  "properties": {
+    "contract": {
+      "const": "kungfu.buildchain.publication-rehearsal-capsule/v1"
+    },
+    "schemaVersion": { "const": 1 },
+    "root": { "$ref": "#/$defs/root" },
+    "declaration": {
+      "$ref": "release-tail-capabilities-v1.schema.json"
+    },
+    "policyRoots": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/root" }
+    },
+    "passport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "root"],
+      "properties": {
+        "path": { "$ref": "#/$defs/path" },
+        "root": { "$ref": "#/$defs/root" }
+      }
+    },
+    "transaction": {
+      "type": "object",
+      "required": [
+        "schema",
+        "transactionPolicy",
+        "transactionRoot",
+        "declarationRoot",
+        "planRoot",
+        "subject",
+        "state",
+        "operationOrder",
+        "operations",
+        "observations",
+        "receipts",
+        "failure",
+        "stateRoot"
+      ]
+    },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["role", "path", "size", "root"],
+        "properties": {
+          "role": { "type": "string", "minLength": 1 },
+          "path": { "$ref": "#/$defs/path" },
+          "size": { "type": "integer", "minimum": 0 },
+          "root": { "$ref": "#/$defs/root" }
+        }
+      }
+    },
+    "providerBindings": {
+      "$ref": "release-tail-provider-bindings-v1.schema.json"
+    },
+    "providerObservations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["operationId", "readbacks", "apply"],
+        "properties": {
+          "operationId": { "$ref": "#/$defs/root" },
+          "readbacks": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "#/$defs/observation" }
+          },
+          "apply": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["outcome", "code", "classification"],
+            "properties": {
+              "outcome": {
+                "enum": ["applied", "transient", "conflict"]
+              },
+              "code": { "type": "string", "minLength": 1 },
+              "classification": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["platform", "declaredEnvironment", "externalEffects"],
+      "properties": {
+        "platform": { "const": "portable" },
+        "declaredEnvironment": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" }
+        },
+        "externalEffects": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["capabilityId", "adapter", "kind"],
+            "properties": {
+              "capabilityId": { "type": "string", "minLength": 1 },
+              "adapter": { "type": "string", "minLength": 1 },
+              "kind": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "root": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "path": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*//)(?!.*\\\\).+$"
+    },
+    "observation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "outcome",
+        "subjectRoot",
+        "targetRoot",
+        "evidenceRoots",
+        "providerCode"
+      ],
+      "properties": {
+        "outcome": {
+          "enum": ["observed", "absent", "transient", "conflict"]
+        },
+        "subjectRoot": {
+          "anyOf": [{ "$ref": "#/$defs/root" }, { "const": "" }]
+        },
+        "targetRoot": {
+          "anyOf": [{ "$ref": "#/$defs/root" }, { "const": "" }]
+        },
+        "evidenceRoots": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/root" }
+        },
+        "providerCode": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}