Skip to content

Commit c9a9981

Browse files
test(dogfood): pin what the reads serve for a dependent's email template locale the base does not ship (#28779) (#28800)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"} --> _Requested by **Leehom** · [project thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XSVGL7WRVYEMMdxciqrWsuF)_ Refs #28779 Clause-②: no Metadata-protocol: none ## 维护者速读 - **改了什么**:只加了一个 dogfood 测试,把今天的实测结果钉住:依赖包(不是 `.custom`)用基础包模板的名字发布一个基础包没有的语言(showcase 的任务完成邮件,`fr-FR`),各个读取今天返回什么。没有任何产品代码改动。 - **为什么改**:#28777 合并后这种写入被当作「新增」放行了,评审要求实测基础包名下的读取会不会把依赖包的内容当成基础包的。实测结果:按名读取(指定基础包、或不指定包)会返回依赖包的法语正文(标注的是依赖包自己的包 id);但列表和真正发邮件用的执行列表都看不到它,法语收件人收到的是英文原版。两条路说法不一致。 - **风险与回滚**:零运行时风险,只新增一个测试文件;回滚即删文件。标了 SHAPE 的用例记录的是「今天的形状」,不是「正确的形状」,裁定后应随裁定改。 - **先看**:`packages/qa/dogfood/test/email-template-dependent-unshipped-locale-read.dogfood.test.ts` 的文件头(实测结论)与两个 SHAPE 用例。 - **两分钟验证**:`pnpm --filter @objectstack/dogfood exec vitest run test/email-template-dependent-unshipped-locale-read.dogfood.test.ts`,预期 6/6 通过。 - **需要你做的**:无,席位决定后续(证据已贴 #28390,卡留开着等席位裁定)。 ## What changes One new dogfood file, a shape pin over the real showcase and its HTTP doors. No product change. The card has two endings; this PR takes the second (`Refs`, not `Fixes`) because a read naming the base serves the dependent's body: | read | dependent's `fr-FR` (showcase ships `en-US` only) | |:--|:--| | `GET /meta/email_template/NAME?package=DEPENDENT&member=fr-FR` | served, `_packageId: DEPENDENT` (expected) | | `GET …?package=BASE&member=fr-FR` | **served, the dependent's body**, `_packageId: DEPENDENT`, `_provenance: org` | | `GET …?member=fr-FR` (package-less) | **served, the dependent's body**, same stamps | | `GET /meta/email_template` (env-wide), `?package=BASE`, `getMetaItemsForExecution` | `fr-FR` absent | | `IEmailService.renderTemplate({ locale: 'fr-FR' })` | the base's `en-US` | Nothing stamps the dependent's body with the base's package id, but the base's address answers it on the by-name reads, and the lists (and so the email send path) do not. Mechanism, read from code at `8f294e04`: - By-name: the served-row candidates for the base's address are the pair's declared override, the base's row and the package-unbound row (`servedOverlayRowCandidates`); none exists at `fr-FR`, and the code layer has no `fr-FR`, so the read falls to `SchemaRegistry.getItem(type, name, BASE, 'fr-FR')`, whose last tier is the legacy first composite match across packages (ADR-0048 §3.3) and holds the dependent's `fr-FR`. `registry.getArtifactItem` at the same arguments answers nothing. - Lists: the env-wide narrowing (`protocol.ts`, `soleShippingPackage(this.shippedArtifactsOf(type, itemName, …))`) keeps a name one code package ships to that package's items at NAME grain, so any other package's member of that name is dropped, whatever its locale. Controls pinned: before the dependent writes, `fr-FR` is 404 on both base-named reads; the base's own `en-US` reads as the base's on every read; the dependent's `en-US` save is refused `403 NOT_OVERRIDABLE` (the #28777 gate); the pair's declared override of `en-US` reads as the override on the by-name reads, the list and the render. ## Tests - `packages/qa/dogfood/test/email-template-dependent-unshipped-locale-read.dogfood.test.ts`: 6/6 pass at `0127ab1f` (tree identical to the head `64d937f0`). The cases named `SHAPE` record today's answer and are meant to move with the seat's ruling. - No red-first and no ablation: the diff changes no product behaviour, and a shape pin records the current behaviour. ## Acceptance notes - **Ending chosen: Refs, hand back.** The order's first ending needs the dependent's item "served only under its own package", and the read naming the base serves it too. Evidence is posted on #28390 in product words; the seat decides. - **The seat's added measurement (the pair's own new locale, no `overrides`), measured on main `8f294e04`, own boot:** admitted at save and publish; the read naming the pair, the read naming the base and the package-less read all serve the pair's `fr-FR` (stamped `_packageId: com.example.showcase.custom`); the list scoped to the pair lists it; the env-wide list, the base-scoped list and `getMetaItemsForExecution` leave it out; `renderTemplate({ locale: 'fr-FR' })` renders the base's `en-US`. So since #28777 a `fr-FR` the customer adds in `.custom` is read but never sent. Same seam as the dependent's case (the list's NAME-grain narrowing). Not fixed here: making the list member-aware would also start sending the dependent's `fr-FR` for the base's template, which is the open question above. Readings: `pm-orders/server/evidence/28779/probe3-readings.log` in the project files. - The layered view (`/layers?package=BASE&member=fr-FR`) answered 404 in every state measured; not pinned, noted only. ## Verification Gate sweep at `0127ab1f`, the same tree as the head `64d937f0` (only the commit trailer was reworded, tree `565c66dc` on both): `dispatch-gates --commands` derived 51 families; 51 run, all exit 0 (`dispatch-gates --ran` reads "51 run, 0 NOT-MEASURED", a derived zero). Two first ran exit 3 on a prerequisite and were re-run green: `check-plugin-teardown-shape --self-test` (its fixture commit was absent from the shallow clone) and `check:dual-build-cjs-loads` (seven packages outside the dogfood closure were unbuilt). `check-nul-bytes` OK. The record is `pm-orders/server/28779-gates-ran.txt` in the project files. No changeset: the only file is in the private `@objectstack/dogfood` package, so the PR carries `skip-changeset`. CI families are read from this PR's check-runs, not re-run here. <details><summary>Probe readings (dependent case)</summary> ``` PROBE after-dep base fr-FR {"status":200,"subject":"Addon FR: {{title}}","locale":"fr-FR","_packageId":"com.example.showcaseaddon","_provenance":"org"} PROBE after-dep dep fr-FR {"status":200,"subject":"Addon FR: {{title}}","locale":"fr-FR","_packageId":"com.example.showcaseaddon"} PROBE after-dep packageless fr-FR {"status":200,"subject":"Addon FR: {{title}}","locale":"fr-FR","_packageId":"com.example.showcaseaddon","_provenance":"org"} PROBE after-dep list {"status":200,"rows":[["en-US","com.example.showcase","✅ Task done: {{title}}"]]} PROBE after-dep list?package=com.example.showcaseaddon {"status":200,"rows":[["fr-FR","com.example.showcaseaddon","Addon FR: {{title}}"]]} PROBE after-dep render fr-FR "✅ Task done: T" PROBE after-dep exec-list [["en-US","com.example.showcase","✅ Task done: {{title}}"]] PROBE after-dep registry.getItem base fr {"_packageId":"com.example.showcaseaddon","_provenance":"org","subject":"Addon FR: {{title}}"} PROBE after-dep registry.getArtifactItem base fr {} ``` </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01FEkQ5pFHjQjFRsVAurERSJ)_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01FEkQ5pFHjQjFRsVAurERSJ Co-authored-by: Claude <noreply@anthropic.com>
1 parent 516119d commit c9a9981

1 file changed

Lines changed: 190 additions & 0 deletions

File tree

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
//
3+
// [#28779, ADR-0146 D2 / D8, #28390] SHAPE PIN — documents what the reads
4+
// serve TODAY when a dependent package (not the base's `.custom` pair) ships
5+
// an email template under a base template's name at a locale the base does
6+
// not ship. Over the real showcase composition and its HTTP doors.
7+
//
8+
// ⛔ This file records a measured shape; it does not assert the shape is
9+
// right. Whether a dependent's member may be served on the base's address is
10+
// open (#28779 hand-back, evidence on #28390). When that is decided, the
11+
// cases marked SHAPE below move with the ruling — that is their purpose.
12+
//
13+
// ## The rig
14+
//
15+
// The showcase ships `showcase_task_done_email` in `en-US` only. A Studio-made
16+
// package `com.example.showcaseaddon` declares the showcase as a dependency
17+
// and publishes the same name at `fr-FR`. Since PR #28777 the write gate
18+
// judges an email template by `(name, locale)`, so this is admitted as an
19+
// addition (the dependent's `en-US` at the same name is still refused).
20+
//
21+
// ## What reads today (measured on main 8f294e04)
22+
//
23+
// - the read naming the dependent serves its `fr-FR`, stamped with its own
24+
// package id — as expected;
25+
// - SHAPE: the read naming the BASE (`?package=<base>&member=fr-FR`) and the
26+
// package-less read (`?member=fr-FR`) also serve the dependent's body,
27+
// stamped `_packageId: <dependent>`, `_provenance: 'org'`. The address
28+
// finds no row of the base, its pair or no package at `fr-FR`, and the
29+
// registry's by-name read falls to its cross-package tier
30+
// (`SchemaRegistry.getItem`, ADR-0048 §3.3 first composite match);
31+
// - SHAPE: the env-wide list, the list scoped to the base and the executing
32+
// list (`getMetaItemsForExecution`) leave the `fr-FR` out — the env-wide
33+
// narrowing keeps a name one code package ships to that package's items,
34+
// at NAME grain — so a send in `fr-FR` renders the base's `en-US`.
35+
//
36+
// So the by-name reads and the lists disagree about the base's `fr-FR`, and
37+
// the body no read stamps as the base's is still answered for the base's
38+
// address. Controls: the base's own `en-US` reads as the base's on every
39+
// read, and the pair's declared override of `en-US` reads as the override.
40+
41+
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
42+
import { type VerifyStack } from '@objectstack/verify';
43+
import { bootShowcase } from './showcase-boot.js';
44+
45+
const BASE = 'com.example.showcase';
46+
const PAIR = 'com.example.showcase.custom';
47+
const DEPENDENT = 'com.example.showcaseaddon';
48+
/** The template the showcase ships, in `en-US` only. */
49+
const NAME = 'showcase_task_done_email';
50+
const SHIPPED_SUBJECT = '✅ Task done: {{title}}';
51+
const DEPENDENT_SUBJECT = 'Add-on FR: {{title}}';
52+
const OVERRIDE_SUBJECT = 'Override: {{title}}';
53+
/** The refusal's code — the save door answers it beside a string `error`, an enveloped door inside `error`. */
54+
const codeOf = (json: any): unknown => json?.code ?? json?.error?.code;
55+
56+
interface Served {
57+
status: number;
58+
subject?: unknown;
59+
locale?: unknown;
60+
_packageId?: unknown;
61+
}
62+
63+
describe('[#28779] SHAPE: what the reads serve for a dependent\'s email template locale the base does not ship (showcase)', () => {
64+
let stack: VerifyStack | undefined;
65+
let token: string;
66+
let shipped: Record<string, unknown>;
67+
68+
const call = async (method: string, path: string, body?: unknown) => {
69+
const res = await stack!.apiAs(token, method, path, body);
70+
return { status: res.status, json: (await res.json().catch(() => ({}))) as any };
71+
};
72+
/** `GET /meta/email_template/:name` at one member, with or without `?package=` — the served document, trimmed. */
73+
const byName = async (member: string, pkg?: string): Promise<Served> => {
74+
const read = await call('GET', `/meta/email_template/${NAME}?member=${member}${pkg ? `&package=${pkg}` : ''}`);
75+
if (read.status !== 200) return { status: read.status };
76+
const doc = read.json?.data ?? read.json?.item ?? read.json;
77+
const item = (doc?.item ?? doc) as Record<string, unknown>;
78+
return { status: read.status, subject: item.subject, locale: item.locale, _packageId: item._packageId };
79+
};
80+
/** The template's rows on `GET /meta/email_template[?package=]`, as `[locale, _packageId, subject]`. */
81+
const listed = async (pkg?: string) => {
82+
const list = await call('GET', `/meta/email_template${pkg ? `?package=${pkg}` : ''}`);
83+
expect(list.status).toBe(200);
84+
const items: any[] = Array.isArray(list.json) ? list.json : (list.json?.items ?? list.json?.data?.items ?? list.json?.data ?? []);
85+
return items.filter((i) => i?.name === NAME).map((i) => [i.locale, i._packageId, i.subject]);
86+
};
87+
/** The executing list the email template loader reads (`protocol.getMetaItemsForExecution`). */
88+
const executing = async () => {
89+
const protocol: any = await stack!.kernel.getServiceAsync('protocol');
90+
const out = await protocol.getMetaItemsForExecution({ type: 'email_template' });
91+
return ((out?.items ?? []) as any[]).filter((i) => i?.name === NAME).map((i) => [i.locale, i._packageId, i.subject]);
92+
};
93+
/** What a send in `locale` renders: `IEmailService.renderTemplate`, the resolver `sendTemplate` uses. */
94+
const rendered = async (locale: string) => {
95+
const email: any = await stack!.kernel.getServiceAsync('email');
96+
return (await email.renderTemplate({ template: NAME, locale, data: { title: 'T' } }))?.subject;
97+
};
98+
const body = (locale: string, subject: string, extra: Record<string, unknown> = {}) => {
99+
const out: Record<string, unknown> = {};
100+
for (const [k, v] of Object.entries(shipped)) if (!k.startsWith('_')) out[k] = v;
101+
return { ...out, locale, subject, ...extra };
102+
};
103+
const saveInto = (pkg: string, b: Record<string, unknown>) =>
104+
call('PUT', `/meta/email_template/${NAME}?mode=draft&package=${pkg}`, b);
105+
const publishFrom = (pkg: string, member: string) =>
106+
call('POST', `/meta/email_template/${NAME}/publish?package=${pkg}&member=${member}`, {});
107+
108+
const BASE_EN = { status: 200, subject: SHIPPED_SUBJECT, locale: 'en-US', _packageId: BASE };
109+
const DEPENDENT_FR = { status: 200, subject: DEPENDENT_SUBJECT, locale: 'fr-FR', _packageId: DEPENDENT };
110+
111+
beforeAll(async () => {
112+
stack = await bootShowcase();
113+
token = await stack.signIn();
114+
const read = await call('GET', `/meta/email_template/${NAME}?member=en-US`);
115+
expect(read.status).toBe(200);
116+
const doc = read.json?.data ?? read.json?.item ?? read.json;
117+
shipped = doc?.item ?? doc;
118+
}, 180_000);
119+
120+
afterAll(async () => {
121+
await stack?.stop();
122+
});
123+
124+
it('baseline: nothing answers `fr-FR`, and the base\'s `en-US` reads as the base\'s', async () => {
125+
expect(await byName('fr-FR', BASE)).toEqual({ status: 404 });
126+
expect(await byName('fr-FR')).toEqual({ status: 404 });
127+
expect(await byName('en-US', BASE)).toEqual(BASE_EN);
128+
expect(await byName('en-US')).toEqual(BASE_EN);
129+
expect(await rendered('fr-FR')).toBe('✅ Task done: T');
130+
});
131+
132+
it('the dependent publishes `fr-FR` under the base\'s name, admitted as an addition; its `en-US` is refused', async () => {
133+
const created = await call('POST', '/packages', {
134+
manifest: {
135+
id: DEPENDENT, name: 'Showcase add-on', version: '0.1.0', type: 'app', namespace: 'scaddon',
136+
dependencies: { [BASE]: '*' },
137+
},
138+
});
139+
expect(created.status, JSON.stringify(created.json)).toBe(201);
140+
141+
const saved = await saveInto(DEPENDENT, body('fr-FR', DEPENDENT_SUBJECT));
142+
expect(saved.status, JSON.stringify(saved.json)).toBe(200);
143+
const published = await publishFrom(DEPENDENT, 'fr-FR');
144+
expect(published.status, JSON.stringify(published.json)).toBe(200);
145+
146+
// Control: the member the base ships is still a same-name collision.
147+
const refused = await saveInto(DEPENDENT, body('en-US', 'Add-on EN: {{title}}'));
148+
expect(refused.status, JSON.stringify(refused.json)).toBe(403);
149+
expect(codeOf(refused.json)).toBe('NOT_OVERRIDABLE');
150+
});
151+
152+
it('the read naming the dependent serves its `fr-FR` under its own package id', async () => {
153+
expect(await byName('fr-FR', DEPENDENT)).toEqual(DEPENDENT_FR);
154+
expect(await listed(DEPENDENT)).toEqual([['fr-FR', DEPENDENT, DEPENDENT_SUBJECT]]);
155+
});
156+
157+
it('SHAPE: the read naming the base and the package-less read serve the dependent\'s `fr-FR` body (stamped with the dependent)', async () => {
158+
expect(await byName('fr-FR', BASE)).toEqual(DEPENDENT_FR);
159+
expect(await byName('fr-FR')).toEqual(DEPENDENT_FR);
160+
// Control: the base's own member is untouched on every read.
161+
expect(await byName('en-US', BASE)).toEqual(BASE_EN);
162+
expect(await byName('en-US')).toEqual(BASE_EN);
163+
});
164+
165+
it('SHAPE: the env-wide, base-scoped and executing lists leave `fr-FR` out, so a `fr-FR` send renders the base\'s `en-US`', async () => {
166+
expect(await listed()).toEqual([['en-US', BASE, SHIPPED_SUBJECT]]);
167+
expect(await listed(BASE)).toEqual([['en-US', BASE, SHIPPED_SUBJECT]]);
168+
expect(await executing()).toEqual([['en-US', BASE, SHIPPED_SUBJECT]]);
169+
expect(await rendered('fr-FR')).toBe('✅ Task done: T');
170+
});
171+
172+
it('control: the pair\'s declared override of `en-US` reads as the override; the dependent\'s `fr-FR` reads as before', async () => {
173+
const ensured = await call('POST', `/packages/${BASE}/ensure-customization`);
174+
expect([200, 201], JSON.stringify(ensured.json)).toContain(ensured.status);
175+
const saved = await saveInto(PAIR, body('en-US', OVERRIDE_SUBJECT, { overrides: { package: BASE, basedOn: '0.1.0' } }));
176+
expect(saved.status, JSON.stringify(saved.json)).toBe(200);
177+
const published = await publishFrom(PAIR, 'en-US');
178+
expect(published.status, JSON.stringify(published.json)).toBe(200);
179+
180+
const OVERRIDE_EN = { status: 200, subject: OVERRIDE_SUBJECT, locale: 'en-US', _packageId: BASE };
181+
expect(await byName('en-US', BASE)).toEqual(OVERRIDE_EN);
182+
expect(await byName('en-US')).toEqual(OVERRIDE_EN);
183+
expect(await listed()).toEqual([['en-US', BASE, OVERRIDE_SUBJECT]]);
184+
expect(await rendered('en-US')).toBe('Override: T');
185+
186+
expect(await byName('fr-FR', BASE)).toEqual(DEPENDENT_FR);
187+
expect(await byName('fr-FR')).toEqual(DEPENDENT_FR);
188+
expect(await rendered('fr-FR')).toBe('Override: T');
189+
});
190+
});

0 commit comments

Comments
 (0)