Skip to content

Commit 9c12140

Browse files
docs(adr): ADR-0066 ⑧'s when note names the record-scoped field projection as a third, row-aware reader (#26594, ruling B) (#27152)
Fixes #27075 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:`docs/adr/0066-unified-authorization-model.md` ⑧ 下新增一条 2026-10-28 的注记(全文 +2 行,其一为空行),点名「记录级字段投影」`GET /api/v1/data/:object/:id/field-access` 是字段权限 `when` 的第三个读者、且是按存储行判定的那一个;ADR 其余每一行一字未动。 - 为什么改:PR #27063(card #26594,裁决记录 6457467702 字母 B)已把这个按行判定的读者落在 main 上,但 ADR 的 2026-10-26 注记只点名了写门与不看行的读者;读 ADR 的人会以为没有任何读者看得到行。现在三类读者在 ADR 里都有名字。 - 风险与回滚:零运行时影响(纯 ADR 文本,`docs/adr/**` 不发布,打 `skip-changeset`);回滚即 revert 本 PR 的单个 commit。 - 先看:只有一个文件、一个 hunk —— `docs/adr/0066-unified-authorization-model.md` L135–L136(新注记);核对其三句话与 `packages/plugins/plugin-security/src/security-plugin-field-readers.ts` L233–L248、`packages/rest/src/rest-route-ledger.ts` L364–L366 一致。 - 两分钟验证:`git diff origin/main...HEAD --numstat`,预期恰好一行 `2 0 docs/adr/0066-unified-authorization-model.md`。 - 需要你做的:Tier H(`docs/adr/**` 受管面)—— 一次 `GOVERNED_APPROVERS` 账号的 APPROVED review;批准后由席位落地,不需要你点合并。 ## What changes One dated note under ⑧ of ADR-0066, placed directly after the 2026-10-26 note (ruling of record 6408558941) and before ⑨, in the file's own form: a blank line, the indented blockquote, a bold dated lead-in, one paragraph on one line (1116 characters against the existing note's 1457). Nothing else in the ADR moves — the 2026-10-26 note, the header and `**Status**:` line, every other item, and `docs/adr/README.md` (generated by `scripts/adr-index.mjs` from `**Status**:` lines only; `check:adr-index` reports it current) are byte-identical to `origin/main`. The note, verbatim: > **Note (2026-10-28) — a third reader of `when` holds the row: the record-scoped field projection (#26594, ruling of record 6457467702, letter B).** `GET /api/v1/data/:object/:id/field-access` (`SecurityPlugin.getRecordFieldAccess`, the answer a record's edit form reads) judges each field permission's `when` against the **stored** row with the write gate's own function, `computeForbiddenFieldWrites`, asked as an update by id of that row naming every field over the same sets, posture and delegator intersection the gate takes — so its `editable` list is the gate's field-level verdict for that row, a conditioned lock disables a field only on the rows its condition names, and no second evaluator of `when` exists for it to drift from. The row-blind readers (`/auth/me/permissions`, the object-level field projections, `os explain`) are unchanged and still apply a conditioned entry as its lock, and `readable` stays row-blind. The record is read first exactly as `GET /api/v1/data/:object/:id` reads it, so an absent or unreadable row answers that read's refusal, and no reading is wider than the gate's. Where each clause was read from on `origin/main` (`24351cfe`, the merge base): - (a) The record-scoped projection judges `when` on the STORED row with the write gate's own function. Route: `GET /api/v1/data/:object/:id/field-access` as `packages/rest/src/rest-route-ledger.ts` L364 spells it, registered at `packages/rest/src/data-action-routes.ts` L356 as `${dataPath}/:object/:id/field-access`. Judge: `SecurityPlugin.getRecordFieldAccess` (`security-plugin.ts` L3013) reads the row as the caller reads it and asks `resolveProjectionFieldMask`'s `readRowForbiddenWrites` (`security-plugin-field-readers.ts` L241), which calls `computeForbiddenFieldWrites` — the exported symbol `security-plugin.ts` L57 imports from `security-plugin-object-inputs.ts` — with `operation: 'update'` and the stored row as `preImage`, naming every field. The record form reads it: `client.data.fieldAccess` (ledger L364; `content/docs/permissions/field-level-security.mdx` L60–67). "Field-level verdict" is deliberate: the object grant and row-level walls are judged elsewhere, as the schema text and the PR #27063 contract review (record 6460514485) state. - (b) The row-blind readers are unchanged and still apply a conditioned entry as its lock: the PR #27063 contract review ("Unchanged without the record — holds": `/auth/me/permissions`, `getWritableFields`, `getReadableFields`, `getMetadataReadableFields`, `getQueryableFields`, `os explain` untouched) and `field-level-security.mdx` L55–59. `readable` stays row-blind: `permission.zod.ts` L923 and the `getRecordFieldAccess` docblock. - (c) No reading is wider than the gate's: the route reads the record through `getData` first with the same gates and mapped refusals as `GET /data/:object/:id`, so an absent or unreadable row answers that read's refusal (`data-action-routes.ts` L349–352; ledger note L366). - (d) Cites #26594 and the ruling of record 6457467702, letter B (read in full this act: "the server judges each field permission's `when` against the stored row exactly as the write gate does … `/auth/me/permissions` and the other row-less readers keep reporting a conditioned entry as its lock"). Premise verified before writing: `git log --oneline -1 --grep='#27063' origin/main` → `f9f27a06 feat(spec,plugin-security,rest,client): a record-scoped field projection judges a \`when\` lock on the stored row (#27063)` — merged and on `origin/main`; its file list carried no `docs/adr/**`, and L134 of the ADR still named only the write gate and the row-blind readers. ## Tests No test changes: a `docs/adr/**` amendment touches no package, so no ① dependency closure and no ② package `test` / `typecheck` is owed (the file surface is `docs/adr/0066-unified-authorization-model.md` alone), and documentation is not ablated. Head measured: `5ccadf23` (`git rev-parse --short HEAD` after the final commit; the gate union below ran on that tree). <details><summary>On-disk proof of the diff shape, head 5ccadf2</summary> ``` git diff --numstat → 2 0 docs/adr/0066-unified-authorization-model.md L134 md5 at HEAD 8a105f47be1fce00f9f2a95fd412c944 == L134 md5 in the tree 8a105f47be1fce00f9f2a95fd412c944 L135 = blank · L136 = the new note (1116 chars, begins " > **Note (2026-10-28) — …") · L137 = "- **⑨ Authoring-time validation …" grep -naP for the C0 / DEL control-byte class on the file → no match (grep exit 1) node scripts/check-nul-bytes.mjs → OK (scanned 21863 text file(s) … no raw ASCII control bytes), exit 0 ``` </details> ## Acceptance notes - Dispatch-order hypotheses, measured — all five held, one with a correction: (1) `docs/adr/README.md` is generated from `**Status**:` lines only, so an in-place note owes it nothing; left untouched and reported current. (2) The derived list is the ADR/docs prose families plus the whole-tree families, nothing from the test tiers; but `check:pm-governed-prose`, the family the order named, does not derive for this path (it reads `AGENTS.md`'s governed-surface paragraph), and no markdown-lint or link-check family exists beyond `check:adr-links`. The ADR siblings that derived: `check:adr-links`, `check:adr-anchors`, `check:adr-index`, `check:adr-symbol-anchors`, `check:doc-authoring`, `check:doc-formula-expressions`. (3) The ledger's spelling of the route is the one cited. (4) `computeForbiddenFieldWrites` is the exported symbol; the plugin's private method of the same name wraps it. (5) `check:pm-skill-id-lint` scans `.claude/skills/pm-dispatch`, `skills/`, `.claude/agents/os-dev.md` and `AGENTS.md` only. - The 2026-10-26 note's phrase "every row-blind reader (`/auth/me/permissions`, the field projections, `os explain`)" now reads beside the new note and is left verbatim by the card's scope (⑧ only, one dated note). Not a finding. - Spelling variance, not a contract violation: `content/docs/protocol/objectql/security.mdx` L264 spells the route `GET /data/{object}/{id}/field-access`, `field-level-security.mdx` L61 spells `GET /api/v1/data/{object}/{id}/field-access`, and the ledger spells `:object/:id`. The ADR cites the ledger's. Noted, not filed. - `pnpm --filter @objectstack/lint run check:doc-formula-expressions` first exited 3 — PREREQUISITE NOT MET: `@objectstack/formula` and `@objectstack/lint` are not built in a fresh worktree. Built both under the verify lock (`VERDICT command-exit 0 · held the lock 89s · waited 0s`) and re-ran: exit 0. A local-environment fact, not a finding; nothing was measured by the first run. - Out-of-scope findings in classes a/b/c: none. - Attribution: the commit carries the model-free trailer pair AGENTS.md prescribes; the harness attribution reminder's model-named trailer form and its PR-footer form were not used, by that reminder's own precedence sentence. ## Verification Local gate subset, derived with `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` (no paths; change set off merge base `24351cfe`: 1 path, +2/-0; 21 commands — 13 matched by path, 8 declared whole-tree) and reconciled with `--ran` on a record carrying every exit code: `21 derived, 21 run, 0 NOT-MEASURED, 0 UNRUN (a DERIVED zero — all 21 recorded an exit code and none of them is 3)`. Every exit captured before any pipe (`cmd > LOG 2>&1; EXIT=$?`). <details><summary>Gate readings on head 5ccadf2 — 21 commands, all exit 0</summary> ``` node scripts/check-adr-links.mjs :: exit 0 — ✅ 925 relative link destination(s) under docs/adr/ resolve node scripts/check-adr-links.mjs --self-test :: exit 0 — ✅ discrimination, census, ADR-0046 pin and baseline staleness all verified pnpm check:adr-anchors :: exit 0 — OK (91 anchored file(s), every governing ADR still referenced; 139 decision number(s) …) pnpm check:adr-index :: exit 0 — OK — docs/adr/README.md is current, every record parsed, self-test 46 assertions green (report-only) pnpm check:adr-symbol-anchors :: exit 0 — ✅ 2773 anchors across 145 records resolve pnpm check:doc-authoring :: exit 0 — ✓ 440 files clean · 69 published skill files clean · 19622 customer-facing string(s) clean · sibling-package prose ids hold the baseline pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0 (rerun after building @objectstack/formula + @objectstack/lint; first run exit 3 PREREQUISITE NOT MET) node scripts/check-closing-keyword-parity.mjs :: exit 0 — OK (3 parsers agree on all 9 keywords and both measured separators) node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0 — ✓ 40 assertions, 5 mutations driven to red node scripts/check-comment-mask-corpus.mjs :: exit 0 — ✓ 18694 files, 0 disagree, 0 unparseable node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0 — ✓ 23 case(s) across 5 batteries pnpm check:ci-filter-parity :: exit 0 — OK: all 202 declared cross-package glob(s) covered; all 23 build input(s) and 13 script(s) covered by `core` pnpm check:closed-ceremony-text :: exit 0 — ✓ 4766 shipped file(s) read; none says the ownership ceremony is closed pnpm check:gitlink-declared :: exit 0 — OK (21965 index entries, 0 gitlink(s)) pnpm check:cross-package-test-inputs :: exit 0 — OK: 31 package(s) read outside themselves, all declared; 3868 test file(s) … every one declared pnpm check:driver-memory-census :: exit 0 — OK — every declaration is ledgered, every ledger entry is live pnpm check:nul-bytes :: exit 0 — OK (scanned 21863 text file(s); no raw ASCII control bytes) pnpm check:pm-governed-merges :: exit 0 — ✓ self-test 537 assertions; live: the real generator declared 9 output(s) and certified this tree pnpm check:pm-prior-rulings :: exit 0 — ✓ self-test 155 cases pass pnpm check:refd-timer-probe :: exit 0 — OK 18684 source file(s) swept; the probe is read in the approved module and nowhere else pnpm check:watch-hint-literal :: exit 0 — ✓ 74 declaration(s) across 4 rostered name(s), all 187 literals admitted ``` </details> Every family CI runs on this PR (the artifact-roster, wide-population and always-runs families the derivation lists as outside the derived total) is read from the PR's check-runs by the seat and was not re-run locally. `check:dev-prereqs` / `check:skill-frame-freshness` are not owed (no `packages/spec` build, no frame file touched). Dogfood battery: n/a (no `!` in the title, Clause-② no). `test:repo` is CI's. --- _Generated by [Claude Code](https://claude.ai/code/session_01QSeKYmhU5KEj1nukYhp1Tg)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent c5b9f5f commit 9c12140

