@bleedingdev/modern-js-utils 3.5.0-ultramodern.10 → 3.5.0-ultramodern.101

package/dist/types/universal/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 '../backend-federation-contract/types';
+import type { ParsedSurfaceRef } from './surface-ref';
+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

@@ -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';
+import type { DiscoveryError, DiscoveryErrorCode, ResolvedDeliveryUnit, ResolvedSurface } from './types';
+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

@@ -17,7 +17,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.5.0-ultramodern.10",
+  "version": "3.5.0-ultramodern.101",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.mjs",
@@ -118,7 +118,6 @@
     }
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "typesVersions": {
@@ -181,19 +180,19 @@
   },
   "dependencies": {
     "@swc/helpers": "^0.5.23",
-    "caniuse-lite": "^1.0.30001799",
+    "caniuse-lite": "^1.0.30001803",
     "import-meta-resolve": "^4.2.0",
     "lodash": "^4.18.1",
     "lodash-es": "^4.18.1",
     "rslog": "^2.1.3"
   },
   "devDependencies": {
-    "@rslib/core": "0.23.1",
-    "@types/node": "^26.0.1",
-    "@typescript/native-preview": "7.0.0-dev.20260628.1",
-    "happy-dom": "^20.10.6",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.5.0-ultramodern.10",
-    "@scripts/rstest-config": "2.66.0"
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.5.0-ultramodern.101",
+    "@rslib/core": "0.23.2",
+    "@scripts/rstest-config": "2.66.0",
+    "@types/node": "^26.1.1",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "happy-dom": "^20.10.6"
   },
   "peerDependencies": {
     "react": "^19.2.7",