@empire-builder-kit/nx 1.0.0-beta.9 → 1.0.0-rc.2

package/src/performance/cost-collection.js

@@ -0,0 +1,825 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAggregateCountEvidence = createAggregateCountEvidence;
+exports.validateAggregateCountEvidence = validateAggregateCountEvidence;
+exports.awsAccountFingerprint = awsAccountFingerprint;
+exports.validateCostAllocationContract = validateCostAllocationContract;
+exports.createExternalCostCollectionContract = createExternalCostCollectionContract;
+exports.validateExternalCostCollectionContract = validateExternalCostCollectionContract;
+exports.collectAwsBillingActualEvidence = collectAwsBillingActualEvidence;
+exports.validateAwsBillingActualEvidence = validateAwsBillingActualEvidence;
+const deterministic_order_js_1 = require("../deterministic-order.js");
+const node_crypto_1 = require("node:crypto");
+const safe_reference_1 = require("@empire-builder-kit/runtime/safe-reference");
+const model_js_1 = require("./model.js");
+const ACCOUNT_ID = /^\d{12}$/;
+const ACCOUNT_FINGERPRINT = /^sha256:[a-f0-9]{64}$/;
+const REGION = /^(?:af|ap|ca|cn|eu|il|me|mx|sa|us)(?:-gov|-iso|-isob)?-[a-z]+-\d$/;
+const MONEY = /^(?:0|[1-9]\d{0,8})(?:\.\d{1,9})?$/;
+const MAX_ALLOCATIONS = 32;
+const MONEY_SCALE = 1_000_000_000;
+function invalid(pointer, message) {
+    return new model_js_1.PerformanceContractError('performance-evidence-invalid', pointer, message);
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function onlyKeys(value, keys, pointer) {
+    if (!record(value))
+        throw invalid(pointer, 'must be an object');
+    for (const key of Object.keys(value)) {
+        if (!keys.includes(key)) {
+            throw invalid(`${pointer}/${key}`, 'is not part of the v1 contract');
+        }
+    }
+}
+function requiredReference(value, pointer) {
+    if (!(0, safe_reference_1.isBoundedSafeReference)(value, 'performance-evidence')) {
+        throw invalid(pointer, 'must be one bounded non-sensitive reference');
+    }
+    return value;
+}
+function digest(value, pointer) {
+    (0, model_js_1.assertDigest)(value, pointer);
+    return value;
+}
+function release(value, pointer) {
+    onlyKeys(value, ['candidateDigest', 'releaseId', 'releaseMaterialDigest', 'sourceCommit'], pointer);
+    (0, model_js_1.assertDigest)(value.candidateDigest, `${pointer}/candidateDigest`);
+    (0, model_js_1.assertDigest)(value.releaseMaterialDigest, `${pointer}/releaseMaterialDigest`);
+    (0, model_js_1.assertFullCommit)(value.sourceCommit, `${pointer}/sourceCommit`);
+    requiredReference(value.releaseId, `${pointer}/releaseId`);
+    return value;
+}
+function releasesEqual(left, right) {
+    return (left.candidateDigest === right.candidateDigest &&
+        left.releaseId === right.releaseId &&
+        left.releaseMaterialDigest === right.releaseMaterialDigest &&
+        left.sourceCommit === right.sourceCommit);
+}
+function protectedCollectionIdentity(value, pointer) {
+    onlyKeys(value, [
+        'aggregateArtifact',
+        'releaseArtifact',
+        'repository',
+        'runAttempt',
+        'runId',
+        'sourceCommit',
+        'workflow',
+    ], pointer);
+    const inputArtifact = (artifact, artifactPointer) => {
+        onlyKeys(artifact, ['name', 'runId', 'sha256'], artifactPointer);
+        const name = requiredReference(artifact.name, `${artifactPointer}/name`);
+        const runId = requiredReference(artifact.runId, `${artifactPointer}/runId`);
+        const sha256 = artifact.sha256;
+        (0, model_js_1.assertDigest)(sha256, `${artifactPointer}/sha256`);
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(name) ||
+            !/^[1-9]\d{0,19}$/.test(runId)) {
+            throw invalid(artifactPointer, 'must identify one bounded artifact from an exact GitHub Actions run');
+        }
+        return { name, runId, sha256: sha256 };
+    };
+    const aggregateArtifact = inputArtifact(value.aggregateArtifact, `${pointer}/aggregateArtifact`);
+    const releaseArtifact = inputArtifact(value.releaseArtifact, `${pointer}/releaseArtifact`);
+    const repository = requiredReference(value.repository, `${pointer}/repository`);
+    const runAttempt = requiredReference(value.runAttempt, `${pointer}/runAttempt`);
+    const runId = requiredReference(value.runId, `${pointer}/runId`);
+    const sourceCommit = value.sourceCommit;
+    (0, model_js_1.assertFullCommit)(sourceCommit, `${pointer}/sourceCommit`);
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) ||
+        !/^[1-9]\d{0,8}$/.test(runAttempt) ||
+        !/^[1-9]\d{0,19}$/.test(runId) ||
+        value.workflow !== '.github/workflows/performance-cost-actual.yml') {
+        throw invalid(pointer, 'must identify one exact protected GitHub billing-collection run');
+    }
+    return {
+        aggregateArtifact,
+        releaseArtifact,
+        repository,
+        runAttempt,
+        runId,
+        sourceCommit: sourceCommit,
+        workflow: '.github/workflows/performance-cost-actual.yml',
+    };
+}
+function exactEnvironment(value, pointer) {
+    onlyKeys(value, ['accountFingerprint', 'region', 'slice', 'stage', 'workspace'], pointer);
+    if (typeof value.accountFingerprint !== 'string' ||
+        !ACCOUNT_FINGERPRINT.test(value.accountFingerprint)) {
+        throw invalid(`${pointer}/accountFingerprint`, 'must be a derived AWS account fingerprint');
+    }
+    if (typeof value.region !== 'string' || !REGION.test(value.region)) {
+        throw invalid(`${pointer}/region`, 'must be an AWS Region');
+    }
+    requiredReference(value.slice, `${pointer}/slice`);
+    requiredReference(value.workspace, `${pointer}/workspace`);
+    if (value.stage !== 'production' && value.stage !== 'staging') {
+        throw invalid(`${pointer}/stage`, 'must be production or staging');
+    }
+    return value;
+}
+function exactPeriod(value, pointer) {
+    onlyKeys(value, ['end', 'start'], pointer);
+    if (!(0, model_js_1.isIsoInstant)(value.start) ||
+        !(0, model_js_1.isIsoInstant)(value.end) ||
+        !value.start.endsWith('T00:00:00.000Z') ||
+        !value.end.endsWith('T00:00:00.000Z') ||
+        Date.parse(value.end) <= Date.parse(value.start)) {
+        throw invalid(pointer, 'must be one increasing UTC-midnight billing window');
+    }
+    const durationDays = (Date.parse(value.end) - Date.parse(value.start)) / 86_400_000;
+    if (!Number.isSafeInteger(durationDays) || durationDays > 370) {
+        throw invalid(pointer, 'must be a bounded billing window of at most 370 days');
+    }
+    return value;
+}
+function dateFromInstant(value) {
+    return value.slice(0, 10);
+}
+function canonicalRequest(environment, period, purpose) {
+    return {
+        filter: {
+            tags: [
+                { key: 'ebk:workspace', value: environment.workspace },
+                { key: 'ebk:slice', value: environment.slice },
+                { key: 'ebk:stage', value: environment.stage },
+            ],
+        },
+        granularity: 'MONTHLY',
+        groupBy: purpose === 'allocation'
+            ? { key: 'ebk:cost-allocation', type: 'TAG' }
+            : null,
+        metric: 'UnblendedCost',
+        operation: 'ce:GetCostAndUsage',
+        timePeriod: {
+            end: dateFromInstant(period.end),
+            start: dateFromInstant(period.start),
+        },
+    };
+}
+function moneyNanosFromString(value, pointer) {
+    if (typeof value !== 'string' || !MONEY.test(value)) {
+        throw invalid(pointer, 'must be a non-negative USD decimal with at most nine fractional digits');
+    }
+    const [whole = '0', fraction = ''] = value.split('.');
+    const nanos = Number(whole) * MONEY_SCALE +
+        Number(`${fraction}${'0'.repeat(9 - fraction.length)}`);
+    if (!Number.isSafeInteger(nanos)) {
+        throw invalid(pointer, 'exceeds the bounded USD evidence range');
+    }
+    return nanos;
+}
+function moneyNanosFromNumber(value, pointer) {
+    if (typeof value !== 'number' ||
+        !Number.isFinite(value) ||
+        value < 0 ||
+        value > 999_999_999) {
+        throw invalid(pointer, 'must be one bounded non-negative USD value');
+    }
+    const nanos = Math.round(value * MONEY_SCALE);
+    if (!Number.isSafeInteger(nanos) ||
+        Math.abs(nanos / MONEY_SCALE - value) > Number.EPSILON * 10) {
+        throw invalid(pointer, 'must have at most nine fractional digits');
+    }
+    return nanos;
+}
+function moneyFromNanos(value) {
+    return value / MONEY_SCALE;
+}
+function exactResult(response, request, pointer) {
+    requiredReference(response.requestId, `${pointer}/requestId`);
+    if (!Array.isArray(response.results) || response.results.length !== 1) {
+        throw invalid(`${pointer}/results`, 'must contain exactly one result period');
+    }
+    const result = response.results[0];
+    if (!result ||
+        result.start !== request.timePeriod.start ||
+        result.end !== request.timePeriod.end ||
+        result.estimated !== false) {
+        throw invalid(`${pointer}/results/0`, 'must be the exact closed, non-estimated query period');
+    }
+    if (!Array.isArray(result.groups)) {
+        throw invalid(`${pointer}/results/0/groups`, 'must be an array');
+    }
+    return result;
+}
+function allocationInputs(value) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.length > MAX_ALLOCATIONS) {
+        throw invalid('collector/allocations', `must contain between one and ${MAX_ALLOCATIONS} allocations`);
+    }
+    const result = value.map((entry, index) => {
+        onlyKeys(entry, ['allocationId', 'capabilityId'], `collector/allocations/${index}`);
+        return {
+            allocationId: requiredReference(entry.allocationId, `collector/allocations/${index}/allocationId`),
+            capabilityId: requiredReference(entry.capabilityId, `collector/allocations/${index}/capabilityId`),
+        };
+    });
+    if (new Set(result.map(({ allocationId }) => allocationId)).size !==
+        result.length ||
+        new Set(result.map(({ capabilityId }) => capabilityId)).size !==
+            result.length) {
+        throw invalid('collector/allocations', 'allocation and capability identifiers must each be unique');
+    }
+    return result.sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.allocationId, right.allocationId));
+}
+function aggregateInputs(value) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.length > MAX_ALLOCATIONS) {
+        throw invalid('collector/aggregateCounts', `must contain between one and ${MAX_ALLOCATIONS} aggregate counts`);
+    }
+    const result = value.map((entry, index) => {
+        onlyKeys(entry, ['aggregateId', 'capabilityId', 'count', 'evidenceDigest', 'sourceRef'], `collector/aggregateCounts/${index}`);
+        const count = entry.count;
+        if (typeof count !== 'number' ||
+            !Number.isSafeInteger(count) ||
+            count <= 0) {
+            throw invalid(`collector/aggregateCounts/${index}/count`, 'must be a positive safe integer');
+        }
+        return {
+            aggregateId: requiredReference(entry.aggregateId, `collector/aggregateCounts/${index}/aggregateId`),
+            capabilityId: requiredReference(entry.capabilityId, `collector/aggregateCounts/${index}/capabilityId`),
+            count,
+            evidenceDigest: digest(entry.evidenceDigest, `collector/aggregateCounts/${index}/evidenceDigest`),
+            sourceRef: requiredReference(entry.sourceRef, `collector/aggregateCounts/${index}/sourceRef`),
+        };
+    });
+    if (new Set(result.map(({ aggregateId }) => aggregateId)).size !==
+        result.length ||
+        new Set(result.map(({ capabilityId }) => capabilityId)).size !==
+            result.length) {
+        throw invalid('collector/aggregateCounts', 'aggregate and capability identifiers must each be unique');
+    }
+    return result.sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.aggregateId, right.aggregateId));
+}
+function aggregateRecords(value, pointer) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.length > MAX_ALLOCATIONS) {
+        throw invalid(pointer, `must contain between one and ${MAX_ALLOCATIONS} aggregate counts`);
+    }
+    const result = value.map((entry, index) => {
+        onlyKeys(entry, ['aggregateId', 'capabilityId', 'count', 'sourceRef'], `${pointer}/${index}`);
+        if (typeof entry.count !== 'number' ||
+            !Number.isSafeInteger(entry.count) ||
+            entry.count <= 0) {
+            throw invalid(`${pointer}/${index}/count`, 'must be a positive safe integer');
+        }
+        return {
+            aggregateId: requiredReference(entry.aggregateId, `${pointer}/${index}/aggregateId`),
+            capabilityId: requiredReference(entry.capabilityId, `${pointer}/${index}/capabilityId`),
+            count: entry.count,
+            sourceRef: requiredReference(entry.sourceRef, `${pointer}/${index}/sourceRef`),
+        };
+    });
+    if (new Set(result.map(({ aggregateId }) => aggregateId)).size !==
+        result.length ||
+        new Set(result.map(({ capabilityId }) => capabilityId)).size !==
+            result.length) {
+        throw invalid(pointer, 'aggregate and capability identifiers must each be unique');
+    }
+    return result.sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.aggregateId, right.aggregateId));
+}
+function createAggregateCountEvidence(input) {
+    onlyKeys(input, [
+        'collectedAt',
+        'counts',
+        'environment',
+        'kind',
+        'period',
+        'producer',
+        'release',
+        'schemaVersion',
+    ], 'aggregateEvidence');
+    if (input.kind !== 'ebk-aggregate-count-evidence' ||
+        input.schemaVersion !== 1) {
+        throw invalid('aggregateEvidence', 'must identify canonical v1 aggregate-count evidence');
+    }
+    const environment = exactEnvironment(input.environment, 'aggregateEvidence/environment');
+    const period = exactPeriod(input.period, 'aggregateEvidence/period');
+    const expectedRelease = release(input.release, 'aggregateEvidence/release');
+    if (!(0, model_js_1.isIsoInstant)(input.collectedAt) ||
+        Date.parse(input.collectedAt) < Date.parse(period.end)) {
+        throw invalid('aggregateEvidence/collectedAt', 'must be an ISO instant at or after the closed aggregate period');
+    }
+    onlyKeys(input.producer, ['access', 'authority', 'requestId'], 'aggregateEvidence/producer');
+    onlyKeys(input.producer.access, ['mode', 'permissionContract'], 'aggregateEvidence/producer/access');
+    if (input.producer.access.mode !== 'dedicated-oidc-read-role' ||
+        input.producer.access.permissionContract !==
+            'adopter-owned-least-privilege-read-v1') {
+        throw invalid('aggregateEvidence/producer/access', 'must identify the dedicated adopter-owned least-privilege read authority');
+    }
+    if (input.producer.authority !== 'adopter-protected-aggregate-v1') {
+        throw invalid('aggregateEvidence/producer/authority', 'must identify the adopter protected aggregate authority');
+    }
+    const unsigned = {
+        collectedAt: input.collectedAt,
+        counts: aggregateRecords(input.counts, 'aggregateEvidence/counts'),
+        environment,
+        kind: 'ebk-aggregate-count-evidence',
+        period,
+        producer: {
+            access: {
+                mode: 'dedicated-oidc-read-role',
+                permissionContract: 'adopter-owned-least-privilege-read-v1',
+            },
+            authority: 'adopter-protected-aggregate-v1',
+            requestId: requiredReference(input.producer.requestId, 'aggregateEvidence/producer/requestId'),
+        },
+        release: expectedRelease,
+        schemaVersion: 1,
+    };
+    return {
+        ...unsigned,
+        materialDigest: (0, model_js_1.performanceDigest)(unsigned),
+    };
+}
+function validateAggregateCountEvidence(value) {
+    onlyKeys(value, [
+        'collectedAt',
+        'counts',
+        'environment',
+        'kind',
+        'materialDigest',
+        'period',
+        'producer',
+        'release',
+        'schemaVersion',
+    ], 'aggregateEvidence');
+    digest(value.materialDigest, 'aggregateEvidence/materialDigest');
+    const expected = createAggregateCountEvidence({
+        collectedAt: value.collectedAt,
+        counts: value.counts,
+        environment: value.environment,
+        kind: value.kind,
+        period: value.period,
+        producer: value.producer,
+        release: value.release,
+        schemaVersion: value.schemaVersion,
+    });
+    if (value.materialDigest !== expected.materialDigest) {
+        throw invalid('aggregateEvidence/materialDigest', 'does not match the canonical aggregate-count evidence bytes');
+    }
+    return expected;
+}
+function assertSameCapabilitySet(allocations, aggregateCounts) {
+    const allocationCapabilities = allocations
+        .map(({ capabilityId }) => capabilityId)
+        .sort();
+    const aggregateCapabilities = aggregateCounts
+        .map(({ capabilityId }) => capabilityId)
+        .sort();
+    if (JSON.stringify(allocationCapabilities) !==
+        JSON.stringify(aggregateCapabilities)) {
+        throw invalid('collector', 'allocations and aggregate counts must name the same exact capabilities');
+    }
+}
+function awsAccountFingerprint(accountId) {
+    if (!ACCOUNT_ID.test(accountId)) {
+        throw invalid('collector/accountId', 'must be a twelve-digit AWS account ID');
+    }
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(accountId).digest('hex')}`;
+}
+function validateCostAllocationContract(value, options = {}) {
+    onlyKeys(value, [
+        'actualCostProvider',
+        'allocations',
+        'forecastProviders',
+        'kind',
+        'provenanceLabels',
+        'resourceTagKey',
+        'schemaVersion',
+        'sharedCostsRemainExplicit',
+        'slice',
+        'unitCosts',
+    ], 'costAllocation');
+    if (value.kind !== 'ebk-cost-allocation-contract' ||
+        value.schemaVersion !== 1 ||
+        value.actualCostProvider !== 'aws-billing-actual' ||
+        value.resourceTagKey !== 'ebk:cost-allocation' ||
+        value.sharedCostsRemainExplicit !== true ||
+        JSON.stringify(value.forecastProviders) !==
+            JSON.stringify(['infrastructure-plan', 'aws-price-estimate']) ||
+        JSON.stringify(value.provenanceLabels) !==
+            JSON.stringify(['estimate', 'test', 'actual'])) {
+        throw invalid('costAllocation', 'must identify the exact v1 adopter-owned cost allocation authority');
+    }
+    const slice = requiredReference(value.slice, 'costAllocation/slice');
+    if (!Array.isArray(value.allocations) ||
+        value.allocations.length !== 2 ||
+        !Array.isArray(value.unitCosts) ||
+        value.unitCosts.length !== 2) {
+        throw invalid('costAllocation', 'must define exactly two allocation and unit-cost capabilities');
+    }
+    const allocations = value.allocations
+        .map((entry, index) => {
+        onlyKeys(entry, ['capabilityId', 'driver', 'id', 'status'], `costAllocation/allocations/${index}`);
+        const status = entry.status;
+        if (status !== 'adopted' && status !== 'requires-adopter-value') {
+            throw invalid(`costAllocation/allocations/${index}/status`, 'must be adopted or require an adopter value');
+        }
+        return {
+            capabilityId: requiredReference(entry.capabilityId, `costAllocation/allocations/${index}/capabilityId`),
+            driver: requiredReference(entry.driver, `costAllocation/allocations/${index}/driver`),
+            id: requiredReference(entry.id, `costAllocation/allocations/${index}/id`),
+            status,
+        };
+    })
+        .sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.id, right.id));
+    const unitCosts = value.unitCosts
+        .map((entry, index) => {
+        onlyKeys(entry, [
+            'aggregateCountRef',
+            'anomalyIncreasePercent',
+            'id',
+            'ownerRouteRef',
+            'status',
+            'unit',
+        ], `costAllocation/unitCosts/${index}`);
+        const status = entry.status;
+        if (status !== 'adopted' && status !== 'requires-adopter-value') {
+            throw invalid(`costAllocation/unitCosts/${index}/status`, 'must be adopted or require an adopter value');
+        }
+        if (typeof entry.anomalyIncreasePercent !== 'number' ||
+            !Number.isFinite(entry.anomalyIncreasePercent) ||
+            entry.anomalyIncreasePercent <= 0 ||
+            entry.anomalyIncreasePercent > 1_000) {
+            throw invalid(`costAllocation/unitCosts/${index}/anomalyIncreasePercent`, 'must be a finite percentage from greater than zero through 1000');
+        }
+        return {
+            aggregateCountRef: requiredReference(entry.aggregateCountRef, `costAllocation/unitCosts/${index}/aggregateCountRef`),
+            anomalyIncreasePercent: entry.anomalyIncreasePercent,
+            id: requiredReference(entry.id, `costAllocation/unitCosts/${index}/id`),
+            ownerRouteRef: requiredReference(entry.ownerRouteRef, `costAllocation/unitCosts/${index}/ownerRouteRef`),
+            status,
+            unit: requiredReference(entry.unit, `costAllocation/unitCosts/${index}/unit`),
+        };
+    })
+        .sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.id, right.id));
+    if (new Set(allocations.map(({ id }) => id)).size !== allocations.length ||
+        new Set(allocations.map(({ capabilityId }) => capabilityId)).size !==
+            allocations.length ||
+        new Set(unitCosts.map(({ id }) => id)).size !== unitCosts.length ||
+        JSON.stringify(allocations.map(({ capabilityId }) => capabilityId).sort()) !== JSON.stringify(unitCosts.map(({ id }) => id).sort())) {
+        throw invalid('costAllocation', 'allocation and unit-cost entries must map each exact capability once');
+    }
+    if (options.requireAdopted === true &&
+        [...allocations, ...unitCosts].some(({ status }) => status !== 'adopted')) {
+        throw invalid('costAllocation', 'protected collection requires every allocation and unit-cost capability to be adopted');
+    }
+    return {
+        actualCostProvider: 'aws-billing-actual',
+        allocations,
+        forecastProviders: ['infrastructure-plan', 'aws-price-estimate'],
+        kind: 'ebk-cost-allocation-contract',
+        provenanceLabels: ['estimate', 'test', 'actual'],
+        resourceTagKey: 'ebk:cost-allocation',
+        schemaVersion: 1,
+        sharedCostsRemainExplicit: true,
+        slice,
+        unitCosts,
+    };
+}
+function createExternalCostCollectionContract(input) {
+    const unsigned = {
+        collection: {
+            authority: 'aws-billing-actual',
+            mode: 'external-read-only',
+            period: 'closed-billing-window',
+        },
+        evidence: {
+            outputKind: 'ebk-aws-billing-actual-evidence',
+            outputPath: requiredReference(input.outputPath, 'costCollection/evidence/outputPath'),
+            provenance: 'actual',
+            releaseBindingRequired: true,
+        },
+        kind: 'ebk-external-cost-collection-contract',
+        owner: requiredReference(input.owner, 'costCollection/owner'),
+        requiredAllocationDimensions: ['workspace', 'slice', 'stage'],
+        schemaVersion: 1,
+        slice: requiredReference(input.slice, 'costCollection/slice'),
+        status: 'requires-live-external-collector',
+    };
+    return { ...unsigned, materialDigest: (0, model_js_1.performanceDigest)(unsigned) };
+}
+function validateExternalCostCollectionContract(value) {
+    onlyKeys(value, [
+        'collection',
+        'evidence',
+        'kind',
+        'materialDigest',
+        'owner',
+        'requiredAllocationDimensions',
+        'schemaVersion',
+        'slice',
+        'status',
+    ], 'costCollection');
+    const expected = createExternalCostCollectionContract({
+        outputPath: value.evidence
+            ?.outputPath,
+        owner: value.owner,
+        slice: value.slice,
+    });
+    if ((0, model_js_1.performanceDigest)(value.collection) !==
+        (0, model_js_1.performanceDigest)(expected.collection) ||
+        (0, model_js_1.performanceDigest)(value.evidence) !==
+            (0, model_js_1.performanceDigest)(expected.evidence) ||
+        (0, model_js_1.performanceDigest)(value.requiredAllocationDimensions) !==
+            (0, model_js_1.performanceDigest)(expected.requiredAllocationDimensions) ||
+        value.kind !== expected.kind ||
+        value.schemaVersion !== expected.schemaVersion ||
+        value.status !== expected.status ||
+        value.materialDigest !== expected.materialDigest) {
+        throw invalid('costCollection', 'must match the canonical external AWS billing collection contract');
+    }
+    return expected;
+}
+/**
+ * Runs the read-only evidence adapter outside the unit-cost evaluator. The
+ * evaluator receives only the bounded, release-bound result and cannot label
+ * arbitrary JSON as AWS billing actuals.
+ */
+async function collectAwsBillingActualEvidence(input) {
+    const environment = exactEnvironment(input.environment, 'collector/environment');
+    const period = exactPeriod(input.period, 'collector/period');
+    const collectedAt = input.collectedAt;
+    if (!(0, model_js_1.isIsoInstant)(collectedAt) ||
+        Date.parse(collectedAt) < Date.parse(period.end)) {
+        throw invalid('collector/collectedAt', 'must be an ISO instant at or after the closed billing period');
+    }
+    const expectedRelease = release(input.release, 'collector/release');
+    const collection = protectedCollectionIdentity(input.collection, 'collector/collection');
+    if (collection.sourceCommit !== expectedRelease.sourceCommit) {
+        throw invalid('collector/collection/sourceCommit', 'must equal the exact release source commit');
+    }
+    const allocations = allocationInputs(input.allocations);
+    const aggregateEvidence = validateAggregateCountEvidence(input.aggregateEvidence);
+    if ((0, model_js_1.performanceDigest)(aggregateEvidence.environment) !==
+        (0, model_js_1.performanceDigest)(environment) ||
+        (0, model_js_1.performanceDigest)(aggregateEvidence.period) !== (0, model_js_1.performanceDigest)(period) ||
+        !releasesEqual(aggregateEvidence.release, expectedRelease)) {
+        throw invalid('collector/aggregateEvidence', 'must bind the same exact environment, period, and release as billing collection');
+    }
+    const aggregateCounts = aggregateEvidence.counts.map((entry) => ({
+        ...entry,
+        evidenceDigest: aggregateEvidence.materialDigest,
+    }));
+    assertSameCapabilitySet(allocations, aggregateCounts);
+    const identity = await input.client.getCallerIdentity();
+    requiredReference(identity.requestId, 'collector/identity/requestId');
+    const observedFingerprint = awsAccountFingerprint(identity.accountId);
+    if (observedFingerprint !== environment.accountFingerprint) {
+        throw invalid('collector/environment/accountFingerprint', 'does not match AWS STS caller identity');
+    }
+    const allocationRequest = canonicalRequest(environment, period, 'allocation');
+    const totalRequest = canonicalRequest(environment, period, 'total');
+    const allocationResponse = await input.client.getCostAndUsage(allocationRequest);
+    const totalResponse = await input.client.getCostAndUsage(totalRequest);
+    const allocationResult = exactResult(allocationResponse, allocationRequest, 'collector/allocationResponse');
+    const totalResult = exactResult(totalResponse, totalRequest, 'collector/totalResponse');
+    if (allocationResult.total !== null || totalResult.groups.length !== 0) {
+        throw invalid('collector/responses', 'allocation and total query shapes must remain separate');
+    }
+    if (!totalResult.total || totalResult.total.currency !== 'USD') {
+        throw invalid('collector/totalResponse/results/0/total', 'must contain one USD total');
+    }
+    const requestedById = new Map(allocations.map((allocation) => [allocation.allocationId, allocation]));
+    const seen = new Set();
+    const collectedAllocations = allocationResult.groups
+        .map((group, index) => {
+        if (group.currency !== 'USD' ||
+            !requestedById.has(group.allocationId) ||
+            seen.has(group.allocationId)) {
+            throw invalid(`collector/allocationResponse/results/0/groups/${index}`, 'must be one unique requested USD allocation');
+        }
+        seen.add(group.allocationId);
+        const requested = requestedById.get(group.allocationId);
+        if (!requested) {
+            throw invalid(`collector/allocationResponse/results/0/groups/${index}`, 'does not match a requested allocation');
+        }
+        const amountNanos = moneyNanosFromString(group.amountUsd, `collector/allocationResponse/results/0/groups/${index}/amountUsd`);
+        if (amountNanos <= 0) {
+            throw invalid(`collector/allocationResponse/results/0/groups/${index}/amountUsd`, 'must be positive for a unit-cost capability');
+        }
+        return {
+            allocatedCostUsd: moneyFromNanos(amountNanos),
+            allocationId: requested.allocationId,
+            capabilityId: requested.capabilityId,
+            sourceRowDigest: (0, model_js_1.performanceDigest)(group),
+        };
+    })
+        .sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.allocationId, right.allocationId));
+    if (collectedAllocations.length !== allocations.length) {
+        throw invalid('collector/allocationResponse/results/0/groups', 'must contain every requested allocation exactly once');
+    }
+    const allocatedNanos = collectedAllocations.reduce((sum, allocation) => sum +
+        moneyNanosFromNumber(allocation.allocatedCostUsd, `collector/allocations/${allocation.allocationId}/allocatedCostUsd`), 0);
+    const billedNanos = moneyNanosFromString(totalResult.total.amountUsd, 'collector/totalResponse/results/0/total/amountUsd');
+    if (allocatedNanos !== billedNanos) {
+        throw invalid('collector/reconciliation', 'allocation rows must reconcile exactly to the independently queried total');
+    }
+    const unsigned = {
+        aggregateCounts,
+        allocations: collectedAllocations,
+        authority: {
+            collector: 'ebk-aws-cost-explorer-v1',
+            mode: 'external-read-only',
+            provider: 'aws-billing-actual',
+        },
+        collection,
+        collectedAt,
+        collectorIdentity: {
+            callerIdentityRequestId: identity.requestId,
+        },
+        environment,
+        kind: 'ebk-aws-billing-actual-evidence',
+        period,
+        queries: [
+            {
+                operation: 'ce:GetCostAndUsage',
+                purpose: 'allocation',
+                request: allocationRequest,
+                requestDigest: (0, model_js_1.performanceDigest)(allocationRequest),
+                requestId: allocationResponse.requestId,
+                responseDigest: (0, model_js_1.performanceDigest)(allocationResponse),
+            },
+            {
+                operation: 'ce:GetCostAndUsage',
+                purpose: 'total',
+                request: totalRequest,
+                requestDigest: (0, model_js_1.performanceDigest)(totalRequest),
+                requestId: totalResponse.requestId,
+                responseDigest: (0, model_js_1.performanceDigest)(totalResponse),
+            },
+        ],
+        reconciliation: {
+            allocatedCostUsd: moneyFromNanos(allocatedNanos),
+            allocationCount: collectedAllocations.length,
+            billedCostUsd: moneyFromNanos(billedNanos),
+            differenceUsd: 0,
+        },
+        release: expectedRelease,
+        schemaVersion: 1,
+    };
+    return validateAwsBillingActualEvidence({
+        ...unsigned,
+        materialDigest: (0, model_js_1.performanceDigest)(unsigned),
+    });
+}
+function validateAwsBillingActualEvidence(value) {
+    onlyKeys(value, [
+        'aggregateCounts',
+        'allocations',
+        'authority',
+        'collectedAt',
+        'collection',
+        'collectorIdentity',
+        'environment',
+        'kind',
+        'materialDigest',
+        'period',
+        'queries',
+        'reconciliation',
+        'release',
+        'schemaVersion',
+    ], 'billingEvidence');
+    if (value.kind !== 'ebk-aws-billing-actual-evidence' ||
+        value.schemaVersion !== 1) {
+        throw invalid('billingEvidence', 'must identify canonical v1 AWS billing-actual evidence');
+    }
+    onlyKeys(value.authority, ['collector', 'mode', 'provider'], 'billingEvidence/authority');
+    if (value.authority.collector !== 'ebk-aws-cost-explorer-v1' ||
+        value.authority.mode !== 'external-read-only' ||
+        value.authority.provider !== 'aws-billing-actual') {
+        throw invalid('billingEvidence/authority', 'must identify the managed read-only AWS Cost Explorer collector');
+    }
+    const environment = exactEnvironment(value.environment, 'billingEvidence/environment');
+    const period = exactPeriod(value.period, 'billingEvidence/period');
+    if (!(0, model_js_1.isIsoInstant)(value.collectedAt) ||
+        Date.parse(value.collectedAt) < Date.parse(period.end)) {
+        throw invalid('billingEvidence/collectedAt', 'must be at or after the closed billing period');
+    }
+    const expectedRelease = release(value.release, 'billingEvidence/release');
+    const collection = protectedCollectionIdentity(value.collection, 'billingEvidence/collection');
+    if (collection.sourceCommit !== expectedRelease.sourceCommit) {
+        throw invalid('billingEvidence/collection/sourceCommit', 'must equal the exact billing release source commit');
+    }
+    onlyKeys(value.collectorIdentity, ['callerIdentityRequestId'], 'billingEvidence/collectorIdentity');
+    requiredReference(value.collectorIdentity.callerIdentityRequestId, 'billingEvidence/collectorIdentity/callerIdentityRequestId');
+    if (!Array.isArray(value.queries) || value.queries.length !== 2) {
+        throw invalid('billingEvidence/queries', 'must contain exact allocation and total query evidence');
+    }
+    const expectedPurposes = ['allocation', 'total'];
+    const queries = value.queries.map((query, index) => {
+        const purpose = expectedPurposes[index];
+        onlyKeys(query, [
+            'operation',
+            'purpose',
+            'request',
+            'requestDigest',
+            'requestId',
+            'responseDigest',
+        ], `billingEvidence/queries/${index}`);
+        const expectedRequest = canonicalRequest(environment, period, purpose);
+        if (query.operation !== 'ce:GetCostAndUsage' ||
+            query.purpose !== purpose ||
+            (0, model_js_1.performanceDigest)(query.request) !== (0, model_js_1.performanceDigest)(expectedRequest) ||
+            query.requestDigest !== (0, model_js_1.performanceDigest)(expectedRequest)) {
+            throw invalid(`billingEvidence/queries/${index}`, 'must bind the canonical exact-scope Cost Explorer request');
+        }
+        requiredReference(query.requestId, `billingEvidence/queries/${index}/requestId`);
+        digest(query.responseDigest, `billingEvidence/queries/${index}/responseDigest`);
+        return {
+            operation: 'ce:GetCostAndUsage',
+            purpose,
+            request: expectedRequest,
+            requestDigest: query.requestDigest,
+            requestId: query.requestId,
+            responseDigest: query.responseDigest,
+        };
+    });
+    if (queries[0].requestId === queries[1].requestId ||
+        queries[0].responseDigest === queries[1].responseDigest) {
+        throw invalid('billingEvidence/queries', 'allocation and total queries must retain distinct request and response identities');
+    }
+    if (!Array.isArray(value.allocations) ||
+        value.allocations.length === 0 ||
+        value.allocations.length > MAX_ALLOCATIONS) {
+        throw invalid('billingEvidence/allocations', `must contain between one and ${MAX_ALLOCATIONS} allocations`);
+    }
+    const allocations = value.allocations.map((allocation, index) => {
+        onlyKeys(allocation, ['allocatedCostUsd', 'allocationId', 'capabilityId', 'sourceRowDigest'], `billingEvidence/allocations/${index}`);
+        const amountNanos = moneyNanosFromNumber(allocation.allocatedCostUsd, `billingEvidence/allocations/${index}/allocatedCostUsd`);
+        if (amountNanos <= 0) {
+            throw invalid(`billingEvidence/allocations/${index}/allocatedCostUsd`, 'must be positive for a unit-cost capability');
+        }
+        return {
+            allocatedCostUsd: moneyFromNanos(amountNanos),
+            allocationId: requiredReference(allocation.allocationId, `billingEvidence/allocations/${index}/allocationId`),
+            capabilityId: requiredReference(allocation.capabilityId, `billingEvidence/allocations/${index}/capabilityId`),
+            sourceRowDigest: digest(allocation.sourceRowDigest, `billingEvidence/allocations/${index}/sourceRowDigest`),
+        };
+    });
+    if (new Set(allocations.map(({ allocationId }) => allocationId)).size !==
+        allocations.length ||
+        new Set(allocations.map(({ capabilityId }) => capabilityId)).size !==
+            allocations.length) {
+        throw invalid('billingEvidence/allocations', 'allocation and capability identifiers must each be unique');
+    }
+    const sortedAllocations = [...allocations].sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.allocationId, right.allocationId));
+    if ((0, model_js_1.performanceDigest)(allocations) !== (0, model_js_1.performanceDigest)(sortedAllocations)) {
+        throw invalid('billingEvidence/allocations', 'must be sorted by allocation identifier');
+    }
+    const aggregateCounts = aggregateInputs(value.aggregateCounts);
+    assertSameCapabilitySet(sortedAllocations, aggregateCounts);
+    onlyKeys(value.reconciliation, ['allocatedCostUsd', 'allocationCount', 'billedCostUsd', 'differenceUsd'], 'billingEvidence/reconciliation');
+    const allocatedNanos = sortedAllocations.reduce((sum, allocation, index) => sum +
+        moneyNanosFromNumber(allocation.allocatedCostUsd, `billingEvidence/allocations/${index}/allocatedCostUsd`), 0);
+    const reportedAllocatedNanos = moneyNanosFromNumber(value.reconciliation.allocatedCostUsd, 'billingEvidence/reconciliation/allocatedCostUsd');
+    const billedNanos = moneyNanosFromNumber(value.reconciliation.billedCostUsd, 'billingEvidence/reconciliation/billedCostUsd');
+    if (value.reconciliation.allocationCount !== sortedAllocations.length ||
+        value.reconciliation.differenceUsd !== 0 ||
+        reportedAllocatedNanos !== allocatedNanos ||
+        billedNanos !== allocatedNanos) {
+        throw invalid('billingEvidence/reconciliation', 'must exactly reconcile every allocation row to the billed total');
+    }
+    digest(value.materialDigest, 'billingEvidence/materialDigest');
+    const unsigned = {
+        aggregateCounts,
+        allocations: sortedAllocations,
+        authority: {
+            collector: 'ebk-aws-cost-explorer-v1',
+            mode: 'external-read-only',
+            provider: 'aws-billing-actual',
+        },
+        collectedAt: value.collectedAt,
+        collection,
+        collectorIdentity: {
+            callerIdentityRequestId: value.collectorIdentity
+                .callerIdentityRequestId,
+        },
+        environment,
+        kind: 'ebk-aws-billing-actual-evidence',
+        period,
+        queries,
+        reconciliation: {
+            allocatedCostUsd: moneyFromNanos(allocatedNanos),
+            allocationCount: sortedAllocations.length,
+            billedCostUsd: moneyFromNanos(billedNanos),
+            differenceUsd: 0,
+        },
+        release: expectedRelease,
+        schemaVersion: 1,
+    };
+    const expected = {
+        ...unsigned,
+        materialDigest: (0, model_js_1.performanceDigest)(unsigned),
+    };
+    if (value.materialDigest !== expected.materialDigest) {
+        throw invalid('billingEvidence/materialDigest', 'does not match the canonical evidence bytes');
+    }
+    return expected;
+}
+//# sourceMappingURL=cost-collection.js.map