# What Happens If Run Composition or Persistence Fails Before Provider Call in Apache Maka

> Discover what happens when Run Composition or persistence fails in Apache Maka. Learn how Maka aborts turns to ensure data consistency and billing integrity.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-08-30

---

**If Run Composition or its persistence fails in Apache Maka, the runtime aborts the turn before any provider request is dispatched, surfacing specific errors like `StateRootCompositionError` or AgentRun immutability violations to preserve data consistency and billing integrity.**

Apache Maka snapshots the **Run Composition** immediately before dispatching the first provider request of a turn. This critical checkpoint, implemented in the runtime-host's execution model composition layer ([`packages/runtime-host/src/server/execution-model-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-model-composition.ts)), ensures that execution state is reliably recorded before any external API calls are made. Understanding what happens if Run Composition or persistence fails before provider call in Apache Maka is essential for debugging session initialization errors and ensuring robust error handling in production environments.

## How Run Composition Persistence Works in Apache Maka

### The Execution Model Composition Layer

In [`packages/runtime-host/src/server/execution-model-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-model-composition.ts) (lines 20-38), the runtime constructs a `commitRunComposition` callback that captures the execution state snapshot. This function resolves the run prompt and persists the composition via the `recordRunComposition` callback supplied by the runtime kernel:

```typescript
const commitRunComposition = recordRunComposition
  ? async (ctx: { readonly turnId: string; readonly runId: string }) => {
      const resolved = await resolveRunPrompt(ctx);
      await recordRunComposition(
        ctx.runId,
        createRunCompositionSnapshot({ /* … */ })
      );
    }
  : undefined;

```

### Kernel Integration via beforeRunProviderDispatch

The runtime kernel in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) (lines 2261-2266) injects this callback as the `beforeRunProviderDispatch` hook. This executes immediately before any provider dispatch:

```typescript
...(commitRunComposition
  ? { beforeRunProviderDispatch: commitRunComposition }
  : {}),

```

## Failure Scenarios and Error Handling

When persistence fails, Apache Maka aborts the turn immediately. The system handles several distinct failure modes across different layers of the stack.

### recordRunComposition Rejection

If the `recordRunComposition` callback rejects—due to store unavailability, duplicate composition entries, or I/O errors—the kernel awaits this promise before provider dispatch. According to the source in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts) (lines 19-27), when `AgentRun.recordRunComposition` returns a rejected promise, the error bubbles up and **skips the provider dispatch entirely**, aborting the turn with messages like "No active AgentRun for Run Composition".

### State-Root Composition I/O Failures

In [`packages/storage/src/state-root-composition.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/state-root-composition.ts) (lines 70-81), the `bindStateRootComposition` function persists the [`.maka-host-composition.json`](https://github.com/apache/maka/blob/main/.maka-host-composition.json) file via `withCompositionIoFailure`. If the low-level write throws a non-ENOENT error, the system wraps it in a `StateRootCompositionError` with code `composition_io_failed`. This binding failure halts session initialization before any provider calls occur.

### Immutable Composition Violations

The `AgentRun.recordRunComposition` method enforces immutability checks. If the code detects that `runComposition` is already set and not deeply equal to the new snapshot, it throws "AgentRun Run Composition changed after resolution". This prevents state corruption by aborting the turn before external requests are issued.

### Composition Mismatches

When `assertMatchingComposition` fails during State-Root validation, the system throws a `StateRootCompositionError` with code `composition_mismatch`. This validation failure prevents session startup, ensuring no provider requests are dispatched when the execution state cannot be reliably matched.

## Practical Code Examples

These examples demonstrate how to handle and simulate Run Composition failures in Apache Maka applications.

### Handling Turn Execution Failures

When executing a turn, wrap the kernel call to catch composition persistence errors before they reach the provider:

```typescript
await kernel.executeTurn({
  sessionId,
  header,
  // …other context…
}).catch((err) => {
  console.error('Turn aborted:', err.message);
  // err.message will be one of:
  // 'No active AgentRun for Run Composition'
  // 'StateRootCompositionError: composition_io_failed'
  // 'AgentRun Run Composition changed after resolution'
});

```

### Simulating Store Unavailability

To test failure paths, simulate a broken run store that throws on update:

```typescript
const brokenStore = { 
  /* …runStore that throws on updateRun… */ 
};
const run = new AgentRun({ runStore: brokenStore, /* … */ });
run.recordRunComposition(someSnapshot).catch((e) => {
  // e.message === 'AgentRun Run Composition cannot be cleared' or similar
  // Provider dispatch never occurs
});

```

## Summary

- Apache Maka records Run Composition snapshots in [`execution-model-composition.ts`](https://github.com/apache/maka/blob/main/execution-model-composition.ts) immediately before provider dispatch via the `beforeRunProviderDispatch` hook.
- If `recordRunComposition` rejects, the kernel aborts the turn and skips provider dispatch entirely.
- State-Root I/O failures throw `StateRootCompositionError` with code `composition_io_failed`, halting session initialization.
- Immutability violations trigger "AgentRun Run Composition changed after resolution" errors to prevent state corruption.
- All failure paths surface errors to the caller before any external provider is contacted, protecting data consistency and billing integrity.

## Frequently Asked Questions

### What error occurs if the Run Composition store is unavailable?

If the run store is unavailable, `AgentRun.recordRunComposition` returns a rejected promise, causing the kernel to abort the turn before provider dispatch. The error message typically reads "No active AgentRun for Run Composition" or similar storage-related failures, ensuring no external API calls are made during infrastructure outages.

### Can a provider call proceed if State-Root composition persistence fails?

No. If `bindStateRootComposition` fails to write the [`.maka-host-composition.json`](https://github.com/apache/maka/blob/main/.maka-host-composition.json) file, it throws a `StateRootCompositionError` with code `composition_io_failed`. This halts session initialization immediately, preventing any provider requests from being dispatched.

### How does Apache Maka prevent Run Composition tampering after resolution?

The `AgentRun.recordRunComposition` method validates that the composition hasn't changed using deep equality checks. If `runComposition` is already set and differs from the new snapshot, it throws "AgentRun Run Composition changed after resolution", aborting the turn before any provider call to maintain execution integrity.

### Where is the beforeRunProviderDispatch hook injected in the Apache Maka runtime?

The hook is injected in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) (lines 2261-2266) when `commitRunComposition` is present. The kernel passes it as an option to the backend, ensuring it executes immediately before any provider dispatch during turn execution.