ARG ELIXIR_VERSION=1.20.3

ARG OTP_VERSION=29.0.5

ARG DEBIAN_VERSION=trixie-20260803-slim

ARG BUILDER_IMAGE="docker.io/hexpm/elixir:${ELIXIR_VERSION}-erlang-${OTP_VERSION}-debian-${DEBIAN_VERSION}"

ARG RUNNER_IMAGE="docker.io/debian:${DEBIAN_VERSION}"

ARG DEBIAN_SNAPSHOT=20260803T000000Z

ARG HEX_VERSION=2.5.1

ARG REBAR3_VERSION=3.25.1

ARG REBAR3_SHA512=69073f6ad163f74971545015238614c327893960c1b3f26df5377df135c773a0716b48b65c2a48cef878f185dd92805abc69894adfa3fd27a90c62a64ba371e2

ARG TAILWIND_VERSION=4.3.0

ARG TAILWIND_SHA256=73f0e5459054e5cfaa8ab6f3b940f3fbe0f13cc7fd83bc24e7c655033c203400

ARG ESBUILD_VERSION=0.25.4

ARG ESBUILD_SHA256=93433b456cac3a454ee27403d3de9adce88d83e5439ba37e1471af54730c9ca7

ARG BUILDER_IMAGE="docker.io/hexpm/elixir:${ELIXIR_VERSION}-erlang-${OTP_VERSION}-debian-${DEBIAN_VERSION}@sha256:ae38be7cb19bffa78adedb04732d9e6ba83a507b4cfb06983cbe711edb49da54"

ARG RUNNER_IMAGE="docker.io/debian:${DEBIAN_VERSION}@sha256:3a39a0592364683e6bab97937b72cad5a8fa6dcbbee90edb3bb48c7f8e94f258"

FROM ${BUILDER_IMAGE} AS builder

ARG OPENAGENTS_BUILD_REVISION="image"

ARG SOURCE_DATE_EPOCH=0

ARG DEBIAN_SNAPSHOT

ARG HEX_VERSION

ARG REBAR3_VERSION

ARG REBAR3_SHA512

ARG TAILWIND_VERSION

ARG TAILWIND_SHA256

ARG ESBUILD_VERSION

ARG ESBUILD_SHA256

ENV OPENAGENTS_BUILD_REVISION=${OPENAGENTS_BUILD_REVISION}

ENV SOURCE_DATE_EPOCH=${SOURCE_DATE_EPOCH}

# install build dependencies

RUN apt-get update \

RUN sed -i \

      "s|URIs: http://deb.debian.org/debian$|URIs: http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|" \

      /etc/apt/sources.list.d/debian.sources \

  && sed -i \

      "s|URIs: http://deb.debian.org/debian-security$|URIs: http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|" \

      /etc/apt/sources.list.d/debian.sources \

  && printf 'Acquire::Check-Valid-Until "false";\n' > /etc/apt/apt.conf.d/99snapshot \

  && apt-get update \

  && apt-get install -y --no-install-recommends build-essential git \

  && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# install hex + rebar

RUN mix local.hex --force \

  && mix local.rebar --force

RUN mix local.hex "${HEX_VERSION}" --force \

  && mix local.rebar rebar3 \

      "https://github.com/erlang/rebar3/releases/download/${REBAR3_VERSION}/rebar3" \

      --sha512 "${REBAR3_SHA512}" \

      --force

# set build ENV

ENV MIX_ENV="prod"

RUN mix deps.compile

# Install Tailwind and esbuild so assets can be built

RUN mix assets.setup

RUN mix assets.setup \

  && printf '%s  %s\n' \

      "${TAILWIND_SHA256}" "/app/_build/tailwind-linux-x64-${TAILWIND_VERSION}" \

      "${ESBUILD_SHA256}" "/app/_build/esbuild-linux-x64" \

    | sha256sum --check --strict

COPY priv priv

# the compiled release and other runtime necessities

FROM ${RUNNER_IMAGE} AS final

RUN apt-get update \

ARG DEBIAN_SNAPSHOT

ARG SOURCE_DATE_EPOCH=0

ENV SOURCE_DATE_EPOCH=${SOURCE_DATE_EPOCH}

