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

package/dist/esm/common/validationHelpers.js

@@ -0,0 +1,115 @@
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const isString = (value) => typeof value === 'string' && value.trim().length > 0;
+export const isOptionalString = (value) => value === undefined || isString(value);
+export const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+export const isOptionalFiniteNumber = (value) => value === undefined || isFiniteNumber(value);
+export const isOptionalBoolean = (value) => value === undefined || typeof value === 'boolean';
+export const isCount = (value) => isFiniteNumber(value) && Number.isInteger(value) && value >= 0;
+export const isDateTime = (value) => isString(value) && Number.isFinite(Date.parse(value));
+export const isStringArray = (value) => Array.isArray(value) && value.every(isString);
+export const isCountRecord = (value) => isRecord(value) && Object.values(value).every(isCount);
+export const countTotal = (value) => Object.values(value).reduce((total, count) => total + count, 0);
+export const hasOptionalStrings = (value, keys) => keys.every(key => isOptionalString(value[key]));
+export const hasOptionalNumbers = (value, keys) => keys.every(key => isOptionalFiniteNumber(value[key]));
+export const isBoundedRows = (value, limit, isRow) => {
+    if (!isRecord(value) || !isCount(value.totalCount) || !isCount(value.omittedCount) || !Array.isArray(value.rows))
+        return false;
+    return value.rows.length <= limit && value.rows.every(isRow) && value.totalCount === value.rows.length + value.omittedCount;
+};
+/*
+ * Throwing assertion primitives for exact-shape boundary validators. Each
+ * failure names the offending field path so rejections are diagnosable.
+ */
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+export function asRecord(value, field) {
+    if (!isRecord(value))
+        throw new Error(`${field} must be a JSON object.`);
+    return value;
+}
+export function asArray(value, field, nonEmpty = false) {
+    if (!Array.isArray(value) || (nonEmpty && value.length === 0))
+        throw new Error(`${field} must be ${nonEmpty ? 'a non-empty' : 'an'} array.`);
+    return value;
+}
+export function requiredString(value, field) {
+    if (typeof value !== 'string' || value.trim() !== value || value.length === 0)
+        throw new Error(`${field} must be a non-empty trimmed string.`);
+    return value;
+}
+export function requiredEnum(value, values, field) {
+    if (typeof value !== 'string' || !values.includes(value))
+        throw new Error(`${field} is not declared.`);
+    return value;
+}
+export function requiredBoolean(value, field) {
+    if (typeof value !== 'boolean')
+        throw new Error(`${field} must be a boolean.`);
+    return value;
+}
+export function nonNegativeInteger(value, field) {
+    if (!Number.isSafeInteger(value) || Number(value) < 0)
+        throw new Error(`${field} must be a non-negative safe integer.`);
+    return Number(value);
+}
+export function finiteNumber(value, field) {
+    if (!isFiniteNumber(value))
+        throw new Error(`${field} must be a finite number.`);
+    return value;
+}
+export function isoTimestamp(value, field) {
+    const timestamp = requiredString(value, field);
+    if (!ISO_TIMESTAMP_PATTERN.test(timestamp) || Number.isNaN(Date.parse(timestamp)))
+        throw new Error(`${field} must be an ISO UTC timestamp.`);
+    return timestamp;
+}
+export function assertExactKeys(value, allowed, field) {
+    const allowedKeys = new Set(allowed);
+    const unknown = Object.keys(value).filter(key => !allowedKeys.has(key));
+    if (unknown.length > 0)
+        throw new Error(`${field} contains undeclared fields: ${unknown.sort().join(', ')}.`);
+}
+export function assertValue(actual, expected, field) {
+    if (actual !== expected)
+        throw new Error(`${field} must match its exact binding.`);
+}
+export function assertUnique(values, field) {
+    if (new Set(values).size !== values.length)
+        throw new Error(`${field} must not contain duplicates.`);
+}
+export function requiredPublicIdentifier(value, field) {
+    const identifier = requiredString(value, field);
+    if (identifier.includes('/') || identifier.includes('\\') || identifier.includes('://') || identifier.includes('..'))
+        throw new Error(`${field} must not contain a physical path or URI.`);
+    return identifier;
+}
+/** Validates an exact `ArtifactGeneration` identity. */
+export function validateGeneration(value, field) {
+    const generation = asRecord(value, field);
+    assertExactKeys(generation, ['runId', 'generatedAt'], field);
+    return {
+        runId: requiredPublicIdentifier(generation.runId, `${field}.runId`),
+        generatedAt: isoTimestamp(generation.generatedAt, `${field}.generatedAt`),
+    };
+}
+/** Rejects non-JSON values and non-plain objects; `isForbiddenKey` rejects keys at every depth. */
+export function assertPlainJson(value, field, isForbiddenKey = () => false) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`${field} must contain only finite JSON numbers.`);
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertPlainJson(item, `${field}[${index}]`, isForbiddenKey));
+        return;
+    }
+    if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error(`${field} must contain only plain JSON values.`);
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (isForbiddenKey(key))
+            throw new Error(`${field}.${key} is not allowed in a public artifact.`);
+        assertPlainJson(child, `${field}.${key}`, isForbiddenKey);
+    }
+}

