@gracker/smartperfetto 1.0.13

package/dist/services/baselineDiffer.js

@@ -0,0 +1,287 @@
+"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.computeBaselineDiff = computeBaselineDiff;
+exports.evaluateRegressionGate = evaluateRegressionGate;
+/**
+ * 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
+ */
+const sparkContracts_1 = require("../types/sparkContracts");
+/** Default thresholds tuned for percent deltas. Callers can override
+ * per-call via `DiffOptions`. */
+const DEFAULT_NONE_THRESHOLD_PCT = 0.005; // 0.5% — counts as "none"
+const DEFAULT_WARNING_THRESHOLD_PCT = 0.05; // 5% — bumps to "warning"
+const DEFAULT_REGRESSION_THRESHOLD_PCT = 0.15; // 15% — flags "regression"
+const DEFAULT_MIN_SAMPLE_COUNT = 3; // mirrors BASELINE_PUBLISH_MIN_SAMPLES
+function resolve(opts) {
+    return {
+        noneThresholdPct: opts.noneThresholdPct ?? DEFAULT_NONE_THRESHOLD_PCT,
+        warningThresholdPct: opts.warningThresholdPct ?? DEFAULT_WARNING_THRESHOLD_PCT,
+        regressionThresholdPct: opts.regressionThresholdPct ?? DEFAULT_REGRESSION_THRESHOLD_PCT,
+        minSampleCount: opts.minSampleCount ?? DEFAULT_MIN_SAMPLE_COUNT,
+        reportMissingOnBase: opts.reportMissingOnBase ?? true,
+    };
+}
+/** Pull the central-tendency value used for diff arithmetic. The schema
+ * exposes median / p95 / p99 / max — the diff focuses on `median`
+ * because that's the most stable summary across capture variability.
+ * If a future caller wants a percentile-aware diff this function
+ * generalizes to a strategy. */
+function pickRepresentativeValue(metric) {
+    return metric.median;
+}
+/** Compute the percent change from `base` to `candidate`. Returns null
+ * (signaling divide-by-zero) when `base` is exactly 0. */
+function percentDelta(base, candidate) {
+    if (base === 0)
+        return null;
+    return (candidate - base) / Math.abs(base);
+}
+/** Classify a percent delta into a severity bucket. */
+function classifySeverity(deltaPct, resolved) {
+    const abs = Math.abs(deltaPct);
+    if (abs <= resolved.noneThresholdPct)
+        return 'none';
+    // Negative deltas are improvements — counts as 'info' regardless of
+    // magnitude. Don't flag improvements as regressions.
+    if (deltaPct < 0)
+        return 'info';
+    if (abs >= resolved.regressionThresholdPct)
+        return 'regression';
+    if (abs >= resolved.warningThresholdPct)
+        return 'warning';
+    return 'none';
+}
+/** Build one delta. Encapsulates the four unsupported paths:
+ *  1. metric.unsupportedReason set on either side
+ *  2. sample count below minimum on either side
+ *  3. divide-by-zero (baseValue exactly 0)
+ *  4. unit mismatch (operator probably mis-keyed metricId)
+ */
+function buildDelta(base, candidate, metricId, unit, resolved) {
+    if (!base && !candidate) {
+        // Caller asked for a metric absent from both — surface it.
+        return {
+            metricId,
+            unit,
+            severity: 'unsupported',
+            unsupportedReason: 'metric missing on both sides',
+        };
+    }
+    if (!base) {
+        return {
+            metricId,
+            unit,
+            severity: 'unsupported',
+            unsupportedReason: 'metric missing on baseline',
+            candidateValue: candidate ? pickRepresentativeValue(candidate) : undefined,
+        };
+    }
+    if (!candidate) {
+        return {
+            metricId,
+            unit,
+            severity: 'unsupported',
+            unsupportedReason: 'metric missing on candidate',
+            baseValue: pickRepresentativeValue(base),
+        };
+    }
+    if (base.unsupportedReason || candidate.unsupportedReason) {
+        return {
+            metricId,
+            unit,
+            severity: 'unsupported',
+            unsupportedReason: base.unsupportedReason ?? candidate.unsupportedReason,
+        };
+    }
+    if (base.unit !== candidate.unit) {
+        return {
+            metricId,
+            unit,
+            severity: 'unsupported',
+            unsupportedReason: `unit mismatch: base='${base.unit}' candidate='${candidate.unit}'`,
+        };
+    }
+    const baseSamples = base.sampleCount;
+    const candSamples = candidate.sampleCount;
+    if (baseSamples < resolved.minSampleCount ||
+        candSamples < resolved.minSampleCount) {
+        return {
+            metricId,
+            unit,
+            severity: 'unsupported',
+            unsupportedReason: `sample count below minimum (${resolved.minSampleCount}); base=${baseSamples} candidate=${candSamples}`,
+            baseValue: pickRepresentativeValue(base),
+            candidateValue: pickRepresentativeValue(candidate),
+        };
+    }
+    const baseValue = pickRepresentativeValue(base);
+    const candidateValue = pickRepresentativeValue(candidate);
+    const pct = percentDelta(baseValue, candidateValue);
+    if (pct === null) {
+        return {
+            metricId,
+            unit,
+            severity: 'unsupported',
+            unsupportedReason: 'divide-by-zero (baseValue is 0)',
+            baseValue,
+            candidateValue,
+        };
+    }
+    return {
+        metricId,
+        unit,
+        severity: classifySeverity(pct, resolved),
+        baseValue,
+        candidateValue,
+        deltaAbs: candidateValue - baseValue,
+        deltaPct: pct,
+    };
+}
+/** Index a metric array by `metricId` for O(1) lookup. */
+function indexMetrics(metrics) {
+    const out = new Map();
+    for (const m of metrics)
+        out.set(m.metricId, m);
+    return out;
+}
+/** Get the candidate id descriptor for the diff artifact. */
+function describeCandidate(candidate) {
+    if ('kind' in candidate && candidate.kind === 'trace') {
+        return { kind: 'trace', traceId: candidate.traceId };
+    }
+    return { kind: 'baseline', id: candidate.baselineId };
+}
+/**
+ * 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.
+ */
+function computeBaselineDiff(base, candidate, opts = {}) {
+    const resolved = resolve(opts);
+    const baseIndex = indexMetrics(base.metrics);
+    const candidateIndex = indexMetrics('kind' in candidate && candidate.kind === 'trace'
+        ? candidate.metrics
+        : candidate.metrics);
+    const allIds = new Set();
+    for (const id of baseIndex.keys())
+        allIds.add(id);
+    for (const id of candidateIndex.keys())
+        allIds.add(id);
+    const deltas = [];
+    for (const metricId of Array.from(allIds).sort()) {
+        const baseMetric = baseIndex.get(metricId);
+        const candMetric = candidateIndex.get(metricId);
+        // When the metric appears on only one side, we still need a unit
+        // string for the delta; pick whichever side is populated.
+        const unit = baseMetric?.unit ?? candMetric?.unit ?? '';
+        const skipMissingBase = !baseMetric && candMetric && !resolved.reportMissingOnBase;
+        if (skipMissingBase)
+            continue;
+        deltas.push(buildDelta(baseMetric, candMetric, metricId, unit, resolved));
+    }
+    // Top regressions: rank actual regressions (severity='regression')
+    // by absolute deltaPct, descending.
+    const topRegressions = deltas
+        .filter(d => d.severity === 'regression' && typeof d.deltaPct === 'number')
+        .sort((a, b) => Math.abs(b.deltaPct) - Math.abs(a.deltaPct))
+        .slice(0, 5)
+        .map(d => ({ metricId: d.metricId, deltaPct: d.deltaPct }));
+    return {
+        ...(0, sparkContracts_1.makeSparkProvenance)({ source: 'baselineDiffer.computeBaselineDiff' }),
+        baseBaselineId: base.baselineId,
+        candidate: describeCandidate(candidate),
+        deltas,
+        ...(topRegressions.length ? { topRegressions } : {}),
+    };
+}
+/**
+ * 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.
+ */
+function evaluateRegressionGate(baselineId, diff, rules, opts) {
+    if (opts.skipReason) {
+        return {
+            ...(0, sparkContracts_1.makeSparkProvenance)({ source: 'baselineDiffer.evaluateRegressionGate' }),
+            gateId: opts.gateId,
+            baselineId,
+            status: 'skipped',
+            skipReason: opts.skipReason,
+        };
+    }
+    const deltaIndex = indexMetricsByDelta(diff.deltas);
+    let triggeredRule;
+    let sawUnsupported = false;
+    for (const rule of rules) {
+        const delta = deltaIndex.get(rule.metricId);
+        if (!delta)
+            continue;
+        if (delta.severity === 'unsupported') {
+            sawUnsupported = true;
+            continue;
+        }
+        if (typeof delta.deltaPct !== 'number')
+            continue;
+        const expectIncrease = rule.expectIncrease ?? true;
+        const breached = expectIncrease
+            ? delta.deltaPct > rule.threshold
+            : delta.deltaPct < -rule.threshold;
+        if (breached) {
+            triggeredRule = {
+                metricId: rule.metricId,
+                threshold: rule.threshold,
+                observed: delta.deltaPct,
+            };
+            break;
+        }
+    }
+    const status = triggeredRule
+        ? 'fail'
+        : sawUnsupported
+            ? 'flaky'
+            : 'pass';
+    return {
+        ...(0, sparkContracts_1.makeSparkProvenance)({ source: 'baselineDiffer.evaluateRegressionGate' }),
+        gateId: opts.gateId,
+        baselineId,
+        status,
+        diff,
+        ...(triggeredRule ? { rule: triggeredRule } : {}),
+    };
+}
+function indexMetricsByDelta(deltas) {
+    const out = new Map();
+    for (const d of deltas)
+        out.set(d.metricId, d);
+    return out;
+}
+//# sourceMappingURL=baselineDiffer.js.map

