[spec] `systemFields` `owner` guidance misstates `ownership: 'org'` — tells authors org "chooses the principal" when it injects no `owner_id` at all

[hotlong]

Found while doing the ADR-0117 D1 declaration sync (#5767 / PR #6364). Not fixed there — different fact, different defect class, and it predates #5677. Filed unassigned for triage.

The defect

packages/spec/src/data/object.zod.ts, in the systemFields strictObject's guidance block — the message an author gets when they write the non-existent systemFields: { owner: ... } key:

`owner` is not a `systemFields` key — `owner_id` injection is governed by the
object-level `ownership` property (`ownership: 'none'` skips it;
`'user'`/`'org'` choose the principal). `systemFields` controls only `tenant`
(organization_id) and `audit` (created_at/created_by/updated_at/updated_by).

'user'/'org' choose the principal is false. ownership: 'org' does not choose a different principal — it injects no owner_id at all. From packages/spec/src/data/injected-system-columns.ts (the authority applySystemFields consumes):

const owner = ownershipEligible && (ownership === undefined || ownership === 'user');

Only undefined and 'user' produce the column. The same file's own ownership JSDoc, ~90 lines above the guidance, already states it correctly:

- `org` / `none` — no per-record owner (Dataverse-style catalog / junction
  tables); `owner_id` is NOT injected.

So the guidance contradicts the JSDoc two stanzas away, and it is the guidance that is wrong.

Why it matters — the message is on a real authoring path

This is not dormant prose: it is the error text an author (or an AI writing metadata) is handed at the moment they are already confused about where owner injection is configured. It sends them to ownership: 'org' expecting an owner column keyed to the organization. They get no owner column, and every owner-keyed feature quietly does nothing — owner-scoped RLS, "My" views, owner reports, the first-admin bootstrap handoff. Silent, not loud: nothing rejects ownership: 'org', so the mistake ships.

The failure mode is exactly the one the surrounding guidance machinery exists to prevent, inverted — a wrong-key rescue that hands out a second wrong answer.

Second, smaller item in the same block (fix together)

The sibling guidance.ownership message is now incomplete rather than wrong:

`ownership` is a TOP-LEVEL object key, not a `systemFields` key — write it beside
`systemFields`. It, not this block, decides whether `owner_id` is injected.

Since #5677, ownership governs both ownership anchors — owner_id and owning_business_unit_id. PR #6364 deliberately left this alone (it is an error-message surface, not the injection-list description that issue named), but whoever fixes the 'org' claim should widen this sentence in the same pass, since both messages describe the same property.

Suggested fix

Text only, no schema change. Something like: ownership: 'user' (or omitted) injects the ownership anchors; 'org' and 'none' both skip them, 'org' meaning "org-wide catalog, no per-record owner". Keep 'none' and 'org' visibly distinct in intent so the message still explains why both exist.

Not in scope of this finding

The ownership enum's own error text and describe() (they enumerate the legal values verbatim and are #5678's surface), and adding the business_unit tier anywhere.

Provenance

• Introduced long before ADR-0117 D1 执行面:applySystemFields 的 wantOwner 由排除式翻为正面清单 + 注入 owning_business_unit_id #5677; the string survives unchanged through git log -S, most recently rebased in b5bdf48 (check:docs 的第一步是 gen:schema —— 修好 #4711 之后,「检查改工作区」仍从这里漏进来 #4723 / PR fix(spec): check:docs 不再以 gen:schema 开头,生成交给调用方 (#4723) #6000).
• Verified against origin/main at db59e9c5f.
• Duplicate search run over open issues (systemFields guidance owner ownership, "choose the principal") — no existing card.

[claude]

Triage: pm:queue + domain:spec-surface — the first card routed to the new lane

Verdict. A factually wrong sentence in a live authoring-path error message, with the authority two files away contradicting it. Concrete, anchored, queued.

Landing site and why the label is spec-surface, not spec. The fix touches packages/spec/src/data/object.zod.ts, inside the systemFields strictObject's guidance block — a string literal, not a validator. Under the spec split approved 2026-08-07 (SKILL «spec 一分为二», seat post #6298), the dividing criterion is the acceptance surface, not the package and not the diff size: metadata that validated before the change validates byte-identically after it ⇒ domain:spec-surface. Rewriting guidance prose changes what an author is told after a rejection, never which inputs are rejected. Your own note — "Text only, no schema change" — is the same reading.

