@crewhaus/tool-flow 0.7.0

package/dist/lib/errors.js

@@ -0,0 +1,436 @@
+/**
+ * Map an error to a stable class and a next action.
+ *
+ * Deciding "is this worth retrying?" is the single most common reason a
+ * harness spends a model turn on something that has a right answer. A 429
+ * with `Retry-After: 30` is not a judgement call, and neither is exit code
+ * 127. This turns the signals a failure actually carries — status, exit
+ * code, errno, the text — into one of a fixed set of classes and one of a
+ * fixed set of actions, so a loop can act on it directly.
+ *
+ * Nothing here reads the clock. `Retry-After` in its HTTP-date form is a
+ * point in time, and turning that into a wait needs a "now"; the caller
+ * supplies one or gets the date back unconverted. A classifier that quietly
+ * called `Date.now()` would return a different answer every second, which is
+ * exactly what this package promises not to do.
+ */
+export const ERROR_CLASSES = [
+    "ok",
+    "transient",
+    "timeout",
+    "unavailable",
+    "rate_limited",
+    "quota",
+    "auth",
+    "permission",
+    "not_found",
+    "bad_request",
+    "conflict",
+    "too_large",
+    "unsupported",
+    "capacity",
+    "integrity",
+    "cancelled",
+    "redirect",
+    "bug",
+    "unknown",
+];
+export const NEXT_ACTIONS = [
+    "continue",
+    "retry",
+    "retry_after",
+    "backoff",
+    "reauth",
+    "reduce_input",
+    "escalate",
+    "skip",
+    "fail",
+];
+/**
+ * Classes whose default action is "try again" rather than "change something".
+ *
+ * This decides whether a `Retry-After` is allowed to upgrade a plain retry —
+ * it is not the same question as {@link Classification.retryable}, which
+ * follows the final action. A capacity failure is in here because some of
+ * them (EMFILE, EAGAIN) do clear on their own, but an OOM kill under the
+ * same class resolves to `escalate`, and then it is not retryable.
+ */
+const RETRY_BY_DEFAULT = new Set([
+    "transient",
+    "timeout",
+    "unavailable",
+    "rate_limited",
+    "capacity",
+]);
+/** The actions that mean "call it again". */
+const RETRY_ACTIONS = new Set(["retry", "retry_after", "backoff"]);
+const STATUS_TABLE = new Map([
+    [400, { class: "bad_request", action: "fail" }],
+    [401, { class: "auth", action: "reauth" }],
+    [402, { class: "quota", action: "escalate" }],
+    [403, { class: "permission", action: "escalate" }],
+    [404, { class: "not_found", action: "fail" }],
+    [405, { class: "bad_request", action: "fail" }],
+    [406, { class: "bad_request", action: "fail" }],
+    [408, { class: "timeout", action: "retry" }],
+    [409, { class: "conflict", action: "escalate" }],
+    [410, { class: "not_found", action: "fail" }],
+    [412, { class: "conflict", action: "escalate" }],
+    [413, { class: "too_large", action: "reduce_input" }],
+    [414, { class: "too_large", action: "reduce_input" }],
+    [415, { class: "unsupported", action: "fail" }],
+    [422, { class: "bad_request", action: "fail" }],
+    [423, { class: "conflict", action: "backoff" }],
+    [425, { class: "transient", action: "retry" }],
+    [428, { class: "bad_request", action: "fail" }],
+    [429, { class: "rate_limited", action: "retry_after" }],
+    [431, { class: "too_large", action: "reduce_input" }],
+    [451, { class: "permission", action: "fail" }],
+    [500, { class: "transient", action: "retry" }],
+    [501, { class: "unsupported", action: "fail" }],
+    [502, { class: "unavailable", action: "retry" }],
+    [503, { class: "unavailable", action: "retry_after" }],
+    [504, { class: "timeout", action: "retry" }],
+    [507, { class: "capacity", action: "escalate" }],
+    [508, { class: "bug", action: "fail" }],
+    [509, { class: "quota", action: "escalate" }],
+    // Anthropic and several other providers use 529 for "overloaded".
+    [529, { class: "unavailable", action: "backoff" }],
+]);
+/**
+ * Exit codes with an agreed meaning. 1 is deliberately absent: it is the
+ * generic "it failed" and says nothing about why, so claiming a class for it
+ * would be inventing information.
+ */
+const EXIT_TABLE = new Map([
+    [0, { class: "ok", action: "continue" }],
+    [2, { class: "bad_request", action: "fail" }],
+    // GNU coreutils `timeout` exits 124 when it had to kill the child.
+    [124, { class: "timeout", action: "retry" }],
+    [125, { class: "bug", action: "fail" }],
+    [126, { class: "permission", action: "fail" }],
+    [127, { class: "not_found", action: "fail" }],
+]);
+/** 128+N, the shell's encoding of "died on signal N". */
+const SIGNAL_TABLE = new Map([
+    ["SIGINT", { class: "cancelled", action: "fail" }],
+    ["SIGTERM", { class: "cancelled", action: "fail" }],
+    ["SIGQUIT", { class: "cancelled", action: "fail" }],
+    // A killed process is usually the OOM killer, which is a capacity problem.
+    ["SIGKILL", { class: "capacity", action: "escalate" }],
+    ["SIGSEGV", { class: "bug", action: "fail" }],
+    ["SIGABRT", { class: "bug", action: "fail" }],
+    ["SIGBUS", { class: "bug", action: "fail" }],
+    ["SIGFPE", { class: "bug", action: "fail" }],
+    ["SIGPIPE", { class: "transient", action: "retry" }],
+    ["SIGALRM", { class: "timeout", action: "retry" }],
+    ["SIGHUP", { class: "transient", action: "retry" }],
+    ["SIGXFSZ", { class: "too_large", action: "reduce_input" }],
+]);
+const EXIT_SIGNALS = new Map([
+    [129, "SIGHUP"],
+    [130, "SIGINT"],
+    [131, "SIGQUIT"],
+    [134, "SIGABRT"],
+    [136, "SIGFPE"],
+    [137, "SIGKILL"],
+    [138, "SIGBUS"],
+    [139, "SIGSEGV"],
+    [141, "SIGPIPE"],
+    [142, "SIGALRM"],
+    [143, "SIGTERM"],
+    [153, "SIGXFSZ"],
+]);
+const CODE_TABLE = new Map([
+    ["ECONNREFUSED", { class: "unavailable", action: "retry" }],
+    ["ECONNRESET", { class: "transient", action: "retry" }],
+    ["ECONNABORTED", { class: "transient", action: "retry" }],
+    ["ETIMEDOUT", { class: "timeout", action: "retry" }],
+    ["ESOCKETTIMEDOUT", { class: "timeout", action: "retry" }],
+    ["EPIPE", { class: "transient", action: "retry" }],
+    ["EHOSTUNREACH", { class: "unavailable", action: "retry" }],
+    ["ENETUNREACH", { class: "unavailable", action: "retry" }],
+    ["ENETDOWN", { class: "unavailable", action: "retry" }],
+    // EAI_AGAIN is a temporary resolver failure; ENOTFOUND is a real NXDOMAIN.
+    ["EAI_AGAIN", { class: "transient", action: "retry" }],
+    ["ENOTFOUND", { class: "not_found", action: "fail" }],
+    ["ENOENT", { class: "not_found", action: "fail" }],
+    ["EEXIST", { class: "conflict", action: "escalate" }],
+    ["EACCES", { class: "permission", action: "escalate" }],
+    ["EPERM", { class: "permission", action: "escalate" }],
+    ["EROFS", { class: "permission", action: "escalate" }],
+    ["ENOSPC", { class: "capacity", action: "escalate" }],
+    ["EDQUOT", { class: "quota", action: "escalate" }],
+    ["EMFILE", { class: "capacity", action: "backoff" }],
+    ["ENFILE", { class: "capacity", action: "backoff" }],
+    ["ENOMEM", { class: "capacity", action: "escalate" }],
+    ["EAGAIN", { class: "transient", action: "backoff" }],
+    ["EBUSY", { class: "conflict", action: "backoff" }],
+    ["EISDIR", { class: "bad_request", action: "fail" }],
+    ["ENOTDIR", { class: "bad_request", action: "fail" }],
+    ["ENOTEMPTY", { class: "conflict", action: "escalate" }],
+    ["EMSGSIZE", { class: "too_large", action: "reduce_input" }],
+    ["ELOOP", { class: "bad_request", action: "fail" }],
+    ["ENAMETOOLONG", { class: "bad_request", action: "fail" }],
+    ["CERT_HAS_EXPIRED", { class: "integrity", action: "fail" }],
+    ["DEPTH_ZERO_SELF_SIGNED_CERT", { class: "integrity", action: "fail" }],
+    ["SELF_SIGNED_CERT_IN_CHAIN", { class: "integrity", action: "fail" }],
+    ["UNABLE_TO_VERIFY_LEAF_SIGNATURE", { class: "integrity", action: "fail" }],
+    ["ERR_TLS_CERT_ALTNAME_INVALID", { class: "integrity", action: "fail" }],
+    ["insufficient_quota", { class: "quota", action: "escalate" }],
+    ["rate_limit_exceeded", { class: "rate_limited", action: "retry_after" }],
+    ["context_length_exceeded", { class: "too_large", action: "reduce_input" }],
+    ["overloaded_error", { class: "unavailable", action: "backoff" }],
+    ["invalid_api_key", { class: "auth", action: "reauth" }],
+    ["authentication_error", { class: "auth", action: "reauth" }],
+    ["permission_error", { class: "permission", action: "escalate" }],
+    ["not_found_error", { class: "not_found", action: "fail" }],
+    ["invalid_request_error", { class: "bad_request", action: "fail" }],
+    ["api_error", { class: "transient", action: "retry" }],
+]);
+/**
+ * Message signatures, tried in order. Plain lowercased substrings, not
+ * regular expressions: these run on attacker-influenced text (a remote
+ * server's error body), and a pattern with nested quantifiers there is a
+ * denial of service waiting to happen. Order matters — the more specific
+ * phrase has to come first.
+ */
+const MESSAGE_TABLE = [
+    ["too many requests", { class: "rate_limited", action: "retry_after" }],
+    ["rate limit", { class: "rate_limited", action: "retry_after" }],
+    ["rate_limit", { class: "rate_limited", action: "retry_after" }],
+    ["credit balance is too low", { class: "quota", action: "escalate" }],
+    ["insufficient funds", { class: "quota", action: "escalate" }],
+    ["insufficient_quota", { class: "quota", action: "escalate" }],
+    ["billing", { class: "quota", action: "escalate" }],
+    ["quota", { class: "quota", action: "escalate" }],
+    ["maximum context length", { class: "too_large", action: "reduce_input" }],
+    ["context length", { class: "too_large", action: "reduce_input" }],
+    ["context window", { class: "too_large", action: "reduce_input" }],
+    ["too many tokens", { class: "too_large", action: "reduce_input" }],
+    ["request entity too large", { class: "too_large", action: "reduce_input" }],
+    ["payload too large", { class: "too_large", action: "reduce_input" }],
+    ["javascript heap out of memory", { class: "capacity", action: "escalate" }],
+    ["out of memory", { class: "capacity", action: "escalate" }],
+    ["no space left on device", { class: "capacity", action: "escalate" }],
+    ["cannot allocate memory", { class: "capacity", action: "escalate" }],
+    ["invalid api key", { class: "auth", action: "reauth" }],
+    ["incorrect api key", { class: "auth", action: "reauth" }],
+    ["api key not valid", { class: "auth", action: "reauth" }],
+    ["unauthorized", { class: "auth", action: "reauth" }],
+    ["authentication failed", { class: "auth", action: "reauth" }],
+    ["token expired", { class: "auth", action: "reauth" }],
+    ["permission denied", { class: "permission", action: "escalate" }],
+    ["access denied", { class: "permission", action: "escalate" }],
+    ["forbidden", { class: "permission", action: "escalate" }],
+    ["certificate", { class: "integrity", action: "fail" }],
+    ["checksum mismatch", { class: "integrity", action: "fail" }],
+    ["signature verification failed", { class: "integrity", action: "fail" }],
+    ["connection refused", { class: "unavailable", action: "retry" }],
+    ["connection reset", { class: "transient", action: "retry" }],
+    ["socket hang up", { class: "transient", action: "retry" }],
+    ["temporarily unavailable", { class: "unavailable", action: "retry" }],
+    ["service unavailable", { class: "unavailable", action: "retry" }],
+    ["server is overloaded", { class: "unavailable", action: "backoff" }],
+    ["overloaded", { class: "unavailable", action: "backoff" }],
+    ["timed out", { class: "timeout", action: "retry" }],
+    ["timeout", { class: "timeout", action: "retry" }],
+    ["deadline exceeded", { class: "timeout", action: "retry" }],
+    ["already exists", { class: "conflict", action: "escalate" }],
+    ["conflict", { class: "conflict", action: "escalate" }],
+    ["not found", { class: "not_found", action: "fail" }],
+    ["no such file or directory", { class: "not_found", action: "fail" }],
+    ["command not found", { class: "not_found", action: "fail" }],
+    ["cancell", { class: "cancelled", action: "fail" }],
+    ["aborted", { class: "cancelled", action: "fail" }],
+];
+/** Guards the substring scan against a multi-megabyte error body. */
+const MAX_MESSAGE_CHARS = 64_000;
+/**
+ * Parse `Retry-After`. Two forms are legal: delta-seconds, and an HTTP-date.
+ * The date form needs a reference point to become a duration, so without
+ * `nowMs` it is returned as a date and `waitMs` stays null.
+ */
+export function parseRetryAfter(raw, nowMs) {
+    const text = raw.trim();
+    if (text === "")
+        return { waitMs: null, retryAt: null };
+    if (/^\d+$/.test(text)) {
+        const seconds = Number.parseInt(text, 10);
+        return { waitMs: seconds * 1000, retryAt: null };
+    }
+    const parsed = Date.parse(text);
+    if (Number.isNaN(parsed))
+        return { waitMs: null, retryAt: null };
+    const retryAt = new Date(parsed).toISOString();
+    if (nowMs === undefined)
+        return { waitMs: null, retryAt };
+    // A date already in the past means "retry now", not "wait a negative time".
+    return { waitMs: Math.max(0, parsed - nowMs), retryAt };
+}
+/**
+ * Match a caller rule.
+ *
+ * `message` and `code` are tested SEPARATELY rather than concatenated. Two
+ * reasons, and the second is the important one:
+ *
+ * - A pattern anchored with `$` means "the end of the message", and against
+ *   a joined `"<message> <code>"` it could never match.
+ * - Because it could never match, the engine has to exhaust every
+ *   alternative before saying so — which turns a pattern that would have
+ *   matched immediately into a backtracking search over attacker-supplied
+ *   text. Joining the fields manufactured the worst case for free.
+ */
+function matchCustom(signal, rules, fields) {
+    for (const rule of rules) {
+        if (rule.status !== undefined && rule.status !== signal.status)
+            continue;
+        if (rule.exitCode !== undefined && rule.exitCode !== signal.exitCode)
+            continue;
+        if (rule.contains !== undefined) {
+            const needle = rule.contains.toLowerCase();
+            if (!fields.some((f) => f.includes(needle)))
+                continue;
+        }
+        if (rule.matches !== undefined) {
+            let re;
+            try {
+                re = new RegExp(rule.matches, "i");
+            }
+            catch (err) {
+                throw new Error(`rule "${rule.id}" has an invalid pattern: ${err.message}`);
+            }
+            if (!fields.some((f) => re.test(f)))
+                continue;
+        }
+        // A rule with no conditions at all would match everything silently.
+        const hasCondition = rule.status !== undefined ||
+            rule.exitCode !== undefined ||
+            rule.contains !== undefined ||
+            rule.matches !== undefined;
+        if (!hasCondition)
+            throw new Error(`rule "${rule.id}" has no conditions, so it matches every error`);
+        return rule;
+    }
+    return null;
+}
+export function classifyError(signal, options = {}) {
+    const message = (signal.message ?? "").slice(0, MAX_MESSAGE_CHARS);
+    const fields = [message.toLowerCase(), (signal.code ?? "").toLowerCase()];
+    const retry = signal.retryAfter === undefined
+        ? { waitMs: null, retryAt: null }
+        : parseRetryAfter(signal.retryAfter, options.nowMs);
+    let verdict = null;
+    let matched = "default";
+    let source = "default";
+    const custom = matchCustom(signal, options.rules ?? [], fields);
+    if (custom) {
+        verdict = { class: custom.class, action: custom.action, waitMs: custom.waitMs };
+        matched = custom.id;
+        source = "custom";
+    }
+    if (!verdict && signal.status !== undefined) {
+        const found = STATUS_TABLE.get(signal.status);
+        if (found) {
+            verdict = found;
+            matched = `status:${signal.status}`;
+            source = "status";
+        }
+        else if (signal.status >= 200 && signal.status < 300) {
+            verdict = { class: "ok", action: "continue" };
+            matched = "status:2xx";
+            source = "status";
+        }
+        else if (signal.status >= 300 && signal.status < 400) {
+            verdict = { class: "redirect", action: "fail" };
+            matched = "status:3xx";
+            source = "status";
+        }
+        else if (signal.status >= 500) {
+            verdict = { class: "transient", action: "retry" };
+            matched = "status:5xx";
+            source = "status";
+        }
+        else if (signal.status >= 400) {
+            verdict = { class: "bad_request", action: "fail" };
+            matched = "status:4xx";
+            source = "status";
+        }
+    }
+    if (!verdict && signal.signal !== undefined) {
+        const found = SIGNAL_TABLE.get(signal.signal.toUpperCase());
+        if (found) {
+            verdict = found;
+            matched = `signal:${signal.signal.toUpperCase()}`;
+            source = "signal";
+        }
+    }
+    if (!verdict && signal.exitCode !== undefined) {
+        const direct = EXIT_TABLE.get(signal.exitCode);
+        if (direct) {
+            verdict = direct;
+            matched = `exit:${signal.exitCode}`;
+            source = "exit";
+        }
+        else {
+            const named = EXIT_SIGNALS.get(signal.exitCode);
+            const found = named ? SIGNAL_TABLE.get(named) : undefined;
+            if (named && found) {
+                verdict = found;
+                matched = `exit:${signal.exitCode} (${named})`;
+                source = "signal";
+            }
+        }
+    }
+    if (!verdict && signal.code !== undefined) {
+        const found = CODE_TABLE.get(signal.code) ?? CODE_TABLE.get(signal.code.toUpperCase());
+        if (found) {
+            verdict = found;
+            matched = `code:${signal.code}`;
+            source = "code";
+        }
+    }
+    if (!verdict && message !== "") {
+        const lower = message.toLowerCase();
+        for (const [needle, found] of MESSAGE_TABLE) {
+            if (lower.includes(needle)) {
+                verdict = found;
+                matched = `message:${needle}`;
+                source = "message";
+                break;
+            }
+        }
+    }
+    if (!verdict)
+        verdict = { class: "unknown", action: "escalate" };
+    // A server that told us when to come back outranks a generic "retry".
+    let action = verdict.action;
+    const waitMs = verdict.waitMs ?? retry.waitMs;
+    if (RETRY_BY_DEFAULT.has(verdict.class) && retry.waitMs !== null && action === "retry") {
+        action = "retry_after";
+    }
+    if (action === "retry_after" && waitMs === null && retry.retryAt === null)
+        action = "backoff";
+    // Attempts run out regardless of how retryable the class is. Without this
+    // a loop reading `action` alone retries a 503 forever.
+    const exhausted = signal.attempt !== undefined &&
+        signal.maxAttempts !== undefined &&
+        signal.attempt >= signal.maxAttempts;
+    if (exhausted && RETRY_ACTIONS.has(action))
+        action = "escalate";
+    // `retryable` follows the action, not the class. Deriving it from the class
+    // instead would report an OOM kill — class `capacity`, action `escalate` —
+    // as retryable, and a caller that reads the boolean rather than the action
+    // would re-run the identical command and be killed identically.
+    const retryable = RETRY_ACTIONS.has(action);
+    return {
+        class: verdict.class,
+        action,
+        retryable,
+        waitMs: waitMs ?? null,
+        retryAt: retry.retryAt,
+        matched,
+        source,
+        exhausted,
+    };
+}

