ci.yml

name: CI

on:
  push:
    branches: [main, develop]
    paths-ignore:
      - '**/*.md'
      - 'content/**'
      - 'docs/**'
      - 'apps/site/**'
      - '.changeset/**'
  # No `paths-ignore` here any more (objectui#3523, step 2). It skipped the
  # whole workflow on a docs-only / changeset-only PR, so every context this
  # file produces was simply absent there and none of them could be made
  # required. The path decision now lives inside the jobs — see the
  # `Decide whether this change needs a full run` step in `type-check`. `push`
  # above deliberately keeps its copy: nothing judges a push to `main`.
  pull_request:
    branches: [main, develop]
  # ── Merge queue (objectui#3523) ────────────────────────────────────────
  # The merge queue is ENFORCED on this repository by a ruleset — a direct push
  # to `main` returns 405 `Changes must be made through the merge queue`
  # (measured in #3243). Until this trigger landed, not one of the repository's
  # workflows subscribed `merge_group`: repo-wide `event=merge_group` runs stood
  # at total_count = 0, historically. A queue with nothing subscribed to it can
  # only have an EMPTY required-check set, so it rebuilt each PR on the current
  # `main` and let it through without validating anything.
  #
  # That is not a theoretical hole; it was cashed in on 2026-08-07. #3498 landed
  # a `scripts/` type gate, itself fully green, that left a TS2578 on `main`;
  # #3503, #3510 and #3516 then merged between 02:11Z and 02:15Z with `Type
  # Check` at conclusion=failure, and #3505 hot-fixed the result. objectstack
  # went through the same frames (objectstack#6067 -> #5615).
  #
  # `types:` is spelled out although `checks_requested` is the ONLY activity
  # type GitHub defines for `merge_group` today — the two spellings are
  # equivalent right now (objectstack's `ci.yml` and `lint.yml` use the bare
  # `merge_group:` form and produce queue builds normally, 3552 of them). Naming
  # the type means a second activity type added later cannot silently start
  # queue builds this workflow was never written for.
  #
  # `concurrency` below needs no merge-queue special case, and that was checked
  # rather than assumed: on `merge_group` the `github.event.pull_request` half of
  # the group expression is null, so the group falls back to `github.ref`, which
  # on a queue build is the queue's own generation — measured on objectstack,
  # `gh-readonly-queue/main/pr-6594-251e888ac9ace8226f3a8450951e5b40a0a84c2c`.
  # It can collide with neither a pull-request group (a bare PR number) nor a
  # push group (a commit sha since objectui#5422), so a queue build and the PR
  # build it came from never cancel each other.
  merge_group:
    types: [checks_requested]
  # ── Two speeds (objectui#12214, objectstack#22998) ─────────────────────
  # A `pull_request` or `merge_group` run carries the FAST SET: the `test`
  # matrix below runs the test files the change affects, selected by
  # `scripts/select-affected-tests.mjs`. `push` to `main` and this hourly
  # `schedule` carry the FULL BATTERY: every test file in sixteen shards, plus
  # the eight-shard coverage lane. Nothing is deleted or weakened; the whole
  # suite moved to `main`, where it runs on every merge and at least hourly.
  # GitHub runs `schedule` on the default branch only. The minute is off the
  # hour on purpose: scheduled workflows queue behind everyone else's `:00`.
  # On `schedule` the concurrency group below falls through to `github.ref`
  # (`refs/heads/main`), which no push (a sha) or pull request (a number)
  # shares; an hourly run is cancelled only by the next one, an hour later.
  schedule:
    - cron: '26 * * * *'

# ── Concurrency (objectui#5422) ───────────────────────────────────
# On `pull_request` the group is the PR number and `cancel-in-progress` cancels
# that PR's previous run. That is correct and is deliberately UNCHANGED here: a
# superseded PR push has nothing left to deliver.
#
# On `push` the group now carries `github.sha`, so every merge to `main` gets a
# group of its own and no merge can cancel another merge's run. Until #5422 the
# push branch of this expression fell back to `github.ref` — `refs/heads/main`
# for EVERY merge — so each merge cancelled the previous merge's still-running
# CI.
#
# That matters because the push lane is the only lane that runs the coverage
# gate (`test-coverage` + `coverage-report` below are push-only), and the merged
# report of every coverage shard is what enforces `coverage.thresholds` for a
# commit. Measured on this repository over the 64 completed push-lane runs on
# `main` between 2026-08-23T06:34Z and 2026-08-24T13:56Z: the merged report was
# produced for 20, five lost it to a red suite, and 39 — 61% — lost it to
# CANCELLATION. Over the 30 strictly consecutive push runs of 2026-08-24 alone
# it is 15 of 28 completed (54%). The lane needs ~13.5 min end to end while the
# median inter-merge interval is 8.8 min, so most merges are overtaken before
# the gate can report at all.
#
# ⚠️ This has to live at WORKFLOW level, not on the coverage jobs. A job-level
# `concurrency:` only decides whether a job waits for another job in the same
# group; it grants no exemption from the workflow-level `cancel-in-progress`,
# which cancels the whole run and every job in it. A per-sha group on
# `test-coverage` alone would therefore NOT have protected it.
#
# ⛔ Not `cancel-in-progress: false` on a `github.ref` group: that does not
# serialise. With `cancel-in-progress` unset GitHub holds ONE pending run per
# group and DISCARDS the rest — measured on this repository's release lane at
# 95 of 200 runs never executing at all (objectui#5395). It would trade
# cancellation for silent dropping, which is strictly worse.
#
# The cost is the one option A named on #5422: a burst of merges no longer
# collapses into a single surviving run, so the push lane's other jobs also run
# to completion and runner minutes rise. Nothing is weakened by that — every
# merged commit now gets its own verdict, which is the only post-merge signal
# this repository has while the merge queue validates nothing (objectui#4986).
#
# Trigger by trigger:
#   pull_request  `github.event.pull_request.number` is set, so the chain stops
#                 there                                       => ci-CI-<number>
#   push          the number is null and `github.event_name == 'push'` is true,
#                 so `&&` yields the sha                       => ci-CI-<sha>
#   merge_group   the number is null and the `push` test is false, so `&&`
#                 yields false and the chain falls through to `github.ref`,
#                 which on a queue build is the queue's own generation ref
#                 (`gh-readonly-queue/main/pr-<n>-<sha>`) — colliding with
#                 neither a PR group nor a push group, exactly as before.
# Least privilege for the job token. Every job without its own `permissions:`
# block (changeset-check, type-check, test, test-dist-pins, test-coverage,
# e2e, docs) only checks out, builds, tests, and saves caches and artifacts;
# none of those calls the API with this token (actions/cache and
# actions/upload-artifact use the runner's own token), so `contents: read` is
# all they get. The two jobs that read the Actions API (test-aggregate,
# coverage-report) declare their own block, which replaces this one.
permissions:
  contents: read

concurrency:
  group: >-
    ci-${{ github.workflow }}-${{ github.event.pull_request.number
    || (github.event_name == 'push' && github.sha)
    || github.ref }}
  cancel-in-progress: true

