@cubis/foundry 0.3.82 → 0.3.84

package/workflows/skills/microservices-design/SKILL.md

@@ -1,82 +0,0 @@
----
-name: microservices-design
-description: Microservices architecture patterns covering service decomposition, API gateways, service mesh, saga pattern, event sourcing, and deployment strategies for distributed applications.
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: Claude Code, Codex, GitHub Copilot
----
-
-# Microservices Design
-
-## Purpose
-
-Provide systematic guidance for designing, building, and operating microservices architectures. Covers service boundary identification, inter-service communication patterns, distributed transaction management, observability instrumentation, and deployment strategies. Ensures that microservices deliver on their promise of independent deployability and team autonomy without introducing unmanageable operational complexity.
-
-## When to Use
-
-- Decomposing a monolith into independently deployable services
-- Defining service boundaries using domain-driven design techniques
-- Choosing between synchronous and asynchronous communication patterns
-- Implementing distributed transactions with saga orchestration or choreography
-- Designing API gateways, service meshes, or sidecar proxy configurations
-- Planning observability across a multi-service architecture
-- Establishing deployment pipelines for independent service releases
-- Evaluating whether microservices are the right architecture for a given system
-
-## Instructions
-
-1. **Validate the need for microservices before decomposing** — Verify that the system has independent scaling requirements, separate team ownership boundaries, or distinct deployment cadences that justify the operational overhead of distribution so that complexity is added only where it pays for itself.
-
-2. **Identify service boundaries using bounded contexts** — Apply domain-driven design to discover bounded contexts where each context owns a cohesive set of domain concepts, data, and business rules so that services are aligned with business capabilities rather than technical layers. See `references/decomposition.md`.
-
-3. **Design each service around a single business capability** — A service should own one capability end-to-end (data store, business logic, API) so that changes to one capability do not require coordinated deployments across multiple services.
-
-4. **Choose communication patterns by coupling tolerance** — Use synchronous HTTP/gRPC for queries requiring immediate responses and asynchronous messaging for commands that tolerate eventual consistency so that coupling between services is explicit and intentional. See `references/communication-patterns.md`.
-
-5. **Implement an API gateway as the single entry point** — Route external traffic through a gateway that handles authentication, rate limiting, request routing, and protocol translation so that cross-cutting concerns are centralized rather than duplicated in every service.
-
-6. **Use the saga pattern for distributed transactions** — Replace two-phase commits with sagas (orchestration for complex workflows, choreography for simple ones) with compensating actions for rollback so that transactions span service boundaries without distributed locks. See `references/saga-pattern.md`.
-
-7. **Design events as first-class contracts** — Define event schemas with versioning, publish events to a durable log, and let consumers process them independently so that services can react to domain changes without direct coupling to the producer.
-
-8. **Deploy a service mesh for operational concerns** — Offload mTLS, retries, circuit breaking, and traffic shaping to the mesh infrastructure (Istio, Linkerd) so that service code focuses on business logic rather than network resilience.
-
-9. **Instrument every service with distributed tracing** — Propagate correlation IDs across all service calls, emit spans with timing data, and aggregate traces centrally so that end-to-end request flows are visible and latency bottlenecks can be isolated. See `references/observability.md`.
-
-10. **Enforce independent deployability as an architectural constraint** — Every service must be deployable without coordinating with other services. If a change requires simultaneous deployment of two services, the boundary is wrong and must be refactored.
-
-11. **Implement health checks and readiness probes** — Expose `/health` (liveness) and `/ready` (readiness) endpoints that check dependencies so that orchestrators can route traffic only to healthy instances and restart stuck ones.
-
-12. **Use contract testing to prevent integration breakage** — Write consumer-driven contract tests (Pact, Spring Cloud Contract) instead of relying solely on end-to-end tests so that API compatibility is verified early and cheaply without requiring all services to be running.
-
-13. **Design for graceful degradation** — When a downstream service is unavailable, return cached data, default values, or a reduced feature set rather than propagating the failure so that user-facing functionality degrades proportionally rather than catastrophically.
-
-14. **Version APIs explicitly from day one** — Use URL path versioning (v1, v2) or header-based versioning and maintain backward compatibility for at least one previous version so that consumers can migrate at their own pace. See `references/deployment.md`.
-
-15. **Automate canary deployments and rollback** — Deploy new versions to a small traffic percentage first, monitor error rates and latency, and auto-rollback if SLOs are breached so that bad deployments are caught before they affect all users.
-
-16. **Centralize configuration management** — Use a configuration server or environment-specific secret stores (Vault, AWS Secrets Manager) rather than config files baked into images so that configuration changes do not require redeployment.
-
-## Output Format
-
-Deliver:
-
-1. **Service boundary map** — List of services with owned capabilities, data stores, and team ownership
-2. **Communication topology** — Sync vs. async patterns between each service pair with protocol choices
-3. **Saga design** — Transaction flow with compensating actions for each failure point
-4. **Observability plan** — Metrics, traces, and logs for each service with alerting thresholds
-5. **Deployment strategy** — Pipeline stages, canary configuration, and rollback triggers
-
-## References
-
-Load only what the current task requires.
-
-| File | Load when |
-| --- | --- |
-| `references/decomposition.md` | Task involves identifying service boundaries, bounded contexts, or domain modeling. |
-| `references/communication-patterns.md` | Task involves sync vs. async patterns, API gateways, or protocol selection. |
-| `references/saga-pattern.md` | Task involves distributed transactions, compensation logic, or orchestration vs. choreography. |
-| `references/observability.md` | Task involves distributed tracing, metrics collection, log aggregation, or alerting. |
-| `references/deployment.md` | Task involves CI/CD pipelines, canary releases, blue-green deployments, or rollback strategies. |