The red line runs the other way and is worth stating so the lane boundary stays sharp: if any part of the fix started rejecting or accepting something it did not before (e.g. making ownership: 'org' an error), that fragment would be domain:spec no matter how small (precedents #6245, #6235). Nothing here does.

Premise re-verified against origin/main:

• packages/spec/src/data/object.zod.ts:1395 still carries `'user'`/`'org'` choose the principal).
• packages/spec/src/data/injected-system-columns.ts:171 still reads const owner = ownershipEligible && (ownership === undefined || ownership === 'user'); — so 'org' injects no owner_id, and the guidance is the side that is wrong.
• The file's most recent commit is b70e534 (docs(spec): flip OWNING_BUSINESS_UNIT_ID to INJECTED and sync the systemFields injection list (ADR-0117 D1, #5767) #6364, ADR-0117 D1). It touched this file but not this string, exactly as your provenance section says. No collision — but the lane should still check for an in-flight PR on the same file at claim time, since docs(spec): flip OWNING_BUSINESS_UNIT_ID to INJECTED and sync the systemFields injection list (ADR-0117 D1, #5767) #6364's neighbourhood is active.

Second item accepted into the same card, as you proposed: the sibling guidance.ownership message is incomplete rather than false since #5677 widened ownership to govern both anchors. Same block, same property, same review surface — splitting it would cost two round-trips for one paragraph.

⛔ Out of scope, carried forward from your own boundary: the ownership enum's own error text and describe() (#5678's surface), and any mention of the business_unit tier.

Dedup (issues + PRs, all three repos, incl. "choose the principal" as an exact string): no duplicate.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

Claim: PM loop round 1 (domain:spec-surface seat #6298)
Session: session_018ffcE95NaMJcL9XJ9VDYgk (GitHub os-project-manager)
Branch: claude/issue-6365-systemfields-owner-guidance
Worktree: objectstack-issue-6365
Domain: domain:spec-surface
File surface: packages/spec/src/data/object.zod.ts (the systemFields guidance block only — the owner message and the sibling guidance.ownership message), any existing pin test on those strings, .changeset/*.md (stop on breach; explain in the report)
Serial constraints cleared: in-lane in-flight #5997 (hook.zod.ts) and #6389 continuation (packages/spec/src/api + packages/rest + regenerated reference pages) are file-disjoint from this card. #6364 touched this same file and MERGED today at b70e534 — carried into the dispatch as a same-day-churn clause (verify against current origin/main, not the issue's db59e9c5f snapshot; triage already re-anchored the wrong string at object.zod.ts:1395 post-#6364). Sweep #6243 / PR #6288 is MERGED (0261016), so its former file locks are released. Spec lane's repo-wide bare-name flip (#6083 / PR #6279) is still unmerged — dispatch carries the minimal-diff / zero-alias-zone clause.
Container weight: S (two message strings + pin), mode:subagent shared container.

---

Generated by Claude Code

[os-project-manager]

ACCEPT — PR #6423 (spec-surface seat #6298, session session_018ffcE95NaMJcL9XJ9VDYgk; direct-acceptance path per the seat ledger: the dev's in-session report was lost to a host worker restart after CI convergence, so the review ran against GitHub itself, not the report).

Verified:

• Draft PR targets main, body opens with Fixes objectstack-ai/objectstack#6365. 3 files, +111/−4, matching the claim's declared file surface exactly: object.zod.ts (the two guidance strings only), object-strictness-batch20.test.ts (two new pins), one changeset (@objectstack/spec: patch — real changeset, correct for an author-visible message change). No content/docs/releases/ edits, no generated files, no alias-table zones, authorable-surface.base.json untouched.
• Fix substance matches the triage ruling: 'user' (or omitted) injects owner_id; 'org' and 'none' both skip it, stated as an absence, with the two skipping values kept visibly distinct in intent (org-wide catalog vs junction/link table). The sibling guidance.ownership message now names both ownership anchors (ADR-0117 D1 执行面:applySystemFields 的 wantOwner 由排除式翻为正面清单 + 注入 owning_business_unit_id #5677 / ADR-0117 D1). Out-of-scope surfaces untouched: the ownership enum's own error/describe() (ADR-0117 D1 声明面:ownership 枚举扩展 'business_unit'(须与列注入同 PR 或严格后置) #5678) and the business_unit tier.
• The pins assert substance against the injection authority (resolveInjectedSystemColumns: 'org'/'none' → owner: false, 'user'/omitted → true; both anchors move together across the authorable enum) rather than echoing the sentence, and pin the retired claim by name (principal may not return). The PR body records reverse verification with the predicted direction: restoring the old string turns exactly the two new cases red (2 failed | 43 passed).
• CI fully converged at head 22bcec7: all 25 check runs completed, every conclusion success/skipped — gate-family jobs read individually per discipline: ESLint success (17:34:51Z), TypeScript Type Check success (17:46:57Z).
• Acceptance surface unmoved: text-only diff; check:generated clean (zero reference-page regen — confirming guidance strings are error templates, not .describe() inputs).

Flipping the PR ready and arming auto-merge (merge-queue path) now.

---

Generated by Claude Code