@bleedingdev/modern-js-utils 3.5.0-ultramodern.1 → 3.5.0-ultramodern.100

package/dist/esm-node/universal/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/universal/surface-resolution/types.mjs

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

package/dist/esm-node/universal/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 };

package/dist/types/import.d.ts

@@ -1,5 +1,5 @@
 declare const lazy: (moduleName: string, getRequireFn: () => (id: string) => unknown) => any;
 export { lazy as lazyImport };
 export declare const Import: {
-    lazy: (moduleName: string, getRequireFn: () => (id: string) => unknown) => any;
+    lazy: typeof lazy;
 };

package/dist/types/universal/backend-federation-contract/build-artifact.d.ts

@@ -0,0 +1,9 @@
+import type { BackendFederationContractValidationResult, DeliveryUnitRecord, UltramodernBuildArtifact } from './types';
+export declare const createUltramodernBuildArtifact: (record: DeliveryUnitRecord) => UltramodernBuildArtifact;
+export declare const validateUltramodernBuildArtifact: (value: unknown, path?: string) => BackendFederationContractValidationResult;
+export declare const isUltramodernBuildArtifact: (value: unknown) => value is UltramodernBuildArtifact;
+export declare const stampUltramodernBuildArtifactIdentity: (artifact: UltramodernBuildArtifact, identity: {
+    buildMarker: string;
+    sourceRevision: string;
+}) => UltramodernBuildArtifact;
+export declare const stampUltramodernBuildArtifactSourceRevision: (artifact: UltramodernBuildArtifact, sourceRevision: string) => UltramodernBuildArtifact;

package/dist/types/universal/backend-federation-contract/constants.d.ts

@@ -0,0 +1,14 @@
+export declare const BACKEND_FEDERATION_EFFECT_EXPOSE = "./effect-api";
+export declare const BACKEND_FEDERATION_MANIFEST_FILE = "backend-mf-manifest.json";
+export declare const BACKEND_FEDERATION_REMOTE_ENTRY_FILE = "backendRemoteEntry.cjs";
+export declare const BACKEND_FEDERATION_CONTRACT_VERSION = "microvertical-server-effect-v1";
+export declare const BACKEND_FEDERATION_NODE_ADAPTER_VERSION = "backend-mf-effect-v1";
+export declare const DELIVERY_UNIT_SCHEMA_VERSION = 1;
+export declare const DELIVERY_UNIT_KIND = "microvertical-delivery-unit";
+export declare const DELIVERY_UNIT_DEPLOY_PROFILE = "cloudflare-ssr-mf-effect-v1";
+export declare const DELIVERY_UNIT_IDENTITY_FIELDS: readonly ['unitId', 'buildMarker', 'sourceRevision'];
+export type DeliveryUnitIdentityField = (typeof DELIVERY_UNIT_IDENTITY_FIELDS)[number];
+export declare const ULTRAMODERN_BUILD_ARTIFACT_FILE = "ultramodern-build.json";
+export declare const ULTRAMODERN_BUILD_ARTIFACT_PATH = "shared/ultramodern-build.json";
+export declare const ULTRAMODERN_BUILD_MODULE_FILE = "ultramodern-build.ts";
+export declare const ULTRAMODERN_BUILD_MODULE_PATH = "shared/ultramodern-build.ts";

package/dist/types/universal/backend-federation-contract/delivery-unit.d.ts

@@ -0,0 +1,9 @@
+import type { DeliveryUnitIdentityField } from './constants';
+import type { BackendFederationContractValidationError, BackendFederationContractValidationResult, DeliveryUnitContractBlock, DeliveryUnitIdentity, DeliveryUnitRecord, ValidateDeliveryUnitIdentityOptions } from './types';
+export declare const deliveryUnitIdentityFieldValue: (value: unknown, field: DeliveryUnitIdentityField, options?: Pick<ValidateDeliveryUnitIdentityOptions, 'allowBuildAlias'>) => string | undefined;
+export declare const validateDeliveryUnitIdentity: (value: unknown, options?: ValidateDeliveryUnitIdentityOptions) => BackendFederationContractValidationResult;
+export declare const validateDeliveryUnitContractBlock: (value: unknown, options?: ValidateDeliveryUnitIdentityOptions) => BackendFederationContractValidationResult;
+export declare const validateDeliveryUnitRecord: (value: unknown, options?: ValidateDeliveryUnitIdentityOptions) => BackendFederationContractValidationResult;
+export declare const validateDeliveryUnitBoundaryIdentity: (value: unknown, path: string) => BackendFederationContractValidationError[];
+export declare const deliveryUnitContractBlock: (record: DeliveryUnitRecord) => DeliveryUnitContractBlock;
+export declare const toDeliveryUnitIdentity: (value: unknown) => DeliveryUnitIdentity | undefined;

