@bleedingdev/modern-js-surface-resolution 0.0.0 → 3.9.0-ultramodern.6

package/dist/esm/surface-resolution/validation.mjs

@@ -0,0 +1,155 @@
+import { formatSurfaceRef } from "./surface-ref.mjs";
+const SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+function createDiscoveryError(code, ref, message, details) {
+    const refString = 'string' == typeof ref ? ref : formatSurfaceRef(ref);
+    return void 0 === details ? {
+        code,
+        ref: refString,
+        message
+    } : {
+        code,
+        ref: refString,
+        message,
+        details
+    };
+}
+function isNonEmptyString(value) {
+    return 'string' == typeof value && value.length > 0;
+}
+function isValidUnitId(unitId) {
+    return unitId.split('/').every((segment)=>SEGMENT_PATTERN.test(segment));
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value);
+}
+const COMPATIBILITY_STATUSES = [
+    'compatible',
+    'incompatible',
+    'degraded'
+];
+const SURFACE_KINDS = [
+    'component',
+    'route',
+    'api',
+    'backend'
+];
+const LOCATION_PLATFORMS = [
+    'browser-mf-manifest',
+    'node-mf-manifest',
+    'http-api',
+    'cloudflare-service-binding'
+];
+const LOCATION_REQUIRED_FIELDS = {
+    'browser-mf-manifest': [
+        'manifestUrl'
+    ],
+    'node-mf-manifest': [
+        'manifestRef'
+    ],
+    'http-api': [
+        'baseUrl',
+        'prefix'
+    ],
+    'cloudflare-service-binding': [
+        'serviceBinding'
+    ]
+};
+function validateLocation(location, path, seenPlatforms, push) {
+    if (!isRecord(location)) return void push(path, 'must be an object');
+    const platform = location.platform;
+    if ('string' != typeof platform || !LOCATION_PLATFORMS.includes(platform)) return void push(`${path}.platform`, `must be one of ${LOCATION_PLATFORMS.join(', ')}`);
+    if (seenPlatforms.has(platform)) push(`${path}.platform`, `duplicate platform ${platform} within one surface`);
+    seenPlatforms.add(platform);
+    for (const field of LOCATION_REQUIRED_FIELDS[platform] ?? [])if (!isNonEmptyString(location[field])) push(`${path}.${field}`, 'must be a non-empty string');
+    if ('cloudflare-service-binding' === platform && void 0 !== location.dispatchNamespace && !isNonEmptyString(location.dispatchNamespace)) push(`${path}.dispatchNamespace`, 'must be a non-empty string when present');
+}
+function validateSurface(surface, path, seenSurfaceIds, push) {
+    if (!isRecord(surface)) return void push(path, 'must be an object');
+    if (isNonEmptyString(surface.surfaceId)) if (SEGMENT_PATTERN.test(surface.surfaceId)) if (seenSurfaceIds.has(surface.surfaceId)) push(`${path}.surfaceId`, 'must be unique within the record');
+    else seenSurfaceIds.add(surface.surfaceId);
+    else push(`${path}.surfaceId`, 'must match the SurfaceRef SurfaceId grammar');
+    else push(`${path}.surfaceId`, 'must be a non-empty string');
+    if ('string' != typeof surface.kind || !SURFACE_KINDS.includes(surface.kind)) push(`${path}.kind`, `must be one of ${SURFACE_KINDS.join(', ')}`);
+    if (void 0 !== surface.servedMajor && (!Number.isSafeInteger(surface.servedMajor) || surface.servedMajor < 1)) push(`${path}.servedMajor`, 'must be a positive safe integer when present');
+    if (!Array.isArray(surface.locations)) return void push(`${path}.locations`, 'must be an array of locations');
+    if (0 === surface.locations.length) push(`${path}.locations`, 'must contain at least one location (no partial records)');
+    const seenPlatforms = new Set();
+    surface.locations.forEach((location, locationIndex)=>{
+        validateLocation(location, `${path}.locations[${locationIndex}]`, seenPlatforms, push);
+    });
+}
+function validateResolvedDeliveryUnit(unit) {
+    const issues = [];
+    const push = (path, message)=>{
+        issues.push({
+            path,
+            message
+        });
+    };
+    if (!isRecord(unit)) {
+        push('', 'must be an object');
+        return {
+            ok: false,
+            issues
+        };
+    }
+    const raw = unit;
+    if (isNonEmptyString(raw.unitId)) {
+        if (!isValidUnitId(raw.unitId)) push('unitId', 'must match the SurfaceRef UnitId grammar');
+    } else push('unitId', 'must be a non-empty string');
+    if (!isNonEmptyString(raw.buildMarker)) push('buildMarker', 'must be a non-empty string');
+    if (!isNonEmptyString(raw.sourceRevision)) push('sourceRevision', 'must be a non-empty string');
+    if (!isNonEmptyString(raw.baselineCohortId)) push('baselineCohortId', 'must be a non-empty string');
+    const compatibility = raw.compatibility;
+    if (isRecord(compatibility)) {
+        if ('string' != typeof compatibility.status || !COMPATIBILITY_STATUSES.includes(compatibility.status)) push('compatibility.status', `must be one of ${COMPATIBILITY_STATUSES.join(', ')}`);
+        if (compatibility.baselineCohortId !== raw.baselineCohortId) push('compatibility.baselineCohortId', 'must equal the record-level baselineCohortId (one verdict per record)');
+        if (void 0 !== compatibility.reason && !isNonEmptyString(compatibility.reason)) push('compatibility.reason', 'must be a non-empty string when present');
+    } else push('compatibility', 'must be an object');
+    if (!Array.isArray(raw.surfaces)) {
+        push('surfaces', 'must be an array of surfaces');
+        return {
+            ok: false,
+            issues
+        };
+    }
+    if (0 === raw.surfaces.length) push('surfaces', 'must contain at least one surface');
+    const seenSurfaceIds = new Set();
+    raw.surfaces.forEach((surface, surfaceIndex)=>{
+        validateSurface(surface, `surfaces[${surfaceIndex}]`, seenSurfaceIds, push);
+    });
+    return {
+        ok: 0 === issues.length,
+        issues
+    };
+}
+function selectResolvedSurface(unit, ref) {
+    if (unit.unitId !== ref.unitId) return {
+        ok: false,
+        error: createDiscoveryError('unknown-unit', ref, `Resolved record is for unit ${unit.unitId}, not ${ref.unitId}.`, {
+            recordUnitId: unit.unitId
+        })
+    };
+    const surface = unit.surfaces.find((candidate)=>candidate.surfaceId === ref.surfaceId);
+    if (void 0 === surface) return {
+        ok: false,
+        error: createDiscoveryError('unknown-surface', ref, `Unit ${unit.unitId} (buildMarker ${unit.buildMarker}) does not publish surface ${ref.surfaceId}.`, {
+            availableSurfaces: unit.surfaces.map((entry)=>entry.surfaceId)
+        })
+    };
+    return {
+        ok: true,
+        surface
+    };
+}
+function matchDeliveryUnitIdentity(expected, unit, ref) {
+    if (expected.unitId === unit.unitId && expected.buildMarker === unit.buildMarker) return;
+    return createDiscoveryError('identity-mismatch', ref, `Delivery-unit identity mismatch: expected ${expected.unitId}@${expected.buildMarker}, resolved ${unit.unitId}@${unit.buildMarker}.`, {
+        expected,
+        resolved: {
+            unitId: unit.unitId,
+            buildMarker: unit.buildMarker
+        }
+    });
+}
+export { createDiscoveryError, matchDeliveryUnitIdentity, selectResolvedSurface, validateResolvedDeliveryUnit };

