docs(spec): meta-read organizationId describes stop promising a supplied org is always consulted (#16524) (#20177)

Fixes #16524

Clause-②: no

## What this changes

Three published `.describe()` strings in
`packages/spec/src/api/protocol.zod.ts`, the `organizationId` member of:

| schema | was | now |
|:--|:--|:--|
| `GetMetaItemRequestSchema` | "Selects the org partition in the
ADR-0005 overlay read order … Absent = environment-wide read: only
env-level overlays apply and no org partition is consulted." | "When an
org partition applies, this selects it in the ADR-0005 overlay read
order … Supplying a value does not by itself guarantee an org partition
is consulted; where none applies, and whenever it is absent, the read is
environment-wide and only env-level overlays apply." |
| `GetMetaItemLayeredRequestSchema` | "Selects the org partition …
Absent = environment-wide read: `overlay` reports the env-level row
only." | "When an org partition applies, this selects it … Supplying a
value does not by itself guarantee an org partition is consulted; where
none applies, and whenever it is absent, the read is environment-wide:
`overlay` reports the env-level row only." |
| `GetMetaItemCachedRequestSchema` | "Selects the org partition …
exactly as on the uncached read. Also folded into the ETag, … Absent =
environment-wide read." | "When an org partition applies, this selects
it … exactly as on the uncached read. Also folded into the ETag, …
Supplying a value does not by itself guarantee an org partition is
consulted; where none applies, and whenever it is absent, the read is
environment-wide." |

Plus the regenerated `content/docs/references/api/protocol.mdx` (three
table rows) and an `@objectstack/spec` **patch** changeset.

Prose only: no key, export, accept set or runtime behaviour changes. A
supplied `organizationId` is still accepted on all three requests, and
the runtime still drops it where no org partition applies.

## Rulings carried

- Ruling B (comment 5567936958), maintainer, verbatim: 「协议不对不是应该修改协议吗？」.
The describes are protocol text, so they are corrected now. The wording
qualifies the promise, states the negative, names neither
`allowOrgOverride` nor the registry (no registry clause), and adds no
key. Its shape matches the sibling
`GetMetaItemsRequestSchema.organizationId` row reworded in PR #16523, so
the four meta-read rows now read the same way.
- Scope ruling (comment 5807019811), maintainer, verbatim: 「16524
改文档,不需要按组织取」. This PR changes published text only: no runtime change,
and no refusal of a supplied `organizationId`.
- Measured correction (comment 5612706063): on
`GetMetaItemCachedRequestSchema` only the opening sentence overstated.
The ETag sentence ("Also folded into the ETag, so a scope switch never
returns a stale 304 from another scope's cached representation.") is
true, is pinned by PR #17292, and is **kept byte-for-byte**. Its source
line does not appear in this diff.

## Premise re-verified on today's tree

Measured on `84880f9` (BASE); the merge of `369bcbed` touched no file
below.

- The gate is `organizationIdForMetaRead`
(`packages/metadata-core/src/meta-write-org-scope.ts:184`). It returns
`undefined` unless `declaresOrgOverride(type)` holds.
- `getMetaItem` (`packages/metadata-protocol/src/protocol.ts`) reads
`request.organizationId` only through the gate (`:8123`). A gated-away
value resolves `findDraft(null)` (`:8161`) and `findOverlay(null)`
(`:8227`-`:8228`), which are env-level.
- `getMetaItemLayered` gates at `:8633`. `if (orgId)` at `:8728` skips
the org overlay read entirely, and only `findOverlay(null)` runs.
- `getMetaItemCached` delegates to `getMetaItem` (`:12199`), so the same
drop applies. The ETag folds the *supplied* value (`:12294`), so the
kept ETag sentence stays true.

The runtime still behaves as the ruling describes, so no stop was
needed.

## Verification

All at head `3388f2920` (branch merged with `origin/main` `369bcbed`),
unless noted. Every heavy run went through
`scripts/pm/os-verify-lock.sh`, and each result is the `VERDICT
command-exit` line.

- `pnpm --filter @objectstack/spec build`, then `check:generated`:
before `--fix`, exactly 1 of 15 artefacts was stale
(`content/docs/references/**`). `--fix` regenerated that one, and the
three `organizationId` rows in `protocol.mdx` are the only lines that
moved. After the merge: "All 15 generated artifacts are up to date",
exit 0.
- `pnpm --filter @objectstack/spec test`: 540 files, 15820 passed and 2
todo, exit 0. `src/api/protocol.test.ts` alone: 178 passed.
- `pnpm --filter @objectstack/spec typecheck` (tsc, scripts, and the
test layer): exit 0.
- Compiled `dist` read back: the three new descriptions are present,
"allowOrgOverride" and "registry" each count 0 in them, and the ETag
sentence occurs verbatim once.
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 101 commands, the same list before
and after the merge. `--ran` reconciliation reads "101 derived, 100 run,
1 NOT-MEASURED, 0 UNRUN". All 100 that ran exited 0.
- NOT MEASURED: `pnpm check:dual-build-cjs-loads` (exit 3, PREREQUISITE
NOT MET). It needs every publishable package built: 33 still had no
`dist/` after the closure build below, and CI's `Build Core` runs it. As
a declared narrowing, I loaded every `require` entry of
`@objectstack/spec`, the only package this diff rebuilds, under CJS: 23
of 23 loaded. The gate's own `--list` names 18 spec entries, all inside
those 23. Every other package's dist is unaffected by string edits in
`packages/spec/src`.
- For five gates the first run refused with PREREQUISITE NOT MET
(unbuilt `lint` / `formula` / `client-react` / `objectql`):
`check:skill-examples`, `check:doc-formula-expressions`,
`check:doc-security-posture`, `check:docs-transcript-drift` and
`check:lean-entry-closure`. After a turbo build of that 34-task closure
they ran green. `check-plugin-teardown-shape --self-test` first refused
on the shallow clone; it went green after a depth-1 fetch of its pinned
fixture commit.
- `check:dts-closure` and `check:sourcemap-no-sources-content` swept 1
built package, `@objectstack/spec`, which is the one this diff touches.
- ESLint (narrowed, a measurement rather than a skip): `eslint
--no-inline-config --format json` over the three touched paths returns 3
entries. `protocol.zod.ts` has 0 errors and 0 warnings. The `.md` and
`.mdx` answer "no matching configuration", which means they are outside
the population defined by `eslint.config.mjs`'s `files` globs. The
config enables no type-aware linting (no `parserOptions.project`, zero
`projectService`), so this diff cannot move a verdict on any untouched
file. The repo-wide `pnpm lint` is left to CI.
- No pin test is added. These strings are prose that no consumer parses,
and pinning their wording would only freeze the wording.

## Acceptance notes

- `packages/spec/src/api/protocol.test.ts:1599`-`1602`, a test comment,
still says the implementation "accepts and HONOURS `organizationId` on
all four read verbs: it selects the org partition … it decides which
tenant's row is served". That is the same overstatement, in an
unpublished test comment. It is outside this card's claimed file
surface, so I left it. Carrier: none.
- Draft PR #19637 also regenerates
`content/docs/references/api/protocol.mdx`. Whichever PR lands second
regenerates that file; the file is routed to the `os-regen` merge
driver.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01CiCTczDo7tGhafXjf61dUJ)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/16524-meta-read-org-describes.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the `organizationId` describes on `GetMetaItemRequestSchema`, `GetMetaItemLayeredRequestSchema` and `GetMetaItemCachedRequestSchema` no longer promise that a supplied organization is always consulted (#16524)
+
+Clause-②: no
+
+Each of the three published `describe()`s opened with "Selects the org partition in the ADR-0005 overlay read order" and closed with an absent-only statement ("Absent = environment-wide read …"). Read together, an integrator completes that as *present ⇒ consulted*, and it is not: on `getMetaItem`, `getMetaItemLayered` and `getMetaItemCached` a supplied organization is dropped wherever no org partition applies, and the read resolves environment-wide exactly as if none had been sent.
+
+The corrected text takes the same shape as the sibling `GetMetaItemsRequestSchema.organizationId` describe: the parameter selects the org partition **when an org partition applies**, and supplying a value "does not by itself guarantee an org partition is consulted; where none applies, and whenever it is absent, the read is environment-wide". On `GetMetaItemCachedRequestSchema` the ETag sentence ("Also folded into the ETag, so a scope switch never returns a stale 304 from another scope's cached representation") is true and is kept byte-for-byte.
+
+Prose only. No key is added, removed or renamed, no export moves, no accept set changes and no runtime behaviour changes — a supplied `organizationId` is still accepted on all three requests, and the runtime still drops it where no org partition applies. What ships is the JSON-Schema `description` of the existing `organizationId` key on the three requests and the matching rows in the generated API reference.

content/docs/references/api/protocol.mdx

@@ -1216,7 +1216,7 @@ Enable package response
 | **name** | `string` | ✅ | Item name |
 | **cacheRequest** | `{ ifNoneMatch?: string; ifModifiedSince?: string; cacheControl?: object }` | optional | Cache validation parameters |
 | **locale** | `string` | optional | Resolved response locale. Folded into the ETag so a language switch never returns a stale-locale 304 — metadata is translated *after* the cache validator check (issue). |
-| **organizationId** | `string` | optional | Organization (tenant) scope for the read. Selects the org partition in the ADR-0005 overlay read order — org overlay wins over env-wide overlay wins over packaged artifact — exactly as on the uncached read. Also folded into the ETag, so a scope switch never returns a stale 304 from another scope's cached representation. Absent = environment-wide read. |
+| **organizationId** | `string` | optional | Organization (tenant) scope for the read. When an org partition applies, this selects it in the ADR-0005 overlay read order — org overlay wins over env-wide overlay wins over packaged artifact — exactly as on the uncached read. Also folded into the ETag, so a scope switch never returns a stale 304 from another scope's cached representation. Supplying a value does not by itself guarantee an org partition is consulted; where none applies, and whenever it is absent, the read is environment-wide. |
 
 ### Nested Shape: `GetMetaItemCachedRequest.cacheRequest`
 
@@ -1270,7 +1270,7 @@ Enable package response
 | **type** | `string` | ✅ | Metadata type name |
 | **name** | `string` | ✅ | Item name |
 | **packageId** | `string` | optional | Optional package ID — scopes the `code` layer so a same-name collision resolves to the requested package's artifact (ADR-0048). |
-| **organizationId** | `string` | optional | Organization (tenant) scope for the read. Selects the org partition in the ADR-0005 overlay read order, so it decides which tenant's customization row is reported as the `overlay` layer (and merged into `effective`). Absent = environment-wide read: `overlay` reports the env-level row only. |
+| **organizationId** | `string` | optional | Organization (tenant) scope for the read. When an org partition applies, this selects it in the ADR-0005 overlay read order, so it decides which tenant's customization row is reported as the `overlay` layer (and merged into `effective`). Supplying a value does not by itself guarantee an org partition is consulted; where none applies, and whenever it is absent, the read is environment-wide: `overlay` reports the env-level row only. |
 
 
 ---
@@ -1319,7 +1319,7 @@ Enable package response
 | **type** | `string` | ✅ | Metadata type name |
 | **name** | `string` | ✅ | Item name (snake_case identifier) |
 | **packageId** | `string` | optional | Optional package ID to filter items by |
-| **organizationId** | `string` | optional | Organization (tenant) scope for the read. Selects the org partition in the ADR-0005 overlay read order — org overlay wins over env-wide overlay wins over packaged artifact — so it decides which tenant's customization row is served as the item. Absent = environment-wide read: only env-level overlays apply and no org partition is consulted. |
+| **organizationId** | `string` | optional | Organization (tenant) scope for the read. When an org partition applies, this selects it in the ADR-0005 overlay read order — org overlay wins over env-wide overlay wins over packaged artifact — so it decides which tenant's customization row is served as the item. Supplying a value does not by itself guarantee an org partition is consulted; where none applies, and whenever it is absent, the read is environment-wide and only env-level overlays apply. |
 | **state** | `Enum<'active' \| 'draft'>` | optional | Draft-visibility switch — which lifecycle row to read (strict mode): `'draft'` opens the pending draft buffer (Studio's editor read) and fails when no draft exists; absent or `'active'` reads the live published row. Distinct from `previewDrafts`, which FALLS BACK to the active row when no draft exists. Declaration ≠ authorization: this member only selects which stored row is read — ADR-0106 masking is unaffected, and draft access is gated upstream, not by this schema. |
 | **previewDrafts** | `boolean` | optional | Draft-visibility switch (ADR-0033 draft-overlay preview, non-strict): when true and `state` is not `'draft'`, a pending draft row is preferred if one exists, else the read falls back to the active row — the render path degrades to the published value instead of erroring. A served draft is tagged `_draft: true` so UIs can badge it. Declaration ≠ authorization: this member only switches which row is read, and ADR-0106 masking is unaffected — draft preview is admin-gated upstream, not by this schema. |
 

packages/spec/src/api/protocol.zod.ts

@@ -274,11 +274,13 @@ export const GetMetaItemRequestSchema = lazySchema(() => z.object({
   name: z.string().describe('Item name (snake_case identifier)'),
   packageId: z.string().optional().describe('Optional package ID to filter items by'),
   organizationId: z.string().optional().describe(
-    'Organization (tenant) scope for the read. Selects the org partition in the '
-    + 'ADR-0005 overlay read order — org overlay wins over env-wide overlay wins '
-    + 'over packaged artifact — so it decides which tenant\'s customization row '
-    + 'is served as the item. Absent = environment-wide read: only env-level '
-    + 'overlays apply and no org partition is consulted.',
+    'Organization (tenant) scope for the read. When an org partition applies, '
+    + 'this selects it in the ADR-0005 overlay read order — org overlay wins '
+    + 'over env-wide overlay wins over packaged artifact — so it decides which '
+    + 'tenant\'s customization row is served as the item. Supplying a value '
+    + 'does not by itself guarantee an org partition is consulted; where none '
+    + 'applies, and whenever it is absent, the read is environment-wide and '
+    + 'only env-level overlays apply.',
   ),
   state: z.enum(['active', 'draft']).optional().describe(
     'Draft-visibility switch — which lifecycle row to read (strict mode): '
@@ -444,10 +446,13 @@ export const GetMetaItemLayeredRequestSchema = lazySchema(() => z.object({
     + 'resolves to the requested package\'s artifact (ADR-0048).',
   ),
   organizationId: z.string().optional().describe(
-    'Organization (tenant) scope for the read. Selects the org partition in the '
-    + 'ADR-0005 overlay read order, so it decides which tenant\'s customization '
-    + 'row is reported as the `overlay` layer (and merged into `effective`). '
-    + 'Absent = environment-wide read: `overlay` reports the env-level row only.',
+    'Organization (tenant) scope for the read. When an org partition applies, '
+    + 'this selects it in the ADR-0005 overlay read order, so it decides which '
+    + 'tenant\'s customization row is reported as the `overlay` layer (and '
+    + 'merged into `effective`). Supplying a value does not by itself guarantee '
+    + 'an org partition is consulted; where none applies, and whenever it is '
+    + 'absent, the read is environment-wide: `overlay` reports the env-level '
+    + 'row only.',
   ),
 }));
 
@@ -1818,11 +1823,14 @@ export const GetMetaItemCachedRequestSchema = lazySchema(() => z.object({
     + 'cache validator check (issue).',
   ),
   organizationId: z.string().optional().describe(
-    'Organization (tenant) scope for the read. Selects the org partition in the '
-    + 'ADR-0005 overlay read order — org overlay wins over env-wide overlay wins '
-    + 'over packaged artifact — exactly as on the uncached read. Also '
+    'Organization (tenant) scope for the read. When an org partition applies, '
+    + 'this selects it in the ADR-0005 overlay read order — org overlay wins '
+    + 'over env-wide overlay wins over packaged artifact — exactly as on the '
+    + 'uncached read. Also '
     + 'folded into the ETag, so a scope switch never returns a stale 304 from '
-    + 'another scope\'s cached representation. Absent = environment-wide read.',
+    + 'another scope\'s cached representation. Supplying a value does not by '
+    + 'itself guarantee an org partition is consulted; where none applies, and '
+    + 'whenever it is absent, the read is environment-wide.',
   ),
 }));