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

package/dist/esm/azure/financialChargeCompositionValidation.js

@@ -0,0 +1,155 @@
+import { formatExactDecimalValue, sumCanonicalDecimals } from '../common/exactDecimal.js';
+import { sha256Utf8 } from '../common/sha256.js';
+import { FINANCIAL_CHARGE_COMPOSITION_CONTRACT_VERSION_V1, FINANCIAL_CHARGE_COMPOSITION_SCHEMA_VERSION_V1, resolveFinancialChargeInclusionPolicyV1, } from './financialChargeComposition.js';
+import { canonicalizeFinancialDataflowJsonV1, hasFinancialDataflowExactFieldsV1, isFinancialDataflowCurrencyV1, isFinancialDataflowHashV1, isFinancialDataflowIdentityV1, isFinancialDataflowRecordV1, isFinancialDataflowValueWithinLimitsV1, } from './financialDataflowValidation.js';
+import { isFinancialBaselinePeriodV2 } from './financialScopeBaselineValidation.js';
+import { isCanonicalExactMoney } from './financialValidationPrimitives.js';
+const SOURCES = new Set(['azure-native', 'marketplace', 'unknown']);
+const RECURRENCES = new Set(['one-time', 'recurring', 'usage-based', 'unknown']);
+const CLASSIFICATIONS = new Set(['usage', 'purchase', 'adjustment', 'tax', 'credit', 'refund', 'residual']);
+const COST_BASES = new Set(['billed', 'amortized']);
+const ESTIMATE_LENSES = new Set(['actual-only', 'actual-plus-estimated', 'estimates-only']);
+const isSortedUniqueHashes = (value) => Array.isArray(value) && value.length > 0 && value.length <= 20000 && value.every(isFinancialDataflowHashV1) &&
+    value.every((entry, index) => index === 0 || value[index - 1] < entry);
+const isBucket = (value) => isFinancialDataflowRecordV1(value) &&
+    hasFinancialDataflowExactFieldsV1(value, [
+        'chargeSource',
+        'chargeRecurrence',
+        'chargeClassification',
+        'amount',
+        'componentIds',
+        'evidenceRefIds',
+    ]) &&
+    SOURCES.has(value.chargeSource) &&
+    RECURRENCES.has(value.chargeRecurrence) &&
+    CLASSIFICATIONS.has(value.chargeClassification) &&
+    isCanonicalExactMoney({ amount: value.amount, currencyCode: 'AUD' }) &&
+    isSortedUniqueHashes(value.componentIds) &&
+    isSortedUniqueHashes(value.evidenceRefIds);
+const isIdentity = (value) => {
+    if (!isFinancialDataflowRecordV1(value) ||
+        !hasFinancialDataflowExactFieldsV1(value, [
+            'schemaVersion',
+            'contractVersion',
+            'baselineId',
+            'ownerScopeId',
+            'period',
+            'costBasis',
+            'estimateLens',
+            'accountingCurrencyCode',
+            'buckets',
+            'reconciliation',
+            'algorithmVersion',
+        ]) ||
+        value.schemaVersion !== FINANCIAL_CHARGE_COMPOSITION_SCHEMA_VERSION_V1 ||
+        value.contractVersion !== FINANCIAL_CHARGE_COMPOSITION_CONTRACT_VERSION_V1 ||
+        !isFinancialDataflowHashV1(value.baselineId) ||
+        !isFinancialDataflowIdentityV1(value.ownerScopeId) ||
+        !isFinancialBaselinePeriodV2(value.period) ||
+        !COST_BASES.has(value.costBasis) ||
+        !ESTIMATE_LENSES.has(value.estimateLens) ||
+        !isFinancialDataflowCurrencyV1(value.accountingCurrencyCode) ||
+        !Array.isArray(value.buckets) ||
+        value.buckets.length === 0 ||
+        value.buckets.length > 20000 ||
+        !value.buckets.every(isBucket) ||
+        !isFinancialDataflowIdentityV1(value.algorithmVersion) ||
+        !isFinancialDataflowRecordV1(value.reconciliation) ||
+        !hasFinancialDataflowExactFieldsV1(value.reconciliation, ['status', 'bucketTotal', 'sourceTotal', 'difference']) ||
+        value.reconciliation.status !== 'reconciled' ||
+        value.reconciliation.difference !== '0' ||
+        !isCanonicalExactMoney({ amount: value.reconciliation.bucketTotal, currencyCode: value.accountingCurrencyCode }) ||
+        !isCanonicalExactMoney({ amount: value.reconciliation.sourceTotal, currencyCode: value.accountingCurrencyCode }))
+        return false;
+    const componentIds = value.buckets.flatMap(bucket => bucket.componentIds);
+    if (new Set(componentIds).size !== componentIds.length)
+        return false;
+    const keys = value.buckets.map(bucket => `${bucket.chargeSource}\u0000${bucket.chargeRecurrence}\u0000${bucket.chargeClassification}`);
+    if (!keys.every((key, index) => index === 0 || keys[index - 1] < key))
+        return false;
+    try {
+        const bucketTotal = formatExactDecimalValue(sumCanonicalDecimals(value.buckets.map(bucket => bucket.amount)));
+        return bucketTotal === value.reconciliation.bucketTotal && bucketTotal === value.reconciliation.sourceTotal;
+    }
+    catch {
+        return false;
+    }
+};
+export const canonicalizeFinancialChargeCompositionIdentityV1 = (value) => {
+    if (!isFinancialDataflowValueWithinLimitsV1(value) || !isIdentity(value)) {
+        throw new TypeError('Invalid FinancialChargeCompositionIdentityPreimageV1.');
+    }
+    return canonicalizeFinancialDataflowJsonV1(value);
+};
+export const createFinancialChargeCompositionIdV1 = (value) => `sha256:${sha256Utf8(canonicalizeFinancialChargeCompositionIdentityV1(value))}`;
+export const isFinancialChargeCompositionV1 = (value) => {
+    if (!isFinancialDataflowValueWithinLimitsV1(value) ||
+        !isFinancialDataflowRecordV1(value) ||
+        !hasFinancialDataflowExactFieldsV1(value, [
+            'chargeCompositionId',
+            'schemaVersion',
+            'contractVersion',
+            'baselineId',
+            'ownerScopeId',
+            'period',
+            'costBasis',
+            'estimateLens',
+            'accountingCurrencyCode',
+            'buckets',
+            'reconciliation',
+            'algorithmVersion',
+        ]))
+        return false;
+    const { chargeCompositionId, ...identity } = value;
+    return isFinancialDataflowHashV1(chargeCompositionId) && isIdentity(identity) &&
+        chargeCompositionId === createFinancialChargeCompositionIdV1(identity);
+};
+export const isFinancialChargeInclusionPolicyRefV1 = (value) => isFinancialDataflowRecordV1(value) &&
+    hasFinancialDataflowExactFieldsV1(value, ['policyId', 'policyDigest']) &&
+    isFinancialDataflowIdentityV1(value.policyId) &&
+    isFinancialDataflowHashV1(value.policyDigest) &&
+    resolveFinancialChargeInclusionPolicyV1(value) !== undefined;
+const sumBuckets = (buckets) => formatExactDecimalValue(sumCanonicalDecimals(buckets.map(bucket => bucket.amount)));
+const sourcesFor = (policy, role) => role === 'include' ? policy.includeSources : role === 'exclude' ? policy.excludeSources : policy.withholdSources;
+export const selectFinancialChargesV1 = (composition, policyRef) => {
+    if (!isFinancialChargeCompositionV1(composition))
+        throw new TypeError('Invalid financial charge composition.');
+    const policy = resolveFinancialChargeInclusionPolicyV1(policyRef);
+    if (!policy)
+        throw new TypeError('Unregistered financial charge-inclusion policy.');
+    const partition = (role) => composition.buckets.filter(bucket => sourcesFor(policy, role).includes(bucket.chargeSource));
+    const included = partition('include');
+    const excluded = partition('exclude');
+    const withheld = partition('withhold');
+    if (included.length + excluded.length + withheld.length !== composition.buckets.length) {
+        throw new TypeError('Financial charge-inclusion policy does not partition every charge source.');
+    }
+    const includedAmount = sumBuckets(included);
+    const excludedAmount = sumBuckets(excluded);
+    const withheldAmount = sumBuckets(withheld);
+    const forecastEligibleAmount = sumBuckets(included.filter(bucket => bucket.chargeRecurrence === 'recurring' || bucket.chargeRecurrence === 'usage-based'));
+    const oneTimeAmount = sumBuckets(included.filter(bucket => bucket.chargeRecurrence === 'one-time'));
+    const unknownRecurrenceAmount = sumBuckets(included.filter(bucket => bucket.chargeRecurrence === 'unknown'));
+    const reasonCodes = [];
+    if (withheldAmount !== '0')
+        reasonCodes.push('charge-source-unknown');
+    const forecastReasonCodes = [...reasonCodes];
+    if (unknownRecurrenceAmount !== '0')
+        forecastReasonCodes.push('charge-recurrence-unknown');
+    const result = {
+        status: withheldAmount === '0' ? 'available' : 'partial',
+        includedAmount,
+        excludedAmount,
+        withheldAmount,
+        forecastEligibleAmount,
+        oneTimeAmount,
+        unknownRecurrenceAmount,
+        forecastStatus: withheldAmount === '0' && unknownRecurrenceAmount === '0' ? 'available' : 'partial',
+        currencyCode: composition.accountingCurrencyCode,
+        ...(reasonCodes.length === 0 ? {} : { reasonCodes: reasonCodes }),
+        ...(forecastReasonCodes.length === 0
+            ? {}
+            : { forecastReasonCodes: forecastReasonCodes }),
+    };
+    return result;
+};

