cursedbelt-core 1.0.0

package/src/core/analytics/schedule.spec.ts

@@ -0,0 +1,311 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  concurrencyProfile,
+  type ContentionModel,
+  estimateContention,
+  meanConcurrency,
+  NO_CONTENTION,
+  projectBudget,
+  type ScheduleItem,
+  simulateSchedule,
+  stretchAt,
+  sweepFleetSizes,
+} from './schedule';
+
+const MIN = 60_000;
+const item = (id: string, minutes: number, rest: Partial<ScheduleItem> = {}): ScheduleItem => ({
+  id,
+  durationMs: minutes * MIN,
+  ...rest,
+});
+
+describe('simulateSchedule', () => {
+  it('runs independent work in parallel up to the worker count', () => {
+    const items = [item('a', 10), item('b', 10), item('c', 10), item('d', 10)];
+    expect(simulateSchedule(items, { workers: 1 }).makespanMs).toBe(40 * MIN);
+    expect(simulateSchedule(items, { workers: 2 }).makespanMs).toBe(20 * MIN);
+    expect(simulateSchedule(items, { workers: 4 }).makespanMs).toBe(10 * MIN);
+    // Nothing left to parallelise — the fifth worker is inert.
+    expect(simulateSchedule(items, { workers: 5 }).makespanMs).toBe(10 * MIN);
+  });
+
+  it('refuses to co-schedule items that write the same resource, at any fleet size', () => {
+    const items = [
+      item('a', 10, { exclusive: ['repo:x'] }),
+      item('b', 10, { exclusive: ['repo:x'] }),
+      item('c', 10, { exclusive: ['repo:x'] }),
+    ];
+    // The whole point: eight workers do not beat one when the work is serial.
+    expect(simulateSchedule(items, { workers: 8 }).makespanMs).toBe(30 * MIN);
+    expect(simulateSchedule(items, { workers: 8 }).peakConcurrency).toBe(1);
+  });
+
+  it('treats `*` as conflicting with everything that declares a scope', () => {
+    const items = [item('fleet', 10, { exclusive: ['*'] }), item('app', 10, { exclusive: ['repo:x'] })];
+    expect(simulateSchedule(items, { workers: 4 }).makespanMs).toBe(20 * MIN);
+  });
+
+  it('lets undeclared items run beside anything — a missing scope is not a lock', () => {
+    const items = [item('scoped', 10, { exclusive: ['repo:x'] }), item('bare', 10)];
+    expect(simulateSchedule(items, { workers: 2 }).makespanMs).toBe(10 * MIN);
+  });
+
+  it('serialises a named group without needing a shared resource', () => {
+    const items = [item('a', 5, { group: 'gpu' }), item('b', 5, { group: 'gpu' })];
+    expect(simulateSchedule(items, { workers: 4 }).makespanMs).toBe(10 * MIN);
+  });
+
+  it('honours dependencies', () => {
+    const items = [item('second', 10, { dependsOn: ['first'] }), item('first', 10)];
+    const r = simulateSchedule(items, { workers: 4 });
+    expect(r.makespanMs).toBe(20 * MIN);
+    const byId = new Map(r.timeline.map((t) => [t.id, t]));
+    expect(byId.get('second')?.startAt).toBe(10 * MIN);
+    expect(byId.get('second')?.blockedBy).toBe('dependency');
+  });
+
+  it('reports a dependency cycle as unschedulable instead of spinning', () => {
+    const items = [item('a', 1, { dependsOn: ['b'] }), item('b', 1, { dependsOn: ['a'] })];
+    const r = simulateSchedule(items, { workers: 2 });
+    expect(r.unschedulable.sort()).toEqual(['a', 'b']);
+    expect(r.makespanMs).toBe(0);
+  });
+
+  it('counts work already in flight against the fleet', () => {
+    const items = [
+      item('running', 0, { runningRemainingMs: 10 * MIN }),
+      item('queued', 10),
+    ];
+    // One worker: the in-flight item holds it, so the queued one waits.
+    expect(simulateSchedule(items, { workers: 1 }).makespanMs).toBe(20 * MIN);
+    expect(simulateSchedule(items, { workers: 2 }).makespanMs).toBe(10 * MIN);
+  });
+
+  it('schedules longest-first so a big task does not tail the run', () => {
+    const items = [item('small1', 1), item('small2', 1), item('big', 10)];
+    // Shortest-first would finish at 12m (big starts at 2m). LPT starts it at 0.
+    expect(simulateSchedule(items, { workers: 2 }).makespanMs).toBe(10 * MIN);
+  });
+
+  it('stamps absolute times when given a start', () => {
+    const r = simulateSchedule([item('a', 5)], { workers: 1, startAt: 1_000_000 });
+    expect(r.timeline[0].startAt).toBe(1_000_000);
+    expect(r.timeline[0].endAt).toBe(1_000_000 + 5 * MIN);
+  });
+});
+
+describe('contention', () => {
+  const busy: ContentionModel = { freeLanes: 2, slowdownPerExtraWorker: 0.5, maxStretch: 8 };
+
+  it('leaves work at nominal speed inside the free lanes', () => {
+    expect(stretchAt(busy, 1)).toBe(1);
+    expect(stretchAt(busy, 2)).toBe(1);
+    expect(stretchAt(busy, 3)).toBe(1.5);
+    expect(stretchAt(busy, 4)).toBe(2);
+  });
+
+  it('caps the multiplier so an absurd fleet does not produce an infinite ETA', () => {
+    expect(stretchAt(busy, 100)).toBe(8);
+  });
+
+  it('makes a big fleet SLOWER than a small one — the owner’s actual question', () => {
+    const items = Array.from({ length: 8 }, (_, i) => item(`t${i}`, 10));
+    const steep: ContentionModel = { freeLanes: 2, slowdownPerExtraWorker: 0.6 };
+    const two = simulateSchedule(items, { workers: 2, contention: steep }).makespanMs;
+    const eight = simulateSchedule(items, { workers: 8, contention: steep }).makespanMs;
+    // Throughput is `workers / stretch(workers)`: 2/1 = 2 against 8/4.6 = 1.74.
+    // Without a contention term this comparison cannot come out this way at all.
+    expect(eight).toBeGreaterThan(two);
+  });
+
+  it('breaks even exactly where the slowdown cancels the extra worker', () => {
+    const items = Array.from({ length: 8 }, (_, i) => item(`t${i}`, 10));
+    // stretch(8) = 1 + 0.5*6 = 4, so 8/4 === 2/1: the same throughput, and the
+    // same makespan. The boundary case is worth pinning — it is what tells the
+    // reader the model is a real trade-off and not a fudge factor.
+    expect(simulateSchedule(items, { workers: 8, contention: busy }).makespanMs).toBe(
+      simulateSchedule(items, { workers: 2, contention: busy }).makespanMs,
+    );
+  });
+
+  it('charges the extra time to contention, not to the work', () => {
+    const items = [item('a', 10), item('b', 10), item('c', 10), item('d', 10)];
+    const r = simulateSchedule(items, { workers: 4, contention: busy });
+    expect(r.workMs).toBe(40 * MIN);
+    expect(r.spentMs).toBeGreaterThan(r.workMs);
+    expect(r.contentionMs).toBeGreaterThan(0);
+  });
+
+  it('is a no-op under NO_CONTENTION', () => {
+    const items = [item('a', 10), item('b', 10)];
+    const r = simulateSchedule(items, { workers: 2, contention: NO_CONTENTION });
+    expect(r.contentionMs).toBe(0);
+    expect(r.makespanMs).toBe(10 * MIN);
+  });
+});
+
+describe('sweepFleetSizes', () => {
+  it('finds the ceiling the WORK imposes, regardless of fleet size', () => {
+    const items = [
+      item('a', 10, { exclusive: ['repo:x'] }),
+      item('b', 10, { exclusive: ['repo:x'] }),
+      item('c', 10, { exclusive: ['repo:x'] }),
+    ];
+    const sweep = sweepFleetSizes(items, { maxWorkers: 6 });
+    expect(sweep.parallelismCeiling).toBe(1);
+    expect(sweep.sweetSpot).toBe(1);
+    expect(sweep.points.every((p) => p.makespanMs === 30 * MIN)).toBe(true);
+  });
+
+  it('recommends the last worker that earned its place, not the fastest', () => {
+    // Six 10m tasks: 1w=60m, 2w=30m, 3w=20m, 4w=20m, 5w=20m, 6w=10m.
+    const items = Array.from({ length: 6 }, (_, i) => item(`t${i}`, 10));
+    const sweep = sweepFleetSizes(items, { maxWorkers: 6 });
+    // 4 and 5 buy nothing at all; 6 buys another 10m, which is >5% of 60m.
+    expect(sweep.points.find((p) => p.workers === 4)?.marginalMs).toBe(0);
+    expect(sweep.sweetSpot).toBe(6);
+    expect(sweep.turnsNegativeAt).toBeNull();
+  });
+
+  it('names the fleet size where another worker starts costing wall clock', () => {
+    const items = Array.from({ length: 8 }, (_, i) => item(`t${i}`, 10));
+    const sweep = sweepFleetSizes(items, {
+      maxWorkers: 8,
+      contention: { freeLanes: 2, slowdownPerExtraWorker: 0.6 },
+    });
+    // 1w 80m · 2w 40m · 3w 42m — the third agent is where it turns.
+    expect(sweep.turnsNegativeAt).toBe(3);
+    expect(sweep.sweetSpot).toBe(2);
+  });
+
+  it('does not recommend a big fleet that merely beats a slightly worse big fleet', () => {
+    // The measured trap: at a 0.6 slowdown, 7 workers take 50m and 8 take 46m,
+    // so 8 shows a healthy +4m MARGIN while being 6m worse than just running 2.
+    const items = Array.from({ length: 8 }, (_, i) => item(`t${i}`, 10));
+    const sweep = sweepFleetSizes(items, {
+      maxWorkers: 8,
+      contention: { freeLanes: 2, slowdownPerExtraWorker: 0.6 },
+    });
+    expect(sweep.points.find((p) => p.workers === 8)?.marginalMs).toBeGreaterThan(0);
+    expect(sweep.sweetSpot).toBe(2);
+  });
+
+  it('reports speedup and efficiency against one worker', () => {
+    const items = Array.from({ length: 4 }, (_, i) => item(`t${i}`, 10));
+    const sweep = sweepFleetSizes(items, { maxWorkers: 4 });
+    const four = sweep.points.find((p) => p.workers === 4);
+    expect(four?.speedup).toBe(4);
+    expect(four?.efficiency).toBe(1);
+  });
+});
+
+describe('projectBudget', () => {
+  const items = Array.from({ length: 4 }, (_, i) => item(`t${i}`, 10, { cost: 1_000_000 }));
+
+  it('keeps the TOTAL flat across fleet sizes and moves only the deadline', () => {
+    const sweep = sweepFleetSizes(items, { maxWorkers: 4 });
+    const projected = projectBudget(sweep, 2_000_000);
+    expect(new Set(sweep.points.map((p) => p.cost)).size).toBe(1);
+    expect(projected.every((p) => p.coverage === 0.5)).toBe(true);
+    const one = projected.find((p) => p.workers === 1) as (typeof projected)[number];
+    const four = projected.find((p) => p.workers === 4) as (typeof projected)[number];
+    // Four workers reach the wall four times sooner.
+    expect(one.exhaustedInMs).toBe(20 * MIN);
+    expect(four.exhaustedInMs).toBe(5 * MIN);
+    expect(one.shortfall).toBe(2_000_000);
+  });
+
+  it('reports no exhaustion when the budget covers the queue', () => {
+    const sweep = sweepFleetSizes(items, { maxWorkers: 2 });
+    expect(projectBudget(sweep, 10_000_000).every((p) => p.exhaustedInMs === null)).toBe(true);
+  });
+});
+
+describe('estimateContention', () => {
+  it('measures a slowdown from real runs', () => {
+    const samples = [
+      ...Array.from({ length: 10 }, () => ({ concurrency: 1, durationMs: 10 * MIN })),
+      ...Array.from({ length: 10 }, () => ({ concurrency: 4, durationMs: 20 * MIN })),
+    ];
+    const model = estimateContention(samples, { freeLanes: 2 });
+    // Median busy concurrency 4, two lanes over free, 2x stretch → 0.5 per worker.
+    expect(model).toEqual({ freeLanes: 2, slowdownPerExtraWorker: 0.5, maxStretch: 8 });
+  });
+
+  it('returns null rather than a confident model when a group is thin', () => {
+    const samples = [
+      { concurrency: 1, durationMs: 10 * MIN },
+      { concurrency: 5, durationMs: 40 * MIN },
+    ];
+    expect(estimateContention(samples)).toBeNull();
+  });
+
+  it('never reports a NEGATIVE slowdown, which would justify an unbounded fleet', () => {
+    const samples = [
+      ...Array.from({ length: 10 }, () => ({ concurrency: 1, durationMs: 30 * MIN })),
+      ...Array.from({ length: 10 }, () => ({ concurrency: 5, durationMs: 5 * MIN })),
+    ];
+    expect(estimateContention(samples, { freeLanes: 2 })?.slowdownPerExtraWorker).toBe(0);
+  });
+});
+
+describe('concurrencyProfile', () => {
+  it('emits one step per change, with ends before starts at a tie', () => {
+    expect(
+      concurrencyProfile([
+        { from: 0, to: 10 },
+        { from: 10, to: 20 },
+      ]),
+    ).toEqual([
+      { at: 0, count: 1 },
+      { at: 10, count: 1 },
+      { at: 20, count: 0 },
+    ]);
+  });
+
+  it('counts genuine overlap', () => {
+    const profile = concurrencyProfile([
+      { from: 0, to: 10 },
+      { from: 5, to: 15 },
+    ]);
+    expect(profile).toEqual([
+      { at: 0, count: 1 },
+      { at: 5, count: 2 },
+      { at: 10, count: 1 },
+      { at: 15, count: 0 },
+    ]);
+  });
+
+  it('drops zero-width intervals', () => {
+    expect(concurrencyProfile([{ from: 5, to: 5 }])).toEqual([]);
+  });
+});
+
+describe('meanConcurrency', () => {
+  const window = { from: 0, to: 100 };
+
+  it('is time-weighted across the window', () => {
+    expect(meanConcurrency([{ from: 0, to: 50 }], window)).toBe(0.5);
+  });
+
+  it('excludes a paused span from BOTH halves of the average', () => {
+    const intervals = [{ from: 90, to: 100 }];
+    // Naively: 10 of 100 = 0.1 — the number the owner saw as ".2".
+    expect(meanConcurrency(intervals, window)).toBe(0.1);
+    // Excluding the 90 units the engine was off: 10 of 10 = 1 task at once.
+    expect(meanConcurrency(intervals, window, [{ from: 0, to: 90 }])).toBe(1);
+  });
+
+  it('merges overlapping exclusions instead of subtracting twice', () => {
+    const intervals = [{ from: 80, to: 100 }];
+    const nested = [
+      { from: 0, to: 80 },
+      { from: 10, to: 40 },
+    ];
+    expect(meanConcurrency(intervals, window, nested)).toBe(1);
+  });
+
+  it('is 0, not NaN, when the window is entirely excluded', () => {
+    expect(meanConcurrency([{ from: 0, to: 10 }], window, [{ from: 0, to: 100 }])).toBe(0);
+  });
+});