jobs:
  changeset-check:
    name: Changeset Fixed Group Check
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Verify all packages are in changeset fixed group
        run: node scripts/check-changeset-fixed.mjs

  # Types were entirely unguarded until #2911: no job ran `type-check`, and
  # `turbo build` only checks types for packages whose build script happens to
  # invoke `tsc` — the 22 `vite build` packages transpile without checking. A
  # `maplibre-gl@6` breakage therefore sat on `main` for a day behind a green CI.
  #
  # Note that `pnpm type-check` alone is not a sufficient gate: turbo silently
  # skips any package with no `type-check` script, so a package without one
  # reads as passing. The coverage guard is what makes that impossible, and it
  # runs first because it is instant and catches the structural mistake.
  type-check:
    name: Type Check
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          submodules: true
          # `pnpm check:i18n-drift` (below) compares the locale packs on this
          # branch against the packs at its MERGE BASE with the target branch,
          # so it needs history — and checkout's default is a depth-1 clone,
          # where `git merge-base` has nothing to find. The gate treats an
          # unresolvable base as a hard failure rather than a skip, so getting
          # this wrong is a red build rather than a silent pass; it is spelled
          # out here so it stays that way. Pinned by
          # `scripts/__tests__/check-i18n-en-drift.test.ts`.
          fetch-depth: 0

      # ── Always report; run only when it matters (objectui#3523) ──────────
      # This context used to be invisible on a docs-only or changeset-only pull
      # request, because `on.pull_request.paths-ignore` skips the WHOLE workflow
      # when every changed file matches — GitHub has no per-job path filter. No
      # workflow means no check run, and a REQUIRED check that never reports
      # does not fail the PR, it leaves it pending forever; in the merge queue
      # it fails on the ruleset's 60-minute status-check timeout instead. So
      # these contexts could not be required while the filter lived on the
      # trigger, which is the second half of the #3523 P0 (#3509 measured a
      # docs-only PR starting zero of them).
      #
      # The filter therefore moved from the trigger into the job: the job always
      # runs and always reports, and the paths decide only whether the expensive
      # steps execute. This is the shape the `docs` job below has used since
      # #3450 — `should_run` plus a per-step `if:` — not a new mechanism.
      #
      # The exclusion list below IS the `paths-ignore` it replaced, unchanged,
      # so which pull requests pay for a full run is exactly as before. The
      # `push` trigger keeps its `paths-ignore`: branch protection and the merge
      # queue judge pull requests and queue builds, never pushes to `main`, so
      # filtering the push lane at the trigger costs nothing there and saves a
      # full run on every docs merge.
      #
      # A failure inside this step means RUN, never SKIP. objectstack#4928 named
      # that the filter contract, after a filter job that skipped when it could
      # not tell produced a fully green, zero-gate pull request. Every gate in
      # this workflow is spelled that way — including the `docs` job below, whose
      # capture swallowed its own failure into an empty result until
      # objectui#3723. `scripts/__tests__/merge-queue-reporting.test.ts` holds
      # every `CHANGED=$(git diff …)` in this file and in `lint.yml` to the
      # fail-open form, so a new gate cannot be added in the closed spelling.
      #
      # ⛔ This job has NO markdown second stage, and objectui#9241 measured
      # what that costs rather than asserting it away: traced under the `fs`
      # harness objectui#9096 built, this job's population DOES open markdown --
      # `pnpm check:spec-symbols` reads every page under `content/docs/**`,
      # which the pathspec below excludes. ⇒ a documentation-only pull request
      # skips the gate that reads that documentation. The reading, and the fence
      # around acting on it, are on the `test` job's decide step below; the
      # widening is objectui#9241's to grade, ⛔ not a thing to add here on
      # sight.
      - name: Decide whether this change needs a full run
        id: relevant
        run: |
          if [ "${{ github.event_name }}" != 'pull_request' ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Not a pull request: push is filtered at the trigger, and a merge_group build is the last validation before main. Running everything.'
            exit 0
          fi
          if ! CHANGED=$(git diff --name-only \
            '${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}' -- \
            . \
            ':(exclude,glob)**/*.md' \
            ':(exclude,glob)content/**' \
            ':(exclude,glob)docs/**' \
            ':(exclude,glob)apps/site/**' \
            ':(exclude,glob).changeset/**'); then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Could not diff against the merge base. Running everything rather than skipping silently.'
            exit 0
          fi
          if [ -n "$CHANGED" ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo "$CHANGED"
          else
            echo 'should_run=false' >> "$GITHUB_OUTPUT"
            echo 'Only ignored paths changed. Skipping the steps below; this check still reports.'
          fi

      - name: Enable Corepack and download the pinned pnpm
        if: steps.relevant.outputs.should_run == 'true'
        run: bash scripts/ci-setup-pnpm.sh

      - name: Verify pnpm version
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm --version

      - name: Setup Node.js
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/setup-node@v7
        with:
          node-version: '22.x'
          cache: 'pnpm'

      # Every package must be either type-checked or explicitly declared as a
      # known gap. Runs before install: it only reads package.json files.
      - name: Verify type-check coverage
        if: steps.relevant.outputs.should_run == 'true'
        run: node scripts/check-type-check-coverage.mjs

      # objectui#12957: every @objectstack/* package resolves to the build of the
      # commit `.objectstack-sha` pins, read from node_modules/.cache/objectstack, so
      # it must be there before pnpm resolves anything. Restored by the pin and built
      # only on a miss (scripts/objectstack-pin.mjs); the save is this job's last step.
      - name: Restore the pinned @objectstack build
        id: objectstack-pin
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/cache/restore@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

      - name: Build @objectstack at the pin (skips a restored build)
        id: objectstack-build
        if: steps.relevant.outputs.should_run == 'true'
        run: node scripts/objectstack-pin.mjs build

      - name: Install dependencies
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm install --frozen-lockfile

      # A bare specifier RESOLVING from a package directory does not mean that
      # package declares it: the workspace root's `devDependencies` sit on the
      # upward resolution path from everywhere, and on no consumer's. So
      # `require.resolve('react', { paths: ['packages/core/src'] })` succeeds
      # although `@object-ui/core` declares react in no field at all
      # (objectui#4394), and a react import added there would typecheck, build
      # and pass every local suite before breaking the published package for the
      # first consumer without React installed. This gate asks the question root
      # hoisting cannot answer for anyone — is it DECLARED — and its first full
      # run found a live instance: `@object-ui/plugin-detail` shipping a bare
      # `react-router-dom` import its manifest never mentioned. Same placement
      # rationale as the steps below: it parses the sources with `typescript` and
      # reads every package.json, so it needs the install but nothing built.
      - name: Verify every imported package is declared by the package that ships it
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:phantom-deps

      # A file inside a package that names its OWN package resolves through that
      # package's `exports` map to `dist/`, and `type-check` waits on `^build`
      # (the DEPENDENCIES' builds), never on the package's own — so on a cold
      # cache the declarations do not exist and the file fails with TS2307. It is
      # green on every machine that has ever run a build, which makes CI the only
      # place it can be seen: PR #4789's first run was red on exactly this, one
      # line in `packages/fields/src` (objectui#4801). Parses sources with
      # `typescript` through the sibling gate's scanner, so it needs the install
      # and nothing built — same placement rationale as the step above.
      - name: Verify no package imports itself by name
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:self-import

      # A source file nothing imports and nothing exports sits in a PUBLISHED
      # package indefinitely: `check-dist-completeness` asks whether `dist/` holds
      # what `tsc` emits, `check-readme-exports` compares documented exports
      # against shipped ones, and neither can see a file that is in the tarball
      # while being reachable from nothing. Both instances found this week —
      # objectui#7319 and objectui#7397 — were found by a human reading unrelated
      # code, which is the detection mechanism this replaces. The hazard is not
      # the bytes: the file objectui#7319 removed carried the same export name as
      # a live engine one package over and evaluated no predicate, so
      # name-completion alone could have wired a silently wrong renderer into a
      # published package (objectui#7515).
      #
      # Reachability here has TWO roots. `packages/components` reaches two live
      # files — the `use-sync-external-store` shims — only through
      # `vite.config.ts` `resolve.alias`, whose importer is a bundled dependency
      # no source file names; a walk that skips that leg reports exactly those two
      # as dead on its first run, and a gate that cries wolf on live files gets
      # switched off rather than fixed. Scope is DECLARED per package and the
      # uncovered remainder is printed as a derived count on every run, because
      # the alias mechanisms differ per package and a gate that covers one
      # correctly beats one that covers forty with false positives.
      #
      # Parses sources with `typescript` through the sibling gate's scanner and
      # reads build configs as text, so it needs the install and nothing built —
      # same placement rationale as the two steps above.
      - name: Verify no covered package ships a source file nothing reaches
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:unreferenced-sources

      # A JSDoc `@example` on an exported hook is not decoration: call sites copy it.
      # When the ruling the example encoded moves, the prose stays, and every later
      # copy is seeded from the prose rather than from the code — so fixing the call
      # sites without fixing the doc comment re-seeds them. That class cost two cards
      # and three copied call sites (objectui#7627, objectui#7638) with nothing in CI
      # able to see it; objectui#7617's `check-spec-symbol-derivation` was cited as
      # covering it twice and does not — its rule 4 judges `@objectstack/spec`
      # citations at member granularity and has nothing to say about prose that
      # prescribes a LOCAL spelling.
      #
      # This step fails only when a documented symbol's own `@example` hand-spells
      # what its real call sites obtain by CALLING a shared reader. Parses sources
      # with `typescript` through the same scanner as the two steps above, so it
      # needs the install and nothing built.
      - name: Verify no doc comment prescribes a spelling a shared reader owns
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:doc-example-readers

      # `BaseSchema` is `.passthrough()`, so an `on*` key that is not declared by
      # its arm is NOT refused — it stops being judged and the value is KEPT, then
      # reaches the renderer that reads it. objectui#7664 measured that on the built
      # dist: `{ type: 'kanban', columns: [], onCardClick: { action: 'toast' } }`
      # went from REFUSED to ACCEPTED with the object surviving into the parsed
      # output, while every gate here stayed green. The objectui#6124 ledger could
      # not see it — its population is two hand-written arrays, and that change
      # re-keyed the arm by SUBSTITUTION, holding the length constant — so a count
      # ratchet would have been green too (objectui#7753 rejected that option on
      # exactly this measurement).
      #
      # This step derives BOTH populations instead: the arms from every
      # `type: z.literal(…)` in `packages/types/src/zod`, and the read sites from
      # every real `ComponentRegistry.register(…)` call, following the document
      # into the components each registration hands it to. It has to live in
      # `scripts/` because the read sites are spread across `@object-ui/plugin-*`
      # and `packages/components`, which `@object-ui/types` may not import —
      # `check:phantom-deps` rejects it and it would close a cycle. Parses sources
      # with `typescript` through the same scanner as the steps above, so it needs
      # the install and nothing built.
      - name: Verify every handler key a registered renderer reads is declared by its arm
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:handler-key-reads

      # objectui#7714 ruled one client behaviour and its PR implemented that ruling
      # by ENUMERATING the writers it knew of. Two. objectui#8057 hit the same
      # defect on a third in that card's own required dogfood, and objectui#8676's
      # sweep found nine more — and, the half that outlives the count, the sweep
      # shape the question is naturally asked in (`client.save(`) CANNOT SEE them:
      # it returns zero over the very file objectui#8057 is about, because the call
      # is `client.save<any>(type, ...)`. A hand list of writers is stale the next
      # time somebody adds one, and nothing says so.
      #
      # So this step enumerates DOORS, not writers. The writer set is open and
      # nobody has to announce a new member; the transport set is closed and this
      # repo owns it. It derives every call that PUTs `/meta/:type/:name` —
      # resolving the URL through templates, fields and helper returns, because
      # the central door says nothing at its own call site — and requires each one
      # that can carry an object document to reach the guard. Parses sources with
      # `typescript`, so it needs the install and nothing built.
      - name: Verify every object-metadata write door applies the write guard
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:metadata-write-doors

      # A build tsconfig that excludes tooling by FILE NAME (`*.test.ts`) stops
      # the files that happen to be named that way and nothing else. The first
      # shared helper added to a `__tests__/` directory is then a program input,
      # and an emitting program writes it into the published `dist`. That has
      # happened three times — objectui#4006 (73 `*.test.d.ts` across two
      # packages), objectui#4836 (9 more, one of them an emitted module whose
      # first statement imports `vitest`) and objectui#6943 (the same package as
      # the first, because that fix wrote the name form) — and every one was
      # found by a human, never by a gate. objectui#7212 measured the standing
      # exposure: 29 published packages carried the name form with ZERO offending
      # files, green because nobody had added such a helper yet. This gate reads
      # `exclude` ARRAYS only: no build, no artifact, no emit model, which is what
      # keeps it clear of the modelling objectui#4846 declined for the
      # artifact-level gate. That gate stays as the second line of defence — it
      # is the only criterion that cannot be wrong about what actually ships, and
      # it lives in `published-dist-gate.yml` because it needs a full-repo build.
      # Its runnable alias is deliberately NOT named anywhere in this file:
      # `check-published-dist-tooling.test.ts` asserts by substring that no
      # per-PR workflow mentions it, which is how the ruling that kept a
      # full-repo build off the PR path is held — prose naming it would read the
      # same to that scan as a step running it. Config
      # reads plus the sibling gate's `typescript`-importing scanner, so it needs
      # the install and nothing built, same as the two steps above.
      - name: Verify published build tsconfigs exclude tooling DIRECTORIES, not just names
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:published-tsconfig-exclude

      # `sideEffects` is a PUBLISHED CONTRACT, and an ARRAY form of it fails in
      # the one direction nothing can witness: an INCOMPLETE array drops a
      # registration inside a CONSUMER's bundle, with no error, no warning and
      # exit 0 — the same failure mode as `"sideEffects": false`, only quieter.
      # `@object-ui/app-shell` declares one because both simpler answers are
      # measurably wrong for it (objectui#6683; `false` drops three live SDUI
      # widget registrations, measured in objectui#6535). This gate re-derives
      # the enumeration from the module bodies and fails when the array and the
      # derivation disagree in EITHER direction — a missing registrar, or a
      # stale name whose module no longer registers anything.
      #
      # Placed here rather than with the build steps for the same reason as the
      # two above: it parses sources with `typescript` and reads package
      # manifests, so it needs the install and nothing built. The artifact half
      # of the same contract — do the registrations survive a real bundler —
      # cannot run here at all and lives in `performance-budget.yml`, which
      # builds the console.
      - name: Verify every `sideEffects` array names exactly its registering modules
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:side-effects-array

      # A block that WRAPS `ElementDataSourceGate` reads the spec's
      # `PageComponentSchema.dataSource`; the input declaration for that key is
      # emitted mechanically at the wrapping seam (`elementDataSourceBlock` ->
      # `Registry.register`), per the maintainer ruling of 2026-08-29, so no
      # block hand-writes it. This gate is the other half of "and cannot forget
      # it": a file that starts rendering the gate without reaching the seam
      # would publish an authoring surface missing the one key its own runtime
      # honours, and the html tier would go back to reporting the only spelling
      # that works as `unknown-prop` (objectui#6678). Source-only — it needs the
      # install and nothing built.
      - name: Verify every ElementDataSourceGate wrapper reaches the declaration seam
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:element-data-source-declaration

      # Node's ESM resolver does not extension-search relative specifiers, so an
      # extensionless `./SchemaRenderer` in a published `dist/` is unloadable
      # under plain Node — `@object-ui/react`'s entry died with
      # ERR_MODULE_NOT_FOUND (objectui#4538). `tsc` never rewrites specifiers, so
      # for a package whose build preserves them the SOURCE specifier is the
      # emitted one, and the defect can be judged without building anything.
      # That is why the cheap leg runs here: it reads sources, needs only the
      # install, and catches a regression the moment it is written.
      #
      # The expensive leg — which BUILDS and actually imports each published
      # entry — is `.github/workflows/node-esm-load-gate.yml`. It is not here on
      # purpose: it needs a full-repo build, which this repository deliberately
      # does not do per pull request (the same trade `published-dist-gate.yml`
      # records at length).
      - name: Verify published ESM packages emit resolvable relative specifiers
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:esm-specifiers

      # A local type/const declared under a `@objectstack/spec` export's NAME reads
      # to the next agent as the spec's own definition — four such symbols had
      # already drifted from the spec they claimed to be (objectstack#4115). Needs
      # the install (it reads the spec's own `.d.ts`) but not the build, so it runs
      # before the expensive steps.
      - name: Verify spec-named symbols are derived, not hand-written
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:spec-symbols

      # Each action renderer hands the runner an explicit key WHITELIST, so a new
      # spec action key is silently dropped until five separate lists are edited —
      # and nothing fails while they are not: the key parses, publishes and reads
      # as honoured. Six instances were found by hand, one at a time
      # (objectstack#6837 `bodyExtra`, #6938 `bodyShape`, objectui#3646
      # `resultDialog`, objectui#4192 `label`/`description`), which is why
      # objectui#4050's ruling asks for a gate rather than a seventh review. Same
      # placement rationale as the step above: it reads `@objectstack/spec`'s own
      # zod shapes and parses the renderers with `typescript`, so it needs the
      # install but nothing built.
      - name: Verify action renderers forward every key the runtime reads
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:action-forward-parity

      # A field designer offering a control that writes a key `FieldSchema`
      # refuses BY NAME is a save-blocking 422 (`INVALID_METADATA`) that blocks
      # EVERY later save of the object, and the author cannot tell from the UI
      # which key did it. It had been filed three times — objectui#4644
      # `indexed`, #4687 `distance_metric`, #4676 `placeholder` — each closed
      # with a per-key tombstone written AFTER the instance was found in
      # production, and nothing detected the next one (objectui#5761). This gate
      # compares the designers' statically declared payload shapes against the
      # installed `FieldSchema`'s own accept set. Reads sources with `typescript`
      # and the installed spec, so it needs the install and nothing built — same
      # placement rationale as the step above. It covers a documented SUBSET of
      # the write path (keys reaching the payload only via a `patchDef` spread
      # are outside its reach); the boundary is stated in the script's docblock,
      # and its draft-I/O half runs in the test suite as
      # `object-fields-io.spec-keys.test.ts`.
      - name: Verify designer field payloads declare only keys FieldSchema accepts
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:designer-field-key-parity

      # lucide retires a spelling by DROPPING IT FROM the runtime `icons` record
      # while keeping it as a deprecated named export. A retired name therefore
      # still imports, still type-checks and still renders wherever it is used as
      # a COMPONENT (`Edit === SquarePen`, `Filter === Funnel`) — and resolves to
      # nothing wherever it is used as a STRING, because the string lookups read
      # that record. Nothing goes red in either direction, which is why it had to
      # be repaired twice, in two packages, by two cards, each leaving a LOCAL pin
      # behind (objectui#5586, objectui#5622). This gate replaces those pins with
      # one predicate over the population, judged by the record itself and never
      # by a list of retired spellings — a list would age the moment lucide
      # retires the next name, and age silently. It also RE-DISCOVERS the
      # resolvers on every run: its first pass found four record-reading resolvers
      # objectui#5633's hand-built table did not know about. Reads sources with
      # `typescript` and the installed lucide, so it needs the install and nothing
      # built — same placement rationale as the step above.
      - name: Verify authored icon names are live lucide `icons` keys
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:icon-record-names

      # A key a component asks `t()` for must exist in the `en` pack.
      # `all-locales-key-parity.test.ts` compares packs to EACH OTHER, so ten
      # packs identically missing a key is full parity and full parity is green
      # — objectui#3517 lived there for months, and this gate's first full run
      # found 258 more keys in the same blind spot. Same placement rationale as
      # the step above: it imports `typescript` to parse the sources, so it
      # needs the install, but nothing built.
      - name: Verify t() call-site keys exist in the en locale pack
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:i18n-keys

      # The step above and `all-locales-key-parity.test.ts` both read KEYS. When
      # an `en` VALUE changes and the nine translations do not, every key-shaped
      # gate stays green — objectui#3582 and objectui#3625 were eight packs each
      # serving a retired sentence, the second one as idiomatic native-script
      # translations that no mechanical judgement can distinguish from healthy.
      # This gate judges the event instead of the state: `en` changed here, the
      # translations must change here too. Needs the install (it parses the
      # packs with `typescript`) and the `fetch-depth: 0` above (it diffs
      # against the merge base), but nothing built.
      - name: Verify changed en strings were followed by the nine translations
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:i18n-drift

      # The two steps above judge the TEN LOCALE PACKS. The metadata-admin
      # designer keeps its own module-local string tables (~3600 lines of
      # user-visible text in packages/app-shell/src/views/metadata-admin/i18n.ts)
      # and both of them are blind to it BY CONSTRUCTION — measured in
      # objectui#8388 and quoted in the header of the script this step runs. The
      # repo's report-only dead-keys sweep does read that table, but it asks about
      # DEAD keys, its corpus is the UNION of the two halves so a one-sided key is
      # not a subject to it, and it deliberately runs in NO workflow ("This is a
      # REPORT, not a gate" — a pin in its own test suite keeps it out of every
      # workflow file, which is why this comment does not spell its name). So
      # until objectui#8834 an author could add an English string and forget the
      # Chinese one with every gate in this repo green. This step is
      # the state half of that fix — en is a subset of zh, and the shared rows
      # carry the same {placeholders}; the event half (an en VALUE changed and zh
      # did not) is a second population inside check:i18n-drift above. Needs the
      # install (it parses the table with `typescript`) but nothing built, and no
      # git history: it judges one commit.
      - name: Verify the metadata-admin designer string tables stay paired
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm check:i18n-designer-parity

      # `scripts/` is not a workspace package, so `pnpm type-check` (i.e.
      # `turbo run type-check`, which walks package.json `scripts`) structurally
      # cannot reach it, and the coverage guard above decides coverage per
      # PACKAGE so it could not see the gap either. Until objectui#3494 that
      # left every file in `scripts/__tests__/` compiled by nothing — ten pin
      # tests holding this workflow, `docs-links.yml`, `lint.yml` and the
      # changeset guard in place, none of which the compiler had ever read. A
      # pin test that `tsc` never reads can assert a contract that no longer
      # type-checks and still print green (objectui#3181).
      #
      # Placed here, not further down: nothing in tsconfig.scripts.json's
      # program imports an @object-ui/* package, so it needs the install but not
      # the `^build` that `pnpm type-check` depends on — it is cheap and fails
      # fast. `scripts/__tests__/scripts-type-check.test.ts` pins that premise,
      # this step's presence, and its position after the install.
      - name: Type-check scripts/
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm type-check:scripts

      # The repo-root `vitest.config.mts` had no RUNNABLE gate of its own
      # (objectui#7328). A program did already contain it —
      # `apps/console/tsconfig.node.json` lists `../../vitest.config.mts` and
      # `vitest.config.ts` outright (objectui#3476) — but the only thing that
      # ran that program was the console's own `type-check` script, which is
      # `tsc --noEmit && tsc -b tsconfig.node.json --force` behind
      # `turbo run type-check`, whose task dependsOn `^build`. So the cheapest
      # compiler that reads the root Vitest config was reachable only through
      # the most expensive job in the repo, and no local gate union short of a
      # full workspace build could red on it.
      #
      # That is not hypothetical. PR #7291 pushed a conditionally spread `dist`
      # project whose literal `extends: true` widened to `boolean`, degrading
      # the whole `projects` array to `never[]`; every gate the author ran was
      # green and CI reported three errors, two of them at
      # `../../vitest.config.mts`. This step is the same compiler, invoked
      # directly.
      #
      # Placed in the CHEAP half beside `pnpm type-check:scripts`, and for the
      # same measured reason: nothing in this project's program imports an
      # @object-ui/* package (its `@object-ui/*` occurrences are alias-map
      # STRINGS in `vite.config.ts`), so it needs the install and nothing built
      # — 2.0s on a worktree with no `dist/` anywhere.
      # `scripts/__tests__/vitest-config-type-check.test.ts` pins that premise,
      # this step's presence and its position.
      - name: Type-check the root Vitest config
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm type-check:vitest-config

      # ── Cache bookkeeping cannot void a recorded verdict (objectui#6577) ──
      # THE ORDERING, because it is the only thing a future reader needs in
      # order to judge whether this step may be touched: this job's verdict is
      # recorded by the three checking steps below, the last of which is
      # `Type-check repo-root vitest setup files`. EVERYTHING AFTER THAT POINT
      # IS BOOKKEEPING — writing `.turbo/cache` back for the next run. It must
      # never be able to discard an answer the gate has already produced.
      #
      # It could, and once did. On 2026-08-26 the merge-group build of #6571
      # was ejected from the queue with `CI_FAILURE` while every substantive
      # check passed: all 21 real steps of this job succeeded, the gate steps
      # included, and then the runner-generated `Post Turbo Cache` step spent
      # 13m09s (789s) inside the cache upload and was still there when this
      # job's `timeout-minutes: 20` fired at 20m02s. The job went `cancelled`,
      # the merge queue cannot tell `cancelled` from `failure`, and a pull
      # request that had passed was dequeued — 20 minutes of head-of-line
      # blocking for every lane, then a full re-run. Same shape as the
      # objectui#5304 apt block in the `e2e` job below: an unbounded network
      # call whose only backstop was the job ceiling, which converts a
      # transient fault into a CANCELLED check — a gate that reports nothing.
      #
      # A transient, not a property of this workflow: the same job on the same
      # PR head thirteen minutes earlier (job 98190108000) went green in 5m53s
      # and its cache save took ONE SECOND. That 1s is what the bound on the
      # save step at the end of this job is sized against.
      #
      # Why the restore/save SPLIT and not a timeout on a single cache step:
      # combined `actions/cache` declares `main: dist/restore/index.js` plus
      # `post: dist/save/index.js`, so the save is a step the RUNNER generates
      # (`Post Turbo Cache`, step #40 in the incident) — not an authored step,
      # and no workflow syntax attaches `timeout-minutes` or
      # `continue-on-error` to it. Splitting moves the save into the main
      # phase, where both are ordinary documented step keys. The action's own
      # `save-always` deprecation text points at this same split.
      #
      # The restore half is deliberately left UNBOUNDED. A restore stall fails
      # before any verdict exists — a gate that did not run, which is honest —
      # rather than a recorded verdict discarded, and bounding it would force a
      # cold check under this same 20-minute ceiling.
      #
      # ⛔ Raising `timeout-minutes: 20` is not the fix and was ruled out on the
      # card: a larger ceiling only buys a longer hang, still ending in
      # `cancelled`, and lifting a gate's ceiling weakens the gate.
      #
      # ONE restore key, the job's own prefix (objectui#12222). `actions/cache`
      # tries every key on the run's OWN ref before it looks at `main`, and
      # the bare `turbo-<os>-` key this step used to end with matched any job's
      # cache on that ref: on that card's first pull-request run it restored
      # the `docs` job's cache, saved minutes earlier by the same run (about
      # 2 GB, most of it unused), and so never reached `main`'s type-check
      # cache at all. Pull-request and queue runs save nothing now (see the
      # prune step below), so on those refs this key finds nothing and the
      # lookup falls through to `main` -- whose entry the full battery wrote.
      - name: Restore Turbo Cache
        id: turbo-cache
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: turbo-${{ runner.os }}-type-check-${{ github.sha }}
          restore-keys: |
            turbo-${{ runner.os }}-type-check-

      # ── Two speeds for the type gate (objectui#12222, objectstack#22998) ──
      # The same doctrine as the `test` job below. A `pull_request` or
      # `merge_group` run type-checks the FAST SET: the packages the change
      # sits in plus every package that depends on them -- turbo's own
      # `--filter=...[<base>]`, against the PR's base sha or the queue's base
      # sha -- and replays from the restored `.turbo/cache` every one whose
      # hash did not move. `push` to `main` and the hourly `schedule` run the
      # FULL BATTERY: every package, with `TURBO_FORCE` so not one verdict is
      # replayed -- which is also what writes the cache those fast runs read.
      #
      # THE ROOT RULE, because the package graph cannot see a file that sits in
      # no package (measured on objectui#12222: a change to the root
      # tsconfig.json, the root package.json, scripts/vite-*.ts or e2e/
      # selects zero packages). A change to any of these means EVERY package
      # is affected, and the fast run becomes a whole-workspace run:
      #   - pnpm-lock.yaml, pnpm-workspace.yaml, the root package.json,
      #     turbo.json, .npmrc, a root tsconfig*.json, anything in patches/;
      #   - every `$TURBO_ROOT$` input of turbo's `type-check` and `build`
      #     tasks (the scripts and root files those tasks' inputs name);
      #   - every `globalDependencies` entry;
      #   - the inputs of every root task `type-check` dependsOn (the e2e
      #     program), which runs only as a dependency of a selected package.
      # The last three are read out of turbo.json on every run by
      # `scripts/select-type-check-scope.mjs`, never copied: the rule follows
      # the file turbo hashes from. A selector that cannot decide -- no base
      # sha, a base git cannot resolve, a turbo dry run that fails -- means the
      # whole workspace, never a skip. Nothing is skipped or weakened: a
      # package the fast set leaves out is one the change cannot reach through
      # the package graph or a turbo input, and the full battery on `main`
      # re-derives every verdict within the hour.
      - name: Decide which packages to type-check
        id: tc-scope
        if: steps.relevant.outputs.should_run == 'true'
        env:
          EVENT: ${{ github.event_name }}
          PR_BASE: ${{ github.event.pull_request.base.sha }}
          QUEUE_BASE: ${{ github.event.merge_group.base_sha }}
        run: |
          case "$EVENT" in
            pull_request) base="$PR_BASE" ;;
            merge_group) base="$QUEUE_BASE" ;;
            *)
              echo 'scope=full' >> "$GITHUB_OUTPUT"
              echo "A $EVENT run is the full battery: every package type-checked, no verdict replayed."
              exit 0
              ;;
          esac
          status=0
          if [ -z "$base" ]; then
            echo "::warning::no base sha on this $EVENT event; type-checking the whole workspace rather than guessing."
            status=2
          else
            node scripts/select-type-check-scope.mjs --base "$base" > "$RUNNER_TEMP/tc-scope.out" || status=$?
            cat "$RUNNER_TEMP/tc-scope.out"
          fi
          verdict=''
          if [ "$status" -eq 0 ]; then
            verdict=$(tail -n 1 "$RUNNER_TEMP/tc-scope.out")
          fi
          case "$verdict" in
            scope=affected)
              echo 'scope=affected' >> "$GITHUB_OUTPUT"
              echo "base=$base" >> "$GITHUB_OUTPUT"
              ;;
            scope=workspace)
              echo 'scope=workspace' >> "$GITHUB_OUTPUT"
              ;;
            *)
              echo "::warning::the type-check scope selector reached no verdict (exit $status); type-checking the whole workspace rather than skipping silently."
              echo 'scope=workspace' >> "$GITHUB_OUTPUT"
              ;;
          esac

      # `type-check` dependsOn `^build`, so this builds workspace dependencies
      # first: the checked packages resolve their deps through built `.d.ts`.
      #
      # `TURBO_RUN_SUMMARY` makes turbo write its run summary to `.turbo/runs/`
      # -- per task, the hash, the cache status and the tasks it depends on. It
      # changes nothing turbo runs or caches; `Report what the turbo cache
      # replayed` below reads it (objectui#12222). `TURBO_FORCE` is the string
      # `true` on the full battery only; turbo reads `false` as not forced.
      - name: Run type-check
        if: steps.relevant.outputs.should_run == 'true'
        env:
          TURBO_RUN_SUMMARY: 'true'
          TURBO_FORCE: ${{ steps.tc-scope.outputs.scope == 'full' }}
          SCOPE: ${{ steps.tc-scope.outputs.scope }}
          BASE: ${{ steps.tc-scope.outputs.base }}
        run: |
          if [ "$SCOPE" = 'affected' ]; then
            pnpm type-check "--filter=...[$BASE]"
          else
            pnpm type-check
          fi

      # ── The repo-root programs' packages, built on the fast speed (objectui#12272) ──
      # `Type-check repo-root vitest setup files` below resolves the workspace
      # packages the root `vitest.setup.*` files import through their BUILT
      # declarations. The full battery and the whole-workspace run build every
      # one of them as the `^build` of the packages that depend on them; the
      # affected run builds only the dependencies of what it selects, and that
      # may hold none of them -- a change outside every package selects ZERO
      # packages, so nothing built and that step failed with four TS2882 and a
      # TS2307 (PR #12262; and a change to `packages/plugin-ai` alone selects
      # one package and still leaves three of them unbuilt -- both measured on
      # objectui#12272, readings of that day, not live counts). So this
      # speed builds them here, whatever it selected. Which packages is read
      # on every run out of that program's tsconfig `paths` by the selector,
      # never copied. `turbo run build` replays each from the restored cache
      # when its hash did not move; it is not `turbo run type-check` with
      # their names added, because that task waits on `^build` -- the
      # DEPENDENCIES' builds -- and builds no named package's own (measured:
      # that spelling leaves `plugin-dashboard` and `plugin-grid` unbuilt).
      # No run summary is asked for here, so `Report what the turbo cache
      # replayed` still reads `Run type-check`'s; turbo's own `Cached:` line
      # goes out as a notice instead, so the replay stays readable to anyone
      # who cannot open this log. `push` and `schedule` skip this step: the
      # full battery is unchanged.
      - name: Build the packages the repo-root programs import
        if: >-
          steps.relevant.outputs.should_run == 'true'
          && steps.tc-scope.outputs.scope == 'affected'
        run: |
          set -o pipefail
          packages=$(node scripts/select-type-check-scope.mjs --root-builds)
          filters=()
          for p in $packages; do filters+=("--filter=$p"); done
          if [ "${#filters[@]}" -eq 0 ]; then
            echo 'The repo-root programs import no workspace package: nothing to build.'
            exit 0
          fi
          pnpm exec turbo run build "${filters[@]}" | tee "$RUNNER_TEMP/root-builds.out"
          cached=$(grep -E '^ *Cached:' "$RUNNER_TEMP/root-builds.out" | tail -n 1 | tr -s ' ' || true)
          echo "::notice title=Repo-root program builds::$(echo $packages) -- ${cached:-turbo printed no Cached line}"

      # The four repo-root `vitest.setup.*` files were in ZERO tsc programs
      # (objectui#3515) — the same shape as `scripts/` before objectui#3494, one
      # directory over. They live outside every workspace package, so
      # `pnpm type-check` above cannot reach them; the root `tsconfig.json`
      # includes only packages/examples/apps; and no consumer IMPORTS them (every
      # one names them as a Vitest `setupFiles` runtime path string), so no gated
      # program pulls them in transitively either.
      #
      # Placed after `pnpm type-check`, NOT next to `pnpm type-check:scripts`
      # above, and the difference is load-bearing. `tsconfig.scripts.json`'s
      # program imports no workspace package, so it can run straight after the
      # install; this one must, because `vitest.setup.dom.tsx` side-effect-imports
      # @object-ui/components, /fields, /plugin-dashboard and /plugin-grid for
      # their registrations. `tsconfig.vitest-setup.json` resolves those through
      # each package's own `exports.types`, i.e. its built declarations — which
      # exist only after the `^build` that `pnpm type-check` depends on, and on
      # the affected speed after the step above (objectui#12272).
      # `scripts/__tests__/vitest-setup-type-check.test.ts` pins that ordering,
      # `scripts/__tests__/select-type-check-scope.test.ts` the step above.
      #
      # A direct step, deliberately: this is not a turbo task, so no cache key
      # decides its verdict. `pnpm type-check` is cached by turbo and its `inputs`
      # would have to hash every root file a program reads (the objectui#3513
      # lesson); running this one directly sidesteps that class of half-armed
      # gate entirely, exactly as `type-check:scripts` does.
      - name: Type-check repo-root vitest setup files
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm type-check:vitest-setup

      # ── What the cache replayed (objectui#12222) ─────────────────────────
      # Bookkeeping, like the save below: it runs after the last checking step,
      # so it can neither delay nor change the verdict, and it is bounded and
      # `continue-on-error` for the reason the save is. It reads the run summary
      # `Run type-check` asked turbo for and prints, per task, what the
      # restored cache replayed and what re-ran -- each re-run task with the
      # tasks it depends on, because a task's hash folds theirs in, so the
      # dependency that moved every package's hash is named in the log. The
      # counts also go out as ONE `::notice` annotation: the check-runs API
      # serves annotations to readers who cannot open this log, so "the cache
      # replayed what the change did not touch" stays a thing anyone can
      # re-read on any run, never a figure written down once (AGENTS.md #9).
      # `!cancelled()` so a red type-check still reports what it replayed.
      - name: Report what the turbo cache replayed
        if: steps.relevant.outputs.should_run == 'true' && !cancelled()
        timeout-minutes: 2
        continue-on-error: true
        env:
          RESTORED_CACHE_KEY: ${{ steps.turbo-cache.outputs.cache-matched-key }}
        run: node scripts/report-turbo-cache.mjs

      # ── Only the full battery writes this cache, and only what it used ──
      # Measured on objectui#12222's first pull-request run: the cache it
      # restored (another job's, through the bare restore key the restore step
      # above no longer has) held 401 entries, about 2 GB, 321 of them unused
      # by the run -- and this job saved all of it again under its own key, on
      # every pull request, queue build and push. A store full of multi-GB
      # entries is one a size-limited cache store evicts (the eviction itself
      # is not readable from a seat's container: the cache API is refused
      # there). So the type-check cache is written by the full battery only
      # -- `push` and `schedule`, whose forced run covers every task -- and
      # this step first deletes every entry that run did not use, so `main`'s
      # entry is exactly the current verdicts and build outputs, the one every
      # pull request and queue build restores. Pull-request and queue runs
      # restore and never save. Bookkeeping like the save: bounded,
      # `continue-on-error`, after the last checking step;
      # `scripts/report-turbo-cache.mjs` refuses to prune on a summary that
      # lists no task.
      - name: Prune the turbo cache to what this run used
        if: >-
          steps.relevant.outputs.should_run == 'true'
          && (github.event_name == 'push' || github.event_name == 'schedule')
        timeout-minutes: 2
        continue-on-error: true
        run: node scripts/report-turbo-cache.mjs --prune

      # The bookkeeping half of the split documented at the restore step above,
      # placed HERE — after the last checking step — because that is exactly
      # where the post phase it replaces already ran. Nothing about which
      # commits this job accepts or rejects moves with it.
      #
      # `timeout-minutes: 5` is the bound the incident asked for: 300x the 1s a
      # healthy save of this cache measured, so it cannot fire on a working
      # runner, and even measured from the slowest verdict path on record
      # (6m53s, the incident run) it lands roughly eight minutes clear of this
      # job's 20-minute ceiling — this step can no longer reach that ceiling.
      #
      # `continue-on-error: true` is the other half, and without it the bound
      # would only trade a `cancelled` gate for a red one. A cache that failed
      # to upload costs the next run some time; it says nothing whatsoever
      # about the code under test, so it must not be allowed to speak for it.
      #
      # Behaviour preserved, spelled out so the equivalence is checkable:
      #   - `cache-hit != 'true'` reproduces the combined action's own "exact
      #     hit on the primary key ⇒ do not save" skip.
      #   - the condition names no status function, so the implicit `success()`
      #     still applies — matching the combined action's `post-if: success()`.
      #   - same `path` and same `key` as the restore step above.
      # One deliberate change (objectui#12222): only `push` and `schedule`
      # save, after the prune step above; see there for why.
      - name: Save Turbo Cache
        if: >-
          steps.relevant.outputs.should_run == 'true'
          && steps.turbo-cache.outputs.cache-hit != 'true'
          && (github.event_name == 'push' || github.event_name == 'schedule')
        uses: actions/cache/save@v6
        timeout-minutes: 5
        continue-on-error: true
        with:
          path: .turbo/cache
          key: turbo-${{ runner.os }}-type-check-${{ github.sha }}

      # The pinned @objectstack build, saved only when this job built it (a cache
      # miss) and whatever the verdict above was -- it does not depend on it.
      # Bookkeeping: bounded and non-fatal (objectui#6577, objectui#7048). The bound
      # is not yet derived from a measured save; re-derive it from this step's runs.
      - name: Save the pinned @objectstack build
        if: ${{ !cancelled() && steps.relevant.outputs.should_run == 'true' && steps.objectstack-build.outcome == 'success' && steps.objectstack-pin.outputs.cache-hit != 'true' }}
        continue-on-error: true
        timeout-minutes: 2
        uses: actions/cache/save@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

  # PRs run the suite split across the runners of the `shard:` matrix below.
  # The suite is dominated by fixed per-file cost rather than by the
  # assertions: a PR run reported 495s wall
  # clock of which only 178s was `tests` — the rest was `setup` (831s
  # cumulative), `import` (199s) and `environment` (156s), each paid once per
  # test file because `isolate: true` re-executes the module graph per file
  # (vitest.config.mts explains why isolation has to stay on). That cost shards
  # near-linearly, and the fixed overhead of an extra runner here is only ~30s
  # (checkout + Node + a warm-pnpm-store install), so 4 shards cut wall clock
  # ~3x for ~26% more runner minutes.
  #
  # ⭐ 4 -> 8 (objectui#9499). At four shards this job had grown into its own
  # `timeout-minutes: 20`. Measured on the card over the 14 most recent
  # `merge_group` runs and the 14 most recent `pull_request` runs: the longest
  # SUCCEEDING shard-1 job was 1199 s against the 1200 s ceiling -- a ONE-SECOND
  # margin -- and two runs crossed it and were CANCELLED, one of them dequeuing
  # a pull request whose tests had already passed, because the merge queue
  # cannot tell `cancelled` from `failure`.
  #
  # ⛔ The ceiling is NOT raised (see `:641`, which ruled that out), ⛔ no test
  # is skipped, disabled or quarantined, and ⛔ the relevance gate is not
  # widened. The work is spread over twice the runners instead, and the one
  # step in this job that was never sharded at all -- the built-artifact pin
  # lane, which ran on shard 1 only and is what pushed the longest shard over --
  # moved out into `test-dist-pins` below.
  #
  # Doubling the matrix is only possible because the required-check set no
  # longer names the legs: `test-aggregate` below is the single required `Test`
  # context, so the width here is an ordinary workflow edit rather than a
  # repository-settings change that renames four live required contexts.
  #
  # ⭐ 8 -> 12 (objectui#12208, PR-1; ruling 6121816480, letter B). At eight
  # shards the job was back against the same `timeout-minutes: 20`: measured
  # on that card over the 1,728 shard jobs of the trailing seven days, the
  # shard wall sat at 14.4 min median, 17.4 min p95 and 20.3 min max. Same
  # remedy, same three refusals: ⛔ the ceiling is NOT raised, ⛔ no test is
  # skipped, and ⛔ the relevance gate is not widened -- the work is spread
  # over half again as many runners. Duration-balanced sharding is that
  # card's second pull request, not this edit. The width is one number on
  # both speeds (objectui#12214): the affected run on a pull request or queue
  # build and the full battery on `push` and `schedule` both use these same
  # legs, so `test-aggregate`'s `--shards` has one value to agree with.
  #
  # ⭐ Duration-balanced (objectui#12208, the same ruling's second pull
  # request). Vitest's own split hashed each file's path and cut the list into
  # equal FILE COUNTS, so which leg drew the heavy files was luck, and the
  # lucky-heavy leg is the one the cap cancels. The note on the `Run tests`
  # step below says what replaced it; `test-aggregate` prints the longest leg's
  # headroom on every run.
  #
  # ⭐ 12 -> 16 (objectui#12384; the same ruling's width rule, "the width
  # derived from the total measured duration at a target of about 10 minutes
  # per shard"). Balanced, the twelve legs were no longer heavy -- measured on
  # that card over the 50 hours after the balanced plan landed, 11.3 min
  # median and 12.6 min p99 per finished leg -- but the runners under them
  # were not all equally fast: the cap cancelled legs in 12 of the 279 runs
  # that ran tests, with no hang, every file on those VMs running 1.6x to 2.0x
  # slower than the same files on a normal one, episodically (13 of the 16
  # cancelled legs fell on one afternoon, 2026-10-14) and with no runner label
  # that tells such a VM apart. Twelve legs left a p99 leg 1.59x (20 / 12.6)
  # of slack, below that factor; sixteen legs carry 0.75 of the load each,
  # which moves the break-even slow factor to about 2.1x. The same three
  # refusals hold: ⛔ the ceiling is NOT raised, ⛔ no test is skipped, and ⛔
  # the relevance gate is not widened. A runner pin was not taken: there was
  # no measured runner class to pin. Whether the width still fits is
  # `test-aggregate`'s headroom reading on every run, not this comment.
  test:
    name: Test (shard ${{ matrix.shard }}/16)
    # Coverage instrumentation (v8 adds 40-100% overhead) is skipped on PRs;
    # the `test-coverage` job below runs the coverage lane on push.
    #
    # Written as "not push" rather than "is pull_request" (objectui#3523): the
    # third event this workflow now sees is `merge_group`, and a queue build
    # that runs no tests is the hole this repository just paid for. `push` is
    # still excluded because the coverage lane below is the push lane: it is
    # sharded of its own since objectui#5403 (4 ways, 8 since objectui#12256) --
    # ⛔ INDEPENDENTLY of the matrix above, which objectui#9499 widened to 8,
    # objectui#12208 to 12 and objectui#12384 to 16 without touching it: the
    # two lanes declare their own
    # `shard:` matrix and their own `--shard=N/M`, and the coverage blobs are
    # named `blob-N-M.json` by the coverage job's own flag -- and its
    # `coverage-report` job merges every shard's blob report into ONE complete
    # report, which is where the coverage thresholds are enforced (and, since
    # objectui#5436, where the report is published as an artifact rather than
    # uploaded to Codecov). PR and push behaviour is unchanged — only the
    # previously impossible third case moves.
    #
    # ⭐ Two speeds (objectui#12214): the event guard that kept this matrix off
    # `push` is GONE. Every event runs it now, at one of two speeds: on
    # `pull_request` and `merge_group` the `Select the tests this change
    # affects` step below narrows each shard to the affected set; on `push` and
    # `schedule` it is the whole suite, beside the coverage lane. The width
    # is the same on both speeds, so `test-aggregate` keeps one `--shards` and
    # still refuses a partial set.
    runs-on: ubuntu-latest
    # Bound the job so a stalled runner / non-exiting test worker fails fast and
    # is retryable, instead of hanging up to GitHub's 6h default.
    timeout-minutes: 20

    strategy:
      # Report every shard's failures, not just the first one to break.
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]

    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          submodules: true
          # `fetch-depth: 0` for the gate step below (objectui#3523): it diffs
          # against the merge base, which a depth-1 clone cannot resolve.
          fetch-depth: 0

      # Always report; run only when it matters — see the full note on the
      # `type-check` job above (objectui#3523). The exclusion list must stay
      # identical across the gated jobs of this workflow;
      # `scripts/__tests__/merge-queue-reporting.test.ts` fails if it drifts.
      - name: Decide whether this change needs a full run
        id: relevant
        run: |
          if [ "${{ github.event_name }}" != 'pull_request' ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Not a pull request: push is filtered at the trigger, and a merge_group build is the last validation before main. Running everything.'
            exit 0
          fi
          if ! CHANGED=$(git diff --name-only \
            '${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}' -- \
            . \
            ':(exclude,glob)**/*.md' \
            ':(exclude,glob)content/**' \
            ':(exclude,glob)docs/**' \
            ':(exclude,glob)apps/site/**' \
            ':(exclude,glob).changeset/**'); then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Could not diff against the merge base. Running everything rather than skipping silently.'
            exit 0
          fi
          if [ -n "$CHANGED" ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo "$CHANGED"
            exit 0
          fi
          # Everything that changed is on the exclusion list above, and for the
          # `type-check` and `e2e` jobs that is the end of it. It is not the end
          # of it HERE, and objectui#8857 paid for the difference: a markdown
          # document can be a TEST'S INPUT. That pull request changed exactly one
          # file, `packages/plugin-dashboard/README.md`; the test that reads that
          # README extracts its fences and evaluates them. `Test (shard 1/4)`
          # reported success on the pull request page in ten seconds having run
          # nothing, the merge_group build then failed the same shard in 907
          # seconds, and the pull request was dequeued. The queue did its job;
          # the cost is that the signal arrived after review had concluded on a
          # green page.
          #
          # So this job asks one more question of the markdown the exclusions
          # above dropped: does a test READ it? `markdown-test-inputs.mjs` holds
          # the derived class -- which documents, and which test reads each --
          # and audits itself against the tree. Only THIS job carries the extra
          # stage.
          #
          # ⚠️ objectui#9241: the reason that used to stand here was an
          # ASSERTION -- "only this job runs the tests that read markdown
          # (measured: `type-check` reads no document, and no e2e spec does)".
          # Nothing had measured it. Both populations have now been run under
          # the same `fs` trace objectui#9096 used -- every `readFileSync` /
          # `openSync` / `promises.readFile` door recorded, the opened markdown
          # written out -- and the two answers differ:
          #
          #   e2e         ZERO. That job's Playwright suite opens no markdown
          #               document at all. Stable across two runs, and in a run
          #               of the same suite the same harness -- extension filter
          #               moved off `.md` -- recorded reads from inside the
          #               Playwright worker process, so the zero is a reading
          #               and not a harness that never fired. ⚠️ The bound on
          #               it: 23 of that job's 46 tests skip for want of a docs
          #               site and a backend, in CI exactly as when this was
          #               taken (`DOCS_BASE_URL` is set nowhere in this file and
          #               that job starts no backend), so their bodies are
          #               outside the reading. Static complement: no spec under
          #               `e2e/` outside `record-header-title-width.spec.ts`
          #               names `node:fs` at all, and that one ran.
          #   type-check  ⛔ NOT zero. Its `check:spec-symbols` gate reads EVERY
          #               page under `content/docs/**` -- objectui#7995 widened
          #               that gate onto published prose deliberately, after a
          #               wrong spec claim shipped in
          #               `content/docs/fields/lookup.mdx` (objectui#7537).
          #               Those pages are excluded by the very pathspec above,
          #               so a documentation-only pull request skips the gate
          #               whose input it just edited -- the objectui#8857 shape,
          #               one job over.
          #
          # ⛔ The second reading is a FINDING, not a licence to widen anything
          # here: objectui#9241 returns it for re-grading before a markdown
          # stage is wired into `type-check`, and this job's stage is unchanged
          # by it. Both readings are a SNAPSHOT -- re-take them with the trace,
          # do not trust this block.
          #
          # ⚠️ objectui#9096: that class is now TOTAL over markdown, and this
          # comment used to claim the opposite ("the widening is deliberately
          # narrow"). `scripts` joined the scan roots, and the gate tests under
          # `scripts/__tests__` read the documentation the way the product tests
          # read a README -- measured by running all 46 of them under an fs
          # trace, 1805 of 1805 tracked markdown files are opened by at least
          # one of them. ⇒ for THIS job, the markdown half of the exclusion list
          # above is now inert: any markdown-only pull request runs the shards.
          # Priced over the 513 first-parent commits available at the time: 36
          # reached this stage, 21 already ran, and the widening moves 14 of the
          # remaining 15 from skip to run -- 2.7pp of merges.
          #
          # ⛔ The rest of the exclusion list is NOT inert and must stay: a
          # non-markdown change under `content/**`, `docs/**` or `apps/site/**`
          # still skips. `8011852dc` is the live instance -- a site-only change
          # carrying no markdown, which skipped then and skips now.
          #
          # Same failure posture as the diff above -- a question that cannot be
          # answered means RUN. The script needs nothing but the checkout and
          # the runner's own node, so it is reachable here, before pnpm and
          # before install.
          if ! CHANGED=$(git diff --name-only \
            '${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}'); then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Could not diff against the merge base. Running everything rather than skipping silently.'
            exit 0
          fi
          if ! TEST_INPUTS=$(printf '%s\n' "$CHANGED" | node scripts/markdown-test-inputs.mjs --changed -); then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Could not tell whether the changed markdown is a test input. Running everything rather than skipping silently.'
            exit 0
          fi
          if [ -n "$TEST_INPUTS" ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Markdown changed that a test reads as its input. Running everything:'
            echo "$TEST_INPUTS"
          else
            echo 'should_run=false' >> "$GITHUB_OUTPUT"
            echo 'Only ignored paths changed, and no test reads the markdown among them. Skipping the steps below; this check still reports.'
          fi

      - name: Enable Corepack and download the pinned pnpm
        if: steps.relevant.outputs.should_run == 'true'
        run: bash scripts/ci-setup-pnpm.sh

      - name: Verify pnpm version
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm --version

      - name: Setup Node.js
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/setup-node@v7
        with:
          node-version: '22.x'
          cache: 'pnpm'

      # objectui#12957: every @objectstack/* package resolves to the build of the
      # commit `.objectstack-sha` pins, read from node_modules/.cache/objectstack, so
      # it must be there before pnpm resolves anything. Restored by the pin and built
      # only on a miss (scripts/objectstack-pin.mjs); the save is this job's last step.
      - name: Restore the pinned @objectstack build
        id: objectstack-pin
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/cache/restore@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

      - name: Build @objectstack at the pin (skips a restored build)
        id: objectstack-build
        if: steps.relevant.outputs.should_run == 'true'
        run: node scripts/objectstack-pin.mjs build

      - name: Install dependencies
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm install --frozen-lockfile

      # ── The two speeds (objectui#12214, objectstack#22998) ──────────────
      # `push` and `schedule` are the full battery: nothing is selected, every
      # test file runs. On `pull_request` and `merge_group` the selector names
      # the affected set -- the packages the change sits in and every package
      # that depends on them, plus the test files the package graph cannot
      # place, which run on every change -- or answers `mode=full` when the
      # change reaches something every test runs through. Its header states the
      # rules and what it does not see; the full battery on `main` is the
      # backstop for every miss.
      #
      # Fails OPEN, like every gate in this file: a selector that exits
      # non-zero, prints no verdict, or is handed no base sha means the full
      # suite, never a skip. The exit status is captured beside the output, not
      # through a command substitution (objectui#6221). Every shard computes the
      # same selection from the same checkout, so `--shard` partitions one set.
      - name: Select the tests this change affects
        id: select
        if: steps.relevant.outputs.should_run == 'true'
        env:
          EVENT: ${{ github.event_name }}
          PR_BASE: ${{ github.event.pull_request.base.sha }}
          QUEUE_BASE: ${{ github.event.merge_group.base_sha }}
        run: |
          case "$EVENT" in
            pull_request) base="$PR_BASE" ;;
            merge_group) base="$QUEUE_BASE" ;;
            *)
              echo 'mode=full' >> "$GITHUB_OUTPUT"
              echo "A $EVENT run is the full battery: every test file, sixteen shards."
              exit 0
              ;;
          esac
          status=0
          if [ -z "$base" ]; then
            echo "::warning::no base sha on this $EVENT event; running the full suite rather than guessing."
            status=2
          else
            node scripts/select-affected-tests.mjs --base "$base" --out "$RUNNER_TEMP/affected-tests.txt" \
              > "$RUNNER_TEMP/select.out" || status=$?
            cat "$RUNNER_TEMP/select.out"
          fi
          verdict=''
          if [ "$status" -eq 0 ]; then
            verdict=$(tail -n 1 "$RUNNER_TEMP/select.out")
          fi
          case "$verdict" in
            mode=affected | mode=full) ;;
            *)
              echo "::warning::the affected-test selector reached no verdict (exit $status); running the full suite rather than skipping silently."
              verdict='mode=full'
              ;;
          esac
          echo "$verdict" >> "$GITHUB_OUTPUT"

      # Run the canonical root Vitest project once. Running `turbo run test`
      # here starts one Vitest process per package; several package configs
      # intentionally inherit the root monorepo project list, so CI ends up
      # repeating large chunks of the suite and can starve slower plugin tests.
      # The affected speed is the same root run with the selector's filters as
      # positionals -- paths relative to the repository root, no `--`, which is
      # the only spelling `scripts/vitest-invocation-guard.mjs` admits.
      #
      # `$MODE` is the VALUE of the step output `mode`: the selector step's
      # `mode=affected` line is GitHub's `key=value` form, so what arrives here
      # is `affected` or `full`, never the line itself. Comparing against the
      # whole line kept this speed from ever running (objectui#13350);
      # `scripts/__tests__/select-affected-tests-wiring.test.ts` runs both
      # steps as written, so neither end can be renamed alone.
      #
      # ⭐ Which files a leg runs is decided by measured per-file duration, not
      # by path hash (objectui#12208, ruling 6121816480, letter B): the root
      # config's `sequence.sequencer` is `scripts/test-shard-sequencer.mjs`,
      # and every leg computes the same plan from the same checkout. The full
      # speed also MEASURES: `scripts/test-file-timings.mjs` is added as a
      # third reporter and writes each file's whole cost on its worker (the
      # built-in json reporter's span leaves out import, setup and environment,
      # which is most of a file here). A CLI `--reporter` replaces vitest's
      # default set rather than adding to it, so the two it would have picked on
      # a runner, `default` and `github-actions`, are named beside it --
      # `scripts/__tests__/test-file-timings.test.ts` pins all three. The
      # writer never throws into the run: no report is one stderr line, never
      # a red leg.
      - name: Run tests (shard ${{ matrix.shard }}/16)
        if: steps.relevant.outputs.should_run == 'true'
        env:
          MODE: ${{ steps.select.outputs.mode }}
          OBJECTUI_TEST_TIMINGS_OUT: ${{ runner.temp }}/test-file-timings/shard-${{ matrix.shard }}.json
        run: |
          if [ "$MODE" = 'affected' ]; then
            mapfile -t filters < "$RUNNER_TEMP/affected-tests.txt"
            echo "Affected speed: ${#filters[@]} vitest filter(s), shard ${{ matrix.shard }} of 16."
            pnpm exec vitest run --shard=${{ matrix.shard }}/16 "${filters[@]}"
          else
            pnpm test --shard=${{ matrix.shard }}/16 --reporter=default --reporter=github-actions --reporter=./scripts/test-file-timings.mjs
          fi

      # The full battery's per-file timings, for the weekly refresh of
      # `scripts/test-shard-timings.json`
      # (`.github/workflows/test-shard-timings-refresh.yml`). Only `push` and
      # `schedule` upload: those are the runs the refresh reads, and an affected
      # run measures a slice. `!cancelled()` so a red leg still uploads what it
      # measured; the refresh takes only runs whose every leg was green.
      # `if-no-files-found: warn`, not `error`: the reading is report-only, and
      # a missing one must not turn a green leg red.
      - name: Upload this shard's per-file timings
        if: "!cancelled() && steps.relevant.outputs.should_run == 'true' && (github.event_name == 'push' || github.event_name == 'schedule')"
        uses: actions/upload-artifact@v7
        with:
          name: test-file-timings-${{ matrix.shard }}
          path: ${{ runner.temp }}/test-file-timings/
          retention-days: 7
          if-no-files-found: warn

      # The pinned @objectstack build, saved only when this job built it (a cache
      # miss) and whatever the verdict above was -- it does not depend on it.
      # Bookkeeping: bounded and non-fatal (objectui#6577, objectui#7048). The bound
      # is not yet derived from a measured save; re-derive it from this step's runs.
      - name: Save the pinned @objectstack build
        if: ${{ !cancelled() && steps.relevant.outputs.should_run == 'true' && steps.objectstack-build.outcome == 'success' && steps.objectstack-pin.outputs.cache-hit != 'true' }}
        continue-on-error: true
        timeout-minutes: 2
        uses: actions/cache/save@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

  # ── The built-artifact pin lane, lifted out of the shard matrix ──────────
  # (objectui#7183 for the lane itself; objectui#9499 for this job.)
  #
  # `pnpm test --shard=N/16` above resolves every workspace package to its `src`
  # -- that is what the root alias map is for -- so no test in it can observe
  # its own package's BUILT output. This is the only place a `dist`-importing
  # pin runs, and `turbo run test:dist` carries `dependsOn: ["build"]` for the
  # package under test, so the bundle exists before the pin reads it. Before
  # the lane existed such a pin could not be committed at all: it landed with
  # no `dist` to import, which is NOT MEASURED rather than a red pin, and the
  # usual repair (delete it, or let it skip) leaves a green suite that measures
  # nothing.
  #
  # ⭐ Why it is a JOB and not a step on shard 1 any more. It was never sharded
  # -- it ran whole, once, on shard 1 only -- so it made shard 1 structurally
  # the longest leg of a matrix bounded by `timeout-minutes: 20`. Measured on
  # objectui#9499 across 28 full CI runs it costs 31-58 s (median ~53 s), and
  # in BOTH observed ceiling kills the job died in this step with the test step
  # already green: the tests passed and the check reported `cancelled`. A
  # separate job pays for one more runner (~30 s of checkout + install) and
  # takes the asymmetry out of the matrix entirely, without touching a single
  # budget, skipping a single test, or widening the relevance gate.
  #
  # The relevance gate below is the `test` job's, verbatim including its
  # markdown second stage. ⛔ Not simplified: this lane used to run whenever
  # that job's gate said run, and a narrower gate here would silently stop
  # running the built-artifact pins on the markdown-only pull requests
  # objectui#9096 deliberately brought back into scope. The reasoning for every
  # line of it is on the `test` job above; it is not repeated here.
  test-dist-pins:
    name: Test (dist pins)
    # No event guard, like the shard matrix above (objectui#12214): the push
    # lane used to be the coverage lane alone, and this job skipped with the
    # shards. `test-aggregate` below asserts this job's result, so the two
    # still run together -- now on every event.
    runs-on: ubuntu-latest
    # The same bound the matrix carries. This job builds one package and runs a
    # handful of files, so it sits nowhere near it -- the bound is here for the
    # reason it is there, a stalled runner failing fast instead of hanging for
    # six hours.
    timeout-minutes: 20

    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          submodules: true
          # `fetch-depth: 0` for the gate step below (objectui#3523): it diffs
          # against the merge base, which a depth-1 clone cannot resolve.
          fetch-depth: 0

      - name: Decide whether this change needs a full run
        id: relevant
        run: |
          if [ "${{ github.event_name }}" != 'pull_request' ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Not a pull request: push is filtered at the trigger, and a merge_group build is the last validation before main. Running everything.'
            exit 0
          fi
          if ! CHANGED=$(git diff --name-only \
            '${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}' -- \
            . \
            ':(exclude,glob)**/*.md' \
            ':(exclude,glob)content/**' \
            ':(exclude,glob)docs/**' \
            ':(exclude,glob)apps/site/**' \
            ':(exclude,glob).changeset/**'); then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Could not diff against the merge base. Running everything rather than skipping silently.'
            exit 0
          fi
          if [ -n "$CHANGED" ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo "$CHANGED"
            exit 0
          fi
          if ! CHANGED=$(git diff --name-only \
            '${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}'); then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Could not diff against the merge base. Running everything rather than skipping silently.'
            exit 0
          fi
          if ! TEST_INPUTS=$(printf '%s\n' "$CHANGED" | node scripts/markdown-test-inputs.mjs --changed -); then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Could not tell whether the changed markdown is a test input. Running everything rather than skipping silently.'
            exit 0
          fi
          if [ -n "$TEST_INPUTS" ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Markdown changed that a test reads as its input. Running everything:'
            echo "$TEST_INPUTS"
          else
            echo 'should_run=false' >> "$GITHUB_OUTPUT"
            echo 'Only ignored paths changed, and no test reads the markdown among them. Skipping the steps below; this check still reports.'
          fi

      - name: Enable Corepack and download the pinned pnpm
        if: steps.relevant.outputs.should_run == 'true'
        run: bash scripts/ci-setup-pnpm.sh

      - name: Verify pnpm version
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm --version

      - name: Setup Node.js
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/setup-node@v7
        with:
          node-version: '22.x'
          cache: 'pnpm'

      # objectui#12957: every @objectstack/* package resolves to the build of the
      # commit `.objectstack-sha` pins, read from node_modules/.cache/objectstack, so
      # it must be there before pnpm resolves anything. Restored by the pin and built
      # only on a miss (scripts/objectstack-pin.mjs); the save is this job's last step.
      - name: Restore the pinned @objectstack build
        id: objectstack-pin
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/cache/restore@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

      - name: Build @objectstack at the pin (skips a restored build)
        id: objectstack-build
        if: steps.relevant.outputs.should_run == 'true'
        run: node scripts/objectstack-pin.mjs build

      - name: Install dependencies
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm install --frozen-lockfile

      - name: Run built-artifact pins (dist project)
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm test:dist

      # The pinned @objectstack build, saved only when this job built it (a cache
      # miss) and whatever the verdict above was -- it does not depend on it.
      # Bookkeeping: bounded and non-fatal (objectui#6577, objectui#7048). The bound
      # is not yet derived from a measured save; re-derive it from this step's runs.
      - name: Save the pinned @objectstack build
        if: ${{ !cancelled() && steps.relevant.outputs.should_run == 'true' && steps.objectstack-build.outcome == 'success' && steps.objectstack-pin.outputs.cache-hit != 'true' }}
        continue-on-error: true
        timeout-minutes: 2
        uses: actions/cache/save@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

  # ── ⭐ The single required test context (objectui#9499, ruling letter C) ──
  #
  # Until this job the required-check set named the matrix legs one by one --
  # `Test (shard 1/4)` … `Test (shard 4/4)` -- which welded the SHARD COUNT to
  # repository settings no workflow edit can reach. Changing 4 to 8 renames four
  # live required contexts: every pull request then blocks forever on a check
  # that can no longer report, and every queue build burns the ruleset's
  # 60-minute status-check timeout. One aggregator context instead means the
  # matrix width above is an ordinary workflow edit again.
  #
  # ⚠️ `needs.test.result` ALONE WOULD BE A PHANTOM GATE, and that is why this
  # job runs a script rather than reading an expression. A matrix job's
  # `needs.<job>.result` is a single ROLLUP over every leg, and a rollup cannot
  # distinguish "all sixteen ran green" from "thirteen ran green and three were
  # SKIPPED". A shard dropped from the matrix, or given a job-level `if:` that
  # is false, would leave this context GREEN while a fraction of the suite never
  # ran -- the objectui#8857 / objectui#3523 shape, a check reporting success
  # having run nothing. `scripts/check-test-shard-results.mjs` therefore reads
  # this run's own job list from the Actions API and asserts each shard BY NAME
  # and by its OWN conclusion, and it fails closed: an unreadable answer is a
  # red context, never a pass.
  #
  # `if: always()` so a red, skipped or cancelled shard still produces a verdict
  # here instead of skipping this job -- a skipped required context counts as
  # SUCCESS in branch protection, which on the one context that speaks for the
  # whole test lane is the failure mode itself. No event guard, matching the
  # two jobs above (objectui#12214): on `push` and `schedule` this is the full
  # battery's test verdict for the commit on `main`, read the same way.
  test-aggregate:
    name: Test
    needs: [test, test-dist-pins]
    if: always()
    runs-on: ubuntu-latest
    timeout-minutes: 10
    # Declaring any `permissions:` block sets every unlisted scope to `none`,
    # so both are named: `contents` for the checkout, `actions` for
    # `GET /actions/runs/{id}/attempts/{n}/jobs`. Nothing here writes.
    permissions:
      contents: read
      actions: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      # No pnpm and no install: the gate is one `fetch` and runs on the
      # runner's own node, exactly as the relevance gates above do. That keeps
      # the one required test context cheap enough to report in seconds on a
      # pull request whose shards did no work.
      - name: Every test shard reported success, one shard at a time
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Printed, never trusted -- see the header above. Having the rollup in
          # the log next to the per-shard reading is what lets a future reader
          # check the claim rather than take it.
          TEST_MATRIX_ROLLUP: ${{ needs.test.result }}
        run: |
          echo "needs.test.result (the matrix rollup this gate deliberately does NOT trust) = $TEST_MATRIX_ROLLUP"
          node scripts/check-test-shard-results.mjs --shards 16 --job-name 'Test'

      # The dist-pin lane is NOT a matrix, so its `needs` result is that one
      # job's own conclusion and `skipped` is visible in it -- no API read is
      # needed to say anything true about it. It is asserted here rather than
      # left as a second required context so that the whole test lane still
      # speaks through one name.
      - name: The built-artifact pin job reported success
        env:
          DIST_PINS_RESULT: ${{ needs.test-dist-pins.result }}
        run: |
          if [ "$DIST_PINS_RESULT" != 'success' ]; then
            echo "::error title=Test::the test-dist-pins job reported '$DIST_PINS_RESULT', not 'success'"
            exit 1
          fi
          echo "test-dist-pins: success"

      # ⛔ REPORT-ONLY, not a gate (objectui#12208, ruling 6121816480;
      # objectstack#22998's timing rule): the longest shard's wall against
      # the `test` job's `timeout-minutes`, and the width this run's measured
      # total implies at the 10-minute target per shard. `always()` so a red
      # verdict above still gets its reading; `continue-on-error` so the
      # reading can never turn this context red, whatever it reads. The
      # arguments are pinned to the matrix and the cap by
      # `scripts/__tests__/shard-headroom.test.ts`.
      - name: The longest test shard's headroom against the cap (report-only)
        if: always()
        continue-on-error: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: node scripts/shard-headroom.mjs --job 'Test (shard {n}/16)' --shards 16 --cap-minutes 20 --target-minutes 10

  # Push to main/develop: the coverage lane, sharded 4 ways with a blob-report
  # merge (objectui#5403). The comment that used to sit here declined to shard
  # it — "nothing blocks on this job, so it isn't worth the blob report merge
  # that sharding a coverage run would require". That trade was priced when the
  # job was shorter. Re-measured on aa949ba2 — current `main`, and the FIRST
  # commit where objectui#5402's fix is in — with both arms on the same commit
  # and the same runner class (instrument: `proto-5403-shard-coverage.yml` on
  # branch `claude/issue-5403-proto`, runs 32387182880 and 32387778786;
  # elapsed from each job's own `started_at`/`completed_at`):
  #
  #   4 shards, slowest shard job   11 min 25 s / 10 min 52 s  (two rounds)
  #   + the merge job                ~1 min 15 s  (13 s of it the merge itself)
  #   = the sharded lane            ~12 min 40 s / ~12 min 07 s
  #   the unsharded run             39 min 51 s of tests, 40 min 19 s of job
  #
  # ⚠️ The unblock comment on #5403 predicted that #5402 would have made the
  # unsharded arm FASTER than the 39 min 05 s measured before it. It has not:
  # 39 min 51 s on this commit, which is the old figure back within run-to-run
  # noise. And measured at the level the cap acts on — the JOB — it is 40 min
  # 19 s, i.e. `timeout-minutes: 40` would have killed this run about twenty
  # seconds before the suite finished. That is the fifth occurrence of a
  # timeout that has already fired four times, and a job killed at 40 minutes
  # uploads nothing at all. Unsharded, this lane is not merely slow; it no
  # longer reliably reaches its own upload step.
  #
  # Equivalence of the merged report is the acceptance test; it is measured
  # rather than assumed, and the numbers are in the pull request that made this
  # change — along with what happens on a red suite, which is the state `main`
  # is in on this commit.
  #
  # `timeout-minutes: 40` is deliberately UNCHANGED. It had already fired four
  # times on the unsharded job; at a quarter of the work per runner the margin
  # stops being tight on its own, and raising or lowering a cap is a separate
  # decision from this one.
  #
  # ⭐ 4 -> 8 (objectui#12256, folded into objectui#12208 under that card's
  # ruling 6121816480, letter B, by the director's fold note 6126024274). At
  # four shards the margin above had gone: measured on objectui#12256 over the
  # 25 newest `push` runs on `main`, a coverage shard was CANCELLED at the
  # 40-minute ceiling on 7 of them, and on the 18 that finished every shard ran
  # within one to three minutes of it. The width is derived from those walls,
  # not guessed: the four shards summed to about 91-153 minutes on the runs
  # that finished, and at a 20-minute target per shard that is eight. The same
  # three refusals as the `test` matrix: ⛔ the ceiling is NOT raised, ⛔ no test
  # is skipped or quarantined, and ⛔ `coverage.thresholds` are unchanged --
  # still enforced exactly once, by `coverage-report` below, over the merge of
  # EVERY shard's blob, which that job refuses to merge from a partial set. The
  # width is said once per job (the matrix here, `COVERAGE_SHARDS` there) and
  # `scripts/__tests__/coverage-shard-width.test.ts` holds every spelling of it
  # -- the job name, `--shard=N/M`, the blob name the merge counts and the
  # count it expects -- to this matrix.
  #
  # ## Why the shard legs override the coverage thresholds, and the merge does
  # ## not
  #
  # `coverage.thresholds` in `vitest.config.mts` is checked by the v8 provider's
  # `generateReports()` on EVERY coverage run — there is no shard-awareness
  # anywhere in that path (`@vitest/coverage-v8/dist/provider.js`: `if (this
  # .options.thresholds) await this.reportThresholds(...)`, reached from
  # `reportCoverage()` and from `mergeReports()` alike). Sharding without the
  # override would therefore evaluate the whole-suite thresholds once per shard
  # over a slice of the suite, plus once on the merged report (five times per
  # push at four shards, nine at eight). Those per-shard evaluations are
  # assertions this lane has never made, they judge partial data, and the only
  # verdict they can add is a false red. The override keeps the check at exactly
  # ONE evaluation over the complete report — the shape this lane had while it
  # was unsharded.
  #
  # ⚠️ It is NOT here because the shards were seen to fail: that prediction was
  # measured and refuted. A shard leg run WITHOUT the override passes today
  # (proto run 32387182880, "PROTO shard 1/4 WITHOUT the threshold override",
  # conclusion=success, reproduced in run 32387778786) — the v8 provider reports
  # only the files a run actually loaded, so one shard's percentage lands near
  # the whole suite's rather than at a quarter of it.
  #
  # That the gate still fires on the merged report is a code path, not a
  # guess: `mergeReports()` calls `generateReports(coverageMap, true)`, the
  # same function that ends in `if (this.options.thresholds) await this
  # .reportThresholds(...)`. ⚠️ The CI ablation that was meant to demonstrate it
  # end-to-end could not: on this commit the merged blobs carry a failing shard,
  # so both the enforced leg and the 99%-threshold leg go red for that reason
  # and neither separates the thresholds from the failures. Said here rather
  # than left as a claim the run does not actually support.
  test-coverage:
    name: Test (coverage shard ${{ matrix.shard }}/8)
    # The full battery's coverage half: every merge to `main` (`push`) and the
    # hourly `schedule` run (objectui#12214).
    if: github.event_name == 'push' || github.event_name == 'schedule'
    runs-on: ubuntu-latest
    timeout-minutes: 40

    strategy:
      # Report every shard's failures, not just the first one to break — and
      # the merge below refuses to publish anything unless every shard is green,
      # so there is nothing to save by stopping early.
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5, 6, 7, 8]

    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          submodules: true

      - name: Enable Corepack and download the pinned pnpm
        run: bash scripts/ci-setup-pnpm.sh

      - name: Verify pnpm version
        run: pnpm --version

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22.x'
          cache: 'pnpm'

      # objectui#12957: every @objectstack/* package resolves to the build of the
      # commit `.objectstack-sha` pins, read from node_modules/.cache/objectstack, so
      # it must be there before pnpm resolves anything. Restored by the pin and built
      # only on a miss (scripts/objectstack-pin.mjs); the save is this job's last step.
      - name: Restore the pinned @objectstack build
        id: objectstack-pin
        uses: actions/cache/restore@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

      - name: Build @objectstack at the pin (skips a restored build)
        id: objectstack-build
        run: node scripts/objectstack-pin.mjs build

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # `--reporter=blob` makes the run write `.vitest-reports/blob-N-8.json`
      # (the shard index is in the FILE NAME, which is what lets every shard's
      # artifact be downloaded into one directory below without colliding —
      # measured, not assumed). The blob carries this shard's raw coverage as
      # well as its test results; the coverage report proper is produced once,
      # by the merge.
      #
      # `--reporter=default --reporter=github-actions` are here because a CLI
      # `--reporter` REPLACES the reporter set rather than adding to it, and the
      # set it replaced is exactly this pair. Vitest 4.1.10 resolves reporters
      # with:
      #
      #     if (!resolved.reporters.length) {
      #       resolved.reporters.push([isAgent ? "agent" : "default", {}]);
      #       if (process.env.GITHUB_ACTIONS === "true")
      #         resolved.reporters.push(["github-actions", {}]);
      #     }
      #
      # — and this repo's vitest config sets no `reporters`, so before
      # objectui#9177 the blob flag alone was the whole set. A red shard's log
      # therefore ended at `blob report written to …` with no failing test name,
      # no assertion text and no timeout message, and the shard job's only
      # annotation was the generic `Process completed with exit code 1.` The
      # failures existed solely inside the `coverage-blob-N` artifact, which is
      # download-only. objectui#8545 priced that: two episodes in which ONE test
      # file held main's coverage gate unevaluated for 84 and 87 consecutive
      # pushes, both found by a person reading a job log by hand, days later.
      #
      # ⚠️ Additive on purpose — the blob stays, because the merge job below is
      # what enforces the thresholds and it has nothing to read without it.
      # Measured on vitest 4.1.10 with all three reporters and `--shard=N/4`
      # (the width then; the reporter set does not depend on it):
      # the log carries `Failed Tests`, the test names, the assertion diff and
      # `Error: Test timed out in …`; `github-actions` emits one `::error`
      # annotation per failing test, which is the only form of this an API
      # reader gets without downloading an artifact; and the shard still writes
      # its `.vitest-reports/blob-N-M.json`, which merges and has the configured
      # thresholds enforced over it exactly as before.
      #
      # ⛔ Do not "simplify" this back to one reporter. Dropping the blob trades
      # an unreadable failure for an unevaluated coverage floor — the same
      # defect wearing the other hat — and dropping the other two restores
      # objectui#9177. `scripts/__tests__/coverage-shard-reporter-readability.test.ts`
      # fails in both directions.
      # ── Why this lane carries its own `--testTimeout` (objectui#9271) ────
      #
      # `vitest.config.mts` sets `testTimeout: 15000`. That budget is calibrated
      # for the UNINSTRUMENTED lane (`test:` above, which runs on every event
      # except push). This lane runs the same files under v8 coverage, and
      # instrumentation is not free: the repo-sweeping rows under
      # `scripts/__tests__/` — the ones that call `sweep(repoRoot)` /
      # `analyze(repoRoot)` and walk the whole tree — take several times longer
      # with the provider attached than without it.
      #
      # ⇒ the 15s budget has comfortable headroom uninstrumented and NONE here,
      # so rows that pass everywhere else die in this lane on a timeout. A dead
      # shard is not a failed gate, it is NO gate: `coverage-report` below gates
      # every merge step on `needs.test-coverage.result == 'success'`, so one
      # timed-out row skips the merge and the thresholds are never evaluated at
      # all. objectui#9271 measured 116 consecutive pushes to `main` in that
      # state; the comment above records objectui#8545 pricing two earlier
      # episodes of the same shape at 84 and 87 pushes.
      #
      # ⛔ This is NOT a performance budget and must not be read as one. The
      # timeout is a hung-test detector, and the detector that guards day-to-day
      # work is the 15s one in the uninstrumented lane — which is UNCHANGED, and
      # is the lane that actually runs before a merge. This number only stops
      # this lane from killing rows that are doing exactly what they should.
      #
      # ⭐ Re-derive the ratio rather than trusting a figure written here
      # (AGENTS.md #5 rule #9) — same tree, same runner, the flag set below as
      # the only variable:
      #
      #     pnpm exec vitest run --project unit --testTimeout=900000 \
      #       --reporter=verbose scripts/__tests__/check-i18n-dead-keys.test.ts
      #     # then again with --coverage and compare the per-row ms
      #
      # ⚠️ Raising this cannot cost the job its own budget on its own: letting a
      # row finish instead of killing it at 15s adds only the difference, not a
      # re-run. The shard's own margin against `timeout-minutes: 40` is a
      # separate question -- objectui#12256 measured it gone at four shards,
      # which is why this lane is eight wide.
      - name: Run tests with coverage (shard ${{ matrix.shard }}/8)
        run: >-
          pnpm test:coverage --reporter=blob --reporter=default
          --reporter=github-actions --shard=${{ matrix.shard }}/8
          --testTimeout=60000
          --coverage.thresholds.lines=0 --coverage.thresholds.functions=0
          --coverage.thresholds.branches=0 --coverage.thresholds.statements=0

      # `always()`: a shard that went red is exactly when someone wants its
      # blob. It holds the failing results AND the coverage this runner
      # collected, and it survives a red run — which is why the `coverage`
      # directory being deleted on failure (vitest's `reportOnFailure: false`,
      # objectui#5402) stops mattering for this lane. `if-no-files-found: error`
      # because "the reporter wrote nothing" is a real finding, not a shrug.
      #
      # `retention-days: 7` is a deliberate, adjustable number rather than the
      # 90-day default: one blob per shard per full-battery run (eight since
      # objectui#12256, on every push and every hourly run) is several GB of
      # steady-state storage at a week -- the run's own artifact list is the
      # reading, not a figure written here (AGENTS.md #9). A week is what
      # makes a Monday-morning question about a Friday-evening red run
      # answerable; shorten it if the storage matters more than that.
      - name: Upload this shard's blob report
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: coverage-blob-${{ matrix.shard }}
          path: .vitest-reports/*
          include-hidden-files: true
          retention-days: 7
          if-no-files-found: error

      # The pinned @objectstack build, saved only when this job built it (a cache
      # miss) and whatever the verdict above was -- it does not depend on it.
      # Bookkeeping: bounded and non-fatal (objectui#6577, objectui#7048). The bound
      # is not yet derived from a measured save; re-derive it from this step's runs.
      - name: Save the pinned @objectstack build
        if: ${{ !cancelled() && steps.objectstack-build.outcome == 'success' && steps.objectstack-pin.outputs.cache-hit != 'true' }}
        continue-on-error: true
        timeout-minutes: 2
        uses: actions/cache/save@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

  # The other half of objectui#5403: merge every shard's blob report into ONE
  # complete coverage report, publish it, and — whatever happens — say out loud
  # whether this lane actually delivered for the commit.
  #
  # ## The Codecov upload is gone (objectui#5436, maintainer ruling 2026-08-22)
  #
  # `CODECOV_TOKEN` was never set on this repository, Codecov no longer accepts
  # tokenless uploads, and so `Upload coverage to Codecov` failed server-side
  # (`Token length: 0`, "Token required - not valid tokenless upload") on every
  # push after #5403 landed. Of the three ways out, the maintainer ruled Option
  # B: retire the upload rather than set the secret, and keep the merged report
  # as a build artifact plus the step summary below. What is given up is the
  # Codecov trend dashboard and its PR comments. What is NOT given up is the
  # GATE — the thresholds have always been enforced by the merge step, never by
  # Codecov, and that is untouched here. Making the upload conditional on the
  # secret being present was rejected: it restores exactly the quiet green that
  # #5403 removed.
  #
  # ## Why this job exists rather than an `if:` on one step
  #
  # The upload step used to carry no `if:` at all, so it inherited the implicit
  # `success()` and was SKIPPED whenever the suite failed: 311 of 373 coverage
  # jobs, and 120 of the 121 most recent. From outside, a lane that delivered
  # nothing and a lane that delivered an unchanged number look identical —
  # which is how four dark days went unnoticed while the job failed 100% of the
  # time (objectui#5402). Nothing blocks on this lane, so the fix cannot be
  # "block on it"; the fix is that the lane STATES its own outcome. #5436
  # carries that guarantee across to the claim that survives the upload's
  # retirement:
  #
  #   this job is green ONLY when every shard passed, every shard's blob report
  #   arrived, they merged into one report, the configured thresholds were
  #   enforced over that whole merged map, and the report was published as a
  #   retrievable artifact — and red, with an error annotation naming which of
  #   those did not happen, every other time.
  #
  # That is a stronger claim than the one it replaces, not a weaker one. The
  # old red said "the dashboard is stale"; the new red says "the coverage GATE
  # did not run on this commit" — and since the shard legs override the
  # thresholds to zero, this job is the only place it can run at all.
  #
  # ⛔ The merge is deliberately NOT unconditional. A merged report built from
  # fewer than every shard would understate coverage on every file the missing
  # shard exercised, and a wrong coverage number is worse than a missing one.
  # So the merge and the publish run only when every shard is green AND every
  # shard's blob actually arrived; everything else takes the loud path.
  #
  # The job keeps the name `Test (coverage)` the unsharded job had: it is the
  # context that answers "did the coverage lane deliver for this commit", and
  # `scripts/dependabot-merge-gate.mjs` classifies it by that name.
  coverage-report:
    name: Test (coverage)
    needs: test-coverage
    # `always()` so the verdict step below still runs when a shard failed —
    # that is the entire point. The event guard matches `test-coverage`: the
    # full battery's events, `push` and `schedule` (objectui#12214).
    if: always() && (github.event_name == 'push' || github.event_name == 'schedule')
    runs-on: ubuntu-latest
    timeout-minutes: 20
    # The coverage matrix's width, said once for this job: the blob count the
    # merge refuses to go below and the verdict's wording both read it.
    # `scripts/__tests__/coverage-shard-width.test.ts` pins it to the
    # `test-coverage` matrix above (objectui#12256).
    env:
      COVERAGE_SHARDS: '8'
    # Declaring any `permissions:` block sets every unlisted scope to `none`,
    # so both are named: `contents` for the checkouts, `actions` for the
    # headroom reading's `GET /actions/runs/{id}/attempts/{n}/jobs`. The
    # artifact steps use the runner's own token, not this one. Nothing here
    # writes.
    permissions:
      contents: read
      actions: read

    steps:
      # Every step up to the verdict is gated on the shards having passed:
      # on a red run this job does a checkout-free ~10 seconds and reports.
      - name: Checkout code
        if: needs.test-coverage.result == 'success'
        uses: actions/checkout@v7
        with:
          submodules: true

      - name: Enable Corepack and download the pinned pnpm
        if: needs.test-coverage.result == 'success'
        run: bash scripts/ci-setup-pnpm.sh

      - name: Verify pnpm version
        if: needs.test-coverage.result == 'success'
        run: pnpm --version

      - name: Setup Node.js
        if: needs.test-coverage.result == 'success'
        uses: actions/setup-node@v7
        with:
          node-version: '22.x'
          cache: 'pnpm'

      # objectui#12957: every @objectstack/* package resolves to the build of the
      # commit `.objectstack-sha` pins, read from node_modules/.cache/objectstack, so
      # it must be there before pnpm resolves anything. Restored by the pin and built
      # only on a miss (scripts/objectstack-pin.mjs); the save is this job's last step.
      - name: Restore the pinned @objectstack build
        id: objectstack-pin
        if: needs.test-coverage.result == 'success'
        uses: actions/cache/restore@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

      - name: Build @objectstack at the pin (skips a restored build)
        id: objectstack-build
        if: needs.test-coverage.result == 'success'
        run: node scripts/objectstack-pin.mjs build

      - name: Install dependencies
        if: needs.test-coverage.result == 'success'
        run: pnpm install --frozen-lockfile

      - name: Download every shard's blob report
        if: needs.test-coverage.result == 'success'
        uses: actions/download-artifact@v8
        with:
          pattern: coverage-blob-*
          path: .vitest-reports
          merge-multiple: true

      # A zero is not a reading: `--merge-reports` is perfectly happy to merge
      # three blobs and print a confident, wrong total. Count them first.
      - name: Refuse to merge a partial set of shard reports
        id: blobs
        if: needs.test-coverage.result == 'success'
        run: |
          # `mkdir -p` first, and no `2>/dev/null` anywhere: a missing directory
          # must not abort this step before it can print the annotation below,
          # and a swallowed stderr is the fail-CLOSED spelling objectui#3723
          # removed from this file (pinned by merge-queue-reporting.test.ts).
          mkdir -p .vitest-reports
          ls -la .vitest-reports/
          blobs=$(find .vitest-reports -maxdepth 1 -type f -name "blob-*-${COVERAGE_SHARDS}.json" | wc -l)
          if [ "$blobs" -ne "$COVERAGE_SHARDS" ]; then
            echo "::error title=Coverage merge::expected $COVERAGE_SHARDS shard blob reports, found $blobs — a merged report built from a partial set understates coverage, refusing to merge"
            exit 1
          fi
          echo "all $COVERAGE_SHARDS shard blob reports present"

      # No tests run here: `--merge-reports` reads the blobs and produces the
      # one complete report. It is ALSO the gate. The configured
      # `coverage.thresholds` (vitest.config.mts: lines 40, functions 33,
      # branches 30, statements 40) are enforced HERE, over the whole merged
      # map, and a breach exits this step non-zero — the shard legs override
      # them to zero, so this step is the only place the gate runs at all.
      #
      # That the gate fires on a merged report is a code path, not a guess:
      # `mergeReports()` calls `generateReports(coverageMap, true)`, which ends
      # in `if (this.options.thresholds) await this.reportThresholds(...)`. It
      # is also measured, not asserted (objectui#5436): against one real blob
      # set reporting 38.4% lines, `--coverage.thresholds.lines=38` exits 0 and
      # `=39` exits 1 with `ERROR: Coverage for lines (38.4%) does not meet
      # global threshold (39%)`. Only the threshold moved between the two runs.
      # #5403's CI ablation could not separate the two legs (its blobs carried
      # a failing shard, so both went red for that reason), which is why the
      # demonstration was owed here.
      #
      # `generateReports()` writes the json reporter BEFORE it evaluates the
      # thresholds, which is what lets the publish step below still capture a
      # report that breached.
      - name: Merge the shard reports into one coverage report
        id: merge
        if: needs.test-coverage.result == 'success'
        run: pnpm test:coverage --merge-reports --coverage.reporter=json --coverage.reporter=text

      # What replaces the Codecov upload (objectui#5436): the merged report is
      # kept here, on the run, instead of on a third-party dashboard.
      #
      # `!cancelled()` plus an explicit `outcome != 'skipped'`, rather than the
      # implicit `success()` the steps above inherit: when the merge fails on
      # the THRESHOLDS, the report exists and is precisely the artifact someone
      # wants to open, so a red gate must still publish its evidence. The job
      # stays red either way — the verdict step below requires `merge=success`.
      #
      # `retention-days: 7` matches the shard blobs deliberately: this report is
      # derived from them, and outliving its own inputs would leave a number
      # with nothing left to check it against. `if-no-files-found: error`
      # because "the merge wrote no report" is a real finding, not a shrug.
      - name: Publish the merged coverage report
        id: report
        if: ${{ !cancelled() && needs.test-coverage.result == 'success' && steps.merge.outcome != 'skipped' }}
        uses: actions/upload-artifact@v7
        with:
          name: coverage-report
          path: coverage/
          retention-days: 7
          if-no-files-found: error

      # ⛔ REPORT-ONLY, not a gate (objectui#12208, ruling 6121816480;
      # objectui#12256): the longest coverage shard's wall against
      # `test-coverage`'s `timeout-minutes`, and the width this run's measured
      # total implies at the 20-minute target per shard. Before the verdict, so
      # the verdict stays this job's last word; `always()` so a red lane still
      # gets its reading -- a cancelled shard is precisely the one whose wall
      # is worth reading -- and `continue-on-error` so the reading can never
      # change the verdict. On a red lane the checkout above was skipped, so
      # this reads `scripts/` through a sparse checkout of its own. Pinned by
      # `scripts/__tests__/shard-headroom.test.ts`.
      - name: Check out the headroom reading's script
        if: always() && needs.test-coverage.result != 'success'
        uses: actions/checkout@v7
        with:
          sparse-checkout: scripts

      - name: The longest coverage shard's headroom against the cap (report-only)
        if: always()
        continue-on-error: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: node scripts/shard-headroom.mjs --job 'Test (coverage shard {n}/8)' --shards 8 --cap-minutes 40 --target-minutes 20

      # The loud part, inherited from objectui#5403 and re-aimed at the claim
      # that outlived the upload. Runs on every path — including the one where
      # every step above was skipped, which without this step would leave this
      # job GREEN while the coverage gate never ran.
      - name: Say out loud whether the coverage gate ran on this commit
        if: always()
        env:
          SHARDS: ${{ needs.test-coverage.result }}
          BLOBS: ${{ steps.blobs.outcome }}
          MERGE: ${{ steps.merge.outcome }}
          REPORT: ${{ steps.report.outcome }}
        run: |
          run_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"

          if [ "$SHARDS" = 'success' ] && [ "$BLOBS" = 'success' ] && [ "$MERGE" = 'success' ] && [ "$REPORT" = 'success' ]; then
            echo "::notice title=Coverage gate ran::the merged $COVERAGE_SHARDS-shard report was produced for $GITHUB_SHA, the thresholds passed over the whole map, and the report is attached as the coverage-report artifact"
            {
              echo "### Coverage: the gate ran on the complete merged report"
              echo
              echo "- commit: \`$GITHUB_SHA\`"
              echo "- shards: all $COVERAGE_SHARDS green, all $COVERAGE_SHARDS blob reports merged"
              echo "- thresholds: enforced over the whole merged map, passed"
              echo "- report: the \`coverage-report\` artifact on [this run]($run_url), kept 7 days"
            } >> "$GITHUB_STEP_SUMMARY"
            exit 0
          fi

          # The gate RAN and said no. Distinguished from the case below
          # because they call for opposite actions: this one is a real coverage
          # regression to fix, that one is a broken lane to repair.
          #
          # `report=success` is what separates them, and it is load-bearing
          # rather than decorative. `generateReports()` writes the configured
          # reporters in a loop and only THEN evaluates the thresholds, so a
          # breach leaves a complete `coverage/` behind and the publish step
          # succeeds; a merge that dies earlier (an unreadable blob, a version
          # mismatch) writes no report, `if-no-files-found: error` makes the
          # publish step red too, and this run falls through to the "gate did
          # not run" branch below — where it belongs. Measured on the pull
          # request for #5436: same blob set, `--coverage.thresholds.lines`
          # moved from 38 to 39 across the report's own 38.4%, exit 0 then
          # exit 1 with `ERROR: Coverage for lines (38.4%) does not meet global
          # threshold (39%)`, and a byte-identical `coverage-final.json` left
          # behind on BOTH legs.
          if [ "$MERGE" = 'failure' ] && [ "$REPORT" = 'success' ]; then
            echo "::error title=Coverage thresholds breached::shards=$SHARDS blobs=$BLOBS merge=failure report=$REPORT — the merged report for $GITHUB_SHA was produced and the configured thresholds were enforced over it, and they FAILED"
            {
              echo "### Coverage: the thresholds were enforced and BREACHED"
              echo
              echo "- commit: \`$GITHUB_SHA\`"
              echo "- shards: all $COVERAGE_SHARDS green, all $COVERAGE_SHARDS blob reports merged"
              echo "- thresholds: enforced over the whole merged map, **failed**"
              echo "- report published: \`$REPORT\`"
              echo
              echo "This is a coverage regression, not a broken lane. The merged"
              echo "report is the \`coverage-report\` artifact on [this run]($run_url);"
              echo "the merge step's log names the metric and the numbers."
            } >> "$GITHUB_STEP_SUMMARY"
            exit 1
          fi

          echo "::error title=Coverage gate did NOT run::shards=$SHARDS blobs=$BLOBS merge=$MERGE report=$REPORT — no complete merged report was produced for $GITHUB_SHA, so the coverage thresholds were never evaluated on this commit"
          {
            echo "### Coverage: the gate did NOT run on this commit"
            echo
            echo "- commit: \`$GITHUB_SHA\`"
            echo "- shard jobs: \`$SHARDS\`"
            echo "- all $COVERAGE_SHARDS blobs present: \`$BLOBS\`"
            echo "- merge + thresholds: \`$MERGE\`"
            echo "- report published: \`$REPORT\`"
            echo
            echo "The thresholds are enforced on the MERGED report and nowhere"
            echo "else — the shard legs override them to zero. So this is not a"
            echo "missing dashboard number: this commit reached the branch with"
            echo "its coverage gate unevaluated."
          } >> "$GITHUB_STEP_SUMMARY"
          exit 1

      # The pinned @objectstack build, saved only when this job built it (a cache
      # miss) and whatever the verdict above was -- it does not depend on it.
      # Bookkeeping: bounded and non-fatal (objectui#6577, objectui#7048). The bound
      # is not yet derived from a measured save; re-derive it from this step's runs.
      - name: Save the pinned @objectstack build
        if: ${{ !cancelled() && needs.test-coverage.result == 'success' && steps.objectstack-build.outcome == 'success' && steps.objectstack-pin.outputs.cache-hit != 'true' }}
        continue-on-error: true
        timeout-minutes: 2
        uses: actions/cache/save@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

  # Build + E2E merged into one job: avoids artifact upload/download (~30s)
  # and a duplicate `pnpm install` (~60s). This job only needs the console SPA
  # artifact for Playwright; package build and package-size checks are covered
  # by the Bundle Analysis workflow for package / console changes.
  e2e:
    name: Build & E2E
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          submodules: true
          # `fetch-depth: 0` for the gate step below (objectui#3523): it diffs
          # against the merge base, which a depth-1 clone cannot resolve.
          fetch-depth: 0

      # Always report; run only when it matters — see the full note on the
      # `type-check` job above (objectui#3523). The exclusion list must stay
      # identical across the gated jobs of this workflow;
      # `scripts/__tests__/merge-queue-reporting.test.ts` fails if it drifts.
      #
      # This job has no markdown second stage and, unlike `type-check`, that is
      # now a MEASUREMENT: objectui#9241 ran this job's suite under the `fs`
      # trace objectui#9096 built and it opened no markdown document, twice, in
      # a run where the same harness recorded non-markdown reads from inside the
      # Playwright worker. The bound on that zero, and the `type-check` reading
      # that did NOT come back zero, are on the `test` job's decide step above.
      - name: Decide whether this change needs a full run
        id: relevant
        run: |
          if [ "${{ github.event_name }}" != 'pull_request' ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Not a pull request: push is filtered at the trigger, and a merge_group build is the last validation before main. Running everything.'
            exit 0
          fi
          if ! CHANGED=$(git diff --name-only \
            '${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}' -- \
            . \
            ':(exclude,glob)**/*.md' \
            ':(exclude,glob)content/**' \
            ':(exclude,glob)docs/**' \
            ':(exclude,glob)apps/site/**' \
            ':(exclude,glob).changeset/**'); then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Could not diff against the merge base. Running everything rather than skipping silently.'
            exit 0
          fi
          if [ -n "$CHANGED" ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo "$CHANGED"
          else
            echo 'should_run=false' >> "$GITHUB_OUTPUT"
            echo 'Only ignored paths changed. Skipping the steps below; this check still reports.'
          fi

      - name: Enable Corepack and download the pinned pnpm
        if: steps.relevant.outputs.should_run == 'true'
        run: bash scripts/ci-setup-pnpm.sh

      - name: Verify pnpm version
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm --version

      - name: Setup Node.js
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/setup-node@v7
        with:
          node-version: '22.x'
          cache: 'pnpm'

      # objectui#12957: every @objectstack/* package resolves to the build of the
      # commit `.objectstack-sha` pins, read from node_modules/.cache/objectstack, so
      # it must be there before pnpm resolves anything. Restored by the pin and built
      # only on a miss (scripts/objectstack-pin.mjs); the save is this job's last step.
      - name: Restore the pinned @objectstack build
        id: objectstack-pin
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/cache/restore@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

      - name: Build @objectstack at the pin (skips a restored build)
        id: objectstack-build
        if: steps.relevant.outputs.should_run == 'true'
        run: node scripts/objectstack-pin.mjs build

      - name: Install dependencies
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm install --frozen-lockfile

      - name: Build Console for E2E
        if: steps.relevant.outputs.should_run == 'true'
        # Pin VITE_BASE_PATH so the E2E suite (which mounts the SPA at
        # /console/) gets an absolute-base build whose asset URLs resolve
        # under that prefix. The default ('./') is correct for embedded
        # deployments but breaks vite preview's SPA fallback.
        #
        # Use Vite directly instead of `pnpm --filter @object-ui/console build`:
        # the package build runs `tsc` and `build:plugin`, which need built
        # workspace declaration files. The Vite bundle aliases workspace
        # packages to `src/` and is the only artifact Playwright consumes.
        env:
          VITE_BASE_PATH: /console/
        run: pnpm --filter @object-ui/console exec vite build

      - name: Verify build artifacts
        if: steps.relevant.outputs.should_run == 'true'
        run: |
          if [ ! -f "apps/console/dist/index.html" ]; then
            echo "Console build failed"
            exit 1
          fi
          echo "Console build artifact is ready"

      - name: Get Playwright version
        if: steps.relevant.outputs.should_run == 'true'
        id: playwright-version
        run: |
          # This pipeline's exit status is load-bearing: the value it produces
          # becomes the Playwright browser cache key in the next step. Without
          # `pipefail` a failing `pnpm list` is masked by `jq`, and `jq -r`
          # prints the string `null` and exits 0 when the field is missing — so
          # either failure used to yield a *successful* step and a key that had
          # silently degraded to `playwright-Linux-` / `playwright-Linux-null`.
          # That wrong bucket is stable, so two Playwright versions can share
          # one cache entry and restore a stale browser (objectui#6231).
          # The same block is duplicated verbatim in `ci.yml` and `live-e2e.yml`
          # — keep them byte-identical so they stay greppable as a pair.
          set -eo pipefail
          if ! version=$(pnpm list @playwright/test --depth=0 --json | jq -r '.[0].devDependencies["@playwright/test"].version'); then
            echo "::error::Reading the @playwright/test version failed (pnpm list --json | jq). Refusing to write a Playwright browser cache key from it."
            exit 1
          fi
          if [ -z "$version" ] || [ "$version" = "null" ]; then
            echo "::error::Could not resolve the @playwright/test version (got: '${version}'). Refusing to write an empty or null version into the Playwright browser cache key."
            exit 1
          fi
          echo "version=$version" >> "$GITHUB_OUTPUT"

      # ── Cache bookkeeping cannot void a recorded verdict (objectui#7048) ──
      # THE ORDERING, carried here from the type-check split (objectui#6577,
      # PR #7047) because it is what a future reader needs in order to judge
      # whether these steps may be touched: the verdict is recorded by the
      # checking steps; everything after them is bookkeeping, and bookkeeping
      # must never discard an answer the gate already produced.
      #
      # Why the SPLIT rather than a timeout on one step: combined
      # `actions/cache` declares `main: dist/restore/index.js` plus
      # `post: dist/save/index.js`, so its save is a step the RUNNER generates
      # at job end (`Post Cache Playwright browsers`). No workflow syntax
      # attaches `timeout-minutes` or `continue-on-error` to a generated post
      # step, so an upload stall runs the job into `timeout-minutes: 30`, the
      # job goes `cancelled`, and the merge queue cannot tell `cancelled` from
      # `failure` — an all-green pull request is ejected and every lane pays
      # the ceiling in head-of-line blocking. Measured once, on the type-check
      # cache: a 1-second save took 789s (objectui#6577). Splitting moves the
      # save into the main phase, where both keys are ordinary documented step
      # keys; `actions/cache`'s own `save-always` deprecation text points at
      # this same split.
      #
      # ⛔ Raising `timeout-minutes: 30` is the ruled-out non-fix: a larger
      # ceiling only buys a longer hang, still ends in `cancelled`, and lifting
      # a gate's ceiling weakens the gate.
      #
      # The restore half is deliberately left UNBOUNDED, as at the type-check
      # site: a restore stall fails BEFORE any verdict exists — a gate that did
      # not run, which is honest — rather than a recorded verdict discarded.
      - name: Restore Playwright browsers
        if: steps.relevant.outputs.should_run == 'true'
        uses: actions/cache/restore@v6
        id: playwright-cache
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}

      # ── No `apt-get` on this path any more (objectui#5304) ────────────────
      # `playwright install --with-deps` / `install-deps` shell out to
      # `apt-get update` as root. On 2026-08-19 that hung this job three times,
      # each for the full 30-minute ceiling, with a byte-identical last line —
      # `Get:5 https://archive.ubuntu.com/ubuntu noble-security InRelease
      # [126 kB]` — after the runner's Azure mirror answered `Ign:` for all four
      # noble indexes and apt fell back to archive.ubuntu.com:
      #   #5290 job 95986117935  07:05:48 -> cancelled 07:34:39 (30m14s)
      #   #5290 job 95993643751  07:38:31 -> cancelled 08:07:32 (30m18s, re-run)
      #   #5294 job 95988703670  07:17:27 -> cancelled 07:46:21 (30m17s)
      # apt has no timeout covering a mirror that connects and then trickles, so
      # the only backstop was `timeout-minutes: 30` — which converts a transient
      # network fault into a CANCELLED check: a gate that reports nothing at all.
      #
      # A transient, not a property of the workflow: on #5290 the
      # `Live E2E (informational)` job (95986118258) ran the same `install-deps`
      # on the same commit in the same minute and went green in 3m26s. Which is
      # why the call has to be bounded rather than trusted.
      #
      # Browser binaries come from the cache step above, never from apt
      # (measured on the run that then hung: `Cache hit for:
      # playwright-Linux-1.62.1`, 269 MB restored). `install` without
      # `--with-deps` fetches them from Playwright's CDN and touches no mirror,
      # so the cache-miss path is safe as spelled.
      - name: Install Playwright browsers
        if: steps.relevant.outputs.should_run == 'true' && steps.playwright-cache.outputs.cache-hit != 'true'
        run: pnpm exec playwright install chromium

      # The system libraries are on the `ubuntu-latest` image already — it ships
      # Chrome, Edge and Firefox, whose shared-library closure is the one
      # `install-deps chromium` asks for. Rather than assume that, this step
      # PROVES it on every run by launching the same bundled Chromium the suite
      # launches, and reaches for apt only if the launch fails — bounded, so a
      # stalled mirror costs seconds instead of the job. It is not a softener:
      # if no browser can be made to launch the script exits non-zero and this
      # job goes red. Rationale and the incident log: the script's header;
      # behaviour pinned by `scripts/__tests__/ensure-chromium-ready.test.ts`.
      - name: Ensure Chromium can launch
        if: steps.relevant.outputs.should_run == 'true'
        run: bash scripts/ensure-chromium-ready.sh

      - name: Run E2E tests
        if: steps.relevant.outputs.should_run == 'true'
        run: pnpm test:e2e --project=chromium

      # `playwright.config.ts` selects the `github` reporter when CI is set, and
      # that reporter writes annotations only — it produces NO
      # `playwright-report/` directory, so this step uploaded nothing and said
      # so in a warning rather than a failure: `No files were found with the
      # provided path: playwright-report/` (objectui#4086). Every failure's
      # actual evidence — screenshot, trace and `error-context.md` — is written
      # by the `use.screenshot` / `use.trace` settings into `test-results/`
      # instead, which is why a red E2E job left nothing behind to diagnose and
      # #4086 had to be reproduced from scratch locally.
      #
      # Both paths are listed: `test-results/` is the one that exists today, and
      # `playwright-report/` keeps working if the HTML reporter is ever enabled
      # on CI. upload-artifact only warns when NO path matches, so the absent
      # one costs nothing.
      - name: Upload failure artefacts
        uses: actions/upload-artifact@v7
        if: ${{ steps.relevant.outputs.should_run == 'true' && !cancelled() && failure() }}
        with:
          name: e2e-failure-artifacts
          path: |
            playwright-report/
            test-results/
          retention-days: 14

      # The bookkeeping half of the split documented at the restore step above,
      # placed HERE — last in the job — because that is exactly where the post
      # phase it replaces already ran. Nothing about which commits this job
      # accepts or rejects moves with it.
      #
      # `timeout-minutes: 8` is DERIVED FOR THIS CACHE, not inherited from the
      # type-check site's 5 (objectui#7048 fences that explicitly). This cache
      # is Playwright's browser binaries — ~269 MB, two orders of magnitude
      # larger than `.turbo/cache` — and upload time scales with size, so the
      # bound has to be sized against a measurement of THIS artefact:
      #   - restores of this exact archive, same runner class: 3s (job
      #     100096569775) and 3s (job 100094597323) here, 5s in `live-e2e.yml`
      #     (job 100097466897) ⇒ the cache service moves it at ~54-90 MB/s.
      #   - a save is only observable after a Playwright version bump (an exact
      #     key hit skips it, and `Post Cache Playwright browsers` measured 0s
      #     on every sampled run), so the honest save is bounded from the
      #     restore rather than read directly — stated plainly rather than
      #     dressed up as a direct measurement.
      #   - taking a deliberately pessimistic 20x penalty on the slowest
      #     observed restore gives ~1m40s for an honest save. 8 minutes is
      #     ~4.8x that, and demands only 0.56 MB/s sustained to finish.
      # And it stays clear of the ceiling in both directions: 8 x 2 = 16 <= 30,
      # so bookkeeping cannot crowd out the checking steps, whose whole verdict
      # path measured 56s wall clock end to end on job 100096569775.
      #
      # `continue-on-error: true` is the other half, and without it the bound
      # would only trade a `cancelled` gate for a red one. A cache that failed
      # to upload costs the next run a re-download from Playwright's CDN — a
      # path this job already takes on a miss — and says nothing whatsoever
      # about the code under test, so it must not be allowed to speak for it.
      #
      # Behaviour preserved, spelled out so the equivalence is checkable:
      #   - `cache-hit != 'true'` reproduces the combined action's own "exact
      #     hit on the primary key ⇒ do not save" skip.
      #   - the condition names no status function, so the implicit `success()`
      #     still applies — matching the combined action's `post-if: success()`.
      #   - same `path` and same `key` as the restore step above.
      - name: Save Playwright browsers
        if: >-
          steps.relevant.outputs.should_run == 'true'
          && steps.playwright-cache.outputs.cache-hit != 'true'
        uses: actions/cache/save@v6
        timeout-minutes: 8
        continue-on-error: true
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}

      # The pinned @objectstack build, saved only when this job built it (a cache
      # miss) and whatever the verdict above was -- it does not depend on it.
      # Bookkeeping: bounded and non-fatal (objectui#6577, objectui#7048). The bound
      # is not yet derived from a measured save; re-derive it from this step's runs.
      - name: Save the pinned @objectstack build
        if: ${{ !cancelled() && steps.relevant.outputs.should_run == 'true' && steps.objectstack-build.outcome == 'success' && steps.objectstack-pin.outputs.cache-hit != 'true' }}
        continue-on-error: true
        timeout-minutes: 2
        uses: actions/cache/save@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

  docs:
    name: Build Docs
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          submodules: true

      # Fails OPEN: if the diff cannot be computed the job builds the site,
      # rather than reporting green having built nothing (objectstack#4928).
      # Until objectui#3723 this step swallowed a failed `git diff` into an empty
      # result (`2>/dev/null || echo ""`), which is indistinguishable from
      # "nothing docs-related changed" — a checkout that did not fetch deep
      # enough, a transient git failure or a malformed sha skipped the whole
      # site build and the job still reported success. Measured against a
      # fixture repository: on an unreachable base sha the old spelling yielded
      # `should_run=false`, this one yields `true`; on a reachable base sha both
      # agree, so which pull requests pay for a site build is unchanged.
      - name: Check for docs changes
        id: docs-changes
        run: |
          # `!= pull_request` covers `push` and `merge_group` alike
          # (objectui#3523). A queue build has no `github.event.pull_request`,
          # so the diff below would run on an empty revision range — and that
          # case is NOT caught by failing open: git reads a bare `...` as
          # `HEAD...HEAD` and exits 0 with no output (measured), so it would
          # skip the site build on the last check before `main`. This early
          # return is what covers it.
          if [ "${{ github.event_name }}" != 'pull_request' ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Not a pull request: push is filtered at the trigger, and a merge_group build is the last validation before main. Building the site.'
            exit 0
          fi
          # ── What this job validates, and therefore what must trigger it ──
          # (objectui#8647). Until then this list was `apps/site/` +
          # `content/` alone, which is the *output* surface of the site, not
          # its *input* surface: `pnpm turbo run build --filter='@object-ui/site'`
          # builds the whole workspace closure before it runs `next build`
          # (measured here: 30 tasks, 2m28s with an empty turbo cache), so a
          # change to any of them changes what this job compiles. A pull
          # request touching only `packages/**` therefore reported `success`
          # in seconds having built nothing — and a skipped build and a passed
          # build are the same green to every reader downstream. That is not
          # hypothetical for this repository: objectui#8344's getter-binding
          # route was green on rollup and red on Next/Turbopack, which is why
          # a green here is written into card acceptance criteria at all.
          #
          # ⭐ The list below is DERIVED, not curated, and
          # `scripts/__tests__/docs-build-trigger.test.ts` re-derives it on
          # every pull request and fails when this list stops covering it:
          #   - one entry per workspace package in the site's build closure —
          #     the package-manifest graph reached from `@object-ui/site` over
          #     `dependencies`, `devDependencies` and `peerDependencies` on the
          #     `workspace:` protocol, which is the graph turbo walks for
          #     `^build` (measured against `turbo run build
          #     --filter='@object-ui/site' --dry=json`: 31 entries = these 30
          #     packages plus the site; one of them, `packages/test-support`,
          #     declares no `build` script, so 30 tasks actually execute);
          #   - one entry per root-level input `turbo.json` declares for the
          #     `build` task (`$TURBO_ROOT$/...`), because turbo names them as
          #     things a build's output depends on;
          #   - the four workspace manifests, since they decide which versions
          #     of everything the build resolves.
          # ⇒ Adding a dependency to any of these packages, or a root build
          # input to `turbo.json`, turns that test red rather than quietly
          # narrowing this gate again.
          #
          # One entry is deliberate rather than derived: this workflow file.
          # It is what decides whether and how the site is built, so a pull
          # request that edits it should be validated by the very job it
          # edits — the alternative is changing this gate and getting the
          # 13-second green as the acceptance evidence for the change. It is
          # not `.github/` wholesale: nothing else under there feeds this
          # build, and the pin asserts an unrelated workflow still skips.
          # Measured over the same 400: 2 of them touch this file.
          #
          # What is deliberately NOT here, priced over the 400 most recent
          # merged pull requests: the 11 workspace packages outside the
          # closure (`app-shell`, `auth`, `cli`, `collaboration`,
          # `create-plugin`, `plugin-ai`, `plugin-designer`, `plugin-report`,
          # `plugin-tree`, `runner`, `vscode-extension`) — including them
          # would fire on a further 15 points of pull requests and cannot
          # change what `next build` compiles; and `scripts/**` beyond the
          # entries turbo itself declares, a further 13 points for the same
          # reason. Cost of the list as it stands, measured over those 400 by
          # replaying this exact pathspec against each merge: it fires on 281
          # (70%) where the old list fired on 54 (13.5%) — 227 (56.8%) newly
          # pay for a site build. ⛔ Narrowing it by excluding the tooling
          # files under those packages (238/400, a further 11 points, sound
          # today because every published build program excludes tooling
          # directories) was considered and declined: this gate's whole defect
          # class is under-firing silently, and an exclusion is a second thing
          # that has to stay true for it not to recur.
          if ! CHANGED=$(git diff --name-only \
            '${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}' -- \
            '.github/workflows/ci.yml' \
            'apps/site/' \
            'content/' \
            'examples/schema-catalog/' \
            'packages/components/' \
            'packages/core/' \
            'packages/data-objectstack/' \
            'packages/fields/' \
            'packages/i18n/' \
            'packages/layout/' \
            'packages/mobile/' \
            'packages/permissions/' \
            'packages/plugin-calendar/' \
            'packages/plugin-charts/' \
            'packages/plugin-chatbot/' \
            'packages/plugin-dashboard/' \
            'packages/plugin-detail/' \
            'packages/plugin-editor/' \
            'packages/plugin-form/' \
            'packages/plugin-gantt/' \
            'packages/plugin-grid/' \
            'packages/plugin-kanban/' \
            'packages/plugin-list/' \
            'packages/plugin-map/' \
            'packages/plugin-markdown/' \
            'packages/plugin-timeline/' \
            'packages/plugin-view/' \
            'packages/providers/' \
            'packages/react/' \
            'packages/react-runtime/' \
            'packages/sdui-parser/' \
            'packages/test-support/' \
            'packages/types/' \
            'scripts/build-plugin-stylesheet.mjs' \
            'scripts/check-dist-completeness.mjs' \
            'scripts/invoked-as.mjs' \
            'scripts/vite-*.ts' \
            'scripts/vitest-invocation-guard.mjs' \
            'tsconfig.json' \
            'tsconfig.tier-base.json' \
            'package.json' \
            'pnpm-lock.yaml' \
            'pnpm-workspace.yaml' \
            'turbo.json'); then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Could not diff against the merge base. Building the site rather than skipping silently.'
            exit 0
          fi
          if [ -n "$CHANGED" ]; then
            echo 'should_run=true' >> "$GITHUB_OUTPUT"
            echo 'Files the site build consumes changed:'
            echo "$CHANGED"
          else
            echo 'should_run=false' >> "$GITHUB_OUTPUT"
            echo 'Nothing the site build consumes changed. Skipping the steps below; this check still reports.'
          fi

      - name: Enable Corepack and download the pinned pnpm
        if: steps.docs-changes.outputs.should_run == 'true'
        run: bash scripts/ci-setup-pnpm.sh

      - name: Verify pnpm version
        if: steps.docs-changes.outputs.should_run == 'true'
        run: pnpm --version

      - name: Setup Node.js
        if: steps.docs-changes.outputs.should_run == 'true'
        uses: actions/setup-node@v7
        with:
          node-version: '22.x'
          cache: 'pnpm'

      # The docs *link* check is deliberately NOT here any more — do not add it
      # back. `node scripts/check-doc-links.mjs` ran in this job from #3213 /
      # #3292 (PR #3450) until #3448 promoted it to its own workflow,
      # `docs-links.yml` (a step of `repo-gates.yml` since objectui#12214), with no
      # path filters. The reason THEN was this
      # workflow's own `paths-ignore`, which at the time listed `content/**` and
      # `'**/*.md'` on both triggers: GitHub has no per-job path filter, so a
      # docs-ONLY pull request never started `ci.yml` at all and the link check
      # never saw the class of PR most likely to break a link. Since
      # objectui#3523 step 2 that filter is gone from `pull_request` and survives
      # only on `push` (objectui#3857), so the pull-request half of that
      # blindness is gone — the push half is not, and this job still does not run
      # on a docs-only push to `main`. objectui#4381 corrected the present tense
      # this note used to carry. It stays removed rather than kept in both places
      # either way: the standalone workflow's trigger set is a strict superset of
      # this job's, so a copy here could only ever add a second red check for the
      # same broken link, and a second place to forget.
      # `scripts/__tests__/docs-links-workflow.test.ts` pins the gate to exactly
      # one home.

      # ── Cache bookkeeping cannot void a recorded verdict (objectui#7048) ──
      # THE ORDERING, carried here from the type-check split (objectui#6577,
      # PR #7047) because it is what a future reader needs in order to judge
      # whether these steps may be touched: the verdict is recorded by the
      # checking steps; everything after them is bookkeeping, and bookkeeping
      # must never discard an answer the gate already produced.
      #
      # Why the SPLIT rather than a timeout on one step: combined
      # `actions/cache` declares `main: dist/restore/index.js` plus
      # `post: dist/save/index.js`, so its save is a step the RUNNER generates
      # at job end (`Post Turbo Cache`). No workflow syntax attaches
      # `timeout-minutes` or `continue-on-error` to a generated post step, so
      # an upload stall runs the job into `timeout-minutes: 15` — the TIGHTEST
      # ceiling of this workflow's three cached jobs — the job goes
      # `cancelled`, and the merge queue cannot tell `cancelled` from
      # `failure`. Measured once, on the type-check cache: a 1-second save took
      # 789s and ejected an all-green pull request (objectui#6577).
      # `actions/cache`'s own `save-always` deprecation text points at this
      # same split.
      #
      # ⛔ Raising `timeout-minutes: 15` is the ruled-out non-fix: a larger
      # ceiling only buys a longer hang, still ends in `cancelled`, and lifting
      # a gate's ceiling weakens the gate.
      #
      # The restore half is deliberately left UNBOUNDED: a restore stall fails
      # BEFORE any verdict exists — a gate that did not run, which is honest —
      # rather than a recorded verdict discarded.
      #
      # ONE restore key, this job's own prefix (objectui#12276, the shape the
      # `type-check` job above took in objectui#12222). Until then a bare
      # `turbo-<os>-` key followed this one, and when the job's own prefix
      # found nothing it matched any job's cache -- `Lint`'s, the bundle and
      # release builds' -- which this job then saved again under its own key.
      # Pull-request and queue runs save nothing now (see the prune step
      # below), so on those refs this key falls through to `main`'s entry.
      - name: Restore Turbo Cache
        id: turbo-cache
        if: steps.docs-changes.outputs.should_run == 'true'
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: turbo-${{ runner.os }}-docs-${{ github.sha }}
          restore-keys: |
            turbo-${{ runner.os }}-docs-

      # objectui#12957: every @objectstack/* package resolves to the build of the
      # commit `.objectstack-sha` pins, read from node_modules/.cache/objectstack, so
      # it must be there before pnpm resolves anything. Restored by the pin and built
      # only on a miss (scripts/objectstack-pin.mjs); the save is this job's last step.
      - name: Restore the pinned @objectstack build
        id: objectstack-pin
        if: steps.docs-changes.outputs.should_run == 'true'
        uses: actions/cache/restore@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}

      - name: Build @objectstack at the pin (skips a restored build)
        id: objectstack-build
        if: steps.docs-changes.outputs.should_run == 'true'
        run: node scripts/objectstack-pin.mjs build

      - name: Install dependencies
        if: steps.docs-changes.outputs.should_run == 'true'
        run: pnpm install --frozen-lockfile

      # `TURBO_RUN_SUMMARY` makes turbo write its run summary to `.turbo/runs/`;
      # it changes nothing turbo runs or caches, and `Report what the turbo
      # cache replayed` below reads it (objectui#12276).
      - name: Build Site
        if: steps.docs-changes.outputs.should_run == 'true'
        env:
          TURBO_RUN_SUMMARY: 'true'
        run: pnpm turbo run build --filter='@object-ui/site'

      # REPORT-ONLY, by the 2026-09-06 ruling on objectui#7851, and it must stay
      # that way until somebody rules otherwise. The class it censuses has four
      # known members and three are OPEN (objectui#7440, #7444, #7838), so a
      # blocking gate here would go red on other people's cards the day it
      # landed. The script prints its findings and exits 0; it exits 1 only when
      # the INSTRUMENT is broken — a derivation that matched nothing, a missing
      # spec artifact, or a failed built-in control — because a census that runs,
      # goes green and looked at nothing is the counterfeit this whole check
      # exists to avoid (objectstack#4928, objectui#4690). ⛔ That is why there is
      # no `continue-on-error` here: it would swallow exactly the failure that
      # must be loud, and it is not what makes this step report-only.
      #
      # It sits in THIS job because its surface is `content/docs/**` and this job
      # is the one that already knows whether docs changed; it needs the install
      # (it reads the carriage map out of the built `@objectstack/spec`) and
      # nothing built beyond it. Consequence worth stating: it runs only when this
      # job's own filter fired, so a pull request that touches nothing the site
      # build consumes does not census either. objectui#8647 shrank that blind
      # spot rather than removing it — a `@objectstack/spec` bump moves
      # `pnpm-lock.yaml`, which is now in the filter, so the census does see the
      # bump that moves the carriage map; a change reaching the map by some other
      # route outside the filter is still reported by the next docs PR. A pull
      # request that edits only the gate is covered elsewhere and does not need
      # this step: `scripts/__tests__/check-doc-
      # expression-carriage.test.ts` runs the controls AND the real-tree census in
      # the ordinary vitest suite, which any PR touching `scripts/**` gets.
      - name: Docs expression-carriage census (report-only)
        if: steps.docs-changes.outputs.should_run == 'true'
        run: node scripts/check-doc-expression-carriage.mjs

      # ── What the cache replayed, and only `main` writes it (objectui#12276) ──
      # The `type-check` job's two bookkeeping steps (objectui#12222), for this
      # job's cache. The report reads the summary `Build Site` asked turbo for
      # and puts what the restored cache replayed, what re-ran and the restored
      # key on ONE `::notice` annotation, readable through the check-runs API
      # by anyone who cannot open this log. The prune deletes every entry this
      # run did not use, on `push` and `schedule` only -- the runs that save --
      # so `main`'s entry is exactly the current build outputs instead of
      # every build output any earlier run left behind; pull-request and queue
      # runs restore and never save (see the save step below).
      #
      # Both are bookkeeping after the last checking step, bounded and
      # `continue-on-error`. `timeout-minutes: 1` each is DERIVED FOR THIS
      # SITE: the script reads one run summary and lists one directory, and
      # measured 87 ms on a lint run's summary (objectui#12276); a minute is
      # several hundred times that, and with the save's 5 this job's
      # bookkeeping stays at 7 of its 15 -- inside half the ceiling, which is
      # the rule the save's own derivation below applies.
      - name: Report what the turbo cache replayed
        if: steps.docs-changes.outputs.should_run == 'true' && !cancelled()
        timeout-minutes: 1
        continue-on-error: true
        env:
          RESTORED_CACHE_KEY: ${{ steps.turbo-cache.outputs.cache-matched-key }}
        run: node scripts/report-turbo-cache.mjs

      - name: Prune the turbo cache to what this run used
        if: >-
          steps.docs-changes.outputs.should_run == 'true'
          && (github.event_name == 'push' || github.event_name == 'schedule')
        timeout-minutes: 1
        continue-on-error: true
        run: node scripts/report-turbo-cache.mjs --prune

      # The bookkeeping half of the split documented at the restore step above,
      # placed HERE — after `Build Site`, the step that records this job's
      # verdict — because that is exactly where the post phase it replaces
      # already ran. Nothing about which commits this job accepts or rejects
      # moves with it.
      #
      # `timeout-minutes: 5` is DERIVED FOR THIS SITE, and landing on the same
      # number PR #7047 chose is a result rather than a copy — objectui#7048
      # fences inheriting that 5, so here is this site's own arithmetic. This
      # cache is `.turbo/cache`, and this job's own save of it measured 5s on
      # 2026-09-02 (`Post Turbo Cache`, job 100094597253, a `merge_group` build
      # where this job's steps actually run — on a pull request that touches
      # nothing the site build consumes they all skip). 5 minutes is 60x
      # that, so it cannot fire on a working runner.
      # Ceiling check: 5 x 2 = 10 <= 15, so bookkeeping cannot crowd out the
      # checking steps — whose whole verdict path measured 4m26s on that job.
      #
      # `continue-on-error: true` is the other half, and without it the bound
      # would only trade a `cancelled` gate for a red one. A cache that failed
      # to upload costs the next run some time; it says nothing whatsoever
      # about the code under test, so it must not be allowed to speak for it.
      #
      # Behaviour preserved, spelled out so the equivalence is checkable:
      #   - `cache-hit != 'true'` reproduces the combined action's own "exact
      #     hit on the primary key ⇒ do not save" skip. Note this is the EXACT
      #     hit only: a `restore-keys` prefix match leaves `cache-hit` false
      #     and the save still runs, which is what the combined action did.
      #   - the condition names no status function, so the implicit `success()`
      #     still applies — matching the combined action's `post-if: success()`.
      #   - same `path` and same `key` as the restore step above.
      # One deliberate change (objectui#12276): only `push` and `schedule`
      # save, after the prune step above, as in the `type-check` job.
      - name: Save Turbo Cache
        if: >-
          steps.docs-changes.outputs.should_run == 'true'
          && steps.turbo-cache.outputs.cache-hit != 'true'
          && (github.event_name == 'push' || github.event_name == 'schedule')
        uses: actions/cache/save@v6
        timeout-minutes: 5
        continue-on-error: true
        with:
          path: .turbo/cache
          key: turbo-${{ runner.os }}-docs-${{ github.sha }}

      # The pinned @objectstack build, saved only when this job built it (a cache
      # miss) and whatever the verdict above was -- it does not depend on it.
      # Bookkeeping: bounded and non-fatal (objectui#6577, objectui#7048). The bound
      # is not yet derived from a measured save; re-derive it from this step's runs.
      - name: Save the pinned @objectstack build
        if: ${{ !cancelled() && steps.docs-changes.outputs.should_run == 'true' && steps.objectstack-build.outcome == 'success' && steps.objectstack-pin.outputs.cache-hit != 'true' }}
        continue-on-error: true
        timeout-minutes: 2
        uses: actions/cache/save@v6
        with:
          path: node_modules/.cache/objectstack
          key: objectstack-pin-${{ runner.os }}-${{ hashFiles('.objectstack-sha', 'scripts/objectstack-pin.mjs') }}