niceeval 0.12.2-canary.31 → 0.13.0

package/dist/analysis/cost.d.mts

@@ -0,0 +1,310 @@
+import { type LogicalSlot, type Measure } from "./definitions.mjs";
+import type { MetricValue } from "./contracts.mjs";
+import type { CanonicalDecimal, CurrencyCode, SafeIdentifier } from "../o11y/record/model.mjs";
+import type { ExecutionIdentityDigest, UtcMillis } from "../record/model/identifiers.mjs";
+import { type IndependentlyBillableTokenBucket } from "./cost-decimal.mjs";
+/** Cross-ESM/CJS v1 Profile descriptor. Its value is a frozen data record. */
+declare const PricingProfileDescriptor: unique symbol;
+/** Cross-ESM/CJS v1 profile-bound Measure descriptor. */
+declare const CostMeasureDescriptor: unique symbol;
+declare const pricingProfileContentIdentityTypeId: unique symbol;
+declare const pricingCoverageIdTypeId: unique symbol;
+export type PricingProfileContentIdentity = string & {
+    readonly [pricingProfileContentIdentityTypeId]: true;
+};
+export type PricingCoverageId = string & {
+    readonly [pricingCoverageIdTypeId]: true;
+};
+export interface PricingDisplay {
+    readonly decimalPlaces: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+    readonly rounding: "half-away-from-zero";
+}
+export interface PricingDisplayInput {
+    readonly decimalPlaces: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+    readonly rounding: "half-away-from-zero";
+}
+/** The declaration that made this rate card auditable. */
+export interface PricingProvenance {
+    readonly kind: "declared-rate-card";
+    readonly source: string;
+    readonly asOf: UtcMillis;
+}
+export interface PricingProvenanceInput {
+    readonly kind: "declared-rate-card";
+    readonly source: string;
+    readonly asOf: number;
+}
+/**
+ * Every selector predicate reads the origin Attempt's closed Core projection.
+ * Optional dimensions are explicit wildcards; model is required and never
+ * inferred from current Report source, the selected target Run, or a provider.
+ */
+export interface PricingSelector {
+    /** Omitted only by a model catalog entry whose quote is provider-neutral. */
+    readonly provider?: SafeIdentifier;
+    readonly model: string;
+    readonly agentId?: string;
+    readonly reasoningEffort?: string | null;
+    readonly executionIdentityDigest?: ExecutionIdentityDigest;
+}
+export interface PricingSelectorInput {
+    readonly provider?: string;
+    readonly model: string;
+    readonly agentId?: string;
+    readonly reasoningEffort?: string | null;
+    readonly executionIdentityDigest?: string;
+}
+export interface PricingEffectiveCondition {
+    readonly startsAt: UtcMillis;
+    readonly endsAt: UtcMillis | null;
+}
+export interface PricingEffectiveConditionInput {
+    readonly startsAt: number;
+    readonly endsAt: number | null;
+}
+export interface TokenPricingCharge {
+    readonly kind: "token";
+    readonly bucket: IndependentlyBillableTokenBucket;
+    readonly perMillionTokens: CanonicalDecimal;
+}
+export interface TokenPricingChargeInput {
+    readonly kind: "token";
+    readonly bucket: string;
+    readonly perMillionTokens: string;
+}
+export interface RequestPricingCharge {
+    readonly kind: "request";
+    readonly requestKind: "model" | "tool";
+    readonly ratePerRequest: CanonicalDecimal;
+}
+export interface RequestPricingChargeInput {
+    readonly kind: "request";
+    readonly requestKind: "model" | "tool";
+    readonly ratePerRequest: string;
+}
+export type PricingCharge = TokenPricingCharge | RequestPricingCharge;
+export type PricingChargeInput = TokenPricingChargeInput | RequestPricingChargeInput;
+interface PricingCoverageBase {
+    readonly coverageId: PricingCoverageId;
+    readonly selector: PricingSelector;
+    readonly effective: PricingEffectiveCondition;
+}
+export interface PricedCoverage extends PricingCoverageBase {
+    readonly state: "priced";
+    readonly charges: readonly [PricingCharge, ...PricingCharge[]];
+}
+export interface UnpricedCoverage extends PricingCoverageBase {
+    readonly state: "unpriced";
+    readonly reason: "provider-not-priced" | "billing-mode-not-priced" | "rate-not-published";
+}
+export type PricingCoverage = PricedCoverage | UnpricedCoverage;
+export interface PricedCoverageInput {
+    readonly coverageId: string;
+    readonly state: "priced";
+    readonly selector: PricingSelectorInput;
+    readonly effective: PricingEffectiveConditionInput;
+    readonly charges: readonly [PricingChargeInput, ...PricingChargeInput[]];
+}
+export interface UnpricedCoverageInput {
+    readonly coverageId: string;
+    readonly state: "unpriced";
+    readonly selector: PricingSelectorInput;
+    readonly effective: PricingEffectiveConditionInput;
+    readonly reason: "provider-not-priced" | "billing-mode-not-priced" | "rate-not-published";
+}
+export type PricingCoverageInput = PricedCoverageInput | UnpricedCoverageInput;
+interface PricingProfileCanonicalContent {
+    readonly version: 1;
+    readonly currency: "USD";
+    readonly display: PricingDisplay;
+    readonly provenance: PricingProvenance;
+    readonly coverage: readonly PricingCoverage[];
+}
+interface PricingProfileDescriptorValue {
+    readonly version: 1;
+    readonly contentIdentity: PricingProfileContentIdentity;
+    readonly content: PricingProfileCanonicalContent;
+}
+/**
+ * v1 profile data is direct and data-only. The global Symbol descriptor lets
+ * another ESM/CJS instance revalidate the exact same frozen canonical value.
+ */
+export interface PricingProfile {
+    readonly contentIdentity: PricingProfileContentIdentity;
+    readonly currency: "USD";
+    readonly display: PricingDisplay;
+    readonly provenance: PricingProvenance;
+    readonly coverage: readonly PricingCoverage[];
+    readonly [PricingProfileDescriptor]: PricingProfileDescriptorValue;
+}
+export interface PricingProfileInput {
+    readonly currency: "USD";
+    readonly display: PricingDisplayInput;
+    readonly provenance: PricingProvenanceInput;
+    readonly coverage: readonly PricingCoverageInput[];
+}
+export type CostProjectionState = "available" | "partial" | "unavailable";
+export type CostBasis = "observed" | "estimated" | "mixed" | "unavailable";
+export interface ProjectedMoney {
+    readonly amount: CanonicalDecimal;
+    readonly currency: CurrencyCode;
+    readonly decimalPlaces: number;
+}
+/** Closed, auditable profile facts without a source object or calculator. */
+export interface CostProjectionProfile {
+    readonly contentIdentity: PricingProfileContentIdentity;
+    readonly currency: CurrencyCode;
+    readonly display: PricingDisplay;
+    readonly provenance: PricingProvenance;
+    readonly coverage: readonly PricingCoverage[];
+}
+export type CostCoverageReasonCode = "member-not-recorded" | "core-invalid" | "origin-run-unavailable" | "execution-model-not-recorded" | "usage-not-recorded" | "usage-unavailable" | "usage-unsupported" | "usage-invalid" | "usage-collection-partial" | "pricing-coverage-not-found" | "pricing-coverage-unpriced" | "pricing-charge-not-found" | "observed-cost-other-currency";
+export interface CostCoverageReason {
+    readonly slot: import("./contracts.mjs").AnalysisSlotRef;
+    readonly provider: SafeIdentifier | null;
+    readonly code: CostCoverageReasonCode;
+}
+export interface ObservedCostComponent {
+    readonly kind: "provider-cost";
+    readonly provider: SafeIdentifier;
+    readonly currency: CurrencyCode;
+    readonly amount: CanonicalDecimal;
+}
+export interface EstimatedTokenCostComponent {
+    readonly kind: "token";
+    readonly provider: SafeIdentifier;
+    readonly bucket: IndependentlyBillableTokenBucket;
+    readonly tokens: number;
+    readonly ratePerMillionTokens: CanonicalDecimal;
+    readonly amount: CanonicalDecimal;
+}
+export interface EstimatedRequestCostComponent {
+    readonly kind: "request";
+    readonly provider: SafeIdentifier;
+    readonly requestKind: "model" | "tool";
+    readonly ratePerRequest: CanonicalDecimal;
+    readonly amount: CanonicalDecimal;
+}
+export type CostComponent = ObservedCostComponent | EstimatedTokenCostComponent | EstimatedRequestCostComponent;
+export interface ObservedOtherCurrency {
+    readonly provider: SafeIdentifier;
+    readonly currency: CurrencyCode;
+    readonly amount: CanonicalDecimal;
+}
+/** One Slot/provider branch; observed and estimated facts never mix in it. */
+export type CostLedgerEntry = {
+    readonly slot: import("./contracts.mjs").AnalysisSlotRef;
+    readonly provider: SafeIdentifier | null;
+    readonly branch: "observed";
+    readonly components: readonly [ObservedCostComponent, ...ObservedCostComponent[]];
+    readonly estimated: null;
+} | {
+    readonly slot: import("./contracts.mjs").AnalysisSlotRef;
+    readonly provider: SafeIdentifier;
+    readonly branch: "estimated";
+    readonly components: readonly (EstimatedTokenCostComponent | EstimatedRequestCostComponent)[];
+    readonly estimated: ProjectedMoney;
+} | {
+    readonly slot: import("./contracts.mjs").AnalysisSlotRef;
+    readonly provider: SafeIdentifier | null;
+    readonly branch: "unavailable";
+    readonly components: readonly [];
+    readonly estimated: null;
+};
+/** Exact aggregation before any display / Number conversion. */
+export type CostProjectionAggregate = {
+    readonly kind: "mean";
+    /** Canonical USD subtotal before division or display rounding. */
+    readonly numerator: CanonicalDecimal;
+    /** Slots with a known quote-currency subtotal, never full denominator. */
+    readonly denominator: number;
+} | {
+    readonly kind: "total";
+    /** Canonical USD subtotal before display rounding. */
+    readonly total: CanonicalDecimal;
+};
+interface CostProjectionCommon {
+    readonly profile: CostProjectionProfile;
+    readonly aggregate: CostProjectionAggregate;
+    readonly observedOtherCurrencies: readonly ObservedOtherCurrency[];
+    readonly reasons: readonly CostCoverageReason[];
+    readonly ledger: readonly CostLedgerEntry[];
+}
+export interface CostProjectionKnown extends CostProjectionCommon {
+    readonly state: "available" | "partial";
+    readonly basis: Exclude<CostBasis, "unavailable">;
+    readonly observed: ProjectedMoney | null;
+    readonly estimated: ProjectedMoney | null;
+    readonly combined: ProjectedMoney;
+}
+export interface CostProjectionUnavailable extends CostProjectionCommon {
+    readonly state: "unavailable";
+    readonly basis: "unavailable";
+    readonly observed: null;
+    readonly estimated: null;
+    readonly combined: null;
+}
+export type CostProjectionValue = CostProjectionKnown | CostProjectionUnavailable;
+/** A normal MetricValue with a closed cost domain value attached. */
+export interface CostMetricValue extends MetricValue<number> {
+    readonly state: CostProjectionState;
+    readonly format: "currency-usd";
+    readonly better: "lower";
+    readonly projection: CostProjectionValue;
+}
+interface CostMeasureDescriptorValue {
+    readonly version: 1;
+    readonly mode: "mean" | "total";
+    readonly profile: PricingProfile;
+    readonly profileIdentity: PricingProfileContentIdentity;
+}
+/** A Measure whose data descriptor binds it to exactly one validated Profile. */
+export interface CostMeasure extends Measure<LogicalSlot, number> {
+    readonly [CostMeasureDescriptor]: CostMeasureDescriptorValue;
+}
+/** Defines, deeply freezes, canonically sorts, and content-addresses one USD Profile. */
+export declare function definePricingProfile(input: PricingProfileInput): PricingProfile;
+/**
+ * Identity-bearing Profile for NiceEval's complete vendored model catalog.
+ * Resolution matches an exact model identifier and does not infer a billing
+ * provider from an agent name. Missing models and buckets remain unpriced.
+ */
+export declare const builtInPricingProfile: PricingProfile;
+/** @internal Resolves one exact model from the catalog named by the built-in Profile. */
+export declare function builtInPricingCoverage(model: string): PricedCoverage | undefined;
+/** @internal
+ * Locally created or already revalidated Profiles use a WeakSet fast path.
+ * A value from another package graph must first pass the global Symbol data
+ * descriptor, recursive freezing, canonical content, and SHA-256 checks.
+ */
+export declare function isPricingProfile(value: unknown): value is PricingProfile;
+/**
+ * @internal Validates one already-closed cost projection without rebuilding a
+ * price, a ledger, or a numeric result. Report imports this internal guard so
+ * every deep cost-domain rule remains owned by Analysis.
+ */
+export declare function isCostProjectionValue(value: unknown): value is CostProjectionValue;
+/** Mean known USD cost per logical Slot for exactly one Profile. */
+export declare function costUSD(profile: PricingProfile): CostMeasure;
+/** Total known USD cost across logical Slots for exactly one Profile. */
+export declare function totalCostUSD(profile: PricingProfile): CostMeasure;
+/** @internal Revalidates a local or external CostMeasure data descriptor. */
+export declare function costMeasureState(value: unknown): CostMeasureDescriptorValue | undefined;
+/** @internal A structural cross-instance guard; it never infers a Profile from `id`. */
+export declare function isCostMeasure(value: unknown): value is CostMeasure;
+/** @internal Closes only immutable profile data for renderer consumption. */
+export declare function closeCostProjectionProfile(profile: PricingProfile): CostProjectionProfile;
+/** @internal Tests immutable Attempt-origin Core facts against a Profile coverage. */
+export declare function pricingCoverageMatches(coverage: PricingCoverage, input: {
+    readonly provider: SafeIdentifier;
+    readonly origin: {
+        readonly startedAt: UtcMillis;
+        readonly executionIdentityDigest: ExecutionIdentityDigest;
+        readonly execution: {
+            readonly agentId: string;
+            readonly model: string | null;
+            readonly reasoningEffort: string | null;
+        };
+    };
+}): boolean;
+export {};

