feat(events): complete P02b-1 transactional event production

.claude/skills/add-architecture-test/SKILL.md

@@ -115,8 +115,9 @@ Patterns to follow:
 
 ### Step 4: Common architecture-test families
 
-**The shipped set is eighteen files, not a family per topic.** Add yours to the one whose
-subject it shares:
+**Choose by subject, not by ADR number.** These common families are starting
+points; inspect the test directory and catalogue for the complete shipped set.
+Add yours to the file whose subject it shares:
 
 | File | What it covers |
 |------|----------------|
@@ -130,6 +131,9 @@ subject it shares:
 | `RequestSurfaceTests.cs` | What the step-4 authority ceiling admits: the two request markers, their permitted sets, the shape of the attributes themselves, and the ban on request shapes MediatR runs with no pipeline. |
 | `PlatformAdminScopeConventionTests.cs` | The single sanctioned `BYPASSRLS` path: who may resolve the keyed platform data source, where connection strings are read, the entry gate, and what the scope must not touch. |
 | `RepositoryLayoutTests.cs` | `No_Source_Folder_Named_Verticals`, the single-frontend-app rule, and the commit-subject grammar — checked by running the `commit-msg` hook. |
+| `DomainEventHandlerTests.cs` | Complete domain-handler/helper/interface census; outbox-only reactions with planted forbidden-capability controls. |
+| `IntegrationEventContractTests.cs` | Production event inheritance, explicit identifier partition derivation and identifier-only payload/serializer shape. |
+| `OutboxProducerConventionTests.cs` | Producer/helper fence against extra connections, commit ownership and direct publication. |
 | `AggregateWriteTests.cs` | The one sanctioned cross-aggregate write, and the count of aggregate roots a handler's ports can write that keeps it at one. |
 | `CustomizationRegistryTests.cs` | The closed renderer registries that exist twice — in C# and in TypeScript — and stop the two drifting. |
 | `AuditConventionTests.cs` | The audit aggregate's shape, the closed-set columns against their `CHECK`s, append-only enforcement at the source level, the closed set of `audit_log` writers, and the `OperationType` table. |
@@ -144,7 +148,7 @@ Rules for surfaces no file covers yet — permissions, the Hub adapters and endp
 [the catalogue](../../../docs/standards/21-architecture-tests-catalogue.md) against
 the phase that ships the code they inspect. Check its Status line before assuming a
 net is under you, and create a new file only when your rule's subject is not one of
-the eighteen above.
+the listed families.
 
 > **The tenancy rules live in three files, and the split is by subject, not by ADR.**
 > All three cite ADR-0036, so "put it with the other ADR-0036 rules" is not a usable

.claude/skills/add-integration-event/SKILL.md

@@ -24,6 +24,14 @@ Amendment 1 (Dapr pub/sub dispatch),
 and [15-event-and-outbox.md](../../../docs/architecture/15-event-and-outbox.md).
 The binding port and envelope contract is
 [ADR-0038](../../../docs/decisions/0038-cross-cutting-port-and-event-contracts.md).
