Skip to content

Commit 7c70f91

Browse files
docs(skills): objectstack-data teaches the field permission when and when to pick it over a validation rule (#26393)
<!-- claude-projects-attribution: {"github_login":"os-warren"} --> _Requested by **Warren** · [project thread](https://claude.ai/code/project/chan_01U5RdnAAmkSQmZbqh6FtqZ8?thread=cmsg_01U5RdnAAmkSQmZbqh6FtqZ89XwmVLX9dBejfHmWEYgMwG)_ Fixes #26179 Clause-②: no Metadata-protocol: none ## 维护者速读 - **改了什么**:`skills/objectstack-data/rules/security.md` 新增一节「字段权限的行条件 `when`」:先写选择规则(所有人都锁 → 验证规则;按角色锁 → 该权限集字段项上的 `when`,二者不并用),再给合同示例,再列四条边界(只管编辑、仅同对象字段、按更新前的行判定、只锁不授),末尾指向文档与配方。`SKILL.md` 的 `readonlyWhen` 一行加一句「对所有人;按角色用 `when`」(在余量内,不抬上限)。eval 文件加第 5 题(合同提示,期望 `when` + `readable: true`,不得出现验证规则或 `readonlyWhen`)。两行 token 上限按实测抬高,裁决原文写在行旁。首轮门禁 `check:role-word` 拒了「按角色」的英文拼法(保留词),已改为 permission set。 - **为什么改**:客户的 AI 作者按技能建应用,遇到「财务审批后不得改合同法律条款」会写验证规则,把字段对所有人锁死;`when` 已随 18.2 发布但技能没教「选它」,能力就一直用不上。 - **风险与回滚**:只改发布技能包的文字与一个 eval 夹具,不改运行时;回滚即 revert 本 PR(两行上限随之回落)。 - **先看**:① `skills/objectstack-data/rules/security.md` 新节(选择规则两条、示例一段、边界四条);② `scripts/check-skills-token-ratchet.mjs` 两行上限及其注释引的裁决;③ `evals/hooks-security-seeds-datasources.json` 第 5 题。 - **两分钟验证**:`node scripts/check-skills-token-ratchet.mjs` → 末行 `81 authored bundle file(s) within their ceilings`,其中 `rules/security.md is 2956 tokens (ceiling 2956; headroom 0)`、`hooks-security-seeds-datasources.json is 1095 tokens (ceiling 1095; headroom 0)`。 - **需要你做的**:Tier H(`skills/**`),请 approve 或直接 Merge when ready。 ## What changes Card #26179, items 1–4: 1. **`rules/security.md` — a `when` section** (placed before "Sensitive fields"): what it is (a row condition on a field entry's **edit** vote, in the canonical CEL of `rowLevelSecurity[].using`), the choice rule stated first, the contract example from the card (`'clm_contract.governing_law': { readable: true, editable: false, when: "status in ['approved', 'signing', 'active']" }`), then the boundaries: edit vote only (`readable: false` beside `when` is refused), same-object fields (no relation reach; refused at `os validate` / publish), pre-image on update (a write cannot unlock itself by moving `status` back; an insert on the row as sent), locks and never grants (unmatched rows fall back to the other grants; another held set's `editable: true` still wins). 2. **The choice rule, as a rule:** a lock that holds for everyone is a validation rule (and `readonlyWhen` likewise strips the write for everyone); a lock that depends on who edits is `when` on the field entries of each permission set that loses the edit. Never both for one need. (`check:role-word`, ADR-0090 D3, refuses the reserved word in prose, so the teaching says "permission set" where the card says role.) 3. **Eval 5** in `evals/hooks-security-seeds-datasources.json`, in the file's existing shape: the contract prompt; expected output names `when` on the finance set's entries with `readable: true` and no validation rule / `readonlyWhen`; `must_not_contain` pins `validations:` and `readonlyWhen`. 4. **Pointers**: the section ends with the docs anchor `field-level-security#row-conditioned-edit-locks-when` and the recipe anchor `access-recipes#data-lock-fields-for-a-position-once-a-record-reaches-a-stage` (both exist on `main`). `references/_index.md` is generator-owned (`gen:skill-refs` from `SKILL_MAP`; `permission.zod.ts` is already listed), so the pointer lives in `security.md`, not the index. Also: one clause on `SKILL.md`'s `readonlyWhen` line — the place an author reaches for the lock-for-everyone — naming the per-set alternative. It lands inside the file's headroom (raw 6104 → 6125 tokens; the ratchet's priced count 6120, ceiling 6123), no raise. **Token-ratchet rows** (`scripts/check-skills-token-ratchet.mjs`), per the maintainer's ruling on the seat's decision card 「skills 修复卡的教学和 eval 都撞 token 天花板,怎么付?」, tap **A** (2026-10-27 01:21Z), verbatim and untranslated: 「A:先削重复,余额按实测提高」. Step one, cut duplicates first: measured on `origin/main` `756220c4`, `rules/security.md` carries no repeated sentence and nothing the package states twice (its `secret` / `requiredPermissions` teaching is the only full one; `SKILL.md:305` and `field-types.md:45` are one-line table cells), and the eval file repeats nothing — so there was nothing to cut and no surviving-home list to give. Step two, raise by the measured remainder: `rules/security.md` 2563 → 2956 (+395 landed on 2561, 2 absorbed by headroom, ceiling +393); `evals/hooks-security-seeds-datasources.json` 894 → 1095 (+201, zero headroom). Both rows re-pinned at zero headroom; the comments beside them quote the ruling. **Two readings** (lines, and tokens as the ratchet counts them, `ceil(utf8 bytes / 4)`; the SKILL.md token reading here is the raw file, the ratchet's priced count excludes the version line): | File | Lines before → after | Tokens before → after | |:--|:--|:--| | `rules/security.md` | 220 → 249 (+29) | 2561 → 2956 (+395) | | `SKILL.md` | 465 → 466 (+1) | 6104 → 6125 (+21) | | `evals/hooks-security-seeds-datasources.json` (not .md, reported for the raise) | 45 → 55 (+10) | 894 → 1095 (+201) | | **Whole package** (`SKILL.md` + `references/**/*.md` + `rules/**/*.md`, 14 files) | **3705 → 3735 (+30)** | **39046 → 39462 (+416)** | Nothing removed: the card names no stale line in this package. Sequencing (zero verbs beside these numbers): #26297 edits the same `rules/security.md` and is dispatched after this lands; #26244 adds a line to `references/_index.md`, which this PR does not touch; #26178 is the companion docs card, already closed. `skip-changeset`: the published skills packages carry no `package.json`; nothing is released from any package. ## Tests - `node scripts/check-skills-token-ratchet.mjs` — exit 0: `81 authored bundle file(s) within their ceilings`, the two raised rows at headroom 0, `SKILL.md` at headroom 3. - `node scripts/check-skills-token-ratchet.mjs --self-test` — exit 0, `79 cases pass`. - `pnpm --filter @objectstack/spec run check:skill-docs`, `check:skill-refs`, `check:skill-examples` — see Verification (the new code block is a fragment, deliberately not marked `os:check`, like the file's RLS block). - Eval 5 is a fixture (the repo has no eval runner): its assertions were checked by hand against the expected output — every `must_contain` string occurs in it, neither `must_not_contain` string does. ## Acceptance notes - `evals/README.md` (headroom 1 token) was not updated to name `when` in its topic list; a one-line mention would need another raise for five tokens. Not filed: observation only. - The dispatch order's "`skills/**` inside the package's ceilings" cannot hold at the measured headroom (security.md 2, eval 0); the seat widened the surface to the two ratchet rows under the ruling above. - The PR body's first two lines are the harness-written attribution block (the os-dev exception); `Fixes #26179` follows immediately. ## Verification Gate list derived with `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` on the final tree (`756220c4` base, head `5f62d15b`), each run locally with the exit code captured before any pipe; `--ran` reconciliation below. **Reconciliation** (`node scripts/pm/dispatch-gates.mjs --ran ran.list --repo objectstack-ai/objectstack`, exit 0): `52 derived, 51 run, 1 NOT-MEASURED, 0 UNRUN`. The one NOT MEASURED is `pnpm check:dual-build-cjs-loads`: its prerequisite is a whole-repo build (111 packages without `dist/` on this fresh worktree); this diff touches no package source, and CI's `Lint & Repo Gates` runs it — a declared narrowing. Three derived gates refused on a missing build on the first pass (`check:doc-formula-expressions`, `check:lean-entry-closure`, `check:skill-examples`); the named closures were built under `scripts/pm/os-verify-lock.sh` (slot `issue-26179`: formula+lint 94 s, objectql 61 s, client-react 149 s) and the gates then exit 0 on the final head. `check:role-word` was red on the first head (the reserved word in the new prose, ADR-0090 D3) and is green on `5f62d15b`. `check:pm-dispatch-gates` ran detached on the final head: 332.2 s fast tier, 1901 cases, exit 0. <details><summary>Every derived command with its exit code on 5f62d15 (54 lines: the 52 derived, plus `check:skill-refs` and `check:skill-examples` the dispatch order asked for)</summary> - `node scripts/check-ci-filter-parity.mjs` — exit 0 - `node scripts/check-closing-keyword-parity.mjs` — exit 0 - `node scripts/check-closing-keyword-parity.mjs --self-test` — exit 0 - `node scripts/check-comment-mask-corpus.mjs` — exit 0 - `node scripts/check-declaration-mirrors.mjs` — exit 0 - `node scripts/check-declaration-mirrors.mjs --self-test` — exit 0 - `node scripts/check-doc-route-spelling.mjs --advisory` — exit 0 - `node scripts/check-doc-route-spelling.mjs --self-test` — exit 0 - `node scripts/check-dts-emitted.mjs --self-test` — exit 0 - `node scripts/check-scripts-symbol-anchors.mjs` — exit 0 - `node scripts/check-scripts-symbol-anchors.mjs --self-test` — exit 0 - `node scripts/check-self-test-wired.mjs` — exit 0 - `node scripts/check-self-test-wired.mjs --self-test` — exit 0 - `node scripts/check-self-test-workflow-commands.mjs` — exit 0 - `node scripts/check-self-test-workflow-commands.mjs --self-test` — exit 0 - `node scripts/check-skills-token-ratchet.mjs` — exit 0 - `node scripts/check-skills-token-ratchet.mjs --self-test` — exit 0 - `node scripts/check-whole-set-label-write.mjs` — exit 0 - `node scripts/check-whole-set-label-write.mjs --self-test` — exit 0 - `node scripts/ci/assert-turbo-remote-cache.mjs --self-test` — exit 0 - `node scripts/ci/prune-turbo-cache.mjs --self-test` — exit 0 - `node scripts/pm/bare-root-worklist.mjs --self-test` — exit 0 - `pnpm --filter @objectstack/lint run check:doc-formula-expressions` — exit 0 - `pnpm --filter @objectstack/spec run check:skill-docs` — exit 0 - `pnpm check:agent-test-spelling` — exit 0 - `pnpm check:bash32-floor` — exit 0 - `pnpm check:cli-command-ids` — exit 0 - `pnpm check:corpus-claim-drift` — exit 0 - `pnpm check:cross-package-test-inputs` — exit 0 - `pnpm check:doc-authoring` — exit 0 - `pnpm check:driver-memory-census` — exit 0 - `pnpm check:dts-closure` — exit 0 - `pnpm check:dual-build-cjs-loads` — NOT MEASURED (exit 3, PREREQUISITE NOT MET) - `pnpm check:entry-guard` — exit 0 - `pnpm check:gitlink-declared` — exit 0 - `pnpm check:lean-entry-closure` — exit 0 - `pnpm check:merge-driver` — exit 0 - `pnpm check:nul-bytes` — exit 0 - `pnpm check:parse-guard` — exit 0 - `pnpm check:pm-governed-merges` — exit 0 - `pnpm check:pm-skill-id-lint` — exit 0 - `pnpm check:pnpm-filter-targets` — exit 0 - `pnpm check:pnpm-flag-spellings` — exit 0 - `pnpm check:ratchet-remedy-authority` — exit 0 - `pnpm check:refd-timer-probe` — exit 0 - `pnpm check:role-word` — exit 0 - `pnpm check:skill-compatibility` — exit 0 - `pnpm check:skill-frame-sync` — exit 0 - `pnpm check:skill-identifier-liveness` — exit 0 - `pnpm check:sourcemap-no-sources-content` — exit 0 - `pnpm check:watch-hint-literal` — exit 0 - `pnpm --filter @objectstack/spec run check:skill-refs` — exit 0 - `pnpm --filter @objectstack/spec run check:skill-examples` — exit 0 - `pnpm check:pm-dispatch-gates` — exit 0 </details> <details><summary>Token ratchet on 5f62d15</summary> - `skills/objectstack-data/rules/security.md is 2956 tokens (ceiling 2956; headroom 0)` - `skills/objectstack-data/evals/hooks-security-seeds-datasources.json is 1095 tokens (ceiling 1095; headroom 0)` - `skills/objectstack-data/SKILL.md is 6120 tokens (ceiling 6123; headroom 3)` - `81 authored bundle file(s) within their ceilings; 10 generator-owned file(s) measured, not ratcheted.` - `--self-test`: `79 cases pass.` </details> <details><summary>check:skill-examples on 5f62d15</summary> `264 prose examples type-check across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC pass on all of them` (the new block in `security.md` is a fragment and is deliberately unmarked, like the file's RLS block). </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01JQwxbakp4nDuCkULsj7Fyr)_ --------- Co-authored-by: objectstack-fleet[bot] <objectstack-fleet[bot]@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>
1 parent 671df26 commit 7c70f91

4 files changed

Lines changed: 60 additions & 3 deletions

File tree

‎scripts/check-skills-token-ratchet.mjs‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -552,7 +552,16 @@ export const CEILINGS = new Map([
552552
// 2026-10-24 (project decision list item 9), verbatim and untranslated, the
553553
// line for item 8 of the same message elided:
554554
// 「9. 技能文档 security.md 的 token 上限 2543 → 2563 … 同意」.
555-
['skills/objectstack-data/rules/security.md', 2563],
555+
// 2563 -> 2956 (#26179): the field permission row condition `when` — the
556+
// choice rule (a lock for everyone is a validation; a lock that depends on
557+
// who edits is `when` on that set's field entries), one example and the
558+
// four boundaries — which the file did not teach, so an author locked the
559+
// fields for every user. +395 tokens on a landed 2561, 2 absorbed by
560+
// headroom, ceiling +393. The file carries no duplicated passage to cut
561+
// first (measured: no sentence repeats in the file). Maintainer ruling
562+
// 2026-10-27 on the decision card 「skills 修复卡的教学和 eval 都撞 token 天
563+
// 花板,怎么付?」, tap A, verbatim and untranslated: 「A:先削重复,余额按实测提高」.
564+
['skills/objectstack-data/rules/security.md', 2956],
556565
// 3024 -> 3109 (2026-08-31 app-repo-principles raise, see the block above).
557566
// Severity Levels listed the three values and left the CHOICE unstated: a
558567
// block rests on a judgement a person made, so a machine-inferred signal — a
@@ -651,7 +660,15 @@ export const CEILINGS = new Map([
651660
['skills/objectstack-ai/evals/skills-tools-knowledge.json', 1074],
652661
['skills/objectstack-api/evals/endpoints-auth-routes.json', 1042],
653662
['skills/objectstack-automation/evals/flows-triggers-approvals.json', 1255],
654-
['skills/objectstack-data/evals/hooks-security-seeds-datasources.json', 894],
663+
// 894 -> 1095 (#26179): one regression case for the field permission `when`
664+
// (the contract prompt: lock the legal terms for finance from approval on,
665+
// legal keeps the edit) — expected: `when` on the finance set's entries with
666+
// `readable: true`, and NO validation rule or `readonlyWhen` locking the
667+
// fields for every user. +201 tokens, zero headroom to absorb any of it,
668+
// ceiling +201; nothing duplicated in the file to cut first. Same ruling as
669+
// the `rules/security.md` row above (2026-10-27, tap A:
670+
// 「A:先削重复,余额按实测提高」).
671+
['skills/objectstack-data/evals/hooks-security-seeds-datasources.json', 1095],
655672
['skills/objectstack-data/evals/objects-fields-relationships.json', 946],
656673
['skills/objectstack-formula/evals/cel-predicates-formulas.json', 1046],
657674
['skills/objectstack-i18n/evals/bundles-locales-coverage.json', 1004],

‎skills/objectstack-data/SKILL.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,8 @@ export const Invoice = ObjectSchema.create({
218218

219219
- Use `visibleWhen` to hide irrelevant fields in ObjectUI forms.
220220
- Use `readonlyWhen` for state-locked fields; the ObjectQL write path ignores
221-
incoming changes when the predicate is `TRUE`.
221+
incoming changes when the predicate is `TRUE` (for everyone; per permission
222+
set → field permission `when`, rules/security.md).
222223
- **`readonly: true` governs the end-user surface, not trusted system writers.**
223224
A non-system write (REST/UI, and any `runAs:'user'` flow — the default) has
224225
the field **stripped** from any non-system write; the write reports

‎skills/objectstack-data/evals/hooks-security-seeds-datasources.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,16 @@
4040
"must_contain": ["defineSeed", "externalId", "upsert", "env:", "daysFromNow"],
4141
"must_not_contain": ["new Date(", "defineDataset", "externalId: 'id'"]
4242
}
43+
},
44+
{
45+
"id": 5,
46+
"prompt": "Finance may edit a contract's legal terms (`governing_law`, `liability_cap`) while it is a draft, but not once it is approved, signing or active. Legal still edits them.",
47+
"expected_output": "Field permission entries with a row condition on the finance set: `'clm_contract.governing_law': { readable: true, editable: false, when: \"status in ['approved', 'signing', 'active']\" }` and the same for `liability_cap`; the legal set keeps its edit grant. No validation rule and no `readonlyWhen`, which would lock the fields for every user.",
48+
"files": [],
49+
"assertions": {
50+
"must_contain": ["when:", "editable: false", "readable: true", "clm_contract.governing_law"],
51+
"must_not_contain": ["validations:", "readonlyWhen"]
52+
}
4353
}
4454
]
4555
}

‎skills/objectstack-data/rules/security.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,35 @@ bridge (warns). The compiler resolves these
116116
`owner_only_deletes`) and the object's `sharingModel` (ADR-0056 D1) over
117117
hand-written policies for the common cases.
118118

119+
## Field permissions — a row-conditioned edit lock (`when`)
120+
121+
A set's `fields` entry (`'OBJECT.FIELD': { readable, editable }`) may carry
122+
`when`, a row condition in the same canonical CEL as `rowLevelSecurity[].using`.
123+
**Choose by who loses the edit — one mechanism per need, never both:**
124+
125+
- Locked for **everyone** at that stage → a [validation rule](./validation.md)
126+
on the object (`readonlyWhen` likewise strips the write for everyone).
127+
- Locked for **some permission sets** only → `when` on the field entries of
128+
each set that loses the edit; the other sets keep their grant.
129+
130+
```typescript
131+
// finance may not change the contract's legal terms after approval
132+
fields: {
133+
'clm_contract.governing_law': { readable: true, editable: false, when: "status in ['approved', 'signing', 'active']" },
134+
}
135+
```
136+
137+
- **Edit vote only.** Reads are row-blind; `readable: false` beside `when` is
138+
refused at parse time.
139+
- **Same object.** Fields of the entry's object vs a literal or `current_user.*`;
140+
no relation reach (refused at `os validate` / publish).
141+
- **Pre-image.** An update is judged on the stored row, so a write cannot unlock
142+
itself by moving `status` back; an insert on the row as sent.
143+
- **Locks, never grants.** On unmatched rows the entry is absent; another held
144+
set's `editable: true` still wins (most-permissive merge).
145+
- Docs: https://objectstack.ai/docs/permissions/field-level-security#row-conditioned-edit-locks-when
146+
and the recipe https://objectstack.ai/docs/permissions/access-recipes#data-lock-fields-for-a-position-once-a-record-reaches-a-stage
147+
119148
## Sensitive fields — `secret` type + `requiredPermissions`
120149

121150
`maskingRule` is **live** (FieldMasker). Two more channels:

0 commit comments

Comments
 (0)