@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/runtime/ops/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Type definitions for operational runbooks.
+ *
+ * Playbooks are machine-readable structured runbooks consumed by the
+ * diagnostics panel and the ops registry. Each playbook describes
+ * symptoms, diagnostic checks, resolution steps, and escalation criteria.
+ */
+/** Severity level of a diagnostic check result. */
+export type DiagnosticSeverity = 'info' | 'warning' | 'error' | 'critical';
+/** Result of running a single diagnostic check. */
+export interface DiagnosticCheckResult {
+    /** Whether the check passed. */
+    readonly passed: boolean;
+    /** Human-readable summary of the check outcome. */
+    readonly summary: string;
+    /** Optional structured context for the diagnostics panel. */
+    readonly context?: Record<string, string | number | boolean>;
+    /** Severity when the check fails. */
+    readonly severity: DiagnosticSeverity;
+}
+/**
+ * A single diagnostic check.
+ *
+ * The `run` function must not throw — it should catch all internal errors
+ * and return them as a failing check result.
+ */
+export interface DiagnosticCheck {
+    /** Unique identifier for this check (e.g. 'queue.overflow'). */
+    readonly id: string;
+    /** Short human-readable label. */
+    readonly label: string;
+    /** Longer description of what this check verifies. */
+    readonly description: string;
+    /** Execute the check and return a result. Never throws. */
+    readonly run: () => Promise<DiagnosticCheckResult>;
+}
+/** Category of action required for a step. */
+export type PlaybookStepKind = 'command' | 'config' | 'observe' | 'wait' | 'escalate';
+/** A single resolution step within a playbook. */
+export interface PlaybookStep {
+    /** Step number (1-indexed). */
+    readonly step: number;
+    /** Short title for display in the diagnostics panel. */
+    readonly title: string;
+    /** Detailed action description. */
+    readonly action: string;
+    /** Category of this step. */
+    readonly kind: PlaybookStepKind;
+    /**
+     * For 'command' steps: the command or API call to run.
+     * For 'config' steps: the config key and value to set.
+     * For 'wait' steps: condition description.
+     * Optional for 'observe' and 'escalate' steps.
+     */
+    readonly command?: string;
+    /** Expected outcome if the step succeeds. */
+    readonly expectedOutcome?: string;
+    /** Whether this step can be safely automated. */
+    readonly automatable: boolean;
+}
+/** A complete operational runbook. */
+export interface Playbook {
+    /** Unique identifier (e.g. 'stuck-turn'). */
+    readonly id: string;
+    /** Short human-readable name. */
+    readonly name: string;
+    /** Description of what this playbook addresses. */
+    readonly description: string;
+    /**
+     * Observable symptoms that suggest this playbook applies.
+     * Used by the diagnostics panel to surface relevant runbooks.
+     */
+    readonly symptoms: string[];
+    /**
+     * Diagnostic checks to run when this playbook is triggered.
+     * Results are displayed in the diagnostics panel.
+     */
+    readonly checks: DiagnosticCheck[];
+    /** Ordered resolution steps. */
+    readonly steps: PlaybookStep[];
+    /**
+     * Conditions that indicate the issue has escalated beyond
+     * automated remediation and requires human intervention.
+     */
+    readonly escalationCriteria: string[];
+    /** Tags for filtering/categorisation in the diagnostics panel. */
+    readonly tags: string[];
+}
+/** Registry entry wrapping a playbook with metadata. */
+export interface PlaybookRegistryEntry {
+    readonly playbook: Playbook;
+    /** Version string (semver-like, e.g. '1.0.0'). */
+    readonly version: string;
+    /** ISO timestamp of when this playbook was last updated. */
+    readonly updatedAt: string;
+}
+/** A map of playbook IDs to their registry entries. */
+export type PlaybookRegistry = Map<string, PlaybookRegistryEntry>;
+//# sourceMappingURL=types.d.ts.map

package/dist/platform/runtime/ops/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/ops/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,mDAAmD;AACnD,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3E,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC7D,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACpD;AAID,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,QAAQ,GACR,SAAS,GACT,MAAM,GACN,UAAU,CAAC;AAEf,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAID,sCAAsC;AACtC,MAAM,WAAW,QAAQ;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC;IACnC,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;CACzB;AAID,wDAAwD;AACxD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC"}

package/dist/platform/runtime/ops/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for operational runbooks.
+ *
+ * Playbooks are machine-readable structured runbooks consumed by the
+ * diagnostics panel and the ops registry. Each playbook describes
+ * symptoms, diagnostic checks, resolution steps, and escalation criteria.
+ */
+export {};