package/dist/lib/score.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Additive rule scoring with an attributable breakdown.
+ *
+ * Any "score this thing and decide which band it lands in" job — lead
+ * qualification, risk, triage priority — is a table lookup plus addition.
+ * The reason to do it here rather than in a model is not only cost: a score
+ * a model produced cannot be explained to the person it affects, and cannot
+ * be re-run identically next quarter. This returns the contributors, and the
+ * version of the rules that produced them.
+ */
+import { type Check } from "@crewhaus/tool-schema";
+export type ScoreRule = {
+    readonly id: string;
+    /** All of these must hold for the points to be awarded. */
+    readonly when: ReadonlyArray<Check>;
+    readonly points: number;
+    /** Human-readable reason, for the note that goes on the record. */
+    readonly label?: string;
+};
+export type ScoreBand = {
+    readonly name: string;
+    /** Inclusive lower bound. The highest band whose min is met wins. */
+    readonly min: number;
+};
+export type ScoreModel = {
+    readonly version?: string;
+    readonly rules: ReadonlyArray<ScoreRule>;
+    readonly bands?: ReadonlyArray<ScoreBand>;
+    /** Clamp the total into this range after summing. */
+    readonly min?: number;
+    readonly max?: number;
+};
+export type ScoreResult = {
+    readonly score: number;
+    /** The sum before clamping, which differs from `score` when it was clamped. */
+    readonly rawScore: number;
+    readonly band: string | null;
+    readonly version: string | null;
+    readonly contributors: ReadonlyArray<{
+        readonly id: string;
+        readonly label: string;
+        readonly points: number;
+    }>;
+    /** Rules that did not fire, with the first reason they did not. */
+    readonly missed: ReadonlyArray<{
+        readonly id: string;
+        readonly reason: string;
+    }>;
+};
+export declare function scoreValue(value: unknown, model: ScoreModel): ScoreResult;

