@lensmcp/protocol-types 1.23.13 → 1.24.1

package/index.d.ts

@@ -15,3 +15,5 @@ export * from './lib/flood-guard.js';
 export * from './lib/dashboard.js';
 export * from './lib/error-dismissal.js';
 export * from './lib/ai-content.js';
+export * from './lib/pod-memory.js';
+export * from './lib/perf-rules.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/error-dismissal.js";export*from"./lib/ai-content.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/error-dismissal.js";export*from"./lib/ai-content.js";export*from"./lib/pod-memory.js";export*from"./lib/perf-rules.js";

package/lib/bounded-map.d.ts

@@ -4,7 +4,7 @@
  * Several reducers kept a session-lifetime `Map` keyed on a value taken straight off an event —
  * `raw.project`, `raw.tool`, a rule id — with no cap and no eviction. Because the bridge accepts a
  * `publish` envelope with an arbitrary `raw` and no origin check, a page the developer visited could
- * grow those maps one entry per message: `db.analyzeRuns` (issues/codex-security/19), the
+ * grow those maps one entry per message: `db.analyzeRuns` (issues/closed/codex-security-19), the
  * `producers` registries in typecheck/lint/build (21), `visual.rules` (64), and the memory
  * reducer's `ownerNodeId` map (41).
  *

package/lib/bounded-writer.d.ts

@@ -1,10 +1,14 @@
 /**
  * Per-generation cap. Override with `LENSMCP_EVENT_MAX_BYTES` (default 50 MB); 0/invalid ⇒ default.
+ *
+ * @deprecated Use `busCapsFromEnv(env).maxBytes` from `@lensmcp/core/bus-rotation`.
  */
 export declare function eventMaxBytes(env?: NodeJS.ProcessEnv): number;
 /**
  * Rotated generations kept as history (`.1` … `.N`, newest → oldest). With the live file that bounds
  * a workspace to (N+1) × the cap — ~300 MB at defaults. Override with `LENSMCP_EVENT_MAX_FILES`.
+ *
+ * @deprecated Use `busCapsFromEnv(env).maxFiles` from `@lensmcp/core/bus-rotation`.
  */
 export declare function eventMaxFiles(env?: NodeJS.ProcessEnv): number;
 /**
@@ -17,10 +21,19 @@ export declare function eventMaxFiles(env?: NodeJS.ProcessEnv): number;
  *
  * `caps` exists for tests, and passing it also bypasses the throttle so a test need not append a
  * megabyte to observe a rotation.
+ *
+ * @deprecated Use `createBusRotator(file, opts)` from `@lensmcp/core/bus-rotation`: this cascade
+ * ignores the `O_EXCL` rotation lock every LensMCP writer takes, so beside a live writer it can
+ * reorder or drop history generations (issues/closed/foodguard-42).
  */
 export declare function maybeRotateEventFile(file: string, addedBytes: number, caps?: {
     maxBytes?: number;
     maxFiles?: number;
 }): void;
-/** Test seam: forget the throttle state for a path (or all paths). */
+/**
+ * Test seam: forget the throttle state for a path (or all paths).
+ *
+ * @deprecated With `createBusRotator` from `@lensmcp/core/bus-rotation` each rotator holds its own
+ * throttle — make a new one instead.
+ */
 export declare function resetRotationThrottle(file?: string): void;

package/lib/capture-demand.d.ts

