@meetless/mla 0.1.4

package/dist/lib/analytics/coverage-gap.js

@@ -0,0 +1,96 @@
+"use strict";
+// Coverage-gap classification (spec §7.5, INV-COVERAGE-GAP-1).
+//
+// A zero-result or low-confidence retrieval is the most actionable forward
+// signal mla produces, but ONLY if it distinguishes cause. "Capture more docs"
+// is the wrong fix when the real problem is ranking, staleness, or a permission
+// filter. This module is the single, pure classifier that maps the inject-time
+// retrieval signals to one closed `coverage_gap_type`, so the inject command and
+// its test run the identical code with no I/O.
+//
+// The classification is INJECT-TIME: it answers "why did this retrieval fail to
+// help" from what we knew when we surfaced (or failed to surface) evidence. The
+// seventh type, `candidates_found_not_used`, is OUTCOME-time (the agent had
+// usable candidates but referenced none) and is owned by the correlator, never
+// emitted here.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyCoverageGap = classifyCoverageGap;
+exports.coerceTopicCategory = coerceTopicCategory;
+exports.coerceRetrievalConfidence = coerceRetrievalConfidence;
+exports.coverageGapEventId = coverageGapEventId;
+exports.coverageGapNotUsedEventId = coverageGapNotUsedEventId;
+exports.buildCoverageGapPayload = buildCoverageGapPayload;
+const envelope_1 = require("./envelope");
+const event_id_1 = require("./event-id");
+// classifyCoverageGap returns the single canonical gap type, or null when there
+// is no coverage gap to report (a healthy, confident retrieval). Precedence is
+// most-specific cause first, so a single inject is attributed to exactly one
+// type even when several signals are set (INV-COVERAGE-GAP-1):
+//
+//   retrieval_error             a bug shadows every other reading
+//   permission_filtered         an ACL drop is an access problem, not knowledge
+//   no_candidate_found          nothing came back at all
+//   stale_or_conflicting        candidates exist but the KB needs reconciling
+//   low_confidence_candidates   candidates exist but ranking is weak
+//   (null)                      confident, non-empty retrieval: no gap
+//
+// candidates_found_not_used is deliberately NOT reachable here: it is the
+// outcome-time type the correlator emits when usable candidates were ignored.
+function classifyCoverageGap(signals) {
+    if (signals.retrievalError)
+        return "retrieval_error";
+    if (signals.permissionFiltered)
+        return "permission_filtered";
+    if (signals.zeroResults)
+        return "no_candidate_found";
+    if (signals.staleOrConflicting)
+        return "stale_or_conflicting_candidates";
+    if (signals.retrievalConfidence === "low")
+        return "low_confidence_candidates";
+    return null;
+}
+// Coerce a free-form topic string to the closed query_topic_category enum,
+// defaulting to "unknown" so an unrecognized topic never leaks a raw string
+// past the PII boundary (INV-POSTHOG-PII-1).
+function coerceTopicCategory(raw) {
+    if (raw && envelope_1.QUERY_TOPIC_CATEGORIES.includes(raw)) {
+        return raw;
+    }
+    return "unknown";
+}
+// Coerce a free-form confidence string to the closed enum, defaulting to "low"
+// (the same conservative default buildInjectPayload uses) so an unknown
+// confidence never inflates the dashboard.
+function coerceRetrievalConfidence(raw) {
+    if (raw && envelope_1.RETRIEVAL_CONFIDENCES.includes(raw)) {
+        return raw;
+    }
+    return "low";
+}
+// Deterministic event_id for an inject-time coverage gap. One inject produces at
+// most one inject-time gap, so the inject_id IS the natural business key; the
+// `coverage_gap:` prefix keeps it from colliding with the inject event's own id
+// (which is the bare inject_id) under control's (workspace_id, event_id) dedupe.
+function coverageGapEventId(injectId) {
+    return (0, event_id_1.deterministicEventId)(`coverage_gap:${injectId}`, 1);
+}
+// Deterministic event_id for the OUTCOME-time `candidates_found_not_used` gap the
+// correlator emits when a confident, non-empty inject closed as ignored. A
+// distinct business-key prefix from the inject-time gap so a single inject can
+// carry both an inject-time gap and (in principle) an outcome-time gap without an
+// event_id collision; in practice they are mutually exclusive (the correlator
+// only emits this when no inject-time gap exists).
+function coverageGapNotUsedEventId(injectId) {
+    return (0, event_id_1.deterministicEventId)(`coverage_gap_not_used:${injectId}`, 1);
+}
+// Build the typed, PII-bounded coverage-gap payload. ids/counts/enums/booleans
+// only (no raw query text or paths): the raw topic stays in Langfuse.
+function buildCoverageGapPayload(input) {
+    return {
+        inject_id: input.injectId,
+        coverage_gap_type: input.coverageGapType,
+        query_topic_category: input.queryTopicCategory,
+        retrieval_confidence: input.retrievalConfidence,
+        zero_results: input.zeroResults,
+    };
+}

