docs(spec): correct the stale cloud/environment.zod.ts attribution in the discovery-environment subset pin

[os-bill]

Fixes #17730

Clause-②: no

The pin test's docblock told a reader that EnvironmentTypeSchema is declared by cloud/environment.zod.ts, while the file's own import 28 lines below reads ./discovery.zod. Class (b): a declared statement contradicted by measurable behaviour in the same file. Only prose moves here — no schema, no assertion, no assertion message.

Premise, re-verified first-hand on origin/main (not taken from the card)

git ls-tree -d origin/main packages/spec/src/cloud   ->  (no output: ABSENT)
git ls-tree -d origin/main packages/spec/src/api     ->  040000 tree 61d3b3d7…   (lit control: the instrument prints a tree when one exists)
git grep -n 'EnvironmentTypeSchema *=' origin/main -- 'packages/spec/src/**'
     ->  packages/spec/src/api/discovery.zod.ts:434

Deletion traced to a commit, with a firing control:

git log --diff-filter=D -- packages/spec/src/cloud/environment.zod.ts
  ->  776d64cd3d  2026-09-10  feat(spec)!: drop the `@objectstack/spec/cloud` subpath … (#17372)
      commit body: "`EnvironmentType` is re-declared in `api/discovery.zod.ts`"
control (a file that still exists, same command):
git log --diff-filter=D -- packages/spec/src/api/discovery.zod.ts   ->  (empty, as it must be)

So #16325 is the ruling and #17372 / 776d64cd3d is the landing. The in-tree prose at api/discovery.zod.ts:412 already attributes the move to #16325 ("Until #16325 this enum was declared by cloud/environment.zod.ts"), and this docblock now matches that convention.

Line numbers were taken off the tree, not off the card: the card says the import is at :39 and the second residue at :27-28; on origin/main @ 5ed7ad9df8 they are at :40 and :26-27.

What changed — two residues, both in the docblock

1. The declaration table row (:12) now names api/discovery.zod.ts. One sentence is added below the table recording why both rows name one module, so the repetition does not read as a copy-paste slip and does not get "repaired" back.
2. The reverse cross-reference note (:26-27) named the two carrier FILES, one of which no longer exists. It now names the two DECLARATIONS — which is what that sentence is actually about, and what survives the next move.

Both cross-reference claims were re-derived rather than copied forward:

claim	verified
DiscoveryEnvironmentSchema's .describe() since #4828	git log -S'a richer 7-member taxonomy' -> 77022a99ce = #4828 (PR #5682)
EnvironmentTypeSchema's JSDoc since this pin	git log --diff-filter=A on the pin file -> 0261016601 (PR #6288), the same commit that introduced the reverse citation; carried into api/discovery.zod.ts by 776d64cd3d

The member lists were re-derived, not copied forward

The table's factual claim about each enum's vocabulary is correct and is unchanged by this PR:

• DiscoveryEnvironmentSchema (discovery.zod.ts:473) = production sandbox development — 3.
• EnvironmentTypeSchema (discovery.zod.ts:434) = those three plus test staging preview trial — 7.

The two folds the docblock cites also hold against NODE_ENV_TO_DISCOVERY_ENVIRONMENT (discovery.zod.ts:591): staging -> sandbox, test -> development.

Tests and gates

• pnpm --filter @objectstack/spec exec vitest run --project local src/api/discovery-environment-subset.pin.test.ts — 4 passed, VERDICT command-exit 0.
• pnpm --filter @objectstack/spec test — 483 files / 13775 tests passed, VERDICT command-exit 0.
• pnpm --filter @objectstack/spec typecheck — exit 0 (tsc --noEmit + check:scripts-typecheck + check:test-typecheck; the last compiles the test layer under tsconfig.test.json, which is what reaches this file).
• Dependency closure: pnpm --filter '@objectstack/spec^...' build -> "No projects matched the filters" — packages/spec has no workspace dependencies, so step 1 is an empty run. packages/spec itself was built before every dist/-reading gate, and later pnpm build (73/73 tasks successful) before the four gates that refuse without one.
• Derived gate families: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands -> 78 commands, each run with its exit code landed to disk before any pipe, reconciled with --ran: 78 derived, 78 run, 0 NOT-MEASURED, 0 UNRUN (reconciler exit 0).
• 77 of the 78 are green. The one red is pnpm check:cross-package-test-inputs (exit 1), and it is the known, already-filed local-only signature: it flags @objectstack/cli descending packages/spec/dist/, which exists only on a tree where packages/spec has been built — cards [finding] check:cross-package-test-inputs passes in CI and fails on a built tree — its verdict is a function of gitignored build state #18353 / [finding] check:cross-package-test-inputs answers 1 or 0 depending on whether packages/spec has been BUILT — the author who follows AGENTS.md is the only one who sees the red, and CI never does #18440. Not re-filed, and not caused by this diff.
• pnpm lint equivalent, run whole rather than narrowed: eslint . --no-inline-config --format json over the repo -> 6803 files, 0 errors, 0 warnings, exit 0. The population figure is eslint's own count from its --format json output, not an estimate.
• Control characters: grep -naP over the changed file finds none, and pnpm check:nul-bytes is green.

Changeset — skip-changeset, measured

packages/spec's files[] is dist · json-schema · liveness · prompts · llms.txt · README.md · src/**/*.zod.ts · CHANGELOG.md · api-surface · spec-changes.json. After a full build, grepping every one of those paths:

• the text this PR adds: 0 hits in the published paths, 0 hits in src/**/*.zod.ts;
• positive control EnvironmentTypeSchema: 12 files in the published paths, 1 in src/**/*.zod.ts — the instrument fires;
• a .pin.test.ts is not a *.zod.ts and nothing named pin is emitted into dist/.

A comment inside a test file publishes nothing from any released package, so skip-changeset is the right label and patch would be wrong.

Acceptance notes

Noted, not folded in — the same #16325 root, one line inside the test body, which this card's dispatch explicitly ring-fences ("do not change what the test asserts"):

:61 of the same file, in the failure message of the second assertion, reads "if a bucket was renamed on the cloud side, rename it here". Post-#16325 the enum is declared here, in the open-source spec, so as a statement about where a rename happens it is stale. It is also arguably still true as a statement about where a rename originates — the sys_environment row and its taxonomy remain the cloud control plane's, and DiscoveryEnvironmentSchema's own .describe() still says "that is sys_environment / EnvironmentTypeSchema". Ambiguous enough that it is a reading for the seat, not a silent edit in a prose-only PR. Reported, not filed by this seat.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 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.

Coarse fallback — 0 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 bb9794a0268163071fa976a5061290a62aeb5f2c → packageMentionDocs.