@pellux/goodvibes-sdk 0.18.14 → 0.18.16

package/dist/_internal/platform/runtime/perf/slo-collector.js

@@ -0,0 +1,324 @@
+/**
+ * SloCollector — collects SLO duration measurements from runtime events.
+ *
+ * Listens to the RuntimeEventBus and tracks four critical path latencies:
+ * - turn_start_ms: TURN_SUBMITTED → first STREAM_DELTA
+ * - cancel_ms: TURN_CANCEL → TURN_COMPLETED or TURN_ERROR
+ * - reconnect_recovery_ms: TRANSPORT_RECONNECTING → TRANSPORT_CONNECTED
+ * - permission_decision_ms: PERMISSION_REQUESTED → DECISION_EMITTED
+ *
+ * Maintains a capped rolling window of measurements per SLO and exposes
+ * p95 values for PerfMonitor integration via `getMetrics()`.
+ */
+/** Metric key constants for each SLO measurement. */
+export const SLO_METRICS = {
+    TURN_START: 'slo.turn_start.p95',
+    CANCEL: 'slo.cancel.p95',
+    RECONNECT_RECOVERY: 'slo.reconnect_recovery.p95',
+    PERMISSION_DECISION: 'slo.permission_decision.p95',
+};
+/** Maximum number of samples retained in each rolling window. */
+const WINDOW_SIZE = 200;
+/**
+ * Maximum age for a pending map entry before it is swept as stale.
+ * Entries that never receive a follow-up event (e.g. TURN_CANCEL without
+ * TURN_COMPLETED due to a connection drop) are evicted after this duration
+ * to prevent unbounded memory growth.
+ */
+const PENDING_TTL_MS = 60_000;
+/** Interval between periodic stale-entry sweeps (ms). */
+const SWEEP_INTERVAL_MS = 30_000;
+/**
+ * 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;
+}
+/**
+ * Appends a sample to a capped rolling window.
+ * Evicts the oldest entry when the window exceeds WINDOW_SIZE.
+ */
+function appendSample(window, sample) {
+    window.push(sample);
+    if (window.length > WINDOW_SIZE) {
+        window.shift();
+    }
+}
+/**
+ * Coerce a strongly-typed bus callback argument to the raw envelope shape.
+ *
+ * The RuntimeEventBus `on()` callback receives a per-event typed envelope,
+ * but SloCollector reads only generic fields (`.ts`, `.payload.*`). The
+ * double-cast is intentional: we lose specificity to gain a uniform access
+ * pattern, isolated to this single conversion site.
+ */
+function toRaw(env) {
+    return env;
+}
+/**
+ * Safely extract a named field from an envelope payload.
+ * Returns `undefined` when the field does not exist on the payload.
+ */
+function getField(envelope, key) {
+    const payload = envelope.payload;
+    return payload[key];
+}
+/**
+ * SloCollector subscribes to RuntimeEventBus events and tracks per-SLO
+ * duration samples in rolling windows. Call `getMetrics()` to retrieve
+ * current p95 values compatible with PerfMonitor's extraMetrics field.
+ *
+ * @example
+ * ```ts
+ * const collector = new SloCollector(bus);
+ * const metrics = collector.getMetrics();
+ * const report = monitor.evaluate({ uiPerf, extraMetrics: Object.fromEntries(
+ *   metrics.map(m => [m.name, m.value])
+ * )});
+ * collector.dispose();
+ * ```
+ */
+export class SloCollector {
+    /** Rolling window of turn_start_ms samples (TURN_SUBMITTED → first STREAM_DELTA). */
+    _turnStartSamples = [];
+    /** Rolling window of cancel_ms samples (TURN_CANCEL → TURN_COMPLETED/ERROR). */
+    _cancelSamples = [];
+    /** Rolling window of reconnect_recovery_ms samples (TRANSPORT_RECONNECTING → TRANSPORT_CONNECTED). */
+    _reconnectSamples = [];
+    /** Rolling window of permission_decision_ms samples (PERMISSION_REQUESTED → DECISION_EMITTED). */
+    _permissionSamples = [];
+    /** Pending turn start timestamps keyed by turnId. */
+    _pendingTurnStart = new Map();
+    /** Tracks which turnIds have received their first STREAM_DELTA. */
+    _seenFirstDelta = new Set();
+    /** Pending cancel timestamps keyed by turnId (set on TURN_CANCEL). */
+    _pendingCancel = new Map();
+    /** Pending reconnect start timestamp. Only the most recent reconnect attempt is tracked. */
+    _pendingReconnectAt = null;
+    /** Pending permission request timestamps keyed by callId. */
+    _pendingPermission = new Map();
+    /** Registered unsubscribe functions. */
+    _unsubs = [];
+    /** Timer handle for the periodic stale-entry sweep. */
+    _sweepTimer = null;
+    constructor(bus) {
+        this._subscribe(bus);
+        this._sweepTimer = setInterval(() => this._sweepPending(), SWEEP_INTERVAL_MS);
+    }
+    /**
+     * Attach all event listeners to the bus.
+     */
+    _subscribe(bus) {
+        // ── turn_start_ms ───────────────────────────────────────────────────────
+        this._unsubs.push(bus.on('TURN_SUBMITTED', (env) => {
+            const e = toRaw(env);
+            const turnId = getField(e, 'turnId');
+            if (turnId !== undefined) {
+                this._pendingTurnStart.set(turnId, e.ts);
+                this._seenFirstDelta.delete(turnId);
+            }
+        }));
+        this._unsubs.push(bus.on('STREAM_DELTA', (env) => {
+            const e = toRaw(env);
+            const turnId = getField(e, 'turnId');
+            if (turnId === undefined)
+                return;
+            if (this._seenFirstDelta.has(turnId))
+                return;
+            this._seenFirstDelta.add(turnId);
+            const startAt = this._pendingTurnStart.get(turnId);
+            if (startAt !== undefined) {
+                appendSample(this._turnStartSamples, e.ts - startAt);
+                this._pendingTurnStart.delete(turnId);
+            }
+        }));
+        // Clean up stale pending turn starts when a turn ends without streaming
+        this._unsubs.push(bus.on('PREFLIGHT_FAIL', (env) => {
+            const e = toRaw(env);
+            const turnId = getField(e, 'turnId');
+            if (turnId !== undefined) {
+                this._pendingTurnStart.delete(turnId);
+                this._seenFirstDelta.delete(turnId);
+                this._pendingCancel.delete(turnId);
+            }
+        }));
+        this._unsubs.push(bus.on('TURN_ERROR', (env) => {
+            const e = toRaw(env);
+            const turnId = getField(e, 'turnId');
+            if (turnId !== undefined) {
+                this._pendingTurnStart.delete(turnId);
+                this._seenFirstDelta.delete(turnId);
+                // Resolve cancel if pending
+                const cancelAt = this._pendingCancel.get(turnId);
+                if (cancelAt !== undefined) {
+                    appendSample(this._cancelSamples, e.ts - cancelAt);
+                    this._pendingCancel.delete(turnId);
+                }
+            }
+        }));
+        this._unsubs.push(bus.on('TURN_COMPLETED', (env) => {
+            const e = toRaw(env);
+            const turnId = getField(e, 'turnId');
+            if (turnId !== undefined) {
+                this._pendingTurnStart.delete(turnId);
+                this._seenFirstDelta.delete(turnId);
+                // Resolve cancel if pending
+                const cancelAt = this._pendingCancel.get(turnId);
+                if (cancelAt !== undefined) {
+                    appendSample(this._cancelSamples, e.ts - cancelAt);
+                    this._pendingCancel.delete(turnId);
+                }
+            }
+        }));
+        // ── cancel_ms ───────────────────────────────────────────────────────────
+        this._unsubs.push(bus.on('TURN_CANCEL', (env) => {
+            const e = toRaw(env);
+            const turnId = getField(e, 'turnId');
+            if (turnId !== undefined) {
+                this._pendingCancel.set(turnId, e.ts);
+            }
+        }));
+        // ── reconnect_recovery_ms ───────────────────────────────────────────────
+        this._unsubs.push(bus.on('TRANSPORT_RECONNECTING', (env) => {
+            const e = toRaw(env);
+            const attempt = getField(e, 'attempt');
+            // Track start of reconnect sequence; use first attempt timestamp
+            if (attempt === 1 || this._pendingReconnectAt === null) {
+                this._pendingReconnectAt = e.ts;
+            }
+        }));
+        this._unsubs.push(bus.on('TRANSPORT_CONNECTED', (env) => {
+            const e = toRaw(env);
+            if (this._pendingReconnectAt !== null) {
+                appendSample(this._reconnectSamples, e.ts - this._pendingReconnectAt);
+                this._pendingReconnectAt = null;
+            }
+        }));
+        // Clear pending reconnect on terminal failure
+        this._unsubs.push(bus.on('TRANSPORT_TERMINAL_FAILURE', () => {
+            this._pendingReconnectAt = null;
+        }));
+        // ── permission_decision_ms ──────────────────────────────────────────────
+        this._unsubs.push(bus.on('PERMISSION_REQUESTED', (env) => {
+            const e = toRaw(env);
+            const callId = getField(e, 'callId');
+            if (callId !== undefined) {
+                this._pendingPermission.set(callId, e.ts);
+            }
+        }));
+        this._unsubs.push(bus.on('DECISION_EMITTED', (env) => {
+            const e = toRaw(env);
+            const callId = getField(e, 'callId');
+            if (callId !== undefined) {
+                const startAt = this._pendingPermission.get(callId);
+                if (startAt !== undefined) {
+                    appendSample(this._permissionSamples, e.ts - startAt);
+                    this._pendingPermission.delete(callId);
+                }
+            }
+        }));
+    }
+    /**
+     * Sweep all pending maps and evict entries older than PENDING_TTL_MS.
+     *
+     * Called periodically by the sweep timer to prevent unbounded memory growth
+     * when expected follow-up events (e.g. TURN_COMPLETED after TURN_CANCEL)
+     * never arrive due to connection drops or unexpected process termination.
+     */
+    _sweepPending() {
+        const cutoff = Date.now() - PENDING_TTL_MS;
+        for (const [key, ts] of this._pendingTurnStart) {
+            if (ts < cutoff) {
+                this._pendingTurnStart.delete(key);
+                this._seenFirstDelta.delete(key);
+            }
+        }
+        for (const [key, ts] of this._pendingCancel) {
+            if (ts < cutoff)
+                this._pendingCancel.delete(key);
+        }
+        for (const [key, ts] of this._pendingPermission) {
+            if (ts < cutoff)
+                this._pendingPermission.delete(key);
+        }
+        // _pendingReconnectAt is a scalar; clear if stale
+        if (this._pendingReconnectAt !== null && this._pendingReconnectAt < cutoff) {
+            this._pendingReconnectAt = null;
+        }
+    }
+    /**
+     * Returns current p95 values for all four SLO metrics as PerfMetric entries.
+     * Metrics with no samples return a value of 0.
+     *
+     * Intended for use with `PerfMonitor.evaluate()` via the `extraMetrics` field:
+     * ```ts
+     * const extras = Object.fromEntries(collector.getMetrics().map(m => [m.name, m.value]));
+     * monitor.evaluate({ uiPerf, extraMetrics: extras });
+     * ```
+     */
+    getMetrics() {
+        const now = Date.now();
+        return [
+            {
+                name: SLO_METRICS.TURN_START,
+                value: p95(this._turnStartSamples),
+                unit: 'ms',
+                timestamp: now,
+            },
+            {
+                name: SLO_METRICS.CANCEL,
+                value: p95(this._cancelSamples),
+                unit: 'ms',
+                timestamp: now,
+            },
+            {
+                name: SLO_METRICS.RECONNECT_RECOVERY,
+                value: p95(this._reconnectSamples),
+                unit: 'ms',
+                timestamp: now,
+            },
+            {
+                name: SLO_METRICS.PERMISSION_DECISION,
+                value: p95(this._permissionSamples),
+                unit: 'ms',
+                timestamp: now,
+            },
+        ];
+    }
+    /**
+     * Returns the number of samples collected for each SLO metric.
+     * Useful for diagnostics to distinguish "no data yet" from an actual 0ms result.
+     */
+    getSampleCounts() {
+        return {
+            [SLO_METRICS.TURN_START]: this._turnStartSamples.length,
+            [SLO_METRICS.CANCEL]: this._cancelSamples.length,
+            [SLO_METRICS.RECONNECT_RECOVERY]: this._reconnectSamples.length,
+            [SLO_METRICS.PERMISSION_DECISION]: this._permissionSamples.length,
+        };
+    }
+    /**
+     * Unsubscribes all event listeners and releases resources.
+     * The collector should not be used after disposal.
+     */
+    dispose() {
+        if (this._sweepTimer !== null) {
+            clearInterval(this._sweepTimer);
+            this._sweepTimer = null;
+        }
+        for (const unsub of this._unsubs) {
+            unsub();
+        }
+        this._unsubs.length = 0;
+        this._pendingTurnStart.clear();
+        this._seenFirstDelta.clear();
+        this._pendingCancel.clear();
+        this._pendingPermission.clear();
+        this._pendingReconnectAt = null;
+    }
+}

