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

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

@@ -0,0 +1,107 @@
+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/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.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/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;

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

@@ -0,0 +1,102 @@
+/**
+ * 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 '@modern-js/backend-federation-contracts';
+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/surface-resolution/validation.d.ts

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

package/package.json

@@ -1,16 +1,52 @@
 {
   "name": "@bleedingdev/modern-js-surface-resolution",
-  "version": "0.0.0",
-  "description": "Package-name registration for the forthcoming UltraModern.js release. This setup version contains no runtime implementation.",
+  "version": "3.9.0-ultramodern.5",
+  "description": "Universal surface references, atomic discovery records, and environment-static resolution.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/BleedingDev/ultramodern.js.git"
+    "url": "git+https://github.com/BleedingDev/ultramodern.js.git",
+    "directory": "packages/toolkit/surface-resolution"
+  },
+  "main": "./dist/cjs/surface-resolution/index.js",
+  "module": "./dist/esm/surface-resolution/index.mjs",
+  "types": "./dist/types/surface-resolution/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/surface-resolution/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/surface-resolution/index.mjs",
+        "require": "./dist/cjs/surface-resolution/index.js"
+      },
+      "default": "./dist/esm/surface-resolution/index.mjs"
+    }
   },
   "files": [
-    "README.md"
+    "dist",
+    "src"
   ],
+  "sideEffects": false,
+  "dependencies": {
+    "@modern-js/backend-federation-contracts": "npm:@bleedingdev/modern-js-backend-federation-contracts@3.9.0-ultramodern.5"
+  },
+  "devDependencies": {
+    "@modern-js/tsconfig": "npm:@bleedingdev/modern-js-tsconfig@3.9.0-ultramodern.5",
+    "@rslib/core": "1.0.0",
+    "@rstest/core": "0.11.12",
+    "@scripts/rstest-config": "2.66.0",
+    "@types/node": "^26.4.1",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "test": "rstest run"
+  },
+  "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
+  "bugs": {
+    "url": "https://github.com/BleedingDev/ultramodern.js/issues"
   }
 }