@k2b/cloud 0.6.0-rc.0

package/src/_internal/readiness.ts

@@ -0,0 +1,3 @@
+export const APP_READINESS_PATH = "/_cloud/ready";
+
+export const appReadinessResponse = (appId: string): Response => Response.json({ status: "ready", appId });

package/src/_internal/registry-validation.ts

@@ -0,0 +1,136 @@
+import type { AppRegistryEntry } from "../contracts/registry";
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+const isString = (value: unknown): value is string => typeof value === "string";
+const isStringArray = (value: unknown): value is string[] => Array.isArray(value) && value.every(isString);
+const isStringRecord = (value: unknown): value is Record<string, string> => isRecord(value) && Object.values(value).every(isString);
+
+const invalid = (path: string, expected: string): string => `${path} must be ${expected}`;
+
+export const validateAppRegistryEntry = (value: unknown): string | null => {
+  if (!isRecord(value)) return "entry must be an object";
+  for (const field of ["id", "name", "icon", "description", "baseUrl"] as const) {
+    if (!isString(value[field]) || value[field].length === 0) return invalid(field, "a non-empty string");
+  }
+  try {
+    const baseUrl = new URL(value.baseUrl as string);
+    if (!(["http:", "https:"] as const).includes(baseUrl.protocol as "http:" | "https:") || baseUrl.username || baseUrl.password) {
+      return invalid("baseUrl", "an HTTP(S) URL without embedded credentials");
+    }
+  } catch {
+    return invalid("baseUrl", "an HTTP(S) URL without embedded credentials");
+  }
+  if (!isStringArray(value.routes) || value.routes.some((route) => !route.startsWith("/"))) {
+    return invalid("routes", "an array of absolute paths");
+  }
+  if (value.startedAt !== undefined && !(typeof value.startedAt === "number" && Number.isFinite(value.startedAt))) {
+    return invalid("startedAt", "a finite number");
+  }
+  if (value.runtime !== undefined) {
+    if (!isRecord(value.runtime)) return invalid("runtime", "an object");
+    if (!isString(value.runtime.release) || value.runtime.release.length === 0) return invalid("runtime.release", "a non-empty string");
+    if (!isString(value.runtime.syncVersion) || value.runtime.syncVersion.length === 0) {
+      return invalid("runtime.syncVersion", "a non-empty string");
+    }
+  }
+  if (value.presentation !== undefined) {
+    if (!isRecord(value.presentation) || !isString(value.presentation.baseLocale) || !isRecord(value.presentation.translations)) {
+      return invalid("presentation", "a localized app-presentation catalog");
+    }
+    for (const [locale, translation] of Object.entries(value.presentation.translations)) {
+      if (!isRecord(translation)) return invalid(`presentation.translations.${locale}`, "an object");
+      if (translation.name !== undefined && !isString(translation.name)) return invalid(`presentation.translations.${locale}.name`, "a string");
+      if (translation.description !== undefined && !isString(translation.description)) {
+        return invalid(`presentation.translations.${locale}.description`, "a string");
+      }
+      for (const field of ["adminGroups", "adminLinks", "legalLinks"] as const) {
+        if (translation[field] !== undefined && !isStringRecord(translation[field])) {
+          return invalid(`presentation.translations.${locale}.${field}`, "a string map");
+        }
+      }
+    }
+  }
+  if (value.nav !== undefined) {
+    if (!isRecord(value.nav)) return invalid("nav", "an object");
+    if (!isString(value.nav.href) || !["primary", "more", "hidden"].includes(String(value.nav.section))) {
+      return invalid("nav", "a valid navigation object");
+    }
+    if (value.nav.requiresRoles !== undefined && !isStringArray(value.nav.requiresRoles)) {
+      return invalid("nav.requiresRoles", "an array of strings");
+    }
+  }
+  if (value.adminNav !== undefined) {
+    if (
+      !Array.isArray(value.adminNav) ||
+      value.adminNav.some(
+        (group) =>
+          !isRecord(group) ||
+          (group.id !== undefined && !isString(group.id)) ||
+          !isString(group.label) ||
+          !Array.isArray(group.links) ||
+          group.links.some((link) => !isRecord(link) || !isString(link.label) || !isString(link.href) || !isString(link.icon)),
+      )
+    ) {
+      return invalid("adminNav", "an array of valid navigation groups");
+    }
+  }
+  if (value.legalLinks !== undefined) {
+    if (
+      !Array.isArray(value.legalLinks) ||
+      value.legalLinks.some(
+        (link) => !isRecord(link) || !isString(link.label) || !isString(link.href) || (link.icon !== undefined && !isString(link.icon)),
+      )
+    ) {
+      return invalid("legalLinks", "an array of valid links");
+    }
+  }
+  if (value.widgets !== undefined) {
+    if (
+      !Array.isArray(value.widgets) ||
+      value.widgets.some((widget) => !isRecord(widget) || !isString(widget.id) || !isString(widget.path))
+    ) {
+      return invalid("widgets", "an array of valid widgets");
+    }
+  }
+  if (value.settingKeys !== undefined && !isStringArray(value.settingKeys)) return invalid("settingKeys", "an array of strings");
+  if (value.capabilities !== undefined) {
+    if (
+      !isRecord(value.capabilities) ||
+      typeof value.capabilities.protocolVersion !== "number" ||
+      !isString(value.capabilities.manifestHash)
+    ) {
+      return invalid("capabilities", "a valid capability summary");
+    }
+  }
+  if (value.help !== undefined) {
+    if (
+      !isRecord(value.help) ||
+      !isString(value.help.manifestHash) ||
+      !isString(value.help.pageBase) ||
+      !Array.isArray(value.help.documents)
+    ) {
+      return invalid("help", "a valid Help summary");
+    }
+    if (
+      !value.help.pageBase.startsWith("/") ||
+      value.help.documents.some(
+        (document) =>
+          !isRecord(document) ||
+          !isString(document.id) ||
+          !isString(document.title) ||
+          typeof document.order !== "number" ||
+          !isString(document.searchUrl) ||
+          !document.searchUrl.startsWith("/") ||
+          !isString(document.url) ||
+          !document.url.startsWith("/"),
+      )
+    ) {
+      return invalid("help", "a valid Help summary");
+    }
+  }
+  if (value.openapi !== undefined && !isString(value.openapi)) return invalid("openapi", "a string");
+  return null;
+};
+
+export const asAppRegistryEntry = (value: unknown): AppRegistryEntry | null =>
+  validateAppRegistryEntry(value) === null ? (value as AppRegistryEntry) : null;

