@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/packages/public-runtime/src/integration/observability.ts

@@ -0,0 +1,451 @@
+/**
+ * Per-integration observability + performance budgets (ext-policy-08).
+ *
+ * Third-party integrations run inside the kernel-05 lifecycle runtime and the
+ * commerce-01 event broker, both of which already isolate a faulting
+ * integration from the page and from every other integration. This module is
+ * the durable, ATTRIBUTED signal those isolation points feed: a closed,
+ * fail-closed, secret-free contract that names WHICH integration (appId +
+ * version + origin) produced a performance measurement, a CSP violation, an
+ * initialization failure, or a delivery failure — tenant/environment/
+ * siteSurface scoped, exactly like {@link import("./tamper-evidence.js").TamperEvidenceBeacon}.
+ *
+ * Every manifest already DECLARES a per-integration {@link PerformanceBudget}
+ * (`browser.performanceBudget`, ext-policy-01). This module is the RUNTIME
+ * side of that declaration: {@link evaluatePerformanceBudget} compares a
+ * measured {@link PerformanceSignal} against the declared budget and flags an
+ * integration that exceeds it. Budget evaluation is fail-closed: an
+ * integration with no resolvable budget is flagged over-budget rather than
+ * silently passed ({@link evaluatePerformanceBudgets}).
+ *
+ * No PII: the schema is closed by construction (no free-form user data field
+ * exists to leak) and every signal is scanned with {@link findForbiddenFields}
+ * (secrets.ts) as defense in depth, exactly like every other contract here.
+ */
+import type { ContractResult } from "./result.js";
+import {
+  Violations,
+  reqObject,
+  childObject,
+  reqEnum,
+  reqLiteral,
+  reqString,
+  reqInt,
+  reqIsoTimestamp,
+  rejectUnknownKeys,
+  joinPath,
+} from "./result.js";
+import { OBSERVABILITY_SIGNAL_SCHEMA_VERSION } from "./version.js";
+import { INTEGRATION_ENVIRONMENTS, INTEGRATION_SITE_SURFACES } from "./environment.js";
+import type { IntegrationEnvironment, IntegrationSiteSurface } from "./environment.js";
+import { findForbiddenFields } from "./secrets.js";
+import type { PerformanceBudget } from "./manifest.js";
+import type { LifecycleObservation } from "./lifecycle-runtime.js";
+import type { SubscriberDeliveryOutcome } from "./commerce-broker.js";
+
+/**
+ * The observability signal taxonomy. Every one is a fact ATTRIBUTABLE to one
+ * integration's own code, entry, or destination — never anonymous DOM reach
+ * (that is {@link import("./tamper-evidence.js").TamperEvidenceBeacon}'s domain).
+ */
+export const OBSERVABILITY_SIGNAL_KINDS = [
+  "performance",
+  "csp-violation",
+  "initialization-failure",
+  "delivery-failure",
+] as const;
+export type ObservabilitySignalKind = (typeof OBSERVABILITY_SIGNAL_KINDS)[number];
+
+/** The exact integration a signal is attributed to — never a guess. */
+export interface IntegrationAttribution {
+  appId: string;
+  version: string;
+  origin: string;
+}
+
+/** Stable key for grouping/looking up signals or budgets by integration identity. */
+export function attributionKey(attribution: IntegrationAttribution): string {
+  return `${attribution.appId}@${attribution.version}`;
+}
+
+// ── Per-kind measured data ──────────────────────────────────────────────────
+
+/**
+ * Measured timing/transfer facts for one integration's load+init. The three
+ * budget-bearing fields ({@link PERFORMANCE_BUDGET_DIMENSIONS}) map 1:1 onto
+ * the manifest's declared {@link PerformanceBudget}; `loadMs`/`initMs` are
+ * diagnostic timing with no declared ceiling.
+ */
+export interface PerformanceSignalData {
+  /** Milliseconds from module-fetch start to the loader resolving (kernel-05 `load` stage). */
+  loadMs: number;
+  /** Milliseconds from a resolved module to `init()` resolving (kernel-05 `init` stage). */
+  initMs: number;
+  /** Bytes transferred for the entry module and anything it fetched during load+init. */
+  transferredBytes: number;
+  /** Network requests beyond the entry module observed during load+init. */
+  additionalRequests: number;
+  /** Main-thread time attributable to this integration's load+init, ms. */
+  mainThreadMilliseconds: number;
+}
+
+export const CSP_VIOLATION_DISPOSITIONS = ["enforce", "report"] as const;
+export type CspViolationDisposition = (typeof CSP_VIOLATION_DISPOSITIONS)[number];
+
+export interface CspViolationSignalData {
+  /** The violated directive, e.g. `"script-src"`. */
+  directive: string;
+  /** The blocked origin only — never a full URL (a query string is where a token lives). */
+  blockedOrigin: string;
+  disposition: CspViolationDisposition;
+}
+
+/** The lifecycle stages a failure can be attributed to before an integration ever runs. */
+export const INITIALIZATION_FAILURE_STAGES = ["load", "init"] as const;
+export type InitializationFailureStage = (typeof INITIALIZATION_FAILURE_STAGES)[number];
+
+export interface InitializationFailureSignalData {
+  stage: InitializationFailureStage;
+  /** A message only — never a stack or thrown value (kernel-05's own convention). */
+  message: string;
+}
+
+export interface DeliveryFailureSignalData {
+  /** The commerce-broker subscription id that failed to receive the event. */
+  subscriberId: string;
+  /** A message only — never a stack or thrown value. */
+  message: string;
+}
+
+// ── The closed, discriminated signal contract ───────────────────────────────
+
+interface ObservabilitySignalBase {
+  schemaVersion: typeof OBSERVABILITY_SIGNAL_SCHEMA_VERSION;
+  tenant: string;
+  environment: IntegrationEnvironment;
+  siteSurface: IntegrationSiteSurface;
+  attribution: IntegrationAttribution;
+  /** ISO-8601 instant the signal was observed. */
+  observedAt: string;
+}
+
+export interface PerformanceSignal extends ObservabilitySignalBase {
+  kind: "performance";
+  data: PerformanceSignalData;
+}
+
+export interface CspViolationSignal extends ObservabilitySignalBase {
+  kind: "csp-violation";
+  data: CspViolationSignalData;
+}
+
+export interface InitializationFailureSignal extends ObservabilitySignalBase {
+  kind: "initialization-failure";
+  data: InitializationFailureSignalData;
+}
+
+export interface DeliveryFailureSignal extends ObservabilitySignalBase {
+  kind: "delivery-failure";
+  data: DeliveryFailureSignalData;
+}
+
+/** The closed, versioned, secret-free per-integration observability signal. */
+export type IntegrationObservabilitySignal =
+  | PerformanceSignal
+  | CspViolationSignal
+  | InitializationFailureSignal
+  | DeliveryFailureSignal;
+
+/** The fields a caller supplies to {@link buildObservabilitySignal}. */
+export type ObservabilitySignalInput = Omit<IntegrationObservabilitySignal, "schemaVersion">;
+
+/** Stamp the fixed `schemaVersion` — the only constructor, so a signal is never built stale. */
+export function buildObservabilitySignal(
+  input: ObservabilitySignalInput,
+): IntegrationObservabilitySignal {
+  return { schemaVersion: OBSERVABILITY_SIGNAL_SCHEMA_VERSION, ...input } as IntegrationObservabilitySignal;
+}
+
+/**
+ * Reduce a raw CSP `blocked-uri` to the bare origin a signal may carry. A
+ * scheme keyword (`"inline"`, `"eval"`, `"data"`, `"blob"`, `"self"`) passes
+ * through unchanged; a URL is reduced to `scheme://host[:port]` with the
+ * path/query/fragment dropped — the query string is where a candidate/preview
+ * token would live (the same reduction {@link import("./lifecycle-runtime.js").sanitizeNavigationUrl} applies to navigation).
+ */
+export function sanitizeBlockedUri(raw: string): string {
+  try {
+    const url = new URL(raw);
+    return `${url.protocol}//${url.host}`;
+  } catch {
+    return raw.split("?")[0]!.split("#")[0]!;
+  }
+}
+
+function reqNonNegativeInt(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): number | undefined {
+  const value = reqInt(obj, key, v, path);
+  if (value !== undefined && value < 0) {
+    v.add(joinPath(path, key), "format", `"${key}" must be non-negative.`);
+    return undefined;
+  }
+  return value;
+}
+
+function reqNonNegativeNumber(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): number | undefined {
+  const value = obj[key];
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    v.add(joinPath(path, key), "type", `Expected a non-negative number at "${key}".`);
+    return undefined;
+  }
+  return value;
+}
+
+/** No query string or fragment — that is where a preview/candidate token would ride. */
+function reqNoQueryOrFragment(value: string, v: Violations, path: string): void {
+  if (value.includes("?") || value.includes("#")) {
+    v.add(path, "format", `"${path}" must not carry a query string or fragment.`);
+  }
+}
+
+function validateAttribution(
+  value: unknown,
+  v: Violations,
+  path: string,
+): IntegrationAttribution | undefined {
+  const obj = reqObject(value, v, path);
+  if (!obj) return undefined;
+  rejectUnknownKeys(obj, ["appId", "version", "origin"], v, path);
+  const appId = reqString(obj, "appId", v, path);
+  const version = reqString(obj, "version", v, path);
+  const origin = reqString(obj, "origin", v, path);
+  if (appId === undefined || version === undefined || origin === undefined) return undefined;
+  return { appId, version, origin };
+}
+
+function validateSignalData(
+  kind: ObservabilitySignalKind,
+  data: Record<string, unknown>,
+  v: Violations,
+): void {
+  switch (kind) {
+    case "performance":
+      rejectUnknownKeys(
+        data,
+        ["loadMs", "initMs", "transferredBytes", "additionalRequests", "mainThreadMilliseconds"],
+        v,
+        "data",
+      );
+      reqNonNegativeNumber(data, "loadMs", v, "data");
+      reqNonNegativeNumber(data, "initMs", v, "data");
+      reqNonNegativeInt(data, "transferredBytes", v, "data");
+      reqNonNegativeInt(data, "additionalRequests", v, "data");
+      reqNonNegativeNumber(data, "mainThreadMilliseconds", v, "data");
+      return;
+    case "csp-violation": {
+      rejectUnknownKeys(data, ["directive", "blockedOrigin", "disposition"], v, "data");
+      reqString(data, "directive", v, "data");
+      const blockedOrigin = reqString(data, "blockedOrigin", v, "data");
+      if (blockedOrigin !== undefined) {
+        reqNoQueryOrFragment(blockedOrigin, v, "data.blockedOrigin");
+      }
+      reqEnum(data, "disposition", CSP_VIOLATION_DISPOSITIONS, v, "data");
+      return;
+    }
+    case "initialization-failure":
+      rejectUnknownKeys(data, ["stage", "message"], v, "data");
+      reqEnum(data, "stage", INITIALIZATION_FAILURE_STAGES, v, "data");
+      reqString(data, "message", v, "data");
+      return;
+    case "delivery-failure":
+      rejectUnknownKeys(data, ["subscriberId", "message"], v, "data");
+      reqString(data, "subscriberId", v, "data");
+      reqString(data, "message", v, "data");
+      return;
+  }
+}
+
+/**
+ * The single fail-CLOSED authority for "is this a well-formed observability
+ * signal?". Rejects an unknown schema version, an unknown kind, a malformed
+ * attribution, a kind/data mismatch, or any secret-bearing field.
+ */
+export function validateObservabilitySignal(
+  input: unknown,
+): ContractResult<IntegrationObservabilitySignal> {
+  const v = new Violations();
+  const obj = reqObject(input, v, "");
+  if (!obj) return { ok: false, violations: v.items };
+
+  rejectUnknownKeys(
+    obj,
+    ["schemaVersion", "kind", "tenant", "environment", "siteSurface", "attribution", "observedAt", "data"],
+    v,
+    "",
+  );
+
+  reqLiteral(obj, "schemaVersion", OBSERVABILITY_SIGNAL_SCHEMA_VERSION, v, "");
+  const kind = reqEnum(obj, "kind", OBSERVABILITY_SIGNAL_KINDS, v, "");
+  reqString(obj, "tenant", v, "");
+  reqEnum(obj, "environment", INTEGRATION_ENVIRONMENTS, v, "");
+  reqEnum(obj, "siteSurface", INTEGRATION_SITE_SURFACES, v, "");
+  reqIsoTimestamp(obj, "observedAt", v, "");
+  validateAttribution(obj["attribution"], v, "attribution");
+
+  const data = childObject(obj, "data", v, "");
+  if (kind && data) validateSignalData(kind, data, v);
+
+  for (const violation of findForbiddenFields(obj)) v.items.push(violation);
+
+  if (!v.ok) return { ok: false, violations: v.items };
+  return { ok: true, value: input as IntegrationObservabilitySignal };
+}
+
+// ── Bridges from the sibling isolation points (kernel-05, commerce-01) ─────
+
+/** {@link IntegrationAttribution} from the boot descriptor's per-integration identity. */
+export function attributionFromBootIntegration(integration: {
+  appId: string;
+  version: string;
+  origin: string;
+}): IntegrationAttribution {
+  return { appId: integration.appId, version: integration.version, origin: integration.origin };
+}
+
+/** Everything an observation needs to become a signal, beyond the observation itself. */
+export interface ObservabilitySignalContext {
+  tenant: string;
+  environment: IntegrationEnvironment;
+  siteSurface: IntegrationSiteSurface;
+  /** ISO-8601 timestamp source; defaults to wall clock. */
+  now?: () => string;
+}
+
+function nowOf(context: ObservabilitySignalContext): string {
+  return context.now ? context.now() : new Date().toISOString();
+}
+
+/**
+ * Turn a failed kernel-05 {@link LifecycleObservation} into an attributed
+ * `initialization-failure` signal. `null` for anything that is not a load/init
+ * failure — a successful stage, an update/dispose, or a consent `gate` deferral
+ * is not an initialization failure.
+ */
+export function initializationFailureFromObservation(
+  observation: LifecycleObservation,
+  context: ObservabilitySignalContext,
+): InitializationFailureSignal | null {
+  if (observation.ok) return null;
+  if (observation.stage !== "load" && observation.stage !== "init") return null;
+  return buildObservabilitySignal({
+    kind: "initialization-failure",
+    tenant: context.tenant,
+    environment: context.environment,
+    siteSurface: context.siteSurface,
+    attribution: attributionFromBootIntegration(observation.integration),
+    observedAt: nowOf(context),
+    data: { stage: observation.stage, message: observation.error ?? "unknown error" },
+  }) as InitializationFailureSignal;
+}
+
+/**
+ * Turn a failed commerce-broker {@link SubscriberDeliveryOutcome} into an
+ * attributed `delivery-failure` signal. `null` when delivery succeeded or was
+ * a policy-correct skip (`out-of-scope` / `consent-ineligible`) — only a
+ * throwing subscriber (`reason: "threw"`) is a genuine delivery failure.
+ * `attribution` is supplied by the caller, which owns the subscriber-id →
+ * integration mapping (a subscriber id is not itself an appId/version/origin).
+ */
+export function deliveryFailureFromOutcome(
+  outcome: SubscriberDeliveryOutcome,
+  attribution: IntegrationAttribution,
+  context: ObservabilitySignalContext,
+): DeliveryFailureSignal | null {
+  if (outcome.delivered || outcome.reason !== "threw") return null;
+  return buildObservabilitySignal({
+    kind: "delivery-failure",
+    tenant: context.tenant,
+    environment: context.environment,
+    siteSurface: context.siteSurface,
+    attribution,
+    observedAt: nowOf(context),
+    data: { subscriberId: outcome.subscriberId, message: outcome.error ?? "unknown error" },
+  }) as DeliveryFailureSignal;
+}
+
+// ── Budgets: the runtime side of the manifest's declared PerformanceBudget ──
+
+/** The three declared budget dimensions a {@link PerformanceSignal} is evaluated against. */
+export const PERFORMANCE_BUDGET_DIMENSIONS = [
+  "transferredBytes",
+  "additionalRequests",
+  "mainThreadMilliseconds",
+] as const;
+export type PerformanceBudgetDimension = (typeof PERFORMANCE_BUDGET_DIMENSIONS)[number];
+
+const BUDGET_CEILING_FIELD: Record<
+  PerformanceBudgetDimension,
+  "maxTransferredBytes" | "maxAdditionalRequests" | "maxMainThreadMilliseconds"
+> = {
+  transferredBytes: "maxTransferredBytes",
+  additionalRequests: "maxAdditionalRequests",
+  mainThreadMilliseconds: "maxMainThreadMilliseconds",
+};
+
+export interface PerformanceBudgetVerdict {
+  attribution: IntegrationAttribution;
+  overBudget: boolean;
+  /** Every dimension that exceeded its declared ceiling; empty ⇔ `overBudget: false`. */
+  exceeded: PerformanceBudgetDimension[];
+}
+
+/**
+ * Compare one measured {@link PerformanceSignal} against its integration's
+ * declared {@link PerformanceBudget}. Every dimension is checked (no
+ * short-circuit), so `exceeded` is complete.
+ */
+export function evaluatePerformanceBudget(
+  signal: PerformanceSignal,
+  budget: PerformanceBudget,
+): PerformanceBudgetVerdict {
+  const exceeded: PerformanceBudgetDimension[] = [];
+  for (const dimension of PERFORMANCE_BUDGET_DIMENSIONS) {
+    if (signal.data[dimension] > budget[BUDGET_CEILING_FIELD[dimension]]) {
+      exceeded.push(dimension);
+    }
+  }
+  return { attribution: signal.attribution, overBudget: exceeded.length > 0, exceeded };
+}
+
+/**
+ * Evaluate a batch of performance signals. FAIL-CLOSED: an integration whose
+ * budget cannot be resolved (`budgetOf` returns `undefined` — an absent or
+ * unresolvable manifest) is flagged over-budget on every dimension rather than
+ * silently passed, so a missing declaration can never read as a clean bill of
+ * health.
+ */
+export function evaluatePerformanceBudgets(
+  signals: readonly PerformanceSignal[],
+  budgetOf: (attribution: IntegrationAttribution) => PerformanceBudget | undefined,
+): PerformanceBudgetVerdict[] {
+  return signals.map((signal) => {
+    const budget = budgetOf(signal.attribution);
+    if (!budget) {
+      return {
+        attribution: signal.attribution,
+        overBudget: true,
+        exceeded: [...PERFORMANCE_BUDGET_DIMENSIONS],
+      };
+    }
+    return evaluatePerformanceBudget(signal, budget);
+  });
+}

