@trillboards/edge-core 0.2.1 → 0.2.3

package/dist/JsonFileStore.d.ts

@@ -0,0 +1,33 @@
+/**
+ * JsonFileStore — Zero-dependency signal store using Node.js fs.
+ *
+ * Storage: configurable path (default: ~/.trillboards/signal_buffer.json)
+ * Persistence: debounced writes (every 5s max) + sync write on close()
+ * Crash safety: write to .tmp then fs.renameSync (atomic on all platforms)
+ * Priority: FACE_BACKED > PERSON_BACKED > SPEECH_ONLY > PROXY_ONLY > EMPTY
+ */
+import type { SignalStore, StoredSignal, SignalStoreStats } from './SignalStore';
+export declare class JsonFileStore implements SignalStore {
+    private signals;
+    private nextId;
+    private readonly filePath;
+    private dirty;
+    private flushTimer;
+    private static readonly FLUSH_INTERVAL_MS;
+    constructor(filePath?: string);
+    private loadFromDisk;
+    private schedulePersist;
+    private persistSync;
+    private extractEvidenceGrade;
+    insert(payload: string, timestamp: number): void;
+    getOldest(limit: number): StoredSignal[];
+    deleteById(id: number): void;
+    deleteOlderThan(cutoffMs: number): number;
+    deleteOldestN(n: number): void;
+    deleteExceedingRetries(maxRetries: number): void;
+    incrementRetry(id: number): void;
+    count(): number;
+    stats(): SignalStoreStats;
+    close(): void;
+}
+//# sourceMappingURL=JsonFileStore.d.ts.map

package/dist/JsonFileStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonFileStore.d.ts","sourceRoot":"","sources":["../src/JsonFileStore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAejF,qBAAa,aAAc,YAAW,WAAW;IAC/C,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;gBAErC,QAAQ,CAAC,EAAE,MAAM;IAiB7B,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,WAAW;IAgBnB,OAAO,CAAC,oBAAoB;IAW5B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAYhD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE;IAWxC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQ5B,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAQzC,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ9B,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAMhD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQhC,KAAK,IAAI,MAAM;IAIf,KAAK,IAAI,gBAAgB;IAmBzB,KAAK,IAAI,IAAI;CASd"}

