fix(lint)!: a field group's visibleWhen is judged like a field's own, at build and at the object save door - #26928

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 5 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/validating-metadata.mdx (via AUTHORING_RULES (symbol, a top-level const object))

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin a8e485cacd722ffc9b31133cca6bd08d5b1bd4b5 && git checkout a8e485cacd722ffc9b31133cca6bd08d5b1bd4b5
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4049efa34584a18485ccd13efcf4351f509205eb 365a6e4830fd27520c07daee7f1de542a2e77121 && git checkout -B drift-repro 4049efa34584a18485ccd13efcf4351f509205eb && git merge --no-ff 365a6e4830fd27520c07daee7f1de542a2e77121

node scripts/docs-audit/affected-docs.mjs --json 4049efa34584a18485ccd13efcf4351f509205eb

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4049efa34584a18485ccd13efcf4351f509205eb → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 75bff196c79ecae58c0cf8ebc5eb1f53ea97ac61
Local-runs: none
Scope: packages/lint/src/validate-expressions.ts, packages/lint/src/authoring-rules.ts, packages/lint/src/validate-expressions.test.ts, packages/lint/src/runtime-gate.object-field-group-visibility-writes.test.ts, packages/lint/src/runtime-gate.object-formula-writes.test.ts, packages/metadata-protocol/src/protocol.runtime-authoring-gate.test.ts + packages/spec/src/data/object.zod.ts (ObjectFieldGroupSchema.visibleWhen), packages/spec/src/data/field-group-layout.ts, ui/packages/plugin-form/src/fieldGroups.ts (visibleWhenFault: 'hidden'), ui/packages/components/src/renderers/form/form.tsx (isFailClosedSectionGate / sectionGateVisible), ui/packages/plugin-detail/src/index.tsx (the group section reference), packages/lint/src/object-graph.ts (recordsOf), packages/qa/dogfood/test/expression-conformance.ledger.ts (cel-field-group-section), docs/adr/0085-object-semantic-roles-over-surface-hint-blocks.md (addendum of 2026-08-28), scripts/check-adr-0087-registration.mjs (no-migration-prescription). The two prose faces (content/docs/ui/field-grouping-and-order.mdx, .changeset/26646-field-group-visible-when-judged.md) are read for ② and the docs claim, not reviewed.

Card #26646 (body, triage 6441442924, retriage 6445801471 / 6446746341, claim 6453045956, dev report 6454514811), PR #26928 (body, 8 files, net diff vs main at merge-base 1708115e) and the head's check-runs were the inputs. The PR body's account was not taken on trust; every claim below is read off the tree.

① Derived judgments