package/workflows/skills/microservices-design/evals/assertions.md

@@ -1,52 +0,0 @@
-# Microservices Design Eval Assertions
-
-## Eval 1: Service Decomposition Strategy
-
-This eval tests the ability to identify service boundaries using domain-driven design, define data ownership, and plan an incremental migration from a monolith.
-
-### Assertions
-
-| # | Type | What it checks | Why it matters |
-|---|------|----------------|----------------|
-| 1 | contains | `bounded context` — DDD-driven boundaries | Service boundaries must align with business domains, not technical layers. Bounded contexts ensure each service owns a cohesive domain model with clear interfaces to other contexts. |
-| 2 | contains | `data ownership` — Per-service data stores | A shared database is the number one cause of microservices failure. Each service must own its data and expose it only through APIs or events. Without this, services cannot deploy independently. |
-| 3 | contains | `strangler` — Incremental migration pattern | Big-bang rewrites have a high failure rate. The strangler fig pattern extracts services one at a time behind a routing layer, allowing the monolith to shrink incrementally with rollback capability. |
-| 4 | contains | `event` — Asynchronous communication | Synchronous-only communication between services creates tight coupling and cascading failures. Event-driven patterns decouple producers from consumers and enable eventual consistency. |
-| 5 | contains | `API gateway` — External traffic routing | An API gateway provides a stable external interface while internal service boundaries evolve. It also centralizes authentication, rate limiting, and request routing. |
-
-### What a passing response looks like
-
-- 5-7 bounded contexts identified: User/Identity, Catalog, Order, Payment, Inventory, Shipping, Notification.
-- Each service owns its data store (User service owns user table, Order service owns orders table).
-- Cross-service data access via API calls or events, no shared database.
-- Strangler fig migration: start with the least-coupled context (e.g., Notification), route via gateway, extract one service per sprint/quarter.
-- Event-driven communication for order-placed, payment-completed, shipment-created events.
-- API gateway routes external traffic, authenticates requests, and fans out to internal services.
-- Team ownership model: one team per 1-2 services with full autonomy over their deployment pipeline.
-
----
-
-## Eval 2: Saga Orchestration Pattern
-
-This eval tests the ability to design a saga with proper step sequencing, compensating actions, timeout handling, and failure recovery for a multi-service distributed transaction.
-
-### Assertions
-
-| # | Type | What it checks | Why it matters |
-|---|------|----------------|----------------|
-| 1 | contains | `compensat` — Compensating action design | Every forward step in a saga must have a reverse (compensating) action. Without compensation, a failed saga leaves the system in an inconsistent state with charged payments and no order. |
-| 2 | contains | `orchestrat` — Central orchestrator pattern | Complex multi-step workflows need a central orchestrator to manage the saga state machine. Pure choreography becomes unmanageable beyond 3-4 steps and makes debugging nearly impossible. |
-| 3 | contains | `timeout` — Step-level timeout handling | A downstream service that hangs indefinitely blocks the entire saga. Each step must have a timeout after which the orchestrator triggers compensation for already-completed steps. |
-| 4 | contains | `idempoten` — Idempotent actions and compensations | Network retries mean both forward and compensating actions may execute multiple times. Without idempotency, retries create duplicate charges, double inventory releases, or ghost shipments. |
-| 5 | contains | `state` — Persistent saga state tracking | If the orchestrator crashes mid-saga, it must recover by reading persisted state. Without durable state, in-flight sagas are lost and the system ends up in an unrecoverable inconsistent state. |
-
-### What a passing response looks like
-
-- Saga orchestrator as a dedicated service with a state machine (states: STARTED, PAYMENT_CHARGED, INVENTORY_RESERVED, SHIPMENT_SCHEDULED, COMPLETED, COMPENSATING, FAILED).
-- Forward steps: CreateOrder -> ChargePayment -> ReserveInventory -> ScheduleShipment -> SendNotification.
-- Compensating actions: CancelOrder, RefundPayment, ReleaseInventory, CancelShipment (notification has no compensation — it is the last step).
-- Failure scenario 1: InventoryService fails -> refund payment -> cancel order.
-- Failure scenario 2: ShippingService times out after 30s -> release inventory -> refund payment -> cancel order.
-- Saga state persisted in a database table with step status, timestamps, and idempotency keys.
-- Idempotency: each step checks if already completed before executing, compensations check if already reversed.
-- Observability: saga ID in all log entries, trace spans per step, dashboard for saga completion rates and failure reasons.

