@spottoai/types-package 1.0.2-beta.36 → 1.0.2-beta.360

package/dist/esm/aws/portalPublicArtifactCurrentValidation.js

@@ -0,0 +1,328 @@
+import { AWS_PORTAL_ACCOUNT_SUMMARY_LOGICAL_NAME, AWS_PORTAL_RESOURCE_COLLECTION_LOGICAL_NAME, } from './portalPublicArtifacts.js';
+import { asRecord, assertExactKeys, assertPublicJson, assertUnique, assertValue, isoTimestamp, nonNegativeInteger, requiredBoolean, requiredEnum, requiredString, stringArray, validateAccountScope, validateFreshness, validateJsonObject, validatePortalEnvelope, validateResourceScope, } from './portalPublicArtifactValidationCommon.js';
+import { validateAwsPortalBillingBlock, validateAwsPortalRecommendationCoverage } from './portalPublicArtifactEvidenceValidation.js';
+import { validateRecommendationActionability, validateResourceBillingEvidence, validateTemplateProvenanceSources, } from './portalPublicArtifactNestedEvidenceValidation.js';
+const DISCOVERY_FAMILIES = [
+    'ec2-instance',
+    'ebs-volume',
+    'efs-file-system',
+    'lambda-function',
+    'elasticache-cache-cluster',
+    'elasticache-serverless-cache',
+    'vpc',
+    'subnet',
+    'route-table',
+    'internet-gateway',
+    'nat-gateway',
+    'network-interface',
+    'virtual-private-gateway',
+    'load-balancer-v2',
+    'classic-load-balancer',
+    'security-group',
+    'rds-db-cluster',
+    'rds-db-instance',
+];
+const METRIC_FAMILIES = [
+    'ec2-core-utilization',
+    'ebs-volume-performance',
+    'lambda-function-performance',
+    'load-balancer-v2-network-traffic',
+    'load-balancer-v2-application-traffic',
+    'rds-db-instance-utilization',
+];
+const RECOMMENDATION_SOURCES = [
+    'custom',
+    'compute-optimizer',
+    'cost-optimization-hub',
+    'resilience-hub',
+    'security-hub',
+    'trusted-advisor',
+    'well-architected',
+];
+const CURRENT_KEYS = [
+    'schemaVersion',
+    'portalSchemaVersion',
+    'provider',
+    'accountId',
+    'artifactType',
+    'artifactGeneration',
+    'generatedAt',
+    'logicalName',
+    'scope',
+];
+export function validateAwsPortalResourceCollectionDetailArtifact(value) {
+    const artifact = asRecord(value, 'artifact');
+    const { accountId } = validatePortalEnvelope(artifact, 'resource-collection', [...CURRENT_KEYS, 'summary', 'coverage', 'resources']);
+    assertValue(artifact.logicalName, AWS_PORTAL_RESOURCE_COLLECTION_LOGICAL_NAME, 'artifact.logicalName');
+    const scope = validateResourceScope(artifact.scope, accountId, 'artifact.scope');
+    validateResourceSummary(artifact.summary, 'artifact.summary');
+    validateResourceCoverage(artifact.coverage, accountId, scope);
+    if (!Array.isArray(artifact.resources))
+        throw new Error('artifact.resources must be an array.');
+    validateResources(artifact.resources, scope.resourceRegions);
+    const summary = asRecord(artifact.summary, 'artifact.summary');
+    if (summary.returnedResourceCount !== artifact.resources.length)
+        throw new Error('artifact.summary.returnedResourceCount must equal artifact.resources length.');
+    if (Number(summary.totalDiscoveredResourceCount) < Number(summary.returnedResourceCount))
+        throw new Error('artifact.summary.totalDiscoveredResourceCount must not be less than returnedResourceCount.');
+    assertPublicJson(artifact, 'artifact');
+    return value;
+}
+export function validateAwsPortalAccountSummaryDetailArtifact(value) {
+    const artifact = asRecord(value, 'artifact');
+    const { accountId } = validatePortalEnvelope(artifact, 'account-summary', [
+        ...CURRENT_KEYS,
+        'account',
+        'billing',
+        'discovery',
+        'metrics',
+        'recommendations',
+    ]);
+    assertValue(artifact.logicalName, AWS_PORTAL_ACCOUNT_SUMMARY_LOGICAL_NAME, 'artifact.logicalName');
+    const scope = validateAccountScope(artifact.scope, accountId, 'artifact.scope');
+    validateAccount(artifact.account, accountId);
+    validateAwsPortalBillingBlock(artifact.billing, 'artifact.billing', scope.billing, accountId, true);
+    validateDiscovery(artifact.discovery, scope.resourceRegions, 'artifact.discovery');
+    validateMetrics(artifact.metrics, scope.resourceRegions, 'artifact.metrics', 'account');
+    validateAwsPortalRecommendationCoverage(artifact.recommendations, accountId, scope.resourceRegions, 'artifact.recommendations', RECOMMENDATION_SOURCES, true);
+    assertPublicJson(artifact, 'artifact');
+    return value;
+}
+function validateResourceSummary(value, field) {
+    const summary = asRecord(value, field);
+    const keys = [
+        'totalDiscoveredResourceCount',
+        'returnedResourceCount',
+        'emptyCollection',
+        'truncated',
+        'unmatchedRecommendationResourceCount',
+        'unmatchedBillingExpenseCount',
+    ];
+    assertExactKeys(summary, keys, field);
+    keys.filter(key => !['emptyCollection', 'truncated'].includes(key)).forEach(key => nonNegativeInteger(summary[key], `${field}.${key}`));
+    requiredBoolean(summary.emptyCollection, `${field}.emptyCollection`);
+    requiredBoolean(summary.truncated, `${field}.truncated`);
+    if (summary.emptyCollection === true && Number(summary.returnedResourceCount) !== 0)
+        throw new Error(`${field}.emptyCollection requires zero returned resources.`);
+}
+function validateResourceCoverage(value, accountId, scope) {
+    const coverage = asRecord(value, 'artifact.coverage');
+    assertExactKeys(coverage, ['billing', 'discovery', 'metrics', 'recommendations', 'virtualTags'], 'artifact.coverage');
+    validateAwsPortalBillingBlock(coverage.billing, 'artifact.coverage.billing', scope.billing, accountId, false);
+    validateDiscovery(coverage.discovery, scope.resourceRegions, 'artifact.coverage.discovery');
+    validateMetrics(coverage.metrics, scope.resourceRegions, 'artifact.coverage.metrics', 'resource');
+    validateAwsPortalRecommendationCoverage(coverage.recommendations, accountId, scope.resourceRegions, 'artifact.coverage.recommendations', RECOMMENDATION_SOURCES, false);
+    if (coverage.virtualTags !== undefined)
+        validateVirtualTags(coverage.virtualTags);
+}
+function validateDiscovery(value, regions, field) {
+    const discovery = asRecord(value, field);
+    assertExactKeys(discovery, ['families'], field);
+    if (!Array.isArray(discovery.families))
+        throw new Error(`${field}.families must be an array.`);
+    const identities = [];
+    discovery.families.forEach((entry, index) => {
+        const itemField = `${field}.families[${index}]`;
+        const family = asRecord(entry, itemField);
+        assertExactKeys(family, ['family', 'resourceRegion', 'freshness', 'summary', 'groupedTotals'], itemField);
+        const familyName = requiredEnum(family.family, DISCOVERY_FAMILIES, `${itemField}.family`);
+        const region = requiredString(family.resourceRegion, `${itemField}.resourceRegion`);
+        if (!regions.includes(region))
+            throw new Error(`${itemField}.resourceRegion is outside artifact scope.`);
+        identities.push(`${familyName}|${region}`);
+        validateFreshness(family.freshness, `${itemField}.freshness`, 'lastSuccessfulRefreshAt');
+        validateJsonObject(family.summary, `${itemField}.summary`);
+        validateJsonObject(family.groupedTotals, `${itemField}.groupedTotals`);
+    });
+    assertUnique(identities, `${field}.families`);
+}
+function validateMetrics(value, regions, field, kind) {
+    const metrics = asRecord(value, field);
+    assertExactKeys(metrics, ['families'], field);
+    if (!Array.isArray(metrics.families))
+        throw new Error(`${field}.families must be an array.`);
+    const identities = [];
+    metrics.families.forEach((entry, index) => {
+        const itemField = `${field}.families[${index}]`;
+        const family = asRecord(entry, itemField);
+        const keys = kind === 'resource'
+            ? ['metricFamily', 'resourceRegion', 'requestedMonths', 'availableMonths', 'missingMonths', 'coverage', 'summary']
+            : ['metricFamily', 'resourceRegion', 'status', 'requestedMonths', 'availableMonths', 'missingMonths', 'freshness', 'readiness', 'summary'];
+        assertExactKeys(family, keys, itemField);
+        const metricFamily = requiredEnum(family.metricFamily, METRIC_FAMILIES, `${itemField}.metricFamily`);
+        const region = requiredString(family.resourceRegion, `${itemField}.resourceRegion`);
+        if (!regions.includes(region))
+            throw new Error(`${itemField}.resourceRegion is outside artifact scope.`);
+        identities.push(`${metricFamily}|${region}`);
+        if (family.status !== undefined)
+            requiredEnum(family.status, ['available', 'not-found'], `${itemField}.status`);
+        const requestedMonths = stringArray(family.requestedMonths, `${itemField}.requestedMonths`);
+        const availableMonths = stringArray(family.availableMonths, `${itemField}.availableMonths`);
+        const missingMonths = stringArray(family.missingMonths, `${itemField}.missingMonths`);
+        [...requestedMonths, ...availableMonths, ...missingMonths].forEach(month => {
+            if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(month))
+                throw new Error(`${itemField} contains a non-canonical billing month: ${month}.`);
+        });
+        const classifiedMonths = [...availableMonths, ...missingMonths].sort();
+        assertUnique(classifiedMonths, `${itemField} classified months`);
+        if (JSON.stringify(requestedMonths) !== JSON.stringify(classifiedMonths))
+            throw new Error(`${itemField} requestedMonths must equal availableMonths plus missingMonths.`);
+        if (family.freshness !== undefined)
+            validateFreshness(family.freshness, `${itemField}.freshness`, 'lastSuccessfulRefreshAt');
+        if (family.readiness !== undefined)
+            validateJsonObject(family.readiness, `${itemField}.readiness`);
+        if (family.coverage !== undefined)
+            validateJsonObject(family.coverage, `${itemField}.coverage`);
+        if (family.summary !== undefined)
+            validateJsonObject(family.summary, `${itemField}.summary`);
+    });
+    assertUnique(identities, `${field}.families`);
+}
+function validateVirtualTags(value) {
+    const tags = asRecord(value, 'artifact.coverage.virtualTags');
+    assertExactKeys(tags, ['status', 'source', 'generatedAt', 'rulesHash', 'enabledRuleCount', 'appliedRuleCount', 'taggedResourceCount', 'unsupportedRuleCount', 'reason'], 'artifact.coverage.virtualTags');
+    requiredEnum(tags.status, ['available', 'missing', 'malformed', 'unsupported'], 'artifact.coverage.virtualTags.status');
+    assertValue(tags.source, 'spotto-tags', 'artifact.coverage.virtualTags.source');
+    isoTimestamp(tags.generatedAt, 'artifact.coverage.virtualTags.generatedAt');
+    if (tags.rulesHash !== undefined && !/^[a-f0-9]{64}$/.test(String(tags.rulesHash)))
+        throw new Error('artifact.coverage.virtualTags.rulesHash must be a SHA-256.');
+    ['enabledRuleCount', 'appliedRuleCount', 'taggedResourceCount', 'unsupportedRuleCount'].forEach(key => nonNegativeInteger(tags[key], `artifact.coverage.virtualTags.${key}`));
+    if (tags.reason !== undefined)
+        requiredString(tags.reason, 'artifact.coverage.virtualTags.reason');
+}
+function validateResources(value, regions) {
+    if (!Array.isArray(value))
+        throw new Error('artifact.resources must be an array.');
+    const stableKeys = [];
+    value.forEach((entry, index) => {
+        const field = `artifact.resources[${index}]`;
+        const resource = asRecord(entry, field);
+        assertExactKeys(resource, [
+            'stableKey',
+            'family',
+            'resourceRegion',
+            'resourceType',
+            'resourceArn',
+            'resourceId',
+            'resourceName',
+            'tags',
+            'spottoTags',
+            'discovery',
+            'billing',
+            'metrics',
+            'recommendations',
+        ], field);
+        stableKeys.push(requiredString(resource.stableKey, `${field}.stableKey`));
+        requiredEnum(resource.family, DISCOVERY_FAMILIES, `${field}.family`);
+        const region = requiredString(resource.resourceRegion, `${field}.resourceRegion`);
+        if (!regions.includes(region))
+            throw new Error(`${field}.resourceRegion is outside artifact scope.`);
+        requiredString(resource.resourceType, `${field}.resourceType`);
+        ['resourceArn', 'resourceId', 'resourceName'].forEach(key => {
+            if (resource[key] !== undefined)
+                requiredString(resource[key], `${field}.${key}`);
+        });
+        if (resource.tags !== undefined)
+            validateStringMap(resource.tags, `${field}.tags`);
+        if (resource.spottoTags !== undefined)
+            validateJsonObject(resource.spottoTags, `${field}.spottoTags`);
+        const discovery = asRecord(resource.discovery, `${field}.discovery`);
+        assertExactKeys(discovery, ['freshness', 'summary'], `${field}.discovery`);
+        validateFreshness(discovery.freshness, `${field}.discovery.freshness`, 'lastSuccessfulRefreshAt');
+        validateJsonObject(discovery.summary, `${field}.discovery.summary`);
+        if (resource.billing !== undefined)
+            validateResourceBillingEvidence(resource.billing, `${field}.billing`);
+        if (resource.metrics !== undefined)
+            validateResourceMetrics(resource.metrics, `${field}.metrics`);
+        if (resource.recommendations !== undefined)
+            validateResourceRecommendations(resource.recommendations, `${field}.recommendations`);
+    });
+    assertUnique(stableKeys, 'artifact.resources');
+}
+function validateResourceMetrics(value, field) {
+    const metrics = asRecord(value, field);
+    assertExactKeys(metrics, ['supported', 'families'], field);
+    requiredBoolean(metrics.supported, `${field}.supported`);
+    if (!Array.isArray(metrics.families))
+        throw new Error(`${field}.families must be an array.`);
+    metrics.families.forEach((entry, index) => {
+        const family = asRecord(entry, `${field}.families[${index}]`);
+        assertExactKeys(family, ['metricFamily', 'summary', 'coverage'], `${field}.families[${index}]`);
+        requiredEnum(family.metricFamily, METRIC_FAMILIES, `${field}.families[${index}].metricFamily`);
+        validateJsonObject(family.summary, `${field}.families[${index}].summary`);
+        validateJsonObject(family.coverage, `${field}.families[${index}].coverage`);
+    });
+}
+function validateResourceRecommendations(value, field) {
+    const recommendations = asRecord(value, field);
+    assertExactKeys(recommendations, ['matchedRecommendationCount', 'sources', 'actionability', 'templateProvenance', 'counts', 'savings'], field);
+    nonNegativeInteger(recommendations.matchedRecommendationCount, `${field}.matchedRecommendationCount`);
+    stringArray(recommendations.sources, `${field}.sources`).forEach(source => requiredEnum(source, RECOMMENDATION_SOURCES, `${field}.sources`));
+    if (recommendations.actionability !== undefined) {
+        validateRecommendationActionability(recommendations.actionability, `${field}.actionability`);
+    }
+    if (recommendations.templateProvenance !== undefined)
+        validateTemplateProvenance(recommendations.templateProvenance, `${field}.templateProvenance`);
+    validateJsonObject(recommendations.counts, `${field}.counts`);
+    validateJsonObject(recommendations.savings, `${field}.savings`);
+}
+function validateTemplateProvenance(value, field) {
+    const provenance = asRecord(value, field);
+    assertExactKeys(provenance, [
+        'status',
+        'templateBackedRecommendationCount',
+        'missingTemplateRecommendationCount',
+        'internalTemplateCount',
+        'externalTemplateCount',
+        'confidenceBackedRecommendationCount',
+        'templateRecommendationWithoutConfidenceCount',
+        'lowestConfidenceSources',
+        'minimumConfidencePercentage',
+        'maximumConfidencePercentage',
+        'averageConfidencePercentage',
+    ], field);
+    requiredEnum(provenance.status, ['available-no-template-items', 'missing-template-evidence', 'missing-confidence-evidence', 'available-with-confidence'], `${field}.status`);
+    [
+        'templateBackedRecommendationCount',
+        'missingTemplateRecommendationCount',
+        'internalTemplateCount',
+        'externalTemplateCount',
+        'confidenceBackedRecommendationCount',
+        'templateRecommendationWithoutConfidenceCount',
+    ].forEach(key => nonNegativeInteger(provenance[key], `${field}.${key}`));
+    validateTemplateProvenanceSources(provenance.lowestConfidenceSources, `${field}.lowestConfidenceSources`);
+    ['minimumConfidencePercentage', 'maximumConfidencePercentage', 'averageConfidencePercentage'].forEach(key => {
+        if (provenance[key] !== undefined && (typeof provenance[key] !== 'number' || !Number.isFinite(provenance[key])))
+            throw new Error(`${field}.${key} must be finite.`);
+    });
+}
+function validateAccount(value, accountId) {
+    const account = asRecord(value, 'artifact.account');
+    assertExactKeys(account, [
+        'metadataFound',
+        'providerAccountId',
+        'cloudAccountId',
+        'accountName',
+        'validatedAt',
+        'providerPartition',
+        'summary',
+        'firstUsefulRecommendationReadiness',
+    ], 'artifact.account');
+    requiredBoolean(account.metadataFound, 'artifact.account.metadataFound');
+    assertValue(account.providerAccountId, accountId, 'artifact.account.providerAccountId');
+    ['cloudAccountId', 'accountName', 'providerPartition'].forEach(key => {
+        if (account[key] !== undefined)
+            requiredString(account[key], `artifact.account.${key}`);
+    });
+    isoTimestamp(account.validatedAt, 'artifact.account.validatedAt');
+    validateJsonObject(account.summary, 'artifact.account.summary');
+    if (account.firstUsefulRecommendationReadiness !== undefined)
+        validateJsonObject(account.firstUsefulRecommendationReadiness, 'artifact.account.firstUsefulRecommendationReadiness');
+}
+function validateStringMap(value, field) {
+    const map = asRecord(value, field);
+    Object.entries(map).forEach(([key, item]) => {
+        requiredString(key, `${field} key`);
+        requiredString(item, `${field}.${key}`);
+    });
+}