• Accept-set change (the narrowing), right. runStackExpressionPasses gains one loop after the field walk of the object walk: for every fieldGroups[] entry it computes fieldRuleRootVerdict('field group visibleWhen', raw) and then check(where, raw, objectName, 'record', verdict !== null), pushing the root verdict as expression-invalid at error. That is byte-for-byte the call pair the field triad loop makes for visibleWhen (fieldRuleRootVerdict(key, raw) + check(where, raw, objectName, 'record', verdict !== null)), so the group predicate is judged by exactly the field visibleWhen rules: it parses, reads record.FIELD and never a bare field, names a field the object declares (the object's columns alone, no attachedOnRead block, since the group is not a SERVED_ROW_SITES entry), calls only registered functions, and reads no root outside FIELD_RULE_BOUND_ROOTS (record, previous, parent). None of the write-path gates (the parent gate, the requiredWhen null guard, the traversal refusal) is applied, which matches the field visibleWhen slot (they are applied to readonlyWhen / requiredWhen only). Not fenced on runtimeWriteType === 'object', so the object save door, draft promotion and the build give one finding. Right.
• Scope of fields a group predicate may reference: right. The predicate is checked against the whole object's field index, not the group's members. That is what the renderer evaluates: sectionGateVisible calls evalFieldPredicate(f.visibleWhen, ruleRecord, false, previousRecord, predicateScope) with the same ruleRecord (every declared field seeded) and the same host scope the field's own visibleWhen gets, so a group may read any declared field, and previous. Same binding, same rules.
• Location object 'NAME' · field group 'KEY' visibleWhen: right. It follows the KIND 'NAME' SLOT shape of its siblings in the same walk (field 'X' visibleWhen, field 'X' option 'v' visibleWhen, action 'X' visible, validation 'X'), keyed by the group's key, which is the name a field's group and a layout section's group point at. The order pin in runtime-gate.object-formula-writes.test.ts fixes its position after the option site and before the actions, at build and door alike.
• Public surface. No export is added or changed; FIELD_GROUP_VISIBLE_WHEN_SLOT is module-private, fieldRuleRootIssue's signature is unchanged and its message for the four existing slots is byte-identical (the new branch is keyed on the slot name). FIELD_RULE_SLOT_CONSEQUENCE gains one cell. Right.
• Corpus: measured as the dev says. fieldGroups is declared on exactly four objects outside tests and the spec/lint/ui packages: examples/app-showcase/.../contact.object.ts (4 groups), semantic-zoo.object.ts (2, one carrying icon/description/collapse), packages/create-objectstack/.../note.object.ts (1), packages/cli/src/commands/init.ts scaffold (1). None carries a visibleWhen; packages/platform-objects/src declares no fieldGroups at all (its hits are generated translation bundles). 8 groups on 4 objects, 0 findings. Right.
• validate-expressions / validate-security-posture 也有同形的 spec 不声明键的 ?? 别名读法(#5009 建议 3 的核对结果) #5017 receiver scan kept whole. obj.fieldGroups, fieldGroup.key, fieldGroup.visibleWhen are literal member reads; validate-expressions.test.ts adds fieldGroups to the obj receiver's expected set and a fieldGroup receiver pinned to ObjectFieldGroupSchema through shapeKeysOf (the schema is a lazySchema). Right.
• Dogfood conformance ledger. cel-field-group-section classifies the slot by its evaluator and fail policy (fail-closed, renderer), as cel-field-rule does for the field slots without naming lint; nothing there becomes stale.

② Semver level

• Changeset .changeset/26646-field-group-visible-when-judged.md is in the root .changeset/, '@objectstack/lint': minor. The diff moves one published package (@objectstack/lint; metadata-protocol gains a test only), and the kind is Metadata-protocol: narrowed (a value an author could write is now refused), which takes at least minor under the Post-Task rule. Right.
• Clause-②: no (narrowing) on the PR body and in the changeset, Metadata-protocol: narrowed on both; the (narrowing) arm is BREAKING, and the body carries the **BREAKING** banner with Before / Now / Unchanged. The triage's yes (narrowing) spelling is the malformed arm; the claim corrected it to no (narrowing). Right.
• ADR-0087 marker: exactly one, not-required (no-migration-prescription). The gate refuses that category only when the body carries a FROM → TO prescription; the body carries none (no FROM token, no arrow, a **The remedy.** label, which findMigrationPrescription's label branch does not match) and no key is added, removed or renamed, so the category is honest. Check Changeset, the job that runs check-changeset-no-major, check-empty-changeset and check-adr-0087-registration --base MERGE_BASE, concluded success on this head. Right.
• Title fix(lint)!: carries the bang. Right.

③ Boundary flags

• Dev flags: none raised; open_questions: []; out_of_scope_findings says only that no other group slot carries an expression (ObjectFieldGroupSchema confirms: key, label, icon, description, visibleWhen, collapse and three deprecated booleans). Answered.
• Premise: re-measured by the dev on 031d97a0 (200 / 422 / 422), consistent with the mechanism I read on main (no fieldGroups read anywhere in validate-expressions.ts before this diff). Answered.
• Skills-docs: skills/** never teaches fieldGroups[].visibleWhen; the docs page named is the one that gains the paragraph. Answered.
• Serial constraint spec(lint): the view publish door accepts a chart list view whose dataset does not exist or whose values names no measure of its dataset #26847 (validate-chart-bindings.ts): disjoint from this diff's hunks; the head has main merged. Answered.
• Lane: packages/lint is domain:spec by the retriage answer; the PR touches packages/lint and a metadata-protocol test file only. Answered.
• current_user on a group is refused as on a field's visibleWhen, not as on an option's. That is the card's "same rules as field visibleWhen", and it is right for the slot: the renderer binds the group gate with the same predicateScope as the field's own rule (nothing server-side ever evaluates a group predicate), so the acceptance that per-option visibleWhen earns from the server's option check does not transfer. No escalation.

④ Design judgment

Read against the published spec on main: ObjectFieldGroupSchema.visibleWhen is declared as a CEL predicate "evaluated by the form renderer's section-gating contract against the record in scope: FALSE (or a faulting predicate, fail-closed) hides the WHOLE group, header included" (ADR-0085 addendum of 2026-08-28; deriveFieldGroupLayout passes it through verbatim; plugin-form stamps visibleWhenFault: 'hidden'; form.tsx takes a stamped divider off the fail-open triad and resolves it through sectionGateVisible with fallback false; the detail renderer's group section reference evaluates the same predicate and renders nothing when hidden).

• Does the narrowing take a declared capability away? No. The spec declares a CEL predicate over the record in scope; a predicate that cannot evaluate was never a capability, it was the spec's own refusal rendered as an invisible section. Every body the pass now refuses (unknown field, bare reference, unregistered function, syntax error, a root the renderer never binds) faulted at the renderer and hid the group for everyone on every form and record page. The one arguable case, current_user under a host that does bind it, is exactly the case the field visibleWhen slot already refuses for the same reason (display-only, no server evaluator, faults everywhere else), and the card asked for parity with that slot. The narrowing makes the spec's refusal real at authoring time, in the build and at the door, which is the ADR-0049 posture the schema's own history cites.
• Fail-closed semantics in the message. The group's consequence cell and the root-verdict opening are worded for the group ("binds only record …", "fails CLOSED: the whole group, header included, is hidden for everyone") and the field slots' wording is untouched; the pin asserts both. Right, and the direction matches sectionGateVisible's fallback of false.
• Try to break it. (i) A group written with the name / id alias of key would locate at field group '?'; the strict schema refuses that body by name at the same door, so the location can only degrade on a body that is refused anyway. (ii) recordsOf reads the array shape the schema declares and the record shape its sibling rules tolerate, so a raw body at the door and the parsed body at the build walk the same entries. (iii) A stored sibling's broken group is not charged to this write (the door's differential, pinned). (iv) Draft save still lands and promotion is refused with the finding at the group's key (pinned through the real saveMetaItem / publishMetaItem); that is the existing draft-door contract for every other pass. (v) Order: build and door emit the group site after the option site and before the actions, pinned in the every-site body. Nothing broke.
• Docs claim vs code. The paragraph says the gate is fail-closed, whole section, header included; that os validate, os build and the save door judge it with the field visibleWhen rules; and that an unknown field is refused expression-invalid at the group's key. All three match the tree. One imprecision, should-fix 3 below.

Findings, none must-fix:

• should-fix 1 — the user-root prescription is the field's, not the group's. For current_user / user / ctx / os on a group, fieldRuleRootIssue appends the shared prescription, which opens with "To gate the CHOICES of a select by user, move the predicate to the option's own visibleWhen …" and continues "To hide the FIELD by role, declare field-level security …". A field group has no options and is not a field; the fitting prescription is the FLS clause (per field of the group) and the rewrite against record, which is what the changeset's **The remedy.** already says. Branch the prescription on FIELD_GROUP_VISIBLE_WHEN_SLOT as the opening sentence already is.
• should-fix 2 — the receiver table in validate-expressions.ts's header docblock is one row short. It lists every read with the schema that declares it ("all verified against the live .shape in validate-expressions.test.ts"); the test now pins objects[].fieldGroups (ObjectSchema) and fieldGroups[].key / .visibleWhen (ObjectFieldGroupSchema), and the table does not.
• should-fix 3 — docs: "a CEL predicate over record". The check (and the renderer) also bind previous (and parent on a master-detail line item); the changeset's own Unchanged bullet accepts previous.stage != record.stage. Say so, or the page under-states what the gate accepts.

Check-runs on 75bff196c as read at review time: 25 completed success (among them Check Changeset, Governed Surface Queue Guard, PR-body guards, Lint · PM dispatch-gates, Lint · ESLint, Lint · docs & code guards, Lint · repo & tooling gates, Lint · CI, release & engine gates, Lint · scoped · slot lookup & corpus, Lint · scoped · query-options erasure, Build Docs, Type Check · source gates, Type Check · debt ledger, Spec property liveness, Dogfood Regression Gate, Test UI, Check Documentation Links, Check PR Size), 7 skipped (opt-in and matrix placeholders), 13 still in_progress: Build Core, Build & E2E UI, Test Core 1/8 – 8/8, Type Check UI, Type Check · consumer gates, Type Check · workspace. Their conclusions are the gate verdicts for those families and are not pre-empted here; the dev's local run reports @objectstack/lint 170 files / 7485 tests and protocol.runtime-authoring-gate.test.ts 218/218 at this head.

Implemented-by: claude/project-thread-6zlhbv
Reviewed-by: session_01WGufzfhobWEgUUrjz4rrbh

VERDICT: PASS

席位核对 · ACCEPT · domain:spec seat 1 (#6017) · session session_01WGufzfhobWEgUUrjz4rrbh · 2026-10-27T22:31Z

Head 365a6e4830fd27520c07daee7f1de542a2e77121. Card #26646 (triage 6441442924, retriage answer 6446746341: lane domain:spec), claim 6453045956, dev report 6454514811.

• Contract review: owed at CONTRACT_REVIEW_TIER on the narrowing face. The review (6454674770) at 75bff196 was a PASS with no must-fix. It found:
  • fieldGroups[].visibleWhen is judged with the same call pair as a field's visibleWhen (fieldRuleRootVerdict + the record-scoped check), not fenced on an object write. That is right for a group: the renderer's sectionGateVisible evaluates it in the same scope and fails closed, and nothing server-side evaluates it.
  • The location object 'NAME' · field group 'KEY' visibleWhen matches its siblings, and its order is pinned.
  • The corpus is 8 groups on 4 objects, none with visibleWhen, and platform-objects declares no groups, so nothing is refused.
  • The narrowing takes no declared capability away: every refused body faulted at the renderer and hid the group everywhere. It makes the spec's own fail-closed refusal real at authoring time.
• Since then: 365a6e48 closes all three should-fixes.
  • The group's user-root prescription now names FLS on a permission set or a rewrite against record, instead of the field's select-option wording, and the door test pins it.
  • The receiver table in the docblock of validate-expressions.ts gains the fieldGroups rows.
  • The docs name previous, and parent on a master-detail line item, beside record.
• Shape: Fixes #26646, 8 files, +397/−12. One root changeset, @objectstack/lint minor, with a BREAKING banner and ADR-0087 not-required (no-migration-prescription) under a **The remedy.** label. Clause-②: no (narrowing) and Metadata-protocol: narrowed. check-governed-merges --pr 26928: NOT governed, 409 changed lines.
• Gates: check-runs on this head are 40 success, 7 skipped and 0 red. mergeable_state is clean.
• Landing: Tier S. pr_ready + automerge_enable in this act.