create-principles-disciple 1.0.0 → 1.74.0

package/plugin/dist/core/shadow-observation-registry.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Shadow Observation Registry — Runtime Shadow Evidence for Promotion Gate
+ * =======================================================================
+ *
+ * PURPOSE: Track real-world runtime evidence from shadow deployments to inform
+ * promotion gate decisions. Real evidence replaces eval verdict proxies.
+ *
+ * ARCHITECTURE:
+ *   - Shadow observations are recorded by the routing system when a checkpoint
+ *     is routed in shadow mode
+ *   - Each observation captures whether the routing decision was accepted,
+ *     rejected, or escalated by the runtime
+ *   - The promotion gate queries this registry to get real arbiter/executability
+ *     reject rates instead of using eval verdict as a proxy
+ *
+ * SHADOW OBSERVATION LIFECYCLE:
+ *   1. Routing system routes task to shadow checkpoint (shadow_ready state)
+ *   2. Observation recorded: { checkpointId, taskFingerprint, routedAt }
+ *   3. Task completes or times out
+ *   4. Observation updated: { completedAt, accepted/rejected/escalated, failureSignals }
+ *   5. After sufficient observations, promotion gate can query real reject rates
+ *
+ * DATA RETENTION:
+ *   - Observations are kept for 7 days by default
+ *   - Can be queried by checkpointId, time window, or outcome
+ *
+ * DESIGN CONSTRAINTS:
+ *   - Fail-closed: if no shadow evidence exists, fall back to eval proxies
+ *   - Shadow evidence must be statistically significant (min sample size)
+ *   - Observations are retained until cleanup removes expired entries
+ */
+/**
+ * Default observation retention period in milliseconds.
+ * 7 days
+ */
+export declare const DEFAULT_RETENTION_MS: number;
+/**
+ * Minimum number of shadow observations required before trusting the evidence.
+ * Below this, we fall back to eval proxies.
+ */
+export declare const MIN_OBSERVATIONS_FOR_TRUST = 5;
+/**
+ * Time window for computing recent reject rates.
+ * Only observations within this window are considered.
+ * 24 hours
+ */
+export declare const RECENT_WINDOW_MS: number;
+/**
+ * Outcome of a shadow routing observation.
+ */
+export type ShadowOutcome = 'accepted' | 'rejected' | 'escalated';
+/**
+ * Runtime failure signals captured during shadow routing.
+ */
+export interface RuntimeFailureSignals {
+    /** Whether the task timed out */
+    timedOut: boolean;
+    /** Whether an exception was thrown */
+    threwException: boolean;
+    /** Whether the output was empty or invalid */
+    invalidOutput: boolean;
+    /** Whether the worker profile rejected the routing */
+    profileRejected: boolean;
+    /** Additional failure signals (free-form for extensibility) */
+    extra: Record<string, boolean>;
+}
+/**
+ * A shadow observation — records a single shadow routing event.
+ */
+export interface ShadowObservation {
+    /** Unique identifier for this observation */
+    observationId: string;
+    /** Checkpoint being routed to in shadow mode */
+    checkpointId: string;
+    /** Worker profile this observation is for */
+    workerProfile: string;
+    /** Task fingerprint (hash of task input for deduplication) */
+    taskFingerprint: string;
+    /** ISO-8601 timestamp when routing decision was made */
+    routedAt: string;
+    /** ISO-8601 timestamp when task completed (null if still pending) */
+    completedAt?: string;
+    /** Outcome of the shadow routing */
+    outcome?: ShadowOutcome;
+    /** Runtime failure signals (null if still pending) */
+    failureSignals?: RuntimeFailureSignals;
+    /** Whether this observation was used in a promotion gate evaluation */
+    usedInGate?: boolean;
+}
+/**
+ * Computed statistics from shadow observations.
+ */
+export interface ShadowStats {
+    /** Checkpoint ID these stats are for */
+    checkpointId: string;
+    /** Total observations in the time window */
+    totalCount: number;
+    /** Count by outcome */
+    acceptedCount: number;
+    rejectedCount: number;
+    escalatedCount: number;
+    /** Computed rates */
+    rejectRate: number;
+    escalationRate: number;
+    acceptanceRate: number;
+    /** Failure signal frequencies */
+    timedOutRate: number;
+    threwExceptionRate: number;
+    invalidOutputRate: number;
+    profileRejectedRate: number;
+    /** Whether this has enough data to trust */
+    isStatisticallySignificant: boolean;
+    /** Time window used for computation */
+    windowStart: string;
+    windowEnd: string;
+}
+/**
+ * The complete shadow registry.
+ */
+export interface ShadowRegistry {
+    observations: ShadowObservation[];
+    /** Schema version for migration support */
+    version: number;
+}
+/**
+ * Parameters for recording a shadow routing observation.
+ */
+export interface RecordObservationParams {
+    /** Checkpoint being routed to in shadow mode */
+    checkpointId: string;
+    /** Worker profile */
+    workerProfile: string;
+    /** Task fingerprint for deduplication */
+    taskFingerprint: string;
+    /** ISO-8601 timestamp when routing decision was made */
+    routedAt?: string;
+}
+/**
+ * Record a new shadow observation (when task is routed to shadow checkpoint).
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Observation parameters
+ * @returns The created ShadowObservation
+ */
+export declare function recordShadowRouting(stateDir: string, params: RecordObservationParams): ShadowObservation;
+/**
+ * Parameters for completing a shadow observation.
+ */
+export interface CompleteObservationParams {
+    /** Observation ID to complete */
+    observationId: string;
+    /** Outcome of the shadow routing */
+    outcome: ShadowOutcome;
+    /** Runtime failure signals */
+    failureSignals?: RuntimeFailureSignals;
+}
+/**
+ * Complete a pending shadow observation (when task finishes).
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Completion parameters
+ * @returns The updated ShadowObservation, or null if not found
+ */
+export declare function completeShadowObservation(stateDir: string, params: CompleteObservationParams): ShadowObservation | null;
+/**
+ * Complete a shadow observation by task fingerprint (alternative lookup).
+ *
+ * @param stateDir - Workspace state directory
+ * @param taskFingerprint - Task fingerprint to look up
+ * @param outcome - Outcome of the shadow routing
+ * @param failureSignals - Runtime failure signals
+ * @returns The updated ShadowObservation, or null if not found
+ */
+export declare function completeShadowObservationByTask(stateDir: string, taskFingerprint: string, outcome: ShadowOutcome, failureSignals?: RuntimeFailureSignals): ShadowObservation | null;
+/**
+ * Parameters for computing shadow statistics.
+ */
+export interface ComputeShadowStatsParams {
+    /** Checkpoint ID to compute stats for */
+    checkpointId: string;
+    /** Time window in milliseconds (default: RECENT_WINDOW_MS) */
+    windowMs?: number;
+    /** Retention period in milliseconds (default: DEFAULT_RETENTION_MS) */
+    retentionMs?: number;
+}
+/**
+ * Compute shadow routing statistics for a checkpoint.
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Computation parameters
+ * @returns ShadowStats with computed rates, or null if not enough data
+ */
+export declare function computeShadowStats(stateDir: string, params: ComputeShadowStatsParams): ShadowStats | null;
+/**
+ * Query shadow observations for a checkpoint.
+ *
+ * @param stateDir - Workspace state directory
+ * @param checkpointId - Checkpoint ID to query
+ * @param limit - Maximum observations to return (default: 100)
+ * @returns Array of shadow observations
+ */
+export declare function queryShadowObservations(stateDir: string, checkpointId: string, limit?: number): ShadowObservation[];
+/**
+ * Mark observations as used in a promotion gate evaluation.
+ *
+ * @param stateDir - Workspace state directory
+ * @param observationIds - IDs of observations to mark
+ */
+export declare function markObservationsUsedInGate(stateDir: string, observationIds: string[]): void;
+/**
+ * Clean up expired observations (older than retention period).
+ *
+ * @param stateDir - Workspace state directory
+ * @param retentionMs - Retention period in milliseconds (default: DEFAULT_RETENTION_MS)
+ * @returns Number of observations removed
+ */
+export declare function cleanupExpiredObservations(stateDir: string, retentionMs?: number): number;

