@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/perf/panel-health-monitor.d.ts

@@ -0,0 +1,92 @@
+/**
+ * PanelHealthMonitor — enforces per-panel resource contracts.
+ *
+ * Tracks update rate and render cost per panel. Panels that exceed their
+ * contracted budget are throttled (render gated to a minimum interval).
+ * Panels with sustained violations are degraded (rendered at a fixed low rate).
+ *
+ * The monitor does NOT render panels itself — callers ask canRender() before
+ * rendering and report the actual render cost via recordRender().
+ *
+ * This keeps the monitor policy-focused and the rendering path ignorant of
+ * throttling policy details.
+ */
+import type { PanelResourceContract, PanelHealthState } from './panel-contracts.js';
+/**
+ * PanelHealthMonitor — tracks panel resource usage and enforces budgets.
+ *
+ * Usage:
+ * 1. Register panels with register(panelId, category).
+ * 2. Before rendering: if (!monitor.canRender(panelId, now)) skip the render.
+ * 3. After rendering: monitor.recordRender(panelId, durationMs, now).
+ * 4. Read health via getHealth(panelId) or getAllHealth().
+ */
+export declare class PanelHealthMonitor {
+    private readonly _tracks;
+    /**
+     * Register a panel with the monitor.
+     *
+     * If the panel is already registered, this is a no-op.
+     *
+     * @param panelId - Unique panel identifier.
+     * @param category - Panel category (used to select the base contract).
+     * @param contractOverrides - Optional per-panel contract overrides.
+     */
+    register(panelId: string, category: string, contractOverrides?: Partial<Omit<PanelResourceContract, 'panelId'>>): void;
+    /**
+     * Deregister a panel, removing all tracking state.
+     */
+    deregister(panelId: string): void;
+    /**
+     * Check whether a panel is permitted to render at the given time.
+     *
+     * Records the render request for rate tracking regardless of the outcome.
+     * If the panel is not registered, renders are always permitted.
+     *
+     * @param panelId - Panel to check.
+     * @param now - Current epoch ms (defaults to Date.now()).
+     * @returns true if the render is permitted; false if it should be skipped.
+     */
+    canRender(panelId: string, now?: number): boolean;
+    /**
+     * Record the actual render duration for a panel.
+     *
+     * Should be called after every permitted render completes. Updates the
+     * p95 render cost and may escalate the panel's throttle status if the
+     * render cost budget is violated.
+     *
+     * @param panelId - Panel that rendered.
+     * @param durationMs - Actual render duration in milliseconds.
+     * @param now - Epoch ms at render completion (defaults to Date.now()).
+     */
+    recordRender(panelId: string, durationMs: number, now?: number): void;
+    /**
+     * Return the current health state for a panel, or undefined if not registered.
+     */
+    getHealth(panelId: string): PanelHealthState | undefined;
+    /**
+     * Return health states for all registered panels.
+     */
+    getAllHealth(): PanelHealthState[];
+    /**
+     * Return the resource contract for a registered panel, or undefined.
+     */
+    getContract(panelId: string): PanelResourceContract | undefined;
+    /**
+     * Forcibly reset a panel's health state to normal.
+     * Useful for tests or manual operator intervention.
+     */
+    resetHealth(panelId: string): void;
+    private _rotateWindow;
+    private _applyViolation;
+    /**
+     * Dual-path recovery: `_recordClean` handles render-cost-based recovery
+     * (triggered from `recordRender` after a cheap render), while `_rotateWindow`
+     * handles rate-based recovery (triggered at window boundaries). Both paths
+     * call `_recover` once the clean-window threshold is met, so either signal
+     * alone is sufficient to restore a panel to normal status.
+     */
+    private _recordClean;
+    private _recover;
+}
+//# sourceMappingURL=panel-health-monitor.d.ts.map

package/dist/_internal/platform/runtime/perf/panel-health-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel-health-monitor.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/perf/panel-health-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAqCpF;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAE9D;;;;;;;;OAQG;IACH,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC,GAClE,IAAI;IAgBP;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;;;;;;OASG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO;IAmC7D;;;;;;;;;;OAUG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,IAAI;IA2BjF;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIxD;;OAEG;IACH,YAAY,IAAI,gBAAgB,EAAE;IAIlC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAI/D;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAalC,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,eAAe;IAiBvB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,QAAQ;CAOjB"}

