@bleedingdev/modern-js-utils 3.9.0-ultramodern.3 → 3.9.0-ultramodern.5

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

@@ -1,156 +0,0 @@
-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/universal/backend-federation-contract/build-artifact.d.ts

@@ -1,9 +0,0 @@
-import type { BackendFederationContractValidationResult, DeliveryUnitRecord, UltramodernBuildArtifact } from './types.js';
-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

@@ -1,14 +0,0 @@
-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

@@ -1,9 +0,0 @@
-import type { DeliveryUnitIdentityField } from './constants.js';
-import type { BackendFederationContractValidationError, BackendFederationContractValidationResult, DeliveryUnitContractBlock, DeliveryUnitIdentity, DeliveryUnitRecord, ValidateDeliveryUnitIdentityOptions } from './types.js';
-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

@@ -1,7 +0,0 @@
-export { createUltramodernBuildArtifact, isUltramodernBuildArtifact, stampUltramodernBuildArtifactIdentity, stampUltramodernBuildArtifactSourceRevision, validateUltramodernBuildArtifact, } from './build-artifact.js';
-export type { DeliveryUnitIdentityField } from './constants.js';
-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.js';
-export { deliveryUnitContractBlock, deliveryUnitIdentityFieldValue, toDeliveryUnitIdentity, validateDeliveryUnitContractBlock, validateDeliveryUnitIdentity, validateDeliveryUnitRecord, } from './delivery-unit.js';
-export { backendFederationExposeNames, backendFederationMetadata, backendFederationVersionBoundary, toBackendFederationExposeNames, validateBackendFederationManifest, validateBackendFederationMetadata, } from './metadata.js';
-export type { BackendFederationContractValidationError, BackendFederationContractValidationResult, DeliveryUnitContractBlock, DeliveryUnitIdentity, DeliveryUnitRecord, UltramodernBuildArtifact, UltramodernBuildDeliveryUnit, UltramodernBuildSurface, ValidateBackendFederationManifestOptions, ValidateBackendFederationMetadataOptions, ValidateDeliveryUnitIdentityOptions, } from './types.js';
-export { formatBackendFederationValidationErrors, nonEmptyString, } from './validation-core.js';

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

@@ -1,7 +0,0 @@
-import type { BackendFederationContractValidationResult, ValidateBackendFederationManifestOptions, ValidateBackendFederationMetadataOptions } from './types.js';
-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

@@ -1,60 +0,0 @@
-import type { DELIVERY_UNIT_DEPLOY_PROFILE, DELIVERY_UNIT_KIND, DELIVERY_UNIT_SCHEMA_VERSION } from './constants.js';
-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

@@ -1,8 +0,0 @@
-import type { BackendFederationContractValidationError, BackendFederationContractValidationResult } from './types.js';
-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/surface-resolution/env-static-provider.d.ts

@@ -1,107 +0,0 @@
-import type { EnvironmentId, ResolvedSurfaceKind, SurfaceResolutionProvider } from './types.js';
-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

@@ -1,4 +0,0 @@
-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.js';
-export { formatSurfaceRef, type ParsedSurfaceRef, parseSurfaceRef, type SurfaceRefParseError, type SurfaceRefParseResult, validateSurfaceRef, } from './surface-ref.js';
-export type { CompatibilityStatus, CompatibilityVerdict, DiscoveryError, DiscoveryErrorCode, DiscoveryResult, EnvironmentId, ResolvedDeliveryUnit, ResolvedSurface, ResolvedSurfaceKind, ResolvedSurfaceLocation, ResolvedSurfaceLocationPlatform, SurfaceResolutionProvider, } from './types.js';
-export { createDiscoveryError, type ExpectedDeliveryUnitIdentity, matchDeliveryUnitIdentity, type ResolvedDeliveryUnitIssue, type ResolvedDeliveryUnitValidationResult, selectResolvedSurface, validateResolvedDeliveryUnit, } from './validation.js';

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