package/dist/esm-node/surface-resolution/env-static-provider.mjs

@@ -0,0 +1,275 @@
+import "node:module";
+import { formatSurfaceRef } from "./surface-ref.mjs";
+import { createDiscoveryError, validateResolvedDeliveryUnit } from "./validation.mjs";
+const DEFAULT_LOCAL_ENVIRONMENTS = [
+    'development',
+    'local'
+];
+const ENV_STATIC_PROVIDER_NAME = 'env-static';
+function trimTrailingSlashes(value) {
+    return value.replace(/\/+$/u, '');
+}
+function envValue(env, name) {
+    const value = env[name]?.trim();
+    return void 0 !== value && value.length > 0 ? value : void 0;
+}
+function stripMfNamePrefix(value, mfName) {
+    return value.startsWith(`${mfName}@`) ? value.slice(mfName.length + 1) : value;
+}
+function createEnvContext(env, allowLocalFallback) {
+    return {
+        env,
+        allowLocalFallback,
+        cloudflareDeployEnabled: 'cloudflare' === env.MODERNJS_DEPLOY,
+        workersDevSubdomain: envValue(env, 'ULTRAMODERN_CLOUDFLARE_WORKERS_DEV_SUBDOMAIN'),
+        requireCloudflarePublicUrls: 'true' === env.ULTRAMODERN_CLOUDFLARE_REQUIRE_PUBLIC_URLS
+    };
+}
+function resolveBaseUrl(context, unit) {
+    const publicUrlEnv = `ULTRAMODERN_PUBLIC_URL_${unit.envSegment}`;
+    const configuredPublicUrl = envValue(context.env, publicUrlEnv);
+    if (void 0 !== configuredPublicUrl) return {
+        ok: true,
+        baseUrl: trimTrailingSlashes(configuredPublicUrl)
+    };
+    if (context.cloudflareDeployEnabled && void 0 !== context.workersDevSubdomain && void 0 !== unit.workerName) return {
+        ok: true,
+        baseUrl: `https://${unit.workerName}.${context.workersDevSubdomain}.workers.dev`
+    };
+    if (context.cloudflareDeployEnabled && context.requireCloudflarePublicUrls) return {
+        ok: false,
+        reason: `Cloudflare deploy requires ${publicUrlEnv} (or a configured manifest env / ULTRAMODERN_CLOUDFLARE_WORKERS_DEV_SUBDOMAIN with a worker name)`,
+        details: {
+            publicUrlEnv
+        }
+    };
+    if (void 0 !== unit.port && context.allowLocalFallback) return {
+        ok: true,
+        baseUrl: `http://localhost:${unit.port}`
+    };
+    if (void 0 !== unit.port) return {
+        ok: false,
+        reason: `No base URL available: set ${publicUrlEnv} (localhost fallback is disabled outside designated local environments)`,
+        details: {
+            publicUrlEnv
+        }
+    };
+    return {
+        ok: false,
+        reason: `No base URL available: set ${publicUrlEnv} or configure a localhost port`,
+        details: {
+            publicUrlEnv
+        }
+    };
+}
+function resolveBrowserMfManifest(context, unit) {
+    const manifestEnv = `VERTICAL_${unit.envSegment}_MF_MANIFEST`;
+    const configuredManifest = envValue(context.env, manifestEnv);
+    if (void 0 !== configuredManifest) return {
+        ok: true,
+        location: {
+            platform: 'browser-mf-manifest',
+            manifestUrl: stripMfNamePrefix(configuredManifest, unit.mfName)
+        }
+    };
+    const base = resolveBaseUrl(context, unit);
+    if (!base.ok) return {
+        ok: false,
+        reason: `browser-mf-manifest unavailable (${manifestEnv} unset; ${base.reason})`,
+        details: {
+            manifestEnv,
+            ...base.details
+        }
+    };
+    return {
+        ok: true,
+        location: {
+            platform: 'browser-mf-manifest',
+            manifestUrl: `${base.baseUrl}/mf-manifest.json`
+        }
+    };
+}
+function resolveNodeMfManifest(context, unit) {
+    const manifestEnv = `VERTICAL_${unit.envSegment}_BACKEND_MF_MANIFEST`;
+    const configuredManifest = envValue(context.env, manifestEnv);
+    if (void 0 !== configuredManifest) return {
+        ok: true,
+        location: {
+            platform: 'node-mf-manifest',
+            manifestRef: configuredManifest
+        }
+    };
+    if (void 0 !== unit.port && context.allowLocalFallback) return {
+        ok: true,
+        location: {
+            platform: 'node-mf-manifest',
+            manifestRef: `http://localhost:${unit.port}/backend-mf-manifest.json`
+        }
+    };
+    if (void 0 !== unit.port) return {
+        ok: false,
+        reason: `node-mf-manifest unavailable: set ${manifestEnv} (localhost fallback is disabled outside designated local environments)`,
+        details: {
+            manifestEnv
+        }
+    };
+    return {
+        ok: false,
+        reason: `node-mf-manifest unavailable: set ${manifestEnv} or configure a localhost port`,
+        details: {
+            manifestEnv
+        }
+    };
+}
+function resolveHttpApi(context, unit, config) {
+    const base = resolveBaseUrl(context, unit);
+    if (!base.ok) return {
+        ok: false,
+        reason: `http-api unavailable (${base.reason})`,
+        details: base.details
+    };
+    return {
+        ok: true,
+        location: {
+            platform: 'http-api',
+            baseUrl: base.baseUrl,
+            prefix: config.prefix
+        }
+    };
+}
+function resolveCloudflareServiceBinding(config) {
+    if (0 === config.serviceBinding.length) return {
+        ok: false,
+        reason: 'cloudflare-service-binding unavailable: empty serviceBinding'
+    };
+    return {
+        ok: true,
+        location: {
+            platform: 'cloudflare-service-binding',
+            serviceBinding: config.serviceBinding,
+            ...void 0 === config.dispatchNamespace ? {} : {
+                dispatchNamespace: config.dispatchNamespace
+            }
+        }
+    };
+}
+function resolveSurfaceLocations(context, unit, surface) {
+    const outcomes = [];
+    if (surface.platforms.browserMfManifest) outcomes.push(resolveBrowserMfManifest(context, unit));
+    if (surface.platforms.nodeMfManifest) outcomes.push(resolveNodeMfManifest(context, unit));
+    if (void 0 !== surface.platforms.httpApi) outcomes.push(resolveHttpApi(context, unit, surface.platforms.httpApi));
+    if (void 0 !== surface.platforms.cloudflareServiceBinding) outcomes.push(resolveCloudflareServiceBinding(surface.platforms.cloudflareServiceBinding));
+    const failure = outcomes.find((outcome)=>!outcome.ok);
+    if (void 0 !== failure && !failure.ok) return {
+        ok: false,
+        reason: `surface ${surface.surfaceId}: ${failure.reason}`,
+        details: failure.details
+    };
+    const locations = outcomes.flatMap((outcome)=>outcome.ok ? [
+            outcome.location
+        ] : []);
+    if (0 === locations.length) return {
+        ok: false,
+        reason: `surface ${surface.surfaceId} declares no platform locations`
+    };
+    return {
+        ok: true,
+        surface: {
+            surfaceId: surface.surfaceId,
+            kind: surface.kind,
+            locations
+        }
+    };
+}
+function createEnvStaticSurfaceResolutionProvider(options) {
+    const env = options.env ?? {};
+    const localEnvironments = new Set(options.localEnvironments ?? DEFAULT_LOCAL_ENVIRONMENTS);
+    const identityVerification = options.identityVerification ?? 'static-trust';
+    const unitsById = new Map(options.units.map((unit)=>[
+            unit.unitId,
+            unit
+        ]));
+    return {
+        name: ENV_STATIC_PROVIDER_NAME,
+        resolve (ref, environment) {
+            const refString = formatSurfaceRef(ref);
+            const unit = unitsById.get(ref.unitId);
+            if (void 0 === unit) return {
+                ok: false,
+                error: createDiscoveryError('unknown-unit', refString, `No statically configured delivery unit ${ref.unitId}.`, {
+                    environment,
+                    knownUnits: [
+                        ...unitsById.keys()
+                    ]
+                })
+            };
+            if (!unit.surfaces.some((surface)=>surface.surfaceId === ref.surfaceId)) return {
+                ok: false,
+                error: createDiscoveryError('unknown-surface', refString, `Unit ${unit.unitId} does not declare surface ${ref.surfaceId}.`, {
+                    environment,
+                    availableSurfaces: unit.surfaces.map((surface)=>surface.surfaceId)
+                })
+            };
+            let effectiveUnit = unit;
+            if (void 0 !== ref.major) {
+                const majorConfig = (unit.majors ?? []).find((candidate)=>candidate.major === ref.major);
+                if (void 0 === majorConfig) return {
+                    ok: false,
+                    error: createDiscoveryError('major-not-published', refString, `Unit ${unit.unitId} has no materialization for external major v${ref.major}.`, {
+                        environment,
+                        publishedMajors: (unit.majors ?? []).map((candidate)=>candidate.major)
+                    })
+                };
+                effectiveUnit = {
+                    ...unit,
+                    envSegment: majorConfig.envSegment ?? `${unit.envSegment}_V${majorConfig.major}`,
+                    port: majorConfig.port,
+                    workerName: majorConfig.workerName
+                };
+            }
+            const context = createEnvContext(env, localEnvironments.has(environment));
+            const surfaces = [];
+            for (const surfaceConfig of unit.surfaces){
+                const resolved = resolveSurfaceLocations(context, effectiveUnit, surfaceConfig);
+                if (!resolved.ok) return {
+                    ok: false,
+                    error: createDiscoveryError('provider-unavailable', refString, `env-static provider cannot assemble a complete record for ${unit.unitId}: ${resolved.reason}.`, {
+                        environment,
+                        ...resolved.details
+                    })
+                };
+                surfaces.push(void 0 === ref.major ? resolved.surface : {
+                    ...resolved.surface,
+                    servedMajor: ref.major
+                });
+            }
+            const record = {
+                unitId: unit.unitId,
+                buildMarker: unit.buildMarker,
+                sourceRevision: unit.sourceRevision,
+                baselineCohortId: unit.baselineCohortId,
+                surfaces,
+                compatibility: {
+                    status: 'compatible',
+                    baselineCohortId: unit.baselineCohortId,
+                    ...'static-trust' === identityVerification ? {
+                        reason: 'static-identity-unverified'
+                    } : {}
+                }
+            };
+            const validation = validateResolvedDeliveryUnit(record);
+            if (!validation.ok) return {
+                ok: false,
+                error: createDiscoveryError('provider-unavailable', refString, `env-static provider assembled an invalid record for ${unit.unitId}.`, {
+                    environment,
+                    issues: validation.issues
+                })
+            };
+            return {
+                ok: true,
+                unit: record
+            };
+        }
+    };
+}
+export { DEFAULT_LOCAL_ENVIRONMENTS, ENV_STATIC_PROVIDER_NAME, createEnvStaticSurfaceResolutionProvider };