+Accepted [ADR-0057](../../../docs/decisions/0057-transactional-event-production-and-completion.md)
+owns immediate producer admission, completion and payload policy. P02b-1
+Steps 2/3 implement immediate enqueue, payload admission, successful-save
+collection and the completed-provisioning publisher. Step 4 implements the
+production censuses and catalogue enforcement; the
+[delivery record](../../../docs/roadmap/phase-02b-events-auth.md#p02b-1-step-4--producer-enforcement-and-closeout-2026-10-12)
+owns final verification and review status.
+P02b-2/P02b-3 retain dispatcher/inbox decisions.
 
 ## When to use
 
@@ -33,8 +41,10 @@ The binding port and envelope contract is
 
 ## When not to use
 
-- Two aggregates in the **same** module need to coordinate — use MediatR
-  `INotification` (a domain event) and handle it in-process inside that module.
+- A domain fact needs only in-module translation to outbox — use MediatR
+  `INotification` inside the owner transaction. Domain reactions cannot mutate
+  roots or coordinate additional writes; substantive reactions belong in an
+  integration consumer under ADR-0057.
 - The consumer can fetch the data on-demand from the producer's read API.
 - Provider webhooks (Stripe, LiveKit) — they enter via a webhook receiver that
   writes to the outbox itself, not via this skill.
@@ -43,11 +53,11 @@ The binding port and envelope contract is
 
 | Input | Required | Description |
 |-------|----------|-------------|
-| Event name | Yes | `<Verb><Aggregate>IntegrationEventV<N>`, PascalCase + version suffix. |
+| Event name | Yes | `<Aggregate><PastTenseFact>IntegrationEventV<N>`, PascalCase + version suffix. |
 | Producing module | Yes | Owns the aggregate the event describes. |
 | Consuming module(s) | Yes | At least one; can be many. |
 | Topic | Declared | The event's `Topic` override, normally `learnstack.{module}.{aggregate}`. |
-| Schema fields | Yes | `IntegrationEventBase` supplies `EventId`, `OccurredAt`, `TenantId` (all `required`) and demands `Topic` and `PartitionKey` overrides. Everything else is yours to declare. |
+| Schema fields | Yes | `IntegrationEventBase` supplies `EventId`, `OccurredAt`, `TenantId` (all `required`) and demands `Topic` and `PartitionKey` overrides. Additional fields are GUIDs or approved strongly-typed identifiers, optionally nullable; no text, DTOs, collections, binary/raw JSON or serializer overrides. |
 
 ## Workflow
 
@@ -56,25 +66,22 @@ The binding port and envelope contract is
 In `<Producer>.Application.Contracts/IntegrationEvents/<EventName>.cs`:
 
 ```csharp
+[IntegrationEventPartition(nameof(EnrollmentId))]
 public sealed record EnrollmentCreatedIntegrationEventV1 : IntegrationEventBase
 {
     public required Guid EnrollmentId { get; init; }
     public required Guid LearnerId { get; init; }
     public required Guid CourseVersionId { get; init; }
     public Guid? CohortId { get; init; }
-    public required string Source { get; init; }  // "manual" | "billing" | "invitation"
 
     // Both abstract on IntegrationEventBase, so this record does not compile
     // without them — deliberately, because each is a property of the event TYPE
     // and a value with two sources is a value that can disagree with itself.
     public override string Topic => "learnstack.enrollment.enrollment";
 
-    // Ordering is guaranteed per partition key and nowhere else, and the
-    // aggregate this event is about is the ordering domain. Keying on TenantId
-    // instead would serialise the tenant's whole stream onto one partition — a
-    // real throughput cost, and one worth taking deliberately rather than by
-    // inheriting a default.
-    public override string PartitionKey => EnrollmentId.ToString();
+    // Declare EnrollmentId as the partition source. ADR-0057 accepts canonical
+    // identifier derivation; G3 durable publish ordering remains P02b-2.
+    public override string PartitionKey => EnrollmentId.ToString("D");
 }
 ```
 
@@ -87,6 +94,13 @@ five members, and every one of them is mandatory:
   `Integration_Event_TopicNames_FollowConvention`
 - `PartitionKey` — `abstract`; the ordering domain, declared by each event
 
+The concrete record declares `[IntegrationEventPartition(nameof(EnrollmentId))]`.
+Use `[IntegrationEventPartition(nameof(TenantId), tenantWide: true)]` only for an
+explicitly tenant-wide fact. The named non-nullable source must match the actual
+canonical lowercase `D` GUID key; inheriting a declaration is insufficient.
+Approved typed payload identifiers are currently `TenantId`, `OrganizationId`
+and `UserId`; module-local identifiers cross the contract as `Guid`.
+
 It supplies **no** `OrganizationId`, `CorrelationId`, `CausationId` or
 `ActorUserId`: those describe the delivery and travel on
 `IntegrationEventEnvelope`, copied from the outbox row. An organization-owned
@@ -117,17 +131,36 @@ await outbox.EnqueueAsync(new EnrollmentCreatedIntegrationEventV1
     // one layer in, so that spelling needs `courseVersionId.Value`.
     CourseVersionId = request.CourseVersionId,
     CohortId = request.CohortId,
-    Source = request.Source.ToString().ToLowerInvariant(),
 }, cancellationToken);
 
