@meetless/mla 0.1.4

package/dist/lib/analytics/followthrough.js

@@ -0,0 +1,194 @@
+"use strict";
+// The evidence-followthrough join: the ONE implementation shared by `mla
+// adoption`, the evidence section of `mla stats`, and the Stop-hook local
+// correlator (INV-ADOPTION-SOURCE-1). It lives here, in a lib module, precisely
+// so every consumer references the same code path rather than reimplementing the
+// math; the §10.5 "adoption parity" test asserts that shared reference.
+//
+// The product has two evidence channels, Push (context injected by the hook) and
+// Pull (the agent's own meetless__* MCP calls). The naive "did the agent call any
+// tool on an inject turn" metric lies both ways, so A1 splits it and joins three
+// LOCAL trace files by (session_id, turn_index):
+//
+//   ask-traces.jsonl        the inject side (P0): enrichment.context_items[]
+//                           with injected==true carry the source_ids we pushed.
+//   mcp-calls.jsonl         the pull side (P1): one record per meetless__* call
+//                           with evidence_tool + the source_ids it touched.
+//   report-citations.jsonl  the push-reference side (P3): the source_ids the
+//                           agent's final report CITED that turn.
+//
+// Per high-value inject turn (a turn that actually injected >=1 source_id):
+//   A1a pull_followthrough           the agent PULLED an overlapping source_id
+//                                    via an EVIDENCE tool, same or immediate-child
+//                                    turn. relationship_verdict is an ACTION
+//                                    (evidence_tool=false) and never counts.
+//   A1b push_reference_followthrough the report CITED an injected source_id
+//                                    (Push adoption with no Pull).
+//   A1c evidence_followthrough_any   A1a OR A1b -- the headline "are we useless"
+//                                    number.
+//
+// INV-EVIDENCE-OBSERVATION (§7.1): these are OBSERVATIONS of the agent's
+// behavior, not a verification that the evidence was correct or well-used. A
+// non-zero overlap is a strong positive signal; silent use undercounts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normId = normId;
+exports.overlap = overlap;
+exports.computeFollowthrough = computeFollowthrough;
+exports.buildAdoption = buildAdoption;
+exports.parseInjectTurns = parseInjectTurns;
+exports.parseMcpCalls = parseMcpCalls;
+exports.parseReportCitations = parseReportCitations;
+// --- the join ---------------------------------------------------------------
+// Normalize a source_id for set-overlap: the inject side records the file id
+// (e.g. NT:20260602-foo.md) while the agent typically cites the bare id
+// (NT:20260602-foo). Strip a trailing .md and lowercase so both sides compare
+// equal without ever collapsing two genuinely-different ids (they differ by far
+// more than case or extension). Exported so the metric family and the correlator
+// dedupe ids by the SAME rule the join uses.
+function normId(s) {
+    return s.trim().replace(/\.md$/i, "").toLowerCase();
+}
+// Original-form lookup so the row can report the injected id the agent matched,
+// not its normalized form.
+function overlap(injected, touched) {
+    const touchedSet = new Set(touched.map(normId));
+    return injected.filter((id) => touchedSet.has(normId(id)));
+}
+// computeFollowthrough scores each inject turn against the pulls and report
+// citations in its window [N, N+window]. Default window=1 covers the turn and
+// its immediate child (the A1a contract's "same turn_id OR its immediate child
+// turn"); the same window applies to A1b since a multi-turn task's final report
+// can land on N+1. The Stop-hook correlator passes the wider 3-turn window.
+//
+// A1a deliberately fires on source_id OVERLAP only, not the looser "query in the
+// same evidence domain" alternative the prose also allows: domain matching
+// cannot be made deterministic without a classifier and would reintroduce the
+// exact false-positive (acceptance case 2) the split is designed to remove. The
+// pull records keep the query string, so a future domain refinement has the raw
+// material if we ever want it.
+function computeFollowthrough(injects, calls, citations, window = 1) {
+    return injects.map((t) => {
+        const inWindow = (turn) => turn >= t.turn_index && turn <= t.turn_index + window;
+        // A1a: evidence-bearing pulls in the same session and window. The verdict
+        // tool (evidence_tool=false) is filtered out here -- an action is not a Pull.
+        const pulledIds = [];
+        for (const c of calls) {
+            if (c.session_id !== t.session_id || !c.evidence_tool || !inWindow(c.turn_index))
+                continue;
+            pulledIds.push(...c.source_ids);
+        }
+        const pulled_overlap = overlap(t.injected_source_ids, pulledIds);
+        // A1b: the report's cited source_ids in the same session and window.
+        const citedIds = [];
+        for (const r of citations) {
+            if (r.session_id !== t.session_id || !inWindow(r.turn_index))
+                continue;
+            citedIds.push(...r.source_ids);
+        }
+        const cited_overlap = overlap(t.injected_source_ids, citedIds);
+        const a1a_pull = pulled_overlap.length > 0;
+        const a1b_push_reference = cited_overlap.length > 0;
+        return {
+            session_id: t.session_id,
+            turn_index: t.turn_index,
+            injected_source_ids: t.injected_source_ids,
+            a1a_pull,
+            a1b_push_reference,
+            a1c_any: a1a_pull || a1b_push_reference,
+            pulled_overlap,
+            cited_overlap,
+        };
+    });
+}
+function buildAdoption(rows) {
+    const n = rows.length;
+    const a1a = rows.filter((r) => r.a1a_pull).length;
+    const a1b = rows.filter((r) => r.a1b_push_reference).length;
+    const a1c = rows.filter((r) => r.a1c_any).length;
+    const rate = (x) => (n ? x / n : 0);
+    return {
+        inject_turns: n,
+        a1a_pull: a1a,
+        a1b_push_reference: a1b,
+        a1c_any: a1c,
+        no_followthrough: n - a1c,
+        a1a_rate: rate(a1a),
+        a1b_rate: rate(a1b),
+        a1c_rate: rate(a1c),
+        rows,
+    };
+}
+// --- record parsers (best-effort; tolerate a partial line) ------------------
+function asNum(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function asStr(v) {
+    return typeof v === "string" ? v : "";
+}
+function asStrArray(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+// An inject turn is a trace line that actually PUSHED at least one source_id:
+// enrichment.context_items[] with injected===true and a non-empty source_id.
+// turn_index must be numeric to join (a null turn cannot be aligned).
+function parseInjectTurns(traceLines) {
+    const byKey = new Map();
+    for (const t of traceLines) {
+        const session_id = asStr(t.session_id);
+        const turn_index = asNum(t.turn_index);
+        if (!session_id || turn_index === null)
+            continue;
+        const enrichment = t.enrichment ?? null;
+        const items = enrichment && Array.isArray(enrichment.context_items) ? enrichment.context_items : [];
+        const ids = [];
+        for (const raw of items) {
+            const item = raw;
+            if (item.injected !== true)
+                continue;
+            const sid = asStr(item.source_id);
+            if (sid)
+                ids.push(sid);
+        }
+        if (ids.length === 0)
+            continue;
+        const key = `${session_id} ${turn_index}`;
+        const existing = byKey.get(key);
+        if (existing) {
+            // Merge the rare duplicate (S,N) inject line.
+            existing.injected_source_ids = Array.from(new Set([...existing.injected_source_ids, ...ids]));
+        }
+        else {
+            byKey.set(key, { session_id, turn_index, injected_source_ids: Array.from(new Set(ids)) });
+        }
+    }
+    return Array.from(byKey.values());
+}
+function parseMcpCalls(lines) {
+    const out = [];
+    for (const c of lines) {
+        const session_id = asStr(c.session_id);
+        const turn_index = asNum(c.turn_index);
+        if (!session_id || turn_index === null)
+            continue;
+        out.push({
+            session_id,
+            turn_index,
+            evidence_tool: c.evidence_tool === true,
+            source_ids: asStrArray(c.source_ids),
+            query: asStr(c.query),
+            tool: asStr(c.tool),
+        });
+    }
+    return out;
+}
+function parseReportCitations(lines) {
+    const out = [];
+    for (const r of lines) {
+        const session_id = asStr(r.session_id);
+        const turn_index = asNum(r.turn_index);
+        if (!session_id || turn_index === null)
+            continue;
+        out.push({ session_id, turn_index, source_ids: asStrArray(r.source_ids) });
+    }
+    return out;
+}

package/dist/lib/analytics/forwarder.js

@@ -0,0 +1,109 @@
+"use strict";
+// Remote analytics forwarder (spec section 10.1, INV-JOIN-1, INV-CONSENT-1).
+//
+// Ships locally-recorded events to control, which dedupes by (workspace_id,
+// event_id), lands them in control.analytics_events, rolls them up, and mirrors
+// to PostHog server-side. The CLI never holds a PostHog key (INV-POSTHOG-PII-1
+// is enforced server-side too, but we minimize here as well).
+//
+// Three gates, all of which must pass for a single event to leave the machine:
+//   1. remoteAnalyticsEnabled(env)  -> the opt-in posture (master kill wins)
+//   2. isRemotelyEmittable(ev)      -> has a real workspace_id + session_id to join
+//   3. transport succeeds           -> control POST. A failure is swallowed (never
+//                                       thrown) and counted in ForwardResult.failed;
+//                                       the optional onError hook is the operator
+//                                       seam. The event stays in the local jsonl
+//                                       (the durable record for `mla stats`), but
+//                                       the CLI does NOT re-forward it on a later
+//                                       run: a control outage simply means the
+//                                       global rollup never sees it, which the spec
+//                                       reports as unknown rather than zero
+//                                       (INV-GLOBAL-UNKNOWN-1). Forwarding is
+//                                       intentionally silent to the user (no-spam);
+//                                       wire onError to surface failures to an
+//                                       operator.
+//
+// X-Trace-ID is already stamped on every control POST by buildRequestHeaders, so
+// the forward inherits the run's trace_id for free.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORWARD_TIMEOUT_MS = exports.ANALYTICS_INGEST_PATH = void 0;
+exports.partitionEmittable = partitionEmittable;
+exports.forwardEvents = forwardEvents;
+const http_1 = require("../http");
+const consent_1 = require("./consent");
+const envelope_1 = require("./envelope");
+exports.ANALYTICS_INGEST_PATH = "/internal/v1/analytics/events";
+// The forward runs at command finalize, so it must never add a long tail to a
+// command's wall-clock. A short, hard bound: a slow or hung control costs at most
+// this many ms before the run completes. On timeout the batch is dropped, not
+// re-queued; it stays durable in the local jsonl and the global rollup tolerates
+// the gap (INV-GLOBAL-UNKNOWN-1).
+exports.FORWARD_TIMEOUT_MS = 3000;
+// Partition events into those that may be shipped and those that can't (unbound
+// runs). Exported for the test contract (INV-JOIN-1: an event with a null
+// workspace never ships).
+function partitionEmittable(events) {
+    const emittable = [];
+    const withheld = [];
+    for (const ev of events) {
+        if ((0, envelope_1.isRemotelyEmittable)(ev))
+            emittable.push(ev);
+        else
+            withheld.push(ev);
+    }
+    return { emittable, withheld };
+}
+// Forward a batch of events to control. Best-effort: a transport error never
+// throws (analytics must not break a command), it is counted in `failed` so the
+// caller can decide whether to log it. Returns the disposition counts.
+async function forwardEvents(cfg, events, env = process.env, onError, timeoutMs = exports.FORWARD_TIMEOUT_MS) {
+    const result = {
+        attempted: events.length,
+        forwarded: 0,
+        skippedConsent: false,
+        skippedNotEmittable: 0,
+        failed: 0,
+    };
+    if (!(0, consent_1.remoteAnalyticsEnabled)(env)) {
+        result.skippedConsent = true;
+        return result;
+    }
+    const { emittable, withheld } = partitionEmittable(events);
+    result.skippedNotEmittable = withheld.length;
+    if (emittable.length === 0)
+        return result;
+    // Control's AgentReviewWorkspaceGuard authorizes ONE workspaceId per request,
+    // so a batch is grouped by workspace_id and posted once per group. In practice
+    // a single CLI run touches one workspace, but grouping keeps the contract honest
+    // if a flush ever spans more (and isolates a per-workspace transport failure).
+    for (const [workspaceId, group] of groupByWorkspace(emittable)) {
+        try {
+            // Control dedupes by (workspace_id, event_id), so the ingest is idempotent:
+            // re-POSTing an already-landed event never double-counts a rollup
+            // (INV-REMOTE-DEDUPE-1). The CLI does not auto-replay across runs; this is
+            // what would keep a future manual re-sync safe.
+            await (0, http_1.post)(cfg, exports.ANALYTICS_INGEST_PATH, { workspaceId, events: group }, timeoutMs);
+            result.forwarded += group.length;
+        }
+        catch (err) {
+            result.failed += group.length;
+            if (onError)
+                onError(err);
+        }
+    }
+    return result;
+}
+// Group emittable events by their workspace_id. Every event here passed
+// isRemotelyEmittable, so workspace_id is a non-empty string; the cast is safe.
+function groupByWorkspace(events) {
+    const groups = new Map();
+    for (const ev of events) {
+        const ws = ev.workspace_id;
+        const existing = groups.get(ws);
+        if (existing)
+            existing.push(ev);
+        else
+            groups.set(ws, [ev]);
+    }
+    return groups;
+}

package/dist/lib/analytics/logs.js

@@ -0,0 +1,78 @@
+"use strict";
+// Local trace-log directory + reader (spec section 7.4). The hook spool writes the
+// three followthrough trace files here: ask-traces.jsonl (the inject side),
+// mcp-calls.jsonl (the pull side), and report-citations.jsonl (the push-reference
+// side). `mla adoption`, the evidence section of `mla stats`, and the Stop-hook
+// correlator all read them through this ONE module so the path and the
+// lenient-parse semantics match exactly (INV-ADOPTION-SOURCE-1).
+//
+// The path resolves from the LIVE MEETLESS_HOME on every call, NOT the module-load
+// cached config.HOME, because the user-prompt-submit hook sets MEETLESS_HOME at
+// spawn time and the detached correlator process must read the same logs directory
+// the hook wrote to. (events.jsonl, by contrast, is read through store.ts on the
+// cached HOME; in the live CLI the two agree because the env is fixed at startup.)
+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.logsDir = logsDir;
+exports.readLogJsonl = readLogJsonl;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+// The trace-log directory: $MEETLESS_HOME/logs (live env, matching the hook spool).
+function logsDir() {
+    return path.join(process.env.MEETLESS_HOME || path.join(os.homedir(), ".meetless"), "logs");
+}
+// Read one jsonl trace file under logsDir(). Lenient: a blank, partially-written,
+// or corrupt line is skipped, never fatal, so a crash mid-append can never brick a
+// reader. Returns [] when the file is absent.
+function readLogJsonl(file) {
+    const p = path.join(logsDir(), file);
+    if (!fs.existsSync(p))
+        return [];
+    const out = [];
+    for (const line of fs.readFileSync(p, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const o = JSON.parse(line);
+            if (o && typeof o === "object")
+                out.push(o);
+        }
+        catch {
+            // tolerate a partially-written or corrupt line
+        }
+    }
+    return out;
+}

package/dist/lib/analytics/metrics.js

@@ -0,0 +1,78 @@
+"use strict";
+// The North Star metric family (spec §5, INV-METRIC-DEFINITION-1). The review
+// killed the single ambiguous "Evidence Utilization Rate" and replaced it with
+// four metrics that are DEFINED SEPARATELY and never collapsed into one number:
+//
+//   Injection Utilization Rate    injects referenced / injects with offered>0
+//                                 the wall metric: did the injection land at all
+//   Evidence Item Utilization     distinct referenced ids / distinct offered ids
+//                                 the drilldown: did the offered DOCS get used
+//   Reference Precision (v1)      used / (used + ignored)
+//                                 v1 used:=referenced, so this is a reference-
+//                                 followthrough proxy, NOT material use. The
+//                                 dashboard MUST label it "Reference Precision
+//                                 (v1)", never "Inject Precision" (§4.2).
+//   Unknown Coverage              unknown / closed inject windows
+//                                 the honesty term: how often we could not classify
+//
+// Injection Utilization can read 100% while Evidence Item Utilization reads 18%
+// (a 10-doc inject where one doc was used is a utilized injection but a 1-in-10
+// item rate). Both are true; they answer different questions; they render side by
+// side, never merged.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFERENCE_PRECISION_V1_LABEL = void 0;
+exports.computeMetrics = computeMetrics;
+const followthrough_1 = require("./followthrough");
+function computeMetrics(inputs) {
+    // Injection Utilization: only injects that actually offered evidence count in
+    // the denominator (a zero-result inject is a coverage gap, not a missed use).
+    const offeredInjects = inputs.filter((i) => i.evidence_offered > 0);
+    const referencedInjects = offeredInjects.filter((i) => i.referenced);
+    // Evidence Item Utilization: distinct source ids, normalized by the SAME rule
+    // the join uses so "NT:foo.md" and "NT:foo" collapse on both sides.
+    const distinctOffered = new Set();
+    const distinctReferenced = new Set();
+    for (const i of inputs) {
+        for (const id of i.offered_source_ids)
+            distinctOffered.add((0, followthrough_1.normId)(id));
+        for (const id of i.referenced_source_ids)
+            distinctReferenced.add((0, followthrough_1.normId)(id));
+    }
+    let used = 0;
+    let ignored = 0;
+    let unknown = 0;
+    let pending = 0;
+    for (const i of inputs) {
+        if (i.outcome === "used")
+            used++;
+        else if (i.outcome === "ignored")
+            ignored++;
+        else if (i.outcome === "unknown")
+            unknown++;
+        else if (i.outcome === "pending")
+            pending++;
+    }
+    const closedWindows = used + ignored + unknown;
+    return {
+        injection_utilization: offeredInjects.length
+            ? referencedInjects.length / offeredInjects.length
+            : null,
+        evidence_item_utilization: distinctOffered.size
+            ? distinctReferenced.size / distinctOffered.size
+            : null,
+        reference_precision_v1: used + ignored ? used / (used + ignored) : null,
+        unknown_coverage: closedWindows ? unknown / closedWindows : null,
+        injects_offered: offeredInjects.length,
+        injects_referenced: referencedInjects.length,
+        distinct_offered: distinctOffered.size,
+        distinct_referenced: distinctReferenced.size,
+        used,
+        ignored,
+        unknown,
+        pending,
+        closed_windows: closedWindows,
+    };
+}
+// The v1 dashboard label for reference_precision_v1. Centralized so every render
+// path (mla stats, mla adoption) shows the same honest wording (§4.2).
+exports.REFERENCE_PRECISION_V1_LABEL = "Reference Precision (v1)";

package/dist/lib/analytics/recorder.js

@@ -0,0 +1,92 @@
+"use strict";
+// Analytics recorder: the single entry point a command uses to emit an event
+// (spec section 10, the dual-sink contract). It does three things, in order:
+//
+//   1. Assemble the envelope from the run context (run_id, trace_id, session_id,
+//      workspace_id, distinct_id) + the caller's event_type/payload.
+//   2. Append it to the local jsonl IMMEDIATELY (durable, offline-safe, the
+//      source of truth for `mla stats`). This happens even with remote analytics
+//      off (gated only by localStatsEnabled inside the store).
+//   3. Buffer it for a best-effort remote forward at run finalize.
+//
+// The local append is synchronous and unconditional-by-consent; the remote
+// forward is deferred to flushAnalyticsEvents() so a single run makes at most one
+// control round-trip. This keeps analytics off the command's hot path: nothing
+// here blocks or can throw into the command.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEvent = buildEvent;
+exports.recordAnalyticsEvent = recordAnalyticsEvent;
+exports.flushAnalyticsEvents = flushAnalyticsEvents;
+exports.resetRecorderForTesting = resetRecorderForTesting;
+exports.peekBuffer = peekBuffer;
+const observability_1 = require("../observability");
+const envelope_1 = require("./envelope");
+const event_id_1 = require("./event-id");
+const store_1 = require("./store");
+const store_2 = require("./store");
+const forwarder_1 = require("./forwarder");
+let buffer = [];
+// Build the fully-formed, flat event (envelope + payload merged). Pure: no I/O,
+// so the test contract can assert envelope completeness on the returned object.
+function buildEvent(ctx, input) {
+    const runId = ctx.runId ?? (0, observability_1.getRunId)();
+    const traceId = ctx.traceId ?? (0, observability_1.getRunTraceId)();
+    if (!runId) {
+        throw new Error("buildEvent requires a run_id (call setRunId at bootstrap or pass ctx.runId)");
+    }
+    if (!traceId) {
+        throw new Error("buildEvent requires a trace_id (call setRunTraceId at bootstrap or pass ctx.traceId)");
+    }
+    const envelope = (0, envelope_1.makeEnvelope)({
+        event_id: input.eventId ?? (0, event_id_1.mintEventId)(),
+        event_type: input.eventType,
+        created_at: ctx.now,
+        emitted_at: ctx.now,
+        workspace_id: ctx.workspaceId,
+        distinct_id: ctx.distinctId ?? (ctx.workspaceId ? null : (0, store_2.machineId)()),
+        session_id: ctx.sessionId,
+        run_id: runId,
+        trace_id: traceId,
+        source: ctx.source ?? "cli",
+        actor_workspace_user_id: ctx.actorWorkspaceUserId ?? null,
+        repo_fingerprint: ctx.repoFingerprint ?? (0, observability_1.getRepoFingerprint)(),
+    });
+    // Flat merge: envelope first so a stray envelope-named payload key can't shadow
+    // the real join fields.
+    return { ...input.payload, ...envelope };
+}
+// Record an event: append locally now, buffer for remote forward later. Returns
+// the built event so a caller (or test) can inspect it. Never throws on I/O.
+function recordAnalyticsEvent(ctx, input, env = process.env, onError) {
+    const ev = buildEvent(ctx, input);
+    (0, store_1.appendEvent)(ev, env, onError);
+    buffer.push(ev);
+    return ev;
+}
+// Flush the buffered events to control (best-effort). Called once at run finalize.
+// Drains the in-process buffer unconditionally: this is the only forward attempt
+// for these events (there is no cross-run replay). On a forward failure they stay
+// durable in the local jsonl (the source of truth for `mla stats`); only the remote
+// rollup misses them, reported as unknown rather than zero (INV-GLOBAL-UNKNOWN-1).
+async function flushAnalyticsEvents(cfg, env = process.env, onError, timeoutMs) {
+    const pending = buffer;
+    buffer = [];
+    if (pending.length === 0) {
+        return {
+            attempted: 0,
+            forwarded: 0,
+            skippedConsent: false,
+            skippedNotEmittable: 0,
+            failed: 0,
+        };
+    }
+    return (0, forwarder_1.forwardEvents)(cfg, pending, env, onError, timeoutMs);
+}
+// Test-only: drop any buffered events so suites don't bleed state across cases.
+function resetRecorderForTesting() {
+    buffer = [];
+}
+// Test/inspection: a copy of the current buffer.
+function peekBuffer() {
+    return [...buffer];
+}

package/dist/lib/analytics/review-analytics.js

@@ -0,0 +1,75 @@
+"use strict";
+// mla_review_decision + mla_contradiction builders (spec §6.2, §7.2; T7.2).
+//
+// Pure, I/O-free: given the reviewed candidate's relation type and the verdict,
+// produce the closed, PII-bounded analytics events to record at DECISION time.
+// Both are recorded exactly ONCE per decision (the dashboard rollup is
+// event-counting), so a single decision-time emit is the whole story and never
+// double-counts.
+//
+//   mla_review_decision  -- every accept / reject / reclassify / no_relation. Tells
+//                           us curation behavior and trust over time.
+//   mla_contradiction    -- only the contradiction/supersession edge classes (the
+//                           "did mla catch a stale assumption" signal). surfaced is
+//                           always true at review time (the candidate WAS shown);
+//                           acted_on is true only when the curator accepted it (made
+//                           it a governed edge).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerceRelationEdgeType = coerceRelationEdgeType;
+exports.reviewDecisionLabel = reviewDecisionLabel;
+exports.buildReviewAnalyticsEvents = buildReviewAnalyticsEvents;
+const envelope_1 = require("./envelope");
+const event_id_1 = require("./event-id");
+// Map a raw relation-type key onto the closed edge-type enum. Anything not in the
+// curated set (or null) becomes "unknown" -- no open string ever reaches PostHog
+// (INV-POSTHOG-PII-1).
+function coerceRelationEdgeType(raw) {
+    if (raw && envelope_1.RELATION_EDGE_TYPES.includes(raw)) {
+        return raw;
+    }
+    return "unknown";
+}
+// The verdict -> closed decision-label mapping. accept/reject pass through; a
+// correction is "no_relation" when it asserts the edge should not exist, else
+// "reclassify" (a re-type or a section-scope correction is still a reclassification).
+function reviewDecisionLabel(verdict, correctionKind) {
+    if (verdict === "accept")
+        return "accept";
+    if (verdict === "reject")
+        return "reject";
+    if (correctionKind === "NO_RELATION")
+        return "no_relation";
+    return "reclassify";
+}
+function buildReviewAnalyticsEvents(input) {
+    const { candidateId, verdict, correctionKind, relationTypeId } = input;
+    const decision = reviewDecisionLabel(verdict, correctionKind);
+    const relationType = coerceRelationEdgeType(relationTypeId);
+    const events = [];
+    const reviewPayload = {
+        decision_id: candidateId,
+        decision_version: 1,
+        decision,
+        relation_type: relationType,
+    };
+    events.push({
+        eventType: "mla_review_decision",
+        eventId: (0, event_id_1.reviewDecisionEventId)(candidateId, 1),
+        payload: reviewPayload,
+    });
+    // Only contradiction/supersession edges are "stale assumption caught" signals.
+    if (relationType === "CONTRADICTS" || relationType === "SUPERSEDES") {
+        const contradictionPayload = {
+            contradiction_id: candidateId,
+            edge_type: relationType,
+            contradiction_surfaced: true,
+            contradiction_acted_on: verdict === "accept",
+        };
+        events.push({
+            eventType: "mla_contradiction",
+            eventId: (0, event_id_1.deterministicEventId)(`contradiction:${candidateId}`, 1),
+            payload: contradictionPayload,
+        });
+    }
+    return events;
+}