feat(email): materialize declared email_template metadata into sys_email_template (#4509)

Authoring an `email_template` was a silent no-op. `sendTemplate` resolves
`(name, locale)` against sys_email_template ROWS, whose only writers were the
built-in auth templates plus a code-constructed `EmailServicePluginOptions.
templates` that no bootstrapper passed — while every door an author can use
(stack `emailTemplates:`, `*.email-template.ts`, Studio, PUT /meta) parked items
in a metadata store nothing read back. An admin could "fix" the password-reset
mail in Studio and users kept receiving the built-in copy: ADR-0078 false
compliance on AUTH mail. Webhook #3461's shape, closed the same way (ADR-0049
enforce-or-remove, route: enforce).

`bootstrapDeclaredEmailTemplates` materializes declared items at boot, validating
each through EmailTemplateDefinitionSchema.parse() and projecting with
`mapTemplateToRow` — the SAME mapping the built-in seeder uses, extracted and
shared so the two doors cannot drift. Because email_template is
allowRuntimeCreate:true (unlike webhook), the plugin also subscribes to metadata
changes and re-materializes the changed item, so a Studio save takes effect
without a restart; a withdrawn template deactivates its rows rather than losing
them.

Three breaks sat on this path, and closing any two would still have shipped a
template that never sent:
- objectql never registered a manifest's `emailTemplates:` into the registry at
  all — the key was missing from the generic ingestion list, so the bridge's own
  source was empty.
- Built-in seeds left `managed_by` at the column's 'admin' default, masquerading
  as admin-authored; since the bridge refuses to overwrite admin rows, a built-in
  would permanently outrank the template an app declared. Built-ins now stamp
  'platform'.
- Nothing materialized declared metadata into rows.

