feat(runtime,cloud-connection,organizations): the marketplace install, sample-data reseed, restart heal and per-organization replay pick seed datasets by the organization's language - #30346

Requested by Bill · project thread

domain:server#4 · os-bill · session_01Utp6CZMkHvuDeVYgTD73qF

维护者速读

• 改了什么： 市场安装、重灌示例数据、重启自愈、新组织的按组织回放，四条路径都按"这个组织说什么语言"挑 Seed.locale 数据集：先看组织的「设置 → 本地化 → 默认语言」（有人设过才算，内置的 en-US 默认值不算），再看安装人/创建人的个人语言，最后看应用声明的 i18n.defaultLocale。
• 为什么改： HotCRM 想让中国客户装上就是中文示例数据。原来安装路径不传语种，中文组织拿到英文产品目录，外加一页中文那份被唯一键拒掉的告警；一台服务器上新建的每个组织都拿启动时那一个语种。Irene 裁定 A（2026-11-05）：安装路径按语种挑。
• 风险与回滚： 只影响带 locale 的数据集；没有 locale 的照旧全装，整包都没有 locale 时连设置和用户都不读。读设置或用户时出错就不灌，按原路径报出（安装摘要、重灌 400、回放告警），不会拿别的语种顶上。启动种子、热重载、包应用、草稿发布不变。回滚即撤 PR。
• 先看： packages/runtime/src/seed-locale.ts（三级取值与"默认值不算"那一句）；packages/runtime/src/app-plugin.ts 的 replayer（改成每次回放按组织取）；packages/plugins/organizations/src/organizations-plugin.ts 中间件 B 把创建人传给 replayer 的那几行。
• 两分钟验证： pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 src/app-plugin.seed-locale-producer.test.ts，预期 22 个测试全绿，其中"两个组织不同语种在同一进程拿到不同数据集"和"建组织时按创建人语言"两条。
• 需要你做的： 无，席位落地。packages/spec 里 Seed.locale 的说明仍写"安装不按语种挑"，归 spec 车道另改（follow-up owed）。

Fixes #30281