package/src/_internal/registry-watch.ts

@@ -0,0 +1,52 @@
+/** Consume registry invalidations without queuing one snapshot read per event. */
+export const watchRegistryChanges = async ({
+  signal,
+  watch,
+  onChange,
+}: {
+  signal: AbortSignal;
+  watch: (signal: AbortSignal) => AsyncIterable<{ type: string }>;
+  onChange: () => Promise<void>;
+}): Promise<void> => {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  signal.addEventListener("abort", abort, { once: true });
+  if (signal.aborted) abort();
+  let dirty = false;
+  let refresh: Promise<void> | undefined;
+  let failure: { error: unknown } | undefined;
+  const invalidate = () => {
+    dirty = true;
+    if (refresh) return;
+    refresh = (async () => {
+      while (dirty) {
+        dirty = false;
+        await onChange();
+      }
+    })()
+      .catch((error: unknown) => {
+        failure = { error };
+        controller.abort();
+      })
+      .finally(() => {
+        refresh = undefined;
+        if (dirty && !failure) invalidate();
+      });
+  };
+  try {
+    while (!controller.signal.aborted) {
+      for await (const event of watch(controller.signal)) {
+        if (controller.signal.aborted) break;
+        invalidate();
+        // A resync invalidates even when the next watch replays no entries.
+        if (event.type === "resync_required") break;
+      }
+    }
+  } finally {
+    controller.abort();
+    signal.removeEventListener("abort", abort);
+    // Finish the current read and any invalidation already received during it.
+    while (refresh) await refresh;
+    if (failure) throw failure.error;
+  }
+};

package/src/_internal/registry.ts