package/dist/analysis/cost.d.ts

@@ -0,0 +1,310 @@
+import { type LogicalSlot, type Measure } from "./definitions.js";
+import type { MetricValue } from "./contracts.js";
+import type { CanonicalDecimal, CurrencyCode, SafeIdentifier } from "../o11y/record/model.js";
+import type { ExecutionIdentityDigest, UtcMillis } from "../record/model/identifiers.js";
+import { type IndependentlyBillableTokenBucket } from "./cost-decimal.js";
+/** Cross-ESM/CJS v1 Profile descriptor. Its value is a frozen data record. */
+declare const PricingProfileDescriptor: unique symbol;
+/** Cross-ESM/CJS v1 profile-bound Measure descriptor. */
+declare const CostMeasureDescriptor: unique symbol;
+declare const pricingProfileContentIdentityTypeId: unique symbol;
+declare const pricingCoverageIdTypeId: unique symbol;
+export type PricingProfileContentIdentity = string & {
+    readonly [pricingProfileContentIdentityTypeId]: true;
+};
+export type PricingCoverageId = string & {
+    readonly [pricingCoverageIdTypeId]: true;
+};
+export interface PricingDisplay {
+    readonly decimalPlaces: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+    readonly rounding: "half-away-from-zero";
+}
+export interface PricingDisplayInput {
+    readonly decimalPlaces: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+    readonly rounding: "half-away-from-zero";
+}
+/** The declaration that made this rate card auditable. */
+export interface PricingProvenance {
+    readonly kind: "declared-rate-card";
+    readonly source: string;
+    readonly asOf: UtcMillis;
+}
+export interface PricingProvenanceInput {
+    readonly kind: "declared-rate-card";
+    readonly source: string;
+    readonly asOf: number;
+}
+/**
+ * Every selector predicate reads the origin Attempt's closed Core projection.
+ * Optional dimensions are explicit wildcards; model is required and never
+ * inferred from current Report source, the selected target Run, or a provider.
+ */
+export interface PricingSelector {
+    /** Omitted only by a model catalog entry whose quote is provider-neutral. */
+    readonly provider?: SafeIdentifier;
+    readonly model: string;
+    readonly agentId?: string;
+    readonly reasoningEffort?: string | null;
+    readonly executionIdentityDigest?: ExecutionIdentityDigest;
+}
+export interface PricingSelectorInput {
+    readonly provider?: string;
+    readonly model: string;
+    readonly agentId?: string;
+    readonly reasoningEffort?: string | null;
+    readonly executionIdentityDigest?: string;
+}
+export interface PricingEffectiveCondition {
+    readonly startsAt: UtcMillis;
+    readonly endsAt: UtcMillis | null;
+}
+export interface PricingEffectiveConditionInput {
+    readonly startsAt: number;
+    readonly endsAt: number | null;
+}
+export interface TokenPricingCharge {
+    readonly kind: "token";
+    readonly bucket: IndependentlyBillableTokenBucket;
+    readonly perMillionTokens: CanonicalDecimal;
+}
+export interface TokenPricingChargeInput {
+    readonly kind: "token";
+    readonly bucket: string;
+    readonly perMillionTokens: string;
+}
+export interface RequestPricingCharge {
+    readonly kind: "request";
+    readonly requestKind: "model" | "tool";
+    readonly ratePerRequest: CanonicalDecimal;
+}
+export interface RequestPricingChargeInput {
+    readonly kind: "request";
+    readonly requestKind: "model" | "tool";
+    readonly ratePerRequest: string;
+}
+export type PricingCharge = TokenPricingCharge | RequestPricingCharge;
+export type PricingChargeInput = TokenPricingChargeInput | RequestPricingChargeInput;
+interface PricingCoverageBase {
+    readonly coverageId: PricingCoverageId;
+    readonly selector: PricingSelector;
+    readonly effective: PricingEffectiveCondition;
+}
+export interface PricedCoverage extends PricingCoverageBase {
+    readonly state: "priced";
+    readonly charges: readonly [PricingCharge, ...PricingCharge[]];
+}
+export interface UnpricedCoverage extends PricingCoverageBase {
+    readonly state: "unpriced";
+    readonly reason: "provider-not-priced" | "billing-mode-not-priced" | "rate-not-published";
+}
+export type PricingCoverage = PricedCoverage | UnpricedCoverage;
+export interface PricedCoverageInput {
+    readonly coverageId: string;
+    readonly state: "priced";
+    readonly selector: PricingSelectorInput;
+    readonly effective: PricingEffectiveConditionInput;
+    readonly charges: readonly [PricingChargeInput, ...PricingChargeInput[]];
+}
+export interface UnpricedCoverageInput {
+    readonly coverageId: string;
+    readonly state: "unpriced";
+    readonly selector: PricingSelectorInput;
+    readonly effective: PricingEffectiveConditionInput;
+    readonly reason: "provider-not-priced" | "billing-mode-not-priced" | "rate-not-published";
+}
+export type PricingCoverageInput = PricedCoverageInput | UnpricedCoverageInput;
+interface PricingProfileCanonicalContent {
+    readonly version: 1;
+    readonly currency: "USD";
+    readonly display: PricingDisplay;
+    readonly provenance: PricingProvenance;
+    readonly coverage: readonly PricingCoverage[];
+}
+interface PricingProfileDescriptorValue {
+    readonly version: 1;
+    readonly contentIdentity: PricingProfileContentIdentity;
+    readonly content: PricingProfileCanonicalContent;
+}
+/**
+ * v1 profile data is direct and data-only. The global Symbol descriptor lets
+ * another ESM/CJS instance revalidate the exact same frozen canonical value.
+ */
+export interface PricingProfile {
+    readonly contentIdentity: PricingProfileContentIdentity;
+    readonly currency: "USD";
+    readonly display: PricingDisplay;
+    readonly provenance: PricingProvenance;
+    readonly coverage: readonly PricingCoverage[];
+    readonly [PricingProfileDescriptor]: PricingProfileDescriptorValue;
+}
+export interface PricingProfileInput {
+    readonly currency: "USD";
+    readonly display: PricingDisplayInput;
+    readonly provenance: PricingProvenanceInput;
+    readonly coverage: readonly PricingCoverageInput[];
+}
+export type CostProjectionState = "available" | "partial" | "unavailable";
+export type CostBasis = "observed" | "estimated" | "mixed" | "unavailable";
+export interface ProjectedMoney {
+    readonly amount: CanonicalDecimal;
+    readonly currency: CurrencyCode;
+    readonly decimalPlaces: number;
+}
+/** Closed, auditable profile facts without a source object or calculator. */
+export interface CostProjectionProfile {
+    readonly contentIdentity: PricingProfileContentIdentity;
+    readonly currency: CurrencyCode;
+    readonly display: PricingDisplay;
+    readonly provenance: PricingProvenance;
+    readonly coverage: readonly PricingCoverage[];
+}
+export type CostCoverageReasonCode = "member-not-recorded" | "core-invalid" | "origin-run-unavailable" | "execution-model-not-recorded" | "usage-not-recorded" | "usage-unavailable" | "usage-unsupported" | "usage-invalid" | "usage-collection-partial" | "pricing-coverage-not-found" | "pricing-coverage-unpriced" | "pricing-charge-not-found" | "observed-cost-other-currency";
+export interface CostCoverageReason {
+    readonly slot: import("./contracts.js").AnalysisSlotRef;
+    readonly provider: SafeIdentifier | null;
+    readonly code: CostCoverageReasonCode;
+}
+export interface ObservedCostComponent {
+    readonly kind: "provider-cost";
+    readonly provider: SafeIdentifier;
+    readonly currency: CurrencyCode;
+    readonly amount: CanonicalDecimal;
+}
+export interface EstimatedTokenCostComponent {
+    readonly kind: "token";
+    readonly provider: SafeIdentifier;
+    readonly bucket: IndependentlyBillableTokenBucket;
+    readonly tokens: number;
+    readonly ratePerMillionTokens: CanonicalDecimal;
+    readonly amount: CanonicalDecimal;
+}
+export interface EstimatedRequestCostComponent {
+    readonly kind: "request";
+    readonly provider: SafeIdentifier;
+    readonly requestKind: "model" | "tool";
+    readonly ratePerRequest: CanonicalDecimal;
+    readonly amount: CanonicalDecimal;
+}
+export type CostComponent = ObservedCostComponent | EstimatedTokenCostComponent | EstimatedRequestCostComponent;
+export interface ObservedOtherCurrency {
+    readonly provider: SafeIdentifier;
+    readonly currency: CurrencyCode;
+    readonly amount: CanonicalDecimal;
+}
+/** One Slot/provider branch; observed and estimated facts never mix in it. */
+export type CostLedgerEntry = {
+    readonly slot: import("./contracts.js").AnalysisSlotRef;
+    readonly provider: SafeIdentifier | null;
+    readonly branch: "observed";
+    readonly components: readonly [ObservedCostComponent, ...ObservedCostComponent[]];
+    readonly estimated: null;
+} | {
+    readonly slot: import("./contracts.js").AnalysisSlotRef;
+    readonly provider: SafeIdentifier;
+    readonly branch: "estimated";
+    readonly components: readonly (EstimatedTokenCostComponent | EstimatedRequestCostComponent)[];
+    readonly estimated: ProjectedMoney;
+} | {
+    readonly slot: import("./contracts.js").AnalysisSlotRef;
+    readonly provider: SafeIdentifier | null;
+    readonly branch: "unavailable";
+    readonly components: readonly [];
+    readonly estimated: null;
+};
+/** Exact aggregation before any display / Number conversion. */
+export type CostProjectionAggregate = {
+    readonly kind: "mean";
+    /** Canonical USD subtotal before division or display rounding. */
+    readonly numerator: CanonicalDecimal;
+    /** Slots with a known quote-currency subtotal, never full denominator. */
+    readonly denominator: number;
+} | {
+    readonly kind: "total";
+    /** Canonical USD subtotal before display rounding. */
+    readonly total: CanonicalDecimal;
+};
+interface CostProjectionCommon {
+    readonly profile: CostProjectionProfile;
+    readonly aggregate: CostProjectionAggregate;
+    readonly observedOtherCurrencies: readonly ObservedOtherCurrency[];
+    readonly reasons: readonly CostCoverageReason[];
+    readonly ledger: readonly CostLedgerEntry[];
+}
+export interface CostProjectionKnown extends CostProjectionCommon {
+    readonly state: "available" | "partial";
+    readonly basis: Exclude<CostBasis, "unavailable">;
+    readonly observed: ProjectedMoney | null;
+    readonly estimated: ProjectedMoney | null;
+    readonly combined: ProjectedMoney;
+}
+export interface CostProjectionUnavailable extends CostProjectionCommon {
+    readonly state: "unavailable";
+    readonly basis: "unavailable";
+    readonly observed: null;
+    readonly estimated: null;
+    readonly combined: null;
+}
+export type CostProjectionValue = CostProjectionKnown | CostProjectionUnavailable;
+/** A normal MetricValue with a closed cost domain value attached. */
+export interface CostMetricValue extends MetricValue<number> {
+    readonly state: CostProjectionState;
+    readonly format: "currency-usd";
+    readonly better: "lower";
+    readonly projection: CostProjectionValue;
+}
+interface CostMeasureDescriptorValue {
+    readonly version: 1;
+    readonly mode: "mean" | "total";
+    readonly profile: PricingProfile;
+    readonly profileIdentity: PricingProfileContentIdentity;
+}
+/** A Measure whose data descriptor binds it to exactly one validated Profile. */
+export interface CostMeasure extends Measure<LogicalSlot, number> {
+    readonly [CostMeasureDescriptor]: CostMeasureDescriptorValue;
+}
+/** Defines, deeply freezes, canonically sorts, and content-addresses one USD Profile. */
+export declare function definePricingProfile(input: PricingProfileInput): PricingProfile;
+/**
+ * Identity-bearing Profile for NiceEval's complete vendored model catalog.
+ * Resolution matches an exact model identifier and does not infer a billing
+ * provider from an agent name. Missing models and buckets remain unpriced.
+ */
+export declare const builtInPricingProfile: PricingProfile;
+/** @internal Resolves one exact model from the catalog named by the built-in Profile. */
+export declare function builtInPricingCoverage(model: string): PricedCoverage | undefined;
+/** @internal
+ * Locally created or already revalidated Profiles use a WeakSet fast path.
+ * A value from another package graph must first pass the global Symbol data
+ * descriptor, recursive freezing, canonical content, and SHA-256 checks.
+ */
+export declare function isPricingProfile(value: unknown): value is PricingProfile;
+/**
+ * @internal Validates one already-closed cost projection without rebuilding a
+ * price, a ledger, or a numeric result. Report imports this internal guard so
+ * every deep cost-domain rule remains owned by Analysis.
+ */
+export declare function isCostProjectionValue(value: unknown): value is CostProjectionValue;
+/** Mean known USD cost per logical Slot for exactly one Profile. */
+export declare function costUSD(profile: PricingProfile): CostMeasure;
+/** Total known USD cost across logical Slots for exactly one Profile. */
+export declare function totalCostUSD(profile: PricingProfile): CostMeasure;
+/** @internal Revalidates a local or external CostMeasure data descriptor. */
+export declare function costMeasureState(value: unknown): CostMeasureDescriptorValue | undefined;
+/** @internal A structural cross-instance guard; it never infers a Profile from `id`. */
+export declare function isCostMeasure(value: unknown): value is CostMeasure;
+/** @internal Closes only immutable profile data for renderer consumption. */
+export declare function closeCostProjectionProfile(profile: PricingProfile): CostProjectionProfile;
+/** @internal Tests immutable Attempt-origin Core facts against a Profile coverage. */
+export declare function pricingCoverageMatches(coverage: PricingCoverage, input: {
+    readonly provider: SafeIdentifier;
+    readonly origin: {
+        readonly startedAt: UtcMillis;
+        readonly executionIdentityDigest: ExecutionIdentityDigest;
+        readonly execution: {
+            readonly agentId: string;
+            readonly model: string | null;
+            readonly reasoningEffort: string | null;
+        };
+    };
+}): boolean;
+export {};

