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