package/dist/esm-node/surface-resolution/index.mjs

@@ -0,0 +1,4 @@
+import "node:module";
+export { DEFAULT_LOCAL_ENVIRONMENTS, ENV_STATIC_PROVIDER_NAME, createEnvStaticSurfaceResolutionProvider } from "./env-static-provider.mjs";
+export { formatSurfaceRef, parseSurfaceRef, validateSurfaceRef } from "./surface-ref.mjs";
+export { createDiscoveryError, matchDeliveryUnitIdentity, selectResolvedSurface, validateResolvedDeliveryUnit } from "./validation.mjs";

package/dist/esm-node/surface-resolution/surface-ref.mjs

@@ -0,0 +1,89 @@
+import "node:module";
+const SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+const MAJOR_PATTERN = /^v[1-9][0-9]*$/;
+function parseSurfaceRef(input) {
+    if ('' === input) return {
+        ok: false,
+        error: {
+            code: 'empty'
+        }
+    };
+    const hashCount = countChar(input, '#');
+    if (0 === hashCount) return {
+        ok: false,
+        error: {
+            code: 'missing-surface-separator'
+        }
+    };
+    if (hashCount > 1) return {
+        ok: false,
+        error: {
+            code: 'multiple-surface-separators'
+        }
+    };
+    const hashIndex = input.indexOf('#');
+    const unitPart = input.slice(0, hashIndex);
+    const rest = input.slice(hashIndex + 1);
+    const atIndex = rest.indexOf('@');
+    const surfaceId = -1 === atIndex ? rest : rest.slice(0, atIndex);
+    const ref = {
+        unitId: unitPart,
+        surfaceId
+    };
+    if (-1 !== atIndex) {
+        const majorPart = rest.slice(atIndex + 1);
+        if ('' === majorPart) return {
+            ok: false,
+            error: {
+                code: 'empty-major'
+            }
+        };
+        if (!MAJOR_PATTERN.test(majorPart)) return {
+            ok: false,
+            error: {
+                code: 'invalid-major',
+                value: majorPart
+            }
+        };
+        ref.major = Number(majorPart.slice(1));
+    }
+    const error = validateSurfaceRef(ref);
+    return void 0 === error ? {
+        ok: true,
+        ref
+    } : {
+        ok: false,
+        error
+    };
+}
+function formatSurfaceRef(ref) {
+    const error = validateSurfaceRef(ref);
+    if (void 0 !== error) throw new TypeError(`Cannot format invalid SurfaceRef: ${error.code}.`);
+    const base = `${ref.unitId}#${ref.surfaceId}`;
+    return void 0 === ref.major ? base : `${base}@v${ref.major}`;
+}
+function validateSurfaceRef(ref) {
+    if ('' === ref.unitId) return {
+        code: 'empty-unit-id'
+    };
+    for (const segment of ref.unitId.split('/'))if (!SEGMENT_PATTERN.test(segment)) return {
+        code: 'invalid-unit-id',
+        segment
+    };
+    if ('' === ref.surfaceId) return {
+        code: 'empty-surface-id'
+    };
+    if (!SEGMENT_PATTERN.test(ref.surfaceId)) return {
+        code: 'invalid-surface-id'
+    };
+    if (void 0 !== ref.major && (!Number.isSafeInteger(ref.major) || ref.major < 1)) return {
+        code: 'invalid-major',
+        value: String(ref.major)
+    };
+}
+function countChar(input, char) {
+    let count = 0;
+    for (const current of input)if (current === char) count += 1;
+    return count;
+}
+export { formatSurfaceRef, parseSurfaceRef, validateSurfaceRef };

