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

package/docs/publication-rehearsal.md

@@ -0,0 +1,94 @@
+---
+status: preview
+period: 2026-08-08
+theme: buildchain-publication-rehearsal
+doc_type: product-manual
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-08
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-08
+  visible_context: Public rehearsal capsule runtime, release-tail provider plane, CLI, Action, workflow, and generated consumer surfaces.
+  invisible_context_boundary: No credentials, private provider state, signed URLs, or external publication receipts were read.
+---
+
+# Publication rehearsal
+
+Buildchain publication rehearsal runs the deterministic release tail locally
+from one `kungfu.buildchain.publication-rehearsal-capsule/v1` document. The
+normative rule is [ADR 0001](../architecture/decisions/0001-release-local-constructibility.md):
+every non-external release behavior must be locally constructible, and no
+semantic path may depend on GitHub runner state.
+
+The machine-readable shape is
+[`publication-rehearsal-capsule-v1.schema.json`](../contracts/publication-rehearsal-capsule-v1.schema.json).
+
+## Exact local command
+
+Run from the repository root after restoring the content-addressed candidate:
+
+```sh
+buildchain release-tail rehearse \
+  --capsule "$PWD/.buildchain/publication/rehearsal-capsule.json" \
+  --capsule-root "$PWD/.buildchain/publication/candidate" \
+  --mode simulate \
+  --state "$PWD/.buildchain/publication/rehearsal-state.json" \
+  --evidence "$PWD/.buildchain/publication/rehearsal-evidence.json"
+```
+
+Use `--mode replay` only when the capsule contains a complete recorded
+provider-response sequence. Both modes produce rooted evidence with
+`externalPublicationClaimed: false`.
+
+## Daily fixture and sealed-candidate modes
+
+For daily development, build a synthetic capsule with
+`createPublicationRehearsalCapsule`, use synthetic files and provider
+observations, and run `--mode simulate` or `--mode replay`. This fixture mode is
+for deterministic regression evidence only.
+
+Before publication qualification, restore the exact sealed candidate bytes,
+Passport, policy roots, initial transaction and recorded observations named by
+the retained capsule, then run the exact command above. Preserve the resulting
+binding root, transaction root, state root, receipt roots and evidence root.
+These roots qualify deterministic construction only; external publication and
+public readback still require their own authorities.
+
+## Capsule contents
+
+The capsule root commits to the release-tail declaration, ordered policy roots,
+Passport path/root, initial durable transaction, complete file inventory,
+data-only provider bindings, recorded observations, portable platform policy,
+declared environment keys, and the exact list of external effects. Every input
+file is a regular non-symlink file under the explicit absolute capsule root and
+must match its size and SHA-256 root.
+
+The CLI never reads `GITHUB_*`, infers a runner workspace, selects behavior from
+`process.platform`, or accepts executable hooks. An explicit environment JSON
+object must match the capsule declaration exactly.
+
+## Hosted parity
+
+The reusable `release-tail.yml` workflow passes the explicit capsule to the
+`actions/release-tail` wrapper. The wrapper supplies only GitHub/HTTP transport
+and declared secret inputs, then invokes the same
+`executePublicationRehearsal` public core used locally. Provider requests,
+responses, failures, transaction roots, receipt roots, and the final evidence
+root are retained together.
+
+Simulation or replay is development evidence. Provider mode can record real
+external observations, but it still does not replace Release Passport,
+attestation, registry, activation, public-readback, or protected-delivery
+authority.
+
+## Failure handling
+
+Diagnostics use
+`kungfu.buildchain.publication-rehearsal-diagnostic/v1`. Preserve the capsule,
+diagnostic root, binding root, and exact failed files. Repair the shared core or
+capsule locally and rerun before spending another hosted runner attempt.

package/docs/release-governance.md