package/plugin/dist/core/shadow-observation-registry.js

@@ -0,0 +1,280 @@
+/**
+ * Shadow Observation Registry — Runtime Shadow Evidence for Promotion Gate
+ * =======================================================================
+ *
+ * PURPOSE: Track real-world runtime evidence from shadow deployments to inform
+ * promotion gate decisions. Real evidence replaces eval verdict proxies.
+ *
+ * ARCHITECTURE:
+ *   - Shadow observations are recorded by the routing system when a checkpoint
+ *     is routed in shadow mode
+ *   - Each observation captures whether the routing decision was accepted,
+ *     rejected, or escalated by the runtime
+ *   - The promotion gate queries this registry to get real arbiter/executability
+ *     reject rates instead of using eval verdict as a proxy
+ *
+ * SHADOW OBSERVATION LIFECYCLE:
+ *   1. Routing system routes task to shadow checkpoint (shadow_ready state)
+ *   2. Observation recorded: { checkpointId, taskFingerprint, routedAt }
+ *   3. Task completes or times out
+ *   4. Observation updated: { completedAt, accepted/rejected/escalated, failureSignals }
+ *   5. After sufficient observations, promotion gate can query real reject rates
+ *
+ * DATA RETENTION:
+ *   - Observations are kept for 7 days by default
+ *   - Can be queried by checkpointId, time window, or outcome
+ *
+ * DESIGN CONSTRAINTS:
+ *   - Fail-closed: if no shadow evidence exists, fall back to eval proxies
+ *   - Shadow evidence must be statistically significant (min sample size)
+ *   - Observations are retained until cleanup removes expired entries
+ */
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { withLock } from '../utils/file-lock.js';
+import { JsonFileStore } from './file-store.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Registry file for shadow observations.
+ */
+const SHADOW_REGISTRY_FILE = 'shadow-registry.json';
+/**
+ * Default observation retention period in milliseconds.
+ * 7 days
+ */
+export const DEFAULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Minimum number of shadow observations required before trusting the evidence.
+ * Below this, we fall back to eval proxies.
+ */
+export const MIN_OBSERVATIONS_FOR_TRUST = 5;
+/**
+ * Time window for computing recent reject rates.
+ * Only observations within this window are considered.
+ * 24 hours
+ */
+export const RECENT_WINDOW_MS = 24 * 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Registry Path & Store
+// ---------------------------------------------------------------------------
+let _store = new Map();
+function getRegistryPath(stateDir) {
+    return path.join(stateDir, SHADOW_REGISTRY_FILE);
+}
+function getStore(stateDir) {
+    let store = _store.get(stateDir);
+    if (!store) {
+        const filePath = path.join(stateDir, SHADOW_REGISTRY_FILE);
+        store = new JsonFileStore(filePath, () => ({ observations: [], version: 1 }));
+        _store.set(stateDir, store);
+    }
+    return store;
+}
+// ---------------------------------------------------------------------------
+// File Operations
+// ---------------------------------------------------------------------------
+/**
+ * Execute a read-modify-write under an exclusive file lock.
+ */
+function withShadowRegistryLock(stateDir, fn) {
+    const store = getStore(stateDir);
+    const filePath = getRegistryPath(stateDir);
+    // Re-create lock behavior using the store's mutate under a simple fs-based lock
+    return withLock(filePath, () => {
+        const registry = store.load();
+        const result = fn(registry);
+        store.save(registry);
+        return result;
+    });
+}
+/**
+ * Record a new shadow observation (when task is routed to shadow checkpoint).
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Observation parameters
+ * @returns The created ShadowObservation
+ */
+export function recordShadowRouting(stateDir, params) {
+    const observation = {
+        observationId: crypto.randomUUID(),
+        checkpointId: params.checkpointId,
+        workerProfile: params.workerProfile,
+        taskFingerprint: params.taskFingerprint,
+        routedAt: params.routedAt ?? new Date().toISOString(),
+    };
+    return withShadowRegistryLock(stateDir, (registry) => {
+        registry.observations.push(observation);
+        return observation;
+    });
+}
+/**
+ * Complete a pending shadow observation (when task finishes).
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Completion parameters
+ * @returns The updated ShadowObservation, or null if not found
+ */
+export function completeShadowObservation(stateDir, params) {
+    return withShadowRegistryLock(stateDir, (registry) => {
+        const idx = registry.observations.findIndex((o) => o.observationId === params.observationId);
+        if (idx === -1) {
+            return null;
+        }
+        const observation = registry.observations[idx];
+        observation.completedAt = new Date().toISOString();
+        observation.outcome = params.outcome;
+        observation.failureSignals = params.failureSignals ?? {
+            timedOut: false,
+            threwException: false,
+            invalidOutput: false,
+            profileRejected: false,
+            extra: {},
+        };
+        return observation;
+    });
+}
+/**
+ * Complete a shadow observation by task fingerprint (alternative lookup).
+ *
+ * @param stateDir - Workspace state directory
+ * @param taskFingerprint - Task fingerprint to look up
+ * @param outcome - Outcome of the shadow routing
+ * @param failureSignals - Runtime failure signals
+ * @returns The updated ShadowObservation, or null if not found
+ */
+export function completeShadowObservationByTask(stateDir, taskFingerprint, outcome, failureSignals) {
+    return withShadowRegistryLock(stateDir, (registry) => {
+        // Find the oldest pending observation for this task
+        const pendingObs = registry.observations
+            .filter((o) => o.taskFingerprint === taskFingerprint && !o.completedAt)
+            .sort((a, b) => a.routedAt.localeCompare(b.routedAt));
+        if (pendingObs.length === 0) {
+            return null;
+        }
+        const [observation] = pendingObs;
+        observation.completedAt = new Date().toISOString();
+        observation.outcome = outcome;
+        observation.failureSignals = failureSignals ?? {
+            timedOut: false,
+            threwException: false,
+            invalidOutput: false,
+            profileRejected: false,
+            extra: {},
+        };
+        return observation;
+    });
+}
+/**
+ * Compute shadow routing statistics for a checkpoint.
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Computation parameters
+ * @returns ShadowStats with computed rates, or null if not enough data
+ */
+export function computeShadowStats(stateDir, params) {
+    const { checkpointId, windowMs = RECENT_WINDOW_MS, retentionMs = DEFAULT_RETENTION_MS, } = params;
+    const now = Date.now();
+    const windowStart = new Date(now - windowMs).toISOString();
+    const windowEnd = new Date(now).toISOString();
+    return withShadowRegistryLock(stateDir, (registry) => {
+        // Filter observations:
+        // 1. For this checkpoint
+        // 2. Within the time window
+        // 3. Not expired (within retention period)
+        const cutoff = new Date(now - retentionMs).toISOString();
+        const relevantObs = registry.observations.filter((o) => {
+            if (o.checkpointId !== checkpointId)
+                return false;
+            if (o.routedAt < cutoff)
+                return false; // expired
+            if (o.routedAt < windowStart)
+                return false; // outside window
+            if (!o.completedAt)
+                return false; // still pending
+            return true;
+        });
+        const totalCount = relevantObs.length;
+        // Not enough data - fail closed (return null to use eval proxies)
+        if (totalCount < MIN_OBSERVATIONS_FOR_TRUST) {
+            return null;
+        }
+        const acceptedCount = relevantObs.filter((o) => o.outcome === 'accepted').length;
+        const rejectedCount = relevantObs.filter((o) => o.outcome === 'rejected').length;
+        const escalatedCount = relevantObs.filter((o) => o.outcome === 'escalated').length;
+        // Failure signal counts
+        const withTimedOut = relevantObs.filter((o) => o.failureSignals?.timedOut).length;
+        const withThrewException = relevantObs.filter((o) => o.failureSignals?.threwException).length;
+        const withInvalidOutput = relevantObs.filter((o) => o.failureSignals?.invalidOutput).length;
+        const withProfileRejected = relevantObs.filter((o) => o.failureSignals?.profileRejected).length;
+        const rejectRate = totalCount > 0 ? rejectedCount / totalCount : 0;
+        const escalationRate = totalCount > 0 ? escalatedCount / totalCount : 0;
+        const acceptanceRate = totalCount > 0 ? acceptedCount / totalCount : 0;
+        return {
+            checkpointId,
+            totalCount,
+            acceptedCount,
+            rejectedCount,
+            escalatedCount,
+            rejectRate: Math.round(rejectRate * 1000) / 1000,
+            escalationRate: Math.round(escalationRate * 1000) / 1000,
+            acceptanceRate: Math.round(acceptanceRate * 1000) / 1000,
+            timedOutRate: Math.round((withTimedOut / totalCount) * 1000) / 1000,
+            threwExceptionRate: Math.round((withThrewException / totalCount) * 1000) / 1000,
+            invalidOutputRate: Math.round((withInvalidOutput / totalCount) * 1000) / 1000,
+            profileRejectedRate: Math.round((withProfileRejected / totalCount) * 1000) / 1000,
+            isStatisticallySignificant: totalCount >= MIN_OBSERVATIONS_FOR_TRUST,
+            windowStart,
+            windowEnd,
+        };
+    });
+}
+/**
+ * Query shadow observations for a checkpoint.
+ *
+ * @param stateDir - Workspace state directory
+ * @param checkpointId - Checkpoint ID to query
+ * @param limit - Maximum observations to return (default: 100)
+ * @returns Array of shadow observations
+ */
+export function queryShadowObservations(stateDir, checkpointId, limit = 100) {
+    return withShadowRegistryLock(stateDir, (registry) => {
+        return registry.observations
+            .filter((o) => o.checkpointId === checkpointId)
+            .sort((a, b) => b.routedAt.localeCompare(a.routedAt)) // newest first
+            .slice(0, limit);
+    });
+}
+/**
+ * Mark observations as used in a promotion gate evaluation.
+ *
+ * @param stateDir - Workspace state directory
+ * @param observationIds - IDs of observations to mark
+ */
+export function markObservationsUsedInGate(stateDir, observationIds) {
+    withShadowRegistryLock(stateDir, (registry) => {
+        for (const obs of registry.observations) {
+            if (observationIds.includes(obs.observationId)) {
+                obs.usedInGate = true;
+            }
+        }
+    });
+}
+/**
+ * Clean up expired observations (older than retention period).
+ *
+ * @param stateDir - Workspace state directory
+ * @param retentionMs - Retention period in milliseconds (default: DEFAULT_RETENTION_MS)
+ * @returns Number of observations removed
+ */
+export function cleanupExpiredObservations(stateDir, retentionMs = DEFAULT_RETENTION_MS) {
+    const cutoff = new Date(Date.now() - retentionMs).toISOString();
+    let removed = 0;
+    withShadowRegistryLock(stateDir, (registry) => {
+        const before = registry.observations.length;
+        registry.observations = registry.observations.filter((o) => o.routedAt >= cutoff);
+        removed = before - registry.observations.length;
+    });
+    return removed;
+}