package/dist/types/universal/backend-federation-contract/index.d.ts

@@ -0,0 +1,7 @@
+export { createUltramodernBuildArtifact, isUltramodernBuildArtifact, stampUltramodernBuildArtifactIdentity, stampUltramodernBuildArtifactSourceRevision, validateUltramodernBuildArtifact, } from './build-artifact';
+export type { DeliveryUnitIdentityField } from './constants';
+export { BACKEND_FEDERATION_CONTRACT_VERSION, BACKEND_FEDERATION_EFFECT_EXPOSE, BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_NODE_ADAPTER_VERSION, BACKEND_FEDERATION_REMOTE_ENTRY_FILE, DELIVERY_UNIT_DEPLOY_PROFILE, DELIVERY_UNIT_IDENTITY_FIELDS, DELIVERY_UNIT_KIND, DELIVERY_UNIT_SCHEMA_VERSION, ULTRAMODERN_BUILD_ARTIFACT_FILE, ULTRAMODERN_BUILD_ARTIFACT_PATH, ULTRAMODERN_BUILD_MODULE_FILE, ULTRAMODERN_BUILD_MODULE_PATH, } from './constants';
+export { deliveryUnitContractBlock, deliveryUnitIdentityFieldValue, toDeliveryUnitIdentity, validateDeliveryUnitContractBlock, validateDeliveryUnitIdentity, validateDeliveryUnitRecord, } from './delivery-unit';
+export { backendFederationExposeNames, backendFederationMetadata, backendFederationVersionBoundary, toBackendFederationExposeNames, validateBackendFederationManifest, validateBackendFederationMetadata, } from './metadata';
+export type { BackendFederationContractValidationError, BackendFederationContractValidationResult, DeliveryUnitContractBlock, DeliveryUnitIdentity, DeliveryUnitRecord, UltramodernBuildArtifact, UltramodernBuildDeliveryUnit, UltramodernBuildSurface, ValidateBackendFederationManifestOptions, ValidateBackendFederationMetadataOptions, ValidateDeliveryUnitIdentityOptions, } from './types';
+export { formatBackendFederationValidationErrors, nonEmptyString, } from './validation-core';

package/dist/types/universal/backend-federation-contract/metadata.d.ts

@@ -0,0 +1,7 @@
+import type { BackendFederationContractValidationResult, ValidateBackendFederationManifestOptions, ValidateBackendFederationMetadataOptions } from './types';
+export declare const toBackendFederationExposeNames: (value: unknown) => string[];
+export declare const backendFederationExposeNames: (value: unknown) => string[];
+export declare const backendFederationMetadata: (value: unknown) => Record<string, unknown> | undefined;
+export declare const backendFederationVersionBoundary: (value: unknown) => Record<string, unknown> | undefined;
+export declare const validateBackendFederationMetadata: (value: unknown, options?: ValidateBackendFederationMetadataOptions) => BackendFederationContractValidationResult;
+export declare const validateBackendFederationManifest: (value: unknown, options?: ValidateBackendFederationManifestOptions) => BackendFederationContractValidationResult;

package/dist/types/universal/backend-federation-contract/types.d.ts

