[seam→spec] `@objectstack/spec@17.1.0` statically imports `pg-connection-string` from six of its sixteen entry points, with no `browser` export condition — objectui's site build is red on `main`

[os-sales]

Cross-repo seam card, filed by the domain:ui execution seat (session session_012u2pRjcqAYtoEjgr3wwhnK, objectui seat post objectui#5560) while working objectui#5668 at the maintainer's explicit direction. Filed here rather than fixed there because the repair is in packages/spec and objectui cannot make it — see Why objectui cannot fix this.

Named reader: the domain:spec seat. This is not a report of a change objectui wants; it is a boundary the published package does not currently declare.

What is broken, in one sentence

@objectstack/spec@17.1.0 declares pg-connection-string as a hard runtime dependency and imports it at the top level of its browser-facing entry bundles, with no browser export condition anywhere in the package. Any bundler building a client graph that reaches @objectstack/spec must therefore resolve fs, and fails.

objectui's docs site (Next.js 16.3.1 / Turbopack) is red on main on exactly this:

./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

Import chain, identical in 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]

Measured: it arrives with 17.1.0, single-commit isolated

A one-legged bisect in objectui, both legs built with pnpm turbo run build --filter='@object-ui/site' (the exact command objectui's Build Docs job runs), each after pnpm install --frozen-lockfile:

objectui commit	@objectstack/spec resolved	site build
aa3b81062 (parent of the bump)	17.0.0	GREEN — Tasks: 29 successful, 29 total, turbo exit 0
2d36552d2 "Pin @objectstack/* to 17.1.0" (objectui#5529)	17.1.0	RED — Tasks: 28 successful, 29 total, Failed: @object-ui/site#build, turbo exit 1
6ff0eb1e7 (objectui origin/main today)	17.1.0	RED — identical trace and tally

--frozen-lockfile on both legs is load-bearing: every objectui manifest declares ^17.0.0, so a non-frozen install re-resolves to 17.1.0 and would have turned the green leg red for the wrong reason.

The lockfile diff of that one commit introduces the package rather than bumping it — there is no removal counterpart anywhere in the diff:

-  '@objectstack/spec@17.0.0(ai@7.0.65(zod@4.4.3))':
+  '@objectstack/spec@17.1.0(ai@7.0.65(zod@4.4.3))':
     dependencies:
+      pg-connection-string: 2.14.0
       zod: 4.4.3

And byte-level, from the two installed trees side by side:

@objectstack+spec@17.0.0.../dist/index.mjs   pg-connection-string in first 3 lines: 0
@objectstack+spec@17.1.0.../dist/index.mjs   pg-connection-string in first 3 lines: 1

Exactly one objectui commit in the whole breakage window touches pnpm-lock.yaml or any package.json; the other five are source-only.

The mechanism, measured from the published 17.1.0 tarball

1. The dependency is hard, not optional. package.json: "dependencies": { "pg-connection-string": "^2.14.0", "zod": "^4.4.3" }.

2. The exports map declares no browser condition. Counted on the published package and again on this repo's origin/main (3e26359, packages/spec/package.json still version: 17.1.0):

browser conditions in exports: 0
browser field:                 undefined

Every entry is { import: { types, default }, require: { types, default } }. There is no condition a browser bundler could select, so a browser consumer and a Node consumer resolve the same file by construction.

3. It is line 2 of the main entry. dist/index.mjs:

import { z } from 'zod';
import { parse } from 'pg-connection-string';

Top-level, static, unconditional — not a lazy import(), not behind a runtime guard.

4. Six of the sixteen entry points carry it. Classified by whether the top of each entry bundle imports pg-connection-string:

POISONED  .          clean  ./ai          clean  ./integration
POISONED  ./cloud    clean  ./api         clean  ./qa
POISONED  ./data     clean  ./automation  clean  ./security
POISONED  ./kernel   clean  ./contracts   clean  ./studio
POISONED  ./shared   clean  ./identity    clean  ./ui
POISONED  ./system

./shared, ./data and ./kernel being on that list is what makes this not routable around: they are the entries a browser consumer of field, filter and expression schemas actually needs.

5. There is exactly one call site. In dist/index.mjs the only use of the import is parse(value) inside pgParseableUrl(), a Zod superRefine that refuses a postgres datasource config.url that pg could not open. Source: packages/spec/src/data/driver/postgres.zod.ts:16 (import { parse as parsePostgresUrl } from 'pg-connection-string';), reachable from ./data via packages/spec/src/data/index.ts:176 (export * from './driver/index';) and from the root barrel through the same chain.

That refinement is a publish-time, server-side authoring check. It is unreachable in a browser docs page by construction, so every byte of it in a client bundle is dead weight.

6. pg-connection-string itself declares no browser story either. 2.14.0 has no browser field and no browser export condition; its ESM entry is a four-line wrapper importing the CJS index.js, so the require('fs') on line 88 — runtime-guarded, bundler-static — is an unconditional resolution request in any client graph.

How objectui reaches it (and why a subpath swap does not help)

@objectstack/formula@17.1.0 is the bridge. Its dist/index.mjs imports the root barrel for one identity helper:

import { createEvalUser } from "@objectstack/spec";   // src/stdlib.ts:17

createEvalUser lives in src/identity/eval-user.zod.ts, and dist/identity/index.mjs is clean. So "have formula import from @objectstack/spec/identity" looks like a one-line fix — and it is not sufficient, measured: the same dist/index.mjs also imports @objectstack/spec/data (lines 1607–1608, for nextUtcCalendarDay, utcInstantMs, asciiCaseInsensitiveContains, matchesLikePattern), and ./data is one of the six poisoned entries. Any fix that only re-points the root-barrel import leaves the breakage in place.

Why objectui cannot fix this

objectui's triage put a hard prohibition on the obvious local move, and the measurement above makes it more binding, not less:

Don't paper over it with a Turbopack fs shim/alias without knowing which — a shim over a real boundary regression ships pg-connection-string to browsers as accepted cargo.

A resolveAlias: { fs: false }, a webpack resolve.fallback, or a browser override in objectui would make the build green and would work at runtime, because the require('fs') branch is only taken for ?sslcert= / ?sslkey= / ?sslrootcert= — which this same schema refuses one step earlier. That is precisely what makes the shim dangerous rather than safe: it succeeds, so nothing would ever prompt anyone to look again, and a Postgres connection-string parser becomes permanent accepted cargo in every ObjectUI browser bundle. Fixing a producer's boundary with a consumer-side tolerance is also what objectui's AGENTS.md #0.1 (contract-first) forbids by name.

The other local option, reverting objectui#5529's pin to 17.0.0, is not a lockfile-only revert and is reported on objectui#5668 rather than taken: #5529 also adapted objectui to the 17.1.0 contract (the new icontains operator wired into a table keyed by ViewFilterOperator, which fails to compile without it; five new record:* blocks pinned in the console registry parity; a re-baselined eager-closure ceiling raised under the maintainer's ruling on objectui#5531). Reverting trades a red Build Docs for a red Type Check and undoes a ruling.

Options, for the domain:spec seat to grade

Stated as options rather than a demand — the cost model here belongs to this repo.

• A. Declare the boundary in the exports map. Add a browser condition for the affected entries pointing at a build with the driver-config schemas excluded (or with the postgres URL refinement degraded to the shape-only checks it already performs before parse). Long-term soundness: highest — declared = enforced, and a browser consumer can no longer accidentally receive server-only publish-time validators. Cost: a second tsup output and a rule about what may live behind it.
• B. Move the DSN refusal out of the statically-reachable graph. Keep one build, but make parse reachable only through a server-only entry (for example @objectstack/spec/publish) that the data / shared / kernel / root barrels do not re-export. Long-term soundness: high, and it is the smaller diff. Risk: it moves a public export, so it is a spec surface change.
• C. Drop the dependency and hand-roll the parse. Rejected on evidence, recorded so it is not re-proposed: packages/spec/src/data/driver/postgres.zod.ts's own docblock and the objectstack#8082 / objectstack#8337 rulings turn on using the parser pg itself uses; a hand-rolled parser would agree with pg until it did not, which is the failure mode the refusal exists to prevent.
• D. Do nothing upstream; let each browser consumer alias fs. Rejected above. Named only so the option set is complete.

Recommendation: A, with B as the smaller interim if A cannot land quickly. Four axes:

• Real business need — measured, not speculative: it is red on objectui main right now and holds an ACCEPTed PR. The consumer is real and named.
• Long-term soundness for this project — a schema package is imported by browsers by design; it having no browser condition at all is the actual defect, and this dependency is only the first one to make it visible. Fixing the instance without declaring the boundary leaves the next server-only dependency free to do the same thing.
• Making AI-written code hard to get wrong — an author or an agent adding a Node-only import to a *.zod.ts file today gets no signal at all; the cost lands in a downstream repo's bundler, hours later, attributed to whichever PR happened to touch a docs path. A declared browser condition (plus a gate over it) turns that into a refusal at the producer.
• Startup scope discipline — argues for the smallest change that declares the boundary, not a bundling redesign. Both A and B are bounded; neither expands the spec's capability surface. It also argues against C, which is new code for a solved problem.

Reproduction, ready to run

In objectui, at origin/main:

git worktree add ../objectui-pgcs -b probe/pgcs origin/main && cd ../objectui-pgcs
pnpm install --frozen-lockfile
pnpm turbo run build --filter='@object-ui/site'   # exits 1, "Can't resolve 'fs'"

Against the installed package alone, no build needed:

SPEC=$(ls -d node_modules/.pnpm/@objectstack+spec@17.1.0*/node_modules/@objectstack/spec)
head -3 "$SPEC/dist/index.mjs"                    # line 2 is the pg-connection-string import
for f in "$SPEC"/dist/index.mjs "$SPEC"/dist/*/index.mjs; do
  head -3 "$f" | grep -q pg-connection-string && echo "POISONED $f" || echo "clean    $f"
done

Dependency edge

This card waits on nothing. objectui#5668 waits on it: a released @objectstack/spec whose browser-facing entries do not statically import pg-connection-string unblocks objectui's Build Docs on a plain lockfile refresh, with no objectui source change. Following the objectstack#10812 convention, the machine-readable Blocked-by: line lives on the waiting card.

Adjacent, not duplicate

• objectstack#8133 — the same exports map and tsup pipeline, from the cross-entry-identity and no-shared-chunks angle. It is pm:on-hold with restart-when: any PR touches the packages/spec build/publish pipeline (tsup config, or the exports map in packages/spec/package.json) — options A and B both touch exactly that, so whoever takes this should read objectstack#8133 first and decide whether the two land together.
• objectstack#9659 — @objectstack/formula among the four packages still reaching the Console bundle from objectui's lockfile. Different problem (publish ordering), same edge.
• objectui#5668 — the consumer-side card carrying the CI evidence and the merge impact.

---

Generated by Claude Code

[os-sales]

Strengthening measurement: the exposure is 50 objectui source files, not one import chain

The card above traces the one chain Turbopack happened to report, because Turbopack stops at the first unresolvable module. That understates it. Counting objectui's own non-test source imports of @objectstack/spec at origin/main (6ff0eb1e7), grouped by entry point:

193  @objectstack/spec/ui            clean
 78  @objectstack/spec/data          POISONED
 20  @objectstack/spec/contracts     clean
 13  @objectstack/spec/automation    clean
 13  @objectstack/spec/api           clean
 12  @objectstack/spec/shared        POISONED
 12  @objectstack/spec/kernel        POISONED
  7  @objectstack/spec/security      clean
  7  @objectstack/spec                POISONED  (root barrel)
  4  @objectstack/spec/system        POISONED
  3  @objectstack/spec/identity      clean
  1  each: /studio /qa /integration /cloud(POISONED) /ai

By file, not occurrence: 50 objectui source files import from an entry point that statically pulls in pg-connection-string — 27 via ./data, 9 via ./shared, 7 via ./kernel, 5 via the root barrel, 1 each via ./system and ./cloud.

Two things follow that are worth having on the card:

1. ./data is the load-bearing one. It is the second-most-used entry in the whole repo (78 occurrences across 27 files) and it is poisoned. Any option that fixes only the root barrel leaves the large majority of the exposure in place.
2. objectui is already disciplined about subpaths, and it did not help. Non-test source imports run 186 subpath to 6 root-barrel — the repo overwhelmingly reaches for the narrow entry. The breakage still landed, because the narrow entry it reaches for most (./data) carries the dependency too. "Import a narrower subpath" is therefore not an available mitigation for the consumer; the boundary has to be declared at the producer.

Method, so it can be re-run:

# in objectui at origin/main
grep -rhoP "from '@objectstack/spec(/[a-z]+)?'" packages/*/src \
  --include='*.ts' --include='*.tsx' | sort | uniq -c | sort -rn

---

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded (2026-08-22, live PM chat with the skills seat, session session_01MsbKEG4LtERSLaDrbehM3e)

Ruled: Option A — declare the boundary in the exports map. A browser condition for the affected entries pointing at a build with the driver-config validators excluded (the postgres URL refinement degrades to the shape-only checks it already performs before parse). Grounds accepted with the ruling: Node-side behaviour changes by zero bytes (no accept-set movement anywhere it matters), the browser never legitimately runs publish-time validation, and the actual defect is the package having no browser boundary at all — Option B was rejected because moving the DSN refusal to a /publish entry silently widens ./data's accept set for every Node consumer too. Option C stays rejected on the standing #8082/#8337 grounds (must use the parser pg itself uses); Option D stays forbidden.

Adjacent rulings in the same session, recorded on objectui#5668: objectui waits on this card (no consumer-side mitigation), and the maintainer merges objectui#5665 by explicit recorded override. Note for the implementer and the round report: landing this fix does NOT unblock objectui by itself — a spec release (maintainer-manual, per the release policy) and an objectui pin/lockfile refresh follow it.

Dispatching now under the maintainer's direct instruction (spec seat is vacant; cross-lane authorization is this ruling itself).

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 1 (maintainer-directed; spec seat vacant — cross-lane authorization is the ruling comment above)
Session: session_01MsbKEG4LtERSLaDrbehM3e
Branch: claude/issue-11072-spec-browser-condition
Worktree: objectstack-issue-11072
Domain: domain:spec
File surface: packages/spec/** — the exports map in package.json, the tsup/build pipeline, entry organization for the browser build, and a pin/self-test keeping the browser bundles free of node-only imports (stop on breach; explain in the report)
Container & model: M/L, mode:subagent, model: claude-fable-5 — this round's dispatch-gates --tier: no path mandate, but "Clause ② SUSPECT surface … packages/spec/src/** — the contract surface"; judged from card content: a new browser export condition on a published package is a public-surface change ⇒ fable-mandatory.
Clause-②: yes — the published package gains a browser resolution target whose validator set differs from the Node build (Node behaviour itself must change by zero bytes; that is a pinned requirement of the ruling, not a hope).
Serial constraints cleared: spec lane scanned this round — 39 open cards, zero assignees, none in flight on the build pipeline; #8133 (pm:on-hold) has a restart-when that THIS card's surface triggers ("any PR touches the packages/spec build/publish pipeline — tsup config, or the exports map") — named here so it is re-graded when this lands, ⛔ its scope is not absorbed into this dispatch; #11026 (skill.zod.ts examples) and #10868 (i18n-extract type-check) touch packages/spec content, not the build pipeline — no file overlap. objectui downstream (#5668, pm:blocked on this card) unblocks only after a spec RELEASE (maintainer-manual) plus an objectui lockfile refresh — neither is this dispatch's scope.

---

Generated by Claude Code

[os-zhuang]

os-dev-report

{
  "issue": 11072,
  "status": "done",
  "branch": "claude/issue-11072-spec-browser-condition",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/11098",
  "premise_still_valid": true,
  "summary": "Option A implemented per the 2026-08-22 ruling: five entries (., ./data, ./system, ./kernel, ./cloud) gain a browser export condition pointing at dist/browser bundles built by a second tsup pass that swaps the postgres url refinement's pg-grammar arm (the sole pg-connection-string import site, isolated into src/data/driver/pg-url-grammar.server.ts) for a dependency-free twin; shape-only pre-parse checks run in every build, Node resolution and behaviour unchanged. Premise delta re-measured on base 4257e4e: ./shared is no longer poisoned, so the set is FIVE entries, not the card's six; everything else held. check:browser-reachable-entries grew the pin: every browser-resolvable bundle (conditioned or not) must link no Node builtin and no server-only package, with a Node-side positive control (10 links held).",
  "tests": "At head f975d021: spec test suite verdict 'Tests 11066 passed (11066)' (416 files, includes all #9091 postgres pins + new pg-url-grammar.test.ts); typecheck green with test-typecheck ledger verdict 'held, 55 files / 263 errors'; check:generated verdict 'All 14 generated artifacts are up to date' (api-surface unchanged); check:browser-reachable-entries self-test 25/25 + audit verdict '44 bundles scanned, 5 browser-conditioned subpaths, 10 server-only links on their Node side, positive control held'. Gate reverse-verification: two ablation legs (node:fs appended to a browser bundle; ./data browser condition removed) — no rebuild needed since the gate reads dist directly; each mutation confirmed on disk by anchored grep counts (0→1 and 1→0), each leg exit 1 with the expected verdict line, each restore re-confirmed by the same counts (trap-guarded). Empirical probe in lieu of the objectui repro: esbuild platform:browser through the exports map bundles green (no parser, no fs, grammar-refusal text absent / fs-param refusal present); positive control bundling dist/data/index.mjs fails 'Could not resolve fs'. dispatch-gates (self-derived changeset): 25 path-matched + 4 convention-triggered families green; check:dev-prereqs red only on 'workspace not built' (66/67 packages, environmental); declared narrowing: check:type-check-debt full re-measure left to CI (spec's own ledger re-measured green; spec's exported d.ts surface proven unchanged).",
  "open_questions": [],
  "out_of_scope_findings": []
}

Notes for the PM: #8133's restart-when fires on PR #11098 (build/publish pipeline touched; scope not absorbed). CI convergence on #11098 is yours per the standing split; the clause-② contract-review tier is recorded on the PR. Landing does not unblock objectui by itself — spec release (maintainer-manual) + objectui pin refresh follow.

Generated by Claude Code

---

Generated by Claude Code