Repository navigation
Commit c44c8ac
docs(agents): stored rows replay only what the installed release still carries (#29011)
<!-- claude-projects-attribution: {"github_login":"huangyiirene"} -->
_Requested by **Irene** · [project
thread](https://claude.ai/code/project/chan_01TJXtQ1tVD26ecLDZxFS67x?thread=cmsg_01TJXtQ1tVD26ecLDZxFS67xJhE8WhApnrf9rNZxcXpcQx)_
Fixes #28924
Clause-②: no
Metadata-protocol: none
## 维护者速读
- **改了什么**:三处文字(AGENTS.md 第 12 条首要原则的最后三行,以及
`stored.ts`、`stored-migration.ts` 两个文件头注释)不再说"存储的转换永远重放";代码和行为零改动。
- **为什么改**:18.3 起 ≤16.x 的退役转换已被删除,旧说法会让 AI 告诉用户 16 时代的存储行仍然安全,与
`.changeset/25767-retire-16x-retirement-kits.md` 的 Stored rows 条目矛盾。
- **风险与回滚**:纯文字,无运行时风险;回滚即 revert 这一个 commit。
- **先看**:① `AGENTS.md` 第 253-255 行(Tier H,行数保持 3 行不变);②
`packages/metadata-protocol/src/stored-migration.ts` 头注释(含对 "Not
load-bearing" 段的收窄);③ `packages/spec/src/conversions/stored.ts` 头注释。
- **两分钟验证**:`git diff origin/main -- AGENTS.md`,预期只见 3 行删、3 行增,第 12
条总行数不变。
- **需要你做的**:批准(APPROVE)本 PR —— 它触及 AGENTS.md,属 Tier H,批准后由席位落地。
## What changes
Three texts that still stated the pre-18.3 policy, that every stored
conversion replays forever, now say what ADR-0087 as amended (ruling
6434038284) says: rehydration replays the chain the **installed
release** carries, retirement kits age out one major after their
retirement, and the stored pass (`os migrate meta --stored --apply`)
must run on a release that still carries a row's conversions, before the
deployment moves to the release that drops them.
1. **`AGENTS.md` Prime Directive #12, lines 253-255.** Governed Tier H
text. The rewrite keeps the directive at exactly its line count (3 lines
removed, 3 added; the directive still spans lines 245-255), every line
stays at or under 116 characters, and the sentence keeps its shape:
"Stored rows: [mechanism]; [limit], so [action]. Strengthens #5." The
old consequence clause ("so a consumer never needs its own accommodation
for a legacy stored shape either") was dropped because it is no longer
unconditionally true, and the three facts the card requires could not
fit beside it in three lines.
2. **`packages/spec/src/conversions/stored.ts` header, the first policy
bullet.** "D3 keeps every conversion forever precisely so any past major
can replay forward" is replaced by the kit age-out rule and the
stored-pass instruction; the bullet's heading now reads "The chain the
installed release carries replays".
3. **`packages/metadata-protocol/src/stored-migration.ts` header.** "a
row written under any past protocol is *served* canonical forever" is
replaced. The same header's **Not load-bearing** paragraph, two
paragraphs below, said "the read path stays the guarantee and nothing
gates on this having run"; left alone it would have contradicted the
corrected sentence, so it is narrowed to the window in which the release
still carries a row's conversions, matching the ADR's 2026-10-26
amendment ("for those rows it is the required one, not an optional
one"). This stays inside the claimed file surface (header comment only).
The wording was cross-checked against
`skills/objectstack-upgrade/SKILL.md` § *Stored rows: rehydration
replays what the release carries* and the **Stored rows** bullet of
`.changeset/25767-retire-16x-retirement-kits.md`.
## Why
Agents read AGENTS.md as binding. After 18.3 a stored row still in a
≤16.x shape is not rewritten by any seam, so a rule saying every seam
replays the full chain forever would lead an agent to tell a user their
16-era rows are safe.
## Tests
No test was added or changed: the diff is comment and rules prose only,
with no behaviour to pin and no ablation owed.
- `pnpm --filter @objectstack/spec build`, exit 0 (os-verify-lock
VERDICT command-exit 0).
- `pnpm --filter @objectstack/spec typecheck`, exit 0 (os-verify-lock
VERDICT command-exit 0).
- `@objectstack/metadata-protocol` typecheck and tests were not run
locally: the edit is inside a block comment and cannot change a type or
a test result. CI's `TypeScript Type Check` and `Test Core` carry them.
## Acceptance notes
- Other comments still say the full chain replays, retired entries
included, for example
`packages/metadata-core/src/artifact-forward-conversion.ts`,
`packages/core/src/fallbacks/authored-translation-sync.ts` and
`packages/metadata-protocol/src/protocol.ts`. Those describe what
replays (every entry the release carries, retired ones too), which is
still true, and none says "forever". They were left alone as outside
this card. Carrier: none.
- No changeset: the diff changes only comments in published packages
plus `AGENTS.md`, so nothing that ships changes in behaviour or API. The
PR carries `skip-changeset` for that reason.
## Verification
Gate derivation `node scripts/pm/dispatch-gates.mjs --commands` on head
`6bb390a5f` (objectstack-ai/objectstack): 73 commands. The
reconciliation `--ran` reports 73 accounted for: 68 run with exit 0, 5
NOT MEASURED (exit 3, prerequisite not met), 0 unrun.
<details><summary>Local gate readings (head 6bb390a)</summary>
- 68 derived commands exit 0, including `check:pm-governed-prose`,
`check:pm-skill-id-lint` (106 files clean), `check:pm-skill-ratchet`,
`check:doc-authoring`, `check:issue-citations`, `check:nul-bytes`,
`check:published-files`, `check-adr-0087-registration --base
origin/main`, and the spec gates `check:api-surface` (unchanged) and
`check:docs` (235 generated files in sync).
- `check-plugin-teardown-shape --self-test` first exited 3 on a shallow
fixture commit; it passed (48 cases) after fetching that commit.
- NOT MEASURED, reason: each needs a full workspace build, which a
comment-only diff does not justify locally, and CI builds before running
them: `check:dts-closure`, `check:dual-build-cjs-loads`,
`check:lean-entry-closure`, `check:sourcemap-no-sources-content`, and
`@objectstack/lint check:doc-formula-expressions`.
</details>
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(No schema touched.)
- [x] 2. Every name I added uses the casing for its kind. (No names
added.)
- [ ] 3. No formatter ran; `pnpm lint` passes. (No formatter ran; `pnpm
lint` was not run locally, CI owns that repo-wide run.)
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset. (Nothing
publishes; `skip-changeset`.)
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed. (`check:docs` and `check:api-surface` green;
nothing to regenerate.)
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01J8VVAmLfc58Ea3cCpbSx7C)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 9a0c622 commit c44c8ac
4 files changed
Lines changed: 31 additions & 15 deletions
File tree
- packages
- metadata-protocol/src
- spec/src/conversions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
250 | 250 | | |
251 | 251 | | |
252 | 252 | | |
253 | | - | |
254 | | - | |
255 | | - | |
| 253 | + | |
| 254 | + | |
| 255 | + | |
256 | 256 | | |
257 | 257 | | |
258 | 258 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
8 | | - | |
9 | | - | |
10 | | - | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
11 | 17 | | |
12 | 18 | | |
13 | 19 | | |
| |||
19 | 25 | | |
20 | 26 | | |
21 | 27 | | |
22 | | - | |
23 | | - | |
24 | | - | |
25 | | - | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
26 | 35 | | |
27 | 36 | | |
28 | 37 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
52 | 52 | | |
53 | 53 | | |
54 | 54 | | |
55 | | - | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
56 | 58 | | |
57 | 59 | | |
58 | 60 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
14 | 14 | | |
15 | 15 | | |
16 | 16 | | |
17 | | - | |
| 17 | + | |
| 18 | + | |
18 | 19 | | |
19 | 20 | | |
20 | 21 | | |
21 | | - | |
22 | | - | |
23 | | - | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
24 | 29 | | |
25 | 30 | | |
26 | 31 | | |
| |||
0 commit comments