@ancplua/qyl-api-schema 0.5.14 → 0.6.0

package/models/cost-etl-audit.tsp

@@ -10,17 +10,8 @@ using Qyl.Api.Contracts.Common;
 
 namespace Qyl.Api.Contracts.Cost;
 
-@doc("How a provider-owned API supplied a cost value.")
-enum ProviderCostSourceKind {
-  @doc("Actual billed cost returned by a provider organization or cloud billing API.")
-  actualBilledCost: "actual_billed_cost",
-
-  @doc("A public SKU price returned by an official provider or cloud pricing API.")
-  officialPublicCatalog: "official_public_catalog",
-}
-
-@doc("Current synchronization state for a provider-owned cost source.")
-enum ProviderCostSourceStatus {
+@doc("Current synchronization state for a provider-owned billing source.")
+enum ProviderBillingSourceStatus {
   @doc("The source has no configured provider credential or cloud identity.")
   unconfigured: "unconfigured",
 
@@ -33,45 +24,36 @@ enum ProviderCostSourceStatus {
   @doc("The last successful provider response is older than its freshness window.")
   stale: "stale",
 
-  @doc("The latest provider fetch failed; no raw credential or upstream response is exposed.")
+  @doc("The latest provider billing fetch failed; no raw credential or upstream response is exposed.")
   syncFailed: "sync_failed",
-
-  @doc("Provider cost exists but cannot be attributed to the reported trace clusters.")
-  notAttributable: "not_attributable",
 }
 
-@doc("Granularity at which a cost value can be attributed to telemetry.")
-enum ProviderCostAttribution {
+@doc("Granularity at which official provider-billed cost can be attributed to telemetry.")
+enum ProviderBillingAttribution {
   @doc("The provider API identified the model and period represented by the value.")
   providerModelPeriod: "provider_model_period",
 
   @doc("The provider API identified only a provider/account period, not a model or request.")
   providerPeriod: "provider_period",
 
-  @doc("The value was supplied explicitly as a what-if scenario input.")
-  scenario: "scenario",
-
   @doc("No defensible attribution is available.")
   unavailable: "unavailable",
 }
 
-@doc("Provenance for cost data fetched directly from a provider-owned API.")
-model ProviderCostSource {
+@doc("Provenance for billed cost data fetched directly from a provider-owned API.")
+model ProviderBillingSource {
   @doc("Canonical GenAI provider or cloud billing system name.")
   provider: string;
 
-  @doc("Whether the API returned billed cost or a public catalog price.")
-  kind: ProviderCostSourceKind;
-
-  @doc("Current synchronization and attribution state.")
-  status: ProviderCostSourceStatus;
+  @doc("Current billing synchronization state.")
+  status: ProviderBillingSourceStatus;
 
   @doc("Official provider-owned API endpoint used for the fetch.")
   @encodedName("application/json", "source_endpoint")
   sourceEndpoint: UrlString;
 
   @doc("Attribution granularity supported by this source response.")
-  attribution: ProviderCostAttribution;
+  attribution: ProviderBillingAttribution;
 
   @doc("UTC time of the latest fetch attempt.")
   @encodedName("application/json", "last_attempt_at")
@@ -81,11 +63,11 @@ model ProviderCostSource {
   @encodedName("application/json", "last_success_at")
   lastSuccessAt?: utcDateTime;
 
-  @doc("Start of the provider billing or catalog validity period.")
+  @doc("Start of the provider billing period.")
   @encodedName("application/json", "period_start")
   periodStart?: utcDateTime;
 
-  @doc("End of the provider billing or catalog validity period.")
+  @doc("End of the provider billing period.")
   @encodedName("application/json", "period_end")
   periodEnd?: utcDateTime;
 
@@ -106,6 +88,494 @@ model ProviderCostSource {
   failureCategory?: string;
 }
 
+@doc("Current synchronization state for a configured live model catalog.")
+enum ModelCatalogSourceStatus {
+  @doc("The source is registered, but its required credential or activation is not configured.")
+  unconfigured: "unconfigured",
+
+  @doc("The source is configured, but no fetch has completed yet.")
+  pending: "pending",
+
+  @doc("The most recent successful catalog fetch is inside its freshness window.")
+  current: "current",
+
+  @doc("The last successful catalog response is older than its freshness window.")
+  stale: "stale",
+
+  @doc("The latest catalog fetch failed; no raw credential or upstream response is exposed.")
+  syncFailed: "sync_failed",
+}
+
+@doc("Synchronization metadata for one configurable live model catalog source.")
+model ModelCatalogSource {
+  @doc("Unique stable identifier of the configured catalog source.")
+  @encodedName("application/json", "source_id")
+  sourceId: string;
+
+  @doc("Configured source priority used for deterministic selection when multiple current catalogs match. Zero is highest priority; lower values win.")
+  priority: Count;
+
+  status: ModelCatalogSourceStatus;
+
+  @doc("Rate-selection semantics published by this source's active snapshot.")
+  @encodedName("application/json", "price_semantics")
+  priceSemantics?: ModelCatalogPriceSemantics;
+
+  @doc("Configured API endpoint used to fetch the live model catalog.")
+  @encodedName("application/json", "source_endpoint")
+  sourceEndpoint: UrlString;
+
+  @doc("UTC time of the latest fetch attempt.")
+  @encodedName("application/json", "last_attempt_at")
+  lastAttemptAt?: utcDateTime;
+
+  @doc("UTC time when the source was last verified successfully, including a verification that retained unchanged content.")
+  @encodedName("application/json", "last_verified_at")
+  lastVerifiedAt?: utcDateTime;
+
+  @doc("UTC time when the content of the currently retained catalog snapshot was retrieved.")
+  @encodedName("application/json", "retrieved_at")
+  retrievedAt?: utcDateTime;
+
+  @doc("Content-addressed identifier of the catalog snapshot currently used for estimates.")
+  @encodedName("application/json", "active_snapshot_id")
+  activeSnapshotId?: string;
+
+  @doc("Number of model records in the active catalog snapshot.")
+  @encodedName("application/json", "model_count")
+  modelCount?: Count;
+
+  @doc("Stable, non-sensitive failure category for the last attempt.")
+  @encodedName("application/json", "failure_category")
+  failureCategory?: string;
+}
+
+@doc("How a live catalog rate was selected when estimating cluster cost.")
+enum ModelCatalogPriceSemantics {
+  @doc("The catalog source publishes its lowest available model rate rather than an official bill or a uniquely routed endpoint price. A conditional rate applies only when its conditions are proven.")
+  minimumAvailableRate: "minimum_available_rate",
+
+  @doc("The source's published rate was applied without selecting a lower conditional rate.")
+  publishedRate: "published_rate",
+}
+
+@doc("Deterministic exact match used to resolve an observed model identity to a catalog record. Fuzzy, prefix, suffix, date, and alias matching are not permitted.")
+enum ModelCatalogMatchKind {
+  @doc("The observed model value exactly matched the catalog model identifier.")
+  exactModelId: "exact_model_id",
+
+  @doc("The observed model value exactly matched the catalog canonical slug.")
+  exactCanonicalSlug: "exact_canonical_slug",
+}
+
+@doc("Telemetry attribute used as the observed model identity for an exact catalog match.")
+enum ModelCatalogObservedIdentityBasis {
+  @doc("The observed identity came from the provider response model.")
+  responseModel: "response_model",
+
+  @doc("No response model was available, so the observed identity came from the request model.")
+  requestModelFallback: "request_model_fallback",
+}
+
+@doc("Provenance for the live catalog rates used to estimate one cluster.")
+model ModelCatalogPriceProvenance {
+  @doc("Unique stable identifier of the configured catalog source.")
+  @encodedName("application/json", "source_id")
+  sourceId: string;
+
+  @doc("Configured API endpoint from which the catalog was retrieved.")
+  @encodedName("application/json", "source_endpoint")
+  sourceEndpoint: UrlString;
+
+  @doc("Content-addressed identifier of the exact catalog snapshot used for this estimate.")
+  @encodedName("application/json", "snapshot_id")
+  snapshotId: string;
+
+  @doc("Exact model identifier selected from the source catalog.")
+  @encodedName("application/json", "price_model_id")
+  priceModelId: string;
+
+  @doc("Exact observed telemetry value compared with the selected catalog record.")
+  @encodedName("application/json", "observed_model_id")
+  observedModelId: string;
+
+  @encodedName("application/json", "observed_model_identity_basis")
+  observedModelIdentityBasis: ModelCatalogObservedIdentityBasis;
+
+  @encodedName("application/json", "model_match_kind")
+  modelMatchKind: ModelCatalogMatchKind;
+
+  @doc("UTC time when the current catalog snapshot used for this counterfactual estimate was retrieved. For historical audit periods, this is not evidence of the price that applied historically.")
+  @encodedName("application/json", "retrieved_at")
+  retrievedAt: utcDateTime;
+
+  @encodedName("application/json", "price_semantics")
+  priceSemantics: ModelCatalogPriceSemantics;
+}
+
+@doc("How a catalog rate charges its measured quantity.")
+enum ModelCatalogBillingMode {
+  @doc("The rate is multiplied by a measured unit quantity.")
+  perUnit: "per_unit",
+
+  @doc("The rate is charged once for each observed request.")
+  perRequest: "per_request",
+}
+
+@doc("How a selected catalog rate relates to the source's published base rate for the same component.")
+enum ModelCatalogRateRelation {
+  @doc("The selected rate is the published base rate for this component.")
+  baseRate: "base_rate",
+
+  @doc("The selected rate is an additive surcharge alongside the published base rate.")
+  additiveSurcharge: "additive_surcharge",
+
+  @doc("A source subtype rate replaces the inclusive published base rate for its target usage dimension. Conditional evidence is present only when an ordered source override altered that subtype rate.")
+  replacesInclusiveBaseRate: "replaces_inclusive_base_rate",
+
+  @doc("A proven ordered source override replaces the previously published rate for its target usage dimension.")
+  replacesPublishedRate: "replaces_published_rate",
+}
+
+@doc("One-based position of a conditional override in its source response.")
+@minValue(1)
+scalar ModelCatalogSourceOrder extends int64;
+
+@doc("Ordered evidence proving whether a conditional catalog override applied to an observed request quantity.")
+model ModelCatalogConditionalRateEvidence {
+  @doc("One-based position of this override in the source response; later matching overrides win. Tier zero is reserved for the published base rate and is not a source override.")
+  @encodedName("application/json", "source_order")
+  sourceOrder: ModelCatalogSourceOrder;
+
+  @doc("Observed per-call usage dimension evaluated by the source condition.")
+  @encodedName("application/json", "condition_usage_dimension")
+  conditionUsageDimension: string;
+
+  @doc("Exclusive minimum quantity declared by the source condition.")
+  @encodedName("application/json", "exclusive_minimum_quantity")
+  @minValue(0)
+  exclusiveMinimumQuantity: float64;
+
+  @doc("Observed per-call quantity compared with the exclusive minimum.")
+  @encodedName("application/json", "observed_per_call_quantity")
+  @minValue(0)
+  observedPerCallQuantity: float64;
+}
+
+@doc("Fields shared by every included token or request pricing component.")
+model ModelCatalogTokenEstimateComponentBase {
+  @doc("Source-defined pricing component, such as prompt, completion, request, cache read, cache write, or internal reasoning.")
+  component: string;
+
+  @doc("Qyl-observed usage dimension to which this rate was applied, such as input_tokens or output_tokens.")
+  @encodedName("application/json", "usage_dimension")
+  usageDimension: string;
+
+  @doc("Source-declared unit represented by the rate.")
+  unit: string;
+
+  @doc("Source-specific billing mode retained from the catalog or deterministically derived from the provider-defined meter.")
+  @encodedName("application/json", "source_billing_mode")
+  sourceBillingMode: string;
+
+  @encodedName("application/json", "billing_mode")
+  billingMode: ModelCatalogBillingMode;
+
+  @doc("Measured quantity to which the catalog unit price was applied.")
+  @minValue(0)
+  quantity: float64;
+
+  @doc("Catalog price in USD per source-defined unit.")
+  @encodedName("application/json", "unit_price_usd")
+  unitPriceUsd: CostUsd;
+
+  @doc("Estimated USD contribution of this component for the reported cluster period.")
+  @encodedName("application/json", "estimated_cost_usd")
+  estimatedCostUsd: CostUsd;
+}
+
+model ModelCatalogTokenBaseRateComponent extends ModelCatalogTokenEstimateComponentBase {
+  @encodedName("application/json", "rate_relation")
+  rateRelation: "base_rate";
+}
+
+model ModelCatalogTokenAdditiveSurchargeComponent extends ModelCatalogTokenEstimateComponentBase {
+  @encodedName("application/json", "rate_relation")
+  rateRelation: "additive_surcharge";
+}
+
+model ModelCatalogTokenInclusiveReplacementRateComponent extends ModelCatalogTokenEstimateComponentBase {
+  @encodedName("application/json", "rate_relation")
+  rateRelation: "replaces_inclusive_base_rate";
+
+  @doc("Inclusive base usage dimension replaced by this subtype rate.")
+  @encodedName("application/json", "replaces_usage_dimension")
+  replacesUsageDimension: string;
+
+  @doc("Ordered override evidence when the source conditionally altered this subtype rate.")
+  @encodedName("application/json", "conditional_evidence")
+  conditionalEvidence?: ModelCatalogConditionalRateEvidence;
+}
+
+model ModelCatalogTokenConditionalOverrideRateComponent extends ModelCatalogTokenEstimateComponentBase {
+  @encodedName("application/json", "rate_relation")
+  rateRelation: "replaces_published_rate";
+
+  @doc("Published usage dimension whose prior base, surcharge, or subtype rate was replaced.")
+  @encodedName("application/json", "replaces_usage_dimension")
+  replacesUsageDimension: string;
+
+  @encodedName("application/json", "conditional_evidence")
+  conditionalEvidence: ModelCatalogConditionalRateEvidence;
+}
+
+@doc("One evidenced token or request component contributing to a current-catalog estimate. The rate_relation literal selects the required evidence shape.")
+@oneOf
+union ModelCatalogTokenEstimateComponent {
+  baseRate: ModelCatalogTokenBaseRateComponent,
+  additiveSurcharge: ModelCatalogTokenAdditiveSurchargeComponent,
+  inclusiveReplacementRate: ModelCatalogTokenInclusiveReplacementRateComponent,
+  conditionalOverrideRate: ModelCatalogTokenConditionalOverrideRateComponent,
+}
+
+@doc("Why a catalog meter or conditional adjustment was not included in a token-and-request estimate.")
+enum ModelCatalogTokenExclusionReason {
+  @doc("The optional usage subtype was not observed; inclusive base input or output tokens remain priced.")
+  usageNotObserved: "usage_not_observed",
+
+  @doc("A conditional adjustment was not applied because its activation condition was not proven.")
+  conditionalAdjustmentNotApplied: "conditional_adjustment_not_applied",
+
+  @doc("The adjustment matched, but a later matching source override replaced it for the same meter.")
+  supersededByLaterOverride: "superseded_by_later_override",
+
+  @doc("The meter is outside the token-and-request estimate boundary and telemetry did not prove that it applied.")
+  outsideTokenEstimateScope: "outside_token_estimate_scope",
+
+  @doc("Telemetry proved the meter applied, but qyl does not support its usage dimension.")
+  unsupportedUsageDimension: "unsupported_usage_dimension",
+
+  @doc("Telemetry proved the meter applied, but qyl does not support its billing mode.")
+  unsupportedBillingMode: "unsupported_billing_mode",
+}
+
+model ModelCatalogBaseRateEvidence {
+  @encodedName("application/json", "rate_relation")
+  rateRelation: "base_rate";
+}
+
+model ModelCatalogAdditiveSurchargeEvidence {
+  @encodedName("application/json", "rate_relation")
+  rateRelation: "additive_surcharge";
+}
+
+model ModelCatalogInclusiveReplacementEvidence {
+  @encodedName("application/json", "rate_relation")
+  rateRelation: "replaces_inclusive_base_rate";
+
+  @doc("Inclusive base usage dimension replaced by this subtype rate.")
+  @encodedName("application/json", "replaces_usage_dimension")
+  replacesUsageDimension: string;
+
+  @doc("Ordered evidence when a source override altered the selected subtype rate.")
+  @encodedName("application/json", "conditional_evidence")
+  conditionalEvidence?: ModelCatalogConditionalRateEvidence;
+}
+
+model ModelCatalogPublishedReplacementEvidence {
+  @encodedName("application/json", "rate_relation")
+  rateRelation: "replaces_published_rate";
+
+  @doc("Published usage dimension whose prior base, surcharge, or subtype rate was replaced.")
+  @encodedName("application/json", "replaces_usage_dimension")
+  replacesUsageDimension: string;
+
+  @encodedName("application/json", "conditional_evidence")
+  conditionalEvidence: ModelCatalogConditionalRateEvidence;
+}
+
+@doc("Relation-specific evidence for a catalog rate omitted from a token-and-request estimate. The rate_relation literal selects the required target and ordered evidence shape.")
+@oneOf
+union ModelCatalogExclusionRateEvidence {
+  baseRate: ModelCatalogBaseRateEvidence,
+  additiveSurcharge: ModelCatalogAdditiveSurchargeEvidence,
+  inclusiveReplacement: ModelCatalogInclusiveReplacementEvidence,
+  publishedReplacement: ModelCatalogPublishedReplacementEvidence,
+}
+
+@doc("Fields shared by every catalog meter or conditional adjustment excluded from a token-and-request estimate.")
+model ModelCatalogTokenEstimateExclusionBase {
+  component: string;
+
+  @encodedName("application/json", "usage_dimension")
+  usageDimension: string;
+
+  unit: string;
+
+  @doc("Source-specific billing mode retained from the catalog or deterministically derived from the provider-defined meter, including unsupported modes.")
+  @encodedName("application/json", "source_billing_mode")
+  sourceBillingMode: string;
+
+  @doc("Relation, replacement target, and ordered override evidence for the omitted rate.")
+  @encodedName("application/json", "rate_evidence")
+  rateEvidence: ModelCatalogExclusionRateEvidence;
+
+  @doc("Catalog rate omitted from the estimate, when the source supplied one.")
+  @encodedName("application/json", "unit_price_usd")
+  unitPriceUsd?: CostUsd;
+}
+
+model ModelCatalogSupportedBillingExclusionBase extends ModelCatalogTokenEstimateExclusionBase {
+  @encodedName("application/json", "billing_mode")
+  billingMode: ModelCatalogBillingMode;
+}
+
+model ModelCatalogOptionallyNormalizedBillingExclusionBase extends ModelCatalogTokenEstimateExclusionBase {
+  @doc("Normalized billing mode when qyl recognizes the source meter; absent when the source meter has no supported normalization.")
+  @encodedName("application/json", "billing_mode")
+  billingMode?: ModelCatalogBillingMode;
+}
+
+model ModelCatalogUsageNotObservedExclusion extends ModelCatalogSupportedBillingExclusionBase {
+  reason: "usage_not_observed";
+}
+
+model ModelCatalogOutsideTokenScopeExclusion extends ModelCatalogOptionallyNormalizedBillingExclusionBase {
+  reason: "outside_token_estimate_scope";
+}
+
+model ModelCatalogUnsupportedUsageExclusion extends ModelCatalogOptionallyNormalizedBillingExclusionBase {
+  reason: "unsupported_usage_dimension";
+}
+
+model ModelCatalogUnsupportedBillingExclusion extends ModelCatalogTokenEstimateExclusionBase {
+  @doc("Normalized billing mode when the source mode has a partial known mapping; absent when no supported normalization exists.")
+  @encodedName("application/json", "billing_mode")
+  billingMode?: ModelCatalogBillingMode;
+
+  reason: "unsupported_billing_mode";
+}
+
+model ModelCatalogConditionalExclusionBase {
+  component: string;
+
+  @encodedName("application/json", "usage_dimension")
+  usageDimension: string;
+
+  unit: string;
+
+  @doc("Source-specific billing mode retained from the catalog or deterministically derived from the provider-defined meter.")
+  @encodedName("application/json", "source_billing_mode")
+  sourceBillingMode: string;
+
+  @doc("Normalized billing mode when qyl recognizes the conditional source meter; absent when the source meter has no supported normalization.")
+  @encodedName("application/json", "billing_mode")
+  billingMode?: ModelCatalogBillingMode;
+
+  @doc("The ordered source override that was not applied or was superseded.")
+  @encodedName("application/json", "rate_evidence")
+  rateEvidence: ModelCatalogPublishedReplacementEvidence;
+
+  @doc("Catalog rate omitted from the estimate, when the source supplied one.")
+  @encodedName("application/json", "unit_price_usd")
+  unitPriceUsd?: CostUsd;
+}
+
+model ModelCatalogConditionalAdjustmentNotAppliedExclusion extends ModelCatalogConditionalExclusionBase {
+  reason: "conditional_adjustment_not_applied";
+}
+
+model ModelCatalogSupersededOverrideExclusion extends ModelCatalogConditionalExclusionBase {
+  reason: "superseded_by_later_override";
+}
+
+@doc("Auditable catalog meter or conditional adjustment excluded from a token-and-request estimate. The reason literal selects the required evidence shape.")
+@oneOf
+union ModelCatalogTokenEstimateExclusion {
+  usageNotObserved: ModelCatalogUsageNotObservedExclusion,
+  conditionalAdjustmentNotApplied: ModelCatalogConditionalAdjustmentNotAppliedExclusion,
+  supersededByLaterOverride: ModelCatalogSupersededOverrideExclusion,
+  outsideTokenEstimateScope: ModelCatalogOutsideTokenScopeExclusion,
+  unsupportedUsageDimension: ModelCatalogUnsupportedUsageExclusion,
+  unsupportedBillingMode: ModelCatalogUnsupportedBillingExclusion,
+}
+
+@doc("Calculated all-or-nothing current-catalog token and request estimate for a complete workflow cluster.")
+model GenAiEtlCatalogTokenCalculatedEstimate {
+  status: "calculated";
+
+  @doc("Estimated token and request cost for the reported cluster period using the current catalog snapshot; this is counterfactual for historical periods and is not an official billed total.")
+  @encodedName("application/json", "estimated_catalog_token_cost_usd")
+  estimatedCatalogTokenCostUsd: CostUsd;
+
+  @doc("Estimated token and request cost per observed cluster call; this is not an official billed total.")
+  @encodedName("application/json", "estimated_catalog_token_cost_per_call_usd")
+  estimatedCatalogTokenCostPerCallUsd: CostUsd;
+
+  @doc("Exact catalog snapshot and model-match evidence.")
+  provenance: ModelCatalogPriceProvenance;
+
+  @doc("Included token or request usage and rate contributions. Ordered source overrides carry conditional evidence; ordinary inclusive subtype replacements do not require it.")
+  @minItems(1)
+  components: ModelCatalogTokenEstimateComponent[];
+
+  @doc("Meters or conditional adjustments explicitly omitted from this calculated estimate.")
+  @minItems(1)
+  exclusions?: ModelCatalogTokenEstimateExclusion[];
+}
+
+model GenAiEtlCatalogTokenEstimateFailureBase {
+  @doc("Available meter or conditional evidence explaining why the cluster estimate failed closed.")
+  @minItems(1)
+  exclusions?: ModelCatalogTokenEstimateExclusion[];
+}
+
+model GenAiEtlCatalogTokenSourceUnavailableEstimate extends GenAiEtlCatalogTokenEstimateFailureBase {
+  status: "source_unavailable";
+}
+
+model GenAiEtlCatalogTokenStaleSourceEstimate extends GenAiEtlCatalogTokenEstimateFailureBase {
+  status: "stale_source";
+}
+
+model GenAiEtlCatalogTokenMissingModelIdentityEstimate extends GenAiEtlCatalogTokenEstimateFailureBase {
+  status: "missing_model_identity";
+}
+
+model GenAiEtlCatalogTokenModelNotFoundEstimate extends GenAiEtlCatalogTokenEstimateFailureBase {
+  status: "model_not_found";
+}
+
+model GenAiEtlCatalogTokenAmbiguousModelEstimate extends GenAiEtlCatalogTokenEstimateFailureBase {
+  status: "ambiguous_model";
+}
+
+model GenAiEtlCatalogTokenIncompleteUsageEstimate extends GenAiEtlCatalogTokenEstimateFailureBase {
+  status: "incomplete_usage";
+}
+
+model GenAiEtlCatalogTokenConditionalPricingUnresolvableEstimate extends GenAiEtlCatalogTokenEstimateFailureBase {
+  status: "conditional_pricing_unresolvable";
+}
+
+model GenAiEtlCatalogTokenUnsupportedPricingEstimate extends GenAiEtlCatalogTokenEstimateFailureBase {
+  status: "unsupported_pricing";
+}
+
+@doc("All-or-nothing current-catalog token and request estimate. The status literal selects the complete calculated or fail-closed response shape.")
+@oneOf
+union GenAiEtlCatalogTokenCostEstimate {
+  calculated: GenAiEtlCatalogTokenCalculatedEstimate,
+  sourceUnavailable: GenAiEtlCatalogTokenSourceUnavailableEstimate,
+  staleSource: GenAiEtlCatalogTokenStaleSourceEstimate,
+  missingModelIdentity: GenAiEtlCatalogTokenMissingModelIdentityEstimate,
+  modelNotFound: GenAiEtlCatalogTokenModelNotFoundEstimate,
+  ambiguousModel: GenAiEtlCatalogTokenAmbiguousModelEstimate,
+  incompleteUsage: GenAiEtlCatalogTokenIncompleteUsageEstimate,
+  conditionalPricingUnresolvable: GenAiEtlCatalogTokenConditionalPricingUnresolvableEstimate,
+  unsupportedPricing: GenAiEtlCatalogTokenUnsupportedPricingEstimate,
+}
+
 @doc("Task family inferred for a repeated GenAI workflow cluster.")
 enum GenAiEtlTaskFamily {
   openReasoningGeneration: "open_reasoning_generation",
@@ -143,6 +613,15 @@ enum GenAiEtlCandidatePath {
   insufficientEvidence: "insufficient_evidence",
 }
 
+@doc("Evidence status of the proposed replacement path.")
+enum GenAiEtlCandidateStatus {
+  @doc("The path is a heuristic hypothesis that still requires the declared validation metrics and promotion gates.")
+  hypothesisOnly: "hypothesis_only",
+
+  @doc("Available evidence is insufficient to propose a replacement path.")
+  insufficientEvidence: "insufficient_evidence",
+}
+
 @doc("Task-specific metrics that can falsify a proposed replacement.")
 enum GenAiEtlValidationMetric {
   accuracy: "accuracy",
@@ -179,7 +658,8 @@ enum GenAiEtlEvidenceSignal {
   outputContract: "output_contract",
   providerModel: "provider_model",
   tokenUsage: "token_usage",
-  providerCost: "provider_cost",
+  @doc("A complete current-catalog token-and-request estimate with exact model and snapshot provenance.")
+  catalogTokenEstimate: "catalog_token_estimate",
   recurringSchema: "recurring_schema",
   boundedReference: "bounded_reference",
   taskMetric: "task_metric",
@@ -278,19 +758,9 @@ model GenAiEtlAuditCluster {
   @encodedName("application/json", "p95_latency_ms")
   p95LatencyMs: DurationMs;
 
-  @doc("Provider-sourced cost attributable to this cluster, absent when attribution is not defensible.")
-  @encodedName("application/json", "observed_cost_usd")
-  observedCostUsd?: CostUsd;
-
-  @encodedName("application/json", "cost_per_call_usd")
-  costPerCallUsd?: CostUsd;
-
-  @encodedName("application/json", "cost_attribution")
-  costAttribution: ProviderCostAttribution;
-
-  @doc("Fraction of attributable spend represented by this cluster.")
-  @encodedName("application/json", "spend_share")
-  spendShare?: Ratio;
+  @doc("Outcome and, when calculated, detailed current-catalog token-and-request estimate for this cluster. Aggregate provider billing is never attributed to a cluster.")
+  @encodedName("application/json", "catalog_token_estimate")
+  catalogTokenEstimate: GenAiEtlCatalogTokenCostEstimate;
 
   @doc("Fraction of calls with a task-specific correctness signal.")
   @encodedName("application/json", "measurable_coverage")
@@ -300,6 +770,10 @@ model GenAiEtlAuditCluster {
   @encodedName("application/json", "safe_deferral_coverage")
   safeDeferralCoverage?: Ratio;
 
+  @doc("Evidence status qualifying the proposed candidate path.")
+  @encodedName("application/json", "candidate_status")
+  candidateStatus: GenAiEtlCandidateStatus;
+
   @encodedName("application/json", "candidate_path")
   candidatePath: GenAiEtlCandidatePath;
 
@@ -332,17 +806,17 @@ model GenAiEtlAuditSummary {
   @encodedName("application/json", "total_output_tokens")
   totalOutputTokens: TokenCount;
 
-  @doc("Provider-sourced cost attributable to the returned trace population.")
-  @encodedName("application/json", "attributed_cost_usd")
-  attributedCostUsd?: CostUsd;
+  @doc("Counterfactual token and request cost of the full observed audit population before the cluster response limit is applied, using the current live catalog snapshot; this is not an official billed total or a historical price claim.")
+  @encodedName("application/json", "estimated_catalog_token_cost_usd")
+  estimatedCatalogTokenCostUsd?: CostUsd;
 
-  @doc("Fraction of calls covered by provider cost attribution.")
-  @encodedName("application/json", "priced_call_coverage")
-  pricedCallCoverage: Ratio;
+  @doc("Fraction of observed calls covered by all-or-nothing calculated token-and-request estimates; missing pricing is not treated as zero.")
+  @encodedName("application/json", "catalog_token_priced_call_coverage")
+  catalogTokenPricedCallCoverage: Ratio;
 
-  @doc("Fraction of attributable spend represented by the returned top clusters.")
-  @encodedName("application/json", "economic_concentration")
-  economicConcentration?: Ratio;
+  @doc("Returned top-cluster token-and-request estimate divided by estimated_catalog_token_cost_usd for the full observed audit population.")
+  @encodedName("application/json", "estimated_token_economic_concentration")
+  estimatedTokenEconomicConcentration?: Ratio;
 
   @doc("Fraction of calls with a task-specific correctness signal.")
   @encodedName("application/json", "measurable_coverage")
@@ -352,9 +826,9 @@ model GenAiEtlAuditSummary {
   @encodedName("application/json", "safe_deferral_coverage")
   safeDeferralCoverage?: Ratio;
 
-  @doc("Fraction of attributable spend attached to ETL-shaped candidates.")
-  @encodedName("application/json", "candidate_etl_spend_share")
-  candidateEtlSpendShare?: Ratio;
+  @doc("Fraction of estimated current-catalog token-and-request spend attached to ETL-shaped candidates.")
+  @encodedName("application/json", "candidate_etl_estimated_token_spend_share")
+  candidateEtlEstimatedTokenSpendShare?: Ratio;
 }
 
 @doc("Trace-level ETL audit for a bounded period.")
@@ -370,8 +844,13 @@ model GenAiEtlAuditReport {
 
   summary: GenAiEtlAuditSummary;
 
-  @encodedName("application/json", "cost_sources")
-  costSources: ProviderCostSource[];
+  @doc("Provider-owned aggregate billing sources. These totals are not attributed to clusters or used as evaluation baselines.")
+  @encodedName("application/json", "billing_sources")
+  billingSources: ProviderBillingSource[];
+
+  @doc("Configured live model catalog sources and their current synchronization state.")
+  @encodedName("application/json", "catalog_sources")
+  catalogSources: ModelCatalogSource[];
 
   clusters: GenAiEtlAuditCluster[];
 }
@@ -384,7 +863,7 @@ model GenAiEtlClusterScenario {
   @doc("Fraction of cluster calls the replacement is expected to serve safely.")
   coverage: Ratio;
 
-  @doc("Explicit baseline cost per call. When absent, qyl uses provider-attributed cluster cost and otherwise fails closed.")
+  @doc("Explicit scenario baseline cost per call. It wins over a calculated catalog estimate; when both are absent, evaluation fails closed.")
   @encodedName("application/json", "frontier_cost_per_call_usd")
   frontierCostPerCallUsd?: CostUsd;
 
@@ -405,19 +884,22 @@ model GenAiEtlAuditEvaluationRequest {
   scenarios: GenAiEtlClusterScenario[];
 }
 
-@doc("Whether the replaceable-value formula had a defensible baseline cost.")
-enum GenAiEtlCalculationStatus {
-  calculated: "calculated",
-  missingFrontierCost: "missing_frontier_cost",
+@doc("Evidence basis for the frontier cost used in a replacement-value calculation.")
+enum GenAiEtlFrontierCostBasis {
+  @doc("The request supplied an explicit what-if scenario cost, which takes precedence over a catalog estimate.")
+  scenario: "scenario",
+
+  @doc("A token-and-request live model catalog estimate was used; this is not an official billed total.")
+  catalogTokenEstimate: "catalog_token_estimate",
+
+  @doc("No defensible frontier cost was available.")
+  unavailable: "unavailable",
 }
 
-@doc("Result of replaceable_value = calls * coverage * (frontier - alternative) - maintenance - error.")
-model GenAiEtlClusterEvaluation {
+model GenAiEtlClusterEvaluationBase {
   @encodedName("application/json", "cluster_id")
   clusterId: string;
 
-  status: GenAiEtlCalculationStatus;
-
   @encodedName("application/json", "call_count")
   callCount: Count;
 
@@ -429,30 +911,60 @@ model GenAiEtlClusterEvaluation {
   @encodedName("application/json", "residual_call_count")
   residualCallCount: float64;
 
-  @encodedName("application/json", "frontier_cost_per_call_usd")
-  frontierCostPerCallUsd?: CostUsd;
-
-  @encodedName("application/json", "frontier_cost_basis")
-  frontierCostBasis: ProviderCostAttribution;
-
   @encodedName("application/json", "alternative_cost_per_call_usd")
   alternativeCostPerCallUsd: CostUsd;
 
-  @encodedName("application/json", "current_period_cost_usd")
-  currentPeriodCostUsd?: CostUsd;
-
-  @encodedName("application/json", "gross_replaceable_value_usd")
-  grossReplaceableValueUsd?: float64;
-
   @encodedName("application/json", "period_maintenance_cost_usd")
   periodMaintenanceCostUsd: CostUsd;
 
   @encodedName("application/json", "period_error_cost_usd")
   periodErrorCostUsd: CostUsd;
+}
+
+model GenAiEtlCalculatedClusterEvaluationBase extends GenAiEtlClusterEvaluationBase {
+  status: "calculated";
+
+  @encodedName("application/json", "frontier_cost_per_call_usd")
+  frontierCostPerCallUsd: CostUsd;
+
+  @encodedName("application/json", "current_period_cost_usd")
+  currentPeriodCostUsd: CostUsd;
+
+  @encodedName("application/json", "gross_replaceable_value_usd")
+  grossReplaceableValueUsd: float64;
 
   @doc("Net period value; this may be negative when maintenance or error cost exceeds gross savings.")
   @encodedName("application/json", "net_replaceable_value_usd")
-  netReplaceableValueUsd?: float64;
+  netReplaceableValueUsd: float64;
+}
+
+model GenAiEtlScenarioClusterEvaluation extends GenAiEtlCalculatedClusterEvaluationBase {
+  @encodedName("application/json", "frontier_cost_basis")
+  frontierCostBasis: "scenario";
+}
+
+model GenAiEtlCatalogTokenClusterEvaluation extends GenAiEtlCalculatedClusterEvaluationBase {
+  @encodedName("application/json", "frontier_cost_basis")
+  frontierCostBasis: "catalog_token_estimate";
+
+  @doc("Exact live-catalog snapshot and model-match evidence used for the calculated frontier cost.")
+  @encodedName("application/json", "catalog_provenance")
+  catalogProvenance: ModelCatalogPriceProvenance;
+}
+
+model GenAiEtlUnavailableClusterEvaluation extends GenAiEtlClusterEvaluationBase {
+  status: "missing_frontier_cost";
+
+  @encodedName("application/json", "frontier_cost_basis")
+  frontierCostBasis: "unavailable";
+}
+
+@doc("Result of replaceable_value = calls * coverage * (frontier - alternative) - maintenance - error. The frontier_cost_basis literal selects a complete calculated result or a fail-closed unavailable result.")
+@oneOf
+union GenAiEtlClusterEvaluation {
+  scenario: GenAiEtlScenarioClusterEvaluation,
+  catalogTokenEstimate: GenAiEtlCatalogTokenClusterEvaluation,
+  unavailable: GenAiEtlUnavailableClusterEvaluation,
 }
 
 @doc("Batch result for ETL replacement scenarios.")