package/dist/esm/entries/commitments-planning.js

@@ -1,3 +1,3 @@
-export * from '../aws/commitmentsPlanningValidation.js';
-import * as namespace from '../aws/commitmentsPlanningValidation.js';
+export * from '../aws/commitments-planning.js';
+import * as namespace from '../aws/commitments-planning.js';
 export default namespace;

package/dist/esm/entries/environment.js

@@ -0,0 +1,3 @@
+export * from '../environment/index.js';
+import * as namespace from '../environment/index.js';
+export default namespace;

package/dist/esm/entries/relationships.js

@@ -1,3 +1,3 @@
-export * from '../aws/portalRelationshipPublicArtifactValidation.js';
-import * as namespace from '../aws/portalRelationshipPublicArtifactValidation.js';
+export * from '../aws/relationships.js';
+import * as namespace from '../aws/relationships.js';
 export default namespace;

package/dist/esm/environment/canonicalization.js

@@ -0,0 +1,34 @@
+import { isEnvironmentDocumentDescriptorSetV1, isEnvironmentScopeV1 } from './validation.js';
+const compareUnicodeCodePoints = (left, right) => {
+    const leftPoints = Array.from(left, character => character.codePointAt(0));
+    const rightPoints = Array.from(right, character => character.codePointAt(0));
+    const length = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = leftPoints[index] - rightPoints[index];
+        if (difference !== 0)
+            return difference;
+    }
+    return leftPoints.length - rightPoints.length;
+};
+/**
+ * Builds the canonical scope-qualified artifact subject used inside opaque
+ * logical references. The JSON tuple is an identifier, never a storage path.
+ */
+export const buildEnvironmentScopeQualifiedSubjectV1 = (scope) => {
+    if (!isEnvironmentScopeV1(scope))
+        throw new TypeError('Invalid V1 environment scope.');
+    return JSON.stringify([scope.kind, scope.tenantId, scope.companyId, scope.subscriptionId]);
+};
+/**
+ * Produces the exact compact UTF-8 tree-digest preimage. Hashing remains the
+ * caller's responsibility so this helper stays browser-safe.
+ */
+export const buildEnvironmentTreeDigestPreimageV1 = (descriptors) => {
+    if (!isEnvironmentDocumentDescriptorSetV1(descriptors)) {
+        throw new TypeError('V1 environment tree digests require each allowlisted document exactly once.');
+    }
+    const pairs = descriptors
+        .map(descriptor => [descriptor.name, descriptor.contentSha256])
+        .sort((left, right) => compareUnicodeCodePoints(left[0], right[0]));
+    return JSON.stringify(pairs);
+};

package/dist/esm/environment/contracts.js