package/packages/public-runtime/src/integration/phases.ts

@@ -0,0 +1,182 @@
+/**
+ * Reserved render phases, authority tiers, and the contribution dependency DAG
+ * (ADR 0014 S1/S2 `integration-phases-fixed-dag`, I1 `integration-authority-
+ * four-tiers`, ADR 0016).
+ *
+ * Phases are a fixed, ordered set — there is no arbitrary selector or generic
+ * injection slot. Dependencies form a DAG within that order; cycles, unresolved
+ * references, duplicate edges, and any edge that would let a later-phase
+ * contribution outrank an earlier compliance phase are rejected.
+ */
+import type { Violations } from "./result.js";
+import { assertUnique } from "./result.js";
+
+/** Reserved phases in fixed execution order. */
+export const RESERVED_PHASES = [
+  "platform.environment", // renderer-owned environment block; not vendor-addressable
+  "consent.defaults", // compliance/consent baseline — cannot be outranked
+  "head.early", // early-head loader
+  "body.start", // body-start fallback markup
+  "document.deferred", // deferred global entry
+] as const;
+export type ReservedPhase = (typeof RESERVED_PHASES)[number];
+
+/** Phases a vendor entry or contribution may target. `platform.environment` is renderer-owned. */
+export const VENDOR_ADDRESSABLE_PHASES = [
+  "consent.defaults",
+  "head.early",
+  "body.start",
+  "document.deferred",
+] as const;
+export type VendorAddressablePhase = (typeof VENDOR_ADDRESSABLE_PHASES)[number];
+
+/** Compliance-critical phases that always precede vendor code and cannot be outranked. */
+export const COMPLIANCE_PHASES: readonly ReservedPhase[] = [
+  "platform.environment",
+  "consent.defaults",
+];
+
+export function isReservedPhase(value: unknown): value is ReservedPhase {
+  return (
+    typeof value === "string" &&
+    (RESERVED_PHASES as readonly string[]).includes(value)
+  );
+}
+
+export function phaseRank(phase: ReservedPhase): number {
+  return RESERVED_PHASES.indexOf(phase);
+}
+
+/** Four authority tiers; declared DOM intent never masquerades as isolation (ADR 0016). */
+export const EXECUTION_TIERS = [
+  "platform-adapter",
+  "sandbox",
+  "server",
+  "elevated-parent",
+] as const;
+export type ExecutionTier = (typeof EXECUTION_TIERS)[number];
+
+/** Contribution kinds. Only curated platform templates — no arbitrary markup slot. */
+export const CONTRIBUTION_KINDS = ["platform-template"] as const;
+export type ContributionKind = (typeof CONTRIBUTION_KINDS)[number];
+
+/** Entry asset formats. Module-only keeps the strict CSP grammar (ADR 0019). */
+export const ENTRY_FORMATS = ["module"] as const;
+export type EntryFormat = (typeof ENTRY_FORMATS)[number];
+
+/** A node in the contribution DAG: the implicit `entry` plus each contribution id. */
+export interface DagNode {
+  id: string;
+  phase: ReservedPhase;
+}
+
+/** `dependent` runs after `prerequisite`. */
+export interface DagEdge {
+  dependent: string;
+  prerequisite: string;
+}
+
+/**
+ * Fail-closed validation of the contribution DAG: unique ids, resolvable edge
+ * endpoints, no duplicate edges, no cycles, and no phase inversion (a dependent
+ * may not sit in an earlier phase than a prerequisite it runs after, which is
+ * how "compliance phases cannot be outranked" is enforced by construction).
+ */
+export function validateContributionDag(
+  nodes: readonly DagNode[],
+  edges: readonly DagEdge[],
+  v: Violations,
+  path: string,
+): void {
+  assertUnique(
+    nodes.map((n) => n.id),
+    v,
+    `${path}.contributions`,
+    "contribution id",
+  );
+
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const adjacency = new Map<string, string[]>();
+  const seenEdges = new Set<string>();
+
+  edges.forEach((edge, i) => {
+    const edgePath = `${path}.dependencies[${i}]`;
+    const dependent = byId.get(edge.dependent);
+    const prerequisite = byId.get(edge.prerequisite);
+    if (!dependent) {
+      v.add(edgePath, "unresolved_ref", `Unknown contribution "${edge.dependent}".`);
+    }
+    if (!prerequisite) {
+      v.add(edgePath, "unresolved_ref", `Unknown prerequisite "${edge.prerequisite}".`);
+    }
+    const key = `${edge.dependent}<-${edge.prerequisite}`;
+    if (seenEdges.has(key)) {
+      v.add(edgePath, "duplicate", "Duplicate dependency edge; duplicates are rejected.");
+    }
+    seenEdges.add(key);
+    if (dependent && prerequisite) {
+      if (phaseRank(dependent.phase) < phaseRank(prerequisite.phase)) {
+        v.add(
+          edgePath,
+          "phase_inversion",
+          `"${edge.dependent}" (${dependent.phase}) cannot run after later-phase ` +
+            `"${edge.prerequisite}" (${prerequisite.phase}); an earlier or compliance ` +
+            `phase cannot be outranked.`,
+        );
+      }
+      const list = adjacency.get(edge.dependent);
+      if (list) list.push(edge.prerequisite);
+      else adjacency.set(edge.dependent, [edge.prerequisite]);
+    }
+  });
+
+  const cycle = findCycle(
+    nodes.map((n) => n.id),
+    adjacency,
+  );
+  if (cycle) {
+    v.add(
+      `${path}.dependencies`,
+      "cycle",
+      `Dependency cycle: ${cycle.join(" -> ")}. The contribution graph must be acyclic.`,
+    );
+  }
+}
+
+function findCycle(
+  ids: readonly string[],
+  adjacency: Map<string, string[]>,
+): string[] | null {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map<string, number>(ids.map((id) => [id, WHITE]));
+  const stack: string[] = [];
+
+  const visit = (node: string): string[] | null => {
+    color.set(node, GRAY);
+    stack.push(node);
+    for (const next of adjacency.get(node) ?? []) {
+      const state = color.get(next) ?? WHITE;
+      if (state === GRAY) {
+        const from = stack.indexOf(next);
+        return [...stack.slice(from), next];
+      }
+      if (state === WHITE) {
+        const found = visit(next);
+        if (found) return found;
+      }
+    }
+    stack.pop();
+    color.set(node, BLACK);
+    return null;
+  };
+
+  for (const id of ids) {
+    if ((color.get(id) ?? WHITE) === WHITE) {
+      const found = visit(id);
+      if (found) return found;
+    }
+  }
+  return null;
+}