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

package/src/surface-resolution/surface-ref.ts

@@ -0,0 +1,145 @@
+/**
+ * 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 };
+
+const SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+const MAJOR_PATTERN = /^v[1-9][0-9]*$/;
+
+/**
+ * Parse a canonical SurfaceRef string. Total function: every rejection is a
+ * typed {@link SurfaceRefParseError}; never throws.
+ */
+export function parseSurfaceRef(input: string): SurfaceRefParseResult {
+  if (input === '') {
+    return { ok: false, error: { code: 'empty' } };
+  }
+
+  const hashCount = countChar(input, '#');
+  if (hashCount === 0) {
+    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 = atIndex === -1 ? rest : rest.slice(0, atIndex);
+  const ref: ParsedSurfaceRef = { unitId: unitPart, surfaceId };
+
+  if (atIndex !== -1) {
+    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 error === undefined ? { ok: true, ref } : { ok: false, error };
+}
+
+/**
+ * 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 function formatSurfaceRef(ref: ParsedSurfaceRef): string {
+  const error = validateSurfaceRef(ref);
+  if (error !== undefined) {
+    throw new TypeError(`Cannot format invalid SurfaceRef: ${error.code}.`);
+  }
+
+  const base = `${ref.unitId}#${ref.surfaceId}`;
+  return ref.major === undefined ? base : `${base}@v${ref.major}`;
+}
+
+/** The shared semantic invariant for parsed and directly formatted references. */
+export function validateSurfaceRef(
+  ref: ParsedSurfaceRef,
+): SurfaceRefParseError | undefined {
+  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 (
+    ref.major !== undefined &&
+    (!Number.isSafeInteger(ref.major) || ref.major < 1)
+  ) {
+    return { code: 'invalid-major', value: String(ref.major) };
+  }
+
+  return undefined;
+}
+
+function countChar(input: string, char: string): number {
+  let count = 0;
+  for (const current of input) {
+    if (current === char) {
+      count += 1;
+    }
+  }
+  return count;
+}

package/src/surface-resolution/types.ts

@@ -0,0 +1,136 @@
+/**
+ * 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';
+
+/* -------------------------------------------------------------------------- */
+/* Locations (RESOLUTION-0001 §2.1)                                            */
+/* -------------------------------------------------------------------------- */
+
+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;
+    };
+
+/* -------------------------------------------------------------------------- */
+/* Record                                                                      */
+/* -------------------------------------------------------------------------- */
+
+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;
+};
+
+/* -------------------------------------------------------------------------- */
+/* Failure semantics (RESOLUTION-0001 §2.4)                                    */
+/* -------------------------------------------------------------------------- */
+
+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 };
+
+/* -------------------------------------------------------------------------- */
+/* Provider SPI (RESOLUTION-0001 §2.2)                                         */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * 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/src/surface-resolution/validation.ts