package/workflows/skills/microservices-design/evals/evals.json

@@ -1,68 +0,0 @@
-{
-  "evals": [
-    {
-      "name": "service-decomposition-strategy",
-      "description": "Validate that the skill produces a service decomposition plan using domain-driven design with proper bounded context identification, data ownership, communication patterns, and team alignment for a monolith-to-microservices migration.",
-      "input": "A monolithic e-commerce platform handles user management, product catalog, order processing, payment, inventory, shipping, and notifications. The team wants to decompose it into microservices. The monolith currently serves 5,000 concurrent users with a shared PostgreSQL database. Identify bounded contexts, define service boundaries, specify which data each service owns, determine communication patterns between services, and propose a phased migration strategy that avoids a big-bang rewrite.",
-      "assertions": [
-        {
-          "type": "contains",
-          "value": "bounded context",
-          "description": "The decomposition must use bounded contexts from domain-driven design to identify service boundaries aligned with business capabilities rather than technical layers."
-        },
-        {
-          "type": "contains",
-          "value": "data ownership",
-          "description": "The design must specify which service owns which data entities and how cross-service data access is handled (API calls, events, or data replication) to eliminate shared database coupling."
-        },
-        {
-          "type": "contains",
-          "value": "strangler",
-          "description": "The migration strategy must use the strangler fig pattern or an equivalent incremental approach to extract services from the monolith one at a time without requiring a complete rewrite."
-        },
-        {
-          "type": "contains",
-          "value": "event",
-          "description": "The design must include event-driven communication for at least some service interactions (e.g., order placed, payment completed) to reduce synchronous coupling between services."
-        },
-        {
-          "type": "contains",
-          "value": "API gateway",
-          "description": "The design must include an API gateway to route external traffic, handle authentication, and provide a stable public API while internal service boundaries evolve."
-        }
-      ]
-    },
-    {
-      "name": "saga-orchestration-pattern",
-      "description": "Validate that the skill produces a saga orchestration design with proper step sequencing, compensating actions, failure handling, timeout management, and observability for a multi-service transaction.",
-      "input": "Design a saga for an order fulfillment workflow that spans five services: OrderService creates the order, PaymentService charges the customer, InventoryService reserves stock, ShippingService schedules delivery, and NotificationService sends confirmation. Each step can fail independently. Design the saga orchestrator with step sequencing, compensating actions for each step, timeout handling, partial failure recovery, and observability. Show the happy path and at least two failure scenarios with their compensation flows.",
-      "assertions": [
-        {
-          "type": "contains",
-          "value": "compensat",
-          "description": "The saga must define a compensating action for each step (refund payment, release inventory, cancel shipment) that reverses the effect of a completed step when a subsequent step fails."
-        },
-        {
-          "type": "contains",
-          "value": "orchestrat",
-          "description": "The design must use a central saga orchestrator that coordinates the sequence of steps and manages the saga state machine rather than relying solely on event choreography for this complex workflow."
-        },
-        {
-          "type": "contains",
-          "value": "timeout",
-          "description": "The design must include timeout handling for each saga step so that a hung downstream service does not block the entire saga indefinitely."
-        },
-        {
-          "type": "contains",
-          "value": "idempoten",
-          "description": "Both forward actions and compensating actions must be idempotent so that retries during failure recovery do not create duplicate side effects."
-        },
-        {
-          "type": "contains",
-          "value": "state",
-          "description": "The saga must maintain persistent state (e.g., in a database) tracking which steps have completed, which have failed, and which compensations have run so that recovery is possible after an orchestrator crash."
-        }
-      ]
-    }
-  ]
-}

