@spottoai/types-package 1.0.2-beta.99 → 1.0.2-dev1138.12

package/dist/esm/azure/costComposition.js

@@ -0,0 +1,139 @@
+const CANONICAL_ESTIMATE_LENS_BY_LEGACY = {
+    'actual-only': 'billing-only',
+    'actual-plus-estimated': 'include-estimates',
+    'estimates-only': 'estimates-only',
+};
+const LEGACY_ESTIMATE_LENS_BY_CANONICAL = {
+    'billing-only': 'actual-only',
+    'include-estimates': 'actual-plus-estimated',
+    'estimates-only': 'estimates-only',
+};
+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']);
+const ESTIMATE_CONFIDENCE_VALUES = new Set(['high', 'medium', 'low', 'unknown']);
+const MONEY_PATTERN = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+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 isPublicMoneyComponent = (value) => isRecord(value) &&
+    hasExactFields(value, ['amount', 'currencyCode']) &&
+    typeof value.amount === 'string' &&
+    MONEY_PATTERN.test(value.amount) &&
+    typeof value.currencyCode === 'string' &&
+    value.currencyCode.length > 0 &&
+    value.currencyCode === value.currencyCode.trim();
+const isPublicAvailability = (value) => {
+    if (!isRecord(value))
+        return false;
+    if (value.status === 'unavailable')
+        return hasExactFields(value, ['status']);
+    return value.status === 'available' && hasExactFields(value, ['status', 'component']) && isPublicMoneyComponent(value.component);
+};
+const isPublicComponentState = (value) => isRecord(value) &&
+    hasExactFields(value, ['support', 'availability']) &&
+    typeof value.support === 'string' &&
+    SUPPORT_STATES.has(value.support) &&
+    isPublicAvailability(value.availability);
+const isPublicBasis = (value, expectedBasis) => isRecord(value) &&
+    hasExactFields(value, ['basis', 'actual', 'estimated', 'combined', 'status'], ['estimateConfidence']) &&
+    value.basis === expectedBasis &&
+    isPublicComponentState(value.actual) &&
+    isPublicComponentState(value.estimated) &&
+    isPublicAvailability(value.combined) &&
+    typeof value.status === 'string' &&
+    BASIS_STATUSES.has(value.status) &&
+    (value.estimateConfidence === undefined ||
+        (typeof value.estimateConfidence === 'string' && ESTIMATE_CONFIDENCE_VALUES.has(value.estimateConfidence)));
+/** Exact dependency-free validator for the public cost-composition boundary. */
+export const isPublicCostComposition = (value) => isRecord(value) &&
+    hasExactFields(value, ['schemaVersion', 'selectedLens', 'billed', 'amortized']) &&
+    value.schemaVersion === 1 &&
+    typeof value.selectedLens === 'string' &&
+    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/dataProtection.js

@@ -0,0 +1,5 @@
+export const DATA_PROTECTION_SCHEMA_VERSION = '2026-06-24';
+export const DATA_PROTECTION_SOURCE = 'Spotto.DataProtectionPosture';
+export const DATA_PROTECTION_PORTAL_FILE = 'data-protection.json.gz';
+export const DATA_PROTECTION_BACKUP_COST_DIAGNOSTICS_FILE = 'data-protection/backup-costs.json.gz';
+export const DATA_PROTECTION_BILLING_SOURCE_FILE = 'history/billing/cost-last-30-days.json';

package/dist/esm/azure/financialAnalytics.js

@@ -0,0 +1,2 @@
+export const FINANCIAL_ANALYTICS_INPUT_CONTRACT_VERSION_V1 = 'financial-analytics-input/v1';
+export const FINANCIAL_ANALYTICS_PROJECTION_CONTRACT_VERSION_V1 = 'financial-analytics-projection/v1';

package/dist/esm/azure/financialAnalyticsDelivery.js

@@ -0,0 +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