package/dist/JsonFileStore.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * JsonFileStore — Zero-dependency signal store using Node.js fs.
+ *
+ * Storage: configurable path (default: ~/.trillboards/signal_buffer.json)
+ * Persistence: debounced writes (every 5s max) + sync write on close()
+ * Crash safety: write to .tmp then fs.renameSync (atomic on all platforms)
+ * Priority: FACE_BACKED > PERSON_BACKED > SPEECH_ONLY > PROXY_ONLY > EMPTY
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonFileStore = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const EVIDENCE_GRADE_PRIORITY = {
+    FACE_BACKED: 1,
+    PERSON_BACKED: 2,
+    SPEECH_ONLY: 3,
+    PROXY_ONLY: 4,
+    EMPTY: 5,
+};
+class JsonFileStore {
+    constructor(filePath) {
+        this.signals = [];
+        this.nextId = 1;
+        this.dirty = false;
+        this.flushTimer = null;
+        this.filePath =
+            filePath ||
+                path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.trillboards', 'signal_buffer.json');
+        const dir = path.dirname(this.filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        this.loadFromDisk();
+    }
+    loadFromDisk() {
+        try {
+            if (fs.existsSync(this.filePath)) {
+                const raw = fs.readFileSync(this.filePath, 'utf-8');
+                const data = JSON.parse(raw);
+                if (Array.isArray(data.signals)) {
+                    this.signals = data.signals;
+                    this.nextId = typeof data.nextId === 'number' ? data.nextId : 1;
+                    // Ensure nextId is higher than any existing signal id
+                    for (const s of this.signals) {
+                        if (s.id >= this.nextId) {
+                            this.nextId = s.id + 1;
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Corrupt file — start fresh, log warning
+            console.warn(`[JsonFileStore] Corrupt signal buffer at ${this.filePath}, starting fresh`);
+            this.signals = [];
+            this.nextId = 1;
+        }
+    }
+    schedulePersist() {
+        this.dirty = true;
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            if (this.dirty) {
+                this.persistSync();
+            }
+        }, JsonFileStore.FLUSH_INTERVAL_MS);
+    }
+    persistSync() {
+        this.dirty = false;
+        const data = {
+            nextId: this.nextId,
+            signals: this.signals,
+        };
+        const json = JSON.stringify(data);
+        const tmpPath = this.filePath + '.tmp';
+        try {
+            fs.writeFileSync(tmpPath, json, 'utf-8');
+            fs.renameSync(tmpPath, this.filePath);
+        }
+        catch (err) {
+            console.error(`[JsonFileStore] Failed to persist signal buffer:`, err);
+        }
+    }
+    extractEvidenceGrade(payload) {
+        try {
+            const parsed = JSON.parse(payload);
+            return typeof parsed.evidenceGrade === 'string'
+                ? parsed.evidenceGrade
+                : 'EMPTY';
+        }
+        catch {
+            return 'EMPTY';
+        }
+    }
+    insert(payload, timestamp) {
+        const signal = {
+            id: this.nextId++,
+            payload,
+            timestamp,
+            retryCount: 0,
+            evidenceGrade: this.extractEvidenceGrade(payload),
+        };
+        this.signals.push(signal);
+        this.schedulePersist();
+    }
+    getOldest(limit) {
+        // Sort by priority (evidence grade), then by timestamp (oldest first)
+        const sorted = [...this.signals].sort((a, b) => {
+            const prioA = EVIDENCE_GRADE_PRIORITY[a.evidenceGrade || 'EMPTY'] || 5;
+            const prioB = EVIDENCE_GRADE_PRIORITY[b.evidenceGrade || 'EMPTY'] || 5;
+            if (prioA !== prioB)
+                return prioA - prioB;
+            return a.timestamp - b.timestamp;
+        });
+        return sorted.slice(0, limit);
+    }
+    deleteById(id) {
+        const idx = this.signals.findIndex((s) => s.id === id);
+        if (idx !== -1) {
+            this.signals.splice(idx, 1);
+            this.schedulePersist();
+        }
+    }
+    deleteOlderThan(cutoffMs) {
+        const before = this.signals.length;
+        this.signals = this.signals.filter((s) => s.timestamp >= cutoffMs);
+        const deleted = before - this.signals.length;
+        if (deleted > 0)
+            this.schedulePersist();
+        return deleted;
+    }
+    deleteOldestN(n) {
+        if (n <= 0 || this.signals.length === 0)
+            return;
+        // Sort by timestamp ascending, remove the oldest N
+        this.signals.sort((a, b) => a.timestamp - b.timestamp);
+        this.signals.splice(0, n);
+        this.schedulePersist();
+    }
+    deleteExceedingRetries(maxRetries) {
+        const before = this.signals.length;
+        this.signals = this.signals.filter((s) => s.retryCount < maxRetries);
+        if (this.signals.length < before)
+            this.schedulePersist();
+    }
+    incrementRetry(id) {
+        const signal = this.signals.find((s) => s.id === id);
+        if (signal) {
+            signal.retryCount++;
+            this.schedulePersist();
+        }
+    }
+    count() {
+        return this.signals.length;
+    }
+    stats() {
+        const byGrade = {};
+        let oldest = null;
+        for (const s of this.signals) {
+            const grade = s.evidenceGrade || 'EMPTY';
+            byGrade[grade] = (byGrade[grade] || 0) + 1;
+            if (oldest === null || s.timestamp < oldest) {
+                oldest = s.timestamp;
+            }
+        }
+        return {
+            total: this.signals.length,
+            byEvidenceGrade: byGrade,
+            oldestTimestampMs: oldest,
+        };
+    }
+    close() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.dirty) {
+            this.persistSync();
+        }
+    }
+}
+exports.JsonFileStore = JsonFileStore;
+JsonFileStore.FLUSH_INTERVAL_MS = 5000;
+//# sourceMappingURL=JsonFileStore.js.map

package/dist/JsonFileStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonFileStore.js","sourceRoot":"","sources":["../src/JsonFileStore.ts"],"names":[],"mappings":"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"}

package/dist/MemoryAttenuationManager.d.ts

@@ -0,0 +1,164 @@
+/**
+ * MemoryAttenuationManager — Monitors V8 heap and OS memory, applies tiered
+ * shedding to keep edge devices stable under pressure.
+ *
+ * Port of CTV agent's MemoryAttenuationManager.kt, adapted for the V8 heap
+ * model. Uses `process.memoryUsage()` for heap metrics and `os.freemem()` /
+ * `os.totalmem()` for system-level awareness.
+ *
+ * Tiers (based on heap usage percentage = heapUsed / heapTotal):
+ *   GREEN    — Normal operation, all systems active
+ *   YELLOW   — >70% heap — disable cloud inference
+ *   ORANGE   — >80% heap — disable federated learning, reduce FPS
+ *   RED      — >90% heap — shed lowest-priority models (one per cycle)
+ *   CRITICAL — >95% heap — camera-only emergency mode, force GC
+ *
+ * Hysteresis prevents oscillation: a tier is only restored when usage drops
+ * a configurable percentage (default 15%) below the threshold that triggered
+ * escalation. For example, YELLOW triggers at 70% but only restores to GREEN
+ * when usage falls below 55%.
+ */
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+export declare enum MemoryTier {
+    GREEN = "GREEN",
+    YELLOW = "YELLOW",
+    ORANGE = "ORANGE",
+    RED = "RED",
+    CRITICAL = "CRITICAL"
+}
+export interface MemorySnapshot {
+    heapUsedMb: number;
+    heapTotalMb: number;
+    heapUsedPercent: number;
+    rssUsedMb: number;
+    osFreeMemMb: number;
+    osTotalMemMb: number;
+    osUsedPercent: number;
+    tier: MemoryTier;
+    timestamp: number;
+}
+export interface AttenuationAction {
+    tier: MemoryTier;
+    action: string;
+    timestamp: number;
+}
+export interface AttenuationCallbacks {
+    onDisableCloudInference: () => void;
+    onEnableCloudInference: () => void;
+    onDisableFederatedLearning: () => void;
+    onEnableFederatedLearning: () => void;
+    onReduceSensingFps: (targetFps: number) => void;
+    onRestoreSensingFps: (targetFps: number) => void;
+    onShedModel: (modelName: string) => void;
+    onRestoreModel: (modelName: string) => void;
+    onForceGC: () => void;
+    onEmergencyMode: () => void;
+    onRestoreNormal: () => void;
+}
+export interface MemoryAttenuationManagerOptions {
+    callbacks: AttenuationCallbacks;
+    /** Polling interval in milliseconds. Default: 10000 (10s). */
+    checkIntervalMs?: number;
+    /** Heap usage fraction to enter YELLOW. Default: 0.70. */
+    yellowThreshold?: number;
+    /** Heap usage fraction to enter ORANGE. Default: 0.80. */
+    orangeThreshold?: number;
+    /** Heap usage fraction to enter RED. Default: 0.90. */
+    redThreshold?: number;
+    /** Heap usage fraction to enter CRITICAL. Default: 0.95. */
+    criticalThreshold?: number;
+    /** Fraction below threshold before restoring to a lower tier. Default: 0.15. */
+    hysteresisPercent?: number;
+    /** Normal sensing FPS, restored when dropping below ORANGE. Default: 8. */
+    normalFps?: number;
+    /** Reduced sensing FPS used at ORANGE and above. Default: 2. */
+    reducedFps?: number;
+    /**
+     * Model shed order from *least important* (index 0, shed first) to
+     * *most important* (last index, shed last). During RED, one model is shed
+     * per check cycle starting from the end of this array.
+     *
+     * Default: ['yamnet', 'whisperAsr', 'ferEmotion', 'poseEngagement', 'ageGender', 'gazeTracking']
+     */
+    shedOrder?: string[];
+}
+export declare class MemoryAttenuationManager extends EventEmitter {
+    private readonly callbacks;
+    private readonly checkIntervalMs;
+    private readonly yellowThreshold;
+    private readonly orangeThreshold;
+    private readonly redThreshold;
+    private readonly criticalThreshold;
+    private readonly hysteresisPercent;
+    private readonly normalFps;
+    private readonly reducedFps;
+    private readonly shedOrder;
+    private currentTier;
+    private intervalHandle;
+    private history;
+    private actions;
+    private cloudInferenceDisabled;
+    private federatedLearningDisabled;
+    private fpsReduced;
+    private shedModels;
+    private emergencyModeActive;
+    constructor(options: MemoryAttenuationManagerOptions);
+    /**
+     * Start the periodic memory monitoring interval. The timer is `unref()`'d
+     * so it will not keep the Node.js event loop alive on its own.
+     */
+    start(): void;
+    /** Stop the periodic monitoring interval. */
+    stop(): void;
+    /** Return the current memory tier. */
+    getCurrentTier(): MemoryTier;
+    /** Take a point-in-time memory snapshot (does NOT trigger actions). */
+    getSnapshot(): MemorySnapshot;
+    /** Return the last N snapshots (up to 100). */
+    getHistory(): MemorySnapshot[];
+    /** Return the list of model names currently shed. */
+    getShedModels(): string[];
+    /** Return the full log of attenuation actions taken. */
+    getActions(): AttenuationAction[];
+    /**
+     * Single check cycle. Exposed as package-internal so tests can drive it
+     * deterministically without timers.
+     */
+    check(): void;
+    /**
+     * Classify a heap usage percentage into a MemoryTier, applying hysteresis
+     * to prevent oscillation at tier boundaries.
+     *
+     * Escalation uses the raw threshold (jumps to the highest applicable tier).
+     * Restoration requires the usage to drop below `threshold - hysteresisPercent`
+     * at each boundary, and walks down through all qualifying tiers in a single
+     * check. For example with default settings:
+     *   - Escalate to YELLOW at 70%, restore to GREEN below 55% (70 - 15)
+     *   - Escalate to ORANGE at 80%, restore to YELLOW below 65% (80 - 15)
+     *   - Escalate to RED at 90%, restore to ORANGE below 75% (90 - 15)
+     *   - Escalate to CRITICAL at 95%, restore to RED below 80% (95 - 15)
+     */
+    private classifyTier;
+    /** Apply the actions for entering a given tier (escalating). */
+    private applyEscalation;
+    /**
+     * Apply the restoration actions for entering a given tier (de-escalating).
+     * `tier` is the tier we are *entering* on the way down.
+     */
+    private applyRestoration;
+    /**
+     * Shed the next model in the shed order. Models are shed from the *end*
+     * of `shedOrder` (lowest priority) toward the beginning (highest priority).
+     * One model per call.
+     */
+    private shedNextModel;
+    /**
+     * Restore all shed models in reverse order (highest priority first,
+     * i.e., from the beginning of `shedOrder`).
+     */
+    private restoreAllShedModels;
+    private takeSnapshot;
+    private recordAction;
+}
+//# sourceMappingURL=MemoryAttenuationManager.d.ts.map

package/dist/MemoryAttenuationManager.d.ts.map

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