base-code-changed #4

Workflow file for this run

.github/workflows/base-std-docs-sync.yml at 1b4fa6b

	name: Apply Base Std Update

	on:
	repository_dispatch:
	types:
	- base-code-changed
	- base-release-published
	workflow_dispatch:
	inputs:
	payload_json:
	description: "Raw client_payload JSON (for manual runs)"
	required: false
	default: "{}"

	# Default minimum; the privileged job below raises only what it needs.
	permissions:
	contents: read

	concurrency:
	# Key by source_repo + sha (not sha alone) so two different source repos
	# dispatching the same SHA can't starve each other's queue. On
	# workflow_dispatch both client_payload fields are empty and we fall
	# back to run_id, which is always unique per run.
	group: ${{ github.workflow }}-${{ github.event.client_payload.source_repo \|\| 'manual' }}-${{ github.event.client_payload.sha \|\| github.run_id }}
	cancel-in-progress: false

	jobs:
	# --------------------------------------------------------------------------
	# 1) authorize: fork guard + write-permission check on the actor.
	# Runs with read-only token. If this job fails, `apply` never starts.
	# --------------------------------------------------------------------------
	authorize:
	name: Authorize trigger
	if: github.event.repository.fork == false
	# Keep every job in this workflow on BaseRunnerGroup. Besides providing a
	# consistent trusted execution environment, the downstream apply job uses
	# Base's internal LLM Gateway.
	runs-on:
	group: BaseRunnerGroup
	permissions:
	contents: read
	steps:
	- name: Validate actor and event
	env:
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	REPO: ${{ github.repository }}
	ACTOR: ${{ github.actor }}
	# github.event.sender.login is the ONLY server-attested identity
	# on a repository_dispatch — it's the user whose PAT/App token
	# called the dispatches API. We capture it explicitly here even
	# though it equals github.actor for these event types, so the
	# downstream audit log (and ALLOWED_SENDER_BINDINGS check in the
	# apply job) has a stable, documented field to key on.
	SENDER_LOGIN: ${{ github.event.sender.login }}
	EVENT: ${{ github.event_name }}
	run: \|
	set -euo pipefail
	# Both event types we accept (repository_dispatch from the source
	# repo's dispatcher, and workflow_dispatch from a maintainer) are
	# authorized the same way: the actor must have write-equivalent
	# permission on THIS repo, queried live from the GitHub
	# collaborators API.
	#
	# github.actor on a repository_dispatch is the user whose PAT was
	# used to call the dispatches API (e.g. the dispatcher's
	# DOCS_REPO_TOKEN owner). So this check answers: "does the PAT
	# owner who fired this dispatch have write access to this docs
	# repo?" — exactly the policy we want.
	case "$EVENT" in
	repository_dispatch\|workflow_dispatch) ;;
	*)
	echo "::error title=Unsupported event::event '$EVENT' is not in the allowlist (repository_dispatch\|workflow_dispatch)" >&2
	exit 1
	;;
	esac
	# Defense-in-depth invariant: for repository_dispatch and
	# workflow_dispatch, github.actor and github.event.sender.login
	# are documented to be the same value. If they ever diverge
	# (event-shape regression, or a future event type slipping
	# through the case above), fail closed rather than guess which
	# one to trust.
	if [[ -n "${SENDER_LOGIN:-}" && "$SENDER_LOGIN" != "$ACTOR" ]]; then
	echo "::error title=Sender identity mismatch::github.actor='${ACTOR}' but github.event.sender.login='${SENDER_LOGIN}' — refusing to run" >&2
	exit 1
	fi
	perm=$(curl -sS --fail-with-body \
	-H "Accept: application/vnd.github+json" \
	-H "Authorization: Bearer $GITHUB_TOKEN" \
	-H "X-GitHub-Api-Version: 2022-11-28" \
	"https://api.github.com/repos/${REPO}/collaborators/${ACTOR}/permission" \
	\| jq -r '.permission // "none"')
	case "$perm" in
	admin\|maintain\|write)
	echo "Actor '$ACTOR' (sender='${SENDER_LOGIN:-unknown}') has '$perm' permission on $REPO (event: $EVENT)."
	echo "::notice title=Authorization passed::actor=${ACTOR} sender=${SENDER_LOGIN:-unknown} permission=${perm} event=${EVENT}"
	;;
	*)
	echo "::error title=Actor not authorized::actor='${ACTOR}' sender='${SENDER_LOGIN:-unknown}' has '${perm}' permission on ${REPO} (event=${EVENT}) — refusing to run" >&2
	exit 1
	;;
	esac

	- name: Emit kill-switch notice (if set)
	# Repo variable: vars.DISABLE_BASE_SYNC. When set to "true", the
	# `apply` job is skipped via its job-level `if:` and we surface a
	# banner here so the run summary explains why nothing happened.
	# Lets a maintainer pause docs syncs during an incident without
	# revoking the dispatcher PAT or deleting the workflow.
	if: vars.DISABLE_BASE_SYNC == 'true'
	run: \|
	echo "::notice title=Base sync disabled::vars.DISABLE_BASE_SYNC is 'true' — authorization passed but the apply job is skipped."

	# --------------------------------------------------------------------------
	# 2) apply: privileged job. Delegates the actual content transformation to
	# scripts/sync-from-base-std, then commits the result and opens a PR.
	# --------------------------------------------------------------------------
	apply:
	name: Open docs PR from base-std dispatch
	needs: authorize
	# Kill switch: see "Emit kill-switch notice" step in the authorize job
	# above. Flipping vars.DISABLE_BASE_SYNC to 'true' skips this job
	# without affecting authorize (so the banner still fires).
	if: github.event.repository.fork == false && vars.DISABLE_BASE_SYNC != 'true'
	# Run where Base's internal LLM Gateway is available. The corresponding
	# Base gateway integration documents BaseRunnerGroup as a requirement.
	runs-on:
	group: BaseRunnerGroup
	permissions:
	contents: write
	pull-requests: write
	steps:
	- name: Harden the runner
	# Audit mode logs every outbound connection without blocking. After a
	# few real runs, review the egress report on the run summary and
	# switch to:
	# egress-policy: block
	# allowed-endpoints: >
	# api.github.com:443
	# llm-gateway.coinbase-corp.com:443
	# registry.npmjs.org:443
	# objects.githubusercontent.com:443
	# plus anything else the audit log surfaces (e.g. npm CDN hosts).
	uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
	with:
	egress-policy: audit

	- name: Checkout
	uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
	with:
	fetch-depth: 0

	- name: Setup Node
	uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
	with:
	node-version: "22"
	cache: "npm"
	cache-dependency-path: scripts/package-lock.json

	- name: Install dependencies
	run: npm ci --prefix scripts --no-audit --no-fund

	- name: Materialize dispatch payload
	id: payload_file
	env:
	# Routed through env — never inlined into the shell, so a hostile
	# PR title/body in the payload cannot escape into a command.
	PAYLOAD: ${{ toJSON(github.event.client_payload) }}
	MANUAL_PAYLOAD: ${{ github.event.inputs.payload_json }}
	EVENT_NAME: ${{ github.event_name }}
	# Captured once here and re-exported to $GITHUB_ENV below so
	# every downstream step (including the shared workflow_fail
	# helper) sees the same sender identity under one name.
	# github.event.sender.login is the only server-attested identity
	# on a repository_dispatch — it's the user/bot whose token
	# called the API.
	SENDER_LOGIN: ${{ github.event.sender.login }}
	run: \|
	set -euo pipefail
	raw_path="$RUNNER_TEMP/payload.raw"
	payload_path="$RUNNER_TEMP/payload.json"

	if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
	printf '%s' "$MANUAL_PAYLOAD" > "$raw_path"
	else
	printf '%s' "$PAYLOAD" > "$raw_path"
	fi

	# Normalize: a workflow_dispatch textarea sometimes ends up containing
	# the default '{}' alongside the user's paste, which produces a file
	# with two stacked JSON values. jq -s slurps them all into an array
	# and we keep the last non-empty object. Single-value inputs pass
	# through unchanged.
	jq -s '
	map(select(type == "object" and (. != {} or length == 0))) as $objs
	\| if ($objs \| length) == 0 then
	(.[-1] // {})
	else
	($objs \| .[-1])
	end
	' "$raw_path" > "$payload_path"

	# Final invariant: must be a single JSON object.
	jq -e 'type == "object"' "$payload_path" > /dev/null

	# Export payload fields into $GITHUB_ENV so downstream steps work
	# the same way on `repository_dispatch` and `workflow_dispatch`.
	# On workflow_dispatch, `github.event.client_payload` is null and
	# all the field expressions return empty strings — so without this,
	# the PR title/commit/PR-body construction sees blanks and
	# produces titles with no source SHA.
	#
	# Multi-line values (intent, pr_body, etc.) use the heredoc form
	# GitHub Actions requires for $GITHUB_ENV.
	set_env_multiline() {
	local key="$1"; local value="$2"
	{
	printf '%s<<EOF_PAYLOAD_VAL\n' "$key"
	printf '%s' "$value"
	printf '\nEOF_PAYLOAD_VAL\n'
	} >> "$GITHUB_ENV"
	}
	set_env_single() {
	local key="$1"; local value="$2"
	printf '%s=%s\n' "$key" "$value" >> "$GITHUB_ENV"
	}

	set_env_single PAYLOAD_KIND "$(jq -r '.kind // ""' "$payload_path")"
	# Required field. If absent, the allowlist step below will reject
	# the dispatch with a clear error.
	set_env_single PAYLOAD_SOURCE_REPO "$(jq -r '.source_repo // ""' "$payload_path")"
	set_env_single PAYLOAD_SHA "$(jq -r '.sha // ""' "$payload_path")"
	# Do not export tag before schema validation. Unlike SHA, it is a
	# newly introduced free-form payload field and a newline here would
	# create an attacker-controlled second GITHUB_ENV assignment.
	set_env_single PAYLOAD_PR_NUMBER "$(jq -r '.pr_number // ""' "$payload_path")"
	set_env_multiline PAYLOAD_PR_TITLE "$(jq -r '.pr_title // ""' "$payload_path")"
	set_env_multiline PAYLOAD_INTENT "$(jq -r '.intent // ""' "$payload_path")"
	# source_refs is an array; flatten to space-separated for shell use.
	set_env_single PAYLOAD_SOURCE_REFS "$(jq -r '(.source_refs // []) \| join(" ")' "$payload_path")"
	# For large diffs the dispatcher uploads the diff as an artifact
	# on the SOURCE repo and the payload only carries a reference.
	# We pick the two fields up here; the next step does the fetch.
	set_env_single PAYLOAD_DIFF_ARTIFACT_RUN_ID "$(jq -r '.diff_artifact_run_id // ""' "$payload_path")"
	set_env_single PAYLOAD_DIFF_ARTIFACT_NAME "$(jq -r '.diff_artifact_name // ""' "$payload_path")"

	# Propagate the sender identity to every downstream step so
	# rejection messages and the workflow_fail helper see the same
	# field. The value originates in the step `env:` block above.
	set_env_single SENDER_LOGIN "${SENDER_LOGIN:-}"

	# OIDC attestation token — Phase 1 is verify-when-present (Phase 2
	# will make it required). Write the JWT to a private file at
	# $RUNNER_TEMP and pass only the PATH downstream so the token
	# itself never sits in $GITHUB_ENV. We mask the value too as
	# belt-and-suspenders against accidental log echo. PAYLOAD_OIDC_PRESENT
	# ("true"/"false") lets downstream steps decide between fail-closed
	# verification and a soft warning.
	oidc_token_value=$(jq -r '.oidc_token // ""' "$payload_path")
	if [[ -n "$oidc_token_value" ]]; then
	echo "::add-mask::$oidc_token_value"
	oidc_token_path="$RUNNER_TEMP/oidc-token.jwt"
	printf '%s' "$oidc_token_value" > "$oidc_token_path"
	chmod 600 "$oidc_token_path"
	set_env_single PAYLOAD_OIDC_TOKEN_PATH "$oidc_token_path"
	set_env_single PAYLOAD_OIDC_PRESENT "true"
	else
	set_env_single PAYLOAD_OIDC_TOKEN_PATH ""
	set_env_single PAYLOAD_OIDC_PRESENT "false"
	fi

	echo "path=$payload_path" >> "$GITHUB_OUTPUT"
	echo "Payload size: $(wc -c < "$payload_path") bytes"
	echo "First 200 bytes:"
	head -c 200 "$payload_path"
	echo

	- name: Validate payload schema
	# Defense in depth — even with a valid DOCS_REPO_TOKEN, a holder of
	# that PAT could craft a payload with a malformed `sha`, a
	# gigantic `changed_paths` array, or a multi-megabyte `pr_body`.
	# We validate field shapes and apply hard caps BEFORE any
	# privileged action (artifact fetch, LLM call, git push). Caps
	# are declared here in one block so they're easy to tune.
	env:
	PAYLOAD_PATH: ${{ steps.payload_file.outputs.path }}
	MAX_PR_TITLE_BYTES: 1024
	MAX_PR_BODY_BYTES: 16384
	MAX_INTENT_BYTES: 4096
	MAX_RELEASE_NOTES_BYTES: 16384
	# code-change dispatches touch a handful of watched files; release
	# dispatches diff a whole tag-to-tag tree and can legitimately list
	# many more. Both stay bounded (each entry is also capped at
	# MAX_CHANGED_PATH_BYTES) so the payload array can't grow without
	# limit. The release cap matches the dispatcher's MAX_CHANGED_PATHS.
	MAX_CHANGED_PATHS: 200
	MAX_CHANGED_PATHS_RELEASE: 2000
	MAX_CHANGED_PATH_BYTES: 512
	# Inline diffs only — the dispatcher already enforces a 60000
	# byte ceiling on this side. Artifact-delivered diffs are capped
	# separately in the artifact-fetch step.
	MAX_INLINE_DIFF_BYTES: 65536
	STEP_NAME: "Validate payload schema"
	run: \|
	set -euo pipefail
	source "${GITHUB_WORKSPACE}/scripts/lib/workflow-fail.sh"

	kind=$(jq -r '.kind // ""' "$PAYLOAD_PATH")
	case "$kind" in
	code-change\|release\|manual-update) ;;
	*) workflow_fail "$STEP_NAME" "kind '${kind}' is not in the allowlist (code-change\|release\|manual-update)" ;;
	esac

	sha=$(jq -r '.sha // ""' "$PAYLOAD_PATH")
	if [[ -n "$sha" && ! "$sha" =~ ^[0-9a-f]{7,40}$ ]]; then
	workflow_fail "$STEP_NAME" "sha '${sha}' is not a 7-40 char lowercase hex string"
	fi

	# Release provenance is meaningful only with BOTH fields. Keep tags
	# deliberately narrow so they are safe in GitHub API paths and can
	# never inject a line into GITHUB_ENV.
	tag=$(jq -r '.tag // ""' "$PAYLOAD_PATH")
	previous_tag=$(jq -r '.previous_tag // ""' "$PAYLOAD_PATH")
	if [[ "$kind" == "release" ]]; then
	if [[ -z "$sha" \|\| ! "$sha" =~ ^[0-9a-f]{7,40}$ ]]; then
	workflow_fail "$STEP_NAME" "release payload requires a lowercase 7-40 character sha"
	fi
	if [[ ! "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
	workflow_fail "$STEP_NAME" "release payload requires a final tag in vX.Y.Z form"
	fi
	if [[ -n "$previous_tag" && ! "$previous_tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
	workflow_fail "$STEP_NAME" "previous_tag must be empty or a final vX.Y.Z tag"
	fi
	if ! jq -e '(.release_notes // "") \| type == "string"' "$PAYLOAD_PATH" >/dev/null; then
	workflow_fail "$STEP_NAME" "release_notes is not a string"
	fi
	fi

	pr_number=$(jq -r '.pr_number // ""' "$PAYLOAD_PATH")
	if [[ -n "$pr_number" && ! "$pr_number" =~ ^[0-9]+$ ]]; then
	workflow_fail "$STEP_NAME" "pr_number '${pr_number}' is not numeric"
	fi

	# changed_paths: when present, must be an array of strings, each
	# within size cap. Empty/absent is fine for release + manual-update.
	# The count cap is kind-aware: release diffs span the whole tree.
	changed_paths_cap="$MAX_CHANGED_PATHS"
	if [[ "$kind" == "release" ]]; then
	changed_paths_cap="$MAX_CHANGED_PATHS_RELEASE"
	fi
	if jq -e '.changed_paths != null' "$PAYLOAD_PATH" >/dev/null; then
	if ! jq -e '.changed_paths \| type == "array"' "$PAYLOAD_PATH" >/dev/null; then
	workflow_fail "$STEP_NAME" "changed_paths is not an array"
	fi
	count=$(jq '.changed_paths \| length' "$PAYLOAD_PATH")
	if (( count > changed_paths_cap )); then
	workflow_fail "$STEP_NAME" "changed_paths has $count entries (cap: $changed_paths_cap for kind '$kind')"
	fi
	bad=$(jq -r --argjson cap "$MAX_CHANGED_PATH_BYTES" '
	.changed_paths
	\| map(select(type != "string" or (length > $cap)))
	\| length
	' "$PAYLOAD_PATH")
	if (( bad > 0 )); then
	workflow_fail "$STEP_NAME" "$bad changed_paths entr(y/ies) are not strings or exceed $MAX_CHANGED_PATH_BYTES bytes"
	fi
	fi

	diff_bytes=$(jq -r '.diff // "" \| length' "$PAYLOAD_PATH")
	if (( diff_bytes > MAX_INLINE_DIFF_BYTES )); then
	workflow_fail "$STEP_NAME" "inline diff is $diff_bytes bytes (cap: $MAX_INLINE_DIFF_BYTES)"
	fi

	# Truncate large freeform strings in-place. Rejecting would take
	# the whole sync down for a cosmetic overrun; truncating fails
	# safe and emits a warning the reviewer can act on. PR_TITLE and
	# INTENT also flow through $GITHUB_ENV (set in the previous
	# step), so we refresh those when we shorten them. PR_BODY only
	# flows through the payload file (sync script reads it from
	# there), so no env refresh needed.
	truncate_field() {
	local field="$1"; local cap="$2"; local env_key="${3:-}"
	local current
	current=$(jq -r --arg f "$field" '.[$f] // ""' "$PAYLOAD_PATH")
	local len=${#current}
	if (( len > cap )); then
	echo "::warning title=Payload field truncated::${field} was ${len} bytes; truncated to ${cap}"
	local truncated="${current:0:$cap}"
	jq --arg f "$field" --arg v "$truncated" \
	'.[$f] = $v' "$PAYLOAD_PATH" > "$PAYLOAD_PATH.tmp"
	mv "$PAYLOAD_PATH.tmp" "$PAYLOAD_PATH"
	if [[ -n "$env_key" ]]; then
	{
	printf '%s<<EOF_PAYLOAD_VAL\n' "$env_key"
	printf '%s' "$truncated"
	printf '\nEOF_PAYLOAD_VAL\n'
	} >> "$GITHUB_ENV"
	fi
	fi
	}
	truncate_field pr_title "$MAX_PR_TITLE_BYTES" PAYLOAD_PR_TITLE
	truncate_field pr_body "$MAX_PR_BODY_BYTES"
	truncate_field intent "$MAX_INTENT_BYTES" PAYLOAD_INTENT
	if [[ "$kind" == "release" ]]; then
	truncate_field release_notes "$MAX_RELEASE_NOTES_BYTES"
	# Safe only after strict vX.Y.Z validation above.
	printf 'PAYLOAD_TAG=%s\n' "$tag" >> "$GITHUB_ENV"
	fi

	echo "::notice title=Payload schema validated::kind=${kind} sha=${sha:0:7} pr_number=${pr_number:-none} changed_paths=$(jq -r '.changed_paths // [] \| length' "$PAYLOAD_PATH") inline_diff_bytes=${diff_bytes}"

	- name: Validate source_repo against allowlist
	# The dispatcher's PAT (DOCS_REPO_TOKEN) authenticates which dispatcher
	# can call this receiver, but it does NOT bind the dispatcher to any
	# particular source_repo value — a holder of the PAT could spoof the
	# field. So we validate the claimed source_repo against an explicit
	# allowlist before using it to fetch artifacts or build PR URLs.
	#
	# Required repo variable: ALLOWED_SOURCE_REPOS, space-separated list
	# of "<owner>/<repo>" entries. No default — an unset or empty value
	# rejects every dispatch with a clear error.
	#
	# This is the COARSE check (is the claimed source repo in the
	# allowlist at all?). The FINE check that source_repo is the same
	# repo the dispatch credential is actually bound to lives in the
	# next step (Verify OIDC source-repo attestation).
	env:
	SOURCE_REPO: ${{ env.PAYLOAD_SOURCE_REPO }}
	ALLOWED: ${{ vars.ALLOWED_SOURCE_REPOS }}
	STEP_NAME: "Validate source_repo against allowlist"
	run: \|
	set -euo pipefail
	source "${GITHUB_WORKSPACE}/scripts/lib/workflow-fail.sh"
	if [[ -z "${ALLOWED:-}" ]]; then
	workflow_fail "$STEP_NAME" "ALLOWED_SOURCE_REPOS repo variable is not configured. Set it under Settings -> Secrets and variables -> Actions -> Variables to a space-separated list of '<owner>/<repo>' entries."
	fi
	if [[ -z "${SOURCE_REPO:-}" ]]; then
	workflow_fail "$STEP_NAME" "Payload is missing required 'source_repo' field — dispatcher is likely on an older payload shape."
	fi
	for allowed in $ALLOWED; do
	if [[ "$SOURCE_REPO" == "$allowed" ]]; then
	echo "source_repo '$SOURCE_REPO' is in the allowlist."
	echo "::notice title=Allowlist passed::source_repo=${SOURCE_REPO} sender=${SENDER_LOGIN:-unknown}"
	exit 0
	fi
	done
	workflow_fail "$STEP_NAME" "source_repo '${SOURCE_REPO}' is NOT in the allowlist '${ALLOWED}'. If this is a legitimate new source repo, add it to the ALLOWED_SOURCE_REPOS repo variable."

	- name: Verify OIDC source-repo attestation
	# Archon security finding closure: source_repo in client_payload is
	# attacker-controllable JSON. A GitHub-signed OIDC token with
	# payload.repository == source_repo is the only way to prove
	# which repo the dispatch actually came from, without trusting
	# the JSON.
	#
	# Phase 1 behavior (this file): verify-when-present, fail closed
	# on signature/claim mismatch, soft-warn when absent so existing
	# dispatchers continue to work during migration.
	#
	# Phase 2 (when REQUIRE_OIDC = "true" in repo vars): missing
	# token is a hard reject too. Flip the variable once every
	# source repo's dispatcher has been updated.
	#
	# Required scopes: none beyond GITHUB_TOKEN read — verification
	# only needs the public JWKS at token.actions.githubusercontent.com.
	env:
	PAYLOAD_PATH: ${{ steps.payload_file.outputs.path }}
	REQUIRE_OIDC: ${{ vars.REQUIRE_OIDC }}
	OIDC_REQUIRE_MAIN_WORKFLOW: ${{ vars.OIDC_REQUIRE_MAIN_WORKFLOW }}
	STEP_NAME: "Verify OIDC source-repo attestation"
	run: \|
	set -euo pipefail
	source "${GITHUB_WORKSPACE}/scripts/lib/workflow-fail.sh"

	# Phase 1 default is opt-in; Phase 2 will document flipping
	# vars.REQUIRE_OIDC = "true" as the breaking cutover.
	require_oidc="${REQUIRE_OIDC:-false}"

	if [[ "${PAYLOAD_OIDC_PRESENT:-false}" != "true" ]]; then
	if [[ "$require_oidc" == "true" ]]; then
	workflow_fail "$STEP_NAME" "OIDC token is missing from client_payload and vars.REQUIRE_OIDC='true'. The dispatcher must be updated to mint an OIDC token before dispatching."
	fi
	echo "::warning title=OIDC attestation missing::client_payload.oidc_token is empty. Phase 1 backward-compat: dispatch proceeds, but provenance is not cryptographically bound. Migrate the dispatcher (see README 'OIDC source-repo attestation') before flipping vars.REQUIRE_OIDC to 'true'."
	exit 0
	fi

	if [[ ! -s "${PAYLOAD_OIDC_TOKEN_PATH:-}" ]]; then
	workflow_fail "$STEP_NAME" "PAYLOAD_OIDC_PRESENT='true' but the token file at '${PAYLOAD_OIDC_TOKEN_PATH:-}' is missing or empty — internal materialize step regression."
	fi

	# The verify script reads OIDC_TOKEN from a file path via shell
	# substitution rather than process env so the JWT never appears
	# in any logged env dump.
	claims_path="$RUNNER_TEMP/oidc-claims.json"
	if ! OIDC_TOKEN="$(cat "${PAYLOAD_OIDC_TOKEN_PATH}")" \
	OIDC_EXPECTED_AUDIENCE="docs-sync:${GITHUB_REPOSITORY}" \
	OIDC_EXPECTED_REPOSITORY="${PAYLOAD_SOURCE_REPO}" \
	OIDC_REQUIRE_MAIN_WORKFLOW="${OIDC_REQUIRE_MAIN_WORKFLOW:-false}" \
	node "${GITHUB_WORKSPACE}/scripts/verify-oidc.mjs" > "$claims_path"; then
	workflow_fail "$STEP_NAME" "OIDC verification failed for source_repo='${PAYLOAD_SOURCE_REPO}'. See the preceding structured stderr line (verification_code) for the precise reason."
	fi

	# Cache claims for downstream steps + audit log. The file is
	# not sensitive (claims are public metadata once verified).
	attested_repo=$(jq -r '.repository // ""' "$claims_path")
	attested_workflow_ref=$(jq -r '.workflow_ref // ""' "$claims_path")
	attested_sha=$(jq -r '.sha // ""' "$claims_path")
	attested_actor=$(jq -r '.actor // ""' "$claims_path")
	echo "OIDC verified: repository=${attested_repo} workflow_ref=${attested_workflow_ref} sha=${attested_sha:0:7} actor=${attested_actor}"
	echo "::notice title=OIDC attestation verified::source_repo=${attested_repo} workflow_ref=${attested_workflow_ref} sender=${SENDER_LOGIN:-unknown}"

	- name: Enforce ALLOWED_SENDER_BINDINGS
	# Optional defense-in-depth: a space-separated map of
	# "<sender_login>=<owner>/<repo>" pairs. When set, the dispatch
	# is rejected unless github.event.sender.login is listed AND
	# maps to the claimed source_repo. Useful for deployments that
	# issue a distinct PAT (or App installation) per source repo.
	# No-op when unset — the OIDC step is the primary binding.
	env:
	BINDINGS: ${{ vars.ALLOWED_SENDER_BINDINGS }}
	STEP_NAME: "Enforce ALLOWED_SENDER_BINDINGS"
	run: \|
	set -euo pipefail
	source "${GITHUB_WORKSPACE}/scripts/lib/workflow-fail.sh"
	if [[ -z "${BINDINGS:-}" ]]; then
	echo "ALLOWED_SENDER_BINDINGS not set — skipping per-sender enforcement (OIDC step is the primary binding)."
	exit 0
	fi
	if [[ -z "${SENDER_LOGIN:-}" ]]; then
	workflow_fail "$STEP_NAME" "ALLOWED_SENDER_BINDINGS is set but github.event.sender.login is empty — cannot enforce binding."
	fi
	if [[ -z "${PAYLOAD_SOURCE_REPO:-}" ]]; then
	workflow_fail "$STEP_NAME" "ALLOWED_SENDER_BINDINGS is set but client_payload.source_repo is empty — cannot enforce binding."
	fi
	matched_repo=""
	for entry in $BINDINGS; do
	entry_login="${entry%%=*}"
	entry_repo="${entry#*=}"
	if [[ -z "$entry_login" \|\| -z "$entry_repo" \|\| "$entry_login" == "$entry" ]]; then
	workflow_fail "$STEP_NAME" "ALLOWED_SENDER_BINDINGS entry '${entry}' is malformed — expected '<sender_login>=<owner>/<repo>'."
	fi
	if [[ "$entry_login" == "$SENDER_LOGIN" ]]; then
	matched_repo="$entry_repo"
	break
	fi
	done
	if [[ -z "$matched_repo" ]]; then
	workflow_fail "$STEP_NAME" "Sender '${SENDER_LOGIN}' is not present in ALLOWED_SENDER_BINDINGS. If this sender is legitimate, add '${SENDER_LOGIN}=<owner>/<repo>' to the variable."
	fi
	if [[ "$matched_repo" != "$PAYLOAD_SOURCE_REPO" ]]; then
	workflow_fail "$STEP_NAME" "Sender '${SENDER_LOGIN}' is bound to '${matched_repo}' but client_payload.source_repo is '${PAYLOAD_SOURCE_REPO}'. Spoofing attempt or stale binding."
	fi
	echo "Sender binding satisfied: ${SENDER_LOGIN} -> ${matched_repo}"
	echo "::notice title=Sender binding verified::sender=${SENDER_LOGIN} source_repo=${matched_repo}"

	- name: Verify payload provenance against source_repo
	# Archon security finding: source_repo is allowlisted, but every other
	# client_payload field (sha, tag, pr_number, diff_artifact_run_id) is
	# attacker-controllable. A holder of DOCS_REPO_TOKEN — or a compromised
	# contributor on an allowlisted source repo — could forge those fields
	# to point at unmerged branches, malicious forks, or attacker-uploaded
	# artifacts. The allowlist authenticates the sender repo, not the
	# claimed content.
	#
	# For each non-empty provenance field we independently re-verify it
	# against the source repo via the GitHub API. ANY failed check rejects
	# the dispatch outright — we never fall back to the client_payload
	# value, per the Archon recommendation.
	#
	# The sha anchor depends on the dispatch kind:
	# * code-change / manual-update — anchor to the source repo's `main`
	# branch (sha must be identical to, or an ancestor of, main HEAD).
	# This is base/base's default branch, so a merged change is on it.
	# * release — anchor to the published release TAG instead. Release
	# commits are cut on releases/* branches and tagged; they are NOT
	# on main, so a main-anchored check would wrongly reject every
	# release. We require compare {tag}...{sha} == `identical`, which
	# proves (a) the tag actually exists on the source repo and (b) the
	# dispatched sha is exactly that tag's commit. This is an
	# equivalent-or-stronger binding than the main-ancestry check (an
	# exact ref+commit match rather than mere reachability), not a
	# downgrade — a forger without push access to the source repo
	# cannot make an arbitrary commit resolve to a real release tag.
	#
	# The artifact-run check stays anchored to `main`: this dispatcher is
	# invoked via workflow_run and therefore always executes from the
	# source repo's default branch (main), so its uploaded artifact run's
	# head_branch is main for both code-change and release dispatches.
	#
	# Required DOCS_REPO_TOKEN scopes on every ALLOWED_SOURCE_REPOS entry:
	# - Contents: read (compare endpoint)
	# - Pull requests: read (pulls endpoint)
	# - Actions: read (workflow-runs endpoint; already needed for artifact fetch)
	env:
	KIND: ${{ env.PAYLOAD_KIND }}
	SOURCE_REPO: ${{ env.PAYLOAD_SOURCE_REPO }}
	SHA: ${{ env.PAYLOAD_SHA }}
	TAG: ${{ env.PAYLOAD_TAG }}
	PR_NUMBER: ${{ env.PAYLOAD_PR_NUMBER }}
	ARTIFACT_RUN_ID: ${{ env.PAYLOAD_DIFF_ARTIFACT_RUN_ID }}
	SOURCE_TOKEN: ${{ secrets.DOCS_REPO_TOKEN }}
	STEP_NAME: "Verify payload provenance against source_repo"
	run: \|
	set -euo pipefail
	source "${GITHUB_WORKSPACE}/scripts/lib/workflow-fail.sh"

	if [[ -z "${SOURCE_TOKEN:-}" ]]; then
	workflow_fail "$STEP_NAME" "DOCS_REPO_TOKEN secret is not configured — required for cross-repo provenance verification"
	fi

	# Thin wrapper: writes body to $2, echoes status code on stdout.
	# Keeps the per-check blocks short and uniform.
	api_get() {
	local path="$1"; local out="$2"
	local code
	code=$(curl -sS -o "$out" -w '%{http_code}' \
	-H "Accept: application/vnd.github+json" \
	-H "Authorization: Bearer $SOURCE_TOKEN" \
	-H "X-GitHub-Api-Version: 2022-11-28" \
	"https://api.github.com${path}") \|\| code="000"
	echo "$code"
	}

	# 1) sha provenance — anchored to the release tag for release
	# dispatches, otherwise to main (see step header).
	if [[ -n "${SHA:-}" ]]; then
	cmp_path="$RUNNER_TEMP/provenance_compare.json"
	if [[ "$KIND" == "release" ]]; then
	if [[ -z "${TAG:-}" ]]; then
	workflow_fail "$STEP_NAME" "release payload is missing required 'tag' field — cannot anchor sha provenance"
	fi
	# GET /repos/{source_repo}/compare/{tag}...{sha}
	# Require status `identical`: sha must be exactly the commit
	# the release tag points to.
	code=$(api_get "/repos/${SOURCE_REPO}/compare/${TAG}...${SHA}" "$cmp_path")
	case "$code" in
	403\|404)
	echo "Response body:" >&2
	cat "$cmp_path" >&2 \|\| true
	workflow_fail "$STEP_NAME" "compare ${TAG}...${SHA} on ${SOURCE_REPO} returned HTTP ${code} — DOCS_REPO_TOKEN likely missing 'Contents: read' on ${SOURCE_REPO}, or the tag/sha does not exist"
	;;
	200) ;;
	*)
	cat "$cmp_path" >&2 \|\| true
	workflow_fail "$STEP_NAME" "compare ${TAG}...${SHA} on ${SOURCE_REPO} failed (HTTP ${code})"
	;;
	esac
	status=$(jq -r '.status // ""' "$cmp_path")
	if [[ "$status" != "identical" ]]; then
	workflow_fail "$STEP_NAME" "release sha ${SHA} does not match tag ${TAG} on ${SOURCE_REPO} (compare status='${status}', expected 'identical')"
	fi
	echo "release sha ${SHA:0:7} matches tag ${TAG} of ${SOURCE_REPO} (compare status=identical)"
	else
	# GET /repos/{source_repo}/compare/main...{sha}
	# Accept when status is `identical` (sha == main HEAD) or
	# `behind` (sha is an ancestor of main HEAD). `ahead` or
	# `diverged` means sha is not on main's history → reject.
	code=$(api_get "/repos/${SOURCE_REPO}/compare/main...${SHA}" "$cmp_path")
	case "$code" in
	403\|404)
	echo "Response body:" >&2
	cat "$cmp_path" >&2 \|\| true
	workflow_fail "$STEP_NAME" "compare main...${SHA} on ${SOURCE_REPO} returned HTTP ${code} — DOCS_REPO_TOKEN likely missing 'Contents: read' on ${SOURCE_REPO}, or sha does not exist"
	;;
	200) ;;
	*)
	cat "$cmp_path" >&2 \|\| true
	workflow_fail "$STEP_NAME" "compare main...${SHA} on ${SOURCE_REPO} failed (HTTP ${code})"
	;;
	esac
	status=$(jq -r '.status // ""' "$cmp_path")
	case "$status" in
	identical\|behind)
	echo "sha ${SHA:0:7} reachable from main of ${SOURCE_REPO} (compare status=${status})"
	;;
	*)
	workflow_fail "$STEP_NAME" "sha ${SHA} is not reachable from main of ${SOURCE_REPO} (compare status='${status}')"
	;;
	esac
	fi
	fi

	# 2) pr_number (if present) merged into main
	# GET /repos/{source_repo}/pulls/{pr_number}
	# Require merged === true AND base.ref === "main".
	if [[ -n "${PR_NUMBER:-}" ]]; then
	pr_path="$RUNNER_TEMP/provenance_pr.json"
	code=$(api_get "/repos/${SOURCE_REPO}/pulls/${PR_NUMBER}" "$pr_path")
	case "$code" in
	403\|404)
	echo "Response body:" >&2
	cat "$pr_path" >&2 \|\| true
	workflow_fail "$STEP_NAME" "pulls/${PR_NUMBER} on ${SOURCE_REPO} returned HTTP ${code} — DOCS_REPO_TOKEN likely missing 'Pull requests: read' on ${SOURCE_REPO}, or PR does not exist"
	;;
	200) ;;
	*)
	cat "$pr_path" >&2 \|\| true
	workflow_fail "$STEP_NAME" "pulls/${PR_NUMBER} on ${SOURCE_REPO} failed (HTTP ${code})"
	;;
	esac
	merged=$(jq -r '.merged // false' "$pr_path")
	base_ref=$(jq -r '.base.ref // ""' "$pr_path")
	if [[ "$merged" != "true" ]]; then
	workflow_fail "$STEP_NAME" "pr #${PR_NUMBER} on ${SOURCE_REPO} is not merged"
	fi
	if [[ "$base_ref" != "main" ]]; then
	workflow_fail "$STEP_NAME" "pr #${PR_NUMBER} on ${SOURCE_REPO} base.ref is '${base_ref}', not 'main'"
	fi
	echo "pr #${PR_NUMBER} on ${SOURCE_REPO} is merged into main"
	fi

	# 3) artifact run_id belongs to a workflow run on main
	# GET /repos/{source_repo}/actions/runs/{run_id}
	# Require head_branch === "main".
	if [[ -n "${ARTIFACT_RUN_ID:-}" ]]; then
	run_path="$RUNNER_TEMP/provenance_run.json"
	code=$(api_get "/repos/${SOURCE_REPO}/actions/runs/${ARTIFACT_RUN_ID}" "$run_path")
	case "$code" in
	403\|404)
	echo "Response body:" >&2
	cat "$run_path" >&2 \|\| true
	workflow_fail "$STEP_NAME" "actions/runs/${ARTIFACT_RUN_ID} on ${SOURCE_REPO} returned HTTP ${code} — DOCS_REPO_TOKEN likely missing 'Actions: read' on ${SOURCE_REPO}, or run does not exist"
	;;
	200) ;;
	*)
	cat "$run_path" >&2 \|\| true
	workflow_fail "$STEP_NAME" "actions/runs/${ARTIFACT_RUN_ID} on ${SOURCE_REPO} failed (HTTP ${code})"
	;;
	esac
	head_branch=$(jq -r '.head_branch // ""' "$run_path")
	if [[ "$head_branch" != "main" ]]; then
	workflow_fail "$STEP_NAME" "artifact run ${ARTIFACT_RUN_ID} on ${SOURCE_REPO} head_branch is '${head_branch}', not 'main'"
	fi
	echo "artifact run ${ARTIFACT_RUN_ID} on ${SOURCE_REPO} was on main"
	fi

	echo "::notice title=Payload provenance verified::kind=${KIND:-code-change} sha=${SHA:0:7} tag=${TAG:-none} pr_number=${PR_NUMBER:-none} artifact_run_id=${ARTIFACT_RUN_ID:-none} (all checks passed against ${SOURCE_REPO})"

	- name: Derive trusted release routing inputs
	# client_payload.changed_paths is attacker-controlled JSON. For a
	# release, replace it with the paths returned by GitHub for the
	# independently verified tag range before it can influence LLM page
	# discovery. previous_tag is also recomputed rather than trusted.
	if: env.PAYLOAD_KIND == 'release'
	env:
	SOURCE_REPO: ${{ env.PAYLOAD_SOURCE_REPO }}
	SHA: ${{ env.PAYLOAD_SHA }}
	TAG: ${{ env.PAYLOAD_TAG }}
	SOURCE_TOKEN: ${{ secrets.DOCS_REPO_TOKEN }}
	PAYLOAD_PATH: ${{ steps.payload_file.outputs.path }}
	STEP_NAME: "Derive trusted release routing inputs"
	run: \|
	set -euo pipefail
	source "${GITHUB_WORKSPACE}/scripts/lib/workflow-fail.sh"

	api_get() {
	local path="$1" out="$2" code
	code=$(curl -sS -o "$out" -w '%{http_code}' \
	-H "Accept: application/vnd.github+json" \
	-H "Authorization: Bearer $SOURCE_TOKEN" \
	-H "X-GitHub-Api-Version: 2022-11-28" \
	"https://api.github.com${path}") \|\| code="000"
	echo "$code"
	}

	refs="$RUNNER_TEMP/release-tag-refs.json"
	code=$(api_get "/repos/${SOURCE_REPO}/git/matching-refs/tags/" "$refs")
	if [[ "$code" != "200" ]]; then
	workflow_fail "$STEP_NAME" "listing release tags on ${SOURCE_REPO} failed (HTTP ${code})"
	fi
	mapfile -t finals < <(
	jq -r '.[].ref \| select(test("^refs/tags/v[0-9]+\\.[0-9]+\\.[0-9]+$")) \| sub("^refs/tags/"; "")' "$refs" \
	\| sort -Vr
	)
	previous=""
	found=false
	for candidate in "${finals[@]}"; do
	if [[ "$found" == true ]]; then previous="$candidate"; break; fi
	if [[ "$candidate" == "$TAG" ]]; then found=true; fi
	done
	if [[ "$found" != true ]]; then
	workflow_fail "$STEP_NAME" "verified tag ${TAG} is not a final release ref on ${SOURCE_REPO}"
	fi

	if [[ -n "$previous" ]]; then
	base="$previous"
	else
	commit="$RUNNER_TEMP/release-commit.json"
	code=$(api_get "/repos/${SOURCE_REPO}/commits/${SHA}" "$commit")
	if [[ "$code" != "200" ]]; then
	workflow_fail "$STEP_NAME" "reading tagged commit ${SHA} failed (HTTP ${code})"
	fi
	base=$(jq -r '.parents[0].sha // ""' "$commit")
	if [[ ! "$base" =~ ^[0-9a-f]{40}$ ]]; then
	workflow_fail "$STEP_NAME" "tagged commit ${SHA} has no first parent for initial-release comparison"
	fi
	fi

	comparison="$RUNNER_TEMP/release-compare.json"
	code=$(api_get "/repos/${SOURCE_REPO}/compare/${base}...${TAG}" "$comparison")
	if [[ "$code" != "200" ]]; then
	workflow_fail "$STEP_NAME" "comparing trusted release range ${base}...${TAG} failed (HTTP ${code})"
	fi
	jq -e '(.files // []) \| all(.[]; (.filename \| type == "string") and (length <= 512))' "$comparison" >/dev/null \
	\|\| workflow_fail "$STEP_NAME" "GitHub comparison returned malformed changed-file metadata"
	jq '[.files[]?.filename] \| .[0:2000]' "$comparison" > "$RUNNER_TEMP/trusted-changed-paths.json"
	jq --arg previous_tag "$previous" --slurpfile paths "$RUNNER_TEMP/trusted-changed-paths.json" \
	'.previous_tag = $previous_tag \| .changed_paths = $paths[0]' "$PAYLOAD_PATH" > "$PAYLOAD_PATH.tmp"
	mv "$PAYLOAD_PATH.tmp" "$PAYLOAD_PATH"
	echo "::notice title=Trusted release routing inputs derived::tag=${TAG} previous=${previous:-<initial>} changed_paths=$(jq length "$RUNNER_TEMP/trusted-changed-paths.json")"

	- name: Fetch diff artifact from source repo (if payload references one)
	# Dispatcher uploads oversized diffs as a workflow artifact on the
	# source repo (env.PAYLOAD_SOURCE_REPO, validated against the
	# allowlist in the previous step) and the payload only carries
	# `diff_artifact_run_id` + `diff_artifact_name`. We resolve those
	# here, download the zip via the GitHub Actions API, unpack it, and
	# splice the diff content back into the payload file so the script
	# sees it like any inline diff.
	#
	# Requires the DOCS_REPO_TOKEN secret on this repo to have
	# `actions:read` on every allowlisted source repo. Inline-diff
	# dispatches skip this step entirely (both env vars are empty).
	env:
	ARTIFACT_RUN_ID: ${{ env.PAYLOAD_DIFF_ARTIFACT_RUN_ID }}
	ARTIFACT_NAME: ${{ env.PAYLOAD_DIFF_ARTIFACT_NAME }}
	SOURCE_REPO: ${{ env.PAYLOAD_SOURCE_REPO }}
	SOURCE_TOKEN: ${{ secrets.DOCS_REPO_TOKEN }}
	PAYLOAD_PATH: ${{ steps.payload_file.outputs.path }}
	# Hard caps — tune here, document in README. Sized for release
	# dispatches: the dispatcher caps the raw diff at 12 MiB
	# (MAX_RELEASE_DIFF_BYTES), which zips far smaller, so MAX_DIFF_BYTES
	# matches that ceiling and the zip cap leaves headroom. Both stay
	# bounded so a tampered artifact can't exhaust the runner.
	MAX_ARTIFACT_ZIP_BYTES: 16777216 # 16 MiB zip on the wire
	MAX_DIFF_BYTES: 12582912 # 12 MiB unpacked diff (matches dispatcher cap)
	STEP_NAME: "Fetch diff artifact from source repo"
	run: \|
	set -euo pipefail
	source "${GITHUB_WORKSPACE}/scripts/lib/workflow-fail.sh"

	# Both-or-none. An asymmetric pair is malformed (or tampered) —
	# fail closed rather than silently fall back to "no artifact".
	if [[ -z "${ARTIFACT_RUN_ID:-}" && -z "${ARTIFACT_NAME:-}" ]]; then
	echo "No diff artifact reference — diff is inline (or empty)."
	exit 0
	fi
	if [[ -z "${ARTIFACT_RUN_ID:-}" \|\| -z "${ARTIFACT_NAME:-}" ]]; then
	workflow_fail "$STEP_NAME" "diff_artifact_run_id and diff_artifact_name must be both set or both empty"
	fi

	# Validate artifact-reference shape before we let either value
	# flow into a URL or a filename. run_id is a uint64; name is
	# the exact pattern the dispatcher uses (sync-diff-<run_id>).
	if [[ ! "$ARTIFACT_RUN_ID" =~ ^[0-9]+$ ]]; then
	workflow_fail "$STEP_NAME" "diff_artifact_run_id '$ARTIFACT_RUN_ID' is not numeric"
	fi
	if [[ ! "$ARTIFACT_NAME" =~ ^sync-diff-[0-9]+$ ]]; then
	workflow_fail "$STEP_NAME" "diff_artifact_name '$ARTIFACT_NAME' does not match sync-diff-<run_id>"
	fi

	if [[ -z "${SOURCE_TOKEN:-}" ]]; then
	workflow_fail "$STEP_NAME" "DOCS_REPO_TOKEN secret is not configured but the dispatch references a diff artifact. Add a PAT with 'actions:read' on ${SOURCE_REPO} as the DOCS_REPO_TOKEN secret."
	fi

	echo "Fetching diff artifact '${ARTIFACT_NAME}' from ${SOURCE_REPO} run ${ARTIFACT_RUN_ID}"

	# 1. List artifacts and pick ours by EXACT name. Require
	# exactly one match — multiple matches means the dispatcher
	# uploaded a name collision and we shouldn't guess.
	listing="$RUNNER_TEMP/artifacts.json"
	status=$(curl -sS -o "$listing" -w '%{http_code}' \
	-H "Authorization: Bearer $SOURCE_TOKEN" \
	-H "Accept: application/vnd.github+json" \
	-H "X-GitHub-Api-Version: 2022-11-28" \
	"https://api.github.com/repos/${SOURCE_REPO}/actions/runs/${ARTIFACT_RUN_ID}/artifacts?per_page=100")
	if [[ "$status" != "200" ]]; then
	cat "$listing" >&2 \|\| true
	workflow_fail "$STEP_NAME" "Listing artifacts failed (HTTP ${status})"
	fi
	matches=$(jq --arg name "$ARTIFACT_NAME" \
	'[.artifacts[] \| select(.name == $name)] \| length' "$listing")
	if [[ "$matches" -ne 1 ]]; then
	echo "Available artifacts:" >&2
	jq -r '.artifacts[].name' "$listing" >&2 \|\| true
	workflow_fail "$STEP_NAME" "expected exactly 1 artifact named '$ARTIFACT_NAME' on run ${ARTIFACT_RUN_ID}, found $matches"
	fi
	archive_url=$(jq -r --arg name "$ARTIFACT_NAME" \
	'.artifacts[] \| select(.name == $name) \| .archive_download_url' "$listing")
	declared_size=$(jq -r --arg name "$ARTIFACT_NAME" \
	'.artifacts[] \| select(.name == $name) \| .size_in_bytes' "$listing")
	if [[ -z "$declared_size" \|\| "$declared_size" == "null" ]]; then
	workflow_fail "$STEP_NAME" "artifact listing did not include size_in_bytes"
	fi
	if (( declared_size > MAX_ARTIFACT_ZIP_BYTES )); then
	workflow_fail "$STEP_NAME" "artifact declared size $declared_size exceeds cap $MAX_ARTIFACT_ZIP_BYTES"
	fi

	# 2. Download the zip.
	# --fail-with-body → non-zero exit on any 4xx/5xx
	# --max-filesize → abort mid-stream if the server lies
	# about size and tries to feed us more
	# -L → follow the archive endpoint's 302 to
	# the actual blob
	zip_path="$RUNNER_TEMP/diff-artifact.zip"
	if ! curl -sSL --fail-with-body \
	--max-filesize "$MAX_ARTIFACT_ZIP_BYTES" \
	-o "$zip_path" \
	-H "Authorization: Bearer $SOURCE_TOKEN" \
	-H "Accept: application/vnd.github+json" \
	-H "X-GitHub-Api-Version: 2022-11-28" \
	"$archive_url"; then
	workflow_fail "$STEP_NAME" "artifact download failed (curl non-zero — see step log for HTTP body)"
	fi
	actual_size=$(wc -c < "$zip_path" \| tr -d ' ')
	if (( actual_size > MAX_ARTIFACT_ZIP_BYTES )); then
	workflow_fail "$STEP_NAME" "downloaded zip is $actual_size bytes (cap: $MAX_ARTIFACT_ZIP_BYTES)"
	fi

	# 3. Unzip into a FRESH directory (rm -rf in case of retry on
	# the same runner) and enforce zip-slip protection: every
	# extracted file's resolved path must stay inside the
	# unpack dir. realpath + prefix compare with a trailing
	# '/' on the boundary avoids the
	# /tmp/diff-unpack-evil/ -> /tmp/diff-unpack/ false-pass.
	unpack_dir="$RUNNER_TEMP/diff-unpack"
	rm -rf "$unpack_dir"
	mkdir -p "$unpack_dir"
	unzip -q "$zip_path" -d "$unpack_dir"
	unpack_abs="$(cd "$unpack_dir" && pwd -P)"
	while IFS= read -r -d '' f; do
	resolved="$(realpath "$f")"
	case "$resolved" in
	"$unpack_abs"/*) ;;
	*) workflow_fail "$STEP_NAME" "zip-slip detected: '$f' resolves to '$resolved' which escapes '$unpack_abs'" ;;
	esac
	done < <(find "$unpack_dir" -mindepth 1 -print0)

	# 4. Require EXACTLY one *.diff file. The dispatcher uploads
	# one *.diff file and nothing else; anything else here is
	# either a misconfigured dispatcher or a tampered artifact.
	mapfile -d '' diff_candidates < <(find "$unpack_dir" -type f -name '*.diff' -print0)
	if (( ${#diff_candidates[@]} != 1 )); then
	echo "Unpack contents:" >&2
	find "$unpack_dir" -type f >&2 \|\| true
	workflow_fail "$STEP_NAME" "expected exactly 1 *.diff file in artifact, found ${#diff_candidates[@]}"
	fi
	diff_path="${diff_candidates[0]}"
	diff_size=$(wc -c < "$diff_path" \| tr -d ' ')
	if (( diff_size > MAX_DIFF_BYTES )); then
	workflow_fail "$STEP_NAME" "unpacked diff is $diff_size bytes (cap: $MAX_DIFF_BYTES)"
	fi
	echo "Downloaded diff: $diff_size bytes at $diff_path"

	# 5. Splice the diff back into the payload JSON in-place. The
	# sync-from-base script reads payload.diff as a string — once
	# we inject the content here, the script can't tell the
	# difference between an inline and an artifact-delivered diff.
	jq --rawfile diff "$diff_path" '.diff = $diff' "$PAYLOAD_PATH" > "$PAYLOAD_PATH.new"
	mv "$PAYLOAD_PATH.new" "$PAYLOAD_PATH"
	echo "Diff injected into payload. New payload size: $(wc -c < "$PAYLOAD_PATH") bytes."
	echo "::notice title=Artifact accepted::${ARTIFACT_NAME} from ${SOURCE_REPO} run ${ARTIFACT_RUN_ID} (zip=${actual_size}B diff=${diff_size}B)"

	- name: Run sync-from-base-std
	id: sync
	env:
	LLM_GATEWAY_API_KEY: ${{ secrets.LLM_GATEWAY_API_KEY }}
	PAYLOAD_PATH: ${{ steps.payload_file.outputs.path }}
	CODE_CHANGE_PAGE_CONCURRENCY: ${{ vars.CODE_CHANGE_PAGE_CONCURRENCY }}
	RELEASE_PAGE_CONCURRENCY: ${{ vars.RELEASE_PAGE_CONCURRENCY }}
	CLAUDE_MODEL: ${{ vars.CLAUDE_MODEL }}
	CLAUDE_MAX_TOKENS: ${{ vars.CLAUDE_MAX_TOKENS }}
	run: \|
	node scripts/sync-from-base-std/index.mjs --payload "$PAYLOAD_PATH"

	- name: Upload sync benchmark log
	# `if: always()` so we still capture the partial bench file even when
	# sync-from-base failed (e.g. on a non-retryable error mid-batch).
	if: always() && hashFiles('.sync-bench/*.jsonl') != ''
	uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
	with:
	name: sync-bench-${{ github.run_id }}
	path: .sync-bench/*.jsonl
	if-no-files-found: ignore
	retention-days: 14
	# The bench dir starts with a dot. upload-artifact filters hidden
	# files by default, so without this the artifact silently uploads
	# zero files (the `if:` above sees the file via hashFiles, but the
	# action's own glob excludes it).
	include-hidden-files: true

	- name: Commit branch
	id: commit
	env:
	BRANCH: ${{ steps.sync.outputs.branch }}
	TOUCHED_PATHS: ${{ steps.sync.outputs.touched_paths }}
	TOUCHED_COUNT: ${{ steps.sync.outputs.touched_count }}
	# Use the env vars populated by Materialize dispatch payload — they
	# work for both repository_dispatch (where client_payload is set)
	# and workflow_dispatch (where it isn't).
	SHA: ${{ env.PAYLOAD_SHA }}
	TAG: ${{ env.PAYLOAD_TAG }}
	KIND: ${{ env.PAYLOAD_KIND }}
	run: \|
	set -euo pipefail
	if [[ -z "${BRANCH:-}" ]] \|\| [[ "${TOUCHED_COUNT:-0}" == "0" ]]; then
	echo "no_changes=true" >> "$GITHUB_OUTPUT"
	echo "No pages touched by sync; skipping PR."
	# Surface this as a banner too — otherwise a run that legitimately
	# "did nothing" (e.g. Claude returned every page unchanged) produces
	# zero annotations and the summary page looks empty.
	echo "::notice title=No changes::Pages already match the requested intent — nothing to commit"
	exit 0
	fi

	git config user.name "github-actions[bot]"
	git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

	git checkout -B "$BRANCH"
	# Structural guard. The route-table is the routing decision;
	# this is the last-mile check that fails closed if the script
	# (or a future LLM regression) ever emits a path outside the
	# docs tree. No denylist needed — anything not matching the
	# allowlist regex is rejected.
	#
	# Allowed: docs/<anything>/<file>.{md,mdx,txt}
	# Rejected: absolute paths, embedded newlines, '..' traversal,
	# anything outside docs/, any non-doc extension.
	allow_re='^docs/[A-Za-z0-9._/-]+\.(md\|mdx\|txt)$'
	for p in $TOUCHED_PATHS; do
	case "$p" in
	/\|..\|$'\n'*)
	echo "::error title=Touched path rejected::'$p' contains an unsafe component (absolute path, '..' traversal, or newline)" >&2
	exit 1
	;;
	esac
	if [[ ! "$p" =~ $allow_re ]]; then
	echo "::error title=Touched path rejected::'$p' is outside the docs allowlist (${allow_re})" >&2
	exit 1
	fi
	git add -- "$p"
	done

	if git diff --staged --quiet; then
	echo "no_changes=true" >> "$GITHUB_OUTPUT"
	echo "Staged diff is empty — script returned paths but git sees no change."
	echo "::notice title=No changes::Script staged paths but git sees no diff"
	exit 0
	fi

	short_sha="${SHA:0:7}"
	case "$KIND" in
	release)
	commit_msg="docs: sync ${TAG:-release} from base-std"
	;;
	manual-update)
	commit_msg="docs: manual sync from maintainer"
	;;
	*)
	commit_msg="docs: sync from base-std@${short_sha:-unknown}"
	;;
	esac
	git commit -m "$commit_msg"
	git push -f origin "$BRANCH"
	echo "no_changes=false" >> "$GITHUB_OUTPUT"
	# Annotation surfaces in the run summary — same primitive Mintlify
	# uses (core.notice). Keep it terse, the next step's notice covers
	# the PR URL.
	echo "::notice title=Pages synced::${TOUCHED_COUNT} page(s) committed to ${BRANCH}"

	- name: Open or update PR via REST
	if: steps.commit.outputs.no_changes != 'true'
	env:
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	REPO: ${{ github.repository }}
	# Server-attested target branch. base/docs currently uses `master`;
	# deriving it avoids another hardcoded main/master mismatch.
	DOCS_BASE_BRANCH: ${{ github.event.repository.default_branch }}
	BRANCH: ${{ steps.sync.outputs.branch }}
	TOUCHED_PATHS: ${{ steps.sync.outputs.touched_paths }}
	REJECTED_PAGES: ${{ steps.sync.outputs.rejected_pages }}
	REJECTED_COUNT: ${{ steps.sync.outputs.rejected_count }}
	PROVENANCE_MD_PATH: ${{ steps.sync.outputs.provenance_md_path }}
	REVIEW_MD_PATH: ${{ steps.sync.outputs.review_md_path }}
	# All payload fields come from $PAYLOAD_* env vars set by Materialize
	# dispatch payload — works for both repository_dispatch and
	# workflow_dispatch trigger types.
	KIND: ${{ env.PAYLOAD_KIND }}
	SOURCE_REPO: ${{ env.PAYLOAD_SOURCE_REPO }}
	SHA: ${{ env.PAYLOAD_SHA }}
	TAG: ${{ env.PAYLOAD_TAG }}
	PR_NUMBER: ${{ env.PAYLOAD_PR_NUMBER }}
	PR_TITLE: ${{ env.PAYLOAD_PR_TITLE }}
	INTENT: ${{ env.PAYLOAD_INTENT }}
	SOURCE_REFS: ${{ env.PAYLOAD_SOURCE_REFS }}
	run: \|
	set -euo pipefail

	short_sha="${SHA:0:7}"
	case "$KIND" in
	release)
	title="docs: sync ${TAG:-release} from base-std"
	;;
	manual-update)
	# Use the first 80 chars of the intent as the title hint.
	intent_preview="${INTENT:0:80}"
	title="docs: ${intent_preview:-manual sync from maintainer}"
	;;
	*)
	if [[ -n "$PR_TITLE" ]]; then
	# Source PRs often already start with 'docs(...)' or 'docs:'.
	# Prepending 'docs:' unconditionally would produce a
	# a duplicated 'docs: docs(...): …' prefix. Strip the prefix
	# off the upstream title first so we always end up with exactly one.
	clean_pr_title="${PR_TITLE#docs: }"
	clean_pr_title="${clean_pr_title#docs$*$: }"
	title="docs: ${clean_pr_title} (base-std@${short_sha})"
	else
	title="docs: sync from base-std@${short_sha}"
	fi
	;;
	esac

	body_file="$RUNNER_TEMP/pr_body.md"
	{
	if [[ "$KIND" == "manual-update" ]]; then
	echo "Maintainer-curated update."
	echo
	echo "Intent: ${INTENT}"
	if [[ -n "${SOURCE_REFS:-}" ]]; then
	echo
	echo "Source references:"
	# SOURCE_REFS is space-separated; render as a bullet list.
	for r in ${SOURCE_REFS}; do
	echo "- ${r}"
	done
	fi
	else
	# Source PR comes first — reviewers want to click straight to
	# the upstream PR (with full source diff + discussion) before
	# looking at anything else. Bold + link + title where available.
	if [[ -n "${PR_NUMBER:-}" ]]; then
	if [[ -n "${PR_TITLE:-}" ]]; then
	echo "> Source PR: [${SOURCE_REPO}#${PR_NUMBER}](https://github.com/${SOURCE_REPO}/pull/${PR_NUMBER}) — _${PR_TITLE}_"
	else
	echo "> Source PR: [${SOURCE_REPO}#${PR_NUMBER}](https://github.com/${SOURCE_REPO}/pull/${PR_NUMBER})"
	fi
	echo ">"
	if [[ -n "${SHA:-}" ]]; then
	echo "> Merge commit: [\`${SHA:0:7}\`](https://github.com/${SOURCE_REPO}/commit/${SHA})"
	fi
	echo
	echo "Auto-generated from the source PR above."
	else
	echo "Auto-generated from \`${SOURCE_REPO}\`."
	if [[ -n "${SHA:-}" ]]; then
	echo
	echo "Commit: [\`${SHA:0:7}\`](https://github.com/${SOURCE_REPO}/commit/${SHA})"
	fi
	fi
	if [[ -n "${TAG:-}" ]]; then
	echo
	echo "Tag: \`${TAG}\`"
	fi
	fi

	# Reviewer checklist + newly-introduced external URLs. Placed
	# ahead of the file-touched / provenance sections so the
	# action-required items are the first thing a reviewer reads
	# after the source-PR link. Sync script writes the file at
	# $REVIEW_MD_PATH; we splice it in verbatim.
	if [[ -n "${REVIEW_MD_PATH:-}" ]] && [[ -f "${REVIEW_MD_PATH}" ]]; then
	cat "${REVIEW_MD_PATH}"
	fi

	echo
	echo "## Files touched"
	for p in ${TOUCHED_PATHS:-}; do
	echo "- \`${p}\`"
	done

	# Surface pages that Claude tried to write but the validator
	# rejected. Reviewer should expect those pages to be missing from
	# the diff and act accordingly (manual edit, retry, or accept the
	# gap).
	if [[ -n "${REJECTED_PAGES:-}" ]]; then
	echo
	echo "## Skipped pages (validator rejected the model output)"
	# REJECTED_PAGES is tab-separated tuples of "path\|reason".
	# Split on TAB, then on the first \| per tuple.
	IFS=$'\t' read -ra tuples <<< "$REJECTED_PAGES"
	for tup in "${tuples[@]}"; do
	page="${tup%%\|*}"
	reason="${tup#*\|}"
	echo "- \`${page}\` — ${reason}"
	done
	fi

	# Splice in the source-provenance markdown table the script wrote.
	# Lets a reviewer click straight from each doc page to the source
	# file(s) in base that drove its edit.
	if [[ -n "${PROVENANCE_MD_PATH:-}" ]] && [[ -f "${PROVENANCE_MD_PATH}" ]]; then
	cat "${PROVENANCE_MD_PATH}"
	fi

	echo
	echo "_Opened by \`Apply Base Std Update\` workflow._"
	} > "$body_file"

	owner="${REPO%%/*}"
	existing=$(curl -sS \
	-H "Accept: application/vnd.github+json" \
	-H "Authorization: Bearer $GITHUB_TOKEN" \
	-H "X-GitHub-Api-Version: 2022-11-28" \
	"https://api.github.com/repos/${REPO}/pulls?state=open&head=${owner}:${BRANCH}" \
	\| jq -r '.[0].number // ""')

	payload_file="$RUNNER_TEMP/pr.json"
	if [[ -n "$existing" ]]; then
	echo "Updating existing PR #$existing"
	jq -n \
	--arg title "$title" \
	--rawfile body "$body_file" \
	'{title: $title, body: $body}' > "$payload_file"

	status=$(curl -sS -o "$RUNNER_TEMP/resp.json" -w "%{http_code}" \
	-X PATCH \
	-H "Accept: application/vnd.github+json" \
	-H "Authorization: Bearer $GITHUB_TOKEN" \
	-H "X-GitHub-Api-Version: 2022-11-28" \
	"https://api.github.com/repos/${REPO}/pulls/${existing}" \
	--data-binary @"$payload_file")
	expected="200"
	else
	echo "Creating PR for $BRANCH"
	jq -n \
	--arg title "$title" \
	--arg head "$BRANCH" \
	--arg base "$DOCS_BASE_BRANCH" \
	--rawfile body "$body_file" \
	'{title: $title, head: $head, base: $base, body: $body, maintainer_can_modify: true}' > "$payload_file"

	status=$(curl -sS -o "$RUNNER_TEMP/resp.json" -w "%{http_code}" \
	-X POST \
	-H "Accept: application/vnd.github+json" \
	-H "Authorization: Bearer $GITHUB_TOKEN" \
	-H "X-GitHub-Api-Version: 2022-11-28" \
	"https://api.github.com/repos/${REPO}/pulls" \
	--data-binary @"$payload_file")
	expected="201"
	fi

	if [[ "$status" != "$expected" ]]; then
	echo "PR API call failed: expected $expected, got $status" >&2
	cat "$RUNNER_TEMP/resp.json" >&2 \|\| true
	exit 1
	fi

	pr_url=$(jq -r '.html_url // empty' "$RUNNER_TEMP/resp.json")
	# `::notice::` is GitHub Actions' annotation primitive — surfaces a
	# green banner in the run summary + the Annotations panel, vs
	# being buried in the step log. Same thing Mintlify's example
	# workflow uses via core.notice(). Pure visibility, no behavior.
	if [[ -n "${pr_url:-}" ]]; then
	echo "::notice title=Docs PR opened::${pr_url}"
	else
	echo "::warning title=Docs PR step::Step succeeded but no PR URL was returned"
	fi
	echo "PR: ${pr_url:-(no url returned)}"

Navigation Menu

Uh oh!

base-code-changed #4

Workflow file

base-code-changed #4

Uh oh!

Workflow file for this run