Clause-②: yes (widening) — @objectstack/runtime exports the seed-locale producer (resolveSeedLocaleForLoad, appDefaultSeedLocale, seedsDeclareLocale, describeSeedLocale and three types), and the seed-replayer service callable takes an optional second argument (organizationId, { userId }); a one-argument caller works as before.
Metadata-protocol: semantic — an existing Seed.locale key now selects datasets on the marketplace install, the sample-data reseed, the restart heal and the per-organization replay, where it loaded every dataset and warned.
Skills-docs: updated here — content/docs/data-modeling/seed-data.mdx (the two Locale Scoping callouts: where the loading locale comes from on the install paths, and "installing is locale-neutral" narrowed to apply and publish); skills/** teaches no Seed.locale (git grep -n locale skills names no seed or dataset line), so nothing there turns false. follow-up owed — packages/spec/src/data/seed.zod.ts locale docblock and .describe() (install paths now pick by the organization's locale, ruling A 2026-11-05), whose .describe() regenerates content/docs/references/data/seed.mdx.

What changes

The producer (@objectstack/runtime, new seed-locale.ts). resolveSeedLocaleForLoad(host, { seeds, organizationId, userId, appDefaultLocale }) answers the locale one seed load filters Seed.locale on. First answer wins:

1. localization.locale read from the settings service for organizationId ({ tenantId }), so the service's own cascade decides (env override, the organization's row, the global row). ⛔ A value whose source is 'default' does not count. The manifest declares default: 'en-US' (service-settings/src/manifests/localization.manifest.ts), so taken literally the card's "effective value (cascade platform → global → tenant), or else the user's locale, or else i18n.defaultLocale" always stops at the first rung and the other two are unreachable. The repo already reads it this way in two places: the auth email language takes localization.locale "only when it was EXPLICITLY set; a manifest default leaves the app's build-time i18n.defaultLocale standing" (plugin-auth/src/auth-plugin.ts, applyLocalizationLocale), and the new-organization currency writes only while the key "still resolves from the default (source: 'default')" (plugin-auth/src/organization-default-currency.ts). The seat accepted this reading before code.
2. sys_user.locale of userId (system-context read, SystemObjectName.USER).
3. appDefaultLocale.

Nothing answers ⇒ undefined, and the request carries no locale key (the loader's unrestricted spelling, with its existing warning). When seeds is given and no dataset declares locale, rungs 1 and 2 are not read at all. No settings service ⇒ rung 1 is skipped. A settings or user read that throws is thrown on: the caller's seed reports it and writes nothing. Also exported: appDefaultSeedLocale(body) (top-level i18n.defaultLocale, then a nested manifest; a legacy i18n array declares none), seedsDeclareLocale, describeSeedLocale (log line), and the three types.

Per-organization replay (AppPlugin, packages/runtime/src/app-plugin.ts). The replayer used to capture resolveSeedLocale() (the boot bundle's i18n.defaultLocale) once at boot. It now resolves at replay time per organization, with the boot default as rung 3, and takes (organizationId, options?: { userId }). One info line names the locale and its rung. The boot inline seed and the dev hot-reload seeder still use resolveSeedLocale() alone (outside the card's ask; see Acceptance notes).

The founder (@objectstack/organizations, Middleware B). On a sys_organization insert the middleware passes opCtx.context.attributedUserId (else userId) to the replayer as { userId }, and keeps the one-argument call when the insert names no person. better-auth's create runs through the adapter as system with the signed-in creator as attributedUserId (plugin-auth/src/objectql-adapter.ts, withSystemContext).

Item 3, new-organization founding: lands on (a), with (c) behind it, by construction. At the insert the organization has no tenant row yet (plugin-auth writes its currency and timezone in afterCreateOrganization, after the insert, and writes no locale at all), so rung 1 answers only an env or global value. Rung 2 is then the founder's sys_user.locale, which is option (a); no founder (the boot's default organization, a cloud system insert) falls to the app's default, which is option (c). Option (b) would need a deferral mechanism the cascade does not have. No needs_decision; both paths are pinned (Tests).

Install paths (@objectstack/cloud-connection, runInlineSeed and its three call sites). runInlineSeed(ctx, datasets, organizationId?, localeFrom = {}) resolves through the runtime producer and spreads locale into the loader config. Measured call sites on origin/main 4be9734 (the dispatch's mapping was off by one role each; the seat confirmed):

• applySideEffects step 3 (reached by the install, handleInstall, and by the reseed, handleReseed): the active organization, the admitted user (opts.userId, new, passed from both handlers' admission.userId), and the package body for its i18n.defaultLocale.
• The rehydrate heal (maybeHealSampleData, single-tenant only): no organization, no user, the converted body.
• This plugin's own seed-replayer (registered only when the host has none): the organization and the founder, ⛔ no app default, because it replays the union of every installed package and no one package's default speaks for it.

The constructor and the rehydrate section (seat 3's #30217) are untouched.

Docs. content/docs/data-modeling/seed-data.mdx, Locale Scoping: the info callout gains the install-path rungs; the warn callout's "publishing and installing are locale-neutral, by decision" is narrowed to apply and publish, citing this ruling as reversing the install half of #17011.

Changeset. 30281-seed-locale-per-organization.md: @objectstack/runtime minor, @objectstack/cloud-connection minor, @objectstack/organizations patch (Metadata-protocol: semantic ⇒ at least one moved package minor), both declaration lines.

Tests

• packages/runtime/src/app-plugin.seed-locale-producer.test.ts (the Seed.locale producer harness), two new top-level describes, rows reaching the engine as the assertion through the real SeedLoaderService:
  • per-org replay (Seed.locale: marketplace install, reseed sample data and per-org replay should select datasets by the installing organization's locale #30281), 12 cases: two organizations with different settings get different datasets in one process (pin 2) and each settings read names its own tenantId; a global value counts; at founding the founder's language decides (option (a)); the manifest's en-US default never outranks the founder; the organization's setting outranks the founder; no founder and no setting ⇒ the app's default (option (c)); a founder with a blank language falls through; no settings service still honours the founder; nothing answers ⇒ every dataset loads and the loader warns; an unscoped dataset loads for both organizations (pin 4); no locale-scoped dataset ⇒ neither the setting nor sys_user is read; a settings read that throws rejects the replay and writes no row.
  • appDefaultSeedLocale, 3 cases (top level, nested manifest, legacy array, blank).
• packages/cloud-connection/src/marketplace-install-local-seed-replayer.test.ts (the install-path seeding harness), new top-level describe, 7 cases with recording stand-ins for the producer (its rungs are pinned in runtime): the install asks for the active organization, the admitted user and the package's i18n.defaultLocale, and the loader receives the answer (pin 1); the reseed asks again and loads the answer as it stands now; the rehydrate heal asks with no organization and no user; the replayer asks per organization (two organizations, two locales, pin 2) and passes the founder with no app default; no answer ⇒ no locale key; a failing read seeds nothing and the install summary names the error.
• packages/plugins/organizations/src/organizations-plugin.test.ts, new top-level describe, 2 cases: Middleware B hands the replayer { userId } from the insert's attributedUserId, and keeps the one-argument call for a system insert with no person.
• Six sibling cloud-connection suites whose @objectstack/runtime mock carries the loader alone gained the three producer exports answering "no locale" (their subject is not the locale; vitest throws on a mocked module's missing export, which turned their seeds into seed-error skips).
• Ablations, one per resolution point (scripts/ablation-replace.mjs, anchor hit 1 → 0 on disk, restore proven by an empty git diff HEAD on the file). All subjects are imported by relative path from src/, so no dist/ leg applies.

Acceptance notes

• "Set" means source !== 'default'. See What changes, rung 1. A deployment that wants every organization seeded en-US regardless of its founders sets the global value (or OS_LOCALIZATION_LOCALE), which counts.
• Tags match exactly. The loader matches Seed.locale case-insensitively and otherwise exactly (['zh'] does not match zh-CN). A user whose stored sys_user.locale is a bare zh does not select a zh-CN dataset; the Localization setting offers only the four region-qualified tags.
• Founder = the insert's attributed user. An organization created server-side on someone else's behalf (a platform administrator's session creating it for a named owner) is attributed to the session's user, so the replay uses that person's language. The owner can reseed under their own Localization setting afterwards.
• A fresh organization on a marketplace-only runtime. This plugin's replayer has no app-default rung (the union has no single default), so an organization with no setting and no founder language loads every dataset with the loader's warning, as before this change. An AppPlugin-hosted runtime keeps its boot app's default as rung 3.
• Unchanged paths, by the card's scope. The boot inline seed and the dev hot-reload seeder still filter on the app's i18n.defaultLocale; package apply (service-package) and draft publish still pass no locale. The ruling text names the install paths; apply and publish are left alone as the dispatch says.
• Spec red line. packages/spec/src/data/seed.zod.ts's locale docblock and .describe() still say the install paths do not filter by locale (and the generated content/docs/references/data/seed.mdx repeats it). Not edited here (follow-up owed, Skills-docs line); the hand-written docs page is corrected in this PR. The code ships honestly against it: the behaviour is the ruling's, and the stale sentence is a description to correct, not a contract a caller relies on.
• Shared file with seat 3. marketplace-install-local-plugin.ts edits are limited to runInlineSeed, its three call sites, applySideEffects' options type and the two handler calls that feed it. Whoever merges second merges origin/main first.
• Assignee and reviewers: none set. The dispatch forbids GitHub MCP writes and asks for no review request, so the session's usual reviewer step is left to the seat.

Verification

Head 6d3a814a4, the merge of origin/main c1240a38a into the branch. The merge touches none of this PR's 16 files.

• At head, under the verify lock: app-plugin.seed-locale-producer.test.ts 22 passed, marketplace-install-local-seed-replayer.test.ts 16 passed, organizations-plugin.test.ts 20 passed.
• Full package suites on c6795fe0a, the last code commit (these packages' files are byte-identical at head; a8fb28cd5 adds the docs page and the changeset): @objectstack/runtime 541 files, 8635 passed, 19 skipped; @objectstack/cloud-connection 70 files, 853 passed; @objectstack/organizations 18 files, 250 passed. Typecheck of the same three packages: exit 0.
• At head: pnpm install --frozen-lockfile exit 0; turbo run build --filter='!@objectstack/docs' 119/119.
• node scripts/pm/dispatch-gates.mjs --commands derived 95 families. Each ran at head with its exit recorded: 95 of 95 exit 0. --ran reconciliation (it re-derives on the head tree): 95 derived, 95 run, 0 NOT-MEASURED, 0 UNRUN, exit 0.
• pnpm lint exit 0.
• Ablations: the table under Tests, each red then restored.

Not measured: a live boot that installs a marketplace package into a zh-CN organization over HTTP. The install, reseed, heal and replay seams are pinned at the plugin with the producer stood in, and the producer's three rungs are pinned in runtime against the real SeedLoaderService, so the join between the two is covered by types and the shared export, not by one end-to-end run.

pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 src/app-plugin.seed-locale-producer.test.ts
pnpm --filter @objectstack/cloud-connection exec vitest run --maxWorkers=2 src/marketplace-install-local-seed-replayer.test.ts
pnpm --filter @objectstack/organizations exec vitest run --maxWorkers=2 src/organizations-plugin.test.ts

Expect 22, 16 and 20 passed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Utp6CafJkuNKWHNo7WLtiP