@taodigital/app-brain 0.0.0-stage → 1.2.1

package/src/run-notifications.ts

@@ -0,0 +1,281 @@
+import { dispatchWebhook, sendSlackTestRunNotification } from '@taodigital/core';
+import { AppBrain } from './repository.js';
+import { dispatchNotification, dispatchToTenantAdmins } from './notifications.js';
+import { sendEmail } from './email.js';
+
+/**
+ * Single, reliable trigger point for everything that should happen when a
+ * TestRun finishes: admin in-app/email notification, generic webhook,
+ * suite-owner failure emails, GitHub check-run, Slack, Teams. Call this from
+ * wherever completeTestRun()/failTestRun() is actually called — for both the
+ * interactive web-driven flow (packages/api/src/routes/runs.ts) and the
+ * CI-triggered worker flow (packages/crawler/src/job-queue.ts's
+ * processRunTestSuiteJob) — NOT from the SSE stream's polling loop, which
+ * only runs while a browser has that run's page open and would otherwise
+ * silently drop notifications for any run that completes with nobody
+ * watching (the common case for CI-triggered runs).
+ */
+export async function notifyRunCompletion(
+  tenantId: string,
+  projectId: string,
+  runId: string,
+  status: 'COMPLETED' | 'FAILED',
+  summary: Record<string, any>,
+  results: Array<{ testCaseId: string; status: string }> = [],
+) {
+  const runEvent = status === 'COMPLETED' ? 'test.run.done' : 'test.run.failed';
+  dispatchToTenantAdmins(tenantId, {
+    type: runEvent,
+    title: status === 'COMPLETED' ? 'Test run completed' : 'Test run failed',
+    body: status === 'COMPLETED'
+      ? `Test run finished. Check results in the dashboard.`
+      : `Test run failed. Review logs for details.`,
+    metadata: { runId },
+  }).catch(console.error);
+  dispatchWebhook(tenantId, projectId, runEvent, {
+    runId,
+    passed: summary.passed ?? 0,
+    failed: summary.failed ?? 0,
+    total: summary.total ?? 0,
+  }).catch(console.error);
+  notifySuiteOwners(tenantId, runId, results).catch(() => {});
+  postGitHubCheckRun(tenantId, projectId, runId, status, summary).catch(() => {});
+  postSlackTestRunResult(tenantId, projectId, runId, status, summary).catch(() => {});
+  postTeamsNotification(tenantId, projectId, runId, status, summary).catch(() => {});
+  if (status === 'FAILED') notifyAlertEmails(tenantId, runId, summary).catch(() => {});
+}
+
+// Workspace Settings > Notifications > Alert Emails — arbitrary external addresses
+// with no User row, so this bypasses dispatchToTenantAdmins/NotificationPreference
+// (which require one) and calls the mailer directly, one send per address. Only
+// fires on FAILED, matching that field's own UI copy ("notify when critical errors
+// occur") — a passing run isn't the kind of thing this list exists to catch.
+async function notifyAlertEmails(tenantId: string, runId: string, summary: Record<string, any>) {
+  const cfg = await AppBrain.getTenantNotificationsConfig(tenantId).catch(() => null);
+  const emails = cfg?.alertEmails ?? [];
+  if (emails.length === 0) return;
+
+  const failed = summary.failed ?? 0;
+  const total = summary.total ?? 0;
+  await Promise.all(emails.map((to) => sendEmail({
+    to,
+    type: 'test_run_failed',
+    title: `${process.env.EMAIL_BRAND_NAME ?? 'ZeTa-AI'} test run failed`,
+    body: `A test run failed: ${failed}/${total} test cases failed. Run ID: ${runId}.`,
+    metadata: { runId, tenantId },
+    tenantId,
+  }).catch(() => {})));
+}
+
+async function notifySuiteOwners(
+  tenantId: string,
+  runId: string,
+  results: Array<{ testCaseId: string; status: string }>,
+) {
+  const failedCaseIds = [...new Set(
+    results.filter(r => r.status === 'FAILED' || r.status === 'FLAKY').map(r => r.testCaseId)
+  )];
+  if (!failedCaseIds.length) return;
+
+  const { prisma } = await import('@taodigital/database');
+
+  const cases = await prisma.testCase.findMany({
+    where: { id: { in: failedCaseIds }, tenantId },
+    select: { suiteId: true },
+  });
+  const suiteIds = [...new Set((cases as any[]).map((c: any) => c.suiteId))];
+
+  const suites = await prisma.testSuite.findMany({
+    where: { id: { in: suiteIds }, tenantId, ownerUserId: { not: null } },
+    select: { id: true, name: true, ownerUserId: true },
+  });
+
+  // Batch-load all suite owners in one query instead of N+1 per suite
+  const ownerIds = (suites as any[]).map((s: any) => s.ownerUserId).filter(Boolean) as string[];
+  const owners = ownerIds.length > 0
+    ? await prisma.user.findMany({
+        where: { id: { in: ownerIds } },
+        select: { id: true, email: true, name: true },
+      }).catch(() => [] as { id: string; email: string; name: string | null }[])
+    : [];
+  const ownerMap = new Map((owners as any[]).map((u: any) => [u.id, u]));
+
+  await Promise.all((suites as any[]).map(async (suite: any) => {
+    if (!suite.ownerUserId) return;
+    const user = ownerMap.get(suite.ownerUserId) ?? null;
+    dispatchNotification({
+      tenantId,
+      userId: suite.ownerUserId,
+      type: 'test.run.failed',
+      title: `Test failures in suite "${suite.name}"`,
+      body: `Tests you own in "${suite.name}" have failures. Run ID: ${runId}`,
+      metadata: { runId, suiteId: suite.id },
+      ...(user ? { email: { recipientEmail: (user as any).email, recipientName: (user as any).name ?? undefined } } : {}),
+    }).catch(console.error);
+  }));
+}
+
+async function postGitHubCheckRun(
+  tenantId: string,
+  projectId: string,
+  runId: string,
+  status: 'COMPLETED' | 'FAILED',
+  summary: Record<string, any>,
+) {
+  try {
+    // Only post if GitHub connector with repo is configured
+    const { withTenant } = await import('@taodigital/database');
+    const connector = await withTenant(tenantId, (tx) =>
+      tx.connector.findFirst({ where: { tenantId, projectId, kind: 'GITHUB' } })
+    );
+    if (!connector) return;
+
+    const { decrypt } = await import('@taodigital/core');
+    const cfg = (connector as any).config as Record<string, any> ?? {};
+    const token = cfg.token_enc ? decrypt(cfg.token_enc) : '';
+    const repo = cfg.repo as string | undefined;
+    if (!token || !repo) return;
+
+    // Get the project's default branch and latest commit SHA
+    const repoRes = await fetch(`https://api.github.com/repos/${repo}`, {
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json' },
+    });
+    if (!repoRes.ok) return;
+    const repoData = await repoRes.json() as { default_branch: string };
+    const branchRes = await fetch(`https://api.github.com/repos/${repo}/branches/${repoData.default_branch}`, {
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json' },
+    });
+    if (!branchRes.ok) return;
+    const branchData = await branchRes.json() as { commit: { sha: string } };
+
+    const conclusion = status === 'COMPLETED' ? 'success' : 'failure';
+    const passed = summary.passed ?? 0;
+    const failed = summary.failed ?? 0;
+    const total = summary.total ?? 0;
+
+    await fetch(`https://api.github.com/repos/${repo}/check-runs`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        name: 'ZeTa Test Run',
+        head_sha: branchData.commit.sha,
+        status: 'completed',
+        conclusion,
+        completed_at: new Date().toISOString(),
+        output: {
+          title: conclusion === 'success' ? `${passed}/${total} tests passed` : `${failed} test(s) failed`,
+          summary: `**Passed:** ${passed} | **Failed:** ${failed} | **Total:** ${total}\n\nRun ID: \`${runId}\``,
+        },
+      }),
+    });
+  } catch { /* fire-and-forget, never block the run */ }
+}
+
+async function postSlackTestRunResult(
+  tenantId: string,
+  projectId: string,
+  runId: string,
+  status: 'COMPLETED' | 'FAILED',
+  summary: Record<string, any>,
+) {
+  try {
+    const passed = summary.passed ?? 0;
+    const failed = summary.failed ?? 0;
+    const total = summary.total ?? 0;
+    const slackStatus = status === 'COMPLETED' && failed === 0 ? 'PASS' : 'FAIL';
+
+    // Resolve the human-readable project name for the notification.
+    const { withTenant } = await import('@taodigital/database');
+    const project = await withTenant(tenantId, (tx) =>
+      tx.project.findUnique({ where: { id: projectId }, select: { name: true } })
+    ).catch(() => null);
+    const projectName = (project as any)?.name ?? projectId;
+
+    const webBase = process.env.NEXT_PUBLIC_WEB_URL || 'http://localhost:3000';
+    const resultsUrl = `${webBase}/projects/${projectId}/runs/${runId}`;
+
+    await sendSlackTestRunNotification(tenantId, {
+      projectName,
+      runId,
+      status: slackStatus,
+      passed,
+      failed,
+      total,
+      resultsUrl,
+    });
+  } catch { /* fire-and-forget */ }
+}
+
+async function postTeamsNotification(
+  tenantId: string,
+  projectId: string,
+  runId: string,
+  status: 'COMPLETED' | 'FAILED',
+  summary: Record<string, any>,
+) {
+  try {
+    const connector = await AppBrain.getWorkspaceConnector(tenantId, 'TEAMS');
+    if (!connector?.config?.webhookUrl) return;
+
+    const passed = summary.passed ?? 0;
+    const failed = summary.failed ?? 0;
+    const total = summary.total ?? 0;
+    const ok = status === 'COMPLETED' && failed === 0;
+    const color = ok ? '00c853' : 'f44336';
+    const title = ok ? '✅ ZeTa: All tests passed' : '❌ ZeTa: Test run failed';
+
+    const payload = {
+      type: 'message',
+      attachments: [{
+        contentType: 'application/vnd.microsoft.card.adaptive',
+        content: {
+          type: 'AdaptiveCard',
+          version: '1.4',
+          body: [
+            { type: 'TextBlock', text: title, weight: 'Bolder', size: 'Medium', color: ok ? 'Good' : 'Attention' },
+            {
+              type: 'FactSet',
+              facts: [
+                { title: 'Passed', value: String(passed) },
+                { title: 'Failed', value: String(failed) },
+                { title: 'Total', value: String(total) },
+                { title: 'Project', value: projectId },
+              ],
+            },
+          ],
+          ...(connector.config.baseUrl ? {
+            actions: [{
+              type: 'Action.OpenUrl',
+              title: 'View Run',
+              url: `${connector.config.baseUrl}/projects/${projectId}/sessions`,
+            }],
+          } : {}),
+        },
+      }],
+    };
+
+    const { assertResolvesToPublicAddress } = await import('@taodigital/core');
+    await assertResolvesToPublicAddress(connector.config.webhookUrl);
+    // redirect:'manual' — same SSRF-bypass concern as postSlackNotification above.
+    // Retry with exponential backoff on transient failures (429, 5xx).
+    let lastErr: unknown;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (attempt > 0) await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt - 1)));
+      try {
+        const res = await fetch(connector.config.webhookUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(payload),
+          redirect: 'manual',
+        });
+        if (res.ok || (res.status >= 400 && res.status < 500 && res.status !== 429)) break;
+        lastErr = new Error(`HTTP ${res.status}`);
+      } catch (err) { lastErr = err; }
+    }
+    void lastErr; // fire-and-forget — log absorbed above
+  } catch { /* fire-and-forget */ }
+}

