@spottoai/types-package 1.0.2-dev1138.1 → 1.0.2-dev1138.12

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 };
+};

package/dist/esm/azure/financialAnalyticsValidation.js

@@ -6,6 +6,7 @@ import { FINANCIAL_DATAFLOW_LIMITS_V1, canonicalizeFinancialDataflowJsonV1, hasF
 import { isCurrentSpendCompositionV1 } from './financialDataflowValidation.js';
 const MAX_POINTS = 3660;
 const MAX_GAPS = 3660;
+const MAX_REFERENCE_COMPOSITIONS = 2;
 const isReasonCodes = (value) => Array.isArray(value) &&
     value.length > 0 &&
     value.length <= FINANCIAL_DATAFLOW_LIMITS_V1.maximumReasonCodes &&
@@ -29,6 +30,7 @@ const comparableCoordinate = (value) => ({
     estimateLens: value.estimateLens,
     requestedCurrencyCode: value.requestedCurrencyCode,
     accountingCurrency: value.accountingCurrency,
+    chargeInclusionPolicyRef: value.chargeInclusionPolicyRef,
 });
 const hasSameFinancialDimensions = (left, right) => canonicalizeFinancialDataflowJsonV1(comparableCoordinate(left)) === canonicalizeFinancialDataflowJsonV1(comparableCoordinate(right));
 const hasComparableTrendPeriods = (current, comparison) => {
@@ -42,6 +44,10 @@ const hasComparableTrendPeriods = (current, comparison) => {
     return (intervalDayCount(current.period.requested.startDate, current.period.requested.endDateExclusive) ===
         intervalDayCount(comparison.period.requested.startDate, comparison.period.requested.endDateExclusive));
 };
+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 isInputIdentity = (value) => {
     if (!isFinancialDataflowRecordV1(value) ||
         !hasFinancialDataflowExactFieldsV1(value, [
@@ -50,6 +56,7 @@ const isInputIdentity = (value) => {
             'coordinate',
             'granularity',
             'producerGenerationId',
+            'referenceCompositions',
             'points',
             'gaps',
             'coverage',
@@ -59,9 +66,12 @@ const isInputIdentity = (value) => {
         value.contractVersion !== FINANCIAL_ANALYTICS_INPUT_CONTRACT_VERSION_V1 ||
         !isFinancialDataflowCoordinateV1(value.coordinate) ||
         value.coordinate.periodRole !== 'analytics-input' ||
+        value.coordinate.period.windowKind !== 'analytics-history' ||
         value.coordinate.accountingCurrency.status !== 'resolved' ||
         value.granularity !== 'daily' ||
         !isFinancialDataflowIdentityV1(value.producerGenerationId) ||
+        !Array.isArray(value.referenceCompositions) ||
+        value.referenceCompositions.length > MAX_REFERENCE_COMPOSITIONS ||
         !Array.isArray(value.points) ||
         value.points.length > MAX_POINTS ||
         !Array.isArray(value.gaps) ||
@@ -71,6 +81,16 @@ const isInputIdentity = (value) => {
         !isFinancialDataflowIdentityV1(value.algorithmVersion)) {
         return false;
     }
+    const coordinate = value.coordinate;
+    const referenceCompositions = value.referenceCompositions;
+    if (!referenceCompositions.every(isCurrentSpendCompositionV1))
+        return false;
+    const referenceRoles = referenceCompositions.map(composition => composition.coordinate.periodRole);
+    if (new Set(referenceCompositions.map(composition => composition.compositionId)).size !== referenceCompositions.length ||
+        new Set(referenceRoles).size !== referenceRoles.length ||
+        referenceCompositions.some(composition => !hasSameFinancialDimensions(coordinate, composition.coordinate))) {
+        return false;
+    }
     const gaps = value.gaps;
     const requested = value.coordinate.period.requested;
     const dates = new Set();
@@ -86,16 +106,47 @@ const isInputIdentity = (value) => {
             return false;
         }
         dates.add(point.date);
+        const pointForecastFields = [
+            point.forecastEligibleAmount,
+            point.oneTimeAmount,
+            point.unknownRecurrenceAmount,
+        ];
+        if (!pointForecastFields.every(amount => isCanonicalExactMoney({ amount, currencyCode: coordinate.accountingCurrency.currencyCode })) ||
+            (point.forecastStatus !== 'available' && point.forecastStatus !== 'partial') ||
+            (point.forecastStatus === 'available'
+                ? point.forecastReasonCodes !== undefined || point.unknownRecurrenceAmount !== '0'
+                : !isReasonCodes(point.forecastReasonCodes))) {
+            return false;
+        }
         if (point.status === 'available') {
-            if (!hasFinancialDataflowExactFieldsV1(point, ['date', 'compositionId', 'status', 'amount']) ||
-                !isCanonicalExactMoney({ amount: point.amount, currencyCode: 'AUD' }))
+            if (!hasFinancialDataflowExactFieldsV1(point, [
+                'date',
+                'compositionId',
+                'status',
+                'amount',
+                'forecastEligibleAmount',
+                'oneTimeAmount',
+                'unknownRecurrenceAmount',
+                'forecastStatus',
+            ], ['forecastReasonCodes']) ||
+                !isCanonicalExactMoney({ amount: point.amount, currencyCode: coordinate.accountingCurrency.currencyCode }))
                 return false;
             availableDayCount += 1;
         }
         else {
             if (point.status !== 'partial' ||
-                !hasFinancialDataflowExactFieldsV1(point, ['date', 'compositionId', 'status', 'knownAmount', 'reasonCodes']) ||
-                !isCanonicalExactMoney({ amount: point.knownAmount, currencyCode: 'AUD' }) ||
+                !hasFinancialDataflowExactFieldsV1(point, [
+                    'date',
+                    'compositionId',
+                    'status',
+                    'knownAmount',
+                    'reasonCodes',
+                    'forecastEligibleAmount',
+                    'oneTimeAmount',
+                    'unknownRecurrenceAmount',
+                    'forecastStatus',
+                ], ['forecastReasonCodes']) ||
+                !isCanonicalExactMoney({ amount: point.knownAmount, currencyCode: coordinate.accountingCurrency.currencyCode }) ||
                 !isReasonCodes(point.reasonCodes))
                 return false;
             partialDayCount += 1;
@@ -143,9 +194,7 @@ const isInputIdentity = (value) => {
         value.coverage.partialDayCount === partialDayCount &&
         value.coverage.unavailableDayCount === unavailableDayCount &&
         availableDayCount + partialDayCount + unavailableDayCount === expectedDays &&
-        cursor === requested.endDateExclusive &&
-        value.coordinate.period.gaps.length === gaps.length &&
-        value.coordinate.period.gaps.every(periodGap => gaps.some(gap => gap.startDate === periodGap.startDate && gap.endDateExclusive === periodGap.endDateExclusive)));
+        cursor === requested.endDateExclusive);
 };
 export const canonicalizeFinancialAnalyticsInputIdentityV1 = (value) => {
     if (!isFinancialDataflowValueWithinLimitsV1(value) || !isInputIdentity(value)) {
@@ -154,9 +203,16 @@ export const canonicalizeFinancialAnalyticsInputIdentityV1 = (value) => {
     return canonicalizeFinancialDataflowJsonV1({
         ...value,
         coordinate: { ...value.coordinate, providerAccountRefs: [...value.coordinate.providerAccountRefs].sort() },
+        referenceCompositions: [...value.referenceCompositions].sort((left, right) => left.compositionId.localeCompare(right.compositionId)),
         points: [...value.points]
             .sort((left, right) => left.date.localeCompare(right.date))
-            .map(point => (point.status === 'partial' ? { ...point, reasonCodes: [...point.reasonCodes].sort() } : point)),
+            .map(point => ({
+            ...point,
+            ...(point.status === 'partial' ? { reasonCodes: [...point.reasonCodes].sort() } : {}),
+            ...(point.forecastReasonCodes === undefined
+                ? {}
+                : { forecastReasonCodes: [...point.forecastReasonCodes].sort() }),
+        })),
         gaps: [...value.gaps]
             .sort((left, right) => `${left.startDate}\u0000${left.endDateExclusive}`.localeCompare(`${right.startDate}\u0000${right.endDateExclusive}`))
             .map(gap => ({ ...gap, reasonCodes: [...gap.reasonCodes].sort() })),
@@ -173,6 +229,18 @@ export const isFinancialAnalyticsInputSeriesV1 = (value) => {
 };
 const nextCalendarDate = (value) => new Date(Date.parse(`${value}T00:00:00.000Z`) + 86400000).toISOString().slice(0, 10);
 const hasSameReasonCodes = (left, right) => left.length === right.length && left.every(reasonCode => right.includes(reasonCode));
+const hasSameForecastSlice = (point, composition) => {
+    const selection = composition.chargeSelection;
+    return selection !== undefined &&
+        point.forecastEligibleAmount === selection.forecastEligibleAmount &&
+        point.oneTimeAmount === selection.oneTimeAmount &&
+        point.unknownRecurrenceAmount === selection.unknownRecurrenceAmount &&
+        point.forecastStatus === selection.forecastStatus &&
+        (point.forecastReasonCodes === undefined
+            ? selection.forecastReasonCodes === undefined
+            : selection.forecastReasonCodes !== undefined &&
+                hasSameReasonCodes(point.forecastReasonCodes, selection.forecastReasonCodes));
+};
 /** Proves that every analytics point is an exact projection of its referenced daily composition. */
 export const isFinancialAnalyticsInputSeriesCompatibleV1 = (input, dailyCompositions) => {
     if (!isFinancialAnalyticsInputSeriesV1(input) ||
@@ -188,6 +256,7 @@ export const isFinancialAnalyticsInputSeriesCompatibleV1 = (input, dailyComposit
     return input.points.every(point => {
         const composition = compositionById.get(point.compositionId);
         if (composition === undefined ||
+            composition.amount.status === 'unavailable' ||
             composition.coordinate.periodRole !== 'current-spend' ||
             composition.coordinate.period.windowKind !== 'daily' ||
             composition.coordinate.period.requested.startDate !== point.date ||
@@ -196,11 +265,14 @@ export const isFinancialAnalyticsInputSeriesCompatibleV1 = (input, dailyComposit
             return false;
         }
         if (point.status === 'available') {
-            return composition.amount.status === 'available' && point.amount === composition.amount.amount;
+            return (composition.amount.status === 'available' &&
+                point.amount === composition.amount.amount &&
+                hasSameForecastSlice(point, composition));
         }
         return (composition.amount.status === 'partial' &&
             point.knownAmount === composition.amount.knownAmount &&
-            hasSameReasonCodes(point.reasonCodes, composition.amount.reasonCodes));
+            hasSameReasonCodes(point.reasonCodes, composition.amount.reasonCodes) &&
+            hasSameForecastSlice(point, composition));
     });
 };
 const isResult = (value, currency) => {
@@ -234,7 +306,6 @@ const isResult = (value, currency) => {
     return (value.kind === 'anomaly' &&
         hasFinancialDataflowExactFieldsV1(value, ['kind', 'events']) &&
         Array.isArray(value.events) &&
-        value.events.length > 0 &&
         value.events.length <= MAX_POINTS &&
         value.events.every(event => {
             if (!isFinancialDataflowRecordV1(event) ||
@@ -283,9 +354,9 @@ const isProjectionIdentity = (value) => {
         return false;
     const currency = coordinateCurrency(value.coordinate);
     return (isFinancialDataflowHashV1(value.analyticsInputId) &&
+        isFinancialDataflowHashV1(value.currentSpendCompositionId) &&
         currency !== undefined &&
-        isResult(value.result, currency) &&
-        (value.result.kind === 'anomaly' || isFinancialDataflowHashV1(value.currentSpendCompositionId)));
+        isResult(value.result, currency));
 };
 export const canonicalizeFinancialAnalyticsProjectionIdentityV1 = (value) => {
     if (!isFinancialDataflowValueWithinLimitsV1(value) || !isProjectionIdentity(value)) {
@@ -334,17 +405,24 @@ export const isFinancialAnalyticsProjectionCompatibleV1 = (projection, input, cu
                 hasSameFinancialDimensions(projection.coordinate, currentSpendComposition.coordinate)));
     }
     if (projection.result.kind === 'anomaly') {
-        if (projection.currentSpendCompositionId !== undefined &&
-            (!isCurrentSpendCompositionV1(currentSpendComposition) ||
-                projection.currentSpendCompositionId !== currentSpendComposition.compositionId ||
-                !hasSameFinancialDimensions(projection.coordinate, currentSpendComposition.coordinate))) {
+        if (!isCurrentSpendCompositionV1(currentSpendComposition) ||
+            projection.currentSpendCompositionId !== currentSpendComposition.compositionId ||
+            !hasSameFinancialDimensions(projection.coordinate, currentSpendComposition.coordinate) ||
+            canonicalizeFinancialDataflowCoordinateV1({ ...projection.coordinate, periodRole: 'current-spend' }) !==
+                canonicalizeFinancialDataflowCoordinateV1(currentSpendComposition.coordinate) ||
+            !periodContains(input.coordinate, projection.coordinate)) {
             return false;
         }
         const pointsByDate = new Map(input.points.map(point => [point.date, point]));
         const eventDates = new Set();
+        const targetPeriod = projection.coordinate.period.requested;
         return projection.result.events.every(event => {
             const point = pointsByDate.get(event.date);
-            if (point === undefined || eventDates.has(event.date) || (projection.status === 'available' && point.status !== 'available'))
+            if (event.date < targetPeriod.startDate ||
+                event.date >= targetPeriod.endDateExclusive ||
+                point === undefined ||
+                eventDates.has(event.date) ||
+                (projection.status === 'available' && point.status !== 'available'))
                 return false;
             eventDates.add(event.date);
             const observedAmount = point.status === 'available' ? point.amount : point.knownAmount;
@@ -394,7 +472,11 @@ export const isFinancialAnalyticsProjectionCompatibleV1 = (projection, input, cu
             canonicalizeFinancialDataflowCoordinateV1(currentSpendComposition.coordinate)) {
         return false;
     }
-    if (projection.status === 'available' && currentSpendComposition.amount.status !== 'available')
+    if (projection.status === 'available' &&
+        currentSpendComposition.amount.status !== 'available' &&
+        !(currentSpendComposition.amount.status === 'partial' &&
+            currentSpendComposition.amount.reasonCodes.length === 1 &&
+            currentSpendComposition.amount.reasonCodes[0] === 'coverage-incomplete'))
         return false;
     if (currentSpendComposition.amount.status === 'unavailable')
         return false;