cursedbelt-core 1.0.0

package/dist/core/analytics/schedule.d.ts

@@ -0,0 +1,301 @@
+/**
+ * "How long until this queue is empty, and does another worker actually help?"
+ *
+ * ── The question this exists to answer (owner, 2026-08-23) ───────────────────
+ * *"For estimates of how long to empty tasks I would also like to be able to see
+ * them based on if I added to the fleet size or reduced it… I want to be able to
+ * tell whether there is a point where adding to the fleet slows down more than
+ * it speeds up. I also want to see the expected token usage so I know if I run
+ * out of tokens earlier and how much earlier."*
+ *
+ * Three separate claims hide in that, and a `remaining / rate` division answers
+ * none of them:
+ *
+ * 1. **Work does not parallelise freely.** Two tasks that write the same files
+ *    may not run together whatever the fleet size — that is the orchestrator's
+ *    own scope rule, and it is why a queue of ten tasks all scoped to one app
+ *    drains at exactly the same speed with eight workers as with one.
+ * 2. **Workers are not free of each other.** This machine's own measurements say
+ *    a verify gate takes 2m09s idle and 857s (6.6x) under seventeen concurrent
+ *    gates. Past some point another worker makes *everyone* slower, so the
+ *    makespan curve turns back UP — the "point where adding to the fleet slows
+ *    down more than it speeds up" is real, has a number, and this module finds
+ *    it. A scheduler with no contention term can never report one, because pure
+ *    list scheduling is monotone: more workers is never worse.
+ * 3. **Tokens are spent by work, not by time.** Doubling the fleet does not
+ *    double the tokens a queue costs — it spends the same budget roughly twice
+ *    as fast, so the wall-clock moment you run dry arrives sooner even though the
+ *    total is unchanged. Both numbers matter and they move in opposite
+ *    directions.
+ *
+ * ── Why it lives in cursedbelt and not in the orchestrator ───────────────────
+ * Nothing here knows what a "task" is. It schedules ITEMS with durations,
+ * exclusion keys and dependencies over WORKERS, which is the same shape as a
+ * deploy train, a batch of renders, a backup rotation or a CI matrix. The
+ * orchestrator supplies the meaning (a scope string, a serial group, a tier's
+ * measured duration) and reads the answer back; any other dashboard in the fleet
+ * can do the same without re-deriving a scheduler.
+ *
+ * Pure, deterministic, and clock-free: the caller passes `now` when it wants
+ * absolute times. That is what lets the whole forecast be asserted in a test
+ * rather than eyeballed on a chart.
+ */
+/** One unit of work to be scheduled. */
+export interface ScheduleItem {
+    id: string;
+    /** Estimated worker time at NOMINAL speed (no contention), in ms. */
+    durationMs: number;
+    /**
+     * Resources this item WRITES. Two items sharing any one of these may never run
+     * at the same time, however many workers are free. This is the orchestrator's
+     * `conflict_scopes.writes`, a deploy's target host, a render's GPU.
+     */
+    exclusive?: readonly string[];
+    /**
+     * A named mutual exclusion — at most one member of the group runs at a time.
+     * Kept separate from {@link exclusive} because it expresses "these take turns"
+     * without anyone having to say what the shared resource IS.
+     */
+    group?: string | null;
+    /** Ids that must have finished before this may start. */
+    dependsOn?: readonly string[];
+    /** What running it is expected to cost, in the caller's unit (tokens, dollars). */
+    cost?: number;
+    /** Higher goes first among items that are simultaneously eligible. Default 0. */
+    priority?: number;
+    /** Already in flight at t=0, with this much work left. Occupies a worker. */
+    runningRemainingMs?: number;
+}
+/**
+ * How much slower every worker gets as more of them run at once.
+ *
+ * The shape is deliberately the simplest one that can bend a makespan curve back
+ * upward, because a more elaborate model would imply a precision the inputs do
+ * not have. `stretch(c) = 1 + slowdownPerExtraWorker * max(0, c - freeLanes)`,
+ * clamped at `maxStretch`: below `freeLanes` the machine absorbs the load, above
+ * it every extra worker taxes all of them.
+ *
+ * 🔴 The default is NOT "no contention". A model with `slowdownPerExtraWorker: 0`
+ * always reports that more workers are better, which is the wrong answer on this
+ * machine and would make the whole panel a machine for justifying a bigger fleet.
+ * Calibrate it from measured runs where you can — {@link estimateContention} —
+ * and state on the panel that it is an estimate where you cannot.
+ */
+export interface ContentionModel {
+    /** Concurrency up to and including this runs at nominal speed. */
+    freeLanes: number;
+    /** Fractional slowdown added to EVERY worker per extra concurrent worker. */
+    slowdownPerExtraWorker: number;
+    /** Upper bound on the multiplier. Default 8 — beyond that the machine is thrashing. */
+    maxStretch?: number;
+}
+/** No contention at all — the ideal machine. Useful as a comparison line, and as
+ *  the honest choice when the work is not CPU-bound on one host. */
+export declare const NO_CONTENTION: ContentionModel;
+export declare function stretchAt(model: ContentionModel, concurrency: number): number;
+export interface SimulateOptions {
+    /** How many items may run at once. */
+    workers: number;
+    contention?: ContentionModel;
+    /** Absolute epoch ms for t=0, so the result carries real timestamps. Default 0. */
+    startAt?: number;
+    /**
+     * Guard against a pathological input (a dependency cycle, a zero-duration
+     * storm). Simulation aborts after this many scheduling events and reports what
+     * it could not place. Default 20,000.
+     */
+    maxEvents?: number;
+}
+export interface ScheduledItem {
+    id: string;
+    /** Epoch ms (or ms from t=0 when `startAt` was omitted). */
+    startAt: number;
+    endAt: number;
+    /** Nominal duration, before contention. */
+    durationMs: number;
+    /** What it actually took at the concurrency it ran under. */
+    effectiveMs: number;
+    /** How long it sat eligible-but-blocked before starting. */
+    waitedMs: number;
+    /** Why it could not start earlier: `worker` (fleet full), `conflict`, `dependency`. */
+    blockedBy: 'worker' | 'conflict' | 'dependency' | null;
+}
+export interface ScheduleResult {
+    workers: number;
+    /** Wall clock from t=0 until the last item finishes. */
+    makespanMs: number;
+    /** Sum of NOMINAL durations — the work itself, independent of fleet size. */
+    workMs: number;
+    /** Sum of EFFECTIVE durations — the work plus what contention added. */
+    spentMs: number;
+    /** Worker-time wasted to contention: `spentMs - workMs`. */
+    contentionMs: number;
+    /** `workMs / (workers * makespanMs)`, 0–1. How much of the fleet was earning. */
+    utilization: number;
+    /** Mean simultaneous items across the makespan. */
+    avgConcurrency: number;
+    peakConcurrency: number;
+    /** Total of every item's `cost`. */
+    cost: number;
+    timeline: ScheduledItem[];
+    /** Ids that could never be placed (a dependency cycle or a missing dependency). */
+    unschedulable: string[];
+}
+/**
+ * Event-driven list scheduling with resource exclusion and a contention term.
+ *
+ * The loop is: admit everything that can start, advance the clock to whichever
+ * running item finishes FIRST **at the current concurrency's speed**, retire it,
+ * repeat. Progress is tracked as remaining WORK rather than an end timestamp,
+ * which is what makes contention correct rather than decorative: a task that
+ * started alone and is joined by three others slows down for the rest of its run
+ * and not retroactively.
+ *
+ * Admission order is priority, then longest-first. Longest-first (LPT) is the
+ * classic list-scheduling heuristic and matters here: shortest-first leaves a
+ * multi-hour task to start last and stretches the makespan by most of its own
+ * length, which would make every large fleet look pointless.
+ */
+export declare function simulateSchedule(items: readonly ScheduleItem[], options: SimulateOptions): ScheduleResult;
+export interface FleetPoint {
+    workers: number;
+    makespanMs: number;
+    /** `makespan(1) / makespan(n)`. 1 = no gain; n = perfect scaling. */
+    speedup: number;
+    /** `speedup / workers`, 0–1 — how much of each worker is actually earning. */
+    efficiency: number;
+    /** Wall clock saved against ONE FEWER worker. Negative = this worker made it worse. */
+    marginalMs: number;
+    utilization: number;
+    avgConcurrency: number;
+    peakConcurrency: number;
+    /** Worker-time lost to contention at this fleet size. */
+    contentionMs: number;
+    /** Total cost of the run (unchanged by fleet size — see {@link burnPerHour}). */
+    cost: number;
+    /** Cost per hour of wall clock at this fleet size — what empties a budget. */
+    burnPerHour: number;
+    /** Items that never got scheduled. */
+    unschedulable: number;
+}
+export interface FleetSweep {
+    points: FleetPoint[];
+    /**
+     * The recommendation: the SMALLEST fleet that gets within `tolerance` of the
+     * best time this queue can achieve anywhere in the sweep.
+     *
+     * 🔴 Not "the last size with a good marginal gain", which is the obvious
+     * definition and is wrong the moment contention makes the curve non-monotone.
+     * Measured on eight 10-minute tasks at a 0.6 slowdown: seven workers take 50
+     * minutes and eight take 46, so eight shows a HEALTHY +4-minute margin over
+     * seven while being six minutes worse than simply running two. A marginal
+     * reading recommends eight. Comparing against the best achievable makespan
+     * cannot: two workers is the answer, and it says so.
+     */
+    sweetSpot: number;
+    /**
+     * The first fleet size whose makespan is WORSE than the size below it, or null
+     * when contention never wins inside the swept range. This is the literal
+     * answer to "is there a point where adding to the fleet slows it down".
+     */
+    turnsNegativeAt: number | null;
+    /**
+     * The ceiling the WORK imposes, independent of the machine: the highest
+     * concurrency the queue's own conflicts ever allow. Adding workers past this
+     * cannot help at any speed, and no contention model is needed to say so.
+     */
+    parallelismCeiling: number;
+}
+export interface SweepOptions extends Omit<SimulateOptions, 'workers'> {
+    /** Largest fleet size to try. Default 8. */
+    maxWorkers?: number;
+    /** How much slower than the best achievable makespan a fleet size may be and
+     *  still count as "as good as it gets". Default 0.05 (5%). */
+    tolerance?: number;
+}
+export declare function sweepFleetSizes(items: readonly ScheduleItem[], options?: SweepOptions): FleetSweep;
+export interface BudgetProjection {
+    workers: number;
+    /** Ms of wall clock until the budget is gone, null when the queue finishes first. */
+    exhaustedInMs: number | null;
+    /** How much of the queue's cost the budget covers, 0–1. */
+    coverage: number;
+    /** Cost the queue is short by, 0 when the budget covers it. */
+    shortfall: number;
+    burnPerHour: number;
+}
+/**
+ * When a spend budget runs out at each fleet size.
+ *
+ * The counter-intuitive half, and the reason the owner asked for it: **the total
+ * is the same and the deadline is not.** A queue that costs 40M tokens costs 40M
+ * whether one agent or five works it; five agents simply reach the wall in a
+ * fifth of the time. So `coverage` (do I have enough at all?) is flat across the
+ * sweep while `exhaustedInMs` shrinks — and the honest reading is "more workers
+ * does not cost more, it costs sooner".
+ */
+export declare function projectBudget(sweep: FleetSweep, budget: number): BudgetProjection[];
+/** One observed run: how long it took, and how loaded the machine was. */
+export interface ContentionSample {
+    /** Mean simultaneous workers while it ran. */
+    concurrency: number;
+    durationMs: number;
+}
+/**
+ * Fit a {@link ContentionModel} to runs that actually happened.
+ *
+ * Deliberately a two-group comparison rather than a regression: the sample is a
+ * few hundred runs of wildly different work, so a least-squares line through
+ * duration-versus-concurrency mostly measures which KIND of task tends to run
+ * alone. Comparing the median duration of "ran near-alone" against the median of
+ * "ran in a crowd" is coarse, robust, and explainable on a caveat line, which is
+ * what a number a fleet-size decision rests on has to be.
+ *
+ * Returns `null` when either group is too thin to speak — the caller must then
+ * say the model is assumed, not measured.
+ */
+export declare function estimateContention(samples: readonly ContentionSample[], options?: {
+    freeLanes?: number;
+    minGroup?: number;
+}): ContentionModel | null;
+export interface ConcurrencyChange {
+    /** When the count changed. */
+    at: number;
+    /** How many intervals were live from `at` until the next change. */
+    count: number;
+}
+/**
+ * Turn a set of intervals into the step function of how many were live.
+ *
+ * The exact series behind an "average tasks at once" number, so a reader can see
+ * the overlaps that produced it instead of taking the mean on faith. Ends before
+ * starts at a tie: two runs where one finishes as the next begins were never
+ * simultaneous, and counting them as two reports a concurrency the fleet's own
+ * limit forbids.
+ */
+export declare function concurrencyProfile(intervals: readonly {
+    from: number;
+    to: number;
+}[]): ConcurrencyChange[];
+/**
+ * Time-weighted mean concurrency across `[from, to)`, optionally counting only
+ * the parts of the window the fleet was actually ELIGIBLE to work.
+ *
+ * 🔴 The `exclude` argument is the whole point (owner report, 2026-08-23: *"the
+ * Tasks at once card says '.2'… if it is using paused time to calculate that
+ * there were usually 0 tasks at once let's stop letting it do that"*). Averaging
+ * a running fleet over a window it was switched off for 90% of does not describe
+ * the fleet, it describes the switch — and it reports a busy afternoon as 0.2.
+ * Excluded spans are removed from BOTH the numerator and the denominator, so the
+ * answer is "while it was running, this many at once".
+ */
+export declare function meanConcurrency(intervals: readonly {
+    from: number;
+    to: number;
+}[], window: {
+    from: number;
+    to: number;
+}, exclude?: readonly {
+    from: number;
+    to: number;
+}[]): number;