package/dist/lib/analytics/envelope.js

@@ -0,0 +1,236 @@
+"use strict";
+// The analytics event envelope + closed enums + the typed event union.
+//
+// Spec section 6 (the event catalog) and section 10 (the implementation
+// contract). Every remotely emitted event carries the envelope (INV-JOIN-1);
+// every payload is ids/counts/rates/enums/booleans/durations only, never raw
+// text/paths/argv/queries/errors (INV-POSTHOG-PII-1). Events are FLAT: the
+// envelope fields and the payload fields sit at the same top level (matching
+// the local jsonl examples in section 7.4).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CE0_HOOKS = exports.OBLIGATION_OUTCOME_LABELS = exports.CONSULTATION_RESULTS = exports.CONSULTATION_EXECUTIONS = exports.MEMORY_REQUIREMENTS = exports.REVIEW_DECISIONS = exports.RELATION_EDGE_TYPES = exports.COMMAND_SCOPES = exports.RETRIEVAL_CONFIDENCES = exports.INJECT_OUTCOMES = exports.WINDOW_CLOSED_REASONS = exports.COVERAGE_GAP_TYPES = exports.QUERY_TOPIC_CATEGORIES = exports.GOVERNED_RELATION_TYPES = exports.TOUCHED_SURFACES = exports.COMMAND_OUTCOMES = exports.SOURCE_SURFACES = exports.EVENT_SOURCES = exports.EVENT_TYPES = exports.SCHEMA_VERSION = void 0;
+exports.makeEnvelope = makeEnvelope;
+exports.buildAttribution = buildAttribution;
+exports.envelopeMissingKeys = envelopeMissingKeys;
+exports.assertEnvelopeComplete = assertEnvelopeComplete;
+exports.isRemotelyEmittable = isRemotelyEmittable;
+// INV-SCHEMA-1: every payload carries schema_version and is forward-compatible.
+exports.SCHEMA_VERSION = 1;
+// --- closed enums (section 6.3) ---------------------------------------------
+// As const tuples so membership can be validated at the privacy boundary; no
+// open string ever reaches PostHog.
+exports.EVENT_TYPES = [
+    "mla_command",
+    "mla_evidence_inject",
+    "mla_evidence_outcome",
+    "mla_coverage_gap",
+    "mla_contradiction",
+    "mla_review_decision",
+    "mla_stats_viewed",
+    // CE0 evidence-consultation telemetry (§6.4). Named per the ratified proposal
+    // contract (no `mla_` prefix): these four are the PostHog projection of the
+    // obligation lifecycle and the dashboards in §6.4 query them by these names.
+    "memory_requirement_assessed",
+    "evidence_consultation_completed",
+    "evidence_obligation_finalized",
+    "evidence_hook_health",
+];
+exports.EVENT_SOURCES = ["cli", "hook", "mcp", "control", "intel"];
+// The emission-surface label carried in the attribution block (spec section 3.7
+// / T1.10). Derived from the typed `source` enum, NOT a free string, so the two
+// axes can never drift: `source` is the closed emission channel (cli|hook|mcp),
+// `sourceSurface` is its human-facing uppercase form. Kept distinct from the
+// product-origin axis (`source:"mla"`), which is a constant on every event.
+exports.SOURCE_SURFACES = {
+    cli: "CLI",
+    hook: "HOOK",
+    mcp: "MCP",
+    control: "CONTROL",
+    intel: "INTEL",
+};
+exports.COMMAND_OUTCOMES = [
+    "success",
+    "user_error",
+    "system_error",
+    "auth_error",
+    "network_error",
+    "permission_denied",
+    "validation_error",
+    "noop",
+    "cancelled",
+    "timeout",
+];
+exports.TOUCHED_SURFACES = [
+    "code",
+    "tests",
+    "docs",
+    "config",
+    "migration",
+    "infra",
+    "unknown",
+];
+exports.GOVERNED_RELATION_TYPES = [
+    "architecture",
+    "api_contract",
+    "migration",
+    "security",
+    "product_decision",
+    "data_model",
+    "unknown",
+];
+exports.QUERY_TOPIC_CATEGORIES = [
+    "architecture",
+    "testing",
+    "deployment",
+    "product_decision",
+    "customer_context",
+    "security",
+    "data_model",
+    "api_contract",
+    "migration",
+    "process",
+    "unknown",
+];
+exports.COVERAGE_GAP_TYPES = [
+    "no_candidate_found",
+    "low_confidence_candidates",
+    "candidates_found_not_used",
+    "stale_or_conflicting_candidates",
+    "retrieval_error",
+    "permission_filtered",
+];
+exports.WINDOW_CLOSED_REASONS = ["turn_limit", "time_limit", "still_open"];
+exports.INJECT_OUTCOMES = ["used", "ignored", "unknown", "pending"];
+exports.RETRIEVAL_CONFIDENCES = ["high", "medium", "low"];
+// Command scope: where the command's effect landed. local = no backend hop;
+// workspace = a single-workspace remote op; global = cross-workspace. Used by
+// mla_command and mla_stats_viewed.
+exports.COMMAND_SCOPES = ["local", "workspace", "global", "unknown"];
+// The relationship edge classes mla curates (kb review / contradiction). These
+// are the governed-relation lifecycle types, not the PII enums above.
+exports.RELATION_EDGE_TYPES = [
+    "CONTRADICTS",
+    "SUPERSEDES",
+    "STALE_RELIES_ON",
+    "REFINES",
+    "unknown",
+];
+exports.REVIEW_DECISIONS = ["accept", "reject", "reclassify", "no_relation"];
+// --- CE0 evidence-consultation telemetry enums (§6.4) -----------------------
+// The wire forms of the rules-layer CE0 enums. Re-declared here, in the analytics
+// layer, on purpose: the privacy boundary validates membership against THESE closed
+// tuples, and the analytics layer must not depend up into lib/rules. The string
+// values mirror the rules-layer unions (MemoryRequirement, ConsultationExecution,
+// ObligationOutcome); ce0-telemetry.ts is the seam that maps one onto the other.
+exports.MEMORY_REQUIREMENTS = ["REQUIRED", "NOT_REQUIRED", "UNKNOWN"];
+exports.CONSULTATION_EXECUTIONS = ["COMPLETE", "FAILED", "UNKNOWN"];
+exports.CONSULTATION_RESULTS = ["RESULTS_RETURNED", "NO_MATCH"];
+exports.OBLIGATION_OUTCOME_LABELS = [
+    "NOT_DUE",
+    "COMPLIANT_ON_TIME",
+    "CONSULTED_LATE_WITH_EVIDENCE",
+    "CONSULTED_LATE_NO_EVIDENCE",
+    "MISSED",
+    "UNKNOWN",
+    "CANCELLED",
+];
+exports.CE0_HOOKS = [
+    "USER_PROMPT_SUBMIT",
+    "CONSULTATION_CAPTURE",
+    "STOP",
+    "OFFLINE_LABEL_IMPORT",
+];
+function makeEnvelope(input) {
+    const source = input.source ?? "cli";
+    return {
+        schema_version: exports.SCHEMA_VERSION,
+        event_id: input.event_id,
+        event_type: input.event_type,
+        created_at: input.created_at,
+        emitted_at: input.emitted_at ?? input.created_at,
+        workspace_id: input.workspace_id,
+        distinct_id: input.distinct_id,
+        session_id: input.session_id,
+        run_id: input.run_id,
+        trace_id: input.trace_id,
+        source,
+        attribution: buildAttribution({
+            source,
+            workspaceId: input.workspace_id,
+            actorWorkspaceUserId: input.actor_workspace_user_id ?? null,
+            agentSessionId: input.session_id,
+            repoFingerprint: input.repo_fingerprint ?? null,
+        }),
+    };
+}
+// Assemble the attribution block (T1.10). Pure: every field is mapped from a
+// caller-supplied id/constant, no I/O. sourceSurface is derived from the closed
+// `source` enum so it can never carry an open string; the `?? "CLI"` is a
+// defensive default for the (type-impossible) case of an unmapped source.
+function buildAttribution(input) {
+    return {
+        source: "mla",
+        sourceProduct: "MLA",
+        sourceSurface: exports.SOURCE_SURFACES[input.source] ?? "CLI",
+        actorWorkspaceUserId: input.actorWorkspaceUserId,
+        workspaceId: input.workspaceId,
+        agentSessionId: input.agentSessionId,
+        repoFingerprint: input.repoFingerprint,
+    };
+}
+// --- validators (INV-JOIN-1, the test contract) -----------------------------
+// The eight join fields the test contract requires on every event. workspace_id
+// and session_id are allowed to be null here (an unbound local run); presence of
+// the KEY is asserted, while remote-emittability (non-null workspace+session) is
+// a separate, stricter check (isRemotelyEmittable).
+const REQUIRED_ENVELOPE_KEYS = [
+    "schema_version",
+    "event_id",
+    "event_type",
+    "created_at",
+    "workspace_id",
+    "session_id",
+    "run_id",
+    "trace_id",
+];
+function envelopeMissingKeys(ev) {
+    const missing = [];
+    for (const k of REQUIRED_ENVELOPE_KEYS) {
+        if (!(k in ev)) {
+            missing.push(k);
+            continue;
+        }
+        const v = ev[k];
+        // null is allowed for workspace_id / session_id (unbound run); undefined
+        // never is. Every other required key must be a non-empty value.
+        if (v === undefined) {
+            missing.push(k);
+        }
+        else if (v === null && k !== "workspace_id" && k !== "session_id") {
+            missing.push(k);
+        }
+        else if (typeof v === "string" && v.length === 0) {
+            missing.push(k);
+        }
+    }
+    return missing;
+}
+// Throws if any required envelope field is missing. Used as the assertion in
+// the envelope test (INV-JOIN-1) and as a defensive gate before remote ship.
+function assertEnvelopeComplete(ev) {
+    const missing = envelopeMissingKeys(ev);
+    if (missing.length > 0) {
+        throw new Error(`analytics event missing required envelope field(s): ${missing.join(", ")}`);
+    }
+}
+// INV-JOIN-1 applies to REMOTELY emitted events: they need a real workspace and
+// session to join. An event with a null workspace_id or session_id is recorded
+// locally (the operator's own view) but never shipped. The forwarder filters on
+// this.
+function isRemotelyEmittable(ev) {
+    return (envelopeMissingKeys(ev).length === 0 &&
+        typeof ev.workspace_id === "string" &&
+        ev.workspace_id.length > 0 &&
+        typeof ev.session_id === "string" &&
+        ev.session_id.length > 0);
+}

