feat(#233): optimiser library + endpoints (Phase 3 of Resource Optimiser)

[NickMonrad]

Summary

Phase 3 of 4 for Resource Optimiser (#233). Adds the optimiser engine + API endpoints. Backend only — frontend lands in Phase 4.

Endpoints

POST /api/projects/:projectId/optimise

Runs grid search across resource-count combinations, evaluates each via the pure scheduler, returns ranked candidates by mode.

Request body:

{
  "mode": "speed" | "utilisation" | "balanced",
  "constraints": {
    "countRanges": [{ "resourceTypeId": "...", "min": 1, "max": 6 }],
    "allowRampUp": true,
    "maxBudget": 500000,         // optional
    "maxDurationWeeks": 52       // optional
  },
  "dayRates": { "rt-id": 1500 }, // optional; falls back to ResourceType.dayRate
  "topN": 3
}

Response: ranked candidates, baseline for diff display, searchStats (scenariosEvaluated, candidatesFound, durationMs, sampled), and a resourceTypes lookup [{id,name}].

POST /api/projects/:projectId/optimise/apply

Applies a candidate scenario:

1. Creates an optimiser_apply snapshot (full v2 state) for rollback
2. Updates ResourceType.count + NamedResource.startWeek (if rampUp suggested) in a transaction
3. Re-materialises timeline via the pure scheduler with the new config
4. Returns the new snapshotId so the UI can offer "Undo"

Library: server/src/lib/optimiser.ts (pure, no I/O)

• Grid search with MAX_SCENARIOS = 5000 cap; falls back to random sampling for larger spaces (search reports sampled: true)
• Modes:
  • speed — minimise deliveryWeeks, tiebreak by cost then utilisation
  • utilisation — maximise avg utilisation %, tiebreak by deliveryWeeks
  • balanced — multi-objective normalised score (40% speed, 40% utilisation, 20% cost; redistributes when costs absent)
• Metrics per candidate: deliveryWeeks, avgUtilisationPct, gapWeeksByResourceTypeId, estimatedCost, parallelWarningCount
• Constraints maxBudget / maxDurationWeeks drop scenarios entirely (not score-penalised)
• Cost: count × dayRate × 5 × deliveryWeeks using ResourceType.dayRate or request-supplied overrides
• Utilisation computed from raw demand vs capacity (no full resource-levelling) — orders-of-magnitude faster, makes 5000 scenarios feasible

Review fixes applied (sub-agent review cycle)

• 🔴 HIGH — apply endpoint was using stale pre-transaction startWeek when re-materialising timeline; now overrides in memory before scheduler call
• 🟡 MEDIUM — searchStats.scenariosEvaluated now counts scheduler invocations (was post-constraint survivors); added candidatesFound
• 🟡 MEDIUM — gapWeeksByResourceTypeId keyed on RT id (was name; collision risk since name has no unique constraint)
• 🟡 MEDIUM — apply body now element-validates each resourceType (rejects count: "three", missing fields, negative startWeek with 400)
• 🟢 LOW — Date.now() and Math.random() made injectable (clock + seedable PRNG) for deterministic tests
• ✅ Verified: purity, baseInput non-mutation, Cartesian product correctness, snapshot+trigger, auth, route ordering, no any casts

Tests

• npx tsc --noEmit (server + client) — ✅ clean
• npm test (server) — ✅ 182/182 passing (164 prior + 18 new optimiser tests)

New test coverage includes: happy path, all 3 modes producing different rankings, both constraint types, empty project, sampling fallback, single-scenario grid, topN > scenarios, manually-pinned stories counted in demand, seeded-PRNG determinism, route validation (4 cases).

Phases

• Phase 1 — Snapshot expansion (feat(#233): expand snapshot JSON to capture timeline state (Phase 1 of Resource Optimiser) #234, merged)
• Phase 2 — Pure scheduler library (feat(#233): extract scheduler engine into pure lib (Phase 2 of Resource Optimiser) #235, merged)
• Phase 3 — Optimiser library + endpoints (this PR)
• Phase 4 — Frontend optimiser drawer + result preview/apply

Refs #233