@@ -0,0 +1,60 @@
+import type { DELIVERY_UNIT_DEPLOY_PROFILE, DELIVERY_UNIT_KIND, DELIVERY_UNIT_SCHEMA_VERSION } from './constants';
+export type DeliveryUnitIdentity = {
+    unitId: string;
+    buildMarker: string;
+    sourceRevision: string;
+};
+export type DeliveryUnitRecord = DeliveryUnitIdentity & {
+    schemaVersion: typeof DELIVERY_UNIT_SCHEMA_VERSION;
+    kind: typeof DELIVERY_UNIT_KIND;
+    appId: string;
+    packageName: string;
+    version: string;
+    deployProfile: typeof DELIVERY_UNIT_DEPLOY_PROFILE;
+};
+export type DeliveryUnitContractBlock = Omit<DeliveryUnitRecord, 'appId' | 'deployProfile'>;
+export type UltramodernBuildDeliveryUnit = DeliveryUnitRecord & {
+    build: string;
+};
+export type UltramodernBuildSurface = (UltramodernBuildDeliveryUnit & {
+    surface: 'ui';
+}) | (UltramodernBuildDeliveryUnit & {
+    surface: 'api';
+});
+export type UltramodernBuildArtifact = {
+    schemaVersion: typeof DELIVERY_UNIT_SCHEMA_VERSION;
+    kind: 'ultramodern-build-artifact';
+    deliveryUnit: UltramodernBuildDeliveryUnit;
+    surfaces: {
+        ui: UltramodernBuildDeliveryUnit & {
+            surface: 'ui';
+        };
+        api: UltramodernBuildDeliveryUnit & {
+            surface: 'api';
+        };
+    };
+};
+export type BackendFederationContractValidationError = {
+    path: string;
+    message: string;
+};
+export type BackendFederationContractValidationResult = {
+    ok: boolean;
+    errors: BackendFederationContractValidationError[];
+};
+export type ValidateDeliveryUnitIdentityOptions = {
+    path?: string;
+    allowBuildAlias?: boolean;
+};
+export type ValidateBackendFederationMetadataOptions = {
+    path?: string;
+    expectedContractVersion?: string | false;
+    expectedNodeAdapterVersion?: string | false;
+    validateDeliveryUnit?: boolean;
+    requireEffectExpose?: boolean;
+    requireEffectRuntime?: boolean;
+    requireVersionFields?: boolean;
+};
+export type ValidateBackendFederationManifestOptions = ValidateBackendFederationMetadataOptions & {
+    requireBackendFederation?: boolean;
+};

package/dist/types/universal/backend-federation-contract/validation-core.d.ts

@@ -0,0 +1,8 @@
+import type { BackendFederationContractValidationError, BackendFederationContractValidationResult } from './types';
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const nonEmptyString: (value: unknown) => string | undefined;
+export declare const validationResult: (errors: BackendFederationContractValidationError[]) => BackendFederationContractValidationResult;
+export declare const addError: (errors: BackendFederationContractValidationError[], path: string, message: string) => void;
+export declare const recordField: (value: Record<string, unknown> | undefined, field: string) => Record<string, unknown> | undefined;
+export declare const formatBackendFederationValidationErrors: (errors: BackendFederationContractValidationError[]) => string;
+export declare const validateVersionField: (errors: BackendFederationContractValidationError[], record: Record<string, unknown>, field: 'contractVersion' | 'nodeAdapterVersion', expected: string | false, path: string, required: boolean) => void;

package/dist/types/universal/index.d.ts

@@ -1 +1,3 @@
+export * from './backend-federation-contract';
 export { cutNameByHyphen } from './path';
+export * from './surface-resolution';

package/dist/types/universal/surface-resolution/env-static-provider.d.ts

