@lensmcp/protocol-types 1.25.3 → 1.25.6

package/index.d.ts

@@ -19,3 +19,4 @@ export * from './lib/ai-content.js';
 export * from './lib/http-exchange.js';
 export * from './lib/pod-memory.js';
 export * from './lib/perf-rules.js';
+export * from './lib/sources.js';

package/index.js

@@ -1 +1 @@
-"use strict";export*from"./lib/schema-version.js";export*from"./lib/source-location.js";export*from"./lib/context.js";export*from"./lib/event.js";export*from"./lib/node.js";export*from"./lib/edge.js";export*from"./lib/attributes.js";export*from"./lib/producer-health.js";export*from"./lib/resources.js";export*from"./lib/tokens.js";export*from"./lib/capture-demand.js";export*from"./lib/bounded-clone.js";export*from"./lib/bounded-map.js";export*from"./lib/flood-guard.js";export*from"./lib/dashboard.js";export*from"./lib/log-query.js";export*from"./lib/error-dismissal.js";export*from"./lib/ai-content.js";export*from"./lib/http-exchange.js";export*from"./lib/pod-memory.js";export*from"./lib/perf-rules.js";
+"use strict";export*from"./lib/schema-version.js";export*from"./lib/source-location.js";export*from"./lib/context.js";export*from"./lib/event.js";export*from"./lib/node.js";export*from"./lib/edge.js";export*from"./lib/attributes.js";export*from"./lib/producer-health.js";export*from"./lib/resources.js";export*from"./lib/tokens.js";export*from"./lib/capture-demand.js";export*from"./lib/bounded-clone.js";export*from"./lib/bounded-map.js";export*from"./lib/flood-guard.js";export*from"./lib/dashboard.js";export*from"./lib/log-query.js";export*from"./lib/error-dismissal.js";export*from"./lib/ai-content.js";export*from"./lib/http-exchange.js";export*from"./lib/pod-memory.js";export*from"./lib/perf-rules.js";export*from"./lib/sources.js";

package/lib/dashboard.d.ts

@@ -106,7 +106,8 @@ export interface DashService {
         min?: number;
         max?: number;
     };
-    workers: string[];
+    /** Its `serve` workers — each declared one, with what its devserver has said of it. */
+    workers: DashWorker[];
     lastColdStartMs?: number;
     restarts: number;
     buildFailed: boolean;
@@ -141,6 +142,40 @@ export interface DashService {
     /** What its running pods weigh, from their own post-GC reports (`pod-memory` events). Absent until one reports. */
     memory?: DashServiceMemory;
 }