Seed-not-clobber mirrors sys_webhook (#3489): sys_email_template gains
managed_by/customized, declared rows re-seed as 'package', and an admin-created
or admin-edited row is never overwritten. Separate axis from `is_system`, which
keeps its meaning for built-ins.

Ledger email_template flips 13 dead → fully live, with an ADR-0054 proof bound on
`subject`: it boots a real stack, authors a template overriding a built-in auth
template, and asserts the AUTHORED wording reaches the transport.

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

Author: claude

.changeset/email-template-materializer-bridge.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/platform-objects": minor
+"@objectstack/plugin-email": minor
+"@objectstack/objectql": minor
+"@objectstack/spec": patch
+---
+
+feat(email): declared email templates reach the mail service (#4509)
+
+Authoring an `email_template` was a silent no-op. `EmailService.sendTemplate`
+resolves `(name, locale)` against **`sys_email_template` rows**, and the only
+writers of those rows were the built-in auth templates plus a code-constructed
+`EmailServicePluginOptions.templates` that no bootstrapper ever passed. Every
+door an author can actually use — a stack's `emailTemplates:`, an
+`*.email-template.ts` file, Studio's metadata-admin list, `PUT /meta` — parked
+items in a metadata store nothing read back. So an admin could "fix" the
+password-reset email in Studio, get a success toast, and watch users keep
+receiving the built-in copy: ADR-0078 false compliance on **authentication
+mail**. This is the shape #3461 had for webhooks, closed the same way (ADR-0049
+enforce-or-remove, route: enforce).
+
+**`bootstrapDeclaredEmailTemplates`** now materializes declared templates into
+`sys_email_template` at boot. Each item is validated through
+`EmailTemplateDefinitionSchema.parse()` — the spec schema finally has a real
+consumer, defaults and all — and projected with `mapTemplateToRow`, which is the
+**same** mapping the built-in seeder uses, extracted and shared so the two doors
+cannot drift apart. A malformed template warns and is skipped rather than
+crashing boot.
+
+**Runtime writes take effect immediately.** Unlike `webhook`, `email_template`
+is `allowRuntimeCreate: true`, so a boot-only bridge would have left a Studio
+save inert until the next restart — the same bug, half-fixed. The plugin also
+subscribes to `email_template` metadata changes and re-materializes the single
+changed item; withdrawing a template deactivates its rows (across locales)
+rather than deleting them.
+
+**Three breaks sat on this path, not one**, and closing any two of them would
+still have shipped a template that never sent:
+
+- `@objectstack/objectql` never registered a manifest's `emailTemplates:` into
+  the metadata registry at all — the key was simply missing from the generic
+  ingestion list, so the bridge's own source was empty.
+- The built-in seeder left `managed_by` at the column's `'admin'` default, which
+  made platform templates masquerade as admin-authored. Since the bridge refuses
+  to overwrite admin rows, a built-in would have permanently outranked the
+  template an app declared. Built-ins now stamp `managed_by: 'platform'`.
+- Nothing materialized declared metadata into rows.
+
+**Seed-not-clobber** mirrors `sys_webhook` (#3489) and `sys_sharing_rule`
+(#2909): `sys_email_template` gains `managed_by` / `customized`. Declared
+templates re-seed every boot as `managed_by: 'package'`; a row an admin created
+(`admin`) or edited (`customized`, stamped by a `beforeUpdate` hook) is never
+overwritten, so reworded transactional mail survives redeploys. This is a
+separate axis from `is_system`, which keeps its existing meaning for built-ins.
+
+The `email_template` liveness ledger flips from 13 dead properties to fully
+live, with an ADR-0054 runtime proof bound on `subject`
+(`email-template-materialization`): it boots a real stack, authors a template
+that overrides a built-in auth template, and asserts the **authored** wording is
+what reaches the transport.

packages/cli/src/utils/lint-liveness-properties.test.ts

@@ -284,9 +284,14 @@ describe('lintLivenessProperties', () => {
     expect(perms!.hint).toMatch(/per item|Per-item/i);
   });
 
-  // email_template: the WHOLE authoring surface is disconnected from
-  // sendTemplate (webhook shape) — one per-artifact warn carried on `name`.
-  it('warns once per email_template artifact via name (#4488)', () => {
+  // email_template used to carry a per-artifact warn on `name`: the WHOLE
+  // authoring surface was disconnected from sendTemplate (the webhook shape).
+  // #4509 built the materializer bridge, so authoring is no longer a no-op and
+  // a well-formed template must warn about NOTHING. The type stays in
+  // TYPE_COLLECTIONS — a listed type with zero warns is the resolved state
+  // (webhook sits there the same way), and keeping it means a future
+  // regression that re-deadens a prop starts warning again on its own.
+  it('does not warn on a well-formed email_template — the bridge closed it (#4509)', () => {
     const findings = lintLivenessProperties({
       emailTemplates: [{
         name: 'crm.welcome',
@@ -295,9 +300,7 @@ describe('lintLivenessProperties', () => {
         bodyHtml: '<p>Welcome</p>',
       }],
     });
-    const hit = findings.find((f) => f.message.includes('`name`'));
-    expect(hit).toBeDefined();
-    expect(hit!.hint).toMatch(/sys_email_template/);
+    expect(findings).toEqual([]);
   });
 
   // translation.validationMessages: pointed at by #3778's own migration table,

packages/objectql/src/engine.ts

@@ -1632,6 +1632,12 @@ export class ObjectQL implements IObjectQLEngine {
         'hooks', 'mappings', 'analyticsCubes',
         // Integration Protocol
         'connectors',
+        // System Protocol — outbound mail templates. Registered here so the
+        // email plugin's materializer can read them back into
+        // `sys_email_template` (#4509); without this key an authored
+        // `emailTemplates:` entry never reached the registry at all, which is
+        // the far end of the disconnect the bridge closes.
+        'emailTemplates',
         // System Protocol — package documentation (ADR-0046); inert data
         'docs',
         // Documentation navigation spine (ADR-0046 §6)

packages/platform-objects/src/audit/sys-email-template.object.ts

@@ -145,6 +145,40 @@ export const SysEmailTemplate = ObjectSchema.create({
       group: 'Lifecycle',
     }),
 
+    // ── Provenance (#4509 — record-authoritative seed-not-clobber) ──
+    // Mirrors sys_webhook (#3461) / sys_sharing_rule (#2909). `is_system`
+    // remains the built-in-auth-template axis; these two track the DECLARED
+    // metadata door: bootstrapDeclaredEmailTemplates seeds `package` rows and
+    // re-seeds them every boot, while an admin's edit stamps `customized` and
+    // freezes the row. Both are `readonly` — the engine strips them from
+    // non-system payloads, and only the seeder / stamp hook (isSystem) write
+    // them. Deliberately NOT a write gate: editing a template in Studio is a
+    // first-class admin action, it just has to be remembered.
+    managed_by: Field.select(
+      ['platform', 'package', 'admin'],
+      {
+        label: 'Managed By',
+        required: false,
+        readonly: true,
+        defaultValue: 'admin',
+        description:
+          'Record provenance: platform = framework built-in / package = app/package-declared ' +
+          '(boot-seeded from declared email_template metadata) / admin = created in Studio.',
+        group: 'System',
+      },
+    ),
+
+    customized: Field.boolean({
+      label: 'Customized',
+      required: false,
+      readonly: true,
+      defaultValue: false,
+      description:
+        'Set when an admin edits a package-declared template; boot seeding will no longer ' +
+        'overwrite the row (a reworded password-reset mail survives redeploys). Meaningless on admin rows.',
+      group: 'System',
+    }),
+
     created_at: Field.datetime({
       label: 'Created At',
       required: true,