@@ -0,0 +1,338 @@
+import type { EphemeralConfig } from "@k2b/sync";
+import type { AppAppearanceColor } from "../contracts/app";
+import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
+import type { AppRegistryEntry, CapabilityRegistryEntry, HelpRegistryEntry } from "../contracts/registry";
+import type { DashboardWidgetPresentation } from "../contracts/widgets";
+import { resolveAppPresentations } from "../shared/app-presentation";
+import { compileCapabilityPresentation, parseCapabilityManifest } from "./capabilities";
+import { lazySync } from "./process-sync";
+import { validateAppRegistryEntry } from "./registry-validation";
+import { watchRegistryChanges } from "./registry-watch";
+
+/**
+ * Shared app registry: three @k2b/sync ephemerals on the process Sync
+ * instance. Apps, the gateway, and gateway-ops all declare them through the
+ * functions below, so id, owner, TTL, and value bound stay identical across
+ * the fleet (a differing declaration fails with ResourceDriftError).
+ *
+ * TTL is 3× the heartbeat interval (see `./heartbeat.ts`).
+ */
+export const APP_REGISTRY_TTL_MS = 180_000;
+const REGISTRY_OWNER = "cloud";
+
+export const APP_REGISTRY_CONFIG = {
+  id: "cloud-apps",
+  owner: REGISTRY_OWNER,
+  ttlMs: APP_REGISTRY_TTL_MS,
+  maxValueBytes: 64 * 1024,
+} as const satisfies EphemeralConfig;
+
+export const CAPABILITY_REGISTRY_CONFIG = {
+  id: "cloud-capabilities",
+  owner: REGISTRY_OWNER,
+  ttlMs: APP_REGISTRY_TTL_MS,
+  maxValueBytes: 512 * 1024,
+} as const satisfies EphemeralConfig;
+
+export const HELP_REGISTRY_CONFIG = {
+  id: "cloud-help",
+  owner: REGISTRY_OWNER,
+  ttlMs: APP_REGISTRY_TTL_MS,
+  maxValueBytes: 512 * 1024,
+} as const satisfies EphemeralConfig;
+
+export const APP_REGISTRY_PREFIX = "apps/";
+
+export type CapabilityRegistryRecord = { appId: string; manifest: CapabilityManifest; presentation?: CapabilityPresentationCatalog };
+
+export const appRegistry = lazySync((sync) => sync.ephemeral<AppRegistryEntry>(APP_REGISTRY_CONFIG));
+export const capabilityRegistry = lazySync((sync) => sync.ephemeral<CapabilityRegistryRecord>(CAPABILITY_REGISTRY_CONFIG));
+export const helpRegistry = lazySync((sync) => sync.ephemeral<HelpRegistryEntry>(HELP_REGISTRY_CONFIG));
+
+/**
+ * Follow the app registry until `signal` aborts. The watch first replays the
+ * current entries, then streams changes. While a refresh runs, further events
+ * coalesce into one follow-up refresh. Resync also refreshes an empty registry.
+ * Shutdown waits for received invalidations; refresh errors stop the watch.
+ */
+export const watchAppRegistry = async ({ signal, onChange }: { signal: AbortSignal; onChange: () => Promise<void> }): Promise<void> => {
+  const registry = appRegistry();
+  await watchRegistryChanges({ signal, onChange, watch: (signal) => registry.watch({ prefix: APP_REGISTRY_PREFIX, signal }) });
+};
+
+/**
+ * App entry enriched with registry metadata.
+ * `createdAt` = process start reported by the app (uptime anchor).
+ * `updatedAt` = most recent heartbeat touch; `expiresAt` = `updatedAt` + TTL.
+ * `version` = the entry's registry revision.
+ */
+export type AppRegistryDetail = AppRegistryEntry & {
+  createdAt: number;
+  updatedAt: number;
+  expiresAt: number;
+  version: string;
+};
+
+export type AppRegistryIssue = {
+  key: string;
+  version: string;
+  reason: string;
+};
+
+export type AppRegistrySnapshot = {
+  apps: AppRegistryDetail[];
+  issues: AppRegistryIssue[];
+};
+
+const loggedInvalidReasons = new Map<string, string>();
+
+const reportInvalidEntry = (issue: AppRegistryIssue): void => {
+  if (loggedInvalidReasons.get(issue.key) === issue.reason) return;
+  loggedInvalidReasons.set(issue.key, issue.reason);
+  console.error(
+    JSON.stringify({
+      level: "error",
+      source: "app-registry",
+      message: "Rejected invalid app registry entry",
+      registryKey: issue.key,
+      registryVersion: issue.version,
+      reason: issue.reason,
+    }),
+  );
+};
+
+export const readAppRegistrySnapshot = async (): Promise<AppRegistrySnapshot> => {
+  const snapshot = await appRegistry().snapshot({ prefix: APP_REGISTRY_PREFIX });
+  const apps: AppRegistryDetail[] = [];
+  const issues: AppRegistryIssue[] = [];
+  const presentKeys = new Set<string>();
+
+  for (const entry of snapshot.entries) {
+    presentKeys.add(entry.key);
+    const expectedKey =
+      entry.value && typeof entry.value === "object" && "id" in entry.value ? `${APP_REGISTRY_PREFIX}${String(entry.value.id)}` : undefined;
+    const reason = entry.key !== expectedKey ? "registry key must match entry id" : validateAppRegistryEntry(entry.value);
+    if (reason) {
+      const issue = { key: entry.key, version: entry.revision, reason };
+      issues.push(issue);
+      reportInvalidEntry(issue);
+      continue;
+    }
+    loggedInvalidReasons.delete(entry.key);
+    const value = entry.value as AppRegistryEntry;
+    const updatedAt = entry.updatedAt.getTime();
+    apps.push({
+      ...value,
+      createdAt: value.startedAt ?? updatedAt,
+      updatedAt,
+      expiresAt: updatedAt + APP_REGISTRY_TTL_MS,
+      version: entry.revision,
+    });
+  }
+
+  for (const key of loggedInvalidReasons.keys()) {
+    if (!presentKeys.has(key)) loggedInvalidReasons.delete(key);
+  }
+  return { apps, issues };
+};
+
+export const requireUsableAppRegistry = (snapshot: AppRegistrySnapshot): AppRegistryDetail[] => {
+  if (snapshot.apps.length === 0 && snapshot.issues.length > 0) {
+    throw new Error(`App registry contains no valid entries (${snapshot.issues.length} rejected)`);
+  }
+  return snapshot.apps;
+};
+
+/**
+ * List all currently live (TTL-valid) app registry entries.
+ */
+export const listApps = async (): Promise<AppRegistryEntry[]> => {
+  const snapshot = await readAppRegistrySnapshot();
+  return requireUsableAppRegistry(snapshot);
+};
+
+/** Reads one live app without materializing the full registry. */
+export const getApp = async (appId: string): Promise<AppRegistryEntry | null> => {
+  const key = `${APP_REGISTRY_PREFIX}${appId}`;
+  const snap = await appRegistry().snapshot({ prefix: key });
+  const entry = snap.entries.find((candidate) => candidate.key === key);
+  if (!entry) return null;
+  const reason =
+    !entry.value || typeof entry.value !== "object" || !("id" in entry.value) || entry.value.id !== appId
+      ? "registry key must match entry id"
+      : validateAppRegistryEntry(entry.value);
+  if (!reason) {
+    loggedInvalidReasons.delete(key);
+    return entry.value;
+  }
+  reportInvalidEntry({ key, version: entry.revision, reason });
+  return null;
+};
+
+const capabilityEndpoint = (baseUrl: string): string | null => {
+  try {
+    const base = new URL(baseUrl);
+    if (!(["http:", "https:"] as const).includes(base.protocol as "http:" | "https:") || base.username || base.password) return null;
+    return new URL("/api/_internal/capabilities/v1", base).toString();
+  } catch {
+    return null;
+  }
+};
+
+const appAccent = (value: string | undefined): AppAppearanceColor | undefined =>
+  /^#[0-9a-f]{6}$/i.test(value ?? "") ? (value as AppAppearanceColor) : undefined;
+
+export const resolveLiveCapabilityRegistryEntry = (
+  key: string,
+  value: unknown,
+  app: AppRegistryEntry | undefined,
+): CapabilityRegistryEntry | null => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (Object.keys(value).some((field) => field !== "appId" && field !== "manifest" && field !== "presentation")) return null;
+  const record = value as Partial<CapabilityRegistryRecord>;
+  if (!app || typeof record.appId !== "string" || key !== `capabilities/${record.appId}` || record.appId !== app.id) return null;
+  if (!app.capabilities) return null;
+  const endpoint = capabilityEndpoint(app.baseUrl);
+  if (!endpoint) return null;
+  try {
+    const manifest = parseCapabilityManifest(record.manifest, app.id);
+    const presentation = compileCapabilityPresentation(manifest, record.presentation);
+    if (app.capabilities.protocolVersion !== manifest.protocolVersion || app.capabilities.manifestHash !== manifest.manifestHash) {
+      return null;
+    }
+    return {
+      appId: app.id,
+      appName: app.name,
+      appIcon: app.icon,
+      appAccent: appAccent(app.appearance?.accent),
+      appDescription: app.description,
+      endpoint,
+      manifest,
+      presentation,
+    };
+  } catch {
+    return null;
+  }
+};
+
+export const listCapabilities = async (appSnapshot?: AppRegistryEntry[]): Promise<CapabilityRegistryEntry[]> => {
+  const [snap, apps] = await Promise.all([capabilityRegistry().snapshot({ prefix: "capabilities/" }), appSnapshot ?? listApps()]);
+  const byId = new Map(apps.map((app) => [app.id, app]));
+  return snap.entries.flatMap((entry) => {
+    const appId = entry.key.startsWith("capabilities/") ? entry.key.slice("capabilities/".length) : "";
+    const capability = resolveLiveCapabilityRegistryEntry(entry.key, entry.value, byId.get(appId));
+    return capability ? [capability] : [];
+  });
+};
+
+export const getCapability = async (appId: string): Promise<CapabilityRegistryEntry | null> => {
+  const key = `capabilities/${appId}`;
+  const [snap, app] = await Promise.all([capabilityRegistry().snapshot({ prefix: key }), getApp(appId)]);
+  const entry = snap.entries.find((candidate) => candidate.key === key);
+  return entry ? resolveLiveCapabilityRegistryEntry(entry.key, entry.value, app ?? undefined) : null;
+};
+
+const isHelpRegistryEntry = (value: unknown): value is HelpRegistryEntry => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entry = value as Partial<HelpRegistryEntry>;
+  const validDocument = (document: unknown) =>
+    !!document &&
+    typeof document === "object" &&
+    typeof (document as { id?: unknown }).id === "string" &&
+    typeof (document as { title?: unknown }).title === "string" &&
+    typeof (document as { order?: unknown }).order === "number" &&
+    typeof (document as { markdown?: unknown }).markdown === "string" &&
+    ((document as { searchText?: unknown }).searchText === undefined ||
+      typeof (document as { searchText?: unknown }).searchText === "string") &&
+    ((document as { icon?: unknown }).icon === undefined || typeof (document as { icon?: unknown }).icon === "string") &&
+    ((document as { description?: unknown }).description === undefined ||
+      typeof (document as { description?: unknown }).description === "string");
+  return (
+    typeof entry.appId === "string" &&
+    typeof entry.appName === "string" &&
+    typeof entry.appIcon === "string" &&
+    typeof entry.manifestHash === "string" &&
+    (entry.baseLocale === undefined || typeof entry.baseLocale === "string") &&
+    Array.isArray(entry.documents) &&
+    entry.documents.every(validDocument) &&
+    (entry.documentsByLocale === undefined ||
+      (!!entry.documentsByLocale &&
+        typeof entry.documentsByLocale === "object" &&
+        !Array.isArray(entry.documentsByLocale) &&
+        Object.values(entry.documentsByLocale).every((documents) => Array.isArray(documents) && documents.every(validDocument))))
+  );
+};
+
+export const listHelp = async (): Promise<HelpRegistryEntry[]> => {
+  const snap = await helpRegistry().snapshot({ prefix: "help/" });
+  return snap.entries.map((entry) => entry.value).filter(isHelpRegistryEntry);
+};
+
+export const getHelp = async (appId: string): Promise<HelpRegistryEntry | null> => {
+  const key = `help/${appId}`;
+  const snap = await helpRegistry().snapshot({ prefix: key });
+  const value = snap.entries.find((entry) => entry.key === key)?.value;
+  return isHelpRegistryEntry(value) ? value : null;
+};
+
+/**
+ * Same as `listApps` but returns registry metadata for admin observability.
+ */
+export const listAppsDetailed = async (): Promise<AppRegistryDetail[]> => {
+  const snapshot = await readAppRegistrySnapshot();
+  return snapshot.apps;
+};
+
+/**
+ * Aggregate every running app's `legalLinks` into one flat list. Used by the
+ * login footer, app Footer, and rail "more" dropdown to render a unified set
+ * of legal/info links (Imprint, Privacy, Terms, FAQ, …).
+ *
+ * Order = registration order across apps (no explicit weights — KISS). Within
+ * one app, declaration order is preserved. Duplicate `href`s are de-duped
+ * (last-seen wins).
+ */
+export const listLegalLinks = async (locale?: string): Promise<Array<{ label: string; href: string; icon?: string }>> => {
+  const registeredApps = await listApps();
+  const apps = locale ? resolveAppPresentations(registeredApps, locale) : registeredApps;
+  const seen = new Map<string, { label: string; href: string; icon?: string }>();
+  for (const app of apps) {
+    for (const link of app.legalLinks ?? []) seen.set(link.href, { ...link });
+  }
+  return [...seen.values()];
+};
+
+/**
+ * Aggregate every running app's widget endpoints into one flat list. Used by
+ * the dashboard app to build the widget grid and for Core to resolve the
+ * exact target before proxying a widget request.
+ *
+ * Order = registration order across apps.
+ */
+export type DashboardWidget = {
+  appId: string;
+  appName: string;
+  appIcon: string;
+  widgetId: string;
+  /** Fully-qualified URL — `<baseUrl>/<path>`. */
+  url: string;
+  presentation?: DashboardWidgetPresentation;
+};
+
+export const listWidgets = async (): Promise<DashboardWidget[]> => {
+  const apps = await listApps();
+  const out: DashboardWidget[] = [];
+  for (const app of apps) {
+    for (const w of app.widgets ?? []) {
+      out.push({
+        appId: app.id,
+        appName: app.name,
+        appIcon: app.icon,
+        widgetId: w.id,
+        url: `${app.baseUrl.replace(/\/$/, "")}${w.path.startsWith("/") ? w.path : `/${w.path}`}`,
+        presentation: w.presentation,
+      });
+    }
+  }
+  return out;
+};

