feat(iios): idempotency ledger on outbound egress (409 on key reuse) (P9)

OutboundService.send is now opt-in idempotent: an explicit idempotencyKey routes
the send through IdempotencyService.run (Slice 6), so reusing a key with a
different target/payload returns a 409 conflict and a same-key/same-request retry
replays the cached command. The inner findUnique early-return stays as a backstop
so a FAILED-then-retried send never collides on the command's unique key. Keyless
sends keep the old behavior (no ledger row).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packages/iios-service/src/adapters/adapters.spec.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import { ConflictException } from '@nestjs/common';
 import { PrismaClient } from '@prisma/client';
 import { DlqService } from '../outbox/dlq.service';
 import { resetDb } from '../test-utils/reset-db';
@@ -9,6 +10,7 @@ import { signedFixture, emailFixture } from '@insignia/iios-adapter-sdk';
 import { AdapterRegistry } from './adapter.registry';
 import { InboundService } from './inbound.service';
 import { OutboundService } from './outbound.service';
+import { IdempotencyService } from '../idempotency/idempotency.service';
 import { CapabilityBroker } from '../capability/capability.broker';
 import { CapabilityProviderRegistry } from '../capability/capability.registry';
 import { RawEventProjector } from './raw-event.projector';
@@ -81,7 +83,7 @@ describe('Adapter inbound (P5)', () => {
 
 describe('Adapter outbound (P5)', () => {
   const outbound = (limit?: number): OutboundService => {
-    const s = new OutboundService(asService, new CapabilityBroker(makeFakePorts(), new CapabilityProviderRegistry()));
+    const s = new OutboundService(asService, new CapabilityBroker(makeFakePorts(), new CapabilityProviderRegistry()), new IdempotencyService(asService));
     if (limit) s.limit = limit;
     return s;
   };
@@ -112,7 +114,7 @@ describe('Adapter outbound (P5)', () => {
   it('broker obligation DENY_OUTBOUND → command BLOCKED, no send (P9)', async () => {
     const ports = makeFakePorts();
     ports.opa.setDecision({ allow: true, obligations: [{ kind: 'DENY_OUTBOUND', reason: 'recipient opted out' }] });
-    const svc = new OutboundService(asService, new CapabilityBroker(ports, new CapabilityProviderRegistry()));
+    const svc = new OutboundService(asService, new CapabilityBroker(ports, new CapabilityProviderRegistry()), new IdempotencyService(asService));
     const cmd = await svc.send('WEBHOOK', 'user@x', { text: 'hi' }, 'blk-1');
     expect(cmd.status).toBe('BLOCKED');
     expect(cmd.providerRef).toBe('blocked');
@@ -121,7 +123,7 @@ describe('Adapter outbound (P5)', () => {
   it('CMP allow → command records the consent receipt (P9 slice 2)', async () => {
     const ports = makeFakePorts();
     ports.cmp.setStatus('ALLOW');
-    const svc = new OutboundService(asService, new CapabilityBroker(ports, new CapabilityProviderRegistry()));
+    const svc = new OutboundService(asService, new CapabilityBroker(ports, new CapabilityProviderRegistry()), new IdempotencyService(asService));
     const cmd = await svc.send('WEBHOOK', 'user@x', { text: 'hi' }, 'consent-1', 'scope1', 'support');
     expect(cmd.status).toBe('SENT');
     expect(cmd.consentReceiptRef).toBe('fake-receipt');
@@ -130,7 +132,7 @@ describe('Adapter outbound (P5)', () => {
   it('CMP DENY for the purpose → command BLOCKED, no send (P9 slice 2)', async () => {
     const ports = makeFakePorts();
     ports.cmp.denyPurpose('marketing');
-    const svc = new OutboundService(asService, new CapabilityBroker(ports, new CapabilityProviderRegistry()));
+    const svc = new OutboundService(asService, new CapabilityBroker(ports, new CapabilityProviderRegistry()), new IdempotencyService(asService));
     const cmd = await svc.send('WEBHOOK', 'user@x', { text: 'promo' }, 'consent-2', 'scope1', 'marketing');
     expect(cmd.status).toBe('BLOCKED');
     expect(await prisma.iiosDeliveryAttempt.count({ where: { commandId: cmd.id, status: 'SENT' } })).toBe(0);
@@ -146,4 +148,18 @@ describe('Adapter outbound (P5)', () => {
     expect(a2.status).toBe('RATE_LIMITED');
     expect(b1.status).toBe('SENT');
   });
+
+  it('idempotency ledger: same key + a different target → conflict, no second command (P9 slice 10)', async () => {
+    const svc = outbound();
+    const first = await svc.send('WEBHOOK', 'user@a', { text: 'hi' }, 'dup-key');
+    expect(first.status).toBe('SENT');
+    await expect(svc.send('WEBHOOK', 'user@b', { text: 'hi' }, 'dup-key')).rejects.toBeInstanceOf(ConflictException);
+    expect(await prisma.iiosOutboundCommand.count({ where: { idempotencyKey: 'dup-key' } })).toBe(1);
+  });
+
+  it('opt-in: a keyless send creates a command but writes no idempotency-ledger row (P9 slice 10)', async () => {
+    const cmd = await outbound().send('WEBHOOK', 'user@x', { text: 'hi' });
+    expect(cmd.status).toBe('SENT');
+    expect(await prisma.iiosIdempotencyCommand.count()).toBe(0);
+  });
 });

packages/iios-service/src/adapters/outbound.service.ts

@@ -3,6 +3,7 @@ import { Injectable } from '@nestjs/common';
 import { Prisma } from '@prisma/client';
 import { PrismaService } from '../prisma/prisma.service';
 import { CapabilityBroker } from '../capability/capability.broker';
+import { IdempotencyService } from '../idempotency/idempotency.service';
 import { recordAudit } from '../observability/audit';
 
 /**
@@ -23,55 +24,67 @@ export class OutboundService {
   constructor(
     private readonly prisma: PrismaService,
     private readonly broker: CapabilityBroker,
+    private readonly idempotency: IdempotencyService,
   ) {}
 
   async send(
     channelType: string,
     target: string,
     payload: Record<string, unknown>,
-    idempotencyKey: string = randomUUID(),
+    idempotencyKey?: string,
     scopeId?: string,
     purpose?: string,
   ) {
-    const existing = await this.prisma.iiosOutboundCommand.findUnique({ where: { idempotencyKey } });
-    if (existing) return existing;
+    const key = idempotencyKey ?? randomUUID();
+
+    // The actual send. The inner findUnique stays as a backstop so a FAILED-then-retried
+    // command returns the existing row instead of colliding on idempotencyKey @unique.
+    const body = async () => {
+      const existing = await this.prisma.iiosOutboundCommand.findUnique({ where: { idempotencyKey: key } });
+      if (existing) return existing;
+
+      // Per-target rate limit AND per-tenant quota (a noisy tenant can't starve shared egress).
+      if (!(await this.allow(channelType, target)) || !(await this.allowTenant(scopeId))) {
+        const cmd = await this.prisma.iiosOutboundCommand.create({
+          data: { channelType, target, scopeId, payload: payload as Prisma.InputJsonValue, status: 'RATE_LIMITED', idempotencyKey: key },
+        });
+        await this.prisma.iiosDeliveryAttempt.create({ data: { commandId: cmd.id, attemptNo: 1, status: 'RATE_LIMITED' } });
+        return cmd;
+      }
 
-    // Per-target rate limit AND per-tenant quota (a noisy tenant can't starve shared egress).
-    if (!(await this.allow(channelType, target)) || !(await this.allowTenant(scopeId))) {
       const cmd = await this.prisma.iiosOutboundCommand.create({
-        data: { channelType, target, scopeId, payload: payload as Prisma.InputJsonValue, status: 'RATE_LIMITED', idempotencyKey },
+        data: { channelType, target, scopeId, payload: payload as Prisma.InputJsonValue, status: 'PENDING', idempotencyKey: key },
       });
-      await this.prisma.iiosDeliveryAttempt.create({ data: { commandId: cmd.id, attemptNo: 1, status: 'RATE_LIMITED' } });
-      return cmd;
-    }
 
-    const cmd = await this.prisma.iiosOutboundCommand.create({
-      data: { channelType, target, scopeId, payload: payload as Prisma.InputJsonValue, status: 'PENDING', idempotencyKey },
-    });
+      let result;
+      try {
+        result = await this.broker.invoke({ capability: 'channel.send', channelType, target, payload, idempotencyKey: key, scopeId, purpose });
+      } catch (err) {
+        // Fail-closed (e.g. PolicyDeniedError): mark the command FAILED, record the attempt, propagate.
+        await this.prisma.$transaction([
+          this.prisma.iiosOutboundCommand.update({ where: { id: cmd.id }, data: { status: 'FAILED' } }),
+          this.prisma.iiosDeliveryAttempt.create({ data: { commandId: cmd.id, attemptNo: 1, status: 'FAILED', errorCode: (err as Error).name } }),
+        ]);
+        throw err;
+      }
 
-    let result;
-    try {
-      result = await this.broker.invoke({ capability: 'channel.send', channelType, target, payload, idempotencyKey, scopeId, purpose });
-    } catch (err) {
-      // Fail-closed (e.g. PolicyDeniedError): mark the command FAILED, record the attempt, propagate.
-      await this.prisma.$transaction([
-        this.prisma.iiosOutboundCommand.update({ where: { id: cmd.id }, data: { status: 'FAILED' } }),
-        this.prisma.iiosDeliveryAttempt.create({ data: { commandId: cmd.id, attemptNo: 1, status: 'FAILED', errorCode: (err as Error).name } }),
+      const [updated] = await this.prisma.$transaction([
+        this.prisma.iiosOutboundCommand.update({
+          where: { id: cmd.id },
+          data: { status: result.outcome, providerRef: result.providerRef, consentReceiptRef: result.consentReceiptRef },
+        }),
+        this.prisma.iiosDeliveryAttempt.create({
+          data: { commandId: cmd.id, attemptNo: 1, status: result.outcome, providerRef: result.providerRef, latencyMs: result.latencyMs, errorCode: result.errorCode },
+        }),
       ]);
-      throw err;
-    }
+      await recordAudit(this.prisma, { action: 'channel.send', resourceType: 'outbound_command', resourceId: cmd.id, scopeId });
+      return updated;
+    };
 
-    const [updated] = await this.prisma.$transaction([
-      this.prisma.iiosOutboundCommand.update({
-        where: { id: cmd.id },
-        data: { status: result.outcome, providerRef: result.providerRef, consentReceiptRef: result.consentReceiptRef },
-      }),
-      this.prisma.iiosDeliveryAttempt.create({
-        data: { commandId: cmd.id, attemptNo: 1, status: result.outcome, providerRef: result.providerRef, latencyMs: result.latencyMs, errorCode: result.errorCode },
-      }),
-    ]);
-    await recordAudit(this.prisma, { action: 'channel.send', resourceType: 'outbound_command', resourceId: cmd.id, scopeId });
-    return updated;
+    // Opt-in idempotency: an explicit key routes through the ledger (request-hash conflict → 409,
+    // response replay); a keyless send just runs with a fresh uuid (old behavior).
+    if (!idempotencyKey) return body();
+    return this.idempotency.run({ scopeId, commandName: 'channel.send', key: idempotencyKey, request: { channelType, target, payload, purpose } }, body);
   }
 
   /** Per-tenant egress quota (P9): count this scope's commands in the window vs the cap. */