RUN sed -i \

      "s|URIs: http://deb.debian.org/debian$|URIs: http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}|" \

      /etc/apt/sources.list.d/debian.sources \

  && sed -i \

      "s|URIs: http://deb.debian.org/debian-security$|URIs: http://snapshot.debian.org/archive/debian-security/${DEBIAN_SNAPSHOT}|" \

      /etc/apt/sources.list.d/debian.sources \

  && printf 'Acquire::Check-Valid-Until "false";\n' > /etc/apt/apt.conf.d/99snapshot \

  && apt-get update \

  && apt-get install -y --no-install-recommends libstdc++6 openssl libncurses6 locales ca-certificates git \

  && rm -rf /var/lib/apt/lists/*

- Reject any component library that emits generic component selectors into the

  Tailwind utilities layer or otherwise outranks the application component

  layer. Verify cascade behavior, not only dependency names.

- Keep the product deliberately dark-only for staging. Hide or remove the theme

  toggle while it has no visual effect; treat a light palette as a separate,

  owner-approved design project.

- Maintain exactly the two owned light and dark palettes, with a functional

  system, light, and dark preference control. Keep explicit choices ahead of

  the operating-system fallback, prevent a wrong-theme first paint, and reject

  third-party theme tokens or an undeclared third palette.

- Treat any style-pack rename as a controlled palette migration. Preserve the

  primitive token contract, run visual regression checks, and do not mistake a

  load-bearing palette file for a cosmetic filename.

- Build an SBOM for the staging image and retain it with the staging evidence.

**Exit criteria:** The application has one Markdown parser, one component

system, one documented two-tier icon policy, no nonfunctional theme control, no

unexplained dependency, and complete license records.

system, one documented two-tier icon policy, exactly two governed themes with a

functional preference control, no unexplained dependency, and complete license

records.

**Gate 4 status (2026-08-20): complete.**

  Added form-aware input, heading, table, and list primitives; removed the

  generated compatibility module; and made `/components` an executable

  inventory of every public component.

- Removed the browser theme script, theme control, theme selectors, and retired

  palette aliases. The palette remains deliberately dark-only. The Node suite

  now compiles Tailwind and proves that Basecoat geometry precedes the

  OpenAgents style pack and that all eight governed button variants survive the

  cascade.

- Removed the retired palette aliases and restored an owner-directed light

  palette alongside the neutral dark palette. The system, light, and dark

  preference control resolves before first paint. The Node suite compiles

  Tailwind and proves that exactly two owned themes and the system fallback

  survive, Basecoat geometry precedes the OpenAgents style pack, and all eight

  governed button variants survive the cascade.

- Migrated current glyph uses to the preferred vendored Apps SDK set. Retained

  Heroicons only as the owner-approved second tier, pinned it to immutable

  revision `0435d4ca364a608cc75e2f8683d374e55abbae26`, and recorded an empty

### Web acceptance lane

Use an isolated staging hostname such as `stage.openagents.com` for browser and

Use the isolated `staging.openagents.com` hostname for browser and

API acceptance. It needs:

- A staging-only GitHub OAuth application and callback.

  build receipt, and deploy receipt probes remained present. Both the candidate

  application and the last-known-good application started against the migrated

  copy.

- Added an exact-SHA staging publisher for the application image, isolated

  builder image, release tar, CycloneDX SBOM, and one checksummed candidate

  manifest. It resolves registry-reported manifest digests, verifies platform,

  OCI labels, and packaged revisions, supports safe resume after a partial

  push, and never creates a mutable convenience tag.

- Enabled immutable Docker tags and Terraform deletion prevention on the

  staging Artifact Registry. Pinned both base image manifests, Debian package

  snapshots, Hex, Rebar3, Tailwind, esbuild, the target architecture, and the

  build timestamp source. Distributed releases now refuse to start without an

  explicit runtime cookie rather than falling back to the packaged

  non-distributed placeholder.

- Built and inspected both container targets locally. The dated Debian sources

  and all executable checksums passed, both OCI labels and packaged build

  revisions matched the source commit, the builder contained one release

  archive, and a distributed boot without a runtime cookie failed closed. The

  repository-wide precommit completed with 1,378 Elixir tests and 17 JavaScript

  tests passing.

The [staging migration-lineage runbook](operations/staging-migration-lineage.md)

defines classification, copy rehearsal, snapshot, single-job migration,

rollback compatibility, and evidence collection. Gate 13 remains open until

the exact candidate image and release artifacts are retained and the selected

path runs against the isolated staging target.

the [immutable candidate runbook](operations/staging-candidate-artifacts.md)

runs against the isolated staging registry and the selected migration path runs

against the isolated staging target.

## Gate 14: Run the staging regression matrix

- [x] All documentation links and invariant evidence resolve.

- [x] The application has one Markdown parser, component system, and documented

      two-tier icon policy.

- [x] The dark-only palette has no nonfunctional theme control.

- [x] Exactly two owned palettes have a functional system, light, and dark

      preference control and compiled cascade coverage.

- [x] Runtime configuration is typed, redacted, and staging-specific.

- [x] Every route has an explicit authority class.

- [x] GitHub token behavior matches code, UI disclosure, and data rights.

The gate structure remains intact. The main plan now incorporates the measured

Gate 0 baseline, the missing JavaScript suite, database isolation, migration

lineage, configuration and authorization evidence, and recovery-test scope.

It also adopts the owner's two-tier icon decision, makes the current dark-only

palette explicit, and treats the style-pack rename as a palette migration.

It also adopts the owner's two-tier icon decision, records the dark-only

palette that existed when the addendum was measured, and treats the style-pack

rename as a palette migration. The later owner-directed light-mode change is

recorded in the current disposition below.

This addendum remains as the measurement record. Everything here was verified

directly at the SHA given, not inferred.

| A1, missing browser tests and incomplete baseline | Resolved by Gate 0. The owned baseline now runs the Node suites, merged Elixir coverage, and release smoke against an exact SHA. |

| A2, staging shares a production database failure domain | Open and blocking Gates 12 and 15. Provision a separate staging database instance before any failure injection or soak. |

| A3, incompatible migration lineage on a nonempty prior database | Mapped and rehearsed locally with a fail-closed release command. Each actual prior-lineage target still requires its own snapshot-copy rehearsal before Gate 13 deployment. |

| A4, component, icon, and palette conflicts | Resolved by Gate 4 and its compiled CSS contract tests. |

| A4, component, icon, and palette conflicts | Resolved by Gate 4 and its compiled CSS contract tests. The later owner-directed light-mode change supersedes only the addendum's historical dark-only palette decision. |

| A5, silent runtime configuration failures | Resolved by Gate 5 and its fail-closed runtime readiness checks. |

| A6, repository authorization violations | Resolved by Gate 7 in code, PostgreSQL constraints, and the populated migration rehearsal. |

| A7, missing recovery-worker tests | Resolved by Gate 8 with direct supervised-process recovery tests. |

## A4. Four places the plan disagrees with a prior decision or current state

These were originally flagged for deliberate choices. Gate 4 now records their

disposition: retain the owner-approved Heroicons fallback, keep staging

deliberately dark-only without a nonfunctional toggle, control the palette-file

rename as a visual migration, and reject conflicting cascade-layer behavior.

disposition: retain the owner-approved Heroicons fallback, govern the two owned

palettes and functional preference control, control the palette-file rename as

a visual migration, and reject conflicting cascade-layer behavior.

**Heroicons, resolved.** Product surfaces now use Apps SDK glyphs. Heroicons

remains the deliberate fallback, is pinned to an immutable revision, and has no

current product call sites. `docs/ICONS.md` governs and inventories exceptions.

**The palette is dark-only, resolved.** The application removed its theme

control, browser theme state, and theme selectors. A light palette remains a

separate owner-approved design project.

**The palette finding is resolved and the original decision is superseded.**

The application was dark-only when this addendum was measured. The later

owner-directed palette change added one governed light palette, restored a

system, light, and dark preference control, and replaced the old negative

theme assertion with compiled positive contracts for both owned themes and the

operating-system fallback. No third-party theme plugin or third palette was

introduced.

**The palette file, resolved.** `assets/css/openagents.css` owns the palette

contract and loads after individually imported Basecoat structure. The retired

# Publish an immutable staging candidate

Publish one exact, gated Git commit as two immutable images and one retained

artifact set before you migrate or deploy staging. The application image serves

traffic. The separate builder image contains the pinned compiler toolchain and

the exact release archive.

The staging Artifact Registry enables [immutable image tags](https://docs.cloud.google.com/artifact-registry/docs/docker/names).

Terraform also prevents deletion of the repository. The publication command

uses the full Git SHA as each tag, reads the registry manifest descriptor after

the push, and deploys by digest rather than by tag.

## Build inputs

The container build pins these external inputs:

- Elixir and Debian base images by OCI manifest digest.

- Debian and Debian Security packages to the dated 2026-08-03 snapshot.

- Hex by exact version.

- Rebar3 by exact release URL and SHA-512 checksum.

- Tailwind and esbuild by exact version and executable SHA-256 checksum.

- Application dependencies by `mix.lock` and Hex package checksums.

- Build timestamps with the commit timestamp through `SOURCE_DATE_EPOCH`.

- The deployment platform as `linux/amd64`, matching the staging fleet.

The packaged release contains a fixed non-distributed cookie placeholder. A

fleet node refuses to start distribution unless the staging runtime provides a

separate `RELEASE_COOKIE` with at least 32 bytes. Never put the staging cookie

in an image or artifact manifest.

Update base, snapshot, Hex, or Rebar3 pins in a dedicated dependency change.

Run the complete exact-SHA release gate and inspect the resulting SBOM before

you publish a candidate with new pins.

## Check publication prerequisites

Use a clean `main` worktree whose `HEAD` equals the locally fetched

`origin/main`. The exact commit must already have a complete local release-gate

receipt. Export only staging and comparison project identifiers:

```sh

export OPENAGENTS_STAGING_PROJECT_ID='openagents-staging-UNIQUE'

export OPENAGENTS_PRODUCTION_PROJECT_ID='PRODUCTION_PROJECT_ID'

export OPENAGENTS_STAGING_REGION='us-central1'

ops/staging/publish-candidate.sh check

```

The check is read-only. It verifies the project fence, active Google Cloud

authentication, exact local gate receipt, staging Artifact Registry format,

and immutable-tag setting. It does not build or push an image.

Do not continue if the check reports an expired login. Refresh both the Cloud

CLI and Application Default Credentials before the broader staging workflow:

```sh

gcloud auth login

gcloud auth application-default login

```

## Publish the candidate

Publish only after the isolated Gate 12 project and registry exist:

```sh

ops/staging/publish-candidate.sh --publish

```

The command performs these operations:

1. Repeats every preflight check and configures Docker authentication only for

   the staging registry host.

2. Builds the application and isolated forge-builder targets with the exact Git

   SHA, commit timestamp, and `linux/amd64` deployment platform.

3. Pushes only full-SHA tags into the immutable staging repository. If an

   earlier attempt already pushed a tag, it resolves and verifies that existing

   immutable image instead of moving the tag.

4. Reads and validates the registry-reported application and builder OCI

   manifest digests.

5. Pulls both digest references and verifies their OCI revision labels and

   packaged `OpenAgents.BuildInfo` revisions.

6. Extracts the exact release tar from the builder image.

7. Generates a CycloneDX SBOM from the digest-addressed application image by

   using the digest-pinned Syft image.

8. Writes and hashes one candidate manifest that binds the Git SHA, registry

   manifests, local image configurations, release archive, SBOM, release-gate

   receipt, Dockerfile, lockfile, migration-lineage map, application spec, and

   compiler toolchain.

The command never creates `latest`, environment, or branch tags. A failed

second image push can be resumed because the first full-SHA tag cannot move.

An unexpected existing local evidence directory fails closed unless it already

contains a valid manifest for the exact SHA.

## Review the retained artifact set

The command writes mode-`0600` evidence under:

```text

.git/openagents/staging-candidates/<full-sha>/

  candidate-manifest.json

  candidate-manifest.sha256

  openagents-<release-version>.tar.gz

  sbom.cdx.json

  sbom.cdx.json.receipt

```

The `.git` location prevents accidental commits. Copy the complete directory

to the staging-only versioned evidence bucket after Gate 12, and verify

`candidate-manifest.sha256` after upload. Do not upload Docker credentials,

Cloud CLI state, environment files, database URLs, or secret values.

Use only the `images.application.reference` and `images.builder.reference`

digest values from `candidate-manifest.json` in deployment configuration. A

tag is a review label, not deployment authority. Require every web revision,

fleet node, `/status` response, and deployment receipt to report the same Git

SHA and application manifest digest.

## Refuse or recover a candidate

Refuse publication if any of these conditions occurs:

- `HEAD` differs from `origin/main` or lacks an exact gate receipt.

- The target project is unmarked, equals production, or lacks immutable tags.

- A registry label or packaged build revision differs from the Git SHA.

- A registry manifest, release, SBOM, or input digest has an invalid shape.

- The generated manifest does not validate before its atomic move.

If publication fails after an immutable tag exists, preserve the local logs and

rerun the same exact commit. Do not delete or move the tag. If the existing

image fails identity verification, stop and investigate the registry as a

security incident. Never recover by publishing a different commit under the

same SHA tag.

  Terraform never creates a secret version or stores a credential in state.

- Separate buckets for forge artifacts, forge WAL, recordings, and evidence.

- One Artifact Registry repository for digest-addressed application and builder

  images.

  images. Full-SHA tags are immutable, and Terraform cannot delete the

  repository.

The instances start fenced. They do not run an application until an operator

assigns exact application and builder image digests and creates the required

staging-only secret versions during Gate 13.

After this boundary exists, use the

[immutable candidate runbook](../../docs/operations/staging-candidate-artifacts.md)

to publish the exact application image, builder image, release archive, SBOM,

and candidate manifest for Gate 13.

## Prerequisites

You need these local tools:

  labels        = local.labels

  cleanup_policy_dry_run = true

  deletion_policy        = "PREVENT"

  docker_config {

    immutable_tags = true

  }

  depends_on = [google_project_service.required]

}

    error_message = "Staging must have a separate application database role."

  }

  assert {

    condition     = google_artifact_registry_repository.openagents.docker_config[0].immutable_tags

    error_message = "Staging application and builder image tags must be immutable."

  }

  assert {

    condition     = google_artifact_registry_repository.openagents.deletion_policy == "PREVENT"

    error_message = "Terraform must not delete the staging artifact repository."

  }

  assert {

    condition     = length(google_secret_manager_secret.runtime) == 12

    error_message = "Every named staging credential and lane configuration needs its own secret resource."

    "system" stores nothing and leaves data-theme unset so the CSS

    prefers-color-scheme fallback governs; an explicit choice sets the

    attribute, which always wins. --%>

    <script phx-no-format>(() => {

          const stored = localStorage.getItem("phx:theme");

          const apply = (choice) => {

            if (choice === "system" || choice === null) {

              localStorage.removeItem("phx:theme");

              document.documentElement.removeAttribute("data-theme");

              document.documentElement.setAttribute("data-theme-choice", "system");

            } else {

              localStorage.setItem("phx:theme", choice);

              document.documentElement.setAttribute("data-theme", choice);

              document.documentElement.setAttribute("data-theme-choice", choice);

            }

          };

          apply(stored);

          window.addEventListener("phx:set-theme", (e) => apply(e.detail?.theme ?? e.target?.dataset?.theme));

          window.addEventListener("storage", (e) => e.key === "phx:theme" && apply(e.newValue));

        })();</script>

    <script phx-no-curly-interpolation>

      (() => {

        const stored = localStorage.getItem("phx:theme");

        const apply = (choice) => {

          if (choice === "system" || choice === null) {

            localStorage.removeItem("phx:theme");

            document.documentElement.removeAttribute("data-theme");

            document.documentElement.setAttribute("data-theme-choice", "system");

          } else {

            localStorage.setItem("phx:theme", choice);

            document.documentElement.setAttribute("data-theme", choice);

            document.documentElement.setAttribute("data-theme-choice", choice);

          }

        };

        apply(stored);

        window.addEventListener("phx:set-theme", (e) => apply(e.detail?.theme ?? e.target?.dataset?.theme));

        window.addEventListener("storage", (e) => e.key === "phx:theme" && apply(e.newValue));

      })();

    </script>

    <script defer phx-track-static type="text/javascript" src={~p"/assets/js/app.js"}>

    </script>

  </head>

      [

        include_erts: true,

        include_src: false,

        cookie: "openagents-nondistributed-placeholder",

        steps: [

          &OpenAgents.ReleaseAssembler.pre_assemble/1,

          :assemble,

ops/ci/reference-check.sh

sh -n rel/overlays/bin/migration-lineage

sh -n ops/staging/cleanup-run.sh

sh -n ops/staging/publish-candidate.sh

elixir ops/ci/docs-check.exs

MIX_ENV=test mix test --warnings-as-errors \

  test/openagents/log_safety_test.exs \

  test/openagents/migration_lineage_test.exs \

  test/openagents/runtime_config_test.exs \

  test/openagents/staging_cleanup_test.exs \

  test/openagents/staging_candidate_contract_test.exs \

  test/openagents_web/icon_affordances_test.exs \

  test/openagents_web/icons_test.exs \

  test/openagents_web/ui_test.exs

fi

git_sha=$(git -C "$repo_root" rev-parse --verify HEAD)

source_date_epoch=$(git -C "$repo_root" show -s --format=%ct "$git_sha")

platform=${OPENAGENTS_IMAGE_PLATFORM:-linux/amd64}

tag=${1:-"openagents:$git_sha"}

image_root="$repo_root/.git/openagents/images"

result_path="$image_root/$git_sha.json"

trap cleanup EXIT INT TERM

if [ "$platform" != "linux/amd64" ]; then

  echo "OPENAGENTS_IMAGE_PLATFORM must be linux/amd64 for the staging fleet" >&2

  exit 1

fi

"$repo_root/ops/ci/gate.sh" --verify

docker build \

  --platform "$platform" \

  --build-arg "OPENAGENTS_BUILD_REVISION=$git_sha" \

  --build-arg "SOURCE_DATE_EPOCH=$source_date_epoch" \

  --iidfile "$iid_file" \

  --label "org.opencontainers.image.revision=$git_sha" \

  --tag "$tag" \

  "schema": "openagents.local-image.v1",

  "git_sha": "$git_sha",

  "image_digest": "$image_digest",

  "digest_scope": "local_config",

  "platform": "$platform",

  "source_date_epoch": $source_date_epoch,

  "tag": "$tag"

}

EOF

}

proof_root() {

  printf '%s\n' "$repo_root/.git/openagents/relup-proof/$(proof_key)"

  key=$(proof_key) || return $?

  printf '%s\n' "$repo_root/.git/openagents/relup-proof/$key"

}

require_proof_artifacts() {

readonly source_commit="$(git rev-parse HEAD)"

readonly image_digest="$(

  docker image inspect "$image_reference" \

    --format '{{index .RepoDigests 0}}' 2>/dev/null

)"

case "$image_reference" in

  *@sha256:????????????????????????????????????????????????????????????????)

    readonly image_digest="$image_reference"

    ;;

  *)

    readonly image_digest="$(

      docker image inspect "$image_reference" \

        --format '{{index .RepoDigests 0}}' 2>/dev/null

    )"

    ;;

esac

if [[ -z "$image_digest" || "$image_digest" == "<no value>" ]]; then

  echo "image must be present locally with a resolved repository digest: $image_reference" >&2

#!/bin/sh

set -eu

script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)

repo_root=$(CDPATH= cd -- "$script_dir/../.." && pwd)

mode=${1:-check}

staging_project=${OPENAGENTS_STAGING_PROJECT_ID:-}

production_project=${OPENAGENTS_PRODUCTION_PROJECT_ID:-}

region=${OPENAGENTS_STAGING_REGION:-us-central1}

repository_id=openagents-staging

platform=linux/amd64

: "${staging_project:?OPENAGENTS_STAGING_PROJECT_ID is required}"

: "${production_project:?OPENAGENTS_PRODUCTION_PROJECT_ID is required}"

case "$mode" in

  check) ;;

  --publish) ;;

  *) echo "usage: ops/staging/publish-candidate.sh [check|--publish]" >&2; exit 64 ;;

esac

case "$staging_project" in

  *stag*) ;;

  *) echo "staging project ID must contain 'stag'" >&2; exit 1 ;;

esac

if [ "$staging_project" = "$production_project" ]; then

  echo "staging and production project IDs must differ" >&2

  exit 1

fi

for command_name in docker gcloud jq sha256sum; do

  if ! command -v "$command_name" >/dev/null 2>&1; then

    echo "$command_name is required" >&2

    exit 1

  fi

done

cd "$repo_root"

if [ -n "$(git status --porcelain --untracked-files=all)" ]; then

  echo "candidate publication requires a clean worktree" >&2

  exit 1

fi

git_sha=$(git rev-parse --verify HEAD)

origin_main=$(git rev-parse --verify refs/remotes/origin/main)

source_date_epoch=$(git show -s --format=%ct "$git_sha")

if [ "$git_sha" != "$origin_main" ]; then

  echo "candidate must equal the locally fetched origin/main commit" >&2

  exit 1

fi

ops/ci/gate.sh --verify

gcloud auth print-access-token >/dev/null

repository_json=$(

  gcloud artifacts repositories describe "$repository_id" \

    --project="$staging_project" \

    --location="$region" \

    --format=json

)

echo "$repository_json" | jq -e '

  .format == "DOCKER" and

  .dockerConfig.immutableTags == true

' >/dev/null || {

  echo "staging Artifact Registry must be Docker format with immutable tags" >&2

  exit 1

}

if [ "$mode" = check ]; then

  echo "Candidate publication preflight passed for $git_sha"

  exit 0

fi

registry_host="${region}-docker.pkg.dev"

repository="${registry_host}/${staging_project}/${repository_id}"

application_repository="${repository}/openagents"

builder_repository="${repository}/openagents-builder"

application_tag="${application_repository}:${git_sha}"

builder_tag="${builder_repository}:${git_sha}"

evidence_root="$repo_root/.git/openagents/staging-candidates"

candidate_path="$evidence_root/$git_sha"

run_root=$(mktemp -d /tmp/openagents-staging-candidate.XXXXXX)

candidate_temp=

builder_container=

cleanup() {

  if [ -n "$builder_container" ]; then

    docker rm "$builder_container" >/dev/null 2>&1 || true

  fi

  if [ -n "$candidate_temp" ] && [ -d "$candidate_temp" ]; then

    find "$candidate_temp" -depth -delete 2>/dev/null || true

  fi

  find "$run_root" -depth -delete 2>/dev/null || true

}

trap cleanup EXIT INT TERM

if [ -e "$candidate_path" ]; then

  if jq -e --arg sha "$git_sha" '.git_sha == $sha' \

    "$candidate_path/candidate-manifest.json" >/dev/null 2>&1; then

    echo "Candidate evidence already exists for $git_sha"

    exit 0

  fi

  echo "candidate evidence path exists without a valid exact-SHA manifest" >&2

  exit 1

fi

umask 077

mkdir -p "$evidence_root"

candidate_temp=$(mktemp -d "$evidence_root/.candidate.$git_sha.XXXXXX")

gcloud auth configure-docker "$registry_host" --quiet >/dev/null

remote_digest() {

  image_tag=$1

  receipt_name=$2

  descriptor="$run_root/$receipt_name.descriptor.json"

  inspect_error="$run_root/$receipt_name.inspect-error"

  if docker buildx imagetools inspect "$image_tag" \

    --format '{{json .Manifest}}' >"$descriptor" 2>"$inspect_error"; then

    if jq -er '.digest | select(test("^sha256:[0-9a-f]{64}$"))' "$descriptor"; then

      return 0

    fi

    echo "registry returned an invalid manifest descriptor for $image_tag" >&2

    cat "$descriptor" >&2

    return 2

  fi

  if grep -Eiq 'not found|manifest unknown|does not exist' "$inspect_error"; then

    return 1

  fi

  cat "$inspect_error" >&2

  return 2

}

verify_platform() {

  image_reference=$1

  operating_system=$(docker image inspect "$image_reference" --format '{{.Os}}')

  architecture=$(docker image inspect "$image_reference" --format '{{.Architecture}}')

  if [ "$operating_system/$architecture" != "$platform" ]; then

    echo "$image_reference resolved to $operating_system/$architecture, expected $platform" >&2

    return 1

  fi

  return 0

}

if application_digest=$(remote_digest "$application_tag" application); then

  echo "Reusing immutable application tag for $git_sha"

else

  remote_status=$?

  if [ "$remote_status" -ne 1 ]; then

    exit "$remote_status"

  fi

  OPENAGENTS_IMAGE_PLATFORM="$platform" ops/deploy/build-image.sh "$application_tag"

  docker push "$application_tag" >/dev/null

  application_digest=$(remote_digest "$application_tag" application)

fi

if builder_digest=$(remote_digest "$builder_tag" builder); then

  echo "Reusing immutable builder tag for $git_sha"

else

  remote_status=$?

  if [ "$remote_status" -ne 1 ]; then

    exit "$remote_status"

  fi

  builder_iid="$run_root/builder.iid"

  docker build \

    --platform "$platform" \

    --build-arg "OPENAGENTS_BUILD_REVISION=$git_sha" \

    --build-arg "SOURCE_DATE_EPOCH=$source_date_epoch" \

    --iidfile "$builder_iid" \

    --label "org.opencontainers.image.revision=$git_sha" \

    --tag "$builder_tag" \

    --target forge-builder \

    "$repo_root"

  docker push "$builder_tag" >/dev/null

  builder_digest=$(remote_digest "$builder_tag" builder)

fi

case "$application_digest" in

  sha256:????????????????????????????????????????????????????????????????) ;;

  *) echo "application registry manifest digest is invalid" >&2; exit 1 ;;

esac

case "$builder_digest" in

  sha256:????????????????????????????????????????????????????????????????) ;;

  *) echo "builder registry manifest digest is invalid" >&2; exit 1 ;;

esac

application_image="${application_repository}@${application_digest}"

builder_image="${builder_repository}@${builder_digest}"

docker pull --platform "$platform" "$application_image" >/dev/null

docker pull --platform "$platform" "$builder_image" >/dev/null

verify_platform "$application_image"

verify_platform "$builder_image"

application_revision=$(

  docker image inspect "$application_image" \

    --format '{{index .Config.Labels "org.opencontainers.image.revision"}}'

)

builder_revision=$(

  docker image inspect "$builder_image" \

    --format '{{index .Config.Labels "org.opencontainers.image.revision"}}'

)

if [ "$application_revision" != "$git_sha" ] || [ "$builder_revision" != "$git_sha" ]; then

  echo "registry image revision labels do not match the exact Git SHA" >&2

  exit 1

fi

embedded_application_revision=$(

  docker run --rm \

    --entrypoint /bin/sh \

    "$application_image" \

    -c 'release_version=$(awk '\''{print $2}'\'' /app/releases/start_erl.data); /app/erts-*/bin/erl -boot_var RELEASE_LIB /app/lib -boot "/app/releases/$release_version/start_clean" -noshell -pa /app/lib/openagents-*/ebin -eval "io:put_chars('\''Elixir.OpenAgents.BuildInfo'\'':revision()), halt()."' \

    | tail -n 1

)