@@ -0,0 +1,69 @@
+/** Single pre-release multi-pillar environment contract shared by producers and consumers. */
+export const ENVIRONMENT_CONTRACT_LIMITS_V1 = Object.freeze({
+    completedPointerBytes: 16 * 1024,
+    projectionBytes: 256 * 1024,
+    environmentIndexBytes: 8 * 1024,
+    pillarDocumentBytes: 8 * 1024,
+    boundedListItems: 50,
+    /**
+     * Row cap for the optional structured detail sections. Deliberately far below
+     * `boundedListItems`: the core lists already consume most of the projection byte budget,
+     * and a detail section is a summary, not an inventory.
+     */
+    sectionListItems: 10,
+    customerStringScalars: 4096,
+    safeLabelScalars: 512,
+    scopeIdentifierScalars: 2048,
+    environmentRunIdAsciiCharacters: 128,
+    sourceIdentityScalars: 256,
+    logicalReferencePayloadBytes: 4 * 1024,
+    validatedContainerDepth: 10,
+});
+export const ENVIRONMENT_PILLARS_V1 = ['cost', 'security', 'governance', 'reliability', 'performance', 'operations'];
+export const ENVIRONMENT_DOCUMENT_NAMES_V1 = [
+    'projection.json',
+    'environment-index.md',
+    'pillars/cost.md',
+    'pillars/security.md',
+    'pillars/governance.md',
+    'pillars/reliability.md',
+    'pillars/performance.md',
+    'pillars/operations.md',
+];
+export const ENVIRONMENT_ARTIFACT_KINDS_V1 = [
+    'subscription-summary',
+    'subscription-resources',
+    'subscription-recommendations',
+    'subscription-service-retirements',
+    'subscription-monitor-alerts',
+    'subscription-data-protection',
+    'subscription-system-tracks',
+    'subscription-metrics',
+    // API-issued evidence kind: a bounded projection of one compiled `projection.json` detail section
+    // (commitments, budgets, idle resources, ...). Never emitted by the compiler as a source reference.
+    'subscription-projection',
+    'tenant-governance',
+    'tenant-governance-access',
+    'tenant-reservations',
+    'tenant-savings-plans',
+    'tenant-applications',
+    'tenant-service-principals',
+];
+export const ENVIRONMENT_FINDING_KINDS_V1 = [
+    'recommendation',
+    'security-posture',
+    'public-exposure',
+    'governance',
+    'compliance',
+    'service-retirement',
+    'data-protection',
+    'health',
+    'performance',
+    'scaling',
+    'operations',
+    'monitoring',
+    'topology',
+];
+export const ENVIRONMENT_SEVERITIES_V1 = ['critical', 'high', 'medium', 'low', 'informational', 'unknown'];
+export const ENVIRONMENT_IMPACTS_V1 = ['high', 'medium', 'low', 'unknown'];
+export const ENVIRONMENT_EFFORTS_V1 = ['high', 'medium', 'low', 'unknown'];

package/dist/esm/environment/index.js

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './references.js';
+export * from './validation.js';
+export * from './canonicalization.js';
+export * from './tenant.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,230 @@
+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.length === 2 && parsed[0] === 'azure-tenant')) &&
+            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 };
+};
+/**
+ * Derives the canonical Azure resource type from a canonical ARM resource ID.
+ * Resource names are consumed structurally, so a resource named `providers`
+ * cannot be mistaken for an extension-resource provider boundary.
+ */
+export const deriveEnvironmentAzureResourceTypeV1 = (canonicalAzureResourceId) => {
+    if (!isCanonicalAzureResourceId(canonicalAzureResourceId))
+        return null;
+    const segments = canonicalAzureResourceId.toLowerCase().split('/').filter(Boolean);
+    const firstProviderIndex = segments.indexOf('providers');
+    if (firstProviderIndex < 0)
+        return null;
+    let providerIndex = firstProviderIndex;
+    let namespace = segments[providerIndex + 1];
+    let typeSegments = [];
+    let index = providerIndex + 2;
+    while (namespace && index < segments.length) {
+        const typeOrProviderMarker = segments[index];
+        if (!typeOrProviderMarker)
+            return null;
+        if (typeOrProviderMarker === 'providers') {
+            providerIndex = index;
+            namespace = segments[providerIndex + 1];
+            typeSegments = [];
+            index = providerIndex + 2;
+            continue;
+        }
+        typeSegments.push(typeOrProviderMarker);
+        if (segments[index + 1] === undefined)
+            return null;
+        index += 2;
+    }
+    if (!namespace || typeSegments.length === 0)
+        return null;
+    const resourceType = `${namespace}/${typeSegments.join('/')}`;
+    return [...resourceType].length <= ENVIRONMENT_CONTRACT_LIMITS_V1.safeLabelScalars ? resourceType : null;
+};
+/** 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;