@spottoai/types-package 1.0.2-dev1138.2 → 1.0.2-dev1138.5

package/dist/esm/environment/contracts.js

@@ -0,0 +1,17 @@
+/** Phase-one environment-memory contract constants shared by producers and consumers. */
+export const ENVIRONMENT_CONTRACT_LIMITS_V1 = Object.freeze({
+    completedPointerBytes: 16 * 1024,
+    projectionBytes: 64 * 1024,
+    environmentIndexBytes: 4 * 1024,
+    costPillarBytes: 8 * 1024,
+    boundedListItems: 50,
+    customerStringScalars: 4096,
+    safeLabelScalars: 512,
+    scopeIdentifierScalars: 2048,
+    environmentRunIdAsciiCharacters: 128,
+    sourceIdentityScalars: 256,
+    logicalReferencePayloadBytes: 4 * 1024,
+    validatedContainerDepth: 8,
+});
+export const ENVIRONMENT_DOCUMENT_NAMES_V1 = ['projection.json', 'environment-index.md', 'pillars/cost.md'];
+export const ENVIRONMENT_ARTIFACT_KINDS_V1 = ['subscription-summary', 'subscription-resources', 'subscription-recommendations'];

package/dist/esm/environment/index.js

@@ -0,0 +1,4 @@
+export * from './contracts.js';
+export * from './references.js';
+export * from './validation.js';
+export * from './canonicalization.js';

package/dist/esm/environment/internal.js

@@ -0,0 +1,97 @@
+import { ENVIRONMENT_CONTRACT_LIMITS_V1 } from './contracts.js';
+export const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+export const ENVIRONMENT_RUN_ID_PATTERN = /^[A-Za-z0-9._-]+$/u;
+export const DECIMAL_PATTERN = /^(?:0|[1-9]\d*)(?:\.\d+)?$/u;
+export const CURRENCY_PATTERN = /^[A-Z]{3}$/u;
+export const PROTOTYPE_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+export const hasControlCharacter = (value) => {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f))
+            return true;
+    }
+    return false;
+};
+export const isRecord = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+export const hasExactKeys = (value, required, optional = []) => {
+    const allowed = new Set([...required, ...optional]);
+    const keys = Object.keys(value);
+    return required.every(key => Object.prototype.hasOwnProperty.call(value, key)) && keys.every(key => allowed.has(key) && !PROTOTYPE_KEYS.has(key));
+};
+const scalarLength = (value) => {
+    let count = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const trailing = value.charCodeAt(index + 1);
+            if (!(trailing >= 0xdc00 && trailing <= 0xdfff))
+                return null;
+            index += 1;
+        }
+        else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            return null;
+        }
+        count += 1;
+    }
+    return count;
+};
+export const isBoundedString = (value, maximumScalars, options = {}) => {
+    if (typeof value !== 'string')
+        return false;
+    if (options.trimmed && (value.length === 0 || value.trim() !== value))
+        return false;
+    if (options.controls && hasControlCharacter(value))
+        return false;
+    const length = scalarLength(value);
+    return length !== null && length <= maximumScalars;
+};
+export const isCustomerString = (value) => isBoundedString(value, ENVIRONMENT_CONTRACT_LIMITS_V1.customerStringScalars, { controls: true });
+export const isSafeLabel = (value) => isBoundedString(value, ENVIRONMENT_CONTRACT_LIMITS_V1.safeLabelScalars, { trimmed: true, controls: true });
+export const isScopeIdentifier = (value) => isBoundedString(value, ENVIRONMENT_CONTRACT_LIMITS_V1.scopeIdentifierScalars, { trimmed: true, controls: true });
+export const isSourceIdentity = (value) => isBoundedString(value, ENVIRONMENT_CONTRACT_LIMITS_V1.sourceIdentityScalars, { trimmed: true, controls: true });
+export const isNonNegativeInteger = (value) => Number.isSafeInteger(value) && value >= 0;
+export const isCanonicalUtcTimestamp = (value) => {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value))
+        return false;
+    const milliseconds = Date.parse(value);
+    return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === value;
+};
+export const utf8ByteLength = (value) => {
+    let bytes = 0;
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint <= 0x7f)
+            bytes += 1;
+        else if (codePoint <= 0x7ff)
+            bytes += 2;
+        else if (codePoint <= 0xffff)
+            bytes += 3;
+        else
+            bytes += 4;
+    }
+    return bytes;
+};
+export const hasSafeContainerShape = (value, depth = 0, seen = new Set()) => {
+    if (depth > ENVIRONMENT_CONTRACT_LIMITS_V1.validatedContainerDepth)
+        return false;
+    if (typeof value !== 'object' || value === null)
+        return true;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        const valid = value.length <= ENVIRONMENT_CONTRACT_LIMITS_V1.boundedListItems && value.every(item => hasSafeContainerShape(item, depth + 1, seen));
+        seen.delete(value);
+        return valid;
+    }
+    if (!isRecord(value))
+        return false;
+    const valid = Object.keys(value).every(key => !PROTOTYPE_KEYS.has(key) && hasSafeContainerShape(value[key], depth + 1, seen));
+    seen.delete(value);
+    return valid;
+};

