feat(spec): declare organizationId on the meta-read request schemas

[os-elon]

Fixes#9726

What

Declared-contract catch-up on the metadata read verbs (packages/spec/src/api/protocol.zod.ts), matching the shapes packages/metadata-protocol/src/protocol.ts already accepts and honours (read-only reference here — not edited):

• GetMetaItemsRequestSchema, GetMetaItemRequestSchema, GetMetaItemCachedRequestSchema: add optional organizationId (string), with .describe() docs stating what the member does — it selects the org partition in the ADR-0005 overlay read order (org overlay wins over env-wide wins over packaged artifact), i.e. it decides which tenant's row is served; on the cached verb it also enters the ETag (Org-overridable metadata (view, dashboard) is accepted with a 200 state:'active' receipt but served by no read door #9454). Optionality mirrors the enforced inline types exactly (organizationId?: string); absent = environment-wide read, all three verbs.
• New GetMetaItemLayeredRequestSchema + GetMetaItemLayeredRequest: the request shape of GET /api/v1/meta/:type/:name/layers, mirroring the implementation's inline parameter type member for member (type, name, packageId?, organizationId?), next to the already-declared layered response schema (GET /meta/:type/:name?layers=true 应答一个 spec 未声明的第三形状 —— 路由只声明了一个 responseSchema #5882).

getMetaItemLayered disposition (measured, per dispatch)

The request schema is folded in (same-shape catch-up: response schema and route already declared, request mirrors the enforced inline type exactly). The MetadataProtocol interface member is NOT added: declaring it makes tsc check the implementing class against GetMetaItemLayeredResponse, and that check fails (TS2416, measured) on exactly one member — the implementation's inline return type annotates lockSource with an 'overlay' arm that its only producer on that path (resolveLockState, typed MetadataLockSource | undefined, values filtered against the enum options) can never emit. Fixing that requires editing the read-only implementation file (narrow the dead annotation arm) or untruthfully widening the wire enum. Filed as unassigned follow-up #9740; a comment at the exact interface spot records the blocker. #9740 is not addressed here and remains open.

REST call-site casts — follow-up material, not dropped here

The as any casts at the REST read doors (packages/rest/src/rest-server.ts: the list door, the cached and uncached single-item doors) cannot drop yet: each call also threads at least one still-undeclared key (previewDrafts, state, environmentId). Removing the casts is therefore not mechanical in this diff. Filed as unassigned #9741 (also not addressed here).

Tests

• New pins in packages/spec/src/api/protocol.test.ts: each of the four request schemas accepts organizationId and preserves it through parse (the pre-change failure mode was silent stripping by the non-strict object, so success alone proves nothing); stays valid without it (env-wide read); rejects non-string values; the layered request's member set is pinned against the inline type.
• ADR-0122: GetMetaItemLayeredRequest pinned isomorphic (Iso853), count 839 → 840 with receipt.

Verification (all at head f59cf56)

• pnpm --filter @objectstack/spec test — 413 files / 10985 tests passed.
• pnpm --filter @objectstack/spec typecheck — green.
• pnpm --filter @objectstack/spec check:generated — all 13 artifacts current (api-surface, export-origins, references docs, strictness-ledger counts regenerated; authorable-surface/json-schema.manifest moved by the build).
• Consumer sweep: full pnpm build (71 tasks green) and pnpm --workspace-concurrency=2 --filter '...@objectstack/spec' typecheck — 61 downstream consumer packages green (filter direction: consumers of spec, not dependencies).
• metadata-protocol probe (npx tsc --noEmit -p packages/metadata-protocol, no typecheck script there): 63 errors, all pre-existing ledgered test-layer debt, none naming the changed surfaces; with the interface member present the count was 64, the delta being exactly the TS2416 documented above — that measurement is the basis for leaving the member out.
• Dispatch-derived gates all green at this head, including: check:cross-package-test-inputs, doc-formula-expressions, empty-state, liveness, strictness-ledger, variant-docs, merge-driver, spec-parsed-alias, type-source-resolution, dev-prereqs, affected-docs, adr-0087-registration, changeset-no-major, empty-changeset, changeset-gate-self-tests, doc-anchors, doc-authoring, docs-audit-scope, docs-redirects, objectui-changeset, published-readme-links, quick-reference-counts, role-word, query-options-erasure, type-check-coverage, type-check-debt (re-measure, no drift), engine-double-contract, where-matcher, check-nul-bytes.

