[GRV-27]: Resolve estimation API and catalog drift (#43)

## What & why

`llm-cost-estimation` re-exported attribution's implemented forecaster
but its catalog still described `ForecastIssueCost` as a planned stub,
and it exposed `forecastProjectCost` / `calibrate` as throwing `not
implemented` placeholders — even though their implemented analogs
already shipped in `llm-cost-attribution`. This PR makes the docs,
README, public exports, and tests agree on what is implemented vs.
unsupported, turning the catalog/API alignment check green for
estimation.

Resolves
[GRV-27](https://linear.app/riddimsoftware/issue/GRV-27/resolve-estimation-api-and-catalog-drift).

## Changes

- **`src/index.mjs`**
- `forecastProjectCost` now re-exports attribution's implemented project
forecaster — estimation-friendly signature `forecastProjectCost(issues,
usageSource?, options?)` with `{ size, model }` IssuePlans, consistent
with `forecastIssueCost`.
- Adds `calibrateCoverage`, re-exported from attribution's implemented
coverage backtester.
- `calibrate` kept as a deprecated compatibility shim; its error names
the supported replacement (`calibrateCoverage`) instead of `not
implemented`.
- **`docs/use-cases.md`** — rewrites `ForecastIssueCost` and
`ForecastProjectCost` to describe shipped behavior (no longer "Planned —
stub throws"), adds a `CalibrateCoverage` entry, and documents
`calibrate` as deprecated. `ForecastIssueCost` now reflects the real
`(cell, records)` shape rather than the never-built `CalibrationDataset`
model.
- **`README.md`** — drops `calibrate` from the ready-use import example;
documents the real `forecastProjectCost` / `calibrateCoverage`
signatures and the `calibrate` deprecation.
- **`test/smoke.test.mjs`** — no longer asserts ready APIs throw `not
implemented`: `forecastProjectCost` forecasts an empty project,
`calibrateCoverage` is asserted exported, and `calibrate`'s error is
asserted to name its replacement.

## Acceptance criteria

- [x] `docs/use-cases.md` accurately describes shipped behavior.
- [x] `ForecastIssueCost` no longer described as a planned stub.
- [x] README import examples do not advertise throwing APIs as
ready-to-use.
- [x] `forecastProjectCost` delegates to attribution's implemented
project forecaster with a documented estimation-friendly signature.
- [x] `calibrate` documented as deprecated and omitted from ready-use
examples; `calibrateCoverage` delegates to the implemented
calibration/coverage API.
- [x] Barrel smoke tests no longer assert advertised ready APIs throw
`not implemented`.
- [x] The one remaining throwing export (`calibrate`) names its
supported replacement.
- [x] Existing enrichment and CLI forecast behavior preserved (no
changes to `enrich.mjs`, `linear-estimate-source.mjs`, `bin/`).
- [x] Catalog/API alignment turns green for estimation.
- [x] Estimation package tests pass.

## Out of scope (unchanged)

No attribution forecast-math changes, no project-level quota forecasts,
no npm publishing / version bumps.

## Verification

```
node --test packages/llm-cost-estimation/test/   # 37 passing, 0 failing
node --check packages/llm-cost-estimation/src/*.mjs  # OK
```

Re-verified after rebasing onto `origin/main` (which merged GRV-24's
attribution port extraction): the `forecastProjectCost` /
`calibrateCoverage` re-exports still resolve and all 37 tests pass.

Co-authored-by: riddim-developer-bot <developer-bot@riddimsoftware.com>

Author: riddim-developer-bot[bot]

packages/llm-cost-estimation/README.md

@@ -99,8 +99,8 @@ llm-cost-estimate --size 3 --model claude-sonnet-4-6 --from-usage ./usage.jsonl
 import {
   forecastIssueCost,
   forecastProjectCost,
+  calibrateCoverage,
   enrichUsageWithEstimate,
-  calibrate,
   createLinearEstimateSource,
 } from 'llm-cost-estimation';
 ```
@@ -122,15 +122,38 @@ Core transform for adding estimates to usage telemetry.
 - Returns `{ records, unresolved, stats }`.
 - Issues with no estimate are left untouched and listed in `unresolved`.
 
-### `forecastProjectCost(projectId, issues, options?)`
+### `forecastProjectCost(issues, usageSource?, options?)`
 
-Public API placeholder for project rollups.
-Throws `Error('not implemented')` until the next sequencing issue lands.
+Forecast a whole project's cost by Monte Carlo convolution over its planned
+issues. Re-exported from [`llm-cost-attribution`](../llm-cost-attribution).
 
-### `calibrate(completedIssues, options?)`
+- `issues` is an array of `{ size, model }` plans — one per planned issue, the
+  same cell model `forecastIssueCost` reads.
+- `usageSource` is estimate-tagged usage records (the project's history).
+- `options` accepts `{ iterations, seed, minSampleSize, pricingTable }`.
+- Returns tokens / turns / (priced) dollars channels — each with P50, P80,
+  `mean`, `variance` — plus `iterations`, `seed`, `issues`, `lowConfidence`, and
+  `empty`.
 
-Public API placeholder for empirical calibration from completed work.
-Throws `Error('not implemented')` until the next sequencing issue lands.
+Summing per-issue P80s over-estimates a project total because tail risks partly
+diversify; the convolution corrects for that. Project-level **quota** is not
+forecast — quota is a per-issue windowed quantity that doesn't sum.
+
+### `calibrateCoverage(records, options?)`
+
+Backtest the forecaster: on held-out issues, does the actual cost really land at
+or below the predicted P80 about 80% of the time? Re-exported from
+[`llm-cost-attribution`](../llm-cost-attribution).
+
+- `records` are estimate-tagged usage records.
+- `options` accepts `{ seed, holdoutFraction, quantile, deviationThreshold, minHoldout, minTrain }`.
+- Returns a per-cell and overall coverage report; cells whose coverage drifts
+  from the target band beyond `deviationThreshold` are flagged.
+
+### `calibrate` — deprecated
+
+`calibrate` was a never-implemented placeholder. It now throws an error naming
+its replacement, `calibrateCoverage` (above). Do not use it.
 
 ## What it doesn't do
 

packages/llm-cost-estimation/docs/use-cases.md

@@ -15,6 +15,12 @@ The stats and forecaster core depends only on the `EstimateTaggedUsageSource` an
 `LinearEstimateSource` ports. No Linear SDK, HTTP client, or filesystem import may
 cross inward into the domain/application layer.
 
+The forecast and calibration use cases below are re-exported from
+`llm-cost-attribution`, which owns the empirical-quantile forecaster, the project
+forecaster, and the coverage backtester. The estimation package surfaces them
+through its public barrel so callers import one package; it does not re-implement
+the math.
+
 ---
 
 ## EnrichUsageWithEstimate
@@ -43,17 +49,17 @@ absent.
 
 | Field | Value |
 |---|---|
-| **Goal** | Forecast the expected LLM cost for a single issue before work begins, given its story-point estimate and a calibration dataset built from completed issues with known actual cost. |
-| **Inputs** | `estimate: number` (story-point estimate); `calibration: CalibrationDataset` (from `calibrate()`). |
-| **Outputs** | `IssueCostForecast` — empirical quantile distribution of expected cost (p50, p80, p95) and dollar API-equivalent. |
-| **Entities / values** | `CalibrationDataset` — cost samples grouped by story-point estimate; `IssueCostForecast` — quantile estimates. |
-| **Ports** | `EstimateTaggedUsageSource` — supplies completed-issue records with `estimate` already stamped, used at calibration time (see `calibrate()`). The `forecastIssueCost` call itself takes no port — it runs over an already-built `CalibrationDataset` value. |
-| **Primary adapters** | `UsageJsonlEstimateTaggedSource` (planned) — reads enriched `usage.jsonl` files produced by `EnrichUsageWithEstimate`. |
+| **Goal** | Forecast the expected LLM cost for a single issue before work begins, from the historical cost of completed issues that share its `{ size, model }` cell. |
+| **Inputs** | `cell: { size, model }`; `records` — estimate-tagged usage records (the cell's history), the same source shape the attribution forecaster accepts. |
+| **Outputs** | `IssueCostForecast` — `tokens`, `turns`, and `dollars` channels each with P50/P80 and `n`; an optional Codex `quota`-fraction P50/P80 (single-issue only, never aggregated to a project) with `quotaReason`; plus `lowConfidence` and `empty` markers. |
+| **Entities / values** | `Cell` / `FeatureRecord` (`{ size, model }`); `IssueCostForecast`. |
+| **Ports** | `EstimateTaggedUsageSource` supplies the records; `PricingTable` (`priceFor(model, buckets)`) prices the dollars channel; `QuotaModel` (`quotaFractionFor(record)`) reads the Codex quota fraction. All three are injected — the forecaster imports none of their implementations. |
+| **Primary adapters** | `usage.jsonl` reader (`EstimateTaggedUsageSource`), synthetic record source in tests, `pricing.mjs` (`PricingTable`), `quota.mjs` (`QuotaModel`) — all in `llm-cost-attribution`. |
 | **Linear issues** | GRV-3, GRV-5 |
-| **Status** | Planned — stub throws `Error('not implemented')`. |
+| **Current implementation** | Re-exported from `llm-cost-attribution` (`packages/llm-cost-attribution/src/forecast.mjs`). |
 
 **Boundary rule:** The empirical quantile forecaster is a pure function over the
-calibration dataset. No Linear SDK, HTTP, or filesystem call occurs during
+records and its injected ports. No Linear SDK, HTTP, or filesystem call occurs during
 `forecastIssueCost`.
 
 ---
@@ -62,28 +68,45 @@ calibration dataset. No Linear SDK, HTTP, or filesystem call occurs during
 
 | Field | Value |
 |---|---|
-| **Goal** | Forecast the aggregate LLM cost for an entire project by Monte Carlo convolution over the per-issue cost distributions for each issue's estimate. |
-| **Inputs** | `issues: { identifier: string, estimate: number }[]` (project issues with story-point estimates); `calibration: CalibrationDataset`. |
-| **Outputs** | `ProjectCostForecast` — aggregate quantile distribution (p50, p80, p95) and dollar API-equivalent for the project total. |
-| **Entities / values** | `CalibrationDataset`; `ProjectCostForecast` — aggregate quantile estimates. |
-| **Ports** | `EstimateTaggedUsageSource` — used at calibration time only (see `calibrate()`). The `forecastProjectCost` call itself takes no port. |
-| **Primary adapters** | `UsageJsonlEstimateTaggedSource` (planned) — same adapter as `ForecastIssueCost`. |
+| **Goal** | Forecast an entire project's aggregate cost by Monte Carlo convolution over its planned issues, so summed quantiles don't over-estimate the total (per-issue tail risks partly diversify). |
+| **Inputs** | `issues: { size, model }[]` (one IssuePlan per planned issue); `usageSource` — estimate-tagged usage records; `options: { iterations, seed, minSampleSize, pricingTable }`. |
+| **Outputs** | `ProjectCostForecast` — `tokens`, `turns`, and (when priced) `dollars` channels, each with P50/P80, `mean`, and `variance`; plus `iterations`, `seed`, `issues`, `lowConfidence`, and `empty`. |
+| **Entities / values** | `IssuePlan` (`{ size, model }`); `ProjectCostForecast`; `ProjectChannelForecast`. |
+| **Ports** | The per-issue forecaster's empirical cell sampler (`collectCellSamples`); the shared `PricingTable` (`priceFor(model, buckets)`); a seeded RNG. The call reads records through the sampler, not directly. |
+| **Primary adapters** | Seeded RNG (mulberry32, in-module); `pricing.mjs` (`PricingTable`) — both in `llm-cost-attribution`. |
 | **Linear issue** | GRV-6 |
-| **Status** | Planned — stub throws `Error('not implemented')`. |
+| **Current implementation** | Re-exported from `llm-cost-attribution` (`packages/llm-cost-attribution/src/project-forecast.mjs`). |
+
+**Scope:** tokens, turns, and dollars only. Project-level quota and wall-clock are
+excluded by construction — they are windowed / scheduling quantities that do not sum
+across issues.
 
 **Boundary rule:** The Monte Carlo convolution is pure. No Linear SDK, HTTP, or
 filesystem call occurs during `forecastProjectCost`.
 
 ---
 
-## calibrate (support function, not a use case)
+## CalibrateCoverage
+
+| Field | Value |
+|---|---|
+| **Goal** | Backtest the forecaster: hold out a deterministic fraction of each cell's issues, fit on the rest, and measure how often held-out actuals land at or below the predicted P80 — so a "P80" only keeps the name if it covers ~80% of held-out cost. |
+| **Inputs** | `records` — estimate-tagged usage records; `options: { seed, holdoutFraction, quantile, deviationThreshold, minHoldout, minTrain }`. |
+| **Outputs** | `CalibrationReport` — per-cell and overall coverage, with cells whose coverage drifts from the target band beyond `deviationThreshold` flagged. |
+| **Entities / values** | `CalibrationReport`; `CalibrationCellReport`. |
+| **Ports** | None beyond the per-issue forecaster it fits with (`forecastIssueCost`). Pure and I/O-free; callers stream records in. |
+| **Primary adapters** | Seeded held-out split (mulberry32, in-module) — in `llm-cost-attribution`. |
+| **Linear issue** | GRV-3 |
+| **Current implementation** | Re-exported as `calibrateCoverage` from `llm-cost-attribution` (`packages/llm-cost-attribution/src/calibrate.mjs`). |
+
+**Boundary rule:** The backtest is a pure function over the supplied records. No Linear
+SDK, HTTP, or filesystem call occurs during `calibrateCoverage`.
+
+---
 
-Builds a `CalibrationDataset` from completed issues whose actual cost is known.
-Used as a preparation step before calling the forecast functions.
+## calibrate (deprecated)
 
-**Input:** `completedIssues: { identifier: string, estimate: number, actualCostUsd: number }[]`
-**Output:** `CalibrationDataset` — cost samples grouped by story-point estimate.
-**Ports used:** None (pure transform over caller-supplied data; I/O for fetching the
-source records is the caller's responsibility, typically via `EstimateTaggedUsageSource`).
-**Linear issue:** GRV-3
-**Status:** Planned — stub throws `Error('not implemented')`.
+The barrel exports a bare `calibrate` name only as a deprecated compatibility shim.
+It was never implemented; calling it throws an error naming its replacement,
+`calibrateCoverage` (above). It is omitted from the README's ready-to-use import
+example and carries no supported behavior.

packages/llm-cost-estimation/src/index.mjs

@@ -1,9 +1,10 @@
 /**
  * Public API for `llm-cost-estimation`.
  *
- * Implemented exports are re-exported from their sub-modules; the remaining
- * stubs throw until their implementing issue lands. Import from this barrel —
- * do not import from sub-modules directly.
+ * Every shipped export is implemented here or re-exported from
+ * `llm-cost-attribution`, which owns the forecaster, project forecaster, and
+ * coverage backtester. Import from this barrel — do not import from sub-modules
+ * directly.
  */
 
 /**
@@ -25,31 +26,49 @@ export { createLinearEstimateSource } from './linear-estimate-source.mjs';
  * cell from a set of estimate-tagged usage records. Re-exported from
  * `llm-cost-attribution`, which owns the empirical-quantile forecaster and
  * its `PricingTable` / `QuotaModel` adapters.
+ *
+ * Signature: `forecastIssueCost(cell, records, options?)` where `cell` is
+ * `{ size, model }` and `records` are estimate-tagged usage records.
  */
 export { forecastIssueCost } from 'llm-cost-attribution';
 
 /**
- * Forecast the aggregate LLM cost for an entire Linear project, given per-issue
- * estimates and a calibration dataset.
+ * Forecast an entire project's aggregate cost by Monte Carlo convolution over
+ * its planned issues. Re-exported from `llm-cost-attribution`, which owns the
+ * project forecaster.
  *
- * @param {string}   projectId    Linear project identifier.
- * @param {object[]} issues       Array of `{ identifier, estimate }` objects.
- * @param {object}   [options]
- * @returns {Promise<object>}
+ * Estimation-friendly signature:
+ * `forecastProjectCost(issues, usageSource?, options?)` where `issues` is an
+ * array of `{ size, model }` IssuePlans (the same cell model
+ * `forecastIssueCost` reads) and `usageSource` is estimate-tagged usage
+ * records. Forecasts tokens / turns / dollars only — project-level quota is a
+ * per-issue windowed quantity that does not sum, and is not forecast here.
  */
-export async function forecastProjectCost(projectId, issues, options = {}) {
-  throw new Error('not implemented');
-}
+export { forecastProjectCost } from 'llm-cost-attribution';
+
+/**
+ * Backtest the empirical forecaster: on held-out estimate-tagged usage records,
+ * does the actual cost land at or below the predicted P80 about 80% of the
+ * time? Re-exported from `llm-cost-attribution`, which owns the coverage
+ * backtester. This is the supported calibration API and the replacement for the
+ * never-shipped `calibrate` placeholder below.
+ *
+ * Signature: `calibrateCoverage(records, options?)`.
+ */
+export { calibrateCoverage } from 'llm-cost-attribution';
 
 /**
- * Build or update a calibration dataset from a set of completed issues whose
- * actual cost is known. Returns calibration parameters used by the forecast
- * functions.
+ * @deprecated Never implemented. The shipped calibration API is
+ * `calibrateCoverage` (re-exported above) — a held-out P80 coverage backtest
+ * over estimate-tagged usage records. This shim is retained only so old imports
+ * fail loudly with a pointer to the replacement instead of silently resolving
+ * to `undefined`.
  *
- * @param {object[]} completedIssues  Array of `{ identifier, estimate, actualCostUsd }`.
- * @param {object}   [options]
- * @returns {object}
+ * @returns {never}
  */
-export function calibrate(completedIssues, options = {}) {
-  throw new Error('not implemented');
+export function calibrate() {
+  throw new Error(
+    'calibrate() was never implemented and is not part of the public API; ' +
+      'use calibrateCoverage() instead.',
+  );
 }

packages/llm-cost-estimation/test/smoke.test.mjs

@@ -4,13 +4,16 @@ import {
   enrichUsageWithEstimate,
   forecastIssueCost,
   forecastProjectCost,
+  calibrateCoverage,
   calibrate,
   createLinearEstimateSource,
 } from '../src/index.mjs';
 
 // `enrichUsageWithEstimate` (GRV-2) and `forecastIssueCost` (GRV-3 + GRV-5 +
-// GRV-8 wiring) are implemented; `forecastProjectCost` (GRV-6) and `calibrate`
-// (planned) are still stubs.
+// GRV-8 wiring) ship from this barrel; `forecastProjectCost` and
+// `calibrateCoverage` are re-exported from the implemented attribution
+// forecasters. The bare `calibrate` name is a deprecated shim that names its
+// replacement.
 describe('llm-cost-estimation barrel', () => {
   it('forecastIssueCost returns the documented shape on an empty source', async () => {
     const forecast = await forecastIssueCost({ size: 'L', model: 'claude-sonnet-4-6' }, []);
@@ -23,6 +26,18 @@ describe('llm-cost-estimation barrel', () => {
     assert.equal(typeof forecast.quotaReason, 'string');
   });
 
+  it('forecastProjectCost forecasts an empty project over no history', async () => {
+    const forecast = await forecastProjectCost(
+      [{ size: 'L', model: 'claude-sonnet-4-6' }],
+      [],
+    );
+    assert.equal(forecast.empty, true);
+    assert.equal(forecast.lowConfidence, true);
+    assert.equal(forecast.issues, 1);
+    assert.equal(forecast.tokens.p50, null);
+    assert.equal(forecast.dollars.priced, false);
+  });
+
   it('enrichUsageWithEstimate is exported from the barrel', () => {
     assert.equal(typeof enrichUsageWithEstimate, 'function');
   });
@@ -31,11 +46,11 @@ describe('llm-cost-estimation barrel', () => {
     assert.equal(typeof createLinearEstimateSource, 'function');
   });
 
-  it('forecastProjectCost throws "not implemented"', async () => {
-    await assert.rejects(() => forecastProjectCost('proj-1', []), /not implemented/);
+  it('calibrateCoverage is exported from the barrel', () => {
+    assert.equal(typeof calibrateCoverage, 'function');
   });
 
-  it('calibrate throws "not implemented"', () => {
-    assert.throws(() => calibrate([]), /not implemented/);
+  it('calibrate is a deprecated shim whose error names calibrateCoverage', () => {
+    assert.throws(() => calibrate([]), /calibrateCoverage/);
   });
 });