fix(plugin-email): use the shared read-decoration strip, not a blanket _ sweep

`readEffectiveTemplate` stripped read decorations with a module-local copy of
`stripReadDecorations` that dropped every key starting with `_`. The shared
list it drifted from (`spec/kernel/metadata-read-decorations.ts`) carries
exactly `['_diagnostics', '_draft']` and names the ADR-0010 protection envelope
as "Deliberately NOT" a member — envelope state the write path legitimately
carries, allowlisted by the closed schemas.

The copy justified the sweep on the claim that `EmailTemplateDefinitionSchema`
"declares no underscore key". `email-template.zod.ts` spreads
`MetadataProtectionFields` into its `strictObject`, so every envelope key is
declared and parses clean.

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

Author: claude

packages/plugins/plugin-email/src/email-plugin.template-runtime-write.test.ts

@@ -263,8 +263,13 @@ describe('#7733 runtime email_template write materializes without a restart', ()
     // `getMetaItem` returns a DECORATED item (`_diagnostics` from
     // `decorateMetadataItem`, `_packageId` / `_provenance` from the registry
     // and the overlay row). `EmailTemplateDefinitionSchema` is a strictObject
-    // that declares no underscore key, so an unstripped body would reject the
-    // very baseline the reset exists to restore.
+    // that declares neither `_diagnostics` nor `_draft`, so an unstripped body
+    // would reject the very baseline the reset exists to restore.
+    //
+    // [#16152] It DOES declare the ADR-0010 envelope (`_packageId` /
+    // `_provenance` and the `_lock*` family, via `MetadataProtectionFields`) —
+    // those parse clean and are not stripped. See the `#16152` describe block
+    // below for the pins that hold that apart.
     const protocol = withEffectiveRead(fakeProtocol(), async () => ({
       type: 'email_template',
       name: 'auth.password_reset',
@@ -378,3 +383,110 @@ describe('#7733 runtime email_template write materializes without a restart', ()
     expect(engine.rows).toHaveLength(0);
   });
 });
+
+// ── #16152 ─────────────────────────────────────────────────────────────────
+//
+// `readEffectiveTemplate` used to strip read decorations with a MODULE-LOCAL
+// copy of `stripReadDecorations` that dropped every key starting with `_`.
+// The shared list it drifted from (`spec/kernel/metadata-read-decorations.ts`)
+// carries exactly `['_diagnostics', '_draft']` and names the ADR-0010
+// protection envelope as "Deliberately NOT" a member — envelope state the
+// write path legitimately carries, allowlisted by the closed schemas so a
+// served document keeps its provenance on re-parse.
+//
+// The copy's docblock justified the blanket sweep on the claim that
+// `EmailTemplateDefinitionSchema` "declares no underscore key". These pin why
+// that claim is false and what the narrow strip must do instead.
+
+describe('#16152 read-decoration strip uses the shared list, not a blanket `_` sweep', () => {
+  /** The full ADR-0010 envelope, as `MetadataProtectionFields` declares it. */
+  const ENVELOPE = {
+    _lock: 'no-delete',
+    _lockReason: 'Shipped by the auth package.',
+    _lockSource: 'artifact',
+    _provenance: 'package',
+    _packageId: 'com.objectstack.auth',
+    _packageVersion: '1.4.2',
+    _lockDocsUrl: 'https://example.invalid/locks',
+  } as const;
+
+  it('the schema declares the ADR-0010 envelope and rejects the read decorations', async () => {
+    // The premise the deleted docblock got backwards, asserted directly
+    // against the schema rather than inferred from it. `email-template.zod.ts`
+    // spreads `MetadataProtectionFields` into its `strictObject`, so every
+    // envelope key is authorable surface here; `_diagnostics` / `_draft` are
+    // not declared anywhere in that shape, which is why they must be stripped.
+    const { EmailTemplateDefinitionSchema } = await import('@objectstack/spec/system');
+
+    const withEnvelope = EmailTemplateDefinitionSchema.safeParse({ ...template(), ...ENVELOPE });
+    expect(withEnvelope.success).toBe(true);
+    // Guarding a KEY's reachability: no `unrecognized_keys` on any envelope key.
+    expect(
+      (withEnvelope as any).error?.issues?.filter((i: any) => i.code === 'unrecognized_keys') ?? [],
+    ).toEqual([]);
+
+    for (const decoration of ['_diagnostics', '_draft']) {
+      const served = EmailTemplateDefinitionSchema.safeParse({
+        ...template(),
+        [decoration]: decoration === '_draft' ? true : { valid: true },
+      });
+      expect(served.success).toBe(false);
+      const keys = (served as any).error.issues
+        .filter((i: any) => i.code === 'unrecognized_keys')
+        .flatMap((i: any) => i.keys);
+      expect(keys).toContain(decoration);
+    }
+  });
+
+  it('re-materializes a baseline served with the FULL protection envelope on it', async () => {
+    // The envelope rides along on the layered read (`_packageId` /
+    // `_provenance` from the registry, `_lock*` from the artifact layer). It
+    // parses clean, so the reset restores the packaged baseline with no
+    // projector failure — and `mapTemplateToRow`'s closed column list is what
+    // keeps it out of the row, not a strip.
+    const protocol = withEffectiveRead(fakeProtocol(), async () => ({
+      item: {
+        ...template({ subject: 'The packaged subject' }),
+        ...ENVELOPE,
+        _diagnostics: { valid: true },
+        _draft: false,
+      },
+    }));
+    const { engine } = await boot({ protocol });
+
+    await protocol.save('auth.password_reset', template({ subject: 'An operator override' }));
+    await protocol.remove('auth.password_reset');
+
+    expect(protocol.projectorFailures).toEqual([]);
+    const rows = rowsOf(engine, 'auth.password_reset');
+    expect(rows).toHaveLength(1);
+    expect(rows[0].subject).toBe('The packaged subject');
+    // `sys_email_template` declares no underscore column, and
+    // `mapTemplateToRow` projects a closed list — so the envelope cannot reach
+    // the row whatever the strip does. This is the measured reason there is no
+    // second, envelope-stripping pass beside the shared one.
+    for (const k of Object.keys(ENVELOPE)) expect(rows[0]).not.toHaveProperty(k);
+  });
+
+  it('does not silently swallow an underscore key the schema never declared', async () => {
+    // The blanket sweep dropped EVERY `_` key before the parse, so a key that
+    // is neither a decoration nor declared — a producer's typo, a decoration
+    // added upstream and never added to the shared list — vanished and the
+    // reset reported success. That is precisely the silent-strip failure the
+    // closed schemas (#4001) exist to end, and the shared list keeps loud:
+    // the projector surfaces it on the write's own response.
+    const protocol = withEffectiveRead(fakeProtocol(), async () => ({
+      item: { ...template({ subject: 'The packaged subject' }), _notADeclaredKey: 'x' },
+    }));
+    const { engine } = await boot({ protocol });
+
+    await protocol.save('auth.password_reset', template({ subject: 'An operator override' }));
+    await protocol.remove('auth.password_reset');
+
+    expect(protocol.projectorFailures).toHaveLength(1);
+    expect(protocol.projectorFailures[0]).toContain('_notADeclaredKey');
+    // The override row is left exactly as it was — a body the schema refuses
+    // never becomes a write.
+    expect(rowsOf(engine, 'auth.password_reset')[0].subject).toBe('An operator override');
+  });
+});

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

@@ -2,6 +2,7 @@
 
 import type { Plugin, PluginContext } from '@objectstack/core';
 import type { IDataEngine } from '@objectstack/spec/contracts';
+import { stripReadDecorations } from '@objectstack/spec/kernel';
 import type {
   IEmailTransport,
   EmailAddress,
@@ -66,23 +67,6 @@ const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
  */
 const FAILED_READ = Symbol('email-template-read-failed');
 
-/**
- * Drop the underscore-prefixed keys a SERVED metadata item carries
- * (`_diagnostics`, `_packageId`, `_provenance`, `_draft`, …). Every one of
- * them is a read-time verdict the protocol attaches, never an authored field:
- * `EmailTemplateDefinitionSchema` is a `strictObject` and declares no
- * underscore key, so leaving them on turns a perfectly good declaration into a
- * validation failure.
- */
-function stripReadDecorations(item: unknown): unknown {
-  if (!item || typeof item !== 'object' || Array.isArray(item)) return item;
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(item as Record<string, unknown>)) {
-    if (!k.startsWith('_')) out[k] = v;
-  }
-  return out;
-}
-
 /**
  * Plugin configuration.
  */
@@ -1282,13 +1266,45 @@ export class EmailServicePlugin implements Plugin {
    * registry, which for a delete is the same baseline. The three outcomes are
    * kept apart on purpose: only "nothing declares it" may deactivate a row.
    *
-   * The body is stripped of read decorations before it is returned. A served
-   * item carries the protocol's own underscore keys (`_diagnostics` from
-   * `decorateMetadataItem`, `_packageId` / `_provenance` from the registry and
-   * the overlay row), `EmailTemplateDefinitionSchema` is a `strictObject`, and
-   * it declares no underscore key — so handing the decorated body to the
-   * upsert would reject the very baseline this read exists to restore. This is
+   * The body is stripped of read decorations before it is returned, using the
+   * SHARED `stripReadDecorations` from `@objectstack/spec/kernel` — the same
+   * helper the other read-back-envelope consumers call (the dataset query in
+   * `rest-server.ts`, the cold-boot flow bind in `service-automation`,
+   * `saveMetaItem`'s verbatim persist, and the route-level seed apply). This is
    * the read-side twin of the strip `saveMetaItem` does on the write side.
+   *
+   * ## [#16152] Why this is the shared list and NOT a blanket `_`-sweep
+   *
+   * This call used to be a module-local copy that dropped **every** key
+   * starting with `_`, justified in its own docblock by the claim that
+   * `EmailTemplateDefinitionSchema` "declares no underscore key". That claim is
+   * false, and the schema disagrees in both directions:
+   *
+   *  - `METADATA_READ_DECORATIONS` is `['_diagnostics', '_draft']`, and those
+   *    two genuinely must go: the schema is a `strictObject`, neither key is
+   *    declared, so an unstripped body rejects the very baseline this read
+   *    exists to restore.
+   *  - The ADR-0010 protection envelope (`_lock`, `_lockReason`, `_lockSource`,
+   *    `_provenance`, `_packageId`, `_packageVersion`, `_lockDocsUrl`) is
+   *    **declared** — `email-template.zod.ts` spreads `MetadataProtectionFields`
+   *    into the shape — and `metadata-read-decorations.ts` names it
+   *    "Deliberately NOT" a member of the strip list, because it is envelope
+   *    state the write path legitimately carries. Sweeping it here removed keys
+   *    the schema was deliberately widened to accept.
+   *
+   * A blanket sweep is also a silent swallow: an underscore key that is neither
+   * a decoration nor declared is exactly what the closed schema exists to
+   * reject (#4001), and dropping it before the parse converts a loud
+   * `unrecognized_keys` into a quiet success.
+   *
+   * ⭐ There is deliberately **no** second, envelope-stripping pass beside this
+   * one. The envelope cannot reach the written row in the first place:
+   * `upsertDeclaredEmailTemplate` projects the parsed template through
+   * `mapTemplateToRow`, a closed column list, and `sys_email_template` declares
+   * no underscore column. Spelling an envelope strip here would encode a rule
+   * this path does not have, as a second copy of a truth that already lives in
+   * that projection — which is the drift this fix removes, re-introduced one
+   * layer up.
    */
   private async readEffectiveTemplate(
     ctx: PluginContext,