package/plugin/dist/core/storage-adapter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * StorageAdapter interface for the Evolution SDK.
+ *
+ * This interface decouples the evolution engine from specific persistence
+ * implementations (file system, SQLite, remote API). All higher-level
+ * modules that need to read or mutate the principle ledger should depend
+ * on this interface rather than importing principle-tree-ledger directly.
+ *
+ * The interface uses HybridLedgerStore from principle-tree-ledger as the
+ * canonical store shape, but future adapters can map alternative backends
+ * to this shape.
+ */
+import type { HybridLedgerStore } from './principle-tree-ledger.js';
+/**
+ * Abstract storage adapter for the principle ledger.
+ *
+ * Implementations must guarantee:
+ * - Atomic writes (no partial/corrupted state on crash)
+ * - Thread-safe concurrent access (locking or equivalent)
+ * - Consistent read-after-write visibility
+ *
+ * The `mutateLedger` method is the preferred way to perform read-modify-write
+ * cycles. It encapsulates locking so callers never need to manage it.
+ */
+export interface StorageAdapter {
+    /**
+     * Load the current ledger state from persistence.
+     *
+     * If no persisted state exists (first run), returns an empty store.
+     */
+    loadLedger(): Promise<HybridLedgerStore>;
+    /**
+     * Persist the full ledger state.
+     *
+     * Must be atomic — partial writes must never be visible to readers.
+     */
+    saveLedger(store: HybridLedgerStore): Promise<void>;
+    /**
+     * Perform a read-modify-write cycle with automatic locking.
+     *
+     * The `mutate` function receives the current store and may return a
+     * value synchronously or via Promise. The store is persisted after
+     * the mutate function resolves, regardless of its return value.
+     *
+     * If two concurrent `mutateLedger` calls overlap, one must wait for
+     * the other to complete (pessimistic locking) or retry on conflict
+     * (optimistic locking). The choice is left to the implementation.
+     *
+     * @example
+     * ```ts
+     * const count = await adapter.mutateLedger((store) => {
+     *   store.tree.principles['p-1'] = newPrinciple;
+     *   return Object.keys(store.tree.principles).length;
+     * });
+     * ```
+     */
+    mutateLedger<T>(mutate: (store: HybridLedgerStore) => T | Promise<T>): Promise<T>;
+}