package/dist/platform/runtime/perf/budgets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Default performance budget definitions for goodvibes-sdk.
+ *
+ * Measurable budgets for frame latency,
+ * event throughput, tool executor overhead, memory growth, and
+ * compaction latency.
+ */
+import type { PerfBudget } from './types.js';
+/**
+ * The default set of performance budgets applied in CI.
+ *
+ * These represent acceptable operational thresholds. Any metric that
+ * consistently exceeds its budget beyond the tolerance window will
+ * cause CI to fail.
+ */
+export declare const DEFAULT_BUDGETS: PerfBudget[];
+//# sourceMappingURL=budgets.d.ts.map

package/dist/platform/runtime/perf/budgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budgets.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/perf/budgets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAiHvC,CAAC"}

package/dist/platform/runtime/perf/budgets.js

@@ -0,0 +1,117 @@
+/**
+ * Default performance budget definitions for goodvibes-sdk.
+ *
+ * Measurable budgets for frame latency,
+ * event throughput, tool executor overhead, memory growth, and
+ * compaction latency.
+ */
+/**
+ * The default set of performance budgets applied in CI.
+ *
+ * These represent acceptable operational thresholds. Any metric that
+ * consistently exceeds its budget beyond the tolerance window will
+ * cause CI to fail.
+ */
+export const DEFAULT_BUDGETS = [
+    {
+        name: 'Frame Render Latency (p95)',
+        metric: 'frame.render.p95',
+        threshold: 16,
+        unit: 'ms',
+        tolerance: 3,
+        description: 'p95 frame render duration must stay under 16ms to maintain 60fps. ' +
+            'Sustained violations indicate rendering bottlenecks under operational load.',
+    },
+    {
+        name: 'Event Queue Depth',
+        metric: 'event.queue.depth',
+        threshold: 1000,
+        unit: 'count',
+        tolerance: 5,
+        description: 'Event queue must not accumulate more than 1000 pending events. ' +
+            'Deep queues indicate the event loop cannot drain fast enough.',
+    },
+    {
+        name: 'Tool Executor Overhead (p95)',
+        metric: 'tool.executor.overhead.p95',
+        threshold: 5,
+        unit: 'ms',
+        tolerance: 3,
+        description: 'p95 overhead per tool executor phase (scheduling, dispatch, teardown) ' +
+            'must be under 5ms. Sustained violations indicate executor inefficiency.',
+    },
+    {
+        name: 'Memory Growth Rate',
+        metric: 'memory.growth.bytes_per_hour',
+        threshold: 52_428_800, // 50 MiB in bytes
+        unit: 'bytes',
+        tolerance: 2,
+        description: 'Sustained heap growth must remain below 50 MiB/hour. ' +
+            'Faster growth indicates a memory leak in long-running sessions.',
+    },
+    {
+        name: 'Compaction Latency (p95)',
+        metric: 'compaction.latency.p95',
+        threshold: 500,
+        unit: 'ms',
+        tolerance: 3,
+        description: 'p95 compaction duration must be under 500ms. ' +
+            'Slower compaction blocks the conversation loop and degrades UX.',
+    },
+    // ── SLO Gates ──────────────────────────────────────────────────────────────
+    {
+        name: 'SLO: Turn Start Latency (p95)',
+        metric: 'slo.turn_start.p95',
+        threshold: 2000,
+        unit: 'ms',
+        tolerance: 3,
+        description: 'p95 duration from TURN_SUBMITTED to first STREAM_DELTA must be under 2000ms. ' +
+            'Sustained violations indicate provider latency or pipeline overhead regression.',
+    },
+    {
+        name: 'SLO: Cancel Latency (p95)',
+        metric: 'slo.cancel.p95',
+        threshold: 500,
+        unit: 'ms',
+        tolerance: 3,
+        description: 'p95 duration from TURN_CANCEL to confirmed turn stop must be under 500ms. ' +
+            'Sustained violations indicate the cancellation path is blocked or too slow.',
+    },
+    {
+        name: 'SLO: Reconnect Recovery (p95)',
+        metric: 'slo.reconnect_recovery.p95',
+        threshold: 10000,
+        unit: 'ms',
+        tolerance: 3,
+        description: 'p95 duration from TRANSPORT_RECONNECTING to TRANSPORT_CONNECTED must be under 10000ms. ' +
+            'Sustained violations indicate degraded transport reliability.',
+    },
+    {
+        name: 'SLO: Permission Decision (p95)',
+        metric: 'slo.permission_decision.p95',
+        threshold: 100,
+        unit: 'ms',
+        tolerance: 3,
+        description: 'p95 duration from PERMISSION_REQUESTED to DECISION_EMITTED must be under 100ms. ' +
+            'Sustained violations indicate permission pipeline overhead regression.',
+    },
+    // ── Integration Delivery SLO ─────────────────────────────────────────────
+    {
+        name: 'SLO: Integration Delivery Success Rate',
+        metric: 'slo.integration.delivery_success_rate',
+        threshold: 95,
+        unit: 'percent',
+        tolerance: 3,
+        description: 'Integration delivery success rate must remain above 95% over any 100-delivery window. '
+            + 'Sustained violations indicate systemic integration delivery failures requiring investigation.',
+    },
+    {
+        name: 'SLO: Integration DLQ Depth',
+        metric: 'slo.integration.dlq_depth',
+        threshold: 10,
+        unit: 'count',
+        tolerance: 3,
+        description: 'Integration dead-letter queue depth must remain below 10 entries. '
+            + 'A deeper queue indicates persistent delivery failures that require manual replay or investigation.',
+    },
+];

