Skip to content

Commit b55d6ab

Browse files
fix(service-settings): the settings manifest list serves a sourced select's options, the table the save judges against (#30568)
<!-- claude-projects-attribution: {"github_login":"os-bill"} --> _Requested by **Bill** · [project thread](https://claude.ai/code/project/chan_016iMXWSZDzqWRWvWzdNo8wg?thread=cmsg_016iMXWSZDzqWRWvWzdNo8wgM7Q68LNSRHwuQMpf4XmEdG)_ 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](https://claude.ai/code/session_01Utp6CZMwT3iajiQDWrXgCn)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 1756666 commit b55d6ab

6 files changed

Lines changed: 95 additions & 14 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/service-settings': patch
3+
'@objectstack/spec': patch
4+
---
5+
6+
fix(service-settings): the settings manifest list serves a sourced select's options, the table the save judges against, as the namespace read does
7+
8+
Clause-②: no — the manifest list now states the table the save already enforces; nothing a caller sends is refused differently.
9+
Metadata-protocol: none
10+
11+
A select key whose options come from the running system (`localization.locale`: the languages the deployment's i18n service reports) was served its live options only by the namespace read (`GET /api/settings/:namespace`). `SettingsService.getManifest()`, `SettingsService.listManifests()` and `GET /api/settings` still carried the declared table (the four codes `en-US`, `zh-CN`, `ja-JP`, `es-ES`), so a reader of the manifest list (the Setup hub, an SDK caller) was told a table that is not the one a save is judged against.
12+
13+
- **Now.** All three are served through the same resolution as the namespace read: a sourced key carries its source's options; every other key, and a sourced key whose source has no answer (no i18n service in the composition), carries the declared table as before. `getManifest(namespace, display?)` and `listManifests(ctx?, display?)` take an optional display language; `GET /api/settings` passes the request's. The registered manifest is never changed.
14+
- **Spec.** The `valueDomain` description in `settings-manifest.zod.ts` names the runtime option source beside `valueDomain` as the other mover of a select's enforcement boundary: where a source answers, the declared `options` are the fallback.

‎packages/services/service-settings/src/localization-locale-options.test.ts‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,11 +121,48 @@ describe('localization.locale serves the deployment\'s locale list', () => {
121121
expect(options.map((o) => o.value)).toEqual(['en-US', 'zh-CN', 'fr', 'vi-VN']);
122122
expect(options.slice(0, 3).map((o) => o.label)).toEqual(['English', '简体中文', 'Français']);
123123
expect(options[3].label).toBe(localeSelfName('vi-VN'));
124-
// The registered manifest is left as declared.
124+
// The registered manifest is left as declared: once the source has no
125+
// answer, the manifest read is the declared four again.
126+
booted.i18n.locales = [];
125127
const declared = (booted.service.getManifest('localization').specifiers as any[]).find((s) => s.key === 'locale');
126128
expect(declared.options.map((o: { value: string }) => o.value)).toEqual(['en-US', 'zh-CN', 'ja-JP', 'es-ES']);
127129
});
128130

131+
it('the manifest list serves the table the namespace read serves and the save judges against', async () => {
132+
booted.i18n.locales = ['en', 'zh-CN', 'fr-FR', 'vi-VN'];
133+
// An offered value in effect, so the namespace read offers the list as reported.
134+
expect((await save(booted.http, { locale: 'fr-FR' })).status).toBe(200);
135+
136+
const list = await call(booted.http, 'GET /api/settings');
137+
expect(list.status).toBe(200);
138+
const listed = (list.body.data.manifests as any[])
139+
.find((m) => m.namespace === 'localization')
140+
.specifiers.find((s: { key?: string }) => s.key === 'locale').options as Array<{ value: string; label: string }>;
141+
const page = servedLocaleOptions((await getPage(booted.http)).body);
142+
expect(listed).toEqual(page);
143+
expect(listed.map((o) => o.value)).toEqual(['en', 'zh-CN', 'fr-FR', 'vi-VN']);
144+
// In-process readers are told the same table.
145+
const read = (booted.service.getManifest('localization').specifiers as any[]).find((s) => s.key === 'locale');
146+
expect(read.options).toEqual(listed);
147+
const inProcess = booted.service.listManifests().find((m) => m.namespace === 'localization')!;
148+
expect((inProcess.specifiers as any[]).find((s) => s.key === 'locale').options).toEqual(listed);
149+
150+
// The save's boundary is that table: every listed value saves, the
151+
// declared `ja-JP` the list leaves out is refused naming the listed values.
152+
for (const { value } of listed) {
153+
expect((await save(booted.http, { locale: value })).status).toBe(200);
154+
}
155+
const refused = await save(booted.http, { locale: 'ja-JP' });
156+
expect(refused.status).toBe(400);
157+
expect(refused.body.error.details.fields).toEqual([
158+
expect.objectContaining({
159+
field: 'locale',
160+
code: 'invalid_option',
161+
constraint: { allowed: listed.map((o) => o.value).join(', ') },
162+
}),
163+
]);
164+
});
165+
129166
it('accepts a language the deployment supports that the declared four never named', async () => {
130167
booted.i18n.locales = ['en', 'zh-CN', 'fr-FR'];
131168
const saved = await save(booted.http, { locale: 'fr-FR' });

‎packages/services/service-settings/src/settings-routes.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -273,8 +273,9 @@ export function registerSettingsRoutes(
273273
};
274274

275275
mountFamilyRoute('get', base, {
276-
async serve(_req, res, ctx) {
277-
const manifests = service.listManifests(ctx);
276+
async serve(req, res, ctx) {
277+
// Served as the namespace read serves them: a sourced key's options.
278+
const manifests = service.listManifests(ctx, { locale: requestLocaleOf(req) });
278279
sendOk(res, { manifests });
279280
},
280281
refuse(res, err) {

‎packages/services/service-settings/src/settings-service.ts‎

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1572,11 +1572,16 @@ export class SettingsService {
15721572
else console.error(message);
15731573
}
15741574

1575-
/** Look up a manifest, or throw `UnknownNamespaceError`. */
1576-
getManifest(namespace: string): SettingsManifest {
1575+
/**
1576+
* Look up a manifest, or throw `UnknownNamespaceError`. A key with a
1577+
* registered option source carries the source's options, as the namespace
1578+
* read serves them ({@link servedManifest}); every other key carries its
1579+
* declared table. `display.locale` is the language the options are named in.
1580+
*/
1581+
getManifest(namespace: string, display: SettingsDisplayOptions = {}): SettingsManifest {
15771582
const reg = this.registry.get(namespace);
15781583
if (!reg) throw new UnknownNamespaceError(namespace);
1579-
return reg.manifest;
1584+
return this.servedManifest(reg, namespace, {}, display);
15801585
}
15811586

15821587
/**
@@ -1605,10 +1610,16 @@ export class SettingsService {
16051610
}
16061611
}
16071612

1608-
/** List all registered manifests, optionally filtered by permission. */
1609-
listManifests(ctx: SettingsContext = {}): SettingsManifest[] {
1613+
/**
1614+
* List all registered manifests, optionally filtered by permission. Each is
1615+
* served as {@link getManifest} serves it: a sourced key carries the options
1616+
* the save judges against, not the declared table the source replaces.
1617+
*/
1618+
listManifests(ctx: SettingsContext = {}, display: SettingsDisplayOptions = {}): SettingsManifest[] {
16101619
const perms = new Set(ctx.permissions ?? []);
1611-
const all = Array.from(this.registry.values()).map((r) => r.manifest);
1620+
const all = Array.from(this.registry.entries()).map(([namespace, reg]) =>
1621+
this.servedManifest(reg, namespace, {}, display),
1622+
);
16121623
// Empty permissions ⇒ pass-through ONLY for a trusted (non-enforced)
16131624
// in-process caller. An ENFORCED HTTP caller with no capabilities sees only
16141625
// the manifests it may read — never the whole set (Finding-1: an
@@ -1742,9 +1753,13 @@ export class SettingsService {
17421753
}
17431754

17441755
/**
1745-
* The manifest a page is served: the registered one, with each sourced
1746-
* key's `options` replaced by its source's answer for the value in effect.
1747-
* The registered manifest itself is never changed.
1756+
* The manifest a reader is served: the registered one, with each sourced
1757+
* key's `options` replaced by its source's answer. The one resolution every
1758+
* manifest read goes through: the namespace read passes the values in
1759+
* effect, so the answer can offer the stored value as stored;
1760+
* {@link getManifest} and {@link listManifests} pass none, and are served
1761+
* the options a write is judged against. The registered manifest itself is
1762+
* never changed.
17481763
*/
17491764
private servedManifest(
17501765
reg: RegisteredManifest,

‎packages/services/service-settings/src/settings-service.types.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -500,7 +500,9 @@ export interface SettingsOptionSourceAnswer {
500500
* absent from the composition).
501501
*
502502
* Asked at the moment it is used, never recorded: on each save (the write's
503-
* acceptance), on each read of an `OS_*` override, and on each page read. It
503+
* acceptance), on each read of an `OS_*` override, on each page read, and on
504+
* each manifest read (`getManifest`, `listManifests`, `GET /api/settings`),
505+
* so every reader of the key's options is told the table a save judges. It
504506
* is not asked when the manifest registers, because what it reads registers
505507
* later in the boot, so an `OS_*` override of such a key is judged when it is
506508
* read.
@@ -510,7 +512,8 @@ export type SettingsOptionSource = (input: {
510512
* The key's value in effect on the page being served, so the answer can
511513
* offer it as stored: under its own spelling when it is a second spelling
512514
* of an offered value, and named as no longer offered when it is not
513-
* admitted. Absent when a write or an override is judged.
515+
* admitted. Absent when a write or an override is judged, and when a
516+
* manifest is read outside a page (`getManifest`, `listManifests`).
514517
*/
515518
current?: unknown;
516519
/** The language the page is read in, {@link SettingsDisplayOptions.locale}. */

‎packages/spec/src/system/settings-manifest.zod.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -499,6 +499,17 @@ export const SpecifierSchema = lazySchema(() => z.object({
499499
* `sms.provider` — where "legal" means "this deployment ships an adapter for
500500
* it", not "some registrar published it". Do not add `valueDomain` to those.
501501
*
502+
* **The one other boundary mover is a runtime option source.** A select whose
503+
* legal values are what the running deployment supports (`localization.locale`:
504+
* the languages its i18n service reports) has its table served by the
505+
* settings service from that system, not from this declaration. Where a
506+
* source answers, its options are what a write is judged against and what
507+
* every manifest read serves (the namespace read and the manifest list
508+
* alike); the declared `options` are the fallback, standing only while the
509+
* source has no answer (the system it reads is absent from the composition).
510+
* That is a runtime registration, not an authorable key: a manifest cannot
511+
* declare one.
512+
*
502513
* `pattern` / `minLength` / `maxLength` still apply and still narrow: they
503514
* constrain the *shape* of the string, the domain constrains its
504515
* *membership*. A value must satisfy both. Reach for `valueDomain` precisely

0 commit comments

Comments
 (0)