package/plugin/dist/core/storage-adapter.js

@@ -0,0 +1 @@
+export {};

package/plugin/dist/core/system-logger.d.ts

@@ -0,0 +1,8 @@
+export declare const SystemLogger: {
+    log(workspaceDir: string | undefined, eventType: string, message: string): void;
+    /**
+     * Force refresh of the cached log file path.
+     * Call this at midnight or when the date changes to ensure proper rotation.
+     */
+    refreshCache(): void;
+};

package/plugin/dist/core/system-logger.js

@@ -0,0 +1,113 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolvePdPath, PD_FILES } from './paths.js';
+/**
+ * System Logger for Principles Disciple
+ *
+ * Writes critical evolutionary events to date-stamped log files:
+ *   memory/logs/SYSTEM_YYYY-MM-DD.log
+ *
+ * Uses asynchronous writing to avoid blocking the Node.js event loop.
+ * Automatically rotates to a new file at midnight.
+ * Old log files are automatically cleaned up based on retention policy.
+ */
+// Cache for current log file path, invalidated when date changes
+let cachedLogFile;
+let cachedLogDate;
+/**
+ * Log retention: delete SYSTEM logs older than this many days.
+ * Set to 0 to disable cleanup.
+ */
+const LOG_RETENTION_DAYS = 7;
+/**
+ * Get the system log file path for a given date.
+ * Format: memory/logs/SYSTEM_YYYY-MM-DD.log
+ */
+function getSystemLogPath(workspaceDir, date) {
+    const dateStr = date.toISOString().slice(0, 10); // YYYY-MM-DD
+    const logDir = path.dirname(resolvePdPath(workspaceDir, 'SYSTEM_LOG'));
+    const baseName = path.basename(PD_FILES.SYSTEM_LOG, '.log');
+    return path.join(logDir, `${baseName}_${dateStr}.log`);
+}
+/**
+ * Get today's date string (YYYY-MM-DD).
+ */
+function getTodayStr() {
+    return new Date().toISOString().slice(0, 10);
+}
+/**
+ * Clean up old SYSTEM log files, keeping only LOG_RETENTION_DAYS.
+ * Called automatically on first log write of each day.
+ */
+function cleanupOldLogs(workspaceDir) {
+    if (LOG_RETENTION_DAYS <= 0)
+        return;
+    try {
+        const logDir = path.dirname(resolvePdPath(workspaceDir, 'SYSTEM_LOG'));
+        const baseName = path.basename(PD_FILES.SYSTEM_LOG, '.log');
+        const prefix = `${baseName}_`;
+        if (!fs.existsSync(logDir))
+            return;
+        const cutoffMs = Date.now() - LOG_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+        const files = fs.readdirSync(logDir);
+        for (const file of files) {
+            if (!file.startsWith(prefix) || !file.endsWith('.log'))
+                continue;
+            const filePath = path.join(logDir, file);
+            const stat = fs.statSync(filePath);
+            if (stat.mtimeMs < cutoffMs) {
+                fs.unlinkSync(filePath);
+            }
+        }
+    }
+    catch {
+        // Silently fail cleanup - don't crash logging for cleanup failures
+    }
+}
+// Track if cleanup has run today
+let lastCleanupDate;
+export const SystemLogger = {
+    log(workspaceDir, eventType, message) {
+        if (!workspaceDir)
+            return;
+        try {
+            const today = getTodayStr();
+            // Check if date changed - invalidate cache and run cleanup
+            if (cachedLogDate !== today) {
+                cachedLogDate = today;
+                cachedLogFile = undefined;
+                // Run cleanup once per day when date changes
+                if (lastCleanupDate !== today) {
+                    lastCleanupDate = today;
+                    cleanupOldLogs(workspaceDir);
+                }
+            }
+            // Get or create log file path
+            if (!cachedLogFile) {
+                cachedLogFile = getSystemLogPath(workspaceDir, new Date());
+                const logDir = path.dirname(cachedLogFile);
+                if (!fs.existsSync(logDir)) {
+                    fs.mkdirSync(logDir, { recursive: true });
+                }
+            }
+            const timestamp = new Date().toISOString();
+            // Format: [YYYY-MM-DDTHH:mm:ss.sssZ] [EVENT_TYPE] Message
+            const logEntry = `[${timestamp}] [${eventType.padEnd(15)}] ${message}\n`;
+            // Use fire-and-forget async append to prevent blocking
+            fs.appendFile(cachedLogFile, logEntry, 'utf8', (_err) => {
+                // Silently drop errors (e.g. disk full) to not crash the gateway
+            });
+        }
+        catch (e) { // eslint-disable-line @typescript-eslint/no-unused-vars -- Reason: intentionally unused - silently fail if we can't setup the log
+            // Silently fail if we can't setup the log
+        }
+    },
+    /**
+     * Force refresh of the cached log file path.
+     * Call this at midnight or when the date changes to ensure proper rotation.
+     */
+    refreshCache() {
+        cachedLogDate = undefined;
+        cachedLogFile = undefined;
+    }
+};