@spottoai/types-package 1.0.2-dev1138.13 → 1.0.2-dev1138.14

package/dist/esm/azure/commitmentsPlanningValidation.js

@@ -0,0 +1,39 @@
+/** Dependency-free runtime guards for Azure commitments planning freshness evidence. */
+import { COMMITMENTS_FRESHNESS_REASON_CODES, } from './commitmentsPlanning.js';
+import { isDateTime, isFiniteNumber, isOptionalString, isRecord, isString, isStringArray } from '../common/validationHelpers.js';
+const FRESHNESS_STATUSES = ['current', 'stale', 'partial', 'unavailable'];
+const SOURCE_KINDS = ['azure-native', 'aws-native', 'spotto-derived', 'fallback-heuristic', 'manual', 'unknown'];
+export const isCommitmentsFreshnessStatus = (value) => typeof value === 'string' && FRESHNESS_STATUSES.includes(value);
+export const isCommitmentsFreshnessReasonCode = (value) => typeof value === 'string' && COMMITMENTS_FRESHNESS_REASON_CODES.includes(value);
+/** Finite, non-negative and rounded to one decimal place. */
+export const isCommitmentsFreshnessAgeHours = (value) => isFiniteNumber(value) && value >= 0 && Number(value.toFixed(1)) === value;
+/**
+ * Checks only the diagnostic fields shared by every commitments freshness producer:
+ * `ageHours` requires `lastSuccessfulSyncAt` and is a non-negative one-decimal number;
+ * `reasonCode` is a known code, and `collection-stale` appears only with status `stale`.
+ */
+export const hasValidCommitmentsFreshnessDiagnostics = (entry) => (entry.ageHours === undefined || (isCommitmentsFreshnessAgeHours(entry.ageHours) && entry.lastSuccessfulSyncAt !== undefined)) &&
+    (entry.reasonCode === undefined ||
+        (isCommitmentsFreshnessReasonCode(entry.reasonCode) && (entry.reasonCode !== 'collection-stale' || entry.status === 'stale')));
+/** Throwing form of `hasValidCommitmentsFreshnessDiagnostics` for exact public-artifact validators. */
+export function assertCommitmentsFreshnessDiagnostics(entry, field) {
+    if (!hasValidCommitmentsFreshnessDiagnostics(entry)) {
+        throw new Error(`${field} ageHours must be a non-negative one-decimal number with lastSuccessfulSyncAt, and reasonCode must be a known code (collection-stale only with status stale).`);
+    }
+}
+const isOptionalDateTime = (value) => value === undefined || isDateTime(value);
+export const isCommitmentsFreshnessEntry = (value) => isRecord(value) &&
+    isString(value.section) &&
+    isCommitmentsFreshnessStatus(value.status) &&
+    isOptionalDateTime(value.generatedAt) &&
+    isOptionalDateTime(value.observedAt) &&
+    isOptionalDateTime(value.lastSuccessfulSyncAt) &&
+    isOptionalString(value.reason) &&
+    (value.sourceKind === undefined || (typeof value.sourceKind === 'string' && SOURCE_KINDS.includes(value.sourceKind))) &&
+    hasValidCommitmentsFreshnessDiagnostics(value);
+export const isCommitmentsFreshnessSummary = (value) => isRecord(value) &&
+    isCommitmentsFreshnessStatus(value.status) &&
+    isDateTime(value.generatedAt) &&
+    Array.isArray(value.entries) &&
+    value.entries.every(isCommitmentsFreshnessEntry) &&
+    (value.warnings === undefined || isStringArray(value.warnings));

package/dist/esm/azure/common.js

@@ -1 +1,28 @@
-export {};
+import { isAzureProviderScopeFinancialChargeSpendBreakdownV1, } from './financialChargePolicy.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const hasExactFields = (value, required, optional = []) => {
+    const allowed = new Set([...required, ...optional]);
+    return required.every(field => Object.prototype.hasOwnProperty.call(value, field)) && Object.keys(value).every(field => allowed.has(field));
+};
+const isOptionalFiniteNumber = (value) => value === undefined || (typeof value === 'number' && Number.isFinite(value));
+const isResourceCostType = (value) => isRecord(value) &&
+    hasExactFields(value, ['name'], ['cost', 'costAmortized', 'costKind', 'commitmentPurchaseCost', 'commitmentPurchaseCostAmortized']) &&
+    typeof value.name === 'string' &&
+    value.name.length > 0 &&
+    value.name === value.name.trim() &&
+    isOptionalFiniteNumber(value.cost) &&
+    isOptionalFiniteNumber(value.costAmortized) &&
+    isOptionalFiniteNumber(value.commitmentPurchaseCost) &&
+    isOptionalFiniteNumber(value.commitmentPurchaseCostAmortized) &&
+    (value.costKind === undefined || value.costKind === 'usage' || value.costKind === 'commitment-purchase' || value.costKind === 'mixed');
+/** Exact validator for one Azure-native daily/month display projection. */
+export const isAzureNativeFinancialSummaryV1 = (value) => isRecord(value) &&
+    hasExactFields(value, ['contractVersion', 'policyRef', 'status', 'resourceTypes'], ['cost', 'costAmortized', 'financialChargeSpend']) &&
+    value.contractVersion === 'azure-native-financial-summary/v1' &&
+    value.policyRef === 'azure-cloud-services-excluding-marketplace/v1' &&
+    (value.status === 'complete' || value.status === 'partial') &&
+    isOptionalFiniteNumber(value.cost) &&
+    isOptionalFiniteNumber(value.costAmortized) &&
+    (value.financialChargeSpend === undefined || isAzureProviderScopeFinancialChargeSpendBreakdownV1(value.financialChargeSpend)) &&
+    Array.isArray(value.resourceTypes) &&
+    value.resourceTypes.every(isResourceCostType);