@@ -610,6 +610,12 @@ The reusable caller supports `off`, read-only `shadow`, and fail-closed
 `required` rollout modes. GitHub Merge Queue remains the final protected-ref
 authority in every mode.
 
+Bounded-concurrency experiments use the separate effect-disabled Warrant
+shadow planner. It may evaluate at most two fully bound lanes from one exact
+observation, but it cannot mint a second production Warrant or mutate GitHub.
+Its aggregate threshold decision is qualification evidence for a later rollout
+change, not authority to change the live single-flight policy.
+
 The canonical consumer required check context is `check / check`, matching the
 reusable workflow call plus its `check` job. Buildchain's own `Verify` workflow
 emits the repository-local context `check`, so Buildchain self-promotion,
@@ -785,6 +791,12 @@ active semver dev line, so consumers do not pin patrol to a stale minor branch.
 The separate workflow names keep consumer schedules readable and stable while
 Buildchain adds new checks behind the cadence wrappers.
 
+Branch and pull-request residue uses the separate
+[`Engineering Housekeeper`](engineering-housekeeper.md) contract. Its scheduled
+callers are report-only and read-only by default; apply requires a manual,
+explicit two-part gate, exact provider-state revalidation, scoped job
+permissions, and rooted plan/report/receipt evidence.
+
 ## Package-Manager Adapters
 
 Old ABV assumed JavaScript repositories with root version state and often
@@ -816,8 +828,11 @@ declare version-state files and lifecycle commands without pretending every
 project is a Node workspace. Supported version files include JSON, TOML, and
 regex-based files such as `CMakeLists.txt` or `conanfile.py`.
 
-The promotion action consumes `version.files`, optional anchored/manual
-`version.derived_files`, and `lifecycle.verify`.
+The promotion action consumes `version.files`, optional
+`version.derived_files`, and `lifecycle.verify`. Semver and anchored/manual
+repositories may both declare lifecycle-regenerated tracked outputs as derived
+files; anchored/manual repositories additionally bind them into their committed
+version witnesses.
 The verify stage runs after generated version-state changes are applied locally
 and before any release refs move. If `verification-command` is passed directly
 to the action, that explicit command overrides `lifecycle.verify`.

package/docs/release-tail-contract.md

