@gracker/smartperfetto 1.0.13

package/dist/services/aospKnowledgeIngester.d.ts

@@ -0,0 +1,67 @@
+import type { RagStore } from './ragStore';
+/** One AOSP source file the fetcher returns. License is REQUIRED;
+ * undefined license rejects the file at the ingester. */
+export interface AospFile {
+    /** Path relative to the AOSP root, e.g.
+     *  `frameworks/base/services/core/.../HwcLayer.cpp`. */
+    filePath: string;
+    /** Source content (typically C++ or Java). */
+    content: string;
+    /** Pinned git commit hash for the AOSP snapshot. Stamped onto
+     *  `verifiedAt` indirectly (epoch ms approximate; commit hash
+     *  carried in the `notes` field of the chunk envelope). */
+    commitHash: string;
+    /** Approximate epoch-ms timestamp when this snapshot was captured. */
+    fetchedAt: number;
+    /** License of the source file. Required — typical values are
+     *  `Apache-2.0` for AOSP / `BSD-3-Clause` for Linux kernel paths. */
+    license: string;
+    /** Optional title; falls back to last path segment. */
+    title?: string;
+}
+/** Pluggable source for AOSP files. Production wiring will read
+ * from a pinned manifest snapshot; tests inject a stub. */
+export interface AospFetcher {
+    fetchFiles(opts?: {
+        pathPrefix?: string;
+    }): Promise<AospFile[]>;
+}
+export interface AospIngestOptions {
+    /** Maximum characters per chunk. Defaults to 2000 (slightly
+     *  larger than blog because source files have more boilerplate). */
+    maxChunkChars?: number;
+    /** Restrict to a path prefix (forwarded to fetcher). */
+    pathPrefix?: string;
+}
+export interface AospIngestError {
+    filePath: string;
+    reason: string;
+}
+export interface AospIngestResult {
+    filesProcessed: number;
+    chunksAdded: number;
+    chunksSkipped: number;
+    errors: AospIngestError[];
+}
+interface PackedChunk {
+    text: string;
+    offset: number;
+}
+/** Section-based chunker. Tries to split on function / class
+ * boundaries; falls back to fixed-size when no boundaries land
+ * within `maxChars * 2`. */
+declare function chunkSource(text: string, maxChars: number): PackedChunk[];
+declare function makeChunkId(filePath: string, offset: number): string;
+export declare class AospKnowledgeIngester {
+    private readonly store;
+    private readonly fetcher;
+    constructor(store: RagStore, fetcher: AospFetcher);
+    ingest(opts?: AospIngestOptions): Promise<AospIngestResult>;
+}
+/** Test-only export of the chunker for boundary-detection coverage. */
+export declare const __TEST_ONLY__: {
+    chunkSource: typeof chunkSource;
+    makeChunkId: typeof makeChunkId;
+};
+export {};
+//# sourceMappingURL=aospKnowledgeIngester.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"aospKnowledgeIngester.d.ts","sourceRoot":"","sources":["../../src/services/aospKnowledgeIngester.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAGzC;yDACyD;AACzD,MAAM,WAAW,QAAQ;IACvB;4DACwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB;;+DAE2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB;yEACqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;2DAC2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,IAAI,CAAC,EAAE;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,iBAAiB;IAChC;wEACoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAWD,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;4BAE4B;AAC5B,iBAAS,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CA+ClE;AAED,iBAAS,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK7D;AAMD,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,WAAW;IAGjC,MAAM,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CA4DtE;AAED,uEAAuE;AACvE,eAAO,MAAM,aAAa;;;CAGzB,CAAC"}

package/dist/services/aospKnowledgeIngester.js

