Sharing coverage gap: territory/team-shared accounts show quote, task and contract related lists the rep cannot read

[yinlianghui]

Split out of #488. The object-grant half was fixed in #547; this is the remaining record-level coverage question, kept separate because it needs a business decision, not just metadata.

The gap

sales_rep holds readScope: 'own' on crm_quote, crm_task and crm_contract (all private OWD), and no sharing rule exists for any of these objects. Meanwhile accounts do have widening rules (north_america_territory, europe_territory, account_team_sharing).

So a rep who receives an account through a territory rule opens it and finds:

• the Contacts related list populated (contacts are controlled_by_parent → follow the account),
• the Opportunities / Quotes / Contracts / Tasks related lists empty or partial — those objects stay own-only, and nothing derives or shares them alongside the account.

The page promises a 360° view of the shared account; record-level security delivers a keyhole. Same shape for service_agent: they read the account org-wide but see only their own cases/tasks on it.

Decision needed (per object)

Whose records should someone see on an account they can read but don't own?

Object	Option 1 — criteria sharing rule	Option 2 — OWD change	Option 3 — status quo
crm_quote	Share quotes whose account matches the territory rules (duplicates the territory criteria per child object; brittle)	controlled_by_parent on the opportunity or account — pricing follows the deal	Own-only is arguably correct for pricing
crm_contract	Share active contracts with the account's team	controlled_by_parent (account) — a contract is account data	Own-only hides renewals from the very team sharing the account
crm_task	Share open tasks by account territory	Keep private — tasks are personal by design	Probably fine as-is

Notes:

