@gracker/smartperfetto 1.0.13

package/dist/services/stdlibSkillCoverage.js

@@ -0,0 +1,289 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeStdlibSkillCoverage = analyzeStdlibSkillCoverage;
+exports.persistStdlibSnapshot = persistStdlibSnapshot;
+/**
+ * Stdlib Skill Coverage Analyzer (Spark Plan 01)
+ *
+ * Produces a `StdlibSkillCoverageContract` snapshot of:
+ *  - Which Perfetto stdlib modules are referenced by Skill YAML prerequisites.
+ *  - Which modules are detected via raw SQL inspection (`sqlIncludeInjector`).
+ *  - Drift between declared and detected — both ways.
+ *  - Modules that no Skill currently references (uncovered → Skill suggestion).
+ *  - New modules since the last persisted snapshot (Spark #21 watcher hook).
+ *
+ * The analyzer is read-only and intentionally side-effect-light: it can run
+ * inside `validate:skills` summary, the CLI `coverage` command, or be invoked
+ * from any maintenance flow without spinning up a trace processor.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const perfettoStdlibScanner_1 = require("./perfettoStdlibScanner");
+const sqlIncludeInjector_1 = require("../agentv3/sqlIncludeInjector");
+const skillLoader_1 = require("./skillEngine/skillLoader");
+const sparkContracts_1 = require("../types/sparkContracts");
+/**
+ * Match an explicit `INCLUDE PERFETTO MODULE <name>;` statement in raw SQL.
+ * Mirrors the include syntax recognized by `sqlStdlibDependencyAnalyzer` so we count
+ * modules the skill author already wrote into their SQL — without those
+ * being treated as drift just because the auto-injector did not need to
+ * add them.
+ */
+const EXPLICIT_INCLUDE_REGEX = /\bINCLUDE\s+PERFETTO\s+MODULE\s+([\w.]+)/gi;
+/** Walk all SQL fragments inside a skill, returning lowercase module names. */
+function detectStdlibModulesUsedBySkill(skill) {
+    const detected = new Set();
+    const visit = (sql) => {
+        if (!sql || sql.trim().length === 0)
+            return;
+        // Count modules the author already wrote: `INCLUDE PERFETTO MODULE foo;`.
+        // Codex review caught that injectStdlibIncludes() only reports modules
+        // it newly added, so a correctly-included module would otherwise look
+        // like "declared but unused" drift.
+        for (const match of sql.matchAll(EXPLICIT_INCLUDE_REGEX)) {
+            const mod = match[1]?.toLowerCase();
+            if (mod)
+                detected.add(mod);
+        }
+        try {
+            const result = (0, sqlIncludeInjector_1.injectStdlibIncludes)(sql);
+            for (const mod of result.injected)
+                detected.add(mod);
+        }
+        catch {
+            // Stay quiet — analyzer must never throw on malformed SQL; the
+            // `validate:skills` path already surfaces those errors separately.
+        }
+    };
+    // Atomic skills carry a single SQL block.
+    if (skill.sql)
+        visit(skill.sql);
+    // Composite / iterator / parallel skills carry SQL inside steps.
+    const walkStep = (step) => {
+        if (!step)
+            return;
+        const anyStep = step;
+        if (typeof anyStep.sql === 'string')
+            visit(anyStep.sql);
+        if (Array.isArray(anyStep.steps)) {
+            for (const child of anyStep.steps)
+                walkStep(child);
+        }
+        if (Array.isArray(anyStep.branches)) {
+            for (const branch of anyStep.branches)
+                walkStep(branch);
+        }
+    };
+    if (Array.isArray(skill.steps)) {
+        for (const step of skill.steps)
+            walkStep(step);
+    }
+    return detected;
+}
+function diffSets(a, b) {
+    const out = [];
+    for (const item of a)
+        if (!b.has(item))
+            out.push(item);
+    return out.sort();
+}
+/** Snapshot file for Spark #21 watcher diffing. */
+function getDefaultSnapshotPath() {
+    return path.resolve(__dirname, '../../data/stdlibSkillCoverageSnapshot.json');
+}
+function readPersistedSnapshot(snapshotPath) {
+    try {
+        if (!fs.existsSync(snapshotPath))
+            return null;
+        const raw = fs.readFileSync(snapshotPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || !Array.isArray(parsed.modules))
+            return null;
+        return {
+            version: 1,
+            capturedAt: typeof parsed.capturedAt === 'number' ? parsed.capturedAt : 0,
+            modules: parsed.modules,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Analyze Skill prerequisites + raw-SQL detected stdlib usage and produce a
+ * `StdlibSkillCoverageContract` snapshot.
+ *
+ * Returns an unsupported contract (with empty arrays) when the stdlib catalog
+ * is unavailable so the caller can detect missing data without inventing
+ * coverage statistics.
+ */
+async function analyzeStdlibSkillCoverage(options = {}) {
+    const stdlibModules = (0, perfettoStdlibScanner_1.getPerfettoStdlibModules)();
+    if (stdlibModules.length === 0) {
+        return {
+            ...(0, sparkContracts_1.makeSparkProvenance)({
+                source: 'stdlib-skill-coverage',
+                unsupportedReason: 'Perfetto stdlib catalog is empty',
+            }),
+            totalModules: 0,
+            modulesCovered: 0,
+            skillsWithDrift: 0,
+            uncoveredModules: [],
+            skillUsage: [],
+            coverage: [
+                { sparkId: 1, planId: '01', status: 'unsupported' },
+                { sparkId: 21, planId: '01', status: 'unsupported' },
+            ],
+        };
+    }
+    await (0, skillLoader_1.ensureSkillRegistryInitialized)();
+    const skills = skillLoader_1.skillRegistry.getAllSkills();
+    const stdlibSet = new Set(stdlibModules);
+    const declaredCount = new Map();
+    const usedCount = new Map();
+    const skillUsage = [];
+    let skillsWithDrift = 0;
+    for (const skill of skills) {
+        const declared = (skill.prerequisites?.modules ?? []).slice().sort();
+        const detected = Array.from(detectStdlibModulesUsedBySkill(skill)).sort();
+        const declaredSet = new Set(declared);
+        const detectedSet = new Set(detected);
+        const declaredButUnused = diffSets(declared, detectedSet);
+        const detectedButUndeclared = diffSets(detected, declaredSet);
+        if (declaredButUnused.length > 0 || detectedButUndeclared.length > 0) {
+            skillsWithDrift += 1;
+        }
+        for (const m of declared) {
+            if (stdlibSet.has(m))
+                declaredCount.set(m, (declaredCount.get(m) ?? 0) + 1);
+        }
+        for (const m of detected) {
+            if (stdlibSet.has(m))
+                usedCount.set(m, (usedCount.get(m) ?? 0) + 1);
+        }
+        skillUsage.push({
+            skillId: skill.name,
+            declared,
+            detected,
+            declaredButUnused,
+            detectedButUndeclared,
+        });
+    }
+    // Coverage = modules referenced by any skill (declared OR detected).
+    const referenced = new Set();
+    for (const m of declaredCount.keys())
+        referenced.add(m);
+    for (const m of usedCount.keys())
+        referenced.add(m);
+    const uncoveredModules = [];
+    for (const m of stdlibModules) {
+        if (referenced.has(m))
+            continue;
+        uncoveredModules.push({
+            module: m,
+            declaredBySkills: declaredCount.get(m) ?? 0,
+            usedBySkills: usedCount.get(m) ?? 0,
+        });
+    }
+    // Watcher: detect modules added since the persisted snapshot.
+    let newlyAddedModules;
+    if (!options.ignoreSnapshot) {
+        const snapshotPath = options.snapshotPath ?? getDefaultSnapshotPath();
+        const previous = readPersistedSnapshot(snapshotPath);
+        if (previous) {
+            const previousSet = new Set(previous.modules);
+            const added = stdlibModules.filter(m => !previousSet.has(m));
+            if (added.length > 0) {
+                newlyAddedModules = added.map(m => ({
+                    module: m,
+                    declaredBySkills: declaredCount.get(m) ?? 0,
+                    usedBySkills: usedCount.get(m) ?? 0,
+                    newSinceLastSnapshot: true,
+                }));
+            }
+        }
+    }
+    return {
+        ...(0, sparkContracts_1.makeSparkProvenance)({ source: 'stdlib-skill-coverage' }),
+        totalModules: stdlibModules.length,
+        modulesCovered: referenced.size,
+        skillsWithDrift,
+        uncoveredModules,
+        skillUsage,
+        ...(newlyAddedModules ? { newlyAddedModules } : {}),
+        coverage: [
+            {
+                sparkId: 1,
+                planId: '01',
+                status: 'implemented',
+                note: 'Skill prerequisites + raw SQL detection cross-checked.',
+            },
+            {
+                sparkId: 21,
+                planId: '01',
+                status: newlyAddedModules ? 'implemented' : 'scaffolded',
+                note: newlyAddedModules
+                    ? 'Newly added stdlib modules surfaced via persisted snapshot diff.'
+                    : 'Watcher uses persisted snapshot; no diff yet because no snapshot exists.',
+            },
+        ],
+    };
+}
+/**
+ * Persist the current stdlib catalog as a snapshot so future runs can detect
+ * newly added modules. Safe to call from CLI; never throws on filesystem
+ * issues — it logs a warning and continues.
+ */
+function persistStdlibSnapshot(snapshotPath) {
+    const target = snapshotPath ?? getDefaultSnapshotPath();
+    const modules = (0, perfettoStdlibScanner_1.getPerfettoStdlibModules)();
+    const snapshot = {
+        version: 1,
+        capturedAt: Date.now(),
+        modules,
+    };
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, JSON.stringify(snapshot, null, 2), 'utf-8');
+    }
+    catch (err) {
+        console.warn(`[StdlibSkillCoverage] Failed to write snapshot ${target}: ${err.message}`);
+    }
+}
+//# sourceMappingURL=stdlibSkillCoverage.js.map

package/dist/services/stdlibSkillCoverage.js.map

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

package/dist/services/threadSchedContext.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Thread State + Scheduler Context Aggregator (Spark Plan 11)
+ *
+ * Aggregates per-thread `thread_state` rows + `sched.with_context` wakeup
+ * edges into a `ThreadSchedContextContract`. The contract is the
+ * prerequisite prior used by jank, ANR, and startup decision trees.
+ */
+import { type NsTimeRange, type ThreadSchedContextContract } from '../types/sparkContracts';
+export interface ThreadStateRow {
+    utid: number;
+    pid: number;
+    threadName: string;
+    state: string;
+    durNs: number;
+}
+export interface WakeupRow {
+    fromUtid: number;
+    toUtid: number;
+    fromThread?: string;
+    toThread?: string;
+    ts: number;
+    latencyNs?: number;
+    reason?: string;
+}
+export interface CriticalChainRow {
+    utid: number;
+    threadName: string;
+    startNs: number;
+    endNs: number;
+    reason: string;
+}
+export interface ThreadSchedContextOptions {
+    range: NsTimeRange;
+    threadStateRows: ThreadStateRow[];
+    wakeupEdges?: WakeupRow[];
+    criticalChain?: CriticalChainRow[];
+    /**
+     * Per-utid runnable-latency p95 in ns. Caller computes via SQL window
+     * aggregation; supplying it as a separate input keeps this function pure.
+     */
+    runnableLatencyP95Ns?: Record<number, number>;
+}
+/**
+ * Assemble the contract from raw rows. Caller is responsible for clamping
+ * thread_state durations to the analysis window — this function trusts the
+ * inputs and just pivots them.
+ */
+export declare function buildThreadSchedContext(options: ThreadSchedContextOptions): ThreadSchedContextContract;
+//# sourceMappingURL=threadSchedContext.d.ts.map

package/dist/services/threadSchedContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threadSchedContext.d.ts","sourceRoot":"","sources":["../../src/services/threadSchedContext.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,OAAO,EAGL,KAAK,WAAW,EAEhB,KAAK,0BAA0B,EAEhC,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,WAAW,CAAC;IACnB,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACnC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/C;AAmCD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,GACjC,0BAA0B,CAgD5B"}

package/dist/services/threadSchedContext.js

@@ -0,0 +1,84 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildThreadSchedContext = buildThreadSchedContext;
+/**
+ * Thread State + Scheduler Context Aggregator (Spark Plan 11)
+ *
+ * Aggregates per-thread `thread_state` rows + `sched.with_context` wakeup
+ * edges into a `ThreadSchedContextContract`. The contract is the
+ * prerequisite prior used by jank, ANR, and startup decision trees.
+ */
+const sparkContracts_1 = require("../types/sparkContracts");
+/** Group rows by utid and pivot duration by state. */
+function groupBreakdowns(rows, range, runnableP95, wakeupCounts) {
+    const byUtid = new Map();
+    for (const row of rows) {
+        let entry = byUtid.get(row.utid);
+        if (!entry) {
+            entry = { row, states: {} };
+            byUtid.set(row.utid, entry);
+        }
+        entry.states[row.state] = (entry.states[row.state] ?? 0) + row.durNs;
+    }
+    const breakdowns = [];
+    for (const [utid, entry] of byUtid) {
+        breakdowns.push({
+            utid,
+            pid: entry.row.pid,
+            threadName: entry.row.threadName,
+            range,
+            durByStateNs: entry.states,
+            ...(wakeupCounts[utid] ? { wakeupCount: wakeupCounts[utid] } : {}),
+            ...(runnableP95?.[utid] ? { runnableLatencyP95Ns: runnableP95[utid] } : {}),
+        });
+    }
+    // Stable order: utid ascending.
+    breakdowns.sort((a, b) => a.utid - b.utid);
+    return breakdowns;
+}
+/**
+ * Assemble the contract from raw rows. Caller is responsible for clamping
+ * thread_state durations to the analysis window — this function trusts the
+ * inputs and just pivots them.
+ */
+function buildThreadSchedContext(options) {
+    const wakeupCounts = {};
+    for (const edge of options.wakeupEdges ?? []) {
+        wakeupCounts[edge.toUtid] = (wakeupCounts[edge.toUtid] ?? 0) + 1;
+    }
+    const threadStates = groupBreakdowns(options.threadStateRows, options.range, options.runnableLatencyP95Ns, wakeupCounts);
+    const wakeupEdges = options.wakeupEdges?.map(e => ({
+        fromUtid: e.fromUtid,
+        toUtid: e.toUtid,
+        ts: e.ts,
+        ...(e.fromThread ? { fromThread: e.fromThread } : {}),
+        ...(e.toThread ? { toThread: e.toThread } : {}),
+        ...(e.latencyNs !== undefined ? { latencyNs: e.latencyNs } : {}),
+        ...(e.reason ? { reason: e.reason } : {}),
+    }));
+    const criticalChain = options.criticalChain?.map(r => ({
+        utid: r.utid,
+        threadName: r.threadName,
+        range: { startNs: r.startNs, endNs: r.endNs },
+        reason: r.reason,
+    }));
+    const allEmpty = threadStates.length === 0;
+    return {
+        ...(0, sparkContracts_1.makeSparkProvenance)({
+            source: 'thread-sched-context',
+            ...(allEmpty ? { unsupportedReason: 'thread_state input is empty' } : {}),
+        }),
+        range: options.range,
+        threadStates,
+        ...(wakeupEdges && wakeupEdges.length > 0 ? { wakeupEdges } : {}),
+        ...(criticalChain && criticalChain.length > 0 ? { criticalChain } : {}),
+        coverage: [
+            { sparkId: 6, planId: '11', status: 'implemented' },
+            { sparkId: 17, planId: '11', status: criticalChain && criticalChain.length > 0 ? 'implemented' : 'scaffolded' },
+        ],
+    };
+}
+//# sourceMappingURL=threadSchedContext.js.map

package/dist/services/threadSchedContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threadSchedContext.js","sourceRoot":"","sources":["../../src/services/threadSchedContext.ts"],"names":[],"mappings":";AAAA,6CAA6C;AAC7C,0CAA0C;AAC1C,+DAA+D;;AA+F/D,0DAkDC;AA/ID;;;;;;GAMG;AAEH,4DAOiC;AAwCjC,sDAAsD;AACtD,SAAS,eAAe,CACtB,IAAsB,EACtB,KAAkB,EAClB,WAA+C,EAC/C,YAAoC;IAEpC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAiE,CAAC;IACxF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,EAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAC,CAAC;YAC1B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;IACvE,CAAC;IACD,MAAM,UAAU,GAA2B,EAAE,CAAC;IAC9C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACnC,UAAU,CAAC,IAAI,CAAC;YACd,IAAI;YACJ,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG;YAClB,UAAU,EAAE,KAAK,CAAC,GAAG,CAAC,UAAU;YAChC,KAAK;YACL,YAAY,EAAE,KAAK,CAAC,MAAM;YAC1B,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAC,WAAW,EAAE,YAAY,CAAC,IAAI,CAAC,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAC,oBAAoB,EAAE,WAAW,CAAC,IAAI,CAAC,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E,CAAC,CAAC;IACL,CAAC;IACD,gCAAgC;IAChC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3C,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CACrC,OAAkC;IAElC,MAAM,YAAY,GAA2B,EAAE,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;QAC7C,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,YAAY,GAAG,eAAe,CAClC,OAAO,CAAC,eAAe,EACvB,OAAO,CAAC,KAAK,EACb,OAAO,CAAC,oBAAoB,EAC5B,YAAY,CACb,CAAC;IAEF,MAAM,WAAW,GAAsC,OAAO,CAAC,WAAW,EAAE,GAAG,CAC7E,CAAC,CAAC,EAAE,CAAC,CAAC;QACJ,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAC,UAAU,EAAE,CAAC,CAAC,UAAU,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAC,SAAS,EAAE,CAAC,CAAC,SAAS,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAC,CACH,CAAC;IAEF,MAAM,aAAa,GACjB,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,EAAC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAC;QAC3C,MAAM,EAAE,CAAC,CAAC,MAAM;KACjB,CAAC,CAAC,CAAC;IAEN,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC;IAC3C,OAAO;QACL,GAAG,IAAA,oCAAmB,EAAC;YACrB,MAAM,EAAE,sBAAsB;YAC9B,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAC,iBAAiB,EAAE,6BAA6B,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACxE,CAAC;QACF,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,YAAY;QACZ,GAAG,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAC,WAAW,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,aAAa,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAC,aAAa,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,QAAQ,EAAE;YACR,EAAC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAC;YACjD,EAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,EAAC;SAC9G;KACF,CAAC;AACJ,CAAC"}

package/dist/services/timelineBinning.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Timeline Binning + Counter RLE (Spark Plan 05)
+ *
+ * Two compressors on a shared contract:
+ *  - binTimelineSamples: uniform fixed-width binning of (ts, value) pairs
+ *    using a configurable aggregation (Spark #23 token compression).
+ *  - encodeCounterRle: turn a counter trail into run-length encoded
+ *    segments that capture each turning point exactly once
+ *    (Spark #27 — counter RLE / turning-point compression).
+ *
+ * Both functions return a TimelineBinningContract sharing trackId, range
+ * and originalSampleCount so callers can reason about the compression
+ * ratio uniformly regardless of which encoder ran.
+ */
+import { type NsTimeRange, type TimelineBinAggregation, type TimelineBinningContract } from '../types/sparkContracts';
+export interface TimelineSample {
+    ts: number;
+    value: number;
+}
+export interface BinTimelineSamplesOptions {
+    trackId: string | number;
+    samples: TimelineSample[];
+    range: NsTimeRange;
+    binDurNs: number;
+    aggregation?: TimelineBinAggregation;
+}
+/**
+ * Uniform-width binning. Samples outside `range` are dropped.
+ * Empty bins ARE included (with rowCount=0) so downstream consumers can
+ * detect coverage gaps without needing to recompute the time axis.
+ */
+export declare function binTimelineSamples(options: BinTimelineSamplesOptions): TimelineBinningContract;
+export interface EncodeCounterRleOptions {
+    trackId: string | number;
+    samples: TimelineSample[];
+    range: NsTimeRange;
+}
+/**
+ * Run-length encode a counter trail. Adjacent samples with the same value
+ * collapse into a single segment, and the segment delta is the change from
+ * the prior segment so consumers can render turning-point arrows.
+ */
+export declare function encodeCounterRle(options: EncodeCounterRleOptions): TimelineBinningContract;
+//# sourceMappingURL=timelineBinning.d.ts.map

package/dist/services/timelineBinning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timelineBinning.d.ts","sourceRoot":"","sources":["../../src/services/timelineBinning.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAGL,KAAK,WAAW,EAEhB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC7B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,sBAAsB,CAAC;CACtC;AAkBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,uBAAuB,CAsDzB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAC/B,uBAAuB,CAmDzB"}

package/dist/services/timelineBinning.js

@@ -0,0 +1,150 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.binTimelineSamples = binTimelineSamples;
+exports.encodeCounterRle = encodeCounterRle;
+/**
+ * Timeline Binning + Counter RLE (Spark Plan 05)
+ *
+ * Two compressors on a shared contract:
+ *  - binTimelineSamples: uniform fixed-width binning of (ts, value) pairs
+ *    using a configurable aggregation (Spark #23 token compression).
+ *  - encodeCounterRle: turn a counter trail into run-length encoded
+ *    segments that capture each turning point exactly once
+ *    (Spark #27 — counter RLE / turning-point compression).
+ *
+ * Both functions return a TimelineBinningContract sharing trackId, range
+ * and originalSampleCount so callers can reason about the compression
+ * ratio uniformly regardless of which encoder ran.
+ */
+const sparkContracts_1 = require("../types/sparkContracts");
+function aggregate(values, op) {
+    if (values.length === 0)
+        return 0;
+    switch (op) {
+        case 'sum':
+            return values.reduce((a, b) => a + b, 0);
+        case 'avg':
+            return values.reduce((a, b) => a + b, 0) / values.length;
+        case 'count':
+            return values.length;
+        case 'max':
+            return Math.max(...values);
+        case 'min':
+            return Math.min(...values);
+    }
+}
+/**
+ * Uniform-width binning. Samples outside `range` are dropped.
+ * Empty bins ARE included (with rowCount=0) so downstream consumers can
+ * detect coverage gaps without needing to recompute the time axis.
+ */
+function binTimelineSamples(options) {
+    const aggregation = options.aggregation ?? 'avg';
+    const { trackId, range, binDurNs } = options;
+    if (binDurNs <= 0 || range.endNs <= range.startNs) {
+        return {
+            ...(0, sparkContracts_1.makeSparkProvenance)({
+                source: 'timeline-binning',
+                unsupportedReason: 'invalid bin width or range',
+            }),
+            trackId,
+            range,
+            originalSampleCount: options.samples.length,
+            coverage: [{ sparkId: 23, planId: '05', status: 'unsupported' }],
+        };
+    }
+    const totalDur = range.endNs - range.startNs;
+    const binCount = Math.ceil(totalDur / binDurNs);
+    const buckets = Array.from({ length: binCount }, () => []);
+    for (const s of options.samples) {
+        if (s.ts < range.startNs || s.ts >= range.endNs)
+            continue;
+        const idx = Math.floor((s.ts - range.startNs) / binDurNs);
+        if (idx < 0 || idx >= buckets.length)
+            continue;
+        buckets[idx].push(s.value);
+    }
+    // Codex round 5 caught that the final bucket extended past range.endNs
+    // when totalDur isn't a multiple of binDurNs. Clamp the last bucket so
+    // [startNs, startNs + durNs) stays inside the requested window.
+    const bins = buckets.map((values, i) => {
+        const startNs = range.startNs + i * binDurNs;
+        const naturalEnd = startNs + binDurNs;
+        const clampedEnd = Math.min(naturalEnd, range.endNs);
+        return {
+            startNs,
+            durNs: clampedEnd - startNs,
+            value: aggregate(values, aggregation),
+            rowCount: values.length,
+        };
+    });
+    return {
+        ...(0, sparkContracts_1.makeSparkProvenance)({ source: 'timeline-binning' }),
+        trackId,
+        range,
+        binDurNs,
+        aggregation,
+        bins,
+        originalSampleCount: options.samples.length,
+        coverage: [
+            { sparkId: 23, planId: '05', status: 'implemented' },
+        ],
+    };
+}
+/**
+ * Run-length encode a counter trail. Adjacent samples with the same value
+ * collapse into a single segment, and the segment delta is the change from
+ * the prior segment so consumers can render turning-point arrows.
+ */
+function encodeCounterRle(options) {
+    const { trackId, range } = options;
+    // Half-open window [startNs, endNs) matching binTimelineSamples.
+    // Codex review caught that an inclusive endNs caused the boundary
+    // sample to appear in both adjacent windows when callers chained them.
+    const samples = options.samples
+        .filter(s => s.ts >= range.startNs && s.ts < range.endNs)
+        .slice()
+        .sort((a, b) => a.ts - b.ts);
+    const rle = [];
+    let prevValue = null;
+    let segmentStart = range.startNs;
+    for (let i = 0; i < samples.length; i++) {
+        const sample = samples[i];
+        if (prevValue === null) {
+            prevValue = sample.value;
+            segmentStart = sample.ts;
+            continue;
+        }
+        if (sample.value !== prevValue) {
+            rle.push({
+                startNs: segmentStart,
+                endNs: sample.ts,
+                value: prevValue,
+                ...(rle.length > 0 ? { delta: prevValue - rle[rle.length - 1].value } : {}),
+            });
+            segmentStart = sample.ts;
+            prevValue = sample.value;
+        }
+    }
+    // Close the last segment at range.endNs.
+    if (prevValue !== null) {
+        rle.push({
+            startNs: segmentStart,
+            endNs: range.endNs,
+            value: prevValue,
+            ...(rle.length > 0 ? { delta: prevValue - rle[rle.length - 1].value } : {}),
+        });
+    }
+    return {
+        ...(0, sparkContracts_1.makeSparkProvenance)({ source: 'counter-rle' }),
+        trackId,
+        range,
+        rle,
+        originalSampleCount: options.samples.length,
+        coverage: [{ sparkId: 27, planId: '05', status: 'implemented' }],
+    };
+}
+//# sourceMappingURL=timelineBinning.js.map

package/dist/services/timelineBinning.js.map

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