-await db.SaveChangesAsync(cancellationToken);   // atomic
+await db.SaveChangesAsync(cancellationToken);   // flush; owner commits state + outbox + audit
 ```
 
 Rules:
 
-- `IOutbox.EnqueueAsync` enlists in the **ambient unit of work** — the one connection and
-  transaction `IUnitOfWork` owns ([ADR-0040](../../../docs/decisions/0040-ambient-unit-of-work.md)),
-  not a module's `DbContext`. Do not open a second transaction.
+- `IOutbox.EnqueueAsync` validates and INSERTs immediately through the enrolled,
+  announced, writable ambient `IUnitOfWork.Connection`/`Transaction`. It opens
+  no connection, commits nothing and never calls `IEventBus`. The frame compares
+  the live announcement generation and event tenant, including unresolved
+  provisioning; caller snapshots are not authority. Raw transactions cannot
+  bypass producer enrollment. `id = EventId`; duplicates fail.
+- Serialize the concrete runtime event through the existing frozen
+  `IntegrationEventBase.PayloadJsonOptions`. The complete canonical UTF-8 input
+  fits `OutboxPayloadLimits.MaxBytes` (262,144 bytes inclusive) before INSERT;
+  multibyte accounting is bytes, not characters. JSON `metadata` is SQL NULL;
+  `IOutbox` accepts no arbitrary metadata. No DDL size CHECK is claimed.
+- Tenant/organization come from the transaction announcement; correlation,
+  causation and optional causal actor come from trusted execution. That boundary
+  guarantees W3C Activity without a listener. Domain translation mints a new
+  integration EventId and uses its domain EventId as causation. A non-marked
+  event does not erase an announced organization; G1 delivery scope stays open.
+- The owner drains successful-save events FIFO before invariants/MUST audit and
+  commit, at most 256 per transaction. Domain handlers only translate to outbox:
+  no mutation/write stores, nested sends, further raises, publication or providers.
+  Successful enqueue/promotion leaves sticky receipts in every ancestor;
+  `Result.Fail` with such work poisons the unit before frame resolution, even if
+  absorbed. Event-free refusals retain ADR-0040 semantics. Terminal paths discard
+  source state; joiners neither drain nor clear the owner.
 - `SaveChangesAsync` **flushes** the context; it does not commit. `TransactionBehavior` owns
   the commit boundary, so the aggregate change and the outbox row land together because they
   share that transaction — not because one `SaveChanges` wrote both.
@@ -155,13 +188,21 @@ fails the build.
 
 ### Step 4: Consumer — handler + inbox guard
 
+**Inherited target, pending P02b-2 G1 and P02b-3 delivery implementation.** This
+example does not decide inbox ownership, deduplication identity or delivery scope.
+The accepted first flow uses independent Customization `card@1`/`plain@1`
+subscriptions for `TenantCreatedIntegrationEventV1`, not an Audit mirror. G1 must
+prevent one subscription from suppressing its sibling before those handlers ship.
+P02b-3 owns create-only preservation, per-effect MUST audit and the semantic
+key/version Seeder handoff described in ADR-0057.
+
 In `<Consumer>.Application/IntegrationEvents/<HandlerName>.cs`:
 
 ```csharp
