[objectstack-fleet]

Requested by Bill · project thread

domain:server#4 · os-bill · session_01Utp6CZMkHvuDeVYgTD73qF

维护者速读

• 改了什么： 设置清单接口（GET /api/settings，以及服务内的 getManifest / listManifests）现在给「默认语言」这类由运行时来源决定选项的下拉框，返回和单个命名空间页面、和保存校验同一份选项（部署实际支持的语言），不再返回清单里写死的四种；spec 的说明同步写明这个例外。
• 为什么改： 上一张卡让「默认语言」页面和保存都改读部署语言列表，但设置总览和 SDK 读的清单接口还在说老四种，读清单的人看到的表和保存时真正判定的表不一致。
• 风险与回滚： 不收窄（Clause-②: no）：保存接受什么、拒绝什么一点没变，只是清单如实说出来；没有 i18n 服务的组合仍返回原来四种；登记的清单对象本身不被改动。回滚即撤本 PR。
• 先看： packages/services/service-settings/src/settings-service.ts 里 getManifest / listManifests 改为走 servedManifest 的两处；settings-routes.ts 清单路由传请求语言的一行；packages/spec/src/system/settings-manifest.zod.ts 中 valueDomain 说明新加的一段。
• 两分钟验证： pnpm --filter @objectstack/service-settings exec vitest run --maxWorkers=2 src/localization-locale-options.test.ts，预期 15 条全绿，其中「the manifest list serves the table the namespace read serves and the save judges against」一条。
• 需要你做的： 无，席位落地。

Fixes #30455

Clause-②: no — the manifest list now states the table the save already enforces; nothing a caller sends is refused differently.
Metadata-protocol: none

What changes

One resolution for every manifest read (settings-service.ts). PR #30446 added servedManifest, which replaces a sourced key's options with its option source's answer, and only the namespace read (getNamespace, GET /api/settings/:namespace) went through it. getManifest() and listManifests() returned the registered manifest, so GET /api/settings served localization.locale's declared four (en-US, zh-CN, ja-JP, es-ES) while the save judged the i18n service's list.

• getManifest(namespace, display?) and listManifests(ctx?, display?) now return servedManifest(reg, namespace, {}, display): no values in effect are passed, so the source answers the options a write is judged against (no stored-value spelling or "no longer offered" entry, which belong to a page). A namespace with no source, or a source with no answer, is returned as the registered object itself, unchanged identity.
• The display argument is optional; existing callers (localization-currency-lock.ts, cloud-connection runtime-config-plugin.ts, plugin-security upgrade-impact-report.ts) compile and behave as before for every unsourced namespace.
• GET /api/settings passes the request's language (requestLocaleOf, the namespace read's helper), one line.
• SettingsOptionSource's docblock (settings-service.types.ts) names the manifest reads among the moments a source is asked.

Spec (packages/spec/src/system/settings-manifest.zod.ts, TSDoc only). The valueDomain docblock said a select without valueDomain keeps options as its exhaustive save boundary. It now names the runtime option source as the other boundary mover: where a source answers, its options are what a write is judged against and what every manifest read serves; the declared options are the fallback; it is a runtime registration, not an authorable key. No .describe() string changed, so no generated artifact moved (check:generated: 14 of 14 up to date after a spec build).

Tests

localization-locale-options.test.ts (real LiteKernel boot, real settings routes), one new case and one adjusted:

• New: with the i18n list ['en', 'zh-CN', 'fr-FR', 'vi-VN'] and fr-FR in effect, GET /api/settings's localization.locale options equal the namespace read's served options and getManifest / in-process listManifests answer the same; every listed value saves 200, and the declared ja-JP the list leaves out is refused invalid_option with constraint.allowed equal to the listed values.
• Adjusted: the first case asserted getManifest returns the declared four while a source answers. It now asserts that once the source has no answer ([]), getManifest is the declared four again, which is what proves the registered manifest was never changed.

Ablation through scripts/ablation-replace.mjs: listManifests made to return reg.manifest ⇒ the new case red, 14 others green; restored, blob equal to HEAD, git diff HEAD empty.

Acceptance notes

• getManifest is now a served read like the namespace read. No caller in the tree needs the declared table from it: the one in-package caller (registerLocalizationCurrencyLock) only probes that the namespace exists.
• listManifests asks each namespace's sources before the permission filter; only localization.locale has one today, and a source is a synchronous in-memory read.

Verification

All at head 1b5ca0e2 (the branch with origin/main 86ae2ca merged), after pnpm install --frozen-lockfile (exit 0) and a full build (turbo run build --filter='!@objectstack/docs', 119/119, under the verify lock):

