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

package/dist/esm/azure/financialResourceSurfaceProjectionValidation.js

@@ -0,0 +1,243 @@
+import { formatExactDecimalValue, parseCanonicalDecimal, subtractExactDecimalValues } from '../common/exactDecimal.js';
+import { sha256Utf8 } from '../common/sha256.js';
+import { FINANCIAL_RESOURCE_SURFACE_PROJECTION_CONTRACT_VERSION_V1, FINANCIAL_RESOURCE_SURFACE_PROJECTION_SCHEMA_VERSION_V1, } from './financialResourceSurfaceProjection.js';
+import { isFinancialSurfaceCoordinateDefinitionV1, isFinancialSurfaceMoneyV1, } from './financialCurrentSpendSurfaceProjectionValidation.js';
+import { canonicalizeFinancialSavingsJsonValue, hasExactFinancialSavingsFields, isFinancialSavingsHash, isFinancialSavingsIdentity, isFinancialSavingsIsoInstant, isFinancialSavingsRecord, } from './financialSavingsAuthorityValidationPrimitives.js';
+import { isCanonicalExactMoney } from './financialValidationPrimitives.js';
+const MAX_COORDINATES = 128;
+const MAX_RESOURCES = 50000;
+const MAX_VALUES_PER_RESOURCE = 128;
+const MAX_SCENARIOS_PER_RESOURCE = 1024;
+const MAX_REASONS = 64;
+const RESOURCE_ROLES = new Set(['owner', 'display-only', 'unclassified']);
+const SCENARIO_CATEGORIES = new Set(['cost', 'security', 'reliability', 'performance', 'operational-excellence', 'compliance']);
+const CURRENCY = /^[A-Z]{3}$/;
+const isCurrency = (value) => typeof value === 'string' && CURRENCY.test(value);
+const isReasonCodes = (value) => Array.isArray(value) &&
+    value.length > 0 &&
+    value.length <= MAX_REASONS &&
+    value.every(isFinancialSavingsIdentity) &&
+    new Set(value).size === value.length;
+const isExactAmount = (amount, currencyCode) => isCurrency(currencyCode) && isCanonicalExactMoney({ amount, currencyCode });
+const isScenario = (value, coordinateIds, requestedCurrencyCode) => {
+    if (!isFinancialSavingsRecord(value))
+        return false;
+    const commonValid = isFinancialSavingsIdentity(value.scenarioId) &&
+        isFinancialSavingsHash(value.coordinateId) &&
+        coordinateIds.has(value.coordinateId) &&
+        (value.recommendationId === undefined || isFinancialSavingsIdentity(value.recommendationId)) &&
+        typeof value.category === 'string' &&
+        SCENARIO_CATEGORIES.has(value.category) &&
+        value.additivity === 'non-additive';
+    if (!commonValid)
+        return false;
+    const optionalCommon = ['recommendationId'];
+    if (value.status === 'available') {
+        if (!hasExactFinancialSavingsFields(value, [
+            'scenarioId',
+            'coordinateId',
+            'category',
+            'additivity',
+            'status',
+            'currentAmount',
+            'targetAmount',
+            'changeAmount',
+            'currencyCode',
+        ], optionalCommon) ||
+            !isExactAmount(value.currentAmount, value.currencyCode) ||
+            !isExactAmount(value.targetAmount, value.currencyCode) ||
+            !isExactAmount(value.changeAmount, value.currencyCode) ||
+            (requestedCurrencyCode !== undefined && value.currencyCode !== requestedCurrencyCode))
+            return false;
+        return (value.changeAmount ===
+            formatExactDecimalValue(subtractExactDecimalValues(parseCanonicalDecimal(value.targetAmount), parseCanonicalDecimal(value.currentAmount))));
+    }
+    if (value.status === 'unavailable') {
+        return hasExactFinancialSavingsFields(value, ['scenarioId', 'coordinateId', 'category', 'additivity', 'status', 'reasonCodes'], optionalCommon) && isReasonCodes(value.reasonCodes);
+    }
+    if (value.status !== 'partial')
+        return false;
+    if (!hasExactFinancialSavingsFields(value, ['scenarioId', 'coordinateId', 'category', 'additivity', 'status', 'reasonCodes'], [...optionalCommon, 'currentAmount', 'targetAmount', 'changeAmount', 'currencyCode']) ||
+        !isReasonCodes(value.reasonCodes))
+        return false;
+    const monetaryFields = [value.currentAmount, value.targetAmount, value.changeAmount];
+    const presentAmounts = monetaryFields.filter(amount => amount !== undefined);
+    if (presentAmounts.length === 0)
+        return value.currencyCode === undefined;
+    return (isCurrency(value.currencyCode) &&
+        (requestedCurrencyCode === undefined || value.currencyCode === requestedCurrencyCode) &&
+        presentAmounts.every(amount => isExactAmount(amount, value.currencyCode)));
+};
+const canonicalizeValue = (value) => value.status === 'available' ? value : { ...value, reasonCodes: [...value.reasonCodes].sort() };
+const canonicalizeScenario = (value) => value.status === 'available' ? value : { ...value, reasonCodes: [...value.reasonCodes].sort() };
+export const canonicalizeFinancialResourceSurfaceProjectionIdentityV1 = (value) => JSON.stringify(canonicalizeFinancialSavingsJsonValue({
+    ...value,
+    providerAccountRefs: [...value.providerAccountRefs].sort(),
+    coordinates: [...value.coordinates].sort((left, right) => left.coordinateId.localeCompare(right.coordinateId)),
+    resources: [...value.resources]
+        .sort((left, right) => left.resourceId.localeCompare(right.resourceId))
+        .map(resource => ({
+        ...resource,
+        values: [...resource.values]
+            .sort((left, right) => left.coordinateId.localeCompare(right.coordinateId))
+            .map(canonicalizeValue),
+        ...(resource.scenarios === undefined
+            ? {}
+            : {
+                scenarios: [...resource.scenarios]
+                    .sort((left, right) => left.scenarioId.localeCompare(right.scenarioId) || left.coordinateId.localeCompare(right.coordinateId))
+                    .map(canonicalizeScenario),
+            }),
+    })),
+}));
+export const createFinancialResourceSurfaceProjectionIdV1 = (value) => `sha256:${sha256Utf8(canonicalizeFinancialResourceSurfaceProjectionIdentityV1(value))}`;
+/**
+ * Selects one resource member without copying unrelated members or coordinates.
+ * The returned projection remains independently content-addressed and valid.
+ */
+export const projectFinancialResourceSurfaceMemberV1 = (source, resourceId) => {
+    if (!isFinancialResourceSurfaceProjectionV1(source)) {
+        throw new TypeError('Invalid FinancialResourceSurfaceProjectionV1.');
+    }
+    const normalizedResourceId = resourceId.trim().toLowerCase().replace(/\/+$/, '');
+    const member = source.resources.find(candidate => candidate.resourceId.trim().toLowerCase().replace(/\/+$/, '') === normalizedResourceId);
+    if (!member)
+        return undefined;
+    const coordinateIds = new Set([
+        ...member.values.map(value => value.coordinateId),
+        ...(member.scenarios ?? []).map(scenario => scenario.coordinateId),
+    ]);
+    const identity = {
+        schemaVersion: source.schemaVersion,
+        contractVersion: source.contractVersion,
+        provider: source.provider,
+        providerAccountRefs: [...source.providerAccountRefs],
+        artifactGeneration: source.artifactGeneration,
+        financialAuthorityId: source.financialAuthorityId,
+        coordinates: source.coordinates.filter(coordinate => coordinateIds.has(coordinate.coordinateId)),
+        resources: [member],
+    };
+    const projection = {
+        ...identity,
+        projectionId: createFinancialResourceSurfaceProjectionIdV1(identity),
+    };
+    if (!isFinancialResourceSurfaceProjectionV1(projection)) {
+        throw new TypeError('Invalid projected FinancialResourceSurfaceProjectionV1.');
+    }
+    return projection;
+};
+/**
+ * Removes mutable recommendation scenarios while preserving authoritative
+ * current-spend values. Used when lifecycle state is newer than the immutable
+ * financial artifact.
+ */
+export const projectFinancialResourceSurfaceWithoutScenariosV1 = (source) => {
+    if (!isFinancialResourceSurfaceProjectionV1(source)) {
+        throw new TypeError('Invalid FinancialResourceSurfaceProjectionV1.');
+    }
+    const referencedCoordinateIds = new Set(source.resources.flatMap(resource => resource.values.map(value => value.coordinateId)));
+    const identity = {
+        schemaVersion: source.schemaVersion,
+        contractVersion: source.contractVersion,
+        provider: source.provider,
+        providerAccountRefs: [...source.providerAccountRefs],
+        artifactGeneration: source.artifactGeneration,
+        financialAuthorityId: source.financialAuthorityId,
+        coordinates: source.coordinates.filter(coordinate => referencedCoordinateIds.has(coordinate.coordinateId)),
+        resources: source.resources.map(resource => {
+            const { scenarios: _scenarios, ...currentSpendOnly } = resource;
+            return currentSpendOnly;
+        }),
+    };
+    const projection = {
+        ...identity,
+        projectionId: createFinancialResourceSurfaceProjectionIdV1(identity),
+    };
+    if (!isFinancialResourceSurfaceProjectionV1(projection)) {
+        throw new TypeError('Invalid current-spend-only FinancialResourceSurfaceProjectionV1.');
+    }
+    return projection;
+};
+export const isFinancialResourceSurfaceProjectionV1 = (value) => {
+    if (!isFinancialSavingsRecord(value) ||
+        !hasExactFinancialSavingsFields(value, [
+            'schemaVersion',
+            'contractVersion',
+            'projectionId',
+            'provider',
+            'providerAccountRefs',
+            'artifactGeneration',
+            'financialAuthorityId',
+            'coordinates',
+            'resources',
+        ]) ||
+        value.schemaVersion !== FINANCIAL_RESOURCE_SURFACE_PROJECTION_SCHEMA_VERSION_V1 ||
+        value.contractVersion !== FINANCIAL_RESOURCE_SURFACE_PROJECTION_CONTRACT_VERSION_V1 ||
+        !isFinancialSavingsHash(value.projectionId) ||
+        value.provider !== 'azure' ||
+        !Array.isArray(value.providerAccountRefs) ||
+        value.providerAccountRefs.length === 0 ||
+        value.providerAccountRefs.length > 64 ||
+        !value.providerAccountRefs.every(isFinancialSavingsIdentity) ||
+        new Set(value.providerAccountRefs).size !== value.providerAccountRefs.length ||
+        !isFinancialSavingsRecord(value.artifactGeneration) ||
+        !hasExactFinancialSavingsFields(value.artifactGeneration, ['runId', 'generatedAt']) ||
+        !isFinancialSavingsIdentity(value.artifactGeneration.runId) ||
+        !isFinancialSavingsIsoInstant(value.artifactGeneration.generatedAt) ||
+        !isFinancialSavingsHash(value.financialAuthorityId) ||
+        !Array.isArray(value.coordinates) ||
+        value.coordinates.length === 0 ||
+        value.coordinates.length > MAX_COORDINATES ||
+        !value.coordinates.every(isFinancialSurfaceCoordinateDefinitionV1) ||
+        new Set(value.coordinates.map(coordinate => coordinate.coordinateId)).size !== value.coordinates.length ||
+        !Array.isArray(value.resources) ||
+        value.resources.length > MAX_RESOURCES)
+        return false;
+    const coordinateById = new Map(value.coordinates.map(coordinate => [coordinate.coordinateId, coordinate]));
+    const coordinateIds = new Set(coordinateById.keys());
+    const resourceIds = new Set();
+    for (const resource of value.resources) {
+        if (!isFinancialSavingsRecord(resource) ||
+            !hasExactFinancialSavingsFields(resource, ['resourceId', 'resourceType', 'financialRole', 'values'], ['scenarios']) ||
+            !isFinancialSavingsIdentity(resource.resourceId) ||
+            resourceIds.has(resource.resourceId.toLowerCase()) ||
+            !isFinancialSavingsIdentity(resource.resourceType) ||
+            typeof resource.financialRole !== 'string' ||
+            !RESOURCE_ROLES.has(resource.financialRole) ||
+            !Array.isArray(resource.values) ||
+            resource.values.length === 0 ||
+            resource.values.length > MAX_VALUES_PER_RESOURCE)
+            return false;
+        resourceIds.add(resource.resourceId.toLowerCase());
+        const valueCoordinates = new Set();
+        for (const memberValue of resource.values) {
+            if (!isFinancialSavingsRecord(memberValue) || !isFinancialSavingsHash(memberValue.coordinateId))
+                return false;
+            const definition = coordinateById.get(memberValue.coordinateId);
+            if (definition === undefined || valueCoordinates.has(memberValue.coordinateId))
+                return false;
+            const money = Object.fromEntries(Object.entries(memberValue).filter(([key]) => key !== 'coordinateId'));
+            if (!isFinancialSurfaceMoneyV1(money, definition.requestedCurrencyCode))
+                return false;
+            valueCoordinates.add(memberValue.coordinateId);
+        }
+        if (resource.scenarios !== undefined) {
+            if (!Array.isArray(resource.scenarios) || resource.scenarios.length > MAX_SCENARIOS_PER_RESOURCE)
+                return false;
+            const scenarioCoordinates = new Set();
+            for (const scenario of resource.scenarios) {
+                if (!isFinancialSavingsRecord(scenario) || !isFinancialSavingsHash(scenario.coordinateId))
+                    return false;
+                const definition = coordinateById.get(scenario.coordinateId);
+                if (definition === undefined ||
+                    !isScenario(scenario, coordinateIds, definition.requestedCurrencyCode) ||
+                    scenarioCoordinates.has(`${scenario.scenarioId}\u0000${scenario.coordinateId}`))
+                    return false;
+                scenarioCoordinates.add(`${scenario.scenarioId}\u0000${scenario.coordinateId}`);
+            }
+        }
+    }
+    const projection = value;
+    const { projectionId: _projectionId, ...identity } = projection;
+    return projection.projectionId === createFinancialResourceSurfaceProjectionIdV1(identity);
+};

