ci.yml

name: CI

on:
  push:
    branches:
      - main
  # ⭐ NO `branches:` filter here, deliberately (#16482). A `pull_request:`
  # trigger filtered to `branches: [main]` does not run at all when the PR's
  # base is a feature branch — and a workflow that does not run publishes NO
  # check run, which is an ABSENCE, not a skip. Branch protection reads that as
  # permanently pending, so every required context this file publishes reports
  # nothing on such a PR. Measured on the #14478 stack: six card PRs showed
  # 8-11 light checks and ZERO of the six required contexts; the first real
  # signal arrived at the trunk PR, after every card was written, reviewed and
  # merged. Correctness rested on local runs quoted into PR bodies — a
  # discipline, not a gate.
  #
  # Runner cost of removing the filter, measured 2026-09-08 over the 30 days
  # 2026-08-09 → 2026-09-08 (4000 PRs read, `sort=created&direction=desc` paged
  # until the window closed): 6 of 4000 PRs had a base other than `main`
  # (0.15%), all six the #14478/#15679 stack. At the window's measured 7008
  # pull_request runs per workflow, 0.15% is ~10.5 extra runs per workflow per
  # 30 days ≈ 2.5/week, or ~57 job-runs/week across both files at 23 job-runs
  # per PR event. Even the pessimistic bound — one uncancelled run per one of
  # those PRs' 115 commits — is 1.6% of current pull_request spend. Small, so
  # the trigger is widened unconditionally rather than gated on a label or on
  # "the base is an open PR's head" (#16482 records the arithmetic).
  #
  # ⛔ Do NOT mirror this widening onto the `push:` trigger above. `push:` is
  # per-branch, not per-PR: unfiltering it would run this workflow on every
  # push to every agent branch in the repo, which is a different and far larger
  # population than the 6 PRs measured here.
  pull_request:
  # Merge queue: the queue builds each PR as speculatively merged onto the
  # current main and only lands it if this workflow is green on that result —
  # the race-free version of the "pull main and re-verify before merging"
  # discipline (AGENTS.md multi-agent §7/§10). Every workflow that produces a
  # branch-protection-required check MUST carry this trigger, or queue builds
  # wait forever on a check that never reports.
  merge_group:
  # ── THE SCHEDULED FULL RUN (#16467), every 4 hours since #25771 ──────────
  # `push` above now computes the Test Core package set with `--affected`
  # against `github.event.before`, so a merge no longer re-tests the whole
  # workspace it just tested in the queue. Something still has to run the FULL
  # battery on `main`, on a clock, or "main is green" stops being a statement
  # about the workspace and becomes a statement about the last diff.
  #
  # This is that run. Minute 0 rather than an offset minute ON PURPOSE, and
  # against the sibling convention in test-nightly-tiers.yml: the reading this
  # feeds — `scripts/ci/select-shard-timings-run.mjs` — wants one complete run
  # per window far more than it wants a short queue wait, and a run that starts
  # a few minutes late is still that window's run. What it must NOT do is
  # collide with the next one, which the concurrency group below decides.
  #
  # EVERY 4 HOURS, not hourly (#25771, maintainer ruling Q6 = C): the job logic
  # is unchanged — the run is still the full battery and still finds flakes on
  # an unchanged SHA — at six runs a day instead of twenty-four, most of which
  # re-tested a SHA an earlier run had already tested. Every runner-minute it
  # spends competes with PR and merge-queue capacity.
  #
  # ⛔ This is a NEW TRIGGER KEY, not a widening of `push:`. The ⛔ above still
  # binds: `push:` stays filtered to `main`.
  schedule:
    - cron: '0 */4 * * *'
  # The same full battery, on demand: an operator who has just landed a fix for
  # a red scheduled run should not have to wait up to 4 hours to see it answered.
  # Treated as `full` by the selection script for the same reason `schedule` is.
  workflow_dispatch:

# Superseded runs on the same PR waste runners and delay feedback; cancel them.
# A push to `main` is the opposite case, and gets a group of its OWN (#25373).
#
# ⭐ `github.event.after` IS LOAD-BEARING IN THIS KEY. A push run is the only
# run that tests ITS OWN merge: Test Core computes `--affected` against
# `github.event.before` (see `on.schedule` above), so a push run that does not
# finish leaves that merge's diff with no Test Core verdict on `main` until the
# next scheduled full run. Main merges land every ~9–16 min and a push run takes ~27,
# so under the old shared key `ci-CI-push-refs/heads/main` the next merge
# cancelled it: 31 of 40 push runs on 2026-10-23 01:03Z–11:03Z, most of them
# inside "Run this shard's tests". (The Turbo seed is NOT what was lost: the
# "Save Turbo cache (main only)" steps are `if: always()` and run on a
# cancelled job too.) `cancel-in-progress: false` alone does NOT fix it:
# GitHub keeps ONE pending run per group and cancels it when a third arrives;
# replayed on the same 40 arrivals, 18 still die. So the push segment is the
# pushed commit. `github.event.after` is set on a push and absent on
# `schedule`, `workflow_dispatch` and `merge_group`, which still fall through
# to `github.ref`; on `pull_request` the PR number wins before it is reached.
# Two push runs never share a group, so every one runs to completion. The seed
# key carries `github.sha`, so two overlapping main runs never write the same
# key.
#
# ⭐ `github.event_name` IS LOAD-BEARING TOO (#16467). A `schedule` and a
# `workflow_dispatch` run on `main` both fall through to `refs/heads/main`;
# without the event name they share one group and an on-demand run cancels the
# scheduled one (and, under any key that drops `github.event.after`, the next
# merge cancels both, which is how 36 of 60 hourly-era push runs died).
#
# ⛔ Do not "simplify" either segment away. `scripts/ci/scheduled-full-run.mjs
# --check-concurrency` evaluates this expression against push, schedule,
# dispatch, PR and queue contexts on two different commits. It reds when two
# pushes share a group, when a push shares one with a schedule or dispatch run,
# or when two schedule, dispatch or same-PR runs stop sharing one (a run-unique
# key such as `github.sha` or `github.run_id` would switch cancellation off for
# those events too).
#
# `cancel-in-progress` stays `true`: with a per-commit push group it never
# fires on a push, and for everything else it is the policy. Two scheduled
# runs overlapping means one of them is over 4 hours old, and a 4-hour-old
# measurement of `main` is strictly the worse of the two. Test Core's wall clock
# is well inside the cadence (~39 shard-minutes across the shards), so this is
# the exceptional path, not the normal one.
concurrency:
  group: ci-${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.event.after || github.ref }}
  cancel-in-progress: true

# ── THE TWO SPEEDS (#22998) ──────────────────────────────────────────────────
# A `pull_request` or `merge_group` run carries the FAST SET: `Build Core`,
# `Test Core` (affected-only) and `Build Docs`. `main`'s 4-hourly `schedule` run,
# its `push` runs and an on-demand `workflow_dispatch` carry the FULL BATTERY:
# the fast set plus the four jobs below that spell
#
#     github.event_name != 'pull_request' && github.event_name != 'merge_group'
#
# in their `if:` — `temporal-conformance`, `dogfood` (three shards),
# `dogfood-verify` and `ui-published-artifacts`. Nothing is deleted: the jobs
# moved off the per-PR path, the last one never had one (#26717). A red in one of them is a main-red for the owning lane, and the
# publish lane reads the full battery before its approval (release.yml's
# `full-battery` job, `scripts/ci/scheduled-full-run.mjs --release-gate`).
#
# Spelled as a DENY-list of the two per-PR events on purpose — the filter
# contract's half 1 below, applied to events: a trigger added to `on:` later
# RUNS these jobs, and the failure direction of a wrong guess is a slower PR,
# never a full battery that silently stopped running. `dogfood-gate` keeps
# `if: always()` (check:shard-attestation pins it): with both legs skipped it
# counts zero expected attestations and concludes success, exactly as on a
# filter-skipped diff.

