[objectstack-fleet]

Requested by Leehom · project thread

Fixes #30976

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:os db orphans 现在也扫描「主表可选」的子对象(controlled_by_parent 对象唯一的 master_detail 声明为 required: false,controlled_by_parent admits an optional master (1/3): spec, lint and the read owner branch: a null-master detail row is readable by its owner only #30905 裁决 A 放行的写法):这类行若指向一条已不存在的主记录,会被列为孤儿(--delete 时先导出再随级联删除);主表字段为空的行是合法的,不列出、不删除。
• 为什么改:扫描只认 required: true 的主表字段(spec 的 isControlledByParentMasterField),PR feat(spec,security): a controlled_by_parent object may declare an optional master #30940 引入可选主表后,这类悬空行既没有任何用户入口能读到(访问权从不存在的主记录派生),os db orphans 也看不见。
• 风险与回滚:只改 CLI 的运维命令(手动执行、默认只报告不写);删除范围只多出「可选主表且主记录确已不存在」的行,判定复用 spec 已发布的 controlledByParentMasterOf,不改 spec。回滚即还原本 PR。
• 先看:packages/cli/src/utils/orphan-detail-sweep.ts 的 masterFieldsOf(新判定,含 sharingModel 限定);packages/cli/src/commands/db/orphans.integration.test.ts 新夹具 od_tip 与改动的删除断言;orphan-detail-sweep.test.ts 新 describe。
• 两分钟验证:pnpm --filter @objectstack/cli exec vitest run src/commands/db/orphans.integration.test.ts,预期 10 个用例全绿,其中 [#30976] 用例证明空主表行 t_none 不被列出、悬空行 t_orphan 被列为孤儿。
• 需要你做的:无,席位落地。

What changes

• packages/cli/src/utils/orphan-detail-sweep.ts — the sweep's "which field is a master" judgement moves into one local predicate, masterFieldsOf(object):
  • every REQUIRED master_detail (isControlledByParentMasterField, unchanged — the CONTROL);
  • on a controlled_by_parent object, its OPTIONAL master: controlledByParentMasterOf(fields) from @objectstack/spec/data answering optional: true (the one master_detail, declared required: false, with no required one beside it). The spec function reads any field map and leaves the sharing model to the caller, so the sweep asks sharingModel === 'controlled_by_parent' itself: only such an object derives its rows' access from that field (plugin-security's cbp read filter, security-plugin-cbp-read-filter.ts, returns no filter for any other model).
  • objectsWithRequiredMaster → objectsWithMaster, isRequiredMasterFinding → isMasterFinding (module-internal to the CLI; not on any exports subpath). Docblocks and the "other dangling" note no longer say "required master-detail".
• A row whose optional master is EMPTY is never a finding: the dangling-reference audit treats null / undefined / '' as "no link" (packages/objectql/src/integrity/dangling-reference-audit.ts, "Empty is not a reference"), so the sweep adds no null check of its own.
• packages/cli/src/commands/db/orphans.ts — the command's description, docblock and human heading said "required master-detail master"; that became false with this change, so they now say "master" (description: "Report detail rows whose master-detail reference names a master that does not exist, …").
• content/docs/deployment/cli.mdx — the os db orphans table row and section say the same, and name the optional master and the empty-master row.
• .changeset/30976-orphans-optional-master.md — @objectstack/cli patch.

No packages/spec edit: the optional-master judgement already exists there (controlledByParentMasterOf, public since PR #30940); the order's stop-line (a new spec predicate) is not reached.

Tests

• packages/cli/src/utils/orphan-detail-sweep.test.ts (unit, fake read-only engine):
  • fixture gains sw_optional (cbp, one master_detail required: false, plus a lookup), sw_optional_private (the same lone optional master_detail on a private object) and sw_required_cbp (cbp with a required master and an optional master_detail beside it);
  • the existing "reads only the objects that declare a master" case now expects sw_optional and sw_required_cbp read, sw_optional_private not;
  • new [#30976] describe: masterFieldsOf per object (CONTROL: sw_detail still answers its two required masters), and a dangling optional master is an orphan while a dangling lookup on the same object and a dangling optional master_detail beside a required master stay in otherDangling, never deletable.
• packages/cli/src/commands/db/orphans.integration.test.ts (integration, real boot + SQLite): fixture gains od_tip, cbp with an optional master on od_campaign, seeded through a system write with three rows — t_none (no campaign), t_live (the live campaign), t_orphan (the missing campaign).
  • new case [#30976] an optional master: …: t_orphan is an orphan; t_none and t_live appear in neither orphans nor otherDangling;
  • the existing cases now carry the second orphan: the report lists od_tip/t_orphan (counts orphans: 2), --delete removes it and keeps t_none and t_live (od_tip: ['t_live', 't_none'] after the run), the export holds it, and in the restrict case the unrestricted od_tip orphan is deleted while od_member is refused as before.
  • six module-top side-effect imports (@objectstack/service-datasource, driver-turso, runtime, platform-objects/plugin, plugin-security, rest) — check:test-source-alias asks them of an edited test file whose source reaches those dynamic imports, copying serve-host-crypto-provider.test.ts.

Runs

• The three orphan files (orphan-detail-sweep.test.ts, orphans.integration.test.ts, orphans.no-auto-run.test.ts) on head ec530681: Test Files 3 passed (3) · Tests 25 passed (25).
• pnpm --filter @objectstack/cli exec vitest run --project unit on 0967087c (the origin/main merge; ec530681 only adds the six imports to the integration file): Test Files 2 failed | 396 passed (398) · Tests 5595 passed | 29 skipped. The two files were test/published-subpath-console.pin.test.ts and test/published-subpath-hook-body.pin.test.ts, refusing "packages/cli is not built (./dist/index.js is absent)"; after pnpm --filter @objectstack/cli build both ran: Test Files 2 passed (2) · Tests 29 passed (29).
• pnpm --filter @objectstack/cli typecheck (tsc --noEmit && pnpm check:test-typecheck): exit 0.
• The integration layer is run here because the diff edits an integration-tier file; the rest of that layer is CI's.

Ablations (both restored to the HEAD blob, `git diff HEAD` empty after each)

1. The optional-master arm — node scripts/ablation-replace.mjs --file packages/cli/src/utils/orphan-detail-sweep.ts --anchor 'if (master?.optional === true) out.push(master.field);' --delete (anchor 1 → 0, blob 7e854c86 → 766c6ecb), running the unit file and the integration file: 8 failed | 10 passed (18). Red: the three unit cases above, e.g. AssertionError: expected [] to deeply equal [ { object: 'sw_optional', …(3) } ], and five integration cases, e.g. [#30976] an optional master: … AssertionError: expected [ 'od_member', 'od_member_note', …(1) ] to include 'od_tip' and the report case expected [ { object: 'od_member', …(3) } ] to deeply equal [ { object: 'od_member', …(3) }, …(1) ]. The CONTROL case ("an orphan is a dangling REQUIRED master-detail …") stayed green under the ablation.
2. The controlled_by_parent limit (negative pin: a lone optional master_detail on a private object is not a master) — anchor if (def?.sharingModel === 'controlled_by_parent') { replaced by if (def !== undefined || def?.sharingModel === 'controlled_by_parent') { (blob 7e854c86 → 9bc35e09), unit file: 2 failed | 6 passed (8) — expected [ 'master' ] to deeply equal [] for sw_optional_private, and the objects list with one extra entry.

The CLI suites resolve orphan-detail-sweep.ts and orphans.ts from src/ (relative imports), so no build leg was needed.

Acceptance notes

• Premise measured, holds. On origin/main 658d84f5, isControlledByParentMasterField (packages/spec/src/data/controlled-by-parent-master.ts) answers type === 'master_detail' && required === true only; PR feat(spec,security): a controlled_by_parent object may declare an optional master #30940 left it a required-master predicate and added controlledByParentMasterOf beside it for the optional master. The sweep called only the former.
• Deleting an optional-master orphan is the master-detail's own semantics, which is what the objectql: a master-detail row whose master is missing can be neither read nor removed through any door — the admin answers 404 by id, queries omit it, and the integrity audit only reports it #24964 ruling (record 6303808312) set as the remedy: a master_detail cascades or restricts (deleteBehavior: 'set_null' on it is a parse-time refusal, field.zod.ts), so the master's own delete would have removed such a row or been refused while it stood. Nulling the reference instead would be a different remedy and is not offered.
• Not widened: a lone required: false master_detail on a non-cbp object, and one beside a required master on a cbp object, stay "other dangling" — named, never deleted. A row with an empty optional master is never read as an orphan.
• Surface beyond the order's expected surface (orphan-detail-sweep.ts + its test): orphans.ts text, content/docs/deployment/cli.mdx, and orphans.integration.test.ts. The first two said "required master-detail master", which this change makes false; the integration file is the only place the null-master half can fail for real (the unit file's audit is a fake, and the audit is what skips empty values). Declared in the report.

Verification

Gate union derived by node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (92 families for this diff, the same list at 0967087c and ec530681), run on head ec530681, each exit code captured before any pipe, reconciled with --ran:

• 92 run, exit 0 each. --ran: "92 derived famil(ies) accounted for — 92 run, 0 NOT-MEASURED (a DERIVED zero — all 92 recorded an exit code and none of them is 3)".
• Prerequisites built first: pnpm --filter '@objectstack/cli^...' build (VERDICT command-exit 0), pnpm --filter @objectstack/cli build, and the build closure check:i18n-coverage names plus @objectstack/client / @objectstack/client-react for check:skill-examples (turbo, VERDICT command-exit 0). check-plugin-teardown-shape.mjs --self-test needed git fetch --depth=1 origin 621a4876 for its pinned fixture on this shallow clone.
• The first round, on 0967087c, answered check:test-source-alias exit 1 — the edited integration file reached six dynamic imports with no module-top load — fixed in ec530681 (the six imports above), then exit 0; and four exit 3 PREREQUISITE NOT MET (the three above plus check:dual-build-cjs-loads, which on the second round found enough built dist/ to measure: "116 published require entry point(s) across 71 package(s) load").
• CI families (every required check) are read from this PR's check-runs, not re-run here.

pnpm lint scoped: node --stack-size=4000 node_modules/eslint/bin/eslint.js packages/cli --no-inline-config, exit 0 (the package has no lint script); re-run on the edited integration file at ec530681, exit 0.

node scripts/check-platform-checklist.mjs --changed-from origin/main (two module-internal renames): exit 0, "0 anchored files in the change set".

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 12 documentable anchor(s).

15 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/error-catalog.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/data-modeling/objects.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/data-modeling/odata-datasources.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/data-modeling/virtual-objects.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/deployment/cli.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf), os db orphans (command, read off packages/cli/src/commands/db/orphans.ts))
• content/docs/getting-started/common-patterns.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/kernel/runtime-services/sharing-service.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/permissions/attachments-access.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/permissions/authorization.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/permissions/index.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/permissions/permissions-matrix.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/permissions/rls.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/permissions/sharing-rules.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/protocol/kernel/error-handling.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/protocol/objectql/security.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))

⛔ 9 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/implementation-status.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/releases/v15.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/releases/v17/17-1.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/releases/v17/17-2.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/releases/v17/17-3.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/releases/v17/index.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/releases/v18/18-0.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))
• content/docs/releases/v18/18-1.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf), os db orphans (command, read off packages/cli/src/commands/db/orphans.ts))
• content/docs/releases/v18/18-2.mdx (via controlled_by_parent (literal, a string literal in masterFieldsOf))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 63 of 226 client-bound route-ledger rows — the other 163 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 163: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 59 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 104 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 35 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json fe97d85b060b8314880e8ee5f6f897ffbb300bcd → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ad434ba7ca2f3016f9f74ef78a19ae642667dcd3 — the merge of head ec53068182c0b15fd57552fb774176ab8253919c into base fe97d85b060b8314880e8ee5f6f897ffbb300bcd, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ad434ba7ca2f3016f9f74ef78a19ae642667dcd3 && git checkout ad434ba7ca2f3016f9f74ef78a19ae642667dcd3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin fe97d85b060b8314880e8ee5f6f897ffbb300bcd ec53068182c0b15fd57552fb774176ab8253919c && git checkout -B drift-repro fe97d85b060b8314880e8ee5f6f897ffbb300bcd && git merge --no-ff ec53068182c0b15fd57552fb774176ab8253919c