package/dist/platform/runtime/perf/monitor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * PerfMonitor — collects metrics from the runtime store and evaluates
+ * them against registered performance budgets.
+ *
+ * The monitor maintains a violation streak counter per budget so that
+ * transient spikes do not trip CI; only sustained regressions fail.
+ */
+import type { SurfacePerfDomainState } from '../store/domains/surface-perf.js';
+import type { PerfBudget, PerfReport } from './types.js';
+/**
+ * Snapshot of runtime state provided to the monitor for metric extraction.
+ * Callers supply this from the store or from test fixtures.
+ */
+export interface PerfSnapshot {
+    /** Current surface performance domain state. */
+    surfacePerf: SurfacePerfDomainState;
+    /**
+     * Optional additional metric overrides keyed by metric name.
+     * Useful for injecting tool executor or compaction metrics from
+     * other subsystems that are not yet reflected in the store domain.
+     */
+    extraMetrics?: Record<string, number>;
+}
+/**
+ * PerfMonitor collects metrics from a runtime snapshot, evaluates them
+ * against a set of performance budgets, and tracks consecutive violation
+ * streaks per budget.
+ *
+ * @example
+ * ```ts
+ * const monitor = new PerfMonitor();
+ * const report = monitor.evaluate(snapshot);
+ * if (!report.passed) process.exit(1);
+ * ```
+ */
+export declare class PerfMonitor {
+    private readonly budgets;
+    /** Maps budget metric name to number of consecutive violations. */
+    private readonly streaks;
+    /** Heap snapshot from the previous evaluation, used to compute growth delta. */
+    private _previousHeapUsedBytes;
+    constructor(budgets?: PerfBudget[]);
+    /**
+     * Extracts PerfMetrics from a PerfSnapshot.
+     *
+     * Metrics derived from SurfacePerfDomainState:
+     * - frame.render.p95 — p95 of recentCycles.durationMs
+     * - memory.growth.bytes_per_hour — heap growth rate since previous evaluate()
+     *
+     * Metrics from extraMetrics (pass-through):
+     * - event.queue.depth
+     * - tool.executor.overhead.p95
+     * - compaction.latency.p95
+     */
+    private extractMetrics;
+    /**
+     * Evaluates the given snapshot against all registered budgets.
+     * Updates internal violation streak counters.
+     *
+     * @param snapshot - Runtime state snapshot to evaluate.
+     * @returns A PerfReport summarising metrics and active violations.
+     */
+    evaluate(snapshot: PerfSnapshot): PerfReport;
+    /** Resets all violation streak counters. */
+    reset(): void;
+    /** Returns the current violation streak for a given metric, or 0. */
+    streak(metric: string): number;
+}
+//# sourceMappingURL=monitor.d.ts.map

package/dist/platform/runtime/perf/monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/perf/monitor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,KAAK,EACV,UAAU,EAGV,UAAU,EACX,MAAM,YAAY,CAAC;AAGpB;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,WAAW,EAAE,sBAAsB,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAaD;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,gFAAgF;IAChF,OAAO,CAAC,sBAAsB,CAAa;gBAE/B,OAAO,GAAE,UAAU,EAAoB;IAInD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;IA4CtB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,UAAU;IAgD5C,4CAA4C;IAC5C,KAAK,IAAI,IAAI;IAIb,qEAAqE;IACrE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;CAG/B"}