package/dist/esm/environment/references.js

@@ -0,0 +1,194 @@
+import { ENVIRONMENT_ARTIFACT_KINDS_V1, ENVIRONMENT_CONTRACT_LIMITS_V1, } from './contracts.js';
+import { hasControlCharacter, isBoundedString, utf8ByteLength } from './internal.js';
+const BASE64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const ARTIFACT_PREFIX = 'spotto://artifact/v1/';
+const RESOURCE_PREFIX = 'spotto://resource/v1/';
+const ARTIFACT_KINDS = new Set(ENVIRONMENT_ARTIFACT_KINDS_V1);
+const isCanonicalScopeQualifiedSubject = (value) => {
+    try {
+        const parsed = JSON.parse(value);
+        return (Array.isArray(parsed) &&
+            parsed.length === 4 &&
+            parsed[0] === 'azure-subscription' &&
+            parsed
+                .slice(1)
+                .every(item => isBoundedString(item, ENVIRONMENT_CONTRACT_LIMITS_V1.scopeIdentifierScalars, { trimmed: true, controls: true })) &&
+            JSON.stringify(parsed) === value);
+    }
+    catch {
+        return false;
+    }
+};
+const encodeUtf8 = (value) => {
+    const bytes = [];
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint <= 0x7f)
+            bytes.push(codePoint);
+        else if (codePoint <= 0x7ff)
+            bytes.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+        else if (codePoint <= 0xffff)
+            bytes.push(0xe0 | (codePoint >> 12), 0x80 | ((codePoint >> 6) & 0x3f), 0x80 | (codePoint & 0x3f));
+        else
+            bytes.push(0xf0 | (codePoint >> 18), 0x80 | ((codePoint >> 12) & 0x3f), 0x80 | ((codePoint >> 6) & 0x3f), 0x80 | (codePoint & 0x3f));
+    }
+    return bytes;
+};
+const encodeBase64Url = (bytes) => {
+    let output = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index];
+        const second = bytes[index + 1];
+        const third = bytes[index + 2];
+        output += BASE64URL_ALPHABET[first >> 2];
+        output += BASE64URL_ALPHABET[((first & 0x03) << 4) | ((second ?? 0) >> 4)];
+        if (second !== undefined)
+            output += BASE64URL_ALPHABET[((second & 0x0f) << 2) | ((third ?? 0) >> 6)];
+        if (third !== undefined)
+            output += BASE64URL_ALPHABET[third & 0x3f];
+    }
+    return output;
+};
+const decodeBase64Url = (value) => {
+    if (!/^[A-Za-z0-9_-]+$/u.test(value) || value.length % 4 === 1)
+        return null;
+    const bytes = [];
+    for (let index = 0; index < value.length; index += 4) {
+        const first = BASE64URL_ALPHABET.indexOf(value[index]);
+        const second = BASE64URL_ALPHABET.indexOf(value[index + 1]);
+        const thirdCharacter = value[index + 2];
+        const fourthCharacter = value[index + 3];
+        const third = thirdCharacter === undefined ? 0 : BASE64URL_ALPHABET.indexOf(thirdCharacter);
+        const fourth = fourthCharacter === undefined ? 0 : BASE64URL_ALPHABET.indexOf(fourthCharacter);
+        if (first < 0 || second < 0 || third < 0 || fourth < 0)
+            return null;
+        bytes.push((first << 2) | (second >> 4));
+        if (thirdCharacter !== undefined)
+            bytes.push(((second & 0x0f) << 4) | (third >> 2));
+        if (fourthCharacter !== undefined)
+            bytes.push(((third & 0x03) << 6) | fourth);
+    }
+    return encodeBase64Url(bytes) === value ? bytes : null;
+};
+const decodeUtf8 = (bytes) => {
+    let output = '';
+    for (let index = 0; index < bytes.length;) {
+        const first = bytes[index];
+        let codePoint;
+        let continuationCount;
+        if (first <= 0x7f) {
+            codePoint = first;
+            continuationCount = 0;
+        }
+        else if (first >= 0xc2 && first <= 0xdf) {
+            codePoint = first & 0x1f;
+            continuationCount = 1;
+        }
+        else if (first >= 0xe0 && first <= 0xef) {
+            codePoint = first & 0x0f;
+            continuationCount = 2;
+        }
+        else if (first >= 0xf0 && first <= 0xf4) {
+            codePoint = first & 0x07;
+            continuationCount = 3;
+        }
+        else
+            return null;
+        if (index + continuationCount >= bytes.length)
+            return null;
+        for (let offset = 1; offset <= continuationCount; offset += 1) {
+            const next = bytes[index + offset];
+            if ((next & 0xc0) !== 0x80)
+                return null;
+            codePoint = (codePoint << 6) | (next & 0x3f);
+        }
+        if ((continuationCount === 2 && codePoint < 0x800) ||
+            (continuationCount === 3 && codePoint < 0x10000) ||
+            (codePoint >= 0xd800 && codePoint <= 0xdfff) ||
+            codePoint > 0x10ffff) {
+            return null;
+        }
+        output += String.fromCodePoint(codePoint);
+        index += continuationCount + 1;
+    }
+    return output;
+};
+const decodePayload = (value) => {
+    const bytes = decodeBase64Url(value);
+    if (bytes === null || bytes.length > ENVIRONMENT_CONTRACT_LIMITS_V1.logicalReferencePayloadBytes)
+        return null;
+    const decoded = decodeUtf8(bytes);
+    if (decoded === null || encodeBase64Url(encodeUtf8(decoded)) !== value)
+        return null;
+    return decoded;
+};
+const assertReferencePayload = (value, label, maximumScalars) => {
+    if (!isBoundedString(value, maximumScalars, { trimmed: true, controls: true })) {
+        throw new TypeError(`${label} must be a non-empty, trimmed, bounded Unicode string without control characters.`);
+    }
+    if (utf8ByteLength(value) > ENVIRONMENT_CONTRACT_LIMITS_V1.logicalReferencePayloadBytes) {
+        throw new RangeError(`${label} exceeds the V1 logical-reference payload limit.`);
+    }
+};
+const isCanonicalAzureResourceId = (value) => {
+    if (!/^\/subscriptions\/[^/]+\/(?:resourceGroups\/[^/]+\/)?providers\/[^/]+\/[^/]+\/[^/]+(?:\/[^/]+\/[^/]+)*$/iu.test(value) ||
+        value.includes('\\') ||
+        value.includes('?') ||
+        value.includes('#') ||
+        value.includes('%') ||
+        hasControlCharacter(value)) {
+        return false;
+    }
+    return value.split('/').every(segment => segment !== '.' && segment !== '..');
+};
+/** Builds an opaque logical artifact reference. The decoded subject is never a storage path. */
+export const buildEnvironmentLogicalArtifactReferenceV1 = (artifactKind, canonicalScopeQualifiedSubject) => {
+    if (!ARTIFACT_KINDS.has(artifactKind))
+        throw new TypeError('Unsupported V1 environment artifact kind.');
+    assertReferencePayload(canonicalScopeQualifiedSubject, 'Artifact subject', ENVIRONMENT_CONTRACT_LIMITS_V1.customerStringScalars);
+    if (!isCanonicalScopeQualifiedSubject(canonicalScopeQualifiedSubject)) {
+        throw new TypeError('Artifact subject is not a canonical V1 scope-qualified subject.');
+    }
+    return `${ARTIFACT_PREFIX}${artifactKind}/${encodeBase64Url(encodeUtf8(canonicalScopeQualifiedSubject))}`;
+};
+/** Parses a V1 logical artifact reference into its allowlisted kind and opaque subject. */
+export const parseEnvironmentLogicalArtifactReferenceV1 = (value) => {
+    if (typeof value !== 'string' || !value.startsWith(ARTIFACT_PREFIX))
+        return null;
+    const remainder = value.slice(ARTIFACT_PREFIX.length);
+    const separator = remainder.indexOf('/');
+    if (separator <= 0 || remainder.indexOf('/', separator + 1) >= 0)
+        return null;
+    const artifactKind = remainder.slice(0, separator);
+    if (!ARTIFACT_KINDS.has(artifactKind))
+        return null;
+    const subject = decodePayload(remainder.slice(separator + 1));
+    if (subject === null || !isCanonicalScopeQualifiedSubject(subject)) {
+        return null;
+    }
+    return { kind: 'artifact', artifactKind: artifactKind, subject };
+};
+/** Builds an opaque logical Azure resource reference from a canonical resource ID. */
+export const buildEnvironmentLogicalResourceReferenceV1 = (canonicalAzureResourceId) => {
+    assertReferencePayload(canonicalAzureResourceId, 'Azure resource ID', ENVIRONMENT_CONTRACT_LIMITS_V1.scopeIdentifierScalars);
+    if (!isCanonicalAzureResourceId(canonicalAzureResourceId))
+        throw new TypeError('Azure resource ID is not canonical or safe.');
+    return `${RESOURCE_PREFIX}${encodeBase64Url(encodeUtf8(canonicalAzureResourceId))}`;
+};
+/** Parses a V1 logical resource reference into a canonical Azure resource ID. */
+export const parseEnvironmentLogicalResourceReferenceV1 = (value) => {
+    if (typeof value !== 'string' || !value.startsWith(RESOURCE_PREFIX))
+        return null;
+    const resourceId = decodePayload(value.slice(RESOURCE_PREFIX.length));
+    if (resourceId === null || !isCanonicalAzureResourceId(resourceId))
+        return null;
+    return { kind: 'resource', resourceId };
+};
+/** Parses either closed V1 logical evidence-reference kind. */
+export const parseEnvironmentLogicalEvidenceReferenceV1 = (value) => parseEnvironmentLogicalArtifactReferenceV1(value) ?? parseEnvironmentLogicalResourceReferenceV1(value);
+/** Returns true when a value is a canonical V1 logical artifact reference. */
+export const isEnvironmentLogicalArtifactReferenceV1 = (value) => parseEnvironmentLogicalArtifactReferenceV1(value) !== null;
+/** Returns true when a value is a canonical V1 logical resource reference. */
+export const isEnvironmentLogicalResourceReferenceV1 = (value) => parseEnvironmentLogicalResourceReferenceV1(value) !== null;
+/** Returns true when a value is one of the closed V1 logical evidence-reference kinds. */
+export const isEnvironmentLogicalEvidenceReferenceV1 = (value) => parseEnvironmentLogicalEvidenceReferenceV1(value) !== null;