package/dist/_internal/platform/runtime/perf/panel-health-monitor.js

@@ -0,0 +1,239 @@
+/**
+ * PanelHealthMonitor — enforces per-panel resource contracts.
+ *
+ * Tracks update rate and render cost per panel. Panels that exceed their
+ * contracted budget are throttled (render gated to a minimum interval).
+ * Panels with sustained violations are degraded (rendered at a fixed low rate).
+ *
+ * The monitor does NOT render panels itself — callers ask canRender() before
+ * rendering and report the actual render cost via recordRender().
+ *
+ * This keeps the monitor policy-focused and the rendering path ignorant of
+ * throttling policy details.
+ */
+import { CATEGORY_CONTRACTS, buildContract, createInitialPanelHealthState, } from './panel-contracts.js';
+/** Measurement window for update-rate enforcement (ms). */
+const RATE_WINDOW_MS = 1000;
+/** Number of recent render durations to keep for p95 calculation. */
+const RENDER_SAMPLE_CAPACITY = 20;
+/** Recovery: violations reset to 0 after this many consecutive clean windows. */
+const RECOVERY_CLEAN_WINDOWS = 3;
+/**
+ * PanelHealthMonitor — tracks panel resource usage and enforces budgets.
+ *
+ * Usage:
+ * 1. Register panels with register(panelId, category).
+ * 2. Before rendering: if (!monitor.canRender(panelId, now)) skip the render.
+ * 3. After rendering: monitor.recordRender(panelId, durationMs, now).
+ * 4. Read health via getHealth(panelId) or getAllHealth().
+ */
+export class PanelHealthMonitor {
+    _tracks = new Map();
+    /**
+     * Register a panel with the monitor.
+     *
+     * If the panel is already registered, this is a no-op.
+     *
+     * @param panelId - Unique panel identifier.
+     * @param category - Panel category (used to select the base contract).
+     * @param contractOverrides - Optional per-panel contract overrides.
+     */
+    register(panelId, category, contractOverrides) {
+        if (this._tracks.has(panelId))
+            return;
+        const contract = buildContract(panelId, category, contractOverrides);
+        const health = createInitialPanelHealthState(panelId);
+        this._tracks.set(panelId, {
+            contract,
+            health,
+            renderSamples: { buf: new Array(RENDER_SAMPLE_CAPACITY), head: 0, size: 0 },
+            windowRequests: [],
+            cleanWindows: 0,
+            windowStart: 0,
+        });
+    }
+    /**
+     * Deregister a panel, removing all tracking state.
+     */
+    deregister(panelId) {
+        this._tracks.delete(panelId);
+    }
+    /**
+     * Check whether a panel is permitted to render at the given time.
+     *
+     * Records the render request for rate tracking regardless of the outcome.
+     * If the panel is not registered, renders are always permitted.
+     *
+     * @param panelId - Panel to check.
+     * @param now - Current epoch ms (defaults to Date.now()).
+     * @returns true if the render is permitted; false if it should be skipped.
+     */
+    canRender(panelId, now = Date.now()) {
+        const track = this._tracks.get(panelId);
+        if (!track)
+            return true; // unregistered panels are always permitted
+        // Rotate the measurement window if needed
+        this._rotateWindow(track, now);
+        // Gate on throttle/degrade interval
+        if (now < track.health.nextAllowedAt) {
+            track.health.totalSuppressed++;
+            return false;
+        }
+        // Record this request in the current window
+        track.windowRequests.push(now);
+        // Check update rate limit
+        let requestsInWindow = 0;
+        for (const t of track.windowRequests) {
+            if (now - t < RATE_WINDOW_MS)
+                requestsInWindow++;
+        }
+        // Note: stale entries older than RATE_WINDOW_MS are pruned at window rotation, not here
+        const maxPerWindow = track.contract.maxUpdatesPerSecond;
+        if (requestsInWindow > maxPerWindow) {
+            // Rate exceeded: throttle or degrade
+            this._applyViolation(track, now);
+            track.health.totalSuppressed++;
+            return false;
+        }
+        track.health.totalPermitted++;
+        return true;
+    }
+    /**
+     * Record the actual render duration for a panel.
+     *
+     * Should be called after every permitted render completes. Updates the
+     * p95 render cost and may escalate the panel's throttle status if the
+     * render cost budget is violated.
+     *
+     * @param panelId - Panel that rendered.
+     * @param durationMs - Actual render duration in milliseconds.
+     * @param now - Epoch ms at render completion (defaults to Date.now()).
+     */
+    recordRender(panelId, durationMs, now = Date.now()) {
+        const track = this._tracks.get(panelId);
+        if (!track)
+            return;
+        // Add sample to ring buffer (O(1) modular index — no shift/realloc)
+        const rb = track.renderSamples;
+        rb.buf[rb.head] = durationMs;
+        rb.head = (rb.head + 1) % RENDER_SAMPLE_CAPACITY;
+        if (rb.size < RENDER_SAMPLE_CAPACITY)
+            rb.size++;
+        // Update p95
+        const samples = rb.buf.slice(0, rb.size);
+        samples.sort((a, b) => a - b); // sort in-place, no second copy
+        const p95Val = samples[Math.ceil(samples.length * 0.95) - 1] ?? 0;
+        track.health.renderP95Ms = p95Val;
+        track.health.lastRenderAt = now;
+        track.health.rendersInWindow++;
+        // Check render cost budget
+        if (track.health.renderP95Ms > track.contract.maxRenderMs) {
+            this._applyViolation(track, now);
+        }
+        else {
+            // Render cost within budget — count as a clean observation
+            this._recordClean(track);
+        }
+    }
+    /**
+     * Return the current health state for a panel, or undefined if not registered.
+     */
+    getHealth(panelId) {
+        return this._tracks.get(panelId)?.health;
+    }
+    /**
+     * Return health states for all registered panels.
+     */
+    getAllHealth() {
+        return Array.from(this._tracks.values()).map((t) => ({ ...t.health }));
+    }
+    /**
+     * Return the resource contract for a registered panel, or undefined.
+     */
+    getContract(panelId) {
+        return this._tracks.get(panelId)?.contract;
+    }
+    /**
+     * Forcibly reset a panel's health state to normal.
+     * Useful for tests or manual operator intervention.
+     */
+    resetHealth(panelId) {
+        const track = this._tracks.get(panelId);
+        if (!track)
+            return;
+        track.health = createInitialPanelHealthState(panelId);
+        track.renderSamples = { buf: new Array(RENDER_SAMPLE_CAPACITY), head: 0, size: 0 };
+        track.windowRequests = [];
+        track.cleanWindows = 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    _rotateWindow(track, now) {
+        if (track.windowStart === 0) {
+            track.windowStart = now;
+            return;
+        }
+        if (now - track.windowStart >= RATE_WINDOW_MS) {
+            // Check for recovery
+            let requestsLastWindow = 0;
+            for (const t of track.windowRequests) {
+                if (t >= track.windowStart && t < track.windowStart + RATE_WINDOW_MS)
+                    requestsLastWindow++;
+            }
+            const withinBudget = requestsLastWindow <= track.contract.maxUpdatesPerSecond;
+            if (withinBudget) {
+                track.cleanWindows++;
+                if (track.cleanWindows >= RECOVERY_CLEAN_WINDOWS) {
+                    this._recover(track);
+                }
+            }
+            else {
+                track.cleanWindows = 0;
+            }
+            // Discard old requests
+            track.windowRequests = track.windowRequests.filter((t) => now - t < RATE_WINDOW_MS);
+            track.windowStart = now;
+            track.health.rendersInWindow = 0;
+        }
+    }
+    _applyViolation(track, now) {
+        track.health.consecutiveViolations++;
+        track.cleanWindows = 0;
+        if (track.health.consecutiveViolations >= track.contract.degradeAfterViolations) {
+            // Escalate to degraded
+            track.health.throttleStatus = 'degraded';
+            track.health.healthStatus = 'overloaded';
+            track.health.nextAllowedAt = now + track.contract.degradedIntervalMs;
+        }
+        else {
+            // Apply standard throttle
+            track.health.throttleStatus = 'throttled';
+            track.health.healthStatus = 'warning';
+            track.health.nextAllowedAt = now + track.contract.throttleIntervalMs;
+        }
+    }
+    /**
+     * Dual-path recovery: `_recordClean` handles render-cost-based recovery
+     * (triggered from `recordRender` after a cheap render), while `_rotateWindow`
+     * handles rate-based recovery (triggered at window boundaries). Both paths
+     * call `_recover` once the clean-window threshold is met, so either signal
+     * alone is sufficient to restore a panel to normal status.
+     */
+    _recordClean(track) {
+        // Only advance recovery if we're already throttled/degraded
+        if (track.health.throttleStatus === 'normal')
+            return;
+        track.cleanWindows++;
+        if (track.cleanWindows >= RECOVERY_CLEAN_WINDOWS) {
+            this._recover(track);
+        }
+    }
+    _recover(track) {
+        track.health.throttleStatus = 'normal';
+        track.health.healthStatus = 'healthy';
+        track.health.consecutiveViolations = 0;
+        track.health.nextAllowedAt = 0;
+        track.cleanWindows = 0;
+    }
+}

package/dist/_internal/platform/runtime/perf/reporter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PerfReporter — formats a PerfReport as a human-readable console table
+ * and provides an exit code for CI integration.
+ */
+import type { PerfReport } from './types.js';
+/**
+ * Formats a PerfReport as a multi-line string suitable for console output.
+ * Includes a header, per-metric rows, a summary, and violation details.
+ */
+export declare function formatReport(report: PerfReport): string;
+/**
+ * Returns the appropriate process exit code for a report.
+ * 0 = all budgets passed; 1 = one or more violated.
+ */
+export declare function exitCode(report: PerfReport): number;
+//# sourceMappingURL=reporter.d.ts.map

package/dist/_internal/platform/runtime/perf/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/perf/reporter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAA2C,MAAM,YAAY,CAAC;AA4CtF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CA6DvD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEnD"}

package/dist/_internal/platform/runtime/perf/reporter.js

@@ -0,0 +1,99 @@
+/**
+ * PerfReporter — formats a PerfReport as a human-readable console table
+ * and provides an exit code for CI integration.
+ */
+/** Column widths for the console table. */
+const COL = {
+    metric: 40,
+    value: 16,
+    threshold: 16,
+    status: 10,
+};
+/** Right-pads a string to the given width. */
+function pad(str, width) {
+    return str.length >= width ? str.slice(0, width) : str + ' '.repeat(width - str.length);
+}
+/** Formats a numeric value with its unit for display. */
+function formatValue(value, unit) {
+    if (unit === 'bytes') {
+        const mib = value / (1024 * 1024);
+        return `${mib.toFixed(1)} MiB/hr`;
+    }
+    if (unit === 'ms')
+        return `${value.toFixed(2)} ms`;
+    if (unit === 'percent')
+        return `${value.toFixed(1)}%`;
+    return `${value}`;
+}
+/**
+ * Builds a console-printable table row for a metric.
+ */
+function metricRow(metric, threshold, unit, violated) {
+    const status = violated ? 'FAIL' : 'ok';
+    return [
+        pad(metric.name, COL.metric),
+        pad(formatValue(metric.value, unit), COL.value),
+        pad(formatValue(threshold, unit), COL.threshold),
+        pad(status, COL.status),
+    ].join(' | ');
+}
+/**
+ * Formats a PerfReport as a multi-line string suitable for console output.
+ * Includes a header, per-metric rows, a summary, and violation details.
+ */
+export function formatReport(report) {
+    const lines = [];
+    const hr = '-'.repeat(COL.metric + COL.value + COL.threshold + COL.status + 9); // 3 column separators × 3 chars each (" | ")
+    lines.push('');
+    lines.push('Performance Budget Report');
+    lines.push(new Date(report.timestamp).toISOString());
+    lines.push(hr);
+    lines.push([
+        pad('Metric', COL.metric),
+        pad('Actual', COL.value),
+        pad('Budget', COL.threshold),
+        pad('Status', COL.status),
+    ].join(' | '));
+    lines.push(hr);
+    // Index violations by metric name for O(1) lookup
+    const violatedMetrics = new Set(report.violations.map((v) => v.budget.metric));
+    for (const metric of report.metrics) {
+        // Prefer violation budget info; fall back to DEFAULT_BUDGETS for passing metrics
+        const violation = report.violations.find((v) => v.budget.metric === metric.name);
+        const knownBudget = violation?.budget ??
+            report.violations.find((v) => v.budget.metric === metric.name)?.budget;
+        const threshold = knownBudget?.threshold ?? Infinity;
+        const unit = knownBudget?.unit ?? metric.unit;
+        lines.push(metricRow(metric, threshold, unit, violatedMetrics.has(metric.name)));
+    }
+    lines.push(hr);
+    if (report.passed) {
+        lines.push('Result: PASSED — all budgets within tolerance');
+    }
+    else {
+        lines.push(`Result: FAILED — ${report.violations.length} budget(s) exceeded tolerance`);
+        lines.push('');
+        lines.push('Violations:');
+        for (const v of report.violations) {
+            if (v.warning) {
+                lines.push(`  ${v.budget.name}: WARNING — ${v.warning}`);
+            }
+            else {
+                lines.push(`  ${v.budget.name}: actual=${formatValue(v.actual, v.budget.unit)} ` +
+                    `budget=${formatValue(v.budget.threshold, v.budget.unit)} ` +
+                    `exceeded_by=${formatValue(v.exceededBy, v.budget.unit)} ` +
+                    `consecutive=${v.consecutiveViolations}/${v.budget.tolerance}`);
+            }
+            lines.push(`    ${v.budget.description}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Returns the appropriate process exit code for a report.
+ * 0 = all budgets passed; 1 = one or more violated.
+ */
+export function exitCode(report) {
+    return report.passed ? 0 : 1;
+}

package/dist/_internal/platform/runtime/perf/types.d.ts

@@ -0,0 +1,70 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Performance budget types for CI regression gates.
+ *
+ * Defines the contracts for budget definitions, collected metrics,
+ * violations, and aggregated reports.
+ */
+/** Unit of measurement for a performance budget threshold. */
+export type PerfUnit = 'ms' | 'bytes' | 'count' | 'percent';
+/**
+ * A performance budget defines an acceptable threshold for a named metric.
+ * Violations are tracked consecutively; failure occurs when consecutiveViolations
+ * exceeds the tolerance.
+ */
+export interface PerfBudget {
+    /** Human-readable name for this budget. */
+    name: string;
+    /** The metric key this budget applies to. */
+    metric: string;
+    /** Acceptable upper bound for the metric value. */
+    threshold: number;
+    /** Unit of the threshold value. */
+    unit: PerfUnit;
+    /** Number of consecutive violations that triggers failure (e.g., 3 means fail on 3rd consecutive violation). */
+    tolerance: number;
+    /** Describes what this budget measures and why it matters. */
+    description: string;
+}
+/**
+ * A single performance metric sample collected at a point in time.
+ */
+export interface PerfMetric {
+    /** The metric key (should match a PerfBudget.metric). */
+    name: string;
+    /** The sampled value. */
+    value: number;
+    /** Unit of the value. */
+    unit: string;
+    /** Unix epoch milliseconds when this sample was collected. */
+    timestamp: number;
+}
+/**
+ * A budget violation record, produced when a metric exceeds its threshold.
+ */
+export interface BudgetViolation {
+    /** The budget that was violated. */
+    budget: PerfBudget;
+    /** The actual metric value that triggered the violation. */
+    actual: number;
+    /** How much the actual value exceeded the threshold (actual - threshold). */
+    exceededBy: number;
+    /** Number of consecutive samples that have violated this budget. */
+    consecutiveViolations: number;
+    /** Warning message when the metric was not found in the snapshot. */
+    warning?: string;
+}
+/**
+ * Aggregated performance report produced by a monitoring run.
+ */
+export interface PerfReport {
+    /** Unix epoch milliseconds when this report was generated. */
+    timestamp: number;
+    /** All metrics collected during this monitoring run. */
+    metrics: PerfMetric[];
+    /** Violations where consecutiveViolations exceeds tolerance. */
+    violations: BudgetViolation[];
+    /** True if all budgets passed (no active violations). */
+    passed: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/_internal/platform/runtime/perf/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/perf/types.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;GAKG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,gHAAgH;IAChH,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,gEAAgE;IAChE,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC;CACjB"}

package/dist/_internal/platform/runtime/perf/types.js

@@ -0,0 +1,2 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export {};

package/dist/_internal/platform/runtime/permissions/decision-log.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Structured audit log for permission decisions.
+ *
+ * DecisionLog provides an in-memory circular buffer of PermissionDecision
+ * records with structured output suitable for debugging and compliance auditing.
+ *
+ * Decisions are appended on every evaluation. The buffer is bounded to prevent
+ * unbounded memory growth during long sessions.
+ */
+import type { PermissionDecision } from './types.js';
+/**
+ * A decorated audit log entry wrapping a PermissionDecision with
+ * a monotonic sequence number for ordered retrieval.
+ */
+export interface DecisionLogEntry {
+    /** Monotonic sequence number (1-based, increments per decision). */
+    seq: number;
+    /** The full permission decision record. */
+    decision: PermissionDecision;
+}
+/** Filters for querying the decision log. */
+export interface DecisionLogQuery {
+    /** Return only decisions for this tool name. */
+    toolName?: string;
+    /** Return only allow or only deny decisions. */
+    allowed?: boolean;
+    /** Return decisions after this timestamp (epoch ms, inclusive). */
+    since?: number;
+    /** Maximum number of entries to return (default: all). */
+    limit?: number;
+}
+/**
+ * DecisionLog — Bounded circular buffer for permission decision audit records.
+ *
+ * Thread-safe for single-threaded Bun/Node runtimes (no async gaps in write path).
+ * Oldest entries are silently evicted when the buffer is full.
+ *
+ * Implements a true O(1) ring buffer with head/tail indexing to avoid O(n)
+ * Array.shift() evictions.
+ */
+export declare class DecisionLog {
+    /** Ring buffer storage (fixed-size array). */
+    private readonly buffer;
+    /** Write head: index where next entry will be written. */
+    private head;
+    /** Total entries currently stored (≤ maxEntries). */
+    private count;
+    private seq;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    /**
+     * append — Records a permission decision in the audit log.
+     *
+     * If the buffer has reached `maxEntries`, the oldest entry is silently evicted
+     * in O(1) time via ring buffer head advancement.
+     *
+     * @param decision — The completed PermissionDecision to record.
+     */
+    append(decision: PermissionDecision): void;
+    /**
+     * toArray — Returns all current entries in chronological order (oldest first).
+     */
+    private toArray;
+    /**
+     * query — Returns filtered log entries in chronological order.
+     *
+     * @param filters — Optional filter criteria.
+     */
+    query(filters?: DecisionLogQuery): DecisionLogEntry[];
+    /**
+     * latest — Returns the most recent decision, or undefined if the log is empty.
+     */
+    latest(): DecisionLogEntry | undefined;
+    /**
+     * size — Returns the current number of entries in the buffer.
+     */
+    get size(): number;
+    /**
+     * totalRecorded — Returns the total number of decisions ever recorded
+     * (including evicted entries). Monotonically increasing.
+     */
+    get totalRecorded(): number;
+    /**
+     * clear — Empties the log and resets the sequence counter.
+     * Primarily useful in tests.
+     */
+    clear(): void;
+    /**
+     * summary — Returns aggregate counts of allow/deny decisions.
+     */
+    summary(): {
+        total: number;
+        allowed: number;
+        denied: number;
+        evicted: number;
+    };
+}
+//# sourceMappingURL=decision-log.d.ts.map

package/dist/_internal/platform/runtime/permissions/decision-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-log.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/permissions/decision-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AASrD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAID,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,0DAA0D;IAC1D,OAAO,CAAC,IAAI,CAAK;IACjB,qDAAqD;IACrD,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,UAAU,GAAE,MAA4B;IAKpD;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAQ1C;;OAEG;IACH,OAAO,CAAC,OAAO;IAWf;;;;OAIG;IACH,KAAK,CAAC,OAAO,GAAE,gBAAqB,GAAG,gBAAgB,EAAE;IAmBzD;;OAEG;IACH,MAAM,IAAI,gBAAgB,GAAG,SAAS;IAOtC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAU/E"}