@taodigital/app-brain 0.0.0-stage → 1.2.1

package/dist/repository.d.ts

@@ -0,0 +1,3185 @@
+import { Prisma } from '@taodigital/database';
+import type { TestKind } from '@taodigital/core';
+export interface AppBrainConfig {
+    maxSelectiveSkillFiles?: number;
+    minRerankScore?: number;
+    chunkCharLimit?: number;
+    chunkOverlap?: number;
+    minChunkLength?: number;
+    minChunkWindow?: number;
+    bm25TopK?: number;
+    maxChunkChars?: number;
+    bm25CandidatePool?: number;
+    rerankSafetyCap?: number;
+    kgMaxHops?: number;
+    kgMaxSuggestions?: number;
+    kgJourneyMaxHops?: number;
+    crossProjectPatternLimit?: number;
+    flakyWindowSize?: number;
+    flakyMinRunsToScore?: number;
+    quarantineMinRuns?: number;
+    quarantineThreshold?: number;
+    coverageWeights?: {
+        CRITICAL: number;
+        HIGH: number;
+        MEDIUM: number;
+        LOW: number;
+    };
+    targetCoveragePercent?: number;
+    sharedRunTtlHours?: number;
+}
+type TruthDiffSegmentKind = 'MATCH' | 'WEAK_MATCH' | 'DOCUMENTED_NOT_OBSERVED' | 'OBSERVED_NOT_DOCUMENTED';
+type TruthDiffSegment = {
+    id: string;
+    kind: TruthDiffSegmentKind;
+    title: string;
+    confidence: number;
+    requirement?: {
+        id: string;
+        reqId: string;
+        title: string;
+        priority: string;
+        type: string;
+        sourceSection?: string | null;
+    };
+    crawlEvidence?: Array<{
+        id?: string;
+        role?: string | null;
+        text: string;
+    }>;
+    requirementEvidence?: string[];
+    recommendation: string;
+};
+export interface CredentialProfile {
+    id: string;
+    name: string;
+    username: string;
+    password?: string;
+    totpSecret?: string;
+    storageState?: string;
+    color?: string;
+}
+export type LLMTaskType = 'crawl' | 'testGeneration' | 'testScriptGen' | 'testScriptPatch' | 'testPlan' | 'testRunner' | 'elementExtraction' | 'linkDiscovery' | 'screenNaming' | 'appBrain' | 'requirementsExtraction' | 'visualDiff';
+export interface RequirementUpsertInput {
+    reqId: string;
+    title: string;
+    actor?: string | null;
+    type?: string;
+    priority?: string;
+    acceptanceCriteria?: string[];
+    businessRules?: string[];
+    relatedScreenHints?: string[];
+    sourceSection?: string | null;
+    derived?: boolean;
+    source?: string;
+    status?: string;
+    externalMeta?: any;
+}
+/**
+ * The Zeta Core repository: read/write the project's permanent knowledge.
+ * Everything goes through withTenant(), so the database enforces isolation.
+ */
+export declare const AppBrain: {
+    /** Delete all elements (and their fingerprints) for a screen — call before re-saving on recrawl. */
+    clearScreenElements(tenantId: string, projectId: string, screenId: string): Promise<void>;
+    /** Add functional elements (buttons/inputs) parsed from the crawler. */
+    saveElements(tenantId: string, projectId: string, screenId: string, elements: any[]): Promise<Prisma.BatchPayload | undefined>;
+    /**
+     * (KAG) Knowledge Graph Traversal: Returns the structural DOM path
+     * bridging a start screen to an end screen.
+     */
+    /**
+     * BFS multi-hop traversal of the KAG navigation graph.
+     * Returns the shortest path of screen→element→screen edges from start to end,
+     * or null if unreachable within maxHops.
+     */
+    getScreenTransitionGraph(tenantId: string, projectId: string, startScreenId: string, endScreenId: string, maxHops?: number, cfg?: AppBrainConfig): Promise<Array<{
+        fromScreenId: string;
+        toScreenId: string;
+        viaElementMeaning: string;
+    }> | null>;
+    /**
+     * Suggests promising cross-screen "journey" pairs to generate a KAG test
+     * for, so a user doesn't have to already know both screen ids before
+     * calling generate-flow. Classifies every active screen with a rule-based
+     * archetype (no LLM needed — see archetype-classification.ts), narrows to
+     * the small set of interesting archetype-pair rules, and only then pays
+     * for a graph-reachability BFS (getScreenTransitionGraph) on that narrowed
+     * candidate list — not on every screen pair in the project.
+     */
+    suggestJourneys(tenantId: string, projectId: string, maxSuggestions?: number, cfg?: AppBrainConfig): Promise<{
+        suggestions: import("./archetype-classification.js").JourneyCandidate[];
+    }>;
+    /** Set which screen an element navigates to (called during crawl post-processing). */
+    setElementTransition(tenantId: string, screenId: string, elementMeaning: string, toScreenId: string): Promise<Prisma.BatchPayload>;
+    /** Save (or update) a discovered screen. Upserts on canonical URL to prevent accumulation
+     *  across re-crawls and to ensure projects crawling the same app share screen identity
+     *  (ZETA-084: inconsistent screen mapping; ZETA-079: inconsistent element discovery). */
+    saveScreen(tenantId: string, projectId: string, name: string, url?: string, jobId?: string, discoveryMethod?: "ENTRY_POINT" | "LINK_FOLLOW" | "SEED_URL" | "SKYVERN_AI" | "SITEMAP" | "INTERACTIVE_PROBE"): Promise<any>;
+    updateScreenDomSnapshot(tenantId: string, screenId: string, domSnapshotPath: string, domSnapshotCloudUrl?: string): Promise<void>;
+    updateScreenRequiresAuth(tenantId: string, screenId: string, requiresAuth: boolean): Promise<void>;
+    updateScreenMarkdownPath(tenantId: string, screenId: string, markdownPath: string): Promise<void>;
+    /** Persist the extracted-markdown file path + metadata, and BM25-index its content for RAG search. */
+    updateScreenAiSummary(tenantId: string, screenId: string, aiSummary: string): Promise<void>;
+    updateScreenMarkdown(tenantId: string, projectId: string, screenId: string, data: {
+        markdownPath: string;
+        markdownMethod: string;
+        markdownWordCount: number;
+        markdown: string;
+        heading: string;
+        aiSummary?: string;
+    }): Promise<void>;
+    /** Read back a screen's previously-extracted markdown content, if any. */
+    getScreenMarkdown(tenantId: string, screenId: string): Promise<{
+        markdownPath: string;
+        markdownContent: string | null;
+        markdownMethod: string | null;
+        markdownWordCount: number | null;
+    } | null>;
+    /**
+     * Compare intended truth (uploaded requirements) with implemented truth
+     * (crawl markdown + captured elements) for a single screen.
+     */
+    compareScreenToRequirements(tenantId: string, screenId: string): Promise<{
+        generatedAt: string;
+        projectId: any;
+        screen: {
+            id: any;
+            name: any;
+            url: any;
+            markdownMethod: any;
+            markdownWordCount: any;
+        };
+        summary: {
+            requirements: number;
+            capturedElements: any;
+            matches: number;
+            weakMatches: number;
+            documentedNotObserved: number;
+            observedNotDocumented: number;
+        };
+        gainedInformation: {
+            fromCrawl: any;
+            fromDocuments: string[];
+            generationGuidance: string[];
+        };
+        segments: TruthDiffSegment[];
+    } | null>;
+    /** Returns screen info needed to regenerate markdown from a DOM snapshot or captured elements. */
+    getScreenForMarkdownRegen(tenantId: string, screenId: string): Promise<{
+        projectId: string;
+        name: string;
+        url: string | null;
+        domSnapshotPath: string | null;
+        elements: Array<{
+            meaning: string | null;
+            text: string | null;
+            role: string | null;
+            expectedData: string | null;
+            notes: string | null;
+            isInteractive: boolean | null;
+            parentLandmark: string | null;
+            ariaState: unknown;
+            selector: string | null;
+        }>;
+    } | null>;
+    updateScreenA11y(tenantId: string, screenId: string, data: {
+        a11yScore?: number;
+    }): Promise<void>;
+    /**
+     * Phase 4.4: Persist axe-core violations for a screen.
+     * Deletes existing violations for the screen first (idempotent on re-crawl).
+     */
+    saveA11yViolations(tenantId: string, projectId: string, screenId: string, violations: Array<{
+        impact: string;
+        rule: string;
+        description: string;
+        nodeHtml?: string;
+        wcagTags?: string[];
+    }>, runId?: string): Promise<void>;
+    /** Reset all screens to ACTIVE for a new crawl — non-destructive replacement for clearScreens(). */
+    prepareForRecrawl(tenantId: string, projectId: string, jobId?: string): Promise<void>;
+    /** Mark screens not re-discovered in the latest crawl as PENDING_REMOVAL. */
+    markRemovedScreens(tenantId: string, projectId: string, discoveredUrls: string[], jobId?: string): Promise<any>;
+    /**
+     * Orphan-page report: classifies every ACTIVE screen as REACHABLE (has an
+     * inbound KAG edge, or is the crawl's entry point), GRAPH_ORPHAN (link-followed
+     * but nothing currently points to it), SITEMAP_ORPHAN (only reached because it
+     * was a configured seed URL — a true SEO-style orphan), or UNVERIFIED_ORPHAN
+     * (Skyvern-discovered, not yet covered by DOM link-wiring).
+     * See docs/research/25-orphan-page-detection-industry-comparison.md.
+     */
+    getOrphanScreens(tenantId: string, projectId: string): Promise<import("./orphan-classification.js").OrphanReport>;
+    /** G12: URL template coverage — groups screens by URL pattern to surface sampled vs. missing page types.
+     *  e.g. /invoice/abc-123 and /invoice/xyz-456 both map to template /invoice/:id (sampleCount: 2). */
+    getTemplateCoverage(tenantId: string, projectId: string): Promise<{
+        templates: {
+            template: string;
+            sampleCount: number;
+            exampleScreenId: any;
+            exampleUrl: any;
+            exampleName: any;
+        }[];
+        totalTemplates: number;
+        totalScreens: any;
+    }>;
+    /** Return ACTIVE and PENDING_REMOVAL screens for a project diff view. */
+    getScreenDiff(tenantId: string, projectId: string): Promise<{
+        active: any;
+        pendingRemoval: any;
+    }>;
+    /** Hard-delete PENDING_REMOVAL screens (user confirmed removal). */
+    acceptRemovals(tenantId: string, projectId: string, screenIds?: string[]): Promise<{
+        deleted: any;
+    }>;
+    /** Restore PENDING_REMOVAL screens to ACTIVE (user chose to keep them). */
+    dismissRemovals(tenantId: string, projectId: string, screenIds?: string[]): Promise<{
+        restored: any;
+    }>;
+    /** Delete all screen groups for a project (called before re-grouping). */
+    clearScreenGroups(tenantId: string, projectId: string): Promise<Prisma.BatchPayload>;
+    /** Save a ScreenGroup record. */
+    saveScreenGroup(tenantId: string, projectId: string, data: {
+        name: string;
+        slug: string;
+        icon: string;
+        color: string;
+        description?: string;
+        order: number;
+        crawlJobId?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        name: string;
+        slug: string;
+        description: string | null;
+        color: string;
+        icon: string;
+        order: number;
+        crawlJobId: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+    }>;
+    /** Assign multiple screens to a group by setting their groupId. */
+    assignScreensToGroup(tenantId: string, screenIds: string[], groupId: string): Promise<Prisma.BatchPayload>;
+    /** Get all screen groups for a project, including screen count. */
+    getScreenGroups(tenantId: string, projectId: string): Promise<any[]>;
+    /** Save an element with its MEANING and Phase 1 enriched metadata. */
+    saveElement(tenantId: string, projectId: string, screenId: string, meaning: string, role: string, expectedData?: string, notes?: string, text?: string, isInteractive?: boolean, boundingRect?: Record<string, number>, ariaState?: Record<string, string>, parentLandmark?: string, viewport?: string): Promise<{
+        tenantId: string;
+        screenId: string | null;
+        meaning: string | null;
+        id: string;
+        projectId: string;
+        role: string | null;
+        expectedData: string | null;
+        notes: string | null;
+        text: string | null;
+        isInteractive: boolean | null;
+        boundingRect: Prisma.JsonValue | null;
+        ariaState: Prisma.JsonValue | null;
+        parentLandmark: string | null;
+        viewport: string;
+        selector: string | null;
+        pageUrl: string | null;
+        screenshotUrl: string | null;
+        source: string;
+        metadata: Prisma.JsonValue | null;
+        transitionsToScreenId: string | null;
+    }>;
+    /** Phase 2: Update element hash; set elementHashChangedAt only when hash actually changes. */
+    updateElementHash(tenantId: string, screenId: string, newHash: string, previousHash: string | null): Promise<void>;
+    /** Phase 2: Return screens whose element hash changed after the most recent test generation. */
+    getScreensWithStaleTests(tenantId: string, projectId: string): Promise<any>;
+    /** Phase 3: Get storage path of previous screenshot version for pHash comparison. */
+    getPreviousScreenshotPath(tenantId: string, screenId: string, version: number): Promise<string | null>;
+    /** Phase 3: Upsert a ScreenDiff record after pHash comparison. */
+    saveScreenDiff(tenantId: string, projectId: string, screenId: string, fromVersion: number, toVersion: number, pHashDistance: number, changeLevel: string): Promise<void>;
+    /** Phase 3: Get most recent ScreenDiff for a screen. */
+    getLatestScreenDiff(tenantId: string, screenId: string): Promise<any>;
+    /** Phase 5: Replace probe observations for a screen (re-probe overwrites). */
+    saveProbeObservations(tenantId: string, projectId: string, screenId: string, observations: Array<{
+        elementMeaning: string;
+        observationType: string;
+        observedText: string;
+        triggeredBy: string;
+    }>): Promise<void>;
+    /** Save dynamic virtual screens discovered during interactive probing */
+    saveVirtualScreens(tenantId: string, projectId: string, parentScreenId: string, screens: Array<{
+        stateId: string;
+        triggerAction: string;
+        overlayType: string;
+        domSnapshotUrl?: string;
+        screenshotUrl?: string;
+    }>): Promise<void>;
+    /** Phase 5: Load probe observations for a screen (used by grounding). */
+    getProbeObservations(tenantId: string, screenId: string): Promise<any>;
+    /** Phase 4: Return full navigation graph with test coverage overlay. */
+    getCoverageGraph(tenantId: string, projectId: string): Promise<{
+        nodes: any;
+        edges: {
+            covered: boolean;
+            from: string;
+            to: string;
+            linkText?: string;
+            discoveryMethod: string;
+        }[];
+        stats: {
+            totalScreens: any;
+            coveredScreens: any;
+            coveragePercent: number;
+        };
+    }>;
+    /** Save a screenshot record linked to the screen and project. */
+    saveScreenshot(tenantId: string, projectId: string, screenId: string, storagePath: string, version?: number, viewport?: string, cloudUrl?: string, dpr?: number): Promise<{
+        tenantId: string;
+        screenId: string;
+        id: string;
+        projectId: string;
+        viewport: string;
+        version: number;
+        storagePath: string;
+        cloudUrl: string | null;
+        capturedAt: Date;
+        dpr: number | null;
+    }>;
+    /** Update cloudUrl on an existing screenshot after successful cloud upload. */
+    updateScreenshotCloudUrl(tenantId: string, screenshotId: string, cloudUrl: string): Promise<{
+        tenantId: string;
+        screenId: string;
+        id: string;
+        projectId: string;
+        viewport: string;
+        version: number;
+        storagePath: string;
+        cloudUrl: string | null;
+        capturedAt: Date;
+        dpr: number | null;
+    }>;
+    /** Delete all flow edges for a project — call before re-crawl to prevent accumulation. */
+    clearFlows(tenantId: string, projectId: string): Promise<Prisma.BatchPayload>;
+    /** Save a directed screen-map edge as a simple two-step flow. */
+    saveFlow(tenantId: string, projectId: string, name: string, fromScreenId: string, toScreenId: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        name: string;
+        steps: Prisma.JsonValue;
+    }>;
+    /** Resolve slug or CUID to the canonical project CUID. Returns null if not found. */
+    resolveProjectId(tenantId: string, idOrSlug: string): Promise<string | null>;
+    /** Save crawl credentials for a project (password + TOTP secret + storageState encrypted). */
+    saveCrawlConfig(tenantId: string, projectId: string, creds: {
+        appUrl?: string;
+        username?: string;
+        password?: string;
+        totpSecret?: string;
+        /** Playwright storageState JSON string — encrypted at rest, used to skip AI login. */
+        storageState?: string | null;
+        maxScreens?: number;
+        deviceProfiles?: string[];
+        /** Enable interactive probing during crawls (form submits, modal triggers). */
+        interactive?: boolean;
+        /** Seed the crawl queue from the project's sitemap.xml, in addition to link-following. */
+        useSitemap?: boolean;
+        /** Explicit sitemap URL override — defaults to `${appUrl origin}/sitemap.xml`. */
+        sitemapUrl?: string | null;
+        /** Crawl queue traversal order: BFS (default) | DFS | BEST_FIRST. */
+        traversalStrategy?: "BFS" | "DFS" | "BEST_FIRST";
+        /** BEST_FIRST only: URLs containing any of these (case-insensitive) are prioritized. */
+        bestFirstKeywords?: string[] | null;
+        /** HTTP Basic Auth credentials — stored in plain text (not secrets, just HTTP layer auth). */
+        httpBasicUsername?: string;
+        httpBasicPassword?: string;
+        /** Bearer/API token — encrypted at rest, injected as HTTP header, skips AI login. */
+        authToken?: string | null;
+        /** Header name for authToken (default: 'Authorization'). */
+        authTokenHeader?: string;
+        /** Prefix for authToken value (default: 'Bearer '). */
+        authTokenPrefix?: string;
+        /** CAPTCHA solving API key — encrypted at rest. */
+        captchaSolverApiKey?: string | null;
+        /** CAPTCHA solving service provider. */
+        captchaSolverProvider?: "2captcha" | "capsolver";
+        /** Named credential profiles for multi-role crawling. */
+        credentialProfiles?: Array<{
+            id?: string;
+            name: string;
+            username: string;
+            password?: string;
+            totpSecret?: string;
+            storageState?: string;
+            color?: string;
+        }>;
+        /** Path to a Chrome user data directory for profile inheritance (local deployments only). */
+        chromeProfilePath?: string;
+        /** GAP 5: MailSlurp API key for email OTP auto-retrieval — encrypted at rest. */
+        mailslurpApiKey?: string | null;
+        /** GAP 5: MailSlurp inbox ID (UUID). */
+        mailslurpInboxId?: string;
+        /** GAP 18: Workspace SSO provider ID. */
+        ssoProviderId?: string | null;
+        /** GAP 17: User ID of the person who captured/updated the session (audit log). */
+        sessionCapturedBy?: string;
+        /** Natural language login instructions for Stagehand AI login. */
+        loginInstructions?: string | null;
+        /** Recorded login steps from the Chrome extension step recorder. */
+        loginRecipe?: Array<{
+            action: string;
+            selector: string;
+            value?: string;
+            ms?: number;
+        }> | null;
+        /** HTTP/HTTPS/SOCKS5 proxy URL for routing browser through a proxy (e.g. residential proxy for bot-protected sites). */
+        proxyUrl?: string | null;
+        /** Use Camoufox (Firefox) as a Cloudflare cookie bootstrapper before the Chromium crawl. */
+        useFirefox?: boolean;
+        /** Additional seed URLs to prepend to the crawl queue (in addition to appUrl). */
+        seedUrls?: string[] | null;
+        /** URLs found by the last pre-crawl discovery (sitemap + robots) — stored for next-run diff. */
+        discoveredUrls?: string[] | null;
+        /** ISO timestamp of the last pre-crawl discovery run — gates the crawl button. */
+        discoveredAt?: string | null;
+        /** URL the browser landed on after successful login — used as Phase 3 discovery start URL. */
+        postLoginUrl?: string | null;
+        /** Error message from the last failed Validate & Capture attempt — shown on page reload. */
+        lastValidationError?: string | null;
+        /** ISO timestamp of the last failed Validate & Capture attempt. */
+        lastValidationErrorAt?: string | null;
+        /** Desktop viewport width in pixels (default: 1440). */
+        viewportWidth?: number | null;
+        /** Desktop viewport height in pixels (default: 900). */
+        viewportHeight?: number | null;
+    }): Promise<any>;
+    /** Get crawl credentials for a project (decrypted). */
+    getCrawlConfig(tenantId: string, projectId: string): Promise<{
+        appUrl?: string;
+        username?: string;
+        password?: string;
+        totpSecret?: string;
+        storageState?: string;
+        maxScreens?: number;
+        deviceProfiles?: string[];
+        /** Enable interactive probing during crawls (form submits, modal triggers). */
+        interactive?: boolean;
+        /** Seed the crawl queue from the project's sitemap.xml, in addition to link-following. */
+        useSitemap?: boolean;
+        /** Explicit sitemap URL override — defaults to `${appUrl origin}/sitemap.xml`. */
+        sitemapUrl?: string;
+        /** Crawl queue traversal order: BFS (default) | DFS | BEST_FIRST. */
+        traversalStrategy?: "BFS" | "DFS" | "BEST_FIRST";
+        /** BEST_FIRST only: URLs containing any of these (case-insensitive) are prioritized. */
+        bestFirstKeywords?: string[];
+        httpBasicUsername?: string;
+        httpBasicPassword?: string;
+        authToken?: string;
+        authTokenHeader?: string;
+        authTokenPrefix?: string;
+        captchaSolverApiKey?: string;
+        captchaSolverProvider?: "2captcha" | "capsolver";
+        credentialProfiles?: CredentialProfile[];
+        /** GAP 3: Path to Chrome user data directory for profile inheritance (local only). */
+        chromeProfilePath?: string;
+        /** GAP 5: MailSlurp API key (decrypted). */
+        mailslurpApiKey?: string;
+        /** GAP 5: MailSlurp inbox ID. */
+        mailslurpInboxId?: string;
+        /** GAP 18: Workspace SSO provider ID. */
+        ssoProviderId?: string;
+        /** GAP 17: ISO timestamp of when the session was last captured. */
+        sessionCapturedAt?: string;
+        /** GAP 17: User ID of who captured the session. */
+        sessionCapturedBy?: string;
+        /** Natural language login instructions for Stagehand AI login. */
+        loginInstructions?: string;
+        /** Recorded login steps from the Chrome extension step recorder. */
+        loginRecipe?: Array<{
+            action: string;
+            selector: string;
+            value?: string;
+            ms?: number;
+        }>;
+        /** HTTP/HTTPS/SOCKS5 proxy URL for bot-protected sites. */
+        proxyUrl?: string;
+        /** Use Camoufox (Firefox) as a Cloudflare cookie bootstrapper before the Chromium crawl. */
+        useFirefox?: boolean;
+        /** Additional seed URLs prepended to the crawl queue. */
+        seedUrls?: string[];
+        /** URLs found by the last pre-crawl discovery — used for next-run diff. */
+        discoveredUrls?: string[];
+        /** ISO timestamp of the last pre-crawl discovery run. */
+        discoveredAt?: string;
+        /** URL the browser landed on after successful login — used as Phase 3 discovery start URL. */
+        postLoginUrl?: string;
+        /** Error message from the last failed Validate & Capture attempt. */
+        lastValidationError?: string;
+        /** ISO timestamp of the last failed Validate & Capture attempt. */
+        lastValidationErrorAt?: string;
+        /** Desktop viewport width in pixels (default: 1440). */
+        viewportWidth?: number;
+        /** Desktop viewport height in pixels (default: 900). */
+        viewportHeight?: number;
+    } | null>;
+    /** Upsert a named credential profile inside crawlConfig.credentialProfiles. */
+    upsertCredentialProfile(tenantId: string, projectId: string, profile: {
+        id?: string;
+        name: string;
+        username: string;
+        password?: string;
+        totpSecret?: string;
+        storageState?: string;
+        color?: string;
+    }): Promise<void>;
+    /** Delete a named credential profile by id. */
+    deleteCredentialProfile(tenantId: string, projectId: string, profileId: string): Promise<void>;
+    /** Read a project with deduped screens (latest version per URL). Includes element diff vs prev version. */
+    getProjectMap(tenantId: string, projectIdOrSlug: string): Promise<{
+        screens: {
+            hasChange: boolean;
+            addedElements: string[];
+            removedElements: string[];
+            elementCountPrev: number;
+            totalVersions: number;
+            elements: {
+                tenantId: string;
+                screenId: string | null;
+                meaning: string | null;
+                id: string;
+                projectId: string;
+                role: string | null;
+                expectedData: string | null;
+                notes: string | null;
+                text: string | null;
+                isInteractive: boolean | null;
+                boundingRect: Prisma.JsonValue | null;
+                ariaState: Prisma.JsonValue | null;
+                parentLandmark: string | null;
+                viewport: string;
+                selector: string | null;
+                pageUrl: string | null;
+                screenshotUrl: string | null;
+                source: string;
+                metadata: Prisma.JsonValue | null;
+                transitionsToScreenId: string | null;
+            }[];
+            screenshots: {
+                tenantId: string;
+                screenId: string;
+                id: string;
+                projectId: string;
+                viewport: string;
+                version: number;
+                storagePath: string;
+                cloudUrl: string | null;
+                capturedAt: Date;
+                dpr: number | null;
+            }[];
+            screenDiffs: {
+                pHashDistance: number;
+                changeLevel: string;
+            }[];
+            tenantId: string;
+            id: string;
+            projectId: string;
+            name: string;
+            url: string | null;
+            version: number;
+            groupId: string | null;
+            figmaMatch: number | null;
+            a11yScore: number | null;
+            lastSeenAt: Date;
+            status: string;
+            lastCrawlJobId: string | null;
+            removedAt: Date | null;
+            removalReason: string | null;
+            discoveryMethod: string;
+            elementHash: string | null;
+            elementHashChangedAt: Date | null;
+            domSnapshotPath: string | null;
+            domSnapshotCloudUrl: string | null;
+            requiresAuth: boolean;
+            depth: number | null;
+            parentUrl: string | null;
+            roleAccess: string[];
+            markdownPath: string | null;
+            markdownContent: string | null;
+            markdownMethod: string | null;
+            markdownWordCount: number | null;
+            aiSummary: string | null;
+        }[];
+        flows: {
+            tenantId: string;
+            id: string;
+            projectId: string;
+            name: string;
+            steps: Prisma.JsonValue;
+        }[];
+        tenantId: string;
+        id: string;
+        name: string;
+        status: string;
+        slug: string;
+        description: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+        appUrl: string | null;
+        figmaUrl: string | null;
+        appType: string | null;
+        crawlConfig: Prisma.JsonValue | null;
+        ciFailureThreshold: number | null;
+        slaThreshold: number | null;
+        visualDiffThreshold: number | null;
+        oversized: boolean;
+        restricted: boolean;
+        vsaEnabled: boolean;
+        workspaceId: string | null;
+    } | null>;
+    /** Read everything known about one screen (used by grounding). */
+    getScreenWithElements(tenantId: string, screenId: string): Promise<({
+        elements: {
+            tenantId: string;
+            screenId: string | null;
+            meaning: string | null;
+            id: string;
+            projectId: string;
+            role: string | null;
+            expectedData: string | null;
+            notes: string | null;
+            text: string | null;
+            isInteractive: boolean | null;
+            boundingRect: Prisma.JsonValue | null;
+            ariaState: Prisma.JsonValue | null;
+            parentLandmark: string | null;
+            viewport: string;
+            selector: string | null;
+            pageUrl: string | null;
+            screenshotUrl: string | null;
+            source: string;
+            metadata: Prisma.JsonValue | null;
+            transitionsToScreenId: string | null;
+        }[];
+    } & {
+        tenantId: string;
+        id: string;
+        projectId: string;
+        name: string;
+        url: string | null;
+        version: number;
+        groupId: string | null;
+        figmaMatch: number | null;
+        a11yScore: number | null;
+        lastSeenAt: Date;
+        status: string;
+        lastCrawlJobId: string | null;
+        removedAt: Date | null;
+        removalReason: string | null;
+        discoveryMethod: string;
+        elementHash: string | null;
+        elementHashChangedAt: Date | null;
+        domSnapshotPath: string | null;
+        domSnapshotCloudUrl: string | null;
+        requiresAuth: boolean;
+        depth: number | null;
+        parentUrl: string | null;
+        roleAccess: string[];
+        markdownPath: string | null;
+        markdownContent: string | null;
+        markdownMethod: string | null;
+        markdownWordCount: number | null;
+        aiSummary: string | null;
+    }) | null>;
+    getScreenOutgoingTransitions(tenantId: string, screenId: string, limit?: number): Promise<unknown>;
+    getLatestScreenshot(tenantId: string, screenId: string, viewport?: string): Promise<{
+        tenantId: string;
+        screenId: string;
+        id: string;
+        projectId: string;
+        viewport: string;
+        version: number;
+        storagePath: string;
+        cloudUrl: string | null;
+        capturedAt: Date;
+        dpr: number | null;
+    } | null>;
+    getScreenshotViewports(tenantId: string, screenId: string): Promise<string[]>;
+    /** Load one skill file by kind (backward-compat accessor). */
+    getSkillFile(tenantId: string, projectId: string, kind: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        source: string;
+        version: number;
+        updatedAt: Date;
+        kind: string;
+        scope: string;
+        summary: string | null;
+        tags: Prisma.JsonValue;
+        screenIds: Prisma.JsonValue;
+        content: string;
+        structuredData: Prisma.JsonValue;
+        provenance: Prisma.JsonValue;
+        confidence: number | null;
+        validationStatus: string;
+        validationSummary: string | null;
+        staleStatus: string;
+        staleReason: string | null;
+        generatorVersion: string | null;
+        approvedBy: string | null;
+        approvalStatus: string;
+        priorContent: string | null;
+        priorVersion: number | null;
+        priorGeneratedAt: Date | null;
+        changesSummary: string | null;
+        lastGenPromptTokens: number | null;
+        lastGenCompletionTokens: number | null;
+        lastGenCostUsd: number | null;
+        lastGenModel: string | null;
+        lastGenAt: Date | null;
+    } | null>;
+    /**
+     * Upsert a taxonomy skill file.
+     * Key: (projectId, kind, scope). Each project has exactly one file per kind.
+     * On update: version increments, content + summary + tags replaced, approvedBy cleared.
+     */
+    upsertSkillFile(tenantId: string, projectId: string, kind: string, content: string, opts?: {
+        summary?: string;
+        tags?: string[];
+        screenIds?: string[];
+        scope?: string;
+        source?: string;
+        approvedBy?: string;
+        approvalStatus?: string;
+        structuredData?: unknown;
+        provenance?: unknown[];
+        confidence?: number | null;
+        validationStatus?: string;
+        validationSummary?: string | null;
+        staleStatus?: string;
+        staleReason?: string | null;
+        generatorVersion?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        source: string;
+        version: number;
+        updatedAt: Date;
+        kind: string;
+        scope: string;
+        summary: string | null;
+        tags: Prisma.JsonValue;
+        screenIds: Prisma.JsonValue;
+        content: string;
+        structuredData: Prisma.JsonValue;
+        provenance: Prisma.JsonValue;
+        confidence: number | null;
+        validationStatus: string;
+        validationSummary: string | null;
+        staleStatus: string;
+        staleReason: string | null;
+        generatorVersion: string | null;
+        approvedBy: string | null;
+        approvalStatus: string;
+        priorContent: string | null;
+        priorVersion: number | null;
+        priorGeneratedAt: Date | null;
+        changesSummary: string | null;
+        lastGenPromptTokens: number | null;
+        lastGenCompletionTokens: number | null;
+        lastGenCostUsd: number | null;
+        lastGenModel: string | null;
+        lastGenAt: Date | null;
+    }>;
+    /** Mark a skill file as human-approved. */
+    approveSkillFile(tenantId: string, skillFileId: string, approverId: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        source: string;
+        version: number;
+        updatedAt: Date;
+        kind: string;
+        scope: string;
+        summary: string | null;
+        tags: Prisma.JsonValue;
+        screenIds: Prisma.JsonValue;
+        content: string;
+        structuredData: Prisma.JsonValue;
+        provenance: Prisma.JsonValue;
+        confidence: number | null;
+        validationStatus: string;
+        validationSummary: string | null;
+        staleStatus: string;
+        staleReason: string | null;
+        generatorVersion: string | null;
+        approvedBy: string | null;
+        approvalStatus: string;
+        priorContent: string | null;
+        priorVersion: number | null;
+        priorGeneratedAt: Date | null;
+        changesSummary: string | null;
+        lastGenPromptTokens: number | null;
+        lastGenCompletionTokens: number | null;
+        lastGenCostUsd: number | null;
+        lastGenModel: string | null;
+        lastGenAt: Date | null;
+    }>;
+    getSkillFileVersions(tenantId: string, projectId: string, kind: string): Promise<any>;
+    getSkillFileVersion(tenantId: string, projectId: string, kind: string, versionNum: number): Promise<any>;
+    /**
+     * Live data for the COVERAGE_MATRIX skill file: active screens with element
+     * counts, plus TestCase counts grouped by (screenId, kind). Retired test
+     * cases are excluded.
+     */
+    getCoverageMatrixData(tenantId: string, projectId: string): Promise<{
+        screens: {
+            id: any;
+            name: any;
+            url: any;
+            elementCount: any;
+        }[];
+        counts: {
+            screenId: any;
+            kind: any;
+            count: any;
+        }[];
+    }>;
+    /** Delete skill files matching given kinds — used to purge legacy kind names after migration. */
+    deleteSkillFilesByKinds(tenantId: string, projectId: string, kinds: string[]): Promise<Prisma.BatchPayload | undefined>;
+    /** List all skill files for a project, optionally filtered by kind. */
+    listSkillFiles(tenantId: string, projectId: string, kinds?: string[]): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        source: string;
+        version: number;
+        updatedAt: Date;
+        kind: string;
+        scope: string;
+        summary: string | null;
+        tags: Prisma.JsonValue;
+        screenIds: Prisma.JsonValue;
+        content: string;
+        structuredData: Prisma.JsonValue;
+        provenance: Prisma.JsonValue;
+        confidence: number | null;
+        validationStatus: string;
+        validationSummary: string | null;
+        staleStatus: string;
+        staleReason: string | null;
+        generatorVersion: string | null;
+        approvedBy: string | null;
+        approvalStatus: string;
+        priorContent: string | null;
+        priorVersion: number | null;
+        priorGeneratedAt: Date | null;
+        changesSummary: string | null;
+        lastGenPromptTokens: number | null;
+        lastGenCompletionTokens: number | null;
+        lastGenCostUsd: number | null;
+        lastGenModel: string | null;
+        lastGenAt: Date | null;
+    }[]>;
+    /**
+     * Retrieve skill files relevant for a specific screen — the graduated strategy:
+     *
+     *   Global tier (always): PLATFORM, FUNCTION, DESIGN, THEME
+     *   Selective tier: COMPONENT + ELEMENT files where screenIds is empty (applies to all)
+     *     OR screenIds contains this screenId
+     *
+     * Callers with < 50 screens: use this method (loads all relevant).
+     * Callers with 300+ screens: add vector search on top of this for COMPONENT/ELEMENT.
+     */
+    getRelevantSkillFilesForScreen(tenantId: string, projectId: string, screenId: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        source: string;
+        version: number;
+        updatedAt: Date;
+        kind: string;
+        scope: string;
+        summary: string | null;
+        tags: Prisma.JsonValue;
+        screenIds: Prisma.JsonValue;
+        content: string;
+        structuredData: Prisma.JsonValue;
+        provenance: Prisma.JsonValue;
+        confidence: number | null;
+        validationStatus: string;
+        validationSummary: string | null;
+        staleStatus: string;
+        staleReason: string | null;
+        generatorVersion: string | null;
+        approvedBy: string | null;
+        approvalStatus: string;
+        priorContent: string | null;
+        priorVersion: number | null;
+        priorGeneratedAt: Date | null;
+        changesSummary: string | null;
+        lastGenPromptTokens: number | null;
+        lastGenCompletionTokens: number | null;
+        lastGenCostUsd: number | null;
+        lastGenModel: string | null;
+        lastGenAt: Date | null;
+    }[]>;
+    listArtifacts(tenantId: string, projectId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    createArtifact(tenantId: string, projectId: string, data: {
+        name: string;
+        originalName: string;
+        mimeType: string;
+        size: number;
+        content: string;
+        kind: string;
+        uploadedBy: string;
+        storageKey?: string;
+    }): Promise<any>;
+    reindexArtifact(tenantId: string, projectId: string, artifactId: string, content: string, name: string): Promise<void>;
+    getArtifactUsage(tenantId: string, projectId: string, artifactId: string): Promise<{
+        testCaseCount: any;
+        suiteCount: number;
+        suites: {
+            id: string;
+            name: string;
+            count: number;
+        }[];
+        artifactName: any;
+        versionNum: any;
+    }>;
+    deleteArtifact(tenantId: string, artifactId: string, opts?: {
+        action?: "keep" | "retire" | "delete";
+        projectId?: string;
+    }): Promise<{
+        deletedArtifact: any;
+        testCasesAffected: number;
+        action: "keep" | "retire" | "delete";
+    }>;
+    updateArtifactIntelligence(tenantId: string, artifactId: string, data: {
+        summary?: string;
+        keywords?: string[];
+        docType?: string;
+        chunkCount?: number;
+    }): Promise<unknown>;
+    enrichChunkKeywords(tenantId: string, projectId: string, artifactId: string, content: string, name: string, keywords: string[]): Promise<void>;
+    /** Artifact ↔ test-case coverage matrix — pure DB, no LLM. */
+    getArtifactCoverage(tenantId: string, projectId: string): Promise<{
+        totalTestCases: any;
+        coveredByArtifact: number;
+        orphaned: number;
+        coveragePct: number;
+        artifacts: {
+            id: string;
+            name: string;
+            originalName: string;
+            kind: string;
+            testCases: {
+                id: string;
+                title: string;
+                status: string;
+            }[];
+        }[];
+        orphanedCases: {
+            id: string;
+            title: string;
+            status: string;
+        }[];
+    }>;
+    /**
+     * BM25 knowledge retrieval using Postgres full-text search (tsvector + GIN).
+     * Searches KnowledgeChunk rows indexed from skill files and artifacts.
+     * No LLM calls, no embeddings. <5ms per query.
+     *
+     * Falls back to in-memory scan of skill files if KnowledgeChunk table is empty
+     * (e.g. before first re-index after the 0014 migration).
+     */
+    searchKnowledge(tenantId: string, projectId: string, query: string, topK?: number, maxChunkChars?: number, cfg?: AppBrainConfig): Promise<{
+        label: any;
+        source: "SKILL_FILE";
+        sourceId: any;
+        score: number;
+        content: any;
+    }[] | {
+        label: string;
+        source: "SKILL_FILE" | "ARTIFACT";
+        sourceId: string;
+        score: any;
+        content: string;
+    }[]>;
+    /** Returns aggregated skill file content from all OTHER projects in the tenant — for cross-project pattern learning */
+    getCrossProjectPatterns(tenantId: string, currentProjectId: string, limit?: number): Promise<string>;
+    listTestSuites(tenantId: string, projectId: string): Promise<any[]>;
+    getTestSuiteWithCases(tenantId: string, suiteId: string): Promise<({
+        testCases: ({
+            screen: {
+                roleAccess: string[];
+            } | null;
+            testData: {
+                tenantId: string;
+                id: string;
+                projectId: string;
+                source: string;
+                kind: string;
+                testCaseId: string;
+                payload: Prisma.JsonValue;
+                supersededAt: Date | null;
+            }[];
+        } & {
+            tenantId: string;
+            screenId: string | null;
+            id: string;
+            projectId: string;
+            source: string;
+            status: string;
+            createdAt: Date;
+            updatedAt: Date;
+            steps: Prisma.JsonValue;
+            kind: string;
+            tags: Prisma.JsonValue;
+            approvedBy: string | null;
+            suiteId: string;
+            ref: string | null;
+            title: string;
+            priority: string;
+            preconditions: string | null;
+            expectedResult: string | null;
+            gherkin: string | null;
+            approvedAt: Date | null;
+            groundedOn: Prisma.JsonValue;
+            caseRefs: Prisma.JsonValue;
+            viewports: Prisma.JsonValue;
+            viewportConstraint: string;
+            techniqueOfRecord: string | null;
+            traceTo: string | null;
+            traceToExtra: Prisma.JsonValue;
+            testDataInline: Prisma.JsonValue | null;
+            dataNote: string | null;
+            scriptNote: string | null;
+            structuredSteps: Prisma.JsonValue | null;
+            artifactId: string | null;
+            scenarioId: string | null;
+            suspect: boolean;
+            suspectReason: string | null;
+            flakyScore: number;
+            consecutiveFlakes: number;
+            lastFlakyAt: Date | null;
+            quarantined: boolean;
+            quarantinedAt: Date | null;
+            quarantineReason: string | null;
+            genPromptTokens: number | null;
+            genCompletionTokens: number | null;
+            genCostUsd: number | null;
+            genModel: string | null;
+            dataSetId: string | null;
+            repoTargetPath: string | null;
+            stepsKey: string | null;
+            gherkinKey: string | null;
+            contentHash: string | null;
+            groundingHash: string | null;
+            locatorsJson: Prisma.JsonValue | null;
+            locatorsExtractedAt: Date | null;
+            captureStepScreenshots: Prisma.JsonValue | null;
+        })[];
+    } & {
+        tenantId: string;
+        id: string;
+        projectId: string;
+        name: string;
+        createdAt: Date;
+        genModel: string | null;
+        category: import(".prisma/client").$Enums.SuiteCategory | null;
+        parentId: string | null;
+        ownerUserId: string | null;
+        genTotalTokens: number | null;
+        genTotalCostUsd: number | null;
+        genAt: Date | null;
+        genScreenCount: number | null;
+        coverageReport: Prisma.JsonValue | null;
+    }) | null>;
+    listTestCases(tenantId: string, projectId: string, filters?: {
+        status?: string;
+        suiteId?: string;
+        kind?: string;
+        priority?: string;
+        screenIds?: string[];
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    listTestCaseSummaries(tenantId: string, projectId: string, limit?: number): Promise<Array<{
+        id: string;
+        ref?: string | null;
+        title: string;
+        screenId?: string | null;
+        groundedOn: string[];
+        steps: unknown;
+    }>>;
+    getScreenTestCounts(tenantId: string, projectId: string): Promise<Record<string, {
+        total: number;
+        approved: number;
+        pending: number;
+        suiteId?: string;
+    }>>;
+    getChangedScreenIds(tenantId: string, projectId: string, sinceDate?: Date): Promise<string[]>;
+    getSuiteLastGenAt(tenantId: string, suiteId: string): Promise<Date | null>;
+    getTestCaseWithContext(tenantId: string, testCaseId: string): Promise<({
+        testData: {
+            tenantId: string;
+            id: string;
+            projectId: string;
+            source: string;
+            kind: string;
+            testCaseId: string;
+            payload: Prisma.JsonValue;
+            supersededAt: Date | null;
+        }[];
+        suite: {
+            tenantId: string;
+            id: string;
+            projectId: string;
+            name: string;
+            createdAt: Date;
+            genModel: string | null;
+            category: import(".prisma/client").$Enums.SuiteCategory | null;
+            parentId: string | null;
+            ownerUserId: string | null;
+            genTotalTokens: number | null;
+            genTotalCostUsd: number | null;
+            genAt: Date | null;
+            genScreenCount: number | null;
+            coverageReport: Prisma.JsonValue | null;
+        };
+        scripts: {
+            tenantId: string;
+            id: string;
+            projectId: string;
+            validationStatus: string;
+            testCaseId: string;
+            language: string;
+            code: string;
+            filePath: string | null;
+            codeKey: string | null;
+            validationErrors: string | null;
+            pushedToPR: boolean;
+            pushedPRId: string | null;
+        }[];
+        dataSet: ({
+            rows: {
+                data: Prisma.JsonValue;
+                tenantId: string;
+                id: string;
+                dataSetId: string;
+                rowIndex: number;
+            }[];
+        } & {
+            tenantId: string;
+            id: string;
+            projectId: string;
+            name: string;
+            createdAt: Date;
+            classification: string;
+            environment: string | null;
+        }) | null;
+    } & {
+        tenantId: string;
+        screenId: string | null;
+        id: string;
+        projectId: string;
+        source: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        steps: Prisma.JsonValue;
+        kind: string;
+        tags: Prisma.JsonValue;
+        approvedBy: string | null;
+        suiteId: string;
+        ref: string | null;
+        title: string;
+        priority: string;
+        preconditions: string | null;
+        expectedResult: string | null;
+        gherkin: string | null;
+        approvedAt: Date | null;
+        groundedOn: Prisma.JsonValue;
+        caseRefs: Prisma.JsonValue;
+        viewports: Prisma.JsonValue;
+        viewportConstraint: string;
+        techniqueOfRecord: string | null;
+        traceTo: string | null;
+        traceToExtra: Prisma.JsonValue;
+        testDataInline: Prisma.JsonValue | null;
+        dataNote: string | null;
+        scriptNote: string | null;
+        structuredSteps: Prisma.JsonValue | null;
+        artifactId: string | null;
+        scenarioId: string | null;
+        suspect: boolean;
+        suspectReason: string | null;
+        flakyScore: number;
+        consecutiveFlakes: number;
+        lastFlakyAt: Date | null;
+        quarantined: boolean;
+        quarantinedAt: Date | null;
+        quarantineReason: string | null;
+        genPromptTokens: number | null;
+        genCompletionTokens: number | null;
+        genCostUsd: number | null;
+        genModel: string | null;
+        dataSetId: string | null;
+        repoTargetPath: string | null;
+        stepsKey: string | null;
+        gherkinKey: string | null;
+        contentHash: string | null;
+        groundingHash: string | null;
+        locatorsJson: Prisma.JsonValue | null;
+        locatorsExtractedAt: Date | null;
+        captureStepScreenshots: Prisma.JsonValue | null;
+    }) | null>;
+    reviewTestCase(tenantId: string, testCaseId: string, opts: {
+        status: string;
+        updatedTitle?: string;
+        updatedSteps?: string[];
+        updatedPreconditions?: string | null;
+        updatedExpectedResult?: string | null;
+        updatedKind?: string;
+        updatedPriority?: string;
+        updatedTags?: string[];
+        note?: string;
+        reviewerId: string;
+        approvedBy?: string | null;
+        approvedAt?: Date | null;
+    }): Promise<{
+        tenantId: string;
+        screenId: string | null;
+        id: string;
+        projectId: string;
+        source: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        steps: Prisma.JsonValue;
+        kind: string;
+        tags: Prisma.JsonValue;
+        approvedBy: string | null;
+        suiteId: string;
+        ref: string | null;
+        title: string;
+        priority: string;
+        preconditions: string | null;
+        expectedResult: string | null;
+        gherkin: string | null;
+        approvedAt: Date | null;
+        groundedOn: Prisma.JsonValue;
+        caseRefs: Prisma.JsonValue;
+        viewports: Prisma.JsonValue;
+        viewportConstraint: string;
+        techniqueOfRecord: string | null;
+        traceTo: string | null;
+        traceToExtra: Prisma.JsonValue;
+        testDataInline: Prisma.JsonValue | null;
+        dataNote: string | null;
+        scriptNote: string | null;
+        structuredSteps: Prisma.JsonValue | null;
+        artifactId: string | null;
+        scenarioId: string | null;
+        suspect: boolean;
+        suspectReason: string | null;
+        flakyScore: number;
+        consecutiveFlakes: number;
+        lastFlakyAt: Date | null;
+        quarantined: boolean;
+        quarantinedAt: Date | null;
+        quarantineReason: string | null;
+        genPromptTokens: number | null;
+        genCompletionTokens: number | null;
+        genCostUsd: number | null;
+        genModel: string | null;
+        dataSetId: string | null;
+        repoTargetPath: string | null;
+        stepsKey: string | null;
+        gherkinKey: string | null;
+        contentHash: string | null;
+        groundingHash: string | null;
+        locatorsJson: Prisma.JsonValue | null;
+        locatorsExtractedAt: Date | null;
+        captureStepScreenshots: Prisma.JsonValue | null;
+    }>;
+    bulkReviewTestCases(tenantId: string, projectId: string, ids: string[], status: string, reviewerId: string): Promise<Prisma.BatchPayload>;
+    addTestCaseToSuite(tenantId: string, projectId: string, suiteId: string, testCase: {
+        title: string;
+        kind: TestKind;
+        steps: unknown[];
+        groundedOn: string[] | Array<{
+            id: string;
+            text: string;
+        }>;
+        ref?: string;
+        screenId?: string | null;
+        priority?: string;
+        preconditions?: string | null;
+        expectedResult?: string | null;
+        tags?: string[];
+        source?: string;
+    }): Promise<{
+        tenantId: string;
+        screenId: string | null;
+        id: string;
+        projectId: string;
+        source: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        steps: Prisma.JsonValue;
+        kind: string;
+        tags: Prisma.JsonValue;
+        approvedBy: string | null;
+        suiteId: string;
+        ref: string | null;
+        title: string;
+        priority: string;
+        preconditions: string | null;
+        expectedResult: string | null;
+        gherkin: string | null;
+        approvedAt: Date | null;
+        groundedOn: Prisma.JsonValue;
+        caseRefs: Prisma.JsonValue;
+        viewports: Prisma.JsonValue;
+        viewportConstraint: string;
+        techniqueOfRecord: string | null;
+        traceTo: string | null;
+        traceToExtra: Prisma.JsonValue;
+        testDataInline: Prisma.JsonValue | null;
+        dataNote: string | null;
+        scriptNote: string | null;
+        structuredSteps: Prisma.JsonValue | null;
+        artifactId: string | null;
+        scenarioId: string | null;
+        suspect: boolean;
+        suspectReason: string | null;
+        flakyScore: number;
+        consecutiveFlakes: number;
+        lastFlakyAt: Date | null;
+        quarantined: boolean;
+        quarantinedAt: Date | null;
+        quarantineReason: string | null;
+        genPromptTokens: number | null;
+        genCompletionTokens: number | null;
+        genCostUsd: number | null;
+        genModel: string | null;
+        dataSetId: string | null;
+        repoTargetPath: string | null;
+        stepsKey: string | null;
+        gherkinKey: string | null;
+        contentHash: string | null;
+        groundingHash: string | null;
+        locatorsJson: Prisma.JsonValue | null;
+        locatorsExtractedAt: Date | null;
+        captureStepScreenshots: Prisma.JsonValue | null;
+    }>;
+    saveTestData(tenantId: string, projectId: string, testCaseId: string, dataSets: Array<{
+        label: string;
+        category: string;
+        values: Record<string, string>;
+        expectedOutcome: string;
+        source?: string;
+    }>): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        source: string;
+        kind: string;
+        testCaseId: string;
+        payload: Prisma.JsonValue;
+        supersededAt: Date | null;
+    }[]>;
+    /**
+     * R2/H4: Rebuild TestCase.gherkin as a data-driven `Scenario Outline: + Examples:` table
+     * using all non-FALLBACK TestData rows for the given test case.
+     * Called after any TestData row is added or updated.
+     */
+    rebuildGherkinOutlineForCase(tenantId: string, testCaseId: string): Promise<void>;
+    getTestDataForCase(tenantId: string, testCaseId: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        source: string;
+        kind: string;
+        testCaseId: string;
+        payload: Prisma.JsonValue;
+        supersededAt: Date | null;
+    }[]>;
+    /** Returns screen elements (with notes/selector fields) needed to compute Playwright locators. */
+    getScreenElementsForLocators(tenantId: string, screenId: string): Promise<Array<{
+        role: string | null;
+        meaning: string | null;
+        text: string | null;
+        notes: string | null;
+        selector: string | null;
+        isInteractive: boolean | null;
+        ariaState: Record<string, unknown> | null;
+    }>>;
+    /** Persist computed Playwright locators on a test case. */
+    saveLocatorsJson(tenantId: string, testCaseId: string, locators: Array<{
+        key: string;
+        expression: string;
+        elementType: string;
+        confidence: string;
+        source: string;
+        description: string;
+    }>): Promise<void>;
+    /** Get stored locators for a test case (may be null if not yet extracted). */
+    getLocatorsJson(tenantId: string, testCaseId: string): Promise<Array<{
+        key: string;
+        expression: string;
+        elementType: string;
+        confidence: string;
+        source: string;
+        description: string;
+    }> | null>;
+    linkOrCreateSharedDataSet(tenantId: string, projectId: string, testCaseId: string, fieldKeys: string[], dataSets: Array<{
+        label: string;
+        category: string;
+        values: Record<string, string>;
+        expectedOutcome: string;
+    }>): Promise<void>;
+    getFieldsForCase(tenantId: string, projectId: string, groundedOn: string[]): Promise<import("@taodigital/core").FieldSchema[]>;
+    upsertAppField(tenantId: string, projectId: string, field: import("@taodigital/core").FieldSchema): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        notes: string | null;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        fieldKey: string;
+        label: string;
+        elementRole: string;
+        dataBearing: boolean;
+        dataType: string;
+        required: boolean;
+        minLength: number | null;
+        maxLength: number | null;
+        minValue: number | null;
+        maxValue: number | null;
+        precision: number | null;
+        regex: string | null;
+        enumValues: Prisma.JsonValue | null;
+        piiClass: string;
+        exampleValue: string | null;
+        relationGroup: string | null;
+    }>;
+    listAppFields(tenantId: string, projectId: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        notes: string | null;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        fieldKey: string;
+        label: string;
+        elementRole: string;
+        dataBearing: boolean;
+        dataType: string;
+        required: boolean;
+        minLength: number | null;
+        maxLength: number | null;
+        minValue: number | null;
+        maxValue: number | null;
+        precision: number | null;
+        regex: string | null;
+        enumValues: Prisma.JsonValue | null;
+        piiClass: string;
+        exampleValue: string | null;
+        relationGroup: string | null;
+    }[]>;
+    confirmAppField(tenantId: string, projectId: string, fieldKey: string, patch: Partial<import("@taodigital/core").FieldSchema>): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        notes: string | null;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        fieldKey: string;
+        label: string;
+        elementRole: string;
+        dataBearing: boolean;
+        dataType: string;
+        required: boolean;
+        minLength: number | null;
+        maxLength: number | null;
+        minValue: number | null;
+        maxValue: number | null;
+        precision: number | null;
+        regex: string | null;
+        enumValues: Prisma.JsonValue | null;
+        piiClass: string;
+        exampleValue: string | null;
+        relationGroup: string | null;
+    }>;
+    deleteAppField(tenantId: string, projectId: string, fieldKey: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        notes: string | null;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        fieldKey: string;
+        label: string;
+        elementRole: string;
+        dataBearing: boolean;
+        dataType: string;
+        required: boolean;
+        minLength: number | null;
+        maxLength: number | null;
+        minValue: number | null;
+        maxValue: number | null;
+        precision: number | null;
+        regex: string | null;
+        enumValues: Prisma.JsonValue | null;
+        piiClass: string;
+        exampleValue: string | null;
+        relationGroup: string | null;
+    }>;
+    saveTestScript(tenantId: string, projectId: string, testCaseId: string, language: string, code: string, filePath?: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        validationStatus: string;
+        testCaseId: string;
+        language: string;
+        code: string;
+        filePath: string | null;
+        codeKey: string | null;
+        validationErrors: string | null;
+        pushedToPR: boolean;
+        pushedPRId: string | null;
+    }>;
+    getTestScript(tenantId: string, testCaseId: string, language: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        validationStatus: string;
+        testCaseId: string;
+        language: string;
+        code: string;
+        filePath: string | null;
+        codeKey: string | null;
+        validationErrors: string | null;
+        pushedToPR: boolean;
+        pushedPRId: string | null;
+    } | null>;
+    getTestScriptVersions(tenantId: string, testCaseId: string, language: string): Promise<unknown>;
+    getTestScriptVersion(tenantId: string, testCaseId: string, language: string, versionNum: number): Promise<unknown>;
+    saveScriptBundle(tenantId: string, projectId: string, scopeType: "SUITE" | "PACK", scopeId: string, language: string, data: {
+        files: unknown;
+        basePage?: string | null;
+        caseCount?: number;
+    }): Promise<unknown>;
+    getScriptBundle(tenantId: string, projectId: string, scopeType: "SUITE" | "PACK", scopeId: string, language: string): Promise<unknown>;
+    deleteScriptBundle(tenantId: string, projectId: string, scopeType: "SUITE" | "PACK", scopeId: string, language: string): Promise<void>;
+    deleteTestScriptsForSuite(tenantId: string, suiteId: string, language: string): Promise<void>;
+    createTestRun(tenantId: string, projectId: string, opts: {
+        suiteId?: string;
+        trigger: string;
+        config?: any;
+        totalShards?: number;
+        githubRepo?: string;
+        githubSha?: string;
+        githubRef?: string;
+        triggeredBy?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        summary: Prisma.JsonValue | null;
+        suiteId: string | null;
+        trigger: string;
+        config: Prisma.JsonValue | null;
+        totalShards: number | null;
+        githubRepo: string | null;
+        githubSha: string | null;
+        githubRef: string | null;
+        triggeredBy: string | null;
+        startedAt: Date;
+        finishedAt: Date | null;
+    }>;
+    createTestRunShards(tenantId: string, runId: string, shards: Array<{
+        shardIndex: number;
+        browser: string;
+    }>): Promise<Prisma.BatchPayload>;
+    getTestRun(tenantId: string, runId: string): Promise<({
+        results: {
+            error: string | null;
+            tenantId: string;
+            id: string;
+            status: string;
+            testCaseId: string;
+            runId: string;
+            duration: number | null;
+            screenshotPath: string | null;
+            logs: Prisma.JsonValue | null;
+            healedAt: Date | null;
+            failureAnalysis: string | null;
+            failureAnalysisAt: Date | null;
+            dataRowId: string | null;
+            dataRowIndex: number | null;
+        }[];
+    } & {
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        summary: Prisma.JsonValue | null;
+        suiteId: string | null;
+        trigger: string;
+        config: Prisma.JsonValue | null;
+        totalShards: number | null;
+        githubRepo: string | null;
+        githubSha: string | null;
+        githubRef: string | null;
+        triggeredBy: string | null;
+        startedAt: Date;
+        finishedAt: Date | null;
+    }) | null>;
+    listTestRuns(tenantId: string, projectId: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        summary: Prisma.JsonValue | null;
+        suiteId: string | null;
+        trigger: string;
+        config: Prisma.JsonValue | null;
+        totalShards: number | null;
+        githubRepo: string | null;
+        githubSha: string | null;
+        githubRef: string | null;
+        triggeredBy: string | null;
+        startedAt: Date;
+        finishedAt: Date | null;
+    }[]>;
+    saveTestResult(tenantId: string, result: {
+        runId: string;
+        testCaseId: string;
+        status: string;
+        duration?: number;
+        error?: string;
+        failureAnalysis?: string;
+        failureAnalysisAt?: Date;
+        dataRowId?: string;
+        dataRowIndex?: number;
+        logs?: Record<string, unknown>;
+    }): Promise<{
+        error: string | null;
+        tenantId: string;
+        id: string;
+        status: string;
+        testCaseId: string;
+        runId: string;
+        duration: number | null;
+        screenshotPath: string | null;
+        logs: Prisma.JsonValue | null;
+        healedAt: Date | null;
+        failureAnalysis: string | null;
+        failureAnalysisAt: Date | null;
+        dataRowId: string | null;
+        dataRowIndex: number | null;
+    }>;
+    completeTestRun(tenantId: string, runId: string, summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        duration: number;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        summary: Prisma.JsonValue | null;
+        suiteId: string | null;
+        trigger: string;
+        config: Prisma.JsonValue | null;
+        totalShards: number | null;
+        githubRepo: string | null;
+        githubSha: string | null;
+        githubRef: string | null;
+        triggeredBy: string | null;
+        startedAt: Date;
+        finishedAt: Date | null;
+    }>;
+    failTestRun(tenantId: string, runId: string, error: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        summary: Prisma.JsonValue | null;
+        suiteId: string | null;
+        trigger: string;
+        config: Prisma.JsonValue | null;
+        totalShards: number | null;
+        githubRepo: string | null;
+        githubSha: string | null;
+        githubRef: string | null;
+        triggeredBy: string | null;
+        startedAt: Date;
+        finishedAt: Date | null;
+    }>;
+    cancelTestRun(tenantId: string, runId: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        summary: Prisma.JsonValue | null;
+        suiteId: string | null;
+        trigger: string;
+        config: Prisma.JsonValue | null;
+        totalShards: number | null;
+        githubRepo: string | null;
+        githubSha: string | null;
+        githubRef: string | null;
+        triggeredBy: string | null;
+        startedAt: Date;
+        finishedAt: Date | null;
+    }>;
+    getTestCaseForExecution(tenantId: string, testCaseId: string): Promise<({
+        screen: ({
+            project: {
+                tenantId: string;
+                id: string;
+                name: string;
+                status: string;
+                slug: string;
+                description: string | null;
+                createdAt: Date;
+                updatedAt: Date;
+                appUrl: string | null;
+                figmaUrl: string | null;
+                appType: string | null;
+                crawlConfig: Prisma.JsonValue | null;
+                ciFailureThreshold: number | null;
+                slaThreshold: number | null;
+                visualDiffThreshold: number | null;
+                oversized: boolean;
+                restricted: boolean;
+                vsaEnabled: boolean;
+                workspaceId: string | null;
+            };
+        } & {
+            tenantId: string;
+            id: string;
+            projectId: string;
+            name: string;
+            url: string | null;
+            version: number;
+            groupId: string | null;
+            figmaMatch: number | null;
+            a11yScore: number | null;
+            lastSeenAt: Date;
+            status: string;
+            lastCrawlJobId: string | null;
+            removedAt: Date | null;
+            removalReason: string | null;
+            discoveryMethod: string;
+            elementHash: string | null;
+            elementHashChangedAt: Date | null;
+            domSnapshotPath: string | null;
+            domSnapshotCloudUrl: string | null;
+            requiresAuth: boolean;
+            depth: number | null;
+            parentUrl: string | null;
+            roleAccess: string[];
+            markdownPath: string | null;
+            markdownContent: string | null;
+            markdownMethod: string | null;
+            markdownWordCount: number | null;
+            aiSummary: string | null;
+        }) | null;
+        dataSet: ({
+            rows: {
+                data: Prisma.JsonValue;
+                tenantId: string;
+                id: string;
+                dataSetId: string;
+                rowIndex: number;
+            }[];
+        } & {
+            tenantId: string;
+            id: string;
+            projectId: string;
+            name: string;
+            createdAt: Date;
+            classification: string;
+            environment: string | null;
+        }) | null;
+    } & {
+        tenantId: string;
+        screenId: string | null;
+        id: string;
+        projectId: string;
+        source: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        steps: Prisma.JsonValue;
+        kind: string;
+        tags: Prisma.JsonValue;
+        approvedBy: string | null;
+        suiteId: string;
+        ref: string | null;
+        title: string;
+        priority: string;
+        preconditions: string | null;
+        expectedResult: string | null;
+        gherkin: string | null;
+        approvedAt: Date | null;
+        groundedOn: Prisma.JsonValue;
+        caseRefs: Prisma.JsonValue;
+        viewports: Prisma.JsonValue;
+        viewportConstraint: string;
+        techniqueOfRecord: string | null;
+        traceTo: string | null;
+        traceToExtra: Prisma.JsonValue;
+        testDataInline: Prisma.JsonValue | null;
+        dataNote: string | null;
+        scriptNote: string | null;
+        structuredSteps: Prisma.JsonValue | null;
+        artifactId: string | null;
+        scenarioId: string | null;
+        suspect: boolean;
+        suspectReason: string | null;
+        flakyScore: number;
+        consecutiveFlakes: number;
+        lastFlakyAt: Date | null;
+        quarantined: boolean;
+        quarantinedAt: Date | null;
+        quarantineReason: string | null;
+        genPromptTokens: number | null;
+        genCompletionTokens: number | null;
+        genCostUsd: number | null;
+        genModel: string | null;
+        dataSetId: string | null;
+        repoTargetPath: string | null;
+        stepsKey: string | null;
+        gherkinKey: string | null;
+        contentHash: string | null;
+        groundingHash: string | null;
+        locatorsJson: Prisma.JsonValue | null;
+        locatorsExtractedAt: Date | null;
+        captureStepScreenshots: Prisma.JsonValue | null;
+    }) | null>;
+    createTestCaseRun(tenantId: string, testCaseId: string, viewport: string, browser?: string): Promise<unknown>;
+    updateTestCaseRun(tenantId: string, runId: string, data: {
+        status?: string;
+        executionPlan?: any;
+        stepResults?: any;
+        totalDuration?: number;
+        errorStep?: number | null;
+        errorMessage?: string;
+        screenshotPath?: string | null;
+        completedAt?: Date;
+    }): Promise<unknown>;
+    getTestCaseRun(tenantId: string, runId: string): Promise<unknown>;
+    /**
+     * Recomputes rolling flakiness stats for a test case from its run history and
+     * writes them back to TestCase. Call after every settled TestCaseRun (PASSED/
+     * FAILED/FLAKY/ERROR) — ERROR rows are excluded from the window itself (infra
+     * failures, not app flakiness) but recording still runs so stats stay current.
+     *
+     * flakyScore: fraction of the last WINDOW_SIZE non-ERROR outcomes that were
+     * FAILED or FLAKY (0.0-1.0) — see docs/13-TEST-FLAKINESS-DETECTION.md.
+     * consecutiveFlakes: current losing streak (FAILED/FLAKY), reset by a PASS.
+     * Auto-quarantine requires BOTH a high flaky score AND at least one PASSED in
+     * the window — a consistently-failing test is a bug, not flakiness, and must
+     * not be silently hidden from the suite by quarantine.
+     */
+    recordFlakinessOutcome(tenantId: string, testCaseId: string): Promise<{
+        tenantId: string;
+        screenId: string | null;
+        id: string;
+        projectId: string;
+        source: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        steps: Prisma.JsonValue;
+        kind: string;
+        tags: Prisma.JsonValue;
+        approvedBy: string | null;
+        suiteId: string;
+        ref: string | null;
+        title: string;
+        priority: string;
+        preconditions: string | null;
+        expectedResult: string | null;
+        gherkin: string | null;
+        approvedAt: Date | null;
+        groundedOn: Prisma.JsonValue;
+        caseRefs: Prisma.JsonValue;
+        viewports: Prisma.JsonValue;
+        viewportConstraint: string;
+        techniqueOfRecord: string | null;
+        traceTo: string | null;
+        traceToExtra: Prisma.JsonValue;
+        testDataInline: Prisma.JsonValue | null;
+        dataNote: string | null;
+        scriptNote: string | null;
+        structuredSteps: Prisma.JsonValue | null;
+        artifactId: string | null;
+        scenarioId: string | null;
+        suspect: boolean;
+        suspectReason: string | null;
+        flakyScore: number;
+        consecutiveFlakes: number;
+        lastFlakyAt: Date | null;
+        quarantined: boolean;
+        quarantinedAt: Date | null;
+        quarantineReason: string | null;
+        genPromptTokens: number | null;
+        genCompletionTokens: number | null;
+        genCostUsd: number | null;
+        genModel: string | null;
+        dataSetId: string | null;
+        repoTargetPath: string | null;
+        stepsKey: string | null;
+        gherkinKey: string | null;
+        contentHash: string | null;
+        groundingHash: string | null;
+        locatorsJson: Prisma.JsonValue | null;
+        locatorsExtractedAt: Date | null;
+        captureStepScreenshots: Prisma.JsonValue | null;
+    } | null>;
+    /** Human-driven quarantine toggle. Auto-quarantine never clears itself — lifting it is always explicit. */
+    setTestCaseQuarantine(tenantId: string, testCaseId: string, quarantined: boolean, reason?: string): Promise<{
+        tenantId: string;
+        screenId: string | null;
+        id: string;
+        projectId: string;
+        source: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        steps: Prisma.JsonValue;
+        kind: string;
+        tags: Prisma.JsonValue;
+        approvedBy: string | null;
+        suiteId: string;
+        ref: string | null;
+        title: string;
+        priority: string;
+        preconditions: string | null;
+        expectedResult: string | null;
+        gherkin: string | null;
+        approvedAt: Date | null;
+        groundedOn: Prisma.JsonValue;
+        caseRefs: Prisma.JsonValue;
+        viewports: Prisma.JsonValue;
+        viewportConstraint: string;
+        techniqueOfRecord: string | null;
+        traceTo: string | null;
+        traceToExtra: Prisma.JsonValue;
+        testDataInline: Prisma.JsonValue | null;
+        dataNote: string | null;
+        scriptNote: string | null;
+        structuredSteps: Prisma.JsonValue | null;
+        artifactId: string | null;
+        scenarioId: string | null;
+        suspect: boolean;
+        suspectReason: string | null;
+        flakyScore: number;
+        consecutiveFlakes: number;
+        lastFlakyAt: Date | null;
+        quarantined: boolean;
+        quarantinedAt: Date | null;
+        quarantineReason: string | null;
+        genPromptTokens: number | null;
+        genCompletionTokens: number | null;
+        genCostUsd: number | null;
+        genModel: string | null;
+        dataSetId: string | null;
+        repoTargetPath: string | null;
+        stepsKey: string | null;
+        gherkinKey: string | null;
+        contentHash: string | null;
+        groundingHash: string | null;
+        locatorsJson: Prisma.JsonValue | null;
+        locatorsExtractedAt: Date | null;
+        captureStepScreenshots: Prisma.JsonValue | null;
+    }>;
+    saveVisualBaseline(tenantId: string, projectId: string, screenId: string, storagePath: string, viewport: string, approvedBy?: string, gitBranch?: string, cloudUrl?: string): Promise<{
+        tenantId: string;
+        screenId: string;
+        id: string;
+        projectId: string;
+        viewport: string;
+        createdAt: Date;
+        storagePath: string;
+        cloudUrl: string | null;
+        approvedBy: string | null;
+        browser: string;
+        gitBranch: string;
+        gitCommit: string | null;
+        ignoredRegions: Prisma.JsonValue;
+        elementSnapshot: Prisma.JsonValue | null;
+    }>;
+    ensureVisualBaselinesForProject(tenantId: string, projectId: string, gitBranch?: string): Promise<{
+        created: number;
+    }>;
+    getVisualBaseline(tenantId: string, screenId: string, viewport: string, gitBranch?: string): Promise<{
+        tenantId: string;
+        screenId: string;
+        id: string;
+        projectId: string;
+        viewport: string;
+        createdAt: Date;
+        storagePath: string;
+        cloudUrl: string | null;
+        approvedBy: string | null;
+        browser: string;
+        gitBranch: string;
+        gitCommit: string | null;
+        ignoredRegions: Prisma.JsonValue;
+        elementSnapshot: Prisma.JsonValue | null;
+    } | null>;
+    updateBaselineIgnoredRegions(tenantId: string, screenId: string, viewport: string, regions: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        label?: string;
+    }>, gitBranch?: string): Promise<void>;
+    getVisualBaselineForDiff(tenantId: string, screenId: string, viewport: string, gitBranch?: string): Promise<{
+        id: string;
+        storagePath: string;
+        cloudUrl?: string;
+        ignoredRegions: Array<{
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }>;
+    } | null>;
+    saveVisualDiff(tenantId: string, diff: {
+        baselineId: string;
+        newScreenshotPath: string;
+        newScreenshotCloudUrl?: string;
+        diffImageCloudUrl?: string;
+        diffScore: number;
+        changeType: string;
+        changes: any[];
+        recommendation: string;
+        bugReportDraft?: any;
+        aiSummary?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        status: string;
+        aiSummary: string | null;
+        createdAt: Date;
+        baselineId: string;
+        newScreenshotPath: string;
+        newScreenshotCloudUrl: string | null;
+        diffImageCloudUrl: string | null;
+        diffScore: number;
+        changeType: string;
+        changes: Prisma.JsonValue | null;
+        recommendation: string | null;
+        bugReportDraft: Prisma.JsonValue | null;
+        reviewedBy: string | null;
+    }>;
+    saveElementFingerprint(tenantId: string, projectId: string, elementId: string, selectors: any[]): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        elementId: string;
+        selectors: Prisma.JsonValue;
+        lastHealedAt: Date | null;
+        healCount: number;
+    }>;
+    getElementFingerprint(tenantId: string, elementId: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        elementId: string;
+        selectors: Prisma.JsonValue;
+        lastHealedAt: Date | null;
+        healCount: number;
+    } | null>;
+    recordElementHeal(tenantId: string, elementId: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        elementId: string;
+        selectors: Prisma.JsonValue;
+        lastHealedAt: Date | null;
+        healCount: number;
+    }>;
+    getCoverageReport(tenantId: string, projectId: string): Promise<{
+        totalScreens: number;
+        screensWithTests: number;
+        coveragePercent: number;
+        screenDesignCoveragePercent: number;
+        screenApprovedCoveragePercent: number;
+        screensWithApprovedTests: number;
+        totalTestCases: number;
+        approvedTestCases: number;
+        pendingReviewCases: number;
+        targetCoverage: number;
+        gapToTarget: number;
+        status: string;
+        byKind: Record<string, number> | undefined;
+        byPriority: Record<string, number> | undefined;
+        byTechnique: Record<string, number> | undefined;
+        gaps: string[] | undefined;
+        requirementsTotal: number | null;
+        requirementsCovered: number | null;
+        requirementCoveragePercent: number | null;
+        requirementDesignCoveragePercent: number | null;
+        requirementApprovedTraceCoveragePercent: number | null;
+        requirementsWithLinkedTests: number | null;
+        requirementsWithApprovedLinkedTests: number | null;
+        requirementsUntested: number | null;
+        requirementsUnbuilt: number | null;
+        riskWeightedCoverage: number | null;
+        untestedRequirements: {
+            reqId: string;
+            title: string;
+            priority: string;
+        }[] | undefined;
+        unbuiltRequirements: {
+            reqId: string;
+            title: string;
+            priority: string;
+        }[] | undefined;
+        requirementsMissingTrace: {
+            reqId: string;
+            title: string;
+            priority: string;
+        }[] | undefined;
+    }>;
+    /**
+     * Persist generated tests as pending review; callers must pass grounded facts.
+     *
+     * Dedup layers (in order):
+     *   1. contentHash  — SHA-256 of normalized(title+steps+expectedResult+preconditions)
+     *   2. groundingHash — SHA-256 of sorted(groundedOn IDs) + kind (structural dedup)
+     *   3. titleJaccard  — stopword-stripped token overlap > SEMANTIC_DEDUP_THRESHOLD (default 0.6)
+     *   4. exact title   — fallback for pre-migration rows that have no stored hash
+     *
+     * mode='append' (default) — skips duplicates, inserts fresh cases.
+     * mode='replace'          — caller must delete existing cases before calling (see deleteScreenTestCases).
+     * mode='edit'             — for hash/similarity matches, upserts existing case (updates steps/gherkin/
+     *                           expectedResult, snapshots old version, clears suspect flag).
+     */
+    saveGeneratedTestCases(tenantId: string, projectId: string, suiteName: string, cases: Array<{
+        title: string;
+        kind: TestKind;
+        priority?: string;
+        preconditions?: string;
+        steps: unknown[];
+        expectedResult?: string;
+        groundedOn: string[];
+        gherkin?: string;
+        tags?: string[];
+        caseRefs?: string[];
+        source?: string;
+        screenId?: string;
+        ref?: string;
+        techniqueOfRecord?: string;
+        traceTo?: string;
+        testDataInline?: Record<string, unknown>;
+        viewportConstraint?: string;
+        dataNote?: string;
+        scriptNote?: string;
+        structuredSteps?: Array<{
+            action: string;
+            target?: string;
+            data?: string;
+        }>;
+    }>, usageStats?: {
+        totalTokens: number;
+        estimatedCostUsd: number;
+        model: string;
+        screenCount?: number;
+        coverageReport?: unknown;
+    }, mode?: "append" | "replace" | "edit"): Promise<{
+        suite: {
+            tenantId: string;
+            id: string;
+            projectId: string;
+            name: string;
+            createdAt: Date;
+            genModel: string | null;
+            category: import(".prisma/client").$Enums.SuiteCategory | null;
+            parentId: string | null;
+            ownerUserId: string | null;
+            genTotalTokens: number | null;
+            genTotalCostUsd: number | null;
+            genAt: Date | null;
+            genScreenCount: number | null;
+            coverageReport: Prisma.JsonValue | null;
+        };
+        testCases: {
+            tenantId: string;
+            screenId: string | null;
+            id: string;
+            projectId: string;
+            source: string;
+            status: string;
+            createdAt: Date;
+            updatedAt: Date;
+            steps: Prisma.JsonValue;
+            kind: string;
+            tags: Prisma.JsonValue;
+            approvedBy: string | null;
+            suiteId: string;
+            ref: string | null;
+            title: string;
+            priority: string;
+            preconditions: string | null;
+            expectedResult: string | null;
+            gherkin: string | null;
+            approvedAt: Date | null;
+            groundedOn: Prisma.JsonValue;
+            caseRefs: Prisma.JsonValue;
+            viewports: Prisma.JsonValue;
+            viewportConstraint: string;
+            techniqueOfRecord: string | null;
+            traceTo: string | null;
+            traceToExtra: Prisma.JsonValue;
+            testDataInline: Prisma.JsonValue | null;
+            dataNote: string | null;
+            scriptNote: string | null;
+            structuredSteps: Prisma.JsonValue | null;
+            artifactId: string | null;
+            scenarioId: string | null;
+            suspect: boolean;
+            suspectReason: string | null;
+            flakyScore: number;
+            consecutiveFlakes: number;
+            lastFlakyAt: Date | null;
+            quarantined: boolean;
+            quarantinedAt: Date | null;
+            quarantineReason: string | null;
+            genPromptTokens: number | null;
+            genCompletionTokens: number | null;
+            genCostUsd: number | null;
+            genModel: string | null;
+            dataSetId: string | null;
+            repoTargetPath: string | null;
+            stepsKey: string | null;
+            gherkinKey: string | null;
+            contentHash: string | null;
+            groundingHash: string | null;
+            locatorsJson: Prisma.JsonValue | null;
+            locatorsExtractedAt: Date | null;
+            captureStepScreenshots: Prisma.JsonValue | null;
+        }[];
+    }>;
+    /**
+     * Delete all generated test cases for a specific screen in a suite.
+     * Used by replace-mode generation to clear stale cases before re-inserting.
+     */
+    deleteScreenTestCases(tenantId: string, projectId: string, suiteName: string, screenId: string): Promise<{
+        deleted: number;
+    }>;
+    getTenantLLMConfig(tenantId: string): Promise<{
+        provider: string;
+        model: string;
+        apiKey?: string;
+        baseUrl?: string;
+        customModels?: Record<string, string[]>;
+        crawlProvider?: string;
+        crawlApiKey?: string;
+        taskOverrides?: Record<string, {
+            provider: string;
+            model: string;
+            apiKey?: string;
+            baseUrl?: string;
+        }>;
+    } | null>;
+    getTaskLLMConfig(tenantId: string, task: LLMTaskType): Promise<{
+        provider: string;
+        model: string;
+        apiKey?: string;
+        baseUrl?: string;
+    } | null>;
+    saveTenantLLMConfig(tenantId: string, data: {
+        provider: string;
+        model: string;
+        apiKey?: string | null;
+        baseUrl?: string;
+        customModels?: Record<string, string[]>;
+        crawlProvider?: string;
+        crawlApiKey?: string;
+        taskOverrides?: Record<string, {
+            provider: string;
+            model: string;
+            apiKey?: string;
+            baseUrl?: string;
+        }>;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantLLMConfigRedacted(tenantId: string): Promise<{
+        provider: string;
+        model: string;
+        apiKeyConfigured: boolean;
+        baseUrl?: string;
+        customModels?: Record<string, string[]>;
+        crawlProvider?: string;
+        crawlApiKeyConfigured: boolean;
+        taskOverrides?: Record<string, {
+            provider: string;
+            model: string;
+            apiKeyConfigured: boolean;
+            baseUrl?: string;
+        }>;
+    } | null>;
+    getOnboardingStatus(tenantId: string, userId: string): Promise<{
+        dismissed: boolean;
+        dismissedAt: string | null;
+        steps: Array<{
+            id: string;
+            label: string;
+            description: string;
+            done: boolean;
+            optional: boolean;
+            href: string;
+        }>;
+        projectSteps: Array<{
+            projectId: string;
+            projectName: string;
+            type: string;
+            stepId: string;
+            label: string;
+            description: string;
+            done: boolean;
+            href: string;
+        }>;
+        allRequiredDone: boolean;
+    }>;
+    dismissOnboarding(tenantId: string): Promise<void>;
+    getTenantEmailConfig(tenantId: string): Promise<{
+        provider: string;
+        resendApiKey?: string;
+        smtpHost?: string;
+        smtpPort?: number;
+        smtpUser?: string;
+        smtpPass?: string;
+        fromEmail?: string;
+        fromName?: string;
+    } | null>;
+    saveTenantEmailConfig(tenantId: string, data: {
+        provider: string;
+        resendApiKey?: string;
+        smtpHost?: string;
+        smtpPort?: number;
+        smtpUser?: string;
+        smtpPass?: string;
+        fromEmail?: string;
+        fromName?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantNotificationsConfig(tenantId: string): Promise<{
+        globalWebhookUrl?: string;
+        slackWebhookUrl?: string;
+        alertEmails?: string[];
+    } | null>;
+    saveTenantNotificationsConfig(tenantId: string, data: {
+        globalWebhookUrl?: string;
+        slackWebhookUrl?: string;
+        alertEmails?: string[];
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantBrandingConfig(tenantId: string): Promise<{
+        primaryColor?: string;
+        logoUrl?: string;
+    } | null>;
+    saveTenantBrandingConfig(tenantId: string, data: {
+        primaryColor?: string;
+        logoUrl?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantEmailConfigRedacted(tenantId: string): Promise<{
+        provider: string;
+        resendConfigured: boolean;
+        smtpHost?: string;
+        smtpPort?: number;
+        smtpUser?: string;
+        fromEmail?: string;
+        fromName?: string;
+    } | null>;
+    saveTenantStorageConfig(tenantId: string, data: {
+        provider: string;
+        bucket: string;
+        region?: string;
+        accountId?: string;
+        endpointUrl?: string;
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        publicUrl?: string;
+        prefix?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantStorageConfigRedacted(tenantId: string): Promise<{
+        provider: string;
+        bucket: string;
+        region?: string;
+        accountId?: string;
+        endpointUrl?: string;
+        accessKeyIdConfigured: boolean;
+        secretKeyConfigured: boolean;
+        publicUrl?: string;
+        prefix?: string;
+        source: "tenant" | "platform";
+    } | null>;
+    /** Persist a confirmed header→field mapping for future auto-apply. */
+    saveImportMapping(tenantId: string, signature: string, mapping: Record<string, unknown>): Promise<void>;
+    /** Load a saved header→field mapping by its signature, or null if none saved. */
+    loadImportMapping(tenantId: string, signature: string): Promise<Record<string, unknown> | null>;
+    getTenantCaptchaConfig(tenantId: string): Promise<{
+        provider: string;
+        apiKey: string;
+    } | null>;
+    saveTenantCaptchaConfig(tenantId: string, data: {
+        provider: string;
+        apiKey?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantCaptchaConfigRedacted(tenantId: string): Promise<{
+        provider: string;
+        configured: boolean;
+    } | null>;
+    getTenantEmailOTPConfig(tenantId: string): Promise<{
+        provider: string;
+        apiKey?: string;
+        inboxId?: string;
+        imapHost?: string;
+        imapPort?: number;
+        imapUser?: string;
+        imapPass?: string;
+        imapTls?: boolean;
+    } | null>;
+    saveTenantEmailOTPConfig(tenantId: string, data: {
+        provider: string;
+        apiKey?: string;
+        inboxId?: string;
+        imapHost?: string;
+        imapPort?: number;
+        imapUser?: string;
+        imapPass?: string;
+        imapTls?: boolean;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantEmailOTPConfigRedacted(tenantId: string): Promise<{
+        provider: string;
+        configured: boolean;
+        inboxId?: string;
+        imapHost?: string;
+        imapPort?: number;
+        imapUser?: string;
+        imapTls?: boolean;
+    } | null>;
+    getTenantSkyvernConfig(tenantId: string): Promise<{
+        apiUrl: string;
+        apiKey: string;
+        llmKey?: string;
+    } | null>;
+    saveTenantSkyvernConfig(tenantId: string, data: {
+        apiUrl?: string;
+        apiKey?: string;
+        llmKey?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantProxyConfig(tenantId: string): Promise<{
+        mode: "none" | "auto" | "custom";
+        proxyUrl?: string;
+    } | null>;
+    saveTenantProxyConfig(tenantId: string, data: {
+        mode: "none" | "auto" | "custom";
+        proxyUrl?: string | null;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantSkyvernConfigRedacted(tenantId: string): Promise<{
+        apiUrl: string;
+        configured: boolean;
+        llmKey?: string;
+    } | null>;
+    getTenantDeviceFarmConfig(tenantId: string): Promise<{
+        appiumServerUrl?: string;
+        browserstackUsername?: string;
+        browserstackAccessKey?: string;
+        awsAccessKeyId?: string;
+        awsSecretAccessKey?: string;
+        awsRegion?: string;
+        awsDeviceFarmProjectArn?: string;
+    } | null>;
+    saveTenantDeviceFarmConfig(tenantId: string, data: {
+        appiumServerUrl?: string;
+        browserstackUsername?: string;
+        browserstackAccessKey?: string;
+        awsAccessKeyId?: string;
+        awsSecretAccessKey?: string;
+        awsRegion?: string;
+        awsDeviceFarmProjectArn?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        updatedAt: Date;
+        category: string;
+        config: Prisma.JsonValue;
+        dataRetentionDays: number;
+    }>;
+    getTenantDeviceFarmConfigRedacted(tenantId: string): Promise<{
+        appiumServerUrl: string;
+        browserstackUsername: string;
+        browserstackConfigured: boolean;
+        awsAccessKeyId: string;
+        awsConfigured: boolean;
+        awsRegion: string;
+        awsDeviceFarmProjectArn: string;
+    }>;
+    getConnectorConfig(tenantId: string, projectId: string, kind: string): Promise<Record<string, string> | null>;
+    logChange(tenantId: string, projectId: string, changeType: "ADDED" | "REMOVED" | "MODIFIED", summary: string, detail?: any): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        createdAt: Date;
+        summary: string;
+        changeType: string;
+        detail: Prisma.JsonValue | null;
+    }>;
+    listChangeLogs(tenantId: string, projectId: string, limit?: number): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        createdAt: Date;
+        summary: string;
+        changeType: string;
+        detail: Prisma.JsonValue | null;
+    }[]>;
+    getTenantInfo(tenantId: string): Promise<{
+        name: string;
+        slug: string;
+    } | null>;
+    /** Save or update an OAuth connection. Tokens are encrypted before storage. */
+    upsertOAuthConnection(tenantId: string, projectId: string, provider: string, data: {
+        accessToken?: string | null;
+        refreshToken?: string | null;
+        tokenExpiresAt?: Date | null;
+        refreshTokenExpiresAt?: Date | null;
+        status?: string;
+        connectedAs?: string | null;
+        installationId?: string | null;
+        cloudId?: string | null;
+        scopes?: string | null;
+        pat?: string | null;
+        dcBaseUrl?: string | null;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: string;
+        accessToken_enc: string | null;
+        refreshToken_enc: string | null;
+        tokenExpiresAt: Date | null;
+        refreshTokenExpiresAt: Date | null;
+        connectedAs: string | null;
+        installationId: string | null;
+        cloudId: string | null;
+        scopes: string | null;
+        pat_enc: string | null;
+        dcBaseUrl: string | null;
+    }>;
+    /** Get an OAuth connection with tokens decrypted. Returns null if not found. */
+    getOAuthConnection(tenantId: string, projectId: string, provider: string): Promise<{
+        accessToken: string | null;
+        refreshToken: string | null;
+        pat: string | null;
+        accessToken_enc: undefined;
+        refreshToken_enc: undefined;
+        pat_enc: undefined;
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: string;
+        tokenExpiresAt: Date | null;
+        refreshTokenExpiresAt: Date | null;
+        connectedAs: string | null;
+        installationId: string | null;
+        cloudId: string | null;
+        scopes: string | null;
+        dcBaseUrl: string | null;
+    } | null>;
+    /** List all OAuth connections for a project (tokens redacted). */
+    listOAuthConnections(tenantId: string, projectId: string): Promise<{
+        id: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: string;
+        tokenExpiresAt: Date | null;
+        refreshTokenExpiresAt: Date | null;
+        connectedAs: string | null;
+        installationId: string | null;
+        cloudId: string | null;
+        scopes: string | null;
+    }[]>;
+    /** Set connection status (CONNECTED | NEEDS_REAUTH | DISCONNECTED). */
+    setOAuthConnectionStatus(tenantId: string, projectId: string, provider: string, status: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: string;
+        accessToken_enc: string | null;
+        refreshToken_enc: string | null;
+        tokenExpiresAt: Date | null;
+        refreshTokenExpiresAt: Date | null;
+        connectedAs: string | null;
+        installationId: string | null;
+        cloudId: string | null;
+        scopes: string | null;
+        pat_enc: string | null;
+        dcBaseUrl: string | null;
+    }>;
+    /** Delete an OAuth connection (user disconnects). */
+    deleteOAuthConnection(tenantId: string, projectId: string, provider: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        status: string;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: string;
+        accessToken_enc: string | null;
+        refreshToken_enc: string | null;
+        tokenExpiresAt: Date | null;
+        refreshTokenExpiresAt: Date | null;
+        connectedAs: string | null;
+        installationId: string | null;
+        cloudId: string | null;
+        scopes: string | null;
+        pat_enc: string | null;
+        dcBaseUrl: string | null;
+    }>;
+    /**
+     * Auto-create a VisualBaseline entry after crawl if one doesn't exist yet for this (screenId, viewport).
+     * Called after saving a screenshot — creates the baseline on first crawl, skips on recrawls.
+     */
+    autoCreateVisualBaseline(tenantId: string, projectId: string, screenId: string, viewport: string, storagePath: string, gitBranch?: string, gitCommit?: string): Promise<void>;
+    computeElementLayoutDiff(tenantId: string, screenId: string, viewport: string, gitBranch?: string): Promise<Array<{
+        element: string;
+        shiftX: number;
+        shiftY: number;
+        shiftW: number;
+        shiftH: number;
+        severity: string;
+        description: string;
+    }>>;
+    /** Store probe observation markdown as BM25-indexed KnowledgeChunks for a screen. */
+    saveKnowledgeChunk(tenantId: string, projectId: string, sourceType: string, sourceId: string, markdown: string, fallbackHeading: string): Promise<void>;
+    saveCrawlEvidence(tenantId: string, projectId: string, data: {
+        screenId?: string;
+        jobId?: string;
+        type: string;
+        payload: any;
+    }): Promise<{
+        tenantId: string;
+        screenId: string | null;
+        id: string;
+        projectId: string;
+        createdAt: Date;
+        payload: Prisma.JsonValue;
+        jobId: string | null;
+        type: string;
+    }>;
+    saveScreenTransition(tenantId: string, projectId: string, data: {
+        fromScreenId: string;
+        toScreenId?: string | null;
+        action: any;
+        confidence?: number;
+        jobId?: string;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        createdAt: Date;
+        confidence: number;
+        action: Prisma.JsonValue;
+        jobId: string | null;
+        fromScreenId: string;
+        toScreenId: string | null;
+    }>;
+    saveDiscoveredLinks(tenantId: string, projectId: string, fromScreenId: string, links: Array<{
+        href: string;
+        text?: string;
+        landmark?: string;
+        linkType?: string;
+        source?: string;
+        confidence?: number;
+        toScreenId?: string;
+        jobId?: string;
+    }>): Promise<Prisma.BatchPayload | undefined>;
+    resolveDiscoveredLinkTargets(tenantId: string, projectId: string, jobId: string, hrefToScreenId: Map<string, string>): Promise<void>;
+    saveActionRecipe(tenantId: string, projectId: string, data: {
+        domain: string;
+        purpose: string;
+        fingerprint: string;
+        steps: any;
+        successRate?: number;
+        lastUsedAt?: Date;
+    }): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        createdAt: Date;
+        updatedAt: Date;
+        fingerprint: string;
+        steps: Prisma.JsonValue;
+        domain: string;
+        purpose: string;
+        successRate: number;
+        lastUsedAt: Date | null;
+    }>;
+    saveApiEndpointObservations(tenantId: string, projectId: string, screenId: string | undefined, observations: Array<{
+        method: string;
+        urlPattern: string;
+        statusCode?: number;
+        requestKind?: string;
+        responseShape?: unknown;
+    }>): Promise<Prisma.BatchPayload>;
+    /** Look up the best matching ActionRecipe for replay-first self-healing. */
+    getActionRecipe(tenantId: string, projectId: string, domain: string, purpose: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        createdAt: Date;
+        updatedAt: Date;
+        fingerprint: string;
+        steps: Prisma.JsonValue;
+        domain: string;
+        purpose: string;
+        successRate: number;
+        lastUsedAt: Date | null;
+    } | null>;
+    /** Mark an ActionRecipe as failed (decrement successRate). */
+    recordActionRecipeFailure(tenantId: string, id: string): Promise<{
+        tenantId: string;
+        id: string;
+        projectId: string;
+        createdAt: Date;
+        updatedAt: Date;
+        fingerprint: string;
+        steps: Prisma.JsonValue;
+        domain: string;
+        purpose: string;
+        successRate: number;
+        lastUsedAt: Date | null;
+    }>;
+    getWorkspaceConnector(tenantId: string, kind: string): Promise<{
+        id: any;
+        kind: any;
+        testOk: any;
+        testedAt: any;
+        config: Record<string, string>;
+    } | null>;
+    saveWorkspaceConnector(tenantId: string, kind: string, config: Record<string, string>, encryptKeys: string[]): Promise<{
+        tenantId: string;
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        kind: string;
+        config: Prisma.JsonValue | null;
+        secretRef: string;
+        testOk: boolean;
+        testedAt: Date | null;
+    }>;
+    deleteWorkspaceConnector(tenantId: string, kind: string): Promise<{
+        tenantId: string;
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        kind: string;
+        config: Prisma.JsonValue | null;
+        secretRef: string;
+        testOk: boolean;
+        testedAt: Date | null;
+    } | null>;
+    listWorkspaceConnectors(tenantId: string): Promise<{
+        id: any;
+        kind: any;
+        testOk: any;
+        testedAt: any;
+        config: Record<string, any>;
+    }[]>;
+    markWorkspaceConnectorTested(tenantId: string, kind: string, ok: boolean): Promise<{
+        tenantId: string;
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        kind: string;
+        config: Prisma.JsonValue | null;
+        secretRef: string;
+        testOk: boolean;
+        testedAt: Date | null;
+    } | null>;
+    createSharedRunToken(tenantId: string, runId: string, ttlHours?: number): Promise<{
+        tenantId: string;
+        id: string;
+        createdAt: Date;
+        runId: string;
+        token: string;
+        expiresAt: Date;
+    }>;
+    getSharedRunToken(token: string): Promise<{
+        tenantId: string;
+        id: string;
+        createdAt: Date;
+        runId: string;
+        token: string;
+        expiresAt: Date;
+    } | null>;
+    getWorkspaceSsoProviders(tenantId: string): Promise<Array<{
+        id: string;
+        name: string;
+        provider: string;
+        domain: string;
+        clientId: string;
+        clientSecret?: string;
+        scope?: string;
+        defaultRole?: string;
+    }>>;
+    saveWorkspaceSsoProviders(tenantId: string, providers: Array<{
+        id?: string;
+        name: string;
+        provider: string;
+        domain: string;
+        clientId: string;
+        clientSecret?: string;
+        scope?: string;
+        defaultRole?: string;
+    }>): Promise<void>;
+    getWorkspaceVpnConfig(tenantId: string): Promise<{
+        enabled: boolean;
+        mode: string;
+        provider?: string;
+        gatewayCidrs: string[];
+        jitProvision: boolean;
+        jitDefaultRole: string;
+        fallbackToPassword: boolean;
+        cloudflareTeamDomain?: string;
+        googleIapAudience?: string;
+        awsAlbRegion?: string;
+        azureTenantId?: string;
+        headerEmail?: string;
+        headerUser?: string;
+        headerGroups?: string;
+        providers?: Array<{
+            id: string;
+            provider: string;
+            cloudflareTeamDomain?: string;
+            googleIapAudience?: string;
+            awsAlbRegion?: string;
+            azureTenantId?: string;
+            headerEmail?: string;
+            headerUser?: string;
+            headerGroups?: string;
+        }>;
+    } | null>;
+    saveWorkspaceVpnConfig(tenantId: string, config: {
+        enabled: boolean;
+        mode: string;
+        provider: string;
+        gatewayCidrs: string[];
+        jitProvision: boolean;
+        jitDefaultRole: string;
+        fallbackToPassword: boolean;
+        cloudflareTeamDomain?: string;
+        googleIapAudience?: string;
+        awsAlbRegion?: string;
+        azureTenantId?: string;
+        headerEmail?: string;
+        headerUser?: string;
+        headerGroups?: string;
+    }): Promise<void>;
+    /** Persist a performance snapshot for a screen captured during a crawl job. */
+    savePerformanceSnapshot(tenantId: string, screenId: string, crawlJobId: string, data: {
+        lcp?: number;
+        fcp?: number;
+        cls?: number;
+        ttfb?: number;
+        viewport?: string;
+        lighthousePerf?: number;
+        lighthouseA11y?: number;
+        lighthouseSEO?: number;
+        lighthouseBP?: number;
+        lighthouseReport?: object;
+    }): Promise<unknown>;
+    getVisualDiff(tenantId: string, diffId: string): Promise<unknown>;
+    /**
+     * promoteBaseline: when true and status is APPROVED, each diff's baseline is
+     * also updated to its new screenshot — otherwise "Approve" only marks the
+     * diff reviewed and the next crawl re-diffs against the same (now-stale)
+     * baseline, re-flagging the exact change the reviewer just accepted. Each
+     * diff can have a different baselineId/newScreenshotPath, so this can't be
+     * a single updateMany — it loops per-diff like promoteVisualDiffToBaseline.
+     */
+    bulkUpdateVisualDiffStatus(tenantId: string, diffIds: string[], status: string, reviewedBy: string, promoteBaseline?: boolean): Promise<any>;
+    promoteVisualDiffToBaseline(tenantId: string, diffId: string): Promise<{
+        promoted: boolean;
+    } | null>;
+    importTestCasesFromArtifact(tenantId: string, projectId: string, suiteId: string, cases: Array<{
+        ref?: string;
+        traceTo?: string;
+        caseRefs?: Array<Record<string, unknown>>;
+        title: string;
+        kind: string;
+        priority: string;
+        preconditions?: string;
+        steps: Array<{
+            stepId?: string;
+            action: string;
+            data?: string;
+            expected: string;
+            actualResult?: string;
+            comment?: string;
+            screenshotUrl?: string;
+        }>;
+        expectedResult: string;
+        actualResult?: string;
+        comment?: string;
+        screenshotUrl?: string;
+        gherkin?: string;
+        tags?: string[];
+        section?: string;
+        testDataInline?: Record<string, unknown>;
+    }>, opts?: {
+        duplicateMode?: "skip" | "create" | "replace";
+        artifactId?: string;
+    }): Promise<{
+        created: any[];
+        skipped: number;
+        replaced?: number;
+    }>;
+    /**
+     * Collect unique test-data strings from imported test case steps and upsert them
+     * into a "Imported Test Data" TestDataSet.  Each unique data value becomes one row
+     * labelled by the first test-case title that used it.
+     *
+     * Handles common key-value formats:
+     *   "username: admin | password: pass"  →  { username: 'admin', password: 'pass' }
+     *   "username=admin, password=pass"     →  { username: 'admin', password: 'pass' }
+     *   Plain text                          →  { testData: '<value>' }
+     *
+     * Safe to call repeatedly — replaces the whole set each time.
+     */
+    syncImportedTestDataToDataSet(tenantId: string, projectId: string, cases: Array<{
+        title: string;
+        steps: Array<{
+            data?: string;
+        }>;
+        /** FZE recording form fields — promoted to a dataset row when no step data strings exist. */
+        testDataInline?: Record<string, unknown>;
+    }>, createdCaseIds?: string[]): Promise<void>;
+    /**
+     * Mirror the project's crawl credentials into a "Crawl Credentials" TestDataSet.
+     * Each credential profile (or the main username/password) becomes a TestDataRow.
+     * Called automatically after test case import and when crawl credentials are saved.
+     * Safe to call repeatedly — upserts, never duplicates.
+     */
+    syncCrawlCredentialsToTestData(tenantId: string, projectId: string): Promise<void>;
+    /**
+     * Upsert requirements extracted from a PRD / user stories.
+     * Conflict key: (tenantId, projectId, reqId) — stable re-ingestion safe.
+     */
+    upsertRequirements(tenantId: string, projectId: string, requirements: RequirementUpsertInput[], options?: {
+        flagSuspectOnChange?: boolean;
+    }): Promise<any[]>;
+    /**
+     * Same as upsertRequirements but also reports which requirements were created vs. changed.
+     * "Changed" means a content field differs (title, acceptance criteria, business rules, actor);
+     * priority/status/metadata-only updates do not invalidate downstream tests.
+     * With flagSuspectOnChange, every test case linked to a changed requirement (primary traceTo,
+     * additional traceToExtra, or via its scenario) is flagged suspect in the same transaction.
+     */
+    upsertRequirementsDetailed(tenantId: string, projectId: string, requirements: RequirementUpsertInput[], options?: {
+        flagSuspectOnChange?: boolean;
+    }): Promise<{
+        saved: any[];
+        created: string[];
+        skipped: string[];
+        changed: {
+            reqId: string;
+            fields: string[];
+            version: number;
+        }[];
+        suspectFlagged: number;
+    }>;
+    /**
+     * Replace a test case's requirement links. traceTo stays the primary link; `additional`
+     * holds secondary reqIds (one test covering several stories).
+     */
+    setTraceLinks(tenantId: string, projectId: string, testCaseId: string, links: {
+        traceTo?: string | null;
+        additional?: string[];
+    }): Promise<any>;
+    /**
+     * Repair test cases with a missing or placeholder traceTo by inheriting the requirement of the
+     * scenario they were generated from. Returns the number of test cases repaired.
+     */
+    backfillTraceTo(tenantId: string, projectId: string): Promise<number>;
+    /**
+     * List all requirements for a project, with optional filters.
+     */
+    listRequirements(tenantId: string, projectId: string, filters?: {
+        priority?: string;
+        type?: string;
+        status?: string;
+    }): Promise<unknown>;
+    /**
+     * Semantic similarity search over project requirements.
+     * Uses the cross-encoder to rank requirements by relevance to an arbitrary query.
+     * Useful for: duplicate detection when creating requirements, TC→req trace suggestions.
+     *
+     * @param query        Free text — requirement title, test case title + steps, etc.
+     * @param excludeReqId Optional reqId to exclude from results (e.g. the req being edited).
+     * @param topK         Max results to return (default 5).
+     */
+    findSimilarRequirements(tenantId: string, projectId: string, query: string, excludeReqId?: string, topK?: number): Promise<Array<{
+        reqId: string;
+        title: string;
+        score: number;
+    }>>;
+    /**
+     * Suggest requirement IDs a test case should trace to, ranked by semantic relevance.
+     * Uses the cross-encoder on the TC title + first steps as the query.
+     *
+     * @param tcTitle   Test case title.
+     * @param tcSteps   Test case steps (uses first 5).
+     * @param topK      Max suggestions (default 5).
+     */
+    suggestTraceLinks(tenantId: string, projectId: string, tcTitle: string, tcSteps?: string[], topK?: number): Promise<Array<{
+        reqId: string;
+        title: string;
+        score: number;
+    }>>;
+    /**
+     * Get a single requirement by reqId.
+     */
+    getRequirement(tenantId: string, projectId: string, reqId: string): Promise<unknown>;
+    /**
+     * Update a single requirement (manual correction or status update).
+     */
+    updateRequirement(tenantId: string, projectId: string, reqId: string, patch: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Delete a single requirement.
+     */
+    deleteRequirement(tenantId: string, projectId: string, reqId: string): Promise<unknown>;
+    /**
+     * Bulk-update requirement statuses after coverage matching.
+     * Called by requirements-agent after generateCoverageGapReport().
+     */
+    updateRequirementStatuses(tenantId: string, projectId: string, result: {
+        covered: string[];
+        untested: string[];
+        unbuilt: string[];
+    }): Promise<void>;
+    /**
+     * Delete all requirements for a project (used before re-extraction).
+     */
+    clearRequirements(tenantId: string, projectId: string): Promise<unknown>;
+    upsertScenarios(tenantId: string, projectId: string, requirementId: string, scenarios: Array<{
+        title: string;
+        description?: string;
+        gherkin: string;
+        source?: string;
+    }>): Promise<any[]>;
+    listScenarios(tenantId: string, projectId: string, reqId: string): Promise<any[]>;
+    updateScenario(tenantId: string, scenarioId: string, patch: Record<string, any>): Promise<any | null>;
+    deleteScenario(tenantId: string, scenarioId: string): Promise<void>;
+    flagSuspectByRequirement(tenantId: string, projectId: string, reqId: string, reason: string): Promise<void>;
+    listSuspectTestCases(tenantId: string, projectId: string): Promise<any[]>;
+    clearSuspectFlag(tenantId: string, testCaseId: string): Promise<void>;
+    getWorkspaceSettings(tenantId: string, workspaceId: string): Promise<any | null>;
+    getProject(tenantId: string, projectId: string): Promise<any | null>;
+    getJobActivity(tenantId: string, jobId: string): Promise<{
+        job: any;
+        timeline: any[];
+        screens: any[];
+        transitions: any[];
+        apiEndpoints: any[];
+        aiCost: any;
+        orphans: string[];
+    }>;
+};
+export {};