• pnpm --filter @objectstack/service-settings test: 69 files, 1172 passed; typecheck: exit 0 (both before the merge; the merged commits touch neither this package nor its dependencies' sources this diff reads).
• pnpm --filter @objectstack/spec build exit 0, then check:generated: 14 of 14 artifacts up to date.
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 83 families from the change set; each run with its exit recorded before any pipe: 83 of 83 exit 0. --ran: 83 derived, 83 run, 0 NOT-MEASURED, exit 0.
• pnpm lint: exit 0.
• Full dogfood: not run. The title carries no ! and Clause-② carries no (narrowing) arm.
• CI check-runs: not yet reported at opening.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/service-settings, @objectstack/spec, touching 7 documentable anchor(s).

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

• content/docs/data-modeling/drivers.mdx (via SettingsService (symbol, a top-level class))
• content/docs/deployment/environment-variables.mdx (via /api/settings (route, a path literal in a comment on a changed line))
• content/docs/permissions/authentication.mdx (via /api/settings (route, a path literal in a comment on a changed line))
• content/docs/protocol/kernel/config-resolution.mdx (via SettingsService (symbol, a top-level class), registerSettingsRoutes (symbol, a top-level function), /api/settings (route, a path literal in a comment on a changed line))
• content/docs/protocol/kernel/error-handling.mdx (via /api/settings (route, a path literal in a comment on a changed line))
• content/docs/protocol/kernel/index.mdx (via SettingsService (symbol, a top-level class))

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

• content/docs/releases/v14.mdx (via /api/settings (route, a path literal in a comment on a changed line))
• content/docs/releases/v17/17-7.mdx (via /api/settings (route, a path literal in a comment on a changed line))

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

• the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 103 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 172 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 48b3ae6eb7cd234dcdea467fb55dd493a56bb0c2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 7db957c009463b764664ba83afe2cf9f287c65e4 — the merge of head 1b5ca0e23ff6d92a22922e4b665184b0dabf9049 into base 48b3ae6eb7cd234dcdea467fb55dd493a56bb0c2, 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 7db957c009463b764664ba83afe2cf9f287c65e4 && git checkout 7db957c009463b764664ba83afe2cf9f287c65e4
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 48b3ae6eb7cd234dcdea467fb55dd493a56bb0c2 1b5ca0e23ff6d92a22922e4b665184b0dabf9049 && git checkout -B drift-repro 48b3ae6eb7cd234dcdea467fb55dd493a56bb0c2 && git merge --no-ff 1b5ca0e23ff6d92a22922e4b665184b0dabf9049

node scripts/docs-audit/affected-docs.mjs --json 48b3ae6eb7cd234dcdea467fb55dd493a56bb0c2

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

[objectstack-fleet]

domain:server#4 · os-bill · session_01Utp6CZMkHvuDeVYgTD73qF

维护者速读

1. 改了什么：设置清单列表（GET /api/settings、getManifest、listManifests）对有运行时选项来源的下拉键（localization.locale），现在给出来源的实际选项，与命名空间读取和保存校验同一张表；spec 里 valueDomain 的说明补一段讲运行时选项来源。
2. 为什么改：之前清单列表仍给声明的四个语言代码，读者（Setup 首页、SDK）看到的表和保存时实际校验的表不一致。
3. 风险：低。保存的接受/拒绝不变（Clause-② no），注册的清单本身不改；来源无答复时退回声明表，与以前一致。两个方法新增的 display 参数是可选的。回滚即 revert。
4. 先看：packages/services/service-settings/src/settings-service.ts 的 getManifest / listManifests 改走 servedManifest。
5. 两分钟验证：pnpm --filter @objectstack/service-settings exec vitest run localization-locale-options。
6. 需要你做的：无，席位落地。非 BREAKING，不属 Tier H，不超 3000 行。

席位意见：ACCEPT（#30455）。设置清单列表上的语言下拉，现在和保存时认可的语言是同一张表。

席位核对

Head-sha: 1b5ca0e23ff6d92a22922e4b665184b0dabf9049 · read 2026-11-05T16:50Z

Item	Reading
Shape	Draft → main via relay pr_create; Fixes #30455. 6 files, +95/−14. packages/spec/** touched in TSDoc only (no schema change); ui/** untouched.
Seat diff read	getManifest and listManifests both resolve through the existing private servedManifest with no current, so a sourced key carries its source's answer and any other key its declared table; the route passes the request locale. The registered manifest is not mutated (the existing assertion now clears the source first to show the fallback). New test pins list = namespace read = in-process reads = the save's boundary, including the refusal of a declared value the source leaves out.
Gates (check-runs on this head)	64 completed: 54 success, 10 skipped, 0 failed.
Semver	@objectstack/service-settings: patch, @objectstack/spec: patch (TSDoc), Clause-②: no, Metadata-protocol: none.
Landing	Not governed (check-governed-merges --pr 30568: 0 of 6 paths), ≤ 3000 lines, not BREAKING, so per pm-dispatch the seat lands it: pr_ready + automerge_enable.