package/dist/platform/runtime/perf/monitor.js

@@ -0,0 +1,148 @@
+/**
+ * PerfMonitor — collects metrics from the runtime store and evaluates
+ * them against registered performance budgets.
+ *
+ * The monitor maintains a violation streak counter per budget so that
+ * transient spikes do not trip CI; only sustained regressions fail.
+ */
+import { DEFAULT_BUDGETS } from './budgets.js';
+/**
+ * Computes the 95th percentile from a numeric array.
+ * Returns 0 for empty arrays.
+ */
+function p95(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const idx = Math.ceil(sorted.length * 0.95) - 1;
+    return sorted[Math.max(0, idx)] ?? 0;
+}
+/**
+ * PerfMonitor collects metrics from a runtime snapshot, evaluates them
+ * against a set of performance budgets, and tracks consecutive violation
+ * streaks per budget.
+ *
+ * @example
+ * ```ts
+ * const monitor = new PerfMonitor();
+ * const report = monitor.evaluate(snapshot);
+ * if (!report.passed) process.exit(1);
+ * ```
+ */
+export class PerfMonitor {
+    budgets;
+    /** Maps budget metric name to number of consecutive violations. */
+    streaks = new Map();
+    /** Heap snapshot from the previous evaluation, used to compute growth delta. */
+    _previousHeapUsedBytes = 0;
+    constructor(budgets = DEFAULT_BUDGETS) {
+        this.budgets = budgets;
+    }
+    /**
+     * Extracts PerfMetrics from a PerfSnapshot.
+     *
+     * Metrics derived from SurfacePerfDomainState:
+     * - frame.render.p95 — p95 of recentCycles.durationMs
+     * - memory.growth.bytes_per_hour — heap growth rate since previous evaluate()
+     *
+     * Metrics from extraMetrics (pass-through):
+     * - event.queue.depth
+     * - tool.executor.overhead.p95
+     * - compaction.latency.p95
+     */
+    extractMetrics(snapshot, now) {
+        const { surfacePerf, extraMetrics = {} } = snapshot;
+        const metrics = [];
+        // Frame render p95
+        const renderDurations = surfacePerf.recentCycles.map((c) => c.durationMs);
+        metrics.push({
+            name: 'frame.render.p95',
+            value: p95(renderDurations),
+            unit: 'ms',
+            timestamp: now,
+        });
+        // Memory growth rate: extrapolate bytes/hour from heap delta since last evaluate().
+        // If no prior sample is available, fall back to 0 (can't compute rate).
+        const lastSampleAge = surfacePerf.lastMemorySampleAt !== undefined
+            ? now - surfacePerf.lastMemorySampleAt
+            : 0;
+        const heapDelta = surfacePerf.heapUsedBytes - this._previousHeapUsedBytes;
+        const bytesPerHour = lastSampleAge > 0 ? (heapDelta / lastSampleAge) * 3_600_000 : 0;
+        this._previousHeapUsedBytes = surfacePerf.heapUsedBytes;
+        metrics.push({
+            name: 'memory.growth.bytes_per_hour',
+            value: bytesPerHour,
+            unit: 'bytes',
+            timestamp: now,
+        });
+        // Pass-through extra metrics
+        for (const [metricName, value] of Object.entries(extraMetrics)) {
+            const budget = this.budgets.find((b) => b.metric === metricName);
+            metrics.push({
+                name: metricName,
+                value,
+                unit: budget?.unit ?? 'count',
+                timestamp: now,
+            });
+        }
+        return metrics;
+    }
+    /**
+     * Evaluates the given snapshot against all registered budgets.
+     * Updates internal violation streak counters.
+     *
+     * @param snapshot - Runtime state snapshot to evaluate.
+     * @returns A PerfReport summarising metrics and active violations.
+     */
+    evaluate(snapshot) {
+        const now = Date.now();
+        const metrics = this.extractMetrics(snapshot, now);
+        const violations = [];
+        for (const budget of this.budgets) {
+            const metric = metrics.find((m) => m.name === budget.metric);
+            if (!metric) {
+                // Metric not found — add a warning entry instead of silently passing
+                violations.push({
+                    budget,
+                    actual: NaN,
+                    exceededBy: NaN,
+                    consecutiveViolations: 0,
+                    warning: `Metric '${budget.metric}' not found in snapshot`,
+                });
+                continue;
+            }
+            const actual = metric.value;
+            if (actual > budget.threshold) {
+                const prev = this.streaks.get(budget.metric) ?? 0;
+                const consecutiveViolations = prev + 1;
+                this.streaks.set(budget.metric, consecutiveViolations);
+                if (consecutiveViolations >= budget.tolerance) {
+                    violations.push({
+                        budget,
+                        actual,
+                        exceededBy: actual - budget.threshold,
+                        consecutiveViolations,
+                    });
+                }
+            }
+            else {
+                // Reset streak on passing sample
+                this.streaks.set(budget.metric, 0);
+            }
+        }
+        return {
+            timestamp: now,
+            metrics,
+            violations,
+            passed: violations.length === 0,
+        };
+    }
+    /** Resets all violation streak counters. */
+    reset() {
+        this.streaks.clear();
+    }
+    /** Returns the current violation streak for a given metric, or 0. */
+    streak(metric) {
+        return this.streaks.get(metric) ?? 0;
+    }
+}

