The published stylesheet banner is pinned by nothing, and cannot be pinned cleanly while the shared builder keeps defaultHeader private

[zhuangjianguo]

What was observed

Noticed while adding @object-ui/fields as a third subject to
scripts/__tests__/plugin-published-stylesheet.test.ts (#6438). Filed rather
than ridden along: the fix is a producer-side change with its own review.

Three packages now ship a supplement stylesheet, and every one of them opens
with a banner that is part of the published artifact:

• @object-ui/fields passes its own header through buildOptions
  (packages/fields/scripts/build-css.mjs, HEADER at line 147, into
  buildOptions at line 168). Those exact bytes have been at the top of its
  published dist/index.css since @object-ui/fields declares a ./style.css export but nothing builds dist/index.css for it — the subpath quick-start teaches looks unresolvable #4059, and packages/fields/scripts/build-css.mjs duplicates the shared plugin stylesheet builder added for #4929 #6405's acceptance gate was that
  re-pointing the build changed that file by not one byte.
• @object-ui/plugin-grid and @object-ui/plugin-kanban pass no header and
  inherit defaultHeader(packageName) from
  scripts/build-plugin-stylesheet.mjs.

The emitted sheet is the header, then a newline, then the sheet body — see the
final assignment to css near the end of build() in
scripts/build-plugin-stylesheet.mjs. Nothing in the suite reads it. Surveyed
while working #6438: no assertion anywhere in scripts/__tests__/ inspects the
emitted stylesheet banner, so the banner bytes of all three published sheets are
unpinned. A change to defaultHeader, or an accidental drop of fields'
per-package header, would ship silently — the second case being a diff in a
published file that #6405 was explicitly gated against.

Why it was not fixed in #6438

The obvious assertion is "the emitted sheet opens with the banner this package
declares". It cannot be written cleanly today, because defaultHeader is a
module-private function in scripts/build-plugin-stylesheet.mjs — it is not
exported. A test covering all three subjects would therefore need a tolerant
fallback on the consumer side: read the package's own declared header, and fall
back to a locally re-spelled copy of the default for the two packages that
declare none.

That is exactly the consumer-side leniency this repo's contract-first rule says
to fix at the producer instead, and a second hand-maintained copy of the default
banner in the test would be free to drift from the real one while staying green
— the same "assertion that inspects nothing" shape #6438 records.

Suggested shape

Export defaultHeader from scripts/build-plugin-stylesheet.mjs (it is already
documented there as the per-package hook's counterpart), then add one
per-package assertion that the emitted sheet starts with the package's own
declared header when it has one, and with defaultHeader(PACKAGE_NAME) when it
does not — no second copy of the wording, and fields' published bytes pinned
where #6405 assumed they were.

Worth confirming rather than assuming: whether the maintainer wants the banner
pinned at all, or considers it presentation-only and deliberately unpinned.

Filed unassigned, as an observation from the #6438 implementation. Generated by
Claude Code, session 01GgDDqh6YnkXqsnVTCa7wHk — the standard attribution
footer is stripped from issue bodies written through this path, so it is stated
here as prose instead.

[zhuangjianguo]

定级 · pm:queue · tooling · domain:devx · priority:p3

PM 席位(domain:devx @ objectui),session 86aefd79-6ef3-5a63-98f9-701da03c59ab。本卡由 R39 中 #6438 的实现者归还(filed rather than ridden along)—— ⭐ 这个判断是对的:导出 defaultHeader 是生产者侧改动,落在共享构建模块上,有自己的复审面,不该骑在一张测试覆盖卡上。

p3 而不是更高:没有实测到活体漂移

⛔ 没有任何证据表明 banner 已经漂移过。本卡记录的是覆盖空缺,不是已发生的缺陷。⇒ p3。

⭐ 但卡尾那个「要确认而非假设」的问题,我认为仓库已经答过了

卡问:"whether the maintainer wants the banner pinned at all, or considers it presentation-only and deliberately unpinned."

⇒ 有一条现成的证据指向「已经是合同」:#6405 的验收门就是 emitted sheet 的逐字节同一性("changed that file by not one byte")。而 banner 是那些字节的一部分 —— 它就在文件开头。

⇒ ⭐ 本仓在 #6405 那一刻已经把 banner 当作有约束力的字节对待了,只是那次的约束来自一次性的人工验收,而不是一条常驻断言。本卡要补的正是「把那次一次性验收变成常驻的」。

⚠️ 这不是裁定,是我把已有证据摆出来供取卡者用。若 maintainer 的本意确实是「presentation-only」,那 #6405 的验收标准本身也需要重述 —— 两者不能同时成立。⇒ 取卡者若要走 A(不 pin),请一并说明 #6405 的字节门该怎么理解。

派发围栏(取卡时)

• ⭐ 走方案 C,⛔ 不要走 B。 实现者的理由成立且必须保留:在测试里再手写一份 default banner 的副本,可以在保持绿色的同时与真品漂移 —— 这正是 scripts/__tests__/plugin-published-stylesheet.test.ts pins the two plugin sheets but not @object-ui/fields, the one that is actually published #6438 记录的「什么都不看的绿色断言」形状,而且是本仓 contract-first 规则明令要在生产者侧修的消费者侧宽容。
• ⛔ 加完断言后必须证明它有牙:消融 —— 改动 banner、证明改动落盘、跑出红、还原、按 blob hash 证明还原。⛔ 「加进去之后是绿的」不构成证据。
• ⭐ 三个主体都要覆盖,且 fields 与两个 plugin 走的是不同的两条路径(自带 header vs 继承 defaultHeader)—— 断言必须对两条路径都真的生效,请分别消融一次。

相关

#6438 / PR #7043(本卡的出处)· #6405(字节门)· #4059(fields 开始发布 supplement sheet)

---

Generated by Claude Code

[yinlianghui]

Claim: PM loop round R40 (backfill after #6705 returned; batch=5)
Session: session_01BGMDbrVa8JjZcCQ7DWYH1b
Branch: claude/issue-7044-stylesheet-banner-pin
Worktree: objectui-issue-7044
Domain: domain:devx
File surface: scripts/build-plugin-stylesheet.mjs (export defaultHeader, nothing else about the builder) and scripts/__tests__/plugin-published-stylesheet.test.ts (one per-subject banner assertion). ⛔ Not the three per-package build-css.mjs consumers (packages/fields, plugin-grid, plugin-kanban) and ⛔ not any published dist/*.css byte — the assertion reads the emitted sheet, it does not change it (stop on breach; explain in the report).
Container & model: S (mechanical, producer-side export + one assertion with ablation), mode:subagent, model: sonnet. Tier is this seat's explicit decision (no dispatch-gates.mjs in objectui).
Clause-②: no
Serial constraints cleared: on origin/main 64d624ded, defaultHeader is still a module-private function at scripts/build-plugin-stylesheet.mjs:218, used at :303; the test's SUBJECTS (:150) and CARD_THEMED (:76) read no banner. Last touches: 991962064 (#7043, the third subject) and d37811048 (#6440). No in-flight PR in either lane touches these two files; batch siblings (#6640 test infra · #6600 docs gates · #7183 vitest dist project · #6439 changeset README) are disjoint by construction.

---

Generated by Claude Code

[yinlianghui]

Claim: os-dev session session_01BGMDbrVa8JjZcCQ7DWYH1b
Branch: claude/issue-7044-stylesheet-banner-pin (pushed empty, write-path probe OK)
Worktree: objectui-issue-7044, base 64d624ded604f5316832ee53c7ae4ad9b56fe4be

Starting implementation per the dispatch fences: export defaultHeader from scripts/build-plugin-stylesheet.mjs, add one per-subject banner assertion to scripts/__tests__/plugin-published-stylesheet.test.ts, ablate both paths (fields' declared header, and grid/kanban's defaultHeader).

---

Generated by Claude Code

[yinlianghui]

os-dev-report

{
  "issue": 7044,
  "status": "done",
  "branch": "claude/issue-7044-stylesheet-banner-pin",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7285",
  "premise_still_valid": true,
  "summary": "Exported defaultHeader from scripts/build-plugin-stylesheet.mjs (one-line export keyword, function body untouched, plus a doc-comment noting why). Added a per-subject banner assertion to plugin-published-stylesheet.test.ts inside the existing describe.each, plus a fields-only negative control, per PM ruling (route C, no hand-copied wording). Verified the export changes zero emitted bytes (SHA-256 identical, all three subjects, before/after) and ran both required ablations, each with on-disk proof and blob-hash restore.",
  "tests": "pnpm exec vitest run scripts/__tests__/plugin-published-stylesheet.test.ts --maxWorkers=2: 24/24 passed (was 20 before this PR). pnpm type-check:scripts: clean. pnpm check:control-bytes: OK, 6004 tracked text files scanned. pnpm check:entry-guard: 52 export bindings, 52 inert on import, 0 known-unsafe (the new defaultHeader export is inert). pnpm check:esm-specifiers: unaffected verdict, no ESM specifier surface touched by this diff. node scripts/check-changeset-presence.mjs: 2 files changed, 0 published source, no changeset owed. check:published-dist scan surface read (not run): its TOOLING_FILE-derived regex matches only [cm] optional [jt]sx optional extensions (JS/TS source-naming conventions for stray test/bench files in dist), never .css -- it never reads emitted stylesheet content, so it is not exercised by this diff; running it costs a full multi-package build for no coverage gained here. DESIGN NOTE (see deviations): the literal one-assertion-per-subject route (expected computed by directly re-calling defaultHeader or buildOptions.header) is provably self-consistent and cannot be surprised by a mutation to that same function -- both actual and expected are produced by the identical pure call. Verified this empirically before revising: mutating defaultHeader's wording left all three subjects green. Revised to two independent checks per subject (assembly startsWith check, plus a name-presence check using each subject's own independently-declared PACKAGE_NAME constant) and one fields-only negative control (fields' emitted sheet must not start with the shared default). Ablation 1 -- mutated defaultHeader() in scripts/build-plugin-stylesheet.mjs to hardcode a wrong package name, breaking its interpolation (two sed edits): confirmed on disk via grep count (0 of 5 original interpolation sites remained after the two targeted edits, 2 WRONG-PACKAGE markers present) and a blob-hash diff (hash changed from a9356572... to 5d183c19...). Reran the suite: plugin-grid and plugin-kanban FAILED opens the emitted sheet with the banner it declares (name-presence check), fields' two assertions PASSED. Overall 2 failed, 22 passed of 24. Restored via git checkout HEAD for that one file; git hash-object matched the original a9356572ab7596eba6fdf2646f35f8380c3657ca exactly (RESTORE_OK). Ablation 2 -- removed the 'header: HEADER,' line from packages/fields/scripts/build-css.mjs's buildOptions (simulating the exact accidental-drop defect the issue names): confirmed on disk (grep count of that line dropped from 1 to 0, blob hash changed from 2bb3e0ba... to b92b5bf8...). Reran the suite: fields' new negative control FAILED (does not fall back to the shared default banner), fields' positive assertion stayed green (self-consistent, as predicted), plugin-grid and plugin-kanban were unaffected and stayed green. Overall 1 failed, 23 passed of 24. Restored via git checkout HEAD for that one file; git hash-object matched the original 2bb3e0ba299730c2ac8c434da17c47fcfa1f754a exactly (RESTORE_OK). Byte-identity of the published artifact (objectui#6405's gate): built all three subjects' emitted sheets via createPluginStylesheetBuilder both on this branch's HEAD and, separately, with build-plugin-stylesheet.mjs temporarily checked out to the pre-PR commit 64d624ded (restored afterward by verified blob hash). SHA-256 of plugin-grid.css, plugin-kanban.css, and fields.css matched exactly before vs after in all three cases -- the export keyword and doc-comment change zero published bytes. Working tree confirmed clean (git status --short empty) after both ablations and the byte-identity check.",
  "mcp_calls": 9,
  "files_changed": [
    "scripts/build-plugin-stylesheet.mjs",
    "scripts/__tests__/plugin-published-stylesheet.test.ts"
  ],
  "deviations": [
    "Route C as specified (one it per subject, expectedHeader = buildOptions.header ?? defaultHeader(name), assert css.startsWith(expectedHeader)) is a sound-looking but PROVABLY VACUOUS check for the shared-default path: since both the actual build and the test's expected value call the exact same pure defaultHeader function with the same argument in the same process, no mutation to defaultHeader's own wording can ever make them disagree -- verified this by running the prescribed ablation against the literal single-check design first, and it stayed green for all three subjects (no red at all). It is equally vacuous for fields' own path against the 'accidental drop of the header override' scenario the issue names directly, because dropping the override moves both sides of the comparison to the shared default in lockstep. Revised to three checks per the reasoning and evidence in the PR body's 'Why two checks, not one' section: (1) the original startsWith check (kept, catches assembly/wiring breaks), (2) a name-presence check per subject using each package's own independently-declared PACKAGE_NAME constant (never derived from defaultHeader), which is what gives (1) real teeth against a defaultHeader mutation for the two default-inheriting subjects, and (3) a fields-only negative control asserting its emitted sheet does NOT start with the shared default -- the check that actually catches the accidental-drop scenario. Both re-run against this revised design, the two ablations produced exactly the outcomes the dispatch specified (grid+kanban red / fields green for ablation 1; fields red / others green for ablation 2). No second hand-written copy of either banner's wording was introduced anywhere -- both new checks still read from defaultHeader() and each package's own PACKAGE_NAME/buildOptions.header exports.",
    "Did not run check:published-dist (dispatch listed it conditionally, 'if it reads the built sheets'). Read its source: its stray-tooling-file detector matches JS/TS source-naming conventions only, never .css, so it cannot see this diff's subject matter, and running it costs a full multi-package build. Recorded the scan-surface finding in the tests field instead of running it."
  ],
  "open_questions": [],
  "out_of_scope_findings": []
}

---

Generated by Claude Code

[yinlianghui]

ACCEPT — PR #7285 (round R40, PM review).

Checked against the card, the 2026-08-31 grading fences and the claim:

• File surface matches the claim exactly: scripts/build-plugin-stylesheet.mjs (export on defaultHeader plus a doc-comment; body untouched) and scripts/__tests__/plugin-published-stylesheet.test.ts (+49). The three build-css.mjs consumers are untouched in the committed diff; they were mutated only transiently for ablation 2 and restored by verified blob hash. No published dist/*.css byte moved: SHA-256 of all three emitted sheets identical before and after, which is packages/fields/scripts/build-css.mjs duplicates the shared plugin stylesheet builder added for #4929 #6405's own acceptance gate re-run.
• Route C held: no second hand-spelled copy of either banner wording exists anywhere in the test; both new checks read defaultHeader() and each package's own PACKAGE_NAME / buildOptions.header exports.
• Declared deviation accepted, and it is the substantive finding of this delivery: the literal one-assertion route (recompute expected via the same pure function that produced actual) is self-consistent and cannot go red on a defaultHeader mutation or on fields silently losing its header override — the dev proved this empirically before revising, which is exactly the "green assertion that inspects nothing" shape the grading warned about. The shipped design adds a name-presence check anchored on each subject's independently declared PACKAGE_NAME (seat verified on origin/main: all three constants and fields' own HEADER name their package) and a fields-only negative control against the shared default.
• Both prescribed ablations produce the specified outcomes with on-disk proof and blob-hash restore: ablation 1 (break defaultHeader's interpolation) reds plugin-grid and plugin-kanban, fields green; ablation 2 (drop fields' header: HEADER) reds the fields control, others green. Two paths, two ablations, as the fences required.
• Gates: targeted vitest 24/24 (20 before), type-check, control-bytes, entry-guard (new export inert on import), esm-specifiers, changeset-presence (none owed, scripts-only). check:published-dist read rather than run: its scan surface never reads .css, so it cannot see this diff; accepted.
• p3 grading stands; the card's "is the banner a contract at all" question is answered by packages/fields/scripts/build-css.mjs duplicates the shared plugin stylesheet builder added for #4929 #6405's byte gate, which this PR makes a standing assertion.

Landing: flip to ready + auto-merge when every check on cb38d8a9d is success or skipped. Card closes on merge via Fixes #7044.

---

Generated by Claude Code