package/dist/services/baselineDiffer.js.map

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

package/dist/services/baselineStore.d.ts

@@ -0,0 +1,52 @@
+import { type BaselineRecord, type PerfBaselineKey } from '../types/sparkContracts';
+import { type KnowledgeScope } from './scopedKnowledgeStore';
+/** Minimum sample count enforced for `status='published'`. */
+export declare const BASELINE_PUBLISH_MIN_SAMPLES = 3;
+/** Whether the key looks like it carries raw identifiable info. */
+export declare function keyHasIdentifiableInfo(key: PerfBaselineKey): boolean;
+/** Derive the canonical baselineId from a key. */
+export declare function deriveBaselineId(key: PerfBaselineKey): string;
+export interface BaselineStoreListOptions {
+    /** Restrict to a single status (e.g. 'published' for read-only consumers). */
+    status?: BaselineRecord['status'];
+    /** Restrict to a key prefix, e.g. `${appId}/${deviceId}` for cross-build trends. */
+    keyPrefix?: string;
+}
+/**
+ * BaselineStore — local file-backed baseline storage. Single instance
+ * per storage path is enough for M0; cross-process writers are not
+ * supported (caller's responsibility).
+ */
+export declare class BaselineStore {
+    private readonly storagePath;
+    private readonly baselines;
+    private loaded;
+    constructor(storagePath: string);
+    /** Idempotently load the on-disk store into memory. */
+    load(): void;
+    /**
+     * Add or replace a baseline record. Validates the publish invariants
+     * before writing — invalid records throw rather than silently
+     * downgrading status, so the operator sees the failure.
+     */
+    addBaseline(record: BaselineRecord, scope?: KnowledgeScope): void;
+    /** Get a baseline by id. */
+    getBaseline(baselineId: string, scope?: KnowledgeScope): BaselineRecord | undefined;
+    /** Remove a baseline. Returns whether anything was actually removed. */
+    removeBaseline(baselineId: string, scope?: KnowledgeScope): boolean;
+    /**
+     * List baselines with optional filters. Results are stable-ordered
+     * by baselineId for deterministic consumers.
+     */
+    listBaselines(opts?: BaselineStoreListOptions, scope?: KnowledgeScope): BaselineRecord[];
+    /**
+     * Validate the §4.1 publish invariants. Throws when violated so the
+     * caller surfaces the cause to the operator instead of silently
+     * downgrading the record's status.
+     */
+    private assertPublishInvariants;
+    /** Atomic write: temp file + rename so a crashed process leaves the
+     * existing on-disk file intact. */
+    private persist;
+}
+//# sourceMappingURL=baselineStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"baselineStore.d.ts","sourceRoot":"","sources":["../../src/services/baselineStore.ts"],"names":[],"mappings":"AA+BA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAIL,KAAK,cAAc,EAKpB,MAAM,wBAAwB,CAAC;AAEhC,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,IAAI,CAAC;AA4B9C,mEAAmE;AACnE,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAKpE;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAE7D;AAED,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAClC,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,MAAM,CAAS;gBAEX,WAAW,EAAE,MAAM;IAI/B,uDAAuD;IACvD,IAAI,IAAI,IAAI;IAkBZ;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI;IAmBjE,4BAA4B;IAC5B,WAAW,CACT,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,cAAc,GACrB,cAAc,GAAG,SAAS;IAY7B,wEAAwE;IACxE,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,OAAO;IAcnE;;;OAGG;IACH,aAAa,CACX,IAAI,GAAE,wBAA6B,EACnC,KAAK,CAAC,EAAE,cAAc,GACrB,cAAc,EAAE;IAoBnB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAoB/B;uCACmC;IACnC,OAAO,CAAC,OAAO;CAYhB"}