@@ -1,72 +0,0 @@
-/**
- * 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;

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

@@ -1,102 +0,0 @@
-/**
- * Surface-resolution record + provider SPI (MV-G25b/c).
- *
- * Contract: `docs/super-app-rfc-adr/RESOLUTION-0001-surface-discovery-record.md`.
- * Discovery answers a SurfaceRef with exactly ONE {@link ResolvedDeliveryUnit}
- * — never a bare URL, never a partial set of locations — or a typed
- * {@link DiscoveryError} (§2.4: discovery errors are expected states, not
- * exceptions).
- *
- * Atomicity invariant (ADR-0019): `buildMarker` / `sourceRevision` /
- * `baselineCohortId` live once on the record; a {@link ResolvedSurface}
- * carries no marker of its own, so mixing locations from two build markers is
- * structurally unrepresentable.
- */
-import type { DeliveryUnitIdentity } from '../backend-federation-contract/types.js';
-import type { ParsedSurfaceRef } from './surface-ref.js';
-export type ResolvedSurfaceLocationPlatform = 'browser-mf-manifest' | 'node-mf-manifest' | 'http-api' | 'cloudflare-service-binding';
-/**
- * One platform address for a surface, discriminated on `platform` so each
- * platform carries only the address shape its execution adapter can load.
- */
-export type ResolvedSurfaceLocation = {
-    platform: 'browser-mf-manifest';
-    manifestUrl: string;
-} | {
-    /** Backend `backend-mf-manifest.json` URL or filesystem path. */
-    platform: 'node-mf-manifest';
-    manifestRef: string;
-} | {
-    platform: 'http-api';
-    baseUrl: string;
-    prefix: string;
-} | {
-    platform: 'cloudflare-service-binding';
-    serviceBinding: string;
-    dispatchNamespace?: string;
-};
-export type ResolvedSurfaceKind = 'component' | 'route' | 'api' | 'backend';
-/**
- * A resolved surface. It carries NO build marker of its own: the marker lives
- * once on the {@link ResolvedDeliveryUnit} (ADR-0019 structural atomicity).
- */
-export type ResolvedSurface = {
-    surfaceId: string;
-    kind: ResolvedSurfaceKind;
-    locations: ResolvedSurfaceLocation[];
-    /**
-     * The external major (ADR-0020) this materialization serves. Present exactly
-     * when the record answers a versioned SurfaceRef (`…@vN`): the locations are
-     * the major-specific materialization, never the unversioned addresses.
-     */
-    servedMajor?: number;
-};
-export type CompatibilityStatus = 'compatible' | 'incompatible' | 'degraded';
-/** The resolver's verdict, not the consumer's guess (RESOLUTION-0001 §2.1). */
-export type CompatibilityVerdict = {
-    status: CompatibilityStatus;
-    /** Baseline cohort id the verdict was computed against. */
-    baselineCohortId: string;
-    reason?: string;
-};
-/**
- * Atomic resolution result: every platform location for the unit, resolved
- * together against ONE `buildMarker` / `sourceRevision`. There is no partial
- * variant; a resolver returns this whole record or a {@link DiscoveryError}.
- */
-export type ResolvedDeliveryUnit = DeliveryUnitIdentity & {
-    baselineCohortId: string;
-    surfaces: ResolvedSurface[];
-    compatibility: CompatibilityVerdict;
-};
-export type DiscoveryErrorCode = 'unknown-unit' | 'unknown-surface' | 'major-not-published' | 'identity-mismatch' | 'stale-record' | 'provider-unavailable';
-export type DiscoveryError = {
-    code: DiscoveryErrorCode;
-    /** Canonical string form of the SurfaceRef being resolved. */
-    ref: string;
-    message: string;
-    details?: Record<string, unknown>;
-};
-export type DiscoveryResult = {
-    ok: true;
-    unit: ResolvedDeliveryUnit;
-} | {
-    ok: false;
-    error: DiscoveryError;
-};
-/**
- * Environment identity. Providers are selected per environment, not per
- * surface: one environment resolves all surfaces of a unit through the same
- * provider chain.
- */
-export type EnvironmentId = string;
-export type SurfaceResolutionProvider = {
-    /** Stable provider name (e.g. `env-static`), used in error details. */
-    name: string;
-    /**
-     * Resolve a SurfaceRef in an environment to one complete record or one
-     * typed error. Must never return a partial record and must never mix
-     * locations from different build markers.
-     */
-    resolve(ref: ParsedSurfaceRef, env: EnvironmentId): DiscoveryResult | Promise<DiscoveryResult>;
-};

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

@@ -1,53 +0,0 @@
-/**
- * Identity / compatibility validation helpers for resolved delivery units
- * (MV-G25c). Runtime checks for records that crossed a serialization boundary;
- * within TypeScript the atomicity invariant is already structural.
- */
-import { type ParsedSurfaceRef } from './surface-ref.js';
-import type { DiscoveryError, DiscoveryErrorCode, ResolvedDeliveryUnit, ResolvedSurface } from './types.js';
-export type ResolvedDeliveryUnitIssue = {
-    path: string;
-    message: string;
-};
-export type ResolvedDeliveryUnitValidationResult = {
-    ok: boolean;
-    issues: ResolvedDeliveryUnitIssue[];
-};
-/** Build a typed {@link DiscoveryError} for a reference. */
-export declare function createDiscoveryError(code: DiscoveryErrorCode, ref: ParsedSurfaceRef | string, message: string, details?: Record<string, unknown>): DiscoveryError;
-/**
- * Validate the structural invariants of a {@link ResolvedDeliveryUnit}:
- * non-empty identity root, a well-formed compatibility verdict (valid status,
- * computed against the record-level baseline cohort), and per-surface
- * completeness (valid unique surface ids, valid kind, at least one location,
- * no duplicate platform entries, and every discriminant + required address
- * field per location platform). There is no partial-success shape: any issue
- * means the record is not a valid resolution.
- *
- * Total: never throws, even for records that crossed a serialization boundary
- * with missing or malformed nested objects — every defect is a typed issue.
- */
-export declare function validateResolvedDeliveryUnit(unit: ResolvedDeliveryUnit): ResolvedDeliveryUnitValidationResult;
-/**
- * Select the surface a {@link ParsedSurfaceRef} points at within one record.
- * `unknown-unit` when the record is for a different unit, `unknown-surface`
- * when the unit does not publish the surface.
- */
-export declare function selectResolvedSurface(unit: ResolvedDeliveryUnit, ref: ParsedSurfaceRef): {
-    ok: true;
-    surface: ResolvedSurface;
-} | {
-    ok: false;
-    error: DiscoveryError;
-};
-export type ExpectedDeliveryUnitIdentity = {
-    unitId: string;
-    buildMarker: string;
-};
-/**
- * Compare a consumer's expected delivery-unit identity against a resolved
- * record. Execution adapters must pass the record's `unitId` + `buildMarker`
- * through to identity validation (RESOLUTION-0001 §2.3); a mismatch is the
- * typed `identity-mismatch` discovery error.
- */
-export declare function matchDeliveryUnitIdentity(expected: ExpectedDeliveryUnitIdentity, unit: Pick<ResolvedDeliveryUnit, 'unitId' | 'buildMarker'>, ref: ParsedSurfaceRef | string): DiscoveryError | undefined;