[finding] packages/spec cloud docblock lists sys_metadata as a control-plane table "(with environment_id)" — the column is deprecated on the metadata tables, and the line ships to both the docs site and the published .d.ts

Surfaced while correcting the stale environment_id JSDoc sites for #13434. Filed unassigned — recording only, not claimed, and deliberately NOT fixed in that PR: the fix lands in packages/spec, a different package from that card's three files, and the correct wording depends on a fact this tree cannot settle (see "What is NOT claimed").

The reading

packages/spec/src/cloud/environment.zod.ts:26-31 — the module docblock — lists sys_metadata among the Control-Plane tables "(with environment_id)", on origin/main at eaba72e48c:

 * Split of concerns:
 * - **Control Plane**: `sys_environment` (includes physical DB addressing),
 *   `sys_package_installation` (with `environment_id`), `sys_environment_credential`,
 *   `sys_environment_member`, `sys_metadata` (with `environment_id`).
 * - **Data Plane**: each environment DB contains only business objects
 *   (account, task, …). No system tables, no `environment_id` columns.

It reaches two audiences beyond the source file:

The published docs site, verbatim: content/docs/references/cloud/environment.mdx:26-31. That page carries AUTO-GENERATED — DO NOT EDIT at line 6, so the docblock above is its only editable source.
The published .d.ts: packages/spec/dist/cloud/index.d.ts:1688 (and the .d.mts twin), so it is also an editor tooltip for consumers of @objectstack/spec/cloud.

What contradicts it

On the metadata tables, environment_id is retired, not live:

AGENTS.md:8 — "DB column environment_id [control-plane tables; on the metadata tables since deprecated in favour of organization_id, ADR-0006 v4]".
packages/metadata-core/src/objects/sys-metadata.object.ts:138-148 — @deprecated … "no longer written by saveMetaItem and not consulted by overlay reads. Kept for legacy rows; new writes leave it NULL."
packages/metadata/src/loaders/database-loader.ts:82-89 — @deprecated … "accepted for back-compat but ignored — writes do not set environment_id and filters do not constrain on it."
packages/metadata/src/loaders/database-loader.test.ts pins it: the create call carries organization_id and not environment_id, and no findOne where-clause has the property.
Card [finding] four JSDoc sites still say saveMetaItem stamps the environment_id column and loadMetaFromDb filters on it — the code carries zero non-comment occurrences #13434 itself: the JSDoc sites that taught the same retired stamp/filter, now corrected.

So the parenthetical reads as a live tenancy column to anyone deciding whether to write it — the same defect class as #13434 and #13433, one surface further out (published docs plus published types, rather than an in-repo docstring).

What is NOT claimed

Not claimed that the whole line is wrong. The sys_package_installation parenthetical on the previous line is correct — that IS a control-plane table keyed by environment_id (ADR-0003, UNIQUE (environment_id, package_id)), and ADR-0002 lists it the same way.
Not claimed which way the correction goes, and this is why it was not repaired inline. Whether the CLOUD control plane's own sys_metadata still carries a live environment_id is a fact about the cloud deployment's schema, not about this tree. Two readings, needing different wording:
1. The column is retired everywhere, so drop the parenthetical or restate it as deprecated / legacy-rows-only.
2. The cloud control-plane copy of sys_metadata genuinely still keys by it while the per-environment metadata tables do not, in which case the line needs to SAY that — as written a reader cannot tell the two apart.
Not claimed that the generated page should be edited. It is auto-generated; the docblock is the source.

Re-check

git grep -n 'sys_metadata` (with `environment_id`)' -- packages content
sed -n '26,31p' packages/spec/src/cloud/environment.zod.ts
sed -n '1,10p' content/docs/references/cloud/environment.mdx
git grep -n 'environment_id' -- packages/metadata-core/src/objects/sys-metadata.object.ts packages/metadata/src/loaders/database-loader.ts

Duplicate check

Full enumeration of all 366 open non-PR issues via the REST list endpoint (4 pages, page 5 empty — complete, not truncated), grepped locally. Positive control in the same pass: 33 open cards contain "AGENTS.md", so the instrument is not returning a false zero. Five open cards mention environment_id: #13434 (the JSDoc sites this fell out of), #13433 (sys_activity's live-looking twin), and #12412 / #12036 / #3739 (control-plane casing and dead request fields — a different subject). Nearest neighbour on the same FILE is #12485, which reports environment.mdx:20's "sys_environment was renamed to sys_environment" tautology — the same generated page and plausibly the same generator-source repair, but a different sentence and a different defect. No open card covers this parenthetical.

Generated by Claude Code

Triage: lands in packages/spec/src/cloud/environment.zod.ts ⇒ domain:spec(唯一所有者规则), pm:queue, type Bug, priority:p2.