embedded_builder_revision=$(

  docker run --rm \

    --entrypoint /bin/sh \

    "$builder_image" \

    -c 'elixir -pa /app/_build/prod/lib/openagents/ebin -e "IO.write(OpenAgents.BuildInfo.revision())"'

)

if [ "$embedded_application_revision" != "$git_sha" ] ||

  [ "$embedded_builder_revision" != "$git_sha" ]; then

  echo "registry image packaged revisions do not match the exact Git SHA" >&2

  exit 1

fi

application_config_digest=$(docker image inspect "$application_image" --format '{{.Id}}')

builder_config_digest=$(docker image inspect "$builder_image" --format '{{.Id}}')

archive_name=$(

  docker run --rm \

    --entrypoint /bin/sh \

    "$builder_image" \

    -c 'set -- /app/_build/prod/openagents-*.tar.gz; [ "$#" -eq 1 ]; basename "$1"'

)

case "$archive_name" in

  openagents-*.tar.gz) ;;

  *) echo "builder image does not contain one release archive" >&2; exit 1 ;;

esac

release_version=${archive_name#openagents-}

release_version=${release_version%.tar.gz}

builder_container=$(docker create "$builder_image")

docker cp "$builder_container:/app/_build/prod/$archive_name" "$candidate_temp/$archive_name" >/dev/null

docker rm "$builder_container" >/dev/null

builder_container=

ops/staging/generate-sbom.sh \

  "$application_image" \

  "$candidate_temp/sbom.cdx.json"

release_sha256=$(sha256sum "$candidate_temp/$archive_name" | cut -d ' ' -f 1)

sbom_sha256=$(sha256sum "$candidate_temp/sbom.cdx.json" | cut -d ' ' -f 1)

sbom_receipt_sha256=$(sha256sum "$candidate_temp/sbom.cdx.json.receipt" | cut -d ' ' -f 1)

gate_receipt="$repo_root/.git/openagents/release-gate-receipts/$git_sha.json"

gate_receipt_sha256=$(sha256sum "$gate_receipt" | cut -d ' ' -f 1)

dockerfile_sha256=$(sha256sum "$repo_root/Dockerfile" | cut -d ' ' -f 1)

mix_lock_sha256=$(sha256sum "$repo_root/mix.lock" | cut -d ' ' -f 1)

lineage_map_sha256=$(sha256sum "$repo_root/priv/migration_lineages/prior-2026-08-19.json" | cut -d ' ' -f 1)

application_spec_sha256=$(

  docker run --rm \

    --entrypoint /bin/sh \

    "$builder_image" \

    -c 'sha256sum /app/_build/prod/lib/openagents/ebin/openagents.app' \

    | cut -d ' ' -f 1

)

elixir_version=$(docker run --rm --entrypoint elixir "$builder_image" --version | awk '/^Elixir / {print $2}')

otp_release=$(docker run --rm --entrypoint elixir "$builder_image" --version | awk '/^Erlang\/OTP / {print $2}')

erts_version=$(

  docker run --rm --entrypoint erl "$builder_image" \

    -noshell -eval 'io:put_chars(erlang:system_info(version)), halt().'

)

generated_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)