@@ -0,0 +1,277 @@
+import { sha256Utf8 } from '../common/sha256.js';
+import { isFinancialAnalyticsInputSeriesV1, isFinancialAnalyticsProjectionV1 } from './financialAnalyticsValidation.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',
+        'contractVersion',
+        'companyId',
+        'coordinateId',
+        'analyticsInputId',
+        'inputGenerationId',
+        'inputArtifactDigest',
+        'requestedOutputs',
+        'requestedAt',
+    ]) &&
+    value.schemaVersion === 1 &&
+    value.contractVersion === FINANCIAL_ANALYTICS_JOB_REQUEST_CONTRACT_VERSION_V1 &&
+    isFinancialDataflowIdentityV1(value.companyId) &&
+    isFinancialDataflowHashV1(value.coordinateId) &&
+    isFinancialDataflowHashV1(value.analyticsInputId) &&
+    isFinancialDataflowIdentityV1(value.inputGenerationId) &&
+    isFinancialDataflowHashV1(value.inputArtifactDigest) &&
+    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,
+        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, [
+            'schemaVersion',
+            'contractVersion',
+            'requestId',
+            'companyId',
+            'coordinateId',
+            'analyticsInputId',
+            'inputGenerationId',
+            'inputArtifactDigest',
+            'requestedOutputs',
+            'requestedAt',
+        ]))
+        return false;
+    const { requestId, ...identity } = value;
+    return (isFinancialDataflowHashV1(requestId) &&
+        isJobRequestIdentity(identity) &&
+        requestId === createFinancialAnalyticsJobRequestIdV1(identity));
+};
+/** Binds an identity-only queue request to already-verified immutable input bytes. */
+export const isFinancialAnalyticsJobRequestCompatibleV1 = (request, input, verifiedInputArtifactDigest) => isFinancialAnalyticsJobRequestV1(request) &&
+    isFinancialAnalyticsInputSeriesV1(input) &&
+    isFinancialDataflowHashV1(verifiedInputArtifactDigest) &&
+    request.companyId === input.coordinate.companyId &&
+    request.coordinateId === createFinancialDataflowCoordinateIdV1(input.coordinate) &&
+    request.analyticsInputId === input.analyticsInputId &&
+    request.inputGenerationId === input.producerGenerationId &&
+    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',
+        'projectionArtifactDigest',
+        'promotedAt',
+    ]) &&
+    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) &&
+    isFinancialDataflowHashV1(value.analyticsProjectionId) &&
+    isFinancialDataflowHashV1(value.projectionArtifactDigest) &&
+    isFinancialDataflowIsoInstantV1(value.promotedAt);
+export const canonicalizeFinancialAnalyticsCurrentPointerIdentityV1 = (value) => {
+    if (!isCurrentPointerIdentity(value))
+        throw new TypeError('Invalid FinancialAnalyticsCurrentPointerIdentityPreimageV1.');
+    return canonicalizeFinancialDataflowJsonV1(value);
+};
+export const createFinancialAnalyticsCurrentPointerDigestV1 = (value) => `sha256:${sha256Utf8(canonicalizeFinancialAnalyticsCurrentPointerIdentityV1(value))}`;
+export const isFinancialAnalyticsCurrentPointerV1 = (value) => {
+    if (!isFinancialDataflowRecordV1(value) || !Object.prototype.hasOwnProperty.call(value, 'pointerDigest'))
+        return false;
+    const { pointerDigest, ...identity } = value;
+    return (isFinancialDataflowHashV1(pointerDigest) &&
+        isCurrentPointerIdentity(identity) &&
+        pointerDigest === createFinancialAnalyticsCurrentPointerDigestV1(identity));
+};
+/** Binds a promoted pointer to already-verified immutable projection bytes. */
+export const isFinancialAnalyticsCurrentPointerCompatibleV1 = (pointer, projection, verifiedProjectionArtifactDigest) => isFinancialAnalyticsCurrentPointerV1(pointer) &&
+    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 };
+};