package/dist/lib/score.js

@@ -0,0 +1,56 @@
+/**
+ * Additive rule scoring with an attributable breakdown.
+ *
+ * Any "score this thing and decide which band it lands in" job — lead
+ * qualification, risk, triage priority — is a table lookup plus addition.
+ * The reason to do it here rather than in a model is not only cost: a score
+ * a model produced cannot be explained to the person it affects, and cannot
+ * be re-run identically next quarter. This returns the contributors, and the
+ * version of the rules that produced them.
+ */
+import { runChecks } from "@crewhaus/tool-schema";
+export function scoreValue(value, model) {
+    if (model.rules.length === 0)
+        throw new Error("the scoring model has no rules");
+    const seen = new Set();
+    for (const rule of model.rules) {
+        if (rule.when.length === 0) {
+            throw new Error(`rule "${rule.id}" has no checks, so it would always award its points`);
+        }
+        if (seen.has(rule.id))
+            throw new Error(`two rules share the id "${rule.id}"`);
+        seen.add(rule.id);
+        if (!Number.isFinite(rule.points)) {
+            throw new Error(`rule "${rule.id}" has non-finite points`);
+        }
+    }
+    if (model.min !== undefined && model.max !== undefined && model.min > model.max) {
+        throw new Error(`min (${model.min}) is above max (${model.max})`);
+    }
+    const contributors = [];
+    const missed = [];
+    let rawScore = 0;
+    for (const rule of model.rules) {
+        const report = runChecks(value, rule.when);
+        if (report.ok) {
+            rawScore += rule.points;
+            contributors.push({ id: rule.id, label: rule.label ?? rule.id, points: rule.points });
+        }
+        else {
+            missed.push({ id: rule.id, reason: report.failures[0]?.reason ?? "" });
+        }
+    }
+    let score = rawScore;
+    if (model.min !== undefined)
+        score = Math.max(model.min, score);
+    if (model.max !== undefined)
+        score = Math.min(model.max, score);
+    let band = null;
+    if (model.bands && model.bands.length > 0) {
+        // Highest qualifying band wins, whatever order they were declared in, so
+        // a table written low-to-high and one written high-to-low agree.
+        const sorted = [...model.bands].sort((a, b) => b.min - a.min);
+        band = sorted.find((b) => score >= b.min)?.name ?? null;
+    }
+    return { score, rawScore, band, version: model.version ?? null, contributors, missed };
+}

