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

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), 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 (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:

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 (lines 2261-2266) injects this callback as the beforeRunProviderDispatch hook. This executes immediately before any provider dispatch:

...(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 (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 (lines 70-81), the bindStateRootComposition function persists the .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:

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:

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 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 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}