package/dist/esm/aws/portalPublicArtifactEvidenceValidation.js

@@ -0,0 +1,294 @@
+import { asRecord, assertExactKeys, assertUnique, assertValue, finiteNumber, isoTimestamp, nonNegativeInteger, requiredBoolean, requiredString, stringArray, validateFreshness, validateJsonArray, validateJsonObject, } from './portalPublicArtifactValidationCommon.js';
+export function validateAwsPortalBillingBlock(value, field, outerBilling, accountId, accountBody) {
+    const billing = asRecord(value, field);
+    const accountFields = [
+        'costViewByCurrency',
+        'groupedCosts',
+        'commitmentSpend',
+        'resourceAttribution',
+        'calendarSummary',
+        'periodSummary',
+        'spendTrend',
+        'comparison',
+    ];
+    const resourceFields = ['pricingReferenceEstimation', 'estimatedBillingAuthority'];
+    // AWS-only window evidence. Optional so artifacts published before the
+    // rolling resource window stay valid, but validated whenever present: a block
+    // that names one anchor period while its totals span three has to say so.
+    const windowFields = ['window', 'contributingBillingPeriods', 'windowCoverage'];
+    assertExactKeys(billing, ['scope', 'freshness', 'summary', 'totalsByCurrency', ...windowFields, ...(accountBody ? accountFields : resourceFields)], field);
+    validateBillingEvidenceScope(billing.scope, outerBilling, accountId, `${field}.scope`);
+    validateBillingEvidenceWindow(billing, outerBilling, field);
+    validateFreshness(billing.freshness, `${field}.freshness`, 'lastSuccessfulImportAt');
+    validateBillingSummary(billing.summary, `${field}.summary`);
+    validateBillingGroupedResult(billing.totalsByCurrency, `${field}.totalsByCurrency`);
+    if (!accountBody) {
+        if (billing.pricingReferenceEstimation !== undefined)
+            validateJsonObject(billing.pricingReferenceEstimation, `${field}.pricingReferenceEstimation`);
+        if (billing.estimatedBillingAuthority !== undefined)
+            validateJsonObject(billing.estimatedBillingAuthority, `${field}.estimatedBillingAuthority`);
+        return;
+    }
+    validateJsonArray(billing.costViewByCurrency, `${field}.costViewByCurrency`);
+    const grouped = asRecord(billing.groupedCosts, `${field}.groupedCosts`);
+    assertExactKeys(grouped, ['byChargeCategory', 'byServiceCode', 'byServiceCategory'], `${field}.groupedCosts`);
+    validateBillingGroupedResult(grouped.byChargeCategory, `${field}.groupedCosts.byChargeCategory`, 'chargeCategory');
+    validateBillingGroupedResult(grouped.byServiceCode, `${field}.groupedCosts.byServiceCode`, 'serviceCode');
+    if (grouped.byServiceCategory !== undefined)
+        validateBillingGroupedResult(grouped.byServiceCategory, `${field}.groupedCosts.byServiceCategory`, 'serviceCategory');
+    ['commitmentSpend', 'resourceAttribution', 'calendarSummary', 'periodSummary', 'spendTrend', 'comparison'].forEach(key => {
+        if (billing[key] !== undefined)
+            validateJsonObject(billing[key], `${field}.${key}`);
+    });
+}
+export function validateAwsPortalRecommendationCoverage(value, accountId, regions, field, sources, includeTrust) {
+    const recommendations = asRecord(value, field);
+    assertExactKeys(recommendations, ['sources'], field);
+    if (!Array.isArray(recommendations.sources))
+        throw new Error(`${field}.sources must be an array.`);
+    const seenSources = [];
+    recommendations.sources.forEach((entry, index) => {
+        const itemField = `${field}.sources[${index}]`;
+        const source = asRecord(entry, itemField);
+        assertExactKeys(source, includeTrust
+            ? ['source', 'scope', 'summary', 'counts', 'savings', 'sourceEvidence', 'actionHealth']
+            : ['source', 'scope', 'summary', 'counts', 'savings'], itemField);
+        const sourceName = requiredString(source.source, `${itemField}.source`);
+        if (!sources.includes(sourceName))
+            throw new Error(`${itemField}.source is not declared.`);
+        seenSources.push(sourceName);
+        const scope = asRecord(source.scope, `${itemField}.scope`);
+        assertExactKeys(scope, ['provider', 'source', 'scope', 'accountId', 'resourceRegions'], `${itemField}.scope`);
+        assertValue(scope.provider, 'aws', `${itemField}.scope.provider`);
+        assertValue(scope.source, sourceName, `${itemField}.scope.source`);
+        assertValue(scope.scope, 'account', `${itemField}.scope.scope`);
+        assertValue(scope.accountId, accountId, `${itemField}.scope.accountId`);
+        const nestedRegions = stringArray(scope.resourceRegions, `${itemField}.scope.resourceRegions`);
+        if (JSON.stringify(nestedRegions) !== JSON.stringify(regions))
+            throw new Error(`${itemField}.scope.resourceRegions must match artifact scope exactly.`);
+        validateRecommendationSummary(source.summary, `${itemField}.summary`);
+        validateRecommendationCounts(source.counts, `${itemField}.counts`);
+        validateRecommendationSavings(source.savings, `${itemField}.savings`);
+        if (source.sourceEvidence !== undefined)
+            validateRecommendationSourceEvidence(source.sourceEvidence, `${itemField}.sourceEvidence`);
+        if (source.actionHealth !== undefined)
+            validateRecommendationActionHealth(source.actionHealth, `${itemField}.actionHealth`);
+    });
+    assertUnique(seenSources, `${field}.sources`);
+}
+function validateBillingEvidenceScope(value, outerBilling, accountId, field) {
+    const scope = asRecord(value, field);
+    assertExactKeys(scope, ['provider', 'source', 'scope', 'accountId', 'reportName', 'billingPeriod'], field);
+    assertValue(scope.provider, 'aws', `${field}.provider`);
+    assertValue(scope.source, outerBilling.source, `${field}.source`);
+    assertValue(scope.scope, 'account', `${field}.scope`);
+    assertValue(scope.accountId, accountId, `${field}.accountId`);
+    assertValue(scope.reportName, outerBilling.source === 'cur' ? outerBilling.reportName : outerBilling.exportName, `${field}.reportName`);
+    if (JSON.stringify(scope.billingPeriod) !== JSON.stringify(outerBilling.billingPeriod))
+        throw new Error(`${field}.billingPeriod must match artifact scope exactly.`);
+}
+/**
+ * Validates the rolling window a billing block measures, and binds it to the
+ * anchor period the artifact scope names.
+ *
+ * The window may start inside the preceding billing period — that is the whole
+ * point of a run-anchored rolling 30 days — but it must end no later than the
+ * day after the anchor period ends, and every period it claims contributed must
+ * form an adjacent chain that covers it, or the block must admit
+ * `partial-billing-period-coverage`.
+ */
+function validateBillingEvidenceWindow(billing, outerBilling, field) {
+    const hasWindow = billing.window !== undefined;
+    if (billing.contributingBillingPeriods !== undefined && !hasWindow)
+        throw new Error(`${field}.contributingBillingPeriods requires ${field}.window.`);
+    if (billing.windowCoverage !== undefined && !hasWindow)
+        throw new Error(`${field}.windowCoverage requires ${field}.window.`);
+    if (!hasWindow)
+        return;
+    const window = asRecord(billing.window, `${field}.window`);
+    assertExactKeys(window, ['kind', 'dayCount', 'startDateInclusive', 'endDateExclusive'], `${field}.window`);
+    assertValue(window.kind, 'last-30-days', `${field}.window.kind`);
+    assertValue(window.dayCount, 30, `${field}.window.dayCount`);
+    const startDateInclusive = utcDate(window.startDateInclusive, `${field}.window.startDateInclusive`);
+    const endDateExclusive = utcDate(window.endDateExclusive, `${field}.window.endDateExclusive`);
+    if (shiftUtcDate(endDateExclusive, -30) !== startDateInclusive)
+        throw new Error(`${field}.window must cover exactly 30 UTC days.`);
+    if (endDateExclusive > shiftUtcDate(outerBilling.billingPeriod.end, 1))
+        throw new Error(`${field}.window.endDateExclusive must not run past the day after the artifact billing period.`);
+    if (billing.contributingBillingPeriods === undefined)
+        return;
+    if (!Array.isArray(billing.contributingBillingPeriods))
+        throw new Error(`${field}.contributingBillingPeriods must be an array.`);
+    const periods = billing.contributingBillingPeriods.map((entry, index) => {
+        const itemField = `${field}.contributingBillingPeriods[${index}]`;
+        const period = asRecord(entry, itemField);
+        assertExactKeys(period, ['start', 'end'], itemField);
+        const start = utcDate(period.start, `${itemField}.start`);
+        const end = utcDate(period.end, `${itemField}.end`);
+        if (end < start)
+            throw new Error(`${itemField}.end must not precede ${itemField}.start.`);
+        return { start, end };
+    });
+    assertUnique(periods.map(period => `${period.start}|${period.end}`), `${field}.contributingBillingPeriods`);
+    if (periods.some((period, index) => index > 0 && period.start <= periods[index - 1].start))
+        throw new Error(`${field}.contributingBillingPeriods must be ordered by start date.`);
+    const anchor = `${outerBilling.billingPeriod.start}|${outerBilling.billingPeriod.end}`;
+    if (periods.length > 0 && !periods.some(period => `${period.start}|${period.end}` === anchor))
+        throw new Error(`${field}.contributingBillingPeriods must include the artifact billing period.`);
+    const complete = periods.length > 0 &&
+        periods[0].start <= startDateInclusive &&
+        periods[periods.length - 1].end >= shiftUtcDate(endDateExclusive, -1) &&
+        periods.every((period, index) => index === 0 || shiftUtcDate(periods[index - 1].end, 1) === period.start);
+    const coverage = billing.windowCoverage;
+    if (coverage !== undefined && coverage !== 'complete' && coverage !== 'partial-billing-period-coverage')
+        throw new Error(`${field}.windowCoverage must be complete or partial-billing-period-coverage.`);
+    if (coverage === 'complete' && !complete)
+        throw new Error(`${field}.windowCoverage claims complete coverage its contributingBillingPeriods do not provide.`);
+}
+function utcDate(value, field) {
+    const date = requiredString(value, field);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || new Date(`${date}T00:00:00.000Z`).toISOString().slice(0, 10) !== date)
+        throw new Error(`${field} must be a YYYY-MM-DD UTC date.`);
+    return date;
+}
+function shiftUtcDate(date, days) {
+    const parsed = new Date(`${date}T00:00:00.000Z`);
+    parsed.setUTCDate(parsed.getUTCDate() + days);
+    return parsed.toISOString().slice(0, 10);
+}
+function validateBillingSummary(value, field) {
+    const summary = asRecord(value, field);
+    assertExactKeys(summary, ['totalPersistedExpenseCount', 'emptyScope', 'metadataFound', 'metadataMatchesRequestedBillingPeriod'], field);
+    nonNegativeInteger(summary.totalPersistedExpenseCount, `${field}.totalPersistedExpenseCount`);
+    requiredBoolean(summary.emptyScope, `${field}.emptyScope`);
+    requiredBoolean(summary.metadataFound, `${field}.metadataFound`);
+    requiredBoolean(summary.metadataMatchesRequestedBillingPeriod, `${field}.metadataMatchesRequestedBillingPeriod`);
+}
+function validateBillingGroupedResult(value, field, label) {
+    const result = asRecord(value, field);
+    assertExactKeys(result, ['totalGroupCount', 'returnedGroupCount', 'truncated', 'items'], field);
+    const total = nonNegativeInteger(result.totalGroupCount, `${field}.totalGroupCount`);
+    const returned = nonNegativeInteger(result.returnedGroupCount, `${field}.returnedGroupCount`);
+    requiredBoolean(result.truncated, `${field}.truncated`);
+    if (returned > total)
+        throw new Error(`${field}.returnedGroupCount must not exceed totalGroupCount.`);
+    if (!Array.isArray(result.items) || result.items.length !== returned)
+        throw new Error(`${field}.items length must equal returnedGroupCount.`);
+    const identities = [];
+    result.items.forEach((entry, index) => {
+        const itemField = `${field}.items[${index}]`;
+        const item = asRecord(entry, itemField);
+        assertExactKeys(item, [...(label ? [label] : []), 'currency', 'expenseCount', 'baseCostAmount', 'amortizedCostAmount', 'amortizedExpenseCount'], itemField);
+        if (label)
+            requiredString(item[label], `${itemField}.${label}`);
+        const currency = requiredString(item.currency, `${itemField}.currency`);
+        nonNegativeInteger(item.expenseCount, `${itemField}.expenseCount`);
+        finiteNumber(item.baseCostAmount, `${itemField}.baseCostAmount`);
+        if (item.amortizedCostAmount !== undefined)
+            finiteNumber(item.amortizedCostAmount, `${itemField}.amortizedCostAmount`);
+        if (item.amortizedExpenseCount !== undefined)
+            nonNegativeInteger(item.amortizedExpenseCount, `${itemField}.amortizedExpenseCount`);
+        identities.push(`${label ? String(item[label]) : ''}|${currency}`);
+    });
+    assertUnique(identities, `${field}.items`);
+}
+function validateRecommendationSummary(value, field) {
+    const summary = asRecord(value, field);
+    const counts = [
+        'totalStateCount',
+        'currentStateCount',
+        'missingStateCount',
+        'snapshotBackedCount',
+        'orphanSnapshotCount',
+        'matchedStateCount',
+        'filteredOutStateCount',
+    ];
+    assertExactKeys(summary, [...counts, 'emptyScope', 'emptyResult'], field);
+    counts.forEach(key => nonNegativeInteger(summary[key], `${field}.${key}`));
+    requiredBoolean(summary.emptyScope, `${field}.emptyScope`);
+    requiredBoolean(summary.emptyResult, `${field}.emptyResult`);
+}
+function validateRecommendationCounts(value, field) {
+    const counts = asRecord(value, field);
+    const groups = [
+        ['byLifecycleStatus', 'lifecycleStatus'],
+        ['bySourcePresence', 'sourcePresence'],
+        ['byCategory', 'category'],
+        ['byRegion', 'region'],
+        ['bySourceService', 'sourceService'],
+        ['byResourceType', 'resourceType'],
+        ['byActionType', 'actionType'],
+        ['byImplementationEffort', 'implementationEffort'],
+    ];
+    assertExactKeys(counts, groups.map(([group]) => group), field);
+    groups.forEach(([group, label]) => validateCountGroup(counts[group], `${field}.${group}`, label));
+}
+function validateCountGroup(value, field, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${field} must be an array.`);
+    const identities = [];
+    value.forEach((entry, index) => {
+        const item = asRecord(entry, `${field}[${index}]`);
+        assertExactKeys(item, [label, 'count'], `${field}[${index}]`);
+        identities.push(requiredString(item[label], `${field}[${index}].${label}`));
+        nonNegativeInteger(item.count, `${field}[${index}].count`);
+    });
+    assertUnique(identities, field);
+}
+function validateRecommendationSavings(value, field) {
+    const savings = asRecord(value, field);
+    const counts = [
+        'snapshotBackedMatchedCount',
+        'positiveEstimatedSavingsRecommendationCount',
+        'nonPositiveEstimatedSavingsCount',
+        'missingEstimatedSavingsCount',
+        'missingCurrencyCodeCount',
+    ];
+    assertExactKeys(savings, [...counts, 'emptySavings', 'mixedCurrencies', 'byCurrency'], field);
+    counts.forEach(key => nonNegativeInteger(savings[key], `${field}.${key}`));
+    requiredBoolean(savings.emptySavings, `${field}.emptySavings`);
+    requiredBoolean(savings.mixedCurrencies, `${field}.mixedCurrencies`);
+    if (!Array.isArray(savings.byCurrency))
+        throw new Error(`${field}.byCurrency must be an array.`);
+    const currencies = [];
+    savings.byCurrency.forEach((entry, index) => {
+        const itemField = `${field}.byCurrency[${index}]`;
+        const item = asRecord(entry, itemField);
+        assertExactKeys(item, ['currencyCode', 'recommendationCount', 'totalEstimatedMonthlySavings'], itemField);
+        currencies.push(requiredString(item.currencyCode, `${itemField}.currencyCode`));
+        nonNegativeInteger(item.recommendationCount, `${itemField}.recommendationCount`);
+        finiteNumber(item.totalEstimatedMonthlySavings, `${itemField}.totalEstimatedMonthlySavings`);
+    });
+    assertUnique(currencies, `${field}.byCurrency`);
+}
+export function validateRecommendationSourceEvidence(value, field) {
+    const evidence = asRecord(value, field);
+    const baseKeys = [
+        'totalStateCount',
+        'currentStateCount',
+        'missingStateCount',
+        'snapshotBackedCount',
+        'orphanSnapshotCount',
+        'matchedStateCount',
+        'filteredOutStateCount',
+        'emptyScope',
+        'emptyResult',
+    ];
+    assertExactKeys(evidence, [...baseKeys, 'partialSourceEvidence', 'oldestRecommendationSynchronizedAt', 'latestRecommendationSynchronizedAt', 'exactScopeCoverage'], field);
+    baseKeys.filter(key => !['emptyScope', 'emptyResult'].includes(key)).forEach(key => nonNegativeInteger(evidence[key], `${field}.${key}`));
+    requiredBoolean(evidence.emptyScope, `${field}.emptyScope`);
+    requiredBoolean(evidence.emptyResult, `${field}.emptyResult`);
+    requiredBoolean(evidence.partialSourceEvidence, `${field}.partialSourceEvidence`);
+    if (evidence.oldestRecommendationSynchronizedAt !== undefined)
+        isoTimestamp(evidence.oldestRecommendationSynchronizedAt, `${field}.oldestRecommendationSynchronizedAt`);
+    if (evidence.latestRecommendationSynchronizedAt !== undefined)
+        isoTimestamp(evidence.latestRecommendationSynchronizedAt, `${field}.latestRecommendationSynchronizedAt`);
+    if (evidence.exactScopeCoverage !== undefined)
+        validateJsonObject(evidence.exactScopeCoverage, `${field}.exactScopeCoverage`);
+}
+export function validateRecommendationActionHealth(value, field) {
+    const health = asRecord(value, field);
+    assertExactKeys(health, ['latestActionCount', 'byLatestActionStatus'], field);
+    nonNegativeInteger(health.latestActionCount, `${field}.latestActionCount`);
+    validateCountGroup(health.byLatestActionStatus, `${field}.byLatestActionStatus`, 'status');
+}