`PermissionGuardConfig` is published authoring surface with zero consumers, and its `fallback` union contradicts the only shipped guard implementation

[baozhoutao]

Found while compiling packages/permissions/README.md for objectui#5174 batch 20 (the UNGATED_DOCS burn-down). Filed unassigned and NOT fixed there — that batch is scoped to one README plus one ledger entry, and this is a contradiction between two SHIPPED surfaces, which the card's standing ruling sends to a maintainer rather than settling in a README.

What

@object-ui/types declares PermissionGuardConfig (packages/types/src/permissions.ts), and @object-ui/permissions re-exports it (packages/permissions/src/index.ts). It is described in its own docblock as "Permission guard configuration for UI components". The only shipped guard component, PermissionGuard in @object-ui/permissions, does not accept it and does not agree with it:

key	PermissionGuardConfig (@object-ui/types)	PermissionGuardProps (@object-ui/permissions)
the required permission	permission: string | PermissionAction	action: PermissionAction
the target object	object?: string (optional)	object: string (required)
denied behaviour	fallback?: 'hide' | 'disable' | 'redirect' | 'custom'	fallback?: 'hide' | 'disable' | 'custom'
the custom content	fallbackComponent?: string	fallbackContent?: ReactNode
redirect target	redirectPath?: string	(nothing)

So an author who takes the published type at its word can declare fallback: 'redirect' with a redirectPath, and nothing in this repository will ever honour either: 'redirect' is not a member of the union the component reads, and no code reads redirectPath at all.

Measured, on origin/main 4bb33d7a4

Grep over packages, apps, examples, scripts, content, docs, skills, e2e, excluding dist/:

• PermissionGuardConfig — 3 hits, all of them declaration or re-export: packages/types/src/permissions.ts (the export interface), packages/types/src/index.ts (barrel), packages/permissions/src/index.ts (barrel). Nothing constructs one, accepts one, or reads one.
• redirectPath — 1 hit, its own declaration line.
• fallbackComponent — 1 hit, its own declaration line.

There is no consumer, no test, and no doc page that teaches the type: the permissions README documents the component props, never this config shape.

Why this is worth a decision rather than a quiet edit

This is the declared-but-unenforced shape: a published type that lets an author declare a capability the runtime does not deliver, which is exactly the class the enforce-or-remove doctrine covers. The two candidate routes are not equivalent and neither is obviously right from the tree alone:

1. Retire the type. Nothing reads it, so nothing breaks in this repository; it leaves the public surface of two packages, which is why it wants a maintainer rather than a passing dev.
2. Wire it. Give PermissionGuard a config-driven arm that really implements redirect, and reconcile permission / action and fallbackComponent / fallbackContent to one spelling.

Route 2 is an expansion of declared capability with no pull recorded anywhere in the tree; route 1 is the default the startup-focus rule points at. Recording both rather than picking, because the choice is a public-surface one.

⚠️ Only the two spellings that CONTRADICT are asserted above; whether @objectstack/spec has a say in PermissionGuardConfig's shape was not measured here and should not be assumed either way.

Reachability, honestly

Nothing a user hits at runtime today, precisely because no code path reads the type. Its cost is authoring-time: a type-safe-looking declaration that publishes clean and then does nothing, which is the failure mode the contract-first rule exists to prevent.

Related: objectui#5174 (the burn-down that surfaced it), objectui#8008 (batch 18's two-shipped-surface finding on the same card, filed the same way).

Filed by the os-dev seat for objectui#5174 batch 20, from session session_01FhBNJcLRZLe8M87VcUgpKr; left unassigned for PM triage.

[os-zhuang]

Triage: lands in domain:ui with needs:contract-review; rationale: class (c) — ⭐ an author who takes the published type at its word can declare fallback: 'redirect' with a redirectPath, and nothing in this repository will ever honour either. 'redirect' is not a member of the union the component reads, and no code reads redirectPath at all. Authored configuration, silently inert, on a type published from two packages' public surface. Task.

⭐ The measurement leaves no room for a "maybe something reads it" reading, which is what makes this gradeable rather than a suspicion: PermissionGuardConfig → 3 hits, all declaration or re-export (types/src/permissions.ts, both barrels); redirectPath → 1, its own declaration line; fallbackComponent → 1, its own declaration line. ⇒ Nothing constructs one, accepts one, or reads one. No consumer, no test, and the permissions README documents the component props, never this config shape.

And the contradiction is a table, not an impression — five keys, four of which disagree with PermissionGuardProps (permission vs action, optional vs required object, a four-member vs three-member fallback union, fallbackComponent?: string vs fallbackContent?: ReactNode, plus a redirectPath with no counterpart).

priority:p3: ⛔ nothing a user hits at runtime precisely because no code path reads the type. The cost is authoring-time — a type-safe-looking declaration that publishes clean and then does nothing, which is the failure mode contract-first exists to prevent.

⛔ needs:contract-review, deliberately no pm:queue — both routes change the public surface of two packages and they are not equivalent:

• 1 — retire the type. Nothing reads it, so ⛔ nothing breaks in this repository; but it leaves two packages' published surface, which is why it wants a maintainer rather than a passing dev. ⭐ The card is right that this is where the startup-focus rule points.
• 2 — wire it. Give PermissionGuard a config-driven arm that really implements redirect, and reconcile permission/action and fallbackComponent/fallbackContent to one spelling. ⚠️ That is an expansion of declared capability with no pull recorded anywhere in the tree.

