> ## Documentation Index
> Fetch the complete documentation index at: https://committ.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Triple-Write Orchestrator

> The Saga-pattern engine: Convex, SQLite, and AlarmManager in sequence.

# Triple-Write Orchestrator

The TripleWriteOrchestrator (lib/triple-write-orchestrator.ts) is a Saga-pattern implementation that coordinates multi-step write operations with automatic rollback on failure.

***

## The Three Steps

Every user action that modifies data must write to three independent systems in strict sequence:

| Step | Target                | Timeout | Compensating Function    |
| :--- | :-------------------- | :------ | :----------------------- |
| 1    | Convex Cloud Mutation | 15s     | Convex rollback mutation |
| 2    | Local SQLite Write    | 15s     | SQLite delete            |
| 3    | Hardware Alarm Sync   | 15s     | None (idempotent)        |

***

## Usage

```typescript theme={null}
const saga = new TripleWriteOrchestrator(context);

saga
  .addStep("Convex Mutation",
    async (ctx) => await convexMutation(ctx),
    async (ctx, result) => await convexRollback(result)
  )
  .addStep("Local SQLite Write",
    async (ctx, prev) => await sqliteInsert(prev),
    async (ctx, result) => await sqliteDelete(result)
  )
  .addStep("Hardware Alarm Sync",
    async (ctx) => await scheduleNextAlarm()
  );

const { success, error, rollbackFailed } = await saga.execute();
```

***

## Per-Step Timeouts

Each step races against its own timeout via Promise.race. If a Convex mutation hangs due to a slow network, the timeout fires and the orchestrator skips to the rollback phase.

***

## Rollback Behavior

Steps are rolled back in reverse order. If Step 2 fails, Step 1's compensating function runs. If a compensating function itself fails, the rollbackFailed flag is set, signaling HydrationSync to perform a full reconciliation on the next cycle.

***

## Saga Tracking

Each orchestrator instance generates a unique saga ID for log correlation:

```
[Saga:X7K2M1] Initiating 3-stage sequence...
[Saga:X7K2M1] Phase: Convex Mutation (timeout: 15000ms)
[Saga:X7K2M1] Phase: Local SQLite Write (timeout: 15000ms)
[Saga:X7K2M1] SUCCESS: All layers committed.
```