manifest_temp="$candidate_temp/candidate-manifest.json.tmp"

jq -n \

  --arg git_sha "$git_sha" \

  --arg generated_at "$generated_at" \

  --argjson source_date_epoch "$source_date_epoch" \

  --arg staging_project "$staging_project" \

  --arg region "$region" \

  --arg platform "$platform" \

  --arg application_tag "$application_tag" \

  --arg application_image "$application_image" \

  --arg application_digest "$application_digest" \

  --arg application_config_digest "$application_config_digest" \

  --arg builder_tag "$builder_tag" \

  --arg builder_image "$builder_image" \

  --arg builder_digest "$builder_digest" \

  --arg builder_config_digest "$builder_config_digest" \

  --arg release_version "$release_version" \

  --arg release_file "$archive_name" \

  --arg release_sha256 "$release_sha256" \

  --arg sbom_sha256 "$sbom_sha256" \

  --arg sbom_receipt_sha256 "$sbom_receipt_sha256" \

  --arg gate_receipt_sha256 "$gate_receipt_sha256" \

  --arg dockerfile_sha256 "$dockerfile_sha256" \

  --arg mix_lock_sha256 "$mix_lock_sha256" \

  --arg lineage_map_sha256 "$lineage_map_sha256" \

  --arg elixir_version "$elixir_version" \

  --arg otp_release "$otp_release" \

  --arg erts_version "$erts_version" \

  --arg application_spec_sha256 "$application_spec_sha256" '

  {

    schema: "openagents.staging-candidate.v1",

    git_sha: $git_sha,

    branch: "main",

    generated_at: $generated_at,

    source_date_epoch: $source_date_epoch,

    target: {

      environment: "staging",

      project: $staging_project,

      region: $region,

      platform: $platform,

      immutable_tags: true

    },

    images: {

      application: {

        tag: $application_tag,

        reference: $application_image,

        manifest_digest: $application_digest,

        config_digest: $application_config_digest

      },

      builder: {

        tag: $builder_tag,

        reference: $builder_image,

        manifest_digest: $builder_digest,

        config_digest: $builder_config_digest

      }

    },

    release: {

      version: $release_version,

      file: $release_file,

      sha256: $release_sha256

    },

    sbom: {

      file: "sbom.cdx.json",

      sha256: $sbom_sha256,

      receipt_sha256: $sbom_receipt_sha256

    },

    receipts: {

      release_gate_sha256: $gate_receipt_sha256

    },

    inputs: {

      dockerfile_sha256: $dockerfile_sha256,

      mix_lock_sha256: $mix_lock_sha256,

      migration_lineage_map_sha256: $lineage_map_sha256,

      application_spec_sha256: $application_spec_sha256

    },

    toolchain: {

      elixir: $elixir_version,

      otp: $otp_release,

      erts: $erts_version

    }

  }

