How it works

The picture

Tasks and providers never import each other. A task plugin owns a contract, a provider plugin registers a handler for it, and the runner only sees the handler.

One item, step by step

Two keys

Each $file enters both keys as its content hash. So one changed keyframe rebuilds that keyframe and every shot that references it. The other items are reused.

The id is not part of either key. It is the file name of the export and the target of a $ref.

Which provider runs

An item picks its provider in this order:

1. provider on the item.
2. defaults.provider in the build file.
3. The first provider registered for the task.

The budget gate

The gate runs right before each provider call, in one transaction:

done actual cost + dispatching estimates + this item's estimate <= maxCostUsd

When the check fails, the run stops admitting, lets in-flight items finish and settles budget-stopped. The guarantee is that spend stays within the done items plus the items that were dispatching at a kill. estimate uses the same math, and moku estimate shows it.

Failures

Backoff is exponential in the attempt number, from runner.retryBaseMs, jittered to 50-100%. runner.maxAttempts caps the attempts. A build file can set defaults.maxAttempts.

limits counts retryable failures per lane. After breakerThreshold in a row the lane's breaker opens for breakerCooldownMs, and items wait.

Crashes, pauses and long jobs

The journal runs SQLite in WAL mode with synchronous=FULL. Every state change is a committed write, so a kill -9 loses only work in flight.

What is stored where

This split is the redaction boundary. A prompt cannot reach the journal, because the runner only passes it statuses, costs and hashes. A generated text output, like a translate result, is an artifact in the store.

Durable path or one-off call

import { app } from "./app";

await app.start();

// One-off: direct, not journaled.
const speech = await app.voiceover.generate({ text: "Hi!", voice: "21m00Tcm4TlvDq8ikWAM" });
console.log(speech.costUsd);

// Durable: journaled, budget-gated, resumable.
const result = await app.runner.run({ files: "**/*.moku.yaml", maxCostUsd: 25 });
if (result.status === "paused") await app.runner.resume({ runId: result.runId });

await app.stop();

The plugin order

createApp composes five core plugins and the regular plugins. Core plugins are on every plugin's ctx: log, env, journal, store, limits. Regular plugins mount at app.<name>. Providers register their handlers in onInit, so app.registry is full as soon as createApp returns, and the order of registration decides the third step of Which provider runs.