@@ -0,0 +1,160 @@
+---
+status: draft
+period: 2026-08-07
+theme: buildchain-release-tail-contract
+doc_type: architecture
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-07
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-07
+  visible_context: Buildchain dev/v3/v3.0 release workflows, promotion Action, transaction and activation code, local exact-head managed-consumer callers, and the Kungfu alpha release-tail implementation.
+  invisible_context_boundary: Did not read credentials, private logs, signed URLs, provider state, or unpublished release assets.
+---
+
+# Declarative release-tail contract
+
+Buildchain v3 currently lets a consumer repository provide shell commands at
+several points around publication. Those hooks made early adoption possible,
+but they also let a consumer redefine the final release transaction. The
+machine authority for the current inventory is
+[`architecture/release-tail-contract-inventory.json`](../architecture/release-tail-contract-inventory.json).
+The declaration schema is
+[`contracts/release-tail-capabilities-v1.schema.json`](../contracts/release-tail-capabilities-v1.schema.json).
+
+This contract freezes the replacement boundary. The Buildchain-owned provider
+implementation is documented in
+[`release-tail-provider-plane.md`](./release-tail-provider-plane.md). Adding the
+provider plane does not itself cut over a consumer, run a release, or
+reinterpret an already published release.
+
+## Current executable surfaces
+
+The reverse scan classifies 27 workflow, Action, config, and CLI coordinates
+into seven owned surface groups:
+
+| Surface                                                                  | Current role                                              | Replacement                                                 |
+| ------------------------------------------------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------- |
+| `publication-gate-command`, `publication-consumer-qualification-command` | Consumer-owned admission and predicate logic              | Buildchain-evaluated declarative predicates                 |
+| `publish-command`, `lifecycle.publish`                                   | Artifact/package materialization and provider publication | `artifact.publish`                                          |
+| KFD-3, invariant Passport, and attachment commands                       | Product-specific evidence generation                      | Typed evidence requirements and Buildchain-owned projectors |
+| `publication-commit-command`                                             | Final signed or well-known channel authority move         | `signed-channel.commit`                                     |
+| `release-activation-command`                                             | Site activation and production readback                   | `release.activate`                                          |
+| reusable-workflow `release-passport-evidence-command`                    | Receipt-only released-evidence synthesis                  | `released-evidence.synthesize`                              |
+| Action `verification-command`                                            | Version-state verification before release-tail execution  | Separate version-state contract; not part of release tail   |
+
+One name is already ambiguous. In the reusable promotion workflow,
+`release-passport-evidence-command` means post-activation released-evidence
+synthesis. In the lower-level promotion Action, the same name is a deprecated
+alias for `release-passport-attachment-command`. New declarations reject that
+cross-layer alias collision instead of preserving it as a permanent escape
+hatch.
+
+The current v3 managed-caller snapshot covers Buildchain self-bootstrap, both
+Buildchain paper release paths, Kungfu, Libnode, KFD, and the Kungfu product
+white paper. The inventory binds every snapshot to an exact commit, tree,
+workflow path, runtime ref, and the executable surface groups it uses. The
+legacy `agent-hub-demo@v2` caller is recorded but excluded from the v3 contract.
+
+## Capability declaration
+
+A declaration contains data, never repository shell. Four capability ids cover
+the current Kungfu alpha tail:
+
+1. `artifact.publish` publishes exact artifact roles to a declared destination.
+2. `signed-channel.commit` moves a signed channel authority only after artifact
+   and Passport prerequisites are durable.
+3. `release.activate` applies the production activation policy and evaluates
+   declared public readback predicates.
+4. `released-evidence.synthesize` consumes the validated activation receipt set
+   and deterministically projects released evidence.
+
+Every capability declares:
+
+- artifact roles and content roots;
+- destination, channel/tag, activation, and readback policy;
+- standardized effect, observation, and receipt schemas;
+- stable transaction, subject, target, capability, and attempt identity;
+- idempotency behavior and a bounded local retry class;
+- exact evidence requirements.
+
+Keys named `command`, `cmd`, `script`, `shell`, or `run` are forbidden anywhere
+in the declaration. Provider adapters may translate a rooted effect into API
+calls, read providers, and return observations. They may not select state
+transitions, change identity, synthesize success, or execute repository-owned
+shell.
+
+The checked fixture
+[`kungfu-alpha.json`](../contracts/fixtures/release-tail-capabilities-v1/kungfu-alpha.json)
+represents the current Kungfu flow: public release assets, the Ed25519-signed
+Alpha channel document, production status/acquisition/product readback, and
+released-evidence synthesis from five canonical activation receipts.
+
+## One release transaction
+
+`buildchain.release-tail/v1` is the only owner of the tail lifecycle:
+
+```text
+prepare
+  -> publish artifacts
+  -> commit signed channel authority
+  -> activate
+  -> read back every declared predicate
+  -> settle receipts and released evidence
+  -> complete | blocked | repair-required | terminal-failure
+```
+
+Each effect uses one stable operation identity. A duplicate attempt performs
+readback before any retry. `never`, `readback`, and `provider-transient` are the
+only retry classes, and no local executor may exceed three attempts. Provider
+conflict, identity drift, missing readback, and exhausted retry remain explicit
+terminal classifications; an adapter cannot convert them into success.
+
+## Compatibility and migration
+
+The compatibility window begins when
+`train/v3/v3.0/release-tail-contract` is published. It closes at the earlier of
+90 days or the first v3.2 stable release, and spans at most two minor lines.
+
+During that window:
+
+- previously published tags, assets, packages, signed channel documents,
+  Passports, and receipts remain immutable;
+- only the exact enumerated callers may use the legacy adapter;
+- every exception has an owner, the common expiry, and a removal test;
+- migrated declarations create new transactions and never reinterpret settled
+  history;
+- no new arbitrary command input or generic plugin is accepted.
+
+Cutover order is the Buildchain paper callers plus a self-bootstrap no-command
+regression, Kungfu's complete Alpha tail, Libnode evidence generation,
+KFD/white-paper no-command regression, then deletion of the Action alias and
+all remaining command inputs. This card
+defines that order only; consumer migrations are separate changes.
+
+## Failure rules
+
+The contract fails closed when:
+
+- a reverse scan discovers an unregistered command-bearing release-tail input;
+- one name maps to multiple capabilities;
+- an effect lacks stable operation identity;
+- a mutation lacks readback and receipt contracts;
+- local retry is unbounded;
+- an exception lacks an owner, expiry, or executable removal test.
+
+Run the contract check with:
+
+```bash
+node scripts/check-release-tail-contract.mjs
+node --test tests/release-tail-contract.test.mjs
+```
+
+The tests mutate the inventory and declaration fixtures to prove that orphaned
+hooks, ambiguous ownership, embedded commands, missing identity/readback,
+unbounded retry, and permanent escape hatches are rejected.