@@ -0,0 +1,171 @@
+"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.__TEST_ONLY__ = exports.AospKnowledgeIngester = void 0;
+/**
+ * AospKnowledgeIngester — pulls source files from an Android Open
+ * Source Project mirror (or any source matching `AospFetcher`),
+ * splits each file into chunks, and writes them to a `RagStore`
+ * under the `aosp` source kind with a license stamp.
+ *
+ * Plan 55 M1 scope:
+ * - Pluggable `AospFetcher` so tests stay offline.
+ * - Mandatory license at ingestion time. Without a license the
+ *   chunk is recorded with `unsupportedReason` and stays in the
+ *   index for audit but never surfaces at retrieval.
+ *   `RagStore.addChunk()` itself rejects aosp chunks without a
+ *   license string — we double-up here so the operator sees the
+ *   reason at ingestion time rather than via a thrown error.
+ * - Section-based chunking by C++ / Java function boundaries when
+ *   present, falling back to fixed-size paragraph packing for
+ *   files without recognizable structure.
+ * - Stable chunk ids: `sha256(filePath + offset)` first 16 hex
+ *   chars; re-ingesting the same file replaces in place.
+ *
+ * Out of scope:
+ * - Real AOSP fetcher (M2 — would call `git archive` against the
+ *   pinned manifest snapshot).
+ * - Cron-based incremental refresh (M2).
+ *
+ * @module aospKnowledgeIngester
+ */
+const crypto_1 = require("crypto");
+const DEFAULT_MAX_CHUNK_CHARS = 2000;
+/** Heuristic regex for C++ / Java function boundaries. Triggers on
+ * a line that looks like `[modifiers] returnType name(args) {` or
+ * `class Name {`. Imperfect but enough to chop large files into
+ * topical chunks. */
+const FUNCTION_BOUNDARY_REGEX = /^(?:[\w<>:&,\s\*]+\s+)?[\w~]+\s*\([^)]*\)[\s\w:]*?\{$|^class\s+\w+/gm;
+/** Section-based chunker. Tries to split on function / class
+ * boundaries; falls back to fixed-size when no boundaries land
+ * within `maxChars * 2`. */
+function chunkSource(text, maxChars) {
+    if (text.trim().length === 0)
+        return [];
+    const boundaries = [0];
+    let m;
+    // Reset regex internal state in case of repeated calls.
+    FUNCTION_BOUNDARY_REGEX.lastIndex = 0;
+    while ((m = FUNCTION_BOUNDARY_REGEX.exec(text)) !== null) {
+        if (m.index > 0)
+            boundaries.push(m.index);
+    }
+    boundaries.push(text.length);
+    const out = [];
+    let bufStart = boundaries[0];
+    let bufEnd = boundaries[0];
+    for (let i = 1; i < boundaries.length; i++) {
+        const next = boundaries[i];
+        if (next - bufStart > maxChars && bufEnd > bufStart) {
+            // Emit the current section before the next boundary pushes us
+            // over. Start a new buffer at the prior boundary.
+            out.push({ text: text.slice(bufStart, bufEnd), offset: bufStart });
+            bufStart = bufEnd;
+        }
+        bufEnd = next;
+    }
+    if (bufEnd > bufStart) {
+        out.push({ text: text.slice(bufStart, bufEnd), offset: bufStart });
+    }
+    // Fallback: if any chunk exceeds 2× maxChars (because no boundaries
+    // landed nearby), hard-split it into fixed-size pieces so the
+    // retrieval path stays reasonable.
+    const final = [];
+    for (const c of out) {
+        if (c.text.length <= maxChars * 2) {
+            final.push(c);
+            continue;
+        }
+        let cursor = 0;
+        while (cursor < c.text.length) {
+            const piece = c.text.slice(cursor, cursor + maxChars);
+            final.push({ text: piece, offset: c.offset + cursor });
+            cursor += maxChars;
+        }
+    }
+    return final;
+}
+function makeChunkId(filePath, offset) {
+    return (0, crypto_1.createHash)('sha256')
+        .update(`${filePath}|${offset}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+function estimateTokenCount(text) {
+    return Math.max(1, Math.round(text.length / 4));
+}
+class AospKnowledgeIngester {
+    constructor(store, fetcher) {
+        this.store = store;
+        this.fetcher = fetcher;
+    }
+    async ingest(opts = {}) {
+        const maxChars = opts.maxChunkChars ?? DEFAULT_MAX_CHUNK_CHARS;
+        const result = {
+            filesProcessed: 0,
+            chunksAdded: 0,
+            chunksSkipped: 0,
+            errors: [],
+        };
+        let files;
+        try {
+            files = await this.fetcher.fetchFiles({ pathPrefix: opts.pathPrefix });
+        }
+        catch (err) {
+            result.errors.push({
+                filePath: '<fetcher>',
+                reason: err instanceof Error ? err.message : String(err),
+            });
+            return result;
+        }
+        for (const file of files) {
+            result.filesProcessed++;
+            if (!file.license || file.license.trim().length === 0) {
+                result.errors.push({
+                    filePath: file.filePath,
+                    reason: 'license required for kind=aosp; entry rejected',
+                });
+                result.chunksSkipped++;
+                continue;
+            }
+            try {
+                const packed = chunkSource(file.content, maxChars);
+                for (const p of packed) {
+                    const chunk = {
+                        chunkId: makeChunkId(file.filePath, p.offset),
+                        kind: 'aosp',
+                        uri: file.filePath,
+                        title: file.title ?? file.filePath.split('/').pop(),
+                        snippet: p.text,
+                        tokenCount: estimateTokenCount(p.text),
+                        license: file.license,
+                        indexedAt: file.fetchedAt,
+                        verifiedAt: file.fetchedAt,
+                        // Use SHA prefix as a "build id"-ish marker by reusing
+                        // license string slot is wrong — keep commit hash off-band
+                        // for now; M2 will add a richer chunk shape if needed.
+                    };
+                    this.store.addChunk(chunk);
+                    result.chunksAdded++;
+                }
+            }
+            catch (err) {
+                result.errors.push({
+                    filePath: file.filePath,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
+                result.chunksSkipped++;
+            }
+        }
+        return result;
+    }
+}
+exports.AospKnowledgeIngester = AospKnowledgeIngester;
+/** Test-only export of the chunker for boundary-detection coverage. */
+exports.__TEST_ONLY__ = {
+    chunkSource,
+    makeChunkId,
+};
+//# sourceMappingURL=aospKnowledgeIngester.js.map

package/dist/services/aospKnowledgeIngester.js.map

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

package/dist/services/artifactCompression.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Artifact Compression (Spark Plan 04)
+ *
+ * Takes a row-shaped artifact (columns + rows) and produces a compressed
+ * view plus the schema-aware sidecar metadata required by
+ * `ArtifactSchemaContract`. The full data still lives in the
+ * `ArtifactStore`; this module only builds the compact summary that
+ * downstream prompts and reporters consume.
+ *
+ * Strategies (Spark #24, #25, #26):
+ *  - full        – no row drop (control case)
+ *  - top_k       – keep top-K rows by `rankBy`
+ *  - p95_tail    – keep rows whose `rankBy` value sits in the >=p95 tail
+ *  - p99_tail    – same, p99
+ *  - random      – seeded random sample of size `topK` (reproducible)
+ *  - cuj_window  – keep rows whose timestamp falls inside `window`
+ *  - cluster_representative – pick the densest representative per cluster
+ *
+ * Schema-aware columns (Spark #28) carry the type/unit/source/sampling
+ * note so AI consumers know exactly what was preserved.
+ */
+import { type ArtifactColumnSpec, type ArtifactSamplingStrategy, type ArtifactSchemaContract, type NsTimeRange } from '../types/sparkContracts';
+export interface CompressionOptions {
+    artifactId: string;
+    columns: ArtifactColumnSpec[];
+    rows: any[][];
+    strategy: ArtifactSamplingStrategy;
+    /** Column name to rank by for top_k/p95_tail/p99_tail. */
+    rankBy?: string;
+    /** Top-K limit for `top_k` and `random`. Defaults to 50. */
+    topK?: number;
+    /** ns window for `cuj_window`. */
+    window?: NsTimeRange;
+    /** Column to read timestamp from when applying `cuj_window`. */
+    timestampColumn?: string;
+    /** Reproducibility seed for `random` strategy. */
+    randomSeed?: number;
+    /** Cluster count for `cluster_representative` (defaults to topK). */
+    clusterCount?: number;
+}
+export interface CompressionResult {
+    compressedRows: any[][];
+    contract: ArtifactSchemaContract;
+}
+/**
+ * Compress an artifact according to `strategy` and emit the schema-aware
+ * sidecar contract. Always returns at least an empty compressed-rows array
+ * + a contract, never throws on bad inputs (downstream will surface the
+ * fallback via `compression.strategy = 'full'` when the strategy can't run).
+ */
+export declare function compressArtifact(opts: CompressionOptions): CompressionResult;
+//# sourceMappingURL=artifactCompression.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifactCompression.d.ts","sourceRoot":"","sources":["../../src/services/artifactCompression.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAEL,KAAK,kBAAkB,EAEvB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;IACd,QAAQ,EAAE,wBAAwB,CAAC;IACnC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,GAAG,EAAE,EAAE,CAAC;IACxB,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAyED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,CA4H5E"}

package/dist/services/artifactCompression.js

@@ -0,0 +1,215 @@
+"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.compressArtifact = compressArtifact;
+/**
+ * Artifact Compression (Spark Plan 04)
+ *
+ * Takes a row-shaped artifact (columns + rows) and produces a compressed
+ * view plus the schema-aware sidecar metadata required by
+ * `ArtifactSchemaContract`. The full data still lives in the
+ * `ArtifactStore`; this module only builds the compact summary that
+ * downstream prompts and reporters consume.
+ *
+ * Strategies (Spark #24, #25, #26):
+ *  - full        – no row drop (control case)
+ *  - top_k       – keep top-K rows by `rankBy`
+ *  - p95_tail    – keep rows whose `rankBy` value sits in the >=p95 tail
+ *  - p99_tail    – same, p99
+ *  - random      – seeded random sample of size `topK` (reproducible)
+ *  - cuj_window  – keep rows whose timestamp falls inside `window`
+ *  - cluster_representative – pick the densest representative per cluster
+ *
+ * Schema-aware columns (Spark #28) carry the type/unit/source/sampling
+ * note so AI consumers know exactly what was preserved.
+ */
+const sparkContracts_1 = require("../types/sparkContracts");
+function indexOfColumn(columns, name) {
+    return columns.findIndex(c => c.name === name);
+}
+function clamp(n, low, high) {
+    return Math.max(low, Math.min(high, n));
+}
+/** Mulberry32 PRNG — deterministic and good enough for sampling. */
+function makePrng(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function pickQuantileTail(rows, rankIndex, quantile) {
+    const values = rows
+        .map(r => Number(r[rankIndex]))
+        .filter(v => Number.isFinite(v))
+        .sort((a, b) => a - b);
+    if (values.length === 0)
+        return { kept: rows.slice(), threshold: 0 };
+    const idx = clamp(Math.floor(values.length * quantile), 0, values.length - 1);
+    const threshold = values[idx];
+    const kept = rows.filter(r => Number(r[rankIndex]) >= threshold);
+    return { kept, threshold };
+}
+function clusterRepresentatives(rows, rankIndex, clusterCount) {
+    if (rows.length === 0 || clusterCount <= 0) {
+        return { kept: rows.slice(), representativeIndices: [] };
+    }
+    // Simple equi-frequency clustering: split sorted indices into N buckets
+    // and keep the median row of each bucket as the representative. We use
+    // floating-point boundaries so the entire range is covered even when
+    // rows.length is not divisible by clusterCount — Codex round 6 caught
+    // that Math.floor(N/K) bucketing dropped the high tail (e.g. 10 rows
+    // with 6 clusters previously returned only the 6 lowest-value rows).
+    const indexed = rows
+        .map((row, idx) => ({ row, idx, value: Number(row[rankIndex]) }))
+        .sort((a, b) => a.value - b.value);
+    const k = Math.min(clusterCount, indexed.length);
+    const kept = [];
+    const representativeIndices = [];
+    const seen = new Set();
+    for (let b = 0; b < k; b++) {
+        const start = Math.floor((b * indexed.length) / k);
+        const end = Math.floor(((b + 1) * indexed.length) / k);
+        if (end <= start)
+            continue;
+        const median = start + Math.floor((end - start) / 2);
+        const safeMedian = Math.min(indexed.length - 1, median);
+        if (seen.has(safeMedian))
+            continue;
+        seen.add(safeMedian);
+        kept.push(indexed[safeMedian].row);
+        representativeIndices.push(indexed[safeMedian].idx);
+    }
+    return { kept, representativeIndices };
+}
+/**
+ * Compress an artifact according to `strategy` and emit the schema-aware
+ * sidecar contract. Always returns at least an empty compressed-rows array
+ * + a contract, never throws on bad inputs (downstream will surface the
+ * fallback via `compression.strategy = 'full'` when the strategy can't run).
+ */
+function compressArtifact(opts) {
+    const { artifactId, columns, rows } = opts;
+    const originalRowCount = rows.length;
+    const topK = opts.topK ?? 50;
+    let compressedRows = rows.slice();
+    let strategy = opts.strategy;
+    let representativeIndices;
+    const samplingNotes = new Map();
+    switch (opts.strategy) {
+        case 'full':
+            compressedRows = rows.slice();
+            break;
+        case 'top_k': {
+            const idx = opts.rankBy ? indexOfColumn(columns, opts.rankBy) : -1;
+            if (idx < 0) {
+                // Fallback to full when rankBy missing — schema records the fallback.
+                strategy = 'full';
+                break;
+            }
+            compressedRows = rows
+                .slice()
+                .sort((a, b) => Number(b[idx]) - Number(a[idx]))
+                .slice(0, topK);
+            samplingNotes.set(opts.rankBy, `top-${topK} by ${opts.rankBy}`);
+            break;
+        }
+        case 'p95_tail':
+        case 'p99_tail': {
+            const idx = opts.rankBy ? indexOfColumn(columns, opts.rankBy) : -1;
+            if (idx < 0) {
+                strategy = 'full';
+                break;
+            }
+            const q = opts.strategy === 'p95_tail' ? 0.95 : 0.99;
+            const { kept } = pickQuantileTail(rows, idx, q);
+            compressedRows = kept;
+            samplingNotes.set(opts.rankBy, `${opts.strategy} on ${opts.rankBy}`);
+            break;
+        }
+        case 'random': {
+            const prng = makePrng(opts.randomSeed ?? 1);
+            const indices = rows.map((_, i) => i);
+            // Fisher-Yates partial shuffle to sample topK rows reproducibly.
+            for (let i = 0; i < Math.min(topK, indices.length); i++) {
+                const j = i + Math.floor(prng() * (indices.length - i));
+                [indices[i], indices[j]] = [indices[j], indices[i]];
+            }
+            compressedRows = indices.slice(0, topK).map(i => rows[i]);
+            break;
+        }
+        case 'cuj_window': {
+            const tsCol = opts.timestampColumn ?? 'ts';
+            const tsIdx = indexOfColumn(columns, tsCol);
+            if (tsIdx < 0 || !opts.window) {
+                strategy = 'full';
+                break;
+            }
+            compressedRows = rows.filter(r => {
+                const t = Number(r[tsIdx]);
+                return t >= opts.window.startNs && t < opts.window.endNs;
+            });
+            samplingNotes.set(tsCol, `cuj_window [${opts.window.startNs}, ${opts.window.endNs})`);
+            break;
+        }
+        case 'cluster_representative': {
+            const idx = opts.rankBy ? indexOfColumn(columns, opts.rankBy) : -1;
+            if (idx < 0) {
+                strategy = 'full';
+                break;
+            }
+            const clusterCount = opts.clusterCount ?? topK;
+            const result = clusterRepresentatives(rows, idx, clusterCount);
+            compressedRows = result.kept;
+            representativeIndices = result.representativeIndices;
+            samplingNotes.set(opts.rankBy, `cluster representative on ${opts.rankBy}`);
+            break;
+        }
+        default:
+            strategy = 'full';
+            compressedRows = rows.slice();
+    }
+    const compressedRowCount = compressedRows.length;
+    // Codex round 8: only stamp window/range when the cuj_window strategy
+    // actually filtered the rows. If we fell back to 'full' (missing
+    // timestamp column or missing window), recording the window would
+    // mislead consumers into treating an unfiltered artifact as bounded.
+    const windowApplied = strategy === 'cuj_window' && opts.window !== undefined;
+    const compression = {
+        strategy,
+        originalRowCount,
+        compressedRowCount,
+        ratio: originalRowCount > 0 ? compressedRowCount / originalRowCount : 0,
+        ...(windowApplied ? { window: opts.window } : {}),
+        ...(strategy === 'top_k' ? { topK } : {}),
+        ...(strategy === 'random' ? { randomSeed: opts.randomSeed ?? 1 } : {}),
+    };
+    const enrichedColumns = columns.map(c => ({
+        ...c,
+        ...(samplingNotes.has(c.name)
+            ? { samplingNote: samplingNotes.get(c.name) }
+            : {}),
+    }));
+    const contract = {
+        ...(0, sparkContracts_1.makeSparkProvenance)({ source: 'artifact-compression' }),
+        artifactId,
+        columns: enrichedColumns,
+        compression,
+        ...(windowApplied ? { range: opts.window } : {}),
+        ...(opts.rankBy ? { rankBy: opts.rankBy } : {}),
+        ...(representativeIndices ? { clusterRepresentatives: representativeIndices } : {}),
+        coverage: [
+            { sparkId: 24, planId: '04', status: strategy === 'cuj_window' ? 'implemented' : 'scaffolded' },
+            { sparkId: 25, planId: '04', status: strategy === 'cluster_representative' ? 'implemented' : 'scaffolded' },
+            { sparkId: 26, planId: '04', status: ['top_k', 'p95_tail', 'p99_tail', 'random'].includes(strategy) ? 'implemented' : 'scaffolded' },
+            { sparkId: 28, planId: '04', status: 'implemented', note: 'Schema-aware columns + sampling notes preserved.' },
+        ],
+    };
+    return { compressedRows, contract };
+}
+//# sourceMappingURL=artifactCompression.js.map

package/dist/services/artifactCompression.js.map

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

package/dist/services/baselineDiffer.d.ts

@@ -0,0 +1,85 @@
+/**
+ * BaselineDiffer — pure functions that compute `BaselineDiffArtifact`
+ * and `RegressionGateResult` from a baseline plus a candidate
+ * (another baseline or a per-trace metric summary).
+ *
+ * Plan 50 M1 scope (this file):
+ * - `computeBaselineDiff(base, candidate, opts?)` — per-metric deltas
+ *   with explicit `unsupportedReason` for the missing-data paths
+ *   Codex round 1 P1#4 enumerated (missing on candidate, both
+ *   unsupported, sample below threshold, divide-by-zero).
+ * - `evaluateRegressionGate(baselineId, diff, rules, opts?)` — apply
+ *   threshold rules to a diff. Skipped gates carry `skipReason` and
+ *   omit `diff` per the §4.1 contract.
+ *
+ * Out of scope:
+ * - GitHub / IM integration (§4.1 explicitly says "CI dry-run mode,
+ *   no GitHub" for M1).
+ * - MCP tool registration — `lookup_baseline` / `compare_to_baseline`
+ *   land in M2.
+ *
+ * @module baselineDiffer
+ */
+import { type BaselineMetric, type BaselineRecord, type BaselineDiffArtifact, type RegressionGateResult } from '../types/sparkContracts';
+/** Trace-side counterpart to BaselineRecord: just the metrics, plus an
+ * id pointer so the differ can record which trace was compared. The
+ * caller (skill or pre-aggregated source) owns metric extraction; the
+ * differ stays trace-agnostic. */
+export interface TraceMetricSummary {
+    kind: 'trace';
+    traceId: string;
+    metrics: BaselineMetric[];
+}
+export type DiffCandidate = BaselineRecord | TraceMetricSummary;
+export interface DiffOptions {
+    /** Below this absolute fractional delta the severity stays 'none'. */
+    noneThresholdPct?: number;
+    /** Above this fractional delta the severity becomes 'warning'. */
+    warningThresholdPct?: number;
+    /** Above this fractional delta the severity becomes 'regression'. */
+    regressionThresholdPct?: number;
+    /** Both sides need at least this many samples; below → unsupported. */
+    minSampleCount?: number;
+    /**
+     * If true, a metric missing on the base is reported as 'unsupported'
+     * with a clear reason; if false the metric is silently skipped.
+     * Defaults to true so missing data stays visible.
+     */
+    reportMissingOnBase?: boolean;
+}
+/**
+ * Compute the diff between `base` and `candidate`. The diff covers
+ * every metricId present on either side; missing-data paths are
+ * surfaced as `severity: 'unsupported'` with a concrete reason rather
+ * than silently skipped or zero-filled.
+ */
+export declare function computeBaselineDiff(base: BaselineRecord, candidate: DiffCandidate, opts?: DiffOptions): BaselineDiffArtifact;
+/** Threshold rule for the regression gate. Applied per metric. */
+export interface RegressionRule {
+    metricId: string;
+    /** Maximum allowed absolute fractional delta. 0.10 == 10%. */
+    threshold: number;
+    /** When true the gate fails if `deltaPct > threshold` (default).
+     * When false (e.g. for "must-decrease" metrics) the gate fails
+     * when `deltaPct < -threshold`. */
+    expectIncrease?: boolean;
+}
+export interface GateOptions {
+    /** Stable id surfaced on the result. Required for audit. */
+    gateId: string;
+    /** Skip the gate with this reason instead of evaluating rules. */
+    skipReason?: string;
+}
+/**
+ * Apply threshold rules to a precomputed diff. Returns a
+ * `RegressionGateResult` whose `status` is `'skipped'` when
+ * `opts.skipReason` is set (the diff is intentionally omitted in that
+ * case, per the §4.1 contract).
+ *
+ * `'fail'` when any rule's threshold is breached. `'flaky'` when no
+ * rule is breached but at least one delta is `'unsupported'` —
+ * surfaces the gate's lack of confidence rather than passing silently.
+ * `'pass'` otherwise.
+ */
+export declare function evaluateRegressionGate(baselineId: string, diff: BaselineDiffArtifact, rules: RegressionRule[], opts: GateOptions): RegressionGateResult;
+//# sourceMappingURL=baselineDiffer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"baselineDiffer.d.ts","sourceRoot":"","sources":["../../src/services/baselineDiffer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EAEzB,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AAEjC;;;kCAGkC;AAClC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAShE,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAwKD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,aAAa,EACxB,IAAI,GAAE,WAAgB,GACrB,oBAAoB,CA2CtB;AAED,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB;;uCAEmC;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,oBAAoB,EAC1B,KAAK,EAAE,cAAc,EAAE,EACvB,IAAI,EAAE,WAAW,GAChB,oBAAoB,CAmDtB"}