@@ -67,7 +67,7 @@ export interface CaptureRequest {
  * reducer heard it. The reducer listed the rule and counted it ("1 rule
  * registered"); the runner — the only process that RUNS rules — never learned
  * it existed. So a registered rule could not produce a violation, and "0
- * violations" read as a pass (issues/foodguard/27).
+ * violations" read as a pass (issues/closed/foodguard-27).
  *
  * Same cure: the MCP server writes the registered rules here and the runner
  * reads them before each capture.

package/lib/dashboard.d.ts

@@ -137,6 +137,33 @@ export interface DashService {
         at: number;
         title: string;
     };
+    /** What its running pods weigh, from their own post-GC reports (`pod-memory` events). Absent until one reports. */
+    memory?: DashServiceMemory;
+}
+/** 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. */
+    live: number;
+    /** Heap V8 holds reserved. */
+    reserved: number;
+    rss: number;
+    /** The boot baseline (the largest of the pods'). */
+    baseline?: number;
+    /** Hot swaps (the most any pod has done). */
+    swaps: number;
+    /** Pods that have reported. */
+    pods: number;
+    /** Closed generations proven still in memory — a leak, not garbage. */
+    retained: Array<{
+        pod: number;
+        gen: number;
+        ageMs: number;
+    }>;
+    /** The latest report. */
+    at: number;
+    trigger: string;
+    /** The cluster service name the pods report under — what `lensmcp mem <service>` takes. */
+    service?: string;
 }
 export interface DashRoute {
     host: string;
@@ -427,7 +454,9 @@ export interface DashLogsFrame {
     lines: DashLogLine[];
 }
 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' | 'other';
+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'
+/** A performance rule's finding (`perf://rules`): build or memory cost, with its fix and how to verify it. */
+ | 'perf-rule' | 'other';
 export interface DashProblem {
     /** Stable across updates — the card's identity for the resolved-lifecycle. */
     id: string;
@@ -441,6 +470,10 @@ export interface DashProblem {
     detail?: string;
     /** What to do — only when the detector itself knows; never invented. */
     fix?: string;
+    /** How to prove the fix worked — only when the detector says (performance rules). */
+    verify?: string;
+    /** Where the detector's rule is documented. */
+    docs?: string;
     /** The concrete artefact: the SQL, the stack's first frames, the failing URL. */
     code?: string;
     /** How many times it happened, when the detector counts. */

package/lib/flood-guard.d.ts

@@ -28,5 +28,13 @@ export interface FloodGuardOptions {
     perSec?: number;
     /** Max distinct fingerprints tracked before stale buckets are evicted. Default 2048. */
     maxKeys?: number;
+    /**
+     * Whether `LENSMCP_EVENT_MAX_EPS` may retune (or disable) this guard. Default `true`.
+     *
+     * That variable is the PER-FINGERPRINT knob. A guard keyed on something else — the bridge's
+     * per-connection budget (issues/closed/codex-security-32) — passes `false`, so tuning event grouping
+     * cannot silently cap a whole browser tab at 5 events/s, nor `off` disable a connection bound.
+     */
+    envOverride?: boolean;
 }
 export declare function createEventFloodGuard(opts?: FloodGuardOptions): FloodGuard;

package/lib/flood-guard.js

@@ -1 +1 @@
-"use strict";var m=Object.defineProperty;var i=(t,n)=>m(t,"name",{value:n,configurable:!0});var v=Object.defineProperty,u=i((t,n)=>v(t,"name",{value:n,configurable:!0}),"o");function p(){const t=typeof process<"u"?process.env?.LENSMCP_EVENT_MAX_EPS:void 0;if(t===void 0||t==="")return;if(t==="off")return"off";const n=Number(t);if(Number.isFinite(n))return n<=0?"off":n}i(p,"S"),u(p,"envPerSec");export function createEventFloodGuard(t){const n=p();if(n==="off")return{admit:u(()=>({ok:!0,suppressed:0}),"admit")};const l=n??t?.perSec??5,f=Math.max(1,t?.burst??Math.max(30,l*4)),c=t?.maxKeys??2048,r=new Map,d=u(o=>{for(const[s,e]of r)o-e.lastSeenAt>6e4&&r.delete(s);if(r.size>c){const s=[...r.entries()].sort((e,a)=>e[1].lastSeenAt-a[1].lastSeenAt);for(let e=0;e<s.length>>1;e++)r.delete(s[e][0])}},"evictStale");return{admit(o){const s=Date.now();let e=r.get(o);e||(r.size>=c&&d(s),e={tokens:f,lastRefillAt:s,suppressed:0,lastSeenAt:s},r.set(o,e)),e.lastSeenAt=s;const a=s-e.lastRefillAt;if(a>0&&(e.tokens=Math.min(f,e.tokens+a/1e3*l),e.lastRefillAt=s),e.tokens>=1){e.tokens-=1;const S=e.suppressed;return e.suppressed=0,{ok:!0,suppressed:S}}return e.suppressed+=1,{ok:!1,suppressed:0}}}}i(createEventFloodGuard,"createEventFloodGuard"),u(createEventFloodGuard,"createEventFloodGuard");
+"use strict";var S=Object.defineProperty;var i=(t,n)=>S(t,"name",{value:n,configurable:!0});var m=Object.defineProperty,u=i((t,n)=>m(t,"name",{value:n,configurable:!0}),"o");function d(){const t=typeof process<"u"?process.env?.LENSMCP_EVENT_MAX_EPS:void 0;if(t===void 0||t==="")return;if(t==="off")return"off";const n=Number(t);if(Number.isFinite(n))return n<=0?"off":n}i(d,"S"),u(d,"envPerSec");export function createEventFloodGuard(t){const n=t?.envOverride===!1?void 0:d();if(n==="off")return{admit:u(()=>({ok:!0,suppressed:0}),"admit")};const l=n??t?.perSec??5,f=Math.max(1,t?.burst??Math.max(30,l*4)),c=t?.maxKeys??2048,r=new Map,p=u(o=>{for(const[s,e]of r)o-e.lastSeenAt>6e4&&r.delete(s);if(r.size>c){const s=[...r.entries()].sort((e,a)=>e[1].lastSeenAt-a[1].lastSeenAt);for(let e=0;e<s.length>>1;e++)r.delete(s[e][0])}},"evictStale");return{admit(o){const s=Date.now();let e=r.get(o);e||(r.size>=c&&p(s),e={tokens:f,lastRefillAt:s,suppressed:0,lastSeenAt:s},r.set(o,e)),e.lastSeenAt=s;const a=s-e.lastRefillAt;if(a>0&&(e.tokens=Math.min(f,e.tokens+a/1e3*l),e.lastRefillAt=s),e.tokens>=1){e.tokens-=1;const v=e.suppressed;return e.suppressed=0,{ok:!0,suppressed:v}}return e.suppressed+=1,{ok:!1,suppressed:0}}}}i(createEventFloodGuard,"createEventFloodGuard"),u(createEventFloodGuard,"createEventFloodGuard");

package/lib/perf-rules.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Performance rules — problems that cost memory or compile time, found by a rule with a STABLE id, and handed to a
+ * coding agent as something it can act on: the measured evidence, the estimated cost, the FIX (steps it can apply),
+ * the VERIFY step (what clears it), and where the rule is documented.
+ *
+ * The case study behind them is FoodGuard's dev cluster on 2026-10-10: seven NestJS dev pods held 0.65–2.6 GB each
+ * and the build side another ~9.4 GB, because every service imported the ROOT barrel of a 905-file shared library,
+ * each copy of the app stayed in memory after a hot swap, and the bundle text was kept several times
+ * (`docs/lensmcp/concepts/memory-and-build-cost.mdx`).
+ *
+ * Two kinds of producer:
+ *  - BUILD rules run where the compilation is (`@lensmcp/cluster`'s dev webpack, `perf/perf-rules-plugin.ts`) and
+ *    publish `perf-rule-finding` / `perf-rule-retracted` / `perf-rule-scan` events (`source: 'perf'`,
+ *    `category: 'performance'`). The cluster MIRRORS these shapes (it does not depend on this package); a parity
+ *    fixture pins both sides.
+ *  - POD rules are evaluated by the lens itself (`apps/agent`'s `PerfRuleBook`) from the pods' own `pod-memory*`
+ *    events, which ARE the bus evidence; their verdicts are published on the lens session's bus in the same shape.
+ *
+ * The FINGERPRINT is the flood bucket (burst 30, then 5/s) — `perf-rule:<rule>:<project>:<subject>` for a finding
+ * and its retraction, `perf-rule-scan:<rule>:<project>` for the scan that says which subjects are open. Coarse on
+ * purpose; identity and evidence live in `raw`.
+ *
+ * Additive only.
+ */
+export declare const PERF_RULE_IDS: readonly ["bundle/heavy-barrel-import", "pod/heap-budget", "pod/retained-generation"];
+export type PerfRuleId = (typeof PERF_RULE_IDS)[number];
+export declare const PERF_RULE_EVENT_KINDS: readonly ["perf-rule-finding", "perf-rule-retracted", "perf-rule-scan"];
+export type PerfRuleEventKind = (typeof PERF_RULE_EVENT_KINDS)[number];
+/** The page that documents every rule: the case study, the thresholds, and how to prevent each problem. */
+export declare const PERF_RULES_DOC = "https://github.com/kiwiapps-ltd/lensmcp/blob/main/docs/lensmcp/concepts/memory-and-build-cost.mdx";
+/** Each rule's section of {@link PERF_RULES_DOC}. */
+export declare const PERF_RULE_DOCS: Readonly<Record<PerfRuleId, string>>;
+/** A finding's estimated cost. Every field is optional: a rule states only what it measured or can estimate. */
+export interface PerfRuleCost {
+    /** Modules compiled that nothing needs. */
+    modules?: number;
+    /** Bytes — of those modules, or of heap. */
+    bytes?: number;
+    /** Compile time they add, ms (estimated). */
+    compileMs?: number;
+    /** Memory they cost, MB (estimated). */
+    memoryMb?: number;
+    /** How the estimate was made — so nobody mistakes it for a measurement. */
+    basis?: string;
+}
+/** What every perf-rule event names. */
+export interface PerfRuleIdentityRaw {
+    /** A rule id (`bundle/heavy-barrel-import`). Unknown ids from a newer producer are kept, not dropped. */
+    rule: string;
+    /** The Nx project the finding is about. */
+    project: string;
+    /** What inside the project: a library (`@org/contracts`), a service. */
+    subject: string;
+    /** Events of this bucket the flood guard dropped since the last admitted one. */
+    floodSuppressed?: number;
+}
+/** A rule fired (`raw.kind: 'perf-rule-finding'`). Re-published while it holds; the newest wins. */
+export interface PerfRuleFindingRaw extends PerfRuleIdentityRaw {
+    kind: 'perf-rule-finding';
+    severity: 'warning' | 'error';
+    /** One line: what is wrong. */
+    title: string;
+    /** One or two sentences: what was measured and why it costs. */
+    summary: string;
+    /** The measurement behind it — counts, files, symbols — rule-specific. */
+    evidence: Record<string, unknown>;
+    cost: PerfRuleCost;
+    /** Steps an agent can apply, in order. */
+    fix: string[];
+    /** What to do to prove the fix, and what clears the finding. */
+    verify: string;
+    /** Where the rule is documented. */
+    docs: string;
+    detectedAt: number;
+}
+/** The condition cleared (`raw.kind: 'perf-rule-retracted'`). Same fingerprint as the finding it retracts. */
+export interface PerfRuleRetractedRaw extends PerfRuleIdentityRaw {
+    kind: 'perf-rule-retracted';
+    /** Why: `cleared` (a newer measurement no longer shows it), `pod-exited`, `released`, … */
+    reason: string;
+    at: number;
+}
+/**
+ * A completed scan of one rule over one project (`raw.kind: 'perf-rule-scan'`): the subjects open NOW. Any finding of
+ * that rule and project not listed is gone — which is how a finding published by a producer that has since restarted
+ * (and so never retracts it) still clears.
+ */
+export interface PerfRuleScanRaw {
+    kind: 'perf-rule-scan';
+    rule: string;
+    project: string;
+    open: string[];
+    at: number;
+    /** What the analysis behind this scan took, in ms (all the projects it covered). */
+    elapsedMs?: number;
+    floodSuppressed?: number;
+}
+export type PerfRuleRaw = PerfRuleFindingRaw | PerfRuleRetractedRaw | PerfRuleScanRaw;
+/** The bucket of a finding and of its retraction. */
+export declare function perfRuleFingerprint(rule: string, project: string, subject: string): string;
+/** The bucket of a rule's scans of one project. */
+export declare function perfRuleScanFingerprint(rule: string, project: string): string;
+/** A perf-rule event's `raw`, checked just enough to be read safely (telemetry is only partly trusted). */
+export declare function asPerfRuleRaw(raw: unknown): PerfRuleRaw | undefined;
+/** One open finding, as `perf://rules` lists it. */
+export interface PerfRuleFindingView {
+    rule: string;
+    project: string;
+    subject: string;
+    severity: 'warning' | 'error';
+    title: string;
+    summary: string;
+    evidence: Record<string, unknown>;
+    cost: PerfRuleCost;
+    fix: string[];
+    verify: string;
+    docs: string;
+    /** When this finding first opened (this lens session). */
+    firstSeenAt: number;
+    /** The newest measurement that still showed it. */
+    lastSeenAt: number;
+}
+/** `perf://rules` — every open performance finding, newest measurement first within each severity. */
+export interface PerfRulesReport {
+    schemaVersion: number;
+    revision: number;
+    updatedAt: string;
+    /** `connected` once any rule has reported (a finding, a retraction, a scan, or a pod reading it evaluated). */
+    producer: 'connected' | 'none';
+    /** One sentence: what is open, or why nothing is known. */
+    detail: string;
+    findings: PerfRuleFindingView[];
+    /** Open findings per rule id. */
+    counts: Record<string, number>;
+}

package/lib/perf-rules.js

@@ -0,0 +1 @@
+"use strict";var u=Object.defineProperty;var o=(r,e)=>u(r,"name",{value:e,configurable:!0});var c=Object.defineProperty,a=o((r,e)=>c(r,"name",{value:e,configurable:!0}),"o");export const PERF_RULE_IDS=["bundle/heavy-barrel-import","pod/heap-budget","pod/retained-generation"],PERF_RULE_EVENT_KINDS=["perf-rule-finding","perf-rule-retracted","perf-rule-scan"],PERF_RULES_DOC="https://github.com/kiwiapps-ltd/lensmcp/blob/main/docs/lensmcp/concepts/memory-and-build-cost.mdx",PERF_RULE_DOCS={"bundle/heavy-barrel-import":`${PERF_RULES_DOC}#bundleheavy-barrel-import`,"pod/heap-budget":`${PERF_RULES_DOC}#podheap-budget`,"pod/retained-generation":`${PERF_RULES_DOC}#podretained-generation`};export function perfRuleFingerprint(r,e,n){return`perf-rule:${r}:${e}:${n}`}o(perfRuleFingerprint,"perfRuleFingerprint"),a(perfRuleFingerprint,"perfRuleFingerprint");export function perfRuleScanFingerprint(r,e){return`perf-rule-scan:${r}:${e}`}o(perfRuleScanFingerprint,"perfRuleScanFingerprint"),a(perfRuleScanFingerprint,"perfRuleScanFingerprint");const s=/^[a-z][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/,l=12,f=4e3,t=a((r,e=f)=>typeof r=="string"&&r.length>0&&r.length<=e,"isText");export function asPerfRuleRaw(r){if(!r||typeof r!="object")return;const e=r;if(!PERF_RULE_EVENT_KINDS.includes(e.kind)||typeof e.rule!="string"||!s.test(e.rule)||!t(e.project,512))return;if(e.kind==="perf-rule-scan"){const i=e.open;return!Array.isArray(i)||i.length>256||!i.every(p=>t(p,512))?void 0:r}if(!t(e.subject,512))return;if(e.kind==="perf-rule-retracted")return r;if(e.severity!=="warning"&&e.severity!=="error"||!t(e.title)||!t(e.summary)||!t(e.verify)||!t(e.docs,1024))return;const n=e.fix;if(!(!Array.isArray(n)||n.length===0||n.length>l||!n.every(i=>t(i)))&&!(!e.evidence||typeof e.evidence!="object"||Array.isArray(e.evidence))&&!(!e.cost||typeof e.cost!="object"||Array.isArray(e.cost)))return r}o(asPerfRuleRaw,"asPerfRuleRaw"),a(asPerfRuleRaw,"asPerfRuleRaw");

package/lib/pod-memory.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Pod memory events — what a dev-cluster pod reports about its own V8 heap (issues/closed/pod-memory-01, pod-memory-02).
+ *
+ * The devserver parent (`@lensmcp/cluster`'s `main.devserver.ts`) publishes them on the bus as `source: 'memory'`,
+ * `category: 'memory'` events whose `raw.kind` is one of {@link POD_MEMORY_KINDS}; `apps/memory` folds them into
+ * `memory://pods` and `memory://leaks/suspected`, the dashboard's cluster tab into a memory column.
+ *
+ * The FINGERPRINT is the flood bucket (burst 30, then 5/s): `pod-memory:<project>` for readings and exits,
+ * `pod-memory-retained:<project>` for retention verdicts and their retractions — one per service, never per pod
+ * or generation. Identity lives here, in `raw`.
+ *
+ * `@lensmcp/cluster` does not depend on this package and MIRRORS these shapes (`pod-memory.ts`,
+ * `pod-memory-events.ts`); a parity fixture pins both sides. Additive only.
+ */
+export declare const POD_MEMORY_KINDS: readonly ["pod-memory", "pod-memory-retained", "pod-memory-released", "pod-memory-exited"];
+export type PodMemoryKind = (typeof POD_MEMORY_KINDS)[number];
+/** Who reported: stamped on every pod-memory event. */
+export interface PodMemoryIdentityRaw {
+    /** The Nx project (`LENSMCP_PROJECT`). */
+    project: string;
+    /** The cluster service name — what `lensmcp mem <service>` takes. */
+    service: string;
+    /** The devserver's pod id (`Child#<pod>`). */
+    pod: number;
+    pid: number;
+    /** The pod-tree generation of a rolling recycle (1 normally). */
+    podGeneration: number;
+    /** Events of this bucket the flood guard dropped since the last admitted one. */
+    floodSuppressed?: number;
+}
+/** What made the pod collect: `boot`, `swap-settled`, `swap+<delay>` (`swap+30s`), `idle`, `retention-check`. */
+export type PodMemoryTrigger = string;
+/** One post-GC reading (`raw.kind: 'pod-memory'`). Bytes throughout. */
+export interface PodMemoryReportRaw extends PodMemoryIdentityRaw {
+    kind: 'pod-memory';
+    trigger: PodMemoryTrigger;
+    at: number;
+    /** The app generation serving (1 = the one the pod booted with). */
+    gen: number;
+    /** Hot swaps since boot. */
+    swaps: number;
+    /** Heap in use after a full GC. */
+    live: number;
+    /** Heap in use just before it — garbage included. */
+    used: number;
+    /** Heap V8 holds reserved after the GC (`heapTotal`). */
+    reserved: number;
+    rss: number;
+    external: number;
+    /** The young generation's reserved size. */
+    youngGen: number;
+    /** V8's heap limit. */
+    limit: number;
+    /** Live heap right after the first app was built. Absent on the boot report itself (its `live` is it). */
+    baseline?: number;
+    /** How long the collection paused the pod, ms. */
+    gcMs: number;
+    /** The generation the latest swap replaced. */
+    previousGen?: number;
+    /** Is it still in memory? `null` when there is none. */
+    previousAlive: boolean | null;
+    /** Closed generations still in memory, whatever their age. */
+    closedAlive: number;
+    /** Of them, the ones past the retained bound. */
+    retained: number;
+    /** Live `NestContainer` instances, when Node could count them. */
+    containers?: number;
+    /** Whether the pod maps stack traces through source maps. */
+    sourceMaps: boolean;
+}
+/** A closed generation proven still in memory (`raw.kind: 'pod-memory-retained'`). */
+export interface PodMemoryRetainedRaw extends PodMemoryIdentityRaw {
+    kind: 'pod-memory-retained';
+    gen: number;
+    closedAt: number;
+    ageMs: number;
+    swapsSinceClose: number;
+    /** Full GCs it survived. */
+    gcs: number;
+    /** Which of its registered objects are still alive: `module`, `app`, `nestApp`, `container`, `rootModule`. */
+    alive: string[];
+    /** Live instances of the shared classes a swapped app leaks through (`NestContainer`, `ZodObject`, …). */
+    counts?: Record<string, number>;
+    /** Heap in use after the GC that proved it. */
+    live: number;
+}
+/** The retraction: a generation reported retained is gone (`raw.kind: 'pod-memory-released'`). */
+export interface PodMemoryReleasedRaw extends PodMemoryIdentityRaw {
+    kind: 'pod-memory-released';
+    gen: number;
+    closedAt: number;
+    ageMs: number;
+    /** Collected after all, or gone with its pod. */
+    reason: 'collected' | 'pod-exited';
+}
+/** The pod process is gone (`raw.kind: 'pod-memory-exited'`) — drop it. */
+export interface PodMemoryExitedRaw extends PodMemoryIdentityRaw {
+    kind: 'pod-memory-exited';
+    code: number | null;
+    signal: string | null;
+}
+export type PodMemoryRaw = PodMemoryReportRaw | PodMemoryRetainedRaw | PodMemoryReleasedRaw | PodMemoryExitedRaw;
+/** A pod-memory event's `raw`, checked just enough to be read safely (telemetry is only partly trusted). */
+export declare function asPodMemoryRaw(raw: unknown): PodMemoryRaw | undefined;

package/lib/pod-memory.js

@@ -0,0 +1 @@
+"use strict";var t=Object.defineProperty;var r=(o,e)=>t(o,"name",{value:e,configurable:!0});var d=Object.defineProperty,m=r((o,e)=>d(o,"name",{value:e,configurable:!0}),"r");export const POD_MEMORY_KINDS=["pod-memory","pod-memory-retained","pod-memory-released","pod-memory-exited"];export function asPodMemoryRaw(o){if(!o||typeof o!="object")return;const e=o;if(POD_MEMORY_KINDS.includes(e.kind)&&!(typeof e.project!="string"||!e.project)&&!(typeof e.pod!="number"||typeof e.pid!="number")&&!(e.kind==="pod-memory"&&(typeof e.live!="number"||!Number.isFinite(e.live)))&&!((e.kind==="pod-memory-retained"||e.kind==="pod-memory-released")&&typeof e.gen!="number"))return o}r(asPodMemoryRaw,"asPodMemoryRaw"),m(asPodMemoryRaw,"asPodMemoryRaw");

package/lib/resources.d.ts

@@ -13,19 +13,19 @@ export declare const ResourceEnvelopeSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ResourceEnvelope = z.infer<typeof ResourceEnvelopeSchema>;
 export declare const AgentStatusKindSchema: z.ZodEnum<{
-    warning: "warning";
+    starting: "starting";
     clean: "clean";
+    warning: "warning";
     failing: "failing";
-    starting: "starting";
 }>;
 export type AgentStatusKind = z.infer<typeof AgentStatusKindSchema>;
 export declare const AgentBlockingItemSchema: z.ZodObject<{
     source: z.ZodString;
     severity: z.ZodEnum<{
         error: "error";
+        warning: "warning";
         debug: "debug";
         info: "info";
-        warning: "warning";
         fatal: "fatal";
     }>;
     title: z.ZodString;
@@ -41,41 +41,45 @@ export declare const AgentBlockingItemSchema: z.ZodObject<{
         componentName: z.ZodOptional<z.ZodString>;
         hookName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    rule: z.ZodOptional<z.ZodString>;
+    fix: z.ZodOptional<z.ZodString>;
+    verify: z.ZodOptional<z.ZodString>;
+    docs: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type AgentBlockingItem = z.infer<typeof AgentBlockingItemSchema>;
 export declare const AgentChecksSchema: z.ZodObject<{
     typecheck: z.ZodOptional<z.ZodEnum<{
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     lint: z.ZodOptional<z.ZodEnum<{
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     build: z.ZodOptional<z.ZodEnum<{
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     runtime: z.ZodOptional<z.ZodEnum<{
         warning: "warning";
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     visual: z.ZodOptional<z.ZodEnum<{
         warning: "warning";
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     memory: z.ZodOptional<z.ZodEnum<{
         warning: "warning";
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
 }, z.core.$strip>;
 /**
@@ -109,10 +113,10 @@ export declare const AgentCurrentStatusSchema: z.ZodObject<{
     updatedAt: z.ZodOptional<z.ZodString>;
     sessionId: z.ZodString;
     status: z.ZodEnum<{
-        warning: "warning";
+        starting: "starting";
         clean: "clean";
+        warning: "warning";
         failing: "failing";
-        starting: "starting";
     }>;
     activeTab: z.ZodOptional<z.ZodString>;
     tabsWithIssues: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -120,9 +124,9 @@ export declare const AgentCurrentStatusSchema: z.ZodObject<{
         source: z.ZodString;
         severity: z.ZodEnum<{
             error: "error";
+            warning: "warning";
             debug: "debug";
             info: "info";
-            warning: "warning";
             fatal: "fatal";
         }>;
         title: z.ZodString;
@@ -138,14 +142,18 @@ export declare const AgentCurrentStatusSchema: z.ZodObject<{
             componentName: z.ZodOptional<z.ZodString>;
             hookName: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        rule: z.ZodOptional<z.ZodString>;
+        fix: z.ZodOptional<z.ZodString>;
+        verify: z.ZodOptional<z.ZodString>;
+        docs: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     warnings: z.ZodDefault<z.ZodArray<z.ZodObject<{
         source: z.ZodString;
         severity: z.ZodEnum<{
             error: "error";
+            warning: "warning";
             debug: "debug";
             info: "info";
-            warning: "warning";
             fatal: "fatal";
         }>;
         title: z.ZodString;
@@ -161,41 +169,45 @@ export declare const AgentCurrentStatusSchema: z.ZodObject<{
             componentName: z.ZodOptional<z.ZodString>;
             hookName: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        rule: z.ZodOptional<z.ZodString>;
+        fix: z.ZodOptional<z.ZodString>;
+        verify: z.ZodOptional<z.ZodString>;
+        docs: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     suggestedReads: z.ZodArray<z.ZodString>;
     checks: z.ZodOptional<z.ZodObject<{
         typecheck: z.ZodOptional<z.ZodEnum<{
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         lint: z.ZodOptional<z.ZodEnum<{
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         build: z.ZodOptional<z.ZodEnum<{
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             warning: "warning";
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         visual: z.ZodOptional<z.ZodEnum<{
             warning: "warning";
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         memory: z.ZodOptional<z.ZodEnum<{
             warning: "warning";
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
     }, z.core.$strip>>;
     server: z.ZodOptional<z.ZodObject<{
@@ -316,9 +328,9 @@ declare const CheckEntrySchema: z.ZodObject<{
     rule: z.ZodOptional<z.ZodString>;
     severity: z.ZodOptional<z.ZodEnum<{
         error: "error";
+        warning: "warning";
         debug: "debug";
         info: "info";
-        warning: "warning";
         fatal: "fatal";
     }>>;
     file: z.ZodOptional<z.ZodString>;
@@ -344,9 +356,9 @@ export declare const TypecheckCurrentSchema: z.ZodObject<{
         lastReportedAt: z.ZodNumber;
         lastRunStatus: z.ZodEnum<{
             error: "error";
-            running: "running";
             clean: "clean";
             failing: "failing";
+            running: "running";
         }>;
         lastRunDurationMs: z.ZodOptional<z.ZodNumber>;
         errorCount: z.ZodNumber;
@@ -358,9 +370,9 @@ export declare const TypecheckCurrentSchema: z.ZodObject<{
     stale: z.ZodBoolean;
     detail: z.ZodString;
     status: z.ZodEnum<{
-        unknown: "unknown";
         clean: "clean";
         failing: "failing";
+        unknown: "unknown";
     }>;
     errorCount: z.ZodNumber;
     lastRunAt: z.ZodOptional<z.ZodNumber>;
@@ -383,9 +395,9 @@ export declare const TypecheckErrorsSchema: z.ZodObject<{
         lastReportedAt: z.ZodNumber;
         lastRunStatus: z.ZodEnum<{
             error: "error";
-            running: "running";
             clean: "clean";
             failing: "failing";
+            running: "running";
         }>;
         lastRunDurationMs: z.ZodOptional<z.ZodNumber>;
         errorCount: z.ZodNumber;
@@ -405,9 +417,9 @@ export declare const TypecheckErrorsSchema: z.ZodObject<{
         rule: z.ZodOptional<z.ZodString>;
         severity: z.ZodOptional<z.ZodEnum<{
             error: "error";
+            warning: "warning";
             debug: "debug";
             info: "info";
-            warning: "warning";
             fatal: "fatal";
         }>>;
         file: z.ZodOptional<z.ZodString>;
@@ -434,9 +446,9 @@ export declare const LintCurrentSchema: z.ZodObject<{
         lastReportedAt: z.ZodNumber;
         lastRunStatus: z.ZodEnum<{
             error: "error";
-            running: "running";
             clean: "clean";
             failing: "failing";
+            running: "running";
         }>;
         lastRunDurationMs: z.ZodOptional<z.ZodNumber>;
         errorCount: z.ZodNumber;
@@ -448,10 +460,10 @@ export declare const LintCurrentSchema: z.ZodObject<{
     stale: z.ZodBoolean;
     detail: z.ZodString;
     status: z.ZodEnum<{
-        warning: "warning";
-        unknown: "unknown";
         clean: "clean";
+        warning: "warning";
         failing: "failing";
+        unknown: "unknown";
     }>;
     errorCount: z.ZodNumber;
     warningCount: z.ZodNumber;
@@ -475,9 +487,9 @@ export declare const BuildCurrentSchema: z.ZodObject<{
         lastReportedAt: z.ZodNumber;
         lastRunStatus: z.ZodEnum<{
             error: "error";
-            running: "running";
             clean: "clean";
             failing: "failing";
+            running: "running";
         }>;
         lastRunDurationMs: z.ZodOptional<z.ZodNumber>;
         errorCount: z.ZodNumber;
@@ -489,10 +501,10 @@ export declare const BuildCurrentSchema: z.ZodObject<{
     stale: z.ZodBoolean;
     detail: z.ZodString;
     status: z.ZodEnum<{
-        warning: "warning";
-        unknown: "unknown";
         clean: "clean";
+        warning: "warning";
         failing: "failing";
+        unknown: "unknown";
     }>;
     hmrUpdates: z.ZodNumber;
     lastRunAt: z.ZodOptional<z.ZodNumber>;

package/lib/resources.js

@@ -1 +1 @@
-"use strict";import{z as n}from"zod";import{SCHEMA_VERSION as i}from"./schema-version.js";import{SourceLocationSchema as r}from"./source-location.js";import{SeveritySchema as t}from"./event.js";import{ProducerHealthSchema as e}from"./producer-health.js";export const URI_SCHEMES=["agent","events","build","lint","typecheck","test","runtime","render","visual","flow","story","trace","graph","bundle","security","perf","deps","memory","browser","react","valtio","nest","next","process"],ResourceEnvelopeSchema=n.object({$schema:n.string().optional(),schemaVersion:n.literal(i),revision:n.number().int().nonnegative(),updatedAt:n.string().datetime().optional()}),AgentStatusKindSchema=n.enum(["starting","clean","warning","failing"]),AgentBlockingItemSchema=n.object({source:n.string(),severity:t,title:n.string(),fingerprint:n.string(),resource:n.string(),pageId:n.string().optional(),flowId:n.string().optional(),location:r.optional()}),AgentChecksSchema=n.object({typecheck:n.enum(["passed","failed","unknown"]).optional(),lint:n.enum(["passed","failed","unknown"]).optional(),build:n.enum(["passed","failed","unknown"]).optional(),runtime:n.enum(["passed","failed","warning","unknown"]).optional(),visual:n.enum(["passed","failed","warning","unknown"]).optional(),memory:n.enum(["passed","failed","warning","unknown"]).optional()}),AgentServerModeSchema=n.enum(["embedded","shared"]),AgentServerInfoSchema=n.object({mode:AgentServerModeSchema,pid:n.number(),startedAt:n.string(),url:n.string().optional()}),AgentCurrentStatusSchema=ResourceEnvelopeSchema.extend({sessionId:n.string(),status:AgentStatusKindSchema,activeTab:n.string().optional(),tabsWithIssues:n.array(n.string()).optional(),blocking:n.array(AgentBlockingItemSchema),warnings:n.array(AgentBlockingItemSchema).default([]),suggestedReads:n.array(n.string()),checks:AgentChecksSchema.optional(),server:AgentServerInfoSchema.optional()}),AgentStorageStatsSchema=n.object({eventsResident:n.number().int().nonnegative(),eventsResidentBytes:n.number().int().nonnegative(),eventsIngested:n.number().int().nonnegative(),eventsDropped:n.number().int().nonnegative(),eventsDroppedForBytes:n.number().int().nonnegative().optional(),eventCap:n.number().int().nonnegative().optional(),eventByteCap:n.number().int().nonnegative().optional(),artifactsResident:n.number().int().nonnegative().optional(),artifactsResidentBytes:n.number().int().nonnegative().optional(),artifactsDropped:n.number().int().nonnegative().optional(),artifactByteCap:n.number().int().nonnegative().optional(),truncatedEvents:n.number().int().nonnegative().optional(),truncatedBytesReclaimed:n.number().int().nonnegative().optional(),rawByteLimit:n.number().int().nonnegative().optional(),reducers:n.record(n.string(),n.object({residentEvents:n.number().int().nonnegative(),residentBytes:n.number().int().nonnegative(),evictedEvents:n.number().int().nonnegative(),evictedForBytes:n.number().int().nonnegative(),eventCap:n.number().int().nonnegative(),byteCap:n.number().int().nonnegative()})).optional()}),AgentSessionSchema=ResourceEnvelopeSchema.extend({sessionId:n.string(),supportedResources:n.array(n.string()),supportedTools:n.array(n.string()),supportedJobs:n.array(n.string()),supportedChannels:n.array(n.string()),subscribedByDefault:n.array(n.string()),transports:n.array(n.enum(["stdio","http","socket"])),host:n.object({platform:n.string(),node:n.string()}),project:n.object({name:n.string(),nxVersion:n.string().optional()}),storage:AgentStorageStatsSchema.optional()});const o=n.object({id:n.string(),timestamp:n.number().int().nonnegative(),message:n.string(),fingerprint:n.string(),code:n.string().optional(),rule:n.string().optional(),severity:t.optional(),file:n.string().optional(),line:n.number().int().nonnegative().optional(),column:n.number().int().nonnegative().optional(),project:n.string().optional()});export const TypecheckCurrentSchema=ResourceEnvelopeSchema.merge(e).extend({status:n.enum(["unknown","clean","failing"]),errorCount:n.number().int().nonnegative(),lastRunAt:n.number().int().nonnegative().optional()}),TypecheckErrorsSchema=ResourceEnvelopeSchema.merge(e).extend({errors:n.array(o)}),LintCurrentSchema=ResourceEnvelopeSchema.merge(e).extend({status:n.enum(["unknown","clean","warning","failing"]),errorCount:n.number().int().nonnegative(),warningCount:n.number().int().nonnegative(),lastRunAt:n.number().int().nonnegative().optional()}),BuildCurrentSchema=ResourceEnvelopeSchema.merge(e).extend({status:n.enum(["unknown","clean","warning","failing"]),hmrUpdates:n.number().int().nonnegative(),lastRunAt:n.number().int().nonnegative().optional()});
+"use strict";import{z as n}from"zod";import{SCHEMA_VERSION as i}from"./schema-version.js";import{SourceLocationSchema as o}from"./source-location.js";import{SeveritySchema as t}from"./event.js";import{ProducerHealthSchema as e}from"./producer-health.js";export const URI_SCHEMES=["agent","events","build","lint","typecheck","test","runtime","render","visual","flow","story","trace","graph","bundle","security","perf","deps","memory","browser","react","valtio","nest","next","process"],ResourceEnvelopeSchema=n.object({$schema:n.string().optional(),schemaVersion:n.literal(i),revision:n.number().int().nonnegative(),updatedAt:n.string().datetime().optional()}),AgentStatusKindSchema=n.enum(["starting","clean","warning","failing"]),AgentBlockingItemSchema=n.object({source:n.string(),severity:t,title:n.string(),fingerprint:n.string(),resource:n.string(),pageId:n.string().optional(),flowId:n.string().optional(),location:o.optional(),rule:n.string().optional(),fix:n.string().optional(),verify:n.string().optional(),docs:n.string().optional()}),AgentChecksSchema=n.object({typecheck:n.enum(["passed","failed","unknown"]).optional(),lint:n.enum(["passed","failed","unknown"]).optional(),build:n.enum(["passed","failed","unknown"]).optional(),runtime:n.enum(["passed","failed","warning","unknown"]).optional(),visual:n.enum(["passed","failed","warning","unknown"]).optional(),memory:n.enum(["passed","failed","warning","unknown"]).optional()}),AgentServerModeSchema=n.enum(["embedded","shared"]),AgentServerInfoSchema=n.object({mode:AgentServerModeSchema,pid:n.number(),startedAt:n.string(),url:n.string().optional()}),AgentCurrentStatusSchema=ResourceEnvelopeSchema.extend({sessionId:n.string(),status:AgentStatusKindSchema,activeTab:n.string().optional(),tabsWithIssues:n.array(n.string()).optional(),blocking:n.array(AgentBlockingItemSchema),warnings:n.array(AgentBlockingItemSchema).default([]),suggestedReads:n.array(n.string()),checks:AgentChecksSchema.optional(),server:AgentServerInfoSchema.optional()}),AgentStorageStatsSchema=n.object({eventsResident:n.number().int().nonnegative(),eventsResidentBytes:n.number().int().nonnegative(),eventsIngested:n.number().int().nonnegative(),eventsDropped:n.number().int().nonnegative(),eventsDroppedForBytes:n.number().int().nonnegative().optional(),eventCap:n.number().int().nonnegative().optional(),eventByteCap:n.number().int().nonnegative().optional(),artifactsResident:n.number().int().nonnegative().optional(),artifactsResidentBytes:n.number().int().nonnegative().optional(),artifactsDropped:n.number().int().nonnegative().optional(),artifactByteCap:n.number().int().nonnegative().optional(),truncatedEvents:n.number().int().nonnegative().optional(),truncatedBytesReclaimed:n.number().int().nonnegative().optional(),rawByteLimit:n.number().int().nonnegative().optional(),reducers:n.record(n.string(),n.object({residentEvents:n.number().int().nonnegative(),residentBytes:n.number().int().nonnegative(),evictedEvents:n.number().int().nonnegative(),evictedForBytes:n.number().int().nonnegative(),eventCap:n.number().int().nonnegative(),byteCap:n.number().int().nonnegative()})).optional()}),AgentSessionSchema=ResourceEnvelopeSchema.extend({sessionId:n.string(),supportedResources:n.array(n.string()),supportedTools:n.array(n.string()),supportedJobs:n.array(n.string()),supportedChannels:n.array(n.string()),subscribedByDefault:n.array(n.string()),transports:n.array(n.enum(["stdio","http","socket"])),host:n.object({platform:n.string(),node:n.string()}),project:n.object({name:n.string(),nxVersion:n.string().optional()}),storage:AgentStorageStatsSchema.optional()});const r=n.object({id:n.string(),timestamp:n.number().int().nonnegative(),message:n.string(),fingerprint:n.string(),code:n.string().optional(),rule:n.string().optional(),severity:t.optional(),file:n.string().optional(),line:n.number().int().nonnegative().optional(),column:n.number().int().nonnegative().optional(),project:n.string().optional()});export const TypecheckCurrentSchema=ResourceEnvelopeSchema.merge(e).extend({status:n.enum(["unknown","clean","failing"]),errorCount:n.number().int().nonnegative(),lastRunAt:n.number().int().nonnegative().optional()}),TypecheckErrorsSchema=ResourceEnvelopeSchema.merge(e).extend({errors:n.array(r)}),LintCurrentSchema=ResourceEnvelopeSchema.merge(e).extend({status:n.enum(["unknown","clean","warning","failing"]),errorCount:n.number().int().nonnegative(),warningCount:n.number().int().nonnegative(),lastRunAt:n.number().int().nonnegative().optional()}),BuildCurrentSchema=ResourceEnvelopeSchema.merge(e).extend({status:n.enum(["unknown","clean","warning","failing"]),hmrUpdates:n.number().int().nonnegative(),lastRunAt:n.number().int().nonnegative().optional()});

package/package.json

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