package/dist/lib/sequence.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Plan a declared sequence of steps. Nothing here runs one.
+ *
+ * A sequence is the other half of {@link ./branch}: a branch answers "which
+ * way", a sequence answers "what next, and what is it still waiting on". The
+ * answer is a plan — the steps whose prerequisites are met, whose gate time
+ * has passed and whose conditions hold, each carrying the parameters the
+ * caller should execute it with.
+ *
+ * It stops there on purpose. Invoking a tool needs the executor, which no
+ * tool package has, and a "runner" that quietly returned the steps it would
+ * have run is the shape of lie a caller only discovers in production. So
+ * this returns the plan and the caller — or the harness, which does have the
+ * executor — acts on it.
+ *
+ * Progress is an argument, not a memory. `completed` and `failed` come in
+ * the way {@link ./stall} takes its history, so the same inputs give the
+ * same plan in a test, in a replay and in production.
+ *
+ * Three distinctions carry the weight here, and each one is a different
+ * answer a caller has to be able to tell apart:
+ *
+ * - **waiting** — a prerequisite has not run yet, or the step is not due
+ *   yet. It can still happen.
+ * - **unreachable** — a prerequisite failed or was skipped, so this step can
+ *   never happen. Reporting that as "waiting" is how a flow hangs forever on
+ *   a step that died three turns ago.
+ * - **skipped** — the step's own conditions did not hold. A settled no.
+ */
+import { type Check } from "@crewhaus/tool-schema";
+import type { MatchMode } from "./branch";
+/**
+ * Where a flow stands.
+ *
+ * `finished` and `halted` are kept apart on purpose. Both mean there is
+ * nothing left to run, and a caller that reads one boolean for both reports
+ * a cadence that died on its second step as a cadence that completed.
+ */
+export declare const PLAN_STATES: readonly ["ready", "blocked", "finished", "halted"];
+export type PlanState = (typeof PLAN_STATES)[number];
+export type SequenceStep = {
+    readonly id: string;
+    /**
+     * The step's own gate. Optional, unlike a branch arm's: arms are
+     * alternatives, so a condition-less arm swallows the ones after it, while
+     * sequence steps are not alternatives and an unconditional step is the
+     * ordinary case. An explicitly empty list is still rejected, because it
+     * says "gated" and means nothing.
+     */
+    readonly when?: ReadonlyArray<Check>;
+    readonly match?: MatchMode;
+    /** Ids that must be completed first. */
+    readonly needs?: ReadonlyArray<string>;
+    /** Handed back verbatim in the plan. Any JSON value. */
+    readonly params?: unknown;
+    /** Not due before this instant, as epoch ms. */
+    readonly afterMs?: number;
+};
+export type SequenceSpec = {
+    /** Echoed into the plan, so a change of flow is attributable. */
+    readonly version?: string;
+    readonly steps: ReadonlyArray<SequenceStep>;
+};
+export type SequenceState = {
+    readonly nowMs: number;
+    readonly completed?: ReadonlyArray<string>;
+    readonly failed?: ReadonlyArray<string>;
+};
+/** A step the caller should execute now. */
+export type PlannedStep = {
+    readonly id: string;
+    /** Position in the declared steps. */
+    readonly index: number;
+    readonly params?: unknown;
+};
+/** A step that is not in the plan, and why. */
+export type HeldStep = {
+    readonly id: string;
+    readonly reason: string;
+    /** Only on a step held by its `after` gate: how long until it is due. */
+    readonly dueInMs?: number;
+};
+export type SequencePlan = {
+    /** Where the flow stands, as a label a branch can switch on. */
+    readonly state: PlanState;
+    /** The plan, in declared order. Executing these is the caller's job. */
+    readonly ready: ReadonlyArray<PlannedStep>;
+    /** `ready[0]`, for the caller that only wants the next one. */
+    readonly next: PlannedStep | null;
+    readonly waiting: ReadonlyArray<HeldStep>;
+    readonly unreachable: ReadonlyArray<HeldStep>;
+    readonly skipped: ReadonlyArray<HeldStep>;
+    readonly completed: ReadonlyArray<string>;
+    readonly failed: ReadonlyArray<string>;
+    readonly version: string | null;
+    readonly total: number;
+};
+/**
+ * Work out what to run next.
+ *
+ * Structural problems throw rather than being reported, the way a duplicate
+ * row id does elsewhere in this package: a cycle, a `needs` naming a step
+ * that does not exist, or progress naming a step that does not exist are all
+ * bugs in the spec or in the caller's bookkeeping, not answers about this
+ * particular record. In particular an unknown id in `completed` — a typo, or
+ * a leftover from an older revision of the flow — would silently re-run a
+ * step the caller believes is finished.
+ */
+export declare function planSequence(value: unknown, spec: SequenceSpec, state: SequenceState): SequencePlan;