@taodigital/app-brain 0.0.0-stage → 1.2.1

package/src/nav-graph.ts

@@ -0,0 +1,295 @@
+import { withTenant, Prisma } from '@taodigital/database';
+
+export interface NavGraphNode {
+  id: string;
+  name: string;
+  url: string | null;
+  section: string;     // Screen group name or classified section
+  sectionColor?: string | null;
+  groupId?: string | null;
+  depth: number | null;
+  entryPoint: boolean;
+  discoveryMethod: string;
+}
+
+export interface NavGraphEdge {
+  id: string;
+  fromScreenId: string;
+  toScreenId: string | null;
+  href: string;
+  text: string | null;
+  landmark: string | null;
+  linkType: string;
+  source: string;
+  confidence: number;
+  isBackEdge: boolean;
+}
+
+export interface NavGraph {
+  nodes: NavGraphNode[];
+  edges: NavGraphEdge[];
+  entryPoints: string[];   // screen IDs
+  orphans: string[];       // screen IDs with no inbound edges
+  sections: Record<string, string[]>; // section -> [screenId]
+  sectionColors?: Record<string, string>; // section -> color
+  stats: {
+    totalNodes: number;
+    totalEdges: number;
+    maxDepth: number | null;
+    sections: string[];
+  };
+}
+
+function classifySection(url: string | null, name: string): string {
+  const text = (url ?? name).toLowerCase();
+  if (/\/(login|signin|sign-in|register|signup|sign-up|auth|forgot|reset|verify|otp|mfa|sso)/.test(text)) return 'Authentication';
+  if (/\/(admin|administration|manage|management|superuser)/.test(text)) return 'Administration';
+  if (/\/(settings|preferences|profile|account|config|configuration)/.test(text)) return 'Settings';
+  if (/\/(dashboard|home|overview|summary|analytics|reports|metrics)/.test(text)) return 'Dashboard';
+  if (/\/(checkout|cart|basket|payment|order-review|billing)/.test(text)) return 'Checkout';
+  if (/\/(product|products|item|items|catalog|shop|store|collection)/.test(text)) return 'Catalog';
+  if (/\/(order|orders|history|purchases)/.test(text)) return 'Orders';
+  if (/\/(user|users|member|members|team|customers)/.test(text)) return 'Users';
+
+  // Extract primary URL path segment if available (e.g. /inventory -> Inventory)
+  if (url) {
+    try {
+      const parsed = new URL(url.startsWith('http') ? url : `https://example.com${url.startsWith('/') ? '' : '/'}${url}`);
+      const segments = parsed.pathname.split('/').filter(Boolean);
+      if (segments.length > 0) {
+        const seg = segments[0].replace(/[^a-zA-Z0-9_-]/g, '');
+        if (seg.length > 1 && !/^[0-9a-f-]{8,}$/i.test(seg)) {
+          return seg.charAt(0).toUpperCase() + seg.slice(1).replace(/[-_]/g, ' ');
+        }
+      }
+    } catch {}
+  }
+  return 'Application';
+}
+
+export async function buildNavigationGraph(
+  tenantId: string,
+  projectId: string,
+  opts: { jobId?: string; maxDepth?: number } = {},
+): Promise<NavGraph> {
+  return withTenant(tenantId, async (tx: Prisma.TransactionClient) => {
+    const [screens, screenGroups] = await Promise.all([
+      (tx as any).screen.findMany({
+        where: { tenantId, projectId, status: 'ACTIVE' },
+        select: {
+          id: true,
+          name: true,
+          url: true,
+          depth: true,
+          discoveryMethod: true,
+          groupId: true,
+          group: { select: { id: true, name: true, slug: true, color: true } },
+        },
+      }),
+      (tx as any).screenGroup.findMany({
+        where: { tenantId, projectId },
+        orderBy: { order: 'asc' },
+        include: {
+          screens: {
+            where: { status: 'ACTIVE' },
+            select: { id: true, name: true, url: true },
+          },
+        },
+      }),
+    ]);
+
+    const linksWhere: any = { tenantId, projectId };
+    if (opts.jobId) linksWhere.jobId = opts.jobId;
+    const links = await (tx as any).discoveredLink.findMany({
+      where: linksWhere,
+      select: {
+        id: true,
+        fromScreenId: true,
+        toScreenId: true,
+        href: true,
+        text: true,
+        landmark: true,
+        linkType: true,
+        source: true,
+        confidence: true,
+      },
+    });
+
+    const screenIds = new Set(screens.map((s: any) => s.id));
+    const inboundCount = new Map<string, number>();
+    for (const s of screens) inboundCount.set(s.id, 0);
+    for (const l of links) {
+      if (l.toScreenId && screenIds.has(l.toScreenId)) {
+        inboundCount.set(l.toScreenId, (inboundCount.get(l.toScreenId) ?? 0) + 1);
+      }
+    }
+
+    // Build screen-to-group map and section colors
+    const screenToGroupMap = new Map<string, { id: string; name: string; color: string }>();
+    const sectionColors: Record<string, string> = {};
+
+    for (const g of screenGroups) {
+      if (g.name && g.color) {
+        sectionColors[g.name] = g.color;
+      }
+      for (const sc of (g.screens ?? [])) {
+        screenToGroupMap.set(sc.id, { id: g.id, name: g.name, color: g.color });
+      }
+    }
+
+    // Compute BFS depth from entry points via discovered link edges
+    const adjacency = new Map<string, string[]>(); // fromScreenId -> [toScreenId]
+    for (const l of links) {
+      if (!l.toScreenId) continue;
+      if (!adjacency.has(l.fromScreenId)) adjacency.set(l.fromScreenId, []);
+      adjacency.get(l.fromScreenId)!.push(l.toScreenId);
+    }
+    const depths = new Map<string, number>();
+    const entryIds = screens
+      .filter((s: any) => s.discoveryMethod === 'ENTRY_POINT' || s.discoveryMethod === 'SEED_URL')
+      .map((s: any) => s.id);
+    const bfsQueue: string[] = [...entryIds];
+    for (const id of entryIds) depths.set(id, 0);
+    while (bfsQueue.length > 0) {
+      const cur = bfsQueue.shift()!;
+      const curDepth = depths.get(cur)!;
+      for (const next of (adjacency.get(cur) ?? [])) {
+        if (!depths.has(next)) {
+          depths.set(next, curDepth + 1);
+          bfsQueue.push(next);
+        }
+      }
+    }
+
+    const nodes: NavGraphNode[] = screens.map((s: any) => {
+      const assignedGroup = s.group ?? screenToGroupMap.get(s.id);
+      let section = assignedGroup?.name;
+      let sectionColor = assignedGroup?.color ?? null;
+
+      if (!section && screenGroups.length > 0) {
+        const text = `${s.url ?? ''} ${s.name ?? ''}`.toLowerCase();
+        const matched = screenGroups.find((g: any) =>
+          (g.slug && text.includes(g.slug.toLowerCase())) ||
+          (g.name && text.includes(g.name.toLowerCase()))
+        );
+        if (matched) {
+          section = matched.name;
+          sectionColor = matched.color;
+        }
+      }
+
+      if (!section) {
+        section = classifySection(s.url, s.name);
+      }
+
+      return {
+        id: s.id,
+        name: s.name,
+        url: s.url ?? null,
+        section,
+        sectionColor,
+        groupId: assignedGroup?.id ?? s.groupId ?? null,
+        depth: depths.get(s.id) ?? s.depth ?? null,
+        entryPoint: s.discoveryMethod === 'ENTRY_POINT' || s.discoveryMethod === 'SEED_URL',
+        discoveryMethod: s.discoveryMethod,
+      };
+    });
+
+    // Detect back-edges: edge goes to a node with lower or equal depth
+    const edges: NavGraphEdge[] = links.map((l: any) => {
+      const fromDepth = depths.get(l.fromScreenId) ?? null;
+      const toDepth = l.toScreenId ? (depths.get(l.toScreenId) ?? null) : null;
+      const isBackEdge = fromDepth !== null && toDepth !== null && toDepth <= fromDepth;
+      return {
+        id: l.id,
+        fromScreenId: l.fromScreenId,
+        toScreenId: l.toScreenId ?? null,
+        href: l.href,
+        text: l.text ?? null,
+        landmark: l.landmark ?? null,
+        linkType: l.linkType,
+        source: l.source,
+        confidence: l.confidence,
+        isBackEdge,
+      };
+    });
+
+    const entryPoints = nodes.filter((n) => n.entryPoint).map((n) => n.id);
+    const orphans = nodes
+      .filter((n) => !n.entryPoint && (inboundCount.get(n.id) ?? 0) === 0)
+      .map((n) => n.id);
+
+    const sectionMap: Record<string, string[]> = {};
+    for (const node of nodes) {
+      if (!sectionMap[node.section]) sectionMap[node.section] = [];
+      sectionMap[node.section]!.push(node.id);
+    }
+    // Ensure all discovered screen groups with matching screens are reflected in sectionMap
+    for (const g of screenGroups) {
+      if (g.name && !sectionMap[g.name] && (g.screens?.length ?? 0) > 0) {
+        const matchingIds = g.screens.map((sc: any) => sc.id).filter((id: string) => screenIds.has(id));
+        if (matchingIds.length > 0) {
+          sectionMap[g.name] = matchingIds;
+        }
+      }
+    }
+
+    const depths2 = nodes.map((n) => n.depth).filter((d): d is number => d !== null);
+    const maxDepth = depths2.length > 0 ? Math.max(...depths2) : null;
+
+    return {
+      nodes,
+      edges,
+      entryPoints,
+      orphans,
+      sections: sectionMap,
+      sectionColors,
+      stats: {
+        totalNodes: nodes.length,
+        totalEdges: edges.length,
+        maxDepth,
+        sections: Object.keys(sectionMap),
+      },
+    };
+  });
+}
+
+export function toMermaid(graph: NavGraph): string {
+  const lines: string[] = ['flowchart TD'];
+
+  // Group nodes by section as subgraphs
+  const sectionLabels: Record<string, string> = {
+    auth: 'Authentication',
+    dashboard: 'Dashboard',
+    settings: 'Settings',
+    admin: 'Admin',
+    app: 'Application',
+  };
+
+  for (const [section, nodeIds] of Object.entries(graph.sections)) {
+    if (!nodeIds.length) continue;
+    const subId = section.replace(/[^a-zA-Z0-9_]/g, '_') || 'sec';
+    lines.push(`  subgraph ${subId}["${sanitizeMermaid(sectionLabels[section] ?? section)}"]`);
+    for (const nodeId of nodeIds) {
+      const node = graph.nodes.find((n) => n.id === nodeId);
+      if (!node) continue;
+      const shape = node.entryPoint ? `([${sanitizeMermaid(node.name)}])` : `[${sanitizeMermaid(node.name)}]`;
+      lines.push(`    ${nodeId}${shape}`);
+    }
+    lines.push('  end');
+  }
+
+  // Edges
+  for (const edge of graph.edges) {
+    if (!edge.toScreenId) continue;
+    const label = edge.text ? `|"${sanitizeMermaid(edge.text.slice(0, 30))}"| ` : '';
+    const arrow = edge.isBackEdge ? '-.->' : '-->';
+    lines.push(`  ${edge.fromScreenId} ${arrow} ${label}${edge.toScreenId}`);
+  }
+
+  return lines.join('\n');
+}
+
+function sanitizeMermaid(s: string): string {
+  return s.replace(/["[\](){}|>]/g, ' ').trim();
+}

package/src/notifications.ts

@@ -0,0 +1,156 @@
+import crypto from 'node:crypto';
+import { withTenant } from '@taodigital/database';
+import { sendEmail } from './email.js';
+
+export type NotificationEvent =
+  | 'invite.created'
+  | 'invite.received'
+  | 'crawl.done'
+  | 'crawl.failed'
+  | 'test.generated'
+  | 'test.run.done'
+  | 'test.run.failed'
+  | 'review.assigned'
+  | 'token.budget.alert'
+  | string;
+
+export interface DispatchOptions {
+  tenantId: string;
+  userId: string;       // recipient
+  type: NotificationEvent;
+  title: string;
+  body: string;
+  metadata?: Record<string, unknown>;
+  /** extra email fields — only used if email pref enabled */
+  email?: {
+    recipientEmail: string;
+    recipientName?: string;
+  };
+}
+
+export interface DispatchResult {
+  emailSent: boolean;
+  emailReason?: string;
+}
+
+/** Dispatch a single notification (in-app + email if prefs allow). Fire-and-forget safe. */
+export async function dispatchNotification(opts: DispatchOptions): Promise<DispatchResult> {
+  // 1. Check user preference (default: both enabled if no row exists)
+  // Check exact eventType, or normalized (dots vs underscores, e.g. test.run.failed vs test_run_failed)
+  const eventTypesToCheck = [
+    opts.type,
+    opts.type.replace(/_/g, '.'),
+    opts.type.replace(/\./g, '_'),
+  ];
+  if (opts.type === 'invite.created') eventTypesToCheck.push('invite.received');
+  if (opts.type === 'invite.received') eventTypesToCheck.push('invite.created');
+
+  const pref = await withTenant(opts.tenantId, (tx) =>
+    tx.notificationPreference.findFirst({
+      where: {
+        userId: opts.userId,
+        tenantId: opts.tenantId,
+        eventType: { in: eventTypesToCheck },
+      },
+    })
+  ).catch(() => null);
+
+  const inAppEnabled = pref ? (pref as any).inApp : true;
+  const emailEnabled  = pref ? (pref as any).email  : true;
+
+  // 2. Create in-app notification
+  if (inAppEnabled) {
+    await withTenant(opts.tenantId, (tx) =>
+      tx.notification.create({
+        data: {
+          id: `notif_${crypto.randomUUID()}`,
+          tenantId: opts.tenantId,
+          userId:   opts.userId,
+          type:     opts.type,
+          title:    opts.title,
+          body:     opts.body,
+          metadata: opts.metadata as any,
+        },
+      })
+    ).catch(console.error);
+  }
+
+  // 3. Send email if enabled
+  if (emailEnabled) {
+    let recipientEmail = opts.email?.recipientEmail;
+    let recipientName = opts.email?.recipientName;
+
+    // Resolve user's registered email if not explicitly provided
+    if (!recipientEmail && opts.userId) {
+      const u = await withTenant(opts.tenantId, (tx) =>
+        tx.user.findUnique({
+          where: { id: opts.userId },
+          select: { email: true, name: true },
+        })
+      ).catch(() => null);
+      if (u?.email) {
+        recipientEmail = u.email;
+        recipientName = u.name ?? undefined;
+      }
+    }
+
+    if (recipientEmail) {
+      try {
+        const result = await sendEmail({
+          to:       recipientEmail,
+          name:     recipientName,
+          type:     opts.type,
+          title:    opts.title,
+          body:     opts.body,
+          metadata: opts.metadata,
+          tenantId: opts.tenantId,
+        });
+        return { emailSent: result.sent, emailReason: result.reason };
+      } catch (err: any) {
+        console.error('[notifications] sendEmail error:', err);
+        return { emailSent: false, emailReason: err?.message ?? String(err) };
+      }
+    }
+  }
+
+  return { emailSent: false, emailReason: emailEnabled ? 'No recipient email available.' : 'Recipient disabled email for this event.' };
+}
+
+/** Dispatch to all active members of a tenant (respecting each user's in-app and email preferences) */
+export async function dispatchToTenantMembers(
+  tenantId: string,
+  opts: Omit<DispatchOptions, 'tenantId' | 'userId' | 'email'>
+): Promise<void> {
+  const members = await withTenant(tenantId, (tx) =>
+    tx.membership.findMany({
+      where: { tenantId, status: 'ACTIVE' },
+      include: { user: { select: { email: true, name: true } } },
+    })
+  ).catch(() => []);
+
+  await Promise.all((members as any[]).map((m: any) =>
+    dispatchNotification({
+      ...opts,
+      tenantId,
+      userId: m.userId,
+      email: m.user?.email ? { recipientEmail: m.user.email, recipientName: m.user.name ?? undefined } : undefined,
+    })
+  ));
+}
+
+/** Dispatch to all members of a tenant (alias to dispatchToTenantMembers) */
+export async function dispatchToTenantAdmins(
+  tenantId: string,
+  opts: Omit<DispatchOptions, 'tenantId' | 'userId' | 'email'>
+): Promise<void> {
+  return dispatchToTenantMembers(tenantId, opts);
+}
+
+/** Dispatch to all project members */
+export async function dispatchToProjectMembers(
+  tenantId: string,
+  _projectId: string,
+  opts: Omit<DispatchOptions, 'tenantId' | 'userId' | 'email'>
+): Promise<void> {
+  return dispatchToTenantMembers(tenantId, opts);
+}

package/src/orphan-classification.test.ts

@@ -0,0 +1,61 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { classifyScreen, buildOrphanReport } from './orphan-classification.js';
+
+test('classifyScreen: entry point is always REACHABLE, even with zero inbound edges', () => {
+  assert.equal(classifyScreen('ENTRY_POINT', false), 'REACHABLE');
+});
+
+test('classifyScreen: any discovery method with an inbound edge is REACHABLE', () => {
+  assert.equal(classifyScreen('LINK_FOLLOW', true), 'REACHABLE');
+  assert.equal(classifyScreen('SEED_URL', true), 'REACHABLE');
+  assert.equal(classifyScreen('SKYVERN_AI', true), 'REACHABLE');
+});
+
+test('classifyScreen: link-followed with no inbound edge is a GRAPH_ORPHAN', () => {
+  assert.equal(classifyScreen('LINK_FOLLOW', false), 'GRAPH_ORPHAN');
+});
+
+test('classifyScreen: seed URL with no inbound edge is a SITEMAP_ORPHAN', () => {
+  assert.equal(classifyScreen('SEED_URL', false), 'SITEMAP_ORPHAN');
+});
+
+test('classifyScreen: Skyvern-discovered with no inbound edge is UNVERIFIED_ORPHAN', () => {
+  assert.equal(classifyScreen('SKYVERN_AI', false), 'UNVERIFIED_ORPHAN');
+});
+
+test('buildOrphanReport: aggregates counts and percent correctly', () => {
+  const screens = [
+    { id: 's1', name: 'Home', url: '/', discoveryMethod: 'ENTRY_POINT' },
+    { id: 's2', name: 'Dashboard', url: '/dashboard', discoveryMethod: 'LINK_FOLLOW' },
+    { id: 's3', name: 'Old Promo', url: '/promo-2023', discoveryMethod: 'LINK_FOLLOW' },
+    { id: 's4', name: 'Legal', url: '/legal', discoveryMethod: 'SEED_URL' },
+  ];
+  // s2 has an inbound edge (from Home); s1's entry-point status makes it reachable
+  // regardless; s3 and s4 have none.
+  const report = buildOrphanReport(screens, new Set(['s2']));
+
+  assert.equal(report.totalScreens, 4);
+  assert.equal(report.reachableCount, 2);
+  assert.equal(report.orphanCount, 2);
+  assert.equal(report.orphanPercent, 50);
+
+  const byId = Object.fromEntries(report.screens.map((s) => [s.id, s.classification]));
+  assert.equal(byId.s1, 'REACHABLE');
+  assert.equal(byId.s2, 'REACHABLE');
+  assert.equal(byId.s3, 'GRAPH_ORPHAN');
+  assert.equal(byId.s4, 'SITEMAP_ORPHAN');
+});
+
+test('buildOrphanReport: zero screens produces a zero-percent report, not NaN/division-by-zero', () => {
+  const report = buildOrphanReport([], new Set());
+  assert.equal(report.totalScreens, 0);
+  assert.equal(report.orphanPercent, 0);
+});
+
+test('buildOrphanReport: all screens reachable gives 0% orphan rate', () => {
+  const screens = [{ id: 's1', name: 'Home', url: '/', discoveryMethod: 'ENTRY_POINT' }];
+  const report = buildOrphanReport(screens, new Set());
+  assert.equal(report.orphanPercent, 0);
+  assert.equal(report.orphanCount, 0);
+});

package/src/orphan-classification.ts

@@ -0,0 +1,65 @@
+/**
+ * Orphan-page classification — pure logic, no I/O, so it's unit-testable in
+ * isolation. See docs/research/25-orphan-page-detection-industry-comparison.md
+ * for the industry comparison and design rationale this implements.
+ */
+
+export type DiscoveryMethod = 'ENTRY_POINT' | 'LINK_FOLLOW' | 'SEED_URL' | 'SKYVERN_AI';
+
+export type OrphanClassification =
+  | 'REACHABLE'          // has an inbound KAG edge, or is the crawl's own entry point
+  | 'GRAPH_ORPHAN'       // discovered via a followed link, but nothing currently links to it
+                         // (usually a stale/removed nav item, or a canonical-URL match miss)
+  | 'SITEMAP_ORPHAN'     // discovered only because it was a configured seed URL — a true
+                         // SEO-style orphan: known to exist, unreachable by navigation
+  | 'UNVERIFIED_ORPHAN'; // discovered via Skyvern AI/vision navigation, not a DOM link —
+                         // less trustworthy until KAG link-wiring covers that path too
+
+/** Classifies a single screen given its discovery method and whether the KAG graph
+ *  has at least one inbound Element.transitionsToScreenId edge pointing to it. */
+export function classifyScreen(discoveryMethod: string, hasInboundEdge: boolean): OrphanClassification {
+  if (discoveryMethod === 'ENTRY_POINT' || hasInboundEdge) return 'REACHABLE';
+  if (discoveryMethod === 'SEED_URL') return 'SITEMAP_ORPHAN';
+  if (discoveryMethod === 'SKYVERN_AI') return 'UNVERIFIED_ORPHAN';
+  return 'GRAPH_ORPHAN';
+}
+
+export interface OrphanScreenResult {
+  id: string;
+  name: string;
+  url: string | null;
+  discoveryMethod: string;
+  classification: OrphanClassification;
+}
+
+export interface OrphanReport {
+  screens: OrphanScreenResult[];
+  totalScreens: number;
+  reachableCount: number;
+  orphanCount: number;
+  /** orphanCount / totalScreens as a percentage, 0 when there are no screens at all. */
+  orphanPercent: number;
+}
+
+/** Builds the full per-project orphan report from raw screen + inbound-edge data. */
+export function buildOrphanReport(
+  screens: Array<{ id: string; name: string; url: string | null; discoveryMethod: string }>,
+  screenIdsWithInboundEdge: Set<string>,
+): OrphanReport {
+  const classified = screens.map((s) => ({
+    id: s.id,
+    name: s.name,
+    url: s.url,
+    discoveryMethod: s.discoveryMethod,
+    classification: classifyScreen(s.discoveryMethod, screenIdsWithInboundEdge.has(s.id)),
+  }));
+  const reachableCount = classified.filter((s) => s.classification === 'REACHABLE').length;
+  const orphanCount = classified.length - reachableCount;
+  return {
+    screens: classified,
+    totalScreens: classified.length,
+    reachableCount,
+    orphanCount,
+    orphanPercent: classified.length > 0 ? Math.round((orphanCount / classified.length) * 1000) / 10 : 0,
+  };
+}

package/src/orphan-screens.test.ts

@@ -0,0 +1,88 @@
+import crypto from 'node:crypto';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { prisma, withTenant } from '@taodigital/database';
+import { AppBrain } from './repository.js';
+
+function id(prefix: string) {
+  return `${prefix}_${crypto.randomUUID()}`;
+}
+
+async function makeFixtureProject() {
+  const tenantId = id('tenant');
+  const projectId = id('project');
+  await prisma.$transaction(async (tx) => {
+    await tx.$executeRawUnsafe(`SELECT set_config('app.current_tenant', $1, true)`, tenantId);
+    await tx.tenant.create({ data: { id: tenantId, name: 'Orphan Screens Test Tenant', slug: tenantId, isolation: 'SHARED', region: 'US' } });
+    await tx.project.create({ data: { id: projectId, tenantId, name: 'Orphan Screens Test Project' } });
+  });
+  return { tenantId, projectId };
+}
+
+async function makeScreen(tenantId: string, projectId: string, name: string, discoveryMethod: string) {
+  return withTenant(tenantId, (tx) =>
+    (tx as any).screen.create({
+      data: { id: id('screen'), tenantId, projectId, name, url: `https://example.com/${name}`, discoveryMethod },
+    })
+  );
+}
+
+async function makeLinkElement(tenantId: string, projectId: string, screenId: string, meaning: string, transitionsToScreenId: string) {
+  return withTenant(tenantId, (tx) =>
+    (tx as any).element.create({
+      data: { id: id('el'), tenantId, projectId, screenId, meaning, role: 'LINK', isInteractive: true, transitionsToScreenId },
+    })
+  );
+}
+
+test('getOrphanScreens: end-to-end classification against real data', async () => {
+  const { tenantId, projectId } = await makeFixtureProject();
+
+  const home = await makeScreen(tenantId, projectId, 'home', 'ENTRY_POINT');
+  const dashboard = await makeScreen(tenantId, projectId, 'dashboard', 'LINK_FOLLOW');
+  const oldPromo = await makeScreen(tenantId, projectId, 'old-promo', 'LINK_FOLLOW'); // no inbound link -> GRAPH_ORPHAN
+  const legalSeed = await makeScreen(tenantId, projectId, 'legal', 'SEED_URL'); // no inbound link -> SITEMAP_ORPHAN
+  const skyvernPage = await makeScreen(tenantId, projectId, 'skyvern-found', 'SKYVERN_AI'); // no inbound -> UNVERIFIED_ORPHAN
+
+  // Home links to Dashboard — the only real inbound edge in this fixture.
+  await makeLinkElement(tenantId, projectId, home.id, 'Go to dashboard', dashboard.id);
+
+  const report = await AppBrain.getOrphanScreens(tenantId, projectId);
+
+  assert.equal(report.totalScreens, 5);
+  assert.equal(report.reachableCount, 2); // home (entry) + dashboard (inbound edge)
+  assert.equal(report.orphanCount, 3);
+
+  const byId = Object.fromEntries(report.screens.map((s: any) => [s.id, s.classification]));
+  assert.equal(byId[home.id], 'REACHABLE');
+  assert.equal(byId[dashboard.id], 'REACHABLE');
+  assert.equal(byId[oldPromo.id], 'GRAPH_ORPHAN');
+  assert.equal(byId[legalSeed.id], 'SITEMAP_ORPHAN');
+  assert.equal(byId[skyvernPage.id], 'UNVERIFIED_ORPHAN');
+});
+
+test('getOrphanScreens: PENDING_REMOVAL screens are excluded entirely (stale, not orphaned)', async () => {
+  const { tenantId, projectId } = await makeFixtureProject();
+  const active = await makeScreen(tenantId, projectId, 'active-page', 'LINK_FOLLOW');
+  const removed = await makeScreen(tenantId, projectId, 'removed-page', 'LINK_FOLLOW');
+  await withTenant(tenantId, (tx) => (tx as any).screen.update({ where: { id: removed.id }, data: { status: 'PENDING_REMOVAL' } }));
+
+  const report = await AppBrain.getOrphanScreens(tenantId, projectId);
+  const ids = report.screens.map((s: any) => s.id);
+  assert.ok(ids.includes(active.id));
+  assert.ok(!ids.includes(removed.id));
+});
+
+test('saveScreen: discoveryMethod is set on create and preserved (not overwritten) on re-crawl update', async () => {
+  const { tenantId, projectId } = await makeFixtureProject();
+  const url = 'https://example.com/preserved';
+  const created = await AppBrain.saveScreen(tenantId, projectId, 'Preserved', url, undefined, 'SEED_URL');
+  assert.equal((created as any).discoveryMethod, 'SEED_URL');
+
+  // Re-crawl the same URL without passing a discoveryMethod (matches how the crawler's
+  // update path never re-specifies it) — must NOT reset to the LINK_FOLLOW default.
+  const updated = await AppBrain.saveScreen(tenantId, projectId, 'Preserved', url);
+  assert.equal((updated as any).version, 2);
+  const refetched = await withTenant(tenantId, (tx) => (tx as any).screen.findUnique({ where: { id: (created as any).id } }));
+  assert.equal(refetched.discoveryMethod, 'SEED_URL');
+});