package/src/_internal/runtime-compatibility.ts

@@ -0,0 +1,64 @@
+import type { AppRegistryEntry } from "../contracts/registry";
+
+export type RuntimeCompatibilityIssue = {
+  code: "invalid-sync-version" | "mixed-sync-generation" | "mixed-sync-version";
+  severity: "warn" | "error";
+  message: string;
+  appIds: string[];
+};
+
+type ParsedVersion = { major: number; minor: number; patch: number };
+
+const parseVersion = (value: string): ParsedVersion | null => {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?$/.exec(value);
+  if (!match) return null;
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+};
+
+/** @k2b/sync 6 moved from Redis to NATS; a 5.x process cannot see 6.x registrations or durable work. */
+const isLegacyGeneration = (version: ParsedVersion): boolean => version.major < 6;
+
+export const assessRuntimeCompatibility = (apps: readonly AppRegistryEntry[]): RuntimeCompatibilityIssue[] => {
+  const issues: RuntimeCompatibilityIssue[] = [];
+  const known: Array<{ id: string; version: string; parsed: ParsedVersion }> = [];
+
+  for (const app of apps) {
+    const version = app.runtime?.syncVersion;
+    if (!version || version === "unknown") continue;
+    const parsed = parseVersion(version);
+    if (!parsed) {
+      issues.push({
+        code: "invalid-sync-version",
+        severity: "warn",
+        message: `App reports invalid @k2b/sync version ${JSON.stringify(version)}.`,
+        appIds: [app.id],
+      });
+      continue;
+    }
+    known.push({ id: app.id, version, parsed });
+  }
+
+  const legacy = known.filter(({ parsed }) => isLegacyGeneration(parsed));
+  const current = known.filter(({ parsed }) => !isLegacyGeneration(parsed));
+  if (legacy.length > 0 && current.length > 0) {
+    issues.push({
+      code: "mixed-sync-generation",
+      severity: "error",
+      message: "Mixed @k2b/sync 5.x (Redis) and 6.x (NATS) runtimes cannot see each other's registrations or durable work.",
+      appIds: [...legacy, ...current].map(({ id }) => id),
+    });
+    return issues;
+  }
+
+  const versions = [...new Set(known.map(({ version }) => version))];
+  if (versions.length > 1) {
+    issues.push({
+      code: "mixed-sync-version",
+      severity: "warn",
+      message: `Mixed @k2b/sync versions are running (${versions.sort().join(", ")}).`,
+      appIds: known.map(({ id }) => id),
+    });
+  }
+
+  return issues;
+};

