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 HOURLY FULL RUN (#16467) ─────────────────────────────────────────
  # `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 hour far more than it wants a short queue wait, and a run that starts
  # a few minutes late is still the hour's run. What it must NOT do is collide
  # with the next hour's, which the concurrency group below decides.
  #
  # ⛔ This is a NEW TRIGGER KEY, not a widening of `push:`. The ⛔ above still
  # binds: `push:` stays filtered to `main`.
  schedule:
    - cron: '0 * * * *'
  # The same full battery, on demand: an operator who has just landed a fix for
  # a red hourly run should not have to wait up to an hour 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/branch waste runners and delay feedback;
# cancel them. Push runs to main group by commit ref as well, so an in-flight
# main run is cancelled only by a newer main push.
#
# ⭐ `github.event_name` IS LOAD-BEARING IN THIS KEY, and it is the whole
# reason the hourly run above can finish (#16467). On a `schedule` event
# `github.event.pull_request.number` is empty and `github.ref` is
# `refs/heads/main` — BYTE-IDENTICAL to what a push to `main` produces. Without
# the event name in the key the hourly run and the next merge share one group,
# `cancel-in-progress: true` applies, and the next merge kills the hourly run.
# That is not a hypothetical: this card's own measurement is that 36 of the
# last 60 push runs on `main` were already cancelled that way, at a merge
# cadence that would censor most hours.
#
# ⛔ Do not "simplify" this back to two segments. `scripts/ci/scheduled-full-
# run.mjs --check-concurrency` evaluates this expression against a push-shaped
# and a schedule-shaped context and reds when the two groups are equal, so the
# collision cannot come back silently.
#
# `cancel-in-progress` stays `true` for every event including `schedule`: two
# hourly runs overlapping means one of them is over an hour old, and an 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 six 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.ref }}
  cancel-in-progress: true

jobs:
  filter:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      pull-requests: read
    outputs:
      # On merge_group — and on the `schedule` / `workflow_dispatch` full runs
      # (#16467) — everything counts as changed: dorny/paths-filter resolves a
      # diff only on `pull_request` and `push`, and each of these three events
      # is a place a skipped job can never be the right answer (the queue build
      # is the last validation before main; the hourly run IS the full battery).
      # A skipped step's output is the empty string (falsy), so `|| 'true'`
      # supplies their value without touching PR/push behavior.
      docs: ${{ steps.changes.outputs.docs || 'true' }}
      core: ${{ steps.changes.outputs.core || 'true' }}
      console: ${{ steps.changes.outputs.console || 'true' }}
      # Gates the `test` job ONLY, ORed with `core` — see the `crosspkg`
      # filter below and the `test` job's `if:` (#9829, #10015).
      crosspkg: ${{ steps.changes.outputs.crosspkg || '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

      # ⭐ SPELLED AS AN ALLOW-LIST, not as `!= 'merge_group'` (#16467). This
      # action reads a diff, and the only two events that hand it one it can
      # resolve unaided are `pull_request` (base vs head) and `push`
      # (`event.before` vs `after`). `merge_group` was the first event with
      # neither, and the exclusion was written as its name; `schedule` and
      # `workflow_dispatch` are the second and third, and under the old
      # spelling they would have 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
      # hourly 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.
      - uses: dorny/paths-filter@v4
        id: changes
        if: github.event_name == 'pull_request' || github.event_name == 'push'
        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'
              - '.github/workflows/ci.yml'
            # Build inputs of the vendored Console SPA — see the Console Pin Gate
            # job at the bottom of this file. `.objectui-sha` is a ROOT DOTFILE, so
            # it matches neither filter above: a pin-only diff skipped `core` and
            # `docs` alike, which is how #4288 moved the pin 76 commits with six of
            # fourteen checks skipped and nothing anywhere building the new SHA.
            # The last two entries are the "a change to the guard runs the guard"
            # rule the repo applies to every other filtered gate; they are close to
            # free here because an unmoved pin hits the dist cache.
            console:
              - '.objectui-sha'
              - 'scripts/build-console.sh'
              - 'scripts/check-console-sha.mjs'
              - 'scripts/check-console-injection.mjs'
              - 'scripts/console-spec-probes.mjs'
              - 'scripts/assert-console-spec-injection.mjs'
              - '.github/workflows/ci.yml'
            # 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/**'

  test:
    # Sharded 6-way BY PACKAGE: 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 six
    # 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 SIX AND NOT 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.
    #
    # SIX specifically, and not four or five: sharding is BY PACKAGE, so no
    # shard can finish faster than its single heaviest package.
    # `@objectstack/spec` is that package — at five shards or fewer the
    # partitioner must co-schedule it with others, and at six it very nearly
    # fills a bin on its own. Six is therefore the smallest count that
    # isolates the heaviest indivisible suite; past six, spec's shard cannot
    # improve, only the others can.
    #
    # ⚠ 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. The conclusion (six) survived the re-
    # measurement; only the units it is argued in changed. Weights now come
    # from scripts/test-shard-timings.json — see partition-test-shards.mjs.
    #
    # AND WHY NOT MORE THAN SIX, measured on that dataset (#10472 asked for
    # 6 -> 8 to be considered). The floor is the heaviest single package, and
    # it does not move when shards are added, while the mean falls with every
    # shard — so max/mean, which is what the acceptance bound is written in,
    # gets WORSE past the point where the floor becomes the max:
    #
    #   6 shards -> max 650s  mean 649s  ratio 1.00x
    #   7 shards -> max 571s  mean 556s  ratio 1.03x
    #   8 shards -> max 571s  mean 487s  ratio 1.17x
    #  10 shards -> max 571s  mean 389s  ratio 1.46x
    #
    # Eight shards would buy ~79s off the critical path for two more runners'
    # fixed overhead and a worse balance ratio. The partitioner's self-test
    # pins this arithmetic so the next person gets the answer from a failing
    # assertion rather than from a CI run.
    #
    # ⚠ THE COST, stated because it is real: per-shard fixed overhead
    # (checkout + pnpm/Turbo cache restore + install, ~60s measured on run
    # 32392712980) is paid once PER SHARD, and the merge queue multiplies it
    # by the speculative build count. Six shards trade roughly 1.7x the
    # billed runner-minutes for a shorter critical path. `--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 }}/6)
    needs: filter
    # "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).
    if: ${{ !cancelled() && (needs.filter.outputs.core != 'false' || needs.filter.outputs.crosspkg != 'false') }}
    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 is
    # ~5× a normal sharded run (~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.
    #
    # ⚠ TEMPORARY RAISE, 30 -> 45 (#16173). Shard 5/6 is being killed at the
    # 30-minute wall — 12+ observations at 30:16-30:21 with every other job in
    # every one of those runs green — so the paragraph above describes the
    # value this line must RETURN to, not the value it currently carries.
    #
    # Two reasons, both #16173's:
    #   1. Unblock. The only uncensored shard-5 readings are 25:32 and 27:36,
    #      and shard 6/6 has been seen at 28:56 — a ~1 minute margin at the top
    #      of the observed green band against a 30:00 wall.
    #   2. Un-censor. Every tail observation is a reading of THIS number, not
    #      of the shard: the true duration is >= 30:16, unbounded above. So the
    #      shard timings cannot be re-derived from CI history while the wall
    #      stands here. Raising it produces the durations #16173 needs before
    #      anyone touches `scripts/test-shard-timings.json`.
    #
    # ⛔ REVERT CONDITION, explicit: back to `30` once #16173 lands its shard
    # rebalance. This value is temporary and carries no other expiry — a raise
    # with no revert condition written beside it becomes permanent by
    # forgetting. The backstop stays loose only for that window; the stall
    # guard named above remains the primary hang detector throughout.
    timeout-minutes: 45
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5, 6]

    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 Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - 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: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # 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 }}-

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

      # 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 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 }}
        run: |
          bash scripts/ci/select-shard-packages.sh
          node scripts/partition-test-shards.mjs "$RUNNER_TEMP/turbo-ls.json" \
            --shard ${{ matrix.shard }}/6 --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"

      # ⛔ A FILE-LEVEL SLICE BUILDS ITS DEPENDENCY CLOSURE HERE, IN A RUN THAT
      # CARRIES NO PASSTHROUGH, so that the sharded run in the next step can be
      # `--only` (#16395).
      #
      # 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"` is the
      # whole reason a slice gets its own invocation at all (the next step's
      # comment says why it cannot ride the shared run). 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; 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"

      # --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: `--shard=k/n` is passed through to vitest by turbo as a
          # RUN-level argument, so it would reach every package in the run —
          # and on any package with fewer test files than n that is a hard
          # vitest failure (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.
          #
          # ⛔ A failing leg STOPS the remaining ones, the same way turbo stops
          # scheduling on the first failure inside one run. Carrying on would add
          # a second full suite to a job that is already red and already inside a
          # 30-minute wall — turning an informative red into a killed job with no
          # attestation at all, which is the #16173 failure mode itself.
          #
          # `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. The cli slice
          # leg stays `test`-only: cli is not split.
          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 --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"
              # `--only` (#16395): the step above already built this slice's
              # dependency closure in a passthrough-free run, so this run must
              # schedule the ONE task the passthrough is for. Without it turbo
              # re-hashes the whole `^build` closure under `--shard=k/n` and
              # rebuilds it -- that comment carries the measurement. ⚠ The build
              # step is load-bearing for this flag: a sliced package whose build
              # never ran fails LOUDLY here (its imports resolve to a missing
              # dist), never as a silent green.
              set -- pnpm turbo run test "--filter=$PKG" --only --concurrency=4 --summarize --log-order=stream -- "--shard=$SLICE"
            fi
            LOGS="$LOGS $LOG"
            node scripts/run-with-stall-guard.mjs --log "$LOG" --stall-minutes 10 \
              --report-dir "$RUNNER_TEMP/stall-reports" -- "$@" || { STATUS=$?; break; }
          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

      # --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 these six artifacts 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.
      - 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-6
          path: .turbo/runs/
          if-no-files-found: ignore
          retention-days: 1

      # ⛔ THE DRIFT STEP IS DELIBERATELY NOT WIRED HERE YET (#16173).
      #
      # partition-test-shards.mjs carries a fully-tested `--check-drift` mode —
      # it reads the summary uploaded above back and reds when a shard's MEASURED
      # test total outruns its PREDICTED one past MAX_MEASURED_OVER_PREDICTED. The
      # code, its self-tests and its ablation are all on this branch; only this
      # invocation waits, and the wait is a SEQUENCING decision, not an oversight.
      #
      # Why: scripts/test-shard-timings.json is still stale for @objectstack/cli
      # (458.15s recorded, 1231.52s measured), so wiring the step today would red
      # the shard carrying a CLI slice on every single PR — a true reading, but one
      # that blocks everything until the dataset is refreshed. The file-level split
      # above already removes the urgent hazard on its own, taking the worst shard
      # from ~1445s (80% of this job's 30-minute wall) to ~1059s (59%) with the
      # dataset untouched, because the CLI is halved across two runners instead of
      # falling on one.
      #
      # ⇒ The refresh and this step land TOGETHER in the follow-up, in that order.
      # The refresh recipe is in PR #16220's body. When it lands, restore a step
      # here that runs `--check-drift` over `.turbo/runs/*.json` with
      # `--label "Test Core (${{ matrix.shard }}/6)"`, with NO `if:` and NO
      # `continue-on-error` (the point is the red), placed ABOVE the attestation
      # pair for the #6082 reason documented on the upload above — so a drift red
      # also withholds the attestation, which is the fail-closed direction.

      # 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 the six 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
      #                30-minute 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` runs here because this is where CI names the script,
      # which is what check:self-test-wired requires. ⚠ Under
      # `continue-on-error` its verdict is VISIBLE but not enforcing: inside
      # this workflow, no step this card may add is permitted to fail anything.
      # Giving that self-test teeth means a `check:` step in lint.yml, which is
      # deliberately NOT taken here.
      - 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 --self-test
          node scripts/report-test-timings.mjs --capture \
            --log "$RUNNER_TEMP/test-core.log" \
            --summaries .turbo/runs \
            --shard "${{ matrix.shard }}/6" \
            --out "$RUNNER_TEMP/test-timings/shard-${{ matrix.shard }}.json"

      # 1 day, matching the run-summary upload above: this is an intermediate
      # the aggregator consumes minutes later in the SAME run. 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-6
          path: ${{ runner.temp }}/test-timings/
          if-no-files-found: ignore
          retention-days: 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

      # 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'
        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 6 \
            --out "$RUNNER_TEMP/shard-attestation"

      - name: Publish this shard's attestation
        uses: actions/upload-artifact@v7
        with:
          name: shard-attest-test-${{ matrix.shard }}-of-6
          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.
    name: Test Core
    needs: [test, filter]
    # ── 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. 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
    if: always()
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7

      # Same-run artifact download needs no permission beyond the `contents:
      # read` above (`actions: read` is for cross-run/cross-repo only), so this
      # gate's permission block is unchanged. 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 }}
        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/6:$OS_TEST_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.
      #
      # ⛔ 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


  # ── 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: the name IS the required check, so renaming
  # it would silently drop the gate wherever branch protection lists it — the
  # same trap the dogfood shards note below. `check:required-contexts` pins
  # this literal, parenthetical and all (#6865).
  temporal-conformance:
    name: Temporal Conformance (live PG + MySQL)
    needs: filter
    # See THE FILTER CONTRACT on the filter job's outputs (#4928).
    if: ${{ !cancelled() && needs.filter.outputs.core != 'false' }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read

    services:
      postgres:
        image: 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: 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 Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - 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: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # 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-

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

      - name: Build driver-sql and its dependencies
        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
        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
        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
        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

  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. Branch protection
    # requires only the bare "Dogfood Regression Gate" context, 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).
    if: ${{ !cancelled() && needs.filter.outputs.core != 'false' }}
    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 Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - 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: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # Shard-scoped key: the turbo test hash differs per shard (pass-through
      # args are 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 }}-

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

      # ⛔ THE DOGFOOD PACKAGE'S DEPENDENCY CLOSURE IS BUILT HERE, IN A RUN
      # THAT CARRIES NO PASSTHROUGH, so that the sharded run in the next step
      # can be `--only` (#16395's shape, applied to this job by #16886).
      #
      # 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/3` is the
      # whole reason each shard gets its own invocation at all (the next step's
      # comment says what those args are for). 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).
      - name: Build the dogfood package's dependency closure
        env:
          NODE_OPTIONS: --report-on-signal --report-signal=SIGUSR2 --report-directory=${{ runner.temp }}/stall-reports
        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

      # 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 `--` args reach the
      # package's `vitest run` and are hashed into the turbo task, so each
      # shard caches its test leg independently -- and under `--only` that is
      # the ONLY task the passthrough is hashed into; the build closure it used
      # to scatter is built once, shard-independently, by the step above.
      # 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"
          # `--only` (#16395's flag, #16886's site): the step above already
          # built this package's dependency closure in a passthrough-free run,
          # so this run must schedule the ONE task the passthrough is for.
          # Without it turbo re-hashes the whole `^build` closure under
          # `--shard=k/3` and rebuilds it, once per shard -- the step comment
          # above carries the measurement. ⚠ That build step is load-bearing
          # for this flag: with the closure unbuilt, this run fails LOUDLY
          # here (imports resolve to a missing dist), never as a silent green.
          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 --only --log-order=stream -- --shard=${{ 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).
    if: ${{ !cancelled() && needs.filter.outputs.core != 'false' }}
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read

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

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

      - 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: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # Restore-only, with no save step at all (the console-pin pattern): 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-

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

      # 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 required-check name for a SHARDED job (#3622 follow-up).
    #
    # Branch protection requires 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 — and since
    # #6865 the bare name is pinned by `check:required-contexts` rather than
    # only described here, so a rename fails in the ESLint job instead of in
    # the queue.
    #
    # Also aggregates dogfood-verify (the CLI pass that used to ride shard 1),
    # so the one required 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
    permissions:
      contents: 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 }}
        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 Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - 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: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # 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 }}-

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

      - name: Build packages (excluding docs)
        run: pnpm build

      # [#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

      # 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'
        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 Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - 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: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-
      
      - name: Setup Next.js cache
        uses: actions/cache@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') }}-

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

      # ── 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 step above: that
      # step stores `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 pinned objectui SHA actually builds (#4290) ───────────────────────
  #
  # `.objectui-sha` is the single source of truth for the vendored Console SPA:
  # release.yml reads it, clones objectstack-ai/objectui at that commit, builds
  # @object-ui/console, and copies the dist into packages/console/. Editing that
  # one line replaces the entire frontend the platform ships.
  #
  # Nothing on the PR side ever built it. The pin appeared in exactly two
  # workflows, neither of them a gate: release.yml (post-merge, on the main push)
  # and showcase-smoke.yml (manual + nightly, whose own header says "it never
  # gates PRs"). Combined with the filter hole noted above, #4288 merged a
  # 76-commit pin bump green with six of fourteen checks skipped. A SHA that
  # cannot build — a typo, a commit that was force-pushed away, a genuinely
  # broken objectui, a dead bundle canary — reached main unchallenged and would
  # have surfaced at PUBLISH time. The only thing standing between the two was
  # the author remembering to run scripts/build-console.sh locally: discipline,
  # not a gate.
  #
  # `pnpm objectui:refresh` does include the build, so the normal path was
  # already covered in practice; the hole is a hand-edited pin, or that single
  # line cherry-picked out of another branch.
  #
  # Cost is real but narrowly aimed. A moved pin is the only trigger that pays
  # the full clone + vite build, and #4288's 76 commits of staleness are the
  # measure of how rare that is. The other triggers (this file, the drift guard)
  # leave the pin untouched, so they hit the dist cache and cost about a minute.
  #
  # Scope, stated plainly: this proves the PINNED SHA builds. It does NOT cover a
  # packages/client change breaking the injected-client bundle — that input lives
  # under `packages/**`, and watching it here would rebuild the console on a large
  # fraction of every PR. release.yml stays the only check for that direction.
  #
  # ⚠️ This gate is ADVISORY, and its name is no longer pinned. It was enrolled
  # in `check:required-contexts` in #6865 on the strength of the 2026-08-09
  # ruling approving it for the required set; the live ruleset read of
  # 2026-08-18 (#9533) found it had never landed there, and the row was dropped
  # rather than left claiming otherwise — see that file's TOMBSTONE for the full
  # provenance. So a red here does NOT block a merge, and renaming this job no
  # longer turns anything red. The name is still load-bearing PROSE that renaming
  # this job silently falsifies — docs/releases-maintenance.md and
  # packages/console/README.md both describe the pin flow by this name (#9793
  # tracks the missing pin for job names that are not required contexts).
  #
  # ⚠️ It used to need telling apart from a same-shaped sibling, `Console Pin
  # Freshness`, which asked whether the pin was CURRENT. That gate is gone
  # (#10134, 2026-08-20 ruling: which objectui revision we pin is a decision
  # recorded in an objectstack issue, never derived from objectui `main`). This
  # gate's question is unaffected and it stays: does the PINNED SHA still BUILD.
  # ⛔ Do not read the sibling's deletion as licence to rebuild one under this
  # name — see scripts/check-required-contexts.mjs for why that name in
  # particular must stay out of any required set.
  console-pin:
    name: Console Pin Gate
    needs: filter
    # See THE FILTER CONTRACT on the filter job's outputs (#4928). `console`,
    # not `core` — each job keeps its own filter output.
    if: ${{ !cancelled() && needs.filter.outputs.console != 'false' }}
    runs-on: ubuntu-latest
    timeout-minutes: 45
    permissions:
      contents: read

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

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

      - 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: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # Restore-only, and with no save step at all: this job runs a handful of
      # times a month, so its own namespace would almost always be cold. The
      # build-core fallbacks below are the ones that actually hit — that job
      # builds a superset of the client closure needed here and is seeded from
      # main (same reasoning as the Temporal Conformance job's fallback).
      - 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-

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

      # build-console.sh bundles THIS tree's @objectstack/client into the console
      # (via OBJECTSTACK_CLIENT_DIST) and falls back to building it in place when
      # the dist is missing — but that fallback is a bare `pnpm build` inside
      # packages/client, which tsup cannot finish unless @objectstack/core and
      # @objectstack/spec are built already. Build the closure through turbo
      # instead: cacheable, and near-free off the restore above. Both of the
      # script's existing callers (release.yml, showcase-smoke.yml) pre-build for
      # the same reason.
      - name: Build @objectstack/client and its dependencies
        run: pnpm exec turbo run build --filter=@objectstack/client... --concurrency=4

      # Same key as release.yml's "Cache vendored Console dist" step. Actions
      # caches are repo-scoped, so a PR reads whatever main already built for this
      # pin — that is what makes the non-pin triggers cheap. Only a pin the repo
      # has never built misses, and a miss is exactly when this gate has work to do.
      #
      # Split restore/save where release.yml uses the combined action, because the
      # combined form's post-step saves even when the job FAILED. build-console.sh
      # writes the SHA stamp before it asserts the bundle canary, so a canary
      # failure leaves a stamped-but-broken dist on disk — cache that and the next
      # run restores it, skips the build, and sails through the stamp check. Saving
      # only once every assertion below is green is what lets a restored dist carry
      # the same guarantees as a freshly built one.
      - name: Restore vendored Console dist (keyed on the objectui pin)
        id: console-dist
        uses: actions/cache/restore@v6
        with:
          path: packages/console/dist
          key: ${{ runner.os }}-console-dist-${{ hashFiles('.objectui-sha', 'scripts/build-console.sh') }}

      # The gate. Shallow-clones objectui at the pinned SHA, builds
      # @object-ui/console against this tree's client, copies the dist into
      # packages/console/, and asserts the bundle canary — every failure mode a
      # bad pin can carry, surfaced on the PR instead of at publish time.
      - name: Build the Console SPA at the pinned objectui SHA
        if: steps.console-dist.outputs.cache-hit != 'true'
        run: bash scripts/build-console.sh

      # check:console-sha exits 0 — deliberately — when there is no dist at all
      # (published installs and package-only CI legitimately have none), and warns
      # without failing when a dist carries no stamp. Both are right for that
      # script and both are VACUOUS here, where producing a dist is the entire
      # point: an empty or partial cache restore would otherwise reach the drift
      # check with nothing to check and report success. Prove one is really in
      # place before letting that check speak for the job.
      - name: Assert a real Console dist is in place
        env:
          CACHE_HIT: ${{ steps.console-dist.outputs.cache-hit }}
        run: |
          dist=packages/console/dist
          if [ "$CACHE_HIT" = "true" ]; then origin="the dist cache restore"; else origin="scripts/build-console.sh"; fi
          fail=0
          [ -s "$dist/index.html" ] || { echo "::error::$dist/index.html is missing or empty"; fail=1; }
          [ -n "$(ls -A "$dist/assets" 2>/dev/null || true)" ] || { echo "::error::$dist/assets is missing or empty"; fail=1; }
          [ -s "$dist/.objectui-sha" ] || { echo "::error::$dist/.objectui-sha stamp is missing — check:console-sha would pass vacuously"; fail=1; }
          if [ "$fail" -ne 0 ]; then
            echo "::error::No usable Console dist after $origin."
            exit 1
          fi
          echo "✓ Console dist present ($(du -sk "$dist" | awk '{print $1}') KB, via $origin) from objectui@$(cut -c1-12 "$dist/.objectui-sha")"

      - name: Verify the Console dist stamp matches the pin
        run: pnpm check:console-sha

      # The spec-injection half of the same question, and the reason it is a
      # SEPARATE step from build-console.sh (#9667).
      #
      # The dist cache key is hashFiles('.objectui-sha', 'scripts/build-console.sh')
      # — packages/spec is deliberately NOT in it, because adding it would bust the
      # key on every spec change and force a ~20 min cold console rebuild on a repo
      # doing ~18 merges a day. The cost model stays; what does not stay is the
      # silence. scripts/assert-console-spec-injection.mjs runs INSIDE
      # build-console.sh, so the `if: cache-hit != 'true'` above skips it exactly
      # when the dist was NOT built here — which is the run that most needs asking.
      #
      # That script cannot simply be re-run on this path: it derives its stale
      # detector from the PUBLISHED @objectstack/spec in objectui's own lockfile,
      # and on a cache hit there is no objectui clone to read it from. So the build
      # stamps the probes it chose into dist/.objectstack-injection.json and this
      # step replays them against whatever is actually on disk — one node process,
      # no network, cheap enough to run on every PR (which is the whole point; a
      # gate too expensive to always run is a gate that gets skipped).
      #
      # --require-stamp because the vacuity that check:console-sha tolerates is
      # wrong here for the same reason the presence assert above exists: an
      # unstamped dist is one no build ever proved, including one saved by a run
      # that died before the assertion. release.yml uses the COMBINED cache action,
      # whose post-step saves even on failure, under this same repo-scoped key — so
      # a poisoned entry is reachable from here and must not pass quietly.
      - name: Verify the restored Console dist bundles this tree's spec
        env:
          CONSOLE_DIST_CACHE_KEY: ${{ runner.os }}-console-dist-${{ hashFiles('.objectui-sha', 'scripts/build-console.sh') }}
        run: pnpm check:console-injection --require-stamp

      # Reached only with every assertion above green (see the split-restore note).
      # This deviates from the workflow's restore-only-on-PRs policy on purpose:
      # that policy targets the ~5 turbo entries every push writes, whereas this
      # key moves only when the pin does. A pin-bump PR writes one entry, and the
      # rest of that PR's pushes reuse it instead of rebuilding the console again.
      - name: Save vendored Console dist
        if: steps.console-dist.outputs.cache-hit != 'true'
        uses: actions/cache/save@v6
        with:
          path: packages/console/dist
          key: ${{ runner.os }}-console-dist-${{ hashFiles('.objectui-sha', 'scripts/build-console.sh') }}