fix(app-showcase): author the task-done email at a locale the send ladder can reach (#10419)

* fix(app-showcase): author the task-done email at a locale the send ladder can reach

`examples/app-showcase/src/system/emails/index.ts` declared `locale: 'en'` on a
bare object literal. `sendTemplate`'s ladder is exact match -> `en-US` ->
(no-locale calls only) the bundle's lowest tag, with deliberately no
language-prefix matching, so `en` never satisfies `en-US`.

Measured against the old declaration, through the real loader and the real
`mapTemplateToRow` projection:

    loader.load(showcase_task_done_email, en-US) -> null
    sendTemplate locale='en-US' -> THREW TEMPLATE_NOT_FOUND: showcase_task_done_email (locale=en-US)
    sendTemplate no locale      -> RESOLVED (rung 3, the lowest-tag fallback)

`en-US` is the ladder's own second rung, so a row authored there is reachable
from every call shape; any other tag is reachable from strictly fewer. The key
is written out rather than left to the schema default because the example
corpus is what gets copied.

The literal is also now wrapped in `defineEmailTemplateDefinition(...)`, so
`EmailTemplateDefinitionSchema.parse()` runs at authoring time instead of first
at boot.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PnJHU45vPJj5UQrxe946Bx

* fix(app-showcase): resolve plugin-email's TYPES from source too, not just its runtime

The vitest source alias added alongside the locale fix closed the runtime half of
the staleness exposure. The new devDependency has a second one on the TYPE path:
unaliased, `@objectstack/plugin-email` contributes
`packages/plugins/plugin-email/dist/*.d.ts` to this app's tsc program, so
`tsc --noEmit` graded the declarations against whatever was last built rather
than against the locale ladder in this checkout.

Reproduced before the fix, on 7bfca1d:

    check-type-source-resolution FAILED
      ✗ @objectstack/example-showcase: NEW dist-resolved type import(s) since
        this entry was measured: @objectstack/plugin-email.

and after:

    check-type-source-resolution OK — 76 packages with a tsconfig.json scanned;
    51 registered as still resolving a workspace dep's types through `dist/`.

The remedy is the `paths` rule the gate asks for, mirroring the existing
`@objectstack/formula` entry; the shrink-only KNOWN_DIST_RESOLVED_TYPE_IMPORTS
registry is untouched. Bare key, no `*` — a tsconfig `paths` key without a star
is an exact match, while the `@objectstack/plugin-email*` spelling would fold
every subpath onto one target and type-check green against the wrong module.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PnJHU45vPJj5UQrxe946Bx

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-warren

examples/app-showcase/package.json

@@ -40,6 +40,7 @@
     "@objectstack/formula": "workspace:*",
     "@objectstack/objectql": "workspace:*",
     "@objectstack/plugin-approvals": "workspace:*",
+    "@objectstack/plugin-email": "workspace:*",
     "@objectstack/service-automation": "workspace:*",
     "@objectstack/service-messaging": "workspace:*",
     "@playwright/test": "^1.62.1",

examples/app-showcase/src/system/emails/index.ts

@@ -1,20 +1,49 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-/** Email template fired by the Task Completed flow. */
-export const TaskDoneEmail = {
+import { defineEmailTemplateDefinition } from '@objectstack/spec';
+
+/**
+ * Email template declared for the Task Completed flow.
+ *
+ * ## Why `locale` is `en-US`, and why it is spelled out
+ *
+ * `sendTemplate`'s ladder is **exact match → `en-US` → (no-locale calls only)
+ * the bundle's lowest tag**, with deliberately no language-prefix matching:
+ * `en` does not satisfy `en-US`. Because `en-US` is the ladder's own second
+ * rung, a row authored at `en-US` is reachable from *every* call shape — an
+ * explicit `en-US`, this app's `defaultLocale: 'en'` (which the notify path
+ * passes as the recipient locale), and a call naming no locale at all. Any
+ * other tag is reachable from strictly fewer: this row used to say `en`, which
+ * made `sendTemplate({ locale: 'en-US' })` fail with `TEMPLATE_NOT_FOUND`.
+ *
+ * The key is written out rather than left to the schema default because the
+ * example corpus is what gets copied: the tag is the bundle key a second
+ * language row has to match, and `content/docs/automation/email-templates.mdx`
+ * teaches authoring the tags your callers actually pass.
+ *
+ * ## Not wired to the flow yet
+ *
+ * `showcase_task_completed`'s notify node demonstrates the inline
+ * `title`/`message` path, which the node schema makes mutually exclusive with
+ * `template` — so referencing this template there is a substitution, not an
+ * addition: it would cost the script node's `{summary}` its only consumer, and
+ * that consumption is what the flow exists to demonstrate. Tracked as its own
+ * decision in #10394 rather than smuggled in here.
+ */
+export const TaskDoneEmail = defineEmailTemplateDefinition({
   name: 'showcase_task_done_email',
   label: 'Task Done Notification',
-  category: 'workflow' as const,
-  locale: 'en',
+  category: 'workflow',
+  locale: 'en-US',
   subject: '✅ Task done: {{title}}',
   bodyHtml: '<p>The task <strong>{{title}}</strong> on project {{project}} was marked done.</p>',
   bodyText: 'The task {{title}} on project {{project}} was marked done.',
   variables: [
-    { name: 'title', type: 'string' as const, required: true, description: 'Task title' },
-    { name: 'project', type: 'string' as const, required: false, description: 'Project name' },
+    { name: 'title', type: 'string', required: true, description: 'Task title' },
+    { name: 'project', type: 'string', required: false, description: 'Project name' },
   ],
   active: true,
   isSystem: false,
-};
+});
 
 export const allEmails = [TaskDoneEmail];

examples/app-showcase/test/email-template-locale.test.ts

@@ -0,0 +1,128 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// The showcase's declared email templates have to be REACHABLE, and the only
+// way to know that is to resolve them.
+//
+// The bug this pins: `showcase_task_done_email` declared `locale: 'en'`.
+// `sendTemplate`'s ladder is exact match → `en-US` → (no-locale calls only) the
+// bundle's lowest tag, with deliberately no language-prefix matching, so `en`
+// never satisfies `en-US`. Measured against the old declaration, through the
+// same loader used below: `load(name, 'en-US')` answered `null`, and a
+// `sendTemplate({ locale: 'en-US' })` threw
+// `TEMPLATE_NOT_FOUND: showcase_task_done_email (locale=en-US)`. A no-locale
+// send still worked — by falling through to rung 3, the arbitrary-looking
+// "lowest tag in the bundle" — which is exactly why the defect was latent.
+//
+// So these assertions run the DECLARED templates through the real boot path:
+// the canonical schema parse, the real `mapTemplateToRow` projection into
+// `sys_email_template` columns, and the real `createSysEmailTemplateLoader`.
+// Nothing here inspects the source literal's strings; every verdict is a
+// resolution. The composition of rungs 1-3 itself is plugin-email's own
+// contract and is pinned there (`template-locale-resolution.test.ts`).
+
+import { describe, it, expect } from 'vitest';
+import { EmailTemplateDefinitionSchema } from '@objectstack/spec/system';
+import {
+  createSysEmailTemplateLoader,
+  mapTemplateToRow,
+  EMAIL_TEMPLATE_OBJECT,
+  DEFAULT_TEMPLATE_LOCALE,
+} from '@objectstack/plugin-email';
+import { allEmails, TaskDoneEmail } from '../src/system/emails/index.js';
+
+type Row = Record<string, unknown> & { id: string };
+
+/** What the boot seeder writes: schema parse, then the shared column mapping. */
+function materialize(templates: readonly unknown[]): Row[] {
+  return templates.map((t, i) => ({
+    id: `row-${i}`,
+    ...mapTemplateToRow(EmailTemplateDefinitionSchema.parse(t) as never),
+  }));
+}
+
+/**
+ * A driver-ish engine over the materialized rows — filters by `where`, honours
+ * `orderBy`, then `limit`. Mirrors the fake plugin-email's own resolution
+ * suite uses, so the loader is exercised the way a real store exercises it.
+ */
+function engine(rows: Row[]) {
+  return {
+    async find(object: string, query: Record<string, unknown>) {
+      expect(object).toBe(EMAIL_TEMPLATE_OBJECT);
+      const where = (query.where ?? {}) as Record<string, unknown>;
+      let out = rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      const orderBy = query.orderBy as Array<{ field: string; order?: string }> | undefined;
+      if (Array.isArray(orderBy)) {
+        out = [...out].sort((a, b) => {
+          for (const { field, order } of orderBy) {
+            const av = String(a[field] ?? '');
+            const bv = String(b[field] ?? '');
+            if (av !== bv) return (av < bv ? -1 : 1) * (order === 'desc' ? -1 : 1);
+          }
+          return 0;
+        });
+      }
+      return typeof query.limit === 'number' ? out.slice(0, query.limit) : out;
+    },
+  };
+}
+
+const loader = () => createSysEmailTemplateLoader(engine(materialize(allEmails)) as never);
+
+describe('showcase email templates — declared tags the send ladder can actually reach', () => {
+  it('resolves `showcase_task_done_email` for an explicit en-US send', async () => {
+    const found = await loader().load('showcase_task_done_email', DEFAULT_TEMPLATE_LOCALE);
+
+    // The regression, stated as the send that used to fail. For an explicit
+    // `en-US` the loader IS the whole ladder: rung 1 and rung 2 name the same
+    // tag, so a null here is a `TEMPLATE_NOT_FOUND` throw at the service.
+    expect(found).not.toBeNull();
+    expect(found?.locale).toBe('en-US');
+  });
+
+  it('resolves THIS template, not some other row of the bundle', async () => {
+    const found = await loader().load('showcase_task_done_email', DEFAULT_TEMPLATE_LOCALE);
+
+    // A resolution that answers the wrong row is the failure mode a bare
+    // "not null" assertion cannot see, so pin the identity of what came back.
+    expect(found?.name).toBe('showcase_task_done_email');
+    expect(found?.subject).toBe(TaskDoneEmail.subject);
+    expect(found?.body_html).toBe(TaskDoneEmail.bodyHtml);
+  });
+
+  it('answers a no-locale send from the default rung, not from the lowest-tag rung', async () => {
+    // Rung 3 ("no en-US row at all ⇒ the bundle's lowest tag") is a
+    // keep-the-tenant-working fallback, not a place an authored corpus should
+    // be living. With the row at en-US this send is answered by rung 2.
+    const found = await loader().load('showcase_task_done_email', undefined);
+    expect(found?.locale).toBe(DEFAULT_TEMPLATE_LOCALE);
+  });
+
+  it('does NOT answer the language-only tag `en` — and does not need to', async () => {
+    // Pinned in the true direction: there is no prefix matching in either
+    // direction, so an `en` lookup misses rung 1 by design. It still delivers,
+    // because rung 2 of the service ladder is `en-US` — which is precisely why
+    // `en-US` is the tag reachable from every call shape and `en` is not.
+    expect(await loader().load('showcase_task_done_email', 'en')).toBeNull();
+  });
+
+  it('every declared template in the corpus is reachable at the default locale', async () => {
+    // The class guard: a template added later cannot reintroduce the defect
+    // by picking a tag the ladder's default rung does not name.
+    for (const template of allEmails) {
+      const name = EmailTemplateDefinitionSchema.parse(template).name;
+      const found = await loader().load(name, DEFAULT_TEMPLATE_LOCALE);
+      expect(found, `${name} is unreachable at ${DEFAULT_TEMPLATE_LOCALE}`).not.toBeNull();
+    }
+  });
+
+  it('every declared template went through `defineEmailTemplateDefinition`', async () => {
+    // The second half of the card: the literal used to be exported bare, so
+    // `EmailTemplateDefinitionSchema.parse()` never ran at authoring time. A
+    // definition that has been through the factory is a FIXED POINT of the
+    // parse (every default already applied); a bare literal is not.
+    for (const template of allEmails) {
+      expect(EmailTemplateDefinitionSchema.parse(template)).toEqual(template);
+    }
+  });
+});

examples/app-showcase/tsconfig.json

@@ -27,8 +27,19 @@
     // `dist` typechecks green over an engine contract that has since moved.
     // `pnpm check:type-source-resolution` is the gate; it wants the `paths`
     // rule, not a registry entry.
+    //
+    // Same rule, same reason, for the email plugin: `test/email-template-locale.test.ts`
+    // resolves this app's declared email templates through plugin-email's real
+    // `sys_email_template` loader and its real column mapping. Unaliased, its TYPES
+    // come from `packages/plugins/plugin-email/dist/*.d.ts`, so `tsc --noEmit` would
+    // grade those declarations against whatever was last built rather than against the
+    // locale ladder in this checkout. Bare key, no `*`: a tsconfig `paths` key without
+    // a star is an EXACT match, and the `@objectstack/plugin-email*` spelling would
+    // fold every subpath onto this one target and type-check green against the wrong
+    // module.
     "paths": {
-      "@objectstack/formula": ["../../packages/formula/src/index.ts"]
+      "@objectstack/formula": ["../../packages/formula/src/index.ts"],
+      "@objectstack/plugin-email": ["../../packages/plugins/plugin-email/src/index.ts"]
     }
   },
   // This package took the widened-`include` route rather than a sibling

examples/app-showcase/vitest.config.ts

@@ -24,8 +24,18 @@ export default defineConfig({
     // PREFIX, so with a FILE replacement it would also swallow any subpath and
     // resolve it to `…/formula/src/index.ts/<sub>` — `ENOTDIR` at run time,
     // from a config that reads as correct.
+    //
+    // `test/email-template-locale.test.ts` resolves this app's declared email
+    // templates through plugin-email's real `sys_email_template` loader and its
+    // real column mapping. Through the workspace link that package resolves to
+    // `dist/` — a build artifact — so a stale dist would grade the declarations
+    // against an OLD locale ladder, which is the one thing those assertions
+    // exist to measure. `pnpm check:test-source-alias` is the gate, and its
+    // registry is shrink-only: the alias is the sanctioned remedy, never a new
+    // registry entry.
     alias: [
       { find: /^@objectstack\/formula$/, replacement: path.resolve(__dirname, '../../packages/formula/src/index.ts') },
+      { find: /^@objectstack\/plugin-email$/, replacement: path.resolve(__dirname, '../../packages/plugins/plugin-email/src/index.ts') },
     ],
   },
   test: {