feat(templates): T4 sendTemplated() + outbound provenance

- IiosOutboundCommand gains templateKey/version/locale/renderedHash (migration).
- OutboundService.send accepts an optional opaque `provenance` and writes it into
  the command on BOTH the PENDING and RATE_LIMITED create paths — the only way to
  stamp provenance by construction, since send() creates the row itself (review
  finding). OutboundService still neither renders nor resolves templates.
- TemplatedSender.sendTemplated: render -> OutboundService.send -> provenance, one
  entry point. EMAIL payload = {subject,html,text}; SMS = {text}. Idempotent per key.

Tests: 4 sender + 16 adapters regression green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/iios-service/src/templates/templated-sender.spec.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import { PrismaClient } from '@prisma/client';
+import { makeFakePorts } from '@insignia/iios-testkit';
+import { resetDb } from '../test-utils/reset-db';
+import { OutboundService } from '../adapters/outbound.service';
+import { CapabilityBroker } from '../capability/capability.broker';
+import { CapabilityProviderRegistry } from '../capability/capability.registry';
+import { IdempotencyService } from '../idempotency/idempotency.service';
+import { TemplateRepository } from './template.repository';
+import { TemplateService } from './template.service';
+import { TemplatedSender } from './templated-sender';
+import type { PrismaService } from '../prisma/prisma.service';
+
+const url = process.env.DATABASE_URL ?? 'postgresql://iios:iios@localhost:5434/iios?schema=public';
+const prisma = new PrismaClient({ datasources: { db: { url } } });
+const asService = prisma as unknown as PrismaService;
+
+function sender(): TemplatedSender {
+  const outbound = new OutboundService(asService, new CapabilityBroker(makeFakePorts(), new CapabilityProviderRegistry()), new IdempotencyService(asService));
+  const templates = new TemplateService(new TemplateRepository(asService));
+  return new TemplatedSender(templates, outbound);
+}
+
+async function seedReceipt() {
+  await prisma.iiosMessageTemplate.create({
+    data: { key: 'payment.receipt', channel: 'EMAIL', locale: 'en', version: 1, subject: 'Thanks {{firstName}}', bodyHtml: '<p>{{amount}}</p>', bodyText: '{{amount}}', variables: ['firstName', 'amount'] },
+  });
+}
+
+beforeAll(async () => { await prisma.$connect(); });
+afterAll(async () => { await prisma.$disconnect(); });
+beforeEach(async () => { await resetDb(prisma); });
+
+describe('TemplatedSender.sendTemplated', () => {
+  it('renders a stored template, queues an outbound command, and stamps provenance', async () => {
+    await seedReceipt();
+    const cmd = await sender().sendTemplated({
+      source: { key: 'payment.receipt' }, channel: 'EMAIL', target: 'dana@acme.com',
+      vars: { firstName: 'Dana', amount: '$2,000' }, idempotencyKey: 'receipt:cs_1',
+    });
+    expect(cmd.channelType).toBe('EMAIL');
+    expect(cmd.target).toBe('dana@acme.com');
+    expect((cmd.payload as { subject: string }).subject).toBe('Thanks Dana');
+    expect(cmd.templateKey).toBe('payment.receipt');
+    expect(cmd.templateVersion).toBe(1);
+    expect(cmd.templateLocale).toBe('en');
+    expect(cmd.renderedHash).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  it('is idempotent per key: a replay yields ONE command', async () => {
+    await seedReceipt();
+    const s = sender();
+    const input = { source: { key: 'payment.receipt' }, channel: 'EMAIL' as const, target: 'dana@acme.com', vars: { firstName: 'Dana', amount: '$1' }, idempotencyKey: 'receipt:cs_dup' };
+    const a = await s.sendTemplated(input);
+    const b = await s.sendTemplated(input);
+    expect(b.id).toBe(a.id);
+    expect(await prisma.iiosOutboundCommand.count({ where: { idempotencyKey: 'receipt:cs_dup' } })).toBe(1);
+  });
+
+  it('sends inline content with null template key but a hash', async () => {
+    const cmd = await sender().sendTemplated({
+      source: { inline: { subject: 'Hi {{n}}', html: '<b>{{n}}</b>', variables: ['n'] } },
+      channel: 'EMAIL', target: 'x@y.com', vars: { n: 'Z' }, idempotencyKey: 'inline:1',
+    });
+    expect((cmd.payload as { subject: string }).subject).toBe('Hi Z');
+    expect(cmd.templateKey).toBeNull();
+    expect(cmd.renderedHash).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  it('shapes an SMS send as text only', async () => {
+    await prisma.iiosMessageTemplate.create({
+      data: { key: 'payment.receipt', channel: 'SMS', locale: 'en', version: 1, bodyText: 'Paid {{amount}}', variables: ['amount'] },
+    });
+    const cmd = await sender().sendTemplated({
+      source: { key: 'payment.receipt' }, channel: 'SMS', target: '+1415', vars: { amount: '$2,000' }, idempotencyKey: 'sms:1',
+    });
+    expect(cmd.channelType).toBe('SMS');
+    expect(cmd.payload).toEqual({ text: 'Paid $2,000' });
+  });
+});

packages/iios-service/src/templates/templated-sender.ts

@@ -0,0 +1,55 @@
+import { Injectable } from '@nestjs/common';
+import { OutboundService } from '../adapters/outbound.service';
+import { TemplateService } from './template.service';
+import type { RenderedContent } from './template.renderer';
+import type { TemplateSource } from './template.model';
+
+/** External-egress channels only. INTERNAL (in-app, no SMTP) delivery is the messaging module's job. */
+export type ExternalChannel = 'EMAIL' | 'SMS';
+
+export interface SendTemplatedInput {
+  source: TemplateSource;
+  channel: ExternalChannel;
+  target: string; // email address / phone number
+  vars: Record<string, unknown>;
+  scopeId?: string;
+  locale?: string;
+  idempotencyKey: string; // REQUIRED — e.g. "receipt:<stripe_session_id>"
+  purpose?: string;
+}
+
+/**
+ * The single entry point for a templated external send: render → OutboundService.send → provenance
+ * stamped in one place (by construction, not caller convention). Rendering stays pure/testable;
+ * OutboundService stays content-agnostic (it only records the provenance it is handed).
+ */
+@Injectable()
+export class TemplatedSender {
+  constructor(
+    private readonly templates: TemplateService,
+    private readonly outbound: OutboundService,
+  ) {}
+
+  async sendTemplated(input: SendTemplatedInput) {
+    const { content, provenance } = await this.templates.render(input.source, input.vars, {
+      channel: input.channel,
+      locale: input.locale,
+      scopeId: input.scopeId,
+    });
+    return this.outbound.send(
+      input.channel,
+      input.target,
+      this.toPayload(input.channel, content),
+      input.idempotencyKey,
+      input.scopeId,
+      input.purpose,
+      provenance,
+    );
+  }
+
+  /** Shape rendered content into the channel's egress envelope (EmailProvider reads subject/text/html). */
+  private toPayload(channel: ExternalChannel, content: RenderedContent): Record<string, unknown> {
+    if (channel === 'EMAIL') return { subject: content.subject, html: content.html, text: content.text };
+    return { text: content.text ?? content.subject ?? '' }; // SMS: text only
+  }
+}