@centerforagenticai/pi-multi-account 0.1.1

package/src/cost-report-json.ts

@@ -0,0 +1,318 @@
+import type {
+	CostReport,
+	CostReportApiEquivalent,
+	CostReportPeriod,
+	SubsidizationPoint,
+	SubsidizationSeries,
+} from "./cost-report.js";
+import type { PeriodType } from "./period-boundaries.js";
+
+/**
+ * Bump on any breaking field change to {@link CostReportJson}. A consumer
+ * (the standalone `cost --format json` command, or any other JSON reader of
+ * this pure projection) reads this before trusting the document's shape.
+ */
+export const COST_REPORT_JSON_SCHEMA_VERSION = 1;
+
+/**
+ * The requested-scope summary carried at the top of {@link CostReportJson},
+ * mirroring the text renderer's leading block: the saved Pi model-price
+ * estimate and the independently calculated API-equivalent estimate are
+ * always both present and separately labeled, even when their amounts match.
+ * `note` explains that relationship in prose for a human reading raw JSON;
+ * neither `money` field is ever combined into one spend total, and neither is
+ * an actual provider bill, payment, refund, tax record, or bank charge -- see
+ * {@link CostReportJson.limitations}.
+ */
+export interface CostReportJsonSummary {
+	readonly scope: {
+		readonly periodType: PeriodType;
+		readonly startMs: number;
+		readonly endMs: number;
+		readonly throughMs: number;
+		readonly completed: boolean;
+		readonly coverage: CostReportPeriod["coverage"];
+	};
+	readonly money: {
+		/** Pi's own saved per-response cost for the requested scope, unchanged from `current.retainedCostUsd`. */
+		readonly piModelPriceEstimateUsd: number;
+		/** The independently calculated, tier-aware estimate for the requested scope, unchanged from `current.apiEquivalent`. */
+		readonly apiEquivalentEstimate: CostReportApiEquivalent;
+	};
+	readonly note: string;
+}
+
+/** When this document was generated, and which pricing snapshot instants its API-equivalent estimates were computed against. */
+export interface CostReportJsonProvenance {
+	readonly generatedAtMs: number;
+	readonly generatedAt: string;
+	readonly pricingSnapshotAtMs: readonly number[];
+}
+
+/** The `"priced"` member of {@link SubsidizationPoint}, isolated so {@link CostReportJsonSubsidizationPoint} can override just its `coverage` field. */
+type PricedSubsidizationPoint = Extract<SubsidizationPoint, { readonly status: "priced" }>;
+
+/**
+ * The legacy subsidization point as serialized for `--format json`.
+ * Identical to {@link SubsidizationPoint} -- plus an explicit
+ * `comparisonSuppressed: false` -- when `status` is not `"priced"` or
+ * `coverage` is `"complete"`. When `status` is `"priced"` and `coverage` is
+ * `"partial"` or `"unknown"`, `ratio` and `deltaFromPrevious` are withheld:
+ * the underlying retained data or its completeness classification cannot
+ * support a definitive comparison for that window, so `comparisonSuppressed`
+ * is `true` and `suppressedReason` names why. `apiEquivalentEstimateUsd` and
+ * `apportionedSubscriptionUsd` -- the two figures a shown ratio would have
+ * divided -- are always still present either way. This withholds only the
+ * ratio itself, never a value {@link SubsidizationPoint} did not already
+ * carry: `buildCostReport` and `SubsidizationPoint` itself are unchanged.
+ */
+export type CostReportJsonSubsidizationPoint =
+	| ((
+			| Extract<SubsidizationPoint, { readonly status: "gap" }>
+			| Extract<SubsidizationPoint, { readonly status: "unpriced" }>
+			| (Omit<PricedSubsidizationPoint, "coverage"> & { readonly coverage: "complete" })
+	  ) & { readonly comparisonSuppressed: false })
+	| {
+			readonly periodStartMs: number;
+			readonly periodEndMs: number;
+			readonly status: "priced";
+			readonly coverage: "partial" | "unknown";
+			readonly apiEquivalentEstimateUsd: number;
+			readonly apportionedSubscriptionUsd: number;
+			readonly comparisonSuppressed: true;
+			readonly suppressedReason: string;
+	  };
+
+/** {@link SubsidizationSeries}, with every point run through {@link CostReportJsonSubsidizationPoint}'s ratio-suppression rule. */
+export interface CostReportJsonSubsidizationSeries {
+	readonly canonicalAccountId: string;
+	readonly monthlySubscriptionUsd: number;
+	readonly observedPeriods: number;
+	readonly completed: readonly CostReportJsonSubsidizationPoint[];
+	readonly current?: CostReportJsonSubsidizationPoint;
+}
+
+/**
+ * One versioned, documented JSON value for the pure `CostReport` projection.
+ * Every money, coverage, scope, and comparison field is a direct, unrenamed
+ * view of {@link CostReport} -- `current`, `completed`, `accountValue`, and
+ * `legacyUnattributed` are the exact same typed values `buildCostReport`
+ * produces, reorganized under one schema-versioned wrapper plus a
+ * requested-scope `summary` and a `limitations` list. `subsidization` is the
+ * one exception: it is the same points with a bare ratio withheld under
+ * incomplete coverage (see {@link CostReportJsonSubsidizationPoint}), a
+ * serialization decision, not a second computed value. Otherwise this is a
+ * serialization and documentation surface, never a second computed report
+ * type: it introduces no value this module did not already receive from
+ * `CostReport`.
+ */
+export interface CostReportJson {
+	readonly schemaVersion: typeof COST_REPORT_JSON_SCHEMA_VERSION;
+	readonly provenance: CostReportJsonProvenance;
+	readonly summary: CostReportJsonSummary;
+	readonly current: CostReportPeriod;
+	readonly completed: CostReport["completed"];
+	readonly accountValue: NonNullable<CostReport["accountValue"]>;
+	readonly subsidization: readonly CostReportJsonSubsidizationSeries[];
+	readonly legacyUnattributed: CostReport["legacyUnattributed"];
+	readonly limitations: readonly string[];
+}
+
+/**
+ * Reuses the spec's own approved billing-claim boundary language verbatim so
+ * the JSON document and the product description never drift: neither
+ * estimate is an actual provider charge, the recorded rate and allocated
+ * account cost are not an invoice/payment/refund/tax record/bank charge, and
+ * comparisons never claim a real subsidy, saving, or provider revenue.
+ */
+const BASE_LIMITATION =
+	"Neither the Pi model-price estimate nor the API-equivalent estimate is an actual provider charge. The recorded account rate and allocated account cost are not an invoice, payment, refund, tax record, or bank charge. Differences, ratios, and value multiples compare report values only and do not claim an actual subsidy, saving, provider revenue, or private-contract economics.";
+
+function sortedUniqueNumbers(values: readonly number[]): readonly number[] {
+	return [...new Set(values)].sort((left, right) => left - right);
+}
+
+function pricingSnapshotAtMs(report: CostReport): readonly number[] {
+	return sortedUniqueNumbers([
+		...report.current.apiEquivalent.rateAsOfMs,
+		...report.completed.flatMap((period) => period.apiEquivalent.rateAsOfMs),
+	]);
+}
+
+function summaryNote(current: CostReportPeriod): string {
+	const lead =
+		"The saved Pi model-price estimate and the independently calculated API-equivalent estimate are reported separately below.";
+	if (current.apiEquivalent.status !== "priced") {
+		return `${lead} The API-equivalent estimate is currently unpriced for this scope.`;
+	}
+	return current.apiEquivalent.estimatedUsd === current.retainedCostUsd
+		? `${lead} They happen to match for this window; they remain two independently produced figures.`
+		: lead;
+}
+
+/**
+ * Serializes one legacy subsidization point, withholding `ratio` and
+ * `deltaFromPrevious` when `status` is `"priced"` and `coverage` is not
+ * `"complete"`. See {@link CostReportJsonSubsidizationPoint}.
+ *
+ * `deltaFromPrevious` (cost-report.ts's `withConsecutiveDeltas`) is a
+ * difference of two ratios, so even when this point's own `coverage` is
+ * `"complete"` the delta is only as reliable as `previous` -- the
+ * immediately preceding point in the same `completed` array, never an
+ * earlier complete point reached by bridging a gap. When `previous` is
+ * missing or not itself a `"priced"`/`"complete"` point, `deltaFromPrevious`
+ * is omitted from the output rather than spread through and labeled
+ * `comparisonSuppressed: false`; `ratio` and every other field of this
+ * point remain valid and present.
+ */
+function toJsonSubsidizationPoint(
+	point: SubsidizationPoint,
+	previous?: SubsidizationPoint,
+): CostReportJsonSubsidizationPoint {
+	if (point.status === "gap") {
+		return { ...point, status: point.status, comparisonSuppressed: false };
+	}
+	if (point.status === "unpriced") {
+		return { ...point, status: point.status, comparisonSuppressed: false };
+	}
+	if (point.coverage === "complete") {
+		const deltaBasisComplete =
+			previous !== undefined && previous.status === "priced" && previous.coverage === "complete";
+		if (deltaBasisComplete || point.deltaFromPrevious === undefined) {
+			return { ...point, coverage: point.coverage, comparisonSuppressed: false };
+		}
+		const { deltaFromPrevious: _omittedDelta, ...pointWithoutDelta } = point;
+		return { ...pointWithoutDelta, coverage: point.coverage, comparisonSuppressed: false };
+	}
+	return {
+		periodStartMs: point.periodStartMs,
+		periodEndMs: point.periodEndMs,
+		status: "priced",
+		coverage: point.coverage,
+		apiEquivalentEstimateUsd: point.apiEquivalentEstimateUsd,
+		apportionedSubscriptionUsd: point.apportionedSubscriptionUsd,
+		comparisonSuppressed: true,
+		suppressedReason: `legacy-subsidization-${point.coverage}-coverage`,
+	};
+}
+
+function toJsonSubsidizationSeries(
+	series: SubsidizationSeries,
+): CostReportJsonSubsidizationSeries {
+	return {
+		canonicalAccountId: series.canonicalAccountId,
+		monthlySubscriptionUsd: series.monthlySubscriptionUsd,
+		observedPeriods: series.observedPeriods,
+		completed: series.completed.map((point, index) =>
+			toJsonSubsidizationPoint(point, series.completed[index - 1]),
+		),
+		...(series.current === undefined
+			? {}
+			: { current: toJsonSubsidizationPoint(series.current) }),
+	};
+}
+
+/** One line disclosing that the legacy subsidization ratio is withheld for one or more periods whose coverage is not complete -- never left to a header disclaimer alone. */
+function subsidizationSuppressionLimitations(report: CostReport): readonly string[] {
+	const hasSuppressedPoint = report.subsidization.some((series) =>
+		[series.current, ...series.completed].some(
+			(point) => point !== undefined && point.status === "priced" && point.coverage !== "complete",
+		),
+	);
+	return hasSuppressedPoint
+		? [
+				"Legacy subsidization comparison is withheld for one or more periods whose coverage is not complete; their apportioned subscription and API-equivalent estimate remain reported without a ratio.",
+			]
+		: [];
+}
+
+/** One line per account-level limitation already disclosed by `CostReport` itself: a suppressed or conditional comparison, or unknown allocation coverage. */
+function accountValueLimitations(report: CostReport): readonly string[] {
+	const limitations: string[] = [];
+	for (const entry of report.accountValue ?? []) {
+		if (entry.comparison.status === "suppressed") {
+			limitations.push(
+				`${entry.canonicalAccountId}: comparison suppressed (${entry.comparison.reason}).`,
+			);
+		} else if (entry.comparison.status === "conditional-lower-bound") {
+			limitations.push(
+				`${entry.canonicalAccountId}: comparison is a conditional lower bound (${entry.comparison.premise}).`,
+			);
+		}
+		if (entry.allocationHasUnknownCoverage) {
+			limitations.push(
+				`${entry.canonicalAccountId}: allocated account cost has unknown coverage for part of this window.`,
+			);
+		}
+	}
+	return limitations;
+}
+
+function buildLimitations(report: CostReport): readonly string[] {
+	const limitations: string[] = [BASE_LIMITATION];
+	if (report.current.coverage !== "complete") {
+		limitations.push(
+			`Requested-scope coverage is "${report.current.coverage}": part or all of the requested window has no immutable retained data.`,
+		);
+	}
+	limitations.push(...accountValueLimitations(report));
+	if (report.legacyUnattributed.length > 0) {
+		limitations.push(
+			"Legacy unattributed retained cost exists for responses saved without a project key.",
+		);
+	}
+	if (report.subsidization.length > 0) {
+		limitations.push(
+			"Subsidization figures use the legacy flat monthly-subscription value, superseded by recorded account rate for new comparisons.",
+		);
+		limitations.push(...subsidizationSuppressionLimitations(report));
+	}
+	return limitations;
+}
+
+/**
+ * Builds the documented {@link CostReportJson} value for `report`. Pure: no
+ * I/O, no clock read, no mutation, and no field not already present on
+ * `report` itself.
+ */
+export function buildCostReportJson(report: CostReport): CostReportJson {
+	const current = report.current;
+	return {
+		schemaVersion: COST_REPORT_JSON_SCHEMA_VERSION,
+		provenance: {
+			generatedAtMs: report.generatedAtMs,
+			generatedAt: new Date(report.generatedAtMs).toISOString(),
+			pricingSnapshotAtMs: pricingSnapshotAtMs(report),
+		},
+		summary: {
+			scope: {
+				periodType: report.periodType,
+				startMs: current.periodStartMs,
+				endMs: current.periodEndMs,
+				throughMs: current.throughMs,
+				completed: current.completed,
+				coverage: current.coverage,
+			},
+			money: {
+				piModelPriceEstimateUsd: current.retainedCostUsd,
+				apiEquivalentEstimate: current.apiEquivalent,
+			},
+			note: summaryNote(current),
+		},
+		current,
+		completed: report.completed,
+		accountValue: report.accountValue ?? [],
+		subsidization: report.subsidization.map(toJsonSubsidizationSeries),
+		legacyUnattributed: report.legacyUnattributed,
+		limitations: buildLimitations(report),
+	};
+}
+
+/**
+ * Renders `report` as one versioned JSON document with no surrounding prose,
+ * for the standalone report's `--format json` output (wired by a later
+ * node).
+ */
+export function renderCostReportJson(report: CostReport): string {
+	return JSON.stringify(buildCostReportJson(report), null, 2);
+}