package/workflows/skills/microservices-design/examples/01-monolith-decomposition.md

@@ -1,120 +0,0 @@
-# Example: Monolith-to-Microservices Decomposition
-
-## Prompt
-
-> We have a monolithic e-commerce platform (Node.js, PostgreSQL) handling users, products, orders, payments, inventory, and shipping. We want to break it into microservices without a big-bang rewrite. How do we identify boundaries, handle shared data, and migrate incrementally?
-
-## Response
-
-### Bounded Context Identification
-
-Using domain-driven design event storming, we identify 7 bounded contexts aligned with business capabilities:
-
-| Bounded Context | Core Entities | Key Events | Team |
-|----------------|---------------|------------|------|
-| **Identity** | User, Role, Session | user.registered, user.authenticated | Platform team |
-| **Catalog** | Product, Category, Brand | product.created, product.updated | Catalog team |
-| **Order** | Order, OrderLine, OrderStatus | order.placed, order.confirmed, order.cancelled | Commerce team |
-| **Payment** | Payment, Refund, PaymentMethod | payment.charged, payment.refunded | Payments team |
-| **Inventory** | StockLevel, Reservation, Warehouse | stock.reserved, stock.released, stock.depleted | Supply chain team |
-| **Shipping** | Shipment, TrackingEvent, Carrier | shipment.created, shipment.delivered | Logistics team |
-| **Notification** | Template, Channel, DeliveryLog | notification.sent, notification.failed | Platform team |
-
-### Data Ownership Rules
-
-Each service owns its data exclusively. Cross-context data access is handled through:
-
-1. **API calls** for synchronous queries (e.g., Order service calls Catalog service to get product details for order confirmation).
-2. **Events** for asynchronous state propagation (e.g., Catalog publishes `product.updated`, Order service caches relevant product data locally).
-3. **Data replication** for read-heavy cross-context needs (e.g., Order service maintains a read-only projection of product names and prices to avoid synchronous calls during checkout).
-
-**Anti-pattern avoided:** No shared database. The monolith's single PostgreSQL database will be split so each service has its own schema or database instance.
-
-### Communication Patterns
-
-```
-  External clients
-        │
-        ▼
-  ┌──────────┐
-  │   API    │  Authentication, rate limiting,
-  │ Gateway  │  request routing, TLS termination
-  └────┬─────┘
-       │
-  ┌────┼────────────────────────────────────┐
-  │    │         Service Mesh (Istio)       │
-  │    │    mTLS, retries, circuit breaking │
-  │    │                                    │
-  │  ┌─▼──┐  sync   ┌──────┐              │
-  │  │Order│────────►│Catalog│              │
-  │  │     │         └──────┘              │
-  │  └──┬──┘                               │
-  │     │ event: order.placed              │
-  │     ▼                                  │
-  │  ┌──────┐  event: payment.charged      │
-  │  │Payment│──────────────────┐          │
-  │  └──────┘                   ▼          │
-  │                         ┌────────┐     │
-  │                         │Inventory│     │
-  │                         └───┬────┘     │
-  │                             │ event     │
-  │                             ▼          │
-  │                         ┌────────┐     │
-  │                         │Shipping│     │
-  │                         └───┬────┘     │
-  │                             │ event     │
-  │                             ▼          │
-  │                         ┌──────────┐   │
-  │                         │Notification│  │
-  │                         └──────────┘   │
-  └────────────────────────────────────────┘
-```
-
-- **Synchronous (gRPC):** Order -> Catalog (product lookup during checkout). Low latency, circuit breaker protected.
-- **Asynchronous (Kafka events):** Order -> Payment -> Inventory -> Shipping -> Notification. Decoupled, at-least-once delivery.
-
-### API Gateway Configuration
-
-The API gateway provides a stable external API while internal boundaries evolve:
-
-- `/api/v1/products/*` -> Catalog Service
-- `/api/v1/orders/*` -> Order Service
-- `/api/v1/users/*` -> Identity Service
-- Authentication: JWT validation at the gateway, user context forwarded as headers.
-- Rate limiting: per-API-key and per-endpoint limits.
-
-### Migration Strategy: Strangler Fig
-
-**Phase 1 (Month 1-2): Extract Notification service**
-- Lowest coupling to other domains (no synchronous callers depend on it).
-- Create Notification service, deploy alongside monolith.
-- Monolith publishes events to Kafka instead of sending notifications directly.
-- Notification service consumes events and sends emails/push/SMS.
-- Rollback: re-enable notification sending in monolith, stop consumer.
-
-**Phase 2 (Month 3-4): Extract Catalog service**
-- High read traffic but low write coupling.
-- Stand up Catalog service with its own PostgreSQL.
-- Migrate product data using dual-write (monolith writes to both old and new DB).
-- Gateway routes `/products/*` to new service.
-- Verify data consistency, cut over reads, then stop dual-write.
-
-**Phase 3 (Month 5-7): Extract Payment service**
-- Compliance and PCI scope benefit from isolation.
-- Payment service owns payment tables, exposes charge/refund API.
-- Order flow in monolith calls Payment service instead of internal payment module.
-
-**Phase 4 (Month 8-10): Extract Inventory and Shipping**
-- These are tightly coupled; extract together or in quick succession.
-- Event-driven: Order -> Payment -> Inventory -> Shipping.
-
-**Phase 5 (Month 11-12): Extract Order and Identity**
-- These are the core of the monolith and the last to leave.
-- At this point, the monolith is thin enough to replace entirely.
-
-### Risk Mitigations
-
-- **Feature flags** on every extraction to enable instant rollback to monolith behavior.
-- **Shadow mode** for new services: run both paths, compare outputs, alert on divergence.
-- **Contract tests** between each service pair before cutting over.
-- **Shared nothing** from day one: no service reads another service's database tables.

