Skip to content

Commit 7c1eeb1

Browse files
docs(skills): the objectstack-data skill leads a hook author to the save notice (#30947)
<!-- claude-projects-attribution: {"github_login":"os-tesla"} --> _Requested by **Tesla** · [project thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6JaoFJX6bqYge66A6RmcwQVyv1)_ Fixes #28819 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:`objectstack-data` 技能的规则索引里,`rules/lifecycle.md` 条目补上「保存提示」(`ctx.notice`)一句;`references/data-hooks.md` 的沙箱 `ctx.*` 表与 `HookContext` 清单各加一行 `notice`,都指向 `rules/lifecycle.md` § Save Notice。新增全部用同文件内删除重复叙述来付账,两行 token 棘轮按落地读数下调(6123→6078、10066→10011)。 - 为什么改:保存提示的教学已在 `rules/lifecycle.md`,但索引把该页写成只讲数据保留,钩子参考里又没有 `notice`,写保存钩子的作者从本技能进来找不到它。 - 风险与回滚:只改技能文本与棘轮上限,不改运行时;若有误,revert 本 PR 即可。 - 先看:`skills/objectstack-data/references/data-hooks.md`(新增的 `ctx.notice` 行、`notice?` 成员,以及被删的三段)、`skills/objectstack-data/SKILL.md` 第 45 行与 `lifecycle` 属性行、`scripts/check-skills-token-ratchet.mjs` 两行下调。 - 两分钟验证:`node scripts/check-skills-token-ratchet.mjs | grep objectstack-data/`,预期 `SKILL.md is 6078 tokens (ceiling 6078; headroom 0)` 与 `data-hooks.md is 10011 tokens (ceiling 10011; headroom 0)`。 - 需要你做的:`skills/**` 为 Tier H,席位契约复审通过后由你批准合并。 ## What changes **`skills/objectstack-data/SKILL.md` — the rule index (L45).** The `rules/lifecycle.md` entry gains one clause: "plus the **save notice** a hook hands the saver (`ctx.notice`)". The "distinct from lifecycle *hooks* below" parenthesis stays, since the page is still the retention page, and now also where the save notice is taught. - Paid by: the `lifecycle` row of the optional-properties table dropped "— a `telemetry`/`transient`/`event`/`audit` class must declare a bounding policy or parsing fails", which the index entry one screen above already states ("❗ append-only objects must declare one") and `rules/lifecycle.md` § Validation Rules carries with the refused shapes. The row keeps the bolded requirement and its link. - The Verify section is untouched (queued card #30893 owns it). **`skills/objectstack-data/references/data-hooks.md` — two rows.** - Sandbox `ctx.*` table: a `ctx.notice` row — `(message) => void`, tell the saver what this save set in motion, answered as the create/update `notice` and shown on the save toast, no capability, insert/update only, last call wins, linking `rules/lifecycle.md` § Save Notice. Every word is read off `main`: `HookContextSchema.notice` (`packages/spec/src/data/hook.zod.ts`, "no capability token", "last call before the write answers wins", "present on every insert/update dispatch", "absent on find and delete"), the body runner's hand-over (`packages/runtime/src/sandbox/body-runner.ts`, `notice: engineCtx.notice`) and the VM bridge (`packages/runtime/src/sandbox/quickjs-runner.ts`, "No capability gate"). - `HookContext` listing: `notice?: (message: string) => void; // Save notice — rules/lifecycle.md § Save Notice`, beside `api?`, matching the spec's optional member and `HookNoticeSetter`. - Paid by three same-file deletions of restated prose: 1. In the `body` section intro, "and the one that was previously undocumented (you had to reverse-engineer `@objectstack/runtime` to use it)" — history of the page, not a rule; the sentence keeps "the one a metadata-only runtime actually executes". 2. The blockquote "The former `ctx.session.tenantId` alias was removed in v16 … (The generic driver-layer `execCtx.tenantId` / `DriverOptions.tenantId` isolation knob is a separate axis and is unaffected.)" — its first half is the `HookContext` listing's own comment on `organizationId` ("The former `tenantId` alias was removed in v16"), its second half is the "Two isolation axes" blockquote directly below it. 3. The paragraph "`ctx.user` is the ergonomic shortcut for an authenticated caller; it is `undefined` for system / unauthenticated writes, so read `ctx.session?.organizationId` when a hook must work regardless of whether a user resolved." — the `ctx.user` table row and the listing's comment both say "`undefined` for system / unauthenticated writes", and the code line right above it (`ctx.user?.organizationId ?? ctx.session?.organizationId`) is the fallback it describes. **`scripts/check-skills-token-ratchet.mjs`** — both rows re-locked DOWN at the landed counts (`6123 → 6078`, `10066 → 10011`), each with a comment naming what paid for what. No ceiling rises. **Changeset:** `.changeset/28819-save-notice-discoverable.md`, `'@objectstack/skills': patch`, with both declaration lines. ### Skill bundle readings (`skills/**` touched) | | before (`origin/main` 4d56914) | after (`79305e90`, same bytes as `6edbf15a`) | |:---|---:|---:| | `skills/objectstack-data/SKILL.md` | 465 lines · 6087 tokens | 465 lines · 6078 tokens | | `skills/objectstack-data/references/data-hooks.md` | 973 lines · 10056 tokens | 965 lines · 10011 tokens | | all 11 `SKILL.md` in `skills/` | 4525 lines · 56670 tokens | 4525 lines · 56661 tokens | Tokens are the gate's own convention, `ceil(utf8 bytes / 4)`, with the 20-byte `version:` stamp line unpriced on a `SKILL.md`. ## Tests Prose only, so no package test and no ablation (the ablation rule excludes docs). The teaching was checked against `main`'s code, not memory: - `node scripts/check-skills-token-ratchet.mjs --self-test` — `97 cases pass`, exit 0. - `node scripts/check-skills-token-ratchet.mjs` — both edited rows report `headroom 0`, exit 0. - `skills/objectstack-data/evals/` has no runner in this tree (`skills/README.md` L74: the fixtures are scored by maintainers); the two JSON fixtures are not touched and the ratchet still measures them (1753 / 1749 tokens, not ratcheted). ## Acceptance notes - The `ctx.notice` row sits between `ctx.crypto` and `ctx.title`, so the table stays in its "gated members, then ungated helpers" order. - Not a defect: `HookContext.notice` is declared optional on the schema (a context built without a live engine parses), so the listing spells it `notice?:`, like `api?:`. - Out of scope, noted only: the optional-properties table and the rule index both still describe `lifecycle` twice (row + index entry); that duplication predates this PR and pays for it here, nothing more was cut. ## Verification <details><summary>Derived gates: 64 derived, 63 run green, 1 NOT MEASURED (head 6edbf15)</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 64 commands at `6edbf15a`. Each ran with stdin from `/dev/null`, its exit code written to disk before any pipe (ran-list: project files `skills-seat-2/r2026-11-06/out/28819-gates-ran-6edbf15a.list`). - 63 exit 0, among them `check-skills-token-ratchet` (+ `--self-test`, 97 cases), `check:skill-identifier-liveness`, `check:skill-frame-sync`, `check:skill-compatibility`, `check:pm-skill-id-lint`, `check:doc-authoring`, `check:role-word`, `check:nul-bytes`, `check:changeset-gate-self-tests`, `check-empty-changeset --base origin/main`, `check-adr-0087-registration --base origin/main`, `check-changeset-no-major --base origin/main`, `check:pm-governed-merges`, `check:pm-dispatch-gates`, `@objectstack/spec check:skill-docs` and `check:skill-refs`, `@objectstack/lint check:doc-formula-expressions`. - `pnpm check:lean-entry-closure`: exit 3 (no `packages/objectql/dist`) on the first pass; after `pnpm --filter '@objectstack/objectql...' build` under the verify lock it exits 0 ("Admitted set held exactly (15 packages)"). The ran-list carries the 0. - `pnpm check:dual-build-cjs-loads`: exit 3, PREREQUISITE NOT MET — it loads every published package's dist (89 absent). **NOT MEASURED** locally; the diff touches no package it loads, and CI's `Lint & Repo Gates` runs it. Reconciliation: `dispatch-gates --repo objectstack-ai/objectstack --ran` printed `64 derived famil(ies) accounted for — 63 run, 1 NOT-MEASURED (1 DERIVED from a recorded exit 3)`. Head `79305e90` is `6edbf15a` merged with `origin/main` 33043bd (one i18n commit, no file in common). On the merged head the base-sensitive families re-ran green: `check-skills-token-ratchet`, `check-empty-changeset --base origin/main`, `check-adr-0087-registration --base origin/main`, `check-changeset-no-major --base origin/main`, `check:skill-identifier-liveness`, all exit 0; the four changed files and their bytes are identical to `6edbf15a`. Prerequisite builds, both under `scripts/pm/os-verify-lock.sh`: `pnpm --filter '@objectstack/lint...' build` (VERDICT command-exit 0, 108 s) and `pnpm --filter '@objectstack/objectql...' build` (VERDICT command-exit 0, 150 s). </details> Tier H by path (`skills/**`). It stays a draft: the seat runs the at-tier contract review, then the maintainer approves and merges. --- _Generated by [Claude Code](https://claude.ai/code/session_01L9qibx4SVi1CLmwbLz82b7)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 1aeeafd commit 7c1eeb1

4 files changed

Lines changed: 30 additions & 17 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): the objectstack-data skill now leads a hook author to the save notice
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The `objectstack-data` rule index described `rules/lifecycle.md` as retention-only, and `references/data-hooks.md` listed no `notice` member, so an author writing a save hook from this skill never found `ctx.notice(message)`. The index entry now names the save notice, and the sandbox `ctx.*` table and the `HookContext` listing each carry a `notice` row that points at `rules/lifecycle.md` § Save Notice. Growth is paid by same-file deletions of restated prose; both token-ratchet rows are re-locked down at the landed counts.

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

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -510,7 +510,10 @@ export const CEILINGS = new Map([
510510
// shrank to 689 characters (card item 3). One pointer line per moved block.
511511
// 6128 -> 6123: A2′ — the release-stamp line left the count (see
512512
// STAMP_LINE_REPIN); the file's count fell by the same 5, headroom unchanged.
513-
['skills/objectstack-data/SKILL.md', 6123],
513+
// 6123 -> 6078: re-locked at the landed count. The rule index's `rules/lifecycle.md`
514+
// entry names the save notice (+16); the `lifecycle` property row dropped the
515+
// bounding-policy clause that entry and `rules/lifecycle.md` already carry (-25).
516+
['skills/objectstack-data/SKILL.md', 6078],
514517
['skills/objectstack-formula/SKILL.md', 5997], // -53 (was 6055), then -5 A2′ (was 6002)
515518
['skills/objectstack-i18n/SKILL.md', 6333], // -11 (was 6349), then -5 A2′ (was 6338)
516519
// 12705 -> 12984 (2026-08-31 app-repo-principles raise, see the block above).
@@ -678,7 +681,14 @@ export const CEILINGS = new Map([
678681
// headings); the row carried 2,727 tokens of headroom left by an earlier
679682
// shrink that nobody re-locked, so the TOC needed no raise. Pinned AT the
680683
// measurement — zero headroom, the ratchet's steady state.
681-
['skills/objectstack-data/references/data-hooks.md', 10066],
684+
// 10066 -> 10011: re-locked at the landed count (main measured 10056; the
685+
// move is -45). A `ctx.notice` row in the sandbox table and a `notice?` member
686+
// in the HookContext listing, paid by same-file restatements: the
687+
// reverse-engineering aside in the `body` intro, the `tenantId` blockquote
688+
// (its two halves live in the listing comment and the two-axes note, which
689+
// now names the two `tenantId` symbols), the `ctx.user` paragraph under the
690+
// `??` line that shows it, and the `session.roles` history clause.
691+
['skills/objectstack-data/references/data-hooks.md', 10011],
682692
['skills/objectstack-data/rules/datasources.md', 911],
683693
// -552 (was 3584): re-locked at the landed count (#16374) after PR #16187
684694
// (the two `tree` rows) and PR #16369 (the ASCII decision tree deleted)

‎skills/objectstack-data/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ Detailed rules, with incorrect/correct examples:
4242
- **[Relationships](./rules/relationships.md)** — lookup vs master_detail, junction patterns, delete behaviors
4343
- **[Validation Rules](./rules/validation.md)** — All validation types, script inversion, severity levels
4444
- **[Index Strategy](./rules/indexing.md)** — btree/gin/gist/fulltext, composite indexes, partial indexes
45-
- **[Data Lifecycle & Retention](./rules/lifecycle.md)** — `lifecycle` classes (record/audit/telemetry/transient/event), retention/TTL/rotation/archive policies; ❗ append-only objects must declare one (distinct from lifecycle *hooks* below)
45+
- **[Data Lifecycle & Retention](./rules/lifecycle.md)** — `lifecycle` classes (record/audit/telemetry/transient/event), retention/TTL/rotation/archive policies; ❗ append-only objects must declare one (distinct from lifecycle *hooks* below); plus the **save notice** a hook hands the saver (`ctx.notice`)
4646
- **[Lifecycle Hooks](./references/data-hooks.md)** — the lifecycle events, `handler` vs sandboxed `body` (ctx + capability contract), registration, canonical patterns
4747
- **[Datasources & Federation](./rules/datasources.md)** — `defineDatasource`, external/federated objects (`remoteName`/`columnMap`), auto-connect gating, credentials; ❌ no `field.columnName` on external objects
4848
- **[Security & Access Control](./rules/security.md)** — permission sets, assignment rows, RLS policies, `secret` / `requiredPermissions`, `tenancy`, platform-global posture
@@ -90,7 +90,7 @@ the publish door rejects it before that:
9090
| `titleFormat` | — | **Refused (ADR-0079)**: a save and `os validate` refuse it (`title-format-retired`). Move it to `nameField`; a composite title follows the `nameField` row |
9191
| `enable` | — | Capability flags (trackHistory, searchable, apiEnabled, etc.) |
9292
| `fieldGroups` | — | Ordered list of logical field groups for forms/detail pages (see [Field Groups](./references/examples-objects.md#field-groups-mvp)) |
93-
| `lifecycle` | `record` semantics (permanent) | Data retention/rotation/archival contract. **Required for append-only, high-write-rate objects** — a `telemetry`/`transient`/`event`/`audit` class must declare a bounding policy or parsing fails (see [Data Lifecycle & Retention](./rules/lifecycle.md)) |
93+
| `lifecycle` | `record` semantics (permanent) | Data retention/rotation/archival contract. **Required for append-only, high-write-rate objects** (see [Data Lifecycle & Retention](./rules/lifecycle.md)) |
9494

9595
### Object Capabilities (`enable`)
9696

‎skills/objectstack-data/references/data-hooks.md‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -310,9 +310,7 @@ onError: 'log'
310310

311311
A hook can carry its logic in one of two shapes. Everything above this point
312312
showed the inline **`handler`** function; the section below documents the
313-
**`body`** form — the one a metadata-only runtime actually executes, and the one
314-
that was previously undocumented (you had to reverse-engineer
315-
`@objectstack/runtime` to use it).
313+
**`body`** form — the one a metadata-only runtime actually executes.
316314

317315
### `body` (sandboxed) vs `handler` (inline) — pick one
318316

@@ -360,12 +358,13 @@ The sandbox is handed a **JSON snapshot** of these (built by
360358
| `ctx.previous` | object \| `undefined` | Pre-write record on update/delete. **`undefined` on insert** → use `!ctx.previous` to detect *create*. |
361359
| `ctx.result` | object \| `undefined` | `after*` only. ⚠️ **partial** on afterUpdate — see gotcha 1. |
362360
| `ctx.user` | object \| `undefined` | `{ id, name, email, organizationId }`. `undefined` for system / unauthenticated writes. |
363-
| `ctx.session` | object \| `undefined` | `{ userId, organizationId, isSystem, … }`. **No role list** — `session.roles` was retired in 17.0.0: it was declared but never produced, so every read was `undefined`. |
361+
| `ctx.session` | object \| `undefined` | `{ userId, organizationId, isSystem, … }`. **No role list** — `session.roles` was retired in 17.0.0 (declared, never produced). |
364362
| `ctx.event` | string | e.g. `'afterUpdate'` — dispatch on it when one hook subscribes to several events. |
365363
| `ctx.object` | string | The target object name. |
366364
| `ctx.api` | object | Cross-object CRUD. Gated by `api.read` / `api.write` — see below. |
367365
| `ctx.log` | `{ debug, info, warn, error }` | Gated by `log`. Call **`ctx.log.info(msg, data?)`** — `ctx.log` is an **object, not** callable as `ctx.log(msg)`. Emission is **best-effort** (see Troubleshooting). |
368366
| `ctx.crypto` | `{ randomUUID }` | Gated by `crypto.uuid`. |
367+
| `ctx.notice` | `(message) => void` | **Tell the saver what this save set in motion** — answered as the create/update `notice`, shown on the save toast. No capability; insert/update only; last call wins. [`rules/lifecycle.md` § Save Notice](../rules/lifecycle.md#save-notice). |
369368
| `ctx.title` | `(field?) => Promise<string \| null>` | **Name the record, not its id.** `ctx.title()` resolves this object's `nameField`, a **formula** included (no extra read); `ctx.title('account_id')` resolves a lookup's title (needs `api.read`). `null` when there is no title, never the id. **Per door:** `body` has it; a deprecated `handler` gets it at runtime, undeclared on `HookContext` (TS2339 when annotated) — use `body`; `ql.registerHook` and a bare `ObjectQL` `bindHooks` lack it. |
370369

371370
(Action bodies additionally receive `ctx.recordId` and `ctx.record`, and their
@@ -599,6 +598,7 @@ interface HookContext {
599598
// Engine access
600599
ql: IDataEngine; // ObjectQL engine instance
601600
api?: ScopedContext; // Cross-object CRUD API
601+
notice?: (message: string) => void; // Save notice: rules/lifecycle.md § Save Notice
602602

603603
// User info shortcut (undefined for system / unauthenticated writes)
604604
user?: {
@@ -622,14 +622,6 @@ predicates, and in seed rows. Read it as **`organizationId`**:
622622
const org = ctx.user?.organizationId ?? ctx.session?.organizationId;
623623
```
624624

625-
> The former `ctx.session.tenantId` alias was removed in v16 — read the
626-
> org under `organizationId`. (The generic driver-layer `execCtx.tenantId` /
627-
> `DriverOptions.tenantId` isolation knob is a separate axis and is unaffected.)
628-
629-
`ctx.user` is the ergonomic shortcut for an authenticated caller; it is
630-
`undefined` for system / unauthenticated writes, so read `ctx.session?.organizationId`
631-
when a hook must work regardless of whether a user resolved.
632-
633625
> **Two isolation axes — don't conflate them.** `organization_id` is
634626
> **org row-scoping**: many organizations share one database and every row
635627
> carries its owning org (`current_user.organizationId` filters reads/writes;
@@ -638,7 +630,8 @@ when a hook must work regardless of whether a user resolved.
638630
> ADR-0132). That is different from
639631
> **environment / database-per-tenant** isolation (`service-tenant`,
640632
> `driver-turso`), where "tenant" means an entire environment/database and the
641-
> generic driver-layer `tenantId` knob can carry that environment id. The
633+
> generic driver-layer `tenantId` knob (`execCtx.tenantId` / `DriverOptions.tenantId`)
634+
> can carry that environment id. The
642635
> object-metadata `tenancy.*` knob configures the *mechanism* (isolation on/off
643636
> + which column); the *value* you read and write is your `organization_id`
644637
> column. Under `single` the bootstrapped Default Organization is the only

0 commit comments

Comments
 (0)