package/dist/esm/azure/costComposition.js

@@ -10,6 +10,8 @@ const LEGACY_ESTIMATE_LENS_BY_CANONICAL = {
 };
 export const toCanonicalEstimateLensV1 = (value) => CANONICAL_ESTIMATE_LENS_BY_LEGACY[value];
 export const toLegacyEstimateLensV1 = (value) => LEGACY_ESTIMATE_LENS_BY_CANONICAL[value];
+/** Declares that a published artifact contains public, rather than authority, cost compositions. */
+export const PUBLIC_COST_COMPOSITION_PROJECTION_CONTRACT_V1 = 'public-cost-composition/v1';
 const ESTIMATE_LENSES = new Set(['actual-only', 'actual-plus-estimated', 'estimates-only']);
 const SUPPORT_STATES = new Set(['supported', 'unsupported', 'unknown']);
 const BASIS_STATUSES = new Set(['actual-only', 'actual-plus-estimated', 'estimated-only', 'unavailable']);
@@ -57,3 +59,81 @@ export const isPublicCostComposition = (value) => isRecord(value) &&
     ESTIMATE_LENSES.has(value.selectedLens) &&
     isPublicBasis(value.billed, 'billed') &&
     isPublicBasis(value.amortized, 'amortized');
+const isCostCompositionProjectionSource = (value) => {
+    if (!isRecord(value))
+        return false;
+    return (value.schemaVersion === 1 &&
+        typeof value.compositionId === 'string' &&
+        isRecord(value.coverageIdentity) &&
+        typeof value.coverageCompletenessRef === 'string' &&
+        typeof value.allocationRef === 'string' &&
+        isRecord(value.billed) &&
+        value.billed.basis === 'billed' &&
+        isRecord(value.amortized) &&
+        value.amortized.basis === 'amortized');
+};
+const projectPublicAvailability = (availability) => availability.status === 'available'
+    ? {
+        status: 'available',
+        component: {
+            amount: availability.component.amount,
+            currencyCode: availability.component.currencyCode,
+        },
+    }
+    : { status: 'unavailable' };
+const projectPublicComponentState = (state) => ({
+    support: state.support,
+    availability: projectPublicAvailability(state.availability),
+});
+const projectPublicBasis = (basis, lens) => {
+    const combined = lens === 'actual-only' ? basis.actual.availability : lens === 'estimates-only' ? basis.estimated.availability : basis.combined;
+    return {
+        basis: basis.basis,
+        actual: projectPublicComponentState(basis.actual),
+        estimated: projectPublicComponentState(basis.estimated),
+        combined: projectPublicAvailability(combined),
+        status: basis.status,
+        ...(basis.estimateConfidence === undefined ? {} : { estimateConfidence: basis.estimateConfidence }),
+    };
+};
+/** Projects one authority composition to its exact customer-safe representation. */
+export const projectPublicCostCompositionV1 = (composition, lens = composition.selectedLens) => ({
+    schemaVersion: 1,
+    selectedLens: lens,
+    billed: projectPublicBasis(composition.billed, lens),
+    amortized: projectPublicBasis(composition.amortized, lens),
+});
+const visitPublicCostCompositions = (value, lens) => {
+    if (isCostCompositionProjectionSource(value))
+        return projectPublicCostCompositionV1(value, lens ?? value.selectedLens);
+    if (isPublicCostComposition(value)) {
+        return lens === undefined || lens === value.selectedLens ? value : projectPublicCostCompositionV1(value, lens);
+    }
+    if (Array.isArray(value)) {
+        let changed = false;
+        const projected = value.map(item => {
+            const next = visitPublicCostCompositions(item, lens);
+            changed || (changed = next !== item);
+            return next;
+        });
+        return changed ? projected : value;
+    }
+    if (!isRecord(value))
+        return value;
+    let changed = false;
+    const projected = Object.fromEntries(Object.entries(value).map(([key, item]) => {
+        const next = visitPublicCostCompositions(item, lens);
+        changed || (changed = next !== item);
+        return [key, next];
+    }));
+    return changed ? projected : value;
+};
+/** Recursively removes authority/evidence fields from every cost composition in a JSON document. */
+export const projectPublicCostCompositionsV1 = (document) => visitPublicCostCompositions(document);
+/** Applies a display lens to authority or already-public compositions without reconstructing money. */
+export const applyPublicCostCompositionEstimateLensV1 = (document, lens) => {
+    const projected = visitPublicCostCompositions(document, lens);
+    if (!isRecord(projected))
+        return projected;
+    return { ...projected, selectedLens: lens };
+};