+/**
+ * A service's `serve` worker (issues/closed/foodguard-80): a queue consumer or a background loop its devserver runs
+ * beside the pods, started again when it crashes. One that is not `running` is work nobody is doing.
+ */
+export interface DashWorker {
+    name: string;
+    /**
+     * `running` · `restarting` — it crashed and starts again at `nextAt` · `crash-looping` — it keeps crashing, each wait
+     * longer · `exited` — it ended on its own, or its bundle is missing: not started again until the next build ·
+     * `stopped` — its service stopped · `unknown` — declared, and its devserver has said nothing of it (one from before
+     * 1.25.3 says nothing).
+     */
+    state: 'running' | 'restarting' | 'crash-looping' | 'exited' | 'stopped' | 'unknown';
+    pid?: number;
+    /** When it entered this state. */
+    since?: number;
+    /** Crashes this session. */
+    crashes: number;
+    /** Crashes in a row (restarting / crash-looping). */
+    inARow?: number;
+    /** When it is started again. */
+    nextAt?: number;
+    /** Why it is not running (exited / stopped). */
+    reason?: string;
+    /** The last time it ended unasked: how, and what it printed last. */
+    lastCrash?: {
+        at: number;
+        exitCode: number | null;
+        signal: string | null;
+        reading?: string;
+        external?: boolean;
+        lines: string[];
+    };
+}
 /** A service's pods, summed: what the Cluster tab's memory column shows. Bytes throughout. */
 export interface DashServiceMemory {
     /** Heap after each pod's latest full GC. */
@@ -621,6 +656,19 @@ export interface DashDiagnostics {
         slow: number;
         warnings: number;
     };
+    /**
+     * Set on the stream's frame, which carries only what a page lists: the findings of a {@link DASH_PERF_KINDS} kind
+     * (failures are the Errors screen's, from `DashErrors`), the open ones and then the recently resolved ones, each up
+     * to a cap. These are their numbers before the cap — `open - problems.filter(open).length` is a list's «N more».
+     * Absent from older servers, whose frame held every problem.
+     */
+    totals?: {
+        open: number;
+        resolved: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
 }
 /** The problem kinds that are "slow or wasteful" — Performance's findings and the slow counter. */
 export declare const DASH_PERF_KINDS: readonly DashProblemKind[];
@@ -707,6 +755,11 @@ export interface DashErrors {
     recentOccurrences: number;
     /** Hidden by hand, and still hidden: nothing of them has been seen since. Listed so they can be restored. */
     dismissed: DashErrorGroup[];
+    /**
+     * Set on the stream's frame: each group carries at most this many `occurrences`, newest first (and the newest with a
+     * flow when none of those has one) — what Errors shows of a group. The error log keeps more; `count` is all of them.
+     */
+    occurrencesShown?: number;
 }
 /** `POST /api/errors/dismiss` and `/api/errors/restore` — the body, and the answer. */
 export interface DashErrorIds {
@@ -763,8 +816,55 @@ export type DashStreamEvent = {
 } | {
     type: 'errors';
     data: DashErrors;
+}
+/** The shell's numbers, on every tab whatever page it shows. */
+ | {
+    type: 'summary';
+    data: DashSummary;
+}
+/** Every 15 s on every connection — what tells a tab its stream is alive when its page's frames are quiet. */
+ | {
+    type: 'ping';
+    data: Record<string, never>;
 };
 export type DashStreamEventType = DashStreamEvent['type'];
+/**
+ * What a tab asks the stream for: `GET /api/stream?topics=cluster,flows` — the frames its page reads. `hello` and
+ * `ping` go to every tab, `summary` too (asked or not); `logs-resync` goes with `logs`, and the log backlog is sent
+ * only to a tab that asks for `logs`. A tab that sends no `topics` gets every frame (a UI from before topics).
+ */
+export type DashStreamTopic = 'summary' | 'session' | 'cluster' | 'kpis' | 'flows' | 'flow-rev' | 'logs' | 'diagnostics' | 'errors';
+export declare const DASH_STREAM_TOPICS: readonly DashStreamTopic[];
+/**
+ * The shell's numbers — the sidebar's badges, the top bar's counters, the scope card — for a tab whose page does not
+ * take the frame they come from. Counted by the same code as those frames, from what their producers last built.
+ * A part is absent until its producer first ran.
+ */
+export interface DashSummary {
+    /** `DashErrors.recentGroups`, and how many groups it lists (`groups.length`). */
+    errors?: {
+        recentGroups: number;
+        groups: number;
+    };
+    /** `DashDiagnostics.counts`, and each warning's title (`warnings[].title`) — the top bar's tooltip. */
+    diagnostics?: {
+        slow: number;
+        warnings: number;
+        warningTitles: string[];
+    };
+    /** Each listed flow's `lastSeenAt`, newest first, as many as `flows` lists: the «new flows» badge counts those after the tab last looked. */
+    flows?: {
+        lastSeenAt: number[];
+    };
+    /** Services down, wedged or crash-looping; and the scope card's `DashCluster.instance` and `worktrees`. */
+    cluster?: {
+        troubled: number;
+        instance?: DashCluster['instance'];
+        worktrees?: DashWorktree[];
+    };
+    /** `DashSession.setupIssues.length`. */
+    setupIssues?: number;
+}
 /**
  * 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>`
@@ -781,6 +881,8 @@ export interface DashRouteRun {
     /** Who called it: another service by name, else `client`. */
     caller?: string;
     touches: DashTouches;
+    /** Its request and response as they came in and went out (an `ingress` exchange, `/api/exchange?id=`). */
+    exchangeId?: string;
 }
 export type DashRouteChangeKind = 'new-external' | 'new-service' | 'new-query' | 'new-queue' | 'new-cache' | 'new-error' | 'gone' | 'gone-error' | 'count' | 'status' | 'duration';
 export interface DashRouteChange {
@@ -1016,8 +1118,13 @@ export interface DashExternalCall {
     /** 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. */
+/**
+ * One exchange opened in the Request & response panel: an outbound call (Data › External APIs, a flow's step) or a
+ * route's run (Routes › a route › Runs) — the call or the run, its exchange, its request's other steps.
+ */
 export interface DashExchangeView {
+    /** What was opened: an outbound call (`host` is its host), or a route's run (`host` is the service that served it). */
+    of?: 'call' | 'run';
     host: string;
     call: DashExternalCall;
     /** Absent: not captured (capture off, headers rotated away) or withheld (`withheld` says why). */
@@ -1131,6 +1238,14 @@ export interface DashSqlFinding {
     tool: string;
     at: number;
 }
+/**
+ * Why a statement is test SQL: every site it ran from is a test file (`sites`), its name starts with `test.` (`name`), or
+ * nx.json → `lensmcp.sql.test` lists it (`listed`).
+ */
+export interface DashSqlTestMark {
+    by: 'sites' | 'name' | 'listed';
+    why: string;
+}
 /**
  * A place in the services' own code where something ran — what a coding agent opens. From the stack the tap took at
  * the call: the service's nearest frame, and the callers above it.
@@ -1175,6 +1290,8 @@ export interface DashSqlTemplateSummary {
     sites?: DashCodeSite[];
     /** An unnamed statement its named version replaced (edited as it was named): that statement's id — not one to name. */
     replacedBy?: string;
+    /** Test SQL — written in a test, not in the services' code (apps/catalog sql-test.ts): not linted, named or reviewed by itself. */
+    test?: DashSqlTestMark;
     /** SELECT · INSERT · UPDATE · DELETE · …; a WITH reads as the statement it leads to. */
     verb: string;
     tables: string[];
@@ -1891,12 +2008,18 @@ export interface DashAiAnalyzer {
     folder?: string;
     /** Its runs in this checkout. */
     runs: number;
+    /**
+     * LensMCP's guide it reviews by. `/api/ai/analyzers` leaves its `text` out and says its length (`chars`):
+     * `/api/ai/analyzers/guide?id=` ({@link DashAiAnalyzerGuide}) returns it when Settings shows it — six guides and
+     * six previews in every list were 1 MB a read (FoodGuard, 2026-10-20).
+     */
     guide?: {
         id: string;
         title: string;
         version: number;
         sha: string;
-        text: string;
+        text?: string;
+        chars?: number;
     };
     indicators: Array<{
         id: string;
@@ -1919,10 +2042,14 @@ export interface DashAiAnalyzer {
         path: string;
         why: string;
     }>;
-    /** The instructions every run of it sends now, before the evidence. */
+    /**
+     * The instructions every run of it sends now, before the evidence: their size in the list (`tokens`, `chars`); the
+     * text itself (`system`) from `/api/ai/analyzers/guide?id=`, like the guide's.
+     */
     preview: {
-        system: string;
+        system?: string;
         tokens: number;
+        chars?: number;
     };
     lastRun?: {
         at: number;
@@ -1943,6 +2070,21 @@ export interface DashAiAnalyzer {
         model: string;
     };
 }
+/** `GET /api/ai/analyzers/guide?id=<analyzer>`: one analyzer's guide and what a run of it sends — fetched when Settings shows them. */
+export interface DashAiAnalyzerGuide {
+    id: string;
+    guide?: {
+        id: string;
+        title: string;
+        version: number;
+        sha: string;
+        text: string;
+    };
+    preview: {
+        system: string;
+        tokens: number;
+    };
+}
 /** 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 {
@@ -2010,8 +2152,13 @@ export interface DashAiRun {
     analyzerName: string;
     question: string;
     /** What was reviewed; `name` is a statement's name (its leading comment) — the same across its versions. */
+    /**
+     * `db`: one database (`<store>/<database>`, the health check); `dbtable`: one table (`<store>/<database>/<schema>.<table>`);
+     * `kvstore` / `queuestore`: one Redis store's keys / BullMQ queues (`<store>`); `files`: the services' file access
+     * (`files`); `external`: the external APIs the services call (`external`); `log`: one log line (its `seq`).
+     */
     target: {
-        kind: 'sql' | 'route' | 'error' | 'flow' | 'ui' | 'kv' | 'queue';
+        kind: 'sql' | 'route' | 'error' | 'flow' | 'ui' | 'kv' | 'queue' | 'db' | 'dbtable' | 'kvstore' | 'queuestore' | 'files' | 'external' | 'log';
         id: string;
         label: string;
         name?: string;
@@ -2109,7 +2256,13 @@ export interface DashAiRun {
         instructions: string;
     };
     error?: string;
+    /**
+     * The run was never sent, so nothing was reviewed: no key could pay (`no-key`), the trigger's daily allowance was
+     * spent (`over-daily-cap`), or every key was out of rate-limit room (`no-room`). A refusal, not a failed review.
+     */
+    refused?: DashAiRefusal;
 }
+export type DashAiRefusal = 'no-key' | 'over-daily-cap' | 'no-room';
 /**
  * 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.
@@ -2195,11 +2348,12 @@ export interface DashReviewStatus {
         turns?: number;
         tools?: number;
     };
-    /** The newest run, when it failed: when, and its error. */
+    /** The newest run, when it failed: when, and its error — `refused` when it was never sent (DashAiRun.refused). */
     failed?: {
         runId: string;
         at: number;
         error: string;
+        refused?: DashAiRefusal;
     };
 }
 /** A finished review in a few lines: when, its score, what it is about, the changes it asks for first. */

package/lib/dashboard.js

@@ -1 +1 @@
-"use strict";export const DASHBOARD_PROTOCOL=1,DASH_PERF_KINDS=["n-plus-one","db-in-loop","render-storm","slow-path","slow-route","slow-query","missing-index","leak","egress-slow","duplicate-requests","perf-rule","db-connection","other"],DASH_AI_TRIGGERS=["auto","click","agent"];
+"use strict";export const DASHBOARD_PROTOCOL=1,DASH_PERF_KINDS=["n-plus-one","db-in-loop","render-storm","slow-path","slow-route","slow-query","missing-index","leak","egress-slow","duplicate-requests","perf-rule","db-connection","other"],DASH_STREAM_TOPICS=["summary","session","cluster","kpis","flows","flow-rev","logs","diagnostics","errors"],DASH_AI_TRIGGERS=["auto","click","agent"];

package/lib/http-exchange.d.ts

@@ -1,5 +1,6 @@
 /**
- * One HTTP exchange the lens captured (R6): a service's outbound call as it went over the wire — its request and
+ * One HTTP exchange the lens captured (R6): a service's outbound call (`egress`), or a request it served (`ingress`
+ * — a route's run, as it came in and went out), as it went over the wire — its request and
  * response headers (redacted), the query string and the bodies (redacted, the first 64 KB of each), and for a
  * server-sent-events response every event with the moment it arrived. Kept OFF the bus, one file per exchange under
  * `.lensmcp/http/`; the bus event carries its `exchangeId`. Capture: `LENSMCP_HTTP_CAPTURE=off | headers | bodies`.
@@ -17,8 +18,11 @@ export interface HttpExchangeBody {
     /** A binary body: its digest instead of its bytes (when it was small enough to hash). */
     sha256?: string;
     truncated: boolean;
-    /** Why there is no text: `binary`, `form-data`, `stream` (a request body sent as a stream), `ai`. */
-    omitted?: 'binary' | 'form-data' | 'stream' | 'ai';
+    /**
+     * Why there is no text: `binary`, `form-data`, `stream` (a request body sent as a stream), `ai`, `encoded` (a
+     * compressed answer too big to unpack).
+     */
+    omitted?: 'binary' | 'form-data' | 'stream' | 'ai' | 'encoded';
 }
 export interface HttpExchangeStreamEvent {
     /** Since the request started. */
@@ -32,7 +36,7 @@ export interface HttpExchange {
     schemaVersion: 1;
     id: string;
     capturedAt: number;
-    side: 'egress';
+    side: 'egress' | 'ingress';
     service?: string;
     flowId?: string;
     requestId?: string;

package/lib/sources.d.ts

@@ -0,0 +1,225 @@
+/**
+ * CUSTOM SOURCES (issues/open/foodguard-81) — an application REPORTS what the lens cannot observe, as one of a closed
+ * set of typed kinds the lens knows how to draw, threshold and explain to an agent: `queue` · `loop` · `store` ·
+ * `traffic`. Phase 1 reads `queue` only — work a service keeps waiting in its OWN storage (an outbox table), which no
+ * event stream can show: FoodGuard's lens showed its BullMQ queues nearly empty while 6,389 outbox rows waited.
+ *
+ * Three hops, each with its own shape:
+ *
+ *  1. The WIRE — the snapshot a service answers on the dev route it declares in project.json (`cluster.sources`):
+ *     `{ schema: 'lensmcp.queue/v1', at, truncated?: { groups }, groups: [{ key, labels?, pending, inFlight?, failed?,
+ *     oldestPendingAt?, completedInWindow? }] }`. The service owns its query; the lens never connects to an app's
+ *     database. `@lensmcp/cluster` parses it (`source-poller.ts`) — a snapshot that does not parse is `malformed`, never
+ *     zero.
+ *  2. The BUS — the gateway's poller reports each poll as a `source: 'gateway'`, `category: 'cluster'` event whose
+ *     `raw.kind` is `source-poll` ({@link SourcePollRaw}), and each service's declaration as `source-declaration`
+ *     ({@link SourceDeclarationRaw}). A group's `key` travels as `group`: the bus redacts any field NAMED `key`
+ *     (`@lensmcp/core` `isSecretParam`), which would have turned every group into `[REDACTED]`. The cluster MIRRORS
+ *     these shapes (it does not depend on this package); a parity fixture pins both sides.
+ *  3. The READ — `apps/agent` folds them into `process://sources` ({@link SourcesReport}); the `observe.sources` and
+ *     `source.get` tools, the status signal and the dashboard read that.
+ *
+ * Everything here is REPORTED by the app, never measured by the lens: every read carries `provenance: 'reported'`.
+ * Additive only.
+ */
+/** The closed set of source kinds. */
+export declare const SOURCE_KINDS: readonly ["queue", "loop", "store", "traffic"];
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+/** The kinds this release reads; a declared kind outside it is said, not polled. */
+export declare const SOURCE_KINDS_READ: readonly ["queue"];
+export type SourceKindRead = (typeof SOURCE_KINDS_READ)[number];
+/** Every snapshot's schema: `lensmcp.<kind>/v1`. */
+export declare const sourceWireSchema: (kind: SourceKind) => string;
+export declare const QUEUE_WIRE_SCHEMA = "lensmcp.queue/v1";
+/** The resource the lens folds the polls into. */
+export declare const URI_SOURCES = "process://sources";
+/** Said on every read of a source: the app's claim, not the lens's measurement. */
+export declare const SOURCE_PROVENANCE: "reported";
+/** The finding's rule id: a queue group whose oldest pending item has waited longer than `thresholds.oldestWaitMin`. */
+export declare const QUEUE_OLDEST_WAIT_RULE = "queue/oldest-wait";
+export declare const SOURCE_EVENT_KINDS: readonly ["source-poll", "source-declaration"];
+export type SourceEventKind = (typeof SOURCE_EVENT_KINDS)[number];
+/** What ONE poll found. */
+export declare const SOURCE_POLL_STATES: readonly ["current", "unreachable", "refused", "malformed", "not-running"];
+export type SourcePollState = (typeof SOURCE_POLL_STATES)[number];
+/**
+ * What the lens says of a source when it is READ: a poll's state; `stale` — its newest report is overdue (the gateway
+ * stopped polling, or its polls are held up), so whatever it last said is no longer known; or `never-polled` —
+ * declared, and no poll has reported yet.
+ */
+export declare const SOURCE_STATES: readonly ["current", "unreachable", "refused", "malformed", "not-running", "stale", "never-polled"];
+export type SourceState = (typeof SOURCE_STATES)[number];
+export declare const SOURCE_DEFAULT_INTERVAL_SEC = 10;
+export declare const SOURCE_MIN_INTERVAL_SEC = 2;
+export declare const QUEUE_DEFAULT_OLDEST_WAIT_MIN = 10;
+/** A snapshot holds at most this many groups; a producer with more caps it and says `truncated: { groups }`. */
+export declare const SOURCE_MAX_GROUPS = 500;
+export declare const SOURCE_MAX_BYTES: number;
+/** A report is overdue — `stale` — once it is this many report periods old (and never sooner than 30 s). */
+export declare const SOURCE_STALE_PERIODS = 3;
+export declare const SOURCE_STALE_MIN_MS = 30000;
+/** When a source's newest report stops being trusted. */
+export declare function sourceStaleAfterMs(reportEveryMs: number): number;
+/** A queue source's thresholds. `stalledMin` is accepted now and judged once the lens keeps a history (phase 2). */
+export interface QueueThresholds {
+    oldestWaitMin: number;
+    stalledMin?: number;
+}
+/** One declared source, as the gateway polls it. */
+export interface SourceDeclRaw {
+    sourceKind: SourceKindRead;
+    name: string;
+    path: string;
+    intervalSec: number;
+    thresholds: QueueThresholds;
+}
+/** One group of a queue snapshot, as the bus carries it. */
+export interface QueueGroupRaw {
+    /** The service's own key for the group (`tenant/kind`) — the wire's `key`. */
+    group: string;
+    labels?: Record<string, string>;
+    pending: number;
+    inFlight?: number;
+    failed?: number;
+    /** When the oldest pending item of the group was written (ISO). `null`/absent: the service did not say. */
+    oldestPendingAt?: string | null;
+    completedInWindow?: number;
+}
+export interface QueueTotals {
+    groups: number;
+    pending: number;
+    inFlight: number;
+    failed: number;
+    /** Present when any group said it. */
+    completedInWindow?: number;
+}
+/** A queue snapshot that parsed. */
+export interface QueueSnapshotRaw {
+    /** When the SERVICE measured it (its `at`, ISO) — a group's wait is measured at this time. */
+    at: string;
+    /** When the gateway received it (epoch ms) — the snapshot's age is measured from this. */
+    receivedAt: number;
+    totals: QueueTotals;
+    /** Every group the service answered (at most {@link SOURCE_MAX_GROUPS}), the oldest-waiting first. */
+    groups: QueueGroupRaw[];
+    /** The service capped its answer: this many groups were dropped, and are in no total. */
+    truncated?: {
+        groups: number;
+    };
+}
+/** One poll of one declared source (`raw.kind: 'source-poll'`). */
+export interface SourcePollRaw extends SourceDeclRaw {
+    kind: 'source-poll';
+    provenance: typeof SOURCE_PROVENANCE;
+    /** The Nx project that declares it. */
+    project: string;
+    state: SourcePollState;
+    /** Why, for every state but `current`: the error, the status line, what did not parse, why the service was not asked. */
+    detail?: string;
+    /** The HTTP status of a `refused` answer. */
+    status?: number;
+    polledAt: number;
+    durationMs?: number;
+    /** The gateway reports this source again within this many ms — what decides when the lens calls it `stale`. */
+    reportEveryMs: number;
+    /** Polls in a row that failed (`unreachable`/`refused`/`malformed`) — the gateway backs off while it grows. */
+    failures?: number;
+    /** The LAST GOOD snapshot: this poll's when `current`, else the one before (kept, with its age), if any. */
+    snapshot?: QueueSnapshotRaw;
+    /** The owning workspace (stamped by the gateway on every service event). */
+    wsKey?: string;
+    floodSuppressed?: number;
+}
+/** A service's `cluster.sources`, as the gateway read it (`raw.kind: 'source-declaration'`). */
+export interface SourceDeclarationRaw {
+    kind: 'source-declaration';
+    project: string;
+    /** The entries it polls. */
+    sources: SourceDeclRaw[];
+    /** Each entry it does NOT poll, and why — an unknown kind or a malformed entry is said, never silently dropped. */
+    problems: string[];
+    wsKey?: string;
+}
+/** A `source-poll` event's `raw`, checked just enough to be read safely (telemetry is only partly trusted). */
+export declare function asSourcePollRaw(raw: unknown): SourcePollRaw | undefined;
+/** A `source-declaration` event's `raw`, checked just enough to be read safely. */
+export declare function asSourceDeclarationRaw(raw: unknown): SourceDeclarationRaw | undefined;
+/** One queue group, as the lens shows it. */
+export interface QueueGroupView extends QueueGroupRaw {
+    /** How long its oldest pending item had waited when the service measured it (`at − oldestPendingAt`). */
+    oldestWaitMs?: number;
+    /** That wait is longer than the source's `thresholds.oldestWaitMin`. */
+    overThreshold: boolean;
+}
+/** A queue source's headline numbers. */
+export interface QueueHeadline extends QueueTotals {
+    /** The longest wait among its groups, as of the snapshot. */
+    oldestWaitMs?: number;
+    /** Groups whose oldest wait is over the threshold. */
+    overThreshold: number;
+}
+/** One declared source, as the lens shows it. */
+export interface SourceView extends SourceDeclRaw {
+    provenance: typeof SOURCE_PROVENANCE;
+    project: string;
+    state: SourceState;
+    /** Why, for every state but `current`. */
+    detail?: string;
+    status?: number;
+    /** When the gateway last polled it (absent: `never-polled`). */
+    polledAt?: number;
+    failures?: number;
+    /** The last good snapshot's age — present whenever one is held, whatever the state. */
+    ageMs?: number;
+    /** When the service measured the last good snapshot (its `at`). */
+    snapshotAt?: string;
+    headline?: QueueHeadline;
+    /** The oldest-waiting first. Empty with `state: 'current'` is a real «nothing pending». */
+    groups: QueueGroupView[];
+    truncated?: {
+        groups: number;
+    };
+}
+/** A queue group whose oldest pending item has waited longer than its source allows. */
+export interface SourceFinding {
+    rule: typeof QUEUE_OLDEST_WAIT_RULE;
+    provenance: typeof SOURCE_PROVENANCE;
+    project: string;
+    name: string;
+    sourceKind: SourceKindRead;
+    group: string;
+    labels?: Record<string, string>;
+    pending: number;
+    oldestWaitMs: number;
+    thresholdMin: number;
+    title: string;
+    fix: string[];
+    verify: string;
+}
+/** `process://sources`. */
+export interface SourcesReport {
+    schemaVersion?: string;
+    revision?: number;
+    updatedAt?: string;
+    provenance: typeof SOURCE_PROVENANCE;
+    /** `none` until a service declares a source: nothing reports what the taps cannot see — not «nothing waits». */
+    producer: 'connected' | 'none';
+    detail?: string;
+    /** The clock every age here was measured against. */
+    readAt: number;
+    sources: SourceView[];
+    /** Groups over their threshold, from `current` snapshots — the longest wait first. */
+    findings: SourceFinding[];
+    /** Declaration entries the gateway does not poll, and why. */
+    problems: Array<{
+        project: string;
+        problem: string;
+    }>;
+    counts: Record<SourceState, number>;
+    /** Over the `current` queue snapshots only. */
+    totals: {
+        pending: number;
+        inFlight: number;
+        failed: number;
+    };
+}

package/lib/sources.js

@@ -0,0 +1 @@
+"use strict";var E=Object.defineProperty;var n=(r,t)=>E(r,"name",{value:t,configurable:!0});var f=Object.defineProperty,e=n((r,t)=>f(r,"name",{value:t,configurable:!0}),"n");export const SOURCE_KINDS=["queue","loop","store","traffic"],SOURCE_KINDS_READ=["queue"],sourceWireSchema=e(r=>`lensmcp.${r}/v1`,"sourceWireSchema"),QUEUE_WIRE_SCHEMA="lensmcp.queue/v1",URI_SOURCES="process://sources",SOURCE_PROVENANCE="reported",QUEUE_OLDEST_WAIT_RULE="queue/oldest-wait",SOURCE_EVENT_KINDS=["source-poll","source-declaration"],SOURCE_POLL_STATES=["current","unreachable","refused","malformed","not-running"],SOURCE_STATES=[...SOURCE_POLL_STATES,"stale","never-polled"],SOURCE_DEFAULT_INTERVAL_SEC=10,SOURCE_MIN_INTERVAL_SEC=2,QUEUE_DEFAULT_OLDEST_WAIT_MIN=10,SOURCE_MAX_GROUPS=500,SOURCE_MAX_BYTES=256*1024,SOURCE_STALE_PERIODS=3,SOURCE_STALE_MIN_MS=3e4;export function sourceStaleAfterMs(r){return Math.max(SOURCE_STALE_MIN_MS,SOURCE_STALE_PERIODS*Math.max(0,r))}n(sourceStaleAfterMs,"sourceStaleAfterMs"),e(sourceStaleAfterMs,"sourceStaleAfterMs");const o=e(r=>typeof r=="object"&&r!==null&&!Array.isArray(r),"isObj"),i=e(r=>typeof r=="number"&&Number.isInteger(r)&&r>=0,"isCount"),c=e(r=>typeof r=="number"&&Number.isFinite(r)&&r>0,"isTime"),a=e((r,t)=>typeof r=="string"&&r.length>0&&r.length<=t,"isStr");function l(r){if(!SOURCE_KINDS_READ.includes(r.sourceKind)||!a(r.name,200)||typeof r.path!="string"||typeof r.intervalSec!="number")return!1;const t=r.thresholds;return o(t)&&typeof t.oldestWaitMin=="number"&&t.oldestWaitMin>0}n(l,"f"),e(l,"asDecl");function p(r){if(!o(r)||!a(r.group,1e3)||!i(r.pending))return!1;for(const u of["inFlight","failed","completedInWindow"])if(r[u]!==void 0&&!i(r[u]))return!1;const t=r.oldestPendingAt;if(t!=null&&typeof t!="string")return!1;const s=r.labels;return s===void 0||o(s)&&Object.values(s).every(u=>typeof u=="string")}n(p,"l"),e(p,"asGroup");function S(r){if(!o(r)||typeof r.at!="string"||!c(r.receivedAt)||!Array.isArray(r.groups))return!1;const t=r.totals;if(!o(t)||!i(t.groups)||!i(t.pending)||!i(t.inFlight)||!i(t.failed))return!1;const s=r.truncated;return s!==void 0&&!(o(s)&&i(s.groups))?!1:r.groups.length<=SOURCE_MAX_GROUPS&&r.groups.every(p)}n(S,"d"),e(S,"asSnapshot");export function asSourcePollRaw(r){if(!(!o(r)||r.kind!=="source-poll"||!a(r.project,200)||!l(r))&&SOURCE_POLL_STATES.includes(r.state)&&!(!c(r.polledAt)||!c(r.reportEveryMs))&&!(r.snapshot!==void 0&&!S(r.snapshot))&&!(r.state==="current"&&r.snapshot===void 0))return r}n(asSourcePollRaw,"asSourcePollRaw"),e(asSourcePollRaw,"asSourcePollRaw");export function asSourceDeclarationRaw(r){if(!(!o(r)||r.kind!=="source-declaration"||!a(r.project,200))&&!(!Array.isArray(r.sources)||!r.sources.every(t=>o(t)&&l(t)))&&!(!Array.isArray(r.problems)||!r.problems.every(t=>typeof t=="string")))return r}n(asSourceDeclarationRaw,"asSourceDeclarationRaw"),e(asSourceDeclarationRaw,"asSourceDeclarationRaw");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/protocol-types",
-  "version": "1.25.3",
+  "version": "1.25.6",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",