• Option 2 for quotes/contracts is the structurally honest fix (same reasoning that moved the line items in fix(security): grant the six objects that had no permissions at all (#488) #547), but it widens visibility for everyone, not just territory recipients — that's the business call.
• Option 1 keeps private but every account-sharing rule then needs a mirrored rule per child object, and the criteria drift apart over time.
• Whatever is chosen, crm_opportunity has the same question one level up (own-only + a single ≥$100k director rule), and Ownership model mismatch: app-authored owner lookups vs the platform's owner_id — reassigning Owner in the UI does not move record access #548 (owner vs owner_id) affects how "own" is evaluated everywhere here.

test/authorization-coverage.test.ts (added in #547) will keep whatever is decided consistent — e.g. if quotes go controlled_by_parent, the inert-scope and parent-resolution checks apply automatically.

[yinlianghui]

Re-verified against main (0437c9f) — the gap is still there

• crm_quote, crm_contract, crm_task: sharingModel: 'private', and objectstack.config.ts registers 9 sharing rules — 3 on crm_account, 2 on crm_opportunity, 2 on crm_case, 2 on crm_campaign. None on quote/contract/task.
• sales_rep holds readScope: 'own' on all three; service_agent holds it on crm_task and crm_case.
• So the account's related lists split exactly as reported: Contacts follow (controlled_by_parent), everything else is own-only except the ≥ $100k / critical-case leadership rules.

Two things worth adding before the decision, because they change what the options cost.

Option 1 is not authorable today without a schema change

The rule the issue sketches ("share quotes whose account matches the territory rules") has nothing to match on. The territory predicate is record.billing_address.country in [...] — billing_address is a structured address field on the account itself, not a traversal. A criteria rule on crm_quote is evaluated against the quote's own columns, and a quote carries no country, region or territory field. Whether the predicate compiler will dot-walk a lookup (record.crm_account.billing_address.country) is unproven in this app — nothing ships that shape, so it would need a platform check before anyone plans around it.

Assume it does not, and Option 1 costs: a denormalized territory/billing_country field on each child object, a hook keeping it in sync when the account moves territory or the child is reparented, and N mirrored rules that drift from the account rules over time. That is materially more expensive than the issue's "duplicates the criteria per child object; brittle" suggests.

Option 2 is available for quote and contract, and structurally impossible for task

Object	Parent for derivation	Option 2 viable?
crm_quote	crm_account — required: true, notNull	Yes
crm_contract	crm_account — required: true, notNull	Yes
crm_task	related_to_account / _contact / _opportunity / _lead / _case, all optional, selected by related_to_type	No — ADR-0055 derivation needs one master-detail or one required lookup. With none, the guard in test/authorization-coverage.test.ts fails and the layer denies every row. Making a parent required would break standalone tasks (a task tied to no record).

So the task row of the table really only has Option 1 (with the denormalization cost above) or Option 3.

What Option 2 actually widens

Read is the small half. On a controlled_by_parent object, write requires edit on the parent — and the territory rules grant edit on accounts, as does account_team_sharing for sales_manager.

• crm_contract — narrow blast radius. sales_rep holds allowCreate: false, allowEdit: false on contracts, so the object gate stops writes regardless of the derived row access. Effectively this is a read widening: anyone who can read the account reads its contracts. That matches the issue's "a contract is account data" reading, and it is the cheapest of the three to reason about.
• crm_quote — wider than it looks. sales_rep holds full CRUD on quotes, so every na_sales_team / eu_sales_team member would gain edit on quotes in their territory, not just read: pricing, discounts and internal_notes (readable+editable for reps under FLS today). crm_quote_line_item is itself controlled_by_parent(crm_quote), so this also creates a two-level derivation chain — also unverified in this app, and worth a platform check before committing.

Mechanical follow-ons either way: the readScope: 'own' on any object that goes controlled_by_parent must be deleted (the inert-scope guard from #547 fails otherwise), the OWD table and the new related-list table in content/docs/administration/sharing-and-security.mdx need updating, and the ledger in test/sharing-coverage.test.ts needs the new classification. And as the issue notes, #548 changes how "own" is evaluated underneath all of this.

Cost summary

	Option 1 — criteria rule	Option 2 — controlled_by_parent	Option 3 — status quo
crm_quote	Needs a denormalized territory field + sync hook + a mirrored rule per account rule	Read and edit widen to every territory/team member; two-level line-item derivation unverified	Pricing stays with the owner; the Quotes related list stays empty for territory recipients
crm_contract	Same denormalization cost	Read widens to anyone who reads the account; writes still blocked by the object gate for reps	Renewals stay hidden from the team that holds the account
crm_task	Same denormalization cost	Not available — no resolvable parent	Personal-by-design; probably fine, per the issue

Not deciding this — one observation

If the goal is the 360° view the account page implies, crm_contract gets closest for the least widening, crm_quote is the one that deserves an explicit "should territory peers edit each other's pricing?" answer before anything moves, and crm_task has no cheap path at all. That is a business call, not a metadata one, so it stays here.

What #584 does in the meantime

#584 fixes only the half that is unambiguously a defect — the docs described access the app does not ship:

• content/docs/revenue/contracts.mdx claimed "Contracts follow the account's sharing — if you can see the account, you can see its contracts". It does not, and never did.
• The security doc documented an account-team roster and a Team tab that this app has no object for; account_team_sharing is an ordinary criteria rule granting sales_manager edit on active customer accounts. The FAQ sent users to ask for a seat on that non-existent team.
• Profile comments claimed reps get cross-team visibility "through the account team / territory sharing rules" — true for accounts and contacts, false for quotes, contracts and tasks.

No OWD, permission set or sharing rule changed. New guards in test/sharing-coverage.test.ts pin the shipped reach per account child and hold the docs to it, so whichever option is chosen has to update the ledger and the prose together.

Two unrelated defects surfaced while reading the docs and are left for their own issues: the Competitor object documented in the OWD table and in profiles.mdx does not exist (competitors are a picklist on crm_opportunity), and ~38 lines across ~13 doc pages still describe role-hierarchy roll-up that ADR-0090 D3 removed.

---

Generated by Claude Code

[os-zhuang]

Decision, per object (the maintainer delegated this call on 2026-08-02; recording it here for implementers):

Object	Decision	Rationale
crm_contract	Option 2 — controlled_by_parent under the account (convert the already-required: true account lookup to masterDetail)	A contract is account data; hiding renewals from the very team the account is shared with defeats the point of territory/team sharing. crm_account is already required on every contract (contract.object.ts:50), so no backfill is needed. Cascade-delete is acceptable: account_protection already blocks deleting customers with open opportunities — extend it to active contracts in the same PR.
crm_quote	Option 2 — controlled_by_parent under the account, same conversion (quote.object.ts:68 is already required: true)	Matches the contract decision and extends the #547 line-item reasoning one level up (the chain becomes quote_line_item → quote → account). Resolves the 360° keyhole this issue reports. Pricing confidentiality is better enforced by discount governance (ceiling + approval — being filed as a batch-2 issue) than by row hiding; a rep who can see the account may see what was quoted on it.
crm_task	Option 3 — status quo (private)	Tasks are personal work items. The legitimate "what's happening on this account" need is an activity timeline need, met by the batch-2 activity-model issue — not by sharing to-do lists.
crm_opportunity (the "one level up" question)	Explicitly deferred	Stays own-only + the ≥$100k director rule until a territory/team model exists; revisit then. We accept the partial pipeline keyhole for now rather than mirror territory criteria per child object (the brittleness this issue itself warns about).

Sequencing: land after #548 Option B, so "own" evaluation is already trustworthy when the OWD changes. Once quotes/contracts go controlled_by_parent, the readScope: 'own' grants on them become parent-derived — test/authorization-coverage.test.ts's inert-scope and parent-resolution checks apply automatically, as noted in the issue body.

---

Generated by Claude Code

[yinlianghui]

认领:PM 循环第 3 轮
会话:session_0194QUW67v7vyLToEd9NSeRM
分支:claude/hotcrm-bug-triage-ks55ze(维护者指定的统一开发分支)
Worktree:hotcrm-issue-549(基于分支当前 head,不基于 main)
文件面:src/objects/{quote,contract,account}.object.ts、objectstack.config.ts(共享规则注册)、src/profiles/、content/docs/administration/sharing-and-security.mdx、test/sharing-coverage.test.ts / test/authorization-coverage.test.ts。不触碰 src/flows/(#650 本轮持有)、src/actions/(#678 本轮持有)。

排序前提已满足:2026-08-02 的决议要求「land after #548 Option B,so "own" evaluation is already trustworthy when the OWD changes」—— #548 已落在本分支(提交 bd45dfbd),owner 列已不存在,一切 own 判定走平台 owner_id。必须基于分支当前 head 开工,quote/contract 两个对象刚被 #548 改写过。

实施依据为该决议评论的逐对象裁决(contract 与 quote 转 controlled_by_parent、task 维持 private、opportunity 明确推迟),含其中要求的 account_protection 扩展到活跃合同。

---

Generated by Claude Code

[yinlianghui]

⛔ 升级维护者拍板:2026-08-02 决议所依赖的前提已被实测证伪

PM 循环第 3 轮派发结果为 needs_decision,我认为这个升级是正确的,不予自行决断 —— 它同时触及产品语义与机密性边界,且推翻的正是那条已拍板决议的事实基础。dev 已按纪律停手:OWD / masterDetail 转换全部回退,分支上 crm_quote 与 crm_contract 仍是 private(已核验),只落了测量与守卫。

被证伪的是什么

决议选择 Option 2 的理由是「read widens to anyone who reads the account」。真实引擎上不是这样 —— 它 widen 到「anyone who reads the object」。

controlled_by_parent 的派生过滤器由 computeControlledByParentFilter 用 computeRlsFilter(master) 解析主记录集合,那只含租户层与 rowLevelSecurity 策略,且以 system 上下文执行;而 owner 作用域与 sys_record_share 授权住在另一个插件(plugin-sharing.buildReadFilter),它对非 private 对象直接返回 null —— 而 controlled_by_parent 映射为 public。本仓没有给 crm_account 写任何 RLS 策略,主记录集合因此是全部账户,派生过滤器什么也没过滤。

实测(真实 kernel:ObjectQL + plugin-security + plugin-sharing 跑本仓 objectstack.config.ts,rep 只被 north_america_territory 分到一个账户):

	现状	应用决议后
crm_account	acct_US(正确)	acct_US(不变)
crm_quote	无(即本 issue 的钥匙孔)	quote_US + quote_JP —— 全组织
crm_contract	无	contract_US + contract_JP —— 全组织
编辑 quote_JP(读不到其账户)	DENIED	ALLOWED

最后一行是关键:assertControlledByParentWrite 用同一个空过滤器校验主记录,而 sales_rep 持有 quote 的 allowEdit —— 所以 Option 2 不只是读放宽,任何 rep 可以改写任何报价(价格、折扣、internal_notes)。

顺带回答了正文里那个「两级派生链未经验证」的问题,方向与预设相反:不是会拒绝行,而是根本不做限制 —— 第一级就没有收窄,第二级没有可收窄的东西。

选项(dev 已逐条实测机制可行性,不是纸面推演)

	做法	代价
A	照决议原样落地 Option 2	报价与合同全组织可读,报价全组织可写;readScope/writeScope 变惰性(本仓 inert-scope 守卫会强制删除它们),手工共享被拒(SHARING_NOT_ENABLED);且会让安全文档比现在更不真实
A'	仅 contract	rep 对合同 allowCreate/allowEdit 均为 false,对象门禁仍挡写;净效果是合同金额、条款、特殊条款对所有持读权者可读。爆炸半径小于 A,概念问题相同
B	Option 1(子对象上的条件共享规则)—— 机制已实测可用(defineRule + 调和 + sys_record_share 正常发放行)	需要在 quote/contract 上加冗余的 territory 列 + 同步 hook(形状与 account.hook.ts 维护 billing_country 相同),每条账户规则镜像一条。精确:只有该 territory 的成员、只有其 territory,基线仍 private + own,写仍受 owner 门禁
C	推迟 OWD 决策,修生产者	保留已落地的测量;把 #694 / 上游 objectstack#5386 当作真正的缺陷;平台把主记录的归属与共享折进派生后再取 Option 2,届时转换是两行改动,且被钉住的测试会变红提醒你

我的建议:C(必要时以 B 兜底),不要落 A/A'

按本仓的两条评估轴:

① 项目长远合理性 —— 缺陷在生产者侧(ADR-0055 的 v1 派生范围)。A/A' 是消费端 workaround:它用「交出 OWD 本要声明的机密性边界」换来一个相关列表,违背 contract-first(Prime Directive #12)与 no-workarounds(#5)。C 把这个选项保留而不是花掉;平台修好后 Option 2 自然成立。B 是诚实的,但要付冗余列 + 规则漂移的代价 —— 而「镜像规则会随时间漂移」恰恰是本 issue 正文自己警告过的东西,所以只在业务确实等不了时才买。

② 防 AI 写元数据犯错 —— 这条指向更明确。A 之下,应用会声明 sharingModel: controlled_by_parent 加一批引擎永不施加的 readScope 授权:一段读起来像窄权限、实际零强制的元数据。这正是本仓反复付学费的陷阱(#488 的惰性 readScope、#621 未播种的规则)。B 的条件规则由真正读它的那一层强制、可被测量验证;C 则根本不新增任何声明。

若维护者仍选 A,请连带两件事一起做,否则会留下比现状更差的状态:安全文档明确改写为「报价/合同全组织可读」,并重新审视 sales_rep 对 crm_quote 的 allowEdit —— 实测的写路径同样是全组织。

本轮已落地的(与决策无关,先行入库)

test/parent-derived-reach.test.ts(5 条断言,~3s)把当前真实可达范围钉住,平台一旦收窄即变红 —— 那正是 Option 2 重新可行的信号;test/sharing-coverage.test.ts 的台账注释按实测更正。

衍生立单

• controlled_by_parent children are readable regardless of parent access — contacts and quote line items reach every holder of object read (measured) #694 —— 本仓侧:controlled_by_parent 子对象无视父记录访问权(今日影响 crm_contact、crm_quote_line_item、crm_opportunity_line_item、crm_event_attendee);并指出 quote_line_item.object.ts、sales-rep.profile.ts、sharing-and-security.mdx 三处当前正在说反话。
• objectstack#5386 —— 上游平台单(查重后无重复),含建议:要么把归属/共享折进派生,要么在发布期对「主记录访问依赖共享而非 RLS」的 controlled_by_parent 声明响亮报错,让静默不再是默认。
• The two opportunity leadership sharing rules materialise zero grants on the memory driver: their negated in compiles to a top-level $not mingo rejects #695(finding)—— opportunity_sales_sharing / opportunity_executive_sharing 在 driver-memory 上零发放(!(record.stage in [...]) 编译成顶层 $not,mingo 拒收),而启动日志仍报「reconciled: 9」。driver-sql 支持 $not,故 sqlite/postgres 实际部署相信不受影响;更值得记的是:test/sharing-seeding.test.ts 证明的是条件能编译,不是所配驱动能执行。

---

@yinlianghui 本单已置 needs-user-decision、退出派发队列,等你的裁定。在你回复前不会有任何 OWD 变更。

---

Generated by Claude Code