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

package/dist/esm/azure/financialSavingsAuthorityValidation.js

@@ -2,7 +2,8 @@ import { sha256Utf8 } from '../common/sha256.js';
 import { FINANCIAL_SAVINGS_AUTHORITY_CONTRACT_VERSION_V1, FINANCIAL_SAVINGS_AUTHORITY_SCHEMA_VERSION_V1, } from './financialSavingsAuthority.js';
 import { validateFinancialEligibilityAssessmentV1, validateFinancialEligibilityBaselineV1, } from './financialEligibilityAssessmentValidation.js';
 import { validateFinancialSavingsCoordinateEnvelopeV1 } from './financialSavingsCoordinateValidation.js';
-import { canonicalizeFinancialSavingsJsonValue, hasExactFinancialSavingsFields, isFinancialSavingsHash, isFinancialSavingsRecord, } from './financialSavingsAuthorityValidationPrimitives.js';
+import { isFinancialChargeInclusionPolicyRefV1 } from './financialChargeCompositionValidation.js';
+import { canonicalizeFinancialSavingsJsonValue, hasExactFinancialSavingsFields, haveSameFinancialSavingsSet, isFinancialSavingsHash, isFinancialSavingsIdentity, isFinancialSavingsIsoInstant, isFinancialSavingsMinorUnits, isFinancialSavingsRecord, sumFinancialSavingsMinorUnits, } from './financialSavingsAuthorityValidationPrimitives.js';
 export { canonicalizeFinancialEligibilityAssessmentIdentityV1, createFinancialEligibilityAssessmentIdV1, } from './financialEligibilityAssessmentValidation.js';
 export { canonicalizeFinancialSavingsActivationIdentityV1, canonicalizeFinancialSavingsAllocationIdentityV1, canonicalizeFinancialSavingsDenominatorIdentityV1, createFinancialSavingsActivationIdV1, createFinancialSavingsAllocationIdV1, createFinancialSavingsDenominatorIdV1, } from './financialSavingsCoordinateValidation.js';
 export const canonicalizeFinancialSavingsAuthorityIdentityV1 = (value) => JSON.stringify(canonicalizeFinancialSavingsJsonValue({
@@ -28,7 +29,7 @@ export const canonicalizeFinancialSavingsAuthorityIdentityV1 = (value) => JSON.s
                 .map(allocation => ({
                 ...allocation,
                 billableComponentIds: [...allocation.billableComponentIds].sort(),
-                eligibility: allocation.eligibility.kind === 'not-applicable'
+                eligibility: allocation.eligibility.kind !== 'mapped'
                     ? allocation.eligibility
                     : {
                         ...allocation.eligibility,
@@ -39,6 +40,9 @@ export const canonicalizeFinancialSavingsAuthorityIdentityV1 = (value) => JSON.s
             resourceContributions: [...coordinate.resourceContributions]
                 .sort((left, right) => left.ownerScopeId.localeCompare(right.ownerScopeId))
                 .map(contribution => ({ ...contribution, allocationIds: [...contribution.allocationIds].sort() })),
+            recommendationContributions: [...coordinate.recommendationContributions]
+                .sort((left, right) => `${left.ownerScopeId}\u0000${left.recommendationId}`.localeCompare(`${right.ownerScopeId}\u0000${right.recommendationId}`))
+                .map(contribution => ({ ...contribution, allocationIds: [...contribution.allocationIds].sort() })),
             aggregate: { ...coordinate.aggregate, allocationIds: [...coordinate.aggregate.allocationIds].sort() },
         }),
 }));
@@ -112,3 +116,183 @@ export const isFinancialSavingsAuthorityBoundToFinancialAuthorityV1 = (value, au
     const { savingsAuthorityId: _savingsAuthorityId, ...identity } = savingsAuthority;
     return savingsAuthority.savingsAuthorityId === createFinancialSavingsAuthorityIdV1(identity);
 };
+const RESOURCE_PROJECTION_UNAVAILABLE_REASONS = new Set([
+    'scenario-coverage-unproven',
+    'unmigrated-scenario-producer',
+    'projection-unavailable',
+    'activation-unavailable',
+    'allocation-unavailable',
+]);
+const RESOURCE_PROJECTION_CURRENCY = /^[A-Z]{3}$/;
+const normalizeResourceScope = (value) => value.trim().toLowerCase().replace(/\/+$/, '');
+const isResourceContribution = (value, scopeId) => isFinancialSavingsRecord(value) &&
+    hasExactFinancialSavingsFields(value, ['ownerScopeId', 'allocationIds', 'savingsMinorUnits']) &&
+    isFinancialSavingsIdentity(value.ownerScopeId) &&
+    normalizeResourceScope(value.ownerScopeId) === scopeId &&
+    Array.isArray(value.allocationIds) &&
+    value.allocationIds.length > 0 &&
+    value.allocationIds.length <= 20000 &&
+    value.allocationIds.every(isFinancialSavingsHash) &&
+    new Set(value.allocationIds).size === value.allocationIds.length &&
+    isFinancialSavingsMinorUnits(value.savingsMinorUnits);
+const isRecommendationContribution = (value, scopeId) => isFinancialSavingsRecord(value) &&
+    hasExactFinancialSavingsFields(value, ['ownerScopeId', 'recommendationId', 'allocationIds', 'savingsMinorUnits']) &&
+    isFinancialSavingsIdentity(value.ownerScopeId) &&
+    normalizeResourceScope(value.ownerScopeId) === scopeId &&
+    isFinancialSavingsIdentity(value.recommendationId) &&
+    Array.isArray(value.allocationIds) &&
+    value.allocationIds.length > 0 &&
+    value.allocationIds.length <= 20000 &&
+    value.allocationIds.every(isFinancialSavingsHash) &&
+    new Set(value.allocationIds).size === value.allocationIds.length &&
+    isFinancialSavingsMinorUnits(value.savingsMinorUnits);
+const isSavingsResourceCoordinate = (value, scopeId) => {
+    if (!isFinancialSavingsRecord(value) || !isFinancialSavingsHash(value.coordinateId))
+        return false;
+    if (value.status === 'unavailable') {
+        return (hasExactFinancialSavingsFields(value, ['status', 'coordinateId', 'unavailableReason'], ['currentAggregateBaselineId', 'chargeInclusionPolicyRef']) &&
+            (value.currentAggregateBaselineId === undefined || isFinancialSavingsHash(value.currentAggregateBaselineId)) &&
+            (value.chargeInclusionPolicyRef === undefined || isFinancialChargeInclusionPolicyRefV1(value.chargeInclusionPolicyRef)) &&
+            typeof value.unavailableReason === 'string' &&
+            RESOURCE_PROJECTION_UNAVAILABLE_REASONS.has(value.unavailableReason));
+    }
+    const partial = value.status === 'partial';
+    if (value.status !== 'available' &&
+        !partial)
+        return false;
+    if (!hasExactFinancialSavingsFields(value, [
+        'status',
+        'coordinateId',
+        'currentAggregateBaselineId',
+        'accountingCurrencyCode',
+        'minorUnitScale',
+        'roundingMode',
+        'recommendationContributions',
+        ...(partial ? ['unavailableScenarioIds'] : []),
+    ], [
+        'resourceContribution',
+        'chargeInclusionPolicyRef',
+        'displayMemberResourceContributions',
+        'displayMemberRecommendationContributions',
+    ]) ||
+        !isFinancialSavingsHash(value.currentAggregateBaselineId) ||
+        (value.chargeInclusionPolicyRef !== undefined && !isFinancialChargeInclusionPolicyRefV1(value.chargeInclusionPolicyRef)) ||
+        typeof value.accountingCurrencyCode !== 'string' ||
+        !RESOURCE_PROJECTION_CURRENCY.test(value.accountingCurrencyCode) ||
+        !Number.isSafeInteger(value.minorUnitScale) ||
+        Number(value.minorUnitScale) < 0 ||
+        Number(value.minorUnitScale) > 6 ||
+        value.roundingMode !== 'half-away-from-zero' ||
+        (value.resourceContribution !== undefined && !isResourceContribution(value.resourceContribution, scopeId)) ||
+        !Array.isArray(value.recommendationContributions) ||
+        value.recommendationContributions.length > 20000 ||
+        !value.recommendationContributions.every(contribution => isRecommendationContribution(contribution, scopeId)) ||
+        (value.displayMemberResourceContributions !== undefined &&
+            (!Array.isArray(value.displayMemberResourceContributions) ||
+                value.displayMemberResourceContributions.length === 0 ||
+                value.displayMemberResourceContributions.length > 20000 ||
+                !value.displayMemberResourceContributions.every(contribution => isFinancialSavingsRecord(contribution) &&
+                    isResourceContribution(contribution, normalizeResourceScope(String(contribution.ownerScopeId))) &&
+                    normalizeResourceScope(String(contribution.ownerScopeId)) !== scopeId))) ||
+        (value.displayMemberRecommendationContributions !== undefined &&
+            (!Array.isArray(value.displayMemberRecommendationContributions) ||
+                value.displayMemberRecommendationContributions.length === 0 ||
+                value.displayMemberRecommendationContributions.length > 20000 ||
+                !value.displayMemberRecommendationContributions.every(contribution => isFinancialSavingsRecord(contribution) &&
+                    isRecommendationContribution(contribution, normalizeResourceScope(String(contribution.ownerScopeId))) &&
+                    normalizeResourceScope(String(contribution.ownerScopeId)) !== scopeId))) ||
+        (partial &&
+            (!Array.isArray(value.unavailableScenarioIds) ||
+                value.unavailableScenarioIds.length === 0 ||
+                value.unavailableScenarioIds.length > 20000 ||
+                !value.unavailableScenarioIds.every(isFinancialSavingsIdentity) ||
+                new Set(value.unavailableScenarioIds).size !== value.unavailableScenarioIds.length)))
+        return false;
+    const recommendationIds = value.recommendationContributions.map(contribution => contribution.recommendationId);
+    const allocationIds = value.recommendationContributions.flatMap(contribution => contribution.allocationIds);
+    const contributionSum = sumFinancialSavingsMinorUnits(value.recommendationContributions.map(contribution => contribution.savingsMinorUnits));
+    const resourceContribution = value.resourceContribution;
+    const primaryValid = new Set(recommendationIds).size === recommendationIds.length &&
+        new Set(allocationIds).size === allocationIds.length &&
+        contributionSum !== undefined &&
+        (resourceContribution === undefined
+            ? allocationIds.length === 0 && contributionSum === 0
+            : haveSameFinancialSavingsSet(allocationIds, resourceContribution.allocationIds) &&
+                contributionSum === resourceContribution.savingsMinorUnits);
+    if (!primaryValid)
+        return false;
+    const displayResourceContributions = (value.displayMemberResourceContributions ?? []);
+    const displayRecommendationContributions = (value.displayMemberRecommendationContributions ?? []);
+    const displayResourceByOwner = new Map(displayResourceContributions.map(contribution => [normalizeResourceScope(contribution.ownerScopeId), contribution]));
+    if (displayResourceByOwner.size !== displayResourceContributions.length)
+        return false;
+    const displayRecommendationKeys = displayRecommendationContributions.map(contribution => `${normalizeResourceScope(contribution.ownerScopeId)}\u0000${contribution.recommendationId}`);
+    if (new Set(displayRecommendationKeys).size !== displayRecommendationKeys.length)
+        return false;
+    const displayAllocationIds = displayRecommendationContributions.flatMap(contribution => contribution.allocationIds);
+    if (new Set(displayAllocationIds).size !== displayAllocationIds.length ||
+        displayAllocationIds.some(allocationId => allocationIds.includes(allocationId)))
+        return false;
+    for (const [ownerScopeId, contribution] of displayResourceByOwner) {
+        const recommendations = displayRecommendationContributions.filter(candidate => normalizeResourceScope(candidate.ownerScopeId) === ownerScopeId);
+        const recommendationAllocationIds = recommendations.flatMap(candidate => candidate.allocationIds);
+        const recommendationSavings = sumFinancialSavingsMinorUnits(recommendations.map(candidate => candidate.savingsMinorUnits));
+        if (recommendationSavings === undefined ||
+            recommendationSavings !== contribution.savingsMinorUnits ||
+            !haveSameFinancialSavingsSet(recommendationAllocationIds, contribution.allocationIds))
+            return false;
+    }
+    return displayRecommendationContributions.every(contribution => displayResourceByOwner.has(normalizeResourceScope(contribution.ownerScopeId)));
+};
+/** Strict structural and arithmetic validation for one bounded resource savings projection. */
+export const isFinancialSavingsResourceProjectionV1 = (value) => {
+    if (!isFinancialSavingsRecord(value) ||
+        !hasExactFinancialSavingsFields(value, [
+            'contractVersion',
+            'savingsAuthorityId',
+            'financialAuthorityId',
+            'artifactGeneration',
+            'scopeId',
+            'coordinates',
+        ]) ||
+        value.contractVersion !== 'financial-savings-resource-projection/v1' ||
+        !isFinancialSavingsHash(value.savingsAuthorityId) ||
+        !isFinancialSavingsHash(value.financialAuthorityId) ||
+        !isFinancialSavingsRecord(value.artifactGeneration) ||
+        !hasExactFinancialSavingsFields(value.artifactGeneration, ['runId', 'generatedAt']) ||
+        !isFinancialSavingsIdentity(value.artifactGeneration.runId) ||
+        !isFinancialSavingsIsoInstant(value.artifactGeneration.generatedAt) ||
+        !isFinancialSavingsIdentity(value.scopeId) ||
+        value.scopeId !== normalizeResourceScope(value.scopeId) ||
+        !Array.isArray(value.coordinates) ||
+        value.coordinates.length === 0 ||
+        value.coordinates.length > 128)
+        return false;
+    const projection = value;
+    return (projection.coordinates.every(coordinate => isSavingsResourceCoordinate(coordinate, projection.scopeId)) &&
+        new Set(projection.coordinates.map(coordinate => coordinate.coordinateId)).size === projection.coordinates.length);
+};
+/** Verifies that the bounded savings projection is the exact companion of one bounded Financial Authority projection. */
+export const isFinancialSavingsResourceProjectionBoundToFinancialProjectionV1 = (value, financialProjection) => {
+    if (!isFinancialSavingsResourceProjectionV1(value))
+        return false;
+    const financialCoordinateIds = financialProjection.coordinates.map(coordinate => coordinate.coordinateId);
+    const displayOwnerScopeIdsByCoordinate = new Map(financialProjection.coordinates.map(coordinate => [
+        coordinate.coordinateId,
+        new Set((coordinate.displayMemberBaselines ?? []).map(baseline => normalizeResourceScope(baseline.scopeId))),
+    ]));
+    return (value.financialAuthorityId === financialProjection.authorityId &&
+        normalizeResourceScope(value.scopeId) === normalizeResourceScope(financialProjection.scopeId) &&
+        value.artifactGeneration.runId === financialProjection.artifactGeneration.runId &&
+        value.artifactGeneration.generatedAt === financialProjection.artifactGeneration.generatedAt &&
+        haveSameFinancialSavingsSet(value.coordinates.map(coordinate => coordinate.coordinateId), financialCoordinateIds) &&
+        value.coordinates.every(coordinate => {
+            if (coordinate.status === 'unavailable')
+                return true;
+            const allowedDisplayOwners = displayOwnerScopeIdsByCoordinate.get(coordinate.coordinateId);
+            if (!allowedDisplayOwners)
+                return false;
+            return ((coordinate.displayMemberResourceContributions ?? []).every(contribution => allowedDisplayOwners.has(normalizeResourceScope(contribution.ownerScopeId))) &&
+                (coordinate.displayMemberRecommendationContributions ?? []).every(contribution => allowedDisplayOwners.has(normalizeResourceScope(contribution.ownerScopeId))));
+        }));
+};

package/dist/esm/azure/financialSavingsChargePolicyKernel.js

@@ -0,0 +1,29 @@
+import { resolveFinancialChargeInclusionPolicyV1 } from './financialChargeComposition.js';
+/**
+ * Classifies a savings allocation against one registered charge policy without
+ * splitting its money. A mixed or unknown affected-component set is
+ * unavailable because the allocation carries one reconciled delta, not a
+ * per-component delta that a consumer could apportion safely.
+ */
+export const classifyFinancialSavingsAllocationForPolicyV1 = (chargeCompositionByBaselineId, allocation, policyRef) => {
+    const policy = resolveFinancialChargeInclusionPolicyV1(policyRef);
+    if (!policy || allocation.billableComponentIds.length === 0)
+        return 'unavailable';
+    const composition = chargeCompositionByBaselineId.get(allocation.baselineId);
+    if (!composition)
+        return 'unavailable';
+    const sourceByComponentId = new Map(composition.buckets.flatMap(bucket => bucket.componentIds.map(componentId => [componentId, bucket.chargeSource])));
+    const dispositions = new Set();
+    for (const componentId of allocation.billableComponentIds) {
+        const source = sourceByComponentId.get(componentId);
+        if (!source || policy.withholdSources.includes(source))
+            return 'unavailable';
+        if (policy.includeSources.includes(source))
+            dispositions.add('included');
+        else if (policy.excludeSources.includes(source))
+            dispositions.add('excluded');
+        else
+            return 'unavailable';
+    }
+    return dispositions.size === 1 ? [...dispositions][0] : 'unavailable';
+};

package/dist/esm/azure/financialSavingsCoordinateValidation.js

@@ -23,8 +23,17 @@ const ACTIVATION_REASONS = new Set([
     'lifecycle-conflict',
     'unrecognized-lifecycle',
     'generation-mismatch',
+    'projection-unavailable',
+    'eligibility-unavailable',
+]);
+const UNAVAILABLE_ACTIVATION_REASONS = new Set([
+    'lifecycle-stale',
+    'lifecycle-unavailable',
+    'lifecycle-conflict',
+    'generation-mismatch',
+    'projection-unavailable',
+    'eligibility-unavailable',
 ]);
-const UNAVAILABLE_ACTIVATION_REASONS = new Set(['lifecycle-stale', 'lifecycle-unavailable', 'lifecycle-conflict', 'generation-mismatch']);
 export const canonicalizeFinancialSavingsDenominatorIdentityV1 = (value) => JSON.stringify(canonicalizeFinancialSavingsJsonValue({
     kind: value.kind,
     baselineId: value.baselineId,
@@ -35,7 +44,8 @@ export const canonicalizeFinancialSavingsDenominatorIdentityV1 = (value) => JSON
 export const createFinancialSavingsDenominatorIdV1 = (value) => `sha256:${sha256Utf8(canonicalizeFinancialSavingsDenominatorIdentityV1(value))}`;
 export const canonicalizeFinancialSavingsActivationIdentityV1 = (value) => JSON.stringify(canonicalizeFinancialSavingsJsonValue({
     recommendationId: value.recommendationId,
-    projectionId: value.projectionId,
+    scenarioId: value.scenarioId,
+    ...(value.projectionId === undefined ? {} : { projectionId: value.projectionId }),
     lifecycleState: value.lifecycleState,
     lifecycleVersion: value.lifecycleVersion,
     lifecycleEvidenceRefId: value.lifecycleEvidenceRefId,
@@ -49,10 +59,11 @@ export const canonicalizeFinancialSavingsAllocationIdentityV1 = (value) => JSON.
     ownerScopeId: value.ownerScopeId,
     billableComponentIds: [...value.billableComponentIds].sort(),
     recommendationId: value.recommendationId,
+    scenarioId: value.scenarioId,
     baselineId: value.baselineId,
     projectionId: value.projectionId,
     denominatorId: value.denominatorId,
-    eligibility: value.eligibility.kind === 'not-applicable'
+    eligibility: value.eligibility.kind !== 'mapped'
         ? value.eligibility
         : {
             ...value.eligibility,
@@ -98,10 +109,23 @@ const isActivationDecision = (state, result, reason) => {
     return UNAVAILABLE_ACTIVATION_REASONS.has(reason);
 };
 const isEligibility = (value) => {
-    if (!isFinancialSavingsRecord(value) || (value.kind !== 'not-applicable' && value.kind !== 'mapped'))
+    if (!isFinancialSavingsRecord(value) || !['not-applicable', 'unavailable', 'mapped'].includes(String(value.kind)))
         return false;
     if (value.kind === 'not-applicable')
         return Object.keys(value).length === 1;
+    if (value.kind === 'unavailable') {
+        return (Object.keys(value).length === 2 &&
+            typeof value.reason === 'string' &&
+            [
+                'rule-evidence-unavailable',
+                'eligibility-baseline-unavailable',
+                'eligible-components-unavailable',
+                'denominator-unavailable',
+                'current-baseline-mapping-unavailable',
+                'currency-conflict',
+                'reconciliation-failure',
+            ].includes(value.reason));
+    }
     return (Object.keys(value).length === 5 &&
         isFinancialSavingsHash(value.eligibilityId) &&
         isFinancialSavingsHash(value.eligibilityBaselineId) &&
@@ -114,7 +138,7 @@ const isEligibility = (value) => {
         value.eligibilityComponentIds.every(isFinancialSavingsIdentity) &&
         new Set(value.eligibilityComponentIds).size === value.eligibilityComponentIds.length);
 };
-const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById, evidenceById, authorityGeneratedAt, authorityRunId) => {
+const validateComposedCoordinate = (value, authorityCoordinate, eligibilityById, evidenceById, authorityGeneratedAt, authorityRunId) => {
     if (!hasExactFinancialSavingsFields(value, [
         'status',
         'coordinateId',
@@ -126,6 +150,7 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
         'activations',
         'allocations',
         'resourceContributions',
+        'recommendationContributions',
         'aggregate',
     ]) ||
         !isFinancialSavingsHash(value.currentAggregateBaselineId) ||
@@ -139,7 +164,7 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
         value.roundingMode !== 'half-away-from-zero' ||
         !isFinancialSavingsRecord(value.scenarioCoverage) ||
         !hasExactFinancialSavingsFields(value.scenarioCoverage, ['status', 'evidenceRefId', 'scenarioIds']) ||
-        value.scenarioCoverage.status !== 'complete' ||
+        value.scenarioCoverage.status !== (value.status === 'available' ? 'complete' : 'partial') ||
         !isFinancialSavingsHash(value.scenarioCoverage.evidenceRefId) ||
         !Array.isArray(value.scenarioCoverage.scenarioIds) ||
         value.scenarioCoverage.scenarioIds.length > 20000 ||
@@ -151,6 +176,8 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
         value.allocations.length > 20000 ||
         !Array.isArray(value.resourceContributions) ||
         value.resourceContributions.length > 20000 ||
+        !Array.isArray(value.recommendationContributions) ||
+        value.recommendationContributions.length > 20000 ||
         !isFinancialSavingsRecord(value.aggregate) ||
         !hasExactFinancialSavingsFields(value.aggregate, ['allocationIds', 'savingsMinorUnits']) ||
         !Array.isArray(value.aggregate.allocationIds) ||
@@ -163,15 +190,17 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
         Date.parse(scenarioCoverageEvidence.intrinsicTime.at) > Date.parse(authorityGeneratedAt))
         return false;
     const projectionById = new Map(authorityCoordinate.projections.flatMap(projection => (projection.status === 'available' ? [[projection.projectionId, projection]] : [])));
+    const availableProjectionScenarioIds = new Set(authorityCoordinate.projections.flatMap(projection => (projection.status === 'available' ? [projection.scenarioId] : [])));
+    const unavailableEligibilityScenarioIds = new Set([...eligibilityById.values()].flatMap(assessment => (assessment.status === 'unavailable' ? [assessment.scenarioId] : [])));
     const activationById = new Map();
-    const activationByRecommendationId = new Map();
+    const activationByScenarioId = new Map();
     for (const activation of value.activations) {
         const lifecycleEvidence = evidenceById.get(activation.lifecycleEvidenceRefId);
         if (!isFinancialSavingsRecord(activation) ||
             !hasExactFinancialSavingsFields(activation, [
                 'activationId',
+                'scenarioId',
                 'recommendationId',
-                'projectionId',
                 'lifecycleState',
                 'lifecycleVersion',
                 'lifecycleEvidenceRefId',
@@ -179,19 +208,29 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
                 'reason',
                 'evaluatedAt',
                 'policyVersion',
-            ]) ||
+            ], ['projectionId']) ||
             !isFinancialSavingsHash(activation.activationId) ||
             activationById.has(activation.activationId) ||
-            activationByRecommendationId.has(activation.recommendationId) ||
+            activationByScenarioId.has(activation.scenarioId) ||
+            !isFinancialSavingsIdentity(activation.scenarioId) ||
             !isFinancialSavingsIdentity(activation.recommendationId) ||
-            !isFinancialSavingsHash(activation.projectionId) ||
+            (activation.projectionId !== undefined && !isFinancialSavingsHash(activation.projectionId)) ||
             !isFinancialSavingsIdentity(activation.lifecycleVersion) ||
             !isFinancialSavingsHash(activation.lifecycleEvidenceRefId) ||
             !isActivationDecision(activation.lifecycleState, activation.result, activation.reason) ||
             !isFinancialSavingsIsoInstant(activation.evaluatedAt) ||
             Date.parse(activation.evaluatedAt) > Date.parse(authorityGeneratedAt) ||
             !isFinancialSavingsIdentity(activation.policyVersion) ||
-            projectionById.get(activation.projectionId)?.scenarioId !== activation.recommendationId ||
+            (activation.result === 'included' &&
+                (activation.projectionId === undefined || projectionById.get(activation.projectionId)?.scenarioId !== activation.scenarioId)) ||
+            (activation.result === 'excluded' &&
+                activation.projectionId !== undefined &&
+                projectionById.get(activation.projectionId)?.scenarioId !== activation.scenarioId) ||
+            (activation.result === 'unavailable' &&
+                (activation.projectionId !== undefined ||
+                    (activation.reason === 'projection-unavailable' && availableProjectionScenarioIds.has(activation.scenarioId)) ||
+                    (activation.reason === 'eligibility-unavailable' &&
+                        !unavailableEligibilityScenarioIds.has(activation.scenarioId)))) ||
             lifecycleEvidence?.role !== 'recommendation-lifecycle' ||
             lifecycleEvidence.revisionId !== activation.lifecycleVersion ||
             Date.parse(lifecycleEvidence.intrinsicTime.at) > Date.parse(authorityGeneratedAt))
@@ -200,12 +239,15 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
         if (activation.activationId !== createFinancialSavingsActivationIdV1(activationIdentity))
             return false;
         activationById.set(activation.activationId, activation);
-        activationByRecommendationId.set(activation.recommendationId, activation);
+        activationByScenarioId.set(activation.scenarioId, activation);
     }
     const coveredScenarioIds = new Set(value.scenarioCoverage.scenarioIds);
-    const activatedScenarioIds = new Set(value.activations.map(activation => activation.recommendationId));
+    const activatedScenarioIds = new Set(value.activations.map(activation => activation.scenarioId));
     if (value.scenarioCoverage.scenarioIds.some(scenarioId => !activatedScenarioIds.has(scenarioId)) ||
-        value.activations.some(activation => !coveredScenarioIds.has(activation.recommendationId)))
+        value.activations.some(activation => !coveredScenarioIds.has(activation.scenarioId)))
+        return false;
+    const hasUnavailableActivation = value.activations.some(activation => activation.result === 'unavailable');
+    if ((value.status === 'available' && hasUnavailableActivation) || (value.status === 'partial' && !hasUnavailableActivation))
         return false;
     const allocationById = new Map();
     const allocatedBaselineComponents = new Set();
@@ -215,7 +257,7 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
         const eligibility = allocation.eligibility.kind === 'mapped' ? eligibilityById.get(allocation.eligibility.eligibilityId) : undefined;
         const expectedDenominatorId = allocation.eligibility.kind === 'mapped' && eligibility?.status === 'available'
             ? eligibility.denominator.denominatorId
-            : projection
+            : allocation.eligibility.kind === 'not-applicable' && projection
                 ? createFinancialSavingsDenominatorIdV1({
                     kind: 'projection-affected-current',
                     baselineId: projection.baselineId,
@@ -229,6 +271,7 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
                 'allocationId',
                 'ownerScopeId',
                 'billableComponentIds',
+                'scenarioId',
                 'recommendationId',
                 'baselineId',
                 'projectionId',
@@ -245,6 +288,7 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
             allocation.billableComponentIds.length > 20000 ||
             !allocation.billableComponentIds.every(isFinancialSavingsIdentity) ||
             new Set(allocation.billableComponentIds).size !== allocation.billableComponentIds.length ||
+            !isFinancialSavingsIdentity(allocation.scenarioId) ||
             !isFinancialSavingsIdentity(allocation.recommendationId) ||
             !isFinancialSavingsHash(allocation.baselineId) ||
             !isFinancialSavingsHash(allocation.projectionId) ||
@@ -258,15 +302,17 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
             projection.baselineId !== allocation.baselineId ||
             !haveSameFinancialSavingsSet(projection.affectedComponentIds, allocation.billableComponentIds) ||
             decimalToMinorUnits(projection.change.savings, value.minorUnitScale) !== allocation.savingsMinorUnits ||
+            projection.scenarioId !== allocation.scenarioId ||
             !activation ||
             activation.result !== 'included' ||
+            activation.scenarioId !== allocation.scenarioId ||
             activation.recommendationId !== allocation.recommendationId ||
             activation.projectionId !== allocation.projectionId ||
             (allocation.eligibility.kind === 'mapped' &&
                 (!eligibility ||
                     eligibility.status !== 'available' ||
                     eligibility.scopeId !== allocation.ownerScopeId ||
-                    eligibility.scenarioId !== allocation.recommendationId ||
+                    eligibility.scenarioId !== allocation.scenarioId ||
                     eligibility.eligibilityBaselineId !== allocation.eligibility.eligibilityBaselineId ||
                     eligibility.denominator.denominatorId !== allocation.denominatorId ||
                     eligibility.currentBaselineMapping.currentBaselineId !== allocation.baselineId ||
@@ -307,8 +353,41 @@ const validateAvailableCoordinate = (value, authorityCoordinate, eligibilityById
         contributedAllocationIds.push(...contribution.allocationIds);
     }
     const allocationIds = [...allocationById.keys()];
+    const recommendationContributionAllocationIds = [];
+    const recommendationContributionKeys = new Set();
+    for (const contribution of value.recommendationContributions) {
+        if (!isFinancialSavingsRecord(contribution) ||
+            !hasExactFinancialSavingsFields(contribution, [
+                'ownerScopeId',
+                'recommendationId',
+                'allocationIds',
+                'savingsMinorUnits',
+            ]) ||
+            !isFinancialSavingsIdentity(contribution.ownerScopeId) ||
+            !isFinancialSavingsIdentity(contribution.recommendationId) ||
+            !Array.isArray(contribution.allocationIds) ||
+            contribution.allocationIds.length === 0 ||
+            contribution.allocationIds.length > 20000 ||
+            !contribution.allocationIds.every(isFinancialSavingsHash) ||
+            new Set(contribution.allocationIds).size !== contribution.allocationIds.length ||
+            !isFinancialSavingsMinorUnits(contribution.savingsMinorUnits))
+            return false;
+        const contributionKey = `${contribution.ownerScopeId}\u0000${contribution.recommendationId}`;
+        if (recommendationContributionKeys.has(contributionKey))
+            return false;
+        const allocations = contribution.allocationIds.map(id => allocationById.get(id));
+        if (allocations.some(allocation => !allocation ||
+            allocation.ownerScopeId !== contribution.ownerScopeId ||
+            allocation.recommendationId !== contribution.recommendationId) ||
+            sumFinancialSavingsMinorUnits(allocations.map(allocation => allocation.savingsMinorUnits)) !== contribution.savingsMinorUnits)
+            return false;
+        recommendationContributionKeys.add(contributionKey);
+        recommendationContributionAllocationIds.push(...contribution.allocationIds);
+    }
     return (haveSameFinancialSavingsSet(contributedAllocationIds, allocationIds) &&
         new Set(contributedAllocationIds).size === contributedAllocationIds.length &&
+        haveSameFinancialSavingsSet(recommendationContributionAllocationIds, allocationIds) &&
+        new Set(recommendationContributionAllocationIds).size === recommendationContributionAllocationIds.length &&
         haveSameFinancialSavingsSet(value.aggregate.allocationIds, allocationIds) &&
         new Set(value.aggregate.allocationIds).size === value.aggregate.allocationIds.length &&
         value.aggregate.savingsMinorUnits === sumFinancialSavingsMinorUnits(value.allocations.map(allocation => allocation.savingsMinorUnits)));
@@ -324,6 +403,6 @@ export const validateFinancialSavingsCoordinateEnvelopeV1 = (value, authorityCoo
                 ? value.currentAggregateBaselineId === authorityCoordinate.aggregateBaseline.baselineId
                 : value.currentAggregateBaselineId === undefined));
     }
-    return (value.status === 'available' &&
-        validateAvailableCoordinate(value, authorityCoordinate, eligibilityById, evidenceById, authorityGeneratedAt, authorityRunId));
+    return ((value.status === 'available' || value.status === 'partial') &&
+        validateComposedCoordinate(value, authorityCoordinate, eligibilityById, evidenceById, authorityGeneratedAt, authorityRunId));
 };

package/dist/esm/azure/financialSavingsPercentageKernel.js

@@ -0,0 +1,44 @@
+import { formatExactDecimalValue, sumCanonicalDecimals } from '../common/exactDecimal.js';
+/**
+ * Composes one exact percentage from allocation-bound denominator evidence.
+ * Repeated denominator identities are counted once; conflicting or missing
+ * evidence fails closed so no consumer substitutes display-resource spend.
+ */
+export const composeFinancialSavingsAllocationPercentageV1 = (allocations, minorUnitScale) => {
+    if (!Number.isSafeInteger(minorUnitScale) || minorUnitScale < 0 || minorUnitScale > 6 || allocations.length === 0) {
+        return undefined;
+    }
+    const denominators = new Map();
+    let savingsMinorUnits = 0n;
+    for (const allocation of allocations) {
+        if (!Number.isSafeInteger(allocation.savingsMinorUnits) || allocation.savingsMinorUnits < 0 || !allocation.denominator) {
+            return undefined;
+        }
+        savingsMinorUnits += BigInt(allocation.savingsMinorUnits);
+        const existing = denominators.get(allocation.denominator.denominatorId);
+        if (existing &&
+            (existing.amount !== allocation.denominator.amount || existing.currencyCode !== allocation.denominator.currencyCode)) {
+            return undefined;
+        }
+        denominators.set(allocation.denominator.denominatorId, {
+            amount: allocation.denominator.amount,
+            currencyCode: allocation.denominator.currencyCode,
+        });
+    }
+    if (savingsMinorUnits > BigInt(Number.MAX_SAFE_INTEGER))
+        return undefined;
+    const currencies = new Set([...denominators.values()].map(denominator => denominator.currencyCode));
+    if (currencies.size !== 1)
+        return undefined;
+    const denominatorAmount = formatExactDecimalValue(sumCanonicalDecimals([...denominators.values()].map(denominator => denominator.amount)));
+    const denominatorNumber = Number(denominatorAmount);
+    const savingsNumber = Number(savingsMinorUnits) / 10 ** minorUnitScale;
+    if (!Number.isFinite(denominatorNumber) || denominatorNumber <= 0 || !Number.isFinite(savingsNumber))
+        return undefined;
+    return {
+        denominatorIds: [...denominators.keys()].sort(),
+        denominatorAmount,
+        denominatorCurrencyCode: [...currencies][0],
+        percentage: (savingsNumber / denominatorNumber) * 100,
+    };
+};

package/dist/esm/azure/financialSavingsSurfaceProjection.js

@@ -1,2 +1,4 @@
 export const FINANCIAL_SAVINGS_SURFACE_PROJECTION_SCHEMA_VERSION_V1 = 1;
 export const FINANCIAL_SAVINGS_SURFACE_PROJECTION_CONTRACT_VERSION_V1 = 'financial-savings-surface-projection/v1';
+export const FINANCIAL_SAVINGS_QUERY_SELECTION_CONTRACT_VERSION_V1 = 'financial-savings-query-selection/v1';
+export const FINANCIAL_SAVINGS_RESOURCE_QUERY_SELECTION_CONTRACT_VERSION_V1 = 'financial-savings-resource-query-selection/v1';