package/workflows/skills/microservices-design/examples/02-saga-order-fulfillment.md

@@ -1,192 +0,0 @@
-# Example: Saga Pattern for Order Fulfillment
-
-## Prompt
-
-> Design a saga for our order fulfillment flow. It spans OrderService, PaymentService, InventoryService, ShippingService, and NotificationService. Each can fail independently. Show the orchestrator design, compensating actions, timeout handling, and at least two failure scenarios.
-
-## Response
-
-### Saga State Machine
-
-```
-  ┌─────────┐
-  │ CREATED │
-  └────┬────┘
-       │ CreateOrder
-       ▼
-  ┌────────────┐
-  │ORDER_CREATED│
-  └────┬───────┘
-       │ ChargePayment
-       ▼
-  ┌───────────────┐
-  │PAYMENT_CHARGED│──── failure ──► COMPENSATING
-  └────┬──────────┘                     │
-       │ ReserveInventory               │ RefundPayment
-       ▼                                ▼
-  ┌──────────────────┐            ┌───────────────┐
-  │INVENTORY_RESERVED│            │PAYMENT_REFUNDED│
-  └────┬─────────────┘            └────┬──────────┘
-       │ ScheduleShipment              │ CancelOrder
-       ▼                               ▼
-  ┌──────────────────┐            ┌──────────┐
-  │SHIPMENT_SCHEDULED│            │  FAILED  │
-  └────┬─────────────┘            └──────────┘
-       │ SendConfirmation
-       ▼
-  ┌───────────┐
-  │ COMPLETED │
-  └───────────┘
-```
-
-### Orchestrator Design
-
-The saga orchestrator is a dedicated service with persistent state:
-
-```typescript
-interface SagaState {
-  sagaId: string;
-  orderId: string;
-  status: SagaStatus;
-  currentStep: number;
-  steps: StepRecord[];
-  createdAt: Date;
-  updatedAt: Date;
-  idempotencyKey: string;
-}
-
-interface StepRecord {
-  name: string;
-  status: 'pending' | 'completed' | 'failed' | 'compensated';
-  requestId: string; // idempotency key for this step
-  completedAt?: Date;
-  error?: string;
-  timeoutMs: number;
-}
-
-enum SagaStatus {
-  STARTED = 'STARTED',
-  ORDER_CREATED = 'ORDER_CREATED',
-  PAYMENT_CHARGED = 'PAYMENT_CHARGED',
-  INVENTORY_RESERVED = 'INVENTORY_RESERVED',
-  SHIPMENT_SCHEDULED = 'SHIPMENT_SCHEDULED',
-  COMPLETED = 'COMPLETED',
-  COMPENSATING = 'COMPENSATING',
-  FAILED = 'FAILED',
-}
-```
-
-### Step Definitions with Compensating Actions
-
-| Step | Forward Action | Compensating Action | Timeout |
-|------|---------------|---------------------|---------|
-| 1. CreateOrder | Create order record with status `pending` | Cancel order, set status `cancelled` | 5s |
-| 2. ChargePayment | Charge customer via payment gateway | Refund the charged amount | 30s |
-| 3. ReserveInventory | Decrement stock, create reservation | Release reservation, restore stock | 10s |
-| 4. ScheduleShipment | Create shipment with carrier API | Cancel shipment with carrier | 30s |
-| 5. SendConfirmation | Send email/push notification | No compensation (notification is terminal) | 10s |
-
-### Idempotency
-
-Every step (forward and compensating) is idempotent:
-
-```typescript
-async function chargePayment(sagaId: string, orderId: string, amount: number, requestId: string) {
-  // Check if already processed
-  const existing = await db.query(
-    'SELECT * FROM payment_transactions WHERE idempotency_key = $1',
-    [requestId]
-  );
-  if (existing.rows.length > 0) {
-    return existing.rows[0]; // Already charged, return existing result
-  }
-
-  // Process payment
-  const result = await paymentGateway.charge({ amount, idempotencyKey: requestId });
-
-  // Record the transaction
-  await db.query(
-    'INSERT INTO payment_transactions (idempotency_key, saga_id, order_id, amount, status) VALUES ($1, $2, $3, $4, $5)',
-    [requestId, sagaId, orderId, amount, result.status]
-  );
-
-  return result;
-}
-```
-
-### Timeout Handling
-
-Each step has a timeout. When a step exceeds its timeout:
-
-1. Orchestrator marks the step as `failed` with reason `timeout`.
-2. Orchestrator transitions to `COMPENSATING` state.
-3. Compensation runs in reverse order for all completed steps.
-4. If a compensation step also times out, it is retried up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s).
-5. If compensation exhausts retries, the saga enters `FAILED` state and alerts the on-call team for manual intervention.
-
-### Failure Scenario 1: Inventory Reservation Fails
-
-The warehouse is out of stock for the requested product.
-
-```
-Step 1: CreateOrder      ✅ completed
-Step 2: ChargePayment    ✅ completed ($49.99 charged)
-Step 3: ReserveInventory ❌ failed (insufficient stock)
-  → Begin compensation
-Step 2 compensation: RefundPayment  ✅ ($49.99 refunded)
-Step 1 compensation: CancelOrder    ✅ (status → cancelled)
-  → Saga status: FAILED
-  → Customer notified: "Sorry, the item is out of stock. Your payment has been refunded."
-```
-
-### Failure Scenario 2: Shipping Service Times Out
-
-The carrier API is experiencing an outage and does not respond within 30 seconds.
-
-```
-Step 1: CreateOrder      ✅ completed
-Step 2: ChargePayment    ✅ completed ($49.99 charged)
-Step 3: ReserveInventory ✅ completed (3 units reserved)
-Step 4: ScheduleShipment ⏱️ timeout after 30s
-  → Begin compensation
-Step 3 compensation: ReleaseInventory ✅ (3 units released)
-Step 2 compensation: RefundPayment    ✅ ($49.99 refunded)
-Step 1 compensation: CancelOrder      ✅ (status → cancelled)
-  → Saga status: FAILED
-  → Alert: shipping-service timeout, saga_id=abc123
-  → Customer notified: "We're having trouble processing your order. Your payment has been refunded."
-```
-
-### Saga State Persistence
-
-```sql
-CREATE TABLE sagas (
-  saga_id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  order_id       UUID NOT NULL,
-  status         TEXT NOT NULL DEFAULT 'STARTED',
-  current_step   INT NOT NULL DEFAULT 0,
-  idempotency_key TEXT UNIQUE NOT NULL,
-  created_at     TIMESTAMPTZ DEFAULT now(),
-  updated_at     TIMESTAMPTZ DEFAULT now()
-);
-
-CREATE TABLE saga_steps (
-  id             SERIAL PRIMARY KEY,
-  saga_id        UUID REFERENCES sagas(saga_id),
-  step_name      TEXT NOT NULL,
-  step_order     INT NOT NULL,
-  status         TEXT NOT NULL DEFAULT 'pending',
-  request_id     TEXT UNIQUE NOT NULL,
-  timeout_ms     INT NOT NULL,
-  completed_at   TIMESTAMPTZ,
-  error_message  TEXT,
-  UNIQUE(saga_id, step_order)
-);
-```
-
-### Observability
-
-- Saga ID propagated as correlation ID in all service calls and log entries.
-- Distributed trace span per saga step (forward and compensation).
-- Dashboard: saga completion rate, average duration, failure rate by step, compensation success rate.
-- Alerts: saga failure rate > 1%, compensation failure (requires manual intervention), saga stuck in COMPENSATING > 5 minutes.