package/dist/lib/analytics/event-id.js

@@ -0,0 +1,86 @@
+"use strict";
+// Event identity (spec section 10.2, INV-IDEMPOTENCY-1, INV-REMOTE-DEDUPE-1).
+//
+// Two minting strategies, picked by who is the system of record for the event:
+//
+//  - CLI-ORIGIN events (mla_command, mla_evidence_inject): the CLI is the only
+//    writer, the event is produced exactly once, and a re-ship must reuse the
+//    SAME id. So we mint a UUID once and persist it in the local jsonl; every
+//    later forward reads it back. We do NOT content-hash these: identical
+//    commands at the same second would collide, and any serialization change
+//    would silently drift the id.
+//
+//  - SERVER-RECOMPUTABLE events (mla_evidence_outcome, mla_review_decision):
+//    these are derived from a business key plus a monotonic version, and may be
+//    recomputed by more than one writer (the correlator, a backfill). A
+//    deterministic id makes that idempotent: sha256(businessKey + ":" + version).
+//
+// Control dedupes on the PAIR (workspace_id, event_id), so a deterministic id
+// scoped only by business key never collides across workspaces.
+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.mintEventId = mintEventId;
+exports.deterministicEventId = deterministicEventId;
+exports.outcomeEventId = outcomeEventId;
+exports.reviewDecisionEventId = reviewDecisionEventId;
+const crypto = __importStar(require("crypto"));
+// Mint a fresh, persisted-once id for a CLI-origin event. uuid (not a hash) so
+// two structurally identical events are still distinct, and so the id is stable
+// across re-serialization.
+function mintEventId() {
+    return crypto.randomUUID();
+}
+// Deterministic id for a server-recomputable event. businessKey is the stable
+// natural key (e.g. an inject_id or decision_id); version is a monotonically
+// increasing integer so a corrected recomputation produces a NEW id rather than
+// silently overwriting the prior landing. The ":" separator is unambiguous
+// because neither side contains it (ids are uuids/hex, version is an integer).
+function deterministicEventId(businessKey, version) {
+    if (!businessKey) {
+        throw new Error("deterministicEventId requires a non-empty businessKey");
+    }
+    if (!Number.isInteger(version) || version < 0) {
+        throw new Error(`deterministicEventId requires a non-negative integer version, got ${version}`);
+    }
+    return crypto.createHash("sha256").update(`${businessKey}:${version}`).digest("hex");
+}
+// Convenience wrappers naming the two server-recomputable event families, so
+// callers can't accidentally pass the wrong version field.
+function outcomeEventId(injectId, outcomeVersion) {
+    return deterministicEventId(injectId, outcomeVersion);
+}
+function reviewDecisionEventId(decisionId, decisionVersion) {
+    return deterministicEventId(decisionId, decisionVersion);
+}