-public sealed class CreateAuditEntryOnEnrollmentCreated(
+public sealed class QueueWelcomeNotificationOnEnrollmentCreated(
     IInboxGuard inbox,
-    AuditDbContext db,
-    ILogger<CreateAuditEntryOnEnrollmentCreated> logger)
+    NotificationsDbContext db,
+    ILogger<QueueWelcomeNotificationOnEnrollmentCreated> logger)
     : IIntegrationEventHandler<EnrollmentCreatedIntegrationEventV1>
 {
     public async Task HandleAsync(
@@ -174,8 +215,9 @@ public sealed class CreateAuditEntryOnEnrollmentCreated(
         }
 
         // ... business logic ...
-        var entry = AuditEntry.FromIntegrationEvent(@event);
-        db.AuditEntries.Add(entry);
+        var dispatch = NotificationDispatch.QueueWelcome(
+            @event.LearnerId, @event.EnrollmentId);
+        db.NotificationDispatches.Add(dispatch);
 
         inbox.MarkAsProcessed(@event.EventId, @event.GetType().Name);
         await db.SaveChangesAsync(ct);   // atomic business write + inbox marker
@@ -185,7 +227,8 @@ public sealed class CreateAuditEntryOnEnrollmentCreated(
 
 Rules:
 
-- **Every** `IIntegrationEventHandler` invokes `IInboxGuard.IsAlreadyProcessedAsync`
+- Under the inherited consumer target, **every** `IIntegrationEventHandler` invokes
+  `IInboxGuard.IsAlreadyProcessedAsync`
   before any business logic. The architecture test
   `Integration_Event_Handlers_Use_InboxGuard` holds every handler to it from
   [Phase 02b](../../../docs/roadmap/phase-02b-events-auth.md), which ships the guard; it
@@ -222,7 +265,7 @@ construction-free registry discovers and registers its concrete handlers:
 ```csharp
 builder.AddLearnStackCrossCuttingFoundation(
     deploymentMode,
-    typeof(CreateAuditEntryOnEnrollmentCreated).Assembly);
+    typeof(QueueWelcomeNotificationOnEnrollmentCreated).Assembly);
 ```
 
 Today `InProcessEventBus` resolves the concrete
@@ -234,7 +277,13 @@ remains identical across transports.
 
 ### Step 6: Tests
 
-Two tests minimum:
+Follow the canonical producer rules and remaining consumer obligations in
+[Standards 21](../../../docs/standards/21-architecture-tests-catalogue.md#events-jobs-and-correlation):
+announced transaction/admission, sticky failure receipts, owner completion,
+outbox-only handlers and identifier-only payloads; extend existing partition and
+row-context proofs. Use real production subjects and planted violations, including
+no-listener trace context, failed-save attribution, absorbed descendant refusal,
+byte boundaries, SQL NULL metadata and terminal reuse. For delivered flows:
 
 1. **Producer test** — exercise the handler, assert an `outbox_messages` row exists
    with the right `type`, `topic`, `payload`.
@@ -245,9 +294,9 @@ Two tests minimum:
 
 - `dotnet build` and `dotnet test` pass.
 - `LearnStack.Tests.Architecture` is green — `Integration_Event_TopicNames_FollowConvention`
-  runs today; `Integration_Events_Inherit_From_IntegrationEventBase` and
-  `Integration_Event_Handlers_Use_InboxGuard` are registered for
-  [Phase 02b](../../../docs/roadmap/phase-02b-events-auth.md) and run from there. Check
+  and `Integration_Events_Inherit_From_IntegrationEventBase` run today.
+  `Integration_Event_Handlers_Use_InboxGuard` remains Registered for P02b-3's
+  consumer delivery after G1. Check
   [the catalogue](../../../docs/standards/21-architecture-tests-catalogue.md) for their
   status rather than assuming a net is under you.
 - An integration test confirms the round-trip: handler enqueues → outbox row
@@ -260,10 +309,11 @@ Two tests minimum:
 - **Crossing modules with a domain event.** Domain events stay inside the module
   that owns the aggregate. The moment another module needs to react, it must be an
   integration event.
-- **Forgetting `IInboxGuard`.** The architecture test catches it, but the symptom
-  in production (Kafka redelivery → duplicate work) is silent until then.
+- **Forgetting `IInboxGuard`.** The consumer rule remains Registered until
+  P02b-3; do not infer enforcement from its name. Consumer delivery must prove
+  redelivery cannot duplicate its business effect.
 - **Writing the outbox row in a separate transaction.** Use `IOutbox.EnqueueAsync`
-  inside the ambient `DbContext`; never `new TransactionScope`.
+  through the enrolled ambient `IUnitOfWork`; never `new TransactionScope`.
 - **Supplying a second topic at enqueue or subscription time.** The concrete
   event's `Topic` override is the one source; persistence, envelope and transport
   forward it unchanged.

.claude/skills/code-review/SKILL.md

@@ -108,7 +108,7 @@ Walk the diff for correctness issues. Common shapes:
 | **Race condition** | Read-modify-write without optimistic concurrency (`row_version`) or a transaction. Cross-instance state without `ICacheService` invalidation. |
 | **Resource leak** | `DbContext` / `HttpClient` / file stream not disposed; long-lived `DaprClient` reuse via DI, not `new`. |
 | **Idempotency** | Command with external side effects (LiveKit room, Stripe charge) missing `Idempotency-Key` handling. Integration-event consumer missing `IInboxGuard.IsAlreadyProcessedAsync`. |
-| **Outbox atomicity** | Outbox row written in the same `DbContext` SaveChanges as the aggregate. No separate transaction. |
+| **Outbox atomicity** | Immediate INSERT through the enrolled, announced ambient `IUnitOfWork`; source state/outbox/MUST audit share its transaction. SaveChanges flushes only. ADR-0057 generation, tenant, read-only, payload/metadata and duplicate refusals hold. |
 | **Tenant context restoration** | Background job + integration-event handler restores `TenantContext` before any work. |
 | **Edge cases** | Empty list, zero, negative, max-int, very-long string. Test or guard. |
 | **Time / clock** | Hard-coded UTC / DateTime.Now / DateTime.UtcNow vs `IClock` injection. |
@@ -282,6 +282,26 @@ Author intent: <one-paragraph restatement>
   — a separate rule per [ADR-0038](../../../docs/decisions/0038-cross-cutting-port-and-event-contracts.md)
   and [29-dapr-integration.md § 8](../../../docs/architecture/29-dapr-integration.md);
   architecture test `Dapr_SDK_Types_NotImportedOutsideInfrastructure`.
+- **ADR-0057 producer boundaries.** Domain handlers only translate to outbox;
+  inspect helper/interface paths for mutations, write stores, nested sends,
+  further raises, notification publication and providers. Successful-save events
+  drain FIFO at one owner site before invariants/MUST audit/commit, with a total
+  256 bound. Sticky produced-work receipts reach all ancestors; absorbed
+  `Result.Fail` poisons before frame resolution. Event-free control still commits.
+  Verify failed-save attribution and cleanup on every terminal/same-scope path.
+- **ADR-0057 payload and execution.** Additional fields are identifiers only;
+  concrete-runtime frozen JSON fits the inclusive 262,144-byte UTF-8 cap; JSON
+  metadata is SQL NULL. Trusted execution supplies no-listener Activity and
+  causation/causal actor; transaction announcement supplies tenant/organization.
+  No caller header/snapshot establishes authority. Common non-MediatR audit
+  entry refuses unregistered direct mutation and reconciles only at the outer
+  frame; producer receipts are distinct. P02b-3 delivery/inbox remains open.
+- **Real flow and evidence.** Completed provisioning emits
+  `TenantCreatedIntegrationEventV1`; P02b-1 claims pending rows only. P02b-3 owns
+  separate create-only `card@1`/`plain@1` subscriptions and Seeder identity
+  handoff after G1; no settings invalidation or Audit mirror is the sample.
+  Read current producer/consumer statuses in the catalogue; require production
+  censuses and planted offenders rather than zero-subject passes.
 - **No direct write to `audit_log` / `outbox_messages` /
   `platform_entitlement_cache`.** Use `IAuditStore` / `IOutbox` /
   `IEntitlementProvider.RefreshAsync`.