package/dist/esm/azure/financialAnalyticsDelivery.js

@@ -1,4 +1,9 @@
 export const FINANCIAL_ANALYTICS_JOB_REQUEST_CONTRACT_VERSION_V1 = 'financial-analytics-job-request/v1';
 export const FINANCIAL_ANALYTICS_CURRENT_POINTER_CONTRACT_VERSION_V1 = 'financial-analytics-current-pointer/v1';
 export const FINANCIAL_ANALYTICS_INPUT_LOGICAL_NAME_V1 = 'financial-analytics-input.json.gz';
+export const FINANCIAL_ANALYTICS_INPUT_BY_ID_ROOT_V1 = 'financial-analytics/inputs-by-id';
 export const FINANCIAL_ANALYTICS_PROJECTION_LOGICAL_NAME_V1 = 'financial-analytics-projection.json.gz';
+export const FINANCIAL_ANALYTICS_BATCH_QUERY_CONTRACT_VERSION_V1 = 'financial-analytics-batch-query/v1';
+export const FINANCIAL_ANALYTICS_BATCH_RESPONSE_CONTRACT_VERSION_V1 = 'financial-analytics-batch-response/v1';
+export const FINANCIAL_ANALYTICS_OUTPUT_MANIFEST_CONTRACT_VERSION_V1 = 'financial-analytics-output-manifest/v1';
+export const financialAnalyticsInputByIdPathV1 = (analyticsInputId) => `${FINANCIAL_ANALYTICS_INPUT_BY_ID_ROOT_V1}/${analyticsInputId}/${FINANCIAL_ANALYTICS_INPUT_LOGICAL_NAME_V1}`;

package/dist/esm/azure/financialAnalyticsDeliveryValidation.js

@@ -1,8 +1,32 @@
 import { sha256Utf8 } from '../common/sha256.js';
 import { isFinancialAnalyticsInputSeriesV1, isFinancialAnalyticsProjectionV1 } from './financialAnalyticsValidation.js';
-import { FINANCIAL_ANALYTICS_CURRENT_POINTER_CONTRACT_VERSION_V1, FINANCIAL_ANALYTICS_JOB_REQUEST_CONTRACT_VERSION_V1, } from './financialAnalyticsDelivery.js';
-import { canonicalizeFinancialDataflowJsonV1, createFinancialDataflowCoordinateIdV1, hasFinancialDataflowExactFieldsV1, isFinancialDataflowHashV1, isFinancialDataflowIdentityV1, isFinancialDataflowIsoInstantV1, isFinancialDataflowRecordV1, isFinancialDataflowSortedUniqueStringsV1, } from './financialDataflowValidation.js';
+import { FINANCIAL_ANALYTICS_CURRENT_POINTER_CONTRACT_VERSION_V1, FINANCIAL_ANALYTICS_BATCH_QUERY_CONTRACT_VERSION_V1, FINANCIAL_ANALYTICS_BATCH_RESPONSE_CONTRACT_VERSION_V1, FINANCIAL_ANALYTICS_JOB_REQUEST_CONTRACT_VERSION_V1, FINANCIAL_ANALYTICS_OUTPUT_MANIFEST_CONTRACT_VERSION_V1, } from './financialAnalyticsDelivery.js';
+import { canonicalizeFinancialDataflowJsonV1, createFinancialDataflowCoordinateIdV1, hasFinancialDataflowExactFieldsV1, isFinancialDataflowHashV1, isFinancialDataflowIdentityV1, isFinancialDataflowIsoInstantV1, isFinancialDataflowJsonGzipArtifactDescriptorV1, isFinancialDataflowRecordV1, isFinancialDataflowCoordinateV1, } from './financialDataflowValidation.js';
 const RESULT_KINDS = new Set(['forecast', 'trend', 'anomaly']);
