`Build Docs` is red on `main`: `fs` reaches the browser bundle via `@objectstack/spec` → `pg-connection-string`

[os-sales]

Filed by the domain:ui execution seat (session session_012u2pRjcqAYtoEjgr3wwhnK) after PR #5665 went red on a job its diff cannot reach. Not a defect in any one PR — recording it because it is red on main itself and now blocks merges.

The failure

apps/site's Next.js 16.3.1 / Turbopack production build fails:

./node_modules/.pnpm/pg-connection-string@2.14.0/node_modules/pg-connection-string/index.js:88:70
Error: Module not found: Can't resolve 'fs'

  87 |   // Only try to load fs if we expect to read from the disk
> 88 |   const fs = config.sslcert || config.sslkey || config.sslrootcert ? require('fs') : null

A Node builtin is being pulled into a client bundle. The import chain, identical in both the Client Component Browser and Client Component SSR traces:

pg-connection-string@2.14.0
  ← @objectstack/spec@17.1.0/dist/index.mjs
  ← @objectstack/formula@17.1.0/dist/index.mjs
  ← packages/core/dist/evaluator/fieldRules.js
  ← packages/components/dist/index.js
  ← apps/site/app/components/InteractiveDemo.tsx   [Client Component]
  ← content/docs/plugins/plugin-form.mdx.js  /  plugin-gantt.mdx.js
  ← apps/site/.source/server.ts → apps/site/lib/source.ts → apps/site/app/api/search/route.ts

@object-ui/site#build is the only failing task (28 successful, 29 total).

It is on main, not on a PR

Push-to-main CI runs, all failure:

head	time	merge of
9986f9114	2026-08-22T07:31Z	#5662
0e05aac68	02:26Z	#5658
26ff2d6ac	01:59Z	#5657
7e811687a	01:14Z	#5655

Run 32559808825 on 9986f9114 reports 2 failed jobs: Build Docs and Test (coverage). Its Build Docs log carries the identical trace above — same modules, same two MDX routes, same task tally. So this is one failure inherited, not four independent ones.

Why it went unnoticed for ~6 hours

The PR-level check kept passing while the push-level one failed. Build Docs was green on the PR runs for #5656 (01:45Z), #5659 (02:03Z) and #5662 (02:09Z) — all based on aa3b81062 or earlier — while the push runs on their own merge commits were already red.

PR #5665 is the first in this lane based after the breakage entered, and its PR-level Build Docs fails. So the gate does catch it; it simply cannot catch it until your base includes it. The breakage window is therefore: after aa3b81062, at or before 7e811687a.

Impact

Any PR whose base includes the breakage cannot go green on Build Docs and cannot be merged. #5665 is ACCEPTed on its merits and is held on this alone — its diff is three comments, two test docstrings, two content/docs/components/basic/*.mdx prose edits, a README and a changeset, none of which appears anywhere in the failing import chain, and none of which can change module resolution.

Not diagnosed here, deliberately

I have not established which change introduced it, and I am not guessing. Two candidates worth measuring first, in this order:

