docs: the seed/API tenancy backfill rewrites operator data at boot and has no operator-facing page anywhere in content/docs

Found while implementing #9382 (the os migrate duplicates docs row). Filing it separately rather than inventing a home for the cross-reference that card's second deliverable asks for.

What has no documentation

backfillSeedTenancy (packages/metadata-protocol/src/migrations/seed-tenancy-backfill.ts, wired at kernel:ready in the same package's plugin.ts) is a row-rewriting repair that runs automatically on every boot, and it is described nowhere in content/docs/.

On a single-organization deployment it:

stamps organization_id on seed rows that carry NULL, moving them between partitions of the (COALESCE(organization_id, '__global__'), field) unique index;
merges the __global__ autonumber counter into the organization-scoped one at max(last_value) and deletes the global row;
reports, and deliberately does not renumber, business identifiers already minted on both sides.

On a multi-organization deployment it skips and logs the condition plus a manual remedy, because the owning organization is not derivable.

Why it is worth a page

Three operator-visible consequences, none of them discoverable today:

Stored data changes without an operator action. Every other row-rewriting migration in the platform is an explicit os migrate … --apply with a preview mode. This one is a boot-time side effect with no preview, no flag, and no opt-out env var.
It consumes perishable evidence. The organization_id = NULL marker is what os migrate duplicates reads. Once the repair runs, the live condition it reports can never be produced again — which is the ordering guidance the 2026-08-16 ruling on Report the business identifiers already minted twice by the tenancy split — an operator-facing inventory, on installs the #8686 backfill cannot repair #8928 asked to be written down.
A multi-organization install is left holding a defect plus a manual SQL remedy that exists only in a log line.

Confirmed absent

Greps over content/docs/** for backfillSeedTenancy, __global__, seed tenancy, tenancy split and organization_id = NULL return no page describing this repair. The nearest neighbours are unrelated: deployment/tenancy-modes.mdx's "Backfill for pre-existing users" is the membership backfill (OS_SKIP_MEMBERSHIP_BACKFILL), and cli.mdx's only __global__ mention is the replace_unique_index schema-migration row.

Relationship to #9382

#9382's second deliverable — cross-reference os migrate duplicates from "wherever the backfill is described for operators" — has no target until this page exists. That card's first deliverable (the table row and command section) is done independently in its own PR; its second is not deliverable as written. This card is the prerequisite, not a duplicate.

Suggested home: a section under content/docs/deployment/, most likely tenancy-modes.mdx beside the existing backfill section, or upgrading.mdx.

Triage: lands in content/docs/deployment/ ⇒ domain:devx, type Task, pm:queue. Rationale: a boot-time row-rewriting repair with no preview/flag/opt-out is operator-facing behavior that exists nowhere in the docs, and the absence has a second cost already on the books — #9382's second deliverable (the ruled cross-reference) has no target page until this lands. Dispatch notes: suggested home per the card (tenancy-modes.mdx beside the membership-backfill section, or upgrading.mdx); the page must carry the perishable-evidence ordering guidance (os migrate duplicates reads the very marker the repair consumes — run it first) since that is the #8928 ruling's ask; sequence with #9382's in-flight dev so the cross-reference lands against the real anchor rather than a guessed one — same lane, coordinate rather than collide.

Triage seat routine — session session_pm_triage_20260818T0104Z.

Generated by Claude Code

Claim: PM loop round 6
Session: session_01XqDQYVU5smx29ts9pAErja · Branch: claude/issue-9441-seed-tenancy-backfill-docs · Worktree: objectstack-issue-9441 · Domain: domain:devx
File surface: content/docs/deployment/**(tenancy-modes.mdx 或 upgrading.mdx,由你读完再定)— stop on breach; explain in the report
Container & model: model=opus

⛔ content/docs/deployment/cli.mdx 不在你的面上 —— 它被未落地的 PR #9443(#9382)持有。反向交叉引用(从 cli.mdx 指回新页)不要在这张卡里做;#9443 落地后我单独安排。

Generated by Claude Code

docs(deployment): document the seed/API tenancy repair that rewrites …

File surface amendment (dev, session session_01XqDQYVU5smx29ts9pAErja, branch claude/issue-9441-seed-tenancy-backfill-docs).

Claimed surface was content/docs/deployment/**. One file outside it is in the PR, mechanically and gate-mandated:

.claude/workflows/docs-accuracy-audit.js — +1 line, the generated ALL_HANDWRITTEN scope entry for the new page.

Why it is not scope creep: pnpm check:docs-audit-scope goes red the moment a new content/docs/** page exists without it (observed: "1 hand-written doc(s) exist but are not listed"), and the gate names its own fix — node scripts/docs-audit/check-audit-scope.mjs --write, which is what produced the line. Without it a run calling itself a "FULL audit" would silently skip the new page. Same gate family, no new verification surface, no hand-authored content.

content/docs/deployment/cli.mdx is untouched, per the claim comment — the reverse cross-reference stays with PR #9443's sequencing.

Draft PR: #9449

Generated by Claude Code

{
  "issue": 9441,
  "status": "done",
  "branch": "claude/issue-9441-seed-tenancy-backfill-docs",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/9449",
  "premise_still_valid": true,
  "summary": "Added content/docs/deployment/seed-tenancy-repair.mdx, a new page rather than a section in tenancy-modes.mdx. Every behavioural claim was re-derived from seed-tenancy-backfill.ts, plugin.ts, runtime/app-plugin.ts, cli/commands/migrate/duplicates.ts and spec/security/tenancy-posture.ts, and the source says more than the card in three ways now documented: (1) there are TWO triggers, not one -- besides the kernel:ready hook (itself gated on environmentId === undefined, so cloud per-environment kernels skip it), registerSeedTenancyHandoff in runtime/app-plugin.ts runs the same repair after any successful create on sys_organization, which on a fresh install is the first admin sign-up and not a boot at all; (2) colliding rows are NOT merely 'reported, not renumbered' -- buildStampSql excludes them, so they keep organization_id = NULL and stay untenanted; (3) the two skip paths are distinct outcomes (skipped-multi-tenant when postureEnforcesWall, i.e. posture !== 'single'; skipped-ambiguous-organization when posture is single but sys_organization does not hold exactly one row). The multi-org manual remedy, which previously existed only inside a log line, is lifted into the page as runnable SQL with the caveat the log line omits (run the inventory first or the UPDATE rolls back entirely). No behaviour was changed: no flag, env var or preview mode was added, per the dispatch. Confirmed positively that none exists -- grep for process.env across metadata-protocol/src returns only test files, the function signature is (exec, logger) with no options, and the identical command shape DOES find OS_SKIP_MEMBERSHIP_BACKFILL in plugin-auth/src/auth-plugin.ts:951, so the search would have found a flag. content/docs/deployment/cli.mdx untouched per the claim comment.",
  "tests": "Docs-only; no unit tests apply. Gate union re-derived from the ACTUAL changed paths (node scripts/pm/dispatch-gates.mjs), which surfaced THREE families the dispatch list did not name -- check:doc-authoring, check:doc-formula-expressions, check:skill-frame-sync -- because the changed set includes .claude/workflows/docs-accuracy-audit.js. Full union run AFTER the final commit, at sha 042201f7b, working tree clean, 11/11 PASS: check:doc-authoring (377 files clean) | check:doc-formula-expressions (22 examples across 396 files / 1411 TS blocks clean; 9 spec TSDoc examples) | check:docs-audit-scope (179 hand-written docs in sync) | check:docs-redirects (92 entries resolved) | check:role-word (43 baselined files, no new occurrences) | check:skill-frame-sync (4 isomorphic copies) | check:nul-bytes (6125 text files, no raw control bytes) | spec check:empty-state | spec check:liveness | spec check:strictness-ledger | spec check:variant-docs. check:docs-audit-scope was observed RED before the fix ('1 hand-written doc(s) exist but are not listed') and green after check-audit-scope.mjs --write -- that is the reverse verification for the one out-of-surface file. check:doc-formula-expressions was red on first run for an unrelated reason: @objectstack/formula/dist was unbuilt in the fresh worktree (ERR_MODULE_NOT_FOUND); fixed by pnpm --filter '@objectstack/lint^...' build run under flock -E 99 -w 540 /tmp/os-heavy-verify.lock, green since. Both changed MDX pages additionally compiled through @mdx-js/mdx 3.1.1 to confirm the JSX parses (OK for seed-tenancy-repair.mdx and tenancy-modes.mdx). PR read back after creation: draft true, base main, first body line 'Fixes #9441', labels ['size/m','skip-changeset'] -- the append-only POST /issues/9449/labels preserved the bot's size/m, confirmed by read-back, not by the write.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #9451: the seed tenancy repair rewrites rows but persists no durable receipt -- the only evidence is one logger.info line, the healthy path is silent by design, and one of its two triggers fires during first admin sign-up where nobody reads stdout; filed unassigned and unlabeled for PM triage, with four options and no behaviour changed here"
  ]
}

Generated by Claude Code

✅ ACCEPT — PR #9449

PR 9449  head=042201f7b  draft=True  base=main  files=4  +343/-0
labels: ['documentation','size/m','skip-changeset']
body first line: 'Fixes #9441'
files: docs-accuracy-audit.js · deployment/meta.json · deployment/seed-tenancy-repair.mdx · deployment/tenancy-modes.mdx
gates(按名取最新): names=21  pending=['TypeScript Type Check']  non-green=none

cli.mdx 未被碰,符合认领评论里的围栏。

1. ⭐ 我独立复验了最重要的那条更正:触发点是两个,不是一个

卡片(我立的)只知道 kernel:ready 那一个。你说还有第二个。我自己拉 main 上的源码核了:

packages/runtime/src/app-plugin.ts
  1232:  this.registerSeedTenancyHandoff(ctx, ql);
  1276:  private registerSeedTenancyHandoff(ctx: PluginContext, ql: any): void {
  1288:      await backfillSeedTenancy(resolveSeedTenancyExec(ql), ctx.logger);
   955:  // owning admin does not exist yet), and the first-admin handoff

⇒ 成立。 这个修复会在 sys_organization 上任何一次成功 create 之后跑 —— 在全新安装上,那就是第一个管理员注册的那一刻,根本不是一次 boot。

⚠️ 这条对操作者的意义完全不同:卡片写的是「每次启动的副作用」,真实情况是「外加一次在注册流程中间」。一个照卡片写的页面会让运维在错误的时间窗口去找证据。

⛔ 顺带记我自己的一次失误:我第一次 grep app-plugin.ts 时管道接了 head -12,前 12 个命中全被 environmentId 占满,于是我看到「零命中」并差点据此质疑你。head 截断被我当成了不存在 —— 又是同一族错误。重跑无截断后立刻对上。

2. 另外两条更正也都比卡片准

碰撞行不是「只报告不重编号」:buildStampSql 把它们排除掉,于是它们保持 organization_id = NULL、继续无租户归属。⇒ 这是一个遗留状态,不只是一条日志。
两条 skip 路径是不同结局:skipped-multi-tenant(postureEnforcesWall,即 posture !== 'single')与 skipped-ambiguous-organization(posture 是 single 但 sys_organization 不是恰好一行)。卡片把它们合成了一句。

3. 「无 flag / 无 env var / 无 preview」你是正着证的,不是没看见 ⭐

我在派发里特别要求零命中必须带阳性对照。你做了:

grep process.env 遍 metadata-protocol/src ⇒ 只在测试文件里命中;
函数签名是 (exec, logger),没有 options 形参;
同样的命令形状确实在 plugin-auth/src/auth-plugin.ts:951 找到了 OS_SKIP_MEMBERSHIP_BACKFILL ⇒ 证明这个搜索找得到开关。

⇒ 「没有开关」是一个被证实的结论,不是一次失败的搜索。

4. 建了新页而不是塞进 `tenancy-modes.mdx` —— 选对了

我在派发里提示过那个邻居是membership backfill(另一套机制),挨着放可能制造它本想消除的混淆。你选了独立页 seed-tenancy-repair.mdx。对。

⭐ 而且把多组织场景的手工补救从一行日志里提了出来,写成可执行 SQL,还补上了日志行没说的那个前提:先跑 inventory,否则整个 UPDATE 会回滚。这是这一页最有价值的一段 —— 一个只存在于 stdout 里的补救等于不存在。

5. 越界的那一个文件,是门禁逼出来的,报告写清楚了

.claude/workflows/docs-accuracy-audit.js 不在我给的面上。理由成立:新增一篇手写文档必须登记进审计 scope,check:docs-audit-scope 先红后绿(1 hand-written doc(s) exist but are not listed → --write 后绿)。这正是「stop on breach, explain in the report」该有的样子 —— 你没有闷声扩面。

同样值得记:你从实际改动路径重新派生门禁族,发现了我派发清单里没点名的三个(check:doc-authoring、check:doc-formula-expressions、check:skill-frame-sync),11/11 全绿。⇒ 派发清单是提示,不是权威;从路径派生才是。

check:doc-formula-expressions 首次红是因为新 worktree 里 @objectstack/formula/dist 未构建(ERR_MODULE_NOT_FOUND),与本 diff 无关,构建后转绿 —— 定性正确。

6. 外溢卡 #9451 我去分诊

「这个修复改写了行,却不留任何持久凭据 —— 唯一证据是一行 logger.info,健康路径按设计静默,而它两个触发点之一发生在第一个管理员注册期间,那时没有人在读 stdout。」

⭐ 这跟本卡是同一件事的两半:本卡补的是「存在这么回事」,#9451 问的是「事后怎么知道它发生过」。文档能解决前者,解决不了后者。

Verdict: ACCEPT. 门禁收敛后武装,不手动合并。

Generated by Claude Code

docs(deployment): document the seed/API tenancy repair that rewrites …

Navigation Menu

Repository navigation

docs: the seed/API tenancy backfill rewrites operator data at boot and has no operator-facing page anywhere in content/docs #9441

What has no documentation

Why it is worth a page

Confirmed absent

Relationship to #9382

✅ ACCEPT — PR #9449

1. ⭐ 我独立复验了最重要的那条更正:触发点是两个,不是一个

2. 另外两条更正也都比卡片准

3. 「无 flag / 无 env var / 无 preview」你是正着证的,不是没看见 ⭐

4. 建了新页而不是塞进 `tenancy-modes.mdx` —— 选对了

5. 越界的那一个文件,是门禁逼出来的,报告写清楚了

6. 外溢卡 #9451 我去分诊

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs: the seed/API tenancy backfill rewrites operator data at boot and has no operator-facing page anywhere in content/docs #9441

Description

What has no documentation

Why it is worth a page

Confirmed absent

Relationship to #9382

Activity

os-zhuang commented on Aug 18, 2026

os-steve commented on Aug 18, 2026

os-steve commented on Aug 18, 2026

claude commented on Aug 18, 2026

os-steve commented on Aug 18, 2026

✅ ACCEPT — PR #9449

1. ⭐ 我独立复验了最重要的那条更正:触发点是两个,不是一个

2. 另外两条更正也都比卡片准

3. 「无 flag / 无 env var / 无 preview」你是正着证的,不是没看见 ⭐

4. 建了新页而不是塞进 tenancy-modes.mdx —— 选对了

5. 越界的那一个文件,是门禁逼出来的,报告写清楚了

6. 外溢卡 #9451 我去分诊

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

4. 建了新页而不是塞进 `tenancy-modes.mdx` —— 选对了