package/dist/platform/runtime/perf/panel-contracts.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Panel resource contracts — per-panel CPU/IO/update budget definitions.
+ *
+ * Each panel declares a resource contract describing its acceptable update
+ * rate and render cost. The PanelHealthMonitor enforces these contracts at
+ * runtime, throttling or degrading panels that exceed their budgets.
+ */
+/** Throttle status for a panel. */
+export type PanelThrottleStatus = 'normal' | 'throttled' | 'degraded';
+/** Health of a single panel based on contract compliance. */
+export type PanelHealthStatus = 'healthy' | 'warning' | 'overloaded';
+/**
+ * Resource contract for a single panel.
+ *
+ * Defines the maximum acceptable update rate and render cost budget.
+ * Violations trigger throttling; sustained violations trigger degradation.
+ */
+export interface PanelResourceContract {
+    /** Panel id this contract applies to. */
+    panelId: string;
+    /**
+     * Maximum updates per second the panel is allowed to request.
+     * Panels that exceed this rate are throttled.
+     */
+    maxUpdatesPerSecond: number;
+    /**
+     * Maximum acceptable render duration in milliseconds (p95).
+     * Panels that consistently exceed this are degraded.
+     */
+    maxRenderMs: number;
+    /**
+     * Minimum interval in milliseconds between renders when throttled.
+     * The monitor enforces this floor when the panel exceeds its update rate.
+     */
+    throttleIntervalMs: number;
+    /**
+     * Number of consecutive budget violations before moving to 'degraded' status.
+     * Degraded panels render at a fixed reduced rate regardless of update requests.
+     */
+    degradeAfterViolations: number;
+    /**
+     * Fixed render interval in milliseconds when the panel is degraded.
+     * Replaces throttleIntervalMs for severely overloaded panels.
+     */
+    degradedIntervalMs: number;
+}
+/**
+ * Live health state for a single panel, maintained by the PanelHealthMonitor.
+ */
+export interface PanelHealthState {
+    /** Panel id. */
+    panelId: string;
+    /** Current throttle status. */
+    throttleStatus: PanelThrottleStatus;
+    /** Current health status. */
+    healthStatus: PanelHealthStatus;
+    /** Observed render count over the last measurement window. */
+    rendersInWindow: number;
+    /** p95 render duration in ms over the last measurement window. */
+    renderP95Ms: number;
+    /** Number of consecutive contract violations (update rate or render cost). */
+    consecutiveViolations: number;
+    /** Epoch ms when the panel was last allowed to render. */
+    lastRenderAt: number;
+    /** Epoch ms of next allowed render (0 = no restriction). */
+    nextAllowedAt: number;
+    /** Total renders suppressed due to throttle or degradation since monitor start. */
+    totalSuppressed: number;
+    /** Total renders permitted since monitor start. */
+    totalPermitted: number;
+}
+/**
+ * Default resource contracts by panel category.
+ *
+ * Panels without an explicit contract inherit from their category default.
+ * Active/interactive panels get more generous budgets; monitoring panels
+ * are throttled aggressively to prevent render storms.
+ */
+export declare const CATEGORY_CONTRACTS: Record<string, Omit<PanelResourceContract, 'panelId'>>;
+/**
+ * Build a PanelResourceContract for a panel, merging category defaults
+ * with any per-panel overrides.
+ *
+ * @param panelId - The panel's unique id.
+ * @param category - The panel's category (used to select the base contract).
+ * @param overrides - Optional per-panel overrides applied on top of the category contract.
+ */
+export declare function buildContract(panelId: string, category: string, overrides?: Partial<Omit<PanelResourceContract, 'panelId'>>): PanelResourceContract;
+/**
+ * Create an initial (clean) PanelHealthState for a panel.
+ */
+export declare function createInitialPanelHealthState(panelId: string): PanelHealthState;
+//# sourceMappingURL=panel-contracts.d.ts.map