package/dist/esm-node/surface-resolution/types.mjs

@@ -0,0 +1 @@
+import "node:module";

package/dist/esm-node/surface-resolution/validation.mjs

@@ -0,0 +1,156 @@
+import "node:module";
+import { formatSurfaceRef } from "./surface-ref.mjs";
+const SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+function createDiscoveryError(code, ref, message, details) {
+    const refString = 'string' == typeof ref ? ref : formatSurfaceRef(ref);
+    return void 0 === details ? {
+        code,
+        ref: refString,
+        message
+    } : {
+        code,
+        ref: refString,
+        message,
+        details
+    };
+}
+function isNonEmptyString(value) {
+    return 'string' == typeof value && value.length > 0;
+}
+function isValidUnitId(unitId) {
+    return unitId.split('/').every((segment)=>SEGMENT_PATTERN.test(segment));
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value);
+}
+const COMPATIBILITY_STATUSES = [
+    'compatible',
+    'incompatible',
+    'degraded'
+];
+const SURFACE_KINDS = [
+    'component',
+    'route',
+    'api',
+    'backend'
+];
+const LOCATION_PLATFORMS = [
+    'browser-mf-manifest',
+    'node-mf-manifest',
+    'http-api',
+    'cloudflare-service-binding'
+];
+const LOCATION_REQUIRED_FIELDS = {
+    'browser-mf-manifest': [
+        'manifestUrl'
+    ],
+    'node-mf-manifest': [
+        'manifestRef'
+    ],
+    'http-api': [
+        'baseUrl',
+        'prefix'
+    ],
+    'cloudflare-service-binding': [
+        'serviceBinding'
+    ]
+};
+function validateLocation(location, path, seenPlatforms, push) {
+    if (!isRecord(location)) return void push(path, 'must be an object');
+    const platform = location.platform;
+    if ('string' != typeof platform || !LOCATION_PLATFORMS.includes(platform)) return void push(`${path}.platform`, `must be one of ${LOCATION_PLATFORMS.join(', ')}`);
+    if (seenPlatforms.has(platform)) push(`${path}.platform`, `duplicate platform ${platform} within one surface`);
+    seenPlatforms.add(platform);
+    for (const field of LOCATION_REQUIRED_FIELDS[platform] ?? [])if (!isNonEmptyString(location[field])) push(`${path}.${field}`, 'must be a non-empty string');
+    if ('cloudflare-service-binding' === platform && void 0 !== location.dispatchNamespace && !isNonEmptyString(location.dispatchNamespace)) push(`${path}.dispatchNamespace`, 'must be a non-empty string when present');
+}
+function validateSurface(surface, path, seenSurfaceIds, push) {
+    if (!isRecord(surface)) return void push(path, 'must be an object');
+    if (isNonEmptyString(surface.surfaceId)) if (SEGMENT_PATTERN.test(surface.surfaceId)) if (seenSurfaceIds.has(surface.surfaceId)) push(`${path}.surfaceId`, 'must be unique within the record');
+    else seenSurfaceIds.add(surface.surfaceId);
+    else push(`${path}.surfaceId`, 'must match the SurfaceRef SurfaceId grammar');
+    else push(`${path}.surfaceId`, 'must be a non-empty string');
+    if ('string' != typeof surface.kind || !SURFACE_KINDS.includes(surface.kind)) push(`${path}.kind`, `must be one of ${SURFACE_KINDS.join(', ')}`);
+    if (void 0 !== surface.servedMajor && (!Number.isSafeInteger(surface.servedMajor) || surface.servedMajor < 1)) push(`${path}.servedMajor`, 'must be a positive safe integer when present');
+    if (!Array.isArray(surface.locations)) return void push(`${path}.locations`, 'must be an array of locations');
+    if (0 === surface.locations.length) push(`${path}.locations`, 'must contain at least one location (no partial records)');
+    const seenPlatforms = new Set();
+    surface.locations.forEach((location, locationIndex)=>{
+        validateLocation(location, `${path}.locations[${locationIndex}]`, seenPlatforms, push);
+    });
+}
+function validateResolvedDeliveryUnit(unit) {
+    const issues = [];
+    const push = (path, message)=>{
+        issues.push({
+            path,
+            message
+        });
+    };
+    if (!isRecord(unit)) {
+        push('', 'must be an object');
+        return {
+            ok: false,
+            issues
+        };
+    }
+    const raw = unit;
+    if (isNonEmptyString(raw.unitId)) {
+        if (!isValidUnitId(raw.unitId)) push('unitId', 'must match the SurfaceRef UnitId grammar');
+    } else push('unitId', 'must be a non-empty string');
+    if (!isNonEmptyString(raw.buildMarker)) push('buildMarker', 'must be a non-empty string');
+    if (!isNonEmptyString(raw.sourceRevision)) push('sourceRevision', 'must be a non-empty string');
+    if (!isNonEmptyString(raw.baselineCohortId)) push('baselineCohortId', 'must be a non-empty string');
+    const compatibility = raw.compatibility;
+    if (isRecord(compatibility)) {
+        if ('string' != typeof compatibility.status || !COMPATIBILITY_STATUSES.includes(compatibility.status)) push('compatibility.status', `must be one of ${COMPATIBILITY_STATUSES.join(', ')}`);
+        if (compatibility.baselineCohortId !== raw.baselineCohortId) push('compatibility.baselineCohortId', 'must equal the record-level baselineCohortId (one verdict per record)');
+        if (void 0 !== compatibility.reason && !isNonEmptyString(compatibility.reason)) push('compatibility.reason', 'must be a non-empty string when present');
+    } else push('compatibility', 'must be an object');
+    if (!Array.isArray(raw.surfaces)) {
+        push('surfaces', 'must be an array of surfaces');
+        return {
+            ok: false,
+            issues
+        };
+    }
+    if (0 === raw.surfaces.length) push('surfaces', 'must contain at least one surface');
+    const seenSurfaceIds = new Set();
+    raw.surfaces.forEach((surface, surfaceIndex)=>{
+        validateSurface(surface, `surfaces[${surfaceIndex}]`, seenSurfaceIds, push);
+    });
+    return {
+        ok: 0 === issues.length,
+        issues
+    };
+}
+function selectResolvedSurface(unit, ref) {
+    if (unit.unitId !== ref.unitId) return {
+        ok: false,
+        error: createDiscoveryError('unknown-unit', ref, `Resolved record is for unit ${unit.unitId}, not ${ref.unitId}.`, {
+            recordUnitId: unit.unitId
+        })
+    };
+    const surface = unit.surfaces.find((candidate)=>candidate.surfaceId === ref.surfaceId);
+    if (void 0 === surface) return {
+        ok: false,
+        error: createDiscoveryError('unknown-surface', ref, `Unit ${unit.unitId} (buildMarker ${unit.buildMarker}) does not publish surface ${ref.surfaceId}.`, {
+            availableSurfaces: unit.surfaces.map((entry)=>entry.surfaceId)
+        })
+    };
+    return {
+        ok: true,
+        surface
+    };
+}
+function matchDeliveryUnitIdentity(expected, unit, ref) {
+    if (expected.unitId === unit.unitId && expected.buildMarker === unit.buildMarker) return;
+    return createDiscoveryError('identity-mismatch', ref, `Delivery-unit identity mismatch: expected ${expected.unitId}@${expected.buildMarker}, resolved ${unit.unitId}@${unit.buildMarker}.`, {
+        expected,
+        resolved: {
+            unitId: unit.unitId,
+            buildMarker: unit.buildMarker
+        }
+    });
+}
+export { createDiscoveryError, matchDeliveryUnitIdentity, selectResolvedSurface, validateResolvedDeliveryUnit };