@@ -0,0 +1,107 @@
+import type { EnvironmentId, ResolvedSurfaceKind, SurfaceResolutionProvider } from './types';
+export type EnvRecord = Record<string, string | undefined>;
+/** Which platforms a surface publishes, plus their static (non-env) inputs. */
+export type EnvStaticSurfacePlatforms = {
+    /** Publish a `browser-mf-manifest` location (env/public/cloudflare/localhost chain). */
+    browserMfManifest?: boolean;
+    /** Publish a `node-mf-manifest` location (backend manifest env / localhost chain). */
+    nodeMfManifest?: boolean;
+    /** Publish an `http-api` location; the base URL follows the public-URL chain. */
+    httpApi?: {
+        prefix: string;
+    };
+    /** Publish a `cloudflare-service-binding` location (statically provisioned). */
+    cloudflareServiceBinding?: {
+        serviceBinding: string;
+        dispatchNamespace?: string;
+    };
+};
+export type EnvStaticSurfaceConfig = {
+    surfaceId: string;
+    kind: ResolvedSurfaceKind;
+    platforms: EnvStaticSurfacePlatforms;
+};
+/**
+ * Static configuration for one delivery unit. Identity comes from the build
+ * artifact (never from the environment); the environment only overrides
+ * addresses through the documented env-var chains.
+ */
+export type EnvStaticUnitConfig = {
+    unitId: string;
+    buildMarker: string;
+    sourceRevision: string;
+    baselineCohortId: string;
+    /**
+     * Env-var segment, e.g. `CHECKOUT` in `VERTICAL_CHECKOUT_MF_MANIFEST` /
+     * `ULTRAMODERN_PUBLIC_URL_CHECKOUT` (`toEnvSegment(domain ?? id)`).
+     */
+    envSegment: string;
+    /** Module-federation container name (used to strip `mfName@` env prefixes). */
+    mfName: string;
+    /** Localhost dev fallback port. Without it, env values are mandatory. */
+    port?: number;
+    /** Cloudflare worker name for the workers.dev fallback. */
+    workerName?: string;
+    /**
+     * Externally published majors (ADR-0020), each with its own materialization.
+     * A requested `@vN` resolves ONLY through the matching entry; a major that
+     * is not configured here is the typed `major-not-published` error.
+     */
+    majors?: EnvStaticMajorConfig[];
+    surfaces: EnvStaticSurfaceConfig[];
+};
+/**
+ * Per-major materialization (ADR-0020): where the externally published major
+ * `vN` of a unit lives. Address inputs are deliberately NOT inherited from the
+ * unversioned unit — a versioned request must never be answered with
+ * unversioned locations — so each major carries its own env segment (default
+ * `${unit.envSegment}_V${major}`) and, optionally, its own localhost port /
+ * worker name.
+ */
+export type EnvStaticMajorConfig = {
+    major: number;
+    /** Env-var segment for this major. Default: `${unit.envSegment}_V${major}`. */
+    envSegment?: string;
+    /** Localhost dev fallback port for this major (local environments only). */
+    port?: number;
+    /** Cloudflare worker name for this major's workers.dev fallback. */
+    workerName?: string;
+};
+/**
+ * How the provider's stamped identity is to be interpreted. `static-trust`
+ * (the only mode, and the default) means identity is asserted from static
+ * config, not verified against the artifacts; the compatibility verdict then
+ * carries `reason: 'static-identity-unverified'`.
+ */
+export type EnvStaticIdentityVerification = 'static-trust';
+/** Environments in which localhost dev fallbacks are allowed by default. */
+export declare const DEFAULT_LOCAL_ENVIRONMENTS: readonly string[];
+export type EnvStaticProviderOptions = {
+    units: EnvStaticUnitConfig[];
+    /**
+     * Environment record to read from. Universal module: `process.env` is never
+     * read implicitly; pass it explicitly in Node hosts.
+     */
+    env?: EnvRecord;
+    /**
+     * Environments in which localhost dev fallbacks apply. Any environment NOT
+     * listed here fails closed: missing explicit configuration is the typed
+     * `provider-unavailable` error, never a localhost URL.
+     * Default: `['development', 'local']`.
+     */
+    localEnvironments?: EnvironmentId[];
+    /**
+     * Identity-honesty mode (ADR-0019). Default `'static-trust'`: the verdict
+     * is marked `static-identity-unverified` because this provider asserts
+     * identity from static config without verifying the resolved artifacts.
+     */
+    identityVerification?: EnvStaticIdentityVerification;
+};
+export declare const ENV_STATIC_PROVIDER_NAME = "env-static";
+/**
+ * Create the baseline env/static provider. Resolution is all-or-nothing per
+ * RESOLUTION-0001: every declared platform location for every surface of the
+ * unit assembles against the unit's single static identity, or the whole
+ * resolution fails with one typed error.
+ */
+export declare function createEnvStaticSurfaceResolutionProvider(options: EnvStaticProviderOptions): SurfaceResolutionProvider;

package/dist/types/universal/surface-resolution/index.d.ts