package/src/_internal/runtime-context.ts

@@ -0,0 +1,84 @@
+import type { CloudRuntime, RuntimeAppMeta } from "../contracts/app";
+import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
+import type { Role } from "../contracts/shared";
+
+/**
+ * Builds a `CloudRuntime` (the shape consumed by Layout, AdminSidebar, NavMenu)
+ * from registry entries.
+ *
+ * This produces the exact same shape as `createRuntimeContext()` in core/runtime.ts,
+ * so all existing UI components work unchanged.
+ */
+export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabilities: CapabilityRegistryEntry[] = []): CloudRuntime => ({
+  apps: entries.map((e): RuntimeAppMeta => {
+    const searchQueries = capabilities.find((entry) => entry.appId === e.id)?.manifest.queries.filter((query) => query.universalSearch);
+    const searchTags = searchQueries?.flatMap((query) => query.universalSearch!.tags.flatMap((tag) => [tag.tag, ...(tag.aliases ?? [])]));
+    return {
+      id: e.id,
+      name: e.name,
+      icon: e.icon,
+      description: e.description,
+      presentation: e.presentation
+        ? {
+            baseLocale: e.presentation.baseLocale,
+            translations: Object.fromEntries(
+              Object.entries(e.presentation.translations).map(([locale, translation]) => [
+                locale,
+                {
+                  ...translation,
+                  adminGroups: translation.adminGroups ? { ...translation.adminGroups } : undefined,
+                  adminLinks: translation.adminLinks ? { ...translation.adminLinks } : undefined,
+                  legalLinks: translation.legalLinks ? { ...translation.legalLinks } : undefined,
+                },
+              ]),
+            ),
+          }
+        : undefined,
+      appearance: e.appearance,
+      adminHref: e.nav?.adminHref,
+      adminNav: e.adminNav?.map((group) => ({
+        id: group.id,
+        label: group.label,
+        links: group.links.map((link) => ({ ...link })),
+      })),
+      routes: e.routes,
+      nav: e.nav
+        ? {
+            href: e.nav.href,
+            match: e.nav.match,
+            section: e.nav.section,
+            requiresAuth: e.nav.requiresAuth,
+            // Registry stores roles as serialized strings; the source type is
+            // Role[] and round-trip is value-preserving.
+            requiresRoles: e.nav.requiresRoles as Role[] | undefined,
+          }
+        : undefined,
+      help: e.help
+        ? {
+            manifestHash: e.help.manifestHash,
+            pageBase: e.help.pageBase,
+            baseLocale: e.help.baseLocale,
+            documentsByLocale: e.help.documentsByLocale
+              ? Object.fromEntries(
+                  Object.entries(e.help.documentsByLocale).map(([locale, documents]) => [
+                    locale,
+                    documents.map((document) => ({ ...document })),
+                  ]),
+                )
+              : undefined,
+            documents: e.help.documents.map((document) => ({ ...document })),
+          }
+        : undefined,
+      searchTags,
+      searchHelp: searchQueries?.map((query) => query.description).join(" "),
+      searchTagHelp: searchQueries?.flatMap((query) =>
+        query.universalSearch!.tags.flatMap((tag) => [
+          { tag: tag.tag, help: tag.description },
+          ...(tag.aliases ?? []).map((alias) => ({ tag: alias, help: `${tag.description} (alias of #${tag.tag})` })),
+        ]),
+      ),
+      legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
+      openapi: e.openapi,
+    };
+  }),
+});