package/src/cost-report-reader.ts

@@ -0,0 +1,368 @@
+import type { AccountRateRecord } from "./account-rate-history.js";
+import type { PiCatalogSnapshot } from "./api-pricing.js";
+import { isAllowedFamily, type MultiAccountConfig } from "./config.js";
+import {
+	classifyProviderId,
+	isProviderSlotWithinAccountLimit,
+} from "./discovery.js";
+import {
+	defaultCostDigestPaths,
+	CostDigestStore,
+} from "./cost-digest-store.js";
+import {
+	summarizeCostHistoryForReport,
+	type CostDigestRow,
+} from "./cost-digest.js";
+import { buildCostReport, type CostReport } from "./cost-report.js";
+import { iterateHistory } from "./history-store.js";
+import { getPeriodBounds, PERIOD_TYPES, type PeriodType } from "./period-boundaries.js";
+import {
+	defaultPricingCachePaths,
+	OpenRouterPricingCache,
+} from "./pricing-cache.js";
+import {
+	resolveCustomRange,
+	type GranularitySegment,
+	type RetainedGranularity,
+} from "./report-range.js";
+
+/**
+ * A request for the six existing calendar periods (a bare {@link PeriodType},
+ * always UTC and byte-identical to the existing slash/tool compatibility
+ * path), the same six periods with an explicit report timezone (the
+ * `"period"` kind), an exact custom range described by raw `--from`/`--to`-
+ * shaped bounds (see {@link resolveCustomRange}), or all available retained
+ * history. A `"period"` request dispatches directly to
+ * {@link buildCostReport}'s existing `periodType`/`timeZone` bounds path --
+ * never through `"custom"` -- so a non-UTC named period keeps its correct
+ * zoned calendar bounds and "current unfinished period" semantics (a
+ * populated `completed` series, a still-open `current` period) instead of
+ * collapsing to a single exact-bounds custom window. The reader resolves a
+ * `"custom"` request's raw bounds and satisfiability against the real
+ * retained store itself, exactly as {@link resolveCustomRange} and
+ * {@link assertRangeSatisfiable} are documented to be used.
+ */
+export type CostReportRangeRequest =
+	| PeriodType
+	| {
+			readonly kind: "period";
+			readonly periodType: PeriodType;
+			readonly timeZone?: string;
+	  }
+	| {
+			readonly kind: "custom";
+			readonly fromRaw: string;
+			readonly toRaw: string;
+			readonly timeZone?: string;
+	  }
+	| { readonly kind: "all-history" };
+
+/**
+ * Thrown when a `"custom"` {@link CostReportRangeRequest} fails syntax
+ * validation or the retained store cannot satisfy its requested precision.
+ * `exitCode` mirrors {@link ReportRangeResult}'s own stable exit codes (2 for
+ * invalid syntax, 3 for unsatisfiable precision) so a later CLI layer can map
+ * this exception onto its own process exit without re-deriving the reason.
+ */
+export class CostReportRangeRequestError extends Error {
+	readonly exitCode: 2 | 3;
+	constructor(exitCode: 2 | 3, reason: string) {
+		super(reason);
+		this.name = "CostReportRangeRequestError";
+		this.exitCode = exitCode;
+	}
+}
+
+export type CostReportReader = (request: CostReportRangeRequest) => CostReport;
+
+/**
+ * Projects a live `monthlySubscriptionUsd` map to the subset within the current
+ * validated account limit.
+ *
+ * Each key is classified through `classifyProviderId()` and checked against
+ * `isProviderSlotWithinAccountLimit(slot, accountLimit)` before its price is
+ * copied. A key that does not classify or is above the current limit is dropped,
+ * so an in-range-for-maximum key above the current configured limit, or a
+ * hostile in-memory slot-33 key that bypassed config parsing, cannot activate a
+ * subscription-value series in the report. The result is frozen and retains no
+ * reference to the source object.
+ */
+export function projectMonthlySubscriptionUsdForReport(
+	monthlySubscriptionUsd: Readonly<Record<string, number>>,
+	accountLimit: number,
+): Readonly<Record<string, number>> {
+	const projected: Record<string, number> = {};
+	for (const [providerId, monthlyCost] of Object.entries(monthlySubscriptionUsd)) {
+		const slot = classifyProviderId({ providerId, credentialType: "unknown" });
+		if (
+			slot === null ||
+			!isProviderSlotWithinAccountLimit(slot, accountLimit) ||
+			// Subscription-only report sink: an owning-vendor-api `openai` cost key
+			// must not enter the subscription-subsidization report, mirroring the
+			// parseMonthlySubscriptionUsd config guard.
+			!isAllowedFamily(slot.family)
+		) {
+			continue;
+		}
+		projected[providerId] = monthlyCost;
+	}
+	return Object.freeze(projected);
+}
+
+/**
+ * Projects a live `accountRateHistory` map to the subset within the current
+ * validated account limit, mirroring {@link projectMonthlySubscriptionUsdForReport}.
+ * Each key is classified and checked against the same account-limit and
+ * allowed-family guards before its records are copied, so a hostile
+ * in-memory slot-33 key that bypassed config parsing cannot inject an
+ * out-of-range account rate into the report. The result is frozen and
+ * retains no reference to the source object.
+ */
+export function projectAccountRateHistoryForReport(
+	accountRateHistory: Readonly<Record<string, readonly AccountRateRecord[]>>,
+	accountLimit: number,
+): Readonly<Record<string, readonly AccountRateRecord[]>> {
+	const projected: Record<string, readonly AccountRateRecord[]> = {};
+	for (const [providerId, records] of Object.entries(accountRateHistory)) {
+		const slot = classifyProviderId({ providerId, credentialType: "unknown" });
+		if (
+			slot === null ||
+			!isProviderSlotWithinAccountLimit(slot, accountLimit) ||
+			!isAllowedFamily(slot.family)
+		) {
+			continue;
+		}
+		projected[providerId] = records;
+	}
+	return Object.freeze(projected);
+}
+
+const PERIOD_TYPE_RANK: ReadonlyMap<PeriodType, number> = new Map(
+	PERIOD_TYPES.map((periodType, index) => [periodType, index]),
+);
+
+/**
+ * Describes which granularity is actually retained across `[startMs, endMs)`,
+ * derived from real, already-closed digest rows plus the still-open current
+ * day's live per-response detail -- never from a fabricated or assumed
+ * grain. A stretch covered by no digest row and outside the still-open
+ * current day is a genuine coverage gap and is simply absent from the
+ * result: {@link assertRangeSatisfiable} in `report-range.ts` then correctly
+ * refuses to let a caller slice inside it, rather than this function
+ * guessing a granularity for time nothing was ever retained at.
+ *
+ * A closed digest row is retained forever once written (the digest store
+ * never deletes a child once a parent rollup exists), so an old day that was
+ * closed while its underlying raw per-response records were still fresh
+ * keeps reporting "day" granularity even long after those raw records
+ * expired from the separate, bounded-retention raw history log -- this
+ * function only reads the immutable digest rows and the live window, never
+ * the raw log's own retention state.
+ */
+export function deriveRetainedGranularitySegments(input: {
+	readonly digestRows: readonly CostDigestRow[];
+	/** The start of the still-open current day, or `undefined` when no live window applies. */
+	readonly liveRawFromMs: number | undefined;
+	readonly nowMs: number;
+}): readonly GranularitySegment[] {
+	const boundaries = new Set<number>();
+	for (const row of input.digestRows) {
+		boundaries.add(row.periodStartMs);
+		boundaries.add(row.periodEndMs);
+	}
+	if (input.liveRawFromMs !== undefined) {
+		boundaries.add(input.liveRawFromMs);
+		boundaries.add(input.nowMs);
+	}
+	const sorted = [...boundaries].sort((left, right) => left - right);
+	const raw: Array<{
+		readonly startMs: number;
+		readonly endMs: number;
+		readonly granularity: RetainedGranularity;
+	}> = [];
+	for (let index = 0; index < sorted.length - 1; index += 1) {
+		const segStart = sorted[index]!;
+		const segEnd = sorted[index + 1]!;
+		if (segEnd <= segStart) continue;
+		if (
+			input.liveRawFromMs !== undefined &&
+			segStart >= input.liveRawFromMs &&
+			segEnd <= input.nowMs
+		) {
+			raw.push({ startMs: segStart, endMs: segEnd, granularity: "raw" });
+			continue;
+		}
+		let finestRank: number | undefined;
+		for (const row of input.digestRows) {
+			if (row.periodStartMs > segStart || row.periodEndMs < segEnd) continue;
+			const rank = PERIOD_TYPE_RANK.get(row.periodType);
+			if (rank !== undefined && (finestRank === undefined || rank < finestRank)) {
+				finestRank = rank;
+			}
+		}
+		if (finestRank !== undefined) {
+			raw.push({
+				startMs: segStart,
+				endMs: segEnd,
+				granularity: PERIOD_TYPES[finestRank]!,
+			});
+		}
+	}
+	const merged: GranularitySegment[] = [];
+	for (const segment of raw) {
+		const previous = merged[merged.length - 1];
+		if (
+			previous !== undefined &&
+			previous.granularity === segment.granularity &&
+			previous.endMs === segment.startMs
+		) {
+			merged[merged.length - 1] = { ...previous, endMs: segment.endMs };
+		} else {
+			merged.push(segment);
+		}
+	}
+	return merged;
+}
+
+export type RetainedHistoryCoverageReader = () => readonly GranularitySegment[];
+
+/**
+ * Bind {@link deriveRetainedGranularitySegments} to the current Pi agent
+ * directory's real, immutable digest store -- the "all available history"
+ * read path. Performs no network request and writes nothing.
+ */
+export function createDefaultRetainedHistoryCoverageReader(options: {
+	readonly now?: () => number;
+}): RetainedHistoryCoverageReader {
+	const digestStore = new CostDigestStore({ path: defaultCostDigestPaths().path });
+	const now = options.now ?? Date.now;
+	return () => {
+		const nowMs = now();
+		const today = getPeriodBounds(nowMs, "day");
+		return deriveRetainedGranularitySegments({
+			digestRows: digestStore.read(),
+			liveRawFromMs: today.startMs,
+			nowMs,
+		});
+	};
+}
+
+/**
+ * Bind the read-only cost-report surfaces to the current Pi agent directory.
+ * The returned reader performs no network request and writes nothing; the
+ * machine-leased period closer is invoked separately before this reader.
+ */
+export function createDefaultCostReportReader(options: {
+	readonly config: () => Pick<
+		MultiAccountConfig,
+		"accountLimit" | "projectLabels" | "monthlySubscriptionUsd" | "accountRateHistory"
+	>;
+	readonly now?: () => number;
+	/**
+	 * Supplies Pi's installed model catalog cost data for per-response
+	 * tier-aware pricing (see `api-pricing.ts`). This adapter never fetches or
+	 * derives that snapshot itself; when omitted, the read path prices
+	 * responses only from the retained OpenRouter rate snapshot, exactly as it
+	 * did before per-response tier pricing existed.
+	 */
+	readonly piCatalog?: () => PiCatalogSnapshot | undefined;
+}): CostReportReader {
+	const digestStore = new CostDigestStore({ path: defaultCostDigestPaths().path });
+	const pricingCache = new OpenRouterPricingCache({
+		...defaultPricingCachePaths(),
+		...(options.now === undefined ? {} : { now: options.now }),
+	});
+	const now = options.now ?? Date.now;
+	// The same "all available history" read path a caller can bind directly
+	// (see `createDefaultRetainedHistoryCoverageReader`'s own doc comment):
+	// reused here so a "custom" request's satisfiability is checked against
+	// the real retained store, never a caller-asserted or absent set of
+	// segments.
+	const coverageReader = createDefaultRetainedHistoryCoverageReader(
+		options.now === undefined ? {} : { now: options.now },
+	);
+	return (request) => {
+		const nowMs = now();
+		const pricing = pricingCache.readStatus();
+		const piCatalog = options.piCatalog?.();
+		const history = summarizeCostHistoryForReport(
+			iterateHistory("cost-delta"),
+			nowMs,
+			pricing,
+			piCatalog,
+		);
+		const config = options.config();
+		const baseInput = {
+			digestRows: digestStore.read(),
+			// Only today's still-open window has per-response raw detail left to
+			// filter by; a resolved sub-day-precise range clipped inside today
+			// (see `provisionalCurrentDayRows` in `cost-report.ts`) rebuilds its
+			// provisional row from these instead of slicing the pre-aggregated
+			// `currentDayDigestRows` below, which has no per-observation
+			// timestamps left once summed.
+			observations: history.currentDayObservations,
+			gaps: history.currentDayGaps,
+			currentDayDigestRows: history.currentDayRows,
+			...(history.earliestAttributedObservedAtMs === undefined
+				? {}
+				: {
+						earliestRawObservationAtMs:
+							history.earliestAttributedObservedAtMs,
+					}),
+			rawAccountIds: history.accountIds,
+			groupedLegacyUnattributed: history.legacyUnattributed,
+			pricing,
+			nowMs,
+			projectLabels: config.projectLabels,
+			monthlySubscriptionUsd: projectMonthlySubscriptionUsdForReport(
+				config.monthlySubscriptionUsd,
+				config.accountLimit,
+			),
+			accountRateHistory: projectAccountRateHistoryForReport(
+				config.accountRateHistory ?? {},
+				config.accountLimit,
+			),
+		} as const;
+
+		if (typeof request === "string") {
+			return buildCostReport({ ...baseInput, periodType: request });
+		}
+		if (request.kind === "period") {
+			return buildCostReport({
+				...baseInput,
+				periodType: request.periodType,
+				...(request.timeZone === undefined ? {} : { timeZone: request.timeZone }),
+			});
+		}
+		// `periodType` below is a nominal placeholder for both branches: neither
+		// `buildCostReport`'s `"custom"` nor `"all-history"` range mode reads it
+		// for bounds (see `BuildCostReportInput.range`); it only keeps
+		// `CostReport.periodType`'s existing required shape until a later node
+		// gives a range-mode report its own dedicated label.
+		if (request.kind === "custom") {
+			const resolved = resolveCustomRange({
+				fromRaw: request.fromRaw,
+				toRaw: request.toRaw,
+				...(request.timeZone === undefined ? {} : { timeZone: request.timeZone }),
+				retainedGranularity: coverageReader(),
+			});
+			if (resolved.status !== "resolved") {
+				throw new CostReportRangeRequestError(resolved.exitCode, resolved.reason);
+			}
+			return buildCostReport({
+				...baseInput,
+				periodType: "day",
+				range: {
+					kind: "custom",
+					startMs: resolved.startMs,
+					endMs: resolved.endMs,
+				},
+			});
+		}
+		return buildCostReport({
+			...baseInput,
+			periodType: "day",
+			range: { kind: "all-history" },
+		});
+	};
+}