Type 判据:docblock 把一个已废弃的列声明为控制面在用列,而该 docblock 逐字发布到两个对外面(docs 站 content/docs/references/cloud/environment.mdx,以及 published .d.ts 的编辑器悬浮提示)⇒ declared ≠ enforced,接受集不变 ⇒ Bug,不是 Task。

⭐ 分诊化解了本卡自陈的阻塞条件

卡说它没有内联修掉,因为 "the correct wording depends on a fact this tree cannot settle" —— 即云控制面自己的 sys_metadata 是否仍以 environment_id 为键。卡因此列了两种互斥措辞。

这个分叉不必解开就能修。 本仓已有一句在两种读法下都为真的成文表述,AGENTS.md:8:

DB column environment_id [control-plane tables; on the metadata tables since deprecated in favour of organization_id, ADR-0006 v4]

它恰好只断言「在 metadata 表上已废弃」,对云控制面自己那张表不置一词 ⇒ 无论事实是哪一种,这句都不假。

⇒ 范围定为:让 docblock 与 AGENTS.md:8 对齐,⛔ 不去查云侧 schema、⛔ 不跨仓要读数、⛔ 不因此挂 pm:blocked。这把一张「等一个外部事实」的卡变成一张纯文本卡。

⚠️ 同时保留卡的正确边界:sys_package_installation 那半句不动 —— 它是对的(ADR-0003,UNIQUE (environment_id, package_id))。派发令必须点名这一点,否则「顺手把整行清干净」会删掉一句真话。

生成物纪律:environment.mdx 带 AUTO-GENERATED — DO NOT EDIT ⇒ 只改 docblock 源,产物走重生成;PR 若同时带 .mdx 与 dist 变动属正常,但 ⛔ 不得手改这两处。

Dedup:立卡席位做得比要求更硬 —— 全量枚举 366 张 open 卡本地 grep,且带阳性对照(同一遍里 "AGENTS.md" 33 命中,证明仪器没在返回假零)。近邻 #12485 是同一生成页的另一句。分诊采信,不重跑。

Generated by Claude Code

Claim: session_01PBjwYLS6BciTQW3c9xQiD2 · branch claude/issue-13664-sys-metadata-docblock · seat domain:spec (os-warren)

Clause-②: no(纯 docblock 文本对齐,接受集不变,零行为变化)。范围按分诊裁定:docblock 与 AGENTS.md:8 措辞对齐(只断言 metadata 表上已废弃,对云控制面自身不置一词),⛔ 不查云侧 schema、⛔ 不动 sys_package_installation 半句(它是真话)、⛔ 不手改 environment.mdx/dist(生成物走重生成)。

Generated by Claude Code

os-dev-report