1 file changed

Lines changed: 2 additions & 0 deletions

File tree

‎docs/adr/0066-unified-authorization-model.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,8 @@ Captured for the record; **out of scope for Phases 1–4 above**. Each is anchor
132132
- **⑧ FLS posture: unlisted fields are visible, and field grants union without deny** *(recorded 2026-07 pre-launch architecture assessment)*. Runtime FLS is block-list-shaped: `field-masker.ts` hides a field only when an explicit rule marks it `readable:false`, so an **undeclared** sensitive field is exposed by default, and `getFieldPermissions` merges most-permissively, so one set's `readable:true` permanently out-votes another's `false`. Consequences: protecting a salary/ID-number field relies on discipline (grant it only where needed), not mechanism. The object-level `private` posture (D2/④) mitigates the unlisted-default-visible half for objects that adopt it; the union half is the field-level face of ⑦ — a muting/deny layer must cover **field** grants, not just object grants, when it lands. Until then, treat "sensitive field on a `public` object" as a smell in review.
133133

134134
> **Note (2026-10-26) — a field permission entry may carry a row condition (#25866, ruling of record 6408558941).** `FieldPermissionSchema.when` is a row predicate in the same canonical CEL as `rowLevelSecurity[].using`, on the **edit** vote only (`when` beside `readable: false` is refused at parse). The condition **narrows where an entry votes**: on a row that matches, the entry votes as declared; on a row that does not, the entry is **absent**, as if the set had not declared the field. It does **not** change the posture recorded here — field grants still **union without deny**: a matched conditioned lock is out-voted by a sibling's unconditioned `editable: true` exactly as before, an entry without `when` votes on every row, and only declaring entries vote. The write gate judges the stored row before an update and the incoming row of an insert, in process (`RLSCompiler.compileRowPredicate` + `storedFormCheckJudge`); a row that cannot be judged (a predicate update, a stored row the caller cannot read, a condition that does not resolve for the request) and every row-blind reader (`/auth/me/permissions`, the field projections, `os explain`) apply the entry as its lock, so no reading is wider than the gate's. The condition is validated like an RLS predicate at authoring (`rls-predicate-*` findings on `permissions[].fields[].when`). Taking an edit away that another set grants remains the job of the muting/deny layer ⑦ still owes.
135+
136+
> **Note (2026-10-28) — a third reader of `when` holds the row: the record-scoped field projection (#26594, ruling of record 6457467702, letter B).** `GET /api/v1/data/:object/:id/field-access` (`SecurityPlugin.getRecordFieldAccess`, the answer a record's edit form reads) judges each field permission's `when` against the **stored** row with the write gate's own function, `computeForbiddenFieldWrites`, asked as an update by id of that row naming every field over the same sets, posture and delegator intersection the gate takes — so its `editable` list is the gate's field-level verdict for that row, a conditioned lock disables a field only on the rows its condition names, and no second evaluator of `when` exists for it to drift from. The row-blind readers (`/auth/me/permissions`, the object-level field projections, `os explain`) are unchanged and still apply a conditioned entry as its lock, and `readable` stays row-blind. The record is read first exactly as `GET /api/v1/data/:object/:id` reads it, so an absent or unreadable row answers that read's refusal, and no reading is wider than the gate's.
135137
- **⑨ Authoring-time validation for capability references** *(recorded 2026-07 pre-launch architecture assessment)*. `systemPermissions` / `requiredPermissions` are free strings today; a typo (`mange_users`) fails closed at runtime — the safe direction — but is undiscoverable: nothing reports that the referenced capability exists nowhere. When D1 lands the `sys_permission` registry, add the authoring/publish-gate lint alongside it: referencing an unregistered capability warns at author time (consistent with ADR-0049 honesty and the contract-first Prime Directive — reject at the producer, don't tolerate at the consumer). **Landed (2026-07):** `validateCapabilityReferences` in `@objectstack/lint` warns (never errors — cross-package capabilities and the fail-closed runtime make a hard gate wrong) when a `requiredPermissions` reference resolves against neither the built-in set (`@objectstack/spec` `PLATFORM_CAPABILITY_NAMES`), nor a capability the stack grants via a permission set's `systemPermissions`, nor a `sys_capability` seed row. Wired into `os validate` and `os lint`. `systemPermissions` (the declaration side) is deliberately not flagged.
136138

137139
> **Note (2026-10-14) — ⑨'s seed-row source is gone.** With `sys_capability` retired by #15204

0 commit comments

Comments
 (0)