@hyperspell/openclaw-hyperspell 0.19.0 → 0.21.0

package/dist/lib/mood-skew-audit.js

@@ -0,0 +1,580 @@
+/**
+ * Pure logic for the mood-retrieval skew audit
+ * (docs/proposals/10-mood-retrieval-skew-audit.md) — extracted here so the
+ * classification/bucketing/verdict logic joins the hermetic unit suite while
+ * the live runner (scripts/audit-mood-skew.ts) stays out of `npm test`,
+ * mirroring the lib/loops-audit.ts + scripts/audit-loops.ts split.
+ *
+ * Nothing here touches the network. The audit is read-only observation of
+ * three live surfaces: the emotional-state snapshot timeline, the corpus
+ * census by `openclaw_source` × ISO week, and a fixed neutral probe panel.
+ */
+// ---------------------------------------------------------------------------
+// Phase 1 — mood timeline
+// ---------------------------------------------------------------------------
+/**
+ * Keyword lexicons from proposal 10 §Phase 1. Deliberately small: this is a
+ * first-pass auto-label whose only job is to make the operator's manual
+ * review of every summary faster — the review, not the lexicon, is the
+ * ground truth. Inflections are included so "grieving"/"sadness" hit; word
+ * boundaries stop "light" matching "lightning" and "sad" matching "sadness"
+ * without its own entry.
+ */
+export const HEAVY_TERMS = [
+    "grief",
+    "grieving",
+    "loss",
+    "mourning",
+    "ache",
+    "aching",
+    "heaviness",
+    "heavy",
+    "sad",
+    "sadness",
+    "sorrow",
+    "tired",
+    "weary",
+    "strained",
+    "fragile",
+    "wounded",
+    "tender",
+];
+export const LIGHT_TERMS = [
+    "warm",
+    "warmth",
+    "playful",
+    "easy",
+    "ease",
+    "curious",
+    "energized",
+    "light",
+    "lighter",
+    "steady",
+    "bright",
+    "joy",
+    "joyful",
+];
+function countTermHits(text, terms) {
+    let hits = 0;
+    for (const term of terms) {
+        hits += text.match(new RegExp(`\\b${term}\\b`, "gi"))?.length ?? 0;
+    }
+    return hits;
+}
+export function classifySummary(summary) {
+    const heavyHits = countTermHits(summary, HEAVY_TERMS);
+    const lightHits = countTermHits(summary, LIGHT_TERMS);
+    const score = heavyHits - lightHits;
+    return {
+        heavyHits,
+        lightHits,
+        score,
+        label: score > 0 ? "heavy" : score < 0 ? "light" : "neutral",
+    };
+}
+/** UTC Monday of the date's ISO week, as YYYY-MM-DD; null on unparseable input. */
+export function weekStartOf(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return null;
+    const day = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+    day.setUTCDate(day.getUTCDate() - ((day.getUTCDay() + 6) % 7));
+    return day.toISOString().slice(0, 10);
+}
+export function classifySnapshots(snapshots) {
+    return snapshots.map((s) => {
+        const { heavyHits, lightHits, label } = classifySummary(s.summary);
+        return {
+            ...s,
+            week: weekStartOf(s.extractedAt),
+            heavyHits,
+            lightHits,
+            label,
+        };
+    });
+}
+/** Week label: strict-majority heavy/light, else mixed. Undated snapshots drop. */
+export function buildMoodTimeline(classified) {
+    const byWeek = new Map();
+    for (const s of classified) {
+        if (s.week === null)
+            continue;
+        const agg = byWeek.get(s.week) ?? { heavy: 0, light: 0, neutral: 0 };
+        agg[s.label]++;
+        byWeek.set(s.week, agg);
+    }
+    return [...byWeek.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([week, agg]) => {
+        const snapshots = agg.heavy + agg.light + agg.neutral;
+        const label = agg.heavy * 2 > snapshots
+            ? "heavy"
+            : agg.light * 2 > snapshots
+                ? "light"
+                : "mixed";
+        return { week, snapshots, ...agg, label };
+    });
+}
+// ---------------------------------------------------------------------------
+// Phase 2 — corpus census by source × week
+// ---------------------------------------------------------------------------
+export const SOURCE_BUCKETS = [
+    "hot_buffer",
+    "agent_end",
+    "command",
+    "memory_sync",
+    "emotional_state",
+    "other",
+];
+function emptyCounts() {
+    return {
+        hot_buffer: 0,
+        agent_end: 0,
+        command: 0,
+        memory_sync: 0,
+        emotional_state: 0,
+        other: 0,
+    };
+}
+/**
+ * `openclaw_source` is the pipeline discriminator every write path stamps
+ * (hooks/hot-buffer.ts, client.sendTrace, client.addMemory, sync/markdown.ts).
+ * Emotional-state snapshots are the exception: storeEmotionalState stamps
+ * `source: "openclaw_agent_end"` (hooks/emotional-state.ts), a different key —
+ * checked after openclaw_source so the two can never shadow each other.
+ */
+export function bucketSource(metadata) {
+    const src = metadata.openclaw_source;
+    if (src === "hot_buffer")
+        return "hot_buffer";
+    if (src === "agent_end")
+        return "agent_end";
+    if (src === "command")
+        return "command";
+    if (src === "memory_sync" || src === "memory_sync_section")
+        return "memory_sync";
+    if (metadata.source === "openclaw_agent_end")
+        return "emotional_state";
+    return "other";
+}
+/**
+ * Week of a listed resource. `created_at` coverage in the list payload is one
+ * of the open questions this audit answers (proposal 10 §Phase 2), so the
+ * fallback — a date embedded in `openclaw_session_id` — is tracked separately
+ * and reported, never silently mixed in.
+ */
+export function resourceWeek(metadata) {
+    const created = metadata.created_at;
+    if (typeof created === "string") {
+        const week = weekStartOf(created);
+        if (week !== null)
+            return { week, via: "created_at" };
+    }
+    const sid = metadata.openclaw_session_id;
+    if (typeof sid === "string") {
+        const embedded = /(\d{4}-\d{2}-\d{2})/.exec(sid);
+        if (embedded) {
+            const week = weekStartOf(embedded[1]);
+            if (week !== null)
+                return { week, via: "session_id" };
+        }
+    }
+    return { week: null, via: null };
+}
+export function buildCensus(resources) {
+    const byWeek = new Map();
+    const undated = emptyCounts();
+    const totals = emptyCounts();
+    const weekOf = new Map();
+    let dated = 0;
+    let datedViaSessionId = 0;
+    for (const r of resources) {
+        const bucket = bucketSource(r.metadata);
+        totals[bucket]++;
+        const { week, via } = resourceWeek(r.metadata);
+        if (week === null) {
+            undated[bucket]++;
+            continue;
+        }
+        dated++;
+        if (via === "session_id")
+            datedViaSessionId++;
+        weekOf.set(r.resourceId, week);
+        const counts = byWeek.get(week) ?? emptyCounts();
+        counts[bucket]++;
+        byWeek.set(week, counts);
+    }
+    const rows = [...byWeek.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([week, counts]) => ({
+        week,
+        counts,
+        total: SOURCE_BUCKETS.reduce((sum, b) => sum + counts[b], 0),
+    }));
+    return {
+        rows,
+        undated,
+        totals,
+        total: resources.length,
+        dated,
+        datedViaSessionId,
+        snapshotResourcesVisible: totals.emotional_state > 0,
+        weekOf,
+    };
+}
+// ---------------------------------------------------------------------------
+// Phase 3 — retrieval probe
+// ---------------------------------------------------------------------------
+/**
+ * Fixed neutral panel from proposal 10 §Phase 3 — deliberately mundane and
+ * NOT emotion-themed, because heavy weeks winning emotion-adjacent queries
+ * would be correct retrieval, not skew. Committed with the code so reruns are
+ * comparable; do not edit between runs of the same audit window.
+ */
+export const PROBE_QUERIES = [
+    "what did we decide about the plugin config",
+    "plans for the weekend",
+    "cooking dinner",
+    "book recommendation",
+    "how the project is going",
+    "morning routine",
+    "travel plans",
+    "something funny that happened",
+    "what David is working on",
+    "health and sleep",
+    "music we talked about",
+    "errands and chores",
+];
+const round2 = (n) => Number(n.toFixed(2));
+const round4 = (n) => Number(n.toFixed(4));
+function mean(xs) {
+    if (xs.length === 0)
+        return null;
+    return xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+/** Mean after dropping the single largest value; null under 2 points. */
+function meanDropMax(xs) {
+    if (xs.length < 2)
+        return null;
+    const maxIdx = xs.indexOf(Math.max(...xs));
+    return mean(xs.filter((_, i) => i !== maxIdx));
+}
+export function buildProbeStats(hits, weekOf) {
+    const byWeek = new Map();
+    const queries = new Set();
+    let unknownSlots = 0;
+    for (const hit of hits) {
+        queries.add(hit.query);
+        // createdAt (search echoes metadata.created_at) first, else census join.
+        const week = (hit.createdAt !== null ? weekStartOf(hit.createdAt) : null) ??
+            weekOf.get(hit.resourceId) ??
+            null;
+        if (week === null) {
+            unknownSlots++;
+            continue;
+        }
+        const agg = byWeek.get(week) ?? { slots: 0, scores: [] };
+        agg.slots++;
+        if (hit.score !== null)
+            agg.scores.push(hit.score);
+        byWeek.set(week, agg);
+    }
+    const totalSlots = hits.length;
+    const rows = [...byWeek.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([week, agg]) => ({
+        week,
+        slots: agg.slots,
+        resultShare: totalSlots === 0 ? 0 : round4(agg.slots / totalSlots),
+        meanScore: agg.scores.length === 0 ? null : round4(mean(agg.scores)),
+    }));
+    return { rows, totalSlots, unknownSlots, queries: queries.size };
+}
+/**
+ * Pre-registered decision rule from proposal 10 §Test plan — thresholds were
+ * fixed before any data was seen, so the outcome can't be argued into
+ * existence. Confirmed skew requires BOTH a volume-or-lift signal AND the
+ * effect being visible on the neutral panel (heavy mean lift > 1.0): the
+ * lift/share numbers come only from the neutral probe queries, so a
+ * volume-only signal that never surfaces in neutral retrieval stays
+ * ambiguous, not confirmed. The guide pins the drop-the-max-week fallback at
+ * 1.3× for volume; the same 1.3× floor is applied to the lift survival check
+ * (the guide says "surviving removal" without a number).
+ */
+export function buildVerdict(timeline, census, probe) {
+    const labelByWeek = new Map(timeline.map((r) => [r.week, r.label]));
+    const censusByWeek = new Map(census.rows.map((r) => [r.week, r]));
+    const probeByWeek = new Map(probe.rows.map((r) => [r.week, r]));
+    const weeks = [
+        ...new Set([
+            ...labelByWeek.keys(),
+            ...censusByWeek.keys(),
+            ...probeByWeek.keys(),
+        ]),
+    ].sort();
+    const rows = weeks.map((week) => {
+        const c = censusByWeek.get(week);
+        const p = probeByWeek.get(week);
+        const hotBufferMsgs = c?.counts.hot_buffer ?? 0;
+        const derived = (c?.counts.agent_end ?? 0) + (c?.counts.emotional_state ?? 0);
+        const corpusShare = c !== undefined && census.dated > 0
+            ? round4(c.total / census.dated)
+            : null;
+        const resultShare = p?.resultShare ?? 0;
+        return {
+            week,
+            label: labelByWeek.get(week) ?? "unknown",
+            hotBufferMsgs,
+            derived,
+            derivedPer100: hotBufferMsgs > 0
+                ? Number(((derived / hotBufferMsgs) * 100).toFixed(1))
+                : null,
+            corpusShare,
+            resultShare,
+            lift: corpusShare !== null && corpusShare > 0
+                ? round2(resultShare / corpusShare)
+                : null,
+            meanScore: p?.meanScore ?? null,
+        };
+    });
+    const heavyRows = rows.filter((r) => r.label === "heavy");
+    const lightRows = rows.filter((r) => r.label === "light");
+    const heavyWeeks = heavyRows.length;
+    const lightWeeks = lightRows.length;
+    const per100 = (rs) => rs.map((r) => r.derivedPer100).filter((v) => v !== null);
+    const lifts = (rs) => rs.map((r) => r.lift).filter((v) => v !== null);
+    const heavyVolMean = mean(per100(heavyRows));
+    const lightVolMean = mean(per100(lightRows));
+    const heavyVolDropMax = meanDropMax(per100(heavyRows));
+    const ratio = (a, b) => a !== null && b !== null && b > 0 ? round2(a / b) : null;
+    const volumeRatio = ratio(heavyVolMean, lightVolMean);
+    const volumeRatioDropMax = ratio(heavyVolDropMax, lightVolMean);
+    const heavyMeanLiftRaw = mean(lifts(heavyRows));
+    const heavyMeanLift = heavyMeanLiftRaw === null ? null : round2(heavyMeanLiftRaw);
+    const heavyMeanLiftDropMaxRaw = meanDropMax(lifts(heavyRows));
+    const heavyMeanLiftDropMax = heavyMeanLiftDropMaxRaw === null ? null : round2(heavyMeanLiftDropMaxRaw);
+    const lightMeanLiftRaw = mean(lifts(lightRows));
+    const lightMeanLift = lightMeanLiftRaw === null ? null : round2(lightMeanLiftRaw);
+    const reasons = [];
+    let outcome;
+    if (heavyWeeks < 3 || lightWeeks < 3) {
+        outcome = "insufficient-data";
+        reasons.push(`need >=3 heavy AND >=3 light labeled weeks (have ${heavyWeeks} heavy, ${lightWeeks} light) — rerun after 4-6 more weeks of data`);
+    }
+    else {
+        const volumeSkew = volumeRatio !== null &&
+            volumeRatio >= 1.5 &&
+            volumeRatioDropMax !== null &&
+            volumeRatioDropMax >= 1.3;
+        const liftSkew = heavyMeanLift !== null &&
+            lightMeanLift !== null &&
+            heavyMeanLift >= 1.5 &&
+            lightMeanLift <= 1.0 &&
+            heavyMeanLiftDropMax !== null &&
+            heavyMeanLiftDropMax >= 1.3;
+        const panelVisible = heavyMeanLift !== null && heavyMeanLift > 1.0;
+        reasons.push(`volume: heavy/light derived-per-100-msgs ratio = ${volumeRatio ?? "n/a"} (threshold 1.5; drop-max ${volumeRatioDropMax ?? "n/a"}, threshold 1.3) — ${volumeSkew ? "SKEW" : "no skew"}`, `lift: heavy mean ${heavyMeanLift ?? "n/a"} (threshold 1.5; drop-max ${heavyMeanLiftDropMax ?? "n/a"}, threshold 1.3), light mean ${lightMeanLift ?? "n/a"} (threshold <=1.0) — ${liftSkew ? "SKEW" : "no skew"}`, `neutral-panel visibility: heavy mean lift ${heavyMeanLift ?? "n/a"} ${panelVisible ? ">" : "<="} 1.0 — ${panelVisible ? "visible" : "not visible"}`);
+        if ((volumeSkew || liftSkew) && panelVisible) {
+            outcome = "confirmed-skew";
+        }
+        else {
+            const liftRatio = ratio(heavyMeanLift, lightMeanLift);
+            const within20 = (v) => v !== null && v >= 0.8 && v <= 1.2;
+            if (within20(volumeRatio) && within20(liftRatio)) {
+                outcome = "no-real-skew";
+                reasons.push(`volume ratio ${volumeRatio} and lift ratio ${liftRatio} both within +/-20% — heavy and light weeks retrieve proportionally`);
+            }
+            else {
+                outcome = "ambiguous";
+                reasons.push("between the confirmed and no-skew bands — record these numbers and rerun after 4-6 more weeks");
+            }
+        }
+    }
+    return {
+        rows,
+        heavyWeeks,
+        lightWeeks,
+        volumeRatio,
+        volumeRatioDropMax,
+        heavyMeanLift,
+        heavyMeanLiftDropMax,
+        lightMeanLift,
+        outcome,
+        reasons,
+    };
+}
+/** Parse CLI args; throws with a usable message on anything malformed. */
+export function parseSkewArgs(argv) {
+    const args = {
+        json: false,
+        mood: false,
+        census: false,
+        probe: false,
+        probeLimit: 25,
+        snapshotLimit: 200,
+    };
+    const take = (flag, i) => {
+        const v = argv[i];
+        if (v === undefined)
+            throw new Error(`${flag} requires a value`);
+        return v;
+    };
+    const takeInt = (flag, i) => {
+        const n = Number(take(flag, i));
+        if (!Number.isInteger(n) || n < 1)
+            throw new Error(`${flag} must be a positive integer`);
+        return n;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "--mood":
+                args.mood = true;
+                break;
+            case "--census":
+                args.census = true;
+                break;
+            case "--probe":
+                args.probe = true;
+                break;
+            case "-o": {
+                const fmt = take(a, ++i);
+                if (fmt !== "json")
+                    throw new Error(`unsupported output format "${fmt}" (only: json)`);
+                args.json = true;
+                break;
+            }
+            case "--user":
+                args.user = take(a, ++i);
+                break;
+            case "--probe-limit":
+                args.probeLimit = takeInt(a, ++i);
+                break;
+            case "--snapshot-limit":
+                args.snapshotLimit = takeInt(a, ++i);
+                break;
+            default:
+                throw new Error(`unknown argument "${a}"`);
+        }
+    }
+    // No phase flag = the full audit (all three phases + combined verdict).
+    if (!args.mood && !args.census && !args.probe) {
+        args.mood = true;
+        args.census = true;
+        args.probe = true;
+    }
+    return args;
+}
+// ---------------------------------------------------------------------------
+// Human formatting
+// ---------------------------------------------------------------------------
+function renderTable(header, rows) {
+    const all = [header, ...rows];
+    const widths = header.map((_, i) => Math.max(...all.map((r) => (r[i] ?? "").length)));
+    return all
+        .map((r) => r
+        .map((c, i) => (c ?? "").padEnd(widths[i]))
+        .join("  ")
+        .trimEnd())
+        .join("\n");
+}
+const pct = (v) => v === null ? "—" : `${(v * 100).toFixed(1)}%`;
+const num = (v) => (v === null ? "—" : String(v));
+export function formatSnapshotReview(classified, includeContent) {
+    const lines = [
+        "mood snapshots — auto-labels for MANUAL review (the lexicon is a first pass, your eyes are the ground truth):",
+    ];
+    for (const s of classified) {
+        const head = `  ${s.week ?? "(undated)"}  ${s.label.padEnd(7)} (heavy ${s.heavyHits} / light ${s.lightHits})  ${s.resourceId}`;
+        lines.push(includeContent
+            ? `${head}\n      ${s.summary.replace(/\s+/g, " ").slice(0, 240)}`
+            : head);
+    }
+    if (!includeContent) {
+        lines.push("  (set HYPERSPELL_AUDIT_CONTENT=1 to print the summaries — required for the manual label review)");
+    }
+    return lines.join("\n");
+}
+export function formatMoodTimeline(rows) {
+    if (rows.length === 0)
+        return "mood timeline: no dated snapshots";
+    return `mood timeline:\n${renderTable(["week", "snapshots", "heavy", "light", "neutral", "label"], rows.map((r) => [
+        r.week,
+        String(r.snapshots),
+        String(r.heavy),
+        String(r.light),
+        String(r.neutral),
+        r.label,
+    ]))}`;
+}
+export function formatCensus(census) {
+    const header = ["week", ...SOURCE_BUCKETS, "total"];
+    const rows = census.rows.map((r) => [
+        r.week,
+        ...SOURCE_BUCKETS.map((b) => String(r.counts[b])),
+        String(r.total),
+    ]);
+    const undatedTotal = SOURCE_BUCKETS.reduce((s, b) => s + census.undated[b], 0);
+    rows.push([
+        "(undated)",
+        ...SOURCE_BUCKETS.map((b) => String(census.undated[b])),
+        String(undatedTotal),
+    ]);
+    rows.push([
+        "TOTAL",
+        ...SOURCE_BUCKETS.map((b) => String(census.totals[b])),
+        String(census.total),
+    ]);
+    const coverage = census.total === 0 ? null : census.dated / census.total;
+    return [
+        `corpus census (${census.total} resources):`,
+        renderTable(header, rows),
+        `dated: ${census.dated}/${census.total} (${pct(coverage)}) — ${census.datedViaSessionId} via session-id fallback, ${undatedTotal} undated`,
+        `snapshot resources visible via memories.list: ${census.snapshotResourcesVisible ? "yes" : "no"}`,
+    ].join("\n");
+}
+export function formatProbe(stats) {
+    return [
+        `retrieval probe (${stats.queries} queries, ${stats.totalSlots} result slots, ${stats.unknownSlots} undatable):`,
+        renderTable(["week", "slots", "resultShare", "meanScore"], stats.rows.map((r) => [
+            r.week,
+            String(r.slots),
+            pct(r.resultShare),
+            num(r.meanScore),
+        ])),
+    ].join("\n");
+}
+export function formatVerdict(verdict) {
+    const lines = [
+        "combined verdict (thresholds pre-registered in docs/proposals/10-mood-retrieval-skew-audit.md):",
+        renderTable([
+            "week",
+            "label",
+            "msgs(hot_buffer)",
+            "derived",
+            "derived/100msgs",
+            "corpusShare",
+            "resultShare",
+            "lift",
+            "meanScore",
+        ], verdict.rows.map((r) => [
+            r.week,
+            r.label,
+            String(r.hotBufferMsgs),
+            String(r.derived),
+            num(r.derivedPer100),
+            pct(r.corpusShare),
+            pct(r.resultShare),
+            num(r.lift),
+            num(r.meanScore),
+        ])),
+        "",
+        `heavy weeks: ${verdict.heavyWeeks}   light weeks: ${verdict.lightWeeks}`,
+        `volume ratio (heavy/light derived-per-100-msgs): ${num(verdict.volumeRatio)} (drop-max: ${num(verdict.volumeRatioDropMax)})`,
+        `mean lift: heavy ${num(verdict.heavyMeanLift)} (drop-max: ${num(verdict.heavyMeanLiftDropMax)})   light ${num(verdict.lightMeanLift)}`,
+        "",
+        `OUTCOME: ${verdict.outcome}`,
+        ...verdict.reasons.map((r) => `  - ${r}`),
+    ];
+    return lines.join("\n");
+}