jobs:
  filter:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      pull-requests: read
    outputs:
      # On the `schedule` / `workflow_dispatch` full runs (#16467) everything
      # counts as changed: dorny/paths-filter is skipped there (no diff to
      # resolve), a skipped step's output is the empty string (falsy), and
      # `|| 'true'` supplies the value without touching PR/push behavior.
      #
      # On merge_group the step RUNS (the diff is the queue base_sha against
      # the group head, see the step below), but only the three ui outputs
      # read it. `docs`, `core` and `crosspkg` stay 'true' there through the
      # `github.event_name != 'merge_group' &&` guard: the queue build is the
      # last validation before main, and those jobs run on every entry, as
      # they did before the step ran on this event. On any other event the
      # guard is true and the expression reads exactly as `<output> ||
      # 'true'` did.
      docs: ${{ github.event_name != 'merge_group' && steps.changes.outputs.docs || 'true' }}
      core: ${{ github.event_name != 'merge_group' && steps.changes.outputs.core || 'true' }}
      # Gates the `test` job ONLY, ORed with `core` — see the `crosspkg`
      # filter below and the `test` job's `if:` (#9829, #10015).
      crosspkg: ${{ github.event_name != 'merge_group' && steps.changes.outputs.crosspkg || 'true' }}
      # The objectui tree under `ui/` (objectstack#25677). Three outputs, read
      # together by the five `* UI` jobs at the bottom of this file (Type Check
      # UI, Test UI, Lint UI, Build & E2E UI and Live E2E UI):
      #   ui            — a path under ui/, a root file the ui jobs build from
      #                   (the lockfile, the workspace, turbo.json), or a root
      #                   the ui gates read (every root workflow, the prompts,
      #                   the objectui skill bundle; see the filter below);
      #   ui_consumers  — one of the seven packages objectui installs from this
      #                   tree changed, so the Console is compiled (Type Check
      #                   UI) and built (Build & E2E UI) against the new shape in
      #                   the PR that moves it;
      #   ui_tree       — `ui/package.json` exists in this checkout.
      # On merge_group `ui` and `ui_consumers` come from the queue diff
      # (objectstack#25867): an entry whose merged diff against
      # `merge_group.base_sha` touches no ui path and none of the seven
      # packages skips the five ui jobs, exactly as the same diff does on its
      # PR head; an entry that touches one runs them. If the step fails (the
      # base cannot be fetched, the diff errors), it is `continue-on-error`
      # there, its outputs are empty and `|| 'true'` runs every ui job.
      #
      # `ui_tree` is what keeps the ui jobs SKIPPED, not failed, on a tree that
      # does not carry ui/ yet: `ui` and `ui_consumers` fall back to 'true' on
      # schedule / dispatch (half 1 below), and on push to main a spec change
      # sets `ui_consumers`, so neither path output alone can tell a job there
      # is nothing to build. Its step runs on every event, so the `|| 'true'`
      # fallback is reached only when this job died before it — and then THE
      # FILTER CONTRACT's "run everything" is the intended reading.
      ui: ${{ steps.changes.outputs.ui || 'true' }}
      ui_consumers: ${{ steps.changes.outputs.ui_consumers || 'true' }}
      ui_tree: ${{ steps.ui-tree.outputs.present || 'true' }}
      # ── THE FILTER CONTRACT, both halves (#4928) ──────────────────────────
      #
      # Half 1 is the `|| 'true'` above: when in doubt, RUN EVERYTHING. It
      # covers a missing output VALUE.
      #
      # Half 2 is every downstream `if:` in this file, and it used to be
      # missing. GitHub wraps an `if:` that names no status function in an
      # IMPLICIT success(), so the original `if: needs.filter.outputs.core ==
      # 'true'` had TWO independent paths to "skip" when this job DIED
      # (checkout flake, a dorny/paths-filter fault, the 10-minute timeout):
      # the implicit success() is false, and the output is no longer a
      # trustworthy 'true'. Both roads led to skipping test / dogfood /
      # build-core — and skipped counts as SUCCESS in branch protection, so a
      # single flake here produced a fully green, zero-test-run, mergeable PR
      # with no red signal anywhere.
      #
      # So every downstream job now spells the contract as "skip only when the
      # filter EXPLICITLY said false":
      #
      #     if: ${{ !cancelled() && needs.filter.outputs.<name> != 'false' }}
      #
      # `!cancelled()` displaces the implicit success() (a genuine run-level
      # cancellation still skips — #3668's lifecycle reasoning); `!= 'false'`
      # makes the empty string mean "run", exactly like `|| 'true'` does. This
      # is deliberately robust to BOTH readings of what a failed job's outputs
      # are — null/empty or the `|| 'true'` fallback — because `'' != 'false'`
      # and `'true' != 'false'` are both true. The old form was broken under
      # both, because the implicit success() dominates either way.
      #
      # Third occurrence of this GitHub semantic in one audit; the other two
      # were release.yml's publish-integrity guard and its docker job (#4900).
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7

      # No `if:` on purpose: every event needs this answer, and a skipped step
      # would hand `ui_tree` the `|| 'true'` fallback on a tree without ui/.
      - name: Detect the imported ui/ tree
        id: ui-tree
        run: |
          if [ -f ui/package.json ]; then
            echo 'present=true' >> "$GITHUB_OUTPUT"
            echo 'ui/package.json is present: the ui jobs are scheduled by the ui / ui_consumers outputs.'
          else
            echo 'present=false' >> "$GITHUB_OUTPUT"
            echo 'ui/package.json is absent: every ui job skips on this run.'
          fi

      # ⭐ SPELLED AS AN ALLOW-LIST, never as a deny-list (#16467). This
      # action reads a diff, and only three events hand it one it can resolve
      # unaided: `pull_request` (base vs head), `push` (`event.before` vs
      # `after`) and `merge_group` (the payload's `base_sha` vs `head_sha`; at
      # the pinned v4.0.3, src/main.ts reads both when `base` / `ref` are
      # unset, and src/git.ts fetches the base sha at depth 1 and diffs the two
      # trees, `base..head`). `schedule` and `workflow_dispatch` hand it
      # neither, and under a deny-list spelling they would RUN the action with
      # no resolvable base.
      #
      # That failure direction is the dangerous one: every filter output would
      # come back `false`, `|| 'true'` supplies nothing (the output exists and
      # says `false`), and every downstream `!= 'false'` guard SKIPS — so the
      # scheduled full run would have been an entirely green, entirely empty run
      # of nothing at all. An allow-list makes each new event fail toward
      # THE FILTER CONTRACT's half 1 instead: the step is skipped, its outputs
      # are the empty string, `|| 'true'` fills them in, and everything runs.
      #
      # `merge_group` joined the list for the ui outputs alone (#25867; the
      # three core-side outputs above ignore the step on that event). Its
      # `continue-on-error` is the fail-open half there: a queue build whose
      # base cannot be fetched reads as "run every ui job", never as a red
      # `filter` job. On pull_request and push a failure stays red, as before.
      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
        id: changes
        if: github.event_name == 'pull_request' || github.event_name == 'push' || github.event_name == 'merge_group'
        continue-on-error: ${{ github.event_name == 'merge_group' }}
        with:
          filters: |
            docs:
              - 'apps/docs/**'
              - 'content/**'
              - 'pnpm-lock.yaml'
              - '.github/workflows/ci.yml'
            core:
              - 'packages/**'
              - 'examples/**'
              - 'apps/!(docs)/**'
              - 'package.json'
              - 'pnpm-lock.yaml'
              - 'tsconfig.json'
              - 'tsconfig.base.json'
              - 'tsconfig.test.base.json'
              - 'vitest.preset.mts'
              - '.github/workflows/ci.yml'
              # BUILD INPUTS outside every package (#21202): turbo.json itself,
              # its `globalDependencies`, and each `$TURBO_ROOT$/…` input of a
              # build task Build Core's `pnpm build` runs. A diff confined to
              # one of them moves the build hashes it reaches, and before these
              # entries it matched nothing here, so Build Core skipped and the
              # merge queue ran that build first (PR #21199, turbo.json only).
              # Every core-gated job starts on such a diff, not Build Core
              # alone: each one builds, and turbo re-runs every task downstream
              # of a moved build hash.
              #
              # scripts/check-ci-filter-parity.mjs DERIVES the required set from
              # turbo.json and the root `build` script, and reds while a declared
              # build input is uncovered here, or while a literal entry beside
              # them covers none of them and none of Build Core's guards below
              # (a leftover). `tsconfig.json` and the
              # `packages/cli/...` input are covered by the entries above;
              # `@objectstack/docs#build` (its input is `content/**`) is the
              # docs filter's, since `pnpm build` excludes that package.
              #
              # WIDTH: literal files, not `scripts/**`. Over the 3288
              # first-parent commits of `main` in the 30 days to `1371dc980c`,
              # through picomatch 2.3.1 and 4.0.5 (they agree on every row),
              # `core` matched 2247; these entries add 28, `scripts/**` with
              # turbo.json and tsup.config.ts would add 593, 516 of them diffs
              # touching a `scripts/pm/` tool or a `scripts/check-*` gate.
              - 'turbo.json'
              - 'tsup.config.ts'
              # `@objectstack/skills#build` copies the repository root's
              # `skills/**` into its publish tree, so that catalog is a build
              # input of a task `pnpm build` runs (turbo.json declares it as
              # `$TURBO_ROOT$/skills/**`; check-ci-filter-parity holds it here).
              - 'skills/**'
              - 'scripts/build-input-hash.mjs'
              - 'scripts/check-dev-prereqs.mjs'
              - 'scripts/check-dts-emitted.mjs'
              - 'scripts/check-dts-references.mjs'
              - 'scripts/check-regen-pending.mjs'
              - 'scripts/cli-build-prerequisite.mjs'
              - 'scripts/git-env.mjs'
              - 'scripts/import-prerequisite.mjs'
              - 'scripts/invoked-as.mjs'
              - 'scripts/js-comment-mask.mjs'
              - 'scripts/regen-artifacts.mjs'
              - 'scripts/sync-scaffold-emission-policy.mjs'
              - 'scripts/sync-template-versions.mjs'
              - 'scripts/ts-parse.mjs'
              - 'scripts/tsup-drop-sources-content.mjs'
              - 'scripts/workspace-enumerator.mjs'
              # BUILD CORE'S GUARDS (#21341): every repository script the
              # build-core job's own steps run (named by a `run:` step or
              # reached through its `pnpm check:*` alias) and each one's
              # first-party imports. Build Core is the only job that runs
              # them, so before these rows a diff confined to one started no
              # Build Core and the changed guard ran nowhere before the merge
              # queue (PR #17100 changed only check-lean-entry-closure.mjs;
              # Build Core skipped). A change to the guard runs the guard.
              #
              # Not a hand-kept list: scripts/check-ci-filter-parity.mjs
              # DERIVES the set from the job's steps and reds while a script a
              # step runs is uncovered here, or while a literal row covers
              # neither a build input nor such a script (a leftover of a
              # deleted step). Scripts that are also build inputs
              # (check-dts-emitted.mjs and the helpers the guards import) are
              # covered by the rows above and are not repeated.
              # population-floor.mjs is here because check-dual-build-cjs-
              # loads.mjs imports it.
              #
              # WIDTH: over the 3287 first-parent commits of `main` in the 30
              # days to `96b12b589f`, through picomatch 2.3.1 and 4.0.5 (they
              # agree on every row), `core` matched 2276; these rows add 2.
              - 'scripts/check-dts-closure.mjs'
              - 'scripts/check-dual-build-cjs-loads.mjs'
              - 'scripts/check-lean-entry-closure.mjs'
              - 'scripts/check-sourcemap-no-sources-content.mjs'
              - 'scripts/ci/assert-turbo-remote-cache.mjs'
              - 'scripts/ci/prune-turbo-cache.mjs'
              - 'scripts/population-floor.mjs'
            # Test inputs that live OUTSIDE every package (#9829, #10015). Packages
            # whose suites read across their own boundary declare that radius in
            # scripts/check-cross-package-test-inputs.mjs, and turbo.json mirrors each
            # as a `$TURBO_ROOT$/…` input. The step that pulls those packages back into
            # the affected set, `--union-into` in the `test` job below, is a step
            # INSIDE that job — so when NO filter matches the changed path the job
            # never starts, the union never runs, and the declaration buys nothing at
            # PR time: the merge queue is the first signal, which is the #7802 failure
            # this whole mechanism exists to prevent.
            #
            # Measured by instantiating every one of turbo.json's `$TURBO_ROOT$`
            # declarations to a real tracked file and running it through these filters
            # with picomatch — the matcher dorny/paths-filter uses — under BOTH 2.3.1
            # (what the action's own lockfile resolves and ncc-bundles) and 4.0.5 (what
            # this tree resolves); the two agree on every row. On `0bfbeb70c`, 19 of 64
            # declarations were core=false. #9829 closed the nine rooted at `scripts/`;
            # the four roots added below are the remaining ten (#10015).
            #
            # Deliberately a SEPARATE output rather than a widening of `core`, because
            # it gates ONE job — the `test` job ORs it with `core`, while Build Core,
            # Dogfood and Temporal Conformance stay filtered exactly as they are today.
            # That separation is what makes `content/**` affordable at all. Widening
            # `core` would put the whole core pipeline on every docs PR; here a
            # docs-only diff starts Test Core, whose package set is `turbo ls
            # --affected` (empty for such a diff) UNIONED with the packages whose
            # declarations matched — so it runs the declaring package, not the
            # workspace. Measured through the real `--union-into` on all three
            # content-only commits in the window below: `create-objectstack` alone,
            # all three times, against a positive control where a
            # `packages/lint/src/**` diff unions in @objectstack/spec and
            # @objectstack/core.
            #
            # WIDTH, per entry — each is exactly what some package declared, never a
            # root rounded up:
            #   `scripts/**` and `content/**` are declared verbatim, by
            #     @objectstack/spec and create-objectstack respectively, so the
            #     narrower filter does not exist and a hand-kept list of the paths
            #     inside them is the failure mode #7802 recorded ("a list you must
            #     remember to update"). Eight further single-file `scripts/`
            #     declarations and six narrower `content/docs/…` ones (spec, cli,
            #     dogfood) sit inside the two.
            #   The last four are a single file, a single subtree, a single file and a
            #     single file, because that is what the declarations say — NOT `docs/**`,
            #     `skills/**` or `.github/workflows/**`. Over the last 100 first-parent
            #     commits of `main` at `0bfbeb70c`, three of those roots would newly have
            #     started Test Core on 5, 2 and 3 commits; the declared paths on ZERO.
            #     `skills/objectstack-automation/SKILL.md` joined later (#10178) and was
            #     NOT in that window's measurement — it is declared by @objectstack/rest,
            #     one file, and the `skills/**` root it sits in is still declined here.
            #
            # PRICE, re-measured over that same 100-commit window through this matcher:
            # Test Core scheduling goes 80/100 → 83/100. All three additions are
            # content-only docs commits, and each runs one package's suite.
            #
            # This list is a SECOND recognizer of those declarations and is kept in
            # step with them BY HAND: nothing fails today when a declaration lands in a
            # root no entry here covers. Closing that is #10379.
            crosspkg:
              - 'scripts/**'
              - 'content/**'
              - 'docs/audits/2026-07-unknown-key-strictness-ledger.md'
              - 'skills/objectstack-formula/**'
              - 'skills/objectstack-automation/SKILL.md'
              # @objectstack/spec's scripts/export-list.test.ts corpus gate reads
              # the whole published catalog (#12201). Verbatim per the declaration;
              # it subsumes the two narrower skills entries above, which are left
              # as the packages that declared them spelled them.
              - 'skills/**'
              - '.github/workflows/scaffold-e2e.yml'
              - '.claude/skills/spec-property-retirement/SKILL.md'
              # @objectstack/lint's production-witness suite reads the repo-root
              # SDUI manifest (#12924) — verbatim per the declaration in
              # scripts/cross-package-test-inputs.mjs (check:ci-filter-parity
              # holds this list to the declarations; the examples/ page files
              # the same suite declares are covered by entries the core filter
              # already carries).
              - 'sdui.manifest.json'
              # @objectstack/rest's meta-state-route-doc-spelling test discovers
              # its population instead of listing it (#14561): it asks git for
              # the authored-prose corpus under content/, docs/ and skills/ and
              # judges every file that mentions the route. Verbatim per that
              # declaration. `content/**` and `skills/**` above already cover
              # two of the three roots; this is the third, and the FIRST entry
              # to open the `docs/` root that the WIDTH note above records as
              # declined — declined then because no declaration reached past
              # `docs/audits/...`, and reached now because one does. The
              # narrower audits entry is left as the package that declared it
              # spelled it, exactly as the two narrower `skills/` entries were.
              - 'docs/**'
            # The objectui tree, the root files the ui jobs build from, and the
            # three roots outside ui/ that the ui jobs' gates and tests read
            # (objectstack#25712):
            #   - every root workflow, not ci.yml alone: Lint UI's pre-install
            #     import graph check scans all of `.github/workflows/` for ui
            #     scripts run before an install. ci.yml, the guard itself, is
            #     one of them. Measured over the 211 merges of the 7 days before
            #     this entry: 3 changed another workflow and no ui path;
            #   - `.github/prompts/**`, where objectui's prompts moved in
            #     objectstack#25957 and which Lint UI's prompt-keys check reads;
            #   - `skills/objectui/**`, objectui's skill bundle since
            #     objectstack#26097. Lint UI's skill gates (skills-paths,
            #     skill-examples, skill-eval-tokens, doc-json,
            #     shell-escape-residue) and Test UI's skill readers find it
            #     through `ui/scripts/skill-bundle-root.mjs`.
            ui:
              - 'ui/**'
              - 'pnpm-lock.yaml'
              - 'pnpm-workspace.yaml'
              - 'turbo.json'
              - '.github/workflows/**'
              - '.github/prompts/**'
              - 'skills/objectui/**'
              # turbo.json's `globalDependencies`: every build task hashes
              # them, so they move what the ui jobs build, the SDUI manifest's
              # regeneration included (#26137).
              - 'tsconfig.json'
              - 'tsconfig.base.json'
              - 'tsconfig.test.base.json'
              - 'tsup.config.ts'
              # The committed SDUI manifest, its record, its producer and its
              # offline gate. Build & E2E UI regenerates the manifest and
              # compares it with the committed bytes (#26137), so a diff that
              # moves only one of these still runs that comparison.
              - 'sdui.manifest.json'
              - 'scripts/sdui-manifest.record.json'
              - 'scripts/gen-sdui-manifest-node.mjs'
              - 'scripts/check-sdui-manifest.mjs'
            # The seven packages objectui installs from this tree (the set its
            # `.objectstack-pin` used to pack). A change here compiles and builds
            # the Console in the same PR — the check the retired Spec Shape Gate
            # ran hourly against a clone of objectui main.
            ui_consumers:
              - 'packages/spec/**'
              - 'packages/client/**'
              - 'packages/core/**'
              - 'packages/formula/**'
              - 'packages/lint/**'
              - 'packages/sdui-parser/**'
              - 'packages/types/**'

  # ── WHICH TEST CORE SHARDS START (#26084) ─────────────────────────────
  # The `test` matrix used to be the literal 1..8, so every Test Core run
  # started eight runners, and a shard whose bin was empty paid checkout,
  # install and its package-set selection before printing "No packages on this
  # shard". Measured over the 25 most recent completed pull_request runs on
  # 2026-10-27 (40415024961 to 40426272873): 72 of 168 Test Core shard jobs
  # were empty, 7020 runner-seconds, ~97 s each. A diff that reaches no
  # package (a root script, a doc, a workflow) fills one to three bins of
  # eight.
  #
  # This job runs the shards' own selection and partition ONCE and publishes
  # the indices of the bins that hold work; `test` builds its matrix from
  # them. The plan never re-sizes: the count stays SHARD_COUNT, so a started
  # shard carries exactly the slice it carried before, and only the empty ones
  # are not created. Every shard re-derives the plan from its own package set
  # and reds when its digest differs (`--verify` in "Compute this shard's
  # package set"), so the plan cannot silently disagree with the shards it
  # leaves out. scripts/ci/plan-test-core-shards.mjs carries the reasoning.
  #
  # The price is one serial hop: Test Core's shards start after this job, ~65-95
  # s later (the same checkout + install a shard pays before its selection,
  # measured on run 40426272873's shards), on every run that starts Test Core.
  #
  # Same `if:` as `test`, so the plan exists exactly when the matrix could.
  # Fail-open both ways (THE FILTER CONTRACT): a plan job that dies publishes
  # no outputs, the matrix falls back to its full literal, and the gate counts
  # that same fallback.
  test-plan:
    name: Plan Test Core shards
    needs: filter
    if: ${{ !cancelled() && (needs.filter.outputs.core != 'false' || needs.filter.outputs.crosspkg != 'false') }}
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    outputs:
      shards: ${{ steps.plan.outputs.shards }}
      digest: ${{ steps.plan.outputs.digest }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          # The same history the shards check out: the selection diffs against
          # the PR's merge base, the queue's base_sha or the push's before sha.
          fetch-depth: 0

      # Restore only: the `test` shards save this key.
      - name: Setup workspace
        uses: ./.github/actions/setup-workspace
        with:
          save-store: 'false'

      # Its own self-test, where it runs (check:self-test-wired). Milliseconds.
      # A red here fails this job before it publishes a plan, so the matrix
      # falls back to all eight shards: a broken planner costs runners, never
      # coverage.
      - name: Test Core shard planner self-test
        run: node scripts/ci/plan-test-core-shards.mjs --self-test

      # The event fields are the `test` job's "Compute this shard's package
      # set", verbatim: the plan is that step's answer, computed once.
      - name: Plan this run's Test Core shards
        id: plan
        env:
          OS_SHARD_EVENT_NAME: ${{ github.event_name }}
          OS_SHARD_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          OS_SHARD_PR_PINNED_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          OS_SHARD_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
          OS_SHARD_PUSH_BEFORE_SHA: ${{ github.event.before }}
        run: |
          bash scripts/ci/select-shard-packages.sh
          node scripts/ci/plan-test-core-shards.mjs "$RUNNER_TEMP/turbo-ls.json" \
            --exclude @objectstack/dogfood --github-output "$GITHUB_OUTPUT"

  test:
    # Sharded 8-way BY PACKAGE (6-way until #25376): a core-touching PR ran
    # the affected suite ~11½ min on one 4-vCPU runner — the longest pole in
    # the whole workflow — and at 2 shards the slower shard still ran ~10 min,
    # keeping merge-queue builds at ~11 min end-to-end (#4859).
    # scripts/partition-test-shards.mjs splits the package list into eight
    # deterministic bins balanced on MEASURED per-package test duration
    # (scripts/test-shard-timings.json, generated — see #10472 below) and each
    # shard runs its slice through turbo. NOT the dogfood
    # job's vitest --shard passthrough, deliberately: that works for dogfood
    # because it is ONE package with ~60 files, but applied workspace-wide,
    # vitest 4 hard-fails every package with fewer test files than the shard
    # count — and `--passWithNoTests` converts the failure into running NOTHING
    # on either shard (three packages have exactly one test file today). See
    # the script header for the verification.
    #
    # ── WHY MORE THAN THREE (#10227) ──────────────────────────────────────
    #
    # The per-package durations this job's logs print are CONTENDED WALL
    # CLOCK, not package cost. `--concurrency=4` on a 4-vCPU runner means up
    # to four suites share four cores, so each averages about one core, and
    # the contention factor differs per package (measured spread across six
    # packages: 0.69x-2.05x). Read as cost, those numbers said the two long
    # poles were inherently over #4859's <=7min (420s) line and that no shard
    # count could help. Measured like-for-like against the same suites run
    # ALONE on an idle 4-core box (#10152 / PR #10258), both clear it:
    #
    #   @objectstack/cli    548.6s contended   vs  337.13s alone
    #   @objectstack/spec   496.4s contended   vs  325.31s alone
    #
    # So the thing over the line is the co-tenancy, not the suites. More
    # shards means fewer suites per runner AND four more vCPUs per added
    # shard, because every shard gets its own runner.
    #
    # EIGHT specifically (#25376; six from #22075 until then): sharding is BY
    # PACKAGE, so no shard can finish faster than the heaviest serial task it
    # carries. `@objectstack/cli` (2899.02s on the 2026-10-23 dataset) runs as 3
    # file-level slices whenever a run's own list makes it the serial floor
    # (FILE_SHARDED_PACKAGES and planShards() in the script), each slice placed
    # at its PLAIN weight so every bin keeps the whole-package split's density,
    # and no slicing may put a shard past that split's densest bin (the density
    # cap, densityCap() in the script; the shard-timing drift check below is
    # why). Re-derived with the partitioner's own planShards() and balanceOf()
    # on scripts/test-shard-timings.json, bins of predicted test windows:
    #
    #   4 shards -> max 3733s  mean 3732s  ratio 1.00x   (the CLI runs whole)
    #   6 shards -> max 2489s  mean 2488s  ratio 1.00x
    #   7 shards -> max 2136s  mean 2133s  ratio 1.00x
    #   8 shards -> max 1868s  mean 1866s  ratio 1.00x
    #   9 shards -> max 1661s  mean 1659s  ratio 1.00x
    #  10 shards -> max 1607s  mean 1493s  ratio 1.08x
    #
    # Bins are not wall. A shard's whole packages run four at a time while a
    # CLI slice runs as a serial leg after them, so its tests step reads close
    # to wholeSum / 2.9 + slice. On merge_group run 40155484566 (59 packages
    # executed, the CLI as 3 slices) that model lands within 6.1% of the
    # measured step on the four slowest shards (the two light ones never set
    # the wall); replayed on that run's own list it puts the slowest shard
    # at ~1696s at six (measured 1794s, a slice shard) and ~1436s at eight,
    # -15%. Full dataset list -14%; a 21-package merge_group run (40157571602)
    # -10%, its slice shards at eight carrying almost nothing else. The
    # partitioner's SHARD_COUNT header carries the arithmetic.
    #
    # ⚠ THE ARGUMENT ABOVE USED TO BE MADE IN TEST-FILE COUNTS (bins
    # 415/389/389/389/389/388, spec carrying 415 of ~2360 files). It is now
    # made in measured seconds, because #10472 replaced the weight input: the
    # file count was a proxy that ran ~2.8x off on @objectstack/cli, and the
    # six perfectly count-balanced bins it produced ran 5.0/6.2/6.3/13.6/6.3/
    # 9.0 min in run 32428961038. Weights now come from
    # scripts/test-shard-timings.json — see partition-test-shards.mjs.
    #
    # AND WHY NOT MORE THAN EIGHT. #10472 asked for 6 -> 8 and was refused
    # while spec's 1146.69s was the floor; #25376 widened once the CLI was
    # sliced and spec's 842s repo file was split (#25372). Two floors remain.
    # In bins, spec's whole 1606.55s binds at ten shards (above), and past it
    # max/mean gets WORSE with every shard. In wall, a CLI slice (~960-1010s
    # measured) is serial: at eight the slice shards of a small run already
    # carry little else, so a ninth shard mostly adds a runner. The
    # partitioner's self-test pins the half of this that can fail: at
    # SHARD_COUNT the heaviest item must sit within 1.3x the mean, and when it
    # stops fitting, slicing it below package granularity is the remedy that
    # failure names.
    #
    # ⚠ THE COST, stated because it is real: per-shard fixed overhead is paid
    # once PER SHARD, and the merge queue multiplies it by the speculative
    # build count. Measured over the 512 `Test Core (N/6)` jobs of the window
    # below, job start to the tests step is 1.6 min median (5.5 p90) and the
    # tail after it 0.2 min, so two more shards cost ≈ +3.6 runner-min per run
    # at the median, accepted by the maintainer directive on #25376.
    # `--concurrency=4` is deliberately UNCHANGED here: narrower shards may
    # well want a lower value, but moving both at once makes the next
    # measurement unreadable.
    #
    # Branch protection requires the bare "Test Core" context, which a matrix
    # can never publish again — the test-gate job below carries that name
    # (the #3622 lesson; see dogfood-gate).
    name: Test Core (${{ matrix.shard }}/8)
    needs: [filter, test-plan]
    # "Skip only when the filter EXPLICITLY said no core paths changed" — see
    # THE FILTER CONTRACT on the filter job's outputs (#4928). `scripts` is ORed
    # in, never ANDed: two independent reasons to run this job, and it skips only
    # when BOTH filters explicitly said false, so the contract's "when in doubt,
    # RUN EVERYTHING" posture is unchanged (#9829).
    #
    # The third clause is the plan's (#26084): `[]` is the test-plan job's
    # positive statement that the package set is empty, and only that literal
    # skips. A plan job that died publishes nothing, `'' != '[]'` holds, and the
    # matrix below falls back to all eight shards: half 1 of the contract again.
    if: ${{ !cancelled() && (needs.filter.outputs.core != 'false' || needs.filter.outputs.crosspkg != 'false') && needs.test-plan.outputs.shards != '[]' }}
    runs-on: ubuntu-latest
    # Backstop only — the stall guard on the test steps is the primary
    # detector for a #4250-style hang and fires well before this. 30 min was
    # chosen as ~5× a normal sharded run when a normal run was ~4-6 min, with
    # margin for a cold Turbo cache; the old 45 left a hung job "running" for
    # half an hour past any plausible healthy finish.
    #
    # History: RAISED 30 -> 45 (#16173) while one shard ran the whole CLI and
    # was killed at the 30-minute wall; held at 45 until #22075 cut the CLI
    # into 3 slices (5919483472).
    #
    # ⚠ RE-SIZED 45 -> 50 (#22075), derived so that BOTH stall-guard verdicts
    # land before this wall on every observed run. Window: every completed,
    # non-cancelled CI run whose tested tree carries 5919483472, runs
    # 37917885267 to 37956350887 (2026-10-09 10:29Z-16:03Z): 5 schedule,
    # 6 push, 30 merge_group and 25 pull_request runs, 396 `Test Core (N/6)`
    # jobs; 24 cancelled runs excluded. Slowest job wall per event, in
    # minutes: schedule 21.0, push 20.9, merge_group 24.1, pull_request 27.1;
    # p90 of all 396 is 22.0. Measured with
    # `node scripts/measure-stall-guard-headroom.mjs` over those jobs, the
    # worst p + s (job start to the end of "Run this shard's tests") is
    # 26m38s, on run 37923333449 `Test Core (3/6)`. Three readings set the
    # value, and the largest answer wins:
    #   * the window verdict, a silent freeze killed 10m after the last
    #     output: p + s + 10m = 36m38s;
    #   * the cap-deferred verdict, when the liveness probe sees the suite
    #     still writing: p + s + 20m = 46m38s, inside 50 by 3m22s. It missed
    #     45 on 8 of the 396 jobs and would miss 40 on 60;
    #   * the 80% wall margin: the slowest job wall, 27m05s on that same job
    #     (70 packages executed, the CLI as all 3 slices), is within 80% of
    #     50 (40.0).
    #
    # ⚠ RE-SIZED 50 -> 60 (#25376), with the matrix widened 6 -> 8. The same
    # tool over the 89 completed, non-cancelled CI runs created 2026-10-24
    # 03:00Z-2026-10-25 03:45Z (23 merge_group, 39 pull_request, 16 push,
    # 11 schedule; 512 `Test Core (N/6)` jobs) found 50 already short at six:
    # worst p + s 40m27s (run 40149547507 `Test Core (1/6)`, a red PR shard;
    # healthy worst 37m22s, run 40125226571 `Test Core (4/6)`), so the
    # cap-deferred path needed 60.45m. The slowest shard is the one carrying
    # a CLI slice; eight shards take it down by 10-15% on the replays in
    # partition-test-shards.mjs's SHARD_COUNT header, so s is scaled by 0.90
    # (the smallest gain, the safe side) until a window of eight-shard runs
    # exists. Five readings, the largest answer wins:
    #   * the window verdict: p + s + 10m = 2m03s + 34m34s + 10m = 46m37s;
    #   * the cap-deferred verdict: p + s + 20m = 56m37s, inside 60 by 3m23s;
    #   * the 80% wall margin: the healthy worst job wall, 37m41s at six, is
    #     ~34m40s at eight (7m28s + 26m55s + the 0.3m tail), within 80% of 60
    #     (48.0);
    #   * the #16465 red line, the slowest shard at or under 70% of its
    #     timeout: ~34m40s against 42.0;
    #   * the drift ceiling: that healthy worst step running 1.5x its
    #     prediction (MAX_MEASURED_OVER_PREDICTED, the DRIFT verdict) lands at
    #     7m28s + 26m55s x 1.5 = 47.8m, still a reading before the wall rather
    #     than a kill.
    # The first full-battery run after landing re-takes these on eight-shard
    # jobs and is reported on #25376.
    #
    # ⛔ REVERT CONDITION, restated against measurement, not a card: a value
    # below 60 is allowed only when, on a re-measured window of Test Core
    # runs (`node scripts/measure-stall-guard-headroom.mjs` over the jobs
    # payloads of every completed pull_request, merge_group, push and
    # schedule run in it), BOTH guard verdicts -- the window path
    # (p + s + 10m) and the cap-deferred path (p + s + 20m) -- land before the
    # new value on every observation, AND the slowest `Test Core (N/8)` job
    # wall is at or under 80% of it. Read the pull_request and merge_group
    # runs, not the 4-hourly schedule alone: scheduled runs mostly replay the
    # cache their commit's push run saved. It carries no other expiry — a
    # raise with no revert condition beside it becomes permanent by
    # forgetting — and the stall guard stays the primary hang detector.
    timeout-minutes: 60
    permissions:
      contents: read
    # ⭐ ONLY THE SHARDS WITH WORK START (#26084). The list is the test-plan
    # job's: the indices of the bins `partition-test-shards.mjs` fills at
    # SHARD_COUNT (8) for this run's package set. The count stays 8, so a
    # started shard runs exactly the `--shard k/8` slice it ran before, under
    # the same name, cache key and attestation; a shard whose bin is empty is
    # simply never created. The literal after `||` is the full roster, read
    # when the plan job published nothing (it died or timed out), and the gate
    # reads this same expression, so the two cannot count different rosters.
    strategy:
      fail-fast: false
      matrix:
        shard: ${{ fromJSON(needs.test-plan.outputs.shards || '[1, 2, 3, 4, 5, 6, 7, 8]') }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          # Full history so `turbo --affected` can diff against the PR base.
          fetch-depth: 0

      - name: Setup workspace
        uses: ./.github/actions/setup-workspace

      # Restore-only on PRs: PR-side saves (~5 turbo entries per push) churned
      # the repo's 10 GB Actions cache pool and evicted the main-branch seeds —
      # observed as sudden cold-cache spikes (Build Core 51s → 4m30s). PRs fall
      # back to main's entries via the prefix restore-keys; only main pushes
      # save (the "Save Turbo cache" step at the end of the job). Shard-scoped
      # key: each shard builds/tests a different half of the workspace (same
      # pattern as dogfood). Jobs that used to fall back to this job's
      # namespace fall back to Build Core now — neither single shard builds a
      # superset anymore.
      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-
            ${{ runner.os }}-turbo-${{ github.job }}-

      # PRs and merge-queue builds: only test packages affected by the diff —
      # against the PR base on pull_request, against the group's own
      # `base_sha` on merge_group (#16453). spec sits at the root of the
      # dependency graph, so spec-touching diffs still run (close to)
      # everything — but the many that don't touch spec skip the bulk of the
      # 75-package matrix, and at ~120 queue merges a day that is the bulk of
      # the queue's test compute. Push to main partitions the FULL package
      # list: it gates nobody, and its full run is the ground truth the
      # shard-timings refresh reads. (Spec's suite runs here plain /
      # uninstrumented; the coverage-instrumented pass lives in the nightly
      # coverage-nightly workflow.)
      #
      # !@objectstack/dogfood: the ~7½-minute dogfood suite is the dedicated
      # Dogfood job's whole purpose, and both jobs run under the same `core`
      # filter — without the exclusion every core PR executed the suite twice
      # in parallel, and it dominated this job's critical path.
      #
      # `turbo ls` is experimental; the partition script asserts its output
      # shape loudly so an upgrade that changes it turns into a red step
      # naming the cause, not a silently empty shard. An EMPTY shard file must
      # short-circuit the test step below: `turbo run test` with zero --filter
      # args runs the entire workspace.
      #
      # WHERE THE AFFECTED DIFF STARTS (#6195, the #6129 family's third
      # consumer). The one thing this base must never be is
      # `github.event.pull_request.base.sha`.
      #
      # The payload's `base.sha` is frozen when the PR is OPENED and does not
      # move on `synchronize`. HEAD, meanwhile, is the merge ref
      # (`refs/pull/N/merge`) that the checkout above resolves by default on a
      # `pull_request` event — no `ref:` is given, so this job stands on a merge
      # commit containing everything main has today. Everything main gained
      # while the PR sat open therefore lands between the two, and
      # `turbo ls --affected` reads it as this PR's own changes: packages only
      # SOMEBODY ELSE's merged PR touched get tested on this shard.
      #
      # The direction is conservative — the frozen base is an ancestor of HEAD,
      # so its file set is a strict SUPERSET of this PR's own. Nothing that
      # should run is skipped; what degrades is the optimisation itself, and it
      # degrades with how long the PR has been open. At ~18 merges a day an
      # affected-only shard drifts back toward a full run.
      #
      # Measured on turbo 2.10.7 against a real merge-ref fixture (base branch
      # moved 1 commit touching pkg-b; this PR touched pkg-a only):
      #   TURBO_SCM_BASE=<frozen base.sha>            -> pkg-a, pkg-b
      #   TURBO_SCM_BASE=merge-base(origin/main,HEAD) -> pkg-a
      #
      # Four spellings that look like the fix and are not:
      #   - `base.sha...HEAD` (three dots). Three-dot means
      #     `merge-base(base.sha, HEAD)..HEAD`, and the frozen sha is ALREADY an
      #     ancestor of HEAD, so it IS its own merge base and the set does not
      #     move. Measured: still both packages. (pr-automation.yml records the
      #     same result for its own diff — same fact, one family.)
      #   - `HEAD^1`. Correct on a merge ref and silently wrong the day someone
      #     gives this checkout a `ref:`, where parent^1 becomes the PR's
      #     previous commit. `merge-base` is right under BOTH checkouts.
      #   - Dropping the variable and letting turbo default to `main`. Measured
      #     in a CI-shaped clone: `fetch-depth: 0` populates
      #     `refs/remotes/origin/*`, NOT local heads, so there is no local `main`
      #     — and turbo does not error, it silently returns the ENTIRE
      #     workspace, untouched packages included. Safe, and the whole
      #     optimisation gone.
      #   - `TURBO_SCM_BASE=origin/$BASE_REF`, letting turbo resolve the ref.
      #     Measured correct today, but it rests the shard's package set on
      #     `turbo ls`'s internal choice of dot-ness — undocumented, and
      #     `turbo ls` is experimental (see above). Resolving to a commit here
      #     leaves turbo no choice to make.
      # The selection itself lives in scripts/ci/select-shard-packages.sh:
      # environment in, `$RUNNER_TEMP/turbo-ls.json` out. This step only
      # exports the event's fields, so the same script -- every branch of
      # it -- runs locally and under its self-test (#16453). Per event:
      #   pull_request  affected set against merge-base(origin/<base>, HEAD)
      #   merge_group   affected set against the group's `base_sha`, unioned
      #                 with the same cross-package scans. An EMPTY set is a
      #                 legitimate docs-only group: it reaches the "No packages
      #                 on this shard" exit below, every shard still attests,
      #                 and Test Core is an honest green. It is NOT the #10057
      #                 case, which is pull_request-only (the script says why).
      #   push          affected set against `github.event.before`, the commit
      #                 `main` was on before this merge landed (#16467). A zero
      #                 sha -- a first push, or a force-push that rewrote
      #                 history -- falls back to the FULL list, loudly.
      #   schedule      the FULL list: the 4-hourly run IS the full battery, and
      #   workflow_     the on-demand rerun of it. Neither carries a diff base,
      #     dispatch    and neither should: they are the run that says whether
      #                 the whole workspace is green on `main`.
      - name: Compute this shard's package set
        env:
          OS_SHARD_EVENT_NAME: ${{ github.event_name }}
          OS_SHARD_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          OS_SHARD_PR_PINNED_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          OS_SHARD_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
          OS_SHARD_PUSH_BEFORE_SHA: ${{ github.event.before }}
          # No fallback on purpose: empty means the plan job published nothing
          # and the matrix is the full roster, which `--verify` says and passes.
          OS_SHARD_PLAN_DIGEST: ${{ needs.test-plan.outputs.digest }}
        run: |
          bash scripts/ci/select-shard-packages.sh
          node scripts/partition-test-shards.mjs "$RUNNER_TEMP/turbo-ls.json" \
            --shard ${{ matrix.shard }}/8 --exclude @objectstack/dogfood \
            > "$RUNNER_TEMP/shard-packages.txt"
          echo 'Items on this shard (a package name, or a package plus a k/n file-level slice):'
          cat "$RUNNER_TEMP/shard-packages.txt"
          # The plan this matrix was built from must be this shard's own plan,
          # or a bin the plan called empty could hold a package no shard tests.
          node scripts/ci/plan-test-core-shards.mjs --verify "$RUNNER_TEMP/turbo-ls.json" \
            --exclude @objectstack/dogfood --shard ${{ matrix.shard }} --digest "$OS_SHARD_PLAN_DIGEST"

      # ⭐ A SHARD WHOSE TESTS READ NO `.d.ts` BUILDS ITS CLOSURE WITHOUT THEM
      # (#25375). vitest loads JavaScript, so on most shards every declaration
      # the closure emits -- spec's 6 GB-heap pass, cli's type-checking `tsc`
      # -- is written and never read. `OS_SKIP_DTS=1` goes to $GITHUB_ENV, so
      # both closure builds below, the test step and the shard's main seed all
      # hash in one namespace (turbo.json `globalEnv`).
      #
      # ⛔ EXCEPT a shard carrying a package in DTS_READERS, whose tests compile
      # against BUILT declarations and go red without them (TS7016, or ENOENT
      # on a `dist/*.d.ts`). Measured on 830a63a, the whole Test Core list under
      # `OS_SKIP_DTS=1`, re-measured for the CLI on 43731031 (#25870): red only in
      #   @objectstack/cli       published-subpath-console/-hook-body.pin (its
      #                          own dist/*.d.ts), scaffold-emission-typechecks,
      #                          scaffold-test-script-passes,
      #                          create-in-repo-scaffold-typechecks (spec's .d.ts)
      #   @objectstack/metadata  typescript-serializer-annotation (spec's .d.ts)
      # Every other package's counts matched the DTS-on run but one: spec's
      # root-entry-type-nameability pin skips (by its own design) and runs in
      # lint.yml's built-dist step.
      #
      # ⛔ A SLICED reader keeps declarations on ONE slice, DTS_READER_SLICE
      # (#25870). The CLI's vitest config pins its reader files into slice 1/n
      # (DECLARATION_READER_FILES, packages/cli/vitest.config.ts), so its other
      # slices read no `.d.ts` and skip them like any other shard; the
      # partitioner charges slice 1/n the closure and puts the whole readers
      # here on its shard (DECLARATION_READER_SLICES / DECLARATION_READER_PACKAGES,
      # scripts/partition-test-shards.mjs, whose self-test reads this step back).
      # A whole reader, or the CLI unsliced, keeps them as before. A new test
      # that reads a built `.d.ts` reds the same loud way on a skipping shard:
      # add its package here, or, for the CLI, its file to
      # DECLARATION_READER_FILES.
      #
      # Local cold closure, 65 packages, 4 cores, `--force`: 5m59s with
      # declarations, 1m24s without. The cost is replay: a skipping shard
      # cannot replay Build Core's DTS-on remote artifacts, only the DTS-off
      # ones the queue and main runs of these shards write.
      - name: Choose this shard's declaration build
        run: |
          DTS_READERS='@objectstack/cli @objectstack/metadata'
          DTS_READER_SLICE='1'
          KEEP=""
          while read -r PKG SLICE; do
            for R in $DTS_READERS; do
              [ "$PKG" = "$R" ] || continue
              case "$SLICE" in
                ''|"$DTS_READER_SLICE"/*) KEEP="$KEEP $PKG${SLICE:+ $SLICE}" ;;
              esac
            done
          done < "$RUNNER_TEMP/shard-packages.txt"
          if [ -n "$KEEP" ]; then
            echo "Declarations kept: this shard tests$KEEP, which read built .d.ts."
          else
            echo "OS_SKIP_DTS=1" >> "$GITHUB_ENV"
            echo "Declarations skipped: OS_SKIP_DTS=1 for the rest of this shard."
          fi

      # ⛔ THIS SHARD'S `^build` CLOSURE IS BUILT HERE, ON THE TURBO REMOTE
      # CACHE (#22077), so `Run this shard's tests` REPLAYS it from the local
      # cache instead of building it. Before this step the closure was built
      # inside the test step's own turbo run (the slice step below ran zero
      # iterations from #21487 to #22075). Merge-queue run 37623284168, `Test Core
      # (3/6)`: `Tasks: 72 successful, 72 total` / `Cached: 1 cached, 72
      # total` / `Time: 11m43.373s` for the tests AND their closure in one
      # run. That run cannot read the remote, because `test` / `test:repo`
      # stay off it (Build Core's PINS), so the closure moves here.
      #
      # `--filter=PKG^...` selects PKG's dependencies without PKG: the
      # `^build` closure that `test` and `test:repo` schedule. Measured on
      # 3d9188502e, turbo 2.11.5, all six shards of the local partition: this
      # plan equals the test plan's build tasks, 32 to 63 per shard, with
      # identical hashes, 0 differing and 0 extra, and every one of them has
      # Build Core's hash -- unless the step above set OS_SKIP_DTS (#25375). A `test` task that `dependsOn: ["build"]` (cli and
      # metadata in turbo.json) also needs its OWN package's build. This filter
      # leaves that out on purpose, so a shard never builds a package its tests
      # do not need; the test step builds it as before. Today that is
      # `cli#build`, on each shard carrying a CLI slice: the slice step below
      # builds it there.
      #
      # Its own guarded step, for the reason the slice step below gives: a
      # guarded SITE is (file, job, step). `.turbo/runs/` stays the test step's
      # alone, because that is what the drift check and the timings capture
      # read: the `--summarize` here is for the remote-cache assertion after
      # this step (#25374), which moves the summary it read out to
      # $RUNNER_TEMP before the tests run. The four TURBO_* lines are Build Core's,
      # verbatim; its "Turbo remote cache (#21186)" comment holds the write
      # rule, the signing and the PINS. ⛔ An empty FILTERS must exit here:
      # `turbo run build` with no filter builds the whole workspace.
      - name: Build this shard's dependency closure
        env:
          NODE_OPTIONS: --report-on-signal --report-signal=SIGUSR2 --report-directory=${{ runner.temp }}/stall-reports
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY || '' }}
        run: |
          FILTERS=""
          if [ -s "$RUNNER_TEMP/shard-packages.txt" ]; then
            while read -r PKG _; do
              [ -n "$PKG" ] || continue
              FILTERS="$FILTERS --filter=$PKG^..."
            done < "$RUNNER_TEMP/shard-packages.txt"
          fi
          if [ -z "$FILTERS" ]; then
            echo "No packages on this shard — nothing to build."
            exit 0
          fi
          mkdir -p "$RUNNER_TEMP/stall-reports"
          node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/test-core-closure-build.log" --stall-minutes 10 \
            --report-dir "$RUNNER_TEMP/stall-reports" -- \
            pnpm turbo run build $FILTERS --concurrency=4 --log-order=stream \
              --summarize --log-file=.turbo/remote-cache/test-core-closure.json

      # Build Core's "Turbo remote cache (#21186)" comment, ASSERTED paragraph.
      # `--if-ran`: an empty shard exits the step above before turbo runs.
      - name: The Turbo remote cache was on for this shard's closure build
        run: |
          node scripts/ci/assert-turbo-remote-cache.mjs --site 'Test Core (${{ matrix.shard }}/8) closure' \
            --log .turbo/remote-cache/test-core-closure.json --if-ran \
            --move-summary-to "$RUNNER_TEMP/turbo-remote-cache"

      # ⛔ A FILE-LEVEL SLICE BUILDS ITS DEPENDENCY CLOSURE HERE, IN ITS OWN
      # GUARDED STEP, so the slice leg in the next step REPLAYS it. Since #19278
      # that leg carries its slice in `OS_TEST_SHARD`, which only the `test`
      # task declares, so its build tasks hash exactly as they do here (61 of 61
      # identical, measured) and it schedules its own closure: this step is no
      # longer what makes the leg correct, only what keeps the closure build off
      # the test step's stall-guard site (see the last paragraph below).
      #
      # Why the step first existed (#16395, when the slice was still a
      # passthrough and the leg was `--only`): turbo folds a run-level
      # passthrough into the hash of EVERY task in the run, not only the task
      # that receives it -- and `-- "--shard=k/n"` was then the whole reason a
      # slice got its own invocation at all. Measured on turbo
      # 2.10.10, `--filter=@objectstack/cli`, `turbo run test ... --dry=json`
      # (60 tasks: 59 `build` + 1 `test`):
      #
      #   plain vs plain             60 identical,  0 changed   <- control, fires
      #   plain vs -- --shard=1/2     0 identical, 60 changed
      #   --shard=1/2 vs 2/2          0 identical, 60 changed
      #
      # So the sliced leg could hit NEITHER the main-seeded Turbo cache restored
      # above NOR the builds the shared leg ran seconds earlier in the SAME job:
      # it re-executed the closure every run, and shards 5/6 and 6/6 -- the two
      # that carry a slice -- paid that closure twice per job. Live reading,
      # `Test Core (5/6)` of run 34193080219 (a `packages/spec` PR, so the
      # affected set reaches cli): the slice leg reported
      # `Cached: 2 cached, 58 total` / `Time: 9m18.941s` while
      # `@objectstack/cli:test` itself measured `Duration 187.49s` -- six of those
      # nine minutes were the duplicate rebuild, on a job that was then standing
      # against a 30-minute wall (#16395's measurement).
      #
      # `turbo run build --filter=$PKG` is that closure and nothing more:
      # measured 59 build tasks, all 59 hash-IDENTICAL to the ones in the
      # passthrough-free test plan (0 differing, 0 extra, and 0 missing against
      # the test's own `^build` closure), so they REPLAY rather than re-execute.
      # `--filter=...^$PKG` was measured too and schedules 12 packages this
      # closure does not need. Locally, back-to-back invocations of this exact
      # command measured `57 cached, 57 total` / `Time: 153ms >>> FULL TURBO` on
      # the second, against `5 cached, 57 total` / `3m45.918s` on the first.
      #
      # ⚠ THIS IS ITS OWN STEP, not a second guarded run inside the step below,
      # because a guarded SITE is the triple (file, job, step) --
      # `measure-stall-guard-headroom` REFUSES to report a verdict when two
      # guarded runs share one, and refusing is right: the two would be judged
      # against the worst reading of their union. `pnpm check:stall-guard-budget`
      # and `pnpm check:stall-guard-headroom` both read this step, so it keeps
      # its own `--stall-minutes` and its own headroom row.
      #
      # A shard with no slice runs zero iterations here. Since #22075 a run
      # whose own list makes `@objectstack/cli` its serial floor cuts it into 3
      # slices on 3 shards (partition-test-shards.mjs planShards(), which
      # prints its decision in "Compute this shard's package set"), so those
      # three shards run one iteration each. Every shard still reaches the
      # step, so its name is a stable site for those two gates.
      - name: Build the sliced package's dependency closure
        env:
          NODE_OPTIONS: --report-on-signal --report-signal=SIGUSR2 --report-directory=${{ runner.temp }}/stall-reports
        run: |
          if [ ! -s "$RUNNER_TEMP/shard-packages.txt" ]; then
            echo "No packages on this shard — nothing to build."
            exit 0
          fi
          mkdir -p "$RUNNER_TEMP/stall-reports"
          while read -r PKG SLICE; do
            [ -n "$PKG" ] || continue
            [ -n "$SLICE" ] || continue
            echo "Slice $PKG=$SLICE — building its dependency closure with no passthrough."
            LOG="$RUNNER_TEMP/test-core-slice-build-$(printf '%s' "$PKG" | tr -c 'A-Za-z0-9' '-').log"
            node scripts/run-with-stall-guard.mjs --log "$LOG" --stall-minutes 10 \
              --report-dir "$RUNNER_TEMP/stall-reports" -- \
              pnpm turbo run build "--filter=$PKG" --concurrency=4 --log-order=stream
          done < "$RUNNER_TEMP/shard-packages.txt"

      # ── Test leftovers, step 1 of 2: the snapshot (#23880, ruling 乙) ──────
      #
      # REPORT ONLY, never a gate; the rationale, the listing and the closed
      # exclusion list are in the `scripts/ci/report-test-leftovers.mjs` header.
      # Taken HERE, after both dependency-closure builds above and before the
      # tests, so the report after the tests can tell what the test run added
      # from what the builds wrote. A package's OWN build (a test task that
      # turbo.json makes depend on `build` without `^`) still runs inside the
      # test step; the report excludes its declared outputs, read from
      # turbo.json on every run. The snapshot goes to $RUNNER_TEMP, outside the
      # tree, or the report would count it.
      #
      # ⛔ No `if:` and no `continue-on-error`: the script exits 0 on every
      # path, by construction (a failure prints one NOT MEASURED warning), so
      # this step cannot fail the shard or withhold its attestation.
      - name: Snapshot the working tree before this shard's tests
        run: node scripts/ci/report-test-leftovers.mjs snapshot --out "$RUNNER_TEMP/test-leftovers/before.json"

      # --concurrency=4: turbo's default (10) oversubscribes the 4-vCPU
      # hosted runner; matching the core count bounds peak memory and the
      # job is CPU-bound anyway.
      # run-with-stall-guard replaces the old `… 2>&1 | tee $log` +
      # `set -o pipefail` idiom: the guard tees combined output to the log
      # itself and propagates the suite's real exit status, so there is no
      # pipe whose status tee could mask (do not reintroduce `| tee`). Its
      # actual job is #4250: a run whose output freezes mid-suite while the
      # job sits in_progress. Silence past --stall-minutes is declared a
      # stall — a labeled red naming the last output line — instead of a
      # 20-minute wait for a human (or the job timeout) to notice. 10 min is
      # ~5× the longest healthy quiet gap.
      #
      # NODE_OPTIONS arms every node process (vitest workers included) to dump
      # a diagnostic report on SIGUSR2; on a stall the guard signals the frozen
      # process group and digests the reports into the log — exact JS stack for
      # a process whose event loop is alive, and a named "no report = blocked
      # loop" verdict for one that is sync-spinning. The next #4250 occurrence
      # identifies its own culprit instead of costing a diagnosis.
      #
      # --log-order=stream is MANDATORY under the guard, not a preference. The
      # guard measures output FLUSHES; turbo's default in CI is grouped log
      # order, which flushes a task's output only when the task ENDS — so a
      # shard whose tail is one task longer than --stall-minutes was killed BY
      # CONSTRUCTION, healthy or not (measured: a healthy cli:test killed at
      # exit 75 with 173/173 files passing in the flush the kill forced). The
      # guard now refuses to wrap a turbo run without this flag. Cost is
      # interleaved logs; the completeness guard below reads the per-line
      # `<pkg>:test:` prefixes stream order emits (a pinned parseSummaries
      # branch), so attribution survives.
      - name: Run this shard's tests
        env:
          NODE_OPTIONS: --report-on-signal --report-signal=SIGUSR2 --report-directory=${{ runner.temp }}/stall-reports
          # The `e2e` and `live` filename tiers run NIGHTLY on main
          # (test-nightly-tiers.yml), not here: `queue` is the per-PR and
          # merge-queue setting, read once in scripts/nightly-tiers.mjs. Spelled
          # explicitly even though unset reads the same, so the setting this
          # required check verifies is written where the check runs.
          # turbo.json hashes it in the `test` task's `env`, which is what lets
          # it reach vitest under strict env mode at all.
          OS_TEST_TIERS: queue
        run: |
          if [ ! -s "$RUNNER_TEMP/shard-packages.txt" ]; then
            echo "No packages on this shard — nothing to test."
            exit 0
          fi
          # Bound vitest's INNER worker pool (#11958). A no-op on a runner with
          # <= 5 cores (it only ever LOWERS vitest's own `cores - 1` default);
          # it exists so a larger runner cannot multiply turbo's outer
          # --concurrency by a host-sized inner pool. Empty on failure, which is
          # vitest's own "use the default" signal. Needs turbo.json's
          # globalPassThroughEnv entry or turbo strips it — see the script header.
          export VITEST_MAX_WORKERS="$(node scripts/vitest-worker-cap.mjs)"
          mkdir -p "$RUNNER_TEMP/stall-reports"

          # Split the shard's ITEMS into the whole packages, which share one
          # turbo run as they always have, and the file-level slices, which
          # cannot: a slice's `k/n` travels as `OS_TEST_SHARD` in the turbo
          # run's environment, and a run has ONE environment — set on the
          # shared run it would reach every package's `test` task, which
          # turbo.json declares it on. (Before #19278 it travelled as a
          # `--shard=k/n` passthrough, which reached every package's vitest: a
          # hard failure on any package with fewer test files than n, or with
          # --passWithNoTests silently no tests at all.) A slice therefore gets
          # its own invocation, filtered to the one package the partitioner
          # sliced.
          FILTERS=""
          SLICES=""
          while read -r PKG SLICE; do
            [ -n "$PKG" ] || continue
            if [ -n "$SLICE" ]; then
              SLICES="$SLICES $PKG=$SLICE"
            else
              FILTERS="$FILTERS --filter=$PKG"
            fi
          done < "$RUNNER_TEMP/shard-packages.txt"

          # Each leg tees to its OWN log — run-with-stall-guard opens the log
          # with 'w', so a second leg pointed at one path would truncate the
          # first leg's output and the completeness guard below would grade half
          # a shard. They are concatenated afterwards, and that concatenation
          # happens even when a leg failed, because a red suite is exactly when
          # the completeness guard earns its keep.
          #
          # ⭐ ONE PACKAGE'S RED STOPS NO OTHER PACKAGE (#23191; #23177 ruling B,
          # item A1, comment 6139629628). Both turbo invocations below pass
          # `--continue=dependencies-successful`: a failed `test` task no longer
          # cancels the tasks still queued beside it, and only a task whose own
          # dependency failed is withheld, because it would test a broken build.
          # A failed leg no longer skips the legs after it either. Turbo still
          # exits non-zero when any task failed, `STATUS` keeps the FIRST
          # non-zero exit, and the step exits with it, so the shard is red
          # exactly when it was before — and now names every red package of the
          # shard in one run instead of the first one turbo reached.
          #
          # Measured before this was written: a three-package probe (turbo
          # 2.11.5, `a#test` exits 1, `c` depends on `a`) ran `b` and `c` to
          # completion and exited 1 with `Failed: a#test`; without the flag the
          # same run stopped at `a` (`Tasks: 1 successful, 4 total`), also exit
          # 1. The flag moves no task hash (`--dry=json` on this tree, plain vs
          # `--continue=dependencies-successful`: 5 of 5 identical), so the
          # main-seeded cache above still replays.
          #
          # What it costs is time on a red shard, and the wall above already
          # holds it. A red leg now runs as long as a green one, and the legs
          # together are the shard's own planned work (each slice is placed at
          # its plain weight), so a red shard takes what a full one takes — the
          # shape of the slowest job the wall above was sized on (27m05s, every
          # package executed and the CLI as all 3 slices). A leg
          # the stall guard kills still lands inside p + s + 20m, the budget
          # the wall was sized to, whichever leg it is: the legs after it are
          # the rest of `s`, not a second suite on top of it. Before this, a red
          # stopped the run early, so the hidden reds cost another CI cycle each.
          #
          # `test test:repo` (#16466): six heavy packages split their suite into
          # two turbo tasks -- `test` (package-local inputs) and `test:repo`
          # (the repo-scanning tests, hashed on the wide `$TURBO_ROOT$` inputs
          # that used to sit on `test`). Naming both runs a split package whole
          # and is a no-op for every package without a `test:repo` script. The
          # per-shard Turbo cache restored above (main-seeded) is what carries
          # an unmoved `PKG#test` across a change outside the package; the
          # completeness guard below reads both tasks' summaries. A slice leg
          # stays `test`-only: the CLI, the one package whose slice wiring is
          # in the tree, is not split. Since #22075 the CLI is cut into 3
          # slices whenever a run's own list makes it the serial floor, so the
          # three shards carrying one run the whole-package leg and then the
          # slice leg, in that order; each slice is placed at its plain weight,
          # so those shards carry correspondingly fewer whole packages.
          STATUS=0
          LOGS=""
          for LEG in __whole__ $SLICES; do
            if [ "$LEG" = __whole__ ]; then
              [ -n "$FILTERS" ] || continue
              LOG="$RUNNER_TEMP/test-core-packages.log"
              set -- pnpm turbo run test test:repo $FILTERS --concurrency=4 --continue=dependencies-successful --summarize --log-order=stream
            else
              PKG="${LEG%%=*}"
              SLICE="${LEG#*=}"
              LOG="$RUNNER_TEMP/test-core-slice-$(printf '%s' "$PKG" | tr -c 'A-Za-z0-9' '-').log"
              # THE SLICE RIDES IN `OS_TEST_SHARD` (#19278), a variable turbo.json
              # declares on this package's `test` task and its vitest.config.ts
              # reads into vitest's `shard` (vitest 4.1.11 reads no shard
              # variable of its own). Not a `-- --shard=k/n` passthrough, and so
              # neither `--only` nor `--force`. The partitioner's `--self-test`
              # fails a package it can slice whose config or task does not.
              #
              # Why the two flags existed, and why they are gone:
              #
              #   `--only` (#16395). Turbo folds a run-level passthrough into the
              #   hash of EVERY task in the run (turbo 2.10.10, cli's plan, plain
              #   vs `-- --shard=1/2`: 0 of 62 hashes identical), so the leg
              #   re-hashed and rebuilt the `^build` closure the step above had
              #   just built. `--only` scheduled the test alone -- and dropped the
              #   closure out of the test's HASH with it (#18671), leaving the
              #   package's own files plus the hand-declared `$TURBO_ROOT$`
              #   inputs. A slice in the affected set (on a PR, queue or push run
              #   this shard's set IS the affected set) could then match a
              #   main-seeded entry across the very change that put it there.
              #   Run 34746808828 did: it replayed `@objectstack/cli:test` on
              #   this leg -- `Cached: 1 cached, 1 total`, `73ms >>> FULL
              #   TURBO` -- out of a log a main push run had produced ~15
              #   minutes earlier, on a commit that did not contain the PR under
              #   test. All six shards reported success,
              #   `check-test-completeness` graded the replay OK, the shard
              #   attestation said "ran to completion", and the red reached
              #   `main`. Neither of those two can tell a run from a replay.
              #
              #   `--force` (#18671, PR #19271). Made the leg execute; a constant
              #   bypass cannot alarm, and the hash stayed blind to the closure.
              #
              # A declared env reaches ONLY the task that declares it: same plan,
              # plain vs `OS_TEST_SHARD=1/2` is 61 of 62 identical, the one that
              # moves is `cli#test`, and `1/2` vs `2/2` moves that one alone. The
              # closure keeps the hashes the step above gave it (61 of 61 equal
              # to `turbo run build --filter=$PKG`) and replays, while the test's
              # hash carries the closure again. `cli#test`, `--dry=json`:
              #
              #   this leg, OS_TEST_SHARD=1/2          clean  1ee03ac2f26389a6
              #     + packages/spec/src/ui/view.zod.ts        04eabd0b5a9db364  moves
              #     + packages/types/src/env.ts               4b15652b8c493471  moves
              #     + connector-slack/src/* (not in closure)  1ee03ac2f26389a6  still (control)
              #   old leg, --only --force -- --shard=1/2
              #     clean / + view.zod.ts                     d5e7ec263710fe59  still (the defect)
              #
              # Executed (cli, slice 1/16 for time; `packages/client/src/index.ts`
              # edited -- a cli dependency no `$TURBO_ROOT$` input names -- then
              # the step above rebuilt the closure, 57 of 59 cached):
              #
              #   old leg, no --force  `cache hit, replaying logs`  69ms FULL TURBO  <- NOT RUN
              #   old leg, --force     `cache bypass, force executing` (same hash)   <- runs
              #   this leg             `cache miss, executing`, 59 of 60 cached      <- runs
              #
              # and on an unchanged tree this leg replays (`60 cached, 60 total`,
              # 104ms): with the closure in the hash a HIT means these inputs were
              # already tested, which is why no `--force`. Cost: 62 tasks planned,
              # 59 HIT / 3 MISS against the cache the step above fills (the test,
              # plus two `#build` tasks of packages with no `build` script, which
              # never execute), where the passthrough without `--only` was 62 MISS.
              # The step above is no longer load-bearing for correctness -- this
              # run schedules its own closure -- but it keeps that build on its
              # own stall-guard site, and here it replays. `--summarize` records
              # the slice only as the sha256 of `OS_TEST_SHARD` (`cliArguments`
              # is empty); measure-test-shard-timings.mjs resolves that digest
              # against the k/n the partitioner can emit and refuses one it
              # cannot, so a slice is never timed as the whole package.
              set -- env "OS_TEST_SHARD=$SLICE" pnpm turbo run test "--filter=$PKG" --concurrency=4 --continue=dependencies-successful --summarize --log-order=stream
            fi
            LOGS="$LOGS $LOG"
            node scripts/run-with-stall-guard.mjs --log "$LOG" --stall-minutes 10 \
              --report-dir "$RUNNER_TEMP/stall-reports" -- "$@" || {
              CODE=$?
              if [ "$STATUS" -eq 0 ]; then STATUS=$CODE; fi
            }
          done

          # Only over logs that EXIST, and via an explicit `if` rather than a
          # `&&` chain: a leg whose guard never got far enough to open its log
          # would otherwise make `cat` non-zero, and under `set -e` that replaces
          # the SUITE's exit status with cat's — the step would report the wrong
          # reason for its own red.
          : > "$RUNNER_TEMP/test-core.log"
          for LOG in $LOGS; do
            if [ -f "$LOG" ]; then
              cat "$LOG" >> "$RUNNER_TEMP/test-core.log"
            fi
          done
          exit $STATUS

      # ── Test leftovers, step 2 of 2: the report (#23880, ruling 乙) ────────
      #
      # Every path this shard's test run ADDED to the working tree since the
      # snapshot, ignored paths included -- `.objectstack/` is gitignored, so
      # `git status` cannot see that class -- grouped by package directory: a
      # table in the job summary and one `::warning::` annotation per package.
      # Placed directly after the test step so no later step's writes are
      # charged to the tests, and `if: always()` so a red shard still reports.
      #
      # ⛔ REPORT ONLY by ruling, never a gate: the script exits 0 on findings,
      # on a missing snapshot and on a crash, so the step carries no
      # `continue-on-error` and cannot fail the shard. Making it block is the
      # maintainer's word, not an edit here. It stays ABOVE the attestation
      # pair at the bottom of the job (#6082), like every step after the tests.
      - name: Report what this shard's tests left in the working tree
        if: always()
        run: |
          node scripts/ci/report-test-leftovers.mjs report \
            --before "$RUNNER_TEMP/test-leftovers/before.json" \
            --label "Test Core (${{ matrix.shard }}/8)"

      # --summarize above costs nothing at runtime and writes
      # `.turbo/runs/<id>.json`: one per-task record with the execution window
      # turbo actually observed. That file IS the balancing input for the next
      # shard split (scripts/test-shard-timings.json is generated from it), and
      # publishing it here is what keeps the dataset re-measurable instead of
      # hand-frozen — refreshing it becomes "download every shard's artifact from
      # any green run and re-run the generator", with no special measurement
      # run and no CI time spent measuring.
      #
      # `if: always()` so a shard that went red still publishes what it timed;
      # the generator refuses failed and cache-replayed tasks on its own side,
      # so a partial upload contributes nothing rather than something wrong.
      #
      # ⛔ This step must stay ABOVE the attestation pair at the bottom of the
      # job. check-shard-attestation.mjs requires `--emit` + upload-artifact to
      # be the job's LAST TWO steps, because anything after them can fail the
      # job while the credential already counts as a pass (#6082). Adding an
      # upload here is fine; moving it below them is not.
      #
      # continue-on-error: this upload is diagnostics-only (`if: always()` and
      # `if-no-files-found: ignore` already say so), but being unguarded still
      # put it on the shard's pass/fail path: a failed *finalize* aborts the
      # job before the attestation pair below ever runs, so a platform-side
      # fault here evicted a fully green shard from the merge queue (#14469 —
      # FinalizeArtifact 403 on a 313-byte upload, content already stored).
      # The attestation pair is untouched by this flag and remains the
      # fail-closed credential exactly as before — it still runs, still has
      # no `continue-on-error`, and still must succeed (#6082 unweakened).
      # ⛔ Do not add continue-on-error, a retry, or an `if:` to the
      # attestation pair below to "match" this step — that pair is the
      # credential, not diagnostics, and check:shard-attestation pins its
      # unguarded shape statically.
      # Retention: 4 days on a `schedule` run, 1 day otherwise (#25771). The
      # weekly shard-timings refresh accumulates the scheduled runs whose
      # summaries are still downloadable; hourly, one day held 24 of them, and
      # at every 4 hours it takes four days to hold the same 24. Every other
      # event's summary is read only inside its own run, so it stays at 1 day.
      - name: Publish this shard's turbo run summary
        if: always()
        continue-on-error: true
        uses: actions/upload-artifact@v7
        with:
          name: test-core-run-summary-${{ matrix.shard }}-of-8
          path: .turbo/runs/
          if-no-files-found: ignore
          retention-days: ${{ github.event_name == 'schedule' && 4 || 1 }}

      # ── Predicted vs measured: this shard's timing drift (#16173, #16465) ──
      #
      # partition-test-shards.mjs `--check-drift` reads back the summary the
      # step above uploads and compares this shard's MEASURED test total with
      # what the split PREDICTED for the same packages. One ratio,
      # measured/predicted, and four verdicts on it:
      #
      #   OK            at or under 1.3x (WARN_MEASURED_OVER_PREDICTED)
      #   WARN          past 1.3x, at or under 1.5x: a `::warning::` annotation
      #                 naming the shard and its heaviest overshoot; green
      #   DRIFT         past 1.5x (MAX_MEASURED_OVER_PREDICTED): a second
      #                 `::warning::` annotation, the upper tier; green
      #   NOT MEASURED  no executed test task carried a dataset entry; green
      #
      # Two thresholds on ONE ratio, and no second rule on wall time against
      # `timeout-minutes`: triage ruled the in-tree 1.5x the upper tier and the
      # card's 1.3x the lower. Both constants, their measured basis and a
      # self-test battery each live in the script.
      #
      # NO EVENT GRADES (#22949 ruling E, item 1, both timing steps:
      # https://github.com/objectstack-ai/objectstack/issues/22949#issuecomment-6125775640).
      # A wall-clock reading on a shared runner measures the run's load as much
      # as the code: the same package reads 82 s on a quiet hour and 209 s on a
      # busy one, 2.56x, past this step's 1.5x bound and the ceilings' 2.0x of
      # weight. The dataset's weights come from a window that was mostly
      # quiet-density and every event, `schedule` included, meets both
      # densities, so busy hours put the same shards past the bound whatever
      # their code does: density, not code.
      # So on `schedule`, `merge_group`, `pull_request`, `push` and
      # `workflow_dispatch` alike the step prints the same verdict, raises DRIFT
      # as a `::warning::` annotation and exits 0. The event reaches the script
      # as `--event "$GITHUB_EVENT_NAME"`, which it requires: a missing one is a
      # refusal, and so is a dataset or run summary that does not parse, and a
      # refusal is still a red step on every event. The rule and its self-test
      # live in the script (timingGateMode); regression detection moves to the
      # dataset refresh's diff (E2, #23059).
      #
      # EXECUTED WINDOWS ONLY. Measurements come from samplesFromSummary() in
      # measure-test-shard-timings.mjs, which drops cache HITs and failed
      # suites, and the prediction is summed over the same executed packages.
      # A replay's near-zero window would read as a shard far FASTER than
      # predicted and vouch for a rotted dataset, so a shard whose packages all
      # replayed is NOT MEASURED, never "fast".
      #
      # NO `if:` and NO `continue-on-error` (the only red left here is a
      # refusal, and a refusal must stay red, so neither is wanted), and ABOVE
      # the attestation pair for the #6082 reason documented on the upload
      # above: a failed unguarded step skips that pair, so a refusal also
      # withholds this shard's attestation, the fail-closed direction. A shard
      # with no packages runs no turbo and writes no summary; that is NOT
      # MEASURED here rather than a usage error from the script.
      #
      # The dataset it reads is scripts/test-shard-timings.json as the 21-run
      # refresh left it (040184752c): the whole CLI at 1738.88s. Since #22075 a
      # shard carrying one of its 3 slices is predicted a third of that, from
      # the slice count the shard's own summary records (the OS_TEST_SHARD
      # digest) rather than from the config, so the ratio stays one shard's
      # executed windows against their own prediction on every run -- the
      # meaning the 1.5x red and the 1.3x warning were written against. The
      # split keeps every shard within the density cap (densityCap() in the
      # script: the whole-package split's densest bin, 1772.65s today), the
      # density those windows were measured at; #22415 packed ~2641s onto three
      # shards and this step redded at 1.52-1.62x until it was reverted.
      # The second sample taken before wiring this, executed windows only, from
      # the `Test Core` timing tables of the main runs after that refresh:
      # shard 1/6 read 0.61x-1.05x on all eight scheduled runs (37416453417 to
      # 37467795959), and no package on any shard read 1.5x, the highest being
      # @objectstack/spec at 1.39x-1.45x on the three runs that executed it
      # (37433381795, 37453598388, 37467882762). spec carries 70% of shard
      # 2/6's prediction, so that shard is the one nearest the warning. Those
      # tables print ten packages, so shards 2-6 were bounded there rather
      # than read whole; this step reads them whole. Per-shard detail: #16465.
      - name: Check this shard's timing drift
        run: |
          shopt -s nullglob
          SUMMARIES=(.turbo/runs/*.json)
          if [ "${#SUMMARIES[@]}" -eq 0 ]; then
            echo "shard-timing-drift: NOT MEASURED -- Test Core (${{ matrix.shard }}/8) wrote no turbo run summary (no packages on this shard)."
            exit 0
          fi
          node scripts/partition-test-shards.mjs --check-drift "${SUMMARIES[@]}" \
            --label "Test Core (${{ matrix.shard }}/8)" --event "$GITHUB_EVENT_NAME"

      # Runs even when the suite failed — that is when it earns its keep. It
      # answers TWO questions about a red suite, and needs both to be able to
      # say anything at all about a green one.
      #
      #   1. Was every test vitest COUNTED actually run (#3812)? A worker dying
      #      at the process level leaves a summary that still leads with
      #      "passed" while falling short of its own declared count — a red
      #      that READS like a pass.
      #   2. Did every package scheduled on this shard report AT ALL (#10032)?
      #      Question 1 is answered from summary lines PRESENT in the log, so a
      #      package that printed nothing contributes no row: neither counted
      #      nor missed, simply invisible. That is why this step is handed the
      #      shard's scheduled package list (and the `turbo ls` document it was
      #      sharded from, which resolves each name to a directory) instead of
      #      grading the log against itself.
      #
      # ⛔ THE OLD NOTE HERE WAS WRONG AND COST A REAL TRIAGE. It read "a red
      # suite plus a GREEN completeness check means real test failures". That
      # inference does not hold for case 2, and #10032 is the bill: Test Core
      # (2/3) failed naming @objectstack/example-showcase#test while this guard
      # printed OK, because the failing package was the one that printed
      # nothing — its complete 5083-line job log mentions that package twice,
      # both times in the error summary, with no vitest output anywhere.
      #
      # ⛔ AND THE REPLACEMENT WAS STILL BLIND, FOR A SECOND REASON — measured
      # on run 32391924279 (`Test Core (3/3)`, job 96499888763, complete 31839-
      # line log). Under grouped log order turbo folds each task into a
      # collapsible `::group::` EXCEPT the one it surfaces as the run's failure,
      # which gets a bare `<pkg>:test` header instead. The guard read groups and
      # prefixes but not that third shape, so the FAILING package — the one it
      # exists to grade — was the one package whose summary it could not
      # attribute, and its "refuse to guess" backstop then withheld judgement on
      # every candidate and exited 0. It printed `OK (24 of 29 …)` under a note
      # naming @objectstack/example-showcase as ungraded: the same green-that-
      # reads-like-a-clearance, one turn of the screw further out.
      # ⇒ The guard now knows all three header shapes, a package named in
      # turbo's `Failed:` roster is judged even when the log holds strays it
      # cannot place, and an ungraded package downgrades the verdict word from
      # OK to PARTIAL and raises a ::warning:: annotation. Only with all three
      # does green cover both questions — which is what makes the dichotomy
      # above true. ⚠ A red HERE can never turn a green shard red: it needs
      # turbo to have named a failed task, and that already failed the run.
      #
      # ⚠ The guard does NOT charge a silent package to this shard when turbo
      # simply never reached it — turbo stops scheduling on the first failure,
      # so an ordinary red suite leaves later packages unrun. Those are printed
      # as notes. See the script header for the two exemptions and the two
      # rules that decide red.
      #
      # ⚠ NOT diagnosed, by either pass: the original zero-output event itself.
      # It has never been reproduced. The 2026-08-20 recurrence was NOT one —
      # that failing suite streamed ~940 lines and a complete summary
      # (`Test Files 21 passed (21)` / `Tests 342 passed (342)`), and failed on
      # a vitest teardown error, not on silence. Read a "zero output" claim as
      # a hypothesis until someone has grepped the WHOLE log for it.
      - name: Test completeness guard
        if: always()
        run: |
          if [ ! -f "$RUNNER_TEMP/test-core.log" ]; then
            echo "No test log — the test step did not get far enough to produce one."
            exit 0
          fi
          node scripts/check-test-completeness.mjs "$RUNNER_TEMP/test-core.log" \
            --scheduled "$RUNNER_TEMP/shard-packages.txt" \
            --package-list "$RUNNER_TEMP/turbo-ls.json"

      # ── Per-file test timings, captured for the aggregator (#16454) ───────
      #
      # Cutting tests is decided per test file BY COST, so the cost has to be
      # visible first. This shard reads the timings it already printed and
      # hands them up; `Test Core` merges every shard's and publishes the table.
      #
      # WHERE THE NUMBERS COME FROM, and why no second test run is needed:
      #   per FILE     the vitest module lines already in `test-core.log`.
      #                Measured before this was written, because the default
      #                reporter appends a file's duration only when the module
      #                HAS one: on run 34317273493 every file line carried its
      #                milliseconds, including files far under the 300ms
      #                slowTestThreshold (which this repo never sets — it picks
      #                the colour, not the presence). So the stream is enough
      #                and no machine-readable reporter is added to the shard's
      #                `timeout-minutes` wall. The script's header carries the
      #                measurement and its control.
      #   per PACKAGE  `.turbo/runs/*.json`, the same `--summarize` output the
      #                step above already uploads — turbo's own execution
      #                windows, the unit scripts/test-shard-timings.json was
      #                measured in, so the drift column compares like with
      #                like. Cache REPLAYS and FAILED tasks are refused there
      #                rather than averaged in as near-zero measurements.
      #
      # ⛔ REPORT ONLY — `if: always()` + `continue-on-error: true`, both
      # load-bearing and for different reasons. `always()` so a red shard still
      # contributes what it timed (a slow suite is most interesting when it has
      # just failed), and `continue-on-error` because an unguarded step here
      # sits on the shard's PASS/FAIL path: it would abort the job before the
      # attestation pair below ever ran, evicting a green shard from the merge
      # queue on a diagnostics fault. That is #14469, measured on the upload
      # step above. This card's ruling is report only, no red.
      #
      # ⛔ These two steps must stay ABOVE the attestation pair at the bottom of
      # the job, exactly like the run-summary upload above:
      # check-shard-attestation.mjs requires `--emit` + upload-artifact to be
      # the job's LAST TWO steps and pins that statically (#6082). Adding steps
      # here is fine; moving them below that pair is not — and ⛔ that pair does
      # not acquire an `if:` or a `continue-on-error:` to "match" these.
      #
      # ⛔ The `--self-test` is deliberately NOT invoked here (#17097). It ran
      # in this step until then, where `continue-on-error` discarded its verdict:
      # the self-test reached an answer nothing could act on, and
      # `check:self-test-wired` was satisfied by an invocation that could not
      # fail. A self-test with no teeth is worse than no self-test, because its
      # presence is what stops anyone from adding a real one. It now runs in
      # lint.yml's `Lint & Repo Gates` job, as `Test-timing parser self-test`,
      # with no `continue-on-error` — so a broken timing parser reddens there
      # while this workflow keeps the report-only property #16454 ruled and
      # #14469 measured the cost of losing. ⛔ Do not re-add it here; giving it
      # teeth in `ci.yml` is exactly the trade-off those two cards refuse.
      - name: Capture this shard's test timings
        if: always()
        continue-on-error: true
        run: |
          if [ ! -f "$RUNNER_TEMP/test-core.log" ]; then
            echo "No test log — the test step did not get far enough to produce one."
            exit 0
          fi
          node scripts/report-test-timings.mjs --capture \
            --log "$RUNNER_TEMP/test-core.log" \
            --summaries .turbo/runs \
            --shard "${{ matrix.shard }}/8" \
            --out "$RUNNER_TEMP/test-timings/shard-${{ matrix.shard }}.json"

      # Retention matches the run-summary upload above (4 days on `schedule`,
      # 1 day otherwise, #25771): the aggregator consumes this minutes later in
      # the SAME run, and the shard-timings refresh reads the scheduled runs'
      # captures beside their summaries. The 14-day retention this card asks
      # for is on the MERGED table, published by `Test Core`.
      - name: Publish this shard's test timings
        if: always()
        continue-on-error: true
        uses: actions/upload-artifact@v7
        with:
          name: test-core-timings-${{ matrix.shard }}-of-8
          path: ${{ runner.temp }}/test-timings/
          if-no-files-found: ignore
          retention-days: ${{ github.event_name == 'schedule' && 4 || 1 }}

      # A stall's full diagnostic reports (JS stacks, libuv handles, heap
      # summary per process) outlive the in-log digest — keep them so a #4250
      # occurrence can be dissected offline. Free when nothing stalled: the
      # directory is empty and if-no-files-found skips the upload. Shard-scoped
      # name so the two matrix jobs don't collide.
      - name: Upload stall diagnostic reports
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: stall-reports-test-core-${{ matrix.shard }}
          path: ${{ runner.temp }}/stall-reports/
          if-no-files-found: ignore
          retention-days: 14

      # ⛔ PRUNE THE SEED TO THIS RUN'S TASKS BEFORE SAVING IT (#25452). The
      # restore step above takes the newest seed by prefix and turbo never
      # evicts its local cache, so a seed saved whole was every seed before it
      # plus this run: on push run 39982654692 all six shard seeds were
      # 2.41-2.44 GB, against 0.048 GB for Build Core's full 76-task build --
      # ~14.6 GB per merge into the 10 GB Actions cache pool, which evicted the
      # seeds PR runs restore. The script keeps the entries the test step's run
      # summary (`.turbo/runs/`) and the closure build's (moved to
      # $RUNNER_TEMP/turbo-remote-cache by the assertion above) name, and drops
      # the rest. No run summary from the test step -- a cancelled run, or an
      # empty shard -- means no save: such a run has no test results to seed,
      # and the previous seed stays the newest. Exits 0 on every run-time path,
      # so it cannot withhold the attestation below.
      - name: Prune the Turbo cache to this run's tasks (main only)
        id: prune-turbo-cache
        if: always() && github.event_name == 'push'
        run: |
          node scripts/ci/prune-turbo-cache.mjs --site 'Test Core (${{ matrix.shard }}/8)' \
            --cache .turbo/cache --run-summaries .turbo/runs \
            --extra-summaries "$RUNNER_TEMP/turbo-remote-cache"

      # Seed the shared Turbo cache from main only (see the restore step
      # above). always(): keep the seed fresh even when a test fails, matching
      # the old actions/cache post-step behavior. Shard-scoped key so the two
      # matrix jobs don't collide.
      - name: Save Turbo cache (main only)
        if: always() && github.event_name == 'push' && steps.prune-turbo-cache.outputs.save == 'true'
        uses: actions/cache/save@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-${{ github.ref_name }}-${{ github.sha }}

      # ── This shard's positive attestation (#6082) ─────────────────────────
      # The credential test-gate counts: "shard N of 6 ran, and every step of it
      # passed". These two steps are LAST and carry NO `if:` — that is what
      # makes the statement true, because an unguarded step runs only when every
      # preceding step of the job succeeded, and nothing after them can fail the
      # job while the credential already counts as a pass.
      # check:shard-attestation enforces both properties statically, so a step
      # appended below here, or an `if:` added to either, is a red lint job
      # rather than a silently weakened credential.
      - name: Attest this shard ran and passed
        run: |
          node scripts/check-shard-attestation.mjs --emit \
            --job test --shard ${{ matrix.shard }} --total 8 \
            --out "$RUNNER_TEMP/shard-attestation"

      - name: Publish this shard's attestation
        uses: actions/upload-artifact@v7
        with:
          name: shard-attest-test-${{ matrix.shard }}-of-8
          path: ${{ runner.temp }}/shard-attestation/
          if-no-files-found: error
          retention-days: 1
          overwrite: true

  test-gate:
    # Stable required-check name for the sharded Test Core matrix — the exact
    # contract dogfood-gate documents below (#3622): branch protection requires
    # the bare "Test Core" context, and once the job is a matrix that context
    # can never appear again, deadlocking every PR. Keeping the contract HERE
    # means a future shard-count change cannot deadlock the repo. `name:` and
    # `if: always()` are therefore both load-bearing: this must not become
    # `if: !cancelled()` (see dogfood-gate), and it must not be renamed.
    # Both halves are now asserted rather than only written down: the `name:`
    # literal by `check:required-contexts` (#6865), the `if: always()` and the
    # attestation roster by `check:shard-attestation` (#6082).
    #
    # ── It COUNTS credentials; it does not read one aggregate word (#6082) ──
    #
    # This gate used to decide from `needs.test.result` alone, passing on
    # `success|skipped|cancelled` and failing on everything else. One datum
    # cannot carry three shards' verdicts, and two measured defects followed:
    #
    #   - run 31120902911: the queue discarded shards under runner starvation
    #     (runner_id 0, no `steps`, zero tests executed), the aggregate read the
    #     undocumented `abandoned`, the `*)` fallthrough painted red, and #6010
    #     was evicted 31 seconds later. Whitelisting `abandoned` was REJECTED
    #     (maintainer, 2026-08-07): that run was NOT moot — the queue was still
    #     consuming its verdicts — so passing it would publish `Test Core:
    #     success` over zero test runs, exactly what #4928 blocks.
    #   - run 31114735713: shard `Test Core (3/3)` concluded `failure` while
    #     this gate's read of the same matrix was `abandoned`. A lifecycle value
    #     in the aggregate SWALLOWS whatever the siblings concluded — so the
    #     bug was never really about one missing word.
    #
    # So the verdict is now: every shard the matrix DECLARES must publish an
    # "I ran and passed" artifact, and the gate must count all of them. A shard
    # that was never scheduled publishes nothing and cannot be counted; a shard
    # that failed publishes nothing either. `cancelled` (#3668) and
    # filter-`skipped` (#4928) keep their existing meanings — see the script.
    #
    # The DECLARED roster is the PLANNED one since #26084: the `test-plan` job
    # starts only the shards whose bin holds a package, so the gate counts
    # those, read from the same expression the matrix reads (`OS_TEST_PLAN`
    # below; check:shard-attestation holds the two byte-identical). A plan of
    # `[]` skips the matrix and expects zero credentials, as a filter skip does.
    name: Test Core
    needs: [test, filter, test-plan]
    # ── ROSTER DECLARATION (#10490) ───────────────────────────────────────
    # What this required aggregate stands in for, stated rather than inferred.
    # `node scripts/check-aggregator-roster.mjs` asserts MEMBERS + NON_MEMBERS
    # equals `needs:` EXACTLY, in both directions, so a lane added to this
    # workflow and forgotten here cannot ride green behind "Test Core" as an
    # advisory check-run, and a `needs:` entry whose job was deleted cannot
    # keep being claimed. `filter` is a non-member on purpose: it is consulted
    # for the #4928 skipped-only-when-filter-succeeded guard, not aggregated —
    # and having somewhere to SAY that is what stops the roster from being
    # widened to launder a red. `test-plan` is a non-member for the same kind
    # of reason: it supplies the roster (#26084), it carries no verdict. The
    # members are cross-checked against the `--leg` tokens below, so this
    # declaration cannot drift into a second source of truth for what
    # check:shard-attestation counts.
    env:
      OS_AGGREGATOR_MEMBERS: test
      OS_AGGREGATOR_NON_MEMBERS: filter test-plan
    if: always()
    runs-on: ubuntu-latest
    timeout-minutes: 10
    # `actions: read` + `checks: read` (#22653) pay for ONE question, asked
    # only when the test matrix reads `cancelled` AFTER at least one shard
    # attested: was each shard that did not attest KILLED by its own
    # `timeout-minutes`, or SUPERSEDED by a newer push? The aggregate word is
    # `cancelled` either way, so the verdict reads the cause the platform
    # records on each such shard's own check run (this attempt's jobs list,
    # then that check run's annotations). Both are reads; an unspecified
    # permission is `none`, so neither is reachable without naming it here.
    permissions:
      contents: read
      actions: read
      checks: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7

      # Same-run artifact download needs no permission beyond `contents: read`
      # (`actions: read` is for cross-run/cross-repo only); the two read scopes
      # above are for the cancel-cause read, not for this. continue-on-error:
      # a legitimate filter-skipped run has zero artifacts to match, and an
      # artifact-service fault must reach the verdict as "credentials
      # missing" — fail-closed, with the step's own outcome printed — instead
      # of an opaque red.
      - name: Download test shard attestations
        id: attestations
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          pattern: shard-attest-test-*
          path: ${{ runner.temp }}/shard-attestations
          merge-multiple: true

      - name: Verify test shard results
        env:
          OS_ATTEST_DIR: ${{ runner.temp }}/shard-attestations
          OS_TEST_RESULT: ${{ needs.test.result }}
          OS_FILTER_RESULT: ${{ needs.filter.result }}
          OS_DOWNLOAD_OUTCOME: ${{ steps.attestations.outcome }}
          # The planned roster, spelled exactly as the `test` job's matrix
          # spells it, fallback included: a plan job that died leaves the
          # matrix on 1..8, and the gate then counts 1..8 too (#26084).
          OS_TEST_PLAN: ${{ needs.test-plan.outputs.shards || '[1, 2, 3, 4, 5, 6, 7, 8]' }}
          OS_TEST_PLAN_RESULT: ${{ needs.test-plan.result }}
          # Read ONLY on the partially-attested-cancelled path above, never
          # otherwise; without it that path fails closed (red, naming the
          # missing token).
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          node scripts/check-shard-attestation.mjs --verify \
            --gate 'Test Core' \
            --dir "$OS_ATTEST_DIR" \
            --filter-result "$OS_FILTER_RESULT" \
            --download-outcome "$OS_DOWNLOAD_OUTCOME" \
            --leg "test/8:$OS_TEST_RESULT" \
            --planned "test=$OS_TEST_PLAN" \
            --plan-result "$OS_TEST_PLAN_RESULT"

      # ── The timing table this gate publishes (#16454) ─────────────────────
      #
      # The slowest 20 test FILES and slowest 10 PACKAGES of this run, each
      # package's measured seconds beside its pinned weight from
      # scripts/test-shard-timings.json, written to the job summary and kept as
      # an artifact for 14 days.
      #
      # ⛔ BOTH STEPS SIT AFTER `Verify test shard results` AND CARRY
      # `if: always()` + `continue-on-error: true`. `Test Core` is the required
      # branch-protection context and the verdict above is the whole reason the
      # job exists; a reporting step must be unable to delay it, displace it, or
      # redden it. Ordering after the verdict is what makes "cannot delay"
      # true, and the two flags are what make "cannot redden" true — a
      # diagnostics fault here (an artifact-service 403 is the measured one,
      # #14469) must not evict a green run. The suite-duration ceiling check
      # at the end of this job reads the same captures and is the one step
      # here that can still red the job, on purpose and only on a refusal (a
      # malformed table or raise record, no `--event`): a package over its
      # ceiling is a `::warning::` on every event, and a capture that never
      # arrived reads NOT MEASURED there, never red.
      #
      # ⛔ Steps, deliberately, NOT a new `needs:` entry: this job's
      # `OS_AGGREGATOR_MEMBERS` / `OS_AGGREGATOR_NON_MEMBERS` block is asserted
      # EQUAL to `needs:` in both directions by check:aggregator-roster
      # (#10490), so widening `needs:` here to reach the shards' artifacts would
      # red that gate and, worse, enlarge what this required context claims to
      # stand for. The shard captures are same-run artifacts and need nothing
      # beyond the `contents: read` this job already has.
      #
      # An EMPTY merge is reported as NOT MEASURED in words rather than as an
      # empty table — the two look identical on a summary page and only one of
      # them needs a person. The tool exits EXIT_PREREQUISITE_NOT_MET there,
      # which `continue-on-error` absorbs while the words stay on the page.
      #
      # BOOTSTRAP WINDOW: the first runs after this lands have shard captures
      # only from shards that ran WITH it. A `pull_request` run always builds
      # its own shards from this ref, so a PR sees a complete table from the
      # first run; there is no back-fill and no window in which this reads a
      # partial merge as a whole one — the "parsed X of Y declared" counter
      # under the table is what says so on every run, including the first.
      - name: Download this run's shard test timings
        if: always()
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          pattern: test-core-timings-*
          path: ${{ runner.temp }}/test-timings
          merge-multiple: true

      - name: Publish the test timing table
        if: always()
        continue-on-error: true
        run: |
          node scripts/report-test-timings.mjs --merge \
            --captures "$RUNNER_TEMP/test-timings" \
            --out "$RUNNER_TEMP/test-timing-table/test-timing-table.md" \
            --json "$RUNNER_TEMP/test-timing-table/test-timing-table.json"
          # Echo the table into the JOB LOG as well as the job summary. A job
          # summary is readable in the web UI and by essentially nothing else —
          # there is no REST endpoint that returns one — so without this the
          # only machine-readable copy is the artifact, and reaching that needs
          # an artifact download. The log is the copy a seat, a script or
          # `gh run view --log` can actually read.
          cat "$RUNNER_TEMP/test-timing-table/test-timing-table.md" || true

      - name: Publish the merged timing table artifact
        if: always()
        continue-on-error: true
        uses: actions/upload-artifact@v7
        with:
          name: test-core-timing-table
          path: ${{ runner.temp }}/test-timing-table/
          if-no-files-found: ignore
          retention-days: 14

      # ── The per-package suite-duration ceilings (#16468) ─────────────────
      #
      # A READING, never a red (ruling E, below): a package whose suite ran
      # past its ceiling is one `::warning::` annotation naming it and its
      # slowest test files, and the step exits 0 on every event. Unlike the two
      # reporting steps above it carries NO `continue-on-error`, because a
      # REFUSAL (a malformed table or raise record, no `--event`) is not a
      # timing reading and reds `Test Core` on every event. The
      # ceiling is the package's slowest executed run in the refresh window
      # x 1.25, generated into scripts/test-shard-timings.json (`ceilings`) by
      # the refresh lane and held by every later refresh; it rises only by a
      # ruled entry in the script's RULED_CEILING_RAISES. A `provisional` package prints "no
      # ceiling: provisional" and is not red; a package absent from the dataset
      # prints "no ceiling: new package" and is not red until the first refresh
      # after it lands gives it a ceiling, while a package the dataset knows
      # that lost its row is refused, red. See the script header for the ruling.
      #
      # HERE, in the aggregator, rather than in each shard, because the CLI's
      # file-level slices land on three shards: the three windows are SUMMED
      # and the sum graded against the whole package's ceiling -- the quantity
      # the ceiling was measured in. It reads the shard captures the download
      # step above already fetched (each package's turbo execution window via
      # samplesFromSummary, and every vitest file line); a capture that did not
      # arrive leaves its packages ungraded and says so, never red.
      #
      # NO EVENT GRADES (#22949 ruling E, item 1, both timing steps:
      # https://github.com/objectstack-ai/objectstack/issues/22949#issuecomment-6125775640).
      # A per-package suite wall on a shared runner measures the run's load as
      # much as the package: the same package reads 82 s on a quiet hour (most
      # packages replayed) and 209 s on a busy one (the whole workspace
      # executing), 2.56x, while the ceiling formula (window max x 1.25) allows
      # 2.0x of weight. The window the ceilings come from was mostly
      # quiet-density and every event, `schedule` included, meets both
      # densities, so busy hours put the same near-ceiling packages over
      # whatever their code does: density, not code. So on `schedule`,
      # `merge_group`, `pull_request`, `push` and `workflow_dispatch` alike the
      # step prints the same table, raises each package over its ceiling as a
      # `::warning::` annotation and exits 0. A package whose ceiling is under
      # the absolute floor (20s, CEILING_FLOOR_SECONDS) prints "below floor" and
      # is never over. The event reaches the script as
      # `--event "$GITHUB_EVENT_NAME"`, which it requires; a refusal (a
      # malformed table or raise record, no event) is red on every event. The
      # rule, the floor's reading and their self-tests live in the script;
      # regression detection moves to the dataset refresh's diff (E2, #23059)
      # and the per-file budget.
      #
      # NOT MEASURED, exit 0, while the dataset carries no `ceilings`: they are
      # generated only where the run-summary artifacts are downloadable (the
      # refresh lane), so the first refresh after this lands writes them, and
      # until then every run prints a warning annotation saying so.
      #
      # LAST, after the reporting steps, so the timing table is published
      # whatever this decides. `always()`: it reads only what the shards already
      # captured, so a red shard's packages are graded too.
      - name: Check the per-package suite-duration ceilings
        if: always()
        run: node scripts/check-test-suite-ceilings.mjs --captures "$RUNNER_TEMP/test-timings" --label 'Test Core' --event "$GITHUB_EVENT_NAME"


  # ── Temporal conformance against live, non-UTC servers (ADR-0053 D-A3) ─────
  #
  # The datetime storage work (#3912/#3942) was verified against real servers
  # because every one of its bugs was invisible on all-UTC infrastructure: a
  # zone-naive write resolved in the SERVER's zone on Postgres, mysql2 rendered
  # a Date in the HOST's zone, and a bare YYYY-MM-DD comparand meant a
  # different midnight per dialect. The committed suites are opt-in
  # (OS_TEST_POSTGRES_URL / OS_TEST_MYSQL_URL) and skip without a server, so
  # without this job they would never run in CI and the seam could regress
  # silently — D-A3's exact concern.
  #
  # Every timezone here is deliberately DIFFERENT: servers at +08:00, the Node
  # process at America/New_York, assertions in UTC. Both suites assert they
  # are pointed at a non-UTC server, so a mis-provisioned service fails loudly
  # instead of letting the job pass vacuously — and each test step now asserts
  # the PROCESS zone too, which nothing did before: a dropped `TZ:` line
  # silently returned the whole job to UTC coverage with everything still
  # green.
  #
  # The job also carries the non-SQL half of that axis (core, formula,
  # driver-memory, driver-mongodb, service-analytics) — the other backends the
  # temporal conformance matrix holds to one standard. Its NAME still says
  # "live PG + MySQL" on purpose: it was a required check until #22998 moved
  # the job to the full battery, and its readers (the scheduled run's red card,
  # merge-queue triage history, every instruction that names it) find it by
  # that literal — renaming it is a contract change, not a tidy-up.
  temporal-conformance:
    name: Temporal Conformance (live PG + MySQL)
    needs: filter
    # See THE FILTER CONTRACT on the filter job's outputs (#4928). Full battery
    # only: see THE TWO SPEEDS above `jobs:` (#22998).
    if: ${{ !cancelled() && needs.filter.outputs.core != 'false' && github.event_name != 'pull_request' && github.event_name != 'merge_group' }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read

    # Both service images are pulled from mirror.gcr.io, Google's cache of
    # Docker Hub: the same official image, tag and index digest. Pulled from
    # Docker Hub directly they ride its anonymous per-IP quota, which shared
    # runner IPs exhaust, and `Initialize containers` then fails before any
    # step runs. A Docker Hub login is no fix: secrets never reach fork PRs
    # (#22541).
    services:
      postgres:
        image: mirror.gcr.io/library/postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        ports:
          - 5432:5432
        options: >-
          --health-cmd="pg_isready -U postgres"
          --health-interval=5s
          --health-timeout=5s
          --health-retries=12
      mysql:
        # Real MySQL 8.0. The hands-on verification of #3942 ran on MariaDB
        # 10.11 — the stricter dialect for datetime literals — so this job is
        # the other half of the compatibility claim. `-h 127.0.0.1` forces the
        # ping over TCP: the image's init phase runs mysqld with networking
        # disabled, so a socket ping would report healthy before init finishes.
        image: mirror.gcr.io/library/mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: conformance
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping -h 127.0.0.1 -uroot -proot"
          --health-interval=5s
          --health-timeout=5s
          --health-retries=24

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

      # Service containers cannot override the image command, so the non-UTC
      # zones are set post-start through each server's own mechanism. Echoed
      # back so a provisioning failure is visible in the log — though the
      # suites' own non-UTC guards are the real gate.
      - name: Point both servers at a non-UTC timezone
        run: |
          docker exec ${{ job.services.postgres.id }} psql -U postgres -c "ALTER SYSTEM SET timezone='Asia/Shanghai'"
          docker exec ${{ job.services.postgres.id }} psql -U postgres -c "SELECT pg_reload_conf()"
          docker exec ${{ job.services.postgres.id }} psql -U postgres -tAc "SHOW timezone"
          docker exec ${{ job.services.mysql.id }} mysql -uroot -proot -e "SET GLOBAL time_zone = '+08:00'"
          docker exec ${{ job.services.mysql.id }} mysql -uroot -proot -N -e "SELECT @@global.time_zone"

      - name: Setup workspace
        uses: ./.github/actions/setup-workspace

      # Restore-only (same policy as every other job); falls back to the Build
      # Core namespace because that job builds every package (a superset of the
      # build closure this one needs) and its cache is seeded from main. It
      # used to fall back to Test Core, but that namespace is per-shard now and
      # neither single shard builds a superset.
      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-${{ github.job }}-
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

      # Turbo remote cache (#22077), on all four of this job's build steps: the
      # four TURBO_* lines are Build Core's, verbatim, and Build Core's "Turbo
      # remote cache (#21186)" comment holds the write rule, the signing and the
      # PINS. Each of these plans is all `build` tasks with Build Core's hashes
      # (8, 18, 14 and 31 nodes, measured). The suites between them run vitest
      # through `pnpm --filter`, not turbo, and carry no credentials.
      - name: Build driver-sql and its dependencies
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY || '' }}
        run: pnpm exec turbo run build --filter=@objectstack/driver-sql... --concurrency=4

      # The whole driver-sql suite runs under the skewed process zone — not
      # just the live-server files — so a TZ-sensitive assumption anywhere in
      # the driver's tests fails here before it can ship.
      #
      # run-with-stall-guard: same wiring as Test Core (see the comment there;
      # #4250). Both of this job's test legs have hit the same nondeterministic
      # stall (#4331) — once frozen mid-file in core's kernel.test, once silent
      # for 24 minutes AFTER every suite printed `Done` (a process that never
      # exited) — and each burned the full 30-minute job timeout to end as an
      # uninformative "The operation was canceled". The guard watches output
      # silence, so both shapes become a labeled red naming the last line after
      # 10 quiet minutes, and its process-group kill takes down whatever
      # refused to exit. `--log` is the guard's own tee (mandatory); no
      # completeness guard reads these files yet. The zone-assert `node -e`
      # stays outside the wrapper: a one-shot print cannot stall, and the
      # guard should time the suite only.
      - name: Run driver-sql suite against both live servers
        env:
          TZ: America/New_York
          OS_TEST_POSTGRES_URL: postgres://postgres:postgres@127.0.0.1:5432/postgres
          OS_TEST_MYSQL_URL: mysql://root:root@127.0.0.1:3306/conformance
          # The URL half of the same vacuous-pass hole the `node -e` below closes
          # for the zone (#4245). The temporal conformance MATRIX now runs one
          # cell per dialect (ADR-0053 D-A3 `driver {SQLite, Postgres at
          # minimum}`), and a cell whose URL is missing is an ordinary skip — so
          # losing either of the two lines above would silently return the matrix
          # to SQLite-only coverage and stay green. This flag says "this runner
          # provisioned the servers", which turns that skip into a named red.
          OS_EXPECT_LIVE_DIALECT_MATRIX: '1'
        run: |
          # The axis is only real if the zone actually took. Without this, a
          # dropped `TZ:` line silently returns the job to UTC coverage and
          # everything still passes — the same vacuous-pass hole the live-server
          # suites close by asserting a non-UTC SERVER.
          node -e "const tz=Intl.DateTimeFormat().resolvedOptions().timeZone,off=new Date().getTimezoneOffset();if(!tz||tz==='UTC'||off===0){console.error('process zone is '+tz+' (offset '+off+') — this job must run skewed');process.exit(1)}console.log('process zone: '+tz+' (offset '+off+')')"
          node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/temporal-driver-sql.log" --stall-minutes 10 -- \
            pnpm --filter @objectstack/driver-sql test

      # The non-SQL half of the same axis. `driver-sql` has run under a skewed
      # process zone since #3979, but the other backends the temporal
      # conformance matrix holds to that standard never did — and they are the
      # ones whose correctness rests ENTIRELY on process-zone independence,
      # since they have no server to blame: `storageDatetimeValue` /
      # `storageTimeValue` fold an instant through UTC getters, the filter-token
      # resolver derives "today" from UTC calendar parts, and the analytics
      # bucketer does the same. Swap one `getUTC*` for its local twin and every
      # one of those silently shifts by the host's offset — the exact defect
      # ADR-0053 D-C1 records for a `Date` bound to a Postgres TIME column.
      #
      # Measured before adding this: all five suites already pass under
      # America/New_York (-5/-4, with DST), Asia/Kolkata (+05:30) and
      # Pacific/Chatham (+12:45). So this found nothing on the day it landed,
      # which is what a ratchet is for — it makes the property enforced rather
      # than incidental.
      - name: Build the non-SQL temporal backends
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY || '' }}
        run: >-
          pnpm exec turbo run build
          --filter=@objectstack/service-analytics...
          --filter=@objectstack/driver-memory...
          --filter=@objectstack/driver-mongodb...
          --filter=@objectstack/formula...
          --concurrency=4

      - name: Run the non-SQL temporal backends under the skewed process zone
        env:
          TZ: America/New_York
          # [#21564] The same URL the SQL legs of this job receive, for the
          # postgres service this job already runs. `service-analytics` keys
          # its live-PostgreSQL cells on it (`describe.skipIf(!config)`), so
          # without this line they were named skips here and the job read as
          # though ADR-0053 D-A3's live non-UTC PostgreSQL row had run. Core,
          # formula, driver-memory and driver-mongodb do not read it. No
          # `OS_EXPECT_LIVE_DIALECT_MATRIX` here: no test in this step reads it.
          OS_TEST_POSTGRES_URL: postgres://postgres:postgres@127.0.0.1:5432/postgres
        run: |
          # The axis is only real if the zone actually took. Without this, a
          # dropped `TZ:` line silently returns the job to UTC coverage and
          # everything still passes — the same vacuous-pass hole the live-server
          # suites close by asserting a non-UTC SERVER.
          node -e "const tz=Intl.DateTimeFormat().resolvedOptions().timeZone,off=new Date().getTimezoneOffset();if(!tz||tz==='UTC'||off===0){console.error('process zone is '+tz+' (offset '+off+') — this job must run skewed');process.exit(1)}console.log('process zone: '+tz+' (offset '+off+')')"
          # Stall guard: same wiring and rationale as the driver-sql step above
          # (#4250/#4331) — the "silent after every suite printed Done"
          # occurrence was on THIS leg.
          node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/temporal-non-sql.log" --stall-minutes 10 -- \
            pnpm \
              --filter @objectstack/core \
              --filter @objectstack/formula \
              --filter @objectstack/driver-memory \
              --filter @objectstack/driver-mongodb \
              --filter @objectstack/service-analytics \
              test

      # ── The migration statements, on the live MySQL (#9381) ───────────────
      #
      # `metadata-protocol` builds raw SQL by hand for the three dialects the
      # platform supports, and MySQL is the only one that can fail: it does not
      # run with `ANSI_QUOTES`, so the ANSI `"identifier"` the seed-tenancy
      # backfill used to emit unconditionally was a STRING LITERAL there and
      # every statement was an `ER_PARSE_ERROR`. Nothing surfaced it, because a
      # migration must never fail a boot — every call site turns the failure
      # into a warning, so the symptom was a skipped repair in the log.
      #
      # This rides this job rather than getting its own because this is where a
      # live MySQL already exists. Only the live files run: the rest of the
      # package's suite has no server axis and runs in Test Core.
      #
      # The argument is a FILTER, not the one path it started as (#9434). A
      # second migration in this family needed the same server — `sys_setting`'s
      # degradation report prints an operator query in which `key` is a MySQL
      # reserved word — and a named-path list is the shape where the next such
      # file is added, is green locally because it SKIPS without a server, and is
      # never run here at all. A test that cannot fail reports success.
      #
      # `live-mysql` and not `src/migrations/*.live-mysql.test.ts`: vitest's
      # positional arguments are SUBSTRING filters against the resolved test
      # paths, not shell globs — measured, the glob form matches zero files
      # ("No test files found", exit 1). Loud rather than silent, but still
      # wrong; the substring is the form that actually selects both.
      #
      # [#17621] TWO substrings now, because the dialect that can fail is no
      # longer only MySQL. #17175 gave the two presence probes a catalog arm per
      # dialect family, and its PostgreSQL arm — `to_regclass` — was pinned as
      # TEXT and executed NOWHERE: this package had no live-PG harness and this
      # step supplied `OS_TEST_MYSQL_URL` alone, so the one arm whose failure
      # mode is a SILENTLY skipped data repair was the one arm no server ever
      # ran. The postgres service this job already provisions for the driver-sql
      # leg is what makes closing that wiring rather than infrastructure.
      #
      # Multiple positionals are OR-ed, and each is still a substring: measured,
      # `live-mysql live-postgres` selects the three `live-mysql*` files the
      # single argument selected plus `seed-tenancy-backfill.live-postgres`. ⛔ A
      # single shorter substring (`live-`) would select the same set today and
      # silently widen with the next unrelated file that happens to spell it.
      - name: Build metadata-protocol and its dependencies
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY || '' }}
        run: pnpm exec turbo run build --filter=@objectstack/metadata-protocol... --concurrency=4

      - name: Run the metadata-protocol migration statements against live MySQL and PostgreSQL
        env:
          OS_TEST_MYSQL_URL: mysql://root:root@127.0.0.1:3306/conformance
          # [#17621] The same URL the driver-sql leg above already receives, for
          # the postgres service this job already runs. One line, and the
          # read-probe's Postgres arm stops being the only one nothing executes.
          OS_TEST_POSTGRES_URL: postgres://postgres:postgres@127.0.0.1:5432/postgres
          # Same vacuous-pass guard as the driver-sql leg: this runner
          # provisioned the server, so a missing URL is a defect in the runner
          # and must be a red rather than a skip. It now covers BOTH URLs: each
          # live file above turns its own missing URL into a named failure.
          OS_EXPECT_LIVE_DIALECT_MATRIX: '1'
        run: |
          pnpm --filter @objectstack/metadata-protocol exec vitest run live-mysql live-postgres

      # ── The cascade-delete multi-value lookup pin, on the live PostgreSQL ──
      #
      # `packages/runtime` rides this job for the same reason metadata-protocol
      # above does: this is where a live PostgreSQL already exists. Only the
      # matrix file runs here — the rest of that package's suite has no server
      # axis and runs in Test Core.
      #
      # WHY (#18734). #18172 was a p1 that reached TWO published releases and
      # was found by a customer rather than by CI: every DELETE of an object
      # targeted by a `multiple: true` reference answered 500 on PostgreSQL,
      # always, while the only real-stack pin of that path stayed green
      # throughout — because it hard-coded `client: 'better-sqlite3'`. #18732
      # removed that literal and gave the file a driver axis, and SHOWED the
      # live cell red: ablating `SqlDriver.applyJsonMembership` produced
      # `6 failed | 9 passed`, all six failures in the live cell and ZERO in
      # SQLite, reproducing `operator does not exist: json ~~ text` (42883).
      #
      # ⚠ "There is a pin that can go red" and "that pin will be run" are two
      # different claims, and until these two steps only the first was true.
      # Measured on `origin/main` before this landed: `@objectstack/runtime`
      # occurred ZERO times in this job's window, against a firing control of
      # SEVEN for `driver-sql`. Without a URL the cell is a NAMED SKIP that
      # says which variable would run it — a report, NOT coverage, and the
      # shape that reads as "already fixed" in every review.
      #
      # `OS_EXPECT_LIVE_DIALECT_MATRIX` is scoped to the STEP, like the two
      # legs above and deliberately not to the job: it asserts "the runner
      # provisioned what THIS step needs", so it stays honest if a later step's
      # server is ever dropped. No stall guard, matching the metadata-protocol
      # leg — the two legs that carry one are the two that actually hit #4331.
      #
      # ⛔ THE POSITIONAL IS A SUBSTRING, NOT A GLOB — the same reading the
      # metadata-protocol step records above, where the glob form matched zero
      # files. ⛔ Do NOT "improve" it into `src/cascade-delete-*.test.ts`: that
      # selects nothing, and a test that cannot fail reports success, which is
      # the exact defect class this step exists to close. (`packages/runtime`'s
      # vitest config also runs `runFilterPreflight` (#17853/#17978), which
      # speaks up when a named path selects no tests — a second net, not a
      # licence to change the form.)
      - name: Build runtime and its dependencies
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY || '' }}
        run: pnpm exec turbo run build --filter=@objectstack/runtime... --concurrency=4

      - name: Run the runtime cascade-delete matrix against live PostgreSQL
        env:
          OS_TEST_POSTGRES_URL: postgres://postgres:postgres@127.0.0.1:5432/postgres
          OS_EXPECT_LIVE_DIALECT_MATRIX: '1'
        run: |
          pnpm --filter @objectstack/runtime exec vitest run --project local \
            cascade-delete-multivalue-lookup-real-driver

  dogfood:
    # Sharded 3-way: the suite is ~60 independent test files, each booting its
    # own in-process app; a single 4-vCPU runner needed ~7½ minutes for the
    # lot, and at 2 shards each half still ran ~7 min — the longest pole left
    # once Test Core went 3-way (#4859). vitest partitions the file list
    # deterministically across shards; all shards must pass. The bare
    # "Dogfood Regression Gate" context is carried by the dogfood-gate job
    # below — the shard count can change without touching it.
    name: Dogfood Regression Gate (${{ matrix.shard }}/3)
    needs: filter
    # See THE FILTER CONTRACT on the filter job's outputs (#4928). Full battery
    # only: see THE TWO SPEEDS above `jobs:` (#22998).
    if: ${{ !cancelled() && needs.filter.outputs.core != 'false' && github.event_name != 'pull_request' && github.event_name != 'merge_group' }}
    runs-on: ubuntu-latest
    # Backstop only — the stall guard on the test step is the primary detector
    # for a #4250-style hang (see Test Core). 30 min is ~6× a shard (~5 min;
    # the verify-CLI pass that used to ride shard 1 is its own parallel job
    # now — dogfood-verify below).
    timeout-minutes: 30
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3]

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

      - name: Setup workspace
        uses: ./.github/actions/setup-workspace

      # Shard-scoped key: the turbo test hash differs per shard (the task-declared
      # env `OS_TEST_SHARD` is part of the task hash). Restore-only on PRs — see the Restore
      # Turbo cache comment in the test job; the save step at the end of this
      # job seeds from main only. The job-level catch-all (same as Test Core's)
      # is what keeps a NEW shard number warm before main has ever saved it:
      # turbo's cache is content-addressed per task, so another shard's entries
      # replay the shared build closure even when the test slice differs.
      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-
            ${{ runner.os }}-turbo-${{ github.job }}-

      # ⛔ THE DOGFOOD PACKAGE'S DEPENDENCY CLOSURE IS BUILT HERE, IN A RUN
      # THAT CARRIES NO PASSTHROUGH. (#20820: the next step no longer needs this
      # for correctness -- it carries its shard in the task env `OS_TEST_SHARD`,
      # so it plans and replays this same closure itself, with no `--only`. The
      # step stays as its own stall-guard site, and the closure replays there.
      # The measurement below is the history of the `-- --shard=k/3` shape.)
      #
      # (History.) Turbo folds a run-level passthrough into the hash of EVERY
      # task in the run, not only the task that receives it -- and the old leg's
      # `-- --shard=k/3` was the whole reason each shard got its own invocation
      # (the next step's comment says what carries the slice now). Measured on turbo 2.10.10,
      # `--filter=@objectstack/dogfood`, `turbo run test ... --dry=json`
      # (67 tasks: 66 `build` + 1 `test`):
      #
      #   plain vs plain              67 identical,  0 changed  <- control, fires
      #   plain vs -- --shard=1/3      0 identical, 67 changed
      #   --shard=1/3 vs 2/3           0 identical, 67 changed
      #   --shard=2/3 vs 3/3           0 identical, 67 changed
      #
      # So the three shards hashed one 66-package build closure three ways, and
      # NONE of them could hit the ordinary `build` cache every other job in
      # this workflow populates -- that cache is written with NO passthrough in
      # the hash. The `Restore Turbo cache` step above addresses the symptom
      # (its shard-scoped key keeps a shard warm against its OWN history); it
      # cannot make three disagreeing closure hashes agree.
      #
      # `turbo run build --filter=@objectstack/dogfood` is that closure and
      # nothing more: measured 66 build tasks, all 66 hash-IDENTICAL to the ones
      # in the passthrough-free test plan (0 differing, 0 missing), so they
      # REPLAY here instead of re-executing per shard. The plan carries one
      # further node, `@objectstack/dogfood#build`, whose command is
      # `<NONEXISTENT>` in the dry output because the package declares no
      # `build` script -- it executes nothing and exists only as the root its
      # 66 `^build` dependencies hang from.
      #
      # ⚠ THIS IS ITS OWN STEP, not a second guarded run inside the step below,
      # because a guarded SITE is the triple (file, job, step) --
      # `measure-stall-guard-headroom` REFUSES to report a verdict when two
      # guarded runs share one. `pnpm check:stall-guard-budget` and
      # `pnpm check:stall-guard-headroom` both read this step, so it keeps its
      # own `--stall-minutes` and its own headroom row. The step is NOT allowed
      # to buy itself room by raising this job's `timeout-minutes`: that budget
      # is the instrument that shows this fix working (#16886).
      #
      # Turbo remote cache (#22077): the four TURBO_* lines are Build Core's,
      # verbatim, and Build Core's "Turbo remote cache (#21186)" comment holds
      # the write rule, the signing and the PINS. This plan is 66 `build` nodes
      # (63 with a command), each with Build Core's hash (measured). ⛔ They stay on THIS step: the
      # test step below runs `dogfood#test`, which must never read the remote,
      # and replays this closure from the local cache this step fills.
      - name: Build the dogfood package's dependency closure
        env:
          NODE_OPTIONS: --report-on-signal --report-signal=SIGUSR2 --report-directory=${{ runner.temp }}/stall-reports
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY || '' }}
        run: |
          mkdir -p "$RUNNER_TEMP/stall-reports"
          node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/dogfood-build.log" --stall-minutes 10 \
            --report-dir "$RUNNER_TEMP/stall-reports" -- \
            pnpm turbo run build --filter=@objectstack/dogfood --concurrency=4 --log-order=stream

      # Test leftovers, step 1 of 2 (#23880, ruling 乙): the snapshot, after the
      # closure build and before the tests. Report only; the same pair as Test
      # Core's, whose comments carry the rationale. `dogfood#test` depends on
      # `^build` alone, so the step above builds everything the tests need.
      - name: Snapshot the working tree before the dogfood tests
        run: node scripts/ci/report-test-leftovers.mjs snapshot --out "$RUNNER_TEMP/test-leftovers/before.json"

      # Boots real example apps in-process (in-memory SQLite) and exercises them
      # through the real HTTP + service stack — catches runtime regressions that
      # build / unit tests / spec-liveness pass over (e.g. the #2018 tz-bucketing
      # break, which was green on every static gate). The shard slice travels in
      # the task-declared env `OS_TEST_SHARD` (#20820, #19278's carrier):
      # `turbo.json` lists it in `@objectstack/dogfood#test`'s `env`, so it is
      # hashed into THAT task only, and `packages/qa/dogfood/vitest.config.ts`
      # hands it to vitest's `shard`. There is no `--` passthrough and no
      # `--only`: the run plans the `^build` closure with the same hashes as the
      # step above (they replay), and the test task's hash therefore moves when
      # an upstream package changes -- the old `--only` + `-- --shard=k/3` shape
      # dropped the closure from the test's hash and a main-seeded cache entry
      # could replay a shard green across an upstream-only change.
      # run-with-stall-guard: same wiring as Test Core (see the comment there;
      # #4250/#4314) — it tees to dogfood.log itself for the completeness guard
      # below, propagates the suite's real exit status (no `| tee` + pipefail),
      # and turns frozen output into a labeled red after 10 min of silence.
      # Dogfood boots real engines in-process — exactly the population #4250's
      # stalls came from. NODE_OPTIONS + --report-dir arm the stall forensics
      # (SIGUSR2 stack harvest) — see the Test Core comment.
      - name: Boot example apps and exercise real user flows
        env:
          NODE_OPTIONS: --report-on-signal --report-signal=SIGUSR2 --report-directory=${{ runner.temp }}/stall-reports
        run: |
          # Bound vitest's INNER worker pool (#11958). A no-op on a runner with
          # <= 5 cores (it only ever LOWERS vitest's own `cores - 1` default);
          # it exists so a larger runner cannot multiply turbo's outer
          # --concurrency by a host-sized inner pool. Empty on failure, which is
          # vitest's own "use the default" signal. Needs turbo.json's
          # globalPassThroughEnv entry or turbo strips it — see the script header.
          export VITEST_MAX_WORKERS="$(node scripts/vitest-worker-cap.mjs)"
          mkdir -p "$RUNNER_TEMP/stall-reports"
          # The slice is the ENV below, not a passthrough: see the step comment.
          # The build step above still builds the closure once, so the closure's
          # `build` tasks REPLAY here (identical hashes: nothing run-level is
          # hashed into them any more) and only `dogfood#test` executes.
          export OS_TEST_SHARD="${{ matrix.shard }}/3"
          node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/dogfood.log" --stall-minutes 10 \
            --report-dir "$RUNNER_TEMP/stall-reports" -- \
            pnpm turbo run test --filter=@objectstack/dogfood --log-order=stream

      # Test leftovers, step 2 of 2 (#23880, ruling 乙): what the dogfood test
      # run added to the working tree. Report only -- exits 0 on every path, no
      # `continue-on-error` -- and `if: always()`; see Test Core's pair.
      - name: Report what the dogfood tests left in the working tree
        if: always()
        run: |
          node scripts/ci/report-test-leftovers.mjs report \
            --before "$RUNNER_TEMP/test-leftovers/before.json" \
            --label "Dogfood Regression Gate (${{ matrix.shard }}/3)"

      # Dogfood boots real apps in-process, so a native/OOM abort is likelier
      # here than in the unit suites — and a shard that dies silently looks like
      # a shard that had less work.
      - name: Test completeness guard
        if: always()
        run: |
          if [ ! -f "$RUNNER_TEMP/dogfood.log" ]; then
            echo "No test log — the test step did not get far enough to produce one."
            exit 0
          fi
          node scripts/check-test-completeness.mjs "$RUNNER_TEMP/dogfood.log"

      # Same offline-forensics artifact as Test Core; shard-scoped name so the
      # two matrix jobs don't collide.
      - name: Upload stall diagnostic reports
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: stall-reports-dogfood-${{ matrix.shard }}
          path: ${{ runner.temp }}/stall-reports/
          if-no-files-found: ignore
          retention-days: 14

      # Seed the shared Turbo cache from main only (see the restore step
      # above); shard-scoped key so the two matrix jobs don't collide.
      - name: Save Turbo cache (main only)
        if: always() && github.event_name == 'push'
        uses: actions/cache/save@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-${{ github.ref_name }}-${{ github.sha }}

      # This shard's positive attestation (#6082) — see the identical pair at
      # the end of the test job for why these are LAST and carry no `if:`.
      - name: Attest this shard ran and passed
        run: |
          node scripts/check-shard-attestation.mjs --emit \
            --job dogfood --shard ${{ matrix.shard }} --total 3 \
            --out "$RUNNER_TEMP/shard-attestation"

      - name: Publish this shard's attestation
        uses: actions/upload-artifact@v7
        with:
          name: shard-attest-dogfood-${{ matrix.shard }}-of-3
          path: ${{ runner.temp }}/shard-attestation/
          if-no-files-found: error
          retention-days: 1
          overwrite: true

  # Replaces the former auto-verify dogfood tests: runs the published
  # `objectstack verify` engine over each example app through the CLI —
  # auto-derived CRUD round-trip fidelity + the cross-owner RLS invariant.
  # Exits non-zero on a real runtime failure, so it gates like the tests did.
  #
  # Its own job, not a rider on dogfood shard 1: the ~4½-minute pass ran
  # SERIALLY after that shard's tests, making shard 1 (~12 min) nearly twice
  # shard 2 (~6½ min) — the second-longest pole in the workflow for no
  # parallelism reason. It reports through dogfood-gate (below) rather than
  # its own required context, so the branch-protection contract is unchanged.
  dogfood-verify:
    name: Dogfood Verify CLI
    needs: filter
    # See THE FILTER CONTRACT on the filter job's outputs (#4928). Full battery
    # only: see THE TWO SPEEDS above `jobs:` (#22998).
    if: ${{ !cancelled() && needs.filter.outputs.core != 'false' && github.event_name != 'pull_request' && github.event_name != 'merge_group' }}
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read

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

      - name: Setup workspace
        uses: ./.github/actions/setup-workspace

      # Restore-only, with no save step at all: the
      # job's only build is the CLI closure, and the build-core fallbacks are
      # the entries that actually hit — that job builds a superset and is
      # seeded from main.
      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-${{ github.job }}-
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

      # Build the CLI plus BOTH example apps' full dependency closures (the
      # `pkg...` filter form). When this pass rode dogfood shard 1 the whole
      # workspace was already built by the test step, so `--filter=@objectstack/cli`
      # alone sufficed; standalone, the bundled objectstack.config imports
      # runtime packages (e.g. @objectstack/connector-mcp for app-showcase)
      # whose dist nothing here had built — ERR_MODULE_NOT_FOUND at verify
      # time. The closure syntax keeps this self-maintaining as app deps move.
      - name: Verify example apps via the `objectstack verify` CLI
        run: |
          pnpm turbo run build \
            --filter=@objectstack/cli... \
            --filter=@objectstack/example-crm... \
            --filter=@objectstack/example-showcase... \
            --concurrency=4
          for app in examples/app-crm examples/app-showcase; do
            echo "::group::objectstack verify $app --rls"
            OS_LOG_LEVEL=error node packages/cli/bin/run.js verify --app "$app/objectstack.config.ts" --rls
            echo "::endgroup::"
          done

      # This leg's positive attestation (#6082). Not a matrix, so its declared
      # roster is the single 1-of-1 credential — but dogfood-gate counts it
      # exactly like a shard, which is what keeps the one required context
      # covering everything it covered before the split.
      - name: Attest this leg ran and passed
        run: |
          node scripts/check-shard-attestation.mjs --emit \
            --job dogfood-verify --shard 1 --total 1 \
            --out "$RUNNER_TEMP/shard-attestation"

      - name: Publish this leg's attestation
        uses: actions/upload-artifact@v7
        with:
          name: shard-attest-dogfood-verify-1-of-1
          path: ${{ runner.temp }}/shard-attestation/
          if-no-files-found: error
          retention-days: 1
          overwrite: true

  dogfood-gate:
    # Stable check name for a SHARDED job (#3622 follow-up). Since #22998 its
    # legs run in the full battery only (THE TWO SPEEDS above `jobs:`) and the
    # context leaves the required set; on a PR or queue build both legs skip
    # and this gate counts zero expected attestations. The history below is
    # why the name and the `if: always()` stay.
    #
    # Branch protection required the context "Dogfood Regression Gate". Once
    # the job became a 2-way matrix its checks publish as "Dogfood Regression
    # Gate (1/2)" / "(2/2)" — the bare context could never appear again, so
    # EVERY pull request in the repo sat permanently BLOCKED (mergeable, all
    # checks green, merge button dead). #3622's own comment called for updating
    # branch protection; keeping the contract HERE instead means a future
    # shard-count change cannot deadlock the repo a second time. From #6865
    # until #22998 the bare name was pinned by `check:required-contexts`; it
    # left that registry with the required set, so a rename now falsifies the
    # prose that names it without reddening anything — treat it as contract.
    #
    # Also aggregates dogfood-verify (the CLI pass that used to ride shard 1),
    # so the one context still covers everything it covered before the split.
    #
    # `if: always()` + attestation counting so a legitimately skipped matrix
    # (the `filter` job says no core paths changed) still satisfies the gate —
    # LEGITIMATELY being the operative word since #4928: `filter` must have
    # concluded success (or the run been cancelled) for a skip to count.
    # Deliberately NOT `if: !cancelled()` on the job instead: a skipped gate
    # publishes no required-check context on the SHA, which is the #3622
    # merge-deadlock all over again.
    #
    # ── It COUNTS credentials; it does not read one aggregate word (#6082) ──
    #
    # Same rework as test-gate above, for the same two measured defects (runs
    # 31120902911 and 31114735713): one `needs.<matrix>.result` cannot carry
    # three shards' verdicts, so any run-lifecycle value in it — the
    # undocumented `abandoned` that runner starvation produces, in both of
    # those runs — either paints a false red or, once whitelisted, swallows a
    # sibling's real `failure`. Each of the FOUR legs this context covers
    # (3 dogfood shards + the CLI pass) now publishes its own "I ran and
    # passed" artifact, and this gate passes only when it counts all four.
    #
    # `cancelled` still passes without counting, for #3668's reason: it is a
    # run-lifecycle state, not a shard verdict — with cancel-in-progress on,
    # every superseded push cancels the in-flight dogfood matrix (the longest
    # job, so almost always the one still running), and failing here would
    # paint a false red on the old SHA. Verified experimentally there (run
    # 30271824408, a fail-fast matrix with one real failure + one cancelled
    # sibling): a real shard failure DOMINATES the aggregate — it reads
    # "failure", never "cancelled" — so passing `cancelled` masks no
    # regression. That dominance is what does NOT hold for `abandoned`, which
    # is why `abandoned` gets counting rather than a place in a word list.
    name: Dogfood Regression Gate
    needs: [dogfood, dogfood-verify, filter]
    # ── ROSTER DECLARATION (#10490) ───────────────────────────────────────
    # Both legs this context covers, named. See test-gate above for the full
    # note; the same gate asserts this list equals `needs:` in both directions
    # and equals the `--leg` tokens the verdict actually counts. `filter` is
    # the #4928 input, not a lane.
    env:
      OS_AGGREGATOR_MEMBERS: dogfood dogfood-verify
      OS_AGGREGATOR_NON_MEMBERS: filter
    if: always()
    runs-on: ubuntu-latest
    timeout-minutes: 10
    # `actions: read` + `checks: read` (#22606) pay for ONE question, asked
    # only when `dogfood-verify` — a single-leg roster, which has no sibling
    # shard to show the leg ran — reads `cancelled` with zero attestations
    # while the dogfood matrix attested: was that leg KILLED by its own
    # `timeout-minutes`, or SUPERSEDED by a newer push? The aggregate word is
    # `cancelled` either way, so the verdict reads the cause the platform
    # records on the leg's own check run (this attempt's jobs list, then that
    # check run's annotations). Both are reads; an unspecified permission is
    # `none`, so neither is reachable without naming it here.
    permissions:
      contents: read
      actions: read
      checks: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7

      # One pattern covers both legs: `shard-attest-dogfood-*` matches the three
      # `…-dogfood-<n>-of-3` shard credentials and `…-dogfood-verify-1-of-1`
      # alike. See test-gate for why continue-on-error and why no new
      # permission is needed.
      - name: Download dogfood attestations
        id: attestations
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          pattern: shard-attest-dogfood-*
          path: ${{ runner.temp }}/shard-attestations
          merge-multiple: true

      - name: Verify dogfood shard results
        env:
          OS_ATTEST_DIR: ${{ runner.temp }}/shard-attestations
          OS_DOGFOOD_RESULT: ${{ needs.dogfood.result }}
          OS_VERIFY_RESULT: ${{ needs['dogfood-verify'].result }}
          OS_FILTER_RESULT: ${{ needs.filter.result }}
          OS_DOWNLOAD_OUTCOME: ${{ steps.attestations.outcome }}
          # Read ONLY on the cancelled-single-leg path above, never otherwise;
          # without it that path fails closed (red, naming the missing token).
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          node scripts/check-shard-attestation.mjs --verify \
            --gate 'Dogfood Regression Gate' \
            --dir "$OS_ATTEST_DIR" \
            --filter-result "$OS_FILTER_RESULT" \
            --download-outcome "$OS_DOWNLOAD_OUTCOME" \
            --leg "dogfood/3:$OS_DOGFOOD_RESULT" \
            --leg "dogfood-verify/1:$OS_VERIFY_RESULT"

  build-core:
    name: Build Core
    needs: filter
    # See THE FILTER CONTRACT on the filter job's outputs (#4928). No
    # aggregation gate stands behind this job — its own name IS the required
    # context, pinned by `check:required-contexts` since #6865 — so this `if:`
    # is the only thing between a filter flake and a green "Build Core" that
    # built nothing.
    if: ${{ !cancelled() && needs.filter.outputs.core != 'false' }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read

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

      - name: Setup workspace
        uses: ./.github/actions/setup-workspace

      # Restore-only on PRs: PR-side saves (~5 turbo entries per push) churned
      # the repo's 10 GB Actions cache pool and evicted the main-branch seeds —
      # observed as sudden cold-cache spikes (Build Core 51s → 4m30s). PRs fall
      # back to main's entries via the prefix restore-keys; only main pushes
      # save (the "Save Turbo cache" step at the end of the job).
      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-${{ github.job }}-

      # 67 package build commands end with `node …/scripts/check-dts-emitted.mjs`,
      # so the `pnpm build` below runs that checker on every package it builds,
      # and until this step no workflow ran its `--self-test`. It surfaced when
      # the `core:` filter began naming the file as a build input (#21202) and
      # `check:self-test-wired` saw a workflow name a self-test it never runs.
      # Milliseconds, no prerequisites; placed before the build so a broken
      # checker is reported before the 67 verdicts that rely on it.
      - name: check-dts-emitted self-test
        run: node scripts/check-dts-emitted.mjs --self-test

      # The remote-cache assertion after the build below, and after every
      # carrier that runs it (Test Core's closure, lint.yml's three Type Check
      # lanes), is one script; its self-test runs here, once.
      - name: assert-turbo-remote-cache self-test
        run: node scripts/ci/assert-turbo-remote-cache.mjs --self-test

      # Test Core's seed prune (the step before its "Save Turbo cache") runs
      # on main pushes only, six times; its self-test runs here, once, on
      # every event, so a PR that breaks it reds before the push that uses it.
      - name: prune-turbo-cache self-test
        run: node scripts/ci/prune-turbo-cache.mjs --self-test

      # ── Turbo remote cache (#21186) ─────────────────────────────────────
      # Vercel's managed Turborepo remote cache. objectstack-ai/cloud's
      # test.yml builds this repo at its pinned SHA with the same command and
      # reads/writes the same Vercel team, and the task hashes are identical
      # in both places (72 of 72 build tasks, read from both CI logs at one
      # SHA), so a pin bump there can replay what this step built on `main`.
      #
      # Scope: `turbo run build` steps only, i.e. `build` tasks. Since #22077
      # that is this step plus the build steps of the Test Core shards, the
      # dogfood shards, Temporal Conformance, Build UI Deps and lint.yml's
      # three Type Check build lanes, each carrying the four lines below
      # verbatim; the PINS paragraph at the end says what keeps that set
      # honest. `test` /
      # `test:repo` stay off the remote: their cross-package inputs are
      # hand-declared, and a wrong hash replayed from a remote reaches every
      # run and cloud too. Build Docs forces execution and carries no
      # credentials.
      #
      # TURBO_CACHE is the env form of `--cache`. Writes happen on
      # `merge_group` and on `push` / `workflow_dispatch` against main; every
      # other event, `pull_request` and `schedule` included, only reads,
      # because read-only is the default branch of the expression. This is
      # turbo configuration, not a property of the credential: the token can
      # write and the signing key can sign whatever holds them, which is why
      # the two secrets below are scoped by event rather than trusted to it.
      # ⚠️ Never let it evaluate to '': turbo then disables the LOCAL cache
      # too (`no caches are enabled`) and re-executes everything.
      #
      # Credentials go only to runs whose code has landed or is landing:
      # `merge_group`, and any run on refs/heads/main (push, the 4-hourly
      # schedule, workflow_dispatch on main). A `pull_request` run, and a
      # dispatch on any other branch, receives neither TURBO_TOKEN nor the
      # signing key, so code a PR adds can neither upload to the remote nor
      # sign an artifact that a queue or main build would replay. Such a run
      # builds from the restored Actions-cache seed (local:rw) and the
      # assertion step reports the remote as withheld, never as broken.
      # TURBO_TOKEN (secret) is further passed only when the signing key
      # is non-empty, because an empty key still "signs" with a zero-length
      # HMAC key; TURBO_TEAM is a repo VARIABLE so the slug is not masked out
      # of the log; TURBO_REMOTE_CACHE_SIGNATURE_KEY (secret) must equal
      # cloud's. turbo.json's `remoteCache.signature` makes turbo tag every
      # upload and verify every download with that key. Any of the three
      # unset: remote caching is off and the build is unchanged; the summary
      # then reads `Remote caching disabled (remote cache requested — …)`.
      #
      # ASSERTED (#25374). The step after this one reads that prelude line
      # from turbo's structured log (`--log-file`, repo-relative or turbo
      # ignores it) and the hit counts from `--summarize`, prints both into the
      # job's step summary, and reds a run that WRITES the remote (the
      # `remote:rw` branch above) when the cache is off; a read-only run only
      # warns. Neither flag enters a task hash (83 of 83 identical with and
      # without, `--dry=json`, turbo 2.11.5). The carriers that assert are this
      # step, Test Core's closure, Build UI Deps and lint.yml's three Type
      # Check lanes; the verdict table is the script header's.
      #
      # PINS, for every step that carries these four lines (#22077). Each
      # carrier points back here.
      #   - BUILD TASKS ONLY. #19086's lesson: a step that writes artifacts from
      #     a cache-served dist must not itself be served. Each carrier runs one
      #     `turbo run build` whose `--dry=json` plan is all `#build` tasks.
      #     ⛔ Never put these lines on a step that runs `test`, `test:repo`,
      #     `typecheck` or a `gen:*` task (turbo.json caches `gen:schema` and
      #     `gen:skill-refs`), or on a step that writes tracked files.
      #   - SAME HASHES AS THIS STEP. Every carrier's build tasks are a subset
      #     of this step's plan with identical hashes (measured on 3d9188502e,
      #     turbo 2.11.5: 8 to 77 tasks per carrier, 0 differing), so a PR read
      #     hits what this step wrote on `main` or in the queue. Filters and
      #     `--concurrency` do not enter a task hash; an env var a carrier sets
      #     that turbo.json hashes would, so do not add one to a carrier.
      #   - A HIT IS ONLY AS CORRECT AS THE HASH (#21193). Every root file a
      #     build reads is a `$TURBO_ROOT$` input in turbo.json. Re-measured for
      #     #22077 on 3d9188502e: one appended line in each of the 17 declared
      #     root inputs moves the build hashes (72, 71 or 6 of 72, #21193's
      #     numbers); the root tsup.config.ts control moves 72/72; an unrelated
      #     script, ci.yml and lint.yml move 0. The static import closure of
      #     every root script a build command or tsup config names is inside
      #     those declarations. A build that starts reading a new root file
      #     must declare it in turbo.json before this cache can be trusted.
      - name: Build packages (excluding docs)
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY || '' }}
        run: pnpm build --summarize --log-file=.turbo/remote-cache/build-core.json

      - name: The Turbo remote cache was on for the build
        run: node scripts/ci/assert-turbo-remote-cache.mjs --site 'Build Core' --log .turbo/remote-cache/build-core.json

      # [#15042] The closure-wide declaration re-check. `check-dts-emitted` runs
      # per package, immediately after that package's `tsup`, and is the LAST
      # thing that ever looks: on the filing observation it reported
      # `3/3 declared declaration file(s) present` and the files were gone later
      # in the same tree, with no second build and no `rm`. Sits directly after
      # the build so the tree the steps BELOW read is the tree this swept — a
      # package whose declarations are absent makes an importing symbol `any`,
      # and the direction that does NOT throw is a suite passing against a type
      # nothing is checking (#7668, #12078). No `dist/` anywhere is exit 3
      # PREREQUISITE NOT MET, never a pass.
      - name: Sweep the built closure for vanished declarations
        run: pnpm check:dts-closure

      # A package that builds with plain `tsc` and does not exclude tests emits
      # `dist/**/*.test.js`. Two costs, and the second is the dangerous one:
      #
      #   1. `files: ["dist"]` publishes the tests to npm.
      #   2. A package with no vitest config COLLECTS those compiled copies
      #      alongside the sources, so every `src/**/*.test.ts` also runs as a
      #      stale `dist/**/*.test.js` built at the last `pnpm build`. That
      #      silently defeats edits — a fix to a source test appears not to work
      #      because the run is still executing the pre-fix duplicate — and it
      #      lets a source test be edited to pass while its stale twin keeps
      #      asserting the old behaviour, with neither obviously wrong.
      #
      # `@objectstack/cli` shipped exactly that (81 test files / 849 tests where
      # its sources hold 58 / 581) until #4065 excluded them. The rest of the
      # repo builds with tsup, which emits only declared entry points — so this
      # gate exists to stop the NEXT tsc-built package repeating it, not to
      # re-check the one that was fixed.
      - name: No compiled test files in any dist
        run: |
          set -o pipefail
          found="$(find packages -type d -name node_modules -prune -o \
            -type f \( -name '*.test.js' -o -name '*.test.cjs' -o -name '*.test.mjs' \) \
            -path '*/dist/*' -print | sort)"
          if [ -n "$found" ]; then
            echo "::error::Compiled test files found in build output. A tsc-built package is"
            echo "::error::missing a test exclude in its tsconfig.build.json, so these ship to"
            echo "::error::npm AND run as stale duplicates of their own sources."
            echo "$found"
            exit 1
          fi
          echo "OK — no compiled test files in any package dist."

      - name: Verify build outputs
        run: |
          if [ ! -d "packages/spec/dist" ]; then
            echo "Error: packages/spec/dist directory not found"
            exit 1
          fi
          if [ ! -d "packages/spec/json-schema" ]; then
            echo "Error: packages/spec/json-schema directory not found"
            exit 1
          fi
          echo "Build outputs verified successfully"

      # Capability packages (services / triggers / plugins) are loaded by the
      # multi-tenant runtime via a DYNAMIC import of their published entry. If a
      # package ships a dts-only / half-built / 0-byte `dist` (an interrupted
      # build, or a package retired in source but still referenced), that import
      # resolves to nothing and the capability SILENTLY fails to load — e.g.
      # record-change automation never fires, with no user-visible signal. The
      # build config always emits JS, so this can only happen by accident; assert
      # every buildable capability package actually produced its declared runtime
      # entry. Self-maintaining: reads each package's own `main`, skips dirs with
      # no package.json (e.g. a retired service-feed/service-ai leftover).
      - name: Verify capability packages ship a runtime entry (no dts-only / half-built)
        run: |
          fail=0
          for d in packages/triggers/* packages/services/* packages/drivers/* packages/plugins/*; do
            [ -f "$d/package.json" ] || continue
            has_build=$(node -p "Boolean((require('./$d/package.json').scripts||{}).build)" 2>/dev/null || echo false)
            [ "$has_build" = "true" ] || continue
            main=$(node -p "require('./$d/package.json').main || 'dist/index.js'" 2>/dev/null || echo dist/index.js)
            if [ ! -s "$d/$main" ]; then
              echo "✗ $d: missing/empty runtime entry '$main' — dts-only or unbuilt? dynamic import would silently fail"
              fail=1
            fi
          done
          if [ "$fail" -ne 0 ]; then exit 1; fi
          echo "✓ all buildable capability packages ship a runtime JS entry"

      # The sibling of the step above, one condition over: that step asks
      # whether the declared entry EXISTS, this one whether it LOADS. #12971:
      # one source line added `createRequire(import.meta.url)` to
      # metadata-core, tsup emitted `import.meta` verbatim into
      # `dist/index.cjs`, and outside an ES module that is a PARSE-time error
      # — so the package's entire `require` condition was unloadable while
      # every suite here stayed green (vitest resolves workspace packages
      # through the `import` condition) and `pnpm build` stayed green too (the
      # bytes emit fine; they just cannot be parsed by the runtime they are
      # declared for). Downstream it refused to boot cloud's walled EE runtime.
      # This lives in Build Core rather than the lint job because it reads a
      # real dist/; with none it exits 3 (PREREQUISITE NOT MET), never a
      # silent green. Its header is the authority on detail.
      - name: Every published require entry point actually loads
        run: pnpm check:dual-build-cjs-loads

      # #16469 (build half of #15905's E3 question 1): `sourcesContent` is off
      # by construction at the shared tsup/esbuild layer, so a `.map` file that
      # carries it means a config skipped the shared hook, or a toolchain
      # upgrade changed esbuild's default back to embedding. Lives here for the
      # same reason the step above does: it reads a real `dist/`, and refuses
      # (exit 3) rather than passing silently when there is none.
      - name: No published source map embeds source text
        run: pnpm check:sourcemap-no-sources-content

      # #15347. The ADR-0076 D2 boundary ratchet beside `core.ts` scans SOURCE
      # TEXT for two hard-coded names, so it is neither transitive nor able to
      # see a heavyweight arriving through any other specifier — which is
      # exactly how #14680 arrived, three packages deep, invisible to every
      # gate for the whole time it was live. This one loads the built lean
      # entry in a fresh child per published condition and asserts the PACKAGE
      # SET it evaluates: an exclusion claim, decidable and unit-carrying, with
      # no size figure anywhere (#9803). Lives here for the same reason the two
      # steps above do — it reads a real `dist/`, and with none it exits 3
      # (PREREQUISITE NOT MET), never a silent green. Its header is the
      # authority on detail, including why it is not a case in the vitest file
      # it guards beside.
      - name: The lean engine entry loads no forbidden or unlisted package
        run: pnpm check:lean-entry-closure

      - name: Analyze bundle size
        run: pnpm --filter @objectstack/spec analyze

      - name: Upload build artifacts
        uses: actions/upload-artifact@v7
        with:
          name: build-output
          path: |
            packages/spec/dist/
            packages/spec/json-schema/
          retention-days: 30

      # Keeps only the entries the build's run summary (`--summarize`, left in
      # `.turbo/runs/` by the assertion above) names, as Test Core's prune step
      # does (#25452): the restore step takes the newest seed by prefix and
      # turbo never evicts its local cache, so a seed saved whole is every seed
      # before it plus this run. No summary -- the build never finished --
      # means no save, and the previous seed stays the newest.
      - name: Prune the Turbo cache to this run's tasks (main only)
        id: prune-turbo-cache
        if: always() && github.event_name == 'push'
        run: |
          node scripts/ci/prune-turbo-cache.mjs --site 'Build Core' \
            --cache .turbo/cache --run-summaries .turbo/runs

      # Seed the shared Turbo cache from main only (see the restore step above).
      - name: Save Turbo cache (main only)
        if: always() && github.event_name == 'push' && steps.prune-turbo-cache.outputs.save == 'true'
        uses: actions/cache/save@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}

  build-docs:
    name: Build Docs
    needs: filter
    # See THE FILTER CONTRACT on the filter job's outputs (#4928). `docs`, not
    # `core` — each job keeps its own filter output.
    if: ${{ !cancelled() && needs.filter.outputs.docs != 'false' }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read

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

      - name: Setup workspace
        uses: ./.github/actions/setup-workspace

      # The Next.js cache is RESTORED on every run and SAVED only on `push` and
      # `schedule`, by "Save Next.js cache" at the end of this job -- the rule
      # `.github/actions/setup-workspace` holds for the pnpm store, for the same
      # reason: an entry saved on a pull request or merge-queue ref is
      # restorable only from that ref, yet it counts toward the one 10 GB
      # Actions cache pool and evicts `main`'s entries, which every pull request
      # and queue run CAN restore. ⛔ No `pull_request` or `merge_group` run
      # saves it.
      - name: Restore Next.js cache
        id: nextjs-cache
        uses: actions/cache/restore@v6
        with:
          path: apps/docs/.next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/pnpm-lock.yaml') }}-${{ hashFiles('apps/docs/**.[jt]s', 'apps/docs/**.[jt]sx', 'content/**/*.mdx') }}
          restore-keys: |
            ${{ runner.os }}-nextjs-${{ hashFiles('**/pnpm-lock.yaml') }}-

      # ── This gate builds what SHIPS, not a hand-copied lookalike (#10642) ──
      #
      # This step used to run `pnpm --filter @objectstack/docs build`: a SECOND,
      # hand-maintained spelling of the production build. Production runs
      # whatever `apps/docs/vercel.json` says, and NOTHING in this repo read
      # that file - grep over every workflow and script found no reader - so the
      # two spellings were free to drift apart silently, and did. `Build Docs`
      # was green on nine consecutive PRs while the production build of that
      # same app was failing. A gate that re-implements the thing it guards can
      # only ever test the re-implementation; its green says nothing about what
      # ships. Note the divergence was never in the path filter: the `docs`
      # filter already lists `content/**` and is fail-open, so those greens were
      # real runs, not skips.
      #
      # So the command is READ FROM `vercel.json` rather than copied. Vercel
      # runs `buildCommand` with the cwd set to the project's Root Directory
      # (`apps/docs` - which is why the stored command opens with `cd ../..`),
      # hence `working-directory` here. Changing how production builds now
      # changes this gate in the same commit, by construction, which is the part
      # that survives the NEXT divergence rather than pinning today's.
      #
      # `eval` of a repo-controlled string adds no trust boundary this job did
      # not already have: it already runs install lifecycle scripts and
      # `next build` from the same tree.
      - name: Build Docs (the command production runs)
        working-directory: apps/docs
        env:
          # The ONE deliberate difference from production, and it is
          # load-bearing. `@objectstack/docs#build` inherits turbo's generic
          # `build` task, whose inputs are the package's own files: 35 of them,
          # NONE under `content/`. Every one of the docs site's 400+ pages lives
          # in `content/`. Measured on 98ea344: appending a line to
          # `content/docs/index.mdx` left the task hash at `4e0c51cb3db203a8` -
          # a cache HIT, i.e. turbo replays the previous `.next` instead of
          # building this tree. A content-only PR is the normal shape of a docs
          # change and precisely the shape this gate has to be able to fail, so
          # the gate must not be satisfiable by a replayed artifact. TURBO_FORCE
          # re-executes the task even on a hash hit. The same hole on the
          # PRODUCTION side, where nothing forces a rebuild, is a separate
          # defect and is filed separately - this env var fixes the gate only.
          TURBO_FORCE: 'true'
        run: |
          set -euo pipefail
          BUILD_COMMAND="$(node -p "JSON.parse(require('node:fs').readFileSync('vercel.json','utf8')).buildCommand || ''")"
          if [ -z "$BUILD_COMMAND" ]; then
            echo "::error file=apps/docs/vercel.json::No buildCommand in apps/docs/vercel.json. This gate cannot know what production runs and refuses to guess: restore buildCommand, or rewrite this step against whatever now defines the production build."
            exit 1
          fi
          echo "Production build command (apps/docs/vercel.json): $BUILD_COMMAND"
          eval "$BUILD_COMMAND"

      # Exit code 0 is NOT evidence that the app was built. `pnpm --filter <name>`
      # with a filter matching no package prints "No projects matched the
      # filters" and exits 0 (measured) - so a renamed package, or a typo in the
      # production build command, is a silent success here and a deploy-time
      # "No Output Directory found" on Vercel, i.e. exactly the failure mode
      # this card exists to catch, arriving AFTER the gate reported green.
      # Assert the artifact rather than trusting the exit code.
      #
      # `.next/BUILD_ID` cannot be a leftover from the cache restore above:
      # the Next.js cache steps store `apps/docs/.next/cache` ONLY, so nothing
      # outside that subtree is ever restored. ⛔ Widening that cache path to
      # `apps/docs/.next` would let this assertion pass without a build.
      - name: Assert the docs app actually built
        run: |
          set -euo pipefail
          if [ ! -f apps/docs/.next/BUILD_ID ]; then
            echo "::error file=apps/docs/vercel.json::The production build command exited 0 but produced no apps/docs/.next/BUILD_ID - nothing was built."
            exit 1
          fi
          echo "Built docs app: BUILD_ID=$(cat apps/docs/.next/BUILD_ID)"

      # The save half of "Restore Next.js cache" (its comment says why it runs
      # on `push` and `schedule` only). It reproduces what the combined
      # `actions/cache` post step did on those events, three ways:
      #   - no status function in `if:`, so it runs only when every step above
      #     succeeded -- the combined action's `post-if: success()`;
      #   - skipped on an exact hit, which has nothing new to write;
      #   - saved under `cache-primary-key`, the key the restore step resolved
      #     BEFORE the build, which is the key the combined action saved under.
      #     A key re-hashed here would hash `apps/docs/`, the tree the build
      #     has just written into, so it could differ from the key the restore
      #     looked up.
      # A main-phase step, bounded and `continue-on-error` like the ui jobs'
      # saves: a stalled or failed upload costs the next run time and says
      # nothing about the docs build.
      - name: Save Next.js cache
        if: >-
          (github.event_name == 'push' || github.event_name == 'schedule')
          && steps.nextjs-cache.outputs.cache-hit != 'true'
        uses: actions/cache/save@v6
        timeout-minutes: 5
        continue-on-error: true
        with:
          path: apps/docs/.next/cache
          key: ${{ steps.nextjs-cache.outputs.cache-primary-key }}

  # ── THE ui/ JOBS (objectstack#25697, epic objectstack#25677) ──────────────
  # objectui is imported under `ui/` as a subtree. These four jobs are its CI,
  # ported from objectui's own ci.yml (`Type Check`, `Test (shard n/16)`,
  # `Build & E2E`) and lint.yml (`Lint`), and they land BEFORE the import:
  #
  #   - every one is gated on the `filter` job's `ui_tree` output, so on a tree
  #     without `ui/package.json` it is SKIPPED on every event, never failed —
  #     see the comment on the `ui` outputs at the top of this file;
  #   - none is a required context, and none is in an aggregator's `needs:`.
  #     Joining the required set is the maintainer's ruleset edit at cutover.
  #
  # What the port changed, everywhere, and why:
  #   - objectui's `.objectstack-pin` plumbing (restore / build / save the
  #     pinned @objectstack build) is gone. The seven packages objectui installs
  #     are workspace packages here, so they are built from this tree with
  #     turbo instead: once per run by `ui-deps` below, whose cache entries each
  #     job's "Build the @objectstack packages objectui consumes" step replays
  #     (the seven names match the `ui_consumers` filter).
  #   - objectui's per-job "Decide whether this change needs a full run" step is
  #     replaced by the `filter` job's `ui` / `ui_consumers` outputs.
  #   - objectui's own commands are spelled `pnpm --dir ui run <its alias>`
  #     (or `pnpm --dir ui exec ...`), so they run with cwd = the objectui root,
  #     which they assume. ⛔ Not `node scripts/<x>` or `pnpm run <x>` under
  #     `working-directory: ui`: this repo's workflow gates (check-self-test-
  #     wired, dispatch-gates' derivation and others) key `scripts/<x>` and
  #     `pnpm <alias>` against THIS repo's root and do not read
  #     `working-directory`, so objectui's `scripts/check-entry-guard.mjs`
  #     would be credited to objectstack's file of the same name, and a name
  #     only objectui has would read as a missing script;
  #   - turbo runs from this repo's root with directory filters, because
  #     `ui/package.json`'s own `lint` / `type-check` scripts are
  #     `turbo run <task>` and would recurse.
  #   - objectui's root-only turbo tasks `//#lint:root` and `//#type-check:e2e`
  #     are steps here (turbo.json carries no dependsOn on a package that does
  #     not exist yet; turbo refuses the whole run over one).
  #   - governance steps (the cross-repo closer contract) are not ported; they
  #     belong to the governance-workflow audit (sub-issue 4 of the epic).
  #
  # ── Cache bookkeeping in the ui jobs (objectui#6577, objectui#7048) ──────
  # Every cache SAVE in these five jobs is a main-phase `actions/cache/save`
  # step after the job's last checking step, with `timeout-minutes` and
  # `continue-on-error: true`: a combined `actions/cache` saves from a
  # runner-generated post step, which no workflow key can bound, and an upload
  # that stalls there runs the job into its ceiling and turns a verdict the job
  # had already recorded into `cancelled`, which the merge queue cannot tell
  # from `failure`. A failed save costs the next run time and says nothing about
  # the code. The restores stay unbounded: a restore stall fails before any
  # verdict exists. Each bound is 5 min, ~14x the slowest healthy save measured
  # on the card (the ui turbo seeds 1-19 s over 22 saves, the pnpm store's
  # combined post step 5-22 s over 734 jobs), and every job ceiling is at
  # least twice its bound.
  # `ui/scripts/__tests__/turbo-cache-save-bound.test.ts` pins all of it.
  #
  # The pnpm store is RESTORED by every ui job and SAVED by `ui-deps` alone, on
  # a miss of its exact key and on `push` and `schedule` runs only: twenty jobs
  # racing to upload one store under one key reserve it once and fail nineteen
  # times. These five jobs keep the setup steps spelled out instead of calling
  # `.github/actions/setup-workspace`, because pins under `ui/scripts/__tests__/`
  # read those steps by name and by text.

  # ── Build UI Deps: the seven packages, built once per run (#25869) ───────
  # Each ui job used to build the seven @objectstack packages itself. Measured
  # over the 51 CI runs that scheduled ui jobs between the ui/ cutover and
  # 2026-10-26T05:30Z: the step replayed in 1-2 s from a job's own turbo seed
  # on 24 runs, and built cold in EVERY ui job on the other 27 (86-288 s each,
  # median 201 s) -- 1191 runner-minutes in all, 33-77 per full-lane run. A
  # cold seed is the common case, not the exception: the seeds are saved per
  # job on `main` pushes, and a pull request or queue entry whose closure
  # differs from the newest seed's (any spec change landed since, or one ahead
  # in the queue) misses in all twenty jobs at once.
  #
  # So this job builds the closure ONCE and uploads the turbo cache entries of
  # that build (36 tasks, ~27 MB, already zstd), and each ui job downloads them
  # into `.turbo/cache` before its own unchanged build step, which then
  # replays every task in about a second. Entries, not `dist/` trees: the
  # Type Check UI and Lint UI jobs run further turbo tasks that depend on
  # `^build`, and only a cache HIT stops turbo rebuilding the seven there.
  # Turbo still hashes every task, so a seed that does not match this tree is
  # rebuilt, never trusted.
  #
  # FAILS OPEN. The download is `continue-on-error` and every ui job keeps its
  # build step: with no artifact (this job red, cancelled or skipped, or the
  # artifact service down) a job builds cold exactly as before, and a closure
  # that does not build reds the same step it always did. That is also why the
  # ui jobs' `if:` lines are unchanged: their `!cancelled()` already runs them
  # whatever this job's result.
  #
  # The cost is wall clock: a ui job now starts after this one, ~1 min of
  # setup and upload later than it used to start building. The build carries
  # the remote-cache lines like every other build carrier, so a queue or
  # `main` run whose closure was built before replays it from the remote.
  # ⛔ A pull_request run still gets no remote credentials (Build Core's
  # "Turbo remote cache (#21186)" comment says why), so a PR is served by its
  # own run's build and the seed below.
  ui-deps:
    name: Build UI Deps
    needs: filter
    # The union of the four ui jobs' conditions: Type Check UI and Build & E2E
    # UI's, which Test UI and Lint UI's imply.
    if: ${{ !cancelled() && needs.filter.outputs.ui_tree != 'false' && (needs.filter.outputs.ui != 'false' || needs.filter.outputs.ui_consumers != 'false') }}
    runs-on: ubuntu-latest
    # The build step's population above: max 288 s cold; with setup, upload
    # and the saves ~7 min. The smallest round number >= 3x that and >= that
    # + 15 min (objectui's lint.yml ceiling rule) is 25.
    timeout-minutes: 25
    permissions:
      contents: read

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

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Restore pnpm cache
        id: pnpm-cache
        uses: actions/cache/restore@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Restore Turbo cache
        id: turbo-cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-${{ github.job }}-
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

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

      # The same command as the step of this name in the four ui jobs, so it
      # schedules the same tasks with the same hashes; the four TURBO_* lines
      # are Build Core's, verbatim (its "Turbo remote cache (#21186)" comment
      # and the PINS paragraph there).
      - name: Build the @objectstack packages objectui consumes
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ (github.event_name == 'merge_group' || github.ref == 'refs/heads/main') && secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY || '' }}
        run: |
          pnpm exec turbo run build --concurrency=4 \
            --filter=@objectstack/spec... \
            --filter=@objectstack/client... \
            --filter=@objectstack/core... \
            --filter=@objectstack/formula... \
            --filter=@objectstack/lint... \
            --filter=@objectstack/sdui-parser... \
            --filter=@objectstack/types... \
            --summarize --log-file=.turbo/remote-cache/ui-deps.json

      - name: The Turbo remote cache was on for the build
        run: |
          node scripts/ci/assert-turbo-remote-cache.mjs --site 'Build UI Deps' \
            --log .turbo/remote-cache/ui-deps.json \
            --move-summary-to "$RUNNER_TEMP/turbo-remote-cache"

      # Keeps exactly the entries the build's run summary names, so the
      # artifact and the seed carry this closure and nothing the restored seed
      # brought with it. `save=false` (no summary) uploads and saves nothing.
      - name: Prune the Turbo cache to this build's tasks
        id: prune-turbo-cache
        run: |
          node scripts/ci/prune-turbo-cache.mjs --site 'Build UI Deps' \
            --cache .turbo/cache --run-summaries "$RUNNER_TEMP/turbo-remote-cache"

      # The entries are zstd tarballs already, so the artifact is stored, not
      # recompressed. One day: only this run's ui jobs read it.
      - name: Hand the build to the ui jobs
        if: steps.prune-turbo-cache.outputs.save == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: ui-deps-turbo-cache
          path: .turbo/cache/
          if-no-files-found: error
          compression-level: 0
          retention-days: 1
          overwrite: true

      - name: Save Turbo cache (main only)
        if: >-
          github.event_name == 'push'
          && steps.turbo-cache.outputs.cache-hit != 'true'
          && steps.prune-turbo-cache.outputs.save == 'true'
        uses: actions/cache/save@v6
        timeout-minutes: 5
        continue-on-error: true
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}

      # On `push` and `schedule` only, the rule `.github/actions/setup-workspace`
      # holds for every other job: a pull request's or queue entry's store is
      # restorable only from that ref and evicts `main`'s seeds from the pool.
      - name: Save pnpm cache
        if: >-
          (github.event_name == 'push' || github.event_name == 'schedule')
          && steps.pnpm-cache.outputs.cache-hit != 'true'
        uses: actions/cache/save@v6
        timeout-minutes: 5
        continue-on-error: true
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}

  type-check-ui:
    name: Type Check UI
    needs: [filter, ui-deps]
    if: ${{ !cancelled() && needs.filter.outputs.ui_tree != 'false' && (needs.filter.outputs.ui != 'false' || needs.filter.outputs.ui_consumers != 'false') }}
    runs-on: ubuntu-latest
    timeout-minutes: 40
    permissions:
      contents: read
    env:
      # @object-ui/app-shell's and the Console's tsc need ~2.3 GB and OOM at
      # Node's default heap (the import spike, objectstack#25678 finding 2).
      NODE_OPTIONS: --max-old-space-size=4096
      # Every turbo run writes its summary to `.turbo/runs/`, which the prune
      # before the seed save reads (neither enters a task hash).
      TURBO_RUN_SUMMARY: 'true'

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          # The affected scope below asks turbo for the packages changed since
          # the base commit, which needs the base's history in the clone.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      # Restore only: Build UI Deps saves the store (see the ui jobs' header).
      - name: Restore pnpm cache
        uses: actions/cache/restore@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Restore Turbo cache
        id: turbo-cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-${{ github.job }}-
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

      # Build UI Deps' turbo cache entries for the seven packages, which the
      # build step below replays (that job's comment). Fails open: without
      # them the build step builds cold, as it did before that job existed.
      - name: Download the @objectstack packages objectui consumes
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: ui-deps-turbo-cache
          path: .turbo/cache

      # objectui runs this first because it is instant and catches the
      # structural mistake: turbo skips a package with no `type-check` script,
      # so without it a package that lacks one reads as passing.
      - name: Verify type-check coverage
        run: pnpm --dir ui run type-check:coverage

      # objectui's `lockfile-integrity.yml` (objectui#8326), row 19 of the
      # objectstack#25697 workflow roster, ported by objectstack#26717: a pull
      # request's `pnpm-lock.yaml` may not give any package a second physical
      # copy. The script's header has the mechanism and its boundary.
      #
      # It lives here because this job already checks out with
      # `fetch-depth: 0`, so `origin/<base>` and the merge base are in the
      # clone, and because it runs on every change to `pnpm-lock.yaml` (the
      # `ui` filter lists it). Before the install on purpose: the gate reads
      # two text files with Node builtins only, which Lint UI's pre-install
      # import graph check holds. `pull_request` only, because the gate's
      # subject is the pull request's delta against its base; a push or queue
      # run has none of its own.
      #
      # ⛔ `continue-on-error` keeps it an ALARM, as objectui ran it: a finding
      # prints an `::error::` annotation naming the packages on the pull
      # request and does NOT fail this required job. Making it blocking is a
      # maintainer decision (`NOT_A_GATE` in `ui/scripts/dependabot-merge-gate.mjs`
      # says why), not a step edit.
      - name: check:lockfile-integrity — compare this pull request's lockfile with its merge base
        if: github.event_name == 'pull_request'
        continue-on-error: true
        env:
          BASE_REF: ${{ github.base_ref }}
        run: pnpm --dir ui run check:lockfile-integrity --base-ref "origin/${BASE_REF}"

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

      # The seven packages objectui installs from this tree, and their own
      # dependencies. The repo-root programs below import them before any
      # turbo type-check task has built them.
      - name: Build the @objectstack packages objectui consumes
        run: |
          pnpm exec turbo run build --concurrency=4 \
            --filter=@objectstack/spec... \
            --filter=@objectstack/client... \
            --filter=@objectstack/core... \
            --filter=@objectstack/formula... \
            --filter=@objectstack/lint... \
            --filter=@objectstack/sdui-parser... \
            --filter=@objectstack/types...

      - name: Verify every imported package is declared by the package that ships it
        run: pnpm --dir ui run check:phantom-deps

      - name: Verify no package imports itself by name
        run: pnpm --dir ui run check:self-import

      - name: Verify no covered package ships a source file nothing reaches
        run: pnpm --dir ui run check:unreferenced-sources

      - name: Verify no doc comment prescribes a spelling a shared reader owns
        run: pnpm --dir ui run check:doc-example-readers

      - name: Verify every handler key a registered renderer reads is declared by its arm
        run: pnpm --dir ui run check:handler-key-reads

      - name: Verify every object-metadata write door applies the write guard
        run: pnpm --dir ui run check:metadata-write-doors

      - name: Verify published build tsconfigs exclude tooling directories
        run: pnpm --dir ui run check:published-tsconfig-exclude

      - name: Verify every sideEffects array names exactly its registering modules
        run: pnpm --dir ui run check:side-effects-array

      - name: Verify every ElementDataSourceGate wrapper reaches the declaration seam
        run: pnpm --dir ui run check:element-data-source-declaration

      - name: Verify published ESM packages emit resolvable relative specifiers
        run: pnpm --dir ui run check:esm-specifiers

      - name: Verify spec-named symbols are derived, not hand-written
        run: pnpm --dir ui run check:spec-symbols

      - name: Verify action renderers forward every key the runtime reads
        run: pnpm --dir ui run check:action-forward-parity

      - name: Verify designer field payloads declare only keys FieldSchema accepts
        run: pnpm --dir ui run check:designer-field-key-parity

      - name: Verify authored icon names are live lucide icons keys
        run: pnpm --dir ui run check:icon-record-names

      - name: Verify t() call-site keys exist in the en locale pack
        run: pnpm --dir ui run check:i18n-keys

      - name: Verify changed en strings were followed by the nine translations
        run: pnpm --dir ui run check:i18n-drift

      - name: Type-check the ui scripts
        run: pnpm --dir ui run type-check:scripts

      - name: Type-check the ui root Vitest config
        run: pnpm --dir ui run type-check:vitest-config

      # objectui's `//#type-check:e2e` root task, which its turbo.json made a
      # dependency of every `type-check`; here it is this step.
      - name: Type-check the ui e2e suite
        run: pnpm --dir ui run type-check:e2e

      # A pull_request or merge_group run type-checks the ui packages turbo
      # reports changed since the base, plus their dependents — a change to
      # one of the seven @objectstack packages selects every ui package that
      # depends on it, which is how a spec change compiles the Console here.
      # Every other event, and any run without a base, type-checks every ui
      # package. The exclusions keep the task on ui packages: this repo's own
      # packages spell the script `typecheck` and Type Check · workspace in
      # lint.yml owns them, and `./ui` is objectui's root manifest, whose
      # `type-check` script is `turbo run type-check` itself.
      - name: Run type-check over the ui packages
        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" ;;
            *) base='' ;;
          esac
          if [ -n "$base" ]; then
            echo "Affected scope: ui packages changed since $base, and their dependents."
            pnpm exec turbo run type-check --concurrency=4 \
              "--filter=...[$base]" \
              --filter='!./ui' \
              --filter='!./packages/**' \
              --filter='!./apps/**' \
              --filter='!./examples/**'
          else
            echo "Full scope: every ui package ($EVENT run)."
            pnpm exec turbo run type-check --concurrency=4 \
              --filter='./ui/packages/*' \
              --filter='./ui/apps/*' \
              --filter='./ui/examples/*'
          fi

      # ui/tsconfig.vitest-setup.json resolves five @object-ui packages through
      # their built declarations (its `paths` comment measures the from-source
      # route at 484 errors). The step above builds them only when they are in
      # its affected scope, and a pull_request whose ui scope is empty builds
      # nothing, so the next step failed with TS2882/TS2307. Turbo replays
      # them from the cache when the step above or main's cache already built them.
      - name: Build the ui packages the vitest setup files import
        run: |
          pnpm exec turbo run build --concurrency=4 \
            --filter=@object-ui/components \
            --filter=@object-ui/fields \
            --filter=@object-ui/plugin-dashboard \
            --filter=@object-ui/plugin-grid \
            --filter=@object-ui/i18n

      - name: Type-check ui repo-root vitest setup files
        run: pnpm --dir ui run type-check:vitest-setup

      # Bookkeeping after the last checking step (the ui jobs' header): the
      # seed keeps only the entries this job's turbo runs used.
      - name: Prune the Turbo cache to this run's tasks (main only)
        id: prune-turbo-cache
        if: always() && github.event_name == 'push'
        run: |
          node scripts/ci/prune-turbo-cache.mjs --site 'Type Check UI' \
            --cache .turbo/cache --run-summaries .turbo/runs

      - name: Save Turbo cache (main only)
        if: >-
          always() && github.event_name == 'push'
          && steps.turbo-cache.outputs.cache-hit != 'true'
          && steps.prune-turbo-cache.outputs.save == 'true'
        uses: actions/cache/save@v6
        timeout-minutes: 5
        continue-on-error: true
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}

  # ── Test UI: the shard count ────────────────────────────────────────────
  # N = 16, objectui's own matrix, chosen the way scripts/partition-test-shards.mjs
  # chooses Test Core's: the slowest leg within MAX_SHARD_OVER_MEAN (1.3) of the
  # mean, and no more legs than that bound and the job timeout need.
  #
  # The unit is a FILE here, not a package, because objectui is one vitest root
  # (`vitest run` with its unit / dom / dom-heavy projects) whose sequencer
  # (ui/scripts/test-shard-sequencer.mjs) already places files on legs by
  # measured duration, LPT, from ui/scripts/test-shard-timings.json — the same
  # algorithm partition-test-shards.mjs runs over packages. Measured over that
  # dataset (4979 files, 325.7 summed file-minutes, heaviest file 76.6 s):
  #   - by PACKAGE, @object-ui/app-shell alone is 104.2 of the 325.7 minutes,
  #     so the 1.3 bound admits at most 4 legs (325.7 x 1.3 / 104.2 = 4.06)
  #     and every leg would carry ~81 summed minutes;
  #   - by FILE, LPT gives max/mean = 1.000 at 6, 8, 12, 16 and 24 legs, so the
  #     bound never binds and N is set by the wall clock: 16 legs carry 20.4
  #     summed file-minutes each, which objectui's 20-minute timeout was sized
  #     against (vitest runs those files across the runner's workers).
  # Raising N past 16 only adds runners; lowering it pushes a leg past the
  # timeout objectui measured. ⛔ The dataset's keys are paths relative to the
  # vitest root, so the suite must run with cwd = ui/ (it does, below); run
  # from this repo's root every key misses and every file weighs the median.
  #
  # ── Test UI: the two speeds (#25868) ────────────────────────────────────
  # `push`, `schedule` and `workflow_dispatch` run the whole suite: the full
  # battery. `pull_request` and `merge_group` run the files
  # ui/scripts/select-affected-tests.mjs selects -- the ui packages the change
  # sits in and their dependents, plus the tests the package graph cannot
  # place, which run on every change -- or the whole suite when the change
  # reaches something every ui test runs through, outside ui/ included (a
  # non-documentation root file, `patches/`, one of the seven packages the
  # `ui_consumers` filter names). The selector's header states the rules and
  # what it does not see; the full battery on `main` is the backstop.
  test-ui:
    name: Test UI (${{ matrix.shard }}/16)
    needs: [filter, ui-deps]
    if: ${{ !cancelled() && needs.filter.outputs.ui_tree != 'false' && needs.filter.outputs.ui != 'false' }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          # The select step below diffs against the base commit, which needs
          # the base's history in the clone.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      # Restore only: Build UI Deps saves the store (see the ui jobs' header).
      - name: Restore pnpm cache
        uses: actions/cache/restore@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # Build UI Deps' turbo cache entries for the seven packages, which the
      # build step below replays (that job's comment). Fails open: without
      # them the build step builds cold, as it did before that job existed.
      # No turbo seed of this job's own: that build is its only turbo run.
      - name: Download the @objectstack packages objectui consumes
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: ui-deps-turbo-cache
          path: .turbo/cache

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

      # objectui's suite resolves its own packages from source and the seven
      # @objectstack packages from their built dist, which the pin used to
      # supply prebuilt.
      - name: Build the @objectstack packages objectui consumes
        run: |
          pnpm exec turbo run build --concurrency=4 \
            --filter=@objectstack/spec... \
            --filter=@objectstack/client... \
            --filter=@objectstack/core... \
            --filter=@objectstack/formula... \
            --filter=@objectstack/lint... \
            --filter=@objectstack/sdui-parser... \
            --filter=@objectstack/types...

      # Fails OPEN: a selector that exits non-zero, prints no verdict, or has
      # no base to diff against means the whole suite, never a skip. The exit
      # status is captured beside the output, not through a command
      # substitution. A pull request diffs from merge-base(origin/<base ref>,
      # HEAD), never the payload's `base.sha`, which is frozen when the PR is
      # opened: everything `main` gained since would be charged to this PR,
      # and a lockfile change among it would make every long-open PR a full
      # run (Test Core's "WHERE THE AFFECTED DIFF STARTS" above is the same
      # fact). A merge group diffs from its `base_sha`. Every shard computes
      # the same selection from the same checkout, so `--shard` partitions
      # one set.
      - name: Select the tests this change affects
        id: select
        env:
          EVENT: ${{ github.event_name }}
          PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          QUEUE_BASE: ${{ github.event.merge_group.base_sha }}
        run: |
          base=''
          case "$EVENT" in
            pull_request)
              if [ -n "$PR_BASE_REF" ]; then
                base=$(git merge-base "refs/remotes/origin/$PR_BASE_REF" HEAD) || base=''
              fi
              ;;
            merge_group) base="$QUEUE_BASE" ;;
            *)
              echo 'mode=full' >> "$GITHUB_OUTPUT"
              echo "A $EVENT run is the full battery: every ui test file, sixteen shards."
              exit 0
              ;;
          esac
          status=0
          if [ -z "$base" ]; then
            echo "::warning::no diff base on this $EVENT event; running the full suite rather than guessing."
            status=2
          else
            echo "Diff base: $base"
            node ui/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"

      # `$MODE` is the VALUE of the select step's output `mode`: its
      # `mode=affected` line is GitHub's `key=value` form, so what arrives here
      # is `affected` or `full`, never the line itself.
      # ui/scripts/__tests__/select-affected-tests-wiring.test.ts runs both
      # steps as written, so neither end can be renamed alone. The filters are
      # paths relative to ui/, the vitest root, passed as positionals with no
      # `--`, the only spelling ui/scripts/vitest-invocation-guard.mjs admits.
      #
      # objectui's full-battery runs also pass its per-file timings reporter
      # and upload the result for the weekly dataset refresh. Both belong to
      # that refresh workflow, which is in the governance-workflow audit
      # (sub-issue 4 of the epic); until it is ported the committed dataset
      # is what the sequencer reads.
      - name: Run the ui tests (shard ${{ matrix.shard }}/16)
        env:
          MODE: ${{ steps.select.outputs.mode }}
        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 --dir ui exec vitest run --shard=${{ matrix.shard }}/16 --reporter=default --reporter=github-actions "${filters[@]}"
          else
            pnpm --dir ui run test --shard=${{ matrix.shard }}/16 --reporter=default --reporter=github-actions
          fi

  test-ui-gate:
    # Stable required-check name for the sharded Test UI matrix (#26460, ruling
    # A, comment 6435318516), in test-gate's shape and for test-gate's reason
    # (#3622): a matrix publishes only `Test UI (k/16)`, so the bare `Test UI`
    # context the ruleset requires can come from nothing but this job, and the
    # shard count stays free to move without a settings edit. Until this job,
    # none of the 16 shards was required and the queue landed PRs whose Test UI
    # was red (#26419 → #26421).
    #
    # `name:` and `if: always()` are both load-bearing, as on test-gate. The
    # name IS the required context (`check:required-contexts` pins the
    # literal), and a gate that skips because a dependency failed publishes no
    # context at all, which leaves the PR permanently pending (#3622). ⛔ Never
    # `if: !cancelled()` here.
    #
    # The verdict reads the matrix rollup `needs.test-ui.result`, and only
    # `success` passes, with one exception: `skipped`, when `filter` concluded
    # `success` AND said the diff reaches no ui path (the shards' own `if:`).
    # That is #4928's skipped-only-when-filter-succeeded guard, and it makes a
    # queue build or PR that touches no ui path read green here the way Lint
    # UI and Build & E2E UI read `skipped` there. Everything else is red:
    # `failure`; `cancelled`, which is also what a shard killed by its own
    # `timeout-minutes` reads (on a superseded push this paints the OLD sha
    # red, which no required check reads); a `skipped` that `filter` does not
    # explain; and any lifecycle value such as the `abandoned` test-gate met
    # (run 31120902911). Unlike test-gate it counts no shard credentials: the
    # Test UI shards publish none, and adding them is a change to `test-ui`,
    # which is the ui lane's job.
    name: Test UI
    needs: [test-ui, filter]
    # ── ROSTER DECLARATION (#10490) ───────────────────────────────────────
    # `check:aggregator-roster` holds this equal to `needs:` in both
    # directions. `filter` is the #4928 input, not a lane.
    env:
      OS_AGGREGATOR_MEMBERS: test-ui
      OS_AGGREGATOR_NON_MEMBERS: filter
    if: always()
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    steps:
      - name: Verify Test UI shard results
        env:
          OS_TEST_UI_RESULT: ${{ needs['test-ui'].result }}
          OS_FILTER_RESULT: ${{ needs.filter.result }}
          OS_UI_TREE: ${{ needs.filter.outputs.ui_tree }}
          OS_UI: ${{ needs.filter.outputs.ui }}
        run: |
          echo "Test UI (k/16) rollup: '$OS_TEST_UI_RESULT'; filter: '$OS_FILTER_RESULT' (ui_tree='$OS_UI_TREE', ui='$OS_UI')."
          case "$OS_TEST_UI_RESULT" in
            success)
              echo "✓ Test UI: every shard concluded success."
              ;;
            skipped)
              if [ "$OS_FILTER_RESULT" = 'success' ] && { [ "$OS_UI_TREE" = 'false' ] || [ "$OS_UI" = 'false' ]; }; then
                echo "✓ Test UI: the shards were skipped because filter found no ui path in this diff."
              else
                echo "::error title=Test UI::the Test UI shards were skipped, but filter (result '$OS_FILTER_RESULT', ui_tree='$OS_UI_TREE', ui='$OS_UI') does not explain the skip. A skip passes only when filter succeeded and said the diff reaches no ui path (#4928)."
                exit 1
              fi
              ;;
            *)
              echo "::error title=Test UI::the Test UI shards concluded '$OS_TEST_UI_RESULT', not success. Read the red 'Test UI (k/16)' check-runs on this sha for the failing test; a shard killed by its timeout reads 'cancelled'."
              exit 1
              ;;
          esac

  # ── Lint UI and Build & E2E UI: the ceilings (#25869 row F13) ──────────
  # objectui's rule (its lint.yml `Lint` ceiling): the smallest round number
  # that is both >= 3x the slowest successful run and >= that run + 15 min, so
  # a healthy-but-slow runner cannot hit it and a wedge dies in minutes rather
  # than hours. ⛔ Raising one is the ruled-out non-fix (objectui#6577,
  # objectui#7048): the hang runs longer and the check still reads `cancelled`.
  # Population: every successful job of each name in the CI runs completed
  # between the ui/ cutover and 2026-10-26T05:30Z, `completed_at` minus
  # `started_at` from the Actions jobs endpoint, before Build UI Deps existed
  # (so each run includes a cold seven-package build of up to 288 s):
  #   - Lint UI: n=42, min 71 s, median 112 s, p95 524 s, max 558 s (9.3 min)
  #     => max(27.9, 24.3) => 30, the value it was ported with. Re-derived
  #     for objectui's Repo Gates (objectstack#25880), which add ~174 s (their
  #     first PR run, 286 s, less the 112 s median): 558 + 174 = 732 s
  #     (12.2 min) => max(36.6, 27.2) => 40.
  #   - Build & E2E UI: n=51, min 106 s, median 170 s, p95 423 s, max 457 s
  #     (7.6 min) => max(22.9, 22.6) => 25, down from objectui's 30 plus the
  #     15 the port added for the in-job build, which no derivation backed.
  #     Re-derived for the SDUI manifest regeneration (objectstack#26137),
  #     which adds 213 s cold (the 27 @object-ui builds plus the enumeration,
  #     measured on main 81bba6c3f): 457 + 213 = 670 s (11.2 min)
  #     => max(33.5, 26.2) => 35.
  # Re-derive when a job's work changes; ui/scripts/__tests__/
  # turbo-cache-save-bound.test.ts holds both values.
  lint-ui:
    name: Lint UI
    needs: [filter, ui-deps]
    if: ${{ !cancelled() && needs.filter.outputs.ui_tree != 'false' && needs.filter.outputs.ui != 'false' }}
    runs-on: ubuntu-latest
    timeout-minutes: 40
    permissions:
      contents: read
    env:
      # Every turbo run writes its summary to `.turbo/runs/`, which the prune
      # before the seed save reads (neither enters a task hash).
      TURBO_RUN_SUMMARY: 'true'

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

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      # Restore only: Build UI Deps saves the store (see the ui jobs' header).
      - name: Restore pnpm cache
        uses: actions/cache/restore@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Restore Turbo cache
        id: turbo-cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-${{ github.job }}-
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

      # Build UI Deps' turbo cache entries for the seven packages, which the
      # build step below replays (that job's comment). Fails open: without
      # them the build step builds cold, as it did before that job existed.
      - name: Download the @objectstack packages objectui consumes
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: ui-deps-turbo-cache
          path: .turbo/cache

      - name: Verify ui lint coverage
        run: pnpm --dir ui run lint:coverage

      - name: Verify every ui scripts entry guard goes through one predicate
        run: |
          pnpm --dir ui run check:entry-guard --self-test
          pnpm --dir ui run check:entry-guard

      - name: Verify the ui shell holds the bash 3.2 floor
        run: |
          pnpm --dir ui run check:bash32-floor --self-test
          pnpm --dir ui run check:bash32-floor

      # ── objectui's Repo Gates (objectstack#25880) ────────────────────────
      # The gates of objectui's `repo-gates.yml`, which GitHub stopped running
      # when the tree moved under `ui/` (it reads only this repository's
      # `.github/workflows/`), and which objectstack#25712 deleted with the
      # rest of `ui/.github/workflows/`. They judge what objectui ships
      # — `ui/content/docs/**`, the skill bundle (`skills/objectui/**` at the
      # repository root since objectstack#26097), the package READMEs and the
      # documented component types — so the change most likely to trip them is
      # a docs-only or skills-only PR, which the `filter` job's `ui` globs
      # include.
      #
      # Ported as that workflow ran them, in its order: the install-free gates
      # here, before the install; the gates that read built `dist/*.d.ts` after
      # this job's last build, below. Every step keeps its `<check> — <step>`
      # name, and every one runs `if: !cancelled()` (or on the install / build
      # it needs), so one red gate never hides another of these; each script's
      # header is the authority on what it checks. Dropped in the port: the
      # `.objectstack-pin` restore / build / save (the merged tree builds
      # `@objectstack/*` from the workspace, see the header above
      # `type-check-ui`) and the turbo-cache report / prune bookkeeping (this
      # job's own restore and save serve the build below). Retired since: the
      # Action Ref Convention scan, which judged objectui's own workflows and
      # went with them (objectstack#25712); a repository-wide action-ref
      # convention needs a home that no `ui` path filter skips (sub-issue 4).
      - name: Control Byte Scan — Scan tracked text files for raw control bytes
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:control-bytes

      # Self-test first: a scan whose recogniser is broken reports a clean
      # tree. It derives its population from this repository's workflows, so
      # it walks this job's install-free steps, itself included.
      - name: Pre-Install Import Graph Check — Check the pre-install gates' import graphs
        if: ${{ !cancelled() }}
        run: |
          pnpm --dir ui run check:pre-install-import-graph --self-test
          pnpm --dir ui run check:pre-install-import-graph

      - name: Shell Escape Residue Scan — Check for machine-produced shell-escape residue in fenced examples
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:shell-escape-residue

      - name: Inert vi.mock Specifier Check — Check every relative vi.mock specifier resolves
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:vi-mock-specifiers

      - name: Inert vi.mock Specifier Check — Check every covered vi.mock factory inherits the real export surface
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:vi-mock-inherit

      - name: Internal Docs Link Check — Check internal docs links
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run docs:check-links

      - name: Doc Fence Language Check — Check that no fence spelling hides a TypeScript block
        if: ${{ !cancelled() }}
        run: |
          pnpm --dir ui run check:doc-fences --self-test
          pnpm --dir ui run check:doc-fences

      - name: Doc Example Id Check — Check documented example ids against the catalog registry
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:doc-example-ids

      - name: Doc Component Type Check — Check documented component types against the registry
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:doc-types

      - name: Doc Component Type Check — Check prompt-taught component keys render
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:prompt-keys

      - name: Skill Guide Path Check — Check paths stated in the skill guides
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:skills-paths

      - name: Skill Eval Token Check — Self-test the oracle and the whole-token rule, both directions
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:skill-eval-tokens --self-test

      - name: Skill Eval Token Check — Check every eval must_contain token against the guides
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:skill-eval-tokens

      - name: Docs Route Eager Closure Check — Weigh the docs route eager closure
        if: ${{ !cancelled() }}
        run: pnpm --dir ui run check:docs-route-closure

      - name: Install dependencies
        id: install
        if: ${{ !cancelled() }}
        run: pnpm install --frozen-lockfile

      # The spec liveness ledger cites the renderer in-repo, under ui/
      # (objectstack#26150), so a ui/ change can delete a file a ledger row
      # cites, move a cited line past the end of its file, drop an anchored
      # symbol or stop naming the cited key. Spec Liveness Check does not run on
      # a ui/-only pull request (its `paths:` are the spec side) and is not a
      # required context, so the gate runs here too, where every ui/ change
      # starts it (objectstack#25712 F26). It runs tsx over spec's sources and
      # needs the install alone; about 3 s.
      - name: Spec Liveness Check — Check the liveness ledger's citations, ui/ included
        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
        run: pnpm --filter @objectstack/spec check:liveness

      - name: Build the @objectstack packages objectui consumes
        run: |
          pnpm exec turbo run build --concurrency=4 \
            --filter=@objectstack/spec... \
            --filter=@objectstack/client... \
            --filter=@objectstack/core... \
            --filter=@objectstack/formula... \
            --filter=@objectstack/lint... \
            --filter=@objectstack/sdui-parser... \
            --filter=@objectstack/types...

      # objectui's `//#lint:root` root task, which its turbo.json made a
      # dependency of every `lint`; here it is this step.
      - name: Lint the ui repo-root files
        run: pnpm --dir ui run lint:root

      - name: Lint the ui packages
        run: |
          pnpm exec turbo run lint --concurrency=4 \
            --filter='./ui/packages/*' \
            --filter='./ui/apps/*' \
            --filter='./ui/examples/*'

      - name: Check every vi.mock override matches the declared export shape
        run: pnpm --dir ui run check:vi-mock-override-shape

      - name: Verify no ui test resolves a repository path from the process cwd
        run: pnpm --dir ui run check:test-path-roots

      - name: Build the ui CLI the self-check runs
        run: pnpm exec turbo run build --concurrency=4 --filter='./ui/packages/cli...'

      - name: Verify the ui CLI's own check command passes on the ui tree
        run: pnpm --dir ui run check

      # ── objectui's Repo Gates that read the built type surface ───────────
      # Gated on the install alone, so a red lint step above hides none of
      # them. The two derive steps capture the gate's status before writing
      # the output: a command substitution inside `echo` reports `echo`'s
      # status, and a failed derivation would read as an empty filter.
      - name: Skill Example Check — Derive the packages the marked examples import
        id: ui-skill-filter
        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
        run: |
          status=0
          args="$(pnpm --dir ui run --silent check:skill-examples --build-filter)" || status=$?
          if [ "$status" -ne 0 ]; then
            echo "::error::Could not derive the build filter: \`check:skill-examples --build-filter\` exited $status. Refusing to continue — carrying on would build every package instead of the ones the marked examples import." >&2
            exit "$status"
          fi
          case "$args" in
            *--filter=*) ;;
            *)
              echo "::error::The derived build filter names no package (got: '$args'). Refusing to continue." >&2
              exit 1
              ;;
          esac
          echo "args=$args" >> "$GITHUB_OUTPUT"

      - name: Doc Snippet Type Check — Derive the packages the covered snippets import
        id: ui-snippet-filter
        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
        run: |
          status=0
          args="$(pnpm --dir ui run --silent check:doc-snippets --build-filter)" || status=$?
          if [ "$status" -ne 0 ]; then
            echo "::error::Could not derive the build filter: \`check:doc-snippets --build-filter\` exited $status. Refusing to continue — carrying on would build every package instead of the ones the covered snippets import." >&2
            exit "$status"
          fi
          case "$args" in
            *--filter=*) ;;
            *)
              echo "::error::The derived build filter names no package (got: '$args'). Refusing to continue." >&2
              exit 1
              ;;
          esac
          echo "args=$args" >> "$GITHUB_OUTPUT"

      # One build for the gates below: every package under `ui/packages/` (the
      # README export check reads each one's declared type entry) in union with
      # the two derived closures. The derived filters are lists of `--filter=`
      # words and stay unquoted so they word-split. ⛔ Never an unfiltered
      # `turbo run build`.
      - name: Build every ui package the gates below read
        id: ui-gate-build
        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
        env:
          SKILL_FILTER: ${{ steps.ui-skill-filter.outputs.args }}
          SNIPPET_FILTER: ${{ steps.ui-snippet-filter.outputs.args }}
        run: pnpm exec turbo run build --concurrency=4 --filter='./ui/packages/*' $SKILL_FILTER $SNIPPET_FILTER

      - name: Skill Example Check — Self-test the marker convention, both directions
        if: ${{ !cancelled() && steps.ui-gate-build.outcome == 'success' }}
        run: pnpm --dir ui run check:skill-examples --self-test

      - name: Skill Example Check — Check the marked skill examples against the built types
        if: ${{ !cancelled() && steps.ui-gate-build.outcome == 'success' }}
        run: pnpm --dir ui run check:skill-examples

      # Report-only: exits 0 whatever it finds, non-zero only when the
      # instrument is broken. Before the blocking gate, so its census is read
      # on exactly the runs where the corpus moved.
      - name: Doc Snippet Type Check — Census the code emitted from template literals (report-only)
        if: ${{ !cancelled() && steps.ui-gate-build.outcome == 'success' }}
        run: pnpm --dir ui run check:doc-snippets --emit-census

      - name: Doc Snippet Type Check — Compile documentation snippets against the built types
        if: ${{ !cancelled() && steps.ui-gate-build.outcome == 'success' }}
        run: pnpm --dir ui run check:doc-snippets

      - name: Doc Snippet Type Check — Compile JSDoc `@example` blocks against the built types
        if: ${{ !cancelled() && steps.ui-gate-build.outcome == 'success' }}
        run: pnpm --dir ui run check:doc-examples

      - name: Doc Snippet Type Check — Judge JSON doc fences through the strict authoring face
        if: ${{ !cancelled() && steps.ui-gate-build.outcome == 'success' }}
        run: pnpm --dir ui run check:doc-json

      - name: README Export Check — Check every README self-import against the real export surface
        if: ${{ !cancelled() && steps.ui-gate-build.outcome == 'success' }}
        run: pnpm --dir ui run check:readme-exports

      # Bookkeeping after the last checking step (the ui jobs' header): the
      # seed keeps only the entries this job's turbo runs used.
      - name: Prune the Turbo cache to this run's tasks (main only)
        id: prune-turbo-cache
        if: always() && github.event_name == 'push'
        run: |
          node scripts/ci/prune-turbo-cache.mjs --site 'Lint UI' \
            --cache .turbo/cache --run-summaries .turbo/runs

      - name: Save Turbo cache (main only)
        if: >-
          always() && github.event_name == 'push'
          && steps.turbo-cache.outputs.cache-hit != 'true'
          && steps.prune-turbo-cache.outputs.save == 'true'
        uses: actions/cache/save@v6
        timeout-minutes: 5
        continue-on-error: true
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.ref_name }}-${{ github.sha }}

  build-e2e-ui:
    name: Build & E2E UI
    needs: [filter, ui-deps]
    if: ${{ !cancelled() && needs.filter.outputs.ui_tree != 'false' && (needs.filter.outputs.ui != 'false' || needs.filter.outputs.ui_consumers != 'false') }}
    runs-on: ubuntu-latest
    # Derived above Lint UI.
    timeout-minutes: 35
    permissions:
      contents: read
    env:
      # The Console's build runs tsc over ~3.5k files and OOMs at Node's default
      # heap (the import spike, objectstack#25678 finding 2).
      NODE_OPTIONS: --max-old-space-size=4096

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

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      # Restore only: Build UI Deps saves the store (see the ui jobs' header).
      - name: Restore pnpm cache
        uses: actions/cache/restore@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # Build UI Deps' turbo cache entries for the seven packages, which the
      # build step below replays (that job's comment). Fails open: without
      # them the build step builds cold, as it did before that job existed.
      # No turbo seed of this job's own: that build is its only turbo run.
      - name: Download the @objectstack packages objectui consumes
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: ui-deps-turbo-cache
          path: .turbo/cache

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

      - name: Build the @objectstack packages objectui consumes
        run: |
          pnpm exec turbo run build --concurrency=4 \
            --filter=@objectstack/spec... \
            --filter=@objectstack/client... \
            --filter=@objectstack/core... \
            --filter=@objectstack/formula... \
            --filter=@objectstack/lint... \
            --filter=@objectstack/sdui-parser... \
            --filter=@objectstack/types...

      # The repo-root SDUI manifest, regenerated from this tree and compared
      # with the committed bytes (#26137). The generator builds the registry
      # with turbo: the 36 tasks of the step above replay, and the 27
      # @object-ui packages build (3m25s cold, measured on 4 cores, on main
      # 81bba6c3f), then it enumerates the registry under plain Node (~8 s; ~6 s
      # for the whole run when nothing moved). It serialises through the
      # @objectstack/sdui-parser the step above built, so a parser edit moves
      # this verdict too. On merge_group it runs on the queue's combined tree,
      # the one run that sees two entries' effect on the manifest together.
      # Only the artefact is compared: the record the generator rewrites beside
      # it is held by `check-sdui-manifest` in lint.yml. The Console build below
      # reads the registry through its src/ aliases, so the dist this step
      # builds does not reach it.
      - name: The committed SDUI manifest is the one this tree generates
        run: |
          node scripts/gen-sdui-manifest-node.mjs
          if ! git diff --quiet -- sdui.manifest.json; then
            echo "::error file=sdui.manifest.json::sdui.manifest.json is not the manifest this tree generates. Run 'node scripts/gen-sdui-manifest-node.mjs' and commit what it writes."
            git diff --stat -- sdui.manifest.json
            git diff -- sdui.manifest.json | head -n 200
            exit 1
          fi
          echo "sdui.manifest.json is byte-identical to this tree's regeneration."

      - name: Build the Console for E2E
        env:
          VITE_BASE_PATH: /console/
        run: pnpm --dir ui/apps/console exec vite build

      - name: Verify the Console build artifact
        run: |
          if [ ! -f ui/apps/console/dist/index.html ]; then
            echo "::error::ui/apps/console/dist/index.html is missing: the Console build produced nothing."
            exit 1
          fi
          echo "Console build artifact is ready."

      # ── Two objectui gates that read this job's build (#26717) ──────────
      # Rows 7 and 22 of the objectstack#25697 workflow roster, "kept,
      # follow-up port": objectui ran them in its own workflows, which have run
      # nowhere since #26058 deleted `ui/.github/workflows/`. Folded in here
      # because this job already builds what they read, so neither pays a
      # build of its own (row 22's note: no second Console build).
      #
      # The Console's eager-closure budget (objectui's performance-budget.yml).
      # The Vite build above writes `ui/apps/console/dist/eager-closure.json`
      # and `chunk-membership.json` in every build; the checker weighs them
      # against the ceilings it carries, next to the reasoning behind each, so
      # no size is copied into this file. Exit 1 is a size verdict, exit 2 a
      # gauge that produced no trustworthy reading; both fail the step.
      #
      # On a pull request the checker also asks whether the ceilings it was
      # checked out with are still the ones on the base branch (objectui#6245:
      # GitHub does not re-run a PR's checks when the base moves). This step
      # hands it the base branch's copy of the checker at two commits. It is
      # `continue-on-error` and that is NOT a fail-open: when it cannot write
      # both files the checker finds the variables unset and exits 2.
      - name: check:eager-closure — resolve the base-branch ceiling constants
        if: ${{ github.event_name == 'pull_request' }}
        continue-on-error: true
        env:
          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          BASE_REF: ${{ github.base_ref }}
        run: |
          set -euo pipefail
          CHECKER='ui/scripts/check-eager-closure-budget.mjs'
          OUT="${RUNNER_TEMP}/eager-closure-ceilings"
          mkdir -p "$OUT"

          # The commit the merge ref was computed against.
          if ! git cat-file -e "${PR_BASE_SHA}^{commit}" 2>/dev/null; then
            git fetch --no-tags --depth=1 origin "$PR_BASE_SHA"
          fi
          git cat-file -p "${PR_BASE_SHA}:${CHECKER}" > "$OUT/pr-base.partial"
          mv "$OUT/pr-base.partial" "$OUT/pr-base.mjs"

          # The base branch as it stands now, which the merge would land on.
          git fetch --no-tags --depth=1 origin "+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}"
          BASE_SHA=$(git rev-parse "refs/remotes/origin/${BASE_REF}")
          git cat-file -p "${BASE_SHA}:${CHECKER}" > "$OUT/base.partial"
          mv "$OUT/base.partial" "$OUT/base.mjs"

          # Written only after both moves: a half-written pair would let the
          # checker compare against a file it takes for the base branch.
          {
            echo "EAGER_CLOSURE_PR_BASE_SOURCE=$OUT/pr-base.mjs"
            echo "EAGER_CLOSURE_BASE_SOURCE=$OUT/base.mjs"
            echo "EAGER_CLOSURE_PR_BASE_SHA=$PR_BASE_SHA"
            echo "EAGER_CLOSURE_BASE_SHA=$BASE_SHA"
            echo "EAGER_CLOSURE_BASE_REF=$BASE_REF"
          } >> "$GITHUB_ENV"

          echo "Ceilings resolved: ${PR_BASE_SHA} (this checkout's base) vs ${BASE_SHA} (${BASE_REF} now)"

      - name: check:eager-closure — weigh the Console's eager closure against its budget
        run: pnpm --dir ui run check:eager-closure

      # The built-artifact pins of @object-ui/components (objectui's ci.yml
      # "Test (dist pins)"). They import the package's `dist/`, which the
      # Test UI lane never builds (it resolves every package to `src`), so this
      # is the only lane that runs them. The task's `dependsOn: ["build"]`
      # replays the build the SDUI manifest step above already ran.
      - name: test:dist — run the built-artifact pins of @object-ui/components
        run: pnpm exec turbo run test:dist --filter=@object-ui/components

      - name: Get the Playwright version
        id: playwright-version
        run: |
          set -eo pipefail
          if ! version=$(pnpm --dir ui 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"

      - name: Restore Playwright browsers
        id: playwright-cache
        uses: actions/cache/restore@v6
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}

      - name: Install Playwright browsers
        if: steps.playwright-cache.outputs.cache-hit != 'true'
        run: pnpm --dir ui exec playwright install chromium

      # Run from inside ui/scripts: the script is cwd-agnostic apart from its
      # `pnpm exec playwright`, which resolves ui/package.json upwards.
      - name: Ensure Chromium can launch
        working-directory: ui/scripts
        run: bash ensure-chromium-ready.sh

      - name: Run the ui E2E tests
        run: pnpm --dir ui run test:e2e --project=chromium

      - name: Upload failure artefacts
        if: ${{ !cancelled() && failure() }}
        uses: actions/upload-artifact@v7
        with:
          name: ui-e2e-failure-artifacts
          path: |
            ui/playwright-report/
            ui/test-results/
          retention-days: 14

      - name: Save Playwright browsers
        if: 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 }}

  # ── Live E2E UI: the Console against a real backend (#27154) ─────────────
  # Row 17 of the objectstack#25697 workflow roster, objectui's `live-e2e.yml`,
  # "kept, follow-up port": it has run nowhere since #26058 deleted
  # `ui/.github/workflows/`. Ruling 6435339772 Q1 A made it required; ruling
  # 6464191239 letter D re-based it on the WORKSPACE backend, so it runs the
  # HEAD Console against the HEAD backend and no published version is pinned
  # anywhere (`ui/e2e/live/ci/backend.env` says why the pin retired).
  #
  # What it runs: the four allowlisted live specs, `test:e2e:live:ci`, with
  # `--retries 0` (the config's own value, stated again on the command line),
  # against `objectstack dev --seed-admin --fresh` serving `examples/app-showcase`
  # from this tree's own built CLI (`ui/e2e/live/ci/start-backend.sh`) and the
  # Console's production build served by `vite preview`, whose `/api` proxy
  # (the Console's `server.proxy`, which preview inherits) points at that
  # backend through DEV_PROXY_TARGET. ⛔ No retry wrapper and no
  # `continue-on-error` anywhere in this job: a red run is a red check.
  #
  # Gated as Build & E2E UI is. Not behind Build UI Deps: this job builds a
  # larger closure (the CLI and the showcase app's) than the seven packages that
  # job hands on, so it restores Build Core's turbo seed instead.
  #
  # Ceiling: there is no CI population yet, so it is derived from one cold
  # local run on 4 shared cores (#27154, 2026-10-28), by the rule above Lint UI:
  # install 60 s + closure build 384 s + Console build 119 s + backend boot
  # 19 s + specs 26 s + browser provisioning and setup ~120 s ≈ 730 s
  # (12.2 min) => max(36.5, 27.2) => 40. Re-derive from the first population.
  live-e2e-ui:
    name: Live E2E UI
    needs: filter
    if: ${{ !cancelled() && needs.filter.outputs.ui_tree != 'false' && (needs.filter.outputs.ui != 'false' || needs.filter.outputs.ui_consumers != 'false') }}
    runs-on: ubuntu-latest
    timeout-minutes: 40
    permissions:
      contents: read
    env:
      # The Console's build OOMs at Node's default heap (see Build & E2E UI).
      NODE_OPTIONS: --max-old-space-size=4096
      # LIVE_BACKEND_DIR is set on the two steps that run the scripts: the
      # `runner` context is not available in a job-level `env:`, and a
      # workflow that names it there does not validate at all.
      LIVE_BACKEND_PORT: '4010'
      LIVE_API_URL: http://localhost:4010
      LIVE_APP_URL: http://localhost:5190

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

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      # Restore only, here and below: Build UI Deps saves the store and Build
      # Core the turbo seed.
      - name: Restore pnpm cache
        uses: actions/cache/restore@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

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

      # The backend's closure (the CLI and the showcase app, the `pkg...` form
      # Dogfood Verify CLI uses) plus the seven packages the Console builds
      # against, the same filters as Build & E2E UI's build step.
      - name: Build the workspace backend and the @objectstack packages objectui consumes
        run: |
          pnpm exec turbo run build --concurrency=4 \
            --filter=@objectstack/cli... \
            --filter=@objectstack/example-showcase... \
            --filter=@objectstack/spec... \
            --filter=@objectstack/client... \
            --filter=@objectstack/core... \
            --filter=@objectstack/formula... \
            --filter=@objectstack/lint... \
            --filter=@objectstack/sdui-parser... \
            --filter=@objectstack/types...

      # Served at the root, where the live specs navigate.
      - name: Build the Console for the live lane
        env:
          VITE_BASE_PATH: /
        run: pnpm --dir ui/apps/console exec vite build

      - name: Get the Playwright version
        id: playwright-version
        run: |
          set -eo pipefail
          if ! version=$(pnpm --dir ui 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"

      # Build & E2E UI saves this key; this job only reads it.
      - name: Restore Playwright browsers
        id: playwright-cache
        uses: actions/cache/restore@v6
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}

      - name: Install Playwright browsers
        if: steps.playwright-cache.outputs.cache-hit != 'true'
        run: pnpm --dir ui exec playwright install chromium

      - name: Ensure Chromium can launch
        working-directory: ui/scripts
        run: bash ensure-chromium-ready.sh

      - name: Boot the workspace backend
        env:
          LIVE_BACKEND_DIR: ${{ runner.temp }}/live-backend
        run: bash ui/e2e/live/ci/start-backend.sh

      # In the background for the rest of the job; the runner reaps it at job
      # end. Ready = the Console's index answers through the preview server.
      - name: Serve the Console with vite preview
        env:
          DEV_PROXY_TARGET: http://localhost:4010
        run: |
          cd ui/apps/console
          nohup pnpm exec vite preview --port 5190 --strictPort > "$RUNNER_TEMP/vite-preview.log" 2>&1 &
          deadline=$((SECONDS + 60))
          until curl -sf -o /dev/null http://localhost:5190/; do
            if [ "$SECONDS" -ge "$deadline" ]; then
              echo "::error::vite preview did not answer on :5190 within 60 s."
              cat "$RUNNER_TEMP/vite-preview.log"
              exit 1
            fi
            sleep 1
          done
          echo "vite preview answers on :5190, proxying /api to :4010."

      - name: Run the live e2e specs
        run: pnpm --dir ui run test:e2e:live:ci --retries 0

      - name: Stop the workspace backend
        if: ${{ always() }}
        env:
          LIVE_BACKEND_DIR: ${{ runner.temp }}/live-backend
        run: bash ui/e2e/live/ci/stop-backend.sh

      - name: Upload failure artefacts
        if: ${{ !cancelled() && failure() }}
        uses: actions/upload-artifact@v7
        with:
          name: ui-live-e2e-failure-artifacts
          path: |
            ui/test-results/
            ${{ runner.temp }}/live-backend/backend.log
            ${{ runner.temp }}/vite-preview.log
          retention-days: 14

  # ── UI Published Artifacts: two objectui gates over a full build (#26717) ─
  # Rows 23 and 21 of the objectstack#25697 workflow roster, "kept, follow-up
  # port" (objectui's published-dist-gate.yml and node-esm-load-gate.yml), both
  # of which have run nowhere since #26058 deleted `ui/.github/workflows/`.
  # Each one grades BUILT artifacts of every published @object-ui package, so
  # each costs a full build, and objectui#4846's ruling (comment 5307574139)
  # refused that build on every pull request. So this job is in the full
  # battery only (THE TWO SPEEDS above `jobs:`): a pull request and a queue
  # entry skip it, `main`'s push and schedule runs carry it, and the publish
  # lane reads it before its approval. The blocking copy of the published-dist
  # scan is on the publish path itself, `scripts/release-publish.sh`, which
  # refuses to run `changeset publish` when the scan exits non-zero.
  # `ui/scripts/__tests__/check-published-dist-tooling.test.ts` pins both
  # halves of that.
  #
  # The build is the release's own (`pnpm build`, the first command of
  # `pnpm run release`), and both gates then read it with `--no-build`, the
  # order the publish path runs the scan in. `--no-build` cannot pass
  # vacuously: a published package with nothing built is `no-build-output`,
  # each gate asserts a floor on how much it inspected, and the ESM gate's
  # provenance leg refuses an artifact whose turbo task log names another tree.
  ui-published-artifacts:
    name: UI Published Artifacts
    needs: filter
    # Build & E2E UI's condition, in the full battery only.
    if: ${{ !cancelled() && needs.filter.outputs.ui_tree != 'false' && (needs.filter.outputs.ui != 'false' || needs.filter.outputs.ui_consumers != 'false') && github.event_name != 'pull_request' && github.event_name != 'merge_group' }}
    runs-on: ubuntu-latest
    # objectui gave each gate's full build 60 minutes, "generous, because a
    # timeout here reads as a gate failure". One build now serves both.
    timeout-minutes: 60
    permissions:
      contents: read
    env:
      NODE_OPTIONS: --max-old-space-size=4096

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

      # The setup is spelled out, as in the ui jobs above, rather than the
      # `setup-workspace` composite: `ui/scripts/check-pre-install-import-graph.mjs`
      # finds a job's install by its `pnpm install` line, and reads every step
      # of a job with none as running before `node_modules` exists, which the
      # two gates below (they import `typescript`) cannot.
      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      # Restore-only, here and below: the per-push jobs above own saving the
      # store and the turbo seeds.
      - name: Restore pnpm cache
        uses: actions/cache/restore@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

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

      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-ui-deps-${{ github.ref_name }}-

      - name: Build every package the release publishes
        id: build
        run: pnpm build

      # objectui#4846: no published tarball may carry tooling material
      # (`__tests__/`, `*.test.*`, `*.bench.*`, a `*.tsbuildinfo`, …). The file
      # list is `npm pack --dry-run`'s, i.e. what npm would publish.
      - name: check:published-dist — scan every published @object-ui tarball for tooling files
        run: pnpm --dir ui run check:published-dist --no-build

      # objectui#4538: every published ESM entry must load under Node's own
      # resolver, with no bundler. The per-PR half is the specifier leg in
      # Type Check UI (`check:esm-specifiers`); this is the load leg, the only
      # one that sees a package broken by a DEPENDENCY. It runs whatever the
      # scan above said, so one run reports both.
      - name: check:node-esm-load — import every published ESM entry under plain Node
        if: ${{ !cancelled() && steps.build.outcome == 'success' }}
        run: pnpm --dir ui run check:node-esm-load --no-build