' >"$manifest_temp"

mv "$manifest_temp" "$candidate_temp/candidate-manifest.json"

manifest_sha256=$(sha256sum "$candidate_temp/candidate-manifest.json" | cut -d ' ' -f 1)

printf '%s  candidate-manifest.json\n' "$manifest_sha256" \

  >"$candidate_temp/candidate-manifest.sha256"

jq -e \

  --arg sha "$git_sha" \

  --arg application_digest "$application_digest" \

  --arg builder_digest "$builder_digest" '

  .schema == "openagents.staging-candidate.v1" and

  .git_sha == $sha and

  .target.environment == "staging" and

  .target.immutable_tags == true and

  .images.application.manifest_digest == $application_digest and

  .images.builder.manifest_digest == $builder_digest and

  (.release.sha256 | test("^[0-9a-f]{64}$")) and

  (.sbom.sha256 | test("^[0-9a-f]{64}$"))

' "$candidate_temp/candidate-manifest.json" >/dev/null

mv "$candidate_temp" "$candidate_path"

candidate_temp=

trap - EXIT INT TERM

find "$run_root" -depth -delete

echo "Published immutable staging candidate $git_sha"

echo "Application: $application_image"

echo "Builder: $builder_image"

echo "Evidence: .git/openagents/staging-candidates/$git_sha"

# all that is needed to form a BEAM cluster.

if [ -n "${OPENAGENTS_NODE_HOST:-}" ]; then

  : "${RELEASE_COOKIE:?RELEASE_COOKIE is required for a distributed node}"

  export RELEASE_DISTRIBUTION="name"

  export RELEASE_NODE="${RELEASE_NODE:-openagents@${OPENAGENTS_NODE_HOST}}"

  # Pin Erlang distribution ports to a fixed range so firewall rules and

defmodule OpenAgents.StagingCandidateContractTest do

  use ExUnit.Case, async: true

  test "the staging registry prevents tag movement and Terraform deletion" do

    terraform = File.read!("infra/staging/main.tf")

    safety_test = File.read!("infra/staging/tests/safety.tftest.hcl")