+const MAX_REQUESTED_OUTPUTS = 16;
+const MAX_BATCH_QUERY_ITEMS = 200;
+const isRequestedOutput = (value) => {
+    if (!isFinancialDataflowRecordV1(value) ||
+        !hasFinancialDataflowExactFieldsV1(value, ['resultKind', 'targetCoordinate'], ['currentSpendCompositionId', 'comparisonSpendCompositionId']) ||
+        !RESULT_KINDS.has(String(value.resultKind)) ||
+        !isFinancialDataflowCoordinateV1(value.targetCoordinate) ||
+        value.targetCoordinate.periodRole !== 'projection-target' ||
+        (value.currentSpendCompositionId !== undefined && !isFinancialDataflowHashV1(value.currentSpendCompositionId)) ||
+        (value.comparisonSpendCompositionId !== undefined && !isFinancialDataflowHashV1(value.comparisonSpendCompositionId))) {
+        return false;
+    }
+    if (value.resultKind === 'forecast')
+        return value.currentSpendCompositionId !== undefined && value.comparisonSpendCompositionId === undefined;
+    if (value.resultKind === 'trend')
+        return value.currentSpendCompositionId !== undefined && value.comparisonSpendCompositionId !== undefined;
+    return value.currentSpendCompositionId !== undefined && value.comparisonSpendCompositionId === undefined;
+};
+const requestedOutputKey = (value) => `${value.resultKind}\u0000${createFinancialDataflowCoordinateIdV1(value.targetCoordinate)}`;
+const sameCoordinateWithRole = (target, source, sourceRole) => canonicalizeFinancialDataflowJsonV1({ ...target, periodRole: sourceRole }) === canonicalizeFinancialDataflowJsonV1(source);
+const periodContains = (container, target) => container.period.requested.dateBasis === target.period.requested.dateBasis &&
+    container.period.requested.timeZone === target.period.requested.timeZone &&
+    container.period.requested.startDate <= target.period.requested.startDate &&
+    container.period.requested.endDateExclusive >= target.period.requested.endDateExclusive;
 const isJobRequestIdentity = (value) => isFinancialDataflowRecordV1(value) &&
     hasFinancialDataflowExactFieldsV1(value, [
         'schemaVersion',
@@ -12,7 +36,8 @@ const isJobRequestIdentity = (value) => isFinancialDataflowRecordV1(value) &&
         'analyticsInputId',
         'inputGenerationId',
         'inputArtifactDigest',
-        'requestedResultKinds',
+        'requestedOutputs',
+        'requestedAt',
     ]) &&
     value.schemaVersion === 1 &&
     value.contractVersion === FINANCIAL_ANALYTICS_JOB_REQUEST_CONTRACT_VERSION_V1 &&
@@ -21,15 +46,32 @@ const isJobRequestIdentity = (value) => isFinancialDataflowRecordV1(value) &&
     isFinancialDataflowHashV1(value.analyticsInputId) &&
     isFinancialDataflowIdentityV1(value.inputGenerationId) &&
     isFinancialDataflowHashV1(value.inputArtifactDigest) &&
-    isFinancialDataflowSortedUniqueStringsV1(value.requestedResultKinds, RESULT_KINDS.size) &&
-    value.requestedResultKinds.length > 0 &&
-    value.requestedResultKinds.every(kind => RESULT_KINDS.has(kind));
+    isFinancialDataflowIsoInstantV1(value.requestedAt) &&
+    Array.isArray(value.requestedOutputs) &&
+    value.requestedOutputs.length > 0 &&
+    value.requestedOutputs.length <= MAX_REQUESTED_OUTPUTS &&
+    value.requestedOutputs.every(isRequestedOutput) &&
+    new Set(value.requestedOutputs.map(requestedOutputKey)).size === value.requestedOutputs.length;
 export const canonicalizeFinancialAnalyticsJobRequestIdentityV1 = (value) => {
     if (!isJobRequestIdentity(value))
         throw new TypeError('Invalid FinancialAnalyticsJobRequestIdentityPreimageV1.');
-    return canonicalizeFinancialDataflowJsonV1({ ...value, requestedResultKinds: [...value.requestedResultKinds].sort() });
+    return canonicalizeFinancialDataflowJsonV1({
+        ...value,
+        requestedOutputs: [...value.requestedOutputs].sort((left, right) => requestedOutputKey(left).localeCompare(requestedOutputKey(right))),
+    });
 };
 export const createFinancialAnalyticsJobRequestIdV1 = (value) => `sha256:${sha256Utf8(canonicalizeFinancialAnalyticsJobRequestIdentityV1(value))}`;