package/dist/esm/environment/validation.js

@@ -0,0 +1,303 @@
+import { ENVIRONMENT_ARTIFACT_KINDS_V1, ENVIRONMENT_CONTRACT_LIMITS_V1, ENVIRONMENT_DOCUMENT_NAMES_V1, } from './contracts.js';
+import { CURRENCY_PATTERN, DECIMAL_PATTERN, ENVIRONMENT_RUN_ID_PATTERN, SHA256_PATTERN, hasExactKeys, hasSafeContainerShape, isBoundedString, isCanonicalUtcTimestamp, isCustomerString, isNonNegativeInteger, isRecord, isSafeLabel, isScopeIdentifier, isSourceIdentity, utf8ByteLength, } from './internal.js';
+import { isEnvironmentLogicalEvidenceReferenceV1, isEnvironmentLogicalResourceReferenceV1 } from './references.js';
+const DOCUMENT_NAMES = new Set(ENVIRONMENT_DOCUMENT_NAMES_V1);
+const ARTIFACT_KINDS = new Set(ENVIRONMENT_ARTIFACT_KINDS_V1);
+const MONEY_BASES = new Set(['billed', 'amortized']);
+const MONEY_PROVENANCE = new Set([
+    'subscription-summary',
+    'subscription-resources',
+    'cost-savings-summary',
+    'savings-aggregate',
+    'recommendation',
+]);
+const SAVINGS_ADDITIVITY = new Set(['additive', 'scenario-non-additive']);
+const CHANGE_DIRECTIONS = new Set(['increase', 'decrease', 'unchanged', 'unknown']);
+const scopesEqual = (left, right) => left.kind === right.kind && left.tenantId === right.tenantId && left.companyId === right.companyId && left.subscriptionId === right.subscriptionId;
+/** Validates a bounded, local Portal route suitable for client-visible evidence. */
+export const isEnvironmentPortalRouteV1 = (value) => isBoundedString(value, ENVIRONMENT_CONTRACT_LIMITS_V1.customerStringScalars, { trimmed: true, controls: true }) &&
+    value.startsWith('/') &&
+    !value.startsWith('//') &&
+    !value.includes('\\') &&
+    !value.includes('://') &&
+    !value.includes('?') &&
+    !value.includes('#') &&
+    !value.includes('%') &&
+    value.split('/').every(segment => segment !== '.' && segment !== '..');
+const isGeneralKey = (value) => isBoundedString(value, ENVIRONMENT_CONTRACT_LIMITS_V1.safeLabelScalars, { trimmed: true, controls: true });
+const isReferenceArray = (value) => Array.isArray(value) &&
+    value.length <= ENVIRONMENT_CONTRACT_LIMITS_V1.boundedListItems &&
+    value.every(isEnvironmentLogicalEvidenceReferenceV1) &&
+    new Set(value).size === value.length;
+/** Validates the closed phase-one Azure subscription scope. */
+export const isEnvironmentScopeV1 = (value) => isRecord(value) &&
+    hasExactKeys(value, ['kind', 'tenantId', 'companyId', 'subscriptionId']) &&
+    value.kind === 'azure-subscription' &&
+    isScopeIdentifier(value.tenantId) &&
+    isScopeIdentifier(value.companyId) &&
+    isScopeIdentifier(value.subscriptionId);
+/** Validates the client-safe identity of one authoritative source generation. */
+export const isEnvironmentSourceGenerationV1 = (value) => isRecord(value) &&
+    hasExactKeys(value, [
+        'viewSetSchemaVersion',
+        'publicationId',
+        'portalRunId',
+        'pluginRunId',
+        'economicsGenerationId',
+        'economicsFingerprint',
+        'completedAt',
+    ]) &&
+    value.viewSetSchemaVersion === 1 &&
+    isSourceIdentity(value.publicationId) &&
+    isSourceIdentity(value.portalRunId) &&
+    isSourceIdentity(value.pluginRunId) &&
+    isSourceIdentity(value.economicsGenerationId) &&
+    isSourceIdentity(value.economicsFingerprint) &&
+    isCanonicalUtcTimestamp(value.completedAt);
+/** Validates a byte-preserving binding to an authoritative CompletedAzureViewSetV1. */
+export const isEnvironmentSourceBindingV1 = (value) => isRecord(value) &&
+    hasExactKeys(value, [
+        'kind',
+        'viewSetSchemaVersion',
+        'scope',
+        'publicationId',
+        'portalRunId',
+        'pluginRunId',
+        'economicsGenerationId',
+        'economicsFingerprint',
+        'completedAt',
+    ]) &&
+    value.kind === 'azure-subscription-view-set' &&
+    value.viewSetSchemaVersion === 1 &&
+    isEnvironmentScopeV1(value.scope) &&
+    isEnvironmentSourceGenerationV1({
+        viewSetSchemaVersion: value.viewSetSchemaVersion,
+        publicationId: value.publicationId,
+        portalRunId: value.portalRunId,
+        pluginRunId: value.pluginRunId,
+        economicsGenerationId: value.economicsGenerationId,
+        economicsFingerprint: value.economicsFingerprint,
+        completedAt: value.completedAt,
+    });
+/** Validates a storage-safe environment run identity independently from source identities. */
+export const isEnvironmentRunIdV1 = (value) => typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= ENVIRONMENT_CONTRACT_LIMITS_V1.environmentRunIdAsciiCharacters &&
+    value !== '.' &&
+    value !== '..' &&
+    ENVIRONMENT_RUN_ID_PATTERN.test(value);
+/** Validates canonical decimal money with explicit currency, basis, period, and provenance. */
+export const isEnvironmentMoneyValueV1 = (value) => isRecord(value) &&
+    hasExactKeys(value, ['amount', 'currencyCode', 'basis', 'period', 'provenance'], ['savingsAdditivity']) &&
+    typeof value.amount === 'string' &&
+    DECIMAL_PATTERN.test(value.amount) &&
+    typeof value.currencyCode === 'string' &&
+    CURRENCY_PATTERN.test(value.currencyCode) &&
+    typeof value.basis === 'string' &&
+    MONEY_BASES.has(value.basis) &&
+    isBoundedString(value.period, ENVIRONMENT_CONTRACT_LIMITS_V1.safeLabelScalars, { trimmed: true, controls: true }) &&
+    typeof value.provenance === 'string' &&
+    MONEY_PROVENANCE.has(value.provenance) &&
+    (value.savingsAdditivity === undefined || (typeof value.savingsAdditivity === 'string' && SAVINGS_ADDITIVITY.has(value.savingsAdditivity)));
+const isObservedMoney = (value) => isEnvironmentMoneyValueV1(value) && value.savingsAdditivity === undefined;
+const isSavingsMoney = (value) => isEnvironmentMoneyValueV1(value) && value.savingsAdditivity !== undefined;
+/** Validates the closed coverage-state union and state-specific freshness rules. */
+export const isEnvironmentCoverageStateV1 = (value) => {
+    if (!isRecord(value) || typeof value.status !== 'string')
+        return false;
+    const hasValidFreshness = (value.observedAt === undefined || isCanonicalUtcTimestamp(value.observedAt)) &&
+        (value.completeThrough === undefined || isCanonicalUtcTimestamp(value.completeThrough)) &&
+        (value.observedAt === undefined ||
+            value.completeThrough === undefined ||
+            Date.parse(value.completeThrough) <= Date.parse(value.observedAt));
+    if (value.status === 'complete') {
+        return hasExactKeys(value, ['status'], ['observedAt', 'completeThrough']) && hasValidFreshness;
+    }
+    if (value.status === 'partial') {
+        return (hasExactKeys(value, ['status', 'reason'], ['observedAt', 'completeThrough']) &&
+            isCustomerString(value.reason) &&
+            value.reason.length > 0 &&
+            hasValidFreshness);
+    }
+    if (value.status === 'stale') {
+        return (hasExactKeys(value, ['status', 'reason', 'observedAt'], ['completeThrough']) &&
+            isCustomerString(value.reason) &&
+            value.reason.length > 0 &&
+            hasValidFreshness);
+    }
+    if (value.status === 'unavailable' || value.status === 'not-collected') {
+        return hasExactKeys(value, ['status', 'reason']) && isCustomerString(value.reason) && value.reason.length > 0;
+    }
+    return false;
+};
+const isBoundedList = (value, itemValidator) => {
+    if (!isRecord(value) || !hasExactKeys(value, ['items', 'totalCount', 'includedCount', 'truncated'], ['continuationReference']))
+        return false;
+    if (!Array.isArray(value.items) || value.items.length > ENVIRONMENT_CONTRACT_LIMITS_V1.boundedListItems || !value.items.every(itemValidator))
+        return false;
+    if (!isNonNegativeInteger(value.totalCount) || !isNonNegativeInteger(value.includedCount))
+        return false;
+    if (value.includedCount !== value.items.length || value.totalCount < value.includedCount || typeof value.truncated !== 'boolean')
+        return false;
+    if (value.truncated !== value.totalCount > value.includedCount)
+        return false;
+    if (value.continuationReference !== undefined && !isEnvironmentLogicalEvidenceReferenceV1(value.continuationReference))
+        return false;
+    return !value.truncated || value.continuationReference !== undefined;
+};
+const isCostRollup = (value) => isRecord(value) &&
+    hasExactKeys(value, ['key', 'safeLabel', 'resourceCount', 'sourceReferences'], ['observedCost', 'potentialSavings']) &&
+    isGeneralKey(value.key) &&
+    isSafeLabel(value.safeLabel) &&
+    isNonNegativeInteger(value.resourceCount) &&
+    (value.observedCost === undefined || isObservedMoney(value.observedCost)) &&
+    (value.potentialSavings === undefined || isSavingsMoney(value.potentialSavings)) &&
+    isReferenceArray(value.sourceReferences);
+const isCostDriver = (value) => isRecord(value) &&
+    hasExactKeys(value, ['key', 'safeLabel', 'sourceReferences'], ['description', 'observedCost', 'portalRoute', 'resourceReference']) &&
+    isGeneralKey(value.key) &&
+    isSafeLabel(value.safeLabel) &&
+    (value.description === undefined || isCustomerString(value.description)) &&
+    (value.observedCost === undefined || isObservedMoney(value.observedCost)) &&
+    (value.portalRoute === undefined || isEnvironmentPortalRouteV1(value.portalRoute)) &&
+    (value.resourceReference === undefined || isEnvironmentLogicalResourceReferenceV1(value.resourceReference)) &&
+    isReferenceArray(value.sourceReferences);
+const isRecommendation = (value) => isRecord(value) &&
+    hasExactKeys(value, ['recommendationId', 'safeLabel', 'portalRoute', 'sourceReferences'], ['description', 'potentialSavings']) &&
+    isScopeIdentifier(value.recommendationId) &&
+    isSafeLabel(value.safeLabel) &&
+    isEnvironmentPortalRouteV1(value.portalRoute) &&
+    (value.description === undefined || isCustomerString(value.description)) &&
+    (value.potentialSavings === undefined || isSavingsMoney(value.potentialSavings)) &&
+    isReferenceArray(value.sourceReferences);
+const isCostChange = (value) => isRecord(value) &&
+    hasExactKeys(value, ['key', 'safeLabel', 'description', 'direction', 'sourceReferences'], ['amount']) &&
+    isGeneralKey(value.key) &&
+    isSafeLabel(value.safeLabel) &&
+    isCustomerString(value.description) &&
+    typeof value.direction === 'string' &&
+    CHANGE_DIRECTIONS.has(value.direction) &&
+    (value.amount === undefined || isObservedMoney(value.amount)) &&
+    isReferenceArray(value.sourceReferences);
+const isWarning = (value) => isRecord(value) &&
+    hasExactKeys(value, ['code', 'safeLabel', 'sourceReferences'], ['detail']) &&
+    isGeneralKey(value.code) &&
+    isSafeLabel(value.safeLabel) &&
+    (value.detail === undefined || isCustomerString(value.detail)) &&
+    isReferenceArray(value.sourceReferences);
+const isSourceCoverage = (value) => isRecord(value) &&
+    hasExactKeys(value, ['subscriptionSummary', 'resources', 'recommendations', 'costs', 'savings']) &&
+    isEnvironmentCoverageStateV1(value.subscriptionSummary) &&
+    isEnvironmentCoverageStateV1(value.resources) &&
+    isEnvironmentCoverageStateV1(value.recommendations) &&
+    isEnvironmentCoverageStateV1(value.costs) &&
+    isEnvironmentCoverageStateV1(value.savings);
+const isCostSummary = (value) => isRecord(value) &&
+    hasExactKeys(value, [], ['observedCost', 'potentialSavings', 'resourceCount', 'recommendationCount']) &&
+    (value.observedCost === undefined || isObservedMoney(value.observedCost)) &&
+    (value.potentialSavings === undefined || isSavingsMoney(value.potentialSavings)) &&
+    (value.resourceCount === undefined || isNonNegativeInteger(value.resourceCount)) &&
+    (value.recommendationCount === undefined || isNonNegativeInteger(value.recommendationCount));
+/** Validates the strict, bounded phase-one subscription-cost projection. */
+export const isEnvironmentSubscriptionCostProjectionV1 = (value) => {
+    if (!hasSafeContainerShape(value) || !isRecord(value))
+        return false;
+    if (!hasExactKeys(value, [
+        'schemaVersion',
+        'scope',
+        'sourceBinding',
+        'generatedAt',
+        'subscription',
+        'sourceCoverage',
+        'costSummary',
+        'serviceFamilyRollups',
+        'estateCostRollups',
+        'costDrivers',
+        'recommendations',
+        'changes',
+        'warnings',
+        'sourceReferences',
+    ]) ||
+        value.schemaVersion !== 1 ||
+        !isEnvironmentScopeV1(value.scope) ||
+        !isEnvironmentSourceBindingV1(value.sourceBinding) ||
+        !scopesEqual(value.scope, value.sourceBinding.scope) ||
+        !isCanonicalUtcTimestamp(value.generatedAt) ||
+        Date.parse(value.generatedAt) < Date.parse(value.sourceBinding.completedAt) ||
+        !isRecord(value.subscription) ||
+        !hasExactKeys(value.subscription, ['safeLabel', 'portalRoute']) ||
+        !isSafeLabel(value.subscription.safeLabel) ||
+        !isEnvironmentPortalRouteV1(value.subscription.portalRoute) ||
+        !isSourceCoverage(value.sourceCoverage) ||
+        !isCostSummary(value.costSummary) ||
+        !isBoundedList(value.serviceFamilyRollups, isCostRollup) ||
+        !isBoundedList(value.estateCostRollups, isCostRollup) ||
+        !isBoundedList(value.costDrivers, isCostDriver) ||
+        !isBoundedList(value.recommendations, isRecommendation) ||
+        !isBoundedList(value.changes, isCostChange) ||
+        !isBoundedList(value.warnings, isWarning) ||
+        !isReferenceArray(value.sourceReferences)) {
+        return false;
+    }
+    return utf8ByteLength(JSON.stringify(value)) <= ENVIRONMENT_CONTRACT_LIMITS_V1.projectionBytes;
+};
+const descriptorByteLimit = (name) => {
+    if (name === 'projection.json')
+        return ENVIRONMENT_CONTRACT_LIMITS_V1.projectionBytes;
+    if (name === 'environment-index.md')
+        return ENVIRONMENT_CONTRACT_LIMITS_V1.environmentIndexBytes;
+    return ENVIRONMENT_CONTRACT_LIMITS_V1.costPillarBytes;
+};
+/** Validates one descriptor from the exact V1 three-document allowlist. */
+export const isEnvironmentDocumentDescriptorV1 = (value) => {
+    if (!isRecord(value) || !hasExactKeys(value, ['name', 'mediaType', 'byteCount', 'contentSha256', 'approximateTokenCount']))
+        return false;
+    if (typeof value.name !== 'string' || !DOCUMENT_NAMES.has(value.name))
+        return false;
+    const expectedMediaType = value.name === 'projection.json' ? 'application/json' : 'text/markdown; charset=utf-8';
+    return (value.mediaType === expectedMediaType &&
+        isNonNegativeInteger(value.byteCount) &&
+        value.byteCount > 0 &&
+        value.byteCount <= descriptorByteLimit(value.name) &&
+        typeof value.contentSha256 === 'string' &&
+        SHA256_PATTERN.test(value.contentSha256) &&
+        isNonNegativeInteger(value.approximateTokenCount));
+};
+/** Validates that descriptors contain each allowlisted V1 document exactly once. */
+export const isEnvironmentDocumentDescriptorSetV1 = (value) => Array.isArray(value) &&
+    value.length === ENVIRONMENT_DOCUMENT_NAMES_V1.length &&
+    value.every(isEnvironmentDocumentDescriptorV1) &&
+    new Set(value.map(descriptor => descriptor.name)).size === ENVIRONMENT_DOCUMENT_NAMES_V1.length &&
+    ENVIRONMENT_DOCUMENT_NAMES_V1.every(name => value.some(descriptor => descriptor.name === name));
+/** Validates an atomically visible completed environment-generation pointer. */
+export const isEnvironmentCompiledGenerationPointerV1 = (value) => {
+    if (!hasSafeContainerShape(value) || !isRecord(value))
+        return false;
+    if (!hasExactKeys(value, ['schemaVersion', 'status', 'environmentRunId', 'scope', 'sourceBinding', 'treeDigestSha256', 'fileCount', 'generatedAt']) ||
+        value.schemaVersion !== 1 ||
+        value.status !== 'completed' ||
+        !isEnvironmentRunIdV1(value.environmentRunId) ||
+        !isEnvironmentScopeV1(value.scope) ||
+        !isEnvironmentSourceBindingV1(value.sourceBinding) ||
+        !scopesEqual(value.scope, value.sourceBinding.scope) ||
+        typeof value.treeDigestSha256 !== 'string' ||
+        !SHA256_PATTERN.test(value.treeDigestSha256) ||
+        value.fileCount !== 3 ||
+        !isCanonicalUtcTimestamp(value.generatedAt) ||
+        Date.parse(value.generatedAt) < Date.parse(value.sourceBinding.completedAt)) {
+        return false;
+    }
+    const sourceIdentities = [
+        value.sourceBinding.publicationId,
+        value.sourceBinding.portalRunId,
+        value.sourceBinding.pluginRunId,
+        value.sourceBinding.economicsGenerationId,
+        value.sourceBinding.economicsFingerprint,
+    ];
+    return (!sourceIdentities.includes(value.environmentRunId) &&
+        utf8ByteLength(JSON.stringify(value)) <= ENVIRONMENT_CONTRACT_LIMITS_V1.completedPointerBytes);
+};
+/** Validates the artifact kind without widening the closed V1 union. */
+export const isEnvironmentArtifactKindV1 = (value) => typeof value === 'string' && ARTIFACT_KINDS.has(value);
+/** Validates the V1 safe-label bound used by customer-visible evidence metadata. */
+export const isEnvironmentSafeLabelV1 = (value) => isSafeLabel(value);