@@ -0,0 +1,337 @@
+/**
+ * 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 { formatSurfaceRef, type ParsedSurfaceRef } from './surface-ref';
+import type {
+  DiscoveryError,
+  DiscoveryErrorCode,
+  ResolvedDeliveryUnit,
+  ResolvedSurface,
+} from './types';
+
+const SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+export type ResolvedDeliveryUnitIssue = {
+  path: string;
+  message: string;
+};
+
+export type ResolvedDeliveryUnitValidationResult = {
+  ok: boolean;
+  issues: ResolvedDeliveryUnitIssue[];
+};
+
+/** Build a typed {@link DiscoveryError} for a reference. */
+export function createDiscoveryError(
+  code: DiscoveryErrorCode,
+  ref: ParsedSurfaceRef | string,
+  message: string,
+  details?: Record<string, unknown>,
+): DiscoveryError {
+  const refString = typeof ref === 'string' ? ref : formatSurfaceRef(ref);
+  return details === undefined
+    ? { code, ref: refString, message }
+    : { code, ref: refString, message, details };
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isValidUnitId(unitId: string): boolean {
+  return unitId.split('/').every(segment => SEGMENT_PATTERN.test(segment));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+const COMPATIBILITY_STATUSES: readonly string[] = [
+  'compatible',
+  'incompatible',
+  'degraded',
+];
+
+const SURFACE_KINDS: readonly string[] = [
+  'component',
+  'route',
+  'api',
+  'backend',
+];
+
+const LOCATION_PLATFORMS: readonly string[] = [
+  'browser-mf-manifest',
+  'node-mf-manifest',
+  'http-api',
+  'cloudflare-service-binding',
+];
+
+/** Required non-empty string address fields per location platform. */
+const LOCATION_REQUIRED_FIELDS: Record<string, readonly string[]> = {
+  'browser-mf-manifest': ['manifestUrl'],
+  'node-mf-manifest': ['manifestRef'],
+  'http-api': ['baseUrl', 'prefix'],
+  'cloudflare-service-binding': ['serviceBinding'],
+};
+
+type IssuePush = (path: string, message: string) => void;
+
+function validateLocation(
+  location: unknown,
+  path: string,
+  seenPlatforms: Set<string>,
+  push: IssuePush,
+): void {
+  if (!isRecord(location)) {
+    push(path, 'must be an object');
+    return;
+  }
+
+  const platform = location.platform;
+  if (typeof platform !== 'string' || !LOCATION_PLATFORMS.includes(platform)) {
+    push(`${path}.platform`, `must be one of ${LOCATION_PLATFORMS.join(', ')}`);
+    return;
+  }
+
+  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 (
+    platform === 'cloudflare-service-binding' &&
+    location.dispatchNamespace !== undefined &&
+    !isNonEmptyString(location.dispatchNamespace)
+  ) {
+    push(
+      `${path}.dispatchNamespace`,
+      'must be a non-empty string when present',
+    );
+  }
+}
+
+function validateSurface(
+  surface: unknown,
+  path: string,
+  seenSurfaceIds: Set<string>,
+  push: IssuePush,
+): void {
+  if (!isRecord(surface)) {
+    push(path, 'must be an object');
+    return;
+  }
+
+  if (!isNonEmptyString(surface.surfaceId)) {
+    push(`${path}.surfaceId`, 'must be a non-empty string');
+  } else if (!SEGMENT_PATTERN.test(surface.surfaceId)) {
+    push(`${path}.surfaceId`, 'must match the SurfaceRef SurfaceId grammar');
+  } else if (seenSurfaceIds.has(surface.surfaceId)) {
+    push(`${path}.surfaceId`, 'must be unique within the record');
+  } else {
+    seenSurfaceIds.add(surface.surfaceId);
+  }
+
+  if (
+    typeof surface.kind !== 'string' ||
+    !SURFACE_KINDS.includes(surface.kind)
+  ) {
+    push(`${path}.kind`, `must be one of ${SURFACE_KINDS.join(', ')}`);
+  }
+
+  if (
+    surface.servedMajor !== undefined &&
+    (!Number.isSafeInteger(surface.servedMajor) ||
+      (surface.servedMajor as number) < 1)
+  ) {
+    push(`${path}.servedMajor`, 'must be a positive safe integer when present');
+  }
+
+  if (!Array.isArray(surface.locations)) {
+    push(`${path}.locations`, 'must be an array of locations');
+    return;
+  }
+  if (surface.locations.length === 0) {
+    push(
+      `${path}.locations`,
+      'must contain at least one location (no partial records)',
+    );
+  }
+  const seenPlatforms = new Set<string>();
+  surface.locations.forEach((location, locationIndex) => {
+    validateLocation(
+      location,
+      `${path}.locations[${locationIndex}]`,
+      seenPlatforms,
+      push,
+    );
+  });
+}
+
+/**
+ * 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 function validateResolvedDeliveryUnit(
+  unit: ResolvedDeliveryUnit,
+): ResolvedDeliveryUnitValidationResult {
+  const issues: ResolvedDeliveryUnitIssue[] = [];
+  const push: IssuePush = (path, message) => {
+    issues.push({ path, message });
+  };
+
+  if (!isRecord(unit)) {
+    push('', 'must be an object');
+    return { ok: false, issues };
+  }
+  // From here on treat the input as untrusted wire data.
+  const raw = unit as unknown as Record<string, unknown>;
+
+  if (!isNonEmptyString(raw.unitId)) {
+    push('unitId', 'must be a non-empty string');
+  } else if (!isValidUnitId(raw.unitId)) {
+    push('unitId', 'must match the SurfaceRef UnitId grammar');
+  }
+  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)) {
+    push('compatibility', 'must be an object');
+  } else {
+    if (
+      typeof compatibility.status !== 'string' ||
+      !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 (
+      compatibility.reason !== undefined &&
+      !isNonEmptyString(compatibility.reason)
+    ) {
+      push('compatibility.reason', 'must be a non-empty string when present');
+    }
+  }
+
+  if (!Array.isArray(raw.surfaces)) {
+    push('surfaces', 'must be an array of surfaces');
+    return { ok: false, issues };
+  }
+  if (raw.surfaces.length === 0) {
+    push('surfaces', 'must contain at least one surface');
+  }
+  const seenSurfaceIds = new Set<string>();
+  raw.surfaces.forEach((surface, surfaceIndex) => {
+    validateSurface(surface, `surfaces[${surfaceIndex}]`, seenSurfaceIds, push);
+  });
+
+  return { ok: issues.length === 0, issues };
+}
+
+/**
+ * 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 function selectResolvedSurface(
+  unit: ResolvedDeliveryUnit,
+  ref: ParsedSurfaceRef,
+):
+  | { ok: true; surface: ResolvedSurface }
+  | { ok: false; error: DiscoveryError } {
+  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 (surface === undefined) {
+    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 };
+}
+
+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 function matchDeliveryUnitIdentity(
+  expected: ExpectedDeliveryUnitIdentity,
+  unit: Pick<ResolvedDeliveryUnit, 'unitId' | 'buildMarker'>,
+  ref: ParsedSurfaceRef | string,
+): DiscoveryError | undefined {
+  if (
+    expected.unitId === unit.unitId &&
+    expected.buildMarker === unit.buildMarker
+  ) {
+    return undefined;
+  }
+
+  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 },
+    },
+  );
+}

package/README.md

@@ -1,3 +0,0 @@
-# @bleedingdev/modern-js-surface-resolution
-
-This 0.0.0 version only registers the package name so npm trusted publishing can be configured. It contains no runtime implementation. Use the subsequent UltraModern.js release, published from the repository workflow with provenance.