package/dist/esm/azure/financialDataflowKernel.js

@@ -0,0 +1,163 @@
+import { formatExactDecimalValue, parseCanonicalDecimal, subtractExactDecimalValues, sumCanonicalDecimals, } from '../common/exactDecimal.js';
+import { FINANCIAL_CURRENT_SPEND_COMPOSITION_CONTRACT_VERSION_V1, FINANCIAL_DATAFLOW_SCHEMA_VERSION_V1, } from './financialDataflow.js';
+import { selectFinancialChargesV1 } from './financialChargeCompositionValidation.js';
+import { createCurrentSpendCompositionIdV1, createCurrentSpendMembershipDigestV1, isCurrentSpendCompositionCompatibleV1, } from './financialDataflowValidation.js';
+import { isCompleteFinancialBaselinePeriodV2 } from './financialScopeBaseline.js';
+export const CURRENT_SPEND_COMPOSITION_ALGORITHM_VERSION_V1 = 'current-spend-composition/shared-v1';
+const exactPercentAtSixDecimalPlaces = (change, comparison) => {
+    if (comparison.coefficient === 0n)
+        return undefined;
+    const numerator = change.coefficient * 100n * 10n ** BigInt(comparison.scale);
+    const denominator = comparison.coefficient * 10n ** BigInt(change.scale);
+    for (let scale = 0; scale <= 6; scale += 1) {
+        const scaledNumerator = numerator * 10n ** BigInt(scale);
+        if (scaledNumerator % denominator === 0n) {
+            return formatExactDecimalValue({ coefficient: scaledNumerator / denominator, scale });
+        }
+    }
+    return undefined;
+};
+/**
+ * Shared exact current-versus-comparison semantics for display composition.
+ * Canonical analytics projections use the same direction/change/percentage
+ * rules; this helper does not create or impersonate an analytics authority.
+ */
+export const compareFinancialExactAmountsV1 = (request) => {
+    if (request.currentAmount === undefined || request.comparisonAmount === undefined)
+        return { status: 'unavailable' };
+    try {
+        const current = parseCanonicalDecimal(request.currentAmount);
+        const comparison = parseCanonicalDecimal(request.comparisonAmount);
+        if (formatExactDecimalValue(current) !== request.currentAmount ||
+            formatExactDecimalValue(comparison) !== request.comparisonAmount) {
+            return { status: 'unavailable' };
+        }
+        const change = subtractExactDecimalValues(current, comparison);
+        const direction = change.coefficient === 0n ? 'flat' : change.coefficient > 0n ? 'increasing' : 'decreasing';
+        const percentChange = exactPercentAtSixDecimalPlaces(change, comparison);
+        return {
+            status: 'available',
+            direction,
+            changeAmount: formatExactDecimalValue(change),
+            ...(percentChange === undefined ? {} : { percentChange }),
+        };
+    }
+    catch {
+        return { status: 'unavailable' };
+    }
+};
+const uniqueSorted = (values) => {
+    const result = Array.from(new Set(values)).sort();
+    if (result.length === 0)
+        throw new TypeError('Current-spend unavailable state requires at least one reason code.');
+    return result;
+};
+/** Portable exact-decimal composition kernel shared by Cloud and browser runtimes. */
+export const composeCurrentSpendV1 = (request) => {
+    if (request.coordinate.periodRole !== 'current-spend' && request.coordinate.periodRole !== 'comparison') {
+        throw new TypeError('Current-spend composition requires a current-spend or comparison coordinate.');
+    }
+    if (request.baselines.length === 0)
+        throw new TypeError('Current-spend composition requires an authoritative baseline member.');
+    if (request.chargeCompositions.length > request.baselines.length) {
+        throw new TypeError('Current-spend composition has more charge compositions than baseline members.');
+    }
+    const chargeCompositionByBaselineId = new Map(request.chargeCompositions.map(composition => [composition.baselineId, composition]));
+    if (chargeCompositionByBaselineId.size !== request.chargeCompositions.length) {
+        throw new TypeError('Current-spend composition cannot contain duplicate charge compositions.');
+    }
+    const sortedBaselines = [...request.baselines].sort((left, right) => left.scopeId.localeCompare(right.scopeId));
+    if (new Set(sortedBaselines.map(baseline => baseline.scopeId)).size !== sortedBaselines.length) {
+        throw new TypeError('Current-spend composition cannot contain duplicate member scopes.');
+    }
+    const selections = new Map();
+    const members = sortedBaselines.map(baseline => {
+        if (baseline.status === 'unavailable') {
+            return { memberScopeId: baseline.scopeId, status: 'unavailable', reasonCode: baseline.unavailableReason };
+        }
+        if (baseline.baselineKind !== 'owner') {
+            return { memberScopeId: baseline.scopeId, status: 'unavailable', reasonCode: 'charge-composition-requires-owner-baseline' };
+        }
+        const chargeComposition = chargeCompositionByBaselineId.get(baseline.baselineId);
+        if (!chargeComposition || chargeComposition.ownerScopeId !== baseline.scopeId) {
+            return { memberScopeId: baseline.scopeId, status: 'unavailable', reasonCode: 'charge-composition-unavailable' };
+        }
+        const selection = selectFinancialChargesV1(chargeComposition, request.coordinate.chargeInclusionPolicyRef);
+        selections.set(baseline.baselineId, selection);
+        return {
+            memberScopeId: baseline.scopeId,
+            baselineId: baseline.baselineId,
+            chargeCompositionId: chargeComposition.chargeCompositionId,
+            status: 'included',
+        };
+    });
+    const available = sortedBaselines.filter((baseline) => baseline.status === 'available');
+    const includedBaselines = available.filter(baseline => members.some(member => member.status === 'included' && member.baselineId === baseline.baselineId));
+    const unavailableReasons = new Set(sortedBaselines
+        .filter((baseline) => baseline.status === 'unavailable')
+        .map(baseline => baseline.unavailableReason));
+    members.filter(member => member.status === 'unavailable').forEach(member => unavailableReasons.add(member.reasonCode));
+    const selectionReasonCodes = new Set();
+    selections.forEach(selection => selection.reasonCodes?.forEach(reason => {
+        selectionReasonCodes.add(reason);
+        unavailableReasons.add(reason);
+    }));
+    if (available.some(baseline => !isCompleteFinancialBaselinePeriodV2(baseline.period)))
+        unavailableReasons.add('coverage-incomplete');
+    if (request.coordinate.accountingCurrency.status === 'unresolved') {
+        unavailableReasons.add(request.coordinate.accountingCurrency.reasonCode);
+    }
+    const common = {
+        schemaVersion: FINANCIAL_DATAFLOW_SCHEMA_VERSION_V1,
+        contractVersion: FINANCIAL_CURRENT_SPEND_COMPOSITION_CONTRACT_VERSION_V1,
+        coordinate: request.coordinate,
+        members,
+        membershipDigest: createCurrentSpendMembershipDigestV1(members),
+        algorithmVersion: request.algorithmVersion ?? CURRENT_SPEND_COMPOSITION_ALGORITHM_VERSION_V1,
+    };
+    const currency = request.coordinate.accountingCurrency.status === 'resolved' ? request.coordinate.accountingCurrency.currencyCode : undefined;
+    let identity;
+    if (!currency || includedBaselines.length === 0) {
+        identity = {
+            ...common,
+            amount: {
+                status: 'unavailable',
+                reasonCodes: uniqueSorted(unavailableReasons.size > 0 ? unavailableReasons : ['evidence-unavailable']),
+            },
+        };
+    }
+    else {
+        const includedSelections = members.flatMap(member => member.status === 'included' ? [selections.get(member.baselineId)] : []);
+        const aggregateSelection = {
+            status: includedSelections.some(selection => selection.status === 'partial') ? 'partial' : 'available',
+            includedAmount: formatExactDecimalValue(sumCanonicalDecimals(includedSelections.map(selection => selection.includedAmount))),
+            excludedAmount: formatExactDecimalValue(sumCanonicalDecimals(includedSelections.map(selection => selection.excludedAmount))),
+            withheldAmount: formatExactDecimalValue(sumCanonicalDecimals(includedSelections.map(selection => selection.withheldAmount))),
+            forecastEligibleAmount: formatExactDecimalValue(sumCanonicalDecimals(includedSelections.map(selection => selection.forecastEligibleAmount))),
+            oneTimeAmount: formatExactDecimalValue(sumCanonicalDecimals(includedSelections.map(selection => selection.oneTimeAmount))),
+            unknownRecurrenceAmount: formatExactDecimalValue(sumCanonicalDecimals(includedSelections.map(selection => selection.unknownRecurrenceAmount))),
+            forecastStatus: includedSelections.some(selection => selection.forecastStatus === 'partial') ? 'partial' : 'available',
+            currencyCode: currency,
+            ...(selectionReasonCodes.size === 0 ? {} : { reasonCodes: uniqueSorted(selectionReasonCodes) }),
+            ...(includedSelections.every(selection => selection.forecastReasonCodes === undefined)
+                ? {}
+                : {
+                    forecastReasonCodes: uniqueSorted(includedSelections.flatMap(selection => selection.forecastReasonCodes ?? [])),
+                }),
+        };
+        const knownAmount = aggregateSelection.includedAmount;
+        identity =
+            unavailableReasons.size === 0
+                ? { ...common, amount: { status: 'available', amount: knownAmount, currencyCode: currency }, chargeSelection: aggregateSelection }
+                : {
+                    ...common,
+                    amount: { status: 'partial', knownAmount, currencyCode: currency, reasonCodes: uniqueSorted(unavailableReasons) },
+                    chargeSelection: aggregateSelection,
+                };
+    }
+    const composition = { ...identity, compositionId: createCurrentSpendCompositionIdV1(identity) };
+    if (!isCurrentSpendCompositionCompatibleV1(composition, sortedBaselines, request.chargeCompositions)) {
+        throw new TypeError('Current-spend composition does not reconcile to its authoritative baseline members.');
+    }
+    return composition;
+};