package/dist/core/analytics/schedule.js

@@ -0,0 +1,372 @@
+/**
+ * "How long until this queue is empty, and does another worker actually help?"
+ *
+ * ── The question this exists to answer (owner, 2026-08-23) ───────────────────
+ * *"For estimates of how long to empty tasks I would also like to be able to see
+ * them based on if I added to the fleet size or reduced it… I want to be able to
+ * tell whether there is a point where adding to the fleet slows down more than
+ * it speeds up. I also want to see the expected token usage so I know if I run
+ * out of tokens earlier and how much earlier."*
+ *
+ * Three separate claims hide in that, and a `remaining / rate` division answers
+ * none of them:
+ *
+ * 1. **Work does not parallelise freely.** Two tasks that write the same files
+ *    may not run together whatever the fleet size — that is the orchestrator's
+ *    own scope rule, and it is why a queue of ten tasks all scoped to one app
+ *    drains at exactly the same speed with eight workers as with one.
+ * 2. **Workers are not free of each other.** This machine's own measurements say
+ *    a verify gate takes 2m09s idle and 857s (6.6x) under seventeen concurrent
+ *    gates. Past some point another worker makes *everyone* slower, so the
+ *    makespan curve turns back UP — the "point where adding to the fleet slows
+ *    down more than it speeds up" is real, has a number, and this module finds
+ *    it. A scheduler with no contention term can never report one, because pure
+ *    list scheduling is monotone: more workers is never worse.
+ * 3. **Tokens are spent by work, not by time.** Doubling the fleet does not
+ *    double the tokens a queue costs — it spends the same budget roughly twice
+ *    as fast, so the wall-clock moment you run dry arrives sooner even though the
+ *    total is unchanged. Both numbers matter and they move in opposite
+ *    directions.
+ *
+ * ── Why it lives in cursedbelt and not in the orchestrator ───────────────────
+ * Nothing here knows what a "task" is. It schedules ITEMS with durations,
+ * exclusion keys and dependencies over WORKERS, which is the same shape as a
+ * deploy train, a batch of renders, a backup rotation or a CI matrix. The
+ * orchestrator supplies the meaning (a scope string, a serial group, a tier's
+ * measured duration) and reads the answer back; any other dashboard in the fleet
+ * can do the same without re-deriving a scheduler.
+ *
+ * Pure, deterministic, and clock-free: the caller passes `now` when it wants
+ * absolute times. That is what lets the whole forecast be asserted in a test
+ * rather than eyeballed on a chart.
+ */
+/** No contention at all — the ideal machine. Useful as a comparison line, and as
+ *  the honest choice when the work is not CPU-bound on one host. */
+export const NO_CONTENTION = { freeLanes: Number.POSITIVE_INFINITY, slowdownPerExtraWorker: 0 };
+export function stretchAt(model, concurrency) {
+    if (concurrency <= model.freeLanes)
+        return 1;
+    const raw = 1 + model.slowdownPerExtraWorker * (concurrency - model.freeLanes);
+    return Math.min(raw, model.maxStretch ?? 8);
+}
+/**
+ * Event-driven list scheduling with resource exclusion and a contention term.
+ *
+ * The loop is: admit everything that can start, advance the clock to whichever
+ * running item finishes FIRST **at the current concurrency's speed**, retire it,
+ * repeat. Progress is tracked as remaining WORK rather than an end timestamp,
+ * which is what makes contention correct rather than decorative: a task that
+ * started alone and is joined by three others slows down for the rest of its run
+ * and not retroactively.
+ *
+ * Admission order is priority, then longest-first. Longest-first (LPT) is the
+ * classic list-scheduling heuristic and matters here: shortest-first leaves a
+ * multi-hour task to start last and stretches the makespan by most of its own
+ * length, which would make every large fleet look pointless.
+ */
+export function simulateSchedule(items, options) {
+    const workers = Math.max(1, Math.floor(options.workers));
+    const contention = options.contention ?? NO_CONTENTION;
+    const startAt = options.startAt ?? 0;
+    const maxEvents = options.maxEvents ?? 20_000;
+    const pending = [...items].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0) || b.durationMs - a.durationMs);
+    const live = [];
+    const done = new Set();
+    const timeline = [];
+    const known = new Set(items.map((i) => i.id));
+    // Items already in flight occupy workers from t=0 and block their scopes.
+    for (const item of pending.filter((i) => typeof i.runningRemainingMs === 'number')) {
+        live.push({ item, remainingMs: Math.max(0, item.runningRemainingMs), startAt: 0, effectiveMs: 0 });
+    }
+    let queue = pending.filter((i) => typeof i.runningRemainingMs !== 'number');
+    let t = 0;
+    let peak = live.length;
+    // Area under the concurrency curve, for the time-weighted mean.
+    let concurrencyArea = 0;
+    let events = 0;
+    const conflicts = (candidate) => live.some((l) => blocks(candidate, l.item));
+    const depsMet = (candidate) => (candidate.dependsOn ?? []).every((id) => done.has(id) || !known.has(id));
+    while ((queue.length > 0 || live.length > 0) && events++ < maxEvents) {
+        // ── Admit ────────────────────────────────────────────────────────────────
+        let admitted = true;
+        while (admitted && live.length < workers) {
+            admitted = false;
+            for (let i = 0; i < queue.length; i++) {
+                const candidate = queue[i];
+                if (!depsMet(candidate) || conflicts(candidate))
+                    continue;
+                queue.splice(i, 1);
+                live.push({
+                    item: candidate,
+                    remainingMs: candidate.durationMs,
+                    startAt: t,
+                    effectiveMs: 0,
+                });
+                admitted = true;
+                break;
+            }
+        }
+        if (live.length > peak)
+            peak = live.length;
+        if (live.length === 0)
+            break; // everything left is unschedulable
+        // ── Advance ──────────────────────────────────────────────────────────────
+        // Everyone runs at the same rate, so the first to finish is simply the one
+        // with the least work left.
+        const stretch = stretchAt(contention, live.length);
+        const slice = Math.min(...live.map((l) => l.remainingMs)) * stretch;
+        // A zero-duration item would otherwise spin the loop without advancing.
+        const step = slice > 0 ? slice : 0;
+        const work = step / stretch;
+        for (const l of live) {
+            l.remainingMs -= work;
+            l.effectiveMs += step;
+        }
+        concurrencyArea += live.length * step;
+        t += step;
+        // ── Retire ───────────────────────────────────────────────────────────────
+        for (let i = live.length - 1; i >= 0; i--) {
+            // Floating-point: `remainingMs` lands on ~1e-10 rather than exactly 0.
+            if (live[i].remainingMs > 1e-6)
+                continue;
+            const l = live[i];
+            live.splice(i, 1);
+            done.add(l.item.id);
+            timeline.push({
+                id: l.item.id,
+                startAt: startAt + l.startAt,
+                endAt: startAt + t,
+                durationMs: l.item.durationMs,
+                effectiveMs: l.effectiveMs,
+                waitedMs: l.startAt,
+                blockedBy: l.startAt === 0 ? null : whyWaited(l.item, timeline, known),
+            });
+        }
+    }
+    const workMs = items.reduce((s, i) => s + (i.runningRemainingMs ?? i.durationMs), 0);
+    const spentMs = timeline.reduce((s, r) => s + r.effectiveMs, 0);
+    const makespanMs = t;
+    return {
+        workers,
+        makespanMs,
+        workMs,
+        spentMs,
+        contentionMs: Math.max(0, spentMs - timeline.reduce((s, r) => s + r.durationMs, 0)),
+        utilization: makespanMs === 0 ? 0 : clamp01(workMs / (workers * makespanMs)),
+        avgConcurrency: makespanMs === 0 ? 0 : round2(concurrencyArea / makespanMs),
+        peakConcurrency: peak,
+        cost: items.reduce((s, i) => s + (i.cost ?? 0), 0),
+        timeline: timeline.sort((a, b) => a.startAt - b.startAt),
+        unschedulable: queue.map((i) => i.id),
+    };
+}
+/** May `candidate` NOT run beside `other`? */
+function blocks(candidate, other) {
+    if (candidate.id === other.id)
+        return true;
+    if (candidate.group != null && candidate.group === other.group)
+        return true;
+    const mine = candidate.exclusive ?? [];
+    const theirs = other.exclusive ?? [];
+    if (mine.length === 0 || theirs.length === 0)
+        return false;
+    // `*` is the wildcard the orchestrator uses for fleet-wide work: it conflicts
+    // with everything that declares anything.
+    if (mine.includes('*') || theirs.includes('*'))
+        return true;
+    return mine.some((s) => theirs.includes(s));
+}
+/**
+ * A best-effort reason an item started late — for the table behind the chart.
+ *
+ * Deliberately approximate and labelled as such: the precise answer would need
+ * the admission loop to record every refusal at every event, which is a lot of
+ * bookkeeping for a column. "Was it waiting on a dependency, on a conflicting
+ * neighbour, or simply for a free worker" is the distinction a reader acts on,
+ * and that is decidable from the item alone.
+ */
+function whyWaited(item, _timeline, known) {
+    if ((item.dependsOn ?? []).some((id) => known.has(id)))
+        return 'dependency';
+    if ((item.exclusive?.length ?? 0) > 0 || item.group != null)
+        return 'conflict';
+    return 'worker';
+}
+export function sweepFleetSizes(items, options = {}) {
+    const maxWorkers = Math.max(1, Math.floor(options.maxWorkers ?? 8));
+    const tolerance = options.tolerance ?? 0.05;
+    const results = [];
+    for (let w = 1; w <= maxWorkers; w++) {
+        results.push(simulateSchedule(items, { ...options, workers: w }));
+    }
+    const base = results[0].makespanMs;
+    const points = results.map((r, i) => ({
+        workers: r.workers,
+        makespanMs: Math.round(r.makespanMs),
+        speedup: r.makespanMs === 0 ? 1 : round2(base / r.makespanMs),
+        efficiency: r.makespanMs === 0 ? 1 : round2(base / r.makespanMs / r.workers),
+        marginalMs: Math.round(i === 0 ? 0 : results[i - 1].makespanMs - r.makespanMs),
+        utilization: r.utilization,
+        avgConcurrency: r.avgConcurrency,
+        peakConcurrency: r.peakConcurrency,
+        contentionMs: Math.round(r.contentionMs),
+        cost: r.cost,
+        burnPerHour: r.makespanMs === 0 ? 0 : Math.round((r.cost / r.makespanMs) * 3_600_000),
+        unschedulable: r.unschedulable.length,
+    }));
+    // 🔴 The SMALLEST fleet that is as good as it gets — not the fastest, and not
+    // the last one with a positive margin. See `sweetSpot`'s doc for the measured
+    // case where the marginal reading recommends four times too many workers.
+    const best = Math.min(...points.map((p) => p.makespanMs));
+    const sweetSpot = points.find((p) => p.makespanMs <= best * (1 + tolerance))?.workers ?? 1;
+    const worse = points.find((p) => p.workers > 1 && p.marginalMs < 0);
+    return {
+        points,
+        sweetSpot,
+        turnsNegativeAt: worse ? worse.workers : null,
+        parallelismCeiling: Math.max(...results.map((r) => r.peakConcurrency), 1),
+    };
+}
+/**
+ * When a spend budget runs out at each fleet size.
+ *
+ * The counter-intuitive half, and the reason the owner asked for it: **the total
+ * is the same and the deadline is not.** A queue that costs 40M tokens costs 40M
+ * whether one agent or five works it; five agents simply reach the wall in a
+ * fifth of the time. So `coverage` (do I have enough at all?) is flat across the
+ * sweep while `exhaustedInMs` shrinks — and the honest reading is "more workers
+ * does not cost more, it costs sooner".
+ */
+export function projectBudget(sweep, budget) {
+    return sweep.points.map((p) => {
+        const coverage = p.cost === 0 ? 1 : clamp01(budget / p.cost);
+        return {
+            workers: p.workers,
+            exhaustedInMs: p.burnPerHour <= 0 || budget >= p.cost ? null : Math.round((budget / p.burnPerHour) * 3_600_000),
+            coverage: round2(coverage),
+            shortfall: Math.max(0, p.cost - budget),
+            burnPerHour: p.burnPerHour,
+        };
+    });
+}
+/**
+ * Fit a {@link ContentionModel} to runs that actually happened.
+ *
+ * Deliberately a two-group comparison rather than a regression: the sample is a
+ * few hundred runs of wildly different work, so a least-squares line through
+ * duration-versus-concurrency mostly measures which KIND of task tends to run
+ * alone. Comparing the median duration of "ran near-alone" against the median of
+ * "ran in a crowd" is coarse, robust, and explainable on a caveat line, which is
+ * what a number a fleet-size decision rests on has to be.
+ *
+ * Returns `null` when either group is too thin to speak — the caller must then
+ * say the model is assumed, not measured.
+ */
+export function estimateContention(samples, options = {}) {
+    const freeLanes = options.freeLanes ?? 2;
+    const minGroup = options.minGroup ?? 5;
+    const quiet = samples.filter((s) => s.concurrency <= freeLanes).map((s) => s.durationMs);
+    const busy = samples.filter((s) => s.concurrency > freeLanes);
+    if (quiet.length < minGroup || busy.length < minGroup)
+        return null;
+    const quietMedian = medianOf(quiet);
+    const busyMedian = medianOf(busy.map((s) => s.durationMs));
+    if (quietMedian <= 0)
+        return null;
+    const excess = medianOf(busy.map((s) => s.concurrency)) - freeLanes;
+    if (excess <= 0)
+        return null;
+    const stretch = busyMedian / quietMedian;
+    // A stretch below 1 means the crowded runs were FASTER — real, and it means
+    // the sample is dominated by task mix rather than by load. Report no
+    // measurable contention rather than a negative slowdown, which would make the
+    // simulator recommend an unbounded fleet.
+    const slope = Math.max(0, (stretch - 1) / excess);
+    return { freeLanes, slowdownPerExtraWorker: round2(slope), maxStretch: 8 };
+}
+/**
+ * Turn a set of intervals into the step function of how many were live.
+ *
+ * The exact series behind an "average tasks at once" number, so a reader can see
+ * the overlaps that produced it instead of taking the mean on faith. Ends before
+ * starts at a tie: two runs where one finishes as the next begins were never
+ * simultaneous, and counting them as two reports a concurrency the fleet's own
+ * limit forbids.
+ */
+export function concurrencyProfile(intervals) {
+    const points = [];
+    for (const i of intervals) {
+        if (i.to <= i.from)
+            continue;
+        points.push({ at: i.from, d: 1 }, { at: i.to, d: -1 });
+    }
+    points.sort((a, b) => a.at - b.at || a.d - b.d);
+    const out = [];
+    let live = 0;
+    for (const p of points) {
+        live += p.d;
+        const last = out[out.length - 1];
+        if (last && last.at === p.at)
+            last.count = live;
+        else
+            out.push({ at: p.at, count: live });
+    }
+    return out;
+}
+/**
+ * Time-weighted mean concurrency across `[from, to)`, optionally counting only
+ * the parts of the window the fleet was actually ELIGIBLE to work.
+ *
+ * 🔴 The `exclude` argument is the whole point (owner report, 2026-08-23: *"the
+ * Tasks at once card says '.2'… if it is using paused time to calculate that
+ * there were usually 0 tasks at once let's stop letting it do that"*). Averaging
+ * a running fleet over a window it was switched off for 90% of does not describe
+ * the fleet, it describes the switch — and it reports a busy afternoon as 0.2.
+ * Excluded spans are removed from BOTH the numerator and the denominator, so the
+ * answer is "while it was running, this many at once".
+ */
+export function meanConcurrency(intervals, window, exclude = []) {
+    const width = liveWidth(window, exclude);
+    if (width <= 0)
+        return 0;
+    let area = 0;
+    for (const i of intervals) {
+        const from = Math.max(i.from, window.from);
+        const to = Math.min(i.to, window.to);
+        if (to <= from)
+            continue;
+        area += liveWidth({ from, to }, exclude);
+    }
+    return round2(area / width);
+}
+/** Width of `window` minus everything `exclude` covers. Overlapping excludes are
+ *  merged first, or a nested pause subtracts twice and the mean explodes. */
+function liveWidth(window, exclude) {
+    const total = Math.max(0, window.to - window.from);
+    if (total === 0 || exclude.length === 0)
+        return total;
+    const clipped = exclude
+        .map((e) => ({ from: Math.max(e.from, window.from), to: Math.min(e.to, window.to) }))
+        .filter((e) => e.to > e.from)
+        .sort((a, b) => a.from - b.from);
+    let covered = 0;
+    let cursor = -Infinity;
+    for (const e of clipped) {
+        const from = Math.max(e.from, cursor);
+        if (e.to > from) {
+            covered += e.to - from;
+            cursor = e.to;
+        }
+    }
+    return Math.max(0, total - covered);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+const round2 = (n) => Math.round(n * 100) / 100;
+function medianOf(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}

package/dist/core/category/index.d.ts

@@ -0,0 +1,3 @@
+export type { Category, CategoryCreateInput, CategoryNode, CategoryStore, } from './types';
+export { buildCategoryForest, categoryPath, descendantCategoryIds, flattenCategoryForest, wouldCreateCycle, } from './tree';
+export { createMemoryCategoryStore } from './memoryStore';