package/docs/release-tail-provider-plane.md

@@ -0,0 +1,120 @@
+---
+status: draft
+period: 2026-08-07
+theme: buildchain-release-tail-provider-plane
+doc_type: architecture
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-07
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-07
+  visible_context: Buildchain release-tail declaration, provider adapters, durable transaction implementation, CLI, Action, reusable workflow, tests, and frozen consumer inventory.
+  invisible_context_boundary: Did not read credentials, private provider state, signed URLs, unpublished release assets, or production receipts.
+---
+
+# Declarative release-tail provider plane
+
+Buildchain owns the final release tail as one versioned transaction. A consumer
+supplies a sealed capability declaration and data-only provider bindings; it
+does not supply shell, JavaScript, executable paths, callbacks, or plugins.
+The frozen boundary and migration inventory remain in
+[`release-tail-contract.md`](./release-tail-contract.md).
+
+## Public entry points
+
+- Node: `@kungfu-tech/buildchain/release-tail-provider-plane`,
+  `release-tail-provider-adapters`, `release-tail-compatibility`, and
+  `publication-rehearsal-runtime`.
+- CLI: `buildchain release-tail plan|init|status|verify|compat|rehearse`.
+- Action: `kungfu-systems/buildchain/actions/release-tail@<exact-ref>`.
+- reusable workflow: `kungfu-systems/buildchain/.github/workflows/release-tail.yml@<exact-ref>`.
+
+The CLI and Action both invoke the public publication rehearsal runtime over
+the same core transaction implementation. The Action is a thin provider
+transport wrapper; callers cannot inject an execution command or runner state.
+
+## Inputs and secrets
+
+The declaration follows
+[`release-tail-capabilities-v1.schema.json`](../contracts/release-tail-capabilities-v1.schema.json).
+Provider file and endpoint bindings follow
+[`release-tail-provider-bindings-v1.schema.json`](../contracts/release-tail-provider-bindings-v1.schema.json).
+Bindings contain paths, asset names, HTTP methods, and evidence input paths.
+GitHub and HTTP bearer tokens are separate secret inputs and never enter the
+effect plan, checkpoint, observation, receipt, or output.
+
+## Transaction semantics
+
+Declaration parsing rejects unknown fields, identity drift, unsupported
+capability/adapter pairs, unbounded retries, and executable keys recursively.
+Compilation produces deterministic effect and plan roots. Execution persists
+one atomic checkpoint containing ordered operations, rooted observations, and
+rooted receipts.
+
+For each effect Buildchain performs readback before mutation, applies at most
+the declared bounded local attempts, then performs readback again. Buildchain
+core alone compares the declared subject and target roots and chooses
+`complete`, `blocked`, `repair-required`, or `terminal-failure`. An adapter can
+report observed, absent, transient, or conflict; it cannot declare success.
+
+The built-in adapters are:
+
+- `github-release-assets`: exact GitHub Release tag and immutable named assets;
+- `signed-static-channel`: rooted HTTPS JSON channel commit with optional CAS;
+- `site-release-activation`: rooted HTTPS activation and public readback;
+- `activation-receipt-projector`: deterministic released-evidence synthesis.
+
+Duplicate execution is a readback no-op. A lost mutation response is recovered
+by the next local readback. A stale rooted object requires repair, immutable
+provider collision is terminal, and credential/network uncertainty remains a
+bounded blocked result rather than synthesized success.
+
+## Local verification
+
+```bash
+buildchain release-tail plan --declaration release-tail.json
+buildchain release-tail init --declaration release-tail.json --state .buildchain/release-tail/state.json
+buildchain release-tail verify --state .buildchain/release-tail/state.json
+```
+
+For complete local release semantics, use the exact capsule command in
+[`publication-rehearsal.md`](publication-rehearsal.md). Simulation and replay
+exercise planning, validation, transaction, retry, and evidence without
+claiming external provider truth. Provider execution belongs in the Action or
+reusable workflow so token handling and transport capabilities remain explicit.
+Retain the state and rehearsal evidence artifacts.
+
+## Buildchain self-dogfood route
+
+Buildchain self-release calls the same public reusable workflow coordinate as a
+consumer:
+
+```text
+kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@769b221bad7a6b9104afad4c2628d9dca396ab0f
+```
+
+The caller pins the public router and runtime to the same exact implementation
+SHA. Its internal alpha shell remains on the named train, so automatic
+`workflow_run` publication uses the immutable-router path without a manual
+runtime override. For alpha self-release, the promotion Action materializes the
+sealed GitHub Release asset declaration, executes it through this provider
+plane, and retains the
+declaration root, transaction root, state root, receipt roots, controller
+receipt, and route-parity evidence. The legacy GitHub Release helper is not a
+fallback when `declarative-release-tail` is enabled; a provider or readback
+failure fails the authoritative run.
+
+Stable routing remains on the existing `v3` shell and does not receive the new
+alpha-train input. Stable cutover is a separate gate after prerelease dogfood.
+
+## v3 compatibility boundary
+
+`release-tail compat --hooks-json <json-or-path>` recognizes only the frozen v3
+hook names. It emits diagnostics for enumerated legacy callers and rejects any
+new command-bearing release-tail field. Compatibility never converts legacy
+shell into a new provider plugin and never reinterprets settled release history.