+/** Stable immutable output generation selected by one exact job output. */
+export const createFinancialAnalyticsOutputGenerationIdV1 = (requestId, output) => {
+    if (!isFinancialDataflowHashV1(requestId) || !isRequestedOutput(output)) {
+        throw new TypeError('Invalid financial analytics output generation identity.');
+    }
+    return `financial-analytics-${sha256Utf8(canonicalizeFinancialDataflowJsonV1({
+        requestId,
+        resultKind: output.resultKind,
+        targetCoordinate: output.targetCoordinate,
+    }))}`;
+};
 export const isFinancialAnalyticsJobRequestV1 = (value) => {
     if (!isFinancialDataflowRecordV1(value) ||
         !hasFinancialDataflowExactFieldsV1(value, [
@@ -41,13 +83,12 @@ export const isFinancialAnalyticsJobRequestV1 = (value) => {
             'analyticsInputId',
             'inputGenerationId',
             'inputArtifactDigest',
-            'requestedResultKinds',
+            'requestedOutputs',
             'requestedAt',
         ]))
         return false;
-    const { requestId, requestedAt, ...identity } = value;
+    const { requestId, ...identity } = value;
     return (isFinancialDataflowHashV1(requestId) &&
-        isFinancialDataflowIsoInstantV1(requestedAt) &&
         isJobRequestIdentity(identity) &&
         requestId === createFinancialAnalyticsJobRequestIdV1(identity));
 };
@@ -59,12 +100,41 @@ export const isFinancialAnalyticsJobRequestCompatibleV1 = (request, input, verif
     request.coordinateId === createFinancialDataflowCoordinateIdV1(input.coordinate) &&
     request.analyticsInputId === input.analyticsInputId &&
     request.inputGenerationId === input.producerGenerationId &&
-    request.inputArtifactDigest === verifiedInputArtifactDigest;
+    request.inputArtifactDigest === verifiedInputArtifactDigest &&
+    request.requestedOutputs.every(output => {
+        const current = output.currentSpendCompositionId === undefined
+            ? undefined
+            : input.referenceCompositions.find(composition => composition.compositionId === output.currentSpendCompositionId);
+        const comparison = output.comparisonSpendCompositionId === undefined
+            ? undefined
+            : input.referenceCompositions.find(composition => composition.compositionId === output.comparisonSpendCompositionId);
+        return (output.targetCoordinate.companyId === input.coordinate.companyId &&
+            output.targetCoordinate.provider === input.coordinate.provider &&
+            canonicalizeFinancialDataflowJsonV1(output.targetCoordinate.providerAccountRefs) ===
+                canonicalizeFinancialDataflowJsonV1(input.coordinate.providerAccountRefs) &&
+            canonicalizeFinancialDataflowJsonV1(output.targetCoordinate.scope) === canonicalizeFinancialDataflowJsonV1(input.coordinate.scope) &&
+            output.targetCoordinate.costBasis === input.coordinate.costBasis &&
+            output.targetCoordinate.estimateLens === input.coordinate.estimateLens &&
+            output.targetCoordinate.requestedCurrencyCode === input.coordinate.requestedCurrencyCode &&
+            canonicalizeFinancialDataflowJsonV1(output.targetCoordinate.accountingCurrency) ===
+                canonicalizeFinancialDataflowJsonV1(input.coordinate.accountingCurrency) &&
+            (current === undefined || current.coordinate.periodRole === 'current-spend') &&
+            (comparison === undefined || comparison.coordinate.periodRole === 'comparison') &&
+            (output.currentSpendCompositionId === undefined || current !== undefined) &&
+            (output.comparisonSpendCompositionId === undefined || comparison !== undefined) &&
+            current !== undefined &&
+            sameCoordinateWithRole(output.targetCoordinate, current.coordinate, 'current-spend') &&
+            (output.resultKind !== 'anomaly' || periodContains(input.coordinate, output.targetCoordinate)));
+    });
 const isCurrentPointerIdentity = (value) => isFinancialDataflowRecordV1(value) &&
     hasFinancialDataflowExactFieldsV1(value, [
         'schemaVersion',
         'contractVersion',
         'coordinateId',
+        'resultKind',
+        'sourceRequestId',
+        'sourceRequestedAt',
+        'analyticsInputId',
         'pointerRevision',
         'outputGenerationId',
         'analyticsProjectionId',
@@ -74,6 +144,11 @@ const isCurrentPointerIdentity = (value) => isFinancialDataflowRecordV1(value) &
     value.schemaVersion === 1 &&
     value.contractVersion === FINANCIAL_ANALYTICS_CURRENT_POINTER_CONTRACT_VERSION_V1 &&
     isFinancialDataflowHashV1(value.coordinateId) &&
+    typeof value.resultKind === 'string' &&
+    RESULT_KINDS.has(value.resultKind) &&
+    isFinancialDataflowHashV1(value.sourceRequestId) &&
+    isFinancialDataflowIsoInstantV1(value.sourceRequestedAt) &&
+    isFinancialDataflowHashV1(value.analyticsInputId) &&
     Number.isSafeInteger(value.pointerRevision) &&
     Number(value.pointerRevision) > 0 &&
     isFinancialDataflowIdentityV1(value.outputGenerationId) &&
@@ -99,6 +174,104 @@ export const isFinancialAnalyticsCurrentPointerCompatibleV1 = (pointer, projecti
     isFinancialAnalyticsProjectionV1(projection) &&
     isFinancialDataflowHashV1(verifiedProjectionArtifactDigest) &&
     pointer.coordinateId === createFinancialDataflowCoordinateIdV1(projection.coordinate) &&
+    pointer.resultKind === (projection.status === 'unavailable' ? projection.resultKind : projection.result.kind) &&
+    pointer.analyticsInputId === projection.analyticsInputId &&
     pointer.outputGenerationId === projection.outputGenerationId &&
     pointer.analyticsProjectionId === projection.analyticsProjectionId &&
     pointer.projectionArtifactDigest === verifiedProjectionArtifactDigest;
+const isOutputManifestIdentity = (value) => isFinancialDataflowRecordV1(value) &&
+    hasFinancialDataflowExactFieldsV1(value, [
+        'schemaVersion',
+        'contractVersion',
+        'coordinateId',
+        'resultKind',
+        'outputGenerationId',
+        'analyticsProjectionId',
+        'sourceRequestId',
+        'analyticsInputId',
+        'inputArtifactDigest',
+        'projection',
+        'publishedAt',
+    ]) &&
+    value.schemaVersion === 1 &&
+    value.contractVersion === FINANCIAL_ANALYTICS_OUTPUT_MANIFEST_CONTRACT_VERSION_V1 &&
+    isFinancialDataflowHashV1(value.coordinateId) &&
+    typeof value.resultKind === 'string' &&
+    RESULT_KINDS.has(value.resultKind) &&
+    isFinancialDataflowIdentityV1(value.outputGenerationId) &&
+    isFinancialDataflowHashV1(value.analyticsProjectionId) &&
+    isFinancialDataflowHashV1(value.sourceRequestId) &&
+    isFinancialDataflowHashV1(value.analyticsInputId) &&
+    isFinancialDataflowHashV1(value.inputArtifactDigest) &&
+    isFinancialDataflowJsonGzipArtifactDescriptorV1(value.projection) &&
+    isFinancialDataflowIsoInstantV1(value.publishedAt);
+export const createFinancialAnalyticsOutputManifestDigestV1 = (value) => {
+    if (!isOutputManifestIdentity(value))
+        throw new TypeError('Invalid FinancialAnalyticsOutputManifestIdentityPreimageV1.');
+    return `sha256:${sha256Utf8(canonicalizeFinancialDataflowJsonV1(value))}`;
+};
+export const isFinancialAnalyticsOutputManifestV1 = (value) => {
+    if (!isFinancialDataflowRecordV1(value) || !Object.prototype.hasOwnProperty.call(value, 'manifestDigest'))
+        return false;
+    const { manifestDigest, ...identity } = value;
+    try {
+        return (isFinancialDataflowHashV1(manifestDigest) &&
+            manifestDigest === createFinancialAnalyticsOutputManifestDigestV1(identity));
+    }
+    catch {
+        return false;
+    }
+};
+export const isFinancialAnalyticsOutputManifestCompatibleV1 = (manifest, projection, verifiedProjectionArtifactDigest) => isFinancialAnalyticsOutputManifestV1(manifest) &&
+    isFinancialAnalyticsProjectionV1(projection) &&
+    isFinancialDataflowHashV1(verifiedProjectionArtifactDigest) &&
+    manifest.coordinateId === createFinancialDataflowCoordinateIdV1(projection.coordinate) &&
+    manifest.resultKind === (projection.status === 'unavailable' ? projection.resultKind : projection.result.kind) &&
+    manifest.outputGenerationId === projection.outputGenerationId &&
+    manifest.analyticsProjectionId === projection.analyticsProjectionId &&
+    manifest.analyticsInputId === projection.analyticsInputId &&
+    manifest.publishedAt === projection.producedAt &&
+    manifest.projection.sha256 === verifiedProjectionArtifactDigest;
+const isBatchQueryItem = (value) => isFinancialDataflowRecordV1(value) &&
+    hasFinancialDataflowExactFieldsV1(value, ['coordinateId', 'resultKind']) &&
+    isFinancialDataflowHashV1(value.coordinateId) &&
+    typeof value.resultKind === 'string' &&
+    RESULT_KINDS.has(value.resultKind);
+const batchQueryItemKey = (value) => `${value.coordinateId}\u0000${value.resultKind}`;
+export const isFinancialAnalyticsBatchQueryV1 = (value) => isFinancialDataflowRecordV1(value) &&
+    hasFinancialDataflowExactFieldsV1(value, ['schemaVersion', 'contractVersion', 'items']) &&
+    value.schemaVersion === 1 &&
+    value.contractVersion === FINANCIAL_ANALYTICS_BATCH_QUERY_CONTRACT_VERSION_V1 &&
+    Array.isArray(value.items) &&
+    value.items.length > 0 &&
+    value.items.length <= MAX_BATCH_QUERY_ITEMS &&
+    value.items.every(isBatchQueryItem) &&
+    new Set(value.items.map(item => batchQueryItemKey(item))).size === value.items.length;
+export const isFinancialAnalyticsBatchResponseV1 = (value) => isFinancialDataflowRecordV1(value) &&
+    hasFinancialDataflowExactFieldsV1(value, ['schemaVersion', 'contractVersion', 'results']) &&
+    value.schemaVersion === 1 &&
+    value.contractVersion === FINANCIAL_ANALYTICS_BATCH_RESPONSE_CONTRACT_VERSION_V1 &&
+    Array.isArray(value.results) &&
+    value.results.length > 0 &&
+    value.results.length <= MAX_BATCH_QUERY_ITEMS &&
+    value.results.every(result => {
+        if (!isFinancialDataflowRecordV1(result) || !isBatchQueryItem(result))
+            return false;
+        if (result.status === 'unavailable') {
+            return hasFinancialDataflowExactFieldsV1(result, ['coordinateId', 'resultKind', 'status', 'reasonCode']) &&
+                result.reasonCode === 'not-produced';
+        }
+        return result.status === 'available' &&
+            hasFinancialDataflowExactFieldsV1(result, ['coordinateId', 'resultKind', 'status', 'projection']) &&
+            isFinancialAnalyticsProjectionV1(result.projection) &&
+            createFinancialDataflowCoordinateIdV1(result.projection.coordinate) === result.coordinateId &&
+            (result.projection.status === 'unavailable' ? result.projection.resultKind : result.projection.result.kind) === result.resultKind;
+    }) &&
+    new Set(value.results.map(result => batchQueryItemKey(result))).size === value.results.length;
+export const isFinancialAnalyticsBatchResponseCompatibleV1 = (query, response) => isFinancialAnalyticsBatchQueryV1(query) &&
+    isFinancialAnalyticsBatchResponseV1(response) &&
+    query.items.length === response.results.length &&
+    query.items.every((item, index) => {
+        const result = response.results[index];
+        return result !== undefined && batchQueryItemKey(item) === batchQueryItemKey(result);
+    });

package/dist/esm/azure/financialAnalyticsDisplayKernel.js

@@ -0,0 +1,139 @@
+import { formatExactDecimalValue, parseCanonicalDecimal, sumCanonicalDecimals } from '../common/exactDecimal.js';
+import { isFinancialAnalyticsInputSeriesV1 } from './financialAnalyticsValidation.js';
+const DAY_MS = 86400000;
+const HISTORY_NOT_PRODUCED = 'history-not-produced';
+const CALENDAR_PERIOD_INCOMPLETE = 'calendar-period-incomplete';
+const addUtcDays = (date, days) => new Date(Date.parse(`${date}T00:00:00.000Z`) + days * DAY_MS).toISOString().slice(0, 10);
+const shiftUtcMonths = (date, months) => {
+    const parsed = new Date(`${date}T00:00:00.000Z`);
+    return new Date(Date.UTC(parsed.getUTCFullYear(), parsed.getUTCMonth() + months, 1)).toISOString().slice(0, 10);
+};
+const uniqueReasons = (values) => {
+    const reasons = [...new Set(values)].sort();
+    return (reasons.length > 0 ? reasons : [HISTORY_NOT_PRODUCED]);
+};
+/** Twelve-decimal half-away-from-zero display average; totals remain exact. */
+const averageKnownPerDay = (amount, dayCount) => {
+    if (!Number.isSafeInteger(dayCount) || dayCount < 1)
+        throw new RangeError('Display average requires a positive day count.');
+    const value = parseCanonicalDecimal(amount);
+    const precision = 12;
+    const numerator = (value.coefficient < 0n ? -value.coefficient : value.coefficient) * 10n ** BigInt(precision);
+    const scaledDivisor = BigInt(dayCount) * 10n ** BigInt(value.scale);
+    let quotient = numerator / scaledDivisor;
+    const remainder = numerator % scaledDivisor;
+    if (remainder * 2n >= scaledDivisor)
+        quotient += 1n;
+    return formatExactDecimalValue({ coefficient: value.coefficient < 0n ? -quotient : quotient, scale: precision });
+};
+const requestedInterval = (input, periodKey) => {
+    const endDateExclusive = input.coordinate.period.requested.endDateExclusive;
+    const startDate = periodKey === 'last-7-days'
+        ? addUtcDays(endDateExclusive, -7)
+        : periodKey === 'rolling-30-days'
+            ? addUtcDays(endDateExclusive, -30)
+            : periodKey === 'rolling-90-days'
+                ? addUtcDays(endDateExclusive, -90)
+                : shiftUtcMonths(addUtcDays(endDateExclusive, -1), -11);
+    return {
+        startDate,
+        endDateExclusive,
+        dateBasis: input.coordinate.period.requested.dateBasis,
+        ...(input.coordinate.period.requested.timeZone === undefined
+            ? {}
+            : { timeZone: input.coordinate.period.requested.timeZone }),
+    };
+};
+const displayDays = (input, startDate, endDateExclusive) => {
+    const pointByDate = new Map(input.points.map(point => [point.date, point]));
+    const gapReasons = (date) => input.gaps
+        .filter(gap => gap.startDate <= date && gap.endDateExclusive > date)
+        .flatMap(gap => gap.reasonCodes);
+    const days = [];
+    for (let date = startDate; date < endDateExclusive; date = addUtcDays(date, 1)) {
+        const point = pointByDate.get(date);
+        if (point?.status === 'available') {
+            days.push({ date, status: 'available', knownAmount: point.amount, reasonCodes: [] });
+        }
+        else if (point?.status === 'partial') {
+            days.push({ date, status: 'partial', knownAmount: point.knownAmount, reasonCodes: point.reasonCodes });
+        }
+        else {
+            const reasons = gapReasons(date);
+            days.push({ date, status: 'unavailable', reasonCodes: reasons.length > 0 ? reasons : [HISTORY_NOT_PRODUCED] });
+        }
+    }
+    return days;
+};
+const toBucket = (bucketKey, startDate, endDateExclusive, days) => {
+    const knownAmounts = days.flatMap(day => (day.knownAmount === undefined ? [] : [day.knownAmount]));
+    const coversWholeBucket = days[0]?.date === startDate && days.length > 0 && addUtcDays(days[days.length - 1].date, 1) === endDateExclusive;
+    const reasonCodes = uniqueReasons([
+        ...days.flatMap(day => day.reasonCodes),
+        ...(coversWholeBucket ? [] : [CALENDAR_PERIOD_INCOMPLETE]),
+    ]);
+    if (knownAmounts.length === 0) {
+        return { bucketKey, startDate, endDateExclusive, status: 'unavailable', reasonCodes };
+    }
+    const knownAmount = formatExactDecimalValue(sumCanonicalDecimals(knownAmounts));
+    const average = averageKnownPerDay(knownAmount, knownAmounts.length);
+    if (coversWholeBucket && days.every(day => day.status === 'available')) {
+        return { bucketKey, startDate, endDateExclusive, status: 'available', amount: knownAmount, averageKnownPerDay: average };
+    }
+    return { bucketKey, startDate, endDateExclusive, status: 'partial', knownAmount, averageKnownPerDay: average, reasonCodes };
+};
+const dailyBuckets = (days) => days.map(day => toBucket(day.date, day.date, addUtcDays(day.date, 1), [day]));
+const monthlyBuckets = (days) => {
+    const byMonth = new Map();
+    days.forEach(day => {
+        const month = day.date.slice(0, 7);
+        byMonth.set(month, [...(byMonth.get(month) ?? []), day]);
+    });
+    return [...byMonth.entries()].map(([month, monthDays]) => toBucket(month, `${month}-01`, shiftUtcMonths(`${month}-01`, 1), monthDays));
+};
+/**
+ * Exact, non-authoritative display rollup over one producer-owned analytics
+ * input. The function never changes charge inclusion, estimates, cost basis,
+ * currency, or source evidence; uncovered dates remain explicit.
+ */
+export const projectFinancialAnalyticsDisplayPeriodV1 = (request) => {
+    if (!isFinancialAnalyticsInputSeriesV1(request.input)) {
+        throw new TypeError('Financial analytics display projection requires a valid input series.');
+    }
+    const current = request.input.referenceCompositions.find(composition => composition.coordinate.periodRole === 'current-spend' && composition.compositionId === request.currentSpendCompositionId);
+    if (!current) {
+        throw new TypeError('Financial analytics input does not bind the requested current-spend composition.');
+    }
+    const accountingCurrency = request.input.coordinate.accountingCurrency;
+    if (accountingCurrency.status !== 'resolved') {
+        throw new TypeError('Financial analytics display projection requires a resolved accounting currency.');
+    }
+    const requested = requestedInterval(request.input, request.periodKey);
+    const days = displayDays(request.input, requested.startDate, requested.endDateExclusive);
+    const buckets = request.periodKey === 'trailing-12-calendar-months' ? monthlyBuckets(days) : dailyBuckets(days);
+    const common = {
+        analyticsInputId: request.input.analyticsInputId,
+        currentSpendCompositionId: current.compositionId,
+        chargeInclusionPolicyRef: current.coordinate.chargeInclusionPolicyRef,
+        periodKey: request.periodKey,
+        requested,
+        bucketGranularity: request.periodKey === 'trailing-12-calendar-months' ? 'calendar-month' : 'daily',
+        currencyCode: accountingCurrency.currencyCode,
+        buckets,
+    };
+    const knownAmounts = days.flatMap(day => (day.knownAmount === undefined ? [] : [day.knownAmount]));
+    const calendarPeriodIncomplete = request.periodKey === 'trailing-12-calendar-months' &&
+        requested.endDateExclusive !== shiftUtcMonths(addUtcDays(requested.endDateExclusive, -1), 1);
+    const reasonCodes = uniqueReasons([
+        ...days.flatMap(day => day.reasonCodes),
+        ...(calendarPeriodIncomplete ? [CALENDAR_PERIOD_INCOMPLETE] : []),
+    ]);
+    if (knownAmounts.length === 0)
+        return { ...common, status: 'unavailable', reasonCodes };
+    const knownAmount = formatExactDecimalValue(sumCanonicalDecimals(knownAmounts));
+    const average = averageKnownPerDay(knownAmount, knownAmounts.length);
+    if (!calendarPeriodIncomplete && days.every(day => day.status === 'available')) {
+        return { ...common, status: 'available', amount: knownAmount, averageKnownPerDay: average };
+    }
+    return { ...common, status: 'partial', knownAmount, averageKnownPerDay: average, reasonCodes };
+};