fix(plugin-email): keep the published sweep signature; the plugin calls an internal effective sweep

The effective-template boot sweep moves to a module-internal
bootstrapEffectiveEmailTemplates, which EmailServicePlugin's boot wiring
calls with the protocol and tenancy services. The exported
bootstrapDeclaredEmailTemplates keeps its published four-parameter
signature and delegates with no sources, reading the registry as before.
The package entry exports no new symbol: EffectiveEmailTemplateSources is
no longer re-exported. One sweep body, two entry points.

Claude-Session: https://claude.ai/code/session_011K3zqE8Pv1Evw5hc8tZCnN
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/21785-email-template-overlay-survives-boot.md

@@ -7,7 +7,7 @@ An email template edited through `PUT /api/v1/meta/email_template/:name` (the St
 Clause-②: no
 
 - The cause: on a deployment with a Default Organization the admin's save is an org-scoped overlay, and boot hydration keeps org-scoped overlays out of the registry the sweep read. An env-wide overlay was already kept.
-- `bootstrapDeclaredEmailTemplates` now projects the effective template, the layered list `protocol.getMetaItems` serves, read in `tenancy.defaultOrgId()`'s organization. That is the Default Organization under the `single` posture, and env-wide (no organization) whenever a walled posture is requested. A host without a `protocol` service reads the registry as before.
+- `EmailServicePlugin`'s boot sweep now projects the effective template: the layered list `protocol.getMetaItems` serves, read in the organization `tenancy.defaultOrgId()` names. That is the Default Organization under the `single` posture. A host without a `protocol` service reads the registry as before.
 - A failed effective read projects nothing for that boot, so the rows keep their last projection. It does not fall back to the package wording.
 - Seed-not-clobber is unchanged. A row an admin created (`managed_by: 'admin'`) or edited through the data API (`customized: true`) is still never overwritten.
-- `bootstrapDeclaredEmailTemplates` takes an optional fifth argument, `{ protocol, tenancy }` (`EffectiveEmailTemplateSources`, now exported). Existing callers are unaffected.
+- The published API is unchanged. The exported `bootstrapDeclaredEmailTemplates` keeps its signature and still reads the registry, so a caller outside the plugin sees the same behaviour as before.

packages/plugins/plugin-email/src/bootstrap-declared-email-templates.test.ts

@@ -12,6 +12,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import {
   bootstrapDeclaredEmailTemplates,
+  bootstrapEffectiveEmailTemplates,
   upsertDeclaredEmailTemplate,
   deactivateDeclaredEmailTemplate,
   mapTemplateToRow,
@@ -494,7 +495,7 @@ describe('bootstrapDeclaredEmailTemplates — the effective template (#21785)',
       { organizationId: ORG, items: [declaredTemplate({ subject: OVERLAY_WORDING })] },
     );
 
-    const result = await bootstrapDeclaredEmailTemplates(engine as any, undefined, undefined, undefined, {
+    const result = await bootstrapEffectiveEmailTemplates(engine as any, undefined, {
       protocol,
       tenancy: { defaultOrgId: async () => ORG },
     });
@@ -512,13 +513,13 @@ describe('bootstrapDeclaredEmailTemplates — the effective template (#21785)',
       { organizationId: ORG, items: [declaredTemplate({ subject: OVERLAY_WORDING })] },
     );
 
-    await bootstrapDeclaredEmailTemplates(engine as any, undefined, undefined, undefined, {
+    await bootstrapEffectiveEmailTemplates(engine as any, undefined, {
       protocol,
       tenancy: { defaultOrgId: async () => null },
     });
 
-    // No organization on the request: one plant's overlay is never what the
-    // org-agnostic sending row carries.
+    // No organization on the request: the tenancy contract named none, so the
+    // read is env-wide and the declaration is what the row carries.
     expect(protocol.requests).toEqual([{ type: 'email_template' }]);
     expect(rowsOf(engine)[0].subject).toBe(PACKAGE_WORDING);
   });
@@ -533,10 +534,10 @@ describe('bootstrapDeclaredEmailTemplates — the effective template (#21785)',
       async getMetaItems(): Promise<never> { throw new Error('sys_metadata read failed'); },
     };
 
-    const result = await bootstrapDeclaredEmailTemplates(engine as any, undefined, { warn }, undefined, {
+    const result = await bootstrapEffectiveEmailTemplates(engine as any, undefined, {
       protocol,
       tenancy: { defaultOrgId: async () => ORG },
-    });
+    }, { warn });
 
     expect(result).toEqual({ seeded: 0, skipped: 0 });
     expect(rowsOf(engine)[0].subject).toBe(OVERLAY_WORDING);
@@ -562,10 +563,10 @@ describe('bootstrapDeclaredEmailTemplates — the effective template (#21785)',
       ],
     });
 
-    const result = await bootstrapDeclaredEmailTemplates(engine as any, undefined, { warn }, undefined, {
+    const result = await bootstrapEffectiveEmailTemplates(engine as any, undefined, {
       protocol,
       tenancy: { defaultOrgId: async () => ORG },
-    });
+    }, { warn });
 
     expect(result).toEqual({ seeded: 0, skipped: 2 });
     expect(rowsOf(engine).map((r) => r.subject)).toEqual(['Admin original', 'Data-door wording']);

packages/plugins/plugin-email/src/bootstrap-declared-email-templates.ts

@@ -115,6 +115,10 @@ function uid(prefix: string): string {
  * (#21785). Both are optional: a host that registers no `protocol` has no
  * metadata door, so nothing can overlay a declaration there and the registry
  * read below is already the effective one.
+ *
+ * Module-internal: exported for EmailServicePlugin's boot wiring only and
+ * deliberately NOT re-exported from the package entry — see
+ * {@link bootstrapEffectiveEmailTemplates}.
  */
 export interface EffectiveEmailTemplateSources {
   /** The `protocol` service. `getMetaItems` is the layered list `GET /meta/email_template` serves. */
@@ -154,9 +158,9 @@ const EFFECTIVE_READ_FAILED = Symbol('email-template-effective-read-failed');
  * org-less reader of org-overridable metadata does: `tenancy.defaultOrgId()`,
  * as the anonymous form doors read a form (`@objectstack/rest`). That answers
  * the Default Organization under `single` (ADR-0131: the organization IS the
- * environment there) and `null` whenever a walled posture was requested, where
- * the read is env-wide and no plant's overlay becomes everyone's mail. The
- * sending row stays org-agnostic: template resolution keys on
+ * environment there) and `null` whenever a walled posture was requested (the
+ * tenancy contract never guesses an organization there), where the read is
+ * env-wide. The sending row stays org-agnostic: template resolution keys on
  * `(name, locale)` only, and per-organization template rows are a capability
  * no ruling has opened.
  *
@@ -359,17 +363,43 @@ export async function deactivateDeclaredEmailTemplate(
 }
 
 /**
- * Materialize every declared email template into `sys_email_template`, as the
- * metadata door serves it (an overlay of the declaration included) when
- * `sources.protocol` is given — see {@link readDeclared}. Idempotent and safe
+ * Materialize every declared email template into `sys_email_template` from the
+ * ObjectQL registry (falling back to the metadata service). Idempotent and safe
  * to run on every boot.
+ *
+ * The published signature, unchanged. It delegates to
+ * {@link bootstrapEffectiveEmailTemplates} with no sources, so an external
+ * caller reads the registry exactly as before — the declarations plus the
+ * env-wide overlays boot hydration registered. The plugin's own boot wiring
+ * calls the effective form directly.
  */
 export async function bootstrapDeclaredEmailTemplates(
   engine: IDataEngine,
   metadataService: any,
   logger?: Logger,
   object = EMAIL_TEMPLATE_OBJECT,
-  sources?: EffectiveEmailTemplateSources,
+): Promise<BootstrapDeclaredEmailTemplatesResult> {
+  return bootstrapEffectiveEmailTemplates(engine, metadataService, undefined, logger, object);
+}
+
+/**
+ * [#21785] The boot sweep EmailServicePlugin runs: materialize every
+ * `email_template` into `sys_email_template` as the metadata door serves it —
+ * an overlay of the declaration included — when `sources.protocol` is given,
+ * and from the registry otherwise (see {@link readDeclared}). The one sweep
+ * body; {@link bootstrapDeclaredEmailTemplates} is this with no sources.
+ *
+ * Module-internal: NOT re-exported from the package entry (`src/index.ts`),
+ * and the package's `exports` map names only that entry, so this function and
+ * {@link EffectiveEmailTemplateSources} add nothing to the published surface.
+ * No caller outside this package needs them.
+ */
+export async function bootstrapEffectiveEmailTemplates(
+  engine: IDataEngine,
+  metadataService: any,
+  sources: EffectiveEmailTemplateSources | undefined,
+  logger?: Logger,
+  object = EMAIL_TEMPLATE_OBJECT,
 ): Promise<BootstrapDeclaredEmailTemplatesResult> {
   const declared = await readDeclared(engine, metadataService, 'email_template', sources, logger);
   if (declared === EFFECTIVE_READ_FAILED || declared.length === 0) return { seeded: 0, skipped: 0 };

packages/plugins/plugin-email/src/email-plugin.ts

@@ -36,7 +36,7 @@ import type {
   SettingsUnsubscribe,
 } from '@objectstack/spec/system';
 import {
-  bootstrapDeclaredEmailTemplates,
+  bootstrapEffectiveEmailTemplates,
   upsertDeclaredEmailTemplate,
   deactivateDeclaredEmailTemplate,
   mapTemplateToRow,
@@ -1102,7 +1102,7 @@ export class EmailServicePlugin implements Plugin {
     try { tenancy = ctx.getService('tenancy'); } catch { /* optional */ }
 
     try {
-      await bootstrapDeclaredEmailTemplates(engine, metadataService, ctx.logger as any, undefined, { protocol, tenancy });
+      await bootstrapEffectiveEmailTemplates(engine, metadataService, { protocol, tenancy }, ctx.logger as any);
     } catch (err: any) {
       ctx.logger.warn(
         'EmailServicePlugin: declared email-template bootstrap failed (built-in templates still serve): '

packages/plugins/plugin-email/src/index.ts

@@ -105,7 +105,6 @@ export {
   mapTemplateToRow,
   EMAIL_TEMPLATE_OBJECT,
   type BootstrapDeclaredEmailTemplatesResult,
-  type EffectiveEmailTemplateSources,
 } from './bootstrap-declared-email-templates.js';
 export {
   sweepStrandedOutbox,