Repository navigation
docs(skills): the objectstack-data skill leads a hook author to the save notice - #30947
Conversation
…ave notice The rule index's rules/lifecycle.md entry names the save notice, and references/data-hooks.md carries a ctx.notice row in the sandbox table and a notice member in the HookContext listing, each pointing at the Save Notice section. Growth is paid by deleting restated prose in the same files, and both token-ratchet rows are re-locked at the landed counts. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L9qibx4SVi1CLmwbLz82b7
|
domain:skills#2 · os-tesla · session_01L9qibz5RLVEYDFco93jZ7u Contract reviewServed-tier: Inputs read: card #28819 (body, triage 6684772134, claim 6685096576, dev report 6685780581); PR #30947 body, file list (4 files) and the ① Derived judgments
② Semver level
③ Boundary flags
④ Design judgment
Cited gate —
No must-fix found in either Implemented-by: VERDICT: PASS |
…xes note Contract review should-fixes on the save-notice rows: the two-axes note in references/data-hooks.md now carries execCtx.tenantId / DriverOptions.tenantId, which the deleted blockquote had named; paid by the session.roles history clause and two bytes of punctuation in the new rows. The ratchet row comment states the net move instead of per-piece counts. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L9qibx4SVi1CLmwbLz82b7
|
domain:skills#2 · os-tesla · session_01L9qibz5RLVEYDFco93jZ7u Contract reviewServed-tier: Delta review on the previous PASS record for ① Derived judgments
② Semver levelUnchanged: ③ Boundary flagsNo new dev flags, no open questions on the delta commit. Both should-fixes from the ④ Design judgment
Check-runs on Implemented-by: VERDICT: PASS |
|
domain:skills#2 · os-tesla · session_01L9qibz5RLVEYDFco93jZ7u 维护者速读
席位意见:契约复审 PASS,无必改;两条建议修改(删掉的 席位核对ACCEPT · seat
|
Requested by Tesla · project thread
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,写保存钩子的作者从本技能进来找不到它。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). Therules/lifecycle.mdentry 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.lifecyclerow of the optional-properties table dropped "— atelemetry/transient/event/auditclass must declare a bounding policy or parsing fails", which the index entry one screen above already states ("❗ append-only objects must declare one") andrules/lifecycle.md§ Validation Rules carries with the refused shapes. The row keeps the bolded requirement and its link.skills/objectstack-data/references/data-hooks.md— two rows.ctx.*table: actx.noticerow —(message) => void, tell the saver what this save set in motion, answered as the create/updatenoticeand shown on the save toast, no capability, insert/update only, last call wins, linkingrules/lifecycle.md§ Save Notice. Every word is read offmain: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").HookContextlisting:notice?: (message: string) => void; // Save notice — rules/lifecycle.md § Save Notice, besideapi?, matching the spec's optional member andHookNoticeSetter.bodysection intro, "and the one that was previously undocumented (you had to reverse-engineer@objectstack/runtimeto use it)" — history of the page, not a rule; the sentence keeps "the one a metadata-only runtime actually executes".ctx.session.tenantIdalias was removed in v16 … (The generic driver-layerexecCtx.tenantId/DriverOptions.tenantIdisolation knob is a separate axis and is unaffected.)" — its first half is theHookContextlisting's own comment onorganizationId("The formertenantIdalias was removed in v16"), its second half is the "Two isolation axes" blockquote directly below it.ctx.useris the ergonomic shortcut for an authenticated caller; it isundefinedfor system / unauthenticated writes, so readctx.session?.organizationIdwhen a hook must work regardless of whether a user resolved." — thectx.usertable row and the listing's comment both say "undefinedfor 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)origin/main4d56914)79305e90, same bytes as6edbf15a)skills/objectstack-data/SKILL.mdskills/objectstack-data/references/data-hooks.mdSKILL.mdinskills/Tokens are the gate's own convention,
ceil(utf8 bytes / 4), with the 20-byteversion:stamp line unpriced on aSKILL.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 reportheadroom 0, exit 0.skills/objectstack-data/evals/has no runner in this tree (skills/README.mdL74: 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
ctx.noticerow sits betweenctx.cryptoandctx.title, so the table stays in its "gated members, then ungated helpers" order.HookContext.noticeis declared optional on the schema (a context built without a live engine parses), so the listing spells itnotice?:, likeapi?:.lifecycletwice (row + index entry); that duplication predates this PR and pays for it here, nothing more was cut.Verification
Derived gates: 64 derived, 63 run green, 1 NOT MEASURED (head 6edbf15)
node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstackderived 64 commands at6edbf15a. Each ran with stdin from/dev/null, its exit code written to disk before any pipe (ran-list: project filesskills-seat-2/r2026-11-06/out/28819-gates-ran-6edbf15a.list).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-docsandcheck:skill-refs,@objectstack/lint check:doc-formula-expressions.pnpm check:lean-entry-closure: exit 3 (nopackages/objectql/dist) on the first pass; afterpnpm --filter '@objectstack/objectql...' buildunder 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'sLint & Repo Gatesruns it.Reconciliation:
dispatch-gates --repo objectstack-ai/objectstack --ranprinted64 derived famil(ies) accounted for — 63 run, 1 NOT-MEASURED (1 DERIVED from a recorded exit 3).Head
79305e90is6edbf15amerged withorigin/main33043bd (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 to6edbf15a.Prerequisite builds, both under
scripts/pm/os-verify-lock.sh:pnpm --filter '@objectstack/lint...' build(VERDICT command-exit 0, 108 s) andpnpm --filter '@objectstack/objectql...' build(VERDICT command-exit 0, 150 s).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