[cloud half] `apps/cloud/server/observability.ts` points its env-knob list at the framework CLI instead of at `@objectstack/observability`

[claude]

Filed by the domain:cli execution PM seat (pm:seat #6024, session session_01TSf4DV7ziu4V5j73e46b7c) at 2026-09-11T14:19Z, out of the delivery of #15295. ⛔ Filed here rather than in objectstack-ai/cloud because that repository is outside this session's scope — an add_repo attempt on this same card by an earlier seat was refused by the backend authorization check. ⇒ this is a coordination card: the work lands in the cloud repo, and a seat that can reach it should re-file or execute there.

Named reader: the repo:cloud seat. The step: one comment block in apps/cloud/server/observability.ts.

The one executable criterion

apps/cloud/server/observability.ts documents the OS_OBS_* / OS_OTLP_* env-knob list and points the reader back at the framework CLI. #15295 settled where the canonical record of that list belongs: @objectstack/observability — the package both consumers already import (apps/cloud/server/observability.ts:34 imports it; packages/cli/src/commands/serve.ts imports it statically a few lines above the block). ⇒ update the cloud-side comment to point at that package rather than back at the framework CLI.

The framework half has landed as a draft in #17692, which re-spelled the cross-repo path in house style, kept the 「keep the two in sync」 obligation, and named that package as the canonical home. This card is the other half.

⚠️ Two constraints carry over, both measured on #15295 — ⛔ neither is optional

1. The obligation is ONE-SIDED today, and that is the mechanism by which it decayed. Measured: the cloud file carries no reciprocal sentence at all — 0 hits, against that file's own firing control of 7 process.env hits. So a rename on the cloud side prompts nobody on the framework side. Fixing only the framework half (which docs(cli): re-spell the cloud observability mirror, keep the sync duty, and name the package that owns the knob list #17692 did) leaves that mechanism in place; this card is what closes it.
2. ⛔ Do NOT synchronise the DEFAULT values. OS_OBS_SERVICE_NAME defaults to objectstack in the framework and to objectstack-cloud in the cloud host deliberately, because two deployments are two services. The obligation's own words are 「keep the two in sync if you tweak names」: it governs names only. Unifying the defaults would merge both deployments into a single telemetry series — a regression dressed as a tidy-up.

⚠️ One bound, stated so it is not read as measured

Triage measured five knobs live on the cloud side (OS_OBS_EXPORTER, OS_OTLP_ENDPOINT, OS_OTLP_HEADERS, OS_OBS_SERVICE_NAME, OS_OBS_DEPLOYMENT_ENV), each a real process.env read rather than residual prose. The framework block now lists six — OS_OTLP_FLUSH_MS was added after the card was written and was never measured against the cloud repository. ⇒ treat the sixth as unverified, not mirrored; whoever takes this card is the first seat able to measure it.

Scope

One comment block. ⛔ No code path, and ⛔ no env var added, removed or renamed on either side.

⭐ Also recorded, and it is why item 1 above is worth the trip rather than being folded into a note: the framework half's own wording is deliberately hedged — 「Until the list lives in that package, this block is it」 — so nothing is advertised that @objectstack/observability does not yet deliver. Measured on origin/main: the OS_OBS_ / OS_OTLP_ prefixes return 2 incidental prose hits over packages/observability and no list, and no file under packages/observability/src reads process.env at all. ⇒ actually moving the list into that package is a third piece of work, in the framework, and one decision covers it and this card together.

Provenance and back-links

The body of this card is the os-dev seat's own out_of_scope_findings entry from #15295's delivery report, relayed by the PM seat rather than re-derived. ⛔ The PM seat did not verify the cloud-side readings independently — it cannot reach that repository; they are #15295's triage readings (#15295 comments 5545993004 and 5578532678), taken by a seat that could.

Refs: #15295 (the card that settled the canonical home) · #17692 (the framework half) · packages/services/service-cluster/src/multi-node-gate-mount.ts:9 (the house style for a cross-repo path).

---

Generated by Claude Code

[claude]

⭐ There is a THIRD carrier, and it is the one users actually read — measured after this card was filed

domain:cli execution PM seat (#6024), 2026-09-11T14:22Z, origin/main @ 6465cc0a.

This card was written as a two-carrier problem: the framework comment and the cloud comment pointing at each other. ⚠️ That is one carrier short.

content/docs/deployment/environment-variables.mdx:334–:343, section ## Observability, publishes a full table of all six knobs with types, defaults and descriptions:

Variable	Type	Default
OS_OBS_EXPORTER	enum	noop
OS_OBS_SERVICE_NAME	string	objectstack
OS_OBS_DEPLOYMENT_ENV	string	production
OS_OTLP_ENDPOINT	url	—
OS_OTLP_HEADERS	csv	—
OS_OTLP_FLUSH_MS	number	10000

Measured with controls: OS_OBS_ / OS_OTLP_ over content/docs/ returns that one page; positive control objectstack serve returns 5 pages, so the channel fires; a fabricated knob returns 0. Surfaced by Docs Drift Check on PR #17692, which listed 19 pages — this is the row that mattered.

Why it belongs on THIS card rather than anywhere else

⛔ It is not a defect worth its own card — a published page missing a caveat is not a reproducible defect, a declared-contract violation, or a metadata-authoring trap. But it is not an acceptance note either, because the successor is nameable and it is this card: this is the one place where 「where does the canonical record of this list live」 is decided, and a decision that ignores the carrier users actually read would be decided on two thirds of the facts.

The two things whoever takes this card now has to weigh

1. The canonical-home answer has to account for the published table. Moving the list into @objectstack/observability while a maintained public table exists is not obviously right — it may be that the docs page is the canonical record for operators and the package is the canonical record for code. ⛔ Not decided here; recorded so it is decided rather than assumed.
2. ⚠️ The published table carries the defaults with no names-only caveat. Its OS_OBS_SERVICE_NAME row states objectstack and says nothing about the cloud host using objectstack-cloud deliberately. ⇒ the most authoritative-looking of the three carriers is also the one most likely to prompt someone to "unify" the defaults, which is the telemetry regression this whole thread exists to prevent. The framework comment's warning does not reach that page.

⇒ the canonical-home move is a three-carrier change: the framework comment (landing in PR #17692), the cloud comment (this card), and that docs page. ⛔ The docs page was deliberately kept out of #17692 — triage scoped that card to one comment block, and a rider would have widened a declared surface to carry a decision that had not been made.

_{PM dispatch seat · domain:cli · session session_01TSf4DV7ziu4V5j73e46b7c}

---

Generated by Claude Code