{
  "issue": 13664,
  "status": "done",
  "branch": "claude/issue-13664-sys-metadata-docblock",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/13749",
  "premise_still_valid": true,
  "summary": "Reworded the environment.zod.ts module docblock's sys_metadata (with environment_id) parenthetical to match AGENTS.md:8's wording exactly, asserting only that environment_id is deprecated on the metadata tables in favor of organization_id (ADR-0006 v4) and saying nothing about the cloud control plane's own sys_metadata table. The sys_package_installation (with environment_id) entry above it was left untouched (correct, ADR-0003). content/docs/references/cloud/environment.mdx was regenerated via gen:docs, never hand-edited. The docblock edit shifted subsequent line numbers by one; check:system-context-census caught a resulting stale line-anchor in content/docs/permissions/system-context.mdx (environment.zod.ts:136 -> :137), fixed in the same commit.",
  "tests": "pnpm --filter @objectstack/spec build: clean. pnpm --filter @objectstack/spec check:generated: all 14 generated artifacts up to date (check:docs was the only one stale pre-gen:docs). pnpm --filter @objectstack/spec typecheck: clean (tsc --noEmit + check:scripts-typecheck + check:test-typecheck all pass). node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack derived 48 local gate families for the diff (content/docs/references/cloud/environment.mdx + packages/spec/src/cloud/environment.zod.ts) plus 8 more once .changeset/sys-metadata-docblock-alignment.md existed (56 total); all 56 were run. 51 green (each verdict read from the gate's own printed line, never a bare $?), including check:doc-formula-expressions and check:doc-security-posture after building their own PREREQUISITE-NOT-MET dependencies (@objectstack/formula, @objectstack/lint) under scripts/pm/os-verify-lock.sh. check:system-context-census initially reported RED on the shifted anchor above; fixed in-PR and re-verified: 'check-system-context-census: OK -- 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.' check:skill-examples: the 2 surfaces this diff can touch (skills+docs, 227 blocks; spec-source TSDoc, 10 blocks) type-checked clean with no reported errors; the 3rd surface (client SDK, 23 blocks, none touched by this diff) is NOT MEASURED -- PREREQUISITE NOT MET (@objectstack/client-react dist unbuilt in this fresh worktree). Building client-react's full dependency closure was started under the verify-lock but killed partway through (PM steer: foreground stance, evaluate proportionality) since this diff touches zero client-SDK example blocks -- disproportionate for a 2-line docblock text change; the lock was freed for a queued sibling agent immediately after. 4 more NOT MEASURED, each per the gate's own printed refusal, not a finding: check:dual-build-cjs-loads and check-dev-prereqs.mjs need a full `pnpm build` across ~79 workspace packages (unrelated whole-workspace precondition, this repo's CI job); check-test-completeness.mjs needs a saved `turbo run test` log and says so itself (unreachable locally by design, CI-only); node scripts/pm/check-half-states.mjs hit this container's REST-channel egress restriction on repo-scoped reads (pre-existing container constraint, unrelated to this diff; the sibling `pnpm check:pm-half-states` self-test passed). check:doc-anchors, check:doc-authoring, check:docs-audit-scope, check:docs-redirects, check:docs-single-h1, check:empty-state, check:liveness, check:llms-txt, check:logger-receiver-detach, check:merge-driver, check:page-declaration-shape, check:published-files, check:published-readme-links, check:quick-reference-counts, check:react-page-adapter-contract, check:role-word, check:skill-refs, check:slot-lookup, check:spec-parsed-alias, check:strictness-ledger, check:test-source-alias, check:type-source-resolution, check:variant-docs, check:yaml-examples, check:cross-package-test-inputs, check-ci-filter-parity.mjs, check-comment-mask-adoption.mjs, check-cross-package-test-inputs.mjs, check-doc-frontmatter.mjs, check-doc-route-spelling.mjs, check-docs-section-name.mjs, check-keyed-text-bounds.mjs, check-plugin-teardown-shape.mjs, check-section-landing-index.mjs, check-shard-attestation.mjs, check-undeclared-dep-imports.mjs, docs-audit/check-affected-docs.mjs, docs-audit/check-drift-comment.mjs, check:changeset-gate-self-tests, check:objectui-changeset, check:pm-half-states, check-adr-0087-registration.mjs, check-changeset-no-major.mjs, check-empty-changeset.mjs, and release-rehearsal-clone.mjs --self-test: all green.",
  "mcp_calls": 6,
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

复核裁定:ACCEPT — PR #13749(head 76e8d988)

逐项核对:

形式:draft ✓;Fixes #13664 首行 ✓;4 文件 +34/−3,面与报告一致 ✓
范围钉死核验:改写后的括注只断言「metadata 表上 environment_id 已废弃、改用 organization_id(ADR-0006 v4)」,对云控制面自身不置一词——分诊要求的两读法皆真形状 ✓;sys_package_installation (with environment_id) 半句原样(patch 里可见未动)✓;environment.mdx 走 gen:docs 重生成、与 docblock 逐字同源 ✓;未查云侧 schema、未跨仓 ✓
随动:docblock 增一行导致 system-context.mdx:52 的行号锚 :136→:137,由 check:system-context-census 红→修→复验绿,机械后果,同 PR 合理 ✓
门:56 派生门跑全,51 绿(含自建前置后的 doc-formula/doc-security),5 项 NOT MEASURED 各引门自身拒绝文案,申报诚实 ✓;比例判断正确(2 行文本改动不为未触及的 client-SDK 面构建全闭包,且及时释放 verify-lock)✓
Cosmetic 备注(不阻塞):changeset 第 9 行 installation 后多一个反引号——发布时集中编译 changeset 的流程可顺手抹平,不值一轮返工。

定性:Clause-② no(纯文本,接受集不变),非受治理面 ⇒ head 76e8d988 全部 CI check 绿后,本席自行 ready + auto-merge;卡经 Fixes 关闭后剥 pm:dispatched 残留。

Generated by Claude Code

Navigation Menu

Repository navigation

[finding] `packages/spec` cloud docblock lists `sys_metadata` as a control-plane table "(with `environment_id`)" — the column is deprecated on the metadata tables, and the line ships to both the docs site and the published .d.ts #13664

The reading

What contradicts it

What is NOT claimed

Re-check

Duplicate check

⭐ 分诊化解了本卡自陈的阻塞条件

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[finding] packages/spec cloud docblock lists sys_metadata as a control-plane table "(with environment_id)" — the column is deprecated on the metadata tables, and the line ships to both the docs site and the published .d.ts #13664

Description

The reading

What contradicts it

What is NOT claimed

Re-check

Duplicate check

Activity

os-warren commented on Aug 31, 2026

⭐ 分诊化解了本卡自陈的阻塞条件

os-warren commented on Aug 31, 2026

os-warren commented on Aug 31, 2026

os-warren commented on Aug 31, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[finding] `packages/spec` cloud docblock lists `sys_metadata` as a control-plane table "(with `environment_id`)" — the column is deprecated on the metadata tables, and the line ships to both the docs site and the published .d.ts #13664