1. A dependency movement. The chain runs entirely through third-party pins (@objectstack/spec@17.1.0, @objectstack/formula@17.1.0, pg-connection-string@2.14.0). Pin @objectstack/* to 17.1.0 #5529 ("Pin @objectstack/* to 17.1.0") is open and touches exactly this surface. A lockfile change would explain why the failure is not attributable to any one PR's source diff.
2. A bundler-boundary change — anything that newly pulls packages/core's evaluator into packages/components' entry, or packages/components into InteractiveDemo.tsx's client graph. That would make it a real regression rather than a dependency surprise.

The distinguishing measurement is cheap: check out aa3b81062 and 7e811687a, run pnpm --filter @object-ui/site build on each, and bisect the window.

Filed unassigned — it is not this seat's to fix and it is not scoped to domain:ui.

[os-sales]

Correction from the filer: the Impact section above is too broad

I wrote "any PR whose base includes the breakage cannot go green on Build Docs". That is wrong, and the title said the same thing — I have narrowed the title to drop "blocking every PR based after it". The defect and the main evidence are unchanged; only the blast radius is.

The measurement that corrects it

PR #5669 is based on 9986f9114 — the same base as #5665, so it includes the breakage. Its Build Docs job 97004132812 reports success, 08:13:01→08:13:12: 11 seconds. The log ends:

No docs-related files changed. Skipping the steps below; this check still reports.

The job is path-filtered inside itself, at the step level, not at the job or workflow level (ci.yml, step Check for docs changes). On a pull_request event it runs git diff --name-only base.sha...head.sha -- 'apps/site/' 'content/', and every subsequent step carries if: steps.docs-changes.outputs.should_run == 'true'.

• Finish the ADR-0080 page-source styling retraction across the remaining 8 prose sites #5665 edits content/docs/components/basic/{div,span}.mdx → should_run=true → real site build → failure, 3m26s.
• plugin-calendar README: hold the calendar-view schema block to CalendarViewSchema #5669 touches only packages/plugin-calendar/README.md → should_run=false → success, 11s, nothing built.

Corrected impact

A PR whose base includes the breakage fails Build Docs only if its diff touches apps/site/** or content/**. Every other PR reports green on that check without building the site.

This also revises the "Why it went unnoticed" section above. I attributed #5656/#5659/#5662's green Build Docs to their bases predating the breakage. Their bases were older, but that was not the only reason and possibly not the operative one — #5669 shows the path filter alone is sufficient to report green on a poisoned base. Four PRs merging between 01:56Z and 07:31Z while main's own push runs were already red is not a race; it is the filter.

main's push runs are unfiltered in this respect (the same step returns should_run=true early on any non-pull_request event), which is why the failure is visible there and nowhere else.

A second reading, recorded as measurement + inference

That early return is worth stating in full, because it bears on whether the merge queue would have caught this:

if [ "${{ github.event_name }}" != 'pull_request' ]; then
  echo 'should_run=true' >> "$GITHUB_OUTPUT"
  echo 'Not a pull request: push is filtered at the trigger, and a merge_group build is the last validation before main. Building the site.'

So a queue build builds the site on every PR regardless of paths, and main's ci.yml does subscribe the queue — merge_group: types: [checks_requested], lines 50–51, verified against origin/main rather than a local checkout.

Measured: GET /actions/runs?event=merge_group returns total_count: 0 — for ci.yml, and again with no workflow filter, i.e. repo-wide. Control: the identical call with event=push on ci.yml returns total_count: 3944, so the event filter is functional and the zero is a real reading.

Inference, flagged as such: if no merge_group run has ever existed, that unconditional branch has never been exercised and the queue is validating neither this check nor any other — which is the precise hole ci.yml's own comment block says #3523 closed. I have not established why the subscription is present in the file yet produces no runs, and I am not guessing. The distinguishing measurement is the repository ruleset's merge-queue configuration — whether a queue is actually engaged for main and what its required-check set is — which I cannot read with this session's access. I am deliberately not filing a card on an inference; if someone with that access confirms it, it deserves its own, and it is a larger problem than this one.

---

Generated by Claude Code

[os-sales]

Follow-up: the "inference" in my last comment is an already-open finding — #4986

In the correction above I recorded the zero-merge_group-runs reading as measurement, flagged the conclusion drawn from it as inference, and said I would not file a card on an inference. That was the right call on the evidence I had, but the reason it was not worth filing turns out to be stronger: #4986 already covers it, is open, and has more than I did — including that the queue's required set was measured directly and does not contain the four test shards, Type Check, or Lint.

I found it on the dedupe search, before filing. Cross-referencing rather than restating.

Two things I have added to #4986 rather than here:

1. The condition is still true today — event=merge_group returns total_count: 0 repo-wide against a control of 3944 for event=push, and main's ci.yml does carry the merge_group subscription (lines 50–51).
2. A second, independent line of evidence: the enqueue→merge timings. plugin-calendar README: hold the calendar-view schema block to CalendarViewSchema #5669/Bind dashboard dateRange.defaultRange to the spec's DateRangeDefaultRange, and pin the preset label half #5670/ComponentInput: re-export the one declaration instead of restating it three times #5671/Lock banner titles every state that opens it; the ADR-0010 lock vocabulary is declared once #5672 each went from pull_request.enqueued to merged_at in 15–17 seconds, while the pull-request lane's run of that same workflow on those same commits took 5m49s–8m25s for Type Check alone and ~10 minutes for the test shards. A queue build that ran ci.yml cannot finish in fifteen seconds.

Why this matters for this card

It supplies the missing half of the "why did four merges carry this forward" question.

The PR-lane Build Docs is path-filtered inside the job, so a PR touching no docs path reports green in 11 s having built nothing. The queue copy is not path-filtered — the same step returns should_run=true early on any non-pull_request event, under the comment "a merge_group build is the last validation before main". A working queue build would have run a real site build on every one of those four PRs and caught this at the first merge.

So this breakage is a concrete cash-in of #4986, in the same shape as the 2026-08-07 incident ci.yml's own comments record — just quieter, because it landed on a job most PRs never really run.

The defect in this card is unchanged and still needs its own fix: the bisect window (after aa3b81062, at or before 7e811687a) and the two candidate causes stand.

---

Generated by Claude Code