@ashlr/hub 2.2.0

package/dist/core/learn/reflect.js

@@ -0,0 +1,435 @@
+/**
+ * reflect.ts — M26 deterministic reflection metrics engine.
+ *
+ * Scores the org's OWN past swarms/usage/genome and computes a ReflectionReport:
+ * success rate, avg cost & tokens per swarm, local-vs-cloud share, clustered
+ * top failure modes, slowest/most-expensive goal categories, and week-over-week
+ * deltas vs the prior persisted snapshot.
+ *
+ * HARD SAFETY INVARIANTS (M26):
+ *  1. READ-ONLY over history. Reads listSwarms() / genomeHubHealth /
+ *     collectUsageEvents() ONLY — the HUB-ONLY genome reader (no portfolio
+ *     disk scan). Writes nothing here (the CLI persists the snapshot via
+ *     learn/store.ts under ~/.ashlr/learn/).
+ *  2. NO TUNING. This module never proposes or applies anything — pure metrics.
+ *  3. LOCAL-FIRST / NO LLM. buildReflection is DETERMINISTIC and makes ZERO
+ *     network connections. No getActiveClient, no fetch. Narrative generation
+ *     lives in playbooks.ts, never here.
+ *  4. BOUNDED. Reads at most `maxRuns` recent swarms (default DEFAULT_MAX_RUNS)
+ *     and/or those within `sinceMs`. listSwarms() is itself capped at 200.
+ *  5. NEVER THROWS. Degrades to a zeroed report on any failure.
+ *
+ * METADATA ONLY — never reads/retains secret values or raw code/payloads.
+ */
+import { listSwarms } from '../swarm/store.js';
+import { genomeHubHealth } from '../genome/store.js';
+import { collectUsageEvents } from '../observability/usage-source.js';
+import { isLocalProviderModel } from '../observability/rollup.js';
+import { loadPreviousReport } from './store.js';
+// ---------------------------------------------------------------------------
+// Bounds
+// ---------------------------------------------------------------------------
+/** Default cap on how many recent swarms to analyze (bounds work). */
+export const DEFAULT_MAX_RUNS = 100;
+/**
+ * Default usage-window lookback (ms) applied when NO --since window is given.
+ * Bounds collectUsageEvents() so the default path never streams the entire
+ * historical transcript corpus — it matches the report's week-over-week
+ * framing. `--since all` (sinceMs explicitly 0) is the opt-in to scan all
+ * history (still bounded by the per-file caps in usage-source.ts).
+ */
+export const DEFAULT_USAGE_LOOKBACK_MS = 30 * 86_400_000;
+/** Max distinct failure-mode clusters surfaced on a report. */
+const MAX_FAILURE_MODES = 8;
+/** Max representative swarm ids retained per failure cluster. */
+const MAX_FAILURE_EXAMPLES = 3;
+/** Coarse goal categories (keyword heuristic; deterministic). */
+const GOAL_CATEGORIES = [
+    'feature',
+    'bugfix',
+    'refactor',
+    'test',
+    'docs',
+    'chore',
+    'other',
+];
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit testing) — NO I/O, NO LLM
+// ---------------------------------------------------------------------------
+/**
+ * Bucket a swarm goal string into one coarse GOAL_CATEGORIES label using a
+ * deterministic keyword heuristic. Pure; never throws.
+ *
+ * Order matters: the first matching category wins (most-specific verbs first).
+ */
+export function classifyGoal(goal) {
+    const g = (goal ?? '').toLowerCase();
+    if (!g.trim())
+        return 'other';
+    // bugfix: fix / bug / crash / regression / hotfix
+    if (/\b(fix|fixes|fixed|bug|bugs|crash|regression|hotfix|defect|broken)\b/.test(g)) {
+        return 'bugfix';
+    }
+    // test: test / spec / coverage / vitest / jest
+    if (/\b(test|tests|testing|spec|specs|coverage|vitest|jest)\b/.test(g)) {
+        return 'test';
+    }
+    // docs: doc / readme / comment / changelog
+    if (/\b(doc|docs|document|documentation|readme|changelog|comment|comments)\b/.test(g)) {
+        return 'docs';
+    }
+    // refactor: refactor / cleanup / rename / restructure / simplify
+    if (/\b(refactor|refactors|refactoring|cleanup|clean-up|rename|restructure|simplify|tidy|dedupe)\b/.test(g)) {
+        return 'refactor';
+    }
+    // chore: chore / bump / deps / config / ci / lint / format / upgrade
+    if (/\b(chore|bump|deps|dependency|dependencies|config|ci|lint|format|upgrade|version)\b/.test(g)) {
+        return 'chore';
+    }
+    // feature: add / implement / build / create / feature / support / new
+    if (/\b(feature|features|add|adds|implement|implements|build|create|support|introduce|new)\b/.test(g)) {
+        return 'feature';
+    }
+    // GOAL_CATEGORIES is the single source of truth for the valid labels; the
+    // fallthrough returns the final ('other') bucket from it.
+    return GOAL_CATEGORIES[GOAL_CATEGORIES.length - 1];
+}
+/**
+ * Normalize a raw task.error string into a stable cluster key (lowercase,
+ * stripped of ids/paths/numbers/hashes) so similar errors cluster together.
+ * Pure; never throws.
+ */
+export function normalizeErrorKey(error) {
+    if (typeof error !== 'string')
+        return '';
+    let s = error.toLowerCase().trim();
+    if (!s)
+        return '';
+    // Strip uuids first (more specific than the generic hash rule below).
+    s = s.replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/g, '<uuid>');
+    // Strip absolute/relative paths to a placeholder.
+    s = s.replace(/(?:\/[\w.\-@]+)+/g, ' <path> ');
+    // Strip hex hashes.
+    s = s.replace(/\b[0-9a-f]{8,}\b/g, '<hash>');
+    // Strip standalone numbers (line/col/byte counts, ports, durations).
+    s = s.replace(/\b\d+(?:\.\d+)?(?:ms|s)?\b/g, '<n>');
+    // Strip quoted identifiers so 'foo'/"bar" don't fragment the cluster.
+    s = s.replace(/['"`][^'"`]*['"`]/g, '<id>');
+    // Collapse whitespace and cap length so the key stays stable + bounded.
+    s = s.replace(/\s+/g, ' ').trim();
+    return s.slice(0, 120);
+}
+/**
+ * Cluster failed tasks across swarms into the top FailureMode buckets, most
+ * frequent first, capped at MAX_FAILURE_MODES. Pure over the provided swarms;
+ * never throws.
+ */
+export function clusterFailures(swarms) {
+    const buckets = new Map();
+    try {
+        for (const s of swarms) {
+            const tasks = Array.isArray(s.tasks) ? s.tasks : [];
+            for (const t of tasks) {
+                if (t.status !== 'failed')
+                    continue;
+                const raw = (t.error ?? '').trim();
+                // Fall back to the phase name when no error string is present, so a
+                // failed task with no message still clusters by phase.
+                const key = normalizeErrorKey(raw) || `phase:${t.phase ?? 'unknown'}`;
+                const label = raw ? raw.slice(0, 100) : `failed in ${t.phase ?? 'unknown'} phase`;
+                let bucket = buckets.get(key);
+                if (!bucket) {
+                    bucket = { label, count: 0, phases: new Set(), examples: new Set() };
+                    buckets.set(key, bucket);
+                }
+                bucket.count++;
+                if (t.phase)
+                    bucket.phases.add(String(t.phase));
+                if (s.id && bucket.examples.size < MAX_FAILURE_EXAMPLES) {
+                    bucket.examples.add(s.id);
+                }
+            }
+        }
+    }
+    catch {
+        return [];
+    }
+    const modes = [];
+    for (const [key, b] of buckets) {
+        modes.push({
+            key,
+            label: b.label,
+            count: b.count,
+            phases: [...b.phases].sort(),
+            exampleSwarmIds: [...b.examples],
+        });
+    }
+    // Most frequent first; tiebreak on key for determinism.
+    modes.sort((a, b) => (b.count - a.count) || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    return modes.slice(0, MAX_FAILURE_MODES);
+}
+/** Total (in+out) tokens for a swarm's cumulative usage. Pure. */
+function swarmTokens(s) {
+    const u = s.usage;
+    if (!u)
+        return 0;
+    const ti = typeof u.tokensIn === 'number' ? u.tokensIn : 0;
+    const to = typeof u.tokensOut === 'number' ? u.tokensOut : 0;
+    return ti + to;
+}
+/** Estimated USD cost for a swarm. Pure. */
+function swarmCost(s) {
+    const c = s.usage?.estCostUsd;
+    return typeof c === 'number' && Number.isFinite(c) ? c : 0;
+}
+/**
+ * Aggregate per-goal-category cost/token/success stats over the swarms,
+ * most-expensive (avgCostUsd) first. Pure; never throws.
+ */
+export function summarizeGoalCategories(swarms) {
+    const buckets = new Map();
+    try {
+        for (const s of swarms) {
+            const cat = classifyGoal(s.goal ?? '');
+            let b = buckets.get(cat);
+            if (!b) {
+                b = { swarms: 0, cost: 0, tokens: 0, done: 0 };
+                buckets.set(cat, b);
+            }
+            b.swarms++;
+            b.cost += swarmCost(s);
+            b.tokens += swarmTokens(s);
+            if (s.status === 'done')
+                b.done++;
+        }
+    }
+    catch {
+        return [];
+    }
+    const stats = [];
+    for (const [category, b] of buckets) {
+        if (b.swarms === 0)
+            continue;
+        stats.push({
+            category,
+            swarms: b.swarms,
+            avgCostUsd: b.cost / b.swarms,
+            avgTokens: b.tokens / b.swarms,
+            successRate: b.done / b.swarms,
+        });
+    }
+    // Most-expensive first; tiebreak on category for determinism.
+    stats.sort((a, b) => b.avgCostUsd - a.avgCostUsd ||
+        (a.category < b.category ? -1 : a.category > b.category ? 1 : 0));
+    return stats;
+}
+/**
+ * Compute week-over-week deltas vs a prior snapshot. Pure; never throws.
+ * When `previous` is null, returns a no-prior delta (all numeric fields null).
+ *
+ * `currentWindow` (the window/scope label of the CURRENT report) is compared
+ * against `previous.window`. When they differ, the metrics were computed over
+ * DIFFERENT populations, so the headline is annotated '(windows differ)' to
+ * flag that the delta is apples-to-oranges. Omitting it (or passing the same
+ * label) leaves the headline unannotated.
+ */
+export function computeDelta(current, previous, currentWindow) {
+    if (!previous) {
+        return {
+            previousAt: null,
+            effectivenessPct: null,
+            costPct: null,
+            localSharePct: null,
+            headline: 'No prior snapshot — this is the first reflection.',
+        };
+    }
+    const round1 = (n) => Math.round(n * 10) / 10;
+    // Effectiveness: signed percentage-POINT change of success rate.
+    const effectivenessPct = round1((current.successRate - previous.successRate) * 100);
+    // Cost: signed PERCENT change in avg cost per swarm. Guard divide-by-zero.
+    let costPct;
+    if (previous.avgCostUsd > 0) {
+        costPct = round1(((current.avgCostUsd - previous.avgCostUsd) / previous.avgCostUsd) * 100);
+    }
+    else if (current.avgCostUsd > 0) {
+        // Was free, now costs something — represent as +100% (newly non-zero).
+        costPct = 100;
+    }
+    else {
+        costPct = 0;
+    }
+    // Local share: signed percentage-POINT change.
+    const localSharePct = round1((current.localShare - previous.localShare) * 100);
+    // Only annotate when BOTH windows are known and actually differ — comparing
+    // metrics across different windows/scopes makes the delta apples-to-oranges.
+    const windowsDiffer = currentWindow !== undefined &&
+        (previous.window ?? null) !== (currentWindow ?? null);
+    const baseHeadline = composeHeadline(effectivenessPct, costPct, localSharePct);
+    const headline = windowsDiffer
+        ? `${baseHeadline} (windows differ: prior ${previous.window ?? 'all'} vs current ${currentWindow ?? 'all'})`
+        : baseHeadline;
+    return { previousAt: previous.generatedAt, effectivenessPct, costPct, localSharePct, headline };
+}
+/** Compose the deterministic week-over-week headline string. Pure. */
+function composeHeadline(effPct, costPct, localPct) {
+    const parts = [];
+    if (effPct > 0)
+        parts.push(`${effPct.toFixed(1)}% more effective`);
+    else if (effPct < 0)
+        parts.push(`${Math.abs(effPct).toFixed(1)}% less effective`);
+    else
+        parts.push('equally effective');
+    if (costPct < 0)
+        parts.push(`${Math.abs(costPct).toFixed(1)}% cheaper`);
+    else if (costPct > 0)
+        parts.push(`${costPct.toFixed(1)}% more expensive`);
+    else
+        parts.push('cost unchanged');
+    if (localPct > 0)
+        parts.push(`${localPct.toFixed(1)} pts more local`);
+    else if (localPct < 0)
+        parts.push(`${Math.abs(localPct).toFixed(1)} pts less local`);
+    return `Since the last reflection, the org got ${parts.join(', ')}.`;
+}
+// ---------------------------------------------------------------------------
+// Public: buildReflection — DETERMINISTIC, NO LLM, NO NETWORK
+// ---------------------------------------------------------------------------
+/**
+ * Build a ReflectionReport from the user's OWN local history.
+ *
+ * Reads (READ-ONLY):
+ *  - listSwarms() — capped to the most-recent `maxRuns` and/or `sinceMs` window.
+ *  - collectUsageEvents(sinceMs) — for the local-vs-cloud token share.
+ *  - genomeHubHealth — HUB-ONLY entry counts (no portfolio disk scan).
+ *
+ * Computes: success rate, avg cost & tokens per swarm, local share, top failure
+ * modes, goal-category stats, and week-over-week deltas vs loadPreviousReport().
+ *
+ * DETERMINISTIC: makes ZERO network connections and uses NO LLM. Never throws —
+ * returns a zeroed report on any failure.
+ */
+export function buildReflection(
+// cfg is retained for API compatibility (callers pass it positionally) but is
+// no longer consumed: genomeHubHealth() reads ONLY the local hub store and
+// takes no config (no portfolio walk, no embeddings probe).
+_cfg, opts = {}) {
+    const now = new Date().toISOString();
+    // Window resolution:
+    //  - opts.sinceMs === undefined  => NO explicit window: apply the bounded
+    //    DEFAULT_USAGE_LOOKBACK_MS so the default path never streams the entire
+    //    historical corpus.
+    //  - opts.sinceMs === 0          => explicit '--since all': scan all history
+    //    (the caller opted in; still bounded by usage-source's per-file caps).
+    //  - opts.sinceMs > 0            => an explicit Nd window.
+    const explicitAll = opts.sinceMs === 0;
+    const sinceMs = opts.sinceMs === undefined ? Date.now() - DEFAULT_USAGE_LOOKBACK_MS : opts.sinceMs;
+    const maxRuns = opts.maxRuns ?? DEFAULT_MAX_RUNS;
+    // --- Read swarm history (READ-ONLY, BOUNDED) ---
+    let swarms = [];
+    try {
+        const all = listSwarms(); // already capped at 200 + sorted most-recent first
+        swarms = all
+            .filter((s) => {
+            if (sinceMs <= 0)
+                return true;
+            const t = Date.parse(s.createdAt ?? '');
+            return Number.isFinite(t) ? t >= sinceMs : true;
+        })
+            .slice(0, Math.max(0, maxRuns));
+    }
+    catch {
+        swarms = [];
+    }
+    // --- Success / cost / token aggregates ---
+    let swarmsDone = 0;
+    let swarmsFailed = 0;
+    let totalCostUsd = 0;
+    let totalTokens = 0;
+    for (const s of swarms) {
+        if (s.status === 'done')
+            swarmsDone++;
+        else if (s.status === 'failed' || s.status === 'aborted')
+            swarmsFailed++;
+        totalCostUsd += swarmCost(s);
+        totalTokens += swarmTokens(s);
+    }
+    const swarmsAnalyzed = swarms.length;
+    // Success rate is computed over TERMINAL swarms only ('done'|'failed'|
+    // 'aborted'); in-flight statuses ('planning'|'running'|'needs-approval') are
+    // NOT counted as non-successes in the denominator (that would understate
+    // effectiveness and corrupt the week-over-week delta when in-flight counts
+    // differ between snapshots). swarmsAnalyzed still reports how many were read.
+    const swarmsTerminal = swarmsDone + swarmsFailed;
+    const successRate = swarmsTerminal > 0 ? swarmsDone / swarmsTerminal : 0;
+    // Cost/token averages stay over all analyzed swarms (in-flight runs still
+    // incur real spend that belongs in the per-swarm average).
+    const avgCostUsd = swarmsAnalyzed > 0 ? totalCostUsd / swarmsAnalyzed : 0;
+    const avgTokens = swarmsAnalyzed > 0 ? totalTokens / swarmsAnalyzed : 0;
+    // --- Local-vs-cloud token share from usage events (READ-ONLY) ---
+    let localShare = 0;
+    try {
+        const events = collectUsageEvents(explicitAll ? 0 : sinceMs);
+        let localTokens = 0;
+        let allTokens = 0;
+        for (const e of events) {
+            const tok = (e.tokensIn ?? 0) + (e.tokensOut ?? 0);
+            if (tok <= 0)
+                continue;
+            allTokens += tok;
+            if (isLocalProviderModel(e.model))
+                localTokens += tok;
+        }
+        localShare = allTokens > 0 ? localTokens / allTokens : 0;
+    }
+    catch {
+        localShare = 0;
+    }
+    // --- Failure clustering + goal categories (pure) ---
+    const topFailures = clusterFailures(swarms);
+    const goalCategories = summarizeGoalCategories(swarms);
+    // --- Week-over-week delta vs the prior snapshot ---
+    // currentWindow lets computeDelta annotate the headline when the prior
+    // snapshot covered a DIFFERENT window/scope (apples-to-oranges deltas).
+    const currentWindow = explicitAll ? 'all' : opts.window ?? null;
+    const delta = computeDelta({ successRate, avgCostUsd, localShare }, loadPreviousReport(now), currentWindow);
+    // --- Genome health snapshot (HUB-ONLY: no portfolio disk scan) ---
+    // Reads ONLY ~/.ashlr/genome/hub.jsonl via genomeHubHealth — it does NOT walk
+    // the configured portfolio roots, honouring invariant #4 (operate only on the
+    // user's OWN local hub history, never a portfolio disk scan).
+    let genome;
+    try {
+        genome = genomeHubHealth();
+    }
+    catch {
+        genome = {
+            totalEntries: 0,
+            projects: 0,
+            hubEntries: 0,
+            sizeBytes: 0,
+            lastLearnedAt: null,
+            embeddingsAvailable: false,
+        };
+    }
+    return {
+        generatedAt: now,
+        // Record the analysis lower bound. For '--since all' (explicitAll) there is
+        // no lower bound, so we record the sentinel 'all' rather than the Unix epoch
+        // (which would misrender as a 1970 window). An Nd / default window records
+        // its concrete ISO lower bound.
+        since: explicitAll ? 'all' : new Date(sinceMs).toISOString(),
+        window: explicitAll ? 'all' : opts.window ?? null,
+        swarmsAnalyzed,
+        swarmsDone,
+        swarmsFailed,
+        successRate,
+        avgCostUsd,
+        avgTokens,
+        totalCostUsd,
+        localShare,
+        topFailures,
+        goalCategories,
+        delta,
+        genome,
+    };
+}
+//# sourceMappingURL=reflect.js.map

package/dist/core/learn/reflect.js.map

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

package/dist/core/learn/store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * store.ts — M26 reflection report persistence (~/.ashlr/learn/).
+ *
+ * Persists + loads ReflectionReport snapshots so each run can compute
+ * week-over-week deltas against the previous snapshot.
+ *
+ * Layout:
+ *   ~/.ashlr/learn/reports/<generatedAt-ms>.json   — one pretty-printed
+ *                                                     ReflectionReport per run
+ *
+ * HARD SAFETY INVARIANTS (M26):
+ *  - READ-ONLY over history: this module READS swarms/genome/usage via the
+ *    reflect engine; it WRITES ONLY under ~/.ashlr/learn/. It NEVER writes
+ *    CONFIG_PATH / saveConfig() / router policy / prompts, and NEVER touches a
+ *    user repo working tree.
+ *  - Atomic-ish write: tmp-write + rename (POSIX-atomic), mirroring
+ *    core/swarm/store.ts and core/inbox/store.ts.
+ *  - Bounded: listReports caps how many snapshot files it reads.
+ *  - Never throws: all exported functions swallow errors and return safe
+ *    defaults (null / []).
+ */
+import type { ReflectionReport } from '../types.js';
+/**
+ * Absolute path to the reports directory: `~/.ashlr/learn/reports`.
+ * Created lazily by saveReport — this function does NOT create it.
+ */
+export declare function reportsDir(): string;
+/**
+ * Persist a ReflectionReport snapshot under ~/.ashlr/learn/reports/.
+ *
+ * Returns the absolute path written, or null on failure. Never throws.
+ *
+ * Atomic tmp-write + rename of `JSON.stringify(report, null, 2) + '\n'` to
+ * `reportsDir()/<reportStem(report.generatedAt)>.json`.
+ * MUST NOT write anywhere outside reportsDir().
+ */
+export declare function saveReport(report: ReflectionReport): string | null;
+/**
+ * List persisted ReflectionReport snapshots, most-recent first by
+ * `generatedAt`. Reads at most MAX_REPORTS files. Never throws; returns [] on
+ * any error and silently skips unreadable/malformed files.
+ */
+export declare function listReports(): ReflectionReport[];
+/**
+ * Load the most recent previously-persisted snapshot (the prior report used to
+ * compute week-over-week deltas), or null when none exists.
+ *
+ * `before` (optional ISO ts) excludes snapshots at/after it so a freshly-saved
+ * current report is not compared against itself.
+ */
+export declare function loadPreviousReport(before?: string): ReflectionReport | null;

package/dist/core/learn/store.js

@@ -0,0 +1,165 @@
+/**
+ * store.ts — M26 reflection report persistence (~/.ashlr/learn/).
+ *
+ * Persists + loads ReflectionReport snapshots so each run can compute
+ * week-over-week deltas against the previous snapshot.
+ *
+ * Layout:
+ *   ~/.ashlr/learn/reports/<generatedAt-ms>.json   — one pretty-printed
+ *                                                     ReflectionReport per run
+ *
+ * HARD SAFETY INVARIANTS (M26):
+ *  - READ-ONLY over history: this module READS swarms/genome/usage via the
+ *    reflect engine; it WRITES ONLY under ~/.ashlr/learn/. It NEVER writes
+ *    CONFIG_PATH / saveConfig() / router policy / prompts, and NEVER touches a
+ *    user repo working tree.
+ *  - Atomic-ish write: tmp-write + rename (POSIX-atomic), mirroring
+ *    core/swarm/store.ts and core/inbox/store.ts.
+ *  - Bounded: listReports caps how many snapshot files it reads.
+ *  - Never throws: all exported functions swallow errors and return safe
+ *    defaults (null / []).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { learnDir } from '../config.js';
+// ---------------------------------------------------------------------------
+// Bounds
+// ---------------------------------------------------------------------------
+/** Never read more than this many snapshot files at once (bounds I/O). */
+const MAX_REPORTS = 200;
+// ---------------------------------------------------------------------------
+// Path helpers (re-resolved at call time so tests can relocate HOME)
+// ---------------------------------------------------------------------------
+/**
+ * Absolute path to the reports directory: `~/.ashlr/learn/reports`.
+ * Created lazily by saveReport — this function does NOT create it.
+ */
+export function reportsDir() {
+    return join(learnDir(), 'reports');
+}
+/** Ensure a directory exists, silently creating it if needed. */
+function ensureDir(dir) {
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        // Best-effort; a subsequent write will fail gracefully in its try/catch.
+    }
+}
+/** Derive a filename-safe, chronologically-sortable stem from an ISO ts. */
+function reportStem(generatedAt) {
+    // Epoch-ms keeps lexicographic order == chronological order. Fall back to a
+    // sanitized ISO string if the timestamp is unparseable.
+    const ms = Date.parse(generatedAt);
+    if (Number.isFinite(ms))
+        return String(ms);
+    return generatedAt.replace(/[^\w.-]+/g, '-');
+}
+// ---------------------------------------------------------------------------
+// Persist
+// ---------------------------------------------------------------------------
+/**
+ * Persist a ReflectionReport snapshot under ~/.ashlr/learn/reports/.
+ *
+ * Returns the absolute path written, or null on failure. Never throws.
+ *
+ * Atomic tmp-write + rename of `JSON.stringify(report, null, 2) + '\n'` to
+ * `reportsDir()/<reportStem(report.generatedAt)>.json`.
+ * MUST NOT write anywhere outside reportsDir().
+ */
+export function saveReport(report) {
+    try {
+        const dir = reportsDir();
+        ensureDir(dir);
+        const dest = join(dir, `${reportStem(report.generatedAt)}.json`);
+        const tmp = dest + '.tmp';
+        writeFileSync(tmp, JSON.stringify(report, null, 2) + '\n', 'utf8');
+        renameSync(tmp, dest);
+        return dest;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Load
+// ---------------------------------------------------------------------------
+/** Light structural guard so we never return garbage from the store. */
+function isReport(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return false;
+    }
+    const r = parsed;
+    return (typeof r['generatedAt'] === 'string' &&
+        typeof r['since'] === 'string' &&
+        typeof r['successRate'] === 'number');
+}
+/**
+ * List persisted ReflectionReport snapshots, most-recent first by
+ * `generatedAt`. Reads at most MAX_REPORTS files. Never throws; returns [] on
+ * any error and silently skips unreadable/malformed files.
+ */
+export function listReports() {
+    try {
+        const dir = reportsDir();
+        if (!existsSync(dir))
+            return [];
+        let files;
+        try {
+            // Filename stems are epoch-ms, so a lexicographic descending sort of the
+            // filenames already orders newest-first; sort here so the slice keeps the
+            // MOST-RECENT MAX_REPORTS rather than an arbitrary directory order.
+            files = readdirSync(dir)
+                .filter((f) => f.endsWith('.json') && !f.endsWith('.tmp'))
+                .sort((a, b) => (a < b ? 1 : a > b ? -1 : 0))
+                .slice(0, MAX_REPORTS);
+        }
+        catch {
+            return [];
+        }
+        const reports = [];
+        for (const file of files) {
+            try {
+                const raw = readFileSync(join(dir, file), 'utf8');
+                const parsed = JSON.parse(raw);
+                if (isReport(parsed))
+                    reports.push(parsed);
+            }
+            catch {
+                // Unreadable or malformed — skip silently.
+            }
+        }
+        // Most-recent first by generatedAt (ISO strings sort lexicographically).
+        reports.sort((a, b) => a.generatedAt < b.generatedAt ? 1 : a.generatedAt > b.generatedAt ? -1 : 0);
+        return reports;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Load the most recent previously-persisted snapshot (the prior report used to
+ * compute week-over-week deltas), or null when none exists.
+ *
+ * `before` (optional ISO ts) excludes snapshots at/after it so a freshly-saved
+ * current report is not compared against itself.
+ */
+export function loadPreviousReport(before) {
+    try {
+        const all = listReports();
+        if (all.length === 0)
+            return null;
+        if (before === undefined)
+            return all[0] ?? null;
+        for (const r of all) {
+            if (r.generatedAt < before)
+                return r;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=store.js.map