package/dist/esm/azure/financialSavingsAuthority.js

@@ -0,0 +1,5 @@
+export const FINANCIAL_SAVINGS_AUTHORITY_SCHEMA_VERSION_V1 = 1;
+export const FINANCIAL_SAVINGS_AUTHORITY_CONTRACT_VERSION_V1 = 'financial-savings-authority/v1';
+export const FINANCIAL_SAVINGS_RESOURCE_PROJECTION_CONTRACT_VERSION_V1 = 'financial-savings-resource-projection/v1';
+export const FINANCIAL_ELIGIBILITY_ASSESSMENT_SCHEMA_VERSION_V1 = 1;
+export const FINANCIAL_ELIGIBILITY_ASSESSMENT_CONTRACT_VERSION_V1 = 'financial-eligibility-assessment/v1';

package/dist/esm/azure/financialSavingsAuthorityValidation.js

@@ -0,0 +1,298 @@
+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 { 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({
+    schemaVersion: value.schemaVersion,
+    contractVersion: value.contractVersion,
+    financialAuthorityId: value.financialAuthorityId,
+    artifactGeneration: value.artifactGeneration,
+    eligibilityBaselines: [...value.eligibilityBaselines].sort((left, right) => left.baselineId.localeCompare(right.baselineId)),
+    eligibilityAssessments: [...value.eligibilityAssessments].sort((left, right) => left.eligibilityId.localeCompare(right.eligibilityId)),
+    coordinates: [...value.coordinates]
+        .sort((left, right) => left.coordinateId.localeCompare(right.coordinateId))
+        .map(coordinate => coordinate.status === 'unavailable'
+        ? coordinate
+        : {
+            ...coordinate,
+            scenarioCoverage: {
+                ...coordinate.scenarioCoverage,
+                scenarioIds: [...coordinate.scenarioCoverage.scenarioIds].sort(),
+            },
+            activations: [...coordinate.activations].sort((left, right) => left.activationId.localeCompare(right.activationId)),
+            allocations: [...coordinate.allocations]
+                .sort((left, right) => left.allocationId.localeCompare(right.allocationId))
+                .map(allocation => ({
+                ...allocation,
+                billableComponentIds: [...allocation.billableComponentIds].sort(),
+                eligibility: allocation.eligibility.kind !== 'mapped'
+                    ? allocation.eligibility
+                    : {
+                        ...allocation.eligibility,
+                        currentComponentIds: [...allocation.eligibility.currentComponentIds].sort(),
+                        eligibilityComponentIds: [...allocation.eligibility.eligibilityComponentIds].sort(),
+                    },
+            })),
+            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() },
+        }),
+}));
+export const createFinancialSavingsAuthorityIdV1 = (value) => `sha256:${sha256Utf8(canonicalizeFinancialSavingsAuthorityIdentityV1(value))}`;
+const buildEligibilityContext = (authority) => {
+    const bundleById = new Map(authority.evidenceBundles.map(bundle => [bundle.bundleId, bundle]));
+    const assessmentById = new Map(authority.evidenceAssessments.map(assessment => [assessment.assessmentId, assessment]));
+    if (bundleById.size !== authority.evidenceBundles.length || assessmentById.size !== authority.evidenceAssessments.length)
+        return undefined;
+    const evidenceById = new Map();
+    for (const reference of authority.evidenceBundles.flatMap(bundle => bundle.references)) {
+        const existing = evidenceById.get(reference.evidenceRefId);
+        if (existing &&
+            JSON.stringify(canonicalizeFinancialSavingsJsonValue(existing)) !== JSON.stringify(canonicalizeFinancialSavingsJsonValue(reference)))
+            return undefined;
+        evidenceById.set(reference.evidenceRefId, reference);
+    }
+    return { authority, bundleById, assessmentById, evidenceById };
+};
+export const isFinancialSavingsAuthorityBoundToFinancialAuthorityV1 = (value, authority) => {
+    if (!isFinancialSavingsRecord(value) ||
+        !hasExactFinancialSavingsFields(value, [
+            'schemaVersion',
+            'contractVersion',
+            'savingsAuthorityId',
+            'financialAuthorityId',
+            'artifactGeneration',
+            'eligibilityBaselines',
+            'eligibilityAssessments',
+            'coordinates',
+        ]) ||
+        value.schemaVersion !== FINANCIAL_SAVINGS_AUTHORITY_SCHEMA_VERSION_V1 ||
+        value.contractVersion !== FINANCIAL_SAVINGS_AUTHORITY_CONTRACT_VERSION_V1 ||
+        !isFinancialSavingsHash(value.savingsAuthorityId) ||
+        value.financialAuthorityId !== authority.authorityId ||
+        !isFinancialSavingsRecord(value.artifactGeneration) ||
+        !hasExactFinancialSavingsFields(value.artifactGeneration, ['runId', 'generatedAt']) ||
+        value.artifactGeneration.runId !== authority.artifactGeneration.runId ||
+        value.artifactGeneration.generatedAt !== authority.artifactGeneration.generatedAt ||
+        !Array.isArray(value.eligibilityBaselines) ||
+        value.eligibilityBaselines.length > 20000 ||
+        !Array.isArray(value.eligibilityAssessments) ||
+        value.eligibilityAssessments.length > 20000 ||
+        !Array.isArray(value.coordinates) ||
+        value.coordinates.length !== authority.coordinates.length ||
+        value.coordinates.length === 0 ||
+        value.coordinates.length > 128)
+        return false;
+    const context = buildEligibilityContext(authority);
+    if (!context)
+        return false;
+    const savingsAuthority = value;
+    if (!savingsAuthority.eligibilityBaselines.every(baseline => validateFinancialEligibilityBaselineV1(baseline, context)))
+        return false;
+    const eligibilityBaselineById = new Map(savingsAuthority.eligibilityBaselines.map(baseline => [baseline.baselineId, baseline]));
+    if (eligibilityBaselineById.size !== savingsAuthority.eligibilityBaselines.length)
+        return false;
+    if (!savingsAuthority.eligibilityAssessments.every(assessment => validateFinancialEligibilityAssessmentV1(assessment, context, eligibilityBaselineById)))
+        return false;
+    const eligibilityById = new Map(savingsAuthority.eligibilityAssessments.map(assessment => [assessment.eligibilityId, assessment]));
+    if (eligibilityById.size !== savingsAuthority.eligibilityAssessments.length)
+        return false;
+    const authorityCoordinateById = new Map(authority.coordinates.map(coordinate => [coordinate.coordinateId, coordinate]));
+    if (new Set(savingsAuthority.coordinates.map(coordinate => coordinate.coordinateId)).size !== savingsAuthority.coordinates.length ||
+        !savingsAuthority.coordinates.every(coordinate => {
+            const authorityCoordinate = authorityCoordinateById.get(coordinate.coordinateId);
+            return (authorityCoordinate !== undefined &&
+                validateFinancialSavingsCoordinateEnvelopeV1(coordinate, authorityCoordinate, eligibilityById, context.evidenceById, authority.artifactGeneration.generatedAt, authority.artifactGeneration.runId));
+        }))
+        return false;
+    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/financialSavingsAuthorityValidationPrimitives.js

@@ -0,0 +1,31 @@
+const SHA256_ID = /^sha256:[0-9a-f]{64}$/;
+export const isFinancialSavingsRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+export const hasExactFinancialSavingsFields = (value, required, optional = []) => {
+    const allowed = new Set([...required, ...optional]);
+    const keys = Object.keys(value);
+    return required.every(field => Object.prototype.hasOwnProperty.call(value, field)) && keys.every(field => allowed.has(field));
+};
+export const isFinancialSavingsIdentity = (value) => typeof value === 'string' && value.length > 0 && value.length <= 2048 && value.trim() === value;
+export const isFinancialSavingsHash = (value) => typeof value === 'string' && SHA256_ID.test(value);
+export const isFinancialSavingsMinorUnits = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+export const isFinancialSavingsIsoInstant = (value) => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value) && Number.isFinite(Date.parse(value));
+export const haveSameFinancialSavingsSet = (left, right) => {
+    if (left.length !== right.length)
+        return false;
+    const sortedLeft = [...left].sort();
+    const sortedRight = [...right].sort();
+    return sortedLeft.every((value, index) => value === sortedRight[index]);
+};
+export const sumFinancialSavingsMinorUnits = (values) => {
+    const total = values.reduce((sum, value) => sum + BigInt(value), 0n);
+    return total <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(total) : undefined;
+};
+export const canonicalizeFinancialSavingsJsonValue = (value) => {
+    if (Array.isArray(value))
+        return value.map(canonicalizeFinancialSavingsJsonValue);
+    if (!isFinancialSavingsRecord(value))
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map(key => [key, canonicalizeFinancialSavingsJsonValue(value[key])]));
+};

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