package/docs/reusable-build-surface.md

@@ -683,6 +683,17 @@ For a declared macOS `archive`, the authority safely extracts the sealed
 container, signs and verifies every Mach-O payload, signs Mach-O payloads inside
 embedded Python wheels, rebuilds each affected wheel's PEP 427 `RECORD`, and
 recreates the original zip or tar.gz before returning the exact final bytes.
+Archives whose executable hosts a JIT runtime can additionally request the
+Buildchain-owned `entitlements_profile = "jit-executable-v1"` and exact paths,
+for example `entitlements_paths = ["product/runtime/python/bin/python3"]`.
+Paths are relative to the extracted archive root. The authority
+then attaches only `com.apple.security.cs.allow-jit` to the exact executable
+Mach-O files sealed in `entitlements_paths`, leaves every other executable and
+library without exception entitlements, and records the profile, paths, and
+entitled executable count in provider evidence. Consumer-provided entitlement
+files and wildcard target paths are unsupported. The profile is valid only for
+Apple `archive` requests and fails closed on an unsafe, missing,
+non-executable, duplicate, or unsealed target path.
 Windows `pe` and `binary` artifacts
 resolve to timestamped native `windows-authenticode`; Windows PE never falls
 back to a detached signature. Linux and other non-native binary files,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.6",