@@ -0,0 +1,4 @@
+export { createEnvStaticSurfaceResolutionProvider, DEFAULT_LOCAL_ENVIRONMENTS, ENV_STATIC_PROVIDER_NAME, type EnvRecord, type EnvStaticIdentityVerification, type EnvStaticMajorConfig, type EnvStaticProviderOptions, type EnvStaticSurfaceConfig, type EnvStaticSurfacePlatforms, type EnvStaticUnitConfig, } from './env-static-provider';
+export { formatSurfaceRef, type ParsedSurfaceRef, parseSurfaceRef, type SurfaceRefParseError, type SurfaceRefParseResult, validateSurfaceRef, } from './surface-ref';
+export type { CompatibilityStatus, CompatibilityVerdict, DiscoveryError, DiscoveryErrorCode, DiscoveryResult, EnvironmentId, ResolvedDeliveryUnit, ResolvedSurface, ResolvedSurfaceKind, ResolvedSurfaceLocation, ResolvedSurfaceLocationPlatform, SurfaceResolutionProvider, } from './types';
+export { createDiscoveryError, type ExpectedDeliveryUnitIdentity, matchDeliveryUnitIdentity, type ResolvedDeliveryUnitIssue, type ResolvedDeliveryUnitValidationResult, selectResolvedSurface, validateResolvedDeliveryUnit, } from './validation';

package/dist/types/universal/surface-resolution/surface-ref.d.ts

@@ -0,0 +1,72 @@
+/**
+ * SurfaceRef grammar (MV-G25a).
+ *
+ * Mirrors the EBNF in `packages/toolkit/create/delivery-unit-schema-SPEC.md` §2
+ * exactly:
+ *
+ * ```ebnf
+ * SurfaceRef   = UnitId , "#" , SurfaceId , [ "@" , Major ] ;
+ * UnitId       = Segment , { "/" , Segment } ;
+ * SurfaceId    = Segment ;
+ * Segment      = SegmentChar , { SegmentChar } ;
+ * SegmentChar  = letter | digit | "-" | "_" | "." ;
+ * Major        = "v" , nonzero , { digit } ;
+ * ```
+ *
+ * Canonical form: `unitId#surfaceId` with optional `@vN` external-major suffix
+ * (e.g. `acme/checkout#cart`, `acme/checkout#cart@v2`). Universal module:
+ * dependency-free, runs in any JavaScript environment.
+ */
+/**
+ * Parsed form of a SurfaceRef. Canonical string form is `unitId#surfaceId`
+ * with an optional `@vN` major suffix.
+ */
+export type ParsedSurfaceRef = {
+    unitId: string;
+    surfaceId: string;
+    /** External-major selector. Absent means "the coordinated-zone surface". */
+    major?: number;
+};
+export type SurfaceRefParseError = {
+    code: 'empty';
+} | {
+    code: 'missing-surface-separator';
+} | {
+    code: 'multiple-surface-separators';
+} | {
+    code: 'empty-unit-id';
+} | {
+    code: 'invalid-unit-id';
+    segment: string;
+} | {
+    code: 'empty-surface-id';
+} | {
+    code: 'invalid-surface-id';
+} | {
+    code: 'empty-major';
+} | {
+    code: 'invalid-major';
+    value: string;
+};
+export type SurfaceRefParseResult = {
+    ok: true;
+    ref: ParsedSurfaceRef;
+} | {
+    ok: false;
+    error: SurfaceRefParseError;
+};
+/**
+ * Parse a canonical SurfaceRef string. Total function: every rejection is a
+ * typed {@link SurfaceRefParseError}; never throws.
+ */
+export declare function parseSurfaceRef(input: string): SurfaceRefParseResult;
+/**
+ * Render a {@link ParsedSurfaceRef} back to its canonical string form.
+ *
+ * Direct inputs are checked against the same invariant as parsed references,
+ * so this formatter cannot emit a string that {@link parseSurfaceRef} rejects.
+ * Round-trip: `formatSurfaceRef(parseSurfaceRef(x).ref) === x` for valid `x`.
+ */
+export declare function formatSurfaceRef(ref: ParsedSurfaceRef): string;
+/** The shared semantic invariant for parsed and directly formatted references. */
+export declare function validateSurfaceRef(ref: ParsedSurfaceRef): SurfaceRefParseError | undefined;