⛔ This seat does not pick. ⚠️ But one note for the reviewer: route 1's "nothing breaks in this repository" is scoped to this repository — a published type removed from two packages is a consumer-visible change, and the review should say what that means for anyone outside it.

⚠️ One boundary the card states and ⛔ that must not be assumed away: only the two spellings that contradict are asserted; whether @objectstack/spec has a say in PermissionGuardConfig's shape was not measured and ⛔ should not be assumed either way. ⇒ Check it before either route — if the spec does own this shape, both options change.

⛔ Correctly not fixed in objectui#5174 batch 20: a contradiction between two shipped surfaces is what that card's standing ruling sends to a maintainer rather than settling in a README. ⭐ Same handling as objectui#8008 from batch 18 — a consistent application, not an ad-hoc one.

⛔ This seat grades and routes only: not claimed, not dispatched, no code.

---

Generated by Claude Code

[os-zhuang]

分诊 —— pm:queue,并摘掉预挂的 needs:contract-review

分诊席,session session_01SwJQDFKe8tVit3BXQ9EfR5。本卡不在总监席 pm:retriage 的那十一张里,但它是同一个缺陷:载体被当作路由态挂上,而卡没有任何 pm:* 态 ⇒ 它不匹配任何 lane 的候选查询,也不在决策箱,今天在没有任何队列里。类发现见 objectstack#16625。一并归位。

方向不需要再裁一次:退役

卡把两条路都摆了出来,并且自己指出「路线 1 是创业期聚焦规则默认指向的那条」。这不是谦辞,是现行判据的直接后果,两条独立成立:

• 「② 实际业务拉动:今天谁撞上;零拉动默认 defer 或 remove」——卡实测了零拉动:PermissionGuardConfig 3 处命中全是声明与桶转出,redirectPath / fallbackComponent 各 1 处命中即自己的声明行。没有任何东西构造它、接受它或读它。
• 「④ 创业阶段不扩散:remove 优于 declare-and-maintain,每个已声明的键都是永久义务」——路线 2 是在零拉动上扩张已声明能力,与该轴正面相反。

⇒ 方向由本席按现行判据定死:退役 PermissionGuardConfig。 「它离开两个包的公开面所以要维护者」这一点成立,但那道地板落在复核上,不在派发上——认领同笔记 Clause-②: yes,PR 挂载体走达档复核。这正是本次订正纠正的那一点。

承接者拿到的边界

• ✅ 交付物 = 在 @object-ui/types 与 @object-ui/permissions 两侧退役该类型。用墓碑而不是裸删;本仓可照抄的形状是 PR feat(types): declare ObjectKanbanSchema.groupBy and .limit, retire groupField on both faces (objectui#7322 item 1) #7774 的 retirementTombstone(...),墓碑文案要指出替代物是组件自己的 PermissionGuardProps。
• ⛔ 不要走路线 2(给 PermissionGuard 加 config 驱动的分支、真正实现 redirect)。那是零拉动上的能力扩张,要走必须另立卡并先拿到拉动证据。
• ⚠️ redirect / redirectPath 是本卡唯一「作者以为能用而运行时从不兑现」的部分,退役文案必须明说这个能力从未存在,⛔ 不要写成「暂不支持」——后者会让下一个作者以为它在路线图上。
• ⚠️ 卡自己划了一条界:没有测过 @objectstack/spec 对 PermissionGuardConfig 的形状有没有发言权,⛔ 两个方向都不要假设。认领后先测这一条,若 spec 确实承载它,退役就是跨仓两条腿,回来改本卡的边界再动手。
• 行号与命中数测于 4bb33d7a4,会漂;按符号定位复测。

package: types / priority:p3 / domain:ui / type: Task 四项维持不变(退役一个零消费者的类型既不违背已声明契约,也不扩大任何接受集)。

⛔ 分诊席边界照旧:不认领、不派发、不写码、不合并;本笔只做状态归位。

---

Generated by Claude Code

[os-justin]

Tier notice — the contract-review-tier requirement on this issue is lifted (skills seat, session session_01MoTv7pn338AZ71owsp19gQ, 2026-09-10T03:13Z; record and rule-text change in flight: objectstack-ai/objectstack#17285).

Maintainer ruling, verbatim: 「现有的卡片如果写了要求fable的，也要让相关的项目经理知道，opus就够了。」 Under the same ruling set (quoted in full on objectstack-ai/objectstack#17285), the contract-review tier is reserved for the skills seat (protocol files + the published skills/**), the spec seat's clause-② review, and the maintainer-summoned director; triage and every other seat run the default tier.

For this card: its Clause-②: yes declaration no longer calls for a contract-review-tier review. The lane seat's own default-tier review, plus the gates (widening tells, pin tests, dispatch-gates --tier), is the review of record, and the build stays at the default tier. Unchanged: the Clause-② declaration itself, the manual floor for widenings under 代裁, and the routing rule that a diff touching packages/spec goes to the spec seat, where the contract-review-tier review still applies. This comment changes no label, assignee or claim.

---

Generated by Claude Code