Changeset: minor for @objectstack/spec (accept-set widening catch-up; no runtime behaviour change).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/kernel/services-checklist.mdx(via MetadataProtocol (symbol))

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

• content/docs/releases/v15.mdx(via MetadataProtocol (symbol))
• content/docs/releases/v17.mdx(via MetadataProtocol (symbol))

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

• 4 changed file(s) yielded no anchor (packages/spec/api-surface/api.json, packages/spec/authorable-surface/api.json, packages/spec/export-origins/api.json, …) — pages documenting those are invisible to this run

Coarse fallback — 115 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 4d80e8bcc050919e874d6ccb629c1f9cb3b1dc0e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 1397435ef4bd60732c5bfe79dec6fde496d01c32 — the merge of head f59cf5609e070fb4aece931d597bcac4362dae07 into base 4d80e8bcc050919e874d6ccb629c1f9cb3b1dc0e, 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 1397435ef4bd60732c5bfe79dec6fde496d01c32 && git checkout 1397435ef4bd60732c5bfe79dec6fde496d01c32
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4d80e8bcc050919e874d6ccb629c1f9cb3b1dc0e f59cf5609e070fb4aece931d597bcac4362dae07 && git checkout -B drift-repro 4d80e8bcc050919e874d6ccb629c1f9cb3b1dc0e && git merge --no-ff f59cf5609e070fb4aece931d597bcac4362dae07
node scripts/docs-audit/affected-docs.mjs --json 4d80e8bcc050919e874d6ccb629c1f9cb3b1dc0e

⚠️ 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 4d80e8bcc050919e874d6ccb629c1f9cb3b1dc0e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 32186054425 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (3/3) — 失败步骤: Run this shard's tests（日志不可读，点进 job 看）

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 6 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试；出现过 ⇒ flaky 实锤，开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[os-elon]

Merge-queue ejection triage (spec seat, session_016D9wdJR14KKCxz1WgdAzcw) — worked the checklist above before any re-queue:

• Failed task: @objectstack/example-showcase#test in queue build 32186054425 — NOT a package this PR touches (diff = packages/spec schema declarations + generated artifacts + tests; the full consumer sweep incl. showcase build was green at dispatch). The job-log tail shows the turbo summary (Failed: @objectstack/example-showcase#test, 82/85 tasks successful); the per-test assertion was not extractable from the retained log window.
• Checklist branch 1 ruled out by measurement: reproduced locally on the exact merged tree the queue would build next — fresh worktree, f59cf56 merged with current origin/main (da666d9, incl. docs(spec): record the second FLOW_DISABLED / FLOW_NO_START_NODE emitter #9739 which shared the 21:07 queue group), full dependency-closure build, then pnpm --filter @objectstack/example-showcase test → 21/21 files, 337/337 tests PASSED, exit 0. The failure does not reproduce from this PR's content.
• Branch 3 applies: the group ahead (docs(spec): record the second FLOW_DISABLED / FLOW_NO_START_NODE emitter #9739) has landed and its build succeeded; queue history shows 6 unrelated failed queue builds in the last 24h (ambient, per the bot's own signal). Per the at-most-once rule: re-queuing exactly once. A second red is real and gets a fresh diagnosis, not another re-queue. Not adding anything to the flaky ledger — signature extraction failed, so this stays a recorded suspicion, not a table entry.

---

Generated by Claude Code