+  "version": "3.0.7-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -49,6 +49,8 @@
     "./publication-control-plane-audit": "./packages/core/publication-control-plane-audit.js",
     "./buildchain-publication-authority": "./packages/core/buildchain-publication-authority.js",
     "./github-governance-authority": "./packages/core/github-governance-authority.js",
+    "./engineering-housekeeper": "./packages/core/engineering-housekeeper.js",
+    "./engineering-housekeeper-github": "./packages/core/engineering-housekeeper-github.js",
     "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",
     "./release-candidate-recovery": "./packages/core/release-candidate-recovery.js",
@@ -57,6 +59,11 @@
     "./release-passport-contract": "./packages/core/release-passport-contract.js",
     "./release-propagation": "./packages/core/release-propagation.js",
     "./release-activation-transaction": "./packages/core/release-activation-transaction.js",
+    "./release-tail-provider-plane": "./packages/core/release-tail-provider-plane.js",
+    "./release-tail-provider-adapters": "./packages/core/release-tail-provider-adapters.js",
+    "./release-tail-compatibility": "./packages/core/release-tail-compatibility.js",
+    "./publication-rehearsal-runtime": "./packages/core/publication-rehearsal-runtime.js",
+    "./publication-rehearsal-projection": "./packages/core/publication-rehearsal-projection.js",
     "./surface-manifest": "./packages/core/surface-manifest.js",
     "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