package/dist/esm/index.js

@@ -44,6 +44,7 @@ export * from './azure/storage-inventory.js';
 export * from './azure/governance.js';
 export * from './azure/publicIpAddresses.js';
 export * from './azure/workManagement.js';
+export * from './azure/vmPatchManagement.js';
 export * from './aws/index.js';
 export * from './accounts/index.js';
 export * from './assessments/index.js';
@@ -54,6 +55,7 @@ export * from './company/index.js';
 export * from './customProperties/index.js';
 export * from './scheduler/index.js';
 export * from './ai/index.js';
+export * from './environment/index.js';
 export * from './events/index.js';
 export * from './integrations/index.js';
 export * from './identity/index.js';

package/dist/index.d.ts

@@ -44,6 +44,7 @@ export * from './azure/storage-inventory';
 export * from './azure/governance';
 export * from './azure/publicIpAddresses';
 export * from './azure/workManagement';
+export * from './azure/vmPatchManagement';
 export * from './aws';
 export * from './accounts';
 export * from './assessments';
@@ -54,6 +55,7 @@ export * from './company';
 export * from './customProperties';
 export * from './scheduler';
 export * from './ai';
+export * from './environment';
 export * from './events';
 export * from './integrations';
 export * from './identity';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,MAAM,CAAC;AACrB,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,MAAM,CAAC;AACrB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC"}