spec + cli: seed mode text still says replace deletes every row and omits the landed-keys rule (seed.zod.ts, os diff note) #31099

domain:skills#3 · huangyiirene · session_01J8VVAj7CvjkGXvgXzd6RZ7

Filing gate: item 3 of #31090 (comment 6702892720, from the contract review of PR #31083): the packages/spec seed text is spec-lane work and is not edited from the skills lane. Wording measured by the #31090 card thread and checked by the contract review of PR #31097 (6703924081). ⛔ Not a claim. Triage sets the grade and the lane, and may split item 2.
class: c · reach: every reader of the seed schema's docs and .describe() text (authors, agents, generated references), and every os diff user.

What is owed

On main 9c1edbcd. Facts: ignore is the default (#30081); replace deletes nothing, it inserts into a table the caller cleared (seed-loader.ts); since PR #31083, the AppPlugin loads (single-tenant boot, the seed-replayer service, hot reload) record the keys that landed per organization and do not insert again a recorded row that is now gone; the deliberate re-seed is seed-replayer(organizationId, { reseed: true }). The package publish apply, the runtime package install and the marketplace install-local loads keep no record.

1. packages/spec/src/data/seed.zod.ts (spec lane).
   • L24 insert comment ("fail on duplicate") and L27 replace comment ("Delete ALL records in object then insert"): align with the loader. replace deletes nothing.
   • L171–172 docstring and L195–196 .describe() ("a missing row is inserted and an existing row is left as it is"): add the landed-keys exception for the AppPlugin loads, and the re-seed door.
   • L116–117 history string: historical, optional.
2. packages/cli/src/commands/diff.ts L81 (seedModeNote): "a replay deletes every row of the object and inserts these" is false for replace. Owner: the CLI lane.

Re-read packages/metadata-protocol/src/seed-loader.ts and packages/runtime/src/app-plugin.ts before rewording. Text only, no behaviour change.

Level: '@objectstack/spec': patch (docs text) and '@objectstack/cli': patch (message), Clause-②: no, Metadata-protocol: none (triage to confirm).

Related: #31090, PR #31097, #31021, PR #31083, #30081.