skills(data): optimization flight — hooks consolidated, generic patterns cut, sharingModel/Field.* /storage.notNull taught (net −9,044 tokens) (#14427)

* skills(data): consolidate hooks into references/data-hooks.md

DATA-B-01 / I-03 — rules/hooks.md called itself "a reference pointer" and then
restated five sections of the canonical file. Delete it; references/data-hooks.md
is the single hooks file and the catalog's hooks anchor. Its ceiling row is
dropped from scripts/check-skills-token-ratchet.mjs (the only edit to that file).

DATA-B-02  second H1 + "When to Use This Skill" inside a reference.
DATA-B-04  three registration methods, compact -- keeping the four load-bearing
           facts (AppPlugin auto-binds; the `functions` map; `packageId`; and
           that programmatic binding gets NO declarative condition/retry/
           timeout/onError/async semantics).
DATA-B-05  10+10 generic DO/DON'T -> the compact 5+5 rules/hooks.md carried.
DATA-C-03  vitest + LiteKernel harnesses -> one-line pointer to
           objectstack-platform, which claims that surface in its frontmatter.
DATA-D-01/02/03  invented benchmark table, plain-JS "Advanced Topics", generic
           Troubleshooting and the Summary that repeated the DO list verbatim.
           The References block survives, and absorbs the two cross-package
           pointers rules/hooks.md carried so no routing is lost.
DATA-D-04  patterns 1,2,4,5,7,9 (generic JS) deleted; 3,6,8,10 kept, renumbered.
DATA-E-04  the file prescribed `body` and demonstrated `handler` ten times: two
           surviving patterns are now sandboxed `body` with declared capabilities.

INC-03 (found while rewriting pattern 8, evidence pinned): "There is NO
`updateMany`" is true of the HANDLER-side repo -- ObjectRepository, what
ctx.api.object() returns, packages/objectql/src/engine.ts:13575-13600 -- but the
SANDBOX repo does install updateMany/deleteMany
(packages/runtime/src/sandbox/quickjs-runner.ts:544-545), exactly as this file's
own capability table says. The comment now names the surface it is true of.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

* skills(data): SKILL.md -- teach sharingModel/Field face, correct INC-01/02, cut restatement

Additions (all paid by deletions in this same file; SKILL.md 13892 -> 12535):
DATA-F-01  `sharingModel` row + the four canonical values. Used by 31/31 real
           objects and absent from both property tables. A publish with no
           authored sharingModel is refused (`security-owd-unset`, 422) --
           maintainer ruling 2026-08-13 recorded at
           packages/lint/src/authoring-rules.ts:1293-1296; enum at
           packages/spec/src/data/object.zod.ts:2177.
DATA-F-02  `required` (write contract) vs `storage: { notNull: true }` (the DDL),
           ADR-0113 -- never mentioned in the package before.
DATA-F-03  `icon` / `pluralLabel` / `highlightFields` rows.
DATA-F-04  four security lint rows; three are publish-blocking errors.
DATA-E-05  the Quick-Start Template now carries the face every real object has
           (pluralLabel/description/icon/highlightFields) and drops `indexes`,
           which appears in 1 of 26 corpus files.

INC-01 (HIGH) -- the schema-evolution table named `required` as the NOT NULL dial
and claimed dev auto-heals it. Both wrong: schema-drift.ts:795-798 compares
`field.storage?.notNull`, explicitly NOT `required`; the emitted op is
severity 'warning' / category 'needs_confirm' / 'relax_not_null' and the comment
says "never auto-applied"; sql-driver.ts:10746 applies only category 'safe'.
INC-02 (MED) -- the tell-tale promised a clean 400 "<field> is required".
schema-drift.ts:800-802: that configuration dies as a RAW DRIVER ERROR instead.

Deletions: DATA-A-03 (intro + when-to-use restating the frontmatter), DATA-C-01
(two verbatim error transcripts; the query skill carries the same 400 text),
DATA-C-04 (standalone tombstones -- each key is refused by a parse error
carrying its own prescription, and objectstack-upgrade owns that path),
DATA-C-05 (protection: schema + lock table + ONE example survive), DATA-D-12,
DATA-D-13, DATA-D-15, DATA-F-06, DATA-G-01 (one CLI spelling: `os`).

DATA-F-05 is a SHRINK, not a removal (retirement deferred pending #14296):
`defineObjectExtension` and `readScope`/`writeScope` each keep one
schema-pointing row -- zero corpus usage is evidence, not proof.

DATA-A-01/A-02/F-06 rewrite the frontmatter description: it never said
datasource / external / federated though rules/datasources.md is entirely that
surface, never said lifecycle or protection, and fired on `*.seed.ts` -- a
pattern that matches nothing in the repo.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

* skills(data): rules/ diet -- naming, indexing, validation, relationships, field-types

DATA-D-11 naming.md   six ❌/✅ pairs + Critical Rules restatements + Rationale for a
                      rule the regex in the table already states. 773 -> 248.
DATA-D-05/06/07       indexing.md: generic RDBMS 101 ("when to add indexes"), four
                      ❌/✅ pairs + three subsections teaching one textbook fact
                      (left-to-right) collapsed to one paragraph, the unsourced
                      `Table Size -> Max Indexes` table, the pg_stat_user_indexes /
                      SHOW INDEX SQL, and a 10-item Best Practices restating the
                      file. The naming block survives -- `name` is a declared key.
DATA-C-04             indexing.md's standalone `type`/`partial` tombstone clause;
                      the in-line ❌ block at "Retired and Redundant Keys" stays,
                      because there a wrong key sits beside the right one.
DATA-C-02 validation  CEL-vs-SQL is objectstack-formula's anchor and this package's
                      description already says to load it alongside. The INVERSION
                      rule stays -- it is validation-specific and lives nowhere else.
DATA-D-09/D-10        validation.md: five patterns restating four examples already on
                      the page; 10 best practices + 4 unsourced performance claims
                      about two rules that lower to the same CEL evaluator.
DATA-B-07             the "no `unique` validation type" rule was stated at 7 sites;
                      the restatements in validation.md and relationships.md go.
DATA-D-08             relationships.md Best Practices + Performance Considerations.
DATA-D-14/E-03/G-02   field-types.md: three ❌/✅ pairs duplicating naming.md, the type
                      table and a lint rule (the autonumber pair survives) pay for the
                      `Field.*` factory preamble -- the corpus is ~92% factory
                      (~250 calls vs 22 literals) and this file had zero `Field.*`.
DATA-E-02             two blocks carried an `import` and then opened `{` /
                      `validations: [` at statement position, which TS parses as a
                      labelled-statement block. Both are now real declarations.
DATA-E-01             `os:check` markers on the two self-contained SKILL.md blocks
                      that compile (definePermissionSet, the protection example).
                      Verified: `check:skill-examples` type-checks 261 marked blocks.

Two liveness-ledger bindings needed handling, both fallout of deleting rules/hooks.md
and the F-05 shrink:
  - the `### Access depth (scope-depth) …` heading is ledger-bound, so the shrink's
    incidental rename is reverted -- the ledger is right.
  - `hook-lifecycle-events-rule` binds a heading in the deleted file. The gate's own
    message prescribes "Re-point `heading`, or delete the row"; re-pointing would
    duplicate `hook-lifecycle-events-reference`, which already binds the same symbol
    (HookEvent) to the surviving canonical file, so the row is dropped. This is the
    one edit outside the declared file surface and it is reported as such.

`check:skill-docs` DEMANDED regeneration (it runs in CI, lint.yml:3986): the
frontmatter description changed, so `pnpm --filter @objectstack/spec gen:skill-docs`
regenerated skills/README.md and content/docs/ai/skills-reference.mdx. Generated
`references/_index.md` is untouched and `check:skill-refs` is green.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

* skills(data): ratchet DOWN the role-word baseline for SKILL.md (4 -> 2)

The DATA-C-04 / D-12 / D-13 deletions removed two role-word occurrences from
skills/objectstack-data/SKILL.md, so `pnpm check:role-word` failed as a
ratchet-DOWN: "role-word count improved 4 -> 2 — run
`node scripts/check-role-word.mjs --update` and commit the baseline". That
remedy is the author's own (baseline EXPANSION is the maintainer-only
direction), so the baseline is updated here. The diff is one line, for this
file only, and it shrinks.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

content/docs/ai/skills-reference.mdx

@@ -44,7 +44,7 @@ ObjectStack ships **11 skills** — one per authoring domain, plus process skill
 | # | Skill | Domain | Path | What it covers |
 | :--- | :--- | :--- | :--- | :--- |
 | 1 | [Platform](#platform) | `platform` | `skills/objectstack-platform/` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). |
-| 2 | [Data](#data) | `data` | `skills/objectstack-data/` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seeds (`defineSeed()`) that load fixtures and reference data alongside them. |
+| 2 | [Data](#data) | `data` | `skills/objectstack-data/` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security, data `lifecycle` retention/TTL/rotation, metadata `protection` locks, and external / federated datasources (`defineDatasource`) — and the seeds (`defineSeed()`) that load fixtures and reference data alongside them. |
 | 3 | [Query](#query) | `query` | `skills/objectstack-query/` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, relation expansion, and full-text search. |
 | 4 | [UI](#ui) | `ui` | `skills/objectstack-ui/` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). |
 | 5 | [Automation](#automation) | `automation` | `skills/objectstack-automation/` | Design ObjectStack automation — Flows (visual logic), Triggers, Approvals, state machines, scheduled jobs, and webhooks. |
@@ -75,9 +75,9 @@ Do not use for data schema design (see objectstack-data) or query patterns (see
 
 **Domain** `data` · **Path** `skills/objectstack-data/`
 
-Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seeds (`defineSeed()`) that load fixtures and reference data alongside them.
+Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security, data `lifecycle` retention/TTL/rotation, metadata `protection` locks, and external / federated datasources (`defineDatasource`) — and the seeds (`defineSeed()`) that load fixtures and reference data alongside them.
 
-Use when the user is creating or modifying `*.object.ts` / `*.seed.ts` files, picking field types, modelling relationships, writing `beforeInsert`/`afterUpdate` hooks, configuring per-object access control, or authoring bootstrap / demo data. Use for `visibleWhen` / `readonlyWhen` / `requiredWhen` rules that belong on fields.
+Use when the user is creating or modifying `*.object.ts` files or `src/data/*.ts` seed modules, picking field types, modelling relationships, writing `beforeInsert`/`afterUpdate` hooks, configuring per-object access control, pointing an object at an existing external database, or authoring bootstrap / demo data. Use for `visibleWhen` / `readonlyWhen` / `requiredWhen` rules that belong on fields.
 
 Do not use for querying data (see objectstack-query) or for plugin / kernel hooks (see objectstack-platform). CEL expressions in formulas / validations / sharing rules / dynamic seed values: load objectstack-formula alongside.
 

scripts/check-skill-identifier-liveness.mjs

@@ -306,14 +306,6 @@ const BINDINGS = [
     source: 'packages/spec/src/data/hook.zod.ts',
     why: 'The reference table of lifecycle events. A missing event is a hook an author never learns exists.',
   },
-  {
-    id: 'hook-lifecycle-events-rule',
-    file: 'skills/objectstack-data/rules/hooks.md',
-    heading: '### 8 Lifecycle Events',
-    symbol: 'HookEvent',
-    source: 'packages/spec/src/data/hook.zod.ts',
-    why: 'The heading states the count, so the section claims exhaustiveness in its own words — and the count goes stale silently when the enum grows.',
-  },
   {
     id: 'lifecycle-classes',
     file: 'skills/objectstack-data/rules/lifecycle.md',

scripts/check-skills-token-ratchet.mjs

@@ -404,7 +404,6 @@ export const CEILINGS = new Map([
   ['skills/objectstack-data/references/data-hooks.md', 12611],
   ['skills/objectstack-data/rules/datasources.md', 911],
   ['skills/objectstack-data/rules/field-types.md', 3584],
-  ['skills/objectstack-data/rules/hooks.md', 2195],
   ['skills/objectstack-data/rules/indexing.md', 3241],
   ['skills/objectstack-data/rules/lifecycle.md', 1590],
   ['skills/objectstack-data/rules/naming.md', 773],

scripts/role-word-baseline.json

@@ -36,7 +36,7 @@
   "skills/objectstack-ai/SKILL.md": 5,
   "skills/objectstack-api/SKILL.md": 1,
   "skills/objectstack-automation/SKILL.md": 1,
-  "skills/objectstack-data/SKILL.md": 4,
+  "skills/objectstack-data/SKILL.md": 2,
   "skills/objectstack-data/rules/relationships.md": 1,
   "skills/objectstack-platform/SKILL.md": 2,
   "skills/objectstack-query/rules/filters.md": 9,

skills/README.md

@@ -30,7 +30,7 @@ apps too).
 | Skill | Domain | What it covers |
 |:------|:-------|:---------------|
 | [Platform](./objectstack-platform/SKILL.md) | `platform` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). |
-| [Data](./objectstack-data/SKILL.md) | `data` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seeds (`defineSeed()`) that load fixtures and reference data alongside them. |
+| [Data](./objectstack-data/SKILL.md) | `data` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security, data `lifecycle` retention/TTL/rotation, metadata `protection` locks, and external / federated datasources (`defineDatasource`) — and the seeds (`defineSeed()`) that load fixtures and reference data alongside them. |
 | [Query](./objectstack-query/SKILL.md) | `query` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, relation expansion, and full-text search. |
 | [UI](./objectstack-ui/SKILL.md) | `ui` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). |
 | [Automation](./objectstack-automation/SKILL.md) | `automation` | Design ObjectStack automation — Flows (visual logic), Triggers, Approvals, state machines, scheduled jobs, and webhooks. |