package/dist/platform/runtime/perf/panel-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel-contracts.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/perf/panel-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,mCAAmC;AACnC,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;AAEtE,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB;IAChB,OAAO,EAAE,MAAM,CAAC;IAEhB,+BAA+B;IAC/B,cAAc,EAAE,mBAAmB,CAAC;IAEpC,6BAA6B;IAC7B,YAAY,EAAE,iBAAiB,CAAC;IAEhC,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IAExB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IAEpB,8EAA8E;IAC9E,qBAAqB,EAAE,MAAM,CAAC;IAE9B,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IAErB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IAEtB,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IAExB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,CA4CrF,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC,GAC1D,qBAAqB,CAOvB;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAa/E"}

package/dist/platform/runtime/perf/panel-contracts.js

@@ -0,0 +1,92 @@
+/**
+ * Panel resource contracts — per-panel CPU/IO/update budget definitions.
+ *
+ * Each panel declares a resource contract describing its acceptable update
+ * rate and render cost. The PanelHealthMonitor enforces these contracts at
+ * runtime, throttling or degrading panels that exceed their budgets.
+ */
+/**
+ * Default resource contracts by panel category.
+ *
+ * Panels without an explicit contract inherit from their category default.
+ * Active/interactive panels get more generous budgets; monitoring panels
+ * are throttled aggressively to prevent render storms.
+ */
+export const CATEGORY_CONTRACTS = {
+    development: {
+        maxUpdatesPerSecond: 10,
+        maxRenderMs: 20,
+        throttleIntervalMs: 100,
+        degradeAfterViolations: 5,
+        degradedIntervalMs: 500,
+    },
+    agent: {
+        maxUpdatesPerSecond: 5,
+        maxRenderMs: 30,
+        throttleIntervalMs: 200,
+        degradeAfterViolations: 5,
+        degradedIntervalMs: 1000,
+    },
+    monitoring: {
+        maxUpdatesPerSecond: 2,
+        maxRenderMs: 50,
+        throttleIntervalMs: 500,
+        degradeAfterViolations: 3,
+        degradedIntervalMs: 2000,
+    },
+    session: {
+        maxUpdatesPerSecond: 4,
+        maxRenderMs: 25,
+        throttleIntervalMs: 250,
+        degradeAfterViolations: 5,
+        degradedIntervalMs: 1000,
+    },
+    ai: {
+        maxUpdatesPerSecond: 8,
+        maxRenderMs: 20,
+        throttleIntervalMs: 125,
+        degradeAfterViolations: 5,
+        degradedIntervalMs: 500,
+    },
+    /** Fallback for unrecognised categories. */
+    default: {
+        maxUpdatesPerSecond: 5,
+        maxRenderMs: 30,
+        throttleIntervalMs: 200,
+        degradeAfterViolations: 5,
+        degradedIntervalMs: 1000,
+    },
+};
+/**
+ * Build a PanelResourceContract for a panel, merging category defaults
+ * with any per-panel overrides.
+ *
+ * @param panelId - The panel's unique id.
+ * @param category - The panel's category (used to select the base contract).
+ * @param overrides - Optional per-panel overrides applied on top of the category contract.
+ */
+export function buildContract(panelId, category, overrides) {
+    const base = CATEGORY_CONTRACTS[category] ?? CATEGORY_CONTRACTS['default'];
+    return {
+        panelId,
+        ...base,
+        ...overrides,
+    };
+}
+/**
+ * Create an initial (clean) PanelHealthState for a panel.
+ */
+export function createInitialPanelHealthState(panelId) {
+    return {
+        panelId,
+        throttleStatus: 'normal',
+        healthStatus: 'healthy',
+        rendersInWindow: 0,
+        renderP95Ms: 0,
+        consecutiveViolations: 0,
+        lastRenderAt: 0,
+        nextAllowedAt: 0,
+        totalSuppressed: 0,
+        totalPermitted: 0,
+    };
+}