@@ -111,8 +118,8 @@
   "packageManager": "pnpm@11.7.0",
   "scripts": {
     "operator:windows-jit": "bash scripts/aws-windows-jit-operator.sh",
-    "check": "pnpm run check:static && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm run check:golden-path && node scripts/check-action-bundles.mjs",
-    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json bin/internal/command-registry.mjs scripts/authorize-promotion-runtime-override.cjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/maintainability-metrics.mjs scripts/public-reference.mjs scripts/site-reference-registry.mjs scripts/generate-public-reference.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs",
+    "check": "pnpm run check:static && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && node scripts/check-core-mechanism-inventory.mjs && node scripts/check-release-tail-contract.mjs && node scripts/v4-architecture.mjs validate && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm run check:golden-path && node scripts/check-action-bundles.mjs",
+    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json contracts/release-tail-capabilities-v1.schema.json contracts/release-tail-provider-bindings-v1.schema.json contracts/publication-rehearsal-capsule-v1.schema.json contracts/fixtures/release-tail-capabilities-v1/*.json bin/internal/command-registry.mjs scripts/authorize-promotion-runtime-override.cjs scripts/check-core-mechanism-inventory.mjs scripts/check-release-tail-contract.mjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/maintainability-metrics.mjs scripts/public-reference.mjs scripts/site-reference-registry.mjs scripts/generate-public-reference.mjs scripts/v4-architecture.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/core-mechanism-inventory.test.mjs tests/release-tail-contract.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs tests/v4-architecture.test.mjs",
     "check:workflows": "bash scripts/check-workflows.sh",
     "generate:reference": "node scripts/generate-public-reference.mjs",
     "check:reference": "node scripts/generate-public-reference.mjs --check",
@@ -132,6 +139,7 @@
   },
   "dependencies": {
     "@kungfu-tech/kfd": "1.0.0-alpha.53",
+    "ajv": "8.20.0",
     "smol-toml": "1.7.0"
   }
 }

package/packages/core/artifact-signing.js

@@ -9,6 +9,7 @@ export const ARTIFACT_SIGNING_AUTHORITY_CONTRACT =
 
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/u;
 const SOURCE_SHA_PATTERN = /^[0-9a-f]{40}$/u;
+const ENTITLEMENTS_PROFILES = new Set(["none", "jit-executable-v1"]);
 const FORBIDDEN_CREDENTIAL_KEYS =
   /(?:certificate|password|private.?key|secret|token|notary|issuer|team.?id|environment)/iu;
 
@@ -88,6 +89,64 @@ function exactSourceSha(value, label) {
   return normalized;
 }
 
+function entitlementsPaths(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new Error("signing entitlements paths must be an array");
+  }
+  const paths = value.map((entry, index) => {
+    const normalized = nonEmptyString(
+      entry,
+      `signing entitlements paths[${index}]`,
+    );
+    const parts = normalized.split("/");
+    if (
+      normalized.startsWith("/") ||
+      normalized.includes("\\") ||
+      normalized.includes(",") ||
+      parts.some((part) => part === "" || part === "." || part === "..")
+    ) {
+      throw new Error(
+        `signing entitlements paths[${index}] must be a safe archive-relative path`,
+      );
+    }
+    return normalized;
+  });
+  if (new Set(paths).size !== paths.length) {
+    throw new Error("signing entitlements paths must not contain duplicates");
+  }
+  return paths;
+}
+
+function signingEntitlements(profileId, kind, signature) {
+  const profile = String(signature.entitlementsProfile || "none").trim();
+  const paths = entitlementsPaths(signature.entitlementsPaths);
+  if (!ENTITLEMENTS_PROFILES.has(profile)) {
+    throw new Error(
+      `unsupported signing entitlements profile: ${profile || "<empty>"}`,
+    );
+  }
+  if (
+    profile !== "none" &&
+    (profileId !== "apple-developer-id" || kind !== "archive")
+  ) {
+    throw new Error(
+      `signing entitlements profile ${profile} requires an Apple archive`,
+    );
+  }
+  if (
+    (profile === "none" && paths.length !== 0) ||
+    (profile !== "none" && paths.length === 0)
+  ) {
+    throw new Error(
+      "signing entitlements paths must be non-empty exactly when an entitlements profile is enabled",
+    );
+  }
+  return profile === "none"
+    ? {}
+    : { entitlementsProfile: profile, entitlementsPaths: paths };
+}
+
 function assertNoCredentialMaterial(value, path = "request") {
   if (!value || typeof value !== "object") return;
   for (const [key, child] of Object.entries(value)) {
@@ -191,6 +250,7 @@ export function createArtifactSigningRequest({
     platform,
     artifactKind: kind,
   });
+  const entitlementIntent = signingEntitlements(profile.id, kind, signature);
   const request = {
     schemaVersion: 1,
     contract: ARTIFACT_SIGNING_REQUEST_CONTRACT,
@@ -253,6 +313,7 @@ export function createArtifactSigningRequest({
       profile: profile.id,
       provider: profile.provider,
       semantics: profile.semantics,
+      ...entitlementIntent,
     },
     delivery: {
       mode: nonEmptyString(

package/packages/core/buildchain-agent-manuals.js

@@ -29,6 +29,9 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
   { id: "reusable-build-surface", title: "Reusable build surface", path: "docs/reusable-build-surface.md", plane: "use" },
   { id: "publish-transaction", title: "Publish transaction", path: "docs/publish-transaction.md", plane: "verify" },
+  { id: "release-tail-contract", title: "Declarative release-tail contract", path: "docs/release-tail-contract.md", plane: "verify" },
+  { id: "release-tail-provider-plane", title: "Declarative release-tail provider plane", path: "docs/release-tail-provider-plane.md", plane: "use" },
+  { id: "publication-rehearsal", title: "Publication rehearsal", path: "docs/publication-rehearsal.md", plane: "use" },
   { id: "release-governance", title: "Release governance", path: "docs/release-governance.md", plane: "why" },
   { id: "release-flow", title: "Release flow", path: "docs/release-flow.md", plane: "verify" },
   { id: "runtime-train-validation", title: "Runtime train validation", path: "docs/runtime-train-validation.md", plane: "verify" },