@lensmcp/protocol-types 1.24.5 → 1.25.1

package/lib/dashboard.d.ts

@@ -10,6 +10,7 @@
  * ({@link DashStreamEvent}); the heavier reads (`/api/flow`, `/api/resource`, `/api/logs`) are
  * on-demand GETs.
  */
+import type { HttpExchange } from './http-exchange.js';
 /** Bumped only on a breaking change to the stream framing itself. */
 export declare const DASHBOARD_PROTOCOL = 1;
 /** The swimlane a flow event belongs to (mirrors `FlowArea` in `@lensmcp/core`'s flow-shape). */
@@ -214,6 +215,12 @@ export interface DashCluster {
     routes: DashRoute[];
     edges: DashEdge[];
     backends: DashBackend[];
+    /** Calls to the gateway's own hosts — back in through it, a service → service hop, not a third party. */
+    backIn?: Array<{
+        host: string;
+        ops: number;
+        usedBy: string[];
+    }>;
     hosts: DashHostCheck[];
     /** Appends the missing /etc/hosts lines — present only when a host does not resolve. */
     hostsFix?: string;
@@ -350,6 +357,19 @@ export interface DashFlowNode {
     jobId?: string;
     sig?: string;
     urlKey?: string;
+    method?: string;
+    /** The route template, `/companies/:id`: the framework's own when it says, else the path with ids folded. */
+    route?: string;
+    /** The path as requested, without the query string. */
+    rawPath?: string;
+    status?: number;
+    host?: string;
+    /** On an east-west hop through the gateway: the service that made the call. */
+    caller?: string;
+    /** The response was streamed (an AI provider's SSE). */
+    streamed?: boolean;
+    /** A call out whose request and response were captured (`/api/exchange?id=`). */
+    exchangeId?: string;
     durationMs?: number;
     detail?: string;
     steps?: string[];
@@ -479,11 +499,19 @@ export interface DashLogLine {
     /** The whole record a pod printed across lines — a message and its metadata, or its stack (shown expanded). */
     detail?: string;
     flowId?: string;
+    /** The request it happened in (the trace), when the line belongs to one. */
+    requestId?: string;
+    /** The step in its flow — the same id as the flow's node — so "open this step" lands exactly. */
+    nodeId?: string;
+    /** How long the thing it records took, when it says (`ms:>500` filters on this). */
+    durationMs?: number;
 }
 export interface DashLogsFrame {
     seq: number;
     sources: string[];
     lines: DashLogLine[];
+    /** The oldest line the ring still holds — anything before it is gone, not missing. */
+    oldestAt?: number;
 }
 export type DashProblemSeverity = 'high' | 'medium' | 'low';
 export type DashProblemKind = 'n-plus-one' | 'db-in-loop' | 'render-storm' | 'slow-path' | 'slow-route' | 'slow-query' | 'missing-index' | 'leak' | 'server-error' | 'browser-error' | 'failed-span' | 'egress-failing' | 'egress-slow' | 'duplicate-requests' | 'build' | 'typecheck' | 'lint' | 'service'
@@ -510,6 +538,17 @@ export interface DashProblem {
     code?: string;
     /** How many times it happened, when the detector counts. */
     count?: number;
+    /**
+     * The number the detector measured, against its budget when it has one — `812 ms / 500 ms`,
+     * `×6 / ×1`, `+421 items`. Only what the detector itself reported; absent otherwise.
+     */
+    measure?: {
+        value: number;
+        budget?: number;
+        unit: 'ms' | '×' | 'items';
+    };
+    /** The latest measurements, oldest first, in `measure.unit` (a slow route's last calls). */
+    samples?: number[];
     /** The flow (and node inside it) that shows this happening. */
     evidence?: {
         flowId?: string;
@@ -558,6 +597,35 @@ export interface DashDiagnostics {
     react: {
         hot: DashHotComponent[];
     };
+    /** Not broken, worth a look — one entry per source, the third counter in the top bar. Absent from older servers. */
+    warnings?: DashWarning[];
+    /**
+     * The top bar's slow and warning counters, counted here so every client shows the same numbers:
+     * `slow` = open problems of a {@link DASH_PERF_KINDS} kind above `low`; `warnings` = the sum of `warnings[].count`.
+     * (The error counter is `DashErrors.recentGroups`.)
+     */
+    counts?: {
+        slow: number;
+        warnings: number;
+    };
+}
+/** The problem kinds that are "slow or wasteful" — Performance's findings and the slow counter. */
+export declare const DASH_PERF_KINDS: readonly DashProblemKind[];
+export type DashWarningKind = 'lint' | 'visual' | 'log' | 'bundle' | 'react' | 'memory' | 'service' | 'gateway' | 'db';
+/** Something that is not failing but deserves a look: lint warnings, visual-rule violations, growing memory. */
+export interface DashWarning {
+    /** Stable for its source, so a list can be kept and diffed. */
+    id: string;
+    kind: DashWarningKind;
+    title: string;
+    /** Where it is, when one place says it (a component, an owner, a file). */
+    where?: string;
+    count: number;
+    lastSeenAt: number;
+    /** The resource that holds the detail. */
+    resource?: string;
+    /** A Logs query that shows it, when it is made of log lines. */
+    query?: Array<[string, string]>;
 }
 /**
  * server    — a request a service answered with a 5xx / an exception reached its handler
@@ -684,3 +752,1908 @@ export type DashStreamEvent = {
     data: DashErrors;
 };
 export type DashStreamEventType = DashStreamEvent['type'];
+/**
+ * What one run of a route touched, by key, with how many times:
+ * `svc:<callee>` a service it called · `ext:<host>` a host outside the cluster · `sql:<VERB> <table>`
+ * a statement shape · `cache:<op>` a key-value command · `queue:<name>` a job it added ·
+ * `err:<what>` something that threw.
+ */
+export type DashTouches = Record<string, number>;
+export interface DashRouteRun {
+    at: number;
+    flowId?: string;
+    requestId?: string;
+    status?: number;
+    durationMs?: number;
+    /** Who called it: another service by name, else `client`. */
+    caller?: string;
+    touches: DashTouches;
+}
+export type DashRouteChangeKind = 'new-external' | 'new-service' | 'new-query' | 'new-queue' | 'new-cache' | 'new-error' | 'gone' | 'gone-error' | 'count' | 'status' | 'duration';
+export interface DashRouteChange {
+    kind: DashRouteChangeKind;
+    /** The touch key it is about, when it is about one. */
+    key?: string;
+    /** One line, plain: "now calls api.openai.com", "now runs select revisions", "select business_facts ×48 → ×96", "404 → 200". */
+    text: string;
+}
+export interface DashRouteSummary {
+    /** `<service> <METHOD> <route>`. */
+    id: string;
+    /** Its newest finished route review, when it has one. */
+    review?: DashReviewMark;
+    service: string;
+    method: string;
+    /** The route template (`/api/companies/:id`). */
+    route: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    runs: number;
+    errors: number;
+    p50?: number;
+    p95?: number;
+    /** The latest run; `touches` with its counts (`sql:SELECT business_facts` ×96). */
+    last: {
+        at: number;
+        status?: number;
+        durationMs?: number;
+        flowId?: string;
+        touches?: DashTouches;
+    };
+    /** Who called its kept runs (`client`, or the calling services). */
+    callers: string[];
+    /** What the latest run touched, most-used first. */
+    uses: string[];
+    /**
+     * The latest run against the route's earlier kept runs: what none of them touched, what all of
+     * them touched and it did not, a query count or a time far from the usual one, a status unlike the
+     * run before.
+     */
+    changes: DashRouteChange[];
+}
+export interface DashRouteUse {
+    key: string;
+    kind: 'svc' | 'ext' | 'sql' | 'cache' | 'queue' | 'err' | 'other';
+    name: string;
+    /** For SQL: the statement's verb, so reads and writes can be told apart. */
+    verb?: string;
+    /** Of the kept runs, how many touched it. */
+    inRuns: number;
+    /** On average, per run that touched it. */
+    perRun: number;
+    /** Only the latest run touched it. */
+    latestOnly: boolean;
+}
+/**
+ * A value's shape. An object's fields are a list, each carrying its name — never property keys: the bus redacts the
+ * value under any key named like a credential (`code`, `token`, `session`…), and a field so named would lose its shape.
+ */
+export type DashShape = {
+    t: 'null';
+} | {
+    t: 'bool';
+} | {
+    t: 'num';
+    int?: true;
+} | {
+    t: 'str';
+    f?: DashStringFormat;
+    max?: number;
+} | {
+    t: 'arr';
+    n: [number, number];
+    of?: DashShape;
+} | {
+    t: 'obj';
+    fields: DashShapeField[];
+    more?: number;
+} | {
+    t: 'map';
+    n: [number, number];
+    key?: DashStringFormat;
+    of?: DashShape;
+} | {
+    t: 'any';
+    of: DashShape[];
+};
+/** One field of an object's shape. `opt`: some samples lacked it. `cred`: named like a credential — its lengths are not kept. */
+export type DashShapeField = DashShape & {
+    name: string;
+    opt?: true;
+    cred?: true;
+};
+export type DashStringFormat = 'uuid' | 'ulid' | 'date-time' | 'date' | 'email' | 'url' | 'jwt' | 'int' | 'decimal' | 'hex' | 'base64' | 'phone';
+/** Facts about a request's headers: what kind of thing came, never the thing. */
+export interface DashHttpRequestFacts {
+    contentType?: string;
+    accept?: string;
+    /** The credential's scheme (`Bearer`, `Basic`) — never the credential. Not `auth`: the bus redacts what is under a key so named. */
+    scheme?: string;
+    cookies?: number;
+    ifMatch?: true;
+    ifNoneMatch?: true;
+    idempotencyKey?: true;
+    origin?: true;
+    bytes?: number;
+    /** Its query's and its path's parameter names. */
+    query?: string[];
+    params?: string[];
+}
+/** Facts about a response's headers. */
+export interface DashHttpResponseFacts {
+    contentType?: string;
+    bytes?: number;
+    cacheControl?: string;
+    etag?: 'strong' | 'weak';
+    lastModified?: true;
+    location?: true;
+    vary?: string;
+    retryAfter?: true;
+    wwwAuthenticate?: string;
+    allow?: string;
+    /** Each cookie it sets: its name and attributes, never its value. */
+    cookies?: Array<{
+        name: string;
+        secure?: true;
+        httpOnly?: true;
+        sameSite?: string;
+        domain?: true;
+        path?: string;
+        maxAge?: true;
+        expires?: true;
+    }>;
+    /** `creds`: `Access-Control-Allow-Credentials: true` (not `credentials`, a name the bus redacts). */
+    cors?: {
+        origin: '*' | 'echoed' | 'fixed';
+        creds?: true;
+        methods?: string;
+        headers?: string;
+    };
+    hsts?: true;
+    nosniff?: true;
+    /** `X-Powered-By` / `Server` that name the stack. */
+    poweredBy?: true;
+    deprecation?: true;
+    sunset?: true;
+    rateLimit?: true;
+    requestId?: true;
+}
+/**
+ * What a route's exchanges looked like, merged over the ones recorded (the services record one per route and status
+ * class a minute): the requests — media types, credential schemes, preconditions, keys, parameter names, body shape —
+ * and, per status, the responses — media type, cache and cookie policy, validators, CORS, body shape. Counts say how
+ * many of the recorded exchanges had a fact.
+ */
+export interface DashRouteContract {
+    samples: number;
+    firstAt: number;
+    lastAt: number;
+    request: {
+        contentTypes: Record<string, number>;
+        /** The credential schemes that came (`Bearer` ×3, `none` ×1). */
+        schemes: Record<string, number>;
+        query: Record<string, number>;
+        params: string[];
+        ifMatch: number;
+        ifNoneMatch: number;
+        idempotencyKey: number;
+        origin: number;
+        cookies: number;
+        bytesMax?: number;
+        body?: DashShape;
+    };
+    responses: Record<string, {
+        n: number;
+        contentTypes: Record<string, number>;
+        bytesMax?: number;
+        cacheControl: Record<string, number>;
+        etag?: 'strong' | 'weak';
+        vary?: string;
+        wwwAuthenticate?: string;
+        allow?: string;
+        cookies?: NonNullable<DashHttpResponseFacts['cookies']>;
+        cors?: NonNullable<DashHttpResponseFacts['cors']>;
+        /** How many had each of: location, lastModified, retryAfter, hsts, nosniff, poweredBy, deprecation, sunset, rateLimit, requestId. */
+        has: Record<string, number>;
+        body?: DashShape;
+    }>;
+}
+export interface DashRouteDetail extends DashRouteSummary {
+    /** Newest first, at most 20. */
+    recent: DashRouteRun[];
+    /** What its exchanges looked like — when its service records them. */
+    contract?: DashRouteContract;
+    /** Over the kept runs: everything the route depends on. */
+    usesDetail: DashRouteUse[];
+    /** The latest run against the run before it, alone. */
+    changesSincePrev?: DashRouteChange[];
+    /** The latest run against the oldest one kept. */
+    changesSinceOldest: DashRouteChange[];
+}
+export interface DashRoutesCatalog {
+    at: number;
+    routes: DashRouteSummary[];
+    /** How far back the kept history reaches. */
+    since?: number;
+}
+/** What one AI model was asked through an endpoint, and what it cost in tokens. */
+export interface DashAiUse {
+    model: string;
+    calls: number;
+    promptTokens: number;
+    completionTokens: number;
+    /** Calls that came back without a usage block. */
+    unmetered: number;
+}
+/** One call out, as kept: the endpoint's templated path (query strings are never captured). */
+export interface DashExternalCall {
+    at: number;
+    service: string;
+    method: string;
+    path: string;
+    status?: number;
+    /** A transport error (refused, reset, timed out). */
+    error?: string;
+    durationMs?: number;
+    flowId?: string;
+    /** The route whose run made the call (a route catalog id), when the request was seen to end. */
+    route?: string;
+    /** Its captured exchange (`/api/exchange?id=`): headers, bodies, a stream's events — when capture was on. */
+    exchangeId?: string;
+    /** The request it was made in — the calls that share it are one request's steps. */
+    requestId?: string;
+}
+/** One call opened (Data › External APIs' Request & response panel): the call, its exchange, its request's other steps. */
+export interface DashExchangeView {
+    host: string;
+    call: DashExternalCall;
+    /** Absent: not captured (capture off, headers rotated away) or withheld (`withheld` says why). */
+    exchange?: HttpExchange;
+    withheld?: string;
+    /** The steps of the same request, in order: the route that made the call, then each outbound call. */
+    chain: Array<{
+        kind: 'route' | 'egress';
+        label: string;
+        status?: number;
+        exchangeId?: string;
+        host?: string;
+        at?: number;
+        current?: boolean;
+    }>;
+}
+export interface DashEndpointSummary {
+    /** `<host> <METHOD> <path>`. */
+    id: string;
+    host: string;
+    method: string;
+    /** Ids folded the same way as routes (`/v1/files/:id`). */
+    path: string;
+    services: string[];
+    /** The routes whose runs call it (route catalog ids), most recent first. */
+    routes: string[];
+    calls: number;
+    /** Calls that did not succeed: a transport error, or a status ≥ 400. */
+    failed: number;
+    status4xx: number;
+    status5xx: number;
+    /** Over the kept durations (the last 100). */
+    avgMs?: number;
+    p50?: number;
+    p95?: number;
+    maxMs: number;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    lastStatus?: number;
+    lastError?: string;
+    ai?: DashAiUse[];
+}
+export type DashExternalHealth = 'failing' | 'slow' | 'ok';
+export interface DashExternalHost {
+    host: string;
+    services: string[];
+    /** Failing or slow now, or repeatedly lately — one blip that recovered is retracted. */
+    health: DashExternalHealth;
+    /** "3 of the last 20 calls failed", "2 of the last 20 took ≥ 1 s", "healthy". */
+    verdict: string;
+    calls: number;
+    failed: number;
+    p50?: number;
+    p95?: number;
+    maxMs: number;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    endpoints: number;
+    ai?: DashAiUse[];
+}
+export interface DashExternalHostDetail extends DashExternalHost {
+    /** A call at or over this is slow (the lens's egress threshold). */
+    slowMs: number;
+    /** Every endpoint of the host, slowest p95 first. */
+    endpointList: DashEndpointSummary[];
+    /** Newest first. */
+    recent: DashExternalCall[];
+    /** Newest first — kept apart, so a busy host does not push its one failure out. */
+    failures: DashExternalCall[];
+}
+export interface DashExternalCatalog {
+    at: number;
+    /** Third parties only, failing first, then slowest. */
+    hosts: DashExternalHost[];
+    /** Every endpoint of those hosts — a row per domain, method and pathname (Data › External APIs' table). */
+    endpoints?: DashEndpointSummary[];
+    /**
+     * Hosts the gateway fronts. A call to one is a hop to one of the cluster's own services, so it is
+     * not an external API — listed so a reader knows where those calls went.
+     */
+    gatewayHosts: Array<{
+        host: string;
+        services: string[];
+        calls: number;
+    }>;
+    /** A call at or over this is slow (the lens's egress threshold). */
+    slowMs: number;
+    since?: number;
+}
+/** One execution of a statement, as the pg tap recorded it. */
+export interface DashSqlExecution {
+    at: number;
+    service: string;
+    durationMs?: number;
+    rows?: number;
+    /** Its values as the tap kept them: credential columns masked, at most 10, each ≤ 80 characters. */
+    params?: string[];
+    /** The first rows it returned, as the tap kept them (redacted by column, ≤ 240 characters). */
+    result?: string;
+    error?: string;
+    flowId?: string;
+    /** The route whose run made it (a route catalog id), when the request was seen to end. */
+    route?: string;
+}
+/** What the workspace's database analyzer (`db://analysis`) said about a table. */
+export interface DashSqlFinding {
+    kind: string;
+    table: string;
+    detail: string;
+    severity: string;
+    tool: string;
+    at: number;
+}
+export interface DashSqlTemplateSummary {
+    /** 12 hex characters — the statement's shape (`@lensmcp/core/sql-shape`). */
+    id: string;
+    /** The statement with literals as `?` and value lists folded to `(…)`. */
+    template: string;
+    /** A leading comment naming it (`registry.product-composition`). */
+    name?: string;
+    /** For one of the services' statements without a name: a name to give it, unique across the workspace (db://lint suggests the same). */
+    suggestedName?: string;
+    /** Its newest finished SQL review, when it has one. */
+    review?: DashReviewMark;
+    /** SELECT · INSERT · UPDATE · DELETE · …; a WITH reads as the statement it leads to. */
+    verb: string;
+    tables: string[];
+    /** The table an INSERT / UPDATE / DELETE writes. */
+    target?: string;
+    services: string[];
+    /** The routes whose runs ran it (route catalog ids), most recent first. */
+    routes: string[];
+    /** The databases it ran on, most recent first — when the tap names them. */
+    databases?: string[];
+    /** `host:port` of the server it last ran on. */
+    server?: string;
+    runs: number;
+    errors: number;
+    /** Time spent in it, summed over the runs seen. */
+    totalMs: number;
+    p50?: number;
+    p95?: number;
+    maxMs: number;
+    rowsTotal: number;
+    rowsMax: number;
+    /** The most times one request ran it — at the N+1 threshold or over, it runs in a loop. */
+    perRequestMax: number;
+    /** The flow of that request. */
+    perRequestMaxFlow?: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    /** Runs the producer's flood guard dropped (when > 0, the counts are a floor). */
+    suppressed: number;
+    /** The statement is known whole (a tap that sends it), not only its first 500 characters. */
+    complete: boolean;
+}
+export interface DashSqlTemplateDetail extends DashSqlTemplateSummary {
+    /** The statement as sent, up to 8 KB — or its first 500 characters when `complete` is false. */
+    statement: string;
+    /** Newest first. */
+    executions: DashSqlExecution[];
+    /** Newest first — kept apart, so a busy statement does not push its one failure out. */
+    failures: DashSqlExecution[];
+    /** What the workspace's database analyzer said about the tables it touches. */
+    findings: DashSqlFinding[];
+}
+export interface DashSqlTable {
+    name: string;
+    /** Runs of reading statements that touched it, and of writing ones. */
+    reads: number;
+    writes: number;
+    statements: number;
+    services: string[];
+    /** The slowest p95 among the statements that touch it. */
+    slowestP95?: number;
+    findings: DashSqlFinding[];
+    lastSeenAt: number;
+}
+/** A run of any statement, for the newest-first list across statements. */
+export interface DashSqlRun extends DashSqlExecution {
+    /** Its statement's shape id, verb, template and tables. */
+    id: string;
+    verb: string;
+    template: string;
+    tables: string[];
+}
+export interface DashSqlCatalog {
+    at: number;
+    /** Costliest first: the most time spent in it. */
+    templates: DashSqlTemplateSummary[];
+    /** Most used first. */
+    tables: DashSqlTable[];
+    /** A run at or over this is slow (`slowQueryMs`). */
+    slowMs: number;
+    /** Runs per request at which a statement counts as a loop (`nPlusOne`). */
+    loopAt: number;
+    /** The latest run of the workspace's database analyzer, when one reported. */
+    analysis?: {
+        at: number;
+        tool: string;
+        findings: number;
+    };
+    since?: number;
+}
+/** `/api/db/stores` — every declared store as this checkout sees it, and what the lens could read of it. */
+export interface DashDbStores {
+    at: number;
+    /** `nx.json` → `lensmcp.stores` problems, as the checker words them. */
+    errors: string[];
+    notes: string[];
+    stores: DashDbStore[];
+}
+export interface DashDbStore {
+    name: string;
+    kind: 'postgres' | 'redis';
+    /** `host:port`. */
+    server: string;
+    /** `PostgreSQL 18.0`. */
+    version?: string;
+    /** Postgres's version number (`180000`) — what decides how a statement can be planned. */
+    versionNum?: number;
+    /** Why the lens read nothing, when it did not (an unset variable, reading off, no `pg` client, refused…). */
+    unread?: string;
+    /** Every database on the server, this checkout's first. */
+    databases: DashDbDatabase[];
+    /** Connections to the server, all databases. */
+    connections?: number;
+}
+export interface DashDbDatabase {
+    name: string;
+    bytes?: number;
+    connections?: number;
+    /** One of this checkout's databases — declared on the store. */
+    mine: boolean;
+}
+/** `/api/db/schema?store=&db=` — one database as Postgres describes it. */
+export interface DashDbSchema {
+    at: number;
+    store: string;
+    database: string;
+    /** Since when Postgres counted scans and statements (its last stats reset), if it says. */
+    statsSince?: number;
+    tables: DashDbTableInfo[];
+    indexes: DashDbIndex[];
+    /** What `pg_stat_statements` counted in this database — or why it could not be read. */
+    statements: {
+        state: 'ok' | 'missing' | 'not-loaded' | 'denied' | 'error';
+        detail?: string;
+        since?: number;
+        rows: DashDbStatementStat[];
+    };
+    findings: DashDbFinding[];
+    /** A read that failed, in Postgres's words. */
+    error?: string;
+}
+export interface DashDbTableInfo {
+    schema: string;
+    name: string;
+    /** Live rows, as Postgres's statistics count them (an estimate). */
+    rows: number;
+    deadRows: number;
+    /** Table, its indexes and TOAST. */
+    bytes: number;
+    indexBytes: number;
+    seqScans: number;
+    /** Rows the sequential scans read, summed. */
+    seqRowsRead: number;
+    indexScans: number;
+    inserts: number;
+    updates: number;
+    deletes: number;
+    lastVacuumAt?: number;
+    lastAnalyzeAt?: number;
+}
+export interface DashDbIndex {
+    schema: string;
+    table: string;
+    name: string;
+    /** `CREATE INDEX … ON … USING btree (tenant_id, created_at)`. */
+    definition: string;
+    unique: boolean;
+    primary: boolean;
+    /** False when a CREATE INDEX CONCURRENTLY failed and left it behind. */
+    valid: boolean;
+    /** Part of a partitioned table's index (or that index itself): changed on the parent, never on its own. */
+    partition?: boolean;
+    scans: number;
+    rowsRead: number;
+    bytes: number;
+}
+/** A table as a review needs it: its size and use, its columns and how their values spread, its keys and indexes. */
+export interface DashDbTableDesign {
+    schema: string;
+    name: string;
+    rows: number;
+    bytes: number;
+    indexBytes: number;
+    deadRows: number;
+    seqScans: number;
+    indexScans: number;
+    lastAnalyzeAt?: number;
+    /** Postgres's statistics about each column — fractions and counts, never a value. */
+    columns: Array<{
+        name: string;
+        type: string;
+        notNull: boolean;
+        default?: string;
+        nullFrac?: number;
+        distinct?: number;
+        correlation?: number;
+    }>;
+    /** `PRIMARY KEY (id)`, `FOREIGN KEY (tenant_id) REFERENCES tenants(id)`, `CHECK (…)`. */
+    constraints: Array<{
+        name: string;
+        type: 'primary' | 'unique' | 'foreign' | 'check' | 'exclusion' | 'other';
+        definition: string;
+    }>;
+    indexes: DashDbIndex[];
+    /** A partitioned table, or a partition of one (its parent). */
+    partitioned?: boolean;
+    partitionOf?: string;
+    /** Row-level security on it, and its policies' definitions. */
+    rowSecurity?: boolean;
+    policies?: Array<{
+        name: string;
+        command: string;
+        using?: string;
+        check?: string;
+    }>;
+    /** Its triggers' definitions (not the internal ones behind foreign keys). */
+    triggers?: Array<{
+        name: string;
+        definition: string;
+    }>;
+}
+/** The server a database is on, as a review needs it: version, the planner and memory settings, extensions. */
+export interface DashDbServer {
+    version?: string;
+    versionNum?: number;
+    settings: Array<{
+        name: string;
+        value: string;
+    }>;
+    extensions: Array<{
+        name: string;
+        version: string;
+    }>;
+}
+/**
+ * `db://lint` — what a coding agent must fix about the SQL the services ran: a statement without a name (it is not
+ * reviewed until it has one: the name is what follows it from one version to the next), one name on two statements
+ * at once, and a statement whose SQL review scores under 70.
+ */
+export interface DashDbLint {
+    at: number;
+    /** Under this overall score a reviewed statement is a warning. */
+    warnBelow: number;
+    errors: number;
+    warnings: number;
+    /** The statements the lint looked at (the services' own: they touch a table), and how many have a name. */
+    statements: number;
+    named: number;
+    /** Errors first, then warnings; the busiest first; at most 60 (`more` says how many were left out). */
+    issues: DashDbLintIssue[];
+    more: number;
+    /** Each name: the statement it names now, and the versions it replaced (not seen since the current one came). */
+    names: Array<{
+        name: string;
+        current: string;
+        replaced: string[];
+        overall?: number;
+    }>;
+}
+export interface DashDbLintIssue {
+    severity: 'error' | 'warning';
+    rule: 'unnamed-statement' | 'name-reused' | 'review-below';
+    statement: string;
+    name?: string;
+    verb: string;
+    tables: string[];
+    services: string[];
+    routes: string[];
+    runs: number;
+    lastSeenAt: number;
+    message: string;
+    /** What to do, for a coding agent. */
+    fix: string;
+    /** For an unnamed statement: a name in the convention, to start from. */
+    suggestedName?: string;
+    review?: {
+        runId: string;
+        at: number;
+        overall: number;
+        title?: string;
+        top?: string;
+    };
+}
+/**
+ * One statement's lint (`db://lint/<statement>`, by id or name): its issues, its newest SQL review, the routes that ran
+ * it — what a route's lint issue (`routes://lint`) points at to check one of its statements.
+ */
+export interface DashDbStatementLint {
+    at: number;
+    /** The id or name asked for, and whether the catalog has it. */
+    asked: string;
+    found: boolean;
+    statement?: string;
+    name?: string;
+    verb?: string;
+    tables?: string[];
+    services?: string[];
+    /** Named, no issue, and its review (if any) at or over the threshold. */
+    ok: boolean;
+    issues: DashDbLintIssue[];
+    review?: {
+        runId: string;
+        at: number;
+        overall?: number;
+        title?: string;
+        top?: string;
+    };
+    /** The routes that ran it, newest first (`routes://lint` has their issues). */
+    routes: string[];
+    /** What to do next, for a coding agent. */
+    next: string;
+}
+/** A statement a route's lint issue is about, with the `db://` resource that checks it. */
+export interface DashRoutesLintStatement {
+    id: string;
+    name?: string;
+    verb: string;
+    tables: string[];
+    /** `db://lint/<id>` — its issues, its SQL review, the routes that run it. */
+    db: string;
+    overall?: number;
+    /** The most times one request ran it (for a loop). */
+    perRequest?: number;
+    suggestedName?: string;
+}
+export interface DashRoutesLintIssue {
+    severity: 'error' | 'warning';
+    rule: 'unnamed-sql' | 'review-hole' | 'credential-in-url' | 'stack-in-error' | 'review-below' | 'sql-review-below' | 'sql-loop' | 'get-writes';
+    /** The route's catalog id (`<service> <METHOD> <route>`), and its parts. */
+    route: string;
+    service: string;
+    method: string;
+    path: string;
+    runs: number;
+    lastSeenAt: number;
+    message: string;
+    /** What to do, for a coding agent. */
+    fix: string;
+    /** For an issue about its SQL: each statement, with the `db://` resource to check it. */
+    statements?: DashRoutesLintStatement[];
+    /** For an issue from its route review: the review, and the indicators it rests on. */
+    review?: {
+        runId: string;
+        at: number;
+        overall?: number;
+        title?: string;
+        top?: string;
+        low?: Array<{
+            id: string;
+            score: number;
+        }>;
+    };
+    /** The resources that check it — `db://lint/<statement>` for each statement it names. */
+    check: string[];
+}
+/**
+ * `routes://lint`: the endpoints the services answered, against what a coding agent fixes — from their route reviews,
+ * their statements (each pointing at its `db://lint/<statement>`) and what their runs and recorded exchanges show.
+ */
+export interface DashRoutesLint {
+    at: number;
+    /** Under this overall score a reviewed route is a warning; a cap indicator (authorization, exposure, write safety) under `holeBelow` is an error. */
+    warnBelow: number;
+    holeBelow: number;
+    /** One statement this many times in one request is a loop. */
+    loopAt: number;
+    errors: number;
+    warnings: number;
+    /** The routes the lint looked at, and how many have a route review. */
+    routes: number;
+    reviewed: number;
+    /** Errors first, then warnings; the busiest first; at most 80 (`more` says how many were left out). */
+    issues: DashRoutesLintIssue[];
+    more: number;
+    /** Every route with an issue, and how many of each — none left out. */
+    byRoute: Record<string, {
+        errors: number;
+        warnings: number;
+    }>;
+}
+/** The tables one catalog statement reads or writes, from the database it ran on. */
+export interface DashDbTables {
+    at: number;
+    id: string;
+    store?: string;
+    database?: string;
+    state: 'ok' | 'unavailable' | 'error';
+    reason?: string;
+    tables: DashDbTableDesign[];
+    server?: DashDbServer;
+}
+export interface DashDbStatementStat {
+    /** The catalog statement it is (`DashSqlTemplateSummary.id`), when its shape matches one. */
+    templateId?: string;
+    /** As Postgres normalised it (`$n` for every constant). */
+    query: string;
+    calls: number;
+    totalMs: number;
+    meanMs: number;
+    rows: number;
+    /** Shared buffers found in memory over all buffers touched, 0..1. */
+    hitRatio?: number;
+}
+export interface DashDbFinding {
+    kind: 'unused-index' | 'duplicate-index' | 'invalid-index' | 'seq-scan' | 'dead-rows';
+    severity: 'high' | 'medium' | 'low';
+    table: string;
+    index?: string;
+    /** What Postgres's numbers say, in a sentence. */
+    detail: string;
+    /** The statement that would fix it — shown to copy, never run by the lens. */
+    fix?: string;
+}
+/** One Redis command by its shape: the command and its key with ids folded (`GET session:*`); a script by its hash. */
+export interface DashKvCommandShape {
+    id: string;
+    op: string;
+    pattern: string;
+    /** EVAL / EVALSHA / FCALL — a script, kept by its hash. */
+    script?: boolean;
+    runs: number;
+    /** GETs the tap saw answer a value, and none. */
+    hits: number;
+    misses: number;
+    totalMs: number;
+    p50?: number;
+    p95?: number;
+    maxMs: number;
+    services: string[];
+    /** Route catalog ids whose runs sent it, most recent first. */
+    routes: string[];
+    firstSeenAt: number;
+    lastSeenAt: number;
+    /** One real key of the shape — to open it on Keys. */
+    sampleKey: string;
+}
+export interface DashKvCommandRun {
+    shape: string;
+    at: number;
+    op: string;
+    key: string;
+    /** The command as sent, values sized or masked. */
+    command: string;
+    result?: 'hit' | 'miss';
+    durationMs?: number;
+    service: string;
+    flowId?: string;
+    route?: string;
+}
+/** `/api/catalog/kv` — every command shape the services sent, kept 30 days. */
+export interface DashKvCommands {
+    at: number;
+    shapes: DashKvCommandShape[];
+    since?: number;
+}
+/** A model provider the lens can hold a key for. `systemone` is TypeSafe's typed-decision protocol (JEV; Laya later). */
+export type DashAiProvider = 'anthropic' | 'openai' | 'systemone';
+/** What a provider is, for the Add a token form. */
+export interface DashAiProviderInfo {
+    id: DashAiProvider;
+    /** `Anthropic API key`. */
+    label: string;
+    /** `Anthropic` — the kind line under a token's name. */
+    short: string;
+    /** `frontier` answers in text (System 2); `decisions` returns typed answers with confidence (System 1). */
+    tier: 'frontier' | 'decisions';
+    placeholder: string;
+    help: string;
+    /** Where the calls go unless the token names another endpoint (a gateway such as OpenRouter, or Laya). */
+    defaultBaseUrl: string;
+    /** Whether a token may name another endpoint. */
+    baseUrlAllowed: boolean;
+    defaultModel: string;
+    /** Where to make a key. */
+    console: string;
+}
+/** One key the lens holds — never its value: that stays in the keychain. */
+export interface DashAiToken {
+    id: string;
+    provider: DashAiProvider;
+    label: string;
+    /** `sk-ant-api03-…x7Qa`. */
+    mask: string;
+    /** Every workspace, or one workspace's key. */
+    scope: 'all' | string;
+    /** Usable in this workspace, and its place among those that are. */
+    here: boolean;
+    position?: number;
+    /** The endpoint, when not the provider's own. */
+    baseUrl?: string;
+    model?: string;
+    /** The models the provider listed at the last test. */
+    models: string[];
+    /** Monthly cap; spend this month, estimated from usage × the price table. */
+    budgetUsd?: number;
+    usedUsd: number;
+    status: 'ok' | 'limited' | 'exhausted' | 'invalid' | 'unreachable' | 'unverified';
+    note: string;
+    /** The provider's organization and workspace the key belongs to, from its responses (Anthropic). */
+    org?: string;
+    workspace?: string;
+    /** The workspace an identity-linked Anthropic key not scoped to one is sent to. */
+    workspaceId?: string;
+    /** Other keys of the same organization and workspace: they draw on one set of limits. */
+    sharedWith: string[];
+    /** What the key's limits hold now, per model it was used with — projected from the last response along the refill. */
+    capacity: DashAiCapacity[];
+    /** Cut off until then: rate-limited, or out of spend (a monthly cap, a self-set limit). */
+    blocked?: {
+        until: number;
+        why: string;
+        kind: 'rate' | 'spend';
+    };
+    /**
+     * The credit on the key's account, as its console lists it — remaining, of how much, granted and expiring when —
+     * less what the lens's calls cost since it was set (other use of the account is not seen). Shared by the keys of
+     * one organization. A promotional grant is lost at its expiry: keys are spent by what they must spend a day not to
+     * lose any.
+     */
+    credit?: {
+        /** Plan credit left plus purchased credit left. */
+        leftUsd: number;
+        /** Plan ("Promotional credits", spent first, lost at its expiry) and purchased (spent after, good for a year). */
+        planUsd: number;
+        purchasedUsd: number;
+        /** What it must spend a day until it expires not to lose any — keys are spent in this order. */
+        perDayUsd: number;
+        out: boolean;
+        expired: boolean;
+        balanceUsd: number;
+        setAt: number;
+        spentUsd: number;
+        grantUsd?: number;
+        grantedAt?: number;
+        expiresAt?: number;
+        monthly?: boolean;
+        nextGrantAt?: number;
+        sharedWith: string[];
+    };
+    addedAt: number;
+    testedAt?: number;
+    lastUsedAt?: number;
+}
+/** What an analyzer suggests: what is wrong, why (from the evidence), the change, how to verify it. */
+export interface DashAiSuggestion {
+    /** What the thing is, as the reviewer read it — a name and a description that later analyzers reuse (a route's review names its statements by them). */
+    about?: {
+        title: string;
+        description: string;
+    };
+    summary: string;
+    /** `fine` · `n+1` · `missing-index` · `slow-plan` · `over-fetch` · `lock-or-io` · `design` · `other`. */
+    verdict: string;
+    severity: 'none' | 'low' | 'medium' | 'high';
+    /** The first finding's — the one most worth doing (or `Nothing to change`). */
+    title: string;
+    why: string[];
+    change?: DashAiChange;
+    verify: string;
+    confidence: number;
+    /** Every change the review asks for, most worth doing first. */
+    findings?: DashAiFinding[];
+    /** The statement as the reviewer would write it, when it would change. */
+    rewrite?: {
+        sql: string;
+        why: string;
+    };
+    /** The analyzer's indicators, each 0–100 (100 is perfect) — what a decision model is later taught from. */
+    indicators?: DashAiIndicator[];
+    /** Who scored them: the frontier model, or the decision model when its answers stood. */
+    scoredBy?: 'frontier' | 'decision';
+    /** The indicators in one number, computed by the lens — under its threshold (70) a warning to the coding agents. */
+    overall?: DashAiOverall;
+    /** What evidence or approval the review was missing. */
+    openQuestions?: string[];
+}
+/**
+ * A review's indicators in one number, 0–100: their weighted mean — held at the score of a bug indicator (correct
+ * results, security, locks) when that is lower, since one wrong result outweighs any number of fast ones.
+ */
+export interface DashAiOverall {
+    score: number;
+    /** Under the set's threshold (70): `db://lint` lists it, and coding agents are told. */
+    warning: boolean;
+    /** `weighted mean of 8` · `held at correct results (20)`. */
+    why: string;
+    /** The lowest indicators, lowest first. */
+    lowest: string[];
+}
+/** One indicator a review scores, 0–100 where 100 is perfect — null when the evidence could not show it. */
+export interface DashAiIndicator {
+    id: string;
+    name: string;
+    score: number | null;
+    why: string;
+}
+/**
+ * An analyzer's instruction file — Markdown kept beside the code, like Claude Code's skills and rules: the user's
+ * (`~/.lensmcp/<analyzer>/*.md`, every project) or the project's (`.lensmcp/<analyzer>/*.md`).
+ */
+export interface DashAiInstructionFile {
+    scope: 'user' | 'project';
+    /** As shown: `~/.lensmcp/sql-review/conventions.md`, `.lensmcp/sql-review/registry.md`. */
+    path: string;
+    /** Its front matter's `description`. */
+    description?: string;
+    /** Its front matter's `tables`: only runs about one of these get it (`*` any characters). */
+    tables?: string[];
+    text: string;
+    chars: number;
+    sha: string;
+}
+/** What a run sent as its instructions: the built-in guide, the workspace's rules and memories, the indicators. */
+export interface DashAiPrompt {
+    guide?: {
+        id: string;
+        version: number;
+        sha: string;
+    };
+    /** The instruction files it was sent, user's then project's. */
+    files?: Array<{
+        scope: 'user' | 'project';
+        path: string;
+        sha: string;
+    }>;
+    rules?: {
+        sha: string;
+        chars: number;
+        at: number;
+    };
+    memories: number;
+    /** The indicator set and its version (`sql@1`). */
+    indicators?: string;
+    systemTokens: number;
+}
+/**
+ * A workspace's note to one analyzer — kept for every worktree, in the workspace's history: its `rules` (one
+ * document, written by its developers) or one thing it remembers (`memory`, from a developer or an agent). Both are
+ * added after the built-in guide in every run, and win over it where they conflict.
+ */
+export interface DashAiNote {
+    id: string;
+    analyzer: string;
+    kind: 'rules' | 'memory';
+    /** A memory about one thing — a table, a statement id — goes only into runs about it. */
+    subject?: string;
+    text: string;
+    /** `developer`, or `agent:<its client>`. */
+    author: string;
+    /** The checkout it was written from. */
+    checkout: string;
+    at: number;
+}
+/** One analyzer as Settings › Analyzers shows it: its guide, its indicators, the workspace's notes, what a run sends. */
+export interface DashAiAnalyzer {
+    id: string;
+    name: string;
+    question: string;
+    /** What it looks at, as a person would list it. */
+    reads: string[];
+    /** The kind of thing it reviews (`sql` — a statement), and the folder its instruction files are in. */
+    target: string;
+    folder?: string;
+    /** Its runs in this checkout. */
+    runs: number;
+    guide?: {
+        id: string;
+        title: string;
+        version: number;
+        sha: string;
+        text: string;
+    };
+    indicators: Array<{
+        id: string;
+        name: string;
+        question: string;
+        levels: string[];
+    }>;
+    indicatorSet?: string;
+    rules?: DashAiNote;
+    memories: DashAiNote[];
+    /** Its instruction files in both scopes, the folders they are read from, and any skipped with why. */
+    files: DashAiInstructionFile[];
+    /** `ignored`: git ignores the project's folder, so its files do not reach the team (`.lensmcp/` instead of `.lensmcp/*`). */
+    folders: Array<{
+        scope: 'user' | 'project';
+        path: string;
+        ignored?: boolean;
+    }>;
+    skippedFiles: Array<{
+        path: string;
+        why: string;
+    }>;
+    /** The instructions every run of it sends now, before the evidence. */
+    preview: {
+        system: string;
+        tokens: number;
+    };
+    lastRun?: {
+        at: number;
+        label: string;
+        status: DashAiRun['status'];
+    };
+    /** What its reviews ask for, as chosen in Settings › Analyzers; absent, the defaults (`DashAiAnalyzers.defaults`). */
+    choice?: {
+        model?: string;
+        effort?: DashAiEffort;
+    };
+    /** What its newest finished runs took, on average — what a run on another model is estimated from. */
+    usage?: {
+        runs: number;
+        input: number;
+        output: number;
+        cacheRead: number;
+        model: string;
+    };
+}
+/** How hard a frontier model thinks (Claude 4.6 and later; other models are sent none). */
+export type DashAiEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export interface DashAiAnalyzers {
+    workspace: string;
+    /** False when there is no history to keep the notes in (Node before 24, or `LENSMCP_EVENT_HISTORY=0`). */
+    notesKept: boolean;
+    /** Where the notes are kept, or why they cannot be. */
+    notesWhere: string;
+    analyzers: DashAiAnalyzer[];
+    /** An analyzer's model and effort can be chosen and kept (there is a workspace history). */
+    choicesKept: boolean;
+    /** The frontier models the keys list, in the keys' order — what an analyzer may ask for. */
+    models: Array<{
+        id: string;
+        provider: DashAiProvider;
+        keys: string[];
+        effort: boolean;
+        price?: {
+            input: number;
+            output: number;
+            cacheRead?: number;
+        };
+    }>;
+    /** Unset, a review runs on each key's own model (the first key's is `model`) at the workspace's effort. */
+    defaults: {
+        model?: string;
+        modelKey?: string;
+        effort: DashAiEffort;
+        effortFrom: 'nx.json' | 'LensMCP';
+    };
+}
+export interface DashAiChange {
+    title: string;
+    kind: 'sql' | 'index' | 'code' | 'config';
+    lines: Array<['+' | '-' | ' ', string]>;
+}
+/** One change a review asks for. */
+export interface DashAiFinding {
+    priority: 'critical' | 'high' | 'medium' | 'low';
+    /** Seen in the evidence (`confirmed`), likely from it (`probable`), or a guess to check (`hypothesis`). */
+    certainty?: 'confirmed' | 'probable' | 'hypothesis';
+    /** The indicator it raises (`correctness`, `index_fit`…). */
+    indicator?: string;
+    /** What it changes: the statement, an index, the table's design, the data in it, the application's code, a setting, an endpoint's contract (its DTOs, statuses, headers), the gateway or proxy. */
+    area: 'query' | 'index' | 'table' | 'data' | 'code' | 'config' | 'contract' | 'gateway' | 'network' | 'service' | 'cache' | 'queue' | 'ui' | 'state' | 'observability';
+    title: string;
+    why: string[];
+    change?: DashAiChange;
+    /** What it could break or cost: semantics, locks, write amplification, storage. */
+    risk?: string;
+    /** How to roll it out safely, and back. */
+    deploy?: string;
+    verify: string;
+}
+/** What a thing costs the app, measured by the lens before any model is asked; `low` holds every finding at low. */
+export interface DashAiImpact {
+    level: 'low' | 'medium' | 'high';
+    /** The numbers it rests on (`p95 3 ms, 12 runs, 40 ms of database time in 2 h`). */
+    why: string;
+}
+/** One analyzer run (R30): its steps, what each tier answered and cost, what the model saw, the suggestion. */
+export interface DashAiRun {
+    id: string;
+    analyzer: string;
+    analyzerName: string;
+    question: string;
+    /** What was reviewed; `name` is a statement's name (its leading comment) — the same across its versions. */
+    target: {
+        kind: 'sql' | 'route' | 'error' | 'flow' | 'ui' | 'kv' | 'queue';
+        id: string;
+        label: string;
+        name?: string;
+    };
+    workspace: string;
+    /** `queued`: waiting for a free slot (`queue` says how many are ahead); one job per target, at most N at once. */
+    status: 'queued' | 'running' | 'done' | 'failed';
+    /** Started by itself (Settings › Features — a route that changed, a statement once named); absent: someone asked. */
+    trigger?: 'auto';
+    queue?: {
+        ahead: number;
+        max: number;
+    };
+    step: string;
+    steps: Array<{
+        at: number;
+        text: string;
+    }>;
+    startedAt: number;
+    finishedAt?: number;
+    costUsd: number;
+    /** `summaries`: shapes, counts, timings and plans — never a run's values. */
+    context: 'summaries' | 'full';
+    /** Each source the models were shown, and its size in tokens (estimated). */
+    saw: Array<{
+        source: string;
+        what: string;
+        tokens: number;
+    }>;
+    /** System 1's typed answers, when there was a decision key. */
+    decision?: {
+        ledgerId: string;
+        label: string;
+        model: string;
+        answers: Record<string, {
+            type: string;
+            value: boolean | string | number;
+            probabilities: Record<string, number>;
+            confidence: number;
+        }>;
+        costUsd?: number;
+    };
+    /** Why the question went on to a frontier model. */
+    escalated?: string[];
+    frontier?: {
+        ledgerId: string;
+        label: string;
+        model: string;
+        latencyMs: number;
+        usage: {
+            input: number;
+            output: number;
+            cacheRead?: number;
+            cacheWrite?: number;
+        };
+        costUsd?: number;
+        skipped: Array<{
+            tokenId: string;
+            label: string;
+            why: string;
+        }>;
+        turns?: number;
+    };
+    /**
+     * How the frontier model worked, turn by turn, as it streamed: its reasoning (summarized), what it wrote, each tool it
+     * called with its input and what the tool returned. `live` marks a block still coming.
+     */
+    transcript?: DashAiTranscriptEntry[];
+    /** What the frontier model asked for during the review (its tools), in order: what each returned, how long it took. */
+    asked?: Array<{
+        tool: string;
+        input: string;
+        ok: boolean;
+        ms: number;
+        tokens: number;
+        what: string;
+    }>;
+    /** What the lens did before the review: statistics refreshed, the plan measured — or why not. */
+    prepared?: string[];
+    /** Other analyzers' reviews it was shown: a route's statements, each with its SQL review as it stood. */
+    reused?: DashAiReuse[];
+    /** The reviews it had run before it (a route's statements' SQL reviews), as each went. */
+    ranFirst?: DashAiRanFirst[];
+    suggestion?: DashAiSuggestion;
+    impact?: DashAiImpact;
+    /** The instructions it sent: which guide, the workspace's rules and memories, the indicator set. */
+    prompt?: DashAiPrompt;
+    /**
+     * What its answer rests on, as fingerprints: the thing's definition (`schema` — a statement's tables, columns,
+     * constraints and indexes; not their counters) and the instructions (guide, indicators, rules). Another analyzer
+     * reuses the review while both still match, instead of asking again.
+     */
+    basis?: {
+        schema?: string;
+        instructions: string;
+    };
+    error?: string;
+}
+/**
+ * An analysis running or waiting now, in the workspace's shared queue: one per `key` (the analyzer and its target),
+ * at most the workspace's limit running together, the rest waiting in the order they came.
+ */
+export interface DashAiJob {
+    key: string;
+    runId: string;
+    analyzer: string;
+    /** `sql:<id>`. */
+    target: string;
+    label: string;
+    checkout: string;
+    /** The lens process that runs it (`<pid>@<host> <role>`). */
+    owner: string;
+    state: 'queued' | 'running';
+    queuedAt: number;
+    startedAt?: number;
+    beatAt: number;
+}
+/** The workspace's analyses now: the limit, those running, those waiting with how many are ahead of each. */
+export interface DashAiQueue {
+    max: number;
+    running: DashAiJob[];
+    queued: Array<DashAiJob & {
+        ahead: number;
+    }>;
+}
+/**
+ * Another analyzer's review of a part, as a run was shown it — a route's statement and its SQL review. `current`: its
+ * review held; `now`: reviewed for this run, just before it; `stale`: only an older review, shown as such; `none`:
+ * not reviewed (`why`: no name, past the limit, or the review failed).
+ */
+export interface DashAiReuse {
+    target: DashAiRun['target'];
+    state: 'current' | 'now' | 'stale' | 'none';
+    why?: string;
+    runId?: string;
+    overall?: DashAiOverall;
+    about?: {
+        title: string;
+        description: string;
+    };
+    findings?: number;
+}
+/** A review run before another — a route's statement's SQL review — as it goes: its run, and its score once done. */
+export interface DashAiRanFirst {
+    target: DashAiRun['target'];
+    state: 'waiting' | 'running' | 'done' | 'failed';
+    runId?: string;
+    overall?: number;
+    why?: string;
+}
+/** A finished review as a list shows it: its overall score (under 70 a warning), when, and its run. */
+export interface DashReviewMark {
+    runId: string;
+    at: number;
+    overall?: number;
+    warning?: boolean;
+}
+/** What became of a suggestion: new, accepted (for a coding agent to do), applied, or dismissed. */
+export type DashSuggestionState = 'new' | 'accepted' | 'applied' | 'dismissed';
+/**
+ * One suggestion: a change a review asked for (a finding of the newest finished review of its target), with what
+ * became of it. A later review of the same target that asks for the same change keeps its state (`key`).
+ */
+export interface DashSuggestion {
+    /** `<runId>#<n>` — the run, and the finding's place in it. */
+    id: string;
+    /** The finding as the state follows it: its analyzer, its target, its title with numbers folded. */
+    key: string;
+    runId: string;
+    analyzer: string;
+    analyzerName: string;
+    target: DashAiRun['target'];
+    /** What the reviewed thing is, as the review named it. */
+    about?: string;
+    finding: DashAiFinding;
+    /** When the review that asked for it finished. */
+    at: number;
+    state: DashSuggestionState;
+    /** When the state was set, by whom (`developer`, or a coding agent's session), and why. */
+    stateAt?: number;
+    by?: string;
+    note?: string;
+}
+/** `/api/ai/suggestions` and `agent://suggestions`: every open suggestion, with what became of each. */
+export interface DashSuggestions {
+    at: number;
+    suggestions: DashSuggestion[];
+    counts: Record<DashSuggestionState, number>;
+    /** What coding agents are shown (`nx.json` → `lensmcp.ai.agentFeed`): accepted suggestions only, or new ones too. */
+    feed: 'accepted' | 'all';
+}
+/** One issue of `kv://lint`: a Redis / Valkey key family against what a coding agent fixes. */
+export interface DashKvLintIssue {
+    severity: 'error' | 'warning';
+    rule: 'secret-in-key' | 'review-hole' | 'counter-unbounded' | 'no-expiry' | 'ttl-dropped' | 'persist' | 'oversized-value' | 'personal-data-in-key' | 'miss-heavy' | 'review-below';
+    /** The key family: the pattern with its ids folded (`session:*`). */
+    pattern: string;
+    /** The commands the services sent against it (`GET`, `INCRBY` …), its runs, who sent them, when last. */
+    ops: string[];
+    runs: number;
+    services: string[];
+    lastSeenAt: number;
+    message: string;
+    /** What to do, for a coding agent. */
+    fix: string;
+    /** For an issue from its cache review: the review, and the indicators it rests on. */
+    review?: {
+        runId: string;
+        at: number;
+        overall?: number;
+        title?: string;
+        top?: string;
+        low?: Array<{
+            id: string;
+            score: number;
+        }>;
+    };
+    /** How to check it: the review tool, the keys to read. */
+    check: string[];
+}
+/**
+ * `kv://lint`: the key families the services used, against what a coding agent fixes — from their commands, a sample
+ * of their keys in the declared stores (read-only) and their cache reviews.
+ */
+export interface DashKvLint {
+    at: number;
+    warnBelow: number;
+    holeBelow: number;
+    errors: number;
+    warnings: number;
+    /** The families the lint looked at, how many have a cache review, and whether the store's keys were read. */
+    families: number;
+    reviewed: number;
+    keysRead: boolean;
+    /** Errors first, then warnings; the busiest first; at most 80 (`more` says how many were left out). */
+    issues: DashKvLintIssue[];
+    more: number;
+    /** Every family with an issue, and how many of each. */
+    byPattern: Record<string, {
+        errors: number;
+        warnings: number;
+    }>;
+    /** Each family's newest cache review, for its score in a list. */
+    reviews: Record<string, DashReviewMark>;
+    /** Why the store's keys were not read, when they were not. */
+    unread?: string;
+}
+/** One issue of `queues://lint`: a BullMQ queue (or a family of per-run queues) against what a coding agent fixes. */
+export interface DashQueuesLintIssue {
+    severity: 'error' | 'warning';
+    rule: 'eviction' | 'no-worker' | 'failing-no-retry' | 'review-hole' | 'no-backoff' | 'retention-unbounded' | 'schedule-late' | 'stalls' | 'retries-exhausted' | 'paused-backlog' | 'review-below';
+    /** `<store>/<db>/<queue>` — the queue the issue was read from (a family's busiest). */
+    queue: string;
+    name: string;
+    /** `product-analysis-*` for queues made per run; the name otherwise. How many queues the family holds. */
+    family: string;
+    queues: number;
+    counts: DashKvQueue['counts'];
+    workers: number;
+    message: string;
+    fix: string;
+    review?: {
+        runId: string;
+        at: number;
+        overall?: number;
+        title?: string;
+        top?: string;
+        low?: Array<{
+            id: string;
+            score: number;
+        }>;
+    };
+    check: string[];
+}
+/** `queues://lint`: the BullMQ queues in the declared stores, against what a coding agent fixes — read-only. */
+export interface DashQueuesLint {
+    at: number;
+    warnBelow: number;
+    holeBelow: number;
+    errors: number;
+    warnings: number;
+    /** The queue families the lint looked at, and how many have a queue review. */
+    families: number;
+    reviewed: number;
+    issues: DashQueuesLintIssue[];
+    more: number;
+    /** Every queue with an issue (by `<store>/<db>/<queue>`, and by family), and how many of each. */
+    byQueue: Record<string, {
+        errors: number;
+        warnings: number;
+    }>;
+    /** Each queue's newest queue review, for its score in a list. */
+    reviews: Record<string, DashReviewMark>;
+    /** Stores that could not be read, and why. */
+    unread?: string[];
+}
+/** One block of how a frontier model worked: reasoning, text, or a tool call with its result. */
+export interface DashAiTranscriptEntry {
+    /** The turn it came in (each tool round trip is a turn). */
+    turn: number;
+    kind: 'thinking' | 'text' | 'tool';
+    /** The reasoning summary, the text, or the tool's input (JSON). */
+    text: string;
+    tool?: string;
+    /** What the tool returned to the model (clipped), whether it worked, how long it took, and the lens's one-line account. */
+    result?: string;
+    ok?: boolean;
+    ms?: number;
+    what?: string;
+    live?: true;
+}
+/** A finished review, as another analyzer (or an agent) reuses it: what the thing is, its scores, what to change. */
+export interface DashAiReviewDigest {
+    target: DashAiRun['target'];
+    runId: string;
+    at: number;
+    analyzer: string;
+    /** The statement's name (its leading comment) — what follows it from one version to the next. */
+    name?: string;
+    about?: {
+        title: string;
+        description: string;
+    };
+    overall?: DashAiOverall;
+    verdict: string;
+    severity: DashAiSuggestion['severity'];
+    indicators?: DashAiIndicator[];
+    findings: Array<{
+        priority: DashAiFinding['priority'];
+        title: string;
+        indicator?: string;
+    }>;
+    impact?: DashAiImpact;
+    basis?: DashAiRun['basis'];
+}
+/** One model's limits for a key's pool: each window's size, what it holds now, and when it is full again. */
+export interface DashAiCapacity {
+    model: string;
+    observedAt: number;
+    /** Of the tightest window, the share left (0–1). */
+    headroom: number;
+    windows: Array<{
+        name: 'requests' | 'input' | 'output' | 'tokens';
+        limit: number;
+        remaining: number;
+        fullAt?: number;
+    }>;
+}
+/** `/api/ai/tokens` — the keys this workspace may use, in order, and where their values are kept. */
+export interface DashAiTokens {
+    at: number;
+    workspace: string;
+    secrets: {
+        kind: 'macos-keychain' | 'secret-service' | 'none';
+        available: boolean;
+        note?: string;
+    };
+    providers: DashAiProviderInfo[];
+    tokens: DashAiToken[];
+    /** What this workspace's model calls cost today (UTC, estimated), and its daily cap. */
+    today: {
+        usd: number;
+        capUsd?: number;
+    };
+}
+/** One path a service read or wrote, by operation — from the fs tap's per-second aggregates. */
+export interface DashFilePath {
+    /** `<service> <op> <path>`. */
+    id: string;
+    /** Relative to the service's working directory when inside it. */
+    path: string;
+    op: 'read' | 'write' | 'append';
+    service: string;
+    /** Calls, and the bytes they moved (a stream's are not counted). */
+    n: number;
+    bytes: number;
+    /** Bytes per call in the latest second it was seen — what one read or write moves. */
+    lastBytes: number;
+    stream?: boolean;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    /** The flow of its latest call, when it ran in one. */
+    flowId?: string;
+    /** Route catalog ids whose requests touched it, most recent first. */
+    routes: string[];
+}
+/** `/api/catalog/files` — every path the services read or wrote, newest first, kept 30 days. */
+export interface DashFiles {
+    at: number;
+    paths: DashFilePath[];
+    since?: number;
+}
+/** `/api/kv/stores` — every declared Redis / Valkey store, as its server describes itself (read-only). */
+export interface DashKvStores {
+    at: number;
+    errors: string[];
+    stores: DashKvStore[];
+}
+export interface DashKvStore {
+    name: string;
+    /** `host:port`. */
+    server: string;
+    /** `Valkey 9.1.1`, `Redis 7.2.4`. */
+    engine?: string;
+    mode?: string;
+    uptimeSec?: number;
+    /** Bytes in use, and the cap (0: none). */
+    memory?: number;
+    maxMemory?: number;
+    policy?: string;
+    clients?: number;
+    opsPerSec?: number;
+    hits?: number;
+    misses?: number;
+    /** Every logical database holding keys; this checkout's (the URL's) marked. */
+    dbs: Array<{
+        db: number;
+        keys: number;
+        expires: number;
+        mine: boolean;
+    }>;
+    /** BullMQ queues found by their `<prefix>:<queue>:meta` hash, in this checkout's database. */
+    queues?: number;
+    unread?: string;
+}
+/** One key as a list shows it. */
+export interface DashKvKeyRow {
+    key: string;
+    type: string;
+    /** Milliseconds to expiry; -1 none. */
+    ttlMs: number;
+    bytes?: number;
+    /** Fields, items, members — or a string's length. */
+    length?: number;
+    /** The value's start, secrets masked. */
+    preview: string;
+    /** A BullMQ job hash: its queue and id. */
+    job?: {
+        queue: string;
+        id: string;
+    };
+}
+/** `/api/kv/keys?store=&db=&match=&cursor=` — one page of a SCAN. */
+export interface DashKvKeys {
+    at: number;
+    store: string;
+    db: number;
+    match: string;
+    /** Where the next page starts; `0` when the scan went through every key. */
+    cursor: string;
+    /** Keys the server looked at for this page (SCAN visits more than it returns under a MATCH). */
+    scanned: number;
+    /** Keys in the database (DBSIZE). */
+    total: number;
+    keys: DashKvKeyRow[];
+    error?: string;
+}
+/** `/api/kv/prefixes?store=&db=` — what the keys look like: their patterns, ids folded to `*`, from a sample. */
+export interface DashKvPrefixes {
+    at: number;
+    store: string;
+    db: number;
+    sampled: number;
+    total: number;
+    /**
+     * Each pattern with its keys in the sample and its type; for the busiest, a few of its keys described — how many of
+     * those have no expiry, and the largest one's memory (`MEMORY USAGE`).
+     */
+    patterns: Array<{
+        pattern: string;
+        keys: number;
+        type?: string;
+        described?: number;
+        noExpiry?: number;
+        maxBytes?: number;
+    }>;
+    error?: string;
+}
+/** `/api/kv/key?store=&db=&key=` — one key in full (bounded), secrets masked. */
+export interface DashKvKey {
+    at: number;
+    store: string;
+    db: number;
+    key: string;
+    type: string;
+    ttlMs: number;
+    bytes?: number;
+    encoding?: string;
+    length: number;
+    /** Field → value, index → item, member → score, id → entry; a string is one row. */
+    rows: Array<{
+        a: string;
+        b: string;
+    }>;
+    /** Only the first rows are shown. */
+    truncated: boolean;
+    job?: DashKvJob;
+    error?: string;
+}
+export interface DashKvQueue {
+    name: string;
+    /** `product-analysis-*` when the name holds an id — the queues made per run fold under it. */
+    family: string;
+    prefix: string;
+    counts: {
+        waiting: number;
+        active: number;
+        delayed: number;
+        prioritized: number;
+        paused: number;
+        waitingChildren: number;
+        completed: number;
+        failed: number;
+    };
+    version?: string;
+    paused: boolean;
+    /** Worker connections, from CLIENT LIST. */
+    workers: number;
+}
+/** `/api/kv/queues?store=&db=` — the BullMQ queues in a database. */
+export interface DashKvQueues {
+    at: number;
+    store: string;
+    db: number;
+    queues: DashKvQueue[];
+    error?: string;
+}
+/**
+ * `/api/kv/queue?store=&db=&queue=` — how one BullMQ queue is set up and what its own event stream says: its meta hash,
+ * its job schedulers (recurring work) and the newest entries of its QueueEvents stream. Read-only, values masked.
+ */
+export interface DashKvQueueDetail {
+    at: number;
+    store: string;
+    db: number;
+    queue: string;
+    prefix?: string;
+    /** The `<prefix>:<queue>:meta` hash as BullMQ keeps it: `version`, `opts.maxLenEvents`, `paused`, and — when set — the global `concurrency` and rate limit (`max` jobs per `duration` ms). */
+    meta: Record<string, string>;
+    /** The `repeat` set's members — job schedulers, next run first — with what each one's hash says. */
+    schedulers: Array<{
+        id: string;
+        next?: number;
+        name?: string;
+        pattern?: string;
+        every?: number;
+        tz?: string;
+        limit?: number;
+        endDate?: number;
+        count?: number;
+        opts?: string;
+    }>;
+    schedulersTotal: number;
+    /** The `<prefix>:<queue>:events` stream: entries kept, how many were read (newest first), the window they span, each event's count, and the failures by reason. */
+    events: {
+        kept: number;
+        read: number;
+        from?: number;
+        to?: number;
+        counts: Record<string, number>;
+        failures: Array<{
+            reason: string;
+            count: number;
+            attempts: number[];
+        }>;
+    };
+    error?: string;
+}
+export interface DashKvJob {
+    queue: string;
+    id: string;
+    name: string;
+    state: 'waiting' | 'active' | 'delayed' | 'prioritized' | 'paused' | 'waiting-children' | 'completed' | 'failed' | 'unknown';
+    /** Its data, as JSON, secrets masked, cut at 4 KB. */
+    data: string;
+    opts?: string;
+    addedAt?: number;
+    processedAt?: number;
+    finishedAt?: number;
+    delayMs?: number;
+    attemptsMade: number;
+    attemptsLimit?: number;
+    failedReason?: string;
+    stacktrace?: string[];
+    returnValue?: string;
+    progress?: string;
+    /** The flow it ran in (the lens stamps one on jobs it sees enqueued; else `job:<queue>#<id>`). */
+    flowId?: string;
+}
+/** `/api/kv/jobs?store=&db=&queue=&state=&offset=` — a queue's jobs in one state, newest first, and its history. */
+export interface DashKvJobs {
+    at: number;
+    store: string;
+    db: number;
+    queue: string;
+    state: string;
+    total: number;
+    offset: number;
+    jobs: DashKvJob[];
+    /** Finished jobs per minute, newest last — from the scores of the completed and failed sets (what BullMQ keeps). */
+    history: {
+        binMs: number;
+        from: number;
+        completed: number[];
+        failed: number[];
+    };
+    error?: string;
+}
+/** `/api/db/plan?id=` — how Postgres would run one statement: `EXPLAIN` (generic plan), never `ANALYZE`. */
+/**
+ * What a statement returned, or a sample of a table's rows — read-only, rolled back, at most a few rows, each value
+ * clipped and a column named like a credential masked. Read only for a review in a workspace that allows rows
+ * (`nx.json` → `lensmcp.ai.rows`): the rows go to the model provider.
+ */
+export interface DashDbRows {
+    at: number;
+    store?: string;
+    database?: string;
+    state: 'ok' | 'unavailable' | 'error';
+    reason?: string;
+    columns: string[];
+    rows: string[][];
+    /** More rows than were read. */
+    more: boolean;
+    /** The columns whose values were masked (named like a credential). */
+    masked: string[];
+    ms?: number;
+}
+/**
+ * A statement's whole text: the tap's, when it sent it whole — else, for one it cut at 500 characters, the text
+ * pg_stat_statements keeps of it (its constants as `$n`) — or why there is none.
+ */
+export type DashDbWhole = {
+    text: string;
+    from: 'tap' | 'pg_stat_statements';
+} | {
+    reason: string;
+};
+export interface DashDbPlan {
+    /** The whole text it planned, when the tap had cut it and pg_stat_statements kept it whole. */
+    statement?: string;
+    statementFrom?: 'pg_stat_statements';
+    at: number;
+    id: string;
+    store?: string;
+    database?: string;
+    state: 'ok' | 'unavailable' | 'error';
+    /** Why there is no plan (`the statement reached the lens cut at 500 characters`…), or Postgres's error. */
+    reason?: string;
+    /** A plan for any parameter values (Postgres 16+ `GENERIC_PLAN`), not for one run's values. */
+    generic?: boolean;
+    /** Measured: the statement ran (`EXPLAIN ANALYZE`, read-only, rolled back) with one recorded run's values. */
+    measured?: {
+        executionMs: number;
+        planningMs: number;
+        run: {
+            at: number;
+            durationMs?: number;
+            rows?: number;
+            route?: string;
+        };
+    };
+    totalCost?: number;
+    rows?: number;
+    nodes: DashDbPlanNode[];
+    /** What in the plan is worth a look (`a Seq Scan reads all of business_facts — ≈1.2M rows — to keep some`). */
+    warnings: string[];
+}
+export interface DashDbPlanNode {
+    depth: number;
+    /** `Seq Scan`, `Index Scan`, `Hash Join`… */
+    type: string;
+    relation?: string;
+    index?: string;
+    /** Postgres's estimate for this step: the total cost and the rows it expects. */
+    cost: number;
+    rows: number;
+    /** `Filter: (tenant_id = $1)`, `Index Cond: …`, `Sort Key: …`. */
+    detail: string[];
+    /** Measured plans only: the rows it produced (per loop), how many times it ran, its time over all loops, buffers. */
+    actualRows?: number;
+    loops?: number;
+    ms?: number;
+    hitBlocks?: number;
+    readBlocks?: number;
+    tempBlocks?: number;
+}
+/** What the lens did to a statement's database before a review: statistics refreshed, and why any were not. */
+export interface DashDbPrep {
+    /** `schema.table — never analyzed` / `— 1,240 changes since its last ANALYZE`. */
+    analyzed: string[];
+    /** Tables whose statistics were fresh enough. */
+    fresh: string[];
+    /** Why it could not (the role may not ANALYZE, `lens.prepare: false`…). */
+    refused?: string;
+}
+/** One thing an agent did through the lens: a tool call, a resource read, what it said it is doing. */
+export interface DashAgentEvent {
+    at: number;
+    kind: 'tool' | 'read' | 'say';
+    /** The tool or the resource URI; `agent.task` for `say`. */
+    name: string;
+    /** Its arguments, redacted, as JSON (at most 2 KB). */
+    args?: string;
+    ms?: number;
+    /** The answer's size. */
+    bytes?: number;
+    isError?: boolean;
+    /** What the answer said first, a line (a tool's first text; a read's MIME type). */
+    result?: string;
+}
+/** One MCP session — one agent connected through the lensmcp plugin and the shim to this lens. */
+export interface DashAgentSession {
+    /** A digest of its MCP session id (never the id itself). */
+    id: string;
+    client: {
+        name: string;
+        version?: string;
+    };
+    /** The lens server it talks to: the worktree's key. */
+    server: string;
+    state: 'live' | 'idle' | 'ended';
+    startedAt: number;
+    lastSeenAt: number;
+    /** Ended: when its shim exited (or, without one, its last call). */
+    endedAt?: number;
+    /** What it says it is doing (`agent.task`): the task's first line, and the step it is on. */
+    task?: string;
+    step?: string;
+    saidAt?: number;
+    conn: {
+        transport: string;
+        /** The lens server's pid, and the shim's (the `lensmcp mcp` process the client started), when it said. */
+        pid: number;
+        shim?: number;
+        protocol?: string;
+        /** New MCP sessions the shim opened for it (a server restart, a replayed `initialize`). */
+        reconnects: number;
+        calls: number;
+        reads: number;
+        errors: number;
+        lastMs?: number;
+        p95Ms?: number;
+    };
+    /** Newest last, at most 500. */
+    events: DashAgentEvent[];
+}
+export interface DashAgentSessions {
+    at: number;
+    /** Live first, then by last seen; at most 20 per server. */
+    sessions: DashAgentSession[];
+}