package/dist/services/baselineStore.js

@@ -0,0 +1,224 @@
+"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.BaselineStore = exports.BASELINE_PUBLISH_MIN_SAMPLES = void 0;
+exports.keyHasIdentifiableInfo = keyHasIdentifiableInfo;
+exports.deriveBaselineId = deriveBaselineId;
+/**
+ * BaselineStore — durable App/Device/Build/CUJ baseline storage with
+ * curation lifecycle and publish gates.
+ *
+ * Plan 50 M0 scope (this file):
+ * - Add / get / remove / list `BaselineRecord` with JSON persistence
+ *   (atomic temp+rename, schemaVersion 1).
+ * - Service-layer invariants the schema does NOT enforce so older
+ *   snapshots remain readable:
+ *     - `status='published'` requires `sampleCount >= 3` (§4.1).
+ *     - `status='published'` requires `redactionState='redacted'` whenever
+ *       the key carries identifiable info (raw appId / deviceId);
+ *       pre-anonymized keys can publish with `redactionState='raw'`.
+ * - Stable canonical `baselineId` derivation:
+ *   `${appId}/${deviceId}/${buildId}/${cuj}`.
+ *
+ * Out of scope here (M1 / M2):
+ * - Diff and regression-gate computation (`baselineDiffer.ts`).
+ * - MCP tool registration (`lookup_baseline`, `compare_to_baseline`).
+ * - Express CRUD route.
+ *
+ * @module baselineStore
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const scopedKnowledgeStore_1 = require("./scopedKnowledgeStore");
+/** Minimum sample count enforced for `status='published'`. */
+exports.BASELINE_PUBLISH_MIN_SAMPLES = 3;
+const KNOWLEDGE_KIND = 'baseline';
+const BASELINE_ROW_SCOPE = 'baseline';
+/** Normalize an appId or deviceId to detect when it carries
+ * identifiable raw info. Heuristic: package-style ids
+ * (`com.example.feed`) or model+os fingerprints (`pixel-9-android-15`)
+ * count as identifiable; placeholder strings starting with `anon-` or
+ * `redacted-` count as already anonymized. The gate is intentionally
+ * conservative — a false positive (re-redacting an already anonymized
+ * key) is harmless; a false negative would leak. */
+function isIdentifiableComponent(value) {
+    const v = value.trim().toLowerCase();
+    if (!v)
+        return false;
+    if (v.startsWith('anon-'))
+        return false;
+    if (v.startsWith('redacted-'))
+        return false;
+    if (v.startsWith('placeholder-'))
+        return false;
+    return true;
+}
+/** Whether the key looks like it carries raw identifiable info. */
+function keyHasIdentifiableInfo(key) {
+    return (isIdentifiableComponent(key.appId) ||
+        isIdentifiableComponent(key.deviceId));
+}
+/** Derive the canonical baselineId from a key. */
+function deriveBaselineId(key) {
+    return `${key.appId}/${key.deviceId}/${key.buildId}/${key.cuj}`;
+}
+/**
+ * BaselineStore — local file-backed baseline storage. Single instance
+ * per storage path is enough for M0; cross-process writers are not
+ * supported (caller's responsibility).
+ */
+class BaselineStore {
+    constructor(storagePath) {
+        this.baselines = new Map();
+        this.loaded = false;
+        this.storagePath = storagePath;
+    }
+    /** Idempotently load the on-disk store into memory. */
+    load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        if (!fs.existsSync(this.storagePath))
+            return;
+        try {
+            const raw = fs.readFileSync(this.storagePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed.schemaVersion !== 1 || !Array.isArray(parsed.baselines)) {
+                return;
+            }
+            for (const b of parsed.baselines) {
+                this.baselines.set(b.baselineId, b);
+            }
+        }
+        catch {
+            // Corrupted JSON: empty cache, file preserved for inspection.
+        }
+    }
+    /**
+     * Add or replace a baseline record. Validates the publish invariants
+     * before writing — invalid records throw rather than silently
+     * downgrading status, so the operator sees the failure.
+     */
+    addBaseline(record, scope) {
+        this.load();
+        this.assertPublishInvariants(record);
+        if ((0, scopedKnowledgeStore_1.legacyKnowledgeFilesystemWritesEnabled)()) {
+            this.baselines.set(record.baselineId, record);
+            this.persist();
+        }
+        if ((0, scopedKnowledgeStore_1.enterpriseKnowledgeDbWritesEnabled)()) {
+            (0, scopedKnowledgeStore_1.upsertScopedKnowledgeRecord)(KNOWLEDGE_KIND, record.baselineId, BASELINE_ROW_SCOPE, record, scope, { createdAt: record.capturedAt, updatedAt: Date.now() });
+        }
+    }
+    /** Get a baseline by id. */
+    getBaseline(baselineId, scope) {
+        if ((0, scopedKnowledgeStore_1.enterpriseKnowledgeStoreEnabled)()) {
+            return (0, scopedKnowledgeStore_1.getScopedKnowledgeRecord)(KNOWLEDGE_KIND, baselineId, scope)?.record;
+        }
+        this.load();
+        return this.baselines.get(baselineId);
+    }
+    /** Remove a baseline. Returns whether anything was actually removed. */
+    removeBaseline(baselineId, scope) {
+        let removed = false;
+        if ((0, scopedKnowledgeStore_1.enterpriseKnowledgeDbWritesEnabled)()) {
+            removed = (0, scopedKnowledgeStore_1.removeScopedKnowledgeRecord)(KNOWLEDGE_KIND, baselineId, scope) || removed;
+        }
+        if ((0, scopedKnowledgeStore_1.legacyKnowledgeFilesystemWritesEnabled)()) {
+            this.load();
+            const had = this.baselines.delete(baselineId);
+            if (had)
+                this.persist();
+            removed = had || removed;
+        }
+        return removed;
+    }
+    /**
+     * List baselines with optional filters. Results are stable-ordered
+     * by baselineId for deterministic consumers.
+     */
+    listBaselines(opts = {}, scope) {
+        this.load();
+        let out = (0, scopedKnowledgeStore_1.enterpriseKnowledgeStoreEnabled)()
+            ? (0, scopedKnowledgeStore_1.listScopedKnowledgeRecords)(KNOWLEDGE_KIND, scope, { rowScope: BASELINE_ROW_SCOPE }).map(row => row.record)
+            : Array.from(this.baselines.values());
+        if (opts.status) {
+            out = out.filter(b => b.status === opts.status);
+        }
+        if (opts.keyPrefix) {
+            const prefix = opts.keyPrefix;
+            out = out.filter(b => b.baselineId.startsWith(prefix));
+        }
+        out.sort((a, b) => a.baselineId.localeCompare(b.baselineId));
+        return out;
+    }
+    /**
+     * Validate the §4.1 publish invariants. Throws when violated so the
+     * caller surfaces the cause to the operator instead of silently
+     * downgrading the record's status.
+     */
+    assertPublishInvariants(record) {
+        if (record.status !== 'published')
+            return;
+        const sampleCount = record.sampleCount ?? 0;
+        if (sampleCount < exports.BASELINE_PUBLISH_MIN_SAMPLES) {
+            throw new Error(`Baseline '${record.baselineId}' cannot be published with sampleCount=${sampleCount} (minimum ${exports.BASELINE_PUBLISH_MIN_SAMPLES})`);
+        }
+        if (keyHasIdentifiableInfo(record.key) &&
+            record.redactionState !== 'redacted') {
+            throw new Error(`Baseline '${record.baselineId}' cannot be published with redactionState='${record.redactionState}' — key carries identifiable info`);
+        }
+    }
+    /** Atomic write: temp file + rename so a crashed process leaves the
+     * existing on-disk file intact. */
+    persist() {
+        const dir = path.dirname(this.storagePath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        // Per-process unique tmp suffix — Codex round E P1#5.
+        const tmp = `${this.storagePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+        const envelope = {
+            schemaVersion: 1,
+            baselines: Array.from(this.baselines.values()),
+        };
+        fs.writeFileSync(tmp, JSON.stringify(envelope, null, 2), 'utf-8');
+        fs.renameSync(tmp, this.storagePath);
+    }
+}
+exports.BaselineStore = BaselineStore;
+//# sourceMappingURL=baselineStore.js.map

package/dist/services/baselineStore.js.map

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

package/dist/services/binderRootCauseChain.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Binder Victim → Server Root-cause Chain (Spark Plan 12)
+ *
+ * Joins client-side and server-side binder transactions and walks the chain
+ * back to the deepest blocker, producing a `BinderRootCauseChainContract`.
+ *
+ * Inputs are deliberately minimal: a flat list of hops keyed by transaction
+ * id, plus per-hop `blockedOn` strings the caller derives from
+ * thread_state aggregations. The walker just sequences hops and picks the
+ * leaf when one exists; otherwise it marks the chain truncated rather than
+ * inventing a root cause.
+ */
+import { type BinderRootCauseChainContract } from '../types/sparkContracts';
+export interface BinderHopInput {
+    step: number;
+    side: 'client' | 'server';
+    pid: number;
+    tid: number;
+    process?: string;
+    thread?: string;
+    method?: string;
+    startNs: number;
+    endNs: number;
+    blockedOn?: string;
+    evidenceArtifactId?: string;
+}
+export interface BuildBinderChainOptions {
+    victim: BinderHopInput;
+    /** Server-side hops in step order (closest hop first). */
+    chain: BinderHopInput[];
+}
+/**
+ * Build the full chain. The deepest hop becomes `rootCause`; if every hop
+ * is blocked on something but there is still a downstream hop pending,
+ * the contract is marked truncated.
+ */
+export declare function buildBinderRootCauseChain(options: BuildBinderChainOptions): BinderRootCauseChainContract;
+//# sourceMappingURL=binderRootCauseChain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"binderRootCauseChain.d.ts","sourceRoot":"","sources":["../../src/services/binderRootCauseChain.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAGL,KAAK,4BAA4B,EAClC,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,cAAc,CAAC;IACvB,0DAA0D;IAC1D,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAmBD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,uBAAuB,GAC/B,4BAA4B,CAiC9B"}