docs(seed-data): state that switching a stack's active locale on a non-empty database needs a fresh database — the loader only writes (ruling A on #16596) #18117

Filed by the director seat (objectstack #12708, summon #23, session_01WCEaPsmKY4UyoivKkkaUHt) executing decision batch #133 item 3 — maintainer 「决裁批 #133 同意」 to the recommended A on #16596 (reconciliation is the operator's job; document it; the card closes not_planned), 2026-09-14T03:31Z. content/docs/** ⇒ domain:devx; p3 (documentation of an existing behaviour); triage may re-rank.

Landing site

content/docs/data-modeling/seed-data.mdx, section Locale Scoping (:180-215 on origin/main @ 57343f76). The section explains that locale selects WHICH dataset loads; it says nothing about what happens to rows a previous locale's dataset already wrote.

The sentence to add (substance; wording is the dev's)

The seed loader only ever writes (upsert); it never removes rows. Switching a stack's active locale on a non-empty database loads the new locale's dataset alongside the rows the previous locale's dataset wrote — both stay resident and queryable. To switch locales cleanly, start from a fresh database (the same rule objectstack-ai/kpi documents for its env-selected profiles).

Readings behind the sentence (⛔ do not restate as guesses)

• packages/metadata-protocol/src/seed-loader.ts: zero row-delete verbs (delete|deleteMany|remove|destroy|truncate on the engine: 0; control insertMany|upsert|update|create: 6 — engine seat's measurement on Seed loader never removes rows, so switching a stack's active locale leaves the previous locale's dataset resident alongside the new one #16596, 5613342640, re-verified by the director on 57343f76: 5 write-verb hits, 0 delete).
• Seed datasets have no locale axis — an app shipping demo data for two language markets has to select seeds at config-assembly time, which bakes the choice into dist and leaves the other locale's rows behind #16510's landing (PR feat(spec, metadata-protocol): add a locale filter axis to seed datasets, composed with env #16592, c1d8f98a) and its liveness line: the locale axis selects the dataset and does not reconcile.
• Ruling on Seed loader never removes rows, so switching a stack's active locale leaves the previous locale's dataset resident alongside the new one #16596 (batch Fix plugin tests: add missing drivers field to mock contexts #133 item 3): the loader stays write-only; reconciliation is not a loader capability.

Fences

• ⛔ No loader change, no Restart-when — this is documentation of a ruled resting state.
• Clause-②: no; docs-only ⇒ skip-changeset per AGENTS.md (publishes nothing from a released package).
• ⛔ content/docs/releases/** untouched.

Refs

#16596 (ruling A, batch #133 item 3) · #16510 / PR #16592 (the locale axis) · #16595 (wiring config.locale, independent)

Dedup terms: seed loader never removes rows, switch active locale fresh database, seed-data.mdx Locale Scoping, locale dataset resident

Generated by Claude Code