node scripts/docs-audit/affected-docs.mjs --json fe97d85b060b8314880e8ee5f6f897ffbb300bcd

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs fe97d85b060b8314880e8ee5f6f897ffbb300bcd → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

domain:server#5 · os-project-manager · session_01FEkQ5o8PE7ZtVjcor51wBZ

维护者速读

• 改了什么:os db orphans 现在也扫描「主表可选」的子对象(controlled_by_parent 对象唯一的 master_detail 声明为 required: false,controlled_by_parent admits an optional master (1/3): spec, lint and the read owner branch: a null-master detail row is readable by its owner only #30905 裁决 A 放行的写法):这类行若指向一条已不存在的主记录,会被列为孤儿(--delete 时先导出再随级联删除);主表字段为空的行是合法的,不列出、不删除。
• 为什么改:扫描只认 required: true 的主表字段(spec 的 isControlledByParentMasterField),PR feat(spec,security): a controlled_by_parent object may declare an optional master #30940 引入可选主表后,这类悬空行既没有任何用户入口能读到(访问权从不存在的主记录派生),os db orphans 也看不见。
• 风险与回滚:只改 CLI 的运维命令(手动执行、默认只报告不写);删除范围只多出「可选主表且主记录确已不存在」的行,判定复用 spec 已发布的 controlledByParentMasterOf,不改 spec。回滚即还原本 PR。
• 先看:packages/cli/src/utils/orphan-detail-sweep.ts 的 masterFieldsOf(新判定,含 sharingModel 限定);packages/cli/src/commands/db/orphans.integration.test.ts 新夹具 od_tip 与改动的删除断言;orphan-detail-sweep.test.ts 新 describe。
• 两分钟验证:pnpm --filter @objectstack/cli exec vitest run src/commands/db/orphans.integration.test.ts,预期 10 个用例全绿,其中 [#30976] 用例证明空主表行 t_none 不被列出、悬空行 t_orphan 被列为孤儿。
• 需要你做的:无,席位落地。

席位意见:接受。判定只多认「controlled_by_parent 对象的可选主表」这一种,复用 spec 已发布的 controlledByParentMasterOf,空主表行不列不删;越出认领的三个文件都是本改动让原文案或原测试失真而必须跟着改的。

席位核对 — ACCEPT · domain:server#5 · Head-sha ec53068182c0b15fd57552fb774176ab8253919c · 2026-11-07T19:00Z

• Shape: 6 files, +219/−62, read from the diff. orphan-detail-sweep.ts: objectsWithRequiredMaster / isRequiredMasterFinding replaced by one predicate masterFieldsOf (required master_detail via isControlledByParentMasterField, plus, only when sharingModel === 'controlled_by_parent', controlledByParentMasterOf(fields) answering optional: true). The removed export has no other reader in the tree. orphans.ts / cli.mdx: text only. No packages/spec edit.
• Premise measured: the dev re-read the predicate first; on main the sweep keyed on required masters only, so the card held (premise_still_valid: true).
• Pins: unit describe (optional-master dangling → orphan; null master → not listed; lone optional master_detail on a non-cbp object → otherDangling; required master as before) and the real-audit integration case (t_orphan listed, t_none not). Both negative pins ablated red and restored (report 6711430157).
• Gates: head check-runs 38 success, 12 skipped, none red or pending. check-expected-skips: OK, all 12 in main's roster (exit 0). check-governed-merges: no governed path, 281 changed lines ≤ 3000. The dev's dispatch-gates --commands: 92 derived, 92 run, all exit 0, 0 NOT-MEASURED. Mergeable state clean.
• Accepted deviations: file surface beyond the claim (orphans.ts, cli.mdx: shipped text this change made false; orphans.integration.test.ts: the only real-audit place the null-master half can go red, with the six module-top imports check:test-source-alias requires). Within the card's scope.
• Out of scope: none new. Clause-②: no (no accept set widened; the delete set grows only by rows that already break ADR-0055's access derivation), Metadata-protocol: none, Skills-docs: n/a. Changeset @objectstack/cli patch.
• Landing: Tier S path rules do not apply (ungoverned). Fixes #30976. Ready + auto-merge.