package/src/skill-file-kinds.ts

@@ -0,0 +1,51 @@
+/** Single source of truth for SkillFile kind classifications. */
+
+export const SKILL_FILE_GLOBAL_KINDS: string[] = [
+  // Platform intelligence (crawl-generated)
+  'TECH_STACK', 'AUTH_SESSION', 'BUSINESS_DOMAIN', 'DATA_MODEL',
+  'INTERACTION_PATTERNS', 'ERROR_CATALOGUE', 'API_CONTRACT',
+  'LOCATOR_STRATEGY', 'PERFORMANCE_BASELINE',
+  // Repo intelligence (repo-scan-generated)
+  'REPO_TEST_FRAMEWORK', 'REPO_CODING_CONVENTIONS', 'REPO_PAGE_OBJECTS', 'REPO_TEST_FILE_STRUCTURE',
+  // Framework standards (Zeta-specific)
+  'ZETA_FRAMEWORK_STANDARD', 'ZETA_FRAMEWORK_SELENIUM_JAVA',
+  // Testing intelligence (post-generation)
+  'COVERAGE_MATRIX', 'TEST_CASES', 'TEST_CASE', 'TEST_DATA', 'TEST_SCRIPT',
+  'REQUIREMENTS', 'REQUIREMENTS_FUNCTIONAL', 'REQUIREMENTS_NONFUNCTIONAL',
+  'REQUIREMENTS_SECURITY', 'REQUIREMENTS_BUSINESS_RULES',
+  'REQUIREMENTS_ACCEPTANCE_CRITERIA', 'REQUIREMENTS_TRACEABILITY',
+  'REQUIREMENTS_WORKFLOWS', 'REQUIREMENTS_ROLES_PERMISSIONS',
+  'REQUIREMENTS_DATA_RULES', 'REQUIREMENTS_INTEGRATIONS',
+  'REQUIREMENTS_COMPLIANCE_AUDIT', 'REQUIREMENTS_ACCESSIBILITY',
+  'REQUIREMENTS_PERFORMANCE',
+  'REQUIREMENTS_COVERAGE',
+  // Execution history
+  'TEST_EXECUTION_HISTORY', 'VISUAL_REGRESSION_HISTORY', 'FIELD_CATALOG',
+  // Healing
+  'HEALING_LOG',
+];
+
+export const SKILL_FILE_SELECTIVE_KINDS: string[] = [
+  'COMPONENT_LIBRARY', 'ELEMENT_BEHAVIORS', 'VISUAL_BASELINE', 'NAVIGATION_MAP',
+  // Per-screen structural knowledge
+  'SCREEN_UNDERSTANDING',
+  // Per-screen actual locator inventory (extracted by extractLocatorsWithLLM)
+  'LOCATOR_INVENTORY',
+];
+
+export const SKILL_FILE_SEARCH_FALLBACK_KINDS: string[] = [
+  'TECH_STACK', 'AUTH_SESSION', 'BUSINESS_DOMAIN', 'DATA_MODEL',
+  'INTERACTION_PATTERNS', 'ERROR_CATALOGUE', 'API_CONTRACT', 'REPO_TEST_FRAMEWORK',
+  'REQUIREMENTS', 'REQUIREMENTS_FUNCTIONAL', 'REQUIREMENTS_NONFUNCTIONAL',
+  'REQUIREMENTS_SECURITY', 'REQUIREMENTS_BUSINESS_RULES',
+  'REQUIREMENTS_ACCEPTANCE_CRITERIA', 'REQUIREMENTS_TRACEABILITY',
+  'REQUIREMENTS_WORKFLOWS', 'REQUIREMENTS_ROLES_PERMISSIONS',
+  'REQUIREMENTS_DATA_RULES', 'REQUIREMENTS_INTEGRATIONS',
+  'REQUIREMENTS_COMPLIANCE_AUDIT', 'REQUIREMENTS_ACCESSIBILITY',
+  'REQUIREMENTS_PERFORMANCE',
+  'REQUIREMENTS_COVERAGE',
+];
+
+export const SKILL_FILE_CROSS_PROJECT_KINDS: string[] = [
+  'ELEMENT_BEHAVIORS', 'INTERACTION_PATTERNS',
+];