package/dist/lib/analytics/evidence.js

@@ -0,0 +1,150 @@
+"use strict";
+// The evidence-grounding lifecycle: build an inject payload at surface time, and
+// derive its outcome once the correlation window closes. Both are pure functions
+// over data the caller supplies, so the Stop-hook correlator and its test run the
+// identical code with no I/O or clock baked in.
+//
+// The window is "next 3 turns OR 15 minutes, whichever first" (spec §0, §7.4).
+// The inject is written immediately and counted as outcome=pending; the local
+// correlator (v1: the Stop hook, INV-CORRELATOR-1) calls deriveOutcome to close
+// eligible windows and append mla_evidence_outcome. Server-side correlation may
+// validate or enrich, never be the only writer.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTCOME_VERSION = exports.WINDOW_MS = exports.WINDOW_TURNS = void 0;
+exports.buildInjectPayload = buildInjectPayload;
+exports.deriveOutcome = deriveOutcome;
+const envelope_1 = require("./envelope");
+const event_id_1 = require("./event-id");
+const followthrough_1 = require("./followthrough");
+// The turn window covers the inject turn and its next 3 turns; the wall-clock
+// window is 15 minutes. Whichever fills first closes the inject (§0).
+exports.WINDOW_TURNS = 3;
+exports.WINDOW_MS = 15 * 60 * 1000;
+// The current outcome schema generation. Bumped only when the outcome derivation
+// changes meaning, so a recomputed outcome gets a NEW deterministic event_id
+// rather than silently overwriting the prior landing (event-id.ts).
+exports.OUTCOME_VERSION = 1;
+// buildInjectPayload normalizes the hook's raw retrieval result into the typed,
+// PII-bounded inject payload. It mints the inject_id ONCE (CLI-origin identity,
+// §10.2) and stamps the window deadline from the supplied clock so the function
+// stays hermetic.
+function buildInjectPayload(input) {
+    const confidence = envelope_1.RETRIEVAL_CONFIDENCES.includes(input.retrieval_confidence)
+        ? input.retrieval_confidence
+        : "low";
+    const offered = input.offered_source_ids.filter((s) => typeof s === "string" && s.length > 0);
+    const offeredCount = Number.isFinite(input.evidence_offered)
+        ? input.evidence_offered
+        : offered.length;
+    return {
+        inject_id: input.injectId ?? (0, event_id_1.mintEventId)(),
+        turn_index: input.turn_index,
+        evidence_offered: offeredCount,
+        offered_source_ids: offered,
+        evidence_tokens: Number.isFinite(input.evidence_tokens) ? input.evidence_tokens : 0,
+        retrieval_confidence: confidence,
+        retrieval_latency_ms: Number.isFinite(input.retrieval_latency_ms)
+            ? input.retrieval_latency_ms
+            : 0,
+        zero_results: offeredCount === 0,
+        window_deadline: new Date(input.createdAtMs + exports.WINDOW_MS).toISOString(),
+    };
+}
+// deriveOutcome closes one inject's window if it is eligible, else returns null
+// (the inject stays pending). Close precedence (§0, "whichever first"):
+//
+//   turn_limit  the full turn window has been observed (maxTurn >= turn+window).
+//               The agent had its whole opportunity; not-referenced => ignored.
+//   time_limit  the 15-minute deadline passed before the turn window filled.
+//               The session went idle, so a not-referenced inject is unknown,
+//               not ignored: we did not observe the full opportunity. This is
+//               what makes Unknown Coverage a meaningful honesty term.
+//   still_open  neither => null, stays pending.
+//
+// v1 used := referenced (§4.2): an inject that was pulled or cited is "used".
+// The schema keeps referenced and used as separate fields so a later correlator
+// can tighten "used" to material incorporation without a migration.
+function deriveOutcome(inject, calls, citations, ctx) {
+    // No numeric turn means we cannot align the inject to pulls/citations; it can
+    // never be correlated, so leave it pending rather than guess an outcome.
+    if (inject.turn_index === null)
+        return null;
+    const window = ctx.window ?? exports.WINDOW_TURNS;
+    const maxTurn = ctx.maxTurnBySession.get(inject.session_id) ?? inject.turn_index;
+    const deadlineMs = Date.parse(inject.window_deadline);
+    let reason;
+    if (maxTurn >= inject.turn_index + window) {
+        reason = "turn_limit";
+    }
+    else if (Number.isFinite(deadlineMs) && ctx.nowMs >= deadlineMs) {
+        reason = "time_limit";
+    }
+    else {
+        return null; // still open -> stays pending
+    }
+    // Reuse the ONE shared join (INV-ADOPTION-SOURCE-1): score this single inject
+    // turn against the window's pulls and citations.
+    const injectTurn = {
+        session_id: inject.session_id,
+        turn_index: inject.turn_index,
+        injected_source_ids: inject.offered_source_ids,
+    };
+    const [row] = (0, followthrough_1.computeFollowthrough)([injectTurn], calls, citations, window);
+    const pulled_within_window = row.a1a_pull;
+    const report_cited = row.a1b_push_reference;
+    const referenced = row.a1c_any;
+    // The offered ids that were referenced (pulled or cited), original form, deduped
+    // by the same normId rule the join uses.
+    const referencedByNorm = new Map();
+    for (const id of [...row.pulled_overlap, ...row.cited_overlap]) {
+        const n = (0, followthrough_1.normId)(id);
+        if (!referencedByNorm.has(n))
+            referencedByNorm.set(n, id);
+    }
+    const referenced_source_ids = Array.from(referencedByNorm.values());
+    let outcome;
+    if (referenced)
+        outcome = "used";
+    else if (reason === "turn_limit")
+        outcome = "ignored";
+    else
+        outcome = "unknown";
+    // offered_reference_rate: distinct offered ids referenced / distinct offered ids
+    // (the recall direction). null when nothing was offered.
+    const distinctOffered = new Set(inject.offered_source_ids.map(followthrough_1.normId));
+    const offered_reference_rate = distinctOffered.size
+        ? referenced_source_ids.length / distinctOffered.size
+        : null;
+    // citation_precision (v1 hallucinated-id guard): of the distinct ids the report
+    // cited in this window, the fraction that resolve to one of THIS inject's
+    // offered ids. null when the report cited nothing in the window (undefined, not
+    // zero). v1 caveat: an id pointing to a real-but-not-offered doc counts against
+    // precision, so this is a conservative proxy, in step with the §4.2 v1 framing.
+    const citedInWindow = [];
+    for (const c of citations) {
+        if (c.session_id !== inject.session_id)
+            continue;
+        if (c.turn_index < inject.turn_index || c.turn_index > inject.turn_index + window)
+            continue;
+        citedInWindow.push(...c.source_ids);
+    }
+    const distinctCited = new Set(citedInWindow.map(followthrough_1.normId));
+    const validOffered = new Set(row.cited_overlap.map(followthrough_1.normId));
+    const citation_precision = distinctCited.size ? validOffered.size / distinctCited.size : null;
+    const payload = {
+        inject_id: inject.inject_id,
+        outcome_version: exports.OUTCOME_VERSION,
+        outcome,
+        pulled_within_window,
+        report_cited,
+        referenced,
+        referenced_source_ids,
+        citation_precision,
+        offered_reference_rate,
+        window_closed_reason: reason,
+    };
+    return {
+        event_id: (0, event_id_1.outcomeEventId)(inject.inject_id, exports.OUTCOME_VERSION),
+        payload,
+    };
+}