package/dist/analysis/cost.js

@@ -0,0 +1,26 @@
+import { createRequire as __niceevalCreateRequire } from "node:module";
+const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
+const __niceevalCanonical = __niceevalRequire("./cost.cjs");
+const __niceevalExport0 = __niceevalCanonical["builtInPricingCoverage"];
+export { __niceevalExport0 as builtInPricingCoverage };
+const __niceevalExport1 = __niceevalCanonical["builtInPricingProfile"];
+export { __niceevalExport1 as builtInPricingProfile };
+const __niceevalExport2 = __niceevalCanonical["closeCostProjectionProfile"];
+export { __niceevalExport2 as closeCostProjectionProfile };
+const __niceevalExport3 = __niceevalCanonical["costMeasureState"];
+export { __niceevalExport3 as costMeasureState };
+const __niceevalExport4 = __niceevalCanonical["costUSD"];
+export { __niceevalExport4 as costUSD };
+const __niceevalExport5 = __niceevalCanonical["definePricingProfile"];
+export { __niceevalExport5 as definePricingProfile };
+const __niceevalExport6 = __niceevalCanonical["isCostMeasure"];
+export { __niceevalExport6 as isCostMeasure };
+const __niceevalExport7 = __niceevalCanonical["isCostProjectionValue"];
+export { __niceevalExport7 as isCostProjectionValue };
+const __niceevalExport8 = __niceevalCanonical["isPricingProfile"];
+export { __niceevalExport8 as isPricingProfile };
+const __niceevalExport9 = __niceevalCanonical["pricingCoverageMatches"];
+export { __niceevalExport9 as pricingCoverageMatches };
+const __niceevalExport10 = __niceevalCanonical["totalCostUSD"];
+export { __niceevalExport10 as totalCostUSD };
+//# sourceMappingURL=cost.js.map

package/dist/analysis/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sources":[],"names":[],"mappings":""}