Skip to content

Commit d53131b

Browse files
docs(skills): seed replace deletes nothing; minimal preset still mounts job and queue (#31461)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} --> _Requested by **Steedos** · [project thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9Ubb1MwwZcM4s82KjfqCmKfFrE)_ Fixes #31379 Clause-②: no Metadata-protocol: none ## 维护者速读 - **改了什么**:平台技能 Seed Data 一行不再把种子模式 `replace` 标成「数据丢失」,改为「从不删除、会重复」;`PLATFORM_ALWAYS_ON_CAPABILITIES` 的注释补全 `--preset minimal` 下仍会挂载 `job`/`queue`/`email` 的情形。 - **为什么改**:实测加载器的 `replace` 只做插入,一行都不删;旧文案吓退本该可用的场景,却漏说真正的风险(重复行)。注释原说 minimal「完全退出」,与 `resolveServedCapabilities` 实际行为不符。 - **风险与回滚**:仅教学文字与代码注释,无行为变化;回滚即 revert 本 PR。 - **先看**:`skills/objectstack-platform/SKILL.md`(Seed Data 段两行)、`packages/spec/src/kernel/platform-capabilities.ts`(L347-351 注释)。 - **两分钟验证**:`node scripts/check-skills-token-ratchet.mjs`,预期平台 SKILL.md 仍为 5994 tokens(上限 6011),退出码 0。 - **需要你做的**:审阅并批准(技能面属 Tier H,需维护者落地)。 ## What changes - `skills/objectstack-platform/SKILL.md` § Seed Data: `replace` ⚠️ **data loss** becomes `replace` ⚠️ never deletes, duplicates. Every `SeedMode` member stays named (the `seed-modes` liveness binding). The growth is paid in the same paragraph ("rows that already exist —" becomes "existing rows:"), on the same two lines. - `packages/spec/src/kernel/platform-capabilities.ts` TSDoc on `PLATFORM_ALWAYS_ON_CAPABILITIES`: `--preset minimal` opts out of the slate, but `resolveServedCapabilities` (`packages/core/src/capability-composition.ts`) still mounts `job` and `queue` first when `email`, `approvals` or `auth` is present (`NEEDS_JOB_AND_QUEUE`), and mounts `email` whenever `auth` is. Comment only. - `.changeset/31379-seed-replace-minimal-preset-text.md`: `'@objectstack/skills': patch`. No `@objectstack/spec` entry: the Check Changeset job requires a changeset, not one per moved package, and the spec edit is a comment. The `SeedMode` comment in `packages/spec/src/data/seed.zod.ts` and `skills/objectstack-data/references/seeds.md` were already right and are unchanged. ## Tests The loader measurement that decided which text was wrong, on `0c4f621e`'s parent `4941c40b`: <details><summary>Seed loader <code>replace</code> over existing rows (throwaway probe, not committed)</summary> The real `SeedLoaderService` over an in-memory engine double holding two rows, `gold` (matched by the dataset's `externalId: 'name'`) and `legacy` (not in the dataset). Dataset: `mode: 'replace'`, records `gold` and `silver`. ``` multiPass=false before=2 after=4 deleteCalls=0 updateCalls=0 totalInserted=2 rows: pre-1:gold:1, pre-2:legacy:9, gen-1:gold:2, gen-2:silver:3 multiPass=true before=4 after=6 deleteCalls=0 updateCalls=0 totalInserted=2 rows: + gen-3:gold:2, gen-4:silver:3 ``` `replace` deleted nothing (the row outside the dataset survives), left the matched row as it was, and inserted every record again on each load. Code: `writeRecord`'s `case 'replace'` only calls `engine.insert`, and `decideWriteAction` groups `replace` with `insert`. </details> - `pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/kernel/platform-capabilities.test.ts`: 35/35 passed. - `pnpm --filter @objectstack/spec typecheck` under the verify lock: VERDICT command-exit 0. ## Acceptance notes - `skills/**` readings, origin/main `4941c40b` vs head: `skills/objectstack-platform/SKILL.md` 411 → 411 lines, 23994 → 23993 bytes, 5994 → 5994 tokens (ceiling 6011); all SKILL.md files 4553 → 4553 lines; bundle total 237077 → 237077 tokens. - The order's file surface names `skills/objectstack-platform/references/seeds.md`, which does not exist; the seeds reference is `skills/objectstack-data/references/seeds.md`, already correct and untouched. ## Verification <details><summary>Derived gates: 93 derived, 92 exit 0, 1 NOT MEASURED</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` at `0c4f621e`: 93 commands; 92 exit 0. `pnpm check:dual-build-cjs-loads` exit 3 (PREREQUISITE NOT MET: needs every package's dist; left to CI). `--ran` reconciliation: 93 accounted, 92 run, 1 NOT-MEASURED, 0 UNRUN. After merging `origin/main` (head `ded443ab`, no incoming change to a touched file), re-run: `check-skills-token-ratchet`, `check:skill-identifier-liveness`, `check:skill-links`, `check-changeset-no-major`, `check-empty-changeset`, spec `check:docs`, `check:nul-bytes`, all exit 0. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01QsR2jT9oVmjxA38pKor1tX)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent ba875d2 commit d53131b

3 files changed

Lines changed: 16 additions & 3 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 platform skill's Seed Data line no longer marks seed mode `replace` as data loss
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
`replace` inserts every record with no match and deletes nothing, so a replay over a table nobody cleared leaves the existing rows as they are and adds the dataset's records again. The platform skill now says so (never deletes, duplicates), as the `SeedMode` comment and the data skill's seeds reference already did. The `PLATFORM_ALWAYS_ON_CAPABILITIES` comment in `@objectstack/spec` also says what `--preset minimal` still mounts: `job` and `queue` when `email`, `approvals` or `auth` is present, and `email` when `auth` is.

‎packages/spec/src/kernel/platform-capabilities.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -345,7 +345,10 @@ export const PLATFORM_PLUGIN_WIRED_RUNTIMES: Readonly<Record<string, PlatformPlu
345345
* only when `audit` does; `sms` has no provider package in that image at all.
346346
*
347347
* This is the FLOOR, not the ceiling: a host may mount more (cloud adds
348-
* `observability`), and `objectstack serve --preset minimal` opts out entirely.
348+
* `observability`), and `objectstack serve --preset minimal` opts out of the
349+
* slate, though not of all of it: `resolveServedCapabilities` (`@objectstack/core`)
350+
* still mounts `job` and `queue` first when `email`, `approvals` or `auth` is
351+
* present, and mounts `email` whenever `auth` is.
349352
*/
350353
export const PLATFORM_ALWAYS_ON_CAPABILITIES: readonly string[] = Object.freeze([
351354
// Order is a CONTRACT, not a count. `queue`/`job`/`cache`/`settings` are the

‎skills/objectstack-platform/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -363,8 +363,8 @@ The stack's `data:` collection is authored with `defineSeed()`, which
363363
**objectstack-data** owns — go there for `externalId` matching, `env:` scoping,
364364
and which keys are derived.
365365

366-
`mode` (`ignore` default · `upsert` · `insert` · `update` · `replace` ⚠️ **data
367-
loss**) decides what a replay does to rows that already exist —
366+
`mode` (`ignore` default · `upsert` · `insert` · `update` · `replace` ⚠️ never
367+
deletes, duplicates) decides what a replay does to existing rows:
368368
[Import modes](../objectstack-data/references/seeds.md#import-modes).
369369

370370
### Demo accounts — `demoStaff` vs `devLogins`

0 commit comments

Comments
 (0)