ci: gate migrate-ts real-Postgres on every push, not after publish

The migrate-ts PG suites ran only on the v* tag push. Tags are pushed AFTER
`bun publish`, so red arrived strictly after four immutable registries were
already updated — which is why the lane sat red for eight consecutive releases
(v0.20.11 through v0.21.1, repaired in #280) with nobody acting on it. The
same suites `describe.skip` silently without MIGRATE_TS_PG_URL, so local runs,
PR runs, and even conformance.yml's own migrate-ts step all looked green while
the real-engine half executed nowhere except post-publish.

ADR-0015 makes migrate-ts the project's only migrate engine, so this is the
only real-engine gate on migration correctness.

local-ci.yml's ts-slow lane now arms the suite from its EXISTING Postgres
sidecar — no new container, no hosted minutes (the job takes ~50s; the
"EXPENSIVE" label on integration-tests.yml belongs to the 5-port Testcontainers
matrix, not this). It is ordered before the docker integration step so a
container-readiness flake there cannot mask the migrate verdict.

A sentinel test makes the silent skip loud where it matters: a lane that
intends real PG sets MIGRATE_TS_PG_EXPECT=1 beside the URL, and the sentinel
fails if the URL ever stops being set. A workflow-level `test -n` check could
not do this — it inspects the workflow's env, not what the test process reads,
so a rename inside the tests is precisely the drift it would miss. The skip
stays the default for contributors without Postgres and for the deliberately
DB-free lanes.

The tag job is kept as the cold-environment release backstop (the self-hosted
runner is warm), with its comment rewritten so red there reads as a broken
release already live, not as noise. RELEASING.md gains a wait-for-local-ci-green
step before publish — the last gate that can precede the irreversible one.

Residual, stated plainly: red is now post-merge rather than pre-merge; a
publish cut minutes after a merge can still beat the verdict; a cold-only
failure still surfaces first on the tag; and if the self-hosted runner is down
nothing goes red at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KTGT5ksntpcJDZVJ5VyXHS

Author: dmealing

.github/workflows/conformance.yml

@@ -142,7 +142,8 @@ jobs:
           cd ../integration-tests && bun test test/validation-conformance.test.ts
           # migrate-ts — the sole cross-port schema-migration engine (ADR-0015).
           # Its unit + integrity suites need no DB; the PG integration tests
-          # (gated on MIGRATE_TS_PG_URL) self-skip here and run in integration-tests.yml.
+          # (gated on MIGRATE_TS_PG_URL) self-skip here and run in local-ci's ts-slow
+          # lane (every push to main) + integration-tests.yml (the v* tag backstop).
           cd ../migrate-ts && bun test
           # Doc-template + CLI suites: byte-identity template gate, embedded-template
           # gate, neutrality / collision guards, and the docs golden corpus +

.github/workflows/integration-tests.yml

@@ -116,8 +116,14 @@ jobs:
   # migrate-ts PG integration tests — the apply / lifecycle / rollback +
   # introspection suites that exercise REAL Postgres behavior (advisory locks,
   # multi-tenant ledger, down-migrations) that pg-mem cannot fake. They
-  # `describe.skip` unless MIGRATE_TS_PG_URL is set, so no workflow ran them
-  # until now. A `services: postgres` container supplies the URL.
+  # `describe.skip` unless MIGRATE_TS_PG_URL is set; a `services: postgres`
+  # container supplies the URL.
+  #
+  # The PRIMARY gate for these suites is local-ci.yml's ts-slow lane, on every push
+  # to main. This job is the cold-environment RELEASE BACKSTOP on the v* tag. Tags
+  # are pushed AFTER publish (docs/RELEASING.md), so red HERE means a broken release
+  # is already live on four immutable registries — treat it as an incident, never as
+  # noise. That inversion is exactly how this lane sat red for eight releases.
   migrate-ts-pg:
     runs-on: ubuntu-latest
     services:
@@ -150,4 +156,7 @@ jobs:
       - name: Run migrate-ts suite against real Postgres
         env:
           MIGRATE_TS_PG_URL: postgres://migrate:migrate@localhost:5432/migrate_test
+          # Arms the in-suite sentinel: if the URL above ever stops being set, the
+          # suite FAILS instead of silently skipping and reporting a green release gate.
+          MIGRATE_TS_PG_EXPECT: '1'
         run: cd server/typescript/packages/migrate-ts && bun test

.github/workflows/local-ci.yml

@@ -140,6 +140,16 @@ jobs:
           persist-credentials: false
       - env:
           METAOBJECTS_TEST_PG_URL: postgres://metaobjects:metaobjects@localhost:${{ job.services.postgres.ports['5432'] }}/metaobjects_test
+          # Arms migrate-ts's real-Postgres suites (apply / lifecycle / rollback /
+          # introspection) on every push to main. They previously ran ONLY on the v* tag
+          # push — strictly AFTER the immutable four-registry publish — and so sat red for
+          # eight straight releases (v0.20.11 … v0.21.1) with nobody looking. Reuses this
+          # job's existing sidecar; the suite is proven to coexist in one database in a
+          # serial run (the hosted tag job runs it against a single migrate_test DB).
+          MIGRATE_TS_PG_URL: postgres://metaobjects:metaobjects@localhost:${{ job.services.postgres.ports['5432'] }}/metaobjects_test
+          # Makes the in-suite sentinel FAIL if the URL above ever rots away (renamed
+          # variable, dropped sidecar) rather than describe.skip-ing in silence.
+          MIGRATE_TS_PG_EXPECT: '1'
         run: scripts/ci-local.sh --only ts-slow --strict-toolchains
 
   # Java FAST lane — java + kotlin conformance only (the quick correctness signal).

docs/RELEASING.md

@@ -198,6 +198,17 @@ A red run here has caught real cross-port divergence (view-DDL identifier quotin
 strategy mismatches) that the unit suites missed.
 
 ### 3. Promote to `latest`
+
+**Before `bun publish`: confirm the `local-ci` run for the release commit is green.**
+Its `ts-slow` lane now carries the real-Postgres migrate gate. Publishing is irreversible on
+all four registries, and the `v*` tag is pushed *after* `bun publish` — so the tag-triggered
+`integration-tests` run can never be the pre-publish gate. This is the last gate that can
+precede the irreversible step.
+
+```bash
+gh run list --workflow local-ci.yml --limit 1 --json headSha,conclusion
+```
+
 ```bash
 # bump the candidate set to the final <version>
 rm bun.lock && bun install

scripts/ci-local.sh

@@ -146,6 +146,14 @@ gate_ts_build_typecheck() { bun_install && bun run --filter '*' build && bun run
 # integration tests, but the typecheck already runs in ts-fast, so don't repeat it.
 gate_ts_build() { bun_install && bun run --filter '*' build; }
 
+# migrate-ts real-Postgres suites — apply / lifecycle / rollback / introspection against a
+# real engine. ADR-0015 makes migrate-ts the project's ONLY migrate engine, so this is the
+# ONLY real-engine gate on migration correctness. The CI ts-slow job supplies
+# MIGRATE_TS_PG_URL (its Postgres sidecar) plus MIGRATE_TS_PG_EXPECT=1, which arms an
+# in-suite sentinel that fails loudly if that URL ever stops being set. Without those env
+# vars (a local run with no Postgres) the PG describes self-skip exactly as before.
+gate_migrate_ts_pg() { bun_install && ( cd server/typescript/packages/migrate-ts && bun test ); }
+
 # ── conformance.yml — per-port conformance corpora (exact CI commands) ────────
 gate_conf_ts() {
   bun_install || return 1
@@ -345,6 +353,9 @@ else
     # runs (umbrella `ts` / local full), its build already produced it — only build
     # here when ts-slow runs in isolation (the CI ts-slow job).
     if want_any ts ts-slow && ! want_any ts ts-fast; then step_if bun "ts build (for integration)" gate_ts_build; fi
+    # Ordered BEFORE the docker integration step so a container-readiness flake there
+    # can never prevent the migrate verdict from being produced.
+    want_any ts ts-slow        && step_if bun "migrate-ts real-PG suite" gate_migrate_ts_pg
     want_any ts ts-slow        && run_integration_for ts     ts
     want_any java java-slow    && run_integration_for java   java kotlin
     want python                && run_integration_for python python

server/typescript/packages/migrate-ts/test/integration/pg-gate-sentinel.test.ts

@@ -0,0 +1,30 @@
+/**
+ * Loud-skip guard for the real-Postgres suites in this package.
+ *
+ * Every one of them (`apply-pg`, `lifecycle-pg`, `postgres-roundtrip`,
+ * `postgres-lenient-inet`, `pg-adopt-view-239`, …) `describe.skip`s when
+ * `MIGRATE_TS_PG_URL` is unset. That is correct for a contributor with no local
+ * Postgres — but in CI the same silence let the lane rot RED for eight consecutive
+ * releases (v0.20.11 … v0.21.1) while every other lane stayed green, because the only
+ * workflow that set the URL ran on the `v*` tag push, i.e. strictly AFTER the
+ * irreversible four-registry publish.
+ *
+ * A lane that INTENDS to run these suites sets `MIGRATE_TS_PG_EXPECT=1` alongside the
+ * URL. This test then fails loudly if the URL plumbing ever rots — a renamed variable,
+ * a dropped sidecar, an unpublished port — instead of the suites quietly skipping and
+ * the lane reporting success over zero real-engine coverage.
+ *
+ * A workflow-level `test -n "$MIGRATE_TS_PG_URL"` step cannot do this job: it checks the
+ * workflow's environment, not what the test process actually reads, so a rename inside
+ * the tests is exactly the drift it would miss. The URL-set-but-Postgres-broken arm needs
+ * no sentinel — those suites already fail loudly on connect.
+ */
+import { describe, expect, test } from "bun:test";
+
+describe("real-PG gate sentinel", () => {
+  test("MIGRATE_TS_PG_URL is set when the lane declares MIGRATE_TS_PG_EXPECT=1", () => {
+    if (process.env["MIGRATE_TS_PG_EXPECT"] === "1") {
+      expect(process.env["MIGRATE_TS_PG_URL"]).toBeTruthy();
+    }
+  });
+});