package/dist/_internal/platform/runtime/permissions/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Runtime permissions public API barrel.
+ *
+ * Exports the LayeredPolicyEvaluator, all types, rule evaluators, safety checks,
+ * and the createPermissionEvaluator() factory function.
+ *
+ * Feature flag: `permissions-policy-engine` must be enabled to use this module in production.
+ */
+export { LayeredPolicyEvaluator } from '@pellux/goodvibes-sdk/platform/runtime/permissions/evaluator';
+export { DecisionLog } from '@pellux/goodvibes-sdk/platform/runtime/permissions/decision-log';
+export { runSafetyChecks } from '@pellux/goodvibes-sdk/platform/runtime/permissions/safety-checks';
+export { PermissionSimulator, SimulationEnforcementError } from '@pellux/goodvibes-sdk/platform/runtime/permissions/simulation';
+export { buildDefaultPolicySimulationScenarios, runPolicySimulationScenarios } from '@pellux/goodvibes-sdk/platform/runtime/permissions/simulation-scenarios';
+export { lintPolicyConfig } from '@pellux/goodvibes-sdk/platform/runtime/permissions/lint';
+export { buildPolicyPreflightReview } from './preflight.js';
+export { buildPermissionRuleSuggestions } from './rule-suggestions.js';
+export { signBundle, verifyBundle, canonicalise } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-signer';
+export { loadPolicyBundle, createUnsignedBundle, PolicySignatureError } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-loader';
+export type { PermissionMode, CommandClassification, DecisionReason, SourceLayer, EvaluationStep, PermissionDecision, PolicyRule, PrefixRule, ArgShapeRule, PathScopeRule, NetworkScopeRule, ModeConstraintRule, RuleOrigin, PermissionsConfig, SimulationMode, SimulationResult, DivergenceType, DivergenceRecord, DivergenceStats, DivergenceReport, PermissionSimulatorConfig, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/types';
+export type { DecisionLogEntry, DecisionLogQuery } from '@pellux/goodvibes-sdk/platform/runtime/permissions/decision-log';
+export type { SafetyCheckResult } from '@pellux/goodvibes-sdk/platform/runtime/permissions/safety-checks';
+export type { PolicyLintFinding, PolicyLintSeverity } from '@pellux/goodvibes-sdk/platform/runtime/permissions/lint';
+export type { PermissionRuleSuggestion } from './rule-suggestions.js';
+export type { PolicyPreflightStatus, PolicyPreflightServer, PolicyPreflightIssue, PolicyPreflightReview, } from './preflight.js';
+export type { PolicySimulationScenario, PolicySimulationScenarioResult, PolicySimulationSummary, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/simulation-scenarios';
+export type { PolicyBundleId, SignatureStatus, ProvenanceSource, SignedPolicyBundle, VerifyResult, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-signer';
+export type { PolicyBundlePayload, BundleProvenance, PolicyLoadResult, PolicyLoaderOptions, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-loader';
+export { evaluatePrefixRule, evaluateArgShapeRule, evaluatePathScopeRule, evaluateNetworkScopeRule, evaluateModeConstraintRule, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/rules/index';
+export { DivergenceDashboard, DivergenceGateError, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/divergence-dashboard';
+export type { DivergenceTrendEntry, EnforceGateStatus, EnforceGateResult, DivergenceDashboardSnapshot, DivergenceDashboardConfig, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/divergence-dashboard';
+export { PolicyRegistry } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-registry';
+export { PolicyRuntimeState, } from './policy-runtime.js';
+export type { BundleLifecycleState, PolicyBundleVersion, PolicyDiffResult, PromoteResult, RollbackResult, PolicyRegistryConfig, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-registry';
+import { LayeredPolicyEvaluator } from '@pellux/goodvibes-sdk/platform/runtime/permissions/evaluator';
+import { PermissionSimulator } from '@pellux/goodvibes-sdk/platform/runtime/permissions/simulation';
+import type { PermissionsConfig, SimulationMode, PermissionSimulatorConfig } from '@pellux/goodvibes-sdk/platform/runtime/permissions/types';
+import type { FeatureFlagManager } from '@pellux/goodvibes-sdk/platform/runtime/feature-flags/manager';
+import type { BundleProvenance } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-loader';
+/**
+ * createPermissionEvaluator — Factory function for the runtime permission evaluator.
+ *
+ * Returns a LayeredPolicyEvaluator configured with the given options.
+ * Designed as the primary entry point for integrating the runtime permissions system.
+ *
+ * The returned evaluator exposes:
+ *   - `evaluate(toolName, args)` — perform a full layered evaluation
+ *   - `recordSessionOverride(...)` — cache a user prompt response
+ *   - `log` — DecisionLog for audit queries
+ *   - `getMode()` — inspect the active mode
+ *
+ * @example
+ * ```ts
+ * const perms = createPermissionEvaluator({ mode: 'default', rules: [] });
+ * const decision = perms.evaluate('write', { path: '/tmp/out.txt' });
+ * if (!decision.allowed) {
+ *   console.error('denied:', decision.reason);
+ * }
+ * ```
+ *
+ * @param config     — Optional configuration; all fields have safe defaults.
+ * @param provenance — Optional bundle provenance (GC-PERM-011).
+ */
+export declare function createPermissionEvaluator(config?: PermissionsConfig, provenance?: BundleProvenance): LayeredPolicyEvaluator;
+/**
+ * createPermissionSimulator — Factory for `PermissionSimulator`.
+ *
+ * Creates a dual-evaluator simulation pipeline for the runtime permissions system that runs
+ * both the actual and simulated evaluators in parallel, tracking divergence.
+ *
+ * Requires the `permissions-simulation` feature flag to be enabled.
+ *
+ * @param actualConfig    — Config for the authoritative evaluator.
+ * @param simulatedConfig — Config for the candidate evaluator.
+ * @param simulationMode  — Controls enforcement and warning behaviour.
+ * @param config          — Optional tuning: record limit, divergence threshold.
+ *
+ * @example
+ * ```ts
+ * const simulator = createPermissionSimulator(
+ *   { mode: 'default', rules: currentRules },
+ *   { mode: 'default', rules: candidateRules },
+ *   'warn-on-divergence',
+ * );
+ * const result = simulator.evaluate('write', { path: '/tmp/out.txt' });
+ * const report = simulator.getDivergenceReport();
+ * ```
+ */
+export declare function createPermissionSimulator(actualConfig: PermissionsConfig, simulatedConfig: PermissionsConfig, simulationMode: SimulationMode, config?: PermissionSimulatorConfig, flagManager?: FeatureFlagManager): PermissionSimulator;
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/permissions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/permissions/index.ts"],"names":[],"mappings":"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"}

package/dist/_internal/platform/runtime/permissions/index.js

@@ -0,0 +1,85 @@
+/**
+ * Runtime permissions public API barrel.
+ *
+ * Exports the LayeredPolicyEvaluator, all types, rule evaluators, safety checks,
+ * and the createPermissionEvaluator() factory function.
+ *
+ * Feature flag: `permissions-policy-engine` must be enabled to use this module in production.
+ */
+export { LayeredPolicyEvaluator } from '@pellux/goodvibes-sdk/platform/runtime/permissions/evaluator';
+export { DecisionLog } from '@pellux/goodvibes-sdk/platform/runtime/permissions/decision-log';
+export { runSafetyChecks } from '@pellux/goodvibes-sdk/platform/runtime/permissions/safety-checks';
+export { PermissionSimulator, SimulationEnforcementError } from '@pellux/goodvibes-sdk/platform/runtime/permissions/simulation';
+export { buildDefaultPolicySimulationScenarios, runPolicySimulationScenarios } from '@pellux/goodvibes-sdk/platform/runtime/permissions/simulation-scenarios';
+export { lintPolicyConfig } from '@pellux/goodvibes-sdk/platform/runtime/permissions/lint';
+export { buildPolicyPreflightReview } from './preflight.js';
+export { buildPermissionRuleSuggestions } from './rule-suggestions.js';
+// Policy signing
+export { signBundle, verifyBundle, canonicalise } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-signer';
+export { loadPolicyBundle, createUnsignedBundle, PolicySignatureError } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-loader';
+export { evaluatePrefixRule, evaluateArgShapeRule, evaluatePathScopeRule, evaluateNetworkScopeRule, evaluateModeConstraintRule, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/rules/index';
+// Divergence dashboard
+export { DivergenceDashboard, DivergenceGateError, } from '@pellux/goodvibes-sdk/platform/runtime/permissions/divergence-dashboard';
+// Policy-as-Code
+export { PolicyRegistry } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-registry';
+export { PolicyRuntimeState, } from './policy-runtime.js';
+// ── Factory ──────────────────────────────────────────────────────────────────────
+import { LayeredPolicyEvaluator } from '@pellux/goodvibes-sdk/platform/runtime/permissions/evaluator';
+import { PermissionSimulator } from '@pellux/goodvibes-sdk/platform/runtime/permissions/simulation';
+/**
+ * createPermissionEvaluator — Factory function for the runtime permission evaluator.
+ *
+ * Returns a LayeredPolicyEvaluator configured with the given options.
+ * Designed as the primary entry point for integrating the runtime permissions system.
+ *
+ * The returned evaluator exposes:
+ *   - `evaluate(toolName, args)` — perform a full layered evaluation
+ *   - `recordSessionOverride(...)` — cache a user prompt response
+ *   - `log` — DecisionLog for audit queries
+ *   - `getMode()` — inspect the active mode
+ *
+ * @example
+ * ```ts
+ * const perms = createPermissionEvaluator({ mode: 'default', rules: [] });
+ * const decision = perms.evaluate('write', { path: '/tmp/out.txt' });
+ * if (!decision.allowed) {
+ *   console.error('denied:', decision.reason);
+ * }
+ * ```
+ *
+ * @param config     — Optional configuration; all fields have safe defaults.
+ * @param provenance — Optional bundle provenance (GC-PERM-011).
+ */
+export function createPermissionEvaluator(config = {}, provenance) {
+    return new LayeredPolicyEvaluator(config, provenance);
+}
+/**
+ * createPermissionSimulator — Factory for `PermissionSimulator`.
+ *
+ * Creates a dual-evaluator simulation pipeline for the runtime permissions system that runs
+ * both the actual and simulated evaluators in parallel, tracking divergence.
+ *
+ * Requires the `permissions-simulation` feature flag to be enabled.
+ *
+ * @param actualConfig    — Config for the authoritative evaluator.
+ * @param simulatedConfig — Config for the candidate evaluator.
+ * @param simulationMode  — Controls enforcement and warning behaviour.
+ * @param config          — Optional tuning: record limit, divergence threshold.
+ *
+ * @example
+ * ```ts
+ * const simulator = createPermissionSimulator(
+ *   { mode: 'default', rules: currentRules },
+ *   { mode: 'default', rules: candidateRules },
+ *   'warn-on-divergence',
+ * );
+ * const result = simulator.evaluate('write', { path: '/tmp/out.txt' });
+ * const report = simulator.getDivergenceReport();
+ * ```
+ */
+export function createPermissionSimulator(actualConfig, simulatedConfig, simulationMode, config = {}, flagManager) {
+    if (flagManager && !flagManager.isEnabled('permissions-simulation')) {
+        throw new Error('Feature flag "permissions-simulation" is not enabled');
+    }
+    return new PermissionSimulator(actualConfig, simulatedConfig, simulationMode, config);
+}

package/dist/_internal/platform/runtime/permissions/policy-runtime.d.ts

@@ -0,0 +1,58 @@
+import { PolicyRegistry } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-registry';
+import { DivergencePanel } from '@pellux/goodvibes-sdk/platform/runtime/diagnostics/panels/divergence';
+import type { PolicyPanelSnapshot } from '../diagnostics/panels/policy.js';
+import type { DivergenceDashboard } from '@pellux/goodvibes-sdk/platform/runtime/permissions/divergence-dashboard';
+import type { PermissionCheckResult } from '@pellux/goodvibes-sdk/platform/permissions/types';
+import type { PolicySimulationSummary } from '@pellux/goodvibes-sdk/platform/runtime/permissions/simulation-scenarios';
+import type { PolicyPreflightReview } from './preflight.js';
+export interface PermissionAuditEntry {
+    readonly callId: string;
+    readonly tool: string;
+    readonly category: string;
+    readonly approved?: boolean;
+    readonly sourceLayer?: string;
+    readonly reasonCode?: string;
+    readonly riskLevel: string;
+    readonly classification: string;
+    readonly summary: string;
+    readonly reasons: readonly string[];
+    readonly target?: string;
+    readonly host?: string;
+    readonly requestedAt: number;
+    readonly decidedAt?: number;
+    readonly persisted?: boolean;
+}
+export declare class PolicyRuntimeState {
+    private readonly _registry;
+    private _dashboard;
+    private _divergencePanel;
+    private readonly _recentPermissionAudit;
+    private _lastSimulationSummary;
+    private _lastPreflightReview;
+    private readonly _subscribers;
+    constructor(registry?: PolicyRegistry);
+    getRegistry(): PolicyRegistry;
+    getDashboard(): DivergenceDashboard | null;
+    getDivergencePanel(): DivergencePanel | null;
+    setDashboard(dashboard: DivergenceDashboard | null): void;
+    recordTrendEntry(): void;
+    getSnapshot(): PolicyPanelSnapshot;
+    recordSimulationSummary(summary: PolicySimulationSummary): void;
+    recordPreflightReview(review: PolicyPreflightReview): void;
+    recordPermissionRequest(params: {
+        callId: string;
+        tool: string;
+        category: string;
+        analysis: PermissionCheckResult['analysis'];
+    }): void;
+    recordPermissionDecision(params: {
+        callId: string;
+        tool: string;
+        category: string;
+        result: PermissionCheckResult;
+    }): void;
+    subscribe(callback: () => void): () => void;
+    notify(): void;
+    private _upsertPermissionAudit;
+}
+//# sourceMappingURL=policy-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy-runtime.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/permissions/policy-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oEAAoE,CAAC;AACpG,OAAO,EAAE,eAAe,EAAE,MAAM,sEAAsE,CAAC;AACvG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yEAAyE,CAAC;AACnH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kDAAkD,CAAC;AAE9F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yEAAyE,CAAC;AACvH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAI5D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,gBAAgB,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA8B;IACrE,OAAO,CAAC,sBAAsB,CAAwC;IACtE,OAAO,CAAC,oBAAoB,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;gBAEnC,QAAQ,GAAE,cAAqC;IAI3D,WAAW,IAAI,cAAc;IAI7B,YAAY,IAAI,mBAAmB,GAAG,IAAI;IAI1C,kBAAkB,IAAI,eAAe,GAAG,IAAI;IAI5C,YAAY,CAAC,SAAS,EAAE,mBAAmB,GAAG,IAAI,GAAG,IAAI;IAOzD,gBAAgB,IAAI,IAAI;IAKxB,WAAW,IAAI,mBAAmB;IAkBlC,uBAAuB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI;IAK/D,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI;IAK1D,uBAAuB,CAAC,MAAM,EAAE;QACrC,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;KAC7C,GAAG,IAAI;IAgBD,wBAAwB,CAAC,MAAM,EAAE;QACtC,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,qBAAqB,CAAC;KAC/B,GAAG,IAAI;IAqBD,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,MAAM,IAAI,IAAI;IAUrB,OAAO,CAAC,sBAAsB;CAe/B"}