package/src/token-ledger.ts

@@ -0,0 +1,209 @@
+import { withTenant } from '@taodigital/database';
+import { Prisma } from '@prisma/client';
+import type { LLMUsage } from '@taodigital/core';
+
+export class TokenBudgetExceededError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TokenBudgetExceededError';
+  }
+}
+
+function isPositiveLimit(value: number | null | undefined): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+function isNewBudgetMonth(lastResetAt: Date, now: Date): boolean {
+  return lastResetAt.getMonth() !== now.getMonth()
+      || lastResetAt.getFullYear() !== now.getFullYear();
+}
+
+function assertWithinBudget(args: {
+  monthlyTokenCap?: number | null;
+  monthlyUsdCap?: number | null;
+  currentMonthTokens: number;
+  currentMonthUsd: number;
+  additionalTokens?: number;
+  additionalUsd?: number;
+}) {
+  const nextTokens = args.currentMonthTokens + Math.max(0, Math.ceil(args.additionalTokens ?? 0));
+  const nextUsd = args.currentMonthUsd + Math.max(0, args.additionalUsd ?? 0);
+  if (isPositiveLimit(args.monthlyTokenCap) && nextTokens > args.monthlyTokenCap) {
+    throw new TokenBudgetExceededError(
+      `Monthly token budget exceeded (${nextTokens.toLocaleString()} / ${args.monthlyTokenCap.toLocaleString()} tokens). Increase the workspace budget or wait until next month.`,
+    );
+  }
+  if (isPositiveLimit(args.monthlyUsdCap) && nextUsd > args.monthlyUsdCap) {
+    throw new TokenBudgetExceededError(
+      `Monthly AI spend budget exceeded ($${nextUsd.toFixed(2)} / $${args.monthlyUsdCap.toFixed(2)}). Increase the workspace budget or wait until next month.`,
+    );
+  }
+}
+
+/** Preflight hard-stop used before starting new AI calls. */
+export async function enforceTokenBudget(tenantId: string, estimatedTokens = 0, estimatedUsd = 0) {
+  await withTenant(tenantId, async (tx) => {
+    const budget = await tx.tokenBudget.findUnique({ where: { tenantId } });
+    if (!budget) return;
+
+    const now = new Date();
+    const resetNeeded = isNewBudgetMonth(budget.lastResetAt, now);
+    const currentMonthTokens = resetNeeded ? 0 : budget.currentMonthTokens;
+    const currentMonthUsd = resetNeeded ? 0 : budget.currentMonthUsd;
+    if (resetNeeded) {
+      await tx.tokenBudget.update({
+        where: { tenantId },
+        data: { currentMonthTokens: 0, currentMonthUsd: 0, lastResetAt: now },
+      });
+    }
+
+    // Soft pre-check: fast fail if clearly over budget.
+    assertWithinBudget({
+      monthlyTokenCap: budget.monthlyTokenCap,
+      monthlyUsdCap: budget.monthlyUsdCap,
+      currentMonthTokens,
+      currentMonthUsd,
+      additionalTokens: estimatedTokens,
+      additionalUsd: estimatedUsd,
+    });
+
+    // Atomic reservation: increment only if the resulting total stays within cap.
+    // rowsAffected = 0 means a concurrent request already consumed the remaining budget.
+    const addTokens = Math.max(0, Math.ceil(estimatedTokens));
+    const addUsd = Math.max(0, estimatedUsd);
+    if (addTokens > 0 || addUsd > 0) {
+      const rowsAffected: number = isPositiveLimit(budget.monthlyTokenCap)
+        ? await tx.$executeRaw`UPDATE "TokenBudget" SET "currentMonthTokens" = "currentMonthTokens" + ${addTokens}, "currentMonthUsd" = "currentMonthUsd" + ${addUsd} WHERE "tenantId" = ${tenantId} AND "currentMonthTokens" + ${addTokens} <= ${budget.monthlyTokenCap}`
+        : await tx.$executeRaw`UPDATE "TokenBudget" SET "currentMonthTokens" = "currentMonthTokens" + ${addTokens}, "currentMonthUsd" = "currentMonthUsd" + ${addUsd} WHERE "tenantId" = ${tenantId}`;
+      if (rowsAffected === 0) {
+        throw new TokenBudgetExceededError(
+          `Monthly token budget exceeded. Increase the workspace budget or wait until next month.`,
+        );
+      }
+    }
+  });
+}
+
+
+/** Write one LLM call record. Call after every askTracked(). */
+export async function recordLLMCall(params: {
+  tenantId:    string;
+  projectId?:  string;
+  jobId?:      string;
+  agentType:   string;
+  label:       string;
+  taskType?:   string;
+  entityId?:   string;
+  entityType?: string;
+  usage:       LLMUsage;
+  latencyMs?:  number;
+}) {
+  await withTenant(params.tenantId, async (tx) => {
+    const budget = await tx.tokenBudget.findUnique({ where: { tenantId: params.tenantId } });
+    const now = new Date();
+    let resetNeeded = false;
+    if (budget) {
+      resetNeeded = isNewBudgetMonth(budget.lastResetAt, now);
+      assertWithinBudget({
+        monthlyTokenCap: budget.monthlyTokenCap,
+        monthlyUsdCap: budget.monthlyUsdCap,
+        currentMonthTokens: resetNeeded ? 0 : budget.currentMonthTokens,
+        currentMonthUsd: resetNeeded ? 0 : budget.currentMonthUsd,
+        additionalTokens: params.usage.totalTokens,
+        additionalUsd: params.usage.estimatedCostUsd,
+      });
+    }
+
+    await tx.lLMCallLog.create({
+      data: {
+        tenantId:         params.tenantId,
+        projectId:        params.projectId ?? null,
+        jobId:            params.jobId     ?? null,
+        agentType:        params.agentType,
+        label:            params.label,
+        taskType:         params.taskType  ?? null,
+        entityId:         params.entityId  ?? null,
+        entityType:       params.entityType ?? null,
+        provider:         params.usage.provider,
+        model:            params.usage.model,
+        promptTokens:     params.usage.promptTokens,
+        completionTokens: params.usage.completionTokens,
+        cacheReadTokens:  params.usage.cacheReadTokens,
+        cacheWriteTokens: params.usage.cacheWriteTokens,
+        totalTokens:      params.usage.totalTokens,
+        estimatedCostUsd: params.usage.estimatedCostUsd,
+        latencyMs:        params.latencyMs ?? null,
+      },
+    });
+
+    if (budget) {
+      await tx.tokenBudget.update({
+        where: { tenantId: params.tenantId },
+        data: {
+          currentMonthTokens: resetNeeded ? params.usage.totalTokens : { increment: params.usage.totalTokens },
+          currentMonthUsd:    resetNeeded ? params.usage.estimatedCostUsd : { increment: params.usage.estimatedCostUsd },
+          lastResetAt:        resetNeeded ? now : undefined,
+        },
+      });
+    }
+  });
+}
+
+/** Summarise token usage for a project within a date range. */
+export async function getProjectTokenSummary(tenantId: string, projectId: string, since?: Date) {
+  return withTenant(tenantId, async (tx) => {
+    const rows = since
+      ? await tx.$queryRaw<any[]>`
+          SELECT
+            "agentType",
+            SUM("promptTokens")::INT     AS "promptTokens",
+            SUM("completionTokens")::INT AS "completionTokens",
+            SUM("cacheReadTokens")::INT  AS "cacheReadTokens",
+            SUM("totalTokens")::INT      AS "totalTokens",
+            SUM("estimatedCostUsd")      AS "estimatedCostUsd",
+            COUNT(*)::INT                AS "callCount"
+          FROM "LLMCallLog"
+          WHERE "tenantId" = ${tenantId}
+            AND "projectId" = ${projectId}
+            AND "calledAt" >= ${since}
+          GROUP BY "agentType"
+          ORDER BY SUM("totalTokens") DESC`
+      : await tx.$queryRaw<any[]>`
+          SELECT
+            "agentType",
+            SUM("promptTokens")::INT     AS "promptTokens",
+            SUM("completionTokens")::INT AS "completionTokens",
+            SUM("cacheReadTokens")::INT  AS "cacheReadTokens",
+            SUM("totalTokens")::INT      AS "totalTokens",
+            SUM("estimatedCostUsd")      AS "estimatedCostUsd",
+            COUNT(*)::INT                AS "callCount"
+          FROM "LLMCallLog"
+          WHERE "tenantId" = ${tenantId}
+            AND "projectId" = ${projectId}
+          GROUP BY "agentType"
+          ORDER BY SUM("totalTokens") DESC`;
+    return rows;
+  });
+}
+
+/** Token breakdown for one job, scoped to a specific project. */
+export async function getJobTokenDetail(tenantId: string, projectId: string, jobId: string) {
+  return withTenant(tenantId, async (tx) => {
+    const rows = await tx.$queryRaw<any[]>`
+      SELECT
+        label,
+        "promptTokens",
+        "completionTokens",
+        "cacheReadTokens",
+        "estimatedCostUsd",
+        "latencyMs",
+        "calledAt"
+      FROM "LLMCallLog"
+      WHERE "tenantId" = ${tenantId}
+        AND "projectId" = ${projectId}
+        AND "jobId" = ${jobId}
+      ORDER BY "calledAt" ASC
+    `;
+    return rows;
+  });
+}

package/src/traceability.test.ts

@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  buildTraceabilityMatrix, buildAlignmentReport, linkedReqIds, matchAcceptanceCriterion,
+  traceabilityToCsv, type TraceCaseInput,
+} from './traceability.js';
+
+const mkCase = (over: Partial<TraceCaseInput>): TraceCaseInput => ({
+  id: 'tc1', ref: 'TC-1', title: 'Verify login', kind: 'POSITIVE', status: 'APPROVED', suiteId: 's1',
+  steps: ['Enter valid username and password', 'Click Login'], expectedResult: 'Dashboard is displayed',
+  preconditions: null, traceTo: null, traceToExtra: [], scenarioId: null, suspect: false, suspectReason: null, scripts: [], ...over,
+});
+
+const REQ = (reqId: string, ac: string[]) => ({
+  id: `db-${reqId}`, reqId, title: `Story ${reqId}`, priority: 'HIGH', status: 'pending', source: 'JIRA_IMPORT',
+  acceptanceCriteria: ac, externalMeta: { url: `https://jira/browse/${reqId}`, status: 'Done', labels: ['auth'] },
+});
+
+test('linkedReqIds: primary + extras, de-duplicated, placeholders removed', () => {
+  assert.deepEqual(linkedReqIds({ traceTo: 'PROJ-1', traceToExtra: ['PROJ-2', 'PROJ-1', 'REQ-UNKNOWN'] }), ['PROJ-1', 'PROJ-2']);
+  assert.deepEqual(linkedReqIds({ traceTo: 'REQ-UNKNOWN' }), []);
+});
+
+test('matchAcceptanceCriterion: matches relevant case, rejects unrelated', () => {
+  const cases = [mkCase({})];
+  assert.equal(matchAcceptanceCriterion('User can login with valid username and password', cases).covered, true);
+  assert.equal(matchAcceptanceCriterion('Invoice PDF can be downloaded and printed', cases).covered, false);
+});
+
+test('buildTraceabilityMatrix: per-AC coverage, multi-link, orphans, broken links, retired excluded', () => {
+  const m = buildTraceabilityMatrix({
+    requirements: [
+      REQ('PROJ-1', ['User can login with valid username and password', 'Invoice PDF can be downloaded and printed']),
+      REQ('PROJ-2', ['Dashboard is displayed after login']),
+      REQ('PROJ-3', ['Something nobody tests']),
+    ],
+    testCases: [
+      mkCase({ id: 'a', ref: 'TC-A', traceTo: 'PROJ-1', traceToExtra: ['PROJ-2'], suspect: true, suspectReason: 'changed',
+        scripts: [{ language: 'playwright-ts', annotated: false, aiScore: 80, aligned: true, stepCoveragePct: 100, verifiedAt: null }] }),
+      mkCase({ id: 'b', ref: 'TC-B', traceTo: 'REQ-UNKNOWN' }),
+      mkCase({ id: 'c', ref: 'TC-C', traceTo: 'PROJ-99' }),
+      mkCase({ id: 'd', ref: 'TC-D', traceTo: 'PROJ-3', status: 'RETIRED' }),
+    ],
+    scenarios: [{ id: 's1', requirementId: 'db-PROJ-1', title: 'Login happy path', status: 'approved' }],
+  });
+  const p1 = m.requirements.find((r) => r.reqId === 'PROJ-1')!;
+  assert.equal(p1.coverageState, 'partial');
+  assert.equal(p1.acCoveragePct, 50);
+  assert.equal(p1.hasSuspect, true);
+  assert.equal(p1.scenarios.length, 1);
+  assert.equal(m.requirements.find((r) => r.reqId === 'PROJ-2')!.testCases[0].linkType, 'additional');
+  assert.equal(m.requirements.find((r) => r.reqId === 'PROJ-3')!.coverageState, 'untested'); // retired test ignored
+  assert.deepEqual(m.orphans.map((o) => o.ref), ['TC-B']);
+  assert.deepEqual(m.brokenLinks.map((b) => b.reqId), ['PROJ-99']);
+  assert.equal(m.summary.scriptsMissingAnnotation, 1);
+  assert.equal(m.summary.suspectTestCases, 1);
+  assert.equal(m.summary.requirementsUntested, 1);
+  assert.match(traceabilityToCsv(m), /PROJ-1,Story PROJ-1/);
+});
+
+test('buildAlignmentReport: average, pass rate at 75, distribution, uncovered steps', () => {
+  const rep = buildAlignmentReport([
+    { testCaseId: '1', ref: 'A', title: 'a', traceTo: 'R1', language: 'playwright-ts', score: 90, aligned: true, issues: [], stepCoveragePct: 100,
+      stepCoverage: { totalSteps: 2, coveredSteps: 2, perStep: [], assertionCoverage: { pct: 100 } }, verifiedAt: null },
+    { testCaseId: '2', ref: 'B', title: 'b', traceTo: 'R1', language: 'playwright-ts', score: 50, aligned: false, issues: ['x'], stepCoveragePct: 50,
+      stepCoverage: { totalSteps: 2, coveredSteps: 1, perStep: [{ index: 2, step: 'Upload', covered: false, confidence: 0 }] }, verifiedAt: null },
+  ]);
+  assert.equal(rep.summary.avgAiScore, 70);
+  assert.equal(rep.summary.passRatePct, 50);
+  assert.equal(rep.summary.belowExportGate, 1);
+  assert.equal(rep.summary.avgStepCoveragePct, 75);
+  assert.equal(rep.rows[0].ref, 'B'); // lowest first
+  assert.deepEqual(rep.rows[0].uncoveredSteps, [{ index: 2, step: 'Upload' }]);
+  assert.equal(rep.summary.distribution['90-100'], 1);
+});