docs(plugin-security): freeze note on assertControlledByParentWrite (#9137)

[os-project-manager]

Fixes#9137

What

Adds the load-bearing freeze note the #8772 ruling's Direction 4 calls for
("immediately", ahead of or alongside the first ramp slice) at
assertControlledByParentWrite's absent-master-FK branch in
packages/plugins/plugin-security/src/security-plugin.ts. No behaviour
change — comment-only.

The note states, in place:

• This if (and the omissionRefusedByValidation predicate it reads) is the
  sole enforcement point for three authorable controlled_by_parent
  master-reference shapes: master_detail with no required; required: true + readonly; required: true + system — the last three rows of
  A controlled_by_parent object may declare its master reference without required, so the master-access guard is the only thing preventing an unreachable orphan detail row #8772's five-shape measurement table, and exactly the three shapes
  record-validator.ts skips before its required check ever runs
  (if (def.system || def.readonly) continue;, insert-mode :993 /
  update-mode :1003).
• ⛔ Do not move, weaken, or stand this gate down further for those three
  shapes — concretely, do not widen omissionRefusedByValidation to admit
  them — until both ramp legs land: (a) the authoring builder forces
  required: true under controlled_by_parent (spec builder: force required: true on a master_detail reference under controlled_by_parent (ruled Direction 2 of #8772) #9138), and (b) lint refuses
  the shape at the v18 boundary (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, held for the v18 window).
• Why, concretely: standing the gate down for any of the three would mint a
  detail row whose master FK is null, which the controlled_by_parent read
  filter (fk IN (readable masters)) can never match — unreadable by anyone,
  and 422 MISSING_REQUIRED_FIELD on every later by-id write, permanently
  (no payload the caller could send would restore a field the request never
  carried).
• A matching one-line pointer was added at the omissionRefusedByValidation
  field declaration itself, since that predicate is the actual knob a future
  change would widen.

Also corrects an adjacent, now-stale [#8959] paragraph in the same
branch. It still read "#8772proposes a lint … it is open and unruled" —
true when #8959 landed it, false today: #8772 was ruled and closed on
2026-08-16 (comment 5306089973).
Left uncorrected, it would have sat one paragraph above this PR's own freeze
note and contradicted it. The corrected paragraph keeps #8959's actual
finding intact and current: no publish-time gate refuses these three shapes
yet — that remains true until #9138and#9139 both land — but it no
longer misdescribes #8772 itself as unruled.

Premise re-check (the card asked for this before writing)

• assertControlledByParentWrite is confirmed live at
  security-plugin.ts:5121 on origin/main (git grep).
• The guard is not flatly unconditional any more. PR fix(plugin-security): a required master-detail parent omitted on insert answers 400 VALIDATION_FAILED with fields[] (#8688) #8879 (merged
  2026-08-15, closing A missing required master-detail parent still answers 422 MISSING_REQUIRED_FIELD with no fields[] and a [Security] message — while the same field, present-but-unresolvable, answers 400 VALIDATION_FAILED with fields[] (#7474 residual, 17.0.0 GA) #8688) already landed a conditional stand-down keyed
  on CbpRelation.omissionRefusedByValidation. For the three shapes this
  note is about, that predicate is always false by construction
  (def?.type === 'master_detail' && !!def?.required && !def?.readonly && !def?.system), so the guard remains the sole, unconditional enforcement
  point for exactly those three — which is what the note now says, rather
  than the flat "still unconditional" framing the card anticipated as the
  default outcome of the re-check.
• A missing required master-detail parent still answers 422 MISSING_REQUIRED_FIELD with no fields[] and a [Security] message — while the same field, present-but-unresolvable, answers 400 VALIDATION_FAILED with fields[] (#7474 residual, 17.0.0 GA) #8688 is not "still open and unruled." It was ruled and merged (PR
  fix(plugin-security): a required master-detail parent omitted on insert answers 400 VALIDATION_FAILED with fields[] (#8688) #8879, 2026-08-15). Its proposed route — stand the guard down for an
  absent master FK on insert — already landed, correctly narrowed to the one
  shape validateRecord actually covers. The freeze note is written
  accordingly: it protects against widening an already-landed, conditional
  stand-down, not against a still-hypothetical change. (Reported per the
  card's own instruction to adjust the framing rather than write a stale
  warning.)
• The three unsafe shapes were independently re-counted against
  record-validator.ts's if (def.system || def.readonly) continue;
  (:993 insert-mode, :1003 update-mode) plus validateOne's
  def.required && isMissing(value) check: exactly 3, matching the card and
  A controlled_by_parent object may declare its master reference without required, so the master-access guard is the only thing preventing an unreachable orphan detail row #8772's five-row measurement table.
• A pinned test asserting the guard refuses the absent-master insert for
  all three shapes already exists —
  controlled-by-parent-sharing.test.ts's it.each block ('[#8688] 422 MISSING_REQUIRED_FIELD survives on insert: %s'), added by PR fix(plugin-security): a required master-detail parent omitted on insert answers 400 VALIDATION_FAILED with fields[] (#8688) #8879. Per
  the card's "check first" instruction, no duplicate test was added.

Changeset

Comment-only, no behaviour change ⇒ no changeset. skip-changeset label
applied.

Tests

All commands below were re-run at this PR's final commit,
1a67152fc (git rev-parse --short HEAD).

• pnpm --filter '@objectstack/plugin-security^...' build — dependency
  closure, green.
• pnpm --filter @objectstack/plugin-security typecheck — green (tsc --noEmit, exit 0).
• pnpm --filter @objectstack/plugin-security test — 66 test files, 1279
  tests, all passing (includes the already-pinned three-shape it.each
  above).
• node scripts/check-cross-package-test-inputs.mjs,
  node scripts/check-test-source-alias.mjs,
  node scripts/check-type-source-resolution.mjs — the three path-derived
  gates from node scripts/pm/dispatch-gates.mjs — all green.
• node scripts/check-adr-anchors.mjs — green (this file is ADR-0055
  content-anchored; the anchor is citation-based, not line-based, so the
  comment edit does not disturb it).
• node scripts/check-nul-bytes.mjs — clean.
• node scripts/check-i18n-bundles.mjs (after pnpm exec turbo run build --filter=@objectstack/cli) — "9 package(s) — all bundles in sync, no
  undeclared authoring keys" (comment-only edit produces no drift).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-security.

12 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/deployment/cli.mdx(via @objectstack/plugin-security)
• content/docs/kernel/runtime-services/sharing-service.mdx(via @objectstack/plugin-security)
• content/docs/kernel/services-checklist.mdx(via @objectstack/plugin-security)
• content/docs/permissions/access-recipes.mdx(via packages/plugins/plugin-security)
• content/docs/permissions/authorization.mdx(via @objectstack/plugin-security)
• content/docs/permissions/explain.mdx(via @objectstack/plugin-security)
• content/docs/permissions/permissions-matrix.mdx(via packages/plugins/plugin-security)
• content/docs/permissions/sharing-rules.mdx(via @objectstack/plugin-security)
• content/docs/plugins/index.mdx(via @objectstack/plugin-security)
• content/docs/plugins/packages.mdx(via @objectstack/plugin-security)
• content/docs/ui/audience-based-interfaces.mdx(via packages/plugins/plugin-security)
• content/docs/ui/dashboards.mdx(via @objectstack/plugin-security)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/plugin-security)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.