@@ -0,0 +1,10 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): objectstack-data carries the metadata-authoring judgment the hosted build agent learned — booleans, people fields, dynamic defaults, process modelling, roll-up qualifiers, seed values, labels, sharing posture
+
+Clause-②: no
+Metadata-protocol: none
+
+Card 1 of the cloud#3659 ruling A split: one source of metadata-authoring knowledge for every build channel. This is the `objectstack-data` port — the judgment the schema cannot express and the published skill did not yet state. `SKILL.md`: a yes/no flag is `{ type: 'boolean', defaultValue: false }` and never `required` ("must be accepted" is a validation rule); a person on the record is `type: 'user'`, optional unless asked; a dynamic default resolves on save and is described as such; record status is a `select` with a `state_machine`, never a status table; approvals, routing and audit trails are not objects; the record owner is the platform `owner_id`, never a hand-added lookup, and `ownership: 'none'` is only for catalogs and junctions; the `sharingModel` posture is chosen from the request; a `state_machine` declares `initialStates` whenever the status has a real start. `rules/relationships.md`: pick the roll-up function from the words, put every qualifier in `summaryOperations.filter` (dropped, it is a plausible wrong total), a rate is a formula over a working summary, and the recompute runs only on a child write — a summary declared after its rows exist is backfilled by `os migrate summary-nulls --apply`; its examples take the posture the paragraph teaches. `rules/validation.md`: the canonical `state_machine` example declares `initialStates`. `rules/naming.md`: labels follow the user's language. `references/seeds.md`: seed values may be fictional, never malformed — `os validate` / `os build` refuse a malformed one first. Eight eval cases pin the teachings (objects-fields-relationships 10–14, hooks-security-seeds-datasources 14–16).
@@ -539,7 +539,33 @@ export const CEILINGS = new Map([
   // 6123 -> 6078: re-locked at the landed count. The rule index's `rules/lifecycle.md`
   // entry names the save notice (+16); the `lifecycle` property row dropped the
   // bounding-policy clause that entry and `rules/lifecycle.md` already carry (-25).
-  ['skills/objectstack-data/SKILL.md', 6078],
+  // 6078 -> 6665 (#31155, card 1 of the cloud#3659 ruling-A split): the
+  // metadata-authoring judgment the hosted build agent carried privately, now
+  // the one published source — the `sharingModel` posture chosen from the
+  // request; a yes/no flag is `defaultValue: false` and never `required`; a
+  // person on the record is `type: 'user'`, optional unless asked; a dynamic
+  // default resolves on save; three Relationship Patterns rows (status is a
+  // `select`, never a table; approvals and audit trails are not objects; the
+  // owner is the platform `owner_id`, `ownership: 'none'` only for catalogs and
+  // junctions); a `state_machine` declares `initialStates`. Paid down first,
+  // two restatements in this file: the `unique`-validation blockquote restated
+  // `rules/validation.md` § Uniqueness and is a one-line pointer now; the
+  // `secret` / `user` parentheticals restated `rules/field-types.md` rows 42-43
+  // and 96 and are gone; the contract-review round then cut the `initialStates`
+  // mechanic sentence (a restatement of `validation.zod.ts`'s describe) and
+  // aligned the conditional-rules `invoice` example with the posture paragraph;
+  // the approver's round then put the two example phrases into English (the
+  // shipped skill text is English-only; eval prompts are exempt).
+  // Arithmetic in priced bytes (stamp line excluded), against `main`'s 24308:
+  // 24308 -> 26658 (+2350 net) -> ceil(26658 / 4) = 6665; headroom was 1
+  // token, so the ceiling moves +587, pinned AT the measurement. Authorised by
+  // the ruling of record that orders this text into the published skills:
+  // objectstack-ai/cloud#3659, letter A, maintainer 「A」 (ruling comment
+  // 6682024726, 2026-11-06): "How to write valid, working metadata lives in the
+  // public skills … The private corpus's rules of that kind move there". The
+  // raise path is the standing 2026-10-27 ruling, verbatim and untranslated:
+  // 「A:先削重复,余额按实测提高」 (ruling record 6513306068).
+  ['skills/objectstack-data/SKILL.md', 6665],
   ['skills/objectstack-formula/SKILL.md', 5997], //     -53 (was 6055), then -5 A2′ (was 6002)
   ['skills/objectstack-i18n/SKILL.md', 6333], //        -11 (was 6349), then -5 A2′ (was 6338)
   // 12705 -> 12984 (2026-08-31 app-repo-principles raise, see the block above).
@@ -750,7 +776,30 @@ export const CEILINGS = new Map([
   // +201 tokens on a landed 3672, 4 absorbed by headroom, ceiling +197. No
   // repeated passage to cut first (measured: no sentence repeats). Maintainer ruling 2026-10-27 on the decision card 「skills 修复卡的教学和 eval 都撞 token 天
   // 花板,怎么付?」, tap A, verbatim and untranslated: 「A:先削重复,余额按实测提高」.
-  ['skills/objectstack-data/rules/relationships.md', 3873],
+  // 3873 -> 4127 (#31155, card 1 of the cloud#3659 ruling-A split): the
+  // Roll-up Summaries `filter` paragraph is REWRITTEN, not appended to — pick
+  // the function from the words, every qualifier goes in `filter` (dropped, a
+  // plausible wrong total), one child feeds several totals, a rate is a
+  // formula over a working summary; and the recompute runs only on a child
+  // write, so a summary declared after its rows exist is backfilled by
+  // `os migrate summary-nulls --apply`, never by editing a child. Five example
+  // objects take the posture the new SKILL.md paragraph teaches
+  // (`public_read_write` on account / contact / invoice / the junction,
+  // `public_read` on the category table). Paid down first: the `engagement`
+  // signup/click example and the "aggregate only a subset" lead-in (both
+  // restated by the kept `procurement_receipt` example), the `filter` code
+  // comment's second line (the paragraph says it), and the child-field half of
+  // the `filter` sentence (an enforce-or-remove row for the spec lane,
+  // #31224 D, not prose). The approver's round then put the roll-up passage's
+  // example phrases into English (the shipped skill text is English-only).
+  // Arithmetic in bytes against `main`'s re-locked 15489:
+  // 15489 -> 16505 (+1016 net) -> ceil(16505 / 4) = 4127; headroom was 0, so
+  // the ceiling moves +254, pinned AT the measurement. Authorised by the ruling
+  // of record that orders this text into the published skills:
+  // objectstack-ai/cloud#3659, letter A, maintainer 「A」 (ruling comment
+  // 6682024726); raise path the 2026-10-27 ruling 「A:先削重复,余额按实测提高」
+  // (ruling record 6513306068).
+  ['skills/objectstack-data/rules/relationships.md', 4127],
   // NEW FILE (#14296 item 1 = A, condition (b)): the entry's Security & Access
   // Control block moved here whole. Pinned at its landed count — no headroom,
   // because a split that arrives with budget is a raise wearing a new path.
@@ -821,7 +870,17 @@ export const CEILINGS = new Map([
   // 3109 -> 2756: RE-LOCK at the landed count (#19715, card item 4). A 5-line
   // table of contents (+155 tokens) landed inside the row's 508 tokens of
   // headroom, so no raise; pinned AT the measurement — zero headroom.
-  ['skills/objectstack-data/rules/validation.md', 2756],
+  // 2756 -> 2761 (#31155): the canonical `state_machine` example gains
+  // `initialStates: ['draft']` so the example no longer undercuts the rule
+  // SKILL.md § Validation Patterns teaches (ordered by the contract review on
+  // PR #31223). Paid down first: the "(removed from the spec)" aside in the
+  // no-`unique` list item, restated by § Uniqueness below it (-24 bytes).
+  // Arithmetic in bytes: 10992 -> 11044 (+52 net) -> ceil(11044 / 4) = 2761;
+  // headroom was 8 tokens, so the ceiling moves +5, pinned AT the
+  // measurement. Same authority as the three rows above: cloud#3659 letter A
+  // (ruling comment 6682024726); raise path 「A:先削重复,余额按实测提高」
+  // (ruling record 6513306068).
+  ['skills/objectstack-data/rules/validation.md', 2761],
 
   // objectstack-platform
   ['skills/objectstack-platform/references/plugin-hooks.md', 2628],
@@ -1099,7 +1158,20 @@ export const CEILINGS = new Map([
   // tokens at headroom 0, ceiling +267. No repeated passage to cut first
   // (measured: no sentence repeats). Maintainer ruling 2026-10-27 on the decision card 「skills 修复卡的教学和 eval 都撞 token 天
   // 花板,怎么付?」, tap A, verbatim and untranslated: 「A:先削重复,余额按实测提高」.
-  ['skills/objectstack-data/references/seeds.md', 1566],
+  // 1566 -> 1747 (#31155, card 1 of the cloud#3659 ruling-A split): one
+  // paragraph under Seed best practices — a seed row passes the same field
+  // validation as a user's insert, so a masked or placeholder value never
+  // lands and the table loads short; `os validate` / `os build` refuse it
+  // first, at the record's field; invent a well-formed fictional value,
+  // never downgrade the field type. No repeated passage to cut first
+  // (measured: the file said nothing about seed values). Arithmetic in bytes:
+  // 6240 -> 6985 (+745) -> ceil(6985 / 4) = 1747; headroom was 6 tokens, so
+  // the ceiling moves +181, pinned AT the measurement. Authorised by the ruling
+  // of record that orders this text into the published skills:
+  // objectstack-ai/cloud#3659, letter A, maintainer 「A」 (ruling comment
+  // 6682024726); raise path the 2026-10-27 ruling 「A:先削重复,余额按实测提高」
+  // (ruling record 6513306068).
+  ['skills/objectstack-data/references/seeds.md', 1747],
   ['skills/objectstack-platform/references/bootstrap.md', 1351],
   // 3108 -> 3287: `os deploy`, the managed-package dev loop — when to deploy
   // rather than publish a release, its entry points, how it picks the
 
@@ -75,6 +75,14 @@ the publish door rejects it before that:
 | `public_read_write` | everyone reads and writes |
 | `controlled_by_parent` | inherited from the master record (`master_detail` children); a row with no (optional) master is its owner's |
 
+Choose the posture from the request, not by habit: a business object a team
+shares is `public_read_write` (`private` would hide every colleague's records
+from everyone else); `private` fits personal or sensitive data only its owner
+should see (HR reviews, pay, personal notes); `public_read` fits reference data
+everyone reads and the owner maintains (price lists, policies, notices). This
+axis is distinct from `ownership`, which decides whether `owner_id` exists at
+all (Relationship Patterns below).
+
 **Important optional properties:**
 
 | Property | Default | Description |
@@ -175,7 +183,7 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const Invoice = ObjectSchema.create({
   name: 'invoice',
-  sharingModel: 'private',
+  sharingModel: 'public_read_write',
   fields: {
     status: Field.select({
       options: [
@@ -275,11 +283,25 @@ lowercase option values — incorrect/correct examples: [rules/naming.md](./rule
 ### Field Type Selection
 
 The full table, per-type config and traps: [rules/field-types.md](./rules/field-types.md).
-From here, three to get right: credentials are `secret` (reversible, **encrypted-at-rest**
-via the registered `ICryptoProvider`, masked on read, fail-closed, ADR-0100) — never
-`password`, which on a generic object is **plaintext at rest**; `user` is a person picker
-(a lookup specialized to `sys_user`, stored identically to `lookup`); `formula` takes CEL in
-`expression` (`F\`...\`` from `@objectstack/spec`; see **objectstack-formula**).
+From here, three to get right: credentials are `secret` (**encrypted-at-rest**, ADR-0100) —
+never `password`, which on a generic object is **plaintext at rest**; `user` is the person
+picker; `formula` takes CEL in `expression` (`F\`...\`` from `@objectstack/spec`; see
+**objectstack-formula**).
+
+- A yes/no flag (`is_*`, `has_*`, "done?", "active?") is `{ type: 'boolean', defaultValue: false }`
+  and never `required`: a checkbox always holds one of its two values, so
+  `required` can only read as "must be true", and a form that reads it that way
+  refuses the unchecked state — the one state a new record starts in. "Must be
+  accepted" (terms, a confirmation) is a `validations[]` rule, not `required`.
+  The default also lands seeded or imported rows that omit the column on a real
+  `false` instead of a null that only looks unchecked.
+- A person on the record (assignee, approver, reviewer) is `type: 'user'` with
+  no `reference`, and optional unless the request says otherwise — the platform
+  already stamps the owner and `created_by`.
+- A dynamic default (`defaultValue: 'current_user'`, `'NOW()'`, a CEL envelope)
+  resolves when the record is SAVED with the field empty. Describe it as
+  save-time; whether a create form pre-displays it is a client capability you
+  cannot promise.
 
 ### Relationship Patterns
 
@@ -290,6 +312,9 @@ via the registered `ICryptoProvider`, masked on read, fail-closed, ADR-0100) —
 | Many-to-Many (simple) | multi-value `lookup` (`multiple: true`) — an **array column** of ids |
 | Many-to-Many (with attributes) | Junction object with two `lookup` fields |
 | Hierarchical | `tree` field (self-reference) |
+| Record status / lifecycle | a `select` on the business object (plus a `state_machine` validation) — never a separate status / stage / step table |
+| Approval, review, routing, audit trail | not objects: an approval is a flow node (**objectstack-automation**) and its trail is platform history; model only the people it references (approver, reviewer), as `user` fields beside the owner |
+| Record owner | the platform's `owner_id` (`ownership: 'user'`, the default) — never a hand-added "owner" / "person in charge" lookup, a second owner that owner-scoped visibility and "My records" views never read; `ownership: 'none'` only for a shared catalog or a pure junction table |
 
 > **`multiple: true` lookup ≠ junction object.** A multi-value lookup
 > (`{ type: 'lookup', reference: 'x', multiple: true }`) is stored and read as an
@@ -309,10 +334,14 @@ via the registered `ICryptoProvider`, masked on read, fail-closed, ADR-0100) —
 The **complete** set of types (`ValidationRuleSchema` discriminators): `script`,
 `state_machine`, `format`, `cross_field`, `json_schema`, `conditional`.
 
-> **There is NO `unique` validation type** (removed from the spec).
-> Enforce uniqueness — including composite — with a **unique index**, and state
-> its scope (ADR-0120):
-> `indexes: [{ fields: ['department', 'email'], unique: 'organization' }]`.
+A `state_machine` rule also declares `initialStates` whenever the status has a
+real starting point — without it a record can be created already `approved` /
+`paid` and walk past the process. List only the genuine entry states (usually
+one: `draft` / `pending` / `new`), never a terminal one; keys and values are
+option `value`s, never labels.
+
+> **There is NO `unique` validation type** — uniqueness is a unique **index**
+> with its scope (ADR-0120; [rules/validation.md § Uniqueness](./rules/validation.md#uniqueness--use-unique-indexes)).
 
 See [rules/validation.md](./rules/validation.md) for all types and examples.
 
 
@@ -130,6 +130,36 @@
         "must_contain": ["condition:", "record.annual_revenue != null", "record.annual_revenue > 1000000"],
         "must_not_contain": []
       }
+    },
+    {
+      "id": 14,
+      "prompt": "Seed eight demo members for the gym app. For privacy, mask the phone numbers like `138****4207` and put `N/A` where we have no email.",
+      "expected_output": "A `defineSeed(Member, { env: ['dev', 'test'], records: [...] })` whose every value is fictional but WELL-FORMED: `+86 138 0013 8000`-style phones, `liyy@example.com`-style emails, option VALUES for selects. Explains that a seed row passes the same field validation as a user's insert, so a masked phone or an `N/A` email is refused and never lands — the table loads short or empty while bookings point at members that do not exist. Does not downgrade the `phone` field to `text` to make the rows load.",
+      "files": [],
+      "assertions": {
+        "must_contain": ["defineSeed", "+86 138", "@example.com"],
+        "must_not_contain": ["****", "'N/A'", "type: 'text', label: 'Phone'"]
+      }
+    },
+    {
+      "id": 15,
+      "prompt": "报销单：申请人默认是当前用户，还有一个审批人和一个复核人。",
+      "expected_output": "`applicant`, `approver` and `reviewer` are `type: 'user'` fields (the person picker — no `reference`, never a `lookup` to a user object you invent); `applicant` carries `defaultValue: 'current_user'`; none is `required`, since the request does not ask for it and the platform already stamps the owner and `created_by`. Describes the default as SAVE-time — 「保存后申请人会自动填为当前用户；表单里这一栏可能显示为空，留空提交即可」 — and does not promise the create form pre-fills it.",
+      "files": [],
+      "assertions": {
+        "must_contain": ["type: 'user'", "defaultValue: 'current_user'"],
+        "must_not_contain": ["reference: 'sys_user'", "reference: 'user'", "{ type: 'user', required: true }", "会自动预填"]
+      }
+    },
+    {
+      "id": 16,
+      "prompt": "Two objects: performance reviews that only the reviewed person's manager and HR may see, and a price list everyone can read but only finance maintains.",
+      "expected_output": "`performance_review` is `sharingModel: 'private'` (owner-only by default, widened to the manager and HR with sharing rules / RLS in a permission set, rules/security.md); `price_list` is `sharingModel: 'public_read'` (everyone reads, the owner writes) with finance as its owners. Neither is `public_read_write`, the posture for an ordinary shared business object — the posture is chosen from the request, not by habit. No `permissions` key on the object.",
+      "files": [],
+      "assertions": {
+        "must_contain": ["sharingModel: 'private'", "sharingModel: 'public_read'"],
+        "must_not_contain": ["sharingModel: 'public_read_write'", "permissions:"]
+      }
     }
   ]
 }