[finding] `controlled_by_parent` master selection is silently decided by FIELD DECLARATION ORDER when an object declares several required lookups — reordering fields moves a security boundary with no diagnostic

[hotlong]

Measured on @objectstack/* 17.2.0 against a real booted kernel (ObjectQL + plugin-security + plugin-sharing) driving the HotCRM app metadata. No decision requested — filing the measurement.

Summary

SecurityPlugin.resolveCbpRelation picks the master relation with this precedence:

const found = pick((f) => f?.type === "master_detail" && f?.required)
 ?? pick((f) => f?.type === "master_detail")
 ?? pick((f) => f?.type === "lookup" && f?.required);

pick is entries.find(...), so within each tier the winner is whichever candidate appears first in the field map — declaration order. When an object declares two or more required lookups (and no master_detail), that order is the only thing deciding which object the record-level security derives from. Nothing reports the ambiguity: not objectstack validate, not objectstack lint, not a boot warning.

The failure direction is the dangerous one. Moving a field up or down in a schema file is a review-invisible edit that reads as cosmetic, and it can silently repoint the security master.

Measurement

Fixture: two accounts (acct_US, acct_JP) owned by another user; a sales_rep who owns none of them and receives acct_US only through a territory sharing rule (sys_record_share, access_level: edit). Subject: HotCRM's crm_contract, which declares two required lookups — crm_account (declared first) and crm_contact — and no master_detail. crm_contract was set to controlled_by_parent for the measurement (an in-test stack override; nothing shipped).

crm_contact is itself controlled_by_parent under crm_account.

crm_contract field order	resolved master	rep reads crm_contract
crm_account first (as authored)	crm_account	contract_US, contract_mixed — correct, narrowed to the shared account
crm_contact first (same fields, order swapped, nothing else changed)	crm_contact	contract_JP, contract_US, contract_mixed — org-wide

contract_mixed is the discriminator row: crm_account: acct_US (readable) with crm_contact: contact_JP (not readable). contract_JP appearing in the second row is the whole finding — one reordering, and a record on an account the caller cannot see becomes readable.

Control, live in the same runs: crm_opportunity_line_item (controlled_by_parent under crm_opportunity, which stays private) reads [oli_own] in both configurations, and oli_JP reads 0 rows and refuses the write. So the flip tracks the resolved master, not the harness.

Same-run sanity: the sibling object crm_quote declares only ONE required lookup (crm_account; its crm_contact is optional and conditionally required), and its reach was identical in both runs — the order swap moved only the object that actually had two candidates.

Why the second row is org-wide rather than merely "wrong master"

On 17.2.0 the derivation does not compose across a chain, so a controlled_by_parent master resolves to no restriction and the child goes org-wide. That half is objectstack#11082, fixed by merged PR objectstack#11183 — the fix is present in this repo's main source and absent from every published version (17.2.0, the latest published, went out 2026-08-23T07:01:00Z, about seven hours before #11082 closed).

The ambiguity survives that fix. Once the chain composes, picking crm_contact instead of crm_account no longer leaks org-wide — it silently derives access from a different object, so contract_mixed would follow the primary contact's account rather than the contract's own account. Narrower, still not what the author declared, and still unreported. The two are independent defects; this one is about which master gets chosen, not what happens after it is chosen.

Prior art checked (not duplicates)

• objectstack#7503 (closed) — publish-time lint for controlled_by_parent with no relation to derive from. This is the opposite case: too many candidates, not zero.
• objectstack#9138 (closed) / objectstack#9139 (open) — force / lint required: true on a master_detail under controlled_by_parent. Adjacent, and lint: promote relationship/master-detail-required from warning to error, scoped to controlled_by_parent — ruled for the v18 boundary (Direction 1 of #8772) #9139's v18 direction would push authors toward an explicit master_detail, which would cover the lookup-tier case by construction. It does not address ambiguity within a tier (two master_detail fields pick by order the same way), and it is not landed.
• objectstack#11082 (closed) / objectstack#5386 (closed) — the composition and share-folding defects. Different question.

Suggested directions (not deciding)

1. Report the ambiguity at publish time — if more than one candidate sits in the winning tier, name them and refuse, in the spirit of Publish-time lint: sharingModel: controlled_by_parent with no master_detail relation is statically detectable and unreported #7503. Silence is the part that makes this expensive.
2. Let the author name the master explicitly — an authored key beats any precedence chain, and makes the security boundary greppable instead of positional.
3. At minimum, document that the tie-break is declaration order, so an author reordering fields knows what they are moving.

Reported by a HotCRM consumer: hotcrm#549's ruled conversion turns crm_contract into exactly this shape, so the app would inherit an order-dependent security master the day it lands.

[huangyiirene]

Triage — graded. bug · security · priority:p2 · pm:queue · domain:devx. The measurement holds at origin/main, and the fix is cheaper than the card assumes — direction ① already has a home, a precedent and a mirror discipline waiting for it.

Verified at origin/main, not only at 17.2.0

The card measured published 17.2.0. Re-checked against source, because a card whose mechanism was fixed in main would be a very different card:

• packages/plugins/plugin-security/src/security-plugin.ts:6058-6061 is byte-identical to the quoted chain — required master_detail, then any master_detail, then required lookup.
• pick at :6057 is entries.find(([, f]) => pred(f) && ref(f)). find, so within a tier the winner is the first entry in the field map. ✅ Declaration order is the tie-break, on main, today.
• The chain-composition fix (fix(plugin-security): compose controlled_by_parent across a chain (#11082) #11183) is present — controlled-by-parent-chain.test.ts carries the [#11082] header. So the card's own framing is right: composition landing does not touch this, and the two are independent defects.

⭐ That last point is what sets the priority. On main the wrong pick no longer goes org-wide; it derives from a different declared object — narrower than the 17.2.0 behaviour, still not what the author wrote, still silent. p2, not p1: the org-wide row in the card's table is #11082's severity, already fixed and awaiting release, not this card's.

⭐ Direction ① is nearly pre-built

packages/lint/src/validate-security-posture.ts:215 already holds a resolveCbpRelation whose own docblock declares it "A point-for-point mirror of resolveCbpRelation in packages/plugins/plugin-security/src/security-plugin.ts — the SAME three-step fallback, in the same order". Its only call site, :323, is if (owd === 'controlled_by_parent' && !resolveCbpRelation(obj)) — the zero-candidate direction, SECURITY_CBP_NO_RELATION, i.e. #7503.

So the card's "opposite case" reading is exactly right, and the consequence is that the too-many-candidates rule needs no new mirror, no new traversal and no new precedent about whether lint may speak to this — only a second finding off the entries the mirror already walks. The :315-322 comment even pre-argues the admissibility criterion ("a self-contained property of the object document — no per-permission-set nuance to adjudicate, no legitimate reading"), which the ambiguity case satisfies identically.

⚠️ Whoever takes this: the mirror has one deliberate divergence documented at :206-213 — it accepts only the reference spelling, where the runtime accepts reference_to / referenceTo too. Keep that divergence. Re-introducing the alias fallback restores the inert branch #5017 removed.

Scope — direction ① only, and the fence is mechanical

Dispatchable scope is direction ①, landing in packages/lint/src/validate-security-posture.ts: when more than one candidate sits in the winning tier, name them and refuse. That is one lane, one file, and no runtime behaviour changes.

⛔ Direction ② is not in scope and is not mine to rule. "Let the author name the master explicitly" is a new authorable key on a published contract and it moves a security boundary — two independent human-floor triggers. It needs a maintainer, not a dispatch. Do not fold it in opportunistically; if you believe ① cannot be done without it, ⛔ do not implement ②, stop and say so in the report with the specific obstruction.

⛔ Direction ③ is excluded, not rejected — documenting the tie-break is a docstring in security-plugin.ts, which is domain:services, a different lane. A one-line rider there is how a clean single-lane PR turns into a cross-lane one. File it separately if you want it.

Prior art — the card's own check re-confirmed

#9139 is open, as the card says. Its v18 direction would push authors toward an explicit master_detail and would cover the lookup tier by construction — but the card is right that it does not address ambiguity within a tier: two required master_detail fields pick by find order identically, and that stays true after #9139. So ① is not made redundant by it. ✅ Not a duplicate of #7503, #9138, #9139, #11082 or #5386.

hotcrm#549's ruled conversion is named as the consumer trigger. Recorded, not chased — the fix lands here regardless of that card's timing.

---

Generated by Claude Code

[claude]

Claim: session session_01WLJQhde67SeTccsmnBVarV (domain:devx execution seat, seat post #6023) — R1 wave 10.

• Branch: claude/issue-14747-lint-cbp-ambiguous-master
• Worktree: ../objectstack-14747 (dedicated per-task worktree, off origin/main 89a156af8)
• File surface: packages/lint/src/validate-security-posture.ts (a second finding off the existing resolveCbpRelation mirror: ambiguous winning tier), its test file, packages/lint/src/index.ts (export), a @objectstack/lint changeset. ⛔ packages/plugins/plugin-security/** (domain:services), ⛔ packages/spec/**, ⛔ direction ② (authorable master key — human floor), ⛔ direction ③ (runtime docstring — separate lane).
• Container & model: subagent lane (M, opus).
• Scope: direction ① only per triage 5518587775; the reference-only spelling divergence at :206-213 is kept.
• Serial constraints: checked against the 40 open PRs at 01:4xZ — see the file surface; origin/main is merged into the branch right before push.

---

Generated by Claude Code

[claude]

os-dev-report

{
 "issue": 14747,
 "status": "done",
 "branch": "claude/issue-14747-lint-cbp-ambiguous-master",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/14818",
 "premise_still_valid": true,
 "summary": "Direction (1) only, per triage 5518587775. New error id `security-controlled-by-parent-ambiguous-relation` in `packages/lint/src/validate-security-posture.ts`, exported from `index.ts` beside `SECURITY_CBP_NO_RELATION`: when two or more candidates sit in the WINNING tier of the master-relation precedence (required master_detail, then any master_detail, then required lookup), it names every candidate (field, type, master) in declaration order, names the tier, names the candidate that wins today, and refuses. Only the winning tier is judged, because the runtime's `??` chain stops at the first tier that resolves, so a lower tier's tie is masked and is not a decision the platform makes. `resolveCbpRelation` now reads its tiers from one shared table so the two CBP rules cannot disagree about which tier wins; its answer is unchanged by construction (`find` over a tier is the first element `filter` keeps). The mirror's deliberate `reference`-only divergence (:206-213, #5017) is kept and pinned by a test from this rule's side. The module header's ADR-0049 paragraph (`every error rule mirrors a runtime enforcement point`) is amended rather than left false: this rule has no runtime refusal to mirror precisely BECAUSE the runtime silently picks instead of refusing, which is what makes author time the only place the ambiguity can surface. `packages/plugins/plugin-security/**` and `packages/spec/**` untouched; directions (2) and (3) not implemented and not needed for (1). FILE-SURFACE AMENDMENT (declared, not silent): one bounded companion fix outside the claimed surface, `packages/lint/scripts/check-doc-security-posture.mjs` -- the new rule is added to the same partial-evaluation suppression that already covers `SECURITY_CBP_NO_RELATION`, because an opaque `Field.master_detail(...)` factory call is invisible to every tier predicate, so a masked tier-1 winner would hand the win to a lower tier and report a tie the platform never resolves. Zero effect on today's corpus (no marked block declares controlled_by_parent, as that gate's own comment records) -- it closes a latent false-red in a security gate and keeps that gate's docblock enumeration true. It is one identifier in a condition plus the docblock line, pinned in shape by the sibling declaration on the adjacent line, and named with evidence in the PR body. No rule catalogue outside the package enumerates rule ids (grep for `security-controlled-by-parent-no-relation` across the tree hits only the package's own source, tests and CHANGELOG), so no doc row was owed. Changeset `@objectstack/lint: minor`, matching neighbouring lint changesets that add a rule id and a public export. No half-states seen: the issue was already assigned and the PM claim comment is mine.",
 "tests": "All on the FINAL commit 81a7c46f71 (the merge of origin/main), in worktree ../objectstack-14747, after `pnpm exec turbo run build --concurrency=2 --filter='./packages/*' --filter='./packages/*/*'` (71/71 tasks). (1) `pnpm --filter @objectstack/lint test` -> `Test Files 93 passed (93) / Tests 2865 passed (2865)`. (2) `pnpm --filter @objectstack/lint typecheck` -> exit 0, and its second half really measured the test layer: `check:test-typecheck: OK -- @objectstack/lint's test layer compiles under packages/lint/tsconfig.test.json; 2 file(s) / 6 error(s) / 2 pinned signature(s) held`. (3) `pnpm lint` (`eslint . --no-inline-config`, WHOLE repo, no narrowing needed) -> exit 0. (4) `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` derived 37 families (31 by path + 8 by kind, 2 shared) from the same 5 paths before and after the merge; all 37 run, 36 green, 1 NOT MEASURED: `node scripts/check-test-completeness.mjs` exits 3 with `PREREQUISITE NOT MET -- this gate grades a saved turbo run test log, and no log was named` -- the script's own text says to record it as NOT MEASURED locally, and that it is not a red. Both build-dependent ratchets ran on the built closure and are green on the final head: `check:dual-build-cjs-loads` (`provenance -- entries/packages/cjsFiles/probes: this run 102/66/610/1 - floors 90/58/520/1`) and `check:type-check-debt` (`check-type-check-coverage --re-measure: OK -- 21 ledger entr(ies) re-measured in 302.5s, 549 raw tsc error(s) total, none above its recorded number`). Exit codes were captured before any pipe (redirect-then-capture) throughout. (5) CORPUS MEASUREMENT of the accept-set narrowing, run against the BUILT dist so it reads the new code: the 4 example-app stacks hold 3 controlled_by_parent objects -- showcase_invoice_line, showcase_expense_line, crm_opportunity_line_item -- and emit `cbp-no-relation=0 cbp-ambiguous-relation=0` each; showcase_invoice_line is the discriminating one, carrying a required master_detail AND a required lookup, and it is silent because the lookup tier is never reached. app-showcase's 5 pre-existing findings are all other rules (2x info security-private-no-readscope, 3x warning security-master-detail-ungranted) and are unchanged. The docs+skills prose corpus is covered by `pnpm --filter @objectstack/lint run check:doc-security-posture`: green over 27 ObjectSchema.create sites in 226 marked blocks across 236 files. So: 0 findings before, 0 after. (6) The rule's own accept bar is 18 new tests: an error on a tie in EACH of the three tiers plus a three-way tie, the same two fields declared in both orders naming the other winner each time, the array field form, and negative controls for every way a tie can fail to be one -- a masked tier-3 tie under a single required master_detail, a masked tier-2 tie, one candidate per tier, a second candidate naming no reference target, an optional second lookup, a non-cbp sharingModel, and the rejected `reference_to` alias -- plus mutual exclusivity with the no-relation rule and non-exemption of system objects. NO ablation was run and none is claimed: the positive controls ARE the rule's failure demonstration (the tier-1/2/3 error fixtures fail against origin/main, where no such rule exists), and the file's own meta-tests already refuse a branch no key-legal stack can reach. Two meta-tests in the file did fail on the first run and were repaired deliberately, not routed around: the `found` receiver row in READ_SURFACES named a local the refactor removed (its FieldSchema reads moved onto `f`, which the table already covers), and `cbpTier` / `winner` / `cand` / `matched` are new receivers that had to be entered in NOT_SCHEMA_RECEIVERS / PLUMBING with reasons; `pushedRuleIds()` went 16 -> 17 and the reachability corpus gained a `cbp-ambiguous-relation` fixture that passes `unrecognizedKeysIn`.",
 "mcp_calls": "0 -- every GitHub